@senad-d/branchme 0.2.1 → 0.3.0

package/src/git.ts

@@ -33,6 +33,7 @@ import type {
   CreateWorktreeMode,
   CurrentBranchInfo,
   FetchBranchDetails,
+  FetchRemoteBranchDetails,
   GitExecResult,
   GitFileChange,
   GitFileChangeSummary,
@@ -740,7 +741,7 @@ export function validateWorktreePathInput(worktreePath: unknown): string {
   return normalizedPath;
 }
 
-async function canonicalizePathAllowMissing(path: string): Promise<string | null> {
+export async function canonicalizePathAllowMissing(path: string): Promise<string | null> {
   let candidate = normalize(path);
   const suffix: string[] = [];
 
@@ -758,7 +759,7 @@ async function canonicalizePathAllowMissing(path: string): Promise<string | null
   }
 }
 
-async function collectWorktreeInventory(
+export async function collectWorktreeInventory(
   pi: Pick<ExtensionAPI, "exec">,
   ctx: GitCommandContext,
   signal?: AbortSignal,
@@ -782,7 +783,7 @@ async function collectWorktreeInventory(
   return { repoRoot, canonicalCurrentPath, entries };
 }
 
-function pathIsInsideOrEqual(candidatePath: string, boundaryPath: string): boolean {
+export function pathIsInsideOrEqual(candidatePath: string, boundaryPath: string): boolean {
   const relation = relative(boundaryPath, candidatePath);
   return relation === "" || (relation !== ".." && !relation.startsWith(`..${sep}`) && !isAbsolute(relation));
 }
@@ -1185,6 +1186,39 @@ function worktreeCreationFailure(
   );
 }
 
+async function resolveWorktreeBaseCommit(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  baseRef: string,
+  signal?: AbortSignal,
+): Promise<string> {
+  // baseRef is a read-only start point: it is resolved to a commit before mutation and
+  // is never checked out, reset, or otherwise modified.
+  if (/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/iu.test(baseRef)) {
+    const result = await runGit(pi, ctx, ["rev-parse", "--verify", `${baseRef}^{commit}`], {
+      signal,
+      timeout: GIT_STATUS_TIMEOUT_MS,
+      allowFailure: true,
+    });
+    const commit = trimOutput(result.stdout);
+    if (result.code !== 0 || !/^[0-9a-f]{40,64}$/iu.test(commit)) {
+      throw new Error(`baseRef ${safeWorktreeBranchLabel(baseRef)} does not resolve to an existing commit.`);
+    }
+    return commit;
+  }
+
+  await validateBranchName(pi, ctx, baseRef, signal);
+  if (await localBranchExists(pi, ctx, baseRef, signal)) {
+    return getLocalBranchCommit(pi, ctx, baseRef, signal);
+  }
+  if (await remoteTrackingRefExists(pi, ctx, baseRef, signal)) {
+    return getRemoteTrackingRefCommit(pi, ctx, baseRef, signal);
+  }
+  throw new Error(
+    `baseRef ${safeWorktreeBranchLabel(baseRef)} does not name an existing local branch, remote-tracking ref, or full commit.`,
+  );
+}
+
 export async function createWorktree(
   pi: Pick<ExtensionAPI, "exec">,
   ctx: GitCommandContext,
@@ -1192,8 +1226,15 @@ export async function createWorktree(
   branchName: string,
   branchMode: CreateWorktreeMode,
   signal?: AbortSignal,
+  baseRef?: string,
 ): Promise<CreateWorktreeDetails> {
   validateCreateWorktreeMode(branchMode);
+  if (baseRef !== undefined) {
+    if (branchMode !== "new") {
+      throw new Error("baseRef is only supported with branchMode 'new'; an existing local branch keeps its own commit.");
+    }
+    validateBranchNameInput(baseRef, "baseRef");
+  }
   const requestedWorktreePath = validateWorktreePathInput(worktreePath);
   const repoRoot = await getGitRoot(pi, ctx, signal);
   const rootCtx = { cwd: repoRoot };
@@ -1222,11 +1263,14 @@ export async function createWorktree(
       throw new Error(`Local branch ${safeWorktreeBranchLabel(branchName)} is already checked out in a worktree.`);
     }
 
+    const baseCommit = baseRef === undefined
+      ? null
+      : await resolveWorktreeBaseCommit(pi, rootCtx, baseRef, signal);
     const expectedHead = branchMode === "new"
-      ? sourceHead
+      ? baseCommit ?? sourceHead
       : await getLocalBranchCommit(pi, rootCtx, branchName, signal);
     const args = branchMode === "new"
-      ? ["worktree", "add", "-b", branchName, prepared.canonicalPath, "HEAD"]
+      ? ["worktree", "add", "-b", branchName, prepared.canonicalPath, baseCommit ?? "HEAD"]
       : ["worktree", "add", prepared.canonicalPath, branchName];
 
     try {
@@ -1263,6 +1307,9 @@ export async function createWorktree(
           worktreePath: safeWorktreeValue(requestedWorktreePath, GIT_WORKTREE_PATH_LIMIT_CHARS),
           branchName: handoffBranch,
           branchMode,
+          ...(baseRef === undefined
+            ? {}
+            : { baseRef: safeWorktreeValue(baseRef, GIT_CONTEXT_VALUE_LIMIT_CHARS) }),
         },
         verified: {
           before: {
@@ -1352,7 +1399,11 @@ async function requirePresentWorktreeDirectory(canonicalPath: string): Promise<v
 
 interface WorktreeRemovalStatus {
   workingTree: WorkingTreeDetails;
-  hasIgnoredEntries: boolean;
+  ignoredPaths: string[];
+}
+
+function compareIgnoredPaths(left: string, right: string): number {
+  return left.localeCompare(right);
 }
 
 function parseWorktreeRemovalStatus(output: string): WorktreeRemovalStatus {
@@ -1361,7 +1412,7 @@ function parseWorktreeRemovalStatus(output: string): WorktreeRemovalStatus {
   }
 
   const records = output.split(NUL_SEPARATOR);
-  let hasIgnoredEntries = false;
+  const ignoredPaths = new Set<string>();
   let skipNextRecord = false;
   for (const [index, record] of records.entries()) {
     if (skipNextRecord) {
@@ -1372,12 +1423,12 @@ function parseWorktreeRemovalStatus(output: string): WorktreeRemovalStatus {
 
     const parsed = parsePorcelainChange(records, index);
     skipNextRecord = parsed.nextIndex > index;
-    if (parsed.status === "!!") hasIgnoredEntries = true;
+    if (parsed.status === "!!") ignoredPaths.add(parsed.path.split("/")[0]);
   }
 
   return {
     workingTree: parseWorkingTreeStatus(output).workingTree,
-    hasIgnoredEntries,
+    ignoredPaths: [...ignoredPaths].sort(compareIgnoredPaths),
   };
 }
 
@@ -1385,7 +1436,8 @@ async function inspectRemovableWorktree(
   pi: Pick<ExtensionAPI, "exec">,
   canonicalPath: string,
   signal?: AbortSignal,
-): Promise<WorkingTreeDetails> {
+  allowIgnored = false,
+): Promise<WorktreeRemovalStatus> {
   const workingTree = await inspectWorktreeState(pi, canonicalPath, signal);
   if (workingTree.state !== "clean") {
     throw new Error("The target worktree has staged, unstaged, untracked, or unmerged changes; clean it before removal.");
@@ -1399,12 +1451,12 @@ async function inspectRemovableWorktree(
   if (removalStatus.workingTree.state !== "clean") {
     throw new Error("The target worktree has staged, unstaged, untracked, or unmerged changes; clean it before removal.");
   }
-  if (removalStatus.hasIgnoredEntries) {
+  if (!allowIgnored && removalStatus.ignoredPaths.length > 0) {
     throw new Error(
       "The target worktree contains ignored files or directories; remove or preserve them outside the checkout before removal.",
     );
   }
-  return workingTree;
+  return removalStatus;
 }
 
 function assertWorktreeRemoved(
@@ -1440,7 +1492,22 @@ export async function removeWorktree(
   const repoRoot = await getGitRoot(pi, ctx, signal);
   const rootCtx = { cwd: repoRoot };
 
-  return withRepositoryMutationQueue(repoRoot, async () => {
+  return withRepositoryMutationQueue(
+    repoRoot,
+    removeWorktreeWithinQueue.bind(undefined, pi, rootCtx, requestedWorktreePath, signal),
+  );
+}
+
+// Caller must hold the repository mutation queue. Standalone removal still refuses ignored residue.
+export async function removeWorktreeWithinQueue(
+  pi: Pick<ExtensionAPI, "exec">,
+  rootCtx: GitCommandContext,
+  requestedWorktreePath: string,
+  signal?: AbortSignal,
+  allowIgnored = false,
+  expectedIdentity?: { branch: string; head: string },
+): Promise<RemoveWorktreeDetails & { deletedIgnoredPaths: string[] }> {
+    const repoRoot = rootCtx.cwd;
     const resolved = await resolveWorktreeRemovalTarget(
       pi,
       rootCtx,
@@ -1452,6 +1519,9 @@ export async function removeWorktree(
     }
 
     const worktree = requireRemovableWorktreeEntry(resolved);
+    if (expectedIdentity && (worktree.branch !== expectedIdentity.branch || worktree.head !== expectedIdentity.head)) {
+      throw new Error("The selected worktree branch or HEAD moved after the landing ancestry proof.");
+    }
     const branchName = resolved.entry.record.branch;
     const head = resolved.entry.record.head;
     if (branchName === null || head === null) {
@@ -1460,7 +1530,7 @@ export async function removeWorktree(
     const verifiedCanonicalPath = requireLosslessWorktreeIdentity(resolved.canonicalPath, "cwd");
     const retainedBranch = requireLosslessWorktreeIdentity(branchName, "branch");
     await requirePresentWorktreeDirectory(verifiedCanonicalPath);
-    const workingTree = await inspectRemovableWorktree(pi, verifiedCanonicalPath, signal);
+    const { workingTree, ignoredPaths } = await inspectRemovableWorktree(pi, verifiedCanonicalPath, signal, allowIgnored);
     const branchHeadBefore = await getLocalBranchCommit(pi, rootCtx, retainedBranch, signal);
     if (branchHeadBefore.toLowerCase() !== head.toLowerCase()) {
       throw new Error("The target local branch did not match the worktree HEAD before removal.");
@@ -1493,6 +1563,7 @@ export async function removeWorktree(
       );
       return {
         action: "remove_worktree",
+        deletedIgnoredPaths: ignoredPaths.map((path) => redactSecrets(path)),
         repoRoot: safeWorktreeValue(repoRoot, GIT_WORKTREE_PATH_LIMIT_CHARS),
         request: {
           worktreePath: safeWorktreeValue(requestedWorktreePath, GIT_WORKTREE_PATH_LIMIT_CHARS),
@@ -1520,7 +1591,6 @@ export async function removeWorktree(
     } catch (error) {
       throw worktreeRemovalFailure(error, resolved.canonicalPath, branchName);
     }
-  });
 }
 
 function isRenameOrCopyStatus(status: string): boolean {
@@ -1833,8 +1903,9 @@ export async function getAheadBehindCount(
   pi: Pick<ExtensionAPI, "exec">,
   ctx: GitCommandContext,
   signal?: AbortSignal,
+  comparison = "HEAD...@{u}",
 ): Promise<AheadBehindCount> {
-  const result = await runGit(pi, ctx, ["rev-list", "--left-right", "--count", "HEAD...@{u}"], {
+  const result = await runGit(pi, ctx, ["rev-list", "--left-right", "--count", comparison], {
     signal,
     timeout: GIT_STATUS_TIMEOUT_MS,
   });
@@ -1887,9 +1958,9 @@ export async function localBranchExists(
   return result.code === 0;
 }
 
-function requireLosslessLocalRef(branchName: string): string {
+function requireLosslessLocalRef(branchName: string, prefix = "refs/heads/"): string {
   requireLosslessWorktreeIdentity(branchName, "branch");
-  const fullRef = `refs/heads/${branchName}`;
+  const fullRef = `${prefix}${branchName}`;
   if (!isLosslessGitMetadata(fullRef, GIT_CONTEXT_VALUE_LIMIT_CHARS)) {
     throw new Error(
       "The full local branch ref cannot be returned safely and losslessly. " +
@@ -1967,9 +2038,28 @@ export async function inspectDirectLocalBranchRef(
   ctx: GitCommandContext,
   branchName: string,
   signal?: AbortSignal,
+): Promise<DirectLocalBranchRefInspection> {
+  return inspectDirectBranchRef(pi, ctx, branchName, "refs/heads/", signal);
+}
+
+export async function inspectDirectRemoteTrackingRef(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  refName: string,
+  signal?: AbortSignal,
+): Promise<DirectLocalBranchRefInspection> {
+  return inspectDirectBranchRef(pi, ctx, refName, "refs/remotes/", signal);
+}
+
+async function inspectDirectBranchRef(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  branchName: string,
+  prefix: string,
+  signal?: AbortSignal,
 ): Promise<DirectLocalBranchRefInspection> {
   validateBranchNameInput(branchName);
-  const fullRef = requireLosslessLocalRef(branchName);
+  const fullRef = requireLosslessLocalRef(branchName, prefix);
   const listArgs = [
     "for-each-ref",
     "--count=1",
@@ -1994,24 +2084,58 @@ export async function inspectDirectLocalBranchRef(
   };
 }
 
-export async function getLocalBranchCommit(
+async function getVerifiedRefCommit(
   pi: Pick<ExtensionAPI, "exec">,
   ctx: GitCommandContext,
-  branchName: string,
+  revision: string,
+  describedRef: string,
   signal?: AbortSignal,
 ): Promise<string> {
-  validateBranchNameInput(branchName);
-  const result = await runGit(pi, ctx, ["rev-parse", "--verify", `refs/heads/${branchName}^{commit}`], {
+  const result = await runGit(pi, ctx, ["rev-parse", "--verify", `${revision}^{commit}`], {
     signal,
     timeout: GIT_STATUS_TIMEOUT_MS,
   });
   const commit = trimOutput(result.stdout);
   if (!/^[0-9a-f]{40,64}$/iu.test(commit)) {
-    throw new Error(`Unable to resolve local branch '${safeGitContextValue(branchName)}' to a commit: ${safeOutput(result.stdout) || "empty output"}`);
+    throw new Error(`Unable to resolve ${describedRef} to a commit: ${safeOutput(result.stdout) || "empty output"}`);
   }
   return commit;
 }
 
+export async function getLocalBranchCommit(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  branchName: string,
+  signal?: AbortSignal,
+): Promise<string> {
+  validateBranchNameInput(branchName);
+  return getVerifiedRefCommit(pi, ctx, `refs/heads/${branchName}`, `local branch '${safeGitContextValue(branchName)}'`, signal);
+}
+
+export async function remoteTrackingRefExists(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  refName: string,
+  signal?: AbortSignal,
+): Promise<boolean> {
+  const result = await runGit(pi, ctx, ["show-ref", "--verify", "--quiet", `refs/remotes/${refName}`], {
+    signal,
+    timeout: GIT_STATUS_TIMEOUT_MS,
+    allowFailure: true,
+  });
+  return result.code === 0;
+}
+
+export async function getRemoteTrackingRefCommit(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  refName: string,
+  signal?: AbortSignal,
+): Promise<string> {
+  validateBranchNameInput(refName, "Remote-tracking ref");
+  return getVerifiedRefCommit(pi, ctx, `refs/remotes/${refName}`, `remote-tracking ref '${safeGitContextValue(refName)}'`, signal);
+}
+
 export async function requireExistingLocalBranch(
   pi: Pick<ExtensionAPI, "exec">,
   ctx: GitCommandContext,
@@ -2044,6 +2168,24 @@ export async function isCommitAncestor(
   return result.code === 0;
 }
 
+async function resolveAncestryRefCommit(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  refName: string,
+  label: "Source" | "Target",
+  signal?: AbortSignal,
+): Promise<string> {
+  // Read-only comparison endpoints: local branches keep precedence, remote-tracking refs
+  // (for example origin/main) are accepted as read baselines and are never mutated.
+  if (await localBranchExists(pi, ctx, refName, signal)) {
+    return getLocalBranchCommit(pi, ctx, refName, signal);
+  }
+  if (await remoteTrackingRefExists(pi, ctx, refName, signal)) {
+    return getRemoteTrackingRefCommit(pi, ctx, refName, signal);
+  }
+  throw new Error(`${label} local branch or remote-tracking ref '${safeGitContextValue(refName)}' does not exist.`);
+}
+
 export async function getLocalBranchAncestry(
   pi: Pick<ExtensionAPI, "exec">,
   ctx: GitCommandContext,
@@ -2054,11 +2196,9 @@ export async function getLocalBranchAncestry(
   validateBranchNameInput(query.targetBranch, "Target branch");
   await validateBranchName(pi, ctx, query.sourceBranch, signal);
   await validateBranchName(pi, ctx, query.targetBranch, signal);
-  await requireExistingLocalBranch(pi, ctx, query.sourceBranch, "Source", signal);
-  await requireExistingLocalBranch(pi, ctx, query.targetBranch, "Target", signal);
 
-  const sourceHead = await getLocalBranchCommit(pi, ctx, query.sourceBranch, signal);
-  const targetHead = await getLocalBranchCommit(pi, ctx, query.targetBranch, signal);
+  const sourceHead = await resolveAncestryRefCommit(pi, ctx, query.sourceBranch, "Source", signal);
+  const targetHead = await resolveAncestryRefCommit(pi, ctx, query.targetBranch, "Target", signal);
   const isAncestor = await isCommitAncestor(pi, ctx, sourceHead, targetHead, signal);
 
   return {
@@ -2181,6 +2321,88 @@ export async function fetchCurrentBranch(
   });
 }
 
+function validateRequestedRemoteName(remote: string): void {
+  if (!remote || /[\u0000-\u001f\u007f]/u.test(remote) || /\s/u.test(remote)) {
+    throw new Error("Unable to fetch: remote cannot be blank or contain whitespace or control characters.");
+  }
+  if (remote === ".") throw new Error("Unable to fetch: remote must name a configured Git remote, not '.'.");
+  if (remote.startsWith("-")) throw new Error("Unable to fetch: remote cannot start with '-'.");
+  if (remote.includes(":") || remote.includes("@")) {
+    throw new Error("Unable to fetch: remote cannot be a URL or user-prefixed target.");
+  }
+}
+
+async function requireConfiguredRemote(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  remote: string,
+  signal?: AbortSignal,
+): Promise<void> {
+  const result = await runGit(pi, ctx, ["remote", "get-url", remote], {
+    signal,
+    timeout: GIT_STATUS_TIMEOUT_MS,
+    allowFailure: true,
+  });
+  if (result.code !== 0) {
+    throw new Error(`Unable to fetch: remote '${safeGitContextValue(remote)}' is not a configured Git remote.`);
+  }
+}
+
+export async function fetchRemoteBranch(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  remote: string,
+  branch: string,
+  signal?: AbortSignal,
+): Promise<FetchRemoteBranchDetails> {
+  validateRequestedRemoteName(remote);
+  validateBranchNameInput(branch, "branch");
+  const repoRoot = await getGitRoot(pi, ctx, signal);
+  const rootCtx = { cwd: repoRoot };
+
+  return withRepositoryMutationQueue(
+    repoRoot,
+    fetchRemoteBranchWithinQueue.bind(undefined, pi, rootCtx, remote, branch, signal),
+  );
+}
+
+// Caller must hold the repository mutation queue.
+export async function fetchRemoteBranchWithinQueue(
+  pi: Pick<ExtensionAPI, "exec">,
+  rootCtx: GitCommandContext,
+  remote: string,
+  branch: string,
+  signal?: AbortSignal,
+): Promise<FetchRemoteBranchDetails> {
+    const repoRoot = rootCtx.cwd;
+    validateRequestedRemoteName(remote);
+    await validateBranchName(pi, rootCtx, branch, signal);
+    await requireConfiguredRemote(pi, rootCtx, remote, signal);
+
+    const remoteRef = `refs/heads/${branch}`;
+    const trackingRef = `refs/remotes/${remote}/${branch}`;
+    const refspec = `${remoteRef}:${trackingRef}`;
+    const result = await runGit(
+      pi,
+      rootCtx,
+      ["fetch", "--no-tags", "--no-recurse-submodules", remote, refspec],
+      {
+        signal,
+        timeout: GIT_FETCH_TIMEOUT_MS,
+      },
+    );
+
+    return {
+      repoRoot,
+      remote: safeDetail(remote),
+      branch: safeDetail(branch),
+      remoteRef: safeDetail(remoteRef),
+      remoteTrackingRef: safeDetail(trackingRef),
+      refspec: safeDetail(refspec),
+      output: safeOutput(result.stdout || result.stderr),
+    };
+}
+
 export async function pullCurrentBranch(
   pi: Pick<ExtensionAPI, "exec">,
   ctx: GitCommandContext,