mcp-adr-analysis-server
Version:
MCP server for analyzing Architectural Decision Records and project architecture
1,072 lines (1,034 loc) • 85.1 kB
JavaScript
/**
* MCP Tool for Bootstrap Validation Loop with ADR Learning
*
* Implements a self-learning architecture validation system:
* 1. Generate bootstrap scripts from ADRs
* 2. Execute scripts in real environment with monitoring
* 3. Capture learnings and failures
* 4. Mask sensitive information
* 5. Update ADRs with deployment experience
* 6. Re-generate improved scripts
* 7. Validate until success
*
* This creates a bidirectional feedback loop where ADRs evolve
* based on real-world deployment experience.
*/
import { promises as fs } from 'fs';
import { exec } from 'node:child_process';
import { promisify } from 'util';
import * as path from 'path';
import { createHash } from 'crypto';
import { McpAdrError } from '../types/index.js';
import { EnhancedLogger } from '../utils/enhanced-logging.js';
import { ResearchOrchestrator } from '../utils/research-orchestrator.js';
import { MemoryEntityManager } from '../utils/memory-entity-manager.js';
import { DynamicDeploymentIntelligence, } from '../utils/dynamic-deployment-intelligence.js';
import generateAdrBootstrapScripts from './adr-bootstrap-validation-tool.js';
// NEW: Validated Patterns Integration
import { detectPlatforms } from '../utils/platform-detector.js';
import { getPattern } from '../utils/validated-pattern-definitions.js';
import { generatePatternResearchReport } from '../utils/pattern-research-utility.js';
// NEW: Tool Context Documentation System
import { ToolContextManager } from '../utils/context-document-manager.js';
// NEW: Hybrid DAG Architecture
import { DAGExecutor } from '../utils/dag-executor.js';
import { PatternToDAGConverter } from '../utils/pattern-to-dag-converter.js';
import { PatternContributionHelper } from '../utils/pattern-contribution-helper.js';
import { PatternLoader } from '../utils/pattern-loader.js';
// NEW: SystemCard for Resource Tracking
import { SystemCardManager } from '../utils/system-card-manager.js';
const execAsync = promisify(exec);
/**
* Bootstrap Validation Loop orchestrator
* Supports dependency injection for improved testability
* @see Issue #310 - Dependency injection for improved testability
*/
export class BootstrapValidationLoop {
logger;
projectPath;
adrDirectory;
researchOrchestrator;
memoryManager;
deploymentIntelligence;
executionHistory = [];
maxIterations;
currentIteration = 0;
deploymentPlan = null;
// NEW: Validated Patterns fields
platformDetection = null;
validatedPattern = null;
patternResearchReport = null;
// NEW: Tool Context Documentation
contextManager;
// NEW: Hybrid DAG Architecture
dagExecutor;
patternLoader;
patternConverter;
contributionHelper;
// NEW: SystemCard Resource Tracking
systemCardManager;
/**
* Constructor with optional dependency injection
* @param projectPath - Path to the project
* @param adrDirectory - Path to ADR directory
* @param maxIterations - Maximum validation iterations
* @param deps - Optional dependencies for testing (defaults create real instances)
*/
constructor(projectPath, adrDirectory, maxIterations = 5, deps = {}) {
this.logger = deps.logger ?? new EnhancedLogger();
this.projectPath = projectPath;
this.adrDirectory = adrDirectory;
this.maxIterations = maxIterations;
this.researchOrchestrator =
deps.researchOrchestrator ?? new ResearchOrchestrator(projectPath, adrDirectory);
this.memoryManager = deps.memoryManager ?? new MemoryEntityManager();
this.deploymentIntelligence = new DynamicDeploymentIntelligence(projectPath, adrDirectory);
this.contextManager = new ToolContextManager(projectPath);
// Initialize SystemCard for resource tracking (must be before DAGExecutor)
this.systemCardManager = new SystemCardManager(projectPath);
// Initialize DAG architecture components
this.dagExecutor = new DAGExecutor(5, this.systemCardManager); // Max 5 parallel tasks, with resource tracking
this.patternLoader = new PatternLoader();
this.patternConverter = new PatternToDAGConverter();
this.contributionHelper = new PatternContributionHelper();
}
/**
* Initialize the validation loop
*/
async initialize() {
await this.memoryManager.initialize();
await this.contextManager.initialize();
this.logger.info('Bootstrap Validation Loop initialized', 'BootstrapValidationLoop', {
projectPath: this.projectPath,
adrDirectory: this.adrDirectory,
maxIterations: this.maxIterations,
});
}
/**
* Execute the complete validation loop
*/
async executeLoop(args) {
const { targetEnvironment, autoFix, captureEnvironmentSnapshot, updateAdrsWithLearnings } = args;
this.logger.info('Starting Bootstrap Validation Loop', 'BootstrapValidationLoop', {
targetEnvironment,
autoFix,
maxIterations: this.maxIterations,
});
// STEP 0: Detect platform using Validated Patterns framework
this.logger.info('🔍 Detecting platform type using Validated Patterns...', 'BootstrapValidationLoop');
this.platformDetection = await detectPlatforms(this.projectPath);
this.logger.info(`📋 Platform detection complete (confidence: ${(this.platformDetection.confidence * 100).toFixed(0)}%)`, 'BootstrapValidationLoop', {
primaryPlatform: this.platformDetection.primaryPlatform,
detectedPlatforms: this.platformDetection.detectedPlatforms.map(p => p.type),
evidence: this.platformDetection.evidence.length,
});
// STEP 0.1: Get validated pattern for detected platform
if (this.platformDetection.primaryPlatform) {
this.validatedPattern = getPattern(this.platformDetection.primaryPlatform);
if (this.validatedPattern) {
this.logger.info(`✅ Loaded validated pattern: ${this.validatedPattern.name}`, 'BootstrapValidationLoop', {
version: this.validatedPattern.version,
lastUpdated: this.validatedPattern.metadata.lastUpdated,
authoritativeSources: this.validatedPattern.authoritativeSources.length,
requiredSources: this.validatedPattern.authoritativeSources.filter(s => s.requiredForDeployment).length,
});
// STEP 0.2: Generate research report for authoritative sources
this.patternResearchReport = generatePatternResearchReport(this.platformDetection.primaryPlatform);
this.logger.info('📚 Generated research report with authoritative source instructions', 'BootstrapValidationLoop');
this.logger.info(`⚠️ IMPORTANT: LLM should query ${this.validatedPattern.authoritativeSources.filter(s => s.requiredForDeployment).length} REQUIRED authoritative sources before deployment`, 'BootstrapValidationLoop');
// Log the research report for LLM to see
this.logger.info('📖 Research Report:\n' + this.patternResearchReport, 'BootstrapValidationLoop');
}
else {
this.logger.warn(`No validated pattern found for ${this.platformDetection.primaryPlatform}, falling back to dynamic intelligence`, 'BootstrapValidationLoop');
}
}
// STEP 0.3: Generate AI-powered deployment plan (fallback or hybrid approach)
this.logger.info('🤖 Generating dynamic deployment plan with AI + research...', 'BootstrapValidationLoop');
this.deploymentPlan = await this.deploymentIntelligence.generateDeploymentPlan();
this.logger.info(`📊 Deployment plan generated (confidence: ${this.deploymentPlan.confidence})`, 'BootstrapValidationLoop', {
platforms: this.deploymentPlan.detectedPlatforms,
recommended: this.deploymentPlan.recommendedPlatform,
source: this.deploymentPlan.source,
requiredFiles: this.deploymentPlan.requiredFiles.length,
});
// STEP 0.5: Create Bootstrap ADR for human review
const bootstrapAdrPath = await this.createBootstrapAdr(this.deploymentPlan);
this.logger.info(`📝 Bootstrap ADR created: ${bootstrapAdrPath}`, 'BootstrapValidationLoop');
// STEP 0.6: Save context document for future sessions
const contextDocumentPath = await this.saveBootstrapContext(this.platformDetection, this.validatedPattern, this.deploymentPlan, bootstrapAdrPath);
this.logger.info(`📄 Context document saved: ${contextDocumentPath}`, 'BootstrapValidationLoop');
this.logger.info('⏸️ WAITING FOR HUMAN APPROVAL - Review the bootstrap ADR before proceeding', 'BootstrapValidationLoop');
// ═══════════════════════════════════════════════════════════════════
// INFRASTRUCTURE LAYER (Hybrid DAG Architecture)
// ═══════════════════════════════════════════════════════════════════
// Execute infrastructure DAG before application deployment iterations
// This runs ONCE and sets up the platform infrastructure
this.logger.info('🏗️ Starting Infrastructure Layer (DAG-based execution)...', 'BootstrapValidationLoop');
const infrastructureResult = await this.executeInfrastructureDAG(this.platformDetection);
if (!infrastructureResult.success) {
const failedTasksList = infrastructureResult.failedTasks.join(', ');
this.logger.error(`❌ Infrastructure Layer failed: ${infrastructureResult.failedTasks.length} tasks failed`, 'BootstrapValidationLoop', undefined, {
failedTasks: infrastructureResult.failedTasks,
skippedTasks: infrastructureResult.skippedTasks,
});
// Infrastructure failure is critical - cannot proceed to application layer
throw new McpAdrError(`Infrastructure deployment failed. Failed tasks: ${failedTasksList}`, 'INFRASTRUCTURE_DEPLOYMENT_ERROR');
}
this.logger.info(`✅ Infrastructure Layer complete (${infrastructureResult.duration}ms)`, 'BootstrapValidationLoop', {
executedTasks: infrastructureResult.executedTasks.length,
duration: infrastructureResult.duration,
});
// ═══════════════════════════════════════════════════════════════════
// APPLICATION LAYER (Phase-based iteration with auto-fix)
// ═══════════════════════════════════════════════════════════════════
this.logger.info('🚀 Starting Application Layer (iterative deployment with auto-fix)...', 'BootstrapValidationLoop');
let success = false;
let finalResult = null;
const adrUpdates = [];
for (let i = 0; i < this.maxIterations; i++) {
this.currentIteration = i + 1;
this.logger.info(`Iteration ${this.currentIteration}/${this.maxIterations}`, 'BootstrapValidationLoop');
// Step 1: Generate bootstrap scripts from current ADRs
const scriptsGenerated = await this.generateBootstrapScripts();
if (!scriptsGenerated) {
throw new McpAdrError('Failed to generate bootstrap scripts', 'SCRIPT_GENERATION_ERROR');
}
// Step 1.5: Detect and handle missing files
this.logger.info('Detecting missing files referenced in ADRs...', 'BootstrapValidationLoop');
const missingFiles = await this.detectMissingFiles();
if (missingFiles.length > 0) {
this.logger.warn(`Found ${missingFiles.length} missing files`, 'BootstrapValidationLoop', {
critical: missingFiles.filter(f => f.severity === 'critical').length,
errors: missingFiles.filter(f => f.severity === 'error').length,
});
// Handle missing files (create templates, add prerequisites)
const missingFileLearnings = await this.handleMissingFiles(missingFiles);
// Log missing file handling results
this.logger.info(`Handled ${missingFileLearnings.length} missing file issues`, 'BootstrapValidationLoop', {
created: missingFileLearnings.filter(l => l.type === 'success').length,
prerequisites: missingFileLearnings.filter(l => l.type === 'prerequisite').length,
});
}
// Step 2: Execute bootstrap.sh with monitoring
const executionResult = await this.executeBootstrapWithMonitoring(targetEnvironment, captureEnvironmentSnapshot);
this.executionHistory.push(executionResult);
// Step 3: Run validation script and capture results
const validationResult = await this.executeValidationScript(executionResult.executionId);
executionResult.validationResults = validationResult.validationResults;
// Step 4: Analyze results and extract learnings
const learnings = await this.extractLearnings(executionResult, validationResult);
executionResult.learnings = learnings;
// Step 5: Store execution in memory system
await this.storeExecutionInMemory(executionResult);
// Check if validation passed
if (validationResult.allPassed) {
this.logger.info('✅ Validation passed!', 'BootstrapValidationLoop');
success = true;
finalResult = executionResult;
// Update ADRs with successful learnings
if (updateAdrsWithLearnings) {
const updates = await this.generateAdrUpdates(learnings, 'success');
adrUpdates.push(...updates);
}
break;
}
// Step 6: If auto-fix enabled, update scripts based on learnings
if (autoFix) {
this.logger.info('Auto-fixing bootstrap scripts based on failures', 'BootstrapValidationLoop');
const scriptsUpdated = await this.updateBootstrapScriptsFromLearnings(learnings, executionResult);
if (!scriptsUpdated) {
this.logger.warn('Failed to auto-fix scripts, stopping loop', 'BootstrapValidationLoop');
finalResult = executionResult;
break;
}
}
else {
// No auto-fix, stop after first iteration
finalResult = executionResult;
break;
}
finalResult = executionResult;
}
// Generate final ADR update proposals
if (updateAdrsWithLearnings && finalResult) {
const updates = await this.generateAdrUpdates(finalResult.learnings, success ? 'success' : 'failure');
adrUpdates.push(...updates);
}
// Ensure finalResult exists before proceeding
if (!finalResult) {
throw new McpAdrError('No execution result available - bootstrap validation loop failed to execute', 'EXECUTION_ERROR');
}
const result = {
success,
iterations: this.currentIteration,
finalResult,
adrUpdates,
executionHistory: this.executionHistory,
requiresHumanApproval: true,
};
// Only add optional properties if they have values
if (this.deploymentPlan) {
result.deploymentPlan = this.deploymentPlan;
}
if (bootstrapAdrPath) {
result.bootstrapAdrPath = bootstrapAdrPath;
}
if (contextDocumentPath) {
result.contextDocumentPath = contextDocumentPath;
}
return result;
}
/**
* Create Bootstrap ADR with deployment plan and architecture diagrams
*/
async createBootstrapAdr(plan) {
try {
const adrContent = `# Bootstrap Deployment Plan
## Status
PROPOSED - Awaiting human approval
## Context
This ADR documents the automated deployment plan generated for this project.
**Detected Platforms**: ${plan.detectedPlatforms.join(', ')}
**Recommended Platform**: ${plan.recommendedPlatform}
**Confidence**: ${(plan.confidence * 100).toFixed(1)}%
**Source**: ${plan.source}
**Generated**: ${plan.timestamp}
## Architecture Diagram
${plan.architectureDiagram}
## Required Files
${plan.requiredFiles
.map(f => `
### ${f.path}
- **Purpose**: ${f.purpose}
- **Required**: ${f.required ? 'Yes' : 'No'}
- **Secret**: ${f.isSecret ? 'Yes' : 'No'}
- **Can Auto-Generate**: ${f.canAutoGenerate ? 'Yes' : 'No'}
- **Best Practice**: ${f.currentBestPractice}
${f.validationCommand ? `- **Validation**: \`${f.validationCommand}\`` : ''}
`)
.join('\n')}
## Environment Variables
${plan.environmentVariables
.map(e => `
- **${e.name}** (${e.required ? 'Required' : 'Optional'})${e.isSecret ? ' 🔒' : ''}
- ${e.purpose}
${e.defaultValue ? `- Default: \`${e.defaultValue}\`` : ''}
`)
.join('\n')}
## Deployment Steps
${plan.deploymentSteps
.map(s => `
### Step ${s.order}: ${s.title}
**Command**: \`${s.command}\`
**Description**: ${s.description}
**Expected Output**: ${s.expectedOutput}
**Estimated Time**: ${s.estimatedTime}
**Troubleshooting**:
${s.troubleshooting.map(t => `- ${t}`).join('\n')}
`)
.join('\n')}
## Validation Checks
${plan.validationChecks
.map(c => `
- **${c.name}** (${c.severity})
- Command: \`${c.command}\`
- Expected: ${c.expectedResult}
`)
.join('\n')}
## Risks
${plan.risks
.map(r => `
### ${r.risk} (${r.severity})
- **Likelihood**: ${r.likelihood}
- **Mitigation**: ${r.mitigation}
`)
.join('\n')}
## Prerequisites
${plan.prerequisites.map(p => `- ${p}`).join('\n')}
## Estimated Duration
${plan.estimatedDuration}
## Research Sources
${plan.researchSources.map(s => `- ${s}`).join('\n')}
## Decision
**Status**: ⏸️ **AWAITING HUMAN APPROVAL**
Please review this deployment plan and:
1. Verify the recommended platform is appropriate
2. Check that all required files are identified
3. Review security considerations (environment variables, secrets)
4. Validate deployment steps make sense for your environment
5. Approve or provide feedback for modifications
## Consequences
### Positive
- Automated deployment infrastructure
- Environment-aware configuration
- Validated deployment process
### Negative
- Initial setup overhead
- Platform-specific complexity
- Maintenance requirements
---
*This ADR was auto-generated by the Bootstrap Validation Loop system using AI-powered deployment intelligence.*
`;
// Ensure ADR directory exists
const adrDir = path.isAbsolute(this.adrDirectory)
? this.adrDirectory
: path.join(this.projectPath, this.adrDirectory);
await fs.mkdir(adrDir, { recursive: true });
// Create absolute path for ADR file
const adrPath = path.join(adrDir, `bootstrap-deployment-${Date.now()}.md`);
await fs.writeFile(adrPath, adrContent, 'utf-8');
return adrPath;
}
catch (error) {
this.logger.error('Failed to create bootstrap ADR', 'BootstrapValidationLoop', error);
throw error;
}
}
/**
* Save bootstrap context document for future sessions
*/
async saveBootstrapContext(platformDetection, validatedPattern, deploymentPlan, bootstrapAdrPath) {
try {
const contextDoc = {
metadata: {
toolName: 'bootstrap_validation_loop',
toolVersion: '1.0.0',
generated: new Date().toISOString(),
projectPath: this.projectPath,
projectName: path.basename(this.projectPath),
status: 'success',
confidence: platformDetection.confidence * 100,
},
quickReference: `
Detected ${platformDetection.primaryPlatform} (${(platformDetection.confidence * 100).toFixed(0)}% confidence).
${validatedPattern ? `Using validated pattern: ${validatedPattern.name} v${validatedPattern.version}.` : 'Using dynamic AI analysis.'}
Bootstrap ADR: ${bootstrapAdrPath}
`.trim(),
executionSummary: {
status: 'Platform detected and deployment plan generated',
confidence: platformDetection.confidence * 100,
keyFindings: [
`Primary platform: ${platformDetection.primaryPlatform}`,
validatedPattern
? `Validated pattern: ${validatedPattern.name}`
: 'Dynamic AI deployment plan',
`Required files: ${deploymentPlan.requiredFiles.length}`,
`Deployment steps: ${deploymentPlan.deploymentSteps.length}`,
`Environment variables: ${deploymentPlan.environmentVariables.length}`,
],
},
detectedContext: {
platform: {
primary: platformDetection.primaryPlatform,
all: platformDetection.detectedPlatforms.map(p => p.type),
confidence: platformDetection.confidence,
evidence: platformDetection.evidence.slice(0, 10).map(e => ({
file: e.file,
indicator: e.indicator,
weight: e.weight,
})),
},
validatedPattern: validatedPattern
? {
name: validatedPattern.name,
version: validatedPattern.version,
platformType: validatedPattern.platformType,
source: 'typescript-builtin', // Could be enhanced to detect YAML vs TS
sourceHash: this.computePatternHash(validatedPattern),
loadedAt: new Date().toISOString(),
baseRepository: validatedPattern.baseCodeRepository.url,
authoritativeSources: validatedPattern.authoritativeSources.map(s => ({
type: s.type,
url: s.url,
required: s.requiredForDeployment,
purpose: s.purpose,
})),
deploymentPhases: validatedPattern.deploymentPhases.length,
validationChecks: validatedPattern.validationChecks.length,
}
: null,
deploymentPlan: {
recommendedPlatform: deploymentPlan.recommendedPlatform,
confidence: deploymentPlan.confidence,
source: deploymentPlan.source,
requiredFiles: deploymentPlan.requiredFiles.map(f => ({
path: f.path,
purpose: f.purpose,
required: f.required,
})),
environmentVariables: deploymentPlan.environmentVariables.map(e => ({
name: e.name,
required: e.required,
isSecret: e.isSecret,
})),
deploymentSteps: deploymentPlan.deploymentSteps.length,
estimatedDuration: deploymentPlan.estimatedDuration,
},
},
generatedArtifacts: [bootstrapAdrPath, 'bootstrap.sh', 'validate_bootstrap.sh'],
keyDecisions: [
{
decision: `Use ${platformDetection.primaryPlatform} as deployment platform`,
rationale: `Detected with ${(platformDetection.confidence * 100).toFixed(0)}% confidence based on project structure and configuration files`,
alternatives: platformDetection.detectedPlatforms
.filter(p => p.type !== platformDetection.primaryPlatform)
.map(p => `${p.type} (${(p.confidence * 100).toFixed(0)}% confidence)`)
.slice(0, 3),
},
],
learnings: {
successes: ['Platform detection completed successfully'],
failures: [],
recommendations: [
'Review bootstrap ADR before proceeding with deployment',
validatedPattern
? `Consult authoritative sources for ${validatedPattern.name}`
: 'Validate deployment plan with team',
],
environmentSpecific: [],
},
relatedDocuments: {
adrs: [bootstrapAdrPath],
configs: deploymentPlan.requiredFiles.map(f => f.path),
otherContexts: [],
},
rawData: {
// Full validated pattern snapshot for reproducibility
validatedPatternSnapshot: validatedPattern
? {
source: 'typescript-builtin', // Could be enhanced to detect YAML vs TS
hash: this.computePatternHash(validatedPattern),
timestamp: new Date().toISOString(),
definition: validatedPattern, // FULL pattern object with all commands, checks, templates
}
: null,
// Deployment plan details
deploymentPlan: {
recommendedPlatform: deploymentPlan.recommendedPlatform,
confidence: deploymentPlan.confidence,
source: deploymentPlan.source,
requiredFiles: deploymentPlan.requiredFiles,
environmentVariables: deploymentPlan.environmentVariables,
deploymentSteps: deploymentPlan.deploymentSteps,
estimatedDuration: deploymentPlan.estimatedDuration,
},
},
};
// Add validated pattern details if available
if (validatedPattern) {
contextDoc.keyDecisions.push({
decision: `Use ${validatedPattern.name} validated pattern`,
rationale: `Best practice pattern for ${platformDetection.primaryPlatform} deployments. Provides proven deployment workflow and authoritative sources.`,
alternatives: ['Custom deployment plan', 'Dynamic AI-generated plan'],
});
}
const contextPath = await this.contextManager.saveContext('bootstrap', contextDoc);
return contextPath;
}
catch (error) {
this.logger.error('Failed to save bootstrap context', 'BootstrapValidationLoop', error);
throw error;
}
}
/**
* Generate bootstrap scripts from validated pattern (NEW)
*/
async generateBootstrapScriptsFromPattern() {
if (!this.validatedPattern) {
return false;
}
try {
this.logger.info(`Generating bootstrap scripts from validated pattern: ${this.validatedPattern.name}`, 'BootstrapValidationLoop');
// Generate bootstrap.sh from pattern's deployment phases
let bootstrapScript = `#!/bin/bash
# Bootstrap script generated from ${this.validatedPattern.name} v${this.validatedPattern.version}
# Pattern source: ${this.validatedPattern.metadata.source}
# Last updated: ${this.validatedPattern.metadata.lastUpdated}
# Generated: ${new Date().toISOString()}
set -e # Exit on error
set -u # Exit on undefined variable
echo "========================================"
echo "Bootstrap Deployment - ${this.validatedPattern.platformType}"
echo "Pattern: ${this.validatedPattern.name}"
echo "========================================"
echo ""
`;
// Add each deployment phase
for (const phase of this.validatedPattern.deploymentPhases) {
bootstrapScript += `
# ============================================================================
# Phase ${phase.order}: ${phase.name}
# ${phase.description}
# Estimated duration: ${phase.estimatedDuration}
# ============================================================================
echo "Starting Phase ${phase.order}: ${phase.name}"
`;
// Add commands for this phase
for (const command of phase.commands) {
bootstrapScript += `# ${command.description}\n`;
bootstrapScript += `echo " → ${command.description}"\n`;
bootstrapScript += `${command.command}\n\n`;
}
bootstrapScript += `echo "✓ Phase ${phase.order} complete"\necho ""\n`;
}
bootstrapScript += `
echo "========================================"
echo "✅ Bootstrap deployment complete!"
echo "========================================"
`;
// Generate validate_bootstrap.sh from pattern's validation checks
let validationScript = `#!/bin/bash
# Validation script generated from ${this.validatedPattern.name}
# Generated: ${new Date().toISOString()}
set -e
echo "========================================"
echo "Bootstrap Validation"
echo "========================================"
echo ""
FAILED_CHECKS=0
`;
for (const check of this.validatedPattern.validationChecks) {
validationScript += `
# ${check.name} (${check.severity})
echo "Checking: ${check.name}"
if ${check.command}; then
echo " ✅ PASSED: ${check.name}"
else
echo " ❌ FAILED: ${check.name}"
echo " ${check.failureMessage}"
echo " Remediation steps:"
${check.remediationSteps.map(step => ` echo " - ${step}"`).join('\n')}
FAILED_CHECKS=$((FAILED_CHECKS + 1))
fi
echo ""
`;
}
validationScript += `
if [ $FAILED_CHECKS -eq 0 ]; then
echo "========================================"
echo "✅ All validation checks passed!"
echo "========================================"
exit 0
else
echo "========================================"
echo "❌ $FAILED_CHECKS validation check(s) failed"
echo "========================================"
exit 1
fi
`;
// Write scripts
const bootstrapPath = path.join(this.projectPath, 'bootstrap.sh');
await fs.writeFile(bootstrapPath, bootstrapScript, { mode: 0o755 });
const validationPath = path.join(this.projectPath, 'validate_bootstrap.sh');
await fs.writeFile(validationPath, validationScript, { mode: 0o755 });
this.logger.info('Bootstrap scripts generated from validated pattern', 'BootstrapValidationLoop', {
bootstrapPath,
validationPath,
phases: this.validatedPattern.deploymentPhases.length,
validationChecks: this.validatedPattern.validationChecks.length,
});
return true;
}
catch (error) {
this.logger.error('Failed to generate scripts from validated pattern', 'BootstrapValidationLoop', error);
return false;
}
}
/**
* Generate bootstrap scripts from current ADRs (FALLBACK)
*/
async generateBootstrapScripts() {
// NEW: Try validated pattern first if available
if (this.validatedPattern) {
this.logger.info('🎯 Using validated pattern to generate bootstrap scripts', 'BootstrapValidationLoop');
const patternSuccess = await this.generateBootstrapScriptsFromPattern();
if (patternSuccess) {
return true;
}
this.logger.warn('Failed to generate from validated pattern, falling back to ADR-based generation', 'BootstrapValidationLoop');
}
try {
this.logger.info('Generating bootstrap scripts from ADRs', 'BootstrapValidationLoop');
const result = await generateAdrBootstrapScripts({
projectPath: this.projectPath,
adrDirectory: this.adrDirectory,
outputPath: this.projectPath,
scriptType: 'both',
includeTests: true,
includeDeployment: true,
enableTreeSitterAnalysis: true,
});
// Validate result structure
if (!result?.content?.[0]?.text) {
throw new McpAdrError('Invalid response from bootstrap script generator - missing content', 'INVALID_RESPONSE');
}
// Extract and validate scripts from result
let response;
try {
response = JSON.parse(result.content[0].text);
}
catch (parseError) {
this.logger.error('Failed to parse bootstrap script response as JSON', 'BootstrapValidationLoop', parseError);
throw new McpAdrError('Malformed JSON response from script generator', 'PARSE_ERROR');
}
// Validate response structure and required properties
if (!response?.scripts) {
throw new McpAdrError('Invalid response structure - missing scripts property', 'INVALID_RESPONSE');
}
if (typeof response.scripts.bootstrap !== 'string' || !response.scripts.bootstrap.trim()) {
throw new McpAdrError('Invalid or empty bootstrap script in response', 'INVALID_SCRIPT');
}
if (typeof response.scripts.validation !== 'string' || !response.scripts.validation.trim()) {
throw new McpAdrError('Invalid or empty validation script in response', 'INVALID_SCRIPT');
}
// Write bootstrap.sh
const bootstrapPath = path.join(this.projectPath, 'bootstrap.sh');
await fs.writeFile(bootstrapPath, response.scripts.bootstrap, { mode: 0o755 });
// Write validate_bootstrap.sh
const validationPath = path.join(this.projectPath, 'validate_bootstrap.sh');
await fs.writeFile(validationPath, response.scripts.validation, { mode: 0o755 });
this.logger.info('Bootstrap scripts generated successfully', 'BootstrapValidationLoop', {
bootstrapPath,
validationPath,
});
return true;
}
catch (error) {
this.logger.error('Failed to generate bootstrap scripts', 'BootstrapValidationLoop', error);
return false;
}
}
/**
* Execute bootstrap.sh with environment monitoring
*/
async executeBootstrapWithMonitoring(targetEnvironment, captureSnapshot) {
const executionId = `bootstrap_${Date.now()}_${Math.random().toString(36).slice(2, 11)}`;
const timestamp = new Date().toISOString();
const startTime = Date.now();
this.logger.info('Executing bootstrap.sh with monitoring', 'BootstrapValidationLoop', {
executionId,
targetEnvironment,
});
let environmentSnapshot = {};
// Capture pre-execution environment snapshot
if (captureSnapshot) {
environmentSnapshot = await this.captureEnvironmentSnapshot();
}
// Execute bootstrap.sh
const bootstrapPath = path.join(this.projectPath, 'bootstrap.sh');
let exitCode = 0;
let stdout = '';
let stderr = '';
try {
const result = await execAsync(`bash "${bootstrapPath}"`, {
cwd: this.projectPath,
timeout: 300000, // 5 minute timeout
maxBuffer: 10 * 1024 * 1024, // 10MB buffer
});
stdout = result.stdout;
stderr = result.stderr;
}
catch (error) {
exitCode = error.code || 1;
stdout = error.stdout || '';
stderr = error.stderr || error.message || '';
this.logger.warn('Bootstrap execution failed', 'BootstrapValidationLoop', {
exitCode,
stderr: stderr.substring(0, 500),
});
}
const duration = Date.now() - startTime;
return {
executionId,
timestamp,
success: exitCode === 0,
duration,
exitCode,
stdout,
stderr,
environmentSnapshot,
learnings: [], // Will be populated later
};
}
/**
* Execute validate_bootstrap.sh and analyze results
*/
async executeValidationScript(executionId) {
this.logger.info('Executing validate_bootstrap.sh', 'BootstrapValidationLoop', { executionId });
const validationPath = path.join(this.projectPath, 'validate_bootstrap.sh');
const validationResults = [];
let allPassed = true;
try {
const result = await execAsync(`bash "${validationPath}"`, {
cwd: this.projectPath,
timeout: 180000, // 3 minute timeout
});
// Parse validation output
// This is a simplified parser - actual implementation would be more sophisticated
const lines = result.stdout.split('\n');
for (const line of lines) {
if (line.includes('PASSED') || line.includes('FAILED')) {
const passed = line.includes('PASSED');
if (!passed)
allPassed = false;
validationResults.push({
checkId: `validation_${validationResults.length}`,
adrId: 'unknown', // Would be parsed from output
requirement: line.trim(),
passed,
actualState: passed ? 'compliant' : 'non-compliant',
expectedState: 'compliant',
confidence: 0.9,
evidence: [line],
});
}
}
}
catch (error) {
allPassed = false;
this.logger.error('Validation script failed', 'BootstrapValidationLoop', error);
// Record the failure
validationResults.push({
checkId: 'validation_execution',
adrId: 'system',
requirement: 'Execute validation script',
passed: false,
actualState: 'failed',
expectedState: 'success',
confidence: 1.0,
evidence: [error.message],
});
}
return { allPassed, validationResults };
}
/**
* Extract learnings from execution results
*/
async extractLearnings(executionResult, validationResult) {
const learnings = [];
// Analyze failures
for (const validation of validationResult.validationResults) {
if (!validation.passed) {
learnings.push({
type: 'failure',
category: 'infrastructure',
description: `Validation failed: ${validation.requirement}`,
adrReference: validation.adrId,
severity: 'error',
recommendation: await this.generateRecommendation(validation, executionResult),
evidence: validation.evidence,
environmentSpecific: true,
timestamp: new Date().toISOString(),
});
}
}
// Analyze stderr for issues
if (executionResult.stderr) {
const errorLines = executionResult.stderr.split('\n').filter(line => line.trim());
for (const errorLine of errorLines) {
if (errorLine.toLowerCase().includes('error') ||
errorLine.toLowerCase().includes('failed')) {
learnings.push({
type: 'failure',
category: 'configuration',
description: errorLine.substring(0, 200),
severity: 'error',
recommendation: 'Review error message and adjust bootstrap script',
evidence: [errorLine],
environmentSpecific: true,
timestamp: new Date().toISOString(),
});
}
}
}
// Use ResearchOrchestrator to understand environment state
try {
const envCheck = await this.researchOrchestrator.answerResearchQuestion('What is the current state of the deployment environment? List all running services.');
if (envCheck.confidence > 0.7) {
learnings.push({
type: 'success',
category: 'infrastructure',
description: `Environment state verified: ${envCheck.answer?.substring(0, 200)}`,
severity: 'info',
recommendation: 'Document current environment state in ADRs',
evidence: [envCheck.answer || 'Environment check completed'],
environmentSpecific: true,
timestamp: new Date().toISOString(),
});
}
}
catch (error) {
this.logger.warn('Failed to check environment state', 'BootstrapValidationLoop', error);
}
return learnings;
}
/**
* Generate recommendation for a failed validation
*/
async generateRecommendation(validation, _executionResult) {
// Use ResearchOrchestrator to generate context-aware recommendation
try {
const question = `How can we fix this deployment issue: ${validation.requirement}?
Current state: ${validation.actualState}
Expected state: ${validation.expectedState}
Evidence: ${validation.evidence.join(', ')}`;
const answer = await this.researchOrchestrator.answerResearchQuestion(question);
if (answer.confidence > 0.6 && answer.answer) {
return answer.answer.substring(0, 500);
}
}
catch (error) {
this.logger.warn('Failed to generate AI recommendation', 'BootstrapValidationLoop', error);
}
return 'Review validation failure and adjust bootstrap script accordingly';
}
/**
* Update bootstrap scripts based on learnings
*/
async updateBootstrapScriptsFromLearnings(learnings, _executionResult) {
try {
const bootstrapPath = path.join(this.projectPath, 'bootstrap.sh');
let bootstrapContent = await fs.readFile(bootstrapPath, 'utf-8');
// Apply fixes based on learnings
for (const learning of learnings) {
if (learning.type === 'failure' && learning.category === 'infrastructure') {
// Add prerequisite checks
if (learning.description.toLowerCase().includes('postgres')) {
const postgresCheck = `
# Auto-fix: Added PostgreSQL startup check
if ! pgrep -x "postgres" > /dev/null; then
echo "Starting PostgreSQL..."
systemctl start postgresql || brew services start postgresql
sleep 3
fi
`;
bootstrapContent = bootstrapContent.replace('# Phase 2: Build and Prepare', postgresCheck + '\n# Phase 2: Build and Prepare');
}
// Add Docker checks
if (learning.description.toLowerCase().includes('docker')) {
const dockerCheck = `
# Auto-fix: Added Docker check
if ! docker ps > /dev/null 2>&1; then
echo "Docker is not running. Please start Docker and retry."
exit 1
fi
`;
bootstrapContent = dockerCheck + '\n' + bootstrapContent;
}
}
}
// Write updated script
await fs.writeFile(bootstrapPath, bootstrapContent, { mode: 0o755 });
this.logger.info('Bootstrap script updated with auto-fixes', 'BootstrapValidationLoop', {
fixesApplied: learnings.filter(l => l.type === 'failure').length,
});
return true;
}
catch (error) {
this.logger.error('Failed to update bootstrap scripts', 'BootstrapValidationLoop', error);
return false;
}
}
/**
* Generate ADR update proposals based on learnings
*/
async generateAdrUpdates(learnings, outcome) {
const proposals = [];
const { discoverAdrsInDirectory } = await import('../utils/adr-discovery.js');
const adrs = await discoverAdrsInDirectory(this.adrDirectory, this.projectPath, {
includeContent: true,
includeTimeline: false,
});
for (const adr of adrs.adrs) {
// Find learnings related to this ADR
const relatedLearnings = learnings.filter(l => l.adrReference === adr.filename || adr.content?.includes(l.description.substring(0, 50)));
if (relatedLearnings.length === 0)
continue;
// Generate update content
const updateContent = this.generateDeploymentExperienceSection(relatedLearnings, outcome);
proposals.push({
adrPath: path.join(this.adrDirectory, adr.filename || 'unknown.md'),
adrTitle: adr.title || 'Unknown ADR',
updateType: 'append',
sectionToUpdate: 'Deployment Experience',
proposedContent: updateContent,
learnings: relatedLearnings,
confidence: 0.85,
requiresReview: outcome === 'failure' && relatedLearnings.some(l => l.severity === 'critical'),
});
}
return proposals;
}
/**
* Generate deployment experience section content
*/
generateDeploymentExperienceSection(learnings, outcome) {
const timestamp = new Date().toISOString().split('T')[0];
let content = `\n## Deployment Experience\n\n`;
content += `**Last Updated**: ${timestamp}\n`;
content += `**Deployment Outcome**: ${outcome === 'success' ? '✅ Successful' : '⚠️ Issues Encountered'}\n\n`;
// Group learnings by category
const byCategory = {};
for (const learning of learnings) {
if (!byCategory[learning.category]) {
byCategory[learning.category] = [];
}
byCategory[learning.category].push(learning);
}
for (const [category, categoryLearnings] of Object.entries(byCategory)) {
content += `### ${category.charAt(0).toUpperCase() + category.slice(1)}\n\n`;
for (const learning of categoryLearnings) {
const icon = learning.type === 'success' ? '✅' : learning.type === 'failure' ? '❌' : 'ℹ️';
content += `${icon} **${learning.description}**\n`;
content += ` - Severity: ${learning.severity}\n`;
content += ` - Recommendation: ${learning.recommendation}\n`;
if (learning.environmentSpecific) {
content += ` - *Environment-specific consideration*\n`;
}
content += `\n`;
}
}
return content;
}
/**
* Detect missing files that might break bootstrap
*/
async detectMissingFiles() {
const missingFiles = [];
try {
// Parse .gitignore patterns
const gitignorePatterns = await this.parseGitignore();
// Extract file references from ADRs
const { discoverAdrsInDirectory } = await import('../utils/adr-discovery.js');
const adrs = await discoverAdrsInDirectory(this.adrDirectory, this.projectPath, {
includeContent: true,
includeTimeline: false,
});
const fileReferences = await this.extractFileReferencesFromAdrs(adrs.adrs);
// Check each referenced file
for (const [filePath, referencedBy] of fileReferences.entries()) {
const fullPath = path.join(this.projectPath, filePath);
try {
await fs.access(fullPath);
// File exists, continue
}
catch (error) {
// Only treat as missing if it's a "file not found" error
// Other errors (permissions, etc.) should be logged but not treated as missing
if (error.code === 'ENOENT') {
const isIgnored = this.isFileIgnored(filePath, gitignorePatterns);
const fileInfo = this.analyzeMissingFile(filePath, referencedBy, isIgnored);
missingFiles.push(fileInfo);
}
else {
this.logger.warn(`Error accessing file ${filePath}: ${error.message}`, 'BootstrapValidationLoop');
}
}
}
// Check for common missing files
const commonFiles = [
{ path: '.env', type: 'env', critical: true },
{ path: '.env.example', type: 'env', critical: false },
{ path: 'config/database.yml', type: 'config', critical: true },
{ path: 'config/secrets.yml',