@thinkingsage/kanon 0.8.0

package/src/manifest-admin.ts

@@ -0,0 +1,306 @@
+import { readFile, writeFile } from "node:fs/promises";
+import * as yaml from "js-yaml";
+import type { Manifest, ManifestEntry } from "./guild/manifest";
+import {
+	ArtifactManifestEntrySchema,
+	CollectionManifestEntrySchema,
+	parseManifest,
+	printManifest,
+} from "./guild/manifest";
+import type { SyncLock } from "./guild/sync";
+
+/** Input shape for adding a manifest entry */
+export interface ManifestEntryInput {
+	name?: string; // for artifact refs
+	collection?: string; // for collection refs
+	version: string;
+	mode: "required" | "optional";
+	harnesses?: string[];
+	backend?: string;
+}
+
+/** Sync status for a single manifest entry */
+export interface EntryStatus {
+	identifier: string; // name or collection
+	type: "artifact" | "collection";
+	version: string;
+	mode: string;
+	syncedVersion: string | null;
+	status: "synced" | "outdated" | "missing";
+}
+
+/** Full sync status response */
+export interface SyncStatusResponse {
+	entries: EntryStatus[];
+	syncedAt: string | null;
+}
+
+/** Reads and parses the manifest file, returns empty manifest if file doesn't exist */
+export async function readManifest(
+	manifestPath: string,
+): Promise<{ manifest: Manifest; raw: Record<string, unknown> }> {
+	let content: string;
+	try {
+		content = await readFile(manifestPath, "utf-8");
+	} catch (err: unknown) {
+		if (
+			err &&
+			typeof err === "object" &&
+			"code" in err &&
+			(err as { code: string }).code === "ENOENT"
+		) {
+			return { manifest: { artifacts: [] }, raw: {} };
+		}
+		throw err;
+	}
+
+	const manifest = parseManifest(content);
+	const raw = (yaml.load(content) as Record<string, unknown>) ?? {};
+
+	return { manifest, raw };
+}
+
+/** Reads and parses the sync-lock file, returns null if file doesn't exist */
+export async function readSyncLock(
+	syncLockPath: string,
+): Promise<SyncLock | null> {
+	let content: string;
+	try {
+		content = await readFile(syncLockPath, "utf-8");
+	} catch (err: unknown) {
+		if (
+			err &&
+			typeof err === "object" &&
+			"code" in err &&
+			(err as { code: string }).code === "ENOENT"
+		) {
+			return null;
+		}
+		throw err;
+	}
+
+	return JSON.parse(content) as SyncLock;
+}
+
+/** Computes sync status by comparing manifest entries against sync-lock */
+export function computeSyncStatus(
+	manifest: Manifest,
+	syncLock: SyncLock | null,
+): SyncStatusResponse {
+	const entries: EntryStatus[] = manifest.artifacts.map((entry) => {
+		const identifier =
+			"name" in entry
+				? entry.name
+				: (entry as { collection: string }).collection;
+		const type: "artifact" | "collection" =
+			"name" in entry ? "artifact" : "collection";
+
+		const lockEntry =
+			syncLock?.entries.find((e) => e.name === identifier) ?? null;
+
+		let status: "synced" | "outdated" | "missing";
+		if (!lockEntry) {
+			status = "missing";
+		} else if (lockEntry.version === entry.version) {
+			status = "synced";
+		} else {
+			status = "outdated";
+		}
+
+		return {
+			identifier,
+			type,
+			version: entry.version,
+			mode: entry.mode,
+			syncedVersion: lockEntry?.version ?? null,
+			status,
+		};
+	});
+
+	return {
+		entries,
+		syncedAt: syncLock?.syncedAt ?? null,
+	};
+}
+
+/** Error type for manifest admin operations */
+export class ManifestAdminError extends Error {
+	constructor(
+		message: string,
+		public readonly type: "conflict" | "not-found" | "validation",
+	) {
+		super(message);
+		this.name = "ManifestAdminError";
+	}
+}
+
+/** Validates a ManifestEntryInput against the appropriate schema */
+export function validateManifestEntry(
+	input: ManifestEntryInput,
+):
+	| { success: true; data: ManifestEntry }
+	| { success: false; errors: Array<{ field: string; message: string }> } {
+	const hasName = input.name != null && input.name !== "";
+	const hasCollection = input.collection != null && input.collection !== "";
+
+	if (hasName && hasCollection) {
+		return {
+			success: false,
+			errors: [
+				{
+					field: "name",
+					message:
+						"Cannot set both 'name' and 'collection' — each entry must have exactly one",
+				},
+			],
+		};
+	}
+
+	if (!hasName && !hasCollection) {
+		return {
+			success: false,
+			errors: [
+				{
+					field: "name",
+					message:
+						"Must set either 'name' (for artifact ref) or 'collection' (for collection ref)",
+				},
+			],
+		};
+	}
+
+	const schema = hasName
+		? ArtifactManifestEntrySchema
+		: CollectionManifestEntrySchema;
+	const result = schema.safeParse(input);
+
+	if (!result.success) {
+		const errors = result.error.issues.map((issue) => ({
+			field: issue.path.join(".") || "unknown",
+			message: issue.message,
+		}));
+		return { success: false, errors };
+	}
+
+	return { success: true, data: result.data as ManifestEntry };
+}
+
+/** Helper to get the identifier from a manifest entry */
+function getEntryIdentifier(entry: ManifestEntry): string {
+	return "name" in entry
+		? entry.name
+		: (entry as { collection: string }).collection;
+}
+
+/** Writes the manifest back to disk, preserving unknown top-level keys from the raw object */
+async function writeManifestToDisk(
+	manifestPath: string,
+	manifest: Manifest,
+	raw: Record<string, unknown>,
+): Promise<void> {
+	// Merge validated manifest back into raw to preserve unknown top-level keys
+	const merged: Record<string, unknown> = { ...raw };
+	if (manifest.backend != null) {
+		merged.backend = manifest.backend;
+	} else {
+		// Only delete if the manifest explicitly doesn't have it
+		// but keep it if raw had it (passthrough)
+		if (!("backend" in manifest)) {
+			delete merged.backend;
+		}
+	}
+	merged.artifacts = manifest.artifacts;
+
+	const yamlContent = printManifest(merged as Manifest);
+	await writeFile(manifestPath, yamlContent, "utf-8");
+}
+
+/** Adds a new entry to the manifest, writes to disk */
+export async function addManifestEntry(
+	manifestPath: string,
+	input: ManifestEntryInput,
+): Promise<Manifest> {
+	const validation = validateManifestEntry(input);
+	if (!validation.success) {
+		throw new ManifestAdminError(
+			`Validation failed: ${validation.errors.map((e) => e.message).join("; ")}`,
+			"validation",
+		);
+	}
+
+	const { manifest, raw } = await readManifest(manifestPath);
+	const newEntry = validation.data;
+	const newIdentifier = getEntryIdentifier(newEntry);
+
+	// Check for duplicate
+	const duplicate = manifest.artifacts.find(
+		(entry) => getEntryIdentifier(entry) === newIdentifier,
+	);
+	if (duplicate) {
+		throw new ManifestAdminError(
+			`Manifest entry '${newIdentifier}' already exists`,
+			"conflict",
+		);
+	}
+
+	manifest.artifacts.push(newEntry);
+	await writeManifestToDisk(manifestPath, manifest, raw);
+
+	return manifest;
+}
+
+/** Updates an existing entry in the manifest, writes to disk */
+export async function editManifestEntry(
+	manifestPath: string,
+	identifier: string,
+	input: Partial<ManifestEntryInput>,
+): Promise<Manifest> {
+	const { manifest, raw } = await readManifest(manifestPath);
+
+	const entryIndex = manifest.artifacts.findIndex(
+		(entry) => getEntryIdentifier(entry) === identifier,
+	);
+	if (entryIndex === -1) {
+		throw new ManifestAdminError(
+			`Manifest entry '${identifier}' not found`,
+			"not-found",
+		);
+	}
+
+	const existing = manifest.artifacts[entryIndex];
+
+	// Update mutable fields from the partial input
+	const updated = { ...existing } as Record<string, unknown>;
+	if (input.version !== undefined) updated.version = input.version;
+	if (input.mode !== undefined) updated.mode = input.mode;
+	if (input.harnesses !== undefined) updated.harnesses = input.harnesses;
+	if (input.backend !== undefined) updated.backend = input.backend;
+
+	manifest.artifacts[entryIndex] = updated as ManifestEntry;
+	await writeManifestToDisk(manifestPath, manifest, raw);
+
+	return manifest;
+}
+
+/** Removes an entry from the manifest, writes to disk */
+export async function removeManifestEntry(
+	manifestPath: string,
+	identifier: string,
+): Promise<Manifest> {
+	const { manifest, raw } = await readManifest(manifestPath);
+
+	const entryIndex = manifest.artifacts.findIndex(
+		(entry) => getEntryIdentifier(entry) === identifier,
+	);
+	if (entryIndex === -1) {
+		throw new ManifestAdminError(
+			`Manifest entry '${identifier}' not found`,
+			"not-found",
+		);
+	}
+
+	manifest.artifacts.splice(entryIndex, 1);
+	await writeManifestToDisk(manifestPath, manifest, raw);
+
+	return manifest;
+}

