@thinkingsage/kanon 0.8.0

package/src/file-writer.ts

@@ -0,0 +1,61 @@
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import * as yaml from "js-yaml";
+import type { CanonicalHook, McpServerDefinition } from "./schemas";
+import type { WizardResult } from "./wizard";
+
+/**
+ * Serialize frontmatter and body into a gray-matter-compatible markdown string.
+ */
+export function buildKnowledgeMd(result: WizardResult): string {
+	const frontmatterYaml = yaml.dump(result.frontmatter, { lineWidth: -1 });
+	const body =
+		result.knowledgeBody.trim().length > 0
+			? result.knowledgeBody
+			: "TODO: Add your knowledge content here";
+	return `---\n${frontmatterYaml}---\n${body}\n`;
+}
+
+/**
+ * Serialize hooks array to YAML. Empty array produces `[]\n`.
+ */
+export function buildHooksYaml(hooks: CanonicalHook[]): string {
+	if (hooks.length === 0) {
+		return "[]\n";
+	}
+	return yaml.dump(hooks);
+}
+
+/**
+ * Serialize MCP servers array to YAML. Empty array produces `[]\n`.
+ */
+export function buildMcpServersYaml(servers: McpServerDefinition[]): string {
+	if (servers.length === 0) {
+		return "[]\n";
+	}
+	return yaml.dump(servers);
+}
+
+/**
+ * Write wizard results to the artifact directory.
+ * Overwrites knowledge.md, hooks.yaml, and mcp-servers.yaml.
+ * Returns the list of written file paths.
+ */
+export async function writeWizardResult(
+	artifactDir: string,
+	result: WizardResult,
+): Promise<string[]> {
+	const knowledgeMd = buildKnowledgeMd(result);
+	const hooksYaml = buildHooksYaml(result.hooks);
+	const mcpServersYaml = buildMcpServersYaml(result.mcpServers);
+
+	const knowledgePath = join(artifactDir, "knowledge.md");
+	const hooksPath = join(artifactDir, "hooks.yaml");
+	const mcpServersPath = join(artifactDir, "mcp-servers.yaml");
+
+	await writeFile(knowledgePath, knowledgeMd, "utf-8");
+	await writeFile(hooksPath, hooksYaml, "utf-8");
+	await writeFile(mcpServersPath, mcpServersYaml, "utf-8");
+
+	return [knowledgePath, hooksPath, mcpServersPath];
+}

package/src/format-registry.ts

