grimoire-framework 1.0.0

package/packages/installer/src/wizard/validation/troubleshooting-system.js

@@ -0,0 +1,348 @@
+/**
+ * Troubleshooting System
+ * Task 1.8.6: Provides actionable troubleshooting for errors
+ *
+ * @module wizard/validation/troubleshooting-system
+ */
+
+const chalk = require('chalk');
+const inquirer = require('inquirer');
+
+/**
+ * Troubleshooting database
+ * Maps error codes to detailed troubleshooting information
+ */
+const TROUBLESHOOTING_DATABASE = {
+  ENV_FILE_MISSING: {
+    problem: '.env file not found',
+    causes: [
+      'Environment configuration step failed',
+      'File creation permissions issue',
+      '.env accidentally deleted',
+    ],
+    solutions: [
+      'Re-run wizard: npx @grimoireAI/grimoire@latest init',
+      'Manually create .env from template: cp .env.example .env',
+      'Check file permissions in project directory',
+    ],
+    docs: 'https://docs.grimoireAI.com/installation/environment',
+    priority: 'critical',
+  },
+
+  CORE_CONFIG_MISSING: {
+    problem: 'core-config.yaml not found',
+    causes: [
+      'Environment configuration step failed',
+      '.grimoire directory missing',
+      'File creation failed',
+    ],
+    solutions: [
+      'Re-run wizard: npx @grimoireAI/grimoire@latest init',
+      'Check .grimoire directory exists',
+      'Manually create from template',
+    ],
+    docs: 'https://docs.grimoireAI.com/configuration/core-config',
+    priority: 'high',
+  },
+
+  MCP_HEALTH_CHECK_FAILED: {
+    problem: 'MCP health check failed',
+    causes: [
+      'API key missing or invalid',
+      'Network connectivity issues',
+      'MCP service temporarily unavailable',
+      'Package not installed correctly',
+    ],
+    solutions: [
+      'Verify API key in .env file',
+      'Test network: curl https://api.service.com/health',
+      'Retry MCP installation: npm run install:mcps',
+      'Check MCP service status',
+      'Verify npx can access package: npx -y [package-name] --version',
+    ],
+    docs: 'https://docs.grimoireAI.com/mcps/troubleshooting',
+    priority: 'medium',
+  },
+
+  ALL_MCP_HEALTH_CHECKS_FAILED: {
+    problem: 'All MCP health checks failed',
+    causes: [
+      'Network connectivity issue',
+      'MCPs not installed correctly',
+      'Configuration file corrupted',
+      'API keys not configured',
+    ],
+    solutions: [
+      'Check internet connection',
+      'Re-run MCP installation',
+      'Verify .mcp.json syntax',
+      'Configure API keys in .env',
+      'Delete .mcp.json and reinstall',
+    ],
+    docs: 'https://docs.grimoireAI.com/mcps/troubleshooting',
+    priority: 'high',
+  },
+
+  GITIGNORE_CRITICAL_MISSING: {
+    problem: '.gitignore missing critical entries',
+    causes: [
+      '.gitignore not created during setup',
+      '.gitignore manually edited incorrectly',
+      'Git not initialized',
+    ],
+    solutions: [
+      'Add missing entries to .gitignore',
+      'Copy from template: .env, node_modules, *.key, *.pem',
+      'Initialize git if needed: git init',
+    ],
+    docs: 'https://docs.grimoireAI.com/security/gitignore',
+    priority: 'high',
+  },
+
+  DEPS_INSTALL_FAILED: {
+    problem: 'Dependencies installation failed',
+    causes: [
+      'Network connectivity issues',
+      'Package manager not installed',
+      'npm/yarn registry unavailable',
+      'Disk space insufficient',
+    ],
+    solutions: [
+      'Check internet connection',
+      'Verify package manager installed: npm --version',
+      'Clear cache: npm cache clean --force',
+      'Try different package manager: yarn or pnpm',
+      'Check disk space: df -h (Unix) or dir (Windows)',
+    ],
+    docs: 'https://docs.grimoireAI.com/installation/dependencies',
+    priority: 'critical',
+  },
+
+  CRITICAL_DEPS_MISSING: {
+    problem: 'Critical dependencies missing',
+    causes: [
+      'Dependency installation incomplete',
+      'node_modules corrupted',
+      'Package installation failed silently',
+    ],
+    solutions: [
+      'Delete node_modules: rm -rf node_modules',
+      'Delete lock file: rm package-lock.json',
+      'Reinstall: npm install',
+      'Try clean install: npm ci',
+    ],
+    docs: 'https://docs.grimoireAI.com/installation/dependencies',
+    priority: 'high',
+  },
+
+  VULNERABILITIES_FOUND: {
+    problem: 'Security vulnerabilities found in dependencies',
+    causes: [
+      'Outdated packages with known vulnerabilities',
+      'Transitive dependencies with security issues',
+    ],
+    solutions: [
+      'Run: npm audit fix',
+      'Run: npm audit fix --force (if needed)',
+      'Update packages: npm update',
+      'Review: npm audit for details',
+    ],
+    docs: 'https://docs.npmjs.com/cli/v8/commands/npm-audit',
+    priority: 'medium',
+  },
+
+  ENV_PERMISSIONS_INSECURE: {
+    problem: '.env file permissions too permissive',
+    causes: [
+      'File created with default permissions',
+      'Permissions not set during installation',
+    ],
+    solutions: [
+      'Run: chmod 600 .env',
+      'Verify: ls -la .env',
+    ],
+    docs: 'https://docs.grimoireAI.com/security/file-permissions',
+    priority: 'medium',
+  },
+};
+
+/**
+ * Offer troubleshooting for errors
+ *
+ * @param {Array} errors - Array of error objects
+ */
+async function offerTroubleshooting(errors) {
+  if (!errors || errors.length === 0) {
+    return;
+  }
+
+  console.log('');
+  console.log(chalk.bold.cyan('═══════════════════════════════════════════════'));
+  console.log(chalk.bold.cyan('🔧 Troubleshooting Guide'));
+  console.log(chalk.bold.cyan('═══════════════════════════════════════════════'));
+  console.log('');
+
+  // Group errors by code
+  const errorsByCode = {};
+  errors.forEach(error => {
+    const code = error.code || 'UNKNOWN';
+    if (!errorsByCode[code]) {
+      errorsByCode[code] = [];
+    }
+    errorsByCode[code].push(error);
+  });
+
+  // Sort by priority
+  const errorCodes = Object.keys(errorsByCode).sort((a, b) => {
+    const priorityA = TROUBLESHOOTING_DATABASE[a]?.priority || 'low';
+    const priorityB = TROUBLESHOOTING_DATABASE[b]?.priority || 'low';
+    const priorityOrder = { critical: 0, high: 1, medium: 2, low: 3 };
+    return priorityOrder[priorityA] - priorityOrder[priorityB];
+  });
+
+  // Display troubleshooting for each error code
+  for (const code of errorCodes) {
+    const errorInstances = errorsByCode[code];
+    const troubleshooting = TROUBLESHOOTING_DATABASE[code];
+
+    if (troubleshooting) {
+      displayTroubleshooting(code, troubleshooting, errorInstances);
+    } else {
+      displayGenericTroubleshooting(code, errorInstances);
+    }
+  }
+
+  // Ask if user wants to see full logs
+  const { viewLogs } = await inquirer.prompt([
+    {
+      type: 'confirm',
+      name: 'viewLogs',
+      message: 'Would you like to see installation logs for more details?',
+      default: false,
+    },
+  ]);
+
+  if (viewLogs) {
+    console.log('');
+    console.log(chalk.bold('📄 Installation Logs:'));
+    console.log(chalk.dim('  - .grimoire/install-log.txt'));
+    console.log(chalk.dim('  - .grimoire/install-errors.log'));
+    console.log('');
+    console.log(chalk.dim('View with: cat .grimoire/install-log.txt'));
+  }
+
+  // Offer to open documentation
+  const { openDocs } = await inquirer.prompt([
+    {
+      type: 'confirm',
+      name: 'openDocs',
+      message: 'Would you like to open the troubleshooting documentation?',
+      default: false,
+    },
+  ]);
+
+  if (openDocs) {
+    console.log('');
+    console.log(chalk.green('📚 Documentation:'));
+    console.log(chalk.green('  https://docs.grimoireAI.com/troubleshooting'));
+    console.log('');
+  }
+
+  // Offer support contact
+  console.log('');
+  console.log(chalk.bold('💬 Need Help?'));
+  console.log(chalk.dim('  - GitHub Issues: https://github.com/grimoireAI/grimoire/issues'));
+  console.log(chalk.dim('  - Documentation: https://docs.grimoireAI.com'));
+  console.log('');
+}
+
+/**
+ * Display troubleshooting for a specific error
+ * @private
+ */
+function displayTroubleshooting(code, troubleshooting, errorInstances) {
+  const priorityIcon = {
+    critical: chalk.red('🔴'),
+    high: chalk.yellow('🟡'),
+    medium: chalk.blue('🔵'),
+    low: chalk.gray('⚪'),
+  }[troubleshooting.priority] || '⚪';
+
+  console.log(chalk.bold(`${priorityIcon} ${troubleshooting.problem}`));
+  console.log('');
+
+  // Show affected items
+  if (errorInstances.length > 1) {
+    console.log(chalk.dim(`Affected items (${errorInstances.length}):`));
+    errorInstances.slice(0, 3).forEach(err => {
+      if (err.file) {
+        console.log(chalk.dim(`  - ${err.file}`));
+      } else if (err.mcp) {
+        console.log(chalk.dim(`  - ${err.mcp}`));
+      }
+    });
+    if (errorInstances.length > 3) {
+      console.log(chalk.dim(`  ... and ${errorInstances.length - 3} more`));
+    }
+    console.log('');
+  }
+
+  // Show causes
+  if (troubleshooting.causes && troubleshooting.causes.length > 0) {
+    console.log(chalk.bold('Possible Causes:'));
+    troubleshooting.causes.forEach((cause, i) => {
+      console.log(`  ${i + 1}. ${cause}`);
+    });
+    console.log('');
+  }
+
+  // Show solutions
+  console.log(chalk.bold.green('Solutions:'));
+  troubleshooting.solutions.forEach((solution, i) => {
+    console.log(chalk.green(`  ${i + 1}. ${solution}`));
+  });
+  console.log('');
+
+  // Show documentation link
+  if (troubleshooting.docs) {
+    console.log(chalk.dim(`📖 Docs: ${troubleshooting.docs}`));
+    console.log('');
+  }
+
+  console.log(chalk.dim('─────────────────────────────────────────────────'));
+  console.log('');
+}
+
+/**
+ * Display generic troubleshooting
+ * @private
+ */
+function displayGenericTroubleshooting(code, errorInstances) {
+  console.log(chalk.bold(`⚠️  ${code}`));
+  console.log('');
+
+  errorInstances.forEach(err => {
+    console.log(`  ${err.message}`);
+    if (err.solution) {
+      console.log(chalk.green(`  → ${err.solution}`));
+    }
+  });
+
+  console.log('');
+  console.log(chalk.bold.green('General Solutions:'));
+  console.log(chalk.green('  1. Review error message above'));
+  console.log(chalk.green('  2. Check installation logs in .grimoire/'));
+  console.log(chalk.green('  3. Re-run installation'));
+  console.log(chalk.green('  4. Contact support if issue persists'));
+  console.log('');
+
+  console.log(chalk.dim('─────────────────────────────────────────────────'));
+  console.log('');
+}
+
+module.exports = {
+  offerTroubleshooting,
+  TROUBLESHOOTING_DATABASE,
+};
+
+