package/src/mcp-bridge.ts

@@ -0,0 +1,240 @@
+#!/usr/bin/env node
+
+/**
+ * context-bazaar MCP bridge
+ *
+ * Exposes the kanon catalog and artifacts as MCP tools so Claude Code
+ * users can browse and install knowledge artifacts directly from the assistant.
+ *
+ * Tools:
+ *   catalog_list      — list all artifacts (optionally filtered by collection)
+ *   artifact_content  — read a specific artifact's knowledge.md
+ *   collection_list   — list collections with member counts
+ */
+
+import { access, readFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+	CallToolRequestSchema,
+	ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+// Resolve the Kanon data root — works when installed as a Claude or Codex
+// plugin, and also when run from the checked-out source tree.
+const ENTRYPOINT_PATH = process.argv[1];
+const RUNTIME_DIR = ENTRYPOINT_PATH
+	? dirname(resolve(ENTRYPOINT_PATH))
+	: process.cwd();
+const ENV_PLUGIN_ROOT =
+	process.env.CODEX_PLUGIN_ROOT ?? process.env.CLAUDE_PLUGIN_ROOT;
+const PLUGIN_ROOT_CANDIDATES = [
+	...(ENV_PLUGIN_ROOT ? [join(ENV_PLUGIN_ROOT, "kanon"), ENV_PLUGIN_ROOT] : []),
+	resolve(RUNTIME_DIR, ".."),
+];
+
+async function resolvePluginRoot() {
+	for (const root of PLUGIN_ROOT_CANDIDATES) {
+		try {
+			await access(join(root, "catalog.json"));
+			return root;
+		} catch {
+			// Try the next root shape.
+		}
+	}
+	return PLUGIN_ROOT_CANDIDATES[PLUGIN_ROOT_CANDIDATES.length - 1];
+}
+
+async function loadCatalog() {
+	const pluginRoot = await resolvePluginRoot();
+	const catalogPath = join(pluginRoot, "catalog.json");
+	const raw = await readFile(catalogPath, "utf-8");
+	return {
+		entries: JSON.parse(raw) as Array<Record<string, unknown>>,
+		pluginRoot,
+	};
+}
+
+const server = new Server(
+	{ name: "context-bazaar", version: "0.2.0" },
+	{ capabilities: { tools: {} } },
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+	tools: [
+		{
+			name: "catalog_list",
+			description:
+				"List knowledge artifacts in the context-bazaar catalog. " +
+				"Optionally filter by collection name (e.g. 'neon-caravan', 'byron-powers') " +
+				"or by type (skill, power, workflow, prompt, agent, template, reference-pack).",
+			inputSchema: {
+				type: "object" as const,
+				properties: {
+					collection: {
+						type: "string",
+						description: "Filter to a specific collection name",
+					},
+					type: {
+						type: "string",
+						description: "Filter by artifact type",
+					},
+				},
+			},
+		},
+		{
+			name: "artifact_content",
+			description:
+				"Return the full knowledge.md content of a specific artifact. " +
+				"Use catalog_list first to find the artifact name.",
+			inputSchema: {
+				type: "object" as const,
+				required: ["name"],
+				properties: {
+					name: {
+						type: "string",
+						description: "Artifact name (kebab-case, e.g. 'commit-craft')",
+					},
+				},
+			},
+		},
+		{
+			name: "collection_list",
+			description:
+				"List all available collections with their member artifact names.",
+			inputSchema: {
+				type: "object" as const,
+				properties: {},
+			},
+		},
+	],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+	const { entries: catalog, pluginRoot } = await loadCatalog();
+	const args = (request.params.arguments ?? {}) as Record<string, string>;
+
+	switch (request.params.name) {
+		case "catalog_list": {
+			let entries = catalog;
+			if (args.collection) {
+				entries = entries.filter(
+					(e) =>
+						Array.isArray(e.collections) &&
+						e.collections.includes(args.collection),
+				);
+			}
+			if (args.type) {
+				entries = entries.filter((e) => e.type === args.type);
+			}
+
+			const summary = entries.map((e) => ({
+				name: e.name,
+				displayName: e.displayName,
+				type: e.type,
+				description: e.description,
+				maturity: e.maturity,
+				collections: e.collections,
+				harnesses: e.harnesses,
+			}));
+
+			return {
+				content: [
+					{
+						type: "text" as const,
+						text: `Found ${summary.length} artifact(s):\n\n${JSON.stringify(summary, null, 2)}`,
+					},
+				],
+			};
+		}
+
+		case "artifact_content": {
+			const entry = catalog.find((e) => e.name === args.name);
+			if (!entry) {
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `Artifact '${args.name}' not found in catalog.`,
+						},
+					],
+					isError: true,
+				};
+			}
+
+			const contentPath = join(pluginRoot, String(entry.path), "knowledge.md");
+			let content: string;
+			try {
+				content = await readFile(contentPath, "utf-8");
+			} catch {
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `Artifact found in catalog but source file not available at ${contentPath}.`,
+						},
+					],
+					isError: true,
+				};
+			}
+
+			return {
+				content: [
+					{
+						type: "text" as const,
+						text: `# ${entry.displayName}\n**Type:** ${entry.type}  **Maturity:** ${entry.maturity}\n\n${content}`,
+					},
+				],
+			};
+		}
+
+		case "collection_list": {
+			const collectionMap = new Map<string, string[]>();
+			for (const entry of catalog) {
+				for (const col of (Array.isArray(entry.collections)
+					? entry.collections
+					: []) as string[]) {
+					if (!collectionMap.has(col)) collectionMap.set(col, []);
+					collectionMap.get(col)?.push(String(entry.name));
+				}
+			}
+
+			const result = [...collectionMap.entries()].map(([name, members]) => ({
+				name,
+				memberCount: members.length,
+				members,
+			}));
+
+			return {
+				content: [
+					{
+						type: "text" as const,
+						text:
+							result.length === 0
+								? "No collections found."
+								: JSON.stringify(result, null, 2),
+					},
+				],
+			};
+		}
+
+		default:
+			return {
+				content: [
+					{
+						type: "text" as const,
+						text: `Unknown tool: ${request.params.name}`,
+					},
+				],
+				isError: true,
+			};
+	}
+});
+
+async function main() {
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+}
+
+main().catch(console.error);

