@alcyone-labs/arg-parser 2.13.5 → 2.14.0

package/dist/core/ArgParserBase.d.ts

@@ -2,7 +2,7 @@ import { type Logger } from "@alcyone-labs/simple-mcp-logger";
 import { McpNotificationsManager, type McpChangeType } from "../mcp/mcp-notifications.js";
 import { McpPromptsManager, type McpPromptConfig } from "../mcp/mcp-prompts.js";
 import { McpResourcesManager, type McpResourceConfig } from "../mcp/mcp-resources.js";
-import type { IArgParser, IFlag, IHandlerContext, ISubCommand, ParseResult, ProcessedFlag, TFlagInheritance, TParsedArgs } from "./types";
+import type { IArgParser, IFlag, IHandlerContext, IPromptableFlag, ISubCommand, ParseResult, ProcessedFlag, PromptWhen, TParsedArgs, TFlagInheritance } from "./types";
 export declare class ArgParserError extends Error {
     cmdChain: string[];
     commandChain: string[];
@@ -86,6 +86,33 @@ export interface IArgParserParams<THandlerReturn = any> {
      * If not provided, a default one will be created.
      */
     logger?: Logger;
+    /**
+     * When to trigger interactive prompts for this command.
+     * - `"interactive-flag"` (default): Prompts shown only when `--interactive` or `-i` flag is present
+     * - `"missing"`: Prompts shown when any promptable flag is missing a value
+     * - `"always"`: Always show prompts (overrides CLI args for promptable flags)
+     *
+     * @default "interactive-flag"
+     *
+     * @example
+     * ```typescript
+     * const cli = new ArgParser({
+     *   appName: "my-cli",
+     *   promptWhen: "interactive-flag",
+     *   handler: async (ctx) => {
+     *     if (ctx.isInteractive) {
+     *       console.log("Interactive mode:", ctx.promptAnswers);
+     *     }
+     *   }
+     * });
+     * ```
+     */
+    promptWhen?: import("./types").PromptWhen;
+    /**
+     * Called when user cancels (Ctrl+C) during interactive prompts.
+     * If not provided, exits gracefully with code 0.
+     */
+    onCancel?: (ctx: import("./types").IHandlerContext) => void | Promise<void>;
 }
 export interface IParseOptions {
     /**
@@ -158,9 +185,36 @@ export declare class ArgParserBase<THandlerReturn = any> implements IArgParser<T
     private _handleExit;
     getHandler(): ((ctx: IHandlerContext) => void) | undefined;
     getSubCommands(): Map<string, ISubCommand>;
+    /**
+     * Sets the promptWhen setting for this parser.
+     * Used internally to propagate promptWhen from parent to sub-parser.
+     * @param promptWhen - The promptWhen value
+     */
+    setPromptWhen(promptWhen: PromptWhen): this;
+    /**
+     * Sets the onCancel callback for this parser.
+     * Used internally to propagate onCancel from parent to sub-parser.
+     * @param onCancel - The onCancel callback
+     */
+    setOnCancel(onCancel: (ctx: IHandlerContext) => void | Promise<void>): this;
     private _addToOutput;
     addFlags(flags: readonly IFlag[]): this;
     addFlag(flag: IFlag): this;
+    /**
+     * Collects all flags that have interactive prompt configuration.
+     * These flags can participate in interactive mode.
+     *
+     * @returns Array of promptable flags with their names
+     */
+    getPromptableFlags(): Array<{
+        flag: IPromptableFlag;
+        name: string;
+    }>;
+    /**
+     * Gets the promptWhen setting for this parser.
+     * @returns The promptWhen value
+     */
+    getPromptWhen(): PromptWhen;
     addSubCommand(subCommandConfig: ISubCommand): this;
     /**
      * Sets the handler function for this specific parser instance.

package/dist/core/ArgParserBase.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ArgParserBase.d.ts","sourceRoot":"","sources":["../../src/core/ArgParserBase.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ArgParserBase.d.ts","sourceRoot":"","sources":["../../src/core/ArgParserBase.ts"],"names":[],"mappings":"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"}

package/dist/core/FlagManager.d.ts

@@ -1,17 +1,174 @@
 import type { IFlag, ProcessedFlag } from "./types";
+/**
+ * Options for FlagManager configuration.
+ */
+export interface FlagManagerOptions {
+    /** Whether to throw an error when a flag with a duplicate name is added. If false, a warning is logged and the duplicate is skipped. @default false */
+    throwForDuplicateFlags?: boolean;
+    /**
+     * Whether to detect and report collisions between flag option strings (e.g., two flags both using `-f` or `--file`).
+     * When enabled, adding a flag with an option string that conflicts with an existing flag will trigger a warning or error.
+     * @default true
+     */
+    detectOptionCollisions?: boolean;
+    /**
+     * Whether to throw an error when flag option collisions are detected.
+     * If false, a warning is logged but the flag is still added.
+     * Only applies when detectOptionCollisions is true.
+     * @default false
+     */
+    throwForOptionCollisions?: boolean;
+}
+/**
+ * Represents a collision between flag option strings.
+ */
+export interface FlagOptionCollision {
+    /** The option string that collides (e.g., "-f" or "--file") */
+    option: string;
+    /** The name of the flag that was already registered with this option */
+    existingFlagName: string;
+    /** The name of the flag being added that causes the collision */
+    newFlagName: string;
+}
+/**
+ * Manages flag definitions and detects collisions between flag names and option strings.
+ *
+ * @example
+ * ```typescript
+ * const manager = new FlagManager({
+ *   throwForDuplicateFlags: true,
+ *   detectOptionCollisions: true,
+ *   throwForOptionCollisions: true
+ * });
+ *
+ * manager.addFlag({
+ *   name: "file",
+ *   options: ["-f", "--file"],
+ *   type: "string"
+ * });
+ *
+ * // This will throw because "-f" is already used:
+ * manager.addFlag({
+ *   name: "force",
+ *   options: ["-f", "--force"],
+ *   type: "boolean"
+ * });
+ * ```
+ */
 export declare class FlagManager {
     #private;
-    constructor(options?: {
-        throwForDuplicateFlags?: boolean;
-    }, initialFlags?: readonly IFlag[]);
+    /**
+     * Creates a new FlagManager instance.
+     *
+     * @param options - Configuration options for the manager
+     * @param initialFlags - Optional array of flags to add immediately
+     */
+    constructor(options?: FlagManagerOptions, initialFlags?: readonly IFlag[]);
+    /**
+     * Converts a raw IFlag to a ProcessedFlag with resolved types.
+     *
+     * @param flag - The flag definition to process
+     * @returns The processed flag with resolved types
+     * @internal
+     */
     static _safeFlag(flag: IFlag): ProcessedFlag;
+    /**
+     * Adds a flag to the manager.
+     *
+     * Detects name collisions (if throwForDuplicateFlags is true) and
+     * option string collisions (if detectOptionCollisions is true).
+     *
+     * @param flag - The flag definition to add
+     * @returns The FlagManager instance for chaining
+     * @throws {Error} If throwForDuplicateFlags is true and a flag with the same name exists
+     * @throws {Error} If throwForOptionCollisions is true and option collisions are detected
+     *
+     * @example
+     * ```typescript
+     * manager.addFlag({
+     *   name: "verbose",
+     *   options: ["-v", "--verbose"],
+     *   type: "boolean",
+     *   description: "Enable verbose output"
+     * });
+     * ```
+     */
     addFlag(flag: IFlag): this;
+    /**
+     * Sets a processed flag for inheritance from a parent parser.
+     * This bypasses collision detection since inherited flags are intentional.
+     *
+     * @param processedFlag - The processed flag to add
+     * @returns The FlagManager instance for chaining
+     * @internal
+     */
     _setProcessedFlagForInheritance(processedFlag: ProcessedFlag): this;
+    /**
+     * Adds multiple flags to the manager.
+     *
+     * @param flags - Array of flag definitions to add
+     * @returns The FlagManager instance for chaining
+     */
     addFlags(flags: readonly IFlag[]): this;
+    /**
+     * Checks if a flag with the given name exists.
+     *
+     * @param name - The flag name to check
+     * @returns True if the flag exists, false otherwise
+     */
     hasFlag(name: string): boolean;
+    /**
+     * Removes a flag by name.
+     *
+     * @param name - The name of the flag to remove
+     * @returns True if the flag was removed, false if it didn't exist
+     */
     removeFlag(name: string): boolean;
+    /**
+     * Gets a flag by name.
+     *
+     * @param name - The name of the flag to retrieve
+     * @returns The flag definition, or undefined if not found
+     */
     getFlag(name: string): ProcessedFlag | undefined;
+    /**
+     * Gets all registered flags.
+     *
+     * @returns An array of all registered flags
+     */
     get flags(): ProcessedFlag[];
+    /**
+     * Gets all registered flag names.
+     *
+     * @returns An array of all flag names
+     */
     get flagNames(): string[];
+    /**
+     * Gets all registered option strings and their associated flag names.
+     *
+     * @returns A map of option strings to flag names
+     */
+    get optionMappings(): ReadonlyMap<string, string>;
+    /**
+     * Gets all collisions between the given flag and existing flags.
+     * Useful for pre-validation before adding a flag.
+     *
+     * @param flag - The flag to check for collisions
+     * @returns An array of detected collisions, empty if none
+     *
+     * @example
+     * ```typescript
+     * const collisions = manager.getCollisionsForFlag({
+     *   name: "force",
+     *   options: ["-f", "--force"],
+     *   type: "boolean"
+     * });
+     *
+     * if (collisions.length > 0) {
+     *   console.log("Collisions detected:", collisions);
+     * }
+     * ```
+     */
+    getCollisionsForFlag(flag: IFlag): FlagOptionCollision[];
 }
 //# sourceMappingURL=FlagManager.d.ts.map

package/dist/core/FlagManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FlagManager.d.ts","sourceRoot":"","sources":["../../src/core/FlagManager.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAEpD,qBAAa,WAAW;;gBAKpB,OAAO,GAAE;QAAE,sBAAsB,CAAC,EAAE,OAAO,CAAA;KAAO,EAClD,YAAY,GAAE,SAAS,KAAK,EAAO;IAMrC,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,KAAK,GAAG,aAAa;IA0C5C,OAAO,CAAC,IAAI,EAAE,KAAK,GAAG,IAAI;IAkB1B,+BAA+B,CAAC,aAAa,EAAE,aAAa,GAAG,IAAI;IAQnE,QAAQ,CAAC,KAAK,EAAE,SAAS,KAAK,EAAE,GAAG,IAAI;IAOvC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI9B,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIjC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAIhD,IAAI,KAAK,IAAI,aAAa,EAAE,CAE3B;IAED,IAAI,SAAS,IAAI,MAAM,EAAE,CAExB;CACF"}
+{"version":3,"file":"FlagManager.d.ts","sourceRoot":"","sources":["../../src/core/FlagManager.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAEpD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,uJAAuJ;IACvJ,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC;;;;;OAKG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,gBAAgB,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,WAAW;;IAOtB;;;;;OAKG;gBACS,OAAO,GAAE,kBAAuB,EAAE,YAAY,GAAE,SAAS,KAAK,EAAO;IAOjF;;;;;;OAMG;IACH,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,KAAK,GAAG,aAAa;IAgF5C;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,IAAI,EAAE,KAAK,GAAG,IAAI;IAwC1B;;;;;;;OAOG;IACH,+BAA+B,CAAC,aAAa,EAAE,aAAa,GAAG,IAAI;IASnE;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,KAAK,EAAE,GAAG,IAAI;IAOvC;;;;;OAKG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI9B;;;;;OAKG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAYjC;;;;;OAKG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAIhD;;;;OAIG;IACH,IAAI,KAAK,IAAI,aAAa,EAAE,CAE3B;IAED;;;;OAIG;IACH,IAAI,SAAS,IAAI,MAAM,EAAE,CAExB;IAED;;;;OAIG;IACH,IAAI,cAAc,IAAI,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAEhD;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,oBAAoB,CAAC,IAAI,EAAE,KAAK,GAAG,mBAAmB,EAAE;CAIzD"}

package/dist/core/PromptManager.d.ts

@@ -0,0 +1,102 @@
+import type { IHandlerContext, IPromptableFlag, PromptWhen } from "./types";
+/**
+ * Options for creating a PromptManager instance.
+ */
+export interface PromptManagerOptions {
+    /** The current handler context, used for passing to prompt functions */
+    context: IHandlerContext;
+    /** Called when user cancels (Ctrl+C) during prompts */
+    onCancel?: (ctx: IHandlerContext) => void | Promise<void>;
+}
+/**
+ * Result of executing interactive prompts.
+ */
+export interface PromptResult {
+    /** Whether the prompts were completed successfully */
+    success: boolean;
+    /** The collected answers (flag name -> value) */
+    answers: Record<string, any>;
+    /** Whether the user cancelled */
+    cancelled: boolean;
+}
+/**
+ * Manages interactive prompts using @clack/prompts.
+ *
+ * This class handles:
+ * - Collecting promptable flags and sorting them by sequence
+ * - Executing prompts in order with @clack/prompts
+ * - Validation and re-prompt loops
+ * - User cancellation (Ctrl+C)
+ * - TTY detection
+ *
+ * @example
+ * ```typescript
+ * const promptManager = new PromptManager({
+ *   context: handlerContext,
+ *   onCancel: () => console.log("Cancelled")
+ * });
+ *
+ * const result = await promptManager.executePrompts([
+ *   { flag: envFlag, name: "environment" },
+ *   { flag: versionFlag, name: "version" }
+ * ]);
+ *
+ * if (result.success) {
+ *   console.log("Answers:", result.answers);
+ * }
+ * ```
+ */
+export declare class PromptManager {
+    #private;
+    /**
+     * Creates a new PromptManager instance.
+     *
+     * @param options - Configuration options
+     */
+    constructor(options: PromptManagerOptions);
+    /**
+     * Checks if the current environment supports interactive prompts.
+     * Returns false in non-TTY environments (CI, pipes, etc.).
+     */
+    static isInteractiveEnvironment(): boolean;
+    /**
+     * Determines if interactive mode should be triggered based on promptWhen condition.
+     *
+     * @param promptWhen - The condition to check
+     * @param flags - The promptable flags to check
+     * @param args - The current parsed args
+     * @returns True if interactive mode should be triggered
+     */
+    static shouldTriggerInteractive(promptWhen: PromptWhen, flags: Array<{
+        flag: IPromptableFlag;
+        name: string;
+    }>, args: Record<string, any>): boolean;
+    /**
+     * Sorts flags by their prompt sequence.
+     * Falls back to array order if promptSequence is not specified.
+     * Ties are broken by array order.
+     *
+     * @param flags - Array of flags to sort
+     * @returns Sorted array of flags
+     */
+    static sortFlagsBySequence(flags: Array<{
+        flag: IPromptableFlag;
+        name: string;
+        index: number;
+    }>): Array<{
+        flag: IPromptableFlag;
+        name: string;
+        index: number;
+    }>;
+    /**
+     * Executes all prompts in sequence.
+     *
+     * @param flags - Array of promptable flags with their names
+     * @returns The result of the prompt execution
+     */
+    executePrompts(flags: Array<{
+        flag: IPromptableFlag;
+        name: string;
+    }>): Promise<PromptResult>;
+}
+//# sourceMappingURL=PromptManager.d.ts.map

package/dist/core/PromptManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PromptManager.d.ts","sourceRoot":"","sources":["../../src/core/PromptManager.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAqB,UAAU,EAAE,MAAM,SAAS,CAAC;AAE/F;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,wEAAwE;IACxE,OAAO,EAAE,eAAe,CAAC;IACzB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3D;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,sDAAsD;IACtD,OAAO,EAAE,OAAO,CAAC;IACjB,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC7B,iCAAiC;IACjC,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,aAAa;;IAIxB;;;;OAIG;gBACS,OAAO,EAAE,oBAAoB;IAKzC;;;OAGG;IACH,MAAM,CAAC,wBAAwB,IAAI,OAAO;IAQ1C;;;;;;;OAOG;IACH,MAAM,CAAC,wBAAwB,CAC7B,UAAU,EAAE,UAAU,EACtB,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,eAAe,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,EACrD,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GACxB,OAAO;IAsBV;;;;;;;OAOG;IACH,MAAM,CAAC,mBAAmB,CACxB,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,eAAe,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,GACnE,KAAK,CAAC;QAAE,IAAI,EAAE,eAAe,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAchE;;;;;OAKG;IACG,cAAc,CAClB,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,eAAe,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,GACpD,OAAO,CAAC,YAAY,CAAC;CA0KzB"}

package/dist/core/types.d.ts

@@ -42,6 +42,9 @@ export interface IArgParser<THandlerReturn = any> {
     removeMcpPrompt(name: string): this;
     getMcpPrompts(): any[];
     getMcpServerConfig?(): any;
+    setPromptWhen?(promptWhen: PromptWhen): this;
+    setOnCancel?(onCancel: (ctx: IHandlerContext) => void | Promise<void>): this;
+    getPromptWhen?(): PromptWhen;
 }
 /**
  * Defines the behavior for flag inheritance in sub-commands.
@@ -115,6 +118,8 @@ export declare const zodFlagSchema: z.ZodPipe<z.ZodObject<{
     dynamicRegister: z.ZodOptional<z.ZodCustom<DynamicRegisterFn, DynamicRegisterFn>>;
     setWorkingDirectory: z.ZodOptional<z.ZodBoolean>;
     positional: z.ZodOptional<z.ZodNumber>;
+    prompt: z.ZodOptional<z.ZodCustom<(ctx: any) => any, (ctx: any) => any>>;
+    promptSequence: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>, z.ZodTransform<{
     [key: string]: any;
 }, {
@@ -144,6 +149,8 @@ export declare const zodFlagSchema: z.ZodPipe<z.ZodObject<{
     dynamicRegister?: DynamicRegisterFn | undefined;
     setWorkingDirectory?: boolean | undefined;
     positional?: number | undefined;
+    prompt?: ((ctx: any) => any) | undefined;
+    promptSequence?: number | undefined;
 }>>;
 /**
  * The raw input type for defining a flag, before Zod processing (aliases, defaults).
@@ -296,6 +303,163 @@ export type TParsedArgs<TFlags extends readonly ProcessedFlag[]> = {
         name: K;
     }>>;
 };
+/**
+ * System flags detected during parsing.
+ * These flags are processed by ArgParser internally and made available to handlers
+ * for inspection and debugging purposes.
+ */
+export interface ISystemArgs {
+    /** Whether --s-debug flag was present (enables debug output) */
+    debug?: boolean;
+    /** Whether --s-debug-print flag was present (prints config and exits) */
+    debugPrint?: boolean;
+    /** Whether --s-enable-fuzzy flag was present (enables fuzzy testing mode) */
+    enableFuzzy?: boolean;
+    /** Path provided with --s-with-env flag (loads env config from file), or true if no path */
+    withEnv?: string | true;
+    /** Whether --s-save-to-env flag was present (saves config to env file) */
+    saveToEnv?: boolean;
+    /** Output path for --s-build-dxt flag (generates DXT package), or true if no path */
+    buildDxt?: string | true;
+    /** Whether --s-mcp-serve flag was present (starts MCP server) */
+    mcpServe?: boolean;
+    /** Transport type from --s-mcp-transport flag */
+    mcpTransport?: string;
+    /** Port from --s-mcp-port flag */
+    mcpPort?: number;
+    /** Host from --s-mcp-host flag */
+    mcpHost?: string;
+    /** Path from --s-mcp-path flag */
+    mcpPath?: string;
+    /** Transports config from --s-mcp-transports flag */
+    mcpTransports?: string;
+    /** Log path from --s-mcp-log-path flag */
+    mcpLogPath?: string;
+    /** CORS config from --s-mcp-cors flag */
+    mcpCors?: any;
+    /** Auth config from --s-mcp-auth flag */
+    mcpAuth?: any;
+    /** Raw system flags that were detected but not explicitly typed */
+    [key: string]: any;
+}
+/**
+ * Types of interactive prompts supported by @clack/prompts integration.
+ */
+export type PromptType = "text" | "password" | "confirm" | "select" | "multiselect";
+/**
+ * Configuration for a single interactive prompt field.
+ * Used to define the appearance and behavior of a prompt.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   type: "select",
+ *   message: "Select environment:",
+ *   options: [
+ *     { label: "Staging", value: "staging", hint: "Safe for testing" },
+ *     { label: "Production", value: "production", hint: "Careful!" }
+ *   ],
+ *   validate: (val) => val !== "production" || confirm("Are you sure?")
+ * }
+ * ```
+ */
+export interface PromptFieldConfig {
+    /** Type of prompt to display */
+    type: PromptType;
+    /** Message shown to the user */
+    message: string;
+    /** Placeholder text (for text/password types) */
+    placeholder?: string;
+    /** Initial/default value */
+    initial?: any;
+    /**
+     * Validation function.
+     * Return true for valid, string for error message.
+     * Can be async.
+     */
+    validate?: (value: any, ctx: IHandlerContext) => boolean | string | Promise<boolean | string>;
+    /**
+     * Options for select/multiselect.
+     * Can be simple strings or label/value objects.
+     */
+    options?: Array<string | {
+        label: string;
+        value: any;
+        hint?: string;
+    }>;
+    /** Maximum items to show before scrolling (select/multiselect) */
+    maxItems?: number;
+}
+/**
+ * When to trigger interactive prompts for a command.
+ * - `"interactive-flag"`: Prompts shown only when `--interactive` or `-i` flag is present (default)
+ * - `"missing"`: Prompts shown when any promptable flag is missing a value
+ * - `"always"`: Always show prompts (overrides CLI args for promptable flags)
+ */
+export type PromptWhen = "interactive-flag" | "missing" | "always";
+/**
+ * Extended flag with interactive prompt capability.
+ * Flags with a `prompt` property can participate in interactive mode.
+ *
+ * @example
+ * ```typescript
+ * cli.addFlag({
+ *   name: "environment",
+ *   options: ["--env", "-e"],
+ *   type: "string",
+ *   promptSequence: 1,
+ *   prompt: async (ctx) => ({
+ *     type: "select",
+ *     message: "Select environment:",
+ *     options: ["staging", "production"]
+ *   })
+ * });
+ * ```
+ */
+export interface IPromptableFlag extends IFlag {
+    /**
+     * Prompt configuration factory.
+     * If provided, this flag can participate in interactive mode.
+     * Called at prompt time to get the configuration for @clack/prompts.
+     *
+     * The context (`ctx`) includes `promptAnswers` with previous answers,
+     * enabling conditional prompts based on earlier selections.
+     */
+    prompt?: (ctx: IHandlerContext) => PromptFieldConfig | Promise<PromptFieldConfig>;
+    /**
+     * Explicit sequence order (1 = first, 2 = second, etc.)
+     * If omitted, uses the flag's position in the parser's flag array.
+     * Ties are broken by array order (first in array wins).
+     */
+    promptSequence?: number;
+}
+/**
+ * Extended subcommand with interactive mode support.
+ * Configure when prompts are shown and handle cancellation.
+ *
+ * @example
+ * ```typescript
+ * cli.addSubCommand({
+ *   name: "deploy",
+ *   description: "Deploy the application",
+ *   promptWhen: "interactive-flag",
+ *   parser: deployParser,
+ *   onCancel: () => console.log("Deployment cancelled")
+ * });
+ * ```
+ */
+export interface IInteractiveSubCommand extends ISubCommand {
+    /**
+     * When to trigger interactive prompts for this command.
+     * @default "interactive-flag"
+     */
+    promptWhen?: PromptWhen;
+    /**
+     * Called when user cancels (Ctrl+C) during prompts.
+     * If not provided, exits gracefully with code 0.
+     */
+    onCancel?: (ctx: IHandlerContext) => void | Promise<void>;
+}
 /**
  * Generic context object passed to command handlers.
  * @template TCurrentCommandArgs Shape of `args` for the current command, derived from its flags.
@@ -315,6 +479,11 @@ export type IHandlerContext<TCurrentCommandArgs = any, TParentCommandArgs = any>
     /** Optional: The root `ArgParser` instance of the CLI. */
     /** Indicates if the handler is being called from MCP mode (true) or CLI mode (false). */
     isMcp?: boolean;
+    /**
+     * Indicates if running in interactive mode (prompts were shown).
+     * Only true when interactive prompts were triggered and completed.
+     */
+    isInteractive?: boolean;
     /**
      * Get a flag value with proper resolution priority (CLI flag > ENV > default).
      * Only available in MCP mode when isMcp is true.
@@ -345,6 +514,30 @@ export type IHandlerContext<TCurrentCommandArgs = any, TParentCommandArgs = any>
      * const userInputPath = path.resolve(ctx.rootPath, ctx.args.input);
      */
     rootPath?: string;
+    /**
+     * System flags that were detected during parsing.
+     * These are flags that start with --s- and are processed internally by ArgParser.
+     * They are made available to handlers for inspection and debugging.
+     *
+     * @example
+     * // User runs: my-cli --s-debug --s-mcp-serve
+     * // In handler:
+     * console.log(ctx.systemArgs); // { debug: true, mcpServe: true }
+     */
+    systemArgs?: ISystemArgs;
+    /**
+     * Answers collected from interactive prompts.
+     * Populated sequentially as prompts are answered.
+     * Available to subsequent prompts for conditional logic.
+     * Also available to the final handler.
+     *
+     * Keys are flag names, values are the user's answers.
+     *
+     * @example
+     * // After prompts: environment="staging", version="1.2.3"
+     * console.log(ctx.promptAnswers); // { environment: "staging", version: "1.2.3" }
+     */
+    promptAnswers?: Record<string, any>;
     /**
      * Data-safe logger instance.
      * In MCP mode, this logger ensures STDOUT safety by routing logs to STDERR or a file.
@@ -478,6 +671,37 @@ export interface ISubCommand<TSubCommandFlags extends FlagsArray = FlagsArray, T
     };
     /** MCP tool generation options for DXT generation */
     mcpToolOptions?: any;
+    /**
+     * When to trigger interactive prompts for this command.
+     * - `"interactive-flag"` (default): Prompts shown only when `--interactive` or `-i` flag is present
+     * - `"missing"`: Prompts shown when any promptable flag is missing a value
+     * - `"always"`: Always show prompts (overrides CLI args for promptable flags)
+     *
+     * @example
+     * ```typescript
+     * cli.addSubCommand({
+     *   name: "deploy",
+     *   description: "Deploy the application",
+     *   promptWhen: "interactive-flag",
+     *   parser: deployParser
+     * });
+     * ```
+     */
+    promptWhen?: PromptWhen;
+    /**
+     * Called when user cancels (Ctrl+C) during prompts.
+     * If not provided, exits gracefully with code 0.
+     *
+     * @example
+     * ```typescript
+     * cli.addSubCommand({
+     *   name: "deploy",
+     *   parser: deployParser,
+     *   onCancel: (ctx) => console.log("Deployment cancelled by user")
+     * });
+     * ```
+     */
+    onCancel?: (ctx: IHandlerContext) => void | Promise<void>;
 }
 /**
  * Result of parsing operations that replaces process.exit() calls.