qa-engineer 0.9.0

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "qa-engineer",
+  "version": "0.9.0",
+  "description": "A vendor-neutral Agent Skills pack that teaches AI coding agents to work like senior QA automation engineers.",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://github.com/abisheik88/qa-engineer#readme",
+  "bugs": {
+    "url": "https://github.com/abisheik88/qa-engineer/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/abisheik88/qa-engineer.git"
+  },
+  "engines": {
+    "node": ">=18.18.0"
+  },
+  "bin": {
+    "qa-engineer": "packages/installer/bin/qa.mjs",
+    "qa": "packages/installer/bin/qa.mjs",
+    "qa-pack": "packages/installer/bin/qa.mjs"
+  },
+  "workspaces": [
+    "packages/*"
+  ],
+  "files": [
+    "packages/installer/bin",
+    "packages/installer/lib",
+    "packages/installer/schemas",
+    "packages/installer/package.json",
+    "packages/installer/README.md",
+    "skills",
+    "shared/analysis/lib/qa_analysis",
+    "shared/analysis/schemas",
+    "shared/diagnostics/lib/qa_diagnostics",
+    "shared/diagnostics/schemas",
+    "shared/tooling/qa_tool.py",
+    "shared/frameworks/registry.json",
+    "shared/frameworks/registry.schema.json",
+    "shared/frameworks/registry.mjs",
+    "shared/frameworks/playwright/lib/playwright_analysis.py",
+    "shared/frameworks/selenium/lib/selenium_analysis.py",
+    "shared/frameworks/cypress/lib/cypress_analysis.py",
+    "shared/frameworks/webdriverio/lib/webdriverio_analysis.py",
+    "COMPATIBILITY.md",
+    "!**/__pycache__",
+    "!**/*.pyc",
+    "!**/tests"
+  ],
+  "scripts": {
+    "qa": "node packages/installer/bin/qa.mjs",
+    "eval:live": "python3 tests/evals/run_live.py --baseline tests/evals/baselines/reference.json",
+    "prepublishOnly": "npm run validate:release && npm run validate:doc-claims && npm run validate:docs-commands && npm test && npm run validate:python && npm run validate:evals",
+    "release:checksums": "node scripts/release/release-notes.mjs --checksums",
+    "release:notes": "node scripts/release/release-notes.mjs",
+    "test": "node --test packages/installer/test/*.test.mjs",
+    "validate:architecture": "node scripts/check-architecture-fitness.mjs",
+    "validate:branding": "node scripts/check-branding.mjs",
+    "validate:bundle": "python3 scripts/bundle_python.py --check",
+    "validate:context": "cd shared/analysis/lib && python3 -m qa_analysis.cli context --path tests/fixtures/valid-context.md",
+    "validate:doc-claims": "node scripts/check-doc-claims.mjs",
+    "validate:docs-commands": "node scripts/check-docs-commands.mjs",
+    "validate:evals": "python3 tests/evals/run_evals.py",
+    "validate:keywords": "node scripts/check-keywords.mjs",
+    "validate:knowledge": "node scripts/check-knowledge.mjs",
+    "validate:matrix": "node scripts/check-capability-matrix.mjs",
+    "validate:python": "python3 shared/analysis/lib/run_tests.py",
+    "validate:registry": "node scripts/check-framework-registry.mjs",
+    "validate:release": "node scripts/release/validate-release.mjs",
+    "validate:release-notes": "node scripts/release/release-notes.mjs --check",
+    "validate:skills": "node scripts/validate-skills.mjs",
+    "validate:spec-sync": "node scripts/check-spec-code-sync.mjs",
+    "validate:sync": "node scripts/sync-shared.mjs --check"
+  },
+  "keywords": [
+    "qa-engineer",
+    "agent-skills",
+    "qa",
+    "test-automation",
+    "playwright",
+    "selenium",
+    "cypress",
+    "webdriverio",
+    "ai-agents",
+    "claude-code"
+  ],
+  "dependencies": {
+    "@clack/prompts": "0.11.0"
+  }
+}

package/packages/installer/README.md

