@alcyone-labs/arg-parser 2.14.2 → 3.0.0

package/dist/core/types.d.ts

@@ -1,68 +1,16 @@
-import { z, type ZodTypeAny } from "zod";
-export type ArgParserInstance = IArgParser;
-/**
- * Interface defining the MCP server methods expected by ArgParserBase.
- * This allows ArgParserBase to use these methods without depending on the concrete ArgParser class.
- */
-export interface IMcpServerMethods {
-    createMcpServer(serverInfo?: any, toolOptions?: any, logPath?: any): Promise<any>;
-    startMcpServerWithTransport(serverInfo: any, transportType: string, transportOptions: any, toolOptions: any, logPath?: string): Promise<void>;
-    startMcpServerWithMultipleTransports(serverInfo: any, transports: any[], toolOptions: any, logPath?: string): Promise<void>;
-    getMcpServerConfig(): any;
-}
 /**
- * Interface representing the public API of ArgParser/ArgParserBase.
+ * Core types for ArgParser
+ *
+ * These types define the shape of flags, commands, and configuration
+ * for the argument parser.
  */
-export interface IArgParser<THandlerReturn = any> {
-    getAppName(): string | undefined;
-    getAppCommandName(): string | undefined;
-    getSubCommandName(): string;
-    getDescription(): string | undefined;
-    getAutoExit(): boolean;
-    getHandler(): ((ctx: IHandlerContext) => void) | undefined;
-    getSubCommands(): Map<string, ISubCommand>;
-    get logger(): any;
-    get flags(): ProcessedFlag[];
-    get flagNames(): string[];
-    addFlag(flag: IFlag): this;
-    addFlags(flags: readonly IFlag[]): this;
-    hasFlag(name: string): boolean;
-    getFlagDefinition(name: string): ProcessedFlag | undefined;
-    addSubCommand(subCommandConfig: ISubCommand): this;
-    getSubCommand(name: string): ISubCommand | undefined;
-    parse(processArgs?: string[], options?: any): Promise<any>;
-    setHandler(handler: (ctx: IHandlerContext<any, any>) => THandlerReturn | Promise<THandlerReturn>): this;
-    helpText(): string;
-    printAll(filePath?: string): void;
-    getCommandChain(): string[];
-    addMcpResource(config: any): this;
-    removeMcpResource(name: string): this;
-    getMcpResources(): any[];
-    addMcpPrompt(config: any): this;
-    removeMcpPrompt(name: string): this;
-    getMcpPrompts(): any[];
-    getMcpServerConfig?(): any;
-    setPromptWhen?(promptWhen: PromptWhen): this;
-    setOnCancel?(onCancel: (ctx: IHandlerContext) => void | Promise<void>): this;
-    getPromptWhen?(): PromptWhen;
-}
+import { z, type ZodTypeAny } from "zod";
 /**
  * Defines the behavior for flag inheritance in sub-commands.
  */
 export declare const FlagInheritance: {
-    /**
-     * No flags are inherited from the parent.
-     */
     readonly NONE: "none";
-    /**
-     * Inherits flags only from the direct parent at the time of attachment (Snapshot behavior).
-     * Equivalent to `true` in legacy boolean config.
-     */
     readonly DirectParentOnly: "direct-parent-only";
-    /**
-     * Inherits flags from the entire parent chain, ensuring grandchildren receive root flags
-     * even in bottom-up construction scenarios.
-     */
     readonly AllParents: "all-parents";
 };
 export type TFlagInheritance = (typeof FlagInheritance)[keyof typeof FlagInheritance] | boolean;
@@ -76,8 +24,8 @@ export declare const zodDxtOptionsSchema: z.ZodObject<{
         string: "string";
         number: "number";
         boolean: "boolean";
-        file: "file";
         directory: "directory";
+        file: "file";
     }>>;
     multiple: z.ZodOptional<z.ZodBoolean>;
     min: z.ZodOptional<z.ZodNumber>;
