@thaut/claude-ide 0.0.0-stage → 1.0.0

package/server/files.test.ts

@@ -0,0 +1,127 @@
+import { test, after } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { channelFixture } from "./http-channel-test-fixture.ts";
+
+const fixture = await channelFixture();
+after(() => fixture.close());
+const { registerFileRoutes } = await import("./files.ts");
+registerFileRoutes(fixture.app);
+const read = (file: string, full = false) => fixture.app.request(`/api/projects/${fixture.project.id}/file?${new URLSearchParams({ path: file, ...(full ? { full: "1" } : {}) })}`);
+
+test("common image and audio formats return native media bytes with seekable ranges", async () => {
+  const media = [["picture.PNG", "image/png"], ["picture.webp", "image/webp"], ["voice.mp3", "audio/mpeg"],
+    ["voice.wav", "audio/wav"], ["voice.wave", "audio/wav"], ["voice.m4a", "audio/mp4"], ["voice.ogg", "audio/ogg"]];
+  const bytes = Buffer.from("0123456789abcdef");
+  for (const [name, mime] of media) {
+    fs.writeFileSync(path.join(fixture.tmp, name!), bytes);
+    const response = await read(name!);
+    assert.equal(response.headers.get("content-type"), mime);
+    assert.equal(response.headers.get("accept-ranges"), "bytes");
+    assert.deepEqual(Buffer.from(await response.arrayBuffer()), bytes);
+  }
+  const range = (value: string) => fixture.app.request(`/api/projects/${fixture.project.id}/file?path=voice.wav`, { headers: { range: value } });
+  const part = await range("bytes=3-7");
+  assert.equal(part.status, 206);
+  assert.equal(part.headers.get("content-range"), "bytes 3-7/16");
+  assert.equal(part.headers.get("content-length"), "5");
+  assert.equal(await part.text(), "34567");
+  assert.equal(await (await range("bytes=-4")).text(), "cdef");
+  assert.equal(await (await range("bytes=12-")).text(), "cdef");
+  assert.equal((await range("bytes=50-")).status, 416);
+  assert.equal((await range("bytes=-0")).status, 416);
+  assert.equal((await range("bytes=0-1,4-5")).status, 416);
+  assert.equal((await fixture.app.request(`/api/projects/${fixture.project.id}/file?path=voice.wav`, { method: "HEAD" })).headers.get("content-length"), "16");
+});
+
+test("file previews stay bounded while explicit full copies include text beyond the preview", async () => {
+  const text = "a".repeat(1024 * 1024) + "\n完整的文件结尾。\n";
+  fs.writeFileSync(path.join(fixture.tmp, "large.txt"), text);
+  const preview = await (await read("large.txt")).json();
+  assert.equal(preview.truncated, true);
+  assert.equal(preview.content, text.slice(0, 1024 * 1024));
+  const complete = await (await read("large.txt", true)).json();
+  assert.equal(complete.truncated, false);
+  assert.equal(complete.content, text);
+  assert.equal(complete.size, Buffer.byteLength(text));
+});
+
+test("full copies retain file size, binary and project-boundary protections", async () => {
+  const large = path.join(fixture.tmp, "too-large.txt");
+  const fd = fs.openSync(large, "w");
+  try { fs.ftruncateSync(fd, 50 * 1024 * 1024 + 1); } finally { fs.closeSync(fd); }
+  assert.equal((await read("too-large.txt", true)).status, 413);
+  fs.writeFileSync(path.join(fixture.tmp, "binary.dat"), Buffer.from([1, 0, 2]));
+  const binary = await (await read("binary.dat", true)).json();
+  assert.equal(binary.binary, true);
+  assert.equal(binary.content, undefined);
+  assert.equal((await read("../outside.txt", true)).status, 403);
+  fs.writeFileSync(path.join(fixture.tmp, "empty.txt"), "");
+  assert.equal((await (await read("empty.txt", true)).json()).content, "");
+});
+
+const transfer = (endpoint: string, dir: string, init?: RequestInit) => fixture.app.request(`/api/projects/${fixture.project.id}/${endpoint}?${new URLSearchParams({ path: dir })}`, init);
+function uploadForm(files: [string, string][], overwrite: string[] = []) {
+  const form = new FormData();
+  files.forEach(([name, text]) => form.append("files", new File([text], name)));
+  overwrite.forEach((name) => form.append("overwrite", name));
+  return form;
+}
+
+test("file downloads preserve binary data and use attachment disposition", async () => {
+  const name = "下载 #1.bin", bytes = Buffer.from([0, 255, 1, 2, 3]);
+  fs.writeFileSync(path.join(fixture.tmp, name), bytes);
+  const response = await transfer("file/download", name);
+  assert.equal(response.status, 200);
+  assert.match(response.headers.get("content-disposition")!, /^attachment;/);
+  assert.ok(response.headers.get("content-disposition")!.includes(encodeURIComponent(name)));
+  assert.deepEqual(Buffer.from(await response.arrayBuffer()), bytes);
+  assert.equal((await transfer("file/download", "../outside.txt")).status, 403);
+  assert.equal((await transfer("file/download", "")).status, 400);
+});
+
+test("folder uploads publish complete files and require exact overwrite confirmation", async () => {
+  const folder = path.join(fixture.tmp, "uploads"); fs.mkdirSync(folder);
+  const send = (form: FormData) => transfer("files/upload", "uploads", { method: "POST", body: form });
+  const first = await send(uploadForm([["a.txt", "first"], ["empty.bin", ""]]));
+  assert.equal(first.status, 200);
+  assert.deepEqual((await first.json()).files, ["uploads/a.txt", "uploads/empty.bin"]);
+  const conflict = await send(uploadForm([["a.txt", "replacement"], ["new.txt", "new"]]));
+  assert.equal(conflict.status, 409);
+  assert.deepEqual((await conflict.json()).conflicts, ["a.txt"]);
+  assert.equal(fs.readFileSync(path.join(folder, "a.txt"), "utf8"), "first");
+  assert.equal(fs.existsSync(path.join(folder, "new.txt")), false, "preflight conflicts do not partially upload a batch");
+  const overwritten = await send(uploadForm([["a.txt", "replacement"], ["new.txt", "new"]], ["a.txt"]));
+  assert.equal(overwritten.status, 200);
+  assert.equal(fs.readFileSync(path.join(folder, "a.txt"), "utf8"), "replacement");
+  assert.deepEqual(fs.readdirSync(folder).sort(), ["a.txt", "empty.bin", "new.txt"], "staging files are removed");
+});
+
+test("uploads retain project boundaries and refuse directories, duplicates and oversized bodies", async () => {
+  const send = (dir: string, form: FormData) => transfer("files/upload", dir, { method: "POST", body: form });
+  assert.equal((await send("..", uploadForm([["escape.txt", "bad"]]))).status, 403);
+  assert.equal((await send("", uploadForm([["duplicate.txt", "one"], ["duplicate.txt", "two"]]))).status, 400);
+  fs.mkdirSync(path.join(fixture.tmp, "occupied.txt"));
+  assert.equal((await send("", uploadForm([["occupied.txt", "bad"]], ["occupied.txt"]))).status, 409);
+  const outside = path.join(fixture.tmp, "..", `${path.basename(fixture.tmp)}-external`);
+  fs.mkdirSync(outside); fs.writeFileSync(path.join(outside, "secret.txt"), "keep");
+  fs.symlinkSync(outside, path.join(fixture.tmp, "external"));
+  try {
+    assert.equal((await send("external", uploadForm([["secret.txt", "bad"]], ["secret.txt"]))).status, 403);
+    assert.equal(fs.readFileSync(path.join(outside, "secret.txt"), "utf8"), "keep");
+  } finally { fs.rmSync(outside, { recursive: true, force: true }); }
+  const huge = await transfer("files/upload", "", { method: "POST", headers: { "content-length": String(52 * 1024 * 1024) }, body: "x" });
+  assert.equal(huge.status, 413);
+});
+
+test("overwrite uploads retain executable and private file permissions", async () => {
+  for (const [name, mode] of [["run.sh", 0o755], ["private.txt", 0o600], ["owner-only.sh", 0o700]] as const) {
+    const file = path.join(fixture.tmp, name);
+    fs.writeFileSync(file, "before"); fs.chmodSync(file, mode);
+    const response = await transfer("files/upload", "", { method: "POST", body: uploadForm([[name, "after"]], [name]) });
+    assert.equal(response.status, 200);
+    assert.equal(fs.statSync(file).mode & 0o777, mode);
+    assert.equal(fs.readFileSync(file, "utf8"), "after");
+  }
+});

