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

package/dist/llm/exporters.js

@@ -1,8 +1,541 @@
-import{jsonSchemaForSpec as e}from"../jsonschema.js";import{isEmitDeclRef as t}from"../spec.js";const n={format:`full`,includeSchemas:!0,includeScenarios:!0,includeExamples:!0,includePolicy:!0,includeSideEffects:!0},r={...n,includeRelatedSpecs:!0,includeRelatedEvents:!0,includeRelatedPresentations:!0};function i(e){let t=e.meta,n=[];if(n.push(`# ${t.name} (v${t.version})`),n.push(``),n.push(`> ${t.description}`),n.push(``),n.push(`**Type:** ${t.kind} | **Stability:** ${t.stability}`),n.push(``),n.push(`## Goal`),n.push(``),n.push(t.goal),n.push(``),n.push(`## Context`),n.push(``),n.push(t.context),n.push(``),e.acceptance?.scenarios?.length){n.push(`## Acceptance Criteria`),n.push(``);for(let t of e.acceptance.scenarios){n.push(`### ${t.name}`),n.push(``),n.push(`**Given:**`);for(let e of t.given)n.push(`- ${e}`);n.push(``),n.push(`**When:**`);for(let e of t.when)n.push(`- ${e}`);n.push(``),n.push(`**Then:**`);for(let e of t.then)n.push(`- ${e}`);n.push(``)}}return n.join(`
-`)}function a(r,i={}){let a={...n,...i},o=r.meta,s=[];if(s.push(`# ${o.name}.v${o.version}`),s.push(``),s.push(`> ${o.description}`),s.push(``),s.push(`## Metadata`),s.push(``),s.push(`| Field | Value |`),s.push(`|-------|-------|`),s.push(`| Kind | ${o.kind} |`),s.push(`| Stability | ${o.stability} |`),s.push(`| Owners | ${o.owners.join(`, `)} |`),s.push(`| Tags | ${o.tags.join(`, `)} |`),s.push(``),s.push(`## Goal`),s.push(``),s.push(o.goal),s.push(``),s.push(`## Context`),s.push(``),s.push(o.context),s.push(``),a.includeSchemas){if(s.push(`## Input/Output`),s.push(``),r.io.input){s.push(`### Input Schema`),s.push(``),s.push("```json");try{let t=e(r);s.push(JSON.stringify(t.input??{},null,2))}catch{s.push(`// Schema generation not available`)}s.push("```"),s.push(``)}s.push(`### Output Schema`),s.push(``),s.push("```json");try{let t=e(r);s.push(JSON.stringify(t.output??{},null,2))}catch{s.push(`// Schema generation not available`)}if(s.push("```"),s.push(``),r.io.errors&&Object.keys(r.io.errors).length){s.push(`### Error Codes`),s.push(``),s.push(`| Code | HTTP | Description | When |`),s.push(`|------|------|-------------|------|`);for(let[e,t]of Object.entries(r.io.errors))s.push(`| \`${e}\` | ${t.http??400} | ${t.description} | ${t.when} |`);s.push(``)}}if(a.includePolicy&&(s.push(`## Policy`),s.push(``),s.push(`- **Auth Required:** ${r.policy.auth}`),s.push(`- **Idempotent:** ${r.policy.idempotent??o.kind===`query`}`),r.policy.rateLimit&&s.push(`- **Rate Limit:** ${r.policy.rateLimit.rpm} rpm per ${r.policy.rateLimit.key}`),r.policy.flags?.length&&s.push(`- **Feature Flags:** ${r.policy.flags.join(`, `)}`),r.policy.pii?.length&&s.push(`- **PII Fields:** ${r.policy.pii.join(`, `)}`),r.policy.escalate&&s.push(`- **Escalation:** ${r.policy.escalate}`),s.push(``)),a.includeSideEffects&&r.sideEffects){if(r.sideEffects.emits?.length){s.push(`## Events Emitted`),s.push(``);for(let e of r.sideEffects.emits)t(e)?s.push(`- \`${e.ref.name}.v${e.ref.version}\` — ${e.when}`):s.push(`- \`${e.name}.v${e.version}\` — ${e.when}`);s.push(``)}if(r.sideEffects.analytics?.length){s.push(`## Analytics Events`),s.push(``);for(let e of r.sideEffects.analytics)s.push(`- ${e}`);s.push(``)}}if(a.includeScenarios&&r.acceptance?.scenarios?.length){s.push(`## Acceptance Scenarios`),s.push(``);for(let e of r.acceptance.scenarios){s.push(`### ${e.name}`),s.push(``),s.push(`**Given:**`);for(let t of e.given)s.push(`- ${t}`);s.push(``),s.push(`**When:**`);for(let t of e.when)s.push(`- ${t}`);s.push(``),s.push(`**Then:**`);for(let t of e.then)s.push(`- ${t}`);s.push(``)}}if(a.includeExamples&&r.acceptance?.examples?.length){s.push(`## Examples`),s.push(``);for(let e of r.acceptance.examples)s.push(`### ${e.name}`),s.push(``),s.push(`**Input:**`),s.push("```json"),s.push(JSON.stringify(e.input,null,2)),s.push("```"),s.push(``),s.push(`**Output:**`),s.push("```json"),s.push(JSON.stringify(e.output,null,2)),s.push("```"),s.push(``)}return r.transport&&(s.push(`## Transport Configuration`),s.push(``),r.transport.rest&&s.push(`- **REST:** ${r.transport.rest.method??`POST`} ${r.transport.rest.path??`auto`}`),r.transport.gql&&s.push(`- **GraphQL:** ${r.transport.gql.field??`auto`}`),r.transport.mcp&&s.push(`- **MCP Tool:** ${r.transport.mcp.toolName??`auto`}`),s.push(``)),s.join(`
-`)}function o(e,t){let n=t?.taskType??`implement`,r=e.meta,i=[],o={implement:`Implement`,test:`Write tests for`,refactor:`Refactor`,review:`Review`}[n];if(i.push(`# Task: ${o} ${r.name}.v${r.version}`),i.push(``),i.push(`## Context`),i.push(``),i.push(`You are working on a ContractSpec-driven codebase. This spec defines a ${r.kind} operation.`),i.push(``),i.push(`**Goal:** ${r.goal}`),i.push(``),i.push(`**Background:** ${r.context}`),i.push(``),i.push(`## Specification`),i.push(``),i.push(a(e)),i.push(``),i.push(`## Instructions`),i.push(``),n===`implement`){if(i.push(`Implement this specification following these requirements:`),i.push(``),i.push("1. **Type Safety**: Use TypeScript with strict typing. No `any` types."),i.push(`2. **Input Validation**: Validate input against the schema before processing.`),i.push(`3. **Error Handling**: Implement all error cases defined in the spec.`),i.push(`4. **Events**: Emit events as specified in sideEffects.emits.`),i.push(`5. **Policy**: Respect auth, rate limits, and feature flags.`),i.push(`6. **Idempotency**: `+(e.policy.idempotent?`This operation MUST be idempotent.`:`This operation may have side effects.`)),i.push(``),e.policy.pii?.length){i.push(`**PII Handling**: The following fields contain PII and must be handled carefully:`);for(let t of e.policy.pii)i.push(`- ${t}`);i.push(``)}}else n===`test`?(i.push(`Write comprehensive tests for this specification:`),i.push(``),i.push(`1. Test all acceptance scenarios defined in the spec.`),i.push(`2. Test all error cases with appropriate assertions.`),i.push(`3. Test edge cases and boundary conditions.`),i.push(`4. Verify events are emitted correctly.`),i.push(`5. Use descriptive test names following the pattern: "should [behavior] when [condition]"`),i.push(``)):n===`refactor`?(i.push(`Refactor this implementation while preserving all behavior:`),i.push(``),i.push(`1. Maintain compliance with the specification.`),i.push(`2. Improve code clarity and maintainability.`),i.push(`3. Reduce complexity where possible.`),i.push(`4. Ensure all existing tests still pass.`),i.push(``)):n===`review`&&(i.push(`Review this implementation against the specification:`),i.push(``),i.push(`1. Verify input/output types match the schema.`),i.push(`2. Check all error cases are handled.`),i.push(`3. Verify events are emitted as specified.`),i.push(`4. Check policy compliance (auth, rate limits).`),i.push(`5. Report any deviations from the spec.`),i.push(``));return t?.existingCode&&(i.push(`## Existing Code`),i.push(``),i.push("```typescript"),i.push(t.existingCode),i.push("```"),i.push(``)),i.push(`## Expected Output`),i.push(``),n===`implement`||n===`refactor`?(i.push(`Provide a complete TypeScript implementation. Include:`),i.push(`- Type definitions for input/output`),i.push(`- Handler function with proper error handling`),i.push(`- JSDoc comments explaining the implementation`)):n===`test`?i.push(`Provide a complete test file using the testing framework available (prefer Vitest).`):n===`review`&&(i.push(`Provide a structured review with:`),i.push(`- Compliance status (pass/fail for each requirement)`),i.push(`- Issues found with severity (error/warning/info)`),i.push(`- Suggestions for improvement`)),i.push(``),i.join(`
-`)}function s(e,t,n={}){let i={...r,...n},o=e.meta,s=[];if(s.push(`# Feature: ${o.title??o.key}`),s.push(``),o.description&&(s.push(`> ${o.description}`),s.push(``)),s.push(`## Overview`),s.push(``),s.push(`- **Key:** \`${o.key}\``),s.push(`- **Stability:** ${o.stability}`),s.push(`- **Owners:** ${o.owners.join(`, `)}`),o.tags?.length&&s.push(`- **Tags:** ${o.tags.join(`, `)}`),s.push(``),e.operations?.length){s.push(`## Operations`),s.push(``),s.push(`| Name | Version | Type |`),s.push(`|------|---------|------|`);for(let n of e.operations){let e=(t?.specs?.getSpec(n.name,n.version))?.meta.kind??`unknown`;s.push(`| ${n.name} | v${n.version} | ${e} |`)}if(s.push(``),i.includeRelatedSpecs&&t?.specs){s.push(`### Operation Details`),s.push(``);for(let n of e.operations){let e=t.specs.getSpec(n.name,n.version);e&&(s.push(`---`),s.push(``),s.push(a(e,i)))}}}if(e.events?.length){s.push(`## Events`),s.push(``),s.push(`| Name | Version |`),s.push(`|------|---------|`);for(let t of e.events)s.push(`| ${t.name} | v${t.version} |`);s.push(``)}if(e.presentations?.length){s.push(`## Presentations`),s.push(``),s.push(`| Name | Version |`),s.push(`|------|---------|`);for(let t of e.presentations)s.push(`| ${t.name} | v${t.version} |`);if(s.push(``),i.includeRelatedPresentations&&t?.presentations){s.push(`### Presentation Details`),s.push(``);for(let n of e.presentations){let e=t.presentations.get(n.name,n.version);e&&(s.push(`#### ${n.name}.v${n.version}`),s.push(``),s.push(`- **Kind:** ${e.content.kind??`unknown`}`),`componentKey`in e.content&&s.push(`- **Component:** ${e.content.componentKey}`),s.push(``))}}}if(e.capabilities){if(e.capabilities.provides?.length){s.push(`## Capabilities Provided`),s.push(``);for(let t of e.capabilities.provides)s.push(`- \`${t.key}.v${t.version}\``);s.push(``)}if(e.capabilities.requires?.length){s.push(`## Capabilities Required`),s.push(``);for(let t of e.capabilities.requires)s.push(`- \`${t.key}\`${t.version?`.v${t.version}`:``} (${t.optional?`optional`:`required`})`);s.push(``)}}return s.join(`
-`)}function c(e){let t=e.meta,n=[];n.push(`# Presentation: ${t.name}.v${t.version}`),n.push(``),t.description&&(n.push(`> ${t.description}`),n.push(``)),n.push(`## Metadata`),n.push(``),n.push(`- **Name:** ${t.name}`),n.push(`- **Version:** ${t.version}`),t.stability&&n.push(`- **Stability:** ${t.stability}`),t.owners?.length&&n.push(`- **Owners:** ${t.owners.join(`, `)}`),t.tags?.length&&n.push(`- **Tags:** ${t.tags.join(`, `)}`),n.push(``),n.push(`## Source`),n.push(``),n.push(`- **Type:** ${e.source.type}`),e.source.type===`component`&&(n.push(`- **Framework:** ${e.source.framework}`),n.push(`- **Component Key:** ${e.source.componentKey}`)),n.push(``),n.push(`## Supported Targets`),n.push(``);for(let t of e.targets)n.push(`- ${t}`);return n.push(``),e.policy&&(n.push(`## Policy`),n.push(``),e.policy.flags?.length&&n.push(`- **Feature Flags:** ${e.policy.flags.join(`, `)}`),e.policy.pii?.length&&n.push(`- **PII Fields:** ${e.policy.pii.join(`, `)}`),n.push(``)),n.join(`
-`)}function l(e){let t=[];t.push(`# Event: ${e.name}.v${e.version}`),t.push(``),t.push(`## Metadata`),t.push(``),t.push(`- **Name:** ${e.name}`),t.push(`- **Version:** ${e.version}`),e.description&&t.push(`- **Description:** ${e.description}`),t.push(``),t.push(`## Payload Schema`),t.push(``),t.push("```json");try{let n=e.payload.getZod();if(`shape`in n&&n.shape){let e=n.shape,r=Object.keys(e);t.push(JSON.stringify({fields:r},null,2))}else t.push(`// Payload schema available at runtime`)}catch{t.push(`// Schema details available at runtime`)}return t.push("```"),t.push(``),t.join(`
-`)}function u(e){let t=[];if(t.push(`# ${e.title}`),t.push(``),e.summary&&(t.push(`> ${e.summary}`),t.push(``)),t.push(`## Metadata`),t.push(``),t.push(`- **ID:** ${e.id}`),t.push(`- **Kind:** ${e.kind??`reference`}`),t.push(`- **Visibility:** ${e.visibility??`public`}`),e.tags?.length&&t.push(`- **Tags:** ${e.tags.join(`, `)}`),e.owners?.length&&t.push(`- **Owners:** ${e.owners.join(`, `)}`),e.domain&&t.push(`- **Domain:** ${e.domain}`),t.push(``),t.push(`## Content`),t.push(``),t.push(e.body),t.push(``),e.links?.length){t.push(`## Related Links`),t.push(``);for(let n of e.links)t.push(`- [${n.label}](${n.href})`);t.push(``)}return t.join(`
-`)}function d(e,t={}){let n=t.format??`full`,r;switch(n){case`context`:r=i(e);break;case`prompt`:r=o(e);break;case`full`:default:r=a(e,t);break}return{spec:e,markdown:r,format:n,meta:{specName:e.meta.name,specVersion:e.meta.version,exportedAt:new Date().toISOString(),wordCount:r.split(/\s+/).length}}}function f(e,t,n={}){let r=n.format??`full`;return{feature:e,markdown:s(e,t,n),format:r,includedSpecs:e.operations?.map(e=>`${e.name}.v${e.version}`)??[],includedEvents:e.events?.map(e=>`${e.name}.v${e.version}`)??[],includedPresentations:e.presentations?.map(e=>`${e.name}.v${e.version}`)??[]}}export{u as docBlockToMarkdown,l as eventToMarkdown,f as exportFeature,d as exportSpec,s as featureToMarkdown,c as presentationToMarkdown,o as specToAgentPrompt,i as specToContextMarkdown,a as specToFullMarkdown};
+import { jsonSchemaForSpec } from "../jsonschema.js";
+import { isEmitDeclRef } from "../spec.js";
+
+//#region src/llm/exporters.ts
+const DEFAULT_SPEC_OPTIONS = {
+	format: "full",
+	includeSchemas: true,
+	includeScenarios: true,
+	includeExamples: true,
+	includePolicy: true,
+	includeSideEffects: true
+};
+const DEFAULT_FEATURE_OPTIONS = {
+	...DEFAULT_SPEC_OPTIONS,
+	includeRelatedSpecs: true,
+	includeRelatedEvents: true,
+	includeRelatedPresentations: true
+};
+/**
+* Export a single spec to context-focused markdown.
+* Includes: goal, context, description, acceptance scenarios.
+* Best for: Understanding what the spec does, providing context to LLMs.
+*/
+function specToContextMarkdown(spec) {
+	const m = spec.meta;
+	const lines = [];
+	lines.push(`# ${m.name} (v${m.version})`);
+	lines.push("");
+	lines.push(`> ${m.description}`);
+	lines.push("");
+	lines.push(`**Type:** ${m.kind} | **Stability:** ${m.stability}`);
+	lines.push("");
+	lines.push("## Goal");
+	lines.push("");
+	lines.push(m.goal);
+	lines.push("");
+	lines.push("## Context");
+	lines.push("");
+	lines.push(m.context);
+	lines.push("");
+	if (spec.acceptance?.scenarios?.length) {
+		lines.push("## Acceptance Criteria");
+		lines.push("");
+		for (const s of spec.acceptance.scenarios) {
+			lines.push(`### ${s.name}`);
+			lines.push("");
+			lines.push("**Given:**");
+			for (const g of s.given) lines.push(`- ${g}`);
+			lines.push("");
+			lines.push("**When:**");
+			for (const w of s.when) lines.push(`- ${w}`);
+			lines.push("");
+			lines.push("**Then:**");
+			for (const t of s.then) lines.push(`- ${t}`);
+			lines.push("");
+		}
+	}
+	return lines.join("\n");
+}
+/**
+* Export a single spec to full markdown with all details.
+* Includes: all fields, I/O schemas, policy, events, examples.
+* Best for: Complete documentation, implementation reference.
+*/
+function specToFullMarkdown(spec, options = {}) {
+	const opts = {
+		...DEFAULT_SPEC_OPTIONS,
+		...options
+	};
+	const m = spec.meta;
+	const lines = [];
+	lines.push(`# ${m.name}.v${m.version}`);
+	lines.push("");
+	lines.push(`> ${m.description}`);
+	lines.push("");
+	lines.push("## Metadata");
+	lines.push("");
+	lines.push("| Field | Value |");
+	lines.push("|-------|-------|");
+	lines.push(`| Kind | ${m.kind} |`);
+	lines.push(`| Stability | ${m.stability} |`);
+	lines.push(`| Owners | ${m.owners.join(", ")} |`);
+	lines.push(`| Tags | ${m.tags.join(", ")} |`);
+	lines.push("");
+	lines.push("## Goal");
+	lines.push("");
+	lines.push(m.goal);
+	lines.push("");
+	lines.push("## Context");
+	lines.push("");
+	lines.push(m.context);
+	lines.push("");
+	if (opts.includeSchemas) {
+		lines.push("## Input/Output");
+		lines.push("");
+		if (spec.io.input) {
+			lines.push("### Input Schema");
+			lines.push("");
+			lines.push("```json");
+			try {
+				const schema = jsonSchemaForSpec(spec);
+				lines.push(JSON.stringify(schema.input ?? {}, null, 2));
+			} catch {
+				lines.push("// Schema generation not available");
+			}
+			lines.push("```");
+			lines.push("");
+		}
+		lines.push("### Output Schema");
+		lines.push("");
+		lines.push("```json");
+		try {
+			const schema = jsonSchemaForSpec(spec);
+			lines.push(JSON.stringify(schema.output ?? {}, null, 2));
+		} catch {
+			lines.push("// Schema generation not available");
+		}
+		lines.push("```");
+		lines.push("");
+		if (spec.io.errors && Object.keys(spec.io.errors).length) {
+			lines.push("### Error Codes");
+			lines.push("");
+			lines.push("| Code | HTTP | Description | When |");
+			lines.push("|------|------|-------------|------|");
+			for (const [code, err] of Object.entries(spec.io.errors)) lines.push(`| \`${code}\` | ${err.http ?? 400} | ${err.description} | ${err.when} |`);
+			lines.push("");
+		}
+	}
+	if (opts.includePolicy) {
+		lines.push("## Policy");
+		lines.push("");
+		lines.push(`- **Auth Required:** ${spec.policy.auth}`);
+		lines.push(`- **Idempotent:** ${spec.policy.idempotent ?? m.kind === "query"}`);
+		if (spec.policy.rateLimit) lines.push(`- **Rate Limit:** ${spec.policy.rateLimit.rpm} rpm per ${spec.policy.rateLimit.key}`);
+		if (spec.policy.flags?.length) lines.push(`- **Feature Flags:** ${spec.policy.flags.join(", ")}`);
+		if (spec.policy.pii?.length) lines.push(`- **PII Fields:** ${spec.policy.pii.join(", ")}`);
+		if (spec.policy.escalate) lines.push(`- **Escalation:** ${spec.policy.escalate}`);
+		lines.push("");
+	}
+	if (opts.includeSideEffects && spec.sideEffects) {
+		if (spec.sideEffects.emits?.length) {
+			lines.push("## Events Emitted");
+			lines.push("");
+			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.sideEffects.analytics?.length) {
+			lines.push("## Analytics Events");
+			lines.push("");
+			for (const a of spec.sideEffects.analytics) lines.push(`- ${a}`);
+			lines.push("");
+		}
+	}
+	if (opts.includeScenarios && spec.acceptance?.scenarios?.length) {
+		lines.push("## Acceptance Scenarios");
+		lines.push("");
+		for (const s of spec.acceptance.scenarios) {
+			lines.push(`### ${s.name}`);
+			lines.push("");
+			lines.push("**Given:**");
+			for (const g of s.given) lines.push(`- ${g}`);
+			lines.push("");
+			lines.push("**When:**");
+			for (const w of s.when) lines.push(`- ${w}`);
+			lines.push("");
+			lines.push("**Then:**");
+			for (const t of s.then) lines.push(`- ${t}`);
+			lines.push("");
+		}
+	}
+	if (opts.includeExamples && spec.acceptance?.examples?.length) {
+		lines.push("## Examples");
+		lines.push("");
+		for (const ex of spec.acceptance.examples) {
+			lines.push(`### ${ex.name}`);
+			lines.push("");
+			lines.push("**Input:**");
+			lines.push("```json");
+			lines.push(JSON.stringify(ex.input, null, 2));
+			lines.push("```");
+			lines.push("");
+			lines.push("**Output:**");
+			lines.push("```json");
+			lines.push(JSON.stringify(ex.output, null, 2));
+			lines.push("```");
+			lines.push("");
+		}
+	}
+	if (spec.transport) {
+		lines.push("## Transport Configuration");
+		lines.push("");
+		if (spec.transport.rest) lines.push(`- **REST:** ${spec.transport.rest.method ?? "POST"} ${spec.transport.rest.path ?? "auto"}`);
+		if (spec.transport.gql) lines.push(`- **GraphQL:** ${spec.transport.gql.field ?? "auto"}`);
+		if (spec.transport.mcp) lines.push(`- **MCP Tool:** ${spec.transport.mcp.toolName ?? "auto"}`);
+		lines.push("");
+	}
+	return lines.join("\n");
+}
+/**
+* Export a single spec as an actionable agent prompt.
+* Includes: instructions, full spec, expected output format.
+* Best for: Directly feeding to coding agents for implementation.
+*/
+function specToAgentPrompt(spec, options) {
+	const taskType = options?.taskType ?? "implement";
+	const m = spec.meta;
+	const lines = [];
+	const taskVerb = {
+		implement: "Implement",
+		test: "Write tests for",
+		refactor: "Refactor",
+		review: "Review"
+	}[taskType];
+	lines.push(`# Task: ${taskVerb} ${m.name}.v${m.version}`);
+	lines.push("");
+	lines.push("## Context");
+	lines.push("");
+	lines.push(`You are working on a ContractSpec-driven codebase. This spec defines a ${m.kind} operation.`);
+	lines.push("");
+	lines.push(`**Goal:** ${m.goal}`);
+	lines.push("");
+	lines.push(`**Background:** ${m.context}`);
+	lines.push("");
+	lines.push("## Specification");
+	lines.push("");
+	lines.push(specToFullMarkdown(spec));
+	lines.push("");
+	lines.push("## Instructions");
+	lines.push("");
+	if (taskType === "implement") {
+		lines.push("Implement this specification following these requirements:");
+		lines.push("");
+		lines.push("1. **Type Safety**: Use TypeScript with strict typing. No `any` types.");
+		lines.push("2. **Input Validation**: Validate input against the schema before processing.");
+		lines.push("3. **Error Handling**: Implement all error cases defined in the spec.");
+		lines.push("4. **Events**: Emit events as specified in sideEffects.emits.");
+		lines.push("5. **Policy**: Respect auth, rate limits, and feature flags.");
+		lines.push("6. **Idempotency**: " + (spec.policy.idempotent ? "This operation MUST be idempotent." : "This operation may have side effects."));
+		lines.push("");
+		if (spec.policy.pii?.length) {
+			lines.push("**PII Handling**: The following fields contain PII and must be handled carefully:");
+			for (const field of spec.policy.pii) lines.push(`- ${field}`);
+			lines.push("");
+		}
+	} else if (taskType === "test") {
+		lines.push("Write comprehensive tests for this specification:");
+		lines.push("");
+		lines.push("1. Test all acceptance scenarios defined in the spec.");
+		lines.push("2. Test all error cases with appropriate assertions.");
+		lines.push("3. Test edge cases and boundary conditions.");
+		lines.push("4. Verify events are emitted correctly.");
+		lines.push("5. Use descriptive test names following the pattern: \"should [behavior] when [condition]\"");
+		lines.push("");
+	} else if (taskType === "refactor") {
+		lines.push("Refactor this implementation while preserving all behavior:");
+		lines.push("");
+		lines.push("1. Maintain compliance with the specification.");
+		lines.push("2. Improve code clarity and maintainability.");
+		lines.push("3. Reduce complexity where possible.");
+		lines.push("4. Ensure all existing tests still pass.");
+		lines.push("");
+	} else if (taskType === "review") {
+		lines.push("Review this implementation against the specification:");
+		lines.push("");
+		lines.push("1. Verify input/output types match the schema.");
+		lines.push("2. Check all error cases are handled.");
+		lines.push("3. Verify events are emitted as specified.");
+		lines.push("4. Check policy compliance (auth, rate limits).");
+		lines.push("5. Report any deviations from the spec.");
+		lines.push("");
+	}
+	if (options?.existingCode) {
+		lines.push("## Existing Code");
+		lines.push("");
+		lines.push("```typescript");
+		lines.push(options.existingCode);
+		lines.push("```");
+		lines.push("");
+	}
+	lines.push("## Expected Output");
+	lines.push("");
+	if (taskType === "implement" || taskType === "refactor") {
+		lines.push("Provide a complete TypeScript implementation. Include:");
+		lines.push("- Type definitions for input/output");
+		lines.push("- Handler function with proper error handling");
+		lines.push("- JSDoc comments explaining the implementation");
+	} else if (taskType === "test") lines.push("Provide a complete test file using the testing framework available (prefer Vitest).");
+	else if (taskType === "review") {
+		lines.push("Provide a structured review with:");
+		lines.push("- Compliance status (pass/fail for each requirement)");
+		lines.push("- Issues found with severity (error/warning/info)");
+		lines.push("- Suggestions for improvement");
+	}
+	lines.push("");
+	return lines.join("\n");
+}
+/**
+* Export a feature module to markdown.
+* Includes all related specs, events, and presentations.
+*/
+function featureToMarkdown(feature, deps, options = {}) {
+	const opts = {
+		...DEFAULT_FEATURE_OPTIONS,
+		...options
+	};
+	const m = feature.meta;
+	const lines = [];
+	lines.push(`# Feature: ${m.title ?? m.key}`);
+	lines.push("");
+	if (m.description) {
+		lines.push(`> ${m.description}`);
+		lines.push("");
+	}
+	lines.push("## Overview");
+	lines.push("");
+	lines.push(`- **Key:** \`${m.key}\``);
+	lines.push(`- **Stability:** ${m.stability}`);
+	lines.push(`- **Owners:** ${m.owners.join(", ")}`);
+	if (m.tags?.length) lines.push(`- **Tags:** ${m.tags.join(", ")}`);
+	lines.push("");
+	if (feature.operations?.length) {
+		lines.push("## Operations");
+		lines.push("");
+		lines.push("| Name | Version | Type |");
+		lines.push("|------|---------|------|");
+		for (const op of feature.operations) {
+			const kind = (deps?.specs?.getSpec(op.name, op.version))?.meta.kind ?? "unknown";
+			lines.push(`| ${op.name} | v${op.version} | ${kind} |`);
+		}
+		lines.push("");
+		if (opts.includeRelatedSpecs && deps?.specs) {
+			lines.push("### Operation Details");
+			lines.push("");
+			for (const op of feature.operations) {
+				const spec = deps.specs.getSpec(op.name, op.version);
+				if (spec) {
+					lines.push(`---`);
+					lines.push("");
+					lines.push(specToFullMarkdown(spec, opts));
+				}
+			}
+		}
+	}
+	if (feature.events?.length) {
+		lines.push("## Events");
+		lines.push("");
+		lines.push("| Name | Version |");
+		lines.push("|------|---------|");
+		for (const evt of feature.events) lines.push(`| ${evt.name} | v${evt.version} |`);
+		lines.push("");
+	}
+	if (feature.presentations?.length) {
+		lines.push("## Presentations");
+		lines.push("");
+		lines.push("| Name | Version |");
+		lines.push("|------|---------|");
+		for (const pres of feature.presentations) lines.push(`| ${pres.name} | v${pres.version} |`);
+		lines.push("");
+		if (opts.includeRelatedPresentations && deps?.presentations) {
+			lines.push("### Presentation Details");
+			lines.push("");
+			for (const pres of feature.presentations) {
+				const p = deps.presentations.get(pres.name, pres.version);
+				if (p) {
+					lines.push(`#### ${pres.name}.v${pres.version}`);
+					lines.push("");
+					lines.push(`- **Kind:** ${p.content.kind ?? "unknown"}`);
+					if ("componentKey" in p.content) lines.push(`- **Component:** ${p.content.componentKey}`);
+					lines.push("");
+				}
+			}
+		}
+	}
+	if (feature.capabilities) {
+		if (feature.capabilities.provides?.length) {
+			lines.push("## Capabilities Provided");
+			lines.push("");
+			for (const cap of feature.capabilities.provides) lines.push(`- \`${cap.key}.v${cap.version}\``);
+			lines.push("");
+		}
+		if (feature.capabilities.requires?.length) {
+			lines.push("## Capabilities Required");
+			lines.push("");
+			for (const cap of feature.capabilities.requires) lines.push(`- \`${cap.key}\`${cap.version ? `.v${cap.version}` : ""} (${cap.optional ? "optional" : "required"})`);
+			lines.push("");
+		}
+	}
+	return lines.join("\n");
+}
+/**
+* Export a presentation descriptor to markdown.
+*/
+function presentationToMarkdown(presentation) {
+	const m = presentation.meta;
+	const lines = [];
+	lines.push(`# Presentation: ${m.name}.v${m.version}`);
+	lines.push("");
+	if (m.description) {
+		lines.push(`> ${m.description}`);
+		lines.push("");
+	}
+	lines.push("## Metadata");
+	lines.push("");
+	lines.push(`- **Name:** ${m.name}`);
+	lines.push(`- **Version:** ${m.version}`);
+	if (m.stability) lines.push(`- **Stability:** ${m.stability}`);
+	if (m.owners?.length) lines.push(`- **Owners:** ${m.owners.join(", ")}`);
+	if (m.tags?.length) lines.push(`- **Tags:** ${m.tags.join(", ")}`);
+	lines.push("");
+	lines.push("## Source");
+	lines.push("");
+	lines.push(`- **Type:** ${presentation.source.type}`);
+	if (presentation.source.type === "component") {
+		lines.push(`- **Framework:** ${presentation.source.framework}`);
+		lines.push(`- **Component Key:** ${presentation.source.componentKey}`);
+	}
+	lines.push("");
+	lines.push("## Supported Targets");
+	lines.push("");
+	for (const target of presentation.targets) lines.push(`- ${target}`);
+	lines.push("");
+	if (presentation.policy) {
+		lines.push("## Policy");
+		lines.push("");
+		if (presentation.policy.flags?.length) lines.push(`- **Feature Flags:** ${presentation.policy.flags.join(", ")}`);
+		if (presentation.policy.pii?.length) lines.push(`- **PII Fields:** ${presentation.policy.pii.join(", ")}`);
+		lines.push("");
+	}
+	return lines.join("\n");
+}
+/**
+* Export an event spec to markdown.
+*/
+function eventToMarkdown(event) {
+	const lines = [];
+	lines.push(`# Event: ${event.name}.v${event.version}`);
+	lines.push("");
+	lines.push("## Metadata");
+	lines.push("");
+	lines.push(`- **Name:** ${event.name}`);
+	lines.push(`- **Version:** ${event.version}`);
+	if (event.description) lines.push(`- **Description:** ${event.description}`);
+	lines.push("");
+	lines.push("## Payload Schema");
+	lines.push("");
+	lines.push("```json");
+	try {
+		const zodSchema = event.payload.getZod();
+		if ("shape" in zodSchema && zodSchema.shape) {
+			const shape = zodSchema.shape;
+			const fields = Object.keys(shape);
+			lines.push(JSON.stringify({ fields }, null, 2));
+		} else lines.push("// Payload schema available at runtime");
+	} catch {
+		lines.push("// Schema details available at runtime");
+	}
+	lines.push("```");
+	lines.push("");
+	return lines.join("\n");
+}
+/**
+* Export a DocBlock to markdown (already markdown, but formatted consistently).
+*/
+function docBlockToMarkdown(doc) {
+	const lines = [];
+	lines.push(`# ${doc.title}`);
+	lines.push("");
+	if (doc.summary) {
+		lines.push(`> ${doc.summary}`);
+		lines.push("");
+	}
+	lines.push("## Metadata");
+	lines.push("");
+	lines.push(`- **ID:** ${doc.id}`);
+	lines.push(`- **Kind:** ${doc.kind ?? "reference"}`);
+	lines.push(`- **Visibility:** ${doc.visibility ?? "public"}`);
+	if (doc.tags?.length) lines.push(`- **Tags:** ${doc.tags.join(", ")}`);
+	if (doc.owners?.length) lines.push(`- **Owners:** ${doc.owners.join(", ")}`);
+	if (doc.domain) lines.push(`- **Domain:** ${doc.domain}`);
+	lines.push("");
+	lines.push("## Content");
+	lines.push("");
+	lines.push(doc.body);
+	lines.push("");
+	if (doc.links?.length) {
+		lines.push("## Related Links");
+		lines.push("");
+		for (const link of doc.links) lines.push(`- [${link.label}](${link.href})`);
+		lines.push("");
+	}
+	return lines.join("\n");
+}
+/**
+* Export a spec with a specific format.
+* Convenience function that wraps the format-specific functions.
+*/
+function exportSpec(spec, options = {}) {
+	const format = options.format ?? "full";
+	let markdown;
+	switch (format) {
+		case "context":
+			markdown = specToContextMarkdown(spec);
+			break;
+		case "prompt":
+			markdown = specToAgentPrompt(spec);
+			break;
+		case "full":
+		default:
+			markdown = specToFullMarkdown(spec, options);
+			break;
+	}
+	return {
+		spec,
+		markdown,
+		format,
+		meta: {
+			specName: spec.meta.name,
+			specVersion: spec.meta.version,
+			exportedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			wordCount: markdown.split(/\s+/).length
+		}
+	};
+}
+/**
+* Export a feature with a specific format.
+*/
+function exportFeature(feature, deps, options = {}) {
+	const format = options.format ?? "full";
+	return {
+		feature,
+		markdown: featureToMarkdown(feature, deps, options),
+		format,
+		includedSpecs: feature.operations?.map((o) => `${o.name}.v${o.version}`) ?? [],
+		includedEvents: feature.events?.map((e) => `${e.name}.v${e.version}`) ?? [],
+		includedPresentations: feature.presentations?.map((p) => `${p.name}.v${p.version}`) ?? []
+	};
+}
+
+//#endregion
+export { docBlockToMarkdown, eventToMarkdown, exportFeature, exportSpec, featureToMarkdown, presentationToMarkdown, specToAgentPrompt, specToContextMarkdown, specToFullMarkdown };

