Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
17.9 KB
Raw Blame
/**
 * Sanitized read-only git reader (Project History Suite, t_c812752c).
 *
 * Every entry point shells out to the `git` binary with a FIXED argv via
 * `execFileSync` - no shell, no user-controlled flags, `--` separators
 * where paths could be ambiguous - following the proven
 * `src/core/discipline/activity-git.ts` pattern. The reader never
 * modifies the repository or its index.
 *
 * Caller-supplied SHAs are validated against the full-40-hex grammar
 * BEFORE they reach argv (`isFullSha`); anything else throws, so an
 * injection-shaped watermark can never become a git argument.
 *
 * Fail-soft contract: a missing repo, a non-repo directory, or a git
 * failure returns `null` (callers report "no history available"); an
 * EMPTY repository returns `[]` - "git works, zero commits" is a real
 * state the ingest watermark logic must distinguish from breakage.
 *
 * Commit records are parsed from `git log` with control-character field
 * separators: %x01 starts a record, %x00 separates fields, %x02 ends the
 * body. Control bytes cannot survive into commit metadata via normal git
 * usage, and a hand-crafted collision degrades to a skipped record, not
 * a corrupted neighbour.
 */

import { existsSync, statSync } from "node:fs";
import { execFileSync } from "node:child_process";
import { join, resolve } from "node:path";

export interface GitCommit {
  readonly sha: string;
  readonly authorName: string;
  readonly authorEmail: string;
  /** Author date, ISO-8601 strict. */
  readonly committedAt: string;
  readonly subject: string;
  readonly body: string;
  /** Repo-relative touched paths; empty for merge commits. */
  readonly files: ReadonlyArray<string>;
}

export interface GitTag {
  readonly name: string;
  /** Peeled commit sha (annotated tags resolve through the tag object). */
  readonly targetSha: string;
  /** Tag creation date, ISO-8601 strict; null when git reports none. */
  readonly createdAt: string | null;
}

export interface ReadCommitsOptions {
  /** Only commits AFTER this sha (exclusive), i.e. `<sha>..HEAD`. */
  readonly sinceSha?: string;
  /** Bound the walk; git keeps the NEWEST `maxCount` commits. */
  readonly maxCount?: number;
  /**
   * Restrict the walk to commits that touched this repo-relative path
   * (a git pathspec). Passed after a `--` separator so it can never be
   * mistaken for a flag. Empty/whitespace is ignored (no restriction).
   */
  readonly path?: string;
}

// Output-side separators. argv strings cannot carry raw NUL bytes
// (Node rejects them), so the FORMAT strings below spell these as
// git-side hex escapes (`%x00` in pretty formats, `%00` in
// for-each-ref formats) and git emits the raw bytes in its OUTPUT,
// where they are safe to split on.
const RECORD_START = "\x01";
const FIELD_SEP = "\x00";
const BODY_END = "\x02";

/** Exactly 40 lowercase hex characters - a full git object sha. */
export function isFullSha(value: unknown): value is string {
  return typeof value === "string" && /^[0-9a-f]{40}$/.test(value);
}

function isGitRepo(repoPath: string): boolean {
  try {
    if (!statSync(repoPath).isDirectory()) return false;
  } catch {
    return false;
  }
  return existsSync(join(resolve(repoPath), ".git"));
}

interface RunGitOptions {
  /**
   * Hard wall-clock bound for this invocation. Absent means "no bound",
   * which is the historical behaviour every pre-existing caller keeps.
   * A bounded caller (the workspace probe below, which runs inside a
   * hook's process ceiling) passes the remaining slice of its budget.
   */
  readonly timeoutMs?: number;
  /** Discard git's stderr instead of inheriting the parent's. */
  readonly quiet?: boolean;
}

