toolroll 0.5.0

package/dist/peek.js

@@ -0,0 +1,578 @@
+/**
+ * The live peek's NATIVE reader (attended finding 7, CRITICAL): the whole
+ * point of this module is what it does not do. No git invocation ever has
+ * the agent's worktree as its working tree; nothing here consults
+ * gitattributes, hooks, clean/process filters, or external diff drivers —
+ * the mechanisms finding 7 proved can execute repository-configured
+ * commands. Change detection is a git-blob sha1 computed IN PROCESS against
+ * the frozen base tree; the diff is a line-based Myers implemented here.
+ *
+ * Two layers, deliberately separated: the PURE core (sha1, diff, parsers,
+ * aggregation — bytes in, structures out) and ONE I/O function,
+ * observeWorktree — descriptor-DISCIPLINED, not descriptor-confined: Node
+ * has no openat, so traversal is by pathname and a same-UID attacker
+ * renaming ancestors mid-walk can misdirect it (round-3 finding 44 owns
+ * the honest disclosure). What IS held: files open O_NOFOLLOW|O_NONBLOCK
+ * and must fstat as regular files on the root's device before a byte is
+ * read; reads go through that descriptor, bounded to the accepted size,
+ * with growth re-checked after; directories must prove the root's device
+ * before descent; symlinks are never followed; `.git` is never entered;
+ * every cap is explicit; unreadable corners make the look PARTIAL rather
+ * than silently narrower. Guarding, caching, and serving stay with their
+ * owners (serve.ts).
+ */
+import { createHash } from "node:crypto";
+import { open, opendir, readlink } from "node:fs/promises";
+import { constants } from "node:fs";
+import { join } from "node:path";
+/** git's own blob identity: sha1 over "blob <len>\0" + bytes. Computing it
+ * here is what lets change detection never ask git about a working tree. */
+export function gitBlobSha1(bytes) {
+    return createHash("sha1")
+        .update(`blob ${bytes.length}\0`)
+        .update(bytes)
+        .digest("hex");
+}
+/** git's heuristic, near enough: a NUL in the first 8 KiB means binary —
+ * named on the page, never diffed. */
+export function looksBinary(bytes) {
+    return bytes.subarray(0, 8192).includes(0);
+}
+/**
+ * Line-based Myers (the O(ND) greedy walk), bounded by the caller's caps —
+ * inputs beyond the byte caps never reach here. Returns unified hunks with
+ * three lines of context, or null when the edit distance exceeds `maxD`
+ * (a rewrite is not usefully rendered as a diff — the caller says so).
+ */
+export function diffLines(aText, bText, maxD = 2000) {
+    const a = aText.split("\n");
+    const b = bText.split("\n");
+    // A trailing newline yields one empty tail element on both sides; keep it —
+    // it makes "no newline at end" edits visible as a real line change.
+    const n = a.length;
+    const m = b.length;
+    const max = Math.min(n + m, maxD);
+    const offset = max;
+    // v[k] = furthest x on diagonal k; trace keeps a snapshot per d for backtrack.
+    let v = new Array(2 * max + 1).fill(0);
+    const trace = [];
+    let found = -1;
+    for (let d = 0; d <= max; d++) {
+        trace.push([...v]);
+        for (let k = -d; k <= d; k += 2) {
+            let x = k === -d || (k !== d && v[offset + k - 1] < v[offset + k + 1])
+                ? v[offset + k + 1]
+                : v[offset + k - 1] + 1;
+            let y = x - k;
+            while (x < n && y < m && a[x] === b[y]) {
+                x++;
+                y++;
+            }
+            v[offset + k] = x;
+            if (x >= n && y >= m) {
+                found = d;
+                break;
+            }
+        }
+        if (found >= 0)
+            break;
+    }
+    if (found < 0)
+        return null; // edit distance beyond maxD — not a diff, a replacement
+    const ops = [];
+    let x = n;
+    let y = m;
+    for (let d = found; d > 0; d--) {
+        const vd = trace[d];
+        const k = x - y;
+        const prevK = k === -d || (k !== d && vd[offset + k - 1] < vd[offset + k + 1])
+            ? k + 1
+            : k - 1;
+        const prevX = vd[offset + prevK];
+        const prevY = prevX - prevK;
+        while (x > prevX && y > prevY) {
+            ops.push("=");
+            x--;
+            y--;
+        }
+        if (d > 0) {
+            if (x === prevX) {
+                ops.push("+");
+                y--;
+            }
+            else {
+                ops.push("-");
+                x--;
+            }
+        }
+    }
+    while (x > 0 && y > 0) {
+        ops.push("=");
+        x--;
+        y--;
+    }
+    while (x > 0) {
+        ops.push("-");
+        x--;
+    }
+    while (y > 0) {
+        ops.push("+");
+        y--;
+    }
+    ops.reverse();
+    // Fold ops into hunks with 3 lines of context.
+    const CONTEXT = 3;
+    const hunks = [];
+    let ai = 0;
+    let bi = 0;
+    let current = null;
+    let trailingContext = 0;
+    const flush = () => {
+        if (current === null)
+            return;
+        // Trim context beyond CONTEXT at the tail.
+        while (trailingContext > CONTEXT) {
+            current.lines.pop();
+            current.aLines--;
+            current.bLines--;
+            trailingContext--;
+        }
+        hunks.push(current);
+        current = null;
+        trailingContext = 0;
+    };
+    for (const op of ops) {
+        if (op === "=") {
+            const line = a[ai];
+            if (current !== null) {
+                current.lines.push(` ${line}`);
+                current.aLines++;
+                current.bLines++;
+                trailingContext++;
+                if (trailingContext > CONTEXT * 2)
+                    flush();
+            }
+            ai++;
+            bi++;
+            continue;
+        }
+        if (current === null) {
+            const aStart = Math.max(0, ai - CONTEXT);
+            const bStart = Math.max(0, bi - CONTEXT);
+            current = { aStart: aStart + 1, aLines: 0, bStart: bStart + 1, bLines: 0, lines: [] };
+            for (let c = aStart; c < ai; c++) {
+                current.lines.push(` ${a[c]}`);
+                current.aLines++;
+                current.bLines++;
+            }
+        }
+        trailingContext = 0;
+        if (op === "-") {
+            current.lines.push(`-${a[ai]}`);
+            current.aLines++;
+            ai++;
+        }
+        else {
+            current.lines.push(`+${b[bi]}`);
+            current.bLines++;
+            bi++;
+        }
+    }
+    flush();
+    return hunks;
+}
+/** Render hunks as a unified patch body for one file, capped in bytes.
+ * The cap drops the incomplete final line (finding 9), and says so. */
+export function renderUnified(path, hunks, capBytes) {
+    const header = `--- a/${path}\n+++ b/${path}\n`;
+    const parts = [header];
+    let bytes = Buffer.byteLength(header);
+    for (const hunk of hunks) {
+        const head = `@@ -${hunk.aStart},${hunk.aLines} +${hunk.bStart},${hunk.bLines} @@\n`;
+        const body = hunk.lines.join("\n") + "\n";
+        const size = Buffer.byteLength(head) + Buffer.byteLength(body);
+        if (bytes + size > capBytes) {
+            return { text: parts.join(""), truncated: true };
+        }
+        parts.push(head, body);
+        bytes += size;
+    }
+    return { text: parts.join(""), truncated: false };
+}
+export function aggregateNewNames(paths, groupAt = 10, rowCap = 200) {
+    const bySegment = new Map();
+    for (const path of paths) {
+        const segment = path.includes("/") ? path.split("/")[0] : "";
+        const bucket = bySegment.get(segment) ?? [];
+        bucket.push(path);
+        bySegment.set(segment, bucket);
+    }
+    // The HARD row cap covers grouped rows too (round-2 finding 31): many
+    // eleven-file groups must saturate the cap exactly like loose names —
+    // an agent choosing segment names cannot amplify the output. Largest
+    // groups first, so saturation drops the least information.
+    const grouped = [];
+    const loose = [];
+    for (const [segment, bucket] of bySegment.entries()) {
+        if (segment !== "" && bucket.length > groupAt)
+            grouped.push({ label: `${segment}/`, count: bucket.length, collapsed: true });
+        else
+            loose.push(...bucket);
+    }
+    grouped.sort((a, b) => b.count - a.count || a.label.localeCompare(b.label));
+    loose.sort();
+    const rows = [];
+    let renderedFiles = 0;
+    for (const row of grouped) {
+        if (rows.length >= rowCap)
+            break;
+        rows.push(row);
+        renderedFiles += row.count;
+    }
+    for (const path of loose) {
+        if (rows.length >= rowCap)
+            break;
+        rows.push({ label: path, count: 1, collapsed: false });
+        renderedFiles += 1;
+    }
+    return { rows, total: paths.length, renderedFiles };
+}
+const KNOWN_MODES = new Set(["100644", "100755", "120000", "160000"]);
+const SHA40 = /^[0-9a-f]{40}$/;
+export function encodeBaseTreeSnapshot(snapshot) {
+    return JSON.stringify({
+        v: "base-tree/1",
+        repo: snapshot.repo,
+        run: snapshot.run,
+        base: snapshot.base,
+        entries: snapshot.entries.map(entry => [entry.path, entry.mode, entry.sha, entry.size]),
+    });
+}
+export function parseBaseTreeSnapshot(json, entryCap = 20_000) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+        return null;
+    const document = parsed;
+    if (document["v"] !== "base-tree/1")
+        return null;
+    const repo = document["repo"];
+    const run = document["run"];
+    const base = document["base"];
+    if (typeof repo !== "string" || repo === "")
+        return null;
+    if (typeof run !== "number" || !Number.isInteger(run) || run <= 0)
+        return null;
+    if (typeof base !== "string" || !SHA40.test(base))
+        return null;
+    const entries = parseBaseTree(JSON.stringify(document["entries"] ?? null), entryCap);
+    if (entries === null)
+        return null;
+    return { repo, run, base, entries };
+}
+export function parseBaseTree(json, entryCap = 20_000) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+    if (!Array.isArray(parsed) || parsed.length > entryCap)
+        return null;
+    const entries = [];
+    const seen = new Set();
+    for (const raw of parsed) {
+        if (!Array.isArray(raw) || raw.length !== 4)
+            return null;
+        const [path, mode, sha, size] = raw;
+        if (typeof path !== "string" || typeof mode !== "string" || typeof sha !== "string" || typeof size !== "number")
+            return null;
+        if (path === "" ||
+            path.startsWith("/") ||
+            path.includes("\\") ||
+            path.split("/").some(part => part === "" || part === "." || part === "..") ||
+            /[\u0000-\u001f\u007f\ufffd]/.test(path) ||
+            seen.has(path)) {
+            return null;
+        }
+        if (!KNOWN_MODES.has(mode) || !SHA40.test(sha) || !Number.isInteger(size) || size < 0 || size > 8_589_934_592)
+            return null;
+        seen.add(path);
+        entries.push({ path, mode, sha, size });
+    }
+    return entries;
+}
+export const PEEK_LIMITS = {
+    maxEntries: 20_000,
+    maxRows: 400,
+    maxFileBytes: 1_048_576,
+    maxHashedBytes: 64 * 1_048_576,
+    deadlineMs: 3_000,
+};
+/** The lease marker every occupied checkout carries — ours, never news. */
+const LEASE_MARKER = ".standing-orders-lease";
+/**
+ * One best-effort observation of a working tree against its frozen base
+ * (v2 brief §2). Descriptor-confined throughout: directories via opendir
+ * handles, files via O_NOFOLLOW descriptors, sizes from fstat on the OPEN
+ * descriptor (never a path-racy stat), bytes hashed through the same
+ * descriptor. Symlinks are typed by lstat-equivalent dirent info and never
+ * opened. Nothing here writes, spawns, or evaluates anything.
+ */
+export async function observeWorktree(root, base, limits = PEEK_LIMITS) {
+    const started = Date.now();
+    // Device pinning (round-2 finding 27 mitigation): the root's filesystem
+    // is the only one this walk will ever read from — a symlinked or
+    // bind-mounted escape onto another device is reported, never read.
+    let rootDevice;
+    try {
+        const rootHandle = await open(root, constants.O_RDONLY | constants.O_DIRECTORY);
+        try {
+            rootDevice = (await rootHandle.stat()).dev;
+        }
+        finally {
+            await rootHandle.close();
+        }
+    }
+    catch {
+        return { ok: false, reason: "the checkout could not be opened" };
+    }
+    const baseByPath = new Map(base.map(entry => [entry.path, entry]));
+    const gitlinks = new Set(base.filter(entry => entry.mode === "160000").map(entry => entry.path));
+    const seen = new Set();
+    const rows = [];
+    let rowOverflow = 0;
+    // ONE combined bound over every row kind (finding 38): past it, rows are
+    // counted, not collected — the fragment states the exact overflow.
+    const push = (row) => {
+        if (rows.length >= limits.maxRows)
+            rowOverflow += 1;
+        else
+            rows.push(row);
+    };
+    const newPaths = [];
+    let scanned = 0;
+    let hashedBytes = 0;
+    let sizeOnly = 0;
+    let unverified = 0;
+    let partialDirs = 0;
+    let partial = null;
+    const overdue = () => Date.now() - started >= limits.deadlineMs;
+    const stack = [""];
+    while (stack.length > 0) {
+        if (overdue()) {
+            partial = "the look ran out of time — showing what was seen";
+            break;
+        }
+        const relative = stack.pop();
+        if (gitlinks.has(relative))
+            continue; // a vendored repo is opaque, like git treats it
+        // Directories prove the root's device BEFORE descent (finding 44): a
+        // swapped ancestor pointing cross-device is typed, never enumerated.
+        if (relative !== "") {
+            try {
+                const gate = await open(join(root, relative), constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+                try {
+                    if ((await gate.stat()).dev !== rootDevice) {
+                        push({ kind: "unchecked", path: relative, detail: "directory on a different filesystem — not entered" });
+                        partialDirs += 1;
+                        continue;
+                    }
+                }
+                finally {
+                    await gate.close();
+                }
+            }
+            catch {
+                push({ kind: "unchecked", path: relative, detail: "directory could not be opened" });
+                partialDirs += 1;
+                continue;
+            }
+        }
+        let dir;
+        try {
+            dir = await opendir(relative === "" ? root : join(root, relative));
+        }
+        catch {
+            push({ kind: "unchecked", path: relative, detail: "directory could not be read" });
+            partialDirs += 1;
+            continue;
+        }
+        try {
+            for await (const entry of dir) {
+                if (overdue()) {
+                    partial = "the look ran out of time — showing what was seen";
+                    break;
+                }
+                const path = relative === "" ? entry.name : `${relative}/${entry.name}`;
+                if (path === ".git" || path === LEASE_MARKER)
+                    continue;
+                scanned += 1;
+                if (scanned > limits.maxEntries) {
+                    return { ok: false, reason: "this tree is too large to watch live" };
+                }
+                const inBase = baseByPath.get(path);
+                if (entry.isDirectory()) {
+                    stack.push(path);
+                    continue;
+                }
+                if (entry.isSymbolicLink()) {
+                    seen.add(path);
+                    if (inBase === undefined)
+                        newPaths.push(path);
+                    else if (inBase.mode !== "120000")
+                        push({ kind: "changed", path, detail: "became a link" });
+                    else {
+                        // The link's TARGET is the tracked content: readlink never
+                        // follows, and a 120000 blob's bytes are exactly the target
+                        // string — so the in-process sha decides (finding 34).
+                        try {
+                            const target = await readlink(join(root, path));
+                            if (gitBlobSha1(Buffer.from(target, "utf8")) !== inBase.sha) {
+                                push({ kind: "changed", path, detail: "link points elsewhere" });
+                            }
+                        }
+                        catch {
+                            push({ kind: "unchecked", path, detail: "link target could not be read" });
+                        }
+                    }
+                    continue; // never opened, never followed
+                }
+                if (!entry.isFile()) {
+                    seen.add(path);
+                    if (inBase !== undefined)
+                        push({ kind: "changed", path, detail: "became something else" });
+                    continue;
+                }
+                seen.add(path);
+                if (inBase === undefined) {
+                    newPaths.push(path);
+                    continue;
+                }
+                if (inBase.mode === "120000") {
+                    push({ kind: "changed", path, detail: "was a link, now a file" });
+                    continue;
+                }
+                // The file: O_NOFOLLOW descriptor; size and mode from fstat ON that
+                // descriptor; bytes through it. A path swapped underneath yields a
+                // typed miss, never a follow.
+                let handle;
+                try {
+                    handle = await open(join(root, path), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+                }
+                catch {
+                    push({ kind: "changed", path, detail: "could not be read just now" });
+                    continue;
+                }
+                try {
+                    const stat = await handle.stat();
+                    if (stat.dev !== rootDevice) {
+                        push({ kind: "unchecked", path, detail: "lives on a different filesystem — not read" });
+                        continue;
+                    }
+                    if (!stat.isFile()) {
+                        // A FIFO or device node planted at a tracked path: opened
+                        // non-blocking, typed, and never read (finding 44).
+                        push({ kind: "unchecked", path, detail: "not a regular file — not read" });
+                        continue;
+                    }
+                    const executable = (stat.mode & 0o100) !== 0;
+                    const baseExecutable = inBase.mode === "100755";
+                    if (stat.size !== inBase.size) {
+                        push({ kind: "changed", path, detail: `${inBase.size} → ${stat.size} bytes` });
+                        continue;
+                    }
+                    if (executable !== baseExecutable) {
+                        push({ kind: "changed", path, detail: executable ? "became executable" : "lost its executable bit" });
+                        continue;
+                    }
+                    if (stat.size > limits.maxFileBytes) {
+                        // Same size, too big to hash: SAID, never silently "unchanged".
+                        push({ kind: "unchecked", path, detail: "same size, too large to verify live" });
+                        sizeOnly += 1;
+                        continue;
+                    }
+                    if (hashedBytes + stat.size > limits.maxHashedBytes) {
+                        push({ kind: "unchecked", path, detail: "the verification budget ran out before this file" });
+                        unverified += 1;
+                        continue;
+                    }
+                    // Read AT MOST the size fstat accepted (finding 33): a file
+                    // growing underneath is a change, not an unbounded read.
+                    const hash = createHash("sha1").update(`blob ${stat.size}\0`);
+                    const buffer = Buffer.alloc(65_536);
+                    let position = 0;
+                    let grew = false;
+                    while (position < stat.size) {
+                        if (overdue()) {
+                            partial = "the look ran out of time — showing what was seen";
+                            break;
+                        }
+                        const want = Math.min(buffer.length, stat.size - position);
+                        const { bytesRead } = await handle.read(buffer, 0, want, position);
+                        if (bytesRead <= 0)
+                            break;
+                        hash.update(buffer.subarray(0, bytesRead));
+                        position += bytesRead;
+                    }
+                    hashedBytes += position;
+                    const after = await handle.stat();
+                    if (position < stat.size || after.size !== stat.size) {
+                        push({ kind: "unchecked", path, detail: "changed underneath the look" });
+                        grew = true;
+                    }
+                    if (!grew && hash.digest("hex") !== inBase.sha) {
+                        push({ kind: "changed", path, detail: "edited (same size)" });
+                    }
+                }
+                catch {
+                    push({ kind: "changed", path, detail: "could not be read just now" });
+                }
+                finally {
+                    await handle.close();
+                }
+            }
+        }
+        catch {
+            // Iteration died mid-stream: this corner was not fully seen, so the
+            // look is partial and the deleted sweep must not run (finding 44).
+            push({ kind: "unchecked", path: relative, detail: "directory could not be fully read" });
+            partialDirs += 1;
+        }
+    }
+    if (partial === null && stack.length === 0 && partialDirs === 0) {
+        for (const entry of base) {
+            if (!seen.has(entry.path) && entry.mode !== "160000" && !isUnder(entry.path, gitlinks)) {
+                push({ kind: "deleted", path: entry.path, detail: "gone" });
+            }
+        }
+    }
+    else {
+        // A timed-out walk cannot distinguish "deleted" from "not reached".
+    }
+    const notes = [];
+    if (partial !== null)
+        notes.push(partial);
+    if (partialDirs > 0)
+        notes.push(`${partialDirs} folder(s) could not be fully seen — deletions are not reported`);
+    if (rowOverflow > 0)
+        notes.push(`${rowOverflow} more change(s) than the live view will render`);
+    if (sizeOnly > 0)
+        notes.push(`${sizeOnly} large file(s) compared by size only`);
+    if (unverified > 0)
+        notes.push(`${unverified} file(s) unverified — the hashing budget ran out`);
+    return { ok: true, rows, newPaths, partial: notes.length === 0 ? null : notes.join("; "), scanned };
+}
+function isUnder(path, roots) {
+    for (const root of roots) {
+        if (path.startsWith(`${root}/`))
+            return true;
+    }
+    return false;
+}