@rethunk/mcp-multi-root-git 3.1.0 → 4.0.0

package/dist/server/batch-commit-tool.js

@@ -1,6 +1,8 @@
-import { existsSync } from "node:fs";
+import { existsSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
 import { z } from "zod";
-import { isStrictlyUnderGitTop, resolvePathForRepo } from "../repo-paths.js";
+import { assertRelativePathUnderTop, resolvePathForRepo } from "../repo-paths.js";
 import { ERROR_CODES } from "./error-codes.js";
 import { spawnGitAsync } from "./git.js";
 import { getCurrentBranch, inferRemoteFromUpstream } from "./git-refs.js";
@@ -20,6 +22,9 @@ const FileEntrySchema = z.union([
                 .min(1)
                 .max(1000000)
                 .describe("End line number (1-indexed, inclusive)."),
+        })
+            .refine((l) => l.from <= l.to, {
+            message: "lines.from must be <= lines.to",
         })
             .describe("Line range to stage. Only hunks overlapping [from, to] are staged."),
     }),
@@ -30,7 +35,10 @@ const CommitEntrySchema = z.object({
         .array(FileEntrySchema)
         .min(1)
         .describe("Paths to stage, relative to git root. String or `{ path, lines }` for hunk-level staging. " +
-        "Deleted tracked files are staged via `git rm --cached`. Cannot combine `lines` with a deleted file."),
+        "Each path is staged individually (`git add` / `git apply --cached` / `git rm --cached`); " +
+        "on mid-entry stage failure, already-staged paths for that entry are unstaged. " +
+        "Deleted tracked files are staged via `git rm --cached`. Cannot combine `lines` with a deleted file. " +
+        "Rejects `.`, the repo root, and directory pathspecs."),
 });
 const PushModeSchema = z
     .enum(["never", "after"])
@@ -42,7 +50,30 @@ const DryRunSchema = z
     .boolean()
     .optional()
     .default(false)
