burgee 0.11.1 → 0.12.0

package/dist/completions.js

@@ -48,13 +48,18 @@ const flags = (name, spec) => {
     return spec.negatable === true ? [...spellings, `--no-${kebab(name)}`] : spellings;
 };
 const takesValue = (spec) => spec.type !== 'boolean';
+const callback = (program, node, name, partial) => [program, '__complete', ...node.path, `--${kebab(name)}`, partial].join(' ');
+const isDynamic = (spec) => spec.complete !== undefined;
+const promise = (program, root) => walk(root).some((n) => Object.values(n.options).some(isDynamic)) ? `runs ${program} on TAB only for options that declare a completer` : `never runs ${program} on TAB`;
 const fname = (program, path) => `_${[program, ...path].join('_').replaceAll(/[^A-Za-z0-9_]/g, '_')}`;
 function bashCase(program, node) {
     const opts = Object.entries(node.options).flatMap(([n, s]) => flags(n, s));
     const subs = node.children.map((c) => c.path[c.path.length - 1] ?? '');
     const valued = Object.entries(node.options)
         .filter(([, s]) => takesValue(s))
-        .map(([n, s]) => `      ${flags(n, s).join('|')}) COMPREPLY=($(compgen -W ${sq((s.choices ?? []).join(' '))} -- "$cur")); return ;;`)
+        .map(([n, s]) => isDynamic(s)
+        ? `      ${flags(n, s).join('|')}) COMPREPLY=($(compgen -W "$(${callback(program, node, n, '"$cur"')} 2>/dev/null)" -- "$cur")); return ;;`
+        : `      ${flags(n, s).join('|')}) COMPREPLY=($(compgen -W ${sq((s.choices ?? []).join(' '))} -- "$cur")); return ;;`)
         .join('\n');
     return `  ${fname(program, node.path)}() {
     case "$prev" in
@@ -70,7 +75,7 @@ function bash(program, root) {
         .filter((n) => n.path.length > 0)
         .map((n) => `      ${sq(n.path.join(' '))}) ${fname(program, n.path)}; return ;;`)
         .join('\n');
-    return `# ${program} completion for bash, generated by burgee — never runs ${program} on TAB.
+    return `# ${program} completion for bash, generated by burgee — ${promise(program, root)}.
 # Install: ${program} completion bash > ~/.local/share/bash-completion/completions/${program}
 _${program}_main() {
   local cur prev words cword
@@ -95,16 +100,17 @@ ${dispatch}
 complete -F _${program}_main ${program}
 `;
 }
