@skyramp/mcp 0.2.150-rc.ldw → 0.2.150-rc.ldw-3

package/build/index.js

@@ -37,6 +37,7 @@ import { registerOneClickTool } from "./tools/one-click/oneClickTool.js";
 import { registerEnrichTestWithMocksTool } from "./tools/enrichTestWithMocksTool.js";
 import { registerPreflightMockCheckTool } from "./tools/preflightMockCheckTool.js";
 import { registerGenerateEnrichedIntegrationTestTool } from "./tools/generateEnrichedIntegrationTestTool.js";
+import { registerLocalDevWorkerComposeTool } from "./tools/localDevWorkerComposeTool.js";
 import { registerAnalysisResources } from "./resources/analysisResources.js";
 import { registerProgressResource } from "./resources/progressResource.js";
 import { AnalyticsService } from "./services/AnalyticsService.js";
@@ -198,7 +199,7 @@ const infrastructureTools = [
     registerTraceStopTool,
 ];
 if (isLocalDevEnabled()) {
-    infrastructureTools.push(registerEnrichTestWithMocksTool, registerPreflightMockCheckTool, registerGenerateEnrichedIntegrationTestTool);
+    infrastructureTools.push(registerEnrichTestWithMocksTool, registerPreflightMockCheckTool, registerGenerateEnrichedIntegrationTestTool, registerLocalDevWorkerComposeTool);
     logger.info("Local-dev tools enabled via SKYRAMP_FEATURE_LOCAL_DEV");
 }
 if (isTestbotEnabled()) {

package/build/prompts/local-dev/local-dev-plan.js

@@ -318,23 +318,24 @@ The tool returns instructions — it does NOT edit the file automatically. Apply
     .done()
     // ─── Phase 5: Deploy ────────────────────────────────────────────────────────
     .addPhase("deploy", "Deploy", { headerLevel: "##", stepFormat: "hash" })
-    .step("START_ENVIRONMENT", "Bring up the service under test", (ctx) => `If a \`docker-compose\` file is present in the repository, the service under test and its real infrastructure (DB, cache, real broker, real first-party services) must be running — **but mocked downstream services must NOT be running.**
+    .step("START_ENVIRONMENT", "Bring up the service under test and the Skyramp worker", (ctx) => `Bring up the service under test and its real infrastructure (DB, cache, real broker, real first-party services) together with the Skyramp mock worker — **but mocked downstream services must NOT be running.**
 
-**Why this matters:** The Skyramp worker intercepts traffic via Docker DNS alias hijacking — it registers itself as the DNS alias for each mocked service's hostname on the Docker network. If the real service container is also up on the same hostname and port, the two will conflict: traffic may reach the real service instead of the mock, or port binding will fail entirely. This is the most common cause of mocks not being applied correctly.
+**Why this matters:** The Skyramp worker runs as a Docker Compose service on the SUT's network and intercepts traffic via Docker DNS alias hijacking at mock-apply time — it takes over the DNS alias for each mocked service's hostname. If the real service container is also up on the same hostname and port, the two conflict: traffic may reach the real service instead of the mock, or port binding fails. This is the most common cause of mocks not being applied correctly. Running the worker as a compose service (rather than spawning it ad hoc) guarantees it joins the SUT's network and is torn down with the stack.
 
 Steps:
-1. Run \`docker compose ps\` in \`${ctx.repositoryPath}\` to check current container state.
-2. Identify which docker-compose service names correspond to services selected for mocking (e.g., if \`ams\` is selected for mocking, do not start the \`ams\` container).
-3. Stop any mocked service containers that are already running:
-   \`docker compose stop <mocked-service-1> <mocked-service-2> ...\`
-4. Rebuild and bring up only the SUT and its real dependencies — start selectively:
-   \`docker compose up -d --build <sut-service> <db> <cache> <broker> <real-first-party-services>\`
-   Do **not** run plain \`docker compose up -d\` when it would start mocked downstream services or reuse a stale SUT image. If the compose file cannot start selectively, start the minimum required profile/services and then re-check that mocked service containers are stopped before executing tests. If the SUT service has no compose \`build\` context, record that local code cannot be rebuilt by compose before execution.
-5. Wait for health checks to pass and verify the service under test responds (e.g., curl the health endpoint or send a minimal request).
-
-The \`skyramp_execute_test\` tool runs the enriched test in the language runner. The enriched test applies selected mocks at runtime through its language-specific helper before exercising the service.
-
-**Do NOT proceed to Execute until: (a) the service under test responds, and (b) all mocked service containers are confirmed stopped.**`)
+1. Call \`skyramp_setup_local_dev_worker\` with \`repositoryPath\` = \`${ctx.repositoryPath}\` (pass \`composeFile\` if the base docker-compose file is not at the repo root). It writes a worker compose override and returns \`composeFilePrefix\` (the \`-f <base> -f <override>\` flags), the resolved \`dockerNetwork\`, and the worker port. **Use the returned \`composeFilePrefix\` for every \`docker compose\` command below, and pass the returned \`dockerNetwork\` to test/mock generation (see the Generate phase).**
+2. Run \`docker compose <composeFilePrefix> ps\` to check current container state.
+3. Identify which docker-compose service names correspond to services selected for mocking (e.g., if \`ams\` is selected for mocking, do not start the \`ams\` container).
+4. Stop any mocked service containers that are already running:
+   \`docker compose <composeFilePrefix> stop <mocked-service-1> <mocked-service-2> ...\`
+5. Rebuild and bring up only the SUT, its real dependencies, and the worker — start selectively:
+   \`docker compose <composeFilePrefix> up -d --build <sut-service> <db> <cache> <broker> <real-first-party-services> skyramp\`
+   Always include the \`skyramp\` service. Do **not** run plain \`docker compose up -d\` when it would start mocked downstream services or reuse a stale SUT image. If the compose file cannot start selectively, start the minimum required profile/services plus \`skyramp\`, then re-check that mocked service containers are stopped before executing tests. If the SUT service has no compose \`build\` context, record that local code cannot be rebuilt by compose before execution.
+6. Wait for health checks to pass and verify (a) the service under test responds (e.g., curl the health endpoint) and (b) the \`skyramp\` worker container is running.
+
+The \`skyramp_execute_test\` tool runs the enriched test in the language runner. Its generated Skyramp client connects to the worker — emitted with \`runtime="docker"\`, \`docker_network\`, and \`docker_skyramp_port\` (from the \`dockerNetwork\` and \`dockerWorkerPort\` passed to generation) — and applies the selected mocks before exercising the service.
+
+**Do NOT proceed to Execute until: (a) the service under test responds, (b) the \`skyramp\` worker is running, and (c) all mocked service containers are confirmed stopped.**`)
     .subStep("DEPLOY_GRPC", "Handle gRPC dependencies", (_ctx) => `If the dependency map from Phase 1 includes gRPC services selected for mocking:
 
 To regenerate a single missing gRPC mock, call \`skyramp_mock_generation\` with \`protocol: "grpc"\`.
@@ -414,6 +415,7 @@ That's it. Pass \`token: ""\` so the executor injects \`SKYRAMP_TEST_TOKEN\` fro
   - **Generated test issue** — failure from wrong auth, missing field, or incorrect assertion in the generated test itself.
   - **Timeout** — execution did not complete; pass/fail is unknown.
 - **Issues found**: unmockable deps, generation failures, connection errors, gaps
+- **Teardown**: remind the user that, when finished, tearing the stack down with \`docker compose <composeFilePrefix> down -v --remove-orphans\` (the same \`-f\` prefix returned by \`skyramp_setup_local_dev_worker\`) removes the SUT, real dependencies, **and the Skyramp worker** together — so no worker container or network is left behind. A plain \`docker compose down\` *without* the override prefix leaves the worker running (it is defined only in the override, so a base-only \`down\` treats it as an orphan) and the network fails to delete with "resource still in use"; always include the prefix. If the prefix is ever unavailable at teardown, \`docker compose down --remove-orphans\` against the base file still sweeps the worker as an orphan.
 
 Do NOT write results to a file — report inline to the user.`)
     .done();

