xcoder-dna 0.0.0-stage → 1.3.0

package/dist/tools/git-tools.js

@@ -0,0 +1,348 @@
+// xcoder:version 9 | xcoder:task task-e6370a | xcoder:updated 2026-08-12T16:55:07.172Z | xcoder:subtask code-st-cd4444
+import { execFile } from "node:child_process";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { resolveInWorkspace } from "./patch-tools.js";
+import { upsertEntry } from "./workspace-index.js";
+import { truncateOutput } from "./fs-tools.js";
+import { getCommentSyntax, injectVersionHeader, } from "./file-header-manager.js";
+import { incrementFileVersion } from "../store/file-version-store.js";
+function run(cmd, args, cwd) {
+    return new Promise((resolve) => {
+        execFile(cmd, args, { cwd, maxBuffer: 10 * 1024 * 1024, timeout: 60_000 }, (error, stdout, stderr) => {
+            resolve({ ok: !error, stdout, stderr });
+        });
+    });
+}
+/**
+ * Walks up from `startDir` looking for a `.git` directory. Returns the repo
+ * root or null. Mirrors the findUp pattern used for repo pinning elsewhere.
+ */
+async function findGitRoot(startDir) {
+    let dir = startDir;
+    for (let i = 0; i < 20; i++) {
+        try {
+            await fs.access(path.join(dir, ".git"));
+            return dir;
+        }
+        catch {
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                return null;
+            dir = parent;
+        }
+    }
+    return null;
+}
+const STAT_LINE_RE = /^\s*(\S+)\s+\|\s+(\d+)\s+([+\-*]+)?\s*$/;
+/**
+ * Low-token diff summary by default (`git diff --stat`). Pass `rawDiff: true`
+ * to get the full unified diff (still capped by truncation). Summary-first is
+ * the cheapest-first default (T5).
+ */
+export async function gitDiffTool(root, input = {}) {
+    const cwd = path.resolve(root);
+    const repoRoot = await findGitRoot(cwd);
+    if (!repoRoot) {
+        return {
+            ok: false,
+            code: "not_a_git_repo",
+            error: `no git repository found from "${root}" upward — git_diff works inside a git repo. Use git_log/read_file/read_outline on the workspace files instead.`,
+        };
+    }
+    const args = [];
+    if (input.rawDiff) {
+        args.push("diff");
+        if (input.ref && input.ref.trim() !== "")
+            args.push(input.ref);
+        if (input.path && input.path.trim() !== "") {
+            args.push("--", input.path.replace(/\\/g, "/"));
+        }
+    }
+    else {
+        args.push("diff", "--stat");
+        if (input.ref && input.ref.trim() !== "")
+            args.push(input.ref);
+        if (input.path && input.path.trim() !== "") {
+            args.push("--", input.path.replace(/\\/g, "/"));
+        }
+    }
+    const res = await run("git", args, repoRoot);
+    if (!res.ok) {
+        return { ok: false, code: "git_error", error: `git ${args[0]} failed: ${res.stderr.trim() || "unknown git error"}`, stderr: res.stderr };
+    }
+    const raw = res.stdout;
+    if (input.rawDiff) {
+        const capped = truncateOutput(raw, 4000);
+        return {
+            ok: true,
+            summary: capped.text.includes("\n") ? capped.text.split("\n")[0] : capped.text,
+            entries: [],
+            hasDiff: raw.trim() !== "",
+            statsOnly: false,
+            rawDiff: capped.text,
+            note: capped.truncated ? capped.note : undefined,
+        };
+    }
+    // Parse the --stat output into entries.
+    const lines = raw.split("\n");
+    const entries = [];
+    const dirs = new Set();
+    for (const line of lines) {
+        if (line.trim() === "" || line.includes("files changed") || line.includes("file changed"))
+            continue;
+        const m = STAT_LINE_RE.exec(line);
+        if (m) {
+            const file = m[1].replace(/\|.*$/, "").trim();
+            const added = (m[3]?.match(/\+/g) ?? []).length;
+            const removed = (m[3]?.match(/-/g) ?? []).length;
+            const status = line.includes("|") ? "modified" : "modified";
+            entries.push({ file, added, removed, status });
+        }
+        else if (/^\s*\S+\s*\|/.test(line)) {
+            // A path with a rename `->` or a mode-change line — best-effort capture.
+            const file = line.split("|")[0].trim();
+            if (file && !file.startsWith(" "))
+                entries.push({ file, added: 0, removed: 0, status: "renamed" });
+        }
+        else if (/^\s*[A-Za-z]:\\.*/.test(line) || line.trim().startsWith("dev/")) {
+            dirs.add(line.trim());
+        }
+    }
+    const capped = truncateOutput(raw, 4000);
+    return {
+        ok: true,
+        summary: capped.text,
+        entries,
+        hasDiff: raw.trim() !== "",
+        statsOnly: true,
+        note: capped.truncated ? capped.note : undefined,
+    };
+}
+export async function gitLogTool(root, input) {
+    const cwd = path.resolve(root);
+    const repoRoot = await findGitRoot(cwd);
+    if (!repoRoot) {
+        return {
+            ok: false,
+            code: "not_a_git_repo",
+            error: `no git repository found from "${root}" upward — git_log works inside a git repo. Use read_file/read_outline on the workspace files instead.`,
+        };
+    }
+    const maxCount = Math.min(Math.max(1, input.maxCount ?? 10), 100);
+    const args = [
+        "log",
+        `--max-count=${maxCount}`,
+        "--format=%H|%h|%an|%ad|%s",
+        "--date=short",
+    ];
+    if (input.path && input.path.trim() !== "") {
+        args.push("--", input.path.replace(/\\/g, "/"));
+    }
+    const res = await run("git", args, repoRoot);
+    if (!res.ok) {
+        return { ok: false, code: "git_error", error: `git log failed: ${res.stderr.trim() || "unknown git error"}`, stderr: res.stderr };
+    }
+    const commits = res.stdout
+        .split("\n")
+        .filter((l) => l.trim() !== "")
+        .map((l) => {
+        const [hash, shortHash, author, date, ...subjectParts] = l.split("|");
+        return { hash, shortHash, author, date, subject: subjectParts.join("|") };
+    });
+    const result = {
+        ok: true,
+        commits: commits.slice(0, maxCount),
+        truncated: commits.length > maxCount || commits.length === 0 ? false : commits.length === maxCount,
+    };
+    if (result.truncated && commits.length > maxCount) {
+        result.truncationNote = `showing the most recent ${maxCount} commits — pass a larger "maxCount" (up to 100) for more.`;
+    }
+    return result;
+}
+/**
+ * Applies a unified diff to a single file. Inside a git repo this uses
+ * `git apply --check` (zero-writes on failure, full check output returned)
+ * then `git apply`. Outside a repo it falls back to a small JS hunk parser
+ * that splices the same way `line_patch` does (cross-platform — no `patch`
+ * binary dependency).
+ */
+export async function applyUnifiedDiffTool(root, input, ctx) {
+    let full;
+    try {
+        full = resolveInWorkspace(root, input.path);
+    }
+    catch (e) {
+        return { ok: false, error: e.message, code: "workspace_escape" };
+    }
+    let content;
+    try {
+        content = await fs.readFile(full, "utf8");
+    }
+    catch {
+        return {
+            ok: false,
+            code: "file_not_found",
+            error: `"${input.path}" doesn't exist or can't be read. Use write_file to create it first.`,
+        };
+    }
+    const repoRoot = await findGitRoot(path.dirname(full));
+    if (repoRoot) {
+        // Work via a temp file so `git apply --check` (zero writes on failure) and
+        // `git apply` both read the exact same bytes. Do NOT use `-` as the patch
+        // path without piping stdin — execFile would leave git waiting on the pipe.
+        const tmp = path.join(repoRoot, ".xcoder", `tmp-apply-${Date.now()}.diff`);
+        await fs.mkdir(path.dirname(tmp), { recursive: true });
+        await fs.writeFile(tmp, input.diff, "utf8");
+        try {
+            const checkRes = await run("git", ["apply", "--check", path.relative(repoRoot, tmp)], repoRoot);
+            if (!checkRes.ok) {
+                return {
+                    ok: false,
+                    code: "diff_check_failed",
+                    error: `git apply --check rejected the diff — no changes were written. Fix the diff or re-read the file and regenerate it.`,
+                    checkOutput: checkRes.stderr.trim() || checkRes.stdout.trim(),
+                };
+            }
+            const applyRes = await run("git", ["apply", path.relative(repoRoot, tmp)], repoRoot);
+            if (!applyRes.ok) {
+                return { ok: false, code: "diff_apply_failed", error: `git apply failed: ${applyRes.stderr.trim() || "unknown error"}` };
+            }
+        }
+        finally {
+            await fs.rm(tmp, { force: true }).catch(() => undefined);
+        }
+        // Header injection + index refresh after git apply (ctx-aware).
+        let finalContent;
+        try {
+            finalContent = await fs.readFile(full, "utf8");
+        }
+        catch {
+            return { ok: false, code: "diff_apply_failed", error: "file unreadable after apply" };
+        }
+        let next = finalContent;
+        if (ctx) {
+            const syntax = getCommentSyntax(input.path);
+            if (syntax) {
+                const meta = await incrementFileVersion(root, input.path, ctx.taskId, ctx.subtaskId);
+                const injected = injectVersionHeader(next, syntax, meta);
+                next = injected.content;
+                await fs.writeFile(full, next, "utf8");
+            }
+        }
+        await upsertEntry(root, path.relative(root, full));
+        const sha1After = await (await import("./patch-tools.js")).hashFile(full);
+        const hunks = (input.diff.match(/^@@/gm) ?? []).length;
+        const changes = (input.diff.match(/^[+-](?![+-])/gm) ?? []).length;
+        return {
+            ok: true,
+            relPath: path.relative(root, full).split(path.sep).join("/"),
+            hunksApplied: hunks,
+            linesChanged: changes,
+            sha1After,
+        };
+    }
+    // ── Non-repo fallback: JS hunk parser + line splice ──
+    const parsed = parseUnifiedDiff(input.diff);
+    if (!parsed.ok)
+        return { ok: false, code: "no_diff_hunks", error: parsed.error, checkOutput: undefined };
+    const lines = content.split("\n");
+    let changed = 0;
+    // Apply hunks bottom-up against ORIGINAL line numbers so earlier hunks
+    // don't shift the coordinates of later ones.
+    const sortedHunks = [...parsed.hunks].sort((a, b) => b.oldStart - a.oldStart);
+    for (const hunk of sortedHunks) {
+        if (hunk.oldCount > 0) {
+            const end = hunk.oldStart + hunk.oldCount - 1;
+            if (hunk.oldStart < 1 || end > lines.length) {
+                return {
+                    ok: false,
+                    code: "no_diff_hunks",
+                    error: `hunk covers old lines ${hunk.oldStart}..${end}, but the file only has ${lines.length} lines — the diff is stale.`,
+                };
+            }
+        }
+        else if (hunk.oldStart !== 0 && (hunk.oldStart < 1 || hunk.oldStart > lines.length + 1)) {
+            return {
+                ok: false,
+                code: "no_diff_hunks",
+                error: `insert hunk at line ${hunk.oldStart} is outside the file's ${lines.length} lines — the diff is stale.`,
+            };
+        }
+        const before = lines.slice(0, hunk.oldStart === 0 ? 0 : hunk.oldStart - 1);
+        const after = lines.slice(hunk.oldStart === 0 ? 0 : hunk.oldStart - 1 + hunk.oldCount);
+        lines.length = 0;
+        lines.push(...before, ...hunk.lines, ...after);
+        changed += hunk.addedCount + hunk.removedCount;
+    }
+    let next = lines.join("\n");
+    if (ctx) {
+        const syntax = getCommentSyntax(input.path);
+        if (syntax) {
+            const meta = await incrementFileVersion(root, input.path, ctx.taskId, ctx.subtaskId);
+            const injected = injectVersionHeader(next, syntax, meta);
+            next = injected.content;
+        }
+    }
+    try {
+        await fs.writeFile(full, next, "utf8");
+        await upsertEntry(root, path.relative(root, full));
+        const sha1After = await (await import("./patch-tools.js")).hashFile(full);
+        return {
+            ok: true,
+            relPath: path.relative(root, full).split(path.sep).join("/"),
+            hunksApplied: parsed.hunks.length,
+            linesChanged: changed,
+            sha1After,
+        };
+    }
+    catch (e) {
+        return { ok: false, code: "diff_apply_failed", error: e.message };
+    }
+}
+/** Minimal unified-diff parser for a single file: `@@ -a,b +c,d @@` + ` `, `+`, `-` lines. */
+function parseUnifiedDiff(diff) {
+    const hunks = [];
+    let current = null;
+    for (const rawLine of diff.split("\n")) {
+        const line = rawLine.replace(/\r$/, "");
+        const hunkHeader = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/.exec(line);
+        if (hunkHeader) {
+            if (current)
+                hunks.push(current);
+            const oldStart = Number(hunkHeader[1]);
+            const oldCount = hunkHeader[2] === undefined ? 1 : Number(hunkHeader[2]);
+            const newStart = Number(hunkHeader[3]);
+            current = {
+                oldStart,
+                oldCount,
+                newStart,
+                lines: [],
+                addedCount: 0,
+                removedCount: 0,
+            };
+            continue;
+        }
+        if (!current)
+            continue;
+        if (line.startsWith("+")) {
+            current.lines.push(line.slice(1));
+            current.addedCount++;
+        }
+        else if (line.startsWith("-")) {
+            // Removed lines are NOT copied into the replacement; they are covered by
+            // the old-side splice extent (oldStart + oldCount).
+            current.removedCount++;
+        }
+        else if (line.startsWith(" ")) {
+            current.lines.push(line.slice(1));
+        }
+        // '\' and 'diff --git' header lines are ignored.
+    }
+    if (current)
+        hunks.push(current);
+    if (hunks.length === 0) {
+        return { ok: false, error: "no hunks found — the diff must contain @@ hunk headers" };
+    }
+    return { ok: true, hunks };
+}

