burgee 0.11.0 → 0.12.0

package/README.md

@@ -46,6 +46,7 @@ run(defineCommand({
   name: 'greet',
   description: 'Greet someone by name',
   options: { name: { type: 'string', required: true, description: 'who to greet' } },
+  effects: 'read_only', // what running it does to the world; required, and what --mcp reads
   run: ({ options }) => ({ greeting: `hello, ${options.name}` }),
 }));
 ```
@@ -55,7 +56,7 @@ $ node cli.mjs --name ada
 greeting: hello, ada
 
 $ node cli.mjs --json --name ada
-{"ok":true,"data":{"greeting":"hello, ada"}}
+{"ok":true,"data":{"greeting":"hello, ada"},"meta":{"provenance":{"name":{"source":"flag","location":"--name"}}}}
 
 $ node cli.mjs            # exit 2
 error: missing required option --name
@@ -94,6 +95,18 @@ published and ratcheting:
 Your code and your tests are unchanged. A façade is never called "compatible" until its
 host's own suite passes 100%; below that the rate is published instead of claimed.
 
+Or let the codemod make that change, and the same one for chalk, ora, string-width,
+cross-spawn, signal-exit and every other incumbent the family replaces at full grade:
+
+```bash
+npx burgee migrate --dry-run
+npx burgee migrate
+```
+
+It rewrites import specifiers and nothing else, leaves a replacement that is not level yet
+alone with its grade, refuses a file it cannot rewrite whole, and prints the install command
+to run next — [Migrate](https://burgee.interlace.tools/docs/migrate).
+
 ## What is in the box
 
 | Import | Gives you |
@@ -154,9 +167,11 @@ the declaration read by a different reader.
 
 ### How do I expose a CLI over MCP?
 
-Run it with `--mcp`: the same manifest is served as MCP tools over stdio. A command becomes
-a tool only when it declares its `effects` (`read_only`, `idempotent` or `non_idempotent`),
-so nothing reaches an agent by accident. Register it with any stdio client:
+Run it with `--mcp`: the same manifest is served as MCP tools over stdio. Every runnable
+command declares its `effects` — `read_only`, `idempotent` or `non_idempotent`, which become
+MCP's hints, or `withheld`, which keeps it out of the tool list — so nothing reaches an
+agent by accident. On `burgee/commander` and `burgee/yargs`, a command that declared
+nothing is still listed, marked `effects: 'undeclared'`. Register it with any stdio client:
 
 ```json
 { "mcpServers": { "mytool": { "command": "npx", "args": ["mytool", "--mcp"] } } }

package/dist/cli.d.ts

