burgee/yargs/v17

import Yargs17 from 'burgee/yargs/v17';
import { applyExtends, argsert, camelCase, … } from 'burgee/yargs/v17';

function applyExtends(config: Record<string, any>, cwd: string, mergeExtends?: boolean): Record<string, any>;

function argsert(arg1: string | any[], arg2?: any, arg3?: number): void;

function camelCase(str: string): string;

function decamelize(str: string, joinString?: string): string;

function hideBin(argv: string[]): string[];

function isPromise(maybePromise: any): maybePromise is Promise<any>;

function isYargsInstance(y: any): y is YargsInstance;

function looksLikeNumber(x: any): boolean;

function objFilter<T extends object>(original?: T, filter?: (k: string, v: any) => boolean): T;

function parseCommand(cmd: string): ParsedCommand;

class YargsInstance {
    #private;
    $0: string;
    argv?: any;
    customScriptName: boolean;
    parsed: any;
    constructor(processArgs: string | string[] | undefined, cwd: string, parentRequire: NodeJS.Require | undefined, shim: PlatformShim);
    addHelpOpt(opt?: string | false, msg?: string): this;
    help(opt?: string | false, msg?: string): this;
    addShowHiddenOpt(opt?: string | false, msg?: string): this;
    showHidden(opt?: string | false, msg?: string): this;
    alias(key: string | string[] | Record<string, string | string[]>, value?: string | string[]): this;
    array(keys: string | string[]): this;
    boolean(keys: string | string[]): this;
    check(f: (argv: any, options: Options) => any, global?: boolean): this;
    choices(key: string | string[] | Record<string, any>, value?: any): this;
    coerce(keys: string | string[] | Record<string, (arg: any) => any>, value?: (arg: any) => any): this;
    conflicts(key1: string | Record<string, string | string[]>, key2?: string | string[]): this;
    config(key?: string | string[] | Record<string, any>, msg?: string | ((path: string) => any), parseFn?: (path: string) => any): this;
    completion(cmd?: string, desc?: string | false | CompletionFunction, fn?: CompletionFunction): this;
    command(cmd: any, description?: any, builder?: any, handler?: any, middlewares?: Middleware[], deprecated?: boolean | string): this;
    commands(cmd: any, description?: any, builder?: any, handler?: any, middlewares?: Middleware[], deprecated?: boolean | string): this;
    commandDir(dir: string, opts?: any): this;
    count(keys: string | string[]): this;
    default(key: string | string[] | Record<string, any>, value?: any, defaultDescription?: string): this;
    defaults(key: string | string[] | Record<string, any>, value?: any, defaultDescription?: string): this;
    demandCommand(min?: number, max?: number | string | null, minMsg?: string | null, maxMsg?: string | null): this;
    demand(keys: string | string[] | number | Record<string, any>, max?: number | string | string[] | boolean, msg?: string | boolean): this;
    demandOption(keys: string | string[] | Record<string, string | undefined>, msg?: string): this;
    deprecateOption(option: string, message?: string | boolean): this;
    describe(keys: string | string[] | Record<string, string>, description?: string): this;
    detectLocale(detect: boolean): this;
    env(prefix?: string | false): this;
    epilogue(msg: string): this;
    epilog(msg: string): this;
    example(cmd: string | [string, string?][], description?: string): this;
    exit(code: number, err?: YError | string): void;
    exitProcess(enabled?: boolean): this;
    fail(f: FailureFunction | boolean): this;
    getAliases(): Record<string, string[]>;
    getCompletion(args: string[], done?: (err: Error | null, completions: string[] | undefined) => void): Promise<string[] | void>;
    getDemandedOptions(): Record<string, string | undefined>;
    getDemandedCommands(): Options['demandedCommands'];
    getDeprecatedOptions(): Options['deprecatedOptions'];
    getDetectLocale(): boolean;
    getExitProcess(): boolean;
    getGroups(): Record<string, string[]>;
    getHelp(): Promise<string>;
    getOptions(): Options;
    getStrict(): boolean;
    getStrictCommands(): boolean;
    getStrictOptions(): boolean;
    global(globals: string | string[], global?: boolean): this;
    group(opts: string | string[], groupName: string): this;
    hide(key: string): this;
    implies(key: string | Record<string, any>, value?: number | string | string[]): this;
    locale(locale?: string): this | string;
    middleware(callback: Middleware | Middleware[], applyBeforeValidation?: boolean, global?: boolean): this;
    nargs(key: string | string[] | Record<string, number>, value?: number): this;
    normalize(keys: string | string[]): this;
    number(keys: string | string[]): this;
    option(key: string | Record<string, any>, opt?: any): this;
    options(key: string | Record<string, any>, opt?: any): this;
    parse(args?: string | string[], shortCircuit?: object | ParseCallback | boolean, _parseFn?: ParseCallback): any;
    parseAsync(args?: string | string[], shortCircuit?: object | ParseCallback | boolean, _parseFn?: ParseCallback): Promise<any>;
    parseSync(args?: string | string[], shortCircuit?: object | ParseCallback | boolean, _parseFn?: ParseCallback): any;
    parserConfiguration(config: Record<string, any>): this;
    pkgConf(key: string, rootPath?: string): this;
    positional(key: string, opts: Record<string, any>): this;
    recommendCommands(recommend?: boolean): this;
    required(keys: string | string[] | number | Record<string, any>, max?: number | string | string[] | boolean, msg?: string | boolean): this;
    require(keys: string | string[] | number | Record<string, any>, max?: number | string | string[] | boolean, msg?: string | boolean): this;
    requiresArg(keys: string | string[] | Record<string, any>): this;
    showCompletionScript($0?: string, cmd?: string): this;
    showHelp(level?: 'error' | 'log' | ((message: string) => void)): this;
    scriptName(scriptName: string): this;
    showHelpOnFail(enabled?: string | boolean, message?: string): this;
    showVersion(level?: 'error' | 'log' | ((message: string) => void)): this;
    skipValidation(keys: string | string[]): this;
    strict(enabled?: boolean): this;
    strictCommands(enabled?: boolean): this;
    strictOptions(enabled?: boolean): this;
    string(keys: string | string[]): this;
    terminalWidth(): number | null;
    updateLocale(obj: Record<string, any>): this;
    updateStrings(obj: Record<string, any>): this;
    usage(msg: string | null, description?: string | false, builder?: any, handler?: any): this;
    usageConfiguration(config: Record<string, any>): this;
    version(opt?: string | false, msg?: string, ver?: string): this;
    wrap(cols: number | null | undefined): this;
    getInternalMethods(): {
        getCommandInstance: () => CommandInstance;
        getContext: () => Context;
        getHasOutput: () => boolean;
        getLoggerInstance: () => Logger;
        getParseContext: () => object;
        getParserConfiguration: () => Record<string, any>;
        getUsageConfiguration: () => Record<string, any>;
        getUsageInstance: () => UsageInstance;
        getValidationInstance: () => ValidationInstance;
        hasParseCallback: () => boolean;
        isGlobalContext: () => boolean;
        postProcess: (argv: any, populateDoubleDash: boolean, calledFromCommand: boolean, runGlobalMiddleware: boolean) => any;
        reset: (aliases?: Record<string, string[]>) => YargsInstance;
        runValidation: (aliases: Record<string, string[]>, positionalMap: Record<string, string[]>, parseErrors: Error | null, isDefaultCommand?: boolean) => (argv: any) => void;
        runYargsParserAndExecuteCommands: (args: string | string[] | null, shortCircuit?: boolean, calledFromCommand?: boolean, commandIndex?: number, helpOnly?: boolean) => any;
        setHasOutput: () => void;
        runHandler: (handler: (argv: any) => any, argv: any, original: string) => any;
    };
    /**
     * The manifest every surface reads (J7, J8). Projected on each access from what the
     * program registered; a command's builder is run on a scratch instance to learn its
     * options, exactly as yargs' own completion does. Plugin-contributed nodes are kept.
     */
    get manifest(): Manifest;
    /** burgee: declare what the command does to the world (N6); what exposes it as an MCP tool (N2). */
    effects(value: DeclaredEffects): this;
    /** Additive: plugins yargs never had. `preRun`/`postRun` fire around every handler. */
    use(plugin: Plugin): this;
    /**
     * Inject the streams and the exit for this instance (T1). Output goes to `stdout`/`stderr`
     * instead of the console, and `exit` receives an E1 code: OK for help and version, USAGE
     * for a validation failure, RUNTIME for a handler that threw.
     */
    burgee({ floor, ...seam }: BurgeeSeam): this;
}

