burgee 0.0.0 → 0.3.0

package/dist/yargs-completion.js

@@ -0,0 +1,271 @@
+import { isCommandBuilderCallback } from './yargs-command.js';
+import { isPromise, parseCommand } from './yargs-utils.js';
+export const completionShTemplate = `###-begin-{{app_name}}-completions-###
+#
+# yargs command completion script
+#
+# Installation: {{app_path}} {{completion_command}} >> ~/.bashrc
+#    or {{app_path}} {{completion_command}} >> ~/.bash_profile on OSX.
+#
+_{{app_name}}_yargs_completions()
+{
+    local cur_word args type_list
+
+    cur_word="\${COMP_WORDS[COMP_CWORD]}"
+    args=("\${COMP_WORDS[@]}")
+
+    # ask yargs to generate completions.
+    # see https://stackoverflow.com/a/40944195/7080036 for the spaces-handling awk
+    mapfile -t type_list < <({{app_path}} --get-yargs-completions "\${args[@]}")
+    mapfile -t COMPREPLY < <(compgen -W "$( printf '%q ' "\${type_list[@]}" )" -- "\${cur_word}" |
+        awk '/ / { print "\\""$0"\\"" } /^[^ ]+$/ { print $0 }')
+
+    # if no match was found, fall back to filename completion
+    if [ \${#COMPREPLY[@]} -eq 0 ]; then
+      COMPREPLY=()
+    fi
+
+    return 0
+}
+complete -o bashdefault -o default -F _{{app_name}}_yargs_completions {{app_name}}
+###-end-{{app_name}}-completions-###
+`;
+export const completionZshTemplate = `#compdef {{app_name}}
+###-begin-{{app_name}}-completions-###
+#
+# yargs command completion script
+#
+# Installation: {{app_path}} {{completion_command}} >> ~/.zshrc
+#    or {{app_path}} {{completion_command}} >> ~/.zprofile on OSX.
+#
+_{{app_name}}_yargs_completions()
+{
+  local reply
+  local si=$IFS
+  IFS=$'\n' reply=($(COMP_CWORD="$((CURRENT-1))" COMP_LINE="$BUFFER" COMP_POINT="$CURSOR" {{app_path}} --get-yargs-completions "\${words[@]}"))
+  IFS=$si
+  if [[ \${#reply} -gt 0 ]]; then
+    _describe 'values' reply
+  else
+    _default
+  fi
+}
+if [[ "'\${zsh_eval_context[-1]}" == "loadautofunc" ]]; then
+  _{{app_name}}_yargs_completions "$@"
+else
+  compdef _{{app_name}}_yargs_completions {{app_name}}
+fi
+###-end-{{app_name}}-completions-###
+`;
+export class Completion {
+    completionKey = 'get-yargs-completions';
+    aliases = null;
+    customCompletionFunction = null;
+    indexAfterLastReset = 0;
+    zshShell;
+    yargs;
+    usage;
+    command;
+    shim;
+    constructor(yargs, usage, command, shim) {
+        this.yargs = yargs;
+        this.usage = usage;
+        this.command = command;
+        this.shim = shim;
+        this.zshShell = (this.shim.getEnv('SHELL')?.includes('zsh') || this.shim.getEnv('ZSH_NAME')?.includes('zsh')) ?? false;
+    }
+    defaultCompletion(args, argv, current, done) {
+        const handlers = this.command.getCommandHandlers();
+        for (let i = 0, ii = args.length; i < ii; ++i) {
+            const handler = handlers[args[i]];
+            if (handler && handler.builder) {
+                const builder = handler.builder;
+                if (isCommandBuilderCallback(builder)) {
+                    this.indexAfterLastReset = i + 1;
+                    const y = this.yargs.getInternalMethods().reset();
+                    builder(y, true);
+                    return y.argv;
+                }
+            }
+        }
+        const completions = [];
+        this.commandCompletions(completions, args, current);
+        this.optionCompletions(completions, args, argv, current);
+        this.choicesFromOptionsCompletions(completions, args, argv, current);
+        this.choicesFromPositionalsCompletions(completions, args, argv, current);
+        done(null, completions);
+    }
+    commandCompletions(completions, args, current) {
+        const parentCommands = this.yargs.getInternalMethods().getContext().commands;
+        if (!/^-/.exec(current) && parentCommands.at(-1) !== current && !this.previousArgHasChoices(args)) {
+            this.usage.getCommands().forEach((usageCommand) => {
+                const commandName = parseCommand(usageCommand[0]).cmd;
+                if (args.indexOf(commandName) === -1) {
+                    if (!this.zshShell)
+                        completions.push(commandName);
+                    else {
+                        const desc = usageCommand[1] || '';
+                        completions.push(`${commandName.replace(/:/g, '\\:')}:${desc}`);
+                    }
+                }
+            });
+        }
+    }
+    optionCompletions(completions, args, argv, current) {
+        if ((/^-/.exec(current) || (current === '' && completions.length === 0)) && !this.previousArgHasChoices(args)) {
+            const options = this.yargs.getOptions();
+            const positionalKeys = this.yargs.getGroups()[this.usage.getPositionalGroupName()] || [];
+            Object.keys(options.key).forEach((key) => {
+                const negable = !!options.configuration['boolean-negation'] && options.boolean.includes(key);
+                const isPositionalKey = positionalKeys.includes(key);
+                if (!isPositionalKey && !options.hiddenOptions.includes(key) && !this.argsContainKey(args, key, negable)) {
+                    this.completeOptionKey(key, completions, current, negable && !!options.default[key]);
+                }
+            });
+        }
+    }
+    choicesFromOptionsCompletions(completions, args, _argv, _current) {
+        if (this.previousArgHasChoices(args)) {
+            const choices = this.getPreviousArgChoices(args);
+            if (choices && choices.length > 0)
+                completions.push(...choices.map((c) => c.replace(/:/g, '\\:')));
+        }
+    }
+    choicesFromPositionalsCompletions(completions, args, argv, current) {
+        if (current === '' && completions.length > 0 && this.previousArgHasChoices(args))
+            return;
+        const positionalKeys = this.yargs.getGroups()[this.usage.getPositionalGroupName()] || [];
+        const offset = Math.max(this.indexAfterLastReset, this.yargs.getInternalMethods().getContext().commands.length + 1);
+        const positionalKey = positionalKeys[argv._.length - offset - 1];
+        if (!positionalKey)
+            return;
+        const choices = this.yargs.getOptions().choices[positionalKey] || [];
+        for (const choice of choices) {
+            if (choice.startsWith(current))
+                completions.push(choice.replace(/:/g, '\\:'));
+        }
+    }
+    getPreviousArgChoices(args) {
+        if (args.length < 1)
+            return undefined;
+        let previousArg = args.at(-1);
+        let filter = '';
+        if (!previousArg.startsWith('-') && args.length > 1) {
+            filter = previousArg;
+            previousArg = args.at(-2);
+        }
+        if (!previousArg.startsWith('-'))
+            return undefined;
+        const previousArgKey = previousArg.replace(/^-+/, '');
+        const options = this.yargs.getOptions();
+        const possibleAliases = [previousArgKey, ...(this.yargs.getAliases()[previousArgKey] || [])];
+        let choices;
+        for (const possibleAlias of possibleAliases) {
+            if (Object.prototype.hasOwnProperty.call(options.key, possibleAlias) && Array.isArray(options.choices[possibleAlias])) {
+                choices = options.choices[possibleAlias];
+                break;
+            }
+        }
+        if (choices)
+            return choices.filter((choice) => !filter || choice.startsWith(filter));
+        return undefined;
+    }
+    previousArgHasChoices(args) {
+        const choices = this.getPreviousArgChoices(args);
+        return choices !== undefined && choices.length > 0;
+    }
+    argsContainKey(args, key, negable) {
+        const argsContains = (s) => args.indexOf((/^[^0-9]$/.test(s) ? '-' : '--') + s) !== -1;
+        if (argsContains(key))
+            return true;
+        if (negable && argsContains(`no-${key}`))
+            return true;
+        if (this.aliases) {
+            for (const alias of this.aliases[key]) {
+                if (argsContains(alias))
+                    return true;
+            }
+        }
+        return false;
+    }
+    completeOptionKey(key, completions, current, negable) {
+        let keyWithDesc = key;
+        if (this.zshShell) {
+            const descs = this.usage.getDescriptions();
+            const aliasKey = this.aliases?.[key]?.find((alias) => {
+                const desc = descs[alias];
+                return typeof desc === 'string' && desc.length > 0;
+            });
+            const descFromAlias = aliasKey ? descs[aliasKey] : undefined;
+            const desc = descs[key] ?? descFromAlias ?? '';
+            keyWithDesc = `${key.replace(/:/g, '\\:')}:${desc.replace('__yargsString__:', '').replace(/(\r\n|\n|\r)/gm, ' ')}`;
+        }
+        const startsByTwoDashes = (s) => /^--/.test(s);
+        const isShortOption = (s) => /^[^0-9]$/.test(s);
+        const dashes = !startsByTwoDashes(current) && isShortOption(key) ? '-' : '--';
+        completions.push(dashes + keyWithDesc);
+        if (negable)
+            completions.push(`${dashes}no-${keyWithDesc}`);
+    }
+    customCompletion(args, argv, current, done) {
+        this.shim.assert.notStrictEqual(this.customCompletionFunction, null);
+        const fn = this.customCompletionFunction;
+        if (isSyncCompletionFunction(fn)) {
+            const result = fn(current, argv);
+            if (isPromise(result)) {
+                return result
+                    .then((list) => {
+                    this.shim.process.nextTick(() => {
+                        done(null, list);
+                    });
+                })
+                    .catch((err) => {
+                    this.shim.process.nextTick(() => {
+                        done(err, undefined);
+                    });
+                });
+            }
+            return done(null, result);
+        }
+        else if (isFallbackCompletionFunction(fn)) {
+            return fn(current, argv, (onCompleted = done) => this.defaultCompletion(args, argv, current, onCompleted), (completions) => {
+                done(null, completions);
+            });
+        }
+        return fn(current, argv, (completions) => {
+            done(null, completions);
+        });
+    }
+    getCompletion(args, done) {
+        const current = args.length ? args.at(-1) : '';
+        const argv = this.yargs.parse(args, true);
+        const completionFunction = this.customCompletionFunction
+            ? (a) => this.customCompletion(args, a, current, done)
+            : (a) => this.defaultCompletion(args, a, current, done);
+        return isPromise(argv) ? argv.then(completionFunction) : completionFunction(argv);
+    }
+    generateCompletionScript($0, cmd) {
+        let script = this.zshShell ? completionZshTemplate : completionShTemplate;
+        const name = this.shim.path.basename($0);
+        if (/\.js$/.exec($0))
+            $0 = `./${$0}`;
+        script = script.replace(/{{app_name}}/g, name);
+        script = script.replace(/{{completion_command}}/g, cmd);
+        return script.replace(/{{app_path}}/g, $0);
+    }
+    registerFunction(fn) {
+        this.customCompletionFunction = fn;
+    }
+    setParsed(parsed) {
+        this.aliases = parsed.aliases;
+    }
+}
+export function completion(yargs, usage, command, shim) {
+    return new Completion(yargs, usage, command, shim);
+}
+function isSyncCompletionFunction(fn) {
+    return fn.length < 3;
+}
+function isFallbackCompletionFunction(fn) {
+    return fn.length > 3;
+}

