@iowarp/clio-coder 0.4.0 → 0.4.2

package/src/domains/extensions/integrity.ts

@@ -0,0 +1,189 @@
+import { createHash } from "node:crypto";
+import {
+	closeSync,
+	constants,
+	fstatSync,
+	lstatSync,
+	openSync,
+	readdirSync,
+	readFileSync,
+	readlinkSync,
+	realpathSync,
+	type Stats,
+} from "node:fs";
+import path from "node:path";
+
+export interface ExtensionContentDigestOptions {
+	/** Root-relative regular files whose exact hashed bytes should be returned. */
+	capture?: ReadonlyArray<string>;
+}
+
+export interface ExtensionContentDigestResult {
+	digest: string;
+	captured: ReadonlyMap<string, Buffer>;
+}
+
+function contained(root: string, candidate: string): boolean {
+	const relative = path.relative(root, candidate);
+	return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}
+
+function digestFrame(hash: ReturnType<typeof createHash>, kind: string, relativePath: string, payload?: Buffer): void {
+	const header = Buffer.from(
+		`${kind}\0${relativePath.replaceAll(path.sep, "/")}\0${payload?.byteLength ?? 0}\0`,
+		"utf8",
+	);
+	hash.update(header);
+	if (payload) hash.update(payload);
+	hash.update("\0");
+}
+
+function sameFileState(left: Stats, right: Stats): boolean {
+	return (
+		left.dev === right.dev &&
+		left.ino === right.ino &&
+		left.mode === right.mode &&
+		left.nlink === right.nlink &&
+		left.size === right.size &&
+		left.mtimeMs === right.mtimeMs &&
+		left.ctimeMs === right.ctimeMs
+	);
+}
+
+function readStableRegularFile(filePath: string, inspected: Stats): Buffer {
+	const fd = openSync(filePath, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+	try {
+		const opened = fstatSync(fd);
+		if (!opened.isFile() || opened.nlink !== 1 || !sameFileState(inspected, opened)) {
+			throw new Error(`extension file changed while being opened: ${filePath}`);
+		}
+		const payload = readFileSync(fd);
+		if (!sameFileState(opened, fstatSync(fd))) {
+			throw new Error(`extension file changed while being hashed: ${filePath}`);
+		}
+		return payload;
+	} finally {
+		closeSync(fd);
+	}
+}
+
+function readStableContainedLink(linkPath: string, inspected: Stats, canonicalRoot: string): Buffer {
+	const canonicalTarget = realpathSync(linkPath);
+	if (!contained(canonicalRoot, canonicalTarget)) {
+		throw new Error(`symbolic link escapes the extension root: ${linkPath}`);
+	}
+	const target = readlinkSync(linkPath);
+	const after = lstatSync(linkPath);
+	if (!after.isSymbolicLink() || !sameFileState(inspected, after)) {
+		throw new Error(`symbolic link changed while being hashed: ${linkPath}`);
+	}
+	const canonicalAfter = realpathSync(linkPath);
+	if (canonicalAfter !== canonicalTarget || !contained(canonicalRoot, canonicalAfter)) {
+		throw new Error(`symbolic link changed or escapes the extension root: ${linkPath}`);
+	}
+	return Buffer.from(target, "utf8");
+}
+
+function assertStableDirectory(
+	directoryPath: string,
+	inspected: Stats,
+	canonicalDirectory: string,
+	canonicalRoot: string,
+	expectedEntries?: readonly string[],
+): void {
+	const after = lstatSync(directoryPath);
+	if (!after.isDirectory() || !sameFileState(inspected, after)) {
+		throw new Error(`extension directory changed while being hashed: ${directoryPath}`);
+	}
+	const canonicalAfter = realpathSync(directoryPath);
+	if (canonicalAfter !== canonicalDirectory || !contained(canonicalRoot, canonicalAfter)) {
+		throw new Error(`extension directory changed or escapes the extension root: ${directoryPath}`);
+	}
+	if (expectedEntries !== undefined) {
+		const currentEntries = readdirSync(directoryPath).sort();
+		if (
+			currentEntries.length !== expectedEntries.length ||
+			currentEntries.some((entry, index) => entry !== expectedEntries[index])
+		) {
+			throw new Error(`extension directory entries changed while being hashed: ${directoryPath}`);
+		}
+	}
+}
+
+function readStableDirectory(
+	directoryPath: string,
+	inspected: Stats,
+	canonicalRoot: string,
+): { canonicalDirectory: string; entries: string[] } {
+	const canonicalDirectory = realpathSync(directoryPath);
+	if (!contained(canonicalRoot, canonicalDirectory)) {
+		throw new Error(`extension directory escapes the extension root: ${directoryPath}`);
+	}
+	const entries = readdirSync(directoryPath).sort();
+	assertStableDirectory(directoryPath, inspected, canonicalDirectory, canonicalRoot);
+	return { canonicalDirectory, entries };
+}
+
+/**
+ * Hash an extension tree in stable relative-path order. File names, node kinds,
+ * symlink targets, empty directories, and file bytes are all integrity-bound.
+ * Symlinks must resolve within the package so their content cannot drift outside
+ * the tree without changing the digest.
+ */
+export function extensionContentDigestWithCapture(
+	root: string,
+	options: ExtensionContentDigestOptions = {},
+): ExtensionContentDigestResult {
+	const resolvedRoot = path.resolve(root);
+	const rootStat = lstatSync(resolvedRoot);
+	if (rootStat.isSymbolicLink()) {
+		throw new Error(`extension root must be a directory, not a symbolic link: ${resolvedRoot}`);
+	}
+	if (!rootStat.isDirectory()) {
+		throw new Error(`extension root must be a directory: ${resolvedRoot}`);
+	}
+	const canonicalRoot = realpathSync(resolvedRoot);
+	const canonicalizedRootStat = lstatSync(resolvedRoot);
+	if (!canonicalizedRootStat.isDirectory() || !sameFileState(rootStat, canonicalizedRootStat)) {
+		throw new Error(`extension root changed while being canonicalized: ${resolvedRoot}`);
+	}
+	const hash = createHash("sha256");
+	const requested = new Set((options.capture ?? []).map((entry) => entry.replaceAll(path.sep, "/")));
+	const captured = new Map<string, Buffer>();
+	const visit = (absolutePath: string, relativePath: string): void => {
+		const stat = lstatSync(absolutePath);
+		if (stat.isSymbolicLink()) {
+			if (relativePath === "") {
+				throw new Error(`extension root changed to a symbolic link while being hashed: ${absolutePath}`);
+			}
+			digestFrame(hash, "link", relativePath, readStableContainedLink(absolutePath, stat, canonicalRoot));
+			return;
+		}
+		if (stat.isDirectory()) {
+			digestFrame(hash, "directory", relativePath);
+			const { canonicalDirectory, entries } = readStableDirectory(absolutePath, stat, canonicalRoot);
+			for (const entry of entries) {
+				visit(path.join(absolutePath, entry), relativePath ? path.join(relativePath, entry) : entry);
+			}
+			assertStableDirectory(absolutePath, stat, canonicalDirectory, canonicalRoot, entries);
+			return;
+		}
+		if (stat.isFile()) {
+			if (stat.nlink !== 1) {
+				throw new Error(`hard-linked file is unsupported in an extension: ${absolutePath}`);
+			}
+			const payload = readStableRegularFile(absolutePath, stat);
+			digestFrame(hash, "file", relativePath, payload);
+			const key = relativePath.replaceAll(path.sep, "/");
+			if (requested.has(key)) captured.set(key, payload);
+			return;
+		}
+		throw new Error(`unsupported filesystem entry in extension: ${absolutePath}`);
+	};
+	visit(resolvedRoot, "");
+	return { digest: hash.digest("hex"), captured };
+}
+
+export function extensionContentDigest(root: string): string {
+	return extensionContentDigestWithCapture(root).digest;
+}

package/src/domains/extensions/manager.ts

@@ -4,27 +4,43 @@ export {
 	findExtensionManifestPath,
 	parseExtensionManifest,
 } from "./discovery.js";
-export { enabledExtensionResourceRoots, extensionResourcePath } from "./resources.js";
+export { enabledExtensionResourceRoots, extensionResourcePath, extensionSnapshotFor } from "./resources.js";
+export type { InstalledExtensionRecord } from "./state.js";
 export {
 	disableExtension,
 	enableExtension,
 	extensionBaseDir,
 	installExtension,
+	listInstalledExtensionRecords,
 	listInstalledExtensions,
 	removeExtension,
+	upgradeLegacyExtensionInstallState,
 } from "./state.js";
 export type {
 	ClioExtensionManifest,
 	ExtensionCandidate,
 	ExtensionDiagnostic,
+	ExtensionHookSource,
 	ExtensionInstallOptions,
 	ExtensionInstallResult,
 	ExtensionListOptions,
 	ExtensionManifestResources,
 	ExtensionMutationResult,
+	ExtensionProvenance,
+	ExtensionReloadCandidate,
+	ExtensionReloadCommitted,
+	ExtensionReloadPrepareResult,
+	ExtensionReloadRejection,
+	ExtensionReloadRejectionReason,
+	ExtensionReloadResult,
 	ExtensionResourceKind,
 	ExtensionResourceRoot,
 	ExtensionScope,
+	ExtensionSnapshot,
+	ExtensionSnapshotDiagnostics,
 	ExtensionState,
+	ExtensionStateUpgradeReport,
 	InstalledExtension,
+	LoadableExtension,
 } from "./types.js";
+export { isLoadableExtension } from "./types.js";

package/src/domains/extensions/resource-path.ts

@@ -0,0 +1,27 @@
+import { realpathSync, statSync } from "node:fs";
+import path from "node:path";
+
+export function extensionResourcePath(rootPath: string, resourcePath: string): string | null {
+	const root = path.resolve(rootPath);
+	const full = path.resolve(root, resourcePath);
+	const relative = path.relative(root, full);
+	if (relative === "" || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+		return null;
+	}
+	try {
+		const rootReal = realpathSync(root);
+		const fullReal = realpathSync(full);
+		const canonicalRelative = path.relative(rootReal, fullReal);
+		if (
+			canonicalRelative === ".." ||
+			canonicalRelative.startsWith(`..${path.sep}`) ||
+			path.isAbsolute(canonicalRelative)
+		) {
+			return null;
+		}
+		if (!statSync(fullReal).isDirectory()) return null;
+		return fullReal;
+	} catch {
+		return null;
+	}
+}

package/src/domains/extensions/resources.ts

@@ -1,50 +1,30 @@
-import { lstatSync, realpathSync } from "node:fs";
+import { realpathSync } from "node:fs";
 import path from "node:path";
-import { listInstalledExtensions } from "./state.js";
-import type { ExtensionResourceKind, ExtensionResourceRoot } from "./types.js";
+import { buildExtensionSnapshot } from "./snapshot.js";
+import { committedExtensionSnapshot } from "./snapshot-store.js";
+import type { ExtensionResourceKind, ExtensionResourceRoot, ExtensionSnapshot } from "./types.js";
 
-export function extensionResourcePath(rootPath: string, resourcePath: string): string | null {
-	const root = path.resolve(rootPath);
-	const full = path.resolve(root, resourcePath);
-	const relative = path.relative(root, full);
-	if (relative === "" || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))
-		return null;
+export { extensionResourcePath } from "./resource-path.js";
+
+/**
+ * The committed snapshot when a store is bound for this cwd; otherwise an
+ * ephemeral generation-0 build that never touches the store. The ephemeral
+ * branch serves the CLI, `config inspect` with an explicit cwd, and any
+ * process that never booted the extensions bundle.
+ */
+export function extensionSnapshotFor(cwd = process.cwd()): ExtensionSnapshot {
+	const committed = committedExtensionSnapshot();
 	try {
-		const rootReal = realpathSync(root);
-		const fullReal = realpathSync(full);
-		const canonicalRelative = path.relative(rootReal, fullReal);
-		if (
-			canonicalRelative === ".." ||
-			canonicalRelative.startsWith(`..${path.sep}`) ||
-			path.isAbsolute(canonicalRelative)
-		) {
-			return null;
-		}
-		if (!lstatSync(full).isDirectory()) return null;
-		return full;
+		if (committed !== null && committed.cwd === realpathSync(path.resolve(cwd))) return committed;
 	} catch {
-		return null;
+		// Fall through to an ephemeral build, which retains the original error semantics.
 	}
+	return buildExtensionSnapshot({ cwd, generation: 0 });
 }
 
 export function enabledExtensionResourceRoots(
 	kind: ExtensionResourceKind,
 	cwd = process.cwd(),
 ): ExtensionResourceRoot[] {
-	const roots: ExtensionResourceRoot[] = [];
-	for (const entry of listInstalledExtensions(cwd)) {
-		if (!entry.enabled || !entry.compatible || !entry.effective) continue;
-		const rel = entry.resources[kind];
-		if (!rel) continue;
-		const full = extensionResourcePath(entry.rootPath, rel);
-		if (!full) continue;
-		roots.push({
-			id: entry.id,
-			scope: entry.scope,
-			path: full,
-			rootPath: entry.rootPath,
-			source: `extension:${entry.scope}:${entry.id}`,
-		});
-	}
-	return roots;
+	return [...extensionSnapshotFor(cwd).resourceRoots[kind]];
 }

package/src/domains/extensions/snapshot-store.ts

@@ -0,0 +1,39 @@
+import type { ExtensionSnapshot } from "./types.js";
+
+/**
+ * Holder for the committed snapshot reference plus the process-local
+ * generation counter. `publish` is assignment-only: validation that a
+ * snapshot is strictly newer belongs to the candidate that prepared it, on
+ * the same stack, immediately before publishing.
+ */
+export interface ExtensionSnapshotStore {
+	current(): ExtensionSnapshot | null;
+	publish(snapshot: ExtensionSnapshot): void;
+	/** Reserve and return the next process-local generation. Reservations are never reused. */
+	nextGeneration(): number;
+}
+
+export function createExtensionSnapshotStore(): ExtensionSnapshotStore {
+	let committed: ExtensionSnapshot | null = null;
+	let reservedGeneration = 0;
+	return {
+		current: () => committed,
+		publish(snapshot) {
+			committed = snapshot;
+		},
+		nextGeneration() {
+			reservedGeneration += 1;
+			return reservedGeneration;
+		},
+	};
+}
+
+let boundStore: ExtensionSnapshotStore | null = null;
+
+export function committedExtensionSnapshot(): ExtensionSnapshot | null {
+	return boundStore?.current() ?? null;
+}
+
+export function bindExtensionSnapshotStore(store: ExtensionSnapshotStore | null): void {
+	boundStore = store;
+}

package/src/domains/extensions/snapshot.ts

@@ -0,0 +1,180 @@
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { extensionResourcePath } from "./resource-path.js";
+import { type InstalledExtensionRecord, listInstalledExtensionRecords } from "./state.js";
+import {
+	type ExtensionDiagnostic,
+	type ExtensionHookSource,
+	type ExtensionResourceKind,
+	type ExtensionResourceRoot,
+	type ExtensionSnapshot,
+	type ExtensionSnapshotDiagnostics,
+	isLoadableExtension,
+} from "./types.js";
+
+export const EXTENSION_SNAPSHOT_DIAGNOSTIC_CAP = 200;
+export const EXTENSION_SNAPSHOT_DIAGNOSTIC_PER_PACKAGE_CAP = 20;
+export const EXTENSION_SNAPSHOT_DIAGNOSTIC_MESSAGE_CAP = 512;
+
+const RESOURCE_KINDS: ReadonlyArray<ExtensionResourceKind> = ["skills", "prompts", "agents", "fleets", "themes"];
+
+export interface BuildExtensionSnapshotInput {
+	cwd: string;
+	generation: number;
+	now?: () => Date;
+	listRecords?: (cwd?: string, options?: { all?: boolean }) => InstalledExtensionRecord[];
+}
+
+function canonicalJson(value: unknown): string {
+	if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+	if (value !== null && typeof value === "object") {
+		const record = value as Record<string, unknown>;
+		return `{${Object.keys(record)
+			.sort()
+			.map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`)
+			.join(",")}}`;
+	}
+	return JSON.stringify(value) ?? "null";
+}
+
+function deepFreeze<T>(value: T, seen = new Set<object>()): T {
+	if (value === null || typeof value !== "object" || seen.has(value as object)) return value;
+	seen.add(value as object);
+	for (const child of Object.values(value as Record<string, unknown>)) deepFreeze(child, seen);
+	return Object.freeze(value);
+}
+
+function boundedDiagnostics(records: ReadonlyArray<InstalledExtensionRecord>): ExtensionSnapshotDiagnostics {
+	const entries: Array<ExtensionDiagnostic & { extensionId?: string }> = [];
+	let truncated = 0;
+	for (const { entry } of records) {
+		let admittedForPackage = 0;
+		for (const diagnostic of entry.diagnostics) {
+			if (
+				admittedForPackage >= EXTENSION_SNAPSHOT_DIAGNOSTIC_PER_PACKAGE_CAP ||
+				entries.length >= EXTENSION_SNAPSHOT_DIAGNOSTIC_CAP
+			) {
+				truncated += 1;
+				continue;
+			}
+			entries.push({
+				type: diagnostic.type,
+				message: diagnostic.message.slice(0, EXTENSION_SNAPSHOT_DIAGNOSTIC_MESSAGE_CAP),
+				...(diagnostic.path ? { path: diagnostic.path } : {}),
+				extensionId: entry.id,
+			});
+			admittedForPackage += 1;
+		}
+	}
+	return { entries, truncated };
+}
+
+export function buildExtensionSnapshot(input: BuildExtensionSnapshotInput): ExtensionSnapshot {
+	const cwd = realpathSync(path.resolve(input.cwd));
+	const records = (input.listRecords ?? listInstalledExtensionRecords)(cwd, { all: true });
+	const resourceRoots: Record<ExtensionResourceKind, ExtensionResourceRoot[]> = {
+		skills: [],
+		prompts: [],
+		agents: [],
+		fleets: [],
+		themes: [],
+	};
+	const hookSources: ExtensionHookSource[] = [];
+	const digestPackages: unknown[] = [];
+
+	for (const record of records) {
+		const { entry } = record;
+		const packageRoots: Array<{ kind: ExtensionResourceKind; path: string }> = [];
+		let hooksDigest: string | undefined;
+		if (isLoadableExtension(entry)) {
+			for (const kind of RESOURCE_KINDS) {
+				const relative = entry.resources[kind];
+				if (!relative) continue;
+				const resolved = extensionResourcePath(entry.rootPath, relative);
+				if (!resolved) continue;
+				resourceRoots[kind].push({
+					id: entry.id,
+					scope: entry.scope,
+					path: resolved,
+					rootPath: entry.rootPath,
+					source: `extension:${entry.scope}:${entry.id}`,
+					provenance: entry.provenance,
+					generation: input.generation,
+				});
+				packageRoots.push({ kind, path: resolved });
+			}
+			const hookBytes = record.captured?.get("hooks.yaml");
+			if (hookBytes !== undefined) {
+				hooksDigest = createHash("sha256").update(hookBytes).digest("hex");
+				let declarations: unknown = [];
+				let parseError: string | undefined;
+				try {
+					declarations = parseYaml(hookBytes.toString("utf8")) ?? [];
+				} catch (error) {
+					parseError = error instanceof Error ? error.message : String(error);
+				}
+				hookSources.push({
+					provenance: entry.provenance,
+					declarationsDigest: hooksDigest,
+					declarations,
+					...(parseError ? { parseError } : {}),
+				});
+			}
+		}
+		digestPackages.push({
+			id: entry.id,
+			scope: entry.scope,
+			loadable: entry.loadable,
+			...(entry.provenance ? { provenance: entry.provenance } : {}),
+			resourceRoots: packageRoots,
+			...(hooksDigest ? { hooksDigest } : {}),
+		});
+	}
+
+	const snapshot: ExtensionSnapshot = {
+		version: 1,
+		generation: input.generation,
+		cwd,
+		builtAt: (input.now ?? (() => new Date()))().toISOString(),
+		digest: createHash("sha256").update(canonicalJson(digestPackages)).digest("hex"),
+		packages: records.map((record) => record.entry),
+		resourceRoots,
+		hookSources,
+		diagnostics: boundedDiagnostics(records),
+	};
+	return deepFreeze(snapshot);
+}
+
+function packageFingerprints(snapshot: ExtensionSnapshot): Map<string, string> {
+	const grouped = new Map<string, unknown[]>();
+	for (const entry of snapshot.packages) {
+		const list = grouped.get(entry.id) ?? [];
+		list.push({
+			scope: entry.scope,
+			loadable: entry.loadable,
+			provenance: entry.provenance ?? null,
+			resources: entry.resources,
+		});
+		grouped.set(entry.id, list);
+	}
+	return new Map(
+		[...grouped].map(([id, values]) => [id, createHash("sha256").update(canonicalJson(values)).digest("hex")]),
+	);
+}
+
+export function diffExtensionSnapshots(
+	previous: ExtensionSnapshot | null,
+	next: ExtensionSnapshot,
+): { changed: boolean; added: string[]; removed: string[]; modified: string[] } {
+	if (previous === null) {
+		return { changed: true, added: [...new Set(next.packages.map((entry) => entry.id))], removed: [], modified: [] };
+	}
+	const before = packageFingerprints(previous);
+	const after = packageFingerprints(next);
+	const added = [...after.keys()].filter((id) => !before.has(id));
+	const removed = [...before.keys()].filter((id) => !after.has(id));
+	const modified = [...after.keys()].filter((id) => before.has(id) && before.get(id) !== after.get(id));
+	return { changed: previous.digest !== next.digest, added, removed, modified };
+}