pi-crew 0.2.3 → 0.2.5

package/src/utils/file-coalescer.ts

@@ -1,86 +1,86 @@
-import * as fs from "node:fs";
-
-interface TimerApi {
-	setTimeout(handler: () => void, delayMs: number): unknown;
-	clearTimeout(handle: unknown): void;
-}
-
-const defaultTimerApi: TimerApi = {
-	setTimeout: (handler, delayMs) => setTimeout(handler, delayMs),
-	clearTimeout: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
-};
-
-export interface FileCoalescer {
-	schedule(file: string, delayMs?: number): boolean;
-	clear(): void;
-}
-
-export function createFileCoalescer(handler: (file: string) => void, defaultDelayMs: number, timerApi: TimerApi = defaultTimerApi): FileCoalescer {
-	const pending = new Map<string, unknown>();
-	return {
-		schedule(file, delayMs = defaultDelayMs) {
-			if (pending.has(file)) return false;
-			const timer = timerApi.setTimeout(() => {
-				pending.delete(file);
-				handler(file);
-			}, delayMs);
-			pending.set(file, timer);
-			return true;
-		},
-		clear() {
-			for (const timer of pending.values()) timerApi.clearTimeout(timer);
-			pending.clear();
-		},
-	};
-}
-
-interface ReadCacheEntry<T> {
-	value: T;
-	mtimeMs: number;
-	size: number;
-	expiresAt: number;
-}
-
-const readCache = new Map<string, ReadCacheEntry<unknown>>();
-const readCacheSizeLimit = 128;
-
-function evictOldestCacheEntry(): void {
-	if (readCache.size < readCacheSizeLimit) return;
-	// Map iteration order is insertion order; first key is LRU.
-	const oldestKey = readCache.keys().next().value;
-	if (oldestKey !== undefined) readCache.delete(oldestKey);
-}
-
-export function clearReadCache(): void {
-	readCache.clear();
-}
-
-export function readJsonFileCoalesced<T>(filePath: string, ttlMs: number, read: () => T): T {
-	const now = Date.now();
-	const stat = (() => {
-		try {
-			const fileStat = fs.statSync(filePath);
-			return { mtimeMs: fileStat.mtimeMs, size: fileStat.size };
-		} catch {
-			return undefined;
-		}
-	})();
-	const cached = readCache.get(filePath);
-	if (cached && stat && cached.expiresAt > now && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size) {
-		// Re-insert to implement LRU: move to end of Map.
-		readCache.delete(filePath);
-		readCache.set(filePath, cached);
-		return cached.value as T;
-	}
-	const value = read();
-	if (stat !== undefined) {
-		readCache.set(filePath, {
-			value,
-			mtimeMs: stat.mtimeMs,
-			size: stat.size,
-			expiresAt: now + ttlMs,
-		});
-		evictOldestCacheEntry();
-	}
-	return value;
-}
+import * as fs from "node:fs";
+
+interface TimerApi {
+	setTimeout(handler: () => void, delayMs: number): unknown;
+	clearTimeout(handle: unknown): void;
+}
+
+const defaultTimerApi: TimerApi = {
+	setTimeout: (handler, delayMs) => setTimeout(handler, delayMs),
+	clearTimeout: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
+};
+
+export interface FileCoalescer {
+	schedule(file: string, delayMs?: number): boolean;
+	clear(): void;
+}
+
+export function createFileCoalescer(handler: (file: string) => void, defaultDelayMs: number, timerApi: TimerApi = defaultTimerApi): FileCoalescer {
+	const pending = new Map<string, unknown>();
+	return {
+		schedule(file, delayMs = defaultDelayMs) {
+			if (pending.has(file)) return false;
+			const timer = timerApi.setTimeout(() => {
+				pending.delete(file);
+				handler(file);
+			}, delayMs);
+			pending.set(file, timer);
+			return true;
+		},
+		clear() {
+			for (const timer of pending.values()) timerApi.clearTimeout(timer);
+			pending.clear();
+		},
+	};
+}
+
+interface ReadCacheEntry<T> {
+	value: T;
+	mtimeMs: number;
+	size: number;
+	expiresAt: number;
+}
+
+const readCache = new Map<string, ReadCacheEntry<unknown>>();
+const readCacheSizeLimit = 128;
+
+function evictOldestCacheEntry(): void {
+	if (readCache.size < readCacheSizeLimit) return;
+	// Map iteration order is insertion order; first key is LRU.
+	const oldestKey = readCache.keys().next().value;
+	if (oldestKey !== undefined) readCache.delete(oldestKey);
+}
+
+export function clearReadCache(): void {
+	readCache.clear();
+}
+
+export function readJsonFileCoalesced<T>(filePath: string, ttlMs: number, read: () => T): T {
+	const now = Date.now();
+	const stat = (() => {
+		try {
+			const fileStat = fs.statSync(filePath);
+			return { mtimeMs: fileStat.mtimeMs, size: fileStat.size };
+		} catch {
+			return undefined;
+		}
+	})();
+	const cached = readCache.get(filePath);
+	if (cached && stat && cached.expiresAt > now && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size) {
+		// Re-insert to implement LRU: move to end of Map.
+		readCache.delete(filePath);
+		readCache.set(filePath, cached);
+		return cached.value as T;
+	}
+	const value = read();
+	if (stat !== undefined) {
+		readCache.set(filePath, {
+			value,
+			mtimeMs: stat.mtimeMs,
+			size: stat.size,
+			expiresAt: now + ttlMs,
+		});
+		evictOldestCacheEntry();
+	}
+	return value;
+}

