@skyramp/mcp 0.0.63-rc.4 → 0.0.63-rc.5

package/build/commands/commandLibrary.js

@@ -0,0 +1,44 @@
+import { TEST_GIVEN_ENDPOINT_COMPREHENSIVELY_COMMAND } from "./testThisEndpointCommand.js";
+import { FULLREPO_RECOMMEND_GENERATE_EXECUTE_TOPN_TESTS_COMMAND } from "./recommendTestsAndExecuteCommand.js";
+/**
+ * To add a new predefined workflow:
+ * 1. Add a new id to OneClickCommandId in types/OneClickCommands.ts
+ * 2. Create a new file in commands/ (e.g. myWorkflowCommand.ts) with steps and export the command
+ * 3. Import the command here and add it to COMMAND_LIBRARY
+ * 4. The generic buildWorkflowFromCommand() will render detailed instructions from your steps
+ *    (no schema changes needed in oneClickTool.ts — the workflow param description is generated dynamically)
+ */
+/** All predefined one-click commands */
+const COMMAND_LIBRARY = {
+    test_given_endpoint_comprehensively: TEST_GIVEN_ENDPOINT_COMPREHENSIVELY_COMMAND,
+    full_repo_scan_recommend_generate_and_execute_top_n_tests: FULLREPO_RECOMMEND_GENERATE_EXECUTE_TOPN_TESTS_COMMAND,
+};
+export function getCommand(id) {
+    const cmd = COMMAND_LIBRARY[id];
+    if (!cmd) {
+        throw new Error(`Unknown one-click command: ${id}`);
+    }
+    return cmd;
+}
+export function getAllCommands() {
+    return Object.values(COMMAND_LIBRARY);
+}
+export function getCommandIds() {
+    return Object.keys(COMMAND_LIBRARY);
+}
+/**
+ * Look up a command by its string ID. Accepts any string so the tool handler
+ * does not need to cast; throws with a helpful message listing valid IDs if
+ * the ID is not found.
+ */
+export function lookupCommand(id) {
+    const cmd = COMMAND_LIBRARY[id];
+    if (!cmd) {
+        const available = getCommandIds().join(", ");
+        throw new Error(`Unknown workflow: "${id}". Valid workflow IDs: ${available}.`);
+    }
+    return cmd;
+}
+// Re-export commands for consumers that import from commandLibrary
+export { TEST_GIVEN_ENDPOINT_COMPREHENSIVELY_COMMAND } from "./testThisEndpointCommand.js";
+export { FULLREPO_RECOMMEND_GENERATE_EXECUTE_TOPN_TESTS_COMMAND } from "./recommendTestsAndExecuteCommand.js";

package/build/commands/recommendTestsAndExecuteCommand.js

