burgee 0.0.0 → 0.2.0

package/dist/commander-argument.js

@@ -0,0 +1,72 @@
+import { InvalidArgumentError } from './commander-error.js';
+export class Argument {
+    description;
+    variadic = false;
+    parseArg = undefined;
+    defaultValue = undefined;
+    defaultValueDescription = undefined;
+    argChoices = undefined;
+    required;
+    _name;
+    constructor(name, description) {
+        this.description = description || '';
+        switch (name[0]) {
+            case '<':
+                this.required = true;
+                this._name = name.slice(1, -1);
+                break;
+            case '[':
+                this.required = false;
+                this._name = name.slice(1, -1);
+                break;
+            default:
+                this.required = true;
+                this._name = name;
+                break;
+        }
+        if (this._name.endsWith('...')) {
+            this.variadic = true;
+            this._name = this._name.slice(0, -3);
+        }
+    }
+    name() {
+        return this._name;
+    }
+    _collectValue(value, previous) {
+        if (previous === this.defaultValue || !Array.isArray(previous))
+            return [value];
+        previous.push(value);
+        return previous;
+    }
+    default(value, description) {
+        this.defaultValue = value;
+        this.defaultValueDescription = description;
+        return this;
+    }
+    argParser(fn) {
+        this.parseArg = fn;
+        return this;
+    }
+    choices(values) {
+        this.argChoices = values.slice();
+        this.parseArg = (arg, previous) => {
+            if (!this.argChoices?.includes(arg)) {
+                throw new InvalidArgumentError(`Allowed choices are ${this.argChoices?.join(', ')}.`);
+            }
+            return this.variadic ? this._collectValue(arg, previous) : arg;
+        };
+        return this;
+    }
+    argRequired() {
+        this.required = true;
+        return this;
+    }
+    argOptional() {
+        this.required = false;
+        return this;
+    }
+}
+export function humanReadableArgName(arg) {
+    const nameOutput = arg.name() + (arg.variadic ? '...' : '');
+    return arg.required ? `<${nameOutput}>` : `[${nameOutput}]`;
+}

package/dist/commander-command.d.ts