package/server/files.ts

@@ -0,0 +1,386 @@
+import fs from "node:fs/promises";
+import type { Dirent } from "node:fs";
+import path from "node:path";
+import { constants } from "node:fs";
+import { Readable } from "node:stream";
+import { spawn } from "node:child_process";
+import type { Context, Hono } from "hono";
+import type { ContentMatch, DirEntry, DirListing, FileContent, FileMatch } from "../shared/files.ts";
+import { AUDIO_TYPES } from "../shared/files.ts";
+import { FsHttpError, gitInfo, hasRipgrep, projectRoot, resolveSafe, route, run } from "./fsutil.ts";
+import { registerGitRoutes } from "./git.ts";
+import { registerFileTransferRoutes } from "./file-transfers.ts";
+
+const MAX_TEXT_BYTES = 1024 * 1024;
+const MAX_RAW_BYTES = 50 * 1024 * 1024;
+const MAX_DIR_ENTRIES = 5000;
+const MAX_FILE_LIST = 200_000;
+
+export const IMAGE_TYPES: Record<string, string> = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".avif": "image/avif",
+  ".bmp": "image/bmp",
+  ".ico": "image/x-icon",
+  ".svg": "image/svg+xml",
+};
+
+export function registerFileRoutes(app: Hono) {
+  app.get("/api/projects/:pid/files", route(async (c) => c.json(await listDir(projectRoot(c), c.req.query("path")))));
+  app.get("/api/projects/:pid/file", route(async (c) => readFile(c, projectRoot(c), c.req.query("path"))));
+  app.get(
+    "/api/projects/:pid/search/files",
+    route(async (c) => c.json(await searchFiles(projectRoot(c), c.req.query("q") ?? "", limitParam(c, 50, 500)))),
+  );
+  app.get(
+    "/api/projects/:pid/search/content",
+    route(async (c) => c.json(await searchContent(projectRoot(c), c.req.query("q") ?? "", limitParam(c, 200, 2000)))),
+  );
+  registerGitRoutes(app);
+  registerFileTransferRoutes(app);
+}
+
+function limitParam(c: Context, def: number, max: number) {
+  const n = Number(c.req.query("limit"));
+  return Number.isFinite(n) && n > 0 ? Math.min(Math.floor(n), max) : def;
+}
+
+// ---------- directory listing ----------
+
+async function mapLimit<T, R>(items: T[], limit: number, fn: (item: T) => Promise<R>): Promise<R[]> {
+  const out = new Array<R>(items.length);
+  let next = 0;
+  const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+    while (true) {
+      const i = next++;
+      if (i >= items.length) return;
+      out[i] = await fn(items[i]!);
+    }
+  });
+  await Promise.all(workers);
+  return out;
+}
+
+async function listDir(projectRoot: string, rel: string | undefined): Promise<DirListing> {
+  const sp = await resolveSafe(projectRoot, rel);
+  const st = await fs.stat(sp.abs);
+  if (!st.isDirectory()) throw new FsHttpError(400, "不是目录");
+  const dirents = (await fs.readdir(sp.abs, { withFileTypes: true })).filter((d) => !(d.name === ".git" && sp.rel === ""));
+  const truncated = dirents.length > MAX_DIR_ENTRIES;
+  const visible = dirents.slice(0, MAX_DIR_ENTRIES);
+  const entries = (
+    await mapLimit(visible, 16, async (d): Promise<DirEntry | undefined> => {
+      if (d.name === ".git") return undefined;
+      const relPath = sp.rel ? `${sp.rel}/${d.name}` : d.name;
+      const abs = path.join(sp.abs, d.name);
+      const entry: DirEntry = { name: d.name, path: relPath, type: "other" };
+      if (d.isSymbolicLink()) {
+        entry.link = true;
+        try {
+          const real = await fs.realpath(abs);
+          const r = path.relative(sp.root, real);
+          if (r.startsWith("..") || path.isAbsolute(r)) {
+            entry.outside = true;
+          } else {
+            const t = await fs.stat(real);
+            entry.type = t.isDirectory() ? "dir" : t.isFile() ? "file" : "other";
+            if (t.isFile()) entry.size = t.size;
+          }
+        } catch {
+          // broken link
+        }
+      } else if (d.isDirectory()) {
+        entry.type = "dir";
+      } else if (d.isFile()) {
+        entry.type = "file";
+        try {
+          entry.size = (await fs.stat(abs)).size;
+        } catch {
+          // vanished
+        }
+      }
+      return entry;
+    })
+  ).filter((e): e is DirEntry => !!e);
+
+  const git = await gitInfo(sp.root);
+  if (git.isRepo && entries.length) {
+    // Paths are relative to the project root, which is the cwd.
+    const res = await run("git", ["check-ignore", "-z", "--stdin"], sp.root, {
+      input: entries.map((e) => (e.type === "dir" ? `${e.path}/` : e.path)).join("\0") + "\0",
+    }).catch(() => null);
+    if (res && res.code === 0) {
+      const ignored = new Set(res.stdout.split("\0").filter(Boolean).map((p) => p.replace(/\/$/, "")));
+      for (const e of entries) if (ignored.has(e.path)) e.ignored = true;
+    }
+  }
+
+  const rank = (e: DirEntry) => (e.type === "dir" ? 0 : 1);
+  entries.sort((a, b) => rank(a) - rank(b) || a.name.localeCompare(b.name, undefined, { numeric: true, sensitivity: "base" }));
+  return { path: sp.rel, entries, truncated, git: git.isRepo };
+}
+
+// ---------- file content ----------
+
+async function readFile(c: Context, projectRoot: string, rel: string | undefined): Promise<Response> {
+  const sp = await resolveSafe(projectRoot, rel);
+  const st = await fs.stat(sp.abs);
+  if (st.isDirectory()) throw new FsHttpError(400, "这是一个目录");
+  if (!st.isFile()) throw new FsHttpError(400, "不是普通文件");
+
+  const extension = path.extname(sp.abs).toLowerCase();
+  const mime = IMAGE_TYPES[extension] ?? AUDIO_TYPES[extension];
+  if (mime) {
+    if (!AUDIO_TYPES[extension] && st.size > MAX_RAW_BYTES) throw new FsHttpError(413, "文件太大");
+    const real = await resolveSafe(projectRoot, await fs.realpath(sp.abs));
+    const handle = await fs.open(real.abs, constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOFOLLOW);
+    try {
+      const stat = await handle.stat();
+      if (!stat.isFile()) throw new FsHttpError(400, "不是普通文件");
+      const headers: Record<string, string> = {
+        "content-type": mime,
+        "content-length": String(stat.size),
+        "accept-ranges": "bytes",
+        "cache-control": "no-cache",
+        "x-content-type-options": "nosniff",
+        // SVG can carry script; never let it run with our origin.
+        "content-security-policy": "default-src 'none'; style-src 'unsafe-inline'; sandbox",
+      };
+      let start = 0, end = stat.size - 1, status = 200;
+      const range = c.req.header("range");
+      if (range) {
+        const match = /^bytes=(\d*)-(\d*)$/.exec(range);
+        if (match && (match[1] || match[2])) {
+          start = match[1] ? Number(match[1]) : Math.max(0, stat.size - Number(match[2]));
+          end = match[1] && match[2] ? Math.min(Number(match[2]), stat.size - 1) : stat.size - 1;
+        } else start = stat.size;
+        if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start >= stat.size || end < start) {
+          await handle.close();
+          return new Response(null, { status: 416, headers: { "content-range": `bytes */${stat.size}`, "accept-ranges": "bytes" } });
+        }
+        status = 206;
+        headers["content-range"] = `bytes ${start}-${end}/${stat.size}`;
+        headers["content-length"] = String(end - start + 1);
+      }
+      if (c.req.method === "HEAD") { await handle.close(); return new Response(null, { status, headers }); }
+      return new Response(Readable.toWeb(handle.createReadStream(stat.size ? { start, end } : {})) as ReadableStream<Uint8Array>, { status, headers });
+    } catch (error) { await handle.close(); throw error; }
+  }
+
+  // Full text is fetched only by an explicit copy action, never by the viewer.
+  const full = c.req.query("full") === "1";
+  if (full && st.size > MAX_RAW_BYTES) throw new FsHttpError(413, "文件太大，无法复制全文");
+  const len = Math.min(st.size, full ? MAX_RAW_BYTES : MAX_TEXT_BYTES);
+  const buf = Buffer.alloc(len);
+  const fh = await fs.open(sp.abs, "r");
+  try {
+    let off = 0;
+    while (off < len) {
+      const { bytesRead } = await fh.read(buf, off, len - off, off);
+      if (bytesRead === 0) break;
+      off += bytesRead;
+    }
+  } finally {
+    await fh.close();
+  }
+  const body: FileContent = { path: sp.rel, size: st.size, truncated: st.size > len, binary: isBinary(buf) };
+  if (!body.binary) body.content = new TextDecoder("utf-8").decode(buf);
+  return c.json(body);
+}
+
+function isBinary(buf: Buffer) {
+  const n = Math.min(buf.length, 8000);
+  for (let i = 0; i < n; i++) if (buf[i] === 0) return true;
+  return false;
+}
+
+// ---------- file name search ----------
+
+/** All non-ignored files of the project (relative paths), capped. */
+export async function listProjectFiles(root: string): Promise<string[]> {
+  const git = await gitInfo(root);
+  if (git.isRepo) {
+    const r = await run("git", ["-c", "core.quotepath=off", "ls-files", "-co", "--exclude-standard", "-z"], root, { maxBuffer: 256 * 1024 * 1024 });
+    if (r.code === 0) {
+      const files = r.stdout.split("\0").filter(Boolean);
+      // ls-files lists deleted-but-tracked files too; that is fine for name search.
+      return files.slice(0, MAX_FILE_LIST);
+    }
+  }
+  if (await hasRipgrep()) {
+    const lines = await streamLines("rg", ["--files", "--hidden", "--no-ignore-parent", "-g", "!.git", "--null"], root, MAX_FILE_LIST, "\0");
+    return lines.lines;
+  }
+  return walk(root, MAX_FILE_LIST);
+}
+
+async function walk(root: string, max: number): Promise<string[]> {
+  const out: string[] = [];
+  const stack = [""];
+  while (stack.length && out.length < max) {
+    const rel = stack.pop()!;
+    let ds: Dirent[];
+    try {
+      ds = await fs.readdir(path.join(root, rel), { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const d of ds) {
+      if (d.name === ".git" || d.name === "node_modules") continue;
+      const p = rel ? `${rel}/${d.name}` : d.name;
+      if (d.isDirectory()) stack.push(p);
+      else if (d.isFile()) out.push(p);
+    }
+  }
+  return out;
+}
+
+async function searchFiles(projectRoot: string, q: string, limit: number): Promise<{ matches: FileMatch[] }> {
+  const query = q.trim().toLowerCase();
+  if (!query) return { matches: [] };
+  const root = (await resolveSafe(projectRoot, "")).root;
+  const files = await listProjectFiles(root);
+  const scored: FileMatch[] = [];
+  for (const f of files) {
+    const s = fuzzyScore(f, query);
+    if (s > 0) scored.push({ path: f, score: s });
+  }
+  scored.sort((a, b) => b.score - a.score || a.path.length - b.path.length || a.path.localeCompare(b.path));
+  return { matches: scored.slice(0, limit) };
+}
+
+/** Higher is better; 0 means no match. Prefers basename hits, then contiguous, then subsequence. */
+export function fuzzyScore(filePath: string, q: string): number {
+  const p = filePath.toLowerCase();
+  const base = p.slice(p.lastIndexOf("/") + 1);
+  if (base === q) return 1000;
+  if (base.startsWith(q)) return 800 - base.length;
+  const bi = base.indexOf(q);
+  if (bi >= 0) return 600 - bi - base.length / 10;
+  const pi = p.indexOf(q);
+  if (pi >= 0) return 400 - p.length / 10;
+  // Subsequence match; reward consecutive characters and word-boundary starts.
+  let score = 0;
+  let last = -2;
+  let j = 0;
+  for (let i = 0; i < p.length && j < q.length; i++) {
+    if (p[i] !== q[j]) continue;
+    score += i === last + 1 ? 5 : 1;
+    if (i === 0 || "/._-".includes(p[i - 1]!)) score += 3;
+    last = i;
+    j++;
+  }
+  if (j < q.length) return 0;
+  return Math.max(1, 100 + score - p.length / 10);
+}
+
+// ---------- content search ----------
+
+async function searchContent(projectRoot: string, q: string, limit: number): Promise<{ matches: ContentMatch[]; truncated: boolean }> {
+  if (!q.trim()) return { matches: [], truncated: false };
+  const root = (await resolveSafe(projectRoot, "")).root;
+  const git = await gitInfo(root);
+  const matches: ContentMatch[] = [];
+
+  if (await hasRipgrep()) {
+    const args = ["--json", "-F", "-S", "--hidden", "-g", "!.git", "--max-count", "50", "--max-columns", "400", "--max-columns-preview", "--max-filesize", "5M"];
+    if (!git.isRepo) args.push("--no-ignore-parent");
+    args.push("-e", q, "--", ".");
+    let truncated = false;
+    await streamLines("rg", args, root, Infinity, "\n", (line) => {
+      if (matches.length >= limit) {
+        truncated = true;
+        return false;
+      }
+      let ev: { type: string; data?: { path?: { text?: string }; lines?: { text?: string }; line_number?: number; submatches?: { start: number; end: number }[] } };
+      try {
+        ev = JSON.parse(line);
+      } catch {
+        return true;
+      }
+      if (ev.type !== "match" || !ev.data?.path?.text) return true;
+      const text = (ev.data.lines?.text ?? "").replace(/\r?\n$/, "");
+      const sm = ev.data.submatches?.[0];
+      matches.push({
+        path: ev.data.path.text.replace(/^\.\//, ""),
+        line: ev.data.line_number ?? 0,
+        text,
+        // rg offsets are bytes; convert to string indices.
+        ...(sm ? byteRangeToChars(text, sm.start, sm.end) : {}),
+      });
+      return true;
+    });
+    return { matches, truncated };
+  }
+
+  if (git.isRepo) {
+    const r = await run("git", ["-c", "core.quotepath=off", "grep", "-n", "-I", "-F", "-i", "--untracked", "--no-color", "-z", "-e", q, "--", "."], root);
+    const lines = r.stdout.split("\n").filter(Boolean);
+    for (const l of lines.slice(0, limit)) {
+      const [file = "", lineNo = "0", ...rest] = l.split("\0");
+      matches.push({ path: file, line: Number(lineNo), text: rest.join("\0").slice(0, 400) });
+    }
+    return { matches, truncated: lines.length > limit };
+  }
+  throw new FsHttpError(409, "内容搜索需要 ripgrep (rg) 或 git 仓库");
+}
+
+function byteRangeToChars(text: string, start: number, end: number) {
+  const bytes = Buffer.from(text, "utf8");
+  const s = bytes.subarray(0, start).toString("utf8").length;
+  const e = bytes.subarray(0, end).toString("utf8").length;
+  return { start: s, end: e };
+}
+
+/**
+ * Spawn a process and hand its output over line by line; stops (and kills it)
+ * once `max` lines were collected or `onLine` returns false.
+ */
+function streamLines(
+  cmd: string,
+  args: string[],
+  cwd: string,
+  max: number,
+  sep: string,
+  onLine?: (line: string) => boolean,
+): Promise<{ lines: string[] }> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { cwd, stdio: ["ignore", "pipe", "ignore"] });
+    const lines: string[] = [];
+    let buf = "";
+    let done = false;
+    const finish = () => {
+      if (done) return;
+      done = true;
+      child.kill();
+      resolve({ lines });
+    };
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", (chunk: string) => {
+      if (done) return;
+      buf += chunk;
+      let i: number;
+      while ((i = buf.indexOf(sep)) >= 0) {
+        const line = buf.slice(0, i);
+        buf = buf.slice(i + sep.length);
+        if (onLine) {
+          if (!onLine(line)) return finish();
+        } else {
+          lines.push(line);
+          if (lines.length >= max) return finish();
+        }
+      }
+    });
+    child.on("error", (err) => (done ? undefined : reject(err)));
+    child.on("close", () => {
+      if (buf && !done) {
+        if (onLine) onLine(buf);
+        else lines.push(buf);
+      }
+      finish();
+    });
+  });
+}