@@ -0,0 +1,46 @@
+# @qa-engineer/installer
+
+Copy-based installer for the QA Automation Pack. Installs Agent Skills into `.agents/skills/` and `.claude/skills/`, writes `qa-lock.json`, and generates thin slash wrappers for agents that need them. **No skill code runs at install time.**
+
+## Commands
+
+```bash
+# Interactive (default)
+npx qa-engineer
+npx qa-engineer --yes --project /path/to/app
+
+# Explicit commands
+npx qa-engineer install --project /path/to/app
+npx qa-engineer verify --project /path/to/app
+npx qa-engineer doctor --project /path/to/app
+npx qa-engineer self-test --project /path/to/app
+npx qa-engineer repair --project /path/to/app
+npx qa-engineer update --project /path/to/app
+npx qa-engineer uninstall --project /path/to/app
+```
+
+Root package binaries: `qa` / `qa-pack` / `qa-engineer` (see repository
+`package.json`). The name-matching binary is what makes `npx qa-engineer`
+resolve without `-p`.
+
+From a local checkout before npm publish:
+
+```bash
+npm install
+npm run qa -- --yes --project /path/to/app
+```
+
+## Agents
+
+| Id | Skills path | Wrappers |
+| --- | --- | --- |
+| claude-code | `.claude/skills/` | native |
+| cursor | `.agents/skills/` | native |
+| codex | `.agents/skills/` | native |
+| opencode | `.agents/skills/` | `.opencode/commands/` |
+| gemini-cli | `.agents/skills/` | `.gemini/commands/` |
+| github-copilot | `.agents/skills/` | `.github/prompts/` |
+| antigravity | `.agents/skills/` | `.agents/workflows/` |
+| kimi | `.agents/skills/` | copy-only |
+
+See [docs/installation/](../../docs/installation/README.md).

package/packages/installer/bin/qa.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+// qa-engineer CLI entry.
+
+import { EXIT } from '../lib/constants.mjs';
+import { VERSION } from '../lib/version.mjs';
+import { QaError } from '../lib/core/errors.mjs';
+import { createLogger } from '../lib/core/logger.mjs';
+import { runInstall } from '../lib/commands/install.mjs';
+import { runVerify } from '../lib/commands/verify.mjs';
+import { runDoctor } from '../lib/commands/doctor.mjs';
+import { runOnboard } from '../lib/commands/onboard.mjs';
+import { runSelfTest } from '../lib/commands/self-test.mjs';
+import { runRepair } from '../lib/commands/repair.mjs';
+import { runUpdate } from '../lib/commands/update.mjs';
+import { runUninstall } from '../lib/commands/uninstall.mjs';
+import { listAgentIds } from '../lib/agents/registry.mjs';
+import { COMMANDS, ACCEPTED } from '../lib/cli/commands.mjs';
+import { formatUserError } from '../lib/ui/theme.mjs';
+
+const debug =
+  process.env.QA_DEBUG === '1' ||
+  process.env.QA_DEBUG === 'true' ||
+  process.argv.includes('--debug');
+
+const log = createLogger({ level: process.env.QA_LOG_LEVEL || 'info' });
+
+function printHelp() {
+  const commandLines = COMMANDS.map((c) => `  ${c.name.padEnd(10)} ${c.summary}`).join('\n');
+  log.result(`qa-engineer ${VERSION}
+
+Usage:
+  qa                  Interactive install + guided first-run
+  qa <command> [options]
+
+Commands:
+${commandLines}
+
+Common options:
+  --project <d>  Project root (default: cwd)
+  --agent <id>   Target agent (repeatable). Known: ${listAgentIds().join(', ')}
+  --yes / --ci   Skip prompts
+  --json         Machine-readable stdout
+  --force        Overwrite conflicting files
+  --dry-run      Plan without writing
+  --debug        Show stack traces on unexpected errors
+
+Skills install into .agents/skills/ (most agents) and .claude/skills/
+(Claude Code).`);
+}
+
+function resolveCommand(argv) {
+  const first = argv[0];
+  const commands = new Set(ACCEPTED);
+
+  if (!first) {
+    // Bare `qa`: interactive onboard on TTY; help otherwise.
+    if (process.stdin.isTTY && process.stdout.isTTY) return { cmd: 'onboard', rest: [] };
+    return { cmd: 'help-non-tty', rest: [] };
+  }
+
+  if (commands.has(first)) {
+    return { cmd: first, rest: argv.slice(1) };
+  }
+
+  // Flags without a command → onboard with those flags (e.g. qa --yes --project .)
+  if (first.startsWith('-')) {
+    return { cmd: 'onboard', rest: argv };
+  }
+
+  return { cmd: 'unknown', rest: argv };
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const { cmd, rest } = resolveCommand(argv);
+
+  try {
+    let code = EXIT.OK;
+    switch (cmd) {
+      case 'onboard':
+        code = await runOnboard(rest, { log });
+        break;
+      case 'install':
+        code = await runInstall(rest, { log });
+        break;
+      case 'verify':
+        code = await runVerify(rest, { log });
+        break;
+      case 'doctor':
+        code = await runDoctor(rest, { log });
+        break;
+      case 'self-test':
+        code = await runSelfTest(rest, { log });
+        break;
+      case 'repair':
+        code = await runRepair(rest, { log });
+        break;
+      case 'update':
+        code = await runUpdate(rest, { log });
+        break;
+      case 'uninstall':
+        code = await runUninstall(rest, { log });
+        break;
+      case 'version':
+      case '--version':
+      case '-V':
+        log.result(VERSION);
+        break;
+      case 'help':
+      case '--help':
+      case '-h':
+        printHelp();
+        break;
+      case 'help-non-tty':
+        printHelp();
+        code = EXIT.USAGE;
+        break;
+      case 'unknown':
+      default:
+        log.error(`unknown command: ${argv[0]}`);
+        printHelp();
+        code = EXIT.USAGE;
+    }
+    process.exitCode = code;
+  } catch (error) {
+    if (error instanceof QaError) {
+      log.error(formatUserError(error, { debug }));
+      process.exitCode = error.code ?? EXIT.FAILURE;
+    } else {
+      log.error(formatUserError(error, { debug: true }));
+      process.exitCode = EXIT.FAILURE;
+    }
+  }
+}
+
+main();

