@skyramp/mcp 0.3.8 → 0.4.0-rc.1

package/build/utils/branchDiff.d.ts

@@ -10,35 +10,67 @@ export interface BranchDiffData {
     /** Files deleted in this branch (+++ /dev/null in diff header). Relative paths. */
     deletedFiles: string[];
 }
-/**
- * Extract every file path mentioned in a unified-diff `diff --git` header.
- * Always uses the `b/` form so renames return the new path.
- */
-export declare function parseChangedFilesFromDiff(rawDiff: string): string[];
-/**
- * Splits a unified diff into per-file added-line arrays, keyed by the `b/`
- * (post-change) path. Exported so other file->resource-affinity callers
- * (e.g. `pathAffinityClassification.ts`'s fallback, SKYR-3857) can derive the
- * same per-file diff hunks this module uses, without re-implementing the
- * diff-header walk. Lives here rather than in `importerHop.ts`, its original
- * home, so callers that `importerHop.ts` itself imports can reach it without
- * an import cycle.
- */
-export declare function sliceAddedLinesByFile(diffContent: string): Map<string, string[]>;
-/**
- * Normalize and validate a caller-provided base branch/ref before passing it
- * to git. Reject option-like or ambiguous values so the ref is always treated
- * as a revision name, not as a command-line flag.
- */
+/** Every path in a `diff --git` header, always the `b/` form so a rename
+ *  returns the new name. */
+/** One `diff --git` block, read once. */
+export interface ChangedFileEntry {
+    /** The `b/` path, so a rename reports the new name. */
+    path: string;
+    /** `--- /dev/null`. A newly added BINARY file has no such line: git renders
+     *  `Binary files /dev/null and b/… differ` instead. */
+    isNew: boolean;
+    /** `+++ /dev/null`, or a deleted binary's `Binary files a/… and /dev/null`. */
+    isDeleted: boolean;
+    /** A pure rename and a mode-only change carry no hunk. */
+    hasHunks: boolean;
+    /** A rename's `a/` path. The block is keyed by the NEW path, so without this
+     *  "was this path removed" answers a false no. */
+    renamedFrom?: string;
+}
+/** Every `diff --git` block, in order. Per BLOCK, never per path: the text
+ *  concatenates every repository, so one repository's deletion of a path would
+ *  hide another's real change to it. */
+export declare function parseDiffEntries(rawDiff: string): ChangedFileEntry[];
+/** Each changed path's own slice, so a check can ask whether a line is in THIS
+ *  file. Two repositories changing one path share a key, which errs toward
+ *  saying a file holds a line it does not. */
+export declare function diffBlocksByPath(rawDiff: string): Map<string, string>;
+/** Git quotes a path only when it has to. An unquoted path is returned as it
+ *  stands, because decoding escapes in one would corrupt a legal name that
+ *  really contains a backslash. */
+export declare function unquoteIfQuoted(value: string): string;
+/** Undo git's C-style quoting. A non-ASCII character arrives as one `\NNN` escape
+ *  per UTF-8 BYTE, so the bytes are decoded once at the end. */
+export declare function unquoteGitPath(value: string): string;
+/** Exported so `frontendSurface` drops a deleted file without a second walk. */
+export declare function parseNewAndDeletedFiles(rawDiff: string): {
+    newFiles: string[];
+    deletedFiles: string[];
+};
+/** Reject an option-like or ambiguous ref, so git reads it as a revision name
+ *  and never as a command-line flag. */
 export declare function normalizeProvidedBaseRef(providedBaseBranch?: string): string | undefined;