@@ -0,0 +1,118 @@
+/**
+ * Predefined One-Click Command: Recommend tests and generate and execute top recommended tests
+ *
+ * Spec order:
+ *   skyramp_analyze_changes (combined analyze + discover + recommend)
+ *   → Generate tests for top N recommended types
+ *   → Execute each via skyramp_execute_test
+ *   → State cleanup
+ */
+const fullRepoRecommendGenerateExecuteTopNSteps = [
+    {
+        stepIndex: 0,
+        title: "Ensure workspace is initialized",
+        description: "First check whether the repositoryPath is a git repository by verifying that a .git directory exists at the repo root. If there is no .git directory, do not attempt to initialize a Skyramp workspace and proceed without one. If .git exists, check whether .skyramp/workspace.yml exists. If workspace.yml exists, read it and capture language, framework, outputDir, and api.baseUrl for use in later steps. If workspace.yml does not exist and the user has not declined initialization, call skyramp_initialize_workspace with repositoryPath to create it, then read and capture language, framework, outputDir, and api.baseUrl.",
+        toolCall: {
+            toolName: "skyramp_initialize_workspace",
+            description: "Initialize Skyramp workspace if not already present",
+            inputs: {
+                workspacePath: { source: "user", paramKey: "repositoryPath" },
+            },
+        },
+        conditionalGuidance: "Follow server-level init rules: (1) Check for .git at repositoryPath — if missing, do not call skyramp_initialize_workspace and proceed without a workspace. (2) If .git exists, check for .skyramp/workspace.yml — if it exists, read it and do not call skyramp_initialize_workspace. (3) If workspace.yml does not exist, call skyramp_initialize_workspace only if the user has not explicitly declined. If the user declines, proceed without a workspace. Always capture language, framework, outputDir, and api.baseUrl for later steps.",
+    },
+    {
+        stepIndex: 1,
+        title: "Analyze changes and get recommendations",
+        description: "Call skyramp_analyze_changes with repositoryPath and analysisScope from user. This single tool scans endpoints, discovers existing tests, and returns ranked test recommendations inline. Capture the stateFile path and the ranked recommendations for step 2.",
+        toolCall: {
+            toolName: "skyramp_analyze_changes",
+            description: "Analyze repo and generate ranked recommendations inline; returns stateFile",
+            inputs: {
+                repositoryPath: { source: "user", paramKey: "repositoryPath" },
+                scope: { source: "literal", value: "full_repo" },
+            },
+            outputs: ["stateFile", "recommendations"],
+        },
+        conditionalGuidance: "Always call skyramp_analyze_changes — do not skip this step or use a pre-existing stateFile. Capture stateFile and ranked recommendations for step 2.",
+    },
+    {
+        stepIndex: 2,
+        title: "Generate tests for top N recommended types",
+        description: "From the ranked recommendations returned by skyramp_analyze_changes in step 1, take the top N recommended test types (high priority first, then medium; N = topN from user, default 3).\n\nIMPORTANT — UI or E2E in top N: If UI or E2E test types are among the top N, treat each recommendation independently. For each such recommendation, first search the repository for existing trace files suitable for the endpoint or path associated with that recommendation (look for .zip or .json Skyramp trace files in the repo that reference the recommended endpoint path or URL). If suitable traces are found, use them directly as inputs to skyramp_ui_test_generation (playwrightInput) or skyramp_e2e_test_generation (trace + playwrightInput) — skip trace collection. If no suitable traces exist in the repo for that recommendation, collect them: call skyramp_start_trace_collection (playwright: true, outputDir: absolute path from workspace.yml), have the user interact with the recommended endpoint/path in the browser, then call skyramp_stop_trace_collection (playwrightEnabled: true, same outputDir). Use the produced trace file and Playwright zip as inputs for generation for that specific recommendation.\n\nFor all other types in the top N, for each recommendation call the corresponding generation tool using an endpoint URL derived from that recommendation (api.baseUrl + endpoint path, or a full endpoint URL included in the recommendation). If a recommendation does not specify a concrete endpoint, follow the scope indicated in the recommendation (e.g. service-wide or repo-wide) and omit endpointURL or use only api.baseUrl as appropriate. In all cases also pass apiSchema, language, framework, and outputDir from workspace.yml. Capture each generated test file path for step 3.",
+        conditionalGuidance: "Tool mapping by type — smoke: skyramp_smoke_test_generation, contract: skyramp_contract_test_generation, integration: skyramp_integration_test_generation, fuzz: skyramp_fuzz_test_generation, load: skyramp_load_test_generation, e2e: skyramp_e2e_test_generation, ui: skyramp_ui_test_generation. Limit to top N types. For UI/E2E: for each recommendation, (1) search the repo for existing traces for the endpoint or path associated with that recommendation; (2) if found, use them directly; (3) if not found, run skyramp_start_trace_collection → user interaction with the recommended endpoint/path → skyramp_stop_trace_collection, then use the produced traces. Record each generated test file path for step 3.",
+    },
+    {
+        stepIndex: 3,
+        title: "Execute generated tests",
+        description: "Before calling skyramp_execute_test, resolve the auth token using only information available to the workflow: (1) if the user provided a token param, use it directly; (2) otherwise, check .skyramp/workspace.yml or other repo config for a documented token value; (3) if no token can be resolved, proceed with empty string '' and rely on skyramp_execute_test to surface 401/403 errors — then report the auth failure to the user and ask them to provide a Bearer token to re-run. Then for each test file generated in step 2, call skyramp_execute_test with the test file path, language, testType, and the resolved token.",
+        toolCall: {
+            toolName: "skyramp_execute_test",
+            description: "Execute each generated test; resolve token before calling. For each generated test file path returned directly by the generation tools in step 2, invoke this tool with testFile set to that path.",
+            inputs: {
+                workspacePath: { source: "user", paramKey: "repositoryPath" },
+                language: { source: "literal", value: "from workspace" },
+                testType: { source: "literal", value: "from test file / recommendation" },
+                testFile: {
+                    source: "literal",
+                    value: "path to a single generated test file; for each test path returned by generation tools in step 2, call skyramp_execute_test separately with testFile set to that path",
+                },
+                token: { source: "user", paramKey: "token" },
+            },
+        },
+        conditionalGuidance: "Skip if step 2 generated no tests. Iterate over each generated test file path returned directly from the tools invoked in step 2 and call skyramp_execute_test once per file. Token resolution: (1) user-provided token; (2) token from .skyramp/workspace.yml or repo config; (3) empty string '' — let skyramp_execute_test surface auth errors, then ask the user for a Bearer token to re-run.",
+    },
+    {
+        stepIndex: 4,
+        title: "Clean up state files",
+        description: "Call skyramp_state_cleanup with action 'cleanup' and maxAgeHours set to 1 to remove temporary state files created by the recommendation toolset. These live in system temp (e.g. /tmp) — not in the user repo.",
+        toolCall: {
+            toolName: "skyramp_state_cleanup",
+            description: "Remove temporary state files from system temp",
+            inputs: {
+                action: { source: "literal", value: "cleanup" },
+                maxAgeHours: { source: "literal", value: 1 },
+            },
+        },
+    },
+];
+export const FULLREPO_RECOMMEND_GENERATE_EXECUTE_TOPN_TESTS_COMMAND = {
+    id: "full_repo_scan_recommend_generate_and_execute_top_n_tests",
+    name: "Full Repo: Recommend, Generate and Run TopN Tests",
+    description: "Run skyramp_analyze_changes to scan the repo and get ranked recommendations, generate tests for the top N recommended types, execute the generated tests, then clean up state files.",
+    intent: {
+        contextIndicators: [
+            "Use when the user wants to scan the entire repository with no specific endpoint or PR diff in mind — to get ranked test recommendations across all endpoints, generate the top N recommended test types, and execute them",
+            "Scope is always the full repository — the user has not mentioned a specific endpoint URL, path, or name",
+            "Use when the user asks to recommend, generate, and execute tests for the whole repo or says something like 'run the full repo test workflow'",
+            "Do NOT use when the user specifies a particular endpoint — use test_given_endpoint_comprehensively instead",
+            "Do NOT use when the user asks about a PR diff or branch-scoped analysis — use skyramp_analyze_changes directly instead",
+            "Do NOT use for simple single-tool requests such as 'generate a smoke test' or 'recommend tests for this PR'",
+        ],
+        purpose: "Full repo scan: get recommendations → Generate top N types → Execute generated tests → Clean up (no specific endpoint, no PR diff)",
+        workflowSummary: "Full Repo Scan → Recommend → Generate top N → Execute each test → Clean up",
+        examples: {
+            use: [
+                "scan the full repo and recommend and execute top 3 tests",
+                "run the full repo test workflow",
+                "recommend generate and execute tests for the whole repo",
+                "find the best tests to write for this codebase and run them",
+            ],
+            doNotUse: [
+                "comprehensively test the products endpoint → has a specific endpoint, use test_given_endpoint_comprehensively instead",
+                "recommend tests for my PR diff → branch-scoped, use skyramp_analyze_changes directly",
+                "generate a smoke test → single tool request, call skyramp_smoke_test_generation directly",
+            ],
+        },
+    },
+    steps: fullRepoRecommendGenerateExecuteTopNSteps,
+    inputParams: {
+        required: ["repositoryPath"],
+        optional: [
+            "topN",
+            "token",
+            "endpointURL",
+            "apiSchema",
+        ],
+    },
+};

