@skyramp/mcp 0.2.5 → 0.2.7

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 {};