@thinkingsage/kanon 0.8.0

package/src/rosetta/builtins/pretty-printers/claude-code-native.ts

@@ -0,0 +1,122 @@
+/**
+ * Rosetta Stone — Claude Code Native Pretty-Printer
+ *
+ * Renders a canonical KnowledgeArtifact back into Claude Code native format:
+ * - `CLAUDE.md` body
+ * - `.claude/settings.json` from hooks (commands)
+ * - `.claude/mcp.json` from mcpServers
+ *
+ * CONSTRAINTS:
+ * - NO filesystem, process, clock, random, Git, or network imports
+ * - Pure function only
+ *
+ * Requirements: 5.4, 12.4, 16.2
+ */
+
+import type {
+	CanonicalHook,
+	McpServerDefinition,
+	NormalizedRelativePath,
+	SourceDocument,
+	TranslationDiagnostic,
+} from "../../../schemas";
+import { codePointCompare, stableJsonStringify } from "../../contracts";
+import type {
+	SourcePrintOutput,
+	SourceTranslatorContext,
+} from "../../registry";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Pretty-Printer
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Pretty-print a canonical KnowledgeArtifact into Claude Code native format.
+ *
+ * Produces:
+ * - `CLAUDE.md` with the artifact body
+ * - `.claude/settings.json` from hooks (agent_stop → commands)
+ * - `.claude/mcp.json` from mcpServers
+ */
+export function prettyPrintClaudeCodeNative(
+	artifact: Record<string, unknown>,
+	_context: SourceTranslatorContext,
+): SourcePrintOutput {
+	const diagnostics: TranslationDiagnostic[] = [];
+	const documents: SourceDocument[] = [];
+
+	const body = (artifact.body as string) ?? "";
+	const hooks = (artifact.hooks as CanonicalHook[]) ?? [];
+	const mcpServers = (artifact.mcpServers as McpServerDefinition[]) ?? [];
+
+	// Render CLAUDE.md
+	documents.push({
+		path: "CLAUDE.md" as NormalizedRelativePath,
+		content: `${body}\n`,
+		executable: false,
+	});
+
+	// Render .claude/settings.json from hooks (agent_stop events → commands)
+	const commands: string[] = [];
+	const sortedHooks = [...hooks].sort((a, b) =>
+		codePointCompare(a.name, b.name),
+	);
+
+	for (const hook of sortedHooks) {
+		if (hook.event === "agent_stop" && hook.action?.type === "run_command") {
+			commands.push(hook.action.command);
+		}
+	}
+
+	if (commands.length > 0) {
+		const settingsObj: Record<string, unknown> = { commands };
+		const settingsJson = stableJsonStringify(settingsObj);
+		documents.push({
+			path: ".claude/settings.json" as NormalizedRelativePath,
+			content: `${settingsJson}\n`,
+			executable: false,
+		});
+	}
+
+	// Render .claude/mcp.json from mcpServers
+	if (mcpServers.length > 0) {
+		const mcpObj: Record<string, unknown> = {};
+		const sortedServers = [...mcpServers].sort((a, b) =>
+			codePointCompare(a.name, b.name),
+		);
+
+		for (const server of sortedServers) {
+			const serverConfig: Record<string, unknown> = {};
+			if (server.transport === "stdio") {
+				serverConfig.command = server.command;
+				if (server.args && server.args.length > 0) {
+					serverConfig.args = server.args;
+				}
+			} else {
+				serverConfig.url = server.url;
+				if (server.transport === "http") {
+					serverConfig.type = "http";
+				}
+			}
+			if (server.env && Object.keys(server.env).length > 0) {
+				serverConfig.env = server.env;
+			}
+			if (server.timeout !== undefined) {
+				serverConfig.timeout = server.timeout;
+			}
+			if (server.autoApprove && server.autoApprove.length > 0) {
+				serverConfig.autoApprove = server.autoApprove;
+			}
+			mcpObj[server.name] = serverConfig;
+		}
+
+		const mcpJson = stableJsonStringify({ mcpServers: mcpObj });
+		documents.push({
+			path: ".claude/mcp.json" as NormalizedRelativePath,
+			content: `${mcpJson}\n`,
+			executable: false,
+		});
+	}
+
+	return { documents, diagnostics };
+}

package/src/rosetta/builtins/pretty-printers/cline-native.ts

