qa-engineer 0.9.0

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

@@ -0,0 +1,68 @@
+// `qa repair` — fix common install problems by reinstalling pack-owned files.
+
+import { EXIT, LOCKFILE } from '../constants.mjs';
+import { resolveProjectRoot } from '../core/paths.mjs';
+import { readLock } from '../core/lockfile.mjs';
+import { parseCommonFlags } from '../cli/flags.mjs';
+import { executeInstall } from './install.mjs';
+import { validateInstall } from '../core/validate-install.mjs';
+import { createLogger } from '../core/logger.mjs';
+
+export async function runRepair(argv, { log } = {}) {
+  const opts = parseCommonFlags(argv);
+  const logger = log ?? createLogger();
+  if (opts.help) {
+    logger.result(`Usage: qa repair [--project <dir>] [--json] [--dry-run]
+
+Repair a broken or drifted installation:
+  - missing lockfile → fresh install
+  - drifted / missing pack files → reinstall with --force
+  - then re-validate`);
+    return EXIT.OK;
+  }
+
+  const root = resolveProjectRoot(opts.project ?? process.cwd());
+  const prior = readLock(root);
+  const before = validateInstall(root);
+
+  if (!opts.json) {
+    logger.step(`repairing ${root}`);
+    if (!prior) logger.warn(`no ${LOCKFILE} — performing fresh install`);
+    else {
+      const bad = before.checks.filter((c) => !c.ok);
+      if (bad.length === 0) logger.ok('installation already healthy — refreshing anyway');
+      else for (const c of bad) logger.warn(`${c.id}: ${c.message}`);
+    }
+  }
+
+  const agentIds = opts.agents.length
+    ? opts.agents
+    : (prior?.agents ?? []).map((a) => a.id).filter(Boolean);
+
+  const result = await executeInstall({
+    projectRoot: root,
+    agentIds,
+    force: true,
+    dryRun: opts.dryRun,
+    json: opts.json,
+    log: logger,
+  });
+
+  const after = opts.dryRun ? before : validateInstall(root);
+
+  if (!opts.json) {
+    if (after.ok) logger.ok('repair complete — installation validated');
+    else logger.error('repair finished but validation still failing — run: qa doctor');
+  }
+
+  logger.result({
+    ok: after.ok,
+    repaired: true,
+    dryRun: opts.dryRun,
+    before: before.checks.filter((c) => !c.ok).map((c) => c.id),
+    after: after.checks,
+    install: result,
+  });
+
+  return after.ok || opts.dryRun ? EXIT.OK : EXIT.VERIFY;
+}

package/packages/installer/lib/commands/self-test.mjs

@@ -0,0 +1,45 @@
+// `qa self-test` — verify an installation is operational.
+
+import { EXIT } from '../constants.mjs';
+import { resolveProjectRoot } from '../core/paths.mjs';
+import { parseCommonFlags } from '../cli/flags.mjs';
+import { validateInstall } from '../core/validate-install.mjs';
+import { createLogger } from '../core/logger.mjs';
+
+export async function runSelfTest(argv, { log } = {}) {
+  const opts = parseCommonFlags(argv);
+  const logger = log ?? createLogger();
+  if (opts.help) {
+    logger.result(`Usage: qa self-test [--project <dir>] [--json]
+
+Verify skills, lockfile integrity, bundled engine, contracts, and environment.
+Prints PASS/FAIL per check. Does not invoke live AI agents.`);
+    return EXIT.OK;
+  }
+
+  const root = resolveProjectRoot(opts.project ?? process.cwd());
+  const { ok, checks } = validateInstall(root);
+
+  if (!opts.json) {
+    logger.step(`self-test — ${root}`);
+    for (const check of checks) {
+      const tag = check.ok ? 'PASS' : check.hard ? 'FAIL' : 'WARN';
+      const line = `[${tag}] ${check.id}: ${check.message}`;
+      if (check.ok) logger.ok(line);
+      else if (check.hard) logger.error(line);
+      else logger.warn(line);
+      if (!check.ok && check.hint) logger.info(`       → ${check.hint}`);
+    }
+    if (ok) logger.ok('self-test PASSED');
+    else logger.error('self-test FAILED');
+  }
+
+  logger.result({
+    ok,
+    projectRoot: root,
+    checks,
+    note: 'Live skill activation is verified in your AI assistant (see guided first-run).',
+  });
+
+  return ok ? EXIT.OK : EXIT.VERIFY;
+}

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

