import { CommandContext, ProvidersFromChain } from "./context.mjs";
import { CompletionCallback, OptionCompletionCallback } from "./completion-types.mjs";
import { PromptOptionConfig, PromptProvider } from "./prompt-types.mjs";
import { InternalCLI } from "./internal-cli.mjs";
import { ArrayOptionConfig, BooleanOptionConfig, ConfigurationFiles, EnvOptionConfig, Expand, LocalizationDictionary, LocalizationFunction, MakeUndefinedPropertiesOptional, NumberOptionConfig, ObjectOptionConfig, OneOfOptionConfig, OptionConfig, OptionConfigToType, ParsedArgs, ResolveProperties, StringOptionConfig, WithOptional } from "@cli-forge/parser";

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