@contractspec/lib.contracts 1.61.0 → 1.63.0

package/dist/docs/tech/llm/llm-integration.docblock.js

@@ -1,482 +0,0 @@
-// @bun
-var __defProp = Object.defineProperty;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __moduleCache = /* @__PURE__ */ new WeakMap;
-var __toCommonJS = (from) => {
-  var entry = __moduleCache.get(from), desc;
-  if (entry)
-    return entry;
-  entry = __defProp({}, "__esModule", { value: true });
-  if (from && typeof from === "object" || typeof from === "function")
-    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
-      get: () => from[key],
-      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-    }));
-  __moduleCache.set(from, entry);
-  return entry;
-};
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, {
-      get: all[name],
-      enumerable: true,
-      configurable: true,
-      set: (newValue) => all[name] = () => newValue
-    });
-};
-var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
-var __require = import.meta.require;
-
-// src/docs/presentations.ts
-var DEFAULT_TARGETS = [
-  "markdown",
-  "react"
-];
-function normalizeRoute(route) {
-  if (!route.length)
-    return "/";
-  const withLeading = route.startsWith("/") ? route : `/${route}`;
-  return withLeading === "/" ? "/" : withLeading.replace(/\/+$/, "");
-}
-function deriveRoute(block, routePrefix) {
-  if (block.route)
-    return normalizeRoute(block.route);
-  const prefix = routePrefix ?? "/docs";
-  const slug = block.id.replace(/^docs\.?/, "").replace(/\./g, "/").replace(/\/+/g, "/");
-  const path = slug.startsWith("/") ? slug : `${prefix}/${slug}`;
-  return normalizeRoute(path);
-}
-function buildName(block, namespace) {
-  return namespace ? `${namespace}.${block.id}` : block.id;
-}
-function docBlockToPresentationSpec(block, options) {
-  const targets = options?.defaultTargets ?? DEFAULT_TARGETS;
-  const version = block.version ?? options?.defaultVersion ?? "1.0.0";
-  const stability = block.stability ?? options?.defaultStability ?? "stable";
-  return {
-    meta: {
-      key: buildName(block, options?.namespace),
-      title: block.title,
-      version,
-      description: block.summary ?? block.title,
-      tags: block.tags || [],
-      owners: block.owners || [],
-      domain: block.domain || "",
-      stability,
-      goal: `Documentation of: ${block.summary}`,
-      context: `Auto-generated`
-    },
-    policy: block.visibility && block.visibility !== "public" ? { flags: [block.visibility] } : undefined,
-    source: {
-      type: "blocknotejs",
-      docJson: block.body
-    },
-    targets
-  };
-}
-function docBlocksToPresentationRoutes(blocks, options) {
-  return blocks.map((block) => ({
-    block,
-    route: deriveRoute(block, options?.routePrefix),
-    descriptor: docBlockToPresentationSpec(block, options)
-  }));
-}
-function docBlocksToPresentationSpecs(blocks, options) {
-  return blocks.map((block) => docBlockToPresentationSpec(block, options));
-}
-function mapDocRoutes(routes) {
-  return routes.map(({ route, descriptor }) => [route, descriptor]);
-}
-
-// src/docs/registry.ts
-class DocRegistry {
-  routes = new Map;
-  constructor(blocks = [], options) {
-    blocks.forEach((block) => this.register(block, options));
-  }
-  register(block, options) {
-    const [route] = docBlocksToPresentationRoutes([block], options);
-    if (route) {
-      this.routes.set(block.id, route);
-    }
-    return this;
-  }
-  list() {
-    return [...this.routes.values()];
-  }
-  get(id) {
-    return this.routes.get(id);
-  }
-  toRouteTuples() {
-    return this.list().map(({ route, descriptor }) => [route, descriptor]);
-  }
-  toPresentationSpecs(options) {
-    return this.list().map(({ block }) => docBlockToPresentationSpec(block, options));
-  }
-}
-var requiredFields = [
-  "id",
-  "title",
-  "body",
-  "kind",
-  "visibility",
-  "route"
-];
-var defaultDocRegistry = new DocRegistry;
-function registerDocBlocks(blocks) {
-  for (const block of blocks) {
-    for (const field of requiredFields) {
-      if (!block[field]) {
-        throw new Error(`DocBlock ${block.id ?? "<missing id>"} missing field ${String(field)}`);
-      }
-    }
-    defaultDocRegistry.register(block);
-  }
-}
-function listRegisteredDocBlocks() {
-  return defaultDocRegistry.list().map((r) => r.block);
-}
-function docId(id) {
-  const found = defaultDocRegistry.get(id);
-  if (!found)
-    throw new Error(`DocBlock not registered: ${id}`);
-  return id;
-}
-
-// src/docs/tech/llm/llm-integration.docblock.ts
-var tech_llm_integration_DocBlocks = [
-  {
-    id: "docs.tech.llm.overview",
-    title: "LLM Integration Overview",
-    summary: "Export specs to LLM-friendly formats, generate implementation guides, and verify implementations.",
-    kind: "reference",
-    visibility: "public",
-    route: "/docs/tech/llm/overview",
-    tags: ["llm", "ai", "export", "guide", "verify"],
-    body: `# LLM Integration
-
-ContractSpec provides first-class LLM integration to bridge specifications and AI coding agents.
-
-## Core Features
-
-### 1. Multi-Format Export
-
-Export specs to markdown in formats optimized for LLM consumption:
-
-- **Context format**: Summary for understanding (goal, context, acceptance criteria)
-- **Full format**: Complete spec with all details (I/O schemas, policy, events)
-- **Prompt format**: Actionable prompt with implementation instructions
-
-### 2. Implementation Guidance
-
-Generate agent-specific implementation plans:
-
-- **Claude Code**: Extended thinking mode with structured prompts
-- **Cursor CLI**: Background/composer mode with .mdc rules generation
-- **Generic MCP**: Standard format for any MCP-compatible agent
-
-### 3. Tiered Verification
-
-Verify implementations against specs:
-
-- **Tier 1 (Structure)**: Types, exports, imports validation
-- **Tier 2 (Behavior)**: Scenario coverage, error handling, events
-- **Tier 3 (AI Review)**: Semantic compliance analysis via LLM
-
-## Access Points
-
-| Surface | Commands/Tools |
-|---------|---------------|
-| CLI | \`contractspec llm export\`, \`guide\`, \`verify\`, \`copy\` |
-| MCP | \`llm.export\`, \`llm.guide\`, \`llm.verify\` tools |
-| VSCode | Export to LLM, Generate Guide, Verify, Copy commands |
-
-## Quick Start
-
-### CLI Usage
-
-\`\`\`bash
-# Export spec as markdown
-contractspec llm export path/to/my.spec.ts --format full
-
-# Generate implementation guide
-contractspec llm guide path/to/my.spec.ts --agent claude-code
-
-# Verify implementation
-contractspec llm verify path/to/my.spec.ts path/to/impl.ts --tier 2
-
-# Copy spec to clipboard
-contractspec llm copy path/to/my.spec.ts --format context
-\`\`\`
-
-### MCP Usage
-
-\`\`\`
-# Export spec
-llm.export { specPath: "path/to/my.spec.ts", format: "full" }
-
-# Generate guide
-llm.guide { specPath: "path/to/my.spec.ts", agent: "cursor-cli" }
-
-# Verify implementation
-llm.verify { specPath: "path/to/my.spec.ts", implementationPath: "path/to/impl.ts", tier: "2" }
-\`\`\`
-
-### Programmatic Usage
-
-\`\`\`typescript
-import { operationSpecToFullMarkdown, operationSpecToAgentPrompt } from '@contractspec/lib.contracts/llm';
-import { createAgentGuideService, createVerifyService } from '@contractspec/bundle.workspace';
-
-// Export
-const markdown = operationSpecToFullMarkdown(mySpec);
-
-// Generate guide
-const guideService = createAgentGuideService({ defaultAgent: 'claude-code' });
-const guide = guideService.generateGuide(mySpec);
-
-// Verify
-const verifyService = createVerifyService();
-const result = await verifyService.verify(mySpec, implementationCode, {
-  tiers: ['structure', 'behavior']
-});
-\`\`\`
-`
-  },
-  {
-    id: "docs.tech.llm.export-formats",
-    title: "LLM Export Formats",
-    summary: "Detailed explanation of the three export formats for LLM consumption.",
-    kind: "reference",
-    visibility: "public",
-    route: "/docs/tech/llm/export-formats",
-    tags: ["llm", "export", "markdown"],
-    body: `# LLM Export Formats
-
-ContractSpec provides three export formats optimized for different LLM use cases.
-
-## Context Format
-
-Best for: Understanding what a spec does, providing background to LLMs.
-
-Includes:
-- Spec name, version, type
-- Goal and context
-- Description
-- Acceptance scenarios
-
-Example:
-
-\`\`\`markdown
-# users.createUser (v1)
-
-> Create a new user account with email verification.
-
-**Type:** command | **Stability:** stable
-
-## Goal
-Create a new user in the system and trigger email verification.
-
-## Context
-Part of the user onboarding flow. Called after signup form submission.
-
-## Acceptance Criteria
-### Happy path
-**Given:** Valid email and password
-**When:** User submits registration
-**Then:** Account is created, verification email is sent
-\`\`\`
-
-## Full Format
-
-Best for: Complete documentation, implementation reference.
-
-Includes everything:
-- All metadata
-- JSON schemas for I/O
-- Error definitions
-- Policy (auth, rate limits, PII)
-- Events emitted
-- Examples
-- Transport configuration
-
-## Prompt Format
-
-Best for: Feeding directly to coding agents.
-
-Includes:
-- Task header with clear instructions
-- Full spec context
-- Implementation requirements
-- Task-specific guidance (implement/test/refactor/review)
-- Expected output format
-
-The prompt format adapts based on task type:
-- **implement**: Full implementation with tests
-- **test**: Test generation for existing code
-- **refactor**: Refactoring while maintaining behavior
-- **review**: Code review against spec
-`
-  },
-  {
-    id: "docs.tech.llm.agent-adapters",
-    title: "Agent Adapters",
-    summary: "Adapters for different AI coding agents (Claude, Cursor, MCP).",
-    kind: "reference",
-    visibility: "public",
-    route: "/docs/tech/llm/agent-adapters",
-    tags: ["llm", "agents", "claude", "cursor", "mcp"],
-    body: `# Agent Adapters
-
-ContractSpec provides specialized adapters for different AI coding agents.
-
-## Claude Code Adapter
-
-Optimized for Anthropic Claude's extended thinking and code generation.
-
-Features:
-- Structured markdown with clear sections
-- Checklists for steps and verification
-- Icons for file operations (\uD83D\uDCDD create, \u270F\uFE0F modify)
-- System prompt for ContractSpec context
-
-Usage:
-\`\`\`typescript
-const guideService = createAgentGuideService({ defaultAgent: 'claude-code' });
-const result = guideService.generateGuide(spec, { agent: 'claude-code' });
-// result.prompt.systemPrompt - Claude system context
-// result.prompt.taskPrompt - Task-specific instructions
-\`\`\`
-
-## Cursor CLI Adapter
-
-Optimized for Cursor's background/composer mode.
-
-Features:
-- Compact format for context efficiency
-- .mdc cursor rules generation
-- Integration with Cursor's file system
-- Concise step lists
-
-Generate Cursor Rules:
-\`\`\`typescript
-const cursorRules = guideService.generateAgentConfig(spec, 'cursor-cli');
-// Save to .cursor/rules/my-spec.mdc
-\`\`\`
-
-## Generic MCP Adapter
-
-Works with any MCP-compatible agent (Cline, Aider, etc.).
-
-Features:
-- Standard markdown format
-- Table-based metadata
-- JSON resource format support
-- Prompt message format
-
-The generic adapter is the default and works across all agents.
-
-## Choosing an Adapter
-
-| Agent | Best For | Key Features |
-|-------|----------|--------------|
-| Claude Code | Complex implementations | Extended thinking, detailed steps |
-| Cursor CLI | IDE-integrated work | Cursor rules, compact format |
-| Generic MCP | Any MCP agent | Universal compatibility |
-`
-  },
-  {
-    id: "docs.tech.llm.verification",
-    title: "Implementation Verification",
-    summary: "Tiered verification of implementations against specifications.",
-    kind: "reference",
-    visibility: "public",
-    route: "/docs/tech/llm/verification",
-    tags: ["llm", "verify", "validation", "testing"],
-    body: `# Implementation Verification
-
-ContractSpec provides tiered verification to check if implementations comply with specs.
-
-## Verification Tiers
-
-### Tier 1: Structure (Fast)
-
-Checks TypeScript structure against spec requirements:
-
-| Check | What it validates |
-|-------|------------------|
-| Handler export | Function is properly exported |
-| Contracts import | Imports from @contractspec/lib.contracts |
-| Schema import | Imports from @contractspec/lib.schema |
-| No \`any\` type | TypeScript strict compliance |
-| Error handling | Error codes are referenced |
-| Event emission | Event patterns exist |
-| Input validation | Validation patterns used |
-| Async patterns | Async/await for commands |
-
-### Tier 2: Behavior (Comprehensive)
-
-Checks implementation coverage of spec behaviors:
-
-| Check | What it validates |
-|-------|------------------|
-| Scenario coverage | Acceptance scenarios implemented |
-| Example coverage | Example I/O values referenced |
-| Error cases | All error conditions handled |
-| Event conditions | Events emitted correctly |
-| Idempotency | Idempotent patterns (if required) |
-
-### Tier 3: AI Review (Deep)
-
-Uses LLM for semantic analysis:
-
-- Does the implementation fulfill the spec's intent?
-- Are edge cases properly handled?
-- Is the code quality acceptable?
-- Are there any subtle violations?
-
-Requires AI API key configuration.
-
-## Running Verification
-
-\`\`\`typescript
-const verifyService = createVerifyService({
-  aiApiKey: process.env.ANTHROPIC_API_KEY, // Optional, for Tier 3
-  aiProvider: 'anthropic',
-});
-
-const result = await verifyService.verify(spec, implementationCode, {
-  tiers: ['structure', 'behavior'],
-  failFast: false,
-  includeSuggestions: true,
-});
-
-console.log(result.passed);  // true/false
-console.log(result.score);   // 0-100
-console.log(result.summary); // Human-readable summary
-\`\`\`
-
-## Verification Report
-
-The report includes:
-
-- **passed**: Overall compliance
-- **score**: 0-100 score
-- **issues**: Array of problems found
-- **suggestions**: Recommended fixes
-- **coverage**: Metrics on scenario/error/field coverage
-
-Each issue has:
-- **severity**: error, warning, or info
-- **category**: type, export, import, scenario, error_handling, semantic
-- **message**: Description of the issue
-- **suggestion**: How to fix it
-`
-  }
-];
-registerDocBlocks(tech_llm_integration_DocBlocks);
-export {
-  tech_llm_integration_DocBlocks
-};

