@lssm/lib.contracts 0.0.0-canary-20251217063201 → 0.0.0-canary-20251217072406

package/dist/llm/prompts.js

@@ -1,4 +1,11 @@
-import{specToAgentPrompt as e,specToFullMarkdown as t}from"./exporters.js";const n={"claude-code":`You are an expert TypeScript developer working with ContractSpec, a spec-first development framework.
+import { specToAgentPrompt, specToFullMarkdown } 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\`)
@@ -14,7 +21,8 @@ When implementing specs:
 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.
+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
@@ -29,7 +37,8 @@ When working with specs:
 - 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.
+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
@@ -39,14 +48,23 @@ ContractSpec specs define:
 - 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.`};function r(r,i,a){let o=n[i],s=t(r),c;return c=i===`claude-code`?`## Implementation Task
+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 = specToFullMarkdown(spec);
+	let taskPrompt;
+	if (agent === "claude-code") taskPrompt = `## Implementation Task
 
 Implement the following ContractSpec operation:
 
-${s}
+${specMarkdown}
 
-${a?.targetPath?`**Target file:** \`${a.targetPath}\`\n`:``}
-${a?.existingCode?`**Existing code to modify:**\n\`\`\`typescript\n${a.existingCode}\n\`\`\`\n`:``}
+${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
@@ -55,25 +73,42 @@ Generate a complete, production-ready TypeScript implementation that:
 4. Emits events as specified
 5. Includes JSDoc documentation
 
-Provide ONLY the TypeScript code.`:i===`cursor-cli`?`Implement this ContractSpec operation.
+Provide ONLY the TypeScript code.`;
+	else if (agent === "cursor-cli") taskPrompt = `Implement this ContractSpec operation.
 
-${s}
+${specMarkdown}
 
-${a?.targetPath?`Target: ${a.targetPath}\n`:``}
+${options?.targetPath ? `Target: ${options.targetPath}\n` : ""}
 
 Requirements:
 - TypeScript with strict types
 - Handle all error cases
 - Emit specified events
-- Follow acceptance scenarios`:e(r,{taskType:`implement`,existingCode:a?.existingCode}),{agent:i,systemPrompt:o,taskPrompt:c}}function i(e,r,i){let a=i?.testFramework??`vitest`,o=`## Test Generation Task
+- Follow acceptance scenarios`;
+	else taskPrompt = specToAgentPrompt(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:
 
-${t(e)}
+${specToFullMarkdown(spec)}
 
-${i?.implementationCode?`**Implementation:**\n\`\`\`typescript\n${i.implementationCode}\n\`\`\`\n`:``}
+${options?.implementationCode ? `**Implementation:**\n\`\`\`typescript\n${options.implementationCode}\n\`\`\`\n` : ""}
 
-**Test Framework:** ${a}
+**Test Framework:** ${framework}
 
 Generate tests that:
 1. Cover all acceptance scenarios from the spec
@@ -84,16 +119,27 @@ Generate tests that:
 
 Use descriptive test names: "should [behavior] when [condition]"
 
-Provide a complete test file.`;return{agent:r,systemPrompt:n[r],taskPrompt:o}}function a(e,r,i){let a=`## Code Review Task
+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:**
-${t(e)}
+${specToFullMarkdown(spec)}
 
 **Implementation:**
 \`\`\`typescript
-${i}
+${implementationCode}
 \`\`\`
 
 Provide a structured review:
@@ -111,16 +157,29 @@ 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:r,systemPrompt:n[r],taskPrompt:a}}function o(e,n){return{agent:`generic-mcp`,taskPrompt:`## Semantic Verification Task
+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:**
-${t(e)}
+${specToFullMarkdown(spec)}
 
 **Implementation:**
 \`\`\`typescript
-${n}
+${implementationCode}
 \`\`\`
 
 Analyze and respond with JSON:
@@ -144,77 +203,208 @@ Analyze and respond with JSON:
   ],
   "summary": "Brief summary of verification results"
 }
-\`\`\``}}function s(e,n){let r=e.meta,i=[],a=n?.projectRoot??`src`,o=r.name.replace(/\./g,`/`);(r.kind===`command`||r.kind===`query`)&&i.push({path:`${a}/${o}/handler.ts`,purpose:`Main handler implementation`,type:`create`},{path:`${a}/${o}/types.ts`,purpose:`Type definitions`,type:`create`},{path:`${a}/${o}/handler.test.ts`,purpose:`Handler tests`,type:`create`});let s=[],c=1;s.push({order:c++,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`]}),s.push({order:c++,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`]}),s.push({order:c++,title:`Implement Core Logic`,description:`Implement the main business logic of the operation`,acceptanceCriteria:e.acceptance?.scenarios?.map(e=>e.name)??[`Operation completes successfully for valid input`]}),e.io.errors&&Object.keys(e.io.errors).length>0&&s.push({order:c++,title:`Implement Error Handling`,description:`Handle all defined error cases`,acceptanceCriteria:Object.entries(e.io.errors).map(([e,t])=>`Handle ${e}: ${t.when}`)}),e.sideEffects?.emits?.length&&s.push({order:c++,title:`Implement Event Emission`,description:`Emit events as specified`,acceptanceCriteria:e.sideEffects.emits.map(e=>`ref`in e?`Emit ${e.ref.name}.v${e.ref.version} when ${e.when}`:`Emit ${e.name}.v${e.version} when ${e.when}`)}),s.push({order:c++,title:`Write Tests`,description:`Create comprehensive test suite`,acceptanceCriteria:[`All acceptance scenarios covered`,`All error cases tested`,`Edge cases handled`,`Events verified`]});let l={policy:[],security:[],pii:[]};return l.policy.push(`Auth level: ${e.policy.auth}`),e.policy.idempotent!==void 0&&l.policy.push(`Idempotent: ${e.policy.idempotent}`),e.policy.rateLimit&&l.policy.push(`Rate limit: ${e.policy.rateLimit.rpm} rpm per ${e.policy.rateLimit.key}`),e.policy.flags?.length&&l.policy.push(`Feature flags required: ${e.policy.flags.join(`, `)}`),e.policy.escalate&&l.security.push(`Escalation required: ${e.policy.escalate}`),e.policy.pii?.length&&(l.pii=e.policy.pii),{target:{type:`spec`,name:r.name,version:r.version},context:{goal:r.goal,description:r.description,background:r.context},specMarkdown:t(e),fileStructure:i,steps:s,constraints:l,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`]}}function c(e,t){let r;return r=t===`claude-code`?`## Implementation Plan: ${e.target.name}.v${e.target.version}
+\`\`\``
+	};
+}
+/**
+* Generate a feature implementation plan.
+*/
+function generateImplementationPlan(spec, options) {
+	const m = spec.meta;
+	const fileStructure = [];
+	const basePath = options?.projectRoot ?? "src";
+	const specPath = m.name.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.name) ?? ["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.name}.v${e.ref.version} when ${e.when}`;
+			return `Emit ${e.name}.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",
+			name: m.name,
+			version: m.version
+		},
+		context: {
+			goal: m.goal,
+			description: m.description,
+			background: m.context
+		},
+		specMarkdown: specToFullMarkdown(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.name}.v${plan.target.version}
 
 ### Context
-**Goal:** ${e.context.goal}
+**Goal:** ${plan.context.goal}
 
-**Background:** ${e.context.background}
+**Background:** ${plan.context.background}
 
 ### Specification
-${e.specMarkdown}
+${plan.specMarkdown}
 
 ### File Structure
-${e.fileStructure.map(e=>`- \`${e.path}\` (${e.type}): ${e.purpose}`).join(`
-`)}
+${plan.fileStructure.map((f) => `- \`${f.path}\` (${f.type}): ${f.purpose}`).join("\n")}
 
 ### Implementation Steps