-    .describe("Stage files and return a preview without writing commits; unstages afterwards. Response is marked DRY RUN.");
+    .describe("Stage files and return a preview without writing commits; restores the index afterwards. Response is marked DRY RUN.");
+/**
+ * True when `path` would stage the whole tree or a directory (not a single file).
+ * Rejects `.`, `./`, paths resolving to gitTop, trailing-slash directory forms,
+ * and on-disk directories.
+ */
+function isWholeTreeOrDirectoryPathspec(path, gitTop) {
+    const t = path.trim();
+    if (t === "" || t === "." || t === "./")
+        return true;
+    if (t.endsWith("/") || t.endsWith("/.") || t.endsWith("/.."))
+        return true;
+    const abs = resolvePathForRepo(path, gitTop);
+    if (resolve(abs) === resolve(gitTop))
+        return true;
+    try {
+        if (existsSync(abs) && statSync(abs).isDirectory())
+            return true;
+    }
+    catch {
+        // ignore stat errors — treat as non-directory
+    }
+    return false;
+}
 /**
  * Parses a unified diff to extract hunks that overlap with a given line range.
  * Returns a partial patch containing only the overlapping hunks, including header lines.
@@ -159,23 +190,42 @@ async function stageFile(gitTop, filePath, lines) {
             error: addResult.ok ? undefined : (addResult.stderr || addResult.stdout).trim(),
         };
     }
-    // Line range case: extract overlapping hunks and apply patch
-    const diffResult = await spawnGitAsync(gitTop, ["diff", filePath]);
-    if (!diffResult.ok) {
-        return { ok: false, error: (diffResult.stderr || diffResult.stdout).trim() };
+    // Line range case: extract overlapping hunks and apply patch.
+    // Tracked files: unstaged worktree vs index (`git diff -- path`).
+    // Untracked files: synthesize a new-file diff via `--no-index` (exit 1 with
+    // differences is expected — treat non-empty stdout as success).
+    const tracked = await spawnGitAsync(gitTop, ["ls-files", "--error-unmatch", "--", filePath]);
+    let diffStdout;
+    if (tracked.ok) {
+        const diffResult = await spawnGitAsync(gitTop, ["diff", "--", filePath]);
+        if (!diffResult.ok && !diffResult.stdout.trim()) {
+            return { ok: false, error: (diffResult.stderr || diffResult.stdout).trim() };
+        }
+        diffStdout = diffResult.stdout;
+    }
+    else {
+        const diffResult = await spawnGitAsync(gitTop, [
+            "diff",
+            "--no-index",
+            "--",
+            "/dev/null",
+            filePath,
+        ]);
+        // --no-index exits 1 when files differ; accept stdout as the patch body.
+        if (!diffResult.stdout.trim()) {
+            return {
+                ok: false,
+                error: (diffResult.stderr || diffResult.stdout || "No hunks found in line range").trim(),
+            };
+        }
+        diffStdout = diffResult.stdout;
     }
-    const partialPatch = extractOverlappingHunks(diffResult.stdout, lines.from, lines.to);
+    const partialPatch = extractOverlappingHunks(diffStdout, lines.from, lines.to);
     if (!partialPatch) {
         return { ok: false, error: "No hunks found in line range" };
     }
-    // Resolve the real git dir (works for linked worktrees where .git is a file, not a dir)
-    const gitDirResult = await spawnGitAsync(gitTop, ["rev-parse", "--absolute-git-dir"]);
-    if (!gitDirResult.ok) {
-        return { ok: false, error: (gitDirResult.stderr || gitDirResult.stdout).trim() };
-    }
-    const gitDir = gitDirResult.stdout.trim();
-    // Write partial patch to temp file in the git dir and apply it to the index
-    const tempPatchFile = `${gitDir}/.mcp-patch-${Date.now()}-${Math.random().toString(36).slice(2)}.patch`;
+    // Write partial patch to a temp file outside the git dir (avoids orphan files in .git)
+    const tempPatchFile = join(tmpdir(), `.mcp-patch-${Date.now()}-${Math.random().toString(36).slice(2)}.patch`);
     const { writeFileSync, unlinkSync } = await import("node:fs");
     writeFileSync(tempPatchFile, partialPatch, "utf8");
     const applyResult = await spawnGitAsync(gitTop, ["apply", "--cached", tempPatchFile]);
@@ -226,7 +276,11 @@ export function registerBatchCommitTool(server) {
     server.addTool({
         name: "batch_commit",
         description: "Create multiple sequential git commits in one call. " +
-            "Each entry stages its files then commits. Stops on first failure. " +
+            "Each entry stages its files then commits. Unrelated pre-staged index paths " +
+            "are temporarily unstaged around the commit so they are not included " +
+            "(hunk-level staging is preserved — pathspec commit mode is not used). " +
+            "Stops on first failure; mid-entry stage failures unstage that entry's " +
+            "already-staged paths. " +
             'Optional `push: "after"` pushes after all commits succeed. `dryRun: true` previews without writing.',
         annotations: {
             readOnlyHint: false,
@@ -248,18 +302,18 @@ export function registerBatchCommitTool(server) {
                 return jsonRespond(pre.error);
             const gitTop = pre.gitTop;
             const results = [];
-            const stagedFilesForCleanup = new Set();
-            // Snapshot already-staged paths BEFORE the preview loop so dry-run cleanup
-            // doesn't unstage files the caller had staged before invoking.
-            let preStagedPaths = new Set();
+            // Snapshot the full index before dry-run so cleanup restores pre-staged
+            // paths even when dryRun stages additional hunks onto the same paths.
+            let indexTreeBefore;
             if (args.dryRun) {
-                const snapResult = await spawnGitAsync(gitTop, ["diff", "--cached", "--name-only"]);
-                if (snapResult.ok) {
-                    preStagedPaths = new Set(snapResult.stdout
-                        .split("\n")
-                        .map((s) => s.trim())
-                        .filter(Boolean));
+                const wt = await spawnGitAsync(gitTop, ["write-tree"]);
+                if (!wt.ok) {
+                    return jsonRespond({
+                        error: ERROR_CODES.COMMIT_FAILED,
+                        detail: (wt.stderr || wt.stdout).trim() || "failed to snapshot index before dryRun",
+                    });
                 }
+                indexTreeBefore = wt.stdout.trim();
             }
             for (let i = 0; i < args.commits.length; i++) {
                 const entry = args.commits[i];
@@ -268,21 +322,38 @@ export function registerBatchCommitTool(server) {
                 // Normalize file entries to { path, lines? } format
                 const fileEntries = [];
                 const filePaths = [];
+                let invalidLineRange = false;
                 for (const fileEntry of entry.files) {
                     if (typeof fileEntry === "string") {
                         fileEntries.push({ path: fileEntry });
                         filePaths.push(fileEntry);
                     }
                     else {
+                        if (fileEntry.lines.from > fileEntry.lines.to) {
+                            invalidLineRange = true;
+                            filePaths.push(fileEntry.path);
+                            break;
+                        }
                         fileEntries.push(fileEntry);
                         filePaths.push(fileEntry.path);
                     }
                 }
+                if (invalidLineRange) {
+                    results.push({
+                        index: i,
+                        ok: false,
+                        message: entry.message,
+                        files: filePaths,
+                        error: ERROR_CODES.INVALID_LINE_RANGE,
+                        detail: "lines.from must be <= lines.to",
+                    });
+                    break;
+                }
                 // --- Validate all paths are under the git toplevel ---
                 const escapedPaths = [];
                 for (const path of filePaths) {
                     const abs = resolvePathForRepo(path, gitTop);
-                    if (!isStrictlyUnderGitTop(abs, gitTop)) {
+                    if (!assertRelativePathUnderTop(path, abs, gitTop)) {
                         escapedPaths.push(path);
                     }
                 }
@@ -297,9 +368,23 @@ export function registerBatchCommitTool(server) {
                     });
                     break;
                 }
+                // --- Reject `.` / repo-root / directory pathspecs ---
+                const invalidPaths = filePaths.filter((p) => isWholeTreeOrDirectoryPathspec(p, gitTop));
+                if (invalidPaths.length > 0) {
+                    results.push({
+                        index: i,
+                        ok: false,
+                        message: entry.message,
+                        files: filePaths,
+                        error: ERROR_CODES.INVALID_PATHS,
+                        detail: `directory or whole-tree pathspec rejected: ${invalidPaths.join(", ")}`,
+                    });
+                    break;
+                }
                 // --- Stage files (with optional line ranges) ---
                 let stagingFailed = false;
                 let stagingError = "";
+                const stagedSoFar = [];
                 for (const fileEntry of fileEntries) {
                     const stageResult = await stageFile(gitTop, fileEntry.path, fileEntry.lines);
                     if (!stageResult.ok) {
@@ -307,16 +392,14 @@ export function registerBatchCommitTool(server) {
                         stagingError = stageResult.error || "Unknown error";
                         break;
                     }
-                    // Track for dry-run cleanup as soon as a file stages successfully — a later
-                    // file in this same commit entry may still fail, and anything already staged
-                    // must still be unstaged so a failed dry run never leaves index state behind.
-                    // Excludes paths that were already staged before this call (so pre-existing
-                    // staged state survives).
-                    if (args.dryRun && !preStagedPaths.has(fileEntry.path)) {
-                        stagedFilesForCleanup.add(fileEntry.path);
-                    }
+                    stagedSoFar.push(fileEntry.path);
                 }
                 if (stagingFailed) {
+                    // Unstage anything this entry already staged (live + dryRun).
+                    // dryRun final cleanup also restores via read-tree when available.
+                    if (stagedSoFar.length > 0) {
+                        await spawnGitAsync(gitTop, ["restore", "--staged", "--", ...stagedSoFar]);
+                    }
                     results.push({
                         index: i,
                         ok: false,
@@ -328,10 +411,16 @@ export function registerBatchCommitTool(server) {
                     });
                     break;
                 }
-                // --- Dry-run mode: collect preview and unstage ---
+                // --- Dry-run mode: collect preview scoped to this entry's paths ---
                 if (args.dryRun) {
-                    // Get diff stat for this staged entry
-                    const diffStatResult = await spawnGitAsync(gitTop, ["diff", "--staged", "--stat"]);
+                    // Path-scoped stat so multi-entry previews do not accumulate prior entries.
+                    const diffStatResult = await spawnGitAsync(gitTop, [
+                        "diff",
+                        "--staged",
+                        "--stat",
+                        "--",
+                        ...filePaths,
+                    ]);
                     const diffStat = diffStatResult.ok ? (diffStatResult.stdout || "").trim() : undefined;
                     results.push({
                         index: i,
@@ -341,11 +430,55 @@ export function registerBatchCommitTool(server) {
                         staged: filePaths,
                         ...spreadDefined("diffStat", diffStat || undefined),
                     });
-                    continue; // Skip actual commit in dry-run mode
+                    // Unstage this entry before the next so the next entry's staging starts clean
+                    // relative to the snapshot (final read-tree still restores pre-call index).
+                    await spawnGitAsync(gitTop, ["restore", "--staged", "--", ...filePaths]);
+                    continue;
+                }
+                // --- Commit: isolate entry files from unrelated pre-staged index paths ---
+                // `git commit -- <paths>` uses --only (worktree) mode and would squash
+                // hunk-level staging. Instead: snapshot index, temporarily unstage
+                // unrelated staged paths, commit from the index, then restore them.
+                const stagedNamesResult = await spawnGitAsync(gitTop, ["diff", "--cached", "--name-only"]);
+                const stagedNames = stagedNamesResult.ok
+                    ? stagedNamesResult.stdout
+                        .split("\n")
+                        .map((s) => s.trim())
+                        .filter(Boolean)
+                    : [];
+                const entryPathSet = new Set(filePaths);
+                const unrelatedStaged = stagedNames.filter((p) => !entryPathSet.has(p));
+                let indexSnap;
+                if (unrelatedStaged.length > 0) {
+                    const wt = await spawnGitAsync(gitTop, ["write-tree"]);
+                    if (!wt.ok) {
+                        results.push({
+                            index: i,
+                            ok: false,
+                            message: entry.message,
+                            files: filePaths,
+                            error: ERROR_CODES.COMMIT_FAILED,
+                            detail: (wt.stderr || wt.stdout).trim() ||
+                                "failed to snapshot index for pre-staged path isolation",
+                        });
+                        break;
+                    }
+                    indexSnap = wt.stdout.trim();
+                    await spawnGitAsync(gitTop, ["restore", "--staged", "--", ...unrelatedStaged]);
                 }
-                // --- Commit ---
                 const commitResult = await spawnGitAsync(gitTop, ["commit", "-m", entry.message]);
                 if (!commitResult.ok) {
+                    // Restore unrelated staged paths even on failure so we don't leave the
+                    // index worse than when we entered this entry.
+                    if (indexSnap && unrelatedStaged.length > 0) {
+                        await spawnGitAsync(gitTop, [
+                            "restore",
+                            `--source=${indexSnap}`,
+                            "--staged",
+                            "--",
+                            ...unrelatedStaged,
+                        ]);
+                    }
                     const gitOutput = (commitResult.stderr || commitResult.stdout).trim();
                     results.push({
                         index: i,
@@ -358,6 +491,15 @@ export function registerBatchCommitTool(server) {
                     });
                     break;
                 }
+                if (indexSnap && unrelatedStaged.length > 0) {
+                    await spawnGitAsync(gitTop, [
+                        "restore",
+                        `--source=${indexSnap}`,
+                        "--staged",
+                        "--",
+                        ...unrelatedStaged,
+                    ]);
+                }
                 // --- Extract SHA from commit output ---
                 const shaMatch = /\[[\w/.-]+\s+([0-9a-f]+)\]/.exec(commitResult.stdout);
                 const gitOutput = (commitResult.stdout || commitResult.stderr).trim();
@@ -370,10 +512,9 @@ export function registerBatchCommitTool(server) {
                     ...spreadDefined("output", gitOutput || undefined),
                 });
             }
-            // --- In dry-run mode, unstage all files ---
-            if (args.dryRun && stagedFilesForCleanup.size > 0) {
-                const filesToReset = Array.from(stagedFilesForCleanup);
-                await spawnGitAsync(gitTop, ["reset", "HEAD", "--", ...filesToReset]);
+            // --- In dry-run mode, restore the full pre-call index ---
+            if (args.dryRun && indexTreeBefore) {
+                await spawnGitAsync(gitTop, ["read-tree", indexTreeBefore]);
             }
             const allOk = results.length === args.commits.length && results.every((r) => r.ok);
             // --- Optional push after all commits succeed (not in dry-run mode) ---

package/dist/server/error-codes.js

@@ -29,7 +29,13 @@ export const ERROR_CODES = {
     INVALID_PATHS: "invalid_paths",
     INVALID_REMOTE_OR_BRANCH: "invalid_remote_or_branch",
     INVALID_SINCE: "invalid_since",
+    /** Canonical path-escape wire string (grep/diff/blame/show/stash). */
     PATH_ESCAPES_REPO: "path_escapes_repo",