package/dist/docs/tech/mcp-endpoints.docblock.d.ts

@@ -1,3 +0,0 @@
-import type { DocBlock } from '@contractspec/lib.contracts/docs';
-export declare const tech_mcp_endpoints_DocBlocks: DocBlock[];
-//# sourceMappingURL=mcp-endpoints.docblock.d.ts.map

package/dist/docs/tech/mcp-endpoints.docblock.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"mcp-endpoints.docblock.d.ts","sourceRoot":"","sources":["../../../src/docs/tech/mcp-endpoints.docblock.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AAGjE,eAAO,MAAM,4BAA4B,EAAE,QAAQ,EAiClD,CAAC"}

package/dist/docs/tech/mcp-endpoints.docblock.js

@@ -1,185 +0,0 @@
-// @bun
-var __defProp = Object.defineProperty;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __moduleCache = /* @__PURE__ */ new WeakMap;
-var __toCommonJS = (from) => {
-  var entry = __moduleCache.get(from), desc;
-  if (entry)
-    return entry;
-  entry = __defProp({}, "__esModule", { value: true });
-  if (from && typeof from === "object" || typeof from === "function")
-    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
-      get: () => from[key],
-      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-    }));
-  __moduleCache.set(from, entry);
-  return entry;
-};
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, {
-      get: all[name],
-      enumerable: true,
-      configurable: true,
-      set: (newValue) => all[name] = () => newValue
-    });
-};
-var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
-var __require = import.meta.require;
-
-// src/docs/presentations.ts
-var DEFAULT_TARGETS = [
-  "markdown",
-  "react"
-];
-function normalizeRoute(route) {
-  if (!route.length)
-    return "/";
-  const withLeading = route.startsWith("/") ? route : `/${route}`;
-  return withLeading === "/" ? "/" : withLeading.replace(/\/+$/, "");
-}
-function deriveRoute(block, routePrefix) {
-  if (block.route)
-    return normalizeRoute(block.route);
-  const prefix = routePrefix ?? "/docs";
-  const slug = block.id.replace(/^docs\.?/, "").replace(/\./g, "/").replace(/\/+/g, "/");
-  const path = slug.startsWith("/") ? slug : `${prefix}/${slug}`;
-  return normalizeRoute(path);
-}
-function buildName(block, namespace) {
-  return namespace ? `${namespace}.${block.id}` : block.id;
-}
-function docBlockToPresentationSpec(block, options) {
-  const targets = options?.defaultTargets ?? DEFAULT_TARGETS;
-  const version = block.version ?? options?.defaultVersion ?? "1.0.0";
-  const stability = block.stability ?? options?.defaultStability ?? "stable";
-  return {
-    meta: {
-      key: buildName(block, options?.namespace),
-      title: block.title,
-      version,
-      description: block.summary ?? block.title,
-      tags: block.tags || [],
-      owners: block.owners || [],
-      domain: block.domain || "",
-      stability,
-      goal: `Documentation of: ${block.summary}`,
-      context: `Auto-generated`
-    },
-    policy: block.visibility && block.visibility !== "public" ? { flags: [block.visibility] } : undefined,
-    source: {
-      type: "blocknotejs",
-      docJson: block.body
-    },
-    targets
-  };
-}
-function docBlocksToPresentationRoutes(blocks, options) {
-  return blocks.map((block) => ({
-    block,
-    route: deriveRoute(block, options?.routePrefix),
-    descriptor: docBlockToPresentationSpec(block, options)
-  }));
-}
-function docBlocksToPresentationSpecs(blocks, options) {
-  return blocks.map((block) => docBlockToPresentationSpec(block, options));
-}
-function mapDocRoutes(routes) {
-  return routes.map(({ route, descriptor }) => [route, descriptor]);
-}
-
-// src/docs/registry.ts
-class DocRegistry {
-  routes = new Map;
-  constructor(blocks = [], options) {
-    blocks.forEach((block) => this.register(block, options));
-  }
-  register(block, options) {
-    const [route] = docBlocksToPresentationRoutes([block], options);
-    if (route) {
-      this.routes.set(block.id, route);
-    }
-    return this;
-  }
-  list() {
-    return [...this.routes.values()];
-  }
-  get(id) {
-    return this.routes.get(id);
-  }
-  toRouteTuples() {
-    return this.list().map(({ route, descriptor }) => [route, descriptor]);
-  }
-  toPresentationSpecs(options) {
-    return this.list().map(({ block }) => docBlockToPresentationSpec(block, options));
-  }
-}
-var requiredFields = [
-  "id",
-  "title",
-  "body",
-  "kind",
-  "visibility",
-  "route"
-];
-var defaultDocRegistry = new DocRegistry;
-function registerDocBlocks(blocks) {
-  for (const block of blocks) {
-    for (const field of requiredFields) {
-      if (!block[field]) {
-        throw new Error(`DocBlock ${block.id ?? "<missing id>"} missing field ${String(field)}`);
-      }
-    }
-    defaultDocRegistry.register(block);
-  }
-}
-function listRegisteredDocBlocks() {
-  return defaultDocRegistry.list().map((r) => r.block);
-}
-function docId(id) {
-  const found = defaultDocRegistry.get(id);
-  if (!found)
-    throw new Error(`DocBlock not registered: ${id}`);
-  return id;
-}
-
-// src/docs/tech/mcp-endpoints.docblock.ts
-var tech_mcp_endpoints_DocBlocks = [
-  {
-    id: "docs.tech.mcp.endpoints",
-    title: "ContractSpec MCP endpoints",
-    summary: "Dedicated MCP servers for docs, CLI usage, and internal development.",
-    kind: "reference",
-    visibility: "mixed",
-    route: "/docs/tech/mcp/endpoints",
-    tags: ["mcp", "docs", "cli", "internal"],
-    body: `# ContractSpec MCP endpoints
-
-Three dedicated MCP servers keep AI agents efficient and scoped:
-
-- **Docs MCP**: \`/api/mcp/docs\` \u2014 exposes DocBlocks as resources + presentations. Tool: \`docs.search\`.
-- **CLI MCP**: \`/api/mcp/cli\` \u2014 surfaces CLI quickstart/reference/README and suggests commands. Tool: \`cli.suggestCommand\`.
-- **Internal MCP**: \`/api/mcp/internal\` \u2014 internal routing hints, playbook, and example registry access. Tool: \`internal.describe\`.
-
-### Usage notes
-- Transports are HTTP POST (streamable HTTP); SSE is disabled.
-- Resources are namespaced (\`docs://*\`, \`cli://*\`, \`internal://*\`) and are read-only.
-- Internal MCP also exposes the examples registry via \`examples://*\` resources:
-  - \`examples://list?q=<query>\`
-  - \`examples://example/<id>\`
-- Prompts mirror each surface (navigator, usage, bootstrap) for quick agent onboarding.
-- GraphQL remains at \`/graphql\`; health at \`/health\`.
-
-### Alpic hosting
-- Alpic exposes MCP at \`/\` (SSE + Streamable HTTP) and \`/mcp\` (Streamable HTTP).
-- Static UI assets are served at \`/assets\` from repo \`/assets\` or build output \`dist/assets\`.
-- Use the \`ALPIC_HOST\` environment variable to build absolute asset URLs.
-`
-  }
-];
-registerDocBlocks(tech_mcp_endpoints_DocBlocks);
-export {
-  tech_mcp_endpoints_DocBlocks
-};

package/dist/docs/tech/presentation-runtime.docblock.d.ts

@@ -1,3 +0,0 @@
-import type { DocBlock } from '@contractspec/lib.contracts/docs';
-export declare const tech_presentation_runtime_DocBlocks: DocBlock[];
-//# sourceMappingURL=presentation-runtime.docblock.d.ts.map

package/dist/docs/tech/presentation-runtime.docblock.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"presentation-runtime.docblock.d.ts","sourceRoot":"","sources":["../../../src/docs/tech/presentation-runtime.docblock.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AAGjE,eAAO,MAAM,mCAAmC,EAAE,QAAQ,EAWzD,CAAC"}