# burgee/plugin

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

Source: https://burgee.interlace.tools/docs/api/plugin

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

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

## Functions

### definePlugin

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.

```ts
function definePlugin(plugin: Plugin): Plugin;
```

| Parameter | Type |
| :-- | :-- |
| `plugin` | `Plugin` |

**Returns** `Plugin`

### validate

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.

```ts
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.

```ts
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.

```ts
const CONTRACT = 1;
```

## Interfaces

### Plugin

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

```ts
interface Plugin {
    name: string;
    contract?: number;
    commands?: CommandNode[];
    hooks?: Partial<Record<HookStage, Hook>>;
    enforce?: 'pre' | 'post';
}
```

## Types

### PluginErrorCode

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