chore(release): add publication preflight

AlbinoGeek · AlbinoGeek · commit 5aec1a2c3bb0 · 2026-04-26T13:00:30.000-07:00
Prepare 2.3.4 with generated tool schemas, a line-coverage gate, and clean-tree checks before tagging.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -28,18 +28,13 @@ jobs:
       - name: Lint and format check
         run: bun run check
 
+      - name: Tool schema snapshot check
+        run: bun run schema:tools:check
+
       - name: Unit tests with coverage
         run: |
           bun run test:coverage 2>&1 | tee /tmp/coverage.txt
-          node -e "
-            const out = require('fs').readFileSync('/tmp/coverage.txt', 'utf8');
-            const m = out.match(/all files[^\|]*\|\s*([\d.]+)/i);
-            if (!m) { console.log('No coverage summary found — skipping threshold check.'); process.exit(0); }
-            const pct = parseFloat(m[1]);
-            const min = 80;
-            if (pct < min) { process.stderr.write('Coverage ' + pct.toFixed(1) + '% is below minimum ' + min + '%\n'); process.exit(1); }
-            console.log('Coverage OK: ' + pct.toFixed(1) + '%');
-          "
+          bun run coverage:check /tmp/coverage.txt 80
 
       - name: Assert Node.js version
         run: node -e "const v=+process.version.slice(1).split('.')[0]; if(v<22)process.exit(1)"
diff --git a/AGENTS.md b/AGENTS.md
@@ -36,6 +36,7 @@ IDEs injecting this as context: do not re-link from rules.
 | [`src/server/git-cherry-pick-tool.ts`](src/server/git-cherry-pick-tool.ts) | `git_cherry_pick` — mutating |
 | [`src/server/git-reset-soft-tool.ts`](src/server/git-reset-soft-tool.ts) | `git_reset_soft` — soft-reset; mutating |
 | [`src/server/presets-resource.ts`](src/server/presets-resource.ts) | `rethunk-git://presets` resource |
+| [`src/server/tool-parameter-schemas.ts`](src/server/tool-parameter-schemas.ts) | `buildToolParameterSchemaDocument`, `captureToolParameterSchemas`; backs `tool-parameters.schema.json` |
 | [`src/repo-paths.ts`](src/repo-paths.ts) | `resolvePathForRepo`, `assertRelativePathUnderTop`, `isStrictlyUnderGitTop` |
 
 ## Changing contracts
@@ -47,7 +48,7 @@ IDEs injecting this as context: do not re-link from rules.
 
 ## Validate + CI
 
-Local: `bun run build` | `bun run check` | `bun run test`. CI ([`ci.yml`](.github/workflows/ci.yml)) runs same on PRs + `main` after `bun install --frozen-lockfile`, 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 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)).
 
 Optional [`.githooks/`](.githooks): `bun run setup-hooks` once per clone. pre-commit=`check`; pre-push=frozen install + build + check + test.
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,24 @@
 
 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.3.4] — 2026-04-26
+
+Publication-prep patch for the `absoluteGitRoots` line.
+
+### Added
+
+- **`tool-parameters.schema.json`** — generated JSON Schema snapshot for every registered tool parameter surface, plus `bun run schema:tools` / `bun run schema:tools:check`.
+- **`git_parity` absolute-root regression coverage** — sibling clone batches are now covered directly.
+
+### Fixed
+
+- **CI coverage gate** now checks `% Lines` from Bun's coverage table instead of accidentally reading `% Funcs`.
+
+### Documentation
+
+- **`HUMANS.md`** — added sibling-clone `absoluteGitRoots` examples for `git_status` and `git_parity`.
+- **`docs/mcp-tools.md`** — clarified direct `git_push` use for already-committed work and `git_parity` sibling-clone batches.
+
 ## [2.3.3] — 2026-04-21
 
 ### Added
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -17,8 +17,12 @@ bun install
 bun run build       # rimraf dist && tsc → dist/server.js, dist/server/*.js, dist/repo-paths.js
 bun run check       # Biome lint + format check
 bun run check:fix   # auto-fix with Biome
+bun run schema:tools       # regenerate tool-parameters.schema.json
+bun run schema:tools:check # verify the generated tool schema is current
+bun run publish:preflight  # clean-tree release gate before tagging
 bun run test        # bun test src/
 bun run test:coverage  # bun test src/ --coverage
