burgee 0.6.0 → 0.7.0

package/dist/plugin.d.ts

@@ -0,0 +1,48 @@
+import { type CommandNode, type Hook } from './manifest.js';
+/**
+ * The plugin contract version. One number for the family — the same `1` flagstaff, caique and
+ * closeout declare, written out rather than imported because a layer never imports a layer.
+ */
+export declare const CONTRACT = 1;
+/**
+ * The keys burgee reads. Declared structurally: any object with these fields is a plugin here,
+ * whatever else it carries.
+ */
+export interface Plugin {
+    name: string;
+    contract?: number;
+    commands?: CommandNode[];
+    hooks?: {
+        preRun?: Hook;
+        postRun?: Hook;
+        onError?: Hook;
+    };
+    enforce?: 'pre' | 'post';
+}
+export type PluginErrorCode = 'E_PLUGIN_SCHEMA' | 'E_PLUGIN_CONTRACT';
+/** A refused plugin says what is wrong and what to do about it — the family's one vocabulary. */
+export declare class PluginError extends Error {
+    readonly code: PluginErrorCode;
+    readonly fix: string;
+    constructor(code: PluginErrorCode, message: string, fix: string);
+}
+/**
+ * Refuse a plugin that cannot contribute, at the door.
+ *
+ * `taken` is the command paths the manifest already serves. A contributed path that is already
+ * declared is refused rather than merged, because the two projections disagree about which
+ * node wins: `find()` answers the first on a path and `resolve()` the last, so the same
+ * command reads one way to help and the other way to dispatch. Which of the two is right for a
+ * *first-party* duplicate is a decision about every program rather than about plugins, and is
+ * left alone here.
+ */
+export declare function validate(plugin: unknown, taken?: readonly string[]): asserts plugin is Plugin;
+/**
+ * Declare a plugin: typed, validated, and stamped with the contract it was compiled against.
+ *
+ * The stamp is the half that makes the refusal in `checkContract` fair. An author who builds
+ * against this burgee gets `contract: 1` without typing it, so the only objects that reach
+ * `use()` without one are objects built against a burgee that checked nothing — which is
+ * exactly the population the version message is addressed to.
+ */
+export declare function definePlugin(plugin: Plugin): Plugin;

package/dist/plugin.js