-${e.steps.map(e=>`
-#### Step ${e.order}: ${e.title}
-${e.description}
+${plan.steps.map((s) => `
+#### Step ${s.order}: ${s.title}
+${s.description}
 
 **Acceptance Criteria:**
-${e.acceptanceCriteria.map(e=>`- [ ] ${e}`).join(`
-`)}
-`).join(`
-`)}
+${s.acceptanceCriteria.map((c) => `- [ ] ${c}`).join("\n")}
+`).join("\n")}
 
 ### Constraints
-${e.constraints.policy.length?`**Policy:**\n${e.constraints.policy.map(e=>`- ${e}`).join(`
-`)}\n`:``}
-${e.constraints.security.length?`**Security:**\n${e.constraints.security.map(e=>`- ${e}`).join(`
-`)}\n`:``}
-${e.constraints.pii.length?`**PII Handling:**\n${e.constraints.pii.map(e=>`- ${e}`).join(`
-`)}\n`:``}
+${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
-${e.verificationChecklist.map(e=>`- [ ] ${e}`).join(`
-`)}
+${plan.verificationChecklist.map((c) => `- [ ] ${c}`).join("\n")}
 
-Implement this plan step by step.`:t===`cursor-cli`?`# ${e.target.name}.v${e.target.version}
+Implement this plan step by step.`;
+	else if (agent === "cursor-cli") taskPrompt = `# ${plan.target.name}.v${plan.target.version}
 
-${e.context.goal}
+${plan.context.goal}
 
 ## Spec
-${e.specMarkdown}
+${plan.specMarkdown}
 
 ## Files to create
-${e.fileStructure.map(e=>`${e.type}: ${e.path}`).join(`
-`)}
+${plan.fileStructure.map((f) => `${f.type}: ${f.path}`).join("\n")}
 
 ## Steps
-${e.steps.map(e=>`${e.order}. ${e.title}`).join(`
-`)}`:`Implementation plan for ${e.target.name}.v${e.target.version}
+${plan.steps.map((s) => `${s.order}. ${s.title}`).join("\n")}`;
+	else taskPrompt = `Implementation plan for ${plan.target.name}.v${plan.target.version}
 
-${e.specMarkdown}
+${plan.specMarkdown}
 
 Steps:
-${e.steps.map(e=>`${e.order}. ${e.title}: ${e.description}`).join(`
-`)}`,{agent:t,systemPrompt:n[t],taskPrompt:r}}function l(e,n,r){return{agent:`generic-mcp`,taskPrompt:`## Fix Specification Violations
+${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:**
-${t(e)}
+${specToFullMarkdown(spec)}
 
 **Current Implementation:**
 \`\`\`typescript
-${n}
+${implementationCode}
 \`\`\`
 
 **Violations Found:**
-${r.map((e,t)=>`${t+1}. ${e.message}${e.suggestion?`\n   Suggestion: ${e.suggestion}`:``}`).join(`
-`)}
+${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.`}}export{n as AGENT_SYSTEM_PROMPTS,c as formatPlanForAgent,l as generateFixViolationsPrompt,s as generateImplementationPlan,r as generateImplementationPrompt,a as generateReviewPrompt,i as generateTestPrompt,o as generateVerificationPrompt};
+Provide the corrected implementation.`
+	};
+}
+
+//#endregion
+export { AGENT_SYSTEM_PROMPTS, formatPlanForAgent, generateFixViolationsPrompt, generateImplementationPlan, generateImplementationPrompt, generateReviewPrompt, generateTestPrompt, generateVerificationPrompt };

package/dist/markdown.js

@@ -1,3 +1,116 @@
-import{isEmitDeclRef as e}from"./spec.js";function t(t,n){let r=[];for(let n of t.listSpecs()){let t=n.meta;if(r.push(`# ${t.name}.v${t.version}`),r.push(``),r.push(`**Kind:** ${t.kind} | **Stability:** ${t.stability} | **Owners:** ${t.owners.join(`, `)}`),r.push(``),r.push(`**Description:** ${t.description}`),r.push(``),r.push(`## Goal`),r.push(t.goal),r.push(``),r.push(`## Context`),r.push(t.context),r.push(``),r.push(`## Policy`),r.push(`- Auth: ${n.policy.auth}`),r.push(`- Idempotent: ${!!n.policy.idempotent}`),n.policy.rateLimit&&r.push(`- Rate Limit: ${n.policy.rateLimit.rpm}/min by ${n.policy.rateLimit.key}`),n.policy.flags?.length&&r.push(`- Flags: ${n.policy.flags.join(`, `)}`),n.policy.pii?.length&&r.push(`- PII: ${n.policy.pii.join(`, `)}`),r.push(``),n.sideEffects?.emits?.length){r.push(`## Emits Events`);for(let t of n.sideEffects.emits)e(t)?r.push(`- \`${t.ref.name}.v${t.ref.version}\` — ${t.when}`):r.push(`- \`${t.name}.v${t.version}\` — ${t.when}`);r.push(``)}if(n.io.errors&&Object.keys(n.io.errors).length){r.push(`## Errors`);for(let[e,t]of Object.entries(n.io.errors))r.push(`- \`${e}\` (${t.http??400}) — ${t.description} (when: ${t.when})`);r.push(``)}if(n.acceptance?.scenarios?.length){r.push(`## Acceptance Scenarios`);for(let e of n.acceptance.scenarios)r.push(`### ${e.name}`),r.push(`- **Given:** ${e.given.join(`; `)}`),r.push(`- **When:** ${e.when.join(`; `)}`),r.push(`- **Then:** ${e.then.join(`; `)}`),r.push(``)}if(n.acceptance?.examples?.length){r.push(`## Examples`);for(let e of n.acceptance.examples)r.push(`- **${e.name}**`),r.push(`  - Input:`),r.push("    ```json"),r.push(JSON.stringify(e.input,null,2)),r.push("    ```"),r.push(`  - Output:`),r.push("    ```json"),r.push(JSON.stringify(e.output,null,2)),r.push("    ```"),r.push(``)}r.push(`---`),r.push(``)}return r.join(`
-`)}function n(e,n){let r=[];if(r.push(t(e,n)),n.presentations){r.push(`# Presentations`),r.push(``);for(let e of n.presentations.list())r.push(`## ${e.meta.name}.v${e.meta.version}`),r.push(``),r.push(`- Kind: ${e.content.kind}`),`framework`in e.content&&r.push(`- Framework: ${e.content.framework}`),`componentKey`in e.content&&r.push(`- Component Key: ${e.content.componentKey}`),`mimeType`in e.content&&r.push(`- MIME Type: ${e.content.mimeType}`),r.push(``);r.push(``)}if(n.features){r.push(`# Features`),r.push(``);for(let e of n.features.list()){if(r.push(`## ${e.meta.title} (${e.meta.key})`),e.meta.description&&r.push(e.meta.description),r.push(``),e.operations?.length){r.push(`- Operations:`);for(let t of e.operations)r.push(`  - ${t.name}.v${t.version}`)}if(e.events?.length){r.push(`- Events:`);for(let t of e.events)r.push(`  - ${t.name}.v${t.version}`)}if(e.presentations?.length){r.push(`- Presentations:`);for(let t of e.presentations)r.push(`  - ${t.name}.v${t.version}`)}r.push(``)}}return r.join(`
-`)}export{n as docsToMarkdown,t as specsToMarkdown};
+import { isEmitDeclRef } from "./spec.js";
+
+//#region src/markdown.ts
+/**
+* Render simple Markdown docs for each spec.
+* Useful for dev portals and repo docs generation.
+*/
+function specsToMarkdown(reg, extras) {
+	const lines = [];
+	for (const spec of reg.listSpecs()) {
+		const m = spec.meta;
+		lines.push(`# ${m.name}.v${m.version}`);
+		lines.push("");
+		lines.push(`**Kind:** ${m.kind} | **Stability:** ${m.stability} | **Owners:** ${m.owners.join(", ")}`);
+		lines.push("");
+		lines.push(`**Description:** ${m.description}`);
+		lines.push("");
+		lines.push(`## Goal`);
+		lines.push(m.goal);
+		lines.push("");
+		lines.push(`## Context`);
+		lines.push(m.context);
+		lines.push("");
+		lines.push(`## Policy`);
+		lines.push(`- Auth: ${spec.policy.auth}`);
+		lines.push(`- Idempotent: ${!!spec.policy.idempotent}`);
+		if (spec.policy.rateLimit) lines.push(`- Rate Limit: ${spec.policy.rateLimit.rpm}/min by ${spec.policy.rateLimit.key}`);
+		if (spec.policy.flags?.length) lines.push(`- Flags: ${spec.policy.flags.join(", ")}`);
+		if (spec.policy.pii?.length) lines.push(`- PII: ${spec.policy.pii.join(", ")}`);
+		lines.push("");
+		if (spec.sideEffects?.emits?.length) {
+			lines.push(`## Emits Events`);
+			for (const e of spec.sideEffects.emits) if (isEmitDeclRef(e)) lines.push(`- \`${e.ref.name}.v${e.ref.version}\` — ${e.when}`);
+			else lines.push(`- \`${e.name}.v${e.version}\` — ${e.when}`);
+			lines.push("");
+		}
+		if (spec.io.errors && Object.keys(spec.io.errors).length) {
+			lines.push(`## Errors`);
+			for (const [code, err] of Object.entries(spec.io.errors)) lines.push(`- \`${code}\` (${err.http ?? 400}) — ${err.description} (when: ${err.when})`);
+			lines.push("");
+		}
+		if (spec.acceptance?.scenarios?.length) {
+			lines.push(`## Acceptance Scenarios`);
+			for (const s of spec.acceptance.scenarios) {
+				lines.push(`### ${s.name}`);
+				lines.push(`- **Given:** ${s.given.join("; ")}`);
+				lines.push(`- **When:** ${s.when.join("; ")}`);
+				lines.push(`- **Then:** ${s.then.join("; ")}`);
+				lines.push("");
+			}
+		}
+		if (spec.acceptance?.examples?.length) {
+			lines.push(`## Examples`);
+			for (const ex of spec.acceptance.examples) {
+				lines.push(`- **${ex.name}**`);
+				lines.push("  - Input:");
+				lines.push("    ```json");
+				lines.push(JSON.stringify(ex.input, null, 2));
+				lines.push("    ```");
+				lines.push("  - Output:");
+				lines.push("    ```json");
+				lines.push(JSON.stringify(ex.output, null, 2));
+				lines.push("    ```");
+				lines.push("");
+			}
+		}
+		lines.push("---");
+		lines.push("");
+	}
+	return lines.join("\n");
+}
+/** Render presentations and features as additional sections. */
+function docsToMarkdown(reg, extras) {
+	const parts = [];
+	parts.push(specsToMarkdown(reg, extras));
+	if (extras.presentations) {
+		parts.push("# Presentations");
+		parts.push("");
+		for (const p of extras.presentations.list()) {
+			parts.push(`## ${p.meta.name}.v${p.meta.version}`);
+			parts.push("");
+			parts.push(`- Kind: ${p.content.kind}`);
+			if ("framework" in p.content) parts.push(`- Framework: ${p.content.framework}`);
+			if ("componentKey" in p.content) parts.push(`- Component Key: ${p.content.componentKey}`);
+			if ("mimeType" in p.content) parts.push(`- MIME Type: ${p.content.mimeType}`);
+			parts.push("");
+		}
+		parts.push("");
+	}
+	if (extras.features) {
+		parts.push("# Features");
+		parts.push("");
+		for (const f of extras.features.list()) {
+			parts.push(`## ${f.meta.title} (${f.meta.key})`);
+			if (f.meta.description) parts.push(f.meta.description);
+			parts.push("");
+			if (f.operations?.length) {
+				parts.push("- Operations:");
+				for (const o of f.operations) parts.push(`  - ${o.name}.v${o.version}`);
+			}
+			if (f.events?.length) {
+				parts.push("- Events:");
+				for (const e of f.events) parts.push(`  - ${e.name}.v${e.version}`);
+			}
+			if (f.presentations?.length) {
+				parts.push("- Presentations:");
+				for (const p of f.presentations) parts.push(`  - ${p.name}.v${p.version}`);
+			}
+			parts.push("");
+		}
+	}
+	return parts.join("\n");
+}
+
+//#endregion
+export { docsToMarkdown, specsToMarkdown };

