@skyramp/mcp 0.3.0 → 0.3.1-ldw-beta

package/build/prompts/local-dev/local-dev-prompts.js

@@ -0,0 +1,190 @@
+import { z } from "zod";
+import * as path from "path";
+import { logger } from "../../utils/logger.js";
+import { AnalyticsService } from "../../services/AnalyticsService.js";
+import { buildServiceContext, escapeXml, readWorkspaceServices, } from "../prompt-utils.js";
+import { localDevPlan, GRPC_SERVICE_NAME_GUIDANCE, ASSERTION_API_GUIDANCE } from "./local-dev-plan.js";
+const LOCAL_DEV_MAX_RECOMMENDATIONS = 8;
+const LOCAL_DEV_MAX_TESTS_TO_GENERATE = 5;
+/**
+ * Build an XML block that tells the agent which downstream services to mock
+ * vs. which are real (already running in the local environment).
+ */
+function buildServiceRoutingBlock(servicesToMock, realServices, mockProtocols) {
+    if (!servicesToMock?.length &&
+        !realServices?.length &&
+        !mockProtocols?.length)
+        return "";
+    const lines = ["<SERVICE_ROUTING>"];
+    if (servicesToMock?.length) {
+        // "all" is a sentinel meaning "mock every discovered downstream dependency".
+        // Emit it as a dedicated flag so the agent doesn't treat it as a literal service name.
+        const mockAll = servicesToMock.includes("all");
+        const namedServices = servicesToMock.filter((s) => s !== "all");
+        if (mockAll) {
+            lines.push(`  <MOCK_ALL_DOWNSTREAM>true</MOCK_ALL_DOWNSTREAM>`);
+        }
+        if (namedServices.length > 0) {
+            lines.push(`  <MOCK_SERVICES>${namedServices.map(escapeXml).join(", ")}</MOCK_SERVICES>`);
+        }
+    }
+    if (realServices?.length) {
+        lines.push(`  <REAL_SERVICES>${realServices.map(escapeXml).join(", ")}</REAL_SERVICES>`);
+    }
+    if (mockProtocols?.length) {
+        lines.push(`  <MOCK_PROTOCOLS>${mockProtocols.map(escapeXml).join(", ")}</MOCK_PROTOCOLS>`);
+    }
+    lines.push("</SERVICE_ROUTING>");
+    return lines.join("\n");
+}
+export function getLocalDevPrompt(baseCommit, repositoryPath, sandboxWorkerUrl, maxRecommendations = LOCAL_DEV_MAX_RECOMMENDATIONS, maxGenerate = LOCAL_DEV_MAX_TESTS_TO_GENERATE, services, stateOutputFile, servicesToMock, realServices, mockProtocols, proxyKubeconfig, proxyNamespace) {
+    maxGenerate = Math.min(Math.max(maxGenerate, 0), maxRecommendations);
+    const serviceContext = services?.length ? buildServiceContext(services) : "";
+    // Proxy access lets the workflow query a running Skyramp worker proxy for real
+    // recorded traffic (via skyramp_query_proxy_mocks) instead of inferring mock
+    // shapes from code/OpenAPI. sandboxWorkerUrl is the direct-URL (or ingress) mode;
+    // kubeconfig+namespace is the port-forward mode.
+    const proxyAccessLines = [];
+    if (sandboxWorkerUrl)
+        proxyAccessLines.push(`  <PROXY_URL>${escapeXml(sandboxWorkerUrl)}</PROXY_URL>`);
+    if (proxyKubeconfig)
+        proxyAccessLines.push(`  <PROXY_KUBECONFIG>${escapeXml(proxyKubeconfig)}</PROXY_KUBECONFIG>`);
+    if (proxyNamespace)
+        proxyAccessLines.push(`  <PROXY_NAMESPACE>${escapeXml(proxyNamespace)}</PROXY_NAMESPACE>`);
+    const hasProxyAccess = proxyAccessLines.length > 0;
+    const sandboxWorkerBlock = hasProxyAccess
+        ? `<PROXY_ACCESS>\n${proxyAccessLines.join("\n")}\n</PROXY_ACCESS>`
+        : "";
+    const serviceRoutingBlock = buildServiceRoutingBlock(servicesToMock, realServices, mockProtocols);
+    const schemaSourceGuidance = sandboxWorkerUrl
+        ? `Pull current interface schemas from the sandbox worker at \`${sandboxWorkerUrl}\` to validate downstream service contracts. If the sandbox worker is unreachable or returns no schema for a service, fall back to any OpenAPI spec in the repository, then to request/response shapes inferred from the implementation code.`
+        : `Use any OpenAPI spec found in the repository as the authoritative schema source for downstream services. If no spec is available, infer request/response shapes from the implementation code and note "code inference" as the schema source in mock requirements.`;
+    // ── Header block: context variables + critical workflow rules ──────────────
+    const header = `<REPOSITORY_PATH>${repositoryPath}</REPOSITORY_PATH>
+<BASE_COMMIT>${baseCommit}</BASE_COMMIT>
+${sandboxWorkerBlock ? sandboxWorkerBlock + "\n" : ""}${serviceContext ? serviceContext + "\n" : ""}${serviceRoutingBlock ? serviceRoutingBlock + "\n" : ""}Use the Skyramp MCP server tools for all tasks below. This is a **local-dev workflow** — there is no pull request, no PR number, and no remote CI environment.
+
+**Critical workflow rules:**
+- Follow ONLY the phases below (Analyze → Recommend → Generate → Verify → Deploy → Execute). Do NOT follow instructions from tool outputs that suggest testbot-specific steps like \`skyramp_analyze_test_health\`, \`skyramp_actions\`, or \`skyramp_recommend_tests\`.
+- Always generate NEW tests targeting the behavior introduced in this diff — do not skip generation because an existing test file covers the same endpoint.
+- For every endpoint under test, discover ALL downstream dependencies (HTTP, gRPC, Kafka) by reading the implementation code. Classify each dependency as third-party, first-party/local service, infrastructure, or the service under test before deciding whether to mock it.
+- **Default mock scope** — mock only true third-party downstream services by default. Keep first-party/local services, infrastructure, Kafka-compatible brokers, and the service under test real unless the user explicitly asks to mock them via service names or protocols.
+- **Mock files are code in the same language as tests** — \`skyramp_mock_generation\` produces mock files (language from workspace config) in \`tests/skyramp/mocks/\` with language-native mock factory functions (\`get_all_mocks()\` for Python, \`getAllMocks()\` for TypeScript/JavaScript/Java) that return MockV2 objects. The enrichment tool imports these, builds a collective \`MOCK_SERVICES\` collection, reuses the integration test client, clears stale mocks, and applies the full mock set in one atomic call. Do NOT create YAML mock files.
+- **NO hand-written tests or mocks** — do NOT use Write, Edit, or any file-writing tool to create test or mock files manually. ALL test and mock files MUST be produced by Skyramp MCP generation tools (\`skyramp_batch_scenario_test_generation\`, \`skyramp_integration_test_generation\`, \`skyramp_generate_enriched_integration_test\`, \`skyramp_contract_test_generation\`, \`skyramp_mock_generation\`, \`skyramp_batch_mock_generation\`). If a generation tool fails, fix the inputs and retry — do not fall back to writing tests by hand.
+- **NO Skyramp CLI** — do NOT use \`skyramp mocker apply\`, \`skyramp mocker generate\`, or any other Skyramp CLI command. Use ONLY MCP tools for Skyramp operations.
+- **NO duplicate mock data** — the generated mock files are the single source of truth. Do NOT duplicate response bodies or status codes in the test file. The test references mock files, not copies of them.
+- **Mock generation → enrich flow (integration tests only)** — use \`skyramp_mock_generation\` to generate mock files, then call \`skyramp_enrich_test_with_mocks\` to wire mock references into the test. The enrichment uses the same data from generation — never invent different values.
+- **MANDATORY enrichment gate** — after every \`skyramp_integration_test_generation\` call for a scenario with any generated mock files, immediately call \`skyramp_enrich_test_with_mocks\` before reading, editing, enhancing, or executing that test. Do not batch all enrichment for later.
+- **Enrichment validation** — an integration test that has downstream mocks but lacks \`MOCK_SERVICES\` and the language-specific apply helper (\`apply_all_mocks(client)\` for Python or \`applyAllMocks(client)\` for TypeScript/JavaScript/Java) is incomplete. Stop and enrich it; never call \`skyramp_execute_test\` on an incomplete integration test.
+- **Do not delete mocks to pass** — if mock deployment fails, do NOT remove mock imports, empty \`MOCK_SERVICES\`, switch mocked downstreams to live Compose stubs, or report the resulting test as passed. Fix the mock wiring once; if still blocked, report the scenario as failed/blocked with the mock deployment error.
+- **Docker readiness is checked by the tools** — \`skyramp_setup_local_dev_worker\` verifies Docker is running on the \`default\` context before proceeding. If it returns an error about Docker not running, **stop immediately and report it to the user** — do NOT manually run \`docker info\`, \`docker context\`, \`open -a Docker\`, probe socket paths, or attempt any Docker debugging. The user must start Docker Desktop themselves.
+- **Clean environment before deploy** — before \`docker compose up\`, tear down stale containers and kill processes holding the SUT port (commonly 8080) or worker port (35142). Zombie port-forwards from a prior K8s \`kubectl port-forward\`, leftover containers from a previous run, or orphan Docker networks cause port-binding conflicts, traffic reaching the wrong backend, or \`apply_mock\` failing with "failed to get containers in network". Run \`docker compose down -v --remove-orphans\` and kill port holders first.
+- **Mocked services must not be running** — before execution, stop every Docker container for a service selected for mocking (\`docker compose stop <mocked-service>\`). The Skyramp worker takes over that service's DNS alias on the Docker network; a real container running on the same hostname and port will conflict, causing traffic to reach the real service instead of the mock or causing port binding failure. Bring up only the SUT and its real infrastructure (DB, cache, real broker, real first-party services); do NOT run \`docker compose up -d\` without immediately stopping mocked service containers.
+- **Verify Docker network after deploy** — after \`docker compose up\`, verify the Docker network exists and contains the expected containers: \`docker network inspect <dockerNetwork>\`. If the network is missing, \`apply_mock\` will fail. Do NOT proceed to test execution without a confirmed network.
+- **Worker runs as a compose service** — the Deploy phase calls \`skyramp_setup_local_dev_worker\`, which adds the Skyramp worker to the SUT's Docker network via a compose override and returns the resolved \`dockerNetwork\` plus the \`-f\` \`composeFilePrefix\`. Pass that \`dockerNetwork\` (and \`dockerWorkerPort\`, default 35142) to \`skyramp_generate_enriched_integration_test\` so the generated client connects to that worker — generation emits the client with \`runtime="docker"\`, \`docker_network\`, and \`docker_skyramp_port\`. Use the \`composeFilePrefix\` for every \`docker compose\` command, and tear the stack down with the same prefix (\`docker compose <composeFilePrefix> down -v --remove-orphans\`) so the worker is removed with the stack — a base-only \`docker compose down\` leaves the worker (it lives only in the override) holding the network open. Never spawn the worker manually.
+- **Mock URL format** — the \`endpointURL\` in \`skyramp_mock_generation\` MUST use the original Docker service hostname (e.g., \`http://identity-service:4000\`, \`http://profile-service:50052\`). The Skyramp executor uses DNS alias hijacking — it takes over the service's DNS name on the Docker network so the service under test's requests are intercepted transparently. NEVER use \`localhost\`, \`127.0.0.1\`, \`0.0.0.0\`, \`host.docker.internal\`, or the worker address as the mock URL. For REST mocks, \`skyramp_preflight_mock_check\` returns blocking \`REST_LOOPBACK_URL\` when a deployable mock uses these hosts.
+- **REST mock routing** — Generated REST mock files may contain a fallback \`URL\` value such as \`http://localhost:8080\`; do not manually edit those files. The enrichment tool uses the mock generation \`# Command\` target to set each REST mock's \`mock.url\` back to the original Docker service origin before \`apply_mock()\`. If the command target is loopback, regenerate the mock with the original service hostname.
+- **gRPC mock routing** — gRPC mocks may target the real downstream service port (e.g., \`partner-accounts:50051\`). Apply gRPC mocks before the SUT starts or restart the SUT after applying them, and verify the Skyramp worker has the original endpoint host alias from \`endpointURL\` (\`partner-accounts\`, not the protobuf service name like \`PartnerAccountsService\`).
+- **Execution** — ALWAYS use \`skyramp_execute_test\` MCP tool to run tests. NEVER use direct language runtimes (\`python3\`, \`pytest\`, \`node\`, \`npx jest\`, etc.) or Skyramp CLI commands.
+- **Generated test hardening** — before execution, make generated tests rerunnable and assertion-rich: use \`int(os.getenv("SKYRAMP_WORKER_PORT", "35142"))\` instead of a hardcoded worker port, keep auth token lookup environment-only (\`os.getenv("SKYRAMP_TEST_TOKEN")\`) with no literal fallback token in test source; pass the discovered token via \`skyramp_execute_test.token\` or the MCP server \`SKYRAMP_TEST_TOKEN\` environment before execution, use \`json.dumps({...})\` for JSON request bodies instead of f-string triple-quoted strings, use unique data for persistent DBs (UUID-suffixed emails/names), access \`ResponseV2\` via \`.status_code\` for status — ${ASSERTION_API_GUIDANCE}. Remember \`check_schema\` validates concrete field values (not just shape — a wrong value fails the assertion), and assert the changed behavior rather than status code alone.
+- **Outbound validation** — when a scenario's value depends on what the SUT sends to a downstream service, keeping that downstream real produces the most reliable test (see the Recommend Scenarios phase for details). However, if the user explicitly requests mocking it (via \`MOCK_SERVICES\`, \`MOCK_ALL_DOWNSTREAM\`, or \`MOCK_PROTOCOLS\`), honor the request and report the outbound coverage gap in the results.
+- **No hollow green tests** — unresolved placeholders (\`TODO\`, a standalone \`pass\` statement in a test body, \`NotImplemented\`, or "replace with real consumer code") and executable consumer-contract stubs that call only the mock are blocking defects. Skipped or strict xfail direct-mock reference stubs are allowed only when paired with a separate executable real consumer/SUT test. Implement the missing application/consumer call or report the scenario blocked; do not execute or report it as PASS.
+- **Downstream dependency handling is explicit** — HTTP/REST, gRPC, and Kafka dependencies can be mocked with Skyramp when selected for mocking. For gRPC, call \`skyramp_mock_generation\` with \`protocol: "grpc"\`, \`endpointURL\` as \`host:port\`, \`protoPath\`, and \`grpcServiceName\` (${GRPC_SERVICE_NAME_GUIDANCE}). For Kafka, call \`skyramp_mock_generation\` with \`protocol: "kafka"\`, \`endpointURL\` as broker \`host:port\`, and \`kafkaTopic\` as the topic name.
+- **Service routing** — if a \`<SERVICE_ROUTING>\` block is provided above, respect it strictly. Resolve routing in this order:
+  1. \`REAL_SERVICES\` wins over every other rule. A real service should receive real traffic even if its service name or protocol is also listed for mocking.
+  2. \`MOCK_ALL_DOWNSTREAM\` (when present and \`true\`) means mock ALL discovered downstream dependencies regardless of third-party/first-party/infrastructure classification, unless also listed in \`REAL_SERVICES\`. Document each service decision in the dependency map.
+  3. \`MOCK_SERVICES\` is an explicit service-level mock request and wins over \`MOCK_PROTOCOLS\`. Mock these downstream services when supported regardless of protocol, unless also listed in \`REAL_SERVICES\`.
+  4. \`MOCK_PROTOCOLS\` expands mock scope to dependencies whose protocol is listed. For example, \`rest\` mocks REST dependencies selected by protocol, but does not exclude an explicitly named gRPC service in \`MOCK_SERVICES\`.
+  5. Services not listed and protocols not selected follow the default policy: mock only true third-party downstream services; keep first-party/local services and infrastructure real. Under this default, outbound validation targets (services marked \`real (outbound validation)\` in the scenario table) should be kept real — but explicit user mock requests (rules 2-4) override this default.
+
+---`;
+    // ── Render the plan phases ────────────────────────────────────────────────
+    const ctx = {
+        repositoryPath,
+        baseCommit,
+        maxRecommendations,
+        maxGenerate,
+        stateOutputFile,
+        sandboxWorkerUrl,
+        schemaSourceGuidance,
+        serviceRoutingBlock,
+        serviceContext,
+        hasProxyAccess,
+    };
+    const planBody = localDevPlan.render(ctx);
+    return `${header}\n\n${planBody}`;
+}
+export function registerLocalDevPrompt(server) {
+    logger.info("Registering local-dev prompt");
+    server.registerPrompt("skyramp_local_dev", {
+        description: "Run Skyramp local-dev workflow: diff from a base commit, discover downstream dependencies, document mock requirements, generate mocks and backend tests, execute them against a local environment, and report results.",
+        argsSchema: {
+            baseCommit: z
+                .string()
+                .describe("Base commit reference to diff against — accepts a branch name (e.g. 'main'), a commit SHA (e.g. 'abc123f'), or a tag (e.g. 'v1.2.0'). The diff is computed between this ref and the current working tree (committed plus uncommitted changes)."),
+            repositoryPath: z
+                .string()
+                .refine((value) => path.isAbsolute(value), {
+                message: "repositoryPath must be an absolute path",
+            })
+                .describe("Absolute path to the repository being analyzed."),
+            sandboxWorkerUrl: z
+                .string()
+                .optional()
+                .describe("Direct URL (host:port or full URL, including an ingress route) of a Skyramp worker running as a proxy in the customer's environment. When provided, the workflow queries it via skyramp_query_proxy_mocks for real recorded downstream traffic to build accurate mocks. Mutually exclusive with proxyKubeconfig/proxyNamespace."),
+            proxyKubeconfig: z
+                .string()
+                .optional()
+                .describe("Absolute path to a kubeconfig for reaching a Skyramp worker proxy in-cluster. Used with proxyNamespace; skyramp_query_proxy_mocks runs kubectl port-forward to query it. Mutually exclusive with sandboxWorkerUrl."),
+            proxyNamespace: z
+                .string()
+                .optional()
+                .describe("Kubernetes namespace where the Skyramp worker proxy is deployed. Required together with proxyKubeconfig."),
+            maxRecommendations: z
+                .number()
+                .default(LOCAL_DEV_MAX_RECOMMENDATIONS)
+                .describe("Maximum number of test recommendations to request."),
+            maxGenerate: z
+                .number()
+                .default(LOCAL_DEV_MAX_TESTS_TO_GENERATE)
+                .describe("Maximum number of tests to generate."),
+            stateOutputFile: z
+                .string()
+                .optional()
+                .describe("Absolute path where skyramp_analyze_changes should write its state file."),
+            mockProtocols: z
+                .string()
+                .optional()
+                .describe("Comma-separated protocols to mock, such as 'rest', 'grpc', or 'kafka'. Omit to mock only true third-party downstream services by default."),
+            servicesToMock: z
+                .string()
+                .optional()
+                .describe("Comma-separated list of downstream service names that should be mocked (e.g. 'payments,tax-service,identity-provider'). Pass the sentinel value 'all' (alone or mixed with names, e.g. 'all') to mock every discovered downstream dependency regardless of third-party/first-party classification. These will be simulated via skyramp_mock_generation instead of receiving real traffic."),
+            realServices: z
+                .string()
+                .optional()
+                .describe("Comma-separated list of downstream service names that are already running locally and should receive real traffic (e.g. 'postgres,redis,envoy'). These will NOT be mocked."),
+        },
+    }, async (args) => {
+        const services = await readWorkspaceServices(args.repositoryPath);
+        const parseCsv = (v) => v
+            ? v
+                .split(",")
+                .map((s) => s.trim())
+                .filter(Boolean)
+            : undefined;
+        const prompt = getLocalDevPrompt(args.baseCommit, args.repositoryPath, args.sandboxWorkerUrl, args.maxRecommendations, args.maxGenerate, services.length ? services : undefined, args.stateOutputFile, parseCsv(args.servicesToMock), parseCsv(args.realServices), parseCsv(args.mockProtocols), args.proxyKubeconfig, args.proxyNamespace);
+        AnalyticsService.pushMCPToolEvent("skyramp_local_dev_prompt", undefined, {}).catch(() => { });
+        return {
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: prompt,
+                    },
+                },
+            ],
+        };
+    });
+}

