@thinkingsage/kanon 0.8.0

package/package.json

@@ -0,0 +1,98 @@
+{
+	"name": "@thinkingsage/kanon",
+	"version": "0.8.0",
+	"description": "Write knowledge once, compile to every AI coding assistant harness",
+	"type": "module",
+	"bin": {
+		"kanon": "./src/cli.ts",
+		"forge": "./src/cli-deprecated.ts"
+	},
+	"main": "./src/cli.ts",
+	"exports": {
+		".": "./src/cli.ts",
+		"./schemas": "./src/schemas.ts",
+		"./parser": "./src/parser.ts",
+		"./adapters": "./src/adapters/index.ts"
+	},
+	"engines": {
+		"bun": ">=1.0.0"
+	},
+	"scripts": {
+		"dev": "bun run src/cli.ts",
+		"build": "bun build src/cli.ts --compile --external chromium-bidi --outfile forge",
+		"build:kanon": "bun build src/cli.ts --compile --external chromium-bidi --outfile kanon",
+		"build:bridge": "bun build src/mcp-bridge.ts --outfile bridge/mcp-server.cjs --target node --format cjs",
+		"build:skills": "bun run scripts/generate-plugin-skills.ts",
+		"build:souk-compass": "bun --cwd mcp-servers/souk-compass run build",
+		"prepublishOnly": "bun test && biome check src/cli.ts src/adapters/ src/backends/ src/guild/ src/help/ src/importers/ src/*.ts templates/ bridge/",
+		"test": "bun test",
+		"validate:rosetta": "bun run scripts/validate-rosetta.ts",
+		"lint": "biome check .",
+		"lint:fix": "biome check --write .",
+		"format": "biome format --write .",
+		"changelog:new": "bun run scripts/changelog-fragment.ts",
+		"changelog:compile": "bun run scripts/changelog-compile.ts",
+		"changelog:draft": "bun run scripts/changelog-compile.ts --draft",
+		"release": "bun run scripts/release-tag.ts",
+		"bundle:analyze": "rollup --config rollup.config.js",
+		"docs:rosetta": "bun run src/rosetta-docs-generator.ts"
+	},
+	"keywords": [
+		"ai",
+		"coding-assistant",
+		"knowledge",
+		"skills",
+		"kiro",
+		"claude",
+		"copilot",
+		"cursor",
+		"windsurf",
+		"cline",
+		"qdeveloper",
+		"cli",
+		"compiler",
+		"bun"
+	],
+	"dependencies": {
+		"@clack/prompts": "^1.7.0",
+		"chalk": "^6.0.0",
+		"commander": "^15.0.0",
+		"gray-matter": "^4.0.3",
+		"js-yaml": "^5.4.1",
+		"nunjucks": "^3.2.4",
+		"promptfoo": "^0.122.0",
+		"tiktoken": "^1.0.22",
+		"zod": "^4.4.3"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.5.7",
+		"@codecov/rollup-plugin": "^2.0.1",
+		"@rollup/plugin-node-resolve": "^16.0.3",
+		"@rollup/plugin-typescript": "^12.3.0",
+		"@types/bun": "^1.3.14",
+		"@types/nunjucks": "^3.2.6",
+		"fast-check": "^4.9.0",
+		"rollup": "^4.62.4",
+		"typescript": "^7.0.2"
+	},
+	"license": "MIT",
+	"files": [
+		"src",
+		"!src/**/__tests__",
+		"!src/**/*.test.ts",
+		"!src/**/*.property.test.ts",
+		"templates",
+		"bridge/mcp-server.cjs",
+		"README.md",
+		"LICENSE",
+		"CHANGELOG.md"
+	],
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/jhu-sheridan-libraries/agentic-skill-forge.git"
+	},
+	"homepage": "https://github.com/jhu-sheridan-libraries/agentic-skill-forge#readme",
+	"bugs": {
+		"url": "https://github.com/jhu-sheridan-libraries/agentic-skill-forge/issues"
+	}
+}