package/build/commands/testThisEndpointCommand.js

@@ -0,0 +1,156 @@
+/**
+ * Predefined One-Click Command: Test this endpoint
+ *
+ * Spec order:
+ *   skyramp_analyze_changes (combined analyze + discover + recommend)
+ *   → Evaluate missing (recommended minus existing)
+ *   → Generate missing tests (by type)
+ *   → Execute generated tests
+ *   → [if existing tests found] Analyze test health → Optional batch execute → Actions
+ *   → State cleanup
+ */
+const comprehensivelyTestGivenEndpointSteps = [
+    {
+        stepIndex: 0,
+        title: "Ensure workspace is initialized",
+        description: "First check whether the repositoryPath is a git repository by verifying that a .git directory exists at the repo root. If there is no .git directory, do not attempt to initialize a Skyramp workspace and proceed without one. If .git exists, check whether .skyramp/workspace.yml exists. If workspace.yml exists, read it and capture language, framework, outputDir, and api.baseUrl for use in later steps. If workspace.yml does not exist and the user has not declined initialization, call skyramp_initialize_workspace with repositoryPath to create it, then read and capture language, framework, outputDir, and api.baseUrl.",
+        toolCall: {
+            toolName: "skyramp_initialize_workspace",
+            description: "Initialize Skyramp workspace if not already present",
+            inputs: {
+                workspacePath: { source: "user", paramKey: "repositoryPath" },
+            },
+        },
+        conditionalGuidance: "Follow server-level init rules: (1) Check for .git at repositoryPath — if missing, do not call skyramp_initialize_workspace and proceed without a workspace. (2) If .git exists, check for .skyramp/workspace.yml — if it exists, read it and do not call skyramp_initialize_workspace. (3) If workspace.yml does not exist, call skyramp_initialize_workspace only if the user has not explicitly declined. If the user declines, proceed without a workspace. Always capture language, framework, outputDir, and api.baseUrl for later steps.",
+    },
+    {
+        stepIndex: 1,
+        title: "Analyze changes and get recommendations",
+        description: "Call skyramp_analyze_changes with repositoryPath and scope from the one-click invocation. It scans endpoints, discovers existing tests, and returns ranked test recommendations along with a stateFile path. The response includes a JSON block with stateFile, sessionId, and a summary (including existingTestCount), plus a ranked recommendations section. Capture the stateFile path and the ranked recommendations for later steps. The full list of existing tests is not in the response — it is stored in the stateFile on disk.",
+        toolCall: {
+            toolName: "skyramp_analyze_changes",
+            description: "Analyze repo, discover tests, and generate ranked recommendations; returns stateFile",
+            inputs: {
+                repositoryPath: { source: "user", paramKey: "repositoryPath" },
+                scope: { source: "literal", value: "full_repo" },
+            },
+            outputs: ["stateFile", "recommendations"],
+        },
+        conditionalGuidance: "If endpointURL is provided by the user, note it for use in generation steps. Capture the stateFile path and ranked recommendations from the response. The existing test list is not returned directly — it is embedded in the stateFile and will be used by skyramp_analyze_test_health in step 5.",
+    },
+    {
+        stepIndex: 2,
+        title: "Evaluate missing tests",
+        description: "Using the ranked recommendations from step 1, determine which test types are missing coverage for the target endpoint. The step 1 response includes an existingTestCount in its summary — if it is 0 for the target endpoint, all recommended types are missing. If existingTestCount > 0, the full existing test list is in the stateFile (it will be processed by skyramp_analyze_test_health in step 5); for now, conservatively treat all recommended types as candidates to generate unless the recommendations explicitly note coverage. Build the list of types to generate in step 3. If all recommended types are already covered, skip steps 3 and 4.",
+        conditionalGuidance: "For each recommended type (high priority first, then medium), check whether the recommendations indicate existing coverage for the target endpoint. If not indicated, add the type to the 'generate' list. If existingTestCount from step 1 is 0, all types are missing. If all recommended types have coverage, steps 3 and 4 can be skipped.",
+    },
+    {
+        stepIndex: 3,
+        title: "Generate missing tests (by type)",
+        description: "IMPORTANT — UI or E2E in missing list: If UI or E2E test types are in the 'missing' list, first search the repository for existing trace files suitable for the target endpoint (look for .zip or .json Skyramp trace files in the repo that reference the endpoint path or URL). If suitable traces are found, use them directly as inputs to skyramp_ui_test_generation (playwrightInput) or skyramp_e2e_test_generation (trace + playwrightInput) — skip trace collection. If no suitable traces exist in the repo, collect them: call skyramp_start_trace_collection (playwright: true, outputDir: absolute path from workspace.yml), have the user interact with the target endpoint in the browser, then call skyramp_stop_trace_collection (playwrightEnabled: true, same outputDir). Use the produced trace file and Playwright zip as inputs for generation.\n\nFor all other types in the 'missing' list, call the corresponding generation tool using endpointURL from the one-click invocation (or api.baseUrl + endpoint path from recommendation), apiSchema, language, framework, and outputDir from workspace.yml. Capture each generated test file path.",
+        conditionalGuidance: "Tool mapping by type — smoke: skyramp_smoke_test_generation, contract: skyramp_contract_test_generation, integration: skyramp_integration_test_generation, fuzz: skyramp_fuzz_test_generation, load: skyramp_load_test_generation, e2e: skyramp_e2e_test_generation, ui: skyramp_ui_test_generation. Only generate types in the 'missing' list. For UI/E2E: (1) search repo for existing traces for the target endpoint; (2) if found, use them directly; (3) if not found, run skyramp_start_trace_collection → user interaction → skyramp_stop_trace_collection, then use produced traces. Record each generated test file path for step 4.",
+    },
+    {
+        stepIndex: 4,
+        title: "Execute generated tests",
+        description: "Before calling skyramp_execute_test, resolve the auth token using only information available to the workflow: (1) if the user provided a token param, use it directly; (2) otherwise, check .skyramp/workspace.yml or other repo config for a documented token value; (3) if no token can be resolved, proceed with empty string '' and rely on skyramp_execute_test to surface 401/403 errors — then report the auth failure to the user and ask them to provide a Bearer token to re-run.",
+        toolCall: {
+            toolName: "skyramp_execute_test",
+            description: "Execute each generated test; resolve token before calling. For each generated test file path returned directly by the generation tools in step 3, invoke this tool with testFile set to that path.",
+            inputs: {
+                workspacePath: { source: "user", paramKey: "repositoryPath" },
+                language: { source: "literal", value: "from workspace" },
+                testType: { source: "literal", value: "from generated test / recommendation" },
+                testFile: {
+                    source: "literal",
+                    value: "path to a single generated test file; for each test path returned by generation tools in step 3, call skyramp_execute_test separately with testFile set to that path",
+                },
+                token: { source: "user", paramKey: "token" },
+            },
+        },
+        conditionalGuidance: "Skip if step 3 generated no tests. Iterate over each generated test file path returned directly from the tools invoked in step 3 and call skyramp_execute_test once per file. Token resolution: (1) user-provided token; (2) token from .skyramp/workspace.yml or repo config; (3) empty string '' — let skyramp_execute_test surface auth errors, then ask the user for a Bearer token to re-run.",
+    },
+    {
+        stepIndex: 5,
+        title: "Analyze test health for existing tests (only if step 1 found existing tests for the target endpoint)",
+        description: "Run only if step 1 discovered at least one existing test specifically for the target endpoint. Call skyramp_analyze_test_health with the stateFile from step 1. This assesses each existing test for drift and health, then returns instructions for the LLM to assign health scores and actions (UPDATE/REGENERATE/VERIFY). Follow the returned prompt to complete the assessment, then call skyramp_actions in step 7.",
+        toolCall: {
+            toolName: "skyramp_analyze_test_health",
+            description: "Drift and health assessment for existing tests; returns LLM assessment prompt",
+            inputs: {
+                stateFile: { source: "step", stepIndex: 1, outputKey: "stateFile" },
+            },
+            outputs: ["stateFile"],
+        },
+        conditionalGuidance: "Only run when step 1 found existing tests specifically for the target endpoint. If no tests were found for the target endpoint, skip steps 5–7 and go to step 8 (cleanup).",
+    },
+    {
+        stepIndex: 6,
+        title: "Optional: execute existing tests in batch (only if step 5 ran)",
+        description: "Run only if step 5 ran. Optionally call skyramp_execute_tests with the stateFile from step 5 to run existing tests and capture pass/fail results. Merge results back into the state file for use by skyramp_actions. Use token from user or empty string. If you skip this step, pass the stateFile from step 5 directly to step 7.",
+        toolCall: {
+            toolName: "skyramp_execute_tests",
+            description: "Optionally run existing tests in batch; updates state with results",
+            inputs: {
+                stateFile: { source: "step", stepIndex: 5, outputKey: "stateFile" },
+                authToken: { source: "user", paramKey: "token" },
+            },
+            outputs: ["stateFile"],
+        },
+        conditionalGuidance: "Only run when step 5 was executed. This step is optional — skip if batch execution is not needed.",
+    },
+    {
+        stepIndex: 7,
+        title: "Run maintenance actions (only if step 5 ran)",
+        description: "Run only if step 5 ran. Call skyramp_actions with the stateFile from step 6 if step 6 ran, or step 5's stateFile if step 6 was skipped. This applies recommended fixes (UPDATE/REGENERATE/VERIFY) to existing tests and generates tests for new endpoints. Call it immediately after the assessment without waiting for user confirmation.",
+        conditionalGuidance: "Only run when step 5 was executed. Use step 6's stateFile if step 6 ran; use step 5's stateFile if step 6 was skipped. Call skyramp_actions with the resolved stateFile.",
+    },
+    {
+        stepIndex: 8,
+        title: "Clean up state files",
+        description: "Call skyramp_state_cleanup with action 'cleanup' and maxAgeHours set to 1 to remove temporary state files created by the analysis and maintenance toolsets. These live in system temp (e.g. /tmp) — not in the user repo.",
+        toolCall: {
+            toolName: "skyramp_state_cleanup",
+            description: "Remove temporary state files from system temp",
+            inputs: {
+                action: { source: "literal", value: "cleanup" },
+                maxAgeHours: { source: "literal", value: 1 },
+            },
+        },
+    },
+];
+export const TEST_GIVEN_ENDPOINT_COMPREHENSIVELY_COMMAND = {
+    id: "test_given_endpoint_comprehensively",
+    name: "Test this endpoint comprehensively",
+    description: "Comprehensively test a REST API endpoint: analyze changes + discover existing tests + get recommendations in one step, then evaluate missing tests, generate only missing tests, execute them — then (if existing tests were found) run the test health analysis toolset (health assessment → optional batch execute → actions). State files stay in system temp.",
+    intent: {
+        contextIndicators: [
+            "Use when the user names or references a specific REST API endpoint (by path such as /api/products, full URL, or name such as 'products endpoint') and wants a complete multi-step test pipeline for it",
+            "Covers the full endpoint testing lifecycle: discover existing tests → evaluate missing coverage → generate missing tests → execute → health analysis → maintenance actions",
+            "Only use when the user explicitly signals a full or deep pipeline — words like 'comprehensively', 'thoroughly', 'deep test', 'full test pipeline', or 'all test types'. Do NOT trigger on bare phrases like 'test this endpoint' or 'test the products endpoint' alone — those are ambiguous and may only mean a single smoke test",
+            "Do NOT use for broad repo-level requests where no specific endpoint is named — use skyramp_analyze_changes directly instead",
+            "Do NOT use for simple single-tool requests such as 'generate a smoke test for this endpoint' — those go directly to the generation tool",
+        ],
+        purpose: "Deep test a given endpoint: discover existing → evaluate missing → generate missing → execute → (if existing found) health analysis → maintenance actions → clean up",
+        workflowSummary: "Analyze Changes → Evaluate missing → Generate missing → Execute generated → [if existing] Test Health → Batch execute → Actions → Clean up",
+        examples: {
+            use: [
+                "comprehensively test the products endpoint",
+                "thoroughly test /api/v1/orders",
+                "deep test the authentication endpoint",
+                "run the full test pipeline for /api/users",
+            ],
+            doNotUse: [
+                "test this endpoint → ambiguous, may mean a single smoke test only",
+                "generate a smoke test for /api/products → single tool request, call skyramp_smoke_test_generation directly",
+                "recommend tests for my PR diff → use skyramp_analyze_changes directly",
+                "scan the full repo and run top tests → use full_repo_scan_recommend_generate_and_execute_top_n_tests instead",
+            ],
+        },
+    },
+    steps: comprehensivelyTestGivenEndpointSteps,
+    inputParams: {
+        required: ["repositoryPath"],
+        optional: ["endpointURL", "apiSchema", "topN", "token"],
+    },
+};