package/packages/installer/lib/agents/registry.mjs

@@ -0,0 +1,209 @@
+// Known Agent Skills hosts the installer can target. Detection is best-effort
+// from project markers; users can override with qa.config.json "agents" or
+// `qa install --agent <id>`.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { SHARED_SKILLS_DIR, CLAUDE_SKILLS_DIR } from '../constants.mjs';
+
+/**
+ * @typedef {object} AgentDef
+ * @property {string} id
+ * @property {string} name
+ * @property {number} tier
+ * @property {string} skillsDir  project-relative skills discovery path
+ * @property {string|null} wrapperFormat  wrappers.mjs renderer key, or null
+ * @property {string|null} wrapperDir  where wrappers are written, or null
+ * @property {(root:string)=>boolean} detect
+ */
+
+/** @type {AgentDef[]} */
+export const AGENTS = Object.freeze([
+  {
+    id: 'claude-code',
+    name: 'Claude Code',
+    tier: 1,
+    skillsDir: CLAUDE_SKILLS_DIR,
+    wrapperFormat: null,
+    wrapperDir: null,
+    detect: (root) =>
+      fs.existsSync(path.join(root, '.claude')) ||
+      fs.existsSync(path.join(root, 'CLAUDE.md')),
+  },
+  {
+    id: 'cursor',
+    name: 'Cursor',
+    tier: 2,
+    skillsDir: SHARED_SKILLS_DIR,
+    wrapperFormat: null,
+    wrapperDir: null,
+    detect: (root) =>
+      fs.existsSync(path.join(root, '.cursor')) ||
+      fs.existsSync(path.join(root, '.cursorrules')),
+  },
+  {
+    id: 'codex',
+    name: 'OpenAI Codex CLI',
+    tier: 1,
+    skillsDir: SHARED_SKILLS_DIR,
+    wrapperFormat: null,
+    wrapperDir: null,
+    detect: (root) =>
+      fs.existsSync(path.join(root, '.codex')) ||
+      fs.existsSync(path.join(root, 'AGENTS.md')),
+  },
+  {
+    id: 'opencode',
+    name: 'OpenCode',
+    tier: 1,
+    skillsDir: SHARED_SKILLS_DIR,
+    wrapperFormat: 'command-md',
+    wrapperDir: '.opencode/commands',
+    detect: (root) => fs.existsSync(path.join(root, '.opencode')),
+  },
+  {
+    id: 'gemini-cli',
+    name: 'Gemini CLI',
+    tier: 2,
+    skillsDir: SHARED_SKILLS_DIR,
+    wrapperFormat: 'command-toml',
+    wrapperDir: '.gemini/commands',
+    detect: (root) => fs.existsSync(path.join(root, '.gemini')),
+  },
+  {
+    id: 'github-copilot',
+    name: 'GitHub Copilot',
+    tier: 2,
+    skillsDir: SHARED_SKILLS_DIR,
+    wrapperFormat: 'prompt-md',
+    wrapperDir: '.github/prompts',
+    // Detected by a Copilot-specific marker, not by `.github/` — almost every
+    // repository has `.github/` for Actions or issue templates, so keying on it
+    // reported Copilot for projects that do not use it and wrote 13 wrapper
+    // files nobody asked for. Request them with `--agent github-copilot`.
+    detect: (root) =>
+      fs.existsSync(path.join(root, '.github', 'copilot-instructions.md')) ||
+      fs.existsSync(path.join(root, '.github', 'prompts')),
+  },
+  {
+    id: 'antigravity',
+    name: 'Antigravity',
+    tier: 2,
+    skillsDir: SHARED_SKILLS_DIR,
+    wrapperFormat: 'workflow-md',
+    wrapperDir: '.agents/workflows',
+    // Detected by its own configuration directory, NOT by `.agents/`.
+    // `.agents/skills/` is the shared Agent Skills path that this installer
+    // creates for every host, so keying on `.agents/` made the installer detect
+    // Antigravity purely because it had run once before: a second `install`
+    // silently added 13 wrapper files and reported a host that was never really
+    // there. Detection must never treat the pack's own footprint as evidence.
+    // Request the wrappers explicitly with `--agent antigravity`.
+    detect: (root) => fs.existsSync(path.join(root, '.antigravity')),
+  },
+  {
+    id: 'kimi',
+    name: 'Kimi (Agent Skills copy)',
+    tier: 2,
+    skillsDir: SHARED_SKILLS_DIR,
+    wrapperFormat: null,
+    wrapperDir: null,
+    detect: () => false,
+  },
+  {
+    // The honest fallback when no agent marker is present. Installing into the
+    // shared Agent Skills path is right for any spec-compliant host, but naming
+    // a specific product would report a detection that never happened — so this
+    // entry says exactly what is known: nothing, beyond the standard path.
+    id: 'agent-skills',
+    name: 'Unknown agent (shared Agent Skills path)',
+    tier: null,
+    skillsDir: SHARED_SKILLS_DIR,
+    wrapperFormat: null,
+    wrapperDir: null,
+    detected: false,
+    detect: () => false,
+  },
+]);
+
+/** The id used when nothing could be detected. */
+export const UNKNOWN_AGENT_ID = 'agent-skills';
+
+const BY_ID = new Map(AGENTS.map((a) => [a.id, a]));
+
+export function getAgent(id) {
+  return BY_ID.get(id) ?? null;
+}
+
+export function listAgentIds() {
+  return AGENTS.map((a) => a.id);
+}
+
+/**
+ * Resolve which agents to install for. Explicit ids win; otherwise detect; if
+ * nothing is detected, install once into the shared `.agents/skills` path under
+ * the honest "Unknown agent" entry rather than naming a product that was never
+ * detected. The install location is identical either way — only the report
+ * differs, and a lockfile that claims a detection that did not happen is a
+ * small lie the pack cannot afford.
+ */
+export function resolveAgents(projectRoot, explicitIds = []) {
+  if (explicitIds.length > 0) {
+    const resolved = [];
+    for (const id of explicitIds) {
+      const agent = getAgent(id);
+      if (!agent) throw new Error(`unknown agent id: ${id}`);
+      resolved.push({ ...agent, detected: false, requested: true });
+    }
+    return dedupeBySkillsDir(resolved);
+  }
+
+  const detected = AGENTS.filter((a) => a.detect(projectRoot));
+  if (detected.length > 0) {
+    return dedupeBySkillsDir(detected.map((a) => ({ ...a, detected: true })));
+  }
+
+  // Nothing detected. The shared Agent Skills path still serves Cursor, Codex,
+  // Copilot, OpenCode, Gemini, Antigravity, Kimi, and peers that read it.
+  return [{ ...getAgent(UNKNOWN_AGENT_ID), detected: false }];
+}
+
+/** Prefer one install per unique skillsDir (avoid duplicating files). */
+function dedupeBySkillsDir(agents) {
+  const seen = new Set();
+  const out = [];
+  for (const agent of agents) {
+    if (seen.has(agent.skillsDir)) continue;
+    seen.add(agent.skillsDir);
+    out.push(agent);
+  }
+  // Claude Code always needs its own directory in addition to .agents/skills
+  // when both are requested — restore claude if it was collapsed away incorrectly.
+  const wantsClaude = agents.some((a) => a.id === 'claude-code');
+  if (wantsClaude && !out.some((a) => a.id === 'claude-code')) {
+    out.push(getAgent('claude-code'));
+  }
+  return out;
+}
+
+/**
+ * When installing for "all common hosts", copy into both canonical dirs.
+ */
+export function resolveInstallTargets(projectRoot, explicitIds = []) {
+  const agents = resolveAgents(projectRoot, explicitIds);
+  const hasClaude = agents.some((a) => a.id === 'claude-code');
+  const hasShared = agents.some((a) => a.skillsDir === SHARED_SKILLS_DIR);
+
+  // If only Claude was detected, still install the shared path so other tools
+  // work — but attribute it to the unknown-agent entry, because no host that
+  // reads .agents/skills/ was actually detected here.
+  // If only shared was detected, also install Claude when .claude exists.
+  const targets = [...agents];
+  if (hasClaude && !hasShared) {
+    targets.push({ ...getAgent(UNKNOWN_AGENT_ID), detected: false });
+  }
+  if (hasShared && fs.existsSync(path.join(projectRoot, '.claude')) && !hasClaude) {
+    targets.push({ ...getAgent('claude-code'), detected: true });
+  }
+  return dedupeBySkillsDir(targets);
+}

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

