@rethunk/mcp-multi-root-git 2.0.1 → 2.2.0

package/dist/server/git-diff-summary-tool.js

@@ -0,0 +1,319 @@
+import { matchesGlob } from "node:path";
+import { z } from "zod";
+import { gitTopLevel, isSafeGitUpstreamToken, spawnGitAsync } from "./git.js";
+import { jsonRespond, spreadDefined, spreadWhen } from "./json.js";
+import { requireGitAndRoots } from "./roots.js";
+import { WorkspacePickSchema } from "./schemas.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const DEFAULT_EXCLUDE_PATTERNS = [
+    "*.lock",
+    "*.lockb",
+    "bun.lock",
+    "package-lock.json",
+    "yarn.lock",
+    "pnpm-lock.yaml",
+    "*.min.js",
+    "*.min.css",
+    "vendor/**",
+    "node_modules/**",
+    "dist/**",
+];
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Parse `git diff --stat` output into per-file stats.
+ * Format: " path/to/file | N ++++---"
+ * Final line: " N files changed, N insertions(+), N deletions(-)"
+ */
+function parseStatOutput(stat) {
+    const result = new Map();
+    for (const line of stat.split("\n")) {
+        // Skip the summary line and blank lines
+        if (!line.includes("|"))
+            continue;
+        const pipeIdx = line.indexOf("|");
+        const filePart = line.slice(0, pipeIdx).trim();
+        const statPart = line.slice(pipeIdx + 1).trim();
+        // statPart looks like "5 ++---" or "3 +++", count + and -
+        const additions = (statPart.match(/\+/g) ?? []).length;
+        const deletions = (statPart.match(/-/g) ?? []).length;
+        result.set(filePart, { additions, deletions });
+    }
+    return result;
+}
+/**
+ * Parse `git diff` output into per-file chunks.
+ * Splits on "diff --git a/..." lines.
+ */
+function parseDiffOutput(diff) {
+    const chunks = [];
+    // Each file section starts with "diff --git"
+    const parts = diff.split(/(?=^diff --git )/m);
+    for (const part of parts) {
+        if (!part.startsWith("diff --git "))
+            continue;
+        const firstNewline = part.indexOf("\n");
+        const header = firstNewline >= 0 ? part.slice(0, firstNewline) : part;
+        const body = firstNewline >= 0 ? part.slice(firstNewline + 1) : "";
+        chunks.push({ header, body });
+    }
+    return chunks;
+}
+/**
+ * Extract file paths and status from a diff chunk header + body.
+ * Header: "diff --git a/old b/new"
+ * Body may contain "rename from", "rename to", "new file mode", "deleted file mode".
+ */
+function extractFileInfo(header, body) {
+    // Parse "diff --git a/X b/Y"
+    const headerMatch = /^diff --git a\/(.+) b\/(.+)$/.exec(header);
+    const aPath = headerMatch?.[1] ?? "";
+    const bPath = headerMatch?.[2] ?? aPath;
+    let status = "modified";
+    let oldPath;
+    if (/^new file mode/m.test(body)) {
+        status = "added";
+    }
+    else if (/^deleted file mode/m.test(body)) {
+        status = "deleted";
+    }
+    else if (/^rename from /m.test(body)) {
+        status = "renamed";
+        const fromMatch = /^rename from (.+)$/m.exec(body);
+        oldPath = fromMatch?.[1];
+    }
+    const path = status === "deleted" ? aPath : bPath;
+    return { path, oldPath, status };
+}
+/**
+ * Truncate diff body to at most `maxLines` lines (counting only hunk content lines).
+ * Returns { text, truncated }.
+ */
+function truncateDiffBody(body, maxLines) {
+    const lines = body.split("\n");
+    if (lines.length <= maxLines) {
+        return { text: body, truncated: false };
+    }
+    return { text: lines.slice(0, maxLines).join("\n"), truncated: true };
+}
+/** Check whether a file path matches any of the given glob patterns. */
+function matchesAnyPattern(filePath, patterns) {
+    const normalized = filePath.replace(/\\/g, "/");
+    for (const pattern of patterns) {
+        if (matchesGlob(normalized, pattern))
+            return true;
+        // Also match just the basename against simple patterns (e.g. "*.lock")
+        const basename = normalized.split("/").at(-1) ?? normalized;
+        if (matchesGlob(basename, pattern))
+            return true;
+    }
+    return false;
+}
+/** Build the diff args array from the `range` parameter. */
+function buildDiffArgs(range) {
+    if (range === undefined || range === "") {
+        return { ok: true, args: [] };
+    }
+    const normalized = range.trim().toLowerCase();
+    if (normalized === "staged" || normalized === "cached") {
+        return { ok: true, args: ["--cached"] };
+    }
+    if (normalized === "head") {
+        return { ok: true, args: ["HEAD"] };
+    }
+    // Range like "A..B", "A...B", or a single ref
+    // Split on ".." or "..." separators to validate each token
+    const separatorMatch = /^(.+?)(\.{2,3})(.+)$/.exec(range.trim());
+    if (separatorMatch) {
+        const [, left, sep, right] = separatorMatch;
+        if (!isSafeGitUpstreamToken(left ?? "") || !isSafeGitUpstreamToken(right ?? "")) {
+            return { ok: false, error: `unsafe_range_token: ${range}` };
+        }
+        return { ok: true, args: [`${left}${sep}${right}`] };
+    }
+    // Single ref
+    if (!isSafeGitUpstreamToken(range.trim())) {
+        return { ok: false, error: `unsafe_range_token: ${range}` };
+    }
+    return { ok: true, args: [range.trim()] };
+}
+/** Human-readable label for the range. */
+function rangeLabel(range, diffArgs) {
+    if (!range || range === "")
+        return "unstaged changes";
+    if (diffArgs[0] === "--cached")
+        return "staged changes";
+    return range;
+}
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+export function registerGitDiffSummaryTool(server) {
+    server.addTool({
+        name: "git_diff_summary",
+        description: "Structured, token-efficient diff viewer. Returns per-file diffs with additions/deletions, " +
+            "truncated to configurable line limits, with noise files (lock files, dist, etc.) excluded by default. " +
+            "Use `range` to target staged, HEAD, or any revision range. See docs/mcp-tools.md.",
+        annotations: {
+            readOnlyHint: true,
+        },
+        parameters: WorkspacePickSchema.extend({
+            range: z
+                .string()
+                .optional()
+                .describe('Diff range. Examples: "staged", "HEAD~3..HEAD", "main...feature". ' +
+                "Default: unstaged changes."),
+            fileFilter: z
+                .string()
+                .optional()
+                .describe('Glob pattern to restrict output to matching files, e.g. "*.ts", "src/**".'),
+            maxLinesPerFile: z
+                .number()
+                .int()
+                .min(1)
+                .max(2000)
+                .optional()
+                .default(50)
+                .describe("Max diff lines to include per file. Default: 50."),
+            maxFiles: z
+                .number()
+                .int()
+                .min(1)
+                .max(500)
+                .optional()
+                .default(30)
+                .describe("Max files to include in output. Default: 30."),
+            excludePatterns: z
+                .array(z.string())
+                .optional()
+                .describe("Glob patterns to exclude. Defaults to common noise: lock files, dist, vendor, etc."),
+        }),
+        execute: async (args) => {
+            // --- Standard prelude ---
+            const pre = requireGitAndRoots(server, args, undefined);
+            if (!pre.ok)
+                return jsonRespond(pre.error);
+            const rootInput = pre.roots[0];
+            if (!rootInput)
+                return jsonRespond({ error: "no_workspace_root" });
+            const gitTop = gitTopLevel(rootInput);
+            if (!gitTop) {
+                return jsonRespond({ error: "not_a_git_repository", path: rootInput });
+            }
+            // --- Build git diff args ---
+            const diffArgsResult = buildDiffArgs(args.range);
+            if (!diffArgsResult.ok) {
+                return jsonRespond({ error: diffArgsResult.error });
+            }
+            const diffArgs = diffArgsResult.args;
+            // --- Run git diff --stat ---
+            const statResult = await spawnGitAsync(gitTop, ["diff", "--stat", ...diffArgs]);
+            if (!statResult.ok) {
+                return jsonRespond({
+                    error: "git_diff_failed",
+                    detail: (statResult.stderr || statResult.stdout).trim(),
+                });
+            }
+            const statMap = parseStatOutput(statResult.stdout);
+            // --- Run git diff ---
+            const diffResult = await spawnGitAsync(gitTop, ["diff", ...diffArgs]);
+            if (!diffResult.ok) {
+                return jsonRespond({
+                    error: "git_diff_failed",
+                    detail: (diffResult.stderr || diffResult.stdout).trim(),
+                });
+            }
+            // --- Parse diff chunks ---
+            const chunks = parseDiffOutput(diffResult.stdout);
+            const totalFiles = chunks.length;
+            // --- Apply excludePatterns and fileFilter ---
+            const excludePatterns = args.excludePatterns !== undefined ? args.excludePatterns : DEFAULT_EXCLUDE_PATTERNS;
+            const excludedFiles = [];
+            const includedChunks = [];
+            for (const chunk of chunks) {
+                const { path: filePath } = extractFileInfo(chunk.header, chunk.body);
+                if (matchesAnyPattern(filePath, excludePatterns)) {
+                    excludedFiles.push(filePath);
+                    continue;
+                }
+                if (args.fileFilter && !matchesAnyPattern(filePath, [args.fileFilter])) {
+                    continue;
+                }
+                includedChunks.push(chunk);
+            }
+            // --- Truncate to maxFiles ---
+            const maxFiles = args.maxFiles ?? 30;
+            const maxLinesPerFile = args.maxLinesPerFile ?? 50;
+            const truncatedFileCount = includedChunks.length > maxFiles ? includedChunks.length - maxFiles : 0;
+            const processedChunks = includedChunks.slice(0, maxFiles);
+            // --- Build FileDiff entries ---
+            let totalAdditions = 0;
+            let totalDeletions = 0;
+            const files = [];
+            for (const chunk of processedChunks) {
+                const { path: filePath, oldPath, status } = extractFileInfo(chunk.header, chunk.body);
+                const stat = statMap.get(filePath) ?? { additions: 0, deletions: 0 };
+                totalAdditions += stat.additions;
+                totalDeletions += stat.deletions;
+                const { text: diffText, truncated } = truncateDiffBody(chunk.body, maxLinesPerFile);
+                files.push({
+                    path: filePath,
+                    status,
+                    additions: stat.additions,
+                    deletions: stat.deletions,
+                    ...spreadDefined("oldPath", oldPath),
+                    truncated,
+                    diff: diffText,
+                });
+            }
+            const rangeStr = rangeLabel(args.range, diffArgs);
+            const summary = {
+                range: rangeStr,
+                totalFiles,
+                totalAdditions,
+                totalDeletions,
+                files,
+                ...spreadWhen(truncatedFileCount > 0, { truncatedFiles: truncatedFileCount }),
+                ...spreadWhen(excludedFiles.length > 0, { excludedFiles }),
+            };
+            // --- Format output ---
+            if (args.format === "json") {
+                return jsonRespond(summary);
+            }
+            // --- Markdown output ---
+            const lines = [];
+            lines.push(`# Diff: ${rangeStr}`, "");
+            // Summary line
+            const fileWord = totalFiles === 1 ? "file" : "files";
+            let summaryLine = `**${totalFiles} ${fileWord} changed** (+${totalAdditions} \u2212${totalDeletions})`;
+            if (excludedFiles.length > 0) {
+                const excWord = excludedFiles.length === 1 ? "file" : "files";
+                summaryLine += `, ${excludedFiles.length} ${excWord} excluded (${excludedFiles.join(", ")})`;
+            }
+            if (truncatedFileCount > 0) {
+                summaryLine += `, ${truncatedFileCount} more file(s) omitted (maxFiles=${maxFiles})`;
+            }
+            lines.push(summaryLine, "");
+            for (const file of files) {
+                // Section header
+                const statusTag = file.status !== "modified" ? `, ${file.status}` : "";
+                const renameTag = file.oldPath ? ` (from ${file.oldPath})` : "";
+                lines.push(`## ${file.path}${renameTag} (+${file.additions} \u2212${file.deletions}${statusTag})`);
+                if (file.diff) {
+                    lines.push("```diff", file.diff.trimEnd(), "```");
+                }
+                else {
+                    lines.push("_(no diff content)_");
+                }
+                if (file.truncated) {
+                    lines.push(`_(diff truncated at ${maxLinesPerFile} lines)_`);
+                }
+                lines.push("");
+            }
+            return lines.join("\n");
+        },
+    });
+}

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

