@thinkingsage/kanon 0.8.0

package/src/adapters/qdeveloper.ts

@@ -0,0 +1,115 @@
+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 qdeveloperAdapter: 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: "qdeveloper",
+					message: `Strict mode: capability ${capability} not supported by harness qdeveloper`,
+				});
+				return { files, warnings };
+			}
+			const degradation = applyDegradation(
+				entry.degradation ?? "inline",
+				capability,
+				artifact,
+				"qdeveloper",
+			);
+			warnings.push(...degradation.warnings);
+		}
+	}
+
+	const harnessConfig = (artifact.frontmatter as Record<string, unknown>)[
+		"harness-config"
+	] as Record<string, unknown> | undefined;
+	const qdeveloperConfig = (harnessConfig?.qdeveloper ?? {}) as Record<
+		string,
+		unknown
+	>;
+	const { format } = resolveFormat("qdeveloper", qdeveloperConfig);
+
+	// Generate .q/rules/<artifact>.md when format is "rule"
+	if (format === "rule") {
+		const ruleContent = renderTemplate(templateEnv, "qdeveloper/rule.md.njk", {
+			artifact,
+		});
+		files.push({
+			relativePath: `.q/rules/${artifact.name}.md`,
+			content: ruleContent,
+		});
+	}
+
+	// Generate .q/agents/ files when format is "agent" or when workflows exist
+	if (format === "agent") {
+		// In agent format, produce agent file from the artifact body
+		const agentContent = renderTemplate(
+			templateEnv,
+			"qdeveloper/agent.md.njk",
+			{ artifact },
+		);
+		files.push({
+			relativePath: `.q/agents/${artifact.name}.md`,
+			content: agentContent,
+		});
+	}
+
+	// Generate .q/agents/ files from workflows (regardless of format)
+	for (const wf of artifact.workflows) {
+		const agentContent = renderTemplate(
+			templateEnv,
+			"qdeveloper/agent.md.njk",
+			{ artifact: { ...artifact, body: wf.content, workflows: [] } },
+		);
+		files.push({
+			relativePath: `.q/agents/${wf.filename}`,
+			content: agentContent,
+		});
+	}
+
+	// Generate MCP configuration
+	if (artifact.mcpServers.length > 0) {
+		const mcpConfig = buildMcpConfig(artifact.mcpServers);
+		const mcpContent = renderTemplate(templateEnv, "qdeveloper/mcp.json.njk", {
+			mcpConfig,
+		});
+		files.push({ relativePath: ".q/mcp.json", content: mcpContent });
+	}
+
+	// Skip hooks with warning
+	if (artifact.hooks.length > 0) {
+		warnings.push({
+			artifactName: artifact.name,
+			harnessName: "qdeveloper",
+			message:
+				"Amazon Q Developer does not support hooks; skipping all hook definitions",
+		});
+	}
+
+	return { files, warnings };
+};

package/src/adapters/types.ts

@@ -0,0 +1,81 @@
+import type nunjucks from "nunjucks";
+import type {
+	CapabilityEntry,
+	HarnessName,
+	KnowledgeArtifact,
+	McpServerDefinition,
+} from "../schemas";
+import { isStdioServer } from "../schemas";
+import type { HarnessCapabilityName } from "./capabilities";
+
+export interface OutputFile {
+	relativePath: string;
+	content: string;
+	executable?: boolean;
+}
+
+export interface AdapterWarning {
+	artifactName: string;
+	harnessName: string;
+	message: string;
+}
+
+export interface AdapterError {
+	artifactName: string;
+	harnessName: HarnessName;
+	message: string;
+	/** Optional: the field/path or filename that caused the error */
+	field?: string;
+}
+
+export interface AdapterResult {
+	files: OutputFile[];
+	warnings: AdapterWarning[];
+	/** Optional error channel for strict violations; unset by default so existing adapters compile unchanged */
+	errors?: AdapterError[];
+}
+
+export interface AdapterContext {
+	capabilities: Record<HarnessCapabilityName, CapabilityEntry>;
+	strict: boolean;
+}
+
+export type HarnessAdapter = (
+	artifact: KnowledgeArtifact,
+	templateEnv: nunjucks.Environment,
+	context?: AdapterContext,
+) => AdapterResult;
+
+/**
+ * Build a harness-native mcpServers config object from canonical server definitions.
+ * Handles both stdio (command-based) and URL-based (SSE/HTTP) servers.
+ */
+export function buildMcpConfig(
+	servers: McpServerDefinition[],
+): Record<string, unknown> {
+	const mcpConfig: Record<string, unknown> = { mcpServers: {} };
+	for (const server of servers) {
+		if (isStdioServer(server)) {
+			const entry: Record<string, unknown> = {
+				command: server.command,
+				args: server.args,
+				env: server.env,
+			};
+			if (server.timeout) entry.timeout = server.timeout;
+			if (server.autoApprove?.length) entry.autoApprove = server.autoApprove;
+			if (server.disabled !== undefined) entry.disabled = server.disabled;
+			(mcpConfig.mcpServers as Record<string, unknown>)[server.name] = entry;
+		} else {
+			const entry: Record<string, unknown> = {
+				url: server.url,
+			};
+			if (server.env && Object.keys(server.env).length > 0)
+				entry.env = server.env;
+			if (server.timeout) entry.timeout = server.timeout;
+			if (server.autoApprove?.length) entry.autoApprove = server.autoApprove;
+			if (server.disabled !== undefined) entry.disabled = server.disabled;
+			(mcpConfig.mcpServers as Record<string, unknown>)[server.name] = entry;
+		}
+	}
+	return mcpConfig;
+}

