@skyramp/mcp 0.2.6 → 0.2.8-rc.1

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