micro-contracts 0.9.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024-present
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,351 @@
+# micro-contracts
+
+**Contract-first vertical slices for TypeScript Web/API systems.**
+
+micro-contracts is a contract-first toolchain for TypeScript Web/API development. It tackles common failure modes—**frontend/backend contract drift**, **duplicated "common" rules**, and **accidental breaking changes in public APIs**—by treating **OpenAPI as the Single Source of Truth (SSoT)**.
+
+Contracts alone aren't enough—they must be **enforceable**. micro-contracts includes **[Enforceable Guardrails](docs/development-guardrails.md)** that prevent both humans and AI from bypassing the contract-first workflow: blocking direct edits to generated files, detecting drift, and verifying security declarations match implementations.
+
+## Design Philosophy
+
+![Architecture](docs/architecture.svg)
+
+The core architecture is organized along two axes:
+
+| Axis | Description | Example |
+|------|-------------|---------|
+| **Vertical (feature-aligned slices)** | A *module* is a feature-aligned contract boundary. The same contract spans UI (frontend) and API (backend). | `core`, `billing`, `users` |
+| **Horizontal (cross-cutting concerns)** | Auth, tenancy, rate limiting, and shared error behavior are applied consistently via **OpenAPI Overlays**. | `x-middleware: [requireAuth, tenantIsolation]` |
+
+### Key Differentiators
+
+| # | Differentiator | What it means |
+|---|----------------|---------------|
+| 1 | **Vertical Modules + Horizontal Overlays** | Feature-aligned modules as contract boundaries; cross-cutting concerns (auth, rate-limit) injected via [OpenAPI Overlays](https://www.openapis.org/blog/2024/10/22/announcing-overlay-specification). |
+| 2 | **OpenAPI as SSoT → Multi-artifact generation** | Single spec generates contract packages, server routes, and frontend clients. No manual sync required. |
+| 3 | **Enforceable Guardrails** | Built-in checks prevent bypassing contract-first workflow—blocks direct edits to generated files, detects drift, verifies security declarations. See **[Guardrails](docs/development-guardrails.md)**. |
+| 4 | **Public Surface Governance** | `contract-published` is extracted (not duplicated) from the master contract. `x-micro-contracts-non-exportable` fails generation if internal data leaks. |
+| 5 | **Explicit Module Dependencies** | `x-micro-contracts-depend-on` declares cross-module dependencies. `deps/` re-exports only declared types; enables impact analysis. |
+
+---
+
+## Who is this for?
+
+| Scenario | Why micro-contracts helps |
+|----------|---------------------------|
+| **Modular monolith → microservices** | Same contracts work in monolith or split services; dependency tracking prevents hidden coupling |
+| **Multiple teams sharing OpenAPI** | Explicit module dependencies make cross-team impact visible |
+| **Published API with compatibility SLA** | `contract-published` extraction + `x-micro-contracts-non-exportable` fail-fast prevents accidental exposure |
+| **Cross-cutting concerns at scale** | OpenAPI Overlays inject auth/rate-limit/tenancy without copy-paste |
+
+**Not the best fit for:** Single-developer projects, auto-generated UI from schema, multi-language SDK generation (use OpenAPI Generator instead).
+
+---
+
+## Quick Start
+
+> **Prerequisites**: Node.js 18+, TypeScript 5.0+, ESM (`"type": "module"`).
+
+```bash
+# 1. Install
+npm install --save-dev micro-contracts
+
+# 2. Initialize module structure
+npx micro-contracts init core --openapi path/to/your/spec.yaml
+
+# 3. Generate all code
+npx micro-contracts generate
+```
+
+```typescript
+// 4. Use in your server
+import { registerRoutes } from './core/routes.generated.js';
+await registerRoutes(fastify);
+```
+
+> **What `init` creates**: The `init` command creates starter templates for **Fastify** (server) and **fetch API** (client).
+> These are scaffolds to get you started — modify them for your framework (Express, Hono, Axios, etc.) or add new output types.
+>
+> **📦 Full working example**: See [`examples/`](./examples/) for a complete project with multiple modules, overlays, and cross-module dependencies.
+
+---
+
+## Core Concepts
+
+### OpenAPI as Single Source of Truth (SSoT)
+
+```
+OpenAPI spec (spec/{module}/openapi/*.yaml)
+    ↓ micro-contracts generate
+Contract packages (packages/contract/{module}/)
+    ├── schemas/types.ts       # Request/Response types
+    ├── domains/               # Domain interfaces
+    └── overlays/              # Overlay handler interfaces
+    ↓
+Server routes + Frontend clients (generated via templates)
+```
+
+### Modules vs Services
+
+| Concept | Definition | Example |
+|---------|------------|---------|
+| **Module** | Logical contract boundary (OpenAPI + Domain) | `core`, `billing`, `users` |
+| **Service** | Deployment unit (can contain 1+ modules) | `api-server` |
+
+A monolith may have multiple modules in one service. Start with multiple modules in one service and split later as needed.
+
+### Contract Packages
+
+| Package | Description | Compatibility Policy |
+|---------|-------------|---------------------|
+| `contract` | Master contract (all APIs) | Internal APIs can change freely |
+| `contract-published` | Public APIs only (`x-micro-contracts-published: true`) | Must maintain backward compatibility |
+
+**Key insight**: `contract-published` is **extracted from** `contract` (not generated separately). This ensures a single SSoT.
+
+### Cross-cutting Concerns with Overlays
+
+1. Mark operations with `x-middleware` (or custom extensions) in OpenAPI
+2. Define overlay that adds params/responses when extension is present
+3. Generator applies overlays and produces `openapi.generated.yaml`
+4. Generate code from the result
+
+> **📖 Deep Dive**: See **[OpenAPI Overlays (Deep Dive)](docs/overlays-deep-dive.md)** for complete examples and configuration.
+
+---
+
+## Directory Structure
+
+```
+project/
+├── spec/                              # ✅ Human-edited (contract source of truth)
+│   ├── spectral.yaml                  #    Global lint rules
+│   ├── default/templates/             #    Handlebars templates (customizable)
+│   ├── _shared/
+│   │   ├── openapi/                   #    Shared schemas (ProblemDetails, etc.)
+│   │   └── overlays/                  #    Cross-module overlays
+│   └── {module}/
+│       ├── openapi/{module}.yaml      #    OpenAPI spec
+│       └── overlays/                  #    Module-specific overlays
+│
+├── packages/                          # ❌ Auto-generated (DO NOT EDIT)
+│   ├── contract/{module}/
+│   │   ├── schemas/                   #    Types, validators
+│   │   ├── domains/                   #    Domain interfaces
+│   │   ├── overlays/                  #    Overlay handler interfaces
+│   │   └── deps/                      #    Re-exports from dependencies
+│   └── contract-published/{module}/   #    Public API subset
+│
+├── server/src/{module}/
+│   ├── routes.generated.ts            # ❌ Auto-generated (template: fastify-routes.hbs)
+│   ├── domains/                       # ✅ Human-edited (domain implementations)
+│   └── overlays/                      # ✅ Human-edited (overlay implementations)
+│
+└── frontend/src/{module}/
+    └── api.generated.ts               # ❌ Auto-generated (template: fetch-client.hbs)
+```
+
+> **Note**: `*.generated.ts` files are generated from Handlebars templates in `spec/default/templates/`.
+> You can customize or replace templates for different frameworks (Express, Hono, Axios, etc.).
+>
+> **Why commit generated files?** Generated artifacts are committed to enable code review of contract changes and CI drift detection. If spec changes but generated code doesn't match, CI fails.
+
+---
+
+## OpenAPI Extensions
+
+### Required Extensions
+
+| Extension | Type | Description |
+|-----------|------|-------------|
+| `x-micro-contracts-domain` | string | Domain class name (e.g., `User`, `Order`) |
+| `x-micro-contracts-method` | string | Method name to call (should match `operationId`) |
+
+### Optional Extensions
+
+| Extension | Type | Description |
+|-----------|------|-------------|
+| `x-micro-contracts-published` | boolean | Include in `contract-published` (compatibility SLA) |
+| `x-micro-contracts-non-exportable` | boolean | Mark as non-exportable (fails if used in published endpoints) |
+| `x-micro-contracts-depend-on` | string[] | Explicit dependencies on other modules' published APIs |
+
+### Example
+
+```yaml
+paths:
+  /api/users:
+    get:
+      operationId: getUsers
+      x-micro-contracts-domain: User
+      x-micro-contracts-method: getUsers
+      x-micro-contracts-published: true
+      x-middleware: [requireAuth]            # Custom extension for overlays
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UserListResponse'
+```
+
+### Module Dependencies
+
+Declare dependencies with `x-micro-contracts-depend-on`:
+
+```yaml
+# spec/billing/openapi/billing.yaml
+info:
+  x-micro-contracts-depend-on:
+    - core.User.getUsers
+    - core.User.getUserById
+```
+
+Import via generated `deps/`:
+
+```typescript
+// ✅ Recommended: Import from deps/
+import type { User } from '@project/contract/billing/deps/core';
+
+// ❌ Avoid: Direct contract-published import
+import type { User } from '@project/contract-published/core/schemas';
+```
+
+---
+
+## Configuration
+
+Create `micro-contracts.config.yaml`:
+
+```yaml
+defaults:
+  contract:
+    output: packages/contract/{module}
+  contractPublic:
+    output: packages/contract-published/{module}
+  outputs:
+    server-routes:
+      output: server/src/{module}/routes.generated.ts
+      template: spec/default/templates/fastify-routes.hbs
+    frontend-api:
+      output: frontend/src/{module}/api.generated.ts
+      template: spec/default/templates/fetch-client.hbs
+  overlays:
+    shared:
+      - spec/_shared/overlays/middleware.overlay.yaml
+
+modules:
+  core:
+    openapi: openapi/core.yaml
+  billing:
+    openapi: openapi/billing.yaml
+    dependsOn:
+      - core.User.getUsers
+```
+
+---
+
+## CLI Reference
+
+```bash
+micro-contracts <command> [options]
+
+Commands:
+  init <module>   Initialize a new module structure
+  generate        Generate code from OpenAPI specifications
+  lint            Lint OpenAPI specifications (Spectral)
+  check           Run guardrail checks
+  deps            Analyze module dependencies
+```
+
+### generate
+
+```bash
+micro-contracts generate [options]
+
+Options:
+  -m, --module <names>    Module names, comma-separated (default: all)
+  --contracts-only        Generate contract packages only
+  --server-only           Generate server routes only
+  --frontend-only         Generate frontend clients only
+```
+
+### lint
+
+```bash
+micro-contracts lint [options]
+
+Options:
+  -m, --module <names>    Module names (default: all)
+  --strict                Treat warnings as errors
+```
+
+### deps
+
+```bash
+micro-contracts deps [options]
+
+Options:
+  --graph                 Display dependency graph
+  --who-depends-on <api>  Find modules that depend on specific API
+  --impact <api>          Analyze impact of changing specific API
+```
+
+---
+
+## Generated Code
+
+### Domain Interface
+
+```typescript
+// packages/contract/core/domains/UserDomainApi.ts
+export interface UserDomainApi {
+  getUsers(input: UserDomain_getUsersInput): Promise<UserListResponse>;
+  getUserById(input: UserDomain_getUserByIdInput): Promise<User>;
+}
+```
+
+### Domain Implementation
+
+```typescript
+// server/src/core/domains/UserDomain.ts
+import type { UserDomainApi } from '@project/contract/core/domains/UserDomainApi.js';
+
+export class UserDomain implements UserDomainApi {
+  async getUsers(input) {
+    // Input is HTTP-agnostic: { limit?: number, offset?: number }
+    return { users: [...], total: 100 };
+  }
+}
+```
+
+---
+
+## Related Documentation
+
+| Document | Description |
+|----------|-------------|
+| **[Examples](./examples/)** | Complete working project with multiple modules, overlays, and cross-module dependencies |
+| **[OpenAPI Overlays (Deep Dive)](docs/overlays-deep-dive.md)** | Complete overlay examples, JSONPath patterns, template context |
+| **[Enforceable Guardrails (AI-ready)](docs/development-guardrails.md)** | CI integration, security checks, allowlist configuration |
+
+---
+
+## Comparison with Similar Tools
+
+| Aspect | micro-contracts | OpenAPI Generator | ts-rest |
+|--------|-----------------|-------------------|---------|
+| **Primary focus** | Contract governance (server + frontend + CI) | Multi-language SDK generation | TypeScript-first contract |
+| **SSoT** | OpenAPI | OpenAPI | TypeScript |
+| **Multi-artifact generation** | ✅ contract + routes + clients | △ SDK-focused (different goal) | ✅ Strong client/server alignment |
+| **Enforceable guardrails** | ✅ Built-in (drift, no direct edit, CI gates) | ❌ Requires separate design | ❌ Requires separate design |
+| **Public API governance** | ✅ `contract-published` + fail-fast | ❌ Manual | ❌ N/A |
+| **Module dependencies** | ✅ `x-micro-contracts-depend-on` + `deps/` | ❌ Manual | ❌ Manual |
+| **Cross-cutting concerns** | ✅ OpenAPI Overlays | ❌ Manual | △ Code-level implementation |
+
+
+---
+
+## License
+
+MIT

package/dist/cli/templates.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Starter Templates for micro-contracts init command
+ *
+ * These templates are created in spec/default/templates/ and can be customized.
+ * Keep in sync with examples/spec/default/templates/
+ */
+export declare const STARTER_FASTIFY_ROUTES_TEMPLATE = "/**\n * Auto-generated Fastify routes\n * Generated from: {{spec.info.title}} v{{spec.info.version}}\n * DO NOT EDIT MANUALLY\n */\n\nimport type { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';\nimport { allSchemas } from '{{contractPackage}}/schemas/index.js';\nimport * as types from '{{contractPackage}}/schemas/types.js';\n{{#if extensionInfo.length}}\nimport { runOverlays, toHttpRequest, sendError } from './overlayAdapter.generated.js';\n{{/if}}\n\nexport async function registerRoutes(fastify: FastifyInstance): Promise<void> {\n  for (const schema of allSchemas) {\n    fastify.addSchema(schema);\n  }\n\n  const { {{#each domains}}{{key}}{{#unless @last}}, {{/unless}}{{/each}} } = {{domainsPath}};\n{{#if extensionInfo.length}}\n  const handlers = fastify.overlayHandlers;\n{{/if}}\n\n{{#each routes}}\n  // {{uppercase method}} {{path}}{{#if isPublished}} [PUBLISHED]{{/if}}\n  fastify.{{method}}('{{fastifyPath}}', {\n    schema: {\n{{#if paramsType}}\n      params: { $ref: '{{typeNameBase}}Params#' },\n{{/if}}\n{{#if requestBody}}\n      body: { $ref: '{{requestBody.schemaName}}#' },\n{{/if}}\n{{#if responses.length}}\n      response: { {{#each responses}}{{#if schemaName}}{{statusCode}}: { $ref: '{{schemaName}}#' }{{#unless @last}}, {{/unless}}{{/if}}{{/each}} },\n{{/if}}\n    },\n  }, async (req: FastifyRequest, reply: FastifyReply) => {\n{{#if extensions.length}}\n    const result = await runOverlays('{{operationId}}', handlers, toHttpRequest(req));\n    if (!result.success) return sendError(reply, result.error);\n{{/if}}\n    // Build input object (always required, even if empty)\n    const input: types.{{inputType}} = {\n{{#if pathParams.length}}\n      ...(req.params as types.{{typeNameBase}}Params),\n{{/if}}\n{{#if queryParams.length}}\n      ...(req.query as types.{{typeNameBase}}Params),\n{{/if}}\n{{#if requestBody}}\n      data: req.body as types.{{requestBody.schemaName}},\n{{/if}}\n    };\n    return {{domainKey}}.{{domainMethod}}(input);\n  });\n\n{{/each}}\n}\n";
+export declare const STARTER_FETCH_CLIENT_TEMPLATE = "/**\n * Auto-generated HTTP Client from OpenAPI specification\n * Generated from: {{title}} v{{version}}\n * \n * DO NOT EDIT MANUALLY\n * \n * Client API matches Domain API signature (single input object).\n * Internally maps input to HTTP request (path params, query params, body).\n */\n\nimport type {\n{{#each domainTypes}}\n  {{this}},\n{{/each}}\n} from '{{contractPackage}}/domains';\nimport type {\n{{#each schemaTypes}}\n  {{this}},\n{{/each}}\n} from '{{contractPackage}}/schemas';\nimport { ApiError } from '{{contractPackage}}/errors';\n\n// BASE_URL derived from OpenAPI servers[0].url: {{baseUrl}}\n// Can be overridden via environment variable (Vite: VITE_API_BASE_URL)\nconst BASE_URL = (typeof import.meta !== 'undefined' && import.meta.env?.VITE_API_BASE_URL) || '{{baseUrl}}';\n\n/**\n * Handle HTTP response with typed error handling\n */\nasync function handleResponse<T>(res: Response): Promise<T> {\n  if (!res.ok) {\n    const problem = await res.json() as ProblemDetails;\n    throw new ApiError(\n      res.status,\n      problem,\n      res.headers.get('x-request-id') ?? undefined\n    );\n  }\n  // Handle 204 No Content and empty responses\n  if (res.status === 204 || res.headers.get('content-length') === '0') {\n    return undefined as T;\n  }\n  return res.json();\n}\n\n{{#each domains}}\n// ==========================================================================\n// {{name}} API Client\n// ==========================================================================\nexport const {{key}}Api: {{name}}Api = {\n{{#each ../routes}}\n{{#if (eq domain ../name)}}\n  /**\n   * {{httpMethod}} {{path}}\n   {{#if summary}}* {{summary}}{{/if}}\n   {{#if isPublished}}* @published{{/if}}\n   */\n  async {{domainMethod}}(input: {{inputType}}): Promise<{{responseType}}> {\n{{#if queryParams.length}}\n    const searchParams = new URLSearchParams();\n{{#each queryParams}}\n    if (input.{{name}} !== undefined) searchParams.set('{{name}}', String(input.{{name}}));\n{{/each}}\n{{/if}}\n{{#if pathParams.length}}\n    const url = `${BASE_URL}{{clientUrlPatternInput}}`{{#if queryParams.length}} + (searchParams.toString() ? '?' + searchParams : ''){{/if}};\n{{else}}\n    const url = `${BASE_URL}{{path}}`{{#if queryParams.length}} + (searchParams.toString() ? '?' + searchParams : ''){{/if}};\n{{/if}}\n{{#if (eq httpMethod \"GET\")}}\n    const res = await fetch(url);\n{{else if requestType}}\n    const res = await fetch(url, {\n      method: '{{httpMethod}}',\n      headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify(input.data),\n    });\n{{else}}\n    const res = await fetch(url, { method: '{{httpMethod}}' });\n{{/if}}\n{{#if (eq responseType \"void\")}}\n    await handleResponse<void>(res);\n{{else}}\n    return handleResponse<{{responseType}}>(res);\n{{/if}}\n  },\n\n{{/if}}\n{{/each}}\n};\n\n{{/each}}\n";
+export declare const STARTER_DOMAIN_STUBS_TEMPLATE = "{{!-- Domain implementation stubs template --}}\n{{!-- Generates skeleton implementations for domain methods --}}\n// Auto-generated domain stubs - Edit to implement business logic\nimport type { {{#each domains}}{{this}}DomainApi{{#unless @last}}, {{/unless}}{{/each}} } from '{{config.contractPackage}}/domains';\nimport type * as types from '{{config.contractPackage}}/schemas/types';\n\n{{#each domains}}\n/**\n * {{this}} Domain Implementation\n * \n * Implement the methods below with your business logic.\n * Generated methods receive HTTP-agnostic input objects.\n */\nexport class {{this}}Domain implements {{this}}DomainApi {\n{{#each ../operations}}\n{{#if (eq domain ../this)}}\n  /**\n   * {{summary}}\n   * {{method}} {{path}}\n   */\n  async {{domainMethod}}({{#if inputType}}input: types.{{inputType}}{{/if}}): Promise<types.{{responseType}}> {\n    // TODO: Implement {{domainMethod}}\n    throw new Error('Not implemented: {{domainMethod}}');\n  }\n\n{{/if}}\n{{/each}}\n}\n\n{{/each}}\n";
+export declare const STARTER_OVERLAY_ADAPTER_TEMPLATE = "/**\n * Auto-generated Overlay Adapter\n * Generated from: {{spec.info.title}} v{{spec.info.version}}\n * DO NOT EDIT MANUALLY\n */\n\nimport type { FastifyReply } from 'fastify';\nimport type { OverlayResult, OverlayRegistry } from '{{contractPackage}}/overlays/index.js';\nimport type { ProblemDetails } from '{{contractPackage}}/schemas/types.js';\n\n// ==========================================================================\n// Types\n// ==========================================================================\n\n/** HTTP request abstraction */\nexport interface HttpRequest {\n  headers: Record<string, string | string[] | undefined>;\n  params: Record<string, string>;\n  query: Record<string, unknown>;\n  body: unknown;\n}\n\n/** Parameter extractor function */\ntype ParamExtractor = (req: HttpRequest) => Record<string, unknown>;\n\n// ==========================================================================\n// Parameter Extractors (one per overlay, shared across endpoints)\n// ==========================================================================\n\nconst getHeader = (req: HttpRequest, name: string): string | undefined =>\n  req.headers[name.toLowerCase()] as string | undefined;\n\nconst getQuery = (req: HttpRequest, name: string): unknown => req.query[name];\n\nconst getParam = (req: HttpRequest, name: string): string | undefined => req.params[name];\n\n/** Overlay parameter extractors - each overlay defined once */\nconst extractors: Record<string, ParamExtractor> = {\n{{#each uniqueOverlays}}\n  '{{name}}': (req) => ({\n{{#each params}}\n    '{{name}}': {{#if (eq location \"headers\")}}getHeader(req, '{{name}}'){{else if (eq location \"query\")}}getQuery(req, '{{name}}'){{else}}getParam(req, '{{name}}'){{/if}},\n{{/each}}\n  }),\n{{/each}}\n};\n\n// ==========================================================================\n// Endpoint \u2192 Overlay Mapping\n// ==========================================================================\n\n/** Which overlays apply to each endpoint */\nexport const endpointOverlays: Record<string, string[]> = {\n{{#each routes}}\n{{#if extensions.length}}\n  '{{operationId}}': [{{#each extensions}}'{{value}}'{{#unless @last}}, {{/unless}}{{/each}}],\n{{/if}}\n{{/each}}\n};\n\n// ==========================================================================\n// Overlay Execution\n// ==========================================================================\n\n/**\n * Execute overlays for an endpoint\n */\nexport async function runOverlays(\n  operationId: string,\n  handlers: OverlayRegistry,\n  req: HttpRequest\n): Promise<{ success: true; context: Record<string, unknown> } | { success: false; error: ProblemDetails }> {\n  const overlayNames = endpointOverlays[operationId] || [];\n  const context: Record<string, unknown> = {};\n\n  for (const name of overlayNames) {\n    const extract = extractors[name];\n    const handler = handlers[name as keyof OverlayRegistry];\n    \n    if (!extract || !handler) continue;\n\n    const input = extract(req);\n    const result = await (handler as (input: Record<string, unknown>) => Promise<OverlayResult<unknown>>)(input);\n\n    if (!result.success) {\n      return {\n        success: false,\n        error: {\n          type: `/errors/${result.error?.code?.toLowerCase() ?? 'error'}`,\n          title: result.error?.message ?? 'Error',\n          status: result.error?.status ?? 500,\n        },\n      };\n    }\n\n    if (result.context) {\n      Object.assign(context, result.context);\n    }\n  }\n\n  return { success: true, context };\n}\n\n/**\n * Build HttpRequest from Fastify request\n */\nexport function toHttpRequest(req: { headers: unknown; params: unknown; query: unknown; body: unknown }): HttpRequest {\n  return {\n    headers: req.headers as Record<string, string | string[] | undefined>,\n    params: req.params as Record<string, string>,\n    query: req.query as Record<string, unknown>,\n    body: req.body,\n  };\n}\n\n/**\n * Send error response\n */\nexport function sendError(reply: FastifyReply, error: ProblemDetails): void {\n  reply.status(error.status).send(error);\n}\n";
+export declare const STARTER_OVERLAY_STUBS_TEMPLATE = "{{!-- Extension implementation stubs template --}}\n{{!-- Generates skeleton implementations for overlay handlers --}}\n// Auto-generated extension stubs - Edit to implement overlay logic\nimport type {\n  OverlayResult,\n{{#each extensionTypes}}\n  {{this}}OverlayInput,\n  {{this}}Overlay,\n{{/each}}\n  OverlayRegistry,\n} from '{{config.contractPackage}}/overlays';\n\n{{#each extensions}}\n/**\n * {{name}} overlay handler\n * \n * Called when an endpoint has x-middleware: [{{name}}]\n * Returns OverlayResult with success/error status\n */\nexport async function {{camelCase name}}(\n  input: {{pascalCase name}}OverlayInput\n): Promise<OverlayResult> {\n  // TODO: Implement {{name}} logic\n{{#if injectedParameters}}\n  // Input parameters:\n{{#each injectedParameters}}\n  // - {{name}}: {{schema.type}}{{#if required}} (required){{/if}}\n{{/each}}\n{{/if}}\n\n  // Example implementation:\n  // if (!validateSomething(input)) {\n  //   return {\n  //     success: false,\n  //     error: { status: 4xx, message: 'Error message', code: 'ERROR_CODE' },\n  //   };\n  // }\n\n  return { success: true, context: { /* optional context for domain */ } };\n}\n\n{{/each}}\n/**\n * Registry of all overlay handlers\n * Register this with your server framework\n */\nexport const overlayHandlers: OverlayRegistry = {\n{{#each extensions}}\n  {{camelCase name}}: {{camelCase name}},\n{{/each}}\n};\n";
+/**
+ * Get all starter templates
+ */
+export declare function getStarterTemplates(): Record<string, string>;
+//# sourceMappingURL=templates.d.ts.map

package/dist/cli/templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../src/cli/templates.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,+BAA+B,g/DA2D3C,CAAC;AAEF,eAAO,MAAM,6BAA6B,+zFA4FzC,CAAC;AAEF,eAAO,MAAM,6BAA6B,k/BA8BzC,CAAC;AAEF,eAAO,MAAM,gCAAgC,ijIAyH5C,CAAC;AAEF,eAAO,MAAM,8BAA8B,63CAmD1C,CAAC;AAEF;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAQ5D"}