@lssm/bundle.contractspec-workspace 0.0.0-canary-20251217083314 → 0.0.0-canary-20251220002821

package/dist/libs/contracts/dist/llm/exporters.js

@@ -1,352 +0,0 @@
-import { jsonSchemaForSpec } from "../jsonschema.js";
-import { isEmitDeclRef } from "../spec.js";
-
-//#region ../../libs/contracts/dist/llm/exporters.js
-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 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");
-}
-
-//#endregion
-export { featureToMarkdown, specToAgentPrompt, specToFullMarkdown };

package/dist/libs/contracts/dist/llm/index.js

@@ -1,2 +0,0 @@
-import { featureToMarkdown, specToAgentPrompt, specToFullMarkdown } from "./exporters.js";
-import { AGENT_SYSTEM_PROMPTS, generateImplementationPlan, generateVerificationPrompt } from "./prompts.js";

package/dist/libs/contracts/dist/llm/prompts.js

@@ -1,211 +0,0 @@
-import { specToFullMarkdown } from "./exporters.js";
-
-//#region ../../libs/contracts/dist/llm/prompts.js
-/**
-* 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 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:**
-${specToFullMarkdown(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.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"
-		]
-	};
-}
-
-//#endregion
-export { AGENT_SYSTEM_PROMPTS, generateImplementationPlan, generateVerificationPrompt };