@herbertgao/pi-extensions 2026.9.0 → 2026.9.2

package/node_modules/pi-web-access/github-extract.ts

@@ -1,4 +1,5 @@
-import { chmodSync, closeSync, existsSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, realpathSync, rmSync, statSync, unlinkSync } from "node:fs";
+import { chmodSync, closeSync, constants as fsConstants, existsSync, fstatSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, realpathSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { lstat as lstatAsync, open as openAsync, opendir as opendirAsync, readFile as readFileAsync, realpath as realpathAsync, rm as rmAsync, type FileHandle } from "node:fs/promises";
 import { execFile, spawn, type ChildProcess } from "node:child_process";
 import { createHash } from "node:crypto";
 import { basename, dirname, extname, join, resolve as resolvePath, sep as pathSep } from "node:path";
@@ -29,6 +30,9 @@ const NOISE_DIRS = new Set([
 
 const MAX_INLINE_FILE_CHARS = 100_000;
 const MAX_TREE_ENTRIES = 200;
+const CLONE_RUNTIME_OWNER_FILENAME = ".owner.json";
+const CLONE_RUNTIME_OWNER_VERSION = 1;
+const MAX_CLONE_RUNTIME_OWNER_BYTES = 1024;
 
 export interface GitHubUrlInfo {
 	owner: string;
@@ -49,6 +53,14 @@ interface CloneDestination {
 	localPath: string;
 }
 
+interface CloneRuntimeOwner {
+	version: 1;
+	pid: number;
+	platform: string;
+	bootId?: string;
+	startTime?: string;
+}
+
 interface GitHubCloneConfig {
 	enabled: boolean;
 	maxRepoSizeMB: number;
@@ -57,6 +69,7 @@ interface GitHubCloneConfig {
 }
 
 const cloneCache = new Map<string, CachedClone>();
+const startedCloneRuntimeCleanups = new Set<string>();
 
 let cachedConfig: GitHubCloneConfig | null = null;
 let cloneRuntime: { parentPath: string; rootPath: string } | null = null;
@@ -190,6 +203,232 @@ function cacheKey(owner: string, repo: string, ref?: string): string {
 	return ref ? `${owner}/${repo}@${ref}` : `${owner}/${repo}`;
 }
 
+function readLinuxBootId(): string | null {
+	try {
+		const bootId = readFileSync("/proc/sys/kernel/random/boot_id", "utf-8").trim();
+		return bootId.length > 0 ? bootId : null;
+	} catch {
+		return null;
+	}
+}
+
+async function readLinuxBootIdAsync(): Promise<string | null> {
+	try {
+		const bootId = (await readFileAsync("/proc/sys/kernel/random/boot_id", "utf-8")).trim();
+		return bootId.length > 0 ? bootId : null;
+	} catch {
+		return null;
+	}
+}
+
+interface LinuxProcessInfo {
+	state: string;
+	startTime: string | null;
+	dead: boolean;
+}
+
+function parseLinuxProcessInfo(stat: string): LinuxProcessInfo | null {
+	const closingParen = stat.lastIndexOf(") ");
+	if (closingParen < 0) return null;
+	const fields = stat.slice(closingParen + 2).trim().split(/\s+/);
+	const state = fields[0];
+	const startTime = fields[19];
+	if (!state || !startTime || !/^\d+$/.test(startTime)) return null;
+	return { state, startTime, dead: false };
+}
+
+function readLinuxProcessInfo(pid: number): LinuxProcessInfo | null {
+	try {
+		return parseLinuxProcessInfo(readFileSync(`/proc/${pid}/stat`, "utf-8"));
+	} catch (err) {
+		if (err && typeof err === "object" && "code" in err && err.code === "ENOENT") {
+			return { state: "", startTime: null, dead: true };
+		}
+		return null;
+	}
+}
+
+async function readLinuxProcessInfoAsync(pid: number): Promise<LinuxProcessInfo | null> {
+	try {
+		return parseLinuxProcessInfo(await readFileAsync(`/proc/${pid}/stat`, "utf-8"));
+	} catch (err) {
+		if (err && typeof err === "object" && "code" in err && err.code === "ENOENT") {
+			return { state: "", startTime: null, dead: true };
+		}
+		return null;
+	}
+}
+
+function currentCloneRuntimeOwner(): CloneRuntimeOwner {
+	const owner: CloneRuntimeOwner = {
+		version: CLONE_RUNTIME_OWNER_VERSION,
+		pid: process.pid,
+		platform: process.platform,
+	};
+
+	if (process.platform === "linux") {
+		const bootId = readLinuxBootId();
+		const processInfo = readLinuxProcessInfo(process.pid);
+		if (bootId && processInfo?.startTime) {
+			owner.bootId = bootId;
+			owner.startTime = processInfo.startTime;
+		}
+	}
+
+	return owner;
+}
+
+function writeCloneRuntimeOwner(runtimePath: string): void {
+	const ownerPath = join(runtimePath, CLONE_RUNTIME_OWNER_FILENAME);
+	writeFileSync(ownerPath, JSON.stringify(currentCloneRuntimeOwner()), {
+		encoding: "utf-8",
+		flag: "wx",
+		mode: 0o600,
+	});
+}
+
+function parseCloneRuntimeOwner(text: string): CloneRuntimeOwner | null {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(text);
+	} catch {
+		return null;
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+
+	const record = parsed as Record<string, unknown>;
+	if (
+		record.version !== CLONE_RUNTIME_OWNER_VERSION ||
+		typeof record.pid !== "number" ||
+		!Number.isSafeInteger(record.pid) ||
+		record.pid <= 0 ||
+		typeof record.platform !== "string" ||
+		record.platform.length === 0 ||
+		record.platform.length > 32
+	) {
+		return null;
+	}
+
+	const owner: CloneRuntimeOwner = {
+		version: CLONE_RUNTIME_OWNER_VERSION,
+		pid: record.pid,
+		platform: record.platform,
+	};
+	if (record.bootId !== undefined) {
+		if (typeof record.bootId !== "string" || record.bootId.length === 0 || record.bootId.length > 256) return null;
+		owner.bootId = record.bootId;
+	}
+	if (record.startTime !== undefined) {
+		if (typeof record.startTime !== "string" || !/^\d+$/.test(record.startTime)) return null;
+		owner.startTime = record.startTime;
+	}
+	return owner;
+}
+
+async function readCloneRuntimeOwner(runtimePath: string): Promise<CloneRuntimeOwner | null> {
+	const ownerPath = join(runtimePath, CLONE_RUNTIME_OWNER_FILENAME);
+	let file: FileHandle | undefined;
+	try {
+		const entry = await lstatAsync(ownerPath);
+		if (!entry.isFile() || entry.size > MAX_CLONE_RUNTIME_OWNER_BYTES) return null;
+		const noFollow = fsConstants.O_NOFOLLOW ?? 0;
+		file = await openAsync(ownerPath, fsConstants.O_RDONLY | noFollow);
+		const opened = await file.stat();
+		if (!opened.isFile() || opened.size > MAX_CLONE_RUNTIME_OWNER_BYTES) return null;
+		return parseCloneRuntimeOwner(await file.readFile("utf-8"));
+	} catch {
+		return null;
+	} finally {
+		if (file !== undefined) {
+			try {
+				await file.close();
+			} catch {
+				// The handle may already have been closed externally.
+			}
+		}
+	}
+}
+
+function processNonexistenceProven(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return false;
+	} catch (err) {
+		return Boolean(err && typeof err === "object" && "code" in err && err.code === "ESRCH");
+	}
+}
+
+async function cloneRuntimeOwnerIsDead(owner: CloneRuntimeOwner, bootId: string | null): Promise<boolean> {
+	if (owner.platform !== process.platform) return false;
+
+	if (process.platform !== "linux") {
+		return processNonexistenceProven(owner.pid);
+	}
+
+	// Linux PID values can be reused. Require both boot ID and proc start time
+	// before treating a runtime as owned, and preserve it when either check is
+	// unavailable.
+	if (!owner.bootId || !owner.startTime || !bootId) return false;
+	const processInfo = await readLinuxProcessInfoAsync(owner.pid);
+	if (!processInfo) return false;
+	if (processInfo.dead || processInfo.state === "Z" || processInfo.state === "X") return true;
+	return processInfo.startTime !== owner.startTime || bootId !== owner.bootId;
+}
+
+async function removeCloneRuntimeAsync(parentPath: string, runtimePath: string): Promise<void> {
+	const normalizedParentPath = resolvePath(parentPath);
+	const normalizedRuntimePath = resolvePath(runtimePath);
+	if (dirname(normalizedRuntimePath) !== normalizedParentPath || !basename(normalizedRuntimePath).startsWith("runtime-")) return;
+
+	try {
+		const realRuntimePath = await realpathAsync(normalizedRuntimePath);
+		if (dirname(realRuntimePath) !== normalizedParentPath || basename(realRuntimePath) !== basename(normalizedRuntimePath)) return;
+		const entry = await lstatAsync(normalizedRuntimePath);
+		if (entry.isSymbolicLink() || !entry.isDirectory()) return;
+		await rmAsync(normalizedRuntimePath, { recursive: true, force: true });
+	} catch {
+		// The runtime directory may already have been removed externally.
+	}
+}
+
+async function sweepStaleCloneRuntimes(parentPath: string): Promise<void> {
+	const normalizedParentPath = resolvePath(parentPath);
+	const bootId = process.platform === "linux" ? await readLinuxBootIdAsync() : null;
+	try {
+		const directory = await opendirAsync(normalizedParentPath);
+		for await (const entry of directory) {
+			if (!entry.name.startsWith("runtime-")) continue;
+			try {
+				if (!entry.isDirectory() || entry.isSymbolicLink()) continue;
+				const runtimePath = resolvePath(normalizedParentPath, entry.name);
+				if (dirname(runtimePath) !== normalizedParentPath) continue;
+				const runtimeEntry = await lstatAsync(runtimePath);
+				if (!runtimeEntry.isDirectory() || runtimeEntry.isSymbolicLink()) continue;
+				const realRuntimePath = await realpathAsync(runtimePath);
+				if (dirname(realRuntimePath) !== normalizedParentPath || basename(realRuntimePath) !== basename(runtimePath)) continue;
+				const owner = await readCloneRuntimeOwner(runtimePath);
+				if (!owner || !(await cloneRuntimeOwnerIsDead(owner, bootId))) continue;
+				await removeCloneRuntimeAsync(normalizedParentPath, runtimePath);
+			} catch {
+				// A changing or unreadable runtime must not stop the rest of the sweep.
+			}
+		}
+	} catch {
+		// Cleanup is opportunistic. A changing or unreadable cache must not stop
+		// GitHub extraction from falling back to the API.
+	}
+}
+
+function startStaleCloneRuntimeCleanup(parentPath: string): void {
+	const normalizedParentPath = resolvePath(parentPath);
+	if (startedCloneRuntimeCleanups.has(normalizedParentPath)) return;
+	startedCloneRuntimeCleanups.add(normalizedParentPath);
+	// Keep runtime creation synchronous and let the complete sweep run in the background.
+	void sweepStaleCloneRuntimes(normalizedParentPath).catch(() => {
+		// Cleanup is best effort and must never affect extraction.
+	});
+}
+
 function removeCloneRuntime(parentPath: string, runtimePath: string): void {
 	const normalizedParentPath = resolvePath(parentPath);
 	const normalizedRuntimePath = resolvePath(runtimePath);
@@ -213,6 +452,7 @@ function getCloneRuntimeRoot(config: GitHubCloneConfig): string | null {
 		const configuredPath = resolvePath(config.clonePath);
 		mkdirSync(configuredPath, { recursive: true });
 		parentPath = realpathSync(configuredPath);
+		startStaleCloneRuntimeCleanup(parentPath);
 		runtimePath = mkdtempSync(join(parentPath, "runtime-"));
 		chmodSync(runtimePath, 0o700);
 		const rootPath = realpathSync(runtimePath);
@@ -220,6 +460,7 @@ function getCloneRuntimeRoot(config: GitHubCloneConfig): string | null {
 			removeCloneRuntime(parentPath, runtimePath);
 			return null;
 		}
+		writeCloneRuntimeOwner(rootPath);
 		cloneRuntime = { parentPath, rootPath };
 		return rootPath;
 	} catch {