@skyramp/mcp 0.2.8 → 0.2.150-rc.ldw

package/build/utils/branchDiff.test.js

@@ -0,0 +1,109 @@
+import { jest } from "@jest/globals";
+import { execFileSync } from "child_process";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { computeBranchDiff, normalizeProvidedBaseRef } from "./branchDiff.js";
+jest.setTimeout(15000);
+function git(cwd, args) {
+    execFileSync("git", args, { cwd, stdio: "ignore" });
+}
+describe("computeBranchDiff", () => {
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "skyramp-branch-diff-"));
+        git(tmpDir, ["init"]);
+        git(tmpDir, ["branch", "-m", "main"]);
+        fs.writeFileSync(path.join(tmpDir, "README.md"), "initial\n");
+        git(tmpDir, ["add", "README.md"]);
+        git(tmpDir, [
+            "-c",
+            "user.name=Test",
+            "-c",
+            "user.email=test@example.com",
+            "commit",
+            "-m",
+            "initial",
+        ]);
+    });
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it("classifies untracked files as both changed and new when including uncommitted changes", async () => {
+        fs.mkdirSync(path.join(tmpDir, "src"));
+        fs.writeFileSync(path.join(tmpDir, "src", "newEndpoint.ts"), "export const value = 1;\n");
+        const diff = await computeBranchDiff(tmpDir, "HEAD", true);
+        expect(diff.changedFiles).toContain("src/newEndpoint.ts");
+        expect(diff.newFiles).toContain("src/newEndpoint.ts");
+    });
+    it("prefers origin branch over local branch for uncommitted local-dev diffs", async () => {
+        const remoteDir = fs.mkdtempSync(path.join(os.tmpdir(), "skyramp-branch-diff-remote-"));
+        try {
+            git(remoteDir, ["init", "--bare"]);
+            git(tmpDir, ["remote", "add", "origin", remoteDir]);
+            git(tmpDir, ["push", "-u", "origin", "main"]);
+            fs.writeFileSync(path.join(tmpDir, "README.md"), "local main ahead\n");
+            git(tmpDir, ["add", "README.md"]);
+            git(tmpDir, [
+                "-c",
+                "user.name=Test",
+                "-c",
+                "user.email=test@example.com",
+                "commit",
+                "-m",
+                "local main ahead",
+            ]);
+            fs.writeFileSync(path.join(tmpDir, "local.txt"), "uncommitted\n");
+            const diff = await computeBranchDiff(tmpDir, "main", true);
+            expect(diff.baseBranch).toBe("origin/main");
+            expect(diff.changedFiles.join("\n")).not.toMatch(/^origin\//m);
+            expect(diff.changedFiles).toContain("README.md");
+            expect(diff.changedFiles).toContain("local.txt");
+        }
+        finally {
+            fs.rmSync(remoteDir, { recursive: true, force: true });
+        }
+    });
+    it("uses SHA-like base refs directly when including uncommitted changes", async () => {
+        const remoteDir = fs.mkdtempSync(path.join(os.tmpdir(), "skyramp-branch-diff-remote-"));
+        try {
+            git(remoteDir, ["init", "--bare"]);
+            git(tmpDir, ["remote", "add", "origin", remoteDir]);
+            git(tmpDir, ["push", "-u", "origin", "main"]);
+            const baseSha = execFileSync("git", ["rev-parse", "--short=7", "HEAD"], {
+                cwd: tmpDir,
+                encoding: "utf8",
+            }).trim();
+            fs.writeFileSync(path.join(tmpDir, "README.md"), "local main ahead\n");
+            git(tmpDir, ["add", "README.md"]);
+            git(tmpDir, [
+                "-c",
+                "user.name=Test",
+                "-c",
+                "user.email=test@example.com",
+                "commit",
+                "-m",
+                "local main ahead",
+            ]);
+            git(tmpDir, ["branch", baseSha, "HEAD"]);
+            git(tmpDir, ["push", "origin", baseSha]);
+            fs.writeFileSync(path.join(tmpDir, "local.txt"), "uncommitted\n");
+            const diff = await computeBranchDiff(tmpDir, baseSha, true);
+            expect(diff.baseBranch).toBe(baseSha);
+            expect(diff.baseBranch).not.toMatch(/^origin\//);
+            expect(diff.changedFiles).toContain("local.txt");
+        }
+        finally {
+            fs.rmSync(remoteDir, { recursive: true, force: true });
+        }
+    });
+    it("trims provided base refs before using them", () => {
+        expect(normalizeProvidedBaseRef("  main  ")).toBe("main");
+    });
+    it("rejects option-like provided base refs", () => {
+        expect(() => normalizeProvidedBaseRef("--output=/tmp/evil")).toThrow("refs must not start with '-'");
+    });
+    it("rejects provided base refs containing internal whitespace", () => {
+        expect(() => normalizeProvidedBaseRef("main --stat")).toThrow("refs must not contain whitespace");
+    });
+});

