@ai-qa/workflow 2.0.0

package/ai-qa-workflow.js

@@ -0,0 +1,330 @@
+#!/usr/bin/env node
+
+const { DIRS, ROOT, CONFIG, ensureDir, listUserStories, listTestPlans, listTestSpecs, timestamp, log, reloadConfig, autoDetectConfig } = require('./scripts/utils');
+const { generateTestPlan } = require('./scripts/planner');
+const { generateTestSpec } = require('./scripts/generator');
+const { executeTests } = require('./scripts/executor');
+const { selfHeal } = require('./scripts/healer');
+const { generateReport } = require('./scripts/reporter');
+const path = require('path');
+const fs = require('fs');
+
+const PROJECT_NAME = CONFIG.project.name;
+
+const COMMANDS = {
+  init:    { desc: 'Create required directories and config', fn: cmdInit },
+  plan:    { desc: '<user-story.md>  Generate test plan from user story', fn: cmdPlan },
+  generate:{ desc: '<test-plan.md>   Generate test spec from test plan', fn: cmdGenerate },
+  execute: { desc: '[test-name]      Run tests with Playwright', fn: cmdExecute },
+  heal:    { desc: '[run-id]         Self-heal failed tests', fn: cmdHeal },
+  report:  { desc: '[run-id]         Generate execution report', fn: cmdReport },
+  'report:allure': { desc: '[run-id]   Generate Allure report from test results', fn: cmdAllure },
+  run:     { desc: '<story-name.md>  Full pipeline: plan → generate → execute → heal → report', fn: cmdRun },
+  status:  { desc: 'Show workflow state', fn: cmdStatus },
+  list:    { desc: 'List user stories, test plans, and test specs', fn: cmdList },
+};
+
+function cmdInit() {
+  log('INIT', 'Creating required directories...');
+  Object.values(DIRS).forEach(dir => ensureDir(dir));
+
+  const configPath = path.join(ROOT, '.qa-workflow.json');
+  if (!fs.existsSync(configPath)) {
+    log('INIT', 'Scanning project to auto-detect configuration...');
+    const detected = autoDetectConfig();
+    fs.writeFileSync(configPath, JSON.stringify(detected, null, 2) + '\n', 'utf-8');
+    log('INIT', '.qa-workflow.json created with auto-detected settings');
+    log('INIT', `Project: ${detected.project.name} → ${detected.project.url}`);
+    reloadConfig();
+  }
+
+  const envContent = `# Application Context
+# Auto-generated from project scan. Edit to provide more context for AI agents.
+
+## Project
+- Name: ${CONFIG.project.name}
+- Description: ${CONFIG.project.description || '(auto-detect from README)'}
+- URL: ${CONFIG.project.url}
+- Environment: ${CONFIG.project.environment || 'Web Application'}
+
+## Tech Stack
+- (auto-detected from project files)
+
+## Stable Selectors
+- (populate during exploration)
+
+## Known Flaky Areas
+- (populate during execution)
+
+## Authentication
+- User: ${CONFIG.auth.user || '(set in .qa-workflow.json or auto-detect from .env)'}
+`;
+  const envPath = path.join(DIRS.docs, 'application-context.md');
+  if (!fs.existsSync(envPath)) {
+    fs.writeFileSync(envPath, envContent, 'utf-8');
+    log('INIT', 'docs/application-context.md created — AI agents will use this for context');
+  }
+
+  log('INIT', 'Ready. Directories: user-story/, specs/, tests/, test-results/, docs/');
+  log('INIT', 'Edit .qa-workflow.json to override auto-detected values');
+}
+
+function cmdPlan() {
+  const storyName = process.argv[3];
+  if (!storyName) {
+    console.log('  Usage: node ai-qa-workflow.js plan <user-story-file.md>');
+    console.log(`  Available: ${listUserStories().join(', ')}`);
+    process.exit(1);
+  }
+  ensureDir(DIRS.specs);
+  const result = generateTestPlan(storyName);
+  console.log(`\n  ✓ Test plan generated: specs/${path.basename(result.planPath)}`);
+  console.log(`\n  Next step: Review and edit the test plan, then run:`);
+  console.log(`  node ai-qa-workflow.js generate ${path.basename(result.planPath)}`);
+}
+
+function cmdGenerate() {
+  const planName = process.argv[3];
+  if (!planName) {
+    console.log('  Usage: node ai-qa-workflow.js generate <test-plan-file.md>');
+    console.log(`  Available: ${listTestPlans().join(', ')}`);
+    process.exit(1);
+  }
+  ensureDir(DIRS.tests);
+  const result = generateTestSpec(planName);
+  console.log(`\n  ✓ Test spec generated: tests/${result.specName}.spec.ts`);
+  console.log(`\n  Next step: Implement test logic in the spec file, then run:`);
+  console.log(`  node ai-qa-workflow.js execute ${result.specName}`);
+}
+
+function cmdExecute() {
+  const testName = process.argv[3];
+  const headed = process.argv.includes('--headed');
+  ensureDir(DIRS.testResults);
+
+  console.log('');
+  const result = executeTests(testName, { headed });
+
+  console.log(`\n  Result: ${result.success ? '✓ PASSED' : '✗ FAILED'}`);
+  console.log(`  Duration: ${(result.duration / 1000).toFixed(1)}s`);
+  if (result.failedTests && result.failedTests.length > 0) {
+    console.log(`  Failures: ${result.failedTests.length}`);
+    result.failedTests.forEach(ft => console.log(`    - ${ft.test || ft.file}`));
+  }
+
+  if (!result.success) {
+    console.log(`\n  Next step: Auto-heal failures:`);
+    console.log(`  node ai-qa-workflow.js heal ${result.runId}`);
+  } else {
+    console.log(`\n  Next step: Generate report:`);
+    console.log(`  node ai-qa-workflow.js report ${result.runId}`);
+  }
+}
+
+function cmdHeal() {
+  const runId = process.argv[3];
+  const result = selfHeal(runId, PROJECT_NAME);
+
+  if (result.healed.length > 0) {
+    console.log(`\n  ✓ Healed: ${result.healed.length} test(s)`);
+    result.healed.forEach(h => console.log(`    - ${h.test || h.file} (${h.strategy})`));
+  }
+  if (result.remaining.length > 0) {
+    console.log(`\n  ✗ Still failing: ${result.remaining.length} test(s)`);
+    result.remaining.forEach(ft => console.log(`    - ${ft.test || ft.file}`));
+  }
+  if (result.healed.length === 0 && result.remaining.length === 0) {
+    console.log('\n  No failures to heal.');
+  }
+
+  console.log(`\n  Next step: Generate report:`);
+  console.log(`  node ai-qa-workflow.js report ${result.reportPath ? path.basename(path.dirname(result.reportPath)) : runId || '(latest)'}`);
+}
+
+function cmdReport() {
+  const runId = process.argv[3];
+  const result = generateReport(runId);
+
+  if (!result) {
+    console.log('\n  No test results found. Run tests first: node ai-qa-workflow.js execute');
+    process.exit(1);
+  }
+
+  console.log(`\n  ✓ Report generated: ${result.reportPath}`);
+  console.log(`  Passed: ${result.stats.passed} | Failed: ${result.stats.failed} | Healed: ${result.stats.healed}`);
+}
+
+function cmdAllure() {
+  const { execSync } = require('child_process');
+  const allureResults = path.join(ROOT, 'allure-results');
+  const allureReport = path.join(ROOT, 'allure-report');
+
+  if (!fs.existsSync(allureResults)) {
+    console.log('\n  No allure-results/ directory found.');
+    console.log('  Ensure your Playwright config outputs Allure results.');
+    console.log('  Add to playwright.config: reporter: [["list"], ["allure-playwright"]]');
+    console.log('  Install: npm install -D allure-playwright');
+    process.exit(1);
+  }
+
+  log('ALLURE', `Generating report from: allure-results/`);
+
+  try {
+    execSync(`npx allure generate "${allureResults}" --clean -o "${allureReport}"`, {
+      cwd: ROOT,
+      encoding: 'utf-8',
+      timeout: 60000,
+      stdio: 'pipe',
+    });
+    log('ALLURE', `Report generated: allure-report/index.html`);
+    console.log(`\n  ✓ Allure report: allure-report/index.html`);
+    console.log(`  Open in dashboard: /allure-report`);
+  } catch (err) {
+    console.error('\n  ✗ Failed to generate Allure report.');
+    console.error('  Ensure Allure CLI is available: npm install -D allure-commandline');
+    if (err.stderr) console.error(`  ${err.stderr.substring(0, 500)}`);
+    process.exit(1);
+  }
+}
+
+function cmdRun() {
+  const storyName = process.argv[3];
+  if (!storyName) {
+    console.log('  Usage: node ai-qa-workflow.js run <user-story-file.md>');
+    console.log(`  Available: ${listUserStories().join(', ')}`);
+    process.exit(1);
+  }
+
+  console.log('\n╔════════════════════════════════════════╗');
+  console.log('║   AI QA WORKFLOW - FULL PIPELINE      ║');
+  console.log('╚════════════════════════════════════════╝\n');
+
+  // Step 1: Plan
+  log('RUN', 'Step 1/5: Generating test plan...');
+  ensureDir(DIRS.specs);
+  const plan = generateTestPlan(storyName);
+  console.log(`  → specs/${path.basename(plan.planPath)}\n`);
+
+  // Step 2: Generate
+  log('RUN', 'Step 2/5: Generating test spec...');
+  ensureDir(DIRS.tests);
+  const spec = generateTestSpec(path.basename(plan.planPath));
+  console.log(`  → tests/${spec.specName}.spec.ts\n`);
+
+  // Step 3: Execute
+  log('RUN', 'Step 3/5: Executing tests...');
+  ensureDir(DIRS.testResults);
+  const execResult = executeTests(spec.specName);
+  console.log(`  → ${execResult.success ? '✓ PASSED' : '✗ FAILED'} (${(execResult.duration / 1000).toFixed(1)}s)\n`);
+
+  // Step 4: Heal (if needed)
+  if (!execResult.success) {
+    log('RUN', 'Step 4/5: Self-healing...');
+    const healResult = selfHeal(execResult.runId, PROJECT_NAME);
+    console.log(`  → Healed: ${healResult.healed.length} | Remaining: ${healResult.remaining.length}\n`);
+  } else {
+    log('RUN', 'Step 4/5: Skipped (all tests passed)');
+    console.log('');
+  }
+
+  // Step 5: Report
+  log('RUN', 'Step 5/5: Generating report...');
+  const report = generateReport(execResult.runId);
+  console.log(`  → ${report ? report.reportPath : 'N/A'}\n`);
+
+  console.log('╔════════════════════════════════════════╗');
+  console.log('║   WORKFLOW COMPLETE                    ║');
+  console.log('╚════════════════════════════════════════╝');
+  if (report) {
+    console.log(`\n  Report: test-results/${execResult.runId}/final-test-report.md`);
+    console.log(`  Passed: ${report.stats.passed} | Failed: ${report.stats.failed} | Healed: ${report.stats.healed}`);
+  }
+}
+
+function cmdStatus() {
+  console.log('\n📊 AI QA Workflow Status\n');
+
+  const stories = listUserStories();
+  console.log(`📝 User Stories: ${stories.length}`);
+  stories.forEach(s => {
+    const planFile = s.replace(/\.md$/, '-test-plan.md');
+    const specFile = s.replace(/\.md$/, '.spec.ts');
+
+    const hasPlan = listTestPlans().includes(planFile);
+    const hasSpec = listTestSpecs().includes(specFile);
+
+    const status = hasSpec ? '✅ Test written' : hasPlan ? '📋 Test plan ready' : '📄 Story only';
+    console.log(`  ${status}  ${s}`);
+  });
+
+  const plans = listTestPlans();
+  console.log(`\n📋 Test Plans: ${plans.length}`);
+  plans.forEach(p => {
+    const hasSpec = listTestSpecs().includes(p.replace('-test-plan.md', '.spec.ts'));
+    console.log(`  ${hasSpec ? '✅ Test written' : '📄 Plan only'}  ${p}`);
+  });
+
+  const specs = listTestSpecs();
+  console.log(`\n🧪 Test Specs: ${specs.length}`);
+  specs.forEach(s => console.log(`  ${s}`));
+
+  if (fs.existsSync(DIRS.testResults)) {
+    const runDirs = fs.readdirSync(DIRS.testResults)
+      .filter(d => fs.statSync(path.join(DIRS.testResults, d)).isDirectory());
+    console.log(`\n📊 Execution Runs: ${runDirs.length}`);
+    runDirs.forEach(d => {
+      const resultFile = path.join(DIRS.testResults, d, 'execution-result.json');
+      if (fs.existsSync(resultFile)) {
+        const result = JSON.parse(fs.readFileSync(resultFile, 'utf-8'));
+        console.log(`  ${result.success ? '✅' : '❌'} ${d} (${(result.duration / 1000).toFixed(1)}s)${result.failedTests ? ` - ${result.failedTests.length} failure(s)` : ''}`);
+      } else {
+        console.log(`  ⏳ ${d} (incomplete)`);
+      }
+    });
+  }
+
+  console.log('');
+}
+
+function cmdList() {
+  console.log('\n📝 User Stories:');
+  listUserStories().forEach(s => console.log(`  ${s}`));
+
+  console.log('\n📋 Test Plans:');
+  listTestPlans().forEach(p => console.log(`  ${p}`));
+
+  console.log('\n🧪 Test Specs:');
+  listTestSpecs().forEach(s => console.log(`  ${s}`));
+  console.log('');
+}
+
+const cmd = process.argv[2];
+
+if (!cmd || cmd === '--help' || cmd === '-h') {
+  console.log('\nAI QA Workflow - Test Automation Pipeline\n');
+  console.log('Usage: node ai-qa-workflow.js <command> [options]\n');
+  console.log('Commands:');
+  for (const [name, { desc }] of Object.entries(COMMANDS)) {
+    console.log(`  ${name.padEnd(12)} ${desc}`);
+  }
+  console.log('\nExamples:');
+  console.log('  node ai-qa-workflow.js init');
+  console.log('  node ai-qa-workflow.js plan US-EXPLORE-01.md');
+  console.log('  node ai-qa-workflow.js generate us-explore-01-test-plan.md');
+  console.log('  node ai-qa-workflow.js execute us-explore-01');
+  console.log('  node ai-qa-workflow.js run US-EXPLORE-01.md');
+  console.log('  node ai-qa-workflow.js report:allure');
+  console.log('  node ai-qa-workflow.js status\n');
+  process.exit(0);
+}
+
+if (!COMMANDS[cmd]) {
+  console.error(`Unknown command: ${cmd}`);
+  console.log(`Available: ${Object.keys(COMMANDS).join(', ')}`);
+  process.exit(1);
+}
+
+ensureDir(DIRS.docs);
+ensureDir(DIRS.testResults);
+
+COMMANDS[cmd].fn();

