@side-quest/bun-runner 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# @side-quest/bun-runner
+
+## 1.0.0
+
+### Major Changes
+
+- Initial release of MCP server runner packages extracted from side-quest-marketplace.
+
+  - @side-quest/bun-runner: Test execution with bun_runTests, bun_testFile, bun_testCoverage
+  - @side-quest/biome-runner: Lint & format with biome_lintCheck, biome_lintFix, biome_formatCheck
+  - @side-quest/tsc-runner: Type checking with tsc_check
+
+## 0.0.0
+
+Initial development version. See [README](./README.md) for details.

package/LICENSE

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

package/README.md

@@ -0,0 +1,32 @@
+# @side-quest/bun-runner
+
+Bun test runner MCP server for Claude Code. Runs tests with structured, token-efficient output.
+
+## Tools
+
+- `bun_runTests` — Run tests with optional pattern filter
+- `bun_testFile` — Run specific test file
+- `bun_testCoverage` — Run tests with coverage report
+
+## Usage
+
+```bash
+bunx --bun @side-quest/bun-runner
+```
+
+Or in `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "bun-runner": {
+      "command": "bunx",
+      "args": ["--bun", "@side-quest/bun-runner"]
+    }
+  }
+}
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/**
+* Bun test output parsing utilities
+*
+* Extracted to a separate file to allow testing without importing mcpez
+*/
+interface TestFailure {
+	file: string;
+	message: string;
+	line?: number;
+	stack?: string;
+}
+interface TestSummary {
+	passed: number;
+	failed: number;
+	total: number;
+	failures: TestFailure[];
+}
+/**
+* Parse bun test output to extract test results
+*/
+declare function parseBunTestOutput(output: string): TestSummary;
+export { parseBunTestOutput, TestSummary, TestFailure };

package/dist/index.js

@@ -0,0 +1,394 @@
+#!/usr/bin/env bun
+// @bun
+
+// mcp/index.ts
+import {
+  createCorrelationId,
+  createPluginLogger
+} from "@side-quest/core/logging";
+import { startServer, tool, z } from "@side-quest/core/mcp";
+import {
+  createLoggerAdapter,
+  ResponseFormat,
+  wrapToolHandler
+} from "@side-quest/core/mcp-response";
+import { spawnWithTimeout } from "@side-quest/core/spawn";
+import {
+  validatePath,
+  validateShellSafePattern
+} from "@side-quest/core/validation";
+
+// mcp/parse-utils.ts
+function parseBunTestOutput(output) {
+  const failures = [];
+  const lines = output.split(`
+`);
+  let currentFailure = null;
+  let currentTestName;
+  for (const line of lines) {
+    if (!line)
+      continue;
+    const failMatch = line.match(/\(fail\)\s+(.+?)\s+\[/);
+    if (failMatch) {
+      if (currentFailure) {
+        currentTestName = failMatch[1];
+        currentFailure.message = `${currentTestName}: ${currentFailure.message}`;
+        failures.push(currentFailure);
+        currentFailure = null;
+      }
+      continue;
+    }
+    if (line.includes("✗") || line.startsWith("FAIL ")) {
+      if (currentFailure)
+        failures.push(currentFailure);
+      currentFailure = {
+        file: "unknown",
+        message: line.trim()
+      };
+      continue;
+    }
+    if (line.trim().startsWith("error:")) {
+      if (currentFailure) {
+        currentFailure.message += `
+${line.trim()}`;
+      } else {
+        currentFailure = {
+          file: "unknown",
+          message: line.trim()
+        };
+      }
+      continue;
+    }
+    if (currentFailure) {
+      if (line.trim().startsWith("at ")) {
+        const match = line.match(/\((.+):(\d+):(\d+)\)/) || line.match(/at (.+):(\d+):(\d+)/);
+        if (match?.[1] && match[2]) {
+          currentFailure.file = match[1];
+          currentFailure.line = Number.parseInt(match[2], 10);
+        }
+        currentFailure.stack = `${currentFailure.stack || ""}${line}
+`;
+      } else if (line.trim() && !line.match(/^\d+ \| /)) {
+        currentFailure.message += `
+${line.trim()}`;
+      }
+    }
+  }
+  if (currentFailure)
+    failures.push(currentFailure);
+  const passMatch = output.match(/(\d+) pass/);
+  const failMatchNum = output.match(/(\d+) fail/);
+  const passed = passMatch?.[1] ? Number.parseInt(passMatch[1], 10) : 0;
+  const failed = failMatchNum?.[1] ? Number.parseInt(failMatchNum[1], 10) : failures.length;
+  return {
+    passed,
+    failed,
+    total: passed + failed,
+    failures
+  };
+}
+
+// mcp/index.ts
+var { initLogger, getSubsystemLogger } = createPluginLogger({
+  name: "bun-runner",
+  subsystems: ["mcp"]
+});
+initLogger().catch(console.error);
+var mcpLogger = getSubsystemLogger("mcp");
+function parseBunTestOutputImpl(output) {
+  const failures = [];
+  const lines = output.split(`
+`);
+  let currentFailure = null;
+  let currentTestName;
+  for (const line of lines) {
+    if (!line)
+      continue;
+    const failMatch = line.match(/\(fail\)\s+(.+?)\s+\[/);
+    if (failMatch) {
+      if (currentFailure) {
+        currentTestName = failMatch[1];
+        currentFailure.message = `${currentTestName}: ${currentFailure.message}`;
+        failures.push(currentFailure);
+        currentFailure = null;
+      }
+      continue;
+    }
+    if (line.includes("\u2717") || line.startsWith("FAIL ")) {
+      if (currentFailure)
+        failures.push(currentFailure);
+      currentFailure = {
+        file: "unknown",
+        message: line.trim()
+      };
+      continue;
+    }
+    if (line.trim().startsWith("error:")) {
+      if (currentFailure) {
+        currentFailure.message += `
+${line.trim()}`;
+      } else {
+        currentFailure = {
+          file: "unknown",
+          message: line.trim()
+        };
+      }
+      continue;
+    }
+    if (currentFailure) {
+      if (line.trim().startsWith("at ")) {
+        const match = line.match(/\((.+):(\d+):(\d+)\)/) || line.match(/at (.+):(\d+):(\d+)/);
+        if (match?.[1] && match[2]) {
+          currentFailure.file = match[1];
+          currentFailure.line = Number.parseInt(match[2], 10);
+        }
+        currentFailure.stack = `${currentFailure.stack || ""}${line}
+`;
+      } else if (line.trim() && !line.match(/^\d+ \| /)) {
+        currentFailure.message += `
+${line.trim()}`;
+      }
+    }
+  }
+  if (currentFailure)
+    failures.push(currentFailure);
+  const passMatch = output.match(/(\d+) pass/);
+  const failMatchNum = output.match(/(\d+) fail/);
+  const passed = passMatch?.[1] ? Number.parseInt(passMatch[1], 10) : 0;
+  const failed = failMatchNum?.[1] ? Number.parseInt(failMatchNum[1], 10) : failures.length;
+  return {
+    passed,
+    failed,
+    total: passed + failed,
+    failures
+  };
+}
+async function runBunTests(pattern) {
+  const cmd = pattern ? ["bun", "test", pattern] : ["bun", "test"];
+  const TIMEOUT_MS = 30000;
+  const { stdout, stderr, exitCode, timedOut } = await spawnWithTimeout(cmd, TIMEOUT_MS, { env: { CI: "true" } });
+  if (timedOut) {
+    return {
+      passed: 0,
+      failed: 1,
+      total: 1,
+      failures: [
+        {
+          file: "timeout",
+          message: "Tests timed out after 30 seconds. Possible causes: open handles, infinite loops, or watch mode accidentally enabled."
+        }
+      ]
+    };
+  }
+  const output = `${stdout}
+${stderr}`;
+  if (exitCode === 0) {
+    const passMatch = output.match(/(\d+) pass/);
+    const passed = passMatch?.[1] ? Number.parseInt(passMatch[1], 10) : 0;
+    return {
+      passed,
+      failed: 0,
+      total: passed,
+      failures: []
+    };
+  }
+  return parseBunTestOutputImpl(output);
+}
+async function runBunTestCoverage() {
+  const TIMEOUT_MS = 60000;
+  const cmd = ["bun", "test", "--coverage"];
+  const { stdout, stderr, exitCode, timedOut } = await spawnWithTimeout(cmd, TIMEOUT_MS, { env: { CI: "true" } });
+  const output = `${stdout}
+${stderr}`;
+  if (timedOut) {
+    return {
+      summary: {
+        passed: 0,
+        failed: 1,
+        total: 1,
+        failures: [
+          {
+            file: "timeout",
+            message: "Tests timed out after 60 seconds."
+          }
+        ]
+      },
+      coverage: { percent: 0, uncovered: [] }
+    };
+  }
+  const summary = exitCode === 0 ? parseBunTestOutputImpl(stdout) : parseBunTestOutputImpl(output);
+  const coverageMatch = output.match(/(\d+(?:\.\d+)?)\s*%/);
+  const percent = coverageMatch?.[1] ? Number.parseFloat(coverageMatch[1]) : 0;
+  const uncovered = [];
+  const lines = output.split(`
+`);
+  for (const line of lines) {
+    const match = line.match(/^([^\s|]+)\s*\|\s*(\d+(?:\.\d+)?)\s*%/);
+    if (match?.[1] && match[2]) {
+      const file = match[1].trim();
+      const fileCoverage = Number.parseFloat(match[2]);
+      if (fileCoverage < 50 && file.endsWith(".ts")) {
+        uncovered.push(`${file} (${fileCoverage}%)`);
+      }
+    }
+  }
+  return {
+    summary,
+    coverage: { percent, uncovered }
+  };
+}
+function formatTestSummary(summary, format = ResponseFormat.MARKDOWN, context) {
+  if (format === ResponseFormat.JSON) {
+    return JSON.stringify({ ...summary, context }, null, 2);
+  }
+  if (summary.failed === 0) {
+    const ctx = context ? ` in ${context}` : "";
+    return `All ${summary.passed} tests passed${ctx}.`;
+  }
+  let output = `${summary.failed} tests failed${context ? ` in ${context}` : ""} (${summary.passed} passed)
+
+`;
+  summary.failures.forEach((f, i) => {
+    output += `${i + 1}. ${f.file}:${f.line || "?"}
+`;
+    output += `   ${f.message.split(`
+`)[0]}
+`;
+    if (f.stack) {
+      output += `${f.stack.split(`
+`).map((l) => `      ${l}`).join(`
+`)}
+`;
+    }
+    output += `
+`;
+  });
+  return output.trim();
+}
+function formatCoverageResult(summary, coverage, format = ResponseFormat.MARKDOWN) {
+  if (format === ResponseFormat.JSON) {
+    return JSON.stringify({ summary, coverage }, null, 2);
+  }
+  let output = "";
+  if (summary.failed === 0) {
+    output += `All ${summary.passed} tests passed.
+
+`;
+  } else {
+    output += `${summary.failed} tests failed (${summary.passed} passed)
+
+`;
+  }
+  output += `Coverage: ${coverage.percent}%
+`;
+  if (coverage.uncovered.length > 0) {
+    output += `
+Files with low coverage (<50%):
+`;
+    coverage.uncovered.forEach((f) => {
+      output += `   - ${f}
+`;
+    });
+  }
+  return output.trim();
+}
+tool("bun_runTests", {
+  description: "Run tests using Bun and return a concise summary of failures. Use this instead of 'bun test' to save tokens and get structured error reports.",
+  inputSchema: {
+    pattern: z.string().optional().describe("File pattern or test name to filter tests (e.g., 'auth' or 'login.test.ts')"),
+    response_format: z.enum(["markdown", "json"]).optional().default("json").describe("Output format: 'markdown' or 'json' (default)")
+  },
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  }
+}, wrapToolHandler(async (args, format) => {
+  const { pattern } = args;
+  if (pattern) {
+    validateShellSafePattern(pattern);
+    if (pattern.includes("/") || pattern.includes("..")) {
+      await validatePath(pattern);
+    }
+  }
+  const summary = await runBunTests(pattern);
+  const text = formatTestSummary(summary, format);
+  if (summary.failed > 0) {
+    const error = new Error(text);
+    error.summary = summary;
+    throw error;
+  }
+  return text;
+}, {
+  toolName: "bun_runTests",
+  logger: createLoggerAdapter(mcpLogger),
+  createCid: createCorrelationId
+}));
+tool("bun_testFile", {
+  description: "Run tests for a specific file only. More targeted than bun_runTests with a pattern.",
+  inputSchema: {
+    file: z.string().describe("Path to the test file to run (e.g., 'src/utils.test.ts')"),
+    response_format: z.enum(["markdown", "json"]).optional().default("json").describe("Output format: 'markdown' or 'json' (default)")
+  },
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  }
+}, wrapToolHandler(async (args, format) => {
+  const { file } = args;
+  const validatedFile = await validatePath(file);
+  const summary = await runBunTests(validatedFile);
+  const text = formatTestSummary(summary, format, file);
+  if (summary.failed > 0) {
+    const error = new Error(text);
+    error.summary = summary;
+    throw error;
+  }
+  return text;
+}, {
+  toolName: "bun_testFile",
+  logger: createLoggerAdapter(mcpLogger),
+  createCid: createCorrelationId
+}));
+tool("bun_testCoverage", {
+  description: "Run tests with code coverage and return a summary. Shows overall coverage percentage and files with low coverage.",
+  inputSchema: {
+    response_format: z.enum(["markdown", "json"]).optional().default("json").describe("Output format: 'markdown' or 'json' (default)")
+  },
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  }
+}, wrapToolHandler(async (_args, format) => {
+  const { summary, coverage } = await runBunTestCoverage();
+  const text = formatCoverageResult(summary, coverage, format);
+  if (summary.failed > 0) {
+    const error = new Error(text);
+    error.summary = summary;
+    error.coverage = coverage;
+    throw error;
+  }
+  return text;
+}, {
+  toolName: "bun_testCoverage",
+  logger: createLoggerAdapter(mcpLogger),
+  createCid: createCorrelationId
+}));
+if (__require.main == __require.module) {
+  startServer("bun-runner", {
+    version: "1.0.0",
+    fileLogging: {
+      enabled: true,
+      subsystems: ["mcp"],
+      level: "info"
+    }
+  });
+}
+export {
+  parseBunTestOutput
+};

package/package.json

@@ -0,0 +1,57 @@
+{
+	"name": "@side-quest/bun-runner",
+	"version": "1.0.0",
+	"description": "Bun test runner MCP server — structured, token-efficient test output for Claude Code",
+	"author": {
+		"name": "Nathan Vale",
+		"url": "https://github.com/nathanvale"
+	},
+	"license": "MIT",
+	"type": "module",
+	"bin": "./dist/index.js",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"files": [
+		"dist/**",
+		"README.md",
+		"LICENSE",
+		"CHANGELOG.md"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/nathanvale/side-quest-runners.git",
+		"directory": "packages/bun-runner"
+	},
+	"bugs": {
+		"url": "https://github.com/nathanvale/side-quest-runners/issues"
+	},
+	"homepage": "https://github.com/nathanvale/side-quest-runners/tree/main/packages/bun-runner#readme",
+	"keywords": [
+		"mcp",
+		"claude-code",
+		"bun",
+		"testing",
+		"test-runner"
+	],
+	"publishConfig": {
+		"access": "public",
+		"provenance": true
+	},
+	"scripts": {
+		"build": "bunx bunup",
+		"clean": "rimraf dist 2>/dev/null || true",
+		"test": "bun test",
+		"test:ci": "TF_BUILD=true bun test",
+		"typecheck": "tsc --noEmit"
+	},
+	"dependencies": {
+		"@side-quest/core": "^0.1.1"
+	}
+}