burgee 0.0.0 → 0.3.0

package/dist/dev.d.ts

@@ -0,0 +1,47 @@
+import { Manifest } from './manifest.js';
+import { type Invoke } from './mcp.js';
+export interface Writer {
+    write: (s: string) => unknown;
+}
+export interface DevOptions {
+    /** The module that exports the program: `program` (or `default`) as a burgee manifest, a commander `Command` or a yargs instance. */
+    entry: string;
+    /** The MCP channel. */
+    input: NodeJS.ReadableStream;
+    output: Writer;
+    /** Where the reload report goes: never stdout, which carries MCP. */
+    log: Writer;
+    /** Off for tests that drive `reload()` themselves. */
+    watch?: boolean;
+    /** Files changed within this window coalesce into one reload. */
+    debounceMs?: number;
+}
+export interface Loaded {
+    manifest: Manifest;
+    invoke: Invoke;
+    kind: 'burgee' | 'commander' | 'yargs';
+    /** Milliseconds from the trigger to the manifest being served (W6). */
+    ms: number;
+}
+export interface DevHandle {
+    ready: Promise<Loaded>;
+    /** Re-import the entry, print the diff and the help, swap the served manifest. */
+    reload: () => Promise<Loaded>;
+    /** Settles when the MCP input closes. */
+    done: Promise<void>;
+    close: () => void;
+}
+/**
+ * Import the entry as a fresh module graph. The query is what discards the previous
+ * graph: the same URL would hand back the cached module and its stale handlers.
+ */
+export declare function load(entry: string, generation: number): Promise<Loaded>;
+/** What changed between two manifests, by command path: added, removed, or a different schema. */
+export declare function diffManifests(before: Manifest | undefined, after: Manifest): {
+    added: string[];
+    removed: string[];
+    changed: string[];
+};
+/** The reload report: one save, every surface (W3). */
+export declare function report(before: Manifest | undefined, loaded: Loaded): string;
+export declare function dev(opts: DevOptions): DevHandle;

package/dist/dev.js