package/build/prompts/local-dev/local-dev-prompts.js

@@ -63,6 +63,7 @@ ${sandboxWorkerBlock ? sandboxWorkerBlock + "\n" : ""}${serviceContext ? service
 - **Enrichment validation** — an integration test that has downstream mocks but lacks \`MOCK_SERVICES\` and the language-specific apply helper (\`apply_all_mocks(client)\` for Python or \`applyAllMocks(client)\` for TypeScript/JavaScript/Java) is incomplete. Stop and enrich it; never call \`skyramp_execute_test\` on an incomplete integration test.
 - **Do not delete mocks to pass** — if mock deployment fails, do NOT remove mock imports, empty \`MOCK_SERVICES\`, switch mocked downstreams to live Compose stubs, or report the resulting test as passed. Fix the mock wiring once; if still blocked, report the scenario as failed/blocked with the mock deployment error.
 - **Mocked services must not be running** — before execution, stop every Docker container for a service selected for mocking (\`docker compose stop <mocked-service>\`). The Skyramp worker takes over that service's DNS alias on the Docker network; a real container running on the same hostname and port will conflict, causing traffic to reach the real service instead of the mock or causing port binding failure. Bring up only the SUT and its real infrastructure (DB, cache, real broker, real first-party services); do NOT run \`docker compose up -d\` without immediately stopping mocked service containers.
+- **Worker runs as a compose service** — the Deploy phase calls \`skyramp_setup_local_dev_worker\`, which adds the Skyramp worker to the SUT's Docker network via a compose override and returns the resolved \`dockerNetwork\` plus the \`-f\` \`composeFilePrefix\`. Pass that \`dockerNetwork\` (and \`dockerWorkerPort\`, default 35142) to \`skyramp_generate_enriched_integration_test\` so the generated client connects to that worker — generation emits the client with \`runtime="docker"\`, \`docker_network\`, and \`docker_skyramp_port\`. Use the \`composeFilePrefix\` for every \`docker compose\` command, and tear the stack down with the same prefix (\`docker compose <composeFilePrefix> down -v --remove-orphans\`) so the worker is removed with the stack — a base-only \`docker compose down\` leaves the worker (it lives only in the override) holding the network open. Never spawn the worker manually.
 - **Mock URL format** — the \`endpointURL\` in \`skyramp_mock_generation\` MUST use the original Docker service hostname (e.g., \`http://identity-service:4000\`, \`http://profile-service:50052\`). The Skyramp executor uses DNS alias hijacking — it takes over the service's DNS name on the Docker network so the service under test's requests are intercepted transparently. NEVER use \`localhost\`, \`127.0.0.1\`, \`0.0.0.0\`, \`host.docker.internal\`, or the worker address as the mock URL. For REST mocks, \`skyramp_preflight_mock_check\` returns blocking \`REST_LOOPBACK_URL\` when a deployable mock uses these hosts.
 - **REST mock routing** — Generated REST mock files may contain a fallback \`URL\` value such as \`http://localhost:8080\`; do not manually edit those files. The enrichment tool uses the mock generation \`# Command\` target to set each REST mock's \`mock.url\` back to the original Docker service origin before \`apply_mock()\`. If the command target is loopback, regenerate the mock with the original service hostname.
 - **gRPC mock routing** — gRPC mocks may target the real downstream service port (e.g., \`partner-accounts:50051\`). Apply gRPC mocks before the SUT starts or restart the SUT after applying them, and verify the Skyramp worker has the original endpoint host alias from \`endpointURL\` (\`partner-accounts\`, not the protobuf service name like \`PartnerAccountsService\`).

package/build/tool-phases.js

@@ -32,6 +32,7 @@ export const TOOLS_WITHOUT_PHASE = new Set([
     "skyramp_init_scan",
     "skyramp_init_workspace",
     "skyramp_one_click_tool",
+    "skyramp_setup_local_dev_worker",
     "skyramp_actions",
     "skyramp_start_trace_collection",
     "skyramp_stop_trace_collection",

package/build/tools/generateEnrichedIntegrationTestTool.d.ts

@@ -16,6 +16,7 @@ export declare function executeGenerateEnrichedIntegrationTest(params: {
     output?: string;
     runtime?: string;
     dockerNetwork?: string;
+    dockerWorkerPort?: number;
     authHeader?: string;
     authScheme?: string;
     language?: string;

package/build/tools/generateEnrichedIntegrationTestTool.js

@@ -4,6 +4,7 @@ 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";
@@ -32,6 +33,13 @@ const enrichedIntegrationTestSchema = {
         .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()
@@ -71,7 +79,7 @@ export function registerGenerateEnrichedIntegrationTestTool(server) {
     });
 }
 export async function executeGenerateEnrichedIntegrationTest(params) {
-    const { scenarioFile, mockFiles, scenarioName, outputDir, output, runtime, dockerNetwork, authHeader, authScheme, language, framework, traceComments, } = 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)) {
@@ -131,6 +139,7 @@ export async function executeGenerateEnrichedIntegrationTest(params) {
             runtime: runtime ?? RuntimeEnvironment.DOCKER,
             force: true,
             dockerNetwork,
+            dockerWorkerPort: (dockerWorkerPort ?? WORKER_CONTROL_PORT).toString(),
             authHeader: resolvedAuthHeader,
             authType: resolvedAuthType,
             language: resolvedLanguage,

package/build/tools/localDevWorkerComposeTool.d.ts

@@ -0,0 +1,23 @@
+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.
+ */
+export declare function setupLocalDevWorker(repositoryPath: string, composeFile?: 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,191 @@
+import { z } from "zod";
+import * as path from "path";
+import * as fs from "fs";
+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";
+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) {
+    const workerService = {
+        image: WORKER_DOCKER_IMAGE,
+        volumes: [
+            "skyramp:/etc/skyramp",
+            "/var/run/docker.sock:/var/run/docker.sock",
+        ],
+        ports: [`${WORKER_CONTROL_PORT}:${WORKER_CONTROL_PORT}`],
+        restart: "always",
+    };
+    const doc = {
+        services: { skyramp: workerService },
+        volumes: { skyramp: null },
+    };
+    if (networkKeys.length > 0) {
+        workerService.networks = networkKeys;
+        // Reference each base network by key so Compose merges (does not redefine) it.
+        doc.networks = Object.fromEntries(networkKeys.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}`;
+}
+/**
+ * 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.
+ */
+export function setupLocalDevWorker(repositoryPath, composeFile) {
+    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);
+    const composeDir = path.dirname(baseComposeFile);
+    const project = deriveProjectName(composeDir);
+    // 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);
+    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."),
+        },
+    }, async (args) => {
+        try {
+            const result = setupLocalDevWorker(args.repositoryPath, args.composeFile);
+            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),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                isError: true,
+                content: [{ type: "text", text: message }],
+            };
+        }
+    });
+}

