burgee 0.7.0 → 0.8.0

package/dist/commander/command.js

@@ -2,21 +2,6 @@ import { EventEmitter } from 'node:events';
 import fs from 'node:fs';
 import path from 'node:path';
 import { stripVTControlCharacters } from 'node:util';
-/**
- * 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).
- */
-// eslint-disable-next-line import-next/no-namespace -- `spawn` is read off the namespace at the call site and never captured into a local. commander's own suite mocks `childProcess.spawn` in roughly 23 `executableSubcommand` cases, and a binding captured at import never re-syncs; bellpull's `cross-spawn.ts` reads `spawn` off its default import for this exact consumer, so a named import here would undo that and take the row from 1360 / 1360 to ungradeable.
 import * as crossSpawn from 'bellpull/cross-spawn';
 import { ExitCode } from '../exit-code.js';
 import { Manifest } from '../manifest.js';
@@ -28,7 +13,6 @@ 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'];
@@ -36,12 +20,10 @@ 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':
@@ -56,7 +38,6 @@ 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 '';
@@ -74,12 +55,9 @@ 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;
@@ -108,7 +86,6 @@ export class Command extends EventEmitter {
     _savedState = null;
     _outputConfiguration;
     _hidden = false;
-    /** Lazy created on demand; null once disabled. */
     _helpOption = undefined;
     _addImplicitHelpCommand = undefined;
     _helpCommand = undefined;
@@ -119,14 +96,10 @@ 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();
@@ -143,7 +116,6 @@ 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;
@@ -191,7 +163,6 @@ export class Command extends EventEmitter {
             return this;
         return cmd;
     }
-    /** Factory for an unattached command; override to customise subcommands. */
     createCommand(name) {
         return new Command(name);
     }
@@ -263,7 +234,6 @@ 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;
@@ -320,25 +290,21 @@ 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.
         }
         return host.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;
@@ -353,7 +319,6 @@ 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);
@@ -401,7 +366,6 @@ 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)
@@ -419,7 +383,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
                 else if (option.isBoolean() || option.optional)
                     value = true;
                 else
-                    value = ''; // not normal, parseArg might have failed or be a mock function for testing
+                    value = '';
             }
             this.setOptionValueWithSource(name, value, valueSource);
         };
@@ -443,7 +407,6 @@ 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);
@@ -461,7 +424,6 @@ 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;
@@ -474,12 +436,10 @@ 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();
@@ -506,7 +466,6 @@ 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;
@@ -518,7 +477,6 @@ 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()) {
@@ -527,7 +485,6 @@ 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');
@@ -537,7 +494,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
                 parseOptions.from = 'electron';
             const execArgv = host.execArgv ?? [];
             if (execArgv.includes('-e') || execArgv.includes('--eval') || execArgv.includes('-p') || execArgv.includes('--print')) {
-                parseOptions.from = 'eval'; // internal usage, not documented
+                parseOptions.from = 'eval';
             }
         }
         if (argv === undefined)
