@skyramp/mcp 0.3.2 → 0.3.4

package/build/utils/gitStaging.d.ts

@@ -10,6 +10,11 @@ export declare function isInsideDir(child: string, parent: string): boolean;
  * is unset or the path is already inside it.
  */
 export declare function resolveOutputDir(outputDir: string, testsRepoDir: string | undefined): string;
+/**
+ * Detect the git repository root for a given file or directory path.
+ * Returns undefined if detection fails (not inside a git repo).
+ */
+export declare function detectGitRoot(filePath: string): string | undefined;
 /**
  * Stages a file path an MCP tool just wrote into the git index by
  * running `git add -- <path>`.

package/build/utils/gitStaging.js

@@ -33,7 +33,7 @@ const execFileAsync = promisify(execFile);
  * Detect the git repository root for a given file or directory path.
  * Returns undefined if detection fails (not inside a git repo).
  */
-function detectGitRoot(filePath) {
+export function detectGitRoot(filePath) {
     if (!path.isAbsolute(filePath))
         return undefined;
     try {

package/build/utils/pom-catalog.d.ts

@@ -0,0 +1,23 @@
+export declare const POM_CATALOG_FILENAME = "skyramp-pom-catalog.md";
+/**
+ * The one canonical path for a test file's `skyramp-pom-catalog.md`:
+ * `<repoRoot>/.skyramp/skyramp-pom-catalog.md`.
+ *
+ * The catalog is cross-run state, and one path per repository is what keeps it
+ * usable — two runs writing at different depths fork the cache so neither finds
+ * the other's. It sits beside `workspace.yml` rather than in the customer's test
+ * directory because it is generated tooling state, not a deliverable, and
+ * delivery stages it by name (SKYR-4125).
+ *
+ * The root is resolved in priority order:
+ * 1. `getTestsRepoDir()` — the test-repo clone root set by `skyramp_analyze_changes`
+ *    when `testsRepoDir` is provided. In cross-repo delivery testbot commits ONLY
+ *    to this clone, so the catalog must anchor here or it is never staged and the
+ *    cache dies silently.
+ * 2. `detectGitRoot` — the fallback for same-repo runs (where nothing sets the
+ *    tests-repo dir) and for the NL path, where a developer drives
+ *    `skyramp_ui_test_generation`/`skyramp_reuse_code` directly without ever
+ *    calling `skyramp_analyze_changes`.
+ * 3. The test file's own directory, for a path in no repository at all.
+ */
+export declare function resolvePomCatalogPath(testFile: string): string;

package/build/utils/pom-catalog.js

@@ -0,0 +1,30 @@
+import path from "path";
+import { getTestsRepoDir } from "./AnalysisStateManager.js";
+import { detectGitRoot } from "./gitStaging.js";
+export const POM_CATALOG_FILENAME = "skyramp-pom-catalog.md";
+/**
+ * The one canonical path for a test file's `skyramp-pom-catalog.md`:
+ * `<repoRoot>/.skyramp/skyramp-pom-catalog.md`.
+ *
+ * The catalog is cross-run state, and one path per repository is what keeps it
+ * usable — two runs writing at different depths fork the cache so neither finds
+ * the other's. It sits beside `workspace.yml` rather than in the customer's test
+ * directory because it is generated tooling state, not a deliverable, and
+ * delivery stages it by name (SKYR-4125).
+ *
+ * The root is resolved in priority order:
+ * 1. `getTestsRepoDir()` — the test-repo clone root set by `skyramp_analyze_changes`
+ *    when `testsRepoDir` is provided. In cross-repo delivery testbot commits ONLY
+ *    to this clone, so the catalog must anchor here or it is never staged and the
+ *    cache dies silently.
+ * 2. `detectGitRoot` — the fallback for same-repo runs (where nothing sets the
+ *    tests-repo dir) and for the NL path, where a developer drives
+ *    `skyramp_ui_test_generation`/`skyramp_reuse_code` directly without ever
+ *    calling `skyramp_analyze_changes`.
+ * 3. The test file's own directory, for a path in no repository at all.
+ */
+export function resolvePomCatalogPath(testFile) {
+    const abs = path.resolve(testFile);
+    const root = getTestsRepoDir() ?? detectGitRoot(abs) ?? path.dirname(abs);
+    return path.join(root, ".skyramp", POM_CATALOG_FILENAME);
+}

package/build/utils/pom-scope/pom-files.d.ts

@@ -1,3 +1,17 @@
+/**
+ * Spec/test basenames. POM discovery excludes them; {@link globSpecFiles}
+ * targets them.
+ */
+export declare const SPEC_BASENAME: RegExp;
 export declare function globPomFiles(root: string): Promise<string[]>;
+/**
+ * Spec files anywhere under `root`, by basename rather than by directory.
+ *
+ * Suites are often grouped by feature or customer rather than under `tests/`
+ * (e.g. `box/workflow.spec.ts`), so the directory name gives nothing away — but
+ * the filename always does. Keeps the cypress/`__tests__` trees that POM
+ * discovery skips: here the tests are the subject, not the thing to skip past.
+ */
+export declare function globSpecFiles(root: string): Promise<string[]>;
 /** Fallback discovery for repos whose POM layer doesn't match the conventional glob patterns. */
 export declare function globAllSourceFiles(root: string): Promise<string[]>;

package/build/utils/pom-scope/pom-files.js

@@ -16,18 +16,24 @@ const POM_GLOBS = [
     "**/{test,tests,e2e,playwright}/**/{lib,utils,helpers,support}/**/*.{ts,js}",
     "**/{testUtils,test-utils,testHelpers,test-helpers}.{ts,js}",
 ];
-const EXCLUDED_BASENAME = /\.(spec|test|cy)\.(ts|js|tsx|jsx|mjs|cjs)$/;
+/**
+ * Spec/test basenames. POM discovery excludes them; {@link globSpecFiles}
+ * targets them.
+ */
+export const SPEC_BASENAME = /\.(spec|test|cy)\.(ts|js|tsx|jsx|mjs|cjs)$/;
 const ALL_SOURCE_GLOBS = ["**/*.{ts,js,tsx,jsx,mjs,cjs}"];
-const ALL_SOURCE_IGNORE = [
+/** Never source: dependencies, build output, VCS metadata. */
+const BUILD_IGNORE = [
     "**/node_modules/**",
     "**/dist/**",
     "**/build/**",
     "**/coverage/**",
     "**/.git/**",
     "**/vendor/**",
-    "**/cypress/**",
-    "**/__tests__/**",
 ];
+/** Test trees a POM is not expected to live in. Not skipped when the tests themselves are the subject. */
+const TEST_TREE_IGNORE = ["**/cypress/**", "**/__tests__/**"];
+const ALL_SOURCE_IGNORE = [...BUILD_IGNORE, ...TEST_TREE_IGNORE];
 export async function globPomFiles(root) {
     const matches = await fg(POM_GLOBS, {
         cwd: root,
@@ -37,7 +43,27 @@ export async function globPomFiles(root) {
         followSymbolicLinks: false,
     });
     return [...new Set(matches)]
-        .filter((f) => !EXCLUDED_BASENAME.test(path.basename(f)))
+        .filter((f) => !SPEC_BASENAME.test(path.basename(f)))
+        .sort();
+}
+/**
+ * Spec files anywhere under `root`, by basename rather than by directory.
+ *
+ * Suites are often grouped by feature or customer rather than under `tests/`
+ * (e.g. `box/workflow.spec.ts`), so the directory name gives nothing away — but
+ * the filename always does. Keeps the cypress/`__tests__` trees that POM
+ * discovery skips: here the tests are the subject, not the thing to skip past.
+ */
+export async function globSpecFiles(root) {
+    const matches = await fg(ALL_SOURCE_GLOBS, {
+        cwd: root,
+        absolute: true,
+        ignore: BUILD_IGNORE,
+        suppressErrors: true,
+        followSymbolicLinks: false,
+    });
+    return [...new Set(matches)]
+        .filter((f) => SPEC_BASENAME.test(path.basename(f)))
         .sort();
 }
 /** Fallback discovery for repos whose POM layer doesn't match the conventional glob patterns. */
@@ -50,6 +76,6 @@ export async function globAllSourceFiles(root) {
         followSymbolicLinks: false,
     });
     return [...new Set(matches)]
-        .filter((f) => !EXCLUDED_BASENAME.test(path.basename(f)))
+        .filter((f) => !SPEC_BASENAME.test(path.basename(f)))
         .sort();
 }

package/build/utils/pom-scope/testIdDiscovery.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Which attribute does this repository use for test ids?
+ *
+ * The blueprint capture anchors every element's xpath on a test-id attribute
+ * when it can find one, and assumes Playwright's `data-testid` otherwise. A repo
+ * using anything else gets no anchor and a positional xpath instead — which
+ * resolves at capture time and breaks later, so the miss is invisible.
+ *
+ * Enumerating popular names (`data-test`, `data-qa`, ...) only covers the repos
+ * someone thought of. The repository already answers the question itself: its
+ * page objects and specs name the attribute every time they select on it. So
+ * read the answer out of the selectors rather than guessing at it.
+ */
+export type AttributeCount = {
+    attribute: string;
+    count: number;
+};
+export type TestIdDiscovery = {
+    /** Most-used qualifying attribute, or undefined when nothing qualified. */
+    attribute?: string;
+    /** Every qualifying attribute with its selector count, most-used first. */
+    counts: AttributeCount[];
+    /**
+     * Most-used attributes overall, qualifying or not.
+     *
+     * The point of reporting these is the case no name rule can reach: a suite
+     * selecting on something arbitrary like `xyz-id` produces no qualifying
+     * candidate, and the miss is otherwise invisible. Printed on a miss, this names
+     * the attribute an operator would set explicitly.
+     */
+    observed: AttributeCount[];
+    filesScanned: number;
+};
+/**
+ * Report which test-id attribute this repository's page objects and specs use.
+ *
+ * Never throws: an unreadable tree yields no attribute, which leaves the capture
+ * on Playwright's default.
+ */
+export declare function discoverTestIdAttribute(root: string): Promise<TestIdDiscovery>;

package/build/utils/pom-scope/testIdDiscovery.js

@@ -0,0 +1,104 @@
+/**
+ * Which attribute does this repository use for test ids?
+ *
+ * The blueprint capture anchors every element's xpath on a test-id attribute
+ * when it can find one, and assumes Playwright's `data-testid` otherwise. A repo
+ * using anything else gets no anchor and a positional xpath instead — which
+ * resolves at capture time and breaks later, so the miss is invisible.
+ *
+ * Enumerating popular names (`data-test`, `data-qa`, ...) only covers the repos
+ * someone thought of. The repository already answers the question itself: its
+ * page objects and specs name the attribute every time they select on it. So
+ * read the answer out of the selectors rather than guessing at it.
+ */
+import { readFile } from "fs/promises";
+import { globPomFiles, globSpecFiles } from "./pom-files.js";
+import { DEFAULT_TESTID_ATTRS } from "./selector-extractor.js";
+/** Bound the read — a monorepo scan must not delay server startup. */
+const MAX_FILES = 400;
+const MAX_BYTES_PER_FILE = 256 * 1024;
+/**
+ * Attribute name inside an attribute selector: `[data-test="x"]`, `[qa-id='y']`.
+ *
+ * Deliberately open-ended, which is why it cannot reuse `selector-extractor`'s
+ * pattern: that one is built from a known attribute list to *extract values for
+ * attributes we already named*, whereas this has to surface names nobody listed.
+ */
+const ATTR_SELECTOR_RE = /\[\s*([A-Za-z][A-Za-z0-9_:-]*)\s*[~^$*|]?=\s*["']/g;
+/**
+ * Tokens by which an attribute name declares itself to be about testing.
+ *
+ * Matched as whole tokens, never as prefixes. `auto` is deliberately absent —
+ * it admitted `data-auto-play` and `data-auto-height`, and `automation` already
+ * covers the convention it was there for (`data-automation-id`).
+ */
+const TEST_TOKENS = new Set(["test", "testid", "tests", "qa", "cy", "cypress", "e2e", "automation"]);
+/**
+ * Whether a name plausibly denotes a test id.
+ *
+ * A name heuristic, safe only because of what it is applied to: an attribute the
+ * repository's own tests already select on. A name that is both used as a
+ * selector and self-describes as test-related is not going to be
+ * `data-testimonial`. Applied to raw DOM attributes the same rule would be
+ * reckless.
+ *
+ * Requiring a token is also what keeps the standard attributes out — `type`,
+ * `role`, `href`, `aria-label`, `placeholder` and the rest carry no such token,
+ * so no exclusion list is needed alongside this. (`autocomplete` tokenises as one
+ * word, so it does not match `auto`.)
+ */
+function looksLikeTestId(attr) {
+    const lower = attr.toLowerCase();
+    if (DEFAULT_TESTID_ATTRS.includes(lower))
+        return true;
+    const tokens = lower.split(/[^a-z0-9]+/).filter(Boolean);
+    if (tokens.some((t) => TEST_TOKENS.has(t)))
+        return true;
+    // Glued forms like `datatestid`. Anchored at the end on purpose: a
+    // `startsWith("test")` catch-all also admits `data-testimonial`, and since
+    // candidates are ranked by use count, a false positive used more often than
+    // the real attribute becomes the anchor for the whole repo.
+    return tokens.some((t) => t.endsWith("testid"));
+}
+const OBSERVED_REPORT_LIMIT = 5;
+/**
+ * Report which test-id attribute this repository's page objects and specs use.
+ *
+ * Never throws: an unreadable tree yields no attribute, which leaves the capture
+ * on Playwright's default.
+ */
+export async function discoverTestIdAttribute(root) {
+    let files;
+    try {
+        const [poms, specs] = await Promise.all([globPomFiles(root), globSpecFiles(root)]);
+        files = [...new Set([...poms, ...specs])].slice(0, MAX_FILES);
+    }
+    catch {
+        return { counts: [], observed: [], filesScanned: 0 };
+    }
+    const all = new Map();
+    for (const file of files) {
+        let content;
+        try {
+            content = (await readFile(file, "utf8")).slice(0, MAX_BYTES_PER_FILE);
+        }
+        catch {
+            continue;
+        }
+        for (const match of content.matchAll(ATTR_SELECTOR_RE)) {
+            const attr = match[1];
+            all.set(attr, (all.get(attr) ?? 0) + 1);
+        }
+    }
+    // Count first; name as a tiebreak so the result never depends on walk order.
+    const ranked = [...all.entries()]
+        .map(([attribute, count]) => ({ attribute, count }))
+        .sort((a, b) => b.count - a.count || a.attribute.localeCompare(b.attribute));
+    const counts = ranked.filter((c) => looksLikeTestId(c.attribute));
+    return {
+        attribute: counts[0]?.attribute,
+        counts,
+        observed: ranked.slice(0, OBSERVED_REPORT_LIMIT),
+        filesScanned: files.length,
+    };
+}

package/build/utils/reportVerification.d.ts

@@ -26,10 +26,12 @@ export interface UnbackedClaimsInput {
         fileName?: string;
         repository?: string;
     }[];
-    /** Maintenance verdicts (server-derived from skyramp_actions). */
+    /** Maintenance verdicts (server-derived from skyramp_actions). `pomFile`, when set, is
+     *  the file the edit actually lands in — see the UPDATE rule below. */
     verdicts: {
         action: DriftAction;
         testFilePath: string;
+        pomFile?: string;
     }[];
     /** owner/repo of the primary repo — used to exempt cross-repo newTest claims
      *  whose files live in a different checkout. */
@@ -46,7 +48,10 @@ export interface UnbackedClaimsInput {
  * edit (or drops the claim) rather than hallucinating it into the report.
  *
  * Only UPDATE verdicts are gated: an UPDATE is a targeted in-place edit that
- * reliably implies a working-tree change. Exemptions:
+ * reliably implies a working-tree change — in `pomFile` when the verdict names one,
+ * otherwise in `testFilePath`. For a POM-based test those are different files: the spec
+ * is what runs, the page object is what gets patched, so checking only `testFilePath`
+ * would reject maintenance that did land (SKYR-4129). Exemptions:
  *  - REGENERATE verdicts — on an EXTERNAL (user-authored Playwright/Cypress/RTL)
  *    test these are report-only (Skyramp can't auto-regenerate them; the developer
  *    acts manually), so no working-tree change is expected; and even an internal

package/build/utils/reportVerification.js

@@ -50,7 +50,10 @@ export async function listChangedFiles(repoRoot) {
  * edit (or drops the claim) rather than hallucinating it into the report.
  *
  * Only UPDATE verdicts are gated: an UPDATE is a targeted in-place edit that
- * reliably implies a working-tree change. Exemptions:
+ * reliably implies a working-tree change — in `pomFile` when the verdict names one,
+ * otherwise in `testFilePath`. For a POM-based test those are different files: the spec
+ * is what runs, the page object is what gets patched, so checking only `testFilePath`
+ * would reject maintenance that did land (SKYR-4129). Exemptions:
  *  - REGENERATE verdicts — on an EXTERNAL (user-authored Playwright/Cypress/RTL)
  *    test these are report-only (Skyramp can't auto-regenerate them; the developer
  *    acts manually), so no working-tree change is expected; and even an internal
@@ -96,8 +99,11 @@ export function findUnbackedClaims(input) {
         // change, and internal ones may regenerate to identical content.
         if (v.action !== DriftAction.Update)
             continue;
-        if (!isBacked(v.testFilePath)) {
-            unbacked.push(`testMaintenance ${v.action} claims an edit to "${path.basename(v.testFilePath)}", but that file has no working-tree change`);
+        // The edit target, not the spec: for a POM-based test the page object is what
+        // gets patched while testFilePath stays the spec (SKYR-4129).
+        const editTarget = v.pomFile ?? v.testFilePath;
+        if (!isBacked(editTarget)) {
+            unbacked.push(`testMaintenance ${v.action} claims an edit to "${path.basename(editTarget)}", but that file has no working-tree change`);
         }
     }
     return unbacked;

package/build/utils/scenarioDrafting.js

@@ -905,7 +905,13 @@ export function draftResponseShapeScenarios(hopEndpoints, byFile, addedFieldsByF
                 : `reflects the change made in ${fileName}`;
             const nameSuffix = addedFields.length > 0 ? addedFields[0] : "response-change";
             scenarios.push({
-                scenarioName: `${slugify(resource)}-response-shape-${slugify(nameSuffix)}`,
+                // The endpoint path is part of the name because one file can reach
+                // several GETs and neither the resource token (from the file) nor the
+                // suffix (a field name, or the constant "response-change" when the hunk
+                // yields none) varies between them. Two same-named candidates are
+                // merged by name in registerTestPlanTool, so a collision here loses a
+                // scenario outright rather than showing up as a duplicate.
+                scenarioName: `${slugify(resource)}-response-shape-${slugify(nameSuffix)}-${slugify(ep.path)}`,
                 description: `Verify GET ${ep.path} response ${fieldsPhrase}.`,
                 category: "breaking_change",
                 priority: "high",

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`, `summaryOutputFile`, `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 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";

package/build/utils/skyrampMdContent.js

@@ -58,7 +58,7 @@ Prefer invoking a prompt over manually chaining tools — prompts run the full w
 
 - **\`skyramp_trace_prompt\`** — Trace collection setup and execution.
 - **\`skyramp_test_health_analysis\`** — Full maintenance flow (discover → drift → health → actions).
-- **\`skyramp_testbot\`** — PR-scoped recommendations + maintenance + report. Required: \`prTitle\`, \`prDescription\`, \`summaryOutputFile\`, \`repositoryPath\`.
+- **\`skyramp_testbot\`** — PR-scoped recommendations + maintenance + report. Required: \`prTitle\`, \`prDescription\`, \`repositoryPath\`.
 
 ---
 

package/build/utils/urlPath.d.ts

@@ -0,0 +1,37 @@
+/**
+ * URL/path derivations shared by the generation tools.
+ *
+ * Both helpers here existed as private copies before: `pathFromEndpointURL`
+ * lived in tools/generate-tests/planGuard.ts, and the base-path derivation was
+ * inlined in ScenarioGenerationService and then mirrored a second time by
+ * generateBatchScenarioRestTool so it could predict the path the service would
+ * emit (SKYR-4127). Two copies of "which path does this request actually have"
+ * is exactly the kind of thing that drifts silently — a pattern that stops
+ * matching produces a 403, not a test failure — so they live in one place now.
+ *
+ * Dependency-free on purpose: this sits below both services/ and tools/ so
+ * either layer can import it without an inversion.
+ */
+/**
+ * Extract the URL path from a generation tool's `endpointURL` param.
+ *
+ * Falls back to treating the value as a bare path when it isn't a parseable
+ * absolute URL, and to undefined when it's neither.
+ *
+ * `new URL()` percent-encodes `{param}` placeholders (`{id}` → `%7Bid%7D`),
+ * which breaks two consumers: plan matchKeys are computed from raw scenario
+ * paths with braces intact, and workspace queryParamOverrides patterns are
+ * authored with braces. Restore them.
+ */
+export declare function pathFromEndpointURL(endpointURL: string | undefined): string | undefined;
+/**
+ * The path prefix a service's `baseURL` contributes to every request under it:
+ * the URL's pathname with any trailing slash removed. Empty string when
+ * `baseURL` is absent or unparseable, and for a host-only URL (`http://host`
+ * → pathname `/` → `""`).
+ *
+ * This is the value ScenarioGenerationService prepends to each step path, so
+ * anything that needs to reason about the emitted path — such as matching
+ * workspace queryParamOverrides — must derive it the same way.
+ */
+export declare function deriveBasePath(baseURL: string | undefined): string;

package/build/utils/urlPath.js

@@ -0,0 +1,55 @@
+/**
+ * URL/path derivations shared by the generation tools.
+ *
+ * Both helpers here existed as private copies before: `pathFromEndpointURL`
+ * lived in tools/generate-tests/planGuard.ts, and the base-path derivation was
+ * inlined in ScenarioGenerationService and then mirrored a second time by
+ * generateBatchScenarioRestTool so it could predict the path the service would
+ * emit (SKYR-4127). Two copies of "which path does this request actually have"
+ * is exactly the kind of thing that drifts silently — a pattern that stops
+ * matching produces a 403, not a test failure — so they live in one place now.
+ *
+ * Dependency-free on purpose: this sits below both services/ and tools/ so
+ * either layer can import it without an inversion.
+ */
+/**
+ * Extract the URL path from a generation tool's `endpointURL` param.
+ *
+ * Falls back to treating the value as a bare path when it isn't a parseable
+ * absolute URL, and to undefined when it's neither.
+ *
+ * `new URL()` percent-encodes `{param}` placeholders (`{id}` → `%7Bid%7D`),
+ * which breaks two consumers: plan matchKeys are computed from raw scenario
+ * paths with braces intact, and workspace queryParamOverrides patterns are
+ * authored with braces. Restore them.
+ */
+export function pathFromEndpointURL(endpointURL) {
+    if (!endpointURL)
+        return undefined;
+    try {
+        return new URL(endpointURL).pathname.replace(/%7B/gi, "{").replace(/%7D/gi, "}");
+    }
+    catch {
+        return endpointURL.startsWith("/") ? endpointURL : undefined;
+    }
+}
+/**
+ * The path prefix a service's `baseURL` contributes to every request under it:
+ * the URL's pathname with any trailing slash removed. Empty string when
+ * `baseURL` is absent or unparseable, and for a host-only URL (`http://host`
+ * → pathname `/` → `""`).
+ *
+ * This is the value ScenarioGenerationService prepends to each step path, so
+ * anything that needs to reason about the emitted path — such as matching
+ * workspace queryParamOverrides — must derive it the same way.
+ */
+export function deriveBasePath(baseURL) {
+    if (!baseURL)
+        return "";
+    try {
+        return new URL(baseURL).pathname.replace(/\/$/, "");
+    }
+    catch {
+        return "";
+    }
+}

package/build/utils/utils.d.ts

@@ -1,6 +1,51 @@
 import { CallToolResult, ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
 export declare function readDiffFile(diffFilePath: string | undefined): string | undefined;
 export declare function toolError(message: string): CallToolResult;
+/**
+ * Build a successful tool result whose payload is delivered on BOTH MCP result
+ * channels — `structuredContent` and `content[]` — carrying the identical text.
+ * The counterpart to `toolError` for any tool that returns a large text payload.
+ *
+ * Use this for every non-error return of such a tool, and declare a matching
+ * `outputSchema`. Two separate failures make that necessary:
+ *
+ * 1. A result with no `structuredContent` is persisted by the agent harness as a
+ *    pretty-printed `.json` spill, which buries the payload inside an escaped
+ *    JSON string. Coming through `structuredContent` instead lands it as a
+ *    `.txt`. Measured on eval runs 32227152533 and 32283973875: the extension
+ *    follows the result shape, with no exceptions either way.
+ *
+ *    The extension is not cosmetic: it changes how the payload TOKENIZES. The
+ *    reader refuses any spill over 25,000 tokens, and pretty-printed JSON with
+ *    escaped quotes and newlines costs 2-3x the tokens of the same bytes in raw
+ *    form. Measured on one payload either way: 141.2KB of `.json` counted 72,318
+ *    tokens and was refused, while the same result at 142.0KB of `.txt` was read
+ *    back in full. A second: 54,085 tokens as `.json`, 26,950 as `.txt`.
+ *
+ *    So the shape raises the deliverable size ceiling by roughly 3x, but does not
+ *    remove it. That second payload still missed the cap by 1,950 tokens, and
+ *    `skyramp_actions` results of 178-621KB are 45,598-158,997 tokens even as
+ *    `.txt` — the agent then falls back to slicing the file with `head -c`. The
+ *    check covers the whole file, so a `limit:` on the read cannot evade it.
+ *    Payloads that big have to shrink (SKYR-4188 and its sibling); this shape is
+ *    what lets a shrunk payload actually arrive.
+ *
+ * 2. Each agent CLI testbot supports reads a different channel and none falls
+ *    back to the other: Claude Code takes `structuredContent` and drops
+ *    `content[]`; Cursor takes `content[]` and ignores `structuredContent`;
+ *    GitHub Copilot CLI surfaces both and de-duplicates them only when the text
+ *    is the literal JSON serialization of `structuredContent` (MCP spec 5.2.6),
+ *    otherwise it concatenates. Hence `JSON.stringify` rather than the raw text,
+ *    which would deliver the payload twice there. Trimming either channel
+ *    silently starves a client.
+ *
+ * Declaring the outputSchema also obliges every non-error return to come through
+ * here: the SDK rejects a successful result without `structuredContent`
+ * ("has an output schema but no structured content was provided"). Error results
+ * are exempt — that check returns early on `isError` — so they keep using
+ * `toolError`.
+ */
+export declare function dualChannelResult(structuredContent: Record<string, string>): CallToolResult;
 /**
  * Does `candidate` (an LLM- or caller-supplied name/path) identify `fullPath` (a known,
  * absolute test file path)? Exact match first, then a real path-segment boundary match

package/build/utils/utils.js

@@ -18,6 +18,56 @@ export function toolError(message) {
         isError: true,
     };
 }
+/**
+ * Build a successful tool result whose payload is delivered on BOTH MCP result
+ * channels — `structuredContent` and `content[]` — carrying the identical text.
+ * The counterpart to `toolError` for any tool that returns a large text payload.
+ *
+ * Use this for every non-error return of such a tool, and declare a matching
+ * `outputSchema`. Two separate failures make that necessary:
+ *
+ * 1. A result with no `structuredContent` is persisted by the agent harness as a
+ *    pretty-printed `.json` spill, which buries the payload inside an escaped
+ *    JSON string. Coming through `structuredContent` instead lands it as a
+ *    `.txt`. Measured on eval runs 32227152533 and 32283973875: the extension
+ *    follows the result shape, with no exceptions either way.
+ *
+ *    The extension is not cosmetic: it changes how the payload TOKENIZES. The
+ *    reader refuses any spill over 25,000 tokens, and pretty-printed JSON with
+ *    escaped quotes and newlines costs 2-3x the tokens of the same bytes in raw
+ *    form. Measured on one payload either way: 141.2KB of `.json` counted 72,318
+ *    tokens and was refused, while the same result at 142.0KB of `.txt` was read
+ *    back in full. A second: 54,085 tokens as `.json`, 26,950 as `.txt`.
+ *
+ *    So the shape raises the deliverable size ceiling by roughly 3x, but does not
+ *    remove it. That second payload still missed the cap by 1,950 tokens, and
+ *    `skyramp_actions` results of 178-621KB are 45,598-158,997 tokens even as
+ *    `.txt` — the agent then falls back to slicing the file with `head -c`. The
+ *    check covers the whole file, so a `limit:` on the read cannot evade it.
+ *    Payloads that big have to shrink (SKYR-4188 and its sibling); this shape is
+ *    what lets a shrunk payload actually arrive.
+ *
+ * 2. Each agent CLI testbot supports reads a different channel and none falls
+ *    back to the other: Claude Code takes `structuredContent` and drops
+ *    `content[]`; Cursor takes `content[]` and ignores `structuredContent`;
+ *    GitHub Copilot CLI surfaces both and de-duplicates them only when the text
+ *    is the literal JSON serialization of `structuredContent` (MCP spec 5.2.6),
+ *    otherwise it concatenates. Hence `JSON.stringify` rather than the raw text,
+ *    which would deliver the payload twice there. Trimming either channel
+ *    silently starves a client.
+ *
+ * Declaring the outputSchema also obliges every non-error return to come through
+ * here: the SDK rejects a successful result without `structuredContent`
+ * ("has an output schema but no structured content was provided"). Error results
+ * are exempt — that check returns early on `isError` — so they keep using
+ * `toolError`.
+ */
+export function dualChannelResult(structuredContent) {
+    return {
+        structuredContent,
+        content: [{ type: "text", text: JSON.stringify(structuredContent) }],
+    };
+}
 /**
  * Does `candidate` (an LLM- or caller-supplied name/path) identify `fullPath` (a known,
  * absolute test file path)? Exact match first, then a real path-segment boundary match

package/build/utils/versions.d.ts

@@ -1,4 +1,4 @@
-export declare const SKYRAMP_IMAGE_VERSION = "v1.3.37";
-export declare const EXECUTOR_DOCKER_IMAGE = "skyramp/executor:v1.3.37";
-export declare const WORKER_DOCKER_IMAGE = "skyramp/worker:v1.3.37";
+export declare const SKYRAMP_IMAGE_VERSION = "v1.3.40";
+export declare const EXECUTOR_DOCKER_IMAGE = "skyramp/executor:v1.3.40";
+export declare const WORKER_DOCKER_IMAGE = "skyramp/worker:v1.3.40";
 export declare const WORKER_CONTROL_PORT = 35142;

package/build/utils/versions.js

@@ -1,4 +1,4 @@
-export const SKYRAMP_IMAGE_VERSION = "v1.3.37";
+export const SKYRAMP_IMAGE_VERSION = "v1.3.40";
 export const EXECUTOR_DOCKER_IMAGE = `skyramp/executor:${SKYRAMP_IMAGE_VERSION}`;
 export const WORKER_DOCKER_IMAGE = `skyramp/worker:${SKYRAMP_IMAGE_VERSION}`;
 // Control port the Skyramp worker listens on (SDK `CONTAINER_PORT`).