qa360 2.1.7 → 2.2.0

package/packages/mcp/src/cli/cli.ts

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+
+/**
+ * QA360 MCP CLI - Zero-Friction Developer Experience
+ * From zero to usable QA360 tools inside  in < 3 minutes
+ */
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { createRequire } from 'node:module';
+import { initCommand } from './init.js';
+import { upCommand } from './up.js';
+import { doctorCommand } from './doctor.js';
+import { fixCommand } from './fix.js';
+import { uninstallCommand } from './uninstall.js';
+import { resetCommand } from './reset.js';
+import { testDxCommand } from './test-dx.js';
+import { telemetryCommand } from './telemetry.js';
+
+// Load version from package.json
+const require = createRequire(import.meta.url);
+const { version, name } = require('../../package.json');
+
+const program = new Command();
+
+program
+  .name('qa360-mcp')
+  .description('QA360 MCP CLI - Zero-friction  integration')
+  .version(version);
+
+// Banner
+console.log(chalk.bold.blue(`\n🧠 ${name} v${version}`));
+console.log(chalk.gray('From zero to usable QA360 tools in < 3 minutes\n'));
+
+// init command
+program
+  .command('init [target]')
+  .description('Configure VS Code +  for QA360 MCP')
+  .option('--vscode', 'Target VS Code settings.json (default)')
+  .option('--force', 'Overwrite existing configuration')
+  .option('--non-interactive', 'Skip interactive prompts (CI mode)')
+  .action(async (target, options) => {
+    await initCommand(target || 'vscode', options);
+  });
+
+// up command
+program
+  .command('up')
+  .description('Start QA360 MCP Server')
+  .option('--stdio', 'Use stdio transport (default for )', true)
+  .option('--port <number>', 'Use HTTP transport on specified port')
+  .option('--allow-run', 'Enable qa360.run tool (requires explicit opt-in)')
+  .option('--allow-secrets', 'Enable secrets management tools')
+  .option('--verbose', 'Verbose logging')
+  .option('--debug', 'Show debug information (command, port, cwd)')
+  .action(async (options) => {
+    await upCommand(options);
+  });
+
+// serve alias for up
+program
+  .command('serve')
+  .description('Alias for "up" command')
+  .option('--stdio', 'Use stdio transport (default)', true)
+  .option('--port <number>', 'Use HTTP transport on specified port')
+  .option('--allow-run', 'Enable qa360.run tool')
+  .option('--allow-secrets', 'Enable secrets management tools')
+  .option('--verbose', 'Verbose logging')
+  .action(async (options) => {
+    await upCommand(options);
+  });
+
+// doctor command
+program
+  .command('doctor')
+  .description('Check QA360 MCP setup health')
+  .option('--verbose', 'Show detailed diagnostics')
+  .option('--json', 'Output results as JSON (for CI integration)')
+  .action(async (options) => {
+    await doctorCommand(options);
+  });
+
+// fix command
+program
+  .command('fix')
+  .description('Repair QA360 MCP configuration and dependencies')
+  .option('--force', 'Force reinstall all dependencies')
+  .action(async (options) => {
+    await fixCommand(options);
+  });
+
+// reset command
+program
+  .command('reset')
+  .description('Clean all QA360 MCP configurations and start fresh')
+  .option('--yes', 'Skip confirmation prompt')
+  .action(async (options) => {
+    await resetCommand(options);
+  });
+
+// uninstall command
+program
+  .command('uninstall')
+  .description('Remove QA360 MCP completely')
+  .option('--yes', 'Skip confirmation prompt')
+  .action(async (options) => {
+    await uninstallCommand(options);
+  });
+
+// test:dx command
+program
+  .command('test:dx')
+  .description('Run DX compliance tests (simulates fresh install)')
+  .option('--ci', 'CI mode (exit with code on failure)')
+  .action(async (options) => {
+    await testDxCommand(options);
+  });
+
+// telemetry command
+program
+  .command('telemetry <action>')
+  .description('Manage opt-in telemetry (on|off|status)')
+  .action(async (action, options) => {
+    await telemetryCommand(action, options);
+  });
+
+// Parse arguments
+program.parse();
+
+// Show help if no command
+if (!process.argv.slice(2).length) {
+  console.log(chalk.yellow('Quick start:'));
+  console.log(chalk.white('  1. qa360-mcp init     # Configure VS Code'));
+  console.log(chalk.white('  2. qa360-mcp up       # Start MCP server'));
+  console.log(chalk.white('  3. Open  and try: /qa360.health\n'));
+  program.outputHelp();
+}