+    /**
+     * Legacy path-escape alias used by `batch_commit`. Same failure class as
+     * `PATH_ESCAPES_REPO`; clients should treat both as equivalent until a
+     * future contract bump unifies them (Worker P owns batch_commit migration).
+     */
     PATH_ESCAPES_REPOSITORY: "path_escapes_repository",
     UNSAFE_RANGE_TOKEN: "unsafe_range_token",
     UNSAFE_REF_TOKEN: "unsafe_ref_token",
@@ -40,8 +46,11 @@ export const ERROR_CODES = {
     ONTO_DETACHED_HEAD: "onto_detached_head",
     PROTECTED_BRANCH: "protected_branch",
     WORKING_TREE_DIRTY: "working_tree_dirty",
-    // Branch list
-    BRANCH_LIST_FAILED: "branch_list_failed",
+    // Branch create/delete/rename
+    BRANCH_CREATE_FAILED: "branch_create_failed",
+    BRANCH_DELETE_FAILED: "branch_delete_failed",
+    BRANCH_RENAME_FAILED: "branch_rename_failed",
+    MISSING_NEW_NAME: "missing_new_name",
     // Commit / stage
     COMMIT_FAILED: "commit_failed",
     STAGE_FAILED: "stage_failed",
@@ -49,16 +58,15 @@ export const ERROR_CODES = {
     GIT_DIFF_FAILED: "git_diff_failed",
     // Log
     GIT_LOG_FAILED: "git_log_failed",
+    // Grep (pickaxe)
+    GIT_GREP_FAILED: "git_grep_failed",
     // Show
     GIT_SHOW_FAILED: "git_show_failed",
     // Blame
     GIT_BLAME_FAILED: "git_blame_failed",
-    // Reflog
-    REFLOG_FAILED: "reflog_failed",
     // Stash
-    STASH_LIST_FAILED: "stash_list_failed",
-    // Fetch
-    // (uses UNSAFE_REMOTE_TOKEN and UNSAFE_REF_TOKEN)
+    STASH_APPLY_FAILED: "stash_apply_failed",
+    STASH_PUSH_FAILED: "stash_push_failed",
     // Push
     PUSH_DETACHED_HEAD: "push_detached_head",
     PUSH_FAILED: "push_failed",
@@ -66,16 +74,26 @@ export const ERROR_CODES = {
     // Merge
     CANNOT_FAST_FORWARD: "cannot_fast_forward",
     DESTINATION_NOT_FOUND: "destination_not_found",
+    MERGE_ABORT_FAILED: "merge_abort_failed",
     MERGE_BASE_FAILED: "merge_base_failed",
     MERGE_CONFLICTS: "merge_conflicts",
     MERGE_FAILED: "merge_failed",
+    REBASE_ABORT_FAILED: "rebase_abort_failed",
     REBASE_CONFLICTS: "rebase_conflicts",
     SOURCE_NOT_FOUND: "source_not_found",
     // Cherry-pick
     CHECKOUT_FAILED: "checkout_failed",
+    CHERRY_PICK_ABORT_FAILED: "cherry_pick_abort_failed",
+    CHERRY_PICK_CONTINUE_FAILED: "cherry_pick_continue_failed",
+    CHERRY_PICK_IN_PROGRESS: "cherry_pick_in_progress",
+    CHERRY_PICK_TOO_MANY_COMMITS: "cherry_pick_too_many_commits",
+    CHERRY_PICK_UNRESOLVED_PATHS: "cherry_pick_unresolved_paths",
+    NO_CHERRY_PICK_IN_PROGRESS: "no_cherry_pick_in_progress",
     RANGE_RESOLUTION_FAILED: "range_resolution_failed",
     // Reset
     RESET_FAILED: "reset_failed",
+    // Revert
+    REVERT_ABORT_FAILED: "revert_abort_failed",
     // Tag
     REF_NOT_FOUND: "ref_not_found",
     TAG_CREATE_FAILED: "tag_create_failed",

package/dist/server/git-blame-tool.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { assertRelativePathUnderTop, resolvePathForRepo } from "../repo-paths.js";
 import { ERROR_CODES } from "./error-codes.js";
 import { spawnGitAsync } from "./git.js";
-import { isSafeGitRefToken } from "./git-refs.js";
+import { isSafeGitCommitIsh } from "./git-refs.js";
 import { jsonRespond, spreadDefined, spreadWhen } from "./json.js";
 import { requireSingleRepo } from "./roots.js";
 import { WorkspacePickSchema } from "./schemas.js";
@@ -182,7 +182,10 @@ export function registerGitBlameTool(server) {
         },
         parameters: WorkspacePickSchema.extend({
             path: z.string().min(1).describe("Repo-relative path to the file to blame."),
-            ref: z.string().optional().describe("Optional commit-ish (SHA, branch, tag) to blame at."),
+            ref: z
+                .string()
+                .optional()
+                .describe('Optional commit-ish (SHA, branch, tag) to blame at. Ancestor notation is accepted (e.g. "HEAD~3", "main^2").'),
             startLine: z
                 .number()
                 .int()
@@ -218,7 +221,7 @@ export function registerGitBlameTool(server) {
             }
             // Ref validation
             if (args.ref !== undefined) {
-                if (!isSafeGitRefToken(args.ref)) {
+                if (!isSafeGitCommitIsh(args.ref)) {
                     return jsonRespond({ error: ERROR_CODES.UNSAFE_REF_TOKEN, ref: args.ref });
                 }
             }

package/dist/server/git-branch-tool.js

@@ -0,0 +1,151 @@
+import { z } from "zod";
+import { ERROR_CODES } from "./error-codes.js";
+import { spawnGitAsync } from "./git.js";
+import { isProtectedBranch, isSafeGitAncestorRef, isSafeGitRefToken } from "./git-refs.js";
+import { jsonRespond } from "./json.js";
+import { requireSingleRepo } from "./roots.js";
+import { WorkspacePickSchema } from "./schemas.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Resolve a ref (branch/commit-ish) to its full SHA; `null` if unresolvable. */
+async function getRefSha(gitTop, ref) {
+    const result = await spawnGitAsync(gitTop, [
+        "rev-parse",
+        "--verify",
+        "--quiet",
+        `${ref}^{commit}`,
+    ]);
+    if (!result.ok)
+        return null;
+    const sha = result.stdout.trim();
+    return sha === "" ? null : sha;
+}
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+export function registerGitBranchTool(server) {
+    server.addTool({
+        name: "git_branch",
+        description: "Create, delete, or rename a local git branch. `action: 'create'` makes `name` from `from` " +
+            "(default HEAD); `action: 'delete'` removes `name` (`force: true` for an unmerged branch, `-D`); " +
+            "`action: 'rename'` renames `name` to `newName`. Refuses protected branch names " +
+            "(main/master/dev/develop/stable/trunk/prod/production/release*/hotfix*) in any role.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+        },
+        parameters: WorkspacePickSchema.extend({
+            action: z.enum(["create", "delete", "rename"]).describe("Which branch operation to perform."),
+            name: z
+                .string()
+                .min(1)
+                .describe("Branch name to create/delete, or the existing branch name for rename."),
+            from: z
+                .string()
+                .optional()
+                .describe("Commit-ish to base a new branch on (create only). Default: HEAD."),
+            newName: z.string().optional().describe("New branch name (required for rename)."),
+            force: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("Force-delete an unmerged branch (`git branch -D`). Delete only; never overrides protected-branch rejection."),
+        }),
+        execute: async (args) => {
+            const pre = requireSingleRepo(server, args);
+            if (!pre.ok)
+                return jsonRespond(pre.error);
+            const { gitTop } = pre;
+            const name = args.name.trim();
+            if (!isSafeGitRefToken(name)) {
+                return jsonRespond({ error: ERROR_CODES.UNSAFE_REF_TOKEN, ref: name });
+            }
+            if (isProtectedBranch(name)) {
+                return jsonRespond({ error: ERROR_CODES.PROTECTED_BRANCH, branch: name });
+            }
+            if (args.action === "create") {
+                const fromRef = (args.from ?? "HEAD").trim();
+                if (!isSafeGitAncestorRef(fromRef)) {
+                    return jsonRespond({ error: ERROR_CODES.UNSAFE_REF_TOKEN, ref: fromRef });
+                }
+                const sha = await getRefSha(gitTop, fromRef);
+                if (!sha) {
+                    return jsonRespond({ error: ERROR_CODES.REF_NOT_FOUND, ref: fromRef });
+                }
+                const createResult = await spawnGitAsync(gitTop, ["branch", name, fromRef]);
+                if (!createResult.ok) {
+                    return jsonRespond({
+                        error: ERROR_CODES.BRANCH_CREATE_FAILED,
+                        detail: (createResult.stderr || createResult.stdout).trim(),
+                    });
+                }
+                return respond(args.format, { action: "create", branch: name, sha }, fromRef);
+            }
+            if (args.action === "delete") {
+                const sha = await getRefSha(gitTop, name);
+                if (!sha) {
+                    return jsonRespond({ error: ERROR_CODES.REF_NOT_FOUND, ref: name });
+                }
+                const deleteArgs = ["branch", args.force ? "-D" : "-d", name];
+                const deleteResult = await spawnGitAsync(gitTop, deleteArgs);
+                if (!deleteResult.ok) {
+                    return jsonRespond({
+                        error: ERROR_CODES.BRANCH_DELETE_FAILED,
+                        detail: (deleteResult.stderr || deleteResult.stdout).trim(),
+                    });
+                }
+                return respond(args.format, { action: "delete", branch: name, sha });
+            }
+            // action === "rename"
+            const newName = args.newName?.trim();
+            if (!newName) {
+                return jsonRespond({ error: ERROR_CODES.MISSING_NEW_NAME });
+            }
+            if (!isSafeGitRefToken(newName)) {
+                return jsonRespond({ error: ERROR_CODES.UNSAFE_REF_TOKEN, ref: newName });
+            }
+            if (isProtectedBranch(newName)) {
+                return jsonRespond({ error: ERROR_CODES.PROTECTED_BRANCH, branch: newName });
+            }
+            const renameResult = await spawnGitAsync(gitTop, ["branch", "-m", name, newName]);
+            if (!renameResult.ok) {
+                return jsonRespond({
+                    error: ERROR_CODES.BRANCH_RENAME_FAILED,
+                    detail: (renameResult.stderr || renameResult.stdout).trim(),
+                });
+            }
+            const sha = await getRefSha(gitTop, newName);
+            if (!sha) {
+                return jsonRespond({
+                    error: ERROR_CODES.BRANCH_RENAME_FAILED,
+                    detail: `renamed '${name}' to '${newName}' but could not resolve its SHA`,
+                });
+            }
+            return respond(args.format, { action: "rename", branch: newName, sha }, undefined, name);
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// Output rendering
+// ---------------------------------------------------------------------------
+function respond(format, result, from, renamedFrom) {
+    if (format === "json") {
+        return jsonRespond(result);
+    }
+    const lines = [];
+    if (result.action === "create") {
+        lines.push(`# Branch created: ${result.branch}`);
+        lines.push("");
+        lines.push(`**From:** ${from ?? "HEAD"}`);
+    }
+    else if (result.action === "delete") {
+        lines.push(`# Branch deleted: ${result.branch}`);
+    }
+    else {
+        lines.push(`# Branch renamed: ${renamedFrom ?? "?"} → ${result.branch}`);
+    }
+    lines.push(`**SHA:** \`${result.sha}\``);
+    return lines.join("\n");
+}