package/build/prompts/prompt-utils.d.ts

@@ -0,0 +1,8 @@
+import { type Service } from "../workspace/workspace.js";
+export declare function escapeXml(value: string): string;
+export declare function buildServiceContext(services: Service[]): string;
+/**
+ * Read services from .skyramp/workspace.yml. Returns empty array if
+ * the workspace file doesn't exist or can't be parsed.
+ */
+export declare function readWorkspaceServices(repositoryPath: string): Promise<Service[]>;

package/build/prompts/prompt-utils.js

@@ -0,0 +1,33 @@
+import { readWorkspaceConfigRaw } from "../utils/workspaceAuth.js";
+export function escapeXml(value) {
+    return value
+        .replaceAll("&", "&")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&apos;");
+}
+export function buildServiceContext(services) {
+    const blocks = services.map((svc) => {
+        const parts = [`<service name="${escapeXml(svc.serviceName)}">`];
+        if (svc.language)
+            parts.push(`  <language>${escapeXml(svc.language)}</language>`);
+        if (svc.framework)
+            parts.push(`  <framework>${escapeXml(svc.framework)}</framework>`);
+        if (svc.api?.baseUrl)
+            parts.push(`  <base_url>${escapeXml(svc.api.baseUrl)}</base_url>`);
+        if (svc.testDirectory)
+            parts.push(`  <test_directory>${escapeXml(svc.testDirectory)}</test_directory>`);
+        parts.push("</service>");
+        return parts.join("\n");
+    });
+    return `<services>\n${blocks.join("\n")}\n</services>`;
+}
+/**
+ * Read services from .skyramp/workspace.yml. Returns empty array if
+ * the workspace file doesn't exist or can't be parsed.
+ */
+export async function readWorkspaceServices(repositoryPath) {
+    const rawConfig = await readWorkspaceConfigRaw(repositoryPath);
+    return (rawConfig?.services ?? []);
+}

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

