Skip to content

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

Merged
l2ysho merged 19 commits into
masterfrom
1236-guided-apify-create-wizard-use-case-language-best-match-template
Aug 3, 2026
Merged

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

Conversation

@l2ysho

@l2ysho l2ysho commented Jul 16, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Closes #1236.

TL;DR — apify create becomes a guided wizard: use case → language → best-match template, plus apify templates ls for discovery. Local scaffold only; the git-sourced flow is #1237 and --json/--origin is #1238.

What changed

  • Wizard — asks "What do you want to build?" then the language, then shows one scrollable, fit-ranked template list: exact matches first (top preselected), a separator, then the closest alternatives.
  • New flags -u/--use-case, -l/--language. -t/--template stays authoritative and skips the wizard; -u/-l are ignored when it's passed.
  • Language aliases js / ts / py. No other option — every template has a language.
  • New command apify templates ls [--json]; --json emits the full template objects, including useCases[].
  • Ported getTemplateRecommendation from apify-core, with two CLI changes: per-template isExactMatch and no result limit.

Flag → manifest mapping

--use-case manifest tag --language (+ alias) category
web-scraper WEB_SCRAPING javascript / js javascript
ai-agent AI typescript / ts typescript
data-pipeline INTEGRATION python / py python
browser-automation AUTOMATION

"Any use case" and "Any language" both mean no filter (ANY_TEMPLATE_USE_CASE / ANY_TEMPLATE_LANGUAGE — symmetric by design).

Tests

Unit tests for getTemplateRecommendation (tiers, dedup, any-language, no-exact), buildTemplateChoiceList (separator, labels, hint), and the flag→tag mappings; create covers --template precedence. build / lint / format clean, docs/ regenerated, wizard driven end-to-end in a terminal.

🤖 Generated with Claude Code

@l2ysho @claude
feat(create): guided wizard with use-case and language filters
4d0d4c4 
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
@l2ysho @claude
test(create): cover flag mappings and --template precedence
4732e9c 
- 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
@l2ysho l2ysho mentioned this pull request Jul 16, 2026
Open
szaganek
szaganek approved these changes Jul 21, 2026
View reviewed changes
Comment thread src/commands/create.ts Outdated
DaveHanns
DaveHanns reviewed Jul 28, 2026
View reviewed changes
Comment thread docs/reference.md Outdated
DaveHanns
DaveHanns reviewed Jul 28, 2026
View reviewed changes
Comment thread docs/reference.md Outdated
DaveHanns
DaveHanns reviewed Jul 28, 2026
View reviewed changes
Comment thread src/lib/templates/consts.ts
DaveHanns
DaveHanns reviewed Jul 28, 2026
View reviewed changes
Comment thread src/lib/templates/consts.ts Outdated
DaveHanns
DaveHanns reviewed Jul 28, 2026
View reviewed changes
Comment thread src/lib/templates/consts.ts Outdated
DaveHanns
DaveHanns reviewed Jul 28, 2026
View reviewed changes
Comment thread src/lib/templates/consts.ts
DaveHanns
DaveHanns reviewed Jul 28, 2026
View reviewed changes
Comment thread src/lib/templates/getTemplateRecommendation.ts Outdated
DaveHanns
DaveHanns reviewed Jul 28, 2026
View reviewed changes
Comment thread src/lib/templates/getTemplateRecommendation.ts Outdated
DaveHanns
DaveHanns reviewed Jul 28, 2026
View reviewed changes
Comment thread src/lib/templates/getTemplateRecommendation.ts Outdated
l2ysho and others added 7 commits July 28, 2026 21:57
@l2ysho @szaganek
Update src/commands/create.ts
93ec04a 
Co-authored-by: Edyta <142720610+szaganek@users.noreply.github.com>
@l2ysho @claude
refactor(create): rename use-case flags to web-scraper and data-pipeline
fe8f3e5 
Address PR review: `web-scraper` reads as an Actor identity (like
`ai-agent`), and `data-pipeline` matches Console's "API & data pipeline"
better than `api-pipeline`. Prompt labels are unchanged.

Refs #1236

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@l2ysho @claude
refactor(create): address review nits on template consts
935f49d 
- Document each TEMPLATE_USE_CASES tag (per-key JSDoc).
- Rename option fields to cliFlag / templateTag and derive UseCaseOption
  and LanguageOption from the `as const` option arrays.
- Correct the --use-case flag description ("by use case", not category).
- Simplify matchesUseCase to `!!...includes(...)`.

Refs #1236

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@l2ysho
Merge branch 'master' into 1236-guided-apify-create-wizard-use-case-l…
38a9f09 
…anguage-best-match-template
@l2ysho @claude
feat(create): language flag aliases; drop the "other" language
dd37fb1 
- Accept `js`/`ts`/`py` as aliases for `--language`, resolved to the
  manifest category via a new `languageFlagToTag`.
