@skyramp/mcp 0.2.5 → 0.2.7

package/build/utils/uiPageEnumerator.test.js

@@ -1,13 +1,20 @@
-// Mock @skyramp/skyramp so workspaceAuth's import resolves; readWorkspaceConfigRaw
-// itself is mocked per-test below.
-jest.mock("@skyramp/skyramp", () => ({
-    WorkspaceConfigManager: { create: jest.fn() },
-}));
+// @ts-nocheck - Jest ESM type inference issues
+import { jest } from "@jest/globals";
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
-import { frameworkFileToUrlPath, findCandidatePagesByFrameworkRoute, findCandidatePagesBySourceRoute, findRootFallbackPage, enumerateCandidateUiPages, pickFrontendBaseUrl, detectsFilesystemRouting, } from "./uiPageEnumerator.js";
-import * as workspaceAuth from "./workspaceAuth.js";
+// Under native ESM, imported module namespaces are read-only, so jest.spyOn on
+// workspaceAuth fails. Partial-mock the module: keep every real export the
+// subject's import graph needs and override only readWorkspaceConfigRaw.
+// jest.requireActual can't load an ESM module synchronously, so import the real
+// module first (unstable_mockModule is not hoisted) and spread its namespace.
+const realWorkspaceAuth = await import("./workspaceAuth.js");
+const readWorkspaceConfigRaw = jest.fn();
+jest.unstable_mockModule("./workspaceAuth.js", () => ({
+    ...realWorkspaceAuth,
+    readWorkspaceConfigRaw,
+}));
+const { frameworkFileToUrlPath, findCandidatePagesByFrameworkRoute, findCandidatePagesBySourceRoute, findRootFallbackPage, enumerateCandidateUiPages, pickFrontendBaseUrl, detectsFilesystemRouting, } = await import("./uiPageEnumerator.js");
 // Helper to create a tmp repo dir with optional config files; returns the path.
 function makeTmpRepo(configFiles = []) {
     const dir = fs.mkdtempSync(path.join(os.tmpdir(), "skyramp-test-repo-"));
@@ -191,25 +198,21 @@ export default function App() {
 // pickFrontendBaseUrl
 // ---------------------------------------------------------------------------
 describe("pickFrontendBaseUrl", () => {
-    let readSpy;
-    beforeEach(() => {
-        readSpy = jest.spyOn(workspaceAuth, "readWorkspaceConfigRaw");
-    });
     afterEach(() => {
-        readSpy.mockRestore();
+        readWorkspaceConfigRaw.mockReset();
     });
     it("returns null when workspace config is missing", async () => {
-        readSpy.mockResolvedValue(null);
+        readWorkspaceConfigRaw.mockResolvedValue(null);
         expect(await pickFrontendBaseUrl("/repo")).toBeNull();
     });
     it("returns null when no services have baseUrl", async () => {
-        readSpy.mockResolvedValue({
+        readWorkspaceConfigRaw.mockResolvedValue({
             services: [{ serviceName: "backend", language: "python" }],
         });
         expect(await pickFrontendBaseUrl("/repo")).toBeNull();
     });
     it("picks the frontend service by name suffix", async () => {
-        readSpy.mockResolvedValue({
+        readWorkspaceConfigRaw.mockResolvedValue({
             services: [
                 { serviceName: "demoshop-backend", api: { baseUrl: "http://localhost:8000" } },
                 { serviceName: "demoshop-frontend", api: { baseUrl: "http://localhost:5173" } },
@@ -218,7 +221,7 @@ describe("pickFrontendBaseUrl", () => {
         expect(await pickFrontendBaseUrl("/repo")).toBe("http://localhost:5173");
     });
     it("picks the frontend service by framework when name doesn't signal it", async () => {
-        readSpy.mockResolvedValue({
+        readWorkspaceConfigRaw.mockResolvedValue({
             services: [
                 { serviceName: "api", language: "python", api: { baseUrl: "http://localhost:8000" } },
                 {
@@ -232,7 +235,7 @@ describe("pickFrontendBaseUrl", () => {
         expect(await pickFrontendBaseUrl("/repo")).toBe("http://localhost:3000");
     });
     it("falls back to first service with baseUrl when no frontend signal", async () => {
-        readSpy.mockResolvedValue({
+        readWorkspaceConfigRaw.mockResolvedValue({
             services: [
                 { serviceName: "svc-a", language: "go", api: { baseUrl: "http://localhost:8000" } },
                 { serviceName: "svc-b", language: "go", api: { baseUrl: "http://localhost:8001" } },
@@ -247,7 +250,7 @@ describe("pickFrontendBaseUrl", () => {
     // frameworks. Without this, the agent never reaches the browser regardless
     // of the .dart classifier fix.
     it("picks the Flutter playwright-framework service by name suffix", async () => {
-        readSpy.mockResolvedValue({
+        readWorkspaceConfigRaw.mockResolvedValue({
             services: [
                 {
                     serviceName: "birdle-frontend",
@@ -264,7 +267,7 @@ describe("pickFrontendBaseUrl", () => {
     // allow-list. The chosen URL must come from H3 (first service with baseUrl).
     // We add a second service to prove H3 picked the first, not H1 by accident.
     it("falls back to first service when name+framework don't match H1 or H2", async () => {
-        readSpy.mockResolvedValue({
+        readWorkspaceConfigRaw.mockResolvedValue({
             services: [
                 {
                     serviceName: "birdle",
@@ -282,24 +285,205 @@ describe("pickFrontendBaseUrl", () => {
         });
         expect(await pickFrontendBaseUrl("/repo")).toBe("http://localhost:8080");
     });
+    // SKYR-3812: Environment variable override tests
+    describe("env var overrides (SKYR-3812)", () => {
+        let originalGlobal;
+        let originalPerSvc = {};
+        beforeEach(() => {
+            // Snapshot env vars this suite may touch so we can restore them exactly.
+            originalGlobal = process.env.SKYRAMP_TEST_BASE_URL;
+            originalPerSvc = {};
+            for (const key of Object.keys(process.env)) {
+                if (key.startsWith("SKYRAMP_TEST_SERVICE_URL_")) {
+                    originalPerSvc[key] = process.env[key];
+                }
+            }
+        });
+        afterEach(() => {
+            // Restore the global override.
+            if (originalGlobal === undefined) {
+                delete process.env.SKYRAMP_TEST_BASE_URL;
+            }
+            else {
+                process.env.SKYRAMP_TEST_BASE_URL = originalGlobal;
+            }
+            // Restore per-service vars: reset the union of keys that existed before
+            // the test and keys the test set, so neither pre-existing values nor
+            // test-set values leak across tests or out of the suite.
+            const keys = new Set([
+                ...Object.keys(originalPerSvc),
+                ...Object.keys(process.env).filter((k) => k.startsWith("SKYRAMP_TEST_SERVICE_URL_")),
+            ]);
+            for (const key of keys) {
+                if (originalPerSvc[key] === undefined) {
+                    delete process.env[key];
+                }
+                else {
+                    process.env[key] = originalPerSvc[key];
+                }
+            }
+            readWorkspaceConfigRaw.mockReset();
+        });
+        it("SKYRAMP_TEST_BASE_URL (global) overrides workspace.yml baseUrl", async () => {
+            readWorkspaceConfigRaw.mockResolvedValue({
+                services: [
+                    {
+                        serviceName: "frontend",
+                        api: { baseUrl: "http://localhost:3000" },
+                    },
+                ],
+            });
+            process.env.SKYRAMP_TEST_BASE_URL = "https://preview.example.com";
+            expect(await pickFrontendBaseUrl("/repo")).toBe("https://preview.example.com");
+        });
+        it("per-service SKYRAMP_TEST_SERVICE_URL_<NAME> overrides for the picked frontend service", async () => {
+            readWorkspaceConfigRaw.mockResolvedValue({
+                services: [
+                    { serviceName: "backend", api: { baseUrl: "http://localhost:8000" } },
+                    {
+                        serviceName: "demoshop-frontend",
+                        api: { baseUrl: "http://localhost:5173" },
+                    },
+                ],
+            });
+            process.env.SKYRAMP_TEST_SERVICE_URL_DEMOSHOP_FRONTEND =
+                "https://frontend-preview.example.com";
+            expect(await pickFrontendBaseUrl("/repo")).toBe("https://frontend-preview.example.com");
+        });
+        it("sanitizes service name: hyphens, dots, colons, slashes to underscores", async () => {
+            readWorkspaceConfigRaw.mockResolvedValue({
+                services: [
+                    {
+                        serviceName: "supabase-nextjs",
+                        api: { baseUrl: "http://localhost:3000" },
+                    },
+                ],
+            });
+            process.env.SKYRAMP_TEST_SERVICE_URL_SUPABASE_NEXTJS =
+                "https://supabase-preview.example.com";
+            expect(await pickFrontendBaseUrl("/repo")).toBe("https://supabase-preview.example.com");
+        });
+        it("sanitizes service name with dot: my.app -> MY_APP", async () => {
+            readWorkspaceConfigRaw.mockResolvedValue({
+                services: [
+                    { serviceName: "my.app", api: { baseUrl: "http://localhost:3000" } },
+                ],
+            });
+            process.env.SKYRAMP_TEST_SERVICE_URL_MY_APP =
+                "https://myapp-preview.example.com";
+            expect(await pickFrontendBaseUrl("/repo")).toBe("https://myapp-preview.example.com");
+        });
+        it("sanitizes service name with colon: proto://app -> PROTO___APP", async () => {
+            readWorkspaceConfigRaw.mockResolvedValue({
+                services: [
+                    {
+                        serviceName: "proto://app",
+                        api: { baseUrl: "http://localhost:3000" },
+                    },
+                ],
+            });
+            process.env.SKYRAMP_TEST_SERVICE_URL_PROTO___APP =
+                "https://proto-preview.example.com";
+            expect(await pickFrontendBaseUrl("/repo")).toBe("https://proto-preview.example.com");
+        });
+        it("per-service takes precedence over global when both are set", async () => {
+            readWorkspaceConfigRaw.mockResolvedValue({
+                services: [
+                    {
+                        serviceName: "frontend",
+                        api: { baseUrl: "http://localhost:3000" },
+                    },
+                ],
+            });
+            process.env.SKYRAMP_TEST_BASE_URL = "https://global-preview.example.com";
+            process.env.SKYRAMP_TEST_SERVICE_URL_FRONTEND =
+                "https://per-service-preview.example.com";
+            expect(await pickFrontendBaseUrl("/repo")).toBe("https://per-service-preview.example.com");
+        });
+        it("empty/whitespace global env var is ignored, falls back to workspace.yml", async () => {
+            readWorkspaceConfigRaw.mockResolvedValue({
+                services: [
+                    {
+                        serviceName: "frontend",
+                        api: { baseUrl: "http://localhost:3000" },
+                    },
+                ],
+            });
+            process.env.SKYRAMP_TEST_BASE_URL = "   ";
+            expect(await pickFrontendBaseUrl("/repo")).toBe("http://localhost:3000");
+        });
+        it("empty/whitespace per-service env var is ignored, falls back to global", async () => {
+            readWorkspaceConfigRaw.mockResolvedValue({
+                services: [
+                    {
+                        serviceName: "frontend",
+                        api: { baseUrl: "http://localhost:3000" },
+                    },
+                ],
+            });
+            process.env.SKYRAMP_TEST_BASE_URL = "https://global-preview.example.com";
+            process.env.SKYRAMP_TEST_SERVICE_URL_FRONTEND = "   ";
+            expect(await pickFrontendBaseUrl("/repo")).toBe("https://global-preview.example.com");
+        });
+        it("global override returned even with no matching service", async () => {
+            readWorkspaceConfigRaw.mockResolvedValue({
+                services: [
+                    {
+                        serviceName: "backend",
+                        language: "python",
+                        api: { baseUrl: "http://localhost:8000" },
+                    },
+                ],
+            });
+            process.env.SKYRAMP_TEST_BASE_URL = "https://global-preview.example.com";
+            // pickFrontendBaseUrl will select the first service with baseUrl (H3), but the override takes precedence
+            expect(await pickFrontendBaseUrl("/repo")).toBe("https://global-preview.example.com");
+        });
+        it("existing no-override behavior still returns workspace.yml value", async () => {
+            readWorkspaceConfigRaw.mockResolvedValue({
+                services: [
+                    {
+                        serviceName: "frontend",
+                        api: { baseUrl: "http://localhost:3000" },
+                    },
+                ],
+            });
+            // No env vars set
+            expect(await pickFrontendBaseUrl("/repo")).toBe("http://localhost:3000");
+        });
+        it("does not throw when picked service has a non-string serviceName (unvalidated YAML)", async () => {
+            // readWorkspaceConfigRaw can fall back to an unvalidated YAML parse where
+            // serviceName is e.g. a number. The per-service guard must skip it rather
+            // than calling sanitizeServiceName on a non-string and throwing.
+            readWorkspaceConfigRaw.mockResolvedValue({
+                services: [
+                    {
+                        serviceName: 123,
+                        language: "typescript",
+                        framework: "next",
+                        api: { baseUrl: "http://localhost:3000" },
+                    },
+                ],
+            });
+            process.env.SKYRAMP_TEST_BASE_URL = "https://global-preview.example.com";
+            // Falls through the per-service branch to the global override.
+            expect(await pickFrontendBaseUrl("/repo")).toBe("https://global-preview.example.com");
+        });
+    });
 });
 // ---------------------------------------------------------------------------
 // findRootFallbackPage
 // ---------------------------------------------------------------------------
 describe("findRootFallbackPage", () => {
-    let readSpy;
-    beforeEach(() => {
-        readSpy = jest.spyOn(workspaceAuth, "readWorkspaceConfigRaw");
-    });
     afterEach(() => {
-        readSpy.mockRestore();
+        readWorkspaceConfigRaw.mockReset();
     });
     it("returns null when no frontend baseUrl resolvable", async () => {
-        readSpy.mockResolvedValue(null);
+        readWorkspaceConfigRaw.mockResolvedValue(null);
         expect(await findRootFallbackPage("/repo")).toBeNull();
     });
     it("returns root-fallback page when frontend baseUrl resolves", async () => {
-        readSpy.mockResolvedValue({
+        readWorkspaceConfigRaw.mockResolvedValue({
             services: [{ serviceName: "frontend", api: { baseUrl: "http://localhost:3000" } }],
         });
         const page = await findRootFallbackPage("/repo");
@@ -314,22 +498,18 @@ describe("findRootFallbackPage", () => {
 // enumerateCandidateUiPages
 // ---------------------------------------------------------------------------
 describe("enumerateCandidateUiPages", () => {
-    let readSpy;
-    beforeEach(() => {
-        readSpy = jest.spyOn(workspaceAuth, "readWorkspaceConfigRaw");
-    });
     afterEach(() => {
-        readSpy.mockRestore();
+        readWorkspaceConfigRaw.mockReset();
     });
     it("returns empty for empty file list", async () => {
         expect(await enumerateCandidateUiPages("/repo", [])).toEqual([]);
     });
     it("returns empty when workspace has no resolvable baseUrl", async () => {
-        readSpy.mockResolvedValue(null);
+        readWorkspaceConfigRaw.mockResolvedValue(null);
         expect(await enumerateCandidateUiPages("/repo", ["app/orders/page.tsx"])).toEqual([]);
     });
     it("uses strategy 1 (framework-route-grep) when route files match", async () => {
-        readSpy.mockResolvedValue({
+        readWorkspaceConfigRaw.mockResolvedValue({
             services: [{ serviceName: "frontend", api: { baseUrl: "http://localhost:3000" } }],
         });
         const repo = makeTmpRepo(["next.config.js"]);
@@ -345,7 +525,7 @@ describe("enumerateCandidateUiPages", () => {
         fs.rmSync(repo, { recursive: true, force: true });
     });
     it("falls back to strategy 3 (root-fallback) when no route files match", async () => {
-        readSpy.mockResolvedValue({
+        readWorkspaceConfigRaw.mockResolvedValue({
             services: [{ serviceName: "frontend", api: { baseUrl: "http://localhost:3000" } }],
         });
         const pages = await enumerateCandidateUiPages("/repo", [
@@ -359,7 +539,7 @@ describe("enumerateCandidateUiPages", () => {
         });
     });
     it("emits multiple route pages when several match strategy 1", async () => {
-        readSpy.mockResolvedValue({
+        readWorkspaceConfigRaw.mockResolvedValue({
             services: [{ serviceName: "frontend", api: { baseUrl: "http://localhost:3000" } }],
         });
         // Need a real repoPath with framework config so detectsFilesystemRouting passes.
@@ -377,7 +557,7 @@ describe("enumerateCandidateUiPages", () => {
         fs.rmSync(repo, { recursive: true, force: true });
     });
     it("uses strategy 2 (source-grounded-routes) when strategy 1 doesn't match but routes are declared in source", async () => {
-        readSpy.mockResolvedValue({
+        readWorkspaceConfigRaw.mockResolvedValue({
             services: [{ serviceName: "frontend", api: { baseUrl: "http://localhost:5173" } }],
         });
         // Repo with no framework config (so strategy 1 won't fire) but with a
@@ -401,7 +581,7 @@ export default function App() { return <Routes><Route path="/cart" element={<Car
         fs.rmSync(repo, { recursive: true, force: true });
     });
     it("falls back to root when repo lacks a framework config (no false positives)", async () => {
-        readSpy.mockResolvedValue({
+        readWorkspaceConfigRaw.mockResolvedValue({
             services: [{ serviceName: "frontend", api: { baseUrl: "http://localhost:3000" } }],
         });
         // Repo has files matching the Pages Router pattern but no next.config —
@@ -423,7 +603,7 @@ export default function App() { return <Routes><Route path="/cart" element={<Car
     // (no framework config; TS extractor doesn't see .dart; no GoRoute calls).
     // Result: root-fallback with the workspace baseUrl.
     it("returns root-fallback for a Flutter repo with no GoRoute declarations", async () => {
-        readSpy.mockResolvedValue({
+        readWorkspaceConfigRaw.mockResolvedValue({
             services: [
                 {
                     serviceName: "birdle-frontend",
@@ -449,7 +629,7 @@ export default function App() { return <Routes><Route path="/cart" element={<Car
     // surfaces every absolute route as a candidate URL via the all-routes
     // fallback. Diff-match narrowing is exercised by the next test.
     it("returns dart-go-router URLs for a Flutter repo with GoRoute declarations", async () => {
-        readSpy.mockResolvedValue({
+        readWorkspaceConfigRaw.mockResolvedValue({
             services: [
                 {
                     serviceName: "books-frontend",
@@ -482,7 +662,7 @@ final router = GoRouter(routes: [
     // whose screen file is in frontendFiles. The fixture has 3 routes; only
     // /authors's screen file (lib/src/screens/authors.dart) is in the diff.
     it("narrows GoRouter candidates to routes whose screen file is in the diff", async () => {
-        readSpy.mockResolvedValue({
+        readWorkspaceConfigRaw.mockResolvedValue({
             services: [
                 {
                     serviceName: "books-frontend",
@@ -519,7 +699,7 @@ final router = GoRouter(routes: [
     // route is redirect-only, so we should fall back to the non-redirect-only
     // routes.
     it("filters out redirect-only GoRoutes", async () => {
-        readSpy.mockResolvedValue({
+        readWorkspaceConfigRaw.mockResolvedValue({
             services: [
                 {
                     serviceName: "frontend",
@@ -547,7 +727,7 @@ final router = GoRouter(routes: [
     // file edited but our import-resolution heuristic missed the screen), surface
     // ALL renderable routes rather than collapsing to empty.
     it("falls back to all renderable routes when no screen file matches the diff", async () => {
-        readSpy.mockResolvedValue({
+        readWorkspaceConfigRaw.mockResolvedValue({
             services: [
                 {
                     serviceName: "frontend",
@@ -580,7 +760,7 @@ final router = GoRouter(routes: [
     // (e.g. shelf_router uses similar names in tests) must NOT trigger Strategy
     // 2.5 — pubspec.yaml lacks `sdk: flutter`, hasFlutterSdkDep returns false.
     it("does not invoke Dart extractor when pubspec.yaml lacks sdk: flutter", async () => {
-        readSpy.mockResolvedValue({
+        readWorkspaceConfigRaw.mockResolvedValue({
             services: [
                 {
                     serviceName: "server-frontend",

package/build/utils/utils.d.ts

@@ -0,0 +1,39 @@
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export declare function readDiffFile(diffFilePath: string | undefined): string | undefined;
+export declare function toolError(message: string): CallToolResult;
+/**
+ * Happy-path counterpart to `toolError`. Wraps a single text payload in the
+ * MCP tool-result shape so handlers don't have to construct
+ * `{ content: [{ type: "text", text }] }` boilerplate themselves.
+ */
+export declare function toolText(text: string): CallToolResult;
+export declare const OUTPUT_DIR_FIELD_NAME = "outputDir";
+export declare const TRACE_OUTPUT_FILE_FIELD_NAME = "traceOutputFile";
+export declare const PLAYWRIGHT_OUTPUT_FILE_FIELD_NAME = "playwrightOutput";
+export declare const PATH_PARAMS_FIELD_NAME = "pathParams";
+export declare const QUERY_PARAMS_FIELD_NAME = "queryParams";
+export declare const FORM_PARAMS_FIELD_NAME = "formParams";
+export declare function IsValidKeyValueList(input: string): boolean;
+export declare const SKYRAMP_UTILS_HEADER = "Generated by Skyramp";
+export declare function getPathParameterValidationError(requiredPathParams: string): string;
+export declare function validatePath(dir: string, fieldName: string): CallToolResult | null;
+export declare function validateParams(params: string, fieldName: string): CallToolResult | null;
+export declare function validateRequestData(value: string): string | null;
+/**
+ * Generates a Skyramp header for generated files
+ * @param language The programming language for the file
+ * @returns The formatted header string
+ */
+export declare function generateSkyrampHeader(language: string): string;
+/**
+ * Returns prompt phrasing for where the agent should find service details.
+ *
+ * - Testbot mode: agent receives a `<services>` XML block — no workspace.yml exists.
+ * - Normal MCP mode: agent reads `.skyramp/workspace.yml`.
+ */
+export declare function resolveServiceDetailsRef(): {
+    testDirRef: string;
+    frontendTestDirRef: string;
+    baseUrlRef: string;
+    authSourceRef: string;
+};

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

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

package/build/utils/versions.d.ts

@@ -0,0 +1,3 @@
+export declare const SKYRAMP_IMAGE_VERSION = "v1.3.28";
+export declare const EXECUTOR_DOCKER_IMAGE = "skyramp/executor:v1.3.28";
+export declare const WORKER_DOCKER_IMAGE = "skyramp/worker:v1.3.28";

package/build/utils/versions.js

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

package/build/utils/workspaceAuth.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Reads `.skyramp/workspace.yml`.
+ *
+ * Tries the library's Zod-validated `WorkspaceConfigManager.read()` first so
+ * well-formed workspaces produce a normalized object. When validation fails
+ * (e.g. a hand-rolled fixture that omits `metadata.createdAt` /`updatedAt`,
+ * or any new field added by a future schema), falls back to a raw YAML parse.
+ *
+ * Callers are expected to read only the fields they need (`services`,
+ * `services[].api.baseUrl`, etc.) — they should not depend on the strict
+ * shape across both paths.
+ *
+ * Returns null if the file does not exist OR cannot be parsed as YAML at all.
+ */
+export declare function readWorkspaceConfigRaw(workspacePath: string): Promise<any | null>;
+export interface WorkspaceServiceCandidate {
+    serviceName: string;
+    baseUrl: string;
+}
+export interface WorkspaceBaseUrlResult {
+    /** Resolved scheme+host+port when exactly one service matched. */
+    baseUrl: string | undefined;
+    /** Docker network from the matched service's runtimeDetails. */
+    dockerNetwork: string | undefined;
+    /**
+     * When baseUrl is undefined and candidates is non-empty, multiple services
+     * matched the test file but could not be disambiguated. Surface these to the
+     * LLM so it can ask the user or re-invoke with SKYRAMP_TEST_BASE_URL set.
+     */
+    candidates: WorkspaceServiceCandidate[];
+}
+/**
+ * Returns scheme+host+port for the service that owns the given test file.
+ *
+ * Matching strategy (in order):
+ * 1. Filter services whose `testDirectory` is a path prefix of `testFile`.
+ * 2. If multiple services match (shared testDirectory), narrow by `language`.
+ * 3. If still ambiguous, return all candidates so the LLM can resolve it —
+ *    never guess when multiple services are plausible owners.
+ *
+ * e.g. repositoryPath=/repo, testDirectory=backend/tests, testFile=/repo/backend/tests/test_api.py
+ *   → { baseUrl: "http://localhost:8000", candidates: [] }
+ */
+export declare function getWorkspaceBaseUrl(repositoryPath: string, testFile?: string, language?: string): Promise<WorkspaceBaseUrlResult>;
+/**
+ * Known auth-related HTTP header names (lowercase).
+ * Single source of truth used for both:
+ *  - trace redaction  (trace-parser.ts  — headers to scrub from recorded traces)
+ *  - auth extraction  (TestGenerationService — headers to pull out as auth credentials)
+ */
+export declare const KNOWN_AUTH_HEADERS: Set<string>;
+/**
+ * Cross-framework auth middleware signal patterns used by both the testbot and
+ * recommendation prompts to detect auth when workspace config says authType: none.
+ *
+ * Format: plain strings (e.g. "HTTPBearer", "@PreAuthorize")
+ *
+ * This is the single source of truth — prompts must import and use this list
+ * instead of hardcoding pattern names inline.
+ */
+export declare const AUTH_MIDDLEWARE_PATTERNS: string[];
+/** Rendered as a comma-separated string for use in prompts. */
+export declare const AUTH_MIDDLEWARE_PATTERNS_STR: string;
+export declare enum WorkspaceAuthType {
+    Bearer = "bearer",
+    Basic = "basic",
+    OAuth = "oauth",
+    /** Generic custom-header auth (X-API-Key, X-Admin-Key, etc.) */
+    ApiKey = "apiKey",
+    /** Session cookie auth — header is typically Cookie: <name>=<value> */
+    Cookie = "cookie",
+    /** Alias for Cookie; some workspace configs write authType: session */
+    Session = "session",
+    /** Django REST Framework / token-based: Authorization: Token <value> */
+    Token = "token",
+    None = "none"
+}
+/**
+ * All valid authType values as a tuple for use in zod enums.
+ * Single source of truth — tools and prompts should use this instead of hardcoding.
+ */
+export declare const ALL_AUTH_TYPES: [string, ...string[]];
+/**
+ * Formatted list of authType values for use in prompt text.
+ * Example: "`bearer`, `basic`, `oauth`, `token`, `cookie`, `session`, `apiKey`, or `none`"
+ */
+export declare const AUTH_TYPES_PROMPT_LIST: string;
+export declare function parseWorkspaceAuthType(value: string | undefined): WorkspaceAuthType | undefined;
+/**
+ * Returns the conventional HTTP header name for an auth type when authHeader
+ * is not explicitly configured in workspace.yml.
+ *
+ * This is the single source of truth for the authType → authHeader mapping.
+ * All prompt builders and tools must use this instead of hardcoding header names.
+ *
+ * - cookie / session           → "Cookie"        (always goes in Cookie header)
+ * - apiKey                     → ""              (custom header; caller must read source)
+ * - none                       → ""
+ * - "" / undefined             → ""              (do not infer a header when authType is missing)
+ * - bearer / basic / oauth / token → "Authorization"
+ */
+export declare function getDefaultAuthHeader(authType: WorkspaceAuthType | "" | undefined): string;
+/**
+ * Returns true when the given header NAME string is the Authorization header.
+ *
+ * Use this instead of sprinkling /^authorization$/i regexes across prompts and tools.
+ */
+export declare function isAuthorizationHeaderName(headerName: string): boolean;
+/**
+ * Maps a WorkspaceAuthType to the canonical HTTP Authorization scheme prefix
+ * (the word that appears before the token in "Authorization: <scheme> <token>").
+ *
+ * If `explicitScheme` is provided (from workspace.yml api.authScheme), it takes
+ * precedence over the inferred scheme. This allows custom schemes like "Ghost",
+ * "Hasura", or any internal API without hardcoding them in the codebase.
+ *
+ * Returns undefined for auth types that do NOT use the Authorization header
+ * (Cookie, ApiKey, None) — callers should not pass authScheme in those cases.
+ */
+export declare function getAuthScheme(authType: WorkspaceAuthType | undefined, explicitScheme?: string): string | undefined;
+export interface WorkspaceAuthConfig {
+    authHeader?: string;
+    authType?: WorkspaceAuthType;
+    /** Explicit Authorization scheme from workspace.yml (e.g., "Ghost", "Hasura", custom). */
+    authScheme?: string;
+}
+export declare function getWorkspaceAuthConfig(repositoryPath: string): Promise<WorkspaceAuthConfig>;

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

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

package/build/utils/workspaceAuth.test.js

@@ -1,29 +1,29 @@
-import { getWorkspaceBaseUrl } from "./workspaceAuth.js";
+// @ts-nocheck - Jest ESM mock type inference issues
+import { jest } from "@jest/globals";
 const REPO = "/some/repo";
-jest.mock("../workspace/workspace.js", () => {
-    const twoServiceConfig = {
-        services: [
-            {
-                serviceName: "backend",
-                language: "python",
-                testDirectory: "backend/tests",
-                api: { baseUrl: "http://localhost:8000" },
-            },
-            {
-                serviceName: "frontend",
-                language: "typescript",
-                testDirectory: "frontend/tests",
-                api: { baseUrl: "http://localhost:5173" },
-            },
-        ],
-    };
-    return {
-        WorkspaceConfigManager: jest.fn().mockImplementation(() => ({
-            exists: jest.fn().mockResolvedValue(true),
-            read: jest.fn().mockResolvedValue(twoServiceConfig),
-        })),
-    };
-});
+const twoServiceConfig = {
+    services: [
+        {
+            serviceName: "backend",
+            language: "python",
+            testDirectory: "backend/tests",
+            api: { baseUrl: "http://localhost:8000" },
+        },
+        {
+            serviceName: "frontend",
+            language: "typescript",
+            testDirectory: "frontend/tests",
+            api: { baseUrl: "http://localhost:5173" },
+        },
+    ],
+};
+jest.unstable_mockModule("../workspace/workspace.js", () => ({
+    WorkspaceConfigManager: jest.fn().mockImplementation(() => ({
+        exists: jest.fn().mockResolvedValue(true),
+        read: jest.fn().mockResolvedValue(twoServiceConfig),
+    })),
+}));
+const { getWorkspaceBaseUrl } = await import("./workspaceAuth.js");
 describe("getWorkspaceBaseUrl", () => {
     it("should return no match when testFile is not provided", async () => {
         const result = await getWorkspaceBaseUrl(REPO);

package/build/workspace/index.d.ts

@@ -0,0 +1 @@
+export * from "./workspace.js";