@thinkingsage/kanon 0.8.0

package/src/adapters/copilot.ts

@@ -0,0 +1,106 @@
+import { resolveFormat } from "../format-registry";
+import { renderTemplate } from "../template-engine";
+import type { HarnessCapabilityName } from "./capabilities";
+import { applyDegradation } from "./degradation";
+import type { AdapterWarning, HarnessAdapter, OutputFile } from "./types";
+
+export const copilotAdapter: HarnessAdapter = (
+	artifact,
+	templateEnv,
+	context?,
+) => {
+	const files: OutputFile[] = [];
+	const warnings: AdapterWarning[] = [];
+
+	// Capability degradation checks
+	if (context) {
+		const checks: Array<{
+			capability: HarnessCapabilityName;
+			hasFeature: boolean;
+		}> = [
+			{ capability: "hooks", hasFeature: artifact.hooks.length > 0 },
+			{ capability: "mcp", hasFeature: artifact.mcpServers.length > 0 },
+			{ capability: "workflows", hasFeature: artifact.workflows.length > 0 },
+		];
+		for (const { capability, hasFeature } of checks) {
+			if (!hasFeature) continue;
+			const entry = context.capabilities[capability];
+			if (entry.support === "full") continue;
+			if (context.strict) {
+				warnings.push({
+					artifactName: artifact.name,
+					harnessName: "copilot",
+					message: `Strict mode: capability ${capability} not supported by harness copilot`,
+				});
+				return { files, warnings };
+			}
+			const degradation = applyDegradation(
+				entry.degradation ?? "inline",
+				capability,
+				artifact,
+				"copilot",
+			);
+			warnings.push(...degradation.warnings);
+		}
+	}
+
+	const harnessConfig = (artifact.frontmatter as Record<string, unknown>)[
+		"harness-config"
+	] as Record<string, unknown> | undefined;
+	const copilotConfig = (harnessConfig?.copilot ?? {}) as Record<
+		string,
+		unknown
+	>;
+	const { format } = resolveFormat("copilot", copilotConfig);
+
+	// Generate .github/copilot-instructions.md
+	const instructionsContent = renderTemplate(
+		templateEnv,
+		"copilot/instructions.md.njk",
+		{ artifact },
+	);
+	files.push({
+		relativePath: ".github/copilot-instructions.md",
+		content: instructionsContent,
+	});
+
+	// Generate path-scoped instructions if file_patterns or harness-config.copilot.path-scoped
+	const filePatterns = artifact.frontmatter.file_patterns;
+	const pathScoped = copilotConfig["path-scoped"] as string[] | undefined;
+	const applyTo = pathScoped || filePatterns;
+	if (applyTo && applyTo.length > 0) {
+		const applyToStr = applyTo.join(", ");
+		const scopedContent = renderTemplate(templateEnv, "copilot/scoped.md.njk", {
+			artifact,
+			applyTo: applyToStr,
+		});
+		files.push({
+			relativePath: `.github/instructions/${artifact.name}.instructions.md`,
+			content: scopedContent,
+		});
+	}
+
+	// Generate AGENTS.md when format is "agent", or when workflows exist / agents-md is true
+	if (
+		format === "agent" ||
+		artifact.workflows.length > 0 ||
+		copilotConfig["agents-md"] === true
+	) {
+		const agentsContent = renderTemplate(templateEnv, "copilot/agents.md.njk", {
+			artifact,
+		});
+		files.push({ relativePath: "AGENTS.md", content: agentsContent });
+	}
+
+	// Skip hooks with warning
+	if (artifact.hooks.length > 0) {
+		warnings.push({
+			artifactName: artifact.name,
+			harnessName: "copilot",
+			message:
+				"GitHub Copilot does not support hooks; skipping all hook definitions",
+		});
+	}
+
+	return { files, warnings };
+};

package/src/adapters/cursor.ts