class YError extends Error {
    constructor(msg?: string | null);
}

const Yargs17: typeof Yargs;

const shim: PlatformShim;

interface Argv<T = {}> {
    /**
     * Set key names as equivalent such that updates to a key will propagate to aliases and vice-versa.
     */
    alias<K1 extends keyof T, K2 extends string>(shortName: K1, longName: K2 | readonly K2[]): Argv<T & {
        [key in K2]: T[K1];
    }>;
    alias<K1 extends keyof T, K2 extends string>(shortName: K2, longName: K1 | readonly K1[]): Argv<T & {
        [key in K2]: T[K1];
    }>;
    alias(shortName: string | readonly string[], longName: string | readonly string[]): Argv<T>;
    alias(aliases: {
        [shortName: string]: string | readonly string[];
    }): Argv<T>;
    /**
     * Get the arguments as a plain old object.
     */
    argv: {
        [key in keyof Arguments<T> as key | CamelCaseKey<key>]: Arguments<T>[key];
    } | Promise<{
        [key in keyof Arguments<T> as key | CamelCaseKey<key>]: Arguments<T>[key];
    }>;
    /**
     * Tell the parser to interpret `key` as an array.
     * If `.array('foo')` is set, `--foo foo bar` will be parsed as `['foo', 'bar']` rather than as `'foo'`.
     * Also, if you use the option multiple times all the values will be flattened in one array so `--foo foo --foo bar` will be parsed as `['foo', 'bar']`
     */
    array<K extends keyof T>(key: K | readonly K[]): Argv<Omit<T, K> & {
        [key in K]: ToArray<T[key]>;
    }>;
    array<K extends string>(key: K | readonly K[]): Argv<T & {
        [key in K]: Array<string | number> | undefined;
    }>;
    /**
     * Interpret `key` as a boolean. If a non-flag option follows `key` in `process.argv`, that string won't get set as the value of `key`.
     */
    boolean<K extends keyof T>(key: K | readonly K[]): Argv<Omit<T, K> & {
        [key in K]: boolean | undefined;
    }>;
    boolean<K extends string>(key: K | readonly K[]): Argv<T & {
        [key in K]: boolean | undefined;
    }>;
    /**
     * Check that certain conditions are met in the provided arguments.
     * @param func Called with two arguments, the parsed `argv` hash and an array of options and their aliases.
     * If `func` throws or returns a non-truthy value, show the thrown error, usage information, and exit.
     * @param global Indicates whether `check()` should be enabled both at the top-level and for each sub-command.
     */
    check(func: (argv: Arguments<T>, aliases: {
        [alias: string]: string;
    }) => any, global?: boolean): Argv<T>;
    /**
     * Limit valid values for key to a predefined set of choices, given as an array or as an individual value.
     * If this method is called multiple times, all enumerated values will be merged together.
     * Choices are generally strings or numbers, and value matching is case-sensitive.
     */
    choices<K extends keyof T, C extends readonly any[]>(key: K, values: C): Argv<Omit<T, K> & {
        [key in K]: C[number] | undefined;
    }>;
    choices<K extends string, C extends readonly any[]>(key: K, values: C): Argv<T & {
        [key in K]: C[number] | undefined;
    }>;
    choices<C extends {
        [key: string]: readonly any[];
    }>(choices: C): Argv<Omit<T, keyof C> & {
        [key in keyof C]: C[key][number] | undefined;
    }>;
    /**
     * Provide a synchronous function to coerce or transform the value(s) given on the command line for `key`.
     */
    coerce<K extends keyof T, V>(key: K | readonly K[], func: (arg: any) => V): Argv<Omit<T, K> & {
        [key in K]: V | undefined;
    }>;
    coerce<K extends string, V>(key: K | readonly K[], func: (arg: any) => V): Argv<T & {
        [key in K]: V | undefined;
    }>;
    coerce<O extends {
        [key: string]: (arg: any) => any;
    }>(opts: O): Argv<Omit<T, keyof O> & {
        [key in keyof O]: ReturnType<O[key]> | undefined;
    }>;
    /**
     * Define the commands exposed by your application.
     * @param command Should be a string representing the command or an array of strings representing the command and its aliases.
     * @param description Use to provide a description for each command your application accepts (the values stored in `argv._`).
     * Set `description` to false to create a hidden command. Hidden commands don't show up in the help output and aren't available for completion.
     * @param [builder] Object to give hints about the options that your command accepts.
     * Can also be a function. This function is executed with a yargs instance, and can be used to provide advanced command specific help.
     *
     * Note that when `void` is returned, the handler `argv` object type will not include command-specific arguments.
     * @param [handler] Function, which will be executed with the parsed `argv` object.
     */
    command<U = T>(command: string | readonly string[], description: string, builder?: BuilderCallback<T, U>, handler?: (args: ArgumentsCamelCase<U>) => unknown, middlewares?: Array<MiddlewareFunction<U>>, deprecated?: boolean | string): Argv<T>;
    command<O extends {
        [key: string]: Options;
    }>(command: string | readonly string[], description: string, builder?: O, handler?: (args: ArgumentsCamelCase<InferredOptionTypes<O>>) => unknown, middlewares?: Array<MiddlewareFunction<O>>, deprecated?: boolean | string): Argv<T>;
    command<U = any>(command: string | readonly string[], description: string, module: CommandModule<T, U>): Argv<T>;
    command<U = T>(command: string | readonly string[], showInHelp: false, builder?: BuilderCallback<T, U>, handler?: (args: ArgumentsCamelCase<U>) => unknown, middlewares?: Array<MiddlewareFunction<U>>, deprecated?: boolean | string): Argv<T>;
    command<O extends {
        [key: string]: Options;
    }>(command: string | readonly string[], showInHelp: false, builder?: O, handler?: (args: ArgumentsCamelCase<InferredOptionTypes<O>>) => unknown): Argv<T>;
    command<U = any>(command: string | readonly string[], showInHelp: false, module: CommandModule<T, U>): Argv<T>;
    command<U = any>(module: CommandModule<T, U>): Argv<T>;
    command<U = any>(modules: Array<CommandModule<T, U>>): Argv<T>;
    /** Apply command modules from a directory relative to the module calling this method. */
    commandDir(dir: string, opts?: RequireDirectoryOptions): Argv<T>;
    /**
     * Enable bash/zsh-completion shortcuts for commands and options.
     * @param [cmd] When present in `argv._`, will result in the `.bashrc` or `.zshrc` completion script being outputted.
     * To enable bash/zsh completions, concat the generated script to your `.bashrc` or `.bash_profile` (or `.zshrc` for zsh).
     * @param [description] Provide a description in your usage instructions for the command that generates the completion scripts.
     * @param [func] Rather than relying on yargs' default completion functionality, which shiver me timbers is pretty awesome, you can provide your own completion method.
     */
    completion(): Argv<T>;
    completion(cmd: string, func?: AsyncCompletionFunction): Argv<T>;
    completion(cmd: string, func?: SyncCompletionFunction): Argv<T>;
    completion(cmd: string, func?: PromiseCompletionFunction): Argv<T>;
    completion(cmd: string, func?: FallbackCompletionFunction): Argv<T>;
    completion(cmd: string, description?: string | false, func?: AsyncCompletionFunction): Argv<T>;
    completion(cmd: string, description?: string | false, func?: SyncCompletionFunction): Argv<T>;
    completion(cmd: string, description?: string | false, func?: PromiseCompletionFunction): Argv<T>;
    completion(cmd: string, description?: string | false, func?: FallbackCompletionFunction): Argv<T>;
    /**
     * Tells the parser that if the option specified by `key` is passed in, it should be interpreted as a path to a JSON config file.
     * The file is loaded and parsed, and its properties are set as arguments.
     * Because the file is loaded using Node's require(), the filename MUST end in `.json` to be interpreted correctly.
     * @param [description] Provided to customize the config (`key`) option in the usage string.
     * @param [explicitConfigurationObject] An explicit configuration `object`
     */
    config(): Argv<T>;
    config(key: string | readonly string[], description?: string, parseFn?: (configPath: string) => object): Argv<T>;
    config(key: string | readonly string[], parseFn: (configPath: string) => object): Argv<T>;
    config(explicitConfigurationObject: object): Argv<T>;
    /**
     * Given the key `x` is set, the key `y` must not be set. `y` can either be a single string or an array of argument names that `x` conflicts with.
     */
    conflicts(key: string, value: string | readonly string[]): Argv<T>;
    conflicts(conflicts: {
        [key: string]: string | readonly string[];
    }): Argv<T>;
    /**
     * Interpret `key` as a boolean flag, but set its parsed value to the number of flag occurrences rather than `true` or `false`. Default value is thus `0`.
     */
    count<K extends keyof T>(key: K | readonly K[]): Argv<Omit<T, K> & {
        [key in K]: number;
    }>;
    count<K extends string>(key: K | readonly K[]): Argv<T & {
        [key in K]: number;
    }>;
    /**
     * Set `argv[key]` to `value` if no option was specified in `process.argv`.
     */
    default<K extends keyof T, V>(key: K, value: V, description?: string): Argv<Omit<T, K> & {
        [key in K]: V;
    }>;
    default<K extends string, V>(key: K, value: V, description?: string): Argv<T & {
        [key in K]: V;
    }>;
    default<D extends {
        [key: string]: any;
    }>(defaults: D, description?: string): Argv<Omit<T, keyof D> & D>;
    /**
     * @deprecated since version 6.6.0
     * Use '.demandCommand()' or '.demandOption()' instead
     */
    demand<K extends keyof T>(key: K | readonly K[], msg?: string | true): Argv<Defined<T, K>>;
    demand<K extends string>(key: K | readonly K[], msg?: string | true): Argv<T & {
        [key in K]: unknown;
    }>;
    demand(key: string | readonly string[], required?: boolean): Argv<T>;
    demand(positionals: number, msg: string): Argv<T>;
    demand(positionals: number, required?: boolean): Argv<T>;
    demand(positionals: number, max: number, msg?: string): Argv<T>;
    /**
     * @param key If is a string, show the usage information and exit if key wasn't specified in `process.argv`.
     * If is an array, demand each element.
     * @param msg If string is given, it will be printed when the argument is missing, instead of the standard error message.
     * @param demand Controls whether the option is demanded; this is useful when using .options() to specify command line parameters.
     */
    demandOption<K extends keyof T>(key: K | readonly K[], msg?: string | true): Argv<Defined<T, K>>;
    demandOption<K extends string>(key: K | readonly K[], msg?: string | true): Argv<T & {
        [key in K]: unknown;
    }>;
    demandOption(key: string | readonly string[], demand?: boolean): Argv<T>;
    /**
     * Demand in context of commands.
     * You can demand a minimum and a maximum number a user can have within your program, as well as provide corresponding error messages if either of the demands is not met.
     */
    demandCommand(): Argv<T>;
    demandCommand(min: number, minMsg?: string): Argv<T>;
    demandCommand(min: number, max?: number, minMsg?: string, maxMsg?: string): Argv<T>;
    /**
     * Shows a [deprecated] notice in front of the option
     */
    deprecateOption(option: string, msg?: string): Argv<T>;
    /**
     * Describe a `key` for the generated usage information.
     */
    describe(key: string | readonly string[], description: string): Argv<T>;
    describe(descriptions: {
        [key: string]: string;
    }): Argv<T>;
    /** Should yargs attempt to detect the os' locale? Defaults to `true`. */
    detectLocale(detect: boolean): Argv<T>;
    /**
     * Tell yargs to parse environment variables matching the given prefix and apply them to argv as though they were command line arguments.
     */
    env(): Argv<T>;
    env(prefix: string): Argv<T>;
    env(enable: boolean): Argv<T>;
    /** A message to print at the end of the usage instructions */
    epilog(msg: string): Argv<T>;
    /** A message to print at the end of the usage instructions */
    epilogue(msg: string): Argv<T>;
    /**
     * Give some example invocations of your program.
     * Inside `cmd`, the string `$0` will get interpolated to the current script name or node command for the present script similar to how `$0` works in bash or perl.
     * Examples will be printed out as part of the help message.
     */
    example(command: string, description: string): Argv<T>;
    example(command: ReadonlyArray<[string, string?]>): Argv<T>;
    /** Manually indicate that the program should exit, and provide context about why we wanted to exit. Follows the behavior set by `.exitProcess().` */
    exit(code: number, err: Error): void;
    /**
     * By default, yargs exits the process when the user passes a help flag, the user uses the `.version` functionality, validation fails, or the command handler fails.
     * Calling `.exitProcess(false)` disables this behavior, enabling further actions after yargs have been validated.
     */
    exitProcess(enabled: boolean): Argv<T>;
    /**
     * Method to execute when a failure occurs, rather than printing the failure message.
     * @param func Is called with the failure message that would have been printed, the Error instance originally thrown and yargs state when the failure occurred.
     */
    fail(func: ((msg: string, err: Error, yargs: Argv<T>) => any) | boolean): Argv<T>;
    /**
     * Allows to programmatically get completion choices for any line.
     * @param args An array of the words in the command line to complete.
     * @param done The callback to be called with the resulting completions.
     */
    getCompletion(args: readonly string[], done: (err: Error | null, completions: readonly string[]) => void): Argv<T>;
    getCompletion(args: readonly string[], done?: never): Promise<readonly string[]>;
    /**
     * Returns a promise which resolves to a string containing the help text.
     */
    getHelp(): Promise<string>;
    /**
     * Indicate that an option (or group of options) should not be reset when a command is executed
     */
    global(key: string | readonly string[]): Argv<T>;
    /** Given a key, or an array of keys, places options under an alternative heading when displaying usage instructions */
    group(key: string | readonly string[], groupName: string): Argv<T>;
    /** Hides a key from the generated usage information. Unless a `--show-hidden` option is also passed with `--help` (see `showHidden()`). */
    hide(key: string): Argv<T>;
    /**
     * Configure an (e.g. `--help`) and implicit command that displays the usage string and exits the process.
     * By default yargs enables help on the `--help` option.
     * @param [description] Customizes the description of the help option in the usage string.
     * @param [enableExplicit] If `false` is provided, it will disable --help.
     */
    help(): Argv<T>;
    help(enableExplicit: boolean): Argv<T>;
    help(option: string, enableExplicit: boolean): Argv<T>;
    help(option: string, description?: string, enableExplicit?: boolean): Argv<T>;
    /**
     * Given the key `x` is set, it is required that the key `y` is set.
     * y` can either be the name of an argument to imply, a number indicating the position of an argument or an array of multiple implications to associate with `x`.
     */
    implies(key: string, value: string | readonly string[]): Argv<T>;
    implies(implies: {
        [key: string]: string | readonly string[];
    }): Argv<T>;
    /**
     * Return the locale that yargs is currently using.
     */
    locale(): string;
    /**
     * Override the auto-detected locale from the user's operating system with a static locale.
     * Note that the OS locale can be modified by setting/exporting the `LC_ALL` environment variable.
     */
    locale(loc: string): Argv<T>;
    /**
     * Define global middleware functions to be called first, in list order, for all cli command.
     * @param callbacks Can be a function or a list of functions. Each callback gets passed a reference to argv.
     * @param [applyBeforeValidation] Set to `true` to apply middleware before validation. This will execute the middleware prior to validation checks, but after parsing.
     */
    middleware(callbacks: MiddlewareFunction<T> | ReadonlyArray<MiddlewareFunction<T>>, applyBeforeValidation?: boolean): Argv<T>;
    /**
     * The number of arguments that should be consumed after a key. This can be a useful hint to prevent parsing ambiguity.
     */
    nargs(key: string, count: number): Argv<T>;
    nargs(nargs: {
        [key: string]: number;
    }): Argv<T>;
    /** The key provided represents a path and should have `path.normalize()` applied. */
    normalize<K extends keyof T>(key: K | readonly K[]): Argv<Omit<T, K> & {
        [key in K]: ToString<T[key]>;
    }>;
    normalize<K extends string>(key: K | readonly K[]): Argv<T & {
        [key in K]: string | undefined;
    }>;
    /**
     * Tell the parser to always interpret key as a number.
     */
    number<K extends keyof T>(key: K | readonly K[]): Argv<Omit<T, K> & {
        [key in K]: ToNumber<T[key]>;
    }>;
    number<K extends string>(key: K | readonly K[]): Argv<T & {
        [key in K]: number | undefined;
    }>;
    /**
     * This method can be used to make yargs aware of options that could exist.
     * You can also pass an opt object which can hold further customization, like `.alias()`, `.demandOption()` etc. for that option.
     */
    option<K extends keyof T, O extends Options>(key: K, options: O): Argv<Omit<T, K> & {
        [key in K]: InferredOptionType<O>;
    } & Alias<O>>;
    option<K extends string, O extends Options>(key: K, options: O): Argv<T & {
        [key in K]: InferredOptionType<O>;
    } & Alias<O>>;
    option<O extends {
        [key: string]: Options;
    }>(options: O): Argv<Omit<T, keyof O> & InferredOptionTypes<O> & Alias<O>>;
    /**
     * This method can be used to make yargs aware of options that could exist.
     * You can also pass an opt object which can hold further customization, like `.alias()`, `.demandOption()` etc. for that option.
     */
    options<K extends keyof T, O extends Options>(key: K, options: O): Argv<Omit<T, K> & {
        [key in K]: InferredOptionType<O>;
    }>;
    options<K extends string, O extends Options>(key: K, options: O): Argv<T & {
        [key in K]: InferredOptionType<O>;
    }>;
    options<O extends {
        [key: string]: Options;
    }>(options: O): Argv<Omit<T, keyof O> & InferredOptionTypes<O>>;
    /**
     * Parse `args` instead of `process.argv`. Returns the `argv` object. `args` may either be a pre-processed argv array, or a raw argument string.
     * @param [context]  Provides a useful mechanism for passing state information to commands
     */
    parse(): {
        [key in keyof Arguments<T> as key | CamelCaseKey<key>]: Arguments<T>[key];
    } | Promise<{
        [key in keyof Arguments<T> as key | CamelCaseKey<key>]: Arguments<T>[key];
    }>;
    parse(arg: string | readonly string[], context?: object, parseCallback?: ParseCallback<T>): {
        [key in keyof Arguments<T> as key | CamelCaseKey<key>]: Arguments<T>[key];
    } | Promise<{
        [key in keyof Arguments<T> as key | CamelCaseKey<key>]: Arguments<T>[key];
    }>;
    parseSync(): {
        [key in keyof Arguments<T> as key | CamelCaseKey<key>]: Arguments<T>[key];
    };
    parseSync(arg: string | readonly string[], context?: object, parseCallback?: ParseCallback<T>): {
        [key in keyof Arguments<T> as key | CamelCaseKey<key>]: Arguments<T>[key];
    };
    parseAsync(): Promise<{
        [key in keyof Arguments<T> as key | CamelCaseKey<key>]: Arguments<T>[key];
    }>;
    parseAsync(arg: string | readonly string[], context?: object, parseCallback?: ParseCallback<T>): Promise<{
        [key in keyof Arguments<T> as key | CamelCaseKey<key>]: Arguments<T>[key];
    }>;
    /**
     * If the arguments have not been parsed, this property is `false`.
     */
    parsed: DetailedArguments | false;
    /** Allows to configure advanced yargs features. */
    parserConfiguration(configuration: Partial<ParserConfigurationOptions>): Argv<T>;
    /**
     * Similar to `config()`, indicates that yargs should interpret the object from the specified key in package.json as a configuration object.
     * @param [cwd] If provided, the package.json will be read from this location
     */
    pkgConf(key: string | readonly string[], cwd?: string): Argv<T>;
    /**
     * Allows you to configure a command's positional arguments with an API similar to `.option()`.
     * `.positional()` should be called in a command's builder function, and is not available on the top-level yargs instance. If so, it will throw an error.
     */
    positional<K extends keyof T, O extends PositionalOptions>(key: K, opt: O): Argv<Omit<T, K> & {
        [key in K]: InferredOptionType<O>;
    }>;
    positional<K extends string, O extends PositionalOptions>(key: K, opt: O): Argv<T & {
        [key in K]: InferredOptionType<O>;
    }>;
    /** Should yargs provide suggestions regarding similar commands if no matching command is found? */
    recommendCommands(): Argv<T>;
    /**
     * @deprecated since version 6.6.0
     * Use '.demandCommand()' or '.demandOption()' instead
     */
    require<K extends keyof T>(key: K | readonly K[], msg?: string | true): Argv<Defined<T, K>>;
    require(key: string, msg: string): Argv<T>;
    require(key: string, required: boolean): Argv<T>;
    require(keys: readonly number[], msg: string): Argv<T>;
    require(keys: readonly number[], required: boolean): Argv<T>;
    require(positionals: number, required: boolean): Argv<T>;
    require(positionals: number, msg: string): Argv<T>;
    /**
     * @deprecated since version 6.6.0
     * Use '.demandCommand()' or '.demandOption()' instead
     */
    required<K extends keyof T>(key: K | readonly K[], msg?: string | true): Argv<Defined<T, K>>;
    required(key: string, msg: string): Argv<T>;
    required(key: string, required: boolean): Argv<T>;
    required(keys: readonly number[], msg: string): Argv<T>;
    required(keys: readonly number[], required: boolean): Argv<T>;
    required(positionals: number, required: boolean): Argv<T>;
    required(positionals: number, msg: string): Argv<T>;
    requiresArg(key: string | readonly string[]): Argv<T>;
    /** Set the name of your script ($0). Default is the base filename executed by node (`process.argv[1]`) */
    scriptName($0: string): Argv<T>;
    /**
     * Generate a bash completion script.
     * Users of your application can install this script in their `.bashrc`, and yargs will provide completion shortcuts for commands and options.
     */
    showCompletionScript(): Argv<T>;
    /**
     * Configure the `--show-hidden` option that displays the hidden keys (see `hide()`).
     * @param option If `boolean`, it enables/disables this option altogether. i.e. hidden keys will be permanently hidden if first argument is `false`.
     * If `string` it changes the key name ("--show-hidden").
     * @param description Changes the default description ("Show hidden options")
     */
    showHidden(option?: string | boolean): Argv<T>;
    showHidden(option: string, description?: string): Argv<T>;
    /**
     * Print the usage data using the console function consoleLevel for printing.
     * @param [consoleLevel='error']
     */
    showHelp(consoleLevel?: string): Argv<T>;
    /**
     * Provide the usage data as a string.
     * @param printCallback a function with a single argument.
     */
    showHelp(printCallback: (s: string) => void): Argv<T>;
    /**
     * By default, yargs outputs a usage string if any error is detected.
     * Use the `.showHelpOnFail()` method to customize this behavior.
     * @param enable If `false`, the usage string is not output.
     * @param [message] Message that is output after the error message.
     */
    showHelpOnFail(enable: boolean, message?: string): Argv<T>;
    /**
     * Print the version data using the console function consoleLevel or the specified function.
     * @param [level='error']
     */
    showVersion(level?: 'error' | 'log' | ((message: string) => void)): Argv<T>;
    /** Specifies either a single option key (string), or an array of options. If any of the options is present, yargs validation is skipped. */
    skipValidation(key: string | readonly string[]): Argv<T>;
    /**
     * Any command-line argument given that is not demanded, or does not have a corresponding description, will be reported as an error.
     */
    strict(): Argv<T>;
    strict(enabled: boolean): Argv<T>;
    /**
     * Similar to .strict(), except that it only applies to unrecognized commands.
     * A user can still provide arbitrary options, but unknown positional commands
     * will raise an error.
     */
    strictCommands(): Argv<T>;
    strictCommands(enabled: boolean): Argv<T>;
    /**
     * Similar to `.strict()`, except that it only applies to unrecognized options. A
     * user can still provide arbitrary positional options, but unknown options
     * will raise an error.
     */
    strictOptions(): Argv<T>;
    strictOptions(enabled: boolean): Argv<T>;
    /**
     * Tell the parser logic not to interpret `key` as a number or boolean. This can be useful if you need to preserve leading zeros in an input.
     */
    string<K extends keyof T>(key: K | readonly K[]): Argv<Omit<T, K> & {
        [key in K]: ToString<T[key]>;
    }>;
    string<K extends string>(key: K | readonly K[]): Argv<T & {
        [key in K]: string | undefined;
    }>;
    terminalWidth(): number;
    updateLocale(obj: {
        [key: string]: string;
    }): Argv<T>;
    /**
     * Override the default strings used by yargs with the key/value pairs provided in obj
     */
    updateStrings(obj: {
        [key: string]: string;
    }): Argv<T>;
    /**
     * Set a usage message to show which commands to use.
     * Inside `message`, the string `$0` will get interpolated to the current script name or node command for the present script similar to how `$0` works in bash or perl.
     */
    usage(message: string): Argv<T>;
    usage<U>(command: string | readonly string[], description: string, builder?: (args: Argv<T>) => Argv<U>, handler?: (args: ArgumentsCamelCase<U>) => unknown): Argv<T>;
    usage<U>(command: string | readonly string[], showInHelp: boolean, builder?: (args: Argv<T>) => Argv<U>, handler?: (args: ArgumentsCamelCase<U>) => unknown): Argv<T>;
    usage<O extends {
        [key: string]: Options;
    }>(command: string | readonly string[], description: string, builder?: O, handler?: (args: ArgumentsCamelCase<InferredOptionTypes<O>>) => unknown): Argv<T>;
    usage<O extends {
        [key: string]: Options;
    }>(command: string | readonly string[], showInHelp: boolean, builder?: O, handler?: (args: ArgumentsCamelCase<InferredOptionTypes<O>>) => unknown): Argv<T>;
    /**
     * Add an option (e.g. `--version`) that displays the version number (given by the version parameter) and exits the process.
     * By default yargs enables version for the `--version` option.
     */
    version(): Argv<T>;
    version(version: string): Argv<T>;
    version(enable: boolean): Argv<T>;
    version(optionKey: string, version: string): Argv<T>;
    version(optionKey: string, description: string, version: string): Argv<T>;
    /**
     * Format usage output to wrap at columns many columns.
     */
    wrap(columns: number | null): Argv<T>;
    /** burgee: the manifest every surface — help, `--json`, `--schema`, `--mcp`, completions — is projected from (J7, J8). */
    readonly manifest: Manifest;
    /** burgee: declare what the command does to the world (N6); what exposes it as an MCP tool (N2). */
    effects(value: DeclaredEffects): Argv<T>;
    /** burgee: plugins yargs never had. `preRun`/`postRun` fire around every handler. */
    use(plugin: Plugin): Argv<T>;
    /** burgee: inject the streams and the exit for this instance (T1), and get E1 exit codes back. */
    burgee(seam: BurgeeSeam): Argv<T>;
}