@@ -0,0 +1,167 @@
+// `qa uninstall` — remove exactly what was installed, and nothing else.
+//
+// The lockfile is the manifest: every path it lists was written by the installer
+// with a recorded hash, so uninstall knows precisely what it owns. Anything not
+// in the lockfile is the user's and is never touched.
+//
+// Removal runs through the same Transaction as install, update, and repair, so
+// it inherits the same guarantees: every deleted file is backed up first, and a
+// failure part-way through restores the project to its prior state rather than
+// leaving a half-removed install.
+//
+// A file that drifted from its recorded hash may carry local edits. Deleting it
+// silently would destroy work, so drift stops the uninstall and names the files;
+// `--force` proceeds (still with backups).
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { EXIT, LOCKFILE, BACKUP_DIR } from '../constants.mjs';
+import { resolveProjectRoot } from '../core/paths.mjs';
+import { readLock, lockPath } from '../core/lockfile.mjs';
+import { hashFile } from '../core/hash.mjs';
+import { Transaction, pruneEmptyDirs } from '../core/fs-safe.mjs';
+import { conflictError, verifyError } from '../core/errors.mjs';
+import { createLogger } from '../core/logger.mjs';
+import { parseCommonFlags } from '../cli/flags.mjs';
+
+/** Every __pycache__ directory at or beneath `dir` (empty list if dir is gone). */
+function findPycache(dir) {
+  const found = [];
+  if (!fs.existsSync(dir)) return found;
+  const walk = (current) => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const full = path.join(current, entry.name);
+      if (entry.name === '__pycache__') found.push(full);
+      else walk(full);
+    }
+  };
+  walk(dir);
+  return found;
+}
+
+export async function runUninstall(argv, { log } = {}) {
+  const opts = parseCommonFlags(argv);
+  const logger = log ?? createLogger();
+  if (opts.help) {
+    logger.result(`Usage: qa uninstall [--project <dir>] [--json] [--dry-run] [--force]
+
+Remove every file listed in ${LOCKFILE}, then the lockfile itself.
+Only pack-owned files are removed; anything else is left alone.
+
+  --dry-run   list what would be removed, write nothing
+  --force     remove files that drifted from their recorded hash`);
+    return EXIT.OK;
+  }
+
+  const root = resolveProjectRoot(opts.project ?? process.cwd());
+  const lock = readLock(root);
+  if (!lock) {
+    if (!opts.json) {
+      logger.error(`FAIL  no ${LOCKFILE} in ${root}`);
+      logger.info('  → nothing to uninstall');
+    }
+    throw verifyError(`no ${LOCKFILE} in ${root}`, 'nothing to uninstall');
+  }
+
+  const present = [];
+  const missing = [];
+  const drifted = [];
+  for (const entry of lock.files) {
+    const abs = path.join(root, entry.path);
+    if (!fs.existsSync(abs)) {
+      missing.push(entry.path);
+      continue;
+    }
+    if (hashFile(abs) !== entry.sha256) drifted.push(entry.path);
+    present.push(entry.path);
+  }
+
+  if (drifted.length > 0 && !opts.force) {
+    if (!opts.json) {
+      logger.error(`FAIL  ${drifted.length} installed file(s) have local changes`);
+      for (const p of drifted.slice(0, 20)) logger.info(`  ${p}`);
+      if (drifted.length > 20) logger.info(`  … and ${drifted.length - 20} more`);
+      logger.info('  → keep them: back them up, then re-run');
+      logger.info('  → discard them: qa uninstall --force');
+    }
+    throw conflictError(
+      `${drifted.length} installed file(s) drifted from ${LOCKFILE}`,
+      'run: qa uninstall --force to remove them anyway',
+    );
+  }
+
+  if (!opts.json) {
+    logger.step(`project: ${root}`);
+    logger.step(`removing: ${present.length} file(s)${missing.length ? `, ${missing.length} already gone` : ''}`);
+  }
+
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const tx = new Transaction(root, path.join(root, BACKUP_DIR, stamp), { dryRun: opts.dryRun });
+  for (const rel of present) tx.delete(rel);
+  if (fs.existsSync(lockPath(root))) tx.delete(LOCKFILE);
+  const summary = tx.commit();
+
+  // Byproducts of the pack's own bundled code: Python writes __pycache__ next to
+  // the modules it imports, so those directories exist because of us and are not
+  // in the lockfile. They are regenerable bytecode, so they are removed without
+  // a backup — but only under directories that held pack-owned bundle files,
+  // never anywhere else in the project.
+  let removedByproducts = 0;
+  if (!opts.dryRun) {
+    const bundleDirs = new Set();
+    for (const rel of lock.files) {
+      const marker = rel.path.indexOf('scripts/lib/');
+      if (marker !== -1) {
+        bundleDirs.add(path.join(root, rel.path.slice(0, marker + 'scripts/lib'.length)));
+      }
+    }
+    for (const bundleDir of bundleDirs) {
+      for (const cache of findPycache(bundleDir)) {
+        fs.rmSync(cache, { recursive: true, force: true });
+        removedByproducts += 1;
+      }
+    }
+  }
+
+  // Leave no empty skeleton behind: prune directories the pack created, deepest
+  // first, stopping at anything that still holds a file the user owns.
+  let prunedDirs = 0;
+  if (!opts.dryRun) {
+    const dirs = new Set();
+    for (const rel of [...present, ...missing]) {
+      let dir = path.dirname(path.join(root, rel));
+      // Walk up to (but never past) the project root.
+      while (dir.startsWith(root) && dir !== root) {
+        dirs.add(dir);
+        dir = path.dirname(dir);
+      }
+    }
+    const before = [...dirs].filter((d) => fs.existsSync(d)).length;
+    pruneEmptyDirs([...dirs]);
+    prunedDirs = before - [...dirs].filter((d) => fs.existsSync(d)).length;
+  }
+
+  if (!opts.json) {
+    if (opts.dryRun) logger.ok(`dry run: would remove ${present.length + 1} file(s)`);
+    else {
+      logger.ok(`uninstalled ${summary.deleted} file(s); removed ${LOCKFILE}`);
+      if (prunedDirs > 0) logger.step(`pruned ${prunedDirs} empty directory(ies)`);
+      if (summary.backupDir) logger.step(`backup: ${path.relative(root, summary.backupDir)}`);
+    }
+  }
+
+  logger.result({
+    ok: true,
+    uninstalled: true,
+    dryRun: Boolean(opts.dryRun),
+    removed: opts.dryRun ? present.length + 1 : summary.deleted,
+    alreadyMissing: missing.length,
+    driftedRemoved: opts.force ? drifted.length : 0,
+    removedByproducts,
+    prunedDirectories: prunedDirs,
+    backupDir: summary.backupDir ?? null,
+  });
+
+  return EXIT.OK;
+}

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