package/cli.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+
+const path = require('path');
+
+// Forward to install.js with --self flag so it installs into cwd
+process.argv.push('--self');
+require(path.join(__dirname, 'install.js'));

package/docs/application-context.md

@@ -0,0 +1,20 @@
+# Application Context
+# Auto-generated from project scan. Edit to provide more context for AI agents.
+
+## Project
+- Name: ai-qa-workflow-template
+- Description: Reusable AI QA Workflow - User Story to Test Report pipeline
+- URL: http://localhost:4000
+- Environment: Web Application
+
+## Tech Stack
+- (auto-detected from project files)
+
+## Stable Selectors
+- (populate during exploration)
+
+## Known Flaky Areas
+- (populate during execution)
+
+## Authentication
+- User: (set in .qa-workflow.json or auto-detect from .env)

package/install.js

@@ -0,0 +1,303 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const TEMPLATE_DIR = __dirname;
+const YES = process.argv.includes('--yes') || process.argv.includes('-y');
+const IS_UPDATE = process.argv.includes('--update') || process.argv.includes('-u');
+const IS_SELF = process.argv.includes('--self') || process.argv.includes('-s');
+
+// Files that belong to the user — NEVER overwritten
+const USER_FILES = new Set([
+  '.qa-workflow.json',
+  'opencode.json',
+  'docs/application-context.md',
+]);
+
+// Directories that are pure user data — NEVER touched
+const USER_DIRS = new Set([
+  'user-story',
+  'specs',
+  'tests',
+  'test-results',
+]);
+
+// Template files to copy/update
+const QA_ITEMS = [
+  { src: 'ai-qa-workflow.js', dest: 'ai-qa-workflow.js' },
+  { src: 'scripts', dest: 'scripts', dir: true },
+  { src: 'opencode.json', dest: 'opencode.json' },
+  { src: '.qa-workflow.json', dest: '.qa-workflow.json' },
+  { src: 'prompts', dest: 'prompts', dir: true },
+  { src: '.github/agents', dest: '.github/agents', dir: true },
+  { src: '.opencode', dest: '.opencode', dir: true },
+];
+
+// Files to copy even during update (excludes user config files)
+const UPDATE_ITEMS = QA_ITEMS.filter(item => {
+  if (item.dir) return !USER_DIRS.has(item.dest);
+  return !USER_FILES.has(item.dest);
+});
+
+const DIRS_TO_CREATE = ['user-story', 'specs', 'tests', 'test-results'];
+
+const NPM_SCRIPTS = {
+  'qa': 'node ai-qa-workflow.js',
+  'qa:init': 'node ai-qa-workflow.js init',
+  'qa:plan': 'node ai-qa-workflow.js plan',
+  'qa:generate': 'node ai-qa-workflow.js generate',
+  'qa:execute': 'node ai-qa-workflow.js execute',
+  'qa:heal': 'node ai-qa-workflow.js heal',
+  'qa:report': 'node ai-qa-workflow.js report',
+  'qa:report:allure': 'node ai-qa-workflow.js report:allure',
+  'qa:run': 'node ai-qa-workflow.js run',
+  'qa:status': 'node ai-qa-workflow.js status',
+  'qa:list': 'node ai-qa-workflow.js list',
+  'dashboard': 'cd qa-dashboard && npm start',
+  'dashboard:dev': 'cd qa-dashboard && npx nodemon app.js',
+};
+
+const BANNER = `
+  ╔══════════════════════════════════════════╗
+  ║    AI QA Pipeline Installer v2.0         ║
+  ╚══════════════════════════════════════════╝
+`;
+
+function copyRecursive(src, dest, skipDirs) {
+  skipDirs = skipDirs || new Set();
+  const stat = fs.statSync(src);
+  if (stat.isDirectory()) {
+    const base = path.basename(src);
+    if (skipDirs.has(base)) return;
+    if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
+    fs.readdirSync(src).forEach(item => copyRecursive(path.join(src, item), path.join(dest, item), skipDirs));
+  } else {
+    if (!fs.existsSync(dest) || fs.readFileSync(src).length !== fs.readFileSync(dest).length) {
+      fs.copyFileSync(src, dest);
+      return true;
+    }
+  }
+  return false;
+}
+
+function countFiles(dir) {
+  let count = 0;
+  if (!fs.existsSync(dir)) return 0;
+  fs.readdirSync(dir).forEach(item => {
+    try {
+      const full = path.join(dir, item);
+      if (fs.statSync(full).isDirectory()) count += countFiles(full);
+      else count++;
+    } catch (e) {}
+  });
+  return count;
+}
+
+function addNpmScripts(pkgPath, overwrite) {
+  if (!fs.existsSync(pkgPath)) return;
+  let pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+  if (!pkg.scripts) pkg.scripts = {};
+  let changed = 0;
+  for (const [key, val] of Object.entries(NPM_SCRIPTS)) {
+    if (!pkg.scripts[key] || overwrite) {
+      pkg.scripts[key] = val;
+      changed++;
+    }
+  }
+  fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+  return changed;
+}
+
+function ask(query) {
+  const rl = require('readline').createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(resolve => rl.question(query, a => { rl.close(); resolve(a.toLowerCase()); }));
+}
+
+async function install(targetPath, mode) {
+  const isUpdate = mode === 'update';
+
+  console.log(BANNER);
+  console.log(`  Mode: ${isUpdate ? 'UPDATE (preserves config)' : 'FRESH INSTALL'}`);
+  console.log(`  Target: ${targetPath}\n`);
+
+  // 1. Copy template files
+  const items = isUpdate ? UPDATE_ITEMS : QA_ITEMS;
+  console.log(`  ── Step 1: QA Pipeline Files ──`);
+  for (const item of items) {
+    const srcPath = path.join(TEMPLATE_DIR, item.src);
+    const destPath = path.join(targetPath, item.dest);
+    if (!fs.existsSync(srcPath)) { console.log(`  ⚠  ${item.src} not found, skipping`); continue; }
+    if (item.dir) {
+      if (!fs.existsSync(destPath)) fs.mkdirSync(destPath, { recursive: true });
+      const skipDirs = isUpdate ? new Set(['node_modules', 'data']) : new Set();
+      copyRecursive(srcPath, destPath, skipDirs);
+      const count = countFiles(srcPath);
+      console.log(`  ✓ ${item.dest}/ (${count} files)`);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+      console.log(`  ✓ ${item.dest}`);
+    }
+  }
+
+  // 2. Create directories (fresh install only)
+  if (!isUpdate) {
+    console.log(`\n  ── Step 2: Project Directories ──`);
+    for (const dir of DIRS_TO_CREATE) {
+      const dirPath = path.join(targetPath, dir);
+      if (!fs.existsSync(dirPath)) { fs.mkdirSync(dirPath, { recursive: true }); console.log(`  ✓ ${dir}/`); }
+      else console.log(`  • ${dir}/ (exists)`);
+    }
+  }
+
+  // 3. Add/update npm scripts
+  console.log(`\n  ── Step 3: NPM Scripts ──`);
+  const pkgPath = path.join(targetPath, 'package.json');
+  const changed = addNpmScripts(pkgPath, isUpdate);
+  if (changed > 0) console.log(`  ✓ ${isUpdate ? 'Updated' : 'Added'} ${changed} npm scripts (qa:*, dashboard)`);
+  else console.log(`  • Scripts already configured`);
+
+  // 4. Dashboard
+  const dashboardSrc = path.join(TEMPLATE_DIR, 'qa-dashboard');
+  const dashboardDest = path.join(targetPath, 'qa-dashboard');
+  if (fs.existsSync(dashboardSrc)) {
+    console.log(`\n  ── Step 4: QA Dashboard ──`);
+    if (!fs.existsSync(dashboardDest)) {
+      fs.mkdirSync(dashboardDest, { recursive: true });
+      copyRecursive(dashboardSrc, dashboardDest);
+      console.log(`  ✓ Dashboard copied to qa-dashboard/`);
+      console.log(`  → Installing dashboard dependencies...`);
+      try { execSync('npm install', { cwd: dashboardDest, stdio: 'pipe', timeout: 120000 }); console.log(`  ✓ Dashboard deps installed`); } catch (e) { console.log(`  ⚠  cd qa-dashboard && npm install`); }
+    } else {
+      const skipDirs = new Set(['node_modules', 'data']);
+      copyRecursive(dashboardSrc, dashboardDest, skipDirs);
+      console.log(`  ✓ Dashboard updated (preserved data/, node_modules/)`);
+      if (!isUpdate) {
+        console.log(`  → Installing dashboard dependencies...`);
+        try { execSync('npm install', { cwd: dashboardDest, stdio: 'pipe', timeout: 120000 }); console.log(`  ✓ Dashboard deps installed`); } catch (e) { console.log(`  ⚠  cd qa-dashboard && npm install`); }
+      }
+    }
+  }
+
+  // 5. Register project in dashboard (fresh install only)
+  if (!isUpdate && fs.existsSync(dashboardDest)) {
+    console.log(`\n  ── Step 5: Link Dashboard → Project ──`);
+    const dashDataDir = path.join(dashboardDest, 'data');
+    const dashProjectsFile = path.join(dashDataDir, 'projects.json');
+    if (fs.existsSync(dashDataDir)) {
+      let projects = [];
+      if (fs.existsSync(dashProjectsFile)) {
+        try { projects = JSON.parse(fs.readFileSync(dashProjectsFile, 'utf-8')); } catch(e) {}
+      }
+      const projectName = path.basename(targetPath);
+      const projectId = projectName.toLowerCase().replace(/[^a-z0-9]+/g, '-');
+      if (!projects.find(p => p.id === projectId)) {
+        projects.push({ id: projectId, name: projectName, path: targetPath, createdAt: new Date().toISOString(), updatedAt: new Date().toISOString() });
+        fs.writeFileSync(dashProjectsFile, JSON.stringify(projects, null, 2));
+        console.log(`  ✓ Project "${projectName}" registered in dashboard`);
+      }
+    }
+  }
+
+  // 6. Install Playwright (fresh only)
+  if (!isUpdate) {
+    console.log(`\n  ── Step 6: Dependencies ──`);
+    if (!fs.existsSync(path.join(targetPath, 'node_modules', '@playwright'))) {
+      console.log(`  → Installing @playwright/test...`);
+      try { execSync('npm install @playwright/test', { cwd: targetPath, stdio: 'pipe', timeout: 120000 }); console.log(`  ✓ Playwright installed`); } catch (e) { console.log(`  ⚠  npm install failed: npm install @playwright/test`); }
+    } else console.log(`  • Playwright already installed`);
+  }
+
+  // Summary
+  const totalFiles = countFiles(path.join(targetPath, 'scripts'));
+  const dashboardCount = countFiles(path.join(targetPath, 'qa-dashboard'));
+
+  console.log(`\n  ╔══════════════════════════════════════════╗`);
+  console.log(`  ║   ✓ ${isUpdate ? 'UPDATE COMPLETE' : 'INSTALLATION COMPLETE'}${' '.repeat(isUpdate ? 13 : 7)}║`);
+  console.log(`  ╚══════════════════════════════════════════╝\n`);
+
+  if (isUpdate) {
+    console.log(`  Pipeline files updated. Your config and data are preserved.`);
+    console.log(`  Restart the dashboard if it was running.\n`);
+  } else {
+    console.log(`  Files: ~${totalFiles} scripts + ${dashboardCount} dashboard files`);
+    console.log(`  Next:\n`);
+    console.log(`  npm run qa:init      Initialize pipeline (auto-detect config)`);
+    console.log(`  npm run qa:run       Run a user story through full pipeline`);
+    console.log(`  npm run qa:status    Check pipeline state`);
+    console.log(`  npm run dashboard    Start dashboard (port 4000)\n`);
+  }
+}
+
+// ---- CLI entry ----
+const args = process.argv.slice(2);
+const isHelp = !args.length || args.includes('--help') || args.includes('-h');
+
+if (isHelp) {
+  console.log(`
+AI QA Pipeline Installer
+
+  USAGE:
+
+    npx ai-qa-workflow init [--yes]     Install into current directory
+    npx ai-qa-workflow update [--yes]   Update pipeline files (preserves config)
+
+  Or from the template directory:
+
+    node install.js <target> [--yes]        Fresh install into target project
+    node install.js <target> --update       Update existing installation
+    node install.js . --yes                 Install into current directory
+
+  FLAGS:
+    --yes, -y    Skip all prompts
+    --update,-u  Update mode (preserves config, stories, results)
+
+  EXAMPLES:
+    npx ai-qa-workflow init --yes
+    node install.js ../my-project --yes
+    node install.js ../my-project --update
+`);
+  process.exit(0);
+}
+
+async function main() {
+  let targetPath;
+  let mode = 'install';
+
+  // Parse flags and target
+  const nonFlagArgs = args.filter(a => !a.startsWith('-'));
+
+  if (IS_SELF || args.includes('init')) {
+    targetPath = process.cwd();
+    mode = 'install';
+  } else if (args.includes('update')) {
+    targetPath = process.cwd();
+    mode = 'update';
+  } else if (IS_UPDATE) {
+    targetPath = path.resolve(nonFlagArgs[0] || process.cwd());
+    mode = 'update';
+  } else if (nonFlagArgs.length > 0) {
+    targetPath = path.resolve(nonFlagArgs[0]);
+    mode = 'install';
+  } else {
+    targetPath = process.cwd();
+    mode = 'install';
+  }
+
+  if (!fs.existsSync(targetPath) || !fs.statSync(targetPath).isDirectory()) {
+    console.error(`  ✗ Target not found: ${targetPath}`);
+    process.exit(1);
+  }
+
+  // Confirm unless --yes
+  if (!YES) {
+    const modeLabel = mode === 'update' ? 'UPDATE pipeline files' : 'INSTALL pipeline';
+    const answer = await ask(`  ${modeLabel} in "${path.basename(targetPath)}"? (Y/n) `);
+    if (answer.startsWith('n')) { console.log('  Aborted.'); process.exit(0); }
+  }
+
+  await install(targetPath, mode);
+}
+
+main().catch(e => { console.error(e); process.exit(1); });