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;| Parameter | Type |
|---|---|
plugin | Plugin |
Returns Plugin
validate
Refuse a plugin that cannot contribute, at the door.
function validate(plugin: unknown, taken?: readonly string[]): asserts plugin is Plugin;| Parameter | Type |
|---|---|
plugin | unknown |
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';