burgee 0.0.0 → 0.3.0

package/dist/execute.js

@@ -0,0 +1,469 @@
+import { dirname } from 'node:path';
+import { parseArgs } from 'node:util';
+import { detectAgent } from './agent.js';
+import { ExitCode, isExitCode } from './exit-code.js';
+import { renderHelp } from './help.js';
+import { Manifest } from './manifest.js';
+import { serveMcp } from './mcp.js';
+import { camel, kebab } from './names.js';
+import { nearestPackage } from './pkg.js';
+import { ConfigError, explain, resolve as resolveLayers } from './precedence.js';
+import { commandSchemaOf, schemaOf, summaryOf } from './schema.js';
+import { checkDefinition, checkRelations, coerce, UsageError } from './validate.js';
+function helpFields(c) {
+    const node = {};
+    if (c.description !== undefined)
+        node.description = c.description;
+    if (c.summary !== undefined)
+        node.summary = c.summary;
+    if (c.arguments !== undefined)
+        node.arguments = c.arguments;
+    if (c.examples !== undefined)
+        node.examples = c.examples;
+    if (c.group !== undefined)
+        node.group = c.group;
+    if (c.epilogue !== undefined)
+        node.epilogue = c.epilogue;
+    if (c.hidden !== undefined)
+        node.hidden = c.hidden;
+    if (c.deprecated !== undefined)
+        node.deprecated = c.deprecated;
+    if (c.effects !== undefined)
+        node.effects = c.effects;
+    if (c.relations !== undefined)
+        node.relations = c.relations;
+    return node;
+}
+const RESERVED = new Set(['json', 'help', 'schema', 'mcp', 'version', 'explain']);
+export function defineCommand(command) {
+    for (const name of Object.keys(command.options ?? {})) {
+        if (RESERVED.has(name) || RESERVED.has(kebab(name)))
+            throw new Error(`burgee: option "${name}" is reserved and cannot be redefined`);
+    }
+    checkDefinition(command.name, command.options ?? {});
+    return command;
+}
+function addTree(manifest, parent, commands) {
+    for (const c of commands) {
+        const path = [...parent, c.name];
+        manifest.add({
+            path,
+            ...helpFields(c),
+            options: c.options ?? {},
+            ...(c.run === undefined ? {} : { run: c.run }),
+            ...(c.load === undefined ? {} : { load: c.load }),
+        });
+        if (c.commands !== undefined)
+            addTree(manifest, path, c.commands);
+    }
+}
+export function sharedOptions(name, specs) {
+    return Object.fromEntries(Object.entries(specs).map(([key, spec]) => [key, { ...spec, sharedFrom: name }]));
+}
+export function defineProgram(program) {
+    const manifest = new Manifest();
+    manifest.rootPath = [program.name];
+    if (program.version !== undefined)
+        manifest.version = program.version;
+    if (program.envPrefix !== undefined)
+        manifest.envPrefix = program.envPrefix;
+    if (program.schemaBudget !== undefined)
+        manifest.schemaBudget = program.schemaBudget;
+    if (program.config === true)
+        manifest.config = { name: program.name };
+    else if (typeof program.config === 'object' && program.config !== null)
+        manifest.config = program.config;
+    manifest.add({ path: [program.name], ...(program.description === undefined ? {} : { description: program.description }), options: {} });
+    addTree(manifest, [program.name], program.commands);
+    return manifest;
+}
+class ActionRequired extends Error {
+    spec;
+    constructor(spec) {
+        super(spec.message);
+        this.spec = spec;
+    }
+}
+const actionRequired = (spec) => {
+    throw new ActionRequired(spec);
+};
+class ExitSignal extends Error {
+    code;
+    constructor(code) {
+        super(`exit ${code}`);
+        this.code = code;
+    }
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function leaf(value) {
+    if (value === undefined || value === null)
+        return '';
+    return typeof value === 'string' ? value : JSON.stringify(value);
+}
+function render(value) {
+    if (value === undefined || value === null)
+        return '';
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value))
+        return value.map((v) => leaf(v)).join('\n');
+    if (isPlainObject(value)) {
+        return Object.entries(value)
+            .map(([k, v]) => `${k}: ${leaf(v)}`)
+            .join('\n');
+    }
+    return String(value);
+}
+function toParseConfig(specs, withConfig) {
+    const config = { json: { type: 'boolean' }, help: { type: 'boolean' }, version: { type: 'boolean' }, explain: { type: 'string' } };
+    if (withConfig) {
+        config['config'] = { type: 'string' };
+        config['no-config'] = { type: 'boolean' };
+    }
+    for (const [name, spec] of Object.entries(specs)) {
+        config[kebab(name)] = {
+            type: spec.type === 'boolean' ? 'boolean' : 'string',
+            ...(spec.short === undefined ? {} : { short: spec.short }),
+            ...(spec.multiple === true ? { multiple: true } : {}),
+        };
+    }
+    return config;
+}
+function canonical(values) {
+    return Object.fromEntries(Object.entries(values).map(([k, v]) => [camel(k), v]));
+}
+function packageLayer(pkg, name) {
+    if (pkg === undefined || name === undefined)
+        return undefined;
+    const field = pkg.data[name];
+    return typeof field === 'object' && field !== null && !Array.isArray(field) ? { path: pkg.path, data: field } : undefined;
+}
+async function configLayers(name, values, io) {
+    const { discover } = await import('./config.js');
+    const explicit = values['config'];
+    const disabled = values['noConfig'] === true;
+    const loaded = await discover({ name, cwd: io.cwd, env: io.env, ...(typeof explicit === 'string' ? { explicit } : {}), disabled });
+    const out = {};
+    if (loaded !== undefined)
+        out.config = { path: loaded.chain.join(' ← '), data: loaded.data };
+    const pkg = disabled ? undefined : packageLayer(io.pkg, name);
+    if (pkg !== undefined)
+        out.pkg = pkg;
+    return out;
+}
+async function resolveValues(manifest, specs, values, io) {
+    const layers = { flags: values, env: io.env };
+    if (manifest.envPrefix !== undefined)
+        layers.envPrefix = manifest.envPrefix;
+    if (manifest.config !== undefined)
+        Object.assign(layers, await configLayers(manifest.config.name, values, io));
+    const resolution = resolveLayers(specs, layers);
+    const out = { values: resolution.values, provenance: resolution.provenance };
+    const asked = values['explain'];
+    if (typeof asked === 'string')
+        out.explainText = explain(asked, resolution);
+    for (const [name, spec] of Object.entries(specs)) {
+        if (out.values[name] === undefined && spec.required === true && out.explainText === undefined) {
+            throw new UsageError(`missing required option --${kebab(name)}`, `pass --${kebab(name)} <value>`);
+        }
+    }
+    return out;
+}
+function splitPositionals(tokens) {
+    const positionals = [];
+    const passthrough = [];
+    let after = false;
+    for (const token of tokens) {
+        const { kind } = token;
+        const value = 'value' in token ? token.value : undefined;
+        if (kind === 'option-terminator')
+            after = true;
+        else if (kind === 'positional' && typeof value === 'string')
+            (after ? passthrough : positionals).push(value);
+    }
+    return { positionals, passthrough };
+}
+function isParseArgsFailure(cause) {
+    if (!(cause instanceof Error))
+        return false;
+    const { code } = cause;
+    return typeof code === 'string' && code.startsWith('ERR_PARSE_ARGS_');
+}
+function exitSignal(cause) {
+    const code = cause?.code;
+    return typeof code === 'number' && isExitCode(code) ? code : undefined;
+}
+const SINGLE_DASH_WORD = /^-([a-zA-Z][\w-]+)(?:=.*)?$/;
+function singleDashHint(argv) {
+    for (const token of argv) {
+        if (token === '--')
+            return undefined;
+        const found = SINGLE_DASH_WORD.exec(token);
+        if (found?.[1] !== undefined)
+            return `did you mean --${found[1]}? a single dash introduces one-letter options`;
+    }
+    return undefined;
+}
+function describeFailure(cause, argv) {
+    const signal = exitSignal(cause);
+    if (signal !== undefined)
+        return { code: signal, message: '', silent: true };
+    const message = cause instanceof Error ? cause.message : String(cause);
+    if (cause instanceof ActionRequired)
+        return { code: ExitCode.CANCELLED, message, action: cause.spec, ...(cause.spec.hint === undefined ? {} : { hint: cause.spec.hint }) };
+    if (cause instanceof UsageError) {
+        return { code: ExitCode.USAGE, message, ...(cause.hint === undefined ? {} : { hint: cause.hint }) };
+    }
+    if (cause instanceof ConfigError) {
+        return { code: ExitCode.CONFIG, message, ...(cause.hint === undefined ? {} : { hint: cause.hint }) };
+    }
+    if (isParseArgsFailure(cause)) {
+        return { code: ExitCode.USAGE, message, hint: singleDashHint(argv) ?? 'run --help to see the available options' };
+    }
+    return { code: ExitCode.RUNTIME, message };
+}
+function textFailure(failure) {
+    const hint = failure.hint === undefined ? '' : `hint: ${failure.hint}\n`;
+    if (failure.action !== undefined) {
+        const next = (failure.action.next ?? []).map((n) => `  ${n.command}    ${n.when}\n`).join('');
+        return `action required (${failure.action.reason}): ${failure.message}\n${next === '' ? '' : `next:\n${next}`}${hint}`;
+    }
+    return `error: ${failure.message}\n${hint}`;
+}
+function runnableNext(manifest, spec, json) {
+    const program = manifest.rootPath.join(' ');
+    return (spec.next ?? []).map((n) => ({ command: `${program} ${n.command}${json && !n.command.includes('--json') ? ' --json' : ''}`, when: n.when }));
+}
+const HELP_FLAGS = new Set(['--help', '-h']);
+const HELP_WIDTH = 100;
+const processExit = (code) => process.exit(code);
+export function beforeTerminator(argv) {
+    const at = argv.indexOf('--');
+    return at === -1 ? argv : argv.slice(0, at);
+}
+function rootNode(manifest, root) {
+    return manifest.find(root) ?? { path: root, options: {} };
+}
+function unresolved({ manifest, root, io: { width } }, argv, at) {
+    const node = at ?? rootNode(manifest, root);
+    const typed = argv.slice(node.path.length - root.length);
+    if (typed.length > 0 && HELP_FLAGS.has(typed[0] ?? ''))
+        return { text: renderHelp(manifest, node, { width }), code: ExitCode.OK };
+    if (typed.length === 0)
+        return { text: renderHelp(manifest, node, { width }), code: ExitCode.USAGE };
+    throw new UsageError(`unknown command "${typed[0] ?? ''}"`, 'run --help to see the available commands');
+}
+async function completion(manifest, argv, io) {
+    if (argv[0] !== 'completion' || manifest.find([...manifest.rootPath, 'completion']) !== undefined)
+        return false;
+    const { renderCompletion, renderFigSpec, SHELLS } = await import('./completions.js');
+    const shell = argv[1] ?? '';
+    if (shell === 'fig') {
+        io.out.write(`${JSON.stringify(renderFigSpec(manifest), null, 2)}\n`);
+        return true;
+    }
+    const known = SHELLS.find((s) => s === shell);
+    if (known === undefined)
+        throw new UsageError(`unknown shell "${shell}"`, `completion ${SHELLS.join('|')}|fig`);
+    io.out.write(renderCompletion(manifest, known));
+    return true;
+}
+async function surface(manifest, argv, io) {
+    const head = beforeTerminator(argv);
+    if (await completion(manifest, argv, io))
+        return true;
+    if (argv[0] === 'help') {
+        io.out.write(helpCommand(manifest, argv.slice(1), manifest.rootPath, io.width));
+        return true;
+    }
+    if (head.includes('--schema')) {
+        io.out.write(`${JSON.stringify(schemaSurface(manifest, argv), null, 2)}\n`);
+        return true;
+    }
+    if (head[0] === '--mcp') {
+        const invoke = async (args) => {
+            const out = [];
+            const err = [];
+            let code = 0;
+            await execute(manifest, {
+                argv: args,
+                env: io.env,
+                stdout: { write: (s) => out.push(s) },
+                stderr: { write: (s) => err.push(s) },
+                exit: (c) => {
+                    code = c;
+                },
+            });
+            return { stdout: out.join(''), stderr: err.join(''), code };
+        };
+        await serveMcp(manifest, { input: io.stdin, output: io.out, invoke });
+        return true;
+    }
+    return false;
+}
+const SCHEMA_BUDGET = 48_000;
+function schemaSurface(manifest, argv) {
+    const { node } = manifest.resolve(beforeTerminator(argv).filter((a) => a !== '--schema'), manifest.rootPath);
+    if (node?.run !== undefined)
+        return commandSchemaOf(node, manifest.rootPath);
+    const full = schemaOf(manifest);
+    const budget = manifest.schemaBudget ?? SCHEMA_BUDGET;
+    return JSON.stringify(full).length <= budget ? full : summaryOf(manifest, budget);
+}
+function helpCommand(manifest, argv, root, width) {
+    const { node } = manifest.resolve(argv, root);
+    return renderHelp(manifest, node ?? rootNode(manifest, root), { width });
+}
+function changedOf(node, data) {
+    const value = isPlainObject(data) ? data['changed'] : undefined;
+    if (typeof value === 'boolean')
+        return value;
+    if (node.effects === 'idempotent') {
+        throw new Error(`"${node.path.slice(1).join(' ')}" is idempotent and must report changed: true | false in its result (N7)`);
+    }
+    return undefined;
+}
+function versionOf(manifest, io) {
+    const declared = manifest.version ?? (typeof io.pkg?.data['version'] === 'string' ? io.pkg.data['version'] : undefined);
+    if (declared === undefined)
+        throw new ConfigError('no version declared', 'pass version to defineProgram, or set "version" in the owning package.json');
+    return declared;
+}
+async function dispatch(manifest, { node, rest, name }, io) {
+    const parsed = parseArgs({ args: rest, options: toParseConfig(node.options, manifest.config !== undefined), allowPositionals: true, strict: true, tokens: true });
+    const flags = canonical(parsed.values);
+    const json = flags.json === true;
+    if (flags.help === true)
+        return { json, text: renderHelp(manifest, node, { width: io.width }) };
+    if (flags.version === true)
+        return { json, text: `${versionOf(manifest, io)}\n` };
+    const resolved = await resolveValues(manifest, node.options, flags, io);
+    if (resolved.explainText !== undefined)
+        return { json, text: resolved.explainText };
+    const { provenance } = resolved;
+    checkRelations(node.relations, resolved.values, provenance);
+    const values = await coerce(node.options, resolved.values);
+    const { positionals, passthrough } = splitPositionals(parsed.tokens);
+    requirePositionals(node, positionals);
+    warnDeprecated(node, io);
+    await manifest.fire('preRun', name, values);
+    const exit = (code) => {
+        io.exit(code);
+        throw new ExitSignal(code);
+    };
+    const detection = detectAgent(io.env, io.tty);
+    const data = await node.run({ options: values, positionals, passthrough, env: io.env, exit, actionRequired, ...detection });
+    await manifest.fire('postRun', name, values);
+    const changed = changedOf(node, data);
+    return { json, data, provenance, ...(changed === undefined ? {} : { changed }) };
+}
+function requirePositionals(node, positionals) {
+    const required = (node.arguments ?? []).filter((a) => a.required !== false && a.variadic !== true);
+    const missing = required[positionals.length];
+    if (positionals.length < required.length && missing !== undefined) {
+        throw new UsageError(`missing required argument "${missing.name}"`, `run --help to see what "${node.path.slice(1).join(' ')}" takes`);
+    }
+}
+const warned = new Set();
+function warnDeprecated(node, io) {
+    if (node.deprecated === undefined || node.deprecated === false)
+        return;
+    const key = node.path.join(' ');
+    if (warned.has(key))
+        return;
+    warned.add(key);
+    const typed = node.path.slice(1).join(' ') || key;
+    const use = typeof node.deprecated === 'string' ? `, use '${node.deprecated}'` : '';
+    io.err.write(`warning: '${typed}' is deprecated${use}\n`);
+}
+function emit(io, outcome) {
+    if (outcome.text !== undefined) {
+        io.out.write(outcome.text);
+        return io.exit(ExitCode.OK);
+    }
+    const meta = { provenance: outcome.provenance ?? {}, ...(outcome.changed === undefined ? {} : { changed: outcome.changed }) };
+    const envelope = { ok: true, data: outcome.data, meta };
+    io.out.write(outcome.json ? `${JSON.stringify(envelope)}\n` : `${render(outcome.data)}\n`);
+    return io.exit(ExitCode.OK);
+}
+async function report(cause, { manifest, io, argv, json, name }) {
+    const failure = describeFailure(cause, argv);
+    if (failure.silent === true)
+        return io.exit(failure.code);
+    await manifest.fire('onError', name, {});
+    if (failure.action !== undefined) {
+        const next = runnableNext(manifest, failure.action, json);
+        const rendered = { ...failure, action: { ...failure.action, next } };
+        const body = { ok: false, status: 'action_required', reason: failure.action.reason, message: failure.message, next, hint: failure.hint, error: { code: failure.code, message: failure.message } };
+        io.err.write(json ? `${JSON.stringify(body)}\n` : textFailure(rendered));
+        return io.exit(failure.code);
+    }
+    const body = { code: failure.code, message: failure.message, hint: failure.hint };
+    io.err.write(json ? `${JSON.stringify({ ok: false, error: body })}\n` : textFailure(failure));
+    return io.exit(failure.code);
+}
+function ioOf(opts) {
+    const out = opts.stdout ?? process.stdout;
+    return {
+        out,
+        err: opts.stderr ?? process.stderr,
+        env: opts.env ?? process.env,
+        exit: opts.exit ?? processExit,
+        width: out.columns ?? HELP_WIDTH,
+        stdin: opts.stdin ?? process.stdin,
+        cwd: opts.cwd ?? process.cwd(),
+        pkg: nearestPackage(dirname(opts.entry ?? process.argv[1] ?? process.cwd())),
+        tty: out.isTTY === true,
+    };
+}
+export async function execute(manifest, opts = {}) {
+    const io = ioOf(opts);
+    const raw = opts.argv ?? process.argv;
+    const argv = opts.argv === undefined || opts.from === 'node' ? raw.slice(2) : raw;
+    const root = opts.root ?? manifest.rootPath;
+    let json = beforeTerminator(argv).includes('--json');
+    let name = '';
+    try {
+        if (await surface(manifest, argv, io))
+            return io.exit(ExitCode.OK);
+        const { node, rest } = manifest.resolve(argv, root);
+        if (node?.run === undefined) {
+            const { text, code } = unresolved({ manifest, root, io }, argv, node);
+            (code === ExitCode.OK ? io.out : io.err).write(text);
+            return io.exit(code);
+        }
+        name = node.path.slice(root.length).join(' ');
+        const outcome = await dispatch(manifest, { node: node, rest, name }, io);
+        json = outcome.json;
+        return emit(io, outcome);
+    }
+    catch (cause) {
+        return await report(cause, { manifest, io, argv, json, name });
+    }
+}
+export function resolveCommand(manifest, argv) {
+    const { node } = manifest.resolve(beforeTerminator(argv), manifest.rootPath);
+    return node ?? null;
+}
+export async function runCommand(manifest, argv, opts = {}) {
+    const out = [];
+    const err = [];
+    let code = ExitCode.OK;
+    await execute(manifest, { ...opts, argv: [...argv], from: 'user', stdout: { write: (s) => out.push(s) }, stderr: { write: (s) => err.push(s) }, exit: (c) => void (code = c) });
+    return { code, stdout: out.join(''), stderr: err.join('') };
+}
+export async function run(target, opts = {}) {
+    if (target instanceof Manifest)
+        return await execute(target, opts);
+    const manifest = new Manifest();
+    manifest.rootPath = [target.name];
+    manifest.add({
+        path: [target.name],
+        ...(target.description === undefined ? {} : { description: target.description }),
+        options: target.options ?? {},
+        ...(target.run === undefined ? {} : { run: target.run }),
+    });
+    return await execute(manifest, opts);
+}