@@ -0,0 +1,69 @@
+// `qa update` — refresh an install from the current pack source.
+
+import { EXIT } from '../constants.mjs';
+import { resolveProjectRoot, resolveSourceRoot } from '../core/paths.mjs';
+import { readLock } from '../core/lockfile.mjs';
+import { parseCommonFlags } from '../cli/flags.mjs';
+import { executeInstall } from './install.mjs';
+import { VERSION } from '../version.mjs';
+import { createLogger } from '../core/logger.mjs';
+
+export async function runUpdate(argv, { log } = {}) {
+  const opts = parseCommonFlags(argv);
+  const logger = log ?? createLogger();
+  if (opts.help) {
+    logger.result(`Usage: qa update [--project <dir>] [--json] [--dry-run]
+
+Update the installed pack from the current source tree (checkout or npm pack).
+After registry publish, this will resolve the latest published version.
+Always re-validates after updating.`);
+    return EXIT.OK;
+  }
+
+  const root = resolveProjectRoot(opts.project ?? process.cwd());
+  const sourceRoot = resolveSourceRoot();
+  const lock = readLock(root);
+  const installedVersion = lock?.pack?.version ?? null;
+
+  if (!opts.json) {
+    logger.step(`pack source: ${sourceRoot}`);
+    logger.step(`available version: ${VERSION}`);
+    if (installedVersion) logger.step(`installed version: ${installedVersion}`);
+    else logger.warn('no prior install found — will install fresh');
+    if (installedVersion === VERSION) {
+      logger.info('already on the source version — refreshing files for integrity');
+    }
+    logger.info(
+      'Note: registry-based updates activate after the package is published to npm.',
+    );
+  }
+
+  const agentIds = opts.agents.length
+    ? opts.agents
+    : (lock?.agents ?? []).map((a) => a.id).filter(Boolean);
+
+  const result = await executeInstall({
+    projectRoot: root,
+    agentIds,
+    force: true,
+    dryRun: opts.dryRun,
+    json: opts.json,
+    log: logger,
+  });
+
+  if (!opts.json) {
+    logger.ok(`updated to ${VERSION}`);
+  }
+
+  logger.result({
+    ok: true,
+    dryRun: opts.dryRun,
+    previousVersion: installedVersion,
+    version: VERSION,
+    sourceRoot,
+    registryNote: 'npm registry updates available after publish',
+    install: result,
+  });
+
+  return EXIT.OK;
+}

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

