burgee 0.6.0 → 0.7.0

package/dist/execute.js

@@ -1,15 +1,18 @@
 import { dirname } from 'node:path';
 import { parseArgs } from 'node:util';
-import { ConfigError, explain, resolve as resolveLayers } from 'seniority';
+import { ConfigError, explain, 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 } from './manifest.js';
+import { Manifest, relationsOf } from './manifest.js';
 import { serveMcp } from './mcp.js';
 import { camel, kebab } from './names.js';
 import { nearestPackage } from './pkg.js';
-import { commandSchemaOf, machineJson, schemaOf, summaryOf } from './schema.js';
-import { checkDefinition, checkRelations, coerce, UsageError } from './validate.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';
 function helpFields(c) {
     const node = {};
     if (c.description !== undefined)
@@ -34,13 +37,8 @@ function helpFields(c) {
         node.relations = c.relations;
     return node;
 }
-const RESERVED = new Set(['json', 'help', 'schema', 'mcp', 'version', 'explain']);
 export function defineCommand(command) {
-    for (const name of Object.keys(command.options ?? {})) {
-        if (RESERVED.has(name) || RESERVED.has(kebab(name)))
-            throw new Error(`burgee: option "${name}" is reserved and cannot be redefined`);
-    }
-    checkDefinition(command.name, command.options ?? {});
+    checkCommand(command.name, command.options ?? {}, command.effects, command.run !== undefined || command.load !== undefined);
     return command;
 }
 function addTree(manifest, parent, commands) {
@@ -94,6 +92,9 @@ class ExitSignal extends Error {
         this.code = code;
     }
 }
+const ctxExit = (code) => {
+    throw new ExitSignal(code);
+};
 function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -159,7 +160,7 @@ function packageLayer(pkg, name) {
     return typeof field === 'object' && field !== null && !Array.isArray(field) ? { path: pkg.path, data: field } : undefined;
 }
 async function configLayers(name, values, io) {
-    const { discover } = await import('seniority');
+    const { discover } = await import('seniority/config');
     const explicit = values['config'];
     const disabled = values['noConfig'] === true;
     const loaded = await discover({ name, cwd: io.cwd, env: io.env, ...(typeof explicit === 'string' ? { explicit } : {}), disabled });
@@ -238,19 +239,35 @@ async function describeFailure(cause, argv, node) {
 }
 function textFailure(failure) {
     const hint = failure.hint === undefined ? '' : `hint: ${failure.hint}\n`;
+    const fix = failure.fix === undefined ? '' : `fix: ${failure.fix}\n`;
     if (failure.action !== undefined) {
         const next = (failure.action.next ?? []).map((n) => `  ${n.command}    ${n.when}\n`).join('');
         return `action required (${failure.action.reason}): ${failure.message}\n${next === '' ? '' : `next:\n${next}`}${hint}`;
     }
-    return `error: ${failure.message}\n${hint}`;
+    return `error: ${failure.message}\n${hint}${fix}`;
 }
 function runnableNext(manifest, spec, json) {
     const program = manifest.rootPath.join(' ');
     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) {
+    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(' '))
+        .map((c) => typedName(c, root));
+    return {
+        schemaVersion: 1,
+        ...commandSchemaOf(node, root),
+        ...(children.length === 0 ? {} : { commands: children }),
+    };
+}
 const HELP_WIDTH = 100;
-const processExit = (code) => process.exit(code);
+const processExit = (code) => host.exit(code);
+async function leave(io, code) {
+    await io.teardown.run(code);
+    io.exit(code);
+}
 export function beforeTerminator(argv) {
     const at = argv.indexOf('--');
     return at === -1 ? argv : argv.slice(0, at);
@@ -262,8 +279,11 @@ 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 (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 };
+    }
     if (first === '--version' || first === '-V')
         return { text: `${versionOf(manifest, io)}\n`, code: ExitCode.OK };
     if (typed.length === 0)
@@ -350,6 +370,8 @@ 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, node.options, parsed.tokens);
     const json = flags.json === true;