package/src/adapters/windsurf.ts

@@ -0,0 +1,96 @@
+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 windsurfAdapter: 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: "windsurf",
+					message: `Strict mode: capability ${capability} not supported by harness windsurf`,
+				});
+				return { files, warnings };
+			}
+			const degradation = applyDegradation(
+				entry.degradation ?? "inline",
+				capability,
+				artifact,
+				"windsurf",
+			);
+			warnings.push(...degradation.warnings);
+		}
+	}
+
+	const harnessConfig = (artifact.frontmatter as Record<string, unknown>)[
+		"harness-config"
+	] as Record<string, unknown> | undefined;
+	const windsurfConfig = (harnessConfig?.windsurf ?? {}) as Record<
+		string,
+		unknown
+	>;
+	resolveFormat("windsurf", windsurfConfig);
+
+	// Generate .windsurf/rules/<artifact>.md
+	const ruleContent = renderTemplate(templateEnv, "windsurf/rule.md.njk", {
+		artifact,
+	});
+	files.push({
+		relativePath: `.windsurf/rules/${artifact.name}.md`,
+		content: ruleContent,
+	});
+
+	// Copy workflows to .windsurf/workflows/
+	for (const wf of artifact.workflows) {
+		const wfContent = renderTemplate(templateEnv, "windsurf/workflow.md.njk", {
+			workflow: wf,
+		});
+		files.push({
+			relativePath: `.windsurf/workflows/${wf.filename}`,
+			content: wfContent,
+		});
+	}
+
+	// Generate .windsurf/mcp.json
+	if (artifact.mcpServers.length > 0) {
+		const mcpConfig = buildMcpConfig(artifact.mcpServers);
+		const mcpContent = renderTemplate(templateEnv, "windsurf/mcp.json.njk", {
+			mcpConfig,
+		});
+		files.push({ relativePath: ".windsurf/mcp.json", content: mcpContent });
+	}
+
+	// Skip hooks with warning
+	if (artifact.hooks.length > 0) {
+		warnings.push({
+			artifactName: artifact.name,
+			harnessName: "windsurf",
+			message: "Windsurf does not support hooks; skipping all hook definitions",
+		});
+	}
+
+	return { files, warnings };
+};

package/src/admin.ts

