burgee 0.7.0 → 0.8.0

package/dist/migrate.js

@@ -0,0 +1,284 @@
+import { readdirSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { ambientRuntime, run } from 'bellpull';
+import { GRADED } from './compat.js';
+import { ExitCode } from './exit-code.js';
+export const MAPPING = {
+    commander: 'burgee/commander',
+    yargs: 'burgee/yargs',
+    'yargs/yargs': 'burgee/yargs',
+    'yargs/helpers': 'burgee/yargs/helpers',
+};
+export const HOSTS = ['commander', 'yargs'];
+const WORD = /[A-Za-z0-9_$]/;
+const DIVIDES = new Set([')', ']', '}']);
+function startsRegex(previous) {
+    if (previous === '')
+        return true;
+    if (DIVIDES.has(previous))
+        return false;
+    return !WORD.test(previous.charAt(previous.length - 1));
+}
+function endOfString(source, open) {
+    const quote = source.charAt(open);
+    for (let i = open + 1; i < source.length; i += 1) {
+        const c = source.charAt(i);
+        if (c === '\\') {
+            i += 1;
+            continue;
+        }
+        if (c === quote || c === '\n')
+            return i + 1;
+    }
+    return source.length;
+}
+function endOfTemplate(source, open) {
+    let depth = 0;
+    for (let i = open + 1; i < source.length; i += 1) {
+        const c = source.charAt(i);
+        if (c === '\\') {
+            i += 1;
+            continue;
+        }
+        if (c === '$' && source.charAt(i + 1) === '{') {
+            depth += 1;
+            i += 1;
+            continue;
+        }
+        if (c === '}' && depth > 0) {
+            depth -= 1;
+            continue;
+        }
+        if (c === '`' && depth === 0)
+            return i + 1;
+    }
+    return source.length;
+}
+function endOfRegex(source, open) {
+    let inClass = false;
+    for (let i = open + 1; i < source.length; i += 1) {
+        const c = source.charAt(i);
+        if (c === '\\') {
+            i += 1;
+            continue;
+        }
+        if (c === '[' || c === ']') {
+            inClass = c === '[';
+            continue;
+        }
+        if (c === '\n')
+            return i;
+        if (c === '/' && !inClass)
+            return i + 1;
+    }
+    return source.length;
+}
+function newlines(source, from, to) {
+    let count = 0;
+    for (let i = from; i < to; i += 1)
+        if (source.charAt(i) === '\n')
+            count += 1;
+    return count;
+}
+function isSpecifier(previous, before) {
+    if (previous === 'from' || previous === 'import')
+        return true;
+    return previous === '(' && (before === 'import' || before === 'require');
+}
+function endOfTrivia(source, at) {
+    const c = source.charAt(at);
+    if (c === ' ' || c === '\t' || c === '\r' || c === '\n' || c === ';')
+        return at + 1;
+    if (c !== '/')
+        return at;
+    const next = source.charAt(at + 1);
+    if (next === '/') {
+        const end = source.indexOf('\n', at);
+        return end === -1 ? source.length : end;
+    }
+    if (next !== '*')
+        return at;
+    const end = source.indexOf('*/', at + 2);
+    return end === -1 ? source.length : end + 2;
+}
+function endOfLiteral(source, at, previous) {
+    const c = source.charAt(at);
+    if (c === "'" || c === '"')
+        return endOfString(source, at);
+    if (c === '`')
+        return endOfTemplate(source, at);
+    if (c === '/' && startsRegex(previous))
+        return endOfRegex(source, at);
+    return -1;
+}
+function endOfWord(source, at) {
+    let i = at;
+    while (i < source.length && WORD.test(source.charAt(i)))
+        i += 1;
+    return i;
+}
+const QUOTED = 'str';
+function push(tokens, text, line) {
+    if (tokens.pending && text !== QUOTED && text !== ')')
+        tokens.nonLiteral.push(line);
+    tokens.pending = text === '(' && (tokens.previous === 'import' || tokens.previous === 'require');
+    tokens.before = tokens.previous;
+    tokens.previous = text;
+}
+export function scan(source) {
+    const sites = [];
+    const tokens = { previous: '', before: '', pending: false, nonLiteral: [] };
+    let line = 1;
+    let i = 0;
+    while (i < source.length) {
+        const trivia = endOfTrivia(source, i);
+        if (trivia !== i) {
+            line += newlines(source, i, trivia);
+            i = trivia;
+            continue;
+        }
+        const literal = endOfLiteral(source, i, tokens.previous);
+        if (literal !== -1) {
+            const c = source.charAt(i);
+            const quoted = c === "'" || c === '"';
+            if (quoted && isSpecifier(tokens.previous, tokens.before))
+                sites.push({ specifier: source.slice(i + 1, literal - 1), start: i + 1, end: literal - 1, line });
+            push(tokens, quoted ? QUOTED : 'lit', line);
+            line += newlines(source, i, literal);
+            i = literal;
+            continue;
+        }
+        const word = endOfWord(source, i);
+        if (word !== i) {
+            push(tokens, source.slice(i, word), line);
+            i = word;
+            continue;
+        }
+        push(tokens, source.charAt(i), line);
+        i += 1;
+    }
+    return { sites, nonLiteral: tokens.nonLiteral };
+}
+const NEEDLE_BYTES = HOSTS.map((host) => Buffer.from(host));
+export function mentionsAHost(source) {
+    return typeof source === 'string' ? HOSTS.some((host) => source.includes(host)) : NEEDLE_BYTES.some((bytes) => source.includes(bytes));
+}
+function isDeep(specifier) {
+    if (MAPPING[specifier] !== undefined)
+        return false;
+    return HOSTS.some((host) => specifier.startsWith(`${host}/`));
+}
+export function rewriteSource(source) {
+    if (!mentionsAHost(source))
+        return { source, mapped: [], refused: [], relevant: false };
+    const { sites, nonLiteral } = scan(source);
+    const hits = sites.filter((s) => MAPPING[s.specifier] !== undefined || isDeep(s.specifier));
+    if (hits.length === 0)
+        return { source, mapped: [], refused: [], relevant: false };
+    const refused = [
+        ...hits.filter((s) => isDeep(s.specifier)).map((s) => ({ line: s.line, specifier: s.specifier, reason: 'deep-import' })),
+        ...nonLiteral.map((line) => ({ line, specifier: '', reason: 'non-literal-specifier' })),
+    ].sort((a, b) => a.line - b.line);
+    if (refused.length > 0)
+        return { source, mapped: [], refused, relevant: true };
+    let out = source;
+    const mapped = [];
+    for (const site of [...hits].sort((a, b) => b.start - a.start)) {
+        const to = MAPPING[site.specifier];
+        out = `${out.slice(0, site.start)}${to}${out.slice(site.end)}`;
+        mapped.push({ from: site.specifier, to });
+    }
+    return { source: out, mapped: mapped.reverse(), refused: [], relevant: true };
+}
+const SOURCE_EXTENSIONS = new Set(['.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx', '.mts', '.cts']);
+const SKIP = new Set(['node_modules', '.git', 'dist', 'build', 'coverage', '.turbo', '.next', '.output', '.cache', '.vercel']);
+export function sourceFiles(dir, at = '', found = []) {
+    for (const entry of readdirSync(join(dir, at), { withFileTypes: true })) {
+        const path = at === '' ? entry.name : `${at}/${entry.name}`;
+        if (entry.isDirectory()) {
+            if (!SKIP.has(entry.name))
+                sourceFiles(dir, path, found);
+        }
+        else if (SOURCE_EXTENSIONS.has(entry.name.slice(entry.name.lastIndexOf('.'))))
+            found.push(path);
+    }
+    return found;
+}
+async function declaredHosts(dir) {
+    try {
+        const raw = JSON.parse(await readFile(join(dir, 'package.json'), 'utf8'));
+        const declared = { ...raw.dependencies, ...raw.devDependencies };
+        return HOSTS.filter((host) => declared[host] !== undefined);
+    }
+    catch {
+        return [];
+    }
+}
+export async function workingTree(dir) {
+    const result = await run('git', ['-C', dir, 'status', '--porcelain'], { runtime: ambientRuntime(), stdio: 'pipe' });
+    if (!result.ok)
+        return undefined;
+    return result.stdout.split('\n').filter((line) => line !== '');
+}
+export class DirtyTreeError extends Error {
+    entries;
+    fix = 'commit or stash your changes, or pass --force';
+    constructor(entries) {
+        super(`the git tree has ${entries.length} uncommitted change${entries.length === 1 ? '' : 's'}`);
+        this.entries = entries;
+        this.name = 'DirtyTreeError';
+    }
+}
+const EMPTY = { source: '', mapped: [], refused: [], relevant: false };
+async function migrateBatch(dir, batch, write) {
+    const sources = await Promise.all(batch.map(async (file) => await readFile(join(dir, file))));
+    const results = sources.map((bytes) => (mentionsAHost(bytes) ? rewriteSource(bytes.toString('utf8')) : EMPTY));
+    if (write)
+        await Promise.all(results.map(async (r, i) => (r.mapped.length === 0 ? undefined : await writeFile(join(dir, batch[i]), r.source))));
+    return results;
+}
+function rollup(all) {
+    return Object.entries(MAPPING)
+        .map(([from, to]) => {
+        const hits = all.filter((m) => m.from === from);
+        return { from, to, imports: hits.length, files: new Set(hits.map((m) => m.file)).size };
+    })
+        .filter((row) => row.imports > 0);
+}
+function gradedFor(hosts) {
+    return hosts.filter((host) => GRADED[host] !== undefined).map((host) => ({ host, ...GRADED[host] }));
+}
+const BATCH = 256;
+export async function migrate(options) {
+    const { dir, dryRun = false, force = false } = options;
+    const entries = await (options.status ?? workingTree)(dir);
+    if (!dryRun && !force && entries !== undefined && entries.length > 0)
+        throw new DirtyTreeError(entries);
+    const files = sourceFiles(dir);
+    const results = [];
+    for (let i = 0; i < files.length; i += BATCH) {
+        const batch = files.slice(i, i + BATCH);
+        const done = await migrateBatch(dir, batch, !dryRun);
+        results.push(...done.map((result, k) => ({ file: batch[k], result })));
+    }
+    const all = results.flatMap(({ file, result }) => result.mapped.map((m) => ({ ...m, file })));
+    const refused = results.flatMap(({ file, result }) => result.refused.map((r) => ({ file, ...r })));
+    const imported = [...new Set(results.flatMap(({ result }) => (result.relevant ? result.mapped.map((m) => m.from) : [])))];
+    const declared = await declaredHosts(dir);
+    const stillUsed = new Set(refused.map((r) => r.specifier.split('/')[0] ?? ''));
+    const removable = declared.filter((host) => !stillUsed.has(host));
+    const touched = [...new Set(all.map((m) => m.file))];
+    return {
+        files: touched.length,
+        imports: all.length,
+        mapped: rollup(all),
+        refused,
+        detected: { declared, imported: [...new Set(imported.map((s) => s.split('/')[0] ?? s))].sort() },
+        dependencies: { before: declared, removable, after: declared.length - removable.length },
+        graded: gradedFor([...new Set([...declared, ...imported.map((s) => s.split('/')[0] ?? s)])].sort()),
+        dryRun,
+        changed: !dryRun && touched.length > 0,
+        exitCode: refused.length > 0 ? ExitCode.RUNTIME : ExitCode.OK,
+    };
+}

package/dist/shutdown.d.ts

@@ -2,7 +2,7 @@
  * E5 and O5 — every door out of a burgee program, bound by the package whose job that is.
  *
  * `exit-code.ts` has declared `SIGINT: 130` and *"SIGINT after the terminal was restored"*
- * since the contract was written, and `.sdlc/intents/burgee/design.md` marks both E5 and O5
+ * since the contract was written, and `.sdlc/intents/burgee/spec.md` marks both E5 and O5
  * `R`. Neither was implemented. The engine's only exit was `host.exit(code)` — `process.exit`
  * — which restores nothing, runs nothing, and truncates a pipe by definition (yargs #1519,
  * #2118: *"No truncated JSON"*). A constant is not an implementation.

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,10 +1,3 @@
-/**
- * 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';
@@ -71,7 +64,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 +74,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 +593,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 +611,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 +662,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 +905,6 @@ export class YargsInstance {
             delete argv['--'];
         }
         catch {
-            // a frozen argv keeps its `--`; yargs ignores the failure
         }
         return argv;
     }
@@ -941,8 +925,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 +1042,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 +1135,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 +1160,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 +1201,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 +1210,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 +1226,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 +1240,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 +1247,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 +1268,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;
@@ -1347,7 +1295,6 @@ 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) => {
@@ -1388,7 +1335,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 +1604,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