burgee 0.8.0 → 0.9.0

package/dist/meow/present.js

@@ -0,0 +1,58 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { host } from '../runtime.js';
+const indent = (text, spaces) => text.replace(/^(?!\s*$)/gmu, ' '.repeat(spaces));
+export function readPackageUp(importMeta) {
+    if (importMeta?.url === undefined)
+        return {};
+    let dir = dirname(fileURLToPath(importMeta.url));
+    for (let depth = 0; depth < 64; depth += 1) {
+        try {
+            return JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+        }
+        catch {
+            const up = dirname(dir);
+            if (up === dir)
+                break;
+            dir = up;
+        }
+    }
+    return {};
+}
+export function buildHelp(options, pkg) {
+    const description = options.description === false ? '' : (options.description ?? pkg['description'] ?? '');
+    const body = options.help === false ? '' : stripIndent(options.help ?? '');
+    const parts = [description, body].filter((p) => p !== '');
+    if (parts.length === 0)
+        return '';
+    const text = parts.join('\n\n');
+    const width = options.helpIndent ?? 2;
+    return `\n${text.includes('\n') ? indent(text, width) : text}\n`;
+}
+export function stripIndent(text) {
+    const lines = text.split('\n');
+    const widths = lines.filter((l) => l.trim() !== '').map((l) => (/^(\s*)/u.exec(l)?.[1] ?? '').length);
+    const smallest = widths.length === 0 ? 0 : Math.min(...widths);
+    return lines
+        .map((l) => l.slice(smallest))
+        .join('\n')
+        .trim();
+}
+export function normalizePackage(pkg) {
+    const out = { ...pkg };
+    const name = typeof out['name'] === 'string' ? out['name'].replace(/^@[^/]+\//u, '') : undefined;
+    if (typeof out['bin'] === 'string' && name !== undefined)
+        out['bin'] = Object.fromEntries([[name, out['bin']]]);
+    if (out['version'] === undefined)
+        out['version'] = '';
+    return out;
+}
+export function setProcessTitle(pkg) {
+    const bin = pkg['bin'];
+    const first = typeof bin === 'object' && bin !== null ? Object.keys(bin)[0] : undefined;
+    const name = typeof pkg['name'] === 'string' ? pkg['name'].replace(/^@[^/]+\//u, '') : undefined;
+    const title = first ?? name;
+    if (title !== undefined && title !== '')
+        host.setTitle(title);
+}

package/dist/meow/types.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `burgee/meow` — the option and result shapes meow's callers write against.
+ *
+ * Kept beside the implementation rather than inside it because three files read them and a
+ * façade's contract is the part most worth seeing on its own.
+ */
+export interface AnyFlag {
+    type?: 'string' | 'boolean' | 'number';
+    alias?: string;
+    aliases?: string[];
+    shortFlag?: string;
+    default?: unknown;
+    isRequired?: boolean | ((flags: Record<string, unknown>, input: string[]) => boolean);
+    isMultiple?: boolean;
+    choices?: unknown[];
+}
+export interface Options {
+    importMeta?: ImportMeta;
+    argv?: readonly string[];
+    description?: string | false;
+    help?: string | false;
+    version?: string | false;
+    autoHelp?: boolean;
+    autoVersion?: boolean;
+    helpIndent?: number;
+    flags?: Record<string, AnyFlag>;
+    pkg?: Record<string, unknown>;
+    input?: unknown;
+    inferType?: boolean;
+    booleanDefault?: boolean | null | undefined;
+    hardRejection?: boolean;
+    allowUnknownFlags?: boolean;
+    commands?: string[];
+}
+export interface Result {
+    input: string[];
+    flags: Record<string, unknown>;
+    unnormalizedFlags: Record<string, unknown>;
+    pkg: Record<string, unknown>;
+    help: string;
+    version: string;
+    command?: string;
+    showHelp: (code?: number) => never;
+    showVersion: () => void;
+}
+/** An own property under a key the caller chose — never the prototype setter. */
+export declare function own(target: Record<string, unknown>, key: string, value: unknown): void;

package/dist/meow/types.js

@@ -0,0 +1,3 @@
+export function own(target, key, value) {
+    Object.defineProperty(target, key, { value, writable: true, enumerable: true, configurable: true });
+}

package/dist/meow/validate.d.ts

@@ -0,0 +1,35 @@
+import { type AnyFlag, type Options } from './types.js';
+export declare function validateFlags(flags: Record<string, AnyFlag>): void;
+/** meow refuses to guess where the caller's `package.json` is. */
+/** meow refuses to guess where the caller's `package.json` is. */
+export declare function requireImportMeta(importMeta: ImportMeta | undefined): void;
+/** meow, over burgee's parser. */
+/** `commands` is an array of bare words, and meow says so in three different sentences. */
+export declare function validateCommands(commands: string[] | undefined): void;
+/**
+ * Where the parent's arguments end and the command's begin.
+ *
+ * The first token the parser reads as positional is the command word; everything after it in
+ * the *raw* argv is the child's, unparsed. `--` is not a fence here — the suite states that
+ * `-- --unknown run` reports `Unknown command: --unknown`, so a post-separator word is a
+ * candidate command like any other.
+ */
+export declare function checkChoices(specs: Record<string, AnyFlag>, flags: Record<string, unknown>): void;
+export declare function checkRequired(specs: Record<string, AnyFlag>, flags: Record<string, unknown>, input: string[]): void;
+export declare function checkUnknown(specs: Record<string, AnyFlag>, parsedFlags: Record<string, unknown>, argv: string[], opts: Options): void;
+/** `commands` is an array of bare words, and meow says so in three different sentences. */
+/** meow's `input` option may demand positionals, as a boolean or as a predicate. */
+export declare function checkInput(opts: Options, input: string[], flags: Record<string, unknown>): void;
+/** A flag declared once may be given once — the parser collects repeats into an array. */
+/** A flag declared once may be given once — the parser collects repeats into an array. */
+export declare function checkSetOnce(specs: Record<string, AnyFlag>, parsed: Record<string, unknown>): void;
+/**
+ * The half of `normalize-package-data` meow's callers can see.
+ *
+ * `bin` as a string becomes `{ [name]: path }` — the suite reads `cli.pkg.bin['browser-sync']`
+ * — and an absent `version` becomes `''`. A copy, because `pkg normalization is lazy` asserts
+ * the object the caller passed in is untouched.
+ */
+/** stderr and exit 2 — how meow ends a run the flags do not support. */
+export declare function reportAndExit(message: string): never;
+/** meow's `input` option may demand positionals, as a boolean or as a predicate. */

package/dist/meow/validate.js

@@ -0,0 +1,144 @@
+import { fileURLToPath } from 'node:url';
+import { ExitCode } from '../exit-code.js';
+import { host } from '../runtime.js';
+import { camelCase, decamelize } from '../yargs-parser.js';
+export function validateFlags(flags) {
+    const errors = [];
+    const kebab = Object.keys(flags).filter((name) => name.includes('-') && name !== '--');
+    if (kebab.length > 0)
+        errors.push(`Flag keys may not contain '-'. Invalid flags: ${kebab.map((k) => `\`${k}\``).join(', ')}`);
+    const renamed = Object.entries(flags).filter(([, spec]) => typeof spec.alias === 'string');
+    if (renamed.length > 0) {
+        errors.push(`The option \`alias\` has been renamed to \`shortFlag\`. The following flags need to be updated: ${renamed.map(([n]) => `\`--${n}\``).join(', ')}`);
+    }
+    const badChoices = Object.entries(flags).filter(([, spec]) => spec.choices !== undefined && !Array.isArray(spec.choices));
+    if (badChoices.length > 0) {
+        errors.push(`The option \`choices\` must be an array. Invalid flags: ${badChoices.map(([n]) => `\`--${n}\``).join(', ')}`);
+    }
+    for (const [name, spec] of Object.entries(flags)) {
+        if (spec.default === undefined || spec.type === undefined)
+            continue;
+        const values = Array.isArray(spec.default) ? spec.default : [spec.default];
+        const wrong = values.find((v) => typeof v !== spec.type);
+        if (wrong !== undefined)
+            errors.push(`Expected "${name}" default value to be of type "${String(spec.type)}", got "${typeof wrong}"`);
+    }
+    if (errors.length > 0)
+        throw new Error(`${errors.join('\n')}`);
+}
+export function requireImportMeta(importMeta) {
+    if (importMeta === undefined || typeof importMeta !== 'object' || typeof importMeta.url !== 'string') {
+        throw new TypeError('The `importMeta` option is required. Its value must be `import.meta`.');
+    }
+    try {
+        fileURLToPath(importMeta.url);
+    }
+    catch {
+        throw new TypeError('The `importMeta` option is required. Its value must be `import.meta`.');
+    }
+}
+export function validateCommands(commands) {
+    if (commands === undefined)
+        return;
+    if (!Array.isArray(commands))
+        throw new TypeError('The `commands` option must be an array of strings.');
+    if (commands.length === 0)
+        throw new TypeError('The `commands` option must contain at least one command.');
+    const bad = commands.some((c) => typeof c !== 'string' || c === '' || /\s/u.test(c) || c.startsWith('-'));
+    if (bad)
+        throw new TypeError('The `commands` option must be an array of non-empty strings without whitespace that do not start with `-`.');
+}
+export function checkChoices(specs, flags) {
+    const errors = [];
+    const badDefaults = Object.entries(specs).filter(([, spec]) => {
+        if (spec.default === undefined || !Array.isArray(spec.choices))
+            return false;
+        return (Array.isArray(spec.default) ? spec.default : [spec.default]).some((d) => !spec.choices?.includes(d));
+    });
+    if (badDefaults.length > 0) {
+        throw new Error(`Each value of the option \`default\` must exist within the option \`choices\`. Invalid flags: ${badDefaults.map(([n]) => `\`--${n}\``).join(', ')}`);
+    }
+    for (const [name, spec] of Object.entries(specs)) {
+        if (spec.choices === undefined || !Array.isArray(spec.choices))
+            continue;
+        const label = `--${decamelize(name, '-')}`;
+        const allowed = `[${spec.choices.map((c) => `\`${String(c)}\``).join(', ')}]`;
+        const value = flags[name];
+        const required = typeof spec.isRequired === 'function' ? true : spec.isRequired === true;
+        if (value === undefined || value === '') {
+            if (required)
+                errors.push(`Flag \`${label}\` has no value. Value must be one of: ${allowed}`);
+            continue;
+        }
+        const values = Array.isArray(value) ? value : [value];
+        const bad = values.filter((v) => !spec.choices?.includes(v));
+        if (bad.length > 0) {
+            errors.push(`Unknown value${bad.length > 1 ? 's' : ''} for flag \`${label}\`: ${bad.map((b) => `\`${String(b)}\``).join(', ')}. Value must be one of: ${allowed}`);
+        }
+    }
+    if (errors.length > 0)
+        throw new Error(`${errors.join('\n')}`);
+}
+export function checkRequired(specs, flags, input) {
+    const missing = [];
+    for (const [name, spec] of Object.entries(specs)) {
+        let required = spec.isRequired;
+        if (typeof spec.isRequired === 'function') {
+            required = spec.isRequired(flags, input);
+            if (typeof required !== 'boolean') {
+                throw new TypeError(`Return value for isRequired callback should be of type boolean, but ${typeof required} was returned.`);
+            }
+        }
+        if (required !== true)
+            continue;
+        const value = flags[name];
+        if (value !== undefined && value !== '' && !(Array.isArray(value) && value.length === 0))
+            continue;
+        const short = typeof spec.shortFlag === 'string' ? `, -${spec.shortFlag}` : '';
+        missing.push(`--${decamelize(name, '-')}${short}`);
+    }
+    if (missing.length > 0) {
+        reportAndExit(`Missing required flag${missing.length > 1 ? 's' : ''}\n${missing.map((m) => `\t${m}`).join('\n')}`);
+    }
+}
+export function checkUnknown(specs, parsedFlags, argv, opts) {
+    const known = new Set(['--']);
+    if (opts.autoHelp !== false)
+        known.add('help');
+    if (opts.autoVersion !== false)
+        known.add('version');
+    for (const [name, spec] of Object.entries(specs)) {
+        known.add(name);
+        known.add(decamelize(name, '-'));
+        if (typeof spec.shortFlag === 'string')
+            known.add(spec.shortFlag);
+        if (typeof spec.alias === 'string')
+            known.add(spec.alias);
+    }
+    const unknown = Object.keys(parsedFlags).filter((k) => !known.has(k) && !known.has(camelCase(k)) && !known.has(decamelize(k, '-')));
+    if (unknown.length > 0) {
+        const names = unknown.map((u) => (u.length === 1 ? `-${u}` : `--${decamelize(u, '-')}`));
+        reportAndExit(`Unknown flag${names.length > 1 ? 's' : ''}\n${names.join('\n')}`);
+    }
+    void argv;
+}
+export function checkInput(opts, input, flags) {
+    if (typeof opts.input !== 'object' || opts.input === null)
+        return;
+    const spec = opts.input;
+    const required = typeof spec.isRequired === 'function' ? spec.isRequired(flags, input) : spec.isRequired === true;
+    if (required && input.length === 0)
+        reportAndExit('Missing required input');
+}
+export function checkSetOnce(specs, parsed) {
+    for (const [name, spec] of Object.entries(specs)) {
+        if (spec.isMultiple === true || name === '--')
+            continue;
+        if (Array.isArray(parsed[name]))
+            throw new Error(`The flag --${decamelize(name, '-')} can only be set once.`);
+    }
+}
+export function reportAndExit(message) {
+    host.stderr.write(`${message}\n`);
+    return host.exit(ExitCode.USAGE);
+}

package/dist/meow.d.ts

@@ -0,0 +1,6 @@
+import { type Options, type Result } from './meow/types.js';
+export { type AnyFlag, type Options, type Result } from './meow/types.js';
+/** meow, over burgee's parser. */
+declare function meow(helpText: string | Options, options?: Options): Result;
+declare const meowFacade: typeof meow;
+export default meowFacade;

package/dist/meow.js

@@ -0,0 +1,146 @@
+import { ExitCode } from './exit-code.js';
+import { aliasMap, splitAtCommand, typeofDefault } from './meow/parse.js';
+import { buildHelp, normalizePackage, readPackageUp, setProcessTitle } from './meow/present.js';
+import { own } from './meow/types.js';
+import { checkChoices, checkInput, checkRequired, checkSetOnce, checkUnknown, requireImportMeta, validateCommands, validateFlags } from './meow/validate.js';
+import { host } from './runtime.js';
+import parser, { camelCase } from './yargs-parser.js';
+function meow(helpText, options = {}) {
+    const opts = typeof helpText === 'string' ? { help: helpText, ...options } : helpText;
+    if (typeof helpText !== 'string' && Object.keys(options).length > 0)
+        Object.assign(opts, options);
+    if (opts.input !== undefined && typeof opts.input !== 'string' && !Array.isArray(opts.input) && typeof opts.input !== 'object') {
+        throw new TypeError('The `input` option must be a string or an object.');
+    }
+    const flagSpecs = (opts.flags ?? {});
+    if (typeof flagSpecs !== 'object' || flagSpecs === null || Array.isArray(flagSpecs)) {
+        throw new TypeError('The `flags` option must be an object.');
+    }
+    if (typeof opts.input === 'object' && opts.input !== null) {
+        const required = opts.input.isRequired;
+        if (required !== undefined && typeof required !== 'boolean' && typeof required !== 'function') {
+            throw new TypeError('The `input.isRequired` option must be a boolean or a function.');
+        }
+    }
+    validateFlags(flagSpecs);
+    if (opts.pkg === undefined)
+        requireImportMeta(opts.importMeta);
+    const pkg = normalizePackage(opts.pkg ?? readPackageUp(opts.importMeta));
+    validateCommands(opts.commands);
+    const rawArgv = [...(opts.argv ?? host.argv.slice(2))];
+    const booleans = [];
+    const strings = [];
+    const numbers = [];
+    const defaults = {};
+    const arrays = [];
+    for (const [name, spec] of Object.entries(flagSpecs)) {
+        if (name === '--')
+            continue;
+        const type = spec.type ?? (spec.default === undefined ? undefined : typeofDefault(spec.default));
+        if (type === 'boolean')
+            booleans.push(name);
+        else if (type === 'number')
+            numbers.push(name);
+        else if (type === 'string')
+            strings.push(name);
+        if (spec.isMultiple === true)
+            arrays.push(name);
+        if (spec.default !== undefined)
+            own(defaults, name, spec.default);
+        else if (type === 'boolean' && 'booleanDefault' in opts) {
+            if (opts.booleanDefault !== undefined)
+                own(defaults, name, opts.booleanDefault);
+        }
+        else if (type === 'boolean')
+            own(defaults, name, false);
+        if (spec.isMultiple === true && spec.default === undefined) {
+            own(defaults, name, type === 'boolean' && !('booleanDefault' in opts) ? [false] : []);
+        }
+    }
+    const parserOptions = {
+        alias: aliasMap(flagSpecs),
+        array: arrays,
+        boolean: booleans,
+        string: strings,
+        number: numbers,
+        default: defaults,
+        configuration: {
+            'camel-case-expansion': true,
+            'greedy-arrays': false,
+            'parse-numbers': opts.inferType === true,
+            'parse-positional-numbers': opts.inferType === true,
+            'populate--': flagSpecs['--'] !== undefined,
+            'strip-aliased': false,
+            'strip-dashed': true,
+            'unknown-options-as-args': false,
+        },
+    };
+    const split = opts.commands === undefined ? undefined : splitAtCommand(rawArgv, parserOptions, opts);
+    const argv = split?.parent ?? rawArgv;
+    const parsed = parser.detailed(argv, parserOptions);
+    const { _: positional, ...rest } = parsed.argv;
+    const inputType = typeof opts.input === 'object' && opts.input !== null ? opts.input.type : opts.input;
+    const coerce = (v) => {
+        if (inputType === 'number')
+            return Number(v);
+        if (inputType === 'string')
+            return String(v);
+        return opts.inferType === true ? v : String(v);
+    };
+    const input = (split === undefined ? positional.map(coerce) : split.input);
+    const command = split?.command;
+    const dropped = new Set();
+    for (const [name, spec] of Object.entries(flagSpecs)) {
+        if (typeof spec.shortFlag === 'string')
+            dropped.add(spec.shortFlag);
+        if (typeof spec.alias === 'string')
+            dropped.add(spec.alias);
+        for (const extra of spec.aliases ?? [])
+            dropped.add(extra);
+        void name;
+    }
+    const flags = {};
+    const unnormalizedFlags = { ...rest };
+    for (const [key, value] of Object.entries(rest)) {
+        if (key === '--' || dropped.has(key))
+            continue;
+        Object.defineProperty(flags, camelCase(key), { value, writable: true, enumerable: true, configurable: true });
+    }
+    if (flagSpecs['--'] !== undefined)
+        flags['--'] = rest['--'] ?? [];
+    const help = buildHelp(opts, pkg);
+    const declared = opts.version === undefined ? undefined : String(opts.version);
+    const fromPkg = typeof pkg['version'] === 'string' && pkg['version'] !== '' ? pkg['version'] : undefined;
+    const version = declared ?? fromPkg ?? 'No version found';
+    const showHelp = (code = ExitCode.USAGE) => {
+        host.stdout.write(help === '' ? '\n' : `${help}\n`);
+        return host.exit(code);
+    };
+    const showVersion = () => {
+        host.stdout.write(`${version}\n`);
+        host.exit(ExitCode.OK);
+    };
+    setProcessTitle(pkg);
+    const result = { input, flags, unnormalizedFlags, pkg, help, version, showHelp, showVersion };
+    if (opts.commands !== undefined && command !== undefined)
+        result.command = command;
+    if (split?.unknownCommand !== undefined) {
+        host.stderr.write(`Unknown command: ${split.unknownCommand}\nAvailable commands: ${opts.commands?.join(', ') ?? ''}\n${help}\n`);
+        host.exit(ExitCode.USAGE);
+    }
+    if (input.length === 0) {
+        if (opts.autoHelp !== false && flagSpecs['help'] === undefined && flags['help'] === true)
+            showHelp(ExitCode.OK);
+        if (opts.autoVersion !== false && flagSpecs['version'] === undefined && flags['version'] === true)
+            showVersion();
+    }
+    checkSetOnce(flagSpecs, rest);
+    checkInput(opts, input, flags);
+    checkChoices(flagSpecs, flags);
+    checkRequired(flagSpecs, flags, input);
+    if (opts.allowUnknownFlags === false)
+        checkUnknown(flagSpecs, rest, argv, opts);
+    return result;
+}
+const meowFacade = meow;
+export default meowFacade;

package/dist/plugin.d.ts

@@ -19,7 +19,7 @@ export interface Plugin {
     };
     enforce?: 'pre' | 'post';
 }
-export type PluginErrorCode = 'E_PLUGIN_SCHEMA' | 'E_PLUGIN_CONTRACT';
+export type PluginErrorCode = 'E_PLUGIN_SCHEMA' | 'E_PLUGIN_CONTRACT' | 'E_NO_CONTRIBUTION';
 /** A refused plugin says what is wrong and what to do about it — the family's one vocabulary. */
 export declare class PluginError extends Error {
     readonly code: PluginErrorCode;

package/dist/plugin.js

@@ -68,7 +68,7 @@ function checkCommands(commands, name, taken) {
         }
         seen.add(path);
         try {
-            checkCommand(path, (node['options'] ?? {}), node['effects'], node['run'] !== undefined || node['load'] !== undefined);
+            checkCommand(path, node);
         }
         catch (error) {
             throw schema(`${at}: ${error.message}`, 'a plugin command is declared exactly as a first-party one');

package/dist/runtime.d.ts

@@ -66,6 +66,8 @@ export declare const host: {
     readonly stdin: NodeJS.ReadStream;
     readonly stdout: NodeJS.WriteStream;
     readonly stderr: NodeJS.WriteStream;
+    /** What `ps` shows. meow renames the process after the binary it is; nothing else sets it. */
+    setTitle(value: string): void;
     /**
      * The terminal's width, or undefined when there is no terminal to ask. Guarded on
      * `process` itself because cliui's upstream is guarded there: `getWindowWidth` is reached

package/dist/runtime.js

@@ -18,6 +18,9 @@ export const host = {
     get stderr() {
         return process.stderr;
     },
+    setTitle(value) {
+        process.title = value;
+    },
     get columns() {
         if (typeof process === 'undefined')
             return undefined;

package/dist/schema-entry.d.ts

@@ -0,0 +1,3 @@
+/** `burgee/schema` — the schema surface and the manifest it reads, by itself. See `index.ts`. */
+export { commandSchemaOf, inputSchemaOf, schemaOf, summaryOf, type CommandSchema, type JsonSchema, type ProgramSchema, type SchemaSummary } from './schema.js';
+export { Manifest } from './manifest.js';

package/dist/schema-entry.js

@@ -0,0 +1,2 @@
+export { commandSchemaOf, inputSchemaOf, schemaOf, summaryOf } from './schema.js';
+export { Manifest } from './manifest.js';

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"}},"$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"}]}}}
+{"$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"}},"$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"}}}}

package/dist/testing-helpers.js

@@ -133,7 +133,9 @@ export async function runBurgee(program, opts) {
         await execute(program, {
             argv: rt.argv,
             env: rt.env,
-            stdout: rt.stdout,
+            cwd: rt.cwd,
+            stdin: rt.stdin,
+            stdout: { write: rt.stdout.write, isTTY: rt.isTTY.stdout },
             stderr: rt.stderr,
             exit: (c) => rt.exit(c),
             root: program.rootPath,

package/dist/validate.d.ts

@@ -11,6 +11,21 @@ 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;
 }>;

package/dist/validate.js

@@ -6,6 +6,16 @@ export class UsageError extends Error {
         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) {

package/dist/yargs/factory.js

@@ -1,7 +1,6 @@
 var _a;
 import { ExitCode } from '../exit-code.js';
 import { Manifest } from '../manifest.js';
-import { serveMcp } from '../mcp.js';
 import { machineJson, schemaOf } from '../schema.js';
 import { tokenizeArgString } from '../yargs-parser.js';
 import { projectManifest, render } from './burgee.js';
@@ -1288,7 +1287,9 @@ export class YargsInstance {
                 return { stdout: out.join(''), stderr: err.join(''), code };
             };
             const write = this.#burgee?.stdout ?? this.#shim.process.stdout();
-            return serveMcp(this.manifest, { input: this.#shim.process.stdin(), output: { write: (s) => void write.write(s) }, invoke }).then(() => {
+            return import('../mcp.js')
+                .then(async ({ serveMcp }) => serveMcp(this.manifest, { input: this.#shim.process.stdin(), output: { write: (s) => void write.write(s) }, invoke }))
+                .then(() => {
                 this.exit(0);
                 return true;
             });
@@ -1315,6 +1316,10 @@ export class YargsInstance {
             .then(async (value) => {
             await manifest.fire('postRun', name, options);
             return settle(value);
+        })
+            .catch(async (cause) => {
+            await manifest.fire('onError', name, options);
+            throw cause;
         });
     }
     #settle(value, argv) {