@@ -0,0 +1,283 @@
+import { exists, mkdir, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import matter from "gray-matter";
+import * as yaml from "js-yaml";
+import { generateCatalog } from "./catalog";
+import {
+	type CatalogEntry,
+	type Frontmatter,
+	FrontmatterSchema,
+} from "./schemas";
+
+const KEBAB_CASE_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
+/** Input shape for create/update requests */
+export interface ArtifactInput {
+	name: string;
+	displayName?: string;
+	description: string;
+	keywords: string[];
+	author: string;
+	version: string;
+	harnesses: string[];
+	type: string;
+	inclusion?: string;
+	categories: string[];
+	ecosystem: string[];
+	depends: string[];
+	enhances: string[];
+	body: string;
+}
+
+/**
+ * Converts a display name to a kebab-case artifact name.
+ * Lowercases, strips non-alphanumeric characters, and joins segments with hyphens.
+ */
+export function toKebabCase(input: string): string {
+	return input
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, " ")
+		.trim()
+		.split(/\s+/)
+		.filter((s) => s.length > 0)
+		.join("-");
+}
+
+/**
+ * Validates ArtifactInput against FrontmatterSchema and the kebab-case name pattern.
+ * Returns either the parsed Frontmatter data or an array of field-level errors.
+ */
+export function validateArtifactInput(
+	input: ArtifactInput,
+):
+	| { success: true; data: Frontmatter }
+	| { success: false; errors: Array<{ field: string; message: string }> } {
+	const errors: Array<{ field: string; message: string }> = [];
+
+	// Validate name against kebab-case pattern
+	if (!KEBAB_CASE_PATTERN.test(input.name)) {
+		errors.push({
+			field: "name",
+			message:
+				"Name must be kebab-case (lowercase alphanumeric segments separated by hyphens)",
+		});
+	}
+
+	// Build the frontmatter object for schema validation
+	const frontmatterData: Record<string, unknown> = {
+		name: input.name,
+		description: input.description,
+		keywords: input.keywords,
+		author: input.author,
+		version: input.version,
+		harnesses: input.harnesses,
+		type: input.type,
+		categories: input.categories,
+		ecosystem: input.ecosystem,
+		depends: input.depends,
+		enhances: input.enhances,
+	};
+
+	if (input.displayName !== undefined) {
+		frontmatterData.displayName = input.displayName;
+	}
+	if (input.inclusion !== undefined) {
+		frontmatterData.inclusion = input.inclusion;
+	}
+
+	const result = FrontmatterSchema.safeParse(frontmatterData);
+
+	if (!result.success) {
+		for (const issue of result.error.issues) {
+			errors.push({
+				field: issue.path.join(".") || "unknown",
+				message: issue.message,
+			});
+		}
+	}
+
+	if (errors.length > 0) {
+		return { success: false, errors };
+	}
+
+	return { success: true, data: result.data as Frontmatter };
+}
+
+/**
+ * Return whether a scalar can remain unquoted without gray-matter changing
+ * its type or value when the generated frontmatter is parsed again.
+ */
+function preservesYamlStringValue(value: string): boolean {
+	try {
+		const parsed: unknown = matter(`---\nvalue: ${value}\n---\n`).data.value;
+		return typeof parsed === "string" && parsed === value;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Remove quotes only from strings that survive a gray-matter round-trip as
+ * strings. Non-string values remain in the representation emitted by js-yaml.
+ */
+function unquoteSafeYamlScalars(yamlContent: string): string {
+	return yamlContent
+		.split("\n")
+		.map((line: string): string => {
+			const match = line.match(/^(\s*(?:-\s+|[^:]+:\s+))'((?:[^']|'')*)'\s*$/);
+			if (!match) return line;
+
+			const [, prefix, encodedScalar] = match;
+			const scalar = encodedScalar.replace(/''/g, "'");
+			if (preservesYamlStringValue(scalar)) {
+				return `${prefix}${scalar}`;
+			}
+			return line;
+		})
+		.join("\n");
+}
+
+/**
+ * Converts Frontmatter + body into a knowledge.md string.
+ * Produces YAML frontmatter wrapped in `---` delimiters, followed by body content.
+ */
+export function serializeFrontmatter(
+	frontmatter: Frontmatter,
+	body: string,
+): string {
+	const yamlStr = yaml.dump(frontmatter, {
+		lineWidth: -1,
+		noRefs: true,
+		quoteStyle: "single",
+		forceQuotes: true,
+	});
+	return `---\n${unquoteSafeYamlScalars(yamlStr)}---\n${body}`;
+}
+
+/**
+ * Creates a new artifact directory with knowledge.md, hooks.yaml, mcp-servers.yaml, and workflows/.
+ * Validates input, checks for conflicts, writes files, and returns the new CatalogEntry.
+ */
+export async function createArtifact(
+	knowledgeDir: string,
+	input: ArtifactInput,
+): Promise<CatalogEntry> {
+	// Validate input
+	const validation = validateArtifactInput(input);
+	if (!validation.success) {
+		const error: Error & { type?: string; details?: unknown } = new Error(
+			"Validation failed",
+		);
+		error.type = "validation";
+		error.details = validation.errors;
+		throw error;
+	}
+
+	const artifactDir = join(knowledgeDir, input.name);
+
+	// Check for existing directory
+	if (await exists(artifactDir)) {
+		const error: Error & { type?: string } = new Error(
+			`Artifact '${input.name}' already exists`,
+		);
+		error.type = "conflict";
+		throw error;
+	}
+
+	// Create the artifact directory
+	await mkdir(artifactDir, { recursive: true });
+
+	// Write knowledge.md
+	const knowledgeMd = serializeFrontmatter(validation.data, input.body);
+	await writeFile(join(artifactDir, "knowledge.md"), knowledgeMd, "utf-8");
+
+	// Write empty hooks.yaml and mcp-servers.yaml
+	await writeFile(join(artifactDir, "hooks.yaml"), "[]\n", "utf-8");
+	await writeFile(join(artifactDir, "mcp-servers.yaml"), "[]\n", "utf-8");
+
+	// Create empty workflows/ subdirectory
+	await mkdir(join(artifactDir, "workflows"), { recursive: true });
+
+	// Re-scan catalog and find the new entry
+	const entries = await generateCatalog(knowledgeDir);
+	const newEntry = entries.find((e) => e.name === input.name);
+
+	if (!newEntry) {
+		throw new Error("Failed to find newly created artifact in catalog");
+	}
+
+	return newEntry;
+}
+
+/**
+ * Updates an existing artifact's knowledge.md (preserves all other files).
+ * Validates input, checks the artifact directory exists, overwrites knowledge.md,
+ * re-scans catalog, and returns the updated CatalogEntry.
+ */
+export async function updateArtifact(
+	knowledgeDir: string,
+	name: string,
+	input: ArtifactInput,
+): Promise<CatalogEntry> {
+	// Validate input
+	const validation = validateArtifactInput(input);
+	if (!validation.success) {
+		const error: Error & { type?: string; details?: unknown } = new Error(
+			"Validation failed",
+		);
+		error.type = "validation";
+		error.details = validation.errors;
+		throw error;
+	}
+
+	const artifactDir = join(knowledgeDir, name);
+
+	// Check that the artifact directory exists
+	if (!(await exists(artifactDir))) {
+		const error: Error & { type?: string } = new Error(
+			`Artifact '${name}' not found`,
+		);
+		error.type = "not-found";
+		throw error;
+	}
+
+	// Overwrite only knowledge.md — preserve hooks.yaml, mcp-servers.yaml, workflows/, etc.
+	const knowledgeMd = serializeFrontmatter(validation.data, input.body);
+	await writeFile(join(artifactDir, "knowledge.md"), knowledgeMd, "utf-8");
+
+	// Re-scan catalog and find the updated entry
+	const entries = await generateCatalog(knowledgeDir);
+	const updatedEntry = entries.find((e) => e.name === input.name);
+
+	if (!updatedEntry) {
+		throw new Error("Failed to find updated artifact in catalog");
+	}
+
+	return updatedEntry;
+}
+
+/**
+ * Deletes an artifact directory recursively.
+ * Validates the directory exists, removes it entirely, and re-scans the catalog.
+ */
+export async function deleteArtifact(
+	knowledgeDir: string,
+	name: string,
+): Promise<void> {
+	const artifactDir = join(knowledgeDir, name);
+
+	// Check that the artifact directory exists
+	if (!(await exists(artifactDir))) {
+		const error: Error & { type?: string } = new Error(
+			`Artifact '${name}' not found`,
+		);
+		error.type = "not-found";
+		throw error;
+	}
+
+	// Recursively remove the entire artifact directory
+	await rm(artifactDir, { recursive: true, force: true });
+
+	// Re-scan catalog to reflect the deletion
+	await generateCatalog(knowledgeDir);
+}