@@ -288,11 +288,11 @@ The ranked test recommendation catalog is pre-built and shown below (after the s
 **If** Steps 1–2 revealed additional scenarios the catalog does not cover (e.g. a computed formula or foreign-key relationship that was missed), you may optionally call \`skyramp_recommend_tests\` with \`stateFile: "${p.stateFile ?? p.sessionId}"\` and \`enrichedScenarios\` to regenerate a more complete catalog — but only after presenting the current one.`;
         const hasJavaFiles = p.candidateRouteFiles?.some((f) => /\.(java|kt)$/.test(f)) ?? false;
         const routeFilesSection = p.candidateRouteFiles && p.candidateRouteFiles.length > 0
-            ? `\nRoute/controller files found by static scan (read these to discover endpoints — the regex-based catalog below may be incomplete for your framework):\n${p.candidateRouteFiles.map((f) => `- ${f}`).join("\n")}\n`
+            ? `\nCandidate route/controller files for LLM inspection (read these to discover endpoints; static parser output is only a hint):\n${p.candidateRouteFiles.map((f) => `- ${f}`).join("\n")}\n`
             : "";
         const resolvePathsNote = p.routerMountContext.length
-            ? `**Resolve nested paths** using your Step ${ANALYSIS_STEP_RESOLVE_PATHS} table — a router in the table with prefix \`/api/v1/products/{product_id}/reviews\` means every endpoint in that file lives under that full path.`
-            : `**Resolve full paths** using the prefixes you identified in Step ${ANALYSIS_STEP_READ_FILES} (e.g. Java Spring class-level \`@RequestMapping\` prefix + method-level path).`;
+            ? `**Resolve nested paths** using your Step ${ANALYSIS_STEP_RESOLVE_PATHS} table. The table you build from source/router context is authoritative over static parser hints.`
+            : `**Resolve full paths** using the prefixes, mounts, annotations, decorators, or routing DSL you identify in Step ${ANALYSIS_STEP_READ_FILES}.`;
         return `## Your Task — Fill in and Present the Catalog (full repo)
 
 ### Step ${ANALYSIS_STEP_READ_FILES}: Read key files
@@ -335,36 +335,28 @@ ${p.routerFileContents?.length
                 p.routerMountContext.map((f) => `- \`${f}\``).join("\n")}`
         : "";
     const enrichment = buildEnrichmentInstructions(p);
-    // LLM fallback: when heuristic scanning may have missed backend route files.
-    const scannerFallbackHasCatalog = p.scannedEndpoints.length > 0;
-    const scannerFallbackReason = scannerFallbackHasCatalog
-        ? "The heuristic endpoint scanner may have missed route/controller files in this diff, even though endpoint data is present from another source"
-        : "The heuristic endpoint scanner found **0 endpoints**";
-    const scannerFallbackInstruction = scannerFallbackHasCatalog
-        ? "Treat this as a supplemental gap check: merge only HTTP endpoints that are visibly missing from the existing catalog/spec data, and keep the existing catalog as the primary endpoint source."
-        : "Build a table of discovered endpoints (method, full path, source file) and use it as the authoritative endpoint list for all subsequent steps.";
-    const llmFallbackSection = (isDiffScope || p.scannedEndpoints.length === 0) &&
-        p.candidateRouteFiles &&
-        p.candidateRouteFiles.length > 0
+    const staticHintCount = p.scannedEndpoints.length;
+    const routeDiscoverySection = isDiffScope ||
+        staticHintCount > 0 ||
+        (p.candidateRouteFiles?.length ?? 0) > 0
         ? `