@@ -0,0 +1,50 @@
+/**
+ * Rosetta Stone — Cline Native Pretty-Printer
+ *
+ * Renders a canonical KnowledgeArtifact back into Cline native format:
+ * - `.clinerules` with body content
+ *
+ * CONSTRAINTS:
+ * - NO filesystem, process, clock, random, Git, or network imports
+ * - Pure function only
+ *
+ * Requirements: 5.4, 12.4, 16.2
+ */
+
+import type {
+	NormalizedRelativePath,
+	SourceDocument,
+	TranslationDiagnostic,
+} from "../../../schemas";
+import type {
+	SourcePrintOutput,
+	SourceTranslatorContext,
+} from "../../registry";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Pretty-Printer
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Pretty-print a canonical KnowledgeArtifact into Cline native format.
+ *
+ * Produces:
+ * - `.clinerules` with the artifact body
+ */
+export function prettyPrintClineNative(
+	artifact: Record<string, unknown>,
+	_context: SourceTranslatorContext,
+): SourcePrintOutput {
+	const diagnostics: TranslationDiagnostic[] = [];
+	const documents: SourceDocument[] = [];
+
+	const body = (artifact.body as string) ?? "";
+
+	documents.push({
+		path: ".clinerules" as NormalizedRelativePath,
+		content: `${body}\n`,
+		executable: false,
+	});
+
+	return { documents, diagnostics };
+}

package/src/rosetta/builtins/pretty-printers/codex-native.ts

