@midhunxavier/code-flow 0.0.0-stage → 0.1.0-preview.1

package/src/workspace-api.js

@@ -0,0 +1,207 @@
+import { isAgentId } from "./adapters/index.js";
+import { open, readFile } from "node:fs/promises";
+import { join, resolve, sep } from "node:path";
+import { assertWorktree, repoRoot, resolveCommit, git, worktreeGit, WorktreeMismatchError } from "./git.js";
+import { readJson, HttpError } from "./http.js";
+import { inspectReadiness, inTemporaryWorktree } from "./readiness.js";
+import { applyCheckpoint, checkpoints, readEditableFile, saveEditableFile, searchCode, WorkspaceConflictError } from "./workspace.js";
+import { detectVerificationProfile, renderVerificationReport, runVerification, validateVerificationProfile } from "./verification.js";
+import { runCheck } from "./checks.js";
+import { redactExport } from "./privacy.js";
+import { CODEFLOW_HOME } from "./config.js";
+import { writeHealth } from "./store.js";
+import { mergeFileDraft, checkpointHunks, applyCheckpointHunks } from "./workspace-changes.js";
+import { verificationIntegrity, VerificationIntegrityError } from "./verification-integrity.js";
+import { inspectContext, ContextInspectionError } from "./context-inspection.js";
+import { applyCommitRevert, compareCheckpoint, previewCommitRevert } from "./checkpoint-review.js";
+import { searchSemanticSymbols, findCodeReferences } from "./code-intelligence.js";
+import { inspectArchitecture } from "./architecture.js";
+async function ownedCheckout(repo, tree) {
+  try {
+    return await assertWorktree(repo, tree);
+  } catch (error) {
+    if (error instanceof WorktreeMismatchError) throw new HttpError(409, error.message);
+    throw error;
+  }
+}
+async function diagnosticTail(path) {
+  const file = await open(path, "r").catch(() => void 0);
+  if (!file) return "";
+  try {
+    const info = await file.stat();
+    if (!info.isFile()) return "";
+    const bytes = Math.min(info.size, 32e3);
+    const buffer = Buffer.alloc(bytes);
+    const { bytesRead } = await file.read(buffer, 0, bytes, Math.max(0, info.size - bytes));
+    return buffer.subarray(0, bytesRead).toString("utf8");
+  } finally {
+    await file.close();
+  }
+}
+async function handleWorkspaceApi(req, url, parts, manager, signal) {
+  if (!["readiness", "verification", "workspace", "diagnostics", "v1"].includes(parts[1] ?? "")) return void 0;
+  const body = req.method === "POST" ? await readJson(req) : {};
+  const selected = body.repo ?? url.searchParams.get("repo");
+  const absolute = typeof selected === "string" && selected.startsWith("/") ? resolve(selected) : void 0;
+  const owned = absolute ? manager.list().flatMap((run) => run.worktrees.map((tree) => ({ run, tree }))).find(({ tree }) => absolute === resolve(tree.path) || absolute.startsWith(resolve(tree.path) + sep)) : void 0;
+  const repo = owned?.tree.path ?? (absolute ? await repoRoot(absolute).catch(() => {
+    throw new HttpError(400, "Choose an existing Git repository");
+  }) : void 0);
+  const requireRepo = () => {
+    if (!repo) throw new HttpError(400, "Choose a repository");
+    return repo;
+  };
+  const readRepo = () => owned ? worktreeGit(owned.run.repo, owned.tree.path) : Promise.resolve(requireRepo());
+  const writeRepo = () => owned ? ownedCheckout(owned.run.repo, owned.tree) : Promise.resolve(requireRepo());
+  const boundedCommand = (value) => {
+    if (value === void 0) return void 0;
+    if (typeof value !== "string" || value.length > 4e3 || value.includes("\0")) throw new HttpError(400, "Commands must be text under 4,000 characters");
+    return value;
+  };
+  if (parts[1] === "v1" && parts[2] === "capabilities" && req.method === "GET") return { status: 200, body: { version: 1, features: ["readiness", "verification", "file-editing", "code-search", "dependencies", "checkpoints", "diagnostics", "run-export", "cursor-history", "shared-projects", "ssh-projects", "ssh-workers", "coordinated-changes", "code-hosts", "github-review-threads", "filesystem-policies", "filtered-tasks", "provider-workflow-extensions", "team-collaboration"], authentication: "Bearer CODEFLOW_TOKEN", api: "/api", docs: "docs/api.md" } };
+  if (parts[1] === "readiness" && req.method === "POST") {
+    const boundedId = (value) => typeof value === "string" && /^[a-zA-Z0-9][a-zA-Z0-9_:/.-]{0,127}$/.test(value);
+    const provider = (value) => boundedId(value) && (value === "auto" || isAgentId(value));
+    const providerList = (value) => Array.isArray(value) && value.length <= 128 && value.every(provider);
+    if (body.pattern !== void 0 && !boundedId(body.pattern)) throw new HttpError(400, "Invalid workflow pattern");
+    if (body.providers !== void 0 && !providerList(body.providers)) throw new HttpError(400, "Invalid readiness providers");
+    if (body.roles !== void 0 && (!body.roles || typeof body.roles !== "object" || Array.isArray(body.roles) || Object.keys(body.roles).length > 64 || !Object.entries(body.roles).every(([role, value]) => boundedId(role) && (typeof value === "string" ? provider(value) : providerList(value))))) throw new HttpError(400, "Invalid readiness roles");
+    if (body.execute === true) manager.noteActivity();
+    return { status: 200, body: await inspectReadiness({ repo: owned?.run.repo ?? requireRepo(), baseRef: await resolveCommit(await readRepo(), typeof body.baseRef === "string" && body.baseRef ? body.baseRef : "HEAD"), setup: boundedCommand(body.setup), check: boundedCommand(body.check), pattern: body.pattern, roles: body.roles, providers: body.providers, execute: body.execute === true, signal }) };
+  }
+  if (parts[1] === "verification") {
+    if (req.method === "GET" && parts[2] === "profile") return { status: 200, body: await detectVerificationProfile(requireRepo(), url.searchParams.get("preset") || "standard") };
+    if (req.method === "POST" && !parts[2]) {
+      const selectedRepo = requireRepo();
+      const profile = body.profile ? validateVerificationProfile(body.profile) : await detectVerificationProfile(selectedRepo, body.preset ?? "standard");
+      const originalRepo = owned?.run.repo ?? selectedRepo;
+      const at = await readRepo();
+      const ref = await resolveCommit(at, typeof body.baseRef === "string" && body.baseRef ? body.baseRef : "HEAD");
+      const setup = boundedCommand(body.setup) ?? profile.setup;
+      const run = async (path, baseline2) => {
+        const integrity = await verificationIntegrity(await assertWorktree(originalRepo, { path }), signal);
+        const report = await runVerification(path, profile, { signal, repeats: body.repeats, baseline: baseline2, execute: async (check, options) => {
+          await integrity.assert(`before gate ${check.id}`);
+          await assertWorktree(originalRepo, { path });
+          const result = await runCheck(path, check.command, options);
+          await integrity.assert(`gate ${check.id}`);
+          return result;
+        } });
+        await integrity.assert("completion");
+        return report;
+      };
+      manager.noteActivity();
+      let baseline;
+      const prepare = async (path) => {
+        const integrity = await verificationIntegrity(await assertWorktree(originalRepo, { path }), signal);
+        if (setup) {
+          await assertWorktree(originalRepo, { path });
+          const result = await runCheck(path, setup, { timeoutMs: 12e4, signal });
+          await integrity.assert("setup");
+          if (!result.ok) throw new HttpError(422, `Verification setup failed: ${result.output.slice(-2e3)}`);
+        }
+      };
+      try {
+        if (typeof body.baseline === "string" && body.baseline) {
+          const base = await resolveCommit(at, body.baseline);
+          baseline = await inTemporaryWorktree(originalRepo, base, async (path) => {
+            await prepare(path);
+            const report2 = await run(path);
+            return Object.fromEntries(report2.checks.filter((check) => check.attempts.length).map((check) => [check.check.id, check.attempts[0]]));
+          }, signal);
+        }
+        const report = await inTemporaryWorktree(originalRepo, ref, async (path) => {
+          await prepare(path);
+          return run(path, baseline);
+        }, signal);
+        return { status: 200, body: redactExport({ ...report, repo: selectedRepo, commit: ref, markdown: renderVerificationReport(report) }) };
+      } catch (error) {
+        if (error instanceof VerificationIntegrityError || error instanceof WorktreeMismatchError) throw new HttpError(409, error.message);
+        throw error;
+      }
+    }
+  }
+  if (parts[1] === "workspace") {
+    const selectedRepo = requireRepo();
+    if (parts[2] === "compare-checkpoint" && req.method === "POST") {
+      if (typeof body.from !== "string" || typeof body.to !== "string") throw new HttpError(400, "Choose two commits to compare");
+      return { status: 200, body: await compareCheckpoint(await readRepo(), body, signal) };
+    }
+    if (["preview-revert", "apply-revert"].includes(parts[2] ?? "") && req.method === "POST") {
+      const run = typeof body.runId === "string" ? manager.get(body.runId) : void 0;
+      const tree = run?.worktrees.find((tree2) => tree2.path === selectedRepo);
+      if (!run || !tree) throw new HttpError(409, "Choose an owned run worktree before reverting a commit");
+      if (typeof body.commit !== "string" || typeof body.expectedHead !== "string") throw new HttpError(400, "Choose a commit and refresh the current HEAD");
+      try {
+        return { status: 200, body: await manager.withIdleRepository(selectedRepo, async () => {
+          const at = await ownedCheckout(run.repo, tree);
+          return parts[2] === "preview-revert" ? previewCommitRevert(at, body, signal, run.repo) : applyCommitRevert(at, body, signal, run.repo);
+        }, { kind: "checkpoint-revert", owner: run.id }) };
+      } catch (error) {
+        if (error instanceof WorkspaceConflictError) throw new HttpError(409, error.message);
+        throw error;
+      }
+    }
+    if (parts[2] === "merge-file" && req.method === "POST") return { status: 200, body: await mergeFileDraft(await readRepo(), body.path, body.base, body.draft) };
+    if (["checkpoint-hunks", "apply-hunks"].includes(parts[2] ?? "") && req.method === "POST") {
+      const run = typeof body.runId === "string" ? manager.get(body.runId) : void 0;
+      const tree = run?.worktrees.find((tree2) => tree2.path === selectedRepo);
+      if (!run || !tree || run.status === "running") throw new HttpError(409, "Choose an idle run worktree before applying checkpoint hunks");
+      try {
+        return { status: 200, body: await manager.withIdleRepository(selectedRepo, async () => {
+          const at = await ownedCheckout(run.repo, tree);
+          return parts[2] === "checkpoint-hunks" ? checkpointHunks(at, body) : applyCheckpointHunks(at, body);
+        }, { kind: "checkpoint-hunks", owner: run.id }) };
+      } catch (error) {
+        if (error instanceof WorkspaceConflictError) throw new HttpError(409, error.message);
+        throw error;
+      }
+    }
+    if (parts[2] === "file") {
+      const path = typeof body.path === "string" ? body.path : url.searchParams.get("path") ?? "";
+      if (req.method === "GET") return { status: 200, body: await readEditableFile(await readRepo(), path) };
+      if (req.method === "POST") {
+        const busy = manager.list().find((run) => run.status === "running" && (run.repo === selectedRepo || run.worktrees.some((tree) => tree.path === selectedRepo)));
+        if (busy) throw new HttpError(409, "Finish or stop the active run before editing its workspace");
+        try {
+          return { status: 200, body: await manager.withIdleRepository(selectedRepo, async () => saveEditableFile(await writeRepo(), path, body.text, body.expectedHash), { kind: "file-edit", owner: "workspace" }) };
+        } catch (error) {
+          if (error instanceof WorkspaceConflictError) throw new HttpError(409, error.message);
+          throw error;
+        }
+      }
+    }
+    if (parts[2] === "search" && req.method === "GET") return { status: 200, body: url.searchParams.get("mode") === "semantic" ? await searchSemanticSymbols(selectedRepo, url.searchParams.get("q") ?? "", signal) : await searchCode(await readRepo(), url.searchParams.get("q") ?? "", url.searchParams.get("mode") === "symbols" ? "symbols" : "text") };
+    if (parts[2] === "references" && req.method === "GET") return { status: 200, body: await findCodeReferences(selectedRepo, { path: url.searchParams.get("path") ?? "", line: Number(url.searchParams.get("line")), column: Number(url.searchParams.get("column")) }, signal) };
+    if (parts[2] === "dependencies" && req.method === "GET") return { status: 200, body: await inspectArchitecture(selectedRepo, signal) };
+    if (parts[2] === "checkpoints" && req.method === "GET") {
+      const at = await readRepo();
+      return { status: 200, body: { head: await resolveCommit(at), checkpoints: await checkpoints(at, url.searchParams.get("ref") || "HEAD") } };
+    }
+    if (parts[2] === "apply-checkpoint" && req.method === "POST") {
+      const run = typeof body.runId === "string" ? manager.get(body.runId) : void 0;
+      const tree = run?.worktrees.find((tree2) => tree2.path === selectedRepo);
+      if (!run || !tree || run.status === "running") throw new HttpError(409, "Choose an idle run worktree before applying checkpoint files");
+      if (!Array.isArray(body.paths) || body.paths.some((path) => typeof path !== "string")) throw new HttpError(400, "Choose repository paths");
+      return { status: 200, body: await manager.withIdleRepository(selectedRepo, async () => applyCheckpoint(await ownedCheckout(run.repo, tree), { source: String(body.source ?? ""), paths: body.paths, expectedHead: String(body.expectedHead ?? "") }), { kind: "checkpoint-files", owner: run.id }) };
+    }
+    if (parts[2] === "context" && req.method === "POST") {
+      try {
+        return { status: 200, body: await inspectContext({ repo: selectedRepo, baseRef: typeof body.baseRef === "string" ? body.baseRef : void 0, paths: body.paths, attachments: body.attachments, signal }) };
+      } catch (error) {
+        if (error instanceof ContextInspectionError) throw new HttpError(error.status, error.message);
+        throw error;
+      }
+    }
+  }
+  if (parts[1] === "diagnostics" && req.method === "GET") {
+    const packageJson = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+    const log = await diagnosticTail(join(CODEFLOW_HOME, "server.log"));
+    const runs = manager.list();
+    return { status: 200, body: redactExport({ version: 1, application: packageJson.version, node: process.version, platform: process.platform, at: Date.now(), busy: manager.busy, activity: manager.inspectRepositoryActivity(), writes: writeHealth, runs: { total: runs.length, active: runs.filter((run) => run.status === "running").length, interrupted: runs.filter((run) => run.status === "interrupted").length }, recentErrors: log.slice(-32e3), capabilities: { workspace: true, verificationProfiles: true }, git: repo ? await git(["--version"], repo).then((result) => result.stdout.trim()) : void 0 }) };
+  }
+  throw new HttpError(404, "Unknown workspace operation");
+}
+export {
+  handleWorkspaceApi
+};