package/dist/llm/index.js

@@ -1 +1,4 @@
-import{docBlockToMarkdown as e,eventToMarkdown as t,exportFeature as n,exportSpec as r,featureToMarkdown as i,presentationToMarkdown as a,specToAgentPrompt as o,specToContextMarkdown as s,specToFullMarkdown as c}from"./exporters.js";import{AGENT_SYSTEM_PROMPTS as l,formatPlanForAgent as u,generateFixViolationsPrompt as d,generateImplementationPlan as f,generateImplementationPrompt as p,generateReviewPrompt as m,generateTestPrompt as h,generateVerificationPrompt as g}from"./prompts.js";export{l as AGENT_SYSTEM_PROMPTS,e as docBlockToMarkdown,t as eventToMarkdown,n as exportFeature,r as exportSpec,i as featureToMarkdown,u as formatPlanForAgent,d as generateFixViolationsPrompt,f as generateImplementationPlan,p as generateImplementationPrompt,m as generateReviewPrompt,h as generateTestPrompt,g as generateVerificationPrompt,a as presentationToMarkdown,o as specToAgentPrompt,s as specToContextMarkdown,c as specToFullMarkdown};
+import { docBlockToMarkdown, eventToMarkdown, exportFeature, exportSpec, featureToMarkdown, presentationToMarkdown, specToAgentPrompt, specToContextMarkdown, specToFullMarkdown } from "./exporters.js";
+import { AGENT_SYSTEM_PROMPTS, formatPlanForAgent, generateFixViolationsPrompt, generateImplementationPlan, generateImplementationPrompt, generateReviewPrompt, generateTestPrompt, generateVerificationPrompt } from "./prompts.js";
+
+export { AGENT_SYSTEM_PROMPTS, docBlockToMarkdown, eventToMarkdown, exportFeature, exportSpec, featureToMarkdown, formatPlanForAgent, generateFixViolationsPrompt, generateImplementationPlan, generateImplementationPrompt, generateReviewPrompt, generateTestPrompt, generateVerificationPrompt, presentationToMarkdown, specToAgentPrompt, specToContextMarkdown, specToFullMarkdown };