@skyramp/mcp 0.3.2-rc.pom-4 → 0.3.3

package/build/tools/queryProxyMocksTool.js

@@ -0,0 +1,521 @@
+import { z } from "zod";
+import { spawn, execFile } from "child_process";
+import { promisify } from "util";
+import { MockProtocol } from "../types/TestTypes.js";
+import { logger } from "../utils/logger.js";
+const execFileAsync = promisify(execFile);
+const TOOL_NAME = "skyramp_query_proxy_mocks";
+// Internal safety cap on total samples fetched per protocol, guards against a
+// runaway pagination loop if the worker keeps reporting hasMore.
+const MAX_SAMPLES_PER_PROTOCOL = 500;
+// Default worker port inside the pod (management API). See skyramp3 mgmt_api.go.
+const DEFAULT_REMOTE_PORT = 35142;
+// How long to wait for `kubectl port-forward` to report a bound local port.
+const PORT_FORWARD_READY_TIMEOUT_MS = 15_000;
+// Grace period between SIGTERM and SIGKILL when tearing a forward down.
+const PORT_FORWARD_KILL_GRACE_MS = 2_000;
+// Per-request timeout for the samples query so a stalled proxy can't hang the tool.
+const SAMPLES_FETCH_TIMEOUT_MS = 10_000;
+// Default label used by the Skyramp worker Helm chart.
+const WORKER_SERVICE_SELECTOR = "app.kubernetes.io/name=skyramp-worker";
+const PROTOCOLS = ["rest", "grpc", "kafka"];
+// ── Pure normalizer (unit tested, no network) ────────────────────────────────
+/**
+ * Split a gRPC full method path like "/helloworld.Greeter/SayHello" into its
+ * service name ("helloworld.Greeter") and method ("SayHello").
+ */
+function parseGrpcMethod(full) {
+    if (!full)
+        return {};
+    const trimmed = full.replace(/^\//, "");
+    const slash = trimmed.lastIndexOf("/");
+    if (slash === -1)
+        return { method: trimmed };
+    return { service: trimmed.slice(0, slash), method: trimmed.slice(slash + 1) };
+}
+/**
+ * Derive a Kafka topic from either explicit metadata.topic or the sample path
+ * ("kafka-protocol/topic/orders" -> "orders").
+ */
+function parseKafkaTopic(meta) {
+    if (meta.topic)
+        return meta.topic;
+    if (meta.path) {
+        const parts = meta.path.split("/").filter(Boolean);
+        return parts[parts.length - 1];
+    }
+    return undefined;
+}
+/**
+ * Combine a bare destination hostname with the separately-reported port
+ * (`metadata.port`) into `host:port`, which is what mock generation expects for
+ * the endpoint origin. Leaves the destination untouched if it already carries a
+ * port or if no usable port was reported.
+ */
+export function withPort(destination, port) {
+    if (destination.includes(":"))
+        return destination;
+    if (!port || port <= 0)
+        return destination;
+    return `${destination}:${port}`;
+}
+/**
+ * Convert raw proxy samples for a single protocol into deduplicated mock specs
+ * whose fields map 1:1 onto skyramp_batch_mock_generation. Deduplication keeps
+ * one representative per distinct (destination, method/path/topic, status).
+ */
+export function normalizeSamplesToMockSpecs(protocol, samples) {
+    const byKey = new Map();
+    for (const sample of samples) {
+        const meta = sample.metadata ?? {};
+        const destination = meta.destination;
+        if (!destination)
+            continue;
+        const host = withPort(destination, meta.port);
+        if (protocol === "rest") {
+            const scheme = meta.scheme || "http";
+            const path = meta.path || "";
+            const method = (meta.method || "GET").toUpperCase();
+            const statusCode = sample.response?.statusCode !== undefined
+                ? String(sample.response.statusCode)
+                : "";
+            const key = `${method} ${host}${path} ${statusCode}`;
+            if (byKey.has(key))
+                continue;
+            const requestBody = sample.request?.body;
+            byKey.set(key, {
+                protocol: MockProtocol.Rest,
+                endpointURL: `${scheme}://${host}${path}`,
+                method,
+                responseData: sample.response?.body || undefined,
+                responseStatusCode: statusCode || undefined,
+                requestData: requestBody || undefined,
+                requestAware: Boolean(requestBody),
+            });
+        }
+        else if (protocol === "grpc") {
+            const { service, method } = parseGrpcMethod(meta.method);
+            const key = `${host} ${meta.method || ""}`;
+            if (byKey.has(key))
+                continue;
+            byKey.set(key, {
+                protocol: MockProtocol.Grpc,
+                endpointURL: host,
+                grpcServiceName: service || meta.service || undefined,
+                method: method || undefined,
+                responseData: sample.response?.body || undefined,
+                requestData: sample.request?.body || undefined,
+            });
+        }
+        else {
+            // kafka
+            const topic = parseKafkaTopic(meta);
+            const isProduce = (meta.method || "").toLowerCase().includes("produce");
+            const key = `${host} ${topic || ""} ${isProduce ? "produce" : "consume"}`;
+            if (byKey.has(key))
+                continue;
+            // Kafka mocks accept exactly one of requestData (producer) or responseData
+            // (consumer) — never both.
+            const spec = {
+                protocol: MockProtocol.Kafka,
+                endpointURL: host,
+                kafkaTopic: topic,
+            };
+            if (isProduce) {
+                spec.requestData =
+                    sample.request?.data || sample.request?.body || undefined;
+            }
+            else {
+                spec.responseData =
+                    sample.response?.data || sample.response?.body || undefined;
+            }
+            byKey.set(key, spec);
+        }
+    }
+    return Array.from(byKey.values());
+}
+// ── Proxy URL normalization ──────────────────────────────────────────────────
+/** Normalize a user-supplied proxy address into a scheme://host:port base. */
+export function normalizeProxyBaseUrl(proxyUrl) {
+    let url = proxyUrl.trim();
+    if (!/^https?:\/\//i.test(url))
+        url = `http://${url}`;
+    const parsed = new URL(url);
+    // Strip any path/query — the samples endpoint is appended by the caller.
+    return `${parsed.protocol}//${parsed.host}`;
+}
+// Registry of live port-forward stop callbacks so a process-level signal can
+// sweep any that are still running (see registerExitSafetyNet).
+const activeForwards = new Set();
+let exitHandlersRegistered = false;
+function registerExitSafetyNet() {
+    if (exitHandlersRegistered)
+        return;
+    exitHandlersRegistered = true;
+    const sweep = () => {
+        for (const stop of Array.from(activeForwards)) {
+            try {
+                stop();
+            }
+            catch {
+                /* best effort */
+            }
+        }
+    };
+    process.on("exit", sweep);
+    process.on("SIGINT", sweep);
+    process.on("SIGTERM", sweep);
+}
+async function discoverWorkerPod(kubeconfig, namespace) {
+    const { stdout } = await execFileAsync("kubectl", [
+        "--kubeconfig",
+        kubeconfig,
+        "-n",
+        namespace,
+        "get",
+        "pods",
+        "-l",
+        WORKER_SERVICE_SELECTOR,
+        "-o",
+        "jsonpath={.items[0].metadata.name}",
+    ]);
+    const name = stdout.trim();
+    if (!name) {
+        throw new Error(`No pod matching '${WORKER_SERVICE_SELECTOR}' found in namespace '${namespace}'. ` +
+            `Pass workerService explicitly.`);
+    }
+    return name;
+}
+/**
+ * Start `kubectl port-forward` to the given target (a pod name, or "svc/<name>")
+ * using an OS-chosen local port (":remotePort"), resolving once kubectl reports
+ * the bound local port. The returned stop() kills the whole process group and is
+ * idempotent. Forwarding to the pod on its container port avoids depending on how
+ * the worker Service maps its ports (the Helm chart exposes port 80 → 35142).
+ */
+function startPortForward(kubeconfig, namespace, target, remotePort) {
+    registerExitSafetyNet();
+    const child = spawn("kubectl", [
+        "--kubeconfig",
+        kubeconfig,
+        "-n",
+        namespace,
+        "port-forward",
+        target,
+        `:${remotePort}`,
+    ], { detached: true, stdio: ["ignore", "pipe", "pipe"] });
+    let stopped = false;
+    const stop = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        activeForwards.delete(stop);
+        const pid = child.pid;
+        if (!pid)
+            return;
+        const killGroup = (signal) => {
+            try {
+                process.kill(-pid, signal);
+            }
+            catch {
+                // Group may already be gone, or on platforms without group semantics
+                // fall back to killing the direct child.
+                try {
+                    child.kill(signal);
+                }
+                catch {
+                    /* already dead */
+                }
+            }
+        };
+        killGroup("SIGTERM");
+        // Escalate to SIGKILL only if the process hasn't exited. child.killed just
+        // records that a signal was *sent* (and stays false for process-group kills
+        // via process.kill(-pid)), so check exitCode/signalCode for actual exit.
+        const timer = setTimeout(() => {
+            if (child.exitCode === null && child.signalCode === null)
+                killGroup("SIGKILL");
+        }, PORT_FORWARD_KILL_GRACE_MS);
+        timer.unref?.();
+    };
+    activeForwards.add(stop);
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            stop();
+            reject(new Error(`kubectl port-forward did not become ready within ${PORT_FORWARD_READY_TIMEOUT_MS}ms`));
+        }, PORT_FORWARD_READY_TIMEOUT_MS);
+        timeout.unref?.();
+        let stderr = "";
+        child.stdout?.on("data", (chunk) => {
+            const text = chunk.toString();
+            // kubectl prints "Forwarding from 127.0.0.1:<port>" and/or "[::1]:<port>";
+            // accept either (some environments emit only the IPv6 line).
+            const match = text.match(/Forwarding from (?:127\.0\.0\.1|\[::1\]):(\d+)/);
+            if (match) {
+                clearTimeout(timeout);
+                resolve({ localPort: Number(match[1]), stop });
+            }
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.on("error", (err) => {
+            clearTimeout(timeout);
+            stop();
+            reject(err);
+        });
+        child.on("exit", (code) => {
+            clearTimeout(timeout);
+            stop();
+            reject(new Error(`kubectl port-forward exited early (code ${code}): ${stderr.trim() || "no output"}`));
+        });
+    });
+}
+// ── Sample querying ──────────────────────────────────────────────────────────
+async function queryProtocolSamples(baseUrl, protocol, pageSize, destination) {
+    const collected = [];
+    let offset = 0;
+    while (true) {
+        const params = new URLSearchParams({
+            protocol,
+            limit: String(pageSize),
+            offset: String(offset),
+        });
+        if (destination)
+            params.set("destination", destination);
+        const url = `${baseUrl}/skyramp/proxy/samples?${params.toString()}`;
+        // Bound each request so a stalled proxy connection can't hang the tool.
+        const res = await fetch(url, {
+            signal: AbortSignal.timeout(SAMPLES_FETCH_TIMEOUT_MS),
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => "");
+            throw new Error(`GET ${url} -> ${res.status} ${body.slice(0, 200)}`);
+        }
+        const data = (await res.json());
+        const batch = data.samples ?? [];
+        collected.push(...batch);
+        // Stop on an empty page, an explicit hasMore=false, the internal cap, or —
+        // ONLY when the server reports a totalCount — once we've collected them all.
+        // Do NOT derive `total` from collected.length: that would make the "reached
+        // total" check trivially true and break pagination when totalCount is absent.
+        const reachedReportedTotal = typeof data.totalCount === "number" &&
+            collected.length >= data.totalCount;
+        if (batch.length === 0 ||
+            data.hasMore === false ||
+            reachedReportedTotal ||
+            collected.length >= MAX_SAMPLES_PER_PROTOCOL) {
+            break;
+        }
+        offset += batch.length;
+    }
+    return collected.slice(0, MAX_SAMPLES_PER_PROTOCOL);
+}
+// ── Input schema ─────────────────────────────────────────────────────────────
+const inputSchema = {
+    proxyUrl: z
+        .string()
+        .optional()
+        .describe("Direct HTTP address of the Skyramp worker proxy management API, as host:port or a full URL " +
+        "(e.g. 'localhost:35141' or 'https://skyramp.example.com'). Also covers an ingress-controller " +
+        "route. Mutually exclusive with kubeconfig/namespace."),
+    kubeconfig: z
+        .string()
+        .optional()
+        .describe("Absolute path to a kubeconfig file. When set (with namespace), the tool runs `kubectl port-forward` " +
+        "to reach the worker in-cluster. Mutually exclusive with proxyUrl."),
+    namespace: z
+        .string()
+        .optional()
+        .describe("Kubernetes namespace where the Skyramp worker is deployed. Required with kubeconfig."),
+    workerService: z
+        .string()
+        .optional()
+        .describe(`Name of the worker Kubernetes Service to port-forward to (forwards to 'svc/<name>' at remotePort). ` +
+        `Optional — when omitted, the tool discovers the worker POD by label '${WORKER_SERVICE_SELECTOR}' and ` +
+        `forwards to it directly (avoids depending on how the Service maps its ports).`),
+    remotePort: z
+        .number()
+        .int()
+        .optional()
+        .describe(`Worker management API port inside the pod. Defaults to ${DEFAULT_REMOTE_PORT}.`),
+    protocols: z
+        .array(z.enum(PROTOCOLS))
+        .optional()
+        .describe("Which protocols to query. Defaults to all of rest, grpc, kafka."),
+    destination: z
+        .string()
+        .optional()
+        .describe("Optional destination filter (e.g. 'ams:4000') passed through to the samples query."),
+    limit: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Page size per samples request (default 50). Total is capped internally."),
+};
+const mockSpecOutputSchema = z.object({
+    protocol: z.nativeEnum(MockProtocol),
+    endpointURL: z.string(),
+    method: z.string().optional(),
+    responseData: z.string().optional(),
+    responseStatusCode: z.string().optional(),
+    requestData: z.string().optional(),
+    requestAware: z.boolean().optional(),
+    grpcServiceName: z.string().optional(),
+    kafkaTopic: z.string().optional(),
+});
+const outputSchema = {
+    proxyReachable: z
+        .boolean()
+        .describe("True if the proxy was reached and queried. When false, fall back to code/OpenAPI inference."),
+    sampleCount: z
+        .number()
+        .describe("Total raw samples retrieved across all queried protocols."),
+    endpointsDiscovered: z
+        .number()
+        .describe("Number of deduplicated mock specs produced."),
+    mockSpecs: z
+        .array(mockSpecOutputSchema)
+        .describe("Normalized mock specs ready to pass to skyramp_batch_mock_generation."),
+    message: z
+        .string()
+        .optional()
+        .describe("Human-readable status or error detail."),
+};
+/**
+ * Validate that exactly one access mode was provided and return a normalized
+ * descriptor. Throws a user-facing error otherwise.
+ */
+export function resolveAccessMode(params) {
+    const hasUrl = Boolean(params.proxyUrl);
+    const hasKube = Boolean(params.kubeconfig || params.namespace);
+    if (hasUrl && hasKube) {
+        throw new Error("Provide either proxyUrl OR kubeconfig+namespace, not both.");
+    }
+    if (!hasUrl && !hasKube) {
+        throw new Error("No proxy access provided. Pass proxyUrl, or kubeconfig+namespace.");
+    }
+    if (hasUrl)
+        return { mode: "url", proxyUrl: params.proxyUrl };
+    if (!params.kubeconfig || !params.namespace) {
+        throw new Error("Kubernetes access requires both kubeconfig and namespace.");
+    }
+    return {
+        mode: "kube",
+        kubeconfig: params.kubeconfig,
+        namespace: params.namespace,
+    };
+}
+export function registerQueryProxyMocksTool(server) {
+    server.registerTool(TOOL_NAME, {
+        description: "Query a running Skyramp worker proxy for recorded downstream traffic and return normalized mock specs. " +
+            "Use during local-dev dependency discovery when a proxy is recording real traffic: the returned mockSpecs " +
+            "map directly onto skyramp_batch_mock_generation (real request/response bodies and status codes) instead " +
+            "of code/OpenAPI inference. Access the proxy via proxyUrl (host:port or full URL, including an ingress " +
+            "route) OR kubeconfig+namespace (the tool runs kubectl port-forward and always tears it down). If the " +
+            "proxy is unreachable, proxyReachable is false and you should fall back to inference — the workflow is not " +
+            "aborted.",
+        inputSchema,
+        outputSchema,
+    }, async (params) => {
+        const protocols = params.protocols ?? [
+            ...PROTOCOLS,
+        ];
+        const pageSize = params.limit ?? 50;
+        const destination = params.destination;
+        let access;
+        try {
+            access = resolveAccessMode(params);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return unreachable(message);
+        }
+        let baseUrl;
+        let portForward;
+        try {
+            if (access.mode === "url") {
+                baseUrl = normalizeProxyBaseUrl(access.proxyUrl);
+            }
+            else {
+                // If a service name is given, forward to it (remotePort must be that
+                // service's port). Otherwise forward to the worker pod on its container
+                // port, which is independent of how the Service maps its ports.
+                const explicitService = params.workerService;
+                const target = explicitService
+                    ? `svc/${explicitService}`
+                    : await discoverWorkerPod(access.kubeconfig, access.namespace);
+                const remotePort = params.remotePort ?? DEFAULT_REMOTE_PORT;
+                portForward = await startPortForward(access.kubeconfig, access.namespace, target, remotePort);
+                baseUrl = `http://localhost:${portForward.localPort}`;
+            }
+            const allSpecs = [];
+            let sampleCount = 0;
+            for (const protocol of protocols) {
+                const samples = await queryProtocolSamples(baseUrl, protocol, pageSize, destination);
+                sampleCount += samples.length;
+                allSpecs.push(...normalizeSamplesToMockSpecs(protocol, samples));
+            }
+            return {
+                structuredContent: {
+                    proxyReachable: true,
+                    sampleCount,
+                    endpointsDiscovered: allSpecs.length,
+                    mockSpecs: allSpecs,
+                },
+                content: [
+                    { type: "text", text: formatSummary(allSpecs, sampleCount) },
+                ],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            logger.warning("skyramp_query_proxy_mocks failed to reach proxy", {
+                error: message,
+            });
+            return unreachable(message);
+        }
+        finally {
+            // Guaranteed teardown of the port-forward on every path.
+            portForward?.stop();
+        }
+    });
+}
+function unreachable(message) {
+    return {
+        structuredContent: {
+            proxyReachable: false,
+            sampleCount: 0,
+            endpointsDiscovered: 0,
+            mockSpecs: [],
+            message,
+        },
+        content: [
+            {
+                type: "text",
+                text: `⚠️  Proxy not queried: ${message}\n\n` +
+                    "Fall back to OpenAPI spec / implementation-code inference for downstream mock shapes.",
+            },
+        ],
+    };
+}
+function formatSummary(specs, sampleCount) {
+    if (specs.length === 0) {
+        return `Proxy reachable but no samples recorded (queried ${sampleCount}). Fall back to code/OpenAPI inference.`;
+    }
+    const lines = specs.map((s) => {
+        if (s.protocol === MockProtocol.Rest) {
+            return `  • [rest] ${s.method} ${s.endpointURL} → ${s.responseStatusCode ?? "?"}`;
+        }
+        if (s.protocol === MockProtocol.Grpc) {
+            return `  • [grpc] ${s.endpointURL} ${s.grpcServiceName ?? ""}/${s.method ?? ""}`;
+        }
+        return `  • [kafka] ${s.endpointURL} topic=${s.kafkaTopic ?? "?"} ${s.requestData ? "(produce)" : "(consume)"}`;
+    });
+    return [
+        `✅ Proxy queried: ${sampleCount} sample(s) → ${specs.length} mock spec(s).`,
+        "Secrets are redacted by the proxy. Pass these specs to skyramp_batch_mock_generation:",
+        ...lines,
+    ].join("\n");
+}

package/build/tools/runExistingTestsTool.d.ts

@@ -0,0 +1,138 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { WorkspaceConfig } from "../workspace/workspace.js";
+import { ParsedExternalRun } from "../types/ExternalTestExecution.js";
+import { SUPPORTED_FRAMEWORKS } from "../workspace/frameworks.js";
+/** Test-run lifecycle resolved from a service's workspace.yml runtimeDetails. */
+export interface ResolvedRunConfig {
+    serviceName: string;
+    framework: Framework;
+    testRunCommand: string;
+    testEnv?: Record<string, string>;
+    /** Repo-relative globs this suite owns; empty/absent means it accepts any selector. */
+    pathGlobs?: string[];
+}
+type Framework = (typeof SUPPORTED_FRAMEWORKS)[number];
+/** Binds a framework to its pure parse/buildArgs pair + how its report is
+ *  obtained. The generic IO shell {@link runExternalSuite} is the only place
+ *  that spawns a process; adding a framework is a new ReaderSpec + registry entry. */
+interface ReaderSpec {
+    framework: Framework;
+    /** Where the machine-readable report lands: a temp file, or the process stdout. */
+    outputVia: "file" | "stdout";
+    /** Env var pointing the reporter at the temp report path (e.g. Playwright). */
+    reportEnvVar?: string;
+    buildArgs(input: {
+        selectors: string[];
+        mode: "confirm" | "verify";
+        project?: string;
+        reportPath: string;
+    }): string[];
+    parse(report: unknown, opts: {
+        truncated: boolean;
+    }): ParsedExternalRun;
+}
+/** True when a framework has an execution reader (playwright/pytest/jest/vitest/mocha). */
+export declare function frameworkHasReader(framework?: string): boolean;
+/** 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 declare function extractLastJsonObject(s: string): string;
+export interface RunExistingTestsParams {
+    workspacePath: string;
+    service?: string;
+    testSelectors?: string[];
+    mode?: "confirm" | "verify";
+    project?: string;
+    stateFile?: string;
+    repository?: string;
+    timeoutMs?: number;
+    maxTests?: number;
+}
+export interface PlaywrightRunOpts {
+    workspacePath: string;
+    selectors: string[];
+    mode: "confirm" | "verify";
+    project?: string;
+    timeoutMs?: number;
+    truncated: boolean;
+}
+/** Injectable IO seam so the orchestration in {@link runExternalTests} is unit
+ *  testable without a real workspace file or Playwright process. */
+export interface RunExistingTestsDeps {
+    readConfig: (workspacePath: string) => Promise<WorkspaceConfig>;
+    runner: (cfg: ResolvedRunConfig, opts: PlaywrightRunOpts) => Promise<ParsedExternalRun>;
+    now: () => string;
+}
+/** The routed suite list: every runnable suite to execute, plus the suites that
+ *  were skipped (with a reason). A suite is runnable when its framework has a
+ *  registered reader (its testRunCommand is required non-empty by the schema). */
+export interface RunConfigResolution {
+    runs: ResolvedRunConfig[];
+    skips: {
+        service: string;
+        reason: string;
+    }[];
+}
+/**
+ * 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 declare function resolveRunConfig(config: WorkspaceConfig, opts?: {
+    service?: string;
+}): RunConfigResolution;
+/** Selectors partitioned into those this suite owns and those it does not. */
+export interface SelectorRouting {
+    kept: string[];
+    dropped: string[];
+}
+/**
+ * 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 declare function routeSelectorsToSuite(input: {
+    selectors: string[];
+    /** The suite's repo-relative globs; absent/empty means it accepts every selector. */
+    pathGlobs?: string[];
+    /** Absolute test-file paths from analyze_changes, used to canonicalize a selector. */
+    knownTestFiles?: string[];
+    workspacePath: string;
+}): SelectorRouting;
+/** Combines per-suite runs into one ParsedExternalRun for the tool's summary
+ *  text: sums counts, concatenates results, ANDs environmentHealthy, joins the
+ *  unhealthy details. */
+export declare function aggregateRuns(parsed: ParsedExternalRun[]): ParsedExternalRun;
+/**
+ * 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 declare function runExternalSuite(spec: ReaderSpec, cfg: ResolvedRunConfig, opts: PlaywrightRunOpts): Promise<ParsedExternalRun>;
+export declare function runPlaywright(cfg: ResolvedRunConfig, opts: PlaywrightRunOpts): Promise<ParsedExternalRun>;
+/**
+ * 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 declare function runExternalTests(params: RunExistingTestsParams, deps?: RunExistingTestsDeps): Promise<ParsedExternalRun>;
+export declare function registerRunExistingTestsTool(server: McpServer): void;
+export {};