@vigent/cli 0.0.0-stage → 0.2.1

package/dist/riftri.js

@@ -0,0 +1,284 @@
+/**
+ * Lightweight agent worktrees with riftri (https://riftri.dev).
+ *
+ * riftri creates real git linked worktrees whose unchanged files share
+ * copy-on-write storage (APFS clones, Btrfs/XFS reflinks, ReFS block clones,
+ * or OverlayFS), so ten agents on one repo cost about one checkout of disk.
+ * vigent drives riftri's CLI through its machine-readable contract: one JSON
+ * report on stdout with --json, one JSON receipt on stderr with --json-errors.
+ *
+ * With `[worktree] backend = "auto"` (the default) vigent uses riftri when it's
+ * installed and falls back to plain `git worktree` only when riftri declines
+ * with a policy receipt that says nothing was changed. Every other failure is
+ * reported, never papered over.
+ */
+import { execFile, execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import { createRequire } from "node:module";
+import * as path from "node:path";
+import { onPath } from "./engines.js";
+export const WORKTREE_BACKENDS = ["auto", "riftri", "git"];
+export const RIFTRI_INSTALL = "npm install -g riftri  (or: curl -fsSL https://riftri.dev/install.sh | bash)";
+let cachedBinary;
+/**
+ * The riftri executable: $RIFTRI_BINARY, the `riftri` npm package (installed
+ * with vigent), or `riftri` on PATH. Undefined when there's none.
+ */
+export function riftriBinary(env = process.env) {
+    const key = `${env.RIFTRI_BINARY ?? ""}\0${env.PATH ?? ""}`;
+    if (cachedBinary?.key === key)
+        return cachedBinary.bin;
+    let bin;
+    if (env.RIFTRI_BINARY)
+        bin = fs.existsSync(env.RIFTRI_BINARY) ? env.RIFTRI_BINARY : undefined;
+    else {
+        try {
+            // the package resolves and verifies the native binary for this platform
+            const pkg = createRequire(import.meta.url)("riftri");
+            bin = pkg.resolveBinary();
+        }
+        catch {
+            bin = onPath("riftri", env) ? "riftri" : undefined;
+        }
+    }
+    cachedBinary = { key, bin };
+    return bin;
+}
+function parseReceipt(stderr) {
+    const lines = stderr.trim().split("\n").reverse();
+    for (const line of lines) {
+        if (!line.trim().startsWith("{"))
+            continue;
+        try {
+            return JSON.parse(line);
+        }
+        catch {
+            // not the receipt
+        }
+    }
+    return undefined;
+}
+function failure(err) {
+    const exitCode = typeof err?.status === "number" ? err.status : typeof err?.code === "number" ? err.code : 1;
+    const stderr = String(err?.stderr ?? "");
+    const receipt = parseReceipt(stderr);
+    const message = receipt?.message ??
+        (err?.code === "ENOENT" ? "riftri isn't installed" : stderr.trim().split("\n").pop() || err?.message || `exited with code ${exitCode}`);
+    // only a policy receipt that confirms no cleanup is needed makes falling back safe
+    const declined = exitCode === 3 && receipt?.category === "policy" && receipt.cleanup === "not-needed" && receipt.code !== "storage-full";
+    return { ok: false, exitCode, receipt, message, declined };
+}
+function parseReport(stdout) {
+    const text = stdout.trim();
+    return text ? JSON.parse(text) : null;
+}
+/** Run riftri and parse its report or receipt. Never throws. */
+export function riftriSync(args, cwd, env = process.env, bin = riftriBinary(env)) {
+    if (!bin)
+        return { ok: false, exitCode: 127, message: "riftri isn't installed", declined: false };
+    try {
+        const out = execFileSync(bin, ["--json-errors", ...args], {
+            cwd,
+            env,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+            maxBuffer: 64 * 1024 * 1024,
+            timeout: 10 * 60 * 1000,
+        });
+        return { ok: true, report: parseReport(out) };
+    }
+    catch (err) {
+        return failure(err);
+    }
+}
+/** The same, without blocking the UI (doctor and status walk the disk). */
+export function riftriAsync(args, cwd, env = process.env, bin = riftriBinary(env)) {
+    if (!bin)
+        return Promise.resolve({ ok: false, exitCode: 127, message: "riftri isn't installed", declined: false });
+    return new Promise((resolve) => {
+        execFile(bin, ["--json-errors", ...args], { cwd, env, maxBuffer: 64 * 1024 * 1024, timeout: 2 * 60 * 1000 }, (err, stdout, stderr) => {
+            if (err)
+                return resolve(failure({ ...err, status: err.code, stderr }));
+            try {
+                resolve({ ok: true, report: parseReport(String(stdout)) });
+            }
+            catch (e) {
+                resolve({ ok: false, exitCode: 1, message: `riftri printed something that isn't JSON: ${e.message}`, declined: false });
+            }
+        });
+    });
+}
+/** A failed riftri step as one line, with the command riftri suggests. */
+export function describeFailure(r) {
+    const next = r.receipt?.nextCommand;
+    return `${r.message}${next ? ` (riftri suggests: ${next})` : ""}`;
+}
+/** `riftri worktree add <folder> -b <branch> <base>` */
+export function riftriAdd(root, folder, branch, base, env) {
+    return riftriSync(["worktree", "add", folder, "-b", branch, base, "--json", "--no-progress"], root, env);
+}
+/** The repository's riftri state folder (<common git dir>/riftri), if riftri has ever been used here. */
+export function riftriStateDir(root) {
+    try {
+        const common = execFileSync("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], {
+            cwd: root,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        }).trim();
+        const dir = path.join(common, "riftri");
+        return fs.existsSync(dir) ? dir : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Does riftri manage this worktree? Answered without running riftri when
+ * the repository has no riftri state. An ownership error is not "unmanaged":
+ * riftri's contract is to never turn it into ordinary git cleanup.
+ */
+export function riftriOwnership(root, worktreePath, env) {
+    if (!riftriStateDir(root))
+        return { managed: false };
+    if (!riftriBinary(env)) {
+        return { managed: false, error: `this repository has riftri worktrees, but riftri isn't installed: ${RIFTRI_INSTALL}` };
+    }
+    const r = riftriSync(["worktree", "inspect", "--json", "--", worktreePath], root, env);
+    if (!r.ok)
+        return { managed: false, error: describeFailure(r) };
+    const w = r.report?.worktrees?.[0];
+    return w?.state_directory ? { managed: true, backend: w.backend ?? undefined } : { managed: false };
+}
+/** `riftri worktree remove [--force]`; dirty views are refused unless forced. */
+export function riftriRemove(root, worktreePath, force, env) {
+    return riftriSync(["worktree", "remove", ...(force ? ["--force"] : []), worktreePath, "--json", "--no-progress"], root, env);
+}
+/** Reclaim bases no worktree uses any more (`riftri gc --apply`). Best effort. */
+export function riftriGc(root, env) {
+    return riftriSync(["gc", "--apply", "--json", "--no-progress"], root, env);
+}
+const READY_MOUNT = new Set([null, undefined, "active"]);
+/**
+ * Before reopening agents: inspect their worktrees, repair views whose
+ * OverlayFS mount went away (a reboot), and inspect again. A repair that
+ * succeeds is not proof by itself; only the second inspection is.
+ */
+export function prepareViews(root, paths, env) {
+    const out = new Map();
+    for (const p of paths)
+        out.set(p, { path: p, ready: true });
+    if (paths.length === 0 || !riftriStateDir(root) || !riftriBinary(env))
+        return out;
+    const inspect = () => riftriSync(["worktree", "inspect", "--json", "--", ...paths], root, env);
+    let r = inspect();
+    if (!r.ok) {
+        for (const p of paths)
+            out.set(p, { path: p, ready: false, reason: describeFailure(r) });
+        return out;
+    }
+    const needsRepair = new Set(r.report.worktrees.filter((w) => w.mount_status === "recovery-required" && w.state_directory).map((w) => w.state_directory));
+    if (needsRepair.size > 0) {
+        for (const dir of needsRepair)
+            riftriSync(["repair", "--state-dir", dir, "--json", "--no-progress"], root, env);
+        r = inspect();
+        if (!r.ok) {
+            for (const p of paths)
+                out.set(p, { path: p, ready: false, reason: describeFailure(r) });
+            return out;
+        }
+    }
+    r.report.worktrees.forEach((w, i) => {
+        const p = paths[i] ?? w.path;
+        const ready = READY_MOUNT.has(w.mount_status);
+        out.set(p, {
+            path: p,
+            ready,
+            backend: w.backend ?? undefined,
+            reason: ready ? undefined : `riftri reports its mount as ${w.mount_status}; run: riftri repair --state-dir '${w.state_directory}'`,
+        });
+    });
+    return out;
+}
+/** Which of these worktrees riftri manages, and with which backend (no disk walk). */
+export function riftriBackends(root, paths, env) {
+    const out = new Map();
+    if (paths.length === 0 || !riftriStateDir(root) || !riftriBinary(env))
+        return out;
+    const r = riftriSync(["worktree", "inspect", "--json", "--", ...paths], root, env);
+    if (!r.ok)
+        return out;
+    r.report.worktrees.forEach((w, i) => {
+        if (w.state_directory && paths[i])
+            out.set(paths[i], w.backend ?? "riftri");
+    });
+    return out;
+}
+/** Ask riftri whether new agent worktrees in `dir` can be copy-on-write, and what the existing ones cost. */
+export async function riftriHealth(root, dir, backend, env = process.env) {
+    const bin = riftriBinary(env);
+    if (backend === "git")
+        return { installed: Boolean(bin), ready: false, detail: "off ([worktree] backend = \"git\")", blockers: [] };
+    if (!bin)
+        return { installed: false, ready: false, detail: "not installed: agent worktrees are full copies", blockers: [] };
+    const v = await new Promise((resolve) => execFile(bin, ["--version"], { env, timeout: 10_000 }, (err, stdout) => resolve(err ? undefined : /\d+\.\d+\.\d+[\w.-]*/.exec(String(stdout))?.[0])));
+    if (!root || !dir)
+        return { installed: true, version: v, ready: false, detail: "not in a git repository", blockers: [] };
+    // doctor needs a destination that doesn't exist yet
+    const probe = path.join(dir, `.vigent-probe-${process.pid}`);
+    const doc = await riftriAsync(["doctor", "--destination", probe, "--json"], root, env, bin);
+    if (!doc.ok)
+        return { installed: true, version: v, ready: false, detail: describeFailure(doc), blockers: [] };
+    const rd = doc.report?.destination_readiness ?? {};
+    // needs-activation only concerns riftri's git shim; vigent calls riftri directly
+    const blockers = (rd.blockers ?? [])
+        .filter((b) => b.kind !== "repository-activation")
+        .map((b) => `${b.explanation}${b.remedy ? ` · ${b.remedy}` : ""}`);
+    const ready = (rd.status === "ready" || rd.status === "needs-activation") && Boolean(rd.copy_on_write);
+    const health = {
+        installed: true,
+        version: v,
+        ready,
+        backend: rd.backend ?? undefined,
+        detail: ready ? `copy-on-write worktrees (${backendName(rd.backend)})` : blockers.length ? "can't optimize this repository yet" : `not available here (${rd.status ?? "blocked"})`,
+        blockers,
+        next: rd.status === "needs-activation" ? undefined : (rd.next_command ?? undefined),
+    };
+    if (riftriStateDir(root)) {
+        const st = await riftriAsync(["status", "--json"], root, env, bin);
+        if (st.ok && st.report) {
+            health.views = st.report.operations?.active_views ?? st.report.worktrees?.length ?? 0;
+            health.logicalBytes = st.report.total_logical_bytes;
+            health.allocatedBytes = st.report.total_allocated_bytes;
+        }
+    }
+    return health;
+}
+export function backendName(backend) {
+    switch (backend) {
+        case "reflink":
+            return "Btrfs/XFS reflinks";
+        case "apfs-clone":
+        case "apfs":
+            return "APFS clones";
+        case "refs-block-clone":
+        case "refs":
+            return "ReFS block clones";
+        case "overlay-fs":
+            return "OverlayFS";
+        default:
+            return backend ?? "unknown";
+    }
+}
+/** 16211491 -> "15.5 MB" */
+export function formatBytes(n) {
+    if (n === undefined || !Number.isFinite(n))
+        return "?";
+    const units = ["B", "KB", "MB", "GB", "TB"];
+    let i = 0;
+    let v = n;
+    while (v >= 1024 && i < units.length - 1) {
+        v /= 1024;
+        i++;
+    }
+    return `${v >= 100 || i === 0 ? Math.round(v) : v.toFixed(1)} ${units[i]}`;
+}