@@ -85,7 +33,7 @@ export declare const zodDxtOptionsSchema: z.ZodObject<{
     default: z.ZodOptional<z.ZodAny>;
     title: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
-export declare const zodFlagSchema: z.ZodPipe<z.ZodObject<{
+export declare const zodFlagSchema: z.ZodObject<{
     name: z.ZodString;
     allowLigature: z.ZodDefault<z.ZodBoolean>;
     allowMultiple: z.ZodDefault<z.ZodBoolean>;
@@ -93,10 +41,10 @@ export declare const zodFlagSchema: z.ZodPipe<z.ZodObject<{
     valueHint: z.ZodOptional<z.ZodString>;
     options: z.ZodArray<z.ZodString>;
     defaultValue: z.ZodOptional<z.ZodAny>;
-    type: z.ZodDefault<z.ZodUnion<readonly [z.ZodAny, z.ZodAny, z.ZodAny, z.ZodAny, z.ZodAny, z.ZodCustom<(value: string) => any | Promise<any>, (value: string) => any | Promise<any>>, z.ZodCustom<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>, z.ZodString]>>;
-    mandatory: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodCustom<(value?: any, parsedArgs?: any) => boolean, (value?: any, parsedArgs?: any) => boolean>]>>;
+    type: z.ZodDefault<z.ZodUnion<readonly [z.ZodCustom<unknown, unknown>, z.ZodCustom<unknown, unknown>, z.ZodCustom<unknown, unknown>, z.ZodCustom<unknown, unknown>, z.ZodCustom<unknown, unknown>, z.ZodCustom<unknown, unknown>, z.ZodCustom<unknown, unknown>, z.ZodString]>>;
+    mandatory: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodCustom<unknown, unknown>]>>;
     flagOnly: z.ZodDefault<z.ZodBoolean>;
-    validate: z.ZodOptional<z.ZodCustom<(value?: any, parsedArgs?: any) => boolean | string | void | Promise<boolean | string | void>, (value?: any, parsedArgs?: any) => boolean | string | void | Promise<boolean | string | void>>>;
+    validate: z.ZodOptional<z.ZodCustom<unknown, unknown>>;
     enum: z.ZodOptional<z.ZodArray<z.ZodAny>>;
     env: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
     dxtOptions: z.ZodOptional<z.ZodObject<{
@@ -106,8 +54,8 @@ export declare const zodFlagSchema: z.ZodPipe<z.ZodObject<{
             string: "string";
             number: "number";
             boolean: "boolean";
-            file: "file";
             directory: "directory";
+            file: "file";
         }>>;
         multiple: z.ZodOptional<z.ZodBoolean>;
         min: z.ZodOptional<z.ZodNumber>;
@@ -115,502 +63,160 @@ export declare const zodFlagSchema: z.ZodPipe<z.ZodObject<{
         default: z.ZodOptional<z.ZodAny>;
         title: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
-    dynamicRegister: z.ZodOptional<z.ZodCustom<DynamicRegisterFn, DynamicRegisterFn>>;
+    dynamicRegister: z.ZodOptional<z.ZodCustom<unknown, unknown>>;
     setWorkingDirectory: z.ZodOptional<z.ZodBoolean>;
     positional: z.ZodOptional<z.ZodNumber>;
-    prompt: z.ZodOptional<z.ZodCustom<(ctx: any) => any, (ctx: any) => any>>;
+    prompt: z.ZodOptional<z.ZodCustom<unknown, unknown>>;
     promptSequence: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strip>, z.ZodTransform<{
-    [key: string]: any;
-}, {
-    name: string;
-    allowLigature: boolean;
-    allowMultiple: boolean;
-    options: string[];
-    type: any;
-    flagOnly: boolean;
-    description?: string | string[] | undefined;
-    valueHint?: string | undefined;
-    defaultValue?: any;
-    mandatory?: boolean | ((value?: any, parsedArgs?: any) => boolean) | undefined;
-    validate?: ((value?: any, parsedArgs?: any) => boolean | string | void | Promise<boolean | string | void>) | undefined;
-    enum?: any[] | undefined;
-    env?: string | string[] | undefined;
-    dxtOptions?: {
-        sensitive?: boolean | undefined;
-        localDefault?: string | undefined;
-        type?: "string" | "number" | "boolean" | "file" | "directory" | undefined;
-        multiple?: boolean | undefined;
-        min?: number | undefined;
-        max?: number | undefined;
-        default?: any;
-        title?: string | undefined;
-    } | undefined;
-    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).
- */
+}, z.core.$strip>;
 export type IFlagCore = z.input<typeof zodFlagSchema>;
-/**
- * The type of the `type` property in a ProcessedFlagCore object.
- * This represents all valid forms the `type` property can take after Zod processing.
- */
-export type TParsedArgsTypeFromFlagDef = StringConstructor | NumberConstructor | BooleanConstructor | ArrayConstructor | ObjectConstructor | ((value: string) => any) | ((value: string) => Promise<any>) | ZodTypeAny | "string" | "number" | "boolean" | "array" | "object";
-/**
- * The core type of a flag after Zod processing (defaults applied, aliases resolved),
- * but before some properties are made more specific (like `type` constructor to actual type).
- * This type is output by `zodFlagSchema.parse()`.
- */
-export type ProcessedFlagCore = Omit<z.output<typeof zodFlagSchema>, "type"> & {
-    type: TParsedArgsTypeFromFlagDef;
-};
-/**
- * DXT-specific configuration options for flags that will be included in DXT manifests.
- * These options control how the flag appears in DXT user_config and how it behaves in DXT environments.
- */
+export type ProcessedFlagCore = z.output<typeof zodFlagSchema>;
 export interface IDxtOptions {
-    /** Whether this field should be marked as sensitive in DXT user_config (default: true for ENV-linked flags) */
     sensitive?: boolean;
-    /** Default value specific to DXT sandbox environment (different from regular default) */
     localDefault?: string;
-    /** DXT input type - determines UI component in DXT clients (default: inferred from IFlag.type) */
     type?: "string" | "directory" | "file" | "boolean" | "number";
-    /** Allow multiple values (for arrays) */
     multiple?: boolean;
-    /** Minimum value (for number type) */
     min?: number;
-    /** Maximum value (for number type) */
     max?: number;
-    /** DXT-specific default value (overrides localDefault if provided) */
     default?: any;
-    /** Custom title for the user_config field (overrides auto-generated title) */
     title?: string;
 }
-/**
- * The user-facing type for defining a flag. It includes aliases like `default` and `required`.
- * The `handler` property is removed as handlers are typically associated with commands/subcommands, not individual flags.
- */
 export type IFlag = IFlagCore & {
-    /** @alias defaultValue */
     default?: any;
-    /** @alias mandatory */
-    required?: boolean | ((parsedArgs: TParsedArgs<any>) => boolean);
-    /** Environment variables that should be set from this flag's value in DXT packages */
+    required?: boolean | ((parsedArgs: any) => boolean);
     env?: string | string[];
-    /** DXT-specific configuration options for enhanced DXT manifest generation */
     dxtOptions?: IDxtOptions;
-    /** Optional callback to dynamically register additional flags when this flag is present */
     dynamicRegister?: DynamicRegisterFn;
-    /**
-     * If true, this flag's value becomes the effective working directory.
-     * When set, all file operations (including .env loading) will be relative to this path.
-     * Last flag with this property in the command chain wins.
-     *
-     * @alias chdir
-     *
-     * @example
-     * ```typescript
-     * .addFlag({
-     *   name: "workspace",
-     *   description: "Workspace directory to operate in",
-     *   options: ["--workspace", "-w"],
-     *   type: "string",
-     *   setWorkingDirectory: true,
-     * })
-     * ```
-     *
-     * @example
-     * ```typescript
-     * // User runs: my-cli --workspace ./packages/my-app
-     * // Effective cwd becomes: /repo/packages/my-app/
-     * // All .env files are loaded from: /repo/packages/my-app/
-     * ```
-     */
     setWorkingDirectory?: boolean;
-    /**
-     * Captures the Nth trailing positional argument (1-indexed).
-     *
-     * - `positional: 1` captures the first trailing arg
-     * - `positional: 2` captures the second trailing arg
-     * - etc.
-     *
-     * Positional args are assigned AFTER all flags and subcommands are parsed.
-     * The flag's `options` array still works as a fallback (e.g., `--id xxx`).
-     *
-     * @example
-     * ```typescript
-     * .addFlag({
-     *   name: "id",
-     *   type: "string",
-     *   mandatory: true,
-     *   options: ["--id"],      // Fallback: --id xxx
-     *   positional: 1,          // Primary: workflow show xxx
-     *   description: "Workflow ID to show",
-     * })
-     * ```
-     */
     positional?: number;
 };
-/**
- * Context for dynamic flag registration callbacks.
- */
 export type DynamicRegisterContext = {
     value: any | any[];
     argsSoFar: Record<string, any>;
-    parser: ArgParserInstance;
+    parser: any;
     processArgs: string[];
     forHelp?: boolean;
     registerFlags: (flags: readonly IFlag[]) => void;
 };
-/**
- * Function signature for dynamic flag loader/registrar.
- */
 export type DynamicRegisterFn = (ctx: DynamicRegisterContext) => Promise<readonly IFlag[] | void> | readonly IFlag[] | void;
-/**
- * A more refined type for a flag after it has been fully processed by ArgParser,
- * particularly its `type` property and validation/enum/mandatory functions.
- * This is the type that ArgParser would internally work with for parsing and type extraction.
- */
-export type ProcessedFlag = Omit<ProcessedFlagCore, "validate" | "enum" | "mandatory"> & {
-    validate?: (value: any, parsedArgs?: TParsedArgs<ProcessedFlag[]>) => boolean | string | void | Promise<boolean | string | void>;
-    enum?: any[];
-    mandatory?: boolean | ((parsedArgs: TParsedArgs<ProcessedFlag[]>) => boolean);
-    env?: string | string[];
-    dynamicRegister?: DynamicRegisterFn;
-    positional?: number;
-};
-/**
- * Resolves the TypeScript type from a flag's `type` definition.
- */
+export type ProcessedFlag = ProcessedFlagCore;
+export type TParsedArgsTypeFromFlagDef = StringConstructor | NumberConstructor | BooleanConstructor | ArrayConstructor | ObjectConstructor | ((value: string) => any) | ((value: string) => Promise<any>) | ZodTypeAny | "string" | "number" | "boolean" | "array" | "object";
 export type ResolveType<T extends TParsedArgsTypeFromFlagDef> = T extends StringConstructor ? string : T extends NumberConstructor ? number : T extends BooleanConstructor ? boolean : T extends ArrayConstructor ? any[] : T extends ObjectConstructor ? Record<string, any> : T extends ZodTypeAny ? z.infer<T> : T extends "string" ? string : T extends "number" ? number : T extends "boolean" ? boolean : T extends "array" ? any[] : T extends "object" ? Record<string, any> : T extends (value: string) => infer R ? R : any;
-/**
- * Extracts the final TypeScript type for a flag's value based on its definition,
- * considering `flagOnly` and `allowMultiple` properties.
- */
-export type ExtractFlagType<TFlag extends ProcessedFlag> = TFlag["flagOnly"] extends true ? TFlag["allowMultiple"] extends true ? boolean[] : boolean : TFlag["allowMultiple"] extends true ? Array<ResolveType<TFlag["type"]>> : ResolveType<TFlag["type"]>;
-/**
- * Represents the structured object of parsed arguments.
- * Keys are flag names, and values are their parsed and typed values.
- * `TFlags` should be the array of `ProcessedFlag` definitions for the specific command.
- */
+export type ExtractFlagType<_TFlag extends ProcessedFlag> = any;
+export type FlagsArray = readonly ProcessedFlag[];
 export type TParsedArgs<TFlags extends readonly ProcessedFlag[]> = {
     [K in TFlags[number]["name"]]: ExtractFlagType<Extract<TFlags[number], {
         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 IHandlerContext<TCurrentCommandArgs = any, TParentCommandArgs = any> = {
+    args: TCurrentCommandArgs;
+    parentArgs?: TParentCommandArgs;
+    commandChain: string[];
+    parser: any;
+    parentParser?: any;
+    isMcp?: boolean;
+    isInteractive?: boolean;
+    getFlag?: (name: string) => any;
+    displayHelp: () => void;
+    rootPath?: string;
+    systemArgs?: ISystemArgs;
+    promptAnswers?: Record<string, any>;
+    logger: any;
+};
+export type MainHandler<TParserFlags extends FlagsArray = FlagsArray, TParentParserFlags extends FlagsArray = FlagsArray, THandlerReturn = any> = (ctx: IHandlerContext<TParsedArgs<TParserFlags>, TParsedArgs<TParentParserFlags>>) => THandlerReturn | Promise<THandlerReturn>;
+export interface ISubCommand {
+    name: string;
+    description?: string;
+    parser: any;
+    handler?: (ctx: IHandlerContext) => any;
+    isMcp?: boolean;
+    mcpServerInfo?: {
+        name: string;
+        version: string;
+        description?: string;
+    };
+    mcpToolOptions?: any;
+    promptWhen?: PromptWhen;
+    onCancel?: (ctx: IHandlerContext) => void | Promise<void>;
+}
 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 for the prompt.
-     * For select: the value to pre-select
-     * For multiselect: array of values to pre-select
-     * For confirm: boolean initial value
-     * Falls back to flag's defaultValue if not specified
-     */
     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;
-    /**
-     * If true, this prompt will be skipped and the flag will not be set.
-     * Useful for conditional prompts based on previous answers.
-     * @default false
-     */
     skip?: boolean;
 }
-/**
- * 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.
- * @template TParentCommandArgs Shape of `parentArgs` from the parent command, if any.
- */
-export type IHandlerContext<TCurrentCommandArgs = any, TParentCommandArgs = any> = {
-    /** Parsed arguments specific to the current command. */
-    args: TCurrentCommandArgs;
-    /** Parsed arguments from the parent command, if this is a subcommand. */
-    parentArgs?: TParentCommandArgs;
-    /** The sequence of command names that led to this handler. */
-    commandChain: string[];
-    /** The `ArgParser` instance that invoked this handler (could be a subcommand's parser). */
-    parser: ArgParserInstance;
-    /** The parent `ArgParser` instance, if this is a subcommand handler. */
-    parentParser?: ArgParserInstance;
-    /** 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.
-     */
-    getFlag?: (name: string) => any;
-    /**
-     * Display the help message for the current command context.
-     */
-    displayHelp: () => void;
-    /**
-     * The root path from the user's CLI command perspective.
-     * This is the original current working directory when the CLI was invoked.
-     *
-     * Use this when you need to reference paths relative to where the user ran the command,
-     * as opposed to the effective working directory (which may have been changed by
-     * flags with `setWorkingDirectory`).
-     *
-     * @example
-     * // User runs: my-cli --workspace ./packages/app --input ./data/file.txt
-     * // From /repo/ directory
-     *
-     * // In handler:
-     * console.log(ctx.rootPath);           // "/repo/" (where user ran command)
-     * console.log(process.cwd());           // "/repo/packages/app/" (effective cwd)
-     * console.log(ctx.args.input);          // "./data/file.txt" (relative to effective cwd)
-     *
-     * // To resolve ctx.args.input relative to user's cwd:
-     * 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.
-     */
-    logger: any;
-};
-/**
- * Generic type for the collection of processed flags that an ArgParser instance manages.
- */
-export type FlagsArray = readonly ProcessedFlag[];
-/**
- * Converts a flag type to a JSON Schema type string.
- * This function handles all possible flag type formats and returns a valid JSON Schema type.
- *
- * @param flagType - The flag type from IFlag or ProcessedFlag
- * @returns A JSON Schema type string: "string" | "number" | "boolean" | "array" | "object"
- *
- * @example
- * ```typescript
- * getJsonSchemaTypeFromFlag(String) // returns "string"
- * getJsonSchemaTypeFromFlag("number") // returns "number"
- * getJsonSchemaTypeFromFlag((val) => parseInt(val)) // returns "string" (fallback for custom functions)
- * ```
- */
+export type ArgParserInstance = any;
+export interface ParseResult<T = any> {
+    success: boolean;
+    exitCode: number;
+    data?: T;
+    message?: string;
+    shouldExit?: boolean;
+    type?: "success" | "error" | "help" | "version" | "debug";
+}
+export interface ArgParserOptions {
+    autoExit?: boolean;
+    handleErrors?: boolean;
+}
+export interface ArgParserBehaviorOptions {
+    autoExit?: boolean;
+    handleErrors?: boolean;
+}
 export declare function getJsonSchemaTypeFromFlag(flagType: TParsedArgsTypeFromFlagDef): "string" | "number" | "boolean" | "array" | "object";
-/**
- * Common output schema patterns for typical CLI/MCP tool responses
- */
 export declare const OutputSchemaPatterns: {
-    /**
-     * Simple success/error response pattern
-     * @example { success: true, message: "Operation completed" }
-     */
     readonly successError: () => z.ZodObject<{
         success: z.ZodBoolean;
         message: z.ZodOptional<z.ZodString>;
         error: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
-    /**
-     * Success response with data payload
-     * @example { success: true, data: {...}, message: "Data retrieved" }
-     */
     readonly successWithData: (dataSchema?: z.ZodTypeAny) => z.ZodObject<{
         success: z.ZodBoolean;
         data: z.ZodAny | z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
         message: z.ZodOptional<z.ZodString>;
         error: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
-    /**
-     * List/array response pattern
-     * @example { items: [...], count: 5, hasMore: false }
-     */
     readonly list: (itemSchema?: z.ZodTypeAny) => z.ZodObject<{
         items: z.ZodArray<z.ZodAny | z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
         count: z.ZodOptional<z.ZodNumber>;
         hasMore: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>;
-    /**
-     * File operation response pattern
-     * @example { path: "/path/to/file", size: 1024, created: true }
-     */
     readonly fileOperation: () => z.ZodObject<{
         path: z.ZodString;
         size: z.ZodOptional<z.ZodNumber>;
@@ -618,10 +224,6 @@ export declare const OutputSchemaPatterns: {
         modified: z.ZodOptional<z.ZodBoolean>;
         exists: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>;
-    /**
-     * Process execution response pattern
-     * @example { exitCode: 0, stdout: "output", stderr: "", duration: 1500 }
-     */
     readonly processExecution: () => z.ZodObject<{
         exitCode: z.ZodNumber;
         stdout: z.ZodOptional<z.ZodString>;
@@ -630,134 +232,23 @@ export declare const OutputSchemaPatterns: {
         command: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
 };
-/**
- * Type for output schema pattern names with auto-completion support
- */
 export type OutputSchemaPatternName = keyof typeof OutputSchemaPatterns;
-/**
- * Type for output schema configuration - supports pattern names, Zod schemas, or schema definition objects
- */
 export type OutputSchemaConfig = OutputSchemaPatternName | z.ZodTypeAny | Record<string, z.ZodTypeAny>;
-/**
- * Creates a Zod output schema from a pattern or custom definition
- *
- * @param pattern - Either a predefined pattern name, a Zod schema, or a schema definition object
- * @returns A Zod schema for output validation
- *
- * @example
- * ```typescript
- * // Using a predefined pattern
- * const schema1 = createOutputSchema('successError');
- *
- * // Using a custom Zod schema
- * const schema2 = createOutputSchema(z.object({ result: z.string() }));
- *
- * // Using a schema definition object
- * const schema3 = createOutputSchema({
- *   result: z.string().describe("The result"),
- *   timestamp: z.string().describe("When the operation completed")
- * });
- * ```
- */
 export declare function createOutputSchema(pattern: OutputSchemaConfig): z.ZodTypeAny;
 /**
- * Defines a subcommand within an ArgParser setup.
- * @template TSubCommandFlags Flags defined specifically FOR this subcommand.
- * @template TParentCommandFlags Flags defined for the PARENT of this subcommand.
- * @template THandlerReturn The expected return type of the subcommand's handler.
- */
-export interface ISubCommand<TSubCommandFlags extends FlagsArray = FlagsArray, TParentCommandFlags extends FlagsArray = FlagsArray, THandlerReturn = any> {
-    name: string;
-    description?: string;
-    /** The ArgParser instance for this subcommand, typed with its own flags. */
-    parser: ArgParserInstance;
-    /** Handler function for this subcommand. */
-    handler?: (ctx: IHandlerContext<TParsedArgs<TSubCommandFlags>, TParsedArgs<TParentCommandFlags>>) => THandlerReturn | Promise<THandlerReturn>;
-    /** Internal flag to identify MCP subcommands for proper exclusion from tool generation */
-    isMcp?: boolean;
-    /** MCP server information for DXT generation */
-    mcpServerInfo?: {
-        name: string;
-        version: string;
-        description?: string;
-    };
-    /** 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.
- * Provides structured information about the parsing outcome.
- */
-export interface ParseResult<T = any> {
-    /** Whether the parsing was successful */
-    success: boolean;
-    /** Exit code that would have been used with process.exit() */
-    exitCode: number;
-    /** The parsed data/result when successful */
-    data?: T;
-    /** Human-readable message about the result */
-    message?: string;
-    /** Whether the process should exit (for help, version, etc.) */
-    shouldExit?: boolean;
-    /** Type of result for better handling */
-    type?: "success" | "error" | "help" | "version" | "debug";
-}
-/**
- * Configuration options for ArgParser behavior
- * @deprecated Use IArgParserParams for full configuration options. This interface will be removed in v3.0.
- */
-export interface ArgParserOptions {
-    /** Whether to automatically call process.exit() based on ParseResult (default: true for backward compatibility) */
-    autoExit?: boolean;
-    /** Whether to handle errors by exiting or throwing (default: true for backward compatibility) */
-    handleErrors?: boolean;
-}
-/**
- * Configuration options for ArgParser runtime behavior
- * This is a more clearly named version of ArgParserOptions
- */
-export interface ArgParserBehaviorOptions {
-    /** Whether to automatically call process.exit() based on ParseResult (default: true for backward compatibility) */
-    autoExit?: boolean;
-    /** Whether to handle errors by exiting or throwing (default: true for backward compatibility) */
-    handleErrors?: boolean;
+ * Result of executing prompts
+ */
+export interface PromptResult {
+    /** Collected answers */
+    answers: Record<string, any>;
+    /** Individual prompt results */
+    results: Array<{
+        flagName: string;
+        success: boolean;
+        value?: any;
+        error?: string;
+    }>;
+    /** Whether the user cancelled */
+    cancelled: boolean;
 }
-/**
- * Type for the main handler of an ArgParser instance (root command or a command defined by an ArgParser).
- * @template TParserFlags Flags defined for this ArgParser instance.
- * @template TParentParserFlags Flags of the parent parser, if this parser is used as a subcommand.
- * @template THandlerReturn The expected return type of the handler.
- */
-export type MainHandler<TParserFlags extends FlagsArray = FlagsArray, TParentParserFlags extends FlagsArray = FlagsArray, THandlerReturn = any> = (ctx: IHandlerContext<TParsedArgs<TParserFlags>, TParsedArgs<TParentParserFlags>>) => THandlerReturn | Promise<THandlerReturn>;
 //# sourceMappingURL=types.d.ts.map