burgee 0.2.0 → 0.4.0

package/dist/execute.js

@@ -8,7 +8,7 @@ import { serveMcp } from './mcp.js';
 import { camel, kebab } from './names.js';
 import { nearestPackage } from './pkg.js';
 import { ConfigError, explain, resolve as resolveLayers } from './precedence.js';
-import { commandSchemaOf, schemaOf, summaryOf } from './schema.js';
+import { commandSchemaOf, machineJson, schemaOf, summaryOf } from './schema.js';
 import { checkDefinition, checkRelations, coerce, UsageError } from './validate.js';
 function helpFields(c) {
     const node = {};
@@ -51,11 +51,15 @@ function addTree(manifest, parent, commands) {
             ...helpFields(c),
             options: c.options ?? {},
             ...(c.run === undefined ? {} : { run: c.run }),
+            ...(c.load === undefined ? {} : { load: c.load }),
         });
         if (c.commands !== undefined)
             addTree(manifest, path, c.commands);
     }
 }
+export function sharedOptions(name, specs) {
+    return Object.fromEntries(Object.entries(specs).map(([key, spec]) => [key, { ...spec, sharedFrom: name }]));
+}
 export function defineProgram(program) {
     const manifest = new Manifest();
     manifest.rootPath = [program.name];
@@ -112,6 +116,7 @@ function render(value) {
     }
     return String(value);
 }
+const NO = 'no-';
 function toParseConfig(specs, withConfig) {
     const config = { json: { type: 'boolean' }, help: { type: 'boolean' }, version: { type: 'boolean' }, explain: { type: 'string' } };
     if (withConfig) {
@@ -124,11 +129,28 @@ function toParseConfig(specs, withConfig) {
             ...(spec.short === undefined ? {} : { short: spec.short }),
             ...(spec.multiple === true ? { multiple: true } : {}),
         };
+        if (spec.type === 'boolean')
+            config[`${NO}${kebab(name)}`] = { type: 'boolean' };
     }
     return config;
 }
