@mxf-dev/core 1.0.0 → 2.0.0

package/dist/protocols/mcp/tools/TestTools.js

@@ -14,21 +14,112 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
-import { Logger } from '../../../utils/Logger.js';
+/**
+ * TestTools.ts
+ *
+ * Run a project's test suite with Jest, Mocha or Vitest, or let test_runner pick
+ * the one the project actually uses.
+ *
+ * On exit codes: a test runner exits non-zero when tests fail. That is the tool
+ * working — it ran the suite and the suite failed. So a failing suite comes back
+ * with `passed: false` and `isError: false`, and `isError` is reserved for the
+ * runner not being usable at all.
+ *
+ * Watch mode is deliberately not offered. These tools are request/response: a
+ * watching runner never exits, so the call would hang until it timed out.
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { TOOL_CATEGORIES } from '../../../constants/ToolNames.js';
+import { defineTool } from '../defineTool.js';
+import { ToolError } from '../ToolError.js';
 import { executeShellCommand } from './InfrastructureTools.js';
-const logger = new Logger('info', 'TestTools', 'server');
+/** Exit code the shell reports when a command could not be found or spawned. */
+const COMMAND_NOT_FOUND = 127;
+const workingDirectoryProperty = {
+    type: 'string',
+    description: 'Working directory path (defaults to the server working directory)'
+};
+/**
+ * Run a test runner via npx and normalize its output.
+ *
+ * Throws only when the runner could not be executed. A failing suite is a
+ * result, and comes back with passed: false.
+ */
+async function runTestRunner(runner, runnerArgs, workingDirectory, context) {
+    const startedAt = Date.now();
+    const result = await executeShellCommand('npx', [runner, ...runnerArgs], {
+        context: {
+            agentId: context.agentId,
+            channelId: context.channelId,
+            requestId: context.requestId
+        },
+        workingDirectory: workingDirectory || process.cwd(),
+        captureOutput: true
+    });
+    if (result.exitCode === COMMAND_NOT_FOUND) {
+        throw ToolError.preconditionFailed(`Could not run ${runner} — the command was not found. ` +
+            `Install it in the project before running this tool.`, { runner });
+    }
+    // Jest and Vitest write their summary to stderr; Mocha writes to stdout.
+    const output = [result.stdout, result.stderr].filter(Boolean).join('\n');
+    const counts = parseTestCounts(runner, output);
+    return {
+        runner,
+        passed: result.exitCode === 0,
+        ...counts,
+        executionTimeMs: Date.now() - startedAt,
+        output
+    };
+}
 /**
- * Test Tools for MXF
+ * Pull pass/fail counts out of a runner's summary.
  *
- * Provides comprehensive testing capabilities for multiple test runners
- * and testing frameworks including Jest, Mocha, Vitest, and others
+ * Each runner prints a different summary, so each gets its own pattern rather
+ * than one regex that half-matches all three.
  */