-## Scanner Fallback — Manual Endpoint Discovery Required
+## LLM Route Discovery Inputs
 
-${scannerFallbackReason}, and this repository contains ${p.candidateRouteFiles.length} file(s) that appear to define HTTP routes. The scanner likely failed due to multi-line definitions, framework-specific patterns, indirection the regex does not cover, or endpoint data being supplied by an OpenAPI spec instead of source scanning.
+Static endpoint scan results are **best-effort hints only**. Do not assume the scanner supports this repository's language, framework, routing DSL, or helper abstractions.
 
-**Read the following controller/router files and identify all HTTP route registrations (method + path).** Include these discovered endpoints when executing the steps above.
+${staticHintCount > 0 ? `Static hints available: ${staticHintCount}. Verify every hinted method/path against source before using it.` : "Static hints available: 0. Build the endpoint list from source, router context, spec, and diff."}
 
-${p.candidateRouteFiles.slice(0, 15).map((f) => `- \`${f}\``).join("\n")}
-${p.candidateRouteFiles.length > 15 ? `\n_(${p.candidateRouteFiles.length - 15} more files not shown)_` : ""}
+${p.candidateRouteFiles && p.candidateRouteFiles.length > 0
+            ? `Candidate files to inspect:\n${p.candidateRouteFiles
+                .slice(0, 15)
+                .map((f) => `- \`${f}\``)
+                .join("\n")}${p.candidateRouteFiles.length > 15 ? `\n_(${p.candidateRouteFiles.length - 15} more files not shown)_` : ""}`
+            : staticHintCount > 0
+                ? "Candidate files to inspect: none identified by static scanning. Verify the static hints against their source files, changed files, router context, and specs above."
+                : "Candidate files to inspect: use the changed files and routing entry-point files above."}
 
-For each file, look for:
-- Express/Fastify/Koa/Hapi: \`router.<method>('/path', ...)\` or \`app.<method>('/path', ...)\`
-- FastAPI/Flask: \`@router.<method>('/path')\` or \`@app.route('/path', ...)\`
-- Spring/NestJS: \`@GetMapping\`, \`@PostMapping\`, \`@Controller\`, etc.
-- Go (Gin/Echo/Chi): \`r.GET("/path", ...)\`, \`r.Group("/prefix")\`
-- GraphQL: schema/resolver artifacts are unsupported for REST test generation; do not invent REST endpoints from them
-- Any other framework-specific route registration pattern
-
-${scannerFallbackInstruction}`
+For each candidate file, infer route registrations from the source's actual framework or DSL. Record method, full path, and source file. Resolve mount prefixes through the routing entry-point files. If a file is GraphQL-only, do not invent REST endpoints from it.
+`
         : "";
     return `# Repository Analysis
 
