qa-engineer 0.9.2 → 0.11.0

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',
+      };
+    }),
+  };
+}

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 });
+}