-export const jestTestTool = {
+function parseTestCounts(runner, output) {
+    if (runner === 'jest') {
+        // "Tests:       1 failed, 2 skipped, 17 passed, 20 total"
+        const summary = output.match(/^Tests:\s+(.+)$/m)?.[1] ?? '';
+        const read = (label) => {
+            const match = summary.match(new RegExp(`(\\d+)\\s+${label}`));
+            return match ? parseInt(match[1], 10) : 0;
+        };
+        return {
+            testsRun: read('total'),
+            testsPassed: read('passed'),
+            testsFailed: read('failed')
+        };
+    }
+    if (runner === 'vitest') {
+        // "Tests  1 failed | 17 passed (18)"
+        const summary = output.match(/^\s*Tests\s+(.+)$/m)?.[1] ?? '';
+        const passed = parseInt(summary.match(/(\d+)\s+passed/)?.[1] ?? '0', 10);
+        const failed = parseInt(summary.match(/(\d+)\s+failed/)?.[1] ?? '0', 10);
+        const total = parseInt(summary.match(/\((\d+)\)/)?.[1] ?? '0', 10);
+        return {
+            testsRun: total || passed + failed,
+            testsPassed: passed,
+            testsFailed: failed
+        };
+    }
+    // Mocha: "  17 passing (1s)" / "  1 failing"
+    const passed = parseInt(output.match(/(\d+)\s+passing/)?.[1] ?? '0', 10);
+    const failed = parseInt(output.match(/(\d+)\s+failing/)?.[1] ?? '0', 10);
+    return {
+        testsRun: passed + failed,
+        testsPassed: passed,
+        testsFailed: failed
+    };
+}
+export const jestTestTool = defineTool({
     name: 'test_jest',
-    description: 'Run Jest tests with comprehensive options',
+    category: TOOL_CATEGORIES.INFRASTRUCTURE,
+    description: 'Run Jest tests. passed is false when any test fails.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -39,142 +130,50 @@ export const jestTestTool = {
             },
             testNamePattern: {
                 type: 'string',
-                description: 'Run tests with names matching this pattern'
+                description: 'Run only tests whose name matches this pattern'
             },
             coverage: {
                 type: 'boolean',
                 default: false,
-                description: 'Generate test coverage report'
-            },
-            watchMode: {
-                type: 'boolean',
-                default: false,
-                description: 'Run tests in watch mode'
+                description: 'Generate a coverage report'
             },
             verbose: {
                 type: 'boolean',
                 default: false,
-                description: 'Display individual test results'
+                description: 'Report each test individually'
             },
             maxWorkers: {
                 type: 'number',
+                minimum: 1,
                 description: 'Maximum number of worker processes'
             },
-            workingDirectory: {
-                type: 'string',
-                description: 'Working directory path (defaults to current directory)'
-            }
+            workingDirectory: workingDirectoryProperty
         }
     },