+bun run coverage:check /tmp/coverage.txt 80  # validate Bun coverage output captured with tee
 bun run setup-hooks    # one-time per clone: wire .githooks/
 ```
 
@@ -62,15 +66,17 @@ One logical unit per commit. Max ~7 files. Split by theme, not by file count.
 1. `bun install --frozen-lockfile`
 2. `bun run build`
 3. `bun run check` (Biome)
-4. `bun run test:coverage` + 80% line coverage threshold assertion
-5. Prerelease `npm pack` artifact uploaded (90-day retention)
+4. `bun run schema:tools:check`
+5. `bun run test:coverage` + `bun run coverage:check /tmp/coverage.txt 80`
+6. Prerelease `npm pack` artifact uploaded (90-day retention)
 
 Match the CI steps locally before opening a PR.
 
 ## Pull request checklist
 
 - [ ] `bun run build` passes.
 - [ ] `bun run check` passes (no Biome errors).
+- [ ] `bun run schema:tools:check` passes.
 - [ ] `bun run test` passes.
 - [ ] Any new tool has a corresponding `*.test.ts` file.
 - [ ] `docs/mcp-tools.md` updated if the public tool surface changed.
diff --git a/HUMANS.md b/HUMANS.md
@@ -53,6 +53,22 @@ With **multiple MCP file roots**, the server picks a root whose git toplevel def
 
 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)).
 
+## Tool parameter schema artifact
+
+The package ships **`tool-parameters.schema.json`**, a generated JSON Schema snapshot of every registered tool's parameter schema. Maintainers regenerate it with:
+
+```bash
+bun run schema:tools
+```
+
+CI and `prepublishOnly` use:
+
+```bash
+bun run schema:tools:check
+```
+
+This artifact is for inspection, drift checks, and clients that want an offline schema snapshot. Runtime MCP schema discovery remains the source of truth for connected clients.
+
 **Layouts:**
 
 1. **Wrapped (recommended):** `{ "schemaVersion": "1", "presets": { "<name>": { ... } } }`.
@@ -128,6 +144,14 @@ Tag pushes run [`.github/workflows/release.yml`](.github/workflows/release.yml):
 
 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"`).
 
+Before tagging, run the clean-tree preflight from the release commit:
+
+```bash
+bun run publish:preflight
+```
+
+It verifies the `package.json` version has a matching `CHANGELOG.md` section, generated tool schemas are current, build/check/coverage pass, and `npm pack --dry-run` includes the expected package files.
+
 ### 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`**):
diff --git a/biome.json b/biome.json
@@ -23,6 +23,6 @@
     }
   },
   "files": {
-    "includes": ["src/**/*", "*.json", "*.md"]
+    "includes": ["src/**/*", "scripts/**/*", "*.json", "*.md", "!tool-parameters.schema.json"]
   }
 }
