burgee 0.12.0 → 0.13.0

package/dist/failure.js

@@ -0,0 +1,90 @@
+import { ConfigError } from 'seniority/precedence';
+import { AuthError, UsageError } from './errors.js';
+import { ExitCode, isExitCode } from './exit-code.js';
+import { kebab } from './names.js';
+function isParseArgsFailure(cause) {
+    if (!(cause instanceof Error))
+        return false;
+    const { code } = cause;
+    return typeof code === 'string' && code.startsWith('ERR_PARSE_ARGS_');
+}
+function exitSignal(cause) {
+    const code = cause?.code;
+    return typeof code === 'number' && isExitCode(code) ? code : undefined;
+}
+const CLASSIFIED = [
+    [UsageError, ExitCode.USAGE],
+    [AuthError, ExitCode.AUTH],
+    [ConfigError, ExitCode.CONFIG],
+];
+const NAMED = new Map([
+    ['USAGE', ExitCode.USAGE],
+    ['CONFIG', ExitCode.CONFIG],
+    ['CANCELLED', ExitCode.CANCELLED],
+    ['AUTH', ExitCode.AUTH],
+]);
+function namedCode(cause) {
+    return NAMED.get(cause?.code);
+}
+function messageOf(cause) {
+    if (cause instanceof Error)
+        return cause.message;
+    const said = cause?.message;
+    return typeof said === 'string' ? said : String(cause);
+}
+function carried(cause) {
+    const { hint, fix } = (cause ?? {});
+    return {
+        ...(typeof hint === 'string' ? { hint } : {}),
+        ...(typeof fix === 'string' ? { fix } : {}),
+    };
+}
+export async function describeFailure(cause, argv, node, action) {
+    const signal = exitSignal(cause);
+    if (signal !== undefined)
+        return { code: signal, message: '', silent: true };
+    const message = messageOf(cause);
+    if (action !== undefined)
+        return { code: ExitCode.CANCELLED, message, action, ...(action.hint === undefined ? {} : { hint: action.hint }) };
+    const named = CLASSIFIED.find(([Class]) => cause instanceof Class);
+    if (named !== undefined)
+        return { code: named[1], message, ...carried(cause) };
+    const own = cause?.constructor?.[Symbol.for('burgee.exitCode')];
+    if (typeof own === 'number')
+        return { code: own, message, ...carried(cause) };
+    const byName = namedCode(cause);
+    if (byName !== undefined)
+        return { code: byName, message, ...carried(cause) };
+    if (isParseArgsFailure(cause)) {
+        const explain = await import('./unknown-option.js');
+        const dash = explain.singleDashHint(argv);
+        if (dash !== undefined)
+            return { code: ExitCode.USAGE, message, hint: dash };
+        const better = explain.unknownOption(cause, Object.keys(node?.options ?? {}).map(kebab));
+        return { code: ExitCode.USAGE, message, hint: 'run --help to see the available options', ...better };
+    }
+    return { code: ExitCode.RUNTIME, message };
+}
+function textFailure(failure) {
+    const hint = failure.hint === undefined ? '' : `hint: ${failure.hint}\n`;
+    const fix = failure.fix === undefined ? '' : `fix: ${failure.fix}\n`;
+    if (failure.action !== undefined) {
+        const next = (failure.action.next ?? []).map((n) => `  ${n.command}    ${n.when}\n`).join('');
+        return `action required (${failure.action.reason}): ${failure.message}\n${next === '' ? '' : `next:\n${next}`}${hint}`;
+    }
+    return `error: ${failure.message}\n${hint}${fix}`;
+}
+function runnableNext(manifest, spec, json) {
+    const program = manifest.rootPath.join(' ');
+    return (spec.next ?? []).map((n) => ({ command: `${program} ${n.command}${json && !n.command.includes('--json') ? ' --json' : ''}`, when: n.when }));
+}
+export function failureText(failure, manifest, json) {
+    if (failure.action !== undefined) {
+        const next = runnableNext(manifest, failure.action, json);
+        const rendered = { ...failure, action: { ...failure.action, next } };
+        const body = { ok: false, status: 'action_required', reason: failure.action.reason, message: failure.message, next, hint: failure.hint, error: { code: failure.code, message: failure.message } };
+        return json ? `${JSON.stringify(body)}\n` : textFailure(rendered);
+    }
+    const body = { code: failure.code, message: failure.message, hint: failure.hint, ...(failure.fix === undefined ? {} : { fix: failure.fix }) };
+    return json ? `${JSON.stringify({ ok: false, error: body })}\n` : textFailure(failure);
+}

