@rethunk/mcp-multi-root-git 2.6.0 → 2.8.1

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

@@ -1,5 +1,6 @@
 import { basename } from "node:path";
 import { z } from "zod";
+import { ERROR_CODES } from "./error-codes.js";
 import { asyncPool, GIT_SUBPROCESS_PARALLELISM, gitTopLevel, spawnGitAsync } from "./git.js";
 import { isSafeGitAncestorRef } from "./git-refs.js";
 import { jsonRespond, spreadDefined, spreadWhen } from "./json.js";
@@ -82,7 +83,7 @@ async function runGitLog(opts) {
     const r = await spawnGitAsync(top, logArgs);
     if (!r.ok) {
         return {
-            error: "git_log_failed",
+            error: ERROR_CODES.GIT_LOG_FAILED,
             path: top,
         };
     }
@@ -175,8 +176,7 @@ function renderLogMarkdown(group, filterSummary) {
 export function registerGitLogTool(server) {
     server.addTool({
         name: "git_log",
-        description: "Path-filtered, time-windowed read-only `git log` across one or more workspace roots. " +
-            "Returns structured commit history with author, date, subject, and optional diff stats.",
+        description: "Read-only `git log` across one or more roots. Returns author, date, subject, optional diff stats.",
         annotations: {
             readOnlyHint: true,
         },
@@ -185,26 +185,21 @@ export function registerGitLogTool(server) {
                 .enum(["markdown", "json", "oneline"])
                 .optional()
                 .default("markdown")
-                .describe("`markdown` (default): headed sections per root. " +
-                "`json`: structured groups array. " +
-                "`oneline`: `<sha7> <subject>` per line, no headers (single-root) or `### repo (branch)` separator per group (multi-root). Lowest-token option for post-commit verification."),
+                .describe("`markdown` (default): headed sections per root. `json`: groups array. " +
+                "`oneline`: `<sha7> <subject>` per line; lowest-token option for post-commit verification."),
             since: z
                 .string()
                 .optional()
-                .describe("Passed to `git log --since=`. Accepts ISO timestamps or git relative forms like " +
-                "`48.hours` or `2.weeks.ago`. Default: `7.days`."),
+                .describe("Passed to `--since=`. ISO timestamp or git relative form (`48.hours`, `2.weeks.ago`). Default: `7.days`."),
             paths: z
                 .array(z.string())
                 .optional()
-                .describe("Limit to commits touching these paths (passed as `-- <paths>`)."),
+                .describe("Limit to commits touching these paths (`-- <paths>`)."),
             grep: z
                 .string()
                 .optional()
-                .describe("Filter commits whose message matches this regex (git `--grep`, case-insensitive)."),
-            author: z
-                .string()
-                .optional()
-                .describe("Filter by author name or email (passed as `--author=`)."),
+                .describe("Filter by commit message regex (git `--grep`, case-insensitive)."),
+            author: z.string().optional().describe("Filter by author name or email (`--author=`)."),
             maxCommits: z
                 .number()
                 .int()
@@ -212,7 +207,7 @@ export function registerGitLogTool(server) {
                 .max(MAX_COMMITS_HARD_CAP)
                 .optional()
                 .default(DEFAULT_MAX_COMMITS)
-                .describe(`Maximum commits to return per root (hard cap ${MAX_COMMITS_HARD_CAP}). Default ${DEFAULT_MAX_COMMITS}.`),
+                .describe(`Max commits per root (hard cap ${MAX_COMMITS_HARD_CAP}, default ${DEFAULT_MAX_COMMITS}).`),
             branch: z.string().optional().describe("Ref/branch to log from. Default: HEAD."),
         }),
         execute: async (args) => {
@@ -222,19 +217,19 @@ export function registerGitLogTool(server) {
             // Validate `since` — reject obvious injection attempts (newlines, semicolons, shell chars).
             const rawSince = (args.since?.trim() ?? DEFAULT_SINCE) || DEFAULT_SINCE;
             if (/[\n\r;|&`$<>]/.test(rawSince)) {
-                return jsonRespond({ error: "invalid_since", since: rawSince });
+                return jsonRespond({ error: ERROR_CODES.INVALID_SINCE, since: rawSince });
             }
             // Validate paths — reject anything with null bytes or shell meta.
             // Use charCodeAt(0) === 0 for the null byte to avoid a biome lint on control chars in regex.
             const rawPaths = args.paths ?? [];
             for (const p of rawPaths) {
                 if (p.split("").some((c) => c.charCodeAt(0) === 0) || /[\n\r;|&`$<>]/.test(p)) {
-                    return jsonRespond({ error: "invalid_paths", path: p });
+                    return jsonRespond({ error: ERROR_CODES.INVALID_PATHS, path: p });
                 }
             }
             // Validate branch — reject leading-dash and other injection attempts.
             if (args.branch && !isSafeGitAncestorRef(args.branch)) {
-                return jsonRespond({ error: "unsafe_ref_token", branch: args.branch });
+                return jsonRespond({ error: ERROR_CODES.UNSAFE_REF_TOKEN, branch: args.branch });
             }
             const maxCommits = Math.min(args.maxCommits ?? DEFAULT_MAX_COMMITS, MAX_COMMITS_HARD_CAP);
             // Fan out across roots.
@@ -242,7 +237,11 @@ export function registerGitLogTool(server) {
             const results = await asyncPool(jobs, GIT_SUBPROCESS_PARALLELISM, async ({ rootInput }) => {
                 const top = gitTopLevel(rootInput);
                 if (!top) {
-                    return { _error: true, workspaceRoot: rootInput, error: "not_a_git_repository" };
+                    return {
+                        _error: true,
+                        workspaceRoot: rootInput,
+                        error: ERROR_CODES.NOT_A_GIT_REPOSITORY,
+                    };
                 }
                 const r = await runGitLog({
                     top,

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

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { ERROR_CODES } from "./error-codes.js";
 import { spawnGitAsync } from "./git.js";
 import { conflictPaths, getCurrentBranch, isFullyMergedInto, isProtectedBranch, isSafeGitRefToken, isWorkingTreeClean, resolveRef, worktreeForBranch, } from "./git-refs.js";
 import { jsonRespond, spreadDefined, spreadWhen } from "./json.js";
@@ -36,17 +37,17 @@ async function mergeOneSource(gitTop, into, source, strategy, mergeMessage) {
     const intoSha = await resolveRef(gitTop, into);
     const sourceSha = await resolveRef(gitTop, source);
     if (!sourceSha) {
-        return { source, ok: false, error: "source_not_found" };
+        return { source, ok: false, error: ERROR_CODES.SOURCE_NOT_FOUND };
     }
     if (!intoSha) {
-        return { source, ok: false, error: "destination_not_found" };
+        return { source, ok: false, error: ERROR_CODES.DESTINATION_NOT_FOUND };
     }
     const mb = await spawnGitAsync(gitTop, ["merge-base", into, source]);
     if (!mb.ok) {
         return {
             source,
             ok: false,
-            error: "merge_base_failed",
+            error: ERROR_CODES.MERGE_BASE_FAILED,
             detail: (mb.stderr || mb.stdout).trim(),
         };
     }
@@ -63,7 +64,7 @@ async function mergeOneSource(gitTop, into, source, strategy, mergeMessage) {
             return {
                 source,
                 ok: false,
-                error: "cannot_fast_forward",
+                error: ERROR_CODES.CANNOT_FAST_FORWARD,
                 detail: "destination and source have diverged; retry with strategy: rebase, merge, or auto",
             };
         }
@@ -102,7 +103,7 @@ async function fastForward(gitTop, source) {
             outcome: "conflicts",
             conflictStage: "merge",
             conflictPaths: [],
-            error: "merge_failed",
+            error: ERROR_CODES.MERGE_FAILED,
             detail: (r.stderr || r.stdout).trim(),
         };
     }
@@ -126,7 +127,7 @@ async function mergeCommit(gitTop, source, message, into) {
             outcome: "conflicts",
             conflictStage: "merge",
             conflictPaths: paths,
-            error: "merge_conflicts",
+            error: ERROR_CODES.MERGE_CONFLICTS,
             detail: (r.stderr || r.stdout).trim(),
         };
     }
@@ -156,7 +157,7 @@ async function rebaseSourceOntoInto(gitTop, into, source) {
             outcome: "conflicts",
             conflictStage: "rebase",
             conflictPaths: paths,
-            error: "rebase_conflicts",
+            error: ERROR_CODES.REBASE_CONFLICTS,
             detail: (r.stderr || r.stdout).trim(),
         };
     }
@@ -166,7 +167,7 @@ async function rebaseSourceOntoInto(gitTop, into, source) {
         return {
             source,
             ok: false,
-            error: "checkout_failed",
+            error: ERROR_CODES.CHECKOUT_FAILED,
             detail: (co.stderr || co.stdout).trim(),
         };
     }
@@ -206,12 +207,10 @@ async function maybeDeleteBranch(gitTop, source, enabled, into) {
 export function registerGitMergeTool(server) {
     server.addTool({
         name: "git_merge",
-        description: "Merge one or more source branches into a destination. Default strategy `auto` " +
-            "cascades fast-forward → rebase → merge-commit per source, preferring linear history. " +
-            "Refuses if the working tree is dirty. Stops on the first conflict and reports " +
-            "the affected paths. Optional flags auto-delete merged branches and worktrees, " +
-            "skipping protected names (main, master, dev, develop, stable, trunk, prod, " +
-            "production, release/*, hotfix/*).",
+        description: "Merge one or more source branches into a destination. `auto` cascades " +
+            "fast-forward → rebase → merge-commit, preferring linear history. " +
+            "Refuses on dirty tree; stops on first conflict. Optional flags delete merged branches/worktrees " +
+            "(protected names skipped: main, master, dev, develop, stable, trunk, prod, production, release/*, hotfix/*).",
         annotations: {
             readOnlyHint: false,
             destructiveHint: false,
@@ -236,14 +235,12 @@ export function registerGitMergeTool(server) {
                 .boolean()
                 .optional()
                 .default(false)
-                .describe("After all sources merge cleanly, delete each source branch locally (`git branch -d`). " +
-                "Protected names always skipped. Never affects remote branches."),
+                .describe("Delete each source branch locally after clean merge (`git branch -d`). Protected names and remote refs unaffected."),
             deleteMergedWorktrees: z
                 .boolean()
                 .optional()
                 .default(false)
-                .describe("After all sources merge cleanly, remove any local worktree currently checked out " +
-                "on a source branch (`git worktree remove`). Protected tails always skipped."),
+                .describe("Remove local worktrees on source branches after clean merge (`git worktree remove`). Protected tails skipped."),
         }),
         execute: async (args) => {
             const pre = requireSingleRepo(server, args);
@@ -253,28 +250,28 @@ export function registerGitMergeTool(server) {
             // --- Validate ref tokens early ---
             for (const s of args.sources) {
                 if (!isSafeGitRefToken(s)) {
-                    return jsonRespond({ error: "unsafe_ref_token", ref: s });
+                    return jsonRespond({ error: ERROR_CODES.UNSAFE_REF_TOKEN, ref: s });
                 }
             }
             if (args.into !== undefined && !isSafeGitRefToken(args.into)) {
-                return jsonRespond({ error: "unsafe_ref_token", ref: args.into });
+                return jsonRespond({ error: ERROR_CODES.UNSAFE_REF_TOKEN, ref: args.into });
             }
             // --- Resolve destination ---
             const startBranch = await getCurrentBranch(gitTop);
             const into = args.into?.trim() || startBranch;
             if (!into) {
-                return jsonRespond({ error: "into_detached_head" });
+                return jsonRespond({ error: ERROR_CODES.INTO_DETACHED_HEAD });
             }
             // --- Refuse dirty tree ---
             if (!(await isWorkingTreeClean(gitTop))) {
-                return jsonRespond({ error: "working_tree_dirty" });
+                return jsonRespond({ error: ERROR_CODES.WORKING_TREE_DIRTY });
             }
             // --- Ensure destination is checked out ---
             if (into !== startBranch) {
                 const co = await spawnGitAsync(gitTop, ["checkout", into]);
                 if (!co.ok) {
                     return jsonRespond({
-                        error: "checkout_failed",
+                        error: ERROR_CODES.CHECKOUT_FAILED,
                         detail: (co.stderr || co.stdout).trim(),
                     });
                 }
@@ -282,7 +279,7 @@ export function registerGitMergeTool(server) {
             // Verify destination exists after checkout.
             const intoShaProbe = await resolveRef(gitTop, into);
             if (!intoShaProbe) {
-                return jsonRespond({ error: "destination_not_found", ref: into });
+                return jsonRespond({ error: ERROR_CODES.DESTINATION_NOT_FOUND, ref: into });
             }
             // --- Merge each source sequentially ---
             const strategy = args.strategy ?? "auto";

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

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { ERROR_CODES } from "./error-codes.js";
 import { gitRevParseHead, gitTopLevel } from "./git.js";
 import { validateRepoPath } from "./inventory.js";
 import { jsonRespond, spreadDefined } from "./json.js";
@@ -33,7 +34,7 @@ export function registerGitParityTool(server) {
             for (const workspaceRoot of pre.roots) {
                 const top = gitTopLevel(workspaceRoot);
                 if (!top) {
-                    const errPayload = { error: "not_a_git_repository", path: workspaceRoot };
+                    const errPayload = { error: ERROR_CODES.NOT_A_GIT_REPOSITORY, path: workspaceRoot };
                     const err = jsonRespond(errPayload);
                     if (args.format === "json") {
                         results.push({
@@ -58,7 +59,7 @@ export function registerGitParityTool(server) {
                     parityPresetSchemaVersion = applied.presetSchemaVersion;
                 }
                 if (!pairs?.length) {
-                    return jsonRespond({ error: "no_pairs" });
+                    return jsonRespond({ error: ERROR_CODES.NO_PAIRS });
                 }
                 let allOk = true;
                 const pairResults = [];

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

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { ERROR_CODES } from "./error-codes.js";
 import { isSafeGitUpstreamToken, spawnGitAsync } from "./git.js";
 import { getCurrentBranch, inferRemoteFromUpstream, isSafeGitRefToken } from "./git-refs.js";
 import { jsonRespond, spreadDefined } from "./json.js";
@@ -42,16 +43,19 @@ export function registerGitPushTool(server) {
             const currentBranch = await getCurrentBranch(gitTop);
             const branch = args.branch?.trim() || currentBranch;
             if (!branch) {
-                return jsonRespond({ error: "push_detached_head" });
+                return jsonRespond({ error: ERROR_CODES.PUSH_DETACHED_HEAD });
             }
             if (!isSafeGitRefToken(branch)) {
-                return jsonRespond({ error: "unsafe_ref_token", ref: branch });
+                return jsonRespond({ error: ERROR_CODES.UNSAFE_REF_TOKEN, ref: branch });
             }
             // --- Resolve remote ---
             let remote;
             if (args.remote?.trim()) {
                 if (!isSafeGitUpstreamToken(args.remote.trim())) {
-                    return jsonRespond({ error: "unsafe_remote_token", remote: args.remote.trim() });
+                    return jsonRespond({
+                        error: ERROR_CODES.UNSAFE_REMOTE_TOKEN,
+                        remote: args.remote.trim(),
+                    });
                 }
                 remote = args.remote.trim();
             }
@@ -64,7 +68,7 @@ export function registerGitPushTool(server) {
                 const t = await inferRemoteFromUpstream(gitTop);
                 if (!t.ok) {
                     return jsonRespond({
-                        error: "push_no_upstream",
+                        error: ERROR_CODES.PUSH_NO_UPSTREAM,
                         branch,
                         detail: t.detail,
                     });
@@ -82,7 +86,7 @@ export function registerGitPushTool(server) {
                     ok: false,
                     branch,
                     remote,
-                    error: "push_failed",
+                    error: ERROR_CODES.PUSH_FAILED,
                     detail: (pushResult.stderr || pushResult.stdout).trim(),
                 });
             }

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

@@ -0,0 +1,126 @@
+import { z } from "zod";
+import { ERROR_CODES } from "./error-codes.js";
+import { spawnGitAsync } from "./git.js";
+import { isSafeGitRefToken } from "./git-refs.js";
+import { jsonRespond } from "./json.js";
+import { requireSingleRepo } from "./roots.js";
+import { WorkspacePickSchema } from "./schemas.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const MAX_ENTRIES_HARD_CAP = 200;
+const DEFAULT_MAX_ENTRIES = 30;
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Run git reflog for a single ref and return structured data.
+ * Uses NUL-delimited fields within each line for robust parsing.
+ */
+async function runGitReflog(opts) {
+    const { top, ref, maxEntries } = opts;
+    // %h = short sha, %H = full sha, %gd = selector (HEAD@{0}), %gs = reflog subject
+    const reflogArgs = [
+        "reflog",
+        "show",
+        ref,
+        "--format=%h%x00%H%x00%gd%x00%gs",
+        `-n`,
+        String(maxEntries),
+    ];
+    const r = await spawnGitAsync(top, reflogArgs);
+    if (!r.ok) {
+        return {
+            error: ERROR_CODES.REFLOG_FAILED,
+            detail: (r.stderr || r.stdout || "git reflog failed").trim(),
+        };
+    }
+    const entries = [];
+    const lines = r.stdout.split("\n");
+    for (const line of lines) {
+        if (!line.trim())
+            continue;
+        const parts = line.split("\x00");
+        // Expect 4 fields: shaShort, shaFull, selector, message
+        if (parts.length < 4)
+            continue;
+        const [, shaFull, selector, message] = parts;
+        if (!shaFull)
+            continue;
+        entries.push({
+            sha: shaFull.trim(),
+            selector: (selector ?? "").trim(),
+            message: (message ?? "").trim(),
+        });
+    }
+    return { ref, entries };
+}
+// ---------------------------------------------------------------------------
+// Markdown rendering
+// ---------------------------------------------------------------------------
+function renderReflogMarkdown(result) {
+    const lines = [];
+    lines.push(`## Reflog (${result.ref})`);
+    lines.push("");
+    if (result.entries.length === 0) {
+        lines.push("_(no reflog entries)_");
+    }
+    else {
+        for (const entry of result.entries) {
+            lines.push(`${entry.selector}  ${entry.sha.slice(0, 7)}  ${entry.message}`);
+        }
+    }
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+export function registerGitReflogTool(server) {
+    server.addTool({
+        name: "git_reflog",
+        description: "Show the reflog for a ref (default HEAD). Returns a list of recent HEAD movements with selector (e.g. HEAD@{0}), full SHA, and message. Useful for recovering lost commits or inspecting reset/checkout history.",
+        annotations: {
+            readOnlyHint: true,
+        },
+        parameters: WorkspacePickSchema.omit({ absoluteGitRoots: true, allWorkspaceRoots: true })
+            .pick({
+            workspaceRoot: true,
+            rootIndex: true,
+            format: true,
+        })
+            .extend({
+            ref: z
+                .string()
+                .optional()
+                .default("HEAD")
+                .describe("Ref whose reflog to show (branch name, HEAD, etc.). Default: HEAD."),
+            maxEntries: z
+                .number()
+                .int()
+                .min(1)
+                .max(MAX_ENTRIES_HARD_CAP)
+                .optional()
+                .default(DEFAULT_MAX_ENTRIES)
+                .describe(`Maximum reflog entries to return (hard cap ${MAX_ENTRIES_HARD_CAP}). Default ${DEFAULT_MAX_ENTRIES}.`),
+        }),
+        execute: async (args) => {
+            const pre = requireSingleRepo(server, args);
+            if (!pre.ok)
+                return jsonRespond(pre.error);
+            const top = pre.gitTop;
+            const ref = args.ref ?? "HEAD";
+            if (!isSafeGitRefToken(ref)) {
+                return jsonRespond({ error: ERROR_CODES.UNSAFE_REF_TOKEN, ref });
+            }
+            const maxEntries = Math.min(args.maxEntries ?? DEFAULT_MAX_ENTRIES, MAX_ENTRIES_HARD_CAP);
+            const result = await runGitReflog({ top, ref, maxEntries });
+            if ("error" in result) {
+                return jsonRespond(result);
+            }
+            if (args.format === "json") {
+                return jsonRespond(result);
+            }
+            return renderReflogMarkdown(result);
+        },
+    });
+}

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

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { ERROR_CODES } from "./error-codes.js";
 import { spawnGitAsync } from "./git.js";
 import { isSafeGitAncestorRef, isWorkingTreeClean } from "./git-refs.js";
 import { jsonRespond, spreadDefined } from "./json.js";
@@ -7,10 +8,8 @@ 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).",
+        description: "`git reset --soft <ref>`: moves HEAD back while keeping rewound changes staged. " +
+            "Use to re-split committed work. Refuses on a dirty tree.",
         annotations: {
             readOnlyHint: false,
             destructiveHint: false,
@@ -20,8 +19,7 @@ export function registerGitResetSoftTool(server) {
             ref: z
                 .string()
                 .min(1)
-                .describe("Commit to reset to. Accepts ancestor notation (`HEAD~1`, `HEAD~3`), " +
-                "branch names, or full SHAs."),
+                .describe("Commit to reset to: ancestor notation (`HEAD~1`, `HEAD~3`), branch name, or SHA."),
         }),
         execute: async (args) => {
             const pre = requireSingleRepo(server, args);
@@ -30,12 +28,12 @@ export function registerGitResetSoftTool(server) {
             const { gitTop } = pre;
             // Validate ref — allow ancestor notation (~N, ^N).
             if (!isSafeGitAncestorRef(args.ref)) {
-                return jsonRespond({ error: "unsafe_ref_token", ref: args.ref });
+                return jsonRespond({ error: ERROR_CODES.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",
+                    error: ERROR_CODES.WORKING_TREE_DIRTY,
                     detail: "git_reset_soft requires a clean working tree. " +
                         "Commit or stash pending changes first.",
                 });
@@ -47,7 +45,7 @@ export function registerGitResetSoftTool(server) {
             const r = await spawnGitAsync(gitTop, ["reset", "--soft", args.ref]);
             if (!r.ok) {
                 return jsonRespond({
-                    error: "reset_failed",
+                    error: ERROR_CODES.RESET_FAILED,
                     detail: (r.stderr || r.stdout).trim(),
                 });
             }