@kb-labs/quality-contracts 0.6.0

package/LICENSE

@@ -0,0 +1,4 @@
+This project is licensed under the same terms as the KB Labs Plugin Template root project.
+
+See the root LICENSE file at the repository root for full details.
+

package/README.md

@@ -0,0 +1,90 @@
+# @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.
+

package/dist/contract.d.ts

@@ -0,0 +1,99 @@
+declare const pluginContractsManifest: {
+    readonly schema: "kb.plugin.contracts/1";
+    readonly pluginId: "@kb-labs/plugin-template";
+    readonly contractsVersion: "1.0.0";
+    readonly artifacts: {
+        readonly 'template.hello.greeting': {
+            readonly id: "template.hello.greeting";
+            readonly kind: "json";
+            readonly description: "Machine-readable greeting payload returned by the hello surfaces.";
+            readonly pathPattern: "artifacts/template/hello/greeting.json";
+            readonly mediaType: "application/json";
+            readonly schemaRef: "@kb-labs/plugin-template-contracts/schema#HelloGreeting";
+            readonly example: {
+                readonly summary: "Greeting payload for anonymous user";
+                readonly payload: {
+                    readonly message: "Hello, World!";
+                    readonly target: "World";
+                };
+            };
+        };
+        readonly 'template.hello.log': {
+            readonly id: "template.hello.log";
+            readonly kind: "log";
+            readonly description: "Execution log for hello command/workflow.";
+            readonly pathPattern: "logs/template/hello/run.log";
+            readonly mediaType: "text/plain";
+        };
+    };
+    readonly commands: {
+        readonly 'plugin-template:hello': {
+            readonly id: "plugin-template:hello";
+            readonly description: "Produce a greeting message optionally targeting a provided name.";
+            readonly input: {
+                readonly ref: "@kb-labs/plugin-template-contracts/schema#HelloCommandInput";
+                readonly format: "zod";
+            };
+            readonly output: {
+                readonly ref: "@kb-labs/plugin-template-contracts/schema#HelloCommandOutput";
+                readonly format: "zod";
+            };
+            readonly produces: ["template.hello.greeting", "template.hello.log"];
+            readonly examples: ["kb plugin-template hello", "kb plugin-template hello --name Dev", "kb plugin-template hello --json"];
+        };
+        readonly 'plugin-template:test-loader': {
+            readonly id: "plugin-template:test-loader";
+            readonly description: "Test UI loader/spinner functionality with various scenarios.";
+            readonly input: {
+                readonly ref: "@kb-labs/plugin-template-contracts/schema#TestLoaderCommandInput";
+                readonly format: "zod";
+            };
+            readonly output: {
+                readonly ref: "@kb-labs/plugin-template-contracts/schema#TestLoaderCommandOutput";
+                readonly format: "zod";
+            };
+            readonly produces: [];
+            readonly examples: ["kb plugin-template test-loader", "kb plugin-template test-loader --duration 1000", "kb plugin-template test-loader --fail"];
+        };
+    };
+    readonly workflows: {
+        readonly 'template.workflow.hello': {
+            readonly id: "template.workflow.hello";
+            readonly description: "Single-step workflow executing the hello command and emitting greeting artifacts.";
+            readonly produces: ["template.hello.greeting", "template.hello.log"];
+            readonly steps: [{
+                readonly id: "template.workflow.hello.step.run-command";
+                readonly commandId: "plugin-template:hello";
+                readonly produces: ["template.hello.greeting", "template.hello.log"];
+            }];
+        };
+    };
+    readonly api: {
+        readonly rest: {
+            readonly basePath: "/v1/plugins/template";
+            readonly routes: {
+                readonly 'template.rest.hello': {
+                    readonly id: "template.rest.hello";
+                    readonly method: "GET";
+                    readonly path: "/hello";
+                    readonly description: "Return a greeting payload from the REST surface.";
+                    readonly response: {
+                        readonly ref: "@kb-labs/plugin-template-contracts/schema#HelloCommandOutput";
+                        readonly format: "zod";
+                    };
+                    readonly produces: ["template.hello.greeting"];
+                };
+            };
+        };
+    };
+};
+type PluginArtifactIds = keyof typeof pluginContractsManifest.artifacts;
+type PluginCommandIds = keyof typeof pluginContractsManifest.commands;
+type PluginWorkflowIds = keyof typeof pluginContractsManifest.workflows;
+type PluginRouteIds = typeof pluginContractsManifest.api extends {
+    rest: {
+        routes: infer R;
+    };
+} ? R extends Record<string, any> ? keyof R : never : never;
+
+export { type PluginArtifactIds, type PluginCommandIds, type PluginRouteIds, type PluginWorkflowIds, pluginContractsManifest };

