executable-stories-mcp 0.2.0

package/README.md

@@ -0,0 +1,81 @@
+# executable-stories-mcp
+
+MCP server for executable-stories behavior catalogs.
+
+It consumes `story-report-json` output from `executable-stories-formatters` and exposes scenario discovery and focused test-run tools for coding agents.
+
+## Create the Report
+
+```bash
+executable-stories format .executable-stories/raw-run.json \
+  --format story-report-json,scenario-index-json,behavior-manifest-json \
+  --output-dir reports \
+  --output-name index
+```
+
+Default StoryReport path used by the MCP server:
+
+```text
+reports/index.story-report.json
+```
+
+## Run
+
+```bash
+npx executable-stories-mcp
+```
+
+The binary speaks the MCP stdio transport. For an HTTP interface, see [HTTP API](#http-api-optional) below.
+
+## Tools
+
+### Read-only (StoryReport query)
+
+- `list_scenarios` — scenario index items with status, source, tags, tickets, covers, steps, doc kinds, errors. Optional `statuses` / `tags` / `sourceFiles` filters
+- `get_scenario` — one scenario by id or exact title
+- `get_failing_scenarios` — failed scenarios only
+- `get_scenarios_for_paths` — code→scenario: scenarios whose declared `covers` globs match given product-code paths
+- `get_feature_summary` — per-feature pass/fail counts
+- `get_scenario_index` — Storybook-like `scenario-index` v1 artifact
+- `get_behavior_manifest` — tags, source files, doc coverage, debugger warnings (incl. `missing-covers`)
+- `get_behavior_diff` — compare two StoryReports by scenario id (regressed / fixed / added / removed)
+
+### Execution
+
+- `run_scenario` — run one scenario via the host framework (`vitest`, `jest`, `playwright`, or `cypress`). **Executes real tests.**
+
+Each tool accepts optional `reportPath` to point at a specific StoryReport JSON file.
+
+## Contract
+
+StoryReport v1 JSON remains the canonical artifact:
+
+```bash
+executable-stories format <raw-run.json> --format story-report-json
+```
+
+MCP is a query and optional execution layer over that artifact.
+
+## HTTP API (optional)
+
+For non-MCP clients or local debugging, start the HTTP server programmatically (the `executable-stories-mcp` binary itself only speaks stdio):
+
+```typescript
+import { startHttpServer } from "executable-stories-mcp/http";
+await startHttpServer({ reportPath: "reports/index.story-report.json", port: 7357 });
+```
+
+Endpoints (each maps to the matching MCP tool):
+
+- `GET /health`
+- `GET /scenarios` (optional `?status=&tag=&sourceFile=`) → `list_scenarios`
+- `GET /scenarios/failing` → `get_failing_scenarios`
+- `GET /scenarios/covering?path=…` → `get_scenarios_for_paths`
+- `GET /scenarios/:id` → `get_scenario`
+- `GET /scenarios-index` → `get_scenario_index`
+- `GET /features` → `get_feature_summary`
+- `GET /manifest` → `get_behavior_manifest`
+- `GET /diff?baseline=&current=` → `get_behavior_diff`
+- `POST /run-scenarios` → `run_scenario`
+
+Every GET accepts a `?reportPath=` query parameter.

package/dist/http.cjs

@@ -0,0 +1,313 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/http.ts
+var http_exports = {};
+__export(http_exports, {
+  createHttpServer: () => createHttpServer,
+  startHttpServer: () => startHttpServer
+});
+module.exports = __toCommonJS(http_exports);
+var import_node_http = __toESM(require("http"), 1);
+
+// src/index.ts
+var fs = __toESM(require("fs"), 1);
+var path = __toESM(require("path"), 1);
+var import_node_child_process = require("child_process");
+var import_executable_stories_formatters = require("executable-stories-formatters");
+function loadStoryReport(reportPath) {
+  const absolutePath = path.resolve(reportPath);
+  const parsed = JSON.parse(fs.readFileSync(absolutePath, "utf8"));
+  assertStoryReport(parsed, absolutePath);
+  return parsed;
+}
+function listScenarios(report, filters) {
+  return (0, import_executable_stories_formatters.toScenarioIndex)(report, filters).scenarios;
+}
+function getFailingScenarios(report) {
+  return listScenarios(report, { statuses: ["failed"] });
+}
+function getScenariosForPaths(report, paths) {
+  return (0, import_executable_stories_formatters.scenariosCoveringPaths)((0, import_executable_stories_formatters.toScenarioIndex)(report), paths);
+}
+function getBehaviorDiff(baseline, current) {
+  return (0, import_executable_stories_formatters.diffStoryReports)(baseline, current);
+}
+function getScenario(report, idOrTitle) {
+  for (const feature of report.features) {
+    const scenario = feature.scenarios.find(
+      (candidate) => candidate.id === idOrTitle || candidate.title === idOrTitle
+    );
+    if (scenario) return { feature, scenario };
+  }
+  return void 0;
+}
+function getFeatureSummary(report) {
+  return report.features.map((feature) => ({
+    id: feature.id,
+    title: feature.title,
+    sourceFile: feature.sourceFile,
+    total: feature.summary.total,
+    passed: feature.summary.passed,
+    failed: feature.summary.failed,
+    skipped: feature.summary.skipped,
+    pending: feature.summary.pending,
+    durationMs: feature.summary.durationMs
+  }));
+}
+function resolveReportPath(reportPath) {
+  return path.resolve(reportPath ?? "reports/index.story-report.json");
+}
+function getScenarioIndex(report) {
+  return (0, import_executable_stories_formatters.toScenarioIndex)(report);
+}
+function getBehaviorManifest(report) {
+  return (0, import_executable_stories_formatters.toBehaviorManifest)(report);
+}
+var readOnlyTools = [
+  {
+    name: "get_failing_scenarios",
+    title: "Get failing scenarios",
+    description: "List failing executable story scenarios from StoryReport JSON.",
+    route: "/scenarios/failing",
+    run: getFailingScenarios
+  },
+  {
+    name: "get_feature_summary",
+    title: "Get feature summary",
+    description: "Summarize features and scenario status counts from StoryReport JSON.",
+    route: "/features",
+    run: getFeatureSummary
+  },
+  {
+    name: "get_scenario_index",
+    title: "Get scenario index",
+    description: "Return the Storybook-like scenario index artifact (schema v1) derived from StoryReport JSON.",
+    route: "/scenarios-index",
+    run: getScenarioIndex
+  },
+  {
+    name: "get_behavior_manifest",
+    title: "Get behavior manifest",
+    description: "Return agent-oriented manifest metadata: source files, tags, doc coverage, debugger warnings.",
+    route: "/manifest",
+    run: getBehaviorManifest
+  }
+];
+var RUNNERS = {
+  vitest: {
+    framework: "vitest",
+    buildCommand: ({ sourceFile, scenarioTitle }) => ({
+      command: "pnpm",
+      args: ["exec", "vitest", "run", sourceFile, ...scenarioTitle ? ["-t", scenarioTitle] : []]
+    })
+  },
+  jest: {
+    framework: "jest",
+    buildCommand: ({ sourceFile, scenarioTitle }) => ({
+      command: "pnpm",
+      args: ["exec", "jest", sourceFile, ...scenarioTitle ? ["-t", scenarioTitle] : [], "--runInBand"]
+    })
+  },
+  playwright: {
+    framework: "playwright",
+    detect: (sourceFile) => sourceFile.includes(".story.spec."),
+    buildCommand: ({ sourceFile, scenarioTitle }) => ({
+      command: "pnpm",
+      args: ["exec", "playwright", "test", sourceFile, ...scenarioTitle ? ["-g", scenarioTitle] : []]
+    })
+  },
+  cypress: {
+    framework: "cypress",
+    detect: (sourceFile) => sourceFile.includes(".story.cy."),
+    buildCommand: ({ sourceFile }) => ({
+      command: "pnpm",
+      args: ["exec", "cypress", "run", "--spec", sourceFile]
+    })
+  }
+};
+function buildFocusedRunCommand(args) {
+  return RUNNERS[args.framework].buildCommand(args);
+}
+async function runFocusedScenario(args) {
+  const command = buildFocusedRunCommand(args);
+  const spawnFn = args.spawnFn ?? import_node_child_process.spawn;
+  return new Promise((resolve2) => {
+    const child = spawnFn(command.command, command.args, {
+      cwd: args.cwd,
+      env: process.env
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => {
+      stdout += String(chunk);
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += String(chunk);
+    });
+    child.on("error", (error) => {
+      resolve2({
+        ok: false,
+        exitCode: null,
+        command: command.command,
+        args: command.args,
+        stdout,
+        stderr: stderr + error.message
+      });
+    });
+    child.on("close", (exitCode) => {
+      resolve2({
+        ok: exitCode === 0,
+        exitCode,
+        command: command.command,
+        args: command.args,
+        stdout,
+        stderr
+      });
+    });
+  });
+}
+function assertStoryReport(value, reportPath) {
+  if (!value || typeof value !== "object") {
+    throw new Error(`Invalid StoryReport JSON in ${reportPath}: expected object`);
+  }
+  const report = value;
+  if (typeof report.schemaVersion !== "string" || !report.schemaVersion.startsWith("1.")) {
+    throw new Error(
+      `Invalid StoryReport JSON in ${reportPath}: expected schemaVersion 1.x`
+    );
+  }
+  if (!Array.isArray(report.features)) {
+    throw new Error(`Invalid StoryReport JSON in ${reportPath}: expected features array`);
+  }
+}
+
+// src/http.ts
+var readOnlyRoutes = new Map(readOnlyTools.map((tool) => [tool.route, tool.run]));
+function parseFilters(params) {
+  const statuses = params.getAll("status");
+  const tags = params.getAll("tag");
+  const sourceFiles = params.getAll("sourceFile");
+  return {
+    statuses: statuses.length ? statuses : void 0,
+    tags: tags.length ? tags : void 0,
+    sourceFiles: sourceFiles.length ? sourceFiles : void 0
+  };
+}
+function createHttpServer(options = {}) {
+  return import_node_http.default.createServer(async (request, response) => {
+    try {
+      if (!request.url) {
+        sendJson(response, 404, { error: "Missing URL" });
+        return;
+      }
+      const url = new URL(request.url, "http://localhost");
+      const reportPath = url.searchParams.get("reportPath") ?? options.reportPath;
+      if (request.method === "GET" && url.pathname === "/health") {
+        sendJson(response, 200, { ok: true, name: "executable-stories-mcp" });
+        return;
+      }
+      if (request.method === "GET" && url.pathname === "/diff") {
+        const baseline = loadStoryReport(
+          resolveReportPath(url.searchParams.get("baseline") ?? void 0)
+        );
+        const current = loadStoryReport(
+          resolveReportPath(url.searchParams.get("current") ?? reportPath ?? void 0)
+        );
+        sendJson(response, 200, getBehaviorDiff(baseline, current));
+        return;
+      }
+      if (request.method === "GET") {
+        const report = loadStoryReport(resolveReportPath(reportPath));
+        if (url.pathname === "/scenarios") {
+          sendJson(response, 200, listScenarios(report, parseFilters(url.searchParams)));
+          return;
+        }
+        if (url.pathname === "/scenarios/covering") {
+          sendJson(response, 200, getScenariosForPaths(report, url.searchParams.getAll("path")));
+          return;
+        }
+        const handler = readOnlyRoutes.get(url.pathname);
+        if (handler) {
+          sendJson(response, 200, handler(report));
+          return;
+        }
+        if (url.pathname.startsWith("/scenarios/")) {
+          const id = decodeURIComponent(url.pathname.slice("/scenarios/".length));
+          const scenario = getScenario(report, id);
+          sendJson(response, scenario ? 200 : 404, scenario ?? { error: `Scenario not found: ${id}` });
+          return;
+        }
+      }
+      if (request.method === "POST" && url.pathname === "/run-scenarios") {
+        const body = await readJsonBody(request);
+        const result = await runFocusedScenario({
+          framework: body.framework,
+          sourceFile: String(body.sourceFile),
+          scenarioTitle: typeof body.scenarioTitle === "string" ? body.scenarioTitle : void 0,
+          cwd: typeof body.cwd === "string" ? body.cwd : void 0
+        });
+        sendJson(response, result.ok ? 200 : 500, result);
+        return;
+      }
+      sendJson(response, 404, { error: "Not found" });
+    } catch (error) {
+      sendJson(response, 500, { error: error.message });
+    }
+  });
+}
+async function startHttpServer(options = {}) {
+  const server = createHttpServer(options);
+  const port = options.port ?? 7357;
+  const host = options.host ?? "127.0.0.1";
+  await new Promise((resolve2) => {
+    server.listen(port, host, resolve2);
+  });
+  return server;
+}
+function sendJson(response, statusCode, value) {
+  response.writeHead(statusCode, {
+    "content-type": "application/json; charset=utf-8",
+    "access-control-allow-origin": "*"
+  });
+  response.end(JSON.stringify(value, null, 2));
+}
+async function readJsonBody(request) {
+  const chunks = [];
+  for await (const chunk of request) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createHttpServer,
+  startHttpServer
+});
+//# sourceMappingURL=http.cjs.map

package/dist/http.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/http.ts","../src/index.ts"],"sourcesContent":["import http from \"node:http\";\n\nimport {\n  getBehaviorDiff,\n  getScenario,\n  getScenariosForPaths,\n  listScenarios,\n  loadStoryReport,\n  readOnlyTools,\n  resolveReportPath,\n  runFocusedScenario,\n  type FocusedRunFramework,\n  type ScenarioIndexFilters,\n} from \"./index.js\";\n\nexport interface HttpServerOptions {\n  port?: number;\n  host?: string;\n  reportPath?: string;\n}\n\n/** Exact GET routes shared with the stdio MCP server (see readOnlyTools). */\nconst readOnlyRoutes = new Map(readOnlyTools.map((tool) => [tool.route, tool.run]));\n\n/** Parse the repeatable filter query params (?status=&tag=&sourceFile=). */\nfunction parseFilters(params: URLSearchParams): ScenarioIndexFilters {\n  const statuses = params.getAll(\"status\");\n  const tags = params.getAll(\"tag\");\n  const sourceFiles = params.getAll(\"sourceFile\");\n  return {\n    statuses: statuses.length ? (statuses as ScenarioIndexFilters[\"statuses\"]) : undefined,\n    tags: tags.length ? tags : undefined,\n    sourceFiles: sourceFiles.length ? sourceFiles : undefined,\n  };\n}\n\nexport function createHttpServer(options: HttpServerOptions = {}): http.Server {\n  return http.createServer(async (request, response) => {\n    try {\n      if (!request.url) {\n        sendJson(response, 404, { error: \"Missing URL\" });\n        return;\n      }\n\n      const url = new URL(request.url, \"http://localhost\");\n      const reportPath = url.searchParams.get(\"reportPath\") ?? options.reportPath;\n\n      if (request.method === \"GET\" && url.pathname === \"/health\") {\n        sendJson(response, 200, { ok: true, name: \"executable-stories-mcp\" });\n        return;\n      }\n\n      // Diff compares two reports, so it resolves before the single-report load.\n      if (request.method === \"GET\" && url.pathname === \"/diff\") {\n        const baseline = loadStoryReport(\n          resolveReportPath(url.searchParams.get(\"baseline\") ?? undefined),\n        );\n        const current = loadStoryReport(\n          resolveReportPath(url.searchParams.get(\"current\") ?? reportPath ?? undefined),\n        );\n        sendJson(response, 200, getBehaviorDiff(baseline, current));\n        return;\n      }\n\n      if (request.method === \"GET\") {\n        const report = loadStoryReport(resolveReportPath(reportPath));\n\n        // Arg-taking routes resolve before the no-arg catalog and the dynamic\n        // /scenarios/:id route.\n        if (url.pathname === \"/scenarios\") {\n          sendJson(response, 200, listScenarios(report, parseFilters(url.searchParams)));\n          return;\n        }\n        if (url.pathname === \"/scenarios/covering\") {\n          sendJson(response, 200, getScenariosForPaths(report, url.searchParams.getAll(\"path\")));\n          return;\n        }\n\n        // Exact catalog routes resolve before the dynamic /scenarios/:id route,\n        // so /scenarios/failing keeps working as a fixed endpoint.\n        const handler = readOnlyRoutes.get(url.pathname);\n        if (handler) {\n          sendJson(response, 200, handler(report));\n          return;\n        }\n        if (url.pathname.startsWith(\"/scenarios/\")) {\n          const id = decodeURIComponent(url.pathname.slice(\"/scenarios/\".length));\n          const scenario = getScenario(report, id);\n          sendJson(response, scenario ? 200 : 404, scenario ?? { error: `Scenario not found: ${id}` });\n          return;\n        }\n      }\n\n      if (request.method === \"POST\" && url.pathname === \"/run-scenarios\") {\n        const body = await readJsonBody(request);\n        const result = await runFocusedScenario({\n          framework: body.framework as FocusedRunFramework,\n          sourceFile: String(body.sourceFile),\n          scenarioTitle: typeof body.scenarioTitle === \"string\" ? body.scenarioTitle : undefined,\n          cwd: typeof body.cwd === \"string\" ? body.cwd : undefined,\n        });\n        sendJson(response, result.ok ? 200 : 500, result);\n        return;\n      }\n\n      sendJson(response, 404, { error: \"Not found\" });\n    } catch (error) {\n      sendJson(response, 500, { error: (error as Error).message });\n    }\n  });\n}\n\nexport async function startHttpServer(options: HttpServerOptions = {}): Promise<http.Server> {\n  const server = createHttpServer(options);\n  const port = options.port ?? 7357;\n  const host = options.host ?? \"127.0.0.1\";\n  await new Promise<void>((resolve) => {\n    server.listen(port, host, resolve);\n  });\n  return server;\n}\n\nfunction sendJson(response: http.ServerResponse, statusCode: number, value: unknown): void {\n  response.writeHead(statusCode, {\n    \"content-type\": \"application/json; charset=utf-8\",\n    \"access-control-allow-origin\": \"*\",\n  });\n  response.end(JSON.stringify(value, null, 2));\n}\n\nasync function readJsonBody(request: http.IncomingMessage): Promise<Record<string, unknown>> {\n  const chunks: Buffer[] = [];\n  for await (const chunk of request) {\n    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));\n  }\n  return JSON.parse(Buffer.concat(chunks).toString(\"utf8\") || \"{}\") as Record<string, unknown>;\n}\n","import * as fs from \"node:fs\";\nimport * as path from \"node:path\";\nimport { spawn, type ChildProcessWithoutNullStreams } from \"node:child_process\";\n\nimport type {\n  ReportFeature,\n  ReportScenario,\n  StoryReport,\n  BehaviorManifest,\n  BehaviorDiff,\n  ScenarioIndex,\n  ScenarioIndexFilters,\n  ScenarioIndexItem,\n} from \"executable-stories-formatters\";\nimport {\n  diffStoryReports,\n  scenariosCoveringPaths,\n  toBehaviorManifest,\n  toScenarioIndex,\n} from \"executable-stories-formatters\";\n\n// Scenario serialization is owned by the formatters package; re-export so MCP\n// consumers get the same shape without a parallel definition to maintain.\nexport type { ScenarioIndexItem, ScenarioIndexFilters };\n\nexport interface FeatureSummaryItem {\n  id: string;\n  title: string;\n  sourceFile: string;\n  total: number;\n  passed: number;\n  failed: number;\n  skipped: number;\n  pending: number;\n  durationMs: number;\n}\n\nexport interface ScenarioLookup {\n  feature: ReportFeature;\n  scenario: ReportScenario;\n}\n\nexport function loadStoryReport(reportPath: string): StoryReport {\n  const absolutePath = path.resolve(reportPath);\n  const parsed: unknown = JSON.parse(fs.readFileSync(absolutePath, \"utf8\"));\n  assertStoryReport(parsed, absolutePath);\n  return parsed;\n}\n\nexport function listScenarios(\n  report: StoryReport,\n  filters?: ScenarioIndexFilters,\n): ScenarioIndexItem[] {\n  return toScenarioIndex(report, filters).scenarios;\n}\n\nexport function getFailingScenarios(report: StoryReport): ScenarioIndexItem[] {\n  return listScenarios(report, { statuses: [\"failed\"] });\n}\n\nexport function getScenariosForPaths(report: StoryReport, paths: string[]): ScenarioIndexItem[] {\n  return scenariosCoveringPaths(toScenarioIndex(report), paths);\n}\n\nexport function getBehaviorDiff(baseline: StoryReport, current: StoryReport): BehaviorDiff {\n  return diffStoryReports(baseline, current);\n}\n\nexport function getScenario(report: StoryReport, idOrTitle: string): ScenarioLookup | undefined {\n  for (const feature of report.features) {\n    const scenario = feature.scenarios.find(\n      (candidate) => candidate.id === idOrTitle || candidate.title === idOrTitle,\n    );\n    if (scenario) return { feature, scenario };\n  }\n  return undefined;\n}\n\nexport function getFeatureSummary(report: StoryReport): FeatureSummaryItem[] {\n  return report.features.map((feature) => ({\n    id: feature.id,\n    title: feature.title,\n    sourceFile: feature.sourceFile,\n    total: feature.summary.total,\n    passed: feature.summary.passed,\n    failed: feature.summary.failed,\n    skipped: feature.summary.skipped,\n    pending: feature.summary.pending,\n    durationMs: feature.summary.durationMs,\n  }));\n}\n\nexport function resolveReportPath(reportPath?: string): string {\n  return path.resolve(reportPath ?? \"reports/index.story-report.json\");\n}\n\nexport function getScenarioIndex(report: StoryReport): ScenarioIndex {\n  return toScenarioIndex(report);\n}\n\nexport function getBehaviorManifest(report: StoryReport): BehaviorManifest {\n  return toBehaviorManifest(report);\n}\n\n/**\n * Single source of truth for the read-only tools, consumed by both the stdio\n * MCP server and the HTTP server so the two transports cannot drift apart.\n * Tools needing extra arguments (get_scenario, run_scenario) are wired up\n * directly in each transport.\n */\nexport interface ReadOnlyTool {\n  /** MCP tool name. */\n  name: string;\n  /** Human-readable MCP tool title. */\n  title: string;\n  /** Shared description used by both transports. */\n  description: string;\n  /** HTTP route that exposes the same data. */\n  route: string;\n  /** Pure projection from a loaded report to its JSON payload. */\n  run: (report: StoryReport) => unknown;\n}\n\nexport const readOnlyTools: ReadOnlyTool[] = [\n  {\n    name: \"get_failing_scenarios\",\n    title: \"Get failing scenarios\",\n    description: \"List failing executable story scenarios from StoryReport JSON.\",\n    route: \"/scenarios/failing\",\n    run: getFailingScenarios,\n  },\n  {\n    name: \"get_feature_summary\",\n    title: \"Get feature summary\",\n    description: \"Summarize features and scenario status counts from StoryReport JSON.\",\n    route: \"/features\",\n    run: getFeatureSummary,\n  },\n  {\n    name: \"get_scenario_index\",\n    title: \"Get scenario index\",\n    description:\n      \"Return the Storybook-like scenario index artifact (schema v1) derived from StoryReport JSON.\",\n    route: \"/scenarios-index\",\n    run: getScenarioIndex,\n  },\n  {\n    name: \"get_behavior_manifest\",\n    title: \"Get behavior manifest\",\n    description:\n      \"Return agent-oriented manifest metadata: source files, tags, doc coverage, debugger warnings.\",\n    route: \"/manifest\",\n    run: getBehaviorManifest,\n  },\n];\n\nexport type FocusedRunFramework = \"vitest\" | \"jest\" | \"playwright\" | \"cypress\";\n\nexport interface FocusedRunCommandArgs {\n  framework: FocusedRunFramework;\n  sourceFile: string;\n  scenarioTitle?: string;\n}\n\nexport interface FocusedRunCommand {\n  command: string;\n  args: string[];\n}\n\nexport interface FocusedRunResult {\n  ok: boolean;\n  exitCode: number | null;\n  command: string;\n  args: string[];\n  stdout: string;\n  stderr: string;\n}\n\n/**\n * One runner per host framework. The seam that keeps `run_scenario` extensible:\n * adding a non-JS framework (go, cargo, pytest, dotnet) later is a single new\n * entry here — no changes to inference, command building, or the transports.\n */\nexport interface RunnerDefinition {\n  framework: FocusedRunFramework;\n  /** Infer this framework from a source-file path, when unambiguous. */\n  detect?: (sourceFile: string) => boolean;\n  /** Build the focused-run command for this framework. */\n  buildCommand: (args: { sourceFile: string; scenarioTitle?: string }) => FocusedRunCommand;\n}\n\nexport const RUNNERS: Record<FocusedRunFramework, RunnerDefinition> = {\n  vitest: {\n    framework: \"vitest\",\n    buildCommand: ({ sourceFile, scenarioTitle }) => ({\n      command: \"pnpm\",\n      args: [\"exec\", \"vitest\", \"run\", sourceFile, ...(scenarioTitle ? [\"-t\", scenarioTitle] : [])],\n    }),\n  },\n  jest: {\n    framework: \"jest\",\n    buildCommand: ({ sourceFile, scenarioTitle }) => ({\n      command: \"pnpm\",\n      args: [\"exec\", \"jest\", sourceFile, ...(scenarioTitle ? [\"-t\", scenarioTitle] : []), \"--runInBand\"],\n    }),\n  },\n  playwright: {\n    framework: \"playwright\",\n    detect: (sourceFile) => sourceFile.includes(\".story.spec.\"),\n    buildCommand: ({ sourceFile, scenarioTitle }) => ({\n      command: \"pnpm\",\n      args: [\"exec\", \"playwright\", \"test\", sourceFile, ...(scenarioTitle ? [\"-g\", scenarioTitle] : [])],\n    }),\n  },\n  cypress: {\n    framework: \"cypress\",\n    detect: (sourceFile) => sourceFile.includes(\".story.cy.\"),\n    buildCommand: ({ sourceFile }) => ({\n      command: \"pnpm\",\n      args: [\"exec\", \"cypress\", \"run\", \"--spec\", sourceFile],\n    }),\n  },\n};\n\nexport function inferFrameworkFromSourceFile(\n  sourceFile: string,\n): FocusedRunFramework | undefined {\n  for (const runner of Object.values(RUNNERS)) {\n    if (runner.detect?.(sourceFile)) return runner.framework;\n  }\n  return undefined;\n}\n\nexport function resolveFocusedRunFramework(args: {\n  sourceFile: string;\n  framework?: FocusedRunFramework;\n}): FocusedRunFramework {\n  if (args.framework) return args.framework;\n  const inferred = inferFrameworkFromSourceFile(args.sourceFile);\n  if (inferred) return inferred;\n  throw new Error(\n    `Could not infer test framework from ${args.sourceFile}. Pass framework: vitest | jest | playwright | cypress.`,\n  );\n}\n\nexport function buildFocusedRunCommand(args: FocusedRunCommandArgs): FocusedRunCommand {\n  return RUNNERS[args.framework].buildCommand(args);\n}\n\nexport async function runFocusedScenario(args: FocusedRunCommandArgs & {\n  cwd?: string;\n  spawnFn?: typeof spawn;\n}): Promise<FocusedRunResult> {\n  const command = buildFocusedRunCommand(args);\n  const spawnFn = args.spawnFn ?? spawn;\n\n  return new Promise((resolve) => {\n    const child = spawnFn(command.command, command.args, {\n      cwd: args.cwd,\n      env: process.env,\n    }) as ChildProcessWithoutNullStreams;\n    let stdout = \"\";\n    let stderr = \"\";\n\n    child.stdout.on(\"data\", (chunk) => {\n      stdout += String(chunk);\n    });\n    child.stderr.on(\"data\", (chunk) => {\n      stderr += String(chunk);\n    });\n    child.on(\"error\", (error) => {\n      resolve({\n        ok: false,\n        exitCode: null,\n        command: command.command,\n        args: command.args,\n        stdout,\n        stderr: stderr + error.message,\n      });\n    });\n    child.on(\"close\", (exitCode) => {\n      resolve({\n        ok: exitCode === 0,\n        exitCode,\n        command: command.command,\n        args: command.args,\n        stdout,\n        stderr,\n      });\n    });\n  });\n}\n\nfunction assertStoryReport(\n  value: unknown,\n  reportPath: string,\n): asserts value is StoryReport {\n  if (!value || typeof value !== \"object\") {\n    throw new Error(`Invalid StoryReport JSON in ${reportPath}: expected object`);\n  }\n  const report = value as Partial<StoryReport>;\n  if (typeof report.schemaVersion !== \"string\" || !report.schemaVersion.startsWith(\"1.\")) {\n    throw new Error(\n      `Invalid StoryReport JSON in ${reportPath}: expected schemaVersion 1.x`,\n    );\n  }\n  if (!Array.isArray(report.features)) {\n    throw new Error(`Invalid StoryReport JSON in ${reportPath}: expected features array`);\n  }\n}\n"],"mappings":"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","names":["resolve","http","resolve"]}

package/dist/http.d.cts

@@ -0,0 +1,11 @@
+import http from 'node:http';
+
+interface HttpServerOptions {
+    port?: number;
+    host?: string;
+    reportPath?: string;
+}
+declare function createHttpServer(options?: HttpServerOptions): http.Server;
+declare function startHttpServer(options?: HttpServerOptions): Promise<http.Server>;
+
+export { type HttpServerOptions, createHttpServer, startHttpServer };

package/dist/http.d.ts

@@ -0,0 +1,11 @@
+import http from 'node:http';
+
+interface HttpServerOptions {
+    port?: number;
+    host?: string;
+    reportPath?: string;
+}
+declare function createHttpServer(options?: HttpServerOptions): http.Server;
+declare function startHttpServer(options?: HttpServerOptions): Promise<http.Server>;
+
+export { type HttpServerOptions, createHttpServer, startHttpServer };