Plugin API
Extend ContractSpec with generators, validators, adapters, formatters, and registry resolvers.
Core capabilities
- Generators for code, docs, and schemas.
- Validators for policy checks and compliance gates.
- Adapters for framework and runtime integration.
- Formatters and diff renderers for deterministic output.
- Registry resolvers for local and remote plugin discovery.
Plugin interface
Define capabilities and lifecycle hooks in a single plugin entrypoint.
plugin.ts
import type {
ContractSpecPlugin,
PluginContext,
GeneratorCapability,
} from "@contractspec/lib.plugins";
export const MarkdownGeneratorPlugin: ContractSpecPlugin = {
meta: {
id: "markdown-generator",
version: "1.0.0",
type: "generator",
provides: ["docs"],
},
register(context: PluginContext) {
const generator: GeneratorCapability = {
id: "markdown",
description: "Generate Markdown docs",
generate: async (specs) => {
// Implementation...
},
};
context.generators.register(generator);
},
};Lifecycle hooks
Use lifecycle hooks to configure, validate, and dispose resources.
lifecycle.ts
export const MarkdownGeneratorPlugin: ContractSpecPlugin = {
meta: {
id: "markdown-generator",
version: "1.0.0",
type: "generator",
provides: ["docs"],
},
register(context) {
// Register capabilities
},
configure(options, context) {
// Optional: apply workspace configuration
},
validate(specs, context) {
// Optional: add validation checks
},
generate(specs, context) {
// Required: emit outputs
},
dispose() {
// Optional: cleanup
},
};Register a plugin
Configure plugins in .contractsrc.json to load them in the CLI and runtime.
.contractsrc.json
{
"plugins": [
{
"id": "markdown-generator",
"package": "@contractspec/plugin.markdown",
"capabilities": ["generator"],
"options": {
"outputDir": "./docs/generated",
"format": "table"
}
}
]
}