package/dist/contract.js

@@ -0,0 +1,100 @@
+// src/version.ts
+var contractsSchemaId = "kb.plugin.contracts/1";
+var contractsVersion = "1.0.0";
+
+// src/contract.ts
+var pluginContractsManifest = {
+  schema: contractsSchemaId,
+  pluginId: "@kb-labs/plugin-template",
+  contractsVersion,
+  artifacts: {
+    "template.hello.greeting": {
+      id: "template.hello.greeting",
+      kind: "json",
+      description: "Machine-readable greeting payload returned by the hello surfaces.",
+      pathPattern: "artifacts/template/hello/greeting.json",
+      mediaType: "application/json",
+      schemaRef: "@kb-labs/plugin-template-contracts/schema#HelloGreeting",
+      example: {
+        summary: "Greeting payload for anonymous user",
+        payload: {
+          message: "Hello, World!",
+          target: "World"
+        }
+      }
+    },
+    "template.hello.log": {
+      id: "template.hello.log",
+      kind: "log",
+      description: "Execution log for hello command/workflow.",
+      pathPattern: "logs/template/hello/run.log",
+      mediaType: "text/plain"
+    }
+  },
+  commands: {
+    "plugin-template:hello": {
+      id: "plugin-template:hello",
+      description: "Produce a greeting message optionally targeting a provided name.",
+      input: {
+        ref: "@kb-labs/plugin-template-contracts/schema#HelloCommandInput",
+        format: "zod"
+      },
+      output: {
+        ref: "@kb-labs/plugin-template-contracts/schema#HelloCommandOutput",
+        format: "zod"
+      },
+      produces: ["template.hello.greeting", "template.hello.log"],
+      examples: ["kb plugin-template hello", "kb plugin-template hello --name Dev", "kb plugin-template hello --json"]
+    },
+    "plugin-template:test-loader": {
+      id: "plugin-template:test-loader",
+      description: "Test UI loader/spinner functionality with various scenarios.",
+      input: {
+        ref: "@kb-labs/plugin-template-contracts/schema#TestLoaderCommandInput",
+        format: "zod"
+      },
+      output: {
+        ref: "@kb-labs/plugin-template-contracts/schema#TestLoaderCommandOutput",
+        format: "zod"
+      },
+      produces: [],
+      examples: ["kb plugin-template test-loader", "kb plugin-template test-loader --duration 1000", "kb plugin-template test-loader --fail"]
+    }
+  },
+  workflows: {
+    "template.workflow.hello": {
+      id: "template.workflow.hello",
+      description: "Single-step workflow executing the hello command and emitting greeting artifacts.",
+      produces: ["template.hello.greeting", "template.hello.log"],
+      steps: [
+        {
+          id: "template.workflow.hello.step.run-command",
+          commandId: "plugin-template:hello",
+          produces: ["template.hello.greeting", "template.hello.log"]
+        }
+      ]
+    }
+  },
+  api: {
+    rest: {
+      basePath: "/v1/plugins/template",
+      routes: {
+        "template.rest.hello": {
+          id: "template.rest.hello",
+          method: "GET",
+          path: "/hello",
+          description: "Return a greeting payload from the REST surface.",
+          response: {
+            ref: "@kb-labs/plugin-template-contracts/schema#HelloCommandOutput",
+            format: "zod"
+          },
+          produces: ["template.hello.greeting"]
+        }
+      }
+    }
+  }
+};
+
+export { pluginContractsManifest };
+//# sourceMappingURL=contract.js.map
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/version.ts","../src/contract.ts"],"names":[],"mappings":";AAAO,IAAM,iBAAA,GAAoB,uBAAA;AAI1B,IAAM,gBAAA,GAAmB,OAAA;;;ACAzB,IAAM,uBAAA,GAA0B;AAAA,EACrC,MAAA,EAAQ,iBAAA;AAAA,EACR,QAAA,EAAU,0BAAA;AAAA,EACV,gBAAA;AAAA,EACA,SAAA,EAAW;AAAA,IACT,yBAAA,EAA2B;AAAA,MACzB,EAAA,EAAI,yBAAA;AAAA,MACJ,IAAA,EAAM,MAAA;AAAA,MACN,WAAA,EAAa,mEAAA;AAAA,MACb,WAAA,EAAa,wCAAA;AAAA,MACb,SAAA,EAAW,kBAAA;AAAA,MACX,SAAA,EAAW,yDAAA;AAAA,MACX,OAAA,EAAS;AAAA,QACP,OAAA,EAAS,qCAAA;AAAA,QACT,OAAA,EAAS;AAAA,UACP,OAAA,EAAS,eAAA;AAAA,UACT,MAAA,EAAQ;AAAA;AACV;AACF,KACF;AAAA,IACA,oBAAA,EAAsB;AAAA,MACpB,EAAA,EAAI,oBAAA;AAAA,MACJ,IAAA,EAAM,KAAA;AAAA,MACN,WAAA,EAAa,2CAAA;AAAA,MACb,WAAA,EAAa,6BAAA;AAAA,MACb,SAAA,EAAW;AAAA;AACb,GACF;AAAA,EACA,QAAA,EAAU;AAAA,IACR,uBAAA,EAAyB;AAAA,MACvB,EAAA,EAAI,uBAAA;AAAA,MACJ,WAAA,EAAa,kEAAA;AAAA,MACb,KAAA,EAAO;AAAA,QACL,GAAA,EAAK,6DAAA;AAAA,QACL,MAAA,EAAQ;AAAA,OACV;AAAA,MACA,MAAA,EAAQ;AAAA,QACN,GAAA,EAAK,8DAAA;AAAA,QACL,MAAA,EAAQ;AAAA,OACV;AAAA,MACA,QAAA,EAAU,CAAC,yBAAA,EAA2B,oBAAoB,CAAA;AAAA,MAC1D,QAAA,EAAU,CAAC,0BAAA,EAA4B,qCAAA,EAAuC,iCAAiC;AAAA,KACjH;AAAA,IACA,6BAAA,EAA+B;AAAA,MAC7B,EAAA,EAAI,6BAAA;AAAA,MACJ,WAAA,EAAa,8DAAA;AAAA,MACb,KAAA,EAAO;AAAA,QACL,GAAA,EAAK,kEAAA;AAAA,QACL,MAAA,EAAQ;AAAA,OACV;AAAA,MACA,MAAA,EAAQ;AAAA,QACN,GAAA,EAAK,mEAAA;AAAA,QACL,MAAA,EAAQ;AAAA,OACV;AAAA,MACA,UAAU,EAAC;AAAA,MACX,QAAA,EAAU,CAAC,gCAAA,EAAkC,gDAAA,EAAkD,uCAAuC;AAAA;AACxI,GACF;AAAA,EACA,SAAA,EAAW;AAAA,IACT,yBAAA,EAA2B;AAAA,MACzB,EAAA,EAAI,yBAAA;AAAA,MACJ,WAAA,EAAa,mFAAA;AAAA,MACb,QAAA,EAAU,CAAC,yBAAA,EAA2B,oBAAoB,CAAA;AAAA,MAC1D,KAAA,EAAO;AAAA,QACL;AAAA,UACE,EAAA,EAAI,0CAAA;AAAA,UACJ,SAAA,EAAW,uBAAA;AAAA,UACX,QAAA,EAAU,CAAC,yBAAA,EAA2B,oBAAoB;AAAA;AAC5D;AACF;AACF,GACF;AAAA,EACA,GAAA,EAAK;AAAA,IACH,IAAA,EAAM;AAAA,MACJ,QAAA,EAAU,sBAAA;AAAA,MACV,MAAA,EAAQ;AAAA,QACN,qBAAA,EAAuB;AAAA,UACrB,EAAA,EAAI,qBAAA;AAAA,UACJ,MAAA,EAAQ,KAAA;AAAA,UACR,IAAA,EAAM,QAAA;AAAA,UACN,WAAA,EAAa,kDAAA;AAAA,UACb,QAAA,EAAU;AAAA,YACR,GAAA,EAAK,8DAAA;AAAA,YACL,MAAA,EAAQ;AAAA,WACV;AAAA,UACA,QAAA,EAAU,CAAC,yBAAyB;AAAA;AACtC;AACF;AACF;AAEJ","file":"contract.js","sourcesContent":["export const contractsSchemaId = 'kb.plugin.contracts/1' as const;\n\nexport type ContractsSchemaId = typeof contractsSchemaId;\n\nexport const contractsVersion = '1.0.0' as const;\n\n","import type { PluginContracts } from './types';\nimport { contractsSchemaId, contractsVersion } from './version';\n\n// Level 2: Contracts типизация с as const для извлечения типов\nexport const pluginContractsManifest = {\n  schema: contractsSchemaId,\n  pluginId: '@kb-labs/plugin-template',\n  contractsVersion,\n  artifacts: {\n    'template.hello.greeting': {\n      id: 'template.hello.greeting',\n      kind: 'json',\n      description: 'Machine-readable greeting payload returned by the hello surfaces.',\n      pathPattern: 'artifacts/template/hello/greeting.json',\n      mediaType: 'application/json',\n      schemaRef: '@kb-labs/plugin-template-contracts/schema#HelloGreeting',\n      example: {\n        summary: 'Greeting payload for anonymous user',\n        payload: {\n          message: 'Hello, World!',\n          target: 'World'\n        }\n      }\n    },\n    'template.hello.log': {\n      id: 'template.hello.log',\n      kind: 'log',\n      description: 'Execution log for hello command/workflow.',\n      pathPattern: 'logs/template/hello/run.log',\n      mediaType: 'text/plain'\n    }\n  },\n  commands: {\n    'plugin-template:hello': {\n      id: 'plugin-template:hello',\n      description: 'Produce a greeting message optionally targeting a provided name.',\n      input: {\n        ref: '@kb-labs/plugin-template-contracts/schema#HelloCommandInput',\n        format: 'zod'\n      },\n      output: {\n        ref: '@kb-labs/plugin-template-contracts/schema#HelloCommandOutput',\n        format: 'zod'\n      },\n      produces: ['template.hello.greeting', 'template.hello.log'],\n      examples: ['kb plugin-template hello', 'kb plugin-template hello --name Dev', 'kb plugin-template hello --json']\n    },\n    'plugin-template:test-loader': {\n      id: 'plugin-template:test-loader',\n      description: 'Test UI loader/spinner functionality with various scenarios.',\n      input: {\n        ref: '@kb-labs/plugin-template-contracts/schema#TestLoaderCommandInput',\n        format: 'zod'\n      },\n      output: {\n        ref: '@kb-labs/plugin-template-contracts/schema#TestLoaderCommandOutput',\n        format: 'zod'\n      },\n      produces: [],\n      examples: ['kb plugin-template test-loader', 'kb plugin-template test-loader --duration 1000', 'kb plugin-template test-loader --fail']\n    }\n  },\n  workflows: {\n    'template.workflow.hello': {\n      id: 'template.workflow.hello',\n      description: 'Single-step workflow executing the hello command and emitting greeting artifacts.',\n      produces: ['template.hello.greeting', 'template.hello.log'],\n      steps: [\n        {\n          id: 'template.workflow.hello.step.run-command',\n          commandId: 'plugin-template:hello',\n          produces: ['template.hello.greeting', 'template.hello.log']\n        }\n      ]\n    }\n  },\n  api: {\n    rest: {\n      basePath: '/v1/plugins/template',\n      routes: {\n        'template.rest.hello': {\n          id: 'template.rest.hello',\n          method: 'GET',\n          path: '/hello',\n          description: 'Return a greeting payload from the REST surface.',\n          response: {\n            ref: '@kb-labs/plugin-template-contracts/schema#HelloCommandOutput',\n            format: 'zod'\n          },\n          produces: ['template.hello.greeting']\n        }\n      }\n    }\n  }\n} as const satisfies PluginContracts;\n\n// Извлекаем типы для использования в других местах\nexport type PluginArtifactIds = keyof typeof pluginContractsManifest.artifacts;\nexport type PluginCommandIds = keyof typeof pluginContractsManifest.commands;\nexport type PluginWorkflowIds = keyof typeof pluginContractsManifest.workflows;\nexport type PluginRouteIds = typeof pluginContractsManifest.api extends { rest: { routes: infer R } }\n  ? R extends Record<string, any>\n    ? keyof R\n    : never\n  : never;\n\n"]}