@indigoai-us/hq-cli 5.77.14 → 5.78.0

package/src/utils/version-gate.ts

@@ -1,702 +0,0 @@
-/**
- * Hard version-gate: ask hq-pro whether the current CLI is below the minimum
- * acceptable version and, if so, run `npm install -g …@latest` synchronously
- * before any commander parsing happens. Distinct from the existing
- * `version-check.ts` which is a passive (cached, opt-in) stderr nag against
- * the npm registry.
- *
- * Why both?
- *   - `version-check.ts` answers "is there something newer?" by polling npm
- *     directly. It's a soft hint, lives on a 24h cache, and never blocks.
- *   - `version-gate.ts` answers "is the team currently allowing your version
- *     to run?" via an authoritative hq-pro endpoint. The server can yank a
- *     known-bad release without waiting for the npm `latest` dist-tag move.
- *
- * The endpoint is reusable across clients (hq-sync, hq-installer, create-hq).
- * See `apps/hq-pro/src/vault-service/handlers/client-version-check.ts` for the
- * source-of-truth table.
- *
- * Trust model: anonymous. The CLI may be running pre-login (e.g. fresh
- * install) so we never send credentials. The endpoint identifies the client
- * by `clientId` + `currentVersion`.
- *
- * Failure mode: silent. Network down, hq-pro returning 5xx, malformed body —
- * the gate must never break the CLI for a user who's otherwise fine. We log
- * to Sentry as a breadcrumb (best-effort) and return.
- *
- * Opt-out: `HQ_NO_UPDATE_CHECK=1` (same env as `version-check.ts` — one knob
- * to silence both check + gate).
- */
-
-import { spawnSync } from "node:child_process";
-import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import chalk from "chalk";
-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`;
-
-/** Which package manager owns the running global install. */
-export type InstallManager = "npm" | "pnpm";
-
-interface VersionCheckResponse {
-  clientId: string;
-  currentVersion: string;
-  minVersion: string;
-  latestVersion: string;
-  updateRequired: boolean;
-  updateRecommended: boolean;
-  updateCommand?: string;
-  downloadUrl?: string;
-  message?: string;
-}
-
-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;
-}
-
-/** `$PNPM_HOME/global`, normalised to forward slashes, when PNPM_HOME is set. */
-function pnpmHomeGlobalRoot(): string | null {
-  const home = process.env.PNPM_HOME;
-  if (!home) return null;
-  const normalized = home.replace(/\\/g, "/").replace(/\/+$/, "");
-  return normalized ? `${normalized}/global` : null;
-}
-
-/**
- * Whether the running package lives inside a pnpm-managed **global** install.
- *
- * pnpm does not use npm's `<prefix>/lib/node_modules` layout. A global
- * `pnpm add -g` puts the package in a versioned content store under the
- * `global/<store-layout-version>` root and exposes it through a generated shim
- * on PATH:
- *
- *   $PNPM_HOME/hq                                        <- shim on PATH
- *   $PNPM_HOME/global/5/node_modules/@indigoai-us/hq-cli <- symlink
- *   $PNPM_HOME/global/5/.pnpm/@indigoai-us+hq-cli@5.61.0/node_modules/…
- *
- * Both the symlinked and the resolved (`.pnpm`) form are recognised, because
- * whether `import.meta.url` reports the link or its target depends on how node
- * resolved the entrypoint.
- *
- * A bare `.pnpm` segment is deliberately NOT enough. It also appears in a local
- * project dependency (`<proj>/node_modules/.pnpm/@indigoai-us+hq-cli@…`) and in
- * a `pnpm dlx` cache. Neither of those is what `pnpm add -g` updates, so
- * treating them as global would mutate the user's global install as a side
- * effect of a local invocation while the copy actually running stayed stale —
- * i.e. the gate would re-fire and re-install globally on every subsequent run.
- * Those layouts fall through to the ordinary npm-prefix/manual handling.
- */
-export function isPnpmManagedPackageDir(pkgDir: string): boolean {
-  const normalized = pkgDir.replace(/\\/g, "/").replace(/\/+$/, "");
-  const segments = normalized.split("/").filter(Boolean);
-
-  // `global/<digits>` — pnpm's global root, in either the symlinked or the
-  // resolved (`.pnpm`) form, and independent of where PNPM_HOME points.
-  for (let i = 0; i < segments.length - 1; i += 1) {
-    if (segments[i] === "global" && /^\d+$/.test(segments[i + 1]!)) return true;
-  }
-
-  // Belt-and-braces for a future pnpm layout whose store dir is not numeric:
-  // anything under `$PNPM_HOME/global` is global by construction. Still keyed
-  // on the `global` segment so `$PNPM_HOME/store/**` (dlx caches) stays out.
-  const globalRoot = pnpmHomeGlobalRoot();
-  if (globalRoot) {
-    if (normalized === globalRoot || normalized.startsWith(`${globalRoot}/`)) {
-      return true;
-    }
-  }
-
-  return false;
-}
-
-/**
- * Where the running CLI is installed and who owns it. Resolved in ONE pass so
- * the package-root walk (which reads and parses a `package.json` per directory
- * level) happens once per invocation, and so the manager and the prefix can
- * never disagree because the filesystem shifted between two separate walks.
- *
- * `prefix` is `null` for a pnpm-managed install even though a prefix-shaped
- * string *can* be derived from those paths: `npmPrefixFromPackageDir` would
- * happily hand back the pnpm store directory, and `npm install -g --prefix
- * <store>` then unpacks a fresh copy into `<store>/lib/node_modules`, which
- * pnpm's shim never reads. npm exits 0, the gate reports success, and the next
- * `hq` invocation still runs the old version — the reported loop where a stale
- * pnpm shim kept resolving 5.61.0 after every "successful" update.
- *
- * Defaults to npm with no prefix when the layout can't be determined — that is
- * the historical behaviour and the common case.
- */
-export interface RunningInstall {
-  manager: InstallManager;
-  prefix: string | null;
-  packageRoot: string | null;
-}
-
-export function resolveRunningInstall(): RunningInstall {
-  try {
-    const packageRoot = findRunningPackageRoot();
-    if (!packageRoot) return { manager: "npm", prefix: null, packageRoot: null };
-    if (isPnpmManagedPackageDir(packageRoot)) {
-      return { manager: "pnpm", prefix: null, packageRoot };
-    }
-    return {
-      manager: "npm",
-      prefix: npmPrefixFromPackageDir(packageRoot),
-      packageRoot,
-    };
-  } catch {
-    return { manager: "npm", prefix: null, packageRoot: null };
-  }
-}
-
-/** Convenience view of {@link resolveRunningInstall} for callers needing one field. */
-export function resolveRunningManager(): InstallManager {
-  return resolveRunningInstall().manager;
-}
-
-/** Convenience view of {@link resolveRunningInstall} for callers needing one field. */
-export function resolveRunningPrefix(): string | null {
-  return resolveRunningInstall().prefix;
-}
-
-export function buildPrefixedInstallArgv(prefix: string): string[] {
-  return ["install", "-g", "--prefix", prefix, LATEST_PACKAGE_SPEC];
-}
-
-/**
- * Argv for updating a pnpm-managed global install. `pnpm add -g` rewrites the
- * PATH shim as part of the install, so the next invocation genuinely resolves
- * the new version — which is the whole point of routing here instead of npm.
- */
-export function buildPnpmInstallArgv(): string[] {
-  return ["add", "-g", LATEST_PACKAGE_SPEC];
-}
-
-/**
- * Filesystem surface used by {@link cleanStalePartialInstall}. Injected so the
- * cleanup logic is unit-testable without touching a real global prefix.
- */
-export interface StaleInstallFs {
-  readdirSync: (dir: string) => string[];
-  existsSync: (target: string) => boolean;
-  readFileSync: (target: string, encoding: "utf-8") => string;
-  rmSync: (target: string, options: { recursive: boolean; force: boolean }) => void;
-}
-
-const nodeStaleInstallFs: StaleInstallFs = {
-  readdirSync: (dir) => readdirSync(dir),
-  existsSync,
-  readFileSync: (target, encoding) => readFileSync(target, encoding),
-  rmSync,
-};
-
-function isHealthyPackageDir(pkgDir: string, fs: StaleInstallFs): boolean {
-  try {
-    const pkg = JSON.parse(
-      fs.readFileSync(path.join(pkgDir, "package.json"), "utf-8"),
-    ) as { name?: unknown };
-    return pkg.name === CLI_NAME;
-  } catch {
-    return false; // missing / unreadable / malformed package.json ⇒ partial
-  }
-}
-
-/**
- * Remove leftover artifacts from an interrupted `npm install -g` so a retry can
- * succeed. npm unpacks a package into a `.<pkg>-<rand>` staging dir alongside
- * the final location and then renames it into place; if a previous run was
- * killed mid-rename (or a half-written package dir survives), every subsequent
- * install fails with `ENOTEMPTY` because npm cannot atomically rename over the
- * non-empty leftover. npm does not self-heal this — the stale dir must be
- * removed first.
- *
- * To stay safe we only ever delete:
- *   - dot-prefixed npm staging dirs for THIS package (`.hq-cli-*`), and
- *   - a package dir whose `package.json` is missing/unreadable or whose `name`
- *     is not exactly {@link CLI_NAME} (i.e. a genuinely partial/foreign dir).
- *
- * A healthy install (valid `package.json`, `name === CLI_NAME`) is never
- * touched, so an ordinary version bump still flows through npm untouched.
- *
- * Returns the list of removed paths — empty when there was nothing to clean, so
- * callers can gate a reinstall retry on `removed.length > 0`.
- */
-export function cleanStalePartialInstall(
-  prefix: string,
-  fs: StaleInstallFs = nodeStaleInstallFs,
-): string[] {
-  const removed: string[] = [];
-  const slash = CLI_NAME.indexOf("/");
-  const scope = slash === -1 ? null : CLI_NAME.slice(0, slash);
-  const leaf = slash === -1 ? CLI_NAME : CLI_NAME.slice(slash + 1);
-  const stagingPrefix = `.${leaf}-`;
-
-  // Global npm keeps packages under `<prefix>/lib/node_modules` (unix) while a
-  // bare `--prefix` dir (windows / some sandboxes) uses `<prefix>/node_modules`.
-  const nmRoots = [
-    path.join(prefix, "lib", "node_modules"),
-    path.join(prefix, "node_modules"),
-  ];
-
-  for (const nmRoot of nmRoots) {
-    // For a scoped package the staging dir + final dir both live inside the
-    // scope dir (`.../@indigoai-us/.hq-cli-<rand>`, `.../@indigoai-us/hq-cli`).
-    const parentDir = scope ? path.join(nmRoot, scope) : nmRoot;
-    let entries: string[];
-    try {
-      entries = fs.readdirSync(parentDir);
-    } catch {
-      continue; // this node_modules / scope dir doesn't exist here
-    }
-
-    for (const entry of entries) {
-      if (!entry.startsWith(stagingPrefix)) continue;
-      const target = path.join(parentDir, entry);
-      try {
-        fs.rmSync(target, { recursive: true, force: true });
-        removed.push(target);
-      } catch {
-        // best-effort: a dir we can't remove (perms) just means the retry
-        // still fails and we fall through to the sudo / manual path.
-      }
-    }
-
-    const pkgDir = path.join(parentDir, leaf);
-    if (fs.existsSync(pkgDir) && !isHealthyPackageDir(pkgDir, fs)) {
-      try {
-        fs.rmSync(pkgDir, { recursive: true, force: true });
-        removed.push(pkgDir);
-      } catch {
-        // best-effort (see above)
-      }
-    }
-  }
-
-  return removed;
-}
-
-/**
- * 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 —
- * a hung server must not delay CLI startup.
- */
-async function fetchVersionDecision(): Promise<VersionCheckResponse | null> {
-  try {
-    const url = `${DEFAULT_VAULT_API_URL}${ENDPOINT_PATH}`;
-    const res = await fetch(url, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Accept: "application/json",
-      },
-      body: JSON.stringify({
-        clientId: CLIENT_ID,
-        currentVersion: CLI_VERSION,
-        platform: `${process.platform}-${process.arch}`,
-      }),
-      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
-    });
-    if (!res.ok) return null;
-    const body = (await res.json()) as Partial<VersionCheckResponse>;
-    if (
-      typeof body.minVersion !== "string" ||
-      typeof body.latestVersion !== "string" ||
-      typeof body.updateRequired !== "boolean"
-    ) {
-      return null;
-    }
-    return body as VersionCheckResponse;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Run the upgrade command in a blocking subprocess. Inherits stdio so the
- * user sees the npm progress. We do NOT auto-rerun the CLI on completion —
- * 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.
- */
-type UpdateResult = { ok: boolean; detail?: string; code?: string };
-type UpdateRunner = (cmd: string, args: string[]) => UpdateResult;
-
-/**
- * Quote an argv entry for a Windows `cmd.exe` invocation. Needed because Node
- * does NOT quote argv when spawning with `shell: true` on Windows — it joins
- * the array with spaces — so an npm prefix like `C:\Program Files\…` would be
- * split into two arguments.
- */
-export function quoteForWindowsShell(arg: string): string {
-  if (arg === "") return '""';
-  if (!/[\s"^&|<>()]/.test(arg)) return arg;
-  return `"${arg.replace(/"/g, '\\"')}"`;
-}
-
-/**
- * How to hand `<cmd> <args…>` to `spawnSync` on this platform.
- *
- * On Windows both `npm` and `pnpm` are `.cmd` shims, and since the
- * CVE-2024-27980 hardening Node refuses to spawn a `.cmd`/`.bat` file without
- * a shell. Without this the update would fail with EINVAL/ENOENT on every
- * Windows install — including the pnpm layouts this gate claims to detect.
- */
-export function buildSpawnPlan(
-  cmd: string,
-  args: readonly string[],
-  platform: NodeJS.Platform = process.platform,
-): { cmd: string; args: string[]; shell: boolean } {
-  if (platform !== "win32") return { cmd, args: [...args], shell: false };
-  return { cmd, args: args.map(quoteForWindowsShell), shell: true };
-}
-
-function runUpdateCommand(cmd: string, args: string[]): UpdateResult {
-  try {
-    const plan = buildSpawnPlan(cmd, args);
-    const result = spawnSync(plan.cmd, plan.args, {
-      stdio: "inherit",
-      shell: plan.shell,
-    });
-    // spawnSync reports a missing executable via `error`, not a throw.
-    if (result.error) {
-      const code = (result.error as NodeJS.ErrnoException).code;
-      return { ok: false, code, detail: result.error.message };
-    }
-    if (result.status !== 0) {
-      return {
-        ok: false,
-        detail: `exit ${result.status ?? "signal"}`,
-      };
-    }
-    return { ok: true };
-  } catch (err) {
-    return {
-      ok: false,
-      code: (err as NodeJS.ErrnoException | undefined)?.code,
-      detail: err instanceof Error ? err.message : String(err),
-    };
-  }
-}
-
-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);
-}
-
-/**
- * The command a user should run by hand for this install layout. hq-pro's
- * `updateCommand` is npm-shaped for every client, so a pnpm-managed install
- * must never be told to run it: `npm install -g …` drops a fresh copy under the
- * npm global prefix while pnpm's PATH shim keeps resolving the old build. That
- * is verbatim the reported symptom (a stale shim still reporting 5.61.0 after a
- * "successful" update), so both the hard gate and the soft nudge below have to
- * speak the running manager's language.
- */
-function manualUpdateCommand(
-  install: RunningInstall,
-  decision: VersionCheckResponse,
-): string | undefined {
-  if (install.manager === "pnpm") return `pnpm ${buildPnpmInstallArgv().join(" ")}`;
-  if (install.prefix) return `npm ${buildPrefixedInstallArgv(install.prefix).join(" ")}`;
-  return decision.updateCommand;
-}
-
-/**
- * Soft notify when the server says we're below `latestVersion` but still ≥
- * `minVersion`. Single chalk-yellow line on stderr; never blocks.
- *
- * This path fires for EVERY version below latest (the hard gate only fires
- * below `minVersion`), so it is the far more frequently seen of the two and
- * must be manager-aware for the same reason the gate is.
- */
-function nudgeUpdateRecommended(
-  decision: VersionCheckResponse,
-  install: RunningInstall = resolveRunningInstall(),
-): void {
-  const msg = chalk.yellow(
-    `⚠ A new version of hq-cli is available: ${decision.latestVersion} (current: ${decision.currentVersion}).`,
-  );
-  console.error(msg);
-  const command =
-    install.manager === "pnpm"
-      ? `pnpm ${buildPnpmInstallArgv().join(" ")}`
-      : decision.updateCommand;
-  if (command) {
-    console.error(chalk.dim(`  Update: ${command}`));
-  }
-}
-
-/**
- * Hard enforcement when the server says we're below `minVersion`. Print a
- * red banner, attempt the update, then exit so the user reruns against the
- * fresh binary. Sequence chosen so a user with a broken `npm` global prefix
- * still gets a clear error rather than an opaque silent failure.
- *
- * Exit codes:
- *   0 — update succeeded; user must rerun their command
- *   75 — update failed (EX_TEMPFAIL; common for sudo/EACCES on system npm)
- */
-function enforceUpdateRequired(
-  decision: VersionCheckResponse,
-  deps: {
-    performUpdateString?: (command: string) => UpdateResult;
-    resolveInstall?: () => RunningInstall;
-    runner?: UpdateRunner;
-    cleanStale?: (prefix: string) => string[];
-  } = {},
-): never {
-  const banner = chalk.red.bold(
-    `✗ hq-cli ${decision.currentVersion} is below the minimum required version (${decision.minVersion}).`,
-  );
-  console.error(banner);
-  if (decision.message) console.error(chalk.dim(`  ${decision.message}`));
-
-  const command = decision.updateCommand;
-  // ONE package-root walk decides both the manager and the prefix. A
-  // pnpm-managed install must be updated by pnpm; the server's `updateCommand`
-  // and any npm prefix are both wrong for that layout, so `resolveRunningInstall`
-  // already reports `prefix: null` there and neither is consulted below.
-  const install = (deps.resolveInstall ?? resolveRunningInstall)();
-  const isPnpm = install.manager === "pnpm";
-  const prefix = install.prefix;
-  if (!isPnpm && !command && !prefix) {
-    console.error(
-      chalk.red(
-        "  No updateCommand provided by hq-pro — see https://hq.indigo.ai/docs/cli-update for manual steps.",
-      ),
-    );
-    if (decision.downloadUrl) {
-      console.error(chalk.dim(`  Download: ${decision.downloadUrl}`));
-    }
-    process.exit(75);
-  }
-
-  const runner = deps.runner ?? runUpdateCommand;
-  // Resolve the concrete install argv once so the sudo fallback below can re-run
-  // the EXACT same command under elevation.
-  let primaryCmd: string;
-  let primaryArgs: string[];
-  if (isPnpm) {
-    primaryCmd = "pnpm";
-    primaryArgs = buildPnpmInstallArgv();
-  } else if (prefix) {
-    primaryCmd = "npm";
-    primaryArgs = buildPrefixedInstallArgv(prefix);
-  } else {
-    const parts = (command ?? "").split(/\s+/).filter(Boolean);
-    primaryCmd = parts[0] ?? "";
-    primaryArgs = parts.slice(1);
-  }
-
-  let result: UpdateResult;
-  if (isPnpm) {
-    console.error(
-      chalk.dim("  Detected a pnpm-managed global install; updating with pnpm"),
-    );
-    console.error(chalk.dim(`  Running: pnpm ${primaryArgs.join(" ")}`));
-    result = performUpdateCommand("pnpm", primaryArgs, runner);
-  } else if (prefix) {
-    console.error(chalk.dim(`  Installing into npm prefix: ${prefix}`));
-    console.error(chalk.dim(`  Running: npm ${primaryArgs.join(" ")}`));
-    result = performUpdateCommand("npm", primaryArgs, runner);
-  } else {
-    console.error(chalk.dim(`  Running: ${command}`));
-    result = deps.performUpdateString
-      ? deps.performUpdateString(command!)
-      : performUpdate(command!, runner);
-  }
-
-  // A partial/corrupt global install leaves npm unable to atomically rename its
-  // freshly-unpacked package over a leftover directory, so the install above
-  // fails with ENOTEMPTY (e.g. a prior interrupted `npm install -g` left a
-  // half-written `hq-cli` package dir or a `.hq-cli-<rand>` staging dir under
-  // the prefix's node_modules). npm cannot self-heal this. Remove the stale
-  // artifacts and retry the install ONCE. Guarded on `cleaned.length > 0` so a
-  // plain EACCES on an otherwise-healthy prefix falls straight through to the
-  // sudo retry below without a redundant reinstall attempt.
-  if (!result.ok && prefix) {
-    const cleaner = deps.cleanStale ?? cleanStalePartialInstall;
-    const cleaned = cleaner(prefix);
-    if (cleaned.length > 0) {
-      console.error(
-        chalk.dim(
-          `  Removing stale partial install artifacts and retrying: ${cleaned.join(", ")}`,
-        ),
-      );
-      result = performUpdateCommand("npm", primaryArgs, runner);
-    }
-  }
-
-  // A root-owned global install (e.g. a system `/usr` install where the CLI runs
-  // unprivileged — the outpost agent boxes) can't rewrite the prefix's bin dir,
-  // so the install above fails with EACCES (`rename /usr/bin/hq`). Retry ONCE
-  // under non-interactive sudo: `sudo -n` fails fast WITHOUT a password prompt
-  // when passwordless sudo isn't configured, so interactive installs (e.g.
-  // Homebrew on macOS, where the first attempt already succeeded anyway) fall
-  // through to the manual path unchanged, while headless boxes with passwordless
-  // sudo self-update cleanly.
-  //
-  // Never for pnpm: `sudo -n pnpm add -g` installs into ROOT's PNPM_HOME, which
-  // leaves the user's shim untouched while reporting success — the same silent
-  // no-op this fix exists to remove. A failed pnpm update must surface instead.
-  if (!result.ok && primaryCmd && !isPnpm) {
-    console.error(
-      chalk.dim(
-        `  Update failed unprivileged; retrying with: sudo -n ${primaryCmd} ${primaryArgs.join(" ")}`,
-      ),
-    );
-    const sudoResult = performUpdateCommand(
-      "sudo",
-      ["-n", primaryCmd, ...primaryArgs],
-      runner,
-    );
-    if (sudoResult.ok) result = sudoResult;
-  }
-
-  if (!result.ok) {
-    console.error(
-      chalk.red(`✗ Update failed${result.detail ? `: ${result.detail}` : ""}.`),
-    );
-    // The package manager itself is missing from this environment — the usual
-    // cause is a minimal-PATH parent (launchd, cron, a bare systemd unit) that
-    // never sourced the shell profile which puts PNPM_HOME (or nvm's npm) on
-    // PATH. Say so, because "exit 75" alone reads as a permissions problem.
-    if (result.code === "ENOENT") {
-      console.error(
-        chalk.red(
-          `  \`${primaryCmd}\` was not found on PATH in this environment (launchd, cron and other minimal-PATH parents commonly lack it).`,
-        ),
-      );
-    }
-    const manual = manualUpdateCommand(install, decision) ?? command!;
-    console.error(chalk.dim(`  Try manually: ${manual}`));
-    // Only informational, and only when we could not run the right manager at
-    // all: hq-pro's command is npm-shaped, so following it on a pnpm layout is
-    // what produced the stale-shim loop in the first place.
-    if (isPnpm && result.code === "ENOENT" && command) {
-      console.error(
-        chalk.dim(
-          `  (hq-pro suggests \`${command}\` — that is for npm-managed installs; use it only if you have switched this install to npm.)`,
-        ),
-      );
-    }
-    process.exit(75);
-  }
-
-  console.error(
-    chalk.green(
-      `✓ Updated to hq-cli ${decision.latestVersion}. Rerun your command.`,
-    ),
-  );
-  process.exit(0);
-}
-
-/**
- * Public entry point. Call before commander parses argv. Blocks the CLI on
- * network IO for up to FETCH_TIMEOUT_MS — acceptable because the alternative
- * (a fire-and-forget background check) gives the user no chance to bail out
- * of a known-bad version before it does damage.
- *
- * `--version` / `-v` callers MUST skip the gate (the user is debugging a
- * broken install and shouldn't be force-upgraded mid-investigation). Caller
- * is responsible for checking argv before invoking us — see index.ts.
- */
-export async function enforceVersionGate(): Promise<void> {
-  if (isOptedOut()) return;
-  const decision = await fetchVersionDecision();
-  if (!decision) return; // best-effort: silent on any failure
-  if (!decision.updateRequired && !decision.updateRecommended) return;
-  // Resolved once, here, so the up-to-date case never pays for the walk and
-  // neither downstream path repeats it.
-  const install = resolveRunningInstall();
-  if (decision.updateRequired) {
-    enforceUpdateRequired(decision, { resolveInstall: () => install }); // exits process
-  }
-  if (decision.updateRecommended) {
-    nudgeUpdateRecommended(decision, install);
-  }
-}
-
-/**
- * Cheap argv pre-check: skip the gate for `--version` / `-V` so users
- * inspecting a broken install can still see what they have without being
- * force-upgraded.
- */
-export function shouldSkipGate(argv: readonly string[]): boolean {
-  return argv.some(
-    (a) => a === "--version" || a === "-V" || a === "-v" || a === "--help" || a === "-h",
-  );
-}
-
-export const __test__ = {
-  CLIENT_ID,
-  ENDPOINT_PATH,
-  FETCH_TIMEOUT_MS,
-  buildPnpmInstallArgv,
-  buildPrefixedInstallArgv,
-  buildSpawnPlan,
-  cleanStalePartialInstall,
-  enforceUpdateRequired,
-  isPnpmManagedPackageDir,
-  npmPrefixFromPackageDir,
-  nudgeUpdateRecommended,
-  performUpdate,
-  performUpdateCommand,
-  quoteForWindowsShell,
-  runUpdateCommand,
-  resolveRunningInstall,
-  resolveRunningManager,
-  resolveRunningPrefix,
-};