burgee 0.11.1 → 0.12.0

package/dist/program.d.ts

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

package/dist/program.js

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

package/dist/runtime.d.ts

@@ -75,7 +75,9 @@ export declare const host: {
      * rather than the 80-column fallback.
      */
     readonly columns: number | undefined;
-    readonly exitCode: number | string | null | undefined;
+    get exitCode(): number | string | null | undefined;
+    /** The code the process leaves with once its work is done — set, never `exit()`, so stdout drains first. */
+    set exitCode(code: ExitCode);
     readonly platform: string;
     readonly execPath: string;
     readonly execArgv: string[];

package/dist/runtime.js

@@ -29,6 +29,9 @@ export const host = {
     get exitCode() {
         return process.exitCode;
     },
+    set exitCode(code) {
+        process.exitCode = code;
+    },
     get platform() {
         return process.platform;
     },

package/dist/schema.d.ts

@@ -49,6 +49,8 @@ export interface CommandSchema {
      * it cannot tell from a command that does not exist (N6).
      */
     effects?: DeclaredEffects;
+    /** What `--json=` selects from (N14), when the command declares it. */
+    fields?: readonly string[];
     deprecated?: boolean | string;
     /** The heading it is listed under (M1). */
     group?: string;
@@ -99,6 +101,11 @@ export interface ProgramSchema {
     name: string;
     version?: string;
     description?: string;
+    /**
+     * F1 — what each exit code means, so an agent branches on the number without reading prose:
+     * the contract's seven, the same table `ExitCode` exports.
+     */
+    exitCodes: Readonly<Record<string, number>>;
     commands: CommandSchema[];
 }
 export declare function inputSchemaOf(node: CommandNode): JsonSchema;

package/dist/schema.js

@@ -1,3 +1,4 @@
+import { ExitCode } from './exit-code.js';
 import { relationsOf } from './manifest.js';
 import { flagsOf, kebab } from './names.js';
 export const PREDICATE = '(predicate)';
@@ -66,6 +67,7 @@ export function inputSchemaOf(node) {
 export function typedName(node, root) {
     return node.path.slice(root.length).join(' ');
 }
+const PASSED_THROUGH = ['description', 'summary', 'effects', 'fields', 'deprecated', 'group'];
 export function commandSchemaOf(node, root) {
     const out = {
         name: typedName(node, root),
@@ -74,16 +76,9 @@ export function commandSchemaOf(node, root) {
         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;
+    for (const key of PASSED_THROUGH)
+        if (node[key] !== undefined)
+            Object.assign(out, { [key]: node[key] });
     if (node.load !== undefined)
         out.lazy = true;
     if (node.plugin !== undefined)
@@ -121,7 +116,7 @@ export function summaryOf(manifest, budget) {
 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)) };
+    const out = { schemaVersion: 1, name: root.join(' '), exitCodes: ExitCode, commands: runnable(manifest).map((c) => commandSchemaOf(c, root)) };
     if (manifest.version !== undefined)
         out.version = manifest.version;
     const description = program?.description;

package/dist/schema.json

@@ -1 +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"},"widths":{"$ref":"#/$defs/widths"},"resolvers":{"type":"object","description":"bellpull resolvers by name: extra directories searched for an executable, before PATH (negative rank) or after it (positive). Two resolvers with one name shadow; two names both apply, in rank order.","additionalProperties":{"$ref":"#/$defs/resolver"}},"widgets":{"type":"object","description":"caique prompt widgets by kind. The six built-in kinds — text, confirm, select, multiselect, password, path — cannot be replaced: a plugin adds kinds of its own.","additionalProperties":{"$ref":"#/$defs/widget"}},"handlers":{"type":"array","description":"closeout exit handlers. The phase decides the order they run in, not their position in this list.","items":{"$ref":"#/$defs/handler"}},"sources":{"type":"object","description":"seniority configuration sources by name, ranked against the built-in layers: a flag is 0 and a declared default is 40, and a plugin source sits strictly between.","additionalProperties":{"$ref":"#/$defs/source"}},"commands":{"type":"array","description":"burgee commands this plugin contributes. Each is read by exactly the code a program's own command is, and a burgee plugin must declare `contract`.","items":{"$ref":"#/$defs/command"}},"hooks":{"type":"object","description":"burgee lifecycle hooks. preRun opens around a command, and exactly one of postRun or onError closes.","additionalProperties":false,"properties":{"preRun":{"$ref":"#/$defs/hook"},"postRun":{"$ref":"#/$defs/hook"},"onError":{"$ref":"#/$defs/hook"}}},"enforce":{"type":"string","pattern":"^(pre|post)$","description":"burgee: order this plugin's hooks before (`pre`) or after (`post`) the others."}},"$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"}]},"widthRange":{"type":"array","description":"One inclusive code-point range, as [low, high]. A single code point is written [n, n].","items":{"type":"integer","minimum":0,"maximum":1114111},"minItems":2,"maxItems":2},"widthOverride":{"type":"object","description":"A linegauge width override: the column count a named set of code-point ranges occupies, for a terminal that disagrees with the Unicode tables. Data only — no function, so it can be written in a config file, diffed, and printed by `linegauge check` without running anyone code.","required":["ranges","columns","why"],"additionalProperties":false,"properties":{"ranges":{"type":"array","description":"The code points this override applies to.","items":{"$ref":"#/$defs/widthRange"},"minItems":1},"columns":{"type":"integer","description":"Columns each cluster in those ranges occupies: 0 for a zero-width mark, 1 narrow, 2 wide.","minimum":0,"maximum":2},"why":{"type":"string","description":"The terminal or the reason. Required, because a width table with no provenance is one nobody can audit when it turns out to be wrong — which is the normal outcome for ambiguous width.","minLength":1}}},"widths":{"type":"object","description":"linegauge width overrides by name — the measurement section of a plugin, read the way flagstaff reads `spinners`.","additionalProperties":{"$ref":"#/$defs/widthOverride"}},"resolver":{"type":"object","required":["rank","paths"],"description":"One bellpull resolver: where to look for an executable, and when.","properties":{"rank":{"type":"number","description":"Search order against PATH: negative searches before it, positive after."},"paths":{"type":"array","minItems":1,"description":"Directories to search. `{VAR}` is substituted from the environment; each must be absolute, or start with a `{VAR}` that holds an absolute path.","items":{"type":"string","minLength":1,"pattern":"^(/|\\{|[A-Za-z]:[\\\\/]|\\\\\\\\)"}},"extensions":{"type":"array","items":{"type":"string"},"description":"Extensions to try on Windows, in place of PATHEXT."},"when":{"type":"object","description":"When the resolver applies. Leave it out and it always does.","properties":{"platform":{"type":"array","items":{"type":"string"},"description":"process.platform values it applies on."},"envAny":{"type":"array","items":{"type":"string"},"description":"It applies when any of these environment variables is set."}}}}},"widget":{"type":"object","required":["static"],"description":"One caique widget: how a prompt kind of the plugin's own is drawn.","properties":{"static":{"description":"(spec) => string. Required: what a pipe, an agent or a screen reader gets instead of the interactive prompt."},"frame":{"description":"(t, spec) => string. Optional: the animated form; leave it out and the widget is line-mode only."},"sample":{"type":"object","required":["running","done"],"description":"Two named states of plain data that `caique check` renders the widget with."}}},"handler":{"type":"object","required":["name","run"],"description":"One closeout exit handler.","properties":{"name":{"type":"string","minLength":1,"description":"How the handler is named in a report, including the one the deadline prints when it does not return."},"phase":{"type":"string","pattern":"^(flush|release)$","description":"When it runs. Defaults to `release`; `restore` is closeout's own last phase and a plugin may not use it."},"run":{"description":"(info) => void | Promise<void>. Required: the cleanup itself."}}},"source":{"type":"object","required":["rank"],"description":"One seniority source. Exactly one of `values` (static) or `read(runtime)` (fetched) gives its answer.","properties":{"rank":{"type":"integer","minimum":1,"maximum":39,"description":"Precedence, strictly between the flag (0) and the declared default (40): a source may not beat what the user typed, nor sink below the default."},"values":{"type":"object","description":"Option name to value."},"read":{"description":"(runtime) => { values, location? } | undefined."},"location":{"type":"string","description":"The file, URL or variable set a person would go and look at."}}},"option":{"type":"object","required":["type"],"description":"One burgee option, keyed by its camelCase name; the flag is its kebab-case form.","properties":{"type":{"type":"string","pattern":"^(string|boolean|number)$"},"description":{"type":"string"},"short":{"type":"string","minLength":1},"required":{"type":"boolean"},"env":{"type":"string"},"choices":{"type":"array","items":{"type":"string"}},"dependsOn":{"type":"array","items":{"type":"string"},"description":"Options that must be set with this one; each must be another option of the same command."},"exclusive":{"type":"array","items":{"type":"string"},"description":"Options that may not be set with this one; each must be another option of the same command."},"deprecated":{"description":"What replaces this option, e.g. '--force'. `true` alone, or an empty string, is refused: a deprecation names its replacement."}}},"command":{"type":"object","required":["path"],"description":"One burgee command node, declared exactly as a program's own command is.","properties":{"path":{"type":"array","minItems":1,"items":{"type":"string","minLength":1},"description":"The words a user types. May not repeat a path the program or an earlier plugin already declares."},"description":{"type":"string"},"options":{"type":"object","additionalProperties":{"$ref":"#/$defs/option"}},"effects":{"type":"string","pattern":"^(read_only|idempotent|non_idempotent|withheld)$","description":"What running it does to the world. Required on any command that runs; `withheld` serves it to people and keeps it out of the MCP tool list."},"deprecated":{"description":"What replaces this command. `true` alone, or an empty string, is refused."},"run":{"description":"(ctx) => unknown. What the command does; its return value is the `--json` envelope's data."},"load":{"description":"() => Promise<module>. A lazy form of `run`, imported on dispatch."}}},"hook":{"type":"object","required":["handler"],"description":"One burgee hook.","properties":{"filter":{"type":"object","description":"`{ command: RegExp }`: fire only for commands whose path matches."},"handler":{"description":"(ctx) => void | Promise<void>. Required."}}}}}
+{"$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"},"widths":{"$ref":"#/$defs/widths"},"resolvers":{"type":"object","description":"bellpull resolvers by name: extra directories searched for an executable, before PATH (negative rank) or after it (positive). Two resolvers with one name shadow; two names both apply, in rank order.","additionalProperties":{"$ref":"#/$defs/resolver"}},"widgets":{"type":"object","description":"caique prompt widgets by kind. The six built-in kinds — text, confirm, select, multiselect, password, path — cannot be replaced: a plugin adds kinds of its own.","additionalProperties":{"$ref":"#/$defs/widget"}},"handlers":{"type":"array","description":"closeout exit handlers. The phase decides the order they run in, not their position in this list.","items":{"$ref":"#/$defs/handler"}},"sources":{"type":"object","description":"seniority configuration sources by name, ranked against the built-in layers: a flag is 0 and a declared default is 40, and a plugin source sits strictly between.","additionalProperties":{"$ref":"#/$defs/source"}},"commands":{"type":"array","description":"burgee commands this plugin contributes. Each is read by exactly the code a program's own command is, and a burgee plugin must declare `contract`.","items":{"$ref":"#/$defs/command"}},"hooks":{"type":"object","description":"burgee lifecycle hooks. parse rewrites argv before a command is resolved; preRun opens around a command, and exactly one of postRun or onError closes; shutdown fires once as the program leaves, by any path.","additionalProperties":false,"properties":{"parse":{"$ref":"#/$defs/hook"},"preRun":{"$ref":"#/$defs/hook"},"postRun":{"$ref":"#/$defs/hook"},"onError":{"$ref":"#/$defs/hook"},"shutdown":{"$ref":"#/$defs/hook"}}},"enforce":{"type":"string","pattern":"^(pre|post)$","description":"burgee: order this plugin's hooks before (`pre`) or after (`post`) the others."}},"$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"}]},"widthRange":{"type":"array","description":"One inclusive code-point range, as [low, high]. A single code point is written [n, n].","items":{"type":"integer","minimum":0,"maximum":1114111},"minItems":2,"maxItems":2},"widthOverride":{"type":"object","description":"A linegauge width override: the column count a named set of code-point ranges occupies, for a terminal that disagrees with the Unicode tables. Data only — no function, so it can be written in a config file, diffed, and printed by `linegauge check` without running anyone code.","required":["ranges","columns","why"],"additionalProperties":false,"properties":{"ranges":{"type":"array","description":"The code points this override applies to.","items":{"$ref":"#/$defs/widthRange"},"minItems":1},"columns":{"type":"integer","description":"Columns each cluster in those ranges occupies: 0 for a zero-width mark, 1 narrow, 2 wide.","minimum":0,"maximum":2},"why":{"type":"string","description":"The terminal or the reason. Required, because a width table with no provenance is one nobody can audit when it turns out to be wrong — which is the normal outcome for ambiguous width.","minLength":1}}},"widths":{"type":"object","description":"linegauge width overrides by name — the measurement section of a plugin, read the way flagstaff reads `spinners`.","additionalProperties":{"$ref":"#/$defs/widthOverride"}},"resolver":{"type":"object","required":["rank","paths"],"description":"One bellpull resolver: where to look for an executable, and when.","properties":{"rank":{"type":"number","description":"Search order against PATH: negative searches before it, positive after."},"paths":{"type":"array","minItems":1,"description":"Directories to search. `{VAR}` is substituted from the environment; each must be absolute, or start with a `{VAR}` that holds an absolute path.","items":{"type":"string","minLength":1,"pattern":"^(/|\\{|[A-Za-z]:[\\\\/]|\\\\\\\\)"}},"extensions":{"type":"array","items":{"type":"string"},"description":"Extensions to try on Windows, in place of PATHEXT."},"when":{"type":"object","description":"When the resolver applies. Leave it out and it always does.","properties":{"platform":{"type":"array","items":{"type":"string"},"description":"process.platform values it applies on."},"envAny":{"type":"array","items":{"type":"string"},"description":"It applies when any of these environment variables is set."}}}}},"widget":{"type":"object","required":["static"],"description":"One caique widget: how a prompt kind of the plugin's own is drawn.","properties":{"static":{"description":"(spec) => string. Required: what a pipe, an agent or a screen reader gets instead of the interactive prompt."},"frame":{"description":"(t, spec) => string. Optional: the animated form; leave it out and the widget is line-mode only."},"sample":{"type":"object","required":["running","done"],"description":"Two named states of plain data that `caique check` renders the widget with."}}},"handler":{"type":"object","required":["name","run"],"description":"One closeout exit handler.","properties":{"name":{"type":"string","minLength":1,"description":"How the handler is named in a report, including the one the deadline prints when it does not return."},"phase":{"type":"string","pattern":"^(flush|release)$","description":"When it runs. Defaults to `release`; `restore` is closeout's own last phase and a plugin may not use it."},"run":{"description":"(info) => void | Promise<void>. Required: the cleanup itself."}}},"source":{"type":"object","required":["rank"],"description":"One seniority source. Exactly one of `values` (static) or `read(runtime)` (fetched) gives its answer.","properties":{"rank":{"type":"integer","minimum":1,"maximum":39,"description":"Precedence, strictly between the flag (0) and the declared default (40): a source may not beat what the user typed, nor sink below the default."},"values":{"type":"object","description":"Option name to value."},"read":{"description":"(runtime) => { values, location? } | undefined."},"location":{"type":"string","description":"The file, URL or variable set a person would go and look at."}}},"option":{"type":"object","required":["type"],"description":"One burgee option, keyed by its camelCase name; the flag is its kebab-case form.","properties":{"type":{"type":"string","pattern":"^(string|boolean|number)$"},"description":{"type":"string"},"short":{"type":"string","minLength":1},"required":{"type":"boolean"},"env":{"type":"string"},"choices":{"type":"array","items":{"type":"string"}},"dependsOn":{"type":"array","items":{"type":"string"},"description":"Options that must be set with this one; each must be another option of the same command."},"exclusive":{"type":"array","items":{"type":"string"},"description":"Options that may not be set with this one; each must be another option of the same command."},"deprecated":{"description":"What replaces this option, e.g. '--force'. `true` alone, or an empty string, is refused: a deprecation names its replacement."}}},"command":{"type":"object","required":["path"],"description":"One burgee command node, declared exactly as a program's own command is.","properties":{"path":{"type":"array","minItems":1,"items":{"type":"string","minLength":1},"description":"The words a user types. May not repeat a path the program or an earlier plugin already declares."},"description":{"type":"string"},"options":{"type":"object","additionalProperties":{"$ref":"#/$defs/option"}},"effects":{"type":"string","pattern":"^(read_only|idempotent|non_idempotent|withheld)$","description":"What running it does to the world. Required on any command that runs; `withheld` serves it to people and keeps it out of the MCP tool list."},"deprecated":{"description":"What replaces this command. `true` alone, or an empty string, is refused."},"run":{"description":"(ctx) => unknown. What the command does; its return value is the `--json` envelope's data."},"load":{"description":"() => Promise<module>. A lazy form of `run`, imported on dispatch."}}},"hook":{"type":"object","required":["handler"],"description":"One burgee hook.","properties":{"filter":{"type":"object","description":"`{ command: RegExp }`: fire only for commands whose path matches."},"handler":{"description":"(ctx) => void | Promise<void>. Required. On parse it may return the string[] argv to use instead."}}}}}