@@ -1,90 +1,2 @@
-export declare const brandCommand: import("./execute.js").Command<{
-    readonly lead: {
-        readonly type: "string";
-        readonly required: true;
-        readonly description: "leading colour, hex. Your primary; it leads the charge upper-left";
-    };
-    readonly follow: {
-        readonly type: "string";
-        readonly required: true;
-        readonly description: "following colour, hex. Your secondary; it follows lower-right";
-    };
-    readonly name: {
-        readonly type: "string";
-        readonly description: "brand name, used as the accessible label and card title";
-    };
-    readonly ground: {
-        readonly type: "string";
-        readonly default: "#0a0a0a";
-        readonly description: "the field’s dark midpoint, which is what keeps the charge legible";
-    };
-    readonly charge: {
-        readonly type: "string";
-        readonly description: "path to an SVG whose contents replace the bars, drawn in a 0 0 100 100 box";
-    };
-    readonly bordure: {
-        readonly type: "string";
-        readonly description: "outline colour, hex. Omit for no outline";
-    };
-    readonly bordureWidth: {
-        readonly type: "string";
-        readonly default: "1.5";
-        readonly description: "outline width";
-    };
-    readonly tagline: {
-        readonly type: "string";
-        readonly description: "one line under the name on the card and cover";
-    };
-    readonly out: {
-        readonly type: "string";
-        readonly description: "directory to write into. Omit to print the flag only";
-    };
-    readonly on: {
-        readonly type: "string";
-        readonly description: "page colour(s) the flag will fly on, comma separated. Checked for contrast";
-    };
-    readonly allowLowContrast: {
-        readonly type: "boolean";
-        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 noWatch: {
-        readonly type: "boolean";
-        readonly description: "load once and serve; do not watch for changes";
-    };
-}>;
-/**
- * `burgee migrate [dir]` — rewrite a commander or yargs project's imports to burgee's
- * drop-in front-ends and report what changed, with the numbers that say why it was safe.
- *
- * The engine is loaded on this path only (K6), the same way `dev` is: a dynamic import, so
- * `burgee`'s own start-up and the framework's weight are what they were. `weight.test.ts`
- * denies `migrate.js` to the root entry by name, so that cannot drift back.
- *
- * `idempotent` is the honest answer rather than the conservative one, and it is earned:
- * `burgee/commander` is not a key in the mapping, so a second run over a migrated tree
- * rewrites nothing. N6 then requires the result to report `changed`, which it does.
- */
-export declare const migrateCommand: import("./execute.js").Command<{
-    readonly dryRun: {
-        readonly type: "boolean";
-        readonly description: "scan and report; write nothing";
-    };
-    readonly force: {
-        readonly type: "boolean";
-        readonly description: "migrate even though the git tree has uncommitted changes";
-    };
-}>;
-/**
- * `burgee check <plugin-file>` — the feedback loop PRINCIPLES 7 asks every extension surface
- * for, and the one burgee did not have. See `check.ts`: this one returns its report as data, so
- * `--json` is the form an agent that just wrote a plugin reads.
- */
-export declare const pluginCheckCommand: import("./execute.js").Command<import("./execute.js").OptionSpecs>;
-export declare const program: import("./manifest.js").Manifest;
+#!/usr/bin/env node
+export * from './program.js';

package/dist/cli.js

@@ -1,152 +1,5 @@
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { DEFAULT_GROUND, defineBurgee, opposedField } from './brand.js';
-import { auditBurgee, report } from './contrast.js';
-import { defineCommand, defineProgram, run } from './execute.js';
-const MASTER = 512;
-const CONTRAST_HINT = 'hint: darken the --ground stop under the charge, or pass --allow-low-contrast';
-const DEFAULT_BORDURE_WIDTH = '1.5';
-function surfaces(brand, tagline) {
-    const burgee = defineBurgee(brand);
-    const subtitle = tagline === '' ? {} : { subtitle: tagline };
-    return [
-        { file: 'flag.svg', svg: burgee.flag(MASTER) },
-        { file: 'icon.svg', svg: burgee.favicon() },
-        { file: 'og.svg', svg: burgee.og(subtitle) },
-        { file: 'cover.svg', svg: burgee.cover(subtitle) },
-        { file: 'lockup.svg', svg: burgee.lockup({ theme: 'dark' }) },
-        { file: 'lockup-light.svg', svg: burgee.lockup({ theme: 'light' }) },
-    ];
-}
-export const brandCommand = defineCommand({
-    name: 'brand',
-    description: 'Generate a burgee — flag, favicon, social card, cover and lockup — from two colours',
-    effects: 'non_idempotent',
-    options: {
-        lead: {
-            type: 'string',
-            required: true,
-            description: 'leading colour, hex. Your primary; it leads the charge upper-left',
-        },
-        follow: {
-            type: 'string',
-            required: true,
-            description: 'following colour, hex. Your secondary; it follows lower-right',
-        },
-        name: { type: 'string', description: 'brand name, used as the accessible label and card title' },
-        ground: {
-            type: 'string',
-            default: DEFAULT_GROUND,
-            description: 'the field’s dark midpoint, which is what keeps the charge legible',
-        },
-        charge: {
-            type: 'string',
-            description: 'path to an SVG whose contents replace the bars, drawn in a 0 0 100 100 box',
-        },
-        bordure: { type: 'string', description: 'outline colour, hex. Omit for no outline' },
-        bordureWidth: { type: 'string', default: DEFAULT_BORDURE_WIDTH, description: 'outline width' },
-        tagline: { type: 'string', description: 'one line under the name on the card and cover' },
-        out: { type: 'string', description: 'directory to write into. Omit to print the flag only' },
-        'on': {
-            type: 'string',
-            description: 'page colour(s) the flag will fly on, comma separated. Checked for contrast',
-        },
-        allowLowContrast: {
-            type: 'boolean',
-            description: 'emit anyway when a contrast check fails. Says so in the output',
-        },
-    },
-    run: ({ options }) => {
-        const lead = options.lead ?? '';
-        const follow = options.follow ?? '';
-        const colors = { lead, follow };
-        const charge = options.charge === undefined
-            ? {}
-            : { charge: readFileSync(options.charge, 'utf8').replace(/<\/?svg[^>]*>/g, '').trim() };
-        const bordure = options.bordure === undefined
-            ? {}
-            : {
-                bordure: {
-                    color: options.bordure,
-                    width: Number(options.bordureWidth ?? DEFAULT_BORDURE_WIDTH),
-                },
-            };
-        const brand = {
-            ...(options.name === undefined ? {} : { name: options.name }),
-            mark: colors,
-            field: opposedField(colors, options.ground ?? DEFAULT_GROUND),
-            ...charge,
-            ...bordure,
-        };
-        const grounds = (options.on ?? '')
-            .split(',')
-            .map((g) => g.trim())
-            .filter((g) => g !== '');
-        const findings = auditBurgee(brand, grounds);
-        const failed = findings.filter((f) => !f.passes);
-        if (failed.length > 0 && options.allowLowContrast !== true) {
-            throw new Error(`contrast below WCAG AA:\n${report(failed)}\n${CONTRAST_HINT}`);
-        }
-        const written = surfaces(brand, options.tagline ?? '');
-        const contrast = findings.map((f) => ({ what: f.what, ratio: f.ratio, passes: f.passes }));
-        if (options.out === undefined) {
-            return { flag: defineBurgee(brand).flag(MASTER), files: [], contrast };
-        }
-        mkdirSync(options.out, { recursive: true });
-        for (const s of written)
-            writeFileSync(join(options.out, s.file), `${s.svg}\n`);
-        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: {
-        noWatch: { type: 'boolean', description: 'load once and serve; do not watch for changes' },
-    },
-    effects: 'withheld',
-    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.noWatch !== true });
-        await handle.done;
-    },
-});
-export const migrateCommand = defineCommand({
-    name: 'migrate',
-    description: 'Rewrite commander and yargs imports to burgee’s drop-in front-ends, and report what changed',
-    arguments: [{ name: 'dir', description: 'the project to migrate. Defaults to the current directory', required: false }],
-    options: {
-        dryRun: { type: 'boolean', description: 'scan and report; write nothing' },
-        force: { type: 'boolean', description: 'migrate even though the git tree has uncommitted changes' },
-    },
-    effects: 'idempotent',
-    examples: [
-        { command: 'burgee migrate --dry-run', description: 'what it would change, without changing it' },
-        { command: 'burgee migrate --json', description: 'the same report as data; exit 1 when anything was refused' },
-    ],
-    run: async ({ positionals, options }) => {
-        const [{ migrate }, { host }] = await Promise.all([import('./migrate.js'), import('./runtime.js')]);
-        return await migrate({ dir: positionals[0] ?? host.cwd(), dryRun: options.dryRun === true, force: options.force === true });
-    },
-});
-export const pluginCheckCommand = defineCommand({
-    name: 'check',
-    description: 'Validate a burgee plugin, register it into a throwaway program, and report what it contributes',
-    arguments: [{ name: 'file', description: 'the plugin module to check' }],
-    effects: 'read_only',
-    examples: [
-        { command: 'burgee check ./my-plugin.mjs', description: 'what the plugin contributes, or why it was refused' },
-        { command: 'burgee check ./my-plugin.mjs --json', description: 'the same, as data; exit 1 on a refusal' },
-    ],
-    run: async ({ positionals }) => (await import('./check.js')).checkPlugin(positionals[0] ?? ''),
-});
-export const program = defineProgram({
-    name: 'burgee',
-    description: 'The agent-native CLI framework, and the tools that come with it',
-    commands: [brandCommand, devCommand, migrateCommand, pluginCheckCommand],
-});
+#!/usr/bin/env node
+import { run } from './execute.js';
+import { program } from './program.js';
 run(program);
