oakode 0.0.0-stage → 0.5.0

package/dist/fileio.js

@@ -0,0 +1,688 @@
+/** Workspace-confined file helpers: path safety, text decoding (BOM/CRLF), edit application, atomic writes, grep, ls. */
+import { closeSync, existsSync, fsyncSync, lstatSync, openSync, readFileSync, readSync, readdirSync, readlinkSync, realpathSync, statSync, unlinkSync, writeSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { renameRetry } from "./config.js";
+import { execFile } from "node:child_process";
+import { diffArrays } from "diff";
+import { promisify } from "node:util";
+import { basename, delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+export class ToolError extends Error {
+}
+export const MAX_LINES = 2000;
+export const MAX_BYTES = 50 * 1024;
+const MAX_TEXT_FILE = 5 * 1024 * 1024;
+// ---------------------------------------------------------------- paths
+/** Resolve `p` against cwd; refuse anything (including via symlinks) that lands outside it. */
+export function safePath(cwd, p) {
+    if (typeof p !== "string" || !p)
+        throw new ToolError("`path` must be a non-empty string");
+    if (p.includes("\0"))
+        throw new ToolError("`path` contains a NUL byte");
+    const root = realpathSync(cwd);
+    const abs = resolve(root, p);
+    let probe = abs;
+    for (;;) {
+        try {
+            lstatSync(probe);
+            break;
+        }
+        catch {
+            const up = dirname(probe);
+            if (up === probe)
+                break;
+            probe = up;
+        }
+    }
+    let real;
+    try {
+        real = realpathSync(probe);
+    }
+    catch {
+        throw new ToolError(`Cannot resolve path (dangling symlink?): ${p}`);
+    }
+    if (real !== root && !real.startsWith(root.endsWith(sep) ? root : root + sep)) {
+        throw new ToolError(`Path is outside the working directory (${root}): ${p}`);
+    }
+    return abs;
+}
+/** Workspace-relative path as the model and the user see it: forward slashes on every platform. */
+export const rel = (cwd, abs) => relative(cwd, abs).split(sep).join("/") || ".";
+/**
+ * The workspace-relative path of the file a write would really reach: symlinks in the existing part of the path are
+ * resolved (a committed `gitlink -> .git` makes `gitlink/config` really `.git/config`), the not-yet-existing rest is
+ * appended as written. Permission decisions use this, never the spelling the model chose.
+ */
+export function realRel(cwd, abs) {
+    const root = realpathSync(cwd);
+    const rest = [];
+    let probe = abs;
+    for (;;) {
+        try {
+            return rel(root, join(realpathSync(probe), ...rest.reverse()));
+        }
+        catch {
+            const up = dirname(probe);
+            if (up === probe)
+                return rel(cwd, abs);
+            rest.push(basename(probe));
+            probe = up;
+        }
+    }
+}
+/** Only regular files: reading a FIFO or device inside the workspace would hang or misbehave. */
+export function requireFile(p, shown) {
+    const st = statSync(p);
+    if (st.isDirectory())
+        throw new ToolError(`${shown} is a directory; use the ls tool.`);
+    if (!st.isFile())
+        throw new ToolError(`${shown} is not a regular file`);
+}
+export function optInt(v, name, max = Infinity) {
+    if (v === undefined || v === null)
+        return undefined;
+    if (typeof v !== "number" || !Number.isInteger(v) || v < 1 || v > max)
+        throw new ToolError(`\`${name}\` must be a positive integer${max === Infinity ? "" : ` up to ${max}`}`);
+    return v;
+}
+/** Keep the head (for files) or tail (for command output) within line/byte limits. */
+export function truncate(text, from, maxBytes = MAX_BYTES) {
+    let lines = text.split("\n");
+    let truncated = false;
+    if (lines.length > MAX_LINES) {
+        lines = from === "head" ? lines.slice(0, MAX_LINES) : lines.slice(-MAX_LINES);
+        truncated = true;
+    }
+    let out = lines.join("\n");
+    if (Buffer.byteLength(out) > maxBytes) {
+        const buf = Buffer.from(out);
+        out = from === "head" ? buf.subarray(0, maxBytes).toString() : buf.subarray(buf.length - maxBytes).toString();
+        truncated = true;
+    }
+    return { text: out, truncated };
+}
+export function readTextFile(path, shown, opts = {}) {
+    const buf = readFileSync(path);
+    if (buf.length > MAX_TEXT_FILE)
+        throw new ToolError(`${shown} is too large (${buf.length} bytes; limit ${MAX_TEXT_FILE}).`);
+    if (buf.subarray(0, 8192).includes(0))
+        throw new ToolError(`${shown} looks like a binary file (${buf.length} bytes).`);
+    const bom = buf.length >= 3 && buf[0] === 0xef && buf[1] === 0xbb && buf[2] === 0xbf;
+    let raw;
+    try {
+        raw = new TextDecoder("utf-8", { fatal: !!opts.strict }).decode(bom ? buf.subarray(3) : buf);
+    }
+    catch {
+        throw new ToolError(`${shown} is not valid UTF-8; refusing to modify it (that would corrupt it).`);
+    }
+    const crlf = (raw.match(/\r\n/g) ?? []).length;
+    const lf = (raw.match(/(?<!\r)\n/g) ?? []).length;
+    return { text: raw.replace(/\r\n/g, "\n"), bom, eol: crlf > lf ? "\r\n" : "\n", mixed: crlf > 0 && lf > 0 };
+}
+/** Encode \n-normalized text with the BOM and line endings of the file it replaces. */
+export function encodeLike(orig, text) {
+    let out = text.replace(/\r\n/g, "\n");
+    if (orig?.eol === "\r\n")
+        out = out.replace(/\n/g, "\r\n");
+    return orig?.bom && !out.startsWith("") ? "" + out : out;
+}
+/** Write via a temp file in the same directory + rename, preserving mode and following (in-workspace) symlinks. */
+export function atomicWrite(target, data) {
+    const real = existsSync(target) ? realpathSync(target) : target;
+    const mode = existsSync(real) ? statSync(real).mode & 0o7777 : 0o666;
+    const tmp = join(dirname(real), `.${basename(real)}.oakode-${process.pid}-${randomBytes(3).toString("hex")}.tmp`);
+    let fd;
+    try {
+        fd = openSync(tmp, "wx", mode);
+        writeSync(fd, data);
+        fsyncSync(fd);
+        closeSync(fd);
+        fd = undefined;
+        renameRetry(tmp, real);
+    }
+    catch (e) {
+        if (fd !== undefined)
+            try {
+                closeSync(fd);
+            }
+            catch { }
+        try {
+            unlinkSync(tmp);
+        }
+        catch { }
+        throw e;
+    }
+}
+const QUOTES = /[‘’‚‛]/g;
+const DQUOTES = /[“”„‟]/g;
+const DASHES = /[‐-―−]/g;
+const SPACES = /[  -   　]/g;
+const foldChar = (c) => c.replace(QUOTES, "'").replace(DQUOTES, '"').replace(DASHES, "-").replace(SPACES, " ");
+/** Whitespace/typography-tolerant view of `text`: trailing blanks per line removed, smart quotes/dashes folded. Keeps an index map back. */
+function fold(text) {
+    let s = "";
+    const map = [];
+    let ls = 0;
+    while (ls <= text.length) {
+        let le = text.indexOf("\n", ls);
+        if (le < 0)
+            le = text.length;
+        let te = le;
+        while (te > ls && (text[te - 1] === " " || text[te - 1] === "\t"))
+            te--;
+        for (let i = ls; i < te; i++) {
+            s += foldChar(text[i]);
+            map.push(i);
+        }
+        if (le < text.length) {
+            s += "\n";
+            map.push(le);
+        }
+        ls = le + 1;
+    }
+    map.push(text.length);
+    return { s, map };
+}
+const lineOf = (text, idx) => text.slice(0, idx).split("\n").length;
+function allIndexes(hay, needle) {
+    const out = [];
+    for (let i = hay.indexOf(needle); i >= 0; i = hay.indexOf(needle, i + needle.length))
+        out.push(i);
+    return out;
+}
+/**
+ * After a tolerant match, the replacement for the matched file text `orig`: lines the model kept unchanged (equal in
+ * old_text and new_text) are taken from the FILE, not from the model, so its quotes, dashes, odd spaces and trailing
+ * whitespace survive; only the lines the model actually changed come from new_text. Falls back to new_text verbatim
+ * when the lines cannot be aligned.
+ */
+function keepUnchangedLines(orig, old, neu) {
+    const o = orig.split("\n"), a = old.split("\n"), b = neu.split("\n");
+    if (o.length !== a.length)
+        return neu;
+    const out = [];
+    let ai = 0;
+    for (const part of diffArrays(a, b)) {
+        if (part.added)
+            out.push(...part.value);
+        else if (part.removed)
+            ai += part.count ?? part.value.length;
+        else
+            for (let k = 0; k < part.value.length; k++)
+                out.push(o[ai++]);
+    }
+    return out.join("\n");
+}
+/** Apply edits; every `old_text` is located in the ORIGINAL text, and none may overlap. */
+export function applyEdits(text, edits) {
+    if (!Array.isArray(edits) || !edits.length)
+        throw new ToolError("`edits` must be a non-empty array");
+    if (edits.length > 50)
+        throw new ToolError("At most 50 edits per call");
+    let folded;
+    const ranges = [];
+    const notes = [];
+    edits.forEach((e, k) => {
+        const n = k + 1;
+        const tag = edits.length > 1 ? `edit #${n}: ` : "";
+        if (!e || typeof e.old_text !== "string" || typeof e.new_text !== "string")
+            throw new ToolError(`${tag}\`old_text\` and \`new_text\` must be strings`);
+        const old = e.old_text.replace(/\r\n/g, "\n");
+        const neu = e.new_text.replace(/\r\n/g, "\n");
+        if (!old)
+            throw new ToolError(`${tag}\`old_text\` must not be empty`);
+        if (old === neu)
+            throw new ToolError(`${tag}\`old_text\` and \`new_text\` are identical`);
+        let found = allIndexes(text, old).map((i) => ({ start: i, end: i + old.length }));
+        let fuzzy = false;
+        if (!found.length) {
+            folded ??= fold(text);
+            const needle = fold(old).s;
+            found = needle ? allIndexes(folded.s, needle).map((i) => ({ start: folded.map[i], end: folded.map[i + needle.length - 1] + 1 })) : [];
+            fuzzy = found.length > 0;
+        }
+        if (!found.length)
+            throw new ToolError(`${tag}old_text not found.${notFound(text, old)}`);
+        if (found.length > 1 && !e.replace_all) {
+            const lines = found.slice(0, 5).map((f) => lineOf(text, f.start)).join(", ");
+            throw new ToolError(`${tag}old_text matches ${found.length} places (lines ${lines}${found.length > 5 ? ", …" : ""}). Add surrounding context to make it unique, or set replace_all.`);
+        }
+        if (fuzzy)
+            notes.push(`${tag}matched ignoring trailing whitespace / quote and dash style; lines you did not change were kept as they are in the file`);
+        for (const f of found)
+            ranges.push({ ...f, neu: fuzzy ? keepUnchangedLines(text.slice(f.start, f.end), old, neu) : neu, i: n });
+    });
+    ranges.sort((a, b) => a.start - b.start || a.end - b.end);
+    for (let k = 1; k < ranges.length; k++) {
+        if (ranges[k].start < ranges[k - 1].end) {
+            throw new ToolError(`edit #${ranges[k - 1].i} and edit #${ranges[k].i} overlap; merge them into one edit.`);
+        }
+    }
+    let out = "";
+    let pos = 0;
+    let line = 1; // the line in `out` where the next replacement starts
+    const spans = [];
+    for (const r of ranges) {
+        const before = text.slice(pos, r.start);
+        line += before.split("\n").length - 1;
+        out += before + r.neu;
+        const n = r.neu.split("\n").length - 1;
+        spans.push({ from: line, to: line + n - (r.neu.endsWith("\n") && n > 0 ? 1 : 0) });
+        line += n;
+        pos = r.end;
+    }
+    out += text.slice(pos);
+    if (out === text)
+        throw new ToolError("The edits would not change the file.");
+    // one span per distinct place (replace_all can hit one line twice), never past the end of the new file
+    const last = out.split("\n").length;
+    const merged = [];
+    for (const x of spans.map((x) => ({ from: Math.min(x.from, last), to: Math.min(x.to, last) }))) {
+        const prev = merged.at(-1);
+        if (prev && x.from <= prev.to + 1)
+            prev.to = Math.max(prev.to, x.to);
+        else
+            merged.push(x);
+    }
+    return { text: out, replacements: ranges.length, notes, spans: merged };
+}
+/**
+ * Why old_text did not match, with the file's real lines where it should have (numbered, the first line that differs
+ * marked), so the next attempt can be fixed without reading the file again.
+ */
+function notFound(text, old) {
+    const want = old.replace(/\n$/, "").split("\n").slice(0, 200);
+    const have = text.split("\n");
+    const norm = (l) => foldChar(l).trim();
+    const w = want.map(norm);
+    const first = w.findIndex(Boolean);
+    if (first < 0)
+        return " re-read the file.";
+    // candidates: exact first-line matches first, then lines containing it; each scored once, over a bounded window
+    const exact = [], partial = [];
+    for (let i = 0; i < have.length && exact.length < 200; i++) {
+        const h = norm(have[i]);
+        if (h === w[first])
+            exact.push(i);
+        else if (partial.length < 200 && h.includes(w[first]))
+            partial.push(i);
+    }
+    const starts = exact.length ? exact : partial;
+    if (!starts.length)
+        return " Its first line does not appear in the file; re-read the file.";
+    const span = Math.min(want.length - first, 50);
+    const score = (s) => {
+        let n = 0;
+        for (let k = 0; k < span; k++)
+            if (norm(have[s + k] ?? "") === w[first + k])
+                n++;
+        return n;
+    };
+    let best = starts[0], bestScore = -1;
+    for (const s of starts) {
+        const sc = score(s);
+        if (sc > bestScore)
+            (best = s), (bestScore = sc);
+    }
+    const at = best - first;
+    const from = Math.max(0, at), to = Math.min(have.length, at + want.length + 2, from + 30);
+    const fold = (l) => foldChar(l).trimEnd();
+    const diff = want.findIndex((l, k) => fold(have[at + k] ?? "") !== fold(l));
+    const cut = (l) => (l.length > 300 ? l.slice(0, 300) + ` … (${l.length - 300} more chars)` : l);
+    const lines = have.slice(from, to).map((l, k) => `${from + k === at + diff ? "→" : " "}${String(from + k + 1).padStart(5)}\t${cut(l)}`);
+    return ` Its first line appears at line ${best + 1}, but the text after it differs. The file there (→ marks the first line that differs):\n${lines.join("\n")}\nMatch these lines exactly (no need to read the file again).`;
+}
+// ---------------------------------------------------------------- grep / ls (never follow symlinks)
+const SKIP_DIRS = new Set([".git", "node_modules", ".hg", ".svn"]);
+const MAX_GREP_FILE = 2 * 1024 * 1024;
+function globToRegExp(glob) {
+    let re = "";
+    for (let i = 0; i < glob.length; i++) {
+        const c = glob[i];
+        if (c === "*") {
+            if (glob[i + 1] === "*") {
+                i++;
+                if (glob[i + 1] === "/") {
+                    i++;
+                    re += "(?:.*/)?";
+                }
+                else
+                    re += ".*";
+            }
+            else
+                re += "[^/]*";
+        }
+        else if (c === "?")
+            re += "[^/]";
+        else if (c === "{") {
+            const end = glob.indexOf("}", i);
+            if (end < 0)
+                re += "\\{";
+            else {
+                re += "(?:" + glob.slice(i + 1, end).split(",").map((x) => x.replace(/[.+^$()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*")).join("|") + ")";
+                i = end;
+            }
+        }
+        else
+            re += c.replace(/[.+^$()|[\]\\}]/g, "\\$&");
+    }
+    return new RegExp("^" + re + "$");
+}
+const MAX_LISTED_FILES = 50_000;
+const execFileP = promisify(execFile);
+/**
+ * Files under `root` (absolute, sorted). In a git work tree this is `git ls-files` (tracked plus untracked files that
+ * .gitignore does not exclude), so build output and dependencies stay out of searches; elsewhere a plain walk that
+ * skips .git and node_modules. Symlinks are never listed or followed.
+ */
+export async function workspaceFiles(root, signal) {
+    const git = await gitFiles(root, signal);
+    return git ? { files: git, gitignore: true } : { files: walkFiles(root), gitignore: false };
+}
+/**
+ * An absolute path to a program from PATH, never one inside the workspace or from a relative PATH entry: on Windows a
+ * plain "git" would also run a git.exe sitting in the working directory, and `npm run` puts node_modules/.bin first.
+ */
+export function trustedExecutable(name, root) {
+    let ws;
+    try {
+        ws = realpathSync(root);
+    }
+    catch {
+        return undefined;
+    }
+    const names = process.platform === "win32" ? [`${name}.exe`] : [name];
+    for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+        if (!dir || !isAbsolute(dir))
+            continue;
+        for (const n of names) {
+            const cand = join(dir, n);
+            try {
+                const real = realpathSync(cand);
+                if (real === ws || real.startsWith(ws + sep) || !statSync(real).isFile())
+                    continue;
+                return cand;
+            }
+            catch { }
+        }
+    }
+    return undefined;
+}
+async function gitFiles(root, signal) {
+    const gitBin = trustedExecutable("git", root);
+    if (!gitBin)
+        return undefined;
+    let stdout;
+    try {
+        // A repository's own config must not run anything: fsmonitor is the one hook-like setting ls-files would honor.
+        ({ stdout } = await execFileP(gitBin, ["-c", "core.fsmonitor=false", "ls-files", "-z", "--cached", "--others", "--exclude-standard"], {
+            cwd: root,
+            signal,
+            timeout: 15_000,
+            maxBuffer: 64 * 1024 * 1024,
+            encoding: "utf8",
+            env: { ...Object.fromEntries(Object.entries(process.env).filter(([k]) => !/^(OICKI|OAKODE)_/i.test(k))), GIT_OPTIONAL_LOCKS: "0" },
+        }));
+    }
+    catch {
+        if (signal.aborted)
+            throw new ToolError("Interrupted");
+        return undefined; // not a git work tree, or no git
+    }
+    const rootReal = realpathSync(root);
+    const dirInside = new Map();
+    // An index entry like evil/x with evil -> ~/somewhere is a regular file to lstat: every directory on the way must
+    // resolve inside the workspace too.
+    const inside = (dir) => {
+        let ok = dirInside.get(dir);
+        if (ok === undefined) {
+            try {
+                const real = realpathSync(dir);
+                ok = real === rootReal || real.startsWith(rootReal + sep);
+            }
+            catch {
+                ok = false;
+            }
+            dirInside.set(dir, ok);
+        }
+        return ok;
+    };
+    const out = new Set();
+    for (const r of stdout.split("\0")) {
+        if (!r || r.split("/").some((seg) => SKIP_DIRS.has(seg)))
+            continue;
+        const full = join(root, r.replace(/\/$/, ""));
+        let st;
+        try {
+            st = lstatSync(full);
+        }
+        catch {
+            continue; // deleted
+        }
+        if (!inside(dirname(full)))
+            continue;
+        if (st.isFile())
+            out.add(full);
+        else if (st.isDirectory())
+            for (const f of walkFiles(full))
+                out.add(f); // a nested repository or submodule
+        if (out.size >= MAX_LISTED_FILES)
+            break;
+    }
+    // Nothing listed (a gitignored directory asked for explicitly, a home-directory dotfiles repo): walk instead.
+    return out.size ? [...out].sort() : undefined;
+}
+function walkFiles(root) {
+    const files = [];
+    const stack = [root];
+    while (stack.length && files.length < MAX_LISTED_FILES) {
+        const dir = stack.pop();
+        let names;
+        try {
+            names = readdirSync(dir, { withFileTypes: true }).sort((x, y) => x.name.localeCompare(y.name));
+        }
+        catch {
+            continue;
+        }
+        const subdirs = [];
+        for (const d of names) {
+            if (d.isSymbolicLink())
+                continue; // never followed: nothing outside the workspace is reachable
+            const full = join(dir, d.name);
+            if (d.isDirectory()) {
+                if (!SKIP_DIRS.has(d.name))
+                    subdirs.push(full);
+            }
+            else if (d.isFile())
+                files.push(full);
+        }
+        stack.push(...subdirs.reverse());
+    }
+    return files;
+}
+/** Files under `a.path` (default: the workspace) matching `a.glob`/`a.pattern`; the shared front half of grep and glob. */
+async function selectFiles(cwd, path, glob, signal) {
+    const root = safePath(cwd, path ?? ".");
+    const st = statSync(root);
+    if (st.isFile())
+        return { root, files: [root], gitignore: false };
+    if (!st.isDirectory())
+        throw new ToolError(`${path} is not a file or directory`);
+    const { files, gitignore } = await workspaceFiles(root, signal);
+    if (typeof glob !== "string" || !glob)
+        return { root, files, gitignore };
+    const re = globToRegExp(glob);
+    const byPath = glob.includes("/");
+    return { root, files: files.filter((f) => re.test(byPath ? relative(root, f).split(sep).join("/") : basename(f))), gitignore };
+}
+export async function grepWorkspace(cwd, a, signal) {
+    if (typeof a.pattern !== "string" || !a.pattern)
+        throw new ToolError("`pattern` must be a non-empty string");
+    const max = optInt(a.max_results, "max_results", 500) ?? 100;
+    const ctxLines = optInt(a.context, "context", 10) ?? 0;
+    const filesOnly = a.files_only === true;
+    let re;
+    try {
+        re = new RegExp(a.literal ? a.pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") : a.pattern, a.ignore_case ? "i" : "");
+    }
+    catch (e) {
+        throw new ToolError(`Invalid regular expression: ${e.message}`);
+    }
+    const { files, gitignore } = await selectFiles(cwd, a.path, a.glob, signal);
+    const out = [];
+    let searched = 0, skipped = 0, matchedFiles = 0, total = 0;
+    for (const f of files) {
+        if (signal.aborted)
+            throw new ToolError("Interrupted");
+        if (total >= max)
+            break;
+        if (searched % 40 === 39)
+            await new Promise((r) => setImmediate(r)); // stay responsive to Ctrl+C
+        let buf;
+        try {
+            if (statSync(f).size > MAX_GREP_FILE) {
+                skipped++;
+                continue;
+            }
+            buf = readFileSync(f);
+        }
+        catch {
+            skipped++;
+            continue;
+        }
+        if (buf.subarray(0, 8192).includes(0)) {
+            skipped++;
+            continue;
+        }
+        searched++;
+        const lines = buf.toString("utf8").split("\n").map((l) => l.replace(/\r$/, ""));
+        if (lines.at(-1) === "")
+            lines.pop(); // the newline that ends the file is not a line
+        const hits = [];
+        for (let i = 0; i < lines.length && total < max; i++) {
+            if (re.test(lines[i].length > 2000 ? lines[i].slice(0, 2000) : lines[i]))
+                (hits.push(i), total++);
+        }
+        if (!hits.length)
+            continue;
+        matchedFiles++;
+        const name = rel(cwd, f);
+        if (filesOnly) {
+            out.push(`${name} (${hits.length} match${hits.length > 1 ? "es" : ""})`);
+            continue;
+        }
+        const clip = (l) => (l.length > 300 ? l.slice(0, 300) + "…" : l);
+        if (!ctxLines) {
+            for (const i of hits)
+                out.push(`${name}:${i + 1}: ${clip(lines[i])}`);
+            continue;
+        }
+        // with context: like grep -C, matches as path:line:, context as path-line-, groups separated by --
+        const hit = new Set(hits);
+        let last = -1;
+        for (const h of hits) {
+            const from = Math.max(h - ctxLines, last + 1);
+            if (last >= 0 && from > last + 1)
+                out.push("--");
+            else if (last < 0 && out.length)
+                out.push("--");
+            for (let i = from; i <= Math.min(h + ctxLines, lines.length - 1); i++) {
+                out.push(`${name}${hit.has(i) ? ":" : "-"}${i + 1}${hit.has(i) ? ":" : "-"} ${clip(lines[i])}`);
+                last = i;
+            }
+        }
+    }
+    const footer = `[${total} match${total === 1 ? "" : "es"} in ${matchedFiles} file${matchedFiles === 1 ? "" : "s"}; searched ${searched} files${gitignore ? " (.gitignore respected)" : ""}${skipped ? `, skipped ${skipped} binary/large/unreadable` : ""}${total >= max ? `; stopped at max_results=${max}` : ""}]`;
+    if (!out.length)
+        return `No matches. ${footer}`;
+    const { text, truncated } = truncate(out.join("\n"), "head");
+    return `${text}\n${footer}${truncated ? " [output truncated]" : ""}`;
+}
+export async function globWorkspace(cwd, a, signal) {
+    if (typeof a.pattern !== "string" || !a.pattern)
+        throw new ToolError("`pattern` must be a non-empty glob, e.g. **/*.test.ts");
+    const { files, gitignore } = await selectFiles(cwd, a.path, a.pattern, signal);
+    const LIMIT = 500;
+    if (!files.length)
+        return `No files match ${a.pattern}.${gitignore ? " (.gitignore respected)" : ""}`;
+    const shown = files.slice(0, LIMIT).map((f) => rel(cwd, f));
+    return `${shown.join("\n")}\n[${files.length} file${files.length > 1 ? "s" : ""}${files.length > LIMIT ? `; showing the first ${LIMIT}, narrow the pattern or path` : ""}${gitignore ? "; .gitignore respected" : ""}]`;
+}
+export function listDir(cwd, a) {
+    const depth = optInt(a.depth, "depth", 3) ?? 1;
+    const root = safePath(cwd, a.path ?? ".");
+    if (!statSync(root).isDirectory())
+        throw new ToolError(`${a.path ?? "."} is not a directory`);
+    const lines = [];
+    let count = 0;
+    const walk = (dir, level) => {
+        let ents;
+        try {
+            ents = readdirSync(dir, { withFileTypes: true });
+        }
+        catch (e) {
+            lines.push(`${"  ".repeat(level)}[unreadable: ${e.code}]`);
+            return;
+        }
+        ents.sort((x, y) => Number(y.isDirectory()) - Number(x.isDirectory()) || x.name.localeCompare(y.name));
+        for (const d of ents) {
+            if (++count > 500)
+                return;
+            const pad = "  ".repeat(level);
+            const full = join(dir, d.name);
+            if (d.isSymbolicLink()) {
+                let target = "?";
+                try {
+                    target = readlinkSync(full);
+                }
+                catch { }
+                lines.push(`${pad}${d.name}@ -> ${target}`);
+            }
+            else if (d.isDirectory()) {
+                lines.push(`${pad}${d.name}/${SKIP_DIRS.has(d.name) ? " (not expanded)" : ""}`);
+                if (level + 1 < depth && !SKIP_DIRS.has(d.name))
+                    walk(full, level + 1);
+            }
+            else {
+                let size = "";
+                try {
+                    size = `  (${statSync(full).size} bytes)`;
+                }
+                catch { }
+                lines.push(`${pad}${d.name}${d.isFile() ? size : "  [special file]"}`);
+            }
+        }
+    };
+    walk(root, 0);
+    if (!lines.length)
+        return "(empty directory)";
+    return lines.join("\n") + (count > 500 ? "\n[truncated at 500 entries]" : "");
+}
+// ---------------------------------------------------------------- images
+/** Base64 makes this about 2.1 MB, leaving most of OICKI's 4,000,000-byte request limit for the conversation. */
+export const MAX_IMAGE_BYTES = 1.5 * 1024 * 1024;
+/** Recognised by content, not by extension: png, jpeg, gif, webp. */
+export function imageMime(path) {
+    let head;
+    try {
+        const fd = openSync(path, "r");
+        try {
+            head = Buffer.alloc(12);
+            readSync(fd, head, 0, 12, 0);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch {
+        return undefined;
+    }
+    if (head.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])))
+        return "image/png";
+    if (head[0] === 0xff && head[1] === 0xd8 && head[2] === 0xff)
+        return "image/jpeg";
+    if (head.subarray(0, 4).toString("latin1") === "GIF8")
+        return "image/gif";
+    if (head.subarray(0, 4).toString("latin1") === "RIFF" && head.subarray(8, 12).toString("latin1") === "WEBP")
+        return "image/webp";
+    return undefined;
+}