package/packages/mcp/src/cli/doctor.ts

@@ -0,0 +1,286 @@
+/**
+ * qa360-mcp doctor - Health check and diagnostics
+ */
+
+import chalk from 'chalk';
+import ora from 'ora';
+import semver from 'semver';
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+
+const execAsync = promisify(exec);
+
+interface DoctorOptions {
+  verbose?: boolean;
+  json?: boolean;
+}
+
+interface CheckResult {
+  name: string;
+  status: 'ok' | 'warn' | 'error';
+  message: string;
+  fix?: string;
+}
+
+export async function doctorCommand(options: DoctorOptions): Promise<void> {
+  if (!options.json) {
+    console.log(chalk.blue.bold('\n🔍 QA360 Doctor - System Health Check\n'));
+  }
+
+  const results: CheckResult[] = [];
+
+  // 1. Check Node.js version
+  const nodeCheck = await checkNodeVersion();
+  results.push(nodeCheck);
+  if (!options.json) printCheck(nodeCheck);
+
+  // 2. Check package manager
+  const pmCheck = await checkPackageManager();
+  results.push(pmCheck);
+  if (!options.json) printCheck(pmCheck);
+
+  // 3. Check VS Code
+  const vscodeCheck = await checkVSCode();
+  results.push(vscodeCheck);
+  if (!options.json) printCheck(vscodeCheck);
+
+  // 4. Check  extension
+  const claudeCheck = await check();
+  results.push(claudeCheck);
+  if (!options.json) printCheck(claudeCheck);
+
+  // 5. Check MCP Server
+  const mcpCheck = await checkMCPServer();
+  results.push(mcpCheck);
+  if (!options.json) printCheck(mcpCheck);
+
+  // 6. Check QA360 home directory
+  const homeCheck = await checkQA360Home();
+  results.push(homeCheck);
+  if (!options.json) printCheck(homeCheck);
+
+  // 7. Check permissions
+  const permCheck = await checkPermissions();
+  results.push(permCheck);
+  if (!options.json) printCheck(permCheck);
+
+  // Summary
+  const okCount = results.filter(r => r.status === 'ok').length;
+  const warnCount = results.filter(r => r.status === 'warn').length;
+  const errorCount = results.filter(r => r.status === 'error').length;
+
+  if (options.json) {
+    // JSON output for CI integration
+    const output = {
+      timestamp: new Date().toISOString(),
+      summary: {
+        total: results.length,
+        passed: okCount,
+        warnings: warnCount,
+        errors: errorCount,
+        status: errorCount > 0 ? 'error' : warnCount > 0 ? 'warn' : 'ok'
+      },
+      checks: results
+    };
+    console.log(JSON.stringify(output, null, 2));
+    process.exit(errorCount > 0 ? 1 : 0);
+  } else {
+    // Human-readable output
+    console.log(chalk.white('\n' + '─'.repeat(60) + '\n'));
+    console.log(chalk.white('Summary:'));
+    console.log(chalk.green(`  ✅ ${okCount} checks passed`));
+    if (warnCount > 0) console.log(chalk.yellow(`  ⚠️  ${warnCount} warnings`));
+    if (errorCount > 0) console.log(chalk.red(`  ❌ ${errorCount} errors`));
+
+    if (errorCount > 0) {
+      console.log(chalk.red.bold('\n❌ Issues detected\n'));
+      console.log(chalk.yellow('Run: qa360-mcp fix\n'));
+      process.exit(1);
+    } else if (warnCount > 0) {
+      console.log(chalk.yellow.bold('\n⚠️  Some warnings detected\n'));
+    } else {
+      console.log(chalk.green.bold('\n✅ All checks passed!\n'));
+    }
+  }
+}
+
+function printCheck(result: CheckResult): void {
+  const icon = result.status === 'ok' ? chalk.green('✅') 
+    : result.status === 'warn' ? chalk.yellow('⚠️ ') 
+    : chalk.red('❌');
+  
+  console.log(`${icon} ${chalk.white(result.name)}: ${result.message}`);
+  
+  if (result.fix && result.status !== 'ok') {
+    console.log(chalk.gray(`   → ${result.fix}`));
+  }
+}
+
+async function checkNodeVersion(): Promise<CheckResult> {
+  const version = process.version;
+  const minVersion = '18.0.0';
+  
+  if (semver.gte(version, minVersion)) {
+    return {
+      name: 'Node.js',
+      status: 'ok',
+      message: `${version} (>= ${minVersion})`
+    };
+  } else {
+    return {
+      name: 'Node.js',
+      status: 'error',
+      message: `${version} (requires >= ${minVersion})`,
+      fix: 'Install Node.js 18+: https://nodejs.org/ or use nvm install 22'
+    };
+  }
+}
+
+async function checkPackageManager(): Promise<CheckResult> {
+  try {
+    const { stdout } = await execAsync('npm --version');
+    return {
+      name: 'Package Manager',
+      status: 'ok',
+      message: `npm ${stdout.trim()}`
+    };
+  } catch {
+    return {
+      name: 'Package Manager',
+      status: 'error',
+      message: 'npm not found',
+      fix: 'Install Node.js which includes npm'
+    };
+  }
+}
+
+async function checkVSCode(): Promise<CheckResult> {
+  const home = os.homedir();
+  const platform = os.platform();
+  
+  const settingsPaths = [
+    path.join(home, 'Library', 'Application Support', 'Code', 'User', 'settings.json'),
+    path.join(home, '.config', 'Code', 'User', 'settings.json'),
+    path.join(home, 'AppData', 'Roaming', 'Code', 'User', 'settings.json')
+  ];
+
+  for (const p of settingsPaths) {
+    if (await fs.pathExists(p)) {
+      return {
+        name: 'VS Code',
+        status: 'ok',
+        message: 'Detected'
+      };
+    }
+  }
+
+  return {
+    name: 'VS Code',
+    status: 'warn',
+    message: 'Not detected (optional)',
+    fix: 'Install VS Code: https://code.visualstudio.com/'
+  };
+}
+
+async function check(): Promise<CheckResult> {
+  const home = os.homedir();
+  const extPath = path.join(home, '.vscode', 'extensions');
+  
+  if (await fs.pathExists(extPath)) {
+    const extensions = await fs.readdir(extPath);
+    const claudeExt = extensions.find(ext => ext.includes('anthropic.claude'));
+    
+    if (claudeExt) {
+      return {
+        name: '',
+        status: 'ok',
+        message: 'Extension detected'
+      };
+    }
+  }
+
+  return {
+    name: '',
+    status: 'warn',
+    message: 'Extension not detected',
+    fix: 'Install: https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code'
+  };
+}
+
+async function checkMCPServer(): Promise<CheckResult> {
+  // Check if qa360-mcp-server binary is available (built-in minimal server)
+  try {
+    await execAsync('which qa360-mcp-server');
+    return {
+      name: 'MCP Server',
+      status: 'ok',
+      message: 'Built-in server available'
+    };
+  } catch {
+    // Binary not found, check for external server
+    const possiblePaths = [
+      path.join(process.cwd(), '../../mcp-server-qa360/dist/index.js'),
+      path.join(process.env.HOME || '', '.npm-global/lib/node_modules/@qa360/mcp-server/dist/index.js'),
+      path.join(process.cwd(), 'node_modules/@qa360/mcp-server/dist/index.js')
+    ];
+
+    for (const p of possiblePaths) {
+      if (await fs.pathExists(p)) {
+        return {
+          name: 'MCP Server',
+          status: 'ok',
+          message: 'External server installed'
+        };
+      }
+    }
+
+    return {
+      name: 'MCP Server',
+      status: 'error',
+      message: 'Server not found',
+      fix: 'Run: qa360-mcp fix'
+    };
+  }
+}
+
+async function checkQA360Home(): Promise<CheckResult> {
+  const qa360Home = process.env.QA360_HOME || path.join(os.homedir(), '.qa360');
+  
+  if (await fs.pathExists(qa360Home)) {
+    return {
+      name: 'QA360 Home',
+      status: 'ok',
+      message: qa360Home
+    };
+  } else {
+    await fs.ensureDir(qa360Home);
+    return {
+      name: 'QA360 Home',
+      status: 'ok',
+      message: `Created: ${qa360Home}`
+    };
+  }
+}
+
+async function checkPermissions(): Promise<CheckResult> {
+  const qa360Home = process.env.QA360_HOME || path.join(os.homedir(), '.qa360');
+  
+  try {
+    await fs.access(qa360Home, fs.constants.W_OK);
+    return {
+      name: 'Permissions',
+      status: 'ok',
+      message: 'Write access OK'
+    };
+  } catch {
+    return {
+      name: 'Permissions',
+      status: 'error',
+      message: 'No write access to QA360 home',
+      fix: `chmod +w ${qa360Home}`
+    };
+  }
+}

