padrone 1.4.0 → 1.6.0

package/src/{help.ts → output/help.ts}

@@ -1,6 +1,9 @@
 import type { StandardJSONSchemaV1 } from '@standard-schema/spec';
-import { extractSchemaMetadata, type PadroneArgsSchemaMeta, parsePositionalConfig, parseStdinConfig } from './args.ts';
-import { findCommandByName } from './command-utils.ts';
+import { extractSchemaMetadata, getJsonSchema, type PadroneArgsSchemaMeta, parsePositionalConfig } from '../core/args.ts';
+import { findCommandByName } from '../core/commands.ts';
+import type { AnyPadroneCommand } from '../types/index.ts';
+import { getRootCommand } from '../util/utils.ts';
+import type { ColorConfig, ColorTheme } from './colorizer.ts';
 import {
   createFormatter,
   type HelpArgumentInfo,
@@ -10,12 +13,19 @@ import {
   type HelpPositionalInfo,
   type HelpSubcommandInfo,
 } from './formatter.ts';
-import type { AnyPadroneCommand } from './types.ts';
-import { getRootCommand } from './utils.ts';
 
 export type HelpPreferences = {
   format?: HelpFormat | 'auto';
   detail?: HelpDetail;
+  theme?: ColorTheme | ColorConfig;
+  /** Show all global commands and flags in full detail */
+  all?: boolean;
+  /** Terminal width for text wrapping. Defaults to terminal columns or 80. */
+  width?: number;
+  /** Terminal capabilities for auto-detection of ANSI and width. */
+  terminal?: { columns?: number; isTTY?: boolean };
+  /** Environment variables for auto-detection (e.g., NO_COLOR, CI). */
+  env?: Record<string, string | undefined>;
 };
 
 /**
@@ -35,7 +45,7 @@ function extractPositionalArgsInfo(
   const positionalConfig = parsePositionalConfig(meta.positional);
 
   try {
-    const jsonSchema = schema['~standard'].jsonSchema.input({ target: 'draft-2020-12' }) as Record<string, any>;
+    const jsonSchema = getJsonSchema(schema) as Record<string, any>;
 
     if (jsonSchema.type === 'object' && jsonSchema.properties) {
       const properties = jsonSchema.properties as Record<string, any>;
@@ -75,7 +85,7 @@ function extractArgsInfo(schema: StandardJSONSchemaV1, meta?: PadroneArgsSchemaM
   const argsMeta = meta?.fields;
 
   try {
-    const jsonSchema = schema['~standard'].jsonSchema.input({ target: 'draft-2020-12' }) as Record<string, any>;
+    const jsonSchema = getJsonSchema(schema) as Record<string, any>;
 
     // Handle object: z.object({ key: z.string(), ... })
     if (jsonSchema.type === 'object' && jsonSchema.properties) {
@@ -134,6 +144,7 @@ function extractArgsInfo(schema: StandardJSONSchemaV1, meta?: PadroneArgsSchemaM
           examples: optMeta?.examples ?? prop?.examples,
           variadic: propType === 'array',
           negatable: isNegatable,
+          group: optMeta?.group,
         });
       }
     }
@@ -154,7 +165,7 @@ function extractArgsInfo(schema: StandardJSONSchemaV1, meta?: PadroneArgsSchemaM
  * @param cmd - The command to build help info for
  * @param detail - The level of detail ('minimal', 'standard', or 'full')
  */
-export function getHelpInfo(cmd: AnyPadroneCommand, detail: HelpPreferences['detail'] = 'standard'): HelpInfo {
+export function getHelpInfo(cmd: AnyPadroneCommand, detail: HelpPreferences['detail'] = 'standard', all?: boolean): HelpInfo {
   const rootCmd = getRootCommand(cmd);
   // A command is a "default" command if its name is '' or it has '' as an alias
   const isDefaultCommand = cmd.parent && (!cmd.name || cmd.aliases?.includes(''));
@@ -176,6 +187,7 @@ export function getHelpInfo(cmd: AnyPadroneCommand, detail: HelpPreferences['det
     name: commandName,
     title: cmd.title,
     description: cmd.description,
+    examples: cmd.examples,
     aliases: displayAliases,
     deprecated: cmd.deprecated,
     hidden: cmd.hidden,
@@ -184,7 +196,7 @@ export function getHelpInfo(cmd: AnyPadroneCommand, detail: HelpPreferences['det
       hasSubcommands: !!(cmd.commands && cmd.commands.length > 0),
       hasPositionals,
       hasArguments: false, // updated below after extracting arguments
-      stdinField: cmd.meta?.stdin ? parseStdinConfig(cmd.meta.stdin).field : undefined,
+      stdinField: cmd.meta?.stdin,
     },
   };
 
@@ -222,6 +234,7 @@ export function getHelpInfo(cmd: AnyPadroneCommand, detail: HelpPreferences['det
               aliases: displayAliases?.length ? displayAliases : undefined,
               deprecated: c.deprecated,
               hidden: c.hidden,
+              group: c.group,
             },
             {
               name: displayName,
@@ -230,6 +243,7 @@ export function getHelpInfo(cmd: AnyPadroneCommand, detail: HelpPreferences['det
               deprecated: c.deprecated,
               hidden: c.hidden,
               hasSubcommands: true,
+              group: c.group,
             },
           ];
         }
@@ -243,6 +257,7 @@ export function getHelpInfo(cmd: AnyPadroneCommand, detail: HelpPreferences['det
             deprecated: c.deprecated,
             hidden: c.hidden,
             hasSubcommands,
+            group: c.group,
           },
         ];
       }),
@@ -285,40 +300,64 @@ export function getHelpInfo(cmd: AnyPadroneCommand, detail: HelpPreferences['det
     }
   }
 
-  // Add built-in commands/flags for root command only
-  if (!cmd.parent) {
+  // Add global commands/flags (root command by default, all commands when --all is passed)
+  if (!cmd.parent || all) {
     const builtins: HelpInfo['builtins'] = [];
 
-    if (!findCommandByName('help', cmd.commands)) {
+    if (!findCommandByName('help', rootCmd.commands)) {
       builtins.push({
         name: 'help [command], -h, --help',
         description: 'Show help for a command',
         sub: [
+          { name: '--all', description: 'Show all global commands and flags' },
           { name: '--detail <level>', description: 'Detail level (minimal, standard, full)' },
           { name: '--format <format>', description: 'Output format (text, ansi, json, markdown, html)' },
         ],
       });
     }
 
-    if (!findCommandByName('version', cmd.commands)) {
+    if (!findCommandByName('version', rootCmd.commands)) {
       builtins.push({
         name: 'version, -v, --version',
         description: 'Show version information',
       });
     }
 
-    if (!findCommandByName('completion', cmd.commands)) {
+    if (!findCommandByName('completion', rootCmd.commands)) {
       builtins.push({
         name: 'completion [shell]',
         description: 'Generate shell completions (bash, zsh, fish, powershell)',
       });
     }
 
+    if (!findCommandByName('man', rootCmd.commands)) {
+      builtins.push({
+        name: 'man',
+        description: 'Show or install man pages (--setup to install, --remove to uninstall) (experimental)',
+      });
+    }
+
     builtins.push({
       name: '[command] --repl',
       description: 'Start interactive REPL scoped to a command',
     });
 
+    if (!findCommandByName('mcp', rootCmd.commands)) {
+      builtins.push({
+        name: 'mcp [http|stdio]',
+        description: 'Start a Model Context Protocol server to expose commands as AI tools (experimental)',
+        sub: [
+          { name: '--port <port>', description: 'HTTP port (default: 3000)' },
+          { name: '--host <host>', description: 'HTTP host (default: 127.0.0.1)' },
+        ],
+      });
+    }
+
+    builtins.push({
+      name: '--color [theme], --no-color',
+      description: 'Set color theme (default, ocean, warm, monochrome) or disable colors',
+    });
+
     if (builtins.length > 0) {
       helpInfo.builtins = builtins;
     }
@@ -332,7 +371,15 @@ export function getHelpInfo(cmd: AnyPadroneCommand, detail: HelpPreferences['det
 // ============================================================================
 
 export function generateHelp(rootCommand: AnyPadroneCommand, commandObj: AnyPadroneCommand = rootCommand, prefs?: HelpPreferences): string {
-  const helpInfo = getHelpInfo(commandObj, prefs?.detail);
-  const formatter = createFormatter(prefs?.format ?? 'auto', prefs?.detail);
+  const helpInfo = getHelpInfo(commandObj, prefs?.detail, prefs?.all);
+  const formatter = createFormatter(
+    prefs?.format ?? 'auto',
+    prefs?.detail,
+    prefs?.theme,
+    prefs?.all,
+    prefs?.width,
+    prefs?.terminal,
+    prefs?.env,
+  );
   return formatter.format(helpInfo);
 }

package/src/{zod.d.ts → schema/zod.d.ts}

@@ -1,4 +1,4 @@
-import type { PadroneFieldMeta } from './args.ts';
+import type { PadroneFieldMeta } from '../core/args.ts';
 
 declare module 'zod/v4/core' {
   export interface GlobalMeta extends PadroneFieldMeta {}

package/src/schema/zod.ts

@@ -0,0 +1,50 @@
+import * as z from 'zod/v4';
+import type { PadroneSchema } from '../types/index.ts';
+import { asyncStream } from '../util/stream.ts';
+
+/**
+ * Creates a Zod schema for an async stream field, ready to use in `.arguments()`.
+ * Wraps `z.custom<AsyncIterable<T>>()` with the `asyncStream()` metadata automatically.
+ *
+ * @param itemSchema - Optional item schema for per-item validation.
+ *
+ * @example
+ * ```ts
+ * import { zodAsyncStream } from 'padrone/zod';
+ *
+ * // String lines
+ * z.object({ lines: zodAsyncStream() })
+ *
+ * // Typed items — each line JSON.parse'd and validated
+ * const recordSchema = z.object({ name: z.string(), age: z.number() });
+ * z.object({ records: zodAsyncStream(jsonCodec(recordSchema)) })
+ * ```
+ */
+export function zodAsyncStream<T = string>(itemSchema?: PadroneSchema<unknown, T>) {
+  return z.custom<AsyncIterable<T>>().meta(asyncStream(itemSchema));
+}
+
+/**
+ * JSON codec for Zod schemas
+ * @see https://zod.dev/codecs?id=jsonschema
+ * Unlike the example in the docs, this codec also handles the case where the input is already an object
+ */
+export const jsonCodec = <T extends z.ZodType>(schema: T) =>
+  z.codec(z.union([z.string(), z.unknown()]), schema, {
+    decode: (jsonString, ctx) => {
+      try {
+        // HACK: in some cases the object is already deserialized, we just need to validate it
+        if (typeof jsonString !== 'string') return jsonString as z.input<T>;
+        return JSON.parse(jsonString) as z.input<T>;
+      } catch (err: any) {
+        ctx.issues.push({
+          code: 'invalid_format',
+          format: 'json',
+          input: typeof jsonString === 'string' ? jsonString : JSON.stringify(jsonString),
+          message: err.message,
+        });
+        return z.NEVER;
+      }
+    },
+    encode: (value) => JSON.stringify(value),
+  });

package/src/test.ts

@@ -1,285 +1,2 @@
-import type { InteractivePromptConfig, PadroneRuntime } from './runtime.ts';
-import type { AnyPadroneCommand, PadroneCommandResult } from './types.ts';
-
-/**
- * Result from a single command execution in test mode.
- * Extends the standard PadroneCommandResult with captured I/O.
- */
-export type TestCliResult = {
-  /** The matched command. */
-  command: AnyPadroneCommand;
-  /** Validated arguments (undefined if validation failed). */
-  args: unknown;
-  /** Action handler return value (undefined if validation failed or no action). */
-  result: unknown;
-  /** Validation issues, if any. */
-  issues: { message: string; path?: PropertyKey[] }[] | undefined;
-  /** All values passed to `runtime.output()`. */
-  stdout: unknown[];
-  /** All strings passed to `runtime.error()`. */
-  stderr: string[];
-  /** The thrown error, if the command threw (routing error, action error, etc.). */
-  error?: unknown;
-};
-
-/**
- * Result from a REPL test session.
- */
-export type TestReplResult = {
-  /** One entry per successfully executed command (validation errors are captured in stderr, not here). */
-  results: Omit<TestCliResult, 'stdout' | 'stderr'>[];
-  /** All output from the entire REPL session. */
-  stdout: unknown[];
-  /** All errors from the entire REPL session. */
-  stderr: string[];
-};
-
-/**
- * Fluent builder for setting up CLI test scenarios.
- */
-export type TestCliBuilder = {
-  /** Set the CLI input string (e.g. `'deploy --env production'`). */
-  args(input: string): TestCliBuilder;
-  /** Set environment variables visible to the command. */
-  env(vars: Record<string, string | undefined>): TestCliBuilder;
-  /** Provide mock answers for interactive prompts. Keys are field names. */
-  prompt(answers: Record<string, unknown>): TestCliBuilder;
-  /** Provide mock config files. Keys are file paths, values are parsed config objects. */
-  config(files: Record<string, Record<string, unknown>>): TestCliBuilder;
-  /** Provide mock stdin data (simulates piped input). */
-  stdin(data: string): TestCliBuilder;
-  /**
-   * Execute a single command via `eval()` and return the result with captured I/O.
-   * @param input - Optional CLI input string. Overrides `.args()` if provided.
-   */
-  run(input?: string): Promise<TestCliResult>;
-  /**
-   * Run a REPL session with the given sequence of inputs.
-   * Each string in the array is fed as one line of input.
-   * The session ends after all inputs are consumed (EOF).
-   */
-  repl(inputs: string[]): Promise<TestReplResult>;
-};
-
-/**
- * Creates a fluent test builder for a Padrone program.
- * Captures all I/O and provides a clean interface for assertions.
- *
- * Works with any test framework (bun:test, vitest, jest, node:test, etc.).
- *
- * @example
- * ```ts
- * import { testCli } from 'padrone/test'
- *
- * const result = await testCli(myProgram)
- *   .args('deploy --env production')
- *   .env({ API_KEY: 'xxx' })
- *   .run()
- *
- * expect(result.result).toBe('Deployed')
- * expect(result.stdout).toContain('Deploying...')
- * ```
- *
- * @example
- * ```ts
- * // Shorthand: pass input directly to run()
- * const result = await testCli(myProgram).run('deploy --env production')
- * ```
- *
- * @example
- * ```ts
- * // Test interactive prompts
- * const result = await testCli(myProgram)
- *   .args('init')
- *   .prompt({ name: 'myapp', template: 'react' })
- *   .run()
- *
- * expect(result.args).toEqual({ name: 'myapp', template: 'react' })
- * ```
- *
- * @example
- * ```ts
- * // Test REPL sessions
- * const { results } = await testCli(myProgram)
- *   .repl(['greet World', 'add --a=2 --b=3'])
- *
- * expect(results[0].result).toBe('Hello, World!')
- * expect(results[1].result).toBe(5)
- * ```
- */
-/**
- * Any program-like object that has `eval`, `runtime`, and `repl` methods.
- * Avoids strict variance issues with `AnyPadroneProgram`.
- */
-type TestableProgram = {
-  eval: (input: string, prefs?: { autoOutput?: boolean }) => any;
-  runtime: (runtime: PadroneRuntime) => TestableProgram;
-  repl: (options?: { greeting?: false; hint?: false }) => AsyncIterable<any>;
-};
-
-export function testCli(program: TestableProgram): TestCliBuilder {
-  let input: string | undefined;
-  let envVars: Record<string, string | undefined> | undefined;
-  let promptAnswers: Record<string, unknown> | undefined;
-  let configFiles: Record<string, Record<string, unknown>> | undefined;
-  let stdinData: string | undefined;
-
-  const builder: TestCliBuilder = {
-    args(args: string) {
-      input = args;
-      return builder;
-    },
-    env(vars) {
-      envVars = vars;
-      return builder;
-    },
-    prompt(answers) {
-      promptAnswers = answers;
-      return builder;
-    },
-    config(files) {
-      configFiles = files;
-      return builder;
-    },
-    stdin(data: string) {
-      stdinData = data;
-      return builder;
-    },
-
-    async run(runInput?: string) {
-      const stdout: unknown[] = [];
-      const stderr: string[] = [];
-
-      const runtime = buildRuntime(stdout, stderr, { envVars, promptAnswers, configFiles, stdinData });
-      const testProgram = program.runtime(runtime);
-
-      try {
-        const evalResult = await testProgram.eval(runInput ?? input ?? '', { autoOutput: false });
-        return toTestResult(evalResult, stdout, stderr);
-      } catch (err) {
-        stderr.push(err instanceof Error ? err.message : String(err));
-        return {
-          command: undefined as unknown as AnyPadroneCommand,
-          args: undefined,
-          result: undefined,
-          issues: undefined,
-          stdout,
-          stderr,
-          error: err,
-        };
-      }
-    },
-
-    async repl(inputs: string[]) {
-      const stdout: unknown[] = [];
-      const stderr: string[] = [];
-
-      const runtime = buildRuntime(stdout, stderr, {
-        envVars,
-        promptAnswers,
-        configFiles,
-        readLine: createMockReadLine(inputs),
-      });
-
-      const testProgram = program.runtime(runtime);
-      const results: Omit<TestCliResult, 'stdout' | 'stderr'>[] = [];
-
-      for await (const r of testProgram.repl({ greeting: false, hint: false })) {
-        results.push({
-          command: r.command,
-          args: r.args,
-          result: r.result,
-          issues: r.argsResult?.issues as TestCliResult['issues'],
-        });
-      }
-
-      return { results, stdout, stderr };
-    },
-  };
-
-  return builder;
-}
-
-function toTestResult(evalResult: PadroneCommandResult, stdout: unknown[], stderr: string[]): TestCliResult {
-  return {
-    command: evalResult.command,
-    args: evalResult.args,
-    result: evalResult.result,
-    issues: evalResult.argsResult?.issues as TestCliResult['issues'],
-    stdout,
-    stderr,
-  };
-}
-
-function buildRuntime(
-  stdout: unknown[],
-  stderr: string[],
-  opts: {
-    envVars?: Record<string, string | undefined>;
-    promptAnswers?: Record<string, unknown>;
-    configFiles?: Record<string, Record<string, unknown>>;
-    readLine?: (prompt: string) => Promise<string | null>;
-    stdinData?: string;
-  },
-): PadroneRuntime {
-  const runtime: PadroneRuntime = {
-    output: (...args: unknown[]) => stdout.push(...args),
-    error: (text: string) => stderr.push(text),
-  };
-
-  if (opts.envVars) {
-    runtime.env = () => opts.envVars!;
-  }
-
-  if (opts.promptAnswers) {
-    runtime.interactive = 'supported';
-    runtime.prompt = async (config: InteractivePromptConfig) => opts.promptAnswers![config.name];
-  }
-
-  if (opts.configFiles) {
-    runtime.loadConfigFile = (path: string) => opts.configFiles![path];
-    runtime.findFile = (names: string[]) => names.find((n) => n in opts.configFiles!);
-  }
-
-  if (opts.readLine) {
-    runtime.readLine = opts.readLine;
-  }
-
-  if (opts.stdinData !== undefined) {
-    runtime.stdin = {
-      isTTY: false,
-      async text() {
-        return opts.stdinData!;
-      },
-      async *lines() {
-        const lines = opts.stdinData!.split('\n');
-        // Remove trailing empty line from final newline (matches readline behavior)
-        if (lines.length > 0 && lines[lines.length - 1] === '') lines.pop();
-        for (const line of lines) {
-          yield line;
-        }
-      },
-    };
-  } else {
-    // No stdin data: simulate a TTY (no piped input) to avoid reading from process.stdin
-    runtime.stdin = {
-      isTTY: true,
-      async text() {
-        return '';
-      },
-      async *lines() {
-        // no lines
-      },
-    };
-  }
-
-  return runtime;
-}
-
-function createMockReadLine(inputs: string[]): (prompt: string) => Promise<string | null> {
-  let index = 0;
-  return async (_prompt: string): Promise<string | null> => {
-    if (index >= inputs.length) return null;
-    return inputs[index++] ?? null;
-  };
-}
+export type { TestCliBuilder, TestCliResult, TestReplResult } from './feature/test.ts';
+export { testCli } from './feature/test.ts';

package/src/types/args-meta.ts

@@ -0,0 +1,151 @@
+type Letter =
+  | 'a'
+  | 'b'
+  | 'c'
+  | 'd'
+  | 'e'
+  | 'f'
+  | 'g'
+  | 'h'
+  | 'i'
+  | 'j'
+  | 'k'
+  | 'l'
+  | 'm'
+  | 'n'
+  | 'o'
+  | 'p'
+  | 'q'
+  | 'r'
+  | 's'
+  | 't'
+  | 'u'
+  | 'v'
+  | 'w'
+  | 'x'
+  | 'y'
+  | 'z';
+
+/** A single letter character, valid as a short CLI flag (e.g. `'v'`, `'n'`, `'V'`). */
+export type SingleChar = Letter | Uppercase<Letter>;
+
+export interface PadroneFieldMeta {
+  description?: string;
+  /** Single-character short flags (stackable: `-abc` = `-a -b -c`). Used with single dash. */
+  flags?: readonly SingleChar[] | SingleChar;
+  /** Multi-character alternative long names. Used with double dash (e.g. `--dry-run` for `--dryRun`). */
+  alias?: readonly string[] | string;
+  deprecated?: boolean | string;
+  hidden?: boolean;
+  examples?: readonly unknown[];
+  /** Group name for organizing this option under a labeled section in help output. */
+  group?: string;
+}
+
+type PositionalArgs<TObj> =
+  TObj extends Record<string, any>
+    ? {
+        [K in keyof TObj]: NonNullable<TObj[K]> extends Array<any> ? `...${K & string}` | (K & string) : K & string;
+      }[keyof TObj]
+    : string;
+
+/**
+ * Meta configuration for arguments, including positional arguments.
+ * The `positional` array defines which arguments are positional and their order.
+ * Use '...name' prefix to indicate variadic (rest) arguments, matching JS/TS rest syntax.
+ *
+ * @example
+ * ```ts
+ * .arguments(schema, {
+ *   positional: ['source', '...files', 'dest'],  // '...files' is variadic
+ * })
+ * ```
+ */
+/**
+ * Configuration for reading from stdin and mapping it to an argument field.
+ * Simply specify the field name — the read mode is inferred from the schema:
+ * - `string` field → reads all stdin as text
+ * - `string[]` field → reads stdin line-by-line
+ */
+export type StdinConfig<TObj = Record<string, any>> = keyof TObj & string;
+
+export interface PadroneArgsSchemaMeta<TObj = Record<string, any>> {
+  /**
+   * Array of argument names that should be treated as positional arguments.
+   * Order in array determines position. Use '...name' prefix for variadic args.
+   * @example ['source', '...files', 'dest'] - 'files' captures multiple values
+   */
+  positional?: readonly PositionalArgs<TObj>[];
+  /**
+   * Per-argument metadata.
+   */
+  fields?: { [K in keyof TObj]?: PadroneFieldMeta };
+  /**
+   * Automatically generate kebab-case aliases for camelCase option names.
+   * For example, `dryRun` automatically gets `--dry-run` as an alias.
+   * Defaults to `true`. Set to `false` to disable.
+   *
+   * @default true
+   * @example
+   * ```ts
+   * // Auto-aliases enabled (default): --dry-run → dryRun
+   * .arguments(z.object({ dryRun: z.boolean() }))
+   *
+   * // Disable auto-aliases
+   * .arguments(z.object({ dryRun: z.boolean() }), { autoAlias: false })
+   * ```
+   */
+  autoAlias?: boolean;
+  /**
+   * Read from stdin and inject the data into the specified argument field.
+   * Only reads when stdin is piped (not a TTY) and the field wasn't already provided via CLI flags.
+   *
+   * The read mode is inferred from the schema type of the target field:
+   * - `string` field → reads all stdin as a single string
+   * - `string[]` field → reads stdin line-by-line into an array
+   *
+   * Precedence: CLI flags > stdin > env vars > config file > schema defaults.
+   *
+   * @example
+   * ```ts
+   * // Read all stdin as text into 'data' field
+   * .arguments(z.object({ data: z.string() }), { stdin: 'data' })
+   *
+   * // Read stdin lines into 'lines' field (inferred from array schema)
+   * .arguments(z.object({ lines: z.string().array() }), { stdin: 'lines' })
+   * ```
+   */
+  stdin?: StdinConfig<TObj>;
+  /**
+   * Fields to interactively prompt for when their values are missing after CLI/env/config resolution.
+   * - `true`: prompt for all required fields that are missing.
+   * - `string[]`: prompt for these specific fields if missing.
+   *
+   * Interactive prompting only occurs in `cli()` when the runtime has `interactive: true`.
+   * Setting this makes `parse()` and `cli()` return Promises.
+   *
+   * @example
+   * ```ts
+   * .arguments(schema, {
+   *   interactive: true,                        // prompt all missing required fields
+   *   interactive: ['name', 'template'],         // prompt only these fields
+   * })
+   * ```
+   */
+  interactive?: true | readonly (keyof TObj & string)[];
+  /**
+   * Optional fields offered after required interactive prompts.
+   * Users are shown a multi-select to choose which of these fields to configure.
+   * - `true`: offer all optional fields that are missing.
+   * - `string[]`: offer these specific fields.
+   *
+   * @example
+   * ```ts
+   * .arguments(schema, {
+   *   interactive: ['name'],
+   *   optionalInteractive: ['typescript', 'eslint', 'prettier'],
+   * })
+   * ```
+   */
+  optionalInteractive?: true | readonly (keyof TObj & string)[];
+}