function runGit(
  repoPath: string,
  args: ReadonlyArray<string>,
  opts: RunGitOptions = {},
): string | null {
  try {
    return execFileSync("git", ["-C", resolve(repoPath), ...args], {
      encoding: "utf8",
      maxBuffer: 64 * 1024 * 1024,
      // SIGKILL rather than SIGTERM: a git process wedged on a stalled
      // network filesystem is exactly the case the bound exists for, and
      // it is the case least likely to honour a polite signal.
      ...(opts.timeoutMs !== undefined
        ? { timeout: opts.timeoutMs, killSignal: "SIGKILL" as const }
        : {}),
      ...(opts.quiet === true ? { stdio: ["ignore", "pipe", "ignore"] as const } : {}),
    });
  } catch {
    // Fail-soft: a broken repo / missing git binary reads as "no
    // history", mirroring activity-git.ts. Callers that need to
    // distinguish breakage from emptiness check isGitRepo first.
    return null;
  }
}

/**
 * Read commits oldest-first. `null` when the directory is not a git
 * repo or git fails; `[]` for a repo with no commits (yet).
 */
export function readCommits(
  repoPath: string,
  opts: ReadCommitsOptions,
): ReadonlyArray<GitCommit> | null {
  if (!isGitRepo(repoPath)) return null;
  if (opts.sinceSha !== undefined && !isFullSha(opts.sinceSha)) {
    throw new Error(`sinceSha must be a full 40-hex git sha, got: ${String(opts.sinceSha)}`);
  }
  const args = [
    "log",
    "--name-only",
    "--pretty=format:%x01%H%x00%an%x00%ae%x00%aI%x00%s%x00%b%x02",
  ];
  if (opts.maxCount !== undefined) {
    args.push(`--max-count=${Math.max(1, Math.floor(opts.maxCount))}`);
  }
  if (opts.sinceSha !== undefined) args.push(`${opts.sinceSha}..HEAD`);
  const pathspec = opts.path?.trim();
  if (pathspec !== undefined && pathspec.length > 0) args.push("--", pathspec);
  const raw = runGit(repoPath, args);
  if (raw === null) {
    // `git log` exits non-zero on a repo with zero commits; report that
    // as empty history rather than breakage when the repo itself is fine.
    return emptyRepoOrNull(repoPath);
  }
  const commits: GitCommit[] = [];
  for (const record of raw.split(RECORD_START)) {
    if (record.trim() === "") continue;
    const bodyEnd = record.indexOf(BODY_END);
    if (bodyEnd === -1) continue; // collision-degraded record: skip
    const fields = record.slice(0, bodyEnd).split(FIELD_SEP);
    if (fields.length !== 6) continue;
    const [sha, authorName, authorEmail, committedAt, subject, body] = fields;
    if (!isFullSha(sha)) continue;
    const files = record
      .slice(bodyEnd + 1)
      .split("\n")
      .map((line) => line.trim())
      .filter((line) => line !== "");
    commits.push(
      Object.freeze({
        sha,
        authorName: authorName ?? "",
        authorEmail: authorEmail ?? "",
        committedAt: committedAt ?? "",
        subject: subject ?? "",
        body: (body ?? "").trim(),
        files: Object.freeze(files),
      }),
    );
  }
  return Object.freeze(commits.toReversed());
}

function emptyRepoOrNull(repoPath: string): ReadonlyArray<GitCommit> | null {
  const probe = runGit(repoPath, ["rev-parse", "--git-dir"]);
  return probe === null ? null : Object.freeze([]);
}

/**
 * List tags with peeled commit shas. `null` on non-repos / git failure,
 * `[]` on tagless repos.
 */
