@thinkingsage/kanon 0.8.0

package/src/rosetta/builtins/sources/superpowers.ts

@@ -0,0 +1,240 @@
+/**
+ * Rosetta Stone — Superpowers Source Translator
+ *
+ * Pure translator for the `superpowers` format:
+ * - Consumes `SKILL.md` → extracts frontmatter (name, description) and body
+ * - Consumes companion `.md` files → maps to workflows
+ * - Sets reasonable defaults for missing fields
+ * - Sets `type: "skill"`, `harnesses: ["claude-code", "codex", "cursor"]`
+ *
+ * CONSTRAINTS:
+ * - NO filesystem, process, clock, random, Git, or network imports
+ * - Pure function only
+ *
+ * Requirements: 2.9, 4.1, 4.2, 4.3, 4.5, 13.7, 14.3
+ */
+
+import matter from "gray-matter";
+
+import type {
+	KnowledgeArtifact,
+	NormalizedRelativePath,
+	SourceDocument,
+	TranslationDiagnostic,
+} from "../../../schemas";
+import { codePointCompare } from "../../contracts";
+import { createDiagnostic } from "../../diagnostics";
+import type {
+	SourceTranslationOutput,
+	SourceTranslatorContext,
+} from "../../registry";
+import { SourceAccountant } from "../../source-accounting";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Translator
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Translate a superpowers document set into a canonical KnowledgeArtifact candidate.
+ *
+ * Expected documents:
+ * - `SKILL.md` (required): YAML frontmatter + Markdown body
+ * - Other `*.md` files (optional): mapped to workflows as companions
+ * - Non-md files: preserved
+ */
+export function translateSuperpowers(
+	documents: readonly SourceDocument[],
+	context: SourceTranslatorContext,
+): SourceTranslationOutput {
+	const accountant = new SourceAccountant();
+	const diagnostics: TranslationDiagnostic[] = [];
+
+	// Find SKILL.md
+	const skillDoc = documents.find((d) => d.path === "SKILL.md");
+	if (!skillDoc) {
+		diagnostics.push(
+			createDiagnostic("RS_CANONICAL_MISSING_KNOWLEDGE_MD", {
+				formatId: "superpowers",
+				message: "SKILL.md not found in the provided document set.",
+				source: { path: "SKILL.md" as NormalizedRelativePath },
+			}),
+		);
+		for (const doc of documents) {
+			accountant.preserve(doc.path);
+		}
+		return {
+			diagnostics,
+			consumedPaths: accountant.getConsumedPaths(),
+			preservedPaths: accountant.getPreservedPaths(),
+		};
+	}
+
+	// Parse SKILL.md frontmatter
+	const rawContent =
+		typeof skillDoc.content === "string"
+			? skillDoc.content
+			: new TextDecoder().decode(skillDoc.content);
+
+	let parsed: matter.GrayMatterFile<string>;
+	try {
+		parsed = matter(rawContent);
+	} catch {
+		diagnostics.push(
+			createDiagnostic("RS_CANONICAL_INVALID_FRONTMATTER", {
+				formatId: "superpowers",
+				message: "The frontmatter YAML in SKILL.md could not be parsed.",
+				source: { path: "SKILL.md" as NormalizedRelativePath },
+			}),
+		);
+		for (const doc of documents) {
+			accountant.preserve(doc.path);
+		}
+		return {
+			diagnostics,
+			consumedPaths: accountant.getConsumedPaths(),
+			preservedPaths: accountant.getPreservedPaths(),
+		};
+	}
+
+	accountant.consume("SKILL.md");
+
+	const sourceFm = parsed.data as Record<string, unknown>;
+	const body = parsed.content.trim();
+
+	// Resolve artifact name from caller context or frontmatter
+	const artifactNameHint = context.callerContext?.artifactNameHint as
+		| string
+		| undefined;
+	const name = String(sourceFm.name || artifactNameHint || "unnamed-skill");
+
+	// Map fields
+	accountant.mapField("SKILL.md", "name", "name", false);
+	accountant.mapField("SKILL.md", "description", "description", false);
+
+	// Collect companion .md files as workflows (exclude SKILL.md itself)
+	const companionDocs = documents
+		.filter((d) => d.path !== "SKILL.md" && d.path.endsWith(".md"))
+		.sort((a, b) => codePointCompare(a.path, b.path));
+
+	const workflows = companionDocs.map((doc) => {
+		accountant.consume(doc.path);
+		const content =
+			typeof doc.content === "string"
+				? doc.content
+				: new TextDecoder().decode(doc.content);
+		const name = doc.path.replace(/\.md$/, "");
+		return { name, filename: doc.path, content };
+	});
+
+	// Preserve non-md files
+	for (const doc of documents) {
+		if (doc.path === "SKILL.md") continue;
+		if (doc.path.endsWith(".md")) continue;
+		accountant.preserve(doc.path);
+	}
+
+	// Extract keywords from frontmatter
+	const keywords: string[] = [];
+	if (Array.isArray(sourceFm.keywords)) {
+		keywords.push(...sourceFm.keywords.map(String));
+		accountant.mapField("SKILL.md", "keywords", "keywords", false);
+	}
+
+	// Extract depends from requires
+	const depends: string[] = [];
+	if (Array.isArray(sourceFm.requires)) {
+		depends.push(...sourceFm.requires.map(String));
+		accountant.mapField("SKILL.md", "requires", "depends", true);
+	}
+
+	// Apply defaults
+	const appliedDefaults: Array<{
+		field: string;
+		value: unknown;
+		rule: string;
+	}> = [];
+
+	// DisplayName: derive from name if not provided
+	const displayName = String(
+		sourceFm.displayName ||
+			name.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase()),
+	);
+	if (!sourceFm.displayName) {
+		appliedDefaults.push({
+			field: "displayName",
+			value: displayName,
+			rule: "superpowers-default-displayName",
+		});
+	}
+
+	const description = String(sourceFm.description || "");
+
+	const author = String(sourceFm.author || "obra");
+	if (!sourceFm.author) {
+		appliedDefaults.push({
+			field: "author",
+			value: author,
+			rule: "superpowers-default-author",
+		});
+	}
+
+	const version = "0.1.0";
+	appliedDefaults.push({
+		field: "version",
+		value: version,
+		rule: "superpowers-default-version",
+	});
+
+	// Emit diagnostics for applied defaults
+	for (const def of appliedDefaults) {
+		accountant.applyDefault(def.field, def.value, def.rule);
+		diagnostics.push(
+			createDiagnostic("RS_DEFAULT_APPLIED", {
+				formatId: "superpowers",
+				message: `Default applied for "${def.field}": ${JSON.stringify(def.value)}`,
+				source: { path: "SKILL.md" as NormalizedRelativePath },
+			}),
+		);
+	}
+
+	// Build canonical candidate
+	const candidate: KnowledgeArtifact = {
+		name,
+		frontmatter: {
+			name,
+			displayName,
+			description,
+			keywords,
+			author,
+			version,
+			harnesses: ["claude-code", "codex", "cursor"],
+			type: "skill",
+			inclusion: "manual",
+			categories: ["documentation"],
+			ecosystem: [],
+			depends,
+			enhances: [],
+			maturity: "stable",
+			trust: "community",
+			audience: "intermediate",
+			"model-assumptions": [],
+			collections: [],
+			"inherit-hooks": false,
+			outcomes: [],
+		},
+		body,
+		hooks: [],
+		mcpServers: [],
+		workflows,
+		sourcePath: "SKILL.md",
+		extraFields: {},
+		bodyOverrides: {},
+	};
+
+	return {
+		candidate,
+		diagnostics,
+		consumedPaths: accountant.getConsumedPaths(),
+		preservedPaths: accountant.getPreservedPaths(),
+	};
+}