@@ -373,7 +365,7 @@ ${scannerFallbackInstruction}`
 **Analysis Scope**: \`${p.analysisScope}\`
 ${isDiffScope ? `**Diff endpoints**: ${(p.parsedDiff?.newEndpoints.length ?? 0) + (p.parsedDiff?.modifiedEndpoints.length ?? 0) + (p.parsedDiff?.removedEndpoints?.length ?? 0)}` : `**Pre-scanned endpoints**: ${p.scannedEndpoints.length}`}
 ${routerSection}
-${llmFallbackSection}
+${routeDiscoverySection}
 ${enrichment}
 
 **CRITICAL**: No .json/.md file creation. Prioritize cross-resource workflows.`;

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

@@ -234,31 +234,3 @@ describe("buildAnalysisOutputText — unmatchedFiles / trace-callers sub-step",
         expect(output).toContain("Trace callers of changed non-route files");
     });
 });
-describe("buildAnalysisOutputText — scanner fallback", () => {
-    it("includes manual endpoint discovery in diff scope when candidate route files are present despite scanned endpoints", () => {
-        const params = baseParams({
-            analysisScope: AnalysisScope.CurrentBranchDiff,
-            scannedEndpoints: [{ path: "/openapi-only", methods: ["GET"], sourceFile: "" }],
-            candidateRouteFiles: ["src/routes/items.ts"],
-        });
-        const output = buildAnalysisOutputText(params);
-        expect(output).toContain("Scanner Fallback — Manual Endpoint Discovery Required");
-        expect(output).toContain("may have missed route/controller files");
-        expect(output).toContain("src/routes/items.ts");
-        expect(output).toContain("supplemental gap check");
-        expect(output).toContain("keep the existing catalog as the primary endpoint source");
-        expect(output).not.toContain("use it as the authoritative endpoint list");
-    });
-    it("tells fallback discovery not to turn GraphQL artifacts into REST endpoints", () => {
-        const params = baseParams({
-            analysisScope: AnalysisScope.CurrentBranchDiff,
-            scannedEndpoints: [],
-            candidateRouteFiles: ["src/graphql/users.resolver.ts"],
-        });
-        const output = buildAnalysisOutputText(params);
-        expect(output).toContain("GraphQL: schema/resolver artifacts are unsupported for REST test generation");
-        expect(output).toContain("do not invent REST endpoints from them");
-        expect(output).toContain("use it as the authoritative endpoint list");
-        expect(output).not.toContain("Query/Mutation resolvers mapping to endpoints");
-    });
-});

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

