@indigoai-us/hq-cli 5.50.1 → 5.51.0

package/src/sentry.ts

@@ -1,9 +1,29 @@
 import * as Sentry from "@sentry/node";
+import type { ErrorEvent, EventHint } from "@sentry/node";
 import { BUNDLED_DSN } from "./sentry-dsn.generated.js";
 import { beforeSend } from "./sentry-before-send.js";
 import { beforeBreadcrumb } from "./utils/breadcrumb-buffer.js";
 import { CLI_VERSION } from "./cli-version.js";
 import { getCachedSentryUser } from "./utils/sentry-identity.js";
+import { isEpipe } from "./utils/epipe.js";
+
+/**
+ * Drop broken-pipe (EPIPE) crashes before scrubbing/send. A closed downstream
+ * reader (`hq … | head`, `source <(hq …)`, a parent that exited) is normal
+ * Unix behavior with no user-facing degradation — never a defect to report.
+ * This is the path-independent catch-all for HQ-6B: whichever way an EPIPE
+ * surfaces (a synchronous throw into the command catch, an async stream
+ * 'error', or a write outside the top-level try), it never ships a fatal. The
+ * clean-exit handlers in index.ts still keep exit code 0 for the common paths.
+ * Consistent with the swallow-EPIPE posture established in #138.
+ */
+export function epipeAwareBeforeSend(
+  event: ErrorEvent,
+  hint: EventHint,
+): ErrorEvent | null {
+  if (isEpipe(hint?.originalException)) return null;
+  return beforeSend(event, hint);
+}
 
 export function initSentry(): void {
   const dsn = BUNDLED_DSN || process.env.SENTRY_DSN;
@@ -18,7 +38,7 @@ export function initSentry(): void {
     initialScope: {
       tags: { repo: "hq-cli" },
     },
-    beforeSend,
+    beforeSend: epipeAwareBeforeSend,
     beforeBreadcrumb,
   });
   // Attribute events to the logged-in HQ identity (best-effort; null when not

package/src/types.ts

@@ -95,12 +95,30 @@ export interface PackAuthor {
   displayName: string;
 }
 
