@rethunk/mcp-multi-root-git 2.5.0 → 2.8.0

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 |
@@ -48,7 +48,7 @@ IDEs injecting this as context: do not re-link from rules.
 ## Changing contracts
 
 - **No banner paragraphs** in shipped docs. Use normal titles + cross-links.
-- **JSON format version** (currently `"3"`, discoverable via MCP `initialize`): bump on incompatible JSON changes (renamed/nested/omitted fields). Document migration here + [docs/mcp-tools.md](docs/mcp-tools.md). v2 removed the `rethunkGitMcp` envelope; payloads are minified; optional fields omitted when empty/null/false. v3 changes in `git_log`: `sha7` → `sha` (full SHA), `workspace_root` → `workspaceRoot`, `ageRelative` removed, `email` omitted when empty.
+- **JSON format version** (currently `"3"`, exported as `MCP_JSON_FORMAT_VERSION` in `src/server.ts` and surfaced via the FastMCP `instructions` field — discoverable from the MCP `initialize` response): bump on incompatible JSON changes (renamed/nested/omitted fields). Document migration here + [docs/mcp-tools.md](docs/mcp-tools.md). v2 removed the `rethunkGitMcp` envelope; payloads are minified; optional fields omitted when empty/null/false. v3 changes in `git_log`: `sha7` → `sha` (full SHA), `workspace_root` → `workspaceRoot`, `ageRelative` removed, `email` omitted when empty.
 - **Preset file:** keep `presets.ts` Zod schemas aligned with [`git-mcp-presets.schema.json`](git-mcp-presets.schema.json).
 - **Public tool surface:** rename/add → update [docs/mcp-tools.md](docs/mcp-tools.md) + [README.md](README.md) (if mentioned), then regenerate the shipped schema artifacts (`tool-parameters.schema.json`, `schemas/index.json`, `schemas/*.json`). Install/client wiring → [docs/install.md](docs/install.md) only.
 
@@ -66,7 +66,7 @@ Rules for LLMs operating in or against this repository.
 
 **End-user Git/MCP preference** (status/log/diff/commits): **`~/.claude/CLAUDE.md`** § **Git & GitHub** — same policy when dogfooding this server from a harness.
 
-**Mutating tools require workspace-root confirmation** — `git_fetch`, `batch_commit`, `git_push`, `git_merge`, `git_cherry_pick`, `git_reset_soft`, `git_tag`, and `git_stash_apply` operate only on roots confirmed by `requireGitAndRoots` / `requireSingleRepo`. Never pass caller-supplied absolute paths to mutating tools; use `workspaceRoot` or MCP roots.
+**Mutating tools use `workspaceRoot` as trusted operator input** — `git_fetch`, `batch_commit`, `git_push`, `git_merge`, `git_cherry_pick`, `git_reset_soft`, `git_tag`, and `git_stash_apply` operate on roots resolved via `requireGitAndRoots` / `requireSingleRepo`. Pass the target repo as `workspaceRoot` (trusted caller input) or via MCP roots. The `absoluteGitRoots` bulk multi-root parameter is not accepted by mutating tools — passing it is rejected.
 
 **`batch_commit` atomic staging — single call per logical change** — Do NOT attempt incremental staging across multiple `batch_commit` calls. Each call is self-contained: it stages all files in all entries, commits them sequentially, and the moment the call completes, all commits have landed. Include all related files (for all related commit entries) in a single `batch_commit` call. A call cannot be resumed or extended by a later call — each is an independent transaction. If entry N fails, entries before N remain committed; entries after N are skipped (not rolled back).
 
@@ -76,7 +76,7 @@ Rules for LLMs operating in or against this repository.
 
 **Never force-push** — `git_push` has no force-push mode by design. `git_merge` with `strategy: "ff-only"` will fail cleanly rather than force.
 
-**Contract bumps need documentation** — if a JSON output shape changes incompatibly, bump `MCP_JSON_FORMAT_VERSION` in `src/server.ts` and document the migration in both this file and [docs/mcp-tools.md](docs/mcp-tools.md).
+**Contract bumps need documentation** — if a JSON output shape changes incompatibly, bump the `MCP_JSON_FORMAT_VERSION` constant in `src/server.ts` (it is surfaced in the server `instructions` field and discoverable via MCP `initialize`) and document the migration in both this file and [docs/mcp-tools.md](docs/mcp-tools.md).
 
 **Path confinement** — any tool accepting file paths must use `resolvePathForRepo` / `assertRelativePathUnderTop` from [`src/repo-paths.ts`](src/repo-paths.ts) and include escaping-attempt tests.
 

package/CHANGELOG.md

@@ -2,7 +2,51 @@
 
 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).
 
