@skyramp/mcp 0.0.62 → 0.0.63-rc.2

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

@@ -0,0 +1,132 @@
+import { z } from "zod";
+import { logger } from "../../utils/logger.js";
+import { StateManager, } from "../../utils/AnalysisStateManager.js";
+import path from "path";
+import { AnalyticsService } from "../../services/AnalyticsService.js";
+import { buildDriftAnalysisPrompt } from "../../prompts/test-maintenance/drift-analysis-prompt.js";
+const TOOL_NAME = "skyramp_analyze_test_health";
+export function registerAnalyzeTestHealthTool(server) {
+    server.registerTool(TOOL_NAME, {
+        description: `Generate drift and health assessment instructions for existing tests — second step of the unified Test Health Analysis Flow.
+
+**PREREQUISITE:** Call \`skyramp_analyze_changes\` first to get a stateFile.
+
+This tool reads existing tests, the branch diff, and scanned endpoints from the stateFile,
+then returns a structured prompt for the LLM to assess each test for drift and health.
+
+The LLM follows the returned prompt to assign health scores (0–100), drift details, and
+actions (UPDATE / REGENERATE / VERIFY / DELETE) for each test, then calls \`skyramp_actions\`.
+
+**This tool does not write drift or health data to the stateFile.** Assessment results
+exist only in the LLM's reasoning context and are acted on by \`skyramp_actions\`.
+
+(Optional) Call \`skyramp_execute_tests\` before \`skyramp_actions\` to validate tests live.
+
+**Output:** LLM drift analysis prompt and assessment instructions.`,
+        inputSchema: {
+            stateFile: z
+                .string()
+                .describe("Path to state file from skyramp_analyze_changes"),
+        },
+    }, async (args) => {
+        let errorResult;
+        try {
+            logger.info(`Analyzing test health from state file: ${args.stateFile}`);
+            // Load UnifiedAnalysisState from state file
+            const stateManager = StateManager.fromStatePath(args.stateFile);
+            const stateData = await stateManager.readData();
+            const fullState = await stateManager.readFullState();
+            const repositoryPath = fullState?.metadata.repositoryPath || "";
+            if (!stateData) {
+                errorResult = {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: "State file is empty or invalid",
+                                stateFile: args.stateFile,
+                            }, null, 2),
+                        },
+                    ],
+                    isError: true,
+                };
+                return errorResult;
+            }
+            const existingTests = stateData.existingTests || [];
+            logger.info(`Loaded ${existingTests.length} existing tests from state file`);
+            if (!repositoryPath || typeof repositoryPath !== "string") {
+                errorResult = {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: "repositoryPath not found in state file metadata",
+                                details: "State file must contain repositoryPath in metadata",
+                            }, null, 2),
+                        },
+                    ],
+                    isError: true,
+                };
+                return errorResult;
+            }
+            const absoluteRepoPath = path.resolve(repositoryPath);
+            // ── Build and return drift analysis prompt ──
+            const diff = stateData.repositoryAnalysis?.diff;
+            // Build structured diff summary for the prompt
+            let parsedDiffText = "";
+            if (diff) {
+                const lines = [];
+                if (diff.currentBranch)
+                    lines.push(`**Branch**: ${diff.currentBranch} → base: ${diff.baseBranch}`);
+                if (diff.changedFiles?.length > 0)
+                    lines.push(`**Changed Files** (${diff.changedFiles.length}): ${diff.changedFiles.join(", ")}`);
+                if (diff.newEndpoints?.length > 0) {
+                    lines.push(`**New Endpoints** (${diff.newEndpoints.length}): ${diff.newEndpoints
+                        .map((e) => e.methods ? e.methods.map((m) => `${m.method} ${e.path}`).join(", ") : `${e.method} ${e.path}`)
+                        .join(", ")}`);
+                }
+                if (diff.modifiedEndpoints?.length > 0) {
+                    lines.push(`**Modified Endpoints** (${diff.modifiedEndpoints.length}): ${diff.modifiedEndpoints
+                        .map((e) => e.methods ? e.methods.map((m) => `${m.method} ${e.path}`).join(", ") : `${e.method} ${e.path}`)
+                        .join(", ")}`);
+                }
+                parsedDiffText = lines.join("\n");
+            }
+            const scannedEndpoints = stateData.repositoryAnalysis?.skeletonEndpoints || [];
+            const promptText = buildDriftAnalysisPrompt({
+                existingTests,
+                parsedDiff: parsedDiffText || undefined,
+                scannedEndpoints,
+                repositoryPath: absoluteRepoPath,
+                stateFile: stateManager.getStatePath(),
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: promptText,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            logger.error(`Test health analysis failed: ${error.message}`, error);
+            errorResult = {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: error.message,
+                            details: error.stack,
+                        }, null, 2),
+                    },
+                ],
+                isError: true,
+            };
+            return errorResult;
+        }
+        finally {
+            AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, {});
+        }
+    });
+}

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