+/**
+ * A pack-to-pack dependency (M0). OPTIONAL and backwards-compatible — packs
+ * published before this field omit `requires.packs` and install unchanged. When
+ * present, each entry names another content pack that MUST already be installed
+ * before this one (enforced at install time by `assertPackDependencies`, which
+ * tracks installed packs by FILESYSTEM PRESENCE — not `modules.yaml`). `version`
+ * is an optional semver RANGE the installed dependency must satisfy.
+ */
+export interface PackDependency {
+  name: string;     // ^hq-pack-[a-z0-9][a-z0-9-]*$
+  version?: string; // optional semver range
+}
+
 export interface PackManifest {
   name: string;                 // ^hq-pack-[a-z0-9][a-z0-9-]*$
   version: string;              // semver
   publisher: string;            // @scope
   access: 'public' | 'private';
-  requires: { hqCore: string }; // semver range
+  /**
+   * Host + pack prerequisites. `hqCore` is a required semver RANGE the host HQ
+   * must satisfy. `packs` (M0) is an OPTIONAL list of other content packs that
+   * must be installed first — see PackDependency.
+   */
+  requires: { hqCore: string; packs?: PackDependency[] };
   contributes: Partial<Record<PackContributeKey, string[]>>;
   description?: string;
   license?: string;

package/src/utils/epipe.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { isEpipe } from "./epipe.js";
+
+describe("isEpipe", () => {
+  it("matches a real Node EPIPE error", () => {
+    const err = Object.assign(new Error("write EPIPE"), { code: "EPIPE" });
+    expect(isEpipe(err)).toBe(true);
+  });
+
+  it("matches a plain object carrying code EPIPE", () => {
+    expect(isEpipe({ code: "EPIPE" })).toBe(true);
+  });
+
+  it("does NOT match other errno codes (so real faults still report)", () => {
+    expect(isEpipe(Object.assign(new Error("disk full"), { code: "ENOSPC" }))).toBe(
+      false,
+    );
+    expect(isEpipe(Object.assign(new Error("nope"), { code: "EACCES" }))).toBe(false);
+    expect(isEpipe(new Error("plain error with no code"))).toBe(false);
+  });
+
+  it("does NOT match non-error values", () => {
+    expect(isEpipe(null)).toBe(false);
+    expect(isEpipe(undefined)).toBe(false);
+    expect(isEpipe("EPIPE")).toBe(false);
+    expect(isEpipe(42)).toBe(false);
+  });
+});

package/src/utils/epipe.ts

@@ -0,0 +1,29 @@
+// src/utils/epipe.ts
+//
+// Classify the "broken pipe" (EPIPE) error: a downstream reader closed the
+// pipe before the CLI finished writing to stdout/stderr. This is normal,
+// expected Unix behavior — `hq … | head`, `source <(hq …)`, or a parent
+// process that exits while `hq` is still printing — NOT an HQ code defect.
+//
+// HQ-6B: a synchronous `write EPIPE` thrown from `console.log` (the Sentry
+// console-instrumentation wraps it) propagated out of an awaited command into
+// the CLI's top-level `catch`, which captured it via `Sentry.captureException`
+// and shipped a fatal — even though the only thing that happened is the
+// consumer of `hq`'s output went away. The async path (an emitted stream
+// 'error' event) was already handled by the stdout/stderr listeners in
+// index.ts; this predicate closes the synchronous-throw path too, mirroring
+// the environmental-error carve-out (HQ-CLI-2).
+
+/**
+ * True when `err` is a Node EPIPE error — the pipe `hq` was writing to was
+ * closed by its reader. Callers should treat this as a clean, expected exit
+ * (code 0) and SKIP Sentry capture: there is no defect and no user-facing
+ * degradation to fix.
+ */
+export function isEpipe(err: unknown): boolean {
+  return (
+    typeof err === "object" &&
+    err !== null &&
+    (err as NodeJS.ErrnoException).code === "EPIPE"
+  );
+}

package/src/utils/intercepted-process-exit.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+import { isInterceptedProcessExit } from "./intercepted-process-exit.js";
+
+describe("isInterceptedProcessExit", () => {
+  it("matches the fuzz harness's intercepted-process.exit marker error", () => {
+    expect(isInterceptedProcessExit(new Error("fuzz-intercepted-process-exit"))).toBe(true);
+  });
+
+  it("matches when the marker is wrapped in a longer message", () => {
+    expect(
+      isInterceptedProcessExit(new Error("audit: fuzz-intercepted-process-exit code=1")),
+    ).toBe(true);
+  });
+
+  it("matches a plain object carrying the marker message", () => {
+    expect(isInterceptedProcessExit({ message: "fuzz-intercepted-process-exit" })).toBe(true);
+  });
+
+  it("matches a bare string carrying the marker", () => {
+    expect(isInterceptedProcessExit("fuzz-intercepted-process-exit")).toBe(true);
+  });
+
+  it("does NOT match genuine errors (so real faults still report)", () => {
+    expect(isInterceptedProcessExit(new Error("boom"))).toBe(false);
+    expect(isInterceptedProcessExit(new Error("ENOENT: no such file or directory"))).toBe(false);
+    expect(isInterceptedProcessExit(Object.assign(new Error("nope"), { code: "EACCES" }))).toBe(
+      false,
+    );
+  });
+
+  it("does NOT match non-error values", () => {
+    expect(isInterceptedProcessExit(null)).toBe(false);
+    expect(isInterceptedProcessExit(undefined)).toBe(false);
+    expect(isInterceptedProcessExit(42)).toBe(false);
+    expect(isInterceptedProcessExit({})).toBe(false);
+  });
+});

package/src/utils/intercepted-process-exit.ts

@@ -0,0 +1,36 @@
+// src/utils/intercepted-process-exit.ts
+//
+// Classify the "intercepted process.exit" synthetic error (HQ-CLI-3).
+//
+// Security/audit FUZZ harnesses (e.g. `/opt/audit/fuzz-exports.js`) monkey-patch
+// `process.exit` to THROW a marker instead of actually terminating, so the
+// fuzzer can keep exercising a binary's entrypoints. When such a harness drives
+// `hq` (e.g. `hq <unknown-command>`), commander legitimately calls
+// `process.exit(1)` — and the patched exit turns that normal CLI control-flow
+// into a thrown `Error: fuzz-intercepted-process-exit` that propagates out of
+// `program.parseAsync()` into the CLI's top-level catch, which then shipped it to
+// Sentry as a fatal.
+//
+// This is a test-harness artifact, NOT an hq-cli defect: a real user's
+// `process.exit` exits the process and nothing is ever thrown or captured.
+// There is no user-facing degradation to fix, so the top-level catch skips
+// Sentry capture for it — the genuine "expected, non-actionable" carve-out,
+// mirroring the EPIPE (HQ-6B) and environmental-FS (HQ-CLI-2) carve-outs.
+
+/** The marker a fuzz/audit harness throws in place of a real `process.exit`. */
+const INTERCEPTED_PROCESS_EXIT_MARKER = "fuzz-intercepted-process-exit";
+
+/**
+ * True when `err` is a fuzz/audit harness's intercepted-`process.exit` marker
+ * rather than a genuine fault. Callers should SKIP Sentry capture (no defect, no
+ * user-facing degradation) while preserving the intended exit code.
+ */
+export function isInterceptedProcessExit(err: unknown): boolean {
+  if (typeof err === "object" && err !== null) {
+    const message = (err as { message?: unknown }).message;
+    if (typeof message === "string" && message.includes(INTERCEPTED_PROCESS_EXIT_MARKER)) {
+      return true;
+    }
+  }
+  return typeof err === "string" && err.includes(INTERCEPTED_PROCESS_EXIT_MARKER);
+}

package/src/utils/pack-contributions.test.ts

@@ -16,11 +16,13 @@ import {
   contributionLinks,
   linkStatus,
   listInstalledPacks,
+  findDependentPacks,
   unwirePack,
   unwirePackMcp,
   packagesDir,
   readHqVersion,
   type WiredLink,
+  type InstalledPack,
 } from './pack-contributions.js';
 import { parse as parseToml } from 'smol-toml';
 import {
@@ -489,3 +491,54 @@ describe('US-009: unwirePackMcp (mcp un-registration parallel to symlink unwire)
     expect(fs.readFileSync(codexConfigPath(env), 'utf-8')).toBe(original);
   });
 });
