@contractspec/lib.contracts 1.44.0

package/dist/llm/prompts.js

@@ -0,0 +1,410 @@
+import { operationSpecToAgentPrompt, operationSpecToFullMarkdown } from "./exporters.js";
+
+//#region src/llm/prompts.ts
+/**
+* System prompts for different agent types.
+*/
+const AGENT_SYSTEM_PROMPTS = {
+	"claude-code": `You are an expert TypeScript developer working with ContractSpec, a spec-first development framework.
+
+Your code follows these principles:
+- Type-safe with comprehensive TypeScript types (no \`any\`)
+- Well-documented with JSDoc comments
+- Production-ready with proper error handling
+- Following SOLID principles and clean code practices
+- Modular and testable
+
+When implementing specs:
+1. Validate input against the schema before processing
+2. Handle all error cases defined in the spec
+3. Emit events as specified in sideEffects
+4. Respect policy constraints (auth, rate limits, PII handling)
+5. Follow the acceptance scenarios as your implementation guide
+
+Generate clean, idiomatic TypeScript that exactly matches the specification.`,
+	"cursor-cli": `You are implementing features for a ContractSpec-driven codebase.
+
+ContractSpec is a spec-first framework where specifications define:
+- Operations (commands and queries) with typed I/O
+- Events that operations emit
+- Presentations for UI components
+- Features that group related specs
+
+When working with specs:
+- Read the spec carefully before implementing
+- Match the input/output types exactly
+- Implement all error cases
+- Follow the acceptance scenarios
+- Respect policy constraints
+
+Use the project's existing patterns and conventions.`,
+	"generic-mcp": `You are a code generation assistant working with ContractSpec specifications.
+
+ContractSpec specs define:
+- meta: name, version, kind (command/query), description, goal, context
+- io: input schema, output schema, error definitions
+- policy: auth level, rate limits, feature flags, PII handling
+- sideEffects: events to emit, analytics, audit
+- acceptance: scenarios and examples
+
+Your task is to generate or modify code that complies with the given specification.
+Follow the spec exactly and handle all defined cases.`
+};
+/**
+* Generate an implementation prompt for a specific agent type.
+*/
+function generateImplementationPrompt(spec, agent, options) {
+	const systemPrompt = AGENT_SYSTEM_PROMPTS[agent];
+	const specMarkdown = operationSpecToFullMarkdown(spec);
+	let taskPrompt;
+	if (agent === "claude-code") taskPrompt = `## Implementation Task
+
+Implement the following ContractSpec operation:
+
+${specMarkdown}
+
+${options?.targetPath ? `**Target file:** \`${options.targetPath}\`\n` : ""}
+${options?.existingCode ? `**Existing code to modify:**\n\`\`\`typescript\n${options.existingCode}\n\`\`\`\n` : ""}
+
+Generate a complete, production-ready TypeScript implementation that:
+1. Exports a handler function matching the spec signature
+2. Validates input using the schema
+3. Handles all defined error cases
+4. Emits events as specified
+5. Includes JSDoc documentation
+
+Provide ONLY the TypeScript code.`;
+	else if (agent === "cursor-cli") taskPrompt = `Implement this ContractSpec operation.
+
+${specMarkdown}
+
+${options?.targetPath ? `Target: ${options.targetPath}\n` : ""}
+
+Requirements:
+- TypeScript with strict types
+- Handle all error cases
+- Emit specified events
+- Follow acceptance scenarios`;
+	else taskPrompt = operationSpecToAgentPrompt(spec, {
+		taskType: "implement",
+		existingCode: options?.existingCode
+	});
+	return {
+		agent,
+		systemPrompt,
+		taskPrompt
+	};
+}
+/**
+* Generate a test generation prompt.
+*/
+function generateTestPrompt(spec, agent, options) {
+	const framework = options?.testFramework ?? "vitest";
+	const taskPrompt = `## Test Generation Task
+
+Generate comprehensive tests for this specification:
+
+${operationSpecToFullMarkdown(spec)}
+
+${options?.implementationCode ? `**Implementation:**\n\`\`\`typescript\n${options.implementationCode}\n\`\`\`\n` : ""}
+
+**Test Framework:** ${framework}
+
+Generate tests that:
+1. Cover all acceptance scenarios from the spec
+2. Test all defined error cases
+3. Verify input validation
+4. Check event emissions
+5. Test edge cases
+
+Use descriptive test names: "should [behavior] when [condition]"
+
+Provide a complete test file.`;
+	return {
+		agent,
+		systemPrompt: AGENT_SYSTEM_PROMPTS[agent],
+		taskPrompt
+	};
+}
+/**
+* Generate a code review prompt.
+*/
+function generateReviewPrompt(spec, agent, implementationCode) {
+	const taskPrompt = `## Code Review Task
+
+Review this implementation against its specification:
+
+**Specification:**
+${operationSpecToFullMarkdown(spec)}
+
+**Implementation:**
+\`\`\`typescript
+${implementationCode}
+\`\`\`
+
+Provide a structured review:
+
+### Compliance Check
+- [ ] Input types match spec
+- [ ] Output types match spec
+- [ ] All error cases handled
+- [ ] Events emitted correctly
+- [ ] Policy constraints respected
+
+### Issues Found
+List any issues with severity (error/warning/info)
+
+### Suggestions
+List improvements and recommendations
+
+Be thorough and precise. Focus on spec compliance first, then code quality.`;
+	return {
+		agent,
+		systemPrompt: AGENT_SYSTEM_PROMPTS[agent],
+		taskPrompt
+	};
+}
+/**
+* Generate a verification prompt for AI-powered semantic review.
+*/
+function generateVerificationPrompt(spec, implementationCode) {
+	return {
+		agent: "generic-mcp",
+		taskPrompt: `## Semantic Verification Task
+
+Verify that this implementation fulfills the specification's intent.
+
+**Specification:**
+${operationSpecToFullMarkdown(spec)}
+
+**Implementation:**
+\`\`\`typescript
+${implementationCode}
+\`\`\`
+
+Analyze and respond with JSON:
+
+\`\`\`json
+{
+  "passed": true/false,
+  "score": 0-100,
+  "compliance": {
+    "inputTypes": { "match": true/false, "issues": [] },
+    "outputTypes": { "match": true/false, "issues": [] },
+    "errorHandling": { "coverage": "full/partial/none", "missing": [] },
+    "eventEmission": { "correct": true/false, "issues": [] },
+    "policyCompliance": { "auth": true/false, "rateLimit": true/false, "pii": true/false }
+  },
+  "scenarios": [
+    { "name": "scenario name", "covered": true/false, "notes": "" }
+  ],
+  "issues": [
+    { "severity": "error/warning/info", "category": "type/export/import/scenario/error_handling/semantic", "message": "", "suggestion": "" }
+  ],
+  "summary": "Brief summary of verification results"
+}
+\`\`\``
+	};
+}
+/**
+* Generate a feature implementation plan.
+*/
+function generateImplementationPlan(spec, options) {
+	const m = spec.meta;
+	const fileStructure = [];
+	const basePath = options?.projectRoot ?? "src";
+	const specPath = m.key.replace(/\./g, "/");
+	if (m.kind === "command" || m.kind === "query") fileStructure.push({
+		path: `${basePath}/${specPath}/handler.ts`,
+		purpose: "Main handler implementation",
+		type: "create"
+	}, {
+		path: `${basePath}/${specPath}/types.ts`,
+		purpose: "Type definitions",
+		type: "create"
+	}, {
+		path: `${basePath}/${specPath}/handler.test.ts`,
+		purpose: "Handler tests",
+		type: "create"
+	});
+	const steps = [];
+	let order = 1;
+	steps.push({
+		order: order++,
+		title: "Define Types",
+		description: "Create TypeScript types for input, output, and internal data structures",
+		acceptanceCriteria: [
+			"Input type matches spec schema exactly",
+			"Output type matches spec schema exactly",
+			"Error types defined for all error cases"
+		]
+	});
+	steps.push({
+		order: order++,
+		title: "Implement Input Validation",
+		description: "Add validation logic for the input payload",
+		acceptanceCriteria: [
+			"All required fields are validated",
+			"Type constraints are enforced",
+			"Validation errors return appropriate error codes"
+		]
+	});
+	steps.push({
+		order: order++,
+		title: "Implement Core Logic",
+		description: "Implement the main business logic of the operation",
+		acceptanceCriteria: spec.acceptance?.scenarios?.map((s) => s.key) ?? ["Operation completes successfully for valid input"]
+	});
+	if (spec.io.errors && Object.keys(spec.io.errors).length > 0) steps.push({
+		order: order++,
+		title: "Implement Error Handling",
+		description: "Handle all defined error cases",
+		acceptanceCriteria: Object.entries(spec.io.errors).map(([code, err]) => `Handle ${code}: ${err.when}`)
+	});
+	if (spec.sideEffects?.emits?.length) steps.push({
+		order: order++,
+		title: "Implement Event Emission",
+		description: "Emit events as specified",
+		acceptanceCriteria: spec.sideEffects.emits.map((e) => {
+			if ("ref" in e) return `Emit ${e.ref.key}.v${e.ref.version} when ${e.when}`;
+			return `Emit ${e.key}.v${e.version} when ${e.when}`;
+		})
+	});
+	steps.push({
+		order: order++,
+		title: "Write Tests",
+		description: "Create comprehensive test suite",
+		acceptanceCriteria: [
+			"All acceptance scenarios covered",
+			"All error cases tested",
+			"Edge cases handled",
+			"Events verified"
+		]
+	});
+	const constraints = {
+		policy: [],
+		security: [],
+		pii: []
+	};
+	constraints.policy.push(`Auth level: ${spec.policy.auth}`);
+	if (spec.policy.idempotent !== void 0) constraints.policy.push(`Idempotent: ${spec.policy.idempotent}`);
+	if (spec.policy.rateLimit) constraints.policy.push(`Rate limit: ${spec.policy.rateLimit.rpm} rpm per ${spec.policy.rateLimit.key}`);
+	if (spec.policy.flags?.length) constraints.policy.push(`Feature flags required: ${spec.policy.flags.join(", ")}`);
+	if (spec.policy.escalate) constraints.security.push(`Escalation required: ${spec.policy.escalate}`);
+	if (spec.policy.pii?.length) constraints.pii = spec.policy.pii;
+	return {
+		target: {
+			type: "spec",
+			key: m.key,
+			version: m.version
+		},
+		context: {
+			goal: m.goal,
+			description: m.description,
+			background: m.context
+		},
+		specMarkdown: operationSpecToFullMarkdown(spec),
+		fileStructure,
+		steps,
+		constraints,
+		verificationChecklist: [
+			"Input validation works for all cases",
+			"Output matches expected schema",
+			"All error cases return correct codes",
+			"Events are emitted with correct payloads",
+			"Auth requirements are enforced",
+			"Rate limiting is applied (if applicable)",
+			"PII fields are handled correctly",
+			"All acceptance scenarios pass",
+			"Tests provide adequate coverage"
+		]
+	};
+}
+/**
+* Format an implementation plan for a specific agent.
+*/
+function formatPlanForAgent(plan, agent) {
+	let taskPrompt;
+	if (agent === "claude-code") taskPrompt = `## Implementation Plan: ${plan.target.key}.v${plan.target.version}
+
+### Context
+**Goal:** ${plan.context.goal}
+
+**Background:** ${plan.context.background}
+
+### Specification
+${plan.specMarkdown}
+
+### File Structure
+${plan.fileStructure.map((f) => `- \`${f.path}\` (${f.type}): ${f.purpose}`).join("\n")}
+
+### Implementation Steps
+${plan.steps.map((s) => `
+#### Step ${s.order}: ${s.title}
+${s.description}
+
+**Acceptance Criteria:**
+${s.acceptanceCriteria.map((c) => `- [ ] ${c}`).join("\n")}
+`).join("\n")}
+
+### Constraints
+${plan.constraints.policy.length ? `**Policy:**\n${plan.constraints.policy.map((p) => `- ${p}`).join("\n")}\n` : ""}
+${plan.constraints.security.length ? `**Security:**\n${plan.constraints.security.map((s) => `- ${s}`).join("\n")}\n` : ""}
+${plan.constraints.pii.length ? `**PII Handling:**\n${plan.constraints.pii.map((p) => `- ${p}`).join("\n")}\n` : ""}
+
+### Verification Checklist
+${plan.verificationChecklist.map((c) => `- [ ] ${c}`).join("\n")}
+
+Implement this plan step by step.`;
+	else if (agent === "cursor-cli") taskPrompt = `# ${plan.target.key}.v${plan.target.version}
+
+${plan.context.goal}
+
+## Spec
+${plan.specMarkdown}
+
+## Files to create
+${plan.fileStructure.map((f) => `${f.type}: ${f.path}`).join("\n")}
+
+## Steps
+${plan.steps.map((s) => `${s.order}. ${s.title}`).join("\n")}`;
+	else taskPrompt = `Implementation plan for ${plan.target.key}.v${plan.target.version}
+
+${plan.specMarkdown}
+
+Steps:
+${plan.steps.map((s) => `${s.order}. ${s.title}: ${s.description}`).join("\n")}`;
+	return {
+		agent,
+		systemPrompt: AGENT_SYSTEM_PROMPTS[agent],
+		taskPrompt
+	};
+}
+/**
+* Generate a fix violations prompt after verification.
+*/
+function generateFixViolationsPrompt(spec, implementationCode, violations) {
+	return {
+		agent: "generic-mcp",
+		taskPrompt: `## Fix Specification Violations
+
+The following implementation has violations against its specification:
+
+**Specification:**
+${operationSpecToFullMarkdown(spec)}
+
+**Current Implementation:**
+\`\`\`typescript
+${implementationCode}
+\`\`\`
+
+**Violations Found:**
+${violations.map((v, i) => `${i + 1}. ${v.message}${v.suggestion ? `\n   Suggestion: ${v.suggestion}` : ""}`).join("\n")}
+
+Fix ALL violations while maintaining existing functionality.
+Provide the corrected implementation.`
+	};
+}
+
+//#endregion
+export { AGENT_SYSTEM_PROMPTS, formatPlanForAgent, generateFixViolationsPrompt, generateImplementationPlan, generateImplementationPrompt, generateReviewPrompt, generateTestPrompt, generateVerificationPrompt };

