@skyramp/mcp 0.2.8 → 0.2.150-rc.local.de

package/build/utils/branchDiff.js

@@ -14,6 +14,9 @@ export function parseChangedFilesFromDiff(rawDiff) {
     return out;
 }
 /** Parse diff headers to find newly created and deleted files. */
+function isShaLikeRef(ref) {
+    return /^[0-9a-f]{7,40}$/i.test(ref);
+}
 function parseNewAndDeletedFiles(rawDiff) {
     const newFiles = [];
     const deletedFiles = [];
@@ -34,24 +37,84 @@ function parseNewAndDeletedFiles(rawDiff) {
     }
     return { newFiles, deletedFiles };
 }
-async function tryDiff(git, ref) {
+/**
+ * Normalize and validate a caller-provided base branch/ref before passing it
+ * to git. Reject option-like or ambiguous values so the ref is always treated
+ * as a revision name, not as a command-line flag.
+ */
+export function normalizeProvidedBaseRef(providedBaseBranch) {
+    if (providedBaseBranch === undefined)
+        return undefined;
+    const trimmed = providedBaseBranch.trim();
+    if (!trimmed)
+        return undefined;
+    if (trimmed.startsWith("-")) {
+        throw new Error(`Invalid base branch/ref "${providedBaseBranch}": refs must not start with '-'.`);
+    }
+    if (/\s/.test(trimmed) || trimmed.includes("\0")) {
+        throw new Error(`Invalid base branch/ref "${providedBaseBranch}": refs must not contain whitespace or NUL characters.`);
+    }
+    return trimmed;
+}
+async function tryDiff(git, ref, includeUncommitted = false) {
     try {
-        const changedFilesRaw = await git.diff([`${ref}...HEAD`, "--name-only"]);
+        // When includeUncommitted is true, diff the ref directly against the
+        // working tree so uncommitted/unstaged local changes are captured.
+        const diffRange = includeUncommitted ? ref : `${ref}...HEAD`;
+        const changedFilesRaw = await git.diff([diffRange, "--name-only"]);
         const changedFiles = changedFilesRaw
             .split("\n")
             .map((f) => f.trim())
             .filter((f) => f.length > 0);
-        const diffStat = await git.diff([`${ref}...HEAD`, "--stat"]);
-        const fullDiff = await git.diff([`${ref}...HEAD`]);
+        const diffStat = await git.diff([diffRange, "--stat"]);
+        const fullDiff = await git.diff([diffRange]);
         const { newFiles, deletedFiles } = parseNewAndDeletedFiles(fullDiff);
-        return { changedFiles, diffContent: fullDiff, diffStat, newFiles, deletedFiles };
+        // git diff does not include untracked files. Include them as both changed
+        // and new so endpoint classification treats newly created local files as new.
+        if (includeUncommitted) {
+            const statusResult = await git.status();
+            const untrackedFiles = statusResult.not_added ?? [];
+            if (untrackedFiles.length > 0) {
+                const changedSet = new Set(changedFiles);
+                const newSet = new Set(newFiles);
+                for (const file of untrackedFiles) {
+                    if (!changedSet.has(file)) {
+                        changedFiles.push(file);
+                        changedSet.add(file);
+                    }
+                    if (!newSet.has(file)) {
+                        newFiles.push(file);
+                        newSet.add(file);
+                    }
+                }
+            }
+        }
+        return {
+            changedFiles,
+            diffContent: fullDiff,
+            diffStat,
+            newFiles,
+            deletedFiles,
+        };
     }
     catch (err) {
-        logger.debug(`tryDiff against ${ref} failed`, { error: err instanceof Error ? err.message : String(err) });
+        logger.debug(`tryDiff against ${ref} failed`, {
+            error: err instanceof Error ? err.message : String(err),
+        });
         return undefined;
     }
 }
-export async function computeBranchDiff(repositoryPath, providedBaseBranch) {
+/**
+ * Compute the diff between a base reference and the current state.
+ *
+ * @param repositoryPath  Absolute path to the git repository.
+ * @param providedBaseBranch  A branch name, tag, or commit SHA to diff against.
+ *   When omitted, the remote default branch is auto-detected.
+ * @param includeUncommitted  When true, diffs against the working tree so
+ *   uncommitted/unstaged changes are included. Defaults to false (CI mode
+ *   that only considers committed changes via the three-dot form).
+ */
+export async function computeBranchDiff(repositoryPath, providedBaseBranch, includeUncommitted = false) {
     const git = simpleGit(repositoryPath);
     const isRepo = await git.checkIsRepo();
     if (!isRepo) {
@@ -60,14 +123,32 @@ export async function computeBranchDiff(repositoryPath, providedBaseBranch) {
     const branchInfo = await git.branch();
     const currentBranch = branchInfo.current || "HEAD";
     // Build candidate base refs in priority order:
-    // 1. Provided branch name (most specific)
-    // 2. Remote default branch auto-detected from available remotes
-    // 3. FETCH_HEAD — present in base_commit repos (git fetch --depth 1 origin <sha>)
+    // 1. Provided value used directly (supports SHAs, local branches, tags)
+    // 2. Provided value with origin/ prefix (remote branch)
+    // 3. Remote default branch auto-detected from available remotes
+    // 4. FETCH_HEAD — present in base_commit repos (git fetch --depth 1 origin <sha>)
     //    where no remote tracking branch is created
-    // 4. HEAD~1 — last resort for repos with no remote at all
+    // 5. HEAD~1 — last resort for repos with no remote at all
     const candidates = [];
-    if (providedBaseBranch) {
-        candidates.push(`origin/${providedBaseBranch}`);
+    const normalizedBaseBranch = normalizeProvidedBaseRef(providedBaseBranch);
+    if (normalizedBaseBranch) {
+        const isRemoteQualified = normalizedBaseBranch.startsWith("origin/");
+        const looksLikeSimpleBranch = !isRemoteQualified &&
+            !isShaLikeRef(normalizedBaseBranch) &&
+            !/[~^:@]/.test(normalizedBaseBranch);
+        if (includeUncommitted && looksLikeSimpleBranch) {
+            // Local-dev diffs should prefer the remote base branch when available;
+            // a developer's local main may be ahead of origin/main.
+            candidates.push(`origin/${normalizedBaseBranch}`);
+            candidates.push(normalizedBaseBranch);
+        }
+        else {
+            // Try the raw value first — handles commit SHAs, tags, and explicit local refs.
+            candidates.push(normalizedBaseBranch);
+            if (!isRemoteQualified) {
+                candidates.push(`origin/${normalizedBaseBranch}`);
+            }
+        }
     }
     // Auto-detect remote default branch
     try {
@@ -89,12 +170,13 @@ export async function computeBranchDiff(repositoryPath, providedBaseBranch) {
     // Final fallback
     candidates.push("HEAD~1");
     for (const ref of candidates) {
-        const result = await tryDiff(git, ref);
+        const result = await tryDiff(git, ref, includeUncommitted);
         if (result) {
             logger.info("Branch diff computed", {
                 currentBranch,
                 baseBranch: ref,
                 changedFiles: result.changedFiles.length,
+                includeUncommitted,
             });
             return { currentBranch, baseBranch: ref, ...result };
         }

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

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

package/build/utils/branchDiff.test.js

@@ -0,0 +1,107 @@
+import { execFileSync } from "child_process";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { computeBranchDiff, normalizeProvidedBaseRef } from "./branchDiff.js";
+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,14 @@ 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;

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,16 @@ 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";
+}

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}". 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}". 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;