@rethunk/mcp-multi-root-git 2.1.0 → 2.3.0

package/dist/server/git-refs.js

@@ -0,0 +1,192 @@
+import { spawnGitAsync } from "./git.js";
+// ---------------------------------------------------------------------------
+// Merge conflict helpers (shared between git_merge and git_cherry_pick)
+// ---------------------------------------------------------------------------
+/** Paths with unresolved merge conflicts (`--diff-filter=U`). */
+export async function conflictPaths(gitTop) {
+    const r = await spawnGitAsync(gitTop, ["diff", "--name-only", "--diff-filter=U"]);
+    if (!r.ok)
+        return [];
+    return r.stdout
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0);
+}
+// ---------------------------------------------------------------------------
+// Protected branch names — never auto-delete, never cascade destructive ops onto
+// ---------------------------------------------------------------------------
+const PROTECTED_EXACT = new Set([
+    "main",
+    "master",
+    "dev",
+    "develop",
+    "stable",
+    "trunk",
+    "prod",
+    "production",
+    "HEAD",
+]);
+const PROTECTED_PATTERN = /^(release|hotfix)[-/].+$/i;
+/** True when a branch name is on the protected list and must not be auto-deleted. */
+export function isProtectedBranch(name) {
+    const t = name.trim();
+    if (t === "")
+        return true;
+    if (PROTECTED_EXACT.has(t))
+        return true;
+    return PROTECTED_PATTERN.test(t);
+}
+// ---------------------------------------------------------------------------
+// Ref/branch name validation (argv-safe subset of git's ref-format rules)
+// ---------------------------------------------------------------------------
+/**
+ * Conservative check for branch/ref names passed to git argv.
+ * Rejects anything outside the ASCII subset `A-Z a-z 0-9 _ . / + -`,
+ * sequences git itself rejects (`..`, `@{`, leading `-`, trailing `.lock`/`/`),
+ * and pathological tokens.
+ */
+export function isSafeGitRefToken(s) {
+    const t = s.trim();
+    if (t.length === 0 || t.length > 256)
+        return false;
+    if (t.startsWith("-"))
+        return false;
+    if (t.endsWith("/") || t.endsWith(".lock") || t.endsWith("."))
+        return false;
+    if (t.includes(".."))
+        return false;
+    if (t.includes("@{"))
+        return false;
+    if (t.includes("//"))
+        return false;
+    return /^[A-Za-z0-9_./+-]+$/.test(t);
+}
+/**
+ * Same as `isSafeGitRefToken` but also allows `~N` / `^N` ancestor notation used
+ * by `git reset --soft HEAD~3`. Permits `~` and `^` suffix characters.
+ */
+export function isSafeGitAncestorRef(s) {
+    const t = s.trim();
+    if (t.length === 0 || t.length > 256)
+        return false;
+    if (t.startsWith("-"))
+        return false;
+    return /^[A-Za-z0-9_./+~^-]+$/.test(t);
+}
+/**
+ * Same as `isSafeGitRefToken` but also allows the `A..B` / `A...B` range forms
+ * used by `git log` / `git cherry-pick`. Splits once and validates each side.
+ */
+export function isSafeGitRangeToken(s) {
+    const t = s.trim();
+    if (t.includes("...")) {
+        const parts = t.split("...");
+        return parts.length === 2 && parts.every((p) => isSafeGitRefToken(p));
+    }
+    if (t.includes("..")) {
+        const parts = t.split("..");
+        return parts.length === 2 && parts.every((p) => isSafeGitRefToken(p));
+    }
+    return isSafeGitRefToken(t);
+}
+// ---------------------------------------------------------------------------
+// Async helpers
+// ---------------------------------------------------------------------------
+/** Current branch name; `null` if detached HEAD. */
+export async function getCurrentBranch(cwd) {
+    const r = await spawnGitAsync(cwd, ["symbolic-ref", "--short", "-q", "HEAD"]);
+    if (!r.ok)
+        return null;
+    const name = r.stdout.trim();
+    return name === "" ? null : name;
+}
+/** Resolve a ref to its full SHA; `null` if unknown. */
+export async function resolveRef(cwd, ref) {
+    if (!isSafeGitRefToken(ref))
+        return null;
+    const r = await spawnGitAsync(cwd, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]);
+    if (!r.ok)
+        return null;
+    const sha = r.stdout.trim();
+    return sha === "" ? null : sha;
+}
+/** Working tree clean (no staged, no unstaged, no untracked). */
+export async function isWorkingTreeClean(cwd) {
+    const r = await spawnGitAsync(cwd, ["status", "--porcelain"]);
+    if (!r.ok)
+        return false;
+    return r.stdout.trim() === "";
+}
+/** True when every commit on `branch` is reachable from `target`. */
+export async function isFullyMergedInto(cwd, branch, target) {
+    if (!isSafeGitRefToken(branch) || !isSafeGitRefToken(target))
+        return false;
+    const r = await spawnGitAsync(cwd, ["merge-base", "--is-ancestor", branch, target]);
+    return r.ok;
+}
+/**
+ * SHAs of commits in `exclude..include`, oldest-first (cherry-pick feed order).
+ * Returns `null` on git failure.
+ */
+export async function commitListBetween(cwd, excludeRef, includeRef) {
+    if (!isSafeGitRefToken(excludeRef) || !isSafeGitRefToken(includeRef))
+        return null;
+    const r = await spawnGitAsync(cwd, ["rev-list", "--reverse", `${excludeRef}..${includeRef}`]);
+    if (!r.ok)
+        return null;
+    return r.stdout
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0);
+}
+/** Parse `git worktree list --porcelain` into structured entries. */
+export async function listWorktrees(cwd) {
+    const r = await spawnGitAsync(cwd, ["worktree", "list", "--porcelain"]);
+    if (!r.ok)
+        return [];
+    const out = [];
+    let cur = {};
+    for (const line of r.stdout.split("\n")) {
+        if (line.startsWith("worktree ")) {
+            if (cur.path)
+                out.push({ path: cur.path, branch: cur.branch ?? null, head: cur.head ?? null });
+            cur = { path: line.slice("worktree ".length).trim() };
+        }
+        else if (line.startsWith("HEAD ")) {
+            cur.head = line.slice("HEAD ".length).trim();
+        }
+        else if (line.startsWith("branch ")) {
+            // e.g. `branch refs/heads/foo`
+            const ref = line.slice("branch ".length).trim();
+            cur.branch = ref.startsWith("refs/heads/") ? ref.slice("refs/heads/".length) : ref;
+        }
+        else if (line === "detached") {
+            cur.branch = null;
+        }
+    }
+    if (cur.path)
+        out.push({ path: cur.path, branch: cur.branch ?? null, head: cur.head ?? null });
+    return out;
+}
+/** Path of the worktree currently checked out on `branch`; `null` if none. */
+export async function worktreeForBranch(cwd, branch) {
+    const trees = await listWorktrees(cwd);
+    const hit = trees.find((t) => t.branch === branch);
+    return hit?.path ?? null;
+}
+// ---------------------------------------------------------------------------
+// Push helpers
+// ---------------------------------------------------------------------------
+/**
+ * Probe `@{u}` and extract the remote name from the tracking ref.
+ * Returns an error payload when no upstream is configured.
+ */
+export async function inferRemoteFromUpstream(cwd) {
+    const r = await spawnGitAsync(cwd, ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"]);
+    if (!r.ok)
+        return { ok: false, detail: (r.stderr || r.stdout).trim() };
+    const upstream = r.stdout.trim();
+    const slash = upstream.indexOf("/");
+    const remote = slash > 0 ? upstream.slice(0, slash) : "origin";
+    return { ok: true, remote, upstream };
+}

package/dist/server/git-reset-soft-tool.js

@@ -0,0 +1,82 @@
+import { z } from "zod";
+import { spawnGitAsync } from "./git.js";
+import { isSafeGitAncestorRef, isWorkingTreeClean } from "./git-refs.js";
+import { jsonRespond, spreadDefined } from "./json.js";
+import { requireSingleRepo } from "./roots.js";
+import { WorkspacePickSchema } from "./schemas.js";
+export function registerGitResetSoftTool(server) {
+    server.addTool({
+        name: "git_reset_soft",
+        description: "Soft-reset the current branch to a reference (`git reset --soft <ref>`). " +
+            "Moves the branch pointer back while keeping all changes from the rewound commits " +
+            "in the staging index — use this to re-split an already-committed chunk. " +
+            "Refuses when the working tree has any uncommitted or unstaged changes (run on a clean tree).",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+        },
+        parameters: WorkspacePickSchema.extend({
+            ref: z
+                .string()
+                .min(1)
+                .describe("Commit to reset to. Accepts ancestor notation (`HEAD~1`, `HEAD~3`), " +
+                "branch names, or full SHAs."),
+        }),
+        execute: async (args) => {
+            const pre = requireSingleRepo(server, args);
+            if (!pre.ok)
+                return jsonRespond(pre.error);
+            const { gitTop } = pre;
+            // Validate ref — allow ancestor notation (~N, ^N).
+            if (!isSafeGitAncestorRef(args.ref)) {
+                return jsonRespond({ error: "unsafe_ref_token", ref: args.ref });
+            }
+            // Refuse when the working tree is dirty (unstaged or untracked changes).
+            if (!(await isWorkingTreeClean(gitTop))) {
+                return jsonRespond({
+                    error: "working_tree_dirty",
+                    detail: "git_reset_soft requires a clean working tree. " +
+                        "Commit or stash pending changes first.",
+                });
+            }
+            // Probe HEAD before reset for the response.
+            const preSha = await spawnGitAsync(gitTop, ["rev-parse", "HEAD"]);
+            const beforeSha = preSha.ok ? preSha.stdout.trim() : undefined;
+            // Run the reset.
+            const r = await spawnGitAsync(gitTop, ["reset", "--soft", args.ref]);
+            if (!r.ok) {
+                return jsonRespond({
+                    error: "reset_failed",
+                    detail: (r.stderr || r.stdout).trim(),
+                });
+            }
+            // Probe HEAD after reset.
+            const postSha = await spawnGitAsync(gitTop, ["rev-parse", "HEAD"]);
+            const afterSha = postSha.ok ? postSha.stdout.trim() : undefined;
+            // Count staged changes after reset.
+            const stagedResult = await spawnGitAsync(gitTop, ["diff", "--cached", "--name-only"]);
+            const stagedFiles = stagedResult.ok
+                ? stagedResult.stdout
+                    .split("\n")
+                    .map((l) => l.trim())
+                    .filter((l) => l.length > 0)
+                : [];
+            if (args.format === "json") {
+                return jsonRespond({
+                    ok: true,
+                    ref: args.ref,
+                    ...spreadDefined("beforeSha", beforeSha),
+                    ...spreadDefined("afterSha", afterSha),
+                    stagedCount: stagedFiles.length,
+                });
+            }
+            const beforeShort = beforeSha?.slice(0, 7) ?? "?";
+            const afterShort = afterSha?.slice(0, 7) ?? "?";
+            return [
+                "# Reset (soft)",
+                `✓ ${beforeShort} → ${afterShort}  (${stagedFiles.length} file(s) staged)`,
+            ].join("\n");
+        },
+    });
+}

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