-function canonical(values) {
-    return Object.fromEntries(Object.entries(values).map(([k, v]) => [camel(k), v]));
+function canonical(values, specs, tokens) {
+    const out = {};
+    const negatable = (key) => {
+        const bare = camel(key.startsWith(NO) ? key.slice(NO.length) : key);
+        return specs[bare]?.type === 'boolean' ? bare : '';
+    };
+    for (const [k, v] of Object.entries(values))
+        if (!k.startsWith(NO) || negatable(k) === '')
+            out[camel(k)] = v;
+    for (const token of tokens) {
+        if (token.kind !== 'option')
+            continue;
+        const bare = negatable(token.name);
+        if (bare !== '')
+            out[bare] = !token.name.startsWith(NO);
+    }
+    return out;
 }
 function packageLayer(pkg, name) {
     if (pkg === undefined || name === undefined)
@@ -191,18 +213,7 @@ function exitSignal(cause) {
     const code = cause?.code;
     return typeof code === 'number' && isExitCode(code) ? code : undefined;
 }
-const SINGLE_DASH_WORD = /^-([a-zA-Z][\w-]+)(?:=.*)?$/;
-function singleDashHint(argv) {
-    for (const token of argv) {
-        if (token === '--')
-            return undefined;
-        const found = SINGLE_DASH_WORD.exec(token);
-        if (found?.[1] !== undefined)
-            return `did you mean --${found[1]}? a single dash introduces one-letter options`;
-    }
-    return undefined;
-}
-function describeFailure(cause, argv) {
+async function describeFailure(cause, argv, node) {
     const signal = exitSignal(cause);
     if (signal !== undefined)
         return { code: signal, message: '', silent: true };
@@ -216,7 +227,12 @@ function describeFailure(cause, argv) {
         return { code: ExitCode.CONFIG, message, ...(cause.hint === undefined ? {} : { hint: cause.hint }) };
     }
     if (isParseArgsFailure(cause)) {
-        return { code: ExitCode.USAGE, message, hint: singleDashHint(argv) ?? 'run --help to see the available options' };
+        const explain = await import('./unknown-option.js');
+        const dash = explain.singleDashHint(argv);
+        if (dash !== undefined)
+            return { code: ExitCode.USAGE, message, hint: dash };
+        const better = explain.unknownOption(cause, Object.keys(node?.options ?? {}));
+        return { code: ExitCode.USAGE, message, hint: 'run --help to see the available options', ...better };
     }
     return { code: ExitCode.RUNTIME, message };
 }
@@ -242,13 +258,16 @@ export function beforeTerminator(argv) {
 function rootNode(manifest, root) {
     return manifest.find(root) ?? { path: root, options: {} };
 }
-function unresolved({ manifest, root, io: { width } }, argv, at) {
+function unresolved({ manifest, root, io }, argv, at) {
     const node = at ?? rootNode(manifest, root);
     const typed = argv.slice(node.path.length - root.length);
-    if (typed.length > 0 && HELP_FLAGS.has(typed[0] ?? ''))
-        return { text: renderHelp(manifest, node, { width }), code: ExitCode.OK };
+    const first = typed[0] ?? '';
+    if (typed.length > 0 && HELP_FLAGS.has(first))
+        return { text: renderHelp(manifest, node, { width: io.width }), 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 }), code: ExitCode.USAGE };
+        return { text: renderHelp(manifest, node, { width: io.width }), code: ExitCode.USAGE };
     throw new UsageError(`unknown command "${typed[0] ?? ''}"`, 'run --help to see the available commands');
 }
 async function completion(manifest, argv, io) {
@@ -275,7 +294,7 @@ async function surface(manifest, argv, io) {
         return true;
     }
     if (head.includes('--schema')) {
-        io.out.write(`${JSON.stringify(schemaSurface(manifest, argv), null, 2)}\n`);
+        io.out.write(`${machineJson(schemaSurface(manifest, argv), head)}\n`);
         return true;
     }
     if (head[0] === '--mcp') {
@@ -301,7 +320,7 @@ async function surface(manifest, argv, io) {
 }
 const SCHEMA_BUDGET = 48_000;
 function schemaSurface(manifest, argv) {
-    const { node } = manifest.resolve(beforeTerminator(argv).filter((a) => a !== '--schema'), manifest.rootPath);
+    const { node } = manifest.resolve(beforeTerminator(argv).filter((a) => a !== '--schema' && !a.startsWith('--format=')), manifest.rootPath);
     if (node?.run !== undefined)
         return commandSchemaOf(node, manifest.rootPath);
     const full = schemaOf(manifest);
@@ -329,7 +348,7 @@ function versionOf(manifest, io) {
 }
 async function dispatch(manifest, { node, rest, name }, io) {
     const parsed = parseArgs({ args: rest, options: toParseConfig(node.options, manifest.config !== undefined), allowPositionals: true, strict: true, tokens: true });
-    const flags = canonical(parsed.values);
+    const flags = canonical(parsed.values, node.options, parsed.tokens);
     const json = flags.json === true;
     if (flags.help === true)
         return { json, text: renderHelp(manifest, node, { width: io.width }) };
@@ -342,6 +361,8 @@ async function dispatch(manifest, { node, rest, name }, io) {
     checkRelations(node.relations, resolved.values, provenance);
     const values = await coerce(node.options, resolved.values);
     const { positionals, passthrough } = splitPositionals(parsed.tokens);
+    requirePositionals(node, positionals);
+    warnDeprecated(node, io);
     await manifest.fire('preRun', name, values);
     const exit = (code) => {
         io.exit(code);
@@ -353,6 +374,25 @@ async function dispatch(manifest, { node, rest, name }, io) {
     const changed = changedOf(node, data);
     return { json, data, provenance, ...(changed === undefined ? {} : { changed }) };
 }
+function requirePositionals(node, positionals) {
+    const required = (node.arguments ?? []).filter((a) => a.required !== false && a.variadic !== true);
+    const missing = required[positionals.length];
+    if (positionals.length < required.length && missing !== undefined) {
+        throw new UsageError(`missing required argument "${missing.name}"`, `run --help to see what "${node.path.slice(1).join(' ')}" takes`);
+    }
+}
+const warned = new Set();
+function warnDeprecated(node, io) {
+    if (node.deprecated === undefined || node.deprecated === false)
+        return;
+    const key = node.path.join(' ');
+    if (warned.has(key))
+        return;
+    warned.add(key);
+    const typed = node.path.slice(1).join(' ') || key;
+    const use = typeof node.deprecated === 'string' ? `, use '${node.deprecated}'` : '';
+    io.err.write(`warning: '${typed}' is deprecated${use}\n`);
+}
 function emit(io, outcome) {
     if (outcome.text !== undefined) {
         io.out.write(outcome.text);
@@ -364,7 +404,7 @@ function emit(io, outcome) {
     return io.exit(ExitCode.OK);
 }
 async function report(cause, { manifest, io, argv, json, name }) {
-    const failure = describeFailure(cause, argv);
+    const failure = await describeFailure(cause, argv, resolveCommand(manifest, argv) ?? undefined);
     if (failure.silent === true)
         return io.exit(failure.code);
     await manifest.fire('onError', name, {});
@@ -418,6 +458,17 @@ export async function execute(manifest, opts = {}) {
         return await report(cause, { manifest, io, argv, json, name });
     }
 }
+export function resolveCommand(manifest, argv) {
+    const { node } = manifest.resolve(beforeTerminator(argv), manifest.rootPath);
+    return node ?? null;
+}
+export async function runCommand(manifest, argv, opts = {}) {
+    const out = [];
+    const err = [];
+    let code = ExitCode.OK;
+    await execute(manifest, { ...opts, argv: [...argv], from: 'user', stdout: { write: (s) => out.push(s) }, stderr: { write: (s) => err.push(s) }, exit: (c) => void (code = c) });
+    return { code, stdout: out.join(''), stderr: err.join('') };
+}
 export async function run(target, opts = {}) {
     if (target instanceof Manifest)
         return await execute(target, opts);

package/dist/help.d.ts

@@ -1,22 +1,34 @@
+import type { CommandNode, Manifest } from './manifest.js';
+/** The token names of `roundel`'s R3, typed structurally: burgee never imports them (U13). */
+export type HelpToken = 'error' | 'warn' | 'ok' | 'hint' | 'muted' | 'command' | 'flag' | 'value' | 'heading';
 /**
- * Help, rendered from the manifest and nothing else (H1). One layout for every node,
- * so a subcommand's help has everything the root's has (yargs #1500, #1331, #1025).
+ * Per-token styling for help (R7). A user who has `roundel` passes its tokens; a user
+ * who does not gets the defaults. Help reads `heading`, `command`, `flag` and `value`;
+ * the others are accepted so one theme object serves the whole output stack.
  *
- * Section order is fixed (R2): usage, description, arguments, options, global options,
- * commands (grouped, yargs #684), examples, environment, epilogue. Empty sections are
- * omitted. Width comes from the caller — the runtime, in practice (H3) — default 100.
+ * What the theme does not touch: the command name after `Usage:` and every `$ example`
+ * line are rendered plain, whatever the theme says. Styling wraps a finished cell, so a
+ * name is measured and padded plain and never coloured in the manifest (yargs #1699).
  */
-import type { CommandNode, Manifest } from './manifest.js';
+export type HelpTheme = Partial<Record<HelpToken, (s: string) => string>>;
 export interface HelpOptions {
     /** Columns available; 100 when unknown, never `process.stdout` directly (H3). */
     width?: number;
     /** Show type hints such as `[string]`; off by default (H6). */
     verbose?: boolean;
+    /** Apply colour (R7). Off by default: the renderer is pure, so the TTY and NO_COLOR decision stays with the caller. */
+    color?: boolean;
+    /**
+     * Replaces the default styling token by token; read only when `color` is on. See
+     * `HelpTheme` for the lines it leaves plain: the `Usage:` command name and `$ example`.
+     */
+    theme?: HelpTheme;
 }
 /** Word-wrap one paragraph; lines the author indented are kept verbatim (yargs #2120). */
 export declare function wrap(text: string, width: number): string[];
 /**
  * Render help for one node — a runnable command, a group, or both — as text.
- * Deterministic for a given node and width; a snapshot suite pins it.
+ * Deterministic for a given node and width; a snapshot suite pins it. With `color`
+ * off — the default — a theme changes nothing; with it on, only ANSI is added.
  */
 export declare function renderHelp(manifest: Manifest, node: CommandNode, opts?: HelpOptions): string;

package/dist/help.js

@@ -1,11 +1,36 @@
+import { styleText } from 'node:util';
 import { kebab } from './names.js';
+const identity = (s) => s;
+const PLAIN = { heading: identity, command: identity, flag: identity, value: identity };
+const DEFAULTS = {
+    heading: (s) => styleText('bold', s, { validateStream: false }),
+    command: (s) => styleText('bold', s, { validateStream: false }),
+    flag: (s) => styleText('cyan', s, { validateStream: false }),
+    value: (s) => styleText('dim', s, { validateStream: false }),
+};
+function painterFor(paint, kind) {
+    if (kind === 'command')
+        return paint.command;
+    return kind === 'flag' ? paint.flag : paint.value;
+}
+function paintOf(opts) {
+    if (opts.color !== true)
+        return PLAIN;
+    const theme = opts.theme ?? {};
+    return {
+        heading: theme.heading ?? DEFAULTS.heading,
+        command: theme.command ?? DEFAULTS.command,
+        flag: theme.flag ?? DEFAULTS.flag,
+        value: theme.value ?? DEFAULTS.value,
+    };
+}
 const DEFAULT_WIDTH = 100;
 const INDENT = '  ';
 const GUTTER = 2;
 const TERM_SHARE = 0.4;
 const GLOBAL = [
-    { term: '--json', text: 'machine-readable output' },
-    { term: '--help', text: 'show this help' },
+    { term: '--json', text: 'machine-readable output', kind: 'flag' },
+    { term: '--help', text: 'show this help', kind: 'flag' },
 ];
 function deprecation(d) {
     if (d === undefined || d === false)
@@ -41,7 +66,7 @@ function optionTerm(name, spec) {
 function optionRows(options, verbose) {
     return Object.entries(options)
         .filter(([, spec]) => spec.hidden !== true)
-        .map(([name, spec]) => ({ term: optionTerm(name, spec), text: annotate(spec.description ?? '', spec, verbose) }));
+        .map(([name, spec]) => ({ term: optionTerm(name, spec), text: annotate(spec.description ?? '', spec, verbose), kind: 'flag' }));
 }
 const argumentTerm = (a) => {
     const name = a.variadic === true ? `${a.name}...` : a.name;
@@ -51,6 +76,7 @@ function argumentRows(args) {
     return args.map((a) => ({
         term: argumentTerm(a),
         text: [a.description ?? '', a.default === undefined ? '' : `(default: ${a.default})`].filter((p) => p !== '').join(' '),
+        kind: 'value',
     }));
 }
 function commandSections(manifest, node) {
@@ -59,7 +85,7 @@ function commandSections(manifest, node) {
     for (const c of children) {
         const heading = c.group ?? 'Commands:';
         const rows = groups.get(heading) ?? [];
-        rows.push({ term: c.path[c.path.length - 1] ?? '', text: `${c.summary ?? c.description ?? ''}${deprecation(c.deprecated)}`.trim() });
+        rows.push({ term: c.path[c.path.length - 1] ?? '', text: `${c.summary ?? c.description ?? ''}${deprecation(c.deprecated)}`.trim(), kind: 'command' });
         groups.set(heading, rows);
     }
     return [...groups].map(([title, rows]) => ({ title, rows }));
@@ -67,9 +93,9 @@ function commandSections(manifest, node) {
 function environmentRows(options) {
     return Object.entries(options)
         .filter(([, spec]) => spec.env !== undefined && spec.hidden !== true)
-        .map(([name, spec]) => ({ term: spec.env ?? '', text: `--${kebab(name)}` }));
+        .map(([name, spec]) => ({ term: spec.env ?? '', text: `--${kebab(name)}`, kind: 'value' }));
 }
-function usageLine(node, root, hasChildren) {
+function usageLine(node, root, hasChildren, paint) {
     const shown = node.path.slice(root.length).join(' ') || node.path.join(' ');
     const parts = [shown];
     if (hasChildren)
@@ -77,7 +103,7 @@ function usageLine(node, root, hasChildren) {
     parts.push('[options]');
     for (const a of node.arguments ?? [])
         parts.push(argumentTerm(a));
-    return `Usage: ${parts.join(' ')}`;
+    return `${paint.heading('Usage:')} ${parts.join(' ')}`;
 }
 export function wrap(text, width) {
     const out = [];
@@ -103,21 +129,23 @@ function termColumn(rows, width) {
     const longest = Math.max(0, ...rows.map((r) => r.term.length));
     return Math.min(longest, Math.floor(width * TERM_SHARE));
 }
-function layout(rows, width, column) {
+function layout(rows, width, column, paint) {
     const textWidth = Math.max(1, width - INDENT.length - column - GUTTER);
     const lines = [];
-    for (const { term, text } of rows) {
+    for (const { term, text, kind } of rows) {
+        const cell = painterFor(paint, kind)(term);
         if (text === '') {
-            lines.push(`${INDENT}${term}`);
+            lines.push(`${INDENT}${cell}`);
             continue;
         }
         const wrapped = wrap(text, textWidth);
         const continuation = INDENT + ' '.repeat(column + GUTTER);
         if (term.length > column) {
-            lines.push(`${INDENT}${term}`, ...wrapped.map((l) => `${continuation}${l}`));
+            lines.push(`${INDENT}${cell}`, ...wrapped.map((l) => `${continuation}${l}`));
             continue;
         }
-        lines.push(`${INDENT}${term.padEnd(column + GUTTER)}${wrapped[0] ?? ''}`, ...wrapped.slice(1).map((l) => `${continuation}${l}`));
+        const pad = ' '.repeat(column + GUTTER - term.length);
+        lines.push(`${INDENT}${cell}${pad}${wrapped[0] ?? ''}`, ...wrapped.slice(1).map((l) => `${continuation}${l}`));
     }
     return lines;
 }
@@ -130,28 +158,29 @@ function exampleLines(examples, width) {
     }
     return lines;
 }
-function section(title, body) {
-    return body.length === 0 ? [] : [title, ...body, ''];
+function section(title, body, paint) {
+    return body.length === 0 ? [] : [paint.heading(title), ...body, ''];
 }
 export function renderHelp(manifest, node, opts = {}) {
     const width = opts.width ?? DEFAULT_WIDTH;
     const verbose = opts.verbose === true;
+    const paint = paintOf(opts);
     const root = manifest.rootPath;
     const commands = commandSections(manifest, node);
     const args = argumentRows(node.arguments ?? []);
     const options = optionRows(node.options, verbose);
     const env = environmentRows(node.options);
     const column = termColumn([...args, ...options, ...GLOBAL, ...commands.flatMap((s) => s.rows), ...env], width);
-    const lines = [usageLine(node, root, commands.length > 0), ''];
+    const lines = [usageLine(node, root, commands.length > 0, paint), ''];
     if (node.description !== undefined)
         lines.push(...wrap(`${node.description}${deprecation(node.deprecated)}`, width), '');
-    lines.push(...section('Arguments:', layout(args, width, column)));
-    lines.push(...section('Options:', layout(options, width, column)));
-    lines.push(...section('Global options:', layout(GLOBAL, width, column)));
+    lines.push(...section('Arguments:', layout(args, width, column, paint), paint));
+    lines.push(...section('Options:', layout(options, width, column, paint), paint));
+    lines.push(...section('Global options:', layout(GLOBAL, width, column, paint), paint));
     for (const s of commands)
-        lines.push(...section(s.title, layout(s.rows, width, column)));
-    lines.push(...section('Examples:', exampleLines(node.examples ?? [], width)));
-    lines.push(...section('Environment:', layout(env, width, column)));
+        lines.push(...section(s.title, layout(s.rows, width, column, paint), paint));
+    lines.push(...section('Examples:', exampleLines(node.examples ?? [], width), paint));
+    lines.push(...section('Environment:', layout(env, width, column, paint), paint));
     if (node.epilogue !== undefined)
         lines.push(...wrap(node.epilogue, width), '');
     return `${lines.join('\n').trimEnd()}\n`;

package/dist/index.d.ts

@@ -6,11 +6,11 @@
  * façade can import it without pulling this barrel.
  */
 export { ExitCode, isExitCode, type ExitCode as ExitCodeValue } from './exit-code.js';
-export { defineCommand, defineProgram, execute, run, type AnyCommand, type Command, type CommandContext, type InferOptions, type OptionSpecs, type Program, type RunOptions, } from './execute.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 { camel, checkDefinition, kebab, UsageError } from './validate.js';
 export { AGENT_PROBES, detectAgent, type AgentProbe, type Detection } from './agent.js';
-export { renderHelp, type HelpOptions } from './help.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 './precedence.js';
 export { commandSchemaOf, inputSchemaOf, schemaOf, summaryOf, type CommandSchema, type JsonSchema, type ProgramSchema, type SchemaSummary } from './schema.js';
-export { definePlugin, Manifest, type ArgumentSpec, type CommandNode, type Effects, type Example, type Hook, type OptionSpec, type ActionRequiredSpec, type Plugin, type Relation, type RunContext, type StandardResult, type StandardSchemaV1, } from './manifest.js';
+export { definePlugin, 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';

package/dist/index.js

@@ -1,5 +1,5 @@
 export { ExitCode, isExitCode } from './exit-code.js';
-export { defineCommand, defineProgram, execute, run, } from './execute.js';
+export { defineCommand, defineProgram, execute, resolveCommand, run, runCommand, sharedOptions, } from './execute.js';
 export { camel, checkDefinition, kebab, UsageError } from './validate.js';
 export { AGENT_PROBES, detectAgent } from './agent.js';
 export { renderHelp } from './help.js';

package/dist/manifest.d.ts

@@ -53,6 +53,13 @@ export interface OptionSpec {
     /** `true` renders `(deprecated)`; a string names the replacement: `(deprecated: use --force)` (yargs #2248). */
     deprecated?: boolean | string;
     hidden?: boolean;
+    /** The shared set this option was copied from (M4); `--schema` carries it, help lists the option like any other. */
+    sharedFrom?: string;
+}
+/** What a lazily loaded command module exports: the handler as `run` or as the default export (M2). */
+export interface LazyModule {
+    default?: (ctx: RunContext) => unknown;
+    run?: (ctx: RunContext) => unknown;
 }
 /**
  * What running a command does to the world (N6). Declared, never inferred: it decides
@@ -133,9 +140,17 @@ export interface CommandNode {
     /** Required for a command to be served as an MCP tool (N2, N6). */
     effects?: Effects;
     run?: (ctx: RunContext) => unknown;
+    /**
+     * The handler's module, imported on dispatch only (M2): the manifest — help, schema,
+     * completions, MCP tool list — is complete from this node without loading it. A node
+     * with `load` and no `run` gets a `run` that imports on first call.
+     */
+    load?: () => Promise<LazyModule>;
     /** Which plugin contributed this, if any. Declared, never diffed (M3). */
     plugin?: string;
 }
+/** `run` for a lazy node: the module is imported on the first call and never before (M2). */
+export declare function lazyRun(load: () => Promise<LazyModule>): (ctx: RunContext) => unknown;
 /** A hook may declare which commands it applies to, as data. */
 export interface HookFilter {
     command?: RegExp;

package/dist/manifest.js

@@ -1,3 +1,14 @@
+export function lazyRun(load) {
+    let loaded;
+    return async (ctx) => {
+        loaded ??= load();
+        const mod = await loaded;
+        const handler = mod.run ?? mod.default;
+        if (handler === undefined)
+            throw new Error('burgee: a lazy command module must export its handler as run or as the default export');
+        return await handler(ctx);
+    };
+}
 export function definePlugin(plugin) {
     return plugin;
 }
@@ -16,7 +27,7 @@ export class Manifest {
     config;
     schemaBudget;
     add(node) {
-        this.commands.push(node);
+        this.commands.push(node.load !== undefined && node.run === undefined ? { ...node, run: lazyRun(node.load) } : node);
     }
     use(plugin) {
         this.plugins.push(plugin);

package/dist/mcp.d.ts

@@ -33,8 +33,20 @@ export interface ServeOptions {
     };
     invoke: Invoke;
 }
+/** A running server: `done` settles when the input closes; `swap` serves a new manifest and says so (W2). */
+export interface McpServer {
+    done: Promise<void>;
+    /**
+     * Serve this manifest (and its invoke) from the next request on, and emit
+     * `notifications/tools/list_changed` so a connected client re-lists. A call already in
+     * flight finishes against the manifest it started on.
+     */
+    swap: (manifest: Manifest, invoke?: Invoke) => void;
+}
 /**
- * Serve until the input closes. Notifications (no `id`) get no reply; a malformed line gets
- * a JSON-RPC error with a null id, as the spec asks.
+ * Start serving; `done` settles when the input closes. Notifications (no `id`) get no
+ * reply; a malformed line gets a JSON-RPC error with a null id, as the spec asks.
  */
+export declare function startMcp(manifest: Manifest, opts: ServeOptions): McpServer;
+/** Serve until the input closes. */
 export declare function serveMcp(manifest: Manifest, opts: ServeOptions): Promise<void>;

package/dist/mcp.js

@@ -81,14 +81,27 @@ async function handle(session, request) {
             return { error: { code: JSON_RPC_METHOD_NOT_FOUND, message: `method not found: ${request.method}` } };
     }
 }
-export async function serveMcp(manifest, opts) {
+export function startMcp(manifest, opts) {
     const session = {
         manifest,
         invoke: opts.invoke,
         serverInfo: { name: manifest.rootPath.join(' ') || 'burgee', version: manifest.version ?? '0.0.0' },
     };
     const reply = (body) => void opts.output.write(`${JSON.stringify({ jsonrpc: '2.0', ...body })}\n`);
-    for await (const line of createInterface({ input: opts.input, crlfDelay: Infinity })) {
+    const swap = (next, invoke) => {
+        session.manifest = next;
+        if (invoke !== undefined)
+            session.invoke = invoke;
+        reply({ method: 'notifications/tools/list_changed' });
+    };
+    const done = serve(session, opts.input, reply);
+    return { done, swap };
+}
+export async function serveMcp(manifest, opts) {
+    return await startMcp(manifest, opts).done;
+}
+async function serve(session, input, reply) {
+    for await (const line of createInterface({ input, crlfDelay: Infinity })) {
         if (line.trim() === '')
             continue;
         let request;

package/dist/runtime.d.ts

@@ -3,6 +3,16 @@ import { type ExitCode } from './exit-code.js';
 export interface Writer {
     write(chunk: string): unknown;
 }
+/**
+ * Time, as the layers above the parser see it (R14 of `cli-output-stack`). `now` is
+ * monotonic milliseconds from an arbitrary origin; `schedule` runs `fn` after `ms` and
+ * hands back the cancel. Typed structurally so the output stack can accept a `Runtime`
+ * without importing one.
+ */
+export interface Clock {
+    now(): number;
+    schedule(fn: () => void, ms: number): () => void;
+}
 /**
  * The world, as the layers above the parser see it (design R1 of
  * `cli-testing-harness`). Nothing above the parser reads `process.*` directly; it
@@ -22,6 +32,8 @@ export interface Runtime {
     };
     /** Ends the run with an E1 code. In the real runtime this never returns. */
     exit(code: ExitCode): never;
+    /** `performance.now` and `setTimeout` in the real runtime; a manual tick in the harness. */
+    clock: Clock;
 }
 /** The one place in the layer that touches `process`. Locked by `process-reference.lock.test.ts`. */
 export declare const processRuntime: Runtime;

package/dist/runtime.js

@@ -14,4 +14,11 @@ export const processRuntime = {
     exit(code) {
         process.exit(code);
     },
+    clock: {
+        now: () => performance.now(),
+        schedule(fn, ms) {
+            const handle = setTimeout(fn, ms);
+            return () => clearTimeout(handle);
+        },
+    },
 };

package/dist/schema.d.ts

@@ -24,6 +24,8 @@ export interface JsonSchemaProperty {
     maximum?: number;
     /** The command-line spelling of the option (S5). */
     flag?: string;
+    /** The shared set this option was copied from (M4). */
+    sharedFrom?: string;
 }
 export interface CommandSchema {
     /** The command as typed, without the program name: `config get`. */
@@ -32,6 +34,12 @@ export interface CommandSchema {
     summary?: string;
     effects?: Effects;
     deprecated?: boolean | string;
+    /** The heading it is listed under (M1). */
+    group?: string;
+    /** Its handler loads on dispatch (M2): this schema was complete without it. */
+    lazy?: true;
+    /** Which plugin contributed it (M3). */
+    plugin?: string;
     arguments: ArgumentSpec[];
     options: Record<string, OptionSpec>;
     examples: Example[];
@@ -69,3 +77,5 @@ export interface SchemaSummary {
 /** Above the budget (N13): every command by name and summary, and the drilling command for one in full. */
 export declare function summaryOf(manifest: Manifest, budget: number): SchemaSummary;
 export declare function schemaOf(manifest: Manifest): ProgramSchema;
+/** The machine document, compact unless a person asked for the readable one. */
+export declare const machineJson: (value: unknown, head: readonly string[]) => string;

package/dist/schema.js

@@ -30,6 +30,8 @@ function optionProperty(name, spec) {
         p.minimum = spec.minimum;
     if (spec.maximum !== undefined)
         p.maximum = spec.maximum;
+    if (spec.sharedFrom !== undefined)
+        p.sharedFrom = spec.sharedFrom;
     return p;
 }
 export function inputSchemaOf(node) {
@@ -68,6 +70,12 @@ export function commandSchemaOf(node, root) {
         out.effects = node.effects;
     if (node.deprecated !== undefined)
         out.deprecated = node.deprecated;
+    if (node.group !== undefined)
+        out.group = node.group;
+    if (node.load !== undefined)
+        out.lazy = true;
+    if (node.plugin !== undefined)
+        out.plugin = node.plugin;
     return out;
 }
 export function runnable(manifest) {
@@ -106,3 +114,6 @@ export function schemaOf(manifest) {
         out.description = description;
     return out;
 }
+const JSON_PRETTY = '--format=json-pretty';
+const INDENT = 2;
+export const machineJson = (value, head) => JSON.stringify(value, null, head.includes(JSON_PRETTY) ? INDENT : 0);