@@ -0,0 +1,141 @@
+/**
+ * Per-harness format definitions and resolution.
+ *
+ * This module is now a **projection** over the Rosetta Stone built-in format
+ * contracts (ADR-RS-002). The public types, harness names, variants, defaults,
+ * sorted valid choices, and Kiro power deprecation behavior are preserved — but
+ * the data is derived from `src/rosetta/builtins/contracts.ts` rather than
+ * independently declared.
+ *
+ * Requirements: 2.9, 6.3, 14.5, 14.6, 14.7
+ */
+
+import type { HarnessName } from "./schemas";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Public Types (preserved)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+export interface HarnessFormatDef {
+	formats: readonly string[];
+	default: string;
+}
+
+export interface ResolveFormatResult {
+	format: string;
+	deprecationWarning?: string;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Registry Projection (lazy to avoid circular initialization)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Cached registry built on first access.
+ * Lazy initialization breaks the circular dependency chain:
+ * adapters/index → format-registry → rosetta/builtins/contracts →
+ * rosetta/builtins/compatibility-profiles → adapters/capabilities
+ */
+let _cachedRegistry: Record<HarnessName, HarnessFormatDef> | null = null;
+
+/**
+ * Build `HARNESS_FORMAT_REGISTRY` by projecting harness-bound built-in
+ * contracts. Each harness entry derives its `formats` (sorted variant keys)
+ * and `default` (contract's declared defaultVariant) from the frozen contracts.
+ */
+function getRegistry(): Record<HarnessName, HarnessFormatDef> {
+	if (_cachedRegistry !== null) {
+		return _cachedRegistry;
+	}
+
+	const { BUILTIN_FORMAT_CONTRACTS } = require("./rosetta/builtins/contracts");
+	const registry: Partial<Record<HarnessName, HarnessFormatDef>> = {};
+
+	for (const contract of BUILTIN_FORMAT_CONTRACTS) {
+		if (contract.harness === null) continue;
+
+		const harness = contract.harness as HarnessName;
+
+		// Only use the primary harness contract (direction: bidirectional or target)
+		// Skip source-only contracts like kiro-power, kiro-skill
+		if (contract.direction === "source") continue;
+
+		const variantKeys = Object.keys(contract.variants);
+		const defaultVariant = contract.defaultVariant as string;
+
+		registry[harness] = {
+			formats: variantKeys,
+			default: defaultVariant,
+		};
+	}
+
+	_cachedRegistry = registry as Record<HarnessName, HarnessFormatDef>;
+	return _cachedRegistry;
+}
+
+/**
+ * Format registry mapping each supported harness to its available formats
+ * and default format. Projected from built-in Rosetta Stone format contracts.
+ *
+ * Uses a Proxy to lazily initialize on first property access, breaking the
+ * circular dependency chain at module load time.
+ */
+export const HARNESS_FORMAT_REGISTRY: Record<HarnessName, HarnessFormatDef> =
+	new Proxy({} as Record<HarnessName, HarnessFormatDef>, {
+		get(_target, prop) {
+			return getRegistry()[prop as HarnessName];
+		},
+		ownKeys() {
+			return Reflect.ownKeys(getRegistry());
+		},
+		getOwnPropertyDescriptor(_target, prop) {
+			const registry = getRegistry();
+			if (prop in registry) {
+				return {
+					value: registry[prop as HarnessName],
+					writable: true,
+					enumerable: true,
+					configurable: true,
+				};
+			}
+			return undefined;
+		},
+		has(_target, prop) {
+			return prop in getRegistry();
+		},
+	});
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// resolveFormat — delegates to Rosetta Stone resolution semantics
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Resolve the output format for a harness from its harness-config section.
+ * Falls back to the registry default. Handles Kiro `power: true` backward compat.
+ *
+ * This function delegates to the same precedence logic used by Rosetta Stone's
+ * variant resolution (src/rosetta/resolution.ts) but provides the legacy
+ * `ResolveFormatResult` shape for backward compatibility.
+ */
+export function resolveFormat(
+	harness: HarnessName,
+	harnessConfig: Record<string, unknown> | undefined,
+): ResolveFormatResult {
+	// Explicit format field — highest precedence
+	if (harnessConfig?.format !== undefined) {
+		return { format: harnessConfig.format as string };
+	}
+
+	// Kiro backward compatibility: power: true without format field
+	if (harness === "kiro" && harnessConfig?.power === true) {
+		return {
+			format: "power",
+			deprecationWarning:
+				'harness-config.kiro.power is deprecated. Migrate to format: "power" in harness-config.kiro.',
+		};
+	}
+
+	// Fall back to the projected default from the registry
+	const registry = getRegistry();
+	return { format: registry[harness].default };
+}

package/src/guild/auto-updater.ts

@@ -0,0 +1,163 @@
+// ---------------------------------------------------------------------------
+// Auto-Updater — throttled remote version checks, download to GlobalCache
+// ---------------------------------------------------------------------------
+
+import { resolveBackend } from "../backends/index";
+import type { BackendConfig } from "../backends/types";
+import { SUPPORTED_HARNESSES } from "../schemas";
+import type { GlobalCacheAPI } from "./global-cache";
+import type { ManifestEntry } from "./manifest";
+
+/**
+ * Options for the auto-update check.
+ */
+export interface AutoUpdateOptions {
+	/** Minimum minutes between remote checks (default 60). */
+	throttleMinutes: number;
+	/** Global cache instance for reading/writing artifacts and throttle state. */
+	cache: GlobalCacheAPI;
+	/** Available backend configurations keyed by name. */
+	configBackends: Map<string, BackendConfig>;
+}
+
+/**
+ * Check backends for newer versions and download to cache.
+ * Respects throttle interval. Silently falls back on network failure.
+ *
+ * @returns List of updated artifact names and whether the check was skipped.
+ */
+export async function autoUpdate(
+	entries: ManifestEntry[],
+	manifestBackend: string | undefined,
+	options: AutoUpdateOptions,
+): Promise<{ updated: string[]; skipped: boolean }> {
+	const { throttleMinutes, cache, configBackends } = options;
+
+	// --- Throttle check (Req 6.4, 6.7) ---
+	const lastCheck = await cache.readThrottleState();
+	if (lastCheck !== null) {
+		const elapsedMs = Date.now() - lastCheck.getTime();
+		const intervalMs = throttleMinutes * 60 * 1000;
+		if (elapsedMs < intervalMs) {
+			return { updated: [], skipped: true };
+		}
+	}
+
+	const updated: string[] = [];
+
+	for (const entry of entries) {
+		try {
+			await processEntry(
+				entry,
+				manifestBackend,
+				configBackends,
+				cache,
+				updated,
+			);
+		} catch {
+			// Silently fall back to cache on network failure (Req 6.5, 10.2)
+			// No user-visible error — continue with next entry
+		}
+	}
+
+	// Write throttle state after check completes (Req 6.3)
+	await cache.writeThrottleState(new Date());
+
+	return { updated, skipped: false };
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the backend name for a manifest entry using the precedence chain:
+ * entry-level → manifest-level → first available in configBackends (Req 2.9, 12.1).
+ */
+function resolveBackendName(
+	entry: ManifestEntry,
+	manifestBackend: string | undefined,
+	configBackends: Map<string, BackendConfig>,
+): string | undefined {
+	// 1. Entry-level backend
+	if (entry.backend) return entry.backend;
+	// 2. Manifest-level backend
+	if (manifestBackend) return manifestBackend;
+	// 3. First available backend in config
+	const firstKey = configBackends.keys().next();
+	return firstKey.done ? undefined : firstKey.value;
+}
+
+/**
+ * Process a single manifest entry: check for newer remote versions and
+ * download them to the cache if found.
+ */
+async function processEntry(
+	entry: ManifestEntry,
+	manifestBackend: string | undefined,
+	configBackends: Map<string, BackendConfig>,
+	cache: GlobalCacheAPI,
+	updated: string[],
+): Promise<void> {
+	// Skip collection refs — they are expanded elsewhere
+	if ("collection" in entry) return;
+
+	const artifactName = entry.name;
+	const versionPin = entry.version;
+
+	// Resolve which backend to use
+	const backendName = resolveBackendName(
+		entry,
+		manifestBackend,
+		configBackends,
+	);
+	if (!backendName) return;
+
+	const backendConfig = configBackends.get(backendName);
+	if (!backendConfig) return;
+
+	const backend = resolveBackend(backendConfig);
+
+	// Fetch remote versions (Req 6.1, 12.2)
+	const remoteVersions = await backend.listVersions();
+
+	// Find versions that satisfy the pin
+	const satisfying = remoteVersions.filter((v) =>
+		Bun.semver.satisfies(v, versionPin),
+	);
+
+	if (satisfying.length === 0) return;
+
+	// Pick the highest satisfying version
+	const sorted = satisfying.sort(Bun.semver.order);
+	const newestRemote = sorted[sorted.length - 1];
+
+	// Check if this version is already in the cache
+	const alreadyCached = await cache.has(artifactName, newestRemote);
+	if (alreadyCached) return;
+
+	// Determine harnesses to fetch
+	const harnesses = entry.harnesses ?? [...SUPPORTED_HARNESSES];
+
+	// Download each harness dist and store in cache (Req 6.2, 12.3)
+	for (const harness of harnesses) {
+		try {
+			const sourceDir = await backend.fetchArtifact(
+				artifactName,
+				harness as Parameters<typeof backend.fetchArtifact>[1],
+				newestRemote,
+			);
+			await cache.store(
+				artifactName,
+				newestRemote,
+				harness,
+				sourceDir,
+				backendName,
+			);
+		} catch {
+			// Silently skip individual harness fetch failures (Req 6.5)
+		}
+	}
+
+	updated.push(artifactName);
+}

package/src/guild/backend-resolver.ts

@@ -0,0 +1,49 @@
+// ---------------------------------------------------------------------------
+// Backend Resolution — shared logic for resolving backend names
+// ---------------------------------------------------------------------------
+
+import type { BackendConfig } from "../backends/types";
+
+/**
+ * Result of resolving a backend name for a manifest entry.
+ */
+export interface BackendResolution {
+	name: string;
+	config: BackendConfig;
+}
+
+/**
+ * Resolve the backend for a manifest entry using the precedence chain:
+ * entry-level → manifest-level → config-level default (first key).
+ *
+ * Throws if the resolved backend name is not defined in configBackends (Req 12.5).
+ * Returns `null` if no backend can be resolved at all.
+ *
+ * Requirements: 12.1, 12.2, 12.3, 12.4, 12.5
+ */
+export function resolveEntryBackend(
+	entryBackend: string | undefined,
+	manifestBackend: string | undefined,
+	configBackends: Map<string, BackendConfig>,
+): BackendResolution | null {
+	// Precedence: entry → manifest → first config key
+	const name = entryBackend ?? manifestBackend ?? firstKey(configBackends);
+
+	if (!name) return null;
+
+	const config = configBackends.get(name);
+	if (!config) {
+		const available = [...configBackends.keys()];
+		const availableStr = available.length > 0 ? available.join(", ") : "(none)";
+		throw new Error(
+			`Unknown backend "${name}". Available backends: ${availableStr}`,
+		);
+	}
+
+	return { name, config };
+}
+
+function firstKey(map: Map<string, unknown>): string | undefined {
+	const iter = map.keys().next();
+	return iter.done ? undefined : iter.value;
+}