qa-engineer 0.9.0

package/packages/installer/lib/core/errors.mjs

@@ -0,0 +1,29 @@
+// Typed errors carrying an exit code, so the CLI can translate a thrown error
+// into the right process exit without a chain of instanceof checks.
+
+import { EXIT } from '../constants.mjs';
+
+export class QaError extends Error {
+  constructor(message, { code = EXIT.FAILURE, hint = null } = {}) {
+    super(message);
+    this.name = 'QaError';
+    this.code = code; // one of EXIT.*
+    this.hint = hint; // optional actionable next step shown to the user
+  }
+}
+
+export function usageError(message, hint = null) {
+  return new QaError(message, { code: EXIT.USAGE, hint });
+}
+
+export function conflictError(message, hint = null) {
+  return new QaError(message, { code: EXIT.CONFLICT, hint });
+}
+
+export function verifyError(message, hint = null) {
+  return new QaError(message, { code: EXIT.VERIFY, hint });
+}
+
+export function environmentError(message, hint = null) {
+  return new QaError(message, { code: EXIT.ENVIRONMENT, hint });
+}

package/packages/installer/lib/core/fs-safe.mjs

@@ -0,0 +1,236 @@
+// Safe filesystem mutation. Every install, update, or uninstall runs through a
+// Transaction that backs up whatever it is about to overwrite or delete, writes
+// atomically, and — on any failure — restores the project to exactly its prior
+// state. A dry run plans without touching disk.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { environmentError, conflictError } from './errors.mjs';
+
+// Directories whose contents are never the installer's to touch, however a path
+// reaches it. Deleting a repository's own metadata (or its hooks) is not a
+// recoverable mistake, and no pack file legitimately lives there.
+const FORBIDDEN_SEGMENTS = new Set(['.git', '.hg', '.svn']);
+
+/** Contained inside `root` (or equal to it), compared as resolved paths. */
+function isInside(root, target) {
+  if (target === root) return true;
+  const prefix = root.endsWith(path.sep) ? root : `${root}${path.sep}`;
+  return target.startsWith(prefix);
+}
+
+/**
+ * The deepest existing ancestor of `target`, with symlinks resolved, plus the
+ * not-yet-existing suffix appended. Used so containment reflects where a write
+ * would *land*, not merely how its path is spelled.
+ */
+function realTargetPath(target) {
+  let probe = target;
+  while (!fs.existsSync(probe)) {
+    const parent = path.dirname(probe);
+    if (parent === probe) return target; // reached the filesystem root
+    probe = parent;
+  }
+  const suffix = path.relative(probe, target);
+  const realProbe = fs.realpathSync(probe);
+  return suffix ? path.join(realProbe, suffix) : realProbe;
+}
+
+/**
+ * Resolve a project-relative path, refusing anything that escapes the project.
+ *
+ * Every mutation the installer performs is expressed as a path relative to the
+ * project root, and some of those paths come from `qa-lock.json` — a file that is
+ * committed to the consumer's repository and therefore travels with a clone.
+ * Both the lockfile *and* the tree it describes are attacker-influenced, so two
+ * escapes must be closed, and closing only the first is a false sense of safety:
+ *
+ *   lexical   `../../etc/passwd` — spelled outside the project.
+ *   symbolic  `link/file` where `link` is a symlink pointing outside. The path is
+ *             lexically inside; `fs` follows the link and writes or deletes
+ *             outside anyway. Git stores symlinks, so this arrives by clone.
+ *
+ * Containment therefore compares *real* paths, and lives at the single point
+ * every write and delete passes through rather than at each call site.
+ */
+function resolveInside(root, relPath) {
+  if (typeof relPath !== 'string' || relPath.length === 0) {
+    throw conflictError('refusing to operate on an empty path');
+  }
+  if (relPath.includes('\0')) {
+    throw conflictError('refusing to operate on a path containing a null byte');
+  }
+  if (path.isAbsolute(relPath)) {
+    throw conflictError(`refusing to operate on an absolute path: ${relPath}`);
+  }
+  for (const segment of relPath.split(/[\\/]+/)) {
+    if (FORBIDDEN_SEGMENTS.has(segment)) {
+      throw conflictError(
+        `refusing to operate inside ${segment}/: ${relPath}`,
+        'no pack file belongs in a version-control directory',
+      );
+    }
+  }
+
+  const resolvedRoot = path.resolve(root);
+  const target = path.resolve(resolvedRoot, relPath);
+  if (!isInside(resolvedRoot, target)) {
+    throw conflictError(
+      `refusing to operate outside the project: ${relPath}`,
+      'a lockfile or config entry points outside the project root; re-run: qa install --force',
+    );
+  }
+
+  // Symlink containment: where would this actually land?
+  const realRoot = fs.existsSync(resolvedRoot) ? fs.realpathSync(resolvedRoot) : resolvedRoot;
+  if (!isInside(realRoot, realTargetPath(target))) {
+    throw conflictError(
+      `refusing to follow a link out of the project: ${relPath}`,
+      'a path inside the project resolves outside it through a symbolic link',
+    );
+  }
+
+  return target;
+}
+
+/** Create dir and parents; returns the list of directories actually created. */
+function ensureDir(dir, createdDirs) {
+  const missing = [];
+  let current = dir;
+  while (!fs.existsSync(current)) {
+    missing.unshift(current);
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  for (const d of missing) {
+    fs.mkdirSync(d);
+    createdDirs.push(d);
+  }
+}
+
+/** Write content to file via a temp file + rename, so readers never see a partial write. */
+function atomicWrite(file, content) {
+  const tmp = `${file}.qa-tmp-${process.pid}`;
+  fs.writeFileSync(tmp, content);
+  fs.renameSync(tmp, file);
+}
+
+export class Transaction {
+  constructor(projectRoot, backupDir, { dryRun = false } = {}) {
+    this.root = projectRoot;
+    this.backupDir = backupDir; // absolute path for this run's backups
+    this.dryRun = dryRun;
+    this.ops = []; // { kind: 'write'|'delete', rel, content? }
+  }
+
+  write(relPath, content) {
+    resolveInside(this.root, relPath); // reject escapes at staging time, not mid-commit
+    this.ops.push({ kind: 'write', rel: relPath, content: Buffer.isBuffer(content) ? content : Buffer.from(content) });
+  }
+
+  delete(relPath) {
+    resolveInside(this.root, relPath);
+    this.ops.push({ kind: 'delete', rel: relPath });
+  }
+
+  /** Directories the transaction will need to write into, deduplicated. */
+  targetDirs() {
+    const dirs = new Set();
+    for (const op of this.ops) {
+      if (op.kind === 'write') dirs.add(path.dirname(path.join(this.root, op.rel)));
+    }
+    return [...dirs];
+  }
+
+  /** Fail early if a target directory exists but is not writable. */
+  checkPermissions() {
+    for (const dir of this.targetDirs()) {
+      let probe = dir;
+      while (!fs.existsSync(probe)) probe = path.dirname(probe); // nearest existing ancestor
+      try {
+        fs.accessSync(probe, fs.constants.W_OK);
+      } catch {
+        throw environmentError(`no write permission for ${probe}`);
+      }
+    }
+  }
+
+  /**
+   * Execute the staged operations. On any error, everything already done is
+   * rolled back and the original error is rethrown. Returns a summary.
+   */
+  commit() {
+    if (this.dryRun) {
+      return { written: this.ops.filter((o) => o.kind === 'write').length, deleted: this.ops.filter((o) => o.kind === 'delete').length, backedUp: 0, dryRun: true };
+    }
+    this.checkPermissions();
+
+    const created = []; // files that did not exist before (remove on rollback)
+    const createdDirs = []; // directories we made (remove on rollback if empty)
+    const backups = []; // { abs, backup } for files that existed (restore on rollback)
+    let backedUp = 0;
+
+    const backup = (abs, rel) => {
+      const dest = path.join(this.backupDir, rel);
+      ensureDir(path.dirname(dest), createdDirs);
+      fs.copyFileSync(abs, dest);
+      backups.push({ abs, backup: dest });
+      backedUp += 1;
+    };
+
+    try {
+      for (const op of this.ops) {
+        // Re-checked at commit time: staging and commit may be separated by
+        // other code, and containment is cheap to reassert.
+        const abs = resolveInside(this.root, op.rel);
+        if (op.kind === 'write') {
+          if (fs.existsSync(abs)) backup(abs, op.rel);
+          else created.push(abs);
+          ensureDir(path.dirname(abs), createdDirs);
+          atomicWrite(abs, op.content);
+        } else if (op.kind === 'delete') {
+          if (fs.existsSync(abs)) {
+            backup(abs, op.rel);
+            fs.rmSync(abs);
+          }
+        }
+      }
+    } catch (error) {
+      // Roll back: remove created files, restore backups, drop created dirs.
+      for (const abs of created) {
+        if (fs.existsSync(abs)) fs.rmSync(abs, { force: true });
+      }
+      for (const { abs, backup: from } of backups) {
+        fs.copyFileSync(from, abs);
+      }
+      for (const dir of [...createdDirs].reverse()) {
+        try {
+          if (fs.existsSync(dir) && fs.readdirSync(dir).length === 0) fs.rmdirSync(dir);
+        } catch {
+          /* leave non-empty directories in place */
+        }
+      }
+      throw error;
+    }
+
+    return {
+      written: this.ops.filter((o) => o.kind === 'write').length,
+      deleted: this.ops.filter((o) => o.kind === 'delete').length,
+      backedUp,
+      backupDir: backedUp > 0 ? this.backupDir : null,
+      dryRun: false,
+    };
+  }
+}
+
+/** Remove now-empty directories from `dirs` (deepest first). Best-effort. */
+export function pruneEmptyDirs(dirs) {
+  for (const dir of [...dirs].sort((a, b) => b.length - a.length)) {
+    try {
+      if (fs.existsSync(dir) && fs.readdirSync(dir).length === 0) fs.rmdirSync(dir);
+    } catch {
+      /* ignore */
+    }
+  }
+}

package/packages/installer/lib/core/hash.mjs

@@ -0,0 +1,19 @@
+// Content hashing for the lockfile. sha256 over raw bytes, so integrity checks
+// are exact and independent of line endings or text encoding assumptions.
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+
+export const HASH_ALGORITHM = 'sha256';
+
+export function hashBytes(buffer) {
+  return crypto.createHash(HASH_ALGORITHM).update(buffer).digest('hex');
+}
+
+export function hashString(text) {
+  return hashBytes(Buffer.from(text, 'utf8'));
+}
+
+export function hashFile(filePath) {
+  return hashBytes(fs.readFileSync(filePath));
+}

package/packages/installer/lib/core/lockfile.mjs

@@ -0,0 +1,75 @@
+// Reading and writing qa-lock.json — the record of exactly what was installed.
+// The lockfile is the manifest uninstall and verify trust; it is validated
+// against its schema on both read and write so a corrupt lockfile fails loudly.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { LOCKFILE, PACK_NAME } from '../constants.mjs';
+import { VERSION, SPEC_REVISION } from '../version.mjs';
+import { QaError } from './errors.mjs';
+import { validate } from './schema-validate.mjs';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const SCHEMA_PATH = path.join(here, '..', '..', 'schemas', 'qa-lock.schema.json');
+
+export const LOCK_SCHEMA = JSON.parse(fs.readFileSync(SCHEMA_PATH, 'utf8'));
+export const LOCKFILE_VERSION = 1;
+
+export function lockPath(projectRoot) {
+  return path.join(projectRoot, LOCKFILE);
+}
+
+export function readLock(projectRoot) {
+  const file = lockPath(projectRoot);
+  if (!fs.existsSync(file)) return null;
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (error) {
+    throw new QaError(`${LOCKFILE} is corrupt (invalid JSON): ${error.message}`);
+  }
+  const errors = validate(raw, LOCK_SCHEMA);
+  if (errors.length > 0) {
+    throw new QaError(`${LOCKFILE} does not match its schema:\n  - ${errors.join('\n  - ')}`);
+  }
+  return raw;
+}
+
+/**
+ * Assemble a lockfile object. `now` is injected so tests are deterministic;
+ * the CLI passes the real time.
+ */
+export function buildLock({ agents, files, now }) {
+  const lock = {
+    lockfileVersion: LOCKFILE_VERSION,
+    pack: { name: PACK_NAME, version: VERSION, specRevision: SPEC_REVISION },
+    installer: VERSION,
+    generatedAt: now,
+    agents: agents.map((a) => ({
+      id: a.id,
+      name: a.name,
+      tier: a.tier ?? null,
+      skillsDir: a.skillsDir,
+      // Whether project markers actually identified this host, as opposed to it
+      // being requested with --agent or standing in as the unknown-agent path.
+      detected: Boolean(a.detected),
+    })),
+    files: [...files].sort((a, b) => a.path.localeCompare(b.path)),
+    summary: {
+      skills: new Set(files.filter((f) => f.owner === 'skill' && f.skill).map((f) => `${f.agent}:${f.skill}`)).size,
+      files: files.length,
+      wrappers: files.filter((f) => f.owner === 'wrapper').length,
+      directories: new Set(files.map((f) => path.posix.dirname(f.path))).size,
+    },
+  };
+  const errors = validate(lock, LOCK_SCHEMA);
+  if (errors.length > 0) {
+    throw new QaError(`internal error: generated lockfile is invalid:\n  - ${errors.join('\n  - ')}`);
+  }
+  return lock;
+}
+
+export function serializeLock(lock) {
+  return `${JSON.stringify(lock, null, 2)}\n`;
+}

package/packages/installer/lib/core/logger.mjs

@@ -0,0 +1,46 @@
+// A tiny leveled logger. Human-readable progress and diagnostics go to stderr
+// so that stdout carries only a command's primary result (often JSON), keeping
+// the CLI pipeable. Colour is used only when stderr is a TTY.
+
+const LEVELS = { silent: 0, error: 1, warn: 2, info: 3, debug: 4 };
+
+const COLOR = {
+  reset: '\x1b[0m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  yellow: '\x1b[33m',
+  green: '\x1b[32m',
+  cyan: '\x1b[36m',
+};
+
+export function createLogger({ level = 'info', color = process.stderr.isTTY } = {}) {
+  const threshold = LEVELS[level] ?? LEVELS.info;
+  const paint = (c, s) => (color ? `${c}${s}${COLOR.reset}` : s);
+  const at = (name) => LEVELS[name] <= threshold;
+
+  return {
+    level,
+    error(msg) {
+      if (at('error')) process.stderr.write(`${paint(COLOR.red, 'error')} ${msg}\n`);
+    },
+    warn(msg) {
+      if (at('warn')) process.stderr.write(`${paint(COLOR.yellow, 'warn')}  ${msg}\n`);
+    },
+    info(msg) {
+      if (at('info')) process.stderr.write(`${msg}\n`);
+    },
+    step(msg) {
+      if (at('info')) process.stderr.write(`${paint(COLOR.cyan, '›')} ${msg}\n`);
+    },
+    ok(msg) {
+      if (at('info')) process.stderr.write(`${paint(COLOR.green, '✓')} ${msg}\n`);
+    },
+    debug(msg) {
+      if (at('debug')) process.stderr.write(`${paint(COLOR.dim, `· ${msg}`)}\n`);
+    },
+    // Primary machine-readable output belongs on stdout.
+    result(value) {
+      process.stdout.write(typeof value === 'string' ? `${value}\n` : `${JSON.stringify(value, null, 2)}\n`);
+    },
+  };
+}

package/packages/installer/lib/core/manifest.mjs

@@ -0,0 +1,89 @@
+// What the pack ships: the set of skills, the files inside each, and which
+// skills carry bundled deterministic tooling. This manifest deliberately
+// mirrors scripts/bundle_python.py — the two must agree, and a test asserts it.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { listFilesRelative } from './paths.mjs';
+
+// Skills that run deterministic tooling in the consumer's repository. The
+// bundle is materialized at install time, never shipped pre-built.
+// qa-review is knowledge-only and bundles nothing.
+//
+//   packages — importable directories
+//   modules  — single-file framework adapters, bundled flat
+export const BUNDLE_MANIFEST = Object.freeze({
+  'qa-init': Object.freeze({ packages: ['qa_analysis'], modules: [] }),
+  'qa-run': Object.freeze({ packages: ['qa_analysis'], modules: ['playwright_analysis'] }),
+  'qa-debug': Object.freeze({ packages: ['qa_analysis', 'qa_diagnostics'], modules: ['playwright_analysis'] }),
+  'qa-fix': Object.freeze({ packages: ['qa_analysis', 'qa_diagnostics'], modules: [] }),
+  'qa-report': Object.freeze({ packages: ['qa_analysis', 'qa_diagnostics'], modules: [] }),
+  'qa-flaky': Object.freeze({ packages: ['qa_analysis', 'qa_diagnostics'], modules: [] }),
+  'qa-api': Object.freeze({ packages: ['qa_analysis', 'qa_diagnostics'], modules: [] }),
+  'qa-audit': Object.freeze({ packages: ['qa_analysis', 'qa_diagnostics'], modules: [] }),
+});
+
+// Canonical source of each bundled package, relative to the pack root.
+export const BUNDLE_SOURCES = Object.freeze({
+  qa_analysis: 'shared/analysis/lib/qa_analysis',
+  qa_diagnostics: 'shared/diagnostics/lib/qa_diagnostics',
+});
+
+// Non-Python files a bundled package reads at runtime, relative to the pack
+// root and to the package directory. The diagnostics engine validates every
+// diagnosis against its internal schemas, so without these it cannot run.
+export const BUNDLE_PACKAGE_DATA = Object.freeze({
+  // The context CLI validates .qa/context.md against the context contract.
+  qa_analysis: Object.freeze([
+    Object.freeze({ from: 'shared/analysis/schemas', to: 'schemas' }),
+  ]),
+  qa_diagnostics: Object.freeze([
+    Object.freeze({ from: 'shared/diagnostics/schemas/internal', to: 'schemas/internal' }),
+  ]),
+});
+
+// Canonical source of each bundled single-file module.
+export const BUNDLE_MODULE_SOURCES = Object.freeze({
+  playwright_analysis: 'shared/frameworks/playwright/lib/playwright_analysis.py',
+});
+
+// The launcher every bundling skill carries, one level above lib/. It resolves
+// its own lib/ path, so the documented invocation needs no shell features and
+// works identically in PowerShell and cmd.exe.
+export const BUNDLE_LAUNCHER = Object.freeze({
+  from: 'shared/tooling/qa_tool.py',
+  to: 'scripts/qa_tool.py',
+});
+
+// Where bundled code lands inside an installed skill.
+export const BUNDLE_DEST = 'scripts/lib';
+
+/** Package names bundled into a skill (empty array when it bundles nothing). */
+export function bundlePackagesForSkill(skill) {
+  return BUNDLE_MANIFEST[skill]?.packages ?? [];
+}
+
+/** Module names bundled into a skill. */
+export function bundleModulesForSkill(skill) {
+  return BUNDLE_MANIFEST[skill]?.modules ?? [];
+}
+
+/** All skill names shipped by the pack (directories under skills/). */
+export function listSkills(sourceRoot) {
+  const base = path.join(sourceRoot, 'skills');
+  return fs
+    .readdirSync(base, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .sort();
+}
+
+/**
+ * Files that make up a skill, relative to the skill directory. Excludes the
+ * bundled tooling (scripts/lib): it is a generated artifact produced by the
+ * bundle step at install time, not copied from source.
+ */
+export function skillFiles(sourceRoot, skill) {
+  const dir = path.join(sourceRoot, 'skills', skill);
+  return listFilesRelative(dir).filter((rel) => !rel.startsWith(`${BUNDLE_DEST}/`));
+}

package/packages/installer/lib/core/paths.mjs

@@ -0,0 +1,74 @@
+// Locating the pack source (what we install FROM) and the target project (what
+// we install INTO), plus small filesystem helpers used across the installer.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { PACK_NAME } from '../constants.mjs';
+import { environmentError } from './errors.mjs';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+function isPackRoot(dir) {
+  const manifest = path.join(dir, 'package.json');
+  if (!fs.existsSync(manifest) || !fs.existsSync(path.join(dir, 'skills'))) return false;
+  try {
+    return JSON.parse(fs.readFileSync(manifest, 'utf8')).name === PACK_NAME;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The directory that contains the skills to install. Resolved from, in order:
+ *   1. QA_PACK_SOURCE (an explicit override, used by tests and power users),
+ *   2. the nearest ancestor of this file that looks like the pack root.
+ * Whether run from a git checkout or an npm/npx install, both resolve here.
+ */
+export function resolveSourceRoot() {
+  const override = process.env.QA_PACK_SOURCE;
+  if (override) {
+    const resolved = path.resolve(override);
+    if (!isPackRoot(resolved)) {
+      throw environmentError(`QA_PACK_SOURCE is not a pack root: ${resolved}`);
+    }
+    return resolved;
+  }
+  let dir = here;
+  while (true) {
+    if (isPackRoot(dir)) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw environmentError(
+    'could not locate the pack source (no ancestor package.json named ' +
+      `"${PACK_NAME}" with a skills/ directory); set QA_PACK_SOURCE to override`,
+  );
+}
+
+/** The project we install into. Defaults to the current working directory. */
+export function resolveProjectRoot(cwd = process.cwd()) {
+  return path.resolve(cwd);
+}
+
+/** All files under dir, returned as paths relative to dir, sorted, POSIX-style. */
+export function listFilesRelative(dir) {
+  const out = [];
+  const walk = (current, prefix) => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (entry.name === '__pycache__' || entry.name.endsWith('.pyc')) continue;
+      const abs = path.join(current, entry.name);
+      const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) walk(abs, rel);
+      else if (entry.isFile()) out.push(rel);
+    }
+  };
+  if (fs.existsSync(dir)) walk(dir, '');
+  return out.sort();
+}
+
+/** POSIX-normalized relative path, so lockfiles are identical across platforms. */
+export function toPosix(relPath) {
+  return relPath.split(path.sep).join('/');
+}