@@ -0,0 +1,29 @@
+// The CLI's command surface, declared once.
+//
+// bin/qa.mjs dispatches on this list, `help` prints from it, and
+// scripts/check-docs-commands.mjs holds the documentation to it — so a command
+// cannot ship undocumented, and the docs cannot name a command that does not
+// exist. (`uninstall` shipped only after being documented in fs-safe.mjs but
+// never implemented; this is the check that would have caught it.)
+
+/** @type {Array<{name: string, summary: string}>} */
+export const COMMANDS = Object.freeze([
+  { name: 'onboard', summary: 'Interactive installer (default when no command is given)' },
+  { name: 'install', summary: 'Non-interactive install into Agent Skills paths' },
+  { name: 'verify', summary: 'Check installed files against qa-lock.json' },
+  { name: 'doctor', summary: 'Diagnose environment and installation' },
+  { name: 'self-test', summary: 'PASS/FAIL smoke checks for the installed pack' },
+  { name: 'repair', summary: 'Fix drifted or missing pack files' },
+  { name: 'update', summary: 'Refresh install from the current pack source' },
+  { name: 'uninstall', summary: 'Remove every file listed in qa-lock.json' },
+  { name: 'version', summary: 'Print pack version' },
+  { name: 'help', summary: 'Show this help' },
+]);
+
+/** Aliases accepted in addition to the command names above. */
+export const ALIASES = Object.freeze(['--version', '-V', '--help', '-h']);
+
+export const COMMAND_NAMES = Object.freeze(COMMANDS.map((c) => c.name));
+
+/** Every token `resolveCommand` accepts as a command. */
+export const ACCEPTED = Object.freeze([...COMMAND_NAMES, ...ALIASES]);

