@thinkingsage/kanon 0.8.0

package/src/rosetta/builtins/targets/codex.ts

@@ -0,0 +1,226 @@
+/**
+ * Rosetta Stone — Codex Target Translator
+ *
+ * Wraps the existing codex adapter logic with resolved variants, body overrides,
+ * template bundles, effective compatibility actions, structured diagnostics,
+ * and deterministic TranslationPlan output.
+ *
+ * CONSTRAINTS:
+ * - NO filesystem, process, clock, random, Git, or network imports
+ * - Pure function only
+ *
+ * Requirements: 6.1, 6.5, 6.6, 7.3, 7.5, 13.8
+ */
+
+import type {
+	DegradationRecord,
+	KnowledgeArtifact,
+	McpServerDefinition,
+	OutputFile,
+	TranslationDiagnostic,
+} from "../../../schemas";
+import { isStdioServer } from "../../../schemas";
+import {
+	evaluateCompatibility,
+	identifyUsedCapabilities,
+	resolveEffectiveProfile,
+} from "../../compatibility";
+import { createDiagnostic } from "../../diagnostics";
+import { createPlan } from "../../plan";
+import type {
+	TargetTranslationOutput,
+	TargetTranslatorContext,
+} from "../../registry";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Codex Target Translator
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Translate a canonical KnowledgeArtifact into Codex harness-native output.
+ *
+ * Handles `agents-md` and `skill` variants:
+ * - agents-md: produces a repo-wide AGENTS.md with full body
+ * - skill: produces .codex/skills/<name>/SKILL.md with references and an
+ *   AGENTS.md pointer
+ *
+ * Applies body overrides for "codex" harness when available.
+ */
+export function translateCodexTarget(
+	artifact: Record<string, unknown>,
+	context: TargetTranslatorContext,
+): TargetTranslationOutput {
+	const diagnostics: TranslationDiagnostic[] = [];
+	const degradations: DegradationRecord[] = [];
+
+	const art = artifact as unknown as KnowledgeArtifact;
+	const { format, variant, canonicalSchemaVersion, templates } = context;
+
+	// Resolve body override for codex harness
+	const body = art.bodyOverrides?.codex ?? art.body;
+
+	// Evaluate compatibility
+	const variantContract = format.variants[variant];
+	const effectiveProfile = resolveEffectiveProfile(format, variantContract);
+	const usedCapabilities = identifyUsedCapabilities(art);
+	const evaluation = evaluateCompatibility(
+		effectiveProfile,
+		usedCapabilities,
+		art,
+	);
+	diagnostics.push(...evaluation.diagnostics);
+	degradations.push(...evaluation.degradations);
+
+	// Collect degraded sections for inline rendering
+	const degradedSections: string[] = [];
+	for (const deg of degradations) {
+		if (deg.action === "inline") {
+			degradedSections.push(
+				`<!-- Degraded: ${deg.capability} (${deg.affectedValueCount} value(s) affected) -->`,
+			);
+		}
+	}
+
+	// Render output files
+	const outputFiles: OutputFile[] = [];
+	const skillName = art.name;
+
+	const renderContext = {
+		artifact: art,
+		body,
+		degradedSections,
+	};
+
+	if (variant === "skill") {
+		// Native Codex skill discovery path + AGENTS.md pointer
+		const skillContent = templates.render("codex/skill.md.njk", renderContext);
+		outputFiles.push({
+			relativePath: `.codex/skills/${skillName}/SKILL.md`,
+			content: skillContent,
+			executable: false,
+		});
+
+		// Workflow phase files under references/
+		for (const wf of art.workflows) {
+			outputFiles.push({
+				relativePath: `.codex/skills/${skillName}/references/${wf.filename}`,
+				content: wf.content,
+				executable: false,
+			});
+		}
+
+		// AGENTS.md pointer
+		const pointerContent = templates.render(
+			"codex/agents-pointer.md.njk",
+			renderContext,
+		);
+		outputFiles.push({
+			relativePath: "AGENTS.md",
+			content: pointerContent,
+			executable: false,
+		});
+	} else {
+		// "agents-md" variant (default): repo-wide AGENTS.md with full body
+		const agentsContent = templates.render(
+			"codex/agents-md.md.njk",
+			renderContext,
+		);
+		outputFiles.push({
+			relativePath: "AGENTS.md",
+			content: agentsContent,
+			executable: false,
+		});
+	}
+
+	// MCP servers → .codex/config.toml
+	if (art.mcpServers.length > 0) {
+		const tomlContent = buildCodexMcpToml(art.mcpServers);
+		outputFiles.push({
+			relativePath: ".codex/config.toml",
+			content: tomlContent,
+			executable: false,
+		});
+	}
+
+	// Hooks diagnostic — Codex has no declarative hook system
+	if (art.hooks.length > 0) {
+		diagnostics.push(
+			createDiagnostic("RS_COMPATIBILITY_NONE", {
+				formatId: format.id,
+				message:
+					"Codex has no declarative event-hook system; hook definitions are omitted.",
+				remediation:
+					"Implement hooks as manual guidance or shell scripts for Codex environments.",
+				canonical: {
+					artifactName: art.name,
+					fieldPath: "hooks",
+				},
+			}),
+		);
+	}
+
+	// Build plan deterministically
+	const plan = createPlan(format.id, canonicalSchemaVersion, outputFiles, {
+		variant,
+	});
+
+	return { plan, diagnostics, degradations };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Internal Helpers — TOML Generation
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/** TOML string literal — escape backslashes and double quotes. */
+function tomlString(value: string): string {
+	return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+/** TOML dotted-table key segment. */
+function tomlKey(value: string): string {
+	return /^[A-Za-z0-9_-]+$/.test(value) ? value : tomlString(value);
+}
+
+/** TOML inline array of strings. */
+function tomlStringArray(values: string[]): string {
+	return `[${values.map((v) => tomlString(v)).join(", ")}]`;
+}
+
+/** TOML inline table of string env vars. */
+function tomlEnvTable(env: Record<string, string>): string {
+	const pairs = Object.entries(env).map(([k, v]) => `${k} = ${tomlString(v)}`);
+	return `{ ${pairs.join(", ")} }`;
+}
+
+/**
+ * Serialize canonical MCP server definitions into Codex `config.toml` form.
+ * Codex registers servers under `[mcp_servers.<name>]` tables.
+ */
+function buildCodexMcpToml(servers: McpServerDefinition[]): string {
+	const blocks: string[] = [
+		"# Generated by Kanon — merge into ~/.codex/config.toml or .codex/config.toml",
+	];
+	for (const server of servers) {
+		const lines = [`[mcp_servers.${tomlKey(server.name)}]`];
+		if (isStdioServer(server)) {
+			lines.push(`command = ${tomlString(server.command)}`);
+			if (server.args.length > 0) {
+				lines.push(`args = ${tomlStringArray(server.args)}`);
+			}
+			if (Object.keys(server.env).length > 0) {
+				lines.push(`env = ${tomlEnvTable(server.env)}`);
+			}
+		} else {
+			// URL-based (SSE / streamable HTTP) servers.
+			lines.push(`url = ${tomlString(server.url)}`);
+			if (server.env && Object.keys(server.env).length > 0) {
+				lines.push(`env = ${tomlEnvTable(server.env)}`);
+			}
+		}
+		if (server.timeout) {
+			lines.push(`startup_timeout_ms = ${server.timeout}`);
+		}
+		blocks.push(lines.join("\n"));
+	}
+	return `${blocks.join("\n\n")}\n`;
+}

package/src/rosetta/builtins/targets/copilot.ts

@@ -0,0 +1,103 @@
+/**
+ * Rosetta Stone — Copilot Target Translator
+ *
+ * Translates a canonical KnowledgeArtifact into GitHub Copilot's native output
+ * format (.github/copilot-instructions.md or agent file per variant).
+ *
+ * CONSTRAINTS:
+ * - NO filesystem, process, clock, random, Git, or network imports
+ * - Pure function only
+ *
+ * Requirements: 6.1, 6.5, 6.6, 12.2, 12.5, 13.8
+ */
+
+import type {
+	DegradationRecord,
+	KnowledgeArtifact,
+	OutputFile,
+	TranslationDiagnostic,
+} from "../../../schemas";
+import {
+	evaluateCompatibility,
+	identifyUsedCapabilities,
+	resolveEffectiveProfile,
+} from "../../compatibility";
+import { codePointCompare } from "../../contracts";
+import { createPlan } from "../../plan";
+import type {
+	TargetTranslationOutput,
+	TargetTranslatorContext,
+} from "../../registry";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Copilot Target Translator
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Translate a canonical artifact into Copilot-native output files.
+ *
+ * Supports variants:
+ * - "instructions" (default): .github/copilot-instructions.md
+ * - "agent": AGENTS.md
+ */
+export function translateCopilotTarget(
+	artifact: Record<string, unknown>,
+	context: TargetTranslatorContext,
+): TargetTranslationOutput {
+	const diagnostics: TranslationDiagnostic[] = [];
+	const degradations: DegradationRecord[] = [];
+
+	const art = artifact as unknown as KnowledgeArtifact;
+	const { format, variant, canonicalSchemaVersion, templates } = context;
+
+	// Resolve body override for copilot harness
+	const body = art.bodyOverrides?.copilot ?? art.body;
+
+	// Evaluate compatibility
+	const variantContract = format.variants[variant];
+	const effectiveProfile = resolveEffectiveProfile(format, variantContract);
+	const usedCapabilities = identifyUsedCapabilities(art);
+	const evaluation = evaluateCompatibility(
+		effectiveProfile,
+		usedCapabilities,
+		art,
+	);
+	diagnostics.push(...evaluation.diagnostics);
+	degradations.push(...evaluation.degradations);
+
+	// Render output files
+	const outputFiles: OutputFile[] = [];
+
+	if (variant === "agent") {
+		// Agent variant: AGENTS.md
+		const content = templates.render("copilot/agents.md.njk", {
+			artifact: art,
+			body,
+		});
+		outputFiles.push({
+			relativePath: "AGENTS.md",
+			content,
+			executable: false,
+		});
+	} else {
+		// Default "instructions" variant: .github/copilot-instructions.md
+		const content = templates.render("copilot/instructions.md.njk", {
+			artifact: art,
+			body,
+		});
+		outputFiles.push({
+			relativePath: ".github/copilot-instructions.md",
+			content,
+			executable: false,
+		});
+	}
+
+	// Sort output files deterministically by path
+	outputFiles.sort((a, b) => codePointCompare(a.relativePath, b.relativePath));
+
+	const plan = createPlan(format.id, canonicalSchemaVersion, outputFiles, {
+		variant,
+	});
+
+	return { plan, diagnostics, degradations };
+}

package/src/rosetta/builtins/targets/cursor.ts

@@ -0,0 +1,87 @@
+/**
+ * Rosetta Stone — Cursor Target Translator
+ *
+ * Translates a canonical KnowledgeArtifact into Cursor's native output
+ * format (.cursor/rules/<name>.mdc).
+ *
+ * CONSTRAINTS:
+ * - NO filesystem, process, clock, random, Git, or network imports
+ * - Pure function only
+ *
+ * Requirements: 6.1, 6.5, 6.6, 12.2, 12.5, 13.8
+ */
+
+import type {
+	DegradationRecord,
+	KnowledgeArtifact,
+	OutputFile,
+	TranslationDiagnostic,
+} from "../../../schemas";
+import {
+	evaluateCompatibility,
+	identifyUsedCapabilities,
+	resolveEffectiveProfile,
+} from "../../compatibility";
+import { codePointCompare } from "../../contracts";
+import { createPlan } from "../../plan";
+import type {
+	TargetTranslationOutput,
+	TargetTranslatorContext,
+} from "../../registry";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Cursor Target Translator
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Translate a canonical artifact into Cursor-native output files.
+ *
+ * Produces .cursor/rules/<artifact-name>.mdc
+ */
+export function translateCursorTarget(
+	artifact: Record<string, unknown>,
+	context: TargetTranslatorContext,
+): TargetTranslationOutput {
+	const diagnostics: TranslationDiagnostic[] = [];
+	const degradations: DegradationRecord[] = [];
+
+	const art = artifact as unknown as KnowledgeArtifact;
+	const { format, variant, canonicalSchemaVersion, templates } = context;
+
+	// Resolve body override for cursor harness
+	const body = art.bodyOverrides?.cursor ?? art.body;
+
+	// Evaluate compatibility
+	const variantContract = format.variants[variant];
+	const effectiveProfile = resolveEffectiveProfile(format, variantContract);
+	const usedCapabilities = identifyUsedCapabilities(art);
+	const evaluation = evaluateCompatibility(
+		effectiveProfile,
+		usedCapabilities,
+		art,
+	);
+	diagnostics.push(...evaluation.diagnostics);
+	degradations.push(...evaluation.degradations);
+
+	// Render output files
+	const outputFiles: OutputFile[] = [];
+
+	const content = templates.render("cursor/rule.md.njk", {
+		artifact: art,
+		body,
+	});
+	outputFiles.push({
+		relativePath: `.cursor/rules/${art.name}.mdc`,
+		content,
+		executable: false,
+	});
+
+	// Sort output files deterministically by path
+	outputFiles.sort((a, b) => codePointCompare(a.relativePath, b.relativePath));
+
+	const plan = createPlan(format.id, canonicalSchemaVersion, outputFiles, {
+		variant,
+	});
+
+	return { plan, diagnostics, degradations };
+}

package/src/rosetta/builtins/targets/index.ts

@@ -0,0 +1,60 @@
+/**
+ * Rosetta Stone — Built-in Target Translator Registry
+ *
+ * Exports all target translators and a lookup map from format identifiers
+ * to their translator implementations.
+ *
+ * CONSTRAINTS:
+ * - NO filesystem, process, clock, random, Git, or network imports
+ * - Pure re-exports only
+ *
+ * Requirements: 6.1, 6.5, 6.6, 7.3, 7.5, 12.2, 12.5, 13.8
+ */
+
+import type { FormatIdentifier } from "../../../schemas";
+import type { TargetTranslator } from "../../registry";
+import { translateClaudeCodeTarget } from "./claude-code";
+import { translateClineTarget } from "./cline";
+import { translateCodexTarget } from "./codex";
+import { translateCopilotTarget } from "./copilot";
+import { translateCursorTarget } from "./cursor";
+import { translateKiroTarget } from "./kiro";
+import { translateQDeveloperTarget } from "./qdeveloper";
+import { translateWindsurfTarget } from "./windsurf";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Re-exports
+// ═══════════════════════════════════════════════════════════════════════════════
+
+export { translateClaudeCodeTarget } from "./claude-code";
+export { translateClineTarget } from "./cline";
+export { translateCodexTarget } from "./codex";
+export { translateCopilotTarget } from "./copilot";
+export { translateCursorTarget } from "./cursor";
+export { translateKiroTarget } from "./kiro";
+export { translateQDeveloperTarget } from "./qdeveloper";
+export { translateWindsurfTarget } from "./windsurf";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Target Translator Map
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Maps format identifiers to their target translators.
+ *
+ * These handle outbound translation from canonical artifacts to harness-native
+ * output files.
+ */
+export const TARGET_TRANSLATORS: ReadonlyMap<
+	FormatIdentifier,
+	TargetTranslator
+> = new Map<FormatIdentifier, TargetTranslator>([
+	["kiro" as FormatIdentifier, translateKiroTarget],
+	["claude-code" as FormatIdentifier, translateClaudeCodeTarget],
+	["codex" as FormatIdentifier, translateCodexTarget],
+	["copilot" as FormatIdentifier, translateCopilotTarget],
+	["cursor" as FormatIdentifier, translateCursorTarget],
+	["windsurf" as FormatIdentifier, translateWindsurfTarget],
+	["cline" as FormatIdentifier, translateClineTarget],
+	["qdeveloper" as FormatIdentifier, translateQDeveloperTarget],
+]);