@bugmole/cli 0.4.0

package/src/mcp/server.test.ts

@@ -0,0 +1,1220 @@
+/**
+ * Comprehensive unit tests for MCP server tools
+ *
+ * These tests ensure all MCP tools handle errors gracefully and never crash the server.
+ * Every tool must be tested for:
+ * - Valid inputs
+ * - Invalid inputs
+ * - Missing files
+ * - Path resolution issues
+ * - Error handling
+ */
+
+import { describe, it, before, after } from "node:test";
+import { strict as assert } from "node:assert";
+import fs from "node:fs";
+import path from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+// Import the functions we need to test
+// Note: We'll need to export these from server.ts for testing
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Mock config for testing
+// The "dashboard" journey / "home" node fixture that bugmole_write_ui_audit
+// tests below assert against. Re-seeded immediately before that describe
+// block, not just once in the outer before(): every test in this file
+// shares one testDir, and the bugmole_explore test in between legitimately
+// rebuilds journeys.graph.json's nodes from a scanned source tree ("Rebuild
+// the sitemap from the current source tree on every run" in explorer.ts) --
+// which has always dropped this fixture's "home" node by the time these
+// tests run. That dangling "dashboard" -> "home" reference used to go
+// unnoticed because nothing validated it; readJourneyGraph now repairs it
+// (see AGENTS.md's "Journey graph reads and mutations must tolerate legacy
+// corruption"), correctly pruning it -- which surfaced this pre-existing
+// test-isolation gap instead of a bug in that repair.
+function seedDashboardJourney(testDir: string) {
+  fs.writeFileSync(
+    path.join(testDir, "spec", "journeys.graph.json"),
+    JSON.stringify({
+      version: 2,
+      projectId: "default",
+      journeys: [{
+        id: "dashboard",
+        name: "Dashboard",
+        actor: "user",
+        nodeIds: ["home"],
+        edgeIds: [],
+        revision: 1,
+        status: "draft",
+      }],
+      nodes: [{ id: "home", title: "Home", kind: "screen", route: "/" }],
+      edges: [],
+    }),
+  );
+}
+
+function createTestConfig(testDir: string) {
+  return {
+    name: "Bugmole MCP Test",
+    runtime: {
+      env: "test",
+      tenant: "test",
+      artifacts_dir: path.join(testDir, "artifacts"),
+      spec_dir: path.join(testDir, "spec"),
+    },
+    mcp: {
+      enabled: true,
+      host: "127.0.0.1",
+      port: 3187,
+    },
+  };
+}
+
+describe("MCP Server Tools", () => {
+  let testDir: string;
+  let cfg: any;
+
+  it("formats tool results for MCP clients", async () => {
+    const { formatMcpToolResult } = await import("./server.js");
+    assert.deepEqual(
+      formatMcpToolResult({ status: "success", auditId: "parity-rerun" }),
+      {
+        content: [{
+          type: "text",
+          text: '{"status":"success","auditId":"parity-rerun"}',
+        }],
+      },
+    );
+  });
+
+  it("serves wrapped tool results over HTTP and rejects invalid JSON-RPC requests", async () => {
+    const { startMcpServer } = await import("./server.js");
+    const httpServer = await startMcpServer({
+      ...createTestConfig(testDir),
+      mcp: { ...createTestConfig(testDir).mcp, port: 0 },
+    }, { forceHttp: true });
+    assert.ok(httpServer);
+    try {
+      const toolResponse = await fetch(`${httpServer.origin}/mcp`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          id: "http-tool",
+          method: "tools/call",
+          params: {
+            name: "bugmole_read_spec",
+            arguments: { filePath: "journeys.graph.json" },
+          },
+        }),
+      });
+      assert.equal(toolResponse.status, 200);
+      const toolBody = await toolResponse.json() as {
+        id: string;
+        result?: { content?: Array<{ type?: string; text?: string }> };
+      };
+      assert.equal(toolBody.id, "http-tool");
+      assert.equal(toolBody.result?.content?.[0]?.type, "text");
+      assert.equal(
+        (JSON.parse(toolBody.result?.content?.[0]?.text ?? "{}") as { content?: string }).content,
+        fs.readFileSync(path.join(testDir, "spec", "journeys.graph.json"), "utf8"),
+      );
+
+      const invalidResponse = await fetch(`${httpServer.origin}/mcp`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: "null",
+      });
+      assert.equal(invalidResponse.status, 200);
+      assert.deepEqual(await invalidResponse.json(), {
+        jsonrpc: "2.0",
+        id: null,
+        error: { code: -32600, message: "Invalid Request" },
+      });
+    } finally {
+      await httpServer.close();
+    }
+  });
+
+  before(() => {
+    // Create temporary test directory
+    testDir = path.join(tmpdir(), `bugmole-test-${Date.now()}`);
+    fs.mkdirSync(testDir, { recursive: true });
+    fs.mkdirSync(path.join(testDir, "spec"), { recursive: true });
+    fs.mkdirSync(path.join(testDir, "spec", "plans"), { recursive: true });
+    fs.mkdirSync(path.join(testDir, "artifacts"), { recursive: true });
+    seedDashboardJourney(testDir);
+
+    cfg = createTestConfig(testDir);
+  });
+
+  after(() => {
+    // Cleanup: remove test directory
+    if (fs.existsSync(testDir)) {
+      fs.rmSync(testDir, { recursive: true, force: true });
+    }
+  });
+
+  describe("bugmole_read_spec", () => {
+    it("should read existing spec file", async () => {
+      // Create test file
+      const testFile = path.join(testDir, "spec", "test.yaml");
+      const testContent = "test: content";
+      fs.writeFileSync(testFile, testContent);
+
+      // Import and test
+      const { readSpecFile } = await import("./server.js");
+      const result = readSpecFile("test.yaml", cfg);
+
+      assert.strictEqual(result.content, testContent);
+      assert.strictEqual(result.path, "test.yaml");
+      assert.strictEqual(result.size, testContent.length);
+    });
+
+    it("should handle file not found gracefully", async () => {
+      const { readSpecFile } = await import("./server.js");
+
+      try {
+        readSpecFile("nonexistent.yaml", cfg);
+        assert.fail("Should have thrown error");
+      } catch (error: any) {
+        // Should throw an error with helpful message
+        assert(error instanceof Error);
+        assert(error.message);
+        assert(
+          error.message.includes("Spec file not found") ||
+            error.message.includes("nonexistent.yaml") ||
+            error.message.includes("Tried"),
+        );
+      }
+    });
+
+    it("should resolve paths with spec/ prefix", async () => {
+      const testFile = path.join(testDir, "spec", "plans", "test.yaml");
+      const testContent = "plan: test";
+      fs.writeFileSync(testFile, testContent);
+
+      const { readSpecFile } = await import("./server.js");
+      const result = readSpecFile("plans/test.yaml", cfg);
+
+      assert.strictEqual(result.content, testContent);
+    });
+
+    it("should handle absolute paths", async () => {
+      const testFile = path.join(testDir, "spec", "absolute.yaml");
+      const testContent = "absolute: test";
+      fs.writeFileSync(testFile, testContent);
+
+      const { readSpecFile } = await import("./server.js");
+      const result = readSpecFile(testFile, cfg);
+
+      assert.strictEqual(result.content, testContent);
+    });
+
+    it("should try multiple path resolution strategies", async () => {
+      // Test that it tries multiple paths when file not found
+      const { readSpecFile } = await import("./server.js");
+
+      try {
+        readSpecFile("missing.yaml", cfg);
+        assert.fail("Should have thrown error");
+      } catch (error: any) {
+        // Error message should show multiple paths were tried
+        const errorMsg = error.message;
+        assert(errorMsg.includes("Tried"));
+        assert(errorMsg.includes("paths"));
+      }
+    });
+  });
+
+  describe("bugmole_write_spec", () => {
+    it("should write spec file successfully", async () => {
+      const { writeSpecFile } = await import("./server.js");
+      const content = "test: write content";
+
+      const result = writeSpecFile("write_test.yaml", content, cfg);
+
+      assert.strictEqual(result.success, true);
+      assert.strictEqual(result.path, "write_test.yaml");
+
+      // Verify file was created
+      const filePath = path.join(testDir, "spec", "write_test.yaml");
+      assert(fs.existsSync(filePath));
+      assert.strictEqual(fs.readFileSync(filePath, "utf-8"), content);
+    });
+
+    it("should create directory if it does not exist", async () => {
+      const { writeSpecFile } = await import("./server.js");
+      const content = "nested: content";
+
+      const result = writeSpecFile("nested/deep/test.yaml", content, cfg);
+
+      assert.strictEqual(result.success, true);
+
+      // Verify nested directory was created
+      const filePath = path.join(testDir, "spec", "nested", "deep", "test.yaml");
+      assert(fs.existsSync(filePath));
+    });
+
+    it("should handle invalid file paths", async () => {
+      const { writeSpecFile } = await import("./server.js");
+
+      // Should not crash on invalid paths
+      try {
+        writeSpecFile("", "content", cfg);
+        // Empty path might be handled or throw - either is acceptable
+      } catch (error: any) {
+        // If it throws, error should be clear
+        assert(error.message.length > 0);
+      }
+    });
+  });
+
+  describe("bugmole_report_progress", () => {
+    it("should create progress report file", async () => {
+      // We need to import callToolInternal or the actual function
+      // For now, test the directory structure
+      const progressDir = path.join(testDir, "artifacts", "progress_reports");
+      fs.mkdirSync(progressDir, { recursive: true });
+
+      const progressId = `progress_${Date.now()}`;
+      const progressPath = path.join(progressDir, `${progressId}.json`);
+      const progressData = {
+        id: progressId,
+        timestamp: new Date().toISOString(),
+        status: "working",
+        message: "Test progress",
+      };
+
+      fs.writeFileSync(progressPath, JSON.stringify(progressData, null, 2));
+
+      assert(fs.existsSync(progressPath));
+      const saved = JSON.parse(fs.readFileSync(progressPath, "utf-8"));
+      assert.strictEqual(saved.status, "working");
+    });
+
+    it("should handle all status types", async () => {
+      const statuses = ["working", "blocked", "completed"];
+
+      for (const status of statuses) {
+        // Test that each status is accepted
+        assert(["working", "blocked", "completed"].includes(status));
+      }
+    });
+  });
+
+  describe("bugmole_commit_response", () => {
+    it("should save commit response with all fields", async () => {
+      const commitDir = path.join(testDir, "artifacts", "cursor_commits");
+      fs.mkdirSync(commitDir, { recursive: true });
+
+      const commitId = `commit_${Date.now()}`;
+      const commitPath = path.join(commitDir, `${commitId}.json`);
+      const commitData = {
+        id: commitId,
+        timestamp: new Date().toISOString(),
+        payload: {
+          status: "ok",
+          summary: "Test commit",
+          next_steps: ["Step 1", "Step 2"],
+        },
+      };
+
+      fs.writeFileSync(commitPath, JSON.stringify(commitData, null, 2));
+
+      assert(fs.existsSync(commitPath));
+      const saved = JSON.parse(fs.readFileSync(commitPath, "utf-8"));
+      assert.strictEqual(saved.payload.status, "ok");
+      assert(Array.isArray(saved.payload.next_steps));
+      assert.strictEqual(saved.payload.next_steps.length, 2);
+    });
+
+    it("should always include next_steps as array", async () => {
+      // Test that next_steps is never undefined
+      const commitDir = path.join(testDir, "artifacts", "cursor_commits");
+      const commitId = `commit_${Date.now()}`;
+      const commitPath = path.join(commitDir, `${commitId}.json`);
+
+      const commitData = {
+        id: commitId,
+        timestamp: new Date().toISOString(),
+        payload: {
+          status: "ok",
+          summary: "Test",
+          next_steps: [], // Should always be array
+        },
+      };
+
+      fs.writeFileSync(commitPath, JSON.stringify(commitData, null, 2));
+      const saved = JSON.parse(fs.readFileSync(commitPath, "utf-8"));
+
+      assert("next_steps" in saved.payload);
+      assert(Array.isArray(saved.payload.next_steps));
+    });
+  });
+
+  describe("bugmole_explore", () => {
+    it("should discover application screens and update the journey graph", async () => {
+      const appDir = path.join(testDir, "app");
+      fs.mkdirSync(path.join(appDir, "settings"), { recursive: true });
+      fs.writeFileSync(
+        path.join(appDir, "page.tsx"),
+        `export default function Home() { return <a href="/settings">Settings</a>; }`,
+      );
+      fs.writeFileSync(
+        path.join(appDir, "settings", "page.tsx"),
+        `export default function Settings() { return <main>Settings</main>; }`,
+      );
+      const previousProjectDirectory = cfg.cursor_driver?.project_directory;
+      cfg.cursor_driver = { project_directory: testDir };
+
+      // Import the explore function
+      const { explore } = await import("../runtime/explorer.js");
+      const result = await explore(cfg, {
+        baseUrl: "http://localhost:8000",
+        maxDepth: 3,
+      });
+
+      assert.strictEqual(result.status, "success");
+      assert.strictEqual(result.screensDiscovered, 2);
+      assert.strictEqual(result.actionsDiscovered, 1);
+      assert.strictEqual(result.journeyGraphUpdated, true);
+      assert(result.message?.includes("Review the graph"));
+      assert(fs.existsSync(path.join(cfg.runtime.spec_dir, "journeys.graph.json")));
+      if (previousProjectDirectory === undefined) delete cfg.cursor_driver.project_directory;
+      else cfg.cursor_driver.project_directory = previousProjectDirectory;
+    });
+
+    it("should not crash on invalid baseUrl", async () => {
+      const { explore } = await import("../runtime/explorer.js");
+
+      // Should handle invalid URLs gracefully
+      const result = await explore(cfg, {
+        baseUrl: "invalid-url",
+        maxDepth: 1,
+      });
+
+      // Should return error, not crash
+      assert(result.status === "error" || result.status === "success");
+      assert(result.error || result.message);
+    });
+  });
+
+  describe("bugmole_plan", () => {
+    it("should handle missing journey gracefully", async () => {
+      const { plan } = await import("../runtime/planner.js");
+
+      try {
+        await plan(cfg, {
+          journeyId: "nonexistent_journey",
+          actor: "staff",
+        });
+        // Might succeed or fail, but should not crash
+      } catch (error: any) {
+        // If it throws, should be a clear error
+        assert(error.message.length > 0);
+      }
+    });
+  });
+
+  describe("bugmole_run", () => {
+    it("should handle missing plan gracefully", async () => {
+      const { execute } = await import("../runtime/executor.js");
+
+      try {
+        await execute(cfg, {
+          planId: "nonexistent_plan",
+          journeyId: "test",
+        });
+        // Might succeed or fail, but should not crash
+      } catch (error: any) {
+        // If it throws, should be a clear error
+        assert(error.message.length > 0);
+      }
+    });
+  });
+
+  describe("bugmole_propose_diff", () => {
+    it("should handle missing file gracefully", async () => {
+      const { proposeDiff } = await import("../runtime/diff-proposal.js");
+
+      try {
+        await proposeDiff(cfg, {
+          filePath: "nonexistent.yaml",
+          evidence: { test: "data" },
+          failures: [],
+        });
+        // Might succeed or fail, but should not crash
+      } catch (error: any) {
+        // If it throws, should be a clear error
+        assert(error.message.length > 0);
+      }
+    });
+
+    it("should handle invalid evidence gracefully", async () => {
+      const { proposeDiff } = await import("../runtime/diff-proposal.js");
+
+      try {
+        await proposeDiff(cfg, {
+          filePath: "test.yaml",
+          evidence: null as any,
+          failures: [],
+        });
+        // Might succeed or fail, but should not crash
+      } catch (error: any) {
+        // If it throws, should be a clear error
+        assert(error.message.length > 0);
+      }
+    });
+  });
+
+  describe("bugmole_review", () => {
+    it("should handle missing file gracefully", async () => {
+      const { review } = await import("../runtime/reviewer.js");
+
+      try {
+        await review(cfg, {
+          filePath: "nonexistent.yaml",
+          changeSummary: "Test change",
+          diff: "test diff",
+          evidence: { test: "data" },
+        });
+        // Might succeed or fail, but should not crash
+      } catch (error: any) {
+        // If it throws, should be a clear error
+        assert(error.message.length > 0);
+      }
+    });
+
+    it("should handle missing arguments gracefully", async () => {
+      const { review } = await import("../runtime/reviewer.js");
+
+      try {
+        await review(cfg, {
+          filePath: "test.yaml",
+          changeSummary: "",
+          diff: "",
+          evidence: {},
+        });
+        // Might succeed or fail, but should not crash
+      } catch (error: any) {
+        // If it throws, should be a clear error
+        assert(error.message.length > 0);
+      }
+    });
+  });
+
+  describe("bugmole_report", () => {
+    it("should handle missing runId gracefully", async () => {
+      const { generateReport } = await import("../runtime/reporter.js");
+
+      try {
+        await generateReport(cfg, {
+          runId: "nonexistent_run",
+          format: "json",
+        });
+        // Might succeed or fail, but should not crash
+      } catch (error: any) {
+        // If it throws, should be a clear error
+        assert(error.message.length > 0);
+      }
+    });
+
+    it("should handle different formats gracefully", async () => {
+      const { generateReport } = await import("../runtime/reporter.js");
+
+      const formats = ["json", "markdown"];
+      for (const format of formats) {
+        try {
+          await generateReport(cfg, {
+            runId: "test_run",
+            format: format as "json" | "markdown",
+          });
+          // Might succeed or fail, but should not crash
+        } catch (error: any) {
+          // If it throws, should be a clear error
+          assert(error.message.length > 0);
+        }
+      }
+    });
+  });
+
+  describe("bugmole_write_ui_audit", () => {
+    before(() => seedDashboardJourney(testDir));
+
+    it("writes a dashboard-consumable JSON audit with stable totals", async () => {
+      const { callTool } = await import("./server.js");
+      // Runtime evidence must reference a real artifact; write one before
+      // the audit claims it, exercising the same existence check a bogus
+      // location would fail.
+      const evidenceKey = "projects/default/ui-audits-evidence/open-project.png";
+      const evidencePath = path.join(testDir, "artifacts", evidenceKey);
+      fs.mkdirSync(path.dirname(evidencePath), { recursive: true });
+      fs.writeFileSync(evidencePath, Buffer.from([0]));
+      const audit = {
+        schemaVersion: 1,
+        auditId: "dashboard-home",
+        requestedFlow: "Open the dashboard",
+        journeyId: "dashboard",
+        journeyRevision: 1,
+        flowStatus: "exhausted",
+        exploredNodeIds: ["home"],
+        exploredEdgeIds: [],
+        summary: {
+          total: 1,
+          implemented: 0,
+          partiallyImplemented: 1,
+          notImplemented: 0,
+        },
+        screens: [
+          {
+            screenId: "home",
+            route: "/",
+            controls: [
+              {
+                controlId: "open-project",
+                label: "Open project",
+                kind: "button",
+                status: "Partially implemented",
+                destinationOrHandler: "openProject()",
+                evidence: [{ type: "runtime", description: "Button responds to click", location: evidenceKey }],
+                missingBehavior: ["Project selection is not persisted"],
+              },
+            ],
+          },
+        ],
+        highestPriorityMissingImplementations: [],
+        blockedVerification: [],
+      };
+
+      const result = await callTool({ name: "bugmole_write_ui_audit", arguments: { audit } }, cfg);
+      assert.equal(result.status, "success");
+      assert.equal(result.schema, "bugmole://spec/app-ui-audit.schema.json");
+      const filePath = path.join(
+        testDir,
+        "artifacts",
+        "projects",
+        "default",
+        "ui-audits",
+        "dashboard-home.json",
+      );
+      assert.deepEqual(JSON.parse(fs.readFileSync(filePath, "utf8")), {
+        ...audit,
+        projectId: "default",
+      });
+    });
+
+    it("rejects runtime evidence without a location", async () => {
+      const { callTool } = await import("./server.js");
+      await assert.rejects(
+        callTool(
+          {
+            name: "bugmole_write_ui_audit",
+            arguments: {
+              audit: {
+                schemaVersion: 1,
+                auditId: "missing-location",
+                journeyId: "dashboard",
+                journeyRevision: 1,
+                flowStatus: "exhausted",
+                exploredNodeIds: ["home"],
+                exploredEdgeIds: [],
+                summary: { total: 1, implemented: 1, partiallyImplemented: 0, notImplemented: 0 },
+                screens: [
+                  {
+                    screenId: "home",
+                    controls: [
+                      {
+                        controlId: "open-project",
+                        label: "Open project",
+                        kind: "button",
+                        status: "Implemented",
+                        destinationOrHandler: "openProject()",
+                        evidence: [{ type: "runtime", description: "Trust me, it works" }],
+                        missingBehavior: [],
+                      },
+                    ],
+                  },
+                ],
+                highestPriorityMissingImplementations: [],
+                blockedVerification: [],
+              },
+            },
+          },
+          cfg,
+        ),
+        /runtime evidence without a location/,
+      );
+    });
+
+    it("rejects runtime evidence whose referenced artifact does not exist", async () => {
+      const { callTool } = await import("./server.js");
+      await assert.rejects(
+        callTool(
+          {
+            name: "bugmole_write_ui_audit",
+            arguments: {
+              audit: {
+                schemaVersion: 1,
+                auditId: "phantom-evidence",
+                journeyId: "dashboard",
+                journeyRevision: 1,
+                flowStatus: "exhausted",
+                exploredNodeIds: ["home"],
+                exploredEdgeIds: [],
+                summary: { total: 1, implemented: 1, partiallyImplemented: 0, notImplemented: 0 },
+                screens: [
+                  {
+                    screenId: "home",
+                    controls: [
+                      {
+                        controlId: "open-project",
+                        label: "Open project",
+                        kind: "button",
+                        status: "Implemented",
+                        destinationOrHandler: "openProject()",
+                        evidence: [
+                          {
+                            type: "runtime",
+                            description: "Captured a screenshot",
+                            location: "projects/default/ui-audits-evidence/does-not-exist.png",
+                          },
+                        ],
+                        missingBehavior: [],
+                      },
+                    ],
+                  },
+                ],
+                highestPriorityMissingImplementations: [],
+                blockedVerification: [],
+              },
+            },
+          },
+          cfg,
+        ),
+        /no artifact exists at that key/,
+      );
+    });
+
+    it("rejects inconsistent status totals", async () => {
+      const { callTool } = await import("./server.js");
+      await assert.rejects(
+        callTool(
+          {
+            name: "bugmole_write_ui_audit",
+            arguments: {
+              audit: {
+                schemaVersion: 1,
+                auditId: "invalid",
+                journeyId: "dashboard",
+                journeyRevision: 1,
+                flowStatus: "exhausted",
+                exploredNodeIds: ["home"],
+                exploredEdgeIds: [],
+                summary: {
+                  total: 0,
+                  implemented: 0,
+                  partiallyImplemented: 0,
+                  notImplemented: 0,
+                },
+                screens: [
+                  {
+                    screenId: "home",
+                    controls: [
+                      {
+                        controlId: "button",
+                        label: "Button",
+                        status: "Implemented",
+                        destinationOrHandler: "buttonHandler",
+                        evidence: [],
+                        missingBehavior: [],
+                      },
+                    ],
+                  },
+                ],
+                blockedVerification: [],
+                highestPriorityMissingImplementations: [],
+              },
+            },
+          },
+          cfg,
+        ),
+        /summary must match control status totals/,
+      );
+    });
+  });
+
+  describe("bugmole_write_ui_parity_audit", () => {
+    it("writes a scored reference/current parity artifact", async () => {
+      const { callTool } = await import("./server.js");
+      const audit = {
+        schemaVersion: 1,
+        auditId: "home-parity",
+        reference: { kind: "url", location: "https://reference.example/home" },
+        current: { kind: "url", location: "http://localhost:3020" },
+        summary: {
+          screensTotal: 1,
+          actionsTotal: 1,
+          visualDifferencePercent: 8,
+          interactionParityScore: 100,
+          apiParityScore: 88,
+          authenticationParityScore: 100,
+          fixedIssues: 2,
+          unresolvedIssues: 1,
+        },
+        flowMatrix: [
+          {
+            flowId: "home",
+            referenceScreen: "Home",
+            currentRoute: "/",
+            authState: "guest",
+            actions: ["Open project"],
+            status: "matched",
+          },
+        ],
+        comparisons: [
+          {
+            screenId: "home",
+            differencePercent: 8,
+            changedPixels: 10,
+            totalPixels: 100,
+            heatmap: "parity-output/heatmap.png",
+            mismatches: ["Card spacing differs by 4px"],
+          },
+        ],
+        issues: [
+          {
+            issueId: "home-card-spacing",
+            category: "visual",
+            status: "unresolved",
+            description: "Card spacing differs by 4px",
+          },
+        ],
+        fixPrompt: "Adjust home card spacing to match the reference.",
+        blockedVerification: [],
+      };
+      const result = await callTool(
+        { name: "bugmole_write_ui_parity_audit", arguments: { audit } },
+        cfg,
+      );
+
+      assert.equal(result.status, "success");
+      assert.equal(result.schema, "bugmole://spec/ui-parity-audit.schema.json");
+      assert.equal(
+        JSON.parse(
+          fs.readFileSync(
+            path.join(testDir, "artifacts/projects/default/ui-parity-audits/home-parity.json"),
+            "utf8",
+          ),
+        ).summary.visualDifferencePercent,
+        8,
+      );
+    });
+  });
+
+  describe("Error Handling", () => {
+    it("should wrap all tool calls in error handler", async () => {
+      // Test that callToolInternal is wrapped
+      // This ensures no tool can crash the server
+      const { callTool } = await import("./server.js");
+
+      // Call with invalid tool name
+      try {
+        await callTool(
+          {
+            name: "nonexistent_tool",
+            arguments: {},
+          },
+          cfg,
+        );
+        // Should throw error, not crash
+      } catch (error: any) {
+        assert(error.message.includes("Unknown tool") || error.message.length > 0);
+      }
+    });
+
+    it("should return JSON-RPC error format", async () => {
+      // Errors should be in JSON-RPC format
+      const { callTool } = await import("./server.js");
+
+      try {
+        await callTool(
+          {
+            name: "bugmole_read_spec",
+            arguments: { filePath: "nonexistent.yaml" },
+          },
+          cfg,
+        );
+        assert.fail("Should have thrown error");
+      } catch (error: any) {
+        // Error should have message
+        assert(error.message);
+        // Should not be a crash/exception that kills the server
+        assert(typeof error.message === "string");
+      }
+    });
+  });
+
+  describe("Resources", () => {
+    it("exposes first-class journey editing and continuation tools", async () => {
+      const { getTools } = await import("./server.js");
+      const names = getTools(cfg).map((tool) => tool.name);
+      for (const name of [
+        "bugmole_journey_list",
+        "bugmole_journey_get",
+        "bugmole_journey_create",
+        "bugmole_journey_add_step",
+        "bugmole_journey_add_transition",
+        "bugmole_journey_update",
+        "bugmole_journey_remove",
+        "bugmole_journey_next",
+        "bugmole_resolve_blocker",
+      ]) {
+        assert(names.includes(name), `missing MCP tool ${name}`);
+      }
+    });
+
+    it("should list available resources", async () => {
+      const { getResources } = await import("./server.js");
+      const resources = getResources(cfg);
+
+      assert(Array.isArray(resources));
+      assert(resources.length > 0);
+      // Should have standard resources
+      const resourceUris = resources.map((r) => r.uri);
+      assert(resourceUris.some((uri) => uri.includes("roles.yaml")));
+      assert(resourceUris.some((uri) => uri.includes("domain_rules.yaml")));
+      assert(resourceUris.includes("bugmole://guidance/app-ui-audit"));
+      assert(resourceUris.includes("bugmole://guidance/ui-parity-audit"));
+      assert(resourceUris.includes("bugmole://guidance/ui-reverse-engineering"));
+      assert(resourceUris.includes("bugmole://spec/ui-reverse-engineering.schema.json"));
+      assert(resourceUris.includes("bugmole://spec/design-dna.schema.json"));
+      assert(resourceUris.includes("bugmole://spec/ui-parity-audit.schema.json"));
+    });
+
+    it("should read the application UI audit guidance", async () => {
+      const { readResource } = await import("./server.js");
+      const result = await readResource({ uri: "bugmole://guidance/app-ui-audit" }, cfg);
+      const text = result.contents[0].text;
+
+      assert.match(text, /reproduce the requested user flow/);
+      assert.match(text, /screen-by-screen grouping/);
+      assert.match(text, /Implemented: the intended action works end-to-end/);
+      // The audit is the only task that populates the component library, so
+      // the component scan has to be part of its instructions.
+      assert.match(text, /bugmole_ui_re_start/);
+      assert.match(text, /stage `atoms`/);
+      assert.match(text, /do not invent components/i);
+    });
+
+    it("should read UI parity guidance without control-audit overlap", async () => {
+      const { readResource } = await import("./server.js");
+      const result = await readResource({ uri: "bugmole://guidance/ui-parity-audit" }, cfg);
+      const text = result.contents[0].text;
+
+      assert.match(text, /reference experience/);
+      assert.match(text, /flow matrix/);
+      assert.match(text, /bugmole_write_ui_parity_audit/);
+      assert.match(text, /does not replace the application UI audit/);
+    });
+
+    it("should read existing resource", async () => {
+      // Create a test resource file
+      const testFile = path.join(testDir, "spec", "roles.yaml");
+      const testContent = "roles: test";
+      fs.writeFileSync(testFile, testContent);
+
+      const { readResource } = await import("./server.js");
+      const result = await readResource({ uri: "bugmole://spec/roles.yaml" }, cfg);
+
+      assert(result.contents);
+      assert(Array.isArray(result.contents));
+      assert.strictEqual(result.contents[0].text, testContent);
+    });
+
+    it("should handle missing resource gracefully", async () => {
+      const { readResource } = await import("./server.js");
+
+      try {
+        await readResource({ uri: "bugmole://spec/nonexistent.yaml" }, cfg);
+        assert.fail("Should have thrown error");
+      } catch (error: any) {
+        assert(error.message.includes("not found") || error.message.includes("Resource"));
+      }
+    });
+
+    it("should handle invalid URI format", async () => {
+      const { readResource } = await import("./server.js");
+
+      try {
+        await readResource({ uri: "invalid://uri" }, cfg);
+        assert.fail("Should have thrown error");
+      } catch (error: any) {
+        assert(error.message.includes("Unknown resource URI"));
+      }
+    });
+  });
+
+  describe("Prompts", () => {
+    it("should list available prompts", async () => {
+      const { getPrompts } = await import("./server.js");
+      const prompts = getPrompts(cfg);
+
+      assert(Array.isArray(prompts));
+      // Should have at least one prompt
+      assert(prompts.length >= 0);
+      assert(prompts.some((prompt) => prompt.name === "app_ui_audit"));
+      assert(prompts.some((prompt) => prompt.name === "ui_parity_audit"));
+      assert(prompts.some((prompt) => prompt.name === "ui_reverse_engineering"));
+      assert(prompts.some((prompt) => prompt.name === "agent_task_execution"));
+    });
+
+    it("should return the application UI audit prompt", async () => {
+      const { getPrompt } = await import("./server.js");
+      const result = await getPrompt({ name: "app_ui_audit" }, cfg);
+      const text = result.messages[0].content.text;
+
+      assert.match(text, /every user-facing button, link, row, card/);
+      assert.match(text, /runtime or source-code evidence/);
+      assert.match(text, /highest-priority missing implementations/);
+    });
+
+    it("should return the UI parity audit prompt", async () => {
+      const { getPrompt } = await import("./server.js");
+      const result = await getPrompt({ name: "ui_parity_audit" }, cfg);
+      const text = result.messages[0].content.text;
+
+      assert.match(text, /flow matrix/);
+      assert.match(text, /visual, behavioral, backend, and authentication parity/);
+      assert.match(text, /bugmole_write_ui_parity_audit/);
+    });
+
+    it("should expose the agent task queue guidance", async () => {
+      const { readResource } = await import("./server.js");
+      const result = await readResource({ uri: "bugmole://guidance/agent-task-queue" }, cfg);
+      const text = result.contents[0].text;
+      assert.match(text, /bugmole_task_next/);
+      assert.match(text, /fresh parity artifact/);
+    });
+
+    it("should return the agent task execution prompt", async () => {
+      const { getPrompt } = await import("./server.js");
+      const result = await getPrompt({ name: "agent_task_execution" }, cfg);
+      const text = result.messages[0].content.text;
+      assert.match(text, /bugmole_task_next/);
+      assert.match(text, /fresh parity audit id and match score/);
+    });
+
+    it("should get prompt with arguments", async () => {
+      const { getPrompt } = await import("./server.js");
+
+      try {
+        await getPrompt(
+          {
+            name: "file_authoring",
+            arguments: {
+              filePath: "test.yaml",
+              filePurpose: "Test file",
+            },
+          },
+          cfg,
+        );
+        // Might succeed or fail depending on template existence
+      } catch (error: any) {
+        // If it throws, should be a clear error
+        assert(error.message.length > 0);
+      }
+    });
+
+    it("should handle unknown prompt gracefully", async () => {
+      const { getPrompt } = await import("./server.js");
+
+      try {
+        await getPrompt({ name: "nonexistent_prompt" }, cfg);
+        assert.fail("Should have thrown error");
+      } catch (error: any) {
+        assert(error.message.includes("Unknown prompt"));
+      }
+    });
+  });
+
+  describe("bugmole_commit_response edge cases", () => {
+    it("should extract next_steps from answer_markdown when missing", async () => {
+      // This tests the fallback extraction logic
+      const { callTool } = await import("./server.js");
+      const commitDir = path.join(testDir, "artifacts", "cursor_commits");
+      fs.mkdirSync(commitDir, { recursive: true });
+
+      // Call with answer_markdown containing "Next Steps" but no next_steps field
+      const result = await callTool(
+        {
+          name: "bugmole_commit_response",
+          arguments: {
+            status: "ok",
+            summary: "Test commit",
+            answer_markdown: "## Next Steps\n\n1. Do something\n2. Do something else",
+            // Intentionally missing next_steps
+          },
+        },
+        cfg,
+      );
+
+      assert.strictEqual(result.success, true);
+
+      // Verify next_steps was extracted and saved
+      const commitFiles = fs.readdirSync(commitDir).filter((f) => f.endsWith(".json"));
+      assert(commitFiles.length > 0);
+
+      const latestCommit = JSON.parse(
+        fs.readFileSync(path.join(commitDir, commitFiles[0]), "utf-8"),
+      );
+      assert("next_steps" in latestCommit.payload);
+      assert(Array.isArray(latestCommit.payload.next_steps));
+    });
+
+    it("should normalize next_steps from string to array", async () => {
+      const { callTool } = await import("./server.js");
+      const commitDir = path.join(testDir, "artifacts", "cursor_commits");
+      fs.mkdirSync(commitDir, { recursive: true });
+
+      // Call with next_steps as string (should be normalized to array)
+      const result = await callTool(
+        {
+          name: "bugmole_commit_response",
+          arguments: {
+            status: "ok",
+            summary: "Test",
+            next_steps: "Single step" as any, // Wrong type, should be normalized
+          },
+        },
+        cfg,
+      );
+
+      assert.strictEqual(result.success, true);
+
+      const commitFiles = fs.readdirSync(commitDir).filter((f) => f.endsWith(".json"));
+      const latestCommit = JSON.parse(
+        fs.readFileSync(path.join(commitDir, commitFiles[commitFiles.length - 1]), "utf-8"),
+      );
+      assert(Array.isArray(latestCommit.payload.next_steps));
+    });
+
+    it("should handle null/undefined next_steps", async () => {
+      const { callTool } = await import("./server.js");
+      const commitDir = path.join(testDir, "artifacts", "cursor_commits");
+      fs.mkdirSync(commitDir, { recursive: true });
+
+      // Call with null next_steps (should become empty array)
+      const result = await callTool(
+        {
+          name: "bugmole_commit_response",
+          arguments: {
+            status: "ok",
+            summary: "Test",
+            next_steps: null as any,
+          },
+        },
+        cfg,
+      );
+
+      assert.strictEqual(result.success, true);
+
+      const commitFiles = fs.readdirSync(commitDir).filter((f) => f.endsWith(".json"));
+      const latestCommit = JSON.parse(
+        fs.readFileSync(path.join(commitDir, commitFiles[commitFiles.length - 1]), "utf-8"),
+      );
+      assert(Array.isArray(latestCommit.payload.next_steps));
+      assert.strictEqual(latestCommit.payload.next_steps.length, 0);
+    });
+  });
+
+  describe("Tool Input Validation", () => {
+    it("should handle missing required arguments", async () => {
+      const { callTool } = await import("./server.js");
+
+      try {
+        await callTool(
+          {
+            name: "bugmole_read_spec",
+            arguments: {}, // Missing required filePath
+          },
+          cfg,
+        );
+        // Should either throw or return error
+      } catch (error: any) {
+        assert(error.message.length > 0);
+      }
+    });
+
+    it("should handle invalid argument types", async () => {
+      const { callTool } = await import("./server.js");
+
+      try {
+        await callTool(
+          {
+            name: "bugmole_read_spec",
+            arguments: {
+              filePath: 123 as any, // Wrong type
+            },
+          },
+          cfg,
+        );
+        // Should handle gracefully
+      } catch (error: any) {
+        // If it throws, should be a clear error
+        assert(error.message.length > 0);
+      }
+    });
+  });
+
+  describe("Path Resolution", () => {
+    it("should handle relative paths from different directories", async () => {
+      const { readSpecFile } = await import("./server.js");
+
+      // Create file in spec/plans/
+      const testFile = path.join(testDir, "spec", "plans", "relative.yaml");
+      fs.writeFileSync(testFile, "relative: test");
+
+      // Try different path formats
+      const paths = [
+        "plans/relative.yaml",
+        "spec/plans/relative.yaml",
+        path.join(testDir, "spec", "plans", "relative.yaml"),
+      ];
+
+      for (const testPath of paths) {
+        try {
+          const result = readSpecFile(testPath, cfg);
+          assert.strictEqual(result.content, "relative: test");
+          break; // If one works, that's good
+        } catch {
+          // Continue trying other paths
+        }
+      }
+    });
+
+    it("should use environment variables for project directory", async () => {
+      // Set environment variable
+      const originalDir = process.env.BUGMOLE_PROJECT_DIR;
+      process.env.BUGMOLE_PROJECT_DIR = testDir;
+
+      try {
+        const { readSpecFile } = await import("./server.js");
+        const testFile = path.join(testDir, "spec", "env_test.yaml");
+        fs.writeFileSync(testFile, "env: test");
+
+        const result = readSpecFile("env_test.yaml", cfg);
+        assert.strictEqual(result.content, "env: test");
+      } finally {
+        // Restore
+        if (originalDir) {
+          process.env.BUGMOLE_PROJECT_DIR = originalDir;
+        } else {
+          delete process.env.BUGMOLE_PROJECT_DIR;
+        }
+      }
+    });
+  });
+});