create-qa-architect 5.0.0

package/lib/error-reporter.js

@@ -0,0 +1,444 @@
+#!/usr/bin/env node
+
+/**
+ * Error reporting module for crash analytics (opt-in only)
+ *
+ * Privacy principles:
+ * - Completely opt-in (prompt on error or ENV var)
+ * - No personal information collected (paths/usernames sanitized)
+ * - Local storage primary (optional remote sync)
+ * - Easy to inspect and delete
+ * - User can add context/comments
+ *
+ * Data collected:
+ * - Error category (dependency, permission, config, validation, network)
+ * - Error type and sanitized message
+ * - Sanitized stack trace (paths removed)
+ * - Node version and OS platform
+ * - Operation attempted (setup, validate, deps)
+ * - Optional user comment/context
+ */
+
+const fs = require('fs')
+const path = require('path')
+const os = require('os')
+const crypto = require('crypto')
+const { REPORTING_LIMITS } = require('../config/constants')
+
+const ERROR_REPORTS_DIR =
+  process.env.QAA_ERROR_DIR || path.join(os.homedir(), '.create-qa-architect')
+const ERROR_REPORTS_FILE = path.join(ERROR_REPORTS_DIR, 'error-reports.json')
+const MAX_REPORTS = REPORTING_LIMITS.MAX_ERROR_REPORTS
+
+/**
+ * Error categories for classification
+ */
+const ErrorCategory = {
+  DEPENDENCY_ERROR: 'DEPENDENCY_ERROR', // npm install, missing packages
+  PERMISSION_ERROR: 'PERMISSION_ERROR', // EACCES, EPERM
+  CONFIGURATION_ERROR: 'CONFIGURATION_ERROR', // Invalid configs
+  VALIDATION_ERROR: 'VALIDATION_ERROR', // ESLint/Prettier failures
+  NETWORK_ERROR: 'NETWORK_ERROR', // npm registry, git
+  UNKNOWN_ERROR: 'UNKNOWN_ERROR', // Uncategorized
+}
+
+/**
+ * Check if error reporting is enabled
+ * Can be enabled via ENV var or interactive prompt
+ */
+function isErrorReportingEnabled() {
+  const envEnabled =
+    process.env.QAA_ERROR_REPORTING === 'true' ||
+    process.env.QAA_ERROR_REPORTING === '1'
+
+  return envEnabled
+}
+
+/**
+ * Categorize error based on error message and code
+ */
+function categorizeError(error) {
+  const message = error?.message?.toLowerCase() || ''
+  const code = error?.code || ''
+
+  // Permission errors
+  if (code === 'EACCES' || code === 'EPERM' || message.includes('permission')) {
+    return ErrorCategory.PERMISSION_ERROR
+  }
+
+  // Dependency errors
+  if (
+    message.includes('npm install') ||
+    message.includes('cannot find module') ||
+    message.includes('module not found') ||
+    code === 'MODULE_NOT_FOUND'
+  ) {
+    return ErrorCategory.DEPENDENCY_ERROR
+  }
+
+  // Network errors
+  if (
+    code === 'ENOTFOUND' ||
+    code === 'ETIMEDOUT' ||
+    code === 'ECONNREFUSED' ||
+    message.includes('network') ||
+    message.includes('registry')
+  ) {
+    return ErrorCategory.NETWORK_ERROR
+  }
+
+  // Configuration errors
+  if (
+    message.includes('package.json') ||
+    message.includes('invalid config') ||
+    message.includes('parse error') ||
+    message.includes('syntax error')
+  ) {
+    return ErrorCategory.CONFIGURATION_ERROR
+  }
+
+  // Validation errors
+  if (
+    message.includes('eslint') ||
+    message.includes('prettier') ||
+    message.includes('stylelint') ||
+    message.includes('validation failed')
+  ) {
+    return ErrorCategory.VALIDATION_ERROR
+  }
+
+  return ErrorCategory.UNKNOWN_ERROR
+}
+
+/**
+ * Sanitize file path to remove personal information
+ */
+function sanitizePath(filePath) {
+  if (!filePath || typeof filePath !== 'string') return filePath
+
+  // Remove username from common paths
+  const homeDir = os.homedir()
+  const sanitized = filePath.replace(homeDir, '/Users/<redacted>')
+
+  // Remove common user-specific directories
+  return sanitized
+    .replace(/\/Users\/[^/]+/g, '/Users/<redacted>')
+    .replace(/\/home\/[^/]+/g, '/home/<redacted>')
+    .replace(/C:\\Users\\[^\\]+/g, 'C:\\Users\\<redacted>')
+}
+
+/**
+ * Sanitize error message to remove personal information
+ */
+function sanitizeMessage(message) {
+  if (!message || typeof message !== 'string') return message
+
+  let sanitized = message
+
+  // Remove file paths
+  sanitized = sanitizePath(sanitized)
+
+  // Remove git URLs with tokens
+  sanitized = sanitized.replace(
+    /https:\/\/[^@]+@github\.com/g,
+    'https://<token>@github.com'
+  )
+
+  // Remove email addresses
+  sanitized = sanitized.replace(
+    /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/g,
+    '<email>'
+  )
+
+  return sanitized
+}
+
+/**
+ * Sanitize stack trace to remove personal information
+ */
+function sanitizeStackTrace(stack) {
+  if (!stack || typeof stack !== 'string') return stack
+
+  return stack
+    .split('\n')
+    .map(line => sanitizePath(line))
+    .join('\n')
+}
+
+/**
+ * Generate unique error report ID
+ */
+function generateReportId() {
+  return crypto.randomBytes(8).toString('hex')
+}
+
+/**
+ * Ensure error reports directory exists
+ */
+function ensureErrorReportsDir() {
+  if (!fs.existsSync(ERROR_REPORTS_DIR)) {
+    fs.mkdirSync(ERROR_REPORTS_DIR, { recursive: true, mode: 0o700 })
+  }
+}
+
+/**
+ * Load existing error reports
+ */
+function loadErrorReports() {
+  try {
+    if (fs.existsSync(ERROR_REPORTS_FILE)) {
+      const data = fs.readFileSync(ERROR_REPORTS_FILE, 'utf8')
+      return JSON.parse(data)
+    }
+  } catch {
+    // If corrupted, start fresh
+    console.warn('⚠️  Error reports data corrupted, starting fresh')
+  }
+
+  return {
+    version: 1,
+    reports: [],
+  }
+}
+
+/**
+ * Save error reports (with rotation)
+ */
+function saveErrorReports(data) {
+  try {
+    ensureErrorReportsDir()
+
+    // Rotate: keep only last MAX_REPORTS
+    if (data.reports.length > MAX_REPORTS) {
+      data.reports = data.reports.slice(-MAX_REPORTS)
+    }
+
+    fs.writeFileSync(
+      ERROR_REPORTS_FILE,
+      JSON.stringify(data, null, 2),
+      { mode: 0o600 } // Owner read/write only
+    )
+  } catch (error) {
+    // Silently fail - error reporting should never break the tool
+    if (process.env.DEBUG) {
+      console.error('Error reporting save failed:', error.message)
+    }
+  }
+}
+
+/**
+ * Error reporter for capturing and analyzing crashes
+ */
+class ErrorReporter {
+  constructor(operation = 'unknown') {
+    this.operation = operation
+    this.enabled = isErrorReportingEnabled()
+  }
+
+  /**
+   * Capture and report an error
+   *
+   * @param {Error} error - The error to report
+   * @param {object} context - Additional context
+   * @param {string} userComment - Optional user comment
+   */
+  captureError(error, context = {}, userComment = null) {
+    if (!this.enabled && !context.forceCapture) {
+      return null
+    }
+
+    try {
+      const data = loadErrorReports()
+
+      const category = categorizeError(error)
+      const reportId = generateReportId()
+
+      const report = {
+        id: reportId,
+        timestamp: new Date().toISOString(),
+        category,
+        errorType: error?.constructor?.name || 'Error',
+        message: sanitizeMessage(error?.message || 'Unknown error'),
+        sanitizedStack: sanitizeStackTrace(error?.stack || ''),
+        operation: this.operation,
+        context: {
+          nodeVersion: process.version,
+          platform: os.platform(),
+          arch: os.arch(),
+          ...context,
+        },
+        userComment: userComment || null,
+      }
+
+      data.reports.push(report)
+      saveErrorReports(data)
+
+      return reportId
+    } catch (captureError) {
+      // Silently fail - error reporting should never break the tool
+      if (process.env.DEBUG) {
+        console.error('Error capture failed:', captureError.message)
+      }
+      return null
+    }
+  }
+
+  /**
+   * Get friendly error message for user
+   */
+  getFriendlyMessage(error) {
+    const category = categorizeError(error)
+
+    const messages = {
+      [ErrorCategory.DEPENDENCY_ERROR]: {
+        title: '📦 Dependency Issue',
+        suggestion: 'Try running: npm install\nOr check your package.json file',
+      },
+      [ErrorCategory.PERMISSION_ERROR]: {
+        title: '🔒 Permission Denied',
+        suggestion:
+          'Try running with appropriate permissions or check file ownership',
+      },
+      [ErrorCategory.CONFIGURATION_ERROR]: {
+        title: '⚙️  Configuration Error',
+        suggestion: 'Check your configuration files for syntax errors',
+      },
+      [ErrorCategory.VALIDATION_ERROR]: {
+        title: '✅ Validation Failed',
+        suggestion:
+          'Review the validation errors above and fix them before continuing',
+      },
+      [ErrorCategory.NETWORK_ERROR]: {
+        title: '🌐 Network Issue',
+        suggestion: 'Check your internet connection and try again',
+      },
+      [ErrorCategory.UNKNOWN_ERROR]: {
+        title: '❌ Unexpected Error',
+        suggestion: 'Please report this issue with the error details below',
+      },
+    }
+
+    return messages[category] || messages[ErrorCategory.UNKNOWN_ERROR]
+  }
+
+  /**
+   * Show error report prompt to user
+   */
+  async promptErrorReport(error) {
+    const friendly = this.getFriendlyMessage(error)
+
+    console.error('\n' + '━'.repeat(60))
+    console.error(`${friendly.title}`)
+    console.error('━'.repeat(60))
+    console.error(`Error: ${error?.message || 'Unknown error'}`)
+    console.error(`\n💡 Suggestion: ${friendly.suggestion}`)
+    console.error('━'.repeat(60))
+
+    if (!this.enabled) {
+      console.log('\n📊 Help improve this tool by reporting errors')
+      console.log('Enable error reporting: export QAA_ERROR_REPORTING=true')
+      console.log(`Report will be saved locally at: ${ERROR_REPORTS_FILE}`)
+    }
+  }
+}
+
+/**
+ * Get error report statistics
+ */
+function getErrorReportStats() {
+  const data = loadErrorReports()
+
+  const stats = {
+    totalReports: data.reports.length,
+    byCategory: {},
+    byPlatform: {},
+    byNodeVersion: {},
+    recentReports: data.reports.slice(-10),
+  }
+
+  data.reports.forEach(report => {
+    // Count by category
+    stats.byCategory[report.category] =
+      (stats.byCategory[report.category] || 0) + 1
+
+    // Count by platform
+    const platform = report.context?.platform || 'unknown'
+    stats.byPlatform[platform] = (stats.byPlatform[platform] || 0) + 1
+
+    // Count by Node version
+    const nodeVersion = report.context?.nodeVersion || 'unknown'
+    stats.byNodeVersion[nodeVersion] =
+      (stats.byNodeVersion[nodeVersion] || 0) + 1
+  })
+
+  return stats
+}
+
+/**
+ * Clear all error reports
+ */
+function clearErrorReports() {
+  try {
+    if (fs.existsSync(ERROR_REPORTS_FILE)) {
+      fs.unlinkSync(ERROR_REPORTS_FILE)
+      return true
+    }
+    return false
+  } catch (error) {
+    console.error('Failed to clear error reports:', error.message)
+    return false
+  }
+}
+
+/**
+ * Show error reporting status
+ */
+function showErrorReportingStatus() {
+  const enabled = isErrorReportingEnabled()
+
+  console.log('\n📊 Error Reporting Status')
+  console.log('─'.repeat(50))
+  console.log(
+    `Status: ${enabled ? '✅ Enabled' : '❌ Disabled (opt-in required)'}`
+  )
+
+  if (enabled) {
+    const stats = getErrorReportStats()
+    console.log(`Total error reports: ${stats.totalReports}`)
+    console.log(`Storage: ${ERROR_REPORTS_FILE}`)
+
+    if (stats.totalReports > 0) {
+      console.log('\nBy Category:')
+      Object.entries(stats.byCategory).forEach(([category, count]) => {
+        console.log(`  ${category}: ${count}`)
+      })
+    }
+  } else {
+    console.log('\nTo enable error reporting (opt-in):')
+    console.log('  export QAA_ERROR_REPORTING=true')
+    console.log('  # or add to ~/.bashrc or ~/.zshrc')
+    console.log('\nWhy enable error reporting?')
+    console.log('  - Helps identify common issues and failure patterns')
+    console.log('  - All data stays local (no network calls)')
+    console.log('  - No personal information collected (paths sanitized)')
+    console.log(
+      '  - Easy to inspect: cat ~/.create-qa-architect/error-reports.json'
+    )
+  }
+
+  console.log('─'.repeat(50))
+}
+
+module.exports = {
+  ErrorReporter,
+  ErrorCategory,
+  isErrorReportingEnabled,
+  categorizeError,
+  sanitizePath,
+  sanitizeMessage,
+  sanitizeStackTrace,
+  getErrorReportStats,
+  clearErrorReports,
+  showErrorReportingStatus,
+  ERROR_REPORTS_FILE,
+}