+
+// ---------------------------------------------------------------------------
+// findDependentPacks — uninstall dependents guard (M0)
+// ---------------------------------------------------------------------------
+
+describe('findDependentPacks (M0)', () => {
+  function ip(
+    name: string,
+    requiresPacks?: Array<{ name: string; version?: string }>,
+  ): InstalledPack {
+    return {
+      name,
+      dir: `/tmp/nope/${name}`,
+      manifest: {
+        name,
+        version: '1.0.0',
+        publisher: '@indigoai-us',
+        access: 'public',
+        requires: { hqCore: '>=15.0.0', packs: requiresPacks },
+        contributes: { skills: ['x'] },
+      },
+    } as InstalledPack;
+  }
+
+  it('returns the packs that require the named pack', () => {
+    const installed = [
+      ip('hq-pack-crm'),
+      ip('hq-pack-accounting', [{ name: 'hq-pack-crm', version: '>=1.0.0' }]),
+      ip('hq-pack-unrelated'),
+    ];
+    const deps = findDependentPacks(installed, 'hq-pack-crm');
+    expect(deps.map((p) => p.name)).toEqual(['hq-pack-accounting']);
+  });
+
+  it('returns empty when no installed pack requires it', () => {
+    const installed = [ip('hq-pack-crm'), ip('hq-pack-unrelated')];
+    expect(findDependentPacks(installed, 'hq-pack-crm')).toEqual([]);
+  });
+
+  it('never counts a pack that lists itself as its own dependent', () => {
+    // Defensive: a self-referencing manifest (rejected at install) must not make
+    // a pack un-removable.
+    const installed = [ip('hq-pack-weird', [{ name: 'hq-pack-weird' }])];
+    expect(findDependentPacks(installed, 'hq-pack-weird')).toEqual([]);
+  });
+
+  it('tolerates an unreadable manifest (manifest === null)', () => {
+    const broken: InstalledPack = { name: 'hq-pack-broken', dir: '/tmp/nope', manifest: null };
+    expect(findDependentPacks([broken], 'hq-pack-crm')).toEqual([]);
+  });
+});

package/src/utils/pack-contributions.ts

@@ -264,6 +264,23 @@ export function listInstalledPacks(hqRoot: string): InstalledPack[] {
   return out;
 }
 
