burgee 0.2.0 → 0.4.0

package/dist/testing-helpers.d.ts

@@ -8,7 +8,7 @@
 import { Readable } from 'node:stream';
 import { ExitCode } from './exit-code.js';
 import { type Manifest } from './manifest.js';
-import { type Runtime } from './runtime.js';
+import { type Clock, type Runtime } from './runtime.js';
 export interface RunOptions {
     argv: string[];
     env?: Record<string, string>;
@@ -16,6 +16,8 @@ export interface RunOptions {
     cwd?: string;
     /** `true` = every stream is a TTY; an object sets each; default: none is. */
     tty?: boolean | Partial<Runtime['isTTY']>;
+    /** The clock the runtime reports; a fresh `fakeClock()` at 0 when not given. */
+    clock?: FakeClock;
 }
 export interface RunResult {
     code: ExitCode;
@@ -33,7 +35,22 @@ export declare class RuntimeExit extends Error {
 export interface FakeRuntime extends Runtime {
     out: string[];
     err: string[];
+    clock: FakeClock;
 }
+/** A `Clock` that moves only when the test says so (R14): `tick` is the only source of time. */
+export interface FakeClock extends Clock {
+    /**
+     * Advance by `ms`, running every callback that falls due, earliest first, then by order
+     * scheduled. A callback that schedules inside the window runs in the same tick, so one that
+     * reschedules itself at `0` would never leave the loop (real Node yields between turns);
+     * a tick runs at most `TICK_CAP` callbacks and throws, naming the cap, when exceeded.
+     */
+    tick(ms: number): void;
+    /** Callbacks scheduled and neither run nor cancelled. */
+    pending(): number;
+}
+/** Deterministic time for the harness. Starts at `start` (0 by default) and never moves on its own. */
+export declare function fakeClock(start?: number): FakeClock;
 /** A `Runtime` whose every part is under the test's control. */
 export declare function fakeRuntime(opts: RunOptions): FakeRuntime;
 export declare function swapEnv(env: Record<string, string> | undefined): () => void;

package/dist/testing-helpers.js

@@ -9,6 +9,40 @@ export class RuntimeExit extends Error {
         this.name = 'RuntimeExit';
     }
 }
+const TICK_CAP = 1000;
+export function fakeClock(start = 0) {
+    let now = start;
+    let nextId = 0;
+    const timers = [];
+    const remove = (id) => {
+        const at = timers.findIndex((t) => t.id === id);
+        if (at !== -1)
+            timers.splice(at, 1);
+    };
+    return {
+        now: () => now,
+        schedule(fn, ms) {
+            const id = nextId++;
+            timers.push({ id, at: now + Math.max(0, ms), fn });
+            return () => remove(id);
+        },
+        tick(ms) {
+            const until = now + ms;
+            const nextDue = () => timers.filter((t) => t.at <= until).sort((a, b) => a.at - b.at || a.id - b.id)[0];
+            let ran = 0;
+            for (let due = nextDue(); due !== undefined; due = nextDue()) {
+                if (ran === TICK_CAP)
+                    throw new Error(`fakeClock.tick(${ms}) ran ${TICK_CAP} callbacks (TICK_CAP): a callback keeps rescheduling inside the window`);
+                ran += 1;
+                remove(due.id);
+                now = Math.max(now, due.at);
+                due.fn();
+            }
+            now = until;
+        },
+        pending: () => timers.length,
+    };
+}
 function ttyOf(tty) {
     if (tty === true)
         return { stdin: true, stdout: true, stderr: true };
@@ -31,6 +65,7 @@ export function fakeRuntime(opts) {
         exit(code) {
             throw new RuntimeExit(code);
         },
+        clock: opts.clock ?? fakeClock(),
         out,
         err,
     };

package/dist/testing.d.ts

@@ -5,6 +5,6 @@
  * A separate entry point so it is paid for per import (K6): a user's shipped CLI
  * imports `burgee` and never pulls a byte of this.
  */
-export { processRuntime, type Runtime, type Writer } from './runtime.js';
-export { captureConsole, codeOf, fakeRuntime, finish, runBurgee, RuntimeExit, stripAnsi, swapEnv, type FakeRuntime, type RunOptions, type RunResult, } from './testing-helpers.js';
+export { processRuntime, type Clock, type Runtime, type Writer } from './runtime.js';
+export { captureConsole, codeOf, fakeClock, fakeRuntime, finish, runBurgee, RuntimeExit, stripAnsi, swapEnv, type FakeClock, type FakeRuntime, type RunOptions, type RunResult, } from './testing-helpers.js';
 export { ExitCode, isExitCode, type ExitCode as ExitCodeValue } from './exit-code.js';

package/dist/testing.js

@@ -1,3 +1,3 @@
 export { processRuntime } from './runtime.js';
-export { captureConsole, codeOf, fakeRuntime, finish, runBurgee, RuntimeExit, stripAnsi, swapEnv, } from './testing-helpers.js';
+export { captureConsole, codeOf, fakeClock, fakeRuntime, finish, runBurgee, RuntimeExit, stripAnsi, swapEnv, } from './testing-helpers.js';
 export { ExitCode, isExitCode } from './exit-code.js';

package/dist/unknown-option.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `-foo=bar` means three short flags to a parser and one long flag to a person
+ * (citty #237). The more specific reading of the same argv, so it is offered first.
+ */
+export declare function singleDashHint(argv: readonly string[]): string | undefined;
+export declare function unknownOption(cause: unknown, declared: readonly string[]): {
+    message: string;
+    hint: string;
+} | undefined;

package/dist/unknown-option.js

@@ -0,0 +1,27 @@
+import { suggestSimilar } from './suggest.js';
+const UNKNOWN_OPTION = /^Unknown option '(?<flag>[^']+)'/u;
+const NEAREST = /--[\w-]+/u;
+const SINGLE_DASH_WORD = /^-(?<word>[a-zA-Z][\w-]+)(?:=.*)?$/u;
+export function singleDashHint(argv) {
+    for (const token of argv) {
+        if (token === '--')
+            return undefined;
+        const word = SINGLE_DASH_WORD.exec(token)?.groups?.['word'];
+        if (word !== undefined)
+            return `did you mean --${word}? a single dash introduces one-letter options`;
+    }
+    return undefined;
+}
+export function unknownOption(cause, declared) {
+    if (!(cause instanceof Error))
+        return undefined;
+    const flag = UNKNOWN_OPTION.exec(cause.message)?.groups?.['flag'];
+    if (flag === undefined)
+        return undefined;
+    const dashed = declared.map((option) => `--${option}`);
+    const near = NEAREST.exec(suggestSimilar(flag, dashed))?.[0];
+    return {
+        message: `unknown option ${flag}`,
+        hint: near === undefined ? 'run --help to see the available options' : `did you mean ${near}?`,
+    };
+}

package/dist/{yargs-burgee.d.ts → yargs/burgee.d.ts}

@@ -4,8 +4,8 @@
  * this module projects that snapshot into the manifest every surface reads (J7, J8).
  * Nothing here runs at parse time unless a burgee surface was asked for.
  */
-import { type Effects, type Manifest, type OptionSpec } from './manifest.js';
-import type { Positional } from './yargs-utils.js';
+import { type Effects, type Manifest, type OptionSpec } from '../manifest.js';
+import type { Positional } from './utils.js';
 /** What one yargs instance (the root, or a command's builder run on a scratch) registered. */
 export interface Snapshot {
     name: string;

package/dist/{yargs-burgee.js → yargs/burgee.js}

@@ -1,4 +1,11 @@
-import { camelCase } from './yargs-parser.js';
+/**
+ * burgee's additions on yargs syntax — the pure half. `yargs-factory.ts` snapshots what
+ * a program registered (options, descriptions, commands and their builders' results) and
+ * this module projects that snapshot into the manifest every surface reads (J7, J8).
+ * Nothing here runs at parse time unless a burgee surface was asked for.
+ */
+import {} from '../manifest.js';
+import { camelCase } from '../yargs-parser.js';
 const DEFER_PREFIX = '__yargsString__:';
 function describe(descriptions, key) {
     const raw = descriptions[key];
@@ -14,6 +21,7 @@ function typeOf(s, key) {
         return 'number';
     return 'string';
 }
+/** Options as the manifest describes them, on a null-prototype record keyed by the canonical camelCase name. */
 export function optionSpecs(s) {
     const specs = Object.create(null);
     const aliasOf = new Set();
@@ -68,6 +76,10 @@ function argumentsOf(s) {
         push(p, false);
     return out;
 }
+/**
+ * Project a snapshot into the manifest: the root, then every command as a child path.
+ * Plugin-contributed nodes survive re-projection, exactly as on the commander façade.
+ */
 export function projectManifest(manifest, root) {
     const contributed = manifest.commands.filter((c) => c.plugin !== undefined);
     manifest.commands.splice(0, manifest.commands.length, ...contributed);
@@ -90,6 +102,7 @@ export function projectManifest(manifest, root) {
     };
     visit(root, [root.name], root.description, undefined);
 }
+/** What a run prints for a handler's return value when the streams are injected. */
 export function render(value) {
     if (value === undefined || value === null)
         return '';
@@ -102,3 +115,4 @@ export function render(value) {
     }
     return `${JSON.stringify(value)}\n`;
 }
+//# sourceMappingURL=burgee.js.map

package/dist/{yargs-cliui.js → yargs/cliui.js}

@@ -1,3 +1,9 @@
+/**
+ * cliui 9 — the column layout yargs' usage renders through — with the string-width,
+ * strip-ansi and wrap-ansi it depends on, ported for `burgee/yargs`. The wrapping
+ * arithmetic is byte-for-byte the upstream's: yargs' usage tests compare whole help
+ * screens.
+ */
 const ANSI_PATTERN = '[\\u001B\\u009B][[\\]()#;?]*(?:(?:(?:(?:;[-a-zA-Z\\d\\/#&.:=?%@~_]+)*|[a-zA-Z\\d]+(?:;[-a-zA-Z\\d\\/#&.:=?%@~_]*)*)?\\u0007)|(?:(?:\\d{1,4}(?:;\\d{0,4})*)?[\\dA-PR-TZcf-ntqry=><~]))';
 export function stripAnsi(str) {
     return typeof str === 'string' ? str.replace(new RegExp(ANSI_PATTERN, 'g'), '') : str;
@@ -47,6 +53,7 @@ export function stringWidth(input) {
     }
     return width;
 }
+/** ansi-styles' open→close map, the part wrap-ansi reads. */
 function closeCode(code) {
     if (code === 1 || code === 2)
         return 22;
@@ -419,3 +426,4 @@ function alignCenter(str, width) {
 export function cliui(opts) {
     return new UI({ width: opts?.width || getWindowWidth(), wrap: opts?.wrap });
 }
+//# sourceMappingURL=cliui.js.map

package/dist/{yargs-command.d.ts → yargs/command.d.ts}

@@ -3,11 +3,11 @@
  * builder/handler pipeline, positionals and the default command — ported for
  * `burgee/yargs`.
  */
-import { type Middleware } from './yargs-middleware.js';
-import type { PlatformShim } from './yargs-shim.js';
-import type { UsageInstance } from './yargs-usage.js';
-import { type Positional } from './yargs-utils.js';
-import type { ValidationInstance } from './yargs-validation.js';
+import { type Middleware } from './middleware.js';
+import type { PlatformShim } from './shim.js';
+import type { UsageInstance } from './usage.js';
+import { type Positional } from './utils.js';
+import type { ValidationInstance } from './validation.js';
 export interface CommandHandler {
     original: string;
     description?: string | false | undefined;

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

@@ -1,5 +1,10 @@
-import { applyMiddleware, commandMiddlewareFactory } from './yargs-middleware.js';
-import { isPromise, maybeAsyncResult, parseCommand } from './yargs-utils.js';
+/**
+ * yargs' command instance — `.command()` in its five shapes, `.commandDir()`, the
+ * builder/handler pipeline, positionals and the default command — ported for
+ * `burgee/yargs`.
+ */
+import { applyMiddleware, commandMiddlewareFactory } from './middleware.js';
+import { isPromise, maybeAsyncResult, parseCommand } from './utils.js';
 const DEFAULT_MARKER = /(^\*)|(^\$0)/;
 export function isYargsInstance(y) {
     return !!y && typeof y.getInternalMethods === 'function';
@@ -222,6 +227,7 @@ export class CommandInstance {
                         yargs.getInternalMethods().getUsageInstance().fail(null, error);
                     }
                     catch {
+                        // the failure was reported; yargs swallows the rethrow here
                     }
                 });
             }
@@ -412,3 +418,4 @@ function isCommandBuilderOptionDefinitions(builder) {
 export function isCommandHandlerDefinition(cmd) {
     return typeof cmd === 'object' && !Array.isArray(cmd);
 }
+//# sourceMappingURL=command.js.map

package/dist/{yargs-completion.d.ts → yargs/completion.d.ts}

@@ -2,9 +2,9 @@
  * yargs' completion — `--get-yargs-completions`, the custom completion function in its
  * three arities, and the bash/zsh script templates — ported for `burgee/yargs`.
  */
-import { type CommandInstance } from './yargs-command.js';
-import type { PlatformShim } from './yargs-shim.js';
-import type { UsageInstance } from './yargs-usage.js';
+import { type CommandInstance } from './command.js';
+import type { PlatformShim } from './shim.js';
+import type { UsageInstance } from './usage.js';
 export declare const completionShTemplate = "###-begin-{{app_name}}-completions-###\n#\n# yargs command completion script\n#\n# Installation: {{app_path}} {{completion_command}} >> ~/.bashrc\n#    or {{app_path}} {{completion_command}} >> ~/.bash_profile on OSX.\n#\n_{{app_name}}_yargs_completions()\n{\n    local cur_word args type_list\n\n    cur_word=\"${COMP_WORDS[COMP_CWORD]}\"\n    args=(\"${COMP_WORDS[@]}\")\n\n    # ask yargs to generate completions.\n    # see https://stackoverflow.com/a/40944195/7080036 for the spaces-handling awk\n    mapfile -t type_list < <({{app_path}} --get-yargs-completions \"${args[@]}\")\n    mapfile -t COMPREPLY < <(compgen -W \"$( printf '%q ' \"${type_list[@]}\" )\" -- \"${cur_word}\" |\n        awk '/ / { print \"\\\"\"$0\"\\\"\" } /^[^ ]+$/ { print $0 }')\n\n    # if no match was found, fall back to filename completion\n    if [ ${#COMPREPLY[@]} -eq 0 ]; then\n      COMPREPLY=()\n    fi\n\n    return 0\n}\ncomplete -o bashdefault -o default -F _{{app_name}}_yargs_completions {{app_name}}\n###-end-{{app_name}}-completions-###\n";
 export declare const completionZshTemplate = "#compdef {{app_name}}\n###-begin-{{app_name}}-completions-###\n#\n# yargs command completion script\n#\n# Installation: {{app_path}} {{completion_command}} >> ~/.zshrc\n#    or {{app_path}} {{completion_command}} >> ~/.zprofile on OSX.\n#\n_{{app_name}}_yargs_completions()\n{\n  local reply\n  local si=$IFS\n  IFS=$'\n' reply=($(COMP_CWORD=\"$((CURRENT-1))\" COMP_LINE=\"$BUFFER\" COMP_POINT=\"$CURSOR\" {{app_path}} --get-yargs-completions \"${words[@]}\"))\n  IFS=$si\n  if [[ ${#reply} -gt 0 ]]; then\n    _describe 'values' reply\n  else\n    _default\n  fi\n}\nif [[ \"'${zsh_eval_context[-1]}\" == \"loadautofunc\" ]]; then\n  _{{app_name}}_yargs_completions \"$@\"\nelse\n  compdef _{{app_name}}_yargs_completions {{app_name}}\nfi\n###-end-{{app_name}}-completions-###\n";
 type Done = (err: Error | null, completions: string[] | undefined) => void;

package/dist/{yargs-completion.js → yargs/completion.js}

@@ -1,5 +1,9 @@
-import { isCommandBuilderCallback } from './yargs-command.js';
-import { isPromise, parseCommand } from './yargs-utils.js';
+/**
+ * yargs' completion — `--get-yargs-completions`, the custom completion function in its
+ * three arities, and the bash/zsh script templates — ported for `burgee/yargs`.
+ */
+import { isCommandBuilderCallback } from './command.js';
+import { isPromise, parseCommand } from './utils.js';
 export const completionShTemplate = `###-begin-{{app_name}}-completions-###
 #
 # yargs command completion script
@@ -269,3 +273,4 @@ function isSyncCompletionFunction(fn) {
 function isFallbackCompletionFunction(fn) {
     return fn.length > 3;
 }
+//# sourceMappingURL=completion.js.map

package/dist/{yargs-factory.d.ts → yargs/factory.d.ts}

@@ -5,14 +5,14 @@
  * `getInternalMethods()` seam are the upstream's — that is what makes a user's
  * existing program run unchanged (J2).
  */
-import { type Effects, Manifest, type Plugin } from './manifest.js';
-import { type CommandInstance } from './yargs-command.js';
-import { type CompletionFunction } from './yargs-completion.js';
-import { type Middleware } from './yargs-middleware.js';
-import type { PlatformShim } from './yargs-shim.js';
-import { type FailureFunction, type UsageInstance } from './yargs-usage.js';
-import { YError } from './yargs-utils.js';
-import { type ValidationInstance } from './yargs-validation.js';
+import { type Effects, Manifest, type Plugin } from '../manifest.js';
+import { type CommandInstance } from './command.js';
+import { type CompletionFunction } from './completion.js';
+import { type Middleware } from './middleware.js';
+import type { PlatformShim } from './shim.js';
+import { type FailureFunction, type UsageInstance } from './usage.js';
+import { YError } from './utils.js';
+import { type ValidationInstance } from './validation.js';
 export interface Options {
     array: string[];
     boolean: string[];

package/dist/{yargs-factory.js → yargs/factory.js}

@@ -1,16 +1,23 @@
+/**
+ * yargs' `YargsInstance`, ported method for method from yargs 18 and graded by yargs'
+ * own suite through `compat-oracle`. Every public method, its argsert contract, the
+ * parse pipeline, the freeze/unfreeze bookkeeping around `.parse()` and the
+ * `getInternalMethods()` seam are the upstream's — that is what makes a user's
+ * existing program run unchanged (J2).
+ */
 var _a;
-import { ExitCode } from './exit-code.js';
-import { Manifest } from './manifest.js';
-import { serveMcp } from './mcp.js';
-import { schemaOf } from './schema.js';
-import { projectManifest, render } from './yargs-burgee.js';
-import { command as Command, isCommandBuilderCallback } from './yargs-command.js';
-import { completion as Completion } from './yargs-completion.js';
-import { applyMiddleware, GlobalMiddleware } from './yargs-middleware.js';
-import { tokenizeArgString } from './yargs-parser.js';
-import { usage as Usage } from './yargs-usage.js';
-import { applyExtends, argsert, isPromise, maybeAsyncResult, objectKeys, objFilter, setBlocking, YError } from './yargs-utils.js';
-import { validation as Validation } from './yargs-validation.js';
+import { ExitCode } from '../exit-code.js';
+import { Manifest } from '../manifest.js';
+import { serveMcp } from '../mcp.js';
+import { schemaOf } from '../schema.js';
+import { tokenizeArgString } from '../yargs-parser.js';
+import { projectManifest, render } from './burgee.js';
+import { command as Command, isCommandBuilderCallback } from './command.js';
+import { completion as Completion } from './completion.js';
+import { applyMiddleware, GlobalMiddleware } from './middleware.js';
+import { usage as Usage } from './usage.js';
+import { applyExtends, argsert, isPromise, maybeAsyncResult, objectKeys, objFilter, setBlocking, YError } from './utils.js';
+import { validation as Validation } from './validation.js';
 const DEFAULT_LOCALE = 'en_US';
 export function YargsFactory(shim) {
     return (processArgs = [], cwd = shim.process.cwd(), parentRequire) => {
@@ -64,6 +71,7 @@ export class YargsInstance {
     #usageConfig = {};
     #versionOpt = null;
     #validation;
+    // ───── burgee: the manifest projection, plugins, --json, the surfaces and the seam ─────
     #burgee = undefined;
     #effects = undefined;
     #manifest = undefined;
@@ -74,6 +82,7 @@ export class YargsInstance {
         this.#parentRequire = parentRequire;
         this.#globalMiddleware = new GlobalMiddleware(this);
         this.$0 = this.#getDollarZero();
+        // kReset builds the four collaborators; the definite assignments below are its result.
         this.#options = undefined;
         this.#usage = undefined;
         this.#validation = undefined;
@@ -593,6 +602,8 @@ export class YargsInstance {
         argsert('[string|array] [function|boolean|object] [function]', [args, shortCircuit, _parseFn], arguments.length);
         if (shortCircuit === true)
             return this.#parse(args, shortCircuit, _parseFn);
+        // burgee: --json and the seam are per parse. What this parse turns on (json, an exit
+        // already reported) is put back afterwards, so the next parse starts as the program left it.
         const before = this.#burgee === undefined ? undefined : { ...this.#burgee };
         const restore = () => {
             this.#burgee = before;
@@ -611,6 +622,8 @@ export class YargsInstance {
                 throw err;
             }
         }
+        // The seam: the whole run settles to one E1 exit. yargs reports its own failures
+        // through exit(); a handler that throws synchronously is the one thing that escapes it.
         seam.exited = false;
         const finish = (argv) => {
             if (!this.#burgee?.exited)
@@ -662,6 +675,8 @@ export class YargsInstance {
         if (!shortCircuit) {
             const served = this.#burgeeSurface(args);
             if (served !== false) {
+                // A surface was (or is being) served: the argv handed back is the short-circuit parse,
+                // as after --help. Completions and --mcp load lazily, so those two return a promise.
                 const settle = () => {
                     const argv = this.#runYargsParserAndExecuteCommands(args, true);
                     this.#unfreeze();
@@ -905,6 +920,7 @@ export class YargsInstance {
             delete argv['--'];
         }
         catch {
+            // a frozen argv keeps its `--`; yargs ignores the failure
         }
         return argv;
     }
@@ -925,6 +941,8 @@ export class YargsInstance {
                 const burgee = this.#burgee;
                 const line = args.join(' ');
                 if (burgee?.json) {
+                    // Under --json the failure is one envelope on stdout; the help screen and the
+                    // message yargs prints on the way are kept only as the envelope's message.
                     if (line.trim() !== '')
                         burgee.lastError = line;
                 }
@@ -1042,6 +1060,7 @@ export class YargsInstance {
             obj = JSON.parse(this.#shim.readFileSync(pkgJsonPath, 'utf8'));
         }
         catch {
+            // no package.json above: version reads 'unknown', as upstream
         }
         this.#pkgs[npath] = obj || {};
         return this.#pkgs[npath];
@@ -1135,19 +1154,32 @@ export class YargsInstance {
             runHandler: this.#runHandler.bind(this),
         };
     }
+    // ───── burgee: additive, and guarded so a program that asks for none of it runs as on yargs ─────
+    /**
+     * The manifest every surface reads (J7, J8). Projected on each access from what the
+     * program registered; a command's builder is run on a scratch instance to learn its
+     * options, exactly as yargs' own completion does. Plugin-contributed nodes are kept.
+     */
     get manifest() {
         this.#manifest ??= new Manifest();
         projectManifest(this.#manifest, this.#snapshot());
         return this.#manifest;
     }
+    /** burgee: declare what the command does to the world (N6); what exposes it as an MCP tool (N2). */
     effects(value) {
         this.#effects = value;
         return this;
     }
+    /** Additive: plugins yargs never had. `preRun`/`postRun` fire around every handler. */
     use(plugin) {
         this.manifest.use(plugin);
         return this;
     }
+    /**
+     * Inject the streams and the exit for this instance (T1). Output goes to `stdout`/`stderr`
+     * instead of the console, and `exit` receives an E1 code: OK for help and version, USAGE
+     * for a validation failure, RUNTIME for a handler that threw.
+     */
     burgee(seam) {
         this.#burgee = { ...(this.#burgee ?? { json: false, lastError: '' }), ...seam };
         return this;
@@ -1160,6 +1192,7 @@ export class YargsInstance {
         let positionals = { demanded: [], optional: [] };
         let hasHandler = false;
         let description;
+        // The default command (`$0`, `*`) is the root's own handler, not a child path.
         const isDefault = (h) => /^\$0( |$)/.test(h.original);
         for (const [name, handler] of Object.entries(handlers)) {
             if (isDefault(handler))
@@ -1201,6 +1234,7 @@ export class YargsInstance {
             commands,
         };
     }
+    /** A command's snapshot: what its builder registered on the scratch, plus the command string's positionals. */
     #snapshotOf(handler, name) {
         const snap = this.#snapshot();
         snap.name = name;
@@ -1210,6 +1244,7 @@ export class YargsInstance {
         snap.version = undefined;
         return snap;
     }
+    /** Run a command's builder on a fresh instance, as yargs' completion does, and hand that instance back. */
     #childOf(handler) {
         const child = new _a([], this.#cwd, this.#parentRequire, this.#shim);
         child.#context.fullCommands.push(handler.original);
@@ -1226,9 +1261,11 @@ export class YargsInstance {
             }
         }
         catch {
+            // A builder that cannot run outside a parse projects only the command string.
         }
         return child;
     }
+    /** `--json` that the program did not declare is burgee's envelope, not an unknown option. */
     #takeJson(args) {
         const list = typeof args === 'string' ? tokenizeArgString(args) : args;
         const terminator = list.indexOf('--');
@@ -1240,6 +1277,11 @@ export class YargsInstance {
         this.#burgee = { ...(this.#burgee ?? { lastError: '' }), json: true };
         return [...list.slice(0, index), ...list.slice(index + 1)];
     }
+    /**
+     * Whether the program declared an option or command by this name — at the root, or in
+     * any command's builder, which the manifest projection runs to find out. Any command in
+     * the tree that declares the flag keeps it: the surface is additive only.
+     */
     #declares(key) {
         if (this.#options.key[key] || Object.values(this.#options.alias).some((list) => list.includes(key)))
             return true;
@@ -1247,12 +1289,17 @@ export class YargsInstance {
             return true;
         return this.manifest.commands.some((node) => Object.prototype.hasOwnProperty.call(node.options, key));
     }
+    /**
+     * `--schema`, `--mcp` and `completion <shell>` on a yargs-syntax program, from its
+     * manifest (J2). Only when the program declares none of them itself; `--schema` is
+     * synchronous, the other two load lazily and return a promise.
+     */
     #burgeeSurface(args) {
         const list = typeof args === 'string' ? tokenizeArgString(args) : args;
         const terminator = list.indexOf('--');
         const head = terminator === -1 ? list : list.slice(0, terminator);
         if (head[0] === 'completion' && this.#completionCommand === null && !this.#declares('completion')) {
-            return import('./completions.js').then(({ renderCompletion, renderFigSpec, SHELLS }) => {
+            return import('../completions.js').then(({ renderCompletion, renderFigSpec, SHELLS }) => {
                 const shell = head[1] ?? '';
                 if (shell === 'fig') {
                     this.#logger.log(JSON.stringify(renderFigSpec(this.manifest), null, 2));
@@ -1295,6 +1342,7 @@ export class YargsInstance {
         }
         return false;
     }
+    /** The handler, wrapped in the plugin hooks and followed by the envelope or the rendering. */
     #runHandler(handler, argv, original) {
         const manifest = this.#manifest;
         const settle = (value) => {
@@ -1335,6 +1383,7 @@ export class YargsInstance {
         const code = err instanceof YError || err === undefined || typeof err === 'string' ? 'usage' : 'runtime';
         this.#logger.log(JSON.stringify({ ok: false, error: { code, message } }));
     }
+    /** burgee: where every option value came from (V3), from yargs-parser's own bookkeeping where it keeps any. */
     #provenance(argv) {
         const out = {};
         const defaulted = this.parsed?.defaulted ?? {};
@@ -1604,3 +1653,4 @@ _a = YargsInstance;
 export function isYargsInstance(y) {
     return !!y && typeof y.getInternalMethods === 'function';
 }
+//# sourceMappingURL=factory.js.map

package/dist/{yargs-middleware.js → yargs/middleware.js}

@@ -1,4 +1,8 @@
-import { argsert, isPromise } from './yargs-utils.js';
+/**
+ * yargs' middleware — global, per-command, and the coerce middleware `.coerce()`
+ * registers — ported for `burgee/yargs`.
+ */
+import { argsert, isPromise } from './utils.js';
 export class GlobalMiddleware {
     globalMiddleware = [];
     frozens = [];
@@ -79,3 +83,4 @@ export function applyMiddleware(argv, yargs, middlewares, beforeValidation) {
         return isPromise(result) ? result.then((middlewareObj) => Object.assign(acc, middlewareObj)) : Object.assign(acc, result);
     }, argv);
 }
+//# sourceMappingURL=middleware.js.map

package/dist/{yargs-shim.d.ts → yargs/shim.d.ts}

@@ -7,9 +7,9 @@
 import { readdirSync, readFileSync } from 'node:fs';
 import { basename, dirname, extname, join, relative, resolve } from 'node:path';
 import { inspect } from 'node:util';
-import { cliui } from './yargs-cliui.js';
-import { Parser } from './yargs-parser.js';
-import { type Y18N } from './yargs-y18n.js';
+import { Parser } from '../yargs-parser.js';
+import { cliui } from './cliui.js';
+import { type Y18N } from './y18n.js';
 export interface PlatformShim {
     assert: {
         notStrictEqual: (a: any, b: any, m?: string) => void;

package/dist/{yargs-shim.js → yargs/shim.js}

@@ -1,15 +1,22 @@
+/**
+ * yargs' Node platform shim — the one object every yargs module reaches the platform
+ * through — built from burgee's own ports of its dependencies (J9). Anything that
+ * yargs 18 took from `cliui`, `escalade`, `get-caller-file`, `string-width`, `y18n`
+ * and `yargs-parser` is served from here.
+ */
 import { readdirSync, readFileSync, statSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { basename, dirname, extname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { inspect } from 'node:util';
-import { cliui, stringWidth } from './yargs-cliui.js';
-import { Parser } from './yargs-parser.js';
-import { getProcessArgvBin } from './yargs-utils.js';
-import { y18n } from './yargs-y18n.js';
+import { Parser } from '../yargs-parser.js';
+import { cliui, stringWidth } from './cliui.js';
+import { getProcessArgvBin } from './utils.js';
+import { y18n } from './y18n.js';
 const here = fileURLToPath(import.meta.url);
 const mainFilename = here.substring(0, here.lastIndexOf('node_modules'));
 const nodeRequire = createRequire(import.meta.url);
+/** escalade/sync: walk up from `start`, asking `callback` at each directory. */
 function findUp(start, callback) {
     let dir = resolve('.', start);
     let tmp;
@@ -27,6 +34,7 @@ function findUp(start, callback) {
     }
     return undefined;
 }
+/** get-caller-file: the file that called the function that called this (v8 stack). */
 function getCallerFile(position = 2) {
     if (position >= Error.stackTraceLimit) {
         throw new TypeError(`getCallerFile(position) requires position be less then Error.stackTraceLimit but position was: \`${position}\` and Error.stackTraceLimit was: \`${Error.stackTraceLimit}\``);
@@ -49,6 +57,16 @@ function strictEqual(actual, expected, message) {
     if (actual !== expected)
         throw new Error(message ?? `Expected values to be strictly equal:\n\n${inspect(actual)} !== ${inspect(expected)}\n`);
 }
+/**
+ * Where the 29 locale files live: the package root, not beside this file.
+ *
+ * This was `resolve(dirname(here), '../locales')`, which was right only while this file sat
+ * directly in `dist/`. The first directory added under `src/` made it `dist/locales`, y18n
+ * returned the key for every string, and 14 of yargs' own 804 tests failed. Walking up to
+ * `package.json` resolves the same from `src/`, from `dist/`, and from
+ * `node_modules/burgee/dist/` once published — so a later move cannot repeat it.
+ */
+const locales = resolve(dirname(findUp(here, (_dir, names) => (names.includes('package.json') ? 'package.json' : undefined)) ?? here), 'locales');
 export const shim = {
     assert: { notStrictEqual, strictEqual },
     cliui,
@@ -80,5 +98,6 @@ export const shim = {
         return /^file:\/\//.exec(callerFile) ? fileURLToPath(callerFile) : callerFile;
     },
     stringWidth,
-    y18n: y18n({ directory: resolve(dirname(here), '../locales'), updateFiles: false }),
+    y18n: y18n({ directory: locales, updateFiles: false }),
 };
+//# sourceMappingURL=shim.js.map

package/dist/{yargs-usage.d.ts → yargs/usage.d.ts}

@@ -3,7 +3,7 @@
  * version string — ported for `burgee/yargs`. Help is rendered through the cliui port,
  * so yargs' usage tests compare whole screens byte for byte.
  */
-import type { PlatformShim } from './yargs-shim.js';
+import type { PlatformShim } from './shim.js';
 export type FailureFunction = (msg: string | undefined | null, err: Error | undefined, usage: UsageInstance) => void;
 export interface UsageInstance {
     failFn: (f: FailureFunction | boolean) => void;