burgee 0.7.1 → 0.9.0

package/dist/schema.json

@@ -1 +1 @@
-{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://github.com/ofri-peretz/burgee/blob/main/packages/flagstaff/src/schema.json","title":"flagstaff plugin","description":"A plugin is one plain object. Everything in it is data that can be read without running it; the only functions allowed are a component's `static` (required) and `frame` (optional). A spinner or component without a static projection is refused at register().","type":"object","required":["name"],"additionalProperties":true,"properties":{"name":{"type":"string","minLength":1,"description":"The plugin's name; also the prefix a host may use when two plugins contribute the same key."},"contract":{"type":"integer","minimum":1,"description":"The plugin contract this object follows. A host refuses a newer contract than it knows."},"tokens":{"type":"object","description":"A roundel theme: semantic token name to a hex colour, contrast-checked when flown.","additionalProperties":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"propertyNames":{"enum":["error","warn","ok","hint","muted","command","flag","value","heading","ground"],"description":"roundel's ten semantic tokens, and nothing else — `roundel`'s own validate() refuses any other name."}},"glyphs":{"type":"object","description":"Symbols by meaning: `ok`, `fail`, `warn`, `info`, `running`. A plugin that ships glyphs changes every built-in that draws one.","additionalProperties":{"type":"string","minLength":1}},"spinners":{"type":"object","description":"Spinner styles by name, in cli-spinners' shape plus the static projection.","additionalProperties":{"$ref":"#/$defs/spinner"}},"borders":{"type":"object","description":"Border styles a box can be drawn with, by name.","additionalProperties":{"$ref":"#/$defs/border"}},"components":{"type":"object","description":"Components by name: `static(state)` returns the text a pipe, an agent or a screen reader gets; `frame(t, state)` is the optional animated form.","additionalProperties":{"$ref":"#/$defs/component"}},"capabilities":{"$ref":"#/$defs/capabilities"}},"$defs":{"spinner":{"type":"object","required":["frames","interval","static"],"properties":{"frames":{"type":"array","items":{"type":"string"},"minItems":1},"interval":{"type":"integer","minimum":1,"description":"Milliseconds between frames on a terminal."},"static":{"type":"string","description":"What a pipe prints instead of the animation."}}},"component":{"type":"object","required":["static"],"properties":{"static":{"description":"(state) => string. Required: the projection every non-terminal mode prints."},"frame":{"description":"(t, state) => string. Optional: the frame at t milliseconds since hoisting."},"sample":{"type":"object","required":["running","done"],"description":"Two states to *show* this component with: `flagstaff check` and the docs gallery render `running` then `done`. Omitted, they assume `{ phase: 'running' }` and `{ phase: 'done' }` and say so in the output. The loop never reads it — a running program's state comes from the program.","properties":{"running":{"description":"The state to open with."},"done":{"description":"The state to close with."}}},"interval":{"type":"integer","minimum":1,"description":"Milliseconds between repaints when `frame` is given; 80 when omitted."}}},"border":{"type":"object","required":["topLeft","top","topRight","left","right","bottomLeft","bottom","bottomRight"],"description":"cli-boxes' shape exactly, so that corpus imports unchanged.","properties":{"topLeft":{"type":"string"},"top":{"type":"string"},"topRight":{"type":"string"},"left":{"type":"string"},"right":{"type":"string"},"bottomLeft":{"type":"string"},"bottom":{"type":"string"},"bottomRight":{"type":"string"}}},"capability":{"type":"object","required":["name","osc","when","encode","fallback"],"additionalProperties":false,"description":"One paratext capability: what it says to the terminal, when the terminal is believed to understand it, and what prints when it does not. No functions, so it travels through JSON. `encode` and `fallback` are templates: `{field}` is the field's value, `{field|base64}` is it base64-encoded, and `[ … ]` is emitted only when every field inside it has a value.","properties":{"name":{"type":"string","minLength":1,"description":"How callers name it. Registering an existing name replaces it — how a caller corrects a guess we got wrong."},"osc":{"description":"The OSC code this speaks, or 'BEL' for the bell and for protocols that are not OSC at all, such as Kitty's.","oneOf":[{"type":"integer","minimum":0},{"const":"BEL"}]},"when":{"type":"object","description":"When the terminal is believed to understand it. Every clause must hold; `termProgram` and `envAny` are ORs within themselves. Guesses — no terminal answers 'do you do OSC 1337' — and therefore data a caller can replace.","additionalProperties":false,"properties":{"tty":{"type":"boolean","description":"Refuse a pipe. Almost always true: a file that receives OSC gets control bytes in it."},"termProgram":{"type":"array","items":{"type":"string"},"description":"Any one of these TERM_PROGRAM values."},"envAny":{"type":"array","items":{"type":"string"},"description":"Any one of these environment variables merely being set, as VTE announces itself."},"term":{"type":"string","description":"An exact TERM — Kitty is xterm-kitty."}}},"encode":{"type":"string","minLength":1,"description":"The bytes, as a template, for a terminal that does understand."},"fallback":{"type":"string","description":"What to print when it does not — PRINCIPLES rule 6. '' is a legitimate answer, a window title having nothing to say in a log; absence is not, which is why this is required and may be ''."}},"examples":[{"name":"kitty-image","osc":"BEL","when":{"tty":true,"term":"xterm-kitty"},"encode":"\u001b_Ga=T,f=100;{base64}\u001b\\","fallback":"{caption}"}]},"capabilities":{"type":"object","description":"paratext capabilities by name — the OSC section of a plugin, read the way flagstaff reads `spinners`.","additionalProperties":{"$ref":"#/$defs/capability"}},"capabilityDocument":{"description":"What paratext's `check()` accepts. Two shapes, and only one of them survives 1.0.","oneOf":[{"description":"The family shape: a plugin carrying its capabilities under `capabilities`.","type":"object","required":["name","capabilities"],"properties":{"name":{"type":"string","minLength":1},"contract":{"type":"integer","minimum":1},"capabilities":{"$ref":"#/$defs/capabilities"}}},{"deprecated":true,"description":"Deprecated: one capability as the whole document, the shape paratext's schema had before this one absorbed it. Accepted for one minor release, removed at 1.0 — `check()` validates it and says so.","$ref":"#/$defs/capability"}]}}}
+{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://github.com/ofri-peretz/burgee/blob/main/packages/flagstaff/src/schema.json","title":"flagstaff plugin","description":"A plugin is one plain object. Everything in it is data that can be read without running it; the only functions allowed are a component's `static` (required) and `frame` (optional). A spinner or component without a static projection is refused at register().","type":"object","required":["name"],"additionalProperties":true,"properties":{"name":{"type":"string","minLength":1,"description":"The plugin's name; also the prefix a host may use when two plugins contribute the same key."},"contract":{"type":"integer","minimum":1,"description":"The plugin contract this object follows. A host refuses a newer contract than it knows."},"tokens":{"type":"object","description":"A roundel theme: semantic token name to a hex colour, contrast-checked when flown.","additionalProperties":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"propertyNames":{"enum":["error","warn","ok","hint","muted","command","flag","value","heading","ground"],"description":"roundel's ten semantic tokens, and nothing else — `roundel`'s own validate() refuses any other name."}},"glyphs":{"type":"object","description":"Symbols by meaning: `ok`, `fail`, `warn`, `info`, `running`. A plugin that ships glyphs changes every built-in that draws one.","additionalProperties":{"type":"string","minLength":1}},"spinners":{"type":"object","description":"Spinner styles by name, in cli-spinners' shape plus the static projection.","additionalProperties":{"$ref":"#/$defs/spinner"}},"borders":{"type":"object","description":"Border styles a box can be drawn with, by name.","additionalProperties":{"$ref":"#/$defs/border"}},"components":{"type":"object","description":"Components by name: `static(state)` returns the text a pipe, an agent or a screen reader gets; `frame(t, state)` is the optional animated form.","additionalProperties":{"$ref":"#/$defs/component"}},"capabilities":{"$ref":"#/$defs/capabilities"},"widths":{"$ref":"#/$defs/widths"}},"$defs":{"spinner":{"type":"object","required":["frames","interval","static"],"properties":{"frames":{"type":"array","items":{"type":"string"},"minItems":1},"interval":{"type":"integer","minimum":1,"description":"Milliseconds between frames on a terminal."},"static":{"type":"string","description":"What a pipe prints instead of the animation."}}},"component":{"type":"object","required":["static"],"properties":{"static":{"description":"(state) => string. Required: the projection every non-terminal mode prints."},"frame":{"description":"(t, state) => string. Optional: the frame at t milliseconds since hoisting."},"sample":{"type":"object","required":["running","done"],"description":"Two states to *show* this component with: `flagstaff check` and the docs gallery render `running` then `done`. Omitted, they assume `{ phase: 'running' }` and `{ phase: 'done' }` and say so in the output. The loop never reads it — a running program's state comes from the program.","properties":{"running":{"description":"The state to open with."},"done":{"description":"The state to close with."}}},"interval":{"type":"integer","minimum":1,"description":"Milliseconds between repaints when `frame` is given; 80 when omitted."}}},"border":{"type":"object","required":["topLeft","top","topRight","left","right","bottomLeft","bottom","bottomRight"],"description":"cli-boxes' shape exactly, so that corpus imports unchanged.","properties":{"topLeft":{"type":"string"},"top":{"type":"string"},"topRight":{"type":"string"},"left":{"type":"string"},"right":{"type":"string"},"bottomLeft":{"type":"string"},"bottom":{"type":"string"},"bottomRight":{"type":"string"}}},"capability":{"type":"object","required":["name","osc","when","encode","fallback"],"additionalProperties":false,"description":"One paratext capability: what it says to the terminal, when the terminal is believed to understand it, and what prints when it does not. No functions, so it travels through JSON. `encode` and `fallback` are templates: `{field}` is the field's value, `{field|base64}` is it base64-encoded, and `[ … ]` is emitted only when every field inside it has a value.","properties":{"name":{"type":"string","minLength":1,"description":"How callers name it. Registering an existing name replaces it — how a caller corrects a guess we got wrong."},"osc":{"description":"The OSC code this speaks, or 'BEL' for the bell and for protocols that are not OSC at all, such as Kitty's.","oneOf":[{"type":"integer","minimum":0},{"const":"BEL"}]},"when":{"type":"object","description":"When the terminal is believed to understand it. Every clause must hold; `termProgram` and `envAny` are ORs within themselves. Guesses — no terminal answers 'do you do OSC 1337' — and therefore data a caller can replace.","additionalProperties":false,"properties":{"tty":{"type":"boolean","description":"Refuse a pipe. Almost always true: a file that receives OSC gets control bytes in it."},"termProgram":{"type":"array","items":{"type":"string"},"description":"Any one of these TERM_PROGRAM values."},"envAny":{"type":"array","items":{"type":"string"},"description":"Any one of these environment variables merely being set, as VTE announces itself."},"term":{"type":"string","description":"An exact TERM — Kitty is xterm-kitty."}}},"encode":{"type":"string","minLength":1,"description":"The bytes, as a template, for a terminal that does understand."},"fallback":{"type":"string","description":"What to print when it does not — PRINCIPLES rule 6. '' is a legitimate answer, a window title having nothing to say in a log; absence is not, which is why this is required and may be ''."}},"examples":[{"name":"kitty-image","osc":"BEL","when":{"tty":true,"term":"xterm-kitty"},"encode":"\u001b_Ga=T,f=100;{base64}\u001b\\","fallback":"{caption}"}]},"capabilities":{"type":"object","description":"paratext capabilities by name — the OSC section of a plugin, read the way flagstaff reads `spinners`.","additionalProperties":{"$ref":"#/$defs/capability"}},"capabilityDocument":{"description":"What paratext's `check()` accepts. Two shapes, and only one of them survives 1.0.","oneOf":[{"description":"The family shape: a plugin carrying its capabilities under `capabilities`.","type":"object","required":["name","capabilities"],"properties":{"name":{"type":"string","minLength":1},"contract":{"type":"integer","minimum":1},"capabilities":{"$ref":"#/$defs/capabilities"}}},{"deprecated":true,"description":"Deprecated: one capability as the whole document, the shape paratext's schema had before this one absorbed it. Accepted for one minor release, removed at 1.0 — `check()` validates it and says so.","$ref":"#/$defs/capability"}]},"widthRange":{"type":"array","description":"One inclusive code-point range, as [low, high]. A single code point is written [n, n].","items":{"type":"integer","minimum":0,"maximum":1114111},"minItems":2,"maxItems":2},"widthOverride":{"type":"object","description":"A linegauge width override: the column count a named set of code-point ranges occupies, for a terminal that disagrees with the Unicode tables. Data only — no function, so it can be written in a config file, diffed, and printed by `linegauge check` without running anyone code.","required":["ranges","columns","why"],"additionalProperties":false,"properties":{"ranges":{"type":"array","description":"The code points this override applies to.","items":{"$ref":"#/$defs/widthRange"},"minItems":1},"columns":{"type":"integer","description":"Columns each cluster in those ranges occupies: 0 for a zero-width mark, 1 narrow, 2 wide.","minimum":0,"maximum":2},"why":{"type":"string","description":"The terminal or the reason. Required, because a width table with no provenance is one nobody can audit when it turns out to be wrong — which is the normal outcome for ambiguous width.","minLength":1}}},"widths":{"type":"object","description":"linegauge width overrides by name — the measurement section of a plugin, read the way flagstaff reads `spinners`.","additionalProperties":{"$ref":"#/$defs/widthOverride"}}}}

package/dist/testing-helpers.js

@@ -133,7 +133,9 @@ export async function runBurgee(program, opts) {
         await execute(program, {
             argv: rt.argv,
             env: rt.env,
-            stdout: rt.stdout,
+            cwd: rt.cwd,
+            stdin: rt.stdin,
+            stdout: { write: rt.stdout.write, isTTY: rt.isTTY.stdout },
             stderr: rt.stderr,
             exit: (c) => rt.exit(c),
             root: program.rootPath,

package/dist/validate.d.ts

@@ -11,6 +11,21 @@ export declare class UsageError extends Error {
     readonly hint?: string | undefined;
     constructor(message: string, hint?: string | undefined);
 }
+/**
+ * E6 — the far side said no. Throw this and the run leaves with `ExitCode.AUTH`.
+ *
+ * The one error class whose *response* is unambiguous: not "read the message and decide" but
+ * "get a credential and run it again". A handler that throws a bare `Error` for a 401 gets
+ * `RUNTIME`, which is the code for everything, and a caller retrying on it retries forever.
+ *
+ * `fix` is the exact command that gets the credential, where the program knows it — `hint` is
+ * prose a person reads and `fix` is a line a caller runs, which is the turn the field saves.
+ */
+export declare class AuthError extends Error {
+    readonly hint?: string | undefined;
+    readonly fix?: string | undefined;
+    constructor(message: string, hint?: string | undefined, fix?: string | undefined);
+}
 type Sources = Record<string, {
     source: string;
 }>;

package/dist/validate.js

@@ -6,6 +6,16 @@ export class UsageError extends Error {
         this.hint = hint;
     }
 }
+export class AuthError extends Error {
+    hint;
+    fix;
+    constructor(message, hint, fix) {
+        super(message);
+        this.hint = hint;
+        this.fix = fix;
+        this.name = 'AuthError';
+    }
+}
 const isSet = (values, key, sources) => values[key] !== undefined && sources[key]?.source !== 'default';
 const flagList = (keys) => flagsOf(keys).join(', ');
 function exactlyOne(keys, on) {

package/dist/yargs/burgee.js

@@ -1,10 +1,3 @@
-/**
- * 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) {
@@ -21,7 +14,6 @@ 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();
@@ -76,10 +68,6 @@ 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);
@@ -102,7 +90,6 @@ 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 '';
@@ -115,4 +102,3 @@ export function render(value) {
     }
     return `${JSON.stringify(value)}\n`;
 }
-//# sourceMappingURL=burgee.js.map

package/dist/yargs/cliui.js

@@ -1,35 +1,7 @@
 import { strip, width, wrap } from "linegauge";
 import { host } from "../runtime.js";
-/**
- * cliui 9 — the column layout yargs' usage renders through — with the wrap-ansi it depends
- * on, ported for `burgee/yargs`. Width and escape-stripping come from linegauge. The wrapping
- * arithmetic is byte-for-byte the upstream's: yargs' usage tests compare whole help
- * screens.
- */
-/*
- * `width` and `strip` are linegauge's — measuring text and removing escapes is the layer
- * below this one, and this file had its own copies of both. They were not merely duplicated,
- * they were wrong: the ITU T.416 sub-parameter form `ESC[38:2::255:0:0m`, which chalk emits
- * for truecolor, left `:2::255:0:0m` behind and measured a 13-column string as 25. linegauge
- * fixed that in its own `strip`; burgee inherited nothing because it was not asking.
- *
- * The names stay, because `usage.ts` and `shim.ts` import them and the upstream port reads
- * the way cliui reads.
- */
 export const stripAnsi = (str) => typeof str === "string" ? strip(str) : str;
 export const stringWidth = (input) => typeof input === "string" ? width(input) : 0;
-/*
- * The wrap is linegauge's too. This file carried a wrap-ansi port — ansi-styles' open→close
- * map, an escape-state machine over every character, hyperlink re-opening — to wrap a line
- * without breaking the styling across it. That is the same job `linegauge/wrap` exists for
- * and grades against wrap-ansi, so burgee kept a second implementation of a thing the layer
- * below already owned.
- *
- * Checked before swapping, because yargs' usage tests compare whole help screens: the two
- * agreed on all ten shapes probed — plain prose at several widths, an unbreakable word,
- * SGR-coloured text, single characters, CJK, an embedded newline, leading and trailing
- * spaces, empty, and a string exactly the column width.
- */
 export function wrapAnsi(string, columns, options) {
     return wrap(String(string).normalize().replace(/\r\n/g, "\n"), columns, options);
 }
@@ -90,13 +62,6 @@ export class UI {
         return { text, padding: this.measurePadding(text) };
     }
     measurePadding(str) {
-        // An unanchored `\s*$` was the upstream spelling, and it is quadratic: the engine
-        // retries at every position, so a cell of 50,000 spaces then an `x` costs 1,346 ms
-        // here — CodeQL alert 35, "polynomial regular expression used on uncontrolled data",
-        // raised once `stripAnsi` became library input. Spaces, not the tabs the alert names:
-        // a tab routes into `applyLayoutDSL`, which splits on it long before this runs.
-        // `trim{Start,End}` remove exactly the set `\s` matches (WhiteSpace + LineTerminator)
-        // and are linear, so this is the same measurement without the backtracking.
         const noAnsi = stripAnsi(str);
         return [
             0,
@@ -222,21 +187,6 @@ export class UI {
         return widths.map((w, i) => w === undefined ? Math.max(unsetWidth, minWidth(row[i])) : w);
     }
 }
-/*
- * `str.replace(/ +$/, "")` was the upstream spelling, and it is the same quadratic shape
- * `measurePadding` had: the start is unanchored, so the engine retries the match at every
- * position in the run of spaces and each attempt walks to the end before failing on the
- * character that is not the end. A row built from a cell of 50,000 spaces then an `x` is
- * 100,001 characters of which the first 50,000 are the left padding, and trimming it cost
- * 1,049 ms of `toString()`'s 1,223 ms. Doubling the cell quadrupled it.
- *
- * `trimEnd()` is linear but not the same function — it also removes tabs, newlines and the
- * rest of `\s`. A trailing tab does reach here: with `wrap: false`, `rasterize` only splits
- * the cell on newlines, so nothing expands the tab and nothing routes the string through
- * `applyLayoutDSL` (that check is behind `this.wrap`). `cliui({ wrap: false }).div('a\t')`
- * renders `'a\t'` today and would render `'a'` under `trimEnd`, and the yargs usage tests
- * compare whole help screens. This removes exactly U+0020, exactly as the regex did.
- */
 function trimTrailingSpaces(str) {
     let end = str.length;
     while (end > 0 && str[end - 1] === " ")
@@ -261,8 +211,6 @@ function minWidth(col) {
     return min;
 }
 function getWindowWidth() {
-    // `host.columns` carries the upstream's guard on the process global itself, so a bundle
-    // that has no process at all still falls back to 80 rather than throwing.
     return host.columns || 80;
 }
 function alignRight(str, width) {
@@ -282,4 +230,3 @@ 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.js

@@ -1,8 +1,3 @@
-/**
- * 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)/;
@@ -227,7 +222,6 @@ export class CommandInstance {
                         yargs.getInternalMethods().getUsageInstance().fail(null, error);
                     }
                     catch {
-                        // the failure was reported; yargs swallows the rethrow here
                     }
                 });
             }
@@ -418,4 +412,3 @@ function isCommandBuilderOptionDefinitions(builder) {
 export function isCommandHandlerDefinition(cmd) {
     return typeof cmd === 'object' && !Array.isArray(cmd);
 }
-//# sourceMappingURL=command.js.map

package/dist/yargs/completion.js

@@ -1,7 +1,3 @@
-/**
- * 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-###
@@ -273,4 +269,3 @@ function isSyncCompletionFunction(fn) {
 function isFallbackCompletionFunction(fn) {
     return fn.length > 3;
 }
-//# sourceMappingURL=completion.js.map

package/dist/yargs/factory.js

@@ -1,14 +1,6 @@
-/**
- * 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 { machineJson, schemaOf } from '../schema.js';
 import { tokenizeArgString } from '../yargs-parser.js';
 import { projectManifest, render } from './burgee.js';
@@ -71,7 +63,6 @@ export class YargsInstance {
     #usageConfig = {};
     #versionOpt = null;
     #validation;
-    // ───── burgee: the manifest projection, plugins, --json, the surfaces and the seam ─────
     #burgee = undefined;
     #effects = undefined;
     #manifest = undefined;
@@ -82,7 +73,6 @@ 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;
@@ -602,8 +592,6 @@ 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;
@@ -622,8 +610,6 @@ 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)
@@ -675,8 +661,6 @@ 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();
@@ -920,7 +904,6 @@ export class YargsInstance {
             delete argv['--'];
         }
         catch {
-            // a frozen argv keeps its `--`; yargs ignores the failure
         }
         return argv;
     }
@@ -941,8 +924,6 @@ 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;
                 }
@@ -1060,7 +1041,6 @@ 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];
@@ -1154,32 +1134,19 @@ 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;
@@ -1192,7 +1159,6 @@ 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))
@@ -1234,7 +1200,6 @@ 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;
@@ -1244,7 +1209,6 @@ 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);
@@ -1261,11 +1225,9 @@ 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('--');
@@ -1277,11 +1239,6 @@ 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;
@@ -1289,11 +1246,6 @@ 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('--');
@@ -1315,11 +1267,6 @@ export class YargsInstance {
             });
         }
         if (head.includes('--schema') && !this.#declares('schema')) {
-            // R1, through the same seam the engine and the commander façade use. Hand-rolling
-            // `JSON.stringify(…, null, 2)` here made this façade the one front-end that could not
-            // see `--format=json-pretty`, and emitted a different document from the other two for
-            // the same CLI. `--schema` is burgee's surface, not yargs', so it answers to burgee's
-            // byte discipline.
             this.#logger.log(machineJson(schemaOf(this.manifest), head));
             this.exit(0);
             return true;
@@ -1340,14 +1287,15 @@ export class YargsInstance {
                 return { stdout: out.join(''), stderr: err.join(''), code };
             };
             const write = this.#burgee?.stdout ?? this.#shim.process.stdout();
-            return serveMcp(this.manifest, { input: this.#shim.process.stdin(), output: { write: (s) => void write.write(s) }, invoke }).then(() => {
+            return import('../mcp.js')
+                .then(async ({ serveMcp }) => serveMcp(this.manifest, { input: this.#shim.process.stdin(), output: { write: (s) => void write.write(s) }, invoke }))
+                .then(() => {
                 this.exit(0);
                 return true;
             });
         }
         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) => {
@@ -1368,6 +1316,10 @@ export class YargsInstance {
             .then(async (value) => {
             await manifest.fire('postRun', name, options);
             return settle(value);
+        })
+            .catch(async (cause) => {
+            await manifest.fire('onError', name, options);
+            throw cause;
         });
     }
     #settle(value, argv) {
@@ -1388,7 +1340,6 @@ 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 ?? {};
@@ -1658,4 +1609,3 @@ _a = YargsInstance;
 export function isYargsInstance(y) {
     return !!y && typeof y.getInternalMethods === 'function';
 }
-//# sourceMappingURL=factory.js.map

package/dist/yargs/middleware.js

@@ -1,7 +1,3 @@
-/**
- * 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 = [];
@@ -83,4 +79,3 @@ 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.js

@@ -1,9 +1,3 @@
-/**
- * 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';
@@ -17,7 +11,6 @@ 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;
@@ -35,7 +28,6 @@ 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}\``);
@@ -58,15 +50,6 @@ 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 },
@@ -91,8 +74,6 @@ export const shim = {
         nextTick: (fn, ...args) => {
             host.nextTick(fn, ...args);
         },
-        // Captured, as it was before the seam: `stdColumns` is a value in `PlatformShim`, not
-        // a thunk, so yargs reads whatever this object was built with. Unchanged on purpose.
         stdColumns: typeof host.stdout.columns !== 'undefined' ? host.stdout.columns : null,
         stdin: () => host.stdin,
         stdout: () => host.stdout,
@@ -107,4 +88,3 @@ export const shim = {
     stringWidth,
     y18n: y18n({ directory: locales, updateFiles: false }),
 };
-//# sourceMappingURL=shim.js.map

package/dist/yargs/usage.js

@@ -1,8 +1,3 @@
-/**
- * yargs' usage — the help screen, `fail`, examples, epilogues, descriptions and the
- * version string — ported for `burgee/yargs`. Help is rendered through the cliui port,
- * so yargs' usage tests compare whole screens byte for byte.
- */
 import { objFilter, setBlocking, YError } from './utils.js';
 function isBoolean(fail) {
     return typeof fail === 'boolean';
@@ -60,8 +55,6 @@ export function usage(yargs, shim) {
                 }
             }
             err = err || new YError(msg);
-            // The error rides along so an injected exit (burgee's seam) can tell a usage failure
-            // from a handler's; without a seam yargs exits the process and it is unobservable.
             if (yargs.getExitProcess())
                 return yargs.exit(1, err);
             else if (yargs.getInternalMethods().hasParseCallback())
@@ -484,4 +477,3 @@ function getIndentation(text) {
 function getText(text) {
     return isIndentedText(text) ? text.text : text;
 }
-//# sourceMappingURL=usage.js.map

package/dist/yargs/utils.js

@@ -1,9 +1,3 @@
-/**
- * yargs' small internal modules — yerror, parse-command, argsert, obj-filter, is-promise,
- * levenshtein, maybe-async-result, set-blocking, apply-extends, process-argv — ported
- * for `burgee/yargs`. Its suite imports four of these by their upstream file paths; the
- * oracle shims those paths to this entry, so the names here are the upstream names.
- */
 import { readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, resolve } from 'node:path';
@@ -165,10 +159,6 @@ export function getProcessArgvBin() {
 }
 const nodeRequire = createRequire(import.meta.url);
 let previouslyVisitedConfigs = [];
-/**
- * `extends` in a config object. The upstream resolves a bare specifier with
- * `import.meta.resolve` and then loads it through `require`; both are done from here.
- */
 export function applyExtends(config, cwd, mergeExtends) {
     let defaultConfig = {};
     if (Object.prototype.hasOwnProperty.call(config, 'extends')) {
@@ -218,4 +208,3 @@ function mergeDeep(config1, config2) {
 export function objectKeys(object) {
     return Object.keys(object);
 }
-//# sourceMappingURL=utils.js.map

package/dist/yargs/validation.js

@@ -1,8 +1,3 @@
-/**
- * yargs' validation — demanded options and commands, unknown arguments under strict
- * modes, choices, implications, conflicts, and `recommendCommands` — ported for
- * `burgee/yargs`. Every message is the upstream's through y18n.
- */
 import { argsert, levenshtein as distance, objFilter } from './utils.js';
 const specialKeys = ['$0', '--', '_'];
 export function validation(yargs, usage, shim) {
@@ -264,4 +259,3 @@ export function validation(yargs, usage, shim) {
     };
     return self;
 }
-//# sourceMappingURL=validation.js.map

package/dist/yargs/y18n.js

@@ -1,8 +1,3 @@
-/**
- * y18n 5 — yargs' string table — ported for `burgee/yargs`. The 29 locales ship with
- * burgee under `locales/`, read on first use of a locale, never written (yargs runs
- * y18n with `updateFiles: false`).
- */
 import { readFileSync, statSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { format } from 'node:util';
@@ -120,4 +115,3 @@ export function y18n(opts) {
         locale: table.locale,
     };
 }
-//# sourceMappingURL=y18n.js.map