burgee 0.8.0 → 0.9.1

package/README.md

@@ -19,6 +19,10 @@
   <img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" alt="License: MIT" />
 </p>
 
+<p align="center">
+  Docs: <a href="https://burgee.interlace.tools/docs/packages/burgee">https://burgee.interlace.tools/docs/packages/burgee</a>
+</p>
+
 A **burgee** is the small swallowtail flag a boat flies to say which club or fleet it
 belongs to — a flag of identity, not of instruction. That is what this framework does for
 a command-line program: a command declares itself once, and every surface is that
@@ -73,8 +77,10 @@ Nothing here needs keeping in sync, because nothing is written twice.
 
 ## Already on commander?
 
-Drop-in compatible with both incumbents, graded by **their own test suites** — 1,215
-commander tests and 1,185 yargs tests — with the pass rate published and ratcheting:
+Drop-in compatible with both incumbents, graded by **their own test suites** — 1,360 / 1,360
+of commander's tests and 804 / 804 of yargs' on the
+[compatibility page](https://burgee.interlace.tools/docs/compatibility) — with the pass rate
+published and ratcheting:
 
 ```diff
 - import { Command } from 'commander';
@@ -119,9 +125,46 @@ help from the manifest, plugins with hook filters, and a `burgee/commander` faç
 runs a real commander program. The dev loop, prompts, lazy commands and groups are not
 here yet.
 
-Roadmap, architecture and the 101-requirement floor:
+Roadmap, architecture and the 114-requirement floor:
 <https://github.com/ofri-peretz/burgee>
 
+## FAQ
+
+### Is burgee a commander alternative?
+
+Yes — and a yargs alternative. It is drop-in compatible with both: change
+`import { Command } from 'commander'` to `import { Command } from 'burgee/commander'` (or
+`yargs` to `burgee/yargs`) and your code and tests are unchanged. Compatibility is graded by
+each host's own test suite in CI, not asserted. Side by side:
+[burgee vs commander](https://burgee.interlace.tools/docs/vs/commander) and
+[burgee vs yargs](https://burgee.interlace.tools/docs/vs/yargs).
+
+### How do I make my CLI usable by an AI agent?
+
+Declare it with `defineCommand()` — or keep it on commander or yargs syntax through the
+drop-in front ends. Every command then answers `--json` with one stable envelope,
+`--schema` with the whole command tree as data, and exits `2` when the *command* was wrong
+so an agent knows to rewrite it rather than retry. None of it is written by hand; it is
+the declaration read by a different reader.
+[Your CLI is an agent tool](https://burgee.interlace.tools/docs/agent-surfaces) has each surface.
+
+### How do I expose a CLI over MCP?
+
+Run it with `--mcp`: the same manifest is served as MCP tools over stdio. A command becomes
+a tool only when it declares its `effects` (`read_only`, `idempotent` or `non_idempotent`),
+so nothing reaches an agent by accident. Register it with any stdio client:
+
+```json
+{ "mcpServers": { "mytool": { "command": "npx", "args": ["mytool", "--mcp"] } } }
+```
+
+### Does it have dependencies?
+
+None outside this repository. `burgee` installs five packages from its own family —
+`bellpull`, `closeout`, `linegauge`, `roundel` and `seniority` — and each of those takes
+nothing from outside it either: one repository, one release pipeline, one supply chain to
+audit.
+
 ---
 
 Part of the [burgee](https://github.com/ofri-peretz/burgee) family: a CLI on burgee declares
@@ -141,6 +184,7 @@ Graded by the incumbent's own test suite:
 | suite | passing |
 | :-- | --: |
 | `commander` | 1360 / 1360 |
+| `meow` | 132 / 148 |
 | `yargs` | 804 / 804 |
 ## Where it sits
 

package/dist/check.d.ts

@@ -0,0 +1,22 @@
+import { ExitCode } from './exit-code.js';
+export interface CheckReport {
+    name: string;
+    commands: {
+        path: string;
+        description: string;
+        effects: string;
+    }[];
+    hooks: {
+        stage: 'preRun' | 'postRun' | 'onError';
+        applies: string;
+    }[];
+}
+export interface CheckRefusal {
+    refused: {
+        code: string;
+        message: string;
+        fix: string;
+    };
+    exitCode: ExitCode;
+}
+export declare function checkPlugin(file: string): Promise<CheckReport | CheckRefusal>;

package/dist/check.js

@@ -0,0 +1,35 @@
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { ExitCode } from './exit-code.js';
+import { Manifest } from './manifest.js';
+import { PluginError, validate } from './plugin.js';
+const STAGES = ['preRun', 'postRun', 'onError'];
+const refuse = (code, message, fix) => ({ refused: { code, message, fix }, exitCode: ExitCode.RUNTIME });
+export async function checkPlugin(file) {
+    const loaded = (await import(pathToFileURL(resolve(file)).href));
+    const plugin = loaded.default ?? loaded;
+    try {
+        validate(plugin, []);
+        new Manifest().use(plugin);
+    }
+    catch (error) {
+        if (error instanceof PluginError)
+            return refuse(error.code, error.message, error.fix);
+        if (error instanceof Error)
+            return refuse('E_PLUGIN_SCHEMA', error.message, 'fix the contributed command the message names; it is checked exactly as one of the program’s own');
+        throw error;
+    }
+    const { name, commands = [], hooks = {} } = plugin;
+    const report = {
+        name,
+        commands: commands.map((c) => ({ path: c.path.join(' '), description: c.description ?? '', effects: String(c.effects ?? 'undeclared') })),
+        hooks: STAGES.filter((stage) => hooks[stage] !== undefined).map((stage) => ({
+            stage,
+            applies: hooks[stage]?.filter?.command === undefined ? 'every command' : `commands matching ${String(hooks[stage]?.filter?.command)}`,
+        })),
+    };
+    if (report.commands.length === 0 && report.hooks.length === 0) {
+        return refuse('E_NO_CONTRIBUTION', `${name} registers, but contributes nothing burgee reads`, 'add `commands` or `hooks` — a key another package in the family reads is allowed in the same object, but `burgee check` cannot show it');
+    }
+    return report;
+}

package/dist/cli.d.ts

@@ -81,4 +81,10 @@ export declare const migrateCommand: import("./execute.js").Command<{
         readonly description: "migrate even though the git tree has uncommitted changes";
     };
 }>;
+/**
+ * `burgee check <plugin-file>` — the feedback loop PRINCIPLES 7 asks every extension surface
+ * for, and the one burgee did not have. See `check.ts`: this one returns its report as data, so
+ * `--json` is the form an agent that just wrote a plugin reads.
+ */
+export declare const pluginCheckCommand: import("./execute.js").Command<import("./execute.js").OptionSpecs>;
 export declare const program: import("./manifest.js").Manifest;

package/dist/cli.js

@@ -133,9 +133,20 @@ export const migrateCommand = defineCommand({
         return await migrate({ dir: positionals[0] ?? host.cwd(), dryRun: options.dryRun === true, force: options.force === true });
     },
 });
+export const pluginCheckCommand = defineCommand({
+    name: 'check',
+    description: 'Validate a burgee plugin, register it into a throwaway program, and report what it contributes',
+    arguments: [{ name: 'file', description: 'the plugin module to check' }],
+    effects: 'read_only',
+    examples: [
+        { command: 'burgee check ./my-plugin.mjs', description: 'what the plugin contributes, or why it was refused' },
+        { command: 'burgee check ./my-plugin.mjs --json', description: 'the same, as data; exit 1 on a refusal' },
+    ],
+    run: async ({ positionals }) => (await import('./check.js')).checkPlugin(positionals[0] ?? ''),
+});
 export const program = defineProgram({
     name: 'burgee',
     description: 'The agent-native CLI framework, and the tools that come with it',
-    commands: [brandCommand, devCommand, migrateCommand],
+    commands: [brandCommand, devCommand, migrateCommand, pluginCheckCommand],
 });
 run(program);

package/dist/commander/command.js

@@ -5,7 +5,6 @@ import { stripVTControlCharacters } from 'node:util';
 import * as crossSpawn from 'bellpull/cross-spawn';
 import { ExitCode } from '../exit-code.js';
 import { Manifest } from '../manifest.js';
-import { serveMcp } from '../mcp.js';
 import { host } from '../runtime.js';
 import { machineJson, schemaOf } from '../schema.js';
 import { suggestSimilar } from '../suggest.js';
@@ -1473,7 +1472,7 @@ Expecting one of '${HELP_POSITIONS.join("', '")}'`);
                 await root.parseAsync(args, { from: 'user', stdout: { write: (s) => out.push(s) }, stderr: { write: (s) => err.push(s) }, exit: (c) => void (code = c) });
                 return { stdout: out.join(''), stderr: err.join(''), code };
             };
