Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
16.8 KB
Raw Blame
/**
 * Capture v2: the git state of every repository a session works in.
 *
 *   - the root's own repository (`position: "root"`);
 *   - repositories in subfolders (`"nested"`): a folder holding `.git` (a
 *     directory, or a gitfile: a submodule or a linked worktree) found by
 *     the archive scan;
 *   - a repository whose work tree starts above the root (`"above"`): the
 *     root is a folder inside it; its relative position is recorded
 *     (`path: "../.."`); its `.git` alone is archived under
 *     `__enclosing_repo__/.git` (enclosing.ts), never its other files.
 *
 * Each gets HEAD, branch (also on an unborn branch: a repository without
 * commits), the remote without userinfo, the tracked-file count, the dirty
 * files with their status, the staged files and the stash count; or, when
 * git cannot read it, why (`error`).
 *
 * Why the old git blocks came back empty while the agent's own git commands
 * worked, and what this runner does about each:
 *   - `dubious ownership` (a folder owned by another user: a container
 *     running as root on a mounted checkout, a shared drive): git refuses
 *     the repository. The capture retries once with `safe.directory` set to
 *     that repository only, with fsmonitor and hooks off, and records it;
 *   - git environment inherited from the launching process (`GIT_DIR`,
 *     `GIT_WORK_TREE`, `GIT_INDEX_FILE`, ... when started from a git hook or
 *     `git rebase -x`) pointing git somewhere else: removed;
 *   - short timeouts under load (5 s for `rev-parse` while a full scan
 *     hashes the tree): 20 s here, and a timeout is reported, not hidden;
 *   - a repository created by the agent (`git init`, `git clone`) after the
 *     session started, or in a subfolder: found again at every state;
 *   - a plain-folder or touched-files chain never read git at all: every
 *     v2 state reads the repositories, whatever the chain's marker.
 */
import { gitChildEnv } from "../git-env.js";
import { spawn } from "node:child_process";
import { realpathSync } from "node:fs";
import { lstat, readFile } from "node:fs/promises";
import { homedir } from "node:os";
import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";

import { gitSkipReason } from "../command-guard.js";

export type RepoPosition = "root" | "nested" | "above";
export type RepoError = "timeout" | "dubious_ownership" | "not_a_repository" | "git_missing" | "failed";

export type RepoState = {
  path: string;
  position: RepoPosition;
  git_dir: string | null;
  gitfile: boolean;
  head: string | null;
  branch: string | null;
  unborn: boolean;
  remote: string | null;
  tracked_files: number | null;
  dirty: boolean;
  dirty_files: Array<{ path: string; status: string }>;
  dirty_truncated: boolean;
  staged_files: string[];
  stash_count: number;
  archived: "byte_exact" | "metadata_only";
  /** An enclosing repository (`position: "above"`): the session folder inside its work tree (its `.git` is archived under `__enclosing_repo__/.git`, enclosing.ts). */
  session_subdir?: string;
  safe_directory_override?: true;
  error: RepoError | null;
};

export const MAX_REPOS = 64;
const MAX_DIRTY_LISTED = 500;
/** One repository item of state.json stays far below the reader's 1 MiB item cap (backend spec 19.3). */
const MAX_LISTED_PATH_BYTES = 128 * 1024;

/** The first items of `items` whose paths fit `MAX_LISTED_PATH_BYTES` (and MAX_DIRTY_LISTED), and whether any was left out. */
function boundedList<T>(items: readonly T[], pathOf: (item: T) => string): { kept: T[]; truncated: boolean } {
  const kept: T[] = [];
  let bytes = 0;
  for (const item of items) {
    bytes += Buffer.byteLength(pathOf(item)) + 32;
    if (kept.length >= MAX_DIRTY_LISTED || bytes > MAX_LISTED_PATH_BYTES) return { kept, truncated: true };
    kept.push(item);
  }
  return { kept, truncated: false };
}
const GIT_TIMEOUT_MS = 20_000;
/** Variables that redirect git away from the folder it is run in. */
const REDIRECTING_GIT_ENV = [
  "GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE", "GIT_OBJECT_DIRECTORY", "GIT_ALTERNATE_OBJECT_DIRECTORIES",
  "GIT_COMMON_DIR", "GIT_NAMESPACE", "GIT_PREFIX", "GIT_CONFIG", "GIT_CONFIG_PARAMETERS", "GIT_CONFIG_COUNT",
  "GIT_DISCOVERY_ACROSS_FILESYSTEM", "GIT_EXEC_PATH",
];