+/**
+ * Installed packs that declare `name` in their `requires.packs` (M0). Pure over
+ * the supplied list — the uninstall dependents guard calls this with
+ * `listInstalledPacks(hqRoot)`. Excludes the pack named `name` itself, so a
+ * self-reference never counts as its own dependent.
+ */
+export function findDependentPacks(
+  installed: InstalledPack[],
+  name: string,
+): InstalledPack[] {
+  return installed.filter(
+    (p) =>
+      p.name !== name &&
+      (p.manifest?.requires?.packs ?? []).some((d) => d.name === name),
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Un-wiring (the uninstall guarantee)
 // ---------------------------------------------------------------------------

package/src/utils/version-gate.test.ts

@@ -49,6 +49,51 @@ describe("shouldSkipGate", () => {
   });
 });
 
+describe("prefix install helpers", () => {
+  it("derives the npm prefix from unix global package layouts", async () => {
+    const { __test__ } = await loadModule();
+    expect(
+      __test__.npmPrefixFromPackageDir(
+        "/Users/x/Library/Application Support/Indigo HQ/toolchain/npm-global/lib/node_modules/@indigoai-us/hq-cli",
+      ),
+    ).toBe("/Users/x/Library/Application Support/Indigo HQ/toolchain/npm-global");
+    expect(
+      __test__.npmPrefixFromPackageDir(
+        "/usr/local/lib/node_modules/@indigoai-us/hq-cli",
+      ),
+    ).toBe("/usr/local");
+  });
+
+  it("derives the npm prefix from a windows-style package layout", async () => {
+    const { __test__ } = await loadModule();
+    expect(
+      __test__.npmPrefixFromPackageDir(
+        "C:\\Users\\x\\AppData\\Roaming\\npm\\node_modules\\@indigoai-us\\hq-cli",
+      ),
+    ).toBe("C:/Users/x/AppData/Roaming/npm");
+  });
+
+  it("returns null when the package path is not under node_modules", async () => {
+    const { __test__ } = await loadModule();
+    expect(
+      __test__.npmPrefixFromPackageDir(
+        "/Users/x/dev/hq/packages/hq-cli",
+      ),
+    ).toBeNull();
+  });
+
+  it("builds the prefixed npm install argv", async () => {
+    const { __test__ } = await loadModule();
+    expect(__test__.buildPrefixedInstallArgv("/tmp/npm-global")).toEqual([
+      "install",
+      "-g",
+      "--prefix",
+      "/tmp/npm-global",
+      "@indigoai-us/hq-cli@latest",
+    ]);
+  });
+});
+
 describe("enforceVersionGate — opt-out + soft paths (no process.exit)", () => {
   it("is silent + no fetch when HQ_NO_UPDATE_CHECK=1", async () => {
     vi.stubEnv("HQ_NO_UPDATE_CHECK", "1");
@@ -242,4 +287,81 @@ describe("enforceVersionGate — hard-update path", () => {
     expect(body.currentVersion).toBe("5.10.0");
     expect(typeof body.platform).toBe("string");
   });
+
+  it("installs with the resolved running prefix instead of the bare server command", async () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const exitSpy = vi
+      .spyOn(process, "exit")
+      .mockImplementation(((code?: number) => {
+        throw new Error(`__process_exit__:${code ?? 0}`);
+      }) as never);
+    const runner = vi.fn().mockReturnValue({ ok: true });
+    const { __test__ } = await loadModule();
+    const prefix = "/Users/x/Library/Application Support/Indigo HQ/toolchain/npm-global";
+
+    expect(() =>
+      __test__.enforceUpdateRequired(
+        {
+          clientId: "hq-cli",
+          currentVersion: "5.10.0",
+          minVersion: "5.20.0",
+          latestVersion: "5.24.0",
+          updateRequired: true,
+          updateRecommended: false,
+          updateCommand: "npm install -g @indigoai-us/hq-cli@latest",
+        },
+        {
+          resolvePrefix: () => prefix,
+          runner,
+        },
+      ),
+    ).toThrow(/__process_exit__:0/);
+
+    expect(exitSpy).toHaveBeenCalledWith(0);
+    expect(runner).toHaveBeenCalledWith("npm", [
+      "install",
+      "-g",
+      "--prefix",
+      prefix,
+      "@indigoai-us/hq-cli@latest",
+    ]);
+    expect(runner).not.toHaveBeenCalledWith("npm", [
+      "install",
+      "-g",
+      "@indigoai-us/hq-cli@latest",
+    ]);
+  });
+
+  it("falls back to the server updateCommand when no running prefix resolves", async () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const exitSpy = vi
+      .spyOn(process, "exit")
+      .mockImplementation(((code?: number) => {
+        throw new Error(`__process_exit__:${code ?? 0}`);
+      }) as never);
+    const performUpdateString = vi.fn().mockReturnValue({ ok: true });
+    const { __test__ } = await loadModule();
+    const updateCommand = "npm install -g @indigoai-us/hq-cli@latest";
+
+    expect(() =>
+      __test__.enforceUpdateRequired(
+        {
+          clientId: "hq-cli",
+          currentVersion: "5.10.0",
+          minVersion: "5.20.0",
+          latestVersion: "5.24.0",
+          updateRequired: true,
+          updateRecommended: false,
+          updateCommand,
+        },
+        {
+          performUpdateString,
+          resolvePrefix: () => null,
+        },
+      ),
+    ).toThrow(/__process_exit__:0/);
+
+    expect(exitSpy).toHaveBeenCalledWith(0);
+    expect(performUpdateString).toHaveBeenCalledWith(updateCommand);
+  });
 });