package/packages/mcp/src/cli/fix.ts

@@ -0,0 +1,99 @@
+/**
+ * qa360-mcp fix - Auto-repair configuration and dependencies
+ */
+
+import chalk from 'chalk';
+import ora from 'ora';
+import { execa } from 'execa';
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+
+interface FixOptions {
+  force?: boolean;
+}
+
+export async function fixCommand(options: FixOptions): Promise<void> {
+  console.log(chalk.blue.bold('\n🔧 QA360 MCP Fix - Auto-Repair\n'));
+
+  const spinner = ora('Starting repair process').start();
+
+  try {
+    // 1. Clean cache
+    spinner.text = 'Cleaning npm cache';
+    await execa('npm', ['cache', 'clean', '--force']);
+    spinner.succeed('Cache cleaned');
+
+    // 2. Ensure QA360 home directory
+    spinner.start('Checking QA360 home directory');
+    const qa360Home = process.env.QA360_HOME || path.join(os.homedir(), '.qa360');
+    await fs.ensureDir(qa360Home);
+    await fs.chmod(qa360Home, 0o755);
+    spinner.succeed(`QA360 home ready: ${qa360Home}`);
+
+    // 3. Reinstall dependencies (if in dev mode)
+    if (options.force) {
+      spinner.start('Reinstalling dependencies');
+      try {
+        await execa('npm', ['install', '--force'], { cwd: process.cwd() });
+        spinner.succeed('Dependencies reinstalled');
+      } catch {
+        spinner.warn('Could not reinstall dependencies (not in dev mode)');
+      }
+    }
+
+    // 4. Verify MCP server
+    spinner.start('Verifying MCP server');
+    const serverInstalled = await verifyMCPServer();
+    if (serverInstalled) {
+      spinner.succeed('MCP server verified');
+    } else {
+      spinner.warn('MCP server not found (install @qa360/mcp-server)');
+    }
+
+    // 5. Fix VS Code settings if corrupted
+    spinner.start('Checking VS Code settings');
+    await fixVSCodeSettings();
+    spinner.succeed('VS Code settings checked');
+
+    console.log(chalk.green.bold('\n✅ Repair completed!\n'));
+    console.log(chalk.white('Run: qa360-mcp doctor\n'));
+
+  } catch (error) {
+    spinner.fail('Repair failed');
+    console.error(chalk.red('\n❌ Error:'), error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+}
+
+async function verifyMCPServer(): Promise<boolean> {
+  const possiblePaths = [
+    path.join(process.cwd(), '../../mcp-server-qa360/dist/index.js'),
+    path.join(process.env.HOME || '', '.npm-global/lib/node_modules/@qa360/mcp-server/dist/index.js'),
+    path.join(process.cwd(), 'node_modules/@qa360/mcp-server/dist/index.js')
+  ];
+
+  for (const p of possiblePaths) {
+    if (await fs.pathExists(p)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+async function fixVSCodeSettings(): Promise<void> {
+  const home = os.homedir();
+  const settingsPath = path.join(home, 'Library', 'Application Support', 'Code', 'User', 'settings.json');
+  
+  if (await fs.pathExists(settingsPath)) {
+    try {
+      const content = await fs.readFile(settingsPath, 'utf-8');
+      JSON.parse(content); // Validate JSON
+    } catch {
+      // Backup corrupted file
+      const backupPath = `${settingsPath}.corrupted.${Date.now()}.json`;
+      await fs.copy(settingsPath, backupPath);
+      await fs.writeFile(settingsPath, '{}', 'utf-8');
+    }
+  }
+}