@skyramp/mcp 0.4.1 → 0.4.2-rc.2

package/build/tools/executeSkyrampTestTool.d.ts

@@ -1,17 +1,18 @@
+import { z } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { TestExecutionResult } from "../types/TestExecution.js";
-import { TestType } from "../types/TestTypes.js";
+import { TestExecutionStatus, TestExecutionResult, type TestExecutionRecord } from "../types/TestExecution.js";
+import { ProgrammingLanguage, TestType } from "../types/TestTypes.js";
 import { MaintenanceActionCore, TestAnalysisResult } from "../types/TestAnalysis.js";
-export declare const CONTRACT_EXECUTION_MODES: readonly ["provider", "consumer"];
-export type ContractExecutionMode = (typeof CONTRACT_EXECUTION_MODES)[number];
+export declare const TOOL_NAME = "skyramp_execute_test";
+/** Output kept per run, from its end: it is held in memory, saved to the state file, and returned to the agent. */
+export declare const MAX_OUTPUT_CHARS = 200000;
 /**
- * Resolve the effective auth token for test execution.
- * `unauthenticated: true` forces no token (empty string) so the container
- * env omits SKYRAMP_TEST_TOKEN entirely — unauthenticated endpoints won't
- * receive an empty Authorization header that triggers encoding errors (E7).
+ * `unauthenticated: true` forces no token, so the child env carries no
+ * SKYRAMP_TEST_TOKEN at all — an empty Authorization header triggers encoding
+ * errors on unauthenticated endpoints (E7). An empty `token` means "use the
+ * server's environment", as the local-dev prompt passes it.
  */
 export declare function resolveEffectiveToken(unauthenticated?: boolean, paramToken?: string, envToken?: string): string;
-export declare function shouldInjectSkyrampBaseUrl(testType: TestType, contractMode?: ContractExecutionMode): boolean;
 /**
  * Append the recorded video path to execution output.
  *
@@ -21,6 +22,67 @@ export declare function shouldInjectSkyrampBaseUrl(testType: TestType, contractM
  * its own attachment line.
  */
 export declare function withVideoInfo(output: string, videoPath?: string): string;