package/src/utils/version-gate.ts

@@ -29,13 +29,17 @@
  */
 
 import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 import chalk from "chalk";
-import { CLI_VERSION } from "../cli-version.js";
+import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
 import { DEFAULT_VAULT_API_URL } from "./cognito-session.js";
 
 const CLIENT_ID = "hq-cli";
 const ENDPOINT_PATH = "/v1/client-version/check";
 const FETCH_TIMEOUT_MS = 3_000;
+const LATEST_PACKAGE_SPEC = `${CLI_NAME}@latest`;
 
 interface VersionCheckResponse {
   clientId: string;
@@ -53,6 +57,53 @@ function isOptedOut(): boolean {
   return process.env.HQ_NO_UPDATE_CHECK === "1";
 }
 
+function findRunningPackageRoot(): string | null {
+  let dir = path.dirname(fileURLToPath(import.meta.url));
+  while (true) {
+    try {
+      const pkg = JSON.parse(
+        readFileSync(path.join(dir, "package.json"), "utf-8"),
+      ) as { name?: unknown };
+      if (pkg.name === CLI_NAME) return dir;
+    } catch {
+      // Keep walking; compiled installs usually start under dist/.
+    }
+
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+export function npmPrefixFromPackageDir(pkgDir: string): string | null {
+  const normalized = pkgDir.replace(/\\/g, "/").replace(/\/+$/, "");
+  const segments = normalized.split("/");
+  const nodeModulesIndex = segments.lastIndexOf("node_modules");
+  if (nodeModulesIndex === -1) return null;
+
+  const prefixEnd =
+    segments[nodeModulesIndex - 1] === "lib"
+      ? nodeModulesIndex - 1
+      : nodeModulesIndex;
+  const prefix = segments.slice(0, prefixEnd).join("/");
+  if (prefix === "" && normalized.startsWith("/")) return "/";
+  return prefix || null;
+}
+
+export function resolveRunningPrefix(): string | null {
+  try {
+    const pkgRoot = findRunningPackageRoot();
+    if (!pkgRoot) return null;
+    return npmPrefixFromPackageDir(pkgRoot);
+  } catch {
+    return null;
+  }
+}
+
+export function buildPrefixedInstallArgv(prefix: string): string[] {
+  return ["install", "-g", "--prefix", prefix, LATEST_PACKAGE_SPEC];
+}
+
 /**
  * Hit POST /v1/client-version/check. Returns the parsed body on 200, or
  * `null` on any failure (caller treats as "no gate"). Tight 3s timeout —
@@ -95,13 +146,10 @@ async function fetchVersionDecision(): Promise<VersionCheckResponse | null> {
  * forcing a re-invocation would run twice on the same process and feel
  * janky; instead we print a clear "rerun your command" message and exit.
  */
-function performUpdate(
-  command: string,
-): { ok: boolean; detail?: string } {
-  const parts = command.split(/\s+/).filter(Boolean);
-  if (parts.length === 0) return { ok: false, detail: "empty command" };
-  const cmd = parts[0]!;
-  const args = parts.slice(1);
+type UpdateResult = { ok: boolean; detail?: string };
+type UpdateRunner = (cmd: string, args: string[]) => UpdateResult;
+
+function runUpdateCommand(cmd: string, args: string[]): UpdateResult {
   try {
     const result = spawnSync(cmd, args, { stdio: "inherit" });
     if (result.status !== 0) {
@@ -116,6 +164,25 @@ function performUpdate(
   }
 }
 
+function performUpdateCommand(
+  cmd: string,
+  args: string[],
+  runner: UpdateRunner = runUpdateCommand,
+): UpdateResult {
+  return runner(cmd, args);
+}
+
+function performUpdate(
+  command: string,
+  runner: UpdateRunner = runUpdateCommand,
+): UpdateResult {
+  const parts = command.split(/\s+/).filter(Boolean);
+  if (parts.length === 0) return { ok: false, detail: "empty command" };
+  const cmd = parts[0]!;
+  const args = parts.slice(1);
+  return performUpdateCommand(cmd, args, runner);
+}
+
 /**
  * Soft notify when the server says we're below `latestVersion` but still ≥
  * `minVersion`. Single chalk-yellow line on stderr; never blocks.
@@ -140,7 +207,14 @@ function nudgeUpdateRecommended(decision: VersionCheckResponse): void {
  *   0 — update succeeded; user must rerun their command
  *   75 — update failed (EX_TEMPFAIL; common for sudo/EACCES on system npm)
  */
-function enforceUpdateRequired(decision: VersionCheckResponse): never {
+function enforceUpdateRequired(
+  decision: VersionCheckResponse,
+  deps: {
+    performUpdateString?: (command: string) => UpdateResult;
+    resolvePrefix?: () => string | null;
+    runner?: UpdateRunner;
+  } = {},
+): never {
   const banner = chalk.red.bold(
     `✗ hq-cli ${decision.currentVersion} is below the minimum required version (${decision.minVersion}).`,
   );
@@ -148,7 +222,8 @@ function enforceUpdateRequired(decision: VersionCheckResponse): never {
   if (decision.message) console.error(chalk.dim(`  ${decision.message}`));
 
   const command = decision.updateCommand;
-  if (!command) {
+  const prefix = (deps.resolvePrefix ?? resolveRunningPrefix)();
+  if (!command && !prefix) {
     console.error(
       chalk.red(
         "  No updateCommand provided by hq-pro — see https://hq.indigo.ai/docs/cli-update for manual steps.",
@@ -160,13 +235,28 @@ function enforceUpdateRequired(decision: VersionCheckResponse): never {
     process.exit(75);
   }
 
-  console.error(chalk.dim(`  Running: ${command}`));
-  const result = performUpdate(command);
+  const runner = deps.runner ?? runUpdateCommand;
+  const result = prefix
+    ? (() => {
+        const args = buildPrefixedInstallArgv(prefix);
+        console.error(chalk.dim(`  Installing into npm prefix: ${prefix}`));
+        console.error(chalk.dim(`  Running: npm ${args.join(" ")}`));
+        return performUpdateCommand("npm", args, runner);
+      })()
+    : (() => {
+        console.error(chalk.dim(`  Running: ${command}`));
+        return deps.performUpdateString
+          ? deps.performUpdateString(command!)
+          : performUpdate(command!, runner);
+      })();
   if (!result.ok) {
     console.error(
       chalk.red(`✗ Update failed${result.detail ? `: ${result.detail}` : ""}.`),
     );
-    console.error(chalk.dim(`  Try manually: ${command}`));
+    const manual = prefix
+      ? `npm ${buildPrefixedInstallArgv(prefix).join(" ")}`
+      : command!;
+    console.error(chalk.dim(`  Try manually: ${manual}`));
     process.exit(75);
   }
 
@@ -215,5 +305,11 @@ export const __test__ = {
   CLIENT_ID,
   ENDPOINT_PATH,
   FETCH_TIMEOUT_MS,
+  buildPrefixedInstallArgv,
+  enforceUpdateRequired,
+  npmPrefixFromPackageDir,
   performUpdate,
+  performUpdateCommand,
+  runUpdateCommand,
+  resolveRunningPrefix,
 };