qa-engineer 0.9.0

package/packages/installer/lib/commands/doctor.mjs

@@ -0,0 +1,190 @@
+// `qa doctor` — environment and pack diagnostics with repair hints.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { EXIT, SHARED_SKILLS_DIR } from '../constants.mjs';
+import { resolveSourceRoot, resolveProjectRoot } from '../core/paths.mjs';
+import { VERSION, SPEC_REVISION } from '../version.mjs';
+import { AGENTS, resolveInstallTargets, listAgentIds } from '../agents/registry.mjs';
+import { packHasBundles, findPython, verifyImports } from '../core/bundle.mjs';
+import { BUNDLE_DEST, BUNDLE_MANIFEST, bundlePackagesForSkill } from '../core/manifest.mjs';
+import { readLock } from '../core/lockfile.mjs';
+import { createLogger } from '../core/logger.mjs';
+import { parseCommonFlags } from '../cli/flags.mjs';
+import { validateInstall } from '../core/validate-install.mjs';
+import { scanProject } from '../detect/scan.mjs';
+import { spawnSync } from 'node:child_process';
+
+function hasGit(root) {
+  if (fs.existsSync(path.join(root, '.git'))) return true;
+  const probe = spawnSync('git', ['rev-parse', '--is-inside-work-tree'], {
+    cwd: root,
+    encoding: 'utf8',
+  });
+  return probe.status === 0;
+}
+
+export async function runDoctor(argv, { log } = {}) {
+  const opts = parseCommonFlags(argv);
+  const logger = log ?? createLogger();
+  if (opts.help) {
+    logger.result(`Usage: qa doctor [--project <dir>] [--json]
+
+Diagnose environment and QA Automation Pack installation.
+Each failure includes an exact repair command.`);
+    return EXIT.OK;
+  }
+
+  const root = resolveProjectRoot(opts.project ?? process.cwd());
+  let source = null;
+  try {
+    source = resolveSourceRoot();
+  } catch (error) {
+    if (!opts.json) logger.warn(error.message);
+  }
+
+  const detected = AGENTS.filter((a) => a.detect(root)).map((a) => a.id);
+  const targets = resolveInstallTargets(root, opts.agents).map((a) => a.id);
+  const lock = readLock(root);
+  const python = findPython();
+  const gitOk = hasGit(root);
+  const scan = scanProject(root, opts.agents);
+  const validation = lock ? validateInstall(root) : null;
+
+  /** @type {Array<{ section: string, id: string, ok: boolean, message: string, hint?: string }>} */
+  const checklist = [];
+
+  const nodeMajor = Number(process.versions.node.split('.')[0]);
+  checklist.push({
+    section: 'Environment',
+    id: 'node',
+    ok: nodeMajor >= 18,
+    message: `Node ${process.version}`,
+    hint: nodeMajor >= 18 ? undefined : 'upgrade to Node.js 18.18+',
+  });
+  checklist.push({
+    section: 'Environment',
+    id: 'python',
+    ok: Boolean(python),
+    message: python ? `${python.bin} (${python.version})` : 'Python not found',
+    hint: python ? undefined : 'install Python 3.8+ for analysis/diagnostics engines',
+  });
+  checklist.push({
+    section: 'Environment',
+    id: 'git',
+    ok: gitOk,
+    message: gitOk ? 'git repository detected' : 'not a git repository',
+    hint: gitOk ? undefined : 'optional — git init if you want version control',
+  });
+  checklist.push({
+    section: 'Environment',
+    id: 'assistant',
+    ok: detected.length > 0,
+    message:
+      detected.length > 0
+        ? `AI assistants: ${detected.join(', ')}`
+        : 'no assistant markers (will use .agents/skills)',
+    hint: detected.length > 0 ? undefined : 'optional — open the project in Cursor/Claude/OpenCode',
+  });
+
+  if (validation) {
+    for (const c of validation.checks) {
+      checklist.push({
+        section: 'QA Automation Pack',
+        id: c.id,
+        ok: c.ok,
+        message: c.message,
+        hint: c.hint,
+      });
+    }
+  } else {
+    checklist.push({
+      section: 'QA Automation Pack',
+      id: 'lockfile',
+      ok: false,
+      message: 'no qa-lock.json',
+      hint: 'run: qa install',
+    });
+    checklist.push({
+      section: 'QA Automation Pack',
+      id: 'skills',
+      ok: false,
+      message: 'skills not installed',
+      hint: 'run: qa install',
+    });
+  }
+
+  // Deep Python import check when bundles are on disk
+  if (lock && packHasBundles() && python) {
+    const bundledSkill = Object.keys(BUNDLE_MANIFEST)[0];
+    const libDir = path.join(root, SHARED_SKILLS_DIR, bundledSkill, BUNDLE_DEST);
+    const claudeLib = path.join(root, '.claude', 'skills', bundledSkill, BUNDLE_DEST);
+    const resolvedLib = fs.existsSync(libDir) ? libDir : fs.existsSync(claudeLib) ? claudeLib : null;
+    if (resolvedLib) {
+      const packages = bundlePackagesForSkill(bundledSkill);
+      const result = verifyImports({ pythonBin: python.bin, libDir: resolvedLib, packages });
+      checklist.push({
+        section: 'QA Automation Pack',
+        id: 'engine-imports',
+        ok: result.ok,
+        message: result.ok ? 'bundled engine runs cleanly' : `engine check failed: ${result.stderr}`,
+        hint: result.ok ? undefined : 'run: qa repair',
+      });
+    }
+  }
+
+  const blocking = checklist.filter(
+    (c) =>
+      !c.ok &&
+      ['node', 'lockfile', 'skills', 'integrity', 'engine'].includes(c.id),
+  );
+
+  const report = {
+    packVersion: VERSION,
+    specRevision: SPEC_REVISION,
+    projectRoot: root,
+    sourceRoot: source,
+    knownAgents: listAgentIds(),
+    detectedAgents: detected,
+    installTargets: targets,
+    lockfilePresent: Boolean(lock),
+    lockfilePack: lock?.pack ?? null,
+    python,
+    bundles: packHasBundles(),
+    node: process.version,
+    git: gitOk,
+    frameworks: scan.frameworks,
+    languages: scan.languages,
+    checklist,
+    ok: blocking.length === 0,
+  };
+
+  if (!opts.json) {
+    logger.step(`QA Automation Pack doctor — ${VERSION}`);
+    logger.step(`project ${root}`);
+    let section = '';
+    for (const item of checklist) {
+      if (item.section !== section) {
+        section = item.section;
+        logger.info(`\n${section}`);
+      }
+      // A failed check that is not blocking is a warning, not an error. Rendering
+      // "no git repository" and "no assistant markers" in red — directly above a
+      // hint calling them optional — is the first thing a new user sees, and it
+      // reads as a broken install when nothing is broken.
+      const isBlocking = blocking.some((b) => b.id === item.id);
+      if (item.ok) logger.ok(item.message);
+      else if (isBlocking) logger.error(item.message);
+      else logger.warn(item.message);
+      if (!item.ok && item.hint) logger.info(`  → ${item.hint}`);
+    }
+    logger.info('');
+    if (blocking.length === 0) logger.ok('doctor: no blocking issues');
+    else logger.error('doctor: blocking issues found — see hints above');
+  }
+
+  // Doctor always exits 0 when it successfully produced a report; `ok` in the
+  // payload (and self-test / verify) are the gates for automation.
+  logger.result(report);
+  return EXIT.OK;
+}