+/**
+ * One directory per run: a unique name leaves nothing to clean up between runs, and
+ * the random suffix keeps two runs in the same millisecond apart.
+ */
+export declare function videoSubdirName(testFile: string): string;
+/** The first `video.webm` under a run's video directory, if one was recorded. */
+export declare function collectVideoPath(videoDir: string): string | undefined;
+/**
+ * The directory whose `.skyramp/workspace.yml` describes this run: the nearest
+ * ancestor of `cwd` that has one, else the run's primary checkout (a tests repo
+ * delivered apart from the SUT has no workspace.yml of its own), else `cwd`.
+ */
+export declare function resolveWorkspaceRoot(cwd: string): string;
+/** pytest splits PYTEST_ADDOPTS with shlex, so a path with whitespace needs quotes. */
+export declare function appendPytestVideoOpts(existing: string | undefined, videoDir: string): string;
+/**
+ * The names by which a command can select `testFile`: its basename, and for Java the
+ * class name, because Maven selects a test with `-Dtest=FooTest`.
+ */
+export declare function testFileNames(testFile: string): string[];
+/**
+ * Backslashes are ignored: Playwright and Jest read the path as a regular
+ * expression, so the agent escapes it (`a\.spec\.ts`).
+ *
+ * A trailing shell comment is removed first. `npm test # a_test.py` names the
+ * file only in a comment and would run the whole suite, and the check exists
+ * to stop exactly that. This is a name check, not a parse: a command that
+ * mentions the file in some other way it does not run still passes.
+ */
+/** The config an explicit `--config <path>` names, resolved against `cwd`, or
+ *  undefined when the command carries none. `$SKYRAMP_PLAYWRIGHT_CONFIG` is
+ *  ours and is not a repository config. */
+export declare function explicitPlaywrightConfig(command: string, cwd: string): string | undefined;
+/** The command with its `--config <repo config>` pointed at the wrapper. The
+ *  wrapper imports that same config, so the run keeps the repository's testDir
+ *  and projects and gains the video overlay. Without this swap a command that
+ *  names a config runs the config directly and records nothing. */
+export declare function pointConfigAtWrapper(command: string, wrapperPath: string): string;
+export declare function commandNamesTestFile(command: string, testFile: string): boolean;
+/** pytest exits 4 on a usage error; without pytest-playwright `--video` is one. */
+export declare function pytestRejectedVideoOptions(run: SpawnedRun): boolean;
+/** The line proving no test ran, or undefined when the output does not say so. */
+export declare function noTestRanReason(output: string): string | undefined;
+export declare function verdictForExit(exitCode: number | null, timedOut: boolean, output?: string): TestExecutionStatus;
+export interface SpawnedRun {
+    exitCode: number | null;
+    output: string;
+    timedOut: boolean;
+    spawnError?: string;
+    duration: number;
+}
+/**
+ * Runs `command` through the shell in its own process group, so a timeout kills
+ * the runner's children too. stdout and stderr share one buffer in arrival order.
+ */
+export declare function spawnTestCommand(opts: {
+    command: string;
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    timeoutMs: number;
+}): Promise<SpawnedRun>;
 /**
  * Normalize the `rebaselineSnapshots` request (SKYR-4298): dedupe and drop blanks,
  * and refuse it on the pre-edit run. A refresh there would overwrite the very
@@ -31,23 +93,6 @@ export declare function resolveRebaselineSnapshots(requested: string[] | undefin
     snapshots: string[];
     error?: string;
 };
-/**
- * The failure text the agent receives. Everything it needs has to be in here:
- * only a tool's return value reaches the transcript, and Claude Code does not
- * capture an MCP server's stderr, so anything this omits is unrecoverable once
- * the run ends.
- *
- * `output` alone was not enough. When the executor produced none, the message
- * read "Test execution failed:" and stopped — so the agent inferred a cause and
- * reported it as fact. Measured in eval run 32220788735: it blamed an
- * unreachable backend while the app was answering 200 on both the host and the
- * docker bridge, and that invented cause reached `issuesFound`.
- *
- * The 401 hint is emitted only when the output carries a 401 in a status-shaped
- * position — see HTTP_401_SHAPES. It used to be unconditional, which pointed the
- * agent at authentication on a run whose output was empty, and then it keyed off
- * the bare number, which pointed it there on a test count or a line number.
- */
 /** The on-disk files a requested baseline name resolves to; empty when none matches. */
 export type BaselineFileState = Array<{
     file: string;
@@ -55,20 +100,12 @@ export type BaselineFileState = Array<{
     mtimeMs: number;
 }>;
 /**
- * Snapshot of the requested baselines under `<spec>-snapshots/` (SKYR-4298): for
- * each requested name, every PNG whose name matches the stem (a spec may hold both
- * `<stem>-linux.png` and `<stem>-chromium-linux.png`; latching onto one of them would
- * misreport the other) with its size and mtime. Taken before and after the run so
- * the tool can tell the agent which baselines were actually rewritten — SmartPlaywright
- * is the only party that knows the exact filename, and an executor image that lacks
- * SKYRAMP_UPDATE_SNAPSHOTS (or a name matching no toHaveScreenshot call) leaves
- * every file untouched.
+ * For each requested name, every PNG under `<spec>-snapshots/` whose name matches the
+ * stem, with size and mtime. A spec may hold both `<stem>-linux.png` and
+ * `<stem>-chromium-linux.png`; latching onto one would misreport the other. Taken
+ * before and after the run to tell which baselines were actually rewritten.
  */
 export declare function readBaselineState(specFile: string, requested: string[]): Record<string, BaselineFileState>;
-/**
- * Which requested baselines changed on disk between two readBaselineState calls, and
- * which files carried the change (the ones to stage).
- */
 export declare function diffBaselineState(before: Record<string, BaselineFileState>, after: Record<string, BaselineFileState>): {
     refreshed: string[];
     notRefreshed: string[];
@@ -91,19 +128,16 @@ export declare function authorizeRebaseline(stateData: {
     error?: string;
 };
 /**
- * Reconcile the persisted verdict with what the executor actually did (SKYR-4298).
- * An executor image whose @skyramp/skyramp predates SKYRAMP_UPDATE_SNAPSHOTS rewrites
- * nothing; left alone, the verdict would still promise a refresh, the report gate
- * would refuse the report, and nothing in the prompt makes the agent's way out
- * deterministic. So: names that were not refreshed are dropped from the verdict; a
- * rebaseline-only UPDATE with nothing left becomes VERIFY (the test stays red, the
- * rationale says why), and an UPDATE that also carried edits keeps UPDATE and is
- * held to its edit. The report then reflects what happened, not what was asked.
+ * Reconcile the persisted verdict with what the run actually did (SKYR-4298). A
+ * @skyramp/skyramp that predates SKYRAMP_UPDATE_SNAPSHOTS rewrites nothing; left
+ * alone, the verdict would still promise a refresh and the report gate would refuse
+ * the report. Names not refreshed are dropped; a rebaseline-only UPDATE with nothing
+ * left becomes VERIFY, and an UPDATE that also carried edits is held to its edit.
  */
 export declare function applyRefreshOutcomeToVerdicts(verdicts: MaintenanceActionCore[], testFile: string, outcome: {
     refreshed: string[];
     notRefreshed: string[];
-}, executorImage: string): {
+}): {
     verdicts: MaintenanceActionCore[];
     note?: string;
 };
@@ -117,5 +151,41 @@ export declare function describeRefreshOutcome(outcome: {
     refreshed: string[];
     notRefreshed: string[];
 }): string;
-export declare function buildExecutionFailureText(result: TestExecutionResult): string;
+/**
+/**
+ * The fix-and-rerun attempt cap (SKYR-4460), enforced where the prompt's prose
+ * cannot be: a file that has already received `cap` runs in the final phase
+ * gets a refusal instead of another execution. Only the "after" phase counts —
+ * a maintained test's baseline run is evidence, not an attempt — and a record
+ * from before the counter existed reads as zero attempts.
+ *
+ * Deliberate limit: `phase: "before"` runs are never refused. The cap bounds
+ * the fix-and-rerun loop, which is a final-phase activity; a baseline is taken
+ * once per file by the prompt (and once per existing test by the baseline
+ * runner), so there is no loop to bound there. A runaway baseline loop would
+ * need its own guard — it is not this one.
+ */
+export declare function fixAttemptRefusal(record: TestExecutionRecord | undefined, phase: "before" | "after", cap: number, testFile: string): string | undefined;
+export declare function setTransientRetryDelayForTests(ms: number): void;
+export declare function describeAttempt(priorAfterRuns: number, cap: number, opts?: {
+    unchangedRerun?: boolean;
+}): string;
+export declare function buildExecutionFailureText(result: TestExecutionResult, opts?: {
+    unchangedRerun?: boolean;
+}): string;
+export declare const inputSchema: {
+    commandOverride: z.ZodOptional<z.ZodString>;
+    cwd: z.ZodOptional<z.ZodString>;
+    workspacePath: z.ZodOptional<z.ZodString>;
+    testFile: z.ZodString;
+    language: z.ZodNativeEnum<typeof ProgrammingLanguage>;
+    testType: z.ZodNativeEnum<typeof TestType>;
+    phase: z.ZodDefault<z.ZodEnum<["before", "after"]>>;
+    stateFile: z.ZodOptional<z.ZodString>;
+    repository: z.ZodString;
+    token: z.ZodOptional<z.ZodString>;
+    unauthenticated: z.ZodOptional<z.ZodBoolean>;
+    rebaselineSnapshots: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+};
 export declare function registerExecuteSkyrampTestTool(server: McpServer): void;