@webpieces/repo-workflow-core 0.0.1

package/src/main-sync-status.d.ts

@@ -0,0 +1,197 @@
+import { AtomicFile } from '@webpieces/tooling-common';
+import { MAIN_SYNC_STATUS_VERSION, MainSyncFileStore, MainSyncStatus, MainSyncStatusFile, PullRequestIndex } from './main-sync-file';
+import { DotWebpieces } from '@webpieces/tooling-common';
+import { WorktreeService } from './worktrees';
+export { MainSyncStatus, MainSyncStatusFile, PullRequestIndex, MAIN_SYNC_STATUS_VERSION };
+export declare const DEFAULT_HANG_TIMEOUT_MINUTES = 5;
+export declare class MainSyncLock {
+    state: string;
+    started: number;
+    pid: number;
+    constructor(state: string, started: number, pid?: number);
+}
+/**
+ * Reads/writes the main-sync cache + lock and computes the slow "is my branch healthy vs origin/main?"
+ * status. `@injectable(bindingScopeValues.Singleton)` so it's injectable and drawn in consumers’ DI designs.
+ */
+export declare class MainSyncStatusService {
+    private readonly dotDir;
+    private readonly atomicFile;
+    private readonly store;
+    private readonly worktrees;
+    constructor(dotDir?: DotWebpieces, atomicFile?: AtomicFile, store?: MainSyncFileStore, worktrees?: WorktreeService);
+    /**
+     * SHARED scope: `<primary>/.webpieces/main-sync-status.json`, one per repo.
+     *
+     * It is the OUTPUT of the single-flight refresher below, so it has to live where the lock lives —
+     * one `.git`, one `origin/main`, one fetch, one answer. A per-worktree copy under single-flight
+     * would only ever be written for whichever worktree won the lock anyway.
+     *
+     * FORMERLY a known defect, now fixed: the file's CONTENT used to be keyed to ONE branch, and every
+     * reader fails OPEN when the cached branch is not the branch being judged (`stale-cross-branch-cache
+     * (fail-open)`). With several worktrees on several branches, only the winner of the lock was ever
+     * described, so every other worktree's guards abstained — and which one was armed thrashed as the
+     * lock changed hands. The file is now a MAP of branch -> status (see MainSyncStatusFile): the single
+     * winning refresher enumerates every worktree and records all of their branches in one atomic write,
+     * so one fetch arms everyone. Single-flight is unchanged; only what the winner writes changed.
+     */
+    mainSyncStatusPath(repoRoot: string): string;
+    /**
+     * SHARED scope — the single-flight lock for the whole repo.
+     *
+     * This is the fix for the filed bug "the detached main-sync refresher's `git fetch` races the
+     * agent's foreground `git fetch`/`git pull` and corrupts `.git/FETCH_HEAD`". The lock was already
+     * atomic (O_CREAT|O_EXCL) and already serialised refreshers against each other — but only WITHIN
+     * one worktree, so N worktrees meant N locks and up to N concurrent `git fetch`es against the ONE
+     * shared `.git`, which is exactly how a duplicate `for-merge` line lands in FETCH_HEAD. There is
+     * one `.git`, so there is now one lock: at most one refresher in flight across all worktrees.
+     *
+     * Stale-lock handling is unchanged and still required (a lock nobody can clear is worse than the
+     * race): the holder records pid + start epoch, and `tryAcquireMainSyncLock` reclaims it once
+     * `isRefreshInProgress` proves the holder is finished, hung past hangTimeoutMinutes, or dead.
+     */
+    mainSyncLockPath(repoRoot: string): string;
+    /**
+     * The cached status FOR ONE BRANCH — the only read the four main-sync guards perform.
+     *
+     * `branch` is mandatory and is the branch being judged. A branch the last refresh never saw
+     * returns null, which every guard already treats as `no-sync-cache (fail-open)`, so an unknown
+     * branch degrades exactly as a missing file did. Any error (missing, truncated, malformed JSON)
+     * also returns null — this must never throw on the blocking path.
+     */
+    readMainSyncStatus(repoRoot: string, branch: string): MainSyncStatus | null;
+    readMainSyncStatusFile(repoRoot: string): MainSyncStatusFile | null;
+    /**
+     * Merge ONE branch's entry into the existing map, atomically, leaving siblings untouched.
+     *
+     * Read-modify-write rather than replace: this is the writer used by everyone who is NOT the
+     * single-flight refresher (notably pr-gate's post-merge stamp, which holds no lock and knows about
+     * exactly one branch). Replacing the document from there would erase every other worktree's entry
+     * and silently disarm their guards until the next refresh.
+     */
+    writeMainSyncStatus(repoRoot: string, status: MainSyncStatus): void;
+    /**
+     * Replace the WHOLE document — only the winning refresher may do this.
+     *
+     * ATOMIC (temp file + `rename()` in the same directory). The refresher writes this file while
+     * guards on the blocking path read it, possibly from another worktree; a plain `writeFileSync`
+     * truncates first, so a reader landing in that window gets a torn document. See AtomicFile.
+     */
+    writeMainSyncStatusFile(repoRoot: string, file: MainSyncStatusFile): void;
+    readMainSyncLock(repoRoot: string): MainSyncLock | null;
+    writeMainSyncLock(repoRoot: string, lock: MainSyncLock): void;
+    isLockStale(lock: MainSyncLock, hangTimeoutMinutes: number, now?: number): boolean;
+    isRefreshInProgress(repoRoot: string, hangTimeoutMinutes: number, now?: number): boolean;
+    /**
+     * ATOMICALLY take the refresher lock. Returns the held lock, or null when someone else holds it.
+     *
+     * Replaces the check-then-write pair (`isRefreshInProgress` then `writeMainSyncLock`), whose gap
+     * let two detached refreshers both pass the check and then both run `git fetch` at once — the
+     * concurrency this lock exists to prevent. The create uses the `wx` flag (O_CREAT|O_EXCL), so of
+     * N racing refreshers exactly one creates the file.
+     *
+     * A lock file left behind by a FINISHED, hung, or killed refresher is reclaimed: we only unlink
+     * and re-take it once `isRefreshInProgress` says the holder is provably not running, and we
+     * re-read afterwards to confirm the entry we see is ours before claiming the lock.
+     */
+    tryAcquireMainSyncLock(repoRoot: string, hangTimeoutMinutes: number, now?: number, pid?: number): MainSyncLock | null;
+    private createExclusive;
+    inProcessLock(now?: number, pid?: number): MainSyncLock;
+    finishedLock(started: number): MainSyncLock;
+    /**
+     * The SLOW path for ONE branch: the branch checked out in `repoRoot`. Runs its own fetch and its
+     * own `gh` query, so it is the right entry point for a single-worktree caller and for tests.
+     * The refresher uses computeAllMainSyncStatuses instead — see there for why.
+     */
+    computeMainSyncStatus(repoRoot: string): MainSyncStatus;
+    /**
+     * The SLOW path for EVERY branch this repo has checked out — what the detached refresher runs.
+     *
+     * The cache is shared by all worktrees but was written for one branch, so only one worktree's
+     * guards were ever armed. Enumerating the worktrees here and writing all of their branches in one
+     * atomic map arms every worktree off a single refresh.
+     *
+     * NETWORK COST DOES NOT SCALE WITH BRANCH COUNT, which is the whole reason this is a separate
+     * method: ONE `git fetch` and ONE repo-wide `gh pr list` for all N branches (the old code asked
+     * `gh` twice per branch, so looping it would have cost 2N round trips). Everything after that is
+     * local git in each worktree — merge-base, rev-parse, diff, ls-files.
+     *
+     * The map is rebuilt from the LIVE worktree set every refresh, so a deleted branch or removed
+     * worktree simply stops appearing. No pruning pass, no unbounded growth.
+     */
+    computeAllMainSyncStatuses(repoRoot: string): MainSyncStatusFile;
+    private hasBranch;
+    /**
+     * One branch's status, computed in `worktreePath` (the tree that has it checked out — the
+     * working-tree overlap signals are only correct from there). Does NOT fetch and does NOT call
+     * `gh`: both are done once per refresh by the caller.
+     */
+    private computeBranchStatus;
+    private stampForge;
+    private computeBranchStatusInner;
+    squashRecoverySteps(currentBranch: string): string[];
+    /**
+     * Synchronously stamp a clean "up to date with main" status — call right after a successful merge.
+     *
+     * This is the one writer that takes NO lock, and it knows about exactly one branch. It therefore
+     * goes through writeMainSyncStatus, which MERGES its entry into the existing map; writing a whole
+     * document from here would wipe every other worktree's entry.
+     */
+    stampCleanMainSyncStatus(repoRoot: string): void;
+    /**
+     * Refresh `origin/main` WITHOUT writing `.git/FETCH_HEAD`.
+     *
+     * WHY the flag is not optional: this runs in a DETACHED background process while the agent is
+     * running its own foreground `git fetch` / `git pull` in the very same repo. `.git/FETCH_HEAD` is
+     * a single file that git takes no lock on, so two overlapping fetches interleave their writes and
+     * can leave the SAME `for-merge` line twice. `git pull` then reads two for-merge entries and dies
+     * with `fatal: Cannot fast-forward to multiple branches` — wedging the exact command the
+     * read-stale-guard tells the agent to run. `--no-write-fetch-head` (git >= 2.29) still updates the
+     * remote-tracking ref, which is all anything downstream reads (`origin/main`, merge-base), so
+     * nothing here needs FETCH_HEAD written at all.
+     *
+     * Older git rejects the flag; only then do we retry the plain form, accepting the old behaviour
+     * rather than losing the refresh entirely on a pre-2020 git.
+     */
+    private fetchOriginMain;
+    private isUnknownGitOption;
+    private ensureDir;
+    private isProcessAlive;
+    private capture;
+    private gitBranch;
+    private localMainHash;
+    private commitDistance;
+    private changedFiles;
+    private featureChangedFiles;
+    /**
+     * ONE repo-wide `gh pr list` giving every branch's merged/open PR — replaces the two per-branch
+     * `--head <branch>` queries. `--limit 200` bounds it; a branch whose only PR is older than that
+     * falls out of the index and reads as "no PR", which is the fail-OPEN direction (no merged PR =
+     * no block), the same way a missing `gh` or an offline machine already degraded.
+     */
+    private loadPullRequestIndex;
+    /**
+     * A `main` entry synthesised WITHOUT a worktree standing on main. Carries only the two hashes
+     * read-stale-guard / stale-main-bash-guard actually compare (originMain vs the live tree's
+     * ancestry) — never merged, never conflicting, so it can only ever produce the stale-main verdict.
+     */
+    private mainOnlyStatus;
+    private benignStatus;
+}
+export declare function mainSyncStatusPath(repoRoot: string): string;
+export declare function mainSyncLockPath(repoRoot: string): string;
+export declare function readMainSyncStatus(repoRoot: string, branch: string): MainSyncStatus | null;
+export declare function readMainSyncStatusFile(repoRoot: string): MainSyncStatusFile | null;
+export declare function writeMainSyncStatus(repoRoot: string, status: MainSyncStatus): void;
+export declare function writeMainSyncStatusFile(repoRoot: string, file: MainSyncStatusFile): void;
+export declare function readMainSyncLock(repoRoot: string): MainSyncLock | null;
+export declare function writeMainSyncLock(repoRoot: string, lock: MainSyncLock): void;
+export declare function isLockStale(lock: MainSyncLock, hangTimeoutMinutes: number, now?: number): boolean;
+export declare function isRefreshInProgress(repoRoot: string, hangTimeoutMinutes: number, now?: number): boolean;
+export declare function tryAcquireMainSyncLock(repoRoot: string, hangTimeoutMinutes: number, now?: number, pid?: number): MainSyncLock | null;
+export declare function inProcessLock(now?: number, pid?: number): MainSyncLock;
+export declare function finishedLock(started: number): MainSyncLock;
+export declare function computeMainSyncStatus(repoRoot: string): MainSyncStatus;
+export declare function computeAllMainSyncStatuses(repoRoot: string): MainSyncStatusFile;
+export declare function squashRecoverySteps(currentBranch: string): string[];
+export declare function stampCleanMainSyncStatus(repoRoot: string): void;