@@ -0,0 +1,82 @@
+import { checkCommand } from './definition.js';
+export const CONTRACT = 1;
+const UNVALIDATED = '0.6.1';
+export class PluginError extends Error {
+    code;
+    fix;
+    constructor(code, message, fix) {
+        super(message);
+        this.code = code;
+        this.fix = fix;
+        this.name = 'PluginError';
+    }
+}
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const ENFORCE = ['pre', 'post'];
+const STAGES = ['preRun', 'postRun', 'onError'];
+const schema = (message, fix) => new PluginError('E_PLUGIN_SCHEMA', message, fix);
+export function validate(plugin, taken = []) {
+    if (!isRecord(plugin))
+        throw schema('a plugin is a plain object', 'export an object, not a function or an array');
+    const name = plugin['name'];
+    if (typeof name !== 'string' || name === '') {
+        throw schema('a plugin needs a name', 'add `name: "…"` — it is what a contributed command is attributed to');
+    }
+    checkContract(plugin['contract'], name);
+    const enforce = plugin['enforce'];
+    if (enforce !== undefined && !ENFORCE.includes(enforce)) {
+        throw schema(`plugin "${name}": ${JSON.stringify(enforce)} is not an enforce`, `use ${ENFORCE.join(' or ')}, or leave it out`);
+    }
+    checkHooks(plugin['hooks'], name);
+    checkCommands(plugin['commands'], name, taken);
+}
+function checkContract(contract, name) {
+    if (contract === undefined) {
+        throw new PluginError('E_PLUGIN_CONTRACT', `plugin "${name}" declares no contract; burgee ${UNVALIDATED} and earlier validated none of it`, `rebuild it against this burgee — \`definePlugin\` from \`burgee/plugin\` stamps \`contract: ${CONTRACT}\` — or add that key by hand`);
+    }
+    if (!Number.isInteger(contract) || contract < 1 || contract > CONTRACT) {
+        throw new PluginError('E_PLUGIN_CONTRACT', `plugin "${name}" declares contract ${String(contract)}; this burgee knows ${CONTRACT}`, 'upgrade burgee, or lower the plugin’s contract');
+    }
+}
+function checkHooks(hooks, name) {
+    if (hooks === undefined)
+        return;
+    if (!isRecord(hooks))
+        throw schema(`plugin "${name}": hooks must be an object`, 'map a stage to a hook: `{ preRun: { filter?, handler } }`');
+    for (const [stage, hook] of Object.entries(hooks)) {
+        if (!STAGES.includes(stage))
+            throw schema(`plugin "${name}": "${stage}" is not a hook stage`, `use one of ${STAGES.join(', ')}`);
+        if (!isRecord(hook) || typeof hook['handler'] !== 'function') {
+            throw schema(`plugin "${name}": ${stage} has no handler()`, 'add `handler(ctx)` — without one the TypeError arrives at fire() time, a run later');
+        }
+    }
+}
+function checkCommands(commands, name, taken) {
+    if (commands === undefined)
+        return;
+    if (!Array.isArray(commands))
+        throw schema(`plugin "${name}": commands must be an array`, 'list them in an array of `{ path, options, … }` nodes');
+    const seen = new Set(taken);
+    for (const [index, node] of commands.entries()) {
+        const at = `plugin "${name}": commands[${index}]`;
+        if (!isRecord(node) || !Array.isArray(node['path']) || node['path'].length === 0) {
+            throw schema(`${at} has no path`, 'add `path: ["…"]` — the words a user types');
+        }
+        const path = node['path'].join(' ');
+        if (seen.has(path)) {
+            throw schema(`${at} contributes "${path}", which is already declared`, 'rename it — find() answers the first node on a path and resolve() the last');
+        }
+        seen.add(path);
+        try {
+            checkCommand(path, (node['options'] ?? {}), node['effects'], node['run'] !== undefined || node['load'] !== undefined);
+        }
+        catch (error) {
+            throw schema(`${at}: ${error.message}`, 'a plugin command is declared exactly as a first-party one');
+        }
+    }
+}
+export function definePlugin(plugin) {
+    const stamped = { ...plugin, contract: plugin.contract ?? CONTRACT };
+    validate(stamped);
+    return stamped;
+}

package/dist/runtime.d.ts

@@ -35,5 +35,61 @@ export interface Runtime {
     /** `performance.now` and `setTimeout` in the real runtime; a manual tick in the harness. */
     clock: Clock;
 }
-/** The one place in the layer that touches `process`. Locked by `process-reference.lock.test.ts`. */
+/**
+ * The one place in the layer that names `process` — the whole of Y9. Every other file in
+ * this package reads it through `host` or through an injected `Runtime`, which is what
+ * `process-reference-lock.test.ts` enforces.
+ *
+ * **Every member is a getter, and that is the load-bearing decision.** burgee's commander
+ * and yargs front-ends do not wrap those packages, they *reproduce their process contracts*,
+ * and the incumbents' own suites grade exactly that contract: yargs' swaps `process.argv`,
+ * `process.exit` and `process.env` per test; commander's grades `process.argv` when `parse()`
+ * is called bare, `process.exit` with no `exitOverride`, and `process.env` for `Option.env()`.
+ * A seam that captured those at import — which is what `processRuntime` below does, and what
+ * it did for the whole object before this file grew a second export — would hand such a test
+ * the value from before its own swap, and the row would drop from 1360 / 804.
+ *
+ * Getters rather than paratext's `processRuntime()` function shape, because these are read in
+ * expression position all over both front-ends (`host.stdout.columns`, `host.env[name]`), and
+ * a function would put a call on every one of them; the getter keeps the port reading the way
+ * the upstream reads, which is the thing yargs' whole-help-screen assertions compare.
+ *
+ * Reads are live; *when* a call site reads is unchanged by this file. Two of them capture on
+ * purpose and still do — `shim.ts`'s `stdColumns` and `mainFilename` are values in
+ * `PlatformShim`, not thunks, and were evaluated at import before the seam existed.
+ */
+export declare const host: {
+    /** Raw and unsliced: commander and yargs each do their own `from`-dependent slicing. */
+    readonly argv: string[];
+    readonly env: Record<string, string | undefined>;
+    cwd(): string;
+    readonly stdin: NodeJS.ReadStream;
+    readonly stdout: NodeJS.WriteStream;
+    readonly stderr: NodeJS.WriteStream;
+    /**
+     * The terminal's width, or undefined when there is no terminal to ask. Guarded on
+     * `process` itself because cliui's upstream is guarded there: `getWindowWidth` is reached
+     * from a bundle that may have no process at all, and a bare read would be a ReferenceError
+     * rather than the 80-column fallback.
+     */
+    readonly columns: number | undefined;
+    readonly exitCode: number | string | null | undefined;
+    readonly platform: string;
+    readonly execPath: string;
+    readonly execArgv: string[];
+    readonly versions: NodeJS.ProcessVersions;
+    /** Electron sets this on the process object; yargs' bin detection asks for it by name. */
+    readonly defaultApp: boolean;
+    exit(code?: number): never;
+    emitWarning(warning: string | Error, type?: string): void;
+    nextTick(fn: (...args: unknown[]) => void, ...args: unknown[]): void;
+    on(event: string, listener: (...args: unknown[]) => void): void;
+};
+/**
+ * The real `Runtime`, for a caller that injects none.
+ *
+ * `argv`, `env` and `cwd` are getters for the reason the block above gives; `isTTY` is one
+ * too, because a stream's `isTTY` is a property of whatever stream is installed *now*, and
+ * the harness swaps streams. `stdin`/`stdout`/`stderr` likewise.
+ */
 export declare const processRuntime: Runtime;