@@ -0,0 +1,62 @@
+// `qa verify` — compare on-disk files to qa-lock.json hashes.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { EXIT, LOCKFILE } from '../constants.mjs';
+import { resolveProjectRoot } from '../core/paths.mjs';
+import { readLock } from '../core/lockfile.mjs';
+import { hashFile } from '../core/hash.mjs';
+import { verifyError } from '../core/errors.mjs';
+import { createLogger } from '../core/logger.mjs';
+import { parseCommonFlags } from '../cli/flags.mjs';
+
+export async function runVerify(argv, { log } = {}) {
+  const opts = parseCommonFlags(argv);
+  const logger = log ?? createLogger();
+  if (opts.help) {
+    logger.result(`Usage: qa verify [--project <dir>] [--json]
+
+Verify installed files match qa-lock.json.
+On failure: run qa repair`);
+    return EXIT.OK;
+  }
+
+  const root = resolveProjectRoot(opts.project ?? process.cwd());
+  const lock = readLock(root);
+  if (!lock) {
+    if (!opts.json) {
+      logger.error(`FAIL  no ${LOCKFILE}`);
+      logger.info('  → run: qa install');
+    }
+    throw verifyError(`no ${LOCKFILE} in ${root}`, 'run: qa install');
+  }
+
+  const problems = [];
+  for (const entry of lock.files) {
+    const abs = path.join(root, entry.path);
+    if (!fs.existsSync(abs)) {
+      problems.push({ path: entry.path, reason: 'missing' });
+      continue;
+    }
+    const actual = hashFile(abs);
+    if (actual !== entry.sha256) {
+      problems.push({ path: entry.path, reason: 'hash mismatch' });
+    }
+  }
+
+  if (problems.length > 0) {
+    if (!opts.json) {
+      logger.error(`FAIL  ${problems.length} drift(s) detected`);
+      for (const p of problems.slice(0, 20)) logger.info(`  ${p.path}: ${p.reason}`);
+      if (problems.length > 20) logger.info(`  … and ${problems.length - 20} more`);
+      logger.info('  → run: qa repair');
+    }
+    throw verifyError('installed files drifted from qa-lock.json', 'run: qa repair');
+  }
+
+  if (!opts.json) {
+    logger.ok(`PASS  verified ${lock.files.length} file(s)`);
+  }
+  logger.result({ ok: true, files: lock.files.length, pack: lock.pack });
+  return EXIT.OK;
+}

package/packages/installer/lib/constants.mjs

@@ -0,0 +1,34 @@
+// Names and paths shared across the installer. Kept in one place so the CLI,
+// commands, and tests agree on where things live.
+
+export const PACK_NAME = 'qa-engineer';
+
+// Files the installer writes into the target project root.
+export const CONFIG_FILE = 'qa.config.json';
+export const LOCKFILE = 'qa-lock.json';
+
+// The pack's private working directory inside a target project.
+export const QA_DIR = '.qa';
+export const BACKUP_DIR = `${QA_DIR}/backups`;
+
+// Marker line prepended to every generated invocation wrapper. Wrappers are
+// disposable build artifacts; this line tells humans and `verify` that the file
+// is pack-owned and regenerated, never hand-edited.
+export const GENERATED_MARKER =
+  'Generated by qa-engineer — do not edit. Regenerate with: qa install --force';
+
+// Process exit codes. Stable so scripts and CI can branch on them.
+export const EXIT = {
+  OK: 0,
+  FAILURE: 1, // an operation failed
+  USAGE: 2, // the command line was wrong
+  CONFLICT: 3, // refused to overwrite un-owned files without --force
+  VERIFY: 4, // installed files drifted from the lockfile
+  ENVIRONMENT: 5, // the environment cannot support the requested operation
+};
+
+// The two canonical skill discovery directories. Every target agent reads one
+// of these; agent-specific directories are alternatives, not additions, so the
+// planner installs each skill once per unique directory (no duplicates).
+export const SHARED_SKILLS_DIR = '.agents/skills';
+export const CLAUDE_SKILLS_DIR = '.claude/skills';

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

