burgee/plugin

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

FunctionsCopy Anchor Link

definePluginCopy Anchor Link

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

The stamp is the half that makes the refusal in checkContract fair. An author who builds against this burgee gets contract: 1 without typing it, so the only objects that reach use() without one are objects built against a burgee that checked nothing — which is exactly the population the version message is addressed to.

function definePlugin(plugin: Plugin): Plugin;

Returns Plugin

validateCopy Anchor Link

Refuse a plugin that cannot contribute, at the door.

taken is the command paths the manifest already serves. A contributed path that is already declared is refused rather than merged, because the two projections disagree about which node wins: find() answers the first on a path and resolve() the last, so the same command reads one way to help and the other way to dispatch. Which of the two is right for a first-party duplicate is a decision about every program rather than about plugins, and is left alone here.

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

Returns asserts plugin is Plugin

ClassesCopy Anchor Link

PluginErrorCopy Anchor Link

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);
}

ConstantsCopy Anchor Link

CONTRACTCopy Anchor Link

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;

InterfacesCopy Anchor Link

PluginCopy Anchor Link

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';
}

TypesCopy Anchor Link

PluginErrorCodeCopy Anchor Link

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