selfguard 0.0.0-stage → 0.1.0

package/dist/cli.js

@@ -0,0 +1,462 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { buildAlert, deliver } from "./alerts.js";
+import * as api from "./api.js";
+import { GUIDE } from "./guide.js";
+import { hookEnter, ZSH_HOOK } from "./hook.js";
+import { findProject } from "./lockfile/detect.js";
+import { runMcpServer } from "./mcp.js";
+import { paint, renderFindings, severityLabel, tildify, worstSeverity } from "./report.js";
+import { repoIdentity } from "./repoid.js";
+import { clean } from "./sanitize.js";
+import { parseInterval, scheduleOff, scheduleOn, scheduleStatus } from "./schedule.js";
+import { runSetup } from "./setup.js";
+import { findingKey, loadRepo } from "./store.js";
+import { isInteractive } from "./tui.js";
+import { VERSION } from "./version.js";
+const HELP = `selfguard ${VERSION} — keeps an eye on the dependencies of every repo you work on
+
+Setup:
+  selfguard setup                    interactive: choose the folders where your repos live
+  selfguard init zsh                 print the shell hook (eval "$(selfguard init zsh)" in ~/.zshrc)
+  selfguard schedule on [--every 6h] | off | status
+                                     periodic sync with macOS notifications (launchd)
+
+Projects:
+  selfguard status [--vulnerable] [--flat]
+                                     tracked repos, riskiest first (worktrees/clones grouped)
+  selfguard scan [dir] [-v]          scan a project now (exit 1 if vulnerable) and track it
+  selfguard report [dir] [-v]        last scan results, no network
+  selfguard sync                     find new repos in your folders + re-check everything
+  selfguard where <package>          which projects use <package>, which versions
+  selfguard vuln <id>                details of an advisory and which projects it affects
+
+Folders:
+  selfguard roots                    list watched folders and exclusions
+  selfguard roots add <dir> [--depth N] | remove <dir>
+  selfguard discover [--dry-run]     register new projects found in your folders
+  selfguard forget [dir] [--keep-discoverable]
+                                     stop tracking (and exclude) a project or folder
+  selfguard unexclude <dir>          allow an excluded path to be discovered again
+
+AI / automation:
+  --json                             any command: one JSON document on stdout
+  selfguard mcp                      MCP server over stdio (claude mcp add selfguard -- selfguard mcp)
+  selfguard guide                    usage guide for AI agents
+
+Data: OSV.dev (GitHub advisories, CVEs, malicious packages). Only package names and versions
+leave your machine. Nothing in your projects is executed. State: ~/.selfguard (SELFGUARD_HOME).
+Exit codes: 0 ok, 1 vulnerabilities found (scan/report), 2 error.`;
+const out = process.stdout;
+const err = process.stderr;
+const jsonMode = process.argv.includes("--json");
+const JSON_OPT = { json: { type: "boolean" } };
+class UsageError extends Error {
+}
+function emit(data) {
+    out.write(`${JSON.stringify(data, null, 2)}\n`);
+}
+function usage(message) {
+    throw new UsageError(message);
+}
+function notifyNew(outcomes) {
+    return deliver(buildAlert(outcomes
+        .filter((o) => o.newFindings.length > 0)
+        .map((o) => ({ path: o.record.path, newFindings: o.newFindings, repo: repoIdentity(o.record.path) }))));
+}
+/** Detached scan started by the shell hook: log + notify, never print to a terminal. */
+async function backgroundScan(path) {
+    const stamp = new Date().toISOString();
+    try {
+        const project = findProject(path);
+        const before = new Set((project ? loadRepo(project.root)?.findings ?? [] : []).map(findingKey));
+        const r = await api.scanPath(path);
+        const rec = loadRepo(r.project.path);
+        await notifyNew([{ record: rec, newFindings: rec.findings.filter((f) => !before.has(findingKey(f))), firstScan: r.firstScan }]);
+        out.write(`${stamp} scan ${r.project.path}: ${r.project.advisories} finding(s)${r.project.error ? ` (${r.project.error})` : ""}\n`);
+    }
+    catch (e) {
+        if (!(e instanceof api.ApiError && e.code === "busy"))
+            out.write(`${stamp} scan ${path}: ${e.message}\n`);
+    }
+    return 0;
+}
+async function cmdScan(args) {
+    const { values, positionals } = parseArgs({
+        args,
+        allowPositionals: true,
+        options: { ...JSON_OPT, background: { type: "boolean" }, verbose: { type: "boolean", short: "v" } },
+    });
+    const path = positionals[0] ?? ".";
+    if (values.background)
+        return backgroundScan(path);
+    const r = await api.scanPath(path);
+    if (values.json)
+        emit(r);
+    else
+        out.write(`${renderFindings(loadRepo(r.project.path), out, values.verbose ?? false)}\n`);
+    return r.project.advisories > 0 ? 1 : 0;
+}
+function cmdReport(args) {
+    const { values, positionals } = parseArgs({
+        args,
+        allowPositionals: true,
+        options: { ...JSON_OPT, verbose: { type: "boolean", short: "v" } },
+    });
+    const report = api.getReport(positionals[0] ?? ".");
+    if (values.json)
+        emit(report);
+    else
+        out.write(`${renderFindings(loadRepo(report.path), out, values.verbose ?? false)}\n`);
+    return report.advisories > 0 ? 1 : 0;
+}
+function cmdStatus(args) {
+    const { values } = parseArgs({ args, options: { ...JSON_OPT, vulnerable: { type: "boolean" }, flat: { type: "boolean" } } });
+    const status = api.getStatus({ onlyVulnerable: values.vulnerable ?? false });
+    if (values.json) {
+        emit(status);
+        return 0;
+    }
+    const c = paint(out);
+    if (status.projects.length === 0) {
+        out.write(`No projects tracked yet. Run ${c.bold("selfguard setup")}.\n`);
+        return 0;
+    }
+    const badge = (w, error) => w ? severityLabel(w, c) : error ? c.yellow("!") : c.green("✓");
+    if (values.flat) {
+        for (const p of status.projects) {
+            const counts = Object.entries(p.bySeverity).map(([s, n]) => `${n} ${s}`).join(", ");
+            const detail = p.advisories
+                ? `${p.vulnerablePackages} vulnerable pkg(s) ${c.dim(`(${counts})`)}`
+                : p.error
+                    ? c.dim(clean(p.error, 80))
+                    : c.dim(`${p.packages} packages, clean`);
+            out.write(`${badge(p.worstSeverity, p.error)} ${c.bold(tildify(p.path))}${p.exists ? "" : c.dim(" (missing)")}  ${detail}\n`);
+        }
+        return 0;
+    }
+    for (const g of status.repos) {
+        const many = g.checkouts.length > 1;
+        const firstError = g.checkouts.find((k) => k.error)?.error ?? null;
+        // Headline: the main checkout; mention a branch that is worse than it.
+        const main = g.checkouts.find((k) => !k.worktree) ?? g.checkouts[0];
+        const worse = g.checkouts
+            .filter((k) => k !== main && k.vulnerablePackages > main.vulnerablePackages)
+            .sort((a, b) => b.vulnerablePackages - a.vulnerablePackages)[0];
+        const mainText = main.vulnerablePackages
+            ? `${main.vulnerablePackages} vulnerable pkg(s)${many && main.branch ? ` on ${clean(main.branch, 40)}` : ""}`
+            : main.error && !many
+                ? c.dim(clean(main.error, 80))
+                : many && main.branch
+                    ? c.dim(`clean on ${clean(main.branch, 40)}`)
+                    : c.dim("clean");
+        const head = worse ? `${mainText} ${c.yellow(`· ${worse.vulnerablePackages} on ${clean(worse.branch ?? "another checkout", 40)}`)}` : mainText;
+        const where = many ? c.dim(`${g.checkouts.length} checkouts`) : c.dim(tildify(g.checkouts[0].path));
+        out.write(`${badge(g.worstSeverity, firstError)} ${c.bold(clean(g.label, 80))}  ${head}  ${where}\n`);
+        if (!many)
+            continue;
+        g.checkouts.forEach((k, i) => {
+            const branch = k.branch ? c.cyan(clean(k.branch, 50)) : c.dim("(no branch)");
+            const kind = k.worktree ? c.dim(" worktree") : "";
+            const detail = k.advisories ? `${k.vulnerablePackages} vulnerable` : k.error ? c.dim(clean(k.error, 60)) : c.dim("clean");
+            const tree = i === g.checkouts.length - 1 ? "└" : "├";
+            out.write(`   ${c.dim(tree)} ${branch}${kind}  ${detail}  ${c.dim(tildify(k.path))}${k.exists ? "" : c.dim(" (missing)")}\n`);
+        });
+    }
+    return 0;
+}
+async function cmdSync(args) {
+    const { values } = parseArgs({ args, options: { ...JSON_OPT, background: { type: "boolean" } } });
+    let r;
+    try {
+        r = await api.sync();
+    }
+    catch (e) {
+        if (values.background && e instanceof api.ApiError && e.code === "busy")
+            return 0;
+        throw e;
+    }
+    await notifyNew(r.outcomes);
+    const { outcomes: _o, ...data } = r;
+    const total = data.news.reduce((n, p) => n + p.packages.length, 0);
+    if (values.json)
+        emit(data);
+    else if (values.background) {
+        out.write(`${new Date().toISOString()} sync: ${data.projects} project(s), ${data.discovered.length} discovered, ${total} newly vulnerable package(s)\n`);
+    }
+    else {
+        const c = paint(out);
+        if (data.discovered.length)
+            out.write(`Discovered ${data.discovered.length} new project(s) in your folders.\n`);
+        if (data.pruned.length)
+            out.write(c.dim(`Stopped tracking ${data.pruned.length} folder(s) that no longer exist.\n`));
+        out.write(`Synced ${data.projects} project(s). ${total ? c.red(`${total} newly vulnerable package(s).`) : c.green("Nothing new.")}\n`);
+        for (const p of data.news) {
+            const pkgs = p.packages.map((g) => `${clean(g.name)}@${clean(g.version)} ${c.dim(`(${g.advisories.length})`)}`);
+            out.write(`  ${c.bold(tildify(p.path))}: ${pkgs.join(", ")}\n`);
+        }
+        for (const e of data.errors)
+            out.write(c.dim(`  ! ${tildify(e.path)}: ${clean(e.error)}\n`));
+    }
+    return 0;
+}
+async function cmdDiscover(args) {
+    const { values } = parseArgs({ args, options: { ...JSON_OPT, "dry-run": { type: "boolean" } } });
+    const r = await api.discoverNew({ dryRun: values["dry-run"] ?? false });
+    if (values.json) {
+        emit(r);
+        return 0;
+    }
+    const c = paint(out);
+    if (r.found.length === 0)
+        out.write("No new projects found.\n");
+    for (const p of r.found) {
+        const note = p.lockType ? c.dim(` (${p.lockType})`) : c.dim(" (no lockfile)");
+        out.write(`  ${c.green("+")} ${tildify(p.path)}${note}\n`);
+    }
+    if (r.dryRun && r.found.length)
+        out.write(`${r.found.length} new project(s) (dry run, nothing registered).\n`);
+    else if (r.registered)
+        out.write(`Registered ${r.registered} project(s); ${r.withVulnerabilities} with vulnerabilities. See: selfguard status\n`);
+    return 0;
+}
+function printRoots(r) {
+    const c = paint(out);
+    if (r.roots.length === 0)
+        out.write("No folders configured. Run: selfguard setup\n");
+    for (const root of r.roots)
+        out.write(`${tildify(root.path)}  ${c.dim(`depth ${root.depth}`)}\n`);
+    if (r.exclude.length) {
+        out.write(c.dim("excluded:\n"));
+        for (const e of r.exclude)
+            out.write(c.dim(`  ${tildify(e)}\n`));
+    }
+}
+function cmdRoots(args) {
+    const { values, positionals } = parseArgs({ args, allowPositionals: true, options: { ...JSON_OPT, depth: { type: "string" } } });
+    const [action, target] = positionals;
+    let r;
+    if (action === "add") {
+        if (!target)
+            usage("usage: selfguard roots add <dir> [--depth N]");
+        const depth = values.depth === undefined ? undefined : Number(values.depth);
+        if (depth !== undefined && !Number.isInteger(depth))
+            usage("--depth must be an integer");
+        r = api.addRoot(target, depth);
+    }
+    else if (action === "remove") {
+        if (!target)
+            usage("usage: selfguard roots remove <dir>");
+        r = api.removeRoot(target);
+    }
+    else if (action === undefined || action === "list") {
+        r = api.listRoots();
+    }
+    else {
+        usage("usage: selfguard roots [add <dir> [--depth N] | remove <dir>]");
+    }
+    if (values.json)
+        emit(r);
+    else
+        printRoots(r);
+    return 0;
+}
+function cmdWhere(args) {
+    const { values, positionals } = parseArgs({ args, allowPositionals: true, options: JSON_OPT });
+    const name = positionals[0];
+    if (!name)
+        usage("usage: selfguard where <package>");
+    const r = api.whereUsed(name);
+    if (values.json) {
+        emit(r);
+        return 0;
+    }
+    const c = paint(out);
+    if (r.usedIn.length === 0)
+        out.write(`${clean(name)} is not used in any tracked project.\n`);
+    for (const p of r.usedIn) {
+        const list = p.versions
+            .map((v) => `${v.vulnerable ? c.red(clean(v.version)) : clean(v.version)}${v.direct ? "" : c.dim(" (transitive)")}`)
+            .join(", ");
+        out.write(`${c.bold(tildify(p.path))}  ${list}\n`);
+    }
+    return 0;
+}
+async function cmdVuln(args) {
+    const { values, positionals } = parseArgs({ args, allowPositionals: true, options: JSON_OPT });
+    const id = positionals[0];
+    if (!id)
+        usage("usage: selfguard vuln <advisory-id>");
+    const v = await api.getVulnerability(id);
+    if (values.json) {
+        emit(v);
+        return 0;
+    }
+    const c = paint(out);
+    out.write(`${severityLabel(v.severity, c)} ${c.bold(v.id)}${v.aliases.length ? c.dim(` (${v.aliases.join(", ")})`) : ""}\n`);
+    if (v.summary)
+        out.write(`${v.summary}\n`);
+    for (const a of v.affected) {
+        const ranges = a.ranges.map((e) => Object.entries(e).map(([k, x]) => `${k} ${clean(x)}`).join("")).join(", ");
+        const versions = a.versions.length ? ` versions ${a.versions.slice(0, 10).join(", ")}` : "";
+        out.write(c.dim(`  ${a.package}: ${ranges}${versions}\n`));
+    }
+    out.write(v.affectsYourProjects.length
+        ? c.red(`Affects ${v.affectsYourProjects.length} place(s) in your projects:\n`)
+        : c.green("None of your tracked projects are affected.\n"));
+    for (const p of v.affectsYourProjects) {
+        out.write(`  ${tildify(p.path)}  ${clean(p.package)}@${clean(p.version)}${p.fixedIn ? c.green(` → ${clean(p.fixedIn)}`) : ""}\n`);
+    }
+    out.write(c.dim(`${v.url}\n`));
+    return 0;
+}
+function cmdForget(args) {
+    const { values, positionals } = parseArgs({
+        args,
+        allowPositionals: true,
+        options: { ...JSON_OPT, "keep-discoverable": { type: "boolean" } },
+    });
+    const r = api.forget(positionals[0] ?? ".", { exclude: !values["keep-discoverable"] });
+    if (values.json)
+        emit(r);
+    else {
+        out.write(r.wasTracked ? `Stopped tracking ${tildify(r.path)}` : `${tildify(r.path)} was not tracked`);
+        out.write(r.excluded ? " (excluded from discovery; undo with selfguard unexclude)\n" : "\n");
+        if (r.alsoForgotten.length)
+            out.write(`Also stopped tracking ${r.alsoForgotten.length} project(s) inside it.\n`);
+    }
+    return 0;
+}
+function cmdUnexclude(args) {
+    const { values, positionals } = parseArgs({ args, allowPositionals: true, options: JSON_OPT });
+    if (!positionals[0])
+        usage("usage: selfguard unexclude <dir>");
+    const r = api.unexclude(positionals[0]);
+    if (values.json)
+        emit(r);
+    else
+        out.write(r.removed ? "Removed from exclusions.\n" : "That path was not excluded.\n");
+    return 0;
+}
+function cmdSchedule(args) {
+    const { values, positionals } = parseArgs({
+        args,
+        allowPositionals: true,
+        options: { ...JSON_OPT, every: { type: "string", default: "6h" } },
+    });
+    switch (positionals[0]) {
+        case "on": {
+            const seconds = parseInterval(values.every ?? "6h");
+            const plist = scheduleOn(seconds);
+            if (values.json)
+                emit({ enabled: true, intervalSeconds: seconds, plist, node: process.execPath });
+            else {
+                out.write(`Background sync every ${values.every}. (${tildify(plist)})\n`);
+                out.write(`Note: it runs with ${process.execPath}; re-run this if you change Node versions.\n`);
+            }
+            return 0;
+        }
+        case "off": {
+            const was = scheduleOff();
+            if (values.json)
+                emit({ enabled: false, wasEnabled: was });
+            else
+                out.write(was ? "Background sync disabled.\n" : "Background sync was not enabled.\n");
+            return 0;
+        }
+        case "status":
+        case undefined: {
+            const s = scheduleStatus();
+            if (values.json)
+                emit(s);
+            else
+                out.write(s.loaded ? `enabled (${tildify(s.plist)})\n` : s.installed ? "installed but not loaded\n" : "disabled\n");
+            return 0;
+        }
+        default:
+            usage("usage: selfguard schedule on [--every 6h] | off | status");
+    }
+}
+async function main(argv) {
+    const [cmd, ...rest] = argv;
+    switch (cmd) {
+        case "setup":
+            if (!isInteractive())
+                usage("setup needs an interactive terminal; use `selfguard roots add <dir>` instead");
+            return runSetup();
+        case "init":
+            if (rest[0] !== "zsh")
+                usage("only zsh is supported for now: selfguard init zsh");
+            out.write(ZSH_HOOK);
+            return 0;
+        case "hook-enter": {
+            const { values } = parseArgs({ args: rest, options: { dir: { type: "string" }, prompt: { type: "boolean" } }, strict: false });
+            hookEnter(typeof values.dir === "string" ? values.dir : process.cwd(), values.prompt === true);
+            return 0;
+        }
+        case "scan":
+            return cmdScan(rest);
+        case "report":
+            return cmdReport(rest);
+        case "status":
+            return cmdStatus(rest);
+        case "sync":
+            return cmdSync(rest);
+        case "discover":
+            return cmdDiscover(rest);
+        case "roots":
+            return cmdRoots(rest);
+        case "where":
+            return cmdWhere(rest);
+        case "vuln":
+            return cmdVuln(rest);
+        case "forget":
+            return cmdForget(rest);
+        case "unexclude":
+            return cmdUnexclude(rest);
+        case "schedule":
+            return cmdSchedule(rest);
+        case "mcp":
+            await runMcpServer();
+            return 0;
+        case "guide":
+            out.write(GUIDE);
+            return 0;
+        case "-v":
+        case "--version":
+        case "version":
+            if (jsonMode)
+                emit({ version: VERSION });
+            else
+                out.write(`${VERSION}\n`);
+            return 0;
+        case undefined:
+        case "-h":
+        case "--help":
+        case "help":
+            out.write(`${HELP}\n`);
+            return 0;
+        default:
+            usage(`unknown command "${clean(cmd, 40)}". See selfguard --help`);
+    }
+}
+function errorCode(e) {
+    if (e instanceof api.ApiError)
+        return e.code;
+    if (e instanceof UsageError)
+        return "usage";
+    const nodeCode = e?.code;
+    if (typeof nodeCode === "string" && nodeCode.startsWith("ERR_PARSE_ARGS"))
+        return "usage";
+    return "error";
+}
+main(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+}, (e) => {
+    const message = clean(e instanceof Error ? e.message : String(e), 500);
+    if (jsonMode)
+        emit({ error: { code: errorCode(e), message } });
+    else
+        err.write(`selfguard: ${message}\n`);
+    process.exitCode = 2;
+});