-/**
- * Compute the diff between a base reference and the current state.
- *
- * @param repositoryPath  Absolute path to the git repository.
- * @param providedBaseBranch  A branch name, tag, or commit SHA to diff against.
- *   When omitted, the remote default branch is auto-detected.
- * @param includeUncommitted  When true, diffs against the working tree so
- *   uncommitted/unstaged changes are included. Defaults to false (CI mode
- *   that only considers committed changes via the three-dot form).
- */
-export declare function computeBranchDiff(repositoryPath: string, providedBaseBranch?: string, includeUncommitted?: boolean): Promise<BranchDiffData>;
+/** One changed path, read from `--name-status` rather than from diff text. */
+export interface ChangedFileName {
+    /** Repository-relative path in git's own spelling, unquoted. A rename reports
+     *  the new path; the old one arrives as a separate deleted entry. */
+    path: string;
+    /** Removed, but still a changed surface: a test can assert its route is gone. */
+    deleted: boolean;
+}
+/** Parse `git diff --name-status`. Exported for its own tests.
+ *  A rename and a copy carry TWO paths: the new one is the changed surface, and
+ *  a rename also removes the old, while a copy leaves the original. Git quotes a
+ *  non-ASCII path here as it does in a diff header. */
+export declare function parseNameStatus(raw: string): ChangedFileName[];
+/** The ONE derivation of `{path, deleted}` from a names-only diff, so no caller
+ *  re-derives the join. */
+export declare function changedFileNames(diff: BranchDiffData): ChangedFileName[];
+/** Compute the diff between a base reference and the current state.
+ *  `providedBaseBranch` takes a branch, tag or SHA; omitted, the remote default
+ *  is detected. `includeUncommitted` diffs the working tree (local dev); false
+ *  compares two commits through the three-dot form, which is the CI shape. */
+export declare function computeBranchDiff(repositoryPath: string, providedBaseBranch?: string, includeUncommitted?: boolean, 
+/** Names only: no diff text is computed, and `diffContent`/`diffStat` come back
+ *  empty. The plan checks read which files changed, never what changed in them. */
+namesOnly?: boolean): Promise<BranchDiffData>;

package/build/utils/branchDiff.js

@@ -1,75 +1,141 @@
 import { simpleGit } from "simple-git";
 import { logger } from "./logger.js";