package/packages/installer/lib/commands/install.mjs

@@ -0,0 +1,291 @@
+// `qa install` — copy skills into agent discovery paths, optional wrappers,
+// lockfile with per-file hashes. Never executes skill code at install time.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { BACKUP_DIR, LOCKFILE, EXIT } from '../constants.mjs';
+import { resolveSourceRoot, resolveProjectRoot, toPosix } from '../core/paths.mjs';
+import { listSkills, skillFiles } from '../core/manifest.mjs';
+import { bundleFilesForSkill } from '../core/bundle.mjs';
+import { hashBytes } from '../core/hash.mjs';
+import { detectConflicts } from '../core/conflict.mjs';
+import { Transaction } from '../core/fs-safe.mjs';
+import { buildLock, readLock, serializeLock, lockPath } from '../core/lockfile.mjs';
+import { loadConfig } from '../core/config.mjs';
+import { readSkillMeta } from '../core/skill-meta.mjs';
+import { renderWrapper } from '../core/wrappers.mjs';
+import { conflictError, verifyError } from '../core/errors.mjs';
+import { resolveInstallTargets } from '../agents/registry.mjs';
+import { createLogger } from '../core/logger.mjs';
+import { parseCommonFlags } from '../cli/flags.mjs';
+import { validateInstall } from '../core/validate-install.mjs';
+import { INSTALL_STEPS, progressBar } from '../ui/progress.mjs';
+import { detectFrameworks } from '../detect/frameworks.mjs';
+import { getFramework } from '../../../../shared/frameworks/registry.mjs';
+
+/**
+ * Say plainly which commands this project can actually use.
+ *
+ * A project with no supported end-to-end framework still gets all thirteen
+ * skills, and `/qa-run` will then stop and recommend `/qa-init` — which the user
+ * has already run. That loop reads as a broken install. Unit-test-only projects
+ * (Jest, Vitest, pytest) are common, so the honest thing is to say up front which
+ * commands work here and which do not, rather than let the user discover it by
+ * hitting a dead end.
+ */
+function reportFrameworkFit(root, logger) {
+  let detected = [];
+  try {
+    // detectFrameworks returns ids; the registry is the source of truth for
+    // whether an id can actually execute live.
+    detected = (detectFrameworks(root).frameworks ?? []).map(
+      (id) => getFramework(id) ?? { id, name: id, liveExecution: false },
+    );
+  } catch {
+    return; // detection is best-effort; never fail an install over it
+  }
+
+  if (detected.length > 0) {
+    const live = detected.filter((f) => f.liveExecution).map((f) => f.name ?? f.id);
+    const gated = detected.filter((f) => !f.liveExecution).map((f) => f.name ?? f.id);
+    if (live.length > 0) {
+      logger.step(`detected ${live.join(', ')} — /qa-run and /qa-generate work here`);
+    }
+    if (gated.length > 0) {
+      logger.step(
+        `detected ${gated.join(', ')} — results are understood, but running and ` +
+          'generating tests live is Playwright-only today',
+      );
+    }
+    return;
+  }
+
+  logger.warn('no supported end-to-end framework detected (Playwright, Selenium, Cypress, WebdriverIO)');
+  logger.info('  → /qa-run and /qa-generate need one; they will tell you so rather than guess');
+  logger.info('  → these work without one: /qa-review, /qa-api, /qa-report, /qa-audit, /qa-explore');
+  logger.info('  → unit tests only (Jest, Vitest, pytest)? That is expected — see the README');
+}
+
+/**
+ * Core install implementation shared by install / onboard / repair / update.
+ *
+ * @param {{
+ *   projectRoot: string,
+ *   agentIds?: string[],
+ *   force?: boolean,
+ *   dryRun?: boolean,
+ *   skipValidate?: boolean,
+ *   json?: boolean,
+ *   onProgress?: (label: string, index: number, total: number) => void,
+ *   log?: ReturnType<typeof createLogger>,
+ * }} options
+ */
+export async function executeInstall({
+  projectRoot,
+  agentIds = [],
+  force = false,
+  dryRun = false,
+  skipValidate = false,
+  json = false,
+  onProgress,
+  log,
+} = {}) {
+  const logger = log ?? createLogger();
+  const sourceRoot = resolveSourceRoot();
+  const root = resolveProjectRoot(projectRoot);
+  const { config } = loadConfig(root);
+  const explicit = agentIds.length > 0 ? agentIds : config.agents ?? [];
+  const agents = resolveInstallTargets(root, explicit);
+  const skills = listSkills(sourceRoot);
+
+  if (!json) {
+    logger.step(`source: ${sourceRoot}`);
+    logger.step(`project: ${root}`);
+    logger.step(`agents: ${agents.map((a) => a.id).join(', ')}`);
+    logger.step(`skills: ${skills.length}`);
+  }
+
+  /** @type {Array<{path:string, sha256:string, bytes:number, owner:string, skill?:string, agent?:string, content:Buffer}>} */
+  const planned = [];
+
+  for (const agent of agents) {
+    for (const skill of skills) {
+      const files = skillFiles(sourceRoot, skill);
+      for (const rel of files) {
+        if (rel.startsWith('tests/') || rel.includes('/tests/')) continue;
+        const abs = path.join(sourceRoot, 'skills', skill, rel);
+        const content = fs.readFileSync(abs);
+        const dest = toPosix(path.join(agent.skillsDir, skill, rel));
+        planned.push({
+          path: dest,
+          sha256: hashBytes(content),
+          bytes: content.length,
+          owner: 'skill',
+          skill,
+          agent: agent.id,
+          content,
+        });
+      }
+      for (const bundled of bundleFilesForSkill(sourceRoot, skill)) {
+        const dest = toPosix(path.join(agent.skillsDir, skill, bundled.rel));
+        planned.push({
+          path: dest,
+          sha256: hashBytes(bundled.content),
+          bytes: bundled.content.length,
+          owner: 'skill',
+          skill,
+          agent: agent.id,
+          content: bundled.content,
+        });
+      }
+    }
+
+    if (agent.wrapperFormat && agent.wrapperDir) {
+      for (const skill of skills) {
+        const meta = readSkillMeta(path.join(sourceRoot, 'skills', skill, 'SKILL.md'));
+        if (!meta.name) continue;
+        const { filename, content } = renderWrapper(agent.wrapperFormat, meta);
+        const buf = Buffer.from(content, 'utf8');
+        const dest = toPosix(path.join(agent.wrapperDir, filename));
+        planned.push({
+          path: dest,
+          sha256: hashBytes(buf),
+          bytes: buf.length,
+          owner: 'wrapper',
+          skill,
+          agent: agent.id,
+          content: buf,
+        });
+      }
+    }
+  }
+
+  const byPath = new Map();
+  for (const entry of planned) {
+    const prev = byPath.get(entry.path);
+    if (prev && prev.sha256 !== entry.sha256) {
+      throw conflictError(`conflicting content for ${entry.path}`);
+    }
+    if (!prev) byPath.set(entry.path, entry);
+  }
+  const unique = [...byPath.values()];
+
+  const priorLock = readLock(root);
+  const conflicts = detectConflicts({
+    projectRoot: root,
+    planned: unique,
+    priorLock,
+  });
+  if (conflicts.length > 0 && !force) {
+    throw conflictError(
+      `refusing to overwrite ${conflicts.length} file(s) not owned by a previous install:\n` +
+        conflicts.map((c) => `  - ${c.path}`).join('\n'),
+      're-run with --force to overwrite, or remove the conflicting files',
+    );
+  }
+
+  const reportProgress = (label, index) => {
+    if (onProgress) onProgress(label, index, INSTALL_STEPS.length);
+    else if (!json) {
+      logger.step(`${progressBar(index, INSTALL_STEPS.length)}  ${label}`);
+    }
+  };
+
+  reportProgress(INSTALL_STEPS[0].label, 1);
+
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const backupDir = path.join(root, BACKUP_DIR, stamp);
+  const tx = new Transaction(root, backupDir, { dryRun });
+  for (const entry of unique) {
+    tx.write(entry.path, entry.content);
+  }
+
+  reportProgress(INSTALL_STEPS[1].label, 2);
+  reportProgress(INSTALL_STEPS[2].label, 3);
+
+  const lock = buildLock({
+    agents: agents.map((a) => ({
+      id: a.id,
+      name: a.name,
+      tier: a.tier,
+      skillsDir: a.skillsDir,
+      detected: a.detected,
+    })),
+    files: unique.map(({ path: p, sha256, bytes, owner, skill, agent }) => ({
+      path: p,
+      sha256,
+      bytes,
+      owner,
+      skill,
+      agent,
+    })),
+    now: new Date().toISOString(),
+  });
+  if (!dryRun) {
+    tx.write(LOCKFILE, Buffer.from(serializeLock(lock), 'utf8'));
+  }
+
+  const summary = tx.commit();
+
+  reportProgress(INSTALL_STEPS[3].label, 4);
+  reportProgress(INSTALL_STEPS[4].label, 5);
+
+  let validation = null;
+  if (!dryRun && !skipValidate) {
+    validation = validateInstall(root);
+    if (!validation.ok) {
+      const failed = validation.checks.filter((c) => c.hard && !c.ok);
+      throw verifyError(
+        `installation completed but validation failed:\n` +
+          failed.map((c) => `  - ${c.message}`).join('\n'),
+        failed.find((c) => c.hint)?.hint ?? 'run: qa doctor',
+      );
+    }
+  }
+
+  reportProgress(INSTALL_STEPS[5].label, 6);
+
+  if (dryRun) {
+    if (!json) logger.ok(`dry run: would write ${summary.written} file(s)`);
+  } else if (!json) {
+    logger.ok(`installed ${unique.length} file(s); lockfile ${lockPath(root)}`);
+    for (const step of INSTALL_STEPS) logger.ok(step.label);
+    reportFrameworkFit(root, logger);
+  }
+
+  return {
+    ok: true,
+    dryRun,
+    projectRoot: root,
+    agents: agents.map((a) => a.id),
+    skills: skills.length,
+    files: unique.length,
+    lockfile: dryRun ? null : LOCKFILE,
+    validation,
+  };
+}
+
+export async function runInstall(argv, { log } = {}) {
+  const opts = parseCommonFlags(argv);
+  const logger = log ?? createLogger();
+  if (opts.help) {
+    logger.result(`Usage: qa install [--agent <id>]... [--force] [--dry-run] [--yes] [--json] [--project <dir>]
+
+Copy QA Automation Pack skills into Agent Skills discovery paths
+(.agents/skills/ and .claude/skills/ when applicable), write qa-lock.json,
+and generate thin slash wrappers for agents that need them.`);
+    return EXIT.OK;
+  }
+
+  const result = await executeInstall({
+    projectRoot: opts.project ?? process.cwd(),
+    agentIds: opts.agents,
+    force: opts.force,
+    dryRun: opts.dryRun,
+    json: opts.json,
+    log: logger,
+  });
+
+  logger.result(result);
+  return EXIT.OK;
+}