package/src/adapters/capabilities.ts

@@ -0,0 +1,178 @@
+import { z } from "zod";
+import type {
+	CapabilityEntry,
+	DegradationStrategy,
+	HarnessName,
+} from "../schemas";
+import { CapabilityEntrySchema, SUPPORTED_HARNESSES } from "../schemas";
+
+// --- Capability Names ---
+
+export const HARNESS_CAPABILITIES = [
+	"hooks",
+	"mcp",
+	"path_scoping",
+	"workflows",
+	"toggleable_rules",
+	"agents",
+	"file_match_inclusion",
+	"system_prompt_merging",
+] as const;
+
+export type HarnessCapabilityName = (typeof HARNESS_CAPABILITIES)[number];
+
+// --- Matrix Type ---
+
+export type CapabilityMatrix = Record<
+	HarnessName,
+	Record<HarnessCapabilityName, CapabilityEntry>
+>;
+
+// --- Capability Matrix Constant ---
+
+export const CAPABILITY_MATRIX: CapabilityMatrix = {
+	kiro: {
+		hooks: { support: "full" },
+		mcp: { support: "full" },
+		path_scoping: { support: "full" },
+		workflows: { support: "full" },
+		toggleable_rules: { support: "full" },
+		agents: { support: "partial", degradation: "inline" },
+		file_match_inclusion: { support: "full" },
+		system_prompt_merging: { support: "full" },
+	},
+	"claude-code": {
+		hooks: { support: "partial", degradation: "inline" },
+		mcp: { support: "full" },
+		path_scoping: { support: "none", degradation: "comment" },
+		workflows: { support: "none", degradation: "inline" },
+		toggleable_rules: { support: "none", degradation: "omit" },
+		agents: { support: "none", degradation: "omit" },
+		file_match_inclusion: { support: "none", degradation: "omit" },
+		system_prompt_merging: { support: "full" },
+	},
+	codex: {
+		// Codex has no canonical event-hook system (only the notify shell hook).
+		hooks: { support: "none", degradation: "inline" },
+		// MCP servers are first-class via ~/.codex/config.toml [mcp_servers].
+		mcp: { support: "full" },
+		// Directory scoping is via nested AGENTS.md, not glob file patterns.
+		path_scoping: { support: "none", degradation: "comment" },
+		// Workflows map naturally onto skill phase files under references/.
+		workflows: { support: "full" },
+		toggleable_rules: { support: "none", degradation: "omit" },
+		// Sub-agents exist via profiles / `codex exec`, but not as declarative files.
+		agents: { support: "partial", degradation: "inline" },
+		file_match_inclusion: { support: "none", degradation: "omit" },
+		// AGENTS.md is merged into the system prompt every session.
+		system_prompt_merging: { support: "full" },
+	},
+	copilot: {
+		hooks: { support: "none", degradation: "inline" },
+		mcp: { support: "none", degradation: "comment" },
+		path_scoping: { support: "full" },
+		workflows: { support: "none", degradation: "inline" },
+		toggleable_rules: { support: "none", degradation: "omit" },
+		agents: { support: "full" },
+		file_match_inclusion: { support: "full" },
+		system_prompt_merging: { support: "none", degradation: "inline" },
+	},
+	cursor: {
+		hooks: { support: "none", degradation: "inline" },
+		mcp: { support: "full" },
+		path_scoping: { support: "full" },
+		workflows: { support: "none", degradation: "inline" },
+		toggleable_rules: { support: "full" },
+		agents: { support: "none", degradation: "omit" },
+		file_match_inclusion: { support: "full" },
+		system_prompt_merging: { support: "none", degradation: "inline" },
+	},
+	windsurf: {
+		hooks: { support: "none", degradation: "inline" },
+		mcp: { support: "full" },
+		path_scoping: { support: "full" },
+		workflows: { support: "full" },
+		toggleable_rules: { support: "none", degradation: "omit" },
+		agents: { support: "none", degradation: "omit" },
+		file_match_inclusion: { support: "full" },
+		system_prompt_merging: { support: "none", degradation: "inline" },
+	},
+	cline: {
+		hooks: { support: "partial", degradation: "inline" },
+		mcp: { support: "full" },
+		path_scoping: { support: "none", degradation: "comment" },
+		workflows: { support: "none", degradation: "inline" },
+		toggleable_rules: { support: "none", degradation: "omit" },
+		agents: { support: "none", degradation: "omit" },
+		file_match_inclusion: { support: "none", degradation: "omit" },
+		system_prompt_merging: { support: "none", degradation: "inline" },
+	},
+	qdeveloper: {
+		hooks: { support: "none", degradation: "inline" },
+		mcp: { support: "full" },
+		path_scoping: { support: "full" },
+		workflows: { support: "none", degradation: "inline" },
+		toggleable_rules: { support: "none", degradation: "omit" },
+		agents: { support: "full" },
+		file_match_inclusion: { support: "full" },
+		system_prompt_merging: { support: "none", degradation: "inline" },
+	},
+};
+
+// --- Zod Validation at Module Load Time ---
+
+const CapabilityRowSchema = z.record(
+	z.enum(HARNESS_CAPABILITIES),
+	CapabilityEntrySchema,
+);
+
+const CapabilityMatrixSchema = z.record(
+	z.enum(SUPPORTED_HARNESSES),
+	CapabilityRowSchema,
+);
+
+// Validate the matrix at module load time — throws if invalid
+CapabilityMatrixSchema.parse(CAPABILITY_MATRIX);
+
+// --- Query Functions ---
+
+/** Get all capability entries for a harness */
+export function getCapabilities(
+	harness: HarnessName,
+): Record<HarnessCapabilityName, CapabilityEntry> {
+	return CAPABILITY_MATRIX[harness];
+}
+
+/** Check if a specific capability is fully supported */
+export function isSupported(
+	harness: HarnessName,
+	capability: HarnessCapabilityName,
+): boolean {
+	return CAPABILITY_MATRIX[harness][capability].support === "full";
+}
+
+/** Get degradation strategy for a capability, or undefined if fully supported */
+export function getDegradation(
+	harness: HarnessName,
+	capability: HarnessCapabilityName,
+): DegradationStrategy | undefined {
+	const entry = CAPABILITY_MATRIX[harness][capability];
+	return entry.support === "full" ? undefined : entry.degradation;
+}
+
+/** Validate matrix harnesses are in sync with adapter registry and format registry */
+export function validateMatrixSync(
+	matrixHarnesses: string[],
+	registryHarnesses: string[],
+	formatRegistryHarnesses: string[],
+): { missing: string[]; extra: string[] } {
+	const matrixSet = new Set(matrixHarnesses);
+	const allRequired = new Set([
+		...registryHarnesses,
+		...formatRegistryHarnesses,
+	]);
+	return {
+		missing: [...allRequired].filter((h) => !matrixSet.has(h)),
+		extra: matrixHarnesses.filter((h) => !allRequired.has(h)),
+	};
+}