package/lib/interactive/prompt.js

@@ -0,0 +1,128 @@
+'use strict'
+
+const readline = require('readline')
+
+/**
+ * Interactive prompt utility using Node.js readline
+ * Handles user input with TTY detection for CI safety
+ */
+class InteractivePrompt {
+  constructor(options = {}) {
+    this.input = options.input || process.stdin
+    this.output = options.output || process.stdout
+  }
+
+  /**
+   * Check if running in a TTY environment
+   * @returns {boolean} True if TTY (interactive terminal)
+   */
+  isTTY() {
+    return Boolean(this.input.isTTY && this.output.isTTY)
+  }
+
+  /**
+   * Ask a single question and get user input
+   * @param {string} question - The question to ask
+   * @returns {Promise<string>} User's answer
+   */
+  async ask(question) {
+    if (!this.isTTY()) {
+      throw new Error('Interactive mode requires a TTY environment')
+    }
+
+    return new Promise((resolve, reject) => {
+      const rl = readline.createInterface({
+        input: this.input,
+        output: this.output,
+      })
+
+      rl.question(question, answer => {
+        rl.close()
+        resolve(answer.trim())
+      })
+
+      rl.on('SIGINT', () => {
+        rl.close()
+        reject(new Error('User cancelled interactive mode'))
+      })
+    })
+  }
+
+  /**
+   * Ask a yes/no question
+   * @param {string} question - The question to ask
+   * @param {boolean} defaultValue - Default value if user just presses Enter
+   * @returns {Promise<boolean>} True for yes, false for no
+   */
+  async confirm(question, defaultValue = false) {
+    const defaultHint = defaultValue ? ' [Y/n]' : ' [y/N]'
+    const answer = await this.ask(question + defaultHint + ' ')
+
+    if (answer === '') {
+      return defaultValue
+    }
+
+    const normalized = answer.toLowerCase()
+    return normalized === 'y' || normalized === 'yes'
+  }
+
+  /**
+   * Present a multiple choice question
+   * @param {string} question - The question to ask
+   * @param {Array<{value: string, label: string}>} choices - Available choices
+   * @returns {Promise<string>} Selected choice value
+   */
+  async select(question, choices) {
+    const choiceList = choices
+      .map((choice, index) => `  ${index + 1}) ${choice.label}`)
+      .join('\n')
+
+    const fullQuestion = `${question}\n${choiceList}\n\nEnter your choice (1-${choices.length}): `
+    const answer = await this.ask(fullQuestion)
+
+    const choiceIndex = parseInt(answer, 10) - 1
+    if (
+      isNaN(choiceIndex) ||
+      choiceIndex < 0 ||
+      choiceIndex >= choices.length
+    ) {
+      throw new Error(
+        `Invalid choice: ${answer}. Please enter a number between 1 and ${choices.length}`
+      )
+    }
+
+    return choices[choiceIndex].value
+  }
+
+  /**
+   * Present a multi-select question (checkboxes)
+   * @param {string} question - The question to ask
+   * @param {Array<{value: string, label: string}>} choices - Available choices
+   * @returns {Promise<Array<string>>} Array of selected choice values
+   */
+  async multiSelect(question, choices) {
+    const choiceList = choices
+      .map((choice, index) => `  ${index + 1}) ${choice.label}`)
+      .join('\n')
+
+    const fullQuestion =
+      `${question}\n${choiceList}\n\n` +
+      `Enter your choices (comma-separated, e.g., "1,3,5" or press Enter for none): `
+
+    const answer = await this.ask(fullQuestion)
+
+    if (answer === '') {
+      return []
+    }
+
+    const selections = answer
+      .split(',')
+      .map(s => s.trim())
+      .map(s => parseInt(s, 10) - 1)
+      .filter(index => !isNaN(index) && index >= 0 && index < choices.length)
+
+    return selections.map(index => choices[index].value)
+  }
+}
+
+module.exports = { InteractivePrompt }

