@skyramp/mcp 0.0.64 → 0.1.0-rc.1

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

@@ -0,0 +1,85 @@
+// 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", () => ({
+    AnalyticsService: { pushMCPToolEvent: jest.fn() },
+}));
+jest.mock("../../prompts/test-recommendation/test-recommendation-prompt.js", () => ({
+    buildRecommendationPrompt: jest.fn(),
+}));
+jest.mock("../../prompts/test-recommendation/recommendationSections.js", () => ({
+    MAX_RECOMMENDATIONS: 10,
+    MAX_TESTS_TO_GENERATE: 3,
+}));
+jest.mock("../../prompts/test-recommendation/analysisOutputPrompt.js", () => ({
+    buildAnalysisOutputText: jest.fn(),
+}));
+jest.mock("../../services/TestDiscoveryService.js", () => ({
+    TestDiscoveryService: jest.fn(),
+}));
+jest.mock("../../utils/branchDiff.js", () => ({
+    computeBranchDiff: jest.fn(),
+}));
+jest.mock("../../utils/routeParsers.js", () => ({
+    parseEndpointsFromDiff: jest.fn(),
+}));
+jest.mock("../../utils/repoScanner.js", () => ({
+    scanAllRepoEndpoints: jest.fn(),
+    scanRelatedEndpoints: jest.fn(),
+    grepRouterMountingContext: jest.fn(),
+}));
+jest.mock("../../utils/projectMetadata.js", () => ({
+    detectProjectMetadata: jest.fn(),
+}));
+jest.mock("../../utils/scenarioDrafting.js", () => ({
+    draftScenariosFromEndpoints: jest.fn(),
+}));
+jest.mock("../../utils/trace-parser.js", () => ({
+    parseTraceFile: jest.fn(),
+    discoverTraceFiles: jest.fn(),
+    discoverPlaywrightZips: jest.fn(),
+}));
+jest.mock("../../utils/pr-comment-parser.js", () => ({
+    parsePRComments: jest.fn(),
+}));
+jest.mock("../../utils/AnalysisStateManager.js", () => ({
+    StateManager: jest.fn(),
+    registerSession: jest.fn(),
+    storeSessionData: jest.fn(),
+}));
+jest.mock("../../utils/workspaceAuth.js", () => ({
+    parseWorkspaceAuthType: jest.fn(),
+}));
+jest.mock("../../utils/logger.js", () => ({
+    logger: { info: jest.fn(), debug: jest.fn(), error: jest.fn(), warn: jest.fn() },
+}));
+jest.mock("@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 } from "./analyzeChangesTool.js";
+const schema = z.object(analyzeChangesInputSchema);
+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);
+    });
+});