-/**
- * Extract every file path mentioned in a unified-diff `diff --git` header.
- * Always uses the `b/` form so renames return the new path.
- */
-export function parseChangedFilesFromDiff(rawDiff) {
-    const out = [];
-    const re = /^diff --git a\/\S+ b\/(\S+)/gm;
-    let m;
-    while ((m = re.exec(rawDiff)) !== null) {
-        out.push(m[1]);
-    }
-    return out;
-}
-/**
- * Splits a unified diff into per-file added-line arrays, keyed by the `b/`
- * (post-change) path. Exported so other file->resource-affinity callers
- * (e.g. `pathAffinityClassification.ts`'s fallback, SKYR-3857) can derive the
- * same per-file diff hunks this module uses, without re-implementing the
- * diff-header walk. Lives here rather than in `importerHop.ts`, its original
- * home, so callers that `importerHop.ts` itself imports can reach it without
- * an import cycle.
- */
-export function sliceAddedLinesByFile(diffContent) {
-    const sections = new Map();
-    let currentFile = null;
-    for (const line of diffContent.split("\n")) {
-        const headerMatch = /^diff --git a\/.+ b\/(.+)$/.exec(line);
-        if (headerMatch) {
-            currentFile = headerMatch[1];
+/** Every `diff --git` block, in order. Per BLOCK, never per path: the text
+ *  concatenates every repository, so one repository's deletion of a path would
+ *  hide another's real change to it. */
+export function parseDiffEntries(rawDiff) {
+    const entries = [];
+    for (const line of rawDiff.split("\n")) {
+        if (line.startsWith("diff --git ")) {
+            const path = parseDiffHeaderPath(line);
+            // An unreadable header still ENDS the previous block, or its `/dev/null`
+            // and `@@` lines are credited to the entry before it.
+            if (path === undefined) {
+                entries.push({ path: "", isNew: false, isDeleted: false, hasHunks: false });
+                continue;
+            }
+            entries.push({ path, isNew: false, isDeleted: false, hasHunks: false });
             continue;
         }
-        if (!currentFile)
+        const current = entries[entries.length - 1];
+        if (!current)
             continue;
-        if (line.startsWith("+") && !line.startsWith("+++")) {
-            const arr = sections.get(currentFile) ?? [];
-            arr.push(line);
-            sections.set(currentFile, arr);
+        if (line === "--- /dev/null")
+            current.isNew = true;
+        else if (line === "+++ /dev/null")
+            current.isDeleted = true;
+        else if (line.startsWith("@@ "))
+            current.hasHunks = true;
+        // A binary block has no `--- `/`+++ ` lines; git folds both into this one.
+        else if (line.startsWith("Binary files /dev/null and "))
+            current.isNew = true;
+        else if (line.startsWith("Binary files ") && line.endsWith(" and /dev/null differ"))
+            current.isDeleted = true;
+        // Unquoted like the new-path side, or one rename's two halves disagree.
+        else if (line.startsWith("rename from "))
+            current.renamedFrom = unquoteIfQuoted(line.slice("rename from ".length));
+    }
+    return entries;
+}
+/** Each changed path's own slice, so a check can ask whether a line is in THIS
+ *  file. Two repositories changing one path share a key, which errs toward
+ *  saying a file holds a line it does not. */
+export function diffBlocksByPath(rawDiff) {
+    const blocks = new Map();
+    let current;
+    for (const line of rawDiff.split("\n")) {
+        // ANY `diff ` header ends a block, not just `diff --git`: a combined diff
+        // writes `diff --cc`, and its lines would otherwise append to the file before.
+        if (line.startsWith("diff ")) {
+            const path = line.startsWith("diff --git ") ? parseDiffHeaderPath(line) : undefined;
+            if (path === undefined) {
+                current = undefined;
+                continue;
+            }
+            current = blocks.get(path) ?? [];
+            blocks.set(path, current);
         }
+        current?.push(line);
     }
-    return sections;
+    return new Map([...blocks].map(([path, lines]) => [path, lines.join("\n")]));
 }
-/** Parse diff headers to find newly created and deleted files. */
-function isShaLikeRef(ref) {
-    return /^[0-9a-f]{7,40}$/i.test(ref);
+/** The `b/` path of a header, unquoted. Git QUOTES a non-ASCII path and
+ *  `core.quotePath` defaults to true, so a header can read
+ *  `diff --git "a/src/caf\303\251.tsx" "b/…"`. */
+function parseDiffHeaderPath(line) {
+    const rest = line.slice("diff --git ".length);
+    // Git quotes each side INDEPENDENTLY: a rename of a non-ASCII name emits one
+    // quoted side and one bare, which a single whole-line pattern reads neither of.
+    const quoted = /^"a\/((?:[^"\\]|\\.)*)" "b\/((?:[^"\\]|\\.)*)"$/.exec(rest);
+    if (quoted)
+        return unquoteGitPath(quoted[2]);
+    const quotedNew = /^a\/.+ "b\/((?:[^"\\]|\\.)*)"$/.exec(rest);
+    if (quotedNew)
+        return unquoteGitPath(quotedNew[1]);
+    const quotedOld = /^"a\/(?:[^"\\]|\\.)*" b\/(.+)$/.exec(rest);
+    if (quotedOld)
+        return quotedOld[1];
+    const plain = /^a\/.+ b\/(.+)$/.exec(rest);
+    if (plain)
+        return plain[1];
+    // `diff.noprefix` drops `a/` and `b/`; `diff.mnemonicPrefix` makes them
+    // `c/ w/ i/ o/`. Both are developer-local, so only the local-dev path sees them.
+    const mnemonic = /^[a-z]\/(.+) [a-z]\/(.+)$/.exec(rest);
+    if (mnemonic)
+        return mnemonic[2];
+    const noPrefix = /^(\S+) (\S+)$/.exec(rest);
+    return noPrefix ? noPrefix[2] : undefined;
+}
+/** Git quotes a path only when it has to. An unquoted path is returned as it
+ *  stands, because decoding escapes in one would corrupt a legal name that
+ *  really contains a backslash. */
+export function unquoteIfQuoted(value) {
+    const trimmed = value.trim();
+    return trimmed.startsWith('"') && trimmed.endsWith('"') ? unquoteGitPath(trimmed) : trimmed;
 }
