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

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/pom-verify/verify.d.ts

@@ -10,5 +10,10 @@ export type VerifyResult = {
     unverifiable: string[];
     parseError?: string;
     checkedCalls: number;
+    /** Every POM call found in the spec, verifiable or not. NOT checkedCalls +
+     *  unverifiable.length: `unverifiable` also absorbs `unrecognized` bindings,
+     *  which are not calls at all, so that sum overcounts. This is the count of
+     *  POM members the delivered spec actually reuses. */
+    reusedCalls: number;
 };
 export declare function verifyReuse(testFile: string, language: string): Promise<VerifyResult>;

package/build/utils/pom-verify/verify.js

@@ -182,5 +182,6 @@ export async function verifyReuse(testFile, language) {
         unverifiable,
         parseError,
         checkedCalls,
+        reusedCalls: calls.length,
     };
 }

package/build/utils/progress.js

@@ -10,11 +10,16 @@ export function makeProgressReporter(extra) {
     return async (progress, total, message) => {
         const progressToken = extra._meta?.progressToken;
         if (progressToken !== undefined) {
-            const notification = {
-                method: "notifications/progress",
-                params: { progressToken, progress, total, message },
-            };
-            await extra.sendNotification(notification);
+            try {
+                const notification = {
+                    method: "notifications/progress",
+                    params: { progressToken, progress, total, message },
+                };
+                await extra.sendNotification(notification);
+            }
+            catch {
+                // Progress is best-effort; a disconnected client should not fail the tool.
+            }
         }
     };
 }

package/build/utils/proxy-terminal.js

@@ -334,7 +334,7 @@ export async function closeProxyTerminal() {
                             terminalPID,
                         });
                     }
