@thinkingsage/kanon 0.8.0

package/src/guild/global-cache.ts

@@ -0,0 +1,247 @@
+import type { Dirent } from "node:fs";
+import {
+	access,
+	copyFile,
+	mkdir,
+	readdir,
+	readFile,
+	writeFile,
+} from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Metadata stored alongside each cached artifact version. */
+export interface CachedArtifactMeta {
+	name: string;
+	version: string;
+	backend: string;
+	installedAt: string;
+	harnesses: string[];
+}
+
+/** A single entry in a collection's cached catalog. */
+export interface CatalogEntry {
+	name: string;
+}
+
+/** Public API surface for the global artifact cache. */
+export interface GlobalCacheAPI {
+	/** Root path of the global cache (platform-aware). */
+	readonly root: string;
+
+	/** List all cached versions for an artifact. */
+	listVersions(artifactName: string): Promise<string[]>;
+
+	/** Construct the dist path for a specific artifact/version/harness. */
+	distPath(artifactName: string, version: string, harness: string): string;
+
+	/** Check whether a specific artifact version exists in the cache. */
+	has(artifactName: string, version: string): Promise<boolean>;
+
+	/** Copy files from `sourceDir` into the cache and write/update `meta.json`. */
+	store(
+		artifactName: string,
+		version: string,
+		harness: string,
+		sourceDir: string,
+		backendLabel: string,
+	): Promise<void>;
+
+	/** Read the cached catalog for a collection at a given version. */
+	readCollectionCatalog(
+		collectionName: string,
+		version: string,
+	): Promise<CatalogEntry[]>;
+
+	/** Write catalog metadata for a collection version. */
+	writeCatalogMeta(
+		collectionName: string,
+		version: string,
+		entries: CatalogEntry[],
+	): Promise<void>;
+
+	/** Read the last-sync throttle timestamp, or `null` if not yet written. */
+	readThrottleState(): Promise<Date | null>;
+
+	/** Persist a throttle timestamp. */
+	writeThrottleState(timestamp: Date): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Recursively collect all relative file paths under `dir`. */
+async function collectFiles(dir: string, base: string = ""): Promise<string[]> {
+	const results: string[] = [];
+	let entries: Dirent[];
+	try {
+		entries = (await readdir(dir, { withFileTypes: true })) as Dirent[];
+	} catch {
+		return results;
+	}
+	for (const entry of entries) {
+		const rel = base ? `${base}/${entry.name}` : entry.name;
+		if (entry.isDirectory()) {
+			results.push(...(await collectFiles(join(dir, entry.name), rel)));
+		} else {
+			results.push(rel);
+		}
+	}
+	return results;
+}
+
+/** Check if a path exists on disk. */
+async function pathExists(p: string): Promise<boolean> {
+	try {
+		await access(p);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+
+export class GlobalCache implements GlobalCacheAPI {
+	readonly root: string;
+
+	constructor(rootOverride?: string) {
+		this.root = rootOverride ?? join(homedir(), ".forge");
+	}
+
+	// -- internal path helpers ------------------------------------------------
+
+	private artifactsDir(): string {
+		return join(this.root, "artifacts");
+	}
+
+	private versionDir(artifactName: string, version: string): string {
+		return join(this.artifactsDir(), artifactName, version);
+	}
+
+	private metaPath(artifactName: string, version: string): string {
+		return join(this.versionDir(artifactName, version), "meta.json");
+	}
+
+	private collectionsDir(): string {
+		return join(this.artifactsDir(), "collections");
+	}
+
+	private catalogPath(collectionName: string, version: string): string {
+		return join(this.collectionsDir(), collectionName, version, "catalog.json");
+	}
+
+	private throttlePath(): string {
+		return join(this.root, ".last-sync");
+	}
+
+	// -- GlobalCacheAPI -------------------------------------------------------
+
+	async listVersions(artifactName: string): Promise<string[]> {
+		const dir = join(this.artifactsDir(), artifactName);
+		try {
+			const entries = await readdir(dir, { withFileTypes: true });
+			return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+		} catch {
+			return [];
+		}
+	}
+
+	distPath(artifactName: string, version: string, harness: string): string {
+		return join(this.artifactsDir(), artifactName, version, "dist", harness);
+	}
+
+	async has(artifactName: string, version: string): Promise<boolean> {
+		return pathExists(this.versionDir(artifactName, version));
+	}
+
+	async store(
+		artifactName: string,
+		version: string,
+		harness: string,
+		sourceDir: string,
+		backendLabel: string,
+	): Promise<void> {
+		const dest = this.distPath(artifactName, version, harness);
+		await mkdir(dest, { recursive: true });
+
+		// Copy every file from sourceDir into the cache dist path
+		const files = await collectFiles(sourceDir);
+		for (const rel of files) {
+			const src = join(sourceDir, rel);
+			const target = join(dest, rel);
+			await mkdir(dirname(target), { recursive: true });
+			await copyFile(src, target);
+		}
+
+		// Read or create meta.json
+		const metaFile = this.metaPath(artifactName, version);
+		let meta: CachedArtifactMeta;
+		try {
+			const raw = await readFile(metaFile, "utf-8");
+			meta = JSON.parse(raw) as CachedArtifactMeta;
+			// Append harness if not already tracked
+			if (!meta.harnesses.includes(harness)) {
+				meta.harnesses.push(harness);
+			}
+		} catch {
+			meta = {
+				name: artifactName,
+				version,
+				backend: backendLabel,
+				installedAt: new Date().toISOString(),
+				harnesses: [harness],
+			};
+		}
+
+		await writeFile(metaFile, JSON.stringify(meta, null, 2), "utf-8");
+	}
+
+	async readCollectionCatalog(
+		collectionName: string,
+		version: string,
+	): Promise<CatalogEntry[]> {
+		const catalogFile = this.catalogPath(collectionName, version);
+		try {
+			const raw = await readFile(catalogFile, "utf-8");
+			return JSON.parse(raw) as CatalogEntry[];
+		} catch {
+			return [];
+		}
+	}
+
+	async writeCatalogMeta(
+		collectionName: string,
+		version: string,
+		entries: CatalogEntry[],
+	): Promise<void> {
+		const catalogFile = this.catalogPath(collectionName, version);
+		const dir = dirname(catalogFile);
+		await mkdir(dir, { recursive: true });
+		await writeFile(catalogFile, JSON.stringify(entries, null, 2), "utf-8");
+	}
+
+	async readThrottleState(): Promise<Date | null> {
+		try {
+			const raw = await readFile(this.throttlePath(), "utf-8");
+			const trimmed = raw.trim();
+			if (!trimmed) return null;
+			const date = new Date(trimmed);
+			return Number.isNaN(date.getTime()) ? null : date;
+		} catch {
+			return null;
+		}
+	}
+
+	async writeThrottleState(timestamp: Date): Promise<void> {
+		await mkdir(this.root, { recursive: true });
+		await writeFile(this.throttlePath(), timestamp.toISOString(), "utf-8");
+	}
+}

package/src/guild/hook-generator.ts

@@ -0,0 +1,100 @@
+// ---------------------------------------------------------------------------
+// Shell Snippet Generator — generate shell profile snippets for auto-sync
+// ---------------------------------------------------------------------------
+
+export type ShellType = "bash" | "zsh" | "fish" | "powershell";
+
+/**
+ * Generate a shell snippet that auto-syncs on directory change.
+ * The snippet detects `.forge/manifest.yaml` and runs
+ * `forge guild sync --auto-update` in the background.
+ * All output is redirected to /dev/null (or $null on PowerShell).
+ *
+ * Requirements: 7.1, 7.2, 7.3, 7.4, 7.7
+ */
+export function generateHookSnippet(shell: ShellType): string {
+	switch (shell) {
+		case "bash":
+			return bashSnippet();
+		case "zsh":
+			return zshSnippet();
+		case "fish":
+			return fishSnippet();
+		case "powershell":
+			return powershellSnippet();
+	}
+}
+
+/**
+ * Detect the current shell from the SHELL environment variable.
+ * Returns null if SHELL is not set.
+ *
+ * Requirements: 7.5, 7.6
+ */
+export function detectShell(): ShellType | null {
+	const shellEnv = process.env.SHELL;
+	if (!shellEnv) return null;
+
+	if (shellEnv.includes("zsh")) return "zsh";
+	if (shellEnv.includes("bash")) return "bash";
+	if (shellEnv.includes("fish")) return "fish";
+
+	return null;
+}
+
+// ---------------------------------------------------------------------------
+// Shell-specific snippets
+// ---------------------------------------------------------------------------
+
+function bashSnippet(): string {
+	return `# Kanon auto-sync hook (bash)
+_forge_guild_autosync() {
+  if [ -f ".forge/manifest.yaml" ]; then
+    forge guild sync --auto-update > /dev/null 2>&1 &
+  fi
+}
+
+cd() {
+  builtin cd "$@" && _forge_guild_autosync
+}`;
+}
+
+function zshSnippet(): string {
+	return `# Kanon auto-sync hook (zsh)
+_forge_guild_autosync() {
+  if [ -f ".forge/manifest.yaml" ]; then
+    forge guild sync --auto-update > /dev/null 2>&1 &
+  fi
+}
+
+autoload -Uz add-zsh-hook
+add-zsh-hook chpwd _forge_guild_autosync`;
+}
+
+function fishSnippet(): string {
+	return `# Kanon auto-sync hook (fish)
+function _forge_guild_autosync --on-variable PWD
+  if test -f ".forge/manifest.yaml"
+    forge guild sync --auto-update > /dev/null 2>&1 &
+  end
+end`;
+}
+
+function powershellSnippet(): string {
+	return `# Kanon auto-sync hook (PowerShell)
+function Invoke-ForgeGuildAutoSync {
+  if (Test-Path ".forge/manifest.yaml") {
+    Start-Process -NoNewWindow -FilePath "forge" -ArgumentList "guild","sync","--auto-update" -RedirectStandardOutput $null -RedirectStandardError $null
+  }
+}
+
+# Override Set-Location to trigger auto-sync
+$ExecutionContext.SessionState.InvokeCommand.CommandNotFoundAction = $null
+function Set-Location {
+  [CmdletBinding()]
+  param([string]$Path)
+  Microsoft.PowerShell.Management\\Set-Location $Path
+  Invoke-ForgeGuildAutoSync
+}
+Set-Alias -Name cd -Value Set-Location -Force`;
+}

package/src/guild/manifest.ts

@@ -0,0 +1,154 @@
+import * as yaml from "js-yaml";
+import { z } from "zod";
+import { SUPPORTED_HARNESSES } from "../schemas";
+
+// --- Schemas ---
+
+export const ManifestEntryModeSchema = z.enum(["required", "optional"]);
+
+/** An individual artifact reference in the manifest. */
+export const ArtifactManifestEntrySchema = z.object({
+	name: z.string().min(1),
+	version: z.string().min(1),
+	mode: ManifestEntryModeSchema.default("required"),
+	harnesses: z.array(z.string()).optional(),
+	backend: z.string().optional(),
+});
+
+/** A collection reference in the manifest. */
+export const CollectionManifestEntrySchema = z.object({
+	collection: z.string().min(1),
+	version: z.string().min(1),
+	mode: ManifestEntryModeSchema.default("required"),
+	harnesses: z.array(z.string()).optional(),
+	backend: z.string().optional(),
+});
+
+export const ManifestEntrySchema = z.union([
+	ArtifactManifestEntrySchema,
+	CollectionManifestEntrySchema,
+]);
+
+export const ManifestSchema = z
+	.object({
+		backend: z.string().optional(),
+		artifacts: z.array(ManifestEntrySchema).default([]),
+	})
+	.passthrough();
+
+export type ManifestEntryMode = z.infer<typeof ManifestEntryModeSchema>;
+export type ArtifactManifestEntry = z.infer<typeof ArtifactManifestEntrySchema>;
+export type CollectionManifestEntry = z.infer<
+	typeof CollectionManifestEntrySchema
+>;
+export type ManifestEntry = z.infer<typeof ManifestEntrySchema>;
+export type Manifest = z.infer<typeof ManifestSchema>;
+
+// --- Recognized harness set for filtering ---
+
+const RECOGNIZED_HARNESSES = new Set<string>(SUPPORTED_HARNESSES);
+
+// --- Functions ---
+
+/**
+ * Parse YAML string into a validated Manifest.
+ *
+ * Accepts an optional `warnings` array — unrecognized harness names
+ * are filtered out and a warning string is pushed for each one.
+ * Entries with both `name` and `collection` set are rejected.
+ */
+export function parseManifest(
+	yamlContent: string,
+	warnings?: string[],
+): Manifest {
+	// 1. YAML parse — catch syntax errors with line/column info
+	let raw: unknown;
+	try {
+		raw = yaml.load(yamlContent);
+	} catch (err: unknown) {
+		if (err && typeof err === "object" && "mark" in err) {
+			const mark = (err as { mark: { line?: number; column?: number } }).mark;
+			const line = mark.line != null ? mark.line + 1 : "?";
+			const col = mark.column != null ? mark.column + 1 : "?";
+			const msg = err instanceof Error ? err.message : String(err);
+			throw new Error(
+				`YAML syntax error at line ${line}, column ${col}: ${msg}`,
+			);
+		}
+		throw err;
+	}
+
+	// Handle empty YAML (null/undefined)
+	if (raw == null) {
+		raw = {};
+	}
+
+	// 2. Reject entries that have both `name` and `collection` set
+	if (
+		raw &&
+		typeof raw === "object" &&
+		"artifacts" in raw &&
+		Array.isArray((raw as Record<string, unknown>).artifacts)
+	) {
+		const artifacts = (raw as Record<string, unknown>).artifacts as unknown[];
+		for (let i = 0; i < artifacts.length; i++) {
+			const entry = artifacts[i];
+			if (
+				entry &&
+				typeof entry === "object" &&
+				"name" in entry &&
+				"collection" in entry
+			) {
+				throw new Error(
+					`Manifest entry at index ${i} has both "name" and "collection" fields set — each entry must have exactly one`,
+				);
+			}
+		}
+	}
+
+	// 3. Zod validation
+	const result = ManifestSchema.safeParse(raw);
+	if (!result.success) {
+		const issues = result.error.issues
+			.map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+			.join("; ");
+		throw new Error(`Manifest validation failed: ${issues}`);
+	}
+
+	const manifest = result.data;
+
+	// 4. Filter harnesses — emit warnings for unrecognized names (Req 3.5)
+	for (const entry of manifest.artifacts) {
+		if (entry.harnesses) {
+			const filtered: string[] = [];
+			for (const h of entry.harnesses) {
+				if (RECOGNIZED_HARNESSES.has(h)) {
+					filtered.push(h);
+				} else {
+					const entryLabel =
+						"name" in entry
+							? entry.name
+							: (entry as CollectionManifestEntry).collection;
+					const msg = `Unrecognized harness "${h}" in entry "${entryLabel}" — skipping`;
+					warnings?.push(msg);
+				}
+			}
+			(entry as { harnesses?: string[] }).harnesses =
+				filtered.length > 0 ? filtered : undefined;
+		}
+	}
+
+	return manifest;
+}
+
+/** Serialize a Manifest object to YAML string. */
+export function printManifest(manifest: Manifest): string {
+	return yaml.dump(manifest, { lineWidth: -1, noRefs: true });
+}
+
+/** Check if a ManifestEntry is a collection reference. */
+export function isCollectionRef(
+	entry: ManifestEntry,
+): entry is CollectionManifestEntry {
+	return "collection" in entry && typeof entry.collection === "string";
+}

package/src/guild/path-utils.ts

@@ -0,0 +1,12 @@
+// ---------------------------------------------------------------------------
+// Path utilities for cross-platform consistency
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalize a file path to use forward slashes only.
+ * Used for manifest and sync-lock output to ensure cross-platform consistency
+ * in committed files (Req 8.3).
+ */
+export function normalizePath(p: string): string {
+	return p.replace(/\\/g, "/");
+}