burgee 0.0.0 → 0.3.0

package/dist/pkg.d.ts

@@ -0,0 +1,5 @@
+export interface Package {
+    path: string;
+    data: Record<string, unknown>;
+}
+export declare function nearestPackage(from: string): Package | undefined;

package/dist/pkg.js

@@ -0,0 +1,21 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+export function nearestPackage(from) {
+    let dir = from;
+    for (let i = 0; i < 64; i++) {
+        const at = join(dir, 'package.json');
+        if (existsSync(at)) {
+            try {
+                return { path: at, data: JSON.parse(readFileSync(at, 'utf8')) };
+            }
+            catch {
+                return undefined;
+            }
+        }
+        const up = dirname(dir);
+        if (up === dir)
+            return undefined;
+        dir = up;
+    }
+    return undefined;
+}

package/dist/precedence.d.ts

@@ -0,0 +1,55 @@
+/**
+ * One precedence order, fixed and not configurable (commander-env V1–V3, V5):
+ *
+ *     flag > env > config file > package.json field > default
+ *
+ * `resolve` is pure — it takes the layers and returns the values with their provenance —
+ * which is what makes `--explain` trustworthy and `meta.provenance` cheap. Env applies
+ * only to the options the running command declares (yargs #873), never to a sibling's.
+ */
+import { type OptionSpec } from './manifest.js';
+export type Source = 'flag' | 'env' | 'config' | 'package' | 'default';
+export interface Provenance {
+    source: Source;
+    /** The env name, the config file, or `package.json` — where a person would look. */
+    location?: string;
+}
+export interface Candidate {
+    source: Source;
+    location: string;
+    /** `undefined` when the layer had nothing for this option. */
+    value: unknown;
+}
+export interface Layer {
+    path: string;
+    data: Record<string, unknown>;
+}
+export interface Layers {
+    /** What the user typed: only options present on the command line. */
+    flags: Record<string, unknown>;
+    env: Record<string, string | undefined>;
+    /** With a prefix, an option without `env:` reads `PREFIX_OPTION_NAME` (R2). */
+    envPrefix?: string;
+    config?: Layer;
+    /** The `package.json` field named after the program, when present. */
+    pkg?: Layer;
+}
+export interface Resolution {
+    values: Record<string, unknown>;
+    provenance: Record<string, Provenance>;
+    candidates: Record<string, Candidate[]>;
+}
+/** A value that cannot be used as configured: exit CONFIG (3), never a stack (E1, E3). */
+export declare class ConfigError extends Error {
+    readonly hint?: string | undefined;
+    constructor(message: string, hint?: string | undefined);
+}
+/** `region` → `REGION`, `dryRun` → `DRY_RUN`, `log-level` → `LOG_LEVEL` (yargs #2005: never camel-cased back). */
+export declare function screaming(name: string): string;
+export declare function envName(name: string, spec: OptionSpec, prefix: string | undefined): string | undefined;
+/** Booleans from env accept one spelling each way (R7). */
+export declare function envBoolean(raw: string): boolean | undefined;
+/** Every declared option, resolved through the layers; a missing required one is left undefined for the caller to report. */
+export declare function resolve(specs: Record<string, OptionSpec>, layers: Layers): Resolution;
+/** `--explain <option>`: the winning source and every candidate it beat, or that was unset (V3). */
+export declare function explain(name: string, resolution: Resolution): string;

package/dist/precedence.js

