@skyramp/mcp 0.2.6 → 0.2.8-rc.1

package/build/tools/test-management/analyzeChangesTool.test.js

@@ -1,70 +1,101 @@
-// Mock all heavy dependencies so the module can be loaded in isolation
-jest.mock("@skyramp/skyramp", () => ({}));
-jest.mock("simple-git", () => ({ simpleGit: jest.fn() }));
-jest.mock("../../services/AnalyticsService.js", () => ({
+// @ts-nocheck - Jest ESM type inference issues
+import { jest } from "@jest/globals";
+import { z } from "zod";
+// Mock all heavy dependencies so the module can be loaded in isolation.
+// Under native ESM, jest.mock is not hoisted — every mock the subject's import
+// graph touches must use unstable_mockModule before the dynamic import below.
+jest.unstable_mockModule("simple-git", () => ({ simpleGit: jest.fn() }));
+jest.unstable_mockModule("../../services/AnalyticsService.js", () => ({
     AnalyticsService: { pushMCPToolEvent: jest.fn() },
 }));
-jest.mock("../../prompts/test-recommendation/test-recommendation-prompt.js", () => ({
+jest.unstable_mockModule("../../prompts/test-recommendation/test-recommendation-prompt.js", () => ({
     buildRecommendationPrompt: jest.fn(),
 }));
-jest.mock("../../prompts/test-recommendation/recommendationSections.js", () => ({
+jest.unstable_mockModule("../../prompts/test-recommendation/recommendationSections.js", () => ({
     MAX_RECOMMENDATIONS: 10,
     MAX_TESTS_TO_GENERATE: 3,
 }));
-jest.mock("../../prompts/test-recommendation/analysisOutputPrompt.js", () => ({
+jest.unstable_mockModule("../../prompts/test-recommendation/analysisOutputPrompt.js", () => ({
     buildAnalysisOutputText: jest.fn(),
 }));
-jest.mock("../../services/TestDiscoveryService.js", () => ({
+jest.unstable_mockModule("../../services/TestDiscoveryService.js", () => ({
     TestDiscoveryService: jest.fn(),
 }));
-jest.mock("../../utils/branchDiff.js", () => ({
+jest.unstable_mockModule("../../utils/branchDiff.js", () => ({
     computeBranchDiff: jest.fn(),
 }));
-jest.mock("../../utils/routeParsers.js", () => ({
+jest.unstable_mockModule("../../utils/routeParsers.js", () => ({
     classifyEndpointsByChangedFiles: jest.fn(),
     extractResourceFromPath: jest.fn(),
     parseFileEndpoints: jest.fn(),
 }));
-jest.mock("../../utils/repoScanner.js", () => ({
+jest.unstable_mockModule("../../utils/repoScanner.js", () => ({
     scanAllRepoEndpoints: jest.fn(),
     scanRelatedEndpoints: jest.fn(),
     grepRouterMountingContext: jest.fn(),
     findCandidateRouteFiles: jest.fn(),
 }));
-jest.mock("../../utils/projectMetadata.js", () => ({
+jest.unstable_mockModule("../../utils/projectMetadata.js", () => ({
     detectProjectMetadata: jest.fn(),
 }));
-jest.mock("../../utils/scenarioDrafting.js", () => ({
+jest.unstable_mockModule("../../utils/scenarioDrafting.js", () => ({
     draftScenariosFromEndpoints: jest.fn(),
 }));
-jest.mock("../../utils/trace-parser.js", () => ({
+jest.unstable_mockModule("../../utils/trace-parser.js", () => ({
     parseTraceFile: jest.fn(),
     discoverTraceFiles: jest.fn(),
     discoverPlaywrightZips: jest.fn(),
 }));
-jest.mock("../../utils/pr-comment-parser.js", () => ({
+jest.unstable_mockModule("../../utils/pr-comment-parser.js", () => ({
     parsePRComments: jest.fn(),
 }));
-jest.mock("../../utils/AnalysisStateManager.js", () => ({
-    StateManager: jest.fn().mockImplementation(() => ({
+jest.unstable_mockModule("../../utils/AnalysisStateManager.js", () => {
+    const makeInstance = () => ({
         writeData: jest.fn(),
-    })),
-    registerSession: jest.fn(),
-    storeSessionData: jest.fn(),
-}));
-jest.mock("../../utils/workspaceAuth.js", () => ({
+        writeRepoData: jest.fn(),
+        getStatePath: jest.fn().mockReturnValue("/tmp/skyramp/analysis-state.json"),
+    });
+    const StateManager = jest.fn().mockImplementation(makeInstance);
+    StateManager.fromStatePath = jest.fn().mockImplementation(makeInstance);
+    return {
+        StateManager,
+        registerSession: jest.fn(),
+        storeSessionData: jest.fn(),
+        setTestsRepoDir: jest.fn(),
+        getActiveRunStatePath: jest.fn(),
+        setActiveRunStatePath: jest.fn(),
+        clearActiveRunStatePath: jest.fn(),
+    };
+});
+// Keep every real workspaceAuth export the subject's import graph needs
+// (readWorkspaceConfigRaw, getDefaultAuthHeader, WorkspaceAuthType, …) and
+// override only parseWorkspaceAuthType. requireActual can't load ESM
+// synchronously, so import the real module first (mock is not hoisted).
+const realWorkspaceAuth = await import("../../utils/workspaceAuth.js");
+jest.unstable_mockModule("../../utils/workspaceAuth.js", () => ({
+    ...realWorkspaceAuth,
     parseWorkspaceAuthType: jest.fn(),
 }));
-jest.mock("../../utils/logger.js", () => ({
+jest.unstable_mockModule("../../utils/logger.js", () => ({
     logger: { info: jest.fn(), debug: jest.fn(), error: jest.fn(), warn: jest.fn(), warning: jest.fn() },
 }));
-jest.mock("@modelcontextprotocol/sdk/server/mcp.js", () => ({
+jest.unstable_mockModule("@modelcontextprotocol/sdk/server/mcp.js", () => ({
     McpServer: jest.fn(),
 }));
-jest.mock("@modelcontextprotocol/sdk/types.js", () => ({}));
-jest.mock("@modelcontextprotocol/sdk/shared/protocol.js", () => ({}));
-import { z } from "zod";
-import { analyzeChangesInputSchema, isSecurityRelevantDiff } from "./analyzeChangesTool.js";
+jest.unstable_mockModule("@modelcontextprotocol/sdk/types.js", () => ({}));
+jest.unstable_mockModule("@modelcontextprotocol/sdk/shared/protocol.js", () => ({}));
+// All subject + mocked-module imports must be dynamic and live AFTER the
+// unstable_mockModule calls above — static imports hoist above the mocks under
+// native ESM, loading the real (heavy) modules unmocked.
+const { analyzeChangesInputSchema, isSecurityRelevantDiff, filterEndpointsBySpec, filterUnsupportedGraphQLEndpoints, isGraphQLFile, registerAnalyzeChangesTool, buildTraceFileEntry, buildCaptureInstructions, NO_UI_INSTRUCTIONS, NO_RESOLVABLE_URLS_INSTRUCTIONS, } = await import("./analyzeChangesTool.js");
+const { computeBranchDiff } = await import("../../utils/branchDiff.js");
+const { classifyEndpointsByChangedFiles } = await import("../../utils/routeParsers.js");
+const { scanRelatedEndpoints, scanAllRepoEndpoints } = await import("../../utils/repoScanner.js");
+const { StateManager } = await import("../../utils/AnalysisStateManager.js");
+const os = await import("os");
+const path = await import("path");
+const fsSync = await import("fs");
+const fsModule = fsSync;
 const schema = z.object(analyzeChangesInputSchema);
 describe("isSecurityRelevantDiff", () => {
     it("matches auth-specific middleware and admin-key signals", () => {
@@ -78,68 +109,35 @@ describe("isSecurityRelevantDiff", () => {
         expect(isSecurityRelevantDiff("move compression middleware to server setup")).toBe(false);
     });
 });
-describe("analyzeChangesInputSchema — stateOutputFile validation", () => {
-    it("accepts a valid absolute path", () => {
-        const result = schema.safeParse({
-            repositoryPath: "/repo",
-            stateOutputFile: "/tmp/analyze-changes-state.json",
-        });
-        expect(result.success).toBe(true);
-    });
-    it("rejects a relative path for stateOutputFile", () => {
-        // stateOutputFile must be absolute so the caller can guarantee the file location.
-        // Relative paths are silently ambiguous and should be rejected.
-        const result = schema.safeParse({
-            repositoryPath: "/repo",
-            stateOutputFile: "relative/path/state.json",
-        });
-        expect(result.success).toBe(false);
-    });
-    it("accepts absence of stateOutputFile (optional field)", () => {
-        const result = schema.safeParse({ repositoryPath: "/repo" });
-        expect(result.success).toBe(true);
-    });
-});
 describe("automatic old files cleanup", () => {
-    let StateManager;
     let cleanupOldFilesSpy;
     beforeEach(() => {
         jest.clearAllMocks();
-        StateManager = require("../../utils/AnalysisStateManager.js").StateManager;
         cleanupOldFilesSpy = jest.fn().mockResolvedValue(0);
         StateManager.cleanupOldFiles = cleanupOldFilesSpy;
     });
-    it("calls cleanupOldFiles with default temp dir when no stateOutputFile provided", async () => {
-        // This test verifies the cleanup call is made without stateDir when using default location
+    it("calls cleanupOldFiles with default temp dir", async () => {
         expect(StateManager.cleanupOldFiles).toBeDefined();
         await StateManager.cleanupOldFiles(24, undefined);
         expect(cleanupOldFilesSpy).toHaveBeenCalledWith(24, undefined);
     });
-    it("calls cleanupOldFiles with custom dir when stateOutputFile is provided", async () => {
-        // This test verifies the cleanup call is made with the directory of stateOutputFile
+    it("calls cleanupOldFiles with custom dir", async () => {
         const customPath = "/custom/dir";
         await StateManager.cleanupOldFiles(24, customPath);
         expect(cleanupOldFilesSpy).toHaveBeenCalledWith(24, customPath);
     });
-    it("calls cleanupOldFiles with empty stateTypes to restrict to diff files only", async () => {
-        // analyzeTestHealthTool passes [] so state files (skyramp-analysis-*, skyramp-recommendation-*)
-        // are never deleted — the caller still needs args.stateFile for skyramp_actions.
+    it("calls cleanupOldFiles with empty stateTypes", async () => {
         await StateManager.cleanupOldFiles(24, undefined, []);
         expect(cleanupOldFilesSpy).toHaveBeenCalledWith(24, undefined, []);
     });
     it("continues execution if cleanup fails", async () => {
-        // Cleanup failures should not crash the analyze flow
         cleanupOldFilesSpy.mockRejectedValue(new Error("permission denied"));
-        await expect(StateManager.cleanupOldFiles(24).catch(() => {
-            // In the real code, this is caught and logged as a warning
-            return Promise.resolve();
-        })).resolves.toBeUndefined();
+        await expect(StateManager.cleanupOldFiles(24).catch(() => Promise.resolve())).resolves.toBeUndefined();
     });
 });
 // ─────────────────────────────────────────────────────────────────────────────
 // filterEndpointsBySpec — spec filtering + merge logic (Step 4c / 4c-merge)
 // ─────────────────────────────────────────────────────────────────────────────
-import { filterEndpointsBySpec } from "./analyzeChangesTool.js";
 describe("filterEndpointsBySpec", () => {
     const makeEp = (path, methods = ["GET"]) => ({ path, methods, sourceFile: "" });
     it("removes scanned endpoints that are not in the spec and not diff-changed", () => {
@@ -224,10 +222,6 @@ describe("filterEndpointsBySpec", () => {
 // ─────────────────────────────────────────────────────────────────────────────
 // isGraphQLFile — unit tests
 // ─────────────────────────────────────────────────────────────────────────────
-import { filterUnsupportedGraphQLEndpoints, isGraphQLFile } from "./analyzeChangesTool.js";
-import * as os from "os";
-import * as path from "path";
-import * as fsSync from "fs";
 describe("isGraphQLFile", () => {
     const tmpDir = os.tmpdir();
     it("returns true for .graphql extension without reading content", async () => {
@@ -303,14 +297,6 @@ describe("filterUnsupportedGraphQLEndpoints", () => {
         readSpy.mockRestore();
     });
 });
-// ─────────────────────────────────────────────────────────────────────────────
-// analyzeChangesTool handler — GraphQL-only early return (handler-level)
-// ─────────────────────────────────────────────────────────────────────────────
-import { registerAnalyzeChangesTool, buildTraceFileEntry } from "./analyzeChangesTool.js";
-import { computeBranchDiff } from "../../utils/branchDiff.js";
-import { classifyEndpointsByChangedFiles } from "../../utils/routeParsers.js";
-import { scanRelatedEndpoints } from "../../utils/repoScanner.js";
-import * as fsModule from "fs";
 /** Register the tool against a minimal mock server and return the captured handler.
  *  The handler takes (params, extra) — extra is pre-filled with a no-op sendNotification. */
 function captureAnalyzeHandler() {
@@ -399,7 +385,6 @@ describe("analyzeChangesTool handler — GraphQL-only early return", () => {
         readSpy.mockRestore();
     });
     it("does NOT early-return when scope is full_repo (only fires for PR diffs)", async () => {
-        const { scanAllRepoEndpoints } = require("../../utils/repoScanner.js");
         scanAllRepoEndpoints.mockReturnValue([]);
         const handler = captureAnalyzeHandler();
         const result = await handler({ ...baseParams, scope: "full_repo" });
@@ -437,3 +422,35 @@ describe("buildTraceFileEntry", () => {
         expect(entry.userFlows).toEqual([]);
     });
 });
+describe("UI blueprint-capture instructions (merged from ui_analyze_changes)", () => {
+    it("NO_UI_INSTRUCTIONS signals no capture is needed and references no follow-up tool", () => {
+        expect(NO_UI_INSTRUCTIONS).toMatch(/no blueprint capture needed/i);
+        // The former pre-flight tool told the agent to "proceed to
+        // skyramp_analyze_changes" — that's redundant now we're inside it.
+        expect(NO_UI_INSTRUCTIONS).not.toMatch(/skyramp_analyze_changes/);
+    });
+    it("NO_RESOLVABLE_URLS_INSTRUCTIONS falls back to source-grounded", () => {
+        expect(NO_RESOLVABLE_URLS_INSTRUCTIONS).toMatch(/source-grounded/i);
+    });
+    it("buildCaptureInstructions numbers each candidate URL with its provenance", () => {
+        const pages = [
+            { url: "http://localhost:3000/notifications", sourcedFrom: ["app/routes.tsx"], strategy: "framework-route-grep" },
+            { url: "http://localhost:3000/settings", sourcedFrom: [], strategy: "root-fallback" },
+        ];
+        const text = buildCaptureInstructions(pages);
+        expect(text).toContain("1. http://localhost:3000/notifications");
+        expect(text).toContain("2. http://localhost:3000/settings");
+        expect(text).toContain("sourcedFrom: app/routes.tsx");
+        expect(text).toContain("sourcedFrom: (none)");
+        expect(text).toContain("browser_navigate");
+        expect(text).toContain("browser_blueprint");
+    });
+    it("buildCaptureInstructions does NOT emit a login step (uiCredentials dropped)", () => {
+        const pages = [
+            { url: "http://localhost:3000/x", sourcedFrom: [], strategy: "root-fallback" },
+        ];
+        const text = buildCaptureInstructions(pages);
+        expect(text).not.toMatch(/log in first/i);
+        expect(text).not.toMatch(/ui-credentials/i);
+    });
+});

package/build/tools/test-management/analyzeTestHealthTool.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerAnalyzeTestHealthTool(server: McpServer): void;

package/build/tools/test-management/analyzeTestHealthTool.js

@@ -15,11 +15,15 @@ export function registerAnalyzeTestHealthTool(server) {
             idempotentHint: true,
             openWorldHint: false,
         },
-        description: `Generate drift assessment instructions for existing tests — second step of the unified Test Health Analysis Flow. Optionally execute tests with skyramp_execute_test before calling skyramp_actions to capture beforeStatus.`,
+        description: `Generate drift assessment instructions for existing tests — second step of the unified Test Health Analysis Flow.`,
         inputSchema: {
             stateFile: z
                 .string()
-                .describe("Path to state file from skyramp_analyze_changes. Assessment results exist only in the LLM's reasoning context — this tool does not write back to the stateFile."),
+                .describe("Path to the analyze-changes-state.json file returned by skyramp_analyze_changes (the stateFile field in its output). Do NOT pass summaryOutputFile or testbot-result.txt here."),
+            repository: z
+                .string()
+                .optional()
+                .describe("The owner/repo whose analysis section to assess (e.g. 'letsramp/api-insight'). In a multi-repo run, ALWAYS set it — the primary's owner/repo for the primary repo, or a related repo's owner/repo for that repo's section within the run-scoped stateFile. Omit only for a single-repo run."),
         },
         outputSchema: {
             prompt: z.string().describe("LLM drift analysis prompt and assessment instructions."),
@@ -27,17 +31,20 @@ export function registerAnalyzeTestHealthTool(server) {
     }, async (args) => {
         let errorResult;
         try {
-            logger.info(`Analyzing test health from state file: ${args.stateFile}`);
-            // Load UnifiedAnalysisState from state file
+            logger.info(`Analyzing test health from state file: ${args.stateFile}${args.repository ? ` (repository: ${args.repository})` : ""}`);
+            // Load UnifiedAnalysisState for the requested repo section (primary when
+            // repository omitted/matches the root) from the run-scoped state file.
             const stateManager = StateManager.fromStatePath(args.stateFile);
-            const stateData = await stateManager.readData();
-            const fullState = await stateManager.readFullState();
-            const repositoryPath = fullState?.metadata.repositoryPath || "";
+            const stateData = await stateManager.readRepoData(args.repository);
+            const repositoryPath = (await stateManager.getRepoRepositoryPath(args.repository)) || "";
             if (!stateData) {
-                return toolError(`State file is empty or invalid: ${args.stateFile}. Call skyramp_analyze_changes first to generate a valid state file.`);
+                return toolError(`State file is empty or invalid: ${args.stateFile}${args.repository ? ` (no section for repository ${args.repository})` : ""}. Call skyramp_analyze_changes first to generate a valid state file.`);
             }
             if (!repositoryPath || typeof repositoryPath !== "string") {
-                return toolError(`repositoryPath not found in state file metadata. The state file was likely created by an older version — re-run skyramp_analyze_changes to regenerate it.`);
+                return toolError(`repositoryPath not found in state file metadata. The stateFile parameter must be the analyze-changes-state.json path returned by skyramp_analyze_changes — not summaryOutputFile or testbot-result.txt. Re-run skyramp_analyze_changes to regenerate it.`);
+            }
+            if (!Array.isArray(stateData.existingTests)) {
+                return toolError(`stateFile does not contain test discovery data (existingTests missing). The stateFile parameter must be the analyze-changes-state.json path returned by skyramp_analyze_changes — not summaryOutputFile or testbot-result.txt.`);
             }
             // Skyramp tests: full drift analysis + all actions permitted.
             // Relevant external tests (user-written, relevant to this PR's endpoints): drift analysis

package/build/tools/test-management/index.d.ts

@@ -0,0 +1,3 @@
+export { registerAnalyzeChangesTool } from "./analyzeChangesTool.js";
+export { registerAnalyzeTestHealthTool } from "./analyzeTestHealthTool.js";
+export { registerActionsTool } from "./actionsTool.js";

package/build/tools/test-management/index.js

@@ -1,4 +1,3 @@
 export { registerAnalyzeChangesTool } from "./analyzeChangesTool.js";
-export { registerUiAnalyzeChangesTool } from "./uiAnalyzeChangesTool.js";
 export { registerAnalyzeTestHealthTool } from "./analyzeTestHealthTool.js";
 export { registerActionsTool } from "./actionsTool.js";

package/build/tools/trace/resolveSaveStoragePath.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Resolve the user-supplied `playwrightSaveStoragePath` against `outputDir`:
+ *   - A bare filename (no separators, not absolute) is joined with `outputDir`.
+ *   - Anything else (absolute path, or a relative path containing separators)
+ *     is returned unchanged.
+ */
+export declare function resolveSaveStoragePath(input: string, outputDir: string | undefined): string;

package/build/tools/trace/resolveSaveStoragePath.test.d.ts

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

package/build/tools/trace/resolveSessionPaths.d.ts

@@ -0,0 +1,40 @@
+/**
+ * SKYR-3321: pick which Playwright session-storage paths to pass to the
+ * recorder based on a single, explicit `sessionMode` signal.
+ *
+ * The original start-trace tool had an asymmetric default: it always
+ * resolved a save path (so every recording overwrote the session file on
+ * stop) but never auto-loaded. That was the root cause of the "load →
+ * 31-min idle → stop → session destroyed" regression that fills SKYR-3321.
+ * The mode vocabulary replaced that with the three real intents — capture a
+ * new session, reuse an existing one, or ignore session storage entirely.
+ *
+ * SKYR-3793: `auto` must never store credentials the user did not ask for.
+ * It loads an existing session if one is present in `outputDir` (reuse), but
+ * when none exists it does NOTHING — it does not auto-capture. Storing is
+ * opt-in only: `sessionMode=capture` or an explicit `saveOverride`.
+ *
+ * Both `loadOverride` and `saveOverride` are plain optional strings: when
+ * the LLM omits them they arrive as `undefined`, which means "use the
+ * mode's default". No sentinel values; explicit overrides win when given.
+ */
+export type SessionMode = "auto" | "capture" | "reuse" | "ignore";
+export interface ResolvedSessionPaths {
+    loadPath?: string;
+    savePath?: string;
+}
+export interface ResolveSessionPathsArgs {
+    mode: SessionMode;
+    /** Raw value of `playwrightStoragePath` (LLM may omit). */
+    loadOverride: string | undefined;
+    /** Raw value of `playwrightSaveStoragePath` (LLM may omit). */
+    saveOverride: string | undefined;
+    /** Workspace directory used to resolve relative paths and locate the default session file. */
+    outputDir: string;
+    /**
+     * Whether `<outputDir>/<SESSION_STORAGE_FILENAME>` exists on disk. Injected
+     * rather than read in-function so the resolver stays pure and testable.
+     */
+    sessionExists: boolean;
+}
+export declare function resolveSessionPaths(args: ResolveSessionPathsArgs): ResolvedSessionPaths;

package/build/tools/trace/resolveSessionPaths.test.d.ts

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

package/build/tools/trace/sessionState.d.ts

@@ -0,0 +1,2 @@
+export declare function setSavedSessionPath(p: string | undefined): void;
+export declare function consumeSavedSessionPath(): string | undefined;

package/build/tools/trace/sessionState.test.d.ts

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

package/build/tools/trace/startTraceCollectionTool.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerTraceTool(server: McpServer): void;

package/build/tools/trace/stopTraceCollectionTool.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerTraceStopTool(server: McpServer): void;

package/build/tools/workspace/initScanWorkspaceTool.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function issueScanToken(): string;
+export declare function validateAndConsumeScanToken(token: string): boolean;
+export declare function registerInitScanWorkspaceTool(server: McpServer): void;

package/build/tools/workspace/initializeWorkspaceTool.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerInitializeWorkspaceTool(server: McpServer): void;

package/build/tools/workspace/initializeWorkspaceTool.js

@@ -7,6 +7,7 @@ import { logger } from "../../utils/logger.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { SKYRAMP_IMAGE_VERSION } from "../../utils/versions.js";
 import { validateAndConsumeScanToken } from "./initScanWorkspaceTool.js";
+import { upsertServicesByRepo } from "./serviceUpsert.js";
 const require = createRequire(import.meta.url);
 const MCP_VERSION = require("../../../package.json").version || "";
 function getExecutorVersion() {
@@ -16,8 +17,8 @@ const TOOL_NAME = "skyramp_init_workspace";
 // writeWorkspaceConfig() writes the YAML directly (rather than via
 // WorkspaceConfigManager.addService) so all services are written in a single
 // pass without N+1 reads. The workspace serviceSchema accepts the full authType
-// set (incl. cookie/session/token), so input services are validated against it
-// directly — no local schema extension needed.
+// set (incl. cookie/session/token) and the multi-repo `repository` field, so input
+// services are validated against it directly — no local schema extension needed.
 const initializeWorkspaceSchema = z.object({
     workspacePath: z
         .string()
@@ -32,6 +33,10 @@ const initializeWorkspaceSchema = z.object({
         .boolean()
         .default(false)
         .describe("Set to true to overwrite an existing workspace file. Use when the user explicitly requests it, or when recovering from a workspace validation failure (schema mismatch, unknown fields). Default is false."),
+    merge: z
+        .boolean()
+        .default(false)
+        .describe("Set to true to MERGE the provided services into an existing workspace.yml instead of overwriting it. The primary use is registering a related repository's services into one unified workspace file (each service carrying its `repository`), but it applies whenever you want to add services without discarding existing ones. Services are upserted by the composite (repository, serviceName), so same-named services in different repos coexist. Ignored on first init (no existing file). Default is false."),
 });
 /**
  * Write a YAML workspace config to disk, bypassing the library's restricted
@@ -72,13 +77,17 @@ export function registerInitializeWorkspaceTool(server) {
         try {
             const workspacePath = params.workspacePath;
             const manager = new WorkspaceConfigManager(workspacePath);
-            // Check if already initialized
-            if ((await manager.exists()) && !params.force) {
+            const alreadyExists = await manager.exists();
+            // Check if already initialized. In merge mode we proceed (read the
+            // existing file and upsert into it) instead of refusing — this is how a
+            // multi-repo run registers each additional repo's services into one
+            // unified workspace.yml without a per-repo file.
+            if (alreadyExists && !params.force && !params.merge) {
                 return {
                     content: [
                         {
                             type: "text",
-                            text: `Workspace already initialized at ${manager.getConfigPath()}. Set force: true to overwrite.`,
+                            text: `Workspace already initialized at ${manager.getConfigPath()}. Set force: true to overwrite, or merge: true to add services to it.`,
                         },
                     ],
                     isError: false,
@@ -107,24 +116,30 @@ export function registerInitializeWorkspaceTool(server) {
                     isError: true,
                 };
             }
-            // Initialize workspace
-            let config = await manager.initialize();
-            config = await manager.updateMetadata({
-                mcpVersion: MCP_VERSION,
-                executorVersion: getExecutorVersion(),
-            });
-            // Batch all service upserts: update in memory, write once (direct YAML
-            // write avoids N+1 reads and a mid-loop validation error).
-            const services = config.services ?? [];
-            for (const svc of params.services) {
-                const idx = services.findIndex((s) => s.serviceName === svc.serviceName);
-                if (idx >= 0) {
-                    services[idx] = svc;
-                }
-                else {
-                    services.push(svc);
-                }
+            // Initialize (fresh) or read (merge into existing). Merge mode preserves
+            // the existing primary repo identity + previously-registered services;
+            // initialize() would reset both, dropping other repos' services.
+            let config;
+            if (params.merge && alreadyExists) {
+                config = await manager.read();
+                config = await manager.updateMetadata({
+                    mcpVersion: MCP_VERSION,
+                    executorVersion: getExecutorVersion(),
+                });
+            }
+            else {
+                config = await manager.initialize();
+                config = await manager.updateMetadata({
+                    mcpVersion: MCP_VERSION,
+                    executorVersion: getExecutorVersion(),
+                });
             }
+            // Batch all service upserts: update in memory, write once (direct YAML
+            // write avoids N+1 reads and a mid-loop validation error). Upsert is keyed
+            // on the composite (repo, serviceName) — see upsertServicesByRepo — so a
+            // same-named service from an additional repo is a distinct entry, not an
+            // overwrite of the primary's.
+            const services = upsertServicesByRepo(config.services ?? [], params.services);
             config.services = services;
             if (config.metadata) {
                 config.metadata.updatedAt = new Date().toISOString();
@@ -142,6 +157,8 @@ export function registerInitializeWorkspaceTool(server) {
                 lines.push(`\nServices (${config.services.length}):`);
                 for (const svc of config.services) {
                     const parts = [svc.serviceName];
+                    if (svc.repository)
+                        parts.push(svc.repository);
                     if (svc.language)
                         parts.push(svc.language);
                     if (svc.framework)

package/build/tools/workspace/initializeWorkspaceTool.test.d.ts

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