package/src/adapters/claude-code.ts

@@ -0,0 +1,110 @@
+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";
+import { buildMcpConfig } from "./types";
+
+const SUPPORTED_CLAUDE_EVENTS = new Set(["agent_stop"]);
+
+export const claudeCodeAdapter: 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: "claude-code",
+					message: `Strict mode: capability ${capability} not supported by harness claude-code`,
+				});
+				return { files, warnings };
+			}
+			const degradation = applyDegradation(
+				entry.degradation ?? "inline",
+				capability,
+				artifact,
+				"claude-code",
+			);
+			warnings.push(...degradation.warnings);
+		}
+	}
+
+	const harnessConfig = (artifact.frontmatter as Record<string, unknown>)[
+		"harness-config"
+	] as Record<string, unknown> | undefined;
+	const claudeCodeConfig = (harnessConfig?.["claude-code"] ?? {}) as Record<
+		string,
+		unknown
+	>;
+	resolveFormat("claude-code", claudeCodeConfig);
+
+	// Generate CLAUDE.md
+	const claudeContent = renderTemplate(
+		templateEnv,
+		"claude-code/claude.md.njk",
+		{ artifact },
+	);
+	files.push({ relativePath: "CLAUDE.md", content: claudeContent });
+
+	// Translate agent_stop + run_command hooks to .claude/settings.json
+	const stopHooks: Array<{ command: string }> = [];
+	for (const hook of artifact.hooks) {
+		if (!SUPPORTED_CLAUDE_EVENTS.has(hook.event)) {
+			warnings.push({
+				artifactName: artifact.name,
+				harnessName: "claude-code",
+				message: `Skipping hook "${hook.name}": event "${hook.event}" not supported by Claude Code`,
+			});
+			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 = renderTemplate(
+			templateEnv,
+			"claude-code/settings.json.njk",
+			{ settings },
+		);
+		files.push({
+			relativePath: ".claude/settings.json",
+			content: settingsContent,
+		});
+	}
+
+	// Generate .claude/mcp.json
+	if (artifact.mcpServers.length > 0) {
+		const mcpConfig = buildMcpConfig(artifact.mcpServers);
+		const mcpContent = renderTemplate(templateEnv, "claude-code/mcp.json.njk", {
+			mcpConfig,
+		});
+		files.push({ relativePath: ".claude/mcp.json", content: mcpContent });
+	}
+
+	return { files, warnings };
+};