package/src/mutation/delta.ts

@@ -0,0 +1,50 @@
+/**
+ * Mutation testing — delta strategy (Req 5.6).
+ *
+ * `selectDeltaTargets` is a pure intersection function: given the set of adapter
+ * files eligible for mutation and the set of files changed since the last
+ * recorded run (from `git diff`), return only the adapter files that appear in
+ * both sets.
+ *
+ * Path normalization is applied so that trailing slashes, redundant separators,
+ * and leading `./` prefixes do not prevent a match.
+ *
+ * The `git diff` invocation and reading the last SHA from history are I/O
+ * concerns handled by the runner; this module is pure.
+ *
+ * See ADR-0042 for the architectural rationale.
+ */
+
+import { normalize } from "node:path";
+
+/**
+ * Normalize a file path for comparison: strip leading `./`, collapse redundant
+ * separators, and remove trailing slashes.
+ */
+function normalizePath(p: string): string {
+	// Use node:path normalize to collapse separators and resolve `.` segments.
+	let normalized = normalize(p);
+	// Strip trailing slash (normalize keeps it for root `/`).
+	if (normalized.length > 1 && normalized.endsWith("/")) {
+		normalized = normalized.slice(0, -1);
+	}
+	return normalized;
+}
+
+/**
+ * Given the set of adapter files and the set of changed files (from git diff
+ * since the last run's SHA), return the subset of adapter files that also appear
+ * in the changed files set — i.e., the files to mutate for a delta run.
+ *
+ * Pure. Preserves the original path strings from `adapterFiles` in the output.
+ * If either input is empty, returns `[]`.
+ */
+export function selectDeltaTargets(
+	adapterFiles: string[],
+	changedFiles: string[],
+): string[] {
+	if (adapterFiles.length === 0 || changedFiles.length === 0) return [];
+
+	const changedSet = new Set(changedFiles.map(normalizePath));
+	return adapterFiles.filter((f) => changedSet.has(normalizePath(f)));
+}