package/dist/llm/types.d.ts

@@ -0,0 +1,215 @@
+import { DocBlock } from "../docs/types.js";
+import { PresentationSpec } from "../presentations/presentations.js";
+import { EventSpec } from "../events.js";
+import { AnyOperationSpec } from "../operations/operation.js";
+import "../operations/index.js";
+import { FeatureModuleSpec } from "../features/types.js";
+import "../features/index.js";
+import { AnySchemaModel } from "@contractspec/lib.schema";
+
+//#region src/llm/types.d.ts
+
+/** Supported export formats for LLM consumption */
+type LLMExportFormat = 'context' | 'full' | 'prompt';
+/** Supported agent types for implementation guidance */
+type AgentType = 'claude-code' | 'cursor-cli' | 'generic-mcp';
+/** Verification tiers */
+type VerificationTier = 'structure' | 'behavior' | 'ai_review';
+/** Options for exporting specs to markdown */
+interface SpecExportOptions {
+  /** Export format: context (summary), full (all details), prompt (actionable) */
+  format: LLMExportFormat;
+  /** Include JSON Schema for I/O types */
+  includeSchemas?: boolean;
+  /** Include acceptance scenarios */
+  includeScenarios?: boolean;
+  /** Include examples */
+  includeExamples?: boolean;
+  /** Include policy details */
+  includePolicy?: boolean;
+  /** Include side effects (events, analytics) */
+  includeSideEffects?: boolean;
+}
+/** Options for exporting features to markdown */
+interface FeatureExportOptions extends SpecExportOptions {
+  /** Include related specs inline */
+  includeRelatedSpecs?: boolean;
+  /** Include related events inline */
+  includeRelatedEvents?: boolean;
+  /** Include related presentations inline */
+  includeRelatedPresentations?: boolean;
+}
+/** Result of spec export */
+interface SpecExportResult {
+  /** The spec that was exported */
+  spec: AnyOperationSpec;
+  /** Generated markdown content */
+  markdown: string;
+  /** Export format used */
+  format: LLMExportFormat;
+  /** Metadata about the export */
+  meta: {
+    specName: string;
+    specVersion: number;
+    exportedAt: string;
+    wordCount: number;
+  };
+}
+/** Result of feature export */
+interface FeatureExportResult {
+  /** The feature that was exported */
+  feature: FeatureModuleSpec;
+  /** Generated markdown content */
+  markdown: string;
+  /** Export format used */
+  format: LLMExportFormat;
+  /** Included specs */
+  includedSpecs: string[];
+  /** Included events */
+  includedEvents: string[];
+  /** Included presentations */
+  includedPresentations: string[];
+}
+/** Implementation plan generated for agents */
+interface ImplementationPlan {
+  /** Feature/spec being implemented */
+  target: {
+    type: 'spec' | 'feature' | 'presentation';
+    key: string;
+    version: number;
+  };
+  /** Context section */
+  context: {
+    goal: string;
+    description: string;
+    background: string;
+  };
+  /** Full spec markdown */
+  specMarkdown: string;
+  /** Suggested file structure */
+  fileStructure: {
+    path: string;
+    purpose: string;
+    type: 'create' | 'modify';
+  }[];
+  /** Ordered implementation steps */
+  steps: {
+    order: number;
+    title: string;
+    description: string;
+    acceptanceCriteria: string[];
+  }[];
+  /** Constraints to follow */
+  constraints: {
+    policy: string[];
+    security: string[];
+    pii: string[];
+  };
+  /** Verification checklist */
+  verificationChecklist: string[];
+}
+/** Verification issue found during implementation check */
+interface VerificationIssue {
+  /** Issue severity */
+  severity: 'error' | 'warning' | 'info';
+  /** Issue category */
+  category: 'type' | 'export' | 'import' | 'scenario' | 'example' | 'error_handling' | 'semantic';
+  /** Issue message */
+  message: string;
+  /** Location in code if applicable */
+  location?: {
+    file?: string;
+    line?: number;
+    column?: number;
+  };
+  /** Suggested fix */
+  suggestion?: string;
+}
+/** Result of implementation verification */
+interface VerificationReport {
+  /** Verification tier that was run */
+  tier: VerificationTier;
+  /** Overall pass/fail */
+  passed: boolean;
+  /** Score from 0-100 */
+  score: number;
+  /** Issues found */
+  issues: VerificationIssue[];
+  /** Suggestions for improvement */
+  suggestions: string[];
+  /** Coverage metrics */
+  coverage: {
+    scenarios: {
+      total: number;
+      covered: number;
+    };
+    errors: {
+      total: number;
+      handled: number;
+    };
+    fields: {
+      total: number;
+      implemented: number;
+    };
+  };
+  /** Metadata about the verification */
+  meta: {
+    specName: string;
+    specVersion: number;
+    implementationPath: string;
+    verifiedAt: string;
+    duration: number;
+  };
+}
+/** Agent-specific prompt format */
+interface AgentPrompt {
+  /** Agent type this prompt is for */
+  agent: AgentType;
+  /** System prompt (if applicable) */
+  systemPrompt?: string;
+  /** User/task prompt */
+  taskPrompt: string;
+  /** Additional context resources */
+  resources?: {
+    uri: string;
+    title: string;
+    mimeType: string;
+  }[];
+}
+/** Input for spec lookup */
+interface SpecLookup {
+  name: string;
+  version?: number;
+}
+/** Input for feature lookup */
+interface FeatureLookup {
+  key: string;
+}
+/** Batch export options */
+interface BatchExportOptions extends SpecExportOptions {
+  /** Glob pattern to match spec files */
+  pattern?: string;
+  /** Spec types to include */
+  types?: ('command' | 'query' | 'event' | 'presentation' | 'feature')[];
+  /** Output format */
+  outputFormat?: 'single' | 'per-spec' | 'per-feature';
+}
+/** Exportable item types */
+type ExportableItem = {
+  type: 'spec';
+  item: AnyOperationSpec;
+} | {
+  type: 'feature';
+  item: FeatureModuleSpec;
+} | {
+  type: 'presentation';
+  item: PresentationSpec;
+} | {
+  type: 'event';
+  item: EventSpec<AnySchemaModel>;
+} | {
+  type: 'doc';
+  item: DocBlock;
+};
+//#endregion
+export { AgentPrompt, AgentType, BatchExportOptions, ExportableItem, FeatureExportOptions, FeatureExportResult, FeatureLookup, ImplementationPlan, LLMExportFormat, SpecExportOptions, SpecExportResult, SpecLookup, VerificationIssue, VerificationReport, VerificationTier };

package/dist/markdown.d.ts

@@ -0,0 +1,22 @@
+import { OperationSpecRegistry } from "./operations/registry.js";
+import { FeatureRegistry } from "./features/registry.js";
+import { PresentationRegistry } from "./presentations/registry.js";
+import "./presentations/index.js";
+import "./features/index.js";
+
+//#region src/markdown.d.ts
+/**
+ * Render simple Markdown docs for each spec.
+ * Useful for dev portals and repo docs generation.
+ */
+declare function operationsToMarkdown(registry: OperationSpecRegistry, _extras?: {
+  presentations?: PresentationRegistry;
+  features?: FeatureRegistry;
+}): string;
+/** Render presentations and features as additional sections. */
+declare function docsToMarkdown(reg: OperationSpecRegistry, extras: {
+  presentations?: PresentationRegistry;
+  features?: FeatureRegistry;
+}): string;
+//#endregion
+export { docsToMarkdown, operationsToMarkdown };