heyspex 0.2.5 → 0.2.7

package/dist/cli/hs-test.mjs

@@ -0,0 +1,1046 @@
+import { createRequire as __hsCreateRequire } from 'node:module';
+const require = __hsCreateRequire(import.meta.url);
+
+// spex-console/bin/hs-test.ts
+import { spawn as spawn2, spawnSync as spawnSync2 } from "node:child_process";
+import { existsSync as existsSync2, readFileSync } from "node:fs";
+import os from "node:os";
+import path2 from "node:path";
+import process3 from "node:process";
+
+// spex-console/src/lib/cli/mutation-gate.ts
+var EXIT = {
+  /** The suite passed the gate. */
+  OK: 0,
+  /** Usage error — unknown flag, bad verb, or out-of-range threshold. */
+  USAGE: 1,
+  /** Report file / target not found. */
+  NOT_FOUND: 10,
+  /** Report present but malformed (not the mutation-testing-elements schema). */
+  INVALID_REPORT: 11,
+  /** The mutation runner is not installed / not on PATH. */
+  RUNNER_MISSING: 12,
+  /** The gate ran and rejected the suite (a real reject, not a harness error). */
+  GATE_FAILED: 20
+};
+function emptyCounts() {
+  return { killed: 0, survived: 0, noCoverage: 0, timeout: 0, invalid: 0 };
+}
+function parseGateArgs(argv) {
+  const verbRaw = argv[0];
+  if (verbRaw === "--help" || verbRaw === "-h") return { help: true };
+  if (verbRaw !== "gate") {
+    return { error: { code: EXIT.USAGE, message: `unknown verb: ${verbRaw ?? "(none)"}` } };
+  }
+  let target;
+  let reportPath = null;
+  let threshold = null;
+  let json = false;
+  for (let i = 1; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") return { help: true };
+    else if (arg === "--json") json = true;
+    else if (arg === "--report" || arg.startsWith("--report=")) {
+      const value = arg.includes("=") ? arg.slice("--report=".length) : argv[++i];
+      if (value === void 0 || value.trim() === "") {
+        return { error: { code: EXIT.USAGE, message: "--report requires a path" } };
+      }
+      reportPath = value;
+    } else if (arg === "--threshold" || arg.startsWith("--threshold=")) {
+      const value = arg.includes("=") ? arg.slice("--threshold=".length) : argv[++i];
+      if (value === void 0) {
+        return { error: { code: EXIT.USAGE, message: "--threshold requires a value (0\u2013100)" } };
+      }
+      const n = Number(value);
+      if (!Number.isFinite(n) || n < 0 || n > 100) {
+        return {
+          error: { code: EXIT.USAGE, message: `--threshold must be a number 0\u2013100, got: ${value}` }
+        };
+      }
+      threshold = n;
+    } else if (arg.startsWith("-")) {
+      return { error: { code: EXIT.USAGE, message: `unknown flag: ${arg}` } };
+    } else if (target === void 0) {
+      target = arg;
+    } else {
+      return { error: { code: EXIT.USAGE, message: `unexpected argument: ${arg}` } };
+    }
+  }
+  return { args: { verb: "gate", target: target ?? ".", reportPath, threshold, json } };
+}
+function tally(counts, rawStatus) {
+  const status = String(rawStatus ?? "").trim().toLowerCase();
+  switch (status) {
+    case "killed":
+      counts.killed += 1;
+      break;
+    case "survived":
+      counts.survived += 1;
+      break;
+    case "nocoverage":
+      counts.noCoverage += 1;
+      break;
+    case "timeout":
+      counts.timeout += 1;
+      break;
+    // CompileError / RuntimeError / Ignored / Pending don't count toward the score.
+    default:
+      counts.invalid += 1;
+      break;
+  }
+}
+function parseMutationReport(text) {
+  let raw;
+  try {
+    raw = JSON.parse(text);
+  } catch (err) {
+    return {
+      error: `report is not valid JSON: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+  const files = raw?.files;
+  if (typeof raw !== "object" || raw === null || typeof files !== "object" || files === null) {
+    return { error: "report must be a mutation-testing-elements object with a `files` map" };
+  }
+  const total = emptyCounts();
+  const perFile = [];
+  for (const [path3, fileRaw] of Object.entries(files)) {
+    const mutants = fileRaw?.mutants;
+    if (!Array.isArray(mutants)) {
+      return { error: `files["${path3}"] is missing a "mutants" array` };
+    }
+    const fileCounts = emptyCounts();
+    for (const m of mutants) {
+      const status = m?.status;
+      tally(fileCounts, status);
+      tally(total, status);
+    }
+    perFile.push({ path: path3, counts: fileCounts });
+  }
+  return { report: { counts: total, files: perFile } };
+}
+function computeScores(counts) {
+  const detected = counts.killed + counts.timeout;
+  const undetected = counts.survived + counts.noCoverage;
+  const valid = detected + undetected;
+  const covered = detected + counts.survived;
+  return {
+    detected,
+    undetected,
+    valid,
+    covered,
+    mutationScore: valid > 0 ? detected / valid * 100 : null,
+    mutationScoreBasedOnCoveredCode: covered > 0 ? detected / covered * 100 : null
+  };
+}
+function evaluateGate(report, threshold) {
+  const scores = computeScores(report.counts);
+  const reasons = [];
+  if (scores.valid === 0) {
+    reasons.push("no valid mutants were produced \u2014 nothing to prove the suite against");
+  } else if (scores.detected === 0) {
+    reasons.push(
+      `the suite killed 0 of ${scores.valid} mutants \u2014 it detects no injected bug (AC1)`
+    );
+  }
+  if (threshold !== null && scores.mutationScore !== null && scores.detected > 0 && scores.mutationScore < threshold) {
+    reasons.push(
+      `mutation score ${scores.mutationScore.toFixed(1)}% is below the required ${threshold}% threshold`
+    );
+  }
+  return {
+    passed: reasons.length === 0,
+    counts: report.counts,
+    scores,
+    threshold,
+    reasons,
+    files: report.files.map((f) => ({
+      path: f.path,
+      counts: f.counts,
+      scores: computeScores(f.counts)
+    }))
+  };
+}
+function gateExitCode(report) {
+  return report.passed ? EXIT.OK : EXIT.GATE_FAILED;
+}
+function scoreLabel(score) {
+  return score === null ? "n/a" : `${score.toFixed(1)}%`;
+}
+function toText(report) {
+  const { counts, scores } = report;
+  const lines = [];
+  const verdict = report.passed ? "PASS" : "REJECT";
+  lines.push(
+    `[${verdict}] mutation gate \u2014 score ${scoreLabel(scores.mutationScore)} (detected ${scores.detected}/${scores.valid})`
+  );
+  lines.push(
+    `       killed ${counts.killed} \xB7 timeout ${counts.timeout} \xB7 survived ${counts.survived} \xB7 no-coverage ${counts.noCoverage}` + (counts.invalid > 0 ? ` \xB7 uncounted ${counts.invalid}` : "")
+  );
+  if (report.threshold !== null) {
+    lines.push(
+      `       threshold ${report.threshold}% (covered-code score ${scoreLabel(scores.mutationScoreBasedOnCoveredCode)})`
+    );
+  }
+  if (report.files.length > 1) {
+    for (const f of report.files) {
+      lines.push(`       ${scoreLabel(f.scores.mutationScore).padStart(6)}  ${f.path}`);
+    }
+  }
+  if (!report.passed) {
+    lines.push("");
+    for (const r of report.reasons) lines.push(`  \u2717 ${r}`);
+  }
+  return lines.join("\n");
+}
+function formatGateReport(report) {
+  return toText(report);
+}
+function gateReportToJson(report) {
+  return {
+    ok: report.passed,
+    mutationScore: report.scores.mutationScore,
+    mutationScoreBasedOnCoveredCode: report.scores.mutationScoreBasedOnCoveredCode,
+    threshold: report.threshold,
+    counts: report.counts,
+    detected: report.scores.detected,
+    valid: report.scores.valid,
+    reasons: report.reasons,
+    files: report.files.map((f) => ({
+      path: f.path,
+      mutationScore: f.scores.mutationScore,
+      counts: f.counts
+    }))
+  };
+}
+var GATE_HELP = [
+  "Usage:",
+  "  hs test gate [<project-dir>] [--report <mutation-report.json>] [--threshold <0-100>] [--json]",
+  "",
+  "The deterministic mutation-testing gate (HS-EPIC-X7C8). A mutation runner",
+  "(Stryker / equivalent) injects bugs; a suite that kills NO mutants detects no",
+  "injected bug and is REJECTED. Tests may be written by your own AI agent \u2014 the",
+  "gate is what makes them trustworthy. HeySpex builds no AI and adds no COGS.",
+  "",
+  "Input is a Stryker mutation-report.json in the cross-tool",
+  "mutation-testing-elements schema, so any runner that emits it can feed the gate.",
+  "",
+  "Arguments:",
+  "  <project-dir>     Where to run the mutation runner (default: current dir).",
+  "                    Ignored when --report points at an existing report.",
+  "",
+  "Flags:",
+  "  --report <path>   Gate an existing mutation-report.json (no runner spawn).",
+  "  --threshold <n>   Also reject if the mutation score is below n% (0\u2013100).",
+  "  --json            Emit a machine-readable JSON result.",
+  "  --help, -h        Show this help.",
+  "",
+  "Exit codes:",
+  "  0 pass \xB7 1 usage \xB7 10 not-found \xB7 11 bad-report \xB7 12 runner-missing \xB7 20 gate-rejected"
+].join("\n");
+
+// spex-console/src/lib/cli/schema-conformance.ts
+var EXIT2 = {
+  /** The implementation conforms to the spec — no drift. */
+  OK: 0,
+  /** Usage error — unknown flag, bad verb, or missing required argument. */
+  USAGE: 1,
+  /** Spec / report file not found. */
+  NOT_FOUND: 10,
+  /** Report present but malformed (not parseable JUnit XML). */
+  INVALID_REPORT: 11,
+  /** Schemathesis is not installed / not on PATH. */
+  RUNNER_MISSING: 12,
+  /** Conformance ran and found drift (a real divergence, not a harness error). */
+  DRIFT_FOUND: 20
+};
+function parseConformArgs(argv) {
+  const verbRaw = argv[0];
+  if (verbRaw === "--help" || verbRaw === "-h") return { help: true };
+  if (verbRaw !== "conform") {
+    return { error: { code: EXIT2.USAGE, message: `unknown verb: ${verbRaw ?? "(none)"}` } };
+  }
+  let spec;
+  let baseUrl = null;
+  let reportPath = null;
+  let json = false;
+  for (let i = 1; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") return { help: true };
+    else if (arg === "--json") json = true;
+    else if (arg === "--url" || arg.startsWith("--url=")) {
+      const value = arg.includes("=") ? arg.slice("--url=".length) : argv[++i];
+      if (value === void 0 || value.trim() === "") {
+        return { error: { code: EXIT2.USAGE, message: "--url requires a base URL" } };
+      }
+      baseUrl = value;
+    } else if (arg === "--report" || arg.startsWith("--report=")) {
+      const value = arg.includes("=") ? arg.slice("--report=".length) : argv[++i];
+      if (value === void 0 || value.trim() === "") {
+        return { error: { code: EXIT2.USAGE, message: "--report requires a path" } };
+      }
+      reportPath = value;
+    } else if (arg.startsWith("-")) {
+      return { error: { code: EXIT2.USAGE, message: `unknown flag: ${arg}` } };
+    } else if (spec === void 0) {
+      spec = arg;
+    } else {
+      return { error: { code: EXIT2.USAGE, message: `unexpected argument: ${arg}` } };
+    }
+  }
+  if (reportPath === null) {
+    if (!spec) {
+      return {
+        error: {
+          code: EXIT2.USAGE,
+          message: "conform requires an OpenAPI spec (or --report <junit.xml>)"
+        }
+      };
+    }
+    if (!baseUrl) {
+      return {
+        error: {
+          code: EXIT2.USAGE,
+          message: "conform requires --url <base-url> when running Schemathesis"
+        }
+      };
+    }
+  }
+  return { args: { verb: "conform", spec: spec ?? "", baseUrl, reportPath, json } };
+}
+function decodeXml(s) {
+  return s.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&amp;/g, "&");
+}
+function attr(attrs, key) {
+  const m = attrs.match(new RegExp(`\\b${key}\\s*=\\s*"([^"]*)"|\\b${key}\\s*=\\s*'([^']*)'`));
+  if (!m) return null;
+  return decodeXml(m[1] ?? m[2] ?? "");
+}
+function parseJUnitReport(xml) {
+  if (typeof xml !== "string" || !/<testsuites?\b|<testcase\b/.test(xml)) {
+    return { error: "report is not JUnit XML (no <testsuite>/<testcase> found)" };
+  }
+  const findings = [];
+  let total = 0;
+  const caseRe = /<testcase\b([^>]*?)(\/>|>([\s\S]*?)<\/testcase>)/g;
+  let m;
+  while ((m = caseRe.exec(xml)) !== null) {
+    total += 1;
+    const attrs = m[1];
+    const body = m[3] ?? "";
+    const operation = attr(attrs, "name") ?? attr(attrs, "classname") ?? "(unnamed operation)";
+    const failRe = /<(failure|error)\b([^>]*?)(\/>|>([\s\S]*?)<\/\1>)/g;
+    let f;
+    while ((f = failRe.exec(body)) !== null) {
+      const kind = f[1] === "error" ? "error" : "failure";
+      const failAttrs = f[2];
+      const text = (f[4] ?? "").trim();
+      const messageAttr = attr(failAttrs, "message");
+      const message = messageAttr && messageAttr.trim() || decodeXml(text) || "conformance check failed";
+      findings.push({ operation, kind, message });
+    }
+  }
+  const failed = new Set(findings.map((x) => x.operation)).size;
+  return { report: { findings, total, failed, passed: findings.length === 0 } };
+}
+function conformExitCode(report) {
+  return report.passed ? EXIT2.OK : EXIT2.DRIFT_FOUND;
+}
+function oneLine(message) {
+  const line = message.split("\n").map((l) => l.trim()).filter(Boolean)[0] ?? message.trim();
+  return line.length > 160 ? `${line.slice(0, 157)}\u2026` : line;
+}
+function toText2(report) {
+  if (report.total === 0) {
+    return "No operations exercised (empty Schemathesis report).";
+  }
+  if (report.passed) {
+    return `[PASS] OpenAPI conformance \u2014 ${report.total} operation(s) conform, no drift.`;
+  }
+  const lines = [
+    `[DRIFT] OpenAPI conformance \u2014 ${report.failed}/${report.total} operation(s) diverge from the spec:`
+  ];
+  for (const f of report.findings) {
+    lines.push(`  \u2717 ${f.operation} \u2014 ${oneLine(f.message)}`);
+  }
+  return lines.join("\n");
+}
+function formatConformReport(report) {
+  return toText2(report);
+}
+function conformReportToJson(report) {
+  return {
+    ok: report.passed,
+    total: report.total,
+    failed: report.failed,
+    drift: report.findings.map((f) => ({
+      operation: f.operation,
+      kind: f.kind,
+      message: f.message
+    }))
+  };
+}
+var CONFORM_HELP = [
+  "Usage:",
+  "  hs test conform <openapi-spec> --url <base-url> [--json]",
+  "  hs test conform --report <schemathesis-junit.xml> [--json]",
+  "",
+  "OpenAPI conformance + docs\u2194implementation drift (HS-EPIC-X7C8 AC2). Schemathesis",
+  "generates deterministic property-based cases from the spec and runs them against",
+  "the live API; any response/schema divergence is surfaced as a drift finding. The",
+  "spec is the docs, the live responses are the implementation \u2014 a divergence is",
+  "docs\u2194impl drift. HeySpex builds no AI and adds no COGS.",
+  "",
+  "Arguments:",
+  "  <openapi-spec>    Path or URL to the OpenAPI/Swagger document.",
+  "",
+  "Flags:",
+  "  --url <base>      Base URL of the running API under test (required to run).",
+  "  --report <path>   Evaluate an existing Schemathesis JUnit report (no spawn).",
+  "  --json            Emit a machine-readable JSON result.",
+  "  --help, -h        Show this help.",
+  "",
+  "Requires Schemathesis on PATH (pip install schemathesis). Exit codes:",
+  "  0 conforms \xB7 1 usage \xB7 10 not-found \xB7 11 bad-report \xB7 12 schemathesis-missing \xB7 20 drift-found"
+].join("\n");
+
+// spex-console/src/lib/cli/test-run.ts
+var EXIT3 = {
+  /** Success — every test (and thus every linked acceptance criterion) passed. */
+  OK: 0,
+  /** Usage error — unknown flag, missing target, or bad verb. */
+  USAGE: 1,
+  /** Manifest / target not found. */
+  NOT_FOUND: 10,
+  /** Manifest present but malformed (not `{ tests: [...] }`, or a test lacks `file`). */
+  INVALID_MANIFEST: 11,
+  /** The Hurl runner is not installed / not on PATH. */
+  RUNNER_MISSING: 12,
+  /** Tests ran and at least one failed (a real red, not a harness error). */
+  TESTS_FAILED: 20
+};
+var UNLINKED = "(unlinked)";
+function parseTestRunArgs(argv) {
+  const verbRaw = argv[0];
+  if (verbRaw === "--help" || verbRaw === "-h") return { help: true };
+  if (verbRaw !== "run") {
+    return { error: { code: EXIT3.USAGE, message: `unknown verb: ${verbRaw ?? "(none)"}` } };
+  }
+  let target;
+  let format = "text";
+  let json = false;
+  for (let i = 1; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") return { help: true };
+    else if (arg === "--json") json = true;
+    else if (arg === "--format" || arg.startsWith("--format=")) {
+      const value = arg.includes("=") ? arg.slice("--format=".length) : argv[++i];
+      if (value === void 0) {
+        return {
+          error: { code: EXIT3.USAGE, message: "--format requires a value (text|junit|tap)" }
+        };
+      }
+      if (value !== "text" && value !== "junit" && value !== "tap") {
+        return {
+          error: {
+            code: EXIT3.USAGE,
+            message: `unknown format: ${value} (expected text|junit|tap)`
+          }
+        };
+      }
+      format = value;
+    } else if (arg === "--manifest" || arg.startsWith("--manifest=")) {
+      const value = arg.includes("=") ? arg.slice("--manifest=".length) : argv[++i];
+      if (value === void 0) {
+        return { error: { code: EXIT3.USAGE, message: "--manifest requires a value" } };
+      }
+      target = value;
+    } else if (arg.startsWith("-")) {
+      return { error: { code: EXIT3.USAGE, message: `unknown flag: ${arg}` } };
+    } else if (target === void 0) {
+      target = arg;
+    } else {
+      return { error: { code: EXIT3.USAGE, message: `unexpected argument: ${arg}` } };
+    }
+  }
+  if (!target) {
+    return { error: { code: EXIT3.USAGE, message: "run requires a spec id or manifest path" } };
+  }
+  return { args: { verb: "run", target, format, json } };
+}
+function basename(file) {
+  const parts = file.split(/[\\/]/);
+  return parts[parts.length - 1] || file;
+}
+function parseManifest(text) {
+  let raw;
+  try {
+    raw = JSON.parse(text);
+  } catch (err) {
+    return {
+      error: `manifest is not valid JSON: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+  if (typeof raw !== "object" || raw === null || !Array.isArray(raw.tests)) {
+    return { error: "manifest must be an object with a `tests` array" };
+  }
+  const tests = [];
+  const rawTests = raw.tests;
+  for (let i = 0; i < rawTests.length; i++) {
+    const t = rawTests[i];
+    if (typeof t !== "object" || t === null) {
+      return { error: `tests[${i}] must be an object` };
+    }
+    const rec = t;
+    if (typeof rec.file !== "string" || rec.file.trim() === "") {
+      return { error: `tests[${i}] is missing a non-empty "file"` };
+    }
+    const file = rec.file;
+    const name = typeof rec.name === "string" && rec.name.trim() !== "" ? rec.name : basename(file);
+    const acRaw = rec.linked_ac ?? rec.linkedAc;
+    const linkedAc = typeof acRaw === "string" && acRaw.trim() !== "" ? acRaw : null;
+    tests.push({ file, name, linkedAc });
+  }
+  return { manifest: { tests } };
+}
+function aggregateByAc(executions) {
+  const order = [];
+  const byAc = /* @__PURE__ */ new Map();
+  for (const ex of executions) {
+    const ac = ex.entry.linkedAc ?? UNLINKED;
+    let agg = byAc.get(ac);
+    if (!agg) {
+      agg = { total: 0, failed: 0 };
+      byAc.set(ac, agg);
+      order.push(ac);
+    }
+    agg.total += 1;
+    if (!ex.passed) agg.failed += 1;
+  }
+  return order.map((ac) => {
+    const agg = byAc.get(ac);
+    return { ac, passed: agg.failed === 0, total: agg.total, failed: agg.failed };
+  });
+}
+async function runManifest(tests, deps) {
+  const executions = [];
+  for (const entry of tests) {
+    let outcome;
+    try {
+      outcome = await deps.runHurl(entry.file);
+    } catch (err) {
+      outcome = {
+        passed: false,
+        durationMs: 0,
+        message: err instanceof Error ? err.message : String(err)
+      };
+    }
+    executions.push({
+      entry,
+      passed: outcome.passed,
+      durationMs: outcome.durationMs,
+      message: outcome.passed ? void 0 : outcome.message
+    });
+  }
+  const failedCount = executions.filter((e) => !e.passed).length;
+  const durationMs = executions.reduce((sum, e) => sum + e.durationMs, 0);
+  return {
+    executions,
+    acResults: aggregateByAc(executions),
+    passed: failedCount === 0,
+    total: executions.length,
+    failedCount,
+    durationMs
+  };
+}
+function reportExitCode(report) {
+  return report.passed ? EXIT3.OK : EXIT3.TESTS_FAILED;
+}
+function escapeXml(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+function secs(ms) {
+  return (ms / 1e3).toFixed(3);
+}
+function toJUnit(report) {
+  const lines = [];
+  lines.push('<?xml version="1.0" encoding="UTF-8"?>');
+  lines.push(
+    `<testsuites name="hs test run" tests="${report.total}" failures="${report.failedCount}" time="${secs(report.durationMs)}">`
+  );
+  for (const ac of report.acResults) {
+    const acExecs = report.executions.filter((e) => (e.entry.linkedAc ?? UNLINKED) === ac.ac);
+    const acTime = acExecs.reduce((s, e) => s + e.durationMs, 0);
+    lines.push(
+      `  <testsuite name="${escapeXml(ac.ac)}" tests="${ac.total}" failures="${ac.failed}" time="${secs(acTime)}">`
+    );
+    for (const e of acExecs) {
+      const open = `    <testcase name="${escapeXml(e.entry.name)}" time="${secs(e.durationMs)}">`;
+      if (e.passed) {
+        lines.push(`${open}</testcase>`);
+      } else {
+        lines.push(open);
+        lines.push(`      <failure message="${escapeXml(e.message ?? "test failed")}"></failure>`);
+        lines.push("    </testcase>");
+      }
+    }
+    lines.push("  </testsuite>");
+  }
+  lines.push("</testsuites>");
+  return lines.join("\n");
+}
+function toTap(report) {
+  const lines = ["TAP version 13", `1..${report.total}`];
+  report.executions.forEach((e, i) => {
+    const status = e.passed ? "ok" : "not ok";
+    const ac = e.entry.linkedAc ? ` # AC ${e.entry.linkedAc}` : "";
+    lines.push(`${status} ${i + 1} - ${e.entry.name}${ac}`);
+    if (!e.passed && e.message) {
+      lines.push(`  ---`);
+      lines.push(`  message: ${e.message}`);
+      lines.push(`  ...`);
+    }
+  });
+  return lines.join("\n");
+}
+function toText3(report) {
+  if (report.total === 0) {
+    return "No tests in manifest.";
+  }
+  const lines = [];
+  for (const ac of report.acResults) {
+    const mark = ac.passed ? "PASS" : "FAIL";
+    lines.push(`[${mark}] ${ac.ac}  (${ac.total - ac.failed}/${ac.total})`);
+    for (const e of report.executions.filter((x) => (x.entry.linkedAc ?? UNLINKED) === ac.ac)) {
+      const m = e.passed ? "ok  " : "FAIL";
+      const detail = !e.passed && e.message ? ` \u2014 ${e.message}` : "";
+      lines.push(`       ${m} ${e.entry.name} (${e.durationMs}ms)${detail}`);
+    }
+  }
+  const overall = report.passed ? "PASS" : "FAIL";
+  lines.push("");
+  lines.push(
+    `${overall}: ${report.total - report.failedCount}/${report.total} tests, ${report.acResults.filter((a) => a.passed).length}/${report.acResults.length} acceptance criteria (${report.durationMs}ms)`
+  );
+  return lines.join("\n");
+}
+function formatReport(report, format) {
+  switch (format) {
+    case "junit":
+      return toJUnit(report);
+    case "tap":
+      return toTap(report);
+    case "text":
+    default:
+      return toText3(report);
+  }
+}
+function reportToJson(report) {
+  return {
+    ok: report.passed,
+    total: report.total,
+    failed: report.failedCount,
+    durationMs: report.durationMs,
+    acceptanceCriteria: report.acResults,
+    tests: report.executions.map((e) => ({
+      name: e.entry.name,
+      file: e.entry.file,
+      linkedAc: e.entry.linkedAc,
+      passed: e.passed,
+      durationMs: e.durationMs,
+      ...e.passed ? {} : { message: e.message }
+    }))
+  };
+}
+var HELP = [
+  "Usage:",
+  "  hs test run <spec-id|manifest.json> [--format text|junit|tap] [--json]",
+  "",
+  "Run open-format API/contract tests (Hurl/.http) bound to acceptance criteria,",
+  "and report pass/fail per acceptance criterion. Tests live as files in the repo",
+  "(tests-as-code), referenced by a thin JSON manifest carrying each test's",
+  "`linked_ac`. Supersedes the proprietary .spex plan (HS-EPIC-Q0KU).",
+  "",
+  "Manifest shape:",
+  '  { "tests": [ { "file": "tests/get-spec.hurl",',
+  '                 "name": "get spec by id",',
+  '                 "linked_ac": "[[HS-TASK-XYZ]]#AC1" } ] }',
+  "",
+  "Arguments:",
+  "  <spec-id|manifest.json>  A manifest path, or a spec id the shell resolves to one.",
+  "",
+  "Flags:",
+  "  --format <fmt>   text (default), junit, or tap. JUnit/TAP are CI-consumable.",
+  "  --manifest <p>   Manifest path (alias for the positional argument).",
+  "  --json           Emit a machine-readable JSON result.",
+  "  --help, -h       Show this help.",
+  "",
+  "Requires the Hurl runner on PATH (https://hurl.dev). Exit codes:",
+  "  0 ok \xB7 1 usage \xB7 10 not-found \xB7 11 bad-manifest \xB7 12 hurl-missing \xB7 20 tests-failed"
+].join("\n");
+
+// spex-console/src/lib/server/api-test-host.ts
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+// spex-console/src/lib/resolution/api-test-failures.ts
+var API_TEST_RUN_SNAPSHOT_PATH = ".heyspex/code-watcher/api-test-run.json";
+
+// spex-console/src/lib/server/api-test-host.ts
+function manifestForSpecId(vaultRoot, specId) {
+  return path.join(vaultRoot, "tests", `${specId}.manifest.json`);
+}
+function resolveManifestPath(target, vaultRoot, cwd = process.cwd()) {
+  const literal = path.resolve(cwd, target);
+  if (existsSync(literal)) return literal;
+  if (target.endsWith(".json")) return null;
+  const byId = manifestForSpecId(vaultRoot, target);
+  return existsSync(byId) ? byId : null;
+}
+function hurlAvailable() {
+  try {
+    const res = spawnSync("hurl", ["--version"], { stdio: "ignore" });
+    return res.status === 0;
+  } catch {
+    return false;
+  }
+}
+function runHurlFile(file) {
+  return new Promise((resolve) => {
+    const started = Date.now();
+    const child = spawn("hurl", ["--test", file], { stdio: ["ignore", "ignore", "pipe"] });
+    let stderr = "";
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on("error", (err) => {
+      resolve({ passed: false, durationMs: Date.now() - started, message: err.message });
+    });
+    child.on("close", (code) => {
+      const durationMs = Date.now() - started;
+      if (code === 0) {
+        resolve({ passed: true, durationMs });
+      } else {
+        const trimmed = stderr.trim();
+        resolve({
+          passed: false,
+          durationMs,
+          message: trimmed.length > 0 ? trimmed.split("\n").slice(-3).join(" ") : `hurl exited ${code}`
+        });
+      }
+    });
+  });
+}
+function writeRunSnapshot(vaultRoot, target, report) {
+  const snapshot = {
+    schemaVersion: 1,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    target,
+    total: report.total,
+    failures: report.executions.filter((e) => !e.passed).map((e) => ({
+      file: path.relative(vaultRoot, e.entry.file).split(path.sep).join("/"),
+      name: e.entry.name,
+      linkedAc: e.entry.linkedAc,
+      ...e.message ? { message: e.message } : {}
+    }))
+  };
+  const outFile = path.join(vaultRoot, API_TEST_RUN_SNAPSHOT_PATH);
+  mkdirSync(path.dirname(outFile), { recursive: true });
+  writeFileSync(outFile, `${JSON.stringify(snapshot, null, 2)}
+`, "utf8");
+  return snapshot;
+}
+
+// spex-console/bin/run-entry.ts
+import process2 from "node:process";
+var BinExit = class extends Error {
+  code;
+  constructor(code) {
+    super(`exit ${code}`);
+    this.name = "BinExit";
+    this.code = code;
+  }
+};
+function runEntry(name, main2, options = {}) {
+  const { fallbackCode = 1, unhandledLabel = "unhandled" } = options;
+  void (async () => {
+    try {
+      await main2();
+    } catch (err) {
+      if (err instanceof BinExit) {
+        process2.exitCode = err.code;
+        return;
+      }
+      const message = err instanceof Error ? err.message : String(err);
+      process2.stderr.write(`${name}: ${unhandledLabel}: ${message}
+`);
+      process2.exitCode = fallbackCode;
+    }
+  })();
+}
+
+// spex-console/bin/hs-test.ts
+var invokedCwd = process3.env.HS_INVOKED_CWD?.trim() || process3.cwd();
+async function runVerb(vaultRoot) {
+  const parsed = parseTestRunArgs(process3.argv.slice(3));
+  if (parsed.help) {
+    process3.stdout.write(`${HELP}
+`);
+    process3.exitCode = EXIT3.OK;
+    return;
+  }
+  if (parsed.error) {
+    process3.stderr.write(`hs test: ${parsed.error.message}
+`);
+    process3.exitCode = parsed.error.code;
+    return;
+  }
+  const args = parsed.args;
+  const manifestPath = resolveManifestPath(args.target, vaultRoot, invokedCwd);
+  if (!manifestPath) {
+    process3.stderr.write(
+      `hs test: no manifest for "${args.target}".
+  Pass a manifest path, or create ${path2.join("tests", `${args.target}.manifest.json`)} under the vault root.
+`
+    );
+    process3.exitCode = EXIT3.NOT_FOUND;
+    return;
+  }
+  const { manifest, error } = parseManifest(readFileSync(manifestPath, "utf-8"));
+  if (error) {
+    process3.stderr.write(`hs test: ${manifestPath}: ${error}
+`);
+    process3.exitCode = EXIT3.INVALID_MANIFEST;
+    return;
+  }
+  const manifestDir = path2.dirname(manifestPath);
+  const tests = manifest.tests.map((t) => ({
+    ...t,
+    file: path2.isAbsolute(t.file) ? t.file : path2.resolve(manifestDir, t.file)
+  }));
+  if (tests.length > 0 && !hurlAvailable()) {
+    process3.stderr.write(
+      "hs test: the Hurl runner is not installed or not on PATH.\n  Install it from https://hurl.dev (e.g. `winget install Orange-OpenSource.Hurl`),\n  or `scoop install hurl` / `brew install hurl`.\n"
+    );
+    process3.exitCode = EXIT3.RUNNER_MISSING;
+    return;
+  }
+  const report = await runManifest(tests, { runHurl: runHurlFile });
+  try {
+    writeRunSnapshot(vaultRoot, args.target, report);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    process3.stderr.write(`hs test: warning \u2014 could not write the run snapshot: ${message}
+`);
+  }
+  if (args.json) {
+    const sink = report.passed ? process3.stdout : process3.stderr;
+    sink.write(`${JSON.stringify(reportToJson(report))}
+`);
+  } else {
+    const sink = report.passed ? process3.stdout : process3.stderr;
+    sink.write(`${formatReport(report, args.format)}
+`);
+  }
+  process3.exitCode = reportExitCode(report);
+}
+function strykerAvailable(projectDir) {
+  try {
+    const res = process3.platform === "win32" ? spawnSync2("cmd", ["/c", "npx", "--no-install", "stryker", "--version"], {
+      cwd: projectDir,
+      stdio: "ignore"
+    }) : spawnSync2("npx", ["--no-install", "stryker", "--version"], {
+      cwd: projectDir,
+      stdio: "ignore"
+    });
+    return res.status === 0;
+  } catch {
+    return false;
+  }
+}
+function runStryker(projectDir) {
+  return new Promise((resolve) => {
+    const child = process3.platform === "win32" ? spawn2("cmd", ["/c", "npx", "--no-install", "stryker", "run"], {
+      cwd: projectDir,
+      stdio: "inherit"
+    }) : spawn2("npx", ["--no-install", "stryker", "run"], { cwd: projectDir, stdio: "inherit" });
+    child.on("error", () => resolve(-1));
+    child.on("close", (code) => resolve(code ?? -1));
+  });
+}
+async function gateVerb(vaultRoot) {
+  const parsed = parseGateArgs(process3.argv.slice(3));
+  if (parsed.help) {
+    process3.stdout.write(`${GATE_HELP}
+`);
+    process3.exitCode = EXIT.OK;
+    return;
+  }
+  if (parsed.error) {
+    process3.stderr.write(`hs test: ${parsed.error.message}
+`);
+    process3.exitCode = parsed.error.code;
+    return;
+  }
+  const args = parsed.args;
+  const projectDir = path2.isAbsolute(args.target) ? args.target : path2.resolve(vaultRoot, args.target);
+  const DEFAULT_REPORT = path2.join(projectDir, "reports", "mutation", "mutation.json");
+  let reportFile;
+  if (args.reportPath) {
+    reportFile = path2.isAbsolute(args.reportPath) ? args.reportPath : path2.resolve(invokedCwd, args.reportPath);
+    if (!existsSync2(reportFile)) {
+      process3.stderr.write(`hs test: mutation report not found: ${reportFile}
+`);
+      process3.exitCode = EXIT.NOT_FOUND;
+      return;
+    }
+  } else {
+    if (!strykerAvailable(projectDir)) {
+      process3.stderr.write(
+        "hs test: the mutation runner (Stryker) is not installed in this project.\n  Add it (e.g. `npm i -D @stryker-mutator/core`) and enable the json reporter,\n  or pass an existing report with --report <mutation-report.json>.\n"
+      );
+      process3.exitCode = EXIT.RUNNER_MISSING;
+      return;
+    }
+    const code = await runStryker(projectDir);
+    if (code !== 0) {
+      process3.stderr.write(
+        `hs test: the mutation runner exited ${code} before producing a report.
+`
+      );
+      process3.exitCode = EXIT.RUNNER_MISSING;
+      return;
+    }
+    reportFile = DEFAULT_REPORT;
+    if (!existsSync2(reportFile)) {
+      process3.stderr.write(
+        `hs test: the runner finished but no report was found at ${reportFile}.
+  Enable Stryker's json reporter so it writes reports/mutation/mutation.json.
+`
+      );
+      process3.exitCode = EXIT.NOT_FOUND;
+      return;
+    }
+  }
+  const { report, error } = parseMutationReport(readFileSync(reportFile, "utf-8"));
+  if (error) {
+    process3.stderr.write(`hs test: ${reportFile}: ${error}
+`);
+    process3.exitCode = EXIT.INVALID_REPORT;
+    return;
+  }
+  const gate = evaluateGate(report, args.threshold);
+  const sink = gate.passed ? process3.stdout : process3.stderr;
+  if (args.json) {
+    sink.write(`${JSON.stringify(gateReportToJson(gate))}
+`);
+  } else {
+    sink.write(`${formatGateReport(gate)}
+`);
+  }
+  process3.exitCode = gateExitCode(gate);
+}
+function schemathesisAvailable() {
+  try {
+    const res = process3.platform === "win32" ? spawnSync2("cmd", ["/c", "st", "--version"], { stdio: "ignore" }) : spawnSync2("st", ["--version"], { stdio: "ignore" });
+    return res.status === 0;
+  } catch {
+    return false;
+  }
+}
+function runSchemathesis(spec, baseUrl, junitOut) {
+  const stArgs = ["run", spec, "--url", baseUrl, "--junit-xml", junitOut];
+  return new Promise((resolve) => {
+    const child = process3.platform === "win32" ? spawn2("cmd", ["/c", "st", ...stArgs], { stdio: "inherit" }) : spawn2("st", stArgs, { stdio: "inherit" });
+    child.on("error", () => resolve(-1));
+    child.on("close", (code) => resolve(code ?? -1));
+  });
+}
+async function conformVerb(vaultRoot) {
+  const parsed = parseConformArgs(process3.argv.slice(3));
+  if (parsed.help) {
+    process3.stdout.write(`${CONFORM_HELP}
+`);
+    process3.exitCode = EXIT2.OK;
+    return;
+  }
+  if (parsed.error) {
+    process3.stderr.write(`hs test: ${parsed.error.message}
+`);
+    process3.exitCode = parsed.error.code;
+    return;
+  }
+  const args = parsed.args;
+  let reportFile;
+  if (args.reportPath) {
+    reportFile = path2.isAbsolute(args.reportPath) ? args.reportPath : path2.resolve(invokedCwd, args.reportPath);
+    if (!existsSync2(reportFile)) {
+      process3.stderr.write(`hs test: conformance report not found: ${reportFile}
+`);
+      process3.exitCode = EXIT2.NOT_FOUND;
+      return;
+    }
+  } else {
+    const specIsUrl = /^https?:\/\//i.test(args.spec);
+    const specPath = specIsUrl ? args.spec : path2.isAbsolute(args.spec) ? args.spec : path2.resolve(vaultRoot, args.spec);
+    if (!specIsUrl && !existsSync2(specPath)) {
+      process3.stderr.write(`hs test: OpenAPI spec not found: ${specPath}
+`);
+      process3.exitCode = EXIT2.NOT_FOUND;
+      return;
+    }
+    if (!schemathesisAvailable()) {
+      process3.stderr.write(
+        "hs test: Schemathesis is not installed or not on PATH.\n  Install it (e.g. `pip install schemathesis` / `uv tool install schemathesis`),\n  or pass an existing report with --report <schemathesis-junit.xml>.\n"
+      );
+      process3.exitCode = EXIT2.RUNNER_MISSING;
+      return;
+    }
+    reportFile = path2.join(os.tmpdir(), "hs-conform-junit.xml");
+    await runSchemathesis(specPath, args.baseUrl, reportFile);
+    if (!existsSync2(reportFile)) {
+      process3.stderr.write(
+        `hs test: Schemathesis finished but wrote no report at ${reportFile}.
+`
+      );
+      process3.exitCode = EXIT2.NOT_FOUND;
+      return;
+    }
+  }
+  const { report, error } = parseJUnitReport(readFileSync(reportFile, "utf-8"));
+  if (error) {
+    process3.stderr.write(`hs test: ${reportFile}: ${error}
+`);
+    process3.exitCode = EXIT2.INVALID_REPORT;
+    return;
+  }
+  const sink = report.passed ? process3.stdout : process3.stderr;
+  if (args.json) {
+    sink.write(`${JSON.stringify(conformReportToJson(report))}
+`);
+  } else {
+    sink.write(`${formatConformReport(report)}
+`);
+  }
+  process3.exitCode = conformExitCode(report);
+}
+async function main() {
+  const vaultRoot = process3.env.HS_VAULT_ROOT;
+  if (!vaultRoot) {
+    process3.stderr.write(
+      "hs test: HS_VAULT_ROOT is not set (the dispatcher must resolve and pass it).\n"
+    );
+    process3.exitCode = EXIT3.USAGE;
+    return;
+  }
+  const verb = process3.argv[3];
+  if (verb === "gate") {
+    await gateVerb(vaultRoot);
+  } else if (verb === "conform") {
+    await conformVerb(vaultRoot);
+  } else {
+    await runVerb(vaultRoot);
+  }
+}
+runEntry("hs test", main, { fallbackCode: EXIT3.RUNNER_MISSING });