qa-engineer 0.10.0 → 0.12.0

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

@@ -0,0 +1,274 @@
+// Installation scopes: where an install lives, and what it shares.
+//
+// Before this, there was one shape — "a project" — and every other arrangement was a
+// user pointing `--project` somewhere unusual and hoping. Three arrangements are real,
+// and each is now a named, tested mode rather than a trick:
+//
+//   global     one install per machine, in ~/.qa-engineer, reused by every project
+//   workspace  one install per monorepo, at the repository root, reused by every package
+//   project    one install in this project — the original behaviour, unchanged
+//
+// ## The one idea that makes sharing work
+//
+// A scope has a `qaRoot`: a directory holding exactly one copy of the engine and one
+// canonical copy of the skills. Global puts it in the user's home; workspace puts it at
+// the monorepo root; project has none, and keeps the engine bundled inside each skill
+// the way it always has.
+//
+// The launcher (`shared/tooling/qa-tool.mjs`) walks up from wherever a skill happens to
+// live looking for `.qa-engineer/engine`, then falls back to the machine home, then to
+// node_modules, then to npx. So a skill does not need to know which scope installed it
+// — which is precisely why one skill directory can serve all three.
+//
+// ## Why project mode is left alone
+//
+// Every existing install on disk is a project install. Changing what those look like
+// would mean an upgrade that rewrites a user's repository, and `verify` reporting drift
+// on installs that were fine. The safe direction here is obvious: new modes are added,
+// the old one is not touched, and a 0.10 lockfile still verifies under 0.11.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { LOCKFILE, QA_HOME_DIR_NAME } from '../constants.mjs';
+import { qaHome } from './qa-home.mjs';
+import { usageError } from './errors.mjs';
+
+export const SCOPES = Object.freeze(['global', 'workspace', 'project']);
+
+// Files that mark the root of a monorepo. Ordered by how strongly each implies "this is
+// the top": a lockfile is decisive, a workspace manifest nearly so, `.git` last because
+// a submodule has one too.
+const WORKSPACE_MARKERS = Object.freeze([
+  { file: 'pnpm-workspace.yaml', kind: 'pnpm' },
+  { file: 'lerna.json', kind: 'lerna' },
+  { file: 'nx.json', kind: 'nx' },
+  { file: 'turbo.json', kind: 'turborepo' },
+  { file: 'rush.json', kind: 'rush' },
+  { file: 'go.work', kind: 'go' },
+  { file: 'Cargo.toml', kind: 'cargo', check: (text) => /^\s*\[workspace\]/m.test(text) },
+]);
+
+/** True when this package.json declares npm/yarn workspaces. */
+function declaresNpmWorkspaces(file) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return Array.isArray(parsed.workspaces) || typeof parsed.workspaces === 'object';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Walk up from `start` looking for the root of a monorepo.
+ *
+ * Returns the *highest* match rather than the nearest: in a repository where a package
+ * has its own `package.json` and the root declares workspaces, the root is the answer.
+ * Stopping at the first hit would install once per package, which is the duplication
+ * this mode exists to remove.
+ */
+export function findWorkspaceRoot(start = process.cwd(), { limit = 24 } = {}) {
+  let dir = path.resolve(start);
+  let best = null;
+
+  for (let depth = 0; depth < limit; depth += 1) {
+    for (const marker of WORKSPACE_MARKERS) {
+      const file = path.join(dir, marker.file);
+      if (!fs.existsSync(file)) continue;
+      if (marker.check) {
+        let text = '';
+        try {
+          text = fs.readFileSync(file, 'utf8');
+        } catch {
+          continue;
+        }
+        if (!marker.check(text)) continue;
+      }
+      best = { root: dir, kind: marker.kind, marker: marker.file };
+    }
+
+    const manifest = path.join(dir, 'package.json');
+    if (fs.existsSync(manifest) && declaresNpmWorkspaces(manifest)) {
+      best = { root: dir, kind: 'npm', marker: 'package.json' };
+    }
+
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  return best;
+}
+
+/**
+ * The user's home, where agent user-level directories live.
+ *
+ * `QA_ENGINEER_USER_HOME` exists for the test suite, which must not write into a real
+ * home to prove that a global install works. It is deliberately separate from
+ * `QA_ENGINEER_HOME`: that one moves what *we* own, this one moves where *agents* look,
+ * and a test needs to move both together while a user normally moves neither.
+ */
+export function resolveUserHome({ env = process.env } = {}) {
+  const override = env.QA_ENGINEER_USER_HOME;
+  if (override && override.trim()) return path.resolve(override.trim());
+  return os.homedir();
+}
+
+/** The deepest directory containing both paths. */
+function commonAncestor(a, b) {
+  const left = path.resolve(a).split(path.sep);
+  const right = path.resolve(b).split(path.sep);
+  const shared = [];
+  for (let i = 0; i < Math.min(left.length, right.length); i += 1) {
+    if (left[i] !== right[i]) break;
+    shared.push(left[i]);
+  }
+  return shared.join(path.sep) || path.parse(path.resolve(a)).root;
+}
+
+/** POSIX-style path from `root` to `target`, for lockfile entries. */
+function toRelative(root, target) {
+  return path.relative(root, target).split(path.sep).join('/');
+}
+
+/**
+ * Resolve the scope a command should operate on.
+ *
+ * Exactly one mode may be requested. Defaulting silently to `project` when `--global`
+ * was misspelled would install into whatever directory the user happened to be in,
+ * which is the kind of surprise that costs trust once and permanently.
+ */
+export function resolveScope({
+  global: wantGlobal = false,
+  workspace = false,
+  project = null,
+  cwd = process.cwd(),
+  env = process.env,
+} = {}) {
+  const requested = [wantGlobal && 'global', workspace && 'workspace', project && 'project'].filter(Boolean);
+  if (requested.length > 1) {
+    throw usageError(
+      `choose one installation scope, not ${requested.length}: ${requested.map((r) => `--${r}`).join(' and ')}`,
+    );
+  }
+
+  if (wantGlobal) {
+    // Two directories are in play and they are not the same one. Everything the tool
+    // owns goes in `qaRoot`; the links that make agents see it go in *their* user-level
+    // directories, which live in the user's home. Conflating the two put `.claude/` and
+    // `.gemini/` inside `~/.qa-engineer`, where no agent looks.
+    const qaRoot = qaHome({ env });
+    const userHome = resolveUserHome({ env });
+    const root = commonAncestor(qaRoot, userHome);
+
+    if (root === path.parse(root).root) {
+      throw usageError(
+        `${qaRoot} and ${userHome} share no directory but the filesystem root, so a single ` +
+          'install cannot contain both',
+        'point QA_ENGINEER_HOME somewhere inside your home directory',
+      );
+    }
+
+    const qaRootRelative = toRelative(root, qaRoot);
+    return Object.freeze({
+      kind: 'global',
+      // The transaction is confined here, and it contains both the owned directory and
+      // the agent directories being linked into.
+      root,
+      qaRoot,
+      qaRootRelative,
+      userHome,
+      lockfile: path.posix.join(qaRootRelative, LOCKFILE),
+      shareEngine: true,
+      userLevel: true,
+      label: `global (${qaRoot})`,
+      describe: () => `machine-wide install in ${qaRoot}`,
+    });
+  }
+
+  if (workspace) {
+    const found = findWorkspaceRoot(cwd);
+    if (!found) {
+      throw usageError(
+        `no monorepo root found above ${path.resolve(cwd)} — looked for ` +
+          `${WORKSPACE_MARKERS.map((m) => m.file).join(', ')}, and package.json with a "workspaces" field`,
+        'run from inside the monorepo, or use --project <dir> to name the root explicitly',
+      );
+    }
+    return Object.freeze({
+      kind: 'workspace',
+      root: found.root,
+      qaRoot: path.join(found.root, QA_HOME_DIR_NAME),
+      qaRootRelative: QA_HOME_DIR_NAME,
+      lockfile: LOCKFILE,
+      shareEngine: true,
+      userLevel: false,
+      workspaceKind: found.kind,
+      label: `workspace (${found.root}, detected by ${found.marker})`,
+      describe: () => `${found.kind} monorepo rooted at ${found.root}`,
+    });
+  }
+
+  const root = path.resolve(project ?? cwd);
+  return Object.freeze({
+    kind: 'project',
+    root,
+    // No shared root: the engine travels inside each skill, as it always has.
+    qaRoot: null,
+    qaRootRelative: null,
+    lockfile: LOCKFILE,
+    shareEngine: false,
+    userLevel: false,
+    label: `project (${root})`,
+    describe: () => `project install in ${root}`,
+  });
+}
+
+/**
+ * The scope an already-installed tree belongs to, for commands that operate on an
+ * existing install rather than creating one.
+ *
+ * A lockfile records its own scope from 0.11 onward. One written by an earlier version
+ * has no `scope` field and is a project install by definition, because that is the only
+ * kind that existed — so the absence is read as `project` rather than as corruption.
+ */
+export function scopeOfLock(lock) {
+  return lock?.scope?.kind ?? 'project';
+}
+
+/**
+ * The scope a lifecycle command should act on when the user did not name one.
+ *
+ * `qa verify` with no flags should verify the install that is actually in play, and
+ * which one that is depends on where you are standing. A project with its own lockfile
+ * is the answer there; otherwise the machine-wide install is, because that is what is
+ * serving this project. Making the user pass `--global` to check the only install they
+ * have would be a tool asking a question it can answer itself.
+ *
+ * Project beats global deliberately, matching every layered tool a developer already
+ * knows: a local `node_modules` beats a global one, `.git/config` beats `~/.gitconfig`.
+ */
+export function resolveOperatingScope({
+  global: wantGlobal = false,
+  workspace = false,
+  project = null,
+  cwd = process.cwd(),
+  env = process.env,
+} = {}) {
+  if (wantGlobal || workspace || project) {
+    return resolveScope({ global: wantGlobal, workspace, project, cwd, env });
+  }
+
+  const here = path.resolve(cwd);
+  if (fs.existsSync(path.join(here, LOCKFILE))) {
+    return resolveScope({ project: here, cwd, env });
+  }
+
+  const globalScope = resolveScope({ global: true, cwd, env });
+  if (fs.existsSync(path.join(globalScope.root, globalScope.lockfile))) return globalScope;
+
+  // Nothing installed anywhere reachable. Return the project scope so the command
+  // reports "no lockfile here", which is the honest and actionable message.
+  return resolveScope({ project: here, cwd, env });
+}

package/packages/installer/lib/core/validate-install.mjs

@@ -4,7 +4,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { LOCKFILE, SHARED_SKILLS_DIR, CLAUDE_SKILLS_DIR } from '../constants.mjs';
 import { readLock } from './lockfile.mjs';
-import { hashFile } from './hash.mjs';
+import { entryDigest } from './integrity.mjs';
 import { verifyEngine, packHasBundles } from './bundle.mjs';
 import { BUNDLE_DEST, BUNDLE_MANIFEST } from './manifest.mjs';
 
@@ -17,17 +17,18 @@ import { BUNDLE_DEST, BUNDLE_MANIFEST } from './manifest.mjs';
  * @param {string} projectRoot
  * @returns {{ ok: boolean, checks: CheckResult[] }}
  */
-export function validateInstall(projectRoot) {
+export function validateInstall(projectRoot, { scope = null } = {}) {
   /** @type {CheckResult[]} */
   const checks = [];
 
-  const lock = readLock(projectRoot);
+  const lockRelative = scope?.lockfile ?? LOCKFILE;
+  const lock = readLock(projectRoot, lockRelative);
   if (!lock) {
     checks.push({
       id: 'lockfile',
       ok: false,
       hard: true,
-      message: `${LOCKFILE} missing`,
+      message: `${lockRelative} missing`,
       hint: 'run: qa install',
     });
     return { ok: false, checks };
@@ -37,17 +38,12 @@ export function validateInstall(projectRoot) {
     id: 'lockfile',
     ok: true,
     hard: true,
-    message: `${LOCKFILE} present (${lock.files.length} files, pack ${lock.pack?.version ?? '?'})`,
+    message: `${lockRelative} present (${lock.files.length} files, pack ${lock.pack?.version ?? '?'})`,
   });
 
   let drift = 0;
   for (const entry of lock.files) {
-    const abs = path.join(projectRoot, entry.path);
-    if (!fs.existsSync(abs)) {
-      drift += 1;
-      continue;
-    }
-    if (hashFile(abs) !== entry.sha256) drift += 1;
+    if (entryDigest(projectRoot, entry) !== entry.sha256) drift += 1;
   }
   checks.push({
     id: 'integrity',
@@ -92,7 +88,36 @@ export function validateInstall(projectRoot) {
         : 'no contract schemas found (optional for minimal installs)',
   });
 
-  if (packHasBundles()) {
+  // Where the engine should be depends on how it was installed: a shared scope has
+  // exactly one copy in its qaRoot, a project install has one inside each bundling
+  // skill. Looking only for the second is what made the first report a broken install.
+  const sharedScope = scope?.shareEngine || lock.scope?.sharedEngine;
+  if (sharedScope) {
+    const qaRootRelative = scope?.qaRootRelative ?? lock.scope?.qaRoot ?? '.';
+    const libDir = path.join(projectRoot, qaRootRelative, 'engine');
+    const bundleOk = fs.existsSync(path.join(libDir, 'bin', 'qa-engine.mjs'));
+    checks.push({
+      id: 'engine',
+      ok: bundleOk,
+      hard: true,
+      message: bundleOk
+        ? `deterministic engine shared at ${path.relative(projectRoot, libDir) || '.'}`
+        : 'shared deterministic engine missing',
+      hint: bundleOk ? undefined : 'run: qa repair',
+    });
+    if (bundleOk) {
+      const result = verifyEngine({ libDir });
+      checks.push({
+        id: 'engine-runs',
+        ok: result.ok,
+        hard: true,
+        message: result.ok
+          ? `shared engine runs (node ${process.versions.node})`
+          : `shared engine failed to run: ${result.stderr || 'unknown error'}`,
+        hint: result.ok ? undefined : 'run: qa repair',
+      });
+    }
+  } else if (packHasBundles()) {
     const bundledSkill = Object.keys(BUNDLE_MANIFEST)[0];
     let libDir = null;
     for (const base of [SHARED_SKILLS_DIR, CLAUDE_SKILLS_DIR]) {

package/packages/installer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qa-engineer/installer",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "The qa-engineer installer: agent detection, copy-based install, lockfile integrity, and wrapper generation.",
   "license": "MIT",
   "type": "module",

package/packages/installer/schemas/qa-lock.schema.json

@@ -5,7 +5,14 @@
   "description": "qa-lock.json records exactly what was installed and a hash per file, so an install can be verified, updated, or removed without guessing. Written by the installer; not hand-edited.",
   "type": "object",
   "additionalProperties": false,
-  "required": ["lockfileVersion", "pack", "installer", "generatedAt", "agents", "files"],
+  "required": [
+    "lockfileVersion",
+    "pack",
+    "installer",
+    "generatedAt",
+    "agents",
+    "files"
+  ],
   "properties": {
     "lockfileVersion": {
       "type": "integer",
@@ -14,11 +21,22 @@
     "pack": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["name", "version", "specRevision"],
+      "required": [
+        "name",
+        "version",
+        "specRevision"
+      ],
       "properties": {
-        "name": { "type": "string" },
-        "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+" },
-        "specRevision": { "type": "string" }
+        "name": {
+          "type": "string"
+        },
+        "version": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+"
+        },
+        "specRevision": {
+          "type": "string"
+        }
       }
     },
     "installer": {
@@ -35,17 +53,31 @@
       "items": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["id", "name", "tier"],
+        "required": [
+          "id",
+          "name",
+          "tier"
+        ],
         "properties": {
-          "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
-          "name": { "type": "string" },
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*$"
+          },
+          "name": {
+            "type": "string"
+          },
           "tier": {
-            "type": ["integer", "null"],
+            "type": [
+              "integer",
+              "null"
+            ],
             "minimum": 1,
             "maximum": 2,
-            "description": "Support tier, or null when the host is unknown — the shared Agent Skills path was installed without identifying a product."
+            "description": "Support tier, or null when the host is unknown \u2014 the shared Agent Skills path was installed without identifying a product."
+          },
+          "skillsDir": {
+            "type": "string"
           },
-          "skillsDir": { "type": "string" },
           "detected": {
             "type": "boolean",
             "description": "True only when project markers identified this host. False when it was requested explicitly or stands in as the unknown-agent path. Optional for lockfiles written before this field existed."
@@ -59,7 +91,12 @@
       "items": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["path", "sha256", "bytes", "owner"],
+        "required": [
+          "path",
+          "sha256",
+          "bytes",
+          "owner"
+        ],
         "properties": {
           "path": {
             "type": "string",
@@ -67,11 +104,36 @@
             "description": "Project-relative POSIX path. Must not be absolute and must not contain a '..' segment: a lockfile travels with a cloned repository, and uninstall deletes what it lists.",
             "pattern": "^(?!/)(?!.*(^|/)\\.\\.($|/)).+$"
           },
-          "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
-          "bytes": { "type": "integer", "minimum": 0 },
-          "owner": { "type": "string", "enum": ["skill", "wrapper", "config"] },
-          "skill": { "type": "string" },
-          "agent": { "type": "string" }
+          "sha256": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{64}$"
+          },
+          "bytes": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "owner": {
+            "type": "string",
+            "enum": [
+              "skill",
+              "wrapper",
+              "config",
+              "engine",
+              "link"
+            ],
+            "description": "What created the entry. `engine` is the shared deterministic engine, present once per scope. `link` is a symbolic link into the canonical skill tree, whose sha256 is the hash of its scope-relative target rather than of file content \u2014 a link has no content, and hashing the target is what lets verify catch one that has been repointed."
+          },
+          "skill": {
+            "type": "string"
+          },
+          "agent": {
+            "type": "string"
+          },
+          "linkTarget": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Absolute path a `link` entry points at. Absolute because the link is created with it verbatim; the hashed form in sha256 is scope-relative so the lockfile stays machine-independent."
+          }
         }
       }
     },
@@ -79,10 +141,46 @@
       "type": "object",
       "additionalProperties": false,
       "properties": {
-        "skills": { "type": "integer", "minimum": 0 },
-        "files": { "type": "integer", "minimum": 0 },
-        "wrappers": { "type": "integer", "minimum": 0 },
-        "directories": { "type": "integer", "minimum": 0 }
+        "skills": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "files": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "wrappers": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "directories": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    },
+    "scope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kind"
+      ],
+      "description": "Which installation mode wrote this lockfile. Absent means `project`: before 0.11 that was the only mode, so its absence is a fact rather than a gap.",
+      "properties": {
+        "kind": {
+          "enum": [
+            "global",
+            "workspace",
+            "project"
+          ]
+        },
+        "qaRoot": {
+          "type": "string",
+          "description": "Scope-relative directory holding the shared engine and canonical skills. Absent for a project install, which shares nothing."
+        },
+        "sharedEngine": {
+          "type": "boolean"
+        }
       }
     }
   }

package/shared/tooling/qa-tool.mjs

@@ -28,6 +28,7 @@
 // `node qa-tool.mjs …`, which needs none.
 
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
@@ -37,7 +38,7 @@ const here = path.dirname(fileURLToPath(import.meta.url));
 const USAGE = `usage: node qa-tool.mjs <tool> <subcommand> [args]
 
   analysis     parse artifacts, classify errors, validate contracts, diff-guard,
-               read .qa/context.md, render an HTML report, print the footer
+              read .qa/context.md, render an HTML report, print the footer
   diagnostics  root cause, timeline, priority, repair plans, release readiness
   playwright   normalize a Playwright report or summarize a trace
 
@@ -52,15 +53,26 @@ examples:
 /**
  * Where the engine is, and how we found it.
  *
- * Ordered by cost: a bundled copy needs no resolution and no network, a
- * node_modules copy needs no network, and npx needs both on first use. Reporting
- * *which* one answered matters when a skill degrades — "the engine is missing" and
- * "the engine is being fetched" are different problems.
+ * Ordered by cost: a bundled copy needs no resolution and no network, a shared copy
+ * needs one stat per ancestor, a node_modules copy needs no network, and npx needs both
+ * on first use. Reporting *which* one answered matters when a skill degrades — "the
+ * engine is missing" and "the engine is being fetched" are different problems.
+ *
+ * The shared lookup is what lets one skill directory serve a project, a workspace, and a
+ * machine-wide install without knowing which installed it. Walking up for
+ * `.qa-engineer/engine` finds a workspace install from a skill inside the repository,
+ * and finds a global install from a skill linked into an agent's user-level directory —
+ * `~/.claude/skills/qa-explore` walks up to `~`, where `~/.qa-engineer/engine` is.
  */
 function resolveEngine() {
   const bundled = path.join(here, 'lib', 'bin', 'qa-engine.mjs');
   if (fs.existsSync(bundled)) return { kind: 'bundled', command: [process.execPath, bundled] };
 
+  for (const root of candidateSharedRoots()) {
+    const shared = path.join(root, 'bin', 'qa-engine.mjs');
+    if (fs.existsSync(shared)) return { kind: 'shared', command: [process.execPath, shared] };
+  }
+
   for (const base of candidateModuleRoots()) {
     const installed = path.join(base, 'qa-engineer', 'packages', 'engine', 'bin', 'qa-engine.mjs');
     if (fs.existsSync(installed)) {
@@ -74,6 +86,30 @@ function resolveEngine() {
   };
 }
 
+/** Shared engine directories worth checking, most specific first. */
+function candidateSharedRoots() {
+  const roots = [];
+
+  // An explicit home wins over anything discovered, so a user who moved the install can
+  // rely on it rather than on whatever the walk happens to find first.
+  const override = process.env.QA_ENGINEER_HOME;
+  if (override && override.trim()) roots.push(path.join(path.resolve(override.trim()), 'engine'));
+
+  let dir = here;
+  for (let depth = 0; depth < 12; depth += 1) {
+    roots.push(path.join(dir, '.qa-engineer', 'engine'));
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  // The default machine home, for the case where the skill lives outside it entirely.
+  const home = os.homedir();
+  if (home) roots.push(path.join(home, '.qa-engineer', 'engine'));
+
+  return roots;
+}
+
 /** node_modules directories worth checking, nearest first. */
 function candidateModuleRoots() {
   const roots = [];