interface CommandModule<T = {}, U = {}> {
    /** array of strings (or a single string) representing aliases of `exports.command`, positional args defined in an alias are ignored */
    aliases?: readonly string[] | string | undefined;
    /** object declaring the options the command accepts, or a function accepting and returning a yargs instance */
    builder?: CommandBuilder<T, U> | undefined;
    /** string (or array of strings) that executes this command when given on the command line, first string may contain positional args */
    command?: readonly string[] | string | undefined;
    /** boolean (or string) to show deprecation notice */
    deprecated?: boolean | string | undefined;
    /** string used as the description for the command in help text, use `false` for a hidden command */
    describe?: string | false | undefined;
    /** a function which will be passed the parsed argv. */
    handler: (args: ArgumentsCamelCase<U>) => unknown;
}

interface DetailedArguments {
    argv: Record<string, any>;
    error: Error | null;
    aliases: Record<string, string[]>;
    newAliases: Record<string, boolean>;
    defaulted: Record<string, boolean>;
    configuration: Record<string, any>;
}

interface Options {
    /** string or array of strings, alias(es) for the canonical option key, see `alias()` */
    alias?: string | readonly string[] | undefined;
    /** boolean, interpret option as an array, see `array()` */
    array?: boolean | undefined;
    /**  boolean, interpret option as a boolean flag, see `boolean()` */
    boolean?: boolean | undefined;
    /** value or array of values, limit valid option arguments to a predefined set, see `choices()` */
    choices?: Choices | undefined;
    /** function, coerce or transform parsed command line values into another value, see `coerce()` */
    coerce?: ((arg: any) => any) | undefined;
    /** boolean, interpret option as a path to a JSON config file, see `config()` */
    config?: boolean | undefined;
    /** function, provide a custom config parsing function, see `config()` */
    configParser?: ((configPath: string) => object) | undefined;
    /** string or object, require certain keys not to be set, see `conflicts()` */
    conflicts?: string | readonly string[] | {
        [key: string]: string | readonly string[];
    } | undefined;
    /** boolean, interpret option as a count of boolean flags, see `count()` */
    count?: boolean | undefined;
    /** value, set a default value for the option, see `default()` */
    default?: any;
    /** string, use this description for the default value in help content, see `default()` */
    defaultDescription?: string | undefined;
    /**
     *  @deprecated since version 6.6.0
     *  Use 'demandOption' instead
     */
    demand?: boolean | string | undefined;
    /** boolean or string, mark the argument as deprecated, see `deprecateOption()` */
    deprecate?: boolean | string | undefined;
    /** boolean or string, mark the argument as deprecated, see `deprecateOption()` */
    deprecated?: boolean | string | undefined;
    /** boolean or string, demand the option be given, with optional error message, see `demandOption()` */
    demandOption?: boolean | string | undefined;
    /** string, the option description for help content, see `describe()` */
    desc?: string | undefined;
    /** string, the option description for help content, see `describe()` */
    describe?: string | undefined;
    /** string, the option description for help content, see `describe()` */
    description?: string | undefined;
    /** boolean, indicate that this key should not be reset when a command is invoked, see `global()` */
    global?: boolean | undefined;
    /** string, when displaying usage instructions place the option under an alternative group heading, see `group()` */
    group?: string | undefined;
    /** don't display option in help output. */
    hidden?: boolean | undefined;
    /**  string or object, require certain keys to be set, see `implies()` */
    implies?: string | readonly string[] | {
        [key: string]: string | readonly string[];
    } | undefined;
    /** number, specify how many arguments should be consumed for the option, see `nargs()` */
    nargs?: number | undefined;
    /** boolean, apply path.normalize() to the option, see `normalize()` */
    normalize?: boolean | undefined;
    /** boolean, interpret option as a number, `number()` */
    number?: boolean | undefined;
    /**
     *  @deprecated since version 6.6.0
     *  Use 'demandOption' instead
     */
    require?: boolean | string | undefined;
    /**
     *  @deprecated since version 6.6.0
     *  Use 'demandOption' instead
     */
    required?: boolean | string | undefined;
    /** boolean, require the option be specified with a value, see `requiresArg()` */
    requiresArg?: boolean | undefined;
    /** boolean, skips validation if the option is present, see `skipValidation()` */
    skipValidation?: boolean | undefined;
    /** boolean, interpret option as a string, see `string()` */
    string?: boolean | undefined;
    type?: 'array' | 'count' | PositionalOptionsType | undefined;
}