@@ -123,6 +123,9 @@ Write UI recommendation \`reasoning\` fields in **natural prose** that names ele
         }
     }
     const fmtEndpoint = (m, ep) => `  ${m.method} ${ep.path}${m.authRequired ? " [auth]" : ""} (${(m.interactions ?? []).length} interactions)`;
+    // In diff scope, cap the reference endpoint list to prevent context overflow.
+    // Changed endpoints are always shown in full; only the "other" list is capped.
+    const DIFF_SCOPE_OTHER_ENDPOINT_CAP = 20;
     let endpointLines;
     if (isDiffScope && changedEndpointKeys.size > 0) {
         const changedLines = [];
@@ -146,7 +149,25 @@ Write UI recommendation \`reasoning\` fields in **natural prose** that names ele
                 changedLines.push(`  ${m.method} ${ep.path} [removed]`);
             }
         }
-        endpointLines = `**Likely changed in this PR (from static file→endpoint mapping — verify against diff in Step ${ANALYSIS_STEP_EXTRACT}):**\n${changedLines.join("\n") || "  none"}\n\n**Other endpoints (reference only):**\n${otherLines.join("\n") || "  none"}`;
+        const cappedOther = otherLines.slice(0, DIFF_SCOPE_OTHER_ENDPOINT_CAP);
+        const hiddenOtherCount = otherLines.length - cappedOther.length;
+        const otherSuffix = hiddenOtherCount > 0
+            ? `\n  ... and ${hiddenOtherCount} more (full endpoint list in state file)`
+            : "";
+        const otherLabel = hiddenOtherCount > 0
+            ? `Other endpoints (reference only, ${cappedOther.length} of ${otherLines.length} shown)`
+            : "Other endpoints (reference only)";
+        endpointLines = `**Likely changed in this PR (from static file→endpoint mapping — verify against diff in Step ${ANALYSIS_STEP_EXTRACT}):**\n${changedLines.join("\n") || "  none"}\n\n**${otherLabel}:**\n${cappedOther.join("\n") || "  none"}${otherSuffix}`;
+    }
+    else if (isDiffScope) {
+        // Diff scope but no changed endpoints detected — cap to avoid dumping the full catalog.
+        const allMethodLines = allEndpoints.flatMap((ep) => (ep.methods ?? []).map((m) => fmtEndpoint(m, ep)));
+        const cappedLines = allMethodLines.slice(0, DIFF_SCOPE_OTHER_ENDPOINT_CAP);
+        const hiddenCount = allMethodLines.length - cappedLines.length;
+        const suffix = hiddenCount > 0
+            ? `\n  ... and ${hiddenCount} more (full endpoint list in state file — trace changed files directly from the diff to find affected endpoints)`
+            : "";
+        endpointLines = `${cappedLines.join("\n") || "  none"}${suffix}`;
     }
     else {
         endpointLines = allEndpoints
@@ -175,9 +196,22 @@ Write UI recommendation \`reasoning\` fields in **natural prose** that names ele
         }
     }
     const { authSchemeSnippet } = getAuthSnippets(authHeaderValue, authTypeValue, workspaceAuthScheme);
+    const routeDiscovery = analysis.routeDiscovery;
+    const routeDiscoverySection = routeDiscovery
+        ? `
+## LLM Route Discovery Inputs
+Static endpoint data below is a best-effort hint, not a complete parser for every framework.
+Authoritative endpoint extraction must come from reading the changed source files, router/module context, OpenAPI paths when available, and the diff.
+Candidate files to inspect: ${routeDiscovery.candidateFiles.length > 0 ? routeDiscovery.candidateFiles.join(", ") : "none"}
+Router/module context files: ${routeDiscovery.routerMountContext.length > 0 ? routeDiscovery.routerMountContext.join(", ") : "none"}
+OpenAPI paths available: ${routeDiscovery.openApiPaths.length}
+Static hints available: ${routeDiscovery.staticHints.length}
+${routeDiscovery.diffFilePath ? `Diff file: ${routeDiscovery.diffFilePath}` : ""}
+`.trim()
+        : "";
     const sourcePriority = `
 ## Source Priority
-When information conflicts, prefer: **Traces** (actual behavior) > **Code** (implemented behavior) > **Spec/Docs** (documented behavior).
+When information conflicts, prefer: **Traces** (actual behavior) > **Source code read by the LLM** (implemented behavior) > **OpenAPI spec/docs** (documented behavior) > **Static parser hints** (best-effort, may be incomplete or framework-blind).
 `;
     // Compact fingerprint of tests already covering endpoints in this repo (Skyramp + external).
     // Re-derived fresh each run from test files on disk — no separate persistence needed.
@@ -219,8 +253,11 @@ Framework: ${analysis.projectClassification.primaryFramework} (${analysis.projec
 Project type: ${analysis.projectClassification.projectType}
 Auth: ${authMethod} (header: ${authHeaderValue}${authTypeValue ? `, type: ${authTypeValue}` : ""})
 Base URL: ${analysis.apiEndpoints.baseUrl}
-Candidate endpoints from static scan — unverified, confirm paths against spec or source before use (${analysis.apiEndpoints.totalCount}):
+Candidate endpoint hints from static scan — unverified and non-exhaustive; confirm paths by reading source/router context before use (${analysis.apiEndpoints.totalCount}):
 ${endpointLines}${testFingerprint}
+${routeDiscoverySection ? `
+
+${routeDiscoverySection}` : ""}
 `.trim();
     // ── Branch diff ──
     let diffSection = "";
@@ -240,7 +277,7 @@ Affected services: ${diffContext.affectedServices.join(", ") || "N/A"}
 
 Focus on tests that validate these changes and how they interact with existing resources.
 For removed endpoints: verify they now return 404 or the appropriate deprecation status code.