/** The environment capture git runs with: no redirecting variables, no prompts, no optional locks, C locale. */
export function captureGitEnv(base: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
  const env: NodeJS.ProcessEnv = { ...base };
  for (const name of REDIRECTING_GIT_ENV) delete env[name];
  for (const name of Object.keys(env)) if (/^GIT_CONFIG_(?:KEY|VALUE)_\d+$/.test(name)) delete env[name];
  let home = homedir();
  try {
    home = realpathSync(home);
  } catch {
    // As given.
  }
  const ceiling = base.GIT_CEILING_DIRECTORIES;
  env.GIT_CEILING_DIRECTORIES = home ? (ceiling ? `${ceiling}${delimiter}${home}` : home) : ceiling ?? "";
  env.GIT_TERMINAL_PROMPT = "0";
  env.GIT_OPTIONAL_LOCKS = "0";
  env.GIT_PAGER = "cat";
  env.PAGER = "cat";
  env.LC_ALL = "C";
  return env;
}

export type RepoGitRun = { ok: boolean; stdout: Buffer; stderr: string; timedOut: boolean; missing: boolean; truncated: boolean };

/** One git run in `cwd`, read-only settings, bounded output; never throws. `onChunk` streams stdout instead of keeping it. */
export async function runRepoGit(
  cwd: string,
  args: string[],
  options: { maxBytes?: number; timeoutMs?: number; safeDirectory?: string; onChunk?: (chunk: Buffer) => void } = {},
): Promise<RepoGitRun> {
  // A Mac without the Command Line Tools: the git shim would open the installer (command-guard.ts).
  if (await gitSkipReason()) return { ok: false, stdout: Buffer.alloc(0), stderr: "", timedOut: false, missing: true, truncated: false };
  return spawnRepoGit(cwd, args, options);
}

function spawnRepoGit(
  cwd: string,
  args: string[],
  options: { maxBytes?: number; timeoutMs?: number; safeDirectory?: string; onChunk?: (chunk: Buffer) => void },
): Promise<RepoGitRun> {
  const maxBytes = options.maxBytes ?? 256 * 1024;
  return new Promise((resolvePromise) => {
    const out: Buffer[] = [];
    const err: Buffer[] = [];
    let total = 0;
    let errTotal = 0;
    let truncated = false;
    let timedOut = false;
    let settled = false;
    let child: ReturnType<typeof spawn> | null = null;
    const finish = (ok: boolean, missing = false) => {
      if (settled) return;
      settled = true;
      clearTimeout(timer);
      resolvePromise({ ok, stdout: Buffer.concat(out), stderr: Buffer.concat(err).toString("utf8"), timedOut, missing, truncated });
    };
    const timer = setTimeout(() => {
      timedOut = true;
      child?.kill("SIGKILL");
      finish(false);
    }, options.timeoutMs ?? GIT_TIMEOUT_MS);
    timer.unref?.();
    const config = [
      "-c", "core.fsmonitor=false", "-c", "core.quotePath=false", "-c", `core.hooksPath=${process.platform === "win32" ? "NUL" : "/dev/null"}`,
      ...(options.safeDirectory ? ["-c", `safe.directory=${options.safeDirectory}`] : []),
    ];
    try {
      child = spawn("git", ["-C", cwd, ...config, ...args], { stdio: ["ignore", "pipe", "pipe"], windowsHide: true, env: captureGitEnv(gitChildEnv()) });
    } catch {
      finish(false, true);
      return;
    }
    child.stdout?.on("data", (chunk: Buffer) => {
      if (options.onChunk) {
        options.onChunk(chunk);
        return;
      }
      if (truncated) return;
      const room = maxBytes - total;
      if (chunk.length > room) {
        out.push(chunk.subarray(0, room));
        total = maxBytes;
        truncated = true;
        child?.kill("SIGKILL");
        return;
      }
      out.push(chunk);
      total += chunk.length;
    });
    child.stderr?.on("data", (chunk: Buffer) => {
      if (errTotal < 16 * 1024) {
        err.push(chunk);
        errTotal += chunk.length;
      }
    });
    child.on("error", (error: NodeJS.ErrnoException) => finish(false, error.code === "ENOENT"));
    child.on("close", (code) => finish(!timedOut && (truncated || code === 0)));
  });
}

function errorOf(run: RepoGitRun): RepoError {
  if (run.missing) return "git_missing";
  if (run.timedOut) return "timeout";
  if (/dubious ownership|safe\.directory/i.test(run.stderr)) return "dubious_ownership";
  if (/not a git repository/i.test(run.stderr)) return "not_a_repository";
  return "failed";
}

function portable(path: string): string {
  return sep === "/" ? path : path.split(sep).join("/");
}

