burgee 0.2.0 → 0.3.0

package/dist/cli.d.ts

@@ -48,4 +48,15 @@ export declare const brandCommand: import("./execute.js").Command<{
         readonly description: "emit anyway when a contrast check fails. Says so in the output";
     };
 }>;
+/**
+ * `burgee dev <entry>` — watch the entry, reload it on change, serve it as MCP on stdio
+ * and print every surface on each save (dev-loop). Loaded only when asked for, so the
+ * CLI's own weight and the framework's stay what they were (W4).
+ */
+export declare const devCommand: import("./execute.js").Command<{
+    readonly 'no-watch': {
+        readonly type: "boolean";
+        readonly description: "load once and serve; do not watch for changes";
+    };
+}>;
 export declare const program: import("./manifest.js").Manifest;

package/dist/cli.js

@@ -97,9 +97,25 @@ export const brandCommand = defineCommand({
         return { out: options.out, files: written.map((s) => s.file), contrast };
     },
 });
+export const devCommand = defineCommand({
+    name: 'dev',
+    description: 'Watch a CLI entry, reload it on change, and serve it as MCP on stdio while you write it',
+    arguments: [{ name: 'entry', description: 'the module that exports the program, as program or as its default export', required: true }],
+    options: {
+        'no-watch': { type: 'boolean', description: 'load once and serve; do not watch for changes' },
+    },
+    run: async ({ positionals, options }) => {
+        const [entry] = positionals;
+        if (entry === undefined)
+            throw new Error('an entry file is required');
+        const [{ dev }, { processRuntime }] = await Promise.all([import('./dev.js'), import('./runtime.js')]);
+        const handle = dev({ entry, input: processRuntime.stdin, output: processRuntime.stdout, log: processRuntime.stderr, watch: options['no-watch'] !== true });
+        await handle.done;
+    },
+});
 export const program = defineProgram({
     name: 'burgee',
     description: 'The agent-native CLI framework, and the tools that come with it',
-    commands: [brandCommand],
+    commands: [brandCommand, devCommand],
 });
 run(program);

package/dist/commander-command.d.ts

@@ -127,6 +127,9 @@ export declare class Command extends EventEmitter {
     _manifest: Manifest | undefined;
     /** burgee: what this command does to the world (N6); declaring it exposes the command as an MCP tool. */
     _effects: Effects | undefined;
+    /** burgee: `true`, or the replacement's name (M5). Shown in help, schema and a one-line warning on use. */
+    _deprecated: boolean | string | undefined;
+    _deprecationWarned: boolean;
     /** burgee: set for the duration of a parse that injected the streams or the exit. */
     _burgee: Burgee | undefined;
     constructor(name?: string);
@@ -313,6 +316,11 @@ export declare class Command extends EventEmitter {
     _optionSpecs(): Record<string, OptionSpec>;
     /** burgee: declare what the command does to the world (N6). This is what exposes it as an MCP tool (N2). */
     effects(value: Effects): this;
+    /**
+     * burgee: mark the command deprecated (M5). Help and `--schema` show it; running it prints
+     * `warning: 'old' is deprecated, use 'new'` on stderr once and goes on, exit unchanged.
+     */
+    deprecate(use?: string): this;
     /**
      * burgee: `--schema` and `--mcp` on a commander-syntax program, from its manifest (J2).
      * Only when the program declares neither option itself; `--mcp` runs commands through
@@ -331,6 +339,8 @@ export declare class Command extends EventEmitter {
     _takeJson(unknown: string[]): void;
     /** The action, wrapped in the plugin hooks and followed by the envelope or the rendering. */
     _runAction(): unknown;
+    /** burgee (M5): once per process, on stderr; only for a command that asked, so commander's own output is untouched. */
+    _warnDeprecated(): void;
     /** burgee: where every option value came from, from commander's own value sources (V3). */
     _provenance(): Record<string, {
         source: string;

package/dist/commander-command.js

@@ -98,6 +98,8 @@ export class Command extends EventEmitter {
     _usage = undefined;
     _manifest = undefined;
     _effects = undefined;
+    _deprecated = undefined;
+    _deprecationWarned = false;
     _burgee = undefined;
     constructor(name) {
         super();
@@ -1375,6 +1377,8 @@ Expecting one of '${HELP_POSITIONS.join("', '")}'`);
                 ...(cmd._description ? { description: cmd._description } : {}),
                 ...(cmd._summary ? { summary: cmd._summary } : {}),
                 ...(cmd._effects === undefined ? {} : { effects: cmd._effects }),
+                ...(cmd._deprecated === undefined ? {} : { deprecated: cmd._deprecated }),
+                ...(cmd._helpGroupHeading === undefined || cmd._helpGroupHeading === '' ? {} : { group: cmd._helpGroupHeading }),
                 ...(cmd._hidden ? { hidden: true } : {}),
                 options: cmd._optionSpecs(),
                 arguments: cmd.registeredArguments.map((a) => ({ name: a.name(), required: a.required, variadic: a.variadic, ...(a.description ? { description: a.description } : {}) })),
@@ -1407,6 +1411,10 @@ Expecting one of '${HELP_POSITIONS.join("', '")}'`);
         this._effects = value;
         return this;
     }
+    deprecate(use) {
+        this._deprecated = use ?? true;
+        return this;
+    }
     _burgeeSurface(userArgs) {
         const root = this._root();
         const declared = (flag, at = root) => at._findOption(flag) !== undefined || at.commands.some((sub) => declared(flag, sub));
@@ -1529,6 +1537,7 @@ Expecting one of '${HELP_POSITIONS.join("', '")}'`);
         const handler = this._actionHandler;
         if (handler === null)
             return undefined;
+        this._warnDeprecated();
         const root = this._root();
         const manifest = root._manifest;
         const settle = (value) => this._emitResult(value);
@@ -1546,6 +1555,13 @@ Expecting one of '${HELP_POSITIONS.join("', '")}'`);
             settle(value);
         });
     }
