{"version":3,"file":"public-api.mjs","names":[],"sources":["../../src/lib/public-api.ts"],"sourcesContent":[" \nimport {\n  ArrayOptionConfig,\n  BooleanOptionConfig,\n  type ConfigurationFiles,\n  EnvOptionConfig,\n  LocalizationDictionary,\n  LocalizationFunction,\n  Expand,\n  MakeUndefinedPropertiesOptional,\n  NumberOptionConfig,\n  ObjectOptionConfig,\n  OneOfOptionConfig,\n  OptionConfig,\n  OptionConfigToType,\n  ParsedArgs,\n  ResolveProperties,\n  StringOptionConfig,\n  WithOptional,\n} from '@cli-forge/parser';\n\nimport { InternalCLI } from './internal-cli';\nimport type { CompletionCallback, OptionCompletionCallback } from './completion-types';\nimport type { PromptOptionConfig, PromptProvider } from './prompt-types';\nimport type { CommandContext, ProvidersFromChain } from './context';\n\nexport interface ProviderConfig<T, TArgs = any> {\n  factory: (args: TArgs) => T;\n  lifetime?: 'executionScope';\n}\n\nexport interface GlobalProviderConfig<T> {\n  factory: () => T;\n  lifetime: 'global';\n}\n\n/**\n * Extracts the command name from a Command type.\n * Works with both CLI instances and command config objects.\n */\nexport type ExtractCommandName<T> = T extends CLI<any, any, any, any, any>\n  ? T extends InternalCLI<any, any, any, any, any>\n    ? string\n    : string\n  : T extends { name: infer N }\n  ? N extends string\n    ? N\n    : string\n  : string;\n\n/**\n * Extracts the args type from a Command.\n * Works with both CLI instances and command config objects.\n */\nexport type ExtractCommandArgs<T> = T extends CLI<infer A, any, any, any, any>\n  ? A\n  : T extends CLICommandOptions<any, infer A, any, any>\n  ? A\n  : ParsedArgs;\n\n/**\n * Extracts the handler return type from a Command.\n */\nexport type ExtractCommandHandlerReturn<T> = T extends CLI<any, infer R, any, any, any>\n  ? R\n  : T extends CLICommandOptions<any, any, infer R, any>\n  ? R\n  : void;\n\n/**\n * Extracts the registered providers from a Command.\n * Works with both CLI instances (uses the 5th generic directly) and command\n * config objects (infers the builder's return type's provider map).\n */\nexport type ExtractCommandProviders<T> = T extends CLI<any, any, any, any, infer P>\n  ? P\n  : T extends CLICommandOptions<any, any, any, any, any, any, infer P>\n  ? P\n  : {};\n\n/**\n * Converts a Command to its child CLI entry for TChildren tracking.\n * TParentCLI is the parent CLI type that will be set as the child's TParent.\n */\nexport type CommandToChildEntry<T, TParentCLI = undefined> = {\n  [K in ExtractCommandName<T>]: CLI<\n    ExtractCommandArgs<T>,\n    ExtractCommandHandlerReturn<T>,\n    {},\n    TParentCLI,\n    ExtractCommandProviders<T>\n  >;\n};\n\n/**\n * The interface for a CLI application or subcommands.\n *\n * {@link cli} is provided as a small helper function to create a new CLI instance.\n *\n * @example\n * ```ts\n * import { cli } from 'cli-forge';\n *\n * cli('basic-cli').command('hello', {\n *   builder: (args) =>\n *    args.option('name', {\n *      type: 'string',\n *    }),\n *   handler: (args) => {\n *     console.log(`Hello, ${args.name}!`);\n *   }).forge();\n * ```\n */\nexport interface CLI<\n  TArgs extends ParsedArgs = ParsedArgs,\n  THandlerReturn = void,\n\n  TChildren = {},\n  TParent = undefined,\n  TProviders = {}\n> {\n  command<\n    TCommand extends Command<TArgs, any, any, any>,\n    TCommandArgs extends TArgs = ExtractCommandArgs<TCommand> extends TArgs\n      ? ExtractCommandArgs<TCommand>\n      : TArgs,\n    TCmdName extends string = ExtractCommandName<TCommand>,\n    TChildHandlerReturn = ExtractCommandHandlerReturn<TCommand>\n  >(\n    cmd: TCommand\n  ): CLI<\n    TArgs,\n    THandlerReturn,\n    TChildren & {\n      [key in TCmdName]: CLI<\n        TCommandArgs,\n        TChildHandlerReturn,\n        {},\n        CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>,\n        ExtractCommandProviders<TCommand>\n      >;\n    },\n    TParent,\n    TProviders\n  >;\n\n  /**\n   * Registers a new command with the CLI.\n   * @param key What should the new command be called?\n   * @param options Settings for the new command. See {@link CLICommandOptions}.\n   * @returns Updated CLI instance with the new command registered.\n   */\n  command<\n    TCommandArgs extends TArgs,\n    TChildHandlerReturn,\n    TKey extends string,\n\n    TChildChildren = {},\n    TChildProviders = {}\n  >(\n    key: TKey,\n    options: CLICommandOptions<\n      TArgs,\n      TCommandArgs,\n      TChildHandlerReturn,\n      TChildren,\n      CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>,\n      TChildChildren,\n      TChildProviders\n    >\n  ): CLI<\n    TArgs,\n    THandlerReturn,\n    TChildren & {\n      [key in TKey]: CLI<\n        TCommandArgs,\n        TChildHandlerReturn,\n        TChildChildren,\n        CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>,\n        TChildProviders\n      >;\n    },\n    TParent,\n    TProviders\n  >;\n\n  /**\n   * Registers multiple subcommands with the CLI.\n   * @param commands Several commands to register. Can be the result of a call to {@link cli} or a configuration object.\n   * @returns Updated CLI instance with the commands registered and their types tracked in TChildren.\n   */\n  // Typed overloads for 1-10 commands to preserve individual command types\n  // Each child command gets this CLI as its TParent\n  commands<C1 extends Command>(\n    c1: C1\n  ): CLI<\n    TArgs,\n    THandlerReturn,\n    TChildren &\n      CommandToChildEntry<C1, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>>,\n    TParent,\n    TProviders\n  >;\n  commands<C1 extends Command, C2 extends Command>(\n    c1: C1,\n    c2: C2\n  ): CLI<\n    TArgs,\n    THandlerReturn,\n    TChildren &\n      CommandToChildEntry<C1, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C2, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>>,\n    TParent,\n    TProviders\n  >;\n  commands<C1 extends Command, C2 extends Command, C3 extends Command>(\n    c1: C1,\n    c2: C2,\n    c3: C3\n  ): CLI<\n    TArgs,\n    THandlerReturn,\n    TChildren &\n      CommandToChildEntry<C1, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C2, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C3, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>>,\n    TParent,\n    TProviders\n  >;\n  commands<\n    C1 extends Command,\n    C2 extends Command,\n    C3 extends Command,\n    C4 extends Command\n  >(\n    c1: C1,\n    c2: C2,\n    c3: C3,\n    c4: C4\n  ): CLI<\n    TArgs,\n    THandlerReturn,\n    TChildren &\n      CommandToChildEntry<C1, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C2, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C3, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C4, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>>,\n    TParent,\n    TProviders\n  >;\n  commands<\n    C1 extends Command,\n    C2 extends Command,\n    C3 extends Command,\n    C4 extends Command,\n    C5 extends Command\n  >(\n    c1: C1,\n    c2: C2,\n    c3: C3,\n    c4: C4,\n    c5: C5\n  ): CLI<\n    TArgs,\n    THandlerReturn,\n    TChildren &\n      CommandToChildEntry<C1, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C2, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C3, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C4, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C5, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>>,\n    TParent,\n    TProviders\n  >;\n  commands<\n    C1 extends Command,\n    C2 extends Command,\n    C3 extends Command,\n    C4 extends Command,\n    C5 extends Command,\n    C6 extends Command\n  >(\n    c1: C1,\n    c2: C2,\n    c3: C3,\n    c4: C4,\n    c5: C5,\n    c6: C6\n  ): CLI<\n    TArgs,\n    THandlerReturn,\n    TChildren &\n      CommandToChildEntry<C1, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C2, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C3, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C4, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C5, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C6, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>>,\n    TParent,\n    TProviders\n  >;\n  commands<\n    C1 extends Command,\n    C2 extends Command,\n    C3 extends Command,\n    C4 extends Command,\n    C5 extends Command,\n    C6 extends Command,\n    C7 extends Command\n  >(\n    c1: C1,\n    c2: C2,\n    c3: C3,\n    c4: C4,\n    c5: C5,\n    c6: C6,\n    c7: C7\n  ): CLI<\n    TArgs,\n    THandlerReturn,\n    TChildren &\n      CommandToChildEntry<C1, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C2, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C3, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C4, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C5, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C6, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C7, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>>,\n    TParent,\n    TProviders\n  >;\n  commands<\n    C1 extends Command,\n    C2 extends Command,\n    C3 extends Command,\n    C4 extends Command,\n    C5 extends Command,\n    C6 extends Command,\n    C7 extends Command,\n    C8 extends Command\n  >(\n    c1: C1,\n    c2: C2,\n    c3: C3,\n    c4: C4,\n    c5: C5,\n    c6: C6,\n    c7: C7,\n    c8: C8\n  ): CLI<\n    TArgs,\n    THandlerReturn,\n    TChildren &\n      CommandToChildEntry<C1, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C2, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C3, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C4, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C5, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C6, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C7, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C8, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>>,\n    TParent,\n    TProviders\n  >;\n  commands<\n    C1 extends Command,\n    C2 extends Command,\n    C3 extends Command,\n    C4 extends Command,\n    C5 extends Command,\n    C6 extends Command,\n    C7 extends Command,\n    C8 extends Command,\n    C9 extends Command\n  >(\n    c1: C1,\n    c2: C2,\n    c3: C3,\n    c4: C4,\n    c5: C5,\n    c6: C6,\n    c7: C7,\n    c8: C8,\n    c9: C9\n  ): CLI<\n    TArgs,\n    THandlerReturn,\n    TChildren &\n      CommandToChildEntry<C1, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C2, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C3, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C4, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C5, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C6, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C7, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C8, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C9, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>>,\n    TParent,\n    TProviders\n  >;\n  commands<\n    C1 extends Command,\n    C2 extends Command,\n    C3 extends Command,\n    C4 extends Command,\n    C5 extends Command,\n    C6 extends Command,\n    C7 extends Command,\n    C8 extends Command,\n    C9 extends Command,\n    C10 extends Command\n  >(\n    c1: C1,\n    c2: C2,\n    c3: C3,\n    c4: C4,\n    c5: C5,\n    c6: C6,\n    c7: C7,\n    c8: C8,\n    c9: C9,\n    c10: C10\n  ): CLI<\n    TArgs,\n    THandlerReturn,\n    TChildren &\n      CommandToChildEntry<C1, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C2, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C3, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C4, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C5, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C6, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C7, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C8, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C9, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>> &\n      CommandToChildEntry<C10, CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>>,\n    TParent,\n    TProviders\n  >;\n  // Fallback for arrays or more than 10 commands (loses individual type tracking)\n  commands(commands: Command[]): CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>;\n  commands(\n    ...commands: Command[]\n  ): CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>;\n\n  /**\n   * Register's a configuration provider for the CLI. See {@link ConfigurationProviders} for built-in providers.\n   *\n   * @param provider Provider to register.\n   */\n  config(\n    provider: ConfigurationFiles.AnyConfigProvider<TArgs>\n  ): CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>;\n\n  /**\n   * Updates configuration by routing each key to its owning provider.\n   *\n   * @param values Partial configuration to write.\n   */\n  updateConfig(values: Partial<TArgs>): Promise<void>;\n  /**\n   * Updates configuration via an updater function. The current merged\n   * configuration is passed via a proxy that tracks which properties are set.\n   * Only properties set during the callback are written back.\n   *\n   * @param updater Function that receives the current config and mutates it.\n   */\n  updateConfig(\n    updater: ConfigurationFiles.ConfigUpdater<TArgs>\n  ): Promise<void>;\n\n  /**\n   * Enables the ability to run CLI commands that contain subcommands as an interactive shell.\n   * This presents as a small shell that only knows the current command and its subcommands.\n   * Any flags already consumed by the command will be passed to every subcommand invocation.\n   */\n  enableInteractiveShell(): CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>;\n\n  /**\n   * Registers a custom global error handler for the CLI. This handler will be called when an error is thrown\n   * during the execution of the CLI and not otherwise handled. Error handlers should re-throw the error if they\n   * cannot handle it, s.t. the next error handler can attempt to handle it.\n   *\n   * @param handler Typically called with an Error object, but you should be prepared to handle any type of error.\n   * @param actions Actions that can be taken by the error handler. Prefer using these over process.exit for better support of interactive shells.\n   */\n  errorHandler(\n    handler: ErrorHandler\n  ): CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>;\n\n  /**\n   * Registers a prompt provider for interactive option fulfillment.\n   * Multiple providers can be registered. Filtered providers are checked first\n   * (in registration order), then fallback providers (no filter).\n   *\n   * @param provider The prompt provider to register.\n   */\n  withPromptProvider(\n    provider: PromptProvider\n  ): CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>;\n\n  /**\n   * Registers a new option for the CLI command. This option will be accessible\n   * within the command handler, as well as any subcommands.\n   *\n   * @param name The name of the option.\n   * @param config Configuration for the option. See {@link UnknownOptionConfig}.\n   * @returns Updated CLI instance with the new option registered.\n   */\n  // Object option overload - must come first for proper contextual typing\n  // Uses direct ObjectOptionConfig type (not `extends`) to ensure TypeScript\n  // infers TProps from `properties` BEFORE evaluating the coerce callback type\n  option<\n    TOption extends string,\n    TCoerce,\n    const TProps extends Record<string, { type: string }>\n  >(\n    name: TOption,\n    config: ObjectOptionConfig<TCoerce, TProps> & { prompt?: PromptOptionConfig<TArgs>; completion?: OptionCompletionCallback<TArgs> }\n  ): CLI<\n    Expand<TArgs &\n      MakeUndefinedPropertiesOptional<{\n        [key in TOption]: WithOptional<\n          unknown extends TCoerce ? ResolveProperties<TProps> : TCoerce,\n          ObjectOptionConfig<TCoerce, TProps>\n        >;\n      }>>,\n    THandlerReturn,\n    TChildren,\n    TParent,\n    TProviders\n  >;\n  // String option overload\n  option<\n    TOption extends string,\n    const TConfig extends StringOptionConfig<any, any>\n  >(\n    name: TOption,\n    config: TConfig & { prompt?: PromptOptionConfig<TArgs>; completion?: OptionCompletionCallback<TArgs> }\n  ): CLI<\n    Expand<TArgs &\n      MakeUndefinedPropertiesOptional<{\n        [key in TOption]: OptionConfigToType<TConfig>;\n      }>>,\n    THandlerReturn,\n    TChildren,\n    TParent,\n    TProviders\n  >;\n  // Number option overload\n  option<\n    TOption extends string,\n    const TConfig extends NumberOptionConfig<any, any>\n  >(\n    name: TOption,\n    config: TConfig & { prompt?: PromptOptionConfig<TArgs>; completion?: OptionCompletionCallback<TArgs> }\n  ): CLI<\n    Expand<TArgs &\n      MakeUndefinedPropertiesOptional<{\n        [key in TOption]: OptionConfigToType<TConfig>;\n      }>>,\n    THandlerReturn,\n    TChildren,\n    TParent,\n    TProviders\n  >;\n  // Boolean option overload\n  option<\n    TOption extends string,\n    const TConfig extends BooleanOptionConfig<any, any>\n  >(\n    name: TOption,\n    config: TConfig & { prompt?: PromptOptionConfig<TArgs>; completion?: OptionCompletionCallback<TArgs> }\n  ): CLI<\n    Expand<TArgs &\n      MakeUndefinedPropertiesOptional<{\n        [key in TOption]: OptionConfigToType<TConfig>;\n      }>>,\n    THandlerReturn,\n    TChildren,\n    TParent,\n    TProviders\n  >;\n  // Array option overload\n  option<\n    TOption extends string,\n    const TConfig extends ArrayOptionConfig<any, any>\n  >(\n    name: TOption,\n    config: TConfig & { prompt?: PromptOptionConfig<TArgs>; completion?: OptionCompletionCallback<TArgs> }\n  ): CLI<\n    Expand<TArgs &\n      MakeUndefinedPropertiesOptional<{\n        [key in TOption]: OptionConfigToType<TConfig>;\n      }>>,\n    THandlerReturn,\n    TChildren,\n    TParent,\n    TProviders\n  >;\n  // OneOf option overload\n  option<\n    TOption extends string,\n    const TConfig extends OneOfOptionConfig<any>\n  >(\n    name: TOption,\n    config: TConfig & { prompt?: PromptOptionConfig<TArgs>; completion?: OptionCompletionCallback<TArgs> }\n  ): CLI<\n    Expand<TArgs &\n      MakeUndefinedPropertiesOptional<{\n        [key in TOption]: OptionConfigToType<TConfig>;\n      }>>,\n    THandlerReturn,\n    TChildren,\n    TParent,\n    TProviders\n  >;\n  // Generic fallback overload\n  option<\n    TOption extends string,\n    const TOptionConfig extends OptionConfig<any, any, any>\n  >(\n    name: TOption,\n    config: TOptionConfig & { prompt?: PromptOptionConfig<TArgs>; completion?: OptionCompletionCallback<TArgs> }\n  ): CLI<\n    Expand<TArgs &\n      MakeUndefinedPropertiesOptional<{\n        [key in TOption]: OptionConfigToType<TOptionConfig>;\n      }>>,\n    THandlerReturn,\n    TChildren,\n    TParent,\n    TProviders\n  >;\n\n  /**\n   * Registers a new positional argument for the CLI command. This argument will be accessible\n   * within the command handler, as well as any subcommands.\n   * @param name The name of the positional argument.\n   * @param config Configuration for the positional argument. See {@link UnknownOptionConfig}.\n   * @returns Updated CLI instance with the new positional argument registered.\n   */\n  // Object option overload - must come first for proper contextual typing\n  // Uses direct ObjectOptionConfig type (not `extends`) to ensure TypeScript\n  // infers TProps from `properties` BEFORE evaluating the coerce callback type\n  positional<\n    TOption extends string,\n    TCoerce,\n    const TProps extends Record<string, { type: string }>\n  >(\n    name: TOption,\n    config: ObjectOptionConfig<TCoerce, TProps> & { prompt?: PromptOptionConfig<TArgs>; completion?: OptionCompletionCallback<TArgs> }\n  ): CLI<\n    Expand<TArgs &\n      MakeUndefinedPropertiesOptional<{\n        [key in TOption]: WithOptional<\n          unknown extends TCoerce ? ResolveProperties<TProps> : TCoerce,\n          ObjectOptionConfig<TCoerce, TProps>\n        >;\n      }>>,\n    THandlerReturn,\n    TChildren,\n    TParent,\n    TProviders\n  >;\n  // String option overload\n  positional<\n    TOption extends string,\n    const TConfig extends StringOptionConfig<any, any>\n  >(\n    name: TOption,\n    config: TConfig & { prompt?: PromptOptionConfig<TArgs>; completion?: OptionCompletionCallback<TArgs> }\n  ): CLI<\n    Expand<TArgs &\n      MakeUndefinedPropertiesOptional<{\n        [key in TOption]: OptionConfigToType<TConfig>;\n      }>>,\n    THandlerReturn,\n    TChildren,\n    TParent,\n    TProviders\n  >;\n  // Number option overload\n  positional<\n    TOption extends string,\n    const TConfig extends NumberOptionConfig<any, any>\n  >(\n    name: TOption,\n    config: TConfig & { prompt?: PromptOptionConfig<TArgs>; completion?: OptionCompletionCallback<TArgs> }\n  ): CLI<\n    Expand<TArgs &\n      MakeUndefinedPropertiesOptional<{\n        [key in TOption]: OptionConfigToType<TConfig>;\n      }>>,\n    THandlerReturn,\n    TChildren,\n    TParent,\n    TProviders\n  >;\n  // Boolean option overload\n  positional<\n    TOption extends string,\n    const TConfig extends BooleanOptionConfig<any, any>\n  >(\n    name: TOption,\n    config: TConfig & { prompt?: PromptOptionConfig<TArgs>; completion?: OptionCompletionCallback<TArgs> }\n  ): CLI<\n    Expand<TArgs &\n      MakeUndefinedPropertiesOptional<{\n        [key in TOption]: OptionConfigToType<TConfig>;\n      }>>,\n    THandlerReturn,\n    TChildren,\n    TParent,\n    TProviders\n  >;\n  // Array option overload\n  positional<\n    TOption extends string,\n    const TConfig extends ArrayOptionConfig<any, any>\n  >(\n    name: TOption,\n    config: TConfig & { prompt?: PromptOptionConfig<TArgs>; completion?: OptionCompletionCallback<TArgs> }\n  ): CLI<\n    Expand<TArgs &\n      MakeUndefinedPropertiesOptional<{\n        [key in TOption]: OptionConfigToType<TConfig>;\n      }>>,\n    THandlerReturn,\n    TChildren,\n    TParent,\n    TProviders\n  >;\n  // Generic fallback overload\n  positional<\n    TOption extends string,\n    const TOptionConfig extends OptionConfig<any, any, any>\n  >(\n    name: TOption,\n    config: TOptionConfig & { prompt?: PromptOptionConfig<TArgs>; completion?: OptionCompletionCallback<TArgs> }\n  ): CLI<\n    Expand<TArgs &\n      MakeUndefinedPropertiesOptional<{\n        [key in TOption]: OptionConfigToType<TOptionConfig>;\n      }>>,\n    THandlerReturn,\n    TChildren,\n    TParent,\n    TProviders\n  >;\n\n  /**\n   * Adds support for reading CLI options from environment variables.\n   * @param prefix The prefix to use when looking up environment variables. Defaults to the command name.\n   */\n  env(prefix?: string): CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>;\n\n  env(options: EnvOptionConfig): CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>;\n\n  /**\n   * Sets up localization for option keys and other text.\n   * When localization is enabled, option keys will be displayed in the specified locale in help text and documentation,\n   * and both the default and localized keys will be accepted when parsing arguments.\n   *\n   * @param dictionary The localization dictionary mapping keys to their translations\n   * @param locale The target locale (defaults to system locale if not provided)\n   * @returns Updated CLI instance for chaining\n   *\n   * @example\n   * ```ts\n   * cli('myapp')\n   *   .localize({\n   *     name: { default: 'name', 'es-ES': 'nombre' },\n   *     port: { default: 'port', 'es-ES': 'puerto' }\n   *   }, 'es-ES')\n   *   .option('name', { type: 'string' })\n   *   .option('port', { type: 'number' });\n   * ```\n   */\n  localize(\n    dictionary: LocalizationDictionary,\n    locale?: string\n  ): CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>;\n  /**\n   * Sets up localization using a custom function for translating keys.\n   * This allows integration with existing localization libraries like i18next.\n   *\n   * @param fn A function that takes a key and returns its localized value\n   * @returns Updated CLI instance for chaining\n   *\n   * @example\n   * ```ts\n   * import i18next from 'i18next';\n   *\n   * cli('myapp')\n   *   .localize((key) => i18next.t(key))\n   *   .option('name', { type: 'string' })\n   *   .option('port', { type: 'number' });\n   * ```\n   */\n  localize(\n    fn: LocalizationFunction\n  ): CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>;\n\n  /**\n   * Sets a group of options as mutually exclusive. If more than one option is provided, there will be a validation error.\n   * @param options The options that should be mutually exclusive.\n   */\n  conflicts(\n    ...options: [string, string, ...string[]]\n  ): CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>;\n\n  /**\n   * Sets a group of options as mutually inclusive. If one option is provided, all other options must also be provided.\n   * @param option The option that implies the other options.\n   * @param impliedOptions The options which become required when the option is provided.\n   */\n  implies(\n    option: string,\n    ...impliedOptions: string[]\n  ): CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>;\n\n  /**\n   * Requires a command to be provided when executing the CLI. Useful if your parent command\n   * cannot be executed on its own.\n   * @returns Updated CLI instance.\n   */\n  demandCommand(): CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>;\n\n  /**\n   * Enables or disables strict mode. When strict mode is enabled, the parser throws a validation error\n   * when unmatched arguments are encountered. Unmatched arguments are those that don't match any\n   * configured option or positional argument.\n   * @param enable Whether to enable strict mode. Defaults to true.\n   * @returns Updated CLI instance.\n   */\n  strict(enable?: boolean): CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>;\n\n  /**\n   * Sets the usage text for the CLI. This text will be displayed in place of the default usage text\n   * @param usageText Text displayed in place of the default usage text for `--help` and in generated docs.\n   */\n  usage(usageText: string): CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>;\n\n  /**\n   * Marks this command as hidden so it is omitted from help output, generated documentation,\n   * and shell completion suggestions. Useful when composing reusable builders that need to\n   * register internal or experimental commands without exposing them to end users.\n   * @param hidden Whether the command should be hidden. Defaults to `true`.\n   */\n  hidden(hidden?: boolean): CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>;\n\n  /**\n   * Sets the description for the CLI. This text will be displayed in the help text and generated docs.\n   * @param examples Examples to display in the help text and generated docs.\n   */\n  examples(\n    ...examples: string[]\n  ): CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>;\n\n  /**\n   * Allows overriding the version displayed when passing `--version`. Defaults to crawling\n   * the file system to get the package.json of the currently executing command.\n   * @param override\n   */\n  version(override?: string): CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>;\n\n  /**\n   * Prints help text to stdout.\n   */\n  printHelp(): void;\n\n  group({\n    label,\n    keys,\n    sortOrder,\n  }: {\n    label: string;\n    keys: (keyof TArgs)[];\n    sortOrder?: number;\n  }): CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>;\n  group(\n    label: string,\n    keys: (keyof TArgs)[]\n  ): CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>;\n\n  middleware<TArgs2>(\n    callback: MiddlewareFunction<TArgs, TArgs2>\n  ): CLI<\n    TArgs2 extends void ? TArgs : Expand<TArgs & TArgs2>,\n    THandlerReturn,\n    TChildren,\n    TParent,\n    TProviders\n  >;\n\n  /**\n   * Registers a handler for this command. Fluent alternative to passing\n   * `handler` in the command configuration object.\n   *\n   * @param fn Handler function receiving parsed args and command context.\n   * @returns Updated CLI instance with the handler return type updated.\n   *\n   * @example\n   * ```ts\n   * cli('serve')\n   *   .option('port', { type: 'number', default: 3000 })\n   *   .handler((args) => {\n   *     console.log(`Listening on port ${args.port}`);\n   *   })\n   *   .forge();\n   * ```\n   */\n  handler<R>(\n    fn: (\n      args: TArgs,\n      context: CLIHandlerContext<TChildren, TParent>\n    ) => R\n  ): CLI<TArgs, R, TChildren, TParent, TProviders>;\n\n  /**\n   * Registers a dependency injection provider under a unique key.\n   * The value (or factory result) is accessible via `inject()` within command handlers.\n   *\n   * Three forms are supported:\n   * - **Eager value**: `provide('key', value)` — stored as-is.\n   * - **ExecutionScope factory**: `provide('key', { factory: (args) => value })` — called per invocation with parsed args.\n   * - **Global factory**: `provide('key', { factory: () => value, lifetime: 'global' })` — called once and cached.\n   *\n   * Duplicate keys on the same command instance throw an error.\n   */\n  // Global factory (no args, must specify lifetime: 'global')\n  provide<TName extends string, T>(\n    key: TName & (TName extends keyof TProviders ? never : TName),\n    config: GlobalProviderConfig<T>,\n  ): CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders & { [K in TName]: T }>;\n\n  // ExecutionScope factory (receives args)\n  provide<TName extends string, T>(\n    key: TName & (TName extends keyof TProviders ? never : TName),\n    config: ProviderConfig<T, TArgs>,\n  ): CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders & { [K in TName]: T }>;\n\n  // Eager value\n  provide<TName extends string, T>(\n    key: TName & (TName extends keyof TProviders ? never : TName),\n    value: T,\n  ): CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders & { [K in TName]: T }>;\n\n  /**\n   * Registers an init hook that runs before command resolution.\n   * Init hooks receive partially-parsed args (from currently-registered options)\n   * and can modify the CLI (register commands, options, middleware) before the\n   * full parse runs. This enables plugin loading from config files.\n   *\n   * @param callback Async function receiving (args, cli). Mutate cli to add commands/options.\n   */\n  init(\n    callback: (\n      cli: CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>,\n      args: TArgs\n    ) => Promise<void> | void\n  ): CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>;\n\n  /**\n   * Enables shell completion for this CLI.\n   * When called at the root level (no parent), also registers:\n   *   - A hidden `--get-completions` flag for runtime completion\n   *   - A `completion` subcommand for installing shell scripts\n   *\n   * At any level, stores the optional callback for custom completion suggestions.\n   *\n   * @param callback Optional custom completion callback for this command level.\n   */\n  completion(\n    callback?: CompletionCallback<TArgs>\n  ): CLI<TArgs, THandlerReturn, TChildren, TParent, TProviders>;\n\n  /**\n   * Parses argv and executes the CLI\n   * @param args argv. Defaults to process.argv.slice(2)\n   * @returns Promise that resolves when the handler completes.\n   */\n  forge(args?: string[]): Promise<TArgs>;\n\n  /**\n   * Returns the typed children commands registered with this CLI.\n   * The return type depends on the commands registered via `command()` or `commands()`.\n   *\n   * @example\n   * ```ts\n   * const app = cli('app')\n   *   .command('init', { ... })\n   *   .command('build', { ... });\n   *\n   * const children = app.getChildren();\n   * // children.init and children.build are typed CLI instances\n   * const initHandler = children.init.getHandler();\n   * ```\n   */\n  getChildren(): TChildren;\n\n  /**\n   * Returns the parent CLI instance, if this command was registered as a subcommand.\n   * Returns undefined for root-level CLI instances.\n   *\n   * @example\n   * ```ts\n   * const build = cli('build', {\n   *   handler: (args, ctx) => {\n   *     const parent = ctx.command.getParent();\n   *     const siblings = parent?.getChildren();\n   *     // Access sibling commands\n   *   }\n   * });\n   * ```\n   */\n  getParent(): TParent;\n\n  /**\n   * Returns the {@link CommandContext} for the currently executing command,\n   * inferred from this CLI instance.\n   *\n   * This is a shorthand for `getCommandContext(this)` — it avoids the\n   * separate `import { getCommandContext } from 'cli-forge'` when you\n   * already have a reference to the CLI. Both forms are equivalent in\n   * type inference and runtime safety: the CLI instance is validated\n   * against the active command chain, so passing a CLI that isn't\n   * running (a sibling, an unrelated app) throws.\n   *\n   * Must be called from within a command handler — not during builders\n   * or middleware.\n   *\n   * @example\n   * ```ts\n   * const app = cli('app')\n   *   .provide('db', { factory: () => connectDb() })\n   *   .command('migrate', {\n   *     handler: () => {\n   *       const db = app.getContext().inject('db');\n   *       return db.runMigrations();\n   *     },\n   *   });\n   * ```\n   */\n  // Uses `ProvidersFromChain<TProviders, TParent>` rather than\n  // `ProvidersOf<CLI<TArgs, ..., TParent, TProviders>>` so this signature\n  // doesn't re-wrap `CLI`'s own type parameters in a `CLI<...>` while\n  // the `CLI` interface is still being constructed. The chain-walk\n  // recursion then stays in conditional-type space, where TypeScript\n  // evaluates it lazily at call sites — no self-reference to trip.\n  getContext(): CommandContext<\n    TArgs,\n    ProvidersFromChain<TProviders, TParent>,\n    TChildren\n  >;\n\n  /**\n   * Returns a programmatic SDK for invoking this CLI and its subcommands.\n   * The SDK provides typed function calls instead of argv parsing.\n   *\n   * @example\n   * ```ts\n   * const myCLI = cli('my-app')\n   *   .option('verbose', { type: 'boolean' })\n   *   .command('build', {\n   *     builder: (cmd) => cmd.option('watch', { type: 'boolean' }),\n   *     handler: (args) => ({ success: true, files: ['a.js'] })\n   *   });\n   *\n   * const sdk = myCLI.sdk();\n   *\n   * // Invoke root command (if it has a handler)\n   * await sdk({ verbose: true });\n   *\n   * // Invoke subcommand with typed args\n   * const result = await sdk.build({ watch: true });\n   * console.log(result.files);       // ['a.js']\n   * console.log(result.$args.watch); // true\n   *\n   * // Use CLI-style args for -- support\n   * await sdk.build(['--watch', '--', 'extra-arg']);\n   * ```\n   *\n   * @returns An SDK object that is callable (if this command has a handler)\n   *          and has properties for each subcommand.\n   */\n  sdk(): SDKCommand<TArgs, THandlerReturn, TChildren>;\n\n  /**\n   * Returns the builder function for this command as a composable builder.\n   * The returned function can be used with `chain` to compose multiple builders.\n   *\n   * @example\n   * ```ts\n   * const siblings = args.getParent().getChildren();\n   * const withBuildArgs = siblings.build.getBuilder()!;\n   * const withServeArgs = siblings.serve.getBuilder()!;\n   * return chain(args, withBuildArgs, withServeArgs);\n   * ```\n   */\n  getBuilder():\n    | (<\n        TInit extends ParsedArgs,\n        TInitHandlerReturn,\n        TInitChildren,\n        TInitParent,\n        TInitProviders\n      >(\n        parser: CLI<TInit, TInitHandlerReturn, TInitChildren, TInitParent, TInitProviders>\n      ) => CLI<\n        TInit & TArgs,\n        TInitHandlerReturn,\n        TInitChildren & TChildren,\n        TInitParent,\n        TInitProviders\n      >)\n    | undefined;\n  getHandler():\n    | ((args: Omit<TArgs, keyof ParsedArgs>) => THandlerReturn)\n    | undefined;\n}\n\nexport interface CLIHandlerContext<TChildren = {}, TParent = any> {\n  command: CLI<any, any, TChildren, TParent, any>;\n}\n\n/**\n * Extracts the TChildren type parameter from a CLI type.\n */\nexport type ExtractCLIChildren<T> = T extends CLI<any, any, infer C, any, any>\n  ? C\n  : {};\n\n/**\n * Represents the configuration needed to create a CLI command.\n */\nexport interface CLICommandOptions<\n  /**\n   * The type of the arguments that are already registered before `builder` is invoked.\n   */\n  TInitial extends ParsedArgs,\n  /**\n   * The type of the arguments that are registered after `builder` is invoked, and the type that is passed to the handler.\n   */\n  TArgs extends TInitial = TInitial,\n  THandlerReturn = void | Promise<void>,\n  /**\n   * The children commands that exist before the builder runs.\n   */\n\n  TInitialChildren = {},\n  TParent = any,\n  /**\n   * The children commands after the builder runs (includes TInitialChildren plus any added by builder).\n   */\n\n  TChildren = {},\n  /**\n   * The providers registered inside the builder via `.provide()`. Inferred\n   * from the builder's return type so that child-overrides-parent semantics\n   * are visible in `getCommandContext(child).inject()`.\n   */\n  TChildProviders = {}\n> {\n  /**\n   * If set the command will be registered under the provided name and any aliases.\n   *\n   * This can be useful if a command should be executed under more than one name, e.g. `npx my-cli` and `npx my-cli hello`.\n   */\n  alias?: string[];\n\n  /**\n   * The command description. This will be displayed in the help text and generated docs.\n   */\n  description?: string;\n\n  /**\n   * The command builder. This function is called before the command is executed, and is used to register options and positional parameters.\n   * @param parser The parser instance to register options and positionals with.\n   */\n  // Note: Builder uses 'any' for THandlerReturn to avoid inference conflicts with the handler.\n  // The handler's return type is inferred independently from the handler function itself.\n  builder?: (\n    parser: CLI<TInitial, any, TInitialChildren, TParent, {}>\n  ) => CLI<TArgs, any, TChildren, any, TChildProviders>;\n\n  /**\n   * The command handler. This function is called when the command is executed.\n   * @param args The parsed arguments.\n   * @param context Context for the handler. Contains the command instance.\n   */\n  handler?: (\n    args: NoInfer<TArgs>,\n    context: CLIHandlerContext<NoInfer<TChildren>, TParent>\n  ) => THandlerReturn;\n\n  /**\n   * The usage text for the command. This text will be displayed in place of the default usage text in the help text and generated docs.\n   */\n  usage?: string;\n\n  /**\n   * Examples to display in the help text and generated docs.\n   */\n  examples?: string[];\n\n  /**\n   * Hides the command from the help text and generated docs. Useful primarily for experimental or internal commands.\n   */\n  hidden?: boolean;\n\n  /**\n   * The epilogue text for the command. This text will be displayed at the end of the help text and generated docs.\n   */\n  epilogue?: string;\n}\n\nexport type Command<\n  TInitial extends ParsedArgs = any,\n  TArgs extends TInitial = TInitial,\n  TCommandName extends string = string,\n  THandlerReturn = void\n> =\n  | ({\n      name: TCommandName;\n    } & CLICommandOptions<TInitial, TArgs, THandlerReturn>)\n  | CLI<TArgs, THandlerReturn>;\n\n/**\n * Error Handler for CLI applications. Error handlers should re-throw the error if they cannot handle it.\n *\n * @param e The error that was thrown.\n * @param actions Actions that can be taken by the error handler. Prefer using these over process.exit for better support of interactive shells.\n */\nexport type ErrorHandler = (\n  e: unknown,\n  actions: {\n    /**\n     * Exits the process immediately.\n     * @param code\n     */\n    exit: (code?: number) => void;\n  }\n) => void;\n\n/** Type alias for a CLI instance with any type parameters. Use in value positions where you need to accept any CLI. */\nexport type AnyCLI = CLI<any, any, any, any, any>;\n\n/**\n * Base CLI constraint for generic functions. Uses `ParsedArgs` instead of `any`\n * for `TArgs` so that method return types (like `.option()`) compute correctly\n * through `chain()`. Use this as the bound in `<T extends UnknownCLI>`.\n *\n * @example\n * ```ts\n * function withVerbose<T extends UnknownCLI>(cli: T) {\n *   return cli.option('verbose', { type: 'boolean' });\n * }\n * ```\n */\nexport type UnknownCLI = CLI<ParsedArgs, any, any, any, any>;\n\nexport type MiddlewareFunction<TArgs extends ParsedArgs, TArgs2> = (\n  args: TArgs\n) => TArgs2 | Promise<TArgs2>;\n\n// ============================================================================\n// SDK Types\n// ============================================================================\n\n/**\n * Result type that conditionally includes $args.\n * Only attaches $args when result is an object type.\n * Uses `Awaited<T>` to handle async handlers that return `Promise<U>`.\n */\nexport type SDKResult<TArgs, THandlerReturn> =\n  Awaited<THandlerReturn> extends object\n    ? Awaited<THandlerReturn> & { $args: TArgs }\n    : Awaited<THandlerReturn>;\n\n/**\n * The callable signature for a command with a handler.\n * Supports both object-style args (typed, skips validation) and\n * string array args (CLI-style, full validation pipeline).\n */\nexport type SDKInvokable<TArgs, THandlerReturn> = {\n  /**\n   * Invoke the command with typed object args.\n   * Skips validation (TypeScript handles it), applies defaults, runs middleware.\n   */\n  (args?: Partial<Omit<TArgs, 'unmatched' | '--'>>): Promise<\n    SDKResult<TArgs, THandlerReturn>\n  >;\n  /**\n   * Invoke the command with CLI-style string args.\n   * Runs full pipeline: parse → validate → middleware → handler.\n   * Use this when you need to pass `--` extra args.\n   */\n  (args: string[]): Promise<SDKResult<TArgs, THandlerReturn>>;\n};\n\n/**\n * Recursively builds SDK type from TChildren.\n * Each child command becomes a property on the SDK object.\n */\nexport type SDKChildren<TChildren> = {\n  [K in keyof TChildren]: TChildren[K] extends CLI<\n    infer A,\n    infer R,\n    infer C,\n\n    infer _P,\n    infer _Providers\n  >\n    ? SDKCommand<A, R, C>\n    : never;\n};\n\n/**\n * A single SDK command - callable if it has a handler, with nested children as properties.\n * Container commands (no handler) are not callable but still provide access to children.\n */\nexport type SDKCommand<TArgs, THandlerReturn, TChildren> =\n   \n  // THandlerReturn extends void | undefined\n  // ? SDKChildren<TChildren> // No handler = just children (not callable)\n  SDKInvokable<TArgs, THandlerReturn> & SDKChildren<TChildren>;\n\n/**\n * Constructs a CLI instance. See {@link CLI} for more information.\n * @param name Name for the top level CLI\n * @param rootCommandConfiguration Configuration used when running the bare CLI. e.g. npx my-cli, rather than npx my-cli [cmd]\n * @returns A {@link CLI} instance.\n */\nexport function cli<\n  TArgs extends ParsedArgs,\n  THandlerReturn = void,\n   \n  TChildren = {},\n  TName extends string = string\n>(\n  name: TName,\n  rootCommandConfiguration?: CLICommandOptions<\n    ParsedArgs,\n    TArgs,\n    THandlerReturn,\n    {},\n    any,\n    TChildren\n  >\n) {\n  return new InternalCLI(name, rootCommandConfiguration as any) as any as CLI<\n    TArgs,\n    THandlerReturn,\n    TChildren,\n    undefined,\n    {}\n  >;\n}\n\nexport default cli;\n"],"mappings":";;;;;;;;AAuzCA,SAAgB,IAOd,MACA,0BAQA;AACA,QAAO,IAAI,YAAY,MAAM,yBAAgC"}