@skyramp/mcp 0.4.1 → 0.4.2-rc.2

package/build/tools/runExistingTestsTool.js

@@ -1,644 +0,0 @@
-import { z } from "zod";
-import * as os from "os";
-import * as path from "path";
-import * as crypto from "crypto";
-import { promises as fs } from "fs";
-import { spawn } from "child_process";
-import { stripVTControlCharacters } from "util";
-import { WorkspaceConfigManager } from "../workspace/workspace.js";
-import { resolveSuites } from "../workspace/testSuites.js";
-import { StateManager, } from "../utils/AnalysisStateManager.js";
-import { buildPlaywrightArgs, parsePlaywrightJson, } from "../adapters/playwrightAdapter.js";
-import { buildPytestArgs, parsePytestJson } from "../adapters/pytestAdapter.js";
-import { buildJestArgs, buildVitestArgs, parseJestJson } from "../adapters/jestAdapter.js";
-import { buildMochaArgs, parseMochaJson } from "../adapters/mochaAdapter.js";
-import picomatch from "picomatch";
-import { AnalyticsService } from "../services/AnalyticsService.js";
-import { logger } from "../utils/logger.js";
-import { toolError } from "../utils/utils.js";
-const TOOL_NAME = "skyramp_run_existing_tests";
-const playwrightSpec = {
-    framework: "playwright",
-    outputVia: "file",
-    reportEnvVar: "PLAYWRIGHT_JSON_OUTPUT_NAME",
-    buildArgs: ({ selectors, mode, project }) => buildPlaywrightArgs({ selectors, mode, project }),
-    parse: (report, opts) => parsePlaywrightJson(report, opts),
-};
-const pytestSpec = {
-    framework: "pytest",
-    outputVia: "file",
-    buildArgs: ({ selectors, mode, reportPath }) => buildPytestArgs({ selectors, mode, reportPath }),
-    parse: (report, opts) => parsePytestJson(report, opts),
-};
-const jestSpec = {
-    framework: "jest",
-    outputVia: "file",
-    buildArgs: ({ selectors, mode, reportPath }) => buildJestArgs({ selectors, mode, reportPath }),
-    parse: (report, opts) => parseJestJson(report, opts),
-};
-const vitestSpec = {
-    framework: "vitest",
-    outputVia: "file",
-    buildArgs: ({ selectors, mode, reportPath }) => buildVitestArgs({ selectors, mode, reportPath }),
-    parse: (report, opts) => parseJestJson(report, opts),
-};
-const mochaSpec = {
-    framework: "mocha",
-    outputVia: "stdout",
-    buildArgs: ({ selectors, mode }) => buildMochaArgs({ selectors, mode }),
-    parse: (report, opts) => parseMochaJson(report, opts),
-};
-/** framework → reader. */
-const READERS = {
-    playwright: playwrightSpec,
-    pytest: pytestSpec,
-    jest: jestSpec,
-    vitest: vitestSpec,
-    mocha: mochaSpec,
-};
-/** True when a framework has an execution reader (playwright/pytest/jest/vitest/mocha). */
-export function frameworkHasReader(framework) {
-    return !!framework && !!READERS[framework];
-}
-/** Extract the last complete top-level JSON object from a stdout blob that may
- *  carry interleaved non-JSON (e.g. a test's console.log before mocha's json
- *  reporter dumps its object). Scans brace depth while respecting string/escape
- *  context so braces inside strings do not miscount. Throws if none found. */
-export function extractLastJsonObject(s) {
-    let start = -1;
-    let depth = 0;
-    let inStr = false;
-    let esc = false;
-    let last = null;
-    for (let i = 0; i < s.length; i++) {
-        const c = s[i];
-        if (inStr) {
-            if (esc)
-                esc = false;
-            else if (c === "\\")
-                esc = true;
-            else if (c === '"')
-                inStr = false;
-            continue;
-        }
-        if (c === '"')
-            inStr = true;
-        else if (c === "{") {
-            if (depth === 0)
-                start = i;
-            depth++;
-        }
-        else if (c === "}") {
-            if (depth > 0 && --depth === 0 && start >= 0)
-                last = s.slice(start, i + 1);
-        }
-    }
-    if (last === null)
-        throw new Error("no JSON object in stdout");
-    return last;
-}
-/**
- * Resolves the runnable suites from workspace.yml (SKYR-4002). Enumerates every
- * (service, suite) via resolveSuites; a suite is runnable when its framework has
- * a registered reader (Playwright, pytest, jest, vitest, Mocha) — testRunCommand
- * is required non-empty by the schema. Suites whose framework has no reader become
- * skips-with-reason (never a throw). Every runnable suite runs. Throws only for an
- * explicitly-named unknown service.
- */
-export function resolveRunConfig(config, opts = {}) {
-    const services = config.services ?? [];
-    let target = services;
-    if (opts.service) {
-        const svc = services.find((s) => s.serviceName === opts.service);
-        if (!svc) {
-            throw new Error(`No service named "${opts.service}" in .skyramp/workspace.yml. Available: ${services.map((s) => s.serviceName).join(", ") || "(none)"}.`);
-        }
-        target = [svc];
-    }
-    const suites = target.flatMap(resolveSuites);
-    const skips = [];
-    const hasReader = (s) => frameworkHasReader(s.framework);
-    const runnable = suites.filter((s) => hasReader(s));
-    for (const s of suites) {
-        if (hasReader(s))
-            continue;
-        skips.push({
-            service: s.serviceName,
-            reason: `framework "${s.framework ?? "none"}" has no reader in ${TOOL_NAME} (supported: ${Object.keys(READERS).join(", ")}).`,
-        });
-    }
-    return { runs: runnable.map(toResolvedRunConfig), skips };
-}
-/** The file part of a selector — `file::test title` keeps only `file`. */
-function selectorFile(selector) {
-    const idx = selector.indexOf("::");
-    return (idx >= 0 ? selector.slice(0, idx) : selector).trim();
-}
-/**
- * Resolves a selector's file to a repo-relative path, the form `pathGlobs` are
- * written in.
- *
- * Selectors arrive in whatever form the caller used — repo-relative, absolute, or
- * a shorter tail. Discovery (analyze_changes) records the ABSOLUTE path of every
- * test it found, so those paths are the authority: when a selector does not
- * resolve to one of them directly, match it by tail to recover the real file.
- */
-function toRepoRelative(file, workspacePath, knownTestFiles) {
-    let abs = path.isAbsolute(file) ? file : path.resolve(workspacePath, file);
-    if (knownTestFiles?.length && !knownTestFiles.includes(abs)) {
-        const match = knownTestFiles.find((known) => known.endsWith(`/${file}`));
-        if (match)
-            abs = match;
-    }
-    return path.relative(workspacePath, abs);
-}
-/**
- * Partitions `selectors` into the ones this suite owns and the ones it does not,
- * using the suite's own `pathGlobs` from workspace.yml.
- *
- * One repo commonly hosts several runners (mocha for a core package, vitest for
- * app packages, Playwright for e2e), and handing a runner another runner's spec is
- * not a test failure — it is a loader crash that yields no report at all. Which
- * suite owns which paths is a fact about the repo, so it is recorded as config the
- * user can read and correct, rather than guessed at run time. Run 30297865488 is
- * the cautionary case: routing on a guessed framework tag sent Ghost's Playwright
- * specs away from the Playwright suite, and nothing ran.
- *
- * A suite with no globs owns everything. That is deliberate: absent globs means
- * the suite is unscoped, not that it owns nothing, and narrowing on no
- * information would silently shrink the run.
- */
-export function routeSelectorsToSuite(input) {
-    const globs = input.pathGlobs ?? [];
-    if (globs.length === 0)
-        return { kept: [...input.selectors], dropped: [] };
-    const kept = [];
-    const dropped = [];
-    for (const selector of input.selectors) {
-        const rel = toRepoRelative(selectorFile(selector), input.workspacePath, input.knownTestFiles);
-        if (picomatch.isMatch(rel, globs))
-            kept.push(selector);
-        else
-            dropped.push(selector);
-    }
-    return { kept, dropped };
-}
-/**
- * The absolute test-file paths analyze_changes recorded, used to canonicalize a
- * selector before glob matching. Best-effort: with no state file, an unreadable
- * one, or a repo section that was never written, routing just resolves selectors
- * against the repo root.
- */
-async function loadKnownTestFiles(stateFile, repository) {
-    if (!stateFile)
-        return [];
-    try {
-        const sm = StateManager.fromStatePath(stateFile);
-        const state = await sm.readRepoData(repository);
-        return (state?.existingTests ?? [])
-            .map((t) => t.testFile)
-            .filter((f) => !!f);
-    }
-    catch (err) {
-        logger.warning(`${TOOL_NAME}: could not read existingTests for selector routing: ${err.message}`);
-        return [];
-    }
-}
-/** Maps a NormalizedSuite to the run-time config the runner consumes. */
-function toResolvedRunConfig(s) {
-    return {
-        serviceName: s.serviceName,
-        framework: s.framework,
-        testRunCommand: s.testRunCommand,
-        testEnv: s.testEnv,
-        pathGlobs: s.pathGlobs,
-    };
-}
-/** Combines per-suite runs into one ParsedExternalRun for the tool's summary
- *  text: sums counts, concatenates results, ANDs environmentHealthy, joins the
- *  unhealthy details. */
-export function aggregateRuns(parsed) {
-    const summary = { ran: 0, failed: 0, errored: 0, skipped: 0, truncated: false };
-    const results = [];
-    let environmentHealthy = true;
-    const details = [];
-    // Diagnostics follow the same "first unhealthy suite wins" rule as healthDetail;
-    // when every suite is healthy (or there's a single suite) it's that suite's diagnostics.
-    let diagnostics = parsed[0]?.diagnostics;
-    let diagnosticsFromUnhealthy = false;
-    for (const p of parsed) {
-        summary.ran += p.summary.ran;
-        summary.failed += p.summary.failed;
-        summary.errored += p.summary.errored;
-        summary.skipped += p.summary.skipped;
-        summary.truncated = summary.truncated || p.summary.truncated;
-        results.push(...p.results);
-        if (!p.environmentHealthy) {
-            environmentHealthy = false;
-            if (p.healthDetail)
-                details.push(p.healthDetail);
-            if (!diagnosticsFromUnhealthy) {
-                diagnostics = p.diagnostics;
-                diagnosticsFromUnhealthy = true;
-            }
-        }
-    }
-    // Only when EVERY suite was skipped is the whole run a skip — otherwise the
-    // suites that did run own the verdict. Surfacing it matters: the tool's caller
-    // branches on `skipped` to say why nothing ran instead of reporting a bare
-    // "ran 0 tests", which reads as a clean pass.
-    const allSkipped = parsed.length > 0 && parsed.every((p) => p.skipped);
-    const skipReasons = parsed.map((p) => p.skipReason).filter(Boolean);
-    return {
-        results,
-        summary,
-        environmentHealthy,
-        healthDetail: details.length ? details.join(" | ") : undefined,
-        diagnostics,
-        ...(allSkipped
-            ? { skipped: true, skipReason: skipReasons.join(" | ") || undefined }
-            : {}),
-    };
-}
-/**
- * How much of a failed run's stderr to carry into `healthDetail`/`skipReason`.
- *
- * This is often the ONLY record of the failure: a run command that shells out to
- * a container writes to the MCP server's child process, not to the CI job log, so
- * nothing else captures it. Run 30314973126 lost the real error to the previous
- * 1200-char tail — it cut off mid-line, one line after the failing command.
- */
-const STDERR_TAIL_CHARS = 4000;
-/**
- * How much of a failed run's stdout to carry alongside the stderr tail.
- *
- * Every framework EXCEPT mocha reports via a file (`outputVia: "file"`), and those
- * runners print their human-readable failure text — a Playwright global-setup stack
- * trace, a pytest collection error — on STDOUT, which used to be dropped unread to
- * avoid backpressure. So the stderr-only tail left exactly the failures it was added
- * for with no cause attached: run 30402703836 reported `global.setup.ts` as failed
- * and carried nothing about why, because the reason went to stdout.
- */
-const STDOUT_TAIL_CHARS = 4000;
-/**
- * Label and join whichever of the child's output streams carried something, so a
- * failure path reports the cause regardless of which stream the runner chose.
- */
-function buildOutputDiagnostic(stderrTail, stdoutTail) {
-    const parts = [];
-    const err = stripVTControlCharacters(stderrTail).trim();
-    const out = stripVTControlCharacters(stdoutTail).trim();
-    if (err)
-        parts.push(`stderr: ${err}`);
-    if (out)
-        parts.push(`stdout: ${out}`);
-    return parts.join(" | ");
-}
-/** POSIX single-quote a shell argument. */
-function shellQuote(s) {
-    return `'${s.replace(/'/g, `'\\''`)}'`;
-}
-/**
- * Generic IO shell for every framework reader: append the reporter + scoped
- * selectors to the suite's `testRunCommand`, spawn it via bash (so a wrapper
- * entrypoint's `exec "$@"` receives the flags), read the machine-readable
- * report (temp file or captured stdout), and hand it to `spec.parse`. A missing
- * or unparseable report is the exit-code rung: `environmentHealthy:false` with
- * the stderr tail — never PR signal, never throws.
- */
-export async function runExternalSuite(spec, cfg, opts) {
-    const reportPath = path.join(os.tmpdir(), `skyramp-${spec.framework}-${crypto.randomUUID()}.json`);
-    const args = spec.buildArgs({
-        selectors: opts.selectors,
-        mode: opts.mode,
-        project: opts.project,
-        reportPath,
-    });
-    const cmd = `${cfg.testRunCommand} ${args.map(shellQuote).join(" ")}`;
-    const env = {
-        ...process.env,
-        ...(cfg.testEnv ?? {}),
-        ...(spec.reportEnvVar ? { [spec.reportEnvVar]: reportPath } : {}),
-    };
-    const { code, stdout, stderrTail, stdoutTail } = await new Promise((resolve) => {
-        const child = spawn("bash", ["-c", cmd], {
-            cwd: opts.workspacePath,
-            env,
-            timeout: opts.timeoutMs,
-        });
-        let stderr = "";
-        let out = "";
-        let outTail = "";
-        child.stderr?.on("data", (d) => {
-            stderr += d.toString();
-            if (stderr.length > 16000)
-                stderr = stderr.slice(-16000);
-        });
-        child.stdout?.on("data", (d) => {
-            const chunk = d.toString();
-            // Always keep a bounded tail: for `outputVia: "file"` frameworks this is the
-            // ONLY record of why the run failed. Accumulating the full stream stays gated
-            // on "stdout" readers, which parse their JSON report out of it.
-            outTail += chunk;
-            if (outTail.length > STDOUT_TAIL_CHARS)
-                outTail = outTail.slice(-STDOUT_TAIL_CHARS);
-            if (spec.outputVia !== "stdout")
-                return; // drain to avoid backpressure
-            out += chunk;
-            if (out.length > 8_000_000)
-                out = out.slice(-8_000_000);
-        });
-        child.on("close", (c) => resolve({
-            code: c,
-            stdout: out,
-            stderrTail: stderr.slice(-STDERR_TAIL_CHARS),
-            stdoutTail: outTail,
-        }));
-        child.on("error", (e) => resolve({ code: -1, stdout: out, stderrTail: String(e), stdoutTail: outTail }));
-    });
-    let report;
-    try {
-        const raw = spec.outputVia === "stdout"
-            ? extractLastJsonObject(stdout)
-            : await fs.readFile(reportPath, "utf8");
-        report = JSON.parse(raw);
-    }
-    catch {
-        if (spec.outputVia === "file")
-            await fs.unlink(reportPath).catch(() => { });
-        const emptySummary = {
-            ran: 0,
-            failed: 0,
-            errored: 0,
-            skipped: 0,
-            truncated: opts.truncated,
-        };
-        const outputDetail = buildOutputDiagnostic(stderrTail, stdoutTail) || "(no output)";
-        // A SCOPED run that produced no report is not evidence the environment is
-        // down: the usual causes are a spec this runner cannot load (the wrong suite
-        // for the file) or this suite's own setup failing. Calling it unhealthy is
-        // what let a mocha loader crash read as a dead SUT and suppress PR findings,
-        // so report a skip and let the other suites speak for the environment.
-        //
-        // Do NOT guess between those causes here — run 30314973126 reported "they
-        // probably belong to another suite" about selectors that provably belonged to
-        // this one, while the real fault was the suite's containerised run command
-        // never emitting a report. State both and hand over the stderr.
-        if (opts.selectors.length > 0) {
-            return {
-                results: [],
-                summary: emptySummary,
-                environmentHealthy: true,
-                skipped: true,
-                skipReason: `${spec.framework} produced no parseable JSON report (exit ${code}) for the ${opts.selectors.length} selector(s) it was given, so this suite reported nothing either way. Either the selectors are not this suite's to run (check its testSuites pathGlobs) or its own run command failed before emitting a report — the output below says which. ${outputDetail}`,
-            };
-        }
-        // Nothing was narrowed, so a suite that cannot even produce a report does
-        // point at the environment.
-        return {
-            results: [],
-            summary: emptySummary,
-            environmentHealthy: false,
-            healthDetail: `${spec.framework} produced no parseable JSON report (exit ${code}); the suite likely failed to install/collect or the environment never came up. ${outputDetail}`,
-        };
-    }
-    if (spec.outputVia === "file")
-        await fs.unlink(reportPath).catch(() => { });
-    const parsed = spec.parse(report, { truncated: opts.truncated });
-    // The parser builds healthDetail from the report contents only. When it flags
-    // an unhealthy env (e.g. a Playwright global-setup spec failed), the report is
-    // parseable but the actual cause — a stack trace, "container not found", a
-    // dependency download that hung — lives on the runner's output, which the
-    // report never carries. Append it so a maintenance run's env failure is
-    // diagnosable from healthDetail alone, not only by re-running blind.
-    //
-    // Both streams, not just stderr: the runners that hit this path all report via a
-    // file and print their failure text on stdout, so a stderr-only tail named the
-    // failing setup spec and dropped the reason (run 30402703836). A dead end here
-    // costs the whole maintenance loop — with no baseline, testbot's step (f) skips
-    // the `mode: "verify"` re-run, so the agent never confirms its own fix.
-    if (!parsed.environmentHealthy) {
-        const detail = buildOutputDiagnostic(stderrTail, stdoutTail);
-        if (detail) {
-            parsed.healthDetail = `${parsed.healthDetail ?? `${spec.framework} environment unhealthy (exit ${code}).`} ${detail}`;
-        }
-    }
-    return parsed;
-}
-export async function runPlaywright(cfg, opts) {
-    return runExternalSuite(READERS.playwright, cfg, opts);
-}
-const defaultDeps = {
-    readConfig: (workspacePath) => new WorkspaceConfigManager(workspacePath).read(),
-    runner: (cfg, opts) => {
-        const spec = READERS[cfg.framework];
-        if (!spec) {
-            // Unreachable: resolveRunConfig only returns `run` for a registered reader.
-            throw new Error(`No reader registered for framework "${cfg.framework}".`);
-        }
-        return runExternalSuite(spec, cfg, opts);
-    },
-    now: () => new Date().toISOString(),
-};
-/** Appends a run record into UnifiedAnalysisState.externalTestResults for the
- *  given repo section. Best-effort: a state failure never fails the run. */
-async function persistExternalRun(stateFile, repository, record) {
-    try {
-        const sm = StateManager.fromStatePath(stateFile);
-        const state = await sm.readRepoData(repository);
-        if (!state) {
-            logger.warning(`${TOOL_NAME}: no analysis state found for repo ${repository ?? "(primary)"}; skipping externalTestResults write`);
-            return;
-        }
-        state.externalTestResults = [...(state.externalTestResults ?? []), record];
-        await sm.writeRepoData(state, { repo: repository });
-    }
-    catch (err) {
-        logger.error(`${TOOL_NAME}: failed to persist externalTestResults: ${err.message}`);
-    }
-}
-/**
- * Orchestrates an external test run: resolve config → apply maxTests cap → run →
- * persist a record to the state file. Pure of MCP/registration concerns and
- * fully injectable for tests.
- */
-export async function runExternalTests(params, deps = defaultDeps) {
-    const mode = params.mode ?? "confirm";
-    const selectors = params.testSelectors ?? [];
-    let effective = selectors;
-    let truncated = false;
-    if (params.maxTests && selectors.length > params.maxTests) {
-        effective = selectors.slice(0, params.maxTests);
-        truncated = true;
-    }
-    const config = await deps.readConfig(params.workspacePath);
-    const resolution = resolveRunConfig(config, { service: params.service });
-    if (resolution.runs.length === 0) {
-        const reason = resolution.skips.map((s) => `${s.service}: ${s.reason}`).join("; ") ||
-            `No runnable test suite in .skyramp/workspace.yml — no external tests to run.`;
-        const skippedRun = {
-            results: [],
-            summary: { ran: 0, failed: 0, errored: 0, skipped: 0, truncated: false },
-            environmentHealthy: true,
-            skipped: true,
-            skipReason: reason,
-        };
-        if (params.stateFile) {
-            await persistExternalRun(params.stateFile, params.repository, {
-                ...skippedRun,
-                mode,
-                ranAt: deps.now(),
-                repository: params.repository,
-            });
-        }
-        return skippedRun;
-    }
-    const knownTestFiles = await loadKnownTestFiles(params.stateFile, params.repository);
-    const perSuite = [];
-    for (const cfg of resolution.runs) {
-        const routing = routeSelectorsToSuite({
-            selectors: effective,
-            pathGlobs: cfg.pathGlobs,
-            knownTestFiles,
-            workspacePath: params.workspacePath,
-        });
-        // An empty selector list means "run the whole configured suite", so routing
-        // every selector away must NOT collapse into that: it would silently widen a
-        // scoped run into the entire suite. Skip the suite instead, loudly.
-        if (effective.length > 0 && routing.kept.length === 0) {
-            const owned = (cfg.pathGlobs ?? []).join(", ");
-            const routedOut = {
-                results: [],
-                summary: { ran: 0, failed: 0, errored: 0, skipped: 0, truncated },
-                environmentHealthy: true,
-                skipped: true,
-                skipReason: `suite "${cfg.serviceName}" owns ${owned}, and none of the ${routing.dropped.length} requested selector(s) fall under it — nothing for this suite to run. Widen its testSuites pathGlobs, or add a suite that owns those paths.`,
-            };
-            perSuite.push(routedOut);
-            if (params.stateFile) {
-                await persistExternalRun(params.stateFile, params.repository, {
-                    ...routedOut,
-                    mode,
-                    ranAt: deps.now(),
-                    repository: params.repository,
-                });
-            }
-            continue;
-        }
-        if (routing.dropped.length > 0) {
-            logger.warning(`${TOOL_NAME}: dropped ${routing.dropped.length} selector(s) outside ${cfg.serviceName}'s ${cfg.framework} suite paths (${(cfg.pathGlobs ?? []).join(", ")}): ${routing.dropped.join(", ")}`);
-        }
-        const parsed = await deps.runner(cfg, {
-            workspacePath: params.workspacePath,
-            selectors: routing.kept,
-            mode,
-            project: params.project,
-            timeoutMs: params.timeoutMs,
-            truncated,
-        });
-        const suiteResult = {
-            ...parsed,
-            summary: { ...parsed.summary, truncated: parsed.summary.truncated || truncated },
-        };
-        perSuite.push(suiteResult);
-        if (params.stateFile) {
-            await persistExternalRun(params.stateFile, params.repository, {
-                ...suiteResult,
-                mode,
-                ranAt: deps.now(),
-                repository: params.repository,
-            });
-        }
-    }
-    return aggregateRuns(perSuite);
-}
-export function registerRunExistingTestsTool(server) {
-    server.registerTool(TOOL_NAME, {
-        description: `Run a repo's OWN user-authored test suite (the \`[external]\` tests, i.e. not Skyramp-generated) to CONFIRM which tests a change actually breaks — instead of guessing from the diff. Supports Playwright, pytest, jest, vitest, and Mocha suites in DELEGATE mode: the suite owns environment bring-up and this tool drives it with scoped selectors, forcing each framework's JSON reporter, then reports structured pass/fail/error/skipped. Requires a runtimeDetails.testSuites entry (with a testRunCommand) in .skyramp/workspace.yml (from the Test Environment Setup bootstrap). A failed setup or missing report is reported as environmentHealthy:false and MUST NOT be treated as PR signal.`,
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: true,
-        },
-        inputSchema: {
-            workspacePath: z
-                .string()
-                .describe("Absolute path to the repo checkout where the tests live."),
-            service: z
-                .string()
-                .optional()
-                .describe("serviceName in .skyramp/workspace.yml whose runtimeDetails.test* to use. Omit when there is exactly one supported test service."),
-            testSelectors: z
-                .array(z.string())
-                .optional()
-                .describe("Spec files to run (paths relative to the run command's cwd), optionally `file::test title` to also filter by name. Omit to run the whole configured suite."),
-            mode: z
-                .enum(["confirm", "verify"])
-                .optional()
-                .describe("confirm (default): scoped run to establish which tests a change breaks; disables the suite's fail-fast cap (e.g. Playwright's maxFailures) so ALL breakages are counted. verify: re-run after an edit."),
-            project: z
-                .string()
-                .optional()
-                .describe("Playwright-only: --project to scope to (e.g. 'main'); the project's global-setup dependency still runs. Ignored by other frameworks."),
-            stateFile: z
-                .string()
-                .optional()
-                .describe("Path to the analyze-changes state file. When set, results are appended to externalTestResults so drift analysis and the report can fold in CONFIRMED failures."),
-            repository: z
-                .string()
-                .optional()
-                .describe("owner/repo whose state section to write into (multi-repo runs). Omit for a single-repo run."),
-            timeoutMs: z
-                .number()
-                .int()
-                .positive()
-                .optional()
-                .describe("Hard wall-clock cap for the whole run, in milliseconds (positive integer)."),
-            maxTests: z
-                .number()
-                .int()
-                .positive()
-                .optional()
-                .describe("Cap the number of selectors run (positive integer); the summary reports truncated:true when the set was cut. Omit for no cap."),
-        },
-        _meta: {
-            keywords: ["run existing tests", "external tests", "confirm failures"],
-        },
-    }, async (params, _extra) => {
-        let errorResult;
-        try {
-            const out = await runExternalTests(params);
-            if (out.skipped) {
-                return {
-                    structuredContent: out,
-                    content: [
-                        { type: "text", text: `Skipped ${TOOL_NAME}: ${out.skipReason}` },
-                    ],
-                };
-            }
-            const health = out.environmentHealthy
-                ? ""
-                : ` Environment UNHEALTHY — results are NOT PR signal: ${out.healthDetail}`;
-            const text = `Ran ${out.summary.ran} external test(s): ${out.summary.failed} failed, ${out.summary.errored} errored, ${out.summary.skipped} skipped` +
-                `${out.summary.truncated ? " (truncated)" : ""}.${health}`;
-            return {
-                structuredContent: out,
-                content: [{ type: "text", text }],
-            };
-        }
-        catch (err) {
-            errorResult = toolError(`${TOOL_NAME} failed: ${err.message}`);
-            return errorResult;
-        }
-        finally {
-            AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, {
-                workspacePath: params.workspacePath,
-                service: params.service ?? "",
-                mode: params.mode ?? "confirm",
-            }).catch((err) => {
-                logger.warning("Analytics event failed", { error: String(err) });
-            });
-        }
-    });
-}