burgee 0.7.1 → 0.9.0

package/dist/commander/error.js

@@ -1,4 +1,3 @@
-/** commander's error classes, byte-for-byte in shape: `code`, `exitCode`, `nestedError`. */
 export class CommanderError extends Error {
     code;
     exitCode;
@@ -19,4 +18,3 @@ export class InvalidArgumentError extends CommanderError {
         this.name = this.constructor.name;
     }
 }
-//# sourceMappingURL=error.js.map

package/dist/commander/help.js

@@ -1,13 +1,11 @@
 import { stripVTControlCharacters } from 'node:util';
 import { humanReadableArgName } from './argument.js';
-/** Methods are static in style so a subclass, or plain functions via `configureHelp`, can override them. */
 export class Help {
     helpWidth = undefined;
     minWidthToWrap = 40;
     sortSubcommands = false;
     sortOptions = false;
     showGlobalOptions = false;
-    /** Called after `configureHelp` overrides are applied and just before `formatHelp`. */
     prepareContext(contextOptions) {
         this.helpWidth = this.helpWidth ?? contextOptions.helpWidth ?? 80;
     }
@@ -28,7 +26,6 @@ export class Help {
         const visibleOptions = cmd.options.filter((option) => !option.hidden);
         const helpOption = cmd._getHelpOption();
         if (helpOption && !helpOption.hidden) {
-            // Historical: hide the built-in help flags a user option already took.
             const removeShort = helpOption.short && cmd._findOption(helpOption.short);
             const removeLong = helpOption.long && cmd._findOption(helpOption.long);
             if (!removeShort && !removeLong)
@@ -54,7 +51,6 @@ export class Help {
         return globalOptions;
     }
     visibleArguments(cmd) {
-        // Side effect: apply the legacy descriptions before the arguments are displayed.
         if (cmd._argsDescription) {
             for (const argument of cmd.registeredArguments) {
                 argument.description = argument.description || cmd._argsDescription[argument.name()] || '';
@@ -110,7 +106,6 @@ export class Help {
     commandDescription(cmd) {
         return cmd.description();
     }
-    /** Summary, falling back to description for backwards compatibility. */
     subcommandDescription(cmd) {
         return cmd.summary() || cmd.description();
     }
@@ -120,7 +115,6 @@ export class Help {
             extraInfo.push(`choices: ${option.argChoices.map((choice) => JSON.stringify(choice)).join(', ')}`);
         }
         if (option.defaultValue !== undefined) {
-            // Defaults for boolean and negated are more for the programmer than the end user.
             const showDefault = option.required || option.optional || (option.isBoolean() && typeof option.defaultValue === 'boolean');
             if (showDefault)
                 extraInfo.push(`default: ${option.defaultValueDescription || JSON.stringify(option.defaultValue)}`);
@@ -154,7 +148,6 @@ export class Help {
             return [];
         return [helper.styleTitle(heading), ...items, ''];
     }
-    /** Groups in order of first appearance among all items; members in order of the visible items. */
     groupItems(unsortedItems, visibleItems, getGroup) {
         const result = new Map();
         for (const item of unsortedItems) {
@@ -203,7 +196,6 @@ export class Help {
         }
         return output.join('\n');
     }
-    /** Width ignoring ANSI escapes, for padding and wrapping. */
     displayWidth(str) {
         return stripVTControlCharacters(str).length;
     }
@@ -211,7 +203,6 @@ export class Help {
         return str;
     }
     styleUsage(str) {
-        // Assume the default usage shape: command subcommand [options] [command] <foo> [bar]
         return str
             .split(' ')
             .map((word) => {
@@ -273,15 +264,9 @@ export class Help {
     padWidth(cmd, helper) {
         return Math.max(helper.longestOptionTermLength(cmd, helper), helper.longestGlobalOptionTermLength(cmd, helper), helper.longestSubcommandTermLength(cmd, helper), helper.longestArgumentTermLength(cmd, helper));
     }
-    /** Manually wrapped text: a line break followed by whitespace. */
     preformatted(str) {
         return /\n[^\S\r\n]/.test(str);
     }
-    /**
-     * Pad the term and wrap the description, indenting the following lines:
-     *   TTT  DDD DDDD
-     *        DD DDD
-     */
     formatItem(term, termWidth, description, helper) {
         const itemIndent = 2;
         const itemIndentStr = ' '.repeat(itemIndent);
@@ -301,7 +286,6 @@ export class Help {
         }
         return itemIndentStr + paddedTerm + ' '.repeat(spacerWidth) + formattedDescription.replace(/\n/g, `\n${itemIndentStr}`);
     }
-    /** Wrap at whitespace, preserving existing line breaks; skipped below `minWidthToWrap`. */
     boxWrap(str, width) {
         if (width < this.minWidthToWrap)
             return str;
@@ -333,4 +317,3 @@ export class Help {
         return wrappedLines.join('\n');
     }
 }
-//# sourceMappingURL=help.js.map

package/dist/commander/option.js

@@ -1,4 +1,3 @@
-import {} from './argument.js';
 import { InvalidArgumentError } from './error.js';
 export class Option {
     flags;
@@ -25,7 +24,6 @@ export class Option {
         this.description = description || '';
         this.required = flags.includes('<');
         this.optional = flags.includes('[');
-        // `<value,...>` describes custom splitting of one argument, not a variadic option.
         this.variadic = /\w\.\.\.[>\]]$/.test(flags);
         const { shortFlag, longFlag } = splitOptionFlags(flags);
         this.short = shortFlag;
@@ -38,7 +36,6 @@ export class Option {
         this.defaultValueDescription = description;
         return this;
     }
-    /** Value used when the option appears without an option-argument. `parseArg` still runs. */
     preset(arg) {
         this.presetArg = arg;
         return this;
@@ -47,7 +44,6 @@ export class Option {
         this.conflictsWith = this.conflictsWith.concat(names);
         return this;
     }
-    /** Values implied for other options when this one is set and they are not. `parseArg` does not run on them. */
     implies(impliedOptionValues) {
         const newImplied = typeof impliedOptionValues === 'string' ? { [impliedOptionValues]: true } : impliedOptionValues;
         this.implied = Object.assign(this.implied ?? {}, newImplied);
@@ -90,7 +86,6 @@ export class Option {
             return this.long.replace(/^--/, '');
         return (this.short ?? '').replace(/^-/, '');
     }
-    /** camelCase key used on the options object; `--no-foo` shares `foo` with `--foo`. */
     attributeName() {
         return camelcase(this.negate ? this.name().replace(/^no-/, '') : this.name());
     }
@@ -101,15 +96,10 @@ export class Option {
     is(arg) {
         return this.short === arg || this.long === arg;
     }
-    /** Options are one of boolean, negated, required-argument or optional-argument. */
     isBoolean() {
         return !this.required && !this.optional && !this.negate;
     }
 }
-/**
- * `--build` and `--no-build` share one value. This works out which of the pair a
- * value (probably) came from, so implied values are only applied for the right one.
- */
 export class DualOptions {
     positiveOptions = new Map();
     negativeOptions = new Map();
@@ -135,7 +125,6 @@ export class DualOptions {
 function camelcase(str) {
     return str.split('-').reduce((acc, word) => acc + (word[0] ?? '').toUpperCase() + word.slice(1));
 }
-/** Split `'-m,--mixed <value>'` into its short and long flags, failing noisily on anything else. */
 export function splitOptionFlags(flags) {
     let shortFlag;
     let longFlag;
@@ -147,10 +136,8 @@ export function splitOptionFlags(flags) {
         shortFlag = flagParts.shift();
     if (longFlagExp.test(head()))
         longFlag = flagParts.shift();
-    // Long then short. Rarely used but fine.
     if (!shortFlag && shortFlagExp.test(head()))
         shortFlag = flagParts.shift();
-    // Two long flags, like '--ws, --workspace': the supported way to have a shortish flag.
     if (!shortFlag && longFlagExp.test(head())) {
         shortFlag = longFlag;
         longFlag = flagParts.shift();
@@ -175,4 +162,3 @@ export function splitOptionFlags(flags) {
     }
     return { shortFlag, longFlag };
 }
-//# sourceMappingURL=option.js.map

package/dist/compat.d.ts

@@ -0,0 +1,30 @@
+/**
+ * A7 — the graded pass rate per host, as `burgee migrate` reports it.
+ *
+ * These are `compat-oracle`'s own numbers: the incumbent's test suite, vendored and run
+ * against burgee's front-end, which is what "drop-in" means here and the only claim in the
+ * package that is measured rather than argued.
+ *
+ * **They live here as a data module rather than as a literal in the report**, and
+ * `compat-baseline-lock.test.ts` holds this file equal to
+ * `packages/compat-oracle/baseline/<host>.json` — the same files the compat page renders.
+ * Changing a number here without the measurement moving fails that lock, which is the
+ * whole point: a number typed into a report template is a number that goes stale silently,
+ * and this repository has published four of those and caught them all late.
+ *
+ * It cannot be read from the oracle at run time. `compat-oracle` is `private: true` and is
+ * never published, so a user who installs `burgee` has no baseline directory to read; a
+ * copy with a lock on it is the strongest control available on the published side, and the
+ * lock is what makes it a copy rather than a claim.
+ */
+/** One row of the baseline, in the shape `baseline/<host>.json` stores it. */
+export interface Graded {
+    /** Cases in the incumbent's own suite. */
+    reference: number;
+    /** Cases that pass against burgee's front-end. */
+    passed: number;
+    /** `passed / reference`, carried rather than recomputed so it is the oracle's own division. */
+    rate: number;
+}
+/** The two hosts `migrate` rewrites, and nothing else — a row here without a mapping would claim a path that does not exist. */
+export declare const GRADED: Readonly<Record<string, Graded>>;

package/dist/compat.js

@@ -0,0 +1,4 @@
+export const GRADED = {
+    commander: { reference: 1360, passed: 1360, rate: 1 },
+    yargs: { reference: 804, passed: 804, rate: 1 },
+};

package/dist/config.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `burgee/config` — the configuration layer, by itself.
+ *
+ * Precedence, provenance and `--explain` come from `seniority`, the package whose job that
+ * is. They were re-exported from the root barrel until the barrel's cost was measured
+ * (see `index.ts`): 3,135 bundled bytes on the startup path of every program, for a
+ * surface a program only touches when it wants to read or explain its own configuration.
+ */
+export { ConfigError, envName, resolve, screaming, type Candidate, type Layers, type Provenance, type Resolution, type Source } from 'seniority/precedence';
+export { explain } from 'seniority/explain';

package/dist/config.js

@@ -0,0 +1,2 @@
+export { ConfigError, envName, resolve, screaming } from 'seniority/precedence';
+export { explain } from 'seniority/explain';

package/dist/definition.d.ts

@@ -26,11 +26,20 @@ import { type OptionSpec } from './manifest.js';
 export declare const WITHHELD = "withheld";
 /**
  * What must be true of a declaration before anything runs (yargs #1198, #887, #1679):
- * a known type, one short alias per command, no two keys that meet on the command line.
+ * a known type, one short alias per command, no two keys that meet on the command line, and
+ * none of V5's reserved surfaces.
+ *
+ * The reserved names used to be a second loop over the same keys in {@link checkCommand},
+ * and the numeric bound used to be a fourth branch in this one. Both moved to pay for the
+ * canonical-key check below without raising a weight ceiling — `./plugin` had 5 bytes of
+ * headroom — and both are better where they are now: `flag` is computed once here and
+ * `kebab` is the identity on every reserved name, and a numeric bound is a fact about a
+ * spec rather than about a name. The file is 51 bytes smaller than before the check existed.
  */
 export declare function checkDefinition(name: string, options: Record<string, OptionSpec>): void;
 /**
- * The whole door: the reserved names of V5, {@link checkDefinition}, and {@link checkEffects}.
+ * The whole door: {@link checkDefinition} — which carries V5's reserved names — and
+ * {@link checkEffects}.
  *
  * This exists as one function because it was two. `defineCommand` ran both; `Manifest.use()`
  * ran neither, so a plugin's command was admitted unread — and a plugin option named `json`
@@ -38,8 +47,17 @@ export declare function checkDefinition(name: string, options: Record<string, Op
  * second copy of the guard beside `use()`; it is that there is one guard and both callers
  * reach it, which is the only arrangement a reader can check by looking.
  *
- * `effects` and `runs` are required rather than optional for exactly that reason. An optional
- * third argument would be a check a caller can decline by writing nothing, which is the shape
- * of the defect `checkEffects` exists to remove, one level up.
+ * It takes the declaration whole, for exactly that reason. It took `effects` and `runs` as
+ * required arguments so a caller could not decline a check by writing nothing; D1 would have
+ * made that five, and a sixth field would make it six. Reading the object means a field the
+ * door checks is one no caller has to remember to forward — including whether it runs.
  */
-export declare function checkCommand(name: string, options: Record<string, OptionSpec>, effects: unknown, runs: boolean): void;
+export declare function checkCommand(name: string, declared: Declared): void;
+/** What the door reads of a command: a first-party declaration and a plugin's have the same fields. */
+export interface Declared {
+    options?: Record<string, OptionSpec>;
+    effects?: unknown;
+    deprecated?: boolean | string;
+    run?: unknown;
+    load?: unknown;
+}

package/dist/definition.js

@@ -1,10 +1,14 @@
-import { kebab } from './names.js';
+import { camel, kebab } from './names.js';
 const TYPES = new Set(['string', 'boolean', 'number']);
 const EFFECTS = ['read_only', 'idempotent', 'non_idempotent'];
 export const WITHHELD = 'withheld';
 const DECLARED = [...EFFECTS, WITHHELD];
 const RESERVED = new Set(['json', 'help', 'schema', 'mcp', 'version', 'explain']);
-function checkRelationNames(name, key, spec, options) {
+function checkSpec(name, key, spec, options) {
+    checkDeprecated(`option "${key}" of "${name}"`, spec.deprecated);
+    if ((spec.minimum !== undefined || spec.maximum !== undefined || spec.integer !== undefined) && spec.type !== 'number') {
+        throw new Error(`burgee: option "${key}" of "${name}" declares a numeric bound but is not a number`);
+    }
     for (const field of ['dependsOn', 'exclusive']) {
         for (const other of spec[field] ?? []) {
             if (other !== key && other in options)
@@ -27,14 +31,13 @@ export function checkDefinition(name, options) {
             shorts.set(spec.short, key);
         }
         const flag = kebab(key);
-        const clash = flags.get(flag);
+        if (RESERVED.has(flag))
+            throw new Error(`burgee: option "${key}" is reserved and cannot be redefined`);
+        const clash = flags.get(flag) ?? (camel(flag) === key ? undefined : camel(flag));
         if (clash !== undefined)
             throw new Error(`burgee: options "${clash}" and "${key}" of "${name}" are both --${flag}`);
         flags.set(flag, key);
-        if ((spec.minimum !== undefined || spec.maximum !== undefined || spec.integer !== undefined) && spec.type !== 'number') {
-            throw new Error(`burgee: option "${key}" of "${name}" declares a numeric bound but is not a number`);
-        }
-        checkRelationNames(name, key, spec, options);
+        checkSpec(name, key, spec, options);
     }
 }
 function checkEffects(name, effects, runs) {
@@ -47,11 +50,12 @@ function checkEffects(name, effects, runs) {
         throw new Error(`burgee: command "${name}" declares effects ${JSON.stringify(effects)}, which is not an effects; use ${DECLARED.join(', ')}`);
     }
 }
-export function checkCommand(name, options, effects, runs) {
-    for (const key of Object.keys(options)) {
-        if (RESERVED.has(key) || RESERVED.has(kebab(key)))
-            throw new Error(`burgee: option "${key}" is reserved and cannot be redefined`);
-    }
-    checkDefinition(name, options);
-    checkEffects(name, effects, runs);
+function checkDeprecated(what, deprecated) {
+    if (deprecated === true || deprecated === '')
+        throw new Error(`burgee: ${what} is deprecated with no replacement; name it, e.g. deprecated: '--force'`);
+}
+export function checkCommand(name, declared) {
+    checkDeprecated(`command "${name}"`, declared.deprecated);
+    checkDefinition(name, declared.options ?? {});
+    checkEffects(name, declared.effects, declared.run !== undefined || declared.load !== undefined);
 }

package/dist/execute.d.ts

@@ -32,6 +32,7 @@ export interface Command<S extends OptionSpecs = OptionSpecs> {
     group?: string;
     epilogue?: string;
     hidden?: boolean;
+    /** What replaces this command, e.g. `'deploy'`: shown in help, `--schema` and the warning. `true` alone is refused (D1). */
     deprecated?: boolean | string;
     /**
      * What running it does to the world (N6). Declaring one of the three is what exposes the

package/dist/execute.js

@@ -1,18 +1,15 @@
 import { dirname } from 'node:path';
 import { parseArgs } from 'node:util';
-import { ConfigError, explain, resolve as resolveLayers } from 'seniority/precedence';
+import { ConfigError, resolve as resolveLayers } from 'seniority/precedence';
 import { detectAgent } from './agent.js';
 import { checkCommand } from './definition.js';
 import { ExitCode, isExitCode } from './exit-code.js';
-import { renderHelp } from './help.js';
 import { Manifest, relationsOf } from './manifest.js';
-import { serveMcp } from './mcp.js';
 import { camel, kebab } from './names.js';
 import { nearestPackage } from './pkg.js';
 import { host } from './runtime.js';
-import { commandSchemaOf, machineJson, schemaOf, summaryOf, typedName } from './schema.js';
 import { detachedTeardown, processTeardown } from './shutdown.js';
-import { checkRelations, coerce, UsageError } from './validate.js';
+import { AuthError, checkRelations, coerce, UsageError } from './validate.js';
 function helpFields(c) {
     const node = {};
     if (c.description !== undefined)
@@ -38,7 +35,7 @@ function helpFields(c) {
     return node;
 }
 export function defineCommand(command) {
-    checkCommand(command.name, command.options ?? {}, command.effects, command.run !== undefined || command.load !== undefined);
+    checkCommand(command.name, command);
     return command;
 }
 function addTree(manifest, parent, commands) {
@@ -182,7 +179,7 @@ async function resolveValues(manifest, specs, values, io) {
     const out = { values: resolution.values, provenance: resolution.provenance };
     const asked = values['explain'];
     if (typeof asked === 'string')
-        out.explainText = explain(asked, resolution);
+        out.explainText = (await import('seniority/explain')).explain(asked, resolution);
     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>`);
@@ -214,6 +211,18 @@ 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],
+];
+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)
@@ -221,12 +230,9 @@ async function describeFailure(cause, argv, node) {
     const message = cause instanceof Error ? cause.message : String(cause);
     if (cause instanceof ActionRequired)
         return { code: ExitCode.CANCELLED, message, action: cause.spec, ...(cause.spec.hint === undefined ? {} : { hint: cause.spec.hint }) };
-    if (cause instanceof UsageError) {
-        return { code: ExitCode.USAGE, message, ...(cause.hint === undefined ? {} : { hint: cause.hint }) };
-    }
-    if (cause instanceof ConfigError) {
-        return { code: ExitCode.CONFIG, message, ...(cause.hint === undefined ? {} : { hint: cause.hint }) };
-    }
+    const named = CLASSIFIED.find(([Class]) => cause instanceof Class);
+    if (named !== undefined)
+        return { code: named[1], message, ...carried(cause) };
     if (isParseArgsFailure(cause)) {
         const explain = await import('./unknown-option.js');
         const dash = explain.singleDashHint(argv);
@@ -251,7 +257,8 @@ function runnableNext(manifest, spec, json) {
     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']);
-function helpDocumentOf(manifest, node) {
+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(' '))
@@ -275,19 +282,24 @@ export function beforeTerminator(argv) {
 function rootNode(manifest, root) {
     return manifest.find(root) ?? { path: root, options: {} };
 }
-function unresolved({ manifest, root, io }, argv, at) {
+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).includes('--json'))
-            return { text: `${machineJson(helpDocumentOf(manifest, node), beforeTerminator(argv))}\n`, code: ExitCode.OK };
-        return { text: renderHelp(manifest, node, { width: io.width }), code: ExitCode.OK };
+            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: renderHelp(manifest, node, { width: io.width }), code: ExitCode.USAGE };
+        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) {
@@ -310,11 +322,11 @@ async function surface(manifest, argv, io) {
     if (await completion(manifest, argv, io))
         return true;
     if (argv[0] === 'help') {
-        io.out.write(helpCommand(manifest, argv.slice(1), manifest.rootPath, io.width));
+        io.out.write(await helpCommand(manifest, argv.slice(1), manifest.rootPath, io));
         return true;
     }
     if (head.includes('--schema')) {
-        io.out.write(`${machineJson(schemaSurface(manifest, argv), head)}\n`);
+        io.out.write(`${await machineJson(await schemaSurface(manifest, argv), head)}\n`);
         return true;
     }
     if (head[0] === '--mcp') {
@@ -333,13 +345,15 @@ async function surface(manifest, argv, io) {
             });
             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;
 }
 const SCHEMA_BUDGET = 48_000;
-function schemaSurface(manifest, argv) {
+async function schemaSurface(manifest, argv) {
+    const { commandSchemaOf, schemaOf, summaryOf } = await import('./schema.js');
     const { node } = manifest.resolve(beforeTerminator(argv).filter((a) => a !== '--schema' && !a.startsWith('--format=')), manifest.rootPath);
     if (node?.run !== undefined)
         return commandSchemaOf(node, manifest.rootPath);
@@ -347,9 +361,9 @@ function schemaSurface(manifest, argv) {
     const budget = manifest.schemaBudget ?? SCHEMA_BUDGET;
     return JSON.stringify(full).length <= budget ? full : summaryOf(manifest, budget);
 }
-function helpCommand(manifest, argv, root, width) {
+async function helpCommand(manifest, argv, root, io) {
     const { node } = manifest.resolve(argv, root);
-    return renderHelp(manifest, node ?? rootNode(manifest, root), { width });
+    return renderHelp(manifest, node ?? rootNode(manifest, root), io);
 }
 function changedOf(node, data) {
     const value = isPlainObject(data) ? data['changed'] : undefined;
@@ -360,6 +374,10 @@ function changedOf(node, data) {
     }
     return undefined;
 }
+function exitCodeOf(data) {
+    const code = isPlainObject(data) ? data['exitCode'] : undefined;
+    return isExitCode(code) ? code : ExitCode.OK;
+}
 function versionOf(manifest, io) {
     const declared = manifest.version ?? (typeof io.pkg?.data['version'] === 'string' ? io.pkg.data['version'] : undefined);
     if (declared === undefined)
@@ -371,9 +389,9 @@ async function dispatch(manifest, { node, rest, name }, io) {
     const flags = canonical(parsed.values, node.options, parsed.tokens);
     const json = flags.json === true;
     if (flags.help === true && json)
-        return { json, text: `${machineJson(helpDocumentOf(manifest, node), json ? ['--json'] : [])}\n` };
+        return { json, text: `${await machineJson(await helpDocumentOf(manifest, node), json ? ['--json'] : [])}\n` };
     if (flags.help === true)
-        return { json, text: renderHelp(manifest, node, { width: io.width }) };
+        return { json, text: await renderHelp(manifest, node, io) };
     if (flags.version === true)
         return { json, text: `${versionOf(manifest, io)}\n` };
     const resolved = await resolveValues(manifest, node.options, flags, io);
@@ -420,7 +438,7 @@ 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`);
-    return await leave(io, ExitCode.OK);
+    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);
@@ -465,7 +483,7 @@ export async function execute(manifest, opts = {}) {
             return await leave(io, ExitCode.OK);
         const { node, rest } = manifest.resolve(argv, root);
         if (node?.run === undefined) {
-            const { text, code } = unresolved({ manifest, root, io }, argv, node);
+            const { text, code } = await unresolved({ manifest, root, io }, argv, node);
             (code === ExitCode.OK ? io.out : io.err).write(text);
             return await leave(io, code);
         }

package/dist/exit-code.d.ts

@@ -10,9 +10,25 @@ export declare const ExitCode: {
     readonly CONFIG: 3;
     /** The user or caller cancelled. */
     readonly CANCELLED: 4;
+    /**
+     * E6 — the far side said no: a credential is missing, expired, or refused.
+     *
+     * Its own code because it is the most actionable one in the survey. `RUNTIME` means *it
+     * failed, read the message*; `AUTH` means *log in and run it again*, and a script or an
+     * agent can branch on that without parsing prose. `USAGE` says fix the script, `CONFIG`
+     * says fix the runner, and this says fix the credential — three different responses that
+     * collapsed into one code before it existed.
+     *
+     * **5, where `gh` uses 4.** Four is `CANCELLED` here and has been since the contract was
+     * written, and moving a published code to match another tool's is a breaking change for
+     * every consumer that already branches on it. The survey's other citation, `aws` v2, uses
+     * 252/253/254 and agrees with nobody either; what matters is that the code is stable and
+     * documented, not that it matches a particular neighbour.
+     */
+    readonly AUTH: 5;
     /** SIGINT after the terminal was restored (E5). */
     readonly SIGINT: 130;
 };
 export type ExitCode = (typeof ExitCode)[keyof typeof ExitCode];
-/** True for the six codes in the contract and nothing else. */
+/** True for the seven codes in the contract and nothing else. */
 export declare function isExitCode(n: unknown): n is ExitCode;

package/dist/exit-code.js

@@ -4,6 +4,7 @@ export const ExitCode = {
     USAGE: 2,
     CONFIG: 3,
     CANCELLED: 4,
+    AUTH: 5,
     SIGINT: 130,
 };
 const CODES = new Set(Object.values(ExitCode));

package/dist/help-entry.d.ts

@@ -0,0 +1,2 @@
+/** `burgee/help` — the help renderer, by itself. See `index.ts` for why it is not in the barrel. */
+export { renderHelp, type HelpOptions, type HelpTheme, type HelpToken } from './help.js';

package/dist/help-entry.js

@@ -0,0 +1 @@
+export { renderHelp } from './help.js';

package/dist/help.d.ts

@@ -24,6 +24,18 @@ export interface HelpOptions {
      */
     theme?: HelpTheme;
 }
+/**
+ * Whether the engine colours help (O2). `FORCE_COLOR` decides when set — `0` and `false`
+ * off, anything else, the empty string included, on — so it overrides a pipe and
+ * `NO_COLOR` both, as Node's own `getColorDepth` does. Otherwise colour needs someone to
+ * see it: an interactive terminal (the caller's answer, in which a detected agent is not
+ * one, N12), no non-empty `NO_COLOR`, and a `TERM` other than `dumb`.
+ *
+ * It lives here, not in the engine, so the startup path pays for none of it (W4).
+ * Not `tty.WriteStream.prototype.hasColors(env)`, which gives the same answers: with
+ * both variables set it calls `process.emitWarning`, and this runs under an injected env.
+ */
+export declare function colorFor(env: Record<string, string | undefined>, interactive: boolean): boolean;
 /**
  * Word-wrap one paragraph; lines the author indented are kept verbatim (yargs #2120).
  *

package/dist/help.js

@@ -3,6 +3,12 @@ import { width as displayWidth, widest } from 'linegauge';
 import { flagsOf, kebab } from './names.js';
 const identity = (s) => s;
 const PLAIN = { heading: identity, command: identity, flag: identity, value: identity };
+export function colorFor(env, interactive) {
+    const force = env['FORCE_COLOR'];
+    if (force !== undefined)
+        return force !== '0' && force !== 'false';
+    return interactive && !env['NO_COLOR'] && env['TERM'] !== 'dumb';
+}
 const DEFAULTS = {
     heading: (s) => styleText('bold', s, { validateStream: false }),
     command: (s) => styleText('bold', s, { validateStream: false }),