@repo-os/repoos 0.5.45

package/dist/core/git.d.ts

@@ -0,0 +1,505 @@
+import type { TaskGitInfo } from "./types.js";
+export interface GitRun {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    /** True when the child was SIGKILLed because it exceeded the timeout. */
+    timedOut?: boolean;
+}
+/**
+ * Non-blocking `spawn` that resolves with the exit status and captured output.
+ * Never throws; a timeout kills the child. Unlike `spawnSync` this does not
+ * freeze the server's event loop, so SSE progress events can flush in real
+ * time while a long command (merge, build, check) is in flight.
+ */
+export declare function runGit(root: string, args: string[], timeout: number): Promise<GitRun>;
+export declare function isGitRepo(root: string): boolean;
+export declare function currentBranch(root: string): string | null;
+/** ISO-8601 commit date of HEAD at `root` (a worktree or the main checkout), or null. */
+export declare function headCommitISO(root: string): string | null;
+/** Set of local branch names, fetched once and reused across tasks. */
+export declare function localBranches(root: string): Set<string>;
+/**
+ * Commits-ahead count for EVERY local branch relative to `base`, in a single
+ * `git for-each-ref` call. The indexer needs "does this task's branch have
+ * unmerged commits" for every task; the per-branch alternative
+ * (`git rev-list --count base..branch` once per task) was ~2.5s of the index
+ * build on a repo with ~40 task branches.
+ *
+ * `%(ahead-behind:<base>)` needs git ≥ 2.41 (2023-06); on older git the field
+ * renders empty and this returns an empty map, so callers fall back to
+ * `rev-list` per branch. Fail-soft: empty map when git is missing.
+ */
+export declare function branchAheadCounts(root: string, base: string | null): Map<string, number>;
+/** Last commit subject + ISO date touching a specific file. */
+export declare function lastCommitForFile(root: string, relPath: string): {
+    subject: string | null;
+    date: string | null;
+};
+/** Async counterpart of lastCommitForFile - see gitAsync. */
+export declare function lastCommitForFileAsync(root: string, relPath: string): Promise<{
+    subject: string | null;
+    date: string | null;
+}>;
+export type LastCommit = {
+    subject: string | null;
+    date: string | null;
+};
+/**
+ * Last commit subject + ISO date for EVERY tracked file under `relDir`, in a
+ * SINGLE `git log` pass. The indexer needs this for every task file; calling
+ * `lastCommitForFile` per task instead runs one full history walk per file,
+ * which was a large share of RepoOS's slow index build at 200+ tasks (#0271
+ * follow-up). Keys are paths relative to `root`, matching `Task.path`.
+ * Fail-soft: an empty map when git is missing or the walk fails.
+ */
+export declare function lastCommitsForDir(root: string, relDir: string): Map<string, LastCommit>;
+/** Async counterpart of `lastCommitsForDir` - see `gitAsync`. */
+export declare function lastCommitsForDirAsync(root: string, relDir: string): Promise<Map<string, LastCommit>>;
+/**
+ * Turn on git's own fast-status machinery for `root` (and, since worktrees
+ * share `.git/config`, every task worktree cut from it). RepoOS runs
+ * `git status --porcelain` once per task worktree on every index build; on a
+ * large monorepo each of those is a full tree stat-walk. `core.fsmonitor`
+ * lets git's builtin file-system-monitor daemon (git ≥ 2.37, macOS/Windows/
+ * Linux) skip unchanged directories, and `core.untrackedCache` caches the
+ * per-directory untracked-file scan. Both are opt-in per repo and safe:
+ * git falls back to a full scan if the daemon is unavailable.
+ *
+ * Idempotent, best-effort, and cheap — call it once at startup. Skips any key
+ * already set to the desired value, so a repo that has been tuned once pays
+ * only two `git config --get` reads on subsequent boots.
+ */
+export declare function tuneRepoForScale(root: string): void;
+/**
+ * True when git tracks `relPath` in the checkout at `root` and its working
+ * copy matches HEAD — i.e. whatever the file currently shows is backed by a
+ * commit, not a stray mid-edit. Untracked or dirty files return false.
+ * Used to prove a worktree's committed task-file state before trusting it.
+ */
+export declare function fileCommittedClean(root: string, relPath: string): boolean;
+export declare function emptyGitInfo(): TaskGitInfo;
+export interface EnsureWorktreeResult {
+    ok: boolean;
+    /** Absolute path of the working directory the agent should use. */
+    path: string;
+    /** True when a brand-new worktree was created. */
+    created: boolean;
+    /** Human-readable failure reason (when not ok). */
+    reason?: string;
+}
+export interface WorktreeEntry {
+    /** Absolute path of the linked worktree. */
+    path: string;
+    /** The commit SHA the worktree currently has checked out. */
+    head: string;
+}
+/**
+ * Branch -> { path, head } for every registered linked worktree, derived from
+ * a single `git worktree list --porcelain`. Empty map when git is missing.
+ * Callers resolving several branches at once (indexer, live index) MUST call
+ * this once and reuse the map — every call shells out to git.
+ *
+ * `head` lets a caller skip an expensive per-worktree `git status` when the
+ * worktree has not moved since a cached check (see the indexer's worktree
+ * dirty-status cache).
+ */
+export declare function worktreeList(root: string): Map<string, WorktreeEntry>;
+export interface WorktreeInfo {
+    /** Absolute path of the linked worktree (as git reports it). */
+    path: string;
+    /** Checked-out branch, or null for a detached HEAD. */
+    branch: string | null;
+    /** The commit SHA the worktree currently has checked out. */
+    head: string;
+    /** True for the repository's own main checkout (`git worktree list` lists it first). */
+    isMain: boolean;
+    /** True for a bare repository entry. */
+    isBare: boolean;
+}
+/**
+ * Every entry from `git worktree list --porcelain`, including detached-HEAD and
+ * bare entries that `worktreeList` (branch-keyed) necessarily drops. The garbage
+ * collector needs the full picture so it can also prune worktrees that lost
+ * their branch ref. Empty when git is missing.
+ */
+export declare function listWorktrees(root: string): WorktreeInfo[];
+/**
+ * Branch -> worktree path for every registered linked worktree. Thin
+ * projection of `worktreeList` kept for the many callers that only need the
+ * path; prefer `worktreeList` when you also want the checked-out SHA.
+ */
+export declare function worktreePaths(root: string): Map<string, string>;
+/**
+ * Absolute path of the worktree that has `branch` checked out, or null when the
+ * branch has no linked worktree (or git is missing). The main checkout's own
+ * branch resolves to the repo root. Uses `git worktree list --porcelain` —
+ * never string concatenation — so branch names with `/` and exotic characters
+ * resolve correctly.
+ */
+export declare function worktreePathForBranch(root: string, branch: string): string | null;
+/**
+ * Make sure the agent for `branch` has a dedicated working directory WITHOUT
+ * touching the main worktree's checkout. Three outcomes:
+ *
+ *  - branch is what the main worktree already has checked out -> use root
+ *  - branch already has a linked worktree -> reuse it (idempotent)
+ *  - otherwise -> `git worktree add` a sibling directory for it
+ *
+ * Fail-soft like the branch-switching predecessor: returns `{ ok: false,
+ * reason }` when git is missing or the worktree can't be created, so agent
+ * launch degrades gracefully instead of crashing the server.
+ *
+ * `taskRelPath`, when given, is the task's own file path relative to `root`
+ * (e.g. `work/0151-....md`). Whichever worktree is resolved — new or reused —
+ * is healed if that file is missing from it; see `healMissingTaskFile`.
+ */
+export declare function ensureWorktree(root: string, branch: string, taskRelPath?: string): EnsureWorktreeResult;
+export interface WorktreeStatus {
+    /** Absolute path of the linked worktree for `branch`, or null. */
+    path: string | null;
+    /**
+     * Whether a clean restart would discard prior work: the linked worktree has
+     * uncommitted changes, or the branch has commits not in the main checkout's
+     * branch. False when no linked worktree exists — the main checkout itself
+     * is never a task worktree.
+     */
+    dirty: boolean;
+}
+/**
+ * Best-effort facts about a task's worktree, derived from `git worktree list`
+ * plus a status check inside the worktree. Fail-soft: any git failure yields
+ * a safe `{ path: null, dirty: false }`.
+ *
+ * `opts.worktrees`/`opts.baseBranch` let a caller looping over many tasks
+ * against the same repo (e.g. `buildIndex`) pass in a `worktreePaths`/
+ * `currentBranch` result it already fetched once, instead of this function
+ * re-running those two `git` spawns on every single task (#0271 follow-up:
+ * this redundancy was a large share of RepoOS's slow boot with 260+ tasks).
+ * Omit them and behavior is unchanged — each call fetches fresh.
+ */
+export declare function worktreeStatus(root: string, branch: string, opts?: {
+    worktrees?: Map<string, string>;
+    baseBranch?: string | null;
+}): WorktreeStatus;
+/** Async counterpart of `worktreeStatus` — see `gitAsync`. */
+export declare function worktreeStatusAsync(root: string, branch: string, opts?: {
+    worktrees?: Map<string, string>;
+    baseBranch?: string | null;
+}): Promise<WorktreeStatus>;
+/** Per-branch working-tree dirtiness, keyed to the SHA it was checked at. */
+export interface WorktreeDirtyEntry {
+    /** The worktree HEAD SHA this `uncommitted` value was computed against. */
+    head: string;
+    /** True when `git status --porcelain` in the worktree was non-empty. */
+    uncommitted: boolean;
+}
+export type WorktreeDirtyCache = Map<string, WorktreeDirtyEntry>;
+/**
+ * Resolve `WorktreeStatus` for MANY branches with a bounded number of git
+ * spawns instead of three per branch:
+ *
+ *  - one `git worktree list --porcelain` (paths + HEAD SHAs)
+ *  - one `git for-each-ref` for every branch's ahead count
+ *  - one `git status --porcelain` per worktree WHOSE HEAD MOVED since `cache`
+ *    (all of them on a cold cache; usually none on a server reload)
+ *
+ * `opts.cache` is consulted and updated in place; `changed` says whether it
+ * needs persisting. `opts.skipStatus` returns the cached dirtiness verbatim
+ * and never runs `git status` — the fast boot path, paired with a later
+ * reconcile sweep. Fail-soft throughout: a git failure yields
+ * `{ path: null, dirty: false }` for that branch, matching `worktreeStatus`.
+ */
+export declare function resolveWorktreeStatuses(root: string, branches: Iterable<string>, opts: {
+    baseBranch: string | null;
+    cache?: WorktreeDirtyCache;
+    skipStatus?: boolean;
+}): Promise<{
+    statuses: Map<string, WorktreeStatus>;
+    cache: WorktreeDirtyCache;
+    changed: boolean;
+}>;
+/**
+ * Discard a task's worktree AND its branch so the next `ensureWorktree`
+ * re-creates both from the main checkout's HEAD — a clean restart. The main
+ * checkout itself is never touched. Fail-soft: false when git is missing,
+ * the branch is the main checkout, or a removal step failed.
+ */
+export declare function resetWorktree(root: string, branch: string): boolean;
+export interface BranchChangesSinceBase {
+    /** Short ref of the branch point (merge-base), or null when undeterminable. */
+    base: string | null;
+    /** Paths that differ from the branch point, committed or uncommitted. */
+    paths: string[];
+}
+/**
+ * What the branch checked out in `worktree` has changed relative to its branch
+ * point — the merge-base with `baseBranch` — combining already-committed
+ * changes with the current uncommitted working-tree diff. This is the correct
+ * base for "did the agent implement anything": diffing against `baseBranch`
+ * itself would count unrelated main drift as the branch's own work. When the
+ * base cannot be resolved (no git, or the two branches share no ancestor)
+ * returns `{ base: null, paths: [] }` so callers can fail soft rather than
+ * block on a false positive.
+ */
+export declare function branchChangesSinceBase(worktree: string, baseBranch: string): BranchChangesSinceBase;
+export interface DiffStats {
+    filesChanged: number;
+    additions: number;
+    deletions: number;
+}
+export interface DiffResult {
+    patch: string;
+    truncated: boolean;
+}
+/**
+ * Get diff statistics comparing a branch point to the current worktree.
+ * This deliberately includes committed, staged, and unstaged source edits so
+ * the task drawer can show an agent's work before its handoff commit.
+ * Generated build output is excluded because it is not task source.
+ * Returns file count and line additions/deletions.
+ */
+export declare function getDiffStats(worktree: string, baseBranch: string): DiffStats;
+/**
+ * Non-blocking counterpart to `getDiffStats`, built on `runGit` (`spawn`)
+ * instead of `git`'s `execFileSync`. Every task card on the Work board fetches
+ * its diff stats on mount (`TaskCard.vue`), so a board with N cards fires N
+ * of these on every reload/tab-switch; the synchronous version froze the
+ * entire server's event loop for the duration of all of them serially —
+ * including whatever `GET /api/tasks/:id` a drawer-opening click was waiting
+ * on — which is what made the drawer take several seconds to appear.
+ */
+export declare function getDiffStatsAsync(worktree: string, baseBranch: string): Promise<DiffStats>;
+/**
+ * Get the full patch diff from a branch point to the current worktree.
+ * This includes committed, staged, and unstaged source edits, while leaving
+ * generated build output out of the task-facing code review view.
+ * Bounded at MAX_DIFF_BYTES to avoid sending giant payloads.
+ */
+export declare function getDiff(worktree: string, baseBranch: string): Promise<DiffResult>;
+/**
+ * The paths changed between `baseBranch` and the current worktree HEAD
+ * (`git diff --name-only <baseBranch> HEAD`), used by the close-out gate's
+ * docs-only fast path (#0355) to decide whether the full build/check gate can
+ * be skipped.
+ *
+ * Unlike `getDiff`/`getDiffStats`, this deliberately does NOT go through
+ * `merge-base`: the caller wants the cumulative difference between the base
+ * branch tip and the candidate commit (which already contains the merge), not
+ * the branch's own commits. Returns `null` — never `[]` — when git errors or
+ * times out, so a caller can distinguish "no changes" from "could not tell"
+ * and fail safe by running the full gate.
+ */
+export declare function getChangedFilePaths(worktree: string, baseBranch: string, timeout?: number): Promise<string[] | null>;
+/** Whether git is installed at all (independent of being inside a repo). */
+export declare function gitAvailable(root: string): boolean;
+/** `git config --get <key>` value, or null when unset or git is missing. */
+export declare function gitConfig(root: string, key: string): string | null;
+/** Run `git init` in root. True on success. */
+export declare function gitInit(root: string): boolean;
+/**
+ * Commit the ENTIRE working tree. Only for a freshly scaffolded repo where
+ * nothing else is pre-staged (the guided `repoos init` flow) — do NOT use this
+ * where 0023's surgical `commitNewFile` applies. Fail-soft: null on failure.
+ */
+export declare function gitCommitAll(root: string, message: string): string | null;
+export interface CommitNewFileResult {
+    ok: boolean;
+    /** Short commit hash (when committed). */
+    hash?: string;
+    /** Human-readable failure reason (when not committed). */
+    reason?: string;
+}
+/**
+ * Surgically commit a single new file with the user's own git identity.
+ *
+ * `git commit --only` refuses paths git doesn't know, so we first run
+ * `git add -N` (intent-to-add): it registers the path WITHOUT staging any
+ * content, then `git commit -o -m <msg> -- <file>` commits only that file's
+ * working-tree content and IGNORES whatever else is staged or dirty. Never
+ * `git add -A`, never a plain `git commit`, never amend/force, hooks run.
+ *
+ * Fail-soft: never throws, never leaves content partially staged. On any
+ * problem it returns `{ ok: false, reason }` and the caller keeps the file.
+ */
+export declare function commitNewFile(root: string, absPath: string, message: string): CommitNewFileResult;
+/**
+ * Whether `ancestor` is an ancestor of `descendant` (i.e. a fast-forward merge
+ * of `descendant` into a checkout on `ancestor` is possible). Uses
+ * `git merge-base --is-ancestor` exit codes; null when git is missing or the
+ * refs are invalid.
+ */
+export declare function isAncestor(root: string, ancestor: string, descendant: string): boolean | null;
+export interface MergeBranchResult {
+    /** Whether the branch was merged into the current checkout. */
+    merged: boolean;
+    /** Whether the merge was a fast-forward (or the branch was already in). */
+    ff: boolean;
+    /** Files with merge conflicts when the merge aborted. */
+    conflicts: string[];
+    /** Human-readable failure reason (not merged and not a conflict). */
+    reason?: string;
+}
+export interface PreflightMergeResult {
+    /** True when the merge would complete without source conflicts. */
+    ok: boolean;
+    /** True when main is not an ancestor of the branch (a merge commit would be required). */
+    drifted: boolean;
+    /** Conflicted source file paths when `ok` is false. */
+    conflicts: string[];
+    /** Human-readable failure reason. */
+    reason?: string;
+}
+/**
+ * Cheap, non-destructive pre-flight for merging `branch` into the CURRENT
+ * checkout. Uses `git merge --no-commit` and always aborts, so the working
+ * tree is left untouched (blocking files may be committed first, as the real
+ * `mergeBranch` does, to keep the pre-flight honest).
+ *
+ * Returns `ok: true` for a clean merge (fast-forward or merge commit), and
+ * `ok: false` with the conflict file list when source files would conflict.
+ * `drifted` is true whenever main is not an ancestor of the branch.
+ */
+export declare function preflightMerge(root: string, branch: string, opts?: {
+    autoResolve?: string[];
+}): Promise<PreflightMergeResult>;
+/**
+ * Commit a single task file in the main checkout, tracking it first when it is
+ * untracked. Task files are the one path that is routinely edited on both sides
+ * of a close-out merge: an untracked file aborts `git merge` outright, and a
+ * dirty one aborts it with "local changes would be overwritten". Committing the
+ * main copy up front (fail-soft) removes both failure modes — the content is
+ * preserved in history either way. Returns false when git failed and the file
+ * is not clean; callers should treat that as a merge blocker.
+ */
+export declare function commitTaskFile(root: string, absPath: string, message: string): boolean;
+/**
+ * The dirty/uncommitted file paths in a checkout (`git status --porcelain`),
+ * including tracked modifications and untracked files, in repo-relative form.
+ * Used by the close-out flow to check `main` before merging: a dirty tree
+ * aborts `git merge`, so the UI surfaces these so it can offer to commit them.
+ *
+ * FAILS CLOSED: returns `[]` only for a genuinely clean tree (git exit 0 with
+ * empty output). Any git failure — a non-zero exit, a timeout, or git being
+ * unavailable — throws `GitDirtyCheckError` instead, so a caller cannot
+ * mistake an unknown state for a clean tree and silently proceed into a merge
+ * that git will abort. This is the fix for #0211, where the old fail-open
+ * behaved that way under load.
+ */
+export declare class GitDirtyCheckError extends Error {
+    readonly causeKind: "timeout" | "git-error" | "no-repo";
+    constructor(causeKind: "timeout" | "git-error" | "no-repo", detail?: string);
+}
+export declare function dirtyFiles(root: string): Promise<string[]>;
+/**
+ * Stage and commit every dirty/uncommitted file in a checkout with a single
+ * checkpoint commit so the tree is left clean and mergeable. Used before a
+ * close-out merge when the user opts in ("Commit & continue"). Returns the
+ * list of committed dirty files on success (matching `dirtyFiles`), or an
+ * empty array when the tree was clean or the commit failed.
+ */
+export declare function commitDirtyFiles(root: string, message: string): Promise<string[]>;
+/**
+ * Merge `branch` into the CURRENT checkout — the main worktree, never the
+ * task's worktree. Default merge semantics: fast-forward when main is an
+ * ancestor of the branch, otherwise a merge commit (`--no-edit` so we never
+ * block on an editor). Longer timeout than `git()`: real merges are slow.
+ *
+ * A dirty working tree aborts `git merge` outright (e.g. the build marker that
+ * `repoos check` regenerates on every run). Rather than fail, the exact files
+ * git refuses to overwrite are committed and the merge is retried once.
+ *
+ * On a conflict the merge is aborted (`git merge --abort`) so nothing is left
+ * half-applied; the conflicted file list is returned and the branch stays
+ * untouched. The exception: when every conflicted path is listed in
+ * `opts.autoResolve`, the branch's version is taken (`--theirs`) and the merge
+ * is completed — used for the task file, which always changes on both sides of
+ * a close-out merge and whose branch version is authoritative for the task's
+ * final state.
+ *
+ * `opts.dryRun` answers the same conflict question non-destructively (see
+ * `dryRunMergeBranch`) — no commit, no branch move, the checkout restored.
+ */
+export declare function mergeBranch(root: string, branch: string, opts?: {
+    autoResolve?: string[];
+    autoResolveOurs?: string[];
+    dryRun?: boolean;
+}): Promise<MergeBranchResult>;
+export interface SyncBranchResult {
+    /** Whether the branch was synced (main merged into its worktree). */
+    ok: boolean;
+    /** Files that conflicted when the sync merge was aborted. */
+    conflicts: string[];
+    /** Human-readable failure reason (when not ok). */
+    reason?: string;
+}
+/**
+ * Sync `branch` with main: merge the main checkout's current branch into
+ * `branch`'s linked worktree. This is the repository's existing "sync with
+ * main" operation — the same `mergeBranch` semantics the review-transition
+ * auto-sync uses, so the automatic done-flow fallback and the manual route
+ * never diverge. On conflict the merge is aborted (nothing half-applied) and
+ * the conflict list is returned. Fail-soft: false when the branch has no
+ * linked worktree or git is missing.
+ */
+export declare function syncBranchWithMain(root: string, branch: string, opts?: {
+    autoResolve?: string[];
+}): Promise<SyncBranchResult>;
+/**
+ * Delete a local branch. The close-out flow only ever deletes a branch that
+ * was just merged into main, so `-d` (refuses unless fully merged) is the
+ * default. Pass `force: true` for a throwaway branch (a `repoos/integrate/*`
+ * candidate) that git will not see as merged.
+ * Fail-soft: false when the branch is gone, not merged, or git is missing —
+ * the caller treats it as best-effort cleanup.
+ */
+export declare function deleteBranch(root: string, branch: string, opts?: {
+    force?: boolean;
+}): boolean;
+/** `git worktree prune` — clears metadata for worktrees whose directory is gone. */
+export declare function pruneWorktrees(root: string): void;
+/**
+ * Remove the linked worktree for `branch` and make sure it is really gone.
+ * Forced when dirty — close-out content is preserved in the merged main, so
+ * nothing is lost.
+ *
+ * Handles the two states a leak actually shows up in:
+ *  - directory + metadata present   -> `git worktree remove --force`
+ *  - directory gone, metadata stale -> `remove` fails ("is not a working
+ *    tree"), so fall back to `git worktree prune`, then `rm -rf` any leftover
+ *    directory and prune once more.
+ *
+ * Returns false (without forcing anything) when `branch` is checked out in a
+ * DIFFERENT worktree than expected, or is the main checkout — the caller asked
+ * to remove the wrong thing.
+ */
+export declare function removeWorktree(root: string, branch: string): boolean;
+export interface EnsureHotfixResult {
+    ok: boolean;
+    /** Always config.root — the hotfix runs in the main checkout. */
+    path: string;
+    /** The branch created or reused. */
+    branch: string;
+    /** Human-readable failure reason. */
+    reason?: string;
+}
+/**
+ * Prepare the main checkout for a hotfix task.
+ *
+ * 1. Create a `hotfix/<id>-<slug>` branch from main (when hotfixTarget is
+ *    "branch") or stay on main (when target is "main").
+ * 2. Refuse if the main checkout is dirty.
+ * 3. Return config.root as the working directory — the agent runs here.
+ */
+export declare function ensureHotfix(root: string, branch: string, hotfixTarget: "branch" | "main"): EnsureHotfixResult;
+/**
+ * Reset the main checkout back to `main` after a hotfix, discarding any
+ * in-flight work. Only touches root when it's on a hotfix branch.
+ */
+export declare function resetHotfix(root: string, branch: string): boolean;
+/**
+ * Get agent-touched files in the working directory: the union of tracked
+ * worktree-changed files and newly-added files since the last ref, excluding
+ * dist/ and screenshots/. Returns an empty list on git failure.
+ */
+export declare function agentTouchedFiles(root: string, sinceRef: string): string[];