@kb-labs/mind-contracts 1.5.0

package/README.md

@@ -0,0 +1,174 @@
+# @kb-labs/mind-contracts
+
+Public contracts for the KB Labs Mind plugin. Declares artifacts, commands, workflows, and API guarantees for consumers.
+
+## Vision & Purpose
+
+**@kb-labs/mind-contracts** provides public contracts for KB Labs Mind. It describes the guarantees that other products (CLI, Studio, REST gateway, Workflow Engine) can rely on without depending on Mind runtime code.
+
+### Core Goals
+
+- **Contract Definition**: Define public contracts for Mind
+- **Schema Validation**: Zod schemas for validation
+- **Type Safety**: TypeScript types derived from schemas
+- **Versioning**: SemVer-based contract versioning
+
+## Package Status
+
+- **Version**: 0.1.0
+- **Stage**: Stable
+- **Status**: Production Ready ✅
+
+## Architecture
+
+### High-Level Overview
+
+```
+Mind Contracts
+    │
+    ├──► Contract Manifest
+    ├──► Zod Schemas
+    ├──► TypeScript Types
+    └──► Helper Parsers
+```
+
+### Key Components
+
+1. **Contract Manifest** (`contract.ts`): Plugin contracts manifest
+2. **Schemas** (`schema/`): Zod validation schemas
+3. **Types** (`types.ts`): TypeScript type definitions
+4. **Parsers** (`schema.ts`): Helper parsers
+
+## ✨ Features
+
+- **Contract Manifest**: Typed declaration of Mind artifacts, commands, workflows, and REST routes
+- **Zod Schemas**: Validation schemas for CLI flag definitions, query DTOs, REST responses, Studio widgets
+- **TypeScript Types**: Type definitions for command inputs/outputs
+- **Helper Parsers**: `parsePluginContracts` for runtime validation
+
+## 📦 API Reference
+
+### Main Exports
+
+#### Contract Manifest
+
+- `pluginContractsManifest`: Typed declaration of Mind artifacts, commands, workflows, and REST routes
+- `contractsVersion`: SemVer version for contract coordination
+- `contractsSchemaId`: Schema ID for contract validation
+
+#### Schemas
+
+- `parsePluginContracts`: Parse plugin contracts
+- `pluginContractsSchema`: Plugin contracts schema
+
+#### Types
+
+- `PluginContracts`: Plugin contracts type
+- `ArtifactDecl`: Artifact declaration type
+- `CommandDecl`: Command declaration type
+
+## 🔧 Configuration
+
+### Configuration Options
+
+No configuration needed - pure contract definitions.
+
+## 🔗 Dependencies
+
+### Runtime Dependencies
+
+- `zod` (`^3.23.8`): Schema validation
+
+### Development Dependencies
+
+- `@kb-labs/devkit` (`link:../../../kb-labs-devkit`): DevKit presets
+- `@types/node` (`^24.7.0`): Node.js types
+- `semver` (`^7.6.3`): SemVer parsing
+- `tsup` (`^8.5.0`): TypeScript bundler
+- `typescript` (`^5.6.3`): TypeScript compiler
+- `vitest` (`^3.2.4`): Test runner
+
+## 🧪 Testing
+
+### Test Structure
+
+```
+tests/
+└── contracts.manifest.test.ts
+```
+
+### Test Coverage
+
+- **Current Coverage**: ~70%
+- **Target Coverage**: 90%
+
+## 📈 Performance
+
+### Performance Characteristics
+
+- **Time Complexity**: O(1) for type operations, O(n) for schema validation
+- **Space Complexity**: O(1)
+- **Bottlenecks**: Schema validation for large payloads
+
+## 🔒 Security
+
+### Security Considerations
+
+- **Schema Validation**: Input validation via Zod schemas
+- **Type Safety**: TypeScript type safety
+
+### Known Vulnerabilities
+
+- None
+
+## 🐛 Known Issues & Limitations
+
+### Known Issues
+
+- None currently
+
+### Limitations
+
+- **Schema Validation**: Basic validation only
+
+### Future Improvements
+
+- **Enhanced Validation**: More validation rules
+
+## 🔄 Migration & Breaking Changes
+
+### Versioning Rules
+
+- **MAJOR** — breaking changes (removed fields, renamed IDs, incompatible schema updates)
+- **MINOR** — backwards-compatible additions (new flags, artifacts, optional fields)
+- **PATCH** — metadata/documentation tweaks that do not alter payload structure
+
+### Breaking Changes in Future Versions
+
+- None planned
+
+## 📚 Examples
+
+### Example 1: Use Contract Manifest
+
+```typescript
+import { pluginContractsManifest } from '@kb-labs/mind-contracts';
+
+const queryArtifactId = pluginContractsManifest.artifacts['mind.query.json'].id;
+```
+
+### Example 2: Parse Plugin Contracts
+
+```typescript
+import { parsePluginContracts } from '@kb-labs/mind-contracts';
+
+const contracts = parsePluginContracts(rawManifest);
+```
+
+## 🤝 Contributing
+
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) for development guidelines.
+
+## 📄 License
+
+MIT © KB Labs

