@senad-d/branchme 0.3.2 → 0.3.3

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";