@senad-d/branchme 0.3.1 → 0.3.3

package/src/git.ts

@@ -1,4 +1,4 @@
-import { lstat, realpath, stat } from "node:fs/promises";
+import { lstat, readFile, realpath, stat } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, normalize, relative, sep } from "node:path";
 import { withFileMutationQueue, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
@@ -629,7 +629,7 @@ function truncateWorktreeValue(value: string, limit: number): string {
   return `${value.slice(0, end)}…`;
 }
 
-function safeWorktreeValue(value: string, limit: number): string {
+export function safeWorktreeValue(value: string, limit: number): string {
   const redacted = redactSecrets(value);
   const escaped = redacted.replace(/[\p{Cc}\p{Cf}\u2028\u2029]/gu, escapeGitContextControlCharacter);
   return truncateWorktreeValue(escaped, limit);
@@ -954,6 +954,14 @@ export async function canonicalizePathAllowMissing(path: string): Promise<string
   }
 }
 
+async function resolveWorktreeInventoryEntry(
+  record: ParsedWorktreeRecord,
+  index: number,
+): Promise<WorktreeInventoryEntry> {
+  const canonicalPath = await canonicalizePathAllowMissing(record.rawPath);
+  return { record, index, canonicalPath };
+}
+
 export async function collectWorktreeInventory(
   pi: Pick<ExtensionAPI, "exec">,
   ctx: GitCommandContext,
@@ -971,10 +979,11 @@ export async function collectWorktreeInventory(
     throw new Error("Unable to inspect worktrees: current repository path could not be resolved.");
   }
 
-  const entries: WorktreeInventoryEntry[] = [];
+  const entryPromises: Promise<WorktreeInventoryEntry>[] = [];
   for (const [index, record] of records.entries()) {
-    entries.push({ record, index, canonicalPath: await canonicalizePathAllowMissing(record.rawPath) });
+    entryPromises.push(resolveWorktreeInventoryEntry(record, index));
   }
+  const entries = await Promise.all(entryPromises);
   return { repoRoot, canonicalCurrentPath, entries };
 }
 
@@ -983,16 +992,20 @@ export function pathIsInsideOrEqual(candidatePath: string, boundaryPath: string)
   return relation === "" || (relation !== ".." && !relation.startsWith(`..${sep}`) && !isAbsolute(relation));
 }
 
-async function requireCanonicalCreationPath(worktreePath: string): Promise<string> {
-  const parentPath = dirname(worktreePath);
-  let parentStats;
+async function requireCanonicalCreationParent(parentPath: string): Promise<string> {
   try {
-    parentStats = await stat(parentPath);
-  } catch {
-    throw new Error(`worktreePath parent ${safeWorktreePathLabel(parentPath)} must exist as a directory.`);
-  }
-  if (!parentStats.isDirectory()) {
-    throw new Error(`worktreePath parent ${safeWorktreePathLabel(parentPath)} must be a directory.`);
+    // lstat distinguishes a missing directory from a dangling symlink.
+    await lstat(parentPath);
+  } catch (error) {
+    if (filesystemErrorCode(error) === "ENOTDIR") {
+      throw new Error(`worktreePath parent ${safeWorktreePathLabel(parentPath)} must be a directory.`);
+    }
+    const ancestorPath = dirname(parentPath);
+    if (filesystemErrorCode(error) !== "ENOENT" || ancestorPath === parentPath) {
+      throw new Error(`worktreePath parent ${safeWorktreePathLabel(parentPath)} could not be inspected.`);
+    }
+    // Resolve missing ancestors without writing; Git creates them after preflight.
+    return join(await requireCanonicalCreationParent(ancestorPath), basename(parentPath));
   }
 
   let canonicalParent: string;
@@ -1001,12 +1014,25 @@ async function requireCanonicalCreationPath(worktreePath: string): Promise<strin
   } catch {
     throw new Error(`worktreePath parent ${safeWorktreePathLabel(parentPath)} could not be resolved.`);
   }
+  let parentStats;
+  try {
+    parentStats = await stat(canonicalParent);
+  } catch {
+    throw new Error(`worktreePath parent ${safeWorktreePathLabel(parentPath)} could not be inspected.`);
+  }
+  if (!parentStats.isDirectory()) {
+    throw new Error(`worktreePath parent ${safeWorktreePathLabel(parentPath)} must be a directory.`);
+  }
+  return canonicalParent;
+}
 
