caique/plugin

import { validate, register, reset, … } from 'caique/plugin';

FunctionsCopy Anchor Link

kindsCopy Anchor Link

Every kind that can be drawn right now: the six, plus whatever is registered.

function kinds(): string[];

Returns string[]

projectionOfCopy Anchor Link

The static projection for any kind — the one surface a caller needs.

The six are still drawn by caique; anything else is a registered widget's static. A kind that is neither is a refusal naming what is registered, so the reader can see the typo rather than a text prompt where their rating widget should have been.

function projectionOf(spec: PromptSpec): string;

Returns string

registerCopy Anchor Link

Register a plugin. Later wins, like ESLint flat config: the array is ordered, a caller reads it top to bottom, and the last word on a kind is the one nearest the program.

function register(plugin: unknown): void;

Returns void

registeredCopy Anchor Link

The plugins registered, in registration order.

function registered(): readonly Plugin[];

Returns readonly Plugin[]

resetCopy Anchor Link

Forget every registered plugin. For tests, and for a program that re-registers at runtime.

function reset(): void;

Returns void

validateCopy Anchor Link

Refuse a plugin that cannot contribute a widget, at the door.

Every refusal here is about the widgets key or the plugin's own identity. A key another layer owns is not inspected and not rejected (R1) — caique has no opinion about a spinner.

function validate(plugin: unknown): asserts plugin is Plugin;

Returns asserts plugin is Plugin

widgetForCopy Anchor Link

The widget that draws kind, or nothing when no plugin registered one.

function widgetFor(kind: string): Widget | undefined;

Returns Widget \| undefined

widgetsCopy Anchor Link

Every kind a plugin contributed, with who won it and who it shadowed.

function widgets(): Contribution[];

Returns Contribution[]

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 and roundel declare, written out rather than imported for the reason in the file comment.

const CONTRACT = 1;

InterfacesCopy Anchor Link

ContributionCopy Anchor Link

Which plugin last contributed each kind — the shadowing a plugin check prints.

interface Contribution {
    kind: string;
    from: string;
    /** Plugins that contributed this kind earlier and were overridden, in order. */
    shadowed: string[];
}

PluginCopy Anchor Link

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

interface Plugin {
    name: string;
    contract?: number;
    widgets?: Record<string, Widget>;
}

WidgetCopy Anchor Link

How a plugin draws one kind of prompt.

static(spec) is what a pipe, an agent and a screen reader get; it is what projection() already returns for the six built-ins, so a plugin widget slots into the same surface rather than beside it. frame is optional and drives caique/raw.

interface Widget {
    static: (spec: PromptSpec) => string;
    frame?: (t: number, spec: PromptSpec) => string;
    sample?: WidgetSample;
}

WidgetSampleCopy Anchor Link

Two named states of plain data, which a grader renders a widget with (R7).

It carries no behaviour, so reading it does not mean running the author's code — that is why an optional sample does not turn a plugin into a program.

interface WidgetSample {
    running: unknown;
    done: unknown;
}

TypesCopy Anchor Link

PluginErrorCodeCopy Anchor Link

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