package/build/utils/docker.test.js

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

package/build/utils/featureFlags.d.ts

@@ -23,11 +23,14 @@
  *   - Testbot recommendation prompts no longer suggest `consumerMode: true`
  *     contract tests.
  *
- * When ON (`SKYRAMP_FEATURE_CONTRACT_CONSUMER_MODE=1`):
+ * When ON (`SKYRAMP_FEATURE_CONTRACT_CONSUMER_MODE=1` OR `SKYRAMP_FEATURE_LOCAL_DEV=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.
+ *
+ * Local-dev implicitly enables this flag because consumer contract tests with
+ * inline mocks are the standard local-dev testing pattern.
  */
 export declare function isContractConsumerModeEnabled(): boolean;
 /**
@@ -35,3 +38,19 @@ export declare function isContractConsumerModeEnabled(): boolean;
  * (SKYRAMP_FEATURE_TESTBOT=1).
  */
 export declare function isTestbotEnabled(): boolean;
+/**
+ * Returns true when the local-dev workflow is enabled
+ * (SKYRAMP_FEATURE_LOCAL_DEV=1).
+ *
+ * The local-dev workflow registers the `skyramp_local_dev` prompt and
+ * one-click routing, which diffs from a base commit against the current
+ * working state, generates mock configurations and backend tests, executes
+ * them locally, and reports results — without requiring a pull request or
+ * CI environment.
+ */
+export declare function isLocalDevEnabled(): boolean;
+/**
+ * Returns true when general one-click workflows are enabled
+ * (SKYRAMP_FEATURE_ONE_CLICK=1).
+ */
+export declare function isOneClickEnabled(): boolean;

package/build/utils/featureFlags.js

@@ -23,14 +23,18 @@
  *   - Testbot recommendation prompts no longer suggest `consumerMode: true`
  *     contract tests.
  *
- * When ON (`SKYRAMP_FEATURE_CONTRACT_CONSUMER_MODE=1`):
+ * When ON (`SKYRAMP_FEATURE_CONTRACT_CONSUMER_MODE=1` OR `SKYRAMP_FEATURE_LOCAL_DEV=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.
+ *
+ * Local-dev implicitly enables this flag because consumer contract tests with
+ * inline mocks are the standard local-dev testing pattern.
  */
 export function isContractConsumerModeEnabled() {
-    return process.env.SKYRAMP_FEATURE_CONTRACT_CONSUMER_MODE === "1";
+    return (process.env.SKYRAMP_FEATURE_CONTRACT_CONSUMER_MODE === "1" ||
+        isLocalDevEnabled());
 }
 /**
  * Returns true when running inside a TestBot environment
@@ -39,3 +43,23 @@ export function isContractConsumerModeEnabled() {
 export function isTestbotEnabled() {
     return process.env.SKYRAMP_FEATURE_TESTBOT === "1";
 }
+/**
+ * Returns true when the local-dev workflow is enabled
+ * (SKYRAMP_FEATURE_LOCAL_DEV=1).
+ *
+ * The local-dev workflow registers the `skyramp_local_dev` prompt and
+ * one-click routing, which diffs from a base commit against the current
+ * working state, generates mock configurations and backend tests, executes
+ * them locally, and reports results — without requiring a pull request or
+ * CI environment.
+ */
+export function isLocalDevEnabled() {
+    return process.env.SKYRAMP_FEATURE_LOCAL_DEV === "1";
+}
+/**
+ * Returns true when general one-click workflows are enabled
+ * (SKYRAMP_FEATURE_ONE_CLICK=1).
+ */
+export function isOneClickEnabled() {
+    return process.env.SKYRAMP_FEATURE_ONE_CLICK === "1";
+}

package/build/utils/featureFlags.test.js

@@ -1,9 +1,15 @@
 import { resolveServiceDetailsRef } from "./utils.js";
-import { isTestbotEnabled } from "./featureFlags.js";
+import { isContractConsumerModeEnabled, isLocalDevEnabled, isTestbotEnabled } from "./featureFlags.js";
 // Capture and restore the original env var so these tests don't pollute other
 // test suites or a developer's shell environment where the var may already be set.
 let originalTestbotEnv;
-beforeAll(() => { originalTestbotEnv = process.env.SKYRAMP_FEATURE_TESTBOT; });
+let originalContractConsumerEnv;
+let originalLocalDevEnv;
+beforeAll(() => {
+    originalTestbotEnv = process.env.SKYRAMP_FEATURE_TESTBOT;
+    originalContractConsumerEnv = process.env.SKYRAMP_FEATURE_CONTRACT_CONSUMER_MODE;
+    originalLocalDevEnv = process.env.SKYRAMP_FEATURE_LOCAL_DEV;
+});
 afterAll(() => {
     if (originalTestbotEnv === undefined) {
         delete process.env.SKYRAMP_FEATURE_TESTBOT;
@@ -11,6 +17,18 @@ afterAll(() => {
     else {
         process.env.SKYRAMP_FEATURE_TESTBOT = originalTestbotEnv;
     }
+    if (originalContractConsumerEnv === undefined) {
+        delete process.env.SKYRAMP_FEATURE_CONTRACT_CONSUMER_MODE;
+    }
+    else {
+        process.env.SKYRAMP_FEATURE_CONTRACT_CONSUMER_MODE = originalContractConsumerEnv;
+    }
+    if (originalLocalDevEnv === undefined) {
+        delete process.env.SKYRAMP_FEATURE_LOCAL_DEV;
+    }
+    else {
+        process.env.SKYRAMP_FEATURE_LOCAL_DEV = originalLocalDevEnv;
+    }
 });
 describe("isTestbotEnabled", () => {
     afterEach(() => {
@@ -32,6 +50,43 @@ describe("isTestbotEnabled", () => {
         expect(isTestbotEnabled()).toBe(false);
     });
 });
+describe("isContractConsumerModeEnabled", () => {
+    afterEach(() => {
+        delete process.env.SKYRAMP_FEATURE_CONTRACT_CONSUMER_MODE;
+        delete process.env.SKYRAMP_FEATURE_LOCAL_DEV;
+    });
+    it("defaults to false when neither flag is set", () => {
+        expect(isContractConsumerModeEnabled()).toBe(false);
+    });
+    it('returns true when SKYRAMP_FEATURE_CONTRACT_CONSUMER_MODE is "1"', () => {
+        process.env.SKYRAMP_FEATURE_CONTRACT_CONSUMER_MODE = "1";
+        expect(isContractConsumerModeEnabled()).toBe(true);
+    });
+    it('returns true when SKYRAMP_FEATURE_LOCAL_DEV is "1" (local-dev implies consumer mode)', () => {
+        process.env.SKYRAMP_FEATURE_LOCAL_DEV = "1";
+        expect(isContractConsumerModeEnabled()).toBe(true);
+    });
+    it('returns false when SKYRAMP_FEATURE_CONTRACT_CONSUMER_MODE is "0"', () => {
+        process.env.SKYRAMP_FEATURE_CONTRACT_CONSUMER_MODE = "0";
+        expect(isContractConsumerModeEnabled()).toBe(false);
+    });
+});
+describe("isLocalDevEnabled", () => {
+    afterEach(() => {
+        delete process.env.SKYRAMP_FEATURE_LOCAL_DEV;
+    });
+    it('returns true when SKYRAMP_FEATURE_LOCAL_DEV is "1"', () => {
+        process.env.SKYRAMP_FEATURE_LOCAL_DEV = "1";
+        expect(isLocalDevEnabled()).toBe(true);
+    });
+    it("returns false when SKYRAMP_FEATURE_LOCAL_DEV is unset", () => {
+        expect(isLocalDevEnabled()).toBe(false);
+    });
+    it('returns false when SKYRAMP_FEATURE_LOCAL_DEV is "0"', () => {
+        process.env.SKYRAMP_FEATURE_LOCAL_DEV = "0";
+        expect(isLocalDevEnabled()).toBe(false);
+    });
+});
 describe("resolveServiceDetailsRef", () => {
     afterEach(() => {
         delete process.env.SKYRAMP_FEATURE_TESTBOT;

package/build/utils/grpcMockValidation.d.ts

@@ -0,0 +1 @@
+export declare function getGrpcMockResponseValidationError(responseData?: string): string | null;

package/build/utils/grpcMockValidation.js

@@ -0,0 +1,49 @@
+const GRPC_STATUS_ERROR_NAMES = new Set([
+    "CANCELLED",
+    "UNKNOWN",
+    "INVALID_ARGUMENT",
+    "DEADLINE_EXCEEDED",
+    "NOT_FOUND",
+    "ALREADY_EXISTS",
+    "PERMISSION_DENIED",
+    "RESOURCE_EXHAUSTED",
+    "FAILED_PRECONDITION",
+    "ABORTED",
+    "OUT_OF_RANGE",
+    "UNIMPLEMENTED",
+    "INTERNAL",
+    "UNAVAILABLE",
+    "DATA_LOSS",
+    "UNAUTHENTICATED",
+]);
+export function getGrpcMockResponseValidationError(responseData) {
+    if (!responseData || responseData.trim().startsWith("@"))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(responseData);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return null;
+    }
+    const record = parsed;
+    const candidate = record.error;
+    if (typeof candidate !== "string")
+        return null;
+    const normalized = normalizeGrpcStatusName(candidate);
+    if (!GRPC_STATUS_ERROR_NAMES.has(normalized))
+        return null;
+    return `gRPC mock responseData cannot simulate gRPC status errors such as "${normalized}". Use grpcStatusCode/grpcStatusMessage for gRPC status errors, generate a successful protobuf-shaped response, use a real failing service, or record this scenario as blocked`;
+}
+function normalizeGrpcStatusName(value) {
+    return value
+        .replace(/^GRPC::Status(?:::|\.)?/i, "")
+        .replace(/^GRPC::/i, "")
+        .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+        .replace(/[\s.:-]+/g, "_")
+        .replace(/^_+|_+$/g, "")
+        .toUpperCase();
+}

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

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

package/build/utils/grpcMockValidation.test.js

@@ -0,0 +1,41 @@
+import { getGrpcMockResponseValidationError } from "./grpcMockValidation.js";
+describe("getGrpcMockResponseValidationError", () => {
+    it.each([
+        ["UNAVAILABLE", "UNAVAILABLE"],
+        ["GRPC::Unavailable", "UNAVAILABLE"],
+        ["GRPC::Status::UNAVAILABLE", "UNAVAILABLE"],
+        ["GRPC::Status.UNAVAILABLE", "UNAVAILABLE"],
+        ["DeadlineExceeded", "DEADLINE_EXCEEDED"],
+    ])("rejects gRPC status error spelling %s", (input, normalized) => {
+        expect(getGrpcMockResponseValidationError(JSON.stringify({ error: input }))).toBe(`gRPC mock responseData cannot simulate gRPC status errors such as "${normalized}". Use grpcStatusCode/grpcStatusMessage for gRPC status errors, generate a successful protobuf-shaped response, use a real failing service, or record this scenario as blocked`);
+    });
+    it("allows successful protobuf-shaped response bodies", () => {
+        expect(getGrpcMockResponseValidationError(JSON.stringify({ tax_exempt: true, features: ["billing"] }))).toBeNull();
+    });
+    it("returns null when responseData is undefined or empty", () => {
+        expect(getGrpcMockResponseValidationError(undefined)).toBeNull();
+        expect(getGrpcMockResponseValidationError("")).toBeNull();
+    });
+    it("returns null when responseData is a file reference", () => {
+        expect(getGrpcMockResponseValidationError("@/repo/fixtures/response.json")).toBeNull();
+    });
+    it("returns null when responseData is a JSON array", () => {
+        expect(getGrpcMockResponseValidationError("[1, 2, 3]")).toBeNull();
+    });
+    it("returns null when responseData is JSON null", () => {
+        expect(getGrpcMockResponseValidationError("null")).toBeNull();
+    });
+    it("returns null when error field is a non-string value", () => {
+        expect(getGrpcMockResponseValidationError(JSON.stringify({ error: 14 }))).toBeNull();
+        expect(getGrpcMockResponseValidationError(JSON.stringify({ error: null }))).toBeNull();
+    });
+    it.each(["status", "code", "statusCode"])("allows bare application status fields in %s field", (field) => {
+        expect(getGrpcMockResponseValidationError(JSON.stringify({ [field]: "NOT_FOUND" }))).toBeNull();
+    });
+    it("allows protobuf-shaped responses with application status fields", () => {
+        expect(getGrpcMockResponseValidationError(JSON.stringify({ status: "INTERNAL", user_id: 123 }))).toBeNull();
+    });
+    it("returns null when error field is a non-status-code string", () => {
+        expect(getGrpcMockResponseValidationError(JSON.stringify({ error: "user not found" }))).toBeNull();
+    });
+});

package/build/utils/httpMethodValidation.d.ts

@@ -0,0 +1,4 @@
+import { HttpMethod } from "../types/TestTypes.js";
+export declare const REST_MOCK_HTTP_METHODS: HttpMethod[];
+export declare function normalizeRestMockMethod(method?: string): string;
+export declare function getRestMockMethodValidationError(method?: string): string | null;

package/build/utils/httpMethodValidation.js

@@ -0,0 +1,13 @@
+import { HttpMethod } from "../types/TestTypes.js";
+export const REST_MOCK_HTTP_METHODS = Object.values(HttpMethod);
+export function normalizeRestMockMethod(method) {
+    return method ? method.trim().toUpperCase() : "";
+}
+export function getRestMockMethodValidationError(method) {
+    if (!method)
+        return null;
+    const normalized = normalizeRestMockMethod(method);
+    if (REST_MOCK_HTTP_METHODS.includes(normalized))
+        return null;
+    return `REST mock method must be one of ${REST_MOCK_HTTP_METHODS.join(", ")} or empty string (got "${method}")`;
+}

package/build/utils/mockCompatibility.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Mock Compatibility Pre-flight Check
+ *
+ * Validates mock protocol combinations BEFORE deployment to surface
+ * known incompatibilities early rather than at test execution time.
+ */
+import { MockProtocol } from "../types/TestTypes.js";
+export { MockProtocol };
+/** Narrow view of a mock spec used only for protocol compatibility checking. */
+export interface MockCompatibilitySpec {
+    protocol: MockProtocol;
+    endpointURL: string;
+    method?: string;
+    grpcServiceName?: string;
+    kafkaTopic?: string;
+}
+export interface CompatibilityWarning {
+    code: string;
+    message: string;
+    suggestion: string;
+    affectedMocks: string[];
+    /** When true, the affected mocks cannot intercept traffic and must not be generated or deployed. */
+    blocking?: boolean;
+}
+export interface CompatibilityResult {
+    compatible: boolean;
+    /** True when at least one warning is blocking — those mocks must be skipped entirely. */
+    hasBlockers: boolean;
+    warnings: CompatibilityWarning[];
+}
+export interface MockCompatibilityOptions {
+    /** Enable Docker local-dev checks that require mocks to intercept service DNS aliases. */
+    dockerLocalDev?: boolean;
+}
+/**
+ * Validates a set of mock specs for known protocol compatibility issues.
+ *
+ * Rules:
+ * - Any gRPC mock present → GRPC_PERSISTENT_CONN warning (DNS hijacking skips persistent conns)
+ * - Docker local-dev REST mock using loopback/host.docker.internal → REST_LOOPBACK_URL blocking warning
+ *
+ * REST mocks work correctly in Docker local-dev mode only when the mock URL uses
+ * the real Docker service hostname (e.g. "billing" from "http://billing:5001").
+ * The worker adds that hostname as a Docker network alias so DNS resolves to the mock server.
+ *
+ * `compatible` is false when any warning is blocking and the mock cannot intercept traffic.
+ * `hasBlockers` is true when at least one warning is blocking (mock must not be generated/deployed).
+ */
+export declare function validateMockCompatibility(mocks: MockCompatibilitySpec[], options?: MockCompatibilityOptions): CompatibilityResult;

package/build/utils/mockCompatibility.js

@@ -0,0 +1,82 @@
+/**
+ * Mock Compatibility Pre-flight Check
+ *
+ * Validates mock protocol combinations BEFORE deployment to surface
+ * known incompatibilities early rather than at test execution time.
+ */
+import { MockProtocol } from "../types/TestTypes.js";
+export { MockProtocol };
+function parseRestHostname(endpointURL) {
+    try {
+        const hostname = new URL(endpointURL).hostname.toLowerCase();
+        return hostname.startsWith("[") && hostname.endsWith("]")
+            ? hostname.slice(1, -1)
+            : hostname;
+    }
+    catch {
+        return null;
+    }
+}
+function isLoopbackRestEndpoint(endpointURL) {
+    const hostname = parseRestHostname(endpointURL);
+    return (hostname === "localhost" ||
+        hostname === "127.0.0.1" ||
+        hostname === "0.0.0.0" ||
+        hostname === "::1" ||
+        hostname === "host.docker.internal");
+}
+/**
+ * Validates a set of mock specs for known protocol compatibility issues.
+ *
+ * Rules:
+ * - Any gRPC mock present → GRPC_PERSISTENT_CONN warning (DNS hijacking skips persistent conns)
+ * - Docker local-dev REST mock using loopback/host.docker.internal → REST_LOOPBACK_URL blocking warning
+ *
+ * REST mocks work correctly in Docker local-dev mode only when the mock URL uses
+ * the real Docker service hostname (e.g. "billing" from "http://billing:5001").
+ * The worker adds that hostname as a Docker network alias so DNS resolves to the mock server.
+ *
+ * `compatible` is false when any warning is blocking and the mock cannot intercept traffic.
+ * `hasBlockers` is true when at least one warning is blocking (mock must not be generated/deployed).
+ */
+export function validateMockCompatibility(mocks, options = {}) {
+    const warnings = [];
+    const restMocks = mocks.filter((m) => m.protocol === MockProtocol.Rest);
+    const grpcMocks = mocks.filter((m) => m.protocol === MockProtocol.Grpc);
+    const loopbackRestMocks = options.dockerLocalDev
+        ? restMocks.filter((m) => isLoopbackRestEndpoint(m.endpointURL))
+        : [];
+    if (loopbackRestMocks.length > 0) {
+        warnings.push({
+            code: "REST_LOOPBACK_URL",
+            message: "REST mocks for Docker local-dev must use the original Docker service hostname. " +
+                "Loopback hosts such as localhost, 127.0.0.1, 0.0.0.0, ::1, or host.docker.internal " +
+                "do not give the Skyramp worker the downstream service DNS alias it needs to intercept traffic.",
+            suggestion: "Use the real Docker service origin in endpointURL, for example http://ams:4000 or " +
+                "http://billing:5001. Do not use localhost, host.docker.internal, or the Skyramp worker address " +
+                "for deployable REST mocks.",
+            affectedMocks: loopbackRestMocks.map((m) => m.endpointURL),
+            blocking: true,
+        });
+    }
+    // Rule: gRPC mocks use DNS hijacking that doesn't intercept persistent connections
+    if (grpcMocks.length > 0) {
+        warnings.push({
+            code: "GRPC_PERSISTENT_CONN",
+            message: "gRPC mocks use DNS hijacking which does not intercept persistent connections. " +
+                "If the service under test establishes a gRPC connection before mocks are applied, " +
+                "the existing connection will bypass the mock.",
+            suggestion: "Apply gRPC mocks before the service under test starts, or restart " +
+                "the service after applying mocks so it establishes a new connection through the mock DNS. " +
+                "For Docker local-dev, also verify the worker has the original downstream hostname alias " +
+                "from endpointURL (for example, partner-accounts for partner-accounts:50051).",
+            affectedMocks: grpcMocks.map((m) => m.grpcServiceName || m.endpointURL),
+        });
+    }
+    const hasBlockers = warnings.some((w) => w.blocking);
+    return {
+        compatible: !hasBlockers,
+        hasBlockers,
+        warnings,
+    };
+}

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

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

package/build/utils/mockCompatibility.test.js

@@ -0,0 +1,79 @@
+import { validateMockCompatibility, MockProtocol } from "./mockCompatibility.js";
+describe("validateMockCompatibility", () => {
+    it("REST-only mocks produce no warnings (DNS interception works correctly)", () => {
+        const mocks = [
+            { protocol: MockProtocol.Rest, endpointURL: "http://billing:5001/api/users", method: "GET" },
+            { protocol: MockProtocol.Rest, endpointURL: "http://ams:4000/api/orders", method: "POST" },
+        ];
+        const result = validateMockCompatibility(mocks);
+        expect(result.compatible).toBe(true);
+        expect(result.warnings).toHaveLength(0);
+    });
+    it("REST mocks using loopback URLs get a blocking REST_LOOPBACK_URL warning", () => {
+        const mocks = [
+            { protocol: MockProtocol.Rest, endpointURL: "http://localhost:8080/api/users", method: "GET" },
+            { protocol: MockProtocol.Rest, endpointURL: "http://host.docker.internal:4000/api/orders", method: "POST" },
+            { protocol: MockProtocol.Rest, endpointURL: "http://[::1]:8080/api/status", method: "GET" },
+        ];
+        const result = validateMockCompatibility(mocks, { dockerLocalDev: true });
+        expect(result.compatible).toBe(false);
+        expect(result.hasBlockers).toBe(true);
+        const warning = result.warnings.find((w) => w.code === "REST_LOOPBACK_URL");
+        expect(warning).toBeDefined();
+        expect(warning.blocking).toBe(true);
+        expect(warning.affectedMocks).toContain("http://localhost:8080/api/users");
+        expect(warning.affectedMocks).toContain("http://host.docker.internal:4000/api/orders");
+        expect(warning.affectedMocks).toContain("http://[::1]:8080/api/status");
+    });
+    it("does not block loopback REST URLs outside Docker local-dev preflight mode", () => {
+        const mocks = [
+            { protocol: MockProtocol.Rest, endpointURL: "http://localhost:8080/api/users", method: "GET" },
+        ];
+        const result = validateMockCompatibility(mocks);
+        expect(result.compatible).toBe(true);
+        expect(result.hasBlockers).toBe(false);
+        expect(result.warnings.find((w) => w.code === "REST_LOOPBACK_URL")).toBeUndefined();
+    });
+    it("Kafka mocks produce no compatibility warning when generation payload shape is valid", () => {
+        const mocks = [
+            { protocol: MockProtocol.Kafka, endpointURL: "redpanda:9092", kafkaTopic: "user-events" },
+            { protocol: MockProtocol.Rest, endpointURL: "http://ams:4000/api/users", method: "GET" },
+        ];
+        const result = validateMockCompatibility(mocks);
+        expect(result.compatible).toBe(true);
+        expect(result.hasBlockers).toBe(false);
+        expect(result.warnings.find((w) => w.code === "KAFKA_SDK_INCOMPATIBLE")).toBeUndefined();
+    });
+    it("gRPC mocks produce GRPC_PERSISTENT_CONN warning", () => {
+        const mocks = [
+            { protocol: MockProtocol.Grpc, endpointURL: "grpc://localhost:50051", grpcServiceName: "UserService" },
+            { protocol: MockProtocol.Rest, endpointURL: "http://ams:4000/api/users", method: "GET" },
+        ];
+        const result = validateMockCompatibility(mocks);
+        expect(result.compatible).toBe(true);
+        const grpcWarning = result.warnings.find((w) => w.code === "GRPC_PERSISTENT_CONN");
+        expect(grpcWarning).toBeDefined();
+        expect(grpcWarning.affectedMocks).toContain("UserService");
+    });
+    it("gRPC on non-8080 ports is allowed with only the persistent connection warning", () => {
+        const mocks = [
+            { protocol: MockProtocol.Grpc, endpointURL: "partner-accounts:50051", grpcServiceName: "PaymentService" },
+        ];
+        const result = validateMockCompatibility(mocks);
+        expect(result.compatible).toBe(true);
+        expect(result.hasBlockers).toBe(false);
+        expect(result.warnings).toHaveLength(1);
+        expect(result.warnings[0].code).toBe("GRPC_PERSISTENT_CONN");
+        expect(result.warnings.find((w) => w.code === "GRPC_PORT_MISMATCH")).toBeUndefined();
+    });
+    it("gRPC on port 8080 also gets only GRPC_PERSISTENT_CONN", () => {
+        const mocks = [
+            { protocol: MockProtocol.Grpc, endpointURL: "some-service:8080", grpcServiceName: "ProfileService" },
+        ];
+        const result = validateMockCompatibility(mocks);
+        expect(result.compatible).toBe(true);
+        expect(result.hasBlockers).toBe(false);
+        expect(result.warnings).toHaveLength(1);
+        expect(result.warnings[0].code).toBe("GRPC_PERSISTENT_CONN");
+    });
+});

package/build/utils/versions.d.ts

@@ -1,3 +1,3 @@
-export declare const SKYRAMP_IMAGE_VERSION = "v1.3.29";
-export declare const EXECUTOR_DOCKER_IMAGE = "skyramp/executor:v1.3.29";
-export declare const WORKER_DOCKER_IMAGE = "skyramp/worker:v1.3.29";
+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";

package/build/utils/versions.js

@@ -1,3 +1,3 @@
-export const SKYRAMP_IMAGE_VERSION = "v1.3.29";
+export const SKYRAMP_IMAGE_VERSION = "v1.3.30";
 export const EXECUTOR_DOCKER_IMAGE = `skyramp/executor:${SKYRAMP_IMAGE_VERSION}`;
 export const WORKER_DOCKER_IMAGE = `skyramp/worker:${SKYRAMP_IMAGE_VERSION}`;