burgee
API reference

burgee/plugin

Every export of burgee/plugin, with its signature and doc comment: validate, definePlugin, CONTRACT, PluginError, plus 7 types.

import { validate, definePlugin, CONTRACT, … } from 'burgee/plugin';

Functions

definePlugin

Declare a plugin: typed, validated, and stamped with the contract it was compiled against.

function definePlugin(plugin: Plugin): Plugin;
ParameterType
pluginPlugin

Returns Plugin

validate

Refuse a plugin that cannot contribute, at the door.

function validate(plugin: unknown, taken?: readonly string[]): asserts plugin is Plugin;
ParameterType
pluginunknown
taken (optional)readonly string[]

Returns asserts plugin is Plugin

Classes

PluginError

A refused plugin says what is wrong and what to do about it — the family's one vocabulary.

class PluginError extends Error {
    readonly code: PluginErrorCode;
    readonly fix: string;
    constructor(code: PluginErrorCode, message: string, fix: string);
}

Constants

CONTRACT

The plugin contract version. One number for the family — the same 1 flagstaff, caique and closeout declare, written out rather than imported because a layer never imports a layer.

const CONTRACT = 1;

Interfaces

Format

One registered output format (agent-headroom RF).

interface Format {
    /** The data `--json` would carry, as text. Called for a success only, never for a failure. */
    render: (value: unknown) => string;
    /** One line `--format` lists beside the name. */
    description: string;
}

Plugin

The keys burgee reads. Declared structurally: any object with these fields is a plugin here, whatever else it carries.

interface Plugin {
    name: string;
    contract?: number;
    commands?: CommandNode[];
    hooks?: Partial<Record<HookStage, Hook>>;
    enforce?: 'pre' | 'post';
    /**
     * A locale pack (`localised-human-surfaces` R4): language tag → catalog id → translation.
     * Not read at the door — `validate` lets it through like any other key — but checked where it
     * is first used, by the help or refusal it translates, and in full by `burgee check`, against
     * `burgee/locale-pack-schema.json`.
     */
    locales?: Locales;
    /**
     * Output formats (`agent-headroom` RF): a name a caller types as `--format=<name>`, and how a
     * success's data is rendered under it. burgee's own `agent` and `tsv` are registered this same
     * way. Like `locales`, not read at the door — `validate` lets it through and `use()` stays as
     * light as it was — but checked in full where it is first used (`--format`, `formats.ts`) and
     * by `burgee check`. A format renders data only: a failure never reaches one, so it cannot
     * drop the `hint` that failure carries (R6).
     */
    formats?: Record<string, Format>;
}

Types

LocaleMessages

One language's translations, keyed by catalog id.

type LocaleMessages = Readonly<Partial<Record<MessageId, Message>>>;

Locales

A pack's locales: BCP 47 tag → its messages. The whole of what a pack contributes.

type Locales = Readonly<Record<string, LocaleMessages>>;

Message

A translation: one string, or — for a message that carries {count} — one per plural form.

type Message = string | Readonly<Partial<Record<Intl.LDMLPluralRule, string>>>;

MessageId

A catalog id: what a pack keys its translations by.

type MessageId = keyof typeof MESSAGES;

PluginErrorCode

type PluginErrorCode = 'E_PLUGIN_SCHEMA' | 'E_PLUGIN_CONTRACT' | 'E_NO_CONTRIBUTION';

On this page