-## [Unreleased]
+## [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.
+
+### Security
+
+- **Argument-injection hardening** — `git_show`, `git_log`, and `git_fetch` passed caller-supplied ref/branch/remote values straight into git argv. A value beginning with `-` is parsed by git as an option (`--output=<path>` writes an arbitrary file; `--upload-pack=<cmd>` on fetch runs a command). These read tools now validate those tokens against the argv-safe subset before invoking git, returning `unsafe_ref_token`, `unsafe_remote_token`, or `path_escapes_repo` on rejection — the same gate already applied to the mutating tools.
+- **`isProtectedBranch` normalization** — input is now normalized (trim, strip leading `refs/heads/`, lowercase) before matching, so `refs/heads/main`, `Main`, and `MAIN` are all recognized as protected. Previously the exact-name set was case-sensitive and a `refs/heads/` prefix evaded it entirely.
+
+### Fixed
+
+- **`batch_commit` linked worktrees** — hunk-level staging wrote its scratch patch under `${gitTop}/.git/`, which fails with `ENOTDIR` in a linked worktree (where `.git` is a file). The scratch path is now resolved via `git rev-parse --absolute-git-dir`, correct for both normal repos and worktrees.
+- **`batch_commit` dry run** — preview cleanup ran an unconditional `git reset HEAD --` over every touched path, silently unstaging work the caller had staged before invoking. A pre-staged snapshot is now taken first; cleanup resets only paths the dry run itself staged.
+- **`git_stash_list` index** — `index` was taken from the loop counter, so a malformed entry dropped by the parse guard shifted every later index and `git_stash_apply` could target the wrong stash. The index is now parsed from the canonical `stash@{N}` ref.
+- **`git_diff_summary` rename parsing** — the new path of a rename whose path contained the substring ` b/` was mis-reported because the greedy `diff --git` header regex split at the wrong point; the authoritative `rename to` body line is now used.
+- **`.gitmodules` parser** — `parseGitSubmodulePaths` matched any `path =` line regardless of INI section and ignored comments; it now tracks `[submodule]` sections and strips `;`/`#` comments.
+- **`git_inventory` / `git_parity` v3 JSON** — `workspace_root` field corrected to `workspaceRoot` (camelCase), completing the v3 contract rename already applied to `git_log`.
+
+### Changed
+
+- **`git_tag` error codes renamed** — `tag_empty` → `empty_tag_name`, `tag_unsafe` → `unsafe_tag_token`, `ref_unsafe` → `unsafe_ref_token`; consistent with the server-wide naming convention.
+- **`git_diff` multi-root parameters removed** — `absoluteGitRoots` and `allWorkspaceRoots` are no longer accepted by `git_diff`; it is now a pure single-repo tool (identical posture to `git_show`). Use `workspaceRoot` or `rootIndex` to select the target repo. `git_diff_summary` keeps single-entry `absoluteGitRoots` and drops only `allWorkspaceRoots`.
+- **`MCP_JSON_FORMAT_VERSION` constant** — `"3"` is now an exported constant in `src/server.ts` and surfaced in the FastMCP `instructions` field, making the format version discoverable from the MCP `initialize` response.
+- **CI** — the 20 published per-tool `schemas/*.json` artifacts are now drift-checked on every PR via a new `schema:individual:check` step; previously only `tool-parameters.schema.json` was gated.
 
 ## [2.5.0] — 2026-05-15
 

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";
@@ -162,8 +163,14 @@ async function stageFile(gitTop, filePath, lines) {
     if (!partialPatch) {
         return { ok: false, error: "No hunks found in line range" };
     }
-    // Write partial patch to temp file in the git repo and apply it to the index
-    const tempPatchFile = `${gitTop}/.git/.mcp-patch-${Date.now()}-${Math.random().toString(36).slice(2)}.patch`;
+    // 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`;
     const { writeFileSync, unlinkSync } = await import("node:fs");
     writeFileSync(tempPatchFile, partialPatch, "utf8");
     const applyResult = await spawnGitAsync(gitTop, ["apply", "--cached", tempPatchFile]);
@@ -186,11 +193,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) {
@@ -198,7 +205,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(),
         };
     }
@@ -239,6 +246,18 @@ export function registerBatchCommitTool(server) {
             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();
+            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));
+                }
+            }
             for (let i = 0; i < args.commits.length; i++) {
                 const entry = args.commits[i];
                 if (!entry)
@@ -270,7 +289,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;
@@ -292,16 +311,19 @@ 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),
                     });
                     break;
                 }
-                // Track staged files for cleanup in dry-run
+                // Track staged files for cleanup in dry-run, excluding paths that were
+                // already staged before this call (so pre-existing staged state survives).
                 if (args.dryRun) {
                     for (const path of filePaths) {
-                        stagedFilesForCleanup.add(path);
+                        if (!preStagedPaths.has(path)) {
+                            stagedFilesForCleanup.add(path);
+                        }
                     }
                 }
                 // --- Dry-run mode: collect preview and unstage ---
@@ -328,7 +350,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);
+        },
+    });
+}