@@ -0,0 +1,100 @@
+export class ConfigError extends Error {
+    hint;
+    constructor(message, hint) {
+        super(message);
+        this.hint = hint;
+    }
+}
+export function screaming(name) {
+    return name
+        .replaceAll(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .replaceAll('-', '_')
+        .toUpperCase();
+}
+export function envName(name, spec, prefix) {
+    if (spec.env !== undefined)
+        return spec.env;
+    return prefix === undefined ? undefined : `${prefix}_${screaming(name)}`;
+}
+const TRUE = new Set(['1', 'true', 'yes']);
+const FALSE = new Set(['0', 'false', 'no']);
+export function envBoolean(raw) {
+    const v = raw.trim().toLowerCase();
+    if (TRUE.has(v))
+        return true;
+    if (FALSE.has(v))
+        return false;
+    return undefined;
+}
+function fromEnv(name, spec, layers) {
+    const variable = envName(name, spec, layers.envPrefix);
+    if (variable === undefined)
+        return undefined;
+    if (spec.type === 'boolean' && layers.envPrefix !== undefined) {
+        const negated = `${layers.envPrefix}_NO_${screaming(name)}`;
+        if (layers.env[negated] !== undefined) {
+            throw new ConfigError(`${negated} is not supported`, `set ${variable}=false instead`);
+        }
+    }
+    const raw = layers.env[variable];
+    if (raw === undefined)
+        return { source: 'env', location: variable, value: undefined };
+    if (spec.type !== 'boolean')
+        return { source: 'env', location: variable, value: raw };
+    const parsed = envBoolean(raw);
+    if (parsed === undefined)
+        throw new ConfigError(`${variable}="${raw}" is not a boolean`, `use ${variable}=true or ${variable}=false`);
+    return { source: 'env', location: variable, value: parsed };
+}
+function candidatesFor(name, spec, layers) {
+    const out = [{ source: 'flag', location: `--${name}`, value: layers.flags[name] }];
+    const env = fromEnv(name, spec, layers);
+    if (env !== undefined)
+        out.push(env);
+    if (layers.config !== undefined)
+        out.push({ source: 'config', location: layers.config.path, value: layers.config.data[name] });
+    if (layers.pkg !== undefined)
+        out.push({ source: 'package', location: layers.pkg.path, value: layers.pkg.data[name] });
+    out.push({ source: 'default', location: 'default', value: spec.default });
+    return out;
+}
+export function resolve(specs, layers) {
+    const values = new Map();
+    const provenance = new Map();
+    const candidates = new Map();
+    for (const [name, spec] of Object.entries(specs)) {
+        const list = candidatesFor(name, spec, layers);
+        candidates.set(name, list);
+        const winner = list.find((c) => c.value !== undefined);
+        if (winner === undefined)
+            continue;
+        values.set(name, winner.value);
+        provenance.set(name, winner.source === 'default' ? { source: 'default' } : { source: winner.source, location: winner.location });
+    }
+    return { values: Object.fromEntries(values), provenance: Object.fromEntries(provenance), candidates: Object.fromEntries(candidates) };
+}
+const describe = (c) => {
+    switch (c.source) {
+        case 'flag':
+            return `flag ${c.location}`;
+        case 'env':
+            return `env ${c.location}`;
+        case 'config':
+            return `config file ${c.location}`;
+        case 'package':
+            return `package.json field in ${c.location}`;
+        case 'default':
+            return 'default';
+    }
+};
+export function explain(name, resolution) {
+    const list = resolution.candidates[name];
+    if (list === undefined)
+        return `${name} is not an option of this command\n`;
+    const winner = list.find((c) => c.value !== undefined);
+    const head = winner === undefined ? `${name} is unset` : `${name} = ${JSON.stringify(winner.value)}   from ${describe(winner)}`;
+    const rest = list
+        .filter((c) => c !== winner)
+        .map((c) => `${describe(c)} ${c.value === undefined ? '(unset)' : JSON.stringify(c.value)}`);
+    return `${head}\n${rest.length === 0 ? '' : `         candidates: ${rest.join(', ')}\n`}`;
+}

package/dist/runtime.d.ts

@@ -0,0 +1,39 @@
+import { type ExitCode } from './exit-code.js';
+/** Anything that accepts text; `process.stdout` satisfies it, so does an array push. */
+export interface Writer {
+    write(chunk: string): unknown;
+}
+/**
+ * Time, as the layers above the parser see it (R14 of `cli-output-stack`). `now` is
+ * monotonic milliseconds from an arbitrary origin; `schedule` runs `fn` after `ms` and
+ * hands back the cancel. Typed structurally so the output stack can accept a `Runtime`
+ * without importing one.
+ */
+export interface Clock {
+    now(): number;
+    schedule(fn: () => void, ms: number): () => void;
+}
+/**
+ * The world, as the layers above the parser see it (design R1 of
+ * `cli-testing-harness`). Nothing above the parser reads `process.*` directly; it
+ * reads its `Runtime`, so a test can substitute every part of it.
+ */
+export interface Runtime {
+    argv: string[];
+    env: Record<string, string | undefined>;
+    cwd: string;
+    stdin: NodeJS.ReadableStream;
+    stdout: Writer;
+    stderr: Writer;
+    isTTY: {
+        stdin: boolean;
+        stdout: boolean;
+        stderr: boolean;
+    };
+    /** Ends the run with an E1 code. In the real runtime this never returns. */
+    exit(code: ExitCode): never;
+    /** `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`. */
+export declare const processRuntime: Runtime;

package/dist/runtime.js

@@ -0,0 +1,24 @@
+const ARGV_PROGRAM_AND_SCRIPT = 2;
+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),
+    },
+    exit(code) {
+        process.exit(code);
+    },
+    clock: {
+        now: () => performance.now(),
+        schedule(fn, ms) {
+            const handle = setTimeout(fn, ms);
+            return () => clearTimeout(handle);
+        },
+    },
+};