package/src/utils/frontmatter.ts

@@ -1,68 +1,68 @@
-export interface ParsedFrontmatter {
-	frontmatter: Record<string, string>;
-	body: string;
-}
-
-export function parseFrontmatter(content: string): ParsedFrontmatter {
-	if (!content.startsWith("---\n") && !content.startsWith("---\r\n")) {
-		return { frontmatter: {}, body: content };
-	}
-
-	const normalized = content.replaceAll("\r\n", "\n");
-	const end = normalized.indexOf("\n---\n", 4);
-	if (end === -1) {
-		// Support frontmatter that ends at EOF without trailing newline after ---.
-		const altEnd = normalized.indexOf("\n---", 4);
-		if (altEnd !== -1 && altEnd + 4 === normalized.length) {
-			const raw = normalized.slice(4, altEnd);
-			const frontmatter = parseLines(raw);
-			return { frontmatter, body: "" };
-		}
-		return { frontmatter: {}, body: content };
-	}
-
-	const raw = normalized.slice(4, end);
-	const body = normalized.slice(end + "\n---\n".length);
-	const frontmatter = parseLines(raw);
-	return { frontmatter, body };
-}
-
-function parseLines(raw: string): Record<string, string> {
-	const frontmatter: Record<string, string> = {};
-	for (const line of raw.split("\n")) {
-		const trimmed = line.trim();
-		if (!trimmed || trimmed.startsWith("#")) continue;
-		const separator = trimmed.indexOf(":");
-		if (separator === -1) continue;
-		const key = trimmed.slice(0, separator).trim();
-		const value = trimmed.slice(separator + 1).trim();
-		if (key) frontmatter[key] = value;
-	}
-	return frontmatter;
-}
-
-export function parseCsv(value: string | undefined): string[] | undefined {
-	if (value === undefined) return undefined;
-	// Handle quoted values with commas inside.
-	const values = splitCsv(value).map((item) => item.trim()).filter(Boolean);
-	return values.length > 0 ? [...new Set(values)] : undefined;
-}
-
-function splitCsv(input: string): string[] {
-	const result: string[] = [];
-	let current = "";
-	let inQuotes = false;
-	for (let i = 0; i < input.length; i++) {
-		const char = input[i];
-		if (char === '"') {
-			inQuotes = !inQuotes;
-		} else if (char === "," && !inQuotes) {
-			result.push(current);
-			current = "";
-		} else {
-			current += char;
-		}
-	}
-	result.push(current);
-	return result;
-}
+export interface ParsedFrontmatter {
+	frontmatter: Record<string, string>;
+	body: string;
+}
+
+export function parseFrontmatter(content: string): ParsedFrontmatter {
+	if (!content.startsWith("---\n") && !content.startsWith("---\r\n")) {
+		return { frontmatter: {}, body: content };
+	}
+
+	const normalized = content.replaceAll("\r\n", "\n");
+	const end = normalized.indexOf("\n---\n", 4);
+	if (end === -1) {
+		// Support frontmatter that ends at EOF without trailing newline after ---.
+		const altEnd = normalized.indexOf("\n---", 4);
+		if (altEnd !== -1 && altEnd + 4 === normalized.length) {
+			const raw = normalized.slice(4, altEnd);
+			const frontmatter = parseLines(raw);
+			return { frontmatter, body: "" };
+		}
+		return { frontmatter: {}, body: content };
+	}
+
+	const raw = normalized.slice(4, end);
+	const body = normalized.slice(end + "\n---\n".length);
+	const frontmatter = parseLines(raw);
+	return { frontmatter, body };
+}
+
+function parseLines(raw: string): Record<string, string> {
+	const frontmatter: Record<string, string> = {};
+	for (const line of raw.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed || trimmed.startsWith("#")) continue;
+		const separator = trimmed.indexOf(":");
+		if (separator === -1) continue;
+		const key = trimmed.slice(0, separator).trim();
+		const value = trimmed.slice(separator + 1).trim();
+		if (key) frontmatter[key] = value;
+	}
+	return frontmatter;
+}
+
+export function parseCsv(value: string | undefined): string[] | undefined {
+	if (value === undefined) return undefined;
+	// Handle quoted values with commas inside.
+	const values = splitCsv(value).map((item) => item.trim()).filter(Boolean);
+	return values.length > 0 ? [...new Set(values)] : undefined;
+}
+
+function splitCsv(input: string): string[] {
+	const result: string[] = [];
+	let current = "";
+	let inQuotes = false;
+	for (let i = 0; i < input.length; i++) {
+		const char = input[i];
+		if (char === '"') {
+			inQuotes = !inQuotes;
+		} else if (char === "," && !inQuotes) {
+			result.push(current);
+			current = "";
+		} else {
+			current += char;
+		}
+	}
+	result.push(current);
+	return result;
+}

