@thinkingsage/kanon 0.8.0

package/src/collection-builder.ts

@@ -0,0 +1,464 @@
+import { exists, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import * as p from "@clack/prompts";
+import chalk from "chalk";
+import { generateCatalog, SOURCE_DIRS } from "./catalog";
+import {
+	buildCollectionMembership,
+	loadCollections,
+	validateArtifactCollectionRefs,
+} from "./collections";
+import type { Collection, HarnessName } from "./schemas";
+import { SUPPORTED_HARNESSES, TrustLaneSchema } from "./schemas";
+
+export interface CollectionBuildResult {
+	collection: string;
+	harness: string;
+	artifactsIncluded: number;
+	filesWritten: number;
+}
+
+/**
+ * Build a single collection bundle for a single harness.
+ *
+ * Copies all pre-built dist artifacts whose `collections` field includes
+ * this collection into `dist/<harness>/collections/<collection-name>/`.
+ * Each artifact's files land in a subdirectory named after the artifact,
+ * preserving the same structure as a normal artifact dist dir.
+ */
+async function buildCollectionForHarness(
+	collection: Collection,
+	members: string[], // artifact names belonging to this collection
+	harness: HarnessName,
+	distDir: string,
+): Promise<{ artifactsIncluded: number; filesWritten: number }> {
+	const collectionOutDir = join(
+		distDir,
+		harness,
+		"collections",
+		collection.name,
+	);
+	await mkdir(collectionOutDir, { recursive: true });
+
+	let artifactsIncluded = 0;
+	let filesWritten = 0;
+
+	for (const artifactName of members) {
+		const artifactDistDir = join(distDir, harness, artifactName);
+
+		if (!(await exists(artifactDistDir))) continue;
+
+		const destDir = join(collectionOutDir, artifactName);
+		await mkdir(destDir, { recursive: true });
+
+		// Recursively copy all files from the artifact's dist dir
+		const copied = await copyDir(artifactDistDir, destDir);
+		if (copied > 0) {
+			artifactsIncluded++;
+			filesWritten += copied;
+		}
+	}
+
+	return { artifactsIncluded, filesWritten };
+}
+
+async function copyDir(src: string, dest: string): Promise<number> {
+	let count = 0;
+	const entries = await readdir(src, { withFileTypes: true });
+
+	for (const entry of entries) {
+		const srcPath = join(src, entry.name);
+		const destPath = join(dest, entry.name);
+
+		if (entry.isDirectory()) {
+			await mkdir(destPath, { recursive: true });
+			count += await copyDir(srcPath, destPath);
+		} else if (entry.isFile()) {
+			const content = await readFile(srcPath);
+			await writeFile(destPath, content);
+			count++;
+		}
+	}
+
+	return count;
+}
+
+/**
+ * Build all collection bundles for all (or a specific) harness.
+ *
+ * Requires `kanon build` to have already run — this command reads from
+ * the existing dist/ output rather than re-compiling artifacts.
+ */
+export async function buildCollections(options: {
+	collectionsDir: string;
+	distDir: string;
+	harness?: HarnessName;
+	sourceDirs?: string[];
+}): Promise<CollectionBuildResult[]> {
+	const { collectionsDir, distDir, harness } = options;
+	const sourceDirs = options.sourceDirs ?? [...SOURCE_DIRS];
+	const results: CollectionBuildResult[] = [];
+
+	// Load collection manifests
+	const collections = await loadCollections(collectionsDir);
+	if (collections.length === 0) {
+		console.error(
+			chalk.yellow("No collection manifests found in collections/"),
+		);
+		return results;
+	}
+
+	// Load catalog to get collection membership from artifact frontmatter
+	const catalogEntries = await generateCatalog(sourceDirs);
+
+	// Warn on unregistered collection references
+	const refWarnings = validateArtifactCollectionRefs(
+		catalogEntries,
+		collections,
+	);
+	for (const w of refWarnings) {
+		console.error(chalk.yellow(`  ⚠ ${w.field}: ${w.message}`));
+	}
+
+	// Build membership map: collection name → artifact names
+	const membership = buildCollectionMembership(catalogEntries);
+
+	const targetHarnesses: HarnessName[] = harness
+		? [harness]
+		: [...SUPPORTED_HARNESSES];
+
+	for (const collection of collections) {
+		const members = membership.get(collection.name) ?? [];
+
+		if (members.length === 0) {
+			console.error(
+				chalk.yellow(
+					`  ⚠ Collection "${collection.name}" has no member artifacts`,
+				),
+			);
+		}
+
+		for (const h of targetHarnesses) {
+			const { artifactsIncluded, filesWritten } =
+				await buildCollectionForHarness(collection, members, h, distDir);
+			results.push({
+				collection: collection.name,
+				harness: h,
+				artifactsIncluded,
+				filesWritten,
+			});
+		}
+	}
+
+	return results;
+}
+
+/**
+ * Default `kanon collection` action — shows a status overview of all collection
+ * manifests, their member counts, trust lanes, and any validation warnings.
+ */
+export async function collectionStatusCommand(): Promise<void> {
+	// When called as `kanon collection help`, show help instead of status
+	const collectionArgIdx = process.argv.indexOf("collection");
+	const nextArg =
+		collectionArgIdx >= 0 ? process.argv[collectionArgIdx + 1] : undefined;
+	if (nextArg === "help") {
+		process.argv.splice(collectionArgIdx + 1, 1, "--help");
+		// Re-parse will be handled by Commander on the next tick; just return to let it flow
+		console.log(
+			[
+				"",
+				"  Manage knowledge collections",
+				"",
+				"  Usage: forge collection [options] [command]",
+				"",
+				"  Commands:",
+				"    new    Scaffold a new collection manifest",
+				"    build  Build collection bundles from dist artifacts",
+				"",
+				"  Options:",
+				"    -h, --help  display help for command",
+				"",
+			].join("\n"),
+		);
+		return;
+	}
+
+	const collectionsDir = "collections";
+	const collections = await loadCollections(collectionsDir);
+	const catalogEntries = await generateCatalog([...SOURCE_DIRS]);
+	const membership = buildCollectionMembership(catalogEntries);
+	const warnings = validateArtifactCollectionRefs(catalogEntries, collections);
+
+	if (collections.length === 0 && warnings.length === 0) {
+		console.log("");
+		console.log(chalk.bold("  No collections yet."));
+		console.log("");
+		console.log(
+			chalk.dim(
+				'  Collections are curated bundles of artifacts (e.g. "aws", "security", "onboarding").',
+			),
+		);
+		console.log(
+			chalk.dim("  Artifacts declare membership in their frontmatter: ") +
+				chalk.cyan("collections: [aws]"),
+		);
+		console.log("");
+
+		const create = await p.confirm({
+			message: "Create your first collection now?",
+			initialValue: true,
+		});
+
+		if (p.isCancel(create) || !create) {
+			console.log("");
+			console.log(
+				chalk.dim("  Run ") +
+					chalk.cyan("forge collection new <name>") +
+					chalk.dim(" when you're ready."),
+			);
+			console.log("");
+			return;
+		}
+
+		const name = await p.text({
+			message: "Collection name (kebab-case)",
+			placeholder: "my-collection",
+			validate: (v) => {
+				if (!v || v.trim().length === 0) return "Name is required";
+				if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(v.trim()))
+					return "Must be kebab-case (e.g. my-collection)";
+			},
+		});
+		if (p.isCancel(name)) return;
+
+		await collectionNewCommand(name as string);
+		return;
+	}
+
+	const total = collections.length;
+	const totalMembers = [...membership.values()].reduce(
+		(s, m) => s + m.length,
+		0,
+	);
+
+	console.log(
+		chalk.bold(`\n  Collections`) +
+			chalk.dim(
+				` (${total} manifest${total !== 1 ? "s" : ""}, ${totalMembers} total memberships)\n`,
+			),
+	);
+
+	if (collections.length > 0) {
+		// Column widths
+		const nameWidth =
+			Math.max(...collections.map((c) => c.displayName.length), 4) + 2;
+		const trustWidth = 12;
+
+		for (const c of collections) {
+			const members = membership.get(c.name) ?? [];
+			const memberCount = members.length;
+			const trustBadge = c.trust
+				? chalk.dim(`[${c.trust}]`).padEnd(trustWidth + 7) // pad accounts for dim codes
+				: "".padEnd(trustWidth);
+			const nameStr = chalk.cyan(c.displayName.padEnd(nameWidth));
+			const countStr =
+				memberCount === 0
+					? chalk.yellow(`${memberCount} members`)
+					: chalk.green(`${memberCount} member${memberCount !== 1 ? "s" : ""}`);
+			const desc = c.description ? chalk.dim(`  ${c.description}`) : "";
+
+			console.log(`  ${nameStr}${trustBadge}${countStr}${desc}`);
+
+			if (members.length > 0 && members.length <= 5) {
+				console.log(chalk.dim(`    ${members.join(", ")}`));
+			} else if (members.length > 5) {
+				console.log(
+					chalk.dim(
+						`    ${members.slice(0, 4).join(", ")}, +${members.length - 4} more`,
+					),
+				);
+			}
+		}
+	}
+
+	// Unknown collection references (artifacts pointing to non-existent manifests)
+	if (warnings.length > 0) {
+		const uniqueUnknown = [
+			...new Set(warnings.map((w) => w.message.match(/"([^"]+)"/)?.[1] ?? "?")),
+		];
+		console.log("");
+		for (const name of uniqueUnknown) {
+			console.log(
+				chalk.yellow(
+					`  ⚠ Artifacts declare collection "${name}" — no manifest found in collections/`,
+				),
+			);
+		}
+	}
+
+	// Artifacts with no collection membership
+	const unaffiliated = catalogEntries.filter(
+		(e) => e.collections.length === 0,
+	).length;
+	if (unaffiliated > 0) {
+		console.log(
+			chalk.dim(
+				`\n  ${unaffiliated} artifact${unaffiliated !== 1 ? "s" : ""} not in any collection`,
+			),
+		);
+	}
+
+	console.log("");
+	console.log(
+		chalk.dim("  forge collection build   — generate distributable bundles"),
+	);
+	console.log("");
+}
+
+/**
+ * Scaffold a new collection manifest interactively.
+ * If `name` is provided, pre-populates the name prompt.
+ */
+export async function collectionNewCommand(name?: string): Promise<void> {
+	p.intro(chalk.bold("New collection"));
+
+	const collectionsDir = "collections";
+	await mkdir(collectionsDir, { recursive: true });
+
+	const collectionName =
+		name ??
+		((await p.text({
+			message: "Collection name (kebab-case)",
+			placeholder: "my-collection",
+			validate: (v) => {
+				if (!v || v.trim().length === 0) return "Name is required";
+				if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(v.trim()))
+					return "Must be kebab-case (e.g. my-collection)";
+			},
+		})) as string);
+	if (p.isCancel(collectionName)) {
+		p.cancel("Cancelled.");
+		return;
+	}
+
+	const filePath = join(collectionsDir, `${collectionName}.yaml`);
+	if (await exists(filePath)) {
+		console.error(
+			chalk.red(
+				`  Collection "${collectionName}" already exists at ${filePath}`,
+			),
+		);
+		process.exit(1);
+	}
+
+	const displayName = (await p.text({
+		message: "Display name",
+		placeholder: collectionName
+			.split("-")
+			.map((w) => w[0].toUpperCase() + w.slice(1))
+			.join(" "),
+	})) as string;
+	if (p.isCancel(displayName)) {
+		p.cancel("Cancelled.");
+		return;
+	}
+
+	const description = (await p.text({
+		message: "Description (one sentence)",
+		placeholder: `Artifacts for ${displayName || collectionName}`,
+	})) as string;
+	if (p.isCancel(description)) {
+		p.cancel("Cancelled.");
+		return;
+	}
+
+	const trust = await p.select({
+		message: "Trust lane",
+		options: TrustLaneSchema.options.map((t) => ({
+			value: t,
+			label: t,
+			hint: {
+				official: "maintained by core team",
+				partner: "maintained by trusted partner",
+				community: "community contributed",
+				experimental: "experimental / untested",
+			}[t],
+		})),
+		initialValue: "community" as const,
+	});
+	if (p.isCancel(trust)) {
+		p.cancel("Cancelled.");
+		return;
+	}
+
+	const resolvedDisplayName =
+		(displayName as string).trim() ||
+		collectionName
+			.split("-")
+			.map((w) => w[0].toUpperCase() + w.slice(1))
+			.join(" ");
+
+	const yaml = `${[
+		`name: ${collectionName}`,
+		`displayName: "${resolvedDisplayName}"`,
+		`description: "${(description as string).trim()}"`,
+		`trust: ${trust}`,
+		`tags: []`,
+	].join("\n")}\n`;
+
+	await writeFile(filePath, yaml, "utf-8");
+
+	p.outro(
+		chalk.green(`✓ Created ${filePath}\n\n`) +
+			chalk.dim(`  Add artifacts to this collection by setting:\n`) +
+			chalk.cyan(`  collections: [${collectionName}]\n`) +
+			chalk.dim(`  in their knowledge.md frontmatter.`),
+	);
+}
+
+export async function collectionBuildCommand(options: {
+	harness?: string;
+}): Promise<void> {
+	const distDir = "dist";
+	const collectionsDir = "collections";
+
+	if (!(await exists(distDir))) {
+		console.error(
+			chalk.red("No dist/ directory found. Run `kanon build` first."),
+		);
+		process.exit(1);
+	}
+
+	if (
+		options.harness &&
+		!(SUPPORTED_HARNESSES as readonly string[]).includes(options.harness)
+	) {
+		console.error(
+			chalk.red(
+				`Error: Unknown harness "${options.harness}". Valid harnesses: ${SUPPORTED_HARNESSES.join(", ")}`,
+			),
+		);
+		process.exit(1);
+	}
+
+	const results = await buildCollections({
+		collectionsDir,
+		distDir,
+		harness: options.harness as HarnessName | undefined,
+	});
+
+	const totalArtifacts = results.reduce((s, r) => s + r.artifactsIncluded, 0);
+	const totalFiles = results.reduce((s, r) => s + r.filesWritten, 0);
+	const uniqueCollections = new Set(results.map((r) => r.collection)).size;
+
+	console.error(
+		chalk.green(
+			`\n✓ Collection build complete: ${uniqueCollections} collection(s), ${totalArtifacts} artifact inclusions, ${totalFiles} files written`,
+		),
+	);
+
+	if (options.harness) {
+		console.error(`  Harness: ${options.harness}`);
+	}
+}