package/dist/stdin-dash.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Copyright (c) 2026 Ofri Peretz
+ * Licensed under the MIT License. Use of this source code is governed by the
+ * MIT license that can be found in the LICENSE file.
+ */
+/** S4 — imported by `execute.ts` only when a positional is `-` (M2). */
+import { type CommandNode } from './manifest.js';
+/**
+ * S4 — the stdin a `-` names, when a `type: 'file'` argument took it; nothing otherwise. A
+ * variadic file argument covers every position from its own. Standard input can be read once,
+ * so `-` for two file arguments is refused rather than handed to both.
+ */
+export declare function stdinFor(node: CommandNode, positionals: readonly string[], stdin: NodeJS.ReadableStream): {
+    stdin?: NodeJS.ReadableStream;
+};

package/dist/stdin-dash.js

@@ -0,0 +1,12 @@
+import { UsageError } from './validate.js';
+export function stdinFor(node, positionals, stdin) {
+    const args = node.arguments ?? [];
+    const last = args.at(-1);
+    const isFile = (i) => (args[i] ?? (last?.variadic === true ? last : undefined))?.type === 'file';
+    const dashes = positionals.filter((p, i) => p === '-' && isFile(i)).length;
+    if (dashes === 0)
+        return {};
+    if (dashes > 1)
+        throw new UsageError(`"-" was given for ${String(dashes)} file arguments, and standard input can be read once`, 'pass a path for all but one of them');
+    return { stdin };
+}