package/dist/yargs-factory.d.ts

@@ -0,0 +1,193 @@
+/**
+ * yargs' `YargsInstance`, ported method for method from yargs 18 and graded by yargs'
+ * own suite through `compat-oracle`. Every public method, its argsert contract, the
+ * parse pipeline, the freeze/unfreeze bookkeeping around `.parse()` and the
+ * `getInternalMethods()` seam are the upstream's — that is what makes a user's
+ * existing program run unchanged (J2).
+ */
+import { type Effects, Manifest, type Plugin } from './manifest.js';
+import { type CommandInstance } from './yargs-command.js';
+import { type CompletionFunction } from './yargs-completion.js';
+import { type Middleware } from './yargs-middleware.js';
+import type { PlatformShim } from './yargs-shim.js';
+import { type FailureFunction, type UsageInstance } from './yargs-usage.js';
+import { YError } from './yargs-utils.js';
+import { type ValidationInstance } from './yargs-validation.js';
+export interface Options {
+    array: string[];
+    boolean: string[];
+    string: string[];
+    skipValidation: string[];
+    count: string[];
+    normalize: string[];
+    number: string[];
+    hiddenOptions: string[];
+    narg: Record<string, number>;
+    key: Record<string, boolean>;
+    alias: Record<string, string[]>;
+    default: Record<string, any>;
+    defaultDescription: Record<string, string>;
+    config: Record<string, any>;
+    choices: Record<string, any[]>;
+    demandedOptions: Record<string, string | undefined>;
+    demandedCommands: Record<string, {
+        min: number;
+        max: number;
+        minMsg?: string | null | undefined;
+        maxMsg?: string | null | undefined;
+    }>;
+    deprecatedOptions: Record<string, string | boolean | undefined>;
+    local: string[];
+    configObjects: Record<string, any>[];
+    envPrefix?: string | undefined;
+    showHiddenOpt: string;
+    configuration: Record<string, any>;
+    __?: (...args: any[]) => string;
+}
+export interface Context {
+    commands: string[];
+    fullCommands: string[];
+}
+interface Logger {
+    log: (...args: any[]) => void;
+    error: (...args: any[]) => void;
+}
+export type ParseCallback = (err: YError | string | undefined | null, argv: any, output: string) => void;
+interface Writer {
+    write: (str: string) => unknown;
+}
+/** burgee's seam: inject the streams and the exit, and get E1 exit codes back (T1). */
+export interface BurgeeSeam {
+    stdout?: Writer;
+    stderr?: Writer;
+    exit?: (code: number) => void;
+}
+export declare function YargsFactory(shim: PlatformShim): (processArgs?: string | string[], cwd?: string, parentRequire?: NodeJS.Require) => YargsInstance;
+export declare 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: Effects): 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(seam: BurgeeSeam): this;
+}
+export declare function isYargsInstance(y: any): y is YargsInstance;
+export {};