@@ -0,0 +1,97 @@
+import { resolveFormat } from "../format-registry";
+import type { InclusionMode } from "../schemas";
+import { renderTemplate } from "../template-engine";
+import type { HarnessCapabilityName } from "./capabilities";
+import { applyDegradation } from "./degradation";
+import type { AdapterWarning, HarnessAdapter, OutputFile } from "./types";
+import { buildMcpConfig } from "./types";
+
+const CURSOR_INCLUSION_MAP: Record<InclusionMode, string> = {
+	always: "always",
+	auto: "auto",
+	fileMatch: "auto",
+	manual: "agent-requested",
+};
+
+export const cursorAdapter: HarnessAdapter = (
+	artifact,
+	templateEnv,
+	context?,
+) => {
+	const files: OutputFile[] = [];
+	const warnings: AdapterWarning[] = [];
+
+	// Capability degradation checks
+	if (context) {
+		const checks: Array<{
+			capability: HarnessCapabilityName;
+			hasFeature: boolean;
+		}> = [
+			{ capability: "hooks", hasFeature: artifact.hooks.length > 0 },
+			{ capability: "mcp", hasFeature: artifact.mcpServers.length > 0 },
+			{ capability: "workflows", hasFeature: artifact.workflows.length > 0 },
+		];
+		for (const { capability, hasFeature } of checks) {
+			if (!hasFeature) continue;
+			const entry = context.capabilities[capability];
+			if (entry.support === "full") continue;
+			if (context.strict) {
+				warnings.push({
+					artifactName: artifact.name,
+					harnessName: "cursor",
+					message: `Strict mode: capability ${capability} not supported by harness cursor`,
+				});
+				return { files, warnings };
+			}
+			const degradation = applyDegradation(
+				entry.degradation ?? "inline",
+				capability,
+				artifact,
+				"cursor",
+			);
+			warnings.push(...degradation.warnings);
+		}
+	}
+
+	const harnessConfig = (artifact.frontmatter as Record<string, unknown>)[
+		"harness-config"
+	] as Record<string, unknown> | undefined;
+	const cursorConfig = (harnessConfig?.cursor ?? {}) as Record<string, unknown>;
+	resolveFormat("cursor", cursorConfig);
+
+	// Map inclusion mode
+	const inclusionOverride = cursorConfig.inclusion as InclusionMode | undefined;
+	const canonicalInclusion =
+		inclusionOverride || artifact.frontmatter.inclusion;
+	const cursorInclusion = CURSOR_INCLUSION_MAP[canonicalInclusion] || "always";
+
+	// Generate .cursor/rules/<artifact>.md
+	const ruleContent = renderTemplate(templateEnv, "cursor/rule.md.njk", {
+		artifact,
+		cursorInclusion,
+	});
+	files.push({
+		relativePath: `.cursor/rules/${artifact.name}.md`,
+		content: ruleContent,
+	});
+
+	// Generate .cursor/mcp.json
+	if (artifact.mcpServers.length > 0) {
+		const mcpConfig = buildMcpConfig(artifact.mcpServers);
+		const mcpContent = renderTemplate(templateEnv, "cursor/mcp.json.njk", {
+			mcpConfig,
+		});
+		files.push({ relativePath: ".cursor/mcp.json", content: mcpContent });
+	}
+
+	// Skip hooks with warning
+	if (artifact.hooks.length > 0) {
+		warnings.push({
+			artifactName: artifact.name,
+			harnessName: "cursor",
+			message: "Cursor does not support hooks; skipping all hook definitions",
+		});
+	}
+
+	return { files, warnings };
+};

package/src/adapters/degradation.ts

