@bridge4dev/runner 0.51.0 → 0.53.0

package/dist/git.d.ts

@@ -1,8 +1,42 @@
+/**
+ * Why git stopped, in a sentence a person can act on.
+ *
+ * `git worktree add` prints its progress to stderr as carriage-return-overwritten
+ * frames, so a process killed mid-checkout leaves «Updating files: 1% (51/2693)»
+ * as the last thing anybody sees — a number, with no verb. The real cause lives
+ * on the error object (`killed`, `signal`, `code`) and nobody was reading it
+ * (#360). Keep the last progress frame, because «how far did it get» is the one
+ * useful thing in it, and put the cause in front of it.
+ */
+export declare function describeGitFailure(error: unknown, context?: {
+    timeoutMs?: number;
+}): string;
+/** What went wrong while building the session's workplace, in one machine-readable word. */
+export type WorktreePrepareCode = 'worktree_prepare_failed' | 'branch_taken' | 'worktree_cleanup_failed';
+/**
+ * A preparation failure that already knows its own fork point.
+ *
+ * The fork point matters precisely BECAUSE preparation failed: without it the
+ * API keeps `base_sha = null` for the session's whole life, and «Continue» can
+ * never prove that the branch it is about to adopt is the empty one this very
+ * session created a moment ago (#360, plan Р6).
+ */
+export declare class WorktreePrepareError extends Error {
+    readonly code: WorktreePrepareCode;
+    readonly baseBranch?: string;
+    readonly baseSha?: string;
+    constructor(message: string, code: WorktreePrepareCode, base?: {
+        baseBranch?: string;
+        baseSha?: string;
+    });
+}
 export interface PathValidation {
     ok: boolean;
     exists: boolean;
     isGitRepo: boolean;
     branch?: string;
+    /** The repository's own main branch, as this machine can see it without the network. */
+    defaultBranch?: string;
     error?: string;
 }
 /**
@@ -16,6 +50,23 @@ export interface PathValidation {
  * '/opt/ids'». That sentence is true and unactionable.
  */
 export declare function validateWorkspacePath(workspacePath: string): Promise<PathValidation>;
+/**
+ * The repository's main branch, read locally (ADR 0004).
+ *
+ * `origin/HEAD` is the honest answer and it is already on disk — set by `clone`,
+ * refreshed by `git remote set-head`. Never asked over the network: this runs
+ * inside a 4-second probe budget, and a repository whose origin is unreachable
+ * must still bind.
+ */
+export declare function remoteDefaultBranch(workspacePath: string): Promise<string | null>;
+/**
+ * `main`, then `master`, and only if the repository really has one.
+ *
+ * The order and the list are one decision, not two: `gitops.ts` asks the same
+ * question when «Apply» has no pinned base, and two copies would drift the day
+ * somebody adds `develop` to one of them (ADR 0004).
+ */
+export declare function firstConventionalBranch(workspacePath: string): Promise<string | null>;
 export declare function sessionShortId(sessionId: string): string;
 export declare function sessionWorktreePath(sessionId: string): string;
 /**
@@ -69,6 +120,19 @@ export declare function ensureSessionWorktree(workspacePath: string, sessionId:
     requireExistingBranch?: boolean;
     plan?: BranchPlan;
 }): Promise<SessionWorktree>;
+/**
+ * Delete a session branch that provably carries no commits (#360).
+ *
+ * Shares its safety rungs with {@link deleteSessionBranch} — prune, then the
+ * folder's own branch, then the holder — and adds the one this caller needs:
+ * the tip must still be exactly the fork point we started from. `-D`, not `-d`,
+ * because `-d` asks «is it merged into the branch THIS folder is on», which is
+ * a different question and answers «no» for a branch that is empty.
+ */
+export declare function dropEmptySessionBranch(workspacePath: string, branch: string, expectedSha: string): Promise<{
+    removed: boolean;
+    leftover?: string;
+}>;
 /**
  * DIRECT mode (session 16): the session's workplace IS the project folder.
  *