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

package/build/types/TestbotReport.d.ts

@@ -1,6 +1,7 @@
 import type { DriftAction } from "./TestAnalysis.js";
 import type { TestExecutionStatus } from "./TestExecution.js";
 import type { HttpMethod, TestType } from "./TestTypes.js";
+import type { ReuseOutcome } from "./ReuseOutcome.js";
 /**
  * Shape of the JSON report written by skyramp_submit_report and read by testbot
  * for rendering as Markdown. All fields mirror the corresponding Zod schemas in
@@ -18,6 +19,12 @@ export interface TestbotReport {
         scenarioFile?: string;
         traceFile?: string;
         frontendTrace?: string;
+        /** UI tests only: POM code-reuse outcome, present when skyramp_reuse_code ran
+         *  for this test. Server-derived — imported from its source of truth rather
+         *  than re-declared, since that module already exports a plain interface (the
+         *  rest of this file mirrors Zod schemas by hand, which is why only this field
+         *  is imported). Absent in reports from MCP versions predating it. */
+        reuse?: ReuseOutcome;
     }[];
     /** Omitted when no existing tests were found (agent omits the field). */
     testMaintenance?: {

package/build/types/index.d.ts

@@ -2,3 +2,5 @@ export { TestExecutionStatus } from "./TestExecution.js";
 export { DriftAction } from "./TestAnalysis.js";
 export { TestType, HttpMethod } from "./TestTypes.js";
 export type { TestbotReport } from "./TestbotReport.js";
+export { ReuseDeclinedBy, ReuseVerificationOutcome } from "./ReuseOutcome.js";
+export type { ReuseOutcome, ReuseSkippedEntry } from "./ReuseOutcome.js";

package/build/types/index.js

@@ -1,3 +1,4 @@
 export { TestExecutionStatus } from "./TestExecution.js";
 export { DriftAction } from "./TestAnalysis.js";
 export { TestType, HttpMethod } from "./TestTypes.js";
+export { ReuseDeclinedBy, ReuseVerificationOutcome } from "./ReuseOutcome.js";

package/build/utils/AnalysisStateManager.d.ts

@@ -1,3 +1,4 @@
+import type { ReuseRecord } from "../tools/code-refactor/reuse-outcome.js";
 import { TestAnalysisResult, MaintenanceActionCore } from "../types/TestAnalysis.js";
 import { RepositoryAnalysis, AnalysisScope } from "../types/RepositoryAnalysis.js";
 import { PRTestContext } from "./pr-comment-parser.js";
@@ -5,13 +6,34 @@ import { ParsedDiffEndpoint } from "./routeParsers.js";
 import type { CandidateUiPage } from "./uiPageEnumerator.js";
 import type { FrontendFileIntegration } from "../types/FrontendIntegration.js";
 import type { ApprovedPlanItem } from "../types/Recommendation.js";
+import type { ExternalTestRunRecord } from "../types/ExternalTestExecution.js";
 export type { CandidateUiPage } from "./uiPageEnumerator.js";
 export declare function setTestsRepoDir(dir: string | undefined): void;
 export declare function getTestsRepoDir(): string | undefined;
+/** Filename of the run-scoped analysis state file under `<RUNNER_TEMP>/skyramp/`.
+ *  Single-sourced so the constructor that WRITES there and `resolveRunStatePath`
+ *  which LOOKS there cannot drift apart. */
+export declare const RUN_STATE_FILE_NAME = "analyze-changes-state.json";
 export declare function setActiveRunStatePath(stateFilePath: string): void;
 export declare function getActiveRunStatePath(): string | undefined;
 /** Reset the run anchor — for tests, and as a safety hook between runs. */
 export declare function clearActiveRunStatePath(): void;
+/**
+ * The run's state-file path, for tools that need to read or amend it without the
+ * agent naming it.
+ *
+ * `setActiveRunStatePath` is only called by skyramp_analyze_changes on multi-repo
+ * runs (the ones carrying a `repository` param), but a single-repo Testbot run's
+ * path is still deterministic in CI: the StateManager constructor above roots
+ * "analysis" state under `$RUNNER_TEMP/skyramp/`. Falling back to that covers
+ * single-repo runs without a new anchor mechanism. Standalone/IDE usage has no
+ * RUNNER_TEMP and resolves to undefined — correct, since there is no run state.
+ *
+ * Lives here rather than in each caller so the convention has one home: this is
+ * the module that decides where the file goes, so it is the module that should
+ * decide where to look for it.
+ */
+export declare function resolveRunStatePath(explicitPath?: string): string | undefined;
 export declare function registerSession(sessionId: string, stateFilePath: string): void;
 export declare function getSessionFilePath(sessionId: string): string | undefined;
 export declare function getRegisteredSessions(): ReadonlyMap<string, string>;
@@ -133,6 +155,17 @@ export interface UnifiedAnalysisState {
     planBudgetContext?: PlanBudgetContext;
     /** SKYR-3879 Path B — see {@link ApprovedPlan}. */
     approvedPlan?: ApprovedPlan;
+    /**
+     * External (repo-owned) test runs recorded by skyramp_run_existing_tests, one
+     * record per confirm/verify invocation. Drift analysis and the report fold in
+     * CONFIRMED failures from here instead of guessing. Absent until the tool runs.
+     */
+    externalTestResults?: ExternalTestRunRecord[];
+    /** POM code-reuse outcome per generated UI spec, keyed by test-file BASENAME
+     *  (what `newTestsCreated[].fileName` carries). Written by skyramp_reuse_code,
+     *  which computes every value in-process; skyramp_submit_report merges it into
+     *  the report's `reuse` field. Never supplied by the LLM. */
+    reuseOutcomes?: Record<string, ReuseRecord>;
 }
 /**
  * State file metadata

package/build/utils/AnalysisStateManager.js

@@ -35,6 +35,10 @@ export function getTestsRepoDir() {
  * Single-repo / standalone calls (no `repository`) never set or read this.
  */
 let _activeRunStatePath;
+/** Filename of the run-scoped analysis state file under `<RUNNER_TEMP>/skyramp/`.
+ *  Single-sourced so the constructor that WRITES there and `resolveRunStatePath`
+ *  which LOOKS there cannot drift apart. */
+export const RUN_STATE_FILE_NAME = "analyze-changes-state.json";
 export function setActiveRunStatePath(stateFilePath) {
     _activeRunStatePath = stateFilePath;
 }
@@ -45,6 +49,32 @@ export function getActiveRunStatePath() {
 export function clearActiveRunStatePath() {
     _activeRunStatePath = undefined;
 }
+/**
+ * The run's state-file path, for tools that need to read or amend it without the
+ * agent naming it.
+ *
+ * `setActiveRunStatePath` is only called by skyramp_analyze_changes on multi-repo
+ * runs (the ones carrying a `repository` param), but a single-repo Testbot run's
+ * path is still deterministic in CI: the StateManager constructor above roots
+ * "analysis" state under `$RUNNER_TEMP/skyramp/`. Falling back to that covers
+ * single-repo runs without a new anchor mechanism. Standalone/IDE usage has no
+ * RUNNER_TEMP and resolves to undefined — correct, since there is no run state.
+ *
+ * Lives here rather than in each caller so the convention has one home: this is
+ * the module that decides where the file goes, so it is the module that should
+ * decide where to look for it.
+ */
+export function resolveRunStatePath(explicitPath) {
+    if (explicitPath)
+        return explicitPath;
+    const anchored = getActiveRunStatePath();
+    if (anchored)
+        return anchored;
+    if (process.env.RUNNER_TEMP) {
+        return path.join(process.env.RUNNER_TEMP, "skyramp", RUN_STATE_FILE_NAME);
+    }
+    return undefined;
+}
 /**
  * In-memory session store: sessionId → { data, storedAt }.
  * Eliminates the need for the LLM to read/write state files on disk.
@@ -149,7 +179,7 @@ export class StateManager {
             // (see getTestbotPrompt TODO). RUNNER_TEMP is GitHub Actions-specific; other CI systems
             // (Jenkins, GitLab, Buildkite) must set it explicitly. Once merged, path flows through
             // summaryOutputFile which is already testbot-controlled and CI-agnostic.
-            this.stateFile = path.join(process.env.RUNNER_TEMP, "skyramp", "analyze-changes-state.json");
+            this.stateFile = path.join(process.env.RUNNER_TEMP, "skyramp", RUN_STATE_FILE_NAME);
         }
         else {
             const baseDir = stateDir || os.tmpdir();
@@ -246,7 +276,11 @@ export class StateManager {
                     repository: options?.repository ?? existingMetadata?.repository,
                     createdAt: existingMetadata?.createdAt || new Date().toISOString(),
                     updatedAt: new Date().toISOString(),
-                    step: options?.step,
+                    // Preserve the prior step when the caller omits one (matches
+                    // repositoryPath/repository/createdAt above) so a metadata-agnostic
+                    // write — e.g. persistExternalRun appending externalTestResults —
+                    // does not wipe the pipeline step recorded by an earlier phase.
+                    step: options?.step ?? existingMetadata?.step,
                 },
                 ...(existingRelated ? { relatedRepos: existingRelated } : {}),
             };

package/build/utils/analyze-openapi.js

@@ -1,5 +1,10 @@
 import { SkyrampClient } from "@skyramp/skyramp";
 import { IsValidKeyValueList } from "./utils.js";
+import { logger } from "./logger.js";
+function isOpenApiRuntimeFailure(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /(?:ECONNREFUSED|ECONNRESET|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|socket hang up|connection refused|unavailable|timed? out)/i.test(message);
+}
 // Analyze OpenAPI to check for required path params
 export async function analyzeOpenAPIWithGivenEndpoint(apiSchemaInput, uriInput, pathParamsInput) {
     const client = new SkyrampClient();
@@ -7,7 +12,19 @@ export async function analyzeOpenAPIWithGivenEndpoint(apiSchemaInput, uriInput,
         apiSchema: apiSchemaInput,
         uri: uriInput,
     };
-    const pathParamRequired = await client.analyzeOpenapi(analyzeOpenapiOptions);
+    let pathParamRequired;
+    try {
+        pathParamRequired = await client.analyzeOpenapi(analyzeOpenapiOptions);
+    }
+    catch (e) {
+        if (isOpenApiRuntimeFailure(e)) {
+            logger.warning("Skipping OpenAPI path-param validation because schema analysis is unavailable", {
+                error: e instanceof Error ? e.message : String(e),
+            });
+            return null;
+        }
+        throw e;
+    }
     if (IsValidKeyValueList(pathParamRequired)) {
         const requiredPathParams = pathParamRequired
             ? pathParamRequired.split(",").map((p) => p.trim())

package/build/utils/branchDiff.d.ts

@@ -15,4 +15,20 @@ export interface BranchDiffData {
  * Always uses the `b/` form so renames return the new path.
  */
 export declare function parseChangedFilesFromDiff(rawDiff: string): string[];
-export declare function computeBranchDiff(repositoryPath: string, providedBaseBranch?: string): Promise<BranchDiffData>;
+/**
+ * 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 declare function normalizeProvidedBaseRef(providedBaseBranch?: string): string | undefined;
+/**
+ * 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 declare function computeBranchDiff(repositoryPath: string, providedBaseBranch?: string, includeUncommitted?: boolean): Promise<BranchDiffData>;

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,87 @@ 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.`);
+    }
+    if (trimmed.includes("..")) {
+        throw new Error(`Invalid base branch/ref "${providedBaseBranch}": range syntax (".."/""..."") is not allowed — provide a single ref.`);
+    }
+    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 +126,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 +173,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/featureFlags.d.ts

@@ -35,3 +35,34 @@ 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;
+/**
+ * Gates the POM-aware path of `skyramp_reuse_code`
+ * (SKYRAMP_FEATURE_POM_REUSE=1).
+ *
+ * When OFF (default), TypeScript/JavaScript + Playwright targets are treated
+ * like every other target: `skyramp_reuse_code` returns the SkyrampUtils
+ * consolidation prompt, and none of the POM machinery runs — no deterministic
+ * POM pre-scoping, no POM catalog / mapping-table workflow, no `verify: true`
+ * compliance gates, and consequently no `reuse` summary on the report (nothing
+ * records an outcome to re-derive).
+ *
+ * When ON, the test is refactored against the repo's existing page objects and
+ * the verification gates apply.
+ */
+export declare function isPomReuseEnabled(): boolean;

package/build/utils/featureFlags.js

@@ -39,3 +39,40 @@ 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";
+}
+/**
+ * Gates the POM-aware path of `skyramp_reuse_code`
+ * (SKYRAMP_FEATURE_POM_REUSE=1).
+ *
+ * When OFF (default), TypeScript/JavaScript + Playwright targets are treated
+ * like every other target: `skyramp_reuse_code` returns the SkyrampUtils
+ * consolidation prompt, and none of the POM machinery runs — no deterministic
+ * POM pre-scoping, no POM catalog / mapping-table workflow, no `verify: true`
+ * compliance gates, and consequently no `reuse` summary on the report (nothing
+ * records an outcome to re-derive).
+ *
+ * When ON, the test is refactored against the repo's existing page objects and
+ * the verification gates apply.
+ */
+export function isPomReuseEnabled() {
+    return process.env.SKYRAMP_FEATURE_POM_REUSE === "1";
+}

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/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,15 @@
+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 (!normalized)
+        return null; // whitespace-only → treated as empty (valid)
+    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/logger.js

@@ -22,7 +22,7 @@ export class McpLogger {
         try {
             console.error(JSON.stringify(logEntry));
         }
-        catch (error) {
+        catch (_error) {
             // silently ignore
         }
     }

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;