qa-engineer 0.10.0 → 0.11.0

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

@@ -109,6 +109,80 @@ function ensureDir(dir, createdDirs) {
   }
 }
 
+/**
+ * The target of a symlink at `abs`, or null when there is no link there.
+ *
+ * `lstat` rather than `exists`, because a link pointing at something that has been
+ * deleted still exists as a link and still has to be replaced rather than written over.
+ */
+export function readLinkTarget(abs) {
+  try {
+    const stat = fs.lstatSync(abs);
+    if (!stat.isSymbolicLink()) return null;
+    return fs.readlinkSync(abs);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Create a directory link, choosing the kind the platform will allow.
+ *
+ * On Windows a symbolic link needs either administrator rights or Developer Mode, while
+ * a *junction* needs neither and behaves the same for reading a directory. Preferring a
+ * junction there is the difference between a global install that works for every Windows
+ * developer and one that works only for those running an elevated shell.
+ */
+export function createLink(abs, target) {
+  const type = process.platform === 'win32' ? 'junction' : 'dir';
+  fs.symlinkSync(target, abs, type);
+}
+
+/**
+ * Can this filesystem hold a directory link at all?
+ *
+ * Asked once, before planning, rather than discovered halfway through a transaction.
+ * The answer is no more often than it looks: a FAT- or exFAT-formatted volume supports
+ * neither symlinks nor junctions, some container and network mounts refuse them, and a
+ * Windows host without Developer Mode refuses symlinks (which is why `createLink` asks
+ * for a junction there instead).
+ *
+ * When the answer is no the installer copies instead. A global install that fails
+ * outright on a USB stick would be a worse tool than one that uses more disk.
+ */
+export function canLink(root) {
+  const probe = path.join(root, `.qa-linkprobe-${process.pid}`);
+  const target = path.join(root, `.qa-linktarget-${process.pid}`);
+  try {
+    fs.mkdirSync(target, { recursive: true });
+    createLink(probe, target);
+    const ok = readLinkTarget(probe) !== null;
+    fs.unlinkSync(probe);
+    fs.rmdirSync(target);
+    return ok;
+  } catch {
+    // Clean up whatever got as far as existing, then report no.
+    try {
+      if (readLinkTarget(probe) !== null) fs.unlinkSync(probe);
+    } catch { /* nothing to undo */ }
+    try {
+      if (fs.existsSync(target)) fs.rmdirSync(target);
+    } catch { /* nothing to undo */ }
+    return false;
+  }
+}
+
+/** True when the file already holds exactly these bytes. */
+function sameContent(file, content) {
+  try {
+    const stat = fs.statSync(file);
+    if (!stat.isFile() || stat.size !== content.length) return false;
+    return fs.readFileSync(file).equals(content);
+  } catch {
+    return false;
+  }
+}
+
 /** 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}`;
@@ -134,6 +208,24 @@ export class Transaction {
     this.ops.push({ kind: 'delete', rel: relPath });
   }
 
+  /**
+   * Stage a symbolic link at `relPath` pointing at `targetAbs`.
+   *
+   * Links are how a global install serves an agent without copying the skills again.
+   * They go through the transaction rather than around it so a half-linked install
+   * rolls back like a half-written one — and because replacing a link silently would
+   * lose where the old one pointed.
+   *
+   * Only a link may be replaced by a link. A real directory at the target path belongs
+   * to someone else, and the conflict detector is what decides whether the user wants it
+   * overwritten; reaching here with one is a bug, so it throws rather than deleting a
+   * directory nobody agreed to lose.
+   */
+  link(relPath, targetAbs) {
+    resolveInside(this.root, relPath);
+    this.ops.push({ kind: 'link', rel: relPath, target: targetAbs });
+  }
+
   /** Directories the transaction will need to write into, deduplicated. */
   targetDirs() {
     const dirs = new Set();
@@ -169,6 +261,8 @@ export class Transaction {
     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 unchanged = 0; // already byte-identical: neither written nor backed up
+    const replacedLinks = []; // { abs, target } symlinks removed (recreate on rollback)
     let backedUp = 0;
 
     const backup = (abs, rel) => {
@@ -185,21 +279,65 @@ export class Transaction {
         // 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);
+          if (fs.existsSync(abs)) {
+            // Reinstalling identical content is the common case for update and repair.
+            // Backing it up copies the whole install into a dated directory on every
+            // run — three copies of the engine after two commands — and restoring a
+            // byte-identical file on rollback achieves nothing.
+            if (sameContent(abs, op.content)) {
+              unchanged += 1;
+              continue;
+            }
+            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)) {
+          // A link is deleted by unlinking it, and "backed up" by remembering where it
+          // pointed. Copying it would follow the link and try to copy a directory as a
+          // file, which is how uninstall crashed on a global install.
+          const linkTarget = readLinkTarget(abs);
+          if (linkTarget !== null) {
+            replacedLinks.push({ abs, target: linkTarget });
+            fs.unlinkSync(abs);
+          } else if (fs.existsSync(abs)) {
             backup(abs, op.rel);
             fs.rmSync(abs);
           }
+        } else if (op.kind === 'link') {
+          const existing = readLinkTarget(abs);
+          if (existing !== null) {
+            replacedLinks.push({ abs, target: existing });
+            fs.unlinkSync(abs);
+          } else if (fs.existsSync(abs)) {
+            throw environmentError(
+              `refusing to replace ${abs} with a link: it is a real file or directory, not a link ` +
+                'this installer created',
+            );
+          } else {
+            created.push(abs);
+          }
+          ensureDir(path.dirname(abs), createdDirs);
+          createLink(abs, op.target);
         }
       }
     } catch (error) {
-      // Roll back: remove created files, restore backups, drop created dirs.
+      // Roll back: remove created files and links, restore backups and replaced links,
+      // drop created dirs.
       for (const abs of created) {
-        if (fs.existsSync(abs)) fs.rmSync(abs, { force: true });
+        if (readLinkTarget(abs) !== null) fs.unlinkSync(abs);
+        else if (fs.existsSync(abs)) fs.rmSync(abs, { force: true });
+      }
+      for (const { abs, target } of replacedLinks) {
+        if (!fs.existsSync(abs) && readLinkTarget(abs) === null) {
+          try {
+            createLink(abs, target);
+          } catch {
+            /* best effort: the original error is what matters */
+          }
+        }
       }
       for (const { abs, backup: from } of backups) {
         fs.copyFileSync(from, abs);
@@ -215,8 +353,10 @@ export class Transaction {
     }
 
     return {
-      written: this.ops.filter((o) => o.kind === 'write').length,
+      written: this.ops.filter((o) => o.kind === 'write').length - unchanged,
+      unchanged,
       deleted: this.ops.filter((o) => o.kind === 'delete').length,
+      linked: this.ops.filter((o) => o.kind === 'link').length,
       backedUp,
       backupDir: backedUp > 0 ? this.backupDir : null,
       dryRun: false,

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

@@ -0,0 +1,59 @@
+// What a lockfile entry should hash to on disk, whatever kind of entry it is.
+//
+// Four commands independently asked "does this file still match its recorded hash?" —
+// validate, verify, uninstall, and the conflict detector — and each did it by calling
+// `hashFile` directly. That was correct while every entry was a file. The moment a
+// global install started recording links, all four tried to read a directory and threw
+// EISDIR, which is a crash rather than a diagnosis.
+//
+// So the question moves here and is asked once. A link's identity is *where it points*,
+// not what is behind it: hashing the target means `verify` catches a link repointed at
+// something else, and does not report drift merely because the canonical skill it points
+// at was legitimately updated.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { hashFile, hashString } from './hash.mjs';
+import { readLinkTarget } from './fs-safe.mjs';
+import { toPosix } from './paths.mjs';
+
+/**
+ * The digest of an installed entry, or `null` when it is not there.
+ *
+ * `null` means missing, which every caller already treats as drift — so a link whose
+ * path now holds a real directory reads as drift rather than as a match, which is what
+ * it is.
+ */
+export function entryDigest(root, entry) {
+  const absolute = path.join(root, entry.path);
+
+  if (entry.owner === 'link') {
+    const target = readLinkTarget(absolute);
+    if (target === null) return null;
+    // Relative to the scope root, so a lockfile stays valid when the whole tree moves —
+    // a home directory that changes name should not invalidate every link in it.
+    return hashString(toPosix(path.relative(root, path.resolve(path.dirname(absolute), target))));
+  }
+
+  if (!fs.existsSync(absolute)) return null;
+  try {
+    return hashFile(absolute);
+  } catch {
+    // A path that exists but cannot be read as a file — a directory where a file was
+    // recorded — is drift, not a crash.
+    return null;
+  }
+}
+
+/** True when the entry on disk matches what the lockfile recorded. */
+export function entryMatches(root, entry) {
+  const digest = entryDigest(root, entry);
+  return digest !== null && digest === entry.sha256;
+}
+
+/** True when anything at all occupies the entry's path, link or file. */
+export function entryPresent(root, entry) {
+  const absolute = path.join(root, entry.path);
+  return fs.existsSync(absolute) || readLinkTarget(absolute) !== null;
+}

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

@@ -20,8 +20,19 @@ export function lockPath(projectRoot) {
   return path.join(projectRoot, LOCKFILE);
 }
 
-export function readLock(projectRoot) {
-  const file = lockPath(projectRoot);
+/**
+ * The lockfile for a scope.
+ *
+ * A global install keeps its lockfile inside `~/.qa-engineer/`, never loose in the home
+ * directory — the whole point of owning a directory is that everything the tool wrote is
+ * in one place a user can inspect and delete.
+ */
+export function scopeLockPath(scope) {
+  return path.join(scope.root, scope.lockfile);
+}
+
+export function readLock(projectRoot, relative = LOCKFILE) {
+  const file = path.join(projectRoot, relative);
   if (!fs.existsSync(file)) return null;
   let raw;
   try {
@@ -40,12 +51,17 @@ export function readLock(projectRoot) {
  * Assemble a lockfile object. `now` is injected so tests are deterministic;
  * the CLI passes the real time.
  */
-export function buildLock({ agents, files, now }) {
+export function buildLock({ agents, files, now, scope = null }) {
   const lock = {
     lockfileVersion: LOCKFILE_VERSION,
     pack: { name: PACK_NAME, version: VERSION, specRevision: SPEC_REVISION },
     installer: VERSION,
     generatedAt: now,
+    // Recorded so every later command knows what it is operating on without being told
+    // again. Omitted for a project install, which is what a lockfile without one means.
+    ...(scope && scope.kind !== 'project'
+      ? { scope: { kind: scope.kind, qaRoot: scope.qaRootRelative, sharedEngine: scope.shareEngine } }
+      : {}),
     agents: agents.map((a) => ({
       id: a.id,
       name: a.name,

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

@@ -0,0 +1,213 @@
+// Turning a scope into a list of files and links to create.
+//
+// The planner was inline in `install.mjs` and knew exactly one arrangement: copy every
+// skill, with the engine bundled inside it, into every agent directory. That produced
+// eighteen copies of the engine for a single install — nine bundling skills times the
+// two discovery directories the installer writes — and there was nowhere to put a
+// different arrangement without an `if` in the middle of the transaction.
+//
+// So planning is separated from executing. A scope describes *what sharing is possible*;
+// this module turns that into a concrete plan; `install.mjs` commits it. The three modes
+// then differ in data rather than in control flow, which is what makes a fourth mode a
+// table entry instead of a branch.
+//
+// ## The two plans
+//
+//   bundled  (project)   every skill carries its own engine — unchanged, and still the
+//                        right answer for a repository that must work on a machine where
+//                        nothing else is installed
+//   shared   (global,    one engine and one canonical skill tree in the scope's qaRoot;
+//             workspace) agents reach them by link, or by copy where a link cannot be made
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { SHARED_ENGINE_DIR, SHARED_SKILLS_STORE } from '../constants.mjs';
+import { toPosix, listFilesRelative } from './paths.mjs';
+import { listSkills, skillFiles, ENGINE_SOURCE } from './manifest.mjs';
+import { bundleFilesForSkill } from './bundle.mjs';
+import { hashBytes, hashString } from './hash.mjs';
+import { readSkillMeta } from './skill-meta.mjs';
+import { renderWrapper } from './wrappers.mjs';
+
+/** A skill file that is never installed: tests are development-only. */
+function isDevelopmentFile(rel) {
+  return rel.startsWith('tests/') || rel.includes('/tests/');
+}
+
+/**
+ * Files for the shared engine, at `<qaRoot>/engine/`.
+ *
+ * One copy. The launcher finds it by walking up for `.qa-engineer/engine`, so no skill
+ * needs to be told where it went.
+ */
+function planSharedEngine(sourceRoot, qaRootRelative) {
+  const engineRoot = path.join(sourceRoot, ENGINE_SOURCE);
+  const entries = [];
+  for (const rel of listFilesRelative(engineRoot)) {
+    if (rel.startsWith('test/') || rel === 'package.json') continue;
+    const content = fs.readFileSync(path.join(engineRoot, rel));
+    entries.push({
+      path: toPosix(path.join(qaRootRelative, SHARED_ENGINE_DIR, rel)),
+      sha256: hashBytes(content),
+      bytes: content.length,
+      owner: 'engine',
+      content,
+    });
+  }
+  return entries;
+}
+
+/** The canonical skill tree at `<qaRoot>/skills/`, with no engine inside it. */
+function planSkillStore(sourceRoot, skills, qaRootRelative) {
+  const entries = [];
+  for (const skill of skills) {
+    for (const rel of skillFiles(sourceRoot, skill)) {
+      if (isDevelopmentFile(rel)) continue;
+      const content = fs.readFileSync(path.join(sourceRoot, 'skills', skill, rel));
+      entries.push({
+        path: toPosix(path.join(qaRootRelative, SHARED_SKILLS_STORE, skill, rel)),
+        sha256: hashBytes(content),
+        bytes: content.length,
+        owner: 'skill',
+        skill,
+        content,
+      });
+    }
+  }
+  return entries;
+}
+
+/** Skill files copied into one agent directory, optionally with the engine bundled. */
+function planSkillCopies(sourceRoot, skills, skillsDir, agentId, { bundleEngine }) {
+  const entries = [];
+  for (const skill of skills) {
+    for (const rel of skillFiles(sourceRoot, skill)) {
+      if (isDevelopmentFile(rel)) continue;
+      const content = fs.readFileSync(path.join(sourceRoot, 'skills', skill, rel));
+      entries.push({
+        path: toPosix(path.join(skillsDir, skill, rel)),
+        sha256: hashBytes(content),
+        bytes: content.length,
+        owner: 'skill',
+        skill,
+        agent: agentId,
+        content,
+      });
+    }
+    if (!bundleEngine) continue;
+    for (const bundled of bundleFilesForSkill(sourceRoot, skill)) {
+      entries.push({
+        path: toPosix(path.join(skillsDir, skill, bundled.rel)),
+        sha256: hashBytes(bundled.content),
+        bytes: bundled.content.length,
+        owner: 'skill',
+        skill,
+        agent: agentId,
+        content: bundled.content,
+      });
+    }
+  }
+  return entries;
+}
+
+/** Slash-command wrappers, for the agents that need one to expose a skill. */
+function planWrappers(sourceRoot, skills, agent) {
+  if (!agent.wrapperFormat || !agent.wrapperDir) return [];
+  const entries = [];
+  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 buffer = Buffer.from(content, 'utf8');
+    entries.push({
+      path: toPosix(path.join(agent.wrapperDir, filename)),
+      sha256: hashBytes(buffer),
+      bytes: buffer.length,
+      owner: 'wrapper',
+      skill,
+      agent: agent.id,
+      content: buffer,
+    });
+  }
+  return entries;
+}
+
+/**
+ * One link per skill, from an agent's directory to the canonical tree.
+ *
+ * The lockfile needs a hash for every entry, and a link has no content to hash — so the
+ * hash is of the target path. That is not a formality: it makes `verify` able to catch a
+ * link that still exists but now points somewhere else, which is exactly what happens
+ * when a second tool claims the same directory.
+ */
+function planLinks(skills, skillsDir, agentId, qaRoot, root) {
+  return skills.map((skill) => {
+    const target = path.join(qaRoot, SHARED_SKILLS_STORE, skill);
+    const rel = toPosix(path.join(skillsDir, skill));
+    return {
+      path: rel,
+      sha256: hashString(toPosix(path.relative(root, target))),
+      bytes: 0,
+      owner: 'link',
+      skill,
+      agent: agentId,
+      linkTarget: target,
+    };
+  });
+}
+
+/**
+ * Build the full plan for a scope.
+ *
+ * `targets` are agent definitions already resolved for this scope, each carrying the
+ * scope-relative `skillsDir` it wants and whether it can be served by a link.
+ */
+export function buildPlan({ sourceRoot, scope, targets, preferLinks = true }) {
+  const skills = listSkills(sourceRoot);
+  const files = [];
+  const links = [];
+
+  if (scope.shareEngine) {
+    files.push(...planSharedEngine(sourceRoot, scope.qaRootRelative));
+    files.push(...planSkillStore(sourceRoot, skills, scope.qaRootRelative));
+  }
+
+  for (const agent of targets) {
+    if (scope.shareEngine && preferLinks && agent.linkable !== false) {
+      links.push(...planLinks(skills, agent.skillsDir, agent.id, scope.qaRoot, scope.root));
+    } else {
+      files.push(
+        ...planSkillCopies(sourceRoot, skills, agent.skillsDir, agent.id, {
+          // A copied skill needs its own engine only when nothing is shared; with a
+          // shared engine present the launcher finds it by walking up.
+          bundleEngine: !scope.shareEngine,
+        }),
+      );
+    }
+    files.push(...planWrappers(sourceRoot, skills, agent));
+  }
+
+  return { skills, files, links };
+}
+
+/**
+ * Collapse duplicate destinations, refusing any that disagree about content.
+ *
+ * Two agents can name the same directory — Cursor and Codex both read `.agents/skills` —
+ * and writing it twice is wasted work. Two *different* contents for one path is a
+ * planning bug, and failing loudly beats letting whichever ran last win.
+ */
+export function dedupePlan(entries) {
+  const byPath = new Map();
+  const conflicts = [];
+  for (const entry of entries) {
+    const previous = byPath.get(entry.path);
+    if (!previous) {
+      byPath.set(entry.path, entry);
+      continue;
+    }
+    if (previous.sha256 !== entry.sha256) conflicts.push(entry.path);
+  }
+  return { unique: [...byPath.values()], conflicts };
+}

package/packages/installer/lib/core/qa-home.mjs

@@ -0,0 +1,145 @@
+// The directory QA Engineer owns on a machine, and the rules for what lives in it.
+//
+// ## Why a single owned directory
+//
+// Before this existed, installing "globally" meant pointing `--project` at `$HOME`,
+// which scattered `qa-lock.json`, `.agents/`, and `.claude/` across the user's home
+// directory and depended on behaviour nothing documented or tested. A tool that writes
+// into `$HOME` directly is a tool that cannot be cleanly uninstalled, because nobody
+// can tell which of those files it put there.
+//
+// So: one directory, everything inside it, and `uninstall` can remove it wholesale.
+// The same shape Docker, the AWS CLI, and Cargo use, for the same reason.
+//
+//   ~/.qa-engineer/
+//     engine/          one copy of the deterministic engine, shared by every skill
+//     skills/          one canonical copy of the skills
+//     config/          machine-level configuration
+//     sessions/        stored authentication, per application
+//     cache/           regenerable — safe to delete at any time
+//     logs/            diagnostics
+//     qa-lock.json     what is installed, with a hash per file
+//
+// ## Why not XDG
+//
+// On Linux the tidier answer is `$XDG_DATA_HOME/qa-engineer` plus `$XDG_STATE_HOME`
+// and `$XDG_CACHE_HOME` — three directories, three variables, three fallbacks, and a
+// different layout on macOS and Windows. The cost is that a user who wants to see what
+// the tool owns has to look in three places on one OS and one place on another, and
+// that `uninstall` has three roots to get right.
+//
+// One dot-directory in `$HOME` is what Docker, AWS, Cargo, and Git do, works
+// identically on all three platforms, and is overridable in full by
+// `QA_ENGINEER_HOME` for anyone who wants it elsewhere. Cache lives inside it and is
+// documented as safe to delete, which is the only thing XDG would really have bought.
+//
+// ## Directories are created on demand
+//
+// Only `engine/`, `skills/`, and the lockfile are written at install time. `sessions/`,
+// `cache/`, and `logs/` are created by whoever first writes to them. An empty directory
+// promising a feature that does not exist yet is a lie the filesystem tells forever.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { QA_HOME_DIR_NAME, QA_HOME_ENV, LOCKFILE } from '../constants.mjs';
+import { environmentError } from './errors.mjs';
+
+/**
+ * Subdirectories of the home, and whether an install creates them.
+ *
+ * `installed: true` means the installer writes content there and `verify` expects it.
+ * Everything else appears the first time something needs it.
+ */
+export const HOME_LAYOUT = Object.freeze({
+  engine: { dir: 'engine', installed: true, purpose: 'the deterministic engine, shared by every skill' },
+  skills: { dir: 'skills', installed: true, purpose: 'the canonical copy of the skills' },
+  adapters: { dir: 'adapters', installed: false, purpose: 'per-agent integration state' },
+  config: { dir: 'config', installed: false, purpose: 'machine-level configuration' },
+  sessions: { dir: 'sessions', installed: false, purpose: 'stored authentication, one file per application' },
+  cache: { dir: 'cache', installed: false, purpose: 'regenerable — safe to delete at any time' },
+  logs: { dir: 'logs', installed: false, purpose: 'diagnostics' },
+});
+
+/**
+ * The absolute path of the QA Engineer home.
+ *
+ * `QA_ENGINEER_HOME` wins when set, which is what makes the whole thing testable: the
+ * test suite points it at a temporary directory rather than touching a real `$HOME`.
+ * It is also the escape hatch for anyone whose home is on a network share or who wants
+ * the install on another volume.
+ */
+export function qaHome({ env = process.env, homedir = os.homedir } = {}) {
+  const override = env[QA_HOME_ENV];
+  if (override && override.trim()) {
+    const resolved = path.resolve(override.trim());
+    if (resolved === path.parse(resolved).root) {
+      // A home at `/` would make `uninstall` a catastrophe.
+      throw environmentError(`${QA_HOME_ENV} must not be a filesystem root: ${resolved}`);
+    }
+    return resolved;
+  }
+
+  // The test suite redirects the user's home wholesale; the owned directory follows it,
+  // so a global install can be proven end to end without touching a real home.
+  const home = env.QA_ENGINEER_USER_HOME?.trim() || homedir();
+  if (!home || home === path.parse(home || '/').root) {
+    throw environmentError(
+      `could not determine a home directory for the global install; set ${QA_HOME_ENV} to choose one`,
+    );
+  }
+  return path.join(home, QA_HOME_DIR_NAME);
+}
+
+/** Absolute path of one layout directory. */
+export function homePath(kind, options) {
+  const entry = HOME_LAYOUT[kind];
+  if (!entry) throw new Error(`unknown qa-home directory: ${kind}`);
+  return path.join(qaHome(options), entry.dir);
+}
+
+/** Absolute path of the global lockfile. Inside the home, never loose in `$HOME`. */
+export function homeLockPath(options) {
+  return path.join(qaHome(options), LOCKFILE);
+}
+
+/** Create a layout directory on demand and return it. */
+export function ensureHomeDir(kind, options) {
+  const target = homePath(kind, options);
+  fs.mkdirSync(target, { recursive: true });
+  return target;
+}
+
+/** True when a global install is present — the engine is the load-bearing part. */
+export function isGlobalInstalled(options) {
+  return fs.existsSync(path.join(homePath('engine', options), 'bin', 'qa-engine.mjs'));
+}
+
+/**
+ * A description of the home for `doctor`: what exists, what does not, and what each
+ * directory is for. Reporting an absent optional directory as "not yet created" rather
+ * than as missing is the difference between a diagnostic and a false alarm.
+ */
+export function describeHome(options) {
+  const root = qaHome(options);
+  const present = fs.existsSync(root);
+  return {
+    root,
+    present,
+    lockfile: homeLockPath(options),
+    engineInstalled: isGlobalInstalled(options),
+    directories: Object.entries(HOME_LAYOUT).map(([kind, entry]) => {
+      const absolute = path.join(root, entry.dir);
+      const exists = fs.existsSync(absolute);
+      return {
+        kind,
+        path: absolute,
+        purpose: entry.purpose,
+        exists,
+        expected: entry.installed,
+        state: exists ? 'present' : entry.installed ? 'missing' : 'not yet created',
+      };
+    }),
+  };
+}