package/dist/schema.d.ts

@@ -0,0 +1,79 @@
+/**
+ * `--schema` — the program as data (F1). It is the one command an agent runs first, so it
+ * must succeed with no authentication, no config file and no network (N8): it reads the
+ * 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';
+export interface JsonSchema {
+    type: 'object';
+    properties: Record<string, JsonSchemaProperty>;
+    required: string[];
+    additionalProperties: false;
+}
+export interface JsonSchemaProperty {
+    type: 'string' | 'boolean' | 'number' | 'integer' | 'array';
+    description?: string;
+    enum?: string[];
+    default?: string | boolean | number | readonly (string | number)[];
+    items?: {
+        type: 'string' | 'boolean' | 'number' | 'integer';
+        enum?: string[];
+    };
+    minimum?: number;
+    maximum?: number;
+    /** The command-line spelling of the option (S5). */
+    flag?: string;
+    /** The shared set this option was copied from (M4). */
+    sharedFrom?: string;
+}
+export interface CommandSchema {
+    /** The command as typed, without the program name: `config get`. */
+    name: string;
+    description?: string;
+    summary?: string;
+    effects?: Effects;
+    deprecated?: boolean | string;
+    /** The heading it is listed under (M1). */
+    group?: string;
+    /** Its handler loads on dispatch (M2): this schema was complete without it. */
+    lazy?: true;
+    /** Which plugin contributed it (M3). */
+    plugin?: string;
+    arguments: ArgumentSpec[];
+    options: Record<string, OptionSpec>;
+    examples: Example[];
+    /** The arguments and options as one JSON Schema object — what an MCP tool call takes. */
+    inputSchema: JsonSchema;
+}
+export interface ProgramSchema {
+    schemaVersion: 1;
+    name: string;
+    version?: string;
+    description?: string;
+    commands: CommandSchema[];
+}
+export declare function inputSchemaOf(node: CommandNode): JsonSchema;
+/** The typed name of a node: its path without the program's own name. */
+export declare function typedName(node: CommandNode, root: string[]): string;
+export declare function commandSchemaOf(node: CommandNode, root: string[]): CommandSchema;
+/** Every runnable, visible command, in declaration order. Groups are structure, not commands. */
+export declare function runnable(manifest: Manifest): CommandNode[];
+export interface SchemaSummary {
+    schemaVersion: 1;
+    name: string;
+    version?: string;
+    description?: string;
+    /** The full schema exceeded the budget; this lists every command and how to get one in full. */
+    summarised: true;
+    budget: number;
+    commands: {
+        name: string;
+        summary?: string;
+        effects?: Effects;
+    }[];
+    hint: string;
+}
+/** Above the budget (N13): every command by name and summary, and the drilling command for one in full. */
+export declare function summaryOf(manifest: Manifest, budget: number): SchemaSummary;
+export declare function schemaOf(manifest: Manifest): ProgramSchema;

package/dist/schema.js

