burgee 0.12.1 → 0.13.1

package/README.md

@@ -20,7 +20,8 @@
 </p>
 
 <p align="center">
-  Docs: <a href="https://burgee.interlace.tools/docs/packages/burgee">https://burgee.interlace.tools/docs/packages/burgee</a>
+  Docs: <a href="https://burgee.interlace.tools/docs/packages/burgee">https://burgee.interlace.tools/docs/packages/burgee</a><br />
+  Migrating from: <a href="https://burgee.interlace.tools/docs/vs/commander">commander</a> · <a href="https://burgee.interlace.tools/docs/vs/yargs">yargs</a>
 </p>
 
 A **burgee** is the small swallowtail flag a boat flies to say which club or fleet it

package/dist/agent-format.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Copyright (c) 2026 Ofri Peretz
+ * Licensed under the MIT License. Use of this source code is governed by the
+ * MIT license that can be found in the LICENSE file.
+ */
+/** The result as `--format=agent` prints it: one line per record, each ending in a newline. */
+export declare function agentLines(data: unknown): string;

package/dist/agent-format.js

@@ -0,0 +1,32 @@
+const SPACE = /\s+/g;
+const UNSAFE = /^$|[ =",\p{Cc}]/u;
+const text = (value) => String(value).replace(SPACE, ' ').trim();
+function scalar(value) {
+    const s = text(value);
+    return UNSAFE.test(s) ? JSON.stringify(s) : s;
+}
+const isScalar = (value) => value === null || typeof value !== 'object';
+const children = (value, key) => Object.entries(value).map(([k, v]) => [key === '' ? k : `${key}.${k}`, v]);
+function line(record) {
+    if (isScalar(record))
+        return text(record);
+    const out = [];
+    const stack = children(record, '').reverse();
+    for (let next = stack.pop(); next !== undefined; next = stack.pop()) {
+        const [key, value] = next;
+        if (isScalar(value))
+            out.push(`${key}=${scalar(value)}`);
+        else if (Array.isArray(value) && value.every(isScalar))
+            out.push(`${key}=${value.map(scalar).join(',')}`);
+        else
+            for (const child of children(value, key).reverse())
+                stack.push(child);
+    }
+    return out.join(' ');
+}
+export function agentLines(data) {
+    const json = JSON.stringify(data);
+    const value = json === undefined ? null : JSON.parse(json);
+    const records = value === null ? [] : [value].flat();
+    return records.map((r) => `${line(r)}\n`).join('');
+}

package/dist/argv.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The readings of argv that both the engine and its lazily loaded surfaces make, in one place so
+ * they cannot disagree: where options end, which flag asks for `--json`, and whether a surface
+ * might be asked for.
+ */
+/** The part of argv the parser will read as options: everything before `--`. */
+export declare function beforeTerminator(argv: readonly string[]): readonly string[];
+/** `--json`, or `--json=<fields>` (N14). */
+export declare function isJsonFlag(arg: string): boolean;
+/**
+ * Whether argv could be asking for a surface — the cheap test the engine runs on every
+ * invocation, so `surfaces.js` loads only when it might answer (U5). It admits a superset:
+ * `serve` there still checks each surface's own condition (a program that defines its own
+ * `completion`, `config explain` without config) and answers `false` when none applies.
+ */
+export declare function mayServe(argv: readonly string[]): boolean;

package/dist/argv.js

@@ -0,0 +1,12 @@
+export function beforeTerminator(argv) {
+    const at = argv.indexOf('--');
+    return at === -1 ? argv : argv.slice(0, at);
+}
+export function isJsonFlag(arg) {
+    return arg === '--json' || arg.startsWith('--json=');
+}
+export function mayServe(argv) {
+    const head = beforeTerminator(argv);
+    const first = argv[0];
+    return first === '__complete' || first === 'completion' || first === 'help' || head[0] === '--mcp' || (head[0] === 'config' && head[1] === 'explain') || head.includes('--schema');
+}

package/dist/commander/command.d.ts

@@ -151,6 +151,8 @@ export declare class Command extends EventEmitter {
     _deprecationWarned: boolean;
     /** burgee: set for the duration of a parse that injected the streams or the exit. */
     _burgee: Burgee | undefined;
+    /** burgee: the behavioural floor, read on the root and turned on by `.burgee({ floor: true })` (J3). */
+    _floor: boolean;
     constructor(name?: string);
     /** Copy settings useful to share between the root and its subcommands. */
     copyInheritedSettings(sourceCommand: Command): this;
@@ -365,6 +367,16 @@ export declare class Command extends EventEmitter {
     _burgeeSurface(userArgs: string[]): boolean | Promise<boolean>;
     /** The surfaces after `completion`: `--schema` is synchronous, `--mcp` serves until stdin closes. */
     _burgeeSurfaceRest(head: string[]): boolean | Promise<boolean>;
+    /**
+     * burgee: turn on what changes commander's observable behaviour, in one call (J3, D-121). Off
+     * by default, because commander's own suite asserts the old behaviour. With `floor: true` a
+     * usage error exits 2 (E1) rather than 1, and an action that throws or rejects prints one
+     * `error:` line and sets its E1 exit code rather than escaping as a stack. A program that
+     * called `exitOverride()` took its exits over and keeps them.
+     */
+    burgee(options: {
+        floor?: boolean;
+    }): this;
     /** Additive, and the point of the whole exercise: plugins commander has never had (#2505, unlanded). */
     use(plugin: Plugin): this;
     /** Inject the streams and the exit for one parse; returns commander's own parse options. */

package/dist/commander/command.js

@@ -102,6 +102,7 @@ export class Command extends EventEmitter {
     _deprecated = undefined;
     _deprecationWarned = false;
     _burgee = undefined;
+    _floor = false;
     constructor(name) {
         super();
         this._args = this.registeredArguments;
@@ -304,7 +305,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
         if (this._exitCallback) {
             this._exitCallback(new CommanderError(exitCode, code, message));
         }
-        return host.exit(exitCode);
+        return host.exit(this._root()._floor ? e1({ code, exitCode }) : exitCode);
     }
     action(fn) {
         const listener = (args) => {
@@ -1479,7 +1480,8 @@ Expecting one of '${HELP_POSITIONS.join("', '")}'`);
     _burgeeSurfaceRest(head) {
         const root = this._root();
         if (head.includes('--schema') && !root._declares('--schema')) {
-            root._outputConfiguration.writeOut(`${machineJson(schemaOf(this.manifest), head)}\n`);
+            const shadows = ['--json', '--mcp', 'completion'].filter((name) => root._declares(name) || root._findCommand(name) !== undefined);
+            root._outputConfiguration.writeOut(`${machineJson({ ...schemaOf(this.manifest), ...(shadows.length > 0 && { shadows }) }, head)}\n`);
             return true;
         }
         if (head[0] === '--mcp' && !root._declares('--mcp')) {
@@ -1495,6 +1497,10 @@ Expecting one of '${HELP_POSITIONS.join("', '")}'`);
         }
         return false;
     }
+    burgee(options) {
+        this._root()._floor = options.floor === true;
+        return this;
+    }
     use(plugin) {
         this.manifest.use(plugin);
         return this;
@@ -1560,11 +1566,11 @@ Expecting one of '${HELP_POSITIONS.join("', '")}'`);
             this._burgee = undefined;
         };
         const fail = (err) => {
-            const json = this._burgee?.json === true && !(err instanceof CommanderError);
-            if (json)
+            const report = (this._burgee?.json === true || (this._floor && this._exitCallback === null)) && !(err instanceof CommanderError);
+            if (report)
                 host.exitCode = this._reportHandlerFailure(err);
             done();
-            if (!json)
+            if (!report)
                 throw err;
         };
         try {

package/dist/compat.d.ts

@@ -63,5 +63,27 @@ export declare const DROP_INS: readonly DropIn[];
  * `scripts/migrate-drop-ins-lock.test.ts` holds each equal to the oracle's.
  */
 export declare const GRADED_VERSIONS: Readonly<Record<string, string>>;
+/**
+ * C1 — the majors of each incumbent its drop-in claims, per incumbent package, highest last.
+ *
+ * A major is on this list only when the incumbent's **own suite at that major** grades the
+ * drop-in level with the incumbent itself (D-137), so the list is a measurement and not a
+ * range somebody believed. The current major is the one in `GRADED_VERSIONS`. An older one
+ * needs a row in `compat-oracle`'s `PREVIOUS_MAJORS` — the suite vendored at that major's last
+ * tag and graded in CI by `compat.yml`'s ratchet job — whose baseline passes as many cases as
+ * its control does.
+ *
+ * Two older majors are graded today and **neither is claimed**, because neither is level:
+ * commander 14 grades 1329 / 1331 (15 names the surplus argument in the excess-arguments
+ * message, 14 does not) and yargs 17 grades 191 / 794 (17's `require('yargs')` is a
+ * singleton, which 18 removed). The measurements are on the compatibility page; the claim
+ * waits for the number.
+ *
+ * `migrate` reads this, and not `GRADED_VERSIONS`, to decide a project is on a major it may
+ * rewrite — so a major that becomes level here is a major `migrate` serves, with no second
+ * edit. `scripts/supported-majors-lock.test.ts` holds every entry to `GRADED_VERSIONS` and to
+ * the oracle's graded rows.
+ */
+export declare const SUPPORTED_MAJORS: Readonly<Record<string, readonly number[]>>;
 /** Level: the drop-in passes every case the incumbent passes against its own suite (D-137). */
 export declare const isLevel: (host: string) => boolean;

package/dist/compat.js

@@ -86,6 +86,35 @@ export const GRADED_VERSIONS = {
     yargs: '18.1.0',
     'yargs-parser': '22.0.0',
 };
+export const SUPPORTED_MAJORS = {
+    '@clack/prompts': [1],
+    '@inquirer/core': [12],
+    'ansi-escapes': [7],
+    boxen: [8],
+    chalk: [6],
+    'cli-table3': [0],
+    commander: [15],
+    cosmiconfig: [10],
+    'cross-spawn': [7],
+    dotenv: [17],
+    'exit-hook': [5],
+    lilconfig: [3],
+    'log-update': [8],
+    meow: [14],
+    ora: [9],
+    rc: [1],
+    'restore-cursor': [5],
+    'signal-exit': [4],
+    'slice-ansi': [7],
+    'string-width': [8],
+    'strip-ansi': [7],
+    'term-img': [7],
+    'terminal-link': [5],
+    which: [7],
+    'wrap-ansi': [10],
+    yargs: [18],
+    'yargs-parser': [22],
+};
 export const isLevel = (host) => {
     const row = GRADED[host];
     return row !== undefined && row.passed >= row.control;

package/dist/config-layers.d.ts

@@ -0,0 +1,16 @@
+/**
+ * V6 — the config file and the package.json field, as precedence layers, for a program that
+ * opted into config discovery.
+ *
+ * Its own module since 2026-09-24 (U5): `execute.ts` imports it only when the manifest declares
+ * `config`, so a program that never reads a config file carries none of this — as it already
+ * carried none of `seniority/config`, which this reaches the same way.
+ */
+import { type Layers } from 'seniority/precedence';
+import { type Package } from './pkg.js';
+/** The config file and the package.json field, for a program that opted in; loaded lazily (K6). */
+export declare function configLayers(name: string, values: Record<string, unknown>, io: {
+    cwd: string;
+    env: Record<string, string | undefined>;
+    pkg: Package | undefined;
+}): Promise<Pick<Layers, 'config' | 'pkg'>>;

package/dist/config-layers.js

@@ -0,0 +1,19 @@
+function packageLayer(pkg, name) {
+    if (pkg === undefined || name === undefined)
+        return undefined;
+    const field = pkg.data[name];
+    return typeof field === 'object' && field !== null && !Array.isArray(field) ? { path: pkg.path, data: field } : undefined;
+}
+export async function configLayers(name, values, io) {
+    const { discover } = await import('seniority/config');
+    const explicit = values['config'];
+    const disabled = values['noConfig'] === true;
+    const loaded = await discover({ name, cwd: io.cwd, env: io.env, ...(typeof explicit === 'string' ? { explicit } : {}), disabled });
+    const out = {};
+    if (loaded !== undefined)
+        out.config = { path: loaded.chain.join(' ← '), data: loaded.data };
+    const pkg = disabled ? undefined : packageLayer(io.pkg, name);
+    if (pkg !== undefined)
+        out.pkg = pkg;
+    return out;
+}

package/dist/execute.d.ts

@@ -108,8 +108,6 @@ export interface RunOptions {
     /** The entry file, whose nearest package.json owns the program's version (V4); `process.argv[1]` otherwise. */
     entry?: string;
 }
-/** The part of argv the parser will read as options: everything before `--`. */
-export declare function beforeTerminator(argv: readonly string[]): readonly string[];
 export declare function execute(manifest: Manifest, opts?: RunOptions & {
     root?: string[];
     from?: 'node' | 'user';
@@ -131,4 +129,4 @@ export declare function runCommand(manifest: Manifest, argv: readonly string[],
  * through `execute`, so there is exactly one code path from argv to exit.
  */
 export declare function run<S extends OptionSpecs>(target: Command<S> | Manifest, opts?: RunOptions): Promise<void>;
-export {};
+export { beforeTerminator } from './argv.js';

package/dist/execute.js

@@ -1,7 +1,8 @@
 import { dirname } from 'node:path';
 import { parseArgs } from 'node:util';
-import { ConfigError, resolve as resolveLayers } from 'seniority/precedence';
+import { resolve as resolveLayers } from 'seniority/precedence';
 import { detectAgent } from './agent.js';
+import { beforeTerminator, isJsonFlag, mayServe } from './argv.js';
 import { checkCommand } from './definition.js';
 import { ExitCode, isExitCode } from './exit-code.js';
 import { Manifest, relationsOf } from './manifest.js';
@@ -9,7 +10,7 @@ import { camel, kebab } from './names.js';
 import { nearestPackage } from './pkg.js';
 import { host } from './runtime.js';
 import { detachedTeardown, processTeardown } from './shutdown.js';
-import { AuthError, checkRelations, coerce, UsageError } from './validate.js';
+import { coerce, UsageError } from './validate.js';
 function helpFields(c) {
     const node = {};
     if (c.description !== undefined)
@@ -152,31 +153,12 @@ function canonical(values, specs, tokens) {
     }
     return out;
 }
-function packageLayer(pkg, name) {
-    if (pkg === undefined || name === undefined)
-        return undefined;
-    const field = pkg.data[name];
-    return typeof field === 'object' && field !== null && !Array.isArray(field) ? { path: pkg.path, data: field } : undefined;
-}
-async function configLayers(name, values, io) {
-    const { discover } = await import('seniority/config');
-    const explicit = values['config'];
-    const disabled = values['noConfig'] === true;
-    const loaded = await discover({ name, cwd: io.cwd, env: io.env, ...(typeof explicit === 'string' ? { explicit } : {}), disabled });
-    const out = {};
-    if (loaded !== undefined)
-        out.config = { path: loaded.chain.join(' ← '), data: loaded.data };
-    const pkg = disabled ? undefined : packageLayer(io.pkg, name);
-    if (pkg !== undefined)
-        out.pkg = pkg;
-    return out;
-}
 async function resolution(manifest, specs, values, io) {
     const layers = { flags: values, env: io.env };
     if (manifest.envPrefix !== undefined)
         layers.envPrefix = manifest.envPrefix;
     if (manifest.config !== undefined)
-        Object.assign(layers, await configLayers(manifest.config.name, values, io));
+        Object.assign(layers, await (await import('./config-layers.js')).configLayers(manifest.config.name, values, io));
     return resolveLayers(specs, layers);
 }
 async function resolveValues(manifest, specs, values, io) {
@@ -206,192 +188,12 @@ function splitPositionals(tokens) {
     }
     return { positionals, passthrough };
 }
-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 } : {}),
-    };
-}
-async function describeFailure(cause, argv, node) {
-    const signal = exitSignal(cause);
-    if (signal !== undefined)
-        return { code: signal, message: '', silent: true };
-    const message = messageOf(cause);
-    if (cause instanceof ActionRequired)
-        return { code: ExitCode.CANCELLED, message, action: cause.spec, ...(cause.spec.hint === undefined ? {} : { hint: cause.spec.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 }));
-}
-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 }),
-    };
-}
 const HELP_WIDTH = 100;
 const processExit = (code) => host.exit(code);
 async function leave(io, code) {
     await io.teardown.run(code);
     io.exit(code);
 }
-export function beforeTerminator(argv) {
-    const at = argv.indexOf('--');
-    return at === -1 ? argv : argv.slice(0, at);
-}
-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);
-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 surface(manifest, argv, io) {
-    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), (specs, flags) => resolution(manifest, specs, flags, io)));
-        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 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;
-}
-async function helpCommand(manifest, argv, root, io) {
-    const { node } = manifest.resolve(argv, root);
-    return renderHelp(manifest, node ?? rootNode(manifest, root), io);
-}
 function changedOf(node, data) {
     const value = isPlainObject(data) ? data['changed'] : undefined;
     if (typeof value === 'boolean')
@@ -405,18 +207,10 @@ function exitCodeOf(data) {
     const code = isPlainObject(data) ? data['exitCode'] : undefined;
     return isExitCode(code) ? code : ExitCode.OK;
 }
-function isJsonFlag(arg) {
-    return arg === '--json' || arg.startsWith('--json=');
-}
-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;
-}
+const readsLazily = (arg) => arg.startsWith('--json=') || arg === '--format=agent';
 async function dispatch(manifest, { node, rest: typed, name }, io) {
-    const select = typed.some((a) => a.startsWith('--json=')) ? await import('./fields.js') : undefined;
-    const { args: rest, fields } = select?.jsonFields(typed) ?? { args: typed };
+    const select = typed.some(readsLazily) ? await import('./fields.js') : undefined;
+    const { args: rest, fields, lines } = select?.jsonFields(typed, node) ?? { args: typed };
     if (fields?.length === 0)
         return { json: true, text: `${JSON.stringify(select?.listFields(node))}\n` };
     if (fields !== undefined)
@@ -424,17 +218,17 @@ async function dispatch(manifest, { node, rest: typed, name }, io) {
     const parsed = parseArgs({ args: rest, options: toParseConfig(node.options, manifest.config !== undefined), allowPositionals: true, strict: true, tokens: true });
     const flags = canonical(parsed.values, node.options, parsed.tokens);
     const json = flags.json === true;
-    if (flags.help === true && json)
-        return { json, text: `${await machineJson(await helpDocumentOf(manifest, node), json ? ['--json'] : [])}\n` };
     if (flags.help === true)
-        return { json, text: await renderHelp(manifest, node, io) };
+        return { json, text: await (await import('./surfaces.js')).helpFor(manifest, node, io, json) };
     if (flags.version === true)
-        return { json, text: `${versionOf(manifest, io)}\n` };
+        return { json, text: `${(await import('./surfaces.js')).versionOf(manifest, io)}\n` };
     const resolved = await resolveValues(manifest, node.options, flags, io);
     if (resolved.explainText !== undefined)
         return { json, text: resolved.explainText };
     const { provenance } = resolved;
-    checkRelations(relationsOf(node), resolved.values, provenance);
+    const relations = relationsOf(node);
+    if (relations.length > 0)
+        (await import('./relations.js')).checkRelations(relations, resolved.values, provenance);
     const values = await coerce(node.options, resolved.values);
     const { positionals, passthrough } = splitPositionals(parsed.tokens);
     requirePositionals(node, positionals);
@@ -447,7 +241,7 @@ async function dispatch(manifest, { node, rest: typed, name }, io) {
     await manifest.fire('postRun', name, values);
     const changed = changedOf(node, data);
     const selected = fields === undefined || select === undefined ? data : select.selectFields(data, fields);
-    return { json, data: selected, provenance, ...(changed === undefined ? {} : { changed }) };
+    return { json, lines, data: selected, provenance, ...(changed === undefined ? {} : { changed }) };
 }
 function requirePositionals(node, positionals) {
     const required = (node.arguments ?? []).filter((a) => a.required !== false && a.variadic !== true);
@@ -475,29 +269,16 @@ async function emit(io, outcome) {
     }
     const meta = { provenance: outcome.provenance ?? {}, ...(outcome.changed === undefined ? {} : { changed: outcome.changed }) };
     const envelope = { ok: true, data: outcome.data, meta };
-    io.out.write(outcome.json ? `${JSON.stringify(envelope)}\n` : `${render(outcome.data)}\n`);
+    io.out.write(outcome.json ? `${JSON.stringify(envelope)}\n` : (outcome.lines?.(outcome.data) ?? `${render(outcome.data)}\n`));
     return await leave(io, exitCodeOf(outcome.data));
 }
 async function report(cause, { manifest, io, argv, json, name }) {
-    const failure = await describeFailure(cause, argv, resolveCommand(manifest, argv) ?? undefined);
+    const { describeFailure, failureText } = await import('./failure.js');
+    const failure = await describeFailure(cause, argv, resolveCommand(manifest, argv) ?? undefined, cause instanceof ActionRequired ? cause.spec : undefined);
     if (failure.silent === true)
         return await leave(io, failure.code);
     await manifest.fire('onError', name, {});
-    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 } };
-        if (json)
-            io.out.write(`${JSON.stringify(body)}\n`);
-        else
-            io.err.write(textFailure(rendered));
-        return await leave(io, failure.code);
-    }
-    const body = { code: failure.code, message: failure.message, hint: failure.hint, ...(failure.fix === undefined ? {} : { fix: failure.fix }) };
-    if (json)
-        io.out.write(`${JSON.stringify({ ok: false, error: body })}\n`);
-    else
-        io.err.write(textFailure(failure));
+    (json ? io.out : io.err).write(failureText(failure, manifest, json));
     return await leave(io, failure.code);
 }
 function ioOf(opts) {
@@ -528,11 +309,11 @@ export async function execute(manifest, opts = {}) {
     try {
         argv = manifest.declares('parse') ? await manifest.parse([...typed]) : typed;
         json = beforeTerminator(argv).some(isJsonFlag);
-        if (await surface(manifest, argv, io))
+        if (mayServe(argv) && (await (await import('./surfaces.js')).serve(manifest, argv, io, { resolution: (specs, flags) => resolution(manifest, specs, flags, io), execute })))
             return await leave(io, ExitCode.OK);
         const { node, rest } = manifest.resolve(argv, root);
         if (node?.run === undefined) {
-            const { text, code } = await unresolved({ manifest, root, io }, argv, node);
+            const { text, code } = await (await import('./surfaces.js')).unresolved({ manifest, root, io }, argv, node);
             (code === ExitCode.OK ? io.out : io.err).write(text);
             return await leave(io, code);
         }
@@ -569,3 +350,4 @@ export async function run(target, opts = {}) {
     });
     return await execute(manifest, opts);
 }
+export { beforeTerminator } from './argv.js';

package/dist/failure.d.ts

@@ -0,0 +1,26 @@
+import { type ExitCode as ExitCodeType } from './exit-code.js';
+import { type ActionRequiredSpec, type CommandNode, type Manifest } from './manifest.js';
+export interface Failure {
+    code: ExitCodeType;
+    message: string;
+    hint?: string;
+    /** E3 — the exact command or flag to run next, where one exists. Never a guess. */
+    fix?: string;
+    /** An exit signal: honour the code, print nothing. */
+    silent?: boolean;
+    /** N11: the caller must act; carried into the envelope with the runnable `next[]`. */
+    action?: ActionRequiredSpec;
+}
+/**
+ * E2/E3 — a usage error never prints a stack, a runtime failure never prints help.
+ *
+ * `action` is the spec of a `ctx.actionRequired(…)` unwind, which the engine recognises by its
+ * own class and hands over; the class stays in `execute.ts` because a handler throws it on the
+ * startup path.
+ */
+export declare function describeFailure(cause: unknown, argv: string[], node: CommandNode | undefined, action: ActionRequiredSpec | undefined): Promise<Failure>;
+/**
+ * What a described failure prints: under `--json` the envelope, for stdout; otherwise the prose,
+ * for stderr. The caller picks the stream by the same `json` it passes here (O1, D-140).
+ */
+export declare function failureText(failure: Failure, manifest: Manifest, json: boolean): string;