@@ -0,0 +1,276 @@
+import { basename } from "node:path";
+import { z } from "zod";
+import { asyncPool, GIT_SUBPROCESS_PARALLELISM, gitTopLevel, spawnGitAsync } from "./git.js";
+import { jsonRespond, spreadDefined, spreadWhen } from "./json.js";
+import { requireGitAndRoots } from "./roots.js";
+import { WorkspacePickSchema } from "./schemas.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const MAX_COMMITS_HARD_CAP = 500;
+const DEFAULT_MAX_COMMITS = 50;
+const DEFAULT_SINCE = "7.days";
+// Field separator written by git into stdout — we use git's %x01 (SOH) escape.
+// The format string itself is safe ASCII; git emits the byte.
+const FIELD_SEP_OUT = "\x01"; // what git outputs (SOH)
+const RECORD_SEP_OUT = "\x02"; // what git outputs (STX) — used as record-START marker
+// git log --pretty tformat: sha7, shaFull, subject, author, email, ISO date, relative date.
+// %x02 is placed at the START of each record (tformat adds \n as terminator after each).
+// Splitting stdout on \x02 then gives empty-first-chunk + one chunk per commit,
+// each structured as:  <fields>\x01\n\n <shortstat text>\n
+// Fields are separated by %x01; the trailing \x01 before \n leaves one empty last field (ignored).
+const PRETTY_FORMAT = "%x02%h%x01%H%x01%s%x01%aN%x01%aE%x01%aI%x01%ar%x01";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Parse a shortstat line like "3 files changed, 12 insertions(+), 5 deletions(-)"
+ * Returns undefined when the line doesn't match (e.g. empty diff).
+ */
+function parseShortstat(line) {
+    const m = /(\d+) files? changed(?:, (\d+) insertions?\(\+\))?(?:, (\d+) deletions?\(-\))?/.exec(line);
+    if (!m)
+        return undefined;
+    return {
+        filesChanged: parseInt(m[1] ?? "0", 10),
+        insertions: parseInt(m[2] ?? "0", 10),
+        deletions: parseInt(m[3] ?? "0", 10),
+    };
+}
+/**
+ * Fetch the current branch name (or detached HEAD fallback).
+ */
+async function gitCurrentBranch(cwd, branchArg) {
+    if (branchArg?.trim())
+        return branchArg.trim();
+    const r = await spawnGitAsync(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]);
+    if (r.ok)
+        return r.stdout.trim();
+    return "HEAD";
+}
+/**
+ * Run git log for a single repo root and return structured data.
+ */
+async function runGitLog(opts) {
+    const { top, since, paths, grep, author, maxCommits, branch } = opts;
+    // Resolve branch first (needed for output metadata).
+    const resolvedBranch = await gitCurrentBranch(top, branch);
+    // Fetch one extra commit to detect truncation.
+    const fetchLimit = maxCommits + 1;
+    const logArgs = [
+        "log",
+        `--pretty=tformat:${PRETTY_FORMAT}`,
+        "--shortstat",
+        `-n`,
+        String(fetchLimit),
+        `--since=${since}`,
+    ];
+    if (branch?.trim()) {
+        logArgs.push(branch.trim());
+    }
+    if (grep?.trim()) {
+        logArgs.push(`--grep=${grep.trim()}`, "-i");
+    }
+    if (author?.trim()) {
+        logArgs.push(`--author=${author.trim()}`);
+    }
+    if (paths.length > 0) {
+        logArgs.push("--", ...paths);
+    }
+    const r = await spawnGitAsync(top, logArgs);
+    if (!r.ok) {
+        return {
+            error: "git_log_failed",
+            path: top,
+        };
+    }
+    // Parse output.
+    // git log --pretty=tformat:%x02<fields>%x01 --shortstat emits, per commit:
+    //   \x02<fields separated by SOH>\x01\n\n <shortstat line>\n
+    // The \x02 is a record-START marker. Splitting on \x02 gives an empty first chunk
+    // followed by one chunk per commit. Each chunk is:
+    //   <fields>\x01\n\n <shortstat>\n
+    const raw = r.stdout;
+    const recordChunks = raw.split(RECORD_SEP_OUT).slice(1); // drop leading empty
+    const allCommits = [];
+    for (const chunk of recordChunks) {
+        if (!chunk.trim())
+            continue;
+        // Fields before the first newline; shortstat (if any) follows blank line.
+        const newlineIdx = chunk.indexOf("\n");
+        const fieldsPart = newlineIdx >= 0 ? chunk.slice(0, newlineIdx) : chunk;
+        const statPart = newlineIdx >= 0 ? chunk.slice(newlineIdx + 1) : "";
+        const fields = fieldsPart.split(FIELD_SEP_OUT);
+        const [sha7, shaFull, subject, authorName, email, date, ageRelative] = fields;
+        if (!sha7 || !shaFull)
+            continue;
+        const stat = parseShortstat(statPart);
+        const commit = {
+            sha7: sha7.trim(),
+            shaFull: shaFull.trim(),
+            subject: subject?.trim() ?? "",
+            author: authorName?.trim() ?? "",
+            email: email?.trim() ?? "",
+            date: date?.trim() ?? "",
+            ageRelative: ageRelative?.trim() ?? "",
+            ...spreadDefined("filesChanged", stat?.filesChanged),
+            ...spreadDefined("insertions", stat?.insertions),
+            ...spreadDefined("deletions", stat?.deletions),
+        };
+        allCommits.push(commit);
+    }
+    const truncated = allCommits.length > maxCommits;
+    const commits = truncated ? allCommits.slice(0, maxCommits) : allCommits;
+    const omittedCount = truncated ? allCommits.length - maxCommits : 0;
+    return {
+        workspace_root: top,
+        repo: basename(top),
+        branch: resolvedBranch,
+        commits,
+        truncated,
+        omittedCount,
+    };
+}
+// ---------------------------------------------------------------------------
+// Markdown rendering
+// ---------------------------------------------------------------------------
+function renderLogMarkdown(group, filterSummary) {
+    const lines = [];
+    lines.push(`### ${group.repo} (${group.branch})${filterSummary ? `  —  ${filterSummary}` : ""}`);
+    lines.push(`_root: ${group.workspace_root}_`);
+    lines.push("");
+    if (group.commits.length === 0) {
+        lines.push("_(no commits match)_");
+    }
+    else {
+        for (const c of group.commits) {
+            lines.push(`- \`${c.sha7}\`  ${c.ageRelative}  ${c.subject}  —  ${c.author}`);
+        }
+    }
+    if (group.truncated) {
+        lines.push("");
+        lines.push(`_(truncated — ${group.omittedCount} more commit(s) not shown; lower \`since\` or \`maxCommits\`)_`);
+    }
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+export function registerGitLogTool(server) {
+    server.addTool({
+        name: "git_log",
+        description: "Path-filtered, time-windowed read-only `git log` across one or more workspace roots. " +
+            "Returns structured commit history with author, date, subject, and optional diff stats. " +
+            "See docs/mcp-tools.md.",
+        annotations: {
+            readOnlyHint: true,
+        },
+        parameters: WorkspacePickSchema.extend({
+            since: z
+                .string()
+                .optional()
+                .describe("Passed to `git log --since=`. Accepts ISO timestamps or git relative forms like " +
+                "`48.hours` or `2.weeks.ago`. Default: `7.days`."),
+            paths: z
+                .array(z.string())
+                .optional()
+                .describe("Limit to commits touching these paths (passed as `-- <paths>`)."),
+            grep: z
+                .string()
+                .optional()
+                .describe("Filter commits whose message matches this regex (git `--grep`, case-insensitive)."),
+            author: z
+                .string()
+                .optional()
+                .describe("Filter by author name or email (passed as `--author=`)."),
+            maxCommits: z
+                .number()
+                .int()
+                .min(1)
+                .max(MAX_COMMITS_HARD_CAP)
+                .optional()
+                .default(DEFAULT_MAX_COMMITS)
+                .describe(`Maximum commits to return per root (hard cap ${MAX_COMMITS_HARD_CAP}). Default ${DEFAULT_MAX_COMMITS}.`),
+            branch: z.string().optional().describe("Ref/branch to log from. Default: HEAD."),
+        }),
+        execute: async (args) => {
+            const pre = requireGitAndRoots(server, args, undefined);
+            if (!pre.ok)
+                return jsonRespond(pre.error);
+            // Validate `since` — reject obvious injection attempts (newlines, semicolons, shell chars).
+            const rawSince = (args.since?.trim() ?? DEFAULT_SINCE) || DEFAULT_SINCE;
+            if (/[\n\r;|&`$<>]/.test(rawSince)) {
+                return jsonRespond({ error: "invalid_since", since: rawSince });
+            }
+            // Validate paths — reject anything with null bytes or shell meta.
+            // Use charCodeAt(0) === 0 for the null byte to avoid a biome lint on control chars in regex.
+            const rawPaths = args.paths ?? [];
+            for (const p of rawPaths) {
+                if (p.split("").some((c) => c.charCodeAt(0) === 0) || /[\n\r;|&`$<>]/.test(p)) {
+                    return jsonRespond({ error: "invalid_paths", path: p });
+                }
+            }
+            const maxCommits = Math.min(args.maxCommits ?? DEFAULT_MAX_COMMITS, MAX_COMMITS_HARD_CAP);
+            // Fan out across roots.
+            const jobs = pre.roots.map((rootInput) => ({ rootInput }));
+            const results = await asyncPool(jobs, GIT_SUBPROCESS_PARALLELISM, async ({ rootInput }) => {
+                const top = gitTopLevel(rootInput);
+                if (!top) {
+                    return { _error: true, workspace_root: rootInput, error: "not_a_git_repo" };
+                }
+                const r = await runGitLog({
+                    top,
+                    since: rawSince,
+                    paths: rawPaths,
+                    grep: args.grep,
+                    author: args.author,
+                    maxCommits,
+                    branch: args.branch,
+                });
+                if ("error" in r) {
+                    return { _error: true, workspace_root: rootInput, error: r.error };
+                }
+                return { _error: false, ...r };
+            });
+            // Build filter summary string for markdown.
+            const filterParts = [`since: ${rawSince}`];
+            if (rawPaths.length > 0)
+                filterParts.push(`paths: ${rawPaths.join(", ")}`);
+            if (args.grep)
+                filterParts.push(`grep: ${args.grep}`);
+            if (args.author)
+                filterParts.push(`author: ${args.author}`);
+            const filterSummary = filterParts.join(" | ");
+            if (args.format === "json") {
+                const groups = results.map((r) => {
+                    if (r._error) {
+                        return {
+                            workspace_root: r.workspace_root,
+                            repo: basename(r.workspace_root),
+                            branch: "",
+                            commits: [],
+                            ...spreadWhen(true, { error: r.error }),
+                        };
+                    }
+                    const { _error: _e, ...rest } = r;
+                    return {
+                        ...rest,
+                        ...spreadWhen(r.truncated, { truncated: true, omittedCount: r.omittedCount }),
+                    };
+                });
+                return jsonRespond({ groups });
+            }
+            // Markdown
+            const mdChunks = ["# Git log"];
+            for (const r of results) {
+                if (r._error) {
+                    mdChunks.push(`### ${r.workspace_root}\n_error: ${r.error}_`);
+                    continue;
+                }
+                const { _error: _e, ...group } = r;
+                mdChunks.push(renderLogMarkdown(group, filterSummary));
+            }
+            return mdChunks.join("\n\n");
+        },
+    });
+}