+export * from './program.js';

package/dist/commander/command.d.ts

@@ -14,6 +14,7 @@ import { EventEmitter } from 'node:events';
  *     then reports through the E1 taxonomy — the harness's seam (T1).
  */
 import * as crossSpawn from 'bellpull/cross-spawn';
+import { ExitCode } from '../exit-code.js';
 import { type DeclaredEffects, Manifest, type OptionSpec, type Plugin } from '../manifest.js';
 import { Argument, type ParseArg } from './argument.js';
 import { CommanderError } from './error.js';
@@ -261,6 +262,14 @@ export declare class Command extends EventEmitter {
     error(message: string, errorOptions?: ErrorOptions): never;
     /** One failure as the envelope (E3, G5); `fix` only when one candidate was named. */
     _reportJson(code: string, message: string): void;
+    /** The failure envelope on stdout, once per run however many paths see the same failure (G5). */
+    _writeFailure(error: Record<string, unknown>): void;
+    /**
+     * A handler's failure — a throw, a rejection, a thrown non-Error — reported on the surface the
+     * run asked for, with the E1 code its error names: `AuthError` is AUTH, `UsageError` USAGE,
+     * anything else RUNTIME (E6, D-140). Returns that code.
+     */
+    _reportHandlerFailure(err: unknown): ExitCode;
     /** Apply environment variables to options that have no value from the cli or client code. */
     _parseOptionsEnv(): void;
     /** Apply implied option values where the option is undefined or at its default. */
@@ -329,7 +338,17 @@ export declare class Command extends EventEmitter {
      */
     get manifest(): Manifest;
     _project(manifest: Manifest): void;
-    /** Options as the manifest describes them, on a null-prototype record. */
+    /**
+     * Options as the manifest describes them, on a null-prototype record — keyed so that the
+     * spelling every surface derives from a key, `--${kebab(key)}`, is a flag commander accepts.
+     *
+     * Commander negates only what it was told to, where burgee's own parser negates every
+     * boolean. So a boolean is `negatable` here only when the program declared its `--no-` twin,
+     * which folds onto it rather than appearing twice; and a `--no-x` declared alone, which has
+     * no `--x`, is described as the switch it is, under `noX`. Before this, `--no-color` was
+     * published as `color` with `flag: '--color'`: completions offered `--color` and
+     * `--no-skip-blank`, and `--mcp` sent `--color` — each refused by the parser behind them.
+     */
     _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: DeclaredEffects): this;
@@ -352,6 +371,19 @@ export declare class Command extends EventEmitter {
     _prepareBurgee(parseOptions?: BurgeeParseOptions): ParseOptions | undefined;
     /** In burgee mode the whole run settles to one E1 exit; otherwise commander's behaviour, untouched. */
     _runBurgee(run: () => unknown): unknown;
+    /**
+     * Nothing injected — `program.parseAsync(process.argv)`, the way every commander program is
+     * run. Commander's own contract, with one exception: a handler that fails under `--json`
+     * settles to the envelope on stdout and the E1 code its error names, set as the process's
+     * exit code, instead of escaping `parse`/`parseAsync` for Node to print as a stack (D-140).
+     *
+     * The seam check in `_runBurgee` cannot see this case, and that was the defect: it runs
+     * before argv is parsed, and `--json` is only recognised *during* the parse, so the run was
+     * already committed to "no burgee" when the handler threw. A `CommanderError` is left alone —
+     * `error()` has reported it already, and an `exitOverride` caller is owed the throw — and so
+     * is every failure without `--json`, which is commander's to surface as it always has.
+     */
+    _runCommanderWay(run: () => unknown): unknown;
     /** Any command from here down declares this flag, so burgee does not serve it: additive only. */
     _declares(flag: string): boolean;
     /** The action, wrapped in the plugin hooks and followed by the envelope or the rendering. */

package/dist/commander/command.js

@@ -4,7 +4,9 @@ import path from 'node:path';
 import { stripVTControlCharacters } from 'node:util';
 import * as crossSpawn from 'bellpull/cross-spawn';
 import { ExitCode } from '../exit-code.js';
+import { handlerFailure } from '../facade-failure.js';
 import { Manifest } from '../manifest.js';
+import { camel } from '../names.js';
 import { host } from '../runtime.js';
 import { machineJson, schemaOf } from '../schema.js';
 import { suggestSimilar } from '../suggest.js';
@@ -1034,13 +1036,24 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
         this._exit(exitCode, code, message);
     }
     _reportJson(code, message) {
+        const [first = '', ...rest] = message.replace(/^error: /, '').split('\n');
+        const guess = /\(Did you mean (\S+)\?\)/.exec(rest.join(''));
+        this._writeFailure({ code, message: first, ...(guess === null ? {} : { fix: guess[1] }) });
+    }
+    _writeFailure(error) {
         const burgee = this._root()._burgee;
         if (burgee === undefined || !burgee.json || burgee.reported)
             return;
         burgee.reported = true;
-        const [first = '', ...rest] = message.replace(/^error: /, '').split('\n');
-        const guess = /\(Did you mean (\S+)\?\)/.exec(rest.join(''));
-        this._outputConfiguration.writeOut(`${JSON.stringify({ ok: false, error: { code, message: first, ...(guess === null ? {} : { fix: guess[1] }) } })}\n`);
+        this._outputConfiguration.writeOut(`${JSON.stringify({ ok: false, error })}\n`);
+    }
+    _reportHandlerFailure(err) {
+        const { exit, error } = handlerFailure(err);
+        if (this._burgee?.json === true)
+            this._writeFailure(error);
+        else
+            this._outputConfiguration.writeErr(`error: ${error.message}\n`);
+        return exit;
     }
     _parseOptionsEnv() {
         for (const option of this.options) {
@@ -1413,6 +1426,10 @@ Expecting one of '${HELP_POSITIONS.join("', '")}'`);
     _optionSpecs() {
         const specs = Object.create(null);
         for (const option of this.options) {
+            const name = option.attributeName();
+            const paired = this.options.some((o) => o.negate !== option.negate && o.attributeName() === name);
+            if (option.negate && paired)
+                continue;
             const spec = { type: option.required || option.optional ? 'string' : 'boolean' };
             if (option.description)
                 spec.description = option.description;
@@ -1424,7 +1441,9 @@ Expecting one of '${HELP_POSITIONS.join("', '")}'`);
                 spec.default = option.defaultValue;
             if (option.envVar)
                 spec.env = option.envVar;
-            Object.defineProperty(specs, option.attributeName(), { value: spec, enumerable: true, writable: true, configurable: true });
+            if (spec.type === 'boolean')
+                spec.negatable = paired;
+            Object.defineProperty(specs, option.negate ? camel(option.name()) : name, { value: spec, enumerable: true, writable: true, configurable: true });
         }
         return specs;
     }
