Skip to content

feat(create): guided wizard with use-case and language filters#1278

Open
l2ysho wants to merge 2 commits into
masterfrom
1236-guided-apify-create-wizard-use-case-language-best-match-template
Open

feat(create): guided wizard with use-case and language filters#1278
l2ysho wants to merge 2 commits into
masterfrom
1236-guided-apify-create-wizard-use-case-language-best-match-template

Conversation

@l2ysho

@l2ysho l2ysho commented Jul 16, 2026

Copy link
Copy Markdown
Contributor

Closes #1236.

Reshapes apify create into the guided wizard from the epic: use case → language → best-match template, plus a new apify templates ls command. Local scaffold only (--source apify); the Git path stays a separate sub-issue.

What changed

  • New wizard flow in apify create: prompts for "What do you want to build?" (use case) and the language, then shows one scrollable, fit-ranked template list — exact matches first with the top one preselected, a non-selectable separator (── The templates below don't exactly match your selection ──), then the closest alternatives in tier order.
  • New flags -u/--use-case and -l/--language. -t/--template stays authoritative and bypasses the wizard entirely; -u/-l are ignored when -t is given (stated in the flag descriptions).
  • New command apify templates ls [--json] — human table by default; --json emits the full template objects including useCases[], so agents can discover the enum values without scraping --help.
  • Ported algorithm getTemplateRecommendation from apify-core, with the two CLI-specific changes agreed on the issue: a per-template isExactMatch flag (no aggregate boolean) and no result limit (tier order already sorts most→least fitting).

Flag → manifest-id mapping

--use-case manifest id --language manifest category
web-scraping WEB_SCRAPING javascript javascript
ai-agent AI typescript typescript
api-pipeline INTEGRATION python python
browser-automation AUTOMATION other (BYO Docker — see below)

"Skip (show all)" in the use-case prompt and "Any language" in the language prompt both mean no filter (the algorithm's exact match then reduces to the remaining dimension, or everything when both are skipped).

Notes for reviewers

  • -l other (BYO Docker) is kept as a valid flag value even though no manifest template matches it today (per the team decision on Guided apify create wizard: use-case → language → best-match template #1236). It's a flag-only escape hatch — not offered in the interactive prompt — and currently falls through to showing all templates with no exact match. Full BYO-Docker scaffolding is out of scope here.
  • Console handoff: since Console works in raw ids (e.g. ?useCase=WEB_SCRAPING), the Console "Use locally" emit will need its own id→kebab mapping when it builds the apify create line.
  • Stale research callout: the research note claimed "Browser automation + JavaScript" was the only zero-exact-match combo. The manifest has since added js-cypress (JavaScript + AUTOMATION), so that pair now has an exact match. The zero-exact "no exact match — showing the closest alternatives" hint path is still covered by a synthetic-fixture unit test.
  • The old install-confirmation prompt and per-template "Go back" affordance were dropped as part of the wizard redesign; dependency install remains governed by --skip-dependency-install.

Test plan

  • New unit tests: getTemplateRecommendation (tiers, dedup, any-language, skip-use-case, BYO-other, no-exact) and buildTemplateChoiceList (separator placement, language-suffix labels, hint text). 31 relevant tests green (incl. existing create tests).
  • pnpm run build, pnpm run lint, pnpm run format — clean. docs/reference.md regenerated via pnpm run update-docs.
  • Drove the wizard end-to-end in a real terminal: use-case → language → template prompts render correctly, top item preselected, and the selected template scaffolds.

🤖 Generated with Claude Code

Reshape `apify create` into a guided wizard: prompt for what the user
wants to build (use case) and the language, then present a single
fit-ranked template list (exact matches first, top preselected, a
non-selectable separator, then the closest alternatives).

- Add `-u/--use-case` and `-l/--language` filter flags; `-t/--template`
  stays authoritative and bypasses the wizard.
- Add `apify templates ls [--json]`, exposing each template's
  useCases[] so agents can discover the enum values.
- Port apify-core's getTemplateRecommendation tier algorithm, with a
  per-template isExactMatch flag (no aggregate) and no result limit;
  a skipped use case and "any language" both mean "no filter".

Refs #1236

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@github-actions github-actions Bot added this to the 145th sprint - Tooling team milestone Jul 16, 2026
@github-actions github-actions Bot added t-tooling Issues with this label are in the ownership of the tooling team. tested Temporary label used only programatically for some analytics. labels Jul 16, 2026
- Assert `--use-case` / `--language` are ignored when `--template` is
  provided: a TypeScript template scaffolds unchanged despite conflicting
  python/ai filters.
- Unit-test the flag→id mappings (useCaseFlagToId, USE_CASE/LANGUAGE
  flag choices, labels), including that STARTER is never exposed.

Refs #1236

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@l2ysho l2ysho added t-builders Issues owned by the Builders team. and removed t-tooling Issues with this label are in the ownership of the tooling team. labels Jul 16, 2026
@l2ysho l2ysho marked this pull request as ready for review July 16, 2026 10:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

t-builders Issues owned by the Builders team. tested Temporary label used only programatically for some analytics.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Guided apify create wizard: use-case → language → best-match template

2 participants