package/packages/installer/lib/commands/onboard.mjs

@@ -0,0 +1,163 @@
+// Interactive onboarding wizard — default bare `qa` command.
+
+import { EXIT } from '../constants.mjs';
+import { resolveProjectRoot } from '../core/paths.mjs';
+import { parseCommonFlags, wantsNonInteractive } from '../cli/flags.mjs';
+import { scanProject } from '../detect/scan.mjs';
+import { executeInstall } from './install.mjs';
+import { createUi, isCancel } from '../ui/theme.mjs';
+import { createLogger } from '../core/logger.mjs';
+import { listAgentIds } from '../agents/registry.mjs';
+
+function formatScanNote(scan) {
+  const lines = [];
+  if (scan.detectedAgents.length) {
+    for (const a of scan.detectedAgents) lines.push(`✓ ${a.name} detected`);
+  } else {
+    lines.push('· No AI coding assistant markers found (will install shared .agents/skills)');
+  }
+  for (const fw of scan.frameworks) {
+    lines.push(`✓ ${fw[0].toUpperCase()}${fw.slice(1)} project detected`);
+  }
+  for (const lang of scan.languages) {
+    lines.push(`✓ ${lang[0].toUpperCase()}${lang.slice(1)} detected`);
+  }
+  if (scan.environment.git) lines.push('✓ Git repository detected');
+  else lines.push('· Not a git repository');
+  if (scan.environment.packageManager) {
+    lines.push(`✓ Package manager: ${scan.environment.packageManager}`);
+  }
+  return lines.join('\n');
+}
+
+function formatRecommendations(scan) {
+  const recommended = scan.recommendations.filter((r) => r.recommended);
+  return recommended.map((r) => `✓ ${r.label}\n  ${r.reason}`).join('\n\n');
+}
+
+async function guidedFirstRun(ui, { skip }) {
+  if (skip) {
+    ui.note(
+      [
+        'Open your AI coding assistant and try:',
+        '  /qa-init',
+        '  Analyze this repository.',
+        '  Find bugs on the Login page.   (or /qa-explore <url>)',
+      ].join('\n'),
+      'Next steps',
+    );
+    return;
+  }
+
+  ui.note('Open your AI coding assistant (Cursor, Claude Code, OpenCode, …).', 'Step 1');
+  const ready = await ui.confirm('Press Enter / confirm when ready', { initialValue: true });
+  if (isCancel(ready) || !ready) {
+    ui.warn('Skipped guided first-run. Run qa self-test anytime.');
+    return;
+  }
+
+  ui.note('Ask your assistant:\n\n  Analyze this repository.\n\n  (or type /qa-init)', 'Step 2');
+  await ui.confirm('Continue when done', { initialValue: true });
+
+  ui.note(
+    'Ask your assistant:\n\n  Find bugs in the Login page.\n\n  (or /qa-explore <url>)',
+    'Step 3',
+  );
+  await ui.confirm('Continue when done', { initialValue: true });
+
+  ui.success('Your QA Automation Pack is fully operational.');
+}
+
+export async function runOnboard(argv, { log } = {}) {
+  const opts = parseCommonFlags(argv);
+  const logger = log ?? createLogger();
+  if (opts.help) {
+    logger.result(`Usage: qa [--yes] [--project <dir>] [--agent <id>]...
+
+Interactive installer and guided first-run. Same as: qa onboard
+
+Options:
+  --yes / --ci   Skip prompts; install with detected defaults
+  --json         Machine-readable result on stdout
+  --force        Overwrite conflicting files
+  --project <d>  Project root (default: cwd)
+  --agent <id>   Target agent (repeatable). Known: ${listAgentIds().join(', ')}`);
+    return EXIT.OK;
+  }
+
+  const projectRoot = resolveProjectRoot(opts.project ?? process.cwd());
+  const nonInteractive = wantsNonInteractive(opts);
+  const ui = createUi({ quiet: nonInteractive && !opts.json, json: opts.json });
+
+  if (!nonInteractive) {
+    ui.intro('Welcome to QA Automation Pack');
+    ui.logLine('Scanning your environment...');
+  } else if (!opts.json) {
+    logger.step('Scanning environment (non-interactive)...');
+  }
+
+  const scan = scanProject(projectRoot, opts.agents);
+
+  if (!nonInteractive) {
+    ui.note(formatScanNote(scan), 'Environment');
+    ui.note(`Project: ${scan.projectName}`, 'Project');
+    ui.note(formatRecommendations(scan), 'Recommended components');
+
+    const proceed = await ui.confirm('Continue with installation?', { initialValue: true });
+    if (isCancel(proceed) || !proceed) {
+      ui.cancel('Installation cancelled.');
+      return EXIT.OK;
+    }
+
+    if (scan.detectedAgents.length > 1 && opts.agents.length === 0) {
+      const picked = await ui.multiselect(
+        'Which assistants should we install for?',
+        scan.detectedAgents.map((a) => ({ value: a.id, label: a.name })),
+        { required: true },
+      );
+      if (isCancel(picked)) {
+        ui.cancel('Installation cancelled.');
+        return EXIT.OK;
+      }
+      opts.agents = picked;
+    }
+  } else if (!opts.json) {
+    for (const line of formatScanNote(scan).split('\n')) logger.ok(line.replace(/^[✓·]\s*/, ''));
+  }
+
+  const spinner = ui.spinner();
+  if (!nonInteractive) spinner.start('Installing...');
+
+  const result = await executeInstall({
+    projectRoot,
+    agentIds: opts.agents,
+    force: opts.force,
+    dryRun: opts.dryRun,
+    json: opts.json,
+    log: createLogger({ level: opts.json || !nonInteractive ? 'error' : 'info' }),
+    onProgress: (label) => {
+      if (!nonInteractive) spinner.message(label);
+      else if (!opts.json) logger.step(label);
+    },
+  });
+
+  if (!nonInteractive) spinner.stop('Installation complete');
+
+  if (!opts.dryRun && !opts.json) {
+    await guidedFirstRun(ui, { skip: nonInteractive });
+  }
+
+  if (!nonInteractive) {
+    ui.outro('Installation complete — you are ready to QA.');
+  } else if (!opts.json) {
+    logger.ok('Installation complete');
+  }
+
+  logger.result({
+    ...result,
+    projectName: scan.projectName,
+    detectedAgents: scan.detectedAgents.map((a) => a.id),
+    recommendations: scan.recommendations.filter((r) => r.recommended).map((r) => r.id),
+  });
+  return EXIT.OK;
+}