npm package: @kb-labs/impact-contracts
Description: Contracts for KB Labs Impact Analysis Plugin — types, interfaces, schemas.
Latest version: 0.5.0

# @kb-labs/plugin-template-contracts

Lightweight public contracts package for the plugin: it describes guaranteed artifacts, commands, workflows, API payloads, and the version of these promises.

## Why this package exists

Every KB Labs plugin is expected to publish a clear, lightweight “promise” to the rest of the ecosystem. This package is that promise: it contains only types, manifests, and validation helpers, so other teams (CLI, Workflow Engine, Studio, REST, marketplace tooling) can rely on a single source of truth without dragging in plugin runtime code.

## Quick start checklist

1. Clone this package as part of your plugin workspace (`packages/contracts`).
2. Update `pluginContractsManifest` with your plugin ID and initial artifacts/commands.
3. Adjust Zod schemas in `src/schema.ts` (or add new ones) to match your payloads.
4. Bump `contractsVersion` whenever the public promise changes (SemVer rules below).
5. Run `pnpm test` and `pnpm type-check` to ensure the manifest validates.
6. Import the manifest in your CLI/REST/workflow code to avoid hard-coded IDs.

### Renaming this package

When you turn the template into your own plugin:
- Change the npm name in `package.json` (e.g. `@kb-labs/my-plugin-contracts`).
- Update `pluginContractsManifest.pluginId` in `src/contract.ts`.
- Adjust aliases in `tsconfig.paths.json` and imports across the workspace (`@kb-labs/plugin-template-contracts` → your new name).
- Replace sample artifact IDs (`template.hello.*`) with your own naming scheme.

## What's inside

- `pluginContractsManifest` — the single source of truth for the plugin's public capabilities
- TypeScript types (`src/types`) and Zod schemas (`src/schema`) for artifacts, commands, workflows, and API payloads
- `parsePluginContracts` utility for runtime validation of the manifest and third-party contracts

## Versioning rules

- `contractsVersion` follows SemVer and is **independent** from the plugin's npm version.
- **MAJOR** — breaking changes (removing/renaming artifacts, changing payload formats).
- **MINOR** — backwards-compatible extensions (new artifacts, commands, fields).
- **PATCH** — documentation/metadata updates without altering payload formats.

## Minimal manifest example

```ts
import type { PluginContracts } from '@kb-labs/plugin-template-contracts';

export const pluginContractsManifest: PluginContracts = {
  schema: 'kb.plugin.contracts/1',
  pluginId: '@kb-labs/my-plugin',
  contractsVersion: '1.0.0',
  artifacts: {
    'my-plugin.result': {
      id: 'my-plugin.result',
      kind: 'json',
      description: 'Primary output of the CLI command.'
    }
  }
  // commands/workflows/api can be added later when needed
};
```

## Optional sections

All additional sections are **optional** — include only what your plugin actually supports:

- `commands` — define CLI or workflow commands that produce/consume artifacts.
- `workflows` — describe composed workflows and their steps.
- `api` — document REST (or future surfaces) when the plugin exposes them.

If your plugin only ships a CLI command, keep `commands` + `artifacts` and omit `workflows`/`api`. The Zod schema accepts missing sections.

## Usage in plugin code

```ts
import { pluginContractsManifest } from '@kb-labs/plugin-template-contracts';

const helloArtifactId = pluginContractsManifest.artifacts['template.hello.greeting'].id;
```

Use the manifest to avoid magic strings, assert that required artifacts exist, or log which promises were fulfilled.

## Who relies on the contract

- **Workflow Engine** — verifies allowed steps, required artifacts, and matches produced results with the contract.
- **Studio** — builds UI and hints based on declared artifacts and commands.
- **CLI / REST / other plugins** — reuse types and schemas as the source of truth, validate inputs/outputs.
- **Marketplace & QA tooling** — checks plugin compatibility and correctness before publishing.

## Looking ahead

- Generate JSON Schema / OpenAPI from the `api` contract surface.
- Add automatic inspectors in Studio and validators for the marketplace.