diff --git a/bun.lock b/bun.lock
diff --git a/docs/mcp-tools.md b/docs/mcp-tools.md
@@ -32,6 +32,8 @@ Pass **`format: "json"`** on any tool for structured JSON instead of markdown (d
 
 Tool JSON bodies are minified and contain only the payload — no `rethunkGitMcp` envelope. Current `MCP_JSON_FORMAT_VERSION` is **`"3"`**; server + format version are discoverable via MCP `initialize`. Payload keys (`groups`, `inventories`, `parity`, `roots`) are stable within a given format version. Preset-related responses may include **`presetSchemaVersion`**.
 
+The package also ships **`tool-parameters.schema.json`**, generated from the registered Zod parameter schemas via `bun run schema:tools`. Connected MCP clients should still prefer live schema discovery from `initialize` / tool listing; the artifact is for offline inspection and drift checks.
+
 ### v2/v3 field omission (consumer contract)
 
 To keep responses compact, **optional fields are omitted when they would be empty, `null`, or `false`** — they are not emitted as `null`. Consumers must test for *presence*, not compare to `null`.
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@rethunk/mcp-multi-root-git",
-  "version": "2.3.3",
+  "version": "2.3.4",
   "description": "MCP stdio server: multi-root git status, inventory, and HEAD parity checks. Generic tools usable by any workspace.",
   "type": "module",
   "private": false,
@@ -11,6 +11,7 @@
   "files": [
     "dist",
     "git-mcp-presets.schema.json",
+    "tool-parameters.schema.json",
     "docs/install.md",
     "docs/mcp-tools.md",
     "AGENTS.md",
@@ -31,9 +32,13 @@
     "build": "rimraf dist && tsc",
     "check": "biome check .",
     "check:fix": "biome check --write .",
+    "coverage:check": "bun scripts/check-coverage.ts",
+    "schema:tools": "bun scripts/generate-tool-parameters-schema.ts",
+    "schema:tools:check": "bun scripts/generate-tool-parameters-schema.ts --check",
+    "publish:preflight": "bun scripts/publish-preflight.ts",
     "test": "bun test src/",
     "test:coverage": "bun test src/ --coverage",
-    "prepublishOnly": "bun run build && bun run check && bun run test",
+    "prepublishOnly": "bun run schema:tools:check && bun run build && bun run check && bun run test",
     "setup-hooks": "git config core.hooksPath .githooks"
   },
   "keywords": [
diff --git a/scripts/check-coverage.ts b/scripts/check-coverage.ts
@@ -0,0 +1,29 @@
+import { readFileSync } from "node:fs";
+
+import { parseAllFilesLineCoverage } from "../src/server/coverage.js";
+
+function main(): void {
+  const file = process.argv[2];
+  const min = Number.parseFloat(process.argv[3] ?? "80");
+  if (!file) {
+    process.stderr.write("Usage: bun scripts/check-coverage.ts <coverage-output-file> [min]\n");
+    process.exit(2);
+  }
+
+  const coverage = parseAllFilesLineCoverage(readFileSync(file, "utf8"));
+  if (coverage == null) {
+    process.stderr.write("No All files line coverage summary found.\n");
+    process.exit(1);
+  }
+  if (coverage < min) {
+    process.stderr.write(
+      `Line coverage ${coverage.toFixed(2)}% is below minimum ${min.toFixed(2)}%\n`,
+    );
+    process.exit(1);
+  }
+  console.log(`Line coverage OK: ${coverage.toFixed(2)}%`);
+}
+
+if (import.meta.main) {
+  main();
+}
diff --git a/scripts/generate-tool-parameters-schema.ts b/scripts/generate-tool-parameters-schema.ts
@@ -0,0 +1,33 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { buildToolParameterSchemaDocument } from "../src/server/tool-parameter-schemas.js";
+
+const OUTPUT_PATH = resolve(
+  join(fileURLToPath(new URL("..", import.meta.url)), "tool-parameters.schema.json"),
+);
+
+function renderSchema(): string {
+  return `${JSON.stringify(buildToolParameterSchemaDocument(), null, 2)}\n`;
+}
+
+function main(): void {
+  const next = renderSchema();
+  if (process.argv.includes("--check")) {
+    const current = readFileSync(OUTPUT_PATH, "utf8");
+    if (current !== next) {
+      process.stderr.write(`${OUTPUT_PATH} is out of date. Run bun run schema:tools.\n`);
+      process.exit(1);
+    }
+    console.log(`${OUTPUT_PATH} is up to date.`);
+    return;
+  }
+
+  writeFileSync(OUTPUT_PATH, next);
+  console.log(`Wrote ${OUTPUT_PATH}`);
+}
+
+if (import.meta.main) {
+  main();
+}
diff --git a/scripts/publish-preflight.ts b/scripts/publish-preflight.ts
@@ -0,0 +1,65 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+
+import { parseAllFilesLineCoverage } from "../src/server/coverage.js";
+
+function run(command: string, args: string[]): string {
+  console.log(`$ ${[command, ...args].join(" ")}`);
+  const result = spawnSync(command, args, {
+    encoding: "utf8",
+    maxBuffer: 20 * 1024 * 1024,
+  });
+  if (result.stdout) process.stdout.write(result.stdout);
+  if (result.stderr) process.stderr.write(result.stderr);
+  if (result.status !== 0) {
+    process.exit(result.status ?? 1);
+  }
+  return `${result.stdout}${result.stderr}`;
+}
+
+function assertCleanTree(): void {
+  const status = run("git", ["status", "--porcelain"]);
+  if (status.trim()) {
+    process.stderr.write("Working tree is dirty; commit or stash changes before publishing.\n");
+    process.exit(1);
+  }
+}
+
+function assertVersionHasChangelog(): string {
+  const pkg = JSON.parse(readFileSync("package.json", "utf8")) as { version?: string };
+  if (!pkg.version) {
+    process.stderr.write("package.json has no version.\n");
+    process.exit(1);
+  }
+  const changelog = readFileSync("CHANGELOG.md", "utf8");
+  if (!changelog.includes(`## [${pkg.version}]`)) {
+    process.stderr.write(`CHANGELOG.md is missing a ## [${pkg.version}] entry.\n`);
+    process.exit(1);
+  }
+  return pkg.version;
+}
+
+function runCoverageGate(): void {
+  const output = run("bun", ["run", "test:coverage"]);
+  writeFileSync("/tmp/mcp-multi-root-git-publish-coverage.txt", output);
+  const coverage = parseAllFilesLineCoverage(output);
+  if (coverage == null) {
+    process.stderr.write("No All files line coverage summary found.\n");
+    process.exit(1);
+  }
+  if (coverage < 80) {
+    process.stderr.write(`Line coverage ${coverage.toFixed(2)}% is below minimum 80.00%\n`);
+    process.exit(1);
+  }
+  console.log(`Line coverage OK: ${coverage.toFixed(2)}%`);
+}
+
+assertCleanTree();
+const version = assertVersionHasChangelog();
+run("bun", ["install", "--frozen-lockfile"]);
+run("bun", ["run", "schema:tools:check"]);
+run("bun", ["run", "build"]);
+run("bun", ["run", "check"]);
+runCoverageGate();
+run("npm", ["pack", "--dry-run"]);
+console.log(`Publish preflight OK for v${version}.`);
diff --git a/src/server/coverage-check.test.ts b/src/server/coverage-check.test.ts
@@ -0,0 +1,22 @@
+import { describe, expect, test } from "bun:test";
+
+import { parseAllFilesLineCoverage } from "./coverage.js";
+
+describe("parseAllFilesLineCoverage", () => {
+  test("reads % Lines rather than the first percentage column", () => {
+    const output = `
+-------------------------------------|---------|---------|-------------------
+File                                 | % Funcs | % Lines | Uncovered Line #s
+-------------------------------------|---------|---------|-------------------
+All files                            |   90.64 |   80.47 |
+ src/foo.ts                          |  100.00 |  100.00 |
+-------------------------------------|---------|---------|-------------------
+`;
+
+    expect(parseAllFilesLineCoverage(output)).toBe(80.47);
+  });
+
+  test("returns null when the coverage table is absent", () => {
+    expect(parseAllFilesLineCoverage("271 pass\n0 fail\n")).toBeNull();
+  });
+});
diff --git a/src/server/coverage.ts b/src/server/coverage.ts
@@ -0,0 +1,22 @@
+export function parseAllFilesLineCoverage(output: string): number | null {
+  const rows = output
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line.includes("|"));
+  const header = rows.find((line) => /^File\s*\|/i.test(line));
+  if (!header) return null;
+
+  const columns = header.split("|").map((column) => column.trim().toLowerCase());
+  const lineIndex = columns.indexOf("% lines");
+  if (lineIndex === -1) return null;
+
+  const allFiles = rows.find((line) => /^All files\s*\|/i.test(line));
+  if (!allFiles) return null;
+
+  const cells = allFiles.split("|").map((cell) => cell.trim());
+  const raw = cells[lineIndex];
+  if (!raw) return null;
+
+  const value = Number.parseFloat(raw);
+  return Number.isFinite(value) ? value : null;
+}
diff --git a/src/server/git-parity-tool.test.ts b/src/server/git-parity-tool.test.ts
@@ -20,8 +20,13 @@ function gitInitMain(dir: string): void {
 
 function commitFile(dir: string, filename: string, content: string): string {
   writeFileSync(join(dir, filename), content);
-  execFileSync("git", ["add", filename], { cwd: dir, stdio: "ignore" });
-  execFileSync("git", ["commit", "-m", `add ${filename}`], { cwd: dir, stdio: "ignore" });
+  const env = {
+    ...process.env,
+    GIT_AUTHOR_DATE: "2026-01-01T00:00:00Z",
+    GIT_COMMITTER_DATE: "2026-01-01T00:00:00Z",
+  };
+  execFileSync("git", ["add", filename], { cwd: dir, env, stdio: "ignore" });
+  execFileSync("git", ["commit", "-m", `add ${filename}`], { cwd: dir, env, stdio: "ignore" });
   return execFileSync("git", ["rev-parse", "HEAD"], { cwd: dir, encoding: "utf8" }).trim();
 }
 
diff --git a/src/server/tool-parameter-schemas.test.ts b/src/server/tool-parameter-schemas.test.ts
diff --git a/src/server/tool-parameter-schemas.ts b/src/server/tool-parameter-schemas.ts
diff --git a/src/server/tool-parameters.test.ts b/src/server/tool-parameters.test.ts
diff --git a/tool-parameters.schema.json b/tool-parameters.schema.json

Original file line number	Diff line number	Diff line change
`@@ -23,6 +23,6 @@`
`23`	`23`	`}`
`24`	`24`	`},`
`25`	`25`	`"files": {`
`26`		`- "includes": ["src/*/", ".json", ".md"]`
	`26`	`+ "includes": ["src/*/", "scripts/*/", ".json", ".md", "!tool-parameters.schema.json"]`
`27`	`27`	`}`
`28`	`28`	`}`