package/dist/validate.d.ts

@@ -1,31 +1,4 @@
-/**
- * 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). */
-export declare class UsageError extends Error {
-    readonly hint?: string | undefined;
-    constructor(message: string, hint?: string | undefined);
-}
-/**
- * E6 — the far side said no. Throw this and the run leaves with `ExitCode.AUTH`.
- *
- * The one error class whose *response* is unambiguous: not "read the message and decide" but
- * "get a credential and run it again". A handler that throws a bare `Error` for a 401 gets
- * `RUNTIME`, which is the code for everything, and a caller retrying on it retries forever.
- *
- * `fix` is the exact command that gets the credential, where the program knows it — `hint` is
- * prose a person reads and `fix` is a line a caller runs, which is the turn the field saves.
- */
-export declare class AuthError extends Error {
-    readonly hint?: string | undefined;
-    readonly fix?: string | undefined;
-    constructor(message: string, hint?: string | undefined, fix?: string | undefined);
-}
 type Sources = Record<string, {
     source: string;
 }>;
@@ -37,3 +10,4 @@ export declare function splitMultiple(spec: OptionSpec, raw: unknown): unknown[]
 /** Every option's resolved value, coerced and validated: numbers, choices, then its Standard Schema (S3, S6). */
 export declare function coerce(specs: Record<string, OptionSpec>, values: Record<string, unknown>): Promise<Record<string, unknown>>;
 export { camel, kebab } from './names.js';