package/packages/installer/src/wizard/validation/validators/config-validator.js

@@ -0,0 +1,364 @@
+/**
+ * Configuration Validator
+ * Task 1.8.2: Validates .env, core-config.yaml, and .mcp.json
+ *
+ * @module wizard/validation/validators/config-validator
+ */
+
+const fs = require('fs');
+const yaml = require('js-yaml');
+
+/**
+ * Validate configurations
+ *
+ * @param {Object} configContext - Configuration context
+ * @param {Object} configContext.env - Environment config result
+ * @param {Object} configContext.mcps - MCP installation result
+ * @param {string} configContext.coreConfig - Path to core-config.yaml
+ * @returns {Promise<Object>} Validation result
+ */
+async function validateConfigs(configContext = {}) {
+  const results = {
+    success: true,
+    checks: [],
+    errors: [],
+    warnings: [],
+  };
+
+  try {
+    // Validate .env file format and content (Story 1.6)
+    await validateEnvFile(results);
+
+    // Validate core-config.yaml YAML syntax (Story 1.6)
+    await validateCoreConfig(results, configContext.coreConfig);
+
+    // Validate .mcp.json schema compliance (Story 1.5)
+    await validateMCPConfig(results);
+
+    // Validate .gitignore entries (security)
+    await validateGitignore(results);
+
+    return results;
+  } catch (error) {
+    results.success = false;
+    results.errors.push({
+      severity: 'critical',
+      message: `Configuration validation failed: ${error.message}`,
+      code: 'CONFIG_VALIDATION_ERROR',
+      details: error.stack,
+    });
+
+    return results;
+  }
+}
+
+/**
+ * Validate .env file
+ * @private
+ */
+async function validateEnvFile(results) {
+  const envPath = '.env';
+
+  if (!fs.existsSync(envPath)) {
+    results.success = false;
+    results.errors.push({
+      severity: 'critical',
+      message: '.env file not found',
+      file: envPath,
+      code: 'ENV_FILE_MISSING',
+    });
+    return;
+  }
+
+  try {
+    const envContent = fs.readFileSync(envPath, 'utf8');
+    const lines = envContent.split('\n');
+    const validLines = lines.filter(line => {
+      const trimmed = line.trim();
+      return trimmed && !trimmed.startsWith('#');
+    });
+
+    // Check for required variables (basic validation)
+    const requiredVars = ['NODE_ENV'];
+    const envVars = {};
+
+    validLines.forEach(line => {
+      const match = line.match(/^([A-Z_][A-Z0-9_]*)=(.*)$/);
+      if (match) {
+        envVars[match[1]] = match[2];
+      }
+    });
+
+    for (const varName of requiredVars) {
+      if (!envVars[varName]) {
+        results.warnings.push({
+          severity: 'low',
+          message: `Recommended environment variable missing: ${varName}`,
+          file: envPath,
+          code: 'ENV_VAR_MISSING',
+        });
+      }
+    }
+
+    // Security check: Verify no hardcoded sensitive data in comments
+    const sensitivePattern = /(password|secret|key|token).*=.*[^${]/i;
+    lines.forEach((line, index) => {
+      if (sensitivePattern.test(line) && !line.trim().startsWith('#')) {
+        results.warnings.push({
+          severity: 'medium',
+          message: `Possible hardcoded credential on line ${index + 1}`,
+          file: envPath,
+          line: index + 1,
+          code: 'POTENTIAL_HARDCODED_CREDENTIAL',
+        });
+      }
+    });
+
+    results.checks.push({
+      component: 'Environment Config',
+      file: envPath,
+      status: 'success',
+      message: `Validated (${validLines.length} variables)`,
+    });
+  } catch (error) {
+    results.errors.push({
+      severity: 'high',
+      message: `.env file validation failed: ${error.message}`,
+      file: envPath,
+      code: 'ENV_VALIDATION_ERROR',
+    });
+    results.success = false;
+  }
+}
+
+/**
+ * Validate core-config.yaml
+ * @private
+ */
+async function validateCoreConfig(results, configPath = '.grimoire/core-config.yaml') {
+  if (!fs.existsSync(configPath)) {
+    results.warnings.push({
+      severity: 'medium',
+      message: 'core-config.yaml not found',
+      file: configPath,
+      code: 'CORE_CONFIG_MISSING',
+    });
+    return;
+  }
+
+  try {
+    const yamlContent = fs.readFileSync(configPath, 'utf8');
+    const parsed = yaml.load(yamlContent);
+
+    if (!parsed || typeof parsed !== 'object') {
+      results.errors.push({
+        severity: 'high',
+        message: 'core-config.yaml is empty or invalid',
+        file: configPath,
+        code: 'CORE_CONFIG_INVALID',
+      });
+      results.success = false;
+      return;
+    }
+
+    // Basic schema validation
+    const requiredKeys = ['markdownExploder', 'qa', 'prd', 'architecture'];
+    const missingKeys = requiredKeys.filter(key => !(key in parsed));
+
+    if (missingKeys.length > 0) {
+      results.warnings.push({
+        severity: 'low',
+        message: `core-config.yaml missing recommended keys: ${missingKeys.join(', ')}`,
+        file: configPath,
+        code: 'CORE_CONFIG_INCOMPLETE',
+      });
+    }
+
+    results.checks.push({
+      component: 'Core Config',
+      file: configPath,
+      status: 'success',
+      message: 'Valid YAML syntax',
+    });
+  } catch (error) {
+    results.errors.push({
+      severity: 'high',
+      message: `core-config.yaml parsing failed: ${error.message}`,
+      file: configPath,
+      code: 'CORE_CONFIG_PARSE_ERROR',
+    });
+    results.success = false;
+  }
+}
+
+/**
+ * Validate .mcp.json
+ * @private
+ */
+async function validateMCPConfig(results) {
+  const mcpConfigPath = '.mcp.json';
+
+  if (!fs.existsSync(mcpConfigPath)) {
+    // MCP config is optional
+    results.checks.push({
+      component: 'MCP Config',
+      file: mcpConfigPath,
+      status: 'skipped',
+      message: 'Not installed (optional)',
+    });
+    return;
+  }
+
+  try {
+    const mcpContent = fs.readFileSync(mcpConfigPath, 'utf8');
+    const parsed = JSON.parse(mcpContent);
+
+    if (!parsed.mcpServers || typeof parsed.mcpServers !== 'object') {
+      results.errors.push({
+        severity: 'medium',
+        message: '.mcp.json missing mcpServers key',
+        file: mcpConfigPath,
+        code: 'MCP_CONFIG_INVALID_SCHEMA',
+      });
+      return;
+    }
+
+    const mcpCount = Object.keys(parsed.mcpServers).length;
+    results.checks.push({
+      component: 'MCP Config',
+      file: mcpConfigPath,
+      status: 'success',
+      message: `Valid schema (${mcpCount} MCP${mcpCount !== 1 ? 's' : ''})`,
+    });
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      results.errors.push({
+        severity: 'high',
+        message: `.mcp.json has invalid JSON syntax: ${error.message}`,
+        file: mcpConfigPath,
+        code: 'MCP_CONFIG_PARSE_ERROR',
+      });
+      results.success = false;
+    } else {
+      results.warnings.push({
+        severity: 'medium',
+        message: `.mcp.json validation failed: ${error.message}`,
+        file: mcpConfigPath,
+      });
+    }
+  }
+}
+
+/**
+ * Check if a gitignore entry exists (handles variations like node_modules, node_modules/, /node_modules)
+ * @private
+ * @param {string[]} lines - gitignore lines
+ * @param {string} entry - entry to check
+ * @returns {boolean}
+ */
+function hasGitignoreEntry(lines, entry) {
+  // Normalize the entry to check (remove leading/trailing slashes)
+  const normalizedEntry = entry.replace(/^\//, '').replace(/\/$/, '');
+
+  return lines.some(line => {
+    const normalizedLine = line.replace(/^\//, '').replace(/\/$/, '');
+    // Check exact match or variations
+    return normalizedLine === normalizedEntry ||
+           normalizedLine === entry ||
+           line === entry ||
+           line === `/${entry}` ||
+           line === `${entry}/`;
+  });
+}
+
+/**
+ * Validate .gitignore entries
+ * @private
+ */
+async function validateGitignore(results) {
+  const gitignorePath = '.gitignore';
+
+  if (!fs.existsSync(gitignorePath)) {
+    results.warnings.push({
+      severity: 'medium',
+      message: '.gitignore not found - sensitive files may be committed',
+      file: gitignorePath,
+      code: 'GITIGNORE_MISSING',
+    });
+    return;
+  }
+
+  try {
+    const gitignoreContent = fs.readFileSync(gitignorePath, 'utf8');
+    const lines = gitignoreContent.split('\n').map(l => l.trim());
+
+    // Critical entries - .env is always critical, node_modules is critical but has variations
+    const criticalEntries = ['.env'];
+    const recommendedEntries = ['.env.local', '*.key', '*.pem', '.grimoire/install-log.txt'];
+
+    // Check critical entries
+    for (const entry of criticalEntries) {
+      if (!hasGitignoreEntry(lines, entry)) {
+        results.errors.push({
+          severity: 'high',
+          message: `.gitignore missing critical entry: ${entry}`,
+          file: gitignorePath,
+          code: 'GITIGNORE_CRITICAL_MISSING',
+          solution: `Add "${entry}" to .gitignore`,
+        });
+        results.success = false;
+      }
+    }
+
+    // Check node_modules - it's critical but accepts variations
+    if (!hasGitignoreEntry(lines, 'node_modules')) {
+      results.errors.push({
+        severity: 'high',
+        message: '.gitignore missing critical entry: node_modules',
+        file: gitignorePath,
+        code: 'GITIGNORE_CRITICAL_MISSING',
+        solution: 'Add "node_modules" or "node_modules/" to .gitignore',
+      });
+      results.success = false;
+    }
+
+    // Check recommended entries
+    for (const entry of recommendedEntries) {
+      const hasEntry = lines.some(line => {
+        if (entry.includes('*')) {
+          const pattern = entry.replace(/\*/g, '.*');
+          return new RegExp(`^${pattern}$`).test(line);
+        }
+        return hasGitignoreEntry(lines, entry);
+      });
+
+      if (!hasEntry) {
+        results.warnings.push({
+          severity: 'low',
+          message: `.gitignore missing recommended entry: ${entry}`,
+          file: gitignorePath,
+          code: 'GITIGNORE_RECOMMENDED_MISSING',
+        });
+      }
+    }
+
+    results.checks.push({
+      component: 'Git Ignore',
+      file: gitignorePath,
+      status: 'success',
+      message: 'Validated',
+    });
+  } catch (error) {
+    results.warnings.push({
+      severity: 'medium',
+      message: `.gitignore validation failed: ${error.message}`,
+      file: gitignorePath,
+    });
+  }
+}
+
+module.exports = {
+  validateConfigs,
+};
+
+