burgee 0.3.0 → 0.4.0

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;

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

@@ -1,4 +1,9 @@
-import { objFilter, setBlocking, YError } from './yargs-utils.js';
+/**
+ * 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';
 }
@@ -55,6 +60,8 @@ 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())
@@ -477,3 +484,4 @@ function getIndentation(text) {
 function getText(text) {
     return isIndentedText(text) ? text.text : text;
 }
+//# sourceMappingURL=usage.js.map

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

@@ -1,3 +1,9 @@
+/**
+ * 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';
@@ -158,6 +164,10 @@ 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')) {
@@ -207,3 +217,4 @@ function mergeDeep(config1, config2) {
 export function objectKeys(object) {
     return Object.keys(object);
 }
+//# sourceMappingURL=utils.js.map

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

@@ -3,7 +3,7 @@
  * modes, choices, implications, conflicts, and `recommendCommands` — ported for
  * `burgee/yargs`. Every message is the upstream's through y18n.
  */
-import type { PlatformShim } from './yargs-shim.js';
+import type { PlatformShim } from './shim.js';
 export interface ValidationInstance {
     nonOptionCount: (argv: any) => void;
     positionalCount: (required: number, observed: number) => void;

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

@@ -1,4 +1,9 @@
-import { argsert, levenshtein as distance, objFilter } from './yargs-utils.js';
+/**
+ * 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) {
     const __ = shim.y18n.__;
@@ -259,3 +264,4 @@ export function validation(yargs, usage, shim) {
     };
     return self;
 }
+//# sourceMappingURL=validation.js.map

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

@@ -1,3 +1,8 @@
+/**
+ * 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';
@@ -115,3 +120,4 @@ export function y18n(opts) {
         locale: table.locale,
     };
 }
+//# sourceMappingURL=y18n.js.map

package/dist/yargs-helpers.d.ts

@@ -2,5 +2,5 @@
  * `burgee/yargs/helpers` — what `yargs/helpers` exports: `hideBin`, `applyExtends`
  * and the parser.
  */
-export { applyExtends, hideBin } from './yargs-utils.js';
+export { applyExtends, hideBin } from './yargs/utils.js';
 export { Parser } from './yargs-parser.js';

package/dist/yargs-helpers.js

@@ -1,2 +1,2 @@
-export { applyExtends, hideBin } from './yargs-utils.js';
+export { applyExtends, hideBin } from './yargs/utils.js';
 export { Parser } from './yargs-parser.js';

package/dist/yargs.d.ts

@@ -1,6 +1,6 @@
-export { YargsInstance, isYargsInstance, type Options, type ParseCallback } from './yargs-factory.js';
+export { YargsInstance, isYargsInstance, type Options, type ParseCallback } from './yargs/factory.js';
 export { Parser, camelCase, decamelize, looksLikeNumber, type DetailedArguments } from './yargs-parser.js';
-export { applyExtends, argsert, hideBin, isPromise, objFilter, parseCommand, YError, type ParsedCommand } from './yargs-utils.js';
-export { shim as platformShim, type PlatformShim } from './yargs-shim.js';
-declare const Yargs: (processArgs?: string | string[], cwd?: string, parentRequire?: NodeJS.Require) => import("./yargs-factory.js").YargsInstance;
+export { applyExtends, argsert, hideBin, isPromise, objFilter, parseCommand, YError, type ParsedCommand } from './yargs/utils.js';
+export { shim as platformShim, type PlatformShim } from './yargs/shim.js';
+declare const Yargs: (processArgs?: string | string[], cwd?: string, parentRequire?: NodeJS.Require) => import("./yargs/factory.js").YargsInstance;
 export default Yargs;

package/dist/yargs.js

@@ -1,8 +1,8 @@
-import { YargsFactory } from './yargs-factory.js';
-import { shim } from './yargs-shim.js';
-export { YargsInstance, isYargsInstance } from './yargs-factory.js';
+import { YargsFactory } from './yargs/factory.js';
+import { shim } from './yargs/shim.js';
+export { YargsInstance, isYargsInstance } from './yargs/factory.js';
 export { Parser, camelCase, decamelize, looksLikeNumber } from './yargs-parser.js';
-export { applyExtends, argsert, hideBin, isPromise, objFilter, parseCommand, YError } from './yargs-utils.js';
-export { shim as platformShim } from './yargs-shim.js';
+export { applyExtends, argsert, hideBin, isPromise, objFilter, parseCommand, YError } from './yargs/utils.js';
+export { shim as platformShim } from './yargs/shim.js';
 const Yargs = YargsFactory(shim);
 export default Yargs;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "burgee",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "An agent-native CLI framework, drop-in compatible with commander and yargs. One declaration; help, --json, --schema, --mcp and completions all projected from it.",
   "license": "MIT",
   "type": "module",
@@ -69,6 +69,7 @@
     "build": "tsc -p tsconfig.build.json && node ../../scripts/strip-comments.mjs dist",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run --passWithNoTests",
+    "coverage": "vitest run --coverage.enabled",
     "lint": "eslint src"
   },
   "repository": {