-            return serveMcp(this.manifest, { input: host.stdin, output: { write: writeOut }, invoke }).then(() => true);
+            return import('../mcp.js').then(async ({ serveMcp }) => serveMcp(this.manifest, { input: host.stdin, output: { write: writeOut }, invoke })).then(() => true);
         }
         return false;
     }
@@ -1565,6 +1564,10 @@ Expecting one of '${HELP_POSITIONS.join("', '")}'`);
             .then(async (value) => {
             await manifest.fire('postRun', name, options);
             settle(value);
+        })
+            .catch(async (cause) => {
+            await manifest.fire('onError', name, options);
+            throw cause;
         });
     }
     _warnDeprecated() {

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

@@ -47,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

@@ -5,6 +5,7 @@ export const WITHHELD = 'withheld';
 const DECLARED = [...EFFECTS, WITHHELD];
 const RESERVED = new Set(['json', 'help', 'schema', 'mcp', 'version', 'explain']);
 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`);
     }
@@ -49,7 +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) {
-    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;
@@ -375,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);
@@ -469,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 }),

package/dist/index.d.ts

@@ -4,15 +4,40 @@
  *
  * The public entry, and only that. The execution core lives in execute.ts so a
  * façade can import it without pulling this barrel.
+ *
+ * ## What is not here, and why (D-093, reversed on a measurement)
+ *
+ * This barrel used to re-export the value half of `help.ts`, `mcp.ts`, `schema.ts`,
+ * `plugin.ts`, `manifest.ts` and `seniority/precedence` as a convenience. A re-export is
+ * not free: it makes those modules live for every consumer of `burgee`, whether or not
+ * anything reads them. `execute.ts` loads each one behind an `await import()`, so the only
+ * thing keeping them on the startup path was this file.
+ *
+ * Measured 2026-09-21 with `--splitting --outdir` over the transitive closure of `import`
+ * statements — the initial load a consumer actually pays:
+ *
+ *   - `import { run } from 'burgee'` — **44,663 bytes**
+ *   - the same program against `execute.ts` directly — **31,047 bytes**
+ *   - cold start, `burgee ÷ cac` — **2.113 → 1.717**
+ *
+ * D-093 declined this split on a cold-start argument it did not have the number for. The
+ * number says 13,616 bytes and 19% of startup, so the split lands: every value moved here
+ * has a subpath of its own (`burgee/help`, `burgee/mcp`, `burgee/schema`, `burgee/plugin`,
+ * `burgee/config`), which is where a program that wants it should say so.
+ *
+ * **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 { 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';
-export { camel, kebab, UsageError } from './validate.js';
+export { AuthError, camel, kebab, UsageError } from './validate.js';
 export { AGENT_PROBES, detectAgent, type AgentProbe, type Detection } from './agent.js';
-export { renderHelp, type HelpOptions, type HelpTheme, type HelpToken } from './help.js';
-export { annotationsOf, MCP_PROTOCOL_VERSION, serveMcp, toolsOf, type Invoke, type ServeOptions, type Tool, type ToolAnnotations } from './mcp.js';
-export { ConfigError, envName, explain, resolve, screaming, type Candidate, type Layers, type Provenance, type Resolution, type Source } from 'seniority/precedence';
-export { commandSchemaOf, inputSchemaOf, schemaOf, summaryOf, type CommandSchema, type JsonSchema, type ProgramSchema, type SchemaSummary } from './schema.js';
-export { CONTRACT, definePlugin, PluginError, type PluginErrorCode } from './plugin.js';
-export { Manifest, type ArgumentSpec, type CommandNode, type Effects, type Example, type Hook, type LazyModule, type OptionSpec, type ActionRequiredSpec, type Plugin, type Relation, type RunContext, type StandardResult, type StandardSchemaV1, } from './manifest.js';
+export type { HelpOptions, HelpTheme, HelpToken } from './help.js';
+export type { Invoke, ServeOptions, Tool, ToolAnnotations } from './mcp.js';
+export type { Candidate, Layers, Provenance, Resolution, Source } from 'seniority/precedence';
+export type { CommandSchema, JsonSchema, ProgramSchema, SchemaSummary } from './schema.js';
+export type { PluginErrorCode } from './plugin.js';
+export type { 
+/** The class itself lives at `burgee/schema`; the *type* stays here so `defineProgram`'s return type is nameable. */
+Manifest, ArgumentSpec, CommandNode, Effects, Example, Hook, LazyModule, OptionSpec, ActionRequiredSpec, Plugin, Relation, RunContext, StandardResult, StandardSchemaV1, } from './manifest.js';

package/dist/index.js

@@ -1,11 +1,5 @@
 export { ExitCode, isExitCode } from './exit-code.js';
 export { defineCommand, defineProgram, execute, resolveCommand, run, runCommand, sharedOptions, } from './execute.js';
 export { checkCommand, checkDefinition } from './definition.js';
-export { camel, kebab, UsageError } from './validate.js';
+export { AuthError, camel, kebab, UsageError } from './validate.js';
 export { AGENT_PROBES, detectAgent } from './agent.js';
-export { renderHelp } from './help.js';
-export { annotationsOf, MCP_PROTOCOL_VERSION, serveMcp, toolsOf } from './mcp.js';
-export { ConfigError, envName, explain, resolve, screaming } from 'seniority/precedence';
-export { commandSchemaOf, inputSchemaOf, schemaOf, summaryOf } from './schema.js';
-export { CONTRACT, definePlugin, PluginError } from './plugin.js';
-export { Manifest, } from './manifest.js';

package/dist/mcp-entry.d.ts

@@ -0,0 +1,2 @@
+/** `burgee/mcp` — the MCP server, by itself. See `index.ts` for why it is not in the barrel. */
+export { annotationsOf, MCP_PROTOCOL_VERSION, serveMcp, toolsOf, type Invoke, type ServeOptions, type Tool, type ToolAnnotations } from './mcp.js';

package/dist/mcp-entry.js

@@ -0,0 +1 @@
+export { annotationsOf, MCP_PROTOCOL_VERSION, serveMcp, toolsOf } from './mcp.js';

package/dist/meow/parse.d.ts

@@ -0,0 +1,21 @@
+import { type AnyFlag, type Options } from './types.js';
+/** Where a command run's parent arguments end and the child's begin. */
+export interface Split {
+    parent: string[];
+    input: string[];
+    command?: string;
+    unknownCommand?: string;
+}
+/** Every flag name a caller may write, and the canonical name each maps to. */
+export declare function aliasMap(flags: Record<string, AnyFlag>): Record<string, string[]>;
+export declare function typeofDefault(value: unknown): 'string' | 'boolean' | 'number' | undefined;
+/**
+ * Where the parent's arguments end and the command's begin.
+ *
+ * The first token the parser reads as positional is the command word; everything after it in
+ * the *raw* argv is the child's, unparsed. `--` is not a fence here — the suite states that
+ * `-- --unknown run` reports `Unknown command: --unknown`, so a post-separator word is a
+ * candidate command like any other.
+ */
+export declare function splitAtCommand(argv: string[], parserOptions: Record<string, unknown>, opts: Options): Split;
+/** stderr and exit 2 — how meow ends a run the flags do not support. */