@@ -0,0 +1,95 @@
+import type {
+	CanonicalHook,
+	DegradationStrategy,
+	KnowledgeArtifact,
+} from "../schemas";
+import type { HarnessCapabilityName } from "./capabilities";
+import type { AdapterWarning } from "./types";
+
+export interface DegradationResult {
+	inlineText: string;
+	commentText: string;
+	warnings: AdapterWarning[];
+}
+
+/** Render hooks as prose for inline degradation */
+export function degradeHooksInline(
+	hooks: CanonicalHook[],
+	artifactName: string,
+	harnessName: string,
+): DegradationResult {
+	const warnings: AdapterWarning[] = [];
+	if (hooks.length === 0) return { inlineText: "", commentText: "", warnings };
+
+	const lines = [
+		"",
+		"---",
+		"<!-- forge:degraded hooks (inline) -->",
+		"## Automated Behaviors",
+		"",
+		"The following behaviors should be applied manually since this harness does not support hooks natively:",
+		"",
+	];
+
+	for (const hook of hooks) {
+		const trigger = hook.event.replace(/_/g, " ");
+		const action =
+			hook.action.type === "ask_agent"
+				? hook.action.prompt
+				: `Run: \`${hook.action.command}\``;
+		lines.push(`- **When** ${trigger}: ${action}`);
+	}
+
+	warnings.push({
+		artifactName,
+		harnessName,
+		message: `hooks: degraded via inline strategy (${hooks.length} hook(s) rendered as prose)`,
+	});
+
+	return { inlineText: lines.join("\n"), commentText: "", warnings };
+}
+
+/** Apply a degradation strategy for a given capability */
+export function applyDegradation(
+	strategy: DegradationStrategy,
+	capability: HarnessCapabilityName,
+	artifact: KnowledgeArtifact,
+	harnessName: string,
+): DegradationResult {
+	const warnings: AdapterWarning[] = [];
+
+	switch (strategy) {
+		case "inline":
+			if (capability === "hooks") {
+				return degradeHooksInline(artifact.hooks, artifact.name, harnessName);
+			}
+			warnings.push({
+				artifactName: artifact.name,
+				harnessName,
+				message: `${capability}: degraded via inline strategy`,
+			});
+			return {
+				inlineText: `\n<!-- forge:degraded ${capability} (inline) -->\n`,
+				commentText: "",
+				warnings,
+			};
+
+		case "comment": {
+			const comment = `<!-- forge:unsupported ${capability} — this harness does not support ${capability} -->`;
+			warnings.push({
+				artifactName: artifact.name,
+				harnessName,
+				message: `${capability}: degraded via comment strategy`,
+			});
+			return { inlineText: "", commentText: comment, warnings };
+		}
+
+		case "omit":
+			warnings.push({
+				artifactName: artifact.name,
+				harnessName,
+				message: `${capability}: omitted (not supported by ${harnessName})`,
+			});
+			return { inlineText: "", commentText: "", warnings };
+	}
+}

package/src/adapters/index.ts