@@ -573,17 +530,10 @@ 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))
@@ -596,8 +546,6 @@ 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))
@@ -608,7 +556,6 @@ 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-/, '--');
@@ -622,7 +569,6 @@ 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,
@@ -668,7 +614,6 @@ 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}`;
@@ -685,7 +630,6 @@ 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)
@@ -694,10 +638,6 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
             executableFile = localFile || executableFile;
         }
         const launchWithNode = SOURCE_EXT.includes(path.extname(executableFile));
-        // Through `bellpull`, not `node:child_process`: it resolves the executable properly on
-        // Windows, where upstream sends every spawn through `node` to dodge `PATHEXT`. The
-        // reasoning, the measurement and the mock constraint are in `weight.test.ts`'s
-        // `./commander` entry — they are prose, and prose in this file ships.
         let proc;
         if (host.platform !== 'win32') {
             if (launchWithNode) {
@@ -717,12 +657,10 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
                 proc = crossSpawn.spawn(host.execPath, args, { stdio: 'inherit' });
             }
             else {
-                // The case upstream cannot reach: a `.cmd`, a `.bat`, or a shebang that is not node.
                 proc = crossSpawn.spawn(executableFile, args, { stdio: 'inherit' });
             }
         }
         if (!proc.killed) {
-            // Testing mainly to avoid leak warnings during unit tests with mocked spawn.
             for (const signal of FORWARDED_SIGNALS) {
                 host.on(signal, () => {
                     if (proc.killed === false && proc.exitCode === null)
@@ -732,7 +670,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
         }
         const exitCallback = this._exitCallback;
         proc.on('close', (code) => {
-            code = code ?? 1; // null when the spawned process terminated due to a signal
+            code = code ?? 1;
             if (!exitCallback)
                 host.exit(code);
             else
@@ -772,14 +710,12 @@ 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',
         ]);
@@ -795,7 +731,6 @@ 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;
@@ -828,7 +763,6 @@ 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());
@@ -855,15 +789,12 @@ 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(); // after cli, so parseArg not called on both cli and env
+        this._parseOptionsEnv();
         this._parseOptionsImplied();
         operands = operands.concat(parsed.operands);
         unknown = parsed.unknown;
-        if (this._actionHandler && !this._findCommand(operands[0]) && !this._defaultCommandName)
-            this._takeJson(unknown);
         this.args = operands.concat(unknown);
         if (operands && this._findCommand(operands[0])) {
             return this._dispatchSubcommand(operands[0] ?? '', operands.slice(1), unknown);
@@ -873,17 +804,15 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
             return this._dispatchHelpCommand(operands[1]);
         }
         if (this._defaultCommandName) {
-            this._outputHelpIfRequested(unknown); // help for the default command comes from the parent
+            this._outputHelpIfRequested(unknown);
             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] ?? '');
@@ -897,7 +826,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); // legacy
+                    this.parent?.emit(commandEvent, operands, unknown);
                 });
             }
             promiseChain = this._chainOrCallHooks(promiseChain, 'postAction');
@@ -906,15 +835,13 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
         if (this.parent?.listenerCount(commandEvent)) {
             checkForUnknownOptions();
             this._processArguments();
-            this.parent.emit(commandEvent, operands, unknown); // legacy
+            this.parent.emit(commandEvent, operands, unknown);
         }
         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) {
@@ -927,13 +854,11 @@ 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;
     }
@@ -945,7 +870,6 @@ 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) {
@@ -973,15 +897,6 @@ 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 = [];
@@ -990,11 +905,10 @@ 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; // working through a group of short options, like -abc
+        let activeGroup = null;
         let i = 0;
         while (i < args.length || activeGroup) {
             const arg = activeGroup ?? args[i++] ?? '';
@@ -1021,7 +935,6 @@ 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;
@@ -1035,8 +948,13 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
                     activeVariadicOption = option.variadic ? option : null;
                     continue;
                 }
+                if (arg === '--json' && !this._root()._declares('--json')) {
+                    const root = this._root();
+                    root._burgee ??= { exit: undefined, json: false };
+                    root._burgee.json = true;
+                    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) {
@@ -1050,7 +968,6 @@ 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));
@@ -1059,13 +976,9 @@ 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);
@@ -1081,7 +994,6 @@ 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;
@@ -1090,7 +1002,6 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
         }
         return { operands, unknown };
     }
-    /** Local option values as key-value pairs. */
     opts() {
         if (this._storeOptionsAsProperties) {
             const result = {};
@@ -1102,31 +1013,40 @@ 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') {
-            this._outputConfiguration.writeErr(`${this._showHelpAfterError}\n`);
-        }
-        else if (this._showHelpAfterError) {
-            this._outputConfiguration.writeErr('\n');
-            this.outputHelp({ error: true });
-        }
         const config = errorOptions ?? {};
         const exitCode = config.exitCode || 1;
         const code = config.code || 'commander.error';
+        if (this._root()._burgee?.json === true)
+            this._reportJson(code, message);
+        else {
+            this._outputConfiguration.outputError(`${message}\n`, this._outputConfiguration.writeErr);
+            if (typeof this._showHelpAfterError === 'string') {
+                this._outputConfiguration.writeErr(`${this._showHelpAfterError}\n`);
+            }
+            else if (this._showHelpAfterError) {
+                this._outputConfiguration.writeErr('\n');
+                this.outputHelp({ error: true });
+            }
+        }
         this._exit(exitCode, code, message);
     }
-    /** Apply environment variables to options that have no value from the cli or client code. */
+    _reportJson(code, message) {
+        const burgee = this._root()._burgee;
+        if (burgee === undefined || !burgee.json || burgee.reported)
+            return;
+        burgee.reported = true;
+        const [first = '', ...rest] = message.replace(/^error: /, '').split('\n');
+        const guess = /\(Did you mean (\S+)\?\)/.exec(rest.join(''));
+        this._outputConfiguration.writeOut(`${JSON.stringify({ ok: false, error: { code, message: first, ...(guess === null ? {} : { fix: guess[1] }) } })}\n`);
+    }
     _parseOptionsEnv() {
         for (const option of this.options) {
             if (option.envVar && option.envVar in host.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()}`, host.env[option.envVar]);
@@ -1136,7 +1056,6 @@ 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) ?? '');
@@ -1160,7 +1079,6 @@ 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);
@@ -1188,7 +1106,6 @@ 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 {
@@ -1265,7 +1182,6 @@ 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)
@@ -1329,7 +1245,6 @@ 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;
@@ -1376,7 +1291,6 @@ 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') {
@@ -1398,17 +1312,16 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
         outputContext.write(String(helpInformation));
         const helpLong = this._getHelpOption()?.long;
         if (helpLong)
-            this.emit(helpLong); // deprecated
+            this.emit(helpLong);
         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; // reenable