package/src/collections.ts

@@ -0,0 +1,116 @@
+import { exists, readdir, readFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import * as yaml from "js-yaml";
+import {
+	type CatalogEntry,
+	type Collection,
+	CollectionSchema,
+	type ValidationWarning,
+} from "./schemas";
+
+/**
+ * Load all collection manifests from a directory.
+ * Each `<name>.yaml` file is parsed against CollectionSchema.
+ * Files that fail validation are skipped with a console warning.
+ */
+export async function loadCollections(
+	collectionsDir: string,
+): Promise<Collection[]> {
+	if (!(await exists(collectionsDir))) return [];
+
+	const entries = await readdir(collectionsDir);
+	const yamlFiles = entries
+		.filter((f) => f.endsWith(".yaml") || f.endsWith(".yml"))
+		.filter((f) => f !== ".gitkeep")
+		.sort();
+
+	const collections: Collection[] = [];
+
+	for (const file of yamlFiles) {
+		const filePath = join(collectionsDir, file);
+		let raw: string;
+		try {
+			raw = await readFile(filePath, "utf-8");
+		} catch {
+			continue;
+		}
+
+		let parsed: unknown;
+		try {
+			parsed = yaml.load(raw);
+		} catch {
+			console.error(`Warning: Skipping ${file} — invalid YAML`);
+			continue;
+		}
+
+		// Infer name from filename if not set in the manifest
+		if (parsed && typeof parsed === "object" && !("name" in parsed)) {
+			(parsed as Record<string, unknown>).name = basename(
+				file,
+				".yaml",
+			).replace(/\.yml$/, "");
+		}
+
+		const result = CollectionSchema.safeParse(parsed);
+		if (!result.success) {
+			console.error(
+				`Warning: Skipping ${file} — schema validation failed: ${result.error.issues.map((i) => i.message).join(", ")}`,
+			);
+			continue;
+		}
+
+		collections.push(result.data);
+	}
+
+	return collections;
+}
+
+/**
+ * Returns warnings for artifact catalog entries that declare a collection name
+ * not backed by any manifest in collectionsDir.
+ *
+ * This is a soft check — artifacts may be authored before a collection manifest
+ * exists, so this is a warning rather than an error.
+ */
+export function validateArtifactCollectionRefs(
+	entries: CatalogEntry[],
+	collections: Collection[],
+): ValidationWarning[] {
+	const knownCollectionNames = new Set(collections.map((c) => c.name));
+	const warnings: ValidationWarning[] = [];
+
+	for (const entry of entries) {
+		for (const collectionRef of entry.collections) {
+			if (!knownCollectionNames.has(collectionRef)) {
+				warnings.push({
+					field: "collections",
+					message: `Artifact declares collection "${collectionRef}" but no matching manifest found in collections/`,
+					filePath: `${entry.path}/knowledge.md`,
+				});
+			}
+		}
+	}
+
+	return warnings;
+}
+
+/**
+ * Summarize collection membership across all catalog entries.
+ * Returns a map from collection name → array of artifact names that belong to it.
+ */
+export function buildCollectionMembership(
+	entries: CatalogEntry[],
+): Map<string, string[]> {
+	const membership = new Map<string, string[]>();
+
+	for (const entry of entries) {
+		for (const collectionName of entry.collections) {
+			if (!membership.has(collectionName)) {
+				membership.set(collectionName, []);
+			}
+			membership.get(collectionName)?.push(entry.name);
+		}
+	}
+
+	return membership;
+}

package/src/compatibility.ts

@@ -0,0 +1,105 @@
+import type { AssetType, HarnessName } from "./schemas";
+
+export type CompatibilityLevel = "full" | "partial" | "none";
+
+/**
+ * Declares how well each asset type is supported by each harness.
+ *
+ * - "full"    — the harness has a native concept for this asset type
+ * - "partial" — the harness can represent this type but with degraded fidelity
+ * - "none"    — the harness has no meaningful output for this type
+ *
+ * Omitting a harness from a type's entry implies "full" (all standard harnesses
+ * support skills/powers/rules fully by default).
+ */
+export const ASSET_HARNESS_COMPATIBILITY: Record<
+	AssetType,
+	Partial<Record<HarnessName, CompatibilityLevel>>
+> = {
+	// Core types — all harnesses support these fully
+	skill: {},
+	// "power" is a deprecated alias for "skill" (see ADR-0051) — its asset-type
+	// compatibility should match skill's exactly, since taxonomy no longer
+	// carries different meaning. (Kiro's actual "power" *format* — as opposed
+	// to this deprecated *type* value — has no separate row here; format-level
+	// concerns live in format-registry.ts / adapters, not this asset-type table.)
+	power: {},
+	rule: {},
+
+	// Extended types
+	workflow: {
+		// Kiro, Copilot, and Q Developer have native workflow/agent file support
+		kiro: "full",
+		copilot: "full",
+		qdeveloper: "full",
+		"claude-code": "partial", // emitted as CLAUDE.md sections
+		cursor: "partial", // emitted as rule file
+		windsurf: "partial",
+		cline: "partial",
+	},
+	// This table answers a build-level question ("does the harness produce
+	// meaningful output for this asset type, or should getCompatibility's
+	// "none" tell build.ts to skip it entirely?") which is coarser than
+	// CAPABILITY_MATRIX[<harness>].agents in adapters/capabilities.ts (a
+	// feature-level question consumed by degradation/temper: "can this
+	// harness represent a declarative sub-agent file?"). The two should never
+	// *contradict* — a "full" here must not pair with "none"/"partial" there —
+	// but they may legitimately differ where a harness has no native agent
+	// format yet still emits generic, meaningful output (kiro, claude-code,
+	// codex all fall into this bucket: no dedicated agent surface, but the
+	// adapter still writes real output, hence "partial" rather than "none").
+	// See ADR-0050.
+	agent: {
+		kiro: "partial", // no dedicated agent format; rendered as steering/power prose
+		"claude-code": "partial", // no agent surface; rendered as generic CLAUDE.md prose
+		codex: "partial", // sub-agents exist via profiles, not declarative files
+		copilot: "full",
+		cursor: "none",
+		windsurf: "none",
+		cline: "none",
+		qdeveloper: "full",
+	},
+	prompt: {
+		// Prompts are universally representable as steering/rule content
+		kiro: "full",
+		"claude-code": "full",
+		codex: "full",
+		copilot: "full",
+		cursor: "full",
+		windsurf: "full",
+		cline: "full",
+		qdeveloper: "full",
+	},
+	template: {
+		// Templates are reference material — includable in any harness context
+		kiro: "full",
+		"claude-code": "full",
+		copilot: "partial",
+		cursor: "partial",
+		windsurf: "partial",
+		cline: "partial",
+		qdeveloper: "partial",
+	},
+	"reference-pack": {
+		// Reference packs are manual-inclusion only; all harnesses can host them
+		kiro: "full",
+		"claude-code": "full",
+		codex: "full",
+		copilot: "full",
+		cursor: "full",
+		windsurf: "full",
+		cline: "full",
+		qdeveloper: "full",
+	},
+};
+
+/**
+ * Returns the compatibility level for a given asset type and harness.
+ * Defaults to "full" if the harness is not explicitly listed for that type.
+ */
+export function getCompatibility(
+	type: AssetType,
+	harness: HarnessName,
+): CompatibilityLevel {
+	return ASSET_HARNESS_COMPATIBILITY[type]?.[harness] ?? "full";
+}