@@ -0,0 +1,124 @@
+// Bundling deterministic tooling, integrated into installation. Skills that run
+// a Python engine need that engine to travel with them (self-containment). The
+// installer materializes it by COPYING the canonical code from shared/ into the
+// installed skill's scripts/lib/ — a pure file copy, no code executed at install
+// time, honoring the SECURITY.md guarantee. This mirrors what
+// scripts/bundle_python.py does for repository development; users never run it.
+//
+// Deep verification (that the bundle *runs* under the user's interpreter)
+// requires running Python and therefore lives in `qa doctor`, an explicit,
+// user-invoked diagnostic — never in the install path.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import {
+  BUNDLE_MANIFEST,
+  BUNDLE_SOURCES,
+  BUNDLE_PACKAGE_DATA,
+  BUNDLE_MODULE_SOURCES,
+  BUNDLE_LAUNCHER,
+  BUNDLE_DEST,
+} from './manifest.mjs';
+import { listFilesRelative } from './paths.mjs';
+
+/** Bundle file entries for one skill, relative to the skill directory. */
+export function bundleFilesForSkill(sourceRoot, skill) {
+  const entry = BUNDLE_MANIFEST[skill];
+  if (!entry) return [];
+  const entries = [];
+
+  for (const pkg of entry.packages) {
+    const src = path.join(sourceRoot, BUNDLE_SOURCES[pkg]);
+    if (!fs.existsSync(src)) {
+      throw new Error(`bundled package source missing: ${BUNDLE_SOURCES[pkg]} (needed by ${skill})`);
+    }
+    for (const rel of listFilesRelative(src)) {
+      entries.push({
+        rel: `${BUNDLE_DEST}/${pkg}/${rel}`,
+        content: fs.readFileSync(path.join(src, rel)),
+      });
+    }
+    // Package data the code reads at runtime (internal schemas). Without these
+    // the diagnostics engine raises on every diagnosis.
+    for (const data of BUNDLE_PACKAGE_DATA[pkg] ?? []) {
+      const dataSrc = path.join(sourceRoot, data.from);
+      if (!fs.existsSync(dataSrc)) {
+        throw new Error(`bundled package data missing: ${data.from} (needed by ${skill})`);
+      }
+      for (const rel of listFilesRelative(dataSrc)) {
+        entries.push({
+          rel: `${BUNDLE_DEST}/${pkg}/${data.to}/${rel}`,
+          content: fs.readFileSync(path.join(dataSrc, rel)),
+        });
+      }
+    }
+  }
+
+  // The launcher: the documented entry point, beside lib/ rather than inside it.
+  const launcherSrc = path.join(sourceRoot, BUNDLE_LAUNCHER.from);
+  if (!fs.existsSync(launcherSrc)) {
+    throw new Error(`bundled launcher missing: ${BUNDLE_LAUNCHER.from} (needed by ${skill})`);
+  }
+  entries.push({ rel: BUNDLE_LAUNCHER.to, content: fs.readFileSync(launcherSrc) });
+
+  for (const mod of entry.modules) {
+    const src = path.join(sourceRoot, BUNDLE_MODULE_SOURCES[mod]);
+    if (!fs.existsSync(src)) {
+      throw new Error(`bundled module source missing: ${BUNDLE_MODULE_SOURCES[mod]} (needed by ${skill})`);
+    }
+    entries.push({
+      rel: `${BUNDLE_DEST}/${path.basename(src)}`,
+      content: fs.readFileSync(src),
+    });
+  }
+
+  return entries;
+}
+
+/** True if any skill carries bundled tooling (used to gate doctor's deep check). */
+export function packHasBundles() {
+  return Object.keys(BUNDLE_MANIFEST).length > 0;
+}
+
+/** Locate a Python 3 interpreter, or null. Used only by doctor. */
+export function findPython() {
+  for (const candidate of ['python3', 'python']) {
+    const probe = spawnSync(candidate, ['--version'], { encoding: 'utf8' });
+    if (probe.status === 0) {
+      const version = (probe.stdout || probe.stderr).trim();
+      return { bin: candidate, version };
+    }
+  }
+  return null;
+}
+
+// Runs inside the bundle with only the bundle on PYTHONPATH. Importing is not
+// enough: a missing data file only surfaces when the engine actually runs, which
+// is exactly the failure this check exists to catch.
+const SMOKE = `
+import json, sys
+names = json.loads(sys.argv[1])
+for name in names:
+    __import__(name)
+if "qa_diagnostics" in names:
+    from qa_diagnostics import engine
+    diagnosis = engine.diagnose({
+        "tests": {"total": 1, "passed": 0, "failed": 1, "skipped": 0},
+        "executed": [{"title": "t", "status": "failed", "message": "no such element: #cart",
+                      "file": "t.spec.ts", "retries": 0}],
+    })
+    assert diagnosis["entries"], "engine produced no diagnosis entries"
+`;
+
+/**
+ * Verify bundled tooling RUNS using ONLY its own directory on PYTHONPATH —
+ * proving self-containment under the user's interpreter. Doctor-only.
+ */
+export function verifyImports({ pythonBin, libDir, packages }) {
+  const result = spawnSync(pythonBin, ['-c', SMOKE, JSON.stringify(packages)], {
+    env: { PYTHONPATH: libDir, PATH: process.env.PATH ?? '' },
+    encoding: 'utf8',
+  });
+  return { ok: result.status === 0, stderr: (result.stderr ?? '').trim() };
+}

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