@@ -0,0 +1,116 @@
+import { kebab } from './names.js';
+function argumentProperty(a) {
+    const p = a.variadic === true ? { type: 'array', items: { type: 'string' } } : { type: 'string' };
+    if (a.description !== undefined)
+        p.description = a.description;
+    if (a.default !== undefined)
+        p.default = a.default;
+    return p;
+}
+function scalarType(spec) {
+    if (spec.type === 'number')
+        return spec.integer === true ? 'integer' : 'number';
+    return spec.type;
+}
+function optionProperty(name, spec) {
+    const scalar = scalarType(spec);
+    const p = spec.multiple === true ? { type: 'array', items: { type: scalar } } : { type: scalar };
+    p.flag = `--${kebab(name)}`;
+    if (spec.description !== undefined)
+        p.description = spec.description;
+    if (spec.choices !== undefined) {
+        if (p.items !== undefined)
+            p.items.enum = [...spec.choices];
+        else
+            p.enum = [...spec.choices];
+    }
+    if (spec.default !== undefined)
+        p.default = spec.default;
+    if (spec.minimum !== undefined)
+        p.minimum = spec.minimum;
+    if (spec.maximum !== undefined)
+        p.maximum = spec.maximum;
+    if (spec.sharedFrom !== undefined)
+        p.sharedFrom = spec.sharedFrom;
+    return p;
+}
+export function inputSchemaOf(node) {
+    const properties = new Map();
+    const required = [];
+    for (const a of node.arguments ?? []) {
+        properties.set(a.name, argumentProperty(a));
+        if (a.required !== false)
+            required.push(a.name);
+    }
+    for (const [name, spec] of Object.entries(node.options)) {
+        if (spec.hidden === true)
+            continue;
+        properties.set(name, optionProperty(name, spec));
+        if (spec.required === true && spec.default === undefined)
+            required.push(name);
+    }
+    return { type: 'object', properties: Object.fromEntries(properties), required, additionalProperties: false };
+}
+export function typedName(node, root) {
+    return node.path.slice(root.length).join(' ');
+}
+export function commandSchemaOf(node, root) {
+    const out = {
+        name: typedName(node, root),
+        arguments: node.arguments ?? [],
+        options: node.options,
+        examples: node.examples ?? [],
+        inputSchema: inputSchemaOf(node),
+    };
+    if (node.description !== undefined)
+        out.description = node.description;
+    if (node.summary !== undefined)
+        out.summary = node.summary;
+    if (node.effects !== undefined)
+        out.effects = node.effects;
+    if (node.deprecated !== undefined)
+        out.deprecated = node.deprecated;
+    if (node.group !== undefined)
+        out.group = node.group;
+    if (node.load !== undefined)
+        out.lazy = true;
+    if (node.plugin !== undefined)
+        out.plugin = node.plugin;
+    return out;
+}
+export function runnable(manifest) {
+    return manifest.commands.filter((c) => c.run !== undefined && c.hidden !== true);
+}
+export function summaryOf(manifest, budget) {
+    const root = manifest.rootPath;
+    const program = manifest.find(root);
+    const out = {
+        schemaVersion: 1,
+        name: root.join(' '),
+        summarised: true,
+        budget,
+        commands: runnable(manifest).map((c) => ({
+            name: typedName(c, root),
+            ...(c.summary ?? c.description === undefined ? {} : { summary: c.summary ?? c.description ?? '' }),
+            ...(c.effects === undefined ? {} : { effects: c.effects }),
+        })),
+        hint: `run \`${root.join(' ')} <command> --schema\` for one command in full`,
+    };
+    if (manifest.version !== undefined)
+        out.version = manifest.version;
+    const description = program?.description;
+    if (description !== undefined)
+        out.description = description;
+    return out;
+}
+export function schemaOf(manifest) {
+    const root = manifest.rootPath;
+    const program = manifest.find(root);
+    const out = { schemaVersion: 1, name: root.join(' '), commands: runnable(manifest).map((c) => commandSchemaOf(c, root)) };
+    if (manifest.version !== undefined)
+        out.version = manifest.version;
+    const description = program?.description;
+    if (description !== undefined)
+        out.description = description;
+    return out;
+}

