@kb-labs/infra-worker-contracts 0.5.0

package/dist/index.d.ts

@@ -0,0 +1,839 @@
+import { PluginArtifactIds, PluginCommandIds, PluginRouteIds } from './contract.js';
+export { PluginWorkflowIds, pluginContractsManifest } from './contract.js';
+import { z } from 'zod';
+export { CaptureSnapshotInput, CaptureSnapshotInputSchema, CaptureSnapshotOutput, CaptureSnapshotOutputSchema, PrepareInfraInput, PrepareInfraInputSchema, PrepareInfraOutput, PrepareInfraOutputSchema, RestoreSnapshotInput, RestoreSnapshotInputSchema, RestoreSnapshotOutput, RestoreSnapshotOutputSchema } from './schema.js';
+
+/**
+ * Type-safe helper functions for contracts
+ * @module @kb-labs/plugin-template-contracts/helpers
+ */
+
+/**
+ * Get artifact path pattern by ID (type-safe)
+ *
+ * @example
+ * const path = getArtifactPath('template.hello.greeting');
+ * // ✅ Автодополнение работает!
+ * // ✅ Проверка на этапе компиляции!
+ */
+declare function getArtifactPath<T extends PluginArtifactIds>(id: T): string;
+/**
+ * Get artifact metadata by ID (type-safe)
+ *
+ * @example
+ * const artifact = getArtifact('template.hello.greeting');
+ * // artifact.kind, artifact.description, и т.д.
+ */
+declare function getArtifact<T extends PluginArtifactIds>(id: T): {
+    readonly 'infra.prepare.result': {
+        readonly id: "infra.prepare.result";
+        readonly kind: "json";
+        readonly description: "Result payload for infra preparation command.";
+        readonly pathPattern: "artifacts/infra/prepare/result.json";
+        readonly mediaType: "application/json";
+        readonly schemaRef: "@kb-labs/infra-worker-contracts/schema#PrepareInfraOutput";
+        readonly example: {
+            readonly summary: "Infra prepare output";
+            readonly payload: {
+                readonly workspaceId: "ws_123";
+                readonly environmentId: "env_456";
+                readonly snapshotId: "snap_789";
+            };
+        };
+    };
+}[T];
+/**
+ * Check if artifact ID exists in contracts (type-safe)
+ *
+ * @example
+ * if (hasArtifact('template.hello.greeting')) {
+ *   // ✅ Типизировано!
+ * }
+ */
+declare function hasArtifact(id: string): id is PluginArtifactIds;
+/**
+ * Get command metadata by ID (type-safe)
+ *
+ * @example
+ * const command = getCommand('template:hello');
+ * // command.description, command.input, command.output, и т.д.
+ */
+declare function getCommand<T extends PluginCommandIds>(id: T): {
+    readonly 'infra-worker:prepare': {
+        readonly id: "infra-worker:prepare";
+        readonly description: "Materialize workspace and optionally provision environment/snapshot.";
+        readonly input: {
+            readonly ref: "@kb-labs/infra-worker-contracts/schema#PrepareInfraInput";
+            readonly format: "zod";
+        };
+        readonly output: {
+            readonly ref: "@kb-labs/infra-worker-contracts/schema#PrepareInfraOutput";
+            readonly format: "zod";
+        };
+        readonly produces: ["infra.prepare.result"];
+        readonly examples: ["kb infra-worker prepare --sourceRef repo://main --basePath /workspace/main"];
+    };
+    readonly 'infra-worker:capture-snapshot': {
+        readonly id: "infra-worker:capture-snapshot";
+        readonly description: "Capture snapshot for workspace/environment.";
+        readonly input: {
+            readonly ref: "@kb-labs/infra-worker-contracts/schema#CaptureSnapshotInput";
+            readonly format: "zod";
+        };
+        readonly output: {
+            readonly ref: "@kb-labs/infra-worker-contracts/schema#CaptureSnapshotOutput";
+            readonly format: "zod";
+        };
+        readonly produces: [];
+        readonly examples: ["kb infra-worker capture-snapshot --workspaceId ws_123 --namespace runs/main"];
+    };
+    readonly 'infra-worker:restore-snapshot': {
+        readonly id: "infra-worker:restore-snapshot";
+        readonly description: "Restore snapshot to workspace/environment.";
+        readonly input: {
+            readonly ref: "@kb-labs/infra-worker-contracts/schema#RestoreSnapshotInput";
+            readonly format: "zod";
+        };
+        readonly output: {
+            readonly ref: "@kb-labs/infra-worker-contracts/schema#RestoreSnapshotOutput";
+            readonly format: "zod";
+        };
+        readonly produces: [];
+        readonly examples: ["kb infra-worker restore-snapshot --snapshotId snap_789 --workspaceId ws_123"];
+    };
+}[T];
+/**
+ * Check if command ID exists in contracts (type-safe)
+ *
+ * @example
+ * if (hasCommand('template:hello')) {
+ *   // ✅ Типизировано!
+ * }
+ */
+declare function hasCommand(id: string): id is PluginCommandIds;
+/**
+ * Type-safe identity function for command IDs (useful for validation)
+ *
+ * @example
+ * const cmdId = getCommandId('template:hello'); // ✅ Проверка на этапе компиляции!
+ */
+declare function getCommandId<T extends PluginCommandIds>(id: T): T;
+/**
+ * Type-safe identity function for artifact IDs (useful for validation)
+ *
+ * @example
+ * const artifactId = getArtifactId('template.hello.greeting'); // ✅ Проверка!
+ */
+declare function getArtifactId<T extends PluginArtifactIds>(id: T): T;
+/**
+ * Get route metadata by ID (type-safe)
+ *
+ * @example
+ * const route = getRoute('template.rest.hello');
+ * // route.method, route.path, route.response, и т.д.
+ */
+declare function getRoute<T extends PluginRouteIds>(id: T): never;
+/**
+ * Check if route ID exists in contracts (type-safe)
+ *
+ * @example
+ * if (hasRoute('template.rest.hello')) {
+ *   // ✅ Типизировано!
+ * }
+ */
+declare function hasRoute(id: string): id is PluginRouteIds;
+/**
+ * Type-safe identity function for route IDs (useful for validation)
+ *
+ * @example
+ * const routeId = getRouteId('template.rest.hello'); // ✅ Проверка!
+ */
+declare function getRouteId<T extends PluginRouteIds>(id: T): T;
+
+declare const pluginContractsSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"kb.plugin.contracts/1">;
+    pluginId: z.ZodString;
+    contractsVersion: z.ZodString;
+    artifacts: z.ZodRecord<z.ZodString, z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<["file", "json", "markdown", "binary", "dir", "log"]>;
+        description: z.ZodOptional<z.ZodString>;
+        pathPattern: z.ZodOptional<z.ZodString>;
+        mediaType: z.ZodOptional<z.ZodString>;
+        schemaRef: z.ZodOptional<z.ZodString>;
+        example: z.ZodOptional<z.ZodObject<{
+            summary: z.ZodOptional<z.ZodString>;
+            payload: z.ZodOptional<z.ZodUnknown>;
+        }, "strip", z.ZodTypeAny, {
+            summary?: string | undefined;
+            payload?: unknown;
+        }, {
+            summary?: string | undefined;
+            payload?: unknown;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        kind: "file" | "json" | "markdown" | "binary" | "dir" | "log";
+        description?: string | undefined;
+        pathPattern?: string | undefined;
+        mediaType?: string | undefined;
+        schemaRef?: string | undefined;
+        example?: {
+            summary?: string | undefined;
+            payload?: unknown;
+        } | undefined;
+    }, {
+        id: string;
+        kind: "file" | "json" | "markdown" | "binary" | "dir" | "log";
+        description?: string | undefined;
+        pathPattern?: string | undefined;
+        mediaType?: string | undefined;
+        schemaRef?: string | undefined;
+        example?: {
+            summary?: string | undefined;
+            payload?: unknown;
+        } | undefined;
+    }>>;
+    commands: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        id: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        input: z.ZodOptional<z.ZodObject<{
+            ref: z.ZodString;
+            format: z.ZodOptional<z.ZodEnum<["zod", "json-schema", "openapi"]>>;
+            description: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            ref: string;
+            format?: "zod" | "json-schema" | "openapi" | undefined;
+            description?: string | undefined;
+        }, {
+            ref: string;
+            format?: "zod" | "json-schema" | "openapi" | undefined;
+            description?: string | undefined;
+        }>>;
+        output: z.ZodOptional<z.ZodObject<{
+            ref: z.ZodString;
+            format: z.ZodOptional<z.ZodEnum<["zod", "json-schema", "openapi"]>>;
+            description: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            ref: string;
+            format?: "zod" | "json-schema" | "openapi" | undefined;
+            description?: string | undefined;
+        }, {
+            ref: string;
+            format?: "zod" | "json-schema" | "openapi" | undefined;
+            description?: string | undefined;
+        }>>;
+        produces: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        consumes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        examples: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        description?: string | undefined;
+        produces?: string[] | undefined;
+        consumes?: string[] | undefined;
+        input?: {
+            ref: string;
+            format?: "zod" | "json-schema" | "openapi" | undefined;
+            description?: string | undefined;
+        } | undefined;
+        output?: {
+            ref: string;
+            format?: "zod" | "json-schema" | "openapi" | undefined;
+            description?: string | undefined;
+        } | undefined;
+        examples?: string[] | undefined;
+    }, {
+        id: string;
+        description?: string | undefined;
+        produces?: string[] | undefined;
+        consumes?: string[] | undefined;
+        input?: {
+            ref: string;
+            format?: "zod" | "json-schema" | "openapi" | undefined;
+            description?: string | undefined;
+        } | undefined;
+        output?: {
+            ref: string;
+            format?: "zod" | "json-schema" | "openapi" | undefined;
+            description?: string | undefined;
+        } | undefined;
+        examples?: string[] | undefined;
+    }>>>;
+    workflows: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        id: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        consumes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        produces: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        steps: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            commandId: z.ZodOptional<z.ZodString>;
+            consumes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            produces: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        }, "strip", z.ZodTypeAny, {
+            id: string;
+            description?: string | undefined;
+            produces?: string[] | undefined;
+            consumes?: string[] | undefined;
+            commandId?: string | undefined;
+        }, {
+            id: string;
+            description?: string | undefined;
+            produces?: string[] | undefined;
+            consumes?: string[] | undefined;
+            commandId?: string | undefined;
+        }>, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        description?: string | undefined;
+        produces?: string[] | undefined;
+        consumes?: string[] | undefined;
+        steps?: {
+            id: string;
+            description?: string | undefined;
+            produces?: string[] | undefined;
+            consumes?: string[] | undefined;
+            commandId?: string | undefined;
+        }[] | undefined;
+    }, {
+        id: string;
+        description?: string | undefined;
+        produces?: string[] | undefined;
+        consumes?: string[] | undefined;
+        steps?: {
+            id: string;
+            description?: string | undefined;
+            produces?: string[] | undefined;
+            consumes?: string[] | undefined;
+            commandId?: string | undefined;
+        }[] | undefined;
+    }>>>;
+    api: z.ZodOptional<z.ZodObject<{
+        rest: z.ZodOptional<z.ZodObject<{
+            basePath: z.ZodString;
+            routes: z.ZodRecord<z.ZodString, z.ZodObject<{
+                id: z.ZodString;
+                method: z.ZodString;
+                path: z.ZodString;
+                description: z.ZodOptional<z.ZodString>;
+                request: z.ZodOptional<z.ZodObject<{
+                    ref: z.ZodString;
+                    format: z.ZodOptional<z.ZodEnum<["zod", "json-schema", "openapi"]>>;
+                    description: z.ZodOptional<z.ZodString>;
+                }, "strip", z.ZodTypeAny, {
+                    ref: string;
+                    format?: "zod" | "json-schema" | "openapi" | undefined;
+                    description?: string | undefined;
+                }, {
+                    ref: string;
+                    format?: "zod" | "json-schema" | "openapi" | undefined;
+                    description?: string | undefined;
+                }>>;
+                response: z.ZodOptional<z.ZodObject<{
+                    ref: z.ZodString;
+                    format: z.ZodOptional<z.ZodEnum<["zod", "json-schema", "openapi"]>>;
+                    description: z.ZodOptional<z.ZodString>;
+                }, "strip", z.ZodTypeAny, {
+                    ref: string;
+                    format?: "zod" | "json-schema" | "openapi" | undefined;
+                    description?: string | undefined;
+                }, {
+                    ref: string;
+                    format?: "zod" | "json-schema" | "openapi" | undefined;
+                    description?: string | undefined;
+                }>>;
+                produces: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+                consumes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            }, "strip", z.ZodTypeAny, {
+                path: string;
+                id: string;
+                method: string;
+                description?: string | undefined;
+                request?: {
+                    ref: string;
+                    format?: "zod" | "json-schema" | "openapi" | undefined;
+                    description?: string | undefined;
+                } | undefined;
+                response?: {
+                    ref: string;
+                    format?: "zod" | "json-schema" | "openapi" | undefined;
+                    description?: string | undefined;
+                } | undefined;
+                produces?: string[] | undefined;
+                consumes?: string[] | undefined;
+            }, {
+                path: string;
+                id: string;
+                method: string;
+                description?: string | undefined;
+                request?: {
+                    ref: string;
+                    format?: "zod" | "json-schema" | "openapi" | undefined;
+                    description?: string | undefined;
+                } | undefined;
+                response?: {
+                    ref: string;
+                    format?: "zod" | "json-schema" | "openapi" | undefined;
+                    description?: string | undefined;
+                } | undefined;
+                produces?: string[] | undefined;
+                consumes?: string[] | undefined;
+            }>>;
+        }, "strip", z.ZodTypeAny, {
+            basePath: string;
+            routes: Record<string, {
+                path: string;
+                id: string;
+                method: string;
+                description?: string | undefined;
+                request?: {
+                    ref: string;
+                    format?: "zod" | "json-schema" | "openapi" | undefined;
+                    description?: string | undefined;
+                } | undefined;
+                response?: {
+                    ref: string;
+                    format?: "zod" | "json-schema" | "openapi" | undefined;
+                    description?: string | undefined;
+                } | undefined;
+                produces?: string[] | undefined;
+                consumes?: string[] | undefined;
+            }>;
+        }, {
+            basePath: string;
+            routes: Record<string, {
+                path: string;
+                id: string;
+                method: string;
+                description?: string | undefined;
+                request?: {
+                    ref: string;
+                    format?: "zod" | "json-schema" | "openapi" | undefined;
+                    description?: string | undefined;
+                } | undefined;
+                response?: {
+                    ref: string;
+                    format?: "zod" | "json-schema" | "openapi" | undefined;
+                    description?: string | undefined;
+                } | undefined;
+                produces?: string[] | undefined;
+                consumes?: string[] | undefined;
+            }>;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        rest?: {
+            basePath: string;
+            routes: Record<string, {
+                path: string;
+                id: string;
+                method: string;
+                description?: string | undefined;
+                request?: {
+                    ref: string;
+                    format?: "zod" | "json-schema" | "openapi" | undefined;
+                    description?: string | undefined;
+                } | undefined;
+                response?: {
+                    ref: string;
+                    format?: "zod" | "json-schema" | "openapi" | undefined;
+                    description?: string | undefined;
+                } | undefined;
+                produces?: string[] | undefined;
+                consumes?: string[] | undefined;
+            }>;
+        } | undefined;
+    }, {
+        rest?: {
+            basePath: string;
+            routes: Record<string, {
+                path: string;
+                id: string;
+                method: string;
+                description?: string | undefined;
+                request?: {
+                    ref: string;
+                    format?: "zod" | "json-schema" | "openapi" | undefined;
+                    description?: string | undefined;
+                } | undefined;
+                response?: {
+                    ref: string;
+                    format?: "zod" | "json-schema" | "openapi" | undefined;
+                    description?: string | undefined;
+                } | undefined;
+                produces?: string[] | undefined;
+                consumes?: string[] | undefined;
+            }>;
+        } | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    schema: "kb.plugin.contracts/1";
+    pluginId: string;
+    contractsVersion: string;
+    artifacts: Record<string, {
+        id: string;
+        kind: "file" | "json" | "markdown" | "binary" | "dir" | "log";
+        description?: string | undefined;
+        pathPattern?: string | undefined;
+        mediaType?: string | undefined;
+        schemaRef?: string | undefined;
+        example?: {
+            summary?: string | undefined;
+            payload?: unknown;
+        } | undefined;
+    }>;
+    commands?: Record<string, {
+        id: string;
+        description?: string | undefined;
+        produces?: string[] | undefined;
+        consumes?: string[] | undefined;
+        input?: {
+            ref: string;
+            format?: "zod" | "json-schema" | "openapi" | undefined;
+            description?: string | undefined;
+        } | undefined;
+        output?: {
+            ref: string;
+            format?: "zod" | "json-schema" | "openapi" | undefined;
+            description?: string | undefined;
+        } | undefined;
+        examples?: string[] | undefined;
+    }> | undefined;
+    workflows?: Record<string, {
+        id: string;
+        description?: string | undefined;
+        produces?: string[] | undefined;
+        consumes?: string[] | undefined;
+        steps?: {
+            id: string;
+            description?: string | undefined;
+            produces?: string[] | undefined;
+            consumes?: string[] | undefined;
+            commandId?: string | undefined;
+        }[] | undefined;
+    }> | undefined;
+    api?: {
+        rest?: {
+            basePath: string;
+            routes: Record<string, {
+                path: string;
+                id: string;
+                method: string;
+                description?: string | undefined;
+                request?: {
+                    ref: string;
+                    format?: "zod" | "json-schema" | "openapi" | undefined;
+                    description?: string | undefined;
+                } | undefined;
+                response?: {
+                    ref: string;
+                    format?: "zod" | "json-schema" | "openapi" | undefined;
+                    description?: string | undefined;
+                } | undefined;
+                produces?: string[] | undefined;
+                consumes?: string[] | undefined;
+            }>;
+        } | undefined;
+    } | undefined;
+}, {
+    schema: "kb.plugin.contracts/1";
+    pluginId: string;
+    contractsVersion: string;
+    artifacts: Record<string, {
+        id: string;
+        kind: "file" | "json" | "markdown" | "binary" | "dir" | "log";
+        description?: string | undefined;
+        pathPattern?: string | undefined;
+        mediaType?: string | undefined;
+        schemaRef?: string | undefined;
+        example?: {
+            summary?: string | undefined;
+            payload?: unknown;
+        } | undefined;
+    }>;
+    commands?: Record<string, {
+        id: string;
+        description?: string | undefined;
+        produces?: string[] | undefined;
+        consumes?: string[] | undefined;
+        input?: {
+            ref: string;
+            format?: "zod" | "json-schema" | "openapi" | undefined;
+            description?: string | undefined;
+        } | undefined;
+        output?: {
+            ref: string;
+            format?: "zod" | "json-schema" | "openapi" | undefined;
+            description?: string | undefined;
+        } | undefined;
+        examples?: string[] | undefined;
+    }> | undefined;
+    workflows?: Record<string, {
+        id: string;
+        description?: string | undefined;
+        produces?: string[] | undefined;
+        consumes?: string[] | undefined;
+        steps?: {
+            id: string;
+            description?: string | undefined;
+            produces?: string[] | undefined;
+            consumes?: string[] | undefined;
+            commandId?: string | undefined;
+        }[] | undefined;
+    }> | undefined;
+    api?: {
+        rest?: {
+            basePath: string;
+            routes: Record<string, {
+                path: string;
+                id: string;
+                method: string;
+                description?: string | undefined;
+                request?: {
+                    ref: string;
+                    format?: "zod" | "json-schema" | "openapi" | undefined;
+                    description?: string | undefined;
+                } | undefined;
+                response?: {
+                    ref: string;
+                    format?: "zod" | "json-schema" | "openapi" | undefined;
+                    description?: string | undefined;
+                } | undefined;
+                produces?: string[] | undefined;
+                consumes?: string[] | undefined;
+            }>;
+        } | undefined;
+    } | undefined;
+}>;
+declare function parsePluginContracts(input: unknown): {
+    schema: "kb.plugin.contracts/1";
+    pluginId: string;
+    contractsVersion: string;
+    artifacts: Record<string, {
+        id: string;
+        kind: "file" | "json" | "markdown" | "binary" | "dir" | "log";
+        description?: string | undefined;
+        pathPattern?: string | undefined;
+        mediaType?: string | undefined;
+        schemaRef?: string | undefined;
+        example?: {
+            summary?: string | undefined;
+            payload?: unknown;
+        } | undefined;
+    }>;
+    commands?: Record<string, {
+        id: string;
+        description?: string | undefined;
+        produces?: string[] | undefined;
+        consumes?: string[] | undefined;
+        input?: {
+            ref: string;
+            format?: "zod" | "json-schema" | "openapi" | undefined;
+            description?: string | undefined;
+        } | undefined;
+        output?: {
+            ref: string;
+            format?: "zod" | "json-schema" | "openapi" | undefined;
+            description?: string | undefined;
+        } | undefined;
+        examples?: string[] | undefined;
+    }> | undefined;
+    workflows?: Record<string, {
+        id: string;
+        description?: string | undefined;
+        produces?: string[] | undefined;
+        consumes?: string[] | undefined;
+        steps?: {
+            id: string;
+            description?: string | undefined;
+            produces?: string[] | undefined;
+            consumes?: string[] | undefined;
+            commandId?: string | undefined;
+        }[] | undefined;
+    }> | undefined;
+    api?: {
+        rest?: {
+            basePath: string;
+            routes: Record<string, {
+                path: string;
+                id: string;
+                method: string;
+                description?: string | undefined;
+                request?: {
+                    ref: string;
+                    format?: "zod" | "json-schema" | "openapi" | undefined;
+                    description?: string | undefined;
+                } | undefined;
+                response?: {
+                    ref: string;
+                    format?: "zod" | "json-schema" | "openapi" | undefined;
+                    description?: string | undefined;
+                } | undefined;
+                produces?: string[] | undefined;
+                consumes?: string[] | undefined;
+            }>;
+        } | undefined;
+    } | undefined;
+};
+
+declare const contractsSchemaId: "kb.plugin.contracts/1";
+type ContractsSchemaId = typeof contractsSchemaId;
+declare const contractsVersion: "1.0.0";
+
+type SchemaFormat = 'zod' | 'json-schema' | 'openapi';
+interface SchemaReference {
+    /**
+     * Reference to the schema. Can be a URI, npm package export, or local module path.
+     */
+    ref: string;
+    /**
+     * Describes the format of the referenced schema.
+     */
+    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 materialised.
+     * Example: "artifacts/template/hello/greeting.json"
+     */
+    pathPattern?: string;
+    /**
+     * IANA media type describing the artifact. 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 help 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>;
+
+/**
+ * Plugin Configuration Contract
+ *
+ * Defines the shape of plugin configuration stored in kb.config.json
+ * under plugins.template section.
+ *
+ * This type is the single source of truth for:
+ * - defineSetup (setup handler knows what config to create)
+ * - defineCommand (commands can access typed config)
+ * - REST handlers (API can access typed config)
+ */
+/**
+ * Greeting configuration
+ */
+interface GreetingConfig {
+    /** Path to greeting config file */
+    configPath: string;
+    /** Default name to greet */
+    defaultName: string;
+}
+/**
+ * Output configuration
+ */
+interface OutputConfig {
+    /** Output directory for generated files */
+    directory: string;
+}
+/**
+ * Plugin configuration stored in kb.config.json
+ *
+ * @example
+ * ```json
+ * {
+ *   "plugins": {
+ *     "template": {
+ *       "enabled": true,
+ *       "greeting": {
+ *         "configPath": ".kb/template/hello-config.json",
+ *         "defaultName": "KB Labs"
+ *       },
+ *       "output": {
+ *         "directory": ".kb/template/output"
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+interface PluginConfig {
+    /** Whether the plugin is enabled */
+    enabled: boolean;
+    /** Greeting configuration */
+    greeting: GreetingConfig;
+    /** Output configuration */
+    output: OutputConfig;
+}
+/**
+ * Default plugin configuration values
+ */
+declare const defaultPluginConfig: PluginConfig;
+
+interface PluginContracts {
+    schema: ContractsSchemaId;
+    pluginId: string;
+    contractsVersion: string;
+    artifacts: ArtifactContractsMap;
+    commands?: CommandContractsMap;
+    workflows?: WorkflowContractsMap;
+    api?: ApiContract;
+}
+
+export { type ApiContract, type ArtifactContractsMap, type ArtifactExample, type ArtifactKind, type CommandContract, type CommandContractsMap, type GreetingConfig, type OutputConfig, type PluginArtifactContract, PluginArtifactIds, PluginCommandIds, type PluginConfig, type PluginContracts, PluginRouteIds, type RestApiContract, type RestRouteContract, type SchemaReference, type WorkflowContract, type WorkflowContractsMap, type WorkflowStepContract, contractsSchemaId, contractsVersion, defaultPluginConfig, getArtifact, getArtifactId, getArtifactPath, getCommand, getCommandId, getRoute, getRouteId, hasArtifact, hasCommand, hasRoute, parsePluginContracts, pluginContractsSchema };