@skyramp/mcp 0.2.6 → 0.2.150-rc.mntnc

package/build/utils/routeParsers.js

@@ -406,21 +406,36 @@ const GENERIC_ROUTE_BASENAMES = new Set(["api", "app", "handler", "handlers", "i
 function normalizeSourcePath(filePath) {
     return filePath.replace(/\\/g, "/");
 }
-/**
- * Classify endpoints by cross-referencing `changedFiles` against `scannedEndpoints[].sourceFile`.
- *
- * This replaces `parseEndpointsFromDiff` — instead of regex-parsing diff hunks for route
- * annotations (fragile for 15+ frameworks), it uses the already-scanned endpoint catalog
- * which has full, resolved paths and concrete HTTP methods.
- *
- * For deleted files, the caller must supply endpoints recovered from the base branch
- * (via `parseFileEndpoints` on `git show base:<file>`) in `deletedFileEndpoints`.
- */
+function staticPathSegments(urlPath) {
+    return urlPath.split("/").filter(s => s && !/^[:{[]/.test(s)).map(s => s.toLowerCase());
+}
+function endpointSourceResource(ep) {
+    const sourceSegments = ep.sourceFile.split(/[\\/]/).filter(Boolean);
+    const filename = sourceSegments.at(-1)?.replace(/\.[^.]+$/, "") ?? "";
+    const normalizedFilename = filename.replace(/^(?:old|new)[-_]/i, "").toLowerCase();
+    const isDynamic = /^\[.*\]$/.test(normalizedFilename) || /^\{.*\}$/.test(normalizedFilename);
+    if (!isDynamic && !GENERIC_ROUTE_BASENAMES.has(normalizedFilename) && normalizedFilename) {
+        return normalizedFilename;
+    }
+    else if (GENERIC_ROUTE_BASENAMES.has(normalizedFilename)) {
+        // Generic filename: walk up the directory tree for a more specific ancestor name.
+        const parentSegments = sourceSegments.slice(0, -1).reverse();
+        const contextSegment = parentSegments
+            .map(s => s.replace(/\.[^.]+$/, "").replace(/^(?:old|new)[-_]/i, "").toLowerCase())
+            .find(s => s && !GENERIC_ROUTE_BASENAMES.has(s) && !/^\[.*\]$/.test(s) && !/^\{.*\}$/.test(s));
+        if (contextSegment)
+            return `${contextSegment}/${normalizedFilename}`;
+    }
+    // Fall back to the last static segment of the endpoint's URL path.
+    const segments = staticPathSegments(ep.path);
+    return segments.at(-1) ?? normalizedFilename;
+}
+function endpointMovedKey(path, resource, method) {
+    return method ? `${path}::${resource}::${method}` : `${path}::${resource}`;
+}
 export function classifyEndpointsByChangedFiles(diffData, scannedEndpoints, deletedFileEndpoints) {
     const newFileSet = new Set(diffData.newFiles.map(normalizeSourcePath));
     const deletedFileSet = new Set(diffData.deletedFiles.map(normalizeSourcePath));
-    // Build sourceFile -> ScannedEndpoint[] map from the post-change catalog.
-    // Git diffs use POSIX separators; scanner output can reflect OS-native paths.
     const bySourceFile = new Map();
     for (const ep of scannedEndpoints) {
         const sourceKey = normalizeSourcePath(ep.sourceFile);
@@ -435,7 +450,6 @@ export function classifyEndpointsByChangedFiles(diffData, scannedEndpoints, dele
     const unmatchedFiles = [];
     for (const file of diffData.changedFiles) {
         const fileKey = normalizeSourcePath(file);
-        // Deleted files won't appear in scanned catalog — handled separately below
         if (deletedFileSet.has(fileKey))
             continue;
         const eps = bySourceFile.get(fileKey);
@@ -454,47 +468,26 @@ export function classifyEndpointsByChangedFiles(diffData, scannedEndpoints, dele
     // Filter out endpoints that still exist in the current catalog as moved/refactored.
     // Same router-relative paths can exist in sibling files, so only treat them as moved
     // when the source resource also matches.
-    function endpointSourceResource(ep) {
-        const sourceSegments = ep.sourceFile.split(/[\\/]/).filter(Boolean);
-        const base = sourceSegments.at(-1)?.replace(/\.[^.]+$/, "") ?? "";
-        const normalizedBase = base.replace(/^(?:old|new)[-_]/i, "").toLowerCase();
-        const isDynamicBase = /^\[.*\]$/.test(normalizedBase) || /^\{.*\}$/.test(normalizedBase);
-        if (normalizedBase && !isDynamicBase && !GENERIC_ROUTE_BASENAMES.has(normalizedBase)) {
-            return normalizedBase;
-        }
-        if (normalizedBase && GENERIC_ROUTE_BASENAMES.has(normalizedBase)) {
-            const contextSegment = [...sourceSegments]
-                .slice(0, -1)
-                .reverse()
-                .map((segment) => segment.replace(/\.[^.]+$/, "").replace(/^(?:old|new)[-_]/i, "").toLowerCase())
-                .find((segment) => segment && !GENERIC_ROUTE_BASENAMES.has(segment) && !/^\[.*\]$/.test(segment) && !/^\{.*\}$/.test(segment));
-            if (contextSegment)
-                return `${contextSegment}/${normalizedBase}`;
-        }
-        const staticSegments = ep.path.split("/").filter(Boolean).filter((segment) => !/^[:{[]/.test(segment));
-        return staticSegments[staticSegments.length - 1]?.toLowerCase() ?? normalizedBase;
-    }
     const currentMethodKeys = new Set();
     const currentPathResourceKeys = new Set();
     const currentMultiKeys = new Set();
-    const movedKey = (path, resource, method) => method ? `${path}::${resource}::${method}` : `${path}::${resource}`;
     for (const current of scannedEndpoints) {
         const currentResource = endpointSourceResource(current);
-        const pathResourceKey = movedKey(current.path, currentResource);
+        const pathResourceKey = endpointMovedKey(current.path, currentResource);
         currentPathResourceKeys.add(pathResourceKey);
         for (const method of current.methods) {
             if (method === "MULTI")
                 currentMultiKeys.add(pathResourceKey);
-            currentMethodKeys.add(movedKey(current.path, currentResource, method));
+            currentMethodKeys.add(endpointMovedKey(current.path, currentResource, method));
         }
     }
     function isMovedEndpoint(deleted, method) {
         const deletedResource = endpointSourceResource(deleted);
-        const pathResourceKey = movedKey(deleted.path, deletedResource);
+        const pathResourceKey = endpointMovedKey(deleted.path, deletedResource);
         if (method === "MULTI")
             return currentPathResourceKeys.has(pathResourceKey);
         return currentMultiKeys.has(pathResourceKey) ||
-            currentMethodKeys.has(movedKey(deleted.path, deletedResource, method));
+            currentMethodKeys.has(endpointMovedKey(deleted.path, deletedResource, method));
     }
     const removedEndpoints = (deletedFileEndpoints ?? [])
         .map((ep) => ({

package/build/utils/routeParsers.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/utils/scenarioDrafting.d.ts

@@ -0,0 +1,71 @@
+import { DraftedScenario } from "../types/RepositoryAnalysis.js";
+import { WorkspaceAuthType } from "./workspaceAuth.js";
+export declare function isRealResource(r: string): boolean;
+type MethodInput = string | {
+    method: string;
+    sourceFile?: string;
+    interactions?: Array<{
+        request?: {
+            body?: Record<string, unknown>;
+        };
+    }>;
+};
+type EndpointInput = {
+    path: string;
+    methods: Array<MethodInput>;
+};
+type EndpointRef = {
+    method: string;
+    path: string;
+    sourceFile?: string;
+};
+type ScenarioDraftOptions = {
+    /** Existing endpoints touched by a security/destructive diff; used only for attack-surface expansion. */
+    changedEndpoints?: Array<EndpointRef>;
+    /** Gate sibling destructive expansion to diffs with auth/permission/admin-key signals. */
+    securityRelevantDiff?: boolean;
+};
+export type ResourceRelationships = Map<string, Set<string>>;
+/**
+ * Infer parent→child resource relationships from two signals already present
+ * in the endpoint data — no source code scanning required.
+ *
+ * Signal 1 — path nesting (always available):
+ *   /collections/{id}/links  →  links depends on collections
+ *
+ * Signal 2 — request body FK fields (available when trace data is merged):
+ *   POST /orders body: { product_id: "..." }  →  orders depends on products
+ *
+ * Returns a map of `dependent → Set<parent>`. Only confirmed, real-resource
+ * pairs are included. When no signal is found the map is empty, which tells
+ * the caller to fall back to heuristic pairing.
+ */
+export declare function inferResourceRelationships(endpoints: Array<EndpointInput>): ResourceRelationships;
+export declare function draftScenariosFromEndpoints(endpoints: Array<EndpointInput>, newEndpoints?: Array<EndpointRef>, wsAuthType?: WorkspaceAuthType, options?: ScenarioDraftOptions, removedEndpoints?: Array<EndpointRef>): DraftedScenario[];
+/**
+ * Draft scenarios that directly test each new endpoint in the branch diff.
+ *
+ * For each new endpoint, method-specific scenarios are produced:
+ *   PUT/PATCH  → mutation-recalc integration, boundary-values integration, contract, not-found
+ *   POST       → lifecycle integration (create + optional GET), contract, validation error
+ *   DELETE     → lifecycle integration (create + delete + 404), contract
+ *   GET /{id}  → contract, not-found
+ *   GET /coll  → contract + collection-list integration (create-then-GET) or contract-only
+ *
+ * Additionally, PUT/PATCH/DELETE methods get an auth-boundary scenario
+ * (category "security_boundary" → HIGH priority, not CRITICAL) so it
+ * lands in ADDITIONAL deterministically instead of depending on LLM
+ * supplement. GET is excluded (often public); POST is excluded because
+ * the security-boundary supplement tier covers it. Exception: execution
+ * endpoints (/execute, /run, /trigger, etc.) include auth-boundary for
+ * all non-GET methods (including POST) since they are high-value targets.
+ */
+export declare function draftDiffDirectScenarios(newEndpoints: Array<{
+    method: string;
+    path: string;
+}>, resourceGroups: Map<string, {
+    basePath: string;
+    methods: Set<string>;
+    paramPath?: string;
+}>, wsAuthType?: WorkspaceAuthType): DraftedScenario[];
+export {};

package/build/utils/scenarioDrafting.js

@@ -142,7 +142,7 @@ export function inferResourceRelationships(endpoints) {
     }
     return relationships;
 }
-export function draftScenariosFromEndpoints(endpoints, newEndpoints = [], wsAuthType, options = {}) {
+export function draftScenariosFromEndpoints(endpoints, newEndpoints = [], wsAuthType, options = {}, removedEndpoints = []) {
     const scenarios = [];
     const resourceGroups = new Map();
     for (const ep of endpoints) {
@@ -191,6 +191,28 @@ export function draftScenariosFromEndpoints(endpoints, newEndpoints = [], wsAuth
     }
     scenarios.push(...draftDiffDirectScenarios(newEndpoints, resourceGroups, wsAuthType));
     scenarios.push(...draftAttackSurfaceExpansionScenarios(endpoints, options.changedEndpoints ?? [], wsAuthType, options.securityRelevantDiff ?? false));
+    // 404-guard scenarios for removed endpoints — absence assertions confirming
+    // the endpoint is gone. Single-step contract tests, no chaining needed.
+    for (const ep of removedEndpoints) {
+        scenarios.push({
+            scenarioName: `verify-removed-${ep.method.toLowerCase()}-${ep.path.replace(/[^a-z0-9]+/gi, "-").replace(/^-|-$/g, "")}`,
+            description: `Verify ${ep.method} ${ep.path} returns 404 — endpoint was removed in this PR`,
+            category: "breaking_change",
+            priority: "high",
+            steps: [{
+                    order: 1,
+                    method: ep.method,
+                    path: ep.path,
+                    description: `${ep.method} ${ep.path} → 404 (endpoint removed)`,
+                    interactionType: "error",
+                    expectedStatusCode: 404,
+                }],
+            chainingKeys: [],
+            requiresAuth: false,
+            estimatedComplexity: "simple",
+            source: ScenarioSource.CodeInferred,
+        });
+    }
     return capScenarios(scenarios);
 }
 const MAX_TOTAL_SCENARIOS = 30;

package/build/utils/scenarioDrafting.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/utils/skyrampMdContent.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 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";

package/build/utils/sourceRouteExtractor.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Source-grounded route extraction — strategy 2 of the candidate UI page ladder.
+ *
+ * Given a repo path, walks router/App files with the TypeScript Compiler API
+ * to find route declarations in three forms:
+ *
+ *   1. React-style JSX route elements:
+ *      <Route path="/cart" element={<Cart/>} />
+ *      <SentryRoute path={WORKSPACE_URL} component={Workspaces} />
+ *
+ *   2. Vue Router object literals:
+ *      const routes = [{ path: '/login', component: Login }, …]
+ *
+ *   3. Directus `defineModule({ id, routes: [...] })`:
+ *      defineModule({ id: 'notifications', routes: [{ path: '', component: X }] })
+ *      → URL = "/notifications" (module id prefix + nested path)
+ *
+ * Path attribute values are resolved through:
+ *   - String literals (`path="/cart"`)
+ *   - Local const declarations (`const X = "/cart"; path={X}`)
+ *   - Cross-file imports + named exports (`import { X } from './constants'`)
+ *   - Template literals composed of resolvable parts (`` `${BASE}/foo` ``)
+ *
+ * Why TS Compiler API rather than regex: route declarations span multiple
+ * lines with attributes interleaved, paths reference constants that must be
+ * cross-file resolved, and tag names vary (Route, SentryRoute, PrivateRoute,
+ * …). The AST gives us the structure for free; regex would have to be
+ * deliberately permissive at the cost of false matches.
+ */
+/** A route declaration discovered in source. */
+export interface SourceRoute {
+    /** URL path string from the route declaration. */
+    path: string;
+    /** Component identifier referenced by `element={<X/>}` or `component: X`. */
+    componentName: string;
+    /** Resolved component source file (absolute path), if the import was found. */
+    componentFile?: string;
+    /** Router file the declaration was found in (absolute path). */
+    declaredIn: string;
+}
+/**
+ * Walk the repo, parse candidate router files, return all route declarations.
+ *
+ * Best-effort by design: a parse error on one file shouldn't block discovery
+ * across the rest. Returns empty when no router files match — callers should
+ * treat that as "strategy 2 inapplicable" and fall through to the next one.
+ */
+export declare function extractSourceRoutes(repositoryPath: string): SourceRoute[];

package/build/utils/sourceRouteExtractor.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/utils/telemetry.d.ts

@@ -0,0 +1,32 @@
+export declare function getEntryPoint(): string;
+/**
+ * Detects the CI/CD platform from environment variables.
+ * Returns undefined when not running in CI.
+ */
+export declare function getCIPlatform(): string | undefined;
+export interface RepositoryInfo {
+    repository?: string;
+    repositoryOwner?: string;
+}
+/**
+ * Parses "owner/repo" out of a git remote URL. Handles both HTTPS
+ * (https://github.com/owner/repo.git) and SSH (git@github.com:owner/repo.git)
+ * forms, with or without the trailing ".git". Returns undefined if no match.
+ */
+export declare function parseRepositoryFromRemoteUrl(remoteUrl: string): RepositoryInfo | undefined;
+/**
+ * Resolves source-repository attribution for telemetry, segmenting usage per
+ * customer/repo.
+ *
+ * - In GitHub Actions (testbot), reads GITHUB_REPOSITORY / GITHUB_REPOSITORY_OWNER
+ *   which the MCP subprocess inherits — fast, no shelling out.
+ * - In local/IDE usage, derives "owner/repo" from `git remote get-url origin`.
+ *   The lookup directory is the caller-supplied `cwd` (a tool's repositoryPath
+ *   or workspacePath) when available, since the MCP server's own process.cwd()
+ *   is set by the IDE and is not necessarily the user's repo. Falls back to
+ *   process.cwd(). Cached per directory so git is invoked at most once each.
+ *
+ * Returns an empty object when attribution can't be determined (e.g. not a git
+ * repo, no origin remote).
+ */
+export declare function getRepositoryInfo(cwd?: string): Promise<RepositoryInfo>;

package/build/utils/telemetry.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/utils/trace-parser.d.ts

@@ -0,0 +1,32 @@
+export type TraceFormat = "skyramp" | "har" | "unknown";
+interface ParsedTraceEntry {
+    method: string;
+    path: string;
+    statusCode: number;
+    requestHeaders?: Record<string, string>;
+    requestBody?: Record<string, any>;
+    queryParams?: Record<string, string[]>;
+    responseHeaders?: Record<string, string>;
+    responseBody?: Record<string, any>;
+    timestamp: string;
+}
+interface ParsedUserFlow {
+    flowId: string;
+    entries: ParsedTraceEntry[];
+    durationMs: number;
+}
+export interface TraceParseResult {
+    entries: ParsedTraceEntry[];
+    userFlows: ParsedUserFlow[];
+    format: TraceFormat;
+}
+export declare function parseTraceFile(filePath: string): Promise<TraceParseResult>;
+/**
+ * Discover trace JSON files in a repository path.
+ */
+export declare function discoverTraceFiles(repositoryPath: string): string[];
+/**
+ * Discover Playwright recording zip files in a repository path.
+ */
+export declare function discoverPlaywrightZips(repositoryPath: string): string[];
+export {};

package/build/utils/trace-parser.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Unit tests for trace-parser.ts — specifically the scanTraceArtifactDirs scoping
+ * introduced to prevent demo/fixture files (e.g. frontend/public/traces/) from being
+ * misidentified as testbot-generated traces.
+ */
+export {};

package/build/utils/uiPageEnumerator.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Programmatic UI page enumeration — translates "which frontend files changed"
+ * into "which URLs should the agent capture blueprints for."
+ *
+ * Replaces the prose-driven Task 0 strategy ladder in the testbot prompt with
+ * deterministic code so the candidate page list lives in the stateFile and is
+ * reusable across analyze_changes consumers (testbot, analyze_test_health,
+ * future blueprint-grounded recommenders).
+ *
+ * Strategies, tried in order:
+ *
+ *   Strategy 1 — Framework route grep
+ *     Translate file-system-routed component paths directly to URLs. Covers
+ *     Next.js (app/ and pages/), Nuxt / Vue Router file-based, and SvelteKit.
+ *     Gated on detection of a framework config file in the repo.
+ *
+ *   Strategy 2 — Source-grounded routes
+ *     Walks router/App files with the TS Compiler API for code-defined
+ *     route declarations like `<Route path="/cart" element={<Cart/>}>`.
+ *     Matches each route's component file OR declaration file against the
+ *     changed-file list (so router rewrites surface their routes even when
+ *     the component itself is unchanged). Handles React Router string-literal
+ *     paths, cross-file constant resolution, Vue Router object literals,
+ *     and Directus `defineModule` aggregation. See `sourceRouteExtractor.ts`.
+ *
+ *   Strategy 3 — Root fallback
+ *     Read the workspace's frontend baseUrl and treat it as the single
+ *     candidate page. Always available when a frontend service is configured.
+ */
+export type CandidateUiPageStrategy = "framework-route-grep" | "source-grounded-routes" | "dart-go-router" | "root-fallback";
+export interface CandidateUiPage {
+    /** Fully qualified URL (workspace baseUrl + framework-derived path). */
+    url: string;
+    /** Source files that suggested this page (for traceability). */
+    sourcedFrom: string[];
+    /** Which strategy enumerated it. */
+    strategy: CandidateUiPageStrategy;
+}
+/**
+ * File-system → URL mapping for filesystem-routed frameworks.
+ *
+ * Returns the URL path (no host) when the file is a route entrypoint, or
+ * null when the file isn't a route in any recognized convention.
+ *
+ * The `null` cases include component files used by routes (e.g. shared
+ * widgets in `components/`), API handlers (e.g. Next.js `pages/api/*`),
+ * and arbitrary `.ts`/`.js` modules under frontend directories. These
+ * are picked up by strategy 2 (import-graph walk, future) or by strategy
+ * 3 (root fallback).
+ */
+export declare function frameworkFileToUrlPath(filePath: string): string | null;
+/**
+ * Detect whether the repository is configured for filesystem-based routing.
+ *
+ * Strategy 1 maps file paths to URLs based on conventions (Next.js Pages
+ * Router, Nuxt, SvelteKit). Without a positive signal that the framework
+ * is actually configured, a repo that just *happens* to have a `pages/`
+ * directory (e.g. React with conventional layout, Vue with route-config
+ * code) produces false-positive URLs. This guard suppresses strategy 1
+ * for those repos so they fall through to root-fallback.
+ *
+ * Looks for framework config files in the repo root, common subdirectories,
+ * and the `frontendFiles[]`-derived candidate frontend roots.
+ */
+export declare function detectsFilesystemRouting(repositoryPath: string): boolean;
+/**
+ * Strategy 1 implementation. Filters frontend files through the framework
+ * route mapper; collects the URL paths that mapped successfully.
+ *
+ * Suppressed when the repo doesn't have a recognized filesystem-routing
+ * framework config — see `detectsFilesystemRouting`. Without that guard,
+ * repos with conventional `pages/` directories but code-defined routes
+ * (e.g. React with React Router) produce false-positive URLs.
+ */
+export declare function findCandidatePagesByFrameworkRoute(frontendFiles: string[], baseUrl: string, repositoryPath?: string): CandidateUiPage[];
+/**
+ * Strategy 2 implementation. Walks router/App files with the TS Compiler API
+ * to find route declarations (`<Route path="/cart" element={<Cart/>}>`),
+ * matches each declaration's component file against the changed-file list,
+ * and emits one CandidateUiPage per matching route.
+ *
+ * Slice 3a covers string-literal `path` attributes only — `path={CONST}` and
+ * Vue Router object literals are deferred to slice 3b.
+ *
+ * Returns empty when no route declarations match the changed files (which is
+ * also the right answer for SPAs without client-side routing — they fall
+ * through to root-fallback).
+ */
+export declare function findCandidatePagesBySourceRoute(frontendFiles: string[], baseUrl: string, repositoryPath: string): CandidateUiPage[];
+/**
+ * Strategy 2.5: walk the repo's Dart files for GoRoute(path: '...') calls.
+ * Gated on `hasFlutterSdkDep(repoPath)` so non-Flutter Dart projects (e.g.
+ * shelf_router servers) don't accidentally emit URLs.
+ *
+ * Diff-matching: each GoRoute references its screen widget via
+ * `builder:`/`pageBuilder:` (e.g. `AuthorsScreen`). The extractor resolves
+ * those identifiers through the route file's imports to absolute screen
+ * file paths. We surface only routes whose screen file appears in the
+ * changed-file list. Falls back to all-routes when no route's screen
+ * file matches — preserves coverage for "router untouched, screen edited"
+ * cases when the import-resolution heuristic doesn't find a match.
+ *
+ * Filters applied:
+ *   1. Drop redirect-only routes (`redirect:` with no `builder:`/`pageBuilder:`).
+ *      These have no UI to render — navigating there is wasted work.
+ *   2. Drop nested relative children (paths that don't start with `/`).
+ *      Without parent-path composition the URL is meaningless.
+ *
+ * Returns empty when the repo isn't Flutter or no GoRoute calls are
+ * found — caller falls through to root-fallback.
+ */
+export declare function findCandidatePagesByDartRoute(repositoryPath: string, baseUrl: string, frontendFiles: string[]): CandidateUiPage[];
+/**
+ * Strategy 3: when strategies 1+2 yield nothing, fall back to the workspace's
+ * frontend baseUrl as the single candidate page. The agent's downstream
+ * explore-and-discover step can then surface gated UI from the root.
+ *
+ * Returns null when the workspace has no recognizable frontend service.
+ */
+export declare function findRootFallbackPage(repositoryPath: string): Promise<CandidateUiPage | null>;
+/**
+ * Resolves the frontend service's baseUrl from the workspace config.
+ *
+ * Returns the baseUrl string with environment variable override precedence:
+ *   1. Per-service override: `SKYRAMP_TEST_SERVICE_URL_<NAME>` (where <NAME>
+ *      is the picked frontend service's serviceName, sanitized via
+ *      `sanitizeServiceName`)
+ *   2. Global override: `SKYRAMP_TEST_BASE_URL` (single service or all
+ *      services share one URL)
+ *   3. Static workspace.yml value: `api.baseUrl` from the picked frontend
+ *      service
+ *
+ * Returns null when no service has a usable URL.
+ *
+ * Exported (vs private) so analyze_changes and future tools can reuse the
+ * same selection without re-implementing it.
+ */
+export declare function pickFrontendBaseUrl(repositoryPath: string): Promise<string | null>;
+/**
+ * Run the strategy ladder in order: framework route grep (1) → source-grounded
+ * routes (2) → root fallback (3). Each strategy is consulted only if the
+ * previous one produced no candidates. Returns whatever the ladder produces
+ * (possibly empty if the workspace has no frontend baseUrl AND none of the
+ * earlier strategies matched).
+ */
+export declare function enumerateCandidateUiPages(repositoryPath: string, frontendFiles: string[]): Promise<CandidateUiPage[]>;

package/build/utils/uiPageEnumerator.js

@@ -311,31 +311,38 @@ export async function findRootFallbackPage(repositoryPath) {
     };
 }
 /**
- * Resolves the frontend service's baseUrl from the workspace config.
+ * Mirror of testbot.git src/services.ts exportServiceBaseUrlEnvVars sanitize().
+ * Keep in sync with that function (separate repo, cannot share code).
+ *
+ * Transforms a service name into the corresponding env var suffix:
+ * `supabase-nextjs` → `SUPABASE_NEXTJS`
+ * `my.app` → `MY_APP`
+ * `proto://app` → `PROTO___APP`
+ */
+function sanitizeServiceName(name) {
+    return name.toUpperCase().replace(/[-.:\/]/g, "_");
+}
+/**
+ * Extracted from pickFrontendBaseUrl: returns the chosen frontend service
+ * object (not the URL). Implements the original heuristics unchanged.
  *
  * Heuristics, in order:
- *   1. Service whose `serviceName` ends with `-frontend` or contains `frontend`
+ *   1. Service whose `serviceName` contains a frontend token (`frontend`,
+ *      `ui`, `app`, or `web`) as a `-`/`_`-delimited word
  *   2. Service whose `language` is `typescript` / `javascript` AND whose
  *      `framework` is one of the common UI frameworks (react, vue, svelte,
  *      next, nuxt, etc.)
  *   3. First service with a defined `api.baseUrl`
  *
- * Returns the baseUrl string, or null when no service has a usable URL.
- *
- * Exported (vs private) so analyze_changes and future tools can reuse the
- * same selection without re-implementing it.
+ * Returns the service object or null when no service has a usable URL.
  */
-export async function pickFrontendBaseUrl(repositoryPath) {
-    const config = await readWorkspaceConfigRaw(repositoryPath);
-    if (!config?.services || !Array.isArray(config.services))
-        return null;
-    const services = config.services;
+function pickFrontendService(services) {
     // Heuristic 1: serviceName signals frontend.
     const byName = services.find((s) => typeof s?.serviceName === "string" &&
         /(?:^|[-_])frontend(?:[-_]|$)|(?:^|[-_])ui(?:[-_]|$)|(?:^|[-_])app(?:[-_]|$)|(?:^|[-_])web(?:[-_]|$)/.test(s.serviceName.toLowerCase()) &&
         s?.api?.baseUrl);
     if (byName)
-        return byName.api.baseUrl;
+        return byName;
     // Heuristic 2: language + framework signal frontend.
     const FRONTEND_FRAMEWORKS = new Set([
         "react", "vue", "svelte", "next", "nextjs", "nuxt", "sveltekit",
@@ -349,10 +356,47 @@ export async function pickFrontendBaseUrl(repositoryPath) {
             s?.api?.baseUrl);
     });
     if (byFramework)
-        return byFramework.api.baseUrl;
+        return byFramework;
     // Heuristic 3: first service with a baseUrl.
     const anyBase = services.find((s) => s?.api?.baseUrl);
-    return anyBase?.api?.baseUrl ?? null;
+    return anyBase ?? null;
+}
+/**
+ * Resolves the frontend service's baseUrl from the workspace config.
+ *
+ * Returns the baseUrl string with environment variable override precedence:
+ *   1. Per-service override: `SKYRAMP_TEST_SERVICE_URL_<NAME>` (where <NAME>
+ *      is the picked frontend service's serviceName, sanitized via
+ *      `sanitizeServiceName`)
+ *   2. Global override: `SKYRAMP_TEST_BASE_URL` (single service or all
+ *      services share one URL)
+ *   3. Static workspace.yml value: `api.baseUrl` from the picked frontend
+ *      service
+ *
+ * Returns null when no service has a usable URL.
+ *
+ * Exported (vs private) so analyze_changes and future tools can reuse the
+ * same selection without re-implementing it.
+ */
+export async function pickFrontendBaseUrl(repositoryPath) {
+    const config = await readWorkspaceConfigRaw(repositoryPath);
+    if (!config?.services || !Array.isArray(config.services))
+        return null;
+    const picked = pickFrontendService(config.services);
+    // 1. Per-service override (multi-service, distinct URLs).
+    // readWorkspaceConfigRaw may fall back to unvalidated YAML, so serviceName
+    // is not guaranteed to be a string — guard before sanitizing.
+    if (typeof picked?.serviceName === "string") {
+        const perSvc = process.env[`SKYRAMP_TEST_SERVICE_URL_${sanitizeServiceName(picked.serviceName)}`]?.trim();
+        if (perSvc)
+            return perSvc;
+    }
+    // 2. Global override (single service / all services share a URL).
+    const global = process.env.SKYRAMP_TEST_BASE_URL?.trim();
+    if (global)
+        return global;
+    // 3. Static workspace.yml value.
+    return picked?.api?.baseUrl ?? null;
 }
 // ── Composer ────────────────────────────────────────────────────────────────
 /**

package/build/utils/uiPageEnumerator.test.d.ts

@@ -0,0 +1 @@
+export {};