@@ -0,0 +1,127 @@
+/**
+ * Rosetta Stone — Codex Native Pretty-Printer
+ *
+ * Renders a canonical KnowledgeArtifact back into Codex native format:
+ * - `AGENTS.md` body
+ * - `.codex/config.toml` from mcpServers (TOML format)
+ *
+ * CONSTRAINTS:
+ * - NO filesystem, process, clock, random, Git, or network imports
+ * - Pure function only
+ *
+ * Requirements: 5.4, 12.4, 16.2
+ */
+
+import type {
+	McpServerDefinition,
+	NormalizedRelativePath,
+	SourceDocument,
+	TranslationDiagnostic,
+} from "../../../schemas";
+import { codePointCompare } from "../../contracts";
+import type {
+	SourcePrintOutput,
+	SourceTranslatorContext,
+} from "../../registry";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// TOML Rendering Helper
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Render MCP server definitions as TOML [mcp_servers.<name>] tables.
+ */
+function renderMcpToml(servers: McpServerDefinition[]): string {
+	const lines: string[] = [];
+
+	for (const server of servers) {
+		lines.push(`[mcp_servers.${quoteTomlKey(server.name)}]`);
+
+		if (server.transport === "stdio") {
+			lines.push(`command = ${quoteTomlString(server.command ?? "")}`);
+			if (server.args && server.args.length > 0) {
+				const argsStr = server.args.map(quoteTomlString).join(", ");
+				lines.push(`args = [${argsStr}]`);
+			}
+		} else if (server.url) {
+			lines.push(`url = ${quoteTomlString(server.url)}`);
+		}
+
+		if (server.env && Object.keys(server.env).length > 0) {
+			const envEntries = Object.keys(server.env)
+				.sort(codePointCompare)
+				.map((k) => `${quoteTomlKey(k)} = ${quoteTomlString(server.env?.[k])}`)
+				.join(", ");
+			lines.push(`env = { ${envEntries} }`);
+		}
+
+		if (server.timeout !== undefined) {
+			lines.push(`startup_timeout_ms = ${server.timeout}`);
+		}
+
+		lines.push("");
+	}
+
+	return lines.join("\n");
+}
+
+/**
+ * Quote a string for TOML output.
+ */
+function quoteTomlString(value: string): string {
+	return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+/**
+ * Quote a TOML key if it contains special characters.
+ */
+function quoteTomlKey(key: string): string {
+	if (/^[a-zA-Z0-9_-]+$/.test(key)) {
+		return key;
+	}
+	return quoteTomlString(key);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Pretty-Printer
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Pretty-print a canonical KnowledgeArtifact into Codex native format.
+ *
+ * Produces:
+ * - `AGENTS.md` with the artifact body
+ * - `.codex/config.toml` from mcpServers in TOML format
+ */
+export function prettyPrintCodexNative(
+	artifact: Record<string, unknown>,
+	_context: SourceTranslatorContext,
+): SourcePrintOutput {
+	const diagnostics: TranslationDiagnostic[] = [];
+	const documents: SourceDocument[] = [];
+
+	const body = (artifact.body as string) ?? "";
+	const mcpServers = (artifact.mcpServers as McpServerDefinition[]) ?? [];
+
+	// Render AGENTS.md
+	documents.push({
+		path: "AGENTS.md" as NormalizedRelativePath,
+		content: `${body}\n`,
+		executable: false,
+	});
+
+	// Render .codex/config.toml from mcpServers
+	if (mcpServers.length > 0) {
+		const sortedServers = [...mcpServers].sort((a, b) =>
+			codePointCompare(a.name, b.name),
+		);
+		const tomlContent = renderMcpToml(sortedServers);
+		documents.push({
+			path: ".codex/config.toml" as NormalizedRelativePath,
+			content: tomlContent,
+			executable: false,
+		});
+	}
+
+	return { documents, diagnostics };
+}

package/src/rosetta/builtins/pretty-printers/copilot-native.ts

@@ -0,0 +1,50 @@
+/**
+ * Rosetta Stone — Copilot Native Pretty-Printer
+ *
+ * Renders a canonical KnowledgeArtifact back into Copilot native format:
+ * - `.github/copilot-instructions.md` with body content
+ *
+ * CONSTRAINTS:
+ * - NO filesystem, process, clock, random, Git, or network imports
+ * - Pure function only
+ *
+ * Requirements: 5.4, 12.4, 16.2
+ */
+
+import type {
+	NormalizedRelativePath,
+	SourceDocument,
+	TranslationDiagnostic,
+} from "../../../schemas";
+import type {
+	SourcePrintOutput,
+	SourceTranslatorContext,
+} from "../../registry";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Pretty-Printer
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Pretty-print a canonical KnowledgeArtifact into Copilot native format.
+ *
+ * Produces:
+ * - `.github/copilot-instructions.md` with the artifact body
+ */
+export function prettyPrintCopilotNative(
+	artifact: Record<string, unknown>,
+	_context: SourceTranslatorContext,
+): SourcePrintOutput {
+	const diagnostics: TranslationDiagnostic[] = [];
+	const documents: SourceDocument[] = [];
+
+	const body = (artifact.body as string) ?? "";
+
+	documents.push({
+		path: ".github/copilot-instructions.md" as NormalizedRelativePath,
+		content: `${body}\n`,
+		executable: false,
+	});
+
+	return { documents, diagnostics };
+}

package/src/rosetta/builtins/pretty-printers/cursor-native.ts

@@ -0,0 +1,50 @@
+/**
+ * Rosetta Stone — Cursor Native Pretty-Printer
+ *
+ * Renders a canonical KnowledgeArtifact back into Cursor native format:
+ * - `.cursorrules` with body content
+ *
+ * CONSTRAINTS:
+ * - NO filesystem, process, clock, random, Git, or network imports
+ * - Pure function only
+ *
+ * Requirements: 5.4, 12.4, 16.2
+ */
+
+import type {
+	NormalizedRelativePath,
+	SourceDocument,
+	TranslationDiagnostic,
+} from "../../../schemas";
+import type {
+	SourcePrintOutput,
+	SourceTranslatorContext,
+} from "../../registry";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Pretty-Printer
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Pretty-print a canonical KnowledgeArtifact into Cursor native format.
+ *
+ * Produces:
+ * - `.cursorrules` with the artifact body
+ */
+export function prettyPrintCursorNative(
+	artifact: Record<string, unknown>,
+	_context: SourceTranslatorContext,
+): SourcePrintOutput {
+	const diagnostics: TranslationDiagnostic[] = [];
+	const documents: SourceDocument[] = [];
+
+	const body = (artifact.body as string) ?? "";
+
+	documents.push({
+		path: ".cursorrules" as NormalizedRelativePath,
+		content: `${body}\n`,
+		executable: false,
+	});
+
+	return { documents, diagnostics };
+}

package/src/rosetta/builtins/pretty-printers/index.ts

@@ -0,0 +1,81 @@
+/**
+ * Rosetta Stone — Built-in Pretty-Printer Registry
+ *
+ * Exports all pretty-printers (path-based and harness-native) and a lookup
+ * map from format identifiers to their pretty-printer implementations.
+ *
+ * Pretty-printers exist for round-trip verification and migration inspection;
+ * direction still controls whether users may request that representation as
+ * an outbound target.
+ *
+ * CONSTRAINTS:
+ * - NO filesystem, process, clock, random, Git, or network imports
+ * - Pure re-exports only
+ *
+ * Requirements: 5.4, 12.4, 16.2
+ */
+
+import type { FormatIdentifier } from "../../../schemas";
+import type { PrettyPrinter } from "../../registry";
+import { prettyPrintClaudeCodeNative } from "./claude-code-native";
+import { prettyPrintClineNative } from "./cline-native";
+import { prettyPrintCodexNative } from "./codex-native";
+import { prettyPrintCopilotNative } from "./copilot-native";
+import { prettyPrintCursorNative } from "./cursor-native";
+import { prettyPrintKiroNative } from "./kiro-native";
+import { prettyPrintKiroPower } from "./kiro-power";
+import { prettyPrintKiroSkill } from "./kiro-skill";
+import { prettyPrintQDeveloperNative } from "./qdeveloper-native";
+import { prettyPrintSuperpowers } from "./superpowers";
+import { prettyPrintWindsurfNative } from "./windsurf-native";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Re-exports — Path-based format pretty-printers
+// ═══════════════════════════════════════════════════════════════════════════════
+
+export { prettyPrintKiroPower } from "./kiro-power";
+export { prettyPrintKiroSkill } from "./kiro-skill";
+export { prettyPrintSuperpowers } from "./superpowers";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Re-exports — Harness-native pretty-printers
+// ═══════════════════════════════════════════════════════════════════════════════
+
+export { prettyPrintClaudeCodeNative } from "./claude-code-native";
+export { prettyPrintCodexNative } from "./codex-native";
+export { prettyPrintKiroNative } from "./kiro-native";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Re-exports — Simple harness pretty-printers
+// ═══════════════════════════════════════════════════════════════════════════════
+
+export { prettyPrintClineNative } from "./cline-native";
+export { prettyPrintCopilotNative } from "./copilot-native";
+export { prettyPrintCursorNative } from "./cursor-native";
+export { prettyPrintQDeveloperNative } from "./qdeveloper-native";
+export { prettyPrintWindsurfNative } from "./windsurf-native";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Pretty-Printer Lookup Map
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Maps format identifiers to their corresponding pretty-printer implementations.
+ *
+ * Every source-capable built-in has a corresponding pretty-printer for
+ * round-trip verification and migration inspection.
+ */
+export const PRETTY_PRINTERS: ReadonlyMap<FormatIdentifier, PrettyPrinter> =
+	new Map<FormatIdentifier, PrettyPrinter>([
+		["kiro-power" as FormatIdentifier, prettyPrintKiroPower],
+		["kiro-skill" as FormatIdentifier, prettyPrintKiroSkill],
+		["superpowers" as FormatIdentifier, prettyPrintSuperpowers],
+		["kiro" as FormatIdentifier, prettyPrintKiroNative],
+		["claude-code" as FormatIdentifier, prettyPrintClaudeCodeNative],
+		["codex" as FormatIdentifier, prettyPrintCodexNative],
+		["copilot" as FormatIdentifier, prettyPrintCopilotNative],
+		["cursor" as FormatIdentifier, prettyPrintCursorNative],
+		["windsurf" as FormatIdentifier, prettyPrintWindsurfNative],
+		["cline" as FormatIdentifier, prettyPrintClineNative],
+		["qdeveloper" as FormatIdentifier, prettyPrintQDeveloperNative],
+	]);

package/src/rosetta/builtins/pretty-printers/kiro-native.ts

@@ -0,0 +1,166 @@
+/**
+ * Rosetta Stone — Kiro Native Pretty-Printer
+ *
+ * Renders a canonical KnowledgeArtifact back into the Kiro native format:
+ * - Primary steering markdown (frontmatter + body)
+ * - Hook files as JSON
+ * - MCP server definitions as JSON
+ *
+ * CONSTRAINTS:
+ * - NO filesystem, process, clock, random, Git, or network imports
+ * - Pure function only
+ *
+ * Requirements: 5.4, 12.4, 16.2
+ */
+
+import type {
+	CanonicalHook,
+	McpServerDefinition,
+	NormalizedRelativePath,
+	SourceDocument,
+	TranslationDiagnostic,
+} from "../../../schemas";
+import { renderDeterministicYaml } from "../../canonical";
+import { codePointCompare, stableJsonStringify } from "../../contracts";
+import type {
+	SourcePrintOutput,
+	SourceTranslatorContext,
+} from "../../registry";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Pretty-Printer
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Pretty-print a canonical KnowledgeArtifact into Kiro native format.
+ *
+ * Produces:
+ * - Primary steering markdown with frontmatter
+ * - `hooks/<name>.kiro.hook` JSON files for each hook
+ * - `mcp.json` for MCP server definitions
+ */
+export function prettyPrintKiroNative(
+	artifact: Record<string, unknown>,
+	_context: SourceTranslatorContext,
+): SourcePrintOutput {
+	const diagnostics: TranslationDiagnostic[] = [];
+	const documents: SourceDocument[] = [];
+
+	const fm = (artifact.frontmatter ?? {}) as Record<string, unknown>;
+	const body = (artifact.body as string) ?? "";
+	const hooks = (artifact.hooks as CanonicalHook[]) ?? [];
+	const mcpServers = (artifact.mcpServers as McpServerDefinition[]) ?? [];
+	const name = (artifact.name as string) ?? "unnamed";
+
+	// Build the primary markdown frontmatter
+	const steeringFm: Record<string, unknown> = {};
+	const STEERING_KEY_ORDER = [
+		"name",
+		"displayName",
+		"description",
+		"keywords",
+		"author",
+		"version",
+		"type",
+		"harnesses",
+		"inclusion",
+		"file_patterns",
+		"categories",
+		"ecosystem",
+		"depends",
+		"enhances",
+		"maturity",
+		"trust",
+		"audience",
+	];
+
+	for (const key of STEERING_KEY_ORDER) {
+		if (fm[key] !== undefined) {
+			steeringFm[key] = fm[key];
+		}
+	}
+	// Add remaining keys in code-point order
+	const remainingKeys = Object.keys(fm)
+		.filter((k) => !STEERING_KEY_ORDER.includes(k))
+		.sort(codePointCompare);
+	for (const key of remainingKeys) {
+		if (fm[key] !== undefined) {
+			steeringFm[key] = fm[key];
+		}
+	}
+
+	// Render primary markdown
+	const frontmatterYaml = renderDeterministicYaml(
+		steeringFm,
+		STEERING_KEY_ORDER,
+	);
+	const primaryPath = `${name}.md`;
+	const primaryContent = `---\n${frontmatterYaml}---\n${body}\n`;
+
+	documents.push({
+		path: primaryPath as NormalizedRelativePath,
+		content: primaryContent,
+		executable: false,
+	});
+
+	// Render hook files as JSON
+	const sortedHooks = [...hooks].sort((a, b) =>
+		codePointCompare(a.name, b.name),
+	);
+
+	for (const hook of sortedHooks) {
+		const hookObj: Record<string, unknown> = {
+			name: hook.name,
+			event: hook.event,
+		};
+		if (hook.description) hookObj.description = hook.description;
+		if (hook.condition) hookObj.condition = hook.condition;
+		hookObj.action = hook.action;
+		if (hook.gate) hookObj.gate = hook.gate;
+		if (hook.postcondition) hookObj.postcondition = hook.postcondition;
+
+		const hookJson = stableJsonStringify(hookObj);
+		documents.push({
+			path: `hooks/${hook.name}.kiro.hook` as NormalizedRelativePath,
+			content: `${hookJson}\n`,
+			executable: false,
+		});
+	}
+
+	// Render MCP server definitions as JSON
+	if (mcpServers.length > 0) {
+		const mcpObj: Record<string, unknown> = {};
+		const sortedServers = [...mcpServers].sort((a, b) =>
+			codePointCompare(a.name, b.name),
+		);
+
+		for (const server of sortedServers) {
+			const serverConfig: Record<string, unknown> = {};
+			if (server.transport === "stdio") {
+				serverConfig.command = server.command;
+				if (server.args && server.args.length > 0) {
+					serverConfig.args = server.args;
+				}
+			} else {
+				serverConfig.url = server.url;
+				serverConfig.type = server.transport;
+			}
+			if (server.env && Object.keys(server.env).length > 0) {
+				serverConfig.env = server.env;
+			}
+			if (server.timeout !== undefined) {
+				serverConfig.timeout = server.timeout;
+			}
+			mcpObj[server.name] = serverConfig;
+		}
+
+		const mcpJson = stableJsonStringify({ mcpServers: mcpObj });
+		documents.push({
+			path: "mcp.json" as NormalizedRelativePath,
+			content: `${mcpJson}\n`,
+			executable: false,
+		});
+	}
+
+	return { documents, diagnostics };
+}