burgee 0.0.0 → 0.3.0

package/dist/help.js

@@ -0,0 +1,187 @@
+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', kind: 'flag' },
+    { term: '--help', text: 'show this help', kind: 'flag' },
+];
+function deprecation(d) {
+    if (d === undefined || d === false)
+        return '';
+    return d === true ? ' (deprecated)' : ` (deprecated: use ${d})`;
+}
+function annotate(text, spec, verbose) {
+    const parts = [text];
+    if (spec.required === true)
+        parts.push('(required)');
+    if (spec.default !== undefined)
+        parts.push(`(default: ${String(spec.default)})`);
+    if (spec.choices !== undefined)
+        parts.push(`(one of: ${spec.choices.join(', ')})`);
+    if (spec.multiple === true)
+        parts.push('(repeatable)');
+    if (spec.env !== undefined)
+        parts.push(`[env: ${spec.env}]`);
+    if (verbose)
+        parts.push(`[${spec.type}]`);
+    return `${parts.filter((p) => p !== '').join(' ')}${deprecation(spec.deprecated)}`.trim();
+}
+function placeholder(spec) {
+    if (spec.placeholder !== undefined)
+        return spec.placeholder;
+    return spec.type === 'number' ? 'n' : 'value';
+}
+function optionTerm(name, spec) {
+    const short = spec.short === undefined ? '' : `-${spec.short}, `;
+    const value = spec.type === 'boolean' ? '' : ` <${placeholder(spec)}>`;
+    return `${short}--${kebab(name)}${value}`;
+}
+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), kind: 'flag' }));
+}
+const argumentTerm = (a) => {
+    const name = a.variadic === true ? `${a.name}...` : a.name;
+    return a.required === false ? `[${name}]` : `<${name}>`;
+};
+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) {
+    const children = manifest.commands.filter((c) => c.hidden !== true && c.path.length === node.path.length + 1 && node.path.every((seg, i) => c.path[i] === seg));
+    const groups = new Map();
+    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(), kind: 'command' });
+        groups.set(heading, rows);
+    }
+    return [...groups].map(([title, rows]) => ({ title, rows }));
+}
+function environmentRows(options) {
+    return Object.entries(options)
+        .filter(([, spec]) => spec.env !== undefined && spec.hidden !== true)
+        .map(([name, spec]) => ({ term: spec.env ?? '', text: `--${kebab(name)}`, kind: 'value' }));
+}
+function usageLine(node, root, hasChildren, paint) {
+    const shown = node.path.slice(root.length).join(' ') || node.path.join(' ');
+    const parts = [shown];
+    if (hasChildren)
+        parts.push('<command>');
+    parts.push('[options]');
+    for (const a of node.arguments ?? [])
+        parts.push(argumentTerm(a));
+    return `${paint.heading('Usage:')} ${parts.join(' ')}`;
+}
+export function wrap(text, width) {
+    const out = [];
+    for (const line of text.split('\n')) {
+        if (/^\s/.test(line) || line.length <= width) {
+            out.push(line);
+            continue;
+        }
+        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}`;
+        }
+        out.push(current);
+    }
+    return out;
+}
+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, paint) {
+    const textWidth = Math.max(1, width - INDENT.length - column - GUTTER);
+    const lines = [];
+    for (const { term, text, kind } of rows) {
+        const cell = painterFor(paint, kind)(term);
+        if (text === '') {
+            lines.push(`${INDENT}${cell}`);
+            continue;
+        }
+        const wrapped = wrap(text, textWidth);
+        const continuation = INDENT + ' '.repeat(column + GUTTER);
+        if (term.length > column) {
+            lines.push(`${INDENT}${cell}`, ...wrapped.map((l) => `${continuation}${l}`));
+            continue;
+        }
+        const pad = ' '.repeat(column + GUTTER - term.length);
+        lines.push(`${INDENT}${cell}${pad}${wrapped[0] ?? ''}`, ...wrapped.slice(1).map((l) => `${continuation}${l}`));
+    }
+    return lines;
+}
+function exampleLines(examples, width) {
+    const lines = [];
+    for (const e of examples) {
+        lines.push(`${INDENT}$ ${e.command}`);
+        if (e.description !== undefined)
+            lines.push(...wrap(e.description, width - INDENT.length * 2).map((l) => `${INDENT}${INDENT}${l}`));
+    }
+    return lines;
+}
+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, paint), ''];
+    if (node.description !== undefined)
+        lines.push(...wrap(`${node.description}${deprecation(node.deprecated)}`, width), '');
+    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, 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

@@ -1 +1,16 @@
-export declare const VERSION = "0.0.0";
+/**
+ * burgee — a command declares itself once; every surface is that declaration
+ * read by a different reader.
+ *
+ * The public entry, and only that. The execution core lives in execute.ts so a
+ * façade can import it without pulling this barrel.
+ */
+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 { 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 './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 LazyModule, type OptionSpec, type ActionRequiredSpec, type Plugin, type Relation, type RunContext, type StandardResult, type StandardSchemaV1, } from './manifest.js';

package/dist/index.js

@@ -1,2 +1,9 @@
-export const VERSION = "0.0.0";
-//# sourceMappingURL=index.js.map
+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 { 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 './precedence.js';
+export { commandSchemaOf, inputSchemaOf, schemaOf, summaryOf } from './schema.js';
+export { definePlugin, Manifest, } from './manifest.js';

package/dist/manifest.d.ts

@@ -0,0 +1,207 @@
+/**
+ * The manifest — the one thing every surface is a projection of.
+ *
+ * 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 Standard Schema interface (standardschema.dev), declared here so any implementation
+ * — zod, valibot, arktype — is accepted as an option's `schema` without a dependency (S1).
+ */
+export interface StandardSchemaV1<Output = unknown> {
+    readonly '~standard': {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => StandardResult<Output> | Promise<StandardResult<Output>>;
+    };
+}
+export type StandardResult<Output> = {
+    readonly value: Output;
+    readonly issues?: undefined;
+} | {
+    readonly issues: readonly {
+        readonly message: string;
+    }[];
+};
+/**
+ * One option, declared once (S1). The key is the canonical camelCase name the handler
+ * reads; the CLI form is derived as kebab-case (S5): `dryRun` is typed `--dry-run`.
+ */
+export interface OptionSpec {
+    /** `boolean` never consumes a value (S7); `number` rejects NaN and Infinity (S3). */
+    type: 'string' | 'boolean' | 'number';
+    description?: string;
+    required?: boolean;
+    short?: string;
+    default?: string | boolean | number | readonly string[] | readonly number[];
+    /** Environment variable consulted when the flag is absent (V2). Read from the injected env, never process.env directly. */
+    env?: string;
+    /** Allowed values, enforced and shown as `(one of: a, b)` (yargs #1408, #1186). */
+    choices?: readonly string[];
+    /** Repeatable, and split on `separator` (`,` unless declared): `--tag a --tag b,c` → `['a', 'b', 'c']` (S8). */
+    multiple?: boolean;
+    separator?: string;
+    /** `number` only. */
+    minimum?: number;
+    maximum?: number;
+    integer?: boolean;
+    /** Any Standard Schema, run on the parsed value; its issues become a usage error (S1). */
+    schema?: StandardSchemaV1;
+    /** The value's name in help: `--id <dataset-id>` (yargs #833). */
+    placeholder?: string;
+    /** `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
+ * whether the command is exposed as an MCP tool at all (N2) and generates the tool's
+ * `readOnlyHint` / `idempotentHint` / `destructiveHint` — MCP defaults `destructiveHint`
+ * to true, so silence is the dangerous reading.
+ */
+export type Effects = 'read_only' | 'idempotent' | 'non_idempotent';
+/**
+ * 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.
+ */
+export type Relation = {
+    exactlyOneOf: readonly string[];
+} | {
+    atLeastOneOf: readonly string[];
+} | {
+    atMostOneOf: readonly string[];
+} | {
+    conflicts: readonly string[];
+} | {
+    implies: readonly [string, string | ((values: Record<string, unknown>) => boolean)];
+};
+/** A positional, as help documents it (yargs #2012). */
+export interface ArgumentSpec {
+    name: string;
+    description?: string;
+    required?: boolean;
+    variadic?: boolean;
+    default?: string;
+}
+/** One example: a single copy-pasteable command line, the description below it (H2). */
+export interface Example {
+    command: string;
+    description?: string;
+}
+/** What a handler receives. `passthrough` is everything after `--`, verbatim (G5). */
+/** What a caller must do before the command can continue (N11): synthesised into the envelope. */
+export interface ActionRequiredSpec {
+    /** A short machine-readable reason: `login`, `confirm`, `missing-config` … */
+    reason: string;
+    message: string;
+    /** Runnable commands, each with when to run it; the engine prefixes the program and carries the caller's flags. */
+    next?: readonly {
+        command: string;
+        when: string;
+    }[];
+    hint?: string;
+}
+export interface RunContext {
+    options: Record<string, unknown>;
+    positionals: string[];
+    passthrough: string[];
+    env: Record<string, string | undefined>;
+    /** Exit with an E1 code. Unwinds cleanly: the code is honoured and nothing is printed. */
+    exit: (code: number) => never;
+    /** A person may be prompted (N12): a terminal, no detected agent, or `FORCE_TTY=1`. */
+    interactive: boolean;
+    /** The agent the environment names, if any (N12). */
+    agent?: string;
+    /** Stop and tell the caller what to do instead of blocking on a prompt (N11). */
+    actionRequired: (spec: ActionRequiredSpec) => never;
+}
+export interface CommandNode {
+    path: string[];
+    description?: string;
+    /** Shown in command lists instead of the description (yargs #1265). */
+    summary?: string;
+    options: Record<string, OptionSpec>;
+    relations?: readonly Relation[];
+    arguments?: ArgumentSpec[];
+    examples?: Example[];
+    /** Heading this command is listed under in its parent's help (yargs #684). */
+    group?: string;
+    epilogue?: string;
+    hidden?: boolean;
+    deprecated?: boolean | string;
+    /** 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;
+}
+export interface Hook {
+    filter?: HookFilter;
+    handler: (ctx: {
+        command: string;
+        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 {
+    readonly commands: CommandNode[];
+    readonly plugins: Plugin[];
+    /** The program's own name, which the user never types; `execute` strips it. */
+    rootPath: string[];
+    /** Reported by `--schema`, `--version` and the MCP handshake; the owning package.json otherwise (V4). */
+    version?: string;
+    /** With a prefix, every option reads `PREFIX_OPTION_NAME` unless it names its own env (V2). */
+    envPrefix?: string;
+    /** Config discovery is opt-in; the name is the file stem and the package.json field (V6). */
+    config?: {
+        name: string;
+    };
+    /** Characters of `--schema` output above which it is summarised (N13). */
+    schemaBudget?: number;
+    add(node: CommandNode): void;
+    use(plugin: Plugin): void;
+    /** `enforce: 'pre'` first, then unordered, then `'post'` — the Vite/Rolldown convention. */
+    private ordered;
+    fire(stage: 'preRun' | 'postRun' | 'onError', command: string, options: Record<string, unknown>): Promise<void>;
+    find(path: string[]): CommandNode | undefined;
+    /**
+     * Longest-prefix match of argv against declared command paths. The root's own
+     * name is not typed by the user, so it is skipped when matching.
+     */
+    resolve(argv: string[], root?: string[]): {
+        node: CommandNode | undefined;
+        rest: string[];
+    };
+}

package/dist/manifest.js

@@ -0,0 +1,66 @@
+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;
+}
+export function hookApplies(hook, command) {
+    if (hook === undefined)
+        return false;
+    return hook.filter?.command === undefined || hook.filter.command.test(command);
+}
+const ORDER = { pre: 0, post: 2 };
+export class Manifest {
+    commands = [];
+    plugins = [];
+    rootPath = [];
+    version;
+    envPrefix;
+    config;
+    schemaBudget;
+    add(node) {
+        this.commands.push(node.load !== undefined && node.run === undefined ? { ...node, run: lazyRun(node.load) } : node);
+    }
+    use(plugin) {
+        this.plugins.push(plugin);
+        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]));
+    }
+    async fire(stage, command, options) {
+        for (const plugin of this.ordered()) {
+            const hook = plugin.hooks?.[stage];
+            if (hookApplies(hook, command))
+                await hook.handler({ command, options });
+        }
+    }
+    find(path) {
+        const key = path.join(' ');
+        return this.commands.find((c) => c.path.join(' ') === key);
+    }
+    resolve(argv, root = []) {
+        let best;
+        let depth = 0;
+        for (const node of this.commands) {
+            const typed = node.path.slice(root.length);
+            if (typed.length > argv.length)
+                continue;
+            if (typed.every((seg, i) => argv[i] === seg) && typed.length >= depth) {
+                best = node;
+                depth = typed.length;
+            }
+        }
+        return { node: best, rest: argv.slice(depth) };
+    }
+}