+    if (flags.help === true && json)
+        return { json, text: `${machineJson(helpDocumentOf(manifest, node), json ? ['--json'] : [])}\n` };
     if (flags.help === true)
         return { json, text: renderHelp(manifest, node, { width: io.width }) };
     if (flags.version === true)
@@ -358,18 +380,15 @@ async function dispatch(manifest, { node, rest, name }, io) {
     if (resolved.explainText !== undefined)
         return { json, text: resolved.explainText };
     const { provenance } = resolved;
-    checkRelations(node.relations, resolved.values, provenance);
+    checkRelations(relationsOf(node), 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);
-        throw new ExitSignal(code);
-    };
     const detection = detectAgent(io.env, io.tty);
-    const data = await node.run({ options: values, positionals, passthrough, env: io.env, exit, actionRequired, ...detection });
+    const onExit = (handler, label) => io.teardown.add(handler, label);
+    const data = await node.run({ options: values, positionals, passthrough, env: io.env, exit: ctxExit, onExit, actionRequired, ...detection });
     await manifest.fire('postRun', name, values);
     const changed = changedOf(node, data);
     return { json, data, provenance, ...(changed === undefined ? {} : { changed }) };
@@ -393,66 +412,67 @@ function warnDeprecated(node, io) {
     const use = typeof node.deprecated === 'string' ? `, use '${node.deprecated}'` : '';
     io.err.write(`warning: '${typed}' is deprecated${use}\n`);
 }