package/build/tools/localDevWorkerComposeTool.test.d.ts

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

package/build/tools/localDevWorkerComposeTool.test.js

@@ -0,0 +1,121 @@
+import { describe, it, expect, afterEach } from "@jest/globals";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import yaml from "js-yaml";
+import { setupLocalDevWorker } from "./localDevWorkerComposeTool.js";
+import { WORKER_DOCKER_IMAGE } from "../utils/versions.js";
+/** Create a project dir (named, for deterministic project-name derivation) with a compose file. */
+function makeRepo(projectName, composeBody, fileName = "docker-compose.yml") {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "skyramp-worker-"));
+    const repo = path.join(root, projectName);
+    fs.mkdirSync(repo, { recursive: true });
+    fs.writeFileSync(path.join(repo, fileName), composeBody);
+    return { root, repo };
+}
+const NAMED_NETWORK_COMPOSE = `services:
+  monolith:
+    image: monolith
+    networks: [checkr_default]
+networks:
+  checkr_default:
+    driver: bridge
+`;
+const DEFAULT_NETWORK_COMPOSE = `services:
+  monolith:
+    image: monolith
+`;
+// Network with an explicit `name:` — Compose uses that verbatim (not project-scoped).
+const EXPLICIT_NAME_COMPOSE = `services:
+  monolith:
+    image: monolith
+    networks: [app]
+networks:
+  app:
+    name: my_custom_net
+`;
+// External network — pre-existing, not project-scoped.
+const EXTERNAL_NETWORK_COMPOSE = `services:
+  monolith:
+    image: monolith
+    networks: [shared]
+networks:
+  shared:
+    external: true
+`;
+describe("setupLocalDevWorker", () => {
+    const created = [];
+    afterEach(() => {
+        while (created.length)
+            fs.rmSync(created.pop(), { recursive: true, force: true });
+        delete process.env.COMPOSE_PROJECT_NAME;
+    });
+    function loadOverride(file) {
+        return yaml.load(fs.readFileSync(file, "utf-8"));
+    }
+    it("attaches the worker to the base's named network and resolves <project>_<key>", () => {
+        const { root, repo } = makeRepo("demoapp", NAMED_NETWORK_COMPOSE);
+        created.push(root);
+        const result = setupLocalDevWorker(repo);
+        expect(result.dockerNetwork).toBe("demoapp_checkr_default");
+        expect(result.workerPort).toBe(35142);
+        expect(result.composeFilePrefix).toBe(`-f ${result.baseComposeFile} -f ${result.overrideFile}`);
+        const doc = loadOverride(result.overrideFile);
+        const worker = doc.services.skyramp;
+        expect(worker.image).toBe(WORKER_DOCKER_IMAGE);
+        expect(worker.ports).toEqual(["35142:35142"]); // only the control port published
+        expect(worker.volumes).toContain("/var/run/docker.sock:/var/run/docker.sock");
+        expect(worker.networks).toEqual(["checkr_default"]);
+        expect(doc.networks).toHaveProperty("checkr_default");
+        expect(doc.volumes).toHaveProperty("skyramp");
+    });
+    it("uses an explicit network name: verbatim (not project-scoped)", () => {
+        const { root, repo } = makeRepo("demoapp", EXPLICIT_NAME_COMPOSE);
+        created.push(root);
+        const result = setupLocalDevWorker(repo);
+        expect(result.dockerNetwork).toBe("my_custom_net");
+        expect(loadOverride(result.overrideFile).services.skyramp.networks).toEqual(["app"]);
+    });
+    it("uses the key (not project-scoped) for an external network", () => {
+        const { root, repo } = makeRepo("demoapp", EXTERNAL_NETWORK_COMPOSE);
+        created.push(root);
+        const result = setupLocalDevWorker(repo);
+        expect(result.dockerNetwork).toBe("shared");
+    });
+    it("joins the implicit default network when the base declares none", () => {
+        const { root, repo } = makeRepo("plainapp", DEFAULT_NETWORK_COMPOSE);
+        created.push(root);
+        const result = setupLocalDevWorker(repo);
+        expect(result.dockerNetwork).toBe("plainapp_default");
+        const doc = loadOverride(result.overrideFile);
+        // No named networks → worker has no explicit networks list (joins default).
+        expect(doc.services.skyramp.networks).toBeUndefined();
+        expect(doc.networks).toBeUndefined();
+    });
+    it("honors COMPOSE_PROJECT_NAME for the network name", () => {
+        const { root, repo } = makeRepo("ignored-basename", NAMED_NETWORK_COMPOSE);
+        created.push(root);
+        process.env.COMPOSE_PROJECT_NAME = "custom";
+        const result = setupLocalDevWorker(repo);
+        expect(result.dockerNetwork).toBe("custom_checkr_default");
+    });
+    it("resolves a non-root composeFile and builds the right -f prefix", () => {
+        const { root, repo } = makeRepo("subdirapp", NAMED_NETWORK_COMPOSE, "docker-compose.yml");
+        created.push(root);
+        // Move the compose into a subdir to simulate a non-default location.
+        const subdir = path.join(repo, "infra");
+        fs.mkdirSync(subdir);
+        const moved = path.join(subdir, "compose.yml");
+        fs.renameSync(path.join(repo, "docker-compose.yml"), moved);
+        const result = setupLocalDevWorker(repo, "infra/compose.yml");
+        expect(result.baseComposeFile).toBe(moved);
+        expect(result.composeFilePrefix).toContain(`-f ${moved}`);
+        // Project name comes from the compose file's directory (infra), not the repo root.
+        expect(result.dockerNetwork).toBe("infra_checkr_default");
+    });
+    it("throws a clear error when no compose file is found", () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), "skyramp-worker-"));
+        created.push(root);
+        expect(() => setupLocalDevWorker(root)).toThrow(/No docker-compose file found/);
+    });
+});

