@skyramp/mcp 0.2.5 → 0.2.7

package/build/utils/docker.test.js

@@ -1,5 +1,12 @@
+// @ts-nocheck - Jest ESM type inference issues
+import { jest } from "@jest/globals";
 // Mock logger before importing docker module
-jest.mock("./logger.js", () => ({
+const mockInspect = jest.fn();
+const mockGetImage = jest.fn(() => ({ inspect: mockInspect }));
+const mockFollowProgress = jest.fn();
+const mockPull = jest.fn();
+const mockModem = { followProgress: mockFollowProgress };
+jest.unstable_mockModule("./logger.js", () => ({
     logger: {
         debug: jest.fn(),
         info: jest.fn(),
@@ -7,18 +14,12 @@ jest.mock("./logger.js", () => ({
         warning: jest.fn(),
     },
 }));
-// Mock dockerode before importing docker module
-const mockInspect = jest.fn();
-const mockGetImage = jest.fn(() => ({ inspect: mockInspect }));
-const mockFollowProgress = jest.fn();
-const mockPull = jest.fn();
-const mockModem = { followProgress: mockFollowProgress };
 jest.mock("dockerode", () => jest.fn().mockImplementation(() => ({
     getImage: mockGetImage,
     pull: mockPull,
     modem: mockModem,
 })));
-import { dockerImageExistsLocally, pullDockerImage } from "./docker.js";
+const { dockerImageExistsLocally, pullDockerImage } = await import("./docker.js");
 // Helper: make docker.pull succeed (stream ends without error)
 function mockPullSuccess() {
     const fakeStream = {};
@@ -54,7 +55,7 @@ describe("dockerImageExistsLocally", () => {
     });
 });
 describe("pullDockerImage", () => {
-    const IMAGE = "skyramp/executor:v1.3.27";
+    const IMAGE = "skyramp/executor:v1.3.28";
     beforeEach(() => jest.clearAllMocks());
     describe("on amd64 host", () => {
         const originalArch = process.arch;

package/build/utils/featureFlags.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Feature flag helpers.
+ *
+ * Each helper in this module reads a `SKYRAMP_FEATURE_*` env var and returns
+ * a boolean. These helpers treat a flag as ON only when the env var is
+ * exactly `"1"`; anything else (unset, empty, "0", "true", "false", etc.) is
+ * treated as OFF.
+ */
+/**
+ * Gates BOTH consumer-side contract tests AND the SDK's "default mode"
+ * fallback (where omitting both `providerMode` and `consumerMode` causes the
+ * SDK to generate BOTH provider and consumer tests).
+ *
+ * `providerMode` itself is exposed regardless of this flag.
+ *
+ * When OFF (default):
+ *   - `skyramp_contract_test_generation` only exposes provider-mode
+ *     parameters in its input schema, and the tool description, validation,
+ *     and post-generation instructions all assume provider-only behavior.
+ *   - The SDK is always invoked with `providerMode: true`, so the
+ *     "neither mode set ⇒ generate both" default cannot leak through. Only
+ *     a provider contract test is ever generated.
+ *   - Testbot recommendation prompts no longer suggest `consumerMode: true`
+ *     contract tests.
+ *
+ * When ON (`SKYRAMP_FEATURE_CONTRACT_CONSUMER_MODE=1`):
+ *   - Restores the previous behavior: `consumerMode` / `consumerOutput` are
+ *     exposed on the input schema, recommendation prompts mention consumer
+ *     contract tests, and the SDK's "no mode set ⇒ generate both" default
+ *     is preserved.
+ */
+export declare function isContractConsumerModeEnabled(): boolean;
+/**
+ * Returns true when running inside a TestBot environment
+ * (SKYRAMP_FEATURE_TESTBOT=1).
+ */
+export declare function isTestbotEnabled(): boolean;

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

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

package/build/utils/gitStaging.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Check whether `child` is inside `parent` using resolved paths with
+ * a trailing separator to avoid prefix false positives (e.g. /tmp/test-repo2
+ * should not match /tmp/test-repo).
+ */
+export declare function isInsideDir(child: string, parent: string): boolean;
+/**
+ * In cross-repo mode, redirects an outputDir to be under the test repo clone
+ * if it isn't already. Returns the original path unchanged when testsRepoDir
+ * is unset or the path is already inside it.
+ */
+export declare function resolveOutputDir(outputDir: string, testsRepoDir: string | undefined): string;
+/**
+ * Stages a file path an MCP tool just wrote into the git index by
+ * running `git add -- <path>`.
+ *
+ * Automatically detects the git root of the target path so that staging
+ * works correctly in cross-repo mode (test repo clone separate from the
+ * source repo).
+ *
+ * Gated by the SKYRAMP_FEATURE_TESTBOT=1 env var, which is set only
+ * inside a testbot CI run.
+ */
+export declare function stageGeneratedPaths(filePath: string, cwd?: string): Promise<void>;

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

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

package/build/utils/gitStaging.test.js

@@ -1,4 +1,7 @@
-jest.mock("./logger.js", () => ({
+import { jest } from "@jest/globals";
+const execFileMock = jest.fn();
+const execFileSyncMock = jest.fn();
+jest.unstable_mockModule("./logger.js", () => ({
     logger: {
         debug: jest.fn(),
         info: jest.fn(),
@@ -6,14 +9,17 @@ jest.mock("./logger.js", () => ({
         error: jest.fn(),
     },
 }));
-jest.mock("fs", () => ({
+jest.unstable_mockModule("fs", () => ({
+    default: {
+        statSync: (p) => ({
+            isDirectory: () => !p.includes("."),
+        }),
+    },
     statSync: (p) => ({
         isDirectory: () => !p.includes("."),
     }),
 }));
-const execFileMock = jest.fn();
-const execFileSyncMock = jest.fn();
-jest.mock("child_process", () => ({
+jest.unstable_mockModule("child_process", () => ({
     execFile: (cmd, args, opts, cb) => {
         const result = execFileMock(cmd, args, opts);
         const cbErr = result && typeof result === "object" && "err" in result
@@ -26,8 +32,8 @@ jest.mock("child_process", () => ({
     },
     execFileSync: (cmd, args, opts) => execFileSyncMock(cmd, args, opts),
 }));
-import { stageGeneratedPaths } from "./gitStaging.js";
-import { logger } from "./logger.js";
+const { stageGeneratedPaths } = await import("./gitStaging.js");
+const { logger } = await import("./logger.js");
 const loggerInfoMock = logger.info;
 let originalTestbotEnv;
 beforeAll(() => {

package/build/utils/httpDefaults.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Shared HTTP method defaults used across scenario drafting and test generation.
+ */
+/**
+ * Returns the conventional success status code for a given HTTP method.
+ *   POST   → 201 Created
+ *   DELETE → 204 No Content
+ *   other  → 200 OK
+ */
+export declare function inferExpectedStatus(method: string): number;

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

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

package/build/utils/initAgent.d.ts

@@ -0,0 +1,36 @@
+import { WORKER_DOCKER_IMAGE } from "./versions.js";
+export { WORKER_DOCKER_IMAGE };
+/**
+ * Install or refresh SKYRAMP_MD_CONTENT at global skill discovery paths only (~/.claude, ~/.cursor, ~/.github/skills).
+ * No workspace path required. Creates files if missing; overwrites if content differs.
+ */
+export declare function ensureSkyrampMdInstalled(): Promise<void>;
+/**
+ * Skyramp init:
+ * install/refresh global skill files (~/.claude, ~/.cursor, ~/.github/skills) (errors logged but do not block init),
+ * check which images are missing, then kick off any needed pulls in the background and return immediately.
+ * Deduplication for the MCP oninitialized path is handled by registerInitTriggerOnMCPInitialized in this module.
+ *
+ * Pull improvements over the previous SkyrampClient.initAgent() FFI approach:
+ * - Skip-if-present: each image is checked independently via a fast daemon inspect (~5ms)
+ *   before any pull is attempted, avoiding unnecessary network calls.
+ * - Pull only what is missing: if one image is already present, only the other is pulled.
+ *   Previously both images were always pulled regardless.
+ * - Parallel pulls: missing images are pulled concurrently via Promise.all, halving
+ *   wall-clock time when both need to be downloaded.
+ * - Arch-aware: pull platform is detected from process.arch (linux/arm64 on Apple Silicon,
+ *   linux/amd64 otherwise) with an automatic amd64 fallback if no arm64 manifest exists
+ *   (e.g. skyramp/executor is amd64-only; skyramp/worker supports both).
+ * - No FFI overhead: direct Dockerode calls replace the Go shared-library bridge,
+ *   removing the cost of loading the .so and marshalling output through a C string.
+ * - Cleaner error propagation: structured errors from Dockerode replace parsing a
+ *   stringified Go output from the C FFI boundary.
+ */
+export declare function initCheck(): Promise<void>;
+/**
+ * Runs initCheck asynchronously after the MCP handshake completes.
+ * Prevents duplicate concurrent runs and skips future runs after a successful init.
+ * If initCheck fails, a later call can retry within the same process.
+ * Assign to server.server.oninitialized in main().
+ */
+export declare function registerInitTriggerOnMCPInitialized(): Promise<void>;

package/build/utils/language-helper.d.ts

@@ -0,0 +1,6 @@
+export interface LanguageStepsParams {
+    language: string;
+    testType?: string;
+    framework?: string;
+}
+export declare function getLanguageSteps(params: LanguageStepsParams): string;

package/build/utils/logger.d.ts

@@ -0,0 +1,11 @@
+export declare class McpLogger {
+    private loggerName;
+    constructor(loggerName?: string);
+    private sendLogMessage;
+    debug(message: string, data?: any): void;
+    info(message: string, data?: any): void;
+    warning(message: string, data?: any): void;
+    error(message: string, data?: any): void;
+    critical(message: string, data?: any): void;
+}
+export declare const logger: McpLogger;

package/build/utils/normalizeParams.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Normalize tool parameters to handle common LLM mistakes:
+ * - Case-insensitive language/framework values
+ * - Common parameter name aliases
+ */
+/**
+ * Normalize language and framework to lowercase accepted values.
+ */
+export declare function normalizeLanguageParams(params: Record<string, any>): void;
+/**
+ * Resolve common parameter name aliases that LLMs use.
+ * e.g., zipPath -> playwrightInput, testFilePath -> testFile
+ */
+export declare function resolveParamAliases(params: Record<string, any>, aliases: Record<string, string>): void;

package/build/utils/normalizeSkyrampImports.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Ensure `expect` is imported from `@skyramp/skyramp` rather than `@playwright/test`.
+ * - Strips `expect` from any `@playwright/test` import (keeps other identifiers).
+ * - If the file uses `expect(...)`, ensures an `@skyramp/skyramp` import carries `expect`.
+ * Returns the original string if no rewrite was needed.
+ */
+export declare function normalizeSkyrampExpectImport(source: string): string;
+/**
+ * Normalize the `expect` import in a file on disk. No-op if the file is missing,
+ * unreadable, or already correct. Errors are swallowed — this is a safety net,
+ * not a blocking step.
+ */
+export declare function normalizeSkyrampImportsInFile(testFile: string | undefined): void;

package/build/utils/pr-comment-parser.d.ts

@@ -0,0 +1,31 @@
+/**
+ * PR Comment Parser — extracts TestBot history from GitHub PR comments.
+ *
+ * Parses previous Skyramp TestBot comments on a PR to build context
+ * about what has already been recommended, implemented, and tested.
+ * This prevents re-recommendations and enables contextual awareness
+ * across the PR lifecycle.
+ */
+export interface PRTestContext {
+    prNumber: number;
+    previousRecommendations: Array<{
+        testType: string;
+        endpoint: string;
+        scenarioName?: string;
+        status: "recommended" | "implemented" | "dismissed";
+        commentId: string;
+    }>;
+    implementedTestFiles: string[];
+    executionResults: Array<{
+        testFile: string;
+        status: "pass" | "fail" | "skipped";
+        timestamp: string;
+    }>;
+}
+/**
+ * Fetch and parse PR comments to build TestBot history context.
+ *
+ * Uses the `gh` CLI (available in CI and local dev environments with
+ * GitHub CLI installed). Falls back gracefully if `gh` is unavailable.
+ */
+export declare function parsePRComments(repoOwner: string, repoName: string, prNumber: number, _token?: string): Promise<PRTestContext>;

package/build/utils/pr-comment-parser.test.d.ts

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

package/build/utils/pr-comment-parser.test.js

@@ -1,9 +1,10 @@
-import { parsePRComments } from "./pr-comment-parser.js";
-import { execFileSync } from "child_process";
-jest.mock("child_process", () => ({
-    execFileSync: jest.fn(),
+import { jest } from "@jest/globals";
+// Mock child_process before importing the module under test
+const mockedExecFileSync = jest.fn();
+jest.unstable_mockModule("child_process", () => ({
+    execFileSync: mockedExecFileSync,
 }));
-const mockedExecFileSync = execFileSync;
+const { parsePRComments } = await import("./pr-comment-parser.js");
 // ---------------------------------------------------------------------------
 // Fixture helpers — build PR comment bodies matching the real renderReport()
 // output wrapped in the progress comment from testbot/src/progress.ts.

package/build/utils/projectMetadata.d.ts

@@ -0,0 +1,15 @@
+export type ProjectType = "rest-api" | "frontend" | "full-stack" | "microservices" | "library" | "cli" | "other";
+export type DeploymentPattern = "microservices" | "full-stack" | "containerized-monolith" | "traditional" | "unknown";
+export interface ProjectMeta {
+    projectType: ProjectType;
+    primaryLanguage: string;
+    primaryFramework: string;
+    deploymentPattern: DeploymentPattern;
+    languages: string[];
+    frameworks: string[];
+    runtime: string;
+    isContainerized: boolean;
+    hasDockerCompose: boolean;
+    hasCiCd: boolean;
+}
+export declare function detectProjectMetadata(repositoryPath: string): ProjectMeta;

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

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

package/build/utils/proxy-terminal.d.ts

@@ -0,0 +1,2 @@
+export default function openProxyTerminal(): Promise<void>;
+export declare function closeProxyTerminal(): Promise<void>;

package/build/utils/repoScanner.d.ts

@@ -0,0 +1,27 @@
+export interface ScannedEndpoint {
+    path: string;
+    methods: string[];
+    sourceFile: string;
+}
+/**
+ * Returns the relative paths of entry-point files that define the routing
+ * hierarchy for this repository. The LLM reads these files in Step 1.5 to
+ * trace router/module nesting and build an authoritative path resolution table.
+ *
+ * Intentionally returns only file paths — no extracted lines. Static regex
+ * extraction is fragile and framework-specific; the LLM reads the files directly
+ * and understands any framework's routing syntax.
+ */
+export declare function grepRouterMountingContext(repositoryPath: string): string[];
+/**
+ * Return relative paths of all source files that are likely to define API
+ * routes. Two-pass strategy:
+ *   1. Fast: filename matches ROUTE_FILE_PATTERN (no file I/O needed).
+ *   2. Content: files not matched by name are read and checked for both a
+ *      URL-path literal AND an HTTP method registration. This covers any
+ *      framework the filename filter misses — Axum, Ktor, .NET, Hono, etc.
+ * Result is capped at MAX_CANDIDATE_FILES to keep the LLM prompt bounded.
+ */
+export declare function findCandidateRouteFiles(repositoryPath: string): string[];
+export declare function scanAllRepoEndpoints(repositoryPath: string): ScannedEndpoint[];
+export declare function scanRelatedEndpoints(repositoryPath: string, changedFiles: string[]): ScannedEndpoint[];

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

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

package/build/utils/routeParsers.d.ts

@@ -0,0 +1,63 @@
+import { BranchDiffData } from "./branchDiff.js";
+import type { ScannedEndpoint } from "./repoScanner.js";
+export interface ParsedDiffEndpoint {
+    method: string;
+    path: string;
+    sourceFile: string;
+}
+export declare function nextjsFileToApiPath(filePath: string): string | null;
+export declare const UI_FILE_EXTENSIONS: readonly ["tsx", "jsx", "vue", "svelte", "html", "xml"];
+export declare const UI_FILE_GIT_PATHSPEC: string;
+export declare const UI_FILE_EXTENSIONS_PIPED: string;
+export declare function parseRouteLine(line: string, sourceFile: string): ParsedDiffEndpoint | null;
+/**
+ * Scan all route definitions in a single source file, combining prefix declarations
+ * with method-level annotations. Two orthogonal state machines run in parallel:
+ *
+ * 1. Class-prefix (Spring, NestJS, ASP.NET, Kotlin):
+ *    @Controller/@RestController/@RequestMapping (class level) + class declaration →
+ *    activates classPrefix, applied to all @Get/@Post/@GetMapping etc. below.
+ *
+ * 2. Router-variable prefix (FastAPI, Flask Blueprint):
+ *    varName = APIRouter(prefix=...) or Blueprint(url_prefix=...) — handles both
+ *    single-line and multi-line declarations — maps the variable name to its prefix.
+ *    Applied when @varName.method(...) is seen.
+ *
+ * Falls back to pure parseRouteLine for all other frameworks (Express inline, Gin,
+ * Rails, Laravel, Actix, Hapi, Go stdlib, etc.), which remain unaffected.
+ */
+export declare function parseFileEndpoints(content: string, sourceFile: string): ParsedDiffEndpoint[];
+export declare const SKIP_PATH_SEGMENTS: Set<string>;
+/**
+ * Extract the primary resource key from an endpoint path for use as a dedup key.
+ *
+ * For top-level resources (e.g. "/api/v1/orders/{id}") returns the resource name ("orders").
+ * For sub-resources (e.g. "/orders/{id}/items") returns "orders_items" — including the
+ * parent prevents "/orders/{id}/items" and "/products/{id}/items" from colliding on "items".
+ */
+export declare function extractResourceFromPath(endpointPath: string): string;
+export interface ClassifiedEndpoints {
+    /** Endpoints in scanned catalog whose sourceFile is in changedFiles (not new/deleted). */
+    changedEndpoints: ScannedEndpoint[];
+    /** Endpoints whose sourceFile is in a newly-created file. */
+    newEndpoints: ScannedEndpoint[];
+    /** Endpoints whose sourceFile is in a deleted file (recovered from base branch). */
+    removedEndpoints: ScannedEndpoint[];
+    /** Changed files that don't map to any scanned endpoint. */
+    unmatchedFiles: string[];
+    changedFiles: string[];
+    currentBranch: string;
+    baseBranch: string;
+    affectedServices: string[];
+}
+/**
+ * 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`.
+ */
+export declare function classifyEndpointsByChangedFiles(diffData: BranchDiffData, scannedEndpoints: ScannedEndpoint[], deletedFileEndpoints?: ScannedEndpoint[]): ClassifiedEndpoints;

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): 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.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 {};