-function emit(io, outcome) {
+async function emit(io, outcome) {
     if (outcome.text !== undefined) {
         io.out.write(outcome.text);
-        return io.exit(ExitCode.OK);
+        return await leave(io, ExitCode.OK);
     }
     const meta = { provenance: outcome.provenance ?? {}, ...(outcome.changed === undefined ? {} : { changed: outcome.changed }) };
     const envelope = { ok: true, data: outcome.data, meta };
     io.out.write(outcome.json ? `${JSON.stringify(envelope)}\n` : `${render(outcome.data)}\n`);
-    return io.exit(ExitCode.OK);
+    return await leave(io, ExitCode.OK);
 }
 async function report(cause, { manifest, io, argv, json, name }) {
     const failure = await describeFailure(cause, argv, resolveCommand(manifest, argv) ?? undefined);
     if (failure.silent === true)
-        return io.exit(failure.code);
+        return await leave(io, failure.code);
     await manifest.fire('onError', name, {});
     if (failure.action !== undefined) {
         const next = runnableNext(manifest, failure.action, json);
         const rendered = { ...failure, action: { ...failure.action, next } };
         const body = { ok: false, status: 'action_required', reason: failure.action.reason, message: failure.message, next, hint: failure.hint, error: { code: failure.code, message: failure.message } };
         io.err.write(json ? `${JSON.stringify(body)}\n` : textFailure(rendered));
-        return io.exit(failure.code);
+        return await leave(io, failure.code);
     }
-    const body = { code: failure.code, message: failure.message, hint: failure.hint };
+    const body = { code: failure.code, message: failure.message, hint: failure.hint, ...(failure.fix === undefined ? {} : { fix: failure.fix }) };
     io.err.write(json ? `${JSON.stringify({ ok: false, error: body })}\n` : textFailure(failure));
-    return io.exit(failure.code);
+    return await leave(io, failure.code);
 }
 function ioOf(opts) {
-    const out = opts.stdout ?? process.stdout;
+    const out = opts.stdout ?? host.stdout;
     return {
         out,
-        err: opts.stderr ?? process.stderr,
-        env: opts.env ?? process.env,
+        err: opts.stderr ?? host.stderr,
+        env: opts.env ?? host.env,
         exit: opts.exit ?? processExit,
         width: out.columns ?? HELP_WIDTH,
-        stdin: opts.stdin ?? process.stdin,
-        cwd: opts.cwd ?? process.cwd(),
-        pkg: nearestPackage(dirname(opts.entry ?? process.argv[1] ?? process.cwd())),
+        stdin: opts.stdin ?? host.stdin,
+        cwd: opts.cwd ?? host.cwd(),
+        pkg: nearestPackage(dirname(opts.entry ?? host.argv[1] ?? host.cwd())),
         tty: out.isTTY === true,
+        teardown: opts.exit === undefined ? processTeardown([host.stdout, host.stderr]) : detachedTeardown(),
     };
 }
 export async function execute(manifest, opts = {}) {
     const io = ioOf(opts);
-    const raw = opts.argv ?? process.argv;
+    const raw = opts.argv ?? host.argv;
     const argv = opts.argv === undefined || opts.from === 'node' ? raw.slice(2) : raw;
     const root = opts.root ?? manifest.rootPath;
     let json = beforeTerminator(argv).includes('--json');
     let name = '';
     try {
         if (await surface(manifest, argv, io))
-            return io.exit(ExitCode.OK);
+            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);
             (code === ExitCode.OK ? io.out : io.err).write(text);
-            return io.exit(code);
+            return await leave(io, code);
         }
         name = node.path.slice(root.length).join(' ');
         const outcome = await dispatch(manifest, { node: node, rest, name }, io);
         json = outcome.json;
-        return emit(io, outcome);
+        return await emit(io, outcome);
     }
     catch (cause) {
         return await report(cause, { manifest, io, argv, json, name });

package/dist/help.d.ts

@@ -24,7 +24,12 @@ export interface HelpOptions {
      */
     theme?: HelpTheme;
 }
-/** Word-wrap one paragraph; lines the author indented are kept verbatim (yargs #2120). */
+/**
+ * Word-wrap one paragraph; lines the author indented are kept verbatim (yargs #2120).
+ *
+ * The running `used` is the width of `current` in columns, carried rather than recomputed:
+ * measuring the accumulated line once per word would make a long paragraph quadratic.
+ */
 export declare function wrap(text: string, width: number): string[];
 /**
  * Render help for one node — a runnable command, a group, or both — as text.

package/dist/help.js

@@ -1,5 +1,6 @@
 import { styleText } from 'node:util';
-import { kebab } from './names.js';
+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 };
 const DEFAULTS = {
@@ -47,6 +48,10 @@ function annotate(text, spec, verbose) {
         parts.push(`(one of: ${spec.choices.join(', ')})`);
     if (spec.multiple === true)
         parts.push('(repeatable)');
+    if (spec.dependsOn !== undefined && spec.dependsOn.length > 0)
+        parts.push(`(requires ${flagsOf(spec.dependsOn).join(', ')})`);
+    if (spec.exclusive !== undefined && spec.exclusive.length > 0)
+        parts.push(`(conflicts with ${flagsOf(spec.exclusive).join(', ')})`);
     if (spec.env !== undefined)
         parts.push(`[env: ${spec.env}]`);
     if (verbose)
@@ -108,26 +113,38 @@ function usageLine(node, root, hasChildren, paint) {
 export function wrap(text, width) {
     const out = [];
     for (const line of text.split('\n')) {
-        if (/^\s/.test(line) || line.length <= width) {
+        if (/^\s/.test(line) || displayWidth(line) <= width)
             out.push(line);
-            continue;
+        else
+            out.push(...wrapLine(line, width));
+    }
+    return out;
+}
+function wrapLine(line, width) {
+    const rows = [];
+    let current = '';
+    let used = 0;
+    for (const word of line.split(' ')) {
+        const w = displayWidth(word);
+        if (current === '') {
+            current = word;
+            used = w;
+        }
+        else if (used + 1 + w > width) {
+            rows.push(current);
+            current = word;
+            used = w;
         }
-        let current = '';
-        for (const word of line.split(' ')) {
-            if (current !== '' && current.length + 1 + word.length > width) {
-                out.push(current);
-                current = word;
-            }
-            else
-                current = current === '' ? word : `${current} ${word}`;
+        else {
+            current = `${current} ${word}`;
+            used += 1 + w;
         }
-        out.push(current);
     }
-    return out;
+    rows.push(current);
+    return rows;
 }
 function termColumn(rows, width) {
-    const longest = Math.max(0, ...rows.map((r) => r.term.length));
-    return Math.min(longest, Math.floor(width * TERM_SHARE));
+    return Math.min(widest(rows.map((r) => r.term)), Math.floor(width * TERM_SHARE));
 }
 function layout(rows, width, column, paint) {
     const textWidth = Math.max(1, width - INDENT.length - column - GUTTER);
@@ -140,11 +157,12 @@ function layout(rows, width, column, paint) {
         }
         const wrapped = wrap(text, textWidth);
         const continuation = INDENT + ' '.repeat(column + GUTTER);
-        if (term.length > column) {
+        const termWidth = displayWidth(term);
+        if (termWidth > column) {
             lines.push(`${INDENT}${cell}`, ...wrapped.map((l) => `${continuation}${l}`));
             continue;
         }
-        const pad = ' '.repeat(column + GUTTER - term.length);
+        const pad = ' '.repeat(column + GUTTER - termWidth);
         lines.push(`${INDENT}${cell}${pad}${wrapped[0] ?? ''}`, ...wrapped.slice(1).map((l) => `${continuation}${l}`));
     }
     return lines;

package/dist/index.d.ts

@@ -7,10 +7,12 @@
  */
 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 { camel, checkDefinition, kebab, UsageError } from './validate.js';
+export { checkCommand, checkDefinition } from './definition.js';
+export { 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';
+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 { 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';
+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';

package/dist/index.js

@@ -1,9 +1,11 @@
 export { ExitCode, isExitCode } from './exit-code.js';
 export { defineCommand, defineProgram, execute, resolveCommand, run, runCommand, sharedOptions, } from './execute.js';
-export { camel, checkDefinition, kebab, UsageError } from './validate.js';
+export { checkCommand, checkDefinition } from './definition.js';
+export { 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';
+export { ConfigError, envName, explain, resolve, screaming } from 'seniority/precedence';
 export { commandSchemaOf, inputSchemaOf, schemaOf, summaryOf } from './schema.js';
-export { definePlugin, Manifest, } from './manifest.js';
+export { CONTRACT, definePlugin, PluginError } from './plugin.js';
+export { Manifest, } from './manifest.js';

package/dist/manifest.d.ts

@@ -4,7 +4,12 @@
  * Commands reach it through a façade (`burgee/commander`, `burgee/yargs`) or
  * natively, and it does not record which. That is the whole reason a plugin
  * written once works on every rung of the adoption ladder (J7, J8).
+ *
+ * The plugin *shape* and its refusals live in `./plugin.js`, which is this package's host in
+ * the sense `plugin-contract` means: one file per package owning `Plugin`, `validate()` and
+ * the error vocabulary. `use()` below is burgee's `register()`.
  */
+import { type Plugin } from './plugin.js';
 /**
  * The Standard Schema interface (standardschema.dev), declared here so any implementation
  * — zod, valibot, arktype — is accepted as an option's `schema` without a dependency (S1).
@@ -42,6 +47,26 @@ export interface OptionSpec {
     /** Repeatable, and split on `separator` (`,` unless declared): `--tag a --tag b,c` → `['a', 'b', 'c']` (S8). */
     multiple?: boolean;
     separator?: string;
+    /**
+     * The other options this one requires: `--out --dependsOn force` is a usage error without
+     * `--force` (S2). Sugar for a `{ implies: [this, other] }` relation per name, and nothing
+     * else — one engine, one order, one error vocabulary.
+     *
+     * It exists as a second spelling because the first states the constraint away from the
+     * option it constrains: a reader looking at `out` learns nothing from a `relations` entry
+     * three keys down, and neither does the help line for `--out`. Both incumbents spell it on
+     * the option (commander `.implies()`, yargs `.implies()`), and so does Fig, whose `Option`
+     * declares this exact key.
+     */
+    dependsOn?: readonly string[];
+    /**
+     * The other options this one may not be given with (S2): `{ conflicts: [this, other] }` per
+     * name. Commander's `.conflicts()`, yargs' `.conflicts()`, Fig's `exclusiveOn`.
+     *
+     * One-sided is enough — the relation it compiles to holds whichever of the two argv names
+     * first — so declare it once, on whichever option the constraint belongs to.
+     */
+    exclusive?: readonly string[];
     /** `number` only. */
     minimum?: number;
     maximum?: number;
@@ -68,6 +93,25 @@ export interface LazyModule {
  * to true, so silence is the dangerous reading.
  */
 export type Effects = 'read_only' | 'idempotent' | 'non_idempotent';
+/**
+ * What a command may declare under `effects`: one of the three above, or `'withheld'`.
+ *
+ * `'withheld'` is not an effect and is deliberately not spelled like one. It answers a
+ * different question — *may an agent call this?* — and it exists because the two questions
+ * used to share one absence. `effects: undefined` meant both "I decided agents should not
+ * have this" and "I forgot", and the second is the one that ships: the tool an author built
+ * for an agent was simply not in `tools/list`, and nothing said so (N6).
+ *
+ * It is not `'none'`, which reads as *this command has no effects* — which is `read_only`,
+ * the one value it could be confused with and the one confusion that would matter. Nor is it
+ * a second field: a boolean beside a now-required `effects` would mean that declaring what a
+ * command does to the world silently opts it in, and the default for *that* field would be
+ * the silence this change exists to remove. One field, four answers, no default.
+ *
+ * {@link Effects} stays the three, because `annotationsOf` is total on them: a withheld
+ * command has no hints, because it has no tool.
+ */
+export type DeclaredEffects = Effects | 'withheld';
 /**
  * A relationship between options, validated after parsing and before choices and the
  * handler (S2, S6). `implies` takes a second option name, or a predicate over the values.
@@ -83,6 +127,22 @@ export type Relation = {
 } | {
     implies: readonly [string, string | ((values: Record<string, unknown>) => boolean)];
 };
+/**
+ * The option-level `dependsOn` / `exclusive` of {@link OptionSpec}, as the `Relation` union
+ * the engine already enforces. Declaration order, options then their names, so two runs of
+ * the same manifest publish the same list.
+ */
+export declare function optionRelations(options: Record<string, OptionSpec>): Relation[];
+/**
+ * Every constraint on a command, from wherever it was declared: the command's own
+ * `relations` first, then the ones its options spell on themselves.
+ *
+ * One function because there must be one answer. `validate.ts` enforces this list and
+ * `schema.ts` publishes it, and a surface that computed its own would be the defect
+ * `relations-schema.test.ts` was written for — an agent learning a constraint by being
+ * refused, one round trip at a time.
+ */
+export declare function relationsOf(node: Pick<CommandNode, 'options' | 'relations'>): Relation[];
 /** A positional, as help documents it (yargs #2012). */
 export interface ArgumentSpec {
     name: string;
@@ -122,6 +182,20 @@ export interface RunContext {
     agent?: string;
     /** Stop and tell the caller what to do instead of blocking on a prompt (N11). */
     actionRequired: (spec: ActionRequiredSpec) => never;
+    /**
+     * Cleanup that runs on **every** path out of the run (E5): a normal return, `ctx.exit`,
+     * Ctrl-C, SIGTERM, a terminal closing, an uncaught throw. Returns the function that
+     * unregisters it, for a command that cleaned up on its own.
+     *
+     * The handler runs after stdout has been drained (O5) and before the terminal is handed
+     * back, and it runs exactly once however many of those arrive together. `label` is what a
+     * breached shutdown deadline calls it; without one an arrow is reported as `(anonymous)`,
+     * and the anonymous arrow is the shape that hangs.
+     *
+     * Typed here rather than re-exported from `closeout`, so a command's signature does not
+     * change when that package's does.
+     */
+    onExit: (handler: () => void | Promise<void>, label?: string) => () => void;
 }
 export interface CommandNode {
     path: string[];
@@ -137,8 +211,14 @@ export interface CommandNode {
     epilogue?: string;
     hidden?: boolean;
     deprecated?: boolean | string;
-    /** Required for a command to be served as an MCP tool (N2, N6). */
-    effects?: Effects;
+    /**
+     * What running it does to the world, or `'withheld'` (N2, N6). Required on a node that
+     * runs — `checkCommand` refuses one that omits it — and optional on the type, because a
+     * group carries no `effects` and the host front-ends build nodes that never reach that
+     * door: commander and yargs have no notion of effects and their graded suites declare
+     * none, so a façade's command is withheld in fact and cannot be made to say so.
+     */
+    effects?: DeclaredEffects;
     run?: (ctx: RunContext) => unknown;
     /**
      * The handler's module, imported on dispatch only (M2): the manifest — help, schema,
@@ -162,17 +242,6 @@ export interface Hook {
         options: Record<string, unknown>;
     }) => void | Promise<void>;
 }
-export interface Plugin {
-    name: string;
-    commands?: CommandNode[];
-    hooks?: {
-        preRun?: Hook;
-        postRun?: Hook;
-        onError?: Hook;
-    };
-    enforce?: 'pre' | 'post';
-}
-export declare function definePlugin(plugin: Plugin): Plugin;
 /** Rolldown's lesson: evaluate the filter before crossing the boundary. */
 export declare function hookApplies(hook: Hook | undefined, command: string): hook is Hook;
 export declare class Manifest {
@@ -191,6 +260,13 @@ export declare class Manifest {
     /** Characters of `--schema` output above which it is summarised (N13). */
     schemaBudget?: number;
     add(node: CommandNode): void;
+    /**
+     * Register a plugin, after the plugin host has read it (`plugin.ts`).
+     *
+     * Nothing is pushed until everything has been checked, so a refused plugin contributes no
+     * command and leaves no half-registration behind: `use()` used to push first and read the
+     * object afterwards, which is how `use(undefined)` became a `TypeError` one line later.
+     */
     use(plugin: Plugin): void;
     /** `enforce: 'pre'` first, then unordered, then `'post'` — the Vite/Rolldown convention. */
     private ordered;
@@ -205,3 +281,9 @@ export declare class Manifest {
         rest: string[];
     };
 }
+/**
+ * Re-exported so a façade importing `Plugin` keeps importing it from the module it registers
+ * against. The declaration itself lives in `./plugin.js`, which is the host file the family's
+ * locks read.
+ */
+export type { Plugin };

package/dist/manifest.js

@@ -1,3 +1,17 @@
+import { validate } from './plugin.js';
+export function optionRelations(options) {
+    const out = [];
+    for (const [key, spec] of Object.entries(options)) {
+        for (const other of spec.dependsOn ?? [])
+            out.push({ implies: [key, other] });
+        for (const other of spec.exclusive ?? [])
+            out.push({ conflicts: [key, other] });
+    }
+    return out;
+}
+export function relationsOf(node) {
+    return [...(node.relations ?? []), ...optionRelations(node.options)];
+}
 export function lazyRun(load) {
     let loaded;
     return async (ctx) => {
@@ -9,9 +23,6 @@ export function lazyRun(load) {
         return await handler(ctx);
     };
 }
-export function definePlugin(plugin) {
-    return plugin;
-}
 export function hookApplies(hook, command) {
     if (hook === undefined)
         return false;
@@ -30,10 +41,10 @@ export class Manifest {
         this.commands.push(node.load !== undefined && node.run === undefined ? { ...node, run: lazyRun(node.load) } : node);
     }
     use(plugin) {
+        validate(plugin, this.commands.map((c) => c.path.join(' ')));
         this.plugins.push(plugin);
-        for (const command of plugin.commands ?? []) {
+        for (const command of plugin.commands ?? [])
             this.add({ ...command, plugin: plugin.name });
-        }
     }
     ordered() {
         return [...this.plugins].sort((a, b) => (a.enforce === undefined ? 1 : ORDER[a.enforce]) - (b.enforce === undefined ? 1 : ORDER[b.enforce]));

package/dist/mcp.d.ts

@@ -22,7 +22,17 @@ export type Invoke = (argv: string[]) => Promise<{
 export declare function annotationsOf(effects: Effects): ToolAnnotations;
 /** `config get` → `config_get`: MCP tool names are `[a-zA-Z0-9_-]`. */
 export declare const toolName: (node: CommandNode, root: string[]) => string;
-/** The tool list: every runnable, visible command that declared its effects. */
+/**
+ * The tool list: every runnable, visible command that declared what running it does.
+ *
+ * Two commands are absent and for different reasons. One declared `'withheld'` — an author
+ * who thought about it and said no, which is what that word is for. The other has no
+ * `effects` at all, which `checkCommand` now refuses at declaration, so on burgee's own API
+ * it cannot reach here; a command built through the commander or yargs façade still can,
+ * because neither incumbent has a notion of effects and neither can be made to acquire one
+ * without breaking the suites that grade the façades. The filter treats both as *not a
+ * tool*, which is the same conservative reading it always had.
+ */
 export declare function toolsOf(manifest: Manifest): Tool[];
 /** A tool call's arguments back into argv: the command, its options, `--json`, then positionals in declared order. */
 export declare function argvOf(node: CommandNode, root: string[], args: Record<string, unknown>): string[];

package/dist/mcp.js

@@ -1,4 +1,5 @@
 import { createInterface } from 'node:readline';
+import { WITHHELD } from './definition.js';
 import { inputSchemaOf, runnable, typedName } from './schema.js';
 export const MCP_PROTOCOL_VERSION = '2025-06-18';
 const JSON_RPC_INVALID_REQUEST = -32600;
@@ -20,7 +21,7 @@ function describe(node) {
 }
 export function toolsOf(manifest) {
     return runnable(manifest)
-        .filter((c) => c.effects !== undefined)
+        .filter((c) => c.effects !== undefined && c.effects !== WITHHELD)
         .map((c) => ({ name: toolName(c, manifest.rootPath), description: describe(c), inputSchema: inputSchemaOf(c), annotations: annotationsOf(c.effects) }));
 }
 function optionArgs(node, args) {

package/dist/names.d.ts

@@ -1,5 +1,11 @@
 /** One canonical camelCase key per option; kebab-case on the command line (S5, yargs #1679). */
 /** `dryRun` → `dry-run`; a kebab key stays as it is. */
 export declare function kebab(name: string): string;
+/**
+ * Option names as the caller types them. Every surface that publishes a list of options —
+ * `--schema`, help, the Fig spec — renders the flags, never the canonical keys, and one
+ * helper here is the difference between that being true and being true three times.
+ */
+export declare function flagsOf(names: readonly string[]): string[];
 /** `--dry-run` on the command line reaches the handler as `dryRun`. */
 export declare function camel(flag: string): string;

package/dist/names.js

@@ -1,6 +1,9 @@
 export function kebab(name) {
     return name.replaceAll(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
 }
+export function flagsOf(names) {
+    return names.map((n) => `--${kebab(n)}`);
+}
 export function camel(flag) {
     return flag.replaceAll(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
 }