package/src/asset-conventions.ts

@@ -0,0 +1,118 @@
+import type { AssetType } from "./schemas";
+
+/**
+ * Per-asset-type file conventions and validation rules.
+ *
+ * Required files must exist for an artifact to be valid.
+ * Optional files are recognized but not required.
+ * Validation rules are human-readable descriptions used to generate warnings
+ * in validate.ts — the actual check logic lives there, this registry just
+ * defines which rules apply to which types.
+ */
+export interface AssetFileConvention {
+	requiredFiles: string[];
+	optionalFiles: string[];
+	/** Rule keys that validate.ts will check for this type. */
+	validationRuleKeys: AssetValidationRuleKey[];
+}
+
+export type AssetValidationRuleKey =
+	| "reference-pack-must-be-manual"
+	| "workflow-should-have-workflows-dir"
+	| "prompt-body-too-short"
+	| "agent-should-document-loop"
+	| "type-power-deprecated"
+	| "kiro-power-should-be-progressive"
+	| "kiro-power-workflow-should-be-progressive"
+	| "kiro-default-inclusion-informational";
+
+/**
+ * Markdown heading markers that signal an artifact's body documents
+ * agent-loop behavior (goal, inputs/outputs, an autonomous loop), independent
+ * of the artifact's declared `type`. Shared by validate.ts (agent
+ * conventions) and temper.ts (degradation detection) so both answer "does
+ * this content document agent-loop behavior?" the same way.
+ */
+const AGENT_LOOP_MARKERS: Record<string, RegExp> = {
+	goal: /^#{1,6}\s*(goal|objective)s?\b/im,
+	inputs: /^#{1,6}\s*inputs?\b/im,
+	outputs: /^#{1,6}\s*outputs?\b/im,
+	loop: /^#{1,6}\s*(autonomous\s+)?loop\b/im,
+};
+
+/**
+ * An artifact "documents agent-loop behavior" when its body has at least two
+ * of the four canonical headings (goal, inputs, outputs, loop). Two is a
+ * deliberately low bar — it flags likely agent content for degradation
+ * reporting without requiring a rigid template.
+ */
+export function documentsAgentLoop(body: string): boolean {
+	const hits = Object.values(AGENT_LOOP_MARKERS).filter((marker) =>
+		marker.test(body),
+	).length;
+	return hits >= 2;
+}
+
+export const ASSET_CONVENTION_RULES: Record<AssetValidationRuleKey, string> = {
+	"reference-pack-must-be-manual":
+		'reference-pack artifacts should use inclusion: "manual" to avoid being auto-injected into every session',
+	"workflow-should-have-workflows-dir":
+		"workflow artifacts should contain at least one file in the workflows/ directory",
+	"prompt-body-too-short":
+		"prompt artifacts should have a non-trivial body (at least 50 characters)",
+	"agent-should-document-loop":
+		"agent artifacts should document at least two of: a goal/objective, inputs, outputs, and an autonomous loop — otherwise harnesses have no basis for rendering agent-specific behavior",
+	"type-power-deprecated":
+		'type: "power" is a deprecated alias for "skill" — "power" is Kiro\'s own output-format concept, not an asset-taxonomy value. Use type: "skill" and set harness-config.kiro.format: "power" explicitly instead.',
+	"kiro-power-should-be-progressive":
+		'Artifacts using harness-config.kiro.format: "power" should not set inclusion to "always"; POWER.md is the always-on surface, steering/ files are meant to be progressively disclosed.',
+	"kiro-power-workflow-should-be-progressive":
+		'Artifacts using harness-config.kiro.format: "power" that ship workflow files should not set inclusion to "always"; workflow files are intended to be referenced on-demand.',
+	"kiro-default-inclusion-informational":
+		'No Kiro inclusion mode was set explicitly. Set harness-config.kiro.inclusion to "always", "fileMatch", or "manual" to make the Progressive Steering choice explicit.',
+};
+
+export const ASSET_CONVENTIONS: Record<AssetType, AssetFileConvention> = {
+	skill: {
+		requiredFiles: ["knowledge.md"],
+		optionalFiles: ["hooks.yaml", "mcp-servers.yaml", "workflows/"],
+		validationRuleKeys: [],
+	},
+	// "power" is a deprecated alias for "skill" (see ADR-0051) — same file
+	// conventions, plus a deprecation warning skill doesn't need.
+	power: {
+		requiredFiles: ["knowledge.md"],
+		optionalFiles: ["hooks.yaml", "mcp-servers.yaml", "workflows/"],
+		validationRuleKeys: ["type-power-deprecated"],
+	},
+	rule: {
+		requiredFiles: ["knowledge.md"],
+		optionalFiles: [],
+		validationRuleKeys: [],
+	},
+	workflow: {
+		requiredFiles: ["knowledge.md"],
+		optionalFiles: ["workflows/"],
+		validationRuleKeys: ["workflow-should-have-workflows-dir"],
+	},
+	agent: {
+		requiredFiles: ["knowledge.md"],
+		optionalFiles: ["hooks.yaml", "mcp-servers.yaml", "workflows/"],
+		validationRuleKeys: ["agent-should-document-loop"],
+	},
+	prompt: {
+		requiredFiles: ["knowledge.md"],
+		optionalFiles: [],
+		validationRuleKeys: ["prompt-body-too-short"],
+	},
+	template: {
+		requiredFiles: ["knowledge.md"],
+		optionalFiles: [],
+		validationRuleKeys: [],
+	},
+	"reference-pack": {
+		requiredFiles: ["knowledge.md"],
+		optionalFiles: [],
+		validationRuleKeys: ["reference-pack-must-be-manual"],
+	},
+};