export function readTags(repoPath: string): ReadonlyArray<GitTag> | null {
  if (!isGitRepo(repoPath)) return null;
  const format =
    "%(refname:short)%00" +
    "%(if)%(*objectname)%(then)%(*objectname)%(else)%(objectname)%(end)%00" +
    "%(creatordate:iso-strict)";
  const raw = runGit(repoPath, ["tag", "--list", `--format=${format}`]);
  if (raw === null) return null;
  const tags: GitTag[] = [];
  for (const line of raw.split("\n")) {
    if (line.trim() === "") continue;
    const [name, targetSha, createdAt] = line.split(FIELD_SEP);
    if (name === undefined || name === "" || !isFullSha(targetSha)) continue;
    tags.push(
      Object.freeze({
        name,
        targetSha,
        createdAt: createdAt !== undefined && createdAt !== "" ? createdAt : null,
      }),
    );
  }
  return Object.freeze(tags);
}

/**
 * Shas reachable from `to` but not from `from`, oldest-first - the
 * standard changelog range. `from === null` means "everything up to
 * `to`" (the first tag's range).
 */
export function revListRange(
  repoPath: string,
  from: string | null,
  to: string,
): ReadonlyArray<string> | null {
  if (!isGitRepo(repoPath)) return null;
  if (from !== null && !isFullSha(from)) {
    throw new Error(`revListRange 'from' must be a full 40-hex git sha, got: ${String(from)}`);
  }
  if (!isFullSha(to)) {
    throw new Error(`revListRange 'to' must be a full 40-hex git sha, got: ${String(to)}`);
  }
  const raw = runGit(repoPath, ["rev-list", "--reverse", from === null ? to : `${from}..${to}`]);
  if (raw === null) return null;
  return Object.freeze(raw.split("\n").filter((line) => isFullSha(line.trim())));
}

// ----- Workspace identity (context-integrity-gates, Unit C) ----------------
//
// Session continuation needs to know whether two lifecycle observations
// happened in the SAME working state, not merely under the same `cwd`
// string. Repo, branch and commit are that state.

/**
 * What a working directory can attest about itself. Every field is
 * explicitly `null` when git could not report it (no remote, detached
 * HEAD, unborn branch), never absent - a caller comparing two
 * identities must be able to distinguish "not attested" from "attested
 * differently" without probing for key presence.
 */
export interface GitWorkspaceIdentity {
  /** Canonical remote identity - see {@link canonicalizeGitRemote}. */
  readonly repo: string | null;
  /** Short branch name; `null` on a detached HEAD. */
  readonly branch: string | null;
  /** Full 40-hex commit sha; `null` on an unborn branch. */
  readonly commit: string | null;
}

/** Default wall-clock bound for the whole workspace probe. */
export const GIT_PROBE_TIMEOUT_MS = 2_000;

/** `HEAD` is what `--abbrev-ref` prints for a detached checkout. */
const DETACHED_HEAD_REF = "HEAD";

/** `user@host:path` - the scp-like remote syntax, which is not a URL. */
const SCP_REMOTE_RE = /^(?<user>[^\s/@]+)@(?<host>[^\s/:]+):(?<path>(?!\/).+)$/;

/** `C:\` or `C:/` - an absolute Windows drive path, which is not a URL. */
const WINDOWS_DRIVE_PATH_RE = /^[A-Za-z]:[\\/]/;

/** `\\server\share\...` - a Windows UNC path, which is not a URL either. */
const UNC_PATH_RE = /^\\\\(?<host>[^\\/]+)[\\/](?<path>.+)$/;

/** A `file:` pathname that starts with a drive: `/c:/...` or a bare `/c:`. */
const FILE_URL_DRIVE_RE = /^\/([A-Za-z]):(?=\/|$)/;

/** A trailing `.git`, with or without trailing slashes already stripped. */
const DOT_GIT_SUFFIX_RE = /\.git$/;