package/dist/contract-D8Rjf1rz.d.ts

@@ -0,0 +1,96 @@
+type SchemaFormat = 'zod' | 'json-schema' | 'openapi';
+interface SchemaReference {
+    ref: string;
+    format?: SchemaFormat;
+    description?: string;
+}
+interface RestRouteContract {
+    id: string;
+    method: string;
+    path: string;
+    description?: string;
+    request?: SchemaReference;
+    response?: SchemaReference;
+    produces?: string[];
+    consumes?: string[];
+}
+interface RestApiContract {
+    basePath: string;
+    routes: Record<string, RestRouteContract>;
+}
+interface ApiContract {
+    rest?: RestApiContract;
+}
+
+type ArtifactKind = 'file' | 'json' | 'markdown' | 'binary' | 'dir' | 'log';
+interface ArtifactExample {
+    summary?: string;
+    payload?: unknown;
+}
+interface PluginArtifactContract {
+    id: string;
+    kind: ArtifactKind;
+    description?: string;
+    /**
+     * Relative path or glob pattern describing where the artifact is produced.
+     */
+    pathPattern?: string;
+    /**
+     * IANA media type describing the artifact (for example: application/json).
+     */
+    mediaType?: string;
+    /**
+     * Reference to a schema describing the artifact payload. Can be a URI or package export.
+     */
+    schemaRef?: string;
+    /**
+     * Optional example payload to support documentation and tooling.
+     */
+    example?: ArtifactExample;
+}
+type ArtifactContractsMap = Record<string, PluginArtifactContract>;
+
+interface CommandContract {
+    id: string;
+    description?: string;
+    input?: SchemaReference;
+    output?: SchemaReference;
+    produces?: string[];
+    consumes?: string[];
+    examples?: string[];
+}
+type CommandContractsMap = Record<string, CommandContract>;
+
+interface WorkflowStepContract {
+    id: string;
+    description?: string;
+    commandId?: string;
+    consumes?: string[];
+    produces?: string[];
+}
+interface WorkflowContract {
+    id: string;
+    description?: string;
+    consumes?: string[];
+    produces?: string[];
+    steps?: WorkflowStepContract[];
+}
+type WorkflowContractsMap = Record<string, WorkflowContract>;
+
+declare const contractsVersion = "1.0.0";
+declare const contractsSchemaId = "@kb-labs/mind-contracts/schema";
+type ContractsSchemaId = typeof contractsSchemaId;
+
+interface PluginContracts {
+    schema: ContractsSchemaId;
+    pluginId: string;
+    contractsVersion: string;
+    artifacts: ArtifactContractsMap;
+    commands?: CommandContractsMap;
+    workflows?: WorkflowContractsMap;
+    api?: ApiContract;
+}
+
+declare const pluginContractsManifest: PluginContracts;
+
+export { type ApiContract as A, type CommandContract as C, type PluginContracts as P, type RestApiContract as R, type SchemaReference as S, type WorkflowContract as W, contractsSchemaId as a, type RestRouteContract as b, contractsVersion as c, type ArtifactKind as d, type ArtifactContractsMap as e, type PluginArtifactContract as f, type ArtifactExample as g, type CommandContractsMap as h, type WorkflowContractsMap as i, type WorkflowStepContract as j, pluginContractsManifest as p };

package/dist/contract.d.ts

@@ -0,0 +1 @@
+export { p as pluginContractsManifest } from './contract-D8Rjf1rz.js';

package/dist/contract.js