package/lib/interactive/questions.js

@@ -0,0 +1,146 @@
+'use strict'
+
+/**
+ * Question definitions and answer parsing for interactive mode
+ */
+
+/**
+ * Generate question definitions for interactive flow
+ * @returns {Array<Object>} Array of question objects
+ */
+function generateQuestions() {
+  return [
+    {
+      name: 'operationMode',
+      type: 'select',
+      message: 'What would you like to do?',
+      choices: [
+        {
+          value: 'setup',
+          label: 'Full quality automation setup (recommended)',
+        },
+        { value: 'update', label: 'Update existing configuration' },
+        { value: 'validate', label: 'Run validation checks only' },
+      ],
+    },
+    {
+      name: 'dependencyMonitoring',
+      type: 'confirm',
+      message: 'Include basic dependency monitoring (Free Tier)?',
+      default: true,
+    },
+    {
+      name: 'dryRun',
+      type: 'confirm',
+      message: 'Preview changes without modifying files (dry-run mode)?',
+      default: false,
+    },
+    {
+      name: 'toolExclusions',
+      type: 'multiSelect',
+      message: 'Disable any specific validation tools?',
+      choices: [
+        {
+          value: 'npm-audit',
+          label: 'npm audit (dependency vulnerability checks)',
+        },
+        { value: 'gitleaks', label: 'gitleaks (secret scanning)' },
+        {
+          value: 'actionlint',
+          label: 'actionlint (GitHub Actions workflow validation)',
+        },
+        {
+          value: 'markdownlint',
+          label: 'markdownlint (markdown formatting checks)',
+        },
+        { value: 'eslint-security', label: 'ESLint security rules' },
+      ],
+    },
+  ]
+}
+
+/**
+ * Parse user answers into CLI flags
+ * @param {Object} answers - User's answers to questions
+ * @returns {Array<string>} Array of CLI flags
+ */
+function parseAnswers(answers) {
+  const flags = []
+
+  // Operation mode
+  if (answers.operationMode === 'update') {
+    flags.push('--update')
+  } else if (answers.operationMode === 'validate') {
+    flags.push('--comprehensive')
+  }
+  // 'setup' mode is default (no flag needed)
+
+  // Dependency monitoring
+  if (answers.dependencyMonitoring) {
+    flags.push('--deps')
+  }
+
+  // Dry-run mode
+  if (answers.dryRun) {
+    flags.push('--dry-run')
+  }
+
+  // Tool exclusions
+  if (Array.isArray(answers.toolExclusions)) {
+    answers.toolExclusions.forEach(tool => {
+      flags.push(`--no-${tool}`)
+    })
+  }
+
+  return flags
+}
+
+/**
+ * Run interactive prompt flow
+ * @param {InteractivePrompt} prompt - Prompt instance
+ * @returns {Promise<Array<string>>} Array of CLI flags based on answers
+ */
+async function runInteractiveFlow(prompt) {
+  const questions = generateQuestions()
+  const answers = {}
+
+  console.log('\n🚀 Interactive Quality Automation Setup\n')
+
+  for (const question of questions) {
+    try {
+      if (question.type === 'confirm') {
+        answers[question.name] = await prompt.confirm(
+          question.message,
+          question.default
+        )
+      } else if (question.type === 'select') {
+        answers[question.name] = await prompt.select(
+          question.message,
+          question.choices
+        )
+      } else if (question.type === 'multiSelect') {
+        answers[question.name] = await prompt.multiSelect(
+          question.message,
+          question.choices
+        )
+      }
+    } catch (error) {
+      // Handle user cancellation or other errors
+      if (error.message.includes('cancelled')) {
+        console.log('\n\n❌ Interactive mode cancelled by user\n')
+        process.exit(0)
+      }
+      throw error
+    }
+  }
+
+  console.log('\n✅ Configuration complete!\n')
+
+  return parseAnswers(answers)
+}
+
+module.exports = {
+  generateQuestions,
+  parseAnswers,
+  runInteractiveFlow,
+}