@arii/boomtick-mcp 0.3.3

package/src/agents/pr-consolidation.prompt.md

@@ -0,0 +1,32 @@
+# PR Consolidation Guidelines
+
+## Objective
+Identify and propose consolidation of Pull Requests (PRs) that demonstrate high levels of functional or structural overlap to minimize code conflicts and streamline review cycles.
+
+## Analysis Criteria
+When reviewing the output of the `pr_overlap.py` analysis, evaluate candidates based on the following:
+
+### 1. File Overlap Density
+* **High Overlap:** PRs sharing identical files or logical components (e.g., core styles, shared UI components). These are primary candidates for consolidation.
+* **Context:** Check if the overlapping files are `design-tokens.ts` or `ci.yml`. Broad overlaps in infrastructure files might indicate a need for coordination rather than full consolidation.
+
+### 2. Functional Alignment (PR Titles & Descriptions)
+* Review the PR titles to determine if they share a common feature set (e.g., "Mobile UI" or "Home Page Performance").
+* Look for duplicate effort; if two PRs address the same UI improvement, they should be merged into a single branch.
+
+### 3. Linked Issue Dependency
+* Cross-reference the `(Fixes: #...)` metadata.
+* If multiple PRs resolve related issues (e.g., #101 and #102 are both part of the same UX audit), suggest consolidating these to ensure the full feature set is verified as one unit.
+
+## Actionable Recommendations
+For every identified cluster:
+1.  **Draft a Proposal:** Write a summary identifying the involved PRs and the common files shared.
+2.  **Assign Ownership:** Determine if one author should take lead on the consolidated PR, or if a pair-programming session is required.
+3.  **Conflict Resolution:** Explicitly state the plan for handling conflicting logic in shared files identified in the report.
+
+## Submission
+Present the findings in the following format:
+- **Cluster ID:** [List of PR Numbers]
+- **Primary Overlap:** [List of critical shared files]
+- **Recommendation:** [Merge/Coordinate/Separate]
+- **Rationale:** [Brief explanation referencing issues fixed]

package/src/agents/pr-writer.prompt.md

@@ -0,0 +1,13 @@
+You are the Boomtick PR Writer Agent.
+
+Your job is to create a reviewable replacement PR.
+
+Rules:
+- Be concise.
+- Be honest about failed checks.
+- Include the original PR number.
+- Include what broke.
+- Include what changed.
+- Include validation commands.
+- Include risk notes.
+- Open as draft unless told otherwise.

package/src/agents/repair-agent.prompt.md

@@ -0,0 +1,18 @@
+You are the Boomtick Repair Agent.
+
+Your job is to make the smallest safe repair.
+
+Rules:
+- Create a repair branch.
+- Preserve the intent of the original PR.
+- Preserve newer changes from the base branch.
+- Do not refactor unrelated code.
+- Do not remove tests.
+- Do not weaken validation.
+- Do not invent features.
+- Stop if conflict risk is high.
+
+Before committing:
+- Ensure no conflict markers remain.
+- Ensure changed files are expected.
+- Run validation tools.

package/src/agents/repo-context.prompt.md

@@ -0,0 +1,20 @@
+You are the BoomTick Repo Context Agent.
+
+Your job is to gather context before repair.
+
+Rules:
+- Do not edit files.
+- Do not create branches.
+- Do not guess repo behavior.
+- Use `package.json` scripts and existing routes as source of truth.
+- Reference `.agent-context.json` (generated by `scripts/build-repo-context.py`) for a high-level static snapshot of the project structure and scripts.
+- For dynamic state (changed files, CI logs, workflows), use MCP tools (`get_changed_files`, `read_ci_logs`, `gh audit-pr`).
+- Identify affected files, routes, tests, and likely validation commands.
+
+Output:
+- changed files
+- affected routes
+- relevant scripts (referencing `package.json` in `.agent-context.json`)
+- CI failures (consult `read_ci_logs` or `gh audit-pr`)
+- likely cause
+- repair risk

package/src/agents/verifier-agent.prompt.md

@@ -0,0 +1,22 @@
+You are the Boomtick Verifier Agent.
+
+Your job is to prove whether the repair is safe.
+
+Run the appropriate commands based on changed files.
+
+Required:
+- install
+- lint
+- test
+- build
+
+Conditional:
+- Playwright for UI/routes/browser behavior
+- Lighthouse for performance/accessibility/SEO-sensitive changes
+
+Output:
+- commands run
+- pass/fail status
+- error summaries
+- report paths
+- remaining risks

package/src/config.ts

@@ -0,0 +1,113 @@
+import dotenv from "dotenv";
+import path from "path";
+import fs from "fs";
+import { fileURLToPath } from "url";
+import { execSync } from "child_process";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+dotenv.config({
+  path: path.resolve(__dirname, "../.env"),
+  quiet: true
+});
+
+function getGithubToken(): string | undefined {
+  if (process.env.GITHUB_TOKEN) {
+    return process.env.GITHUB_TOKEN;
+  }
+  try {
+    const token = execSync("gh auth token", { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    if (token) {
+      return token;
+    }
+  } catch (e) { /* ignore to allow fallback */ }
+  return undefined;
+}
+
+let cachedDynamicConfig: any = null;
+
+/**
+ * Explicitly initializes dynamic configuration from the Python CLI.
+ * Should be called once during server startup.
+ */
+export function initializeConfig() {
+  if (cachedDynamicConfig !== null) {
+    return cachedDynamicConfig;
+  }
+
+  try {
+    // Attempt to load core properties from the Python CLI to avoid duplication
+    const cmd = `td-cli config view`;
+    const output = execSync(cmd, {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    cachedDynamicConfig = JSON.parse(output);
+    return cachedDynamicConfig;
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    const errorPrefix = `CRITICAL: Failed to load dynamic config from Python CLI. Ensure Python 3 is installed and cli is in your PYTHONPATH. Details: ${message}`;
+
+    if (process.env.NODE_ENV === "development" || process.env.CI === "true") {
+      throw new Error(errorPrefix);
+    } else {
+      console.warn(errorPrefix);
+    }
+    // Set an empty object to prevent repeated attempts if initialization fails in non-blocking mode
+    cachedDynamicConfig = {};
+  }
+  return cachedDynamicConfig;
+}
+
+function findRepoRoot() {
+  if (process.env.BOOMTICK_REPO_PATH) {
+    return process.env.BOOMTICK_REPO_PATH;
+  }
+
+  // Traverse up to find workspace.json or .git
+  let current = __dirname;
+  while (current !== path.parse(current).root) {
+    if (fs.existsSync(path.join(current, "workspace.json")) || fs.existsSync(path.join(current, ".git"))) {
+      return current;
+    }
+    current = path.dirname(current);
+  }
+  // Fallback to the monolithic relative path if discovery fails
+  return path.resolve(__dirname, "../../../");
+}
+
+export const config = {
+  get githubToken() { return getGithubToken(); },
+  get githubOwner() {
+    if (process.env.GITHUB_OWNER) return process.env.GITHUB_OWNER;
+    const repoString = cachedDynamicConfig?.github_repo;
+    if (typeof repoString !== "string" || !repoString.includes("/")) {
+      throw new Error("GITHUB_OWNER must be set via environment variable or project_config.json");
+    }
+    return repoString.split("/")[0];
+  },
+  get githubRepo() {
+    if (process.env.GITHUB_REPO) return process.env.GITHUB_REPO;
+    const repoString = cachedDynamicConfig?.github_repo;
+    if (typeof repoString !== "string" || !repoString.includes("/")) {
+      throw new Error("GITHUB_REPO must be set via environment variable or project_config.json");
+    }
+    return repoString.split("/")[1];
+  },
+  get repoPath() {
+    return findRepoRoot();
+  },
+  get defaultBaseBranch() {
+    return process.env.DEFAULT_BASE_BRANCH || cachedDynamicConfig?.base_branch?.split("/").pop() || "main";
+  },
+  get viteBasePath() {
+    const path = process.env.VITE_BASE_PATH || cachedDynamicConfig?.vite_base_path;
+    if (!path) {
+      throw new Error("VITE_BASE_PATH must be set via environment variable or project_config.json");
+    }
+    return path;
+  },
+  get ghPath() {
+    return process.env.GH_PATH || cachedDynamicConfig?.gh_path || "gh";
+  }
+};

package/src/evals/run-evals.ts

@@ -0,0 +1,40 @@
+import { healthHandler, HealthCheckInputSchema } from "../mcp/tools.js";
+import { searchOpenPrsHandler, SearchOpenPrsInputSchema } from "../tools/github.search_open_prs.js";
+import { getPackageScriptsHandler, GetPackageScriptsInputSchema } from "../tools/repo.get_package_scripts.js";
+
+async function runEvals() {
+  console.log("Starting Boomtick MCP Evaluations...");
+
+  try {
+    console.log("\n1. Health Check:");
+    try {
+      const health = await healthHandler({ checkDeep: false });
+      console.log(JSON.stringify(health, null, 2));
+    } catch (e) {
+      console.log("Health check failed:", e instanceof Error ? e.message : String(e));
+    }
+
+    console.log("\n2. Repository Scripts:");
+    try {
+      const scripts = await getPackageScriptsHandler({ filter: "" });
+      console.log(`Found ${Object.keys(scripts.scripts).length} scripts.`);
+    } catch (e) {
+      console.log("Repository scripts fetch failed:", e instanceof Error ? e.message : String(e));
+    }
+
+    console.log("\n3. GitHub PR Search (Dry Run):");
+    try {
+      const prs = await searchOpenPrsHandler({ state: "open", includeDrafts: true, limit: 100 });
+      console.log(`Found ${prs.prs.length} open PRs.`);
+    } catch (e) {
+      console.log("GitHub search failed (likely due to environment/auth):", e instanceof Error ? e.message : String(e));
+    }
+
+    console.log("\nEvaluations complete.");
+  } catch (error) {
+    console.error("\nEvaluation failed:", error);
+    process.exit(1);
+  }
+}
+
+runEvals();

package/src/index.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { BoomtickMCPServer } from "./mcp/server.js";
+import { initializeConfig } from "./config.js";
+
+// Initialize configuration once at startup
+initializeConfig();
+
+const server = new BoomtickMCPServer();
+server.run().catch((error) => {
+  console.error("Fatal error running server:", error);
+  process.exit(1);
+});

package/src/lib/error_utils.ts

@@ -0,0 +1,8 @@
+/**
+ * Sanitizes stderr from CLI commands to prevent implementation detail leakage
+ * in error messages returned to the AI agent.
+ */
+export function sanitizeError(stderr: string): string {
+  // Take first line and truncate to 200 chars to balance detail vs security
+  return (stderr.split("\n")[0] || "Unknown error").slice(0, 200);
+}

package/src/lib/git.ts

@@ -0,0 +1,41 @@
+import { runCommand } from "./shell.js";
+import { config } from "../config.js";
+import path from "path";
+import fs from "fs/promises";
+
+function validatePrNumber(value: unknown): number {
+  const prNumber = Number(value);
+
+  if (!Number.isInteger(prNumber) || prNumber <= 0) {
+    throw new Error("Invalid PR number");
+  }
+
+  return prNumber;
+}
+
+export async function createWorktree(branch: string, prNumber: number): Promise<string> {
+  const safePrNumber = validatePrNumber(prNumber);
+
+  const workspaceRoot = "/tmp/boomtick-worktrees";
+  // nosemgrep
+  const worktreePath = path.join(workspaceRoot, `boomtick-mcp-rescue-${safePrNumber}`);
+
+  // Clean up if exists
+  try {
+    await fs.rm(worktreePath, { recursive: true, force: true });
+    await runCommand("git", ["worktree", "prune"]);
+  } catch (e) { /* ignore if no previous worktree */ }
+
+  const result = await runCommand("git", ["worktree", "add", "-b", `repair-pr-${prNumber}-${Date.now()}`, worktreePath, branch]);
+
+  if (result.exitCode !== 0) {
+    throw new Error(`Failed to create worktree: ${result.stderr}`);
+  }
+
+  return worktreePath;
+}
+
+export async function removeWorktree(worktreePath: string): Promise<void> {
+  await runCommand("git", ["worktree", "remove", "--force", worktreePath]);
+  await runCommand("git", ["worktree", "prune"]);
+}

package/src/lib/result.ts

@@ -0,0 +1,28 @@
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+
+export interface ToolResult extends CallToolResult {
+  isError?: boolean;
+}
+
+export function createSuccessResult(data: any): ToolResult {
+  return {
+    content: [
+      {
+        type: "text",
+        text: typeof data === "string" ? data : JSON.stringify(data, null, 2),
+      },
+    ],
+  };
+}
+
+export function createErrorResult(message: string): ToolResult {
+  return {
+    content: [
+      {
+        type: "text",
+        text: message,
+      },
+    ],
+    isError: true,
+  };
+}

package/src/lib/shell.test.ts

@@ -0,0 +1,11 @@
+import { describe, it, expect } from "vitest";
+import path from "path";
+
+// Simple test to verify environment and vitest setup
+describe("Basic Environment", () => {
+  it("should have a valid repo path", () => {
+    const repoPath = process.env.BOOMTICK_REPO_PATH || "/app";
+    expect(repoPath).toBeDefined();
+    expect(path.isAbsolute(repoPath)).toBe(true);
+  });
+});

package/src/lib/shell.ts

@@ -0,0 +1,118 @@
+import { spawn } from "child_process";
+import { config } from "../config.js";
+import path from "path";
+import fs from "fs";
+
+export const ALLOWED_COMMANDS = {
+  git: "git",
+  gh: "gh",
+  "td-cli": "td-cli",
+  pnpm: "pnpm",
+  ls: "ls",
+  rm: "rm",
+  mkdir: "mkdir",
+  cp: "cp",
+  python3: "python3"
+} as const;
+
+export type AllowedCommand = keyof typeof ALLOWED_COMMANDS;
+
+export interface ShellResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number | null;
+  durationMs: number;
+  command: string;
+}
+
+export async function runCommand(
+  cmd: string,
+  args: string[],
+  options: { cwd?: string; timeout?: number; env?: Record<string, string> } = {}
+): Promise<ShellResult> {
+  if (!(cmd in ALLOWED_COMMANDS)) {
+    throw new Error(`Command not allowed: ${cmd}`);
+  }
+
+  const safeCmd = cmd as AllowedCommand;
+
+  const start = Date.now();
+  const timeout = options.timeout || 60000;
+
+  // Resolve path for 'gh' or 'td-cli' if specified
+  let finalCmd = ALLOWED_COMMANDS[safeCmd] as string;
+  if (safeCmd === "gh") {
+    finalCmd = config.ghPath;
+  } else if (safeCmd === "td-cli") {
+    // If we have a repo-relative .venv, prioritize it
+    const venvBin = path.join(config.repoPath, ".venv", "bin", "td-cli");
+    const localVenvBin = path.join(process.cwd(), ".venv", "bin", "td-cli");
+    const parentVenvBin = path.join(config.repoPath, "..", ".venv", "bin", "td-cli");
+
+    // In standalone mode, config.repoPath is the boomtick-pkg root.
+    // We check common venv locations to ensure we call the isolated binary.
+    if (fs.existsSync(venvBin)) {
+      finalCmd = venvBin;
+    } else if (fs.existsSync(localVenvBin)) {
+      finalCmd = localVenvBin;
+    } else if (fs.existsSync(parentVenvBin)) {
+      finalCmd = parentVenvBin;
+    }
+  }
+
+  const env = {
+    ...process.env,
+    ...options.env,
+    GH_TOKEN: config.githubToken,
+    GITHUB_TOKEN: config.githubToken
+  };
+
+  return new Promise((resolve, reject) => {
+    // nosemgrep
+    const child = spawn(finalCmd, args, {
+      cwd: options.cwd || config.repoPath,
+      env
+    });
+
+    let stdout = "";
+    let stderr = "";
+
+    child.stdout.on("data", (data) => {
+      stdout += data.toString();
+    });
+
+    child.stderr.on("data", (data) => {
+      stderr += data.toString();
+    });
+
+    const timer = setTimeout(() => {
+      child.kill();
+      reject(new Error(`Command timed out: ${cmd} ${args.join(" ")}`));
+    }, timeout);
+
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      const durationMs = Date.now() - start;
+
+      // Redact token from output
+      if (config.githubToken) {
+        const redact = (str: string) => str.replace(new RegExp(config.githubToken!, "g"), "REDACTED");
+        stdout = redact(stdout);
+        stderr = redact(stderr);
+      }
+
+      resolve({
+        stdout,
+        stderr,
+        exitCode: code,
+        durationMs,
+        command: `${cmd} ${args.join(" ")}`
+      });
+    });
+
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+  });
+}

package/src/lib/td-cli.ts

@@ -0,0 +1,38 @@
+import { runCommand } from "../lib/shell.js";
+
+export interface TDCliResponse {
+  status: string;
+  message?: string;
+  [key: string]: any;
+}
+
+function tryParseJson(text: string): TDCliResponse | null {
+  try {
+    return JSON.parse(text) as TDCliResponse;
+  } catch {
+    return null;
+  }
+}
+
+export async function runTDCli(args: string[]): Promise<TDCliResponse> {
+  const result = await runCommand("td-cli", args);
+  const stdout = result.stdout.trim();
+  const output = stdout.startsWith("{") ? tryParseJson(stdout) : null;
+
+  // Handle structured errors (status: "error") regardless of exit code
+  if (output?.status === "error") {
+    throw new Error(`td-cli returned error: ${output.message ?? "Unknown error"}`);
+  }
+
+  // Handle non-zero exit codes (shell failure)
+  if (result.exitCode !== 0) {
+    throw new Error(`td-cli command failed (${args.join(" ")}): ${result.stderr || stdout}`);
+  }
+
+  // Ensure we have a valid JSON response for successful exit
+  if (!output) {
+    throw new Error(`td-cli returned non-JSON output with exit code 0: ${stdout}`);
+  }
+
+  return output;
+}

package/src/lib/test-utils.ts

@@ -0,0 +1,23 @@
+import { vi } from "vitest";
+
+/**
+ * Shared test utilities for boomtick-mcp
+ */
+
+/**
+ * Ensures JULES_API_KEY is set in the environment for tests that require it.
+ * Should be called in beforeEach.
+ */
+export function setupTestEnv() {
+  vi.stubEnv("JULES_API_KEY", "test-key");
+}
+
+/**
+ * Resets the test environment.
+ * Should be called in afterEach.
+ */
+export function teardownTestEnv() {
+  vi.unstubAllEnvs();
+  // Explicitly delete to satisfy strict isolation requirements if vi.unstubAllEnvs is not enough
+  delete process.env.JULES_API_KEY;
+}