package/dist/config.js

@@ -0,0 +1,70 @@
+import { existsSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { atomicWrite, isObject, readJsonFile } from "./fsutil.js";
+import { stateRoot } from "./paths.js";
+export const DEFAULT_DEPTH = 5;
+export const MAX_DEPTH = 10;
+const configFile = () => join(stateRoot(), "config.json");
+export function loadConfig() {
+    const raw = readJsonFile(configFile());
+    const roots = [];
+    if (raw && isObject(raw) && Array.isArray(raw.roots)) {
+        for (const r of raw.roots) {
+            if (isObject(r) && typeof r.path === "string") {
+                const depth = typeof r.depth === "number" ? clampDepth(r.depth) : DEFAULT_DEPTH;
+                roots.push({ path: r.path, depth });
+            }
+        }
+    }
+    const exclude = raw && isObject(raw) && Array.isArray(raw.exclude) ? raw.exclude.filter((e) => typeof e === "string") : [];
+    return { schema: 1, roots, exclude };
+}
+export function isExcluded(path, exclude) {
+    return exclude.some((e) => path === e || path.startsWith(e.endsWith("/") ? e : `${e}/`));
+}
+export function saveConfig(cfg) {
+    atomicWrite(configFile(), `${JSON.stringify(cfg, null, 2)}\n`);
+}
+export function clampDepth(n) {
+    return Math.max(1, Math.min(MAX_DEPTH, Math.trunc(n)));
+}
+export function expandHome(p) {
+    const t = p.trim();
+    if (t === "~")
+        return homedir();
+    if (t.startsWith("~/"))
+        return join(homedir(), t.slice(2));
+    return t;
+}
+/** Absolute, symlink-resolved directory path, or null if it isn't a directory. */
+export function normalizeDir(p) {
+    try {
+        const abs = resolve(expandHome(p));
+        if (!existsSync(abs) || !statSync(abs).isDirectory())
+            return null;
+        return realpathSync(abs);
+    }
+    catch {
+        return null;
+    }
+}
+/** Common places people keep code, shown as suggestions in `selfguard setup`. */
+const CANDIDATES = [
+    "repository", "repositories", "repos", "code", "Code", "dev", "Developer", "development",
+    "projects", "Projects", "src", "workspace", "work", "git", "github", "GitHub",
+    "Documents/GitHub", "Documents/code", "Documents/projects", "Sites",
+];
+export function candidateRoots() {
+    const seen = new Set();
+    const out = [];
+    for (const c of CANDIDATES) {
+        const dir = normalizeDir(join(homedir(), c));
+        // macOS is case-insensitive: ~/code and ~/Code are the same folder
+        if (dir && !seen.has(dir.toLowerCase())) {
+            seen.add(dir.toLowerCase());
+            out.push(dir);
+        }
+    }
+    return out;
+}

package/dist/discover.js

@@ -0,0 +1,73 @@
+/**
+ * Discovery of JS projects under folders the user chose.
+ * Breadth-first and depth-limited. Descends into every subfolder (including inside
+ * projects, so monorepos with several lockfiles are found) except dependency and
+ * generated folders like node_modules. Never follows symlinks.
+ */
+import { readdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { isExcluded } from "./config.js";
+import { LOCKFILES } from "./lockfile/detect.js";
+/** Installed dependencies and generated caches: never your code. */
+export const SKIP_DIRS = new Set([
+    "node_modules", "bower_components", "jspm_packages", // JS deps
+    "vendor", "Pods", "venv", "__pycache__", "target", // other ecosystems' deps/build caches
+]);
+/** Only skipped when they sit directly in your home folder (macOS system folders). */
+const HOME_SKIP = new Set(["Library", "Applications", "Movies", "Music", "Pictures", "Public"]);
+export async function discover(root, opts) {
+    const maxDirs = opts.maxDirs ?? 50_000;
+    const exclude = opts.exclude ?? [];
+    const home = homedir();
+    const found = [];
+    let queue = [root];
+    let visited = 0;
+    for (let level = 0; level <= opts.depth && queue.length > 0; level++) {
+        const next = [];
+        for (const dir of queue) {
+            if (opts.isCancelled?.() || visited++ >= maxDirs)
+                return found;
+            if (isExcluded(dir, exclude))
+                continue;
+            let entries;
+            try {
+                entries = await readdir(dir, { withFileTypes: true });
+            }
+            catch {
+                continue; // no permission, vanished, etc.
+            }
+            const files = new Set(entries.filter((e) => e.isFile()).map((e) => e.name));
+            const lock = LOCKFILES.find(([name]) => files.has(name));
+            if (lock) {
+                found.push({ root: dir, lockfile: join(dir, lock[0]), lockType: lock[1] });
+            }
+            else if (files.has("package.json") && entries.some((e) => e.name === ".git")) {
+                // A repo without a lockfile yet. (Workspace packages without their own
+                // lockfile are covered by the root lockfile, so they aren't listed.)
+                found.push({ root: dir, lockfile: null, lockType: null });
+            }
+            for (const e of entries) {
+                if (!e.isDirectory() || e.isSymbolicLink())
+                    continue;
+                if (e.name.startsWith("."))
+                    continue; // .git, .next, .cache, .turbo, .yarn…
+                if (SKIP_DIRS.has(e.name))
+                    continue;
+                if (dir === home && HOME_SKIP.has(e.name))
+                    continue;
+                next.push(join(dir, e.name));
+            }
+        }
+        queue = next;
+    }
+    return found;
+}
+export async function discoverAll(roots, opts = {}) {
+    const byRoot = new Map();
+    for (const r of roots) {
+        for (const p of await discover(r.path, { ...opts, depth: r.depth }))
+            byRoot.set(p.root, p);
+    }
+    return [...byRoot.values()].sort((a, b) => a.root.localeCompare(b.root));
+}

package/dist/fsutil.js

@@ -0,0 +1,66 @@
+import { createHash, randomBytes } from "node:crypto";
+import { closeSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { locksDir } from "./paths.js";
+/** Create a private directory (0700): our state reveals what you work on. */
+export function ensureDir(dir) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+/** Write a file atomically (tmp + rename) with 0600 permissions. */
+export function atomicWrite(file, data) {
+    ensureDir(dirname(file));
+    const tmp = `${file}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+    writeFileSync(tmp, data, { mode: 0o600 });
+    renameSync(tmp, file);
+}
+export function readJsonFile(file) {
+    try {
+        return JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function sha256(data) {
+    return createHash("sha256").update(data).digest("hex");
+}
+export function isObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+const STALE_LOCK_MS = 5 * 60 * 1000;
+/**
+ * Best-effort cross-process lock using O_EXCL. Returns a release function,
+ * or null if someone else holds a fresh lock.
+ */
+export function tryLock(name) {
+    ensureDir(locksDir());
+    const file = join(locksDir(), `${sha256(name).slice(0, 32)}.lock`);
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            const fd = openSync(file, "wx", 0o600);
+            writeFileSync(fd, String(process.pid));
+            closeSync(fd);
+            return () => {
+                try {
+                    unlinkSync(file);
+                }
+                catch {
+                    /* already gone */
+                }
+            };
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            try {
+                if (Date.now() - statSync(file).mtimeMs < STALE_LOCK_MS)
+                    return null;
+                unlinkSync(file); // stale: previous run crashed
+            }
+            catch {
+                /* raced with another process; retry once */
+            }
+        }
+    }
+    return null;
+}