@@ -0,0 +1,324 @@
+/**
+ * Adapter Registry — Routes harness adapters through Rosetta Stone target translators
+ *
+ * Each adapter entry wraps the corresponding target translator with template
+ * bundle loading and result mapping, preserving the existing adapter function
+ * signatures: (artifact, templateEnv, context?) => AdapterResult.
+ *
+ * ADR-RS-002: adapterRegistry remains keyed by harness. Each adapter entry
+ * calls the corresponding target translator with an in-memory template bundle
+ * and maps plans/diagnostics back to AdapterResult.
+ *
+ * ADR-RS-004: Templates are preloaded into an immutable bundle before entering
+ * the pure translation boundary.
+ *
+ * Requirements: 1.1, 6.1, 12.2, 14.5, 14.10
+ */
+
+import { resolve } from "node:path";
+import type nunjucks from "nunjucks";
+import { resolveFormat } from "../format-registry";
+import type {
+	TargetTranslator,
+	TargetTranslatorContext,
+} from "../rosetta/registry";
+import type { ImmutableTemplateBundle } from "../rosetta/templates";
+import type {
+	FormatContract,
+	HarnessName,
+	KnowledgeArtifact,
+} from "../schemas";
+import { SUPPORTED_HARNESSES } from "../schemas";
+import { loadTemplateBundle } from "../template-bundle-loader";
+import type { AdapterContext, AdapterResult, HarnessAdapter } from "./types";
+
+export type { HarnessName };
+export { SUPPORTED_HARNESSES };
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Template Bundle Cache
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Cached immutable template bundle, loaded once on first use.
+ * The templates dir is inferred from the Nunjucks Environment's loader path
+ * or falls back to the standard `templates/harness-adapters` location.
+ */
+let cachedTemplateBundle: ImmutableTemplateBundle | null = null;
+
+/**
+ * Get or create the immutable template bundle.
+ * Lazily loads templates from the filesystem on first call, then returns the
+ * cached frozen bundle for all subsequent calls.
+ */
+function getTemplateBundle(
+	templateEnv: nunjucks.Environment,
+): ImmutableTemplateBundle {
+	if (cachedTemplateBundle !== null) {
+		return cachedTemplateBundle;
+	}
+
+	// Extract the templates directory from the Nunjucks environment's loader.
+	// The FileSystemLoader stores its search paths; use the first one.
+	let templatesDir: string;
+	const loaders = (
+		templateEnv as unknown as { loaders: Array<{ searchPaths?: string[] }> }
+	).loaders;
+	if (loaders?.[0]?.searchPaths?.[0]) {
+		templatesDir = loaders[0].searchPaths[0];
+	} else {
+		// Fallback: resolve from cwd (standard kanon layout)
+		templatesDir = resolve("templates/harness-adapters");
+	}
+
+	cachedTemplateBundle = loadTemplateBundle(templatesDir);
+	return cachedTemplateBundle;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Format Contract Lookup (lazy to avoid circular initialization)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/** Lazily-built map from harness name to primary bidirectional/target format contract. */
+let harnessContractMap: Map<HarnessName, FormatContract> | null = null;
+
+/**
+ * Get the harness-to-contract map, building it on first call.
+ * Uses lazy initialization to avoid circular dependency issues at module load.
+ */
+function getHarnessContractMap(): ReadonlyMap<HarnessName, FormatContract> {
+	if (harnessContractMap !== null) {
+		return harnessContractMap;
+	}
+	// Import lazily to break the circular init chain:
+	// adapters/index → rosetta/builtins/contracts → rosetta/builtins/compatibility-profiles → adapters/capabilities
+	const { BUILTIN_FORMAT_CONTRACTS } = require("../rosetta/builtins/contracts");
+	const map = new Map<HarnessName, FormatContract>();
+	for (const contract of BUILTIN_FORMAT_CONTRACTS) {
+		if (contract.harness === null) continue;
+		if (contract.direction === "source") continue;
+		const harness = contract.harness as HarnessName;
+		// First matching bidirectional/target contract wins
+		if (!map.has(harness)) {
+			map.set(harness, contract);
+		}
+	}
+	harnessContractMap = map;
+	return map;
+}
+
+/** Lazily-built target translator map from format identifiers. */
+let targetTranslatorMap: ReadonlyMap<string, TargetTranslator> | null = null;
+
+/**
+ * Get the target translator map, loading it on first call.
+ */
+function getTargetTranslatorMap(): ReadonlyMap<string, TargetTranslator> {
+	if (targetTranslatorMap !== null) {
+		return targetTranslatorMap;
+	}
+	const { TARGET_TRANSLATORS } = require("../rosetta/builtins/targets");
+	targetTranslatorMap = TARGET_TRANSLATORS as ReadonlyMap<
+		string,
+		TargetTranslator
+	>;
+	return targetTranslatorMap;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Result Mapping
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Map a TargetTranslationOutput (plan + diagnostics + degradations) back to
+ * the AdapterResult shape that existing consumers expect.
+ *
+ * - plan.outputFiles → AdapterResult.files (preserving relativePath, content, executable)
+ * - diagnostics with severity "warning" → AdapterResult.warnings
+ * - diagnostics with severity "error" → AdapterResult.errors
+ * - degradation records generate additional warnings
+ */
+function mapToAdapterResult(
+	output: {
+		plan: Record<string, unknown>;
+		diagnostics: readonly Record<string, unknown>[];
+		degradations: readonly Record<string, unknown>[];
+	},
+	artifactName: string,
+	harnessName: HarnessName,
+): AdapterResult {
+	const plan = output.plan as {
+		outputFiles?: Array<{
+			relativePath: string;
+			content: string | Uint8Array;
+			executable?: boolean;
+		}>;
+	};
+	const files = (plan.outputFiles ?? []).map((f) => ({
+		relativePath: f.relativePath,
+		content:
+			typeof f.content === "string"
+				? f.content
+				: new TextDecoder().decode(f.content),
+		...(f.executable ? { executable: true } : {}),
+	}));
+
+	const warnings: AdapterResult["warnings"] = [];
+	const errors: AdapterResult["errors"] = [];
+
+	// Map diagnostics to warnings/errors
+	for (const diag of output.diagnostics) {
+		const d = diag as { severity?: string; message?: string; code?: string };
+		const message = d.message ?? d.code ?? "Unknown diagnostic";
+
+		if (d.severity === "error") {
+			errors.push({
+				artifactName,
+				harnessName,
+				message,
+			});
+		} else {
+			// "warning" and "info" both map to adapter warnings for backward compat
+			warnings.push({
+				artifactName,
+				harnessName,
+				message,
+			});
+		}
+	}
+
+	// Map degradation records to warnings
+	for (const deg of output.degradations) {
+		const d = deg as {
+			capability?: string;
+			action?: string;
+			affectedValueCount?: number;
+		};
+		warnings.push({
+			artifactName,
+			harnessName,
+			message: `Degradation: ${d.capability ?? "unknown"} (${d.action ?? "omit"}, ${d.affectedValueCount ?? 0} value(s) affected)`,
+		});
+	}
+
+	return {
+		files,
+		warnings,
+		...(errors.length > 0 ? { errors } : {}),
+	};
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Adapter Wrapper
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Create an adapter that routes through a Rosetta Stone target translator.
+ *
+ * Preserves the existing adapter signature:
+ *   (artifact: KnowledgeArtifact, templateEnv: nunjucks.Environment, context?: AdapterContext) => AdapterResult
+ *
+ * During migration, each adapter entry in the registry wraps the target
+ * translator with the necessary template loading and result mapping.
+ */
+function createRosettaAdapter(harness: HarnessName): HarnessAdapter {
+	return (
+		artifact: KnowledgeArtifact,
+		templateEnv: nunjucks.Environment,
+		_context?: AdapterContext,
+	): AdapterResult => {
+		// Get the format contract for this harness (lazy init)
+		const contractMap = getHarnessContractMap();
+		const contract = contractMap.get(harness);
+		if (!contract) {
+			return {
+				files: [],
+				warnings: [
+					{
+						artifactName: artifact.name,
+						harnessName: harness,
+						message: `No format contract found for harness "${harness}"`,
+					},
+				],
+			};
+		}
+
+		// Resolve variant from harness-config using the same logic as before
+		const harnessConfig = (artifact.frontmatter as Record<string, unknown>)[
+			"harness-config"
+		] as Record<string, unknown> | undefined;
+		const perHarnessConfig = (harnessConfig?.[harness] ?? {}) as Record<
+			string,
+			unknown
+		>;
+		const { format: variant } = resolveFormat(harness, perHarnessConfig);
+
+		// Preload immutable template bundle (cached after first load)
+		const templates = getTemplateBundle(templateEnv);
+
+		// Build the target translator context
+		const translatorContext: TargetTranslatorContext = {
+			format: contract,
+			variant,
+			canonicalSchemaVersion: "1.0.0",
+			options: {},
+			callerContext: {},
+			templates,
+		};
+
+		// Look up and call the target translator (lazy init)
+		const translatorMap = getTargetTranslatorMap();
+		const translator = translatorMap.get(contract.id as unknown as string);
+		if (!translator) {
+			return {
+				files: [],
+				warnings: [
+					{
+						artifactName: artifact.name,
+						harnessName: harness,
+						message: `No target translator found for format "${contract.id}"`,
+					},
+				],
+			};
+		}
+
+		// Call the target translator with the artifact as a record
+		const output = translator(
+			artifact as unknown as Record<string, unknown>,
+			translatorContext,
+		);
+
+		// Map the output back to AdapterResult shape
+		return mapToAdapterResult(output, artifact.name, harness);
+	};
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Public Adapter Registry
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Registry mapping harness names to adapter functions.
+ *
+ * Each entry routes through the corresponding Rosetta Stone target translator,
+ * preloading immutable template bundles and mapping plans/diagnostics back to
+ * the AdapterResult shape that existing consumers expect.
+ */
+export const adapterRegistry: Record<HarnessName, HarnessAdapter> = {
+	kiro: createRosettaAdapter("kiro"),
+	"claude-code": createRosettaAdapter("claude-code"),
+	codex: createRosettaAdapter("codex"),
+	copilot: createRosettaAdapter("copilot"),
+	cursor: createRosettaAdapter("cursor"),
+	windsurf: createRosettaAdapter("windsurf"),
+	cline: createRosettaAdapter("cline"),
+	qdeveloper: createRosettaAdapter("qdeveloper"),
+};
+
+/**
+ * Reset the cached template bundle. Used in tests to ensure fresh state.
+ * @internal
+ */
+export function _resetTemplateBundleCache(): void {
+	cachedTemplateBundle = null;
+}