Wizard mode for guided command construction

[toiroakr]

Summary

Add a --wizard built-in flag that launches an interactive, step-by-step guided mode for constructing and executing commands. This mode walks users through all available options, arguments, and subcommands using interactive prompts.

Motivation

Complex CLI tools with many subcommands and options can be overwhelming for new users. Wizard mode provides a guided experience that:

• Improves discoverability: Users can explore all available options without reading help text
• Reduces errors: Each value is validated as it's entered
• Lowers the learning curve: New users can build commands interactively before memorizing flags

This is inspired by @effect/cli's --wizard flag, which is a distinctive feature among CLI frameworks.

Relationship with Interactive Prompts (#147)

Wizard mode is built on top of the interactive prompt infrastructure from #147. The key difference:

Aspect	Interactive Prompts (#147)	Wizard Mode (this issue)
Scope	Individual missing options	Entire command
Trigger	Automatic (when value missing)	Explicit (--wizard flag)
Purpose	Fill in gaps	Full guided construction
Options covered	Only those with prompt: true	All options and arguments
Coexistence	Works alongside normal CLI usage	Separate mode

In practice, wizard mode iterates over all command fields and uses the same prompt primitives (text, confirm, select, etc.) to collect values, regardless of whether individual fields have prompt metadata configured.

Proposed Behavior

$ mycli --wizard

? Which command would you like to run? › (Use arrow keys)
❯ greet - Greet someone
  build - Build the project  
  deploy - Deploy to production

? What is your name? (--name) › Alice
? Enable verbose output? (--verbose) › No
? Output format? (--format) › json

Running: mycli greet --name Alice --format json

Flow

1. If the command has subcommands, present a selection prompt
2. For each argument/option in the selected command:
   • Show a prompt appropriate to the field type (inferred from Zod schema)
   • Pre-fill with default values where available
   • Validate input immediately using the Zod schema
3. Display the constructed command for confirmation
4. Execute the command

Schema-Driven Prompt Generation

Since politty already extracts rich metadata from Zod schemas (via schema-extractor.ts), wizard mode can automatically generate appropriate prompts:

Zod Schema	Wizard Prompt
z.string()	Text input
z.number()	Numeric input
z.boolean()	Confirm (y/N)
z.enum([...])	Select list
z.string().optional()	Text input (skippable)
z.string().default("x")	Text input (pre-filled with "x")
z.discriminatedUnion(...)	Select discriminator, then show variant fields

Implementation Notes

• Depends on Interactive prompts for missing options #147: Reuse the prompt primitives and auto-detection logic from the interactive prompts feature
• Built-in flag: --wizard should be a reserved built-in option (similar to --help and --version)
• Non-TTY handling: Skip wizard mode and show an error when stdin is not a TTY
• Separate module: Like prompts, wizard mode should be opt-in (politty/wizard or similar) to avoid bloating the core

Depends On

• Interactive prompts for missing options #147 (Interactive prompts for missing options)