burgee 0.2.0 → 0.4.0

package/dist/{commander-command.js → commander/command.js}

@@ -1,18 +1,33 @@
+/**
+ * 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 fs from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
 import { stripVTControlCharacters } from 'node:util';
-import { Argument, humanReadableArgName } from './commander-argument.js';
-import { CommanderError } from './commander-error.js';
-import { Help } from './commander-help.js';
-import { DualOptions, Option } from './commander-option.js';
-import { suggestSimilar } from './commander-suggest.js';
-import { ExitCode } from './exit-code.js';
-import { Manifest } from './manifest.js';
-import { serveMcp } from './mcp.js';
-import { schemaOf } from './schema.js';
+import { ExitCode } from '../exit-code.js';
+import { Manifest } from '../manifest.js';
+import { serveMcp } from '../mcp.js';
+import { machineJson, schemaOf } from '../schema.js';
+import { suggestSimilar } from '../suggest.js';
+import { Argument, humanReadableArgName } from './argument.js';
+import { CommanderError } from './error.js';
+import { Help } from './help.js';
+import { DualOptions, Option } from './option.js';
+/** Names that would reach Object.prototype if used as an option key. */
 const POLLUTING = new Set(['__proto__', 'constructor', 'prototype']);
 const ENV_SOURCES = ['default', 'config', 'env'];
 const IMPLIED_SOURCES = ['default', 'implied'];
@@ -20,10 +35,12 @@ const HOOK_EVENTS = ['preSubcommand', 'preAction', 'postAction'];
 const HELP_POSITIONS = ['beforeAll', 'before', 'after', 'afterAll'];
 const SOURCE_EXT = ['.js', '.ts', '.tsx', '.mjs', '.cjs'];
 const FORWARDED_SIGNALS = ['SIGUSR1', 'SIGUSR2', 'SIGTERM', 'SIGINT', 'SIGHUP'];
+/** Wraps in single quotes. Used where a message says "from" right before a quoted method name, which a static import scanner would otherwise read as a specifier. */
 const quoted = (s) => `'${s}'`;
 function isThenable(value) {
     return typeof value?.then === 'function';
 }
