@urateam/core 0.1.0

package/dist/repo/git.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Execute a git command with the given args in the given cwd.
+ * Uses execFile (never exec) to prevent command injection.
+ *
+ * Per-command execution details are logged at debug level; errors at error level.
+ */
+export declare function gitExec(args: string[], cwd: string, timeoutMs?: number): Promise<string>;
+/**
+ * Non-throwing variant of gitExec. Returns trimmed stdout on success,
+ * empty string on failure. For commands where leading whitespace matters
+ * (e.g. git status --porcelain), use gitExecRaw instead.
+ */
+export declare function gitExecSafe(args: string[], cwd: string, timeoutMs?: number): Promise<string>;
+/**
+ * Like gitExecSafe but preserves leading whitespace in output.
+ * Needed for `git status --porcelain` where " M file.txt" has meaningful leading space.
+ */
+export declare function gitExecRaw(args: string[], cwd: string, timeoutMs?: number): Promise<string>;
+/**
+ * Clone the repo to dir. If dir exists and has the correct remote, run fetchLatest instead.
+ */
+export declare function cloneRepo(url: string, dir: string): Promise<void>;
+/**
+ * Fetch latest from origin.
+ */
+export declare function fetchLatest(repoDir: string): Promise<void>;
+/**
+ * Create a git worktree for the given run.
+ * Creates branch from HEAD. Returns the worktree path.
+ * If the branch is already checked out in a stale worktree, removes it and retries.
+ * Also installs a pre-push branch-safety hook in the shared .git directory.
+ */
+export declare function createWorktree(repoDir: string, runId: string, branch: string, baseDir?: string): Promise<string>;
+/**
+ * Create a git worktree that checks out an existing remote branch.
+ * Used for feedback runs where the PR branch already exists.
+ * Fetches origin first, then creates the worktree from origin/<branch>.
+ * Returns the worktree path.
+ * Also installs a pre-push branch-safety hook in the shared .git directory.
+ */
+export declare function createWorktreeFromRemote(repoDir: string, runId: string, branch: string, baseDir?: string): Promise<string>;
+/**
+ * Read the current HEAD branch name for a worktree.
+ * Returns the branch name (e.g. "agent/BEC-99-foo") or empty string on failure.
+ */
+export declare function getCurrentBranch(worktreePath: string): Promise<string>;
+/**
+ * Verify that the worktree's HEAD is on the expected branch.
+ * Throws an Error (and logs) if a mismatch is detected.
+ *
+ * This is the primary cross-worktree contamination guard: if an agent (or a
+ * tool invoked by the agent) ran `git checkout <other-branch>` inside the
+ * worktree, any subsequent commit or push would silently land on the wrong
+ * branch.  Calling this function before committing or pushing turns the
+ * silent data loss into a loud, recoverable error.
+ */
+export declare function verifyBranchMatch(worktreePath: string, expectedBranch: string): Promise<void>;
+/**
+ * Install a pre-push git hook in the shared .git directory of the given clone.
+ * The hook verifies that the branch being pushed matches the worktree's HEAD,
+ * providing a last-line-of-defence against cross-branch contamination.
+ *
+ * Because all worktrees of a clone share the same .git/hooks/ directory, this
+ * hook is installed once per clone — it protects every worktree.
+ *
+ * The hook is idempotent: if a pre-push hook already exists that was installed
+ * by the Linear Agent Framework, it is not overwritten.
+ */
+export declare function installPrePushHook(repoDir: string): Promise<void>;
+/**
+ * Remove a worktree.
+ */
+export declare function deleteWorktree(worktreePath: string): Promise<void>;
+/**
+ * Push the branch to origin.
+ * Verifies that the worktree HEAD is on the expected branch before pushing
+ * to prevent cross-branch contamination (BEC-99).
+ */
+export declare function pushBranch(worktreePath: string, branch: string): Promise<void>;
+/**
+ * Fetch latest from origin and rebase the current branch on top of
+ * origin/<baseBranch>.
+ *
+ * Returns { success: true } if the rebase applied cleanly.
+ * Returns { success: false } if there are unresolved conflicts — the caller
+ * must either resolve them (then run `git rebase --continue`) or call
+ * abortRebase() before attempting another git operation.
+ */
+export declare function rebaseBranch(worktreePath: string, baseBranch: string): Promise<{
+    success: boolean;
+    hasConflicts: boolean;
+}>;
+/**
+ * Abort an in-progress rebase (non-throwing).
+ * Safe to call even when no rebase is in progress.
+ */
+export declare function abortRebase(worktreePath: string): Promise<void>;
+/**
+ * Push the branch to origin using --force-with-lease.
+ * Used as a fallback when auto-rebase fails and the pipeline needs to push
+ * the original (possibly diverged) branch for human review.
+ * Verifies that the worktree HEAD is on the expected branch before pushing
+ * to prevent cross-branch contamination (BEC-99).
+ */
+export declare function pushBranchForce(worktreePath: string, branch: string): Promise<void>;
+/**
+ * Determines the push strategy for a given branch and rebase state.
+ *
+ * Returns `"force-with-lease"` when:
+ * - The branch name starts with `"agent/"` (pipeline-owned branches that may
+ *   have a stale remote ref from a previous failed run), OR
+ * - `rebaseConflict` is true (force-push to preserve diverged work for human review).
+ *
+ * Returns `"standard"` for all other branches (human-owned branches where an
+ * accidental force-push could overwrite reviewer commits).
+ */
+export declare function choosePushStrategy(branch: string, rebaseConflict: boolean): "force-with-lease" | "standard";
+/**
+ * Check for uncommitted changes and auto-commit them if found.
+ * Returns true if a commit was made, false if the worktree was clean.
+ *
+ * This is a safety net for when the agent doesn't commit its work
+ * (hits maxTurns, maxTokens, or a permission error). Without this,
+ * the push queue's rebase fails and the work is lost.
+ *
+ * @param expectedBranch - When provided, the function verifies that the
+ *   worktree HEAD is on this branch before committing.  A mismatch throws
+ *   immediately to prevent cross-branch contamination (BEC-99).
+ */
+export declare function autoCommitChanges(worktreePath: string, issueId: string, expectedBranch?: string): Promise<boolean>;
+/**
+ * Get commit subject lines authored on this branch since it diverged from the
+ * base branch. Used to include agent-authored commit messages in PR descriptions.
+ * Returns commits in chronological order (oldest first).
+ * Returns an empty array on failure (fail-open — commit listing is best-effort).
+ */
+export declare function getAgentCommits(worktreePath: string, baseBranch: string): Promise<string[]>;
+/**
+ * Create a PR using the `gh` CLI. Returns the PR URL.
+ * Falls back gracefully — returns empty string if `gh` is not available.
+ */
+export declare function createPRViaCli(options: {
+    worktreePath: string;
+    branch: string;
+    base: string;
+    title: string;
+    body: string;
+    draft?: boolean;
+}): Promise<string>;
+/**
+ * Merge a PR using the `gh` CLI. Returns true on success.
+ */
+export declare function mergePRViaCli(worktreePath: string, branch: string): Promise<boolean>;
+/**
+ * Get the list of files changed between the branch and the merge base with the
+ * default branch. Used for auto-merge exclusion pattern matching.
+ * Returns an empty array on failure (fail-open — pattern matching is best-effort).
+ */
+export declare function getChangedFiles(worktreePath: string, baseBranch: string): Promise<string[]>;
+/**
+ * Get the number of changed lines (additions + deletions) between the branch
+ * and the merge base with the default branch. This measures the actual PR diff,
+ * not uncommitted working tree changes.
+ */
+export declare function getDiffLineCount(worktreePath: string, baseBranch: string): Promise<number>;
+/**
+ * Check if a branch already exists on the remote for this issue.
+ * Uses the repo URL directly (no local clone needed).
+ * Returns the branch name if found, null otherwise.
+ * Silently returns null on failure (fail-open — dedup is best-effort).
+ */
+export declare function checkDuplicateBranch(repoUrl: string, issueId: string): Promise<string | null>;
+/**
+ * Generate a branch name from issue ID and slug.
+ */
+export declare function branchName(issueId: string, slug: string): string;
+/**
+ * Scan baseDir for run directories (each containing a "worktree" sub-dir) that
+ * are older than ttlHours and remove them.  Returns the list of paths removed.
+ *
+ * TTL is measured against the directory's mtime so that an actively-modified
+ * worktree (e.g. still being debugged) resets the clock on every write.
+ */
+export declare function cleanupWorktrees(baseDir: string, ttlHours?: number): Promise<string[]>;
+//# sourceMappingURL=git.d.ts.map

package/dist/repo/git.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../../src/repo/git.ts"],"names":[],"mappings":"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"}