@@ -0,0 +1,345 @@
+/**
+ * commander's `Command`, ported method for method from commander 15 and graded by
+ * commander's own suite through `compat-oracle`. The parse pipeline, the option
+ * grammar, every error string and exit code are commander's — that is what makes a
+ * user's existing program run unchanged (J2).
+ *
+ * burgee's additions sit beside it and never alter the default behaviour:
+ *   - `manifest` projects the command tree, so plugins (`use`) and the generated
+ *     surfaces read commander-syntax programs exactly like native ones (J7, J8);
+ *   - `--json`, when the program has not declared that option itself, wraps the
+ *     action's return value in the envelope (N-family);
+ *   - `parse(argv, { stdout, stderr, exit })` injects the streams and the exit, and
+ *     then reports through the E1 taxonomy — the harness's seam (T1).
+ */
+import childProcess from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import { Argument, type ParseArg } from './commander-argument.js';
+import { CommanderError } from './commander-error.js';
+import { Help } from './commander-help.js';
+import { Option } from './commander-option.js';
+import { type Effects, Manifest, type OptionSpec, type Plugin } from './manifest.js';
+export interface OutputConfiguration {
+    writeOut: (str: string) => void;
+    writeErr: (str: string) => void;
+    outputError: (str: string, write: (str: string) => void) => void;
+    getOutHelpWidth: () => number | undefined;
+    getErrHelpWidth: () => number | undefined;
+    getOutHasColors: () => boolean | undefined;
+    getErrHasColors: () => boolean | undefined;
+    stripColor: (str: string) => string;
+}
+export interface ParseOptions {
+    from?: 'node' | 'electron' | 'user' | 'eval';
+}
+interface Writer {
+    write: (str: string) => unknown;
+}
+/** burgee's additions: inject the streams and the exit, and get E1 exit codes back (T1). */
+export interface BurgeeParseOptions extends ParseOptions {
+    stdout?: Writer;
+    stderr?: Writer;
+    exit?: (code: number) => void;
+}
+export interface CommandOptions {
+    hidden?: boolean;
+    isDefault?: boolean;
+    /** @deprecated since v7, replaced by hidden */
+    noHelp?: boolean;
+}
+export interface ExecutableCommandOptions extends CommandOptions {
+    executableFile?: string;
+}
+export interface ErrorOptions {
+    code?: string;
+    exitCode?: number;
+}
+export interface OutputContext {
+    error?: boolean;
+}
+export type HookEvent = 'preSubcommand' | 'preAction' | 'postAction';
+export type HookListener = (thisCommand: Command, actionCommand: Command) => void | Promise<void>;
+export type AddHelpTextPosition = 'beforeAll' | 'before' | 'after' | 'afterAll';
+export type AddHelpTextContext = {
+    error: boolean;
+    command: Command;
+};
+interface SavedState {
+    _name: string;
+    _optionValues: Record<string, unknown>;
+    _optionValueSources: Record<string, string | undefined>;
+}
+interface Burgee {
+    exit: ((code: number) => void) | undefined;
+    json: boolean;
+}
+export declare class Command extends EventEmitter {
+    commands: Command[];
+    options: Option[];
+    parent: Command | null;
+    registeredArguments: Argument[];
+    /** @deprecated old name for registeredArguments */
+    _args: Argument[];
+    /** cli args with options removed */
+    args: string[];
+    rawArgs: string[];
+    /** like .args but after custom processing and collecting variadic */
+    processedArgs: unknown[];
+    runningCommand: childProcess.ChildProcess | undefined;
+    _allowUnknownOption: boolean;
+    _allowExcessArguments: boolean;
+    _scriptPath: string | null;
+    _name: string;
+    _optionValues: Record<string, unknown>;
+    _optionValueSources: Record<string, string | undefined>;
+    _storeOptionsAsProperties: boolean;
+    _actionHandler: ((args: unknown[]) => unknown) | null;
+    _executableHandler: boolean;
+    _executableFile: string | null;
+    _executableDir: string | null;
+    _defaultCommandName: string | null;
+    _exitCallback: ((err: CommanderError) => void) | null;
+    _aliases: string[];
+    _combineFlagAndOptionalValue: boolean;
+    _description: string;
+    _summary: string;
+    _argsDescription: Record<string, string> | undefined;
+    _enablePositionalOptions: boolean;
+    _passThroughOptions: boolean;
+    _lifeCycleHooks: Partial<Record<HookEvent, HookListener[]>>;
+    _showHelpAfterError: boolean | string;
+    _showSuggestionAfterError: boolean;
+    _savedState: SavedState | null;
+    _outputConfiguration: OutputConfiguration;
+    _hidden: boolean;
+    /** Lazy created on demand; null once disabled. */
+    _helpOption: Option | null | undefined;
+    _addImplicitHelpCommand: boolean | undefined;
+    _helpCommand: Command | undefined;
+    _helpConfiguration: Partial<Help>;
+    _helpGroupHeading: string | undefined;
+    _defaultCommandGroup: string | undefined;
+    _defaultOptionGroup: string | undefined;
+    _version: string | undefined;
+    _versionOptionName: string | undefined;
+    _usage: string | undefined;
+    /** burgee: the root's projection, created on first use. */
+    _manifest: Manifest | undefined;
+    /** burgee: what this command does to the world (N6); declaring it exposes the command as an MCP tool. */
+    _effects: Effects | undefined;
+    /** burgee: set for the duration of a parse that injected the streams or the exit. */
+    _burgee: Burgee | undefined;
+    constructor(name?: string);
+    /** Copy settings useful to share between the root and its subcommands. */
+    copyInheritedSettings(sourceCommand: Command): this;
+    _getCommandAndAncestors(): Command[];
+    /**
+     * Define a command. With a description as the second argument it is an executable
+     * subcommand and `this` is returned; otherwise the new command is returned.
+     */
+    command(nameAndArgs: string, opts?: CommandOptions): Command;
+    command(nameAndArgs: string, description: string, opts?: ExecutableCommandOptions): this;
+    /** Factory for an unattached command; override to customise subcommands. */
+    createCommand(name?: string): Command;
+    createHelp(): Help;
+    configureHelp(): Partial<Help>;
+    configureHelp(configuration: Partial<Help>): this;
+    configureOutput(): OutputConfiguration;
+    configureOutput(configuration: Partial<OutputConfiguration>): this;
+    showHelpAfterError(displayHelp?: boolean | string): this;
+    showSuggestionAfterError(displaySuggestion?: boolean): this;
+    addCommand(cmd: Command, opts?: CommandOptions): this;
+    createArgument(name: string, description?: string): Argument;
+    argument(name: string, description?: string, parseArg?: ParseArg | unknown, defaultValue?: unknown): this;
+    arguments(names: string): this;
+    addArgument(argument: Argument): this;
+    /** Customise or disable the default help command (added by default when there are subcommands). */
+    helpCommand(enableOrNameAndArgs?: string | boolean, description?: string): this;
+    addHelpCommand(helpCommand: Command | string | boolean, deprecatedDescription?: string): this;
+    _getHelpCommand(): Command | null;
+    hook(event: HookEvent, listener: HookListener): this;
+    /** Replace the call to process.exit; defaults to throwing the CommanderError. */
+    exitOverride(fn?: (err: CommanderError) => void): this;
+    _exit(exitCode: number, code: string, message: string): never;
+    action(fn: (...args: any[]) => unknown): this;
+    createOption(flags: string, description?: string): Option;
+    /** Wrap parseArg to turn `commander.invalidArgument` into an error with context. */
+    _callParseArg(target: Option | Argument, value: string, previous: unknown, invalidArgumentMessage: string): unknown;
+    _registerOption(option: Option): void;
+    _registerCommand(command: Command): void;
+    addOption(option: Option): this;
+    _optionEx(config: {
+        mandatory?: boolean;
+    }, flags: string, description?: string, fn?: unknown, defaultValue?: unknown): this;
+    option(flags: string, description?: string, parseArg?: ParseArg | unknown, defaultValue?: unknown): this;
+    requiredOption(flags: string, description?: string, parseArg?: ParseArg | unknown, defaultValue?: unknown): this;
+    /** `-f80` as `--flag=80` (default) versus `-fb` as `-f -b`. */
+    combineFlagAndOptionalValue(combine?: boolean): this;
+    allowUnknownOption(allowUnknown?: boolean): this;
+    allowExcessArguments(allowExcess?: boolean): this;
+    /** Global options before subcommands only, so subcommands may reuse option names. */
+    enablePositionalOptions(positional?: boolean): this;
+    /** Options after the first command-argument are passed through, not parsed. */
+    passThroughOptions(passThrough?: boolean): this;
+    _checkForBrokenPassThrough(): void;
+    storeOptionsAsProperties(storeAsProperties?: boolean): this;
+    getOptionValue(key: string): unknown;
+    setOptionValue(key: string, value: unknown): this;
+    /** `source` is default | config | env | cli | implied. */
+    setOptionValueWithSource(key: string, value: unknown, source: string | undefined): this;
+    getOptionValueSource(key: string): string | undefined;
+    /** Globals overwrite locals, like optsWithGlobals. */
+    getOptionValueSourceWithGlobals(key: string): string | undefined;
+    /** User args from argv per `from`; sets `_scriptPath` and the default program name. */
+    _prepareUserArgs(argv: readonly string[] | undefined, parseOptions?: ParseOptions): string[];
+    /**
+     * Parse argv, set options and run commands. Use `parseAsync` when an action is async.
+     * With no arguments, parses process.argv and auto-detects Electron and `node --eval`.
+     */
+    parse(argv?: readonly string[], parseOptions?: BurgeeParseOptions): this;
+    parseAsync(argv?: readonly string[], parseOptions?: BurgeeParseOptions): Promise<this>;
+    _prepareForParse(): void;
+    /** Called lazily on first parse; available for subclasses to save custom state. */
+    saveStateBeforeParse(): void;
+    restoreStateBeforeParse(): void;
+    _checkForMissingExecutable(executableFile: string, executableDir: string, subcommandName: string): void;
+    _executeSubCommand(subcommand: Command, args: string[]): void;
+    _dispatchSubcommand(commandName: string, operands: string[], unknown: string[]): unknown;
+    /** `help foo`: invoke help directly if possible, or dispatch if necessary. */
+    _dispatchHelpCommand(subcommandName: string | undefined): unknown;
+    _checkNumberOfArguments(): void;
+    /** Process this.args against registeredArguments into this.processedArgs. */
+    _processArguments(): void;
+    /** Chain once we have a promise; call synchronously until then. */
+    _chainOrCall(promise: unknown, fn: () => unknown): unknown;
+    _chainOrCallHooks(promise: unknown, event: HookEvent): unknown;
+    _chainOrCallSubCommandHook(promise: unknown, subCommand: Command, event: HookEvent): unknown;
+    /** Process arguments in the context of this command; returns the action result in case it is a promise. */
+    _parseCommand(operands: string[], unknown: string[]): unknown;
+    _findCommand(name: string | undefined): Command | undefined;
+    _findOption(arg: string): Option | undefined;
+    /** Walks up the hierarchy so a subcommand can check after displaying help. */
+    _checkForMissingMandatoryOptions(): void;
+    _checkForConflictingLocalOptions(): void;
+    _checkForConflictingOptions(): void;
+    /**
+     * Parse options from `args`, removing known options, and return argv split into
+     * operands and unknown arguments. Side effect: stores option values on the command.
+     *
+     *     --known kkk op => [op], []
+     *     op --known kkk => [op], []
+     *     sub --unknown uuu op => [sub], [--unknown uuu op]
+     *     sub -- --unknown uuu op => [sub --unknown uuu op], []
+     */
+    parseOptions(args: string[]): {
+        operands: string[];
+        unknown: string[];
+    };
+    /** Local option values as key-value pairs. */
+    opts(): Record<string, unknown>;
+    /** Merged local and global option values; globals overwrite locals. */
+    optsWithGlobals(): Record<string, unknown>;
+    /** Display an error message and exit (or call exitOverride). */
+    error(message: string, errorOptions?: ErrorOptions): never;
+    /** Apply environment variables to options that have no value from the cli or client code. */
+    _parseOptionsEnv(): void;
+    /** Apply implied option values where the option is undefined or at its default. */
+    _parseOptionsImplied(): void;
+    missingArgument(name: string): never;
+    optionMissingArgument(option: Option): never;
+    missingMandatoryOptionValue(option: Option): never;
+    _conflictingOption(option: Option, conflictingOption: Option): never;
+    unknownOption(flag: string): void;
+    _excessArguments(receivedArgs: string[]): void;
+    unknownCommand(): never;
+    /** Get or set the version; registers `-V, --version` (or the given flags). */
+    version(): string | undefined;
+    version(str: string, flags?: string, description?: string): this;
+    description(): string;
+    description(str: string, argsDescription?: Record<string, string>): this;
+    /** Summary, used when listed as a subcommand of the parent. */
+    summary(): string;
+    summary(str: string): this;
+    /** Add an alias; only the first is shown in help. */
+    alias(): string | undefined;
+    alias(alias: string): this;
+    aliases(): string[];
+    aliases(aliases: string[]): this;
+    usage(): string;
+    usage(str: string): this;
+    name(): string;
+    name(str: string): this;
+    helpGroup(): string;
+    helpGroup(heading: string): this;
+    /** Default help group for subcommands added to this command. */
+    commandsGroup(): string;
+    commandsGroup(heading: string): this;
+    /** Default help group for options added to this command. */
+    optionsGroup(): string;
+    optionsGroup(heading: string): this;
+    _initOptionGroup(option: Option): void;
+    _initCommandGroup(cmd: Command): void;
+    /** Name the command from a script filename, such as process.argv[1] or import.meta.filename. */
+    nameFromFilename(filename: string): this;
+    executableDir(): string | null;
+    executableDir(dir: string): this;
+    helpInformation(contextOptions?: OutputContext): string;
+    _getOutputContext(contextOptions?: OutputContext): {
+        error: boolean;
+        write: (str: string) => void;
+        hasColors: boolean | undefined;
+        helpWidth: number | undefined;
+    };
+    /** Output built-in help plus any text added with `addHelpText`. */
+    outputHelp(contextOptions?: OutputContext | ((text: string) => string | Buffer)): void;
+    /** Customise the built-in help option, or pass false to disable it. */
+    helpOption(flags?: string | boolean, description?: string): this;
+    /** Lazily created; null once disabled with `helpOption(false)`. */
+    _getHelpOption(): Option | null;
+    addHelpOption(option: Option): this;
+    /** Output help and exit. */
+    help(contextOptions?: OutputContext | ((text: string) => string | Buffer)): never;
+    /** Extra help text: 'before'/'after' for this command, 'beforeAll'/'afterAll' for its subcommands too. */
+    addHelpText(position: AddHelpTextPosition, text: string | ((context: AddHelpTextContext) => string)): this;
+    _outputHelpIfRequested(args: string[]): void;
+    _root(): Command;
+    /**
+     * The manifest every surface reads. Projected from the command tree on each access,
+     * so it is never stale; plugin-contributed nodes are kept across projections.
+     */
+    get manifest(): Manifest;
+    _project(manifest: Manifest): void;
+    /** Options as the manifest describes them, on a null-prototype record. */
+    _optionSpecs(): Record<string, OptionSpec>;
+    /** burgee: declare what the command does to the world (N6). This is what exposes it as an MCP tool (N2). */
+    effects(value: Effects): this;
+    /**
+     * burgee: `--schema` and `--mcp` on a commander-syntax program, from its manifest (J2).
+     * Only when the program declares neither option itself; `--mcp` runs commands through
+     * this very program with the streams captured, so tool results are the `--json` envelope.
+     */
+    _burgeeSurface(userArgs: string[]): boolean | Promise<boolean>;
+    /** The surfaces after `completion`: `--schema` is synchronous, `--mcp` serves until stdin closes. */
+    _burgeeSurfaceRest(head: string[], declared: (flag: string) => boolean): boolean | Promise<boolean>;
+    /** Additive, and the point of the whole exercise: plugins commander has never had (#2505, unlanded). */
+    use(plugin: Plugin): this;
+    /** Inject the streams and the exit for one parse; returns commander's own parse options. */
+    _prepareBurgee(parseOptions?: BurgeeParseOptions): ParseOptions | undefined;
+    /** In burgee mode the whole run settles to one E1 exit; otherwise commander's behaviour, untouched. */
+    _runBurgee(run: () => unknown): unknown;
+    /** `--json` that no command in the chain declared is burgee's envelope, not an unknown option. */
+    _takeJson(unknown: string[]): void;
+    /** The action, wrapped in the plugin hooks and followed by the envelope or the rendering. */
+    _runAction(): unknown;
+    /** burgee: where every option value came from, from commander's own value sources (V3). */
+    _provenance(): Record<string, {
+        source: string;
+    }>;
+    _emitResult(value: unknown): void;
+}
+/**
+ * The common colour conventions: NO_COLOR and FORCE_COLOR=0/false disable, FORCE_COLOR
+ * and CLICOLOR_FORCE enable, otherwise undecided (the stream's TTY-ness decides).
+ */
+export declare function useColor(): boolean | undefined;
+export {};