@skyramp/mcp 0.0.61 → 0.0.63-rc.1

package/build/index.js

@@ -19,21 +19,17 @@ import { registerLoginTool } from "./tools/auth/loginTool.js";
 import { registerLogoutTool } from "./tools/auth/logoutTool.js";
 import { registerFixErrorTool } from "./tools/fixErrorTool.js";
 import { registerAnalyzeRepositoryTool } from "./tools/test-recommendation/analyzeRepositoryTool.js";
-import { registerMapTestsTool } from "./tools/test-recommendation/mapTestsTool.js";
 import { registerRecommendTestsTool } from "./tools/test-recommendation/recommendTestsTool.js";
+import { registerRecommendTestsPrompt } from "./prompts/test-recommendation/registerRecommendTestsPrompt.js";
 import { registerModularizationTool } from "./tools/code-refactor/modularizationTool.js";
 import { registerCodeReuseTool } from "./tools/code-refactor/codeReuseTool.js";
 import { registerScenarioTestTool } from "./tools/generate-tests/generateScenarioRestTool.js";
-import { registerDiscoverTestsTool } from "./tools/test-maintenance/discoverTestsTool.js";
-import { registerAnalyzeTestDriftTool } from "./tools/test-maintenance/analyzeTestDriftTool.js";
-import { registerExecuteBatchTestsTool } from "./tools/test-maintenance/executeBatchTestsTool.js";
-import { registerCalculateHealthScoresTool } from "./tools/test-maintenance/calculateHealthScoresTool.js";
-import { registerActionsTool } from "./tools/test-maintenance/actionsTool.js";
-import { registerStateCleanupTool } from "./tools/test-maintenance/stateCleanupTool.js";
+import { registerAnalyzeChangesTool, registerAnalyzeTestHealthTool, registerExecuteTestsTool, registerActionsTool, registerStateCleanupTool, } from "./tools/test-management/index.js";
 import { registerTestbotPrompt, registerTestbotResource, } from "./prompts/testbot/testbot-prompts.js";
 import { registerInitTestbotTool } from "./tools/initTestbotTool.js";
 import { registerSubmitReportTool } from "./tools/submitReportTool.js";
 import { registerInitializeWorkspaceTool } from "./tools/workspace/initializeWorkspaceTool.js";
