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

package/AGENTS.md

@@ -17,7 +17,7 @@ IDEs injecting this as context: do not re-link from rules.
 |------|---------|
 | [`src/server.ts`](src/server.ts) | `FastMCP` + `roots: { enabled: true }`; `readMcpServerVersion()`; `registerRethunkGitTools` |
 | [`src/server/json.ts`](src/server/json.ts) | `jsonRespond()` (minified, no envelope), `spreadWhen`, `spreadDefined` |
-| [`src/server/git.ts`](src/server/git.ts) | `gateGit`, `spawnGitAsync`, `asyncPool`, `GIT_SUBPROCESS_PARALLELISM`, `gitTopLevel`, `gitRevParseGitDir`, `gitRevParseHead`, `parseGitSubmodulePaths`, `hasGitMetadata`, `gitStatusSnapshotAsync`, `gitStatusShortBranchAsync`, `fetchAheadBehind`, `isSafeGitUpstreamToken` |
+| [`src/server/git.ts`](src/server/git.ts) | `gateGit`, `spawnGitAsync` (optional `{ timeoutMs, signal }`), `asyncPool`, `GIT_SUBPROCESS_PARALLELISM`, `GIT_SUBPROCESS_TIMEOUT_MS`, `gitTopLevel`, `gitRevParseGitDir`, `gitRevParseHead`, `parseGitSubmodulePaths`, `hasGitMetadata`, `gitStatusSnapshotAsync`, `gitStatusShortBranchAsync`, `fetchAheadBehind`, `isSafeGitUpstreamToken` |
 | [`src/server/roots.ts`](src/server/roots.ts) | `requireGitAndRoots`, `requireSingleRepo`, `resolveAbsoluteGitRootsList`, `GitRootPickArgs` — shared tool preludes; session root resolution; optional `absoluteGitRoots` bulk pick |
 | [`src/server/presets.ts`](src/server/presets.ts) | `PRESET_FILE_PATH`, `loadPresetsFromGitTop`, `presetLoadErrorPayload`, `applyPresetNestedRoots`, `applyPresetParityPairs`; Zod schemas must match [`git-mcp-presets.schema.json`](git-mcp-presets.schema.json) |
 | [`src/server/schemas.ts`](src/server/schemas.ts) | `WorkspacePickSchema`, `MAX_INVENTORY_ROOTS_DEFAULT`, **`MAX_ABSOLUTE_GIT_ROOTS`** (256), optional **`absoluteGitRoots`** on workspace pick |
@@ -54,7 +54,7 @@ IDEs injecting this as context: do not re-link from rules.
 
 ## Validate + CI
 
