@bridge4dev/runner 0.13.1 → 0.22.1

package/dist/gitops.d.ts

@@ -7,6 +7,30 @@ export interface GitFileEntry {
     /** Present in the working tree but not committed yet. */
     uncommitted: boolean;
 }
+/**
+ * One line of `git status --porcelain`, kept as the two columns git wrote.
+ *
+ * Both letters travel, not a flattened verdict, because the pair is the whole
+ * meaning: `MM` is a file that is staged AND edited again since, and it belongs
+ * in two groups of the panel at once. Any collapsing we did here would have to
+ * be undone in the browser.
+ */
+export interface GitWorkingEntry {
+    /** Repo-root-relative — exactly the string every write command takes back. */
+    path: string;
+    /** Index column (X). `?` for untracked, ' ' when nothing is staged. */
+    index: string;
+    /** Worktree column (Y). ' ' when the file is fully staged. */
+    worktree: string;
+    /** Where a rename came from, when git reported one. */
+    origPath?: string;
+}
+export declare function isConflictedEntry(entry: {
+    index: string;
+    worktree: string;
+}): boolean;
+export declare function isStagedEntry(entry: GitWorkingEntry): boolean;
+export declare function isUnstagedEntry(entry: GitWorkingEntry): boolean;
 export interface GitStatusResult {
     branch: string;
     baseBranch: string;
@@ -16,30 +40,312 @@ export interface GitStatusResult {
     /** Commits the agent made on the session branch (base..HEAD). */
     agentCommits: number;
     uncommittedFiles: number;
+    /** Tip of the session branch — what an apply would swallow. */
+    branchSha: string | null;
+    /** Tip of the base branch right now. */
+    baseSha: string | null;
+    /** Where the two last agreed. */
+    forkSha: string | null;
+    /** Commits the branch has that the base does not. */
+    ahead: number | null;
+    /** Commits the base has that the branch does not — «main moved on». */
+    behind: number | null;
+    /**
+     * Commits made since the last «Apply» swallowed the branch, excluding
+     * anything the base contributed. This — not `ahead` — is the honest «N
+     * commits not in main»: a squash merge never makes the branch an ancestor,
+     * so `ahead` keeps counting work that already landed.
+     *
+     * `null` means «we cannot know»: no apply has been recorded with a branch
+     * tip. The caller must NOT substitute `ahead` — that is the number this
+     * field exists to replace.
+     */
+    newCommits: number | null;
+    /** Commits made since the last successful «Push». */
+    aheadOfPushed: number | null;
+    /** The branch the PROJECT FOLDER is checked out on right now. */
+    worktreeBranch: string | null;
+    /** The folder moved off the branch this session forked from. */
+    drifted: boolean;
+    /** The branch this session forked from is gone from the repository. */
+    baseMissing: boolean;
+    /**
+     * Uncommitted changes in the PROJECT FOLDER — not in the session worktree.
+     *
+     * `applySession` has refused to merge into a dirty checkout since session 4,
+     * and until now nothing told the panel, so «Apply» was offered, pressed, and
+     * refused with an instruction to go and fix it by hand on a server the person
+     * pressing may not even have a shell on. Same predicate as the guard —
+     * `status --porcelain` in `workspacePath` — so the panel and the runner
+     * cannot disagree about it.
+     *
+     * `null` is «could not read it», and it is deliberately NOT `true`. Session
+     * 14 rounds an unknown tree to «dirty», and that is right there: it WITHHOLDS
+     * a claim. Here the same rounding would BLOCK the button — turning a failed
+     * `git status` into a dead end of our own making, which is the exact thing
+     * this field exists to remove. Unknown keeps the old behaviour: offer Apply,
+     * and let the guard on the other side have the last word.
+     */
+    workspaceDirty: boolean | null;
+    /** The paths, so the panel can name what is in the way. Capped. */
+    workspaceDirtyFiles: string[];
+    workspaceDirtyCount: number;
+    /**
+     * A merge stopped in the PROJECT FOLDER and is waiting for a human.
+     *
+     * Kept apart from `mergeInProgress` above, which is about this session's own
+     * tree. The two are the same folder only for a DIRECT session, and the
+     * difference decides what a BRANCH session is told: a conflicted tree cannot
+     * be committed, so «commit it and press Apply again» would be advice nobody
+     * can follow (QA-110 m7).
+     */
+    workspaceMergeInProgress: boolean;
+    /**
+     * Every path `git status` has something to say about, with both of its
+     * columns. This is what the Source Control panel groups into «Staged
+     * Changes», «Changes» and «Merge Changes» — the same three groups VS Code
+     * draws, from the same one command.
+     *
+     * `files` above answers a different question («what would an Apply bring
+     * to main») and cannot answer this one: it is a diff against the base, so it
+     * knows nothing about the index and calls a staged file and an unstaged file
+     * by the same name.
+     */
+    working: GitWorkingEntry[];
+    /** True total — `working` is capped, this never is. */
+    workingCount: number;
+    workingTruncated: boolean;
+    stagedCount: number;
+    unstagedCount: number;
+    conflictedCount: number;
+    /** `MERGE_HEAD` exists: a merge stopped here and is waiting for a human. */
+    mergeInProgress: boolean;
+    /** The remote-tracking branch this branch follows, `origin/main`-style. */
+    upstream: string | null;
+    /** Commits this branch has that its upstream does not — what Push sends. */
+    aheadUpstream: number | null;
+    /** Commits the upstream has that this branch does not — what Pull brings. */
+    behindUpstream: number | null;
+    /** Remotes configured at all: no remote means no Push and no Pull. */
+    remotes: string[];
+}
+/**
+ * `git status --porcelain=v1 -z`, parsed.
+ *
+ * NUL-separated and not line-separated on purpose: a file name may legally
+ * contain a newline, and with `core.quotePath=false` — which we set globally so
+ * Cyrillic paths stay readable — git no longer escapes it. Splitting that output
+ * on `\n` invents two entries out of one file, and the second one is a path that
+ * exists nowhere. `-z` is the only format that cannot be misread.
+ *
+ * A rename or a copy carries its ORIGINAL path as its own NUL-terminated token
+ * right after the entry, so the loop consumes two tokens for those.
+ */
+export declare function parsePorcelainZ(raw: string): GitWorkingEntry[];
+export interface ResolvedBase {
+    baseBranch: string;
+    baseRef: string;
+    /** The API pinned this base at session creation and it still exists. */
+    pinned: boolean;
+    /** The pinned base was asked for and is not in this repository any more. */
+    baseMissing: boolean;
 }
-export declare function gitStatus(worktreePath: string, workspacePath: string, sessionBranch: string): Promise<GitStatusResult>;
+export interface GitStatusInput {
+    worktreePath: string;
+    workspacePath: string;
+    sessionBranch: string;
+    /** The base pinned at session creation; absent for pre-session-13 rows. */
+    baseBranch?: string;
+    /** Branch tip the last «Apply» swallowed — makes `newCommits` truthful. */
+    appliedBranchSha?: string;
+    /** Branch tip the last «Push» sent — makes `aheadOfPushed` truthful. */
+    pushedSha?: string;
+    /**
+     * Session 16 — the session works in the project folder itself, on the branch
+     * the folder is already on.
+     *
+     * There is no base to be «ahead of» then: the branch IS the base, and every
+     * number derived from the pair — ahead, behind, newCommits, drift — would be
+     * a comparison of a thing with itself. So the whole block is skipped and
+     * reported as unknown, and `files` becomes what an uncommitted-work list
+     * should be: the diff against HEAD.
+     */
+    direct?: boolean;
+}
+export declare function gitStatus(input: GitStatusInput): Promise<GitStatusResult>;
 export interface GitDiffResult {
     diff: string;
     truncated: boolean;
 }
 /** Exposed for tests: the header check is the control worth pinning directly. */
 export declare function capDiffForTest(diff: string): GitDiffResult;
-export declare function gitDiff(worktreePath: string, workspacePath: string, sessionBranch: string, filePath: string): Promise<GitDiffResult>;
+/**
+ * Which comparison a diff request means (session 16).
+ *
+ * `base` is the historical one and stays the default: the whole change of this
+ * branch against the branch it forked from, which is what «Apply» would bring.
+ * The Source Control panel asks the two questions an editor asks instead —
+ * `staged` is HEAD↔index, `worktree` is index↔disk — because a file that is
+ * both staged and edited again has two different diffs and showing one of them
+ * twice is how a person loses an edit they thought they had saved.
+ */
+export type GitDiffMode = 'base' | 'staged' | 'worktree';
+export declare function gitDiff(worktreePath: string, workspacePath: string, sessionBranch: string, filePath: string, baseBranch?: string, mode?: GitDiffMode): Promise<GitDiffResult>;
+/**
+ * The whole diff of the branch against its base — masked, never header-checked.
+ *
+ * Deliberately separate from `gitDiff`: that one REFUSES a diff containing a
+ * protected file, which is right for a panel showing one file at a time and
+ * wrong here, where the answer would be «no commit message at all, because the
+ * branch happens to touch `.env.example`». The caller strips protected files
+ * instead of losing the diff, and says how many it dropped.
+ */
+export declare function gitBranchDiff(input: {
+    worktreePath: string;
+    workspacePath: string;
+    sessionBranch: string;
+    baseBranch?: string;
+    maxBytes?: number;
+}): Promise<{
+    diff: string;
+    truncated: boolean;
+}>;
 export interface GitCommitResult {
     committed: boolean;
     sha?: string;
     reason?: string;
 }
-export declare function gitCommit(worktreePath: string, message: string): Promise<GitCommitResult>;
+export interface GitStageResult {
+    /** How many paths were handed to git — not how many changed. */
+    paths: number;
+    staged: number;
+    unstaged: number;
+}
+export interface GitDiscardResult {
+    /** Tracked files put back to what the index holds. */
+    restored: number;
+    /** Untracked files removed from disk. */
+    deleted: number;
+    /** Conflicted paths, which git refuses to restore — named, not swallowed. */
+    skipped: string[];
+}
+export interface GitPullResult {
+    pulled: boolean;
+    alreadyUpToDate?: boolean;
+    /** The branch moved without a merge commit — the ordinary, happy case. */
+    fastForward?: boolean;
+    commitSha?: string;
+    upstream?: string;
+    remote?: string;
+    conflict?: boolean;
+    conflictPaths?: string[];
+    behind?: number;
+    ahead?: number;
+    error?: string;
+}
+export interface GitMergeAbortResult {
+    aborted: boolean;
+    reason?: string;
+}
 export interface ApplyResult {
     applied: boolean;
     commitSha?: string;
     conflict?: boolean;
     /** On conflict: the branch the agent must merge into its session branch. */
     baseBranch?: string;
+    /**
+     * Everything already in the base — nothing new to merge. A normal outcome,
+     * not a failure: it used to surface as a raw «Commit failed: nothing to
+     * commit» from git.
+     */
+    noChanges?: boolean;
+    /** The project folder is not on the branch this session forked from. */
+    drifted?: boolean;
+    /** What the folder IS on, so the message can name it. */
+    workspaceBranch?: string;
+    /** Tip of the session branch this apply swallowed — the next one starts here. */
+    branchSha?: string;
+    /** Tip of the base before the merge, for the journal. */
+    baseShaBefore?: string;
+    /**
+     * Refused because the PROJECT FOLDER has uncommitted changes (session 15).
+     *
+     * A flag rather than only the sentence: the API used to see nothing but a
+     * free-text `error`, so this refusal reached the user as a raw string with no
+     * state behind it and no way forward. `error` stays alongside it so an API
+     * older than session 15 keeps behaving exactly as it did.
+     */
+    workspaceDirty?: boolean;
+    workspaceDirtyFiles?: string[];
+    workspaceDirtyCount?: number;
+    /** …and whether that dirt is a stopped merge, which cannot be committed. */
+    workspaceMergeInProgress?: boolean;
+    error?: string;
+}
+export interface ApplySessionInput {
+    workspacePath: string;
+    worktreePath: string;
+    sessionBranch: string;
+    message: string;
+    /**
+     * The base pinned at session creation. When given, the apply refuses to run
+     * while the project folder sits on any other branch: merging into whatever
+     * happens to be checked out is how work silently landed in the wrong place.
+     */
+    expectedBase?: string;
+    /**
+     * Branch tip the previous apply already merged. Only work after it counts —
+     * this is what turns «Apply» from a one-shot door into a repeatable action.
+     */
+    sinceSha?: string;
+}
+export interface UpdateFromBaseResult {
+    updated: boolean;
+    commitSha?: string;
+    /** The branch already contained everything the base has. */
+    alreadyUpToDate?: boolean;
+    conflict?: boolean;
+    /** Paths git could not merge — captured BEFORE the abort wipes them. */
+    conflictPaths?: string[];
+    baseBranch?: string;
+    error?: string;
+}
+export interface GitBranchEntry {
+    name: string;
+    sha: string;
+    subject: string;
+    date: string;
+    /** Absolute path of the worktree holding it — git refuses a second checkout. */
+    checkedOutIn: string | null;
+    /** Reachable from the current base: the work is already in. */
+    merged: boolean;
+}
+export interface GitBranchesResult {
+    branches: GitBranchEntry[];
+    /** What the project folder is on right now. */
+    currentBranch: string | null;
+    currentSha: string | null;
+    remotes: string[];
+    truncated: boolean;
+}
+/**
+ * Every local branch, with the one fact the user cannot see anywhere else:
+ * whether it is already checked out in another worktree. Git refuses to check
+ * one branch out twice, so «continue this branch» has to know before it starts,
+ * not after the worktree command fails.
+ */
+export declare function gitBranches(workspacePath: string): Promise<GitBranchesResult>;
+export interface GitPushResult {
+    pushed: boolean;
+    remote?: string;
+    branch?: string;
+    /** The sha that is now on the remote. */
+    commitSha?: string;
+    alreadyUpToDate?: boolean;
+    /** This push also gave the branch an upstream (session 16). */
+    upstreamSet?: boolean;
     error?: string;
 }
-export declare function applySession(workspacePath: string, worktreePath: string, sessionBranch: string, message: string): Promise<ApplyResult>;
 /**
  * Reading history is the one git surface where the *repository*, not the
  * session worktree, is the right place to stand: a finished session may have
@@ -53,6 +359,21 @@ export declare function applySession(workspacePath: string, worktreePath: string
  * `assertRefArgument` / `sanitizeBranch` and by the same denylist the Changes
  * panel uses.
  */
+/**
+ * A ref pointing at a commit, with its KIND (session 14).
+ *
+ * Until now these were bare strings, so a local branch, a remote-tracking
+ * branch and a tag were drawn identically and `tag: v1.2` leaked its prefix
+ * into the badge. The graph needs to tell them apart to look like a repository
+ * viewer rather than a list.
+ */
+export interface GitRef {
+    /** Short name: `main`, `origin/main`, `v1.2.0`. */
+    name: string;
+    type: 'head' | 'remote' | 'tag';
+    /** `HEAD -> ` pointed here: this is what the folder is checked out on. */
+    isHead: boolean;
+}
 export interface GitLogCommit {
     sha: string;
     /** Empty for a root commit, more than one for a merge. */
@@ -60,12 +381,28 @@ export interface GitLogCommit {
     author: string;
     /** Author date, ISO-8601 with offset. */
     date: string;
+    /** Who committed it — differs from the author after a rebase or a cherry-pick. */
+    committer: string;
+    committerDate: string;
     subject: string;
-    /** Branch/tag names pointing at this commit (`HEAD -> ` already stripped). */
-    refs: string[];
+    refs: GitRef[];
 }
 /** Which slice of history to show. */
 export type GitLogScope = 'session' | 'branch' | 'all';
+/**
+ * Which refs a log (and therefore a commit read) may reach (session 14).
+ *
+ * `refs` names them explicitly; `includeRemotes`/`includeTags`/`all` widen the
+ * set to whole namespaces. `all` deliberately expands to
+ * `--branches --remotes --tags` rather than the bare `--all`, which would also
+ * drag in `refs/stash` and `refs/notes` — neither is history anybody asked for.
+ */
+export interface GitRefSelector {
+    refs?: string[];
+    includeRemotes?: boolean;
+    includeTags?: boolean;
+    all?: boolean;
+}
 export interface GitLogResult {
     branch: string;
     baseBranch: string;
@@ -73,6 +410,12 @@ export interface GitLogResult {
     mergeBase: string | null;
     commits: GitLogCommit[];
     hasMore: boolean;
+    /** The refs this page was actually allowed to walk — echoed for the caller. */
+    scopeRefs: string[];
+    /**
+     * Where the next page starts. Plain offset — see the note on `GitLogInput`.
+     */
+    nextSkip: number;
 }
 export interface GitCommitFileEntry {
     path: string;
@@ -89,9 +432,13 @@ export interface GitCommitDetail {
     author: string;
     authorEmail: string;
     date: string;
+    /** Session 14: the committer is a different person after a rebase. */
+    committer: string;
+    committerEmail: string;
+    committerDate: string;
     subject: string;
     body: string;
-    refs: string[];
+    refs: GitRef[];
     files: GitCommitFileEntry[];
     /** The file list hit the cap — the commit touched more than we return. */
     truncated: boolean;
@@ -103,19 +450,109 @@ export interface GitCommitFileDiff {
 }
 /** A full or abbreviated commit hash — never a ref name, never an option. */
 export declare function isCommitSha(value: string): boolean;
+/**
+ * Everything a ref name must satisfy before it becomes a git argument.
+ *
+ * The same class of check branch names go through (`sanitizeBranch`), because
+ * that is exactly what these are: `main`, `origin/main`, `v1.2.0`. A leading
+ * dash would be an option, `..` a range, and neither belongs in an argv slot
+ * built from a query string.
+ *
+ * Plus the pseudo-refs above, which are the hole this check exists to close.
+ */
+export declare function sanitizeRefName(value: unknown): string | null;
 /**
  * `--numstat` names a rename as `old => new` (or `dir/{old => new}/file`),
  * while `--name-status` gives the plain new path. Keying the two maps by
  * different strings is why every renamed file showed `null` additions.
  */
 export declare function normalizeNumstatPath(raw: string): string;
-export declare function gitLog(input: {
+export interface GitLogInput extends GitRefSelector {
     workspacePath: string;
-    branch: string;
+    /**
+     * The session branch. Optional since session 14: the repository graph is
+     * reached from the workspace, where there is no session and therefore no
+     * branch that has to be in the picture.
+     */
+    branch?: string;
     scope?: GitLogScope;
     limit?: number;
+    /**
+     * Where this page starts. An OFFSET, and deliberately so.
+     *
+     * Session 14 first paged by a `--before=<committer date>` cursor, to avoid
+     * the prefix re-walk `--skip` pays. That is unsound, and QA-108 proved it on
+     * real git with no clock skew at all: `--topo-order` holds a parent back
+     * until every child is emitted, so the emitted dates are NOT monotonically
+     * decreasing. One ordinary feature branch — started in January, merged in
+     * July — emits merge, the whole January side, then the June main-line, so a
+     * page boundary inside the January side leaves the remaining June commits
+     * NEWER than the page's date. `--before` then excludes them from every later
+     * page, `hasMore` goes false, and a truncated history is presented as
+     * complete. Taking the minimum date instead of the last made it strictly
+     * worse: a smaller boundary excludes more.
+     *
+     * There is no repair for that combination — a date filter and a topological
+     * order answer different questions. `--skip` re-walks the prefix, which is
+     * O(n) per page and invisible at the depths a human scrolls; every real git
+     * UI (GitHub, GitLab, VS Code's Git Graph) pages the same way.
+     */
     skip?: number;
-}): Promise<GitLogResult>;
+    /** The base pinned at session creation (session 13). */
+    baseBranch?: string;
+}
+export declare function gitLog(input: GitLogInput): Promise<GitLogResult>;
+export interface GitRefEntry extends GitRef {
+    sha: string;
+    subject: string;
+    /** Committer date, ISO-8601 — the list is sorted newest first by it. */
+    date: string;
+    /** For a local branch: the remote-tracking ref it follows, if any. */
+    upstream: string | null;
+    /** Absolute path of the worktree holding it — git refuses a second checkout. */
+    checkedOutIn: string | null;
+}
+export interface GitRefsResult {
+    refs: GitRefEntry[];
+    /** What the project folder is on right now (null on a detached HEAD). */
+    currentBranch: string | null;
+    currentSha: string | null;
+    remotes: string[];
+    truncated: boolean;
+}
+/**
+ * Every ref worth drawing, with the two facts a picker cannot get anywhere
+ * else: which worktree holds a branch, and what it tracks.
+ *
+ * One `for-each-ref` over the three namespaces rather than three calls — the
+ * type comes from the ref path, which is more reliable than guessing from the
+ * short name.
+ */
+export declare function gitRefs(workspacePath: string): Promise<GitRefsResult>;
+export interface WorkspaceStateResult {
+    /** The branch the project folder is on; null when HEAD is detached. */
+    branch: string | null;
+    sha: string | null;
+    subject: string;
+    /** Committer date of that commit, ISO-8601. */
+    date: string;
+    /** Uncommitted changes in the project folder itself. */
+    dirty: boolean;
+    dirtyFiles: number;
+    /** The remote-tracking branch it follows, and how far apart they are. */
+    upstream: string | null;
+    ahead: number | null;
+    behind: number | null;
+    remotes: string[];
+}
+/**
+ * The truth about the checkout everything is actually built from.
+ *
+ * The product used to collect exactly this during path validation and throw it
+ * away, which is why it could never answer «is the running build yours» — the
+ * question behind «how do I know docker was not rebuilt». Read-only.
+ */
+export declare function workspaceState(workspacePath: string): Promise<WorkspaceStateResult>;
 /**
  * One commit: its metadata and the files it touched, or — when `filePath` is
  * given — the diff of that one file.
@@ -125,12 +562,52 @@ export declare function gitLog(input: {
  * parents, and the answer to "what did this merge bring onto my branch" comes
  * out empty. For an ordinary commit the flag changes nothing.
  */
-export declare function gitShow(workspacePath: string, sha: string, filePath?: string, branch?: string): Promise<GitCommitDetail | GitCommitFileDiff>;
+export declare function gitShow(workspacePath: string, sha: string, filePath?: string, branch?: string, baseBranch?: string, selector?: GitRefSelector): Promise<GitCommitDetail | GitCommitFileDiff>;
 export interface RevertResult {
     reverted: boolean;
     revertSha?: string;
     conflict?: boolean;
+    /** Same refusal as «Apply», same reason — see `ApplyResult` (session 15). */
+    workspaceDirty?: boolean;
+    workspaceDirtyFiles?: string[];
+    workspaceDirtyCount?: number;
+    /** …and whether that dirt is a stopped merge, which cannot be committed. */
+    workspaceMergeInProgress?: boolean;
     error?: string;
 }
-export declare function revertApply(workspacePath: string, commitSha: string): Promise<RevertResult>;
+export declare const gitCommit: (worktreePath: string, message: string, options?: {
+    all?: boolean;
+} | undefined) => Promise<GitCommitResult>;
+export declare const gitStage: (input: {
+    worktreePath: string;
+    paths?: readonly string[];
+    all?: boolean;
+}) => Promise<GitStageResult>;
+export declare const gitUnstage: (input: {
+    worktreePath: string;
+    paths?: readonly string[];
+    all?: boolean;
+}) => Promise<GitStageResult>;
+export declare const gitDiscard: (input: {
+    worktreePath: string;
+    paths?: readonly string[];
+    all?: boolean;
+}) => Promise<GitDiscardResult>;
+export declare const gitPull: (input: {
+    worktreePath: string;
+}) => Promise<GitPullResult>;
+export declare const gitMergeAbort: (worktreePath: string) => Promise<GitMergeAbortResult>;
+export declare const applySession: (input: ApplySessionInput) => Promise<ApplyResult>;
+export declare const revertApply: (workspacePath: string, commitSha: string, expectedBase?: string | undefined) => Promise<RevertResult>;
+export declare const updateFromBase: (input: {
+    workspacePath: string;
+    worktreePath: string;
+    sessionBranch: string;
+    baseBranch?: string;
+}) => Promise<UpdateFromBaseResult>;
+export declare const gitPush: (input: {
+    workspacePath: string;
+    branch: string;
+    remote: string;
+}) => Promise<GitPushResult>;
 //# sourceMappingURL=gitops.d.ts.map