+import { registerAnalysisResources } from "./resources/analysisResources.js";
 import { AnalyticsService } from "./services/AnalyticsService.js";
 import { initCheck } from "./utils/initAgent.js";
 const server = new McpServer({
@@ -47,13 +43,38 @@ const server = new McpServer({
         prompts: {
             listChanged: true,
         },
+        resources: {
+            listChanged: true,
+        },
     },
-    instructions: `Skyramp MCP Server — generates and executes API tests (smoke, fuzz, contract, load, integration, E2E, UI).
+    instructions: `Skyramp MCP Server — generates and executes API tests (fuzz, contract, integration, E2E, UI).
 
 ## Rules
 - NEVER show CLI commands. ALWAYS use the MCP tools provided.
 - For UI and E2E tests, use the trace collection start/stop tools.
 
+## Test Recommendation Flow (2-step)
+1. Call \`skyramp_analyze_repository\` → returns a \`sessionId\`.
+   The analysis scans source code (code-first) to build enriched endpoints
+   (Path → Method → Interaction with request/response bodies, headers, cookies)
+   and draft user-flow scenarios for integration/E2E tests.
+2. Call \`skyramp_recommend_tests\` with \`sessionId\` → the LLM reasons over the
+   enriched data to recommend tests, referencing specific interactions and scenarios.
+
+## Test Health Analysis Flow (4-step)
+1. Call \`skyramp_analyze_changes\` with \`repositoryPath\` and \`scope\` → discovers existing tests, scans endpoints, computes branch diff → returns a \`stateFile\`.
+2. Call \`skyramp_analyze_test_health\` with \`stateFile\` → runs drift analysis + health scoring + LLM semantic assessment → returns enriched \`stateFile\`.
+3. (Optional) Call \`skyramp_execute_tests\` with \`stateFile\` → runs tests live to verify status.
+4. Call \`skyramp_actions\` with \`stateFile\` → executes UPDATE/REGENERATE/ADD recommendations.
+
+After analysis, you can also inspect data via MCP Resources:
+- \`skyramp://analysis/{sessionId}/summary\` — high-level overview
+- \`skyramp://analysis/{sessionId}/endpoints\` — compact endpoint listing
+- \`skyramp://analysis/{sessionId}/endpoints/{path}\` — full path detail
+- \`skyramp://analysis/{sessionId}/endpoints/{path}/{method}\` — single method detail
+- \`skyramp://analysis/{sessionId}/scenarios\` — drafted scenarios
+- \`skyramp://analysis/{sessionId}/diff\` — branch diff context
+
 ## Workspace Initialization (before ANY other Skyramp tool)
 Follow this flow EVERY time before calling any Skyramp tool:
 
@@ -78,16 +99,23 @@ Before calling ANY test generation tool, you MUST follow this flow:
 2. **Extract** the \`language\`, \`framework\`, \`outputDir\`, and \`api.baseUrl\` from the services section.
 3. **Use those values** as defaults for the test generation tool call. Do NOT ask the user for these values if they are already configured in the workspace file.
 4. **CRITICAL — endpointURL**: The \`endpointURL\` parameter MUST be the full URL to the specific endpoint being tested, NOT just the base URL. Construct it by combining \`api.baseUrl\` with the endpoint path. Example: if \`api.baseUrl\` is \`http://localhost:8000\` and the endpoint is \`/api/v1/products\`, pass \`endpointURL: "http://localhost:8000/api/v1/products"\`. NEVER pass just the base URL (e.g. \`http://localhost:8000\`) as \`endpointURL\`.
-5. **If the workspace file does not exist**, or the needed values (language, framework, outputDir) are missing from the workspace config, ASK the user which language and framework they want before calling the tool.
-6. The user can always override workspace defaults by explicitly specifying values in their request.
+5. **CRITICAL — scenario generation**: When calling \`skyramp_scenario_test_generation\`, ALWAYS pass:
+   - \`baseURL\`: The full base URL from \`api.baseUrl\` (e.g., \`http://localhost:3000\`). This determines the scheme, host, and port in the generated trace. Without it, the trace defaults to https:443 which is almost always wrong for local development.
+   - \`authHeader\`: The auth header name from \`api.authHeader\` in the workspace config. Use \`Cookie\` for cookie/session-based auth (NextAuth, etc.), \`Authorization\` for Bearer tokens, \`X-API-Key\` for API keys. Without it, the trace defaults to \`Authorization: Bearer\` which breaks cookie-based apps.
+   - \`apiSchema\` is OPTIONAL — omit it for code-first apps without OpenAPI specs.
+6. **CRITICAL — integration test from scenario**: When calling \`skyramp_integration_test_generation\` with a \`scenarioFile\`, ALSO pass \`authHeader\` (same value as used in scenario generation). This tells the CLI which header to parameterize with the auth token. Without it, the generated test defaults to \`Authorization: Bearer\` regardless of what's in the trace.
+7. **If the workspace file does not exist**, or the needed values (language, framework, outputDir) are missing from the workspace config, ASK the user which language and framework they want before calling the tool.
+8. The user can always override workspace defaults by explicitly specifying values in their request.
 `,
 });
 // Check for first-time invocation after version update (runs in background, doesn't block)
 let initCheckInFlight = false;
 let initCheckDone = false;
+const INIT_MESSAGE = "Skyramp init: Triggering pull of Skyramp worker and executor images if not present locally.";
 const originalRegisterTool = server.registerTool.bind(server);
 server.registerTool = function (name, definition, handler) {
     const wrappedHandler = async (...args) => {
+        let triggeredInitThisCall = false;
         if (!initCheckDone && !initCheckInFlight) {
             // Guard with inFlight so concurrent tool calls don't each spawn a new initCheck(),
             // but allow retry on failure (initCheckInFlight is reset to false on error).
@@ -96,6 +124,7 @@ server.registerTool = function (name, definition, handler) {
             // unreachable.  Deferring via setImmediate ensures the tool response is written to
             // stdout (and acknowledged by the MCP client) before any blocking FFI call runs.
             initCheckInFlight = true;
+            triggeredInitThisCall = true;
             setImmediate(() => {
                 initCheck()
                     .then(() => {
@@ -109,7 +138,15 @@ server.registerTool = function (name, definition, handler) {
                 });
             });
         }
-        return handler(...args);
+        const result = await handler(...args);
+        if (triggeredInitThisCall && result) {
+            const content = result.content ?? [];
+            result.content = [
+                { type: "text", text: INIT_MESSAGE },
+                ...content,
+            ];
+        }
+        return result;
     };
     return originalRegisterTool(name, definition, wrappedHandler);
 };
@@ -119,6 +156,7 @@ const prompts = [
     registerTestGenerationPrompt,
     registerStartTraceCollectionPrompt,
     registerTestHealthPrompt,
+    registerRecommendTestsPrompt,
 ];
 if (process.env.SKYRAMP_FEATURE_TESTBOT === "1") {
     prompts.push(registerTestbotPrompt);
@@ -148,13 +186,13 @@ const codeQualityTools = [
 codeQualityTools.forEach((registerTool) => registerTool(server));
 // Register test recommendation tools
 registerAnalyzeRepositoryTool(server);
-registerMapTestsTool(server);
 registerRecommendTestsTool(server);
-// Register test maintenance tools
-registerDiscoverTestsTool(server);
-registerAnalyzeTestDriftTool(server);
-registerExecuteBatchTestsTool(server);
-registerCalculateHealthScoresTool(server);
+// Register analysis resources (MCP Resources for enriched data access)
+registerAnalysisResources(server);
+// Register unified test-management tools (replaces separate test-maintenance tools)
+registerAnalyzeChangesTool(server);
+registerAnalyzeTestHealthTool(server);
+registerExecuteTestsTool(server);
 registerActionsTool(server);
 registerStateCleanupTool(server);
 // Register workspace management tools

package/build/prompts/test-maintenance/drift-analysis-prompt.js

@@ -0,0 +1,59 @@
+import { buildDriftScoringGuide, buildActionDecisionMatrix, buildBreakingChangePatterns, buildTestAssessmentGuidelines, buildAddRecommendationGuidelines, buildDriftOutputChecklist, } from "./driftAnalysisSections.js";
+export function buildDriftAnalysisPrompt(params) {
+    const { existingTests, parsedDiff, scannedEndpoints, repositoryPath, stateFile } = params;
+    // Detect new endpoints count from parsedDiff
+    let newEndpointCount = 0;
+    let diffSection = "";
+    if (parsedDiff) {
+        const lines = parsedDiff.split("\n");
+        const epMatches = parsedDiff.match(/(?:^|\n)\*\*(GET|POST|PUT|PATCH|DELETE)\s+[^\*]+\*\*/gm);
+        if (epMatches)
+            newEndpointCount = epMatches.length;
+        diffSection = `## Branch Diff
+\`\`\`
+${lines.slice(0, 200).join("\n")}
+\`\`\`
+`;
+    }
+    const testListSection = existingTests.length > 0
+        ? `## Existing Test Files (${existingTests.length})
+${existingTests
+            .map((t) => {
+            const score = t.drift?.driftScore !== undefined ? ` [drift: ${t.drift.driftScore}]` : "";
+            return `- ${t.testFile} (${t.testType})${score}`;
+        })
+            .join("\n")}
+`
+        : `## Existing Test Files
+No existing Skyramp tests found in repository.
+`;
+    const scannedSection = scannedEndpoints.length > 0
+        ? `## Scanned Endpoints (${scannedEndpoints.length})
+${scannedEndpoints.map((ep) => `- ${Array.isArray(ep.methods) ? ep.methods.join("|") : ep.method} ${ep.path}`).join("\n")}
+`
+        : "";
+    return `# Test Health Analysis
+
+**Repository**: \`${repositoryPath}\`
+**Existing tests**: ${existingTests.length}
+**New endpoints in diff**: ${newEndpointCount}
+
+${diffSection}
+${testListSection}
+${scannedSection}
+${buildDriftScoringGuide()}
+
+${buildActionDecisionMatrix()}
+
+${buildBreakingChangePatterns()}
+
+${buildTestAssessmentGuidelines()}
+
+${buildAddRecommendationGuidelines()}
+
+${buildDriftOutputChecklist(existingTests.length, newEndpointCount)}
+
+After completing the assessment above, call \`skyramp_actions\` with \`stateFile: "${stateFile}"\`
+
+**CRITICAL**: Do NOT create any .json or .md files. Only call skyramp_actions when done.`;
+}

package/build/prompts/test-maintenance/driftAnalysisSections.js

@@ -0,0 +1,153 @@
+/**
+ * Modular section builders for the Drift Analysis prompt,
+ * mirroring the recommendationSections.ts pattern.
+ */
+export function buildDriftScoringGuide() {
+    return `## Drift Score Guide (0–100)
+
+| Score | Label | Meaning |
+|-------|-------|---------|
+| 0–20  | IGNORE | No meaningful drift — test is still valid as-is |
+| 21–40 | VERIFY | Minor changes detected — review but likely fine |
+| 41–70 | UPDATE | Breaking changes detected — test needs edits |
+| 71–100 | REGENERATE | Major structural changes — regenerate from scratch |
+
+Assign each existing test a score based on how much the codebase has changed relative to what the test expects.`;
+}
+export function buildActionDecisionMatrix() {
+    return `## Action Decision Matrix
+
+For each test, choose one of:
+
+| Action | When to use |
+|--------|------------|
+| **IGNORE** | Drift score 0–20; no breaking changes AND no additive field gaps detected |
+| **VERIFY** | Drift score 21–40; minor changes, manual review recommended |
+| **UPDATE** | Drift score 25–70; breaking changes OR additive fields added to a covered endpoint (new response field the test doesn't assert) |
+| **REGENERATE** | Drift score 71–100; endpoint removed, major restructuring, or test is fundamentally broken |
+| **ADD** | New endpoint detected in diff that has no corresponding test yet |
+
+Rules:
+- Prefer UPDATE over REGENERATE when changes are localized (e.g., only the URL path changed).
+- Prefer IGNORE over VERIFY when all changed files are unrelated to the test's endpoint.
+- Always use ADD for new endpoints when the action is scoped to new test creation.
+- **Additive changes (new response fields) on a covered endpoint always trigger UPDATE** — even if existing assertions still pass. The test needs a new assertion for the added field.`;
+}
+export function buildBreakingChangePatterns() {
+    return `## Breaking Change Patterns to Detect
+
+Scan the diff lines for these high-signal patterns:
+
+### Endpoint-level breaking changes
+- \`-  @app.route("/old-path")\` / \`+  @app.route("/new-path")\` — renamed endpoint
+- \`-  router.get("/old")\` / \`+  router.get("/new")\` — renamed route
+- \`-  @GetMapping("/old")\` / \`+  @GetMapping("/new")\` — Spring rename
+- Lines removing a route decorator entirely (endpoint removed)
+
+### Request/response shape changes
+- Field type changes: \`- field: int\` → \`+ field: string\`
+- Required field added: \`+ required: [..., "newField"]\`
+- Response field removed: \`- "responseField":\`
+- Enum value changes: \`- status: "active"\` → \`+ status: "enabled"\`
+
+### Auth changes
+- \`+ @require_auth\`, \`+ @login_required\`, \`+ middleware(authMiddleware)\`
+- \`- @require_auth\` (auth removed)
+- Token type changed: Bearer → Cookie
+
+### Status code changes
+- \`- return 200\` → \`+ return 201\`
+- \`- status_code=200\` → \`+ status_code=204\`
+- \`- res.status(201)\` → \`+ res.status(200)\`
+
+### Additive response field changes (non-breaking but coverage gap)
+These do NOT break existing assertions but leave the new field untested. Always flag as UPDATE for covered endpoints.
+- \`+ "newField": queryset.filter(...).count()\` added inside a \`Response({...})\` or \`res.json({...})\`
+- \`+ newField = serializers.XXXField()\` added to a serializer used by a tested endpoint
+- \`+ "newField":\` added to a response body dict returned by the endpoint
+- New key added inside an existing dict/object returned by the endpoint`;
+}
+export function buildTestAssessmentGuidelines() {
+    return `## Per-Test Assessment (4 Steps)
+
+For each existing test file, follow these steps:
+
+### Step 1: Check endpoint existence
+Does the endpoint the test targets still exist in the codebase?
+- If the endpoint path/method is no longer present → score 80+, action: REGENERATE
+- If the endpoint was renamed → score 50–70, action: UPDATE (path substitution)
+
+### Step 2: Check request/response shape (breaking changes)
+Has the request body or response structure changed in a way that breaks the test?
+- Compare test's expected fields against current schema/model definitions
+- Type changes (string→int, int→string) → score 60+, action: UPDATE or REGENERATE
+- New required fields the test doesn't send → score 50+, action: UPDATE
+- Response fields the test asserts on have been removed → score 50+, action: UPDATE
+
+### Step 2b: Check additive response field changes (coverage gaps)
+**Even if existing assertions still pass**, does the diff add a new field to the response of an endpoint this test already covers?
+- Look at the diff for lines like \`+ "newField":\` or \`+ newField =\` inside a view/serializer this test hits
+- If YES → score 30, action: UPDATE — add an assertion for the new field (e.g. \`assert "newField" in response_body\` or \`assert response_body["newField"] >= 0\`)
+- This applies even when the test only checks status codes — the test should be extended to cover the new field
+- **Do NOT score IGNORE if a new response field was added to a covered endpoint**
+
+### Step 3: Check auth changes
+Has the authentication mechanism for this endpoint changed?
+- Auth added where none existed → score 40+, action: UPDATE
+- Auth method changed (bearer→cookie) → score 50+, action: UPDATE
+- Auth removed → score 30+, action: VERIFY or UPDATE
+
+### Step 4: Assign score and action
+Based on the above, assign a final drift score 0–100 and choose the action (IGNORE / VERIFY / UPDATE / REGENERATE).
+Provide a 1-2 sentence rationale.
+- If Step 2b flagged an additive field → score must be ≥ 30 and action must be UPDATE, even if Steps 2/3 found no breaking changes.`;
+}
+export function buildAddRecommendationGuidelines() {
+    return `## ADD Recommendations for New Endpoints
+
+For each new endpoint detected in the diff (not yet covered by any existing test):
+
+### Test type priority by HTTP method
+| Method | Recommended test types |
+|--------|----------------------|
+| POST / PUT / PATCH | integration, contract |
+| GET | contract, smoke |
+| DELETE | integration, smoke |
+
+### ADD recommendation format
+For each new endpoint, include:
+1. The endpoint path and method
+2. The recommended test types (from the table above)
+3. The Skyramp tool to call (e.g., \`skyramp_contract_test_generation\`, \`skyramp_integration_test_generation\`)
+4. The \`endpointURL\` to use (combine base URL + path)
+5. The language/framework to use (from workspace config or project metadata)`;
+}
+export function buildDriftOutputChecklist(existingTestCount, newEndpointCount) {
+    return `## Output Checklist
+
+Complete ALL of the following before calling skyramp_actions:
+
+### Existing tests (${existingTestCount} total)
+For EACH existing test, output:
+\`\`\`
+Test: <testFile>
+Drift Score: <0-100>
+Action: <IGNORE | VERIFY | UPDATE | REGENERATE>
+Rationale: <1-2 sentence explanation>
+\`\`\`
+
+${newEndpointCount > 0
+        ? `### New endpoints (${newEndpointCount} detected)
+For EACH new endpoint, output:
+\`\`\`
+Endpoint: <METHOD> <path>
+Action: ADD
+Test types: <contract | integration | smoke | ...>
+Rationale: <1 sentence>
+\`\`\``
+        : `### New endpoints
+No new endpoints detected in this diff.`}
+
+### Final step
+After completing all assessments above, call \`skyramp_actions\` with the stateFile to execute the recommended changes.`;
+}

package/build/prompts/test-recommendation/analysisOutputPrompt.js

@@ -0,0 +1,113 @@
+function buildEnrichmentInstructions(p) {
+    const isDiffScope = p.analysisScope === "current_branch_diff";
+    const useHealthFlow = p.nextTool === "skyramp_analyze_test_health";
+    if (!isDiffScope) {
+        const nextStep = useHealthFlow
+            ? `### Step 3: Identify tests at risk of drift
+Call \`skyramp_analyze_test_health\` with \`stateFile: "${p.sessionId}"\``
+            : `### Step 3: Call recommend tests
+Call \`skyramp_recommend_tests\` with \`sessionId: "${p.sessionId}"\``;
+        return `## Your Task — Enrich & Recommend (full repo)
+
+### Step 1: Read key files
+Read \`package.json\` / \`requirements.txt\`, \`docker-compose.yml\`, route/controller files,
+and model/schema files (Zod schemas, Pydantic models, TypeScript interfaces, DTOs)
+to understand the tech stack, endpoint shapes, auth mechanisms, and request/response schemas.
+
+### Step 2: Identify resource relationships
+Map how endpoints relate to each other — which POST creates resources consumed by other endpoints?
+**Resolve nested/sub-router paths** from the Router Mounting section above.
+
+${nextStep}`;
+    }
+    const changedFiles = p.parsedDiff?.changedFiles.join(", ") ?? "";
+    const hasApiEndpoints = p.parsedDiff && (p.parsedDiff.newEndpoints.length > 0 || p.parsedDiff.modifiedEndpoints.length > 0);
+    const isUIOnly = !hasApiEndpoints && (p.parsedDiff?.changedFiles.every(f => !f.match(/\/(api|routes?|controllers?|routers?|handlers?|endpoints?)\//)) ?? false);
+    const step2 = hasApiEndpoints
+        ? `### Step 2: Discover related endpoints
+Read handler code for the changed endpoints and their model/schema files (Zod schemas,
+Pydantic models, DTOs) to understand request/response shapes. Find related endpoints via
+imports, shared models, adjacent route files. Resolve nested/sub-router paths from Router
+Mounting context.`
+        : isUIOnly
+            ? `### Step 2: Identify consumed API endpoints
+UI-only PR — read changed components to find API calls (fetch, axios, hooks).`
+            : `### Step 2: Identify affected endpoints
+No API route changes detected — read changed files to identify affected endpoints.`;
+    const step3Content = useHealthFlow
+        ? `### Step 3: Identify tests at risk of drift
+Assess which existing tests may be broken by the changes in this diff.
+
+### Step 4: Call analyze test health
+Call \`skyramp_analyze_test_health\` with \`stateFile: "${p.sessionId}"\``
+        : `### Step 3: Draft integration scenarios
+Draft multi-step scenarios simulating realistic user workflows:
+- **Cross-resource data flow**: Foreign key relationships, parent→child creation, verification
+- **Search/filter verification**: Create data, search, verify results
+- **Negative/error paths**: Invalid references → appropriate errors
+- **UI user journeys**: Concrete browser steps for frontend changes
+
+**Quality:** Realistic request bodies, response data verification, actual field names for chaining.
+
+### Step 4: Call recommend tests
+Call \`skyramp_recommend_tests\` with \`sessionId: "${p.sessionId}"\``;
+    return `## Your Task — Enrich & Recommend (PR-scoped)
+
+### Step 1: Read the changed files
+${changedFiles}
+
+${step2}
+
+${step3Content}`;
+}
+export function buildAnalysisOutputText(p) {
+    const isDiffScope = p.analysisScope === "current_branch_diff";
+    const diffSection = p.parsedDiff
+        ? `
+## Branch Diff Context
+**Branch**: \`${p.parsedDiff.currentBranch}\` → base: \`${p.parsedDiff.baseBranch}\`
+**Changed Files** (${p.parsedDiff.changedFiles.length}): ${p.parsedDiff.changedFiles.join(", ")}
+**New Endpoints** (${p.parsedDiff.newEndpoints.length}): ${p.parsedDiff.newEndpoints.map((e) => `${e.method} ${e.path} (${e.sourceFile})`).join(", ") || "none"}
+**Modified Endpoints** (${p.parsedDiff.modifiedEndpoints.length}): ${p.parsedDiff.modifiedEndpoints.map((e) => `${e.method} ${e.path} (${e.sourceFile})`).join(", ") || "none"}
+**Affected Services**: ${p.parsedDiff.affectedServices.join(", ") || "none"}
+`
+        : "";
+    const endpointCatalog = p.scannedEndpoints.length > 0
+        ? `
+## Pre-Scanned Endpoint Catalog (${p.scannedEndpoints.length} routes)
+${p.scannedEndpoints.map((ep) => `  ${ep.methods.join("|")} ${ep.path} (${ep.sourceFile})`).join("\n")}
+`
+        : "";
+    const wsLine = p.wsBaseUrl
+        ? `**Base URL**: \`${p.wsBaseUrl}\` | **Auth header**: \`${p.wsAuthHeader || "Authorization"}\``
+        : "";
+    const specSection = p.wsSchemaPath
+        ? `
+## OpenAPI Spec Available
+Spec at \`${p.wsSchemaPath}\`. **Read it** for authoritative paths and schemas.
+Pass \`apiSchema: "${p.wsSchemaPath}"\` to ALL test generation tool calls.`
+        : p.routerMountContext
+            ? `
+## Router Mounting / Nesting
+\`\`\`
+${p.routerMountContext}
+\`\`\`
+Use this to resolve full URL paths for nested endpoints.`
+            : "";
+    const enrichment = buildEnrichmentInstructions(p);
+    return `# Repository Analysis
+
+**Session ID**: \`${p.sessionId}\`
+**Repository**: \`${p.repositoryPath}\`
+**Analysis Scope**: \`${p.analysisScope}\`
+${isDiffScope ? `**Diff endpoints**: ${(p.parsedDiff?.newEndpoints.length ?? 0) + (p.parsedDiff?.modifiedEndpoints.length ?? 0)}` : `**Pre-scanned endpoints**: ${p.scannedEndpoints.length}`}
+${wsLine}
+${p.wsSchemaPath ? `**OpenAPI Spec**: \`${p.wsSchemaPath}\` (spec-based flow)` : "**Flow**: Code-scanning (may miss nesting)"}
+
+${diffSection}
+${endpointCatalog}
+${specSection}
+${enrichment}
+
+**CRITICAL**: No .json/.md file creation. Prioritize cross-resource workflows.`;
+}

package/build/prompts/test-recommendation/recommendationSections.js

@@ -0,0 +1,193 @@
+export const MAX_TESTS_TO_GENERATE = 4;
+export const MAX_RECOMMENDATIONS = 10;
+export function buildPrioritizationDimensions() {
+    return `## Prioritization Dimensions (evaluate each candidate test)
+
+For each candidate test, assess these dimensions using your judgment:
+
+| Dimension | What to assess |
+|-----------|---------------|
+| **Sophistication** | Does it test a multi-step workflow or non-obvious scenario? Or is it a simple request→response check? |
+| **Bug-Finding Potential** | Does it target known failure modes (race conditions, data consistency, state transitions, cascade effects)? |
+| **User Journey Relevance** | Does it reflect how real users interact with the system (from traces, business flows, or critical paths)? |
+| **Coverage Gap** | Does it address an area with zero existing test coverage? Or does it duplicate what\'s already tested? |
+| **Code Insight** | Is it derived from actual implementation analysis (e.g., spotted a middleware pattern, found an N+1 risk) rather than just API shape? |
+
+Candidates scoring well across MULTIPLE dimensions should be recommended first.
+Candidates satisfying only ONE dimension (e.g., covers a gap but is trivially simple) should be deprioritized.
+
+**Quality Gate:** For each candidate, ask: "Would a senior engineer be impressed by this test?"
+If the answer is no — deprioritize it. Impressive tests catch real bugs, exercise real workflows,
+and demonstrate understanding of the system\'s behavior. Trivial tests do not.`;
+}
+export function buildTestExamples() {
+    return `## Test Examples (calibrate your judgment)
+
+**Impressive tests (recommend these):**
+1. "Register user → login → create order → verify order appears in user\'s order list"
+   Cross-resource workflow with auth chaining and data verification across users + orders.
+2. "Create product with inventory=10 → place order for qty=10 → verify inventory=0 →
+   place another order → verify 409 out-of-stock error"
+   Cross-resource state machine + business rule validation (products + orders + inventory).
+3. "POST /users with duplicate email → verify 409 Conflict → verify original user unchanged"
+   Error handling with side-effect verification — not just status code check.
+
+**Non-impressive tests (deprioritize or skip):**
+1. "GET /products → 200" — trivial health check, no assertions beyond status code.
+2. "POST /products → GET /products/{id} → PUT /products/{id} → DELETE /products/{id}"
+   Single-resource CRUD — baseline, not impressive by itself.
+3. "POST /products with missing name → 422" — obvious validation, already covered by contract/fuzz.`;
+}
+export function buildTestPatternGuidelines() {
+    return `## Test Pattern Guidelines (reference, not rigid rules)
+
+### Tier 1 — Base Patterns
+- CRUD lifecycle per resource group (Create → Read → Update → Delete)
+- Auth flow (Register → Login → Access protected → Token refresh → Logout)
+- Pagination & filtering (boundary values, empty results, large page sizes)
+- Error responses (400, 401, 403, 404, 409, 422 — each with specific trigger)
+
+### Tier 2 — Code-Informed Patterns (higher value — look for these in the codebase)
+- **Middleware chains**: If auth/rate-limit/logging middleware exists, test the chain
+  (e.g., rate limit hit → auth still checked → correct error returned)
+- **N+1 query risk**: If list endpoints join related data (e.g., orders with products),
+  test with large datasets under load
+- **State machines**: If resources have status transitions (draft→published→archived),
+  test invalid transitions (e.g., archived→draft should fail)
+- **Cascade deletes**: If deleting a parent removes children, verify cascade AND verify
+  orphan prevention (delete product → orders referencing it get error or cascade)
+- **Race conditions**: If concurrent writes are possible (inventory deduction, counter
+  increment), test concurrent requests under load
+- **Computed fields**: If response contains derived values (total, average, count),
+  verify computation with known inputs
+- **Webhook/event side effects**: If endpoints trigger async operations, test that side
+  effects occur (e.g., POST /orders triggers email notification)`;
+}
+export function buildTestQualityCriteria() {
+    return `## What Makes a Good Test
+
+**Integration tests** should demonstrate cross-resource data flow — step A creates data
+that step B depends on (e.g., create product \u2192 create order referencing that product's ID \u2192
+verify order contains correct product). Single-resource CRUD alone is not an integration test.
+Use realistic request bodies from source code schemas and verify response data, not just
+status codes.
+
+**E2E tests** should follow realistic user journeys end-to-end: browse products \u2192 search \u2192
+add to cart \u2192 checkout. Verify that frontend actions trigger the correct API calls and
+that the UI reflects backend state.
+
+**UI tests** should exercise component behavior and interaction flows: fill form \u2192 validate
+inputs \u2192 submit \u2192 see confirmation. Include visual state changes (loading, error, empty)
+and accessibility checks.`;
+}
+export function buildGenerationRules(isUIOnlyPR) {
+    return `## Generation Guidelines
+
+**Scenario fidelity:** Every workflow scenario should reflect the actual resource
+relationships in the code. If the pre-drafted scenarios don't match the real data model,
+replace them with accurate ones.
+
+**Available test types:**
+- **Integration** — multi-endpoint workflows that chain data across resources
+- **Fuzz** — boundary/invalid input testing for POST/PUT endpoints
+- **Contract** — response schema validation for new/changed endpoints
+- **E2E** — user journeys spanning frontend to backend (needs Playwright traces)
+- **UI** — frontend component interaction flows (needs Playwright traces)
+${isUIOnlyPR ? `
+This is a **UI-only PR** — no backend changes. UI and E2E tests are most relevant.
+Without Playwright traces, recommend them with trace recording instructions
+(\`skyramp_start_trace_collection\` with \`playwright: true\`).
+` : `
+When no Playwright trace exists, still recommend E2E/UI tests with instructions for
+recording a trace using \`skyramp_start_trace_collection\` with \`playwright: true\`.
+`}
+**No duplicate coverage.** If an existing test already covers an endpoint + test type,
+recommend a different test that adds new coverage.
+
+Choose the test types and distribution that maximize coverage for this specific PR.
+No smoke tests.`;
+}
+export function buildToolWorkflows(authHeaderValue) {
+    return `## How to Generate Tests — Tool Workflows
+
+**Auth Header:** \`authHeader: "${authHeaderValue}"\` — pass to EVERY tool call below.
+
+**For multi-endpoint workflows (integration tests) — Scenario → Integration pipeline:**
+1. Call \`skyramp_scenario_test_generation\` once per step: \`scenarioName\`, \`destination\`,
+   \`baseURL\`, \`method\`, \`path\`, \`requestBody\`, \`responseBody\`, \`authHeader: "${authHeaderValue}"\`.
+   \`statusCode\` is optional — defaults: POST→201, DELETE→204, GET/PUT/PATCH→200. Only override for non-standard codes.
+   **OpenAPI spec is NOT required.** \`apiSchema\` is OPTIONAL — omit it if no spec exists.
+   \`requestBody\` should use realistic field values from source code schemas (Zod, Pydantic, DTOs).
+   \`responseBody\` should match the actual API response shape from source code (including all fields
+   returned by the controller — e.g., \`id\`, \`ownerId\`, \`createdAt\`, included relations like \`collection\`, \`tags\`).
+   Wrap in \`{"response": ...}\` if the API uses an envelope pattern. If omitted, a synthetic response is generated.
+   Inspect the source code to determine the correct request AND response body shapes — avoid sending \`{}\`.
+   Use unique names with timestamp suffix to avoid conflicts on re-runs.
+   For GET/PUT/DELETE with path IDs, use a placeholder — chaining resolves the real ID.
+2. Produces a \`scenario_<name>.json\` in the same \`outputDir\` as the test files (not \`.skyramp/\`).
+3. Call \`skyramp_integration_test_generation\` with \`scenarioFile\` AND \`authHeader: "${authHeaderValue}"\`.
+   Do NOT pass \`chainingKey\` — defaults to \`response.id\`. After generation, the testbot
+   will verify and fix path param chaining in the generated test.
+
+**For single-endpoint tests (contract/fuzz):**
+\`skyramp_{type}_test_generation\` with \`endpointURL\` (full URL incl. base + path), \`method\`,
+\`authHeader: "${authHeaderValue}"\`, and \`requestData\` from source code schemas.
+If an OpenAPI spec exists, ALSO pass \`apiSchema\` — it enables schema-aware validation
+(contract tests verify response structure, fuzz tests generate smarter boundary values).
+Without a spec, \`endpointURL\` alone is sufficient.
+
+**For UI tests (no Playwright recording):**
+1. \`skyramp_start_trace_collection\` (playwright: true)
+2. Perform browser steps
+3. \`skyramp_stop_trace_collection\`
+4. \`skyramp_ui_test_generation\` with playwright zip
+
+**For E2E tests:**
+Same trace flow, pass both trace file and playwright zip to \`skyramp_e2e_test_generation\`.`;
+}
+export function buildCoverageChecklist(openApiSpec, isUIOnlyPR, topN, maxGenerate = MAX_TESTS_TO_GENERATE) {
+    const specNote = openApiSpec
+        ? `\n**OpenAPI Spec available**: \`${openApiSpec.path}\`
+Use it actively:
+- **Contract tests**: pass \`apiSchema: "${openApiSpec.path}"\` — the CLI validates response schemas against the spec.
+- **Fuzz tests**: pass \`apiSchema: "${openApiSpec.path}"\` — the CLI generates boundary values from schema constraints.
+- **Integration tests**: pass \`apiSchema\` to \`skyramp_scenario_test_generation\` — it extracts destination and request/response shapes.
+- **Single-endpoint tests**: pass both \`endpointURL\` AND \`apiSchema\` for schema-aware generation.
+\n`
+        : "";
+    return `## Coverage Checklist
+${specNote}
+${isUIOnlyPR ? `**UI-only PR** — no backend changes.
+Without Playwright traces, the testbot skips generation entirely — all recommendations
+become additionalRecommendations in the report.
+` : `**Available test types:** integration, fuzz, contract, E2E, UI. No smoke tests.
+Choose based on what adds the most value for this PR's changes.
+`}
+## For Each Recommendation Include:
+1. Test type  2. Priority (high/medium/low)  3. Target endpoint/scenario
+4. What it validates (business logic, not just "tests the endpoint")
+5. Skyramp tool call details — exact tool + key params for zero-editing execution
+6. For integration/E2E: reference draftedScenario by scenarioName
+
+## When Artifacts Are Missing
+Recommend the test anyway — never mark it "blocked":
+- **No OpenAPI spec** \u2192 use \`endpointURL\` and \`requestBody\` from source code
+- **No Playwright recording** \u2192 provide trace recording instructions
+- **No backend trace** \u2192 use the scenario generation pipeline
+
+## Select the Top ${topN}
+Consider all possible tests (endpoints \u00d7 interaction types + scenarios), then select the
+top ${topN} most valuable. Include \`totalConsidered\` count in your output. The top ${Math.min(maxGenerate, topN)} will
+be generated; ${topN > maxGenerate ? `recommendations #${Math.min(maxGenerate, topN) + 1}\u2013${topN} go to additionalRecommendations in the report,
+so ensure the top ${Math.min(maxGenerate, topN)} are the highest-impact tests.` : `all will be generated.`}
+
+- Each integration scenario's step sequence should be logically valid — preconditions
+  met by prior steps.
+
+Each recommendation should include enough detail for direct tool invocation.
+Reference draftedScenarios by name and interactions by description.
+Use "high"/"medium"/"low" for priority — no numeric scores.
+Total candidates should be \u2265 ${topN}.
+
+Generate recommendations now.`;
+}