@@ -1510,7 +1529,7 @@ Expecting one of '${HELP_POSITIONS.join("', '")}'`);
         const root = this._root();
         const burgee = root._burgee;
         if (burgee === undefined)
-            return run();
+            return root._runCommanderWay(run);
         const finish = (code) => {
             root._burgee = undefined;
             burgee.exit?.(code);
@@ -1522,12 +1541,7 @@ Expecting one of '${HELP_POSITIONS.join("', '")}'`);
                 finish(e1(err));
                 return;
             }
-            const message = err instanceof Error ? err.message : String(err);
-            if (burgee.json)
-                root._reportJson('runtime', message);
-            else
-                root._outputConfiguration.writeErr(`error: ${message}\n`);
-            finish(ExitCode.RUNTIME);
+            finish(root._reportHandlerFailure(err));
         };
         try {
             const result = run();
@@ -1541,6 +1555,30 @@ Expecting one of '${HELP_POSITIONS.join("', '")}'`);
             return undefined;
         }
     }
+    _runCommanderWay(run) {
+        const done = () => {
+            this._burgee = undefined;
+        };
+        const fail = (err) => {
+            const json = this._burgee?.json === true && !(err instanceof CommanderError);
+            if (json)
+                host.exitCode = this._reportHandlerFailure(err);
+            done();
+            if (!json)
+                throw err;
+        };
+        try {
+            const result = run();
+            if (isThenable(result))
+                return Promise.resolve(result).then(done, fail);
+            done();
+            return undefined;
+        }
+        catch (err) {
+            fail(err);
+            return undefined;
+        }
+    }
     _declares(flag) {
         return this._findOption(flag) !== undefined || this.commands.some((sub) => sub._declares(flag));
     }

package/dist/compat.d.ts

@@ -26,5 +26,42 @@ export interface Graded {
     /** `passed / reference`, carried rather than recomputed so it is the oracle's own division. */
     rate: number;
 }
-/** The two hosts `migrate` rewrites, and nothing else — a row here without a mapping would claim a path that does not exist. */
-export declare const GRADED: Readonly<Record<string, Graded>>;
+/** One host's grade, with the control beside it: the incumbent's own suite run against the incumbent in the same harness. */
+export interface Row extends Graded {
+    /**
+     * Cases the incumbent itself passes here — from the published compatibility page, which
+     * `npm run compat:page` generates on ubuntu. A drop-in that passes as many as the control
+     * is **level**: every case it misses, the incumbent misses too, in this harness.
+     */
+    control: number;
+}
+/**
+ * Every host the oracle grades, keyed by its `hosts.ts` name. The lock holds `reference`,
+ * `passed` and `rate` equal to `baseline/<host>.json` and `control` equal to the page's
+ * control column.
+ */
+export declare const GRADED: Readonly<Record<string, Row>>;
+/** One graded path: an incumbent's specifier, and the family specifier that replaces it. */
+export interface DropIn {
+    /** The `hosts.ts` name, which keys `GRADED`. */
+    host: string;
+    from: string;
+    to: string;
+}
+/**
+ * Every drop-in pair the oracle grades, derived from `hosts.ts`: `from` is what the
+ * incumbent's own tests import (`<host><subpath>`, or the import's `control` where the
+ * incumbent is a separate package, as `yargs-parser` is), `to` is `<target><subpath>`.
+ * `scripts/migrate-drop-ins-lock.test.ts` re-derives this list and fails on any difference.
+ */
+export declare const DROP_INS: readonly DropIn[];
+/**
+ * The version each incumbent package was graded at: `vendor/<host>/.source.json`, or for
+ * `yargs-parser` the copy the yargs control resolves. The grade is for that major and no other
+ * — `signal-exit` 3 exports a function where 4 exports `onExit`, and `chalk` 4 is CommonJS where
+ * 6 is not — so `migrate` leaves a project on another major alone and says so.
+ * `scripts/migrate-drop-ins-lock.test.ts` holds each equal to the oracle's.
+ */
+export declare const GRADED_VERSIONS: Readonly<Record<string, string>>;
+/** Level: the drop-in passes every case the incumbent passes against its own suite (D-137). */
+export declare const isLevel: (host: string) => boolean;

package/dist/compat.js

@@ -1,4 +1,92 @@
 export const GRADED = {
-    commander: { reference: 1360, passed: 1360, rate: 1 },
-    yargs: { reference: 804, passed: 804, rate: 1 },
+    commander: { reference: 1360, passed: 1360, rate: 1, control: 1360 },
+    yargs: { reference: 804, passed: 804, rate: 1, control: 802 },
+    chalk: { reference: 58, passed: 58, rate: 1, control: 58 },
+    ora: { reference: 99, passed: 99, rate: 1, control: 99 },
+    'log-update': { reference: 99, passed: 99, rate: 1, control: 99 },
+    boxen: { reference: 84, passed: 84, rate: 1, control: 84 },
+    'cli-table3': { reference: 29, passed: 29, rate: 1, control: 29 },
+    'string-width': { reference: 229, passed: 229, rate: 1, control: 229 },
+    'strip-ansi': { reference: 8, passed: 8, rate: 1, control: 8 },
+    'cross-spawn': { reference: 68, passed: 68, rate: 1, control: 68 },
+    which: { reference: 5, passed: 5, rate: 1, control: 5 },
+    rc: { reference: 1, passed: 1, rate: 1, control: 1 },
+    'wrap-ansi': { reference: 80, passed: 80, rate: 1, control: 80 },
+    'slice-ansi': { reference: 15, passed: 15, rate: 1, control: 15 },
+    cosmiconfig: { reference: 243, passed: 186, rate: 0.7654320987654321, control: 240 },
+    lilconfig: { reference: 77, passed: 77, rate: 1, control: 77 },
+    dotenv: { reference: 141, passed: 106, rate: 0.75177304964539, control: 141 },
+    clack: { reference: 17, passed: 14, rate: 0.8235294117647058, control: 17 },
+    'inquirer-core': { reference: 41, passed: 41, rate: 1, control: 41 },
+    meow: { reference: 148, passed: 132, rate: 0.8918918918918919, control: 146 },
+    'ansi-escapes': { reference: 4, passed: 4, rate: 1, control: 4 },
+    'terminal-link': { reference: 8, passed: 8, rate: 1, control: 8 },
+    'term-img': { reference: 18, passed: 12, rate: 0.6666666666666666, control: 18 },
+    'restore-cursor': { reference: 6, passed: 6, rate: 1, control: 6 },
+    'exit-hook': { reference: 21, passed: 21, rate: 1, control: 21 },
+    'signal-exit': { reference: 135, passed: 134, rate: 0.9925925925925926, control: 134 },
+};
+export const DROP_INS = [
+    { host: 'commander', from: 'commander', to: 'burgee/commander' },
+    { host: 'yargs', from: 'yargs', to: 'burgee/yargs' },
+    { host: 'yargs', from: 'yargs/helpers', to: 'burgee/yargs/helpers' },
+    { host: 'yargs', from: 'yargs-parser', to: 'burgee/yargs/parser' },
+    { host: 'chalk', from: 'chalk', to: 'roundel/chalk' },
+    { host: 'ora', from: 'ora', to: 'flagstaff/ora' },
+    { host: 'log-update', from: 'log-update', to: 'flagstaff/log-update' },
+    { host: 'boxen', from: 'boxen', to: 'flagstaff/boxen' },
+    { host: 'cli-table3', from: 'cli-table3', to: 'flagstaff/cli-table3' },
+    { host: 'string-width', from: 'string-width', to: 'linegauge' },
+    { host: 'strip-ansi', from: 'strip-ansi', to: 'linegauge/strip' },
+    { host: 'cross-spawn', from: 'cross-spawn', to: 'bellpull/cross-spawn' },
+    { host: 'which', from: 'which', to: 'bellpull/node-which' },
+    { host: 'rc', from: 'rc', to: 'seniority/rc' },
+    { host: 'wrap-ansi', from: 'wrap-ansi', to: 'linegauge/wrap' },
+    { host: 'slice-ansi', from: 'slice-ansi', to: 'linegauge/slice' },
+    { host: 'cosmiconfig', from: 'cosmiconfig', to: 'seniority' },
+    { host: 'lilconfig', from: 'lilconfig', to: 'seniority/lilconfig' },
+    { host: 'dotenv', from: 'dotenv', to: 'seniority/dotenv' },
+    { host: 'clack', from: '@clack/prompts', to: 'caique/clack' },
+    { host: 'inquirer-core', from: '@inquirer/core', to: 'caique/inquirer' },
+    { host: 'meow', from: 'meow', to: 'burgee/meow' },
+    { host: 'ansi-escapes', from: 'ansi-escapes', to: 'paratext' },
+    { host: 'terminal-link', from: 'terminal-link', to: 'paratext/terminal-link' },
+    { host: 'term-img', from: 'term-img', to: 'paratext/term-img' },
+    { host: 'restore-cursor', from: 'restore-cursor', to: 'closeout/restore-cursor' },
+    { host: 'exit-hook', from: 'exit-hook', to: 'closeout/exit-hook' },
+    { host: 'signal-exit', from: 'signal-exit', to: 'closeout/signal-exit' },
+    { host: 'signal-exit', from: 'signal-exit/signals', to: 'closeout/signal-exit/signals' },
+];
+export const GRADED_VERSIONS = {
+    '@clack/prompts': '1.8.1',
+    '@inquirer/core': '12.0.3',
+    'ansi-escapes': '7.3.0',
+    boxen: '8.0.1',
+    chalk: '6.0.0',
+    'cli-table3': '0.6.5',
+    commander: '15.0.0',
+    cosmiconfig: '10.0.1',
+    'cross-spawn': '7.0.6',
+    dotenv: '17.4.2',
+    'exit-hook': '5.1.0',
+    lilconfig: '3.1.3',
+    'log-update': '8.0.0',
+    meow: '14.1.0',
+    ora: '9.4.1',
+    rc: '1.2.8',
+    'restore-cursor': '5.1.0',
+    'signal-exit': '4.1.0',
+    'slice-ansi': '7.1.2',
+    'string-width': '8.2.2',
+    'strip-ansi': '7.2.0',
+    'term-img': '7.1.0',
+    'terminal-link': '5.0.0',
+    which: '7.0.0',
+    'wrap-ansi': '10.0.1',
+    yargs: '18.1.0',
+    'yargs-parser': '22.0.0',
+};
+export const isLevel = (host) => {
+    const row = GRADED[host];
+    return row !== undefined && row.passed >= row.control;
 };

package/dist/complete-dynamic.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Copyright (c) 2026 Ofri Peretz
+ * Licensed under the MIT License. Use of this source code is governed by the
+ * MIT license that can be found in the LICENSE file.
+ */
+/**
+ * D3 / D-119 — the program's side of a dynamic completion. A generated script calls
+ * `<program> __complete <command…> --<option> <partial>` for an option that declared
+ * `complete`, and prints what comes back, one candidate per line.
+ *
+ * It never fails loudly. A TAB that prints an error into someone's prompt is worse than one
+ * that offers nothing, so an unknown command, an option without a completer, or a completer
+ * that throws all print nothing and leave 0.
+ *
+ * Imported by `execute.ts` only when argv starts with `__complete` (M2).
+ */
+import { type Manifest } from './manifest.js';
+export declare function completeDynamic(manifest: Manifest, argv: readonly string[], write: (s: string) => unknown): Promise<void>;

package/dist/complete-dynamic.js

@@ -0,0 +1,19 @@
+import { kebab } from './names.js';
+export async function completeDynamic(manifest, argv, write) {
+    const flag = argv.findIndex((a) => a.startsWith('--'));
+    if (flag === -1)
+        return;
+    const { node } = manifest.resolve(argv.slice(0, flag), manifest.rootPath);
+    const name = argv[flag]?.slice(2);
+    const spec = Object.entries(node?.options ?? {}).find(([key]) => kebab(key) === name)?.[1];
+    if (spec?.complete === undefined)
+        return;
+    const partial = argv[flag + 1] ?? '';
+    const { complete } = spec;
+    const offered = await Promise.resolve()
+        .then(async () => [...(await complete(partial))])
+        .then((all) => all, () => []);
+    const found = offered.filter((c) => c.startsWith(partial));
+    if (found.length > 0)
+        write(`${found.join('\n')}\n`);
+}