package/dist/testing-helpers.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Test-side helpers shared by `commander-harness` and `yargs-harness` (design R2,
+ * R5, R7 of `cli-testing-harness`). This is the second and last file in the layer
+ * that may touch `process`, because swapping `process.env` for the duration of a run
+ * is the one thing a harness cannot avoid: commander reads `Option#env()` from
+ * `process.env` at parse time (commander #2549), and yargs' `.env()` likewise.
+ */
+import { Readable } from 'node:stream';
+import { ExitCode } from './exit-code.js';
+import { type Manifest } from './manifest.js';
+import { type Clock, type Runtime } from './runtime.js';
+export interface RunOptions {
+    argv: string[];
+    env?: Record<string, string>;
+    stdin?: string | Readable;
+    cwd?: string;
+    /** `true` = every stream is a TTY; an object sets each; default: none is. */
+    tty?: boolean | Partial<Runtime['isTTY']>;
+    /** The clock the runtime reports; a fresh `fakeClock()` at 0 when not given. */
+    clock?: FakeClock;
+}
+export interface RunResult {
+    code: ExitCode;
+    stdout: string;
+    stderr: string;
+    /** Parsed stdout when `--json` was in argv and stdout parsed; see `finish`. */
+    json?: unknown;
+    durationMs: number;
+}
+/** Thrown by `fakeRuntime.exit` so a handler that exits unwinds to the harness. */
+export declare class RuntimeExit extends Error {
+    readonly code: ExitCode;
+    constructor(code: ExitCode);
+}
+export interface FakeRuntime extends Runtime {
+    out: string[];
+    err: string[];
+    clock: FakeClock;
+}
+/** A `Clock` that moves only when the test says so (R14): `tick` is the only source of time. */
+export interface FakeClock extends Clock {
+    /**
+     * Advance by `ms`, running every callback that falls due, earliest first, then by order
+     * scheduled. A callback that schedules inside the window runs in the same tick, so one that
+     * reschedules itself at `0` would never leave the loop (real Node yields between turns);
+     * a tick runs at most `TICK_CAP` callbacks and throws, naming the cap, when exceeded.
+     */
+    tick(ms: number): void;
+    /** Callbacks scheduled and neither run nor cancelled. */
+    pending(): number;
+}
+/** Deterministic time for the harness. Starts at `start` (0 by default) and never moves on its own. */
+export declare function fakeClock(start?: number): FakeClock;
+/** A `Runtime` whose every part is under the test's control. */
+export declare function fakeRuntime(opts: RunOptions): FakeRuntime;
+export declare function swapEnv(env: Record<string, string> | undefined): () => void;
+/**
+ * Route `console.*` into the fake runtime while a run lasts. Hosts print through
+ * `console` in a few paths a public seam does not cover (yargs' help printer, a
+ * handler that never met the output layer); a harness that let those reach the real
+ * terminal would be measuring the wrong thing.
+ */
+export declare function captureConsole(rt: FakeRuntime): () => void;
+/** Strip ANSI escape sequences — the decision from the intent: `stdout` stays raw. */
+export declare function stripAnsi(text: string): string;
+/**
+ * Assemble the result (R2). `json` is set only when `--json` was in argv and stdout
+ * parsed; a parse failure turns the run into `RUNTIME` with the parse error on
+ * stderr, so a broken envelope cannot pass a test by accident.
+ */
+export declare function finish(rt: FakeRuntime, code: ExitCode, startedAt: number): RunResult;
+/** The E1 code an unwound error carries, or `RUNTIME` when it carries none. */
+export declare function codeOf(e: unknown): ExitCode;
+/**
+ * Run a burgee program in-process — the T1 harness for burgee itself. Env is injected,
+ * never swapped: the engine reads env-bound options from the runtime it is given, so
+ * `process.env` is untouched by construction. Exit unwinds through `RuntimeExit`.
+ */
+export declare function runBurgee(program: Manifest, opts: RunOptions): Promise<RunResult>;

package/dist/testing-helpers.js

@@ -0,0 +1,145 @@
+import { Readable } from 'node:stream';
+import { beforeTerminator, execute } from './execute.js';
+import { ExitCode, isExitCode } from './exit-code.js';
+export class RuntimeExit extends Error {
+    code;
+    constructor(code) {
+        super(`runtime.exit(${code})`);
+        this.code = code;
+        this.name = 'RuntimeExit';
+    }
+}
+const TICK_CAP = 1000;
+export function fakeClock(start = 0) {
+    let now = start;
+    let nextId = 0;
+    const timers = [];
+    const remove = (id) => {
+        const at = timers.findIndex((t) => t.id === id);
+        if (at !== -1)
+            timers.splice(at, 1);
+    };
+    return {
+        now: () => now,
+        schedule(fn, ms) {
+            const id = nextId++;
+            timers.push({ id, at: now + Math.max(0, ms), fn });
+            return () => remove(id);
+        },
+        tick(ms) {
+            const until = now + ms;
+            const nextDue = () => timers.filter((t) => t.at <= until).sort((a, b) => a.at - b.at || a.id - b.id)[0];
+            let ran = 0;
+            for (let due = nextDue(); due !== undefined; due = nextDue()) {
+                if (ran === TICK_CAP)
+                    throw new Error(`fakeClock.tick(${ms}) ran ${TICK_CAP} callbacks (TICK_CAP): a callback keeps rescheduling inside the window`);
+                ran += 1;
+                remove(due.id);
+                now = Math.max(now, due.at);
+                due.fn();
+            }
+            now = until;
+        },
+        pending: () => timers.length,
+    };
+}
+function ttyOf(tty) {
+    if (tty === true)
+        return { stdin: true, stdout: true, stderr: true };
+    if (tty === false || tty === undefined)
+        return { stdin: false, stdout: false, stderr: false };
+    return { stdin: false, stdout: false, stderr: false, ...tty };
+}
+export function fakeRuntime(opts) {
+    const out = [];
+    const err = [];
+    const stdin = typeof opts.stdin === 'string' ? Readable.from([opts.stdin]) : (opts.stdin ?? Readable.from([]));
+    return {
+        argv: opts.argv,
+        env: { ...(opts.env ?? {}) },
+        cwd: opts.cwd ?? '/',
+        stdin,
+        stdout: { write: (s) => out.push(s) },
+        stderr: { write: (s) => err.push(s) },
+        isTTY: ttyOf(opts.tty),
+        exit(code) {
+            throw new RuntimeExit(code);
+        },
+        clock: opts.clock ?? fakeClock(),
+        out,
+        err,
+    };
+}
+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);
+    return () => {
+        for (const key of Object.keys(process.env))
+            delete process.env[key];
+        Object.assign(process.env, saved);
+    };
+}
+const CONSOLE_METHODS = ['log', 'info', 'debug', 'warn', 'error'];
+const into = (sink) => (...args) => {
+    sink.push(`${args.map(String).join(' ')}\n`);
+};
+export function captureConsole(rt) {
+    const saved = Object.fromEntries(CONSOLE_METHODS.map((m) => [m, console[m]]));
+    console.log = into(rt.out);
+    console.info = into(rt.out);
+    console.debug = into(rt.out);
+    console.warn = into(rt.err);
+    console.error = into(rt.err);
+    return () => {
+        for (const m of CONSOLE_METHODS)
+            console[m] = saved[m];
+    };
+}
+export function stripAnsi(text) {
+    return text.replace(/\u001b\[[0-9;]*[A-Za-z]/g, '');
+}
+export function finish(rt, code, startedAt) {
+    const stdout = rt.out.join('');
+    const stderr = rt.err.join('');
+    const result = { code, stdout, stderr, durationMs: performance.now() - startedAt };
+    if (beforeTerminator(rt.argv).includes('--json')) {
+        const source = stdout.trim() === '' && code !== ExitCode.OK ? stderr.split('\n')[0] ?? '' : stdout;
+        try {
+            result.json = JSON.parse(source);
+        }
+        catch (e) {
+            return { ...result, code: ExitCode.RUNTIME, stderr: `${stderr}--json output did not parse: ${e.message}\n` };
+        }
+    }
+    return result;
+}
+export function codeOf(e) {
+    if (e instanceof RuntimeExit)
+        return e.code;
+    const exitCode = e?.exitCode;
+    return isExitCode(exitCode) ? exitCode : ExitCode.RUNTIME;
+}
+export async function runBurgee(program, opts) {
+    const startedAt = performance.now();
+    const rt = fakeRuntime(opts);
+    let code = ExitCode.OK;
+    try {
+        await execute(program, {
+            argv: rt.argv,
+            env: rt.env,
+            stdout: rt.stdout,
+            stderr: rt.stderr,
+            exit: (c) => rt.exit(c),
+            root: program.rootPath,
+        });
+    }
+    catch (e) {
+        code = codeOf(e);
+    }
+    return finish(rt, code, startedAt);
+}

package/dist/testing.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `burgee/testing` — run a burgee CLI in-process, with argv, env, stdin, cwd and
+ * TTY-ness injected, and get back `{ code, stdout, stderr, json }`. Requirement T1.
+ *
+ * A separate entry point so it is paid for per import (K6): a user's shipped CLI
+ * imports `burgee` and never pulls a byte of this.
+ */
+export { processRuntime, type Clock, type Runtime, type Writer } from './runtime.js';
+export { captureConsole, codeOf, fakeClock, fakeRuntime, finish, runBurgee, RuntimeExit, stripAnsi, swapEnv, type FakeClock, type FakeRuntime, type RunOptions, type RunResult, } from './testing-helpers.js';
+export { ExitCode, isExitCode, type ExitCode as ExitCodeValue } from './exit-code.js';