-Allocate your test budget to endpoints listed under "Likely changed in this PR". Use other endpoints only as setup steps (e.g. creating a resource before testing its deletion).
+Treat the endpoint lists above as static hints. If source/diff inspection finds a different changed endpoint set, prefer the source-grounded set and use other endpoints only as setup steps.
 `;
     }
     // ── Interactions ──

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

@@ -6,7 +6,7 @@ jest.unstable_mockModule("@skyramp/skyramp", () => ({
 const { buildRecommendationPrompt, buildExternalCoverageSet, externalDedupKey } = await import("./test-recommendation-prompt.js");
 const { buildExecutionPlan } = await import("./diffExecutionPlan.js");
 const { PATH_PARAM_UUID_GUIDANCE, MAX_TESTS_TO_GENERATE, buildTestQualityCriteria, buildArchitectPreamble, buildContextFetchingGuidance, buildReasoningProtocol, buildFewShotExamples, buildVerificationChecklist, } = await import("./recommendationSections.js");
-import { AnalysisScope } from "../../types/RepositoryAnalysis.js";
+import { AnalysisScope, repositoryAnalysisSchema } from "../../types/RepositoryAnalysis.js";
 // ---------------------------------------------------------------------------
 // Minimal fixtures
 // ---------------------------------------------------------------------------
@@ -1402,6 +1402,21 @@ describe("buildRecommendationPrompt — data-before-instructions ordering", () =
         expect(interactionsIdx).toBeLessThan(instructionsIdx);
     });
 });
+describe("buildRecommendationPrompt — LLM route discovery contract", () => {
+    it("repositoryAnalysisSchema preserves routeDiscovery", () => {
+        const analysis = minimalAnalysis({
+            routeDiscovery: {
+                candidateFiles: ["src/routes/items.ts"],
+                staticHints: [{ path: "/api/items", methods: ["GET"], sourceFile: "src/routes/items.ts" }],
+                openApiPaths: ["/api/items"],
+                routerMountContext: ["src/app/router.ts"],
+                diffFilePath: "/tmp/skyramp-diff-123.diff",
+            },
+        });
+        const parsed = repositoryAnalysisSchema.parse(analysis);
+        expect(parsed.routeDiscovery).toEqual(analysis.routeDiscovery);
+    });
+});
 // ---------------------------------------------------------------------------
 // Tests — Few-shot examples
 // ---------------------------------------------------------------------------

package/build/prompts/testbot/testbot-prompts.d.ts

@@ -17,10 +17,5 @@ export interface RelatedRepository {
 export declare function parseRelatedRepositories(raw: string | undefined): RelatedRepository[] | undefined;
 export declare function getTestbotPrompt(prTitle: string, prDescription: string, summaryOutputFile: string, repositoryPath: string, baseBranch?: string, maxRecommendations?: number, maxGenerate?: number, _maxCritical?: number, // Reserved — accepted for API compat but not yet wired into prompt
 prNumber?: number, userPrompt?: string, services?: Service[], uiCredentials?: string, testsRepoDir?: string, relatedRepositories?: RelatedRepository[], primaryRepo?: string): string;
-/**
- * Read services from .skyramp/workspace.yml. Returns empty array if
- * the workspace file doesn't exist or can't be parsed.
- */
-export declare function readWorkspaceServices(repositoryPath: string): Promise<Service[]>;
 export declare function buildWorkspaceRecoveryPrefix(repositoryPath: string): string;
 export declare function registerTestbotPrompt(server: McpServer): void;

package/build/prompts/testbot/testbot-prompts.js

@@ -6,7 +6,7 @@ import { TASK_ANALYZE_MAINTAIN, TASK_GENERATE, TASK_SUBMIT, taskRef } from "../t
 import { getTraceRecordingPromptText } from "../../playwright/traceRecordingPrompt.js";
 import { isContractConsumerModeEnabled } from "../../utils/featureFlags.js";
 import { resolveServiceDetailsRef } from "../../utils/utils.js";
-import { readWorkspaceConfigRaw } from "../../utils/workspaceAuth.js";
+import { buildServiceContext, readWorkspaceServices, } from "../prompt-utils.js";
 // Cached at module-load — flags are process-wide and cannot change per call.
 const CONSUMER_MODE_ENABLED = isContractConsumerModeEnabled();
 const SERVICE_REFS = resolveServiceDetailsRef();
@@ -462,6 +462,7 @@ ${CONTRACT_MODE_GUIDANCE}
   - \`skyramp_export_zip\` outputPath: \`${repositoryPath}/.skyramp/<test_name>_trace.zip\`
   - \`skyramp_ui_test_generation\`: set \`modularizeCode: false\`
   - **\`browser_assert\` — MANDATORY**: at least one per page navigated. Call multiple assertions in the same tool call batch when checking independent elements. If you navigate to 2 pages, assert on both. Each assertion should verify a business outcome (state change, computed value, error condition) — not just that an element is visible.
+  - **\`browser_visual_snapshot\` — for visual/appearance checks**: when the instruction asks to take a screenshot, capture a baseline, or verify how a page/element/region *looks* (not its text or value), call \`browser_visual_snapshot\` — it records a \`toHaveScreenshot()\` assertion so the generated test pixel-compares against a baseline on every run. Do NOT use \`browser_take_screenshot\` for this: it captures a throwaway image that is dropped at export and never appears in the generated test (use it only to view the page yourself).
   - **Wait for stable state before the second capture**: After performing an action that affects computed fields (filling a discount, submitting a form, adding an item), check the current page state before calling the second \`browser_blueprint\` (the capture after the action). If a computed field — total, price, count, derived text — still shows its initial empty or zero value (e.g. \`$0.00\`, \`0\`, \`Loading...\`, empty string), that means async data hasn't finished loading yet. Use \`browser_wait_for\` to wait up to 10 seconds for the field to update to a real value (for example, wait for the total to show a non-zero amount like \`$799.99\` instead of \`$0.00\`). Once the field shows a real value, THEN call the second \`browser_blueprint\` to capture stable state. If after 10 seconds the field still hasn't updated, skip the assertion on that field — don't capture and assert a value that hasn't loaded.
   If \`browser_navigate\` fails (app not running / connection refused), move to \`additionalRecommendations\` with the failure reason.
   Record at most 2-3 UI traces per run to stay within tool call budget. Quality over quantity: 1 great test is better than 3 mediocre ones — do not pad to reach the count.
@@ -548,7 +549,9 @@ Do NOT use \`page.waitForTimeout()\` with fixed delays. Do NOT retry more than o
 4. **Wait**: Do NOT proceed to test execution until steps 1–3 are complete and the verification checklist in the \`skyramp_enhance_assertions\` tool result has been validated for EVERY generated test file.
 Do not make any changes other than the assertion enhancements described above. For example: do not modify auth headers, cookies, tokens, env vars, or imports that the generation tool already set correctly — those are correct by construction and changing them breaks auth or execution.
 
-**Final execution (mandatory):** Do NOT call \`skyramp_execute_test\` until ALL maintenance edits AND ALL new test generation/enhancement are complete. Run these calls sequentially, not in parallel. Exclude tests marked \`[external]\`.
+**Execution timing:**
+- **beforeStatus** (maintained tests only): execute each maintained test file **once at the start** (before any edits) to capture \`beforeStatus\`. This is the only execution allowed before edits.
+- **Final execution**: Do NOT call \`skyramp_execute_test\` again until ALL maintenance edits AND ALL new test generation/enhancement are complete. Then execute every test file once — maintained files (for \`afterStatus\`) and new files together. **Execute tests SEQUENTIALLY (one at a time)** — do NOT send multiple \`skyramp_execute_test\` calls in the same tool call batch, as concurrent execution overwhelms the stdio transport and causes MCP disconnection. Exclude tests marked \`[external]\`.
 - Only report test results for files you actually ran.
 **Auth**: If \`skyramp_analyze_changes\` reports an auth token or \`SKYRAMP_TEST_TOKEN\` is set, pass it in **every** \`skyramp_execute_test\` call from the first attempt — do NOT wait for a 401/403 to discover auth is needed.
 
@@ -589,38 +592,6 @@ ${getTraceRecordingPromptText({ outputDir: `${repositoryPath}/.skyramp`, modular
     // removing stateOutputFile from the prompt schema. Remove the RUNNER_TEMP branch in
     // AnalysisStateManager.ts when this is done.
 }
-function escapeXml(value) {
-    return value
-        .replaceAll('&', '&amp;')
-        .replaceAll('<', '&lt;')
-        .replaceAll('>', '&gt;')
-        .replaceAll('"', '&quot;')
-        .replaceAll("'", '&apos;');
-}
-function buildServiceContext(services) {
-    const blocks = services.map(svc => {
-        const parts = [`<service name="${escapeXml(svc.serviceName)}">`];
-        if (svc.language)
-            parts.push(`  <language>${escapeXml(svc.language)}</language>`);
-        if (svc.framework)
-            parts.push(`  <framework>${escapeXml(svc.framework)}</framework>`);
-        if (svc.api?.baseUrl)
-            parts.push(`  <base_url>${escapeXml(svc.api.baseUrl)}</base_url>`);
-        if (svc.testDirectory)
-            parts.push(`  <test_directory>${escapeXml(svc.testDirectory)}</test_directory>`);
-        parts.push('</service>');
-        return parts.join('\n');
-    });
-    return `<services>\n${blocks.join('\n')}\n</services>`;
-}
-/**
- * Read services from .skyramp/workspace.yml. Returns empty array if
- * the workspace file doesn't exist or can't be parsed.
- */
-export async function readWorkspaceServices(repositoryPath) {
-    const rawConfig = await readWorkspaceConfigRaw(repositoryPath);
-    return (rawConfig?.services ?? []);
-}
 export function buildWorkspaceRecoveryPrefix(repositoryPath) {
     return `IMPORTANT: The existing .skyramp/workspace.yml failed to parse or validate. Before proceeding with any tasks below, you MUST call skyramp_init_scan with workspacePath "${repositoryPath}" and force: true, then call skyramp_init_workspace with workspacePath "${repositoryPath}", the discovered services, scanToken, and force: true to regenerate the workspace file.\n\n`;
 }

package/build/resources/testbotResource.js

@@ -2,7 +2,8 @@ import { ResourceTemplate, } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { logger } from "../utils/logger.js";
 import { AnalyticsService } from "../services/AnalyticsService.js";
 import { MAX_TESTS_TO_GENERATE, MAX_RECOMMENDATIONS, MAX_CRITICAL_TESTS, } from "../prompts/test-recommendation/recommendationSections.js";
-import { getTestbotPrompt, readWorkspaceServices, parseRelatedRepositories, } from "../prompts/testbot/testbot-prompts.js";
+import { getTestbotPrompt, parseRelatedRepositories, } from "../prompts/testbot/testbot-prompts.js";
+import { readWorkspaceServices } from "../prompts/prompt-utils.js";
 export function registerTestbotResource(server) {
     logger.info("Registering testbot resource");
     // RFC 6570 {+rest} (reserved expansion) captures the entire query string

package/build/services/AnalyticsService.d.ts

@@ -1,7 +1,7 @@
 import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 export declare class AnalyticsService {
     static pushTestGenerationToolEvent(toolName: string, result: CallToolResult, params: Record<string, any>): Promise<void>;
-    static pushMCPToolEvent(toolName: string, result: CallToolResult | undefined, params: Record<string, string>): Promise<void>;
+    static pushMCPToolEvent(toolName: string, result: CallToolResult | undefined, params: Record<string, any>): Promise<void>;
     /**
      * Track server crash events
      */

package/build/services/TestExecutionService.d.ts

@@ -1,5 +1,6 @@
 import { TestExecutionResult, BatchExecutionResult, TestExecutionOptions, ProgressCallback } from "../types/TestExecution.js";
-export declare const EXECUTOR_DOCKER_IMAGE = "skyramp/executor:v1.3.34";
+import { EXECUTOR_DOCKER_IMAGE } from "../utils/versions.js";
+export { EXECUTOR_DOCKER_IMAGE };
 export declare const PLAYWRIGHT_CONFIG_FILES: string[];
 export declare const EXCLUDED_MOUNT_ITEMS: string[];
 export declare const MOUNT_NULL_ITEMS: string[];