package/build/types/RepositoryAnalysis.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { SCENARIO_CATEGORIES } from "./TestRecommendation.js";
 // ── Zod schemas ──
 export const analysisScopeSchema = z.enum(["full_repo", "current_branch_diff"]);
 export const paramInfoSchema = z.object({
@@ -76,18 +77,7 @@ export const scenarioStepSchema = z.object({
 export const draftedScenarioSchema = z.object({
     scenarioName: z.string(),
     description: z.string(),
-    category: z.enum([
-        "crud",
-        "workflow",
-        "auth",
-        "error-handling",
-        "data-validation",
-        "security_boundary",
-        "business_rule",
-        "data_integrity",
-        "breaking_change",
-        "new_endpoint",
-    ]),
+    category: z.enum(SCENARIO_CATEGORIES),
     priority: z.enum(["high", "medium", "low"]),
     steps: z.array(scenarioStepSchema),
     chainingKeys: z.array(z.string()),

package/build/types/TestRecommendation.js

@@ -1,5 +1,47 @@
 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
+];
+/** External categories valid for tool submissions, ordered by priority. */
+const CATEGORIES = [
+    // HIGH priority
+    "security_boundary", // auth, permission, cross-user isolation, idempotency
+    "business_rule", // unique constraints, range validation, state machines
+    "data_integrity", // cascade deletes, orphan prevention, referential integrity
+    "breaking_change", // route renames, auth migration, response shape changes
+    "auth", // authentication and authorization flows
+    // MEDIUM priority
+    "workflow", // cross-resource integration, user journeys
+    "error_handling", // error responses and edge cases
+    "data_validation", // input validation and schema enforcement
+    // LOW priority
+    "crud", // basic create/read/update/delete operations
+];
+/** All categories including internal ones. */
+export const SCENARIO_CATEGORIES = [...INTERNAL_CATEGORIES, ...CATEGORIES];
+/** Categories valid for tool submissions (excludes internal-only categories). */
+export const TEST_CATEGORIES = CATEGORIES;
+/** Priority assignment for each category. */
+export const CATEGORY_PRIORITY = {
+    new_endpoint: "CRITICAL",
+    security_boundary: "HIGH",
+    business_rule: "HIGH",
+    data_integrity: "HIGH",
+    breaking_change: "HIGH",
+    auth: "HIGH",
+    workflow: "MEDIUM",
+    error_handling: "MEDIUM",
+    data_validation: "MEDIUM",
+    crud: "LOW",
+};
+/** Map internal-only categories to their external equivalent for tool submission. */
+export function externalCategory(cat) {
+    if (cat === "new_endpoint")
+        return "crud";
+    return cat;
+}
 // Test type to documentation URL mapping
 export const TEST_TYPE_DOCS = {
     [TestType.SMOKE]: "https://www.skyramp.dev/docs/smoke-tests",
@@ -33,7 +75,7 @@ export const specificTestSchema = z.object({
 export const testTypeRecommendationSchema = z.object({
     priority: z.enum(["high", "medium", "low"]),
     testType: z.nativeEnum(TestType),
-    category: z.enum(["security_boundary", "business_rule", "breaking_change", "data_integrity", "workflow"]),
+    category: z.enum(TEST_CATEGORIES),
     rationale: z.string(),
     reasoning: z.string(),
     specificTests: z.array(specificTestSchema),

package/build/types/TestTypes.js

@@ -1,6 +1,13 @@
 import { z } from "zod";
 export const SESSION_STORAGE_FILENAME = "skyramp_session_storage.json";
 export const AUTH_PLACEHOLDER_TOKEN = "SKYRAMP_PLACEHOLDER_TOKEN";
+export var ProgrammingLanguage;
+(function (ProgrammingLanguage) {
+    ProgrammingLanguage["PYTHON"] = "python";
+    ProgrammingLanguage["TYPESCRIPT"] = "typescript";
+    ProgrammingLanguage["JAVASCRIPT"] = "javascript";
+    ProgrammingLanguage["JAVA"] = "java";
+})(ProgrammingLanguage || (ProgrammingLanguage = {}));
 export var TestType;
 (function (TestType) {
     TestType["SMOKE"] = "smoke";
@@ -12,15 +19,17 @@ export var TestType;
     TestType["UI"] = "ui";
     TestType["MOCK"] = "mock";
 })(TestType || (TestType = {}));
+export var HttpMethod;
+(function (HttpMethod) {
+    HttpMethod["GET"] = "GET";
+    HttpMethod["POST"] = "POST";
+    HttpMethod["PUT"] = "PUT";
+    HttpMethod["DELETE"] = "DELETE";
+    HttpMethod["PATCH"] = "PATCH";
+})(HttpMethod || (HttpMethod = {}));
 export const languageSchema = z.object({
     language: z
-        .string()
-        .refine((val) => {
-        const validLanguages = ["python", "typescript", "javascript", "java"];
-        return validLanguages.includes(val.toLowerCase());
-    }, {
-        message: "Language must be one of: python, typescript, javascript, java",
-    })
+        .nativeEnum(ProgrammingLanguage)
         .describe("Programming language for the generated test (default: python). Must be one of: python, typescript, javascript, java"),
     framework: z
         .string()
@@ -101,6 +110,10 @@ export const baseSchema = z.object({
         .number()
         .default(0)
         .describe("Port number for the mock server"),
+    optionalFields: z
+        .boolean()
+        .default(false)
+        .describe("Whether to include optional fields in the generated test/mock"),
     prompt: z.string().describe("The prompt user provided to generate the test"),
 });
 export const basePlaywrightSchema = z.object({

package/build/utils/AnalysisStateManager.js

@@ -75,12 +75,17 @@ export class StateManager {
      * @param sessionId Unique session identifier (defaults to UUID)
      * @param stateDir Directory to store state files (defaults to /tmp)
      */
-    constructor(stateType = "analysis", sessionId, stateDir) {
+    constructor(stateType = "analysis", sessionId, stateDir, stateFilePath) {
         this.stateType = stateType;
         this.sessionId = sessionId || crypto.randomUUID();
-        const baseDir = stateDir || os.tmpdir();
-        const prefix = STATE_FILE_PREFIXES[stateType];
-        this.stateFile = path.join(baseDir, `${prefix}-${this.sessionId}.json`);
+        if (stateFilePath) {
+            this.stateFile = stateFilePath;
+        }
+        else {
+            const baseDir = stateDir || os.tmpdir();
+            const prefix = STATE_FILE_PREFIXES[stateType];
+            this.stateFile = path.join(baseDir, `${prefix}-${this.sessionId}.json`);
+        }
     }
     /**
      * Create state manager from a sessionId (resolves the state file path internally)
@@ -104,7 +109,9 @@ export class StateManager {
                 break;
             }
         }
-        return new StateManager(stateType, sessionId, stateDir);
+        // Pass stateFilePath as the 4th arg so the constructor uses it directly
+        // instead of reconstructing a potentially-different path from the parsed parts.
+        return new StateManager(stateType, sessionId, stateDir, stateFilePath);
     }
     /**
      * Read data from state file (excludes metadata)
@@ -164,6 +171,7 @@ export class StateManager {
                     step: options?.step,
                 },
             };
+            await fs.promises.mkdir(path.dirname(this.stateFile), { recursive: true });
             await fs.promises.writeFile(this.stateFile, JSON.stringify(state, null, 2), "utf-8");
             logger.debug(`Wrote data to state file: ${this.stateFile}`);
         }

package/build/utils/AnalysisStateManager.test.js

@@ -0,0 +1,35 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { StateManager } from "./AnalysisStateManager.js";
+describe("StateManager.fromStatePath", () => {
+    it("preserves the exact supplied path for a standard-prefixed file", () => {
+        const stdPath = path.join(os.tmpdir(), "skyramp-analysis-some-uuid.json");
+        const manager = StateManager.fromStatePath(stdPath);
+        expect(manager.getStatePath()).toBe(stdPath);
+    });
+    it("preserves the exact supplied path for a custom filename like analyze-changes-state.json", () => {
+        // This is the filename testbot uses — it does NOT match any STATE_FILE_PREFIXES entry.
+        // fromStatePath must pass stateFilePath through to the constructor so the path is not rebuilt.
+        const customPath = path.join(os.tmpdir(), "analyze-changes-state.json");
+        const manager = StateManager.fromStatePath(customPath);
+        expect(manager.getStatePath()).toBe(customPath);
+    });
+});
+describe("StateManager.writeData", () => {
+    it("creates parent directories when they do not exist", async () => {
+        const nestedDir = path.join(os.tmpdir(), `skyramp-test-mkdir-${Date.now()}`);
+        const nestedPath = path.join(nestedDir, "state.json");
+        // Directory must not exist before the test
+        expect(fs.existsSync(nestedDir)).toBe(false);
+        const manager = new StateManager("analysis", undefined, undefined, nestedPath);
+        await expect(manager.writeData({
+            existingTests: [],
+            analysisScope: "branch_diff",
+            newEndpoints: [],
+        })).resolves.not.toThrow();
+        expect(fs.existsSync(nestedPath)).toBe(true);
+        // cleanup
+        await fs.promises.rm(nestedDir, { recursive: true, force: true });
+    });
+});

package/node_modules/playwright/lib/mcp/browser/browserServerBackend.js

@@ -74,6 +74,9 @@ ${String(error)}` }],
     }
     return responseObject;
   }
+  get context() {
+    return this._context;
+  }
   serverClosed() {
     void this._context?.dispose().catch(import_log.logUnhandledError);
   }

package/node_modules/playwright/lib/mcp/browser/tab.js

@@ -253,7 +253,14 @@ class Tab extends import_events.EventEmitter {
         if (param.element)
           locator = locator.describe(param.element);
         const { resolvedSelector } = await locator._resolveSelector();
-        return { locator, resolved: (0, import_utils.asLocator)("javascript", resolvedSelector) };
+        let fixedSelector = resolvedSelector;
+        if (!resolvedSelector.includes("internal:control=enter-frame") && /^(css=)?iframe\b[^>]*\s+>>\s+/.test(resolvedSelector)) {
+          fixedSelector = resolvedSelector.replace(
+            /^(css=)?(iframe\b[^>]*)\s+>>\s+/,
+            "css=$2 >> internal:control=enter-frame >> "
+          );
+        }
+        return { locator, resolved: (0, import_utils.asLocator)("javascript", fixedSelector) };
       } catch (e) {
         throw new Error(`Ref ${param.ref} not found in the current page snapshot. Try capturing new snapshot.`);
       }

package/node_modules/playwright/lib/mcp/browser/tools/keyboard.js

@@ -69,14 +69,15 @@ const pressSequentially = (0, import_tool.defineTabTool)({
 const typeSchema = import_snapshot.elementSchema.extend({
   text: import_mcpBundle.z.string().describe("Text to type into the element"),
   submit: import_mcpBundle.z.boolean().optional().describe("Whether to submit entered text (press Enter after)"),
-  slowly: import_mcpBundle.z.boolean().optional().describe("Whether to type one character at a time. Useful for triggering key handlers in the page. By default entire text is filled in at once.")
+  slowly: import_mcpBundle.z.boolean().optional().describe("DO NOT USE \u2014 causes silent failures in contenteditable and rich text editors. Use default fast fill instead."),
+  clear: import_mcpBundle.z.boolean().optional().describe("Ignored \u2014 browser_type always replaces existing content. Do not pass this parameter.")
 });
 const type = (0, import_tool.defineTabTool)({
   capability: "core",
   schema: {
     name: "browser_type",
     title: "Type text",
-    description: "Type text into editable element",
+    description: "Type text into an editable element. Auto-focuses and replaces existing content. NEVER call browser_click on the field first \u2014 clicking before typing injects extra network requests that corrupt the trace.",
     inputSchema: typeSchema,
     type: "input"
   },

package/node_modules/playwright/lib/mcp/browser/tools/navigate.js

@@ -28,7 +28,7 @@ const navigate = (0, import_tool.defineTool)({
   schema: {
     name: "browser_navigate",
     title: "Navigate to a URL",
-    description: "Navigate to a URL",
+    description: "Navigate to a URL. Prefer direct navigation to known URLs over clicking menus or carousels \u2014 menus may open unwanted popups and carousel items cause strict-mode violations. To reload the current page, navigate to the same URL \u2014 the backend converts this to page.reload(). After navigating to a folder where content was just created/edited, always call browser_wait_for with the file name before interacting with it.",
     inputSchema: import_mcpBundle.z.object({
       url: import_mcpBundle.z.string().describe("The URL to navigate to")
     }),

package/node_modules/playwright/lib/mcp/browser/tools/snapshot.js

@@ -30,7 +30,7 @@ const snapshot = (0, import_tool.defineTool)({
   schema: {
     name: "browser_snapshot",
     title: "Page snapshot",
-    description: "Capture accessibility snapshot of the current page, this is better than screenshot",
+    description: "Capture the ARIA accessibility tree of the current page. Returns element refs required by all interaction tools (browser_click, browser_type, browser_hover, etc.). Call before any interaction and after every action that changes the page to get fresh refs. If any interaction tool fails with a stale ref error, call this first to refresh.",
     inputSchema: import_mcpBundle.z.object({
       filename: import_mcpBundle.z.string().optional().describe("Save snapshot to markdown file instead of returning it in the response.")
     }),
@@ -55,7 +55,7 @@ const click = (0, import_tool.defineTabTool)({
   schema: {
     name: "browser_click",
     title: "Click",
-    description: "Perform click on a web page",
+    description: "Click an element on the page. Always click the actual interactive element (button, link, input) \u2014 never a container or wrapper div. NEVER click a text field before typing \u2014 browser_type auto-focuses; a prior click injects extra network requests that corrupt the trace. NEVER click a row or link in a file list to access contextual actions \u2014 use browser_hover on the row instead.",
     inputSchema: clickSchema,
     type: "input"
   },
@@ -111,7 +111,7 @@ const hover = (0, import_tool.defineTabTool)({
   schema: {
     name: "browser_hover",
     title: "Hover mouse",
-    description: "Hover over element on page",
+    description: "Hover over an element. Required pattern for contextual actions (More Options, Delete, Rename, \u22EF) on list/grid rows: (1) call browser_hover on the row element, (2) call browser_snapshot to reveal hover-only controls, (3) click the target button. NEVER click the row itself \u2014 that navigates into the item.",
     inputSchema: elementSchema,
     type: "input"
   },
@@ -132,7 +132,7 @@ const selectOption = (0, import_tool.defineTabTool)({
   schema: {
     name: "browser_select_option",
     title: "Select option",
-    description: "Select an option in a dropdown",
+    description: "Select an option in a native <select> dropdown only. For custom dropdowns (Radix, MUI, etc.) that appear as combobox in the snapshot, do NOT use this tool \u2014 instead: (1) click the combobox to open it, (2) call browser_snapshot to see the listbox options, (3) click the desired option.",
     inputSchema: selectOptionSchema,
     type: "input"
   },

package/node_modules/playwright/lib/mcp/browser/tools/tabs.js

@@ -29,10 +29,10 @@ const browserTabs = (0, import_tool.defineTool)({
   schema: {
     name: "browser_tabs",
     title: "Manage tabs",
-    description: "List, create, close, or select a browser tab.",
+    description: 'List, create, close, or switch to a browser tab. When a click opens a new tab, use action "select" with the tab index to switch to it. Do NOT call browser_navigate after switching \u2014 the tab is already on the right page.',
     inputSchema: import_mcpBundle.z.object({
-      action: import_mcpBundle.z.enum(["list", "new", "close", "select"]).describe("Operation to perform"),
-      index: import_mcpBundle.z.number().optional().describe("Tab index, used for close/select. If omitted for close, current tab is closed.")
+      action: import_mcpBundle.z.enum(["list", "new", "close", "select", "switch"]).describe('Operation to perform. "select" and "switch" are equivalent \u2014 both switch to a tab by index.'),
+      index: import_mcpBundle.z.number().optional().describe("Tab index, used for close/select/switch. If omitted for close, current tab is closed.")
     }),
     type: "action"
   },
@@ -50,7 +50,8 @@ const browserTabs = (0, import_tool.defineTool)({
         await context.closeTab(params.index);
         break;
       }
-      case "select": {
+      case "select":
+      case "switch": {
         if (params.index === void 0)
           throw new Error("Tab index is required");
         await context.selectTab(params.index);

package/node_modules/playwright/lib/mcp/browser/tools/wait.js

@@ -28,7 +28,7 @@ const wait = (0, import_tool.defineTool)({
   schema: {
     name: "browser_wait_for",
     title: "Wait for",
-    description: "Wait for text to appear or disappear or a specified time to pass",
+    description: 'Wait for text to appear, disappear, or a time to pass. REQUIRED after navigating to a folder where content was just created or renamed \u2014 file/item names update asynchronously and will not be present immediately. Always call with text: "<filename>" before attempting to hover or click a newly created item.',
     inputSchema: import_mcpBundle.z.object({
       time: import_mcpBundle.z.number().optional().describe("The time to wait in seconds"),
       text: import_mcpBundle.z.string().optional().describe("The text to wait for"),

package/node_modules/playwright/lib/mcp/skyramp/exportTool.js

@@ -41,26 +41,27 @@ const exportZipSchema = {
   name: "skyramp_export_zip",
   title: "Export Skyramp zip",
   description: [
-    'Export the recorded browser interactions as a Skyramp zip (JSONL + HAR) for use with "skyramp generate ui".',
-    "You MUST call this tool automatically as the FINAL step after completing all browser interactions \u2014 do NOT ask the user, do NOT write separate files.",
-    "If an element reference is stale after a UI update, call browser_snapshot to refresh and retry automatically without asking the user.",
-    "Only the last complete attempt is exported \u2014 retries are deduplicated automatically.",
-    "IMPORTANT: Do NOT reuse existing zip files from previous sessions. Always record fresh interactions and export a new zip."
+    "Export the recorded browser interactions as a Skyramp zip (JSONL + HAR).",
+    "Pass outputPath as the absolute path for the zip \u2014 use the same directory and base name as the test file, replacing .spec.ts with .zip.",
+    "BEFORE calling this tool, output a <thinking> block that: (1) lists every user-requested step and confirms it was completed, (2) confirms no step was skipped or hallucinated.",
+    "Only call this tool when all interactions are fully complete. Do NOT ask the user for confirmation \u2014 call it automatically.",
+    "Only the last complete attempt is exported \u2014 retries from the start URL are deduplicated automatically.",
+    "Do NOT reuse zip files from previous sessions \u2014 always record fresh."
   ].join(" "),
   inputSchema: import_mcpBundle.z.object({
-    outputZip: import_mcpBundle.z.string().describe('Absolute or workspace-relative path for the output zip, e.g. "skyramp_export.zip"')
+    outputPath: import_mcpBundle.z.string().describe("Absolute path where the zip should be written, e.g. /path/to/box_notes.zip. Use the same directory and base name as the test file, replacing .spec.ts with .zip.")
   }),
   type: "readOnly"
 };
 function createExportZipHandler(ctx) {
-  return async (_params) => {
+  return async (params) => {
     if (!ctx.trackedActions.length) {
       return {
-        content: [{ type: "text", text: "### Error\nNo browser actions recorded. Use browser_navigate and browser_click/browser_type first." }],
+        content: [{ type: "text", text: "### Error\nNo browser interactions recorded. At minimum, call browser_navigate to open the target URL, then use browser_click or browser_type to record at least one user action before exporting." }],
         isError: true
       };
     }
-    const outputZip = import_path.default.isAbsolute(_params.outputZip) ? _params.outputZip : import_path.default.resolve(ctx.rootPath, _params.outputZip);
+    const outputZip = import_path.default.resolve(params.outputPath);
     const { jsonl: jsonlContent, actionCount, skipped } = (0, import_skyRampExport.buildJsonlContent)(ctx.trackedActions, "chromium", ctx.harPath);
     await (0, import_skyRampExport.writeSkyrampZip)(outputZip, jsonlContent, ctx.harPath);
     const skippedNote = skipped.length ? `