package/dist/mcp.d.ts

@@ -0,0 +1,52 @@
+import { type CommandNode, type Effects, type Manifest } from './manifest.js';
+import { type JsonSchema } from './schema.js';
+export declare const MCP_PROTOCOL_VERSION = "2025-06-18";
+export interface ToolAnnotations {
+    readOnlyHint: boolean;
+    idempotentHint: boolean;
+    destructiveHint: boolean;
+}
+export interface Tool {
+    name: string;
+    description: string;
+    inputSchema: JsonSchema;
+    annotations: ToolAnnotations;
+}
+/** What a tool call runs: the same execute a `--json` caller reaches, with the streams captured. */
+export type Invoke = (argv: string[]) => Promise<{
+    stdout: string;
+    stderr: string;
+    code: number;
+}>;
+/** MCP's hints, from the declared effects. `destructiveHint` is only ever false by declaration. */
+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. */
+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[];
+export interface ServeOptions {
+    input: NodeJS.ReadableStream;
+    output: {
+        write: (s: string) => unknown;
+    };
+    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;
+}
+/**
+ * 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

@@ -0,0 +1,124 @@
+import { createInterface } from 'node:readline';
+import { inputSchemaOf, runnable, typedName } from './schema.js';
+export const MCP_PROTOCOL_VERSION = '2025-06-18';
+const JSON_RPC_INVALID_REQUEST = -32600;
+const JSON_RPC_METHOD_NOT_FOUND = -32601;
+const JSON_RPC_INVALID_PARAMS = -32602;
+export function annotationsOf(effects) {
+    return {
+        readOnlyHint: effects === 'read_only',
+        idempotentHint: effects !== 'non_idempotent',
+        destructiveHint: effects === 'non_idempotent',
+    };
+}
+export const toolName = (node, root) => typedName(node, root).replaceAll(' ', '_');
+function describe(node) {
+    const parts = [node.description ?? node.summary ?? ''];
+    for (const e of node.examples ?? [])
+        parts.push(`Example: ${e.command}${e.description === undefined ? '' : ` — ${e.description}`}`);
+    return parts.filter((p) => p !== '').join('\n');
+}
+export function toolsOf(manifest) {
+    return runnable(manifest)
+        .filter((c) => c.effects !== undefined)
+        .map((c) => ({ name: toolName(c, manifest.rootPath), description: describe(c), inputSchema: inputSchemaOf(c), annotations: annotationsOf(c.effects) }));
+}
+function optionArgs(node, args) {
+    const out = [];
+    for (const [name, spec] of Object.entries(node.options)) {
+        const value = args[name];
+        if (value === undefined || value === null)
+            continue;
+        if (spec.type === 'boolean') {
+            if (value === true)
+                out.push(`--${name}`);
+        }
+        else
+            out.push(`--${name}`, String(value));
+    }
+    return out;
+}
+function positionalArgs(node, args) {
+    const out = [];
+    for (const a of node.arguments ?? []) {
+        const value = args[a.name];
+        if (value === undefined || value === null)
+            continue;
+        out.push(...(Array.isArray(value) ? value.map(String) : [String(value)]));
+    }
+    return out;
+}
+export function argvOf(node, root, args) {
+    const command = typedName(node, root).split(' ').filter((s) => s !== '');
+    return [...command, ...optionArgs(node, args), '--json', ...positionalArgs(node, args)];
+}
+async function callTool(session, params) {
+    const { manifest, invoke } = session;
+    const root = manifest.rootPath;
+    const given = params ?? {};
+    const raw = given['name'];
+    const name = typeof raw === 'string' ? raw : '';
+    const exposed = new Set(toolsOf(manifest).map((t) => t.name));
+    const node = exposed.has(name) ? runnable(manifest).find((c) => toolName(c, root) === name) : undefined;
+    if (node === undefined)
+        return { error: { code: JSON_RPC_INVALID_PARAMS, message: `unknown tool "${name}"` } };
+    const args = (given['arguments'] ?? {});
+    const { stdout, stderr, code } = await invoke(argvOf(node, root, args));
+    const text = stdout.trim() !== '' ? stdout.trim() : stderr.trim();
+    return { result: { content: [{ type: 'text', text }], isError: code !== 0 } };
+}
+async function handle(session, request) {
+    switch (request.method) {
+        case 'initialize':
+            return { result: { protocolVersion: MCP_PROTOCOL_VERSION, capabilities: { tools: {} }, serverInfo: session.serverInfo } };
+        case 'ping':
+            return { result: {} };
+        case 'tools/list':
+            return { result: { tools: toolsOf(session.manifest) } };
+        case 'tools/call':
+            return await callTool(session, request.params);
+        default:
+            return { error: { code: JSON_RPC_METHOD_NOT_FOUND, message: `method not found: ${request.method}` } };
+    }
+}
+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`);
+    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;
+        try {
+            request = JSON.parse(line);
+        }
+        catch {
+            reply({ id: null, error: { code: JSON_RPC_INVALID_REQUEST, message: 'invalid JSON' } });
+            continue;
+        }
+        if (typeof request.method !== 'string') {
+            reply({ id: request.id ?? null, error: { code: JSON_RPC_INVALID_REQUEST, message: 'missing method' } });
+            continue;
+        }
+        if (request.id === undefined)
+            continue;
+        const outcome = (await handle(session, request));
+        reply({ id: request.id, ...outcome });
+    }
+}

package/dist/names.d.ts

@@ -0,0 +1,5 @@
+/** 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;
+/** `--dry-run` on the command line reaches the handler as `dryRun`. */
+export declare function camel(flag: string): string;

package/dist/names.js

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