@@ -0,0 +1,73 @@
+// Loading, validating, and defaulting qa.config.json. The file is optional;
+// when absent, DEFAULTS apply. When present, it is validated against the
+// published schema and merged over the defaults.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CONFIG_FILE } from '../constants.mjs';
+import { QaError, usageError } 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.config.schema.json');
+
+export const CONFIG_SCHEMA = JSON.parse(fs.readFileSync(SCHEMA_PATH, 'utf8'));
+
+// Every documented default in one place. The effective configuration is these
+// values with any qa.config.json overrides applied on top.
+export const DEFAULTS = Object.freeze({
+  version: 1,
+  frameworks: {},
+  browser: { default: 'chromium' },
+  output: { directory: 'qa-artifacts' },
+  logging: { level: 'info' },
+  telemetry: { enabled: false },
+  plugins: [],
+  agents: [],
+});
+
+function deepMerge(base, override) {
+  const result = Array.isArray(base) ? [...base] : { ...base };
+  for (const [key, value] of Object.entries(override ?? {})) {
+    if (value && typeof value === 'object' && !Array.isArray(value) && typeof result[key] === 'object') {
+      result[key] = deepMerge(result[key], value);
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+/** The starter config written by `qa init`. Minimal on purpose — only version. */
+export function starterConfig() {
+  return { version: 1 };
+}
+
+/** Validate a raw config object; throws a usage error listing every problem. */
+export function validateConfig(raw, source = CONFIG_FILE) {
+  const errors = validate(raw, CONFIG_SCHEMA);
+  if (errors.length > 0) {
+    throw usageError(`${source} is invalid:\n  - ${errors.join('\n  - ')}`);
+  }
+  return raw;
+}
+
+/**
+ * Load the effective configuration for a project. Returns { config, source }
+ * where source is the file path when one was read, or null for defaults.
+ */
+export function loadConfig(projectRoot) {
+  const file = path.join(projectRoot, CONFIG_FILE);
+  if (!fs.existsSync(file)) {
+    return { config: structuredClone(DEFAULTS), source: null };
+  }
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (error) {
+    throw new QaError(`${CONFIG_FILE} is not valid JSON: ${error.message}`);
+  }
+  validateConfig(raw, file);
+  return { config: deepMerge(DEFAULTS, raw), source: file };
+}

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

@@ -0,0 +1,29 @@
+// Conflict detection. The installer must never silently overwrite a file it
+// does not own. A conflict is an on-disk file that (a) we are about to write,
+// (b) differs from what we would write, and (c) was not recorded as pack-owned
+// by a previous install. Files owned by the prior lockfile are ours to update;
+// byte-identical files are a no-op, not a conflict.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { hashFile } from './hash.mjs';
+
+/**
+ * @param {object}   args
+ * @param {string}   args.projectRoot
+ * @param {Array<{path:string, sha256:string}>} args.planned  files we intend to write
+ * @param {object|null} args.priorLock  the previous lockfile, if any
+ * @returns {Array<{path:string, reason:string}>}  conflicts (empty = safe)
+ */
+export function detectConflicts({ projectRoot, planned, priorLock }) {
+  const owned = new Set((priorLock?.files ?? []).map((f) => f.path));
+  const conflicts = [];
+  for (const entry of planned) {
+    const abs = path.join(projectRoot, entry.path);
+    if (!fs.existsSync(abs)) continue; // brand-new file, no conflict
+    if (owned.has(entry.path)) continue; // pack-owned, safe to update
+    if (hashFile(abs) === entry.sha256) continue; // identical content, no-op
+    conflicts.push({ path: entry.path, reason: 'exists and is not owned by a previous install' });
+  }
+  return conflicts;
+}