package/src/workspace-changes.js

@@ -0,0 +1,61 @@
+import { createHash } from "node:crypto";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { git, resolveCommit, withRepoLock } from "./git.js";
+import { normalizeRepoPath } from "./repo-tree.js";
+import { readEditableFile, WorkspaceConflictError } from "./workspace.js";
+const digest = (text) => createHash("sha256").update(text).digest("hex");
+const MAX_TEXT = 512 * 1024;
+async function mergeFileDraft(repo, path, base, draft) {
+  if ([base, draft].some((value) => typeof value !== "string" || Buffer.byteLength(value) > MAX_TEXT || value.includes("\0"))) throw new Error("Merge drafts must be text under 512 KB");
+  const current = await readEditableFile(repo, path);
+  const folder = await mkdtemp(join(tmpdir(), "codeflow-file-merge-"));
+  try {
+    await Promise.all([["current", current.text], ["base", base], ["draft", draft]].map(([name, text]) => writeFile(join(folder, name), text, { mode: 384, flag: "wx" })));
+    const merged = await git(["merge-file", "--stdout", "--diff3", "-L", "Current file", "-L", "Loaded base", "-L", "Your draft", "current", "base", "draft"], folder, { timeoutMs: 1e4 });
+    if (merged.code < 0 || merged.code > 127 || merged.timedOut || merged.aborted || merged.stderr.trim()) throw new Error(merged.stderr.trim() || "Cannot merge the file drafts");
+    return { current, text: merged.stdout, conflicts: merged.code, clean: merged.code === 0 };
+  } finally {
+    await rm(folder, { recursive: true, force: true });
+  }
+}
+async function checkpointHunks(repo, input) {
+  const path = normalizeRepoPath(input.path);
+  if (!path || path.split("/").some((part) => part.toLowerCase() === ".git")) throw new Error("Choose a regular repository file outside .git");
+  await readEditableFile(repo, path);
+  const [head, source] = await Promise.all([resolveCommit(repo), resolveCommit(repo, input.source)]);
+  const modes = await Promise.all([head, source].map((ref) => git(["--literal-pathspecs", "ls-tree", "-z", ref, "--", path], repo)));
+  if (modes.some((result) => result.code || !/^100(?:644|755) blob /.test(result.stdout))) throw new Error("Hunks support existing regular text files. Apply added, deleted, renamed or binary files as complete files instead.");
+  const diff = await git(["--literal-pathspecs", "diff", "--no-ext-diff", "--no-textconv", "--no-color", "--unified=3", head, source, "--", path], repo);
+  if (diff.code) throw new Error(diff.stderr.trim() || "Cannot compare the checkpoint file");
+  if (diff.stdout.length > 2 * 1024 * 1024 || /^(?:Binary files |GIT binary patch)/m.test(diff.stdout)) throw new Error("The patch is binary or too large for selective hunks");
+  const first = diff.stdout.search(/^@@ /m);
+  if (first < 0) return { head, source, path, patchHeader: "", hunks: [] };
+  const patchHeader = diff.stdout.slice(0, first).replace(/^index .*\n/m, "");
+  const chunks = diff.stdout.slice(first).split(/(?=^@@ )/m).filter(Boolean);
+  if (chunks.length > 200) throw new Error("This file has too many hunks; apply the complete file instead");
+  return { head, source, path, patchHeader, hunks: chunks.map((patch) => ({ id: digest(`${head}\0${source}\0${path}\0${patch}`), header: patch.split("\n")[0], patch })) };
+}
+async function applyCheckpointHunks(repo, input) {
+  if (!Array.isArray(input.hunks) || input.hunks.length < 1 || input.hunks.length > 200 || input.hunks.some((id) => typeof id !== "string" || !/^[a-f0-9]{64}$/.test(id)) || new Set(input.hunks).size !== input.hunks.length) throw new Error("Choose 1\u2013200 distinct checkpoint hunks");
+  return withRepoLock(typeof repo === "string" ? repo : repo.path, async () => {
+    if (await resolveCommit(repo) !== input.expectedHead) throw new WorkspaceConflictError(await resolveCommit(repo));
+    const status = await git(["status", "--porcelain"], repo);
+    if (status.code || status.stdout.trim()) throw new Error("Commit or save existing changes before applying checkpoint hunks");
+    const preview = await checkpointHunks(repo, input);
+    const chosen = preview.hunks.filter((hunk) => input.hunks.includes(hunk.id));
+    if (chosen.length !== input.hunks.length) throw new Error("The checkpoint hunks changed. Refresh the comparison before applying");
+    const patch = preview.patchHeader + chosen.map((hunk) => hunk.patch).join("");
+    const checked = await git(["apply", "--check", "--whitespace=nowarn", "-"], repo, { input: patch });
+    if (checked.code) throw new Error(checked.stderr.trim() || "The selected hunks cannot be applied safely");
+    const applied = await git(["apply", "--whitespace=nowarn", "-"], repo, { input: patch });
+    if (applied.code) throw new Error(applied.stderr.trim() || "Cannot apply the selected hunks");
+    return { head: preview.head, source: preview.source, path: preview.path, hunks: input.hunks, staged: false };
+  });
+}
+export {
+  applyCheckpointHunks,
+  checkpointHunks,
+  mergeFileDraft
+};