package/src/adapters/cline.ts

@@ -0,0 +1,98 @@
+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";
+import { buildMcpConfig } from "./types";
+
+export const clineAdapter: 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: "cline",
+					message: `Strict mode: capability ${capability} not supported by harness cline`,
+				});
+				return { files, warnings };
+			}
+			const degradation = applyDegradation(
+				entry.degradation ?? "inline",
+				capability,
+				artifact,
+				"cline",
+			);
+			warnings.push(...degradation.warnings);
+		}
+	}
+
+	const harnessConfig = (artifact.frontmatter as Record<string, unknown>)[
+		"harness-config"
+	] as Record<string, unknown> | undefined;
+	const clineConfig = (harnessConfig?.cline ?? {}) as Record<string, unknown>;
+	resolveFormat("cline", clineConfig);
+
+	// Generate .clinerules/<artifact>.md
+	const ruleContent = renderTemplate(templateEnv, "cline/rule.md.njk", {
+		artifact,
+	});
+	files.push({
+		relativePath: `.clinerules/${artifact.name}.md`,
+		content: ruleContent,
+	});
+
+	// Translate hooks to executable shell scripts
+	for (const hook of artifact.hooks) {
+		if (hook.action.type === "run_command") {
+			const hookContent = renderTemplate(templateEnv, "cline/hook.sh.njk", {
+				hook: {
+					name: hook.name,
+					description: hook.description || "",
+					command: hook.action.command,
+				},
+			});
+			const hookName = hook.name.toLowerCase().replace(/\s+/g, "-");
+			files.push({
+				relativePath: `.clinerules/hooks/${hookName}.sh`,
+				content: hookContent,
+				executable: true,
+			});
+		} else if (hook.action.type === "ask_agent") {
+			warnings.push({
+				artifactName: artifact.name,
+				harnessName: "cline",
+				message: `Skipping hook "${hook.name}": ask_agent actions are translated as shell scripts only for run_command`,
+			});
+		}
+	}
+
+	// Generate VS Code MCP configuration
+	if (artifact.mcpServers.length > 0) {
+		const mcpConfig = buildMcpConfig(artifact.mcpServers);
+		const mcpContent = renderTemplate(templateEnv, "cline/mcp.json.njk", {
+			mcpConfig,
+		});
+		files.push({ relativePath: ".clinerules/mcp.json", content: mcpContent });
+	}
+
+	return { files, warnings };
+};