+    _warnDeprecated() {
+        if (this._deprecated === undefined || this._deprecated === false || this._deprecationWarned)
+            return;
+        this._deprecationWarned = true;
+        const use = typeof this._deprecated === 'string' ? `, use '${this._deprecated}'` : '';
+        this._outputConfiguration.writeErr(`warning: '${this.name()}' is deprecated${use}\n`);
+    }
     _provenance() {
         const out = {};
         const names = { cli: 'flag', env: 'env', config: 'config', default: 'default', implied: 'implied' };

package/dist/dev.d.ts

@@ -0,0 +1,47 @@
+import { Manifest } from './manifest.js';
+import { type Invoke } from './mcp.js';
+export interface Writer {
+    write: (s: string) => unknown;
+}
+export interface DevOptions {
+    /** The module that exports the program: `program` (or `default`) as a burgee manifest, a commander `Command` or a yargs instance. */
+    entry: string;
+    /** The MCP channel. */
+    input: NodeJS.ReadableStream;
+    output: Writer;
+    /** Where the reload report goes: never stdout, which carries MCP. */
+    log: Writer;
+    /** Off for tests that drive `reload()` themselves. */
+    watch?: boolean;
+    /** Files changed within this window coalesce into one reload. */
+    debounceMs?: number;
+}
+export interface Loaded {
+    manifest: Manifest;
+    invoke: Invoke;
+    kind: 'burgee' | 'commander' | 'yargs';
+    /** Milliseconds from the trigger to the manifest being served (W6). */
+    ms: number;
+}
+export interface DevHandle {
+    ready: Promise<Loaded>;
+    /** Re-import the entry, print the diff and the help, swap the served manifest. */
+    reload: () => Promise<Loaded>;
+    /** Settles when the MCP input closes. */
+    done: Promise<void>;
+    close: () => void;
+}
+/**
+ * Import the entry as a fresh module graph. The query is what discards the previous
+ * graph: the same URL would hand back the cached module and its stale handlers.
+ */
+export declare function load(entry: string, generation: number): Promise<Loaded>;
+/** What changed between two manifests, by command path: added, removed, or a different schema. */
+export declare function diffManifests(before: Manifest | undefined, after: Manifest): {
+    added: string[];
+    removed: string[];
+    changed: string[];
+};
+/** The reload report: one save, every surface (W3). */
+export declare function report(before: Manifest | undefined, loaded: Loaded): string;
+export declare function dev(opts: DevOptions): DevHandle;

package/dist/dev.js

@@ -0,0 +1,132 @@
+import { watch } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { execute } from './execute.js';
+import { renderHelp } from './help.js';
+import { Manifest } from './manifest.js';
+import { startMcp, toolsOf } from './mcp.js';
+import { commandSchemaOf } from './schema.js';
+const DEFAULT_DEBOUNCE_MS = 50;
+const SOURCE = /\.(m?[jt]s|c[jt]s|json)$/;
+const isObject = (x) => x !== null && x !== undefined && typeof x === 'object' && !Array.isArray(x);
+function isManifest(x) {
+    return x instanceof Manifest || (isObject(x) && Array.isArray(x['commands']) && Array.isArray(x['rootPath']));
+}
+function isYargs(x) {
+    return isObject(x) && typeof x['burgee'] === 'function' && isObject(x['manifest']);
+}
+function isCommander(x) {
+    return isObject(x) && typeof x['parseAsync'] === 'function' && isObject(x['manifest']);
+}
+function invokeOn(program, kind, entry) {
+    return async (argv) => {
+        const out = [];
+        const err = [];
+        let code = 0;
+        const seam = { stdout: { write: (s) => out.push(s) }, stderr: { write: (s) => err.push(s) }, exit: (c) => void (code = c) };
+        if (kind === 'burgee')
+            await execute(program, { argv, from: 'user', entry, ...seam });
+        else if (kind === 'yargs')
+            await program.burgee(seam).parseAsync(argv);
+        else
+            await program.parseAsync(argv, { from: 'user', ...seam });
+        return { stdout: out.join(''), stderr: err.join(''), code };
+    };
+}
+export async function load(entry, generation) {
+    const started = performance.now();
+    const url = pathToFileURL(resolve(entry));
+    url.searchParams.set('burgee-dev', String(generation));
+    const mod = (await import(url.href));
+    const exported = mod['program'] ?? mod['default'];
+    if (isManifest(exported))
+        return { manifest: exported, invoke: invokeOn(exported, 'burgee', entry), kind: 'burgee', ms: performance.now() - started };
+    if (isYargs(exported))
+        return { manifest: exported.manifest, invoke: invokeOn(exported, 'yargs', entry), kind: 'yargs', ms: performance.now() - started };
+    if (isCommander(exported))
+        return { manifest: exported.manifest, invoke: invokeOn(exported, 'commander', entry), kind: 'commander', ms: performance.now() - started };
+    throw new Error(`${entry} exports no program: export a burgee manifest, a commander Command or a yargs instance as \`program\` or default`);
+}
+const schemasByPath = (m) => new Map(m.commands.map((c) => [c.path.join(' '), JSON.stringify(commandSchemaOf(c, m.rootPath))]));
+export function diffManifests(before, after) {
+    const was = before === undefined ? new Map() : schemasByPath(before);
+    const now = schemasByPath(after);
+    return {
+        added: [...now.keys()].filter((k) => !was.has(k)),
+        removed: [...was.keys()].filter((k) => !now.has(k)),
+        changed: [...now.keys()].filter((k) => was.has(k) && was.get(k) !== now.get(k)),
+    };
+}
+export function report(before, loaded) {
+    const { manifest } = loaded;
+    const diff = diffManifests(before, manifest);
+    const lines = [];
+    lines.push(`${before === undefined ? 'loaded' : 'reloaded'} ${manifest.rootPath.join(' ')} (${loaded.kind}) in ${loaded.ms.toFixed(0)} ms — ${manifest.commands.length} commands, ${toolsOf(manifest).length} MCP tools`);
+    for (const p of diff.added)
+        lines.push(`  + ${p}`);
+    for (const p of diff.removed)
+        lines.push(`  - ${p}`);
+    for (const p of diff.changed)
+        lines.push(`  ~ ${p}`);
+    const root = manifest.find(manifest.rootPath);
+    if (root !== undefined)
+        lines.push('', renderHelp(manifest, root).trimEnd());
+    return `${lines.join('\n')}\n`;
+}
+export function dev(opts) {
+    let generation = 0;
+    let current;
+    let server;
+    let watcher;
+    let timer;
+    let chain = Promise.resolve();
+    const entry = resolve(opts.entry);
+    const reloadNow = async () => {
+        generation += 1;
+        const loaded = await load(entry, generation);
+        opts.log.write(report(current, loaded));
+        current = loaded.manifest;
+        if (server === undefined)
+            server = startMcp(loaded.manifest, { input: opts.input, output: opts.output, invoke: loaded.invoke });
+        else
+            server.swap(loaded.manifest, loaded.invoke);
+        return loaded;
+    };
+    const reload = async () => {
+        await chain;
+        const next = reloadNow();
+        chain = next.catch((err) => {
+            opts.log.write(`reload failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        });
+        return await next;
+    };
+    const ready = reload();
+    if (opts.watch !== false) {
+        watcher = watch(dirname(entry), { recursive: true }, (_event, filename) => {
+            const name = filename === null ? '' : String(filename);
+            if (name !== '' && (!SOURCE.test(name) || name.includes('node_modules')))
+                return;
+            clearTimeout(timer);
+            timer = setTimeout(() => void reload().catch(() => undefined), opts.debounceMs ?? DEFAULT_DEBOUNCE_MS);
+        });
+    }
+    const untilInputCloses = async () => {
+        try {
+            await ready;
+            await server.done;
+        }
+        finally {
+            watcher?.close();
+        }
+    };
+    const done = untilInputCloses();
+    return {
+        ready,
+        reload,
+        done,
+        close: () => {
+            clearTimeout(timer);
+            watcher?.close();
+        },
+    };
+}

package/dist/execute.d.ts

@@ -1,4 +1,4 @@
-import { type ArgumentSpec, type Effects, type Example, Manifest, type OptionSpec, type Relation, type RunContext } from './manifest.js';
+import { type ArgumentSpec, type CommandNode, type Effects, type Example, type LazyModule, Manifest, type OptionSpec, type Relation, type RunContext } from './manifest.js';
 export interface CommandContext<O> extends Omit<RunContext, 'options'> {
     options: O;
 }
@@ -39,6 +39,8 @@ export interface Command<S extends OptionSpecs = OptionSpecs> {
     relations?: readonly Relation[];
     /** Absent on a group that only holds subcommands. `NoInfer`: the spec fixes S, the handler only reads it. */
     run?: (ctx: CommandContext<InferOptions<NoInfer<S>>>) => unknown;
+    /** The handler's module, imported on dispatch only (M2); everything else about the command is declared here. */
+    load?: () => Promise<LazyModule>;
     commands?: AnyCommand[];
 }
 export interface Program {
@@ -59,6 +61,13 @@ export interface Program {
     commands: AnyCommand[];
 }
 export declare function defineCommand<const S extends OptionSpecs = OptionSpecs>(command: Command<S>): Command<S>;
+/**
+ * Options declared once and spread into each command that takes them (M4): never global,
+ * so `--schema` stays a tree and each command's help lists them as its own, and the
+ * handler's `options` type carries them like any other. Every copy is tagged
+ * `sharedFrom` with the set's name, so the schema says where it came from.
+ */
+export declare function sharedOptions<const T extends OptionSpecs>(name: string, specs: T): T;
 /** A native multi-command program. The manifest it builds is the same one the façades fill. */
 export declare function defineProgram(program: Program): Manifest;
 export interface RunOptions {
@@ -89,6 +98,18 @@ export declare function execute(manifest: Manifest, opts?: RunOptions & {
     root?: string[];
     from?: 'node' | 'user';
 }): Promise<void>;
+/** M6: which command argv names, or null — the same longest-prefix match `execute` uses. */
+export declare function resolveCommand(manifest: Manifest, argv: readonly string[]): CommandNode | null;
+export interface RunResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * M6: run a command programmatically — the harness's own entry, public. The streams are
+ * captured, the exit recorded; env, cwd and the entry can be injected like `execute`'s.
+ */
+export declare function runCommand(manifest: Manifest, argv: readonly string[], opts?: Pick<RunOptions, 'env' | 'cwd' | 'entry' | 'stdin'>): Promise<RunResult>;
 /**
  * The one-file entry: a single command, or a program from `defineProgram`. Both go
  * through `execute`, so there is exactly one code path from argv to exit.

package/dist/execute.js

@@ -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];
@@ -342,6 +346,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 +359,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);
@@ -418,6 +443,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[];

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) {

package/dist/testing-helpers.d.ts

@@ -8,7 +8,7 @@
 import { Readable } from 'node:stream';
 import { ExitCode } from './exit-code.js';
 import { type Manifest } from './manifest.js';
-import { type Runtime } from './runtime.js';
+import { type Clock, type Runtime } from './runtime.js';
 export interface RunOptions {
     argv: string[];
     env?: Record<string, string>;
@@ -16,6 +16,8 @@ export interface RunOptions {
     cwd?: string;
     /** `true` = every stream is a TTY; an object sets each; default: none is. */
     tty?: boolean | Partial<Runtime['isTTY']>;
+    /** The clock the runtime reports; a fresh `fakeClock()` at 0 when not given. */
+    clock?: FakeClock;
 }
 export interface RunResult {
     code: ExitCode;
@@ -33,7 +35,22 @@ export declare class RuntimeExit extends Error {
 export interface FakeRuntime extends Runtime {
     out: string[];
     err: string[];
+    clock: FakeClock;
 }
+/** A `Clock` that moves only when the test says so (R14): `tick` is the only source of time. */
+export interface FakeClock extends Clock {
+    /**
+     * Advance by `ms`, running every callback that falls due, earliest first, then by order
+     * scheduled. A callback that schedules inside the window runs in the same tick, so one that
+     * reschedules itself at `0` would never leave the loop (real Node yields between turns);
+     * a tick runs at most `TICK_CAP` callbacks and throws, naming the cap, when exceeded.
+     */
+    tick(ms: number): void;
+    /** Callbacks scheduled and neither run nor cancelled. */
+    pending(): number;
+}
+/** Deterministic time for the harness. Starts at `start` (0 by default) and never moves on its own. */
+export declare function fakeClock(start?: number): FakeClock;
 /** A `Runtime` whose every part is under the test's control. */
 export declare function fakeRuntime(opts: RunOptions): FakeRuntime;
 export declare function swapEnv(env: Record<string, string> | undefined): () => void;

package/dist/testing-helpers.js

@@ -9,6 +9,40 @@ export class RuntimeExit extends Error {
         this.name = 'RuntimeExit';
     }
 }
+const TICK_CAP = 1000;
+export function fakeClock(start = 0) {
+    let now = start;
+    let nextId = 0;
+    const timers = [];
+    const remove = (id) => {
+        const at = timers.findIndex((t) => t.id === id);
+        if (at !== -1)
+            timers.splice(at, 1);
+    };
+    return {
+        now: () => now,
+        schedule(fn, ms) {
+            const id = nextId++;
+            timers.push({ id, at: now + Math.max(0, ms), fn });
+            return () => remove(id);
+        },
+        tick(ms) {
+            const until = now + ms;
+            const nextDue = () => timers.filter((t) => t.at <= until).sort((a, b) => a.at - b.at || a.id - b.id)[0];
+            let ran = 0;
+            for (let due = nextDue(); due !== undefined; due = nextDue()) {
+                if (ran === TICK_CAP)
+                    throw new Error(`fakeClock.tick(${ms}) ran ${TICK_CAP} callbacks (TICK_CAP): a callback keeps rescheduling inside the window`);
+                ran += 1;
+                remove(due.id);
+                now = Math.max(now, due.at);
+                due.fn();
+            }
+            now = until;
+        },
+        pending: () => timers.length,
+    };
+}
 function ttyOf(tty) {
     if (tty === true)
         return { stdin: true, stdout: true, stderr: true };
@@ -31,6 +65,7 @@ export function fakeRuntime(opts) {
         exit(code) {
             throw new RuntimeExit(code);
         },
+        clock: opts.clock ?? fakeClock(),
         out,
         err,
     };

package/dist/testing.d.ts

@@ -5,6 +5,6 @@
  * A separate entry point so it is paid for per import (K6): a user's shipped CLI
  * imports `burgee` and never pulls a byte of this.
  */
-export { processRuntime, type Runtime, type Writer } from './runtime.js';
-export { captureConsole, codeOf, fakeRuntime, finish, runBurgee, RuntimeExit, stripAnsi, swapEnv, type FakeRuntime, type RunOptions, type RunResult, } from './testing-helpers.js';
+export { processRuntime, type Clock, type Runtime, type Writer } from './runtime.js';
+export { captureConsole, codeOf, fakeClock, fakeRuntime, finish, runBurgee, RuntimeExit, stripAnsi, swapEnv, type FakeClock, type FakeRuntime, type RunOptions, type RunResult, } from './testing-helpers.js';
 export { ExitCode, isExitCode, type ExitCode as ExitCodeValue } from './exit-code.js';

package/dist/testing.js

@@ -1,3 +1,3 @@
 export { processRuntime } from './runtime.js';
-export { captureConsole, codeOf, fakeRuntime, finish, runBurgee, RuntimeExit, stripAnsi, swapEnv, } from './testing-helpers.js';
+export { captureConsole, codeOf, fakeClock, fakeRuntime, finish, runBurgee, RuntimeExit, stripAnsi, swapEnv, } from './testing-helpers.js';
 export { ExitCode, isExitCode } from './exit-code.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "burgee",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "An agent-native CLI framework, drop-in compatible with commander and yargs. One declaration; help, --json, --schema, --mcp and completions all projected from it.",
   "license": "MIT",
   "type": "module",
@@ -95,7 +95,7 @@
     "provenance": true
   },
   "devDependencies": {
-    "vitest": "^4.0.0"
+    "vitest": "^5.0.0"
   },
   "bin": {
     "burgee": "./dist/cli.js"