@indigoai-us/hq-cli 5.345.147 → 5.345.148

package/dist/lib/doctor/temp-home-sweeper.js

@@ -0,0 +1,418 @@
+/**
+ * Sweeper for abandoned throwaway `$HOME` folders.
+ *
+ * Commands run as `HOME=$(mktemp -d) <cmd>` leave a `tmp.XXXXXXXX` folder in
+ * the temp dir. When the command touched Rust or pnpm tooling, that folder
+ * holds a full `.rustup` / `.cargo` download (1-2 GB) and nothing deletes it.
+ * On 2026-10-18 about 45 GB refilled within hours of a cleanup this way.
+ * `core/scripts/with-temp-home.sh` makes `hq-temp-home.XXXXXXXX` folders and
+ * removes them on exit, but a wrapper killed with SIGKILL leaves its folder.
+ *
+ * The sweep is deliberately narrow. A folder is removed only when ALL hold:
+ *
+ * - it is a direct child of a temp root (TMPDIR, os.tmpdir(), /tmp,
+ *   /private/tmp, /var/folders/{a}/{b}/T) and its name starts with `tmp.` or
+ *   `hq-temp-home.`;
+ * - `lstat` says it is a real directory (never a symlink) owned by this user;
+ * - a `tmp.*` folder holds a `.rustup` or `.cargo` directory (again by
+ *   `lstat`). An `hq-temp-home.*` folder needs no marker: the name shows the
+ *   wrapper made it;
+ * - nothing inside it, the folder itself included, was modified in the last
+ *   90 minutes;
+ * - no live process uses it: the wrapper's `.hq-temp-home.lock` does not name
+ *   a live pid, and no process of this user has its cwd or an open file
+ *   there (on Linux, or its `HOME` there either).
+ *
+ * The walk uses `lstat` throughout and never descends into a symlink, so a
+ * link inside a temp home that points elsewhere is neither measured nor
+ * followed. `fs.rmSync` unlinks symlinks rather than following them. A folder
+ * that cannot be fully read is kept, because an incomplete scan cannot prove
+ * the folder is idle. When the in-use probe fails, every candidate is kept.
+ *
+ * `shallow` mode is for plain `hq doctor`, which must stay fast. It checks
+ * only the folder and its direct children for recent changes, skips the size
+ * walk and the process probe, and reports no byte counts.
+ */
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+/** Folders younger than this (by newest mtime anywhere inside) are kept. */
+export const TEMP_HOME_MIN_IDLE_MS = 90 * 60 * 1000;
+/** Names that mark a `tmp.*` temp home as holding a toolchain download. */
+export const TEMP_HOME_TOOLCHAIN_MARKERS = [".rustup", ".cargo"];
+/** Folders made by `HOME=$(mktemp -d)`; swept only with a toolchain marker. */
+export const TEMP_HOME_MKTEMP_PREFIX = "tmp.";
+/** Folders made by `core/scripts/with-temp-home.sh`. */
+export const TEMP_HOME_WRAPPER_PREFIX = "hq-temp-home.";
+/** Lock file the wrapper writes into its temp home; holds the wrapper pid. */
+export const TEMP_HOME_LOCK_FILE = ".hq-temp-home.lock";
+const BYTES_PER_GB = 1_000_000_000;
+const nodeFs = {
+    lstatSync: (target) => fs.lstatSync(target),
+    readdirSync: (target) => fs.readdirSync(target),
+    realpathSync: (target) => fs.realpathSync(target),
+    readFileSync: (target, encoding) => fs.readFileSync(target, encoding),
+    rmSync: (target, options) => fs.rmSync(target, options),
+};
+/**
+ * The temp roots a throwaway home can land in: `$TMPDIR`, `os.tmpdir()`,
+ * `/tmp`, `/private/tmp`, and every per-user macOS temp dir
+ * `/var/folders/{a}/{b}/T`. Missing roots are dropped later by the sweep.
+ */
+export function defaultTempRoots(env = process.env, fsImpl = nodeFs) {
+    const roots = [];
+    if (env.TMPDIR)
+        roots.push(env.TMPDIR);
+    roots.push(os.tmpdir(), "/tmp", "/private/tmp");
+    for (const a of safeReaddir(fsImpl, "/var/folders")) {
+        for (const b of safeReaddir(fsImpl, path.join("/var/folders", a))) {
+            roots.push(path.join("/var/folders", a, b, "T"));
+        }
+    }
+    return roots;
+}
+function safeReaddir(fsImpl, target) {
+    try {
+        return fsImpl.readdirSync(target);
+    }
+    catch {
+        return [];
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** `process.kill(pid, 0)`: alive unless the pid does not exist (ESRCH). */
+export function defaultIsPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+/**
+ * True when `value` (a cwd or open-file path, or `HOME`) is `home` or a path
+ * inside it. Matched by folder name as a path segment, because the same temp
+ * dir is reachable as `/var/folders/...` and `/private/var/folders/...`; the
+ * random `mktemp` suffix makes the name unique. Over-matching only keeps more.
+ */
+export function pathUsesHome(value, home) {
+    const name = path.basename(home);
+    if (value === name)
+        return true;
+    const marker = `/${name}`;
+    let index = value.indexOf(marker);
+    while (index !== -1) {
+        const next = value[index + marker.length];
+        if (next === undefined || next === "/")
+            return true;
+        index = value.indexOf(marker, index + 1);
+    }
+    return false;
+}
+function runProbe(command, args) {
+    const result = spawnSync(command, args, { encoding: "utf8", maxBuffer: 256 * 1024 * 1024 });
+    if (result.error)
+        throw result.error;
+    if (result.status !== 0 && !result.stdout) {
+        throw new Error(`${command} exited ${result.status ?? result.signal}`);
+    }
+    return result.stdout;
+}
+/**
+ * Default in-use probe. Only processes of `uid` are checked; other users
+ * cannot own these folders' contents in a way the sweep would delete.
+ *
+ * - Linux: `/proc/{pid}/cwd`, every `/proc/{pid}/fd/*` link, and `HOME` from
+ *   `/proc/{pid}/environ`. Environment values are matched in memory and never
+ *   logged.
+ * - macOS: `lsof -u uid` for every file each process has open, its cwd and
+ *   its executable included. macOS does not show other processes'
+ *   environments (`ps -E` leaves them out), so `HOME` itself is not checked
+ *   there. A process that has HOME set to a temp home but holds nothing open
+ *   inside it is not seen; the wrapper lock and the 90-minute idle check
+ *   cover that case.
+ */
+export function defaultInUseProbe(uid) {
+    return (homes) => {
+        const used = new Set();
+        if (homes.length === 0)
+            return used;
+        const values = [];
+        if (process.platform === "linux") {
+            for (const pid of fs.readdirSync("/proc").filter((name) => /^\d+$/.test(name))) {
+                try {
+                    if (uid !== undefined && fs.statSync(`/proc/${pid}`).uid !== uid)
+                        continue;
+                }
+                catch {
+                    continue;
+                }
+                try {
+                    values.push(fs.readlinkSync(`/proc/${pid}/cwd`));
+                }
+                catch {
+                    // The process exited or the link is unreadable.
+                }
+                try {
+                    for (const fd of fs.readdirSync(`/proc/${pid}/fd`)) {
+                        try {
+                            values.push(fs.readlinkSync(`/proc/${pid}/fd/${fd}`));
+                        }
+                        catch {
+                            // The descriptor closed.
+                        }
+                    }
+                }
+                catch {
+                    // Same.
+                }
+                try {
+                    for (const entry of fs.readFileSync(`/proc/${pid}/environ`, "utf8").split("\0")) {
+                        if (entry.startsWith("HOME="))
+                            values.push(entry.slice(5));
+                    }
+                }
+                catch {
+                    // Same.
+                }
+            }
+        }
+        else {
+            const userArgs = uid !== undefined ? ["-u", String(uid)] : [];
+            // -w: no warnings; -n and -P: no host or port name lookups.
+            const lsof = runProbe("lsof", ["-w", "-n", "-P", "-Fn", ...userArgs]);
+            for (const line of lsof.split("\n")) {
+                if (line.startsWith("n"))
+                    values.push(line.slice(1));
+            }
+        }
+        for (const home of homes) {
+            if (values.some((value) => pathUsesHome(value, home)))
+                used.add(home);
+        }
+        return used;
+    };
+}
+/** On-disk size of one lstat result: allocated blocks when known, else size. */
+function diskBytes(stat) {
+    return typeof stat.blocks === "number" && stat.blocks >= 0 ? stat.blocks * 512 : stat.size;
+}
+/**
+ * Measure a folder with `lstat`, never descending into symlinks. Stops as soon
+ * as it sees an entry modified after `cutoffMs`, since such a folder is kept
+ * and its size is not needed. With `maxDepth` 1 it reads only direct children.
+ */
+function walk(fsImpl, dir, dirStat, cutoffMs, maxDepth = Number.POSITIVE_INFINITY) {
+    if (dirStat.mtimeMs > cutoffMs)
+        return { complete: true, recent: true, bytes: 0 };
+    let bytes = diskBytes(dirStat);
+    const stack = [{ dir, depth: 0 }];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        let names;
+        try {
+            names = fsImpl.readdirSync(current.dir);
+        }
+        catch {
+            return { complete: false, recent: false, bytes };
+        }
+        for (const name of names) {
+            const child = path.join(current.dir, name);
+            let stat;
+            try {
+                stat = fsImpl.lstatSync(child);
+            }
+            catch {
+                return { complete: false, recent: false, bytes };
+            }
+            if (stat.mtimeMs > cutoffMs)
+                return { complete: true, recent: true, bytes };
+            bytes += diskBytes(stat);
+            if (stat.isDirectory() && !stat.isSymbolicLink() && current.depth + 1 < maxDepth) {
+                stack.push({ dir: child, depth: current.depth + 1 });
+            }
+        }
+    }
+    return { complete: true, recent: false, bytes };
+}
+function hasToolchainMarker(fsImpl, dir) {
+    return TEMP_HOME_TOOLCHAIN_MARKERS.some((marker) => {
+        try {
+            const stat = fsImpl.lstatSync(path.join(dir, marker));
+            return stat.isDirectory() && !stat.isSymbolicLink();
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** True when the wrapper's lock file in `dir` names a live pid. */
+function lockHeldByLiveProcess(fsImpl, dir, isPidAlive) {
+    let text;
+    try {
+        const lock = path.join(dir, TEMP_HOME_LOCK_FILE);
+        if (!fsImpl.lstatSync(lock).isFile())
+            return false;
+        text = fsImpl.readFileSync(lock, "utf8");
+    }
+    catch {
+        return false;
+    }
+    const pid = Number.parseInt(text.trim(), 10);
+    return Number.isInteger(pid) && pid > 0 && isPidAlive(pid);
+}
+function resolveRoots(fsImpl, roots) {
+    const seen = new Set();
+    const resolved = [];
+    for (const root of roots) {
+        let real;
+        try {
+            real = fsImpl.realpathSync(root);
+            if (!fsImpl.lstatSync(real).isDirectory())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        if (seen.has(real))
+            continue;
+        seen.add(real);
+        resolved.push(real);
+    }
+    return resolved;
+}
+/**
+ * Find and (unless `dryRun`) remove idle, unused temp homes. See the module
+ * comment for the exact rules.
+ */
+export function sweepTempHomes(options = {}) {
+    const fsImpl = options.fs ?? nodeFs;
+    const shallow = options.shallow === true;
+    const dryRun = shallow || options.dryRun === true;
+    const nowMs = options.nowMs ?? Date.now();
+    const cutoffMs = nowMs - (options.minIdleMs ?? TEMP_HOME_MIN_IDLE_MS);
+    const uid = options.uid ?? (typeof process.getuid === "function" ? process.getuid() : undefined);
+    const isPidAlive = options.isPidAlive ?? defaultIsPidAlive;
+    const roots = resolveRoots(fsImpl, options.roots ?? defaultTempRoots());
+    // Pass 1: decide per folder from the file system alone.
+    const entries = [];
+    const candidates = [];
+    for (const root of roots) {
+        const names = safeReaddir(fsImpl, root)
+            .filter((name) => name.startsWith(TEMP_HOME_MKTEMP_PREFIX) || name.startsWith(TEMP_HOME_WRAPPER_PREFIX))
+            .sort();
+        for (const name of names) {
+            const candidate = path.join(root, name);
+            let stat;
+            try {
+                stat = fsImpl.lstatSync(candidate);
+            }
+            catch (error) {
+                entries.push({ path: candidate, action: "kept", reason: "unreadable", error: errorMessage(error) });
+                continue;
+            }
+            if (stat.isSymbolicLink()) {
+                entries.push({ path: candidate, action: "kept", reason: "symlink" });
+                continue;
+            }
+            if (!stat.isDirectory()) {
+                entries.push({ path: candidate, action: "kept", reason: "not-directory" });
+                continue;
+            }
+            if (uid !== undefined && stat.uid !== uid) {
+                entries.push({ path: candidate, action: "kept", reason: "not-owned" });
+                continue;
+            }
+            if (name.startsWith(TEMP_HOME_MKTEMP_PREFIX) && !hasToolchainMarker(fsImpl, candidate)) {
+                entries.push({ path: candidate, action: "kept", reason: "no-toolchain-marker" });
+                continue;
+            }
+            const measured = walk(fsImpl, candidate, stat, cutoffMs, shallow ? 1 : undefined);
+            if (measured.recent) {
+                entries.push({ path: candidate, action: "kept", reason: "recent" });
+                continue;
+            }
+            if (!measured.complete) {
+                entries.push({ path: candidate, action: "kept", reason: "unreadable" });
+                continue;
+            }
+            if (lockHeldByLiveProcess(fsImpl, candidate, isPidAlive)) {
+                entries.push({ path: candidate, action: "kept", reason: "in-use" });
+                continue;
+            }
+            candidates.push({ path: candidate, stat, bytes: shallow ? undefined : measured.bytes });
+        }
+    }
+    // Pass 2: one process probe for every remaining candidate. Shallow mode
+    // only reports, so it skips the probe; the full sweep runs it.
+    let inUse = new Set();
+    if (!shallow && candidates.length > 0) {
+        const probe = options.inUse ?? defaultInUseProbe(uid);
+        try {
+            inUse = probe(candidates.map((candidate) => candidate.path));
+        }
+        catch (error) {
+            const message = errorMessage(error);
+            for (const candidate of candidates) {
+                entries.push({ path: candidate.path, action: "kept", reason: "in-use-unknown", error: message });
+            }
+            return finish(entries, roots, dryRun, shallow);
+        }
+    }
+    // Pass 3: remove, or report what would be removed.
+    for (const candidate of candidates) {
+        if (inUse.has(candidate.path)) {
+            entries.push({ path: candidate.path, action: "kept", reason: "in-use" });
+            continue;
+        }
+        if (dryRun) {
+            entries.push(withBytes({ path: candidate.path, action: "would-remove" }, candidate.bytes));
+            continue;
+        }
+        // Re-check right before deleting: the path must still be the same real
+        // directory, untouched since it was measured, and not newly locked.
+        let again;
+        try {
+            again = fsImpl.lstatSync(candidate.path);
+        }
+        catch (error) {
+            entries.push({ path: candidate.path, action: "kept", reason: "changed-before-delete", error: errorMessage(error) });
+            continue;
+        }
+        if (again.isSymbolicLink() ||
+            !again.isDirectory() ||
+            again.ino !== candidate.stat.ino ||
+            again.dev !== candidate.stat.dev ||
+            again.mtimeMs > cutoffMs ||
+            lockHeldByLiveProcess(fsImpl, candidate.path, isPidAlive)) {
+            entries.push({ path: candidate.path, action: "kept", reason: "changed-before-delete" });
+            continue;
+        }
+        try {
+            fsImpl.rmSync(candidate.path, { recursive: true, force: false });
+            entries.push(withBytes({ path: candidate.path, action: "removed" }, candidate.bytes));
+        }
+        catch (error) {
+            entries.push(withBytes({ path: candidate.path, action: "failed", error: errorMessage(error) }, candidate.bytes));
+        }
+    }
+    return finish(entries, roots, dryRun, shallow);
+}
+function withBytes(entry, bytes) {
+    return bytes === undefined ? entry : { ...entry, bytes };
+}
+function finish(entries, roots, dryRun, shallow) {
+    const bytesFreed = entries
+        .filter((entry) => entry.action === "removed" || entry.action === "would-remove")
+        .reduce((sum, entry) => sum + (entry.bytes ?? 0), 0);
+    return { dryRun, shallow, roots, entries, bytesFreed, gbFreed: toGb(bytesFreed) };
+}
+/** Bytes to GB (10^9 bytes), rounded to two decimals. */
+export function toGb(bytes) {
+    return Math.round((bytes / BYTES_PER_GB) * 100) / 100;
+}
+//# sourceMappingURL=temp-home-sweeper.js.map