package/src/rosetta/builtins/sources/windsurf-native.ts

@@ -0,0 +1,176 @@
+/**
+ * Rosetta Stone — Windsurf Harness-Native Source Translator
+ *
+ * Translates Windsurf's native format (.windsurfrules or .windsurf/rules/*.md)
+ * into a canonical KnowledgeArtifact candidate.
+ *
+ * CONSTRAINTS:
+ * - NO filesystem, process, clock, random, Git, or network imports
+ * - Pure function only
+ *
+ * Requirements: 2.9, 4.1, 4.2, 4.3, 4.5, 4.6
+ */
+
+import matter from "gray-matter";
+import type { SourceDocument, TranslationDiagnostic } from "../../../schemas";
+import { createDiagnostic } from "../../diagnostics";
+import type {
+	SourceTranslationOutput,
+	SourceTranslatorContext,
+} from "../../registry";
+import {
+	normalizeDocumentOrder,
+	SourceAccountant,
+} from "../../source-accounting";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Internal helpers
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Checks if a document is the root .windsurfrules file.
+ */
+function isWindsurfRulesRoot(path: string): boolean {
+	return path === ".windsurfrules" || path.endsWith("/.windsurfrules");
+}
+
+/**
+ * Checks if a document is a Windsurf rule file under .windsurf/rules/.
+ */
+function isWindsurfRuleFile(path: string): boolean {
+	return (
+		(path.includes(".windsurf/rules/") || path.includes(".windsurf/rules\\")) &&
+		path.endsWith(".md")
+	);
+}
+
+/**
+ * Checks if a document is any recognized Windsurf file.
+ */
+function isWindsurfFile(path: string): boolean {
+	return isWindsurfRulesRoot(path) || isWindsurfRuleFile(path);
+}
+
+/**
+ * Derives a kebab-case artifact name from a document path.
+ */
+function deriveArtifactName(path: string): string {
+	const segments = path.split("/");
+	const base = segments[segments.length - 1] ?? "";
+	const name = base.replace(/\.[^.]+$/, "");
+	return name
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-|-$/g, "");
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Exported Translator
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Windsurf harness-native source translator.
+ *
+ * Consumes:
+ * - .windsurfrules → body content becomes the artifact body
+ * - .windsurf/rules/*.md → rule file body content
+ *
+ * Sets type: "rule" and harnesses: ["windsurf"]
+ */
+export function translateWindsurfNative(
+	documents: readonly SourceDocument[],
+	context: SourceTranslatorContext,
+): SourceTranslationOutput {
+	const accountant = new SourceAccountant();
+	const diagnostics: TranslationDiagnostic[] = [];
+	const sorted = normalizeDocumentOrder(documents);
+
+	// Determine artifact name from caller context
+	const artifactNameHint = context.callerContext.artifactNameHint as
+		| string
+		| undefined;
+
+	// Classify documents — prefer .windsurfrules, fall back to rule dir files
+	const rootRuleDocs = sorted.filter((d) => isWindsurfRulesRoot(d.path));
+	const ruleDirDocs = sorted.filter((d) => isWindsurfRuleFile(d.path));
+
+	const primaryDoc = rootRuleDocs[0] ?? ruleDirDocs[0];
+
+	// Handle missing primary file
+	if (!primaryDoc) {
+		diagnostics.push(
+			createDiagnostic("RS_CANONICAL_MISSING_KNOWLEDGE_MD", {
+				formatId: context.format.id,
+				message:
+					"No .windsurfrules or .windsurf/rules/ file found in the document set.",
+			}),
+		);
+		return {
+			diagnostics,
+			consumedPaths: accountant.getConsumedPaths(),
+			preservedPaths: accountant.getPreservedPaths(),
+		};
+	}
+
+	// Parse primary file
+	const content =
+		typeof primaryDoc.content === "string"
+			? primaryDoc.content
+			: new TextDecoder().decode(primaryDoc.content);
+
+	let frontmatterData: Record<string, unknown> = {};
+	let body = "";
+
+	try {
+		const parsed = matter(content);
+		frontmatterData = { ...parsed.data };
+		body = parsed.content.trim();
+	} catch {
+		diagnostics.push(
+			createDiagnostic("RS_CANONICAL_INVALID_FRONTMATTER", {
+				formatId: context.format.id,
+				message: `Failed to parse frontmatter in "${primaryDoc.path}".`,
+				source: { path: primaryDoc.path },
+			}),
+		);
+		body = content.trim();
+	}
+
+	accountant.consume(primaryDoc.path);
+	accountant.mapField(primaryDoc.path, "content", "body");
+
+	// Mark remaining files as preserved
+	for (const doc of sorted) {
+		if (doc.path !== primaryDoc.path && isWindsurfFile(doc.path)) {
+			accountant.preserve(doc.path);
+		}
+	}
+
+	// Derive artifact name
+	const name = artifactNameHint ?? deriveArtifactName(primaryDoc.path);
+
+	// Build the canonical candidate
+	const candidate: Record<string, unknown> = {
+		name,
+		frontmatter: {
+			name,
+			...frontmatterData,
+			type: "rule",
+			harnesses: ["windsurf"],
+		},
+		body,
+		hooks: [],
+		mcpServers: [],
+		workflows: [],
+		sourcePath: primaryDoc.path,
+		extraFields: {},
+		bodyOverrides: {},
+	};
+
+	return {
+		candidate,
+		diagnostics,
+		consumedPaths: accountant.getConsumedPaths(),
+		preservedPaths: accountant.getPreservedPaths(),
+	};
+}