package/dist/fields.d.ts

@@ -3,11 +3,6 @@
  * Licensed under the MIT License. Use of this source code is governed by the
  * MIT license that can be found in the LICENSE file.
  */
-/**
- * N14 — what `--json=<fields>` does once it is typed: list the declared fields, refuse an
- * unknown one naming the valid set, select the named fields of a result. Its own chunk,
- * imported by `execute.ts` only when `--json=` is on the command line (M2).
- */
 import { type CommandNode } from './manifest.js';
 /** `--json=` with nothing after it: the declared fields, without running the handler. */
 export declare function listFields(node: CommandNode): {
@@ -25,8 +20,13 @@ export declare function selectFields(data: unknown, fields: readonly string[]):
  * N14 — `--json=a,b` becomes `--json` plus the fields it names; `--json=` alone is an empty
  * list, which asks for the valid set. Only the `=` form takes fields, so `cmd --json name`
  * keeps `name` a positional (D-114). Nothing after `--` is read (G5).
+ *
+ * N15 — `--format=agent` is taken out before the parser sees it and hands back the formatter.
+ * A command that declares its own `format` option keeps the flag, because the program wins;
+ * and after `--` it is the command's, like everything else there.
  */
-export declare function jsonFields(args: readonly string[]): {
+export declare function jsonFields(args: readonly string[], node: CommandNode): {
     args: string[];
     fields?: string[];
+    lines?: (data: unknown) => string;
 };

package/dist/fields.js

@@ -1,3 +1,4 @@
+import { agentLines } from './agent-format.js';
 import { UsageError } from './validate.js';
 const isPlainObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
 function declared(node) {
@@ -33,13 +34,18 @@ export function selectFields(data, fields) {
     const pick = (row) => (isPlainObject(row) ? Object.fromEntries(fields.filter((f) => f in row).map((f) => [f, row[f]])) : row);
     return Array.isArray(data) ? data.map(pick) : pick(data);
 }
-export function jsonFields(args) {
+const AGENT = '--format=agent';
+export function jsonFields(args, node) {
     const end = args.indexOf('--');
-    const head = end === -1 ? args : args.slice(0, end);
+    const all = end === -1 ? args : args.slice(0, end);
+    const agent = node.options['format'] === undefined && all.includes(AGENT);
+    const head = agent ? all.filter((a) => a !== AGENT) : all;
+    const lines = agent ? { lines: agentLines } : {};
+    const tail = end === -1 ? [] : args.slice(end);
     const given = head.findLast((a) => a.startsWith('--json='));
     if (given === undefined)
-        return { args: [...args] };
+        return { args: [...head, ...tail], ...lines };
     const fields = given.slice('--json='.length).split(',').map((f) => f.trim()).filter((f) => f !== '');
     const kept = head.map((a) => (a.startsWith('--json=') ? '--json' : a));
-    return { args: end === -1 ? kept : [...kept, ...args.slice(end)], fields };
+    return { args: [...kept, ...tail], fields, ...lines };
 }

package/dist/mcp.js

@@ -62,6 +62,24 @@ export function argvOf(node, root, args) {
 }
 const STDOUT_CONSOLE = ['log', 'info', 'debug', 'dir', 'dirxml', 'table', 'group', 'groupCollapsed', 'groupEnd', 'count', 'countReset', 'time', 'timeLog', 'timeEnd'];
 let framing = false;
+let sessions = 0;
+let release = () => undefined;
+function holdStdout() {
+    if (sessions++ === 0) {
+        const stdout = host.stdout;
+        const write = stdout.write;
+        stdout.write = function (...args) {
+            return Reflect.apply(framing ? write : host.stderr.write, framing ? stdout : host.stderr, args);
+        };
+        release = () => void (stdout.write = write);
+    }
+    let held = true;
+    return () => {
+        if (held && --sessions === 0)
+            release();
+        held = false;
+    };
+}
 async function printedBy(run) {
     const chunks = [];
     const decoder = new TextDecoder();
@@ -162,7 +180,8 @@ export function startMcp(manifest, opts) {
             session.invoke = invoke;
         reply({ method: 'notifications/tools/list_changed' });
     };
-    const done = serve(session, opts.input, reply);
+    const unhold = holdStdout();
+    const done = serve(session, opts.input, reply).finally(unhold);
     return { done, swap };
 }
 export async function serveMcp(manifest, opts) {

package/dist/migrate.js

@@ -2,7 +2,7 @@ import { existsSync, readdirSync } from 'node:fs';
 import { readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { ambientRuntime, run } from 'bellpull';
-import { DROP_INS, GRADED, GRADED_VERSIONS, isLevel } from './compat.js';
+import { DROP_INS, GRADED, GRADED_VERSIONS, isLevel, SUPPORTED_MAJORS } from './compat.js';
 import { ExitCode } from './exit-code.js';
 export function packageOf(specifier) {
     const parts = specifier.split('/');
@@ -707,7 +707,7 @@ async function offMajorOf(dir, dependencies) {
         if (version === undefined || graded === undefined)
             return [];
         const major = majorOf(version);
-        return major === undefined || major === majorOf(graded) ? [] : [{ from, found: version, graded }];
+        return major === undefined || (SUPPORTED_MAJORS[from] ?? []).includes(major) ? [] : [{ from, found: version, graded }];
     });
 }
 function installer(dir) {

package/dist/program-schema.json

@@ -1 +1 @@
-{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://burgee.dev/program-schema.json","title":"burgee --schema","description":"The document `<program> --schema` prints: the program as data, for an agent or an MCP host to read without running anything. Published so a reader can validate what a program says about itself (burgee F1, D-123); burgee's own test validates `--schema` output against this file on every run.","type":"object","required":["schemaVersion","name","exitCodes","commands"],"additionalProperties":false,"properties":{"schemaVersion":{"const":1,"description":"Bumped only when a field changes meaning."},"name":{"type":"string","description":"The program as typed."},"version":{"type":"string"},"description":{"type":"string"},"exitCodes":{"type":"object","additionalProperties":{"type":"integer"},"description":"What each exit code means (F1): the contract's names and numbers, so a caller branches on the code without reading prose."},"commands":{"type":"array","description":"Every runnable, visible command, in declaration order.","items":{"$ref":"#/$defs/command"}}},"$defs":{"command":{"type":"object","required":["name","arguments","options","examples","inputSchema"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"The command as typed, without the program name: `config get`."},"description":{"type":"string"},"summary":{"type":"string"},"effects":{"type":"string","pattern":"^(read_only|idempotent|non_idempotent|withheld)$","description":"What running it does to the world, or `withheld` (N6)."},"deprecated":{"description":"`true`, or the replacement's name (M5)."},"group":{"type":"string"},"lazy":{"const":true,"description":"Its handler loads on dispatch (M2)."},"plugin":{"type":"string","description":"The plugin that contributed it (M3)."},"fields":{"type":"array","items":{"type":"string"},"description":"The result's top-level fields, what `--json=` selects from (N14)."},"arguments":{"type":"array","items":{"$ref":"#/$defs/argument"}},"options":{"type":"object","additionalProperties":{"$ref":"#/$defs/option"}},"relations":{"type":"array","items":{"type":"object"},"description":"Constraints between options (S2, S6): exactlyOneOf, atLeastOneOf, atMostOneOf, conflicts, implies."},"examples":{"type":"array","items":{"$ref":"#/$defs/example"}},"inputSchema":{"$ref":"#/$defs/inputSchema"}}},"argument":{"type":"object","required":["name"],"additionalProperties":false,"properties":{"name":{"type":"string"},"description":{"type":"string"},"required":{"type":"boolean"},"variadic":{"type":"boolean"},"default":{"type":"string"},"type":{"type":"string","pattern":"^file$","description":"`file`: `-` means standard input (S4)."}}},"option":{"type":"object","required":["type"],"additionalProperties":false,"properties":{"type":{"type":"string","pattern":"^(string|boolean|number)$"},"description":{"type":"string"},"required":{"type":"boolean"},"short":{"type":"string"},"default":{"description":"A string, boolean, number, or a list of strings or numbers."},"env":{"type":"string"},"choices":{"type":"array","items":{"type":"string"}},"multiple":{"type":"boolean"},"separator":{"type":"string"},"dependsOn":{"type":"array","items":{"type":"string"}},"exclusive":{"type":"array","items":{"type":"string"}},"minimum":{"type":"number"},"maximum":{"type":"number"},"integer":{"type":"boolean"},"schema":{"type":"object","description":"A Standard Schema validator, as its own library serialises it."},"placeholder":{"type":"string"},"deprecated":{"description":"`true`, or the replacement's name."},"hidden":{"type":"boolean"},"sharedFrom":{"type":"string"}}},"example":{"type":"object","required":["command"],"additionalProperties":false,"properties":{"command":{"type":"string"},"description":{"type":"string"}}},"inputSchema":{"type":"object","required":["type","properties","required","additionalProperties"],"additionalProperties":false,"description":"The arguments and options as one JSON Schema object — what an MCP tool call takes.","properties":{"type":{"const":"object"},"properties":{"type":"object"},"required":{"type":"array","items":{"type":"string"}},"additionalProperties":{"const":false}}}}}
+{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://burgee.dev/program-schema.json","title":"burgee --schema","description":"The document `<program> --schema` prints: the program as data, for an agent or an MCP host to read without running anything. Published so a reader can validate what a program says about itself (burgee F1, D-123); burgee's own test validates `--schema` output against this file on every run.","type":"object","required":["schemaVersion","name","exitCodes","commands"],"additionalProperties":false,"properties":{"schemaVersion":{"const":1,"description":"Bumped only when a field changes meaning."},"name":{"type":"string","description":"The program as typed."},"version":{"type":"string"},"description":{"type":"string"},"exitCodes":{"type":"object","additionalProperties":{"type":"integer"},"description":"What each exit code means (F1): the contract's names and numbers, so a caller branches on the code without reading prose."},"commands":{"type":"array","description":"Every runnable, visible command, in declaration order.","items":{"$ref":"#/$defs/command"}},"shadows":{"type":"array","minItems":1,"items":{"type":"string","pattern":"^(--json|--mcp|completion)$"},"description":"The reserved surfaces a commander- or yargs-syntax program declares for itself, which burgee therefore withholds (J4): the program wins, and the document says so. Absent when it shadows none; a native program cannot shadow them (V5)."}},"$defs":{"command":{"type":"object","required":["name","arguments","options","examples","inputSchema"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"The command as typed, without the program name: `config get`."},"description":{"type":"string"},"summary":{"type":"string"},"effects":{"type":"string","pattern":"^(read_only|idempotent|non_idempotent|withheld)$","description":"What running it does to the world, or `withheld` (N6)."},"deprecated":{"description":"`true`, or the replacement's name (M5)."},"group":{"type":"string"},"lazy":{"const":true,"description":"Its handler loads on dispatch (M2)."},"plugin":{"type":"string","description":"The plugin that contributed it (M3)."},"fields":{"type":"array","items":{"type":"string"},"description":"The result's top-level fields, what `--json=` selects from (N14)."},"arguments":{"type":"array","items":{"$ref":"#/$defs/argument"}},"options":{"type":"object","additionalProperties":{"$ref":"#/$defs/option"}},"relations":{"type":"array","items":{"type":"object"},"description":"Constraints between options (S2, S6): exactlyOneOf, atLeastOneOf, atMostOneOf, conflicts, implies."},"examples":{"type":"array","items":{"$ref":"#/$defs/example"}},"inputSchema":{"$ref":"#/$defs/inputSchema"}}},"argument":{"type":"object","required":["name"],"additionalProperties":false,"properties":{"name":{"type":"string"},"description":{"type":"string"},"required":{"type":"boolean"},"variadic":{"type":"boolean"},"default":{"type":"string"},"type":{"type":"string","pattern":"^file$","description":"`file`: `-` means standard input (S4)."}}},"option":{"type":"object","required":["type"],"additionalProperties":false,"properties":{"type":{"type":"string","pattern":"^(string|boolean|number)$"},"description":{"type":"string"},"required":{"type":"boolean"},"short":{"type":"string"},"default":{"description":"A string, boolean, number, or a list of strings or numbers."},"env":{"type":"string"},"choices":{"type":"array","items":{"type":"string"}},"multiple":{"type":"boolean"},"separator":{"type":"string"},"dependsOn":{"type":"array","items":{"type":"string"}},"exclusive":{"type":"array","items":{"type":"string"}},"minimum":{"type":"number"},"maximum":{"type":"number"},"integer":{"type":"boolean"},"schema":{"type":"object","description":"A Standard Schema validator, as its own library serialises it."},"placeholder":{"type":"string"},"deprecated":{"description":"`true`, or the replacement's name."},"hidden":{"type":"boolean"},"negatable":{"type":"boolean","description":"Booleans only: whether `--no-<name>` is accepted. Absent means yes; a commander-syntax program's option says `false` where commander would refuse the negation (D-134)."},"sharedFrom":{"type":"string"}}},"example":{"type":"object","required":["command"],"additionalProperties":false,"properties":{"command":{"type":"string"},"description":{"type":"string"}}},"inputSchema":{"type":"object","required":["type","properties","required","additionalProperties"],"additionalProperties":false,"description":"The arguments and options as one JSON Schema object — what an MCP tool call takes.","properties":{"type":{"const":"object"},"properties":{"type":"object"},"required":{"type":"array","items":{"type":"string"}},"additionalProperties":{"const":false}}}}}

package/dist/relations.d.ts

@@ -0,0 +1,7 @@
+import { type Relation } from './manifest.js';
+type Sources = Record<string, {
+    source: string;
+}>;
+/** Relations before anything else (S6, yargs #1186); `--no-x` counts as set, because it was typed (yargs #898). */
+export declare function checkRelations(relations: readonly Relation[] | undefined, values: Record<string, unknown>, sources: Sources): void;
+export {};

package/dist/relations.js

@@ -0,0 +1,49 @@
+import { UsageError } from './errors.js';
+import { flagsOf, kebab } from './names.js';
+const isSet = (values, key, sources) => values[key] !== undefined && sources[key]?.source !== 'default';
+const flagList = (keys) => flagsOf(keys).join(', ');
+function exactlyOne(keys, on) {
+    if (on.length === 1)
+        return;
+    throw new UsageError(`exactly one of ${flagList(keys)} is required`, on.length === 0 ? 'pass one of them' : `drop all but one of ${flagList(on)}`);
+}
+function atLeastOne(keys, on) {
+    if (on.length === 0)
+        throw new UsageError(`at least one of ${flagList(keys)} is required`, 'pass one of them');
+}
+function atMostOne(keys, on) {
+    if (on.length > 1)
+        throw new UsageError(`at most one of ${flagList(keys)} may be given`, `drop all but one of ${flagList(on)}`);
+}
+function noConflict(on) {
+    if (on.length > 1)
+        throw new UsageError(`${flagList(on)} cannot be used together`, 'drop one of them');
+}
+function implied(a, b, values, sources) {
+    if (!isSet(values, a, sources))
+        return;
+    if (typeof b === 'string') {
+        if (!isSet(values, b, sources))
+            throw new UsageError(`--${kebab(a)} requires --${kebab(b)}`, `pass --${kebab(b)}`);
+        return;
+    }
+    if (!b(values))
+        throw new UsageError(`--${kebab(a)} is not allowed with these values`, `check the values --${kebab(a)} is declared to require`);
+}
+function checkRelation(rel, values, sources) {
+    const set = (keys) => keys.filter((k) => isSet(values, k, sources));
+    if ('exactlyOneOf' in rel)
+        exactlyOne(rel.exactlyOneOf, set(rel.exactlyOneOf));
+    else if ('atLeastOneOf' in rel)
+        atLeastOne(rel.atLeastOneOf, set(rel.atLeastOneOf));
+    else if ('atMostOneOf' in rel)
+        atMostOne(rel.atMostOneOf, set(rel.atMostOneOf));
+    else if ('conflicts' in rel)
+        noConflict(set(rel.conflicts));
+    else
+        implied(rel.implies[0], rel.implies[1], values, sources);
+}
+export function checkRelations(relations, values, sources) {
+    for (const rel of relations ?? [])
+        checkRelation(rel, values, sources);
+}

package/dist/schema.d.ts

@@ -107,6 +107,13 @@ export interface ProgramSchema {
      */
     exitCodes: Readonly<Record<string, number>>;
     commands: CommandSchema[];
+    /**
+     * J4 — the reserved surfaces a façade program declares for itself, which burgee therefore
+     * withholds: the program wins, and this says so rather than leaving a caller to find the
+     * surface missing. Absent when it shadows none. A native program cannot shadow them —
+     * `defineProgram` refuses the names (V5) — so only the commander and yargs façades set it.
+     */
+    shadows?: ('--json' | '--mcp' | 'completion')[];
 }
 export declare function inputSchemaOf(node: CommandNode): JsonSchema;
 /** The typed name of a node: its path without the program's own name. */

package/dist/surfaces.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Everything the engine answers without running a command — help, `--version`, `help
+ * [command…]`, `completion <shell>`, `__complete`, `config explain`, `--schema` and `--mcp` —
+ * kept off the startup path (U5).
+ *
+ * `execute.ts` imports this module only when argv asks for one of them, or when argv resolves
+ * no runnable command. A run that dispatches a handler, which is every run a program exists
+ * for, never loads a byte of it. Each surface was already asynchronous, and each already loaded
+ * its own body (`help.js`, `schema.js`, `completions.js`, `mcp.js` …) behind an `await
+ * import()`; what moved here is the routing and the glue that used to sit in the entry chunk.
+ */
+import { type Resolution } from 'seniority/precedence';
+import { type ExitCode as ExitCodeType } from './exit-code.js';
+import { type CommandNode, type Manifest, type OptionSpec } from './manifest.js';
+import { type Package } from './pkg.js';
+/** The slice of the engine's `Io` a surface reads. */
+export interface SurfaceIo {
+    out: {
+        write: (s: string) => unknown;
+    };
+    env: Record<string, string | undefined>;
+    width: number;
+    stdin: NodeJS.ReadableStream;
+    /** The package.json owning the entry file, read once (V4). */
+    pkg: Package | undefined;
+    tty: boolean;
+}
+/** What a surface needs back from the engine: precedence for `config explain`, a run for `--mcp`. */
+export interface Engine {
+    resolution: (specs: Record<string, OptionSpec>, flags: Record<string, unknown>) => Promise<Resolution>;
+    execute: (manifest: Manifest, opts: {
+        argv: string[];
+        env: Record<string, string | undefined>;
+        stdout: {
+            write: (s: string) => unknown;
+        };
+        stderr: {
+            write: (s: string) => unknown;
+        };
+        exit: (code: number) => void;
+    }) => Promise<void>;
+}
+/** What to do when argv resolves to no runnable command: help, or a usage error naming it. */
+interface Resolving {
+    manifest: Manifest;
+    root: string[];
+    io: SurfaceIo;
+}
+/**
+ * `--help` on a command that resolved: prose, or — with `--json` beside it — the help document
+ * (F2). It printed the same prose as `--help` with both flags, so a caller who asked for a
+ * machine-readable answer got one they had to parse: the exact failure the `--json` surface
+ * exists to avoid, on the flag people type first.
+ */
+export declare function helpFor(manifest: Manifest, node: CommandNode, io: SurfaceIo, json: boolean): Promise<string>;
+/** `--version`: the declared version, else the owning package.json's (V4). */
+export declare function versionOf(manifest: Manifest, io: Pick<SurfaceIo, 'pkg'>): string;
+/**
+ * What to do when argv resolves to no runnable command: help, the version, or a usage error
+ * naming it.
+ *
+ * `--version` is the same courtesy `--help` gets, for the flag people type first. A program
+ * that is a pure command group resolves nothing for `burgee --version`, so it fell through
+ * to `unknown command "--version"` and **exit 2** — which under E1 means *rewrite the
+ * command*, so an agent asked for the version would rewrite it until it gave up. Real
+ * commander and real yargs both print the version and exit 0 for the identical program.
+ *
+ * `-V` is commander's spelling, and `commander-command.ts` already defaults to
+ * `-V, --version`. Like `HELP_FLAGS` above, this does not check whether the root declares
+ * an option of the same name: a root that is not runnable has no path that would answer it.
+ */
+export declare function unresolved({ manifest, root, io }: Resolving, argv: string[], at: CommandNode | undefined): Promise<{
+    text: string;
+    code: ExitCodeType;
+}>;
+/**
+ * `--schema` (F1, N8) and `--mcp` (N1) are served for every program from the manifest
+ * alone, before any command resolves: no config, no network, no handler runs.
+ */
+export declare function serve(manifest: Manifest, argv: string[], io: SurfaceIo, engine: Engine): Promise<boolean>;
+export {};

package/dist/surfaces.js

@@ -0,0 +1,116 @@
+import { ConfigError } from 'seniority/precedence';
+import { detectAgent } from './agent.js';
+import { beforeTerminator, isJsonFlag } from './argv.js';
+import { UsageError } from './errors.js';
+import { ExitCode } from './exit-code.js';
+const HELP_FLAGS = new Set(['--help', '-h']);
+async function helpDocumentOf(manifest, node) {
+    const { commandSchemaOf, typedName } = await import('./schema.js');
+    const root = manifest.rootPath;
+    const children = manifest.commands
+        .filter((c) => c.path.length === node.path.length + 1 && c.path.slice(0, node.path.length).join(' ') === node.path.join(' '))
+        .map((c) => typedName(c, root));
+    return {
+        schemaVersion: 1,
+        ...commandSchemaOf(node, root),
+        ...(children.length === 0 ? {} : { commands: children }),
+    };
+}
+function rootNode(manifest, root) {
+    return manifest.find(root) ?? { path: root, options: {} };
+}
+const renderHelp = async (manifest, node, io) => {
+    const help = await import('./help.js');
+    return help.renderHelp(manifest, node, { width: io.width, color: help.colorFor(io.env, detectAgent(io.env, io.tty).interactive) });
+};
+const machineJson = async (...args) => (await import('./schema.js')).machineJson(...args);
+export async function helpFor(manifest, node, io, json) {
+    if (json)
+        return `${await machineJson(await helpDocumentOf(manifest, node), ['--json'])}\n`;
+    return await renderHelp(manifest, node, io);
+}
+export function versionOf(manifest, io) {
+    const declared = manifest.version ?? (typeof io.pkg?.data['version'] === 'string' ? io.pkg.data['version'] : undefined);
+    if (declared === undefined)
+        throw new ConfigError('no version declared', 'pass version to defineProgram, or set "version" in the owning package.json');
+    return declared;
+}
+export async function unresolved({ manifest, root, io }, argv, at) {
+    const node = at ?? rootNode(manifest, root);
+    const typed = argv.slice(node.path.length - root.length);
+    const first = typed[0] ?? '';
+    if (typed.length > 0 && HELP_FLAGS.has(first)) {
+        if (beforeTerminator(typed).some(isJsonFlag))
+            return { text: `${await machineJson(await helpDocumentOf(manifest, node), beforeTerminator(argv))}\n`, code: ExitCode.OK };
+        return { text: await renderHelp(manifest, node, io), code: ExitCode.OK };
+    }
+    if (first === '--version' || first === '-V')
+        return { text: `${versionOf(manifest, io)}\n`, code: ExitCode.OK };
+    if (typed.length === 0)
+        return { text: await renderHelp(manifest, node, io), code: ExitCode.USAGE };
+    throw new UsageError(`unknown command "${typed[0] ?? ''}"`, 'run --help to see the available commands');
+}
+async function completion(manifest, argv, io) {
+    if (argv[0] !== 'completion' || manifest.find([...manifest.rootPath, 'completion']) !== undefined)
+        return false;
+    const { renderCompletion, renderFigSpec, SHELLS } = await import('./completions.js');
+    const shell = argv[1] ?? '';
+    if (shell === 'fig') {
+        io.out.write(`${JSON.stringify(renderFigSpec(manifest), null, 2)}\n`);
+        return true;
+    }
+    const known = SHELLS.find((s) => s === shell);
+    if (known === undefined)
+        throw new UsageError(`unknown shell "${shell}"`, `completion ${SHELLS.join('|')}|fig`);
+    io.out.write(renderCompletion(manifest, known));
+    return true;
+}
+async function helpCommand(manifest, argv, root, io) {
+    const { node } = manifest.resolve(argv, root);
+    return renderHelp(manifest, node ?? rootNode(manifest, root), io);
+}
+export async function serve(manifest, argv, io, engine) {
+    const head = beforeTerminator(argv);
+    if (argv[0] === '__complete') {
+        await (await import('./complete-dynamic.js')).completeDynamic(manifest, argv.slice(1), (t) => io.out.write(t));
+        return true;
+    }
+    const root = manifest.rootPath;
+    if (head[0] === 'config' && head[1] === 'explain' && manifest.config !== undefined && manifest.find([...root, 'config', 'explain']) === undefined) {
+        const { explainConfig } = await import('./config-explain.js');
+        io.out.write(await explainConfig(manifest, head.slice(2), engine.resolution));
+        return true;
+    }
+    if (await completion(manifest, argv, io))
+        return true;
+    if (argv[0] === 'help') {
+        io.out.write(await helpCommand(manifest, argv.slice(1), manifest.rootPath, io));
+        return true;
+    }
+    if (head.includes('--schema')) {
+        const { schemaSurface } = await import('./schema-surface.js');
+        io.out.write(`${await machineJson(await schemaSurface(manifest, argv), head)}\n`);
+        return true;
+    }
+    if (head[0] === '--mcp') {
+        const invoke = async (args) => {
+            const out = [];
+            const err = [];
+            let code = 0;
+            await engine.execute(manifest, {
+                argv: args,
+                env: io.env,
+                stdout: { write: (s) => out.push(s) },
+                stderr: { write: (s) => err.push(s) },
+                exit: (c) => {
+                    code = c;
+                },
+            });
+            return { stdout: out.join(''), stderr: err.join(''), code };
+        };
+        const { serveMcp } = await import('./mcp.js');
+        await serveMcp(manifest, { input: io.stdin, output: io.out, invoke });
+        return true;
+    }
+    return false;
+}

package/dist/validate.d.ts

@@ -1,9 +1,4 @@
-import { type OptionSpec, type Relation } from './manifest.js';
-type Sources = Record<string, {
-    source: string;
-}>;
-/** Relations before anything else (S6, yargs #1186); `--no-x` counts as set, because it was typed (yargs #898). */
-export declare function checkRelations(relations: readonly Relation[] | undefined, values: Record<string, unknown>, sources: Sources): void;
+import { type OptionSpec } from './manifest.js';
 export declare function toNumber(key: string, spec: OptionSpec, raw: unknown): number;
 /** Split a repeatable option's raw values on its separator; arrays from config pass through (S8, yargs #846). */
 export declare function splitMultiple(spec: OptionSpec, raw: unknown): unknown[];

package/dist/validate.js

@@ -1,52 +1,5 @@
 import { UsageError } from './errors.js';
-import { flagsOf, kebab } from './names.js';
-const isSet = (values, key, sources) => values[key] !== undefined && sources[key]?.source !== 'default';
-const flagList = (keys) => flagsOf(keys).join(', ');
-function exactlyOne(keys, on) {
-    if (on.length === 1)
-        return;
-    throw new UsageError(`exactly one of ${flagList(keys)} is required`, on.length === 0 ? 'pass one of them' : `drop all but one of ${flagList(on)}`);
-}
-function atLeastOne(keys, on) {
-    if (on.length === 0)
-        throw new UsageError(`at least one of ${flagList(keys)} is required`, 'pass one of them');
-}
-function atMostOne(keys, on) {
-    if (on.length > 1)
-        throw new UsageError(`at most one of ${flagList(keys)} may be given`, `drop all but one of ${flagList(on)}`);
-}
-function noConflict(on) {
-    if (on.length > 1)
-        throw new UsageError(`${flagList(on)} cannot be used together`, 'drop one of them');
-}
-function implied(a, b, values, sources) {
-    if (!isSet(values, a, sources))
-        return;
-    if (typeof b === 'string') {
-        if (!isSet(values, b, sources))
-            throw new UsageError(`--${kebab(a)} requires --${kebab(b)}`, `pass --${kebab(b)}`);
-        return;
-    }
-    if (!b(values))
-        throw new UsageError(`--${kebab(a)} is not allowed with these values`, `check the values --${kebab(a)} is declared to require`);
-}
-function checkRelation(rel, values, sources) {
-    const set = (keys) => keys.filter((k) => isSet(values, k, sources));
-    if ('exactlyOneOf' in rel)
-        exactlyOne(rel.exactlyOneOf, set(rel.exactlyOneOf));
-    else if ('atLeastOneOf' in rel)
-        atLeastOne(rel.atLeastOneOf, set(rel.atLeastOneOf));
-    else if ('atMostOneOf' in rel)
-        atMostOne(rel.atMostOneOf, set(rel.atMostOneOf));
-    else if ('conflicts' in rel)
-        noConflict(set(rel.conflicts));
-    else
-        implied(rel.implies[0], rel.implies[1], values, sources);
-}
-export function checkRelations(relations, values, sources) {
-    for (const rel of relations ?? [])
-        checkRelation(rel, values, sources);
-}
+import { kebab } from './names.js';
 const isFinite = (n) => Number.isFinite(n);
 const numberOf = (raw) => {
     if (typeof raw === 'number')

package/dist/yargs/factory.d.ts

@@ -61,6 +61,13 @@ export interface BurgeeSeam {
     stdout?: Writer;
     stderr?: Writer;
     exit?: (code: number) => void;
+    /**
+     * The behavioural floor (J3, D-121), off by default because yargs' own suite asserts the old
+     * behaviour: a usage failure exits 2 (E1) rather than 1, and a handler that throws or rejects
+     * prints one line and exits with its E1 code, never the help screen and a stack. On its own
+     * it injects nothing — the program's output stays yargs' own.
+     */
+    floor?: boolean;
 }
 export declare function YargsFactory(shim: PlatformShim): (processArgs?: string | string[], cwd?: string, parentRequire?: NodeJS.Require) => YargsInstance;
 export declare class YargsInstance {
@@ -187,7 +194,7 @@ export declare class YargsInstance {
      * 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: BurgeeSeam): this;
+    burgee({ floor, ...seam }: BurgeeSeam): this;
 }
 export declare function isYargsInstance(y: any): y is YargsInstance;
 export {};