package/src/workspace.js

@@ -0,0 +1,146 @@
+import { createHash, randomBytes } from "node:crypto";
+import { lstat, readFile, realpath, rename, unlink, writeFile } from "node:fs/promises";
+import { dirname, join, posix, sep } from "node:path";
+import { git, repoRoot, resolveCommit, withRepoLock } from "./git.js";
+import { normalizeRepoPath } from "./repo-tree.js";
+import { assertProjectFileAccess } from "./filesystem-policy.js";
+const MAX_EDIT_BYTES = 512 * 1024;
+class WorkspaceConflictError extends Error {
+  constructor(currentHash) {
+    super("This file changed since it was loaded. Reload and compare your draft before saving.");
+    this.currentHash = currentHash;
+  }
+}
+const hash = (text) => createHash("sha256").update(text).digest("hex");
+const folderOf = (repo) => typeof repo === "string" ? repo : repo.path;
+const rootOf = (repo) => typeof repo === "string" ? repoRoot(repo) : Promise.resolve(repo.path);
+async function editablePath(repo, path) {
+  const root = await realpath(await rootOf(repo));
+  const rel = normalizeRepoPath(path);
+  if (!rel || rel.split("/").some((part) => part.toLowerCase() === ".git")) throw new Error("Choose a regular repository file outside .git");
+  let current = root;
+  for (const part of rel.split("/")) {
+    current = join(current, part);
+    const info2 = await lstat(current);
+    if (info2.isSymbolicLink()) throw new Error("Editing symbolic links is refused; open the regular file instead");
+  }
+  const canonical = await realpath(current);
+  if (!canonical.startsWith(root + sep)) throw new Error("The file leaves the repository");
+  const info = await lstat(canonical);
+  if (!info.isFile() || info.size > MAX_EDIT_BYTES) throw new Error("Edit a regular text file under 512 KB");
+  return { root, path: rel, absolute: canonical };
+}
+async function readEditableFile(repo, path) {
+  await assertProjectFileAccess(folderOf(repo), path, "read");
+  const file = await editablePath(repo, path);
+  const text = await readFile(file.absolute, "utf8");
+  if (text.includes("\0")) throw new Error("Binary files cannot be edited as text");
+  await assertProjectFileAccess(folderOf(repo), path, "read");
+  return { path: file.path, text, hash: hash(text), bytes: Buffer.byteLength(text) };
+}
+async function saveEditableFile(repo, path, text, expectedHash) {
+  await assertProjectFileAccess(folderOf(repo), path, "write");
+  if (typeof text !== "string" || Buffer.byteLength(text) > MAX_EDIT_BYTES || text.includes("\0")) throw new Error("The file must be text under 512 KB without binary NUL characters");
+  if (!/^[a-f0-9]{64}$/.test(expectedHash)) throw new Error("Saving needs the hash of the loaded version");
+  return withRepoLock(await rootOf(repo), async () => {
+    const file = await editablePath(repo, path);
+    const before = await readEditableFile(repo, path);
+    if (before.hash !== expectedHash) throw new WorkspaceConflictError(before.hash);
+    const temp = join(dirname(file.absolute), `.codeflow-edit-${randomBytes(8).toString("hex")}`);
+    const mode = (await lstat(file.absolute)).mode & 511;
+    try {
+      await writeFile(temp, text, { flag: "wx", mode });
+      const current = await readEditableFile(repo, path);
+      if (current.hash !== expectedHash) throw new WorkspaceConflictError(current.hash);
+      await assertProjectFileAccess(folderOf(repo), path, "write");
+      await rename(temp, file.absolute);
+      return { path: file.path, hash: hash(text), bytes: Buffer.byteLength(text), savedAt: Date.now() };
+    } finally {
+      await unlink(temp).catch(() => void 0);
+    }
+  });
+}
+const definition = /^\s*(?:(?:export|default|public|private|protected|static|async|declare|abstract)\s+)*(?:(function|class|interface|type|enum|def|struct|fn|trait)\s+([\w$]+)|(?:const|let|var)\s+([\w$]+)\s*=)/;
+async function searchCode(repo, query, mode = "text") {
+  const root = await rootOf(repo);
+  const at = typeof repo === "string" ? root : repo;
+  const listing = await git(["-c", "core.fsmonitor=false", "ls-files", "-z", "--cached", "--others", "--exclude-standard"], at);
+  if (listing.code !== 0) throw new Error("Cannot list repository files");
+  const files = [...new Set(listing.stdout.split("\0").filter(Boolean))];
+  const needle = query.trim().toLowerCase();
+  if (!needle && mode === "text") return { hits: [], truncated: false, scanned: 0 };
+  if (query.length > 300) throw new Error("Search is limited to 300 characters");
+  const hits = [];
+  let scanned = 0, bytes = 0, truncated = false;
+  for (const path of files) {
+    if (scanned >= 2e3 || bytes > 8 * 1024 * 1024 || hits.length >= 200) {
+      truncated = true;
+      break;
+    }
+    if (/(^|\/)(?:node_modules|vendor|dist|build|\.git)\//.test(path)) continue;
+    const file = await readEditableFile(at, path).catch(() => void 0);
+    if (!file) continue;
+    scanned++;
+    bytes += file.bytes;
+    const lines = file.text.split("\n");
+    for (let index = 0; index < lines.length && hits.length < 200; index++) {
+      const text = lines[index];
+      const match = mode === "symbols" ? definition.exec(text) : null;
+      const symbol = match?.[2] ?? match?.[3];
+      if (mode === "symbols" ? symbol && (!needle || symbol.toLowerCase().includes(needle)) : text.toLowerCase().includes(needle)) hits.push({ path, line: index + 1, text: text.slice(0, 500), ...symbol ? { symbol, kind: match?.[1] ?? "variable" } : {} });
+    }
+  }
+  return { hits, scanned, truncated: truncated || hits.length >= 200 };
+}
+async function dependencyGraph(repo) {
+  const root = await rootOf(repo);
+  const at = typeof repo === "string" ? root : repo;
+  const listed = await git(["ls-files", "-z"], at);
+  if (listed.code !== 0) throw new Error("Cannot list repository files");
+  const all = new Set(listed.stdout.split("\0").filter((path) => /\.[cm]?[jt]sx?$/.test(path)));
+  const nodes = [...all].slice(0, 500), edges = [];
+  for (const path of nodes) {
+    const file = await readEditableFile(at, path).catch(() => void 0);
+    if (!file) continue;
+    for (const match of file.text.matchAll(/(?:\b(?:import|export)\s+(?:[^;\n]*?\s+from\s*)?|\b(?:require|import)\s*\()\s*["']([^"']+)["']/g)) {
+      const specifier = match[1];
+      if (!specifier.startsWith(".")) continue;
+      const base = posix.normalize(posix.join(posix.dirname(path), specifier));
+      const stem = base.replace(/\.[cm]?js$/, "");
+      const target = [base, `${stem}.ts`, `${stem}.tsx`, `${stem}.js`, `${base}/index.ts`, `${base}/index.tsx`, `${base}/index.js`].find((candidate) => all.has(candidate));
+      if (target) edges.push({ from: path, to: target, specifier });
+    }
+  }
+  return { nodes, edges, truncated: all.size > nodes.length, language: "JavaScript/TypeScript relative imports" };
+}
+async function checkpoints(repo, ref = "HEAD") {
+  const commit = await resolveCommit(repo, ref);
+  const log = await git(["log", "--max-count=50", "--format=%H%x00%at%x00%s", commit], repo);
+  if (log.code !== 0) throw new Error("Cannot read checkpoints");
+  return log.stdout.trim().split("\n").filter(Boolean).map((line) => {
+    const [sha, at, subject] = line.split("\0");
+    return { sha, at: Number(at) * 1e3, subject };
+  });
+}
+async function applyCheckpoint(repo, input) {
+  return withRepoLock(folderOf(repo), async () => {
+    const head = await resolveCommit(repo);
+    if (head !== input.expectedHead) throw new WorkspaceConflictError(head);
+    if ((await git(["status", "--porcelain"], repo)).stdout.trim()) throw new Error("Commit or save existing changes before applying a checkpoint");
+    const source = await resolveCommit(repo, input.source);
+    const paths = [...new Set(input.paths.map(normalizeRepoPath))];
+    if (!paths.length || paths.length > 100 || paths.some((path) => !path || path.split("/").some((part) => part.toLowerCase() === ".git"))) throw new Error("Choose 1\u2013100 repository paths");
+    const applied = await git(["--literal-pathspecs", "restore", `--source=${source}`, "--worktree", "--", ...paths], repo);
+    if (applied.code !== 0) throw new Error(applied.stderr.trim() || "Could not apply the selected paths");
+    return { head, source, paths, staged: false };
+  });
+}
+export {
+  WorkspaceConflictError,
+  applyCheckpoint,
+  checkpoints,
+  dependencyGraph,
+  readEditableFile,
+  saveEditableFile,
+  searchCode
+};