package/src/rosetta/builtins/targets/claude-code.ts

@@ -0,0 +1,181 @@
+/**
+ * Rosetta Stone — Claude Code Target Translator
+ *
+ * Wraps the existing claude-code 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,
+	OutputFile,
+	TranslationDiagnostic,
+} from "../../../schemas";
+import {
+	evaluateCompatibility,
+	identifyUsedCapabilities,
+	resolveEffectiveProfile,
+} from "../../compatibility";
+import { createDiagnostic } from "../../diagnostics";
+import { createPlan } from "../../plan";
+import type {
+	TargetTranslationOutput,
+	TargetTranslatorContext,
+} from "../../registry";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Constants
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/** Claude Code supported hook events */
+const SUPPORTED_CLAUDE_EVENTS = new Set(["agent_stop"]);
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Claude Code Target Translator
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Translate a canonical KnowledgeArtifact into Claude Code harness-native output.
+ *
+ * Renders CLAUDE.md output, handles MCP server configuration (.claude/mcp.json),
+ * and translates agent_stop hooks to .claude/settings.json.
+ *
+ * Applies body overrides for "claude-code" harness when available.
+ */
+export function translateClaudeCodeTarget(
+	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 claude-code harness
+	const body = art.bodyOverrides?.["claude-code"] ?? 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[] = [];
+
+	// Generate CLAUDE.md via template
+	const claudeContent = templates.render("claude-code/claude.md.njk", {
+		artifact: art,
+		body,
+	});
+	outputFiles.push({
+		relativePath: "CLAUDE.md",
+		content: claudeContent,
+		executable: false,
+	});
+
+	// Translate agent_stop + run_command hooks to .claude/settings.json
+	const stopHooks: Array<{ command: string }> = [];
+	for (const hook of art.hooks) {
+		if (!SUPPORTED_CLAUDE_EVENTS.has(hook.event)) {
+			diagnostics.push(
+				createDiagnostic("RS_COMPATIBILITY_PARTIAL", {
+					formatId: format.id,
+					message: `Hook "${hook.name}" uses event "${hook.event}" which is not supported by Claude Code. Skipped.`,
+					remediation:
+						"Only agent_stop hooks with run_command actions are supported.",
+					canonical: {
+						artifactName: art.name,
+						fieldPath: "hooks",
+					},
+				}),
+			);
+			continue;
+		}
+		if (hook.action.type === "run_command") {
+			stopHooks.push({ command: hook.action.command });
+		}
+	}
+
+	if (stopHooks.length > 0) {
+		const settings = {
+			hooks: {
+				stop: stopHooks.map((h) => ({ type: "command", command: h.command })),
+			},
+		};
+		const settingsContent = templates.render("claude-code/settings.json.njk", {
+			settings,
+		});
+		outputFiles.push({
+			relativePath: ".claude/settings.json",
+			content: settingsContent,
+			executable: false,
+		});
+	}
+
+	// Generate .claude/mcp.json
+	if (art.mcpServers.length > 0) {
+		const mcpConfig = buildMcpConfigData(art.mcpServers);
+		const mcpContent = templates.render("claude-code/mcp.json.njk", {
+			mcpConfig,
+		});
+		outputFiles.push({
+			relativePath: ".claude/mcp.json",
+			content: mcpContent,
+			executable: false,
+		});
+	}
+
+	// Build plan deterministically
+	const plan = createPlan(format.id, canonicalSchemaVersion, outputFiles, {
+		variant,
+	});
+
+	return { plan, diagnostics, degradations };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Internal Helpers
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Build MCP config data structure for Claude Code template rendering.
+ */
+function buildMcpConfigData(
+	servers: KnowledgeArtifact["mcpServers"],
+): Record<string, unknown> {
+	const mcpServers: Record<string, unknown> = {};
+	for (const server of servers) {
+		if ("command" in server) {
+			mcpServers[server.name] = {
+				command: server.command,
+				args: server.args,
+				env: server.env,
+				...(server.timeout ? { timeout: server.timeout } : {}),
+			};
+		} else {
+			mcpServers[server.name] = {
+				url: server.url,
+				...(server.env && Object.keys(server.env).length > 0
+					? { env: server.env }
+					: {}),
+				...(server.timeout ? { timeout: server.timeout } : {}),
+			};
+		}
+	}
+	return { mcpServers };
+}

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

@@ -0,0 +1,87 @@
+/**
+ * Rosetta Stone — Cline Target Translator
+ *
+ * Translates a canonical KnowledgeArtifact into Cline's native output
+ * format (.cline/rules/<name>.md).
+ *
+ * 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";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Cline Target Translator
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Translate a canonical artifact into Cline-native output files.
+ *
+ * Produces .cline/rules/<artifact-name>.md
+ */
+export function translateClineTarget(
+	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 cline harness
+	const body = art.bodyOverrides?.cline ?? 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("cline/rule.md.njk", {
+		artifact: art,
+		body,
+	});
+	outputFiles.push({
+		relativePath: `.cline/rules/${art.name}.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 };
+}