package/dist/tools/github-tool.d.ts

@@ -0,0 +1,48 @@
+export interface GithubCreateRepoInput {
+    name: string;
+    description?: string;
+    private?: boolean;
+    org?: string;
+    credentialRef?: string;
+}
+export interface GithubCreateRepoResult {
+    ok: boolean;
+    detail: string;
+    cloneUrl?: string;
+    htmlUrl?: string;
+}
+export declare function githubCreateRepo(input: GithubCreateRepoInput): Promise<GithubCreateRepoResult>;
+export interface GithubCloneInput {
+    url: string;
+    dir: string;
+    credentialRef?: string;
+}
+export declare function githubClone(root: string, input: GithubCloneInput): Promise<{
+    ok: boolean;
+    detail: string;
+}>;
+export interface GithubCommitInput {
+    cwd?: string;
+    message: string;
+    addAll?: boolean;
+}
+export declare function githubCommit(root: string, input: GithubCommitInput): Promise<{
+    ok: boolean;
+    detail: string;
+}>;
+export interface GithubPushInput {
+    cwd?: string;
+    remote?: string;
+    branch?: string;
+    credentialRef?: string;
+}
+/**
+ * The token is embedded into the remote URL only for the duration of this
+ * one push, then the original URL is restored — it is never left sitting
+ * in `.git/config`, and it's redacted out of any error text before this
+ * function returns.
+ */
+export declare function githubPush(root: string, input: GithubPushInput): Promise<{
+    ok: boolean;
+    detail: string;
+}>;