+async function requireCanonicalCreationPath(worktreePath: string): Promise<string> {
+  const canonicalParent = await requireCanonicalCreationParent(dirname(worktreePath));
   const canonicalPath = join(canonicalParent, basename(worktreePath));
   try {
     await lstat(canonicalPath);
   } catch (error) {
-    if (isMissingFilesystemPath(error)) return canonicalPath;
+    if (filesystemErrorCode(error) === "ENOENT") return canonicalPath;
     throw new Error(`worktreePath destination ${safeWorktreePathLabel(canonicalPath)} could not be inspected.`);
   }
   throw new Error(`worktreePath destination ${safeWorktreePathLabel(canonicalPath)} already exists.`);
@@ -1092,10 +1118,8 @@ export async function getGitOperationState(
   }
 
   const active: GitOperationKind[] = [];
-  const presentMarkers: boolean[] = [];
-  for (const [index, path] of paths.entries()) {
-    const present = await gitOperationMarkerExists(path);
-    presentMarkers.push(present);
+  const presentMarkers = await Promise.all(paths.map(gitOperationMarkerExists));
+  for (const [index, present] of presentMarkers.entries()) {
     if (!present) continue;
     const operation = GIT_OPERATION_MARKERS[index][1];
     if (!active.includes(operation)) active.push(operation);
@@ -2378,6 +2402,33 @@ async function getVerifiedRefCommit(
   return commit;
 }
 
+export async function getMergeHeadCommit(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  signal?: AbortSignal,
+): Promise<string> {
+  const result = await runGit(pi, ctx, ["rev-parse", "--path-format=absolute", "--git-path", "MERGE_HEAD"], {
+    signal, timeout: GIT_STATUS_TIMEOUT_MS,
+  });
+  const path = stripSingleLineTerminator(result.stdout);
+  if (!isAbsolute(path) || /[\p{Cc}\p{Cf}\u2028\u2029]/u.test(path)) {
+    throw new Error("Unable to inspect MERGE_HEAD: Git returned an invalid state path.");
+  }
+  const metadata = await lstat(path);
+  if (!metadata.isFile() || metadata.size > 65) {
+    throw new Error("MERGE_HEAD must contain exactly one commit; multi-head merges are not supported.");
+  }
+  const contents = await readFile(path, { encoding: "utf8", signal });
+  if (!/^(?:[0-9a-f]{40}|[0-9a-f]{64})\n?$/iu.test(contents)) {
+    throw new Error("MERGE_HEAD must contain exactly one valid commit identity.");
+  }
+  const commit = await getVerifiedRefCommit(pi, ctx, "MERGE_HEAD", "MERGE_HEAD", signal);
+  if (commit.toLowerCase() !== contents.trimEnd().toLowerCase()) {
+    throw new Error("MERGE_HEAD changed during inspection; inspect the merge before retrying.");
+  }
+  return commit;
+}
+
 export async function getLocalBranchCommit(
   pi: Pick<ExtensionAPI, "exec">,
   ctx: GitCommandContext,

package/src/tools/branchme-tools.ts

@@ -9,7 +9,6 @@ import {
   CREATE_WORKTREE_TOOL_NAME,
   FETCH_BRANCH_TOOL_NAME,
   GIT_BRANCH_SUMMARY_LIMIT_CHARS,
-  GIT_INTEGRATION_SUMMARY_LIMIT_CHARS,
   GIT_RETIREMENT_SUMMARY_LIMIT_CHARS,
   GIT_WORKTREE_SUMMARY_LIMIT_CHARS,
   INIT_REPOSITORY_TOOL_NAME,
@@ -47,7 +46,7 @@ import {
   withRepositoryMutationQueue,
 } from "../git.ts";
 import { collectGitContext, formatGitContext } from "../git-context.ts";
-import { integrateBranch } from "../git-integration.ts";
+import { formatConflictPathList, integrateBranch } from "../git-integration.ts";
 import { retireBranch } from "../git-retirement.ts";
 import { formatLandBranch, landBranch } from "../git-landing.ts";
 import {
@@ -328,42 +327,17 @@ export function formatRemoveWorktree(details: RemoveWorktreeDetails): string {
   return `Removed linked worktree directory ${path}. Verified it is no longer registered and retained local branch ${branch} at HEAD ${shortCommit(details.handoff.head)}; the removed cwd is not ready for handoff.`;
 }
 
-function integrationConflictOmissionLine(omitted: number): string {
-  return `${omitted} conflict path${omitted === 1 ? "" : "s"} omitted.`;
-}
-
-function formatIntegrationConflict(details: Extract<IntegrateBranchDetails, { status: "conflict" }>): string {
+function formatIntegrationConflict(details: Extract<IntegrateBranchDetails, { status: "conflict" | "conflict_kept" }>): string {
   const source = safeWorktreeFormatValue(details.request.sourceBranch, WORKTREE_FORMAT_BRANCH_LIMIT_CHARS);
   const target = safeWorktreeFormatValue(details.request.targetBranch, WORKTREE_FORMAT_BRANCH_LIMIT_CHARS);
-  const lines = [
-    `integrate_branch found conflicts while integrating ${source} into ${target}; the merge was automatically aborted and exact restoration was verified at target HEAD ${shortCommit(details.verified.heads.after.targetHead)}.`,
-    "Conflict paths:",
-  ];
-  let omitted = details.conflict.omitted;
-
-  for (const [index, entry] of details.conflict.paths.entries()) {
-    const path = safeWorktreeFormatValue(entry.path, WORKTREE_FORMAT_PATH_LIMIT_CHARS);
-    const line = `- ${path}`;
-    const remaining = details.conflict.paths.length - index - 1;
-    const candidateOmitted = details.conflict.omitted + remaining;
-    const candidate = [
-      ...lines,
-      line,
-      ...(candidateOmitted > 0 ? [integrationConflictOmissionLine(candidateOmitted)] : []),
-    ].join("\n");
-    if (candidate.length > GIT_INTEGRATION_SUMMARY_LIMIT_CHARS) {
-      omitted += details.conflict.paths.length - index;
-      break;
-    }
-    lines.push(line);
-  }
-
-  if (omitted > 0) lines.push(integrationConflictOmissionLine(omitted));
-  return lines.join("\n");
+  const header = details.status === "conflict"
+    ? `integrate_branch found conflicts while integrating ${source} into ${target}; the merge was automatically aborted and exact restoration was verified at target HEAD ${shortCommit(details.verified.heads.after.targetHead)}.`
+    : `integrate_branch found conflicts while integrating ${source} into ${target}; the merge was kept in progress at target HEAD ${shortCommit(details.heads.targetHead)} and must be finished with conclude_merge.`;
+  return formatConflictPathList(header, details.conflict);
 }
 
 export function formatIntegrateBranch(details: IntegrateBranchDetails): string {
-  if (details.status === "conflict") return formatIntegrationConflict(details);
+  if (details.status === "conflict" || details.status === "conflict_kept") return formatIntegrationConflict(details);
 
   const source = safeWorktreeFormatValue(details.request.sourceBranch, WORKTREE_FORMAT_BRANCH_LIMIT_CHARS);
   const target = safeWorktreeFormatValue(details.request.targetBranch, WORKTREE_FORMAT_BRANCH_LIMIT_CHARS);

package/src/tools/workflow-tools.ts

@@ -1,11 +1,57 @@
+import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { PULL_REQUEST_STATUS_TOOL_NAME, TRACK_BRANCH_TOOL_NAME, UPDATE_FROM_BASE_TOOL_NAME } from "../constants.ts";
-import { getGitRoot, requireCurrentBranch } from "../git.ts";
+import {
+  CONCLUDE_MERGE_TOOL_NAME, GIT_CONTEXT_VALUE_LIMIT_CHARS, PULL_REQUEST_STATUS_TOOL_NAME, TRACK_BRANCH_TOOL_NAME,
+  UPDATE_FROM_BASE_TOOL_NAME,
+} from "../constants.ts";
+import { getGitRoot, requireCurrentBranch, safeWorktreeValue } from "../git.ts";
+import { concludeMerge, formatConflictPathList } from "../git-integration.ts";
 import { findGitHubPullRequest, getGitHubPullRequest, resolveGitHubRepository, resolveGitHubToken } from "../github.ts";
-import type { PullRequestStatusDetails } from "../types.ts";
+import type { ConcludeMergeDetails, PullRequestStatusDetails } from "../types.ts";
 import type { BranchMeToolOptions } from "./branchme-tools.ts";
-import { trackBranch, updateFromBase } from "../git-workflow.ts";
+import { trackBranch, updateFromBase, type UpdateFromBaseDetails } from "../git-workflow.ts";
+
+function shortCommit(commit: string): string {
+  return commit.slice(0, 12);
+}
+
+function branchLabel(branch: string): string {
+  return safeWorktreeValue(branch, GIT_CONTEXT_VALUE_LIMIT_CHARS);
+}
+
+export function formatUpdateFromBase(details: UpdateFromBaseDetails): string {
+  const { integration } = details;
+  const source = branchLabel(integration.request.sourceBranch);
+  const target = branchLabel(integration.request.targetBranch);
+  if (integration.status === "conflict") {
+    return formatConflictPathList(
+      `update_from_base: conflict. Merging ${source} into ${target} conflicted; the merge was automatically aborted and restoration was verified at HEAD ${shortCommit(integration.verified.heads.after.targetHead)}. Rerun with keepConflicts: true to keep the conflicted merge in progress for resolution.`,
+      integration.conflict,
+    );
+  }
+  if (integration.status === "conflict_kept") {
+    return formatConflictPathList(
+      `update_from_base: conflict_kept. Merging ${source} (${shortCommit(integration.heads.sourceHead)}) into ${target} conflicted; the merge is in progress with MERGE_HEAD set and HEAD unchanged at ${shortCommit(integration.heads.targetHead)}. Remove the conflict markers in the listed paths, then run conclude_merge with action "conclude" to commit the merge or action "abort" to restore the branch.`,
+      integration.conflict,
+    );
+  }
+  return `update_from_base: ${integration.status}. Base integration verified without rewriting published history.`;
+}
+
+export function formatConcludeMerge(details: ConcludeMergeDetails): string {
+  const branch = branchLabel(details.branch);
+  if (details.status === "aborted") {
+    return `conclude_merge: aborted. git merge --abort restored ${branch} to HEAD ${shortCommit(details.head)}; MERGE_HEAD ${shortCommit(details.mergeHead)} is cleared, no Git operation is in progress, and the working tree is clean.`;
+  }
+  const count = details.resolvedPaths.length;
+  return formatConflictPathList(
+    `conclude_merge: concluded. Committed merge ${shortCommit(details.heads.after)} on ${branch} with parents ${shortCommit(details.parents.first)} (previous HEAD) and ${shortCommit(details.parents.second)} (MERGE_HEAD); MERGE_HEAD is cleared and both parents were verified. Only the ${count} resolved path${count === 1 ? "" : "s"} listed below ${count === 1 ? "was" : "were"} staged during this call; other working-tree changes remain unstaged. The commit includes all previously staged entries.`,
+    { paths: details.resolvedPaths, omitted: 0 },
+    "Resolved paths:",
+    "resolved path",
+  );
+}
 
 function formatPullRequestStatus(pullRequest: PullRequestStatusDetails | null): string {
   if (!pullRequest) return "No matching pull request found.";
@@ -47,20 +93,43 @@ export function registerWorkflowTools(pi: Pick<ExtensionAPI, "registerTool" | "e
   pi.registerTool({
     name: UPDATE_FROM_BASE_TOOL_NAME,
     label: "Update From Base",
-    description: "update_from_base fetches one remote base and merges its captured commit into the clean current feature branch with verified no-op, fast-forward, merge-commit, or automatically aborted conflict results. Never rebases, pushes, stashes, or changes upstream configuration.",
-    promptSnippet: "update_from_base: merge a fresh remote base into the current feature without rewriting published history",
+    description: "update_from_base fetches one remote base and merges its captured commit into the clean current feature branch with verified no-op, fast-forward, merge-commit, or conflict results. A conflict is automatically aborted with restoration verified unless keepConflicts is true, which leaves the conflicted merge in progress for conclude_merge. Never rebases, pushes, stashes, or changes upstream configuration.",
+    promptSnippet: "update_from_base: merge a fresh remote base into the current feature without rewriting published history; keepConflicts keeps a conflicted merge in progress",
     promptGuidelines: [
       "Use update_from_base only when asked to update the current feature branch from an explicit baseBranch; remote defaults to origin.",
-      "Run update_from_base by itself. It fetches the base and uses the fixed normal-merge policy; conflicts are automatically aborted with restoration verified.",
-      "update_from_base preserves published history and upstream configuration; committing conflict-resolution changes belongs to a separate workflow.",
+      "Run update_from_base by itself. It fetches the base and uses the fixed normal-merge policy; by default conflicts are automatically aborted with restoration verified and the conflict paths are listed.",
+      "Pass keepConflicts: true to update_from_base only when a file-editing step will resolve the listed paths; the result conflict_kept leaves MERGE_HEAD set, and conclude_merge must then conclude or abort it before any other Git mutation.",
+      "update_from_base preserves published history and upstream configuration; it never resolves conflict content itself.",
     ],
     parameters: Type.Object({
       baseBranch: Type.String({ minLength: 1, description: "Exact base branch on the remote, for example main." }),
       remote: Type.Optional(Type.String({ minLength: 1, description: "Configured remote; defaults to origin." })),
+      keepConflicts: Type.Optional(Type.Boolean({ description: "When true, a conflicted merge is left in progress (MERGE_HEAD set, conflicted paths unmerged) for conclude_merge instead of being aborted; defaults to false." })),
     }, { additionalProperties: false }),
     async execute(_id, params, signal, _update, ctx) {
       const details = await updateFromBase(pi, ctx, params, signal);
-      return { content: [{ type: "text", text: `update_from_base: ${details.status}. ${details.status === "conflict" ? "Merge aborted and restoration verified; inspect conflict paths in details." : "Base integration verified without rewriting published history."}` }], details };
+      return { content: [{ type: "text", text: formatUpdateFromBase(details) }], details };
+    },
+  });
+  pi.registerTool({
+    name: CONCLUDE_MERGE_TOOL_NAME,
+    label: "Conclude Merge",
+    description: "conclude_merge finishes or abandons the in-progress merge on the current checkout, normally one kept by update_from_base with keepConflicts: true. action \"conclude\" checks unmerged working-tree paths and staged blobs for default/custom-sized conflict marker lines, stages exactly the unmerged paths, checks the candidate index again, and commits the full index with Git's prepared merge message, then verifies the two-parent result; action \"abort\" runs git merge --abort and verifies restoration. conclude_merge never stages other changes, accepts no commit message, and never pushes.",
+    promptSnippet: "conclude_merge: commit or abort the kept in-progress merge after conflict markers are removed",
+    promptGuidelines: [
+      "Use conclude_merge only after update_from_base reported conflict_kept, or when a single-head merge is otherwise in progress on the current checkout; run conclude_merge by itself. Multi-head merges are refused before mutation.",
+      "Before conclude_merge with action conclude, a file-editing step must remove every <<<<<<<, |||||||, =======, and >>>>>>> marker line from the listed paths; conclude_merge refuses and names the paths that still contain markers.",
+      "conclude_merge with action conclude stages only the currently unmerged paths and uses Git's prepared merge message; unrelated unstaged edits stay unstaged and are not part of the merge commit. Git commits the entire index, including previously staged entries: do not stage unrelated edits during the merge.",
+      "conclude_merge with action abort restores the branch with git merge --abort and verifies a clean idle checkout; conclude_merge refuses when no merge is in progress.",
+    ],
+    parameters: Type.Object({
+      action: StringEnum(["conclude", "abort"] as const, {
+        description: "conclude stages the resolved formerly unmerged paths and commits the merge; abort runs git merge --abort and verifies restoration.",
+      }),
+    }, { additionalProperties: false }),
+    async execute(_id, params, signal, _update, ctx) {
+      const details = await concludeMerge(pi, ctx, params, signal);
+      return { content: [{ type: "text", text: formatConcludeMerge(details) }], details };
     },
   });
   pi.registerTool({

package/src/types.ts

@@ -318,7 +318,7 @@ export interface PushBranchDetails {
   output: string;
 }
 
-export type IntegrateBranchStatus = "already_integrated" | "fast_forward" | "merge_commit" | "conflict";
+export type IntegrateBranchStatus = "already_integrated" | "fast_forward" | "merge_commit" | "conflict" | "conflict_kept";
 
 export interface IntegrateBranchHeads {
   sourceHead: string;
@@ -406,11 +406,72 @@ export interface IntegrateBranchConflictDetails extends IntegrateBranchDetailsBa
   };
 }
 
+/** A conflicted merge deliberately left in progress (update_from_base keepConflicts); conclude_merge finishes or abandons it. */
+export interface IntegrateBranchConflictKeptDetails {
+  action: "integrate_branch";
+  status: "conflict_kept";
+  mergeExecuted: true;
+  request: IntegrateBranchToolInput;
+  /** targetHead is the unchanged HEAD; sourceHead is the commit recorded in MERGE_HEAD. */
+  heads: IntegrateBranchHeads;
+  conflict: {
+    paths: IntegrateBranchConflictPathEntry[];
+    omitted: number;
+    kept: true;
+    mergeInProgress: true;
+  };
+}
+
 export type IntegrateBranchDetails =
   | IntegrateBranchAlreadyIntegratedDetails
   | IntegrateBranchFastForwardDetails
   | IntegrateBranchMergeCommitDetails
-  | IntegrateBranchConflictDetails;
+  | IntegrateBranchConflictDetails
+  | IntegrateBranchConflictKeptDetails;
+
+export type ConcludeMergeAction = "conclude" | "abort";
+
+export interface ConcludeMergeToolInput {
+  action: ConcludeMergeAction;
+}
+
+export interface ConcludeMergeConcludedDetails {
+  action: "conclude_merge";
+  status: "concluded";
+  request: ConcludeMergeToolInput;
+  repoRoot: string;
+  branch: string;
+  heads: {
+    before: string;
+    after: string;
+  };
+  parents: {
+    first: string;
+    second: string;
+  };
+  mergeHead: string;
+  /** Exactly the formerly unmerged paths that were staged for the merge commit. */
+  resolvedPaths: IntegrateBranchConflictPathEntry[];
+}
+
+export interface ConcludeMergeAbortedDetails {
+  action: "conclude_merge";
+  status: "aborted";
+  request: ConcludeMergeToolInput;
+  repoRoot: string;
+  branch: string;
+  head: string;
+  mergeHead: string;
+  restoration: {
+    verified: true;
+    headRestored: true;
+    branchPreserved: true;
+    operationStateCleared: true;
+    cleanWorktree: true;
+  };
+}
+
+export type ConcludeMergeDetails = ConcludeMergeConcludedDetails | ConcludeMergeAbortedDetails;
 
 export type RetireBranchMode = "merged" | "forced_unmerged";