@@ -0,0 +1,198 @@
+import { z } from "zod";
+import { TestExecutionService } from "../../services/TestExecutionService.js";
+import { logger } from "../../utils/logger.js";
+import { StateManager, } from "../../utils/AnalysisStateManager.js";
+import * as path from "path";
+import * as fs from "fs";
+import { AnalyticsService } from "../../services/AnalyticsService.js";
+const TOOL_NAME = "skyramp_execute_tests";
+export function registerExecuteTestsTool(server) {
+    server.registerTool(TOOL_NAME, {
+        description: `Execute existing Skyramp tests live — optional third step of the unified Test Health Analysis Flow.
+
+**PREREQUISITE:** Call \`skyramp_analyze_test_health\` first.
+
+Runs all discovered tests in parallel batches (up to 5 concurrent). Results are merged
+back into the state file for use by \`skyramp_actions\`.
+
+**Key features:**
+- Parallel execution: up to 5 tests simultaneously
+- Isolated execution: each test in a separate Docker container
+- Error resilient: failed tests don't stop the batch
+
+**Next step:** Call \`skyramp_actions\` with the returned stateFile.
+
+**Output:** {summary, stateFile, sessionId, stateFileSize, message}`,
+        inputSchema: {
+            stateFile: z
+                .string()
+                .describe("Path to state file from skyramp_analyze_test_health (required)"),
+            authToken: z
+                .string()
+                .optional()
+                .default("")
+                .describe("Authentication token for test execution. Use empty string if no auth required."),
+            timeout: z
+                .number()
+                .optional()
+                .describe("Timeout in milliseconds for each test (default: 300000 = 5 minutes)"),
+        },
+    }, async (args) => {
+        let errorResult;
+        try {
+            logger.info("Starting test execution from unified state");
+            // Load UnifiedAnalysisState from state file
+            const stateManager = StateManager.fromStatePath(args.stateFile);
+            const stateData = await stateManager.readData();
+            const fullState = await stateManager.readFullState();
+            const repositoryPath = fullState?.metadata.repositoryPath || "";
+            if (!stateData) {
+                errorResult = {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: "State file is empty or invalid",
+                                stateFile: args.stateFile,
+                            }, null, 2),
+                        },
+                    ],
+                    isError: true,
+                };
+                return errorResult;
+            }
+            const originalTestResults = stateData.existingTests || [];
+            if (originalTestResults.length === 0) {
+                errorResult = {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: "No existing tests found in state file",
+                                stateFile: args.stateFile,
+                            }, null, 2),
+                        },
+                    ],
+                    isError: true,
+                };
+                return errorResult;
+            }
+            logger.info(`Loaded ${originalTestResults.length} tests from state file: ${args.stateFile}`);
+            if (!repositoryPath || typeof repositoryPath !== "string") {
+                errorResult = {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: "repositoryPath not found in state file metadata",
+                            }, null, 2),
+                        },
+                    ],
+                    isError: true,
+                };
+                return errorResult;
+            }
+            const absoluteWorkspacePath = path.resolve(repositoryPath);
+            if (!fs.existsSync(absoluteWorkspacePath)) {
+                errorResult = {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: `Workspace path does not exist: ${absoluteWorkspacePath}`,
+                            }, null, 2),
+                        },
+                    ],
+                    isError: true,
+                };
+                return errorResult;
+            }
+            const testsToExecute = originalTestResults.map((test) => ({
+                testFile: test.testFile,
+                language: test.language,
+                testType: test.testType,
+            }));
+            const testOptions = testsToExecute.map((test) => ({
+                testFile: test.testFile,
+                workspacePath: absoluteWorkspacePath,
+                language: test.language,
+                testType: test.testType,
+                token: args.authToken || "",
+                timeout: args.timeout,
+            }));
+            logger.info(`Executing ${testOptions.length} tests in parallel batches (max 5 concurrent)`);
+            const executionService = new TestExecutionService();
+            const executionResult = await executionService.executeBatch(testOptions);
+            logger.info(`Batch execution complete: ${executionResult.passed} passed, ` +
+                `${executionResult.failed} failed, ${executionResult.crashed} crashed`);
+            // Enrich test results with execution data
+            const enrichedTests = originalTestResults.map((test) => {
+                const execResult = executionResult.results.find((r) => r.testFile === test.testFile);
+                if (execResult) {
+                    return {
+                        ...test,
+                        execution: {
+                            passed: execResult.passed,
+                            duration: execResult.duration,
+                            errors: execResult.errors,
+                            warnings: execResult.warnings,
+                            crashed: execResult.crashed,
+                            stdout: execResult.output,
+                            stderr: execResult.errors.join("\n"),
+                            executionTimestamp: execResult.executedAt,
+                        },
+                    };
+                }
+                return test;
+            });
+            // Save updated state
+            await stateManager.writeData({ ...stateData, existingTests: enrichedTests }, {
+                repositoryPath: absoluteWorkspacePath,
+                step: "execution",
+            });
+            const stateSize = await stateManager.getSizeFormatted();
+            logger.info(`Saved ${enrichedTests.length} tests with execution data to: ${stateManager.getStatePath()} (${stateSize})`);
+            const responseData = {
+                summary: {
+                    totalTests: executionResult.totalTests,
+                    passed: executionResult.passed,
+                    failed: executionResult.failed,
+                    crashed: executionResult.crashed,
+                    totalDuration: executionResult.totalDuration,
+                    totalDurationSeconds: (executionResult.totalDuration / 1000).toFixed(2),
+                },
+                stateFile: stateManager.getStatePath(),
+                sessionId: stateManager.getSessionId(),
+                stateFileSize: stateSize,
+                message: `Execution complete. ${executionResult.passed} passed, ${executionResult.failed} failed, ${executionResult.crashed} crashed. Pass stateFile to skyramp_actions.`,
+                generatedAt: new Date().toISOString(),
+            };
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(responseData, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            logger.error(`Test execution failed: ${error.message}`, error);
+            errorResult = {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: error.message,
+                        }, null, 2),
+                    },
+                ],
+                isError: true,
+            };
+            return errorResult;
+        }
+        finally {
+            AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, {});
+        }
+    });
+}

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

