pi-studio 0.9.52 → 0.9.54

package/shared/studio-file-watcher.js

@@ -0,0 +1,181 @@
+import { watchFile, unwatchFile } from "node:fs";
+import { resolve } from "node:path";
+import {
+	createStudioDiskRevision,
+	normalizeStudioDiskRevision,
+	readStudioDiskFileSnapshot,
+} from "./studio-disk-revisions.js";
+
+export const STUDIO_FILE_WATCH_INTERVAL_MS = 300;
+export const STUDIO_FILE_WATCH_DEBOUNCE_MS = 150;
+
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+
+function normalizeComparablePath(filePath) {
+	const normalized = resolve(filePath);
+	return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+
+function pathsMatch(left, right) {
+	return normalizeComparablePath(left) === normalizeComparablePath(right);
+}
+
+export function createStudioFileWatcher(options) {
+	const filePath = typeof options?.filePath === "string" ? options.filePath.trim() : "";
+	if (!filePath) throw new Error("Missing watched file path.");
+	const canonicalPath = resolve(filePath);
+	const requestedIntervalMs = Number(options?.intervalMs);
+	const requestedDebounceMs = Number(options?.debounceMs);
+	const intervalMs = Math.max(20, Math.floor(Number.isFinite(requestedIntervalMs) ? requestedIntervalMs : STUDIO_FILE_WATCH_INTERVAL_MS));
+	const debounceMs = Math.max(0, Math.floor(Number.isFinite(requestedDebounceMs) ? requestedDebounceMs : STUDIO_FILE_WATCH_DEBOUNCE_MS));
+	const readSnapshot = typeof options?.readSnapshot === "function" ? options.readSnapshot : readStudioDiskFileSnapshot;
+	const onUpdate = typeof options?.onUpdate === "function" ? options.onUpdate : () => undefined;
+	const onError = typeof options?.onError === "function" ? options.onError : () => undefined;
+	const onRecovered = typeof options?.onRecovered === "function" ? options.onRecovered : () => undefined;
+	let lastRevision = normalizeStudioDiskRevision(options?.initialRevision);
+	let lastError = null;
+	let generation = 0;
+	let debounceTimer = null;
+	let errorRetryTimer = null;
+	let startupReconcileTimer = null;
+	let refreshInFlight = null;
+	let refreshQueued = false;
+	let closed = false;
+
+	const readStableSnapshot = async () => {
+		const snapshot = await readSnapshot(canonicalPath);
+		if (!snapshot || typeof snapshot !== "object" || !pathsMatch(snapshot.path, canonicalPath)) {
+			throw new Error("The watched file location now resolves somewhere else.");
+		}
+		const revision = normalizeStudioDiskRevision(snapshot.revision)
+			|| createStudioDiskRevision(snapshot.buffer ?? snapshot.text ?? "");
+		const text = typeof snapshot.text === "string"
+			? snapshot.text
+			: Buffer.from(snapshot.buffer ?? "").toString("utf8");
+		return { ...snapshot, path: canonicalPath, text, revision };
+	};
+
+	const scheduleErrorRetry = () => {
+		if (closed || errorRetryTimer) return;
+		errorRetryTimer = setTimeout(() => {
+			errorRetryTimer = null;
+			void refresh().catch(() => {
+				// onError owns watcher failures; never create an unhandled rejection.
+			});
+		}, intervalMs);
+	};
+
+	const performRefresh = async () => {
+		try {
+			const snapshot = await readStableSnapshot();
+			if (closed) return false;
+			if (errorRetryTimer) {
+				clearTimeout(errorRetryTimer);
+				errorRetryTimer = null;
+			}
+			const recovered = lastError !== null;
+			const changed = snapshot.revision !== lastRevision;
+			if (changed) {
+				const nextGeneration = generation + 1;
+				await onUpdate(snapshot, { generation: nextGeneration, recovered });
+				if (closed) return false;
+				generation = nextGeneration;
+				lastRevision = snapshot.revision;
+				// Reconcile after publication in case a save landed while an earlier
+				// read or client update was in flight and filesystem events coalesced.
+				refreshQueued = true;
+			}
+			if (recovered) {
+				lastError = null;
+				await onRecovered(snapshot, { generation, changed });
+			}
+			return changed;
+		} catch (error) {
+			if (closed) return false;
+			const message = errorMessage(error);
+			if (message !== lastError) {
+				lastError = message;
+				await onError(error, { generation: generation + 1, lastRevision });
+			}
+			scheduleErrorRetry();
+			return false;
+		}
+	};
+
+	const refresh = () => {
+		if (closed) return Promise.resolve(false);
+		refreshQueued = true;
+		if (refreshInFlight) return refreshInFlight;
+		let changed = false;
+		const loop = (async () => {
+			while (!closed && refreshQueued) {
+				refreshQueued = false;
+				changed = await performRefresh() || changed;
+			}
+			return changed;
+		})();
+		const tracked = loop.finally(() => {
+			if (refreshInFlight === tracked) refreshInFlight = null;
+		});
+		refreshInFlight = tracked;
+		return tracked;
+	};
+
+	const schedule = () => {
+		if (closed) return;
+		if (debounceTimer) clearTimeout(debounceTimer);
+		debounceTimer = setTimeout(() => {
+			debounceTimer = null;
+			void refresh().catch(() => {
+				// onError owns watcher failures; never create an unhandled rejection.
+			});
+		}, debounceMs);
+	};
+
+	const listener = () => schedule();
+	watchFile(canonicalPath, { interval: intervalMs }, listener);
+	// StatWatcher establishes its first comparison baseline asynchronously. Reconcile
+	// once after that window so an atomic replacement immediately after subscribe
+	// cannot become the unseen baseline and wait forever for another filesystem event.
+	startupReconcileTimer = setTimeout(() => {
+		startupReconcileTimer = null;
+		void refresh().catch(() => {
+			// onError owns watcher failures; never create an unhandled rejection.
+		});
+	}, intervalMs);
+
+	return Object.freeze({
+		filePath: canonicalPath,
+		refresh,
+		async close() {
+			if (closed) return;
+			closed = true;
+			refreshQueued = false;
+			if (debounceTimer) {
+				clearTimeout(debounceTimer);
+				debounceTimer = null;
+			}
+			if (errorRetryTimer) {
+				clearTimeout(errorRetryTimer);
+				errorRetryTimer = null;
+			}
+			if (startupReconcileTimer) {
+				clearTimeout(startupReconcileTimer);
+				startupReconcileTimer = null;
+			}
+			unwatchFile(canonicalPath, listener);
+			if (refreshInFlight) await refreshInFlight.catch(() => undefined);
+		},
+		get revision() {
+			return lastRevision;
+		},
+		get error() {
+			return lastError;
+		},
+		get generation() {
+			return generation;
+		},
+	});
+}

package/shared/studio-resource-grants.js

@@ -0,0 +1,157 @@
+import { realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+
+export const STUDIO_RESOURCE_GRANT_MAX_ENTRIES = 128;
+
+function expandHome(pathInput) {
+	const value = String(pathInput || "").trim();
+	if (value === "~") return homedir();
+	if (value.startsWith("~/") || value.startsWith("~\\")) return resolve(homedir(), value.slice(2));
+	return value;
+}
+
+function resolveGrantInput(pathInput, fallbackCwd) {
+	const raw = expandHome(pathInput);
+	if (!raw) throw new Error("Missing Studio resource grant path.");
+	if (/\0/.test(raw)) throw new Error("Invalid Studio resource grant path.");
+	if (/^[a-z][a-z0-9+.-]*:/i.test(raw) && !/^[a-z]:[\\/]/i.test(raw)) {
+		throw new Error("Studio resource grants require a local path.");
+	}
+	return isAbsolute(raw) ? raw : resolve(fallbackCwd, raw);
+}
+
+function canonicalExistingPath(pathInput, fallbackCwd, expectedKind) {
+	const resolvedPath = resolveGrantInput(pathInput, fallbackCwd);
+	const canonicalPath = realpathSync(resolvedPath);
+	const stats = statSync(canonicalPath);
+	if (expectedKind === "directory" && !stats.isDirectory()) {
+		throw new Error("Studio resource directory grant does not refer to a directory.");
+	}
+	if (expectedKind === "file" && !stats.isFile()) {
+		throw new Error("Studio resource file grant does not refer to a file.");
+	}
+	if (!stats.isDirectory() && !stats.isFile()) {
+		throw new Error("Studio resource grant path must refer to a file or directory.");
+	}
+	return { canonicalPath, resolvedPath, kind: stats.isDirectory() ? "directory" : "file" };
+}
+
+function isPathInsideOrEqualDirectory(candidatePath, directoryPath) {
+	const rel = relative(directoryPath, candidatePath);
+	return rel === "" || (!isAbsolute(rel) && rel !== ".." && !rel.startsWith(`..${sep}`));
+}
+
+function normalizeGrantSource(source, fallback) {
+	const value = String(source || "").trim();
+	return (value || fallback).slice(0, 100);
+}
+
+function copyGrant(entry) {
+	return Object.freeze({
+		kind: entry.kind,
+		path: entry.path,
+		sources: Object.freeze(Array.from(entry.sources)),
+		grantedAt: entry.grantedAt,
+	});
+}
+
+export function createStudioResourceGrantRegistry(options = {}) {
+	const requestedMaxEntries = Number(options.maxEntries);
+	const maxEntries = Math.max(1, Math.min(
+		STUDIO_RESOURCE_GRANT_MAX_ENTRIES,
+		Number.isFinite(requestedMaxEntries) && requestedMaxEntries > 0
+			? Math.floor(requestedMaxEntries)
+			: STUDIO_RESOURCE_GRANT_MAX_ENTRIES,
+	));
+	const now = typeof options.now === "function" ? options.now : Date.now;
+	const defaultCwd = typeof options.cwd === "string" && options.cwd.trim() ? options.cwd : process.cwd();
+	const entries = new Map();
+
+	function fallbackCwd(details) {
+		return typeof details?.cwd === "string" && details.cwd.trim() ? details.cwd : defaultCwd;
+	}
+
+	function addGrant(kind, canonicalPath, source) {
+		const key = `${kind}:${canonicalPath}`;
+		const existing = entries.get(key);
+		if (existing) {
+			existing.sources.add(source);
+			return copyGrant(existing);
+		}
+		if (entries.size >= maxEntries) {
+			throw new Error(`Studio resource grant limit reached (${maxEntries}).`);
+		}
+		const entry = {
+			kind,
+			path: canonicalPath,
+			sources: new Set([source]),
+			grantedAt: Math.max(0, Number(now()) || 0),
+		};
+		entries.set(key, entry);
+		return copyGrant(entry);
+	}
+
+	function grantDirectory(pathInput, details = {}) {
+		const resolved = canonicalExistingPath(pathInput, fallbackCwd(details), "directory");
+		return addGrant("directory", resolved.canonicalPath, normalizeGrantSource(details.source, "explicit-directory"));
+	}
+
+	function grantFile(pathInput, details = {}) {
+		const resolved = canonicalExistingPath(pathInput, fallbackCwd(details), "file");
+		return addGrant("file", resolved.canonicalPath, normalizeGrantSource(details.source, "explicit-file"));
+	}
+
+	function grantDocument(pathInput, details = {}) {
+		const cwd = fallbackCwd(details);
+		const document = canonicalExistingPath(pathInput, cwd, "file");
+		const documentDirectory = dirname(resolveGrantInput(pathInput, cwd));
+		const directoryGrant = grantDirectory(documentDirectory, {
+			cwd,
+			source: normalizeGrantSource(details.source, "document"),
+		});
+		if (!isPathInsideOrEqualDirectory(document.canonicalPath, directoryGrant.path)) {
+			grantFile(document.canonicalPath, { cwd, source: "document-file" });
+		}
+		return directoryGrant;
+	}
+
+	function findGrant(pathInput, details = {}) {
+		let candidate;
+		try {
+			candidate = canonicalExistingPath(pathInput, fallbackCwd(details));
+		} catch {
+			return null;
+		}
+		const exactFile = entries.get(`file:${candidate.canonicalPath}`);
+		if (exactFile) return copyGrant(exactFile);
+
+		let bestDirectory = null;
+		for (const entry of entries.values()) {
+			if (entry.kind !== "directory" || !isPathInsideOrEqualDirectory(candidate.canonicalPath, entry.path)) continue;
+			if (!bestDirectory || entry.path.length > bestDirectory.path.length) bestDirectory = entry;
+		}
+		return bestDirectory ? copyGrant(bestDirectory) : null;
+	}
+
+	return Object.freeze({
+		grantDirectory,
+		grantFile,
+		grantDocument,
+		findGrant,
+		allows(pathInput, details = {}) {
+			return findGrant(pathInput, details) !== null;
+		},
+		snapshot() {
+			return Array.from(entries.values())
+				.sort((a, b) => a.path.localeCompare(b.path) || a.kind.localeCompare(b.kind))
+				.map(copyGrant);
+		},
+		clear() {
+			entries.clear();
+		},
+		get size() {
+			return entries.size;
+		},
+	});
+}

package/shared/studio-side-question-context.js

@@ -1,4 +1,4 @@
-import { readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { lstatSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 
 export const STUDIO_SIDE_CONTEXT_MAX_FILE_BYTES = 5_000_000;
@@ -53,8 +53,21 @@ export function resolveStudioSideQuestionRoot(pathInput, fallbackCwd) {
 	return stats.isDirectory() ? real : dirname(real);
 }
 
+export function assertStudioSideQuestionRootStable(rootPath) {
+	const requested = resolve(String(rootPath || ""));
+	if (lstatSync(requested).isSymbolicLink()) {
+		throw new Error("The selected side-question context root changed or now resolves to another folder.");
+	}
+	const currentReal = realpathSync(requested);
+	if (currentReal !== requested) {
+		throw new Error("The selected side-question context root changed or now resolves to another folder.");
+	}
+	if (!statSync(currentReal).isDirectory()) throw new Error("The selected side-question context root is no longer a folder.");
+	return currentReal;
+}
+
 export function resolveStudioSideQuestionPath(rootPath, pathInput, options = {}) {
-	const rootReal = realpathSync(rootPath);
+	const rootReal = assertStudioSideQuestionRootStable(rootPath);
 	const raw = String(pathInput || "").trim().replace(/^@/, "");
 	if (!raw || /^[a-z][a-z0-9+.-]*:\/\//i.test(raw)) throw new Error("Use a local path inside the selected context root.");
 	const candidate = isAbsolute(raw) ? raw : resolve(rootReal, raw);
@@ -76,7 +89,7 @@ function classifyContextPath(filePath) {
 }
 
 export function listStudioSideQuestionContext(rootPath, options = {}) {
-	const root = realpathSync(rootPath);
+	const root = assertStudioSideQuestionRootStable(rootPath);
 	const maxFiles = Math.max(1, Math.min(1_000, Math.floor(Number(options.maxFiles) || 400)));
 	const maxDirs = Math.max(1, Math.min(1_000, Math.floor(Number(options.maxDirs) || 500)));
 	const maxDepth = Math.max(0, Math.min(12, Math.floor(Number(options.maxDepth) || 8)));
@@ -177,7 +190,7 @@ export function sliceStudioSideQuestionExtractedText(text, options = {}) {
 
 export function searchStudioSideQuestionContext(rootPath, queryInput, options = {}) {
 	if (options.signal?.aborted) throw new Error("Local context search was cancelled.");
-	const root = realpathSync(rootPath);
+	const root = assertStudioSideQuestionRootStable(rootPath);
 	const query = String(queryInput || "").trim();
 	if (!query) throw new Error("Search query is empty.");
 	if (query.length > 500) throw new Error("Search query is too long.");

package/shared/studio-workspace-state.js

@@ -20,6 +20,9 @@ export function normalizeStudioWorkspaceRecoveryState(value) {
 	if (!value || typeof value !== "object" || value.version !== 1 || typeof value.text !== "string") return null;
 	if (value.text.length > STUDIO_WORKSPACE_STATE_MAX_TEXT_CHARS) return null;
 	const sourceState = value.sourceState && typeof value.sourceState === "object" ? value.sourceState : {};
+	const diskRevision = typeof value.diskRevision === "string" && /^sha256:[a-f0-9]{64}$/i.test(value.diskRevision.trim())
+		? value.diskRevision.trim().toLowerCase()
+		: null;
 	return {
 		version: 1,
 		savedAt: Math.max(0, finiteNumber(value.savedAt)),
@@ -29,6 +32,7 @@ export function normalizeStudioWorkspaceRecoveryState(value) {
 			path: boundedString(sourceState.path, 16_384) || null,
 			draftId: boundedString(sourceState.draftId, 256) || null,
 		},
+		diskRevision,
 		resourceDir: boundedString(value.resourceDir, 16_384),
 		editorView: boundedString(value.editorView, 100),
 		rightView: boundedString(value.rightView, 100),