/** Strips `user:password@` from a remote URL (scheme form) and the password from an scp form. */
export function stripRemoteCredentials(url: string): string {
  const trimmed = url.trim();
  const scheme = /^([a-z][a-z0-9+.-]*:\/\/)(?:[^/@]*@)?(.*)$/i.exec(trimmed);
  if (scheme) return `${scheme[1]}${scheme[2]}`;
  const scp = /^([^/@:\s]+)(?::[^@/]*)?@([^/:\s]+:.*)$/.exec(trimmed);
  if (scp) return `${scp[1]}@${scp[2]}`;
  return trimmed;
}

type Located = { top: string; gitDir: string; safeDirectory?: string } | { error: RepoError };

async function locate(dir: string): Promise<Located> {
  const args = ["rev-parse", "--show-toplevel", "--absolute-git-dir"];
  let run = await runRepoGit(dir, args, { maxBytes: 64 * 1024 });
  let safeDirectory: string | undefined;
  if (!run.ok && errorOf(run) === "dubious_ownership") {
    // Only this repository, never `*`: the user's own folder the agent works in.
    const match = /repository at '([^']+)'/.exec(run.stderr);
    safeDirectory = match?.[1] ?? dir;
    run = await runRepoGit(dir, args, { maxBytes: 64 * 1024, safeDirectory });
  }
  if (!run.ok) return { error: errorOf(run) };
  const [top, gitDir] = run.stdout.toString("utf8").split(/\r?\n/);
  if (!top || !gitDir) return { error: "not_a_repository" };
  return { top, gitDir, ...(safeDirectory ? { safeDirectory } : {}) };
}

function within(root: string, path: string): string | null {
  const rel = relative(root, path);
  if (rel === "") return "";
  if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return null;
  return portable(rel);
}

/** Parses `git status --porcelain=v1 -z` into dirty and staged files. */
export function parsePorcelainZ(text: string): { dirty: Array<{ path: string; status: string }>; staged: string[] } {
  const dirty: Array<{ path: string; status: string }> = [];
  const staged: string[] = [];
  const parts = text.split("\0");
  for (let index = 0; index < parts.length; index += 1) {
    const item = parts[index]!;
    if (item.length < 4) continue;
    const status = item.slice(0, 2);
    const path = item.slice(3);
    dirty.push({ path, status });
    if (status[0] !== " " && status[0] !== "?" && status[0] !== "!") staged.push(path);
    // A rename or copy is followed by its source path.
    if (status[0] === "R" || status[0] === "C") index += 1;
  }
  return { dirty, staged };
}

/** The state of the repository whose work tree is `top`, as seen from `root`. */
export async function readRepoState(root: string, located: { top: string; gitDir: string; safeDirectory?: string }, position: RepoPosition, gitfile: boolean): Promise<RepoState> {
  const { top, gitDir, safeDirectory } = located;
  const opt = (extra: { maxBytes?: number; timeoutMs?: number } = {}) => ({ ...extra, ...(safeDirectory ? { safeDirectory } : {}) });
  let tracked = 0;
  const [head, branch, remotes, status, lsFiles, stash] = await Promise.all([
    runRepoGit(top, ["rev-parse", "--verify", "-q", "HEAD"], opt()),
    runRepoGit(top, ["symbolic-ref", "--short", "-q", "HEAD"], opt()),
    runRepoGit(top, ["remote"], opt()),
    runRepoGit(top, ["status", "--porcelain=v1", "-z", "--no-renames", "--untracked-files=normal"], opt({ maxBytes: 4 * 1024 * 1024 })),
    runRepoGit(top, ["ls-files", "-z"], {
      ...opt(),
      onChunk: (chunk) => {
        for (const byte of chunk) if (byte === 0) tracked += 1;
      },
    }),
    runRepoGit(top, ["rev-list", "--walk-reflogs", "--count", "refs/stash"], opt()),
  ]);
  const headText = head.ok ? head.stdout.toString("utf8").trim() : "";
  const branchText = branch.ok ? branch.stdout.toString("utf8").trim() : "";
  const names = remotes.ok ? remotes.stdout.toString("utf8").split(/\r?\n/).map((name) => name.trim()).filter(Boolean) : [];
  const remoteName = names.includes("origin") ? "origin" : names[0];
  const remoteUrl = remoteName ? await runRepoGit(top, ["remote", "get-url", remoteName], opt()) : null;
  const parsed = status.ok ? parsePorcelainZ(status.stdout.toString("utf8")) : { dirty: [], staged: [] };
  const dirtyListed = boundedList(parsed.dirty, (item) => item.path);
  const stagedListed = boundedList(parsed.staged, (path) => path);
  const relTop = relative(root, top);
  const insideRoot = within(root, gitDir) !== null;
  const failed = [status, lsFiles].find((run) => !run.ok && !run.truncated);
  return {
    path: portable(relTop),
    position,
    git_dir: insideRoot ? within(root, gitDir) : null,
    gitfile,
    head: /^[0-9a-f]{40,64}$/.test(headText) ? headText : null,
    branch: branchText || null,
    unborn: !/^[0-9a-f]{40,64}$/.test(headText) && Boolean(branchText),
    remote: remoteUrl?.ok ? stripRemoteCredentials(remoteUrl.stdout.toString("utf8").trim()) || null : null,
    tracked_files: lsFiles.ok ? tracked : null,
    dirty: parsed.dirty.length > 0,
    dirty_files: dirtyListed.kept,
    dirty_truncated: dirtyListed.truncated || stagedListed.truncated || status.truncated,
    staged_files: stagedListed.kept,
    stash_count: stash.ok ? Number.parseInt(stash.stdout.toString("utf8").trim(), 10) || 0 : 0,
    archived: position !== "above" && insideRoot ? "byte_exact" : "metadata_only",
    // The session folder inside an enclosing repository's work tree (`packages/app`).
    ...(position === "above" ? { session_subdir: portable(relative(realpathOr(top), realpathOr(root))) } : {}),
    ...(safeDirectory ? { safe_directory_override: true as const } : {}),
    error: failed ? errorOf(failed) : null,
  };
}

