@rethunk/mcp-multi-root-git 1.0.0

package/AGENTS.md

@@ -0,0 +1,53 @@
+# AGENTS.md — LLM and developer onboarding
+
+**Scope:** [`@rethunk/mcp-multi-root-git`](https://www.npmjs.com/package/@rethunk/mcp-multi-root-git) is an MCP **stdio** server: entry [`src/server.ts`](src/server.ts) (FastMCP + `registerRethunkGitTools`), supporting modules under [`src/server/`](src/server/), build output [`dist/server.js`](dist/server.js) (see `package.json` `bin` / `exports`; publish ships the full `dist/` tree).
+
+**Operators and integrators:** **[docs/install.md](docs/install.md)** is the **only** place for prerequisites, how to launch the server, and per-client MCP configuration — do not duplicate that in README, HUMANS, rules, or here. Preset file, dev workflow, CI, and publishing: **[HUMANS.md](HUMANS.md)**.
+
+**Tool ids, client naming, `format` / JSON envelopes, resource URI, workspace root order:** **[docs/mcp-tools.md](docs/mcp-tools.md)** — canonical; do not duplicate those tables in this file or HUMANS.
+
+## Implementation map
+
+| File | Symbols / notes |
+|------|-------------------|
+| [`src/server.ts`](src/server.ts) | `FastMCP` + `roots: { enabled: true }`; `readMcpServerVersion()`; `registerRethunkGitTools` |
+| [`src/server/json.ts`](src/server/json.ts) | `MCP_JSON_FORMAT_VERSION`, `jsonRespond()`, `spreadWhen`, `spreadDefined` — every tool JSON body ends with `rethunkGitMcp` |
+| [`src/server/git.ts`](src/server/git.ts) | `gateGit()` — lazy `git --version`; `spawnGitAsync`, `asyncPool`, `GIT_SUBPROCESS_PARALLELISM`; `gitTopLevel`, `gitRevParseGitDir`, `gitRevParseHead`, `parseGitSubmodulePaths`, `hasGitMetadata`; `gitStatusSnapshotAsync`, `gitStatusShortBranchAsync`, `fetchAheadBehind`, `isSafeGitUpstreamToken` |
+| [`src/server/roots.ts`](src/server/roots.ts) | `uriToPath`, `listFileRoots`, `pathMatchesWorkspaceRootHint`, `resolveWorkspaceRoots`, `resolveRootsForPreset`, `requireGitAndRoots` — session roots only (client wiring: [docs/install.md](docs/install.md)) |
+| [`src/server/presets.ts`](src/server/presets.ts) | `PRESET_FILE_PATH`, `splitPresetFileRaw`, `loadPresetsFromGitTop`, `getPresetEntry`, `presetLoadErrorPayload`, `applyPresetNestedRoots`, `applyPresetParityPairs`; Zod `PresetEntrySchema` / `PresetFileSchema` 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` |
+| [`src/server/inventory.ts`](src/server/inventory.ts) | `validateRepoPath`, `makeSkipEntry`, `buildInventorySectionMarkdown`, `collectInventoryEntry` (uses repo-paths + git) |
+| [`src/server/tools.ts`](src/server/tools.ts) | `registerRethunkGitTools` — calls per-surface `register*` below |
+| [`src/server/git-status-tool.ts`](src/server/git-status-tool.ts) | `registerGitStatusTool` — `git_status` |
+| [`src/server/git-inventory-tool.ts`](src/server/git-inventory-tool.ts) | `registerGitInventoryTool` — `git_inventory` |
+| [`src/server/git-parity-tool.ts`](src/server/git-parity-tool.ts) | `registerGitParityTool` — `git_parity` |
+| [`src/server/list-presets-tool.ts`](src/server/list-presets-tool.ts) | `registerListPresetsTool` — `list_presets` |
+| [`src/server/presets-resource.ts`](src/server/presets-resource.ts) | `registerPresetsResource` — `rethunk-git://presets` resource |
+| [`src/repo-paths.ts`](src/repo-paths.ts) | `resolvePathForRepo`, `assertRelativePathUnderTop`, `isStrictlyUnderGitTop`, `realPathOrSelf` |
+
+## Changing contracts
+
+- **Documentation layout:** do not add top-of-file **banner** paragraphs (bold blocks such as “Canonical doc for… / link here only”) to `docs/install.md` or other shipped docs. Use normal titles, TOC, and cross-links from README / this file / HUMANS.
+- **`rethunkGitMcp.jsonFormatVersion`:** bump **`MCP_JSON_FORMAT_VERSION`** and document the migration in this file and in [docs/mcp-tools.md](docs/mcp-tools.md) when JSON field names or nesting change incompatibly.
+- **Preset file:** keep **`splitPresetFileRaw`** + Zod parsing aligned with **`git-mcp-presets.schema.json`**; update the schema when adding keys or shapes.
+- **Public tool surface:** if you add/rename tools, update [docs/mcp-tools.md](docs/mcp-tools.md) and [README.md](README.md) if the landing page still mentions tools; update [docs/install.md](docs/install.md) if install or client-specific wiring changes — **never** copy install steps into other docs; update [.cursor/rules/rethunk-git-mcp.mdc](.cursor/rules/rethunk-git-mcp.mdc) only if *when-to-use MCP vs shell* wording must change (that rule links `docs/install.md`, [HUMANS.md](HUMANS.md), and `docs/mcp-tools.md` without duplicating them).
+
+## Validation and CI
+
+Local: `bun run build` (`rimraf dist && tsc`), `bun run check` (Biome), `bun run test` (`bun test` for [`src/repo-paths.test.ts`](src/repo-paths.test.ts)). GitHub Actions runs the same after `bun install --frozen-lockfile` on PRs and `main` ([`.github/workflows/ci.yml`](.github/workflows/ci.yml)), then uploads a **prerelease `npm pack` artifact**. Pushes of tag **`v*.*.*`** matching `package.json` `version` run [`.github/workflows/release.yml`](.github/workflows/release.yml) (**GitHub Packages** npm publish under **`@rethunk-ai/mcp-multi-root-git`** + **GitHub Release** with tarball); **npmjs** is manual only — see [HUMANS.md](HUMANS.md) Publishing.
+
+Optional [`.githooks/`](.githooks): run **`bun run setup-hooks`** once per clone (`core.hooksPath` → `.githooks`). **pre-commit** = `check`; **pre-push** = frozen install + build + check. See [HUMANS.md](HUMANS.md) Development.
+
+Path confinement helpers live in [`src/repo-paths.ts`](src/repo-paths.ts); extend tests when changing that logic.
+
+## Repository MCP entry (contributors)
+
+Dogfooding from a clone: **[docs/install.md](docs/install.md)** — *From source (this repository)* only.
+
+This repo may ship **`.cursor/`** config (example MCP entry + **alwaysApply** rule [`.cursor/rules/rethunk-git-mcp.mdc`](.cursor/rules/rethunk-git-mcp.mdc)). The rule covers *when* to call these tools vs shell git and links **`docs/install.md`**, **[HUMANS.md](HUMANS.md)**, and **`docs/mcp-tools.md`** without duplicating their bodies; it does not re-link this file when it is already injected as project context.
+
+User-level skills may still mention the GitHub **README** for discovery. Canonical references: **tools / JSON** — **[docs/mcp-tools.md](docs/mcp-tools.md)**; **install / client wiring** — **[docs/install.md](docs/install.md)** (link it; do not paste per-client JSON into skills); **preset file** — **[HUMANS.md](HUMANS.md)**.
+
+## Commits
+
+Use the team’s **conventional commits + batching** skill (or equivalent): small themed commits, why-focused messages, `git add` + `git commit` in one shell invocation per batch.

package/HUMANS.md

@@ -0,0 +1,115 @@
+# @rethunk/mcp-multi-root-git — User guide
+
+Read-only MCP git tools for any workspace. **How the server is installed and wired to clients:** **[docs/install.md](docs/install.md)** only (do not restate that material here).
+
+**Implementation map (modules under `src/server/`, entry `src/server.ts`), symbols, and contract bumps** live in **`AGENTS.md`** at the repository root. This guide does not repeat those sections.
+
+**Registered tool ids, client naming (`rethunk-git_*`), `format` / JSON envelopes, resource URI, workspace root resolution:** **[docs/mcp-tools.md](docs/mcp-tools.md)** — canonical; not duplicated here.
+
+## Workspace preset file
+
+Commit **`.rethunk/git-mcp-presets.json`** at the **git repository root** (next to `.git`).
+
+Example (legacy-style map):
+
+```json
+{
+  "push-prep": {
+    "nestedRoots": ["path/to/package-a", "path/to/package-b"],
+    "parityPairs": [
+      { "left": "core/packages/shared", "right": "edge/packages/shared", "label": "shared" }
+    ],
+    "workspaceRootHint": "my-repo"
+  }
+}
+```
+
+Call tools with `"preset": "push-prep"` instead of passing paths inline. Use **`presetMerge`: true** on `git_inventory` or `git_parity` to merge preset paths/pairs with inline `nestedRoots` / `pairs`.
+
+With **multiple MCP file roots**, the server picks a root whose git toplevel defines that preset. If the preset entry has **`workspaceRootHint`**, only MCP roots whose basename or path suffix match are considered.
+
+**JSON Schema** ships with the package as **`git-mcp-presets.schema.json`** for editor validation. Example wrapped layout:
+
+```json
+{
+  "$schema": "./node_modules/@rethunk/mcp-multi-root-git/git-mcp-presets.schema.json",
+  "schemaVersion": "1",
+  "presets": {
+    "push-prep": {
+      "nestedRoots": ["packages/a"],
+      "parityPairs": []
+    }
+  }
+}
+```
+
+If you installed from **GitHub Packages**, use **`./node_modules/@rethunk-ai/mcp-multi-root-git/git-mcp-presets.schema.json`** in **`$schema`** instead (see [docs/install.md](docs/install.md#github-packages)).
+
+**Layouts:**
+
+1. **Wrapped (recommended):** `{ "schemaVersion": "1", "presets": { "<name>": { ... } } }`.
+2. **Legacy map:** `{ "<preset-name>": { ... } }` with optional top-level `"schemaVersion"` and `"$schema"`.
+
+Invalid JSON or schema errors return **`preset_file_invalid`** (not a silent empty result).
+
+### Preset entry (quick reference)
+
+```jsonc
+{
+  "<preset-name>": {
+    "nestedRoots": ["<relative-path>", ...],
+    "parityPairs": [{ "left": "<rel>", "right": "<rel>", "label": "<display>" }],
+    "workspaceRootHint": "<basename-or-suffix>"
+  }
+}
+```
+
+Relative preset paths must stay inside the git toplevel; escapes are rejected.
+
+## `git_not_found`
+
+If **`git`** is missing or not runnable, tools and the presets resource respond with **`git_not_found`**. Prerequisites and `PATH`: **[docs/install.md](docs/install.md)**.
+
+## Installation
+
+**Package install and MCP clients:** **[docs/install.md](docs/install.md)**.
+
+## Development
+
+Requires **Bun ≥ 1.3.11** to build this repository (`packageManager` in `package.json`). **Published runtime** (Node/Bun/Git and how to launch the server): **[docs/install.md](docs/install.md)** — *Prerequisites*.
+
+```bash
+bun install
+bun run build      # rimraf dist + tsc → dist/server.js, dist/server/*.js, dist/repo-paths.js
+bun run check      # Biome
+bun run check:fix  # Biome --write
+bun run setup-hooks   # once per clone: use .githooks (pre-commit: check; pre-push: CI parity)
+```
+
+**Git hooks:** after `setup-hooks`, **pre-commit** runs `bun run check`; **pre-push** runs `bun install --frozen-lockfile`, `bun run build`, `bun run check`, and `bun run test` (same order as CI). Set **`SKIP_GIT_HOOKS=1`** or use **`--no-verify`** to bypass.
+
+**CI:** [`.github/workflows/ci.yml`](.github/workflows/ci.yml) runs on pull requests and pushes to `main`: **`actions/setup-node` with Node 24** (minimum 22 asserted), then `bun install --frozen-lockfile`, `bun run build`, `bun run check`, and `bun run test`. A follow-up job **`prerelease-pack`** builds the same tree and runs **`npm pack`**, then uploads a **prerelease `.tgz` artifact** (named with the commit SHA) you can download from the workflow run’s **Artifacts** section (retention 90 days). Match the check job locally before opening a PR.
+
+## Publishing
+
+### GitHub (automated) — version tags only
+
+Tag pushes run [`.github/workflows/release.yml`](.github/workflows/release.yml): build, check, tests, then:
+
+1. **`npm pack`** using the committed **`package.json`** name [`@rethunk/mcp-multi-root-git`](https://github.com/Rethunk-AI/mcp-multi-root-git) — tarball attached to a **GitHub Release** for that tag.
+2. **GitHub Packages** (npm registry): the workflow temporarily rewrites the package **name** to **`@rethunk-ai/mcp-multi-root-git`** (required scope for org `Rethunk-AI` on GitHub) and runs **`npm publish`** to **`https://npm.pkg.github.com`** with **`GITHUB_TOKEN`** (`packages: write`). No npmjs token is used in CI.
+
+Prerequisite: push a **semver git tag** `vX.Y.Z` that **exactly matches** `version` in `package.json` (e.g. `v1.2.3` and `"version": "1.2.3"`).
+
+### npmjs (manual) — maintainers only
+
+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`).
+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.json` `files`** must keep the whole **`dist/`** directory so every emitted chunk the entry imports is packed; if you add new `src/server/*.ts` modules, `tsc` emits matching **`dist/server/*.js`** files — do not narrow **`files`** back to a single **`server.js`** or installs break.
+
+**Preset `$schema`:** after **`npm install`**, the schema path is under **`node_modules/@rethunk/mcp-multi-root-git/`** for npmjs, or **`node_modules/@rethunk-ai/mcp-multi-root-git/`** when installing from GitHub Packages — adjust **`$schema`** accordingly (see [docs/install.md](docs/install.md)).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rethunk-AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,25 @@
+# @rethunk/mcp-multi-root-git
+
+[![CI](https://github.com/Rethunk-AI/mcp-multi-root-git/actions/workflows/ci.yml/badge.svg)](https://github.com/Rethunk-AI/mcp-multi-root-git/actions/workflows/ci.yml)
+[![Release](https://github.com/Rethunk-AI/mcp-multi-root-git/actions/workflows/release.yml/badge.svg)](https://github.com/Rethunk-AI/mcp-multi-root-git/actions/workflows/release.yml)
+[![GitHub release](https://img.shields.io/github/v/release/Rethunk-AI/mcp-multi-root-git?logo=github&label=release)](https://github.com/Rethunk-AI/mcp-multi-root-git/releases/latest)
+[![npm version](https://img.shields.io/npm/v/%40rethunk%2Fmcp-multi-root-git.svg)](https://www.npmjs.com/package/@rethunk/mcp-multi-root-git)
+[![npm downloads](https://img.shields.io/npm/dm/%40rethunk%2Fmcp-multi-root-git.svg?label=npm%20downloads)](https://www.npmjs.com/package/@rethunk/mcp-multi-root-git)
+[![GitHub Packages](https://img.shields.io/badge/github%20packages-%40rethunk--ai%2Fmcp--multi--root--git-24292f?logo=github)](https://github.com/Rethunk-AI/mcp-multi-root-git/pkgs/npm/mcp-multi-root-git)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D22-339933.svg)](https://github.com/Rethunk-AI/mcp-multi-root-git/blob/main/package.json)
+
+Read-only **git** tools over MCP (status, multi-root inventory, `HEAD` parity, presets). **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/pkgs/npm/mcp-multi-root-git) — see [docs/install.md](docs/install.md) and [HUMANS.md](HUMANS.md) Publishing.
+
+## Documentation
+
+| Doc | Audience |
+|-----|----------|
+| **[docs/install.md](docs/install.md)** | Single source for prerequisites, running the package, and every supported MCP client (plus from-source and troubleshooting) |
+| **[docs/mcp-tools.md](docs/mcp-tools.md)** | Tool ids, client naming, `format` / JSON, resource URI, workspace root resolution (canonical reference) |
+| **[HUMANS.md](HUMANS.md)** | Preset file, dev commands, CI, publishing |
+| **[AGENTS.md](AGENTS.md)** | Contributors: implementation map ([`src/server/`](src/server/) + entry [`src/server.ts`](src/server.ts)), contract bumps, CI (IDEs that inject this file as project context should not re-link it from rules) |
+
+**Tools at a glance:** see the table in **[docs/mcp-tools.md](docs/mcp-tools.md)**.

package/dist/repo-paths.js

@@ -0,0 +1,26 @@
+import { realpathSync } from "node:fs";
+import { isAbsolute, relative, resolve } from "node:path";
+export function realPathOrSelf(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+export function isStrictlyUnderGitTop(absPath, gitTop) {
+    const absR = realPathOrSelf(resolve(absPath));
+    const topR = realPathOrSelf(resolve(gitTop));
+    const rel = relative(topR, absR);
+    if (rel === "")
+        return true;
+    return !rel.startsWith("..") && !isAbsolute(rel);
+}
+export function resolvePathForRepo(p, gitTop) {
+    const t = p.trim();
+    return isAbsolute(t) ? resolve(t) : resolve(gitTop, t);
+}
+/** Resolved path must lie inside git toplevel (relative or absolute user input). */
+export function assertRelativePathUnderTop(_relPath, absResolved, gitTop) {
+    return isStrictlyUnderGitTop(absResolved, gitTop);
+}

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

@@ -0,0 +1,191 @@
+import { z } from "zod";
+import { asyncPool, GIT_SUBPROCESS_PARALLELISM, gitRevParseGitDir, gitTopLevel, isSafeGitUpstreamToken, } from "./git.js";
+import { buildInventorySectionMarkdown, collectInventoryEntry, makeSkipEntry, validateRepoPath, } from "./inventory.js";
+import { jsonRespond, spreadDefined, spreadWhen } from "./json.js";
+import { applyPresetNestedRoots } from "./presets.js";
+import { requireGitAndRoots } from "./roots.js";
+import { MAX_INVENTORY_ROOTS_DEFAULT, WorkspacePickSchema } from "./schemas.js";
+export function registerGitInventoryTool(server) {
+    server.addTool({
+        name: "git_inventory",
+        description: "Read-only push-prep inventory: status + ahead/behind per root. " +
+            "Uses each repo's configured upstream (`@{u}`) unless both `remote` and `branch` are set. " +
+            "Presets from `.rethunk/git-mcp-presets.json`; use `presetMerge` to combine with inline paths.",
+        parameters: WorkspacePickSchema.extend({
+            nestedRoots: z
+                .array(z.string())
+                .optional()
+                .describe("Paths relative to git toplevel. If empty/omitted, only the repo root is listed. With `presetMerge`, merged with preset paths."),
+            preset: z
+                .string()
+                .optional()
+                .describe("Named preset from .rethunk/git-mcp-presets.json (at git toplevel)."),
+            presetMerge: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("When true, merge `nestedRoots` with preset nestedRoots instead of replacing."),
+            remote: z
+                .string()
+                .optional()
+                .describe("Fixed upstream remote; must be set together with `branch` to override auto upstream."),
+            branch: z
+                .string()
+                .optional()
+                .describe("Fixed upstream branch name; must be set together with `remote`."),
+            maxRoots: z
+                .number()
+                .int()
+                .min(1)
+                .max(256)
+                .optional()
+                .default(MAX_INVENTORY_ROOTS_DEFAULT)
+                .describe("Max nested roots to process (cap)."),
+        }),
+        execute: async (args) => {
+            const pre = requireGitAndRoots(server, args, args.preset);
+            if (!pre.ok) {
+                return jsonRespond(pre.error);
+            }
+            const fixedRemote = args.remote;
+            const fixedBranch = args.branch;
+            const hasRemote = fixedRemote !== undefined && fixedRemote.trim() !== "";
+            const hasBranch = fixedBranch !== undefined && fixedBranch.trim() !== "";
+            if (hasRemote !== hasBranch) {
+                return jsonRespond({
+                    error: "remote_branch_mismatch",
+                    message: "Set both `remote` and `branch` for fixed upstream, or omit both for auto `@{u}`.",
+                });
+            }
+            const useFixed = hasRemote && hasBranch;
+            if (useFixed) {
+                const r = String(fixedRemote).trim();
+                const b = String(fixedBranch).trim();
+                if (!isSafeGitUpstreamToken(r) || !isSafeGitUpstreamToken(b)) {
+                    return jsonRespond({
+                        error: "invalid_remote_or_branch",
+                        message: "remote and branch must be plain tokens: no whitespace, control characters, `@`, `..`, leading `-`, or git rev metacharacters like `^ : ? * [ ] { } ~ \\`.",
+                    });
+                }
+            }
+            const allJson = [];
+            const mdChunks = [];
+            for (const workspaceRoot of pre.roots) {
+                const top = gitTopLevel(workspaceRoot);
+                if (!top) {
+                    const err = { error: "not_a_git_repository", path: workspaceRoot };
+                    if (args.format === "json") {
+                        allJson.push({
+                            workspace_root: workspaceRoot,
+                            upstream: {
+                                mode: useFixed ? "fixed" : "auto",
+                                remote: fixedRemote,
+                                branch: fixedBranch,
+                            },
+                            entries: [
+                                {
+                                    label: workspaceRoot,
+                                    path: workspaceRoot,
+                                    branchStatus: "",
+                                    shortStatus: "",
+                                    detached: false,
+                                    headAbbrev: "",
+                                    upstreamMode: useFixed ? "fixed" : "auto",
+                                    upstreamRef: null,
+                                    ahead: null,
+                                    behind: null,
+                                    upstreamNote: "",
+                                    skipReason: JSON.stringify(err),
+                                },
+                            ],
+                        });
+                    }
+                    else {
+                        mdChunks.push(`# Git inventory`, "", jsonRespond(err), "");
+                    }
+                    continue;
+                }
+                let nestedRoots = args.nestedRoots;
+                let presetSchemaVersion;
+                if (args.preset) {
+                    const applied = applyPresetNestedRoots(top, args.preset, args.presetMerge, nestedRoots);
+                    if (!applied.ok) {
+                        return jsonRespond(applied.error);
+                    }
+                    nestedRoots = applied.nestedRoots;
+                    presetSchemaVersion = applied.presetSchemaVersion;
+                }
+                const maxRoots = args.maxRoots ?? MAX_INVENTORY_ROOTS_DEFAULT;
+                let nestedRootsTruncated = false;
+                let nestedRootsOmittedCount = 0;
+                if (nestedRoots && nestedRoots.length > maxRoots) {
+                    nestedRootsOmittedCount = nestedRoots.length - maxRoots;
+                    nestedRoots = nestedRoots.slice(0, maxRoots);
+                    nestedRootsTruncated = true;
+                }
+                const headerNote = useFixed
+                    ? `remote/branch (fixed): ${fixedRemote}/${fixedBranch}`
+                    : "upstream: per-repo @{u} (configured upstream)";
+                const entries = [];
+                if (nestedRoots?.length) {
+                    const jobs = [];
+                    for (const rel of nestedRoots) {
+                        const { abs, underTop } = validateRepoPath(rel, top);
+                        if (!underTop) {
+                            entries.push(makeSkipEntry(rel, abs, useFixed ? "fixed" : "auto", "(path escapes git toplevel — rejected)"));
+                            continue;
+                        }
+                        if (!gitRevParseGitDir(abs)) {
+                            entries.push(makeSkipEntry(rel, abs, useFixed ? "fixed" : "auto", "(not a git work tree — skip)"));
+                            continue;
+                        }
+                        jobs.push({ label: rel, abs });
+                    }
+                    const computed = await asyncPool(jobs, GIT_SUBPROCESS_PARALLELISM, (j) => collectInventoryEntry(j.label, j.abs, useFixed ? fixedRemote : undefined, useFixed ? fixedBranch : undefined));
+                    entries.push(...computed);
+                }
+                else if (!gitRevParseGitDir(top)) {
+                    entries.push(makeSkipEntry(".", top, useFixed ? "fixed" : "auto", "(not a git work tree — unexpected)"));
+                }
+                else {
+                    const one = await collectInventoryEntry(".", top, useFixed ? fixedRemote : undefined, useFixed ? fixedBranch : undefined);
+                    entries.push(one);
+                }
+                if (args.format === "json") {
+                    allJson.push({
+                        workspace_root: top,
+                        ...spreadDefined("presetSchemaVersion", presetSchemaVersion),
+                        ...spreadWhen(nestedRootsTruncated, {
+                            nestedRootsTruncated: true,
+                            nestedRootsOmittedCount,
+                        }),
+                        upstream: useFixed
+                            ? { mode: "fixed", remote: fixedRemote, branch: fixedBranch }
+                            : { mode: "auto" },
+                        entries,
+                    });
+                }
+                else {
+                    const sections = [
+                        "# Git inventory",
+                        "",
+                        `workspace_root: ${top}`,
+                        headerNote,
+                        "",
+                    ];
+                    if (nestedRootsTruncated) {
+                        sections.push(`nested_roots_truncated: ${nestedRootsOmittedCount} path(s) not listed (maxRoots=${maxRoots})`, "");
+                    }
+                    for (const e of entries) {
+                        sections.push(...buildInventorySectionMarkdown(e));
+                    }
+                    mdChunks.push(sections.join("\n"));
+                }
+            }
+            if (args.format === "json") {
+                return jsonRespond({ inventories: allJson });
+            }
+            return mdChunks.join("\n\n---\n\n");
+        },
+    });
+}

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

@@ -0,0 +1,149 @@
+import { z } from "zod";
+import { gitRevParseHead, gitTopLevel } from "./git.js";
+import { validateRepoPath } from "./inventory.js";
+import { jsonRespond, spreadDefined } from "./json.js";
+import { applyPresetParityPairs } from "./presets.js";
+import { requireGitAndRoots } from "./roots.js";
+import { WorkspacePickSchema } from "./schemas.js";
+export function registerGitParityTool(server) {
+    server.addTool({
+        name: "git_parity",
+        description: "Read-only: compare `git rev-parse HEAD` for path pairs. Presets or inline `pairs`; `presetMerge` merges with inline pairs.",
+        parameters: WorkspacePickSchema.extend({
+            pairs: z
+                .array(z.object({
+                left: z.string(),
+                right: z.string(),
+                label: z.string().optional(),
+            }))
+                .optional(),
+            preset: z.string().optional(),
+            presetMerge: z.boolean().optional().default(false),
+        }),
+        execute: async (args) => {
+            const pre = requireGitAndRoots(server, args, args.preset);
+            if (!pre.ok) {
+                return jsonRespond(pre.error);
+            }
+            const results = [];
+            const mdParts = [];
+            for (const workspaceRoot of pre.roots) {
+                const top = gitTopLevel(workspaceRoot);
+                if (!top) {
+                    const errPayload = { error: "not_a_git_repository", path: workspaceRoot };
+                    const err = jsonRespond(errPayload);
+                    if (args.format === "json") {
+                        results.push({
+                            workspace_root: workspaceRoot,
+                            status: "MISMATCH",
+                            pairs: [{ label: "—", leftPath: "", rightPath: "", match: false, error: err }],
+                        });
+                    }
+                    else {
+                        mdParts.push(err);
+                    }
+                    continue;
+                }
+                let pairs = args.pairs;
+                let parityPresetSchemaVersion;
+                if (args.preset) {
+                    const applied = applyPresetParityPairs(top, args.preset, args.presetMerge, pairs);
+                    if (!applied.ok) {
+                        return jsonRespond(applied.error);
+                    }
+                    pairs = applied.pairs;
+                    parityPresetSchemaVersion = applied.presetSchemaVersion;
+                }
+                if (!pairs?.length) {
+                    return jsonRespond({
+                        error: "no_pairs",
+                        message: "Pass `pairs` directly or a `preset` with parityPairs (or presetMerge).",
+                    });
+                }
+                let allOk = true;
+                const pairResults = [];
+                for (const pair of pairs) {
+                    const pa = validateRepoPath(pair.left, top);
+                    const pb = validateRepoPath(pair.right, top);
+                    const label = pair.label ?? `${pair.left} / ${pair.right}`;
+                    if (!pa.underTop || !pb.underTop) {
+                        allOk = false;
+                        pairResults.push({
+                            label,
+                            leftPath: pa.abs,
+                            rightPath: pb.abs,
+                            match: false,
+                            error: "path escapes git toplevel — rejected",
+                        });
+                        continue;
+                    }
+                    const ha = gitRevParseHead(pa.abs);
+                    const hb = gitRevParseHead(pb.abs);
+                    if (!ha.ok || !hb.ok) {
+                        allOk = false;
+                        pairResults.push({
+                            label,
+                            leftPath: pa.abs,
+                            rightPath: pb.abs,
+                            match: false,
+                            error: [!ha.ok ? `left: ${ha.text}` : "", !hb.ok ? `right: ${hb.text}` : ""]
+                                .filter(Boolean)
+                                .join("\n"),
+                        });
+                        continue;
+                    }
+                    if (ha.sha !== hb.sha) {
+                        allOk = false;
+                        pairResults.push({
+                            label,
+                            leftPath: pa.abs,
+                            rightPath: pb.abs,
+                            match: false,
+                            leftSha: ha.sha,
+                            rightSha: hb.sha,
+                        });
+                    }
+                    else {
+                        pairResults.push({
+                            label,
+                            leftPath: pa.abs,
+                            rightPath: pb.abs,
+                            match: true,
+                            sha: ha.sha,
+                        });
+                    }
+                }
+                results.push({
+                    workspace_root: top,
+                    ...spreadDefined("presetSchemaVersion", parityPresetSchemaVersion),
+                    status: allOk ? "OK" : "MISMATCH",
+                    pairs: pairResults,
+                });
+                if (args.format !== "json") {
+                    const lines = [
+                        "# Git HEAD parity",
+                        "",
+                        `status: ${allOk ? "OK" : "MISMATCH"}`,
+                        "",
+                    ];
+                    for (const pr of pairResults) {
+                        if (pr.error) {
+                            lines.push(`## ${pr.label} — error`, "```text", pr.error, "```", "");
+                        }
+                        else if (pr.match) {
+                            lines.push(`## ${pr.label} — OK`, "```text", `SHA: ${pr.sha}`, "```", "");
+                        }
+                        else {
+                            lines.push(`## ${pr.label} — MISMATCH`, "```text", `left:  ${pr.leftSha}`, `right: ${pr.rightSha}`, "```", "");
+                        }
+                    }
+                    mdParts.push(lines.join("\n"));
+                }
+            }
+            if (args.format === "json") {
+                return jsonRespond({ parity: results });
+            }
+            return mdParts.join("\n\n---\n\n");
+        },
+    });
+}