package/dist/tools/github-tool.js

@@ -0,0 +1,147 @@
+import { execFile } from "node:child_process";
+import path from "node:path";
+import { resolveCredential, redact } from "./credential.js";
+function run(cmd, args, cwd) {
+    return new Promise((resolve) => {
+        execFile(cmd, args, { cwd, maxBuffer: 10 * 1024 * 1024 }, (error, stdout, stderr) => {
+            resolve({ ok: !error, stdout, stderr });
+        });
+    });
+}
+function resolveInWorkspace(root, relDir) {
+    const full = path.resolve(root, relDir ?? ".");
+    const normalizedRoot = path.resolve(root) + path.sep;
+    if (full + path.sep !== normalizedRoot && !full.startsWith(normalizedRoot)) {
+        throw new Error(`"${relDir}" resolves outside the workspace root — refusing.`);
+    }
+    return full;
+}
+/** Embeds a token into an https remote URL only for the duration of one git invocation. */
+function withEmbeddedToken(url, token) {
+    if (!url.startsWith("https://"))
+        return url; // ssh remotes use the user's own key, nothing to embed
+    return url.replace("https://", `https://x-access-token:${token}@`);
+}
+export async function githubCreateRepo(input) {
+    const ref = input.credentialRef ?? "GITHUB_TOKEN";
+    let token;
+    try {
+        token = resolveCredential(ref);
+    }
+    catch (e) {
+        return { ok: false, detail: e.message };
+    }
+    const endpoint = input.org
+        ? `https://api.github.com/orgs/${input.org}/repos`
+        : `https://api.github.com/user/repos`;
+    try {
+        const res = await fetch(endpoint, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${token}`,
+                Accept: "application/vnd.github+json",
+                "X-GitHub-Api-Version": "2022-11-28",
+                "User-Agent": "xcoder-sdlc-cli",
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                name: input.name,
+                description: input.description,
+                private: input.private ?? true,
+            }),
+        });
+        const body = (await res.json());
+        if (!res.ok) {
+            return { ok: false, detail: redact(`GitHub API ${res.status}: ${body.message ?? "unknown error"}`, ref) };
+        }
+        return {
+            ok: true,
+            detail: `created ${body.html_url}`,
+            cloneUrl: body.clone_url,
+            htmlUrl: body.html_url,
+        };
+    }
+    catch (e) {
+        return { ok: false, detail: redact(`request failed: ${e.message}`, ref) };
+    }
+}
+export async function githubClone(root, input) {
+    let full;
+    try {
+        full = resolveInWorkspace(root, input.dir);
+    }
+    catch (e) {
+        return { ok: false, detail: e.message };
+    }
+    let cloneUrl = input.url;
+    const ref = input.credentialRef;
+    if (ref) {
+        try {
+            cloneUrl = withEmbeddedToken(input.url, resolveCredential(ref));
+        }
+        catch (e) {
+            return { ok: false, detail: e.message };
+        }
+    }
+    const result = await run("git", ["clone", cloneUrl, full], path.dirname(full));
+    return {
+        ok: result.ok,
+        detail: redact(result.ok ? `cloned into ${input.dir}` : result.stderr.trim(), ref),
+    };
+}
+export async function githubCommit(root, input) {
+    let full;
+    try {
+        full = resolveInWorkspace(root, input.cwd);
+    }
+    catch (e) {
+        return { ok: false, detail: e.message };
+    }
+    if (input.addAll ?? true) {
+        const add = await run("git", ["add", "-A"], full);
+        if (!add.ok)
+            return { ok: false, detail: `git add failed: ${add.stderr.trim()}` };
+    }
+    const commit = await run("git", ["commit", "-m", input.message], full);
+    return { ok: commit.ok, detail: commit.ok ? commit.stdout.trim() : commit.stderr.trim() };
+}
+/**
+ * The token is embedded into the remote URL only for the duration of this
+ * one push, then the original URL is restored — it is never left sitting
+ * in `.git/config`, and it's redacted out of any error text before this
+ * function returns.
+ */
+export async function githubPush(root, input) {
+    let full;
+    try {
+        full = resolveInWorkspace(root, input.cwd);
+    }
+    catch (e) {
+        return { ok: false, detail: e.message };
+    }
+    const remote = input.remote ?? "origin";
+    const ref = input.credentialRef ?? "GITHUB_TOKEN";
+    const getUrl = await run("git", ["remote", "get-url", remote], full);
+    if (!getUrl.ok)
+        return { ok: false, detail: `could not resolve remote "${remote}": ${getUrl.stderr.trim()}` };
+    const originalUrl = getUrl.stdout.trim();
+    let token;
+    try {
+        token = resolveCredential(ref);
+    }
+    catch (e) {
+        return { ok: false, detail: e.message };
+    }
+    const authedUrl = withEmbeddedToken(originalUrl, token);
+    try {
+        await run("git", ["remote", "set-url", remote, authedUrl], full);
+        const args = ["push", remote];
+        if (input.branch)
+            args.push(input.branch);
+        const push = await run("git", args, full);
+        return { ok: push.ok, detail: redact(push.ok ? push.stdout.trim() || "pushed" : push.stderr.trim(), ref) };
+    }
+    finally {
+        await run("git", ["remote", "set-url", remote, originalUrl], full); // always restore, even on failure
+    }
+}

package/dist/tools/globTool.d.ts

@@ -0,0 +1,20 @@
+import type { WorkspaceIndex } from "./workspace-index.js";
+export interface GlobToolOptions {
+    /**
+     * A pre-gated index to answer from. Long-running callers (the orchestrator,
+     * grep) pass this so one freshness probe serves many lookups.
+     */
+    index?: WorkspaceIndex;
+    /** Workspace root the index describes. Defaults to `cwd`. */
+    root?: string;
+    /** Maximum number of results. */
+    limit?: number;
+}
+/**
+ * Match `pattern` against the workspace index.
+ *
+ * The first two parameters are unchanged from the previous real-FS
+ * implementation, so existing call sites keep working — they simply get
+ * index-backed answers instead of a directory walk.
+ */
+export declare function globTool(pattern: string, cwd?: string, opts?: GlobToolOptions): Promise<string[]>;

package/dist/tools/globTool.js

@@ -0,0 +1,34 @@
+// xcoder:version 1 | xcoder:task task-e16f85 | xcoder:updated 2026-10-30T18:14:11.042Z | xcoder:subtask code-st-791be4
+// Glob, answered by the workspace index and nothing else.
+//
+// This module used to call `tinyglobby` directly, which meant `glob` walked the
+// real filesystem and could disagree with the index about which files exist —
+// the two answers came from two different sources. Deleting that import is
+// deliberate: there is now no code path in this module that can enumerate the
+// filesystem, so "glob is index-backed" is enforced rather than promised.
+//
+// Consequences, stated plainly: files excluded from the index are excluded
+// here too — files over `MAX_INDEXED_FILE_BYTES`, dotfiles/dotdirs, and
+// anything under `IGNORE_DIRS` (node_modules, dist, .git, .xcoder, …). Results
+// are therefore a strict subset of the old behaviour. That inconsistency was
+// itself the bug: every other discovery tool already treated the index as the
+// source of truth, so glob returning files the index denied merely moved the
+// disagreement downstream.
+import { loadIgnoreRules } from "../indexing/ignoreRules.js";
+import { globIndex } from "./index-glob.js";
+import { ensureFreshIndex } from "./index-freshness.js";
+/**
+ * Match `pattern` against the workspace index.
+ *
+ * The first two parameters are unchanged from the previous real-FS
+ * implementation, so existing call sites keep working — they simply get
+ * index-backed answers instead of a directory walk.
+ */
+export async function globTool(pattern, cwd = process.cwd(), opts = {}) {
+    const root = opts.root ?? cwd;
+    const index = opts.index ?? (await ensureFreshIndex(root)).index;
+    return globIndex(index, pattern, {
+        ignore: loadIgnoreRules(root),
+        limit: opts.limit,
+    });
+}

package/dist/tools/grepTool.d.ts

@@ -0,0 +1,19 @@
+import type { WorkspaceIndex } from "./workspace-index.js";
+export interface GrepMatch {
+    file: string;
+    line: number;
+    text: string;
+}
+export interface GrepOptions {
+    /** Number of surrounding context lines to include around each match (default 0). */
+    contextLines?: number;
+    /**
+     * Pre-gated index supplying the candidate file set. When omitted, `globTool`
+     * gates one for this call. Either way the *selection* of files is
+     * index-authoritative; only their bytes are read from disk.
+     */
+    index?: WorkspaceIndex;
+    /** Workspace root the index describes. Defaults to `cwd`. */
+    root?: string;
+}
+export declare function grepTool(regex: string, globPattern?: string, cwd?: string, opts?: GrepOptions): Promise<GrepMatch[]>;

package/dist/tools/grepTool.js

@@ -0,0 +1,44 @@
+// xcoder:version 4 | xcoder:task task-e16f85 | xcoder:updated 2026-10-30T18:14:23.512Z | xcoder:subtask code-st-791be4
+import fs from "node:fs";
+import path from "node:path";
+import { globTool } from "./globTool.js";
+import { MAX_INDEXED_FILE_BYTES } from "./workspace-index.js";
+export async function grepTool(regex, globPattern = "**/*", cwd = process.cwd(), opts) {
+    const root = opts?.root ?? cwd;
+    // Selection is index-authoritative; content still comes from disk.
+    const files = await globTool(globPattern, root, { index: opts?.index, root });
+    const re = new RegExp(regex);
+    const context = Math.max(0, opts?.contextLines ?? 0);
+    const matches = [];
+    for (const file of files) {
+        const full = path.join(root, file);
+        let content;
+        try {
+            // The index already excludes these, but a caller may hand us an index
+            // built elsewhere — never read an unbounded file into memory.
+            if (fs.statSync(full).size > MAX_INDEXED_FILE_BYTES)
+                continue;
+            content = fs.readFileSync(full, "utf-8");
+        }
+        catch {
+            continue; // binary or unreadable file — skip
+        }
+        const lines = content.split("\n");
+        lines.forEach((line, idx) => {
+            if (re.test(line)) {
+                matches.push({ file, line: idx + 1, text: line.trim() });
+                for (let c = 1; c <= context; c++) {
+                    const before = lines[idx - c];
+                    if (before !== undefined) {
+                        matches.push({ file, line: idx - c + 1, text: before.trim() });
+                    }
+                    const after = lines[idx + c];
+                    if (after !== undefined) {
+                        matches.push({ file, line: idx + c + 1, text: after.trim() });
+                    }
+                }
+            }
+        });
+    }
+    return matches;
+}