package/server/fs-queue.ts

@@ -0,0 +1,14 @@
+/**
+ * Serialize read-modify-write sequences per file. Sync code used to be atomic
+ * because it could not yield; async code must re-acquire that guarantee.
+ */
+const chains = new Map<string, Promise<unknown>>();
+
+export function withFileLock<T>(key: string, fn: () => Promise<T>): Promise<T> {
+  const previous = chains.get(key) ?? Promise.resolve();
+  const work = previous.catch(() => {}).then(fn);
+  chains.set(key, work);
+  return work.finally(() => {
+    if (chains.get(key) === work) chains.delete(key);
+  });
+}

package/server/fsutil.ts

@@ -0,0 +1,144 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import type { Context } from "hono";
+import { projectPath } from "./sessions.ts";
+
+/** Errors from the file/git routes; mapped to JSON responses by the route wrapper. */
+export class FsHttpError extends Error {
+  constructor(
+    public status: 400 | 403 | 404 | 409 | 413,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+const isInside = (root: string, p: string) => {
+  const rel = path.relative(root, p);
+  return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+};
+
+export type SafePath = {
+  /** Real (symlink-free) project root */
+  root: string;
+  /** Lexically resolved absolute path (may not exist when `mustExist` is false) */
+  abs: string;
+  /** Path relative to the root with forward slashes ("" for the root itself) */
+  rel: string;
+};
+
+/**
+ * Resolve a client-supplied path against the project root. Rejects anything that
+ * escapes the root lexically (`..`, absolute paths) or physically (symlinks
+ * pointing outside). With `mustExist: false` the deepest existing ancestor is checked.
+ */
+export async function resolveSafe(projectRoot: string, input: string | undefined, opts: { mustExist?: boolean } = {}): Promise<SafePath> {
+  const mustExist = opts.mustExist ?? true;
+  const raw = (input ?? "").trim();
+  if (raw.includes("\0")) throw new FsHttpError(400, "非法路径");
+  let root: string;
+  try {
+    root = await fs.realpath(projectRoot);
+  } catch {
+    throw new FsHttpError(404, "项目目录不存在");
+  }
+  // Absolute paths are accepted only when they name something under the project root
+  // (spelled either through the registered path or its realpath).
+  let rel = raw;
+  if (path.isAbsolute(raw)) {
+    const viaRegistered = path.resolve(raw);
+    rel = isInside(path.resolve(projectRoot), viaRegistered) ? path.relative(path.resolve(projectRoot), viaRegistered) : path.relative(root, viaRegistered);
+  }
+  const abs = path.resolve(root, rel);
+  if (!isInside(root, abs)) throw new FsHttpError(403, "路径超出项目目录");
+
+  let probe = abs;
+  for (;;) {
+    try {
+      const real = await fs.realpath(probe);
+      if (!isInside(root, real)) throw new FsHttpError(403, "路径超出项目目录");
+      break;
+    } catch (err) {
+      if (err instanceof FsHttpError) throw err;
+      if (mustExist) throw new FsHttpError(404, "文件不存在");
+      const parent = path.dirname(probe);
+      if (parent === probe) break;
+      probe = parent;
+    }
+  }
+  return { root, abs, rel: path.relative(root, abs).split(path.sep).join("/") };
+}
+
+export type RunResult = { code: number; stdout: string; stderr: string };
+
+/** Run a command without a shell. Non-zero exit codes resolve (callers decide). */
+export function run(cmd: string, args: string[], cwd: string, opts: { maxBuffer?: number; input?: string } = {}): Promise<RunResult> {
+  return new Promise((resolve, reject) => {
+    const child = execFile(
+      cmd,
+      args,
+      {
+        cwd,
+        maxBuffer: opts.maxBuffer ?? 32 * 1024 * 1024,
+        encoding: "utf8",
+        // Don't take index.lock for read-only commands: Claude may be running git concurrently.
+        env: { ...process.env, GIT_OPTIONAL_LOCKS: "0", GIT_TERMINAL_PROMPT: "0", LC_ALL: "C.UTF-8" },
+      },
+      (err, stdout, stderr) => {
+        if (err && typeof (err as NodeJS.ErrnoException).code === "string") {
+          // Spawn failure (ENOENT) or maxBuffer exceeded.
+          const code = (err as NodeJS.ErrnoException).code;
+          if (code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER") return resolve({ code: -2, stdout, stderr });
+          return reject(err);
+        }
+        const code = err ? ((err as { code?: number }).code ?? 1) : 0;
+        resolve({ code: typeof code === "number" ? code : 1, stdout, stderr });
+      },
+    );
+    if (opts.input !== undefined) child.stdin?.end(opts.input);
+  });
+}
+
+let rgAvailable: Promise<boolean> | undefined;
+export function hasRipgrep(): Promise<boolean> {
+  rgAvailable ??= run("rg", ["--version"], process.cwd())
+    .then((r) => r.code === 0)
+    .catch(() => false);
+  return rgAvailable;
+}
+
+export type GitInfo = { isRepo: false } | { isRepo: true; top: string; prefix: string };
+
+/**
+ * Is the project a git working tree? A project directory that sits inside some
+ * other repository but is ignored by it (e.g. a scratch dir) counts as "not a repo".
+ */
+export async function gitInfo(root: string): Promise<GitInfo> {
+  const r = await run("git", ["rev-parse", "--show-toplevel", "--show-prefix"], root).catch(() => null);
+  if (!r || r.code !== 0) return { isRepo: false };
+  const [top = "", prefix = ""] = r.stdout.split("\n");
+  if (prefix) {
+    const ign = await run("git", ["check-ignore", "-q", "--", "."], root);
+    if (ign.code === 0) return { isRepo: false };
+  }
+  return { isRepo: true, top, prefix };
+}
+
+/** Wrap a handler so FsHttpError becomes a JSON error; other errors go to app.onError. */
+export function route(fn: (c: Context) => Promise<Response>) {
+  return async (c: Context) => {
+    try {
+      return await fn(c);
+    } catch (err) {
+      if (err instanceof FsHttpError) return c.json({ error: err.message }, err.status);
+      throw err;
+    }
+  };
+}
+
+
+/** Registered project root for the `:pid` route param (404 when unknown). */
+export function projectRoot(c: Context): string {
+  return projectPath(c.req.param("pid") ?? "");
+}