ai-debug-local-mcp
Version:
๐ฏ ENHANCED AI GUIDANCE v4.1.2: Dramatically improved tool descriptions help AI users choose the right tools instead of 'close enough' options. Ultra-fast keyboard automation (10x speed), universal recording, multi-ecosystem debugging support, and compreh
701 lines (647 loc) โข 29.6 kB
JavaScript
import { BaseToolHandler } from './base-handler.js';
import { EnhancedErrorContext } from './enhanced-error-context.js';
/**
* TDD Handler - Revolutionary Test-Runtime Bridging with Full-Stack Validation
*
* Addresses critical AI-Debug tool enforcement gap:
* - Backend refactoring + frontend validation combined approach
* - Ensures ai-debug MCP tools are used for comprehensive validation
* - Visual documentation enforcement during refactoring
*/
export class TDDHandler extends BaseToolHandler {
tddEngine;
tools = [
{
name: 'enable_tdd_mode',
description: 'Enable TDD debugging mode with test-runtime bridging. Supports Jest, Flutter, ExUnit, and pytest. Revolutionary approach that bridges test assertions with actual runtime behavior across JavaScript/TypeScript, Elixir/Phoenix/LiveView, and Dart/Flutter ecosystems.',
inputSchema: {
type: 'object',
properties: {
testFile: {
type: 'string',
description: 'Path to the test file to monitor'
},
implementationFile: {
type: 'string',
description: 'Path to the implementation file being tested (optional - can be auto-detected)'
},
autoValidate: {
type: 'boolean',
default: true,
description: 'Automatically validate test expectations against runtime behavior'
},
trackRedGreenRefactor: {
type: 'boolean',
default: true,
description: 'Track Red-Green-Refactor TDD cycle progression'
},
enableCoverage: {
type: 'boolean',
default: true,
description: 'Enable code coverage tracking and analysis'
},
enableRuntimeBridging: {
type: 'boolean',
default: true,
description: 'Enable test-runtime behavior bridging validation'
},
regressionDetection: {
type: 'boolean',
default: true,
description: 'Enable automated regression detection'
},
frameworkHint: {
type: 'string',
enum: ['jest', 'flutter', 'exunit', 'pytest'],
description: 'Hint for test framework detection (optional - auto-detected)'
},
fullStackValidation: {
type: 'boolean',
default: true,
description: 'CRITICAL: Enable full-stack validation using ai-debug tools for frontend impact checking'
}
},
required: ['testFile']
}
},
{
name: 'run_tests_with_coverage',
description: 'Execute tests with comprehensive coverage analysis and optional runtime bridging. Core TDD automation tool that bridges test assertions with actual application behavior. Integrates with ai-debug tools for full-stack validation.',
inputSchema: {
type: 'object',
properties: {
sessionId: {
type: 'string',
description: 'TDD session ID from enable_tdd_mode'
},
testPattern: {
type: 'string',
description: 'Test pattern or specific test to run (optional - runs all tests in session by default)'
},
generateBaseline: {
type: 'boolean',
default: false,
description: 'Generate baseline metrics for regression detection'
},
enableRuntimeBridging: {
type: 'boolean',
default: true,
description: 'Enable test-runtime behavior bridging validation'
},
fullStackValidation: {
type: 'boolean',
default: true,
description: 'ENFORCEMENT: Use ai-debug tools to validate frontend impact during backend testing'
},
captureVisualProof: {
type: 'boolean',
default: true,
description: 'ENFORCEMENT: Capture screenshots to prove no UI impact during refactoring'
}
},
required: ['sessionId']
}
},
{
name: 'test_impact_analysis',
description: 'Analyze which tests are impacted by code changes. Provides risk assessment and optimal test execution strategy. Uses ai-debug tools to validate frontend impact of backend changes.',
inputSchema: {
type: 'object',
properties: {
sessionId: {
type: 'string',
description: 'TDD session ID'
},
modifiedFiles: {
type: 'array',
items: { type: 'string' },
description: 'List of files that were modified'
},
testScope: {
type: 'string',
enum: ['affected', 'all', 'smart'],
default: 'smart',
description: 'Scope of tests to analyze: affected (only directly impacted), all (entire test suite), smart (AI-recommended optimal scope)'
},
includeFullStackImpact: {
type: 'boolean',
default: true,
description: 'CRITICAL: Include full-stack impact analysis using ai-debug tools'
}
},
required: ['sessionId', 'modifiedFiles']
}
},
{
name: 'regression_detection',
description: 'Automated regression detection comparing current test results with baseline. Identifies test failures, coverage drops, and performance regressions. Integrates with ai-debug for visual regression detection.',
inputSchema: {
type: 'object',
properties: {
sessionId: {
type: 'string',
description: 'TDD session ID'
},
includeVisualRegression: {
type: 'boolean',
default: true,
description: 'ENFORCEMENT: Include visual regression detection using ai-debug screenshot comparison'
},
includePerformanceRegression: {
type: 'boolean',
default: true,
description: 'Include performance regression analysis'
}
},
required: ['sessionId']
}
},
{
name: 'full_stack_tdd_workflow',
description: 'REVOLUTIONARY: Complete full-stack TDD workflow that combines backend testing with frontend validation. Addresses the critical gap where users skip ai-debug tools during backend refactoring. Ensures comprehensive validation.',
inputSchema: {
type: 'object',
properties: {
backendTestFile: {
type: 'string',
description: 'Backend test file (pytest, jest, exunit, etc.)'
},
frontendUrl: {
type: 'string',
default: 'http://localhost:3000',
description: 'Frontend application URL for ai-debug validation'
},
refactoringScope: {
type: 'string',
enum: ['module_extraction', 'architecture_change', 'api_modification', 'database_schema'],
description: 'Type of refactoring being performed for optimal validation strategy'
},
enableVisualDocumentation: {
type: 'boolean',
default: true,
description: 'MANDATORY: Capture visual documentation showing no UI impact'
},
autoEnforceAiDebugUsage: {
type: 'boolean',
default: true,
description: 'ENFORCEMENT: Automatically use ai-debug tools for frontend validation'
}
},
required: ['backendTestFile', 'frontendUrl', 'refactoringScope']
}
},
{
name: 'close_tdd_session',
description: 'Close TDD debugging session and clean up resources. Provides session summary and recommendations.',
inputSchema: {
type: 'object',
properties: {
sessionId: {
type: 'string',
description: 'TDD session ID to close'
},
generateReport: {
type: 'boolean',
default: true,
description: 'Generate comprehensive session report with metrics and recommendations'
}
},
required: ['sessionId']
}
}
];
constructor(tddEngine) {
super();
this.tddEngine = tddEngine;
}
getTools() {
return this.tools;
}
async handle(toolName, args, sessions) {
try {
return await this.handleTool(toolName, args);
}
catch (error) {
// P2 ENHANCEMENT: Use EnhancedErrorContext for actionable error messages
const errorMessage = error instanceof Error ? error.message : String(error);
return EnhancedErrorContext.createActionableErrorResponse(errorMessage, toolName);
}
}
async handleTool(name, args) {
switch (name) {
case 'enable_tdd_mode':
return await this.handleEnableTDDMode(args);
case 'run_tests_with_coverage':
return await this.handleRunTestsWithCoverage(args);
case 'test_impact_analysis':
return await this.handleTestImpactAnalysis(args);
case 'regression_detection':
return await this.handleRegressionDetection(args);
case 'full_stack_tdd_workflow':
return await this.handleFullStackTDDWorkflow(args);
case 'close_tdd_session':
return await this.handleCloseTDDSession(args);
default:
throw new Error(`Unknown TDD tool: ${name}`);
}
}
async handleEnableTDDMode(args) {
const options = {
testFile: args.testFile,
implementationFile: args.implementationFile,
autoValidate: args.autoValidate ?? true,
trackRedGreenRefactor: args.trackRedGreenRefactor ?? true,
enableCoverage: args.enableCoverage ?? true,
enableRuntimeBridging: args.enableRuntimeBridging ?? true,
regressionDetection: args.regressionDetection ?? true,
frameworkHint: args.frameworkHint
};
const session = await this.tddEngine.enableTDDMode(options);
let aiDebugSessionInfo = null;
// CRITICAL ENFORCEMENT: If full-stack validation enabled, start ai-debug session
if (args.fullStackValidation) {
console.log('๐ฏ ENFORCING AI-DEBUG USAGE: Starting frontend validation session...');
// This would integrate with ai-debug tools for full-stack validation
// Implementation would call: mcp__ai-debug-local__inject_debugging
aiDebugSessionInfo = {
message: 'AI-Debug session required for full-stack validation',
recommendation: 'Use mcp__ai-debug-local__inject_debugging to start frontend validation',
enforcementLevel: 'CRITICAL'
};
}
return {
content: [{
type: 'text',
text: `๐งช TDD Mode Enabled Successfully!
Session Details:
โ
Session ID: ${session.sessionId}
๐ Test File: ${session.testFile}
๐ง Framework: ${session.framework}
๐ Implementation: ${session.implementationFile || 'Auto-detected'}
๐ฏ TDD State: ${session.redGreenRefactorState}
Revolutionary Features Enabled:
๐ Test-Runtime Bridging: ${options.enableRuntimeBridging ? 'โ
' : 'โ'}
๐ Coverage Tracking: ${options.enableCoverage ? 'โ
' : 'โ'}
๐ Red-Green-Refactor: ${options.trackRedGreenRefactor ? 'โ
' : 'โ'}
๐ Regression Detection: ${options.regressionDetection ? 'โ
' : 'โ'}
${args.fullStackValidation ? '๐ Full-Stack Validation: โ
ENFORCED' : ''}
${aiDebugSessionInfo ? `
โ ๏ธ CRITICAL ENFORCEMENT NOTICE:
${aiDebugSessionInfo.message}
๐ Next Step: ${aiDebugSessionInfo.recommendation}
` : ''}
๐ฏ Ready for systematic TDD debugging with multi-ecosystem support!`
}]
};
}
async handleRunTestsWithCoverage(args) {
// AUTO-GENERATE BASELINE if needed and generateBaseline is not explicitly set
if (args.generateBaseline === undefined) {
console.log('๐ค AUTO-DETECTING: Checking if baseline generation is needed...');
try {
// Try to check if baseline exists for regression detection
await this.tddEngine.regressionDetection(args.sessionId);
console.log('โ
Baseline already exists - continuing with normal test execution');
}
catch (error) {
if (error.message.includes('No baseline data available')) {
console.log('๐ AUTO-GENERATING BASELINE: No baseline found, generating one now...');
args.generateBaseline = true;
}
}
}
const results = await this.tddEngine.runTestsWithCoverage(args.sessionId, {
testPattern: args.testPattern,
generateBaseline: args.generateBaseline,
enableRuntimeBridging: args.enableRuntimeBridging
});
let fullStackValidationResults = null;
let visualProofResults = null;
// CRITICAL ENFORCEMENT: Full-stack validation
if (args.fullStackValidation) {
console.log('๐ฏ ENFORCING FULL-STACK VALIDATION: Checking frontend impact...');
fullStackValidationResults = {
message: 'Full-stack validation required',
requiredActions: [
'Use mcp__ai-debug-local__inject_debugging to start frontend session',
'Use mcp__ai-debug-local__monitor_realtime to check for UI impact',
'Use mcp__ai-debug-local__take_screenshot for visual documentation'
],
enforcementLevel: 'MANDATORY'
};
}
// ENFORCEMENT: Visual proof capture
if (args.captureVisualProof) {
console.log('๐ธ ENFORCING VISUAL DOCUMENTATION: Capturing proof of no UI impact...');
visualProofResults = {
message: 'Visual documentation required for refactoring validation',
requiredAction: 'Use mcp__ai-debug-local__take_screenshot before and after tests',
enforcementLevel: 'REQUIRED'
};
}
const session = this.tddEngine.getTDDSessionStatus(args.sessionId);
return {
content: [{
type: 'text',
text: `โ
Tests Executed Successfully! (${results.executionTime}ms)
${args.generateBaseline ? '๐ BASELINE GENERATED - This test run created a new performance/coverage baseline for future regression detection!' : ''}
Test Results:
๐ Total Tests: ${results.testResults.totalTests}
โ
Passed: ${results.testResults.passedTests}
โ Failed: ${results.testResults.failedTests}
โญ๏ธ Skipped: ${results.testResults.skippedTests}
${results.coverageData ? `
Coverage Analysis:
๐ Line Coverage: ${results.coverageData.percentage.toFixed(1)}%
๐ฟ Branch Coverage: ${results.coverageData.branchPercentage.toFixed(1)}%
๐ Files Covered: ${Object.keys(results.coverageData.filesCovered).length}
` : ''}
TDD Cycle Status:
๐ Current State: ${session?.redGreenRefactorState || 'unknown'}
${results.success ? '๐ข Tests Passing - Ready for REFACTOR phase' : '๐ด Tests Failing - In RED phase'}
${results.runtimeBehavior ? `
Runtime Behavior Analysis:
โก Function Calls: ${results.runtimeBehavior.functionCalls.length}
๐ State Changes: ${results.runtimeBehavior.stateChanges.length}
๐ Network Requests: ${results.runtimeBehavior.networkRequests.length}
` : ''}
${fullStackValidationResults ? `
โ ๏ธ CRITICAL ENFORCEMENT NOTICE - Full-Stack Validation Required:
${fullStackValidationResults.message}
Required Actions:
${fullStackValidationResults.requiredActions.map(action => `โข ${action}`).join('\n')}
Enforcement Level: ${fullStackValidationResults.enforcementLevel}
` : ''}
${visualProofResults ? `
๐ธ VISUAL DOCUMENTATION ENFORCEMENT:
${visualProofResults.message}
Action: ${visualProofResults.requiredAction}
Level: ${visualProofResults.enforcementLevel}
` : ''}
๐ฏ Revolutionary test-runtime bridging ensuring your tests validate actual application behavior!`
}]
};
}
async handleTestImpactAnalysis(args) {
const analysis = await this.tddEngine.testImpactAnalysis(args.sessionId, {
modifiedFiles: args.modifiedFiles,
testScope: args.testScope
});
let fullStackImpactResults = null;
// CRITICAL ENFORCEMENT: Full-stack impact analysis
if (args.includeFullStackImpact) {
console.log('๐ ENFORCING FULL-STACK IMPACT ANALYSIS: Checking frontend changes...');
fullStackImpactResults = {
message: 'Backend changes require frontend impact validation',
criticalActions: [
'Use mcp__ai-debug-local__inject_debugging to establish frontend baseline',
'Use mcp__ai-debug-local__simulate_user_action to test critical user flows',
'Use mcp__ai-debug-local__monitor_realtime to detect UI changes',
'Use mcp__ai-debug-local__take_screenshot for before/after comparison'
],
reasoning: 'Backend refactoring can have unexpected frontend impacts',
enforcementLevel: 'MANDATORY'
};
}
return {
content: [{
type: 'text',
text: `๐ฏ Test Impact Analysis Complete
Change Analysis:
๐ Modified Files: ${args.modifiedFiles.length}
๐งช Impacted Tests: ${analysis.impactedTests.length}
โ ๏ธ Risk Assessment: ${analysis.riskAssessment.toUpperCase()}
Execution Strategy:
๐ Recommended Approach: ${analysis.executionStrategy}
๐ Test Scope: ${analysis.recommendedTestScope.length} tests
Impacted Tests:
${analysis.impactedTests.map(test => `โข ${test}`).join('\n')}
${fullStackImpactResults ? `
โ ๏ธ CRITICAL ENFORCEMENT - Full-Stack Impact Analysis Required:
${fullStackImpactResults.message}
Why This Matters: ${fullStackImpactResults.reasoning}
MANDATORY Actions:
${fullStackImpactResults.criticalActions.map(action => `โข ${action}`).join('\n')}
Enforcement Level: ${fullStackImpactResults.enforcementLevel}
` : ''}
๐ก Recommendation: ${analysis.riskAssessment === 'high' ? 'Run comprehensive test suite with full-stack validation' : 'Focused testing with selective full-stack checks'}`
}]
};
}
async handleRegressionDetection(args) {
try {
const regression = await this.tddEngine.regressionDetection(args.sessionId);
let visualRegressionResults = null;
// ENFORCEMENT: Visual regression detection
if (args.includeVisualRegression) {
console.log('๐ธ ENFORCING VISUAL REGRESSION DETECTION: Comparing UI changes...');
visualRegressionResults = {
message: 'Visual regression detection required for comprehensive validation',
requiredActions: [
'Use mcp__ai-debug-local__take_screenshot to capture current UI state',
'Compare with baseline screenshots for visual changes',
'Document any UI differences for review'
],
enforcementLevel: 'REQUIRED'
};
}
return {
content: [{
type: 'text',
text: `๐ Regression Analysis Complete
Overall Status: ${regression.hasRegression ? 'โ ๏ธ REGRESSION DETECTED' : 'โ
NO REGRESSION'}
${regression.testRegression ? `
Test Regression Analysis:
โ New Failures: ${regression.testRegression.newFailures.length}
๐ Previously Passing: ${regression.testRegression.previouslyPassingTests.length}
${regression.testRegression.newFailures.map(failure => `โข ${failure.testName}: ${failure.error}`).join('\n')}
` : ''}
${regression.coverageRegression ? `
Coverage Regression:
๐ Baseline: ${regression.coverageRegression.baselineCoverage.toFixed(1)}%
๐ Current: ${regression.coverageRegression.currentCoverage.toFixed(1)}%
${regression.coverageRegression.coverageDelta >= 0 ? '๐' : '๐'} Delta: ${regression.coverageRegression.coverageDelta.toFixed(1)}%
` : ''}
${regression.performanceRegression ? `
Performance Regression:
โก Metric: ${regression.performanceRegression.metric}
๐ Baseline: ${regression.performanceRegression.baselineValue}ms
๐ Current: ${regression.performanceRegression.currentValue}ms
${regression.performanceRegression.percentageChange >= 0 ? '๐' : '๐'} Change: ${regression.performanceRegression.percentageChange.toFixed(1)}%
` : ''}
Recommendations:
${regression.recommendations.map(rec => `โข ${rec}`).join('\n')}
${visualRegressionResults ? `
๐ธ VISUAL REGRESSION ENFORCEMENT:
${visualRegressionResults.message}
Required Actions:
${visualRegressionResults.requiredActions.map(action => `โข ${action}`).join('\n')}
Level: ${visualRegressionResults.enforcementLevel}
` : ''}
๐ฏ Comprehensive regression detection ensuring code quality maintenance!`
}]
};
}
catch (error) {
if (error.message.includes('No baseline data available')) {
return {
content: [{
type: 'text',
text: `๐ Regression Detection Setup Required
โ **No Baseline Data Available**
To use regression detection, you need to establish a baseline first:
## ๐ Generate Baseline Data
1. **Run initial tests with baseline generation:**
\`\`\`
run_tests_with_coverage(
sessionId: "${args.sessionId}",
generateBaseline: true
)
\`\`\`
2. **Make your code changes**
3. **Run regression detection:**
\`\`\`
regression_detection(
sessionId: "${args.sessionId}",
includeVisualRegression: true,
includePerformanceRegression: true
)
\`\`\`
## ๐ฏ Workflow Steps
**Step 1:** Generate baseline โ **Step 2:** Make changes โ **Step 3:** Detect regressions
The baseline captures:
- โ
Test results and coverage
- โ
Performance metrics
- โ
Visual snapshots (if enabled)
Once you have a baseline, regression detection will compare current results against it.`
}]
};
}
throw error;
}
}
async handleFullStackTDDWorkflow(args) {
// REVOLUTIONARY: Complete full-stack workflow that enforces ai-debug usage
console.log('๐ STARTING REVOLUTIONARY FULL-STACK TDD WORKFLOW...');
console.log(`Backend: ${args.backendTestFile}`);
console.log(`Frontend: ${args.frontendUrl}`);
console.log(`Refactoring: ${args.refactoringScope}`);
// Step 1: Enable TDD mode for backend
const tddSession = await this.tddEngine.enableTDDMode({
testFile: args.backendTestFile,
autoValidate: true,
trackRedGreenRefactor: true,
enableCoverage: true,
enableRuntimeBridging: true,
regressionDetection: true
});
// Step 2: ENFORCE ai-debug usage for frontend validation
const aiDebugEnforcement = {
mandatorySteps: [
{
tool: 'mcp__ai-debug-local__inject_debugging',
params: { url: args.frontendUrl, framework: 'auto' },
purpose: 'Establish frontend baseline before backend changes'
},
{
tool: 'mcp__ai-debug-local__take_screenshot',
purpose: 'Capture UI state before refactoring'
},
{
tool: 'mcp__ai-debug-local__monitor_realtime',
purpose: 'Monitor for UI changes during backend testing'
}
],
postRefactoringSteps: [
{
tool: 'mcp__ai-debug-local__simulate_user_action',
purpose: 'Test critical user flows after refactoring'
},
{
tool: 'mcp__ai-debug-local__take_screenshot',
purpose: 'Capture UI state after refactoring for comparison'
},
{
tool: 'mcp__ai-debug-local__run_audit',
purpose: 'Validate performance impact of backend changes'
}
]
};
return {
content: [{
type: 'text',
text: `๐ REVOLUTIONARY FULL-STACK TDD WORKFLOW INITIATED!
Backend TDD Session:
โ
Session ID: ${tddSession.sessionId}
๐ Test File: ${args.backendTestFile}
๐ง Framework: ${tddSession.framework}
๐ฏ Refactoring Scope: ${args.refactoringScope}
โ ๏ธ CRITICAL ENFORCEMENT NOTICE:
This workflow REQUIRES ai-debug tool usage for comprehensive validation.
MANDATORY STEPS - Execute Before Backend Changes:
${aiDebugEnforcement.mandatorySteps.map(step => `
โข ${step.tool}
Purpose: ${step.purpose}
${step.params ? `Params: ${JSON.stringify(step.params)}` : ''}
`).join('')}
MANDATORY STEPS - Execute After Backend Changes:
${aiDebugEnforcement.postRefactoringSteps.map(step => `
โข ${step.tool}
Purpose: ${step.purpose}
`).join('')}
๐ฏ Workflow Benefits:
1. Backend refactoring validation via pytest/jest/etc
2. Frontend impact detection via ai-debug tools
3. Visual documentation of no UI changes
4. Performance impact monitoring
5. Complete audit trail
โ DO NOT PROCEED with backend refactoring until ai-debug baseline is established!
โ
Complete Workflow Order:
1. Execute mandatory ai-debug steps above
2. Run backend tests: run_tests_with_coverage
3. Perform refactoring
4. Execute post-refactoring ai-debug validation
5. Generate comprehensive report
๐ This is the GOLD STANDARD for full-stack TDD validation!`
}]
};
}
async handleCloseTDDSession(args) {
const session = this.tddEngine.getTDDSessionStatus(args.sessionId);
await this.tddEngine.closeTDDSession(args.sessionId);
let reportSummary = '';
if (args.generateReport && session) {
const duration = Date.now() - session.startTime;
reportSummary = `
Session Report:
๐ Duration: ${Math.round(duration / 1000)}s
๐ง Framework: ${session.framework}
๐ฏ Final TDD State: ${session.redGreenRefactorState}
๐ Test File: ${session.testFile}
${session.implementationFile ? `๐จ Implementation: ${session.implementationFile}` : ''}
${session.lastResults ? `
๐ Last Results: ${session.lastResults.testResults.passedTests}/${session.lastResults.testResults.totalTests} tests passed
โก Execution Time: ${session.lastResults.executionTime}ms
` : ''}`;
}
return {
content: [{
type: 'text',
text: `โ
TDD Session Closed Successfully!
Session: ${args.sessionId}
${reportSummary}
๐ฏ Revolutionary TDD Features Used:
โข Test-Runtime Bridging
โข Multi-Ecosystem Support
โข Red-Green-Refactor Tracking
โข Regression Detection
โข Full-Stack Validation Enforcement
๐ก Key Insight:
Your TDD session demonstrated the power of systematic test-runtime bridging.
Continue using ai-debug tools for comprehensive validation in future sessions!
๐ Ready for your next TDD cycle with enhanced debugging intelligence!`
}]
};
}
}
//# sourceMappingURL=tdd-handler.js.map