-function zshOptionSpec(name, spec) {
+function zshOptionSpec(program, node, name, spec) {
     const desc = (spec.description ?? '').replaceAll(/[[\]:]/g, ' ');
-    const action = spec.choices === undefined ? ' ' : `(${spec.choices.join(' ')})`;
+    const listed = spec.choices === undefined ? ' ' : `(${spec.choices.join(' ')})`;
+    const action = isDynamic(spec) ? `{compadd -- \${(f)"$(${callback(program, node, name, '"$PREFIX"')} 2>/dev/null)"}}` : listed;
     const value = takesValue(spec) ? `:${name}:${action}` : '';
     return flags(name, spec)
         .map((f) => sq(`${f}[${desc}]${value}`))
         .join(' ');
 }
 function zshFunction(program, node) {
-    const options = Object.entries(node.options).map(([n, s]) => zshOptionSpec(n, s));
+    const options = Object.entries(node.options).map(([n, s]) => zshOptionSpec(program, node, n, s));
     if (node.children.length === 0) {
         return `${fname(program, node.path)}() {\n  _arguments -s ${options.join(' ')} '*: :_files'\n}`;
     }
@@ -124,7 +130,7 @@ ${dispatch}
 }
 function zsh(program, root) {
     return `#compdef ${program}
-# ${program} completion for zsh, generated by burgee — never runs ${program} on TAB.
+# ${program} completion for zsh, generated by burgee — ${promise(program, root)}.
 # Install: ${program} completion zsh > "\${fpath[1]}/_${program}" && compinit
 ${walk(root).map((n) => zshFunction(program, n)).join('\n')}
 if [[ $zsh_eval_context[-1] == loadautofunc ]]; then ${fname(program, [])} "$@"; else compdef ${fname(program, [])} ${program}; fi
@@ -135,9 +141,10 @@ function fishCondition(node) {
         return '__fish_use_subcommand';
     return node.path.map((seg) => `__fish_seen_subcommand_from ${seg}`).join('; and ');
 }
-function fishOption(program, cond, name, spec) {
+function fishOption({ program, cond, node }, name, spec) {
     const short = spec.short === undefined ? '' : ` -s ${spec.short}`;
-    const choices = spec.choices === undefined ? '' : ` -f -a ${sq(spec.choices.join(' '))}`;
+    const listed = spec.choices === undefined ? '' : ` -f -a ${sq(spec.choices.join(' '))}`;
+    const choices = isDynamic(spec) && node !== undefined ? ` -f -a ${sq(`(${callback(program, node, name, '(commandline -ct)')} 2>/dev/null)`)}` : listed;
     const value = takesValue(spec) ? ` -r${choices}` : '';
     return `complete -c ${program} -n ${cond}${short} -l ${name}${value} -d ${sq(spec.description ?? '')}`;
 }
@@ -148,14 +155,14 @@ function fish(program, root) {
         for (const c of node.children)
             lines.push(`complete -c ${program} -n ${cond} -f -a ${c.path[c.path.length - 1] ?? ''} -d ${sq(c.description)}`);
         for (const [name, spec] of Object.entries(node.options)) {
-            lines.push(fishOption(program, cond, kebab(name), spec));
+            lines.push(fishOption({ program, cond, node }, kebab(name), spec));
             if (spec.negatable === true) {
                 const { short: _short, ...unshort } = spec;
-                lines.push(fishOption(program, cond, `no-${kebab(name)}`, unshort));
+                lines.push(fishOption({ program, cond }, `no-${kebab(name)}`, unshort));
             }
         }
     }
-    return `# ${program} completion for fish, generated by burgee — never runs ${program} on TAB.
+    return `# ${program} completion for fish, generated by burgee — ${promise(program, root)}.
 # Install: ${program} completion fish > ~/.config/fish/completions/${program}.fish
 ${lines.join('\n')}
 `;
@@ -166,10 +173,14 @@ function pwshEntry(node) {
     const values = Object.entries(node.options)
         .filter(([, s]) => s.choices !== undefined)
         .map(([n, s]) => `'--${n}' = @(${(s.choices ?? []).map((c) => `'${c}'`).join(', ')})`);
-    return `    '${node.path.join(' ')}' = @{ Items = @(${[...subs, ...opts].join(', ')}); Values = @{ ${values.join('; ')} } }`;
+    const dynamic = Object.entries(node.options)
+        .filter(([, s]) => isDynamic(s))
+        .map(([n]) => `'--${kebab(n)}' = $true`);
+    const callbacks = dynamic.length === 0 ? '' : `; Dynamic = @{ ${dynamic.join('; ')} }`;
+    return `    '${node.path.join(' ')}' = @{ Items = @(${[...subs, ...opts].join(', ')}); Values = @{ ${values.join('; ')} }${callbacks} }`;
 }
 function pwsh(program, root) {
-    return `# ${program} completion for PowerShell, generated by burgee — never runs ${program} on TAB.
+    return `# ${program} completion for PowerShell, generated by burgee — ${promise(program, root)}.
 # Install: ${program} completion pwsh > ${program}-completion.ps1, then dot-source it from $PROFILE
 Register-ArgumentCompleter -Native -CommandName '${program}' -ScriptBlock {
   param($wordToComplete, $commandAst, $cursorPosition)
@@ -186,7 +197,14 @@ ${walk(root).map(pwshEntry).join('\n')}
   }
   $entry = $table[$path]
   $prev = if ($words.Count -gt 0) { $words[$words.Count - 1] } else { '' }
-  if ($entry.Values.ContainsKey($prev)) {
+${walk(root).some((n) => Object.values(n.options).some(isDynamic))
+        ? `  if ($entry.Dynamic -and $entry.Dynamic.ContainsKey($prev)) {
+    $steps = @($path -split ' ' | Where-Object { $_ -ne '' })
+    & '${program}' __complete @steps $prev $wordToComplete 2>$null | ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) }
+    return
+  }
+`
+        : ''}  if ($entry.Values.ContainsKey($prev)) {
     $entry.Values[$prev] | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) }
     return
   }

package/dist/config-explain.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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.
+ */
+/**
+ * V8 / D-117 — `config explain [command…]`: the precedence, and every option's value with the
+ * source that won, **generated from the resolver** rather than written in a README. Ten of ten
+ * surveyed CLIs read config and env; three of ten document the order. This one prints it,
+ * from `seniority`'s own `ORDER`, so the table cannot disagree with what a run does.
+ *
+ * It resolves without the command line's own flags — it explains the configuration, not one
+ * invocation — except `--config <path>` and `--no-config`, which choose what is read. With
+ * `--json` it answers as data.
+ *
+ * Imported by `execute.ts` only for `config explain` (M2).
+ */
+import { type Resolution } from 'seniority/precedence';
+import { type Manifest, type OptionSpec } from './manifest.js';
+type Resolve = (specs: Record<string, OptionSpec>, flags: Record<string, unknown>) => Promise<Resolution>;
+export declare function explainConfig(manifest: Manifest, argv: readonly string[], resolve: Resolve): Promise<string>;
+export {};

package/dist/config-explain.js

@@ -0,0 +1,33 @@
+import { ORDER } from 'seniority/precedence';
+import { kebab } from './names.js';
+const label = (source) => (source === 'package' ? 'package.json' : source);
+function where(p) {
+    if (p?.location === undefined)
+        return '';
+    return p.line === undefined ? p.location : `${p.location}:${String(p.line)}`;
+}
+function shown(value) {
+    if (value === undefined)
+        return '—';
+    return typeof value === 'string' ? value : JSON.stringify(value);
+}
+export async function explainConfig(manifest, argv, resolve) {
+    const json = argv.includes('--json');
+    const at = argv.indexOf('--config');
+    const flags = { ...(at === -1 ? {} : { config: argv[at + 1] }), ...(argv.includes('--no-config') ? { noConfig: true } : {}) };
+    const path = argv.filter((a, i) => !a.startsWith('--') && (at === -1 || i !== at + 1));
+    const { node } = manifest.resolve([...path], manifest.rootPath);
+    const specs = node?.options ?? {};
+    const resolved = await resolve(specs, flags);
+    const rows = Object.keys(specs).map((name) => {
+        const p = resolved.provenance[name];
+        const location = where(p);
+        return { option: `--${kebab(name)}`, value: resolved.values[name], source: p === undefined ? 'unset' : label(p.source), ...(location === '' ? {} : { location }) };
+    });
+    const precedence = ORDER.map(label);
+    if (json)
+        return `${JSON.stringify({ ok: true, data: { precedence, options: rows }, meta: {} })}\n`;
+    const width = Math.max(0, ...rows.map((r) => r.option.length));
+    const lines = rows.map((r) => `  ${r.option.padEnd(width)}  ${shown(r.value)}  (${r.source}${r.location === undefined ? '' : ` ${r.location}`})`);
+    return `precedence: ${precedence.join(' > ')} — the first that sets a value wins\n${lines.length === 0 ? '  (this command takes no options)' : lines.join('\n')}\n`;
+}

package/dist/define-error.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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.
+ */
+/** What an author declares. */
+export interface ErrorDefinition {
+    /** The class name, shown as the error's `name`. */
+    name: string;
+    /** The exit code, 7–125, owned by this class alone. */
+    code: number;
+}
+/** What `new` takes: the message, and optionally the E3 `hint` and exact `fix`. */
+export interface DefinedErrorOptions {
+    hint?: string;
+    fix?: string;
+}
+/** An author-defined error class; `exitCode` is the code it leaves with. */
+export interface DefinedErrorClass {
+    new (message: string, options?: DefinedErrorOptions): Error & DefinedErrorOptions;
+    readonly exitCode: number;
+}
+/**
+ * Where the engine reads the code: a registered symbol on the class, so `execute.ts` finds it
+ * without importing this module — only a program that defines an error pays for defining one.
+ * A subclass inherits it the way statics are inherited.
+ */
+export declare const EXIT_CODE: unique symbol;
+export declare function defineError(definition: ErrorDefinition): DefinedErrorClass;

package/dist/define-error.js

@@ -0,0 +1,29 @@
+const MIN = 7;
+const MAX = 125;
+export const EXIT_CODE = Symbol.for('burgee.exitCode');
+const owners = new Map();
+export function defineError(definition) {
+    const { name, code } = definition;
+    if (!Number.isInteger(code) || code < MIN || code > MAX) {
+        throw new RangeError(`burgee: defineError "${name}" claims exit code ${String(code)}; use an integer from ${String(MIN)} to ${String(MAX)} — 0–6 and 130 are the contract's own`);
+    }
+    const owner = owners.get(code);
+    if (owner !== undefined)
+        throw new Error(`burgee: defineError "${name}" claims exit code ${String(code)}, which "${owner}" already owns; one code, one class (E7)`);
+    owners.set(code, name);
+    const Defined = class extends Error {
+        static exitCode = code;
+        static [EXIT_CODE] = code;
+        hint;
+        fix;
+        constructor(message, options = {}) {
+            super(message);
+            this.name = name;
+            if (options.hint !== undefined)
+                this.hint = options.hint;
+            if (options.fix !== undefined)
+                this.fix = options.fix;
+        }
+    };
+    return Defined;
+}

package/dist/errors.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The error classes an author throws to name an exit code (E6, E7).
+ *
+ * Their own module, and a small one, so the commander and yargs façades can recognise an
+ * `AuthError` without reaching `validate.ts` and the whole run-time validator behind it. Before
+ * they could, both filed every handler failure as `runtime`, exit 1, and an `AuthError` thrown
+ * from a commander-syntax action told the caller *read the message* where E6 promises *log in
+ * and run it again* (D-140). `validate.ts` re-exports both, so no import path changed.
+ */
+/** A usage problem the caller can fix, carrying the flag that fixes it (E3). */
+export declare class UsageError extends Error {
+    readonly hint?: string | undefined;
+    constructor(message: string, hint?: string | undefined);
+}
+/**
+ * E6 — the far side said no. Throw this and the run leaves with `ExitCode.AUTH`.
+ *
+ * The one error class whose *response* is unambiguous: not "read the message and decide" but
+ * "get a credential and run it again". A handler that throws a bare `Error` for a 401 gets
+ * `RUNTIME`, which is the code for everything, and a caller retrying on it retries forever.
+ *
+ * `fix` is the exact command that gets the credential, where the program knows it — `hint` is
+ * prose a person reads and `fix` is a line a caller runs, which is the turn the field saves.
+ */
+export declare class AuthError extends Error {
+    readonly hint?: string | undefined;
+    readonly fix?: string | undefined;
+    constructor(message: string, hint?: string | undefined, fix?: string | undefined);
+}

package/dist/errors.js

@@ -0,0 +1,17 @@
+export class UsageError extends Error {
+    hint;
+    constructor(message, hint) {
+        super(message);
+        this.hint = hint;
+    }
+}
+export class AuthError extends Error {
+    hint;
+    fix;
+    constructor(message, hint, fix) {
+        super(message);
+        this.hint = hint;
+        this.fix = fix;
+        this.name = 'AuthError';
+    }
+}

package/dist/execute.d.ts

@@ -47,6 +47,12 @@ export interface Command<S extends OptionSpecs = OptionSpecs> {
     effects?: DeclaredEffects;
     /** Relationships between options, validated before choices and the handler (S2, S6). */
     relations?: readonly Relation[];
+    /**
+     * The top-level fields of this command's result (N14). With them, `--json=` lists them
+     * without running the handler and `--json=a,b` refuses an unknown field before it runs.
+     * Without them `--json=a,b` still selects, checked against the result's own keys.
+     */
+    fields?: readonly string[];
     /** Absent on a group that only holds subcommands. `NoInfer`: the spec fixes S, the handler only reads it. */
     run?: (ctx: CommandContext<InferOptions<NoInfer<S>>>) => unknown;
     /** The handler's module, imported on dispatch only (M2); everything else about the command is declared here. */

package/dist/execute.js

@@ -32,6 +32,8 @@ function helpFields(c) {
         node.effects = c.effects;
     if (c.relations !== undefined)
         node.relations = c.relations;
+    if (c.fields !== undefined)
+        node.fields = c.fields;
     return node;
 }
 export function defineCommand(command) {
@@ -169,17 +171,20 @@ async function configLayers(name, values, io) {
         out.pkg = pkg;
     return out;
 }
-async function resolveValues(manifest, specs, values, io) {
+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));
-    const resolution = resolveLayers(specs, layers);
-    const out = { values: resolution.values, provenance: resolution.provenance };
+    return resolveLayers(specs, layers);
+}
+async function resolveValues(manifest, specs, values, io) {
+    const resolved = await resolution(manifest, specs, values, io);
+    const out = { values: resolved.values, provenance: resolved.provenance };
     const asked = values['explain'];
     if (typeof asked === 'string')
-        out.explainText = (await import('seniority/explain')).explain(asked, resolution);
+        out.explainText = (await import('seniority/explain')).explain(asked, resolved);
     for (const [name, spec] of Object.entries(specs)) {
         if (out.values[name] === undefined && spec.required === true && out.explainText === undefined) {
             throw new UsageError(`missing required option --${kebab(name)}`, `pass --${kebab(name)} <value>`);
@@ -216,6 +221,21 @@ const CLASSIFIED = [
     [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 {
@@ -227,12 +247,18 @@ async function describeFailure(cause, argv, node) {
     const signal = exitSignal(cause);
     if (signal !== undefined)
         return { code: signal, message: '', silent: true };
-    const message = cause instanceof Error ? cause.message : String(cause);
+    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);
@@ -292,7 +318,7 @@ async function unresolved({ manifest, root, io }, argv, at) {
     const typed = argv.slice(node.path.length - root.length);
     const first = typed[0] ?? '';
     if (typed.length > 0 && HELP_FLAGS.has(first)) {
-        if (beforeTerminator(typed).includes('--json'))
+        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 };
     }
@@ -319,6 +345,16 @@ async function completion(manifest, argv, io) {
 }
 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') {
@@ -369,13 +405,22 @@ 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;
 }
-async function dispatch(manifest, { node, rest, name }, io) {
+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 };
+    if (fields?.length === 0)
+        return { json: true, text: `${JSON.stringify(select?.listFields(node))}\n` };
+    if (fields !== undefined)
+        select?.checkFields(fields, node);
     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;
@@ -397,10 +442,12 @@ async function dispatch(manifest, { node, rest, name }, io) {
     await manifest.fire('preRun', name, values);
     const detection = detectAgent(io.env, io.tty);
     const onExit = (handler, label) => io.teardown.add(handler, label);
-    const data = await node.run({ options: values, positionals, passthrough, env: io.env, exit: ctxExit, onExit, actionRequired, ...detection });
+    const stdin = positionals.includes('-') ? (await import('./stdin-dash.js')).stdinFor(node, positionals, io.stdin) : {};
+    const data = await node.run({ options: values, positionals, passthrough, ...stdin, env: io.env, exit: ctxExit, onExit, actionRequired, ...detection });
     await manifest.fire('postRun', name, values);
     const changed = changedOf(node, data);
-    return { json, data, provenance, ...(changed === undefined ? {} : { changed }) };
+    const selected = fields === undefined || select === undefined ? data : select.selectFields(data, fields);
+    return { json, data: selected, provenance, ...(changed === undefined ? {} : { changed }) };
 }
 function requirePositionals(node, positionals) {
     const required = (node.arguments ?? []).filter((a) => a.required !== false && a.variadic !== true);
@@ -440,11 +487,17 @@ async function report(cause, { manifest, io, argv, json, name }) {
         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 } };
-        io.err.write(json ? `${JSON.stringify(body)}\n` : textFailure(rendered));
+        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 }) };
-    io.err.write(json ? `${JSON.stringify({ ok: false, error: body })}\n` : textFailure(failure));
+    if (json)
+        io.out.write(`${JSON.stringify({ ok: false, error: body })}\n`);
+    else
+        io.err.write(textFailure(failure));
     return await leave(io, failure.code);
 }
 function ioOf(opts) {
@@ -465,11 +518,16 @@ function ioOf(opts) {
 export async function execute(manifest, opts = {}) {
     const io = ioOf(opts);
     const raw = opts.argv ?? host.argv;
-    const argv = opts.argv === undefined || opts.from === 'node' ? raw.slice(2) : raw;
+    const typed = opts.argv === undefined || opts.from === 'node' ? raw.slice(2) : raw;
     const root = opts.root ?? manifest.rootPath;
-    let json = beforeTerminator(argv).includes('--json');
+    let json = beforeTerminator(typed).some(isJsonFlag);
     let name = '';
+    if (manifest.declares('shutdown'))
+        io.teardown.add(async () => await manifest.fire('shutdown', name, {}), 'plugin shutdown hooks');
+    let argv = typed;
     try {
+        argv = manifest.declares('parse') ? await manifest.parse([...typed]) : typed;
+        json = beforeTerminator(argv).some(isJsonFlag);
         if (await surface(manifest, argv, io))
             return await leave(io, ExitCode.OK);
         const { node, rest } = manifest.resolve(argv, root);

package/dist/facade-failure.d.ts

@@ -0,0 +1,17 @@
+import { ExitCode } from './exit-code.js';
+/** A handler's failure as a façade reports it: the E1 code, the envelope's word for it, and the E3 fields. */
+export interface HandlerFailure {
+    exit: ExitCode;
+    error: {
+        code: 'usage' | 'auth' | 'runtime';
+        message: string;
+        hint?: string;
+        fix?: string;
+    };
+}
+/**
+ * Anything a handler threw or rejected with — an `Error`, a subclass that names its code, or a
+ * value that is not an Error at all — as one failure. Never a stack: the envelope is for a
+ * caller that branches on `code`, and the prose line carries the message.
+ */
+export declare function handlerFailure(cause: unknown): HandlerFailure;

package/dist/facade-failure.js

@@ -0,0 +1,12 @@
+import { AuthError, UsageError } from './errors.js';
+import { ExitCode } from './exit-code.js';
+const CLASSES = [
+    [AuthError, [ExitCode.AUTH, 'auth']],
+    [UsageError, [ExitCode.USAGE, 'usage']],
+];
+export function handlerFailure(cause) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    const [exit, code] = CLASSES.find(([Class]) => cause instanceof Class)?.[1] ?? [ExitCode.RUNTIME, 'runtime'];
+    const { hint, fix } = (cause ?? {});
+    return { exit, error: { code, message, ...(typeof hint === 'string' ? { hint } : {}), ...(typeof fix === 'string' ? { fix } : {}) } };
+}

package/dist/fields.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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.
+ */
+/**
+ * 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): {
+    ok: true;
+    data: {
+        fields: readonly string[];
+    };
+    meta: Record<string, never>;
+};
+/** An unknown field is refused with the valid set named — before the handler when they are declared. */
+export declare function checkFields(fields: readonly string[], node: CommandNode): void;
+/** The named fields of a result: of the object, or of each object in a list. */
+export declare function selectFields(data: unknown, fields: readonly string[]): unknown;
+/**
+ * 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).
+ */
+export declare function jsonFields(args: readonly string[]): {
+    args: string[];
+    fields?: string[];
+};

package/dist/fields.js

@@ -0,0 +1,45 @@
+import { UsageError } from './validate.js';
+const isPlainObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+function declared(node) {
+    const { fields } = node;
+    if (fields === undefined)
+        return undefined;
+    if (fields.every((f) => f !== '' && !f.includes(',')) && new Set(fields).size === fields.length)
+        return fields;
+    throw new Error(`burgee: command "${node.path.slice(1).join(' ')}" declares fields ${JSON.stringify(fields)}; declare distinct, non-empty names without commas`);
+}
+export function listFields(node) {
+    const fields = declared(node);
+    if (fields === undefined) {
+        const typed = node.path.slice(1).join(' ');
+        throw new UsageError(`"${typed}" declares no fields to list`, `run "${typed} --json" to see its whole result`);
+    }
+    return { ok: true, data: { fields }, meta: {} };
+}
+export function checkFields(fields, node) {
+    const valid = declared(node);
+    if (valid !== undefined)
+        refuseUnknown(fields, valid);
+}
+function refuseUnknown(fields, valid) {
+    const unknown = fields.filter((f) => !valid.includes(f));
+    if (unknown.length > 0)
+        throw new UsageError(`unknown field${unknown.length === 1 ? '' : 's'} ${unknown.map((f) => `"${f}"`).join(', ')}`, `valid fields: ${valid.join(', ')}`);
+}
+export function selectFields(data, fields) {
+    const list = Array.isArray(data) ? data : [data];
+    const rows = list.filter(isPlainObject);
+    refuseUnknown(fields, [...new Set(rows.flatMap((row) => Object.keys(row)))]);
+    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 end = args.indexOf('--');
+    const head = end === -1 ? args : args.slice(0, end);
+    const given = head.findLast((a) => a.startsWith('--json='));
+    if (given === undefined)
+        return { args: [...args] };
+    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 };
+}

package/dist/index.d.ts

@@ -28,6 +28,7 @@
  * **Every `type` stays.** A type re-export is erased and costs a consumer nothing, so the
  * whole type surface is still importable from `burgee` and no typed program has to move.
  */
+export { defineError, type DefinedErrorClass, type DefinedErrorOptions, type ErrorDefinition } from './define-error.js';
 export { ExitCode, isExitCode, type ExitCode as ExitCodeValue } from './exit-code.js';
 export { defineCommand, defineProgram, execute, resolveCommand, run, runCommand, sharedOptions, type AnyCommand, type Command, type CommandContext, type InferOptions, type OptionSpecs, type Program, type RunOptions, type RunResult, } from './execute.js';
 export { checkCommand, checkDefinition } from './definition.js';

package/dist/index.js

@@ -1,3 +1,4 @@
+export { defineError } from './define-error.js';
 export { ExitCode, isExitCode } from './exit-code.js';
 export { defineCommand, defineProgram, execute, resolveCommand, run, runCommand, sharedOptions, } from './execute.js';
 export { checkCommand, checkDefinition } from './definition.js';