package/packages/installer/lib/cli/flags.mjs

@@ -0,0 +1,64 @@
+// Shared CLI flag parsing helpers for installer commands.
+
+import { usageError } from '../core/errors.mjs';
+
+/**
+ * Parse common flags from argv. Unknown tokens are returned in `rest` unless
+ * `strict` is true (then they throw).
+ *
+ * @param {string[]} argv
+ * @param {{ strict?: boolean }} [opts]
+ */
+export function parseCommonFlags(argv, { strict = true } = {}) {
+  const flags = {
+    yes: false,
+    ci: false,
+    json: false,
+    debug: false,
+    force: false,
+    dryRun: false,
+    help: false,
+    project: null,
+    agents: [],
+    rest: /** @type {string[]} */ ([]),
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--yes' || a === '-y') flags.yes = true;
+    else if (a === '--ci') {
+      flags.ci = true;
+      flags.yes = true;
+    } else if (a === '--json') flags.json = true;
+    else if (a === '--debug') flags.debug = true;
+    else if (a === '--force') flags.force = true;
+    else if (a === '--dry-run') flags.dryRun = true;
+    else if (a === '--help' || a === '-h') flags.help = true;
+    else if (a === '--agent' || a === '-a') {
+      const id = argv[++i];
+      if (!id) throw usageError('--agent requires an id');
+      flags.agents.push(id);
+    } else if (a === '--project' || a === '-C') {
+      flags.project = argv[++i];
+      if (!flags.project) throw usageError('--project requires a path');
+    } else if (strict) {
+      throw usageError(`unknown option: ${a}`);
+    } else {
+      flags.rest.push(a);
+    }
+  }
+
+  if (process.env.CI === 'true' || process.env.CI === '1') {
+    flags.ci = true;
+    flags.yes = true;
+  }
+  if (process.env.QA_DEBUG === '1' || process.env.QA_DEBUG === 'true') {
+    flags.debug = true;
+  }
+
+  return flags;
+}
+
+export function wantsNonInteractive(flags) {
+  return Boolean(flags.yes || flags.ci || !process.stdin.isTTY || !process.stdout.isTTY);
+}