package/dist/exit-code.d.ts

@@ -0,0 +1,18 @@
+/** E1 — exit codes are a contract. No other literal may reach `process.exitCode`. */
+export declare const ExitCode: {
+    /** Command completed. */
+    readonly OK: 0;
+    /** The command ran and failed. Never accompanied by help text (E2). */
+    readonly RUNTIME: 1;
+    /** Bad arguments, unknown command, missing flag, prompt needed in a non-TTY (P2). */
+    readonly USAGE: 2;
+    /** Config file or environment could not be loaded or validated (V1). */
+    readonly CONFIG: 3;
+    /** The user or caller cancelled. */
+    readonly CANCELLED: 4;
+    /** SIGINT after the terminal was restored (E5). */
+    readonly SIGINT: 130;
+};
+export type ExitCode = (typeof ExitCode)[keyof typeof ExitCode];
+/** True for the six codes in the contract and nothing else. */
+export declare function isExitCode(n: unknown): n is ExitCode;

package/dist/exit-code.js

@@ -0,0 +1,12 @@
+export const ExitCode = {
+    OK: 0,
+    RUNTIME: 1,
+    USAGE: 2,
+    CONFIG: 3,
+    CANCELLED: 4,
+    SIGINT: 130,
+};
+const CODES = new Set(Object.values(ExitCode));
+export function isExitCode(n) {
+    return typeof n === 'number' && CODES.has(n);
+}