@@ -0,0 +1,5 @@
+export { registerAnalyzeChangesTool } from "./analyzeChangesTool.js";
+export { registerAnalyzeTestHealthTool } from "./analyzeTestHealthTool.js";
+export { registerExecuteTestsTool } from "./executeTestsTool.js";
+export { registerActionsTool } from "./actionsTool.js";
+export { registerStateCleanupTool } from "./stateCleanupTool.js";

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

@@ -0,0 +1,163 @@
+import { z } from "zod";
+import { StateManager } from "../../utils/AnalysisStateManager.js";
+import { logger } from "../../utils/logger.js";
+import { AnalyticsService } from "../../services/AnalyticsService.js";
+const TOOL_NAME = "skyramp_state_cleanup";
+/**
+ * Register the state file cleanup tool with the MCP server
+ *
+ * This tool helps manage state files created during test analysis workflows.
+ * It can list existing state files and clean up old ones to save disk space.
+ */
+export function registerStateCleanupTool(server) {
+    server.registerTool(TOOL_NAME, {
+        description: `Manage and cleanup Skyramp state files.
+
+**WHAT IT DOES:**
+- List all existing state files with details (size, age, session ID, type)
+- Delete state files older than specified age
+- Show disk space usage by state files
+
+**STATE TYPES MANAGED:**
+- analysis: Test maintenance workflow (discovery, drift, execution, health)
+- recommendation: Test recommendation workflow (analyze repo, map tests, recommend)
+
+**WHEN TO USE:**
+- Periodically to clean up old analysis sessions
+- To check current state files in the system
+- To free up disk space from temporary analysis data
+
+**OPTIONS:**
+- action: "list" - Show all state files
+- action: "cleanup" - Delete old state files
+- maxAgeHours: How old files must be before deletion (default: 24 hours)
+
+**Output:**
+Information about state files and cleanup results.`,
+        inputSchema: {
+            action: z
+                .enum(["list", "cleanup"])
+                .describe('Action to perform: "list" shows all state files, "cleanup" deletes old files'),
+            maxAgeHours: z
+                .number()
+                .optional()
+                .default(24)
+                .describe("For cleanup action: delete files older than this many hours (default: 24)"),
+        },
+    }, async (args) => {
+        let errorResult;
+        try {
+            logger.info(`State file ${args.action} requested`);
+            if (args.action === "list") {
+                const stateFiles = await StateManager.listStateFiles();
+                if (stateFiles.length === 0) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    message: "No state files found",
+                                    totalFiles: 0,
+                                    totalSize: 0,
+                                }, null, 2),
+                            },
+                        ],
+                    };
+                }
+                const totalSize = stateFiles.reduce((sum, file) => sum + file.size, 0);
+                const formatSize = (bytes) => {
+                    if (bytes === 0)
+                        return "0 B";
+                    const k = 1024;
+                    const sizes = ["B", "KB", "MB", "GB"];
+                    const i = Math.floor(Math.log(bytes) / Math.log(k));
+                    return `${parseFloat((bytes / Math.pow(k, i)).toFixed(2))} ${sizes[i]}`;
+                };
+                const fileDetails = stateFiles.map((file) => ({
+                    sessionId: file.sessionId,
+                    stateType: file.stateType,
+                    path: file.path,
+                    size: formatSize(file.size),
+                    sizeBytes: file.size,
+                    createdAt: file.createdAt.toISOString(),
+                    modifiedAt: file.modifiedAt.toISOString(),
+                    ageHours: ((Date.now() - file.modifiedAt.getTime()) /
+                        (1000 * 60 * 60)).toFixed(1),
+                }));
+                logger.info(`Found ${stateFiles.length} state files, total size: ${formatSize(totalSize)}`);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                totalFiles: stateFiles.length,
+                                totalSize: formatSize(totalSize),
+                                totalSizeBytes: totalSize,
+                                files: fileDetails,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            else if (args.action === "cleanup") {
+                const maxAgeHours = args.maxAgeHours || 24;
+                const deletedCount = await StateManager.cleanupOldStateFiles(maxAgeHours);
+                logger.info(`Cleaned up ${deletedCount} state files older than ${maxAgeHours} hours`);
+                if (deletedCount > 0) {
+                    try {
+                        await server.sendResourceListChanged();
+                    }
+                    catch {
+                        logger.warning("Unable to update MCP clients with new resource list");
+                    }
+                }
+                const remainingFiles = await StateManager.listStateFiles();
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                deletedCount,
+                                maxAgeHours,
+                                remainingFiles: remainingFiles.length,
+                                message: deletedCount > 0
+                                    ? `Successfully deleted ${deletedCount} state file(s) older than ${maxAgeHours} hours`
+                                    : `No state files found older than ${maxAgeHours} hours`,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            errorResult = {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "Invalid action",
+                        }, null, 2),
+                    },
+                ],
+                isError: true,
+            };
+            return errorResult;
+        }
+        catch (error) {
+            logger.error(`State cleanup failed: ${error.message}`, error);
+            errorResult = {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: error.message,
+                        }, null, 2),
+                    },
+                ],
+                isError: true,
+            };
+            return errorResult;
+        }
+        finally {
+            AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, {});
+        }
+    });
+}

package/build/tools/test-recommendation/recommendTestsTool.js

@@ -105,7 +105,7 @@ For each recommended test, you'll get:
             }
             stateData = normalizeRecommendationState(stateData);
             const { analysisScope } = stateData;
-            let { repositoryPath, analysis } = stateData;
+            const { repositoryPath, analysis } = stateData;
             if (!analysis) {
                 throw new Error("Session is missing analysis data. Run skyramp_analyze_repository first.");
             }

package/build/utils/analyze-openapi.js

@@ -12,11 +12,11 @@ export async function analyzeOpenAPIWithGivenEndpoint(apiSchemaInput, uriInput,
         const requiredPathParams = pathParamRequired
             ? pathParamRequired.split(",").map((p) => p.trim())
             : [];
-        let providedPathParams = pathParamsInput
+        const providedPathParams = pathParamsInput
             ? pathParamsInput.split(",").map((param) => param.split("=")[0].trim())
             : [];
         // Find missing path parameters by comparing keys
-        let missingPathParams = requiredPathParams.filter((param) => !providedPathParams.includes(param));
+        const missingPathParams = requiredPathParams.filter((param) => !providedPathParams.includes(param));
         if (missingPathParams.length > 0) {
             return `${missingPathParams.join(", ")}`;
         }