@@ -0,0 +1,132 @@
+import { watch } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { execute } from './execute.js';
+import { renderHelp } from './help.js';
+import { Manifest } from './manifest.js';
+import { startMcp, toolsOf } from './mcp.js';
+import { commandSchemaOf } from './schema.js';
+const DEFAULT_DEBOUNCE_MS = 50;
+const SOURCE = /\.(m?[jt]s|c[jt]s|json)$/;
+const isObject = (x) => x !== null && x !== undefined && typeof x === 'object' && !Array.isArray(x);
+function isManifest(x) {
+    return x instanceof Manifest || (isObject(x) && Array.isArray(x['commands']) && Array.isArray(x['rootPath']));
+}
+function isYargs(x) {
+    return isObject(x) && typeof x['burgee'] === 'function' && isObject(x['manifest']);
+}
+function isCommander(x) {
+    return isObject(x) && typeof x['parseAsync'] === 'function' && isObject(x['manifest']);
+}
+function invokeOn(program, kind, entry) {
+    return async (argv) => {
+        const out = [];
+        const err = [];
+        let code = 0;
+        const seam = { stdout: { write: (s) => out.push(s) }, stderr: { write: (s) => err.push(s) }, exit: (c) => void (code = c) };
+        if (kind === 'burgee')
+            await execute(program, { argv, from: 'user', entry, ...seam });
+        else if (kind === 'yargs')
+            await program.burgee(seam).parseAsync(argv);
+        else
+            await program.parseAsync(argv, { from: 'user', ...seam });
+        return { stdout: out.join(''), stderr: err.join(''), code };
+    };
+}
+export async function load(entry, generation) {
+    const started = performance.now();
+    const url = pathToFileURL(resolve(entry));
+    url.searchParams.set('burgee-dev', String(generation));
+    const mod = (await import(url.href));
+    const exported = mod['program'] ?? mod['default'];
+    if (isManifest(exported))
+        return { manifest: exported, invoke: invokeOn(exported, 'burgee', entry), kind: 'burgee', ms: performance.now() - started };
+    if (isYargs(exported))
+        return { manifest: exported.manifest, invoke: invokeOn(exported, 'yargs', entry), kind: 'yargs', ms: performance.now() - started };
+    if (isCommander(exported))
+        return { manifest: exported.manifest, invoke: invokeOn(exported, 'commander', entry), kind: 'commander', ms: performance.now() - started };
+    throw new Error(`${entry} exports no program: export a burgee manifest, a commander Command or a yargs instance as \`program\` or default`);
+}
+const schemasByPath = (m) => new Map(m.commands.map((c) => [c.path.join(' '), JSON.stringify(commandSchemaOf(c, m.rootPath))]));
+export function diffManifests(before, after) {
+    const was = before === undefined ? new Map() : schemasByPath(before);
+    const now = schemasByPath(after);
+    return {
+        added: [...now.keys()].filter((k) => !was.has(k)),
+        removed: [...was.keys()].filter((k) => !now.has(k)),
+        changed: [...now.keys()].filter((k) => was.has(k) && was.get(k) !== now.get(k)),
+    };
+}
+export function report(before, loaded) {
+    const { manifest } = loaded;
+    const diff = diffManifests(before, manifest);
+    const lines = [];
+    lines.push(`${before === undefined ? 'loaded' : 'reloaded'} ${manifest.rootPath.join(' ')} (${loaded.kind}) in ${loaded.ms.toFixed(0)} ms — ${manifest.commands.length} commands, ${toolsOf(manifest).length} MCP tools`);
+    for (const p of diff.added)
+        lines.push(`  + ${p}`);
+    for (const p of diff.removed)
+        lines.push(`  - ${p}`);
+    for (const p of diff.changed)
+        lines.push(`  ~ ${p}`);
+    const root = manifest.find(manifest.rootPath);
+    if (root !== undefined)
+        lines.push('', renderHelp(manifest, root).trimEnd());
+    return `${lines.join('\n')}\n`;
+}
+export function dev(opts) {
+    let generation = 0;
+    let current;
+    let server;
+    let watcher;
+    let timer;
+    let chain = Promise.resolve();
+    const entry = resolve(opts.entry);
+    const reloadNow = async () => {
+        generation += 1;
+        const loaded = await load(entry, generation);
+        opts.log.write(report(current, loaded));
+        current = loaded.manifest;
+        if (server === undefined)
+            server = startMcp(loaded.manifest, { input: opts.input, output: opts.output, invoke: loaded.invoke });
+        else
+            server.swap(loaded.manifest, loaded.invoke);
+        return loaded;
+    };
+    const reload = async () => {
+        await chain;
+        const next = reloadNow();
+        chain = next.catch((err) => {
+            opts.log.write(`reload failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        });
+        return await next;
+    };
+    const ready = reload();
+    if (opts.watch !== false) {
+        watcher = watch(dirname(entry), { recursive: true }, (_event, filename) => {
+            const name = filename === null ? '' : String(filename);
+            if (name !== '' && (!SOURCE.test(name) || name.includes('node_modules')))
+                return;
+            clearTimeout(timer);
+            timer = setTimeout(() => void reload().catch(() => undefined), opts.debounceMs ?? DEFAULT_DEBOUNCE_MS);
+        });
+    }
+    const untilInputCloses = async () => {
+        try {
+            await ready;
+            await server.done;
+        }
+        finally {
+            watcher?.close();
+        }
+    };
+    const done = untilInputCloses();
+    return {
+        ready,
+        reload,
+        done,
+        close: () => {
+            clearTimeout(timer);
+            watcher?.close();
+        },
+    };
+}

package/dist/execute.d.ts

@@ -0,0 +1,118 @@
+import { type ArgumentSpec, type CommandNode, type Effects, type Example, type LazyModule, Manifest, type OptionSpec, type Relation, type RunContext } from './manifest.js';
+export interface CommandContext<O> extends Omit<RunContext, 'options'> {
+    options: O;
+}
+type Scalar<S extends OptionSpec> = S['type'] extends 'number' ? number : S['type'] extends 'boolean' ? boolean : S extends {
+    choices: readonly (infer C)[];
+} ? C : string;
+type Many<S extends OptionSpec, V> = S extends {
+    multiple: true;
+} ? V[] : V;
+type Present<S extends OptionSpec> = S extends {
+    required: true;
+} ? true : S extends {
+    default: unknown;
+} ? true : false;
+/** The handler's `options`, derived from the declaration (S1): `choices` become a union, `multiple` an array, `number` a number. */
+export type InferOptions<S extends Record<string, OptionSpec>> = {
+    [K in keyof S]: Present<S[K]> extends true ? Many<S[K], Scalar<S[K]>> : Many<S[K], Scalar<S[K]>> | undefined;
+};
+export type OptionSpecs = Record<string, OptionSpec>;
+export type AnyCommand = Command<any>;
+export interface Command<S extends OptionSpecs = OptionSpecs> {
+    name: string;
+    description?: string;
+    /** Shown in command lists instead of the description. */
+    summary?: string;
+    /** Declared once (S1); the handler's `options` type is derived from it. */
+    options?: S;
+    arguments?: ArgumentSpec[];
+    examples?: Example[];
+    /** Heading this command is listed under in its parent's help. */
+    group?: string;
+    epilogue?: string;
+    hidden?: boolean;
+    deprecated?: boolean | string;
+    /** What running it does to the world (N6). Declaring it is what exposes the command as an MCP tool (N2). */
+    effects?: Effects;
+    /** Relationships between options, validated before choices and the handler (S2, S6). */
+    relations?: readonly Relation[];
+    /** Absent on a group that only holds subcommands. `NoInfer`: the spec fixes S, the handler only reads it. */
+    run?: (ctx: CommandContext<InferOptions<NoInfer<S>>>) => unknown;
+    /** The handler's module, imported on dispatch only (M2); everything else about the command is declared here. */
+    load?: () => Promise<LazyModule>;
+    commands?: AnyCommand[];
+}
+export interface Program {
+    name: string;
+    version?: string;
+    description?: string;
+    /** Options read `PREFIX_OPTION_NAME` from the environment unless they name their own variable (V2). */
+    envPrefix?: string;
+    /** Characters of `--schema` output above which it is summarised (N13); 48,000 by default. */
+    schemaBudget?: number;
+    /**
+     * Opt into config discovery (V6): `--config <path>` > `NAME_CONFIG` > `./name.config.{json,mjs,js,cjs}`
+     * > `package.json#name` > the user config directory; `true` uses the program's name.
+     */
+    config?: boolean | {
+        name: string;
+    };
+    commands: AnyCommand[];
+}
+export declare function defineCommand<const S extends OptionSpecs = OptionSpecs>(command: Command<S>): Command<S>;
+/**
+ * Options declared once and spread into each command that takes them (M4): never global,
+ * so `--schema` stays a tree and each command's help lists them as its own, and the
+ * handler's `options` type carries them like any other. Every copy is tagged
+ * `sharedFrom` with the set's name, so the schema says where it came from.
+ */
+export declare function sharedOptions<const T extends OptionSpecs>(name: string, specs: T): T;
+/** A native multi-command program. The manifest it builds is the same one the façades fill. */
+export declare function defineProgram(program: Program): Manifest;
+export interface RunOptions {
+    argv?: string[];
+    /** Read only by `--mcp`, which serves JSON-RPC over it. */
+    stdin?: NodeJS.ReadableStream;
+    /** The environment env-bound options read from. Injected by the harness; the process's own otherwise. */
+    env?: Record<string, string | undefined>;
+    /** `columns` is read when present, so help wraps to the terminal (H3); `isTTY` feeds agent detection (N12). */
+    stdout?: {
+        write: (s: string) => unknown;
+        columns?: number;
+        isTTY?: boolean;
+    };
+    stderr?: {
+        write: (s: string) => unknown;
+    };
+    /** Receives the E1 code. The default calls process.exit; an injected one may simply record it. */
+    exit?: (code: number) => void;
+    /** Where config discovery starts; the process's own otherwise. */
+    cwd?: string;
+    /** The entry file, whose nearest package.json owns the program's version (V4); `process.argv[1]` otherwise. */
+    entry?: string;
+}
+/** The part of argv the parser will read as options: everything before `--`. */
+export declare function beforeTerminator(argv: readonly string[]): readonly string[];
+export declare function execute(manifest: Manifest, opts?: RunOptions & {
+    root?: string[];
+    from?: 'node' | 'user';
+}): Promise<void>;
+/** M6: which command argv names, or null — the same longest-prefix match `execute` uses. */
+export declare function resolveCommand(manifest: Manifest, argv: readonly string[]): CommandNode | null;
+export interface RunResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * M6: run a command programmatically — the harness's own entry, public. The streams are
+ * captured, the exit recorded; env, cwd and the entry can be injected like `execute`'s.
+ */
+export declare function runCommand(manifest: Manifest, argv: readonly string[], opts?: Pick<RunOptions, 'env' | 'cwd' | 'entry' | 'stdin'>): Promise<RunResult>;
+/**
+ * The one-file entry: a single command, or a program from `defineProgram`. Both go
+ * through `execute`, so there is exactly one code path from argv to exit.
+ */
+export declare function run<S extends OptionSpecs>(target: Command<S> | Manifest, opts?: RunOptions): Promise<void>;
+export {};