/**
 * Reduce a git remote URL to a COMPARABLE repository identity of the
 * form `scheme://host/org/repo`, or `null` when the input names no
 * repository.
 *
 * This is a canonicalizer, NOT a redactor. `redactor.ts` rewrites
 * embedded credentials to a placeholder, which is right for a log and
 * useless as an identity key: two clones carrying different tokens
 * would produce the same placeholder string but a different one from a
 * credential-free clone of the same repository. Here userinfo, port, a
 * `.git` suffix and trailing slashes are normalized AWAY, so all three
 * clones compare equal - and, as a direct consequence, the credential
 * cannot survive into any recorded field.
 *
 * Host case is normalized (DNS is case-insensitive); path case is not
 * (many forges are case-sensitive, and folding it would merge two
 * genuinely distinct repositories) - except a Windows drive letter,
 * which is case-insensitive and is folded to upper case.
 *
 * Path remotes (POSIX, drive, UNC, scp-like) are escaped before parsing,
 * so their identity carries `#`, `?` and `%` percent-encoded.
 */
export function canonicalizeGitRemote(raw: unknown): string | null {
  if (typeof raw !== "string") return null;
  const trimmed = raw.trim();
  if (trimmed.length === 0) return null;

  const url = parseRemote(trimmed);
  if (url === null) return null;
  // A URL-shaped string with no authority is not a remote - except for
  // `file:`, whose authority is empty by construction.
  const isFile = url.protocol === "file:";
  if (!isFile && url.hostname.length === 0) return null;

  const path = canonicalRemotePath(isFile ? foldDriveLetter(url.pathname) : url.pathname);
  if (path === null) return null;
  return `${url.protocol}//${url.hostname}${path}`;
}

/**
 * Upper-case the drive letter of a `file:` pathname. Windows drive
 * letters are case-insensitive and git reports whichever spelling the
 * clone was made with, so `c:\x.git` and `C:\x.git` are one repository.
 * Only the letter is folded; the rest of the path keeps its case. Doing
 * it here rather than in the drive-path branch also folds an explicit
 * `file:///c:/...` remote and the identity an older version recorded.
 */
function foldDriveLetter(pathname: string): string {
  return pathname.replace(FILE_URL_DRIVE_RE, (_m, drive: string) => `/${drive.toUpperCase()}:`);
}

/**
 * Escape the characters of a filesystem path that are URL syntax, before
 * the path is placed into a URL to be parsed. `#` and `?` are legal in
 * directory names and would otherwise end the path (`/repos/c#1` and
 * `/repos/c#2` both parse as `/repos/c`); `%` goes first, so a literal
 * `%23` in a name stays distinct from an escaped `#`.
 */
function toFileUrlPath(path: string): string {
  return path.replaceAll("%", "%25").replaceAll("#", "%23").replaceAll("?", "%3F");
}

function parseRemote(value: string): URL | null {
  const scp = SCP_REMOTE_RE.exec(value);
  if (scp?.groups !== undefined) {
    return safeUrl(`ssh://${scp.groups["host"]}/${toFileUrlPath(scp.groups["path"]!)}`);
  }
  // An absolute filesystem path is a legitimate git remote and is not a
  // URL; give it the `file:` scheme so it lands in the same shape.
  if (value.startsWith("/")) return safeUrl(`file://${toFileUrlPath(value)}`);
  // A UNC path (`\\server\share\repo.git`) names a host, so it becomes a
  // `file:` URL WITH that authority instead of failing to parse at all.
  const unc = UNC_PATH_RE.exec(value);
  if (unc?.groups !== undefined) {
    const path = toFileUrlPath(unc.groups["path"]!.replaceAll("\\", "/"));
    return safeUrl(`file://${unc.groups["host"]}/${path}`);
  }
  // A Windows drive path (`C:\srv\git\x.git`, or git's own `C:/srv/...`
  // spelling) is the same kind of remote. Left to `new URL` it parses as
  // a `c:` scheme with no host and the identity is lost. Matched by shape
  // rather than host platform, so the identity is the same on every
  // device that reads the remote.
  if (WINDOWS_DRIVE_PATH_RE.test(value)) {
    return safeUrl(`file:///${toFileUrlPath(value.replaceAll("\\", "/"))}`);
  }
  return safeUrl(value);
}

function safeUrl(value: string): URL | null {
  try {
    return new URL(value);
  } catch {
    return null;
  }
}

