@thinkingsage/kanon 0.8.0

package/src/workspace.ts

@@ -0,0 +1,237 @@
+import { exists, readdir, readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import * as yaml from "js-yaml";
+import {
+	SUPPORTED_HARNESSES,
+	type ValidationError,
+	type WorkspaceConfig,
+	WorkspaceConfigSchema,
+} from "./schemas";
+
+/**
+ * Load workspace config from forge.config.ts or kanon.config.yaml.
+ * Prefers .ts if both exist (with a warning).
+ */
+export async function loadWorkspaceConfig(
+	rootDir: string,
+): Promise<{ config: WorkspaceConfig; source: string } | null> {
+	const tsPath = join(rootDir, "forge.config.ts");
+	const yamlPath = join(rootDir, "forge.config.yaml");
+
+	const tsExists = await exists(tsPath);
+	const yamlExists = await exists(yamlPath);
+
+	if (!tsExists && !yamlExists) {
+		return null;
+	}
+
+	if (tsExists && yamlExists) {
+		console.warn(
+			"Warning: Both forge.config.ts and forge.config.yaml exist. Preferring forge.config.ts.",
+		);
+	}
+
+	if (tsExists) {
+		const mod = await import(resolve(tsPath));
+		const raw = mod.default ?? mod;
+		const result = WorkspaceConfigSchema.safeParse(raw);
+		if (!result.success) {
+			throw new Error(
+				`Invalid workspace config in forge.config.ts: ${result.error.message}`,
+			);
+		}
+		return { config: result.data, source: tsPath };
+	}
+
+	// YAML path
+	const raw = await readFile(yamlPath, "utf-8");
+	const parsed = yaml.load(raw) as Record<string, unknown> | null;
+
+	if (!parsed || typeof parsed !== "object") {
+		return null;
+	}
+
+	// Extract workspace-specific fields from the full config
+	const workspaceFields: Record<string, unknown> = {};
+	if ("knowledgeSources" in parsed)
+		workspaceFields.knowledgeSources = parsed.knowledgeSources;
+	if ("sharedMcpServers" in parsed)
+		workspaceFields.sharedMcpServers = parsed.sharedMcpServers;
+	if ("defaults" in parsed) workspaceFields.defaults = parsed.defaults;
+	if ("projects" in parsed) workspaceFields.projects = parsed.projects;
+
+	// If no workspace fields are present, return null
+	if (!workspaceFields.knowledgeSources && !workspaceFields.projects) {
+		return null;
+	}
+
+	const result = WorkspaceConfigSchema.safeParse(workspaceFields);
+	if (!result.success) {
+		throw new Error(
+			`Invalid workspace config in forge.config.yaml: ${result.error.message}`,
+		);
+	}
+	return { config: result.data, source: yamlPath };
+}
+
+/**
+ * Validate workspace config against filesystem and known artifacts.
+ * Returns an array of validation errors.
+ */
+export async function validateWorkspaceConfig(
+	config: WorkspaceConfig,
+	rootDir: string,
+	knownArtifacts: Set<string>,
+): Promise<ValidationError[]> {
+	const errors: ValidationError[] = [];
+	const validHarnesses = new Set<string>(SUPPORTED_HARNESSES);
+
+	for (const project of config.projects) {
+		// Validate root path exists
+		const projectRoot = resolve(rootDir, project.root);
+		if (!(await exists(projectRoot))) {
+			errors.push({
+				field: `projects.${project.name}.root`,
+				message: `Project root directory does not exist: ${project.root}`,
+				filePath: "forge.config.yaml",
+			});
+		}
+
+		// Validate harness names
+		for (const harness of project.harnesses) {
+			if (!validHarnesses.has(harness)) {
+				errors.push({
+					field: `projects.${project.name}.harnesses`,
+					message: `Unknown harness name: ${harness}`,
+					filePath: "forge.config.yaml",
+				});
+			}
+		}
+
+		// Validate artifact include/exclude references
+		if (project.artifacts?.include) {
+			for (const name of project.artifacts.include) {
+				if (!knownArtifacts.has(name)) {
+					errors.push({
+						field: `projects.${project.name}.artifacts.include`,
+						message: `Unknown artifact name: ${name}`,
+						filePath: "forge.config.yaml",
+					});
+				}
+			}
+		}
+		if (project.artifacts?.exclude) {
+			for (const name of project.artifacts.exclude) {
+				if (!knownArtifacts.has(name)) {
+					errors.push({
+						field: `projects.${project.name}.artifacts.exclude`,
+						message: `Unknown artifact name: ${name}`,
+						filePath: "forge.config.yaml",
+					});
+				}
+			}
+		}
+	}
+
+	// Validate knowledgeSources paths exist
+	for (const source of config.knowledgeSources) {
+		const sourcePath = resolve(rootDir, source);
+		if (!(await exists(sourcePath))) {
+			errors.push({
+				field: "knowledgeSources",
+				message: `Knowledge source directory does not exist: ${source}`,
+				filePath: "forge.config.yaml",
+			});
+		}
+	}
+
+	// Validate default harnesses
+	if (config.defaults?.harnesses) {
+		for (const harness of config.defaults.harnesses) {
+			if (!validHarnesses.has(harness)) {
+				errors.push({
+					field: "defaults.harnesses",
+					message: `Unknown harness name in defaults: ${harness}`,
+					filePath: "forge.config.yaml",
+				});
+			}
+		}
+	}
+
+	return errors;
+}
+
+/**
+ * Merge artifacts from multiple knowledge source directories.
+ * Detects name conflicts when the same artifact name appears in multiple sources.
+ */
+export async function mergeKnowledgeSources(
+	sources: string[],
+	rootDir: string,
+): Promise<{
+	artifacts: Map<string, string>;
+	conflicts: Array<{ name: string; sources: string[] }>;
+}> {
+	// Map artifact name → source path (first occurrence)
+	const artifacts = new Map<string, string>();
+	// Track all sources per artifact name for conflict detection
+	const seen = new Map<string, string[]>();
+
+	for (const source of sources) {
+		const sourcePath = resolve(rootDir, source);
+		let entries: string[];
+		try {
+			entries = await readdir(sourcePath);
+		} catch {
+			// Skip non-existent or unreadable directories
+			continue;
+		}
+
+		for (const entry of entries) {
+			// Skip hidden files and non-directories
+			if (entry.startsWith(".")) continue;
+
+			const entryPath = join(sourcePath, entry);
+			const knowledgeFile = join(entryPath, "knowledge.md");
+			if (!(await exists(knowledgeFile))) continue;
+
+			const existing = seen.get(entry);
+			if (existing) {
+				existing.push(source);
+			} else {
+				seen.set(entry, [source]);
+				artifacts.set(entry, entryPath);
+			}
+		}
+	}
+
+	// Build conflicts array
+	const conflicts: Array<{ name: string; sources: string[] }> = [];
+	for (const [name, srcs] of seen) {
+		if (srcs.length > 1) {
+			conflicts.push({ name, sources: srcs });
+		}
+	}
+
+	return { artifacts, conflicts };
+}
+
+/**
+ * Serialize a WorkspaceConfig to YAML string.
+ */
+export function serializeWorkspaceConfig(config: WorkspaceConfig): string {
+	return yaml.dump(config, {
+		indent: 2,
+		lineWidth: -1,
+		noRefs: true,
+		sortKeys: false,
+	});
+}
+
+/**
+ * Parse a YAML string into a validated WorkspaceConfig.
+ */
+export function parseWorkspaceConfigYaml(yamlStr: string): WorkspaceConfig {
+	const parsed = yaml.load(yamlStr);
+	return WorkspaceConfigSchema.parse(parsed);
+}

package/templates/eval-contexts/claude-code.md.njk

@@ -0,0 +1,6 @@
+{# Simulates how Claude Code injects CLAUDE.md content #}
+The following instructions have been loaded from CLAUDE.md:
+
+{{ prompt }}
+
+---

package/templates/eval-contexts/cline.md.njk

@@ -0,0 +1,6 @@
+{# Simulates how Cline injects rule files #}
+The following rule has been loaded from .clinerules/:
+
+{{ prompt }}
+
+---

package/templates/eval-contexts/copilot.md.njk

@@ -0,0 +1,6 @@
+{# Simulates how GitHub Copilot injects instruction files #}
+The following instructions have been loaded from .github/copilot-instructions.md:
+
+{{ prompt }}
+
+---

package/templates/eval-contexts/cursor.md.njk

@@ -0,0 +1,6 @@
+{# Simulates how Cursor injects rule files #}
+The following rule has been loaded from .cursor/rules/:
+
+{{ prompt }}
+
+---

package/templates/eval-contexts/kiro.md.njk

@@ -0,0 +1,10 @@
+{# Simulates how Kiro injects steering file content into the LLM context #}
+You are Kiro, an AI assistant and IDE built to assist developers.
+
+The following steering file has been loaded into your context:
+
+{{ prompt }}
+
+---
+
+User: {{ user_query }}

package/templates/eval-contexts/qdeveloper.md.njk

@@ -0,0 +1,6 @@
+{# Simulates how Amazon Q Developer injects rule files #}
+The following rule has been loaded from .q/rules/:
+
+{{ prompt }}
+
+---

package/templates/eval-contexts/windsurf.md.njk

@@ -0,0 +1,6 @@
+{# Simulates how Windsurf injects rule files #}
+The following rule has been loaded from .windsurf/rules/:
+
+{{ prompt }}
+
+---

package/templates/harness-adapters/_base/attribution-footer.md.njk

@@ -0,0 +1,17 @@
+{%- if artifact.frontmatter.attribution and artifact.frontmatter.attribution.upstream | length -%}
+
+---
+
+## Sources & credits
+{% for u in artifact.frontmatter.attribution.upstream %}
+- **{{ u.work }}** — {{ u.authors | join(", ") if u.authors | length else "(author unknown)" }} [{{ u.relationship }}]{% if u.license %} ({{ u.license }}){% endif %}{% if u.url %} — {{ u.url }}{% endif %}
+{% endfor %}
+{%- if artifact.frontmatter.attribution["curated-by"] %}
+
+Curated by {{ artifact.frontmatter.attribution["curated-by"] }}.
+{%- endif %}
+{%- if artifact.frontmatter.attribution.notice %}
+
+{{ artifact.frontmatter.attribution.notice }}
+{%- endif %}
+{%- endif -%}

package/templates/harness-adapters/_base/base.md.njk

@@ -0,0 +1,16 @@
+{% block frontmatter %}{% endblock %}
+{% block header %}
+{# Generated by Kanon from knowledge/{{ artifact.name }} — do not edit #}
+{% endblock %}
+{% block body %}
+{{ artifact.body }}
+{% endblock %}
+{% block workflows %}
+{% for workflow in artifact.workflows %}
+
+## {{ workflow.name }}
+
+{{ workflow.content }}
+{% endfor %}
+{% endblock %}
+{% block footer %}{% include "../_base/attribution-footer.md.njk" %}{% endblock %}

package/templates/harness-adapters/claude-code/claude.md.njk

@@ -0,0 +1 @@
+{% extends "../_base/base.md.njk" %}

package/templates/harness-adapters/claude-code/mcp.json.njk

@@ -0,0 +1 @@
+{{ mcpConfig | dump(2) }}

package/templates/harness-adapters/claude-code/settings.json.njk

@@ -0,0 +1 @@
+{{ settings | dump(2) }}

package/templates/harness-adapters/claude-code/skill-library-index.md.njk

@@ -0,0 +1,13 @@
+---
+name: skill-library
+description: "Lists every skill installed by this plugin, with a one-line description and how to invoke each. Use when asked what skills are installed, to list skills, or to show the library."
+---
+
+## Installed Skills
+
+| Skill | Type | Description |
+|---|---|---|
+{% for entry in qualifying %}| `{{ entry.name }}` | {{ entry.type }} | {{ entry.description }} |
+{% endfor %}
+
+Ask about any skill by name, or describe what you're trying to do — Claude Code matches your request to the skill whose own trigger phrases fit best.

package/templates/harness-adapters/claude-code/skill.md.njk

@@ -0,0 +1,19 @@
+{% extends "../_base/base.md.njk" %}
+{% block frontmatter %}
+---
+name: {{ artifact.name }}
+description: {{ artifact.frontmatter.description | dump | safe }}
+---
+{% endblock %}
+{% block workflows %}
+{% if artifact.workflows | length %}
+
+## Reference Pointers
+
+Load these only when the workflow calls for them (progressive disclosure):
+
+{% for workflow in artifact.workflows %}
+- `references/{{ workflow.filename }}` — {{ workflow.name }}
+{% endfor %}
+{% endif %}
+{% endblock %}

package/templates/harness-adapters/cline/hook.sh.njk

@@ -0,0 +1,4 @@
+#!/bin/bash
+# Hook: {{ hook.name }}
+# {{ hook.description | default("") }}
+{{ hook.command }}

package/templates/harness-adapters/cline/mcp.json.njk

@@ -0,0 +1 @@
+{{ mcpConfig | dump(2) }}

package/templates/harness-adapters/cline/rule.md.njk

@@ -0,0 +1 @@
+{% extends "../_base/base.md.njk" %}

package/templates/harness-adapters/codex/agents-md.md.njk

@@ -0,0 +1,6 @@
+{% extends "../_base/base.md.njk" %}
+{% block footer %}
+{% for section in degradedSections %}
+{{ section }}
+{% endfor %}
+{% endblock %}

package/templates/harness-adapters/codex/agents-pointer.md.njk

@@ -0,0 +1,16 @@
+{# Generated by Kanon from knowledge/{{ artifact.name }} — do not edit #}
+# Repository Agents Guide
+
+Keep this file short and repo-wide. Point to deeper docs when detail is conditional.
+
+## {{ artifact.frontmatter.displayName | default(artifact.frontmatter.name | titleCase) }}
+
+{{ artifact.frontmatter.description }}
+
+**Trigger:** When a task matches this skill, read and follow
+`.codex/skills/{{ artifact.name }}/SKILL.md`. That file carries the full
+workflow; its `references/` directory holds phase detail to load on demand.
+{% if artifact.frontmatter.keywords | length %}
+
+**Keywords:** {{ artifact.frontmatter.keywords | join(", ") }}
+{% endif %}

package/templates/harness-adapters/codex/skill.md.njk

@@ -0,0 +1,27 @@
+{% extends "../_base/base.md.njk" %}
+{% block frontmatter %}
+---
+name: {{ artifact.name }}
+description: {{ artifact.frontmatter.description | dump | safe }}
+{% if artifact.frontmatter.keywords | length %}
+keywords: {{ artifact.frontmatter.keywords | dump }}
+{% endif %}
+---
+{% endblock %}
+{% block workflows %}
+{% if artifact.workflows | length %}
+
+## Reference Pointers
+
+Load these only when the workflow calls for them (progressive disclosure):
+
+{% for workflow in artifact.workflows %}
+- `references/{{ workflow.filename }}` — {{ workflow.name }}
+{% endfor %}
+{% endif %}
+{% endblock %}
+{% block footer %}
+{% for section in degradedSections %}
+{{ section }}
+{% endfor %}
+{% endblock %}

package/templates/harness-adapters/copilot/agents.md.njk

@@ -0,0 +1 @@
+{% extends "../_base/base.md.njk" %}

package/templates/harness-adapters/copilot/instructions.md.njk

@@ -0,0 +1 @@
+{% extends "../_base/base.md.njk" %}

package/templates/harness-adapters/copilot/scoped.md.njk

@@ -0,0 +1,6 @@
+{% extends "../_base/base.md.njk" %}
+{% block frontmatter %}
+---
+applyTo: "{{ applyTo }}"
+---
+{% endblock %}

package/templates/harness-adapters/cursor/mcp.json.njk

@@ -0,0 +1 @@
+{{ mcpConfig | dump(2) }}

package/templates/harness-adapters/cursor/rule.md.njk

@@ -0,0 +1,6 @@
+{% extends "../_base/base.md.njk" %}
+{% block frontmatter %}
+---
+inclusion: {{ cursorInclusion | default("always") }}
+---
+{% endblock %}

package/templates/harness-adapters/kiro/hook.json.njk

@@ -0,0 +1 @@
+{{ hook | dump(2) }}

package/templates/harness-adapters/kiro/mcp.json.njk

@@ -0,0 +1 @@
+{{ mcpConfig | dump(2) }}

package/templates/harness-adapters/kiro/power-steering.md.njk

@@ -0,0 +1,3 @@
+{% extends "../_base/base.md.njk" %}
+{% block frontmatter %}{% endblock %}
+{% block header %}{% endblock %}

package/templates/harness-adapters/kiro/power.md.njk

@@ -0,0 +1,12 @@
+{% extends "../_base/base.md.njk" %}
+{% block frontmatter %}
+---
+name: "{{ artifact.frontmatter.name }}"
+displayName: "{{ artifact.frontmatter.displayName | default(artifact.frontmatter.name) }}"
+description: "{{ artifact.frontmatter.description }}"
+keywords: {{ artifact.frontmatter.keywords | dump }}
+author: "{{ artifact.frontmatter.author }}"
+---
+{% endblock %}
+{# Inline workflow content into POWER.md by default. Set harness-config.kiro.inline-workflows: false to keep POWER.md lean and rely on separate steering files (official-power style). #}
+{% block workflows %}{% if harnessConfig["inline-workflows"] != false %}{{ super() }}{% endif %}{% endblock %}

package/templates/harness-adapters/kiro/steering.md.njk

@@ -0,0 +1,16 @@
+{% extends "../_base/base.md.njk" %}
+{% block frontmatter %}
+---
+inclusion: {{ inclusion }}
+{% if inclusion == "fileMatch" and fileMatchPattern %}
+fileMatchPattern: "{{ fileMatchPattern }}"
+{% endif %}
+{% if artifact.frontmatter.description %}
+description: {{ artifact.frontmatter.description | dump | safe }}
+{% endif %}
+---
+{% endblock %}
+{% block header %}
+{{ auditComment | safe }}
+{# Generated by Kanon from knowledge/{{ artifact.name }} — do not edit #}
+{% endblock %}

package/templates/harness-adapters/qdeveloper/agent.md.njk

@@ -0,0 +1 @@
+{% extends "../_base/base.md.njk" %}

package/templates/harness-adapters/qdeveloper/mcp.json.njk

@@ -0,0 +1 @@
+{{ mcpConfig | dump(2) }}

package/templates/harness-adapters/qdeveloper/rule.md.njk

@@ -0,0 +1 @@
+{% extends "../_base/base.md.njk" %}

package/templates/harness-adapters/windsurf/mcp.json.njk

@@ -0,0 +1 @@
+{{ mcpConfig | dump(2) }}

package/templates/harness-adapters/windsurf/rule.md.njk

@@ -0,0 +1 @@
+{% extends "../_base/base.md.njk" %}

package/templates/harness-adapters/windsurf/workflow.md.njk

@@ -0,0 +1 @@
+{{ workflow.content }}

package/templates/knowledge/hooks.yaml.njk

@@ -0,0 +1,4 @@
+# Canonical hooks for {{ name }}
+# See docs for supported events: file_edited, file_created, file_deleted,
+# agent_stop, prompt_submit, pre_tool_use, post_tool_use, pre_task, post_task, user_triggered
+[]

package/templates/knowledge/knowledge.md.njk

@@ -0,0 +1,53 @@
+---
+name: {{ name }}
+displayName: {{ displayName }}
+description: "TODO: Add description"
+keywords: []
+author: "TODO: Add author"
+version: "0.1.0"
+harnesses:
+  - kiro
+  - claude-code
+  - copilot
+  - cursor
+  - windsurf
+  - cline
+  - qdeveloper
+type: skill
+inclusion: always
+# Categories: testing, security, code-style, devops, documentation, architecture, debugging, performance, accessibility
+categories: []
+# Ecosystem: freeform kebab-case values, e.g. typescript, python, react, bun
+ecosystem: []
+# Depends: artifact names this artifact depends on
+depends: []
+# Enhances: artifact names this artifact enhances
+enhances: []
+# Bazaar metadata (optional — remove comments to activate)
+maturity: experimental
+# trust: official|partner|community|experimental
+# license: MIT
+# audience: beginner|intermediate|advanced
+# risk-level: low|medium|high
+# model-assumptions: []
+# id: "@org/artifact-name"
+# collections: []   # kebab-case collection names this artifact belongs to
+---
+
+# {{ displayName }}
+
+## Overview
+
+TODO: What this artifact does, when to use it, and why it matters.
+
+## Best Practices
+
+TODO: Key principles, rules, or guidelines.
+
+## Examples
+
+TODO: Real-world usage scenarios showing the artifact in action.
+
+## Troubleshooting
+
+TODO: Common mistakes, pitfalls, and what to do when things go wrong.

package/templates/knowledge/mcp-servers.yaml.njk

@@ -0,0 +1,2 @@
+# MCP server definitions for {{ name }}
+[]