@@ -8,7 +8,10 @@ import { WorkspacePickSchema } from "./schemas.js";
 export function registerGitStatusTool(server) {
     server.addTool({
         name: "git_status",
-        description: "Read-only `git status --short -b` per root + submodules. See docs/mcp-tools.md.",
+        description: "Read-only `git status --short -b` per root + submodules.",
+        annotations: {
+            readOnlyHint: true,
+        },
         parameters: WorkspacePickSchema.extend({
             includeSubmodules: z.boolean().optional().default(true),
         }),

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

@@ -0,0 +1,188 @@
+import { resolve } from "node:path";
+import { z } from "zod";
+import { spawnGitAsync } from "./git.js";
+import { isProtectedBranch, isSafeGitRefToken, listWorktrees, } from "./git-refs.js";
+import { jsonRespond, spreadDefined, spreadWhen } from "./json.js";
+import { requireSingleRepo } from "./roots.js";
+import { WorkspacePickSchema } from "./schemas.js";
+// ---------------------------------------------------------------------------
+// git_worktree_list
+// ---------------------------------------------------------------------------
+export function registerGitWorktreeListTool(server) {
+    server.addTool({
+        name: "git_worktree_list",
+        description: "List all git worktrees for the repository (`git worktree list --porcelain`).",
+        annotations: {
+            readOnlyHint: true,
+        },
+        parameters: WorkspacePickSchema.pick({
+            workspaceRoot: true,
+            rootIndex: true,
+            format: true,
+        }),
+        execute: async (args) => {
+            const pre = requireSingleRepo(server, args);
+            if (!pre.ok)
+                return jsonRespond(pre.error);
+            const { gitTop } = pre;
+            const trees = await listWorktrees(gitTop);
+            if (args.format === "json") {
+                return jsonRespond({ worktrees: trees });
+            }
+            if (trees.length === 0) {
+                return "# Worktrees\n_(none)_";
+            }
+            const lines = ["# Worktrees", ""];
+            for (const t of trees) {
+                const branchPart = t.branch ?? "(detached)";
+                const headPart = t.head ? ` @ ${t.head.slice(0, 7)}` : "";
+                lines.push(`- \`${t.path}\`  ${branchPart}${headPart}`);
+            }
+            return lines.join("\n");
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// git_worktree_add
+// ---------------------------------------------------------------------------
+export function registerGitWorktreeAddTool(server) {
+    server.addTool({
+        name: "git_worktree_add",
+        description: "Add a new git worktree. If `branch` does not exist it is created from `baseRef` " +
+            "(defaults to HEAD). Refuses to create on a protected branch name.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+        },
+        parameters: WorkspacePickSchema.extend({
+            path: z
+                .string()
+                .min(1)
+                .describe("Filesystem path for the new worktree. Relative paths are resolved from the git toplevel."),
+            branch: z
+                .string()
+                .min(1)
+                .describe("Branch to check out in the new worktree. Created from `baseRef` if absent."),
+            baseRef: z
+                .string()
+                .optional()
+                .describe("Commit-ish to base the new branch on when it does not yet exist. Default: HEAD."),
+        }),
+        execute: async (args) => {
+            const pre = requireSingleRepo(server, args);
+            if (!pre.ok)
+                return jsonRespond(pre.error);
+            const { gitTop } = pre;
+            // Validate branch
+            if (!isSafeGitRefToken(args.branch)) {
+                return jsonRespond({ error: "unsafe_ref_token", ref: args.branch });
+            }
+            if (isProtectedBranch(args.branch)) {
+                return jsonRespond({ error: "protected_branch", branch: args.branch });
+            }
+            if (args.baseRef !== undefined && !isSafeGitRefToken(args.baseRef)) {
+                return jsonRespond({ error: "unsafe_ref_token", ref: args.baseRef });
+            }
+            // Resolve path
+            const wtPath = resolve(gitTop, args.path);
+            // Check if branch already exists
+            const branchCheck = await spawnGitAsync(gitTop, [
+                "show-ref",
+                "--verify",
+                "--quiet",
+                `refs/heads/${args.branch}`,
+            ]);
+            const branchExists = branchCheck.ok;
+            let gitArgs;
+            if (branchExists) {
+                gitArgs = ["worktree", "add", wtPath, args.branch];
+            }
+            else {
+                gitArgs = ["worktree", "add", "-b", args.branch, wtPath];
+                if (args.baseRef)
+                    gitArgs.push(args.baseRef);
+            }
+            const r = await spawnGitAsync(gitTop, gitArgs);
+            if (!r.ok) {
+                return jsonRespond({
+                    ok: false,
+                    error: "worktree_add_failed",
+                    detail: (r.stderr || r.stdout).trim(),
+                });
+            }
+            if (args.format === "json") {
+                return jsonRespond({
+                    ok: true,
+                    path: wtPath,
+                    branch: args.branch,
+                    created: !branchExists,
+                    ...spreadDefined("baseRef", !branchExists ? (args.baseRef ?? "HEAD") : undefined),
+                });
+            }
+            const createdNote = branchExists ? "" : ` (new branch from ${args.baseRef ?? "HEAD"})`;
+            return `# Worktree added\n✓ ${wtPath}  →  ${args.branch}${createdNote}`;
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// git_worktree_remove
+// ---------------------------------------------------------------------------
+export function registerGitWorktreeRemoveTool(server) {
+    server.addTool({
+        name: "git_worktree_remove",
+        description: "Remove a git worktree (`git worktree remove`). " +
+            "Pass `force: true` to remove a worktree with uncommitted changes. " +
+            "Refuses to remove the main worktree.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+        },
+        parameters: WorkspacePickSchema.extend({
+            path: z
+                .string()
+                .min(1)
+                .describe("Path of the worktree to remove. Must not be the main worktree."),
+            force: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("Pass `--force` to allow removal of worktrees with uncommitted changes."),
+        }),
+        execute: async (args) => {
+            const pre = requireSingleRepo(server, args);
+            if (!pre.ok)
+                return jsonRespond(pre.error);
+            const { gitTop } = pre;
+            // Refuse to remove the main worktree
+            const wtPath = resolve(gitTop, args.path);
+            if (wtPath === gitTop) {
+                return jsonRespond({ error: "cannot_remove_main_worktree", path: wtPath });
+            }
+            // Verify it exists in the worktree list
+            const trees = await listWorktrees(gitTop);
+            const isRegistered = trees.some((t) => t.path === wtPath || t.path === args.path);
+            if (!isRegistered) {
+                return jsonRespond({ error: "worktree_not_found", path: args.path });
+            }
+            const removeArgs = ["worktree", "remove", wtPath];
+            if (args.force)
+                removeArgs.push("--force");
+            const r = await spawnGitAsync(gitTop, removeArgs);
+            if (!r.ok) {
+                return jsonRespond({
+                    ok: false,
+                    error: "worktree_remove_failed",
+                    detail: (r.stderr || r.stdout).trim(),
+                    ...spreadWhen((r.stderr || r.stdout).includes("contains modified") ||
+                        (r.stderr || r.stdout).includes("is not empty"), { hint: "Pass force: true to remove a worktree with uncommitted changes." }),
+                });
+            }
+            if (args.format === "json") {
+                return jsonRespond({ ok: true, path: wtPath });
+            }
+            return `# Worktree removed\n✓ ${wtPath}`;
+        },
+    });
+}

package/dist/server/list-presets-tool.js

@@ -7,7 +7,10 @@ import { WorkspacePickSchema } from "./schemas.js";
 export function registerListPresetsTool(server) {
     server.addTool({
         name: "list_presets",
-        description: "List presets from .rethunk/git-mcp-presets.json. See docs/mcp-tools.md.",
+        description: "List presets from .rethunk/git-mcp-presets.json.",
+        annotations: {
+            readOnlyHint: true,
+        },
         parameters: WorkspacePickSchema.pick({
             workspaceRoot: true,
             rootIndex: true,

package/dist/server/roots.js

@@ -118,3 +118,20 @@ export function requireGitAndRoots(server, args, presetName) {
     }
     return { ok: true, roots: rootsRes.roots };
 }
+/**
+ * Convenience wrapper for single-repo tools: gate git, resolve roots, pick the first
+ * root, and resolve its git toplevel. Returns `{ ok: true, gitTop }` or a structured
+ * error payload ready for `jsonRespond`.
+ */
+export function requireSingleRepo(server, args, presetName = undefined) {
+    const pre = requireGitAndRoots(server, args, presetName);
+    if (!pre.ok)
+        return pre;
+    const rootInput = pre.roots[0];
+    if (!rootInput)
+        return { ok: false, error: { error: "no_workspace_root" } };
+    const top = gitTopLevel(rootInput);
+    if (!top)
+        return { ok: false, error: { error: "not_a_git_repository", path: rootInput } };
+    return { ok: true, gitTop: top };
+}

package/dist/server/schemas.js

@@ -3,8 +3,17 @@ import { MAX_INVENTORY_ROOTS_DEFAULT } from "./inventory.js";
 const FormatSchema = z.enum(["markdown", "json"]).optional().default("markdown");
 export const WorkspacePickSchema = z.object({
     workspaceRoot: z.string().optional().describe("Highest-priority override."),
-    rootIndex: z.number().int().min(0).optional(),
-    allWorkspaceRoots: z.boolean().optional().default(false),
+    rootIndex: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe("0-based index into the MCP file roots list; ignored when workspaceRoot is set."),
+    allWorkspaceRoots: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("Fan out across all MCP file roots."),
     format: FormatSchema,
 });
 export { MAX_INVENTORY_ROOTS_DEFAULT };

package/dist/server/test-harness.js

@@ -16,6 +16,9 @@
  *   const result = await tool({ workspaceRoot: dir, commits: [...] });
  *   // result is string (markdown) or JSON-parseable string
  */
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 // Stub context — no tool currently uses context
 const STUB_CONTEXT = {
     log: {
@@ -28,6 +31,30 @@ const STUB_CONTEXT = {
     session: undefined,
 };
 // ---------------------------------------------------------------------------
+// Tmp-dir lifecycle — prevents accumulating thousands of leaked test dirs.
+// Each test file must register the hook itself:
+//   afterEach(cleanupTmpPaths);
+// Module-scope afterEach(...) would only register once (first-importer wins)
+// because the module is cached across test files in the same bun test run.
+// ---------------------------------------------------------------------------
+const tmpPaths = [];
+export function mkTmpDir(prefix) {
+    const dir = mkdtempSync(join(tmpdir(), prefix));
+    tmpPaths.push(dir);
+    return dir;
+}
+export function trackTmpPath(path) {
+    tmpPaths.push(path);
+    return path;
+}
+export function cleanupTmpPaths() {
+    while (tmpPaths.length > 0) {
+        const p = tmpPaths.pop();
+        if (p)
+            rmSync(p, { recursive: true, force: true });
+    }
+}
+// ---------------------------------------------------------------------------
 // Fake server
 // ---------------------------------------------------------------------------
 function makeFakeServer() {

package/dist/server/tools.js

@@ -1,18 +1,33 @@
 import { registerBatchCommitTool } from "./batch-commit-tool.js";
+import { registerGitCherryPickTool } from "./git-cherry-pick-tool.js";
 import { registerGitDiffSummaryTool } from "./git-diff-summary-tool.js";
 import { registerGitInventoryTool } from "./git-inventory-tool.js";
 import { registerGitLogTool } from "./git-log-tool.js";
+import { registerGitMergeTool } from "./git-merge-tool.js";
 import { registerGitParityTool } from "./git-parity-tool.js";
+import { registerGitPushTool } from "./git-push-tool.js";
+import { registerGitResetSoftTool } from "./git-reset-soft-tool.js";
 import { registerGitStatusTool } from "./git-status-tool.js";
+import { registerGitWorktreeAddTool, registerGitWorktreeListTool, registerGitWorktreeRemoveTool, } from "./git-worktree-tool.js";
 import { registerListPresetsTool } from "./list-presets-tool.js";
 import { registerPresetsResource } from "./presets-resource.js";
 export function registerRethunkGitTools(server) {
+    // Read-only tools
     registerGitStatusTool(server);
     registerGitInventoryTool(server);
     registerGitParityTool(server);
     registerListPresetsTool(server);
-    registerBatchCommitTool(server);
-    registerGitDiffSummaryTool(server);
     registerGitLogTool(server);
+    registerGitDiffSummaryTool(server);
+    registerGitWorktreeListTool(server);
+    // Mutating tools
+    registerBatchCommitTool(server);
+    registerGitPushTool(server);
+    registerGitMergeTool(server);
+    registerGitCherryPickTool(server);
+    registerGitResetSoftTool(server);
+    registerGitWorktreeAddTool(server);
+    registerGitWorktreeRemoveTool(server);
+    // Resources
     registerPresetsResource(server);
 }