package/build/utils/docker.test.js

@@ -55,7 +55,7 @@ describe("dockerImageExistsLocally", () => {
     });
 });
 describe("pullDockerImage", () => {
-    const IMAGE = "skyramp/executor:v1.3.30";
+    const IMAGE = "skyramp/executor:v1.3.32";
     beforeEach(() => jest.clearAllMocks());
     describe("on amd64 host", () => {
         const originalArch = process.arch;

package/build/utils/versions.d.ts

@@ -1,3 +1,4 @@
-export declare const SKYRAMP_IMAGE_VERSION = "v1.3.30";
-export declare const EXECUTOR_DOCKER_IMAGE = "skyramp/executor:v1.3.30";
-export declare const WORKER_DOCKER_IMAGE = "skyramp/worker:v1.3.30";
+export declare const SKYRAMP_IMAGE_VERSION = "v1.3.32";
+export declare const EXECUTOR_DOCKER_IMAGE = "skyramp/executor:v1.3.32";
+export declare const WORKER_DOCKER_IMAGE = "skyramp/worker:v1.3.32";
+export declare const WORKER_CONTROL_PORT = 35142;

package/build/utils/versions.js

@@ -1,3 +1,5 @@
-export const SKYRAMP_IMAGE_VERSION = "v1.3.30";
+export const SKYRAMP_IMAGE_VERSION = "v1.3.32";
 export const EXECUTOR_DOCKER_IMAGE = `skyramp/executor:${SKYRAMP_IMAGE_VERSION}`;
 export const WORKER_DOCKER_IMAGE = `skyramp/worker:${SKYRAMP_IMAGE_VERSION}`;
+// Control port the Skyramp worker listens on (SDK `CONTAINER_PORT`).
+export const WORKER_CONTROL_PORT = 35142;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyramp/mcp",
-  "version": "0.2.150-rc.ldw",
+  "version": "0.2.150-rc.ldw-3",
   "main": "build/index.js",
   "exports": {
     ".": "./build/index.js",
@@ -67,7 +67,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.24.3",
     "@playwright/test": "^1.55.0",
-    "@skyramp/skyramp": "1.3.30",
+    "@skyramp/skyramp": "1.3.32",
     "dockerode": "^5.0.0",
     "fast-glob": "^3.3.3",
     "js-yaml": "^4.1.1",