package/src/adapters/codex.ts

@@ -0,0 +1,173 @@
+import { resolveFormat } from "../format-registry";
+import type { McpServerDefinition } from "../schemas";
+import { isStdioServer } from "../schemas";
+import { renderTemplate } from "../template-engine";
+import type { HarnessCapabilityName } from "./capabilities";
+import { applyDegradation } from "./degradation";
+import type { AdapterWarning, HarnessAdapter, OutputFile } from "./types";
+
+/** 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`;
+}
+
+export const codexAdapter: HarnessAdapter = (
+	artifact,
+	templateEnv,
+	context?,
+) => {
+	const files: OutputFile[] = [];
+	const warnings: AdapterWarning[] = [];
+	const degradedSections: string[] = [];
+
+	// 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;
+			const degradation = applyDegradation(
+				entry.degradation ?? "inline",
+				capability,
+				artifact,
+				"codex",
+			);
+			warnings.push(...degradation.warnings);
+			if (context.strict) {
+				warnings.push({
+					artifactName: artifact.name,
+					harnessName: "codex",
+					message: `Strict mode: capability ${capability} is degraded for harness codex`,
+				});
+			}
+			if (degradation.inlineText) {
+				degradedSections.push(degradation.inlineText);
+			}
+		}
+	}
+
+	const harnessConfig = (artifact.frontmatter as Record<string, unknown>)[
+		"harness-config"
+	] as Record<string, unknown> | undefined;
+	const codexConfig = (harnessConfig?.codex ?? {}) as Record<string, unknown>;
+	const { format } = resolveFormat("codex", codexConfig);
+	const skillName = artifact.name;
+	const renderContext = {
+		artifact,
+		degradedSections,
+	};
+
+	if (format === "skill") {
+		// Native Codex skill discovery path + always-loaded AGENTS.md pointer.
+		const skillContent = renderTemplate(
+			templateEnv,
+			"codex/skill.md.njk",
+			renderContext,
+		);
+		files.push({
+			relativePath: `.codex/skills/${skillName}/SKILL.md`,
+			content: skillContent,
+		});
+
+		// Workflow phase files live under references/ for progressive disclosure.
+		for (const wf of artifact.workflows) {
+			files.push({
+				relativePath: `.codex/skills/${skillName}/references/${wf.filename}`,
+				content: wf.content,
+			});
+		}
+
+		const pointerContent = renderTemplate(
+			templateEnv,
+			"codex/agents-pointer.md.njk",
+			renderContext,
+		);
+		files.push({ relativePath: "AGENTS.md", content: pointerContent });
+	} else {
+		// "agents-md": a repo-wide AGENTS.md carrying the full body.
+		const agentsContent = renderTemplate(
+			templateEnv,
+			"codex/agents-md.md.njk",
+			renderContext,
+		);
+		files.push({ relativePath: "AGENTS.md", content: agentsContent });
+	}
+
+	// MCP servers → .codex/config.toml
+	if (artifact.mcpServers.length > 0) {
+		files.push({
+			relativePath: ".codex/config.toml",
+			content: buildCodexMcpToml(artifact.mcpServers),
+		});
+	}
+
+	// Codex has no canonical event-hook system (only the `notify` shell hook),
+	// so declarative hooks are skipped.
+	if (artifact.hooks.length > 0) {
+		warnings.push({
+			artifactName: artifact.name,
+			harnessName: "codex",
+			message:
+				"Codex has no declarative event-hook system; hook definitions were rendered as manual guidance",
+		});
+	}
+
+	return { files, warnings };
+};