@contractspec/lib.contracts-spec 2.0.0

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

@@ -0,0 +1,482 @@
+import { createRequire } from "node:module";
+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 = /* @__PURE__ */ createRequire(import.meta.url);
+
+// 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-spec/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, ✏️ 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-spec |
+| 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/node/docs/tech/mcp-endpoints.docblock.js

@@ -0,0 +1,185 @@
+import { createRequire } from "node:module";
+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 = /* @__PURE__ */ createRequire(import.meta.url);
+
+// 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\` — exposes DocBlocks as resources + presentations. Tool: \`docs.search\`.
+- **CLI MCP**: \`/api/mcp/cli\` — surfaces CLI quickstart/reference/README and suggests commands. Tool: \`cli.suggestCommand\`.
+- **Internal MCP**: \`/api/mcp/internal\` — 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
+};