package/build/index.js

@@ -7,6 +7,7 @@ import { registerTraceTool } from "./tools/trace/startTraceCollectionTool.js";
 import { registerTraceStopTool } from "./tools/trace/stopTraceCollectionTool.js";
 import { registerExecuteSkyrampTestTool } from "./tools/executeSkyrampTestTool.js";
 import { registerTestGenerationPrompt } from "./prompts/testGenerationPrompt.js";
+import { AUTH_PLACEHOLDER_TOKEN } from "./types/TestTypes.js";
 import { logger } from "./utils/logger.js";
 import { registerUITestTool } from "./tools/generate-tests/generateUIRestTool.js";
 import { registerSmokeTestTool } from "./tools/generate-tests/generateSmokeRestTool.js";
@@ -26,6 +27,7 @@ import { registerAnalyzeChangesTool, registerAnalyzeTestHealthTool, registerExec
 import { registerTestbotPrompt, registerTestbotResource, } from "./prompts/testbot/testbot-prompts.js";
 import { registerSubmitReportTool } from "./tools/submitReportTool.js";
 import { registerInitializeWorkspaceTool } from "./tools/workspace/initializeWorkspaceTool.js";
+import { registerOneClickTool } from "./tools/one-click/oneClickTool.js";
 import { registerAnalysisResources } from "./resources/analysisResources.js";
 import { AnalyticsService } from "./services/AnalyticsService.js";
 import { initCheck } from "./utils/initAgent.js";
@@ -49,6 +51,8 @@ const server = new McpServer({
 ## Rules
 - NEVER show CLI commands. ALWAYS use the MCP tools provided.
 - For UI and E2E tests, use the trace collection start/stop tools.
+- When the user asks to comprehensively, thoroughly, or deeply test a specific endpoint: MUST call \`skyramp_one_click_tool\` with workflow \`test_given_endpoint_comprehensively\` first. Do NOT self-orchestrate the steps manually.
+- When the user asks to scan the full repo, recommend, generate, and execute top N tests: MUST call \`skyramp_one_click_tool\` with workflow \`full_repo_scan_recommend_generate_and_execute_top_n_tests\`.
 
 ## Test Management Flow
 Use \`skyramp_analyze_changes\` as the single entry point for both test recommendations and test health analysis.
@@ -92,14 +96,16 @@ Follow this flow EVERY time before calling any Skyramp tool:
 Before calling ANY test generation tool, you MUST follow this flow:
 
 1. **Read** the .skyramp/workspace.yml file to get the configured defaults.
-2. **Extract** the \`language\`, \`framework\`, \`outputDir\`, and \`api.baseUrl\` from the services section.
+2. **Extract** the \`language\`, \`framework\`, \`outputDir\`, \`api.baseUrl\`, \`api.authHeader\`, and \`api.authType\` from the services section.
 3. **Use those values** as defaults for the test generation tool call. Do NOT ask the user for these values if they are already configured in the workspace file.
 4. **CRITICAL — endpointURL**: The \`endpointURL\` parameter MUST be the full URL to the specific endpoint being tested, NOT just the base URL. Construct it by combining \`api.baseUrl\` with the endpoint path. Example: if \`api.baseUrl\` is \`http://localhost:8000\` and the endpoint is \`/api/v1/products\`, pass \`endpointURL: "http://localhost:8000/api/v1/products"\`. NEVER pass just the base URL (e.g. \`http://localhost:8000\`) as \`endpointURL\`.
 5. **CRITICAL — scenario generation**: When calling \`skyramp_scenario_test_generation\`, ALWAYS pass:
    - \`baseURL\`: The full base URL from \`api.baseUrl\` (e.g., \`http://localhost:3000\`). This determines the scheme, host, and port in the generated trace. Without it, the trace defaults to https:443 which is almost always wrong for local development.
-   - \`authHeader\`: The auth header name from \`api.authHeader\` in the workspace config. Use \`Cookie\` for cookie/session-based auth (NextAuth, etc.), \`Authorization\` for Bearer tokens, \`X-API-Key\` for API keys. Without it, the trace defaults to \`Authorization: Bearer\` which breaks cookie-based apps.
+   - \`authHeader\`: Which HTTP header carries the auth credential. Get it from \`api.authHeader\` in workspace config. Examples: \`Authorization\` (Bearer/Token auth), \`X-Api-Key\` (API key auth), \`Cookie\` (session/cookie auth like NextAuth). Pass \`""\` to skip auth entirely (unauthenticated endpoints or \`api.authType: "none"\`).
+   - \`authScheme\`: Only when \`authHeader\` is \`Authorization\`. The prefix before the token (e.g., \`"Bearer"\` → \`Authorization: Bearer <token>\`). Common values: \`"Bearer"\`, \`"Basic"\`, \`"Token"\`. Leave empty if the API uses raw tokens with no prefix. Ignored for non-Authorization headers. **Derive from**: (1) OpenAPI spec \`securitySchemes\`/\`securityDefinitions\`, (2) source code auth middleware (\`passport.use\`, \`jwt.verify\`, header parsing logic), (3) workspace \`api.authType\`. **Do NOT guess.**
+   - \`authToken\`: The full header value, used verbatim. When omitted, \`SKYRAMP_PLACEHOLDER_TOKEN\` is auto-generated (combined with \`authScheme\` for Authorization headers). Only provide when the header needs a specific format — e.g., \`"session=${AUTH_PLACEHOLDER_TOKEN}"\` for Cookie. For Authorization headers, use \`authScheme\` instead. **Do NOT fabricate token values.**
    - \`apiSchema\` is OPTIONAL — omit it for code-first apps without OpenAPI specs.
-6. **CRITICAL — integration test from scenario**: When calling \`skyramp_integration_test_generation\` with a \`scenarioFile\`, ALSO pass \`authHeader\` (same value as used in scenario generation). This tells the CLI which header to parameterize with the auth token. Without it, the generated test defaults to \`Authorization: Bearer\` regardless of what's in the trace.
+6. **CRITICAL — integration test from scenario**: When calling \`skyramp_integration_test_generation\` with a \`scenarioFile\`, ALSO pass \`authHeader\` and the same auth parameters used in scenario generation (\`authScheme\` for Authorization headers, or \`authToken\` for non-Authorization headers).
 7. **If the workspace file does not exist**, or the needed values (language, framework, outputDir) are missing from the workspace config, ASK the user which language and framework they want before calling the tool.
 8. The user can always override workspace defaults by explicitly specifying values in their request.
 `,
@@ -190,6 +196,8 @@ registerActionsTool(server);
 registerStateCleanupTool(server);
 // Register workspace management tools
 registerInitializeWorkspaceTool(server);
+// Register one-click orchestrated workflows
+registerOneClickTool(server);
 // Register other Skyramp tools
 const infrastructureTools = [
     registerLoginTool,

package/build/prompts/test-recommendation/analysisOutputPrompt.js

@@ -34,6 +34,13 @@ Mounting context.`
 UI-only PR — read changed components to find API calls (fetch, axios, hooks).`
             : `### Step 2: Identify affected endpoints
 No API route changes detected — read changed files to identify affected endpoints.`;
+    const criticalPatternStep = `### Step 2.5: Identify critical patterns for test categorization
+Look for these patterns in model/schema/handler files to inform test recommendations:
+- **Unique constraints**: \`@unique\`, \`unique: true\`, unique indexes, \`.refine()\` uniqueness checks, \`UNIQUE\` in SQL migrations
+- **Cascade deletes**: \`ON DELETE CASCADE\`, \`.onDelete("cascade")\`, manual cascade logic in delete handlers
+- **Permission checks**: auth middleware, ownership guards (\`req.user.id === resource.ownerId\`), role-based access control, \`isOwner\` assertions
+- **Breaking changes in diff**: route renames, auth header changes, removed required fields, changed status codes
+Tag each finding with its category (security_boundary, business_rule, data_integrity, breaking_change) for the recommendation step.`;
     const step3Content = useHealthFlow
         ? `### Step 3: Identify tests at risk of drift
 Assess which existing tests may be broken by the changes in this diff.
@@ -58,6 +65,8 @@ ${changedFiles}
 
 ${step2}
 
+${criticalPatternStep}
+
 ${step3Content}`;
 }
 export function buildAnalysisOutputText(p) {
@@ -79,7 +88,7 @@ ${p.scannedEndpoints.map((ep) => `  ${ep.methods.join("|")} ${ep.path} (${ep.sou
 `
         : "";
     const wsLine = p.wsBaseUrl
-        ? `**Base URL**: \`${p.wsBaseUrl}\` | **Auth header**: \`${p.wsAuthHeader || "Authorization"}\``
+        ? `**Base URL**: \`${p.wsBaseUrl}\`${p.wsAuthHeader ? ` | **Auth header**: \`${p.wsAuthHeader}\`` : ""}${p.wsAuthType ? ` | **Auth type**: \`${p.wsAuthType}\`` : ""}`
         : "";
     const specSection = p.wsSchemaPath
         ? `