-Local: `bun run build` | `bun run check` | `bun run schema:tools:check` | `bun run test`. CI ([`ci.yml`](.github/workflows/ci.yml)) runs same on PRs + `main` after `bun install --frozen-lockfile`, then `bun run test:coverage` + `bun run coverage:check`, and uploads prerelease `npm pack` artifact. Tag `v*.*.*` matching `package.json` version → [`release.yml`](.github/workflows/release.yml) publishes to GitHub Packages as `@rethunk-ai/mcp-multi-root-git` + cuts GitHub Release. npmjs publish is manual (see [HUMANS.md](HUMANS.md)).
+Local: `bun run build` | `bun run lint` | `bun run schema:tools:check` | `bun run test`. CI ([`ci.yml`](.github/workflows/ci.yml)) runs same on PRs + `main` after `bun install --frozen-lockfile`, then `bun run test:coverage` + `bun run coverage:check`, and uploads prerelease `npm pack` artifact. Tag `v*.*.*` matching `package.json` version → [`release.yml`](.github/workflows/release.yml) publishes to GitHub Packages as `@rethunk-ai/mcp-multi-root-git` + cuts GitHub Release. npmjs publish is manual (see [HUMANS.md](HUMANS.md)).
 
 Optional [`.githooks/`](.githooks): `bun run setup-hooks` once per clone. pre-commit=`check`; pre-push=frozen install + build + check + test.
 

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to `@rethunk/mcp-multi-root-git` are documented here. Format loosely follows [Keep a Changelog](https://keepachangelog.com); the project uses [Semantic Versioning](https://semver.org).
 
+## [2.8.0] — 2026-05-29
+
+Feature release: three new read-only inspection tools (tool count 20 → 23). Additive — no JSON format-version bump.
+
+### Added
+
+- **`git_blame`** — line-by-line authorship for a file: commit SHA, author, ISO date, summary, and content per line. Blames at an optional `ref` and an optional `startLine`/`endLine` range (`-L`); path-confined like the other path tools (`path_escapes_repo`).
+- **`git_branch_list`** — list local branches with sha, current marker, and upstream; optional `includeRemotes` adds remote-tracking branches (symbolic `origin/HEAD` skipped). Returns `{ branches, remotes? }`.
+- **`git_reflog`** — show the reflog for a ref (default `HEAD`): recent HEAD movements with selector (`HEAD@{N}`), full SHA, and message; `maxEntries` cap (default 30, max 200).
+
+## [2.7.0] — 2026-05-29
+
+Feature release: deepens three read tools per recurring agent pain points (TODO.md) and hardens the git subprocess layer. All changes are additive — no JSON format-version bump.
+
+### Added
+
+- **`git_diff` — multi-path + context control** — new `paths: string[]` scopes the diff to multiple files (unioned with the legacy single `path`), and `unified: number` (0–100) sets the context-line width (`-U<n>`). Path confinement is now enforced on every path input, returning `path_escapes_repo` on escape.
+- **`git_show` — stat + multi-path modes** — new `stat: true` returns a `--stat` diffstat (commit message + per-file counts, no full patch), and `paths: string[]` filters the shown patch/stat to specific files, with the same path-confinement guarantees as single `path`.
+- **`git_fetch` — structured ref deltas** — emits `updated: [{ ref, oldSha, newSha, flag }]`, `created: [{ ref, newSha, flag }]`, and `pruned: [{ ref }]` parsed from `git fetch --porcelain` (git ≥ 2.41). On older git the option is detected as unsupported and the tool falls back to the legacy line parse; the string `updatedRefs` / `newRefs` fields are retained for back-compat in both modes.
+- **`GIT_SUBPROCESS_TIMEOUT_MS`** — `spawnGitAsync` now accepts an optional `{ timeoutMs, signal }` argument and applies a default timeout (120000 ms, configurable via the env var; `0` disables). A hung git operation against a dead remote no longer blocks the server indefinitely — the child is killed (SIGTERM) on expiry or `AbortSignal` abort, and the result resolves `ok: false` with `timedOut` / `aborted` flags. Existing callers are unchanged beyond gaining default timeout protection.
+
 ## [2.6.0] — 2026-05-22
 
 Security-hardening and correctness release surfaced by a full-repo critical review.

package/HUMANS.md

@@ -205,7 +205,7 @@ It verifies the `package.json` version has a matching `CHANGELOG.md` section, bo
 
 npmjs no longer fits an unattended CI publish flow for this org; **do not** rely on automation to [npmjs](https://www.npmjs.com/package/@rethunk/mcp-multi-root-git). To publish the **same** package name consumers already use (**`@rethunk/mcp-multi-root-git`**):
 
-1. On a clean checkout at the release commit (usually **`main`** after bumping version), run **`bun run prepublishOnly`** (or `bun run build && bun run check && bun run test`).
+1. On a clean checkout at the release commit (usually **`main`** after bumping version), run **`bun run prepublishOnly`** (or `bun run build && bun run lint && bun run test`).
 2. Log in to the public registry once per machine: **`npm login`** (or `npm adduser`) so **`npm whoami`** shows the account that owns **`@rethunk`** on npmjs.
 3. Ensure **`package.json`** still has **`"name": "@rethunk/mcp-multi-root-git"`** and **`publishConfig.access`** is **`"public"`** (no **`publishConfig.registry`** pointing at GitHub — leave default registry for npmjs).
 4. Publish: **`npm publish --access public`** (runs **`prepublishOnly`** again unless you pass **`--ignore-scripts`** after you already verified locally).

package/README.md

@@ -4,7 +4,7 @@
 [![npm version](https://img.shields.io/npm/v/%40rethunk%2Fmcp-multi-root-git.svg)](https://www.npmjs.com/package/@rethunk/mcp-multi-root-git)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-**git** tools over MCP: status, multi-root inventory, `HEAD` parity, presets, logs, structured and raw diff views, commit inspection, fetch, stash, tag, batch commit, push, merge, cherry-pick, worktrees, and soft-reset. **Install and MCP client wiring:** **[docs/install.md](docs/install.md)** only — do not duplicate those steps elsewhere.
+**git** tools over MCP: status, multi-root inventory, `HEAD` parity, presets, logs, structured and raw diff views, commit inspection, fetch, stash, tag, batch commit, push, merge, cherry-pick, worktrees, soft-reset, blame, branch listing, and reflog. **Install and MCP client wiring:** **[docs/install.md](docs/install.md)** only — do not duplicate those steps elsewhere.
 
 **Repository:** [github.com/Rethunk-AI/mcp-multi-root-git](https://github.com/Rethunk-AI/mcp-multi-root-git) · **npmjs (manual releases):** [`@rethunk/mcp-multi-root-git`](https://www.npmjs.com/package/@rethunk/mcp-multi-root-git) · **GitHub Packages (CI on each tag):** [`@rethunk-ai/mcp-multi-root-git`](https://github.com/Rethunk-AI/mcp-multi-root-git/packages) — see [docs/install.md](docs/install.md) and [HUMANS.md](HUMANS.md) Publishing.
 

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

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import { z } from "zod";
 import { isStrictlyUnderGitTop, resolvePathForRepo } from "../repo-paths.js";
+import { ERROR_CODES } from "./error-codes.js";
 import { spawnGitAsync } from "./git.js";
 import { getCurrentBranch, inferRemoteFromUpstream } from "./git-refs.js";
 import { jsonRespond, spreadDefined, spreadWhen } from "./json.js";
@@ -23,23 +24,20 @@ const CommitEntrySchema = z.object({
     files: z
         .array(FileEntrySchema)
         .min(1)
-        .describe("Paths to stage, relative to the git root. Each can be a string path or { path, lines } for hunk-level staging. " +
-        "Deleted files (missing on disk but tracked in HEAD) are staged as removals via `git rm --cached`. " +
-        "Combining { path, lines } with a deleted file is an error."),
+        .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."),
 });
 const PushModeSchema = z
     .enum(["never", "after"])
     .optional()
     .default("never")
-    .describe("`never` (default): no push. `after`: push the current branch to its upstream once all commits succeed; " +
-    "fails with `push_no_upstream` if the branch has no upstream (commits are NOT rolled back). " +
-    "Enum reserved for future modes such as `force-with-lease`.");
+    .describe("`never` (default): no push. `after`: push current branch to upstream after all commits succeed; " +
+    "fails with `push_no_upstream` if no upstream (commits are NOT rolled back).");
 const DryRunSchema = z
     .boolean()
     .optional()
     .default(false)
-    .describe("When true, stage files, collect preview (files staged, commit messages), return preview response without writing commits. " +
-    "Unstages any files that were staged for the preview. Response indicates DRY RUN mode.");
+    .describe("Stage files and return a preview without writing commits; unstages afterwards. Response is marked DRY RUN.");
 /**
  * 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.
@@ -192,11 +190,11 @@ async function stageFile(gitTop, filePath, lines) {
 export async function runPushAfter(gitTop) {
     const branch = await getCurrentBranch(gitTop);
     if (!branch) {
-        return { ok: false, error: "push_detached_head" };
+        return { ok: false, error: ERROR_CODES.PUSH_DETACHED_HEAD };
     }
     const t = await inferRemoteFromUpstream(gitTop);
     if (!t.ok) {
-        return { ok: false, branch, error: "push_no_upstream", detail: t.detail };
+        return { ok: false, branch, error: ERROR_CODES.PUSH_NO_UPSTREAM, detail: t.detail };
     }
     const pushResult = await spawnGitAsync(gitTop, ["push", t.remote, branch]);
     if (!pushResult.ok) {
@@ -204,7 +202,7 @@ export async function runPushAfter(gitTop) {
             ok: false,
             branch,
             upstream: t.upstream,
-            error: "push_failed",
+            error: ERROR_CODES.PUSH_FAILED,
             detail: (pushResult.stderr || pushResult.stdout).trim(),
         };
     }
@@ -219,11 +217,9 @@ export async function runPushAfter(gitTop) {
 export function registerBatchCommitTool(server) {
     server.addTool({
         name: "batch_commit",
-        description: "Create multiple sequential git commits in a single call. " +
-            "Each entry stages the listed files then commits with the given message. " +
-            'Stops on first failure. Optional `push: "after"` pushes the current branch ' +
-            "to its upstream once all commits succeed. " +
-            "Optional `dryRun: true` previews what would be staged/committed without writing commits.",
+        description: "Create multiple sequential git commits in one call. " +
+            "Each entry stages its files then commits. Stops on first failure. " +
+            'Optional `push: "after"` pushes after all commits succeed. `dryRun: true` previews without writing.',
         annotations: {
             readOnlyHint: false,
             destructiveHint: false,
@@ -234,7 +230,7 @@ export function registerBatchCommitTool(server) {
                 .array(CommitEntrySchema)
                 .min(1)
                 .max(50)
-                .describe("Commits to create, applied in order."),
+                .describe("Ordered list of commits to create."),
             push: PushModeSchema,
             dryRun: DryRunSchema,
         }),
@@ -288,7 +284,7 @@ export function registerBatchCommitTool(server) {
                         ok: false,
                         message: entry.message,
                         files: filePaths,
-                        error: "path_escapes_repository",
+                        error: ERROR_CODES.PATH_ESCAPES_REPOSITORY,
                         detail: escapedPaths.join(", "),
                     });
                     break;
@@ -310,7 +306,7 @@ export function registerBatchCommitTool(server) {
                         ok: false,
                         message: entry.message,
                         files: filePaths,
-                        error: "stage_failed",
+                        error: ERROR_CODES.STAGE_FAILED,
                         detail: stagingError,
                         ...spreadDefined("output", stagingError || undefined),
                     });
@@ -349,7 +345,7 @@ export function registerBatchCommitTool(server) {
                         ok: false,
                         message: entry.message,
                         files: filePaths,
-                        error: "commit_failed",
+                        error: ERROR_CODES.COMMIT_FAILED,
                         detail: gitOutput,
                         ...spreadDefined("output", gitOutput || undefined),
                     });

package/dist/server/error-codes.js

@@ -0,0 +1,95 @@
+/**
+ * Centralised error-code registry.
+ *
+ * Every value here is the exact string that appears on the wire in JSON
+ * responses (the `error` field). Keys are SCREAMING_SNAKE equivalents so
+ * callers get autocomplete and typos become compile errors.
+ *
+ * Adding a new code: append one entry here, then use ERROR_CODES.YOUR_CODE at
+ * the call-site — do not introduce a new inline string literal.
+ */
+export const ERROR_CODES = {
+    // Git availability
+    GIT_NOT_FOUND: "git_not_found",
+    // Repository resolution
+    NOT_A_GIT_REPOSITORY: "not_a_git_repository",
+    NO_WORKSPACE_ROOT: "no_workspace_root",
+    ROOT_INDEX_OUT_OF_RANGE: "root_index_out_of_range",
+    // absoluteGitRoots validation
+    ABSOLUTE_GIT_ROOTS_EMPTY: "absolute_git_roots_empty",
+    ABSOLUTE_GIT_ROOTS_EXCLUSIVE: "absolute_git_roots_exclusive",
+    ABSOLUTE_GIT_ROOTS_NESTED_OR_PRESET_CONFLICT: "absolute_git_roots_nested_or_preset_conflict",
+    ABSOLUTE_GIT_ROOTS_PRESET_CONFLICT: "absolute_git_roots_preset_conflict",
+    ABSOLUTE_GIT_ROOTS_SINGLE_REPO_ONLY: "absolute_git_roots_single_repo_only",
+    ABSOLUTE_GIT_ROOTS_TOO_MANY: "absolute_git_roots_too_many",
+    INVALID_ABSOLUTE_GIT_ROOT: "invalid_absolute_git_root",
+    // Presets
+    PRESET_FILE_INVALID: "preset_file_invalid",
+    PRESET_NOT_FOUND: "preset_not_found",
+    // Input validation — tokens / refs / paths
+    EMPTY_TAG_NAME: "empty_tag_name",
+    INVALID_LINE_RANGE: "invalid_line_range",
+    INVALID_PATHS: "invalid_paths",
+    INVALID_REMOTE_OR_BRANCH: "invalid_remote_or_branch",
+    INVALID_SINCE: "invalid_since",
+    PATH_ESCAPES_REPO: "path_escapes_repo",
+    PATH_ESCAPES_REPOSITORY: "path_escapes_repository",
+    UNSAFE_RANGE_TOKEN: "unsafe_range_token",
+    UNSAFE_REF_TOKEN: "unsafe_ref_token",
+    UNSAFE_REMOTE_TOKEN: "unsafe_remote_token",
+    UNSAFE_TAG_TOKEN: "unsafe_tag_token",
+    // Branch / ref state
+    INTO_DETACHED_HEAD: "into_detached_head",
+    ONTO_DETACHED_HEAD: "onto_detached_head",
+    PROTECTED_BRANCH: "protected_branch",
+    WORKING_TREE_DIRTY: "working_tree_dirty",
+    // Branch list
+    BRANCH_LIST_FAILED: "branch_list_failed",
+    // Commit / stage
+    COMMIT_FAILED: "commit_failed",
+    STAGE_FAILED: "stage_failed",
+    // Diff
+    GIT_DIFF_FAILED: "git_diff_failed",
+    // Log
+    GIT_LOG_FAILED: "git_log_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)
+    // Push
+    PUSH_DETACHED_HEAD: "push_detached_head",
+    PUSH_FAILED: "push_failed",
+    PUSH_NO_UPSTREAM: "push_no_upstream",
+    // Merge
+    CANNOT_FAST_FORWARD: "cannot_fast_forward",
+    DESTINATION_NOT_FOUND: "destination_not_found",
+    MERGE_BASE_FAILED: "merge_base_failed",
+    MERGE_CONFLICTS: "merge_conflicts",
+    MERGE_FAILED: "merge_failed",
+    REBASE_CONFLICTS: "rebase_conflicts",
+    SOURCE_NOT_FOUND: "source_not_found",
+    // Cherry-pick
+    CHECKOUT_FAILED: "checkout_failed",
+    RANGE_RESOLUTION_FAILED: "range_resolution_failed",
+    // Reset
+    RESET_FAILED: "reset_failed",
+    // Tag
+    REF_NOT_FOUND: "ref_not_found",
+    TAG_CREATE_FAILED: "tag_create_failed",
+    TAG_DELETE_FAILED: "tag_delete_failed",
+    TAG_VERIFICATION_FAILED: "tag_verification_failed",
+    // Worktree
+    CANNOT_REMOVE_MAIN_WORKTREE: "cannot_remove_main_worktree",
+    WORKTREE_ADD_FAILED: "worktree_add_failed",
+    WORKTREE_NOT_FOUND: "worktree_not_found",
+    WORKTREE_REMOVE_FAILED: "worktree_remove_failed",
+    // Inventory / parity
+    NO_PAIRS: "no_pairs",
+    REMOTE_BRANCH_MISMATCH: "remote_branch_mismatch",
+};

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

@@ -0,0 +1,227 @@
+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 { jsonRespond, spreadDefined } from "./json.js";
+import { requireSingleRepo } from "./roots.js";
+import { WorkspacePickSchema } from "./schemas.js";
+/**
+ * Convert a Unix epoch + timezone offset string (e.g. "+0200") to an ISO 8601 string.
+ * The tz offset is in the format ±HHMM as emitted by git blame --porcelain.
+ */
+function epochTzToIso(epoch, tz) {
+    // tz looks like "+0200" or "-0500"
+    const sign = tz.startsWith("-") ? -1 : 1;
+    const tzBody = tz.replace(/^[+-]/, "");
+    const tzHours = Number.parseInt(tzBody.slice(0, 2), 10);
+    const tzMins = Number.parseInt(tzBody.slice(2), 10);
+    const offsetMs = sign * (tzHours * 60 + tzMins) * 60 * 1000;
+    const localMs = epoch * 1000 + offsetMs;
+    const d = new Date(localMs);
+    const pad2 = (n) => String(n).padStart(2, "0");
+    const datePart = `${d.getUTCFullYear()}-${pad2(d.getUTCMonth() + 1)}-${pad2(d.getUTCDate())}`;
+    const timePart = `${pad2(d.getUTCHours())}:${pad2(d.getUTCMinutes())}:${pad2(d.getUTCSeconds())}`;
+    const tzSign = sign >= 0 ? "+" : "-";
+    const tzStr = `${tzSign}${pad2(tzHours)}:${pad2(tzMins)}`;
+    return `${datePart}T${timePart}${tzStr}`;
+}
+/**
+ * Parse `git blame --porcelain` output into structured lines.
+ *
+ * Porcelain format per commit block:
+ *   <sha> <orig-line> <final-line> [<num-lines>]
+ *   author <name>
+ *   author-mail <email>
+ *   author-time <epoch>
+ *   author-tz <±HHMM>
+ *   committer ...
+ *   summary <msg>
+ *   ...
+ *   \t<line content>
+ *
+ * Key-value header lines only appear for the FIRST occurrence of a SHA.
+ * Subsequent blocks for the same SHA have only the header line + TAB line.
+ */
+function parsePorcelain(output) {
+    const lines = output.split("\n");
+    const metaCache = new Map();
+    const result = [];
+    let i = 0;
+    while (i < lines.length) {
+        const headerLine = lines[i];
+        if (headerLine === undefined || headerLine.trim() === "") {
+            i++;
+            continue;
+        }
+        // Header: "<sha40> <origLine> <finalLine> [numLines]"
+        const headerMatch = /^([0-9a-f]{40}) \d+ (\d+)/.exec(headerLine);
+        if (!headerMatch) {
+            i++;
+            continue;
+        }
+        const sha = headerMatch[1] ?? "";
+        const finalLine = Number.parseInt(headerMatch[2] ?? "0", 10);
+        i++;
+        // Collect key-value lines until the TAB-prefixed content line
+        let author = "";
+        let authorTime = 0;
+        let authorTz = "+0000";
+        let summary = "";
+        let content = "";
+        let foundContent = false;
+        while (i < lines.length) {
+            const l = lines[i];
+            if (l === undefined) {
+                i++;
+                break;
+            }
+            if (l.startsWith("\t")) {
+                content = l.slice(1);
+                foundContent = true;
+                i++;
+                break;
+            }
+            // Parse known key-value pairs
+            if (l.startsWith("author ") && !l.startsWith("author-")) {
+                author = l.slice("author ".length);
+            }
+            else if (l.startsWith("author-time ")) {
+                authorTime = Number.parseInt(l.slice("author-time ".length), 10);
+            }
+            else if (l.startsWith("author-tz ")) {
+                authorTz = l.slice("author-tz ".length).trim();
+            }
+            else if (l.startsWith("summary ")) {
+                summary = l.slice("summary ".length);
+            }
+            i++;
+        }
+        if (!foundContent)
+            continue;
+        // Merge with cache: first occurrence populates cache; subsequent occurrences read it.
+        const cached = metaCache.get(sha);
+        if (cached === undefined) {
+            // First occurrence — we collected the metadata
+            metaCache.set(sha, { author, authorTime, summary, authorTz });
+        }
+        else {
+            // Subsequent occurrence — restore from cache
+            author = cached.author;
+            authorTime = cached.authorTime;
+            authorTz = cached.authorTz;
+            summary = cached.summary;
+        }
+        const date = epochTzToIso(authorTime, authorTz);
+        result.push({
+            line: finalLine,
+            sha,
+            author,
+            date,
+            summary,
+            content,
+        });
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Markdown rendering
+// ---------------------------------------------------------------------------
+function renderBlameMarkdown(result) {
+    const header = result.ref !== undefined
+        ? `# git blame ${result.ref} -- ${result.path}`
+        : `# git blame ${result.path}`;
+    const rows = result.lines.map((l) => {
+        const sha7 = l.sha.slice(0, 7);
+        return `${sha7} (${l.author} ${l.date}) ${l.content}`;
+    });
+    return [`${header}`, "", "```", ...rows, "```"].join("\n");
+}
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+export function registerGitBlameTool(server) {
+    server.addTool({
+        name: "git_blame",
+        description: "Annotate each line of a file with the commit SHA, author, date, and summary that last modified it. Optionally restrict to a commit-ish ref and/or a line range.",
+        annotations: {
+            readOnlyHint: true,
+        },
+        parameters: WorkspacePickSchema.omit({ absoluteGitRoots: true, allWorkspaceRoots: true })
+            .pick({
+            workspaceRoot: true,
+            rootIndex: true,
+            format: true,
+        })
+            .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."),
+            startLine: z
+                .number()
+                .int()
+                .min(1)
+                .optional()
+                .describe("First line of the range to blame (1-based). Requires endLine."),
+            endLine: z
+                .number()
+                .int()
+                .min(1)
+                .optional()
+                .describe("Last line of the range to blame (1-based, inclusive). Requires startLine."),
+        }),
+        execute: async (args) => {
+            const pre = requireSingleRepo(server, args);
+            if (!pre.ok)
+                return jsonRespond(pre.error);
+            const top = pre.gitTop;
+            // Path confinement
+            const resolved = resolvePathForRepo(args.path, top);
+            if (!assertRelativePathUnderTop(args.path, resolved, top)) {
+                return jsonRespond({ error: ERROR_CODES.PATH_ESCAPES_REPO, path: args.path });
+            }
+            // Ref validation
+            if (args.ref !== undefined) {
+                if (!isSafeGitRefToken(args.ref)) {
+                    return jsonRespond({ error: ERROR_CODES.UNSAFE_REF_TOKEN, ref: args.ref });
+                }
+            }
+            // Line range validation
+            const startLine = args.startLine;
+            const endLine = args.endLine;
+            if (startLine !== undefined || endLine !== undefined) {
+                if (startLine === undefined || endLine === undefined) {
+                    return jsonRespond({ error: ERROR_CODES.INVALID_LINE_RANGE });
+                }
+                if (startLine > endLine) {
+                    return jsonRespond({ error: ERROR_CODES.INVALID_LINE_RANGE });
+                }
+            }
+            // Build git blame args
+            const blameArgs = ["blame", "--porcelain"];
+            if (args.ref !== undefined) {
+                blameArgs.push(args.ref);
+            }
+            if (startLine !== undefined && endLine !== undefined) {
+                blameArgs.push(`-L${startLine},${endLine}`);
+            }
+            blameArgs.push("--", args.path);
+            const r = await spawnGitAsync(top, blameArgs);
+            if (!r.ok) {
+                return jsonRespond({
+                    error: ERROR_CODES.GIT_BLAME_FAILED,
+                    detail: (r.stderr || r.stdout).trim(),
+                });
+            }
+            const blameLines = parsePorcelain(r.stdout);
+            const blameJson = {
+                ...spreadDefined("ref", args.ref),
+                path: args.path,
+                lines: blameLines,
+            };
+            if (args.format === "json") {
+                return jsonRespond(blameJson);
+            }
+            return renderBlameMarkdown(blameJson);
+        },
+    });
+}

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

@@ -0,0 +1,138 @@
+import { z } from "zod";
+import { ERROR_CODES } from "./error-codes.js";
+import { spawnGitAsync } from "./git.js";
+import { jsonRespond, spreadDefined, spreadWhen } from "./json.js";
+import { requireSingleRepo } from "./roots.js";
+import { WorkspacePickSchema } from "./schemas.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+async function runBranchList(opts) {
+    const { top, includeRemotes } = opts;
+    // Local branches: name, full SHA, upstream (may be empty), HEAD marker (* or space)
+    const localR = await spawnGitAsync(top, [
+        "for-each-ref",
+        "--format=%(refname:short)%00%(objectname)%00%(upstream:short)%00%(HEAD)",
+        "refs/heads",
+    ]);
+    if (!localR.ok) {
+        return {
+            error: ERROR_CODES.BRANCH_LIST_FAILED,
+            detail: (localR.stderr || localR.stdout).trim(),
+        };
+    }
+    const branches = [];
+    const localLines = (localR.stdout || "").split("\n").filter((l) => l.length > 0);
+    for (const line of localLines) {
+        const parts = line.split("\x00");
+        const name = parts[0] ?? "";
+        const sha = parts[1] ?? "";
+        const upstream = parts[2] ?? "";
+        const headMarker = parts[3] ?? "";
+        if (!name || !sha)
+            continue;
+        branches.push({
+            name,
+            sha,
+            current: headMarker === "*",
+            ...spreadDefined("upstream", upstream || undefined),
+        });
+    }
+    if (!includeRemotes) {
+        return { branches };
+    }
+    // Remote branches: name, full SHA — skip symbolic origin/HEAD refs
+    const remoteR = await spawnGitAsync(top, [
+        "for-each-ref",
+        "--format=%(refname:short)%00%(objectname)",
+        "refs/remotes",
+    ]);
+    if (!remoteR.ok) {
+        return {
+            error: ERROR_CODES.BRANCH_LIST_FAILED,
+            detail: (remoteR.stderr || remoteR.stdout).trim(),
+        };
+    }
+    const remotes = [];
+    const remoteLines = (remoteR.stdout || "").split("\n").filter((l) => l.length > 0);
+    for (const line of remoteLines) {
+        const parts = line.split("\x00");
+        const name = parts[0] ?? "";
+        const sha = parts[1] ?? "";
+        // Skip symbolic origin/HEAD
+        if (!name || !sha || name.endsWith("/HEAD"))
+            continue;
+        remotes.push({ name, sha });
+    }
+    return {
+        branches,
+        ...spreadWhen(remotes.length > 0, { remotes }),
+    };
+}
+// ---------------------------------------------------------------------------
+// Markdown rendering
+// ---------------------------------------------------------------------------
+function renderBranchListMarkdown(result) {
+    const lines = ["## Branches", ""];
+    if (result.branches.length === 0) {
+        lines.push("_(none)_");
+    }
+    else {
+        for (const b of result.branches) {
+            const prefix = b.current ? "* " : "  ";
+            const upstream = b.upstream ? ` → ${b.upstream}` : "";
+            lines.push(`${prefix}**${b.name}**${upstream}  (\`${b.sha}\`)`);
+        }
+    }
+    if (result.remotes && result.remotes.length > 0) {
+        lines.push("");
+        lines.push("## Remote branches");
+        lines.push("");
+        for (const r of result.remotes) {
+            lines.push(`- **${r.name}**  (\`${r.sha}\`)`);
+        }
+    }
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+export function registerGitBranchListTool(server) {
+    server.addTool({
+        name: "git_branch_list",
+        description: "List local (and optionally remote-tracking) branches. Current branch marked `current: true`. Set `includeRemotes: true` for remotes.",
+        annotations: {
+            readOnlyHint: true,
+        },
+        parameters: WorkspacePickSchema.omit({ absoluteGitRoots: true, allWorkspaceRoots: true })
+            .pick({
+            workspaceRoot: true,
+            rootIndex: true,
+            format: true,
+        })
+            .extend({
+            includeRemotes: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("Include remote-tracking branches from refs/remotes (symbolic origin/HEAD excluded)."),
+        }),
+        execute: async (args) => {
+            const pre = requireSingleRepo(server, args);
+            if (!pre.ok)
+                return jsonRespond(pre.error);
+            const { gitTop } = pre;
+            const result = await runBranchList({
+                top: gitTop,
+                includeRemotes: args.includeRemotes ?? false,
+            });
+            if ("error" in result) {
+                return jsonRespond(result);
+            }
+            if (args.format === "json") {
+                return jsonRespond(result);
+            }
+            return renderBranchListMarkdown(result);
+        },
+    });
+}