package/dist/migrations.js

@@ -1 +1,33 @@
-const e=(e,t)=>`${e}.v${t}`;var t=class{items=new Map;register(t){let n=e(t.meta.name,t.meta.version);if(this.items.has(n))throw Error(`Duplicate migration ${n}`);return this.items.set(n,t),this}list(){return[...this.items.values()].sort((t,r)=>n(e(t.meta.name,t.meta.version),e(r.meta.name,r.meta.version)))}get(t,n){if(n!=null)return this.items.get(e(t,n));let r,i=-1/0;for(let e of this.items.values())e.meta.name===t&&e.meta.version>i&&(i=e.meta.version,r=e);return r}};function n(e,t){return e<t?-1:e>t?1:0}export{t as MigrationRegistry};
+//#region src/migrations.ts
+const migrationKey = (name, version) => `${name}.v${version}`;
+var MigrationRegistry = class {
+	items = /* @__PURE__ */ new Map();
+	register(spec) {
+		const key = migrationKey(spec.meta.name, spec.meta.version);
+		if (this.items.has(key)) throw new Error(`Duplicate migration ${key}`);
+		this.items.set(key, spec);
+		return this;
+	}
+	list() {
+		return [...this.items.values()].sort((a, b) => compareKey(migrationKey(a.meta.name, a.meta.version), migrationKey(b.meta.name, b.meta.version)));
+	}
+	get(name, version) {
+		if (version != null) return this.items.get(migrationKey(name, version));
+		let candidate;
+		let max = -Infinity;
+		for (const spec of this.items.values()) {
+			if (spec.meta.name !== name) continue;
+			if (spec.meta.version > max) {
+				max = spec.meta.version;
+				candidate = spec;
+			}
+		}
+		return candidate;
+	}
+};
+function compareKey(a, b) {
+	return a < b ? -1 : a > b ? 1 : 0;
+}
+
+//#endregion
+export { MigrationRegistry };