@wjarka/cezarion 0.10.0-pr30.54

package/dist/git-refs.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Reject option-like git revision arguments (#431). A `-`/`--`-prefixed
+ * base/from ref is git argument injection: `git diff --output=/path` writes an
+ * arbitrary file, `--upload-pack=<cmd>` runs a command, etc. Every ref cezar
+ * feeds to git is already gated upstream by `git rev-parse --verify` /
+ * `git check-ref-format`, which reject option-like values — this is the
+ * explicit last line of defense so a future refactor can't silently drop that
+ * gate. Empty refs are rejected too: git would resolve them to an unexpected
+ * default rather than the intended revision.
+ */
+export declare function isSafeGitRef(ref: string): boolean;

package/dist/git-refs.js

@@ -0,0 +1,14 @@
+/**
+ * Reject option-like git revision arguments (#431). A `-`/`--`-prefixed
+ * base/from ref is git argument injection: `git diff --output=/path` writes an
+ * arbitrary file, `--upload-pack=<cmd>` runs a command, etc. Every ref cezar
+ * feeds to git is already gated upstream by `git rev-parse --verify` /
+ * `git check-ref-format`, which reject option-like values — this is the
+ * explicit last line of defense so a future refactor can't silently drop that
+ * gate. Empty refs are rejected too: git would resolve them to an unexpected
+ * default rather than the intended revision.
+ */
+export function isSafeGitRef(ref) {
+    return ref.length > 0 && !ref.startsWith('-');
+}
+//# sourceMappingURL=git-refs.js.map

package/dist/git-refs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-refs.js","sourceRoot":"","sources":["../src/git-refs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,OAAO,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;AAChD,CAAC"}

package/dist/git-worktree.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Git worktree per task (spec 006). Each run gets its own branch
+ * `cez/<id8>` checked out into `.ai/cezar/worktrees/<runId>` so agents never
+ * touch the user's working tree. Pattern ported from github-janitor's
+ * `git.ts` (createWorktree / autosaveCommit), minus the bare clone — we're
+ * already inside a working copy. Everything degrades: helpers never throw
+ * except `createWorktree`, whose failure the caller turns into a note.
+ */
+/** Repo-relative home of all task worktrees (gitignored via .ai/cezar/.gitignore). */
+export declare const WORKTREES_DIR = ".ai/cezar/worktrees";
+export declare function branchFor(runId: string): string;
+/**
+ * Resolve the configured base branch to something `git worktree add` can
+ * fork from: the local branch, its remote-tracking ref, or null — the caller
+ * falls back to the current branch with a note. Never throws.
+ *
+ * When BOTH the local branch and `origin/<base>` exist, prefer whichever is up
+ * to date. A stale LOCAL base (behind origin, because nothing fetched it into
+ * this worktree's repo) is the classic inflated-diff trap: the merge-base every
+ * diff is measured from collapses onto the stale tip, so all of the history
+ * merged into origin since then counts as the task's own changes — the phantom
+ * 142k-line diff. `origin/<base>` is the source of truth for a review base, so
+ * only keep the local ref when it is equal to or ahead of origin (unpushed base
+ * commits); otherwise use origin.
+ *
+ * This answers the question once, when the worktree is forked. The local ref
+ * goes stale AFTERWARDS too — agents fetch, they never pull — so every diff
+ * re-applies the same rule at read time through `freshestBaseRef`
+ * (`git-diff-base.ts`). Keep the two in agreement.
+ */
+export declare function resolveBaseRef(repoRoot: string, base: string): Promise<string | null>;
+export declare function worktreePathFor(repoRoot: string, runId: string): string;
+export interface WorktreeInfo {
+    path: string;
+    branch: string;
+    /** Branch name the worktree was forked from (commit sha when HEAD was detached). */
+    baseBranch: string;
+}
+/**
+ * Establish the task worktree idempotently. Besides the fresh
+ * `git worktree add -b` path, recover the two normal restart/deletion cases:
+ * reuse an already-registered task worktree, or reattach a surviving task
+ * branch after its directory/registration was removed. Existing non-empty
+ * unregistered paths are never deleted because they may hold recoverable
+ * uncommitted work.
+ */
+export declare function createWorktree(repoRoot: string, runId: string, baseBranch: string): Promise<WorktreeInfo>;
+/**
+ * Best-effort on-disk size of a worktree directory in bytes, via POSIX
+ * `du -sk` (kibibytes → bytes). Returns `null` when `du` is unavailable —
+ * including all of Windows, where `du` is not a command — or on any error.
+ * Never throws and never blocks: worktree retention is count-based, so a null
+ * size only blanks the panel's size column, it does not affect reclamation.
+ */
+export declare function worktreeSizeBytes(path: string): Promise<number | null>;
+/** Remove a task worktree and its branch. Best effort — never throws. */
+export declare function removeWorktree(repoRoot: string, worktreePath: string, branch?: string): Promise<void>;
+/**
+ * Why an autosave commit happened. Only `periodic` is gated (behind
+ * `CEZ_AUTOSAVE=1`, #471) — the three flushes always run so the branch ends
+ * holding the finished state. Before this was recorded, all four wrote the bare
+ * message `cezar autosave`, so a user who had opted out of the periodic timer
+ * still saw `cezar autosave` in `git log` and reasonably concluded the opt-out
+ * was broken. Only commit *spacing* (~90 s ⇒ timer) told them apart.
+ */
+export type AutosaveReason = 'periodic' | 'turn end' | 'run finalize' | 'pre-PR';
+/**
+ * What an autosave attempt did. `refused` and `failed` are distinct from
+ * `nothing-to-do` because one call site must act on them: the pre-PR flush is
+ * the *last* one, so anything other than `committed`/`nothing-to-do` there
+ * means the branch leaves the box without the run's final state and the user
+ * has to be told (see createDraftPr). A bare boolean could not carry that.
+ */
+export type AutosaveResult = 'committed' | 'nothing-to-do' | 'refused' | 'failed';
+/**
+ * Stage and commit everything in the worktree as a "cezar autosave" commit
+ * (janitor pattern) — the agent's progress is always recoverable from the
+ * `cez/<id8>` branch history. Quietly a no-op when nothing changed.
+ *
+ * The message carries `reason` so the opt-in periodic timer and the always-on
+ * flushes are distinguishable in `git log`; the `cezar autosave` prefix is kept
+ * so existing log greps still match.
+ *
+ * Refuses to commit a worktree that is mid-merge or still carries conflict
+ * markers: the incident behind #471 was an autosave capturing a half-resolved
+ * merge, and a blind `git add -A` would do it again.
+ */
+export declare function autosaveCommit(dir: string, reason: AutosaveReason): Promise<AutosaveResult>;
+/**
+ * "What did this task change": diff of the worktree (committed + uncommitted
+ * + untracked, via `add -N`) against the merge-base with its base branch —
+ * so the diff stays *this task's* changes even after the base moves on.
+ *
+ * Deliberately does NOT take the repointed-HEAD guard that `collectChanges`
+ * (#591) and `worktreeShortstat` (#751) resolve through
+ * `resolveTaskDiffBase` — this is the whole-branch anchor on purpose, for two
+ * reasons. Its text output is `GET /api/v1/runs/:id/diff`, a protected surface
+ * (BACKWARD_COMPATIBILITY.md §2), so narrowing it would silently change what
+ * every existing consumer reads. And its other caller, `settleSuccess`, asks
+ * only "is there anything here to review at all" — over-answering that parks a
+ * run at the review gate, which is recoverable, while under-answering would
+ * settle a run to `done` with work still in the tree. If a future change wants
+ * the narrow answer here, take it from `resolveTaskDiffBase` rather than
+ * re-deriving the rule a fourth time.
+ */
+export declare function worktreeDiff(worktreePath: string, baseBranch: string, cap?: number): Promise<string>;
+/**
+ * `git diff --stat` version of `worktreeDiff` (spec 010 — the variant
+ * comparison columns). Same merge-base anchoring, and it stays whole-branch
+ * for a reason of its own: variants are sibling cezar worktrees, each on its
+ * own `cez/*` branch, and the column exists to compare their *committed* work
+ * against one another. Narrowing one variant to its uncommitted tree would
+ * make the comparison meaningless rather than more honest. Returns '' on any
+ * failure. (The task-diff rule the other surfaces follow: `git-diff-base.ts`.)
+ */
+export declare function worktreeDiffStat(worktreePath: string, baseBranch: string): Promise<string>;
+/** Aggregate diff numbers (#389) — the shape stored on `RunRecord.diffStat`. */
+export interface DiffStat {
+    adds: number;
+    dels: number;
+    files: number;
+    /** Set only when the numbers were narrowed to what this run did on a branch it checked
+     *  out into its worktree, because HEAD had been repointed off the task's branch (#751).
+     *  Absent — never `false` — on a normal run, so the persisted shape is unchanged for
+     *  every task that behaved. */
+    repointed?: boolean;
+}
+/**
+ * Parse `git diff --shortstat` output — " 3 files changed, 10 insertions(+),
+ * 2 deletions(-)". Every part is optional: insertions-only and deletions-only
+ * diffs omit the other counter, and an empty diff prints nothing at all
+ * (→ all zeros). The wording is stable porcelain English — git does not
+ * localize `--shortstat` — so matching the words is safe.
+ */
+export declare function parseShortstat(s: string): DiffStat;
+/**
+ * `git diff --shortstat` of the worktree vs its base (#389) — the numbers
+ * behind `RunRecord.diffStat`, which is what the sidebar quick list and the
+ * Tasks table show. Same intent-to-add as `worktreeDiff`, but the anchor comes
+ * from the shared `resolveTaskDiffBase` rule (`git-diff-base.ts`): pass the
+ * run's own `taskBranch` and `runStartedAt`, and a worktree whose HEAD was
+ * repointed onto another branch reports what this run did to that branch
+ * instead of claiming the branch's whole diff as this task's (#751 — the #591
+ * guard, on this surface). The same rule re-resolves a stale local base ref,
+ * so the number never counts upstream history the task merely forked from.
+ *
+ * `repointed: true` rides along on the returned stat exactly when that
+ * narrowing happened, so the UI can say why the number is what it is. Null on
+ * git failure (the caller notes it, never fails the run); an empty diff is a
+ * valid all-zero stat.
+ */
+export declare function worktreeShortstat(worktreePath: string, baseBranch: string, opts?: {
+    taskBranch?: string;
+    runStartedAt?: string;
+}): Promise<DiffStat | null>;
+/**
+ * Startup reconcile: `git worktree prune` + remove every directory under
+ * `.ai/cezar/worktrees/` whose run id is no longer in the store (and its
+ * branch). Returns the removed run ids for the boot log. Never throws.
+ */
+export declare function pruneOrphans(repoRoot: string, validIds: ReadonlySet<string>): Promise<string[]>;