burgee 0.11.0 → 0.12.0

package/dist/manifest.d.ts

@@ -36,6 +36,13 @@ export type StandardResult<Output> = {
 export interface OptionSpec {
     /** `boolean` never consumes a value (S7); `number` rejects NaN and Infinity (S3). */
     type: 'string' | 'boolean' | 'number';
+    /**
+     * D3 / D-119 — values computed when a person presses TAB: the generated script calls the
+     * program back (`<program> __complete <command> --<option> <partial>`) for this option and
+     * no other. Declaring it is the opt-in; an option without one completes from `choices`, or
+     * not at all, and never runs the program.
+     */
+    complete?: (partial: string) => Iterable<string> | Promise<Iterable<string>>;
     description?: string;
     required?: boolean;
     short?: string;
@@ -78,6 +85,13 @@ export interface OptionSpec {
     /** `true` renders `(deprecated)`; a string names the replacement: `(deprecated: use --force)` (yargs #2248). */
     deprecated?: boolean | string;
     hidden?: boolean;
+    /**
+     * `boolean` only: whether `--no-<name>` is accepted. Every boolean is negatable unless this
+     * says `false`. burgee's own parser negates every boolean (see `toParseConfig`); the
+     * commander façade sets `false` where commander would refuse the negation, so completions
+     * and `--mcp` never offer or send a flag the parser behind them rejects.
+     */
+    negatable?: boolean;
     /** The shared set this option was copied from (M4); `--schema` carries it, help lists the option like any other. */
     sharedFrom?: string;
 }
@@ -150,6 +164,8 @@ export interface ArgumentSpec {
     required?: boolean;
     variadic?: boolean;
     default?: string;
+    /** `'file'`: a path, where `-` means standard input — handed to the handler as `ctx.stdin` (S4). */
+    type?: 'file';
 }
 /** One example: a single copy-pasteable command line, the description below it (H2). */
 export interface Example {
@@ -173,6 +189,11 @@ export interface RunContext {
     options: Record<string, unknown>;
     positionals: string[];
     passthrough: string[];
+    /**
+     * Standard input, present only when a `type: 'file'` argument was given `-` (S4). The
+     * positional still reads `-`, so a handler checks it the same way it checks a path.
+     */
+    stdin?: NodeJS.ReadableStream;
     env: Record<string, string | undefined>;
     /** Exit with an E1 code. Unwinds cleanly: the code is honoured and nothing is printed. */
     exit: (code: number) => never;
@@ -219,6 +240,8 @@ export interface CommandNode {
      * none, so a façade's command is withheld in fact and cannot be made to say so.
      */
     effects?: DeclaredEffects;
+    /** The result's top-level fields, as declared (N14); what `--json=` lists. */
+    fields?: readonly string[];
     run?: (ctx: RunContext) => unknown;
     /**
      * The handler's module, imported on dispatch only (M2): the manifest — help, schema,
@@ -235,13 +258,19 @@ export declare function lazyRun(load: () => Promise<LazyModule>): (ctx: RunConte
 export interface HookFilter {
     command?: RegExp;
 }
+/** What a hook is handed. `argv` on `parse` only; `options` is empty on `parse` and `shutdown`. */
+export interface HookContext {
+    command: string;
+    options: Record<string, unknown>;
+    argv?: string[];
+}
 export interface Hook {
     filter?: HookFilter;
-    handler: (ctx: {
-        command: string;
-        options: Record<string, unknown>;
-    }) => void | Promise<void>;
+    /** `parse` may return the argv to use instead; every other stage's return is ignored. */
+    handler: (ctx: HookContext) => unknown;
 }
+/** The stages a plugin hook fires at. `parse` and `shutdown` bracket the run (D-122). */
+export type HookStage = 'parse' | 'preRun' | 'postRun' | 'onError' | 'shutdown';
 /** 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 {
@@ -270,7 +299,15 @@ export declare class Manifest {
     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>;
+    /** Whether any registered plugin declares a hook at `stage` — so a run without one pays nothing. */
+    declares(stage: HookStage): boolean;
+    /**
+     * `parse` (D-122): argv in, argv out, before the command is resolved. Each plugin, in
+     * `enforce` order, is handed what the previous one returned; returning nothing keeps it.
+     * A filter is matched against the typed argv, since no command has been resolved yet.
+     */
+    parse(argv: string[]): Promise<string[]>;
+    fire(stage: Exclude<HookStage, 'parse'>, 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

package/dist/manifest.js

@@ -49,6 +49,12 @@ export class Manifest {
     ordered() {
         return [...this.plugins].sort((a, b) => (a.enforce === undefined ? 1 : ORDER[a.enforce]) - (b.enforce === undefined ? 1 : ORDER[b.enforce]));
     }
+    declares(stage) {
+        return this.plugins.some((p) => p.hooks?.[stage] !== undefined);
+    }
+    async parse(argv) {
+        return (await import('./parse-hooks.js')).runParseHooks(this.ordered(), argv);
+    }
     async fire(stage, command, options) {
         for (const plugin of this.ordered()) {
             const hook = plugin.hooks?.[stage];

package/dist/mcp.d.ts

@@ -34,7 +34,11 @@ export type Invoke = (argv: string[]) => Promise<{
  * this command is not a `read_only` one, and it is not a `withheld` one either — nobody said.
  */
 export declare function annotationsOf(effects?: Effects): ToolAnnotations;
-/** `config get` → `config_get`: MCP tool names are `[a-zA-Z0-9_-]`. */
+/**
+ * `config get` → `config_get`: MCP tool names are `[a-zA-Z0-9_-]`, one character or more. A
+ * program whose root runs — a single `run(defineCommand(…))`, a commander program with a root
+ * `.action()` — has no typed name at all, so its tool is named after the program.
+ */
 export declare const toolName: (node: CommandNode, root: string[]) => string;
 /**
  * The tool list: every runnable, visible command an author has not withheld.

package/dist/mcp.js

@@ -1,5 +1,9 @@
+import { Console } from 'node:console';
 import { createInterface } from 'node:readline';
+import { Writable } from 'node:stream';
 import { WITHHELD } from './definition.js';
+import { kebab } from './names.js';
+import { host } from './runtime.js';
 import { inputSchemaOf, runnable, typedName } from './schema.js';
 export const MCP_PROTOCOL_VERSION = '2025-06-18';
 const JSON_RPC_INVALID_REQUEST = -32600;
@@ -14,7 +18,7 @@ export function annotationsOf(effects) {
         destructiveHint: effects === 'non_idempotent',
     };
 }
-export const toolName = (node, root) => typedName(node, root).replaceAll(' ', '_');
+export const toolName = (node, root) => (typedName(node, root) || root.join(' ')).replaceAll(' ', '_');
 function describe(node) {
     const parts = [node.description ?? node.summary ?? ''];
     for (const e of node.examples ?? [])
@@ -32,12 +36,13 @@ function optionArgs(node, args) {
         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));
+        const flag = `--${kebab(name)}`;
+        if (spec.type !== 'boolean')
+            out.push(flag, String(value));
+        else if (value === true)
+            out.push(flag);
+        else if (value === false && spec.negatable !== false && (spec.default === true || spec.env !== undefined))
+            out.push(`--no-${kebab(name)}`);
     }
     return out;
 }
@@ -55,6 +60,46 @@ export function argvOf(node, root, args) {
     const command = typedName(node, root).split(' ').filter((s) => s !== '');
     return [...command, ...optionArgs(node, args), '--json', ...positionalArgs(node, args)];
 }
+const STDOUT_CONSOLE = ['log', 'info', 'debug', 'dir', 'dirxml', 'table', 'group', 'groupCollapsed', 'groupEnd', 'count', 'countReset', 'time', 'timeLog', 'timeEnd'];
+let framing = false;
+async function printedBy(run) {
+    const chunks = [];
+    const decoder = new TextDecoder();
+    const take = (chunk) => void chunks.push(typeof chunk === 'string' ? chunk : decoder.decode(chunk));
+    const sink = new Writable({
+        decodeStrings: false,
+        write(chunk, _encoding, done) {
+            take(chunk);
+            done();
+        },
+    });
+    const stdout = host.stdout;
+    const write = stdout.write;
+    stdout.write = function (chunk, ...rest) {
+        if (framing)
+            return Reflect.apply(write, stdout, [chunk, ...rest]);
+        take(chunk);
+        const done = rest.find((r) => typeof r === 'function');
+        if (done !== undefined)
+            queueMicrotask(done);
+        return true;
+    };
+    const printer = new Console({ stdout: sink, stderr: host.stderr });
+    const saved = STDOUT_CONSOLE.map((m) => [m, console[m]]);
+    for (const m of STDOUT_CONSOLE)
+        Reflect.set(console, m, printer[m].bind(printer));
+    try {
+        return { settled: { status: 'fulfilled', value: await run() }, printed: chunks.join('') };
+    }
+    catch (reason) {
+        return { settled: { status: 'rejected', reason }, printed: chunks.join('') };
+    }
+    finally {
+        for (const [m, fn] of saved)
+            Reflect.set(console, m, fn);
+        stdout.write = write;
+    }
+}
 async function callTool(session, params) {
     const { manifest, invoke } = session;
     const root = manifest.rootPath;
@@ -65,9 +110,22 @@ async function callTool(session, params) {
     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 } };
+    const { settled, printed } = await printedBy(async () => await invoke(argvOf(node, root, args)));
+    let text;
+    let isError;
+    if (settled.status === 'fulfilled') {
+        const { stdout, stderr, code } = settled.value;
+        text = stdout.trim() !== '' ? stdout.trim() : stderr.trim();
+        isError = code !== 0;
+    }
+    else {
+        text = settled.reason instanceof Error ? settled.reason.message : String(settled.reason);
+        isError = true;
+    }
+    const content = [{ type: 'text', text }];
+    if (printed.trim() !== '')
+        content.push({ type: 'text', text: printed.trimEnd() });
+    return { result: { content, isError } };
 }
 async function handle(session, request) {
     switch (request.method) {
@@ -89,7 +147,15 @@ export function startMcp(manifest, opts) {
         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 reply = (body) => {
+        framing = true;
+        try {
+            opts.output.write(`${JSON.stringify({ jsonrpc: '2.0', ...body })}\n`);
+        }
+        finally {
+            framing = false;
+        }
+    };
     const swap = (next, invoke) => {
         session.manifest = next;
         if (invoke !== undefined)

package/dist/migrate.d.ts

@@ -1,13 +1,25 @@
-import { type Graded } from './compat.js';
+import { type Row } from './compat.js';
+/** The npm package a specifier names: `@scope/name/x` → `@scope/name`, `name/x` → `name`. */
+export declare function packageOf(specifier: string): string;
 /**
- * A2 — the whole mapping, as data.
+ * A2, A12 — the whole mapping, as data, and none of it typed here.
+ *
+ * Every drop-in the oracle grades **level** with its incumbent (D-137): the incumbent's own
+ * suite passes as many cases against the family's replacement as against the incumbent
+ * itself, in the same harness. That is commander and yargs, and chalk, ora, string-width,
+ * cross-spawn, signal-exit and the rest — `compat.ts` holds the list and a lock re-derives it
+ * from `compat-oracle`. A drop-in that is not level yet is reported, never rewritten.
  *
  * Whole specifiers only. `burgee/commander` is not a key, which is what makes a second run
  * over an already-migrated tree a no-op and lets the command declare `effects: 'idempotent'`.
+ * `yargs/yargs` is the one key the oracle does not name: yargs documents it as an entry,
+ * and it is the same module as `yargs`.
  */
 export declare const MAPPING: Readonly<Record<string, string>>;
-/** The packages a project depends on that this command is about (A1). */
-export declare const HOSTS: readonly ["commander", "yargs"];
+/** The packages a project depends on that this command rewrites (A1). */
+export declare const HOSTS: readonly string[];
+/** The leading number of a version or a range — `^3.0.7` is 3, `>=18` is 18; `undefined` for `*` or a tag. */
+export declare function majorOf(version: string): number | undefined;
 /**
  * Every name each target exports — values and types alike — so a rewrite that moves
  * `import { Argv } from 'yargs'` can first ask whether `burgee/yargs` has an `Argv`.
@@ -24,8 +36,24 @@ export declare const FACADE_EXPORTS: Readonly<Record<string, readonly string[]>>
  *
  * `unknown-export` is a named import the target does not export — rewriting it would turn a
  * working import into TS2305 or a `SyntaxError` at load, so the file stays as it was.
+ *
+ * `require-of-default` is a `require()` whose two sides hand back different kinds of value.
+ * `require()` of an ES module returns its namespace, so `require('cross-spawn')` — a function —
+ * rewritten to a target with a default and no `'module.exports'` would make `spawn(...)` throw.
+ * A `require('chalk')` of chalk 6, which is ESM only, already returns a namespace, and moves to
+ * a target that does too ({@link REQUIRE_NAMESPACE}, A29). Where the shapes differ, the file
+ * stays on the incumbent, where it works.
  */
-export type RefusalReason = 'deep-import' | 'non-literal-specifier' | 'unknown-export';
+export type RefusalReason = 'deep-import' | 'non-literal-specifier' | 'unknown-export' | 'require-of-default';
+/**
+ * Incumbents whose own `require()` already returns an ES namespace — they ship ESM only and
+ * export no `'module.exports'`, so `require('chalk').default` is how a CommonJS caller of
+ * chalk 6 reaches it. Moving that line to a target that also hands back its namespace is
+ * exact (A29). Derived, not typed: `migrate-require.test.ts` holds this list equal to what
+ * Node's own `require()` returns for every installed incumbent in `MAPPING`, so a name here
+ * is a measurement and an incumbent that is not installed is left out, and refused as before.
+ */
+export declare const REQUIRE_NAMESPACE: readonly string[];
 export interface Refusal {
     /** Relative to the directory being migrated, with forward slashes on every platform. */
     file: string;
@@ -64,6 +92,18 @@ export interface Detection {
     /** Hosts a source file actually imports — used. These two disagree more often than not. */
     imported: string[];
 }
+/** An incumbent the project has on a different major from the one graded — left alone (A12). */
+export interface OffMajor {
+    from: string;
+    /** The installed version, or the declared range when nothing is installed here. */
+    found: string;
+    graded: string;
+}
+/** A declared incumbent with a graded drop-in that is not level yet (A12). */
+export interface NotLevel extends Row {
+    from: string;
+    to: string;
+}
 export interface MigrationReport {
     files: number;
     imports: number;
@@ -72,14 +112,22 @@ export interface MigrationReport {
     /** Type-only imports left pointing at the incumbent, each with the note that says why. */
     kept: Kept[];
     detected: Detection;
+    /** `add`: the family packages the rewritten imports now name, which the project must depend on. */
     dependencies: {
         before: string[];
         removable: string[];
         after: number;
+        add: string[];
     };
-    graded: (Graded & {
+    graded: (Row & {
         host: string;
     })[];
+    /** Declared incumbents whose drop-in is graded but not level — left alone, with the grade that says why. */
+    partial: NotLevel[];
+    /** Incumbents on a major the oracle did not grade — left alone, never rewritten onto an API they do not use. */
+    offMajor: OffMajor[];
+    /** The install and uninstall to run next, for the package manager the lockfile names; `''` when there is none. */
+    next: string;
     dryRun: boolean;
     /** N7 — an idempotent command says whether it changed anything; silence is what an agent misreads. */
     changed: boolean;
@@ -97,6 +145,8 @@ interface Site {
      * — the import clause, which is all `bindingsOf` needs. Absent for the other three positions.
      */
     clause?: string[];
+    /** `require('x')`: CommonJS receives the target's whole namespace, not its default export. */
+    require?: true;
 }
 interface Scan {
     sites: Site[];
@@ -154,7 +204,7 @@ export declare function bindingsOf(clause: readonly string[]): {
  * source is returned unchanged the moment there is a refusal in it: the unit of success is
  * the file, so the worst case is *nothing changed here, and here is why* (D-051).
  */
-export declare function rewriteSource(source: string): Rewrite;
+export declare function rewriteSource(source: string, skip?: ReadonlySet<string>): Rewrite;
 /** Every source file under `dir`, relative and slash-separated so a report reads the same everywhere. */
 export declare function sourceFiles(dir: string, at?: string, found?: string[]): string[];
 /**