+export { AuthError, UsageError } from './errors.js';

package/dist/validate.js

@@ -1,21 +1,5 @@
+import { UsageError } from './errors.js';
 import { flagsOf, kebab } from './names.js';
-export class UsageError extends Error {
-    hint;
-    constructor(message, hint) {
-        super(message);
-        this.hint = hint;
-    }
-}
-export class AuthError extends Error {
-    hint;
-    fix;
-    constructor(message, hint, fix) {
-        super(message);
-        this.hint = hint;
-        this.fix = fix;
-        this.name = 'AuthError';
-    }
-}
 const isSet = (values, key, sources) => values[key] !== undefined && sources[key]?.source !== 'default';
 const flagList = (keys) => flagsOf(keys).join(', ');
 function exactlyOne(keys, on) {
@@ -118,3 +102,4 @@ export async function coerce(specs, values) {
     return { ...values, ...Object.fromEntries(coerced) };
 }
 export { camel, kebab } from './names.js';
+export { AuthError, UsageError } from './errors.js';

package/dist/yargs/factory.js

@@ -1,6 +1,8 @@
 var _a;
 import { ExitCode } from '../exit-code.js';
+import { handlerFailure } from '../facade-failure.js';
 import { Manifest } from '../manifest.js';
+import { host } from '../runtime.js';
 import { machineJson, schemaOf } from '../schema.js';
 import { tokenizeArgString } from '../yargs-parser.js';
 import { projectManifest, render } from './burgee.js';
@@ -343,17 +345,18 @@ export class YargsInstance {
         this.#hasOutput = true;
         this.#exitError = err;
         const burgee = this.#burgee;
+        const e1 = code === 0 ? ExitCode.OK : this.#failureOf(err).exit;
         if (burgee !== undefined && code !== 0 && burgee.json)
             this.#failureEnvelope(err);
         if (burgee?.exit !== undefined) {
             if (burgee.exited)
                 return;
             burgee.exited = true;
-            burgee.exit(code === 0 ? ExitCode.OK : err instanceof YError || err === undefined || typeof err === 'string' ? ExitCode.USAGE : ExitCode.RUNTIME);
+            burgee.exit(e1);
             return;
         }
         if (this.#exitProcess)
-            this.#shim.process.exit(code);
+            this.#shim.process.exit(burgee?.json === true ? e1 : code);
     }
     exitProcess(enabled = true) {
         argsert('[boolean]', [enabled], arguments.length);
@@ -598,19 +601,28 @@ export class YargsInstance {
         };
         const seam = this.#burgee?.exit === undefined ? undefined : this.#burgee;
         if (seam === undefined) {
+            const escape = (err) => {
+                const json = this.#burgee?.json === true && !(err instanceof YError);
+                if (json)
+                    this.#failJson(err);
+                restore();
+                if (!json)
+                    throw err;
+                return undefined;
+            };
             try {
                 const result = this.#parse(args, shortCircuit, _parseFn);
                 if (isPromise(result))
-                    return result.finally(restore);
+                    return result.then((argv) => (restore(), argv), escape);
                 restore();
                 return result;
             }
             catch (err) {
-                restore();
-                throw err;
+                return escape(err);
             }
         }
         seam.exited = false;
+        seam.reported = false;
         const finish = (argv) => {
             if (!this.#burgee?.exited)
                 seam.exit?.(ExitCode.OK);
@@ -622,13 +634,13 @@ export class YargsInstance {
                 restore();
                 throw err;
             }
-            const message = err instanceof Error ? err.message : String(err);
+            const failure = this.#failureOf(err);
             if (this.#burgee?.json)
-                this.#failureEnvelope(err instanceof Error ? err : message);
+                this.#failureEnvelope(err);
             else
-                this.#logger.error(message);
+                this.#logger.error(failure.error.message);
             if (!this.#burgee?.exited)
-                seam.exit?.(ExitCode.RUNTIME);
+                seam.exit?.(failure.exit);
             restore();
             return undefined;
         };
@@ -1236,7 +1248,7 @@ export class YargsInstance {
             return args;
         if (this.#declares('json'))
             return args;
-        this.#burgee = { ...(this.#burgee ?? { lastError: '' }), json: true };
+        this.#burgee = { ...(this.#burgee ?? { lastError: '' }), json: true, reported: false };
         return [...list.slice(0, index), ...list.slice(index + 1)];
     }
     #declares(key) {
@@ -1334,11 +1346,25 @@ export class YargsInstance {
         if (text !== '')
             this.#logger.log(text.replace(/\n$/, ''));
     }
+    #failureOf(err) {
+        if (err instanceof YError || err === undefined)
+            return { exit: ExitCode.USAGE, error: { code: 'usage', message: err?.message ?? (this.#burgee?.lastError ?? '') } };
+        return handlerFailure(err);
+    }
     #failureEnvelope(err) {
         const burgee = this.#burgee;
-        const message = err instanceof Error ? err.message : typeof err === 'string' ? err : burgee.lastError;
-        const code = err instanceof YError || err === undefined || typeof err === 'string' ? 'usage' : 'runtime';
-        this.#logger.log(JSON.stringify({ ok: false, error: { code, message } }));
+        if (burgee.reported === true)
+            return;
+        burgee.reported = true;
+        this.#logger.log(JSON.stringify({ ok: false, error: this.#failureOf(err).error }));
+    }
+    #failJson(err) {
+        this.#failureEnvelope(err);
+        const { exit } = this.#failureOf(err);
+        if (this.#exitProcess)
+            this.#shim.process.exit(exit);
+        else
+            host.exitCode = exit;
     }
     #provenance(argv) {
         const out = {};