+/** commander's exit codes, read through burgee's taxonomy when the exit is injected (E1). */
 function e1(err) {
     switch (err.code) {
         case 'commander.helpDisplayed':
@@ -38,6 +55,7 @@ function e1(err) {
             return err.exitCode === 1 ? ExitCode.USAGE : err.exitCode;
     }
 }
+/** What a run prints for an action's return value when the streams are injected. */
 function render(value) {
     if (value === undefined || value === null)
         return '';
@@ -55,9 +73,12 @@ export class Command extends EventEmitter {
     options = [];
     parent = null;
     registeredArguments = [];
+    /** @deprecated old name for registeredArguments */
     _args;
+    /** cli args with options removed */
     args = [];
     rawArgs = [];
+    /** like .args but after custom processing and collecting variadic */
     processedArgs = [];
     runningCommand = undefined;
     _allowUnknownOption = false;
@@ -86,6 +107,7 @@ export class Command extends EventEmitter {
     _savedState = null;
     _outputConfiguration;
     _hidden = false;
+    /** Lazy created on demand; null once disabled. */
     _helpOption = undefined;
     _addImplicitHelpCommand = undefined;
     _helpCommand = undefined;
@@ -96,8 +118,14 @@ export class Command extends EventEmitter {
     _version = undefined;
     _versionOptionName = undefined;
     _usage = undefined;
+    /** burgee: the root's projection, created on first use. */
     _manifest = undefined;
+    /** burgee: what this command does to the world (N6); declaring it exposes the command as an MCP tool. */
     _effects = undefined;
+    /** burgee: `true`, or the replacement's name (M5). Shown in help, schema and a one-line warning on use. */
+    _deprecated = undefined;
+    _deprecationWarned = false;
+    /** burgee: set for the duration of a parse that injected the streams or the exit. */
     _burgee = undefined;
     constructor(name) {
         super();
@@ -114,6 +142,7 @@ export class Command extends EventEmitter {
             stripColor: (str) => stripVTControlCharacters(str),
         };
     }
+    /** Copy settings useful to share between the root and its subcommands. */
     copyInheritedSettings(sourceCommand) {
         this._outputConfiguration = sourceCommand._outputConfiguration;
         this._helpOption = sourceCommand._helpOption;
@@ -161,6 +190,7 @@ export class Command extends EventEmitter {
             return this;
         return cmd;
     }
+    /** Factory for an unattached command; override to customise subcommands. */
     createCommand(name) {
         return new Command(name);
     }
@@ -232,6 +262,7 @@ export class Command extends EventEmitter {
         this.registeredArguments.push(argument);
         return this;
     }
+    /** Customise or disable the default help command (added by default when there are subcommands). */
     helpCommand(enableOrNameAndArgs, description) {
         if (typeof enableOrNameAndArgs === 'boolean') {
             this._addImplicitHelpCommand = enableOrNameAndArgs;
@@ -288,21 +319,25 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
             this._lifeCycleHooks[event] = [listener];
         return this;
     }
+    /** Replace the call to process.exit; defaults to throwing the CommanderError. */
     exitOverride(fn) {
         this._exitCallback =
             fn ??
                 ((err) => {
                     if (err.code !== 'commander.executeSubCommandAsync')
                         throw err;
+                    // Async callback from spawn events, not useful to throw.
                 });
         return this;
     }
     _exit(exitCode, code, message) {
         if (this._exitCallback) {
             this._exitCallback(new CommanderError(exitCode, code, message));
+            // Expecting this line is not reached.
         }
         process.exit(exitCode);
     }
+    // commander's contract: the positional args, then the options, then the command itself.
     action(fn) {
         const listener = (args) => {
             const expectedArgsCount = this.registeredArguments.length;
@@ -317,6 +352,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
     createOption(flags, description) {
         return new Option(flags, description);
     }
+    /** Wrap parseArg to turn `commander.invalidArgument` into an error with context. */
     _callParseArg(target, value, previous, invalidArgumentMessage) {
         try {
             return target.parseArg?.(value, previous);
@@ -364,6 +400,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
         if (option.defaultValue !== undefined) {
             this.setOptionValueWithSource(name, option.defaultValue, 'default');
         }
+        // val is null for an optional option used without its argument, undefined for boolean and negated.
         const handleOptionValue = (val, invalidValueMessage, valueSource) => {
             let value = val;
             if (value == null && option.presetArg !== undefined)
@@ -381,7 +418,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
                 else if (option.isBoolean() || option.optional)
                     value = true;
                 else
-                    value = '';
+                    value = ''; // not normal, parseArg might have failed or be a mock function for testing
             }
             this.setOptionValueWithSource(name, value, valueSource);
         };
@@ -405,6 +442,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
             option.default(defaultValue).argParser(fn);
         }
         else if (fn instanceof RegExp) {
+            // deprecated
             const regex = fn;
             option.default(defaultValue).argParser((val, def) => {
                 const m = regex.exec(val);
@@ -422,6 +460,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
     requiredOption(flags, description, parseArg, defaultValue) {
         return this._optionEx({ mandatory: true }, flags, description, parseArg, defaultValue);
     }
+    /** `-f80` as `--flag=80` (default) versus `-fb` as `-f -b`. */
     combineFlagAndOptionalValue(combine = true) {
         this._combineFlagAndOptionalValue = !!combine;
         return this;
@@ -434,10 +473,12 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
         this._allowExcessArguments = !!allowExcess;
         return this;
     }
+    /** Global options before subcommands only, so subcommands may reuse option names. */
     enablePositionalOptions(positional = true) {
         this._enablePositionalOptions = !!positional;
         return this;
     }
+    /** Options after the first command-argument are passed through, not parsed. */
     passThroughOptions(passThrough = true) {
         this._passThroughOptions = !!passThrough;
         this._checkForBrokenPassThrough();
@@ -464,6 +505,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
     setOptionValue(key, value) {
         return this.setOptionValueWithSource(key, value, undefined);
     }
+    /** `source` is default | config | env | cli | implied. */
     setOptionValueWithSource(key, value, source) {
         if (this._storeOptionsAsProperties)
             this[key] = value;
@@ -475,6 +517,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
     getOptionValueSource(key) {
         return this._optionValueSources[key];
     }
+    /** Globals overwrite locals, like optsWithGlobals. */
     getOptionValueSourceWithGlobals(key) {
         let source;
         for (const cmd of this._getCommandAndAncestors()) {
@@ -483,6 +526,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
         }
         return source;
     }
+    /** User args from argv per `from`; sets `_scriptPath` and the default program name. */
     _prepareUserArgs(argv, parseOptions) {
         if (argv !== undefined && !Array.isArray(argv))
             throw new Error('first parameter to parse must be array or undefined');
@@ -492,7 +536,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
                 parseOptions.from = 'electron';
             const execArgv = process.execArgv ?? [];
             if (execArgv.includes('-e') || execArgv.includes('--eval') || execArgv.includes('-p') || execArgv.includes('--print')) {
-                parseOptions.from = 'eval';
+                parseOptions.from = 'eval'; // internal usage, not documented
             }
         }
         if (argv === undefined)
@@ -528,10 +572,17 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
         this._name = this._name || 'program';
         return userArgs;
     }
+    /**
+     * 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, parseOptions) {
         const from = this._prepareBurgee(parseOptions);
         this._prepareForParse();
         const userArgs = this._prepareUserArgs(argv, from);
+        // The surface check is synchronous unless a surface is actually served (completions,
+        // --mcp), so a synchronous action has run by the time parse() returns — commander's
+        // contract, which its suite asserts on after every parse(). commander-sync.test.ts.
         this._runBurgee(() => {
             const served = this._burgeeSurface(userArgs);
             if (isThenable(served))
@@ -544,6 +595,8 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
         const from = this._prepareBurgee(parseOptions);
         this._prepareForParse();
         const userArgs = this._prepareUserArgs(argv, from);
+        // Same synchronous start as parse(): a preAction hook has run before the promise is
+        // handed back, which commander's hook tests assert on.
         await this._runBurgee(() => {
             const served = this._burgeeSurface(userArgs);
             if (isThenable(served))
@@ -554,6 +607,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
     }
     _prepareForParse() {
         if (this._savedState === null) {
+            // Lone negated option (--no-foo without --foo) defaults to true, now that all options are known.
             for (const option of this.options) {
                 if (option.negate && option.defaultValue === undefined && this.getOptionValue(option.attributeName()) === undefined) {
                     const positiveLongFlag = (option.long ?? '').replace(/^--no-/, '--');
@@ -567,6 +621,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
             this.restoreStateBeforeParse();
         }
     }
+    /** Called lazily on first parse; available for subclasses to save custom state. */
     saveStateBeforeParse() {
         this._savedState = {
             _name: this._name,
@@ -612,6 +667,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
             const foundExt = SOURCE_EXT.find((ext) => fs.existsSync(`${localBin}${ext}`));
             return foundExt ? `${localBin}${foundExt}` : undefined;
         };
+        // Not checking for help first: can't robustly test for help flags in an external command.
         this._checkForMissingMandatoryOptions();
         this._checkForConflictingOptions();
         let executableFile = subcommand._executableFile || `${this._name}-${subcommand._name}`;
@@ -628,6 +684,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
         }
         if (executableDir) {
             let localFile = findFile(executableDir, executableFile);
+            // Legacy search using the script name as prefix instead of the command name.
             if (!localFile && !subcommand._executableFile && this._scriptPath) {
                 const legacyName = path.basename(this._scriptPath, path.extname(this._scriptPath));
                 if (legacyName !== this._name)
@@ -654,6 +711,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
             proc = childProcess.spawn(process.execPath, args, { stdio: 'inherit' });
         }
         if (!proc.killed) {
+            // Testing mainly to avoid leak warnings during unit tests with mocked spawn.
             for (const signal of FORWARDED_SIGNALS) {
                 process.on(signal, () => {
                     if (proc.killed === false && proc.exitCode === null)
@@ -663,7 +721,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
         }
         const exitCallback = this._exitCallback;
         proc.on('close', (code) => {
-            code = code ?? 1;
+            code = code ?? 1; // null when the spawned process terminated due to a signal
             if (!exitCallback)
                 process.exit(code);
             else
@@ -703,12 +761,14 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
         });
         return promiseChain;
     }
+    /** `help foo`: invoke help directly if possible, or dispatch if necessary. */
     _dispatchHelpCommand(subcommandName) {
         if (!subcommandName)
             this.help();
         const subCommand = this._findCommand(subcommandName);
         if (subCommand && !subCommand._executableHandler)
             subCommand.help();
+        // Fallback to parsing the help flag to invoke the help.
         return this._dispatchSubcommand(subcommandName ?? '', [], [
             this._getHelpOption()?.long ?? this._getHelpOption()?.short ?? '--help',
         ]);
@@ -724,6 +784,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
         if (this.args.length > this.registeredArguments.length)
             this._excessArguments(this.args);
     }
+    /** Process this.args against registeredArguments into this.processedArgs. */
     _processArguments() {
         const myParseArg = (argument, value, previous) => {
             let parsedValue = value;
@@ -756,6 +817,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
         });
         this.processedArgs = processedArgs;
     }
+    /** Chain once we have a promise; call synchronously until then. */
     _chainOrCall(promise, fn) {
         if (isThenable(promise))
             return promise.then(() => fn());
@@ -782,9 +844,10 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
         }
         return result;
     }
+    /** Process arguments in the context of this command; returns the action result in case it is a promise. */
     _parseCommand(operands, unknown) {
         const parsed = this.parseOptions(unknown);
-        this._parseOptionsEnv();
+        this._parseOptionsEnv(); // after cli, so parseArg not called on both cli and env
         this._parseOptionsImplied();
         operands = operands.concat(parsed.operands);
         unknown = parsed.unknown;
@@ -799,15 +862,17 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
             return this._dispatchHelpCommand(operands[1]);
         }
         if (this._defaultCommandName) {
-            this._outputHelpIfRequested(unknown);
+            this._outputHelpIfRequested(unknown); // help for the default command comes from the parent
             return this._dispatchSubcommand(this._defaultCommandName, operands, unknown);
         }
         if (this.commands.length && this.args.length === 0 && !this._actionHandler && !this._defaultCommandName) {
+            // probably missing subcommand and no handler, user needs help (and exit)
             this.help({ error: true });
         }
         this._outputHelpIfRequested(parsed.unknown);
         this._checkForMissingMandatoryOptions();
         this._checkForConflictingOptions();
+        // Not always called, to avoid masking a "better" error like unknown command.
         const checkForUnknownOptions = () => {
             if (parsed.unknown.length > 0)
                 this.unknownOption(parsed.unknown[0] ?? '');
@@ -821,7 +886,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
             promiseChain = this._chainOrCall(promiseChain, () => this._runAction());
             if (this.parent) {
                 promiseChain = this._chainOrCall(promiseChain, () => {
-                    this.parent?.emit(commandEvent, operands, unknown);
+                    this.parent?.emit(commandEvent, operands, unknown); // legacy
                 });
             }
             promiseChain = this._chainOrCallHooks(promiseChain, 'postAction');
@@ -830,13 +895,15 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
         if (this.parent?.listenerCount(commandEvent)) {
             checkForUnknownOptions();
             this._processArguments();
-            this.parent.emit(commandEvent, operands, unknown);
+            this.parent.emit(commandEvent, operands, unknown); // legacy
         }
         else if (operands.length) {
             if (this._findCommand('*')) {
+                // legacy default command
                 return this._dispatchSubcommand('*', operands, unknown);
             }
             if (this.listenerCount('command:*')) {
+                // skip option check, emit event for possible misspelling suggestion
                 this.emit('command:*', operands, unknown);
             }
             else if (this.commands.length) {
@@ -849,11 +916,13 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
         }
         else if (this.commands.length) {
             checkForUnknownOptions();
+            // This command has subcommands and nothing hooked up at this level, so display help (and exit).
             this.help({ error: true });
         }
         else {
             checkForUnknownOptions();
             this._processArguments();
+            // fall through for caller to handle after calling .parse()
         }
         return undefined;
     }
@@ -865,6 +934,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
     _findOption(arg) {
         return this.options.find((option) => option.is(arg));
     }
+    /** Walks up the hierarchy so a subcommand can check after displaying help. */
     _checkForMissingMandatoryOptions() {
         for (const cmd of this._getCommandAndAncestors()) {
             for (const anOption of cmd.options) {
@@ -892,6 +962,15 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
         for (const cmd of this._getCommandAndAncestors())
             cmd._checkForConflictingLocalOptions();
     }
+    /**
+     * 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) {
         const operands = [];
         const unknown = [];
@@ -900,10 +979,11 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
         const negativeNumberArg = (arg) => {
             if (!/^-(\d+|\d*\.\d+)(e[+-]?\d+)?$/.test(arg))
                 return false;
+            // a negative number is ok unless a digit is used as an option in the command hierarchy
             return !this._getCommandAndAncestors().some((cmd) => cmd.options.some((opt) => /^-\d$/.test(opt.short ?? '')));
         };
         let activeVariadicOption = null;
-        let activeGroup = null;
+        let activeGroup = null; // working through a group of short options, like -abc
         let i = 0;
         while (i < args.length || activeGroup) {
             const arg = activeGroup ?? args[i++] ?? '';
@@ -930,6 +1010,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
                     }
                     else if (option.optional) {
                         let value = null;
+                        // historical behaviour: the optional value is the following arg unless it is an option
                         const next = args[i];
                         if (i < args.length && next !== undefined && (!maybeOption(next) || negativeNumberArg(next))) {
                             value = next;
@@ -944,6 +1025,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
                     continue;
                 }
             }
+            // Combined short options: eat the first one if known.
             if (arg.length > 2 && arg[0] === '-' && arg[1] !== '-') {
                 const option = this._findOption(`-${arg[1]}`);
                 if (option) {
@@ -957,6 +1039,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
                     continue;
                 }
             }
+            // Known long flag with value, like --foo=bar
             if (/^--[^=]+=/.test(arg)) {
                 const index = arg.indexOf('=');
                 const option = this._findOption(arg.slice(0, index));
@@ -965,9 +1048,13 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
                     continue;
                 }
             }
+            // Not recognised by this command: command-argument, subcommand option, unknown option, or help.
+            // An unknown option makes everything after it unknown too, for a subcommand to reprocess.
+            // A negative number in a leaf command is not an unknown option.
             if (dest === operands && maybeOption(arg) && !(this.commands.length === 0 && negativeNumberArg(arg))) {
                 dest = unknown;
             }
+            // Positional options: stop processing our options at a subcommand.
             if ((this._enablePositionalOptions || this._passThroughOptions) && operands.length === 0 && unknown.length === 0) {
                 if (this._findCommand(arg)) {
                     operands.push(arg);
@@ -983,6 +1070,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
                     break;
                 }
             }
+            // Pass-through options: stop processing options at the first command-argument.
             if (this._passThroughOptions) {
                 dest.push(arg, ...args.slice(i));
                 break;
@@ -991,6 +1079,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
         }
         return { operands, unknown };
     }
+    /** Local option values as key-value pairs. */
     opts() {
         if (this._storeOptionsAsProperties) {
             const result = {};
@@ -1002,9 +1091,11 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
         }
         return this._optionValues;
     }
+    /** Merged local and global option values; globals overwrite locals. */
     optsWithGlobals() {
         return this._getCommandAndAncestors().reduce((combined, cmd) => Object.assign(combined, cmd.opts()), {});
     }
+    /** Display an error message and exit (or call exitOverride). */
     error(message, errorOptions) {
         this._outputConfiguration.outputError(`${message}\n`, this._outputConfiguration.writeErr);
         if (typeof this._showHelpAfterError === 'string') {
@@ -1019,10 +1110,12 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
         const code = config.code || 'commander.error';
         this._exit(exitCode, code, message);
     }
+    /** Apply environment variables to options that have no value from the cli or client code. */
     _parseOptionsEnv() {
         for (const option of this.options) {
             if (option.envVar && option.envVar in process.env) {
                 const optionKey = option.attributeName();
+                // Do not overwrite cli values or values from an unknown (client-code) source.
                 if (this.getOptionValue(optionKey) === undefined || ENV_SOURCES.includes(this.getOptionValueSource(optionKey) ?? '')) {
                     if (option.required || option.optional)
                         this.emit(`optionEnv:${option.name()}`, process.env[option.envVar]);
@@ -1032,6 +1125,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
             }
         }
     }
+    /** Apply implied option values where the option is undefined or at its default. */
     _parseOptionsImplied() {
         const dualHelper = new DualOptions(this.options);
         const hasCustomOptionValue = (optionKey) => this.getOptionValue(optionKey) !== undefined && !IMPLIED_SOURCES.includes(this.getOptionValueSource(optionKey) ?? '');
@@ -1055,6 +1149,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
         this.error(`error: required option '${option.flags}' not specified`, { code: 'commander.missingMandatoryOptionValue' });
     }
     _conflictingOption(option, conflictingOption) {
+        // The caller does not know whether a negated option is the source of the value; take an educated guess.
         const findBestOptionFromValue = (candidate) => {
             const optionKey = candidate.attributeName();
             const optionValue = this.getOptionValue(optionKey);
@@ -1082,6 +1177,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
             return;
         let suggestion = '';
         if (flag.startsWith('--') && this._showSuggestionAfterError) {
+            // Looping to pick up the global options too.
             let candidateFlags = [];
             let command = this;
             do {
@@ -1158,6 +1254,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
         let command = this;
         const last = this.commands[this.commands.length - 1];
         if (this.commands.length !== 0 && last?._executableHandler) {
+            // assume adding an alias for the last added executable subcommand, rather than this
             command = last;
         }
         if (alias === command._name)
@@ -1221,6 +1318,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
         if (this._defaultCommandGroup && !cmd.helpGroup())
             cmd.helpGroup(this._defaultCommandGroup);
     }
+    /** Name the command from a script filename, such as process.argv[1] or import.meta.filename. */
     nameFromFilename(filename) {
         this._name = path.basename(filename, path.extname(filename));
         return this;
@@ -1267,6 +1365,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
         };
         return { error, write, hasColors, helpWidth };
     }
+    /** Output built-in help plus any text added with `addHelpText`. */
     outputHelp(contextOptions) {
         let deprecatedCallback;
         if (typeof contextOptions === 'function') {
@@ -1288,16 +1387,17 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
         outputContext.write(String(helpInformation));
         const helpLong = this._getHelpOption()?.long;
         if (helpLong)
-            this.emit(helpLong);
+            this.emit(helpLong); // deprecated
         this.emit('afterHelp', eventContext);
         for (const command of this._getCommandAndAncestors())
             command.emit('afterAllHelp', eventContext);
     }
+    /** Customise the built-in help option, or pass false to disable it. */
     helpOption(flags, description) {
         if (typeof flags === 'boolean') {
             if (flags) {
                 if (this._helpOption === null)
-                    this._helpOption = undefined;
+                    this._helpOption = undefined; // reenable
                 if (this._defaultOptionGroup) {
                     const helpOption = this._getHelpOption();
                     if (helpOption)
@@ -1305,7 +1405,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
                 }
             }
             else {
-                this._helpOption = null;
+                this._helpOption = null; // disable
             }
             return this;
         }
@@ -1314,6 +1414,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
             this._initOptionGroup(this._helpOption);
         return this;
     }
+    /** Lazily created; null once disabled with `helpOption(false)`. */
     _getHelpOption() {
         if (this._helpOption === undefined)
             this.helpOption(undefined, undefined);
@@ -1324,13 +1425,16 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
         this._initOptionGroup(option);
         return this;
     }
+    /** Output help and exit. */
     help(contextOptions) {
         this.outputHelp(contextOptions);
         let exitCode = Number(process.exitCode ?? 0);
         if (exitCode === 0 && contextOptions && typeof contextOptions !== 'function' && contextOptions.error)
             exitCode = 1;
+        // message: not all displayed text is available, so only a placeholder is passed.
         this._exit(exitCode, 'commander.help', '(outputHelp)');
     }
+    /** Extra help text: 'before'/'after' for this command, 'beforeAll'/'afterAll' for its subcommands too. */
     addHelpText(position, text) {
         if (!HELP_POSITIONS.includes(position)) {
             throw new Error(`Unexpected value for position to addHelpText.
@@ -1350,12 +1454,17 @@ Expecting one of '${HELP_POSITIONS.join("', '")}'`);
             this._exit(0, 'commander.helpDisplayed', '(outputHelp)');
         }
     }
+    // ───── burgee: the manifest projection, plugins, `--json` and the injected seam ─────
     _root() {
         let command = this;
         while (command.parent)
             command = command.parent;
         return 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() {
         const root = this._root();
         root._manifest ??= new Manifest();
@@ -1375,6 +1484,8 @@ Expecting one of '${HELP_POSITIONS.join("', '")}'`);
                 ...(cmd._description ? { description: cmd._description } : {}),
                 ...(cmd._summary ? { summary: cmd._summary } : {}),
                 ...(cmd._effects === undefined ? {} : { effects: cmd._effects }),
+                ...(cmd._deprecated === undefined ? {} : { deprecated: cmd._deprecated }),
+                ...(cmd._helpGroupHeading === undefined || cmd._helpGroupHeading === '' ? {} : { group: cmd._helpGroupHeading }),
                 ...(cmd._hidden ? { hidden: true } : {}),
                 options: cmd._optionSpecs(),
                 arguments: cmd.registeredArguments.map((a) => ({ name: a.name(), required: a.required, variadic: a.variadic, ...(a.description ? { description: a.description } : {}) })),
@@ -1385,6 +1496,7 @@ Expecting one of '${HELP_POSITIONS.join("', '")}'`);
         };
         visit(this, [rootName]);
     }
+    /** Options as the manifest describes them, on a null-prototype record. */
     _optionSpecs() {
         const specs = Object.create(null);
         for (const option of this.options) {
@@ -1403,17 +1515,33 @@ Expecting one of '${HELP_POSITIONS.join("', '")}'`);
         }
         return specs;
     }
+    /** burgee: declare what the command does to the world (N6). This is what exposes it as an MCP tool (N2). */
     effects(value) {
         this._effects = value;
         return this;
     }
+    /**
+     * burgee: mark the command deprecated (M5). Help and `--schema` show it; running it prints
+     * `warning: 'old' is deprecated, use 'new'` on stderr once and goes on, exit unchanged.
+     */
+    deprecate(use) {
+        this._deprecated = use ?? true;
+        return 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) {
         const root = this._root();
+        // Any command in the tree that declares the flag keeps it: the surface is additive only.
         const declared = (flag, at = root) => at._findOption(flag) !== undefined || at.commands.some((sub) => declared(flag, sub));
         const terminator = userArgs.indexOf('--');
         const head = terminator === -1 ? userArgs : userArgs.slice(0, terminator);
         if (head[0] === 'completion' && root._findCommand('completion') === undefined) {
-            return import('./completions.js').then(({ renderCompletion, renderFigSpec, SHELLS }) => {
+            // Loaded on this command only (K6), exactly as the engine does.
+            return import('../completions.js').then(({ renderCompletion, renderFigSpec, SHELLS }) => {
                 const shell = head[1] ?? '';
                 if (shell === 'fig') {
                     root._outputConfiguration.writeOut(`${JSON.stringify(renderFigSpec(this.manifest), null, 2)}\n`);
@@ -1429,10 +1557,13 @@ Expecting one of '${HELP_POSITIONS.join("', '")}'`);
         }
         return this._burgeeSurfaceRest(head, declared);
     }
+    /** The surfaces after `completion`: `--schema` is synchronous, `--mcp` serves until stdin closes. */
     _burgeeSurfaceRest(head, declared) {
         const root = this._root();
         if (head.includes('--schema') && !declared('--schema')) {
-            root._outputConfiguration.writeOut(`${JSON.stringify(schemaOf(this.manifest), null, 2)}\n`);
+            // R1, and the same escape hatch the engine has: `--schema` is burgee's surface, not
+            // commander's, so it answers to E-floor byte discipline rather than to the host.
+            root._outputConfiguration.writeOut(`${machineJson(schemaOf(this.manifest), head)}\n`);
             return true;
         }
         if (head[0] === '--mcp' && !declared('--mcp')) {
@@ -1447,10 +1578,12 @@ Expecting one of '${HELP_POSITIONS.join("', '")}'`);
         }
         return false;
     }
+    /** Additive, and the point of the whole exercise: plugins commander has never had (#2505, unlanded). */
     use(plugin) {
         this.manifest.use(plugin);
         return this;
     }
+    /** Inject the streams and the exit for one parse; returns commander's own parse options. */
     _prepareBurgee(parseOptions) {
         if (parseOptions === undefined)
             return undefined;
@@ -1477,6 +1610,7 @@ Expecting one of '${HELP_POSITIONS.join("', '")}'`);
         visit(root);
         return from;
     }
+    /** In burgee mode the whole run settles to one E1 exit; otherwise commander's behaviour, untouched. */
     _runBurgee(run) {
         const root = this._root();
         const burgee = root._burgee;
@@ -1513,6 +1647,7 @@ Expecting one of '${HELP_POSITIONS.join("', '")}'`);
             return undefined;
         }
     }
+    /** `--json` that no command in the chain declared is burgee's envelope, not an unknown option. */
     _takeJson(unknown) {
         const terminator = unknown.indexOf('--');
         const index = unknown.indexOf('--json');
@@ -1525,10 +1660,12 @@ Expecting one of '${HELP_POSITIONS.join("', '")}'`);
         root._burgee ??= { exit: undefined, json: false };
         root._burgee.json = true;
     }
+    /** The action, wrapped in the plugin hooks and followed by the envelope or the rendering. */
     _runAction() {
         const handler = this._actionHandler;
         if (handler === null)
             return undefined;
+        this._warnDeprecated();
         const root = this._root();
         const manifest = root._manifest;
         const settle = (value) => this._emitResult(value);
@@ -1546,6 +1683,15 @@ Expecting one of '${HELP_POSITIONS.join("', '")}'`);
             settle(value);
         });
     }
+    /** burgee (M5): once per process, on stderr; only for a command that asked, so commander's own output is untouched. */
+    _warnDeprecated() {
+        if (this._deprecated === undefined || this._deprecated === false || this._deprecationWarned)
+            return;
+        this._deprecationWarned = true;
+        const use = typeof this._deprecated === 'string' ? `, use '${this._deprecated}'` : '';
+        this._outputConfiguration.writeErr(`warning: '${this.name()}' is deprecated${use}\n`);
+    }
+    /** burgee: where every option value came from, from commander's own value sources (V3). */
     _provenance() {
         const out = {};
         const names = { cli: 'flag', env: 'env', config: 'config', default: 'default', implied: 'implied' };
@@ -1568,7 +1714,9 @@ Expecting one of '${HELP_POSITIONS.join("', '")}'`);
             this._outputConfiguration.writeOut(text);
     }
 }
+/** Bump inspector ports so a spawned subcommand does not collide with the parent. */
 function incrementNodeInspectorPort(args) {
+    //  --inspect[=[host:]port], --inspect-brk[=[host:]port], --inspect-port=[host:]port
     return args.map((arg) => {
         if (!arg.startsWith('--inspect'))
             return arg;
@@ -1596,6 +1744,10 @@ function incrementNodeInspectorPort(args) {
         return arg;
     });
 }
+/**
+ * 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 function useColor() {
     if (process.env['NO_COLOR'] || process.env['FORCE_COLOR'] === '0' || process.env['FORCE_COLOR'] === 'false')
         return false;
@@ -1603,3 +1755,4 @@ export function useColor() {
         return true;
     return undefined;
 }
+//# sourceMappingURL=command.js.map