package/dist/runtime.js

@@ -1,18 +1,87 @@
 const ARGV_PROGRAM_AND_SCRIPT = 2;
+export const host = {
+    get argv() {
+        return process.argv;
+    },
+    get env() {
+        return process.env;
+    },
+    cwd() {
+        return process.cwd();
+    },
+    get stdin() {
+        return process.stdin;
+    },
+    get stdout() {
+        return process.stdout;
+    },
+    get stderr() {
+        return process.stderr;
+    },
+    get columns() {
+        if (typeof process === 'undefined')
+            return undefined;
+        return process.stdout?.columns;
+    },
+    get exitCode() {
+        return process.exitCode;
+    },
+    get platform() {
+        return process.platform;
+    },
+    get execPath() {
+        return process.execPath;
+    },
+    get execArgv() {
+        return process.execArgv;
+    },
+    get versions() {
+        return process.versions;
+    },
+    get defaultApp() {
+        return Reflect.get(process, 'defaultApp') === true;
+    },
+    exit(code) {
+        return process.exit(code);
+    },
+    emitWarning(warning, type) {
+        process.emitWarning(warning, type);
+    },
+    nextTick(fn, ...args) {
+        process.nextTick(fn, ...args);
+    },
+    on(event, listener) {
+        process.on(event, listener);
+    },
+};
 export const processRuntime = {
-    argv: process.argv.slice(ARGV_PROGRAM_AND_SCRIPT),
-    env: process.env,
-    cwd: process.cwd(),
-    stdin: process.stdin,
-    stdout: process.stdout,
-    stderr: process.stderr,
-    isTTY: {
-        stdin: Boolean(process.stdin.isTTY),
-        stdout: Boolean(process.stdout.isTTY),
-        stderr: Boolean(process.stderr.isTTY),
+    get argv() {
+        return host.argv.slice(ARGV_PROGRAM_AND_SCRIPT);
+    },
+    get env() {
+        return host.env;
+    },
+    get cwd() {
+        return host.cwd();
+    },
+    get stdin() {
+        return host.stdin;
+    },
+    get stdout() {
+        return host.stdout;
+    },
+    get stderr() {
+        return host.stderr;
+    },
+    get isTTY() {
+        return {
+            stdin: Boolean(host.stdin.isTTY),
+            stdout: Boolean(host.stdout.isTTY),
+            stderr: Boolean(host.stderr.isTTY),
+        };
     },
     exit(code) {
-        process.exit(code);
+        return host.exit(code);
     },
     clock: {
         now: () => performance.now(),

package/dist/schema.d.ts

@@ -4,7 +4,7 @@
  * manifest and nothing else. Choices are carried as data (N9), the same data that becomes
  * an MCP tool's input schema.
  */
-import type { ArgumentSpec, CommandNode, Effects, Example, Manifest, OptionSpec } from './manifest.js';
+import { type ArgumentSpec, type CommandNode, type DeclaredEffects, type Example, type Manifest, type OptionSpec } from './manifest.js';
 export interface JsonSchema {
     type: 'object';
     properties: Record<string, JsonSchemaProperty>;
@@ -26,13 +26,29 @@ export interface JsonSchemaProperty {
     flag?: string;
     /** The shared set this option was copied from (M4). */
     sharedFrom?: string;
+    /**
+     * The flags this option requires, and the flags it excludes — as the caller types them, not
+     * as the handler reads them, because the reader of this document is composing a command line
+     * (S5). Both are also in the command's `relations`; here they are on the property an agent is
+     * already looking at, which is the difference between reading a constraint and finding one.
+     *
+     * Omitted when the option declares none, so absent reads as "no constraint" rather than
+     * "constraints not published" — the rule `relations` follows one level up.
+     */
+    dependsOn?: string[];
+    exclusive?: string[];
 }
 export interface CommandSchema {
     /** The command as typed, without the program name: `config get`. */
     name: string;
     description?: string;
     summary?: string;
-    effects?: Effects;
+    /**
+     * What running it does, or `'withheld'` — published either way, because an agent reading
+     * the program as data is better served by *this exists and is not for you* than by a gap
+     * it cannot tell from a command that does not exist (N6).
+     */
+    effects?: DeclaredEffects;
     deprecated?: boolean | string;
     /** The heading it is listed under (M1). */
     group?: string;
@@ -102,7 +118,7 @@ export interface SchemaSummary {
     commands: {
         name: string;
         summary?: string;
-        effects?: Effects;
+        effects?: DeclaredEffects;
     }[];
     hint: string;
 }

package/dist/schema.js

@@ -1,4 +1,5 @@
-import { kebab } from './names.js';
+import { relationsOf } from './manifest.js';
+import { flagsOf, kebab } from './names.js';
 export const PREDICATE = '(predicate)';
 function publishable(relation) {
     if (!('implies' in relation))
@@ -39,6 +40,10 @@ function optionProperty(name, spec) {
         p.maximum = spec.maximum;
     if (spec.sharedFrom !== undefined)
         p.sharedFrom = spec.sharedFrom;
+    if (spec.dependsOn !== undefined && spec.dependsOn.length > 0)
+        p.dependsOn = flagsOf(spec.dependsOn);
+    if (spec.exclusive !== undefined && spec.exclusive.length > 0)
+        p.exclusive = flagsOf(spec.exclusive);
     return p;
 }
 export function inputSchemaOf(node) {
@@ -83,8 +88,9 @@ export function commandSchemaOf(node, root) {
         out.lazy = true;
     if (node.plugin !== undefined)
         out.plugin = node.plugin;
-    if (node.relations !== undefined && node.relations.length > 0)
-        out.relations = node.relations.map(publishable);
+    const relations = relationsOf(node);
+    if (relations.length > 0)
+        out.relations = relations.map(publishable);
     return out;
 }
 export function runnable(manifest) {

package/dist/schema.json

@@ -0,0 +1 @@
+{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://github.com/ofri-peretz/burgee/blob/main/packages/flagstaff/src/schema.json","title":"flagstaff plugin","description":"A plugin is one plain object. Everything in it is data that can be read without running it; the only functions allowed are a component's `static` (required) and `frame` (optional). A spinner or component without a static projection is refused at register().","type":"object","required":["name"],"additionalProperties":true,"properties":{"name":{"type":"string","minLength":1,"description":"The plugin's name; also the prefix a host may use when two plugins contribute the same key."},"contract":{"type":"integer","minimum":1,"description":"The plugin contract this object follows. A host refuses a newer contract than it knows."},"tokens":{"type":"object","description":"A roundel theme: semantic token name to a hex colour, contrast-checked when flown.","additionalProperties":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"propertyNames":{"enum":["error","warn","ok","hint","muted","command","flag","value","heading","ground"],"description":"roundel's ten semantic tokens, and nothing else — `roundel`'s own validate() refuses any other name."}},"glyphs":{"type":"object","description":"Symbols by meaning: `ok`, `fail`, `warn`, `info`, `running`. A plugin that ships glyphs changes every built-in that draws one.","additionalProperties":{"type":"string","minLength":1}},"spinners":{"type":"object","description":"Spinner styles by name, in cli-spinners' shape plus the static projection.","additionalProperties":{"$ref":"#/$defs/spinner"}},"borders":{"type":"object","description":"Border styles a box can be drawn with, by name.","additionalProperties":{"$ref":"#/$defs/border"}},"components":{"type":"object","description":"Components by name: `static(state)` returns the text a pipe, an agent or a screen reader gets; `frame(t, state)` is the optional animated form.","additionalProperties":{"$ref":"#/$defs/component"}},"capabilities":{"$ref":"#/$defs/capabilities"}},"$defs":{"spinner":{"type":"object","required":["frames","interval","static"],"properties":{"frames":{"type":"array","items":{"type":"string"},"minItems":1},"interval":{"type":"integer","minimum":1,"description":"Milliseconds between frames on a terminal."},"static":{"type":"string","description":"What a pipe prints instead of the animation."}}},"component":{"type":"object","required":["static"],"properties":{"static":{"description":"(state) => string. Required: the projection every non-terminal mode prints."},"frame":{"description":"(t, state) => string. Optional: the frame at t milliseconds since hoisting."},"sample":{"type":"object","required":["running","done"],"description":"Two states to *show* this component with: `flagstaff check` and the docs gallery render `running` then `done`. Omitted, they assume `{ phase: 'running' }` and `{ phase: 'done' }` and say so in the output. The loop never reads it — a running program's state comes from the program.","properties":{"running":{"description":"The state to open with."},"done":{"description":"The state to close with."}}},"interval":{"type":"integer","minimum":1,"description":"Milliseconds between repaints when `frame` is given; 80 when omitted."}}},"border":{"type":"object","required":["topLeft","top","topRight","left","right","bottomLeft","bottom","bottomRight"],"description":"cli-boxes' shape exactly, so that corpus imports unchanged.","properties":{"topLeft":{"type":"string"},"top":{"type":"string"},"topRight":{"type":"string"},"left":{"type":"string"},"right":{"type":"string"},"bottomLeft":{"type":"string"},"bottom":{"type":"string"},"bottomRight":{"type":"string"}}},"capability":{"type":"object","required":["name","osc","when","encode","fallback"],"additionalProperties":false,"description":"One paratext capability: what it says to the terminal, when the terminal is believed to understand it, and what prints when it does not. No functions, so it travels through JSON. `encode` and `fallback` are templates: `{field}` is the field's value, `{field|base64}` is it base64-encoded, and `[ … ]` is emitted only when every field inside it has a value.","properties":{"name":{"type":"string","minLength":1,"description":"How callers name it. Registering an existing name replaces it — how a caller corrects a guess we got wrong."},"osc":{"description":"The OSC code this speaks, or 'BEL' for the bell and for protocols that are not OSC at all, such as Kitty's.","oneOf":[{"type":"integer","minimum":0},{"const":"BEL"}]},"when":{"type":"object","description":"When the terminal is believed to understand it. Every clause must hold; `termProgram` and `envAny` are ORs within themselves. Guesses — no terminal answers 'do you do OSC 1337' — and therefore data a caller can replace.","additionalProperties":false,"properties":{"tty":{"type":"boolean","description":"Refuse a pipe. Almost always true: a file that receives OSC gets control bytes in it."},"termProgram":{"type":"array","items":{"type":"string"},"description":"Any one of these TERM_PROGRAM values."},"envAny":{"type":"array","items":{"type":"string"},"description":"Any one of these environment variables merely being set, as VTE announces itself."},"term":{"type":"string","description":"An exact TERM — Kitty is xterm-kitty."}}},"encode":{"type":"string","minLength":1,"description":"The bytes, as a template, for a terminal that does understand."},"fallback":{"type":"string","description":"What to print when it does not — PRINCIPLES rule 6. '' is a legitimate answer, a window title having nothing to say in a log; absence is not, which is why this is required and may be ''."}},"examples":[{"name":"kitty-image","osc":"BEL","when":{"tty":true,"term":"xterm-kitty"},"encode":"\u001b_Ga=T,f=100;{base64}\u001b\\","fallback":"{caption}"}]},"capabilities":{"type":"object","description":"paratext capabilities by name — the OSC section of a plugin, read the way flagstaff reads `spinners`.","additionalProperties":{"$ref":"#/$defs/capability"}},"capabilityDocument":{"description":"What paratext's `check()` accepts. Two shapes, and only one of them survives 1.0.","oneOf":[{"description":"The family shape: a plugin carrying its capabilities under `capabilities`.","type":"object","required":["name","capabilities"],"properties":{"name":{"type":"string","minLength":1},"contract":{"type":"integer","minimum":1},"capabilities":{"$ref":"#/$defs/capabilities"}}},{"deprecated":true,"description":"Deprecated: one capability as the whole document, the shape paratext's schema had before this one absorbed it. Accepted for one minor release, removed at 1.0 — `check()` validates it and says so.","$ref":"#/$defs/capability"}]}}}

package/dist/shutdown.d.ts

@@ -0,0 +1,70 @@
+/**
+ * E5 and O5 — every door out of a burgee program, bound by the package whose job that is.
+ *
+ * `exit-code.ts` has declared `SIGINT: 130` and *"SIGINT after the terminal was restored"*
+ * since the contract was written, and `.sdlc/intents/burgee/design.md` marks both E5 and O5
+ * `R`. Neither was implemented. The engine's only exit was `host.exit(code)` — `process.exit`
+ * — which restores nothing, runs nothing, and truncates a pipe by definition (yargs #1519,
+ * #2118: *"No truncated JSON"*). A constant is not an implementation.
+ *
+ * Writing the listener here was the other option and it is the worse one, for a reason this
+ * repository can count: `caique`, `flagstaff` and `closeout` each had a copy of "restore the
+ * cursor on the way out" before closeout existed, and three copies of a signal handler is
+ * three answers to whether Ctrl-C during a spinner leaves the terminal usable. closeout's
+ * whole claim is the sentence burgee needs — bound every exit path, run the handlers exactly
+ * once, hand the terminal back **last** — and it grades 21/21 against `exit-hook`'s own suite
+ * and 6/6 against `restore-cursor`'s.
+ *
+ * ## The two registries, and why a run must say which it is
+ *
+ * A run either owns the process or it does not, and the difference is not cosmetic. The
+ * harness (`runCommand`), the MCP loop and every façade test inject their own `exit`; a
+ * registry that attached nine listeners to the process on their behalf would leak a listener
+ * per test and would exit the *test runner* on the first raised signal. So:
+ *
+ *   - `processTeardown` — the real CLI. `install()` wires `exit`, `beforeExit`, five signals,
+ *     `uncaughtException` and `unhandledRejection`, and burgee's drain goes in the `flush`
+ *     phase, which closeout runs before `release` and before `restore`.
+ *   - `detachedTeardown` — a run that owns no process. The same registry with no wiring, run
+ *     by the engine when the run ends.
+ *
+ * Both are run by the engine at the end of a run, and closeout's run-once state machine is
+ * what makes that safe: a signal that beats the engine to it wins, and the engine's own call
+ * finds the work already done rather than doing it twice. That is the property that lets the
+ * ordinary path be *awaited* — where `process.exit` would have abandoned an async handler —
+ * without giving up the signal path.
+ */
+import { type ProcessLike, type Registry } from 'closeout';
+/**
+ * The half of a stream a flush needs.
+ *
+ * Structural, so the engine can hand it `host.stdout` and a test can hand it eight bytes that
+ * only come out when somebody waits. `writableLength` is optional because a caller's injected
+ * `stdout` is a `{ write }` and has nothing buffered to begin with.
+ */
+export interface Drainable {
+    writableLength?: number;
+    write(chunk: string, callback?: () => void): unknown;
+}
+export interface Teardown {
+    /**
+     * Register cleanup for this run. Returns the function that unregisters it.
+     *
+     * `label` is what a breached deadline calls it. Worth passing: the default is the
+     * function's own `name`, which is right for `onExit(releaseTheLock)` and `(anonymous)` for
+     * the arrow that is the shape that actually hangs.
+     */
+    add(handler: () => void | Promise<void>, label?: string): () => void;
+    /** Run every handler, once, phase by phase, for a run leaving with `code`. */
+    run(code: number): Promise<void>;
+    /** closeout's registry, for the lock that grades which phase the drain went into. */
+    readonly registry: Registry;
+}
+/**
+ * The run that owns the process. `proc` is closeout's own seam (its design R7) and is passed
+ * only by a test — the memo is skipped for it, so a fake process never becomes the answer a
+ * later real run gets.
+ */
+export declare function processTeardown(streams: readonly Drainable[], proc?: ProcessLike): Teardown;
+/** A run that owns no process: the harness, the MCP loop, any caller that injected `exit`. */
+export declare function detachedTeardown(streams?: readonly Drainable[]): Teardown;

package/dist/shutdown.js

@@ -0,0 +1,27 @@
+import { createRegistry, install } from 'closeout';
+function drained(stream) {
+    if ((stream.writableLength ?? 0) === 0)
+        return Promise.resolve();
+    return new Promise((done) => {
+        stream.write('', () => done());
+    });
+}
+function teardownOf(registry, streams) {
+    registry.add(async function flushStreams() {
+        await Promise.all(streams.map(drained));
+    }, { phase: 'flush', label: 'burgee:flush' });
+    return {
+        add: (handler, label) => registry.add(handler, label === undefined ? 'release' : { phase: 'release', label }),
+        run: async (code) => void (await registry.run({ code, signal: null })),
+        registry,
+    };
+}
+let shared;
+export function processTeardown(streams, proc) {
+    if (proc !== undefined)
+        return teardownOf(install({ process: proc }).registry, streams);
+    return (shared ??= teardownOf(install().registry, streams));
+}
+export function detachedTeardown(streams = []) {
+    return teardownOf(createRegistry(), streams);
+}

package/dist/testing-helpers.js

@@ -1,6 +1,7 @@
 import { Readable } from 'node:stream';
 import { beforeTerminator, execute } from './execute.js';
 import { ExitCode, isExitCode } from './exit-code.js';
+import { host } from './runtime.js';
 export class RuntimeExit extends Error {
     code;
     constructor(code) {
@@ -74,14 +75,14 @@ const noop = () => undefined;
 export function swapEnv(env) {
     if (!env)
         return noop;
-    const saved = { ...process.env };
-    for (const key of Object.keys(process.env))
-        delete process.env[key];
-    Object.assign(process.env, env);
+    const saved = { ...host.env };
+    for (const key of Object.keys(host.env))
+        delete host.env[key];
+    Object.assign(host.env, env);
     return () => {
-        for (const key of Object.keys(process.env))
-            delete process.env[key];
-        Object.assign(process.env, saved);
+        for (const key of Object.keys(host.env))
+            delete host.env[key];
+        Object.assign(host.env, saved);
     };
 }
 const CONSOLE_METHODS = ['log', 'info', 'debug', 'warn', 'error'];

package/dist/unknown-option.d.ts

@@ -6,4 +6,5 @@ export declare function singleDashHint(argv: readonly string[]): string | undefi
 export declare function unknownOption(cause: unknown, declared: readonly string[]): {
     message: string;
     hint: string;
+    fix?: string;
 } | undefined;

package/dist/unknown-option.js

@@ -23,5 +23,6 @@ export function unknownOption(cause, declared) {
     return {
         message: `unknown option ${flag}`,
         hint: near === undefined ? 'run --help to see the available options' : `did you mean ${near}?`,
+        ...(near === undefined ? {} : { fix: near }),
     };
 }

package/dist/validate.d.ts

@@ -1,7 +1,9 @@
 /**
- * Definition-time checks (S3, S5, V5) and run-time validation in one fixed order (S6):
- * relations first, then each option's value — numbers, choices, Standard Schema. Every
- * failure is a usage error with the fix in hand (E3).
+ * Run-time validation in one fixed order (S6): relations first, then each option's value —
+ * numbers, choices, Standard Schema. Every failure is a usage error with the fix in hand (E3).
+ *
+ * The definition-time checks (S3, S5, V5) moved to `./definition.js` when the plugin host
+ * arrived; that file says why. This one runs on every invocation, that one runs once.
  */
 import { type OptionSpec, type Relation } from './manifest.js';
 /** A usage problem the caller can fix, carrying the flag that fixes it (E3). */
@@ -9,11 +11,6 @@ export declare class UsageError extends Error {
     readonly hint?: string | undefined;
     constructor(message: string, hint?: string | undefined);
 }
-/**
- * What must be true of a declaration before anything runs (yargs #1198, #887, #1679):
- * a known type, one short alias per command, no two keys that meet on the command line.
- */
-export declare function checkDefinition(name: string, options: Record<string, OptionSpec>): void;
 type Sources = Record<string, {
     source: string;
 }>;

package/dist/validate.js

@@ -1,4 +1,4 @@
-import { kebab } from './names.js';
+import { flagsOf, kebab } from './names.js';
 export class UsageError extends Error {
     hint;
     constructor(message, hint) {
@@ -6,31 +6,8 @@ export class UsageError extends Error {
         this.hint = hint;
     }
 }
-const TYPES = new Set(['string', 'boolean', 'number']);
-export function checkDefinition(name, options) {
-    const shorts = new Map();
-    const flags = new Map();
-    for (const [key, spec] of Object.entries(options)) {
-        if (!TYPES.has(spec.type))
-            throw new Error(`burgee: option "${key}" of "${name}" has unknown type "${String(spec.type)}"`);
-        if (spec.short !== undefined) {
-            const owner = shorts.get(spec.short);
-            if (owner !== undefined)
-                throw new Error(`burgee: options "${owner}" and "${key}" of "${name}" both use -${spec.short}`);
-            shorts.set(spec.short, key);
-        }
-        const flag = kebab(key);
-        const clash = flags.get(flag);
-        if (clash !== undefined)
-            throw new Error(`burgee: options "${clash}" and "${key}" of "${name}" are both --${flag}`);
-        flags.set(flag, key);
-        if ((spec.minimum !== undefined || spec.maximum !== undefined || spec.integer !== undefined) && spec.type !== 'number') {
-            throw new Error(`burgee: option "${key}" of "${name}" declares a numeric bound but is not a number`);
-        }
-    }
-}
 const isSet = (values, key, sources) => values[key] !== undefined && sources[key]?.source !== 'default';
-const flagList = (keys) => keys.map((k) => `--${kebab(k)}`).join(', ');
+const flagList = (keys) => flagsOf(keys).join(', ');
 function exactlyOne(keys, on) {
     if (on.length === 1)
         return;

package/dist/yargs/burgee.d.ts

@@ -4,14 +4,14 @@
  * this module projects that snapshot into the manifest every surface reads (J7, J8).
  * Nothing here runs at parse time unless a burgee surface was asked for.
  */
-import { type Effects, type Manifest, type OptionSpec } from '../manifest.js';
+import { type DeclaredEffects, type Manifest, type OptionSpec } from '../manifest.js';
 import type { Positional } from './utils.js';
 /** What one yargs instance (the root, or a command's builder run on a scratch) registered. */
 export interface Snapshot {
     name: string;
     version?: string | undefined;
     description?: string | undefined;
-    effects?: Effects | undefined;
+    effects?: DeclaredEffects | undefined;
     hasHandler: boolean;
     keys: string[];
     aliases: Record<string, string[]>;

package/dist/yargs/cliui.d.ts

@@ -1,21 +1,17 @@
+import { type WrapOptions } from "linegauge";
 /**
- * cliui 9 — the column layout yargs' usage renders through — with the string-width,
- * strip-ansi and wrap-ansi it depends on, ported for `burgee/yargs`. The wrapping
+ * cliui 9 — the column layout yargs' usage renders through — with the wrap-ansi it depends
+ * on, ported for `burgee/yargs`. Width and escape-stripping come from linegauge. The wrapping
  * arithmetic is byte-for-byte the upstream's: yargs' usage tests compare whole help
  * screens.
  */
-export declare function stripAnsi(str: string): string;
-export declare function stringWidth(input: string): number;
-interface WrapOptions {
-    hard?: boolean;
-    wordWrap?: boolean;
-    trim?: boolean;
-}
+export declare const stripAnsi: (str: string) => string;
+export declare const stringWidth: (input: string) => number;
 export declare function wrapAnsi(string: string, columns: number, options?: WrapOptions): string;
 export interface Column {
     text: string;
     width?: number | undefined;
-    align?: 'right' | 'left' | 'center';
+    align?: "right" | "left" | "center";
     padding: number[];
     border?: boolean;
 }