-    handler: async (args, context) => {
-        try {
-            const jestArgs = ['--no-watchman', '--passWithNoTests'];
-            if (args.coverage) {
-                jestArgs.push('--coverage');
-            }
-            if (args.verbose) {
-                jestArgs.push('--verbose');
-            }
-            if (args.maxWorkers) {
-                jestArgs.push('--maxWorkers', args.maxWorkers.toString());
-            }
-            if (args.testNamePattern) {
-                jestArgs.push('--testNamePattern', args.testNamePattern);
-            }
-            if (args.watchMode) {
-                jestArgs.push('--watch');
-            }
-            if (args.testFiles && args.testFiles.length > 0) {
-                jestArgs.push(...args.testFiles);
-            }
-            const result = await executeShellCommand('npx', ['jest', ...jestArgs], {
-                workingDirectory: args.workingDirectory || process.cwd(),
-                captureOutput: true
-            });
-            // Parse Jest output for test results
-            let testsRun = 0;
-            let testsPassed = 0;
-            let testsFailed = 0;
-            let testSuites = 0;
-            let testSuitesPassed = 0;
-            let testSuitesFailed = 0;
-            if (result.stdout) {
-                // Parse test results
-                const runMatch = result.stdout.match(/Tests:\s+(\d+)\s+total/);
-                const passMatch = result.stdout.match(/Tests:\s+\d+\s+failed,\s+(\d+)\s+passed/);
-                const failMatch = result.stdout.match(/Tests:\s+(\d+)\s+failed/);
-                // Parse test suites
-                const suitesMatch = result.stdout.match(/Test Suites:\s+(\d+)\s+total/);
-                const suitesPassMatch = result.stdout.match(/Test Suites:\s+\d+\s+failed,\s+(\d+)\s+passed/);
-                const suitesFailMatch = result.stdout.match(/Test Suites:\s+(\d+)\s+failed/);
-                if (runMatch)
-                    testsRun = parseInt(runMatch[1]);
-                if (passMatch)
-                    testsPassed = parseInt(passMatch[1]);
-                if (failMatch)
-                    testsFailed = parseInt(failMatch[1]);
-                if (suitesMatch)
-                    testSuites = parseInt(suitesMatch[1]);
-                if (suitesPassMatch)
-                    testSuitesPassed = parseInt(suitesPassMatch[1]);
-                if (suitesFailMatch)
-                    testSuitesFailed = parseInt(suitesFailMatch[1]);
-                // Alternative parsing for different Jest output formats
-                if (testsRun === 0) {
-                    const totalMatch = result.stdout.match(/(\d+)\s+tests?\s+passed/);
-                    if (totalMatch) {
-                        testsRun = parseInt(totalMatch[1]);
-                        testsPassed = testsRun;
-                    }
-                }
-            }
-            const content = {
-                type: 'application/json',
-                data: {
-                    success: result.exitCode === 0,
-                    runner: 'jest',
-                    output: result.stdout || '',
-                    errorOutput: result.stderr || '',
-                    testsRun,
-                    testsPassed,
-                    testsFailed,
-                    testSuites,
-                    testSuitesPassed,
-                    testSuitesFailed,
-                    executionTime: result.executionTime,
-                    coverage: args.coverage ? 'Coverage report generated' : null,
-                    error: result.exitCode !== 0 ? result.stderr : null
-                }
-            };
-            return { content };
+    run: async (input, context) => {
+        const args = ['--no-watchman', '--passWithNoTests'];
+        if (input.coverage) {
+            args.push('--coverage');
         }
-        catch (error) {
-            logger.error('Jest test failed', { error });
-            const content = {
-                type: 'application/json',
-                data: {
-                    success: false,
-                    runner: 'jest',
-                    output: '',
-                    errorOutput: '',
-                    testsRun: 0,
-                    testsPassed: 0,
-                    testsFailed: 0,
-                    testSuites: 0,
-                    testSuitesPassed: 0,
-                    testSuitesFailed: 0,
-                    executionTime: 0,
-                    coverage: null,
-                    error: error instanceof Error ? error.message : String(error)
-                }
-            };
-            return { content };
+        if (input.verbose) {
+            args.push('--verbose');
+        }
+        if (input.maxWorkers) {
+            args.push('--maxWorkers', String(input.maxWorkers));
+        }
+        if (input.testNamePattern) {
+            args.push('--testNamePattern', input.testNamePattern);
         }
+        if (input.testFiles && input.testFiles.length > 0) {
+            args.push(...input.testFiles);
+        }
+        return runTestRunner('jest', args, input.workingDirectory, context);
     }
-};
-export const mochaTestTool = {
+});
+export const mochaTestTool = defineTool({
     name: 'test_mocha',
-    description: 'Run Mocha tests with comprehensive options',
+    category: TOOL_CATEGORIES.INFRASTRUCTURE,
+    description: 'Run Mocha tests. passed is false when any test fails.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -185,104 +184,51 @@ export const mochaTestTool = {
             },
             grep: {
                 type: 'string',
-                description: 'Run tests matching this pattern'
+                description: 'Run only tests matching this pattern'
             },
             reporter: {
                 type: 'string',
-                enum: ['spec', 'json', 'tap', 'dot', 'nyan', 'landing', 'list', 'progress', 'json-stream', 'min'],
+                enum: ['spec', 'dot', 'nyan', 'tap', 'json', 'min'],
                 default: 'spec',
-                description: 'Test reporter format'
+                description: 'Reporter format'
             },
             timeout: {
                 type: 'number',
-                default: 2000,
-                description: 'Test timeout in milliseconds'
+                minimum: 1,
+                description: 'Per-test timeout in milliseconds'
             },
             recursive: {
                 type: 'boolean',
                 default: false,
                 description: 'Look for tests in subdirectories'
             },
-            workingDirectory: {
-                type: 'string',
-                description: 'Working directory path (defaults to current directory)'
-            }
+            workingDirectory: workingDirectoryProperty
         }
     },
