@skyramp/mcp 0.4.2-rc.1 → 0.4.2-rc.3

package/build/utils/runContextGauge.js

@@ -0,0 +1,181 @@
+import * as fs from "fs";
+import * as path from "path";
+import { runArtifactDir } from "./AnalysisStateManager.js";
+import { logger } from "./logger.js";
+/** What the agent's own context usage is, read from the agent log the Testbot
+ *  action streams beside this run's artifacts.
+ *
+ *  WHY THIS EXISTS. Two runs cut planned work citing a "context budget" they
+ *  could not measure: one declared itself out at 357k of a 1M window, the next at
+ *  457k, and neither had a warning from anywhere. The agent has no reading of its
+ *  own context and the prompt cannot give it one, so a refusal that says "do not
+ *  stop because you believe you are low on context" is arguing with a feeling.
+ *  This turns it into a number the server can put in the refusal.
+ *
+ *  It is a MEASUREMENT, never a limit. Nothing here refuses anything or decides
+ *  anything; the callers do, on grounds that hold without it, and every one of
+ *  them still works when this returns undefined. */
+/** The Testbot action streams the agent CLI's `--output-format stream-json` here,
+ *  live, in the same directory this server already writes `testbot-result.txt` to. */
+const AGENT_LOG_NAME = "agent-log.ndjson";
+/** Enough of the tail to hold the last assistant record with a usage block. These
+ *  records carry whole tool results, so a fixed slice can miss one — 512 KiB covers
+ *  it with room, and a miss costs a sentence, not a refusal. */
+const TAIL_BYTES = 512 * 1024;
+/** Enough of the head to hold the `init` record, which is the FIRST line. */
+const HEAD_BYTES = 64 * 1024;
+/** Windows for models with no `[1m]`-style suffix on the init record, first
+ *  match wins. Opus 5 and Sonnet 5 are 1M by default — reading them as
+ *  200k is the same error the suffix rule below guards against, one level up.
+ *  Bedrock prefixes the id (`us.anthropic.claude-opus-5`), so these match
+ *  anywhere in the string rather than at the start. */
+const MODEL_WINDOWS = [
+    [/claude-(opus|sonnet)-5/i, 1_000_000],
+    [/claude-haiku/i, 200_000],
+];
+/** A model none of the above names. ERRS LARGE on purpose: too small a window
+ *  overstates the percentage, which is how this file manufactures the scarcity
+ *  it exists to disprove, and no caller acts on the number — the refusals stand
+ *  on their own grounds. Too large only understates it. */
+const DEFAULT_CONTEXT_WINDOW = 1_000_000;
+function windowForModel(model) {
+    for (const [pattern, window] of MODEL_WINDOWS) {
+        if (pattern.test(model))
+            return window;
+    }
+    return DEFAULT_CONTEXT_WINDOW;
+}
+/** Window and log path do not change within a run, so they are read once and kept
+ *  against the directory they came from — a new run is a new directory. The token
+ *  count is NOT cached: it is the thing that moves. */
+let cachedForDir;
+let cachedWindow;
+function readSlice(file, bytes, fromEnd) {
+    const fd = fs.openSync(file, "r");
+    try {
+        const size = fs.fstatSync(fd).size;
+        const length = Math.min(size, bytes);
+        const buffer = Buffer.alloc(length);
+        fs.readSync(fd, buffer, 0, length, fromEnd ? size - length : 0);
+        return buffer.toString("utf8");
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/** The context window this run's model was started with.
+ *
+ *  READ FROM THE INIT RECORD, not from the per-message model. The two disagree:
+ *  `message.model` is `claude-opus-5` while the init record says
+ *  `claude-opus-5[1m]`, and taking the former turns 46% of a 1M window into 228%
+ *  of a 200k one — a gauge that manufactures the panic it exists to prevent. */
+function contextWindowFrom(head) {
+    for (const line of head.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith("{"))
+            continue;
+        let record;
+        try {
+            record = JSON.parse(trimmed);
+        }
+        catch {
+            // The head slice ends mid-record on any file longer than it. Only the first
+            // line matters here and it is whole.
+            break;
+        }
+        if (record.type !== "system" || record.subtype !== "init")
+            break;
+        const model = typeof record.model === "string" ? record.model : "";
+        const suffix = /\[(\d+)(m|k)\]/i.exec(model);
+        if (!suffix)
+            return windowForModel(model);
+        const scale = suffix[2].toLowerCase() === "m" ? 1_000_000 : 1_000;
+        return Number(suffix[1]) * scale;
+    }
+    return DEFAULT_CONTEXT_WINDOW;
+}
+/** Tokens on the most recent assistant request in the log, or undefined.
+ *
+ *  Walks BACKWARDS to the first record that has them: the tail ends with the turn
+ *  that called the tool now running, and every later line is that turn's own
+ *  output. Records with no usage — heartbeats, progress, tool results — are
+ *  skipped, so the reading is always the newest real request. */
+function tokensFrom(tail) {
+    const lines = tail.split("\n");
+    for (let index = lines.length - 1; index >= 0; index--) {
+        const line = lines[index].trim();
+        // Cheap rejects first: this runs over a few thousand lines per call.
+        if (!line.startsWith("{") || !line.includes('"usage"'))
+            continue;
+        let record;
+        try {
+            record = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const usage = record.message?.usage;
+        if (!usage)
+            continue;
+        const count = (key) => typeof usage[key] === "number" ? usage[key] : 0;
+        const tokens = count("input_tokens") +
+            count("cache_read_input_tokens") +
+            count("cache_creation_input_tokens");
+        if (tokens > 0)
+            return tokens;
+    }
+    return undefined;
+}
+/** This run's context usage, or undefined when it cannot be read.
+ *
+ *  Undefined is ORDINARY, not an error: a local or IDE run has no `RUNNER_TEMP`
+ *  and no agent log, and an agent whose CLI writes no NDJSON log never produces
+ *  one. Every caller prints nothing and carries on. */
+export function readRunContext() {
+    try {
+        const directory = runArtifactDir();
+        if (!directory)
+            return undefined;
+        const file = path.join(directory, AGENT_LOG_NAME);
+        if (!fs.existsSync(file))
+            return undefined;
+        if (directory !== cachedForDir) {
+            cachedForDir = directory;
+            cachedWindow = contextWindowFrom(readSlice(file, HEAD_BYTES, false));
+        }
+        const window = cachedWindow ?? DEFAULT_CONTEXT_WINDOW;
+        const tokens = tokensFrom(readSlice(file, TAIL_BYTES, true));
+        if (tokens === undefined || tokens <= 0)
+            return undefined;
+        return { tokens, window, percent: Math.round((tokens / window) * 100) };
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        logger.warning(`readRunContext failed: ${detail}`);
+        return undefined;
+    }
+}
+/** One sentence naming the measurement, for a refusal that has already told the
+ *  agent not to stop on a context it believes it is short of. Empty when there is
+ *  no reading — the refusal reads correctly without it.
+ *
+ *  It states the reading and nothing else. It does not say the run has room: the
+ *  reading can be 95% and the refusal still stands on its own grounds, and a
+ *  sentence that argued headroom would be wrong exactly when it mattered most.
+ *
+ *  CARRIES ITS OWN TRAILING SPACE, so a caller concatenates it unconditionally
+ *  and an empty reading leaves no gap. */
+export function contextGaugeSentence() {
+    const reading = readRunContext();
+    if (!reading)
+        return "";
+    const k = (value) => `${Math.round(value / 1000)}k`;
+    return (`Measured, not estimated: this run's last request carried ${k(reading.tokens)} of a ` +
+        `${k(reading.window)} token context window (${reading.percent}%). ` +
+        "Use that number rather than an impression of it. ");
+}
+/** Test seam: drop the per-run window cache. */
+export function resetRunContextGaugeForTests() {
+    cachedForDir = undefined;
+    cachedWindow = undefined;
+}

package/build/utils/skyrampMdContent.d.ts

@@ -2,4 +2,4 @@
  * Skill content for skyramp.md — installed at auto-discovery paths: ~/.claude/skills/skyramp/SKILLS.md, ~/.cursor/skills/skyramp/SKILLS.md, ~/.github/skills/skyramp.md
  * Follows the SKILL.md specification: https://agentskills.io/what-are-skills#the-skill-md-file
  */
-export declare const SKYRAMP_MD_CONTENT = "---\nname: skyramp\ndescription: Generate, execute, and maintain API tests (smoke, contract, fuzz, load, integration, E2E, UI) using Skyramp MCP tools.\n---\n\n# Skyramp\n\n## When to use this skill\nUse this skill whenever the user asks to generate, run, or maintain API tests. Always read `<workspace-root>/.skyramp/workspace.yml` first to get `language`, `framework`, `outputDir`, and `api.baseUrl` \u2014 do not ask the user for values already present.\n\n---\n\n## Tools\n\n### Workspace Setup\n1. **`skyramp_initialize_workspace`** \u2014 Create or update `.skyramp/workspace.yml` in a git repository workspace. Scan the repo for all services before calling. Required before any other Skyramp tool.\n\n### Test Generation\n2. **`skyramp_smoke_test_generation`** \u2014 Verify an endpoint is reachable and returns a valid response.\n3. **`skyramp_contract_test_generation`** \u2014 Validate implementation matches OpenAPI/Swagger schema.\n4. **`skyramp_fuzz_test_generation`** \u2014 Send malformed or boundary inputs to find edge cases and security issues.\n5. **`skyramp_load_test_generation`** \u2014 Test performance under concurrent load. Optional: `loadDuration`, `loadNumThreads`. Accepts `trace` instead of `apiSchema`/`endpointURL`.\n6. **`skyramp_integration_test_generation`** \u2014 Multi-step workflows across one or more services. Supply one of: `apiSchema`+`endpointURL`, `trace`, or `scenarioFile`. Do not combine them.\n7. **`skyramp_e2e_test_generation`** \u2014 Full user journey covering UI and backend. Requires `trace` and `playwrightInput` zip. Do not pass `apiSchema` or `endpointURL`.\n8. **`skyramp_ui_test_generation`** \u2014 UI-only tests from Playwright recordings. Requires `playwrightInput` zip.\n\n### Trace Generation\n9. **`skyramp_start_trace_collection`** \u2014 Start capturing backend traffic. Set `playwright: true` for UI or E2E tests. Use an absolute path for `outputDir`.\n10. **`skyramp_stop_trace_collection`** \u2014 Stop capture and save the trace. Use the same `outputDir` and `playwrightEnabled` values as start.\n11. **`skyramp_scenario_test_generation`** \u2014 Scenario trace generation. Describe a multi-step flow in natural language to produce a scenario file. Pass output to `skyramp_integration_test_generation` via `scenarioFile`.\n\n### Test Execution\n12. **`skyramp_execute_test`** \u2014 Run a single Skyramp-generated test file. Required: `workspacePath`, `language`, `testType`, `testFile`. Optional: `stateFile` (writes execution results back for health analysis). For multiple tests, call sequentially to avoid env var conflicts.\n\n### Test Analysis & Maintenance\n13. **`skyramp_analyze_changes`** \u2014 Unified entry point: scans endpoints, discovers tests, computes diff. Takes `repositoryPath` and `scope`. Returns `stateFile` + recommendations.\n14. **`skyramp_analyze_test_health`** \u2014 Drift and health assessment for existing tests. Takes `stateFile`. Returns LLM prompt for scoring.\n15. **`skyramp_actions`** \u2014 Execute UPDATE / REGENERATE / VERIFY / DELETE actions. Takes `stateFile`. Call after analyze_test_health.\n\n### Code Quality\n16. **`skyramp_fix_errors`** \u2014 Fix compilation or runtime errors in a generated test file.\n17. **`skyramp_modularization`** \u2014 Refactor a test file into reusable modules. Set `isTraceBased: true` for trace-based tests.\n18. **`skyramp_reuse_code`** \u2014 Pull shared helpers from other Skyramp tests. Only when `code_reuse` was `true` at generation time.\n\n### Authentication\n19. **`skyramp_login`** \u2014 Log in to the Skyramp platform.\n20. **`skyramp_logout`** \u2014 Log out from the Skyramp platform.\n\n---\n\n## Prompts\n\nPrefer invoking a prompt over manually chaining tools \u2014 prompts run the full workflow automatically.\n\n- **`skyramp_trace_prompt`** \u2014 Trace collection setup and execution.\n- **`skyramp_test_health_analysis`** \u2014 Full maintenance flow (discover \u2192 drift \u2192 health \u2192 actions).\n- **`skyramp_testbot`** \u2014 PR-scoped recommendations + maintenance + report. Required: `prTitle`, `prDescription`, `repositoryPath`.\n\n---\n\n## Workflows\n\nUse these when a prompt is not available.\n\n**Generate and run a test**\nRead `.skyramp/workspace.yml` \u2192 Call appropriate generation tool \u2192 `skyramp_execute_test`\n\n**Trace-based test (integration / load / E2E / UI)**\n`skyramp_start_trace_collection` (set `playwright: true` for UI/E2E) \u2192 User exercises the app \u2192 `skyramp_stop_trace_collection` \u2192 Call target generation tool with `trace` (and `playwrightInput` for E2E/UI)\n\n**Scenario \u2192 integration test**\n`skyramp_scenario_test_generation` \u2192 `skyramp_integration_test_generation` with `scenarioFile`\n\n**Recommend tests for a PR**\n`skyramp_analyze_changes` (with `scope: \"branch_diff\"`) \u2192 follow enrichment steps \u2192 `skyramp_recommend_tests` \u2192 Generate recommended tests\n\n**Maintain existing tests**\n`skyramp_analyze_changes` \u2192 `skyramp_analyze_test_health` \u2192 *(optional)* execute tests via `skyramp_execute_test` with `stateFile` param (writes results back) \u2192 `skyramp_actions` (do not skip)\n\n---\n\n## Conventions\n\n- **`endpointURL`** \u2014 Full URL to a specific endpoint, not just the base URL. Build from `api.baseUrl` + path (e.g. `http://localhost:8000/api/v1/users`).\n- **`outputDir`** \u2014 Use absolute paths for both test output and trace collection.\n- **Mutually exclusive inputs** \u2014 `apiSchema`/`endpointURL`, `trace`, and `scenarioFile` are mutually exclusive for integration and load tests. Use exactly one.\n- **Sequential execution** \u2014 Execute tests sequentially (not in parallel) to avoid environment variable conflicts with `SKYRAMP_TEST_BASE_URL`.\n";
+export declare const SKYRAMP_MD_CONTENT = "---\nname: skyramp\ndescription: Generate, execute, and maintain API tests (smoke, contract, fuzz, load, integration, E2E, UI) using Skyramp MCP tools.\n---\n\n# Skyramp\n\n## When to use this skill\nUse this skill whenever the user asks to generate, run, or maintain API tests. Always read `<workspace-root>/.skyramp/workspace.yml` first to get `language`, `framework`, `outputDir`, and `api.baseUrl` \u2014 do not ask the user for values already present.\n\n---\n\n## Tools\n\n### Workspace Setup\n1. **`skyramp_initialize_workspace`** \u2014 Create or update `.skyramp/workspace.yml` in a git repository workspace. Scan the repo for all services before calling. Required before any other Skyramp tool.\n\n### Test Generation\n2. **`skyramp_smoke_test_generation`** \u2014 Verify an endpoint is reachable and returns a valid response.\n3. **`skyramp_contract_test_generation`** \u2014 Validate implementation matches OpenAPI/Swagger schema.\n4. **`skyramp_fuzz_test_generation`** \u2014 Send malformed or boundary inputs to find edge cases and security issues.\n5. **`skyramp_load_test_generation`** \u2014 Test performance under concurrent load. Optional: `loadDuration`, `loadNumThreads`. Accepts `trace` instead of `apiSchema`/`endpointURL`.\n6. **`skyramp_integration_test_generation`** \u2014 Multi-step workflows across one or more services. Supply one of: `apiSchema`+`endpointURL`, `trace`, or `scenarioFile`. Do not combine them.\n7. **`skyramp_e2e_test_generation`** \u2014 Full user journey covering UI and backend. Requires `trace` and `playwrightInput` zip. Do not pass `apiSchema` or `endpointURL`.\n8. **`skyramp_ui_test_generation`** \u2014 UI-only tests from Playwright recordings. Requires `playwrightInput` zip.\n\n### Trace Generation\n9. **`skyramp_start_trace_collection`** \u2014 Start capturing backend traffic. Set `playwright: true` for UI or E2E tests. Use an absolute path for `outputDir`.\n10. **`skyramp_stop_trace_collection`** \u2014 Stop capture and save the trace. Use the same `outputDir` and `playwrightEnabled` values as start.\n11. **`skyramp_scenario_test_generation`** \u2014 Scenario trace generation. Describe a multi-step flow in natural language to produce a scenario file. Pass output to `skyramp_integration_test_generation` via `scenarioFile`.\n\n### Test Execution\n12. **`skyramp_execute_test`** \u2014 Run one test file and record the verdict from the exit code. Required: `testFile`, `language`, `testType`, `repository`. To run on this host, pass `commandOverride` (the command for that one file) with `cwd`. Omit `commandOverride` to run in the Skyramp executor instead, which needs `workspacePath`. Optional: `stateFile` (writes execution results back for health analysis). Output is capped at the last 200,000 characters.\n\n### Test Analysis & Maintenance\n13. **`skyramp_analyze_changes`** \u2014 Unified entry point: scans endpoints, discovers tests, computes diff. Takes `repositoryPath` and `scope`. Returns `stateFile` + recommendations.\n14. **`skyramp_analyze_test_health`** \u2014 Drift and health assessment for existing tests. Takes `stateFile`. Returns LLM prompt for scoring.\n15. **`skyramp_actions`** \u2014 Execute UPDATE / REGENERATE / VERIFY / DELETE actions. Takes `stateFile`. Call after analyze_test_health.\n\n### Code Quality\n16. **`skyramp_fix_errors`** \u2014 Fix compilation or runtime errors in a generated test file.\n17. **`skyramp_modularization`** \u2014 Refactor a test file into reusable modules. Set `isTraceBased: true` for trace-based tests.\n18. **`skyramp_reuse_code`** \u2014 Pull shared helpers from other Skyramp tests. Only when `code_reuse` was `true` at generation time.\n\n### Authentication\n19. **`skyramp_login`** \u2014 Log in to the Skyramp platform.\n20. **`skyramp_logout`** \u2014 Log out from the Skyramp platform.\n\n---\n\n## Prompts\n\nPrefer invoking a prompt over manually chaining tools \u2014 prompts run the full workflow automatically.\n\n- **`skyramp_trace_prompt`** \u2014 Trace collection setup and execution.\n- **`skyramp_test_health_analysis`** \u2014 Full maintenance flow (discover \u2192 drift \u2192 health \u2192 actions).\n- **`skyramp_testbot`** \u2014 PR-scoped recommendations + maintenance + report. Required: `prTitle`, `prDescription`, `repositoryPath`.\n\n---\n\n## Workflows\n\nUse these when a prompt is not available.\n\n**Generate and run a test**\nRead `.skyramp/workspace.yml` \u2192 Call appropriate generation tool \u2192 `skyramp_execute_test`\n\n**Trace-based test (integration / load / E2E / UI)**\n`skyramp_start_trace_collection` (set `playwright: true` for UI/E2E) \u2192 User exercises the app \u2192 `skyramp_stop_trace_collection` \u2192 Call target generation tool with `trace` (and `playwrightInput` for E2E/UI)\n\n**Scenario \u2192 integration test**\n`skyramp_scenario_test_generation` \u2192 `skyramp_integration_test_generation` with `scenarioFile`\n\n**Recommend tests for a PR**\n`skyramp_analyze_changes` (with `scope: \"branch_diff\"`) \u2192 follow enrichment steps \u2192 `skyramp_recommend_tests` \u2192 Generate recommended tests\n\n**Maintain existing tests**\n`skyramp_analyze_changes` \u2192 `skyramp_analyze_test_health` \u2192 *(optional)* execute tests via `skyramp_execute_test` with `stateFile` param (writes results back) \u2192 `skyramp_actions` (do not skip)\n\n---\n\n## Conventions\n\n- **`endpointURL`** \u2014 Full URL to a specific endpoint, not just the base URL. Build from `api.baseUrl` + path (e.g. `http://localhost:8000/api/v1/users`).\n- **`outputDir`** \u2014 Use absolute paths for both test output and trace collection.\n- **Mutually exclusive inputs** \u2014 `apiSchema`/`endpointURL`, `trace`, and `scenarioFile` are mutually exclusive for integration and load tests. Use exactly one.\n- **Sequential execution** \u2014 Execute tests sequentially (not in parallel) to avoid environment variable conflicts with `SKYRAMP_TEST_BASE_URL`.\n";

package/build/utils/skyrampMdContent.js

@@ -34,7 +34,7 @@ Use this skill whenever the user asks to generate, run, or maintain API tests. A
 11. **\`skyramp_scenario_test_generation\`** — Scenario trace generation. Describe a multi-step flow in natural language to produce a scenario file. Pass output to \`skyramp_integration_test_generation\` via \`scenarioFile\`.
 
 ### Test Execution
-12. **\`skyramp_execute_test\`** — Run a single Skyramp-generated test file. Required: \`workspacePath\`, \`language\`, \`testType\`, \`testFile\`. Optional: \`stateFile\` (writes execution results back for health analysis). For multiple tests, call sequentially to avoid env var conflicts.
+12. **\`skyramp_execute_test\`** — Run one test file and record the verdict from the exit code. Required: \`testFile\`, \`language\`, \`testType\`, \`repository\`. To run on this host, pass \`commandOverride\` (the command for that one file) with \`cwd\`. Omit \`commandOverride\` to run in the Skyramp executor instead, which needs \`workspacePath\`. Optional: \`stateFile\` (writes execution results back for health analysis). Output is capped at the last 200,000 characters.
 
 ### Test Analysis & Maintenance
 13. **\`skyramp_analyze_changes\`** — Unified entry point: scans endpoints, discovers tests, computes diff. Takes \`repositoryPath\` and \`scope\`. Returns \`stateFile\` + recommendations.

package/build/utils/skyrampSdkVersion.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The Skyramp SDK version installed beside this server, which is the version the
+ * generated tests are written against.
+ *
+ * Read once: it cannot change while the process runs. The SDK is a direct
+ * dependency that this server imports at load time, so it is always installed
+ * here — a read failure is a broken install, not a state to degrade into.
+ */
+export declare const SKYRAMP_SDK_VERSION: string;

package/build/utils/skyrampSdkVersion.js

@@ -0,0 +1,16 @@
+import { readFileSync } from "fs";
+import { createRequire } from "module";
+const require = createRequire(import.meta.url);
+/**
+ * The Skyramp SDK version installed beside this server, which is the version the
+ * generated tests are written against.
+ *
+ * Read once: it cannot change while the process runs. The SDK is a direct
+ * dependency that this server imports at load time, so it is always installed
+ * here — a read failure is a broken install, not a state to degrade into.
+ */
+export const SKYRAMP_SDK_VERSION = readInstalledSdkVersion();
+function readInstalledSdkVersion() {
+    const manifest = require.resolve("@skyramp/skyramp/package.json");
+    return JSON.parse(readFileSync(manifest, "utf8")).version;
+}

package/build/utils/testDependencyPolicy.js

@@ -6,6 +6,7 @@ import { promisify } from "util";
 import fg from "fast-glob";
 import { canonicalJson as canonical, isPlainObject as isObject, } from "./canonicalJson.js";
 import { listChangedFiles } from "./reportVerification.js";
+import { SKYRAMP_SDK_VERSION } from "./skyrampSdkVersion.js";
 const execFileAsync = promisify(execFile);
 export const NPM_TEST_PACKAGES = new Set([
     "@playwright/test",
@@ -48,6 +49,7 @@ export const JAVA_TEST_PACKAGES = new Set([
     "org.junit.platform:junit-platform-console-standalone",
     "org.mockito:mockito-core",
     "org.testng:testng",
+    "dev.skyramp:skyramp-library",
 ]);
 const DEPENDENCY_FILES = {
     javascript: {
@@ -57,6 +59,9 @@ const DEPENDENCY_FILES = {
             "npm-shrinkwrap.json",
             "yarn.lock",
             "pnpm-lock.yaml",
+            // Named in the fix-errors guidance, so it must not bypass validation.
+            "bun.lock",
+            "bun.lockb",
         ],
     },
     python: {
@@ -277,10 +282,26 @@ function verifyPackageJson(file, beforeRaw, afterRaw, violations) {
         else if (!isSafeNpmSpecifier(afterDev[name])) {
             violations.push(`${file}: ${name} must use a registry version, not an alias, URL, git, or local package source.`);
         }
+        else if (!declaresServerSdkVersion(name, afterDev[name])) {
+            violations.push(`${file}: ${name} is declared as ${afterDev[name]}, but the tests were generated by ${SKYRAMP_SDK_VERSION}. Declare exactly ${SKYRAMP_SDK_VERSION}, with no range operator: a range lets a clean install resolve a different SDK.`);
+        }
     }
     return (canonical(beforeRuntime) !== canonical(afterRuntime) ||
         canonical(beforeDev) !== canonical(afterDev));
 }
+/** The SDK the tests were generated by is the one this server imports, so the
+ *  repository must declare exactly that version. Only the npm spelling carries
+ *  a version: the Python and Java manifests declare the SDK without one, so
+ *  neither is checked here.
+ *
+ *  The specifier must be the bare version. A range is refused, including
+ *  `^1.2.3`: it permits 1.3.0, so a clean install elsewhere can resolve an SDK
+ *  that did not write these tests, which is the whole thing this prevents. */
+function declaresServerSdkVersion(name, specifier) {
+    if (name !== "@skyramp/skyramp")
+        return true;
+    return specifier.trim() === SKYRAMP_SDK_VERSION;
+}
 function verifyPyproject(file, beforeRaw, afterRaw, violations) {
     const before = pythonDevView(beforeRaw);
     const after = pythonDevView(afterRaw);

package/build/utils/testExecutionRecord.d.ts

@@ -79,6 +79,7 @@ export declare function reserveTestExecutionAttempt(stateFile: string, repo: str
  * per-file testExecutions record (every file, keyed by canonical path — see
  * executionRecordFrom), plus the maintained-test executionBefore/After row
  * when `testFile` has one. No-op when the repo section doesn't exist yet.
+ * Returns what was written, so the caller can say what was not.
  *
  * Extracted from skyramp_execute_test's own state-write block so the
  * behavior that makes a file's result available to the post-execution
@@ -87,4 +88,7 @@ export declare function reserveTestExecutionAttempt(stateFile: string, repo: str
  */
 export declare function persistTestExecutionResult(stateFile: string, repo: string, testType: TestType, phase: "before" | "after", result: TestExecutionResult, options?: {
     reserved?: boolean;
-}): Promise<void>;
+}): Promise<{
+    saved: boolean;
+    matchedExistingTest: boolean;
+}>;

package/build/utils/testExecutionRecord.js

@@ -231,6 +231,7 @@ fileHash) {
  * per-file testExecutions record (every file, keyed by canonical path — see
  * executionRecordFrom), plus the maintained-test executionBefore/After row
  * when `testFile` has one. No-op when the repo section doesn't exist yet.
+ * Returns what was written, so the caller can say what was not.
  *
  * Extracted from skyramp_execute_test's own state-write block so the
  * behavior that makes a file's result available to the post-execution
@@ -245,7 +246,7 @@ export async function persistTestExecutionResult(stateFile, repo, testType, phas
         const stateManager = StateManager.fromStatePath(stateFile);
         const stateData = await stateManager.readRepoData(repo);
         if (!stateData)
-            return;
+            return { saved: false, matchedExistingTest: false };
         const testIndex = stateData.existingTests?.findIndex((t) => canonicalTestPath(t.testFile) === canonicalTestPath(testFile)) ?? -1;
         if (testIndex >= 0) {
             if (phase === "before") {
@@ -263,5 +264,6 @@ export async function persistTestExecutionResult(stateFile, repo, testType, phas
             !options.reserved),
         };
         await stateManager.updateRepoData(stateData, { repo });
+        return { saved: true, matchedExistingTest: testIndex >= 0 };
     });
 }

package/build/utils/testFileClassification.d.ts

@@ -14,6 +14,14 @@ export declare function isDiscoveredTestFile(filePath: string): boolean;
  *  `isDiscoveredTestFile`'s rule, which also counts `tests/`, a page-object
  *  directory and `test_orders.py`. The maintenance tool wants this narrow one. */
 export declare function isTestFile(filePath: string): boolean;
+/** The file's own NAME says it is a test — `login.spec.ts`, `orders.test.js`,
+ *  `test_orders.py`, `UserDAOTest.java`. Almost entirely a NAME rule: a helper,
+ *  a fixture, a page object or a config sitting in `e2e/` or `cypress/support/`
+ *  is not a test and cannot be run as one. The one exception is `__tests__/`,
+ *  Jest's convention that everything inside it is a test whatever it is called.
+ *  Exported for callers that must not act on a file merely because of where it
+ *  lives. */
+export declare function hasTestFileName(filePath: string): boolean;
 /** Whether a path is a test file, by directory or by name. Read by the route
  *  checks: a route declared in a mock server or a spec fixture is not a surface
  *  anyone serves. */

package/build/utils/testFileClassification.js

@@ -76,10 +76,43 @@ const TEST_ROOT_DIR = /(^|[\\/])(tests?|__tests__|__mocks__|e2e|cypress|testing)
  *  `TEST_FILE_PATTERNS` rows it resembles — any extension, and `.`, `_` or `-`
  *  before `test` — so no row above can stand in for it. */
 const TEST_FILE_NAME = /[._-](test|spec)\.[a-z]+$|(^|[\\/])test_[^\\/]*$/i;
+/** The file's own NAME says it is a test — `login.spec.ts`, `orders.test.js`,
+ *  `test_orders.py`, `UserDAOTest.java`. Almost entirely a NAME rule: a helper,
+ *  a fixture, a page object or a config sitting in `e2e/` or `cypress/support/`
+ *  is not a test and cannot be run as one. The one exception is `__tests__/`,
+ *  Jest's convention that everything inside it is a test whatever it is called.
+ *  Exported for callers that must not act on a file merely because of where it
+ *  lives. */
+export function hasTestFileName(filePath) {
+    return (
+    // Discovery's own name rule, applied to the basename so it admits no
+    // directory. It carries the framework spellings the regexes below miss:
+    // `UserDAOTest.java`, `orders_smoke.py`, `checkout_e2e.ts`.
+    TEST_FILE_PATTERNS.some((p) => p.test(path.basename(filePath))) ||
+        TEST_FILE_NAME.test(filePath) ||
+        CAMEL_TEST_FILE_NAME.test(filePath) ||
+        // Surefire's default includes are `Test*.java` as well as `*Test.java`, and
+        // Failsafe's are `*IT.java`. CAMEL_TEST_FILE_NAME needs a lowercase
+        // character before the suffix, so the acronym spelling (`APIIT.java`) and
+        // the prefix spelling (`TestOrder.java`) both fall through it.
+        /(^|[\\/])Test[A-Z][A-Za-z0-9]*\.(java|kt|kts|scala)$/.test(filePath) ||
+        /[A-Za-z0-9]IT\.(java|kt|kts|scala)$/.test(filePath) ||
+        // mocha's default spec glob is `./test/*.js` — one directory level, and no
+        // name rule at all, so `test/app.js` is a test to mocha.
+        /(^|[\\/])test[\\/][^\\/]+\.(js|cjs|mjs)$/.test(filePath) ||
+        // `login.e2e.ts` and Cypress's own `login.cy.ts` — the dot forms
+        // TEST_FILE_NAME does not carry. `.cy.` is to Cypress what `.spec.` is to
+        // Playwright.
+        /\.(cy|e2e)\.[a-z]+$/i.test(filePath) ||
+        // Jest's convention: everything under `__tests__/` is a test, whatever it
+        // is called. The only directory that means that on its own.
+        /(^|[\\/])__tests__[\\/]/.test(filePath));
+}
 /** The CamelCase spellings, which carry no separator before `Test`.
- *  Case-SENSITIVE and must stay so: with `i` it also matches `Latest.java` and
- *  `Manifest.cs`, ordinary source files. That is why the case-insensitive
- *  `*Test.java` / `*Tests.cs` rows above cannot serve here. */
+ *  Case-SENSITIVE and must stay so: with `i` it also matches `Latest.java`,
+ *  `Audit.java`, `Edit.cs` and `Digit.ts`, ordinary source files. That is why
+ *  the case-insensitive `*Test.java` / `*Tests.cs` rows above cannot serve
+ *  here. */
 const CAMEL_TEST_FILE_NAME = /[a-z0-9](Tests?|IT)\.[A-Za-z0-9]+$/;
 /** Whether a path is a test file, by directory or by name. Read by the route
  *  checks: a route declared in a mock server or a spec fixture is not a surface

package/build/utils/utils-verify/action-key.d.ts

@@ -25,7 +25,49 @@ import type { UtilsLanguage } from "./language-spec.js";
  * helper in either language gets the same key.
  */
 export declare function actionKeyOf(body: string, language?: UtilsLanguage): string | undefined;
+/** The keys of every step, in order, or `undefined` when there is no step or a
+ *  step has no key — the sequence `actionKeyOf` joins, kept as steps for a caller
+ *  that matches step by step (a key is not split back: a selector may carry the
+ *  separator). */
+export declare function actionStepKeys(steps: ActionStep[]): string[] | undefined;
+/** One Playwright action in a body, in source order — the unit `actionKeyOf` joins. */
+export interface ActionStep {
+    /** The step's key (`verb chain [target]`), or `undefined` when this action cannot
+     *  be read: its locator is not built from plain string literals, or its arguments
+     *  do not balance. A helper with one such step has no key; a spec's other steps
+     *  are still read, so an unreadable step is a boundary no matched run crosses. */
+    key?: string;
+    /** 1-based line of the action verb. */
+    line: number;
+    /** The source between the previous action's closing `)` (or the start of the
+     *  body) and this action's chain: what stands between two consecutive actions.
+     *  Comments are as the caller left them; string contents are kept. Empty for
+     *  the first step. See `betweenActionsIsTransparent`. */
+    gapBefore: string;
+    /** The source after this action's closing `)` up to the next action's chain, or
+     *  to the end of the body for the last step — the next step's `gapBefore`. */
+    gapAfter: string;
+}
+/**
+ * Every action in `body`, in order, each keyed as `actionKeyOf` keys it. Where
+ * `actionKeyOf` answers "what does this helper do" with one string, this answers
+ * "which actions, where, and what sits between them" — what a scan for an inline
+ * copy of a helper's sequence needs. Lines survive the Python and alias rewrites:
+ * neither adds or removes a newline.
+ */
+export declare function actionStepsOf(body: string, language?: UtilsLanguage): ActionStep[];
+/** `click empty-cart-btn; fill qty` → `click \`empty-cart-btn\`; fill \`qty\`` — the
+ *  key as the agent reads it, selectors quoted so a `#id` never reads as prose. */
+export declare function describeActionKey(key: string): string;
 /** Index of the `)` that closes the `(` at `open`, on a string-blanked copy. */
 export declare function matchingClose(structure: string, open: number): number;
+/** Whitespace and braces dropped outside string literals, `'` normalised to `"` —
+ *  the spelling a locator chain has inside a key. */
+export declare function normalizeChain(text: string): string;
 /** String contents replaced by spaces, delimiters kept, same length. */
 export declare function blankStringContents(text: string): string;
+/** The statements of a fragment as `[start, end)` spans on `structure` (a
+ *  string-blanked copy): each cut where valueEnd cuts — a `;` at depth 0, or a line
+ *  end at depth 0 that the next line does not continue with `.` — so a
+ *  Prettier-wrapped chain is one statement, not one per line. */
+export declare function statementSpans(structure: string): [number, number][];