-                    catch (killErr) {
+                    catch (_killErr) {
                         // Process is already dead, which is what we want
                         logger.debug("Terminal process already terminated", {
                             terminalPID,
@@ -384,14 +384,14 @@ export async function closeProxyTerminal() {
                             terminalPID,
                         });
                     }
-                    catch (killErr) {
+                    catch (_killErr) {
                         // Process is already dead, which is what we want
                         logger.debug("Terminal process already terminated", {
                             terminalPID,
                         });
                     }
                 }
-                catch (pidErr) {
+                catch (_pidErr) {
                     // Fallback to regular process kill
                     try {
                         process.kill(terminalPID, "SIGTERM");

package/build/utils/routeParsers.d.ts

@@ -59,15 +59,9 @@ export declare function isRouteLikeFile(filePath: string): boolean;
  * route that existed in the base branch.
  */
 export declare function selectRemovalCandidateFiles(diffData: BranchDiffData): string[];
-/**
- * Recover endpoints as they existed in the base branch, for the given candidate
- * files. `fetchBaseContent` returns a file's base-branch content (e.g. via
- * `git show base:<file>`); files that throw are skipped. Returns every endpoint
- * found in the base versions — callers pass the result to
- * `classifyEndpointsByChangedFiles`, whose moved/still-present filter drops any
- * endpoint that survives in the current catalog, leaving only genuine removals.
- */
-export declare function recoverRemovedEndpointsFromBase(candidateFiles: string[], fetchBaseContent: (file: string) => Promise<string>): Promise<ScannedEndpoint[]>;
+export declare function recoverRemovedEndpointsFromBase(candidateFiles: string[], fetchBaseContent: (file: string) => Promise<string>, repositoryPath?: string, baseBranch?: string): Promise<ScannedEndpoint[]>;
+/** Strip git's `a/` / `b/` diff-path prefix and normalize separators. */
+export declare function normalizeDiffPath(spec: string): string;
 /**
  * Parse a unified diff into the set of new-side (post-change) line numbers that
  * were touched, keyed by normalized file path.

package/build/utils/routeParsers.js

@@ -1,4 +1,8 @@
-import { joinRoutePrefix } from "./pythonMountPrefixes.js";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { execFileSync } from "child_process";
+import { joinRoutePrefix, resolvePythonMountPrefixes } from "./pythonMountPrefixes.js";
 import { logger } from "./logger.js";
 export function nextjsFileToApiPath(filePath) {
     const pagesMatch = filePath.match(/(?:^|\/)pages\/(api\/.+)\.[jt]sx?$/);
@@ -577,9 +581,80 @@ export function selectRemovalCandidateFiles(diffData) {
  * `classifyEndpointsByChangedFiles`, whose moved/still-present filter drops any
  * endpoint that survives in the current catalog, leaving only genuine removals.
  */
-export async function recoverRemovedEndpointsFromBase(candidateFiles, fetchBaseContent) {
+/**
+ * Materialize just the `.py` files of a git ref into a fresh temp directory
+ * via `git archive` (no full checkout/worktree) — lets `resolvePythonMountPrefixes`
+ * run against the BASE tree unmodified. Best-effort: returns null on any
+ * failure (shallow clone missing the ref, git/tar unavailable, etc.) so the
+ * caller can fall back rather than abort removal recovery.
+ */
+function materializePythonFilesFromRef(repositoryPath, ref) {
+    let tmpDir;
+    try {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "skyramp-base-py-"));
+    }
+    catch {
+        return null;
+    }
+    const archivePath = path.join(tmpDir, "archive.tar");
+    try {
+        execFileSync("git", ["-C", repositoryPath, "archive", "--format=tar", "-o", archivePath, ref, "--", "*.py"], {
+            stdio: ["ignore", "ignore", "ignore"],
+        });
+        execFileSync("tar", ["-xf", archivePath, "-C", tmpDir], { stdio: ["ignore", "ignore", "ignore"] });
+        fs.rmSync(archivePath, { force: true });
+        return tmpDir;
+    }
+    catch (err) {
+        logger.warning("Failed to materialize base-branch Python files for mount-prefix resolution — falling back to current working tree", {
+            ref,
+            error: err instanceof Error ? err.message : String(err),
+        });
+        try {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+        catch {
+            // best-effort cleanup
+        }
+        return null;
+    }
+}
+export async function recoverRemovedEndpointsFromBase(candidateFiles, fetchBaseContent, repositoryPath, baseBranch) {
     const routeFiles = candidateFiles.filter(isRouteLikeFile);
     const endpointMap = new Map();
+    // Cross-file FastAPI mount-prefix resolution, mirroring the main scan
+    // (repoScanner.ts). Without it, a route file whose prefix is applied
+    // externally (app.include_router(router, prefix=...)) yields unmounted
+    // paths here that can never match the fully-mounted current-catalog
+    // paths in classifyEndpointsByChangedFiles's "still exists" check — every
+    // endpoint in that file gets misreported as removed, not just the one
+    // actually deleted (SKYR-4026).
+    //
+    // Resolved from the BASE tree when possible (via a `.py`-only git-archive
+    // extraction), not the current working tree — if a PR also renames the
+    // mount prefix itself (not just the recovered route), head-state prefixes
+    // would rewrite the recovered base endpoint onto the NEW prefix, which
+    // could mask a real removal or misattribute the path. Falls back to the
+    // current working tree if base-tree materialization isn't possible (e.g.
+    // shallow clone, git/tar unavailable) — still strictly better than no
+    // mount-prefix resolution at all.
+    let mountPrefixesByFile;
+    if (repositoryPath && routeFiles.some((f) => f.endsWith(".py"))) {
+        const baseTreeDir = baseBranch ? materializePythonFilesFromRef(repositoryPath, baseBranch) : null;
+        try {
+            mountPrefixesByFile = resolvePythonMountPrefixes(baseTreeDir ?? repositoryPath);
+        }
+        finally {
+            if (baseTreeDir) {
+                try {
+                    fs.rmSync(baseTreeDir, { recursive: true, force: true });
+                }
+                catch {
+                    // best-effort cleanup
+                }
+            }
+        }
+    }
     for (const file of routeFiles) {
         let content;
         try {
@@ -597,7 +672,7 @@ export async function recoverRemovedEndpointsFromBase(candidateFiles, fetchBaseC
             });
             continue;
         }
-        for (const ep of parseFileEndpoints(content, file)) {
+        for (const ep of parseFileEndpoints(content, file, mountPrefixesByFile?.get(file))) {
             // parseFileEndpoints already normalizes paths to a leading slash.
             const key = `${file}::${ep.path}`;
             const existing = endpointMap.get(key);
@@ -620,7 +695,7 @@ export async function recoverRemovedEndpointsFromBase(candidateFiles, fetchBaseC
     }));
 }
 /** Strip git's `a/` / `b/` diff-path prefix and normalize separators. */
-function normalizeDiffPath(spec) {
+export function normalizeDiffPath(spec) {
     let p = spec.replace(/\\/g, "/");
     if (p.startsWith("a/") || p.startsWith("b/"))
         p = p.slice(2);

package/build/utils/utils.js

@@ -69,7 +69,7 @@ export function getPathParameterValidationError(requiredPathParams) {
         return (`Please specify value for the following required path parameter:\n` +
             `${requiredPathParams
                 .split(",")
-                .map((param, index) => `- \`${param.trim()}\``)
+                .map((param) => `- \`${param.trim()}\``)
                 .join("\n")}\n\n`);
     }
 }
@@ -150,7 +150,7 @@ export function validateRequestData(value) {
         JSON.parse(value);
         return value;
     }
-    catch (e) {
+    catch (_e) {
         logger.warning("Request data is not a valid JSON string", { value });
     }
     const isAbsolute = path.isAbsolute(value);

package/build/utils/versions.d.ts

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

package/build/utils/versions.js

@@ -1,3 +1,5 @@
-export const SKYRAMP_IMAGE_VERSION = "v1.3.36";
+export const SKYRAMP_IMAGE_VERSION = "v1.3.37";
 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/build/utils/workspaceAuth.d.ts

@@ -133,3 +133,49 @@ export declare function getWorkspaceAuthConfig(repositoryPath: string): Promise<
 /** True when any workspace service declares api.skipTLSVerify — the SUT serves
  *  self-signed TLS and generated tests must skip cert verification (SKYR-3961). */
 export declare function getWorkspaceSkipTLSVerify(repositoryPath: string): Promise<boolean>;
+/**
+ * Resolve api.defaultQueryParams for test generation — query params always
+ * attached to every generated request for this service (e.g. RBAC context
+ * an authorization layer requires beyond the auth header). Same
+ * first-matching-service convention as getWorkspaceAuthConfig (SKYR-4050).
+ *
+ * Unlike readWorkspaceConfigRaw (which delegates to WorkspaceConfigManager and
+ * resolves EXACTLY `<repositoryPath>/.skyramp/workspace.yml`), this walks up
+ * from `repositoryPath` to find the nearest `.skyramp/workspace.yml` — both
+ * call sites pass a nested test-output directory (e.g. `<repo>/tests/skyramp`),
+ * not the repo root, so an exact-match lookup would silently never find the
+ * config. Mirrors the sync fs.existsSync walk-up in
+ * generateBatchScenarioRestTool.ts.
+ */
+/**
+ * Walk up from `startDir` to find the nearest `.skyramp/workspace.yml`, checking
+ * `startDir` itself first and continuing through every ancestor INCLUDING the
+ * filesystem root — a naive `while (dir !== path.dirname(dir))` loop exits
+ * before ever checking the root candidate, since that equality only becomes
+ * true once `dir` already IS the root. Returns the full config path, or null.
+ * `existsSync` is injectable for testing; defaults to the real filesystem.
+ */
+export declare function findWorkspaceConfigPath(startDir: string, existsSync?: (p: string) => boolean): string | null;
+export declare function getWorkspaceDefaultQueryParams(repositoryPath: string): Promise<Record<string, string> | undefined>;
+/**
+ * Merge workspace-declared default query params into a comma-separated
+ * "key=value,key2=value2" queryParams string (the format used by
+ * baseTestSchema.queryParams). Existing keys always win on collision.
+ */
+export declare function mergeQueryParamsString(existing: string | undefined, defaults: Record<string, string>): string;
+/**
+ * Merge workspace-declared default query params into a JSON-object queryParams
+ * string (the format used by batch-scenario step queryParams). Existing keys
+ * always win on collision. A malformed existingJson is left untouched — the
+ * caller's own JSON.parse warning path still fires downstream.
+ */
+export declare function mergeQueryParamsJson(existingJson: string | undefined, defaults: Record<string, string>): string;
+/**
+ * Resolve auth header and scheme from workspace config for test generation.
+ * Returns null when auth should be skipped (authType absent or "none").
+ * Single source of truth — used by both TestGenerationService and batch scenario tool.
+ */
+export declare function resolveAuthFromWorkspace(repoPath: string, existingAuthHeader?: string, existingAuthScheme?: string): Promise<{
+    authHeader: string;
+    authScheme?: string;
+} | null>;

package/build/utils/workspaceAuth.js

@@ -89,7 +89,20 @@ export async function getWorkspaceBaseUrl(repositoryPath, testFile, language, te
                 return absTestFile.startsWith(absTestDirectory + path.sep) || absTestFile === absTestDirectory;
             });
         });
-        // Step 2: narrow by language if still ambiguous
+        // Step 2: longest-prefix match — when multiple services match (e.g.
+        // tests/skyramp is a prefix of tests/skyramp/cart), pick the service
+        // whose testDirectory is the most specific (longest) prefix of the test file.
+        if (matches.length > 1) {
+            matches.sort((a, b) => {
+                const aLen = path.resolve(repositoryPath, a.testDirectory).length;
+                const bLen = path.resolve(repositoryPath, b.testDirectory).length;
+                return bLen - aLen; // longest first
+            });
+            // Keep only services with the longest matching testDirectory length.
+            const longestLen = path.resolve(repositoryPath, matches[0].testDirectory).length;
+            matches = matches.filter((s) => path.resolve(repositoryPath, s.testDirectory).length === longestLen);
+        }
+        // Step 3: narrow by language if still ambiguous, but don't eliminate all matches
         if (matches.length > 1 && language) {
             const byLanguage = matches.filter((s) => s.language?.toLowerCase() === language.toLowerCase());
             if (byLanguage.length > 0)
@@ -350,3 +363,145 @@ export async function getWorkspaceSkipTLSVerify(repositoryPath) {
         return false;
     return (rawConfig.services ?? []).some((s) => s.api?.skipTLSVerify === true);
 }
+/**
+ * Resolve api.defaultQueryParams for test generation — query params always
+ * attached to every generated request for this service (e.g. RBAC context
+ * an authorization layer requires beyond the auth header). Same
+ * first-matching-service convention as getWorkspaceAuthConfig (SKYR-4050).
+ *
+ * Unlike readWorkspaceConfigRaw (which delegates to WorkspaceConfigManager and
+ * resolves EXACTLY `<repositoryPath>/.skyramp/workspace.yml`), this walks up
+ * from `repositoryPath` to find the nearest `.skyramp/workspace.yml` — both
+ * call sites pass a nested test-output directory (e.g. `<repo>/tests/skyramp`),
+ * not the repo root, so an exact-match lookup would silently never find the
+ * config. Mirrors the sync fs.existsSync walk-up in
+ * generateBatchScenarioRestTool.ts.
+ */
+/**
+ * Walk up from `startDir` to find the nearest `.skyramp/workspace.yml`, checking
+ * `startDir` itself first and continuing through every ancestor INCLUDING the
+ * filesystem root — a naive `while (dir !== path.dirname(dir))` loop exits
+ * before ever checking the root candidate, since that equality only becomes
+ * true once `dir` already IS the root. Returns the full config path, or null.
+ * `existsSync` is injectable for testing; defaults to the real filesystem.
+ */
+export function findWorkspaceConfigPath(startDir, existsSync = fs.existsSync) {
+    const WS_SUBPATH = path.join(".skyramp", "workspace.yml");
+    let searchDir = path.resolve(startDir);
+    while (true) {
+        const candidate = path.join(searchDir, WS_SUBPATH);
+        if (existsSync(candidate))
+            return candidate;
+        const parentDir = path.dirname(searchDir);
+        if (parentDir === searchDir)
+            return null; // reached the filesystem root; already checked above
+        searchDir = parentDir;
+    }
+}
+export async function getWorkspaceDefaultQueryParams(repositoryPath) {
+    const wsConfigPath = findWorkspaceConfigPath(repositoryPath);
+    if (!wsConfigPath)
+        return undefined;
+    try {
+        const raw = fs.readFileSync(wsConfigPath, "utf-8");
+        const parsed = yaml.load(raw);
+        const svc = parsed?.services?.find((s) => s.api?.defaultQueryParams !== undefined);
+        return svc?.api?.defaultQueryParams;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Merge workspace-declared default query params into a comma-separated
+ * "key=value,key2=value2" queryParams string (the format used by
+ * baseTestSchema.queryParams). Existing keys always win on collision.
+ */
+export function mergeQueryParamsString(existing, defaults) {
+    const pairs = new Map();
+    if (existing) {
+        for (const pair of existing.split(",")) {
+            const eqIndex = pair.indexOf("=");
+            if (eqIndex === -1)
+                continue;
+            const key = pair.slice(0, eqIndex).trim();
+            const value = pair.slice(eqIndex + 1).trim();
+            if (key)
+                pairs.set(key, value);
+        }
+    }
+    for (const [key, value] of Object.entries(defaults)) {
+        if (typeof value !== "string") {
+            logger.warning("Skipping workspace defaultQueryParams entry with a non-string value", { key });
+            continue;
+        }
+        if (key.includes(",") || key.includes("=") || value.includes(",") || value.includes("=")) {
+            logger.warning("Skipping workspace defaultQueryParams entry with invalid characters", { key });
+            continue;
+        }
+        if (!pairs.has(key))
+            pairs.set(key, value);
+    }
+    return Array.from(pairs.entries())
+        .map(([key, value]) => `${key}=${value}`)
+        .join(",");
+}
+/**
+ * Merge workspace-declared default query params into a JSON-object queryParams
+ * string (the format used by batch-scenario step queryParams). Existing keys
+ * always win on collision. A malformed existingJson is left untouched — the
+ * caller's own JSON.parse warning path still fires downstream.
+ */
+export function mergeQueryParamsJson(existingJson, defaults) {
+    let parsed = {};
+    if (existingJson) {
+        try {
+            const candidate = JSON.parse(existingJson);
+            if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) {
+                return existingJson;
+            }
+            parsed = candidate;
+        }
+        catch {
+            return existingJson;
+        }
+    }
+    return JSON.stringify({ ...defaults, ...parsed });
+}
+/**
+ * Resolve auth header and scheme from workspace config for test generation.
+ * Returns null when auth should be skipped (authType absent or "none").
+ * Single source of truth — used by both TestGenerationService and batch scenario tool.
+ */
+export async function resolveAuthFromWorkspace(repoPath, existingAuthHeader, existingAuthScheme) {
+    if (existingAuthHeader !== undefined)
+        return null; // caller already specified
+    const wsAuth = await getWorkspaceAuthConfig(repoPath);
+    // Skip auth when explicitly none. When authType is absent, still resolve if
+    // authHeader or authScheme is set (some workspaces specify only the header).
+    if (wsAuth.authType === WorkspaceAuthType.None)
+        return null;
+    if (!wsAuth.authType && !wsAuth.authHeader && !wsAuth.authScheme)
+        return null;
+    let resolvedHeader = wsAuth.authHeader ?? getDefaultAuthHeader(wsAuth.authType);
+    if (!resolvedHeader && wsAuth.authScheme !== undefined) {
+        resolvedHeader = "Authorization";
+    }
+    if (wsAuth.authType === WorkspaceAuthType.ApiKey && !resolvedHeader) {
+        logger.warning("workspace.yml has authType: apiKey but no authHeader is set — " +
+            "requests will be sent without an auth header and will likely receive 401/403. " +
+            "Add authHeader: <X-Your-Key-Header> to .skyramp/workspace.yml.");
+        return null;
+    }
+    if (!resolvedHeader)
+        return null;
+    logger.info("authHeader resolved from workspace config", {
+        authHeader: resolvedHeader,
+        authType: wsAuth.authType,
+    });
+    let authScheme = existingAuthScheme;
+    if (isAuthorizationHeaderName(resolvedHeader)) {
+        authScheme = authScheme ?? wsAuth.authScheme ?? getAuthScheme(wsAuth.authType);
+    }
+    return { authHeader: resolvedHeader, authScheme };
+}

package/build/workspace/frameworks.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Canonical set of supported test frameworks — the single source of truth for
+ * both the workspace `framework` enum and the `framework` tool-param description
+ * in TestTypes.ts. `robot` is Robot Framework (Python). Extend this list when a
+ * new framework is genuinely supported; do not fork it.
+ *
+ * Kept in its own dependency-free module so lightweight consumers (e.g.
+ * TestTypes.ts) can read the list without importing workspace.ts and pulling in
+ * its Node-only dependencies (fs / child_process / js-yaml).
+ */
+export declare const SUPPORTED_FRAMEWORKS: readonly ["playwright", "pytest", "robot", "junit", "vitest", "jest", "mocha", "go", "rspec", "jasmine"];

package/build/workspace/frameworks.js

@@ -0,0 +1,22 @@
+/**
+ * Canonical set of supported test frameworks — the single source of truth for
+ * both the workspace `framework` enum and the `framework` tool-param description
+ * in TestTypes.ts. `robot` is Robot Framework (Python). Extend this list when a
+ * new framework is genuinely supported; do not fork it.
+ *
+ * Kept in its own dependency-free module so lightweight consumers (e.g.
+ * TestTypes.ts) can read the list without importing workspace.ts and pulling in
+ * its Node-only dependencies (fs / child_process / js-yaml).
+ */
+export const SUPPORTED_FRAMEWORKS = [
+    "playwright",
+    "pytest",
+    "robot",
+    "junit",
+    "vitest",
+    "jest",
+    "mocha",
+    "go",
+    "rspec",
+    "jasmine",
+];

package/build/workspace/testSuites.d.ts

@@ -0,0 +1,20 @@
+import type { Service } from "./workspace.js";
+/**
+ * A single test suite (one runtimeDetails.testSuites[] entry) flattened to one
+ * uniform shape, carrying its owning serviceName so routing/aggregation can label
+ * results per suite, and a framework resolved against the service's.
+ */
+export interface NormalizedSuite {
+    serviceName: string;
+    framework?: string;
+    testRunCommand: string;
+    testEnv?: Record<string, string>;
+    /** Repo-relative globs this suite owns, for selector→suite routing. */
+    pathGlobs?: string[];
+}
+/**
+ * Normalizes a service's runtimeDetails.testSuites into a flat list of suites
+ * (SKYR-4002), each carrying its owning serviceName and a framework that falls
+ * back to the service's. Returns [] when the service records no testSuites.
+ */
+export declare function resolveSuites(service: Service): NormalizedSuite[];

package/build/workspace/testSuites.js

@@ -0,0 +1,17 @@
+/**
+ * Normalizes a service's runtimeDetails.testSuites into a flat list of suites
+ * (SKYR-4002), each carrying its owning serviceName and a framework that falls
+ * back to the service's. Returns [] when the service records no testSuites.
+ */
+export function resolveSuites(service) {
+    const suites = service.runtimeDetails?.testSuites;
+    if (!suites)
+        return [];
+    return suites.map((suite) => ({
+        serviceName: service.serviceName,
+        framework: suite.framework ?? service.framework,
+        testRunCommand: suite.testRunCommand,
+        testEnv: suite.testEnv,
+        pathGlobs: suite.pathGlobs,
+    }));
+}