package/src/mutation/history.ts

@@ -0,0 +1,66 @@
+/**
+ * Mutation testing — history persistence (Req 5.8).
+ *
+ * Pure core: `serializeRecord` and `parseHistory` are deterministic, I/O-free
+ * functions that convert between `MutationRunRecord` objects and JSONL text.
+ *
+ * Thin I/O shell: `appendRecord` writes one JSONL line to the history file,
+ * creating parent directories if needed.
+ *
+ * See ADR-0042 for the architectural rationale.
+ */
+
+import { appendFile, mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+
+/**
+ * A single mutation testing run result, persisted as one JSONL line.
+ *
+ * Fields (per Req 5.8):
+ * - ts: ISO 8601 timestamp of the run
+ * - sha: short git commit hash at time of run
+ * - killRate: decimal kill rate (killed / total)
+ * - totalMutants: total mutants generated
+ * - killed: mutants detected by the test suite
+ * - survived: mutants not detected
+ * - operators: array of operator names used in the run
+ */
+export interface MutationRunRecord {
+	ts: string;
+	sha: string;
+	killRate: number;
+	totalMutants: number;
+	killed: number;
+	survived: number;
+	operators: string[];
+}
+
+/**
+ * Serialize one record to a single JSONL line (trailing newline included). Pure.
+ */
+export function serializeRecord(r: MutationRunRecord): string {
+	return `${JSON.stringify(r)}\n`;
+}
+
+/**
+ * Parse JSONL content into an array of records. Pure.
+ * Empty lines are silently skipped.
+ */
+export function parseHistory(content: string): MutationRunRecord[] {
+	return content
+		.split("\n")
+		.filter((line) => line.trim().length > 0)
+		.map((line) => JSON.parse(line) as MutationRunRecord);
+}
+
+/**
+ * Append a single record to the mutation history file (I/O).
+ * Creates parent directories if they do not already exist.
+ */
+export async function appendRecord(
+	filePath: string,
+	record: MutationRunRecord,
+): Promise<void> {
+	await mkdir(dirname(filePath), { recursive: true });
+	await appendFile(filePath, serializeRecord(record), "utf-8");
+}