-function parseNewAndDeletedFiles(rawDiff) {
-    const newFiles = [];
-    const deletedFiles = [];
-    const lines = rawDiff.split("\n");
-    let currentFile = "";
-    for (const line of lines) {
-        const fileMatch = line.match(/^diff --git a\/.+ b\/(.+)$/);
-        if (fileMatch) {
-            currentFile = fileMatch[1];
+/** Undo git's C-style quoting. A non-ASCII character arrives as one `\NNN` escape
+ *  per UTF-8 BYTE, so the bytes are decoded once at the end. */
+export function unquoteGitPath(value) {
+    const trimmed = value.startsWith('"') && value.endsWith('"') ? value.slice(1, -1) : value;
+    const simple = { n: "\n", t: "\t", r: "\r", '"': '"', "\\": "\\" };
+    const bytes = [];
+    for (let i = 0; i < trimmed.length; i++) {
+        if (trimmed[i] !== "\\") {
+            bytes.push(...Buffer.from(trimmed[i], "utf-8"));
             continue;
         }
-        if (line === "--- /dev/null" && currentFile) {
-            newFiles.push(currentFile);
-        }
-        else if (line === "+++ /dev/null" && currentFile) {
-            deletedFiles.push(currentFile);
+        const next = trimmed[++i];
+        if (next !== undefined && /[0-7]/.test(next) && /^[0-7]{3}$/.test(trimmed.slice(i, i + 3))) {
+            bytes.push(parseInt(trimmed.slice(i, i + 3), 8));
+            i += 2;
+            continue;
         }
+        bytes.push(...Buffer.from(next === undefined ? "\\" : (simple[next] ?? next), "utf-8"));
     }
-    return { newFiles, deletedFiles };
+    return Buffer.from(bytes).toString("utf-8");
+}
+/** Parse diff headers to find newly created and deleted files. */
+function isShaLikeRef(ref) {
+    return /^[0-9a-f]{7,40}$/i.test(ref);
 }
-/**
- * Normalize and validate a caller-provided base branch/ref before passing it
- * to git. Reject option-like or ambiguous values so the ref is always treated
- * as a revision name, not as a command-line flag.
- */
+/** Exported so `frontendSurface` drops a deleted file without a second walk. */
+export function parseNewAndDeletedFiles(rawDiff) {
+    const entries = parseDiffEntries(rawDiff);
+    const renamedFromPaths = entries
+        .map((entry) => entry.renamedFrom)
+        .filter((path) => path !== undefined);
+    // An unreadable header yields `""`, which would read as a file nobody added.
+    return {
+        newFiles: entries.filter((entry) => entry.isNew && entry.path).map((entry) => entry.path),
+        // Keyed by the NEW path, so the OLD one is added here: it moved, not died.
+        deletedFiles: [
+            ...entries.filter((entry) => entry.isDeleted && entry.path).map((entry) => entry.path),
+            ...renamedFromPaths,
+        ].filter(Boolean),
+    };
+}
+/** Reject an option-like or ambiguous ref, so git reads it as a revision name
+ *  and never as a command-line flag. */
 export function normalizeProvidedBaseRef(providedBaseBranch) {
     if (providedBaseBranch === undefined)
         return undefined;
@@ -87,21 +153,53 @@ export function normalizeProvidedBaseRef(providedBaseBranch) {
     }
     return trimmed;
 }
+/** The paths `--name-status` marks `A`. A rename's new path is NOT one: git
+ *  reports it as `R`, and `parseNameStatus` already lists it as changed. */
+function addedPaths(raw) {
+    const added = [];
+    for (const line of (typeof raw === "string" ? raw : "").split("\n")) {
+        const parts = line.split("\t");
+        if ((parts[0] ?? "").trim().toUpperCase() !== "A")
+            continue;
+        const path = unquoteIfQuoted(parts[1] ?? "");
+        if (path)
+            added.push(path);
+    }
+    return added;
+}
+/** `--name-status` for one ref, split into the three lists `BranchDiffData` carries.
+ *  Undefined when the ref does not resolve; an EMPTY listing is a result, not a
+ *  failure. */
+async function tryNameStatus(git, ref, includeUncommitted) {
+    try {
+        const raw = await git.diff([includeUncommitted ? ref : `${ref}...HEAD`, "--name-status"]);
+        const files = parseNameStatus(raw);
+        return {
+            changedFiles: files.filter((file) => !file.deleted).map((file) => file.path),
+            // `--name-status` marks an added path `A`; the header parser never runs here.
+            newFiles: addedPaths(raw),
+            deletedFiles: files.filter((file) => file.deleted).map((file) => file.path),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
 async function tryDiff(git, ref, includeUncommitted = false) {
     try {
-        // When includeUncommitted is true, diff the ref directly against the
-        // working tree so uncommitted/unstaged local changes are captured.
+        // `includeUncommitted` diffs the ref against the working tree.
         const diffRange = includeUncommitted ? ref : `${ref}...HEAD`;
         const changedFilesRaw = await git.diff([diffRange, "--name-only"]);
         const changedFiles = changedFilesRaw
             .split("\n")
             .map((f) => f.trim())
-            .filter((f) => f.length > 0);
+            .filter((f) => f.length > 0)
+            // `--name-only` quotes a non-ASCII path too.
+            .map((f) => unquoteGitPath(f));
         const diffStat = await git.diff([diffRange, "--stat"]);
         const fullDiff = await git.diff([diffRange]);
         const { newFiles, deletedFiles } = parseNewAndDeletedFiles(fullDiff);
-        // git diff does not include untracked files. Include them as both changed
-        // and new so endpoint classification treats newly created local files as new.
+        // git diff omits untracked files; list them as both changed and new.
         if (includeUncommitted) {
             const statusResult = await git.status();
             const untrackedFiles = statusResult.not_added ?? [];
@@ -135,31 +233,11 @@ async function tryDiff(git, ref, includeUncommitted = false) {
         return undefined;
     }
 }
-/**
- * Compute the diff between a base reference and the current state.
- *
- * @param repositoryPath  Absolute path to the git repository.
- * @param providedBaseBranch  A branch name, tag, or commit SHA to diff against.
- *   When omitted, the remote default branch is auto-detected.
- * @param includeUncommitted  When true, diffs against the working tree so
- *   uncommitted/unstaged changes are included. Defaults to false (CI mode
- *   that only considers committed changes via the three-dot form).
- */
-export async function computeBranchDiff(repositoryPath, providedBaseBranch, includeUncommitted = false) {
-    const git = simpleGit(repositoryPath);
-    const isRepo = await git.checkIsRepo();
-    if (!isRepo) {
-        throw new Error(`"${repositoryPath}" is not a Git repository.`);
-    }
-    const branchInfo = await git.branch();
-    const currentBranch = branchInfo.current || "HEAD";
-    // Build candidate base refs in priority order:
-    // 1. Provided value used directly (supports SHAs, local branches, tags)
-    // 2. Provided value with origin/ prefix (remote branch)
-    // 3. Remote default branch auto-detected from available remotes
-    // 4. FETCH_HEAD — present in base_commit repos (git fetch --depth 1 origin <sha>)
-    //    where no remote tracking branch is created
-    // 5. HEAD~1 — last resort for repos with no remote at all
+/** The base refs to try, in priority order. One ladder for both modes, or they
+ *  would answer about different bases. */
+async function baseRefCandidates(git, providedBaseBranch, includeUncommitted) {
+    // In order: the value as given, then with `origin/`, the detected remote
+    // default, FETCH_HEAD (a base_commit clone has no tracking branch), HEAD~1.
     const candidates = [];
     const normalizedBaseBranch = normalizeProvidedBaseRef(providedBaseBranch);
     if (normalizedBaseBranch) {
@@ -168,20 +246,17 @@ export async function computeBranchDiff(repositoryPath, providedBaseBranch, incl
             !isShaLikeRef(normalizedBaseBranch) &&
             !/[~^:@]/.test(normalizedBaseBranch);
         if (includeUncommitted && looksLikeSimpleBranch) {
-            // Local-dev diffs should prefer the remote base branch when available;
-            // a developer's local main may be ahead of origin/main.
+            // A developer's local main may be ahead of origin/main.
             candidates.push(`origin/${normalizedBaseBranch}`);
             candidates.push(normalizedBaseBranch);
         }
         else {
-            // Try the raw value first — handles commit SHAs, tags, and explicit local refs.
             candidates.push(normalizedBaseBranch);
             if (!isRemoteQualified) {
                 candidates.push(`origin/${normalizedBaseBranch}`);
             }
         }
     }
-    // Auto-detect remote default branch
     try {
         const remoteBranches = await git.branch(["-r"]);
         if (remoteBranches.all.some((b) => b.endsWith("/main"))) {
@@ -196,10 +271,83 @@ export async function computeBranchDiff(repositoryPath, providedBaseBranch, incl
     catch {
         logger.debug("Could not list remote branches");
     }
-    // FETCH_HEAD covers base_commit repos (appsmith, etc.)
     candidates.push("FETCH_HEAD");
-    // Final fallback
     candidates.push("HEAD~1");
+    return candidates;
+}
+/** Parse `git diff --name-status`. Exported for its own tests.
+ *  A rename and a copy carry TWO paths: the new one is the changed surface, and
+ *  a rename also removes the old, while a copy leaves the original. Git quotes a
+ *  non-ASCII path here as it does in a diff header. */
+export function parseNameStatus(raw) {
+    const files = [];
+    const add = (value, deleted) => {
+        const path = unquoteIfQuoted(value ?? "");
+        if (path)
+            files.push({ path, deleted });
+    };
+    for (const line of (typeof raw === "string" ? raw : "").split("\n")) {
+        if (!line.trim())
+            continue;
+        const parts = line.split("\t");
+        // A similarity score follows the letter on a rename or a copy: `R100`, `C085`.
+        const status = (parts[0] ?? "").trim().toUpperCase();
+        if (!status)
+            continue;
+        if ((status.startsWith("R") || status.startsWith("C")) && parts[2]) {
+            add(parts[2], false);
+            if (status.startsWith("R"))
+                add(parts[1], true);
+            continue;
+        }
+        // A rename or copy with no second path is malformed; read its one path as an
+        // ordinary change rather than dropping the file.
+        add(parts[1], status === "D");
+    }
+    return files;
+}
+/** The ONE derivation of `{path, deleted}` from a names-only diff, so no caller
+ *  re-derives the join. */
+export function changedFileNames(diff) {
+    return [
+        ...(diff.changedFiles ?? []).map((path) => ({ path, deleted: false })),
+        ...(diff.deletedFiles ?? []).map((path) => ({ path, deleted: true })),
+    ];
+}
+/** Compute the diff between a base reference and the current state.
+ *  `providedBaseBranch` takes a branch, tag or SHA; omitted, the remote default
+ *  is detected. `includeUncommitted` diffs the working tree (local dev); false
+ *  compares two commits through the three-dot form, which is the CI shape. */
+export async function computeBranchDiff(repositoryPath, providedBaseBranch, includeUncommitted = false, 
+/** Names only: no diff text is computed, and `diffContent`/`diffStat` come back
+ *  empty. The plan checks read which files changed, never what changed in them. */
+namesOnly = false) {
+    const git = simpleGit(repositoryPath);
+    const isRepo = await git.checkIsRepo();
+    if (!isRepo) {
+        throw new Error(`"${repositoryPath}" is not a Git repository.`);
+    }
+    const branchInfo = await git.branch();
+    const currentBranch = branchInfo.current || "HEAD";
+    const candidates = await baseRefCandidates(git, providedBaseBranch, includeUncommitted);
+    if (namesOnly) {
+        for (const ref of candidates) {
+            const result = await tryNameStatus(git, ref, includeUncommitted);
+            // The FIRST ref that resolves wins, even when it lists nothing: walking past
+            // an empty listing reached `HEAD~1` and reported the previous commit's files
+            // as this pull request's.
+            if (result) {
+                logger.info("Changed-file names computed", {
+                    currentBranch,
+                    baseBranch: ref,
+                    changedFiles: result.changedFiles.length,
+                });
+                return { currentBranch, baseBranch: ref, diffContent: "", diffStat: "", ...result };
+            }
+            logger.debug(`Name-status against ${ref} failed, trying next candidate`);
+        }
+        throw new Error(`Could not list changed file names: all candidates failed (${candidates.join(", ")})`);
+    }
     for (const ref of candidates) {
         const result = await tryDiff(git, ref, includeUncommitted);
         if (result) {

package/build/utils/containedPath.d.ts

@@ -0,0 +1,18 @@
+/** Resolve and read a path an AGENT wrote, without leaving the checkout. ONE
+ *  implementation for every such reader: an escape closed in one and left open in
+ *  another is the same hole. */
+/** `candidate` resolved against `root`, or undefined when the real target is not
+ *  inside `root`. `root` must already be a real path, or a symlinked checkout fails
+ *  its own containment test. */
+export declare function resolveWithinRoot(root: string, candidate: string): string | undefined;
+/** Whether `cited` names a real FILE inside `root`. */
+export declare function fileExistsWithinRoot(root: string, cited: string): boolean;
+/** The text of a file inside `root`, or undefined for anything else — outside the
+ *  checkout, absent, not a regular file, or past the cap. A caller cannot tell those
+ *  apart ON PURPOSE. `size` is 0 for a FIFO, so the byte cap is not enough:
+ *  `readFile` on one blocks until something writes and the tool never returns. */
+export declare function readFileWithinRoot(root: string, candidate: string, maxBytes: number): string | undefined;
+/** The real paths of a run's checkouts, deduped. Every containment test compares
+ *  real paths, so a root has to be one: on macOS `os.tmpdir()` is a symlink, and
+ *  a raw root failed its own containment test for files really inside it. */
+export declare function realRootsOf(roots: Array<string | undefined>): string[];

package/build/utils/containedPath.js

@@ -0,0 +1,73 @@
+import fs from "fs";
+import path from "path";
+/** Resolve and read a path an AGENT wrote, without leaving the checkout. ONE
+ *  implementation for every such reader: an escape closed in one and left open in
+ *  another is the same hole. */
+/** `candidate` resolved against `root`, or undefined when the real target is not
+ *  inside `root`. `root` must already be a real path, or a symlinked checkout fails
+ *  its own containment test. */
+export function resolveWithinRoot(root, candidate) {
+    try {
+        // `path.resolve` returns an absolute candidate unchanged and a
+        // drive-relative one as written, so neither is silently joined to the root;
+        // the containment test below is what rejects them.
+        const real = fs.realpathSync(path.resolve(root, candidate));
+        if (real !== root && !real.startsWith(root + path.sep))
+            return undefined;
+        return real;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Whether `cited` names a real FILE inside `root`. */
+export function fileExistsWithinRoot(root, cited) {
+    const real = resolveWithinRoot(root, cited);
+    if (!real)
+        return false;
+    try {
+        // A directory is not a file that defines a route, and `realpathSync` has
+        // already followed every symlink, so this is the real target's kind.
+        return fs.statSync(real).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** The text of a file inside `root`, or undefined for anything else — outside the
+ *  checkout, absent, not a regular file, or past the cap. A caller cannot tell those
+ *  apart ON PURPOSE. `size` is 0 for a FIFO, so the byte cap is not enough:
+ *  `readFile` on one blocks until something writes and the tool never returns. */
+export function readFileWithinRoot(root, candidate, maxBytes) {
+    const real = resolveWithinRoot(root, candidate);
+    if (!real)
+        return undefined;
+    try {
+        const stat = fs.statSync(real);
+        if (!stat.isFile() || stat.size > maxBytes)
+            return undefined;
+        return fs.readFileSync(real, "utf-8");
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The real paths of a run's checkouts, deduped. Every containment test compares
+ *  real paths, so a root has to be one: on macOS `os.tmpdir()` is a symlink, and
+ *  a raw root failed its own containment test for files really inside it. */
+export function realRootsOf(roots) {
+    const real = [];
+    for (const root of roots) {
+        if (!root || root === "unknown")
+            continue;
+        try {
+            const resolved = fs.realpathSync(root);
+            if (!real.includes(resolved))
+                real.push(resolved);
+        }
+        catch {
+            // A checkout path that no longer resolves holds no readable file.
+        }
+    }
+    return real;
+}