+                    this._helpOption = undefined;
                 if (this._defaultOptionGroup) {
                     const helpOption = this._getHelpOption();
                     if (helpOption)
@@ -1416,7 +1329,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
                 }
             }
             else {
-                this._helpOption = null; // disable
+                this._helpOption = null;
             }
             return this;
         }
@@ -1425,7 +1338,6 @@ 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);
@@ -1436,16 +1348,13 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
         this._initOptionGroup(option);
         return this;
     }
-    /** Output help and exit. */
     help(contextOptions) {
         this.outputHelp(contextOptions);
         let exitCode = Number(host.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.
@@ -1465,17 +1374,12 @@ 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();
@@ -1507,7 +1411,6 @@ 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) {
@@ -1526,32 +1429,19 @@ 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) {
-            // 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') {
@@ -1563,21 +1453,19 @@ Expecting one of '${HELP_POSITIONS.join("', '")}'`);
                     root._outputConfiguration.writeOut(renderCompletion(this.manifest, known));
                     return true;
                 }
-                return this._burgeeSurfaceRest(head, declared);
+                return this._burgeeSurfaceRest(head);
             });
         }
-        return this._burgeeSurfaceRest(head, declared);
+        return this._burgeeSurfaceRest(head);
     }
-    /** The surfaces after `completion`: `--schema` is synchronous, `--mcp` serves until stdin closes. */
-    _burgeeSurfaceRest(head, declared) {
+    _burgeeSurfaceRest(head) {
         const root = this._root();
-        if (head.includes('--schema') && !declared('--schema')) {
-            // 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.
+        if (head.includes('--schema') && !root._declares('--schema')) {
             root._outputConfiguration.writeOut(`${machineJson(schemaOf(this.manifest), head)}\n`);
             return true;
         }
-        if (head[0] === '--mcp' && !declared('--mcp')) {
+        if (head[0] === '--mcp' && !root._declares('--mcp')) {
+            const writeOut = root._outputConfiguration.writeOut;
             const invoke = async (args) => {
                 const out = [];
                 const err = [];
@@ -1585,16 +1473,14 @@ Expecting one of '${HELP_POSITIONS.join("', '")}'`);
                 await root.parseAsync(args, { from: 'user', stdout: { write: (s) => out.push(s) }, stderr: { write: (s) => err.push(s) }, exit: (c) => void (code = c) });
                 return { stdout: out.join(''), stderr: err.join(''), code };
             };
-            return serveMcp(this.manifest, { input: host.stdin, output: { write: (s) => root._outputConfiguration.writeOut(s) }, invoke }).then(() => true);
+            return serveMcp(this.manifest, { input: host.stdin, output: { write: writeOut }, invoke }).then(() => true);
         }
         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;
@@ -1621,7 +1507,6 @@ 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;
@@ -1633,15 +1518,14 @@ Expecting one of '${HELP_POSITIONS.join("', '")}'`);
         };
         const fail = (err) => {
             if (err instanceof CommanderError) {
-                if (burgee.json && err.code !== 'commander.helpDisplayed' && err.code !== 'commander.version') {
-                    root._outputConfiguration.writeOut(`${JSON.stringify({ ok: false, error: { code: err.code, message: err.message } })}\n`);
-                }
+                if (err.code !== 'commander.helpDisplayed' && err.code !== 'commander.version')
+                    root._reportJson(err.code, err.message);
                 finish(e1(err));
                 return;
             }
             const message = err instanceof Error ? err.message : String(err);
             if (burgee.json)
-                root._outputConfiguration.writeOut(`${JSON.stringify({ ok: false, error: { code: 'runtime', message } })}\n`);
+                root._reportJson('runtime', message);
             else
                 root._outputConfiguration.writeErr(`error: ${message}\n`);
             finish(ExitCode.RUNTIME);
@@ -1658,20 +1542,9 @@ 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');
-        if (index === -1 || (terminator !== -1 && index > terminator))
-            return;
-        if (this._getCommandAndAncestors().some((cmd) => cmd._findOption('--json')))
-            return;
-        unknown.splice(index, 1);
-        const root = this._root();
-        root._burgee ??= { exit: undefined, json: false };
-        root._burgee.json = true;
+    _declares(flag) {
+        return this._findOption(flag) !== undefined || this.commands.some((sub) => sub._declares(flag));
     }
-    /** The action, wrapped in the plugin hooks and followed by the envelope or the rendering. */
     _runAction() {
         const handler = this._actionHandler;
         if (handler === null)
@@ -1694,7 +1567,6 @@ 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;
@@ -1702,7 +1574,6 @@ Expecting one of '${HELP_POSITIONS.join("', '")}'`);
         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' };
@@ -1725,9 +1596,7 @@ 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;
@@ -1755,10 +1624,6 @@ 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 (host.env['NO_COLOR'] || host.env['FORCE_COLOR'] === '0' || host.env['FORCE_COLOR'] === 'false')
         return false;
@@ -1766,4 +1631,3 @@ export function useColor() {
         return true;
     return undefined;
 }
-//# sourceMappingURL=command.js.map