package/src/utils/fs-watch.ts

@@ -1,31 +1,88 @@
-import * as fs from "node:fs";
-import type { FSWatcher, WatchListener } from "node:fs";
-
-export const FS_WATCH_RETRY_DELAY_MS = 5000;
-
-export function closeWatcher(watcher: FSWatcher | null | undefined): void {
-	if (!watcher) {
-		return;
-	}
-
-	try {
-		watcher.close();
-	} catch {
-		// Ignore watcher close errors
-	}
-}
-
-export function watchWithErrorHandler(
-	path: string,
-	listener: WatchListener<string>,
-	onError: (error?: unknown) => void,
-): FSWatcher | null {
-	try {
-		const watcher = fs.watch(path, listener);
-		watcher.on("error", onError);
-		return watcher;
-	} catch (error) {
-		onError(error);
-		return null;
-	}
-}
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { FSWatcher, WatchListener } from "node:fs";
+
+export const FS_WATCH_RETRY_DELAY_MS = 5000;
+
+export function closeWatcher(watcher: FSWatcher | null | undefined): void {
+	if (!watcher) {
+		return;
+	}
+
+	try {
+		watcher.close();
+	} catch {
+		// Ignore watcher close errors
+	}
+}
+
+export function watchWithErrorHandler(
+	path: string,
+	listener: WatchListener<string>,
+	onError: (error?: unknown) => void,
+): FSWatcher | null {
+	try {
+		const watcher = fs.watch(path, listener);
+		watcher.on("error", onError);
+		return watcher;
+	} catch (error) {
+		onError(error);
+		return null;
+	}
+}
+
+/**
+ * 1.3 — Watch a directory recursively and invoke `onChange` when any file
+ * inside changes. Falls back to `null` on systems where `fs.watch` rejects
+ * recursive mode (e.g., Linux when running on older kernels via FUSE/network FS).
+ *
+ * Callers MUST handle null and fall back to polling. The watcher emits the
+ * filename relative to `rootDir` (forward-slash normalised on Windows).
+ */
+export function createRecursiveWatcher(
+	rootDir: string,
+	onChange: (relativePath: string) => void,
+	onError: (error: unknown) => void,
+): FSWatcher | null {
+	try {
+		if (!fs.existsSync(rootDir)) fs.mkdirSync(rootDir, { recursive: true });
+		const watcher = fs.watch(rootDir, { recursive: true }, (_eventType, filename) => {
+			if (typeof filename !== "string" || filename.length === 0) return;
+			onChange(filename.replace(/\\/g, "/"));
+		});
+		watcher.on("error", (error) => {
+			try { watcher.close(); } catch { /* ignore */ }
+			onError(error);
+		});
+		return watcher;
+	} catch (error) {
+		onError(error);
+		return null;
+	}
+}
+
+/**
+ * Given a path relative to `<crewRoot>/state`, return the runId that owns
+ * the change, or undefined if the path doesn't match any tracked run layout.
+ */
+export function runIdFromStateRelativePath(relativePath: string): string | undefined {
+	const parts = relativePath.split("/");
+	// Layout is `runs/{runId}/...` — see docs/architecture.md state layer.
+	if (parts.length >= 2 && parts[0] === "runs" && parts[1]) return parts[1];
+	return undefined;
+}
+
+/** Convenience: combine the two helpers for `<crewRoot>/state` watching. */
+export function watchCrewState(
+	stateDir: string,
+	onRunChange: (runId: string) => void,
+	onError: (error: unknown) => void,
+): FSWatcher | null {
+	return createRecursiveWatcher(stateDir, (relativePath) => {
+		const runId = runIdFromStateRelativePath(relativePath);
+		if (runId) onRunChange(runId);
+	}, onError);
+}
+
+// Re-export path helper so callers don't pull node:path just for join.
+export const joinPath = path.join;