package/dist/help.d.ts

@@ -0,0 +1,34 @@
+import type { CommandNode, Manifest } from './manifest.js';
+/** The token names of `roundel`'s R3, typed structurally: burgee never imports them (U13). */
+export type HelpToken = 'error' | 'warn' | 'ok' | 'hint' | 'muted' | 'command' | 'flag' | 'value' | 'heading';
+/**
+ * Per-token styling for help (R7). A user who has `roundel` passes its tokens; a user
+ * who does not gets the defaults. Help reads `heading`, `command`, `flag` and `value`;
+ * the others are accepted so one theme object serves the whole output stack.
+ *
+ * What the theme does not touch: the command name after `Usage:` and every `$ example`
+ * line are rendered plain, whatever the theme says. Styling wraps a finished cell, so a
+ * name is measured and padded plain and never coloured in the manifest (yargs #1699).
+ */
+export type HelpTheme = Partial<Record<HelpToken, (s: string) => string>>;
+export interface HelpOptions {
+    /** Columns available; 100 when unknown, never `process.stdout` directly (H3). */
+    width?: number;
+    /** Show type hints such as `[string]`; off by default (H6). */
+    verbose?: boolean;
+    /** Apply colour (R7). Off by default: the renderer is pure, so the TTY and NO_COLOR decision stays with the caller. */
+    color?: boolean;
+    /**
+     * Replaces the default styling token by token; read only when `color` is on. See
+     * `HelpTheme` for the lines it leaves plain: the `Usage:` command name and `$ example`.
+     */
+    theme?: HelpTheme;
+}
+/** Word-wrap one paragraph; lines the author indented are kept verbatim (yargs #2120). */
+export declare function wrap(text: string, width: number): string[];
+/**
+ * Render help for one node — a runnable command, a group, or both — as text.
+ * Deterministic for a given node and width; a snapshot suite pins it. With `color`
+ * off — the default — a theme changes nothing; with it on, only ANSI is added.
+ */
+export declare function renderHelp(manifest: Manifest, node: CommandNode, opts?: HelpOptions): string;