function canonicalRemotePath(pathname: string): string | null {
  let path = pathname;
  while (path.endsWith("/")) path = path.slice(0, -1);
  path = path.replace(DOT_GIT_SUFFIX_RE, "");
  while (path.endsWith("/")) path = path.slice(0, -1);
  // `https://host` alone identifies a forge, not a repository.
  return path.length === 0 || path === "/" ? null : path;
}

/**
 * Resolve the probe's wall-clock budget from an optional caller value.
 *
 * Three cases, each stated rather than approximated:
 *
 *   - absent: the module default, which is what every production caller
 *     takes today;
 *   - a finite number at or below zero: the budget is ALREADY spent, so
 *     no git runs at all. This is the only way to express an exhausted
 *     budget; passing a small positive number instead leaves the first
 *     invocation that much budget and so asserts something about how
 *     fast the host's git is, not about the probe.
 *   - anything else finite: floored to whole milliseconds.
 *
 * A non-finite value is a caller bug and raises. Substituting the
 * default there would hand a two-second probe to a caller who believes
 * it asked for something else, inside a lifecycle hook whose own
 * process ceiling this must never consume.
 */
function resolveProbeBudgetMs(timeoutMs: number | undefined): number {
  if (timeoutMs === undefined) return GIT_PROBE_TIMEOUT_MS;
  if (!Number.isFinite(timeoutMs)) {
    throw new TypeError(
      `readGitWorkspaceIdentity: timeoutMs must be a finite number, got ${timeoutMs}`,
    );
  }
  return timeoutMs <= 0 ? 0 : Math.floor(timeoutMs);
}

/**
 * Probe `repoPath` for its workspace identity, or `null` when it is not
 * inside a git repository (or the probe's budget ran out).
 *
 * TWO git invocations, both through the hardened fixed-argv {@link
 * runGit}: `rev-parse HEAD --abbrev-ref HEAD` yields the commit and the
 * branch together, and `remote get-url origin` yields the remote. The
 * whole probe shares ONE wall-clock budget - each invocation gets only
 * what is left of it - because this runs inside a lifecycle hook whose
 * own process ceiling it must never consume.
 *
 * Deliberately NOT gated on {@link isGitRepo}: that helper looks for a
 * `.git` entry in the directory itself, so it reports `false` for every
 * SUBDIRECTORY of a repository, which is where a session's `cwd`
 * usually sits. git's own resolution walks upward and is the authority.
 */
export function readGitWorkspaceIdentity(
  repoPath: string,
  opts: { readonly timeoutMs?: number } = {},
): GitWorkspaceIdentity | null {
  const budgetMs = resolveProbeBudgetMs(opts.timeoutMs);
  const deadline = Date.now() + budgetMs;
  const probe = (args: ReadonlyArray<string>): string => {
    const remaining = deadline - Date.now();
    if (remaining <= 0) return "";
    return runGit(repoPath, args, { timeoutMs: remaining, quiet: true })?.trim() ?? "";
  };

  const [shaLine, refLine] = probe(["rev-parse", "HEAD", "--abbrev-ref", "HEAD"]).split("\n");
  const commit = isFullSha(shaLine?.trim()) ? shaLine!.trim() : null;
  const ref = refLine?.trim() ?? "";
  const branch = ref.length > 0 && ref !== DETACHED_HEAD_REF ? ref : null;
  const repo = canonicalizeGitRemote(probe(["remote", "get-url", "origin"]));

  if (repo === null && branch === null && commit === null) return null;
  return Object.freeze({ repo, branch, commit });
}

/** True when the (validated) sha resolves to a commit in this repo. */
export function shaExists(repoPath: string, sha: string): boolean {
  if (!isFullSha(sha)) return false;
  if (!isGitRepo(repoPath)) return false;
  return runGit(repoPath, ["cat-file", "-e", `${sha}^{commit}`]) !== null;
}