@skyramp/mcp 0.3.2-rc.pom-3 → 0.3.2

package/build/tools/generateEnrichedIntegrationTestTool.js

@@ -0,0 +1,235 @@
+import { z } from "zod";
+import { SkyrampClient } from "@skyramp/skyramp";
+import { logger } from "../utils/logger.js";
+import { RuntimeEnvironment, runtimeEnvironmentInputSchema } from "../types/TestTypes.js";
+import { injectMockImports, isSupportedMockEnrichmentLanguage } from "./enrichTestWithMocksTool.js";
+import { isAuthorizationHeaderName } from "../utils/workspaceAuth.js";
+import { WORKER_CONTROL_PORT } from "../utils/versions.js";
+import * as fs from "fs";
+import * as path from "path";
+const TOOL_NAME = "skyramp_generate_enriched_integration_test";
+const enrichedIntegrationTestSchema = {
+    scenarioFile: z
+        .string()
+        .describe("Absolute path to the scenario JSON file (from skyramp_batch_scenario_test_generation). Used as trace input for integration test generation."),
+    mockFiles: z
+        .array(z.string())
+        .describe("Absolute paths to the generated mock files (from skyramp_mock_generation or skyramp_batch_mock_generation) that this test needs."),
+    scenarioName: z
+        .string()
+        .describe("Human-readable scenario name (e.g., order-happy-path). Used as the SCENARIO_NAME constant in the enriched test."),
+    outputDir: z
+        .string()
+        .describe("Absolute path to the directory where the test file will be written."),
+    output: z
+        .string()
+        .optional()
+        .describe("Output test file name (e.g., order_happy_path_integration_test.py). Derived from scenario if omitted."),
+    runtime: runtimeEnvironmentInputSchema
+        .optional()
+        .default(RuntimeEnvironment.DOCKER)
+        .describe("Runtime environment: 'docker' or 'k8s' (also accepts 'kubernetes'). Defaults to docker."),
+    dockerNetwork: z
+        .string()
+        .optional()
+        .describe("Docker network name for the test runtime."),
+    dockerWorkerPort: z
+        .number()
+        .int()
+        .min(0)
+        .max(65535)
+        .optional()
+        .describe("Skyramp worker control port the generated client connects to. Defaults to 35142 (the local-dev compose worker's published port)."),
+    authHeader: z
+        .string()
+        .optional()
+        .describe("HTTP header that carries the auth credential (e.g., Authorization, X-Api-Key)."),
+    authScheme: z
+        .string()
+        .optional()
+        .describe("Auth scheme prefix (e.g., Bearer). Mapped to authType for the backend."),
+    language: z
+        .string()
+        .optional()
+        .describe("Programming language for the generated test. Automatic mock enrichment supports Python, TypeScript, JavaScript, and Java."),
+    framework: z
+        .string()
+        .optional()
+        .describe("Test framework (e.g., pytest, playwright)."),
+    traceComments: z
+        .array(z.string())
+        .optional()
+        .describe("Optional trace comments showing how mock values flow to assertions."),
+};
+/**
+ * skyramp_generate_enriched_integration_test
+ *
+ * Combines integration test generation (from a scenario file) and mock enrichment
+ * into a single atomic operation. Eliminates the need to call
+ * skyramp_integration_test_generation and skyramp_enrich_test_with_mocks separately.
+ */
+export function registerGenerateEnrichedIntegrationTestTool(server) {
+    server.registerTool(TOOL_NAME, {
+        description: "Generate an integration test from a scenario file AND enrich it with mock imports in one step. " +
+            "Combines skyramp_integration_test_generation + mock enrichment into a single call. " +
+            "Use this after skyramp_batch_scenario_test_generation and skyramp_batch_mock_generation when the target test language is Python, TypeScript, JavaScript, or Java.",
+        inputSchema: enrichedIntegrationTestSchema,
+    }, async (params) => {
+        return executeGenerateEnrichedIntegrationTest(params);
+    });
+}
+export async function executeGenerateEnrichedIntegrationTest(params) {
+    const { scenarioFile, mockFiles, scenarioName, outputDir, output, runtime, dockerNetwork, dockerWorkerPort, authHeader, authScheme, language, framework, traceComments, } = params;
+    try {
+        const resolvedLanguage = (language ?? "python").toLowerCase();
+        if (!isSupportedMockEnrichmentLanguage(resolvedLanguage)) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `**Error:** Mock enrichment for ${resolvedLanguage} tests is not supported by this combined tool. ` +
+                            "Supported languages: python, typescript, javascript, java. " +
+                            "Use `skyramp_integration_test_generation` + `skyramp_enrich_test_with_mocks` separately if your language is listed but enrichment fails.",
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // Step 1b: Validate scenarioFile exists
+        if (!fs.existsSync(scenarioFile)) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `**Error:** Scenario file not found: ${scenarioFile}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // Step 1b: Validate mock files exist
+        const missingFiles = mockFiles.filter((f) => !fs.existsSync(f));
+        if (missingFiles.length > 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `**Error:** Mock files not found:\n` +
+                            missingFiles.map((f) => `  - ${f}`).join("\n") +
+                            `\n\nGenerate them first with \`skyramp_batch_mock_generation\`.`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // Step 2: Generate the integration test
+        // Normalize auth params: the Go CLI treats --auth-type and --auth-header as
+        // mutually exclusive when authHeader is the standard Authorization header.
+        // Mirror TestGenerationService.executeGeneration() normalization:
+        // if authScheme is set and authHeader is Authorization, use authType only.
+        let resolvedAuthHeader = authHeader;
+        const resolvedAuthType = authScheme;
+        if (resolvedAuthType !== undefined && isAuthorizationHeaderName(resolvedAuthHeader || "")) {
+            resolvedAuthHeader = undefined;
+        }
+        const client = new SkyrampClient();
+        const result = await client.generateRestTest({
+            traceFilePath: scenarioFile,
+            outputDir,
+            output,
+            runtime: runtime ?? RuntimeEnvironment.DOCKER,
+            force: true,
+            dockerNetwork,
+            dockerWorkerPort: (dockerWorkerPort ?? WORKER_CONTROL_PORT).toString(),
+            authHeader: resolvedAuthHeader,
+            authType: resolvedAuthType,
+            language: resolvedLanguage,
+            framework,
+            testType: "integration",
+        });
+        // Check if generation succeeded
+        if (!result || !result.toLowerCase().includes("success")) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `**Error:** Integration test generation failed: ${result || "no output from backend"}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // Step 3: Determine the test file path and read it
+        const testFileName = output || deriveTestFileName(scenarioFile, resolvedLanguage);
+        const testFilePath = path.join(outputDir, testFileName);
+        if (!fs.existsSync(testFilePath)) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `**Error:** Generated test file not found at expected path: ${testFilePath}\n` +
+                            `Backend output: ${result}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const testContent = fs.readFileSync(testFilePath, "utf-8");
+        // Step 4: Enrich with mock imports
+        const enrichedContent = injectMockImports(testContent, testFilePath, scenarioName, mockFiles, traceComments, resolvedLanguage);
+        // Step 5: Write the enriched content back
+        fs.writeFileSync(testFilePath, enrichedContent);
+        logger.info(`Generated and enriched integration test: ${testFilePath}`, {
+            scenarioName,
+            mockFileCount: mockFiles.length,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        `**Integration test generated and enriched with mocks for scenario "${scenarioName}".**\n`,
+                        `**Test file:** ${testFilePath}`,
+                        `**Mock files imported:** ${mockFiles.length}`,
+                        ...mockFiles.map((f) => `  - ${path.basename(f)}`),
+                        `\nThe test is ready for execution with: \`skyramp_execute_test({testFile: "${testFilePath}", ...})\``,
+                    ].join("\n"),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        logger.error(`Failed to generate enriched integration test: ${error.message}`);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `**Failed to generate enriched integration test:** ${error.message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}
+function deriveTestFileName(scenarioFile, language) {
+    const base = path.basename(scenarioFile, ".json");
+    const name = base.replace(/^scenario_/, "").replace(/[^a-zA-Z0-9]/g, "_");
+    const normalizedLanguage = language?.toLowerCase();
+    if (normalizedLanguage === "typescript") {
+        return `${name}_integration_test.spec.ts`;
+    }
+    if (normalizedLanguage === "javascript") {
+        return `${name}_integration_test.spec.js`;
+    }
+    if (normalizedLanguage === "java") {
+        return `${toPascalCase(name)}IntegrationTest.java`;
+    }
+    return `${name}_integration_test.py`;
+}
+function toPascalCase(value) {
+    return value
+        .split(/[^a-zA-Z0-9]+/)
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join("");
+}

package/build/tools/localDevWorkerComposeTool.d.ts

@@ -0,0 +1,24 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export interface WorkerComposeResult {
+    baseComposeFile: string;
+    overrideFile: string;
+    dockerNetwork: string;
+    workerPort: number;
+    composeFilePrefix: string;
+}
+/**
+ * Generate the worker compose override and return the resolved network name and
+ * the `-f` prefix for `docker compose` commands. Throws on a missing compose file
+ * or if Docker is not running.
+ */
+export declare function setupLocalDevWorker(repositoryPath: string, composeFile?: string, thirdPartyHosts?: string[]): WorkerComposeResult;
+/**
+ * Deterministically set up the Skyramp worker as a Docker Compose service for
+ * the local-dev workflow.
+ *
+ * This replaces the SDK's imperative worker spawn (which raced onto the wrong
+ * Docker network and leaked on teardown — Local-Dev Skill Findings #1, #9, #10).
+ * The worker becomes a compose service via a generated override file, so it joins
+ * the SUT's network declaratively and is removed by `docker compose down`.
+ */
+export declare function registerLocalDevWorkerComposeTool(server: McpServer): void;

package/build/tools/localDevWorkerComposeTool.js

@@ -0,0 +1,264 @@
+import { z } from "zod";
+import * as path from "path";
+import * as fs from "fs";
+import { execSync } from "child_process";
+import yaml from "js-yaml";
+import { AnalyticsService } from "../services/AnalyticsService.js";
+import { WORKER_DOCKER_IMAGE, WORKER_CONTROL_PORT } from "../utils/versions.js";
+import { logger } from "../utils/logger.js";
+const TOOL_NAME = "skyramp_setup_local_dev_worker";
+// Relative path (under the repo) where the generated worker override is written.
+const OVERRIDE_REL_PATH = ".skyramp/skyramp.worker.compose.yml";
+/**
+ * Normalize and validate third-party host entries.
+ * - Trims whitespace from each entry
+ * - Filters out empty strings
+ * - Deduplicates
+ * - Rejects entries containing `://`, `/`, or `:` (scheme, path, or port)
+ *
+ * Returns the cleaned array, or throws on invalid entries.
+ */
+function normalizeThirdPartyHosts(hosts) {
+    const trimmed = hosts.map((h) => h.trim()).filter(Boolean);
+    const unique = [...new Set(trimmed)];
+    const invalid = unique.filter((h) => h.includes("://") || h.includes("/") || h.includes(":"));
+    if (invalid.length > 0) {
+        throw new Error(`Invalid thirdPartyHosts — entries must be bare hostnames without scheme, path, or port. ` +
+            `Got: ${invalid.join(", ")}`);
+    }
+    return unique;
+}
+const BASE_COMPOSE_CANDIDATES = [
+    "docker-compose.yml",
+    "docker-compose.yaml",
+    "compose.yml",
+    "compose.yaml",
+];
+/**
+ * Docker Compose project name derivation: lowercase the directory basename and
+ * strip characters outside [a-z0-9_-] (Compose's normalization). COMPOSE_PROJECT_NAME
+ * overrides it when set. The default network is then `<project>_<networkKey>`, or
+ * `<project>_default` when the compose file declares no named networks.
+ */
+function deriveProjectName(composeDir, env = process.env) {
+    const override = env.COMPOSE_PROJECT_NAME?.trim();
+    if (override)
+        return override;
+    return path
+        .basename(composeDir)
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]/g, "");
+}
+/** Resolve the base compose file: explicit path wins, else discover at repo root. */
+function resolveBaseCompose(repositoryPath, composeFile) {
+    if (composeFile) {
+        const abs = path.isAbsolute(composeFile)
+            ? composeFile
+            : path.join(repositoryPath, composeFile);
+        return fs.existsSync(abs) ? abs : undefined;
+    }
+    for (const candidate of BASE_COMPOSE_CANDIDATES) {
+        const abs = path.join(repositoryPath, candidate);
+        if (fs.existsSync(abs))
+            return abs;
+    }
+    return undefined;
+}
+/**
+ * Build the worker override compose document. The worker joins the same named
+ * network(s) the base declares (so it shares the SUT's network for DNS-alias
+ * hijacking at mock-apply time); when the base declares none, the worker joins
+ * the implicit `default` network like every other service. Only the control
+ * port (35142) is published to the host — mock ports stay internal to the
+ * docker network.
+ */
+function buildOverrideDoc(networkKeys, thirdPartyHosts) {
+    const workerService = {
+        image: WORKER_DOCKER_IMAGE,
+        volumes: [
+            "skyramp:/etc/skyramp",
+            "/var/run/docker.sock:/var/run/docker.sock",
+        ],
+        ports: [`127.0.0.1:${WORKER_CONTROL_PORT}:${WORKER_CONTROL_PORT}`],
+        restart: "always",
+    };
+    const doc = {
+        services: { skyramp: workerService },
+        volumes: { skyramp: null },
+    };
+    if (networkKeys.length > 0 || thirdPartyHosts?.length) {
+        // When third-party hosts are provided, the worker needs network aliases
+        // so Docker DNS resolves the FQDN to the worker container. This is how
+        // mocks intercept traffic to external services (e.g., www.google.com).
+        const nets = networkKeys.length > 0 ? networkKeys : ["default"];
+        const networkConfig = {};
+        for (const key of nets) {
+            if (thirdPartyHosts?.length) {
+                networkConfig[key] = { aliases: [...thirdPartyHosts] };
+            }
+            else {
+                networkConfig[key] = {};
+            }
+        }
+        workerService.networks = networkConfig;
+        doc.networks = Object.fromEntries(nets.map((k) => [k, {}]));
+    }
+    return doc;
+}
+/**
+ * Resolve the actual Docker network name Compose uses for `key`:
+ * - an explicit `name:` is used verbatim (NOT project-scoped),
+ * - `external: true` networks are pre-existing and not project-scoped
+ *   (use `external.name` for the legacy form, else the key),
+ * - otherwise Compose prefixes the project: `<project>_<key>`.
+ */
+function resolveNetworkName(project, key, def) {
+    const d = def ?? {};
+    if (typeof d.name === "string" && d.name.length > 0)
+        return d.name;
+    if (d.external) {
+        if (typeof d.external === "object" && d.external.name) {
+            return d.external.name;
+        }
+        return key;
+    }
+    return `${project}_${key}`;
+}
+/**
+ * Verify that the Docker daemon is reachable.
+ * Throws with a clear, actionable message so the agent stops immediately
+ * instead of spending turns manually debugging Docker connectivity.
+ *
+ * Does NOT switch Docker contexts — that can break a working setup when the
+ * active context differs from `default` but Docker is accessible via symlink.
+ */
+function checkDockerReady() {
+    try {
+        execSync("docker info", { stdio: "pipe", timeout: 15_000 });
+        return; // Docker is reachable.
+    }
+    catch {
+        // Docker not reachable on current context/config.
+    }
+    throw new Error("Docker daemon is not running or not reachable. " +
+        "Start Docker Desktop and retry. " +
+        "Do NOT attempt to debug Docker connectivity, try alternative socket paths, " +
+        "switch Docker contexts, or run `open -a Docker` — " +
+        "report this as a blocking environment error and stop.");
+}
+/**
+ * Generate the worker compose override and return the resolved network name and
+ * the `-f` prefix for `docker compose` commands. Throws on a missing compose file
+ * or if Docker is not running.
+ */
+export function setupLocalDevWorker(repositoryPath, composeFile, thirdPartyHosts) {
+    // Fail fast if Docker is not available — prevents the agent from proceeding
+    // with false confidence and then spending turns debugging Docker manually.
+    // Skipped when SKIP_DOCKER_CHECK=1 (unit tests that only validate YAML generation).
+    if (process.env.SKIP_DOCKER_CHECK !== "1") {
+        checkDockerReady();
+    }
+    const baseComposeFile = resolveBaseCompose(repositoryPath, composeFile);
+    if (!baseComposeFile) {
+        throw new Error(composeFile
+            ? `Compose file not found: ${composeFile}`
+            : `No docker-compose file found at ${repositoryPath} (looked for: ${BASE_COMPOSE_CANDIDATES.join(", ")}). Pass composeFile for a non-default location.`);
+    }
+    const parsed = yaml.load(fs.readFileSync(baseComposeFile, "utf-8"), {
+        schema: yaml.JSON_SCHEMA,
+    });
+    const networksObj = parsed?.networks ?? {};
+    const networkKeys = Object.keys(networksObj);
+    // Compose derives project name from the working directory (typically repo root),
+    // not from the compose file's directory. The plan instructs agents to run
+    // `docker compose` from repositoryPath.
+    const project = deriveProjectName(repositoryPath);
+    // The network the SDK client + executor target. First declared named network,
+    // else the implicit default network. Honor explicit `name:`/`external:` so the
+    // returned name matches the network Compose actually creates/uses.
+    const primaryKey = networkKeys[0] ?? "default";
+    const dockerNetwork = resolveNetworkName(project, primaryKey, networksObj[primaryKey]);
+    const overrideFile = path.join(repositoryPath, OVERRIDE_REL_PATH);
+    fs.mkdirSync(path.dirname(overrideFile), { recursive: true });
+    const overrideDoc = buildOverrideDoc(networkKeys, thirdPartyHosts);
+    const header = "# Generated by skyramp_setup_local_dev_worker — runs the Skyramp mock worker\n" +
+        "# as a compose service so it shares the SUT's network and is torn down with\n" +
+        "# the project. Layer it: docker compose -f <base> -f this up. Safe to delete.\n";
+    fs.writeFileSync(overrideFile, header + yaml.dump(overrideDoc, { lineWidth: -1 }), "utf-8");
+    return {
+        baseComposeFile,
+        overrideFile,
+        dockerNetwork,
+        workerPort: WORKER_CONTROL_PORT,
+        composeFilePrefix: `-f ${baseComposeFile} -f ${overrideFile}`,
+    };
+}
+/**
+ * Deterministically set up the Skyramp worker as a Docker Compose service for
+ * the local-dev workflow.
+ *
+ * This replaces the SDK's imperative worker spawn (which raced onto the wrong
+ * Docker network and leaked on teardown — Local-Dev Skill Findings #1, #9, #10).
+ * The worker becomes a compose service via a generated override file, so it joins
+ * the SUT's network declaratively and is removed by `docker compose down`.
+ */
+export function registerLocalDevWorkerComposeTool(server) {
+    server.registerTool(TOOL_NAME, {
+        description: `Set up the Skyramp mock worker as a Docker Compose service for the local-dev workflow (run this in the Deploy phase, before bringing the stack up).
+
+Writes a compose override file (.skyramp/skyramp.worker.compose.yml) that declares the worker as a service on the SUT's docker network, then returns the docker-compose \`-f\` prefix and the resolved docker network name.
+
+Why: running the worker as a compose service makes it join the SUT's network declaratively (so the app can reach its mocks) and tears it down with \`docker compose down\` — replacing the fragile runtime worker spawn that landed on the wrong network and leaked on teardown.
+
+Use the returned values like this:
+- Bring up: \`docker compose <composeFilePrefix> up -d --build <sut-service> <real-deps...> skyramp\` (stop mocked-service containers first).
+- Tear down: \`docker compose <composeFilePrefix> down -v\`.
+- Pass \`dockerNetwork\` (and \`dockerWorkerPort\`=workerPort) to every test generation call so the generated client — emitted with runtime="docker", docker_network, docker_skyramp_port — connects to this worker.`,
+        inputSchema: {
+            repositoryPath: z
+                .string()
+                .refine((value) => path.isAbsolute(value), {
+                message: "repositoryPath must be an absolute path",
+            })
+                .describe("Absolute path to the repository (where docker-compose runs)."),
+            composeFile: z
+                .string()
+                .optional()
+                .describe("Path to the base docker-compose file (absolute, or relative to repositoryPath). Omit to auto-discover docker-compose.yml/.yaml or compose.yml/.yaml at the repo root. Provide this when the compose file lives in a subdirectory or has a non-default name."),
+            thirdPartyHosts: z
+                .array(z.string().min(1, "Host entries must be non-empty strings"))
+                .optional()
+                .describe("Third-party FQDNs to intercept on the Docker network (e.g., ['www.google.com', 'api.stripe.com']). " +
+                "The worker is given Docker network aliases for these hostnames so DNS resolves them to the worker container, " +
+                "allowing mocks to intercept traffic to external services that are not part of the compose stack."),
+        },
+    }, async (args) => {
+        try {
+            const normalizedHosts = args.thirdPartyHosts
+                ? normalizeThirdPartyHosts(args.thirdPartyHosts)
+                : undefined;
+            const result = setupLocalDevWorker(args.repositoryPath, args.composeFile, normalizedHosts);
+            AnalyticsService.pushMCPToolEvent(TOOL_NAME, undefined, {}).catch(() => { });
+            logger.info("Generated local-dev worker compose override", {
+                overrideFile: result.overrideFile,
+                dockerNetwork: result.dockerNetwork,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(result, null, 2),
+                    },
+                ],
+                structuredContent: { ...result },
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                isError: true,
+                content: [{ type: "text", text: message }],
+            };
+        }
+    });
+}

package/build/tools/one-click/oneClickTool.d.ts

@@ -1,4 +1,8 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare enum CallingAgentIde {
+    Cursor = "cursor",
+    Claude = "claude"
+}
 /** User params passed to workflow builder (optional fields may be undefined) */
 export type OneClickParams = {
     workflow: string;
@@ -7,5 +11,14 @@ export type OneClickParams = {
     apiSchema?: string;
     topN?: number;
     token?: string;
+    baseBranch?: string;
+    servicesToMock?: string;
+    realServices?: string;
+    mockProtocols?: string;
+    proxyUrl?: string;
+    proxyKubeconfig?: string;
+    proxyNamespace?: string;
+    callingAgent?: CallingAgentIde;
+    rawCallingAgent?: string;
 };
 export declare function registerOneClickTool(server: McpServer): void;