@skyramp/mcp 0.1.8 → 0.2.0-rc.2

package/build/tools/trace/startTraceCollectionTool.js

@@ -1,11 +1,14 @@
 import { z } from "zod";
+import fs from "fs";
+import path from "path";
 import { SkyrampClient } from "@skyramp/skyramp";
 import openProxyTerminalTracked from "../../utils/proxy-terminal.js";
 import { getEntryPoint } from "../../utils/telemetry.js";
 import { logger } from "../../utils/logger.js";
-import { basePlaywrightSchema, baseSchema, } from "../../types/TestTypes.js";
+import { basePlaywrightSchema, baseSchema, SESSION_STORAGE_FILENAME, } from "../../types/TestTypes.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
-import path from "path";
+import { resolveSessionPaths } from "./resolveSessionPaths.js";
+import { setSavedSessionPath } from "./sessionState.js";
 const TOOL_NAME = "skyramp_start_trace_collection";
 export function registerTraceTool(server) {
     server.registerTool(TOOL_NAME, {
@@ -21,12 +24,42 @@ WORKFLOW:
 3. Stop trace collection to save captured data
 4. Use traces to generate test scenarios
 
+SESSION HANDLING:
+Pass \`sessionMode\` to declare what you want to do with the workspace's session file. Defaults to \`auto\`, which does the right thing for most prompts.
+
+\`sessionMode: "capture"\` — Use when the user wants to log in once and SAVE a session for reuse later. Triggers: "save my session", "log in once", "store the session", "create a new session", "capture login".
+  Workflow:
+  1. Start trace collection (sessionMode=capture).
+  2. USER logs in.
+  3. Stop trace collection AFTER the post-login page is fully loaded — wait a few seconds for the app's initial authenticated API calls to fire, then stop. Do not interact further; those actions would pollute the trace and dilute the saved cookies.
+  4. The session file lands at \`outputDir/${SESSION_STORAGE_FILENAME}\`.
+
+\`sessionMode: "reuse"\` — Use when the user wants to RECORD a test flow against an existing authenticated session. Triggers: "load my session", "use my saved session", "skip login", "reuse the session", "I'm already logged in".
+  Workflow:
+  1. Start trace collection (sessionMode=reuse). The recorder loads \`outputDir/${SESSION_STORAGE_FILENAME}\` so the browser starts already authenticated.
+  2. USER walks through the test flow (no login needed).
+  3. Stop trace collection when the flow is complete.
+  4. The session file is NOT overwritten — this preserves the captured session for the next recording or test run.
+
+\`sessionMode: "ignore"\` — Use when the user explicitly does NOT want session handling. Triggers: "fresh trace", "without session", "ignore my session".
+
+\`sessionMode: "auto"\` (default) — Decides between capture and reuse based on whether a session file already exists in \`outputDir\`. Use when the user does not signal an intent either way. If a session file is present, behaves like \`reuse\`; otherwise like \`capture\`.
+
 For detailed documentation visit: https://www.skyramp.dev/docs/load-test/advanced-generation#start-trace-collection`,
         inputSchema: {
             playwright: z
                 .boolean()
                 .describe("Whether to enable Playwright for trace collection. Set to true for UI interactions, false for API-only tracing")
                 .default(true),
+            sessionMode: z
+                .enum(["auto", "capture", "reuse", "ignore"])
+                .default("auto")
+                .describe(`Controls how Playwright session storage is handled for this trace. ` +
+                `"capture" = save a fresh session at outputDir/${SESSION_STORAGE_FILENAME} (use when user wants to log in once and save). ` +
+                `"reuse" = load that file into the browser and DO NOT overwrite it (use when user wants to record a test flow against an existing session). ` +
+                `"ignore" = neither load nor save. ` +
+                `"auto" (default) = reuse if the session file already exists in outputDir, otherwise capture. ` +
+                `Explicit playwrightStoragePath / playwrightSaveStoragePath overrides still win when provided.`),
             browser: basePlaywrightSchema.shape.browser,
             device: basePlaywrightSchema.shape.device,
             playwrightStoragePath: basePlaywrightSchema.shape.playwrightStoragePath,
@@ -95,14 +128,32 @@ For detailed documentation visit: https://www.skyramp.dev/docs/load-test/advance
             outputDir: params.outputDir,
             prompt: params.prompt,
         });
-        let saveStoragePath = params.playwrightSaveStoragePath;
-        if (saveStoragePath) {
-            // If saveStoragePath is just a filename (no directory separators), use outputDir
-            if (params.outputDir && !saveStoragePath.includes(path.sep) && !path.isAbsolute(saveStoragePath)) {
-                saveStoragePath = path.join(params.outputDir, saveStoragePath);
+        const defaultSessionFile = path.join(params.outputDir, SESSION_STORAGE_FILENAME);
+        const sessionExists = (() => {
+            try {
+                return fs.existsSync(defaultSessionFile);
             }
-            logger.info("Session storage will be saved to:", { saveStoragePath });
-        }
+            catch {
+                return false;
+            }
+        })();
+        const { loadPath, savePath } = resolveSessionPaths({
+            mode: params.sessionMode,
+            loadOverride: params.playwrightStoragePath,
+            saveOverride: params.playwrightSaveStoragePath,
+            outputDir: params.outputDir,
+            sessionExists,
+        });
+        logger.info("Resolved session paths", {
+            sessionMode: params.sessionMode,
+            sessionExists,
+            loadPath: loadPath ?? "(not loading)",
+            savePath: savePath ?? "(not saving)",
+        });
+        // Carry the save path forward so the stop tool can name it in its message.
+        // When savePath is undefined (e.g. reuse mode), the stop tool just won't
+        // reference one — which is correct: the session file isn't being touched.
+        setSavedSessionPath(savePath);
         try {
             // Send initial progress
             await sendProgress(0, 100, "Initializing trace collection...");
@@ -119,13 +170,16 @@ For detailed documentation visit: https://www.skyramp.dev/docs/load-test/advance
                 playwright: params.playwright,
                 browser: params.browser,
                 device: params.device,
-                playwrightStoragePath: params.playwrightStoragePath,
                 playwrightViewportSize: params.playwrightViewportSize,
                 entrypoint: getEntryPoint(),
             };
-            if (saveStoragePath) {
-                generateOptions.playwrightSaveStoragePath = saveStoragePath;
-            }
+            // Only pass the storage options when sessionMode actually wants them.
+            // Leaving them undefined tells the underlying recorder to skip load /
+            // save entirely — that's what prevents the silent-overwrite trap.
+            if (loadPath)
+                generateOptions.playwrightStoragePath = loadPath;
+            if (savePath)
+                generateOptions.playwrightSaveStoragePath = savePath;
             // Send progress for configuration
             const traceMode = params.playwright ? "UI + Backend" : "Backend-only";
             await sendProgress(30, 100, `Configuring ${traceMode} trace collection...`);
@@ -151,6 +205,8 @@ For detailed documentation visit: https://www.skyramp.dev/docs/load-test/advance
                 clearInterval(progressInterval);
             }
             if (result.toLowerCase().includes("failed")) {
+                // Clear stashed session path so a failed start does not leak into a later unrelated stop.
+                setSavedSessionPath(undefined);
                 errorResult = {
                     content: [
                         {
@@ -167,17 +223,31 @@ For detailed documentation visit: https://www.skyramp.dev/docs/load-test/advance
             await openProxyTerminalTracked();
             // Send completion progress
             await sendProgress(100, 100, "Trace collection started successfully");
+            const sessionGuidance = (() => {
+                if (loadPath && savePath) {
+                    return `\n\nSession ${loadPath} loaded into the browser; will be re-saved to ${savePath} on stop.`;
+                }
+                if (loadPath) {
+                    return `\n\nSession ${loadPath} loaded into the browser — the browser starts already authenticated. The session file will NOT be overwritten on stop.`;
+                }
+                if (savePath) {
+                    return `\n\nPlaywright session storage will be saved to ${savePath}. If the goal is to capture an authenticated session, ask the user to log in and then call skyramp_stop_trace_collection a few seconds AFTER the post-login page is fully loaded — long enough for the app's initial authenticated API calls to fire, short enough that no test-flow interactions are captured.`;
+                }
+                return "";
+            })();
             errorResult = {
                 content: [
                     {
                         type: "text",
-                        text: `Trace collection started: ${result}. Please let me know when you are ready to stop the trace collection.`,
+                        text: `Trace collection started: ${result}. Please let me know when you are ready to stop the trace collection.${sessionGuidance}`,
                     },
                 ],
             };
             return errorResult;
         }
         catch (error) {
+            // Clear stashed session path so a failed start does not leak into a later unrelated stop.
+            setSavedSessionPath(undefined);
             errorResult = {
                 content: [
                     {

package/build/tools/trace/stopTraceCollectionTool.js

@@ -6,6 +6,7 @@ import { logger } from "../../utils/logger.js";
 import { baseSchema } from "../../types/TestTypes.js";
 import { existsSync, mkdirSync } from "fs";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
+import { consumeSavedSessionPath } from "./sessionState.js";
 const TOOL_NAME = "skyramp_stop_trace_collection";
 export function registerTraceStopTool(server) {
     server.registerTool(TOOL_NAME, {
@@ -103,14 +104,20 @@ For detailed documentation visit: https://www.skyramp.dev/docs/load-test/advance
                 };
                 return errorResult;
             }
+            const savedSession = consumeSavedSessionPath();
+            const sessionAppendix = savedSession
+                ? `\n\nPlaywright session storage saved to: ${savedSession}\nRe-use it by:\n` +
+                    `• Pass \`playwrightStoragePath: "${savedSession}"\` to skyramp_start_trace_collection for future recordings (skips login).\n` +
+                    `• Generated tests that reference \`storageState: "${savedSession}"\` will auto-mount the file when run via skyramp_execute_test.`
+                : "";
             errorResult = {
                 content: [
                     {
                         type: "text",
                         text: `Trace collection is stopped: ${result}. Trace is generated to given output file
-              
+
               **IMPORTANT: GO THROUGH THE TRACE AND LET THE USER KNOW THE ENDPOINT DOMAINS CAPTURED AND MAKE SURE USER WANTS TO INCLUDE THEN FOR INTEGRATION/E2E/LOAD TEST GENERATION.
-              UI TESTS CAN BE GENERATED USING PLAYWRIGHT FILES ONLY.**`,
+              UI TESTS CAN BE GENERATED USING PLAYWRIGHT FILES ONLY.**${sessionAppendix}`,
                     },
                 ],
             };

package/build/types/TestAnalysis.js

@@ -1,6 +1,56 @@
+export var RecommendationPriority;
+(function (RecommendationPriority) {
+    RecommendationPriority["High"] = "high";
+    RecommendationPriority["Medium"] = "medium";
+    RecommendationPriority["Low"] = "low";
+})(RecommendationPriority || (RecommendationPriority = {}));
+export var IssueSeverity;
+(function (IssueSeverity) {
+    IssueSeverity["Low"] = "low";
+    IssueSeverity["Medium"] = "medium";
+    IssueSeverity["High"] = "high";
+    IssueSeverity["Critical"] = "critical";
+})(IssueSeverity || (IssueSeverity = {}));
+export var DriftChangeType;
+(function (DriftChangeType) {
+    DriftChangeType["EndpointAdded"] = "endpoint_added";
+    DriftChangeType["EndpointRemoved"] = "endpoint_removed";
+    DriftChangeType["EndpointRenamed"] = "endpoint_renamed";
+    DriftChangeType["EndpointModified"] = "endpoint_modified";
+    DriftChangeType["AuthenticationChanged"] = "authentication_changed";
+    DriftChangeType["SchemaChanges"] = "schema_changes";
+    DriftChangeType["RouteChanged"] = "route_changed";
+    DriftChangeType["RouteAdded"] = "route_added";
+    DriftChangeType["RouteRemoved"] = "route_removed";
+    DriftChangeType["UiComponentAdded"] = "ui_component_added";
+    DriftChangeType["UiComponentRemoved"] = "ui_component_removed";
+    DriftChangeType["UiComponentModified"] = "ui_component_modified";
+    DriftChangeType["UiComponentRestructured"] = "ui_component_restructured";
+    DriftChangeType["DependencyChanged"] = "dependency_changed";
+    DriftChangeType["FunctionChanged"] = "function_changed";
+    DriftChangeType["ClassChanged"] = "class_changed";
+    DriftChangeType["BreakingChange"] = "breaking_change";
+    DriftChangeType["CodeChange"] = "code_change";
+})(DriftChangeType || (DriftChangeType = {}));
 /** Origin of a test file — whether it was generated by Skyramp or is user/third-party maintained. */
 export var TestSource;
 (function (TestSource) {
     TestSource["Skyramp"] = "skyramp";
     TestSource["External"] = "external";
 })(TestSource || (TestSource = {}));
+/** Drift action assigned by the LLM health assessment for an existing test. */
+export var DriftAction;
+(function (DriftAction) {
+    DriftAction["Update"] = "UPDATE";
+    DriftAction["Regenerate"] = "REGENERATE";
+    DriftAction["Delete"] = "DELETE";
+    DriftAction["Verify"] = "VERIFY";
+    DriftAction["Ignore"] = "IGNORE";
+})(DriftAction || (DriftAction = {}));
+/** Estimated effort to apply a drift UPDATE action. */
+export var EstimatedWork;
+(function (EstimatedWork) {
+    EstimatedWork["Small"] = "Small";
+    EstimatedWork["Medium"] = "Medium";
+    EstimatedWork["Large"] = "Large";
+})(EstimatedWork || (EstimatedWork = {}));

package/build/types/TestRecommendation.js

@@ -1,14 +1,12 @@
-import { z } from "zod";
-import { TestType } from "./TestTypes.js";
 /** Internal-only categories (not submitted to tools). */
 const INTERNAL_CATEGORIES = [
     "new_endpoint", // CRITICAL - diff-direct scenarios always fill GENERATE slots first
+    "bug_caught", // CRITICAL - tests targeting a specific <bug_found> flaw identified during enrichment
 ];
 /** External categories valid for tool submissions, ordered by priority. */
 const CATEGORIES = [
-    // CRITICAL priority
-    "business_rule", // formula bugs, unique constraints, state machines — most common production failures
     // HIGH priority
+    "business_rule", // formula bugs, unique constraints, state machines — most common production failures
     "security_boundary", // auth, permission, cross-user isolation, idempotency
     "data_integrity", // cascade deletes, orphan prevention, referential integrity
     "breaking_change", // route renames, auth migration, response shape changes
@@ -27,7 +25,8 @@ export const TEST_CATEGORIES = CATEGORIES;
 /** Priority assignment for each category. */
 export const CATEGORY_PRIORITY = {
     new_endpoint: "CRITICAL",
-    business_rule: "CRITICAL", // formula/business-logic bugs are the most common production failures
+    bug_caught: "CRITICAL", // tests targeting a <bug_found> flaw — always in GENERATE
+    business_rule: "HIGH", // formula/business-logic bugs are high priority but CRITICAL is reserved for new-endpoint diff-direct scenarios
     security_boundary: "HIGH",
     data_integrity: "HIGH",
     breaking_change: "HIGH",
@@ -41,58 +40,7 @@ export const CATEGORY_PRIORITY = {
 export function externalCategory(cat) {
     if (cat === "new_endpoint")
         return "crud";
+    if (cat === "bug_caught")
+        return "business_rule";
     return cat;
 }
-// Test type to documentation URL mapping
-export const TEST_TYPE_DOCS = {
-    [TestType.SMOKE]: "https://www.skyramp.dev/docs/smoke-tests",
-    [TestType.CONTRACT]: "https://www.skyramp.dev/docs/contract-tests",
-    [TestType.FUZZ]: "https://www.skyramp.dev/docs/fuzz-tests",
-    [TestType.INTEGRATION]: "https://www.skyramp.dev/docs/integration-tests",
-    [TestType.LOAD]: "https://www.skyramp.dev/docs/load-tests",
-    [TestType.E2E]: "https://www.skyramp.dev/docs/e2e-tests",
-    [TestType.UI]: "https://www.skyramp.dev/docs/ui-tests",
-    [TestType.MOCK]: "https://www.skyramp.dev/docs/mocks",
-};
-// Zod schemas for validation
-export const specificTestSchema = z.object({
-    testName: z.string(),
-    description: z.string(),
-    targetEndpoint: z.string().optional(),
-    targetFlow: z.string().optional(),
-    // generationPrompt: z.string(),
-    requiredInputs: z.object({
-        available: z.array(z.object({
-            name: z.string(),
-            path: z.string(),
-        })),
-        missing: z.array(z.object({
-            name: z.string(),
-            guidance: z.string(),
-        })),
-    }),
-    estimatedValue: z.string(),
-});
-export const testTypeRecommendationSchema = z.object({
-    priority: z.enum(["high", "medium", "low"]),
-    testType: z.nativeEnum(TestType),
-    category: z.enum(TEST_CATEGORIES),
-    rationale: z.string(),
-    reasoning: z.string(),
-    specificTests: z.array(specificTestSchema),
-    gettingStarted: z.object({
-        prerequisites: z.array(z.string()),
-        quickStartCommand: z.string().optional(),
-        documentationUrl: z.string(),
-    }),
-});
-export const testRecommendationSchema = z.object({
-    summary: z.object({
-        totalRecommended: z.number(),
-        highPriorityCount: z.number(),
-        estimatedEffort: z.string(),
-        quickWins: z.array(z.string()),
-    }),
-    recommendations: z.array(testTypeRecommendationSchema),
-    nextSteps: z.array(z.string()),
-});

package/build/types/TestTypes.js

@@ -141,7 +141,7 @@ export const basePlaywrightSchema = z.object({
     playwrightSaveStoragePath: z
         .string()
         .optional()
-        .describe(`Path to SAVE Playwright session storage after trace collection. ONLY provide this when user explicitly says 'with session storage', 'save session', or similar. If user specifies this without a path, defaults to '${SESSION_STORAGE_FILENAME}' in the outputDir. This SAVES authentication state (cookies, localStorage, sessionStorage) when the browser closes. To LOAD existing auth state, use playwrightStoragePath instead. Can be relative (e.g., 'auth.json') or absolute path.`),
+        .describe(`Path to SAVE Playwright session storage after trace collection. Omit this argument to use the default — \`${SESSION_STORAGE_FILENAME}\` resolved against the active outputDir, which produces an absolute path like '/abs/outputDir/${SESSION_STORAGE_FILENAME}'. SAVES authentication state (cookies, localStorage, sessionStorage) when the browser closes. To LOAD existing auth state, use playwrightStoragePath instead. Can be a bare filename (joined with outputDir), a relative path, or an absolute path.`),
     playwrightViewportSize: z
         .union([
         z.enum(["", "hd", "full-hd", "2k"]),

package/build/utils/AnalysisStateManager.js

@@ -10,6 +10,18 @@ import { logger } from "./logger.js";
  * multiple MCP clients share the same filesystem (e.g. /tmp).
  */
 const processSessionRegistry = new Map();
+/**
+ * Cross-repo test directory set by skyramp_analyze_changes when testsRepoDir
+ * is provided. Test generation tools read this to rewrite outputDir so files
+ * land in the test repo clone instead of the source repo.
+ */
+let _testsRepoDir;
+export function setTestsRepoDir(dir) {
+    _testsRepoDir = dir;
+}
+export function getTestsRepoDir() {
+    return _testsRepoDir;
+}
 /**
  * In-memory session store: sessionId → { data, storedAt }.
  * Eliminates the need for the LLM to read/write state files on disk.
@@ -247,34 +259,33 @@ export class StateManager {
      * @param stateTypes Which state types to clean (defaults to all)
      * @returns Number of files deleted
      */
-    static async cleanupOldStateFiles(maxAgeHours = 24, stateDir, stateTypes) {
+    static async cleanupOldFiles(maxAgeHours = 24, stateDir, stateTypes) {
         const baseDir = stateDir || os.tmpdir();
-        const files = await fs.promises.readdir(baseDir);
-        // Get prefixes to clean
-        const prefixesToClean = stateTypes
+        const files = await fs.promises.readdir(baseDir).catch(() => []);
+        const statePrefixes = stateTypes
             ? stateTypes.map((t) => STATE_FILE_PREFIXES[t])
             : Object.values(STATE_FILE_PREFIXES);
-        const stateFiles = files.filter((f) => prefixesToClean.some((prefix) => f.startsWith(prefix)));
+        const candidates = files.filter((f) => statePrefixes.some((prefix) => f.startsWith(prefix)) ||
+            (f.startsWith("skyramp-diff-") && f.endsWith(".diff")));
         let deletedCount = 0;
         const now = Date.now();
         const maxAge = maxAgeHours * 60 * 60 * 1000;
-        for (const file of stateFiles) {
+        for (const file of candidates) {
             const filePath = path.join(baseDir, file);
             try {
                 const stats = await fs.promises.stat(filePath);
-                const age = now - stats.mtimeMs;
-                if (age > maxAge) {
+                if (now - stats.mtimeMs > maxAge) {
                     await fs.promises.unlink(filePath);
                     deletedCount++;
-                    logger.debug(`Deleted old state file: ${filePath}`);
+                    logger.debug(`Deleted old temp file: ${filePath}`);
                 }
             }
             catch (error) {
-                logger.error(`Failed to delete state file ${filePath}: ${error.message}`);
+                logger.error(`Failed to delete temp file ${filePath}: ${error.message}`);
             }
         }
         if (deletedCount > 0) {
-            logger.info(`Cleaned up ${deletedCount} old state files`);
+            logger.info(`Cleaned up ${deletedCount} old temp files`);
         }
         return deletedCount;
     }

package/build/utils/branchDiff.js

@@ -1,9 +1,18 @@
 import { simpleGit } from "simple-git";
 import { logger } from "./logger.js";
 /**
- * Try a git diff against the given ref. Returns undefined if the ref doesn't exist
- * or the diff fails, so the caller can try the next candidate.
+ * Extract every file path mentioned in a unified-diff `diff --git` header.
+ * Always uses the `b/` form so renames return the new path.
  */
+export function parseChangedFilesFromDiff(rawDiff) {
+    const out = [];
+    const re = /^diff --git a\/\S+ b\/(\S+)/gm;
+    let m;
+    while ((m = re.exec(rawDiff)) !== null) {
+        out.push(m[1]);
+    }
+    return out;
+}
 /** Parse diff headers to find newly created and deleted files. */
 function parseNewAndDeletedFiles(rawDiff) {
     const newFiles = [];

package/build/utils/docker.test.js

@@ -54,7 +54,7 @@ describe("dockerImageExistsLocally", () => {
     });
 });
 describe("pullDockerImage", () => {
-    const IMAGE = "skyramp/executor:v1.3.24";
+    const IMAGE = "skyramp/executor:v1.3.25";
     beforeEach(() => jest.clearAllMocks());
     describe("on amd64 host", () => {
         const originalArch = process.arch;

package/build/utils/gitStaging.js

@@ -1,18 +1,67 @@
+import { execFileSync } from "child_process";
 import { execFile } from "child_process";
 import { promisify } from "util";
+import fs from "fs";
+import path from "path";
 import { logger } from "./logger.js";
 import { isTestbotEnabled } from "./featureFlags.js";
+/**
+ * Check whether `child` is inside `parent` using resolved paths with
+ * a trailing separator to avoid prefix false positives (e.g. /tmp/test-repo2
+ * should not match /tmp/test-repo).
+ */
+export function isInsideDir(child, parent) {
+    const resolved = path.resolve(child) + path.sep;
+    const resolvedParent = path.resolve(parent) + path.sep;
+    return resolved.startsWith(resolvedParent);
+}
+/**
+ * In cross-repo mode, redirects an outputDir to be under the test repo clone
+ * if it isn't already. Returns the original path unchanged when testsRepoDir
+ * is unset or the path is already inside it.
+ */
+export function resolveOutputDir(outputDir, testsRepoDir) {
+    if (!testsRepoDir || isInsideDir(outputDir, testsRepoDir))
+        return outputDir;
+    const relative = path.isAbsolute(outputDir)
+        ? path.basename(outputDir)
+        : outputDir;
+    return path.join(testsRepoDir, relative);
+}
 const execFileAsync = promisify(execFile);
+/**
+ * Detect the git repository root for a given file or directory path.
+ * Returns undefined if detection fails (not inside a git repo).
+ */
+function detectGitRoot(filePath) {
+    if (!path.isAbsolute(filePath))
+        return undefined;
+    try {
+        const dir = fs.statSync(filePath).isDirectory() ? filePath : path.dirname(filePath);
+        const stdout = execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd: dir, encoding: "utf8" });
+        return stdout.trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Stages a file path an MCP tool just wrote into the git index by
  * running `git add -- <path>`.
  *
+ * Automatically detects the git root of the target path so that staging
+ * works correctly in cross-repo mode (test repo clone separate from the
+ * source repo).
+ *
  * Gated by the SKYRAMP_FEATURE_TESTBOT=1 env var, which is set only
  * inside a testbot CI run.
  */
-export async function stageGeneratedPaths(path, cwd) {
+export async function stageGeneratedPaths(filePath, cwd) {
     if (!isTestbotEnabled())
         return;
-    await execFileAsync("git", ["add", "--", path], { cwd });
-    logger.info("Staged generated file", { path });
+    const effectiveCwd = cwd ?? detectGitRoot(filePath);
+    await execFileAsync("git", ["add", "--", filePath], {
+        cwd: effectiveCwd,
+    });
+    logger.info("Staged generated file", { path: filePath, cwd: effectiveCwd });
 }

package/build/utils/gitStaging.test.js

@@ -6,15 +6,25 @@ jest.mock("./logger.js", () => ({
         error: jest.fn(),
     },
 }));
+jest.mock("fs", () => ({
+    statSync: (p) => ({
+        isDirectory: () => !p.includes("."),
+    }),
+}));
 const execFileMock = jest.fn();
+const execFileSyncMock = jest.fn();
 jest.mock("child_process", () => ({
     execFile: (cmd, args, opts, cb) => {
         const result = execFileMock(cmd, args, opts);
         const cbErr = result && typeof result === "object" && "err" in result
             ? result.err
             : null;
-        cb(cbErr, "", "");
+        const cbStdout = result && typeof result === "object" && "stdout" in result
+            ? result.stdout
+            : "";
+        cb(cbErr, cbStdout, "");
     },
+    execFileSync: (cmd, args, opts) => execFileSyncMock(cmd, args, opts),
 }));
 import { stageGeneratedPaths } from "./gitStaging.js";
 import { logger } from "./logger.js";
@@ -33,6 +43,7 @@ afterAll(() => {
 });
 beforeEach(() => {
     execFileMock.mockReset();
+    execFileSyncMock.mockReset();
     loggerInfoMock.mockReset();
 });
 afterEach(() => {
@@ -49,6 +60,13 @@ describe("stageGeneratedPaths", () => {
             expect(execFileMock).toHaveBeenCalledWith("git", ["add", "--", "tests/a.py"], expect.objectContaining({}));
             expect(loggerInfoMock).toHaveBeenCalledWith("Staged generated file", expect.objectContaining({ path: "tests/a.py" }));
         });
+        it("auto-detects git root for absolute paths and uses it as cwd", async () => {
+            execFileSyncMock.mockReturnValue("/tmp/test-repo\n");
+            await stageGeneratedPaths("/tmp/test-repo/tests/a.py");
+            // Uses path.dirname for the cwd since the path is a file
+            expect(execFileSyncMock).toHaveBeenCalledWith("git", ["rev-parse", "--show-toplevel"], expect.objectContaining({ cwd: "/tmp/test-repo/tests" }));
+            expect(execFileMock).toHaveBeenCalledWith("git", ["add", "--", "/tmp/test-repo/tests/a.py"], expect.objectContaining({ cwd: "/tmp/test-repo" }));
+        });
         it("passes through the cwd option when provided", async () => {
             await stageGeneratedPaths("tests/a.py", "/repo/root");
             expect(execFileMock).toHaveBeenCalledWith("git", ["add", "--", "tests/a.py"], expect.objectContaining({ cwd: "/repo/root" }));

package/build/utils/repoScanner.js

@@ -104,11 +104,13 @@ export function grepRouterMountingContext(repositoryPath) {
 function addEndpointToMap(endpointMap, apiPath, method, sourceFile, repositoryPath) {
     const relative = sourceFile.startsWith(repositoryPath)
         ? sourceFile.slice(repositoryPath.length + 1) : sourceFile;
-    const existing = endpointMap.get(apiPath);
+    const normalizedPath = apiPath.startsWith("/") ? apiPath : `/${apiPath}`;
+    const key = `${relative}::${normalizedPath}`;
+    const existing = endpointMap.get(key);
     if (existing)
         existing.methods.add(method);
     else
-        endpointMap.set(apiPath, { methods: new Set([method]), sourceFile: relative });
+        endpointMap.set(key, { path: normalizedPath, methods: new Set([method]), sourceFile: relative });
 }
 function scanNextjsFile(file, repositoryPath, endpointMap) {
     const relative = file.startsWith(repositoryPath)
@@ -140,7 +142,13 @@ function scanNextjsFile(file, repositoryPath, endpointMap) {
     return true;
 }
 /** Filename pattern used to identify candidate route/handler files. */
-const ROUTE_FILE_PATTERN = /route|controller|endpoint|handler|view|urls|api|router/i;
+// Extended to cover NestJS (service, gateway, resolver) and other frameworks.
+// Tested against the full relative path — terms here are specific enough not to over-match.
+const ROUTE_FILE_PATTERN = /route|controller|endpoint|handler|view|urls|api|router|service|gateway|resolver|\bserver\b/i;
+// Generic terms like "app" and "main" must only match the basename (filename),
+// not directory names — otherwise every file under src/app/ would match by-name
+// and fill MAX_CANDIDATE_FILES, potentially skipping the content pass.
+const ROUTE_FILE_BASENAME_PATTERN = /\bapp\b|\bmain\b/i;
 /**
  * Content-based routing signature: a file is a route file if it contains BOTH
  * a URL-path-like string literal AND an HTTP method registration, regardless of
@@ -178,7 +186,7 @@ export function findCandidateRouteFiles(repositoryPath) {
         if (/test/i.test(f))
             continue;
         const relative = f.startsWith(repositoryPath) ? f.slice(repositoryPath.length + 1) : f;
-        if (ROUTE_FILE_PATTERN.test(relative)) {
+        if (ROUTE_FILE_PATTERN.test(relative) || ROUTE_FILE_BASENAME_PATTERN.test(path.basename(relative))) {
             byName.push(relative);
         }
         else {
@@ -225,7 +233,7 @@ export function scanAllRepoEndpoints(repositoryPath) {
             continue;
         const relative = file.startsWith(repositoryPath)
             ? file.slice(repositoryPath.length + 1) : file;
-        if (!ROUTE_FILE_PATTERN.test(relative))
+        if (!ROUTE_FILE_PATTERN.test(relative) && !ROUTE_FILE_BASENAME_PATTERN.test(path.basename(relative)))
             continue;
         const content = safeReadFile(file);
         if (content === null)
@@ -234,8 +242,8 @@ export function scanAllRepoEndpoints(repositoryPath) {
             addEndpointToMap(endpointMap, ep.path, ep.method, file, repositoryPath);
         }
     }
-    return Array.from(endpointMap.entries()).map(([apiPath, data]) => ({
-        path: apiPath,
+    return Array.from(endpointMap.values()).map((data) => ({
+        path: data.path,
         methods: Array.from(data.methods),
         sourceFile: data.sourceFile,
     }));
@@ -259,7 +267,7 @@ export function scanRelatedEndpoints(repositoryPath, changedFiles) {
                 continue;
             const relative = file.startsWith(repositoryPath)
                 ? file.slice(repositoryPath.length + 1) : file;
-            if (!ROUTE_FILE_PATTERN.test(relative))
+            if (!ROUTE_FILE_PATTERN.test(relative) && !ROUTE_FILE_BASENAME_PATTERN.test(path.basename(relative)))
                 continue;
             const fileContent = safeReadFile(file);
             if (fileContent === null)
@@ -269,8 +277,8 @@ export function scanRelatedEndpoints(repositoryPath, changedFiles) {
             }
         }
     }
-    return Array.from(endpointMap.entries()).map(([apiPath, data]) => ({
-        path: apiPath,
+    return Array.from(endpointMap.values()).map((data) => ({
+        path: data.path,
         methods: Array.from(data.methods),
         sourceFile: data.sourceFile,
     }));