qaa-agent 1.9.2 → 1.9.5

package/bin/install.cjs

@@ -1,253 +1,375 @@
-#!/usr/bin/env node
-
-/**
- * QAA Agent Installer
- *
- * Installs QAA (QA Automation Agent) into the user's Claude Code environment.
- *
- * What it does:
- *   1. Copies agents, commands, skills, templates, workflows, docs, bin, and config files
- *      to the chosen install directory (global ~/.claude/qaa or local ./.claude/qaa)
- *   2. Registers Playwright MCP and Context7 MCP as global MCP servers
- *   3. Merges required permissions into Claude Code settings.json
- *
- * Usage:
- *   npx qaa-agent
- */
-
-const fs = require('fs');
-const path = require('path');
-const readline = require('readline');
-const { execSync } = require('child_process');
-
-// ── Helpers ──────────────────────────────────────────────────────────────────
-
-function log(msg) { console.log(`  ${msg}`); }
-function success(msg) { console.log(`  ✓ ${msg}`); }
-function warn(msg) { console.log(`  ⚠ ${msg}`); }
-function fail(msg) { console.error(`  ✗ ${msg}`); }
-
-function ask(question) {
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise(resolve => {
-    rl.question(`  ${question} `, answer => {
-      rl.close();
-      resolve(answer.trim());
-    });
-  });
-}
-
-function copyDirRecursive(src, dest) {
-  if (!fs.existsSync(src)) return 0;
-  fs.mkdirSync(dest, { recursive: true });
-  let count = 0;
-  const entries = fs.readdirSync(src, { withFileTypes: true });
-  for (const entry of entries) {
-    const srcPath = path.join(src, entry.name);
-    const destPath = path.join(dest, entry.name);
-    if (entry.isDirectory()) {
-      count += copyDirRecursive(srcPath, destPath);
-    } else {
-      fs.copyFileSync(srcPath, destPath);
-      count++;
-    }
-  }
-  return count;
-}
-
-function deepMerge(target, source) {
-  for (const key of Object.keys(source)) {
-    if (
-      source[key] && typeof source[key] === 'object' && !Array.isArray(source[key]) &&
-      target[key] && typeof target[key] === 'object' && !Array.isArray(target[key])
-    ) {
-      deepMerge(target[key], source[key]);
-    } else if (Array.isArray(source[key]) && Array.isArray(target[key])) {
-      // Merge arrays without duplicates
-      const merged = [...new Set([...target[key], ...source[key]])];
-      target[key] = merged;
-    } else {
-      target[key] = source[key];
-    }
-  }
-  return target;
-}
-
-// ── MCP Registration ─────────────────────────────────────────────────────────
-
-function registerMcpServers(claudeJsonPath) {
-  const mcpServers = {
-    playwright: {
-      command: 'npx',
-      args: ['@playwright/mcp@latest']
-    },
-    context7: {
-      command: 'npx',
-      args: ['-y', '@upstash/context7-mcp@latest']
-    }
-  };
-
-  let config = {};
-  if (fs.existsSync(claudeJsonPath)) {
-    try {
-      config = JSON.parse(fs.readFileSync(claudeJsonPath, 'utf-8'));
-    } catch {
-      config = {};
-    }
-  }
-
-  if (!config.mcpServers) config.mcpServers = {};
-
-  let added = [];
-  for (const [name, serverConfig] of Object.entries(mcpServers)) {
-    if (!config.mcpServers[name]) {
-      config.mcpServers[name] = serverConfig;
-      added.push(name);
-    }
-  }
-
-  fs.writeFileSync(claudeJsonPath, JSON.stringify(config, null, 2) + '\n');
-  return added;
-}
-
-// ── Settings Merge ───────────────────────────────────────────────────────────
-
-function mergeSettings(installDir, packageDir) {
-  const srcSettings = path.join(packageDir, 'settings.json');
-  if (!fs.existsSync(srcSettings)) return false;
-
-  const claudeDir = path.dirname(installDir);
-  const destSettings = path.join(claudeDir, 'settings.json');
-
-  const source = JSON.parse(fs.readFileSync(srcSettings, 'utf-8'));
-
-  let target = {};
-  if (fs.existsSync(destSettings)) {
-    try {
-      target = JSON.parse(fs.readFileSync(destSettings, 'utf-8'));
-    } catch {
-      target = {};
-    }
-  }
-
-  deepMerge(target, source);
-  fs.writeFileSync(destSettings, JSON.stringify(target, null, 2) + '\n');
-  return true;
-}
-
-// ── Main ─────────────────────────────────────────────────────────────────────
-
-async function main() {
-  console.log('');
-  console.log('  ╔═══════════════════════════════════════╗');
-  console.log('  ║   QAA — QA Automation Agent Installer ║');
-  console.log('  ╚═══════════════════════════════════════╝');
-  console.log('');
-
-  // Determine package root (where the npm package files are)
-  const packageDir = path.resolve(__dirname, '..');
-
-  // Check that package files exist
-  const requiredDirs = ['agents', 'commands', 'skills'];
-  const missing = requiredDirs.filter(d => !fs.existsSync(path.join(packageDir, d)));
-  if (missing.length > 0) {
-    fail(`Package incomplete — missing: ${missing.join(', ')}`);
-    process.exit(1);
-  }
-
-  // Ask install scope
-  console.log('  Install scope:');
-  console.log('    1) Global  — ~/.claude/qaa  (available in all projects)');
-  console.log('    2) Local   — ./.claude/qaa  (this project only)');
-  console.log('');
-  const scopeChoice = await ask('Choose [1/2] (default: 1):');
-  const isGlobal = scopeChoice !== '2';
-
-  const homeDir = process.env.HOME || process.env.USERPROFILE;
-  const claudeDir = isGlobal
-    ? path.join(homeDir, '.claude')
-    : path.join(process.cwd(), '.claude');
-  const installDir = path.join(claudeDir, 'qaa');
-
-  // Check for existing installation
-  if (fs.existsSync(installDir)) {
-    const overwrite = await ask('QAA already installed at this location. Overwrite? [y/N]:');
-    if (overwrite.toLowerCase() !== 'y') {
-      log('Installation cancelled.');
-      process.exit(0);
-    }
-  }
-
-  console.log('');
-  log(`Installing to: ${installDir}`);
-  console.log('');
-
-  // ── Step 1: Copy files ──────────────────────────────────────────────────
-
-  const dirsToCopy = ['agents', 'commands', 'skills', 'templates', 'workflows', 'docs', 'bin'];
-  const filesToCopy = ['CLAUDE.md', 'CHANGELOG.md', '.mcp.json', 'package.json'];
-
-  let totalFiles = 0;
-
-  for (const dir of dirsToCopy) {
-    const src = path.join(packageDir, dir);
-    const dest = path.join(installDir, dir);
-    if (fs.existsSync(src)) {
-      const count = copyDirRecursive(src, dest);
-      success(`${dir}/ — ${count} files`);
-      totalFiles += count;
-    }
-  }
-
-  for (const file of filesToCopy) {
-    const src = path.join(packageDir, file);
-    const dest = path.join(installDir, file);
-    if (fs.existsSync(src)) {
-      fs.mkdirSync(path.dirname(dest), { recursive: true });
-      fs.copyFileSync(src, dest);
-      success(file);
-      totalFiles++;
-    }
-  }
-
-  console.log('');
-
-  // ── Step 2: Register MCP servers ────────────────────────────────────────
-
-  const claudeJsonPath = path.join(homeDir, '.claude.json');
-  const addedMcps = registerMcpServers(claudeJsonPath);
-
-  if (addedMcps.length > 0) {
-    success(`MCP servers registered: ${addedMcps.join(', ')} → ${claudeJsonPath}`);
-  } else {
-    success('MCP servers already configured (playwright, context7)');
-  }
-
-  // ── Step 3: Merge settings ──────────────────────────────────────────────
-
-  const settingsMerged = mergeSettings(installDir, packageDir);
-  if (settingsMerged) {
-    success('Permissions merged into settings.json');
-  }
-
-  // ── Done ────────────────────────────────────────────────────────────────
-
-  console.log('');
-  console.log('  ╔═══════════════════════════════════════╗');
-  console.log('  ║         Installation complete!        ║');
-  console.log('  ╚═══════════════════════════════════════╝');
-  console.log('');
-  log(`${totalFiles} files installed to ${installDir}`);
-  log('MCP servers: playwright, context7');
-  log('');
-  log('Restart Claude Code, then run any QAA command:');
-  log('  /qa-start --dev-repo ./your-project');
-  log('  /qa-create-test login');
-  log('  /qa-map');
-  console.log('');
-}
-
-main().catch(err => {
-  fail(err.message);
-  process.exit(1);
-});
+#!/usr/bin/env node
+
+/**
+ * QAA Agent Installer
+ *
+ * Installs QAA (QA Automation Agent) into the user's Claude Code environment.
+ *
+ * What it does:
+ *   1. Copies agents, commands, skills, templates, workflows, docs, bin, and config files
+ *      to the chosen install directory (global ~/.claude/qaa or local ./.claude/qaa)
+ *   2. Registers Playwright MCP and Context7 MCP as global MCP servers
+ *   3. Merges required permissions into Claude Code settings.json
+ *
+ * Usage:
+ *   npx qaa-agent
+ */
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const { execSync } = require('child_process');
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function log(msg) { console.log(`  ${msg}`); }
+function success(msg) { console.log(`  ✓ ${msg}`); }
+function warn(msg) { console.log(`  ⚠ ${msg}`); }
+function fail(msg) { console.error(`  ✗ ${msg}`); }
+
+function ask(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(resolve => {
+    rl.question(`  ${question} `, answer => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+function copyDirRecursive(src, dest, dryRun) {
+  if (!fs.existsSync(src)) return 0;
+  if (!dryRun) fs.mkdirSync(dest, { recursive: true });
+  let count = 0;
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      count += copyDirRecursive(srcPath, destPath, dryRun);
+    } else {
+      if (!dryRun) fs.copyFileSync(srcPath, destPath);
+      count++;
+    }
+  }
+  return count;
+}
+
+function deepMerge(target, source) {
+  for (const key of Object.keys(source)) {
+    if (
+      source[key] && typeof source[key] === 'object' && !Array.isArray(source[key]) &&
+      target[key] && typeof target[key] === 'object' && !Array.isArray(target[key])
+    ) {
+      deepMerge(target[key], source[key]);
+    } else if (Array.isArray(source[key]) && Array.isArray(target[key])) {
+      // Merge arrays without duplicates
+      const merged = [...new Set([...target[key], ...source[key]])];
+      target[key] = merged;
+    } else {
+      target[key] = source[key];
+    }
+  }
+  return target;
+}
+
+// ── MCP Registration ─────────────────────────────────────────────────────────
+
+function registerMcpServers(claudeJsonPath, dryRun) {
+  const mcpServers = {
+    playwright: {
+      command: 'npx',
+      args: ['@playwright/mcp@latest']
+    },
+    context7: {
+      command: 'npx',
+      args: ['-y', '@upstash/context7-mcp@latest']
+    }
+  };
+
+  let config = {};
+  if (fs.existsSync(claudeJsonPath)) {
+    try {
+      config = JSON.parse(fs.readFileSync(claudeJsonPath, 'utf-8'));
+    } catch {
+      config = {};
+    }
+  }
+
+  if (!config.mcpServers) config.mcpServers = {};
+
+  let added = [];
+  for (const [name, serverConfig] of Object.entries(mcpServers)) {
+    if (!config.mcpServers[name]) {
+      config.mcpServers[name] = serverConfig;
+      added.push(name);
+    }
+  }
+
+  if (!dryRun) fs.writeFileSync(claudeJsonPath, JSON.stringify(config, null, 2) + '\n');
+  return added;
+}
+
+// ── Settings Merge ───────────────────────────────────────────────────────────
+
+function mergeSettings(installDir, packageDir, dryRun) {
+  const srcSettings = path.join(packageDir, 'settings.json');
+  if (!fs.existsSync(srcSettings)) return false;
+
+  const claudeDir = path.dirname(installDir);
+  const destSettings = path.join(claudeDir, 'settings.json');
+
+  const source = JSON.parse(fs.readFileSync(srcSettings, 'utf-8'));
+
+  let target = {};
+  if (fs.existsSync(destSettings)) {
+    try {
+      target = JSON.parse(fs.readFileSync(destSettings, 'utf-8'));
+    } catch {
+      target = {};
+    }
+  }
+
+  deepMerge(target, source);
+  if (!dryRun) fs.writeFileSync(destSettings, JSON.stringify(target, null, 2) + '\n');
+  return true;
+}
+
+// ── Live Location Sync (finding #52) ─────────────────────────────────────────
+
+// Mirror QAA-owned files into a Claude Code live dir. Only files matching the
+// QAA pattern are copied; QAA orphans (removed in this version) are pruned.
+// Foreign files (gsd-*, sc:*, etc.) are never copied or deleted.
+function syncLive(srcDir, destDir, matches, dryRun) {
+  const copied = [];
+  const pruned = [];
+  if (!fs.existsSync(srcDir)) return { copied, pruned, skipped: true };
+
+  const srcFiles = fs.readdirSync(srcDir).filter(matches);
+  const srcSet = new Set(srcFiles);
+
+  // Prune QAA orphans that no longer ship in this version
+  if (fs.existsSync(destDir)) {
+    for (const f of fs.readdirSync(destDir).filter(matches)) {
+      if (!srcSet.has(f)) {
+        pruned.push(f);
+        if (!dryRun) fs.rmSync(path.join(destDir, f), { force: true });
+      }
+    }
+  }
+
+  // Copy / overwrite QAA files
+  if (srcFiles.length > 0 && !dryRun) fs.mkdirSync(destDir, { recursive: true });
+  for (const f of srcFiles) {
+    copied.push(f);
+    if (!dryRun) fs.copyFileSync(path.join(srcDir, f), path.join(destDir, f));
+  }
+  return { copied, pruned, skipped: false };
+}
+
+// Sync CLAUDE.md into the live location using QAA markers so user content is
+// preserved. Returns { action, backupPath? }.
+function syncClaudeMd(installDir, claudeDir, dryRun, version) {
+  const srcPath = path.join(installDir, 'CLAUDE.md');
+  const destPath = path.join(claudeDir, 'CLAUDE.md');
+  if (!fs.existsSync(srcPath)) return { action: 'skip' };
+
+  const BEGIN = `<!-- QAA-BEGIN v${version} -->`;
+  const END = '<!-- QAA-END -->';
+  const markerRe = /<!-- QAA-BEGIN[^>]*-->[\s\S]*?<!-- QAA-END -->/;
+  const srcContent = fs.readFileSync(srcPath, 'utf-8').trim();
+  const wrapped = `${BEGIN}\n${srcContent}\n${END}`;
+
+  // Case 1: no live CLAUDE.md → create it wrapped
+  if (!fs.existsSync(destPath)) {
+    if (!dryRun) {
+      fs.mkdirSync(claudeDir, { recursive: true });
+      fs.writeFileSync(destPath, wrapped + '\n');
+    }
+    return { action: 'created' };
+  }
+
+  const existing = fs.readFileSync(destPath, 'utf-8');
+
+  // Case 2: markers present → replace only the QAA section
+  if (markerRe.test(existing)) {
+    if (!dryRun) fs.writeFileSync(destPath, existing.replace(markerRe, wrapped));
+    return { action: 'updated-section' };
+  }
+
+  // Case 3: exists without markers → backup, then replace wrapped
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  const backupPath = path.join(claudeDir, `CLAUDE.md.bak-${ts}`);
+  if (!dryRun) {
+    fs.copyFileSync(destPath, backupPath);
+    fs.writeFileSync(destPath, wrapped + '\n');
+  }
+  return { action: 'backup-replaced', backupPath };
+}
+
+// ── Main ─────────────────────────────────────────────────────────────────────
+
+async function main() {
+  console.log('');
+  console.log('  ╔═══════════════════════════════════════╗');
+  console.log('  ║   QAA — QA Automation Agent Installer ║');
+  console.log('  ╚═══════════════════════════════════════╝');
+  console.log('');
+
+  // Determine package root (where the npm package files are)
+  const packageDir = path.resolve(__dirname, '..');
+
+  const dryRun = process.argv.includes('--dry-run');
+  if (dryRun) warn('--dry-run mode — no files will be written.');
+
+  let pkgVersion = 'unknown';
+  try {
+    pkgVersion = JSON.parse(fs.readFileSync(path.join(packageDir, 'package.json'), 'utf-8')).version || 'unknown';
+  } catch { /* keep 'unknown' */ }
+
+  // Check that package files exist
+  const requiredDirs = ['agents', 'commands', 'skills'];
+  const missing = requiredDirs.filter(d => !fs.existsSync(path.join(packageDir, d)));
+  if (missing.length > 0) {
+    fail(`Package incomplete — missing: ${missing.join(', ')}`);
+    process.exit(1);
+  }
+
+  // Ask install scope
+  console.log('  Install scope:');
+  console.log('    1) Global  — ~/.claude/qaa  (available in all projects)');
+  console.log('    2) Local   — ./.claude/qaa  (this project only)');
+  console.log('');
+  const scopeChoice = await ask('Choose [1/2] (default: 1):');
+  const isGlobal = scopeChoice !== '2';
+
+  const homeDir = process.env.HOME || process.env.USERPROFILE;
+  if (!homeDir) {
+    fail('Cannot determine home directory (HOME / USERPROFILE not set).');
+    process.exit(1);
+  }
+  const claudeDir = isGlobal
+    ? path.join(homeDir, '.claude')
+    : path.join(process.cwd(), '.claude');
+  const installDir = path.join(claudeDir, 'qaa');
+
+  // Check for existing installation
+  if (fs.existsSync(installDir)) {
+    const overwrite = await ask('QAA already installed at this location. Overwrite? [y/N]:');
+    if (overwrite.toLowerCase() !== 'y') {
+      log('Installation cancelled.');
+      process.exit(0);
+    }
+  }
+
+  console.log('');
+  log(`Installing to: ${installDir}`);
+  console.log('');
+
+  // ── Step 1: Copy files ──────────────────────────────────────────────────
+
+  const dirsToCopy = ['agents', 'commands', 'skills', 'templates', 'workflows', 'docs', 'bin'];
+  const filesToCopy = ['CLAUDE.md', 'CHANGELOG.md', '.mcp.json', 'package.json'];
+
+  let totalFiles = 0;
+
+  for (const dir of dirsToCopy) {
+    const src = path.join(packageDir, dir);
+    const dest = path.join(installDir, dir);
+    if (fs.existsSync(src)) {
+      const count = copyDirRecursive(src, dest, dryRun);
+      success(`${dir}/ — ${count} files`);
+      totalFiles += count;
+    }
+  }
+
+  for (const file of filesToCopy) {
+    const src = path.join(packageDir, file);
+    const dest = path.join(installDir, file);
+    if (fs.existsSync(src)) {
+      if (!dryRun) {
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.copyFileSync(src, dest);
+      }
+      success(file);
+      totalFiles++;
+    }
+  }
+
+  console.log('');
+
+  // ── Step 2: Register MCP servers ────────────────────────────────────────
+
+  const claudeJsonPath = path.join(homeDir, '.claude.json');
+  const addedMcps = registerMcpServers(claudeJsonPath, dryRun);
+
+  if (addedMcps.length > 0) {
+    success(`MCP servers registered: ${addedMcps.join(', ')} → ${claudeJsonPath}`);
+  } else {
+    success('MCP servers already configured (playwright, context7)');
+  }
+
+  // ── Step 3: Merge settings ──────────────────────────────────────────────
+
+  const settingsMerged = mergeSettings(installDir, packageDir, dryRun);
+  if (settingsMerged) {
+    success('Permissions merged into settings.json');
+  }
+
+  // ── Step 4: Sync to live locations (finding #52) ────────────────────────
+  //
+  // Claude Code loads slash commands from <claudeDir>/commands, sub-agents from
+  // <claudeDir>/agents, and global standards from <claudeDir>/CLAUDE.md — NOT
+  // from the qaa/ install dir. Mirror QAA files there so new versions activate.
+  // Only QAA-owned files (qa*.md / qaa-*.md) are touched.
+
+  console.log('');
+
+  const qaMatch = (f) => /^qa.*\.md$/i.test(f);
+  const tag = dryRun ? '[dry-run] ' : '';
+
+  const cmdSync = syncLive(
+    path.join(installDir, 'commands'),
+    path.join(claudeDir, 'commands'),
+    qaMatch, dryRun
+  );
+  success(`${tag}Live commands → ${path.join(claudeDir, 'commands')} (${cmdSync.copied.length} synced${cmdSync.pruned.length ? `, ${cmdSync.pruned.length} pruned` : ''})`);
+  if (cmdSync.pruned.length) log(`${tag}Pruned: ${cmdSync.pruned.join(', ')}`);
+
+  const agentSync = syncLive(
+    path.join(installDir, 'agents'),
+    path.join(claudeDir, 'agents'),
+    qaMatch, dryRun
+  );
+  success(`${tag}Live agents → ${path.join(claudeDir, 'agents')} (${agentSync.copied.length} synced${agentSync.pruned.length ? `, ${agentSync.pruned.length} pruned` : ''})`);
+  if (agentSync.pruned.length) log(`${tag}Pruned: ${agentSync.pruned.join(', ')}`);
+
+  const cmd = syncClaudeMd(installDir, claudeDir, dryRun, pkgVersion);
+  if (cmd.action === 'created')              success(`${tag}CLAUDE.md created (QAA markers) → ${path.join(claudeDir, 'CLAUDE.md')}`);
+  else if (cmd.action === 'updated-section') success(`${tag}CLAUDE.md QAA section updated → ${path.join(claudeDir, 'CLAUDE.md')}`);
+  else if (cmd.action === 'backup-replaced') warn(`${tag}CLAUDE.md had no QAA markers — backed up to ${cmd.backupPath}, replaced with marked version`);
+  else if (cmd.action === 'skip')            warn(`${tag}No CLAUDE.md in package to sync`);
+
+  // ── Done ────────────────────────────────────────────────────────────────
+
+  console.log('');
+  console.log('  ╔═══════════════════════════════════════╗');
+  console.log('  ║         Installation complete!        ║');
+  console.log('  ╚═══════════════════════════════════════╝');
+  console.log('');
+  if (dryRun) log('Dry-run complete — nothing was written.');
+  log(`${totalFiles} files installed to ${installDir}`);
+  log(`Live commands & agents synced to ${claudeDir}`);
+  log('MCP servers: playwright, context7');
+  log('');
+  log('Restart Claude Code, then run any QAA command:');
+  log('  /qa-start --dev-repo ./your-project');
+  log('  /qa-create-test login');
+  log('  /qa-map');
+  console.log('');
+}
+
+main().catch(err => {
+  fail(err.message);
+  process.exit(1);
+});