@@ -0,0 +1,57 @@
+// src/version.ts
+var contractsVersion = "1.0.0";
+var contractsSchemaId = "@kb-labs/mind-contracts/schema";
+
+// src/contract.ts
+var pluginContractsManifest = {
+  schema: contractsSchemaId,
+  pluginId: "@kb-labs/mind",
+  contractsVersion,
+  artifacts: {},
+  commands: {
+    "mind:init": {
+      id: "mind:init",
+      description: "Initialise the Mind workspace structure.",
+      input: {
+        ref: "@kb-labs/mind-contracts/schema#MindInitCommandInputSchema",
+        format: "zod"
+      },
+      examples: ["kb mind init --force", "kb mind init --json"]
+    },
+    "mind:verify": {
+      id: "mind:verify",
+      description: "Validate Mind indexes and surface inconsistencies.",
+      input: {
+        ref: "@kb-labs/mind-contracts/schema#MindVerifyCommandInputSchema",
+        format: "zod"
+      },
+      output: {
+        ref: "@kb-labs/mind-contracts/schema#MindVerifyCommandOutputSchema",
+        format: "zod"
+      },
+      examples: ["kb mind verify", "kb mind verify --json"]
+    }
+  },
+  workflows: {},
+  api: {
+    rest: {
+      basePath: "/v1/plugins/mind",
+      routes: {
+        "mind.rest.verify": {
+          id: "mind.rest.verify",
+          method: "GET",
+          path: "/verify",
+          description: "Summarise index verification status for Studio dashboards.",
+          response: {
+            ref: "@kb-labs/mind-contracts/schema#MindVerifyResponseSchema",
+            format: "zod"
+          }
+        }
+      }
+    }
+  }
+};
+export {
+  pluginContractsManifest
+};
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/version.ts","../src/contract.ts"],"sourcesContent":["export const contractsVersion = '1.0.0';\nexport const contractsSchemaId = '@kb-labs/mind-contracts/schema';\n\nexport type ContractsSchemaId = typeof contractsSchemaId;\n","import type { PluginContracts } from './types';\nimport { contractsSchemaId, contractsVersion } from './version';\n\nexport const pluginContractsManifest: PluginContracts = {\n  schema: contractsSchemaId,\n  pluginId: '@kb-labs/mind',\n  contractsVersion,\n  artifacts: {},\n  commands: {\n    'mind:init': {\n      id: 'mind:init',\n      description: 'Initialise the Mind workspace structure.',\n      input: {\n        ref: '@kb-labs/mind-contracts/schema#MindInitCommandInputSchema',\n        format: 'zod',\n      },\n      examples: ['kb mind init --force', 'kb mind init --json'],\n    },\n    'mind:verify': {\n      id: 'mind:verify',\n      description: 'Validate Mind indexes and surface inconsistencies.',\n      input: {\n        ref: '@kb-labs/mind-contracts/schema#MindVerifyCommandInputSchema',\n        format: 'zod',\n      },\n      output: {\n        ref: '@kb-labs/mind-contracts/schema#MindVerifyCommandOutputSchema',\n        format: 'zod',\n      },\n      examples: ['kb mind verify', 'kb mind verify --json'],\n    },\n  },\n  workflows: {},\n  api: {\n    rest: {\n      basePath: '/v1/plugins/mind',\n      routes: {\n        'mind.rest.verify': {\n          id: 'mind.rest.verify',\n          method: 'GET',\n          path: '/verify',\n          description: 'Summarise index verification status for Studio dashboards.',\n          response: {\n            ref: '@kb-labs/mind-contracts/schema#MindVerifyResponseSchema',\n            format: 'zod',\n          },\n        },\n      },\n    },\n  },\n};\n"],"mappings":";AAAO,IAAM,mBAAmB;AACzB,IAAM,oBAAoB;;;ACE1B,IAAM,0BAA2C;AAAA,EACtD,QAAQ;AAAA,EACR,UAAU;AAAA,EACV;AAAA,EACA,WAAW,CAAC;AAAA,EACZ,UAAU;AAAA,IACR,aAAa;AAAA,MACX,IAAI;AAAA,MACJ,aAAa;AAAA,MACb,OAAO;AAAA,QACL,KAAK;AAAA,QACL,QAAQ;AAAA,MACV;AAAA,MACA,UAAU,CAAC,wBAAwB,qBAAqB;AAAA,IAC1D;AAAA,IACA,eAAe;AAAA,MACb,IAAI;AAAA,MACJ,aAAa;AAAA,MACb,OAAO;AAAA,QACL,KAAK;AAAA,QACL,QAAQ;AAAA,MACV;AAAA,MACA,QAAQ;AAAA,QACN,KAAK;AAAA,QACL,QAAQ;AAAA,MACV;AAAA,MACA,UAAU,CAAC,kBAAkB,uBAAuB;AAAA,IACtD;AAAA,EACF;AAAA,EACA,WAAW,CAAC;AAAA,EACZ,KAAK;AAAA,IACH,MAAM;AAAA,MACJ,UAAU;AAAA,MACV,QAAQ;AAAA,QACN,oBAAoB;AAAA,UAClB,IAAI;AAAA,UACJ,QAAQ;AAAA,UACR,MAAM;AAAA,UACN,aAAa;AAAA,UACb,UAAU;AAAA,YACR,KAAK;AAAA,YACL,QAAQ;AAAA,UACV;AAAA,QACF;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACF;","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,95 @@
+export { A as ApiContract, e as ArtifactContractsMap, g as ArtifactExample, d as ArtifactKind, C as CommandContract, h as CommandContractsMap, f as PluginArtifactContract, P as PluginContracts, R as RestApiContract, b as RestRouteContract, S as SchemaReference, W as WorkflowContract, i as WorkflowContractsMap, j as WorkflowStepContract, a as contractsSchemaId, c as contractsVersion, p as pluginContractsManifest } from './contract-D8Rjf1rz.js';
+export { MindFeedCommandInputSchema, MindFeedCommandOutputSchema, MindInitCommandInputSchema, MindPackCommandInputSchema, MindPackCommandOutputSchema, MindQueryCommandInputSchema, MindQueryCommandOutputSchema, MindQueryRequestSchema, MindQueryResponseSchema, MindUpdateCommandInputSchema, MindUpdateCommandOutputSchema, MindVerifyCommandInputSchema, MindVerifyCommandOutputSchema, MindVerifyResponseSchema, PluginContractsSchema, apiContractSchema, artifactContractSchema, artifactExampleSchema, artifactsContractMapSchema, commandContractMapSchema, commandContractSchema, parsePluginContracts, pluginContractsSchema, restApiContractSchema, restRouteContractSchema, schemaReferenceSchema, workflowContractMapSchema, workflowContractSchema, workflowStepSchema } from './schema.js';
+import 'zod';
+
+/**
+ * Registry configuration for Mind sync
+ */
+interface MindSyncRegistryConfig {
+    type: 'filesystem';
+    path: string;
+}
+/**
+ * Soft delete configuration for Mind sync
+ */
+interface MindSyncSoftDeleteConfig {
+    enabled: boolean;
+    ttlDays: number;
+}
+/**
+ * Partial updates configuration for Mind sync
+ */
+interface MindSyncPartialUpdatesConfig {
+    enabled: boolean;
+}
+/**
+ * Batch processing configuration for Mind sync
+ */
+interface MindSyncBatchConfig {
+    maxSize: number;
+}
+/**
+ * Mind synchronization configuration
+ */
+interface MindSyncConfig {
+    registry: MindSyncRegistryConfig;
+    softDelete: MindSyncSoftDeleteConfig;
+    partialUpdates: MindSyncPartialUpdatesConfig;
+    batch: MindSyncBatchConfig;
+}
+/**
+ * Mind source configuration
+ */
+interface MindSourceConfig {
+    id: string;
+    paths: string[];
+    exclude?: string[];
+}
+/**
+ * Mind engine configuration
+ */
+interface MindEngineConfig {
+    id: string;
+    type: string;
+    options?: Record<string, unknown>;
+}
+/**
+ * Mind scope configuration
+ */
+interface MindScopeConfig {
+    id: string;
+    sourceIds?: string[];
+    defaultEngine?: string;
+    include?: string[];
+    exclude?: string[];
+}
+/**
+ * Mind defaults configuration
+ */
+interface MindDefaultsConfig {
+    fallbackEngineId?: string;
+}
+/**
+ * Canonical Mind configuration input
+ */
+interface MindConfigInput {
+    sources: MindSourceConfig[];
+    scopes: MindScopeConfig[];
+    engines: MindEngineConfig[];
+    defaults?: MindDefaultsConfig;
+}
+/**
+ * Mind configuration with sync section
+ */
+interface MindConfig extends MindConfigInput {
+    /**
+     * Synchronization settings for Mind
+     */
+    sync?: MindSyncConfig;
+}
+/**
+ * Default sync configuration
+ */
+declare const defaultMindSyncConfig: MindSyncConfig;
+
+export { type MindConfig, type MindConfigInput, type MindDefaultsConfig, type MindEngineConfig, type MindScopeConfig, type MindSourceConfig, type MindSyncBatchConfig, type MindSyncConfig, type MindSyncPartialUpdatesConfig, type MindSyncRegistryConfig, type MindSyncSoftDeleteConfig, defaultMindSyncConfig };