interface ParsedCommand {
    cmd: string;
    demanded: Positional[];
    optional: Positional[];
}

interface Parser {
    (args: string | any[], opts?: any): Record<string, any>;
    detailed: (args: string | any[], opts?: any) => DetailedArguments;
    camelCase: typeof camelCase;
    decamelize: typeof decamelize;
    looksLikeNumber: typeof looksLikeNumber;
}

interface PlatformShim {
    assert: {
        notStrictEqual: (a: any, b: any, m?: string) => void;
        strictEqual: (a: any, b: any, m?: string) => void;
    };
    cliui: typeof cliui;
    findUp: (start: string, callback: (dir: string, names: string[]) => string | undefined) => string | undefined;
    getEnv: (key: string) => string | undefined;
    inspect: typeof inspect;
    getProcessArgvBin: () => string;
    mainFilename: string;
    Parser: typeof Parser;
    path: {
        basename: typeof basename;
        dirname: typeof dirname;
        extname: typeof extname;
        relative: typeof relative;
        resolve: typeof resolve;
        join: typeof join;
    };
    process: {
        argv: () => string[];
        cwd: () => string;
        emitWarning: (warning: string | Error, type?: string) => void;
        execPath: () => string;
        exit: (code: number) => void;
        nextTick: (cb: () => void) => void;
        stdColumns: number | null;
        /** burgee: the streams --mcp serves on, reached through the shim like everything else. */
        stdin: () => NodeJS.ReadableStream;
        stdout: () => {
            write: (s: string) => unknown;
        };
    };
    readFileSync: typeof readFileSync;
    readdirSync: typeof readdirSync;
    require: NodeJS.Require;
    getCallerFile: () => string;
    stringWidth: (str: string) => number;
    y18n: Y18N;
    /** burgee: a previous major's command collaborator, where its behaviour differs from 18's (`yargs/v17-factory.ts`). */
    CommandInstance?: typeof CommandInstance;
}