- Drop the `other` (BYO-Docker) language value: no template matches it,
  and language becomes inherent once templates turn into Actors.

Refs #1236

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@l2ysho @claude
refactor(create): symmetric use-case/language filter shapes
435dca5 
- Replace the `undefined` "skip use case" sentinel with an
  ANY_TEMPLATE_USE_CASE marker, mirroring ANY_TEMPLATE_LANGUAGE.
- Give LanguageOption a `cliFlag` alongside `templateTag` so it mirrors
  UseCaseOption's shape.

Refs #1236

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@l2ysho @DaveHanns
Update src/lib/templates/getTemplateRecommendation.ts
2f0bb24 
Co-authored-by: David Hanuš <david.hanus@apify.com>
@l2ysho @claude
fix(create): correct no-filter tier guard (hasUseCaseFilter)
098d658 
The committed #14 suggestion used `matchesUseCase` (a function) in the
guard condition — TS2774 build failure. Use the `hasUseCaseFilter`
boolean so the exact-match tier is skipped only when no filter is
active, letting the show-all path lead with curated templates.

Refs #1236

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@l2ysho
l2ysho requested a review from DaveHanns July 28, 2026 21:20
DaveHanns
DaveHanns reviewed Jul 29, 2026
View reviewed changes
Comment thread src/commands/create.ts
DaveHanns
DaveHanns reviewed Jul 29, 2026
View reviewed changes
Comment thread src/lib/create-utils.ts Outdated
DaveHanns
DaveHanns requested changes Jul 29, 2026
View reviewed changes

@DaveHanns DaveHanns left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Few comments, otherwise LGTM.

The main things are the drop of other option of --language flag and unification of "skip / no preference / any" language and use case.

l2ysho and others added 3 commits July 29, 2026 15:23
@l2ysho @claude
docs(create): reflect guided wizard in note/examples; "Any use case" …
db72423 
…copy

Update `interactiveNote` and `examples` to describe the use-case/language
wizard and the -u/-l filter flags, and unify the use-case prompt's "skip"
copy with the language prompt ("Any use case" ↔ "Any language").

Addresses PR #1278 review comments r3672018996, r3672030798, r3672045202.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@l2ysho @claude
docs(create): fix stale "Skip (show all)" reference in doc comment
22ad9c0 
The use-case prompt label changed to "Any use case"; update the
getTemplateRecommendation doc comment to match.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@l2ysho
Merge branch 'master' into 1236-guided-apify-create-wizard-use-case-l…
391f035 
…anguage-best-match-template
@l2ysho
l2ysho requested review from DaveHanns and szaganek July 29, 2026 13:36
DaveHanns
DaveHanns reviewed Aug 2, 2026
View reviewed changes
Comment thread src/lib/templates/consts.ts Outdated
* the fallback tiers.
*/
export const USE_CASE_OPTIONS = [
{ cliFlag: 'web-scraper', templateTag: TEMPLATE_USE_CASES.WEB_SCRAPING, label: 'Web scraping' },

@DaveHanns DaveHanns Aug 2, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion: lets go with Web scraper label to match the Console.

DaveHanns
DaveHanns approved these changes Aug 2, 2026
View reviewed changes

@DaveHanns DaveHanns left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One additional suggestion. Otherwise looks great 🚀

DaveHanns
DaveHanns reviewed Aug 3, 2026
View reviewed changes
Comment thread src/lib/templates/consts.ts Outdated
export const USE_CASE_FLAG_CHOICES: string[] = USE_CASE_OPTIONS.map((option) => option.cliFlag);

/** Maps a `--use-case` flag value to its manifest tag, or `undefined` when unknown. */
export function useCaseFlagToId(flag: string): string | undefined {

@DaveHanns DaveHanns Aug 3, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
export function useCaseFlagToId(flag: string): string | undefined {
export function useCaseFlagToTag(flag: string): string | undefined {

@l2ysho @claude
refactor(create): rename useCaseFlagToId to useCaseFlagToTag
3a64f5c 
The function returns a manifest `useCases[]` tag, not an id, and its
language counterpart is already named `languageFlagToTag`.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@l2ysho
l2ysho merged commit 84647b9 into master Aug 3, 2026
24 checks passed
@l2ysho
l2ysho deleted the 1236-guided-apify-create-wizard-use-case-language-best-match-template branch August 3, 2026 09:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@DaveHanns DaveHanns DaveHanns approved these changes
@szaganek szaganek Awaiting requested review from szaganek szaganek is a code owner

Assignees

@l2ysho l2ysho

Labels

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

Projects

None yet

Milestone

145th sprint - Tooling team

Development

Successfully merging this pull request may close these issues.

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

4 participants

@l2ysho @szaganek @DaveHanns @apify-service-account