/** A repository marker git could not read: recorded with the reason. */
function unreadable(root: string, dir: string, position: RepoPosition, gitfile: boolean, error: RepoError): RepoState {
  return {
    path: portable(relative(root, dir)), position, git_dir: null, gitfile, head: null, branch: null, unborn: false, remote: null,
    tracked_files: null, dirty: false, dirty_files: [], dirty_truncated: false, staged_files: [], stash_count: 0, archived: "metadata_only", error,
  };
}

/**
 * Every repository of the session: `markers` are the root-relative paths of
 * the `.git` entries the archive scan found (`.git`, `sub/x/.git`), with
 * whether each is a gitfile. The root's enclosing repository (above the
 * root) is found by git itself, never above home.
 */
export async function discoverRepos(root: string, markers: ReadonlyArray<{ path: string; gitfile: boolean }>): Promise<RepoState[]> {
  const absRoot = resolve(root);
  const repos: RepoState[] = [];
  const seenTops = new Set<string>();
  const ordered = [...markers].sort((left, right) => left.path.split("/").length - right.path.split("/").length).slice(0, MAX_REPOS);
  const hasRootMarker = ordered.some((marker) => marker.path === ".git");
  if (!hasRootMarker) {
    // The root inside a larger repository (or none).
    const located = await locate(absRoot);
    if ("top" in located) {
      const rel = relative(absRoot, located.top);
      if (rel !== "" && (rel === ".." || rel.startsWith(`..${sep}`))) {
        seenTops.add(located.top);
        repos.push(await readRepoState(absRoot, located, "above", false));
      }
    } else if (located.error === "dubious_ownership" || located.error === "timeout" || located.error === "git_missing") {
      repos.push(unreadable(absRoot, absRoot, "above", false, located.error));
    }
  }
  for (const marker of ordered) {
    const dir = marker.path === ".git" ? absRoot : join(absRoot, ...marker.path.split("/").slice(0, -1));
    const position: RepoPosition = marker.path === ".git" ? "root" : "nested";
    const located = await locate(dir);
    if ("error" in located) {
      repos.push(unreadable(absRoot, dir, position, marker.gitfile, located.error));
      continue;
    }
    // `.git` folders of a repository's own internals or a broken marker resolving elsewhere are not repositories of their own.
    if (resolve(located.top) !== resolve(dir) && realpathOr(located.top) !== realpathOr(dir)) continue;
    if (seenTops.has(located.top)) continue;
    seenTops.add(located.top);
    repos.push(await readRepoState(absRoot, located, position, marker.gitfile));
  }
  return repos;
}

function realpathOr(path: string): string {
  try {
    return realpathSync(path);
  } catch {
    return resolve(path);
  }
}

/** Whether `path` (absolute) holds a `.git` gitfile, and where it points. */
export async function readGitfile(path: string): Promise<string | null> {
  try {
    const info = await lstat(path);
    if (!info.isFile() || info.size > 4096) return null;
    const match = /^gitdir:\s*(.+?)\s*$/m.exec(await readFile(path, "utf8"));
    return match ? resolve(dirname(path), match[1]!) : null;
  } catch {
    return null;
  }
}