-    handler: async (args, context) => {
-        try {
-            const mochaArgs = ['--reporter', args.reporter || 'spec'];
-            if (args.timeout) {
-                mochaArgs.push('--timeout', args.timeout.toString());
-            }
-            if (args.grep) {
-                mochaArgs.push('--grep', args.grep);
-            }
-            if (args.recursive) {
-                mochaArgs.push('--recursive');
-            }
-            if (args.testFiles && args.testFiles.length > 0) {
-                mochaArgs.push(...args.testFiles);
-            }
-            else {
-                mochaArgs.push('test/**/*.js');
-            }
-            const result = await executeShellCommand('npx', ['mocha', ...mochaArgs], {
-                workingDirectory: args.workingDirectory || process.cwd(),
-                captureOutput: true
-            });
-            // Parse Mocha output for test results
-            let testsRun = 0;
-            let testsPassed = 0;
-            let testsFailed = 0;
-            if (result.stdout) {
-                const passMatch = result.stdout.match(/(\d+)\s+passing/);
-                const failMatch = result.stdout.match(/(\d+)\s+failing/);
-                if (passMatch)
-                    testsPassed = parseInt(passMatch[1]);
-                if (failMatch)
-                    testsFailed = parseInt(failMatch[1]);
-                testsRun = testsPassed + testsFailed;
-            }
-            const content = {
-                type: 'application/json',
-                data: {
-                    success: result.exitCode === 0,
-                    runner: 'mocha',
-                    output: result.stdout || '',
-                    errorOutput: result.stderr || '',
-                    testsRun,
-                    testsPassed,
-                    testsFailed,
-                    executionTime: result.executionTime,
-                    error: result.exitCode !== 0 ? result.stderr : null
-                }
-            };
-            return { content };
+    run: async (input, context) => {
+        const args = [];
+        if (input.reporter) {
+            args.push('--reporter', input.reporter);
         }
-        catch (error) {
-            logger.error('Mocha test failed', { error });
-            const content = {
-                type: 'application/json',
-                data: {
-                    success: false,
-                    runner: 'mocha',
-                    output: '',
-                    errorOutput: '',
-                    testsRun: 0,
-                    testsPassed: 0,
-                    testsFailed: 0,
-                    executionTime: 0,
-                    error: error instanceof Error ? error.message : String(error)
-                }
-            };
-            return { content };
+        if (input.grep) {
+            args.push('--grep', input.grep);
+        }
+        if (input.timeout) {
+            args.push('--timeout', String(input.timeout));
+        }
+        if (input.recursive) {
+            args.push('--recursive');
         }
+        if (input.testFiles && input.testFiles.length > 0) {
+            args.push(...input.testFiles);
+        }
+        return runTestRunner('mocha', args, input.workingDirectory, context);
     }
-};
-export const vitestTestTool = {
+});
+export const vitestTestTool = defineTool({
     name: 'test_vitest',
-    description: 'Run Vitest tests with comprehensive options',
+    category: TOOL_CATEGORIES.INFRASTRUCTURE,
+    description: 'Run Vitest tests once (not in watch mode). passed is false when any test fails.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -294,99 +240,77 @@ export const vitestTestTool = {
             coverage: {
                 type: 'boolean',
                 default: false,
-                description: 'Generate test coverage report'
-            },
-            watchMode: {
-                type: 'boolean',
-                default: false,
-                description: 'Run tests in watch mode'
+                description: 'Generate a coverage report'
             },
             reporter: {
                 type: 'string',
-                enum: ['default', 'verbose', 'dot', 'json', 'junit', 'html'],
+                enum: ['default', 'verbose', 'dot', 'json', 'tap'],
                 default: 'default',
-                description: 'Test reporter format'
+                description: 'Reporter format'
             },
-            workingDirectory: {
-                type: 'string',
-                description: 'Working directory path (defaults to current directory)'
-            }
+            workingDirectory: workingDirectoryProperty
         }
     },
-    handler: async (args, context) => {
-        try {
-            const vitestArgs = ['--run']; // Force single run (no watch by default)
-            if (args.coverage) {
-                vitestArgs.push('--coverage');
-            }
-            if (args.watchMode) {
-                vitestArgs.pop(); // Remove --run
-                vitestArgs.push('--watch');
-            }
-            if (args.reporter) {
-                vitestArgs.push('--reporter', args.reporter);
-            }
-            if (args.testFiles && args.testFiles.length > 0) {
-                vitestArgs.push(...args.testFiles);
-            }
-            const result = await executeShellCommand('npx', ['vitest', ...vitestArgs], {
-                workingDirectory: args.workingDirectory || process.cwd(),
-                captureOutput: true
-            });
-            // Parse Vitest output for test results
-            let testsRun = 0;
-            let testsPassed = 0;
-            let testsFailed = 0;
-            if (result.stdout) {
-                const testsMatch = result.stdout.match(/Test Files\s+(\d+)\s+passed/);
-                const failMatch = result.stdout.match(/Test Files\s+(\d+)\s+failed/);
-                if (testsMatch)
-                    testsPassed = parseInt(testsMatch[1]);
-                if (failMatch)
-                    testsFailed = parseInt(failMatch[1]);
-                testsRun = testsPassed + testsFailed;
-            }
-            const content = {
-                type: 'application/json',
-                data: {
-                    success: result.exitCode === 0,
-                    runner: 'vitest',
-                    output: result.stdout || '',
-                    errorOutput: result.stderr || '',
-                    testsRun,
-                    testsPassed,
-                    testsFailed,
-                    executionTime: result.executionTime,
-                    coverage: args.coverage ? 'Coverage report generated' : null,
-                    error: result.exitCode !== 0 ? result.stderr : null
-                }
-            };
-            return { content };
+    run: async (input, context) => {
+        // `run` is Vitest's non-watching mode. Without it Vitest watches by
+        // default and the process would never exit.
+        const args = ['run'];
+        if (input.coverage) {
+            args.push('--coverage');
         }
-        catch (error) {
-            logger.error('Vitest test failed', { error });
-            const content = {
-                type: 'application/json',
-                data: {
-                    success: false,
-                    runner: 'vitest',
-                    output: '',
-                    errorOutput: '',
-                    testsRun: 0,
-                    testsPassed: 0,
-                    testsFailed: 0,
-                    executionTime: 0,
-                    coverage: null,
-                    error: error instanceof Error ? error.message : String(error)
-                }
-            };
-            return { content };
+        if (input.reporter) {
+            args.push('--reporter', input.reporter);
+        }
+        if (input.testFiles && input.testFiles.length > 0) {
+            args.push(...input.testFiles);
         }
+        return runTestRunner('vitest', args, input.workingDirectory, context);
     }
-};
-export const testRunnerTool = {
+});
+/**
+ * Read the project's package.json and work out which runner it uses.
+ *
+ * Throws when there is no package.json or no known runner in it — guessing
+ * "jest" for a project that does not use jest produces a confusing failure two
+ * steps later.
+ */
+async function detectFramework(workingDirectory) {
+    const packageJsonPath = path.join(workingDirectory, 'package.json');
+    let raw;
+    try {
+        raw = await fs.readFile(packageJsonPath, 'utf-8');
+    }
+    catch {
+        throw ToolError.notFound(`No package.json in ${workingDirectory}, so the test framework cannot be detected. ` +
+            `Pass framework explicitly, or run this from the project root.`);
+    }
+    let packageJson;
+    try {
+        packageJson = JSON.parse(raw);
+    }
+    catch (parseError) {
+        throw ToolError.executionFailed(`package.json in ${workingDirectory} is not valid JSON: ` +
+            `${parseError instanceof Error ? parseError.message : String(parseError)}`);
+    }
+    const deps = { ...packageJson.dependencies, ...packageJson.devDependencies };
+    if (deps.vitest) {
+        return 'vitest';
+    }
+    if (deps.jest) {
+        return 'jest';
+    }
+    if (deps.mocha) {
+        return 'mocha';
+    }
+    throw ToolError.notFound(`No supported test framework found in ${packageJsonPath}. ` +
+        `Expected one of jest, mocha or vitest in dependencies or devDependencies. ` +
+        `Pass framework explicitly to override.`);
+}
+export const testRunnerTool = defineTool({
     name: 'test_runner',
-    description: 'Universal test runner that detects and runs the appropriate test framework',
+    category: TOOL_CATEGORIES.INFRASTRUCTURE,
+    description: 'Run the project\'s tests, detecting whether it uses Jest, Mocha or Vitest from ' +
+        'package.json. passed is false when any test fails.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -394,7 +318,7 @@ export const testRunnerTool = {
                 type: 'string',
                 enum: ['auto', 'jest', 'mocha', 'vitest'],
                 default: 'auto',
-                description: 'Test framework to use (auto-detects if not specified)'
+                description: 'Test framework. "auto" reads it from package.json.'
             },
             testFiles: {
                 type: 'array',
@@ -404,91 +328,45 @@ export const testRunnerTool = {
             coverage: {
                 type: 'boolean',
                 default: false,
-                description: 'Generate test coverage report'
+                description: 'Generate a coverage report'
             },
-            watchMode: {
-                type: 'boolean',
-                default: false,
-                description: 'Run tests in watch mode'
-            },
-            workingDirectory: {
-                type: 'string',
-                description: 'Working directory path (defaults to current directory)'
-            }
+            workingDirectory: workingDirectoryProperty
         }
     },
-    handler: async (args, context) => {
-        try {
-            let framework = args.framework;
-            // Auto-detect framework if not specified
-            if (framework === 'auto' || !framework) {
-                // Check package.json for test scripts and dependencies
-                const packageJsonResult = await executeShellCommand('cat', ['package.json'], {
-                    workingDirectory: args.workingDirectory || process.cwd(),
-                    captureOutput: true
-                });
-                if (packageJsonResult.exitCode === 0 && packageJsonResult.stdout) {
-                    try {
-                        const packageJson = JSON.parse(packageJsonResult.stdout);
-                        // Check dependencies and devDependencies
-                        const allDeps = {
-                            ...packageJson.dependencies,
-                            ...packageJson.devDependencies
-                        };
-                        if (allDeps.vitest) {
-                            framework = 'vitest';
-                        }
-                        else if (allDeps.jest) {
-                            framework = 'jest';
-                        }
-                        else if (allDeps.mocha) {
-                            framework = 'mocha';
-                        }
-                        else {
-                            framework = 'jest'; // Default fallback
-                        }
-                    }
-                    catch (parseError) {
-                        framework = 'jest'; // Default fallback
-                    }
+    run: async (input, context) => {
+        const workingDirectory = input.workingDirectory || process.cwd();
+        const requested = input.framework ?? 'auto';
+        const detected = requested === 'auto';
+        const framework = detected
+            ? await detectFramework(workingDirectory)
+            : requested;
+        const args = [];
+        switch (framework) {
+            case 'jest':
+                args.push('--no-watchman', '--passWithNoTests');
+                if (input.coverage) {
+                    args.push('--coverage');
                 }
-                else {
-                    framework = 'jest'; // Default fallback
+                break;
+            case 'vitest':
+                args.push('run');
+                if (input.coverage) {
+                    args.push('--coverage');
                 }
-            }
-            // Delegate to the appropriate test tool
-            switch (framework) {
-                case 'jest':
-                    return await jestTestTool.handler(args, context);
-                case 'mocha':
-                    return await mochaTestTool.handler(args, context);
-                case 'vitest':
-                    return await vitestTestTool.handler(args, context);
-                default:
-                    throw new Error(`Unknown test framework: ${framework}`);
-            }
-        }
-        catch (error) {
-            logger.error('Universal test runner failed', { error });
-            const content = {
-                type: 'application/json',
-                data: {
-                    success: false,
-                    runner: 'unknown',
-                    output: '',
-                    errorOutput: '',
-                    testsRun: 0,
-                    testsPassed: 0,
-                    testsFailed: 0,
-                    executionTime: 0,
-                    error: error instanceof Error ? error.message : String(error)
+                break;
+            case 'mocha':
+                if (input.coverage) {
+                    throw ToolError.notImplemented('Mocha does not produce coverage on its own — run it under nyc or c8 instead.');
                 }
-            };
-            return { content };
+                break;
+        }
+        if (input.testFiles && input.testFiles.length > 0) {
+            args.push(...input.testFiles);
         }
+        const result = await runTestRunner(framework, args, workingDirectory, context);
+        return { ...result, detected };
     }
-};
-// Export all test tools
+});
 export const testTools = [
     jestTestTool,
     mochaTestTool,