@indigoai-us/hq-cli 5.77.8 → 5.77.9

package/src/utils/version-gate.ts

@@ -41,6 +41,9 @@ 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;
@@ -90,20 +93,124 @@ export function npmPrefixFromPackageDir(pkgDir: string): string | null {
   return prefix || null;
 }
 
-export function resolveRunningPrefix(): string | 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 pkgRoot = findRunningPackageRoot();
-    if (!pkgRoot) return null;
-    return npmPrefixFromPackageDir(pkgRoot);
+    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 null;
+    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.
@@ -249,12 +356,50 @@ 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.
  */
-type UpdateResult = { ok: boolean; detail?: string };
+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 result = spawnSync(cmd, args, { stdio: "inherit" });
+    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,
@@ -263,7 +408,11 @@ function runUpdateCommand(cmd: string, args: string[]): UpdateResult {
     }
     return { ok: true };
   } catch (err) {
-    return { ok: false, detail: err instanceof Error ? err.message : String(err) };
+    return {
+      ok: false,
+      code: (err as NodeJS.ErrnoException | undefined)?.code,
+      detail: err instanceof Error ? err.message : String(err),
+    };
   }
 }
 
@@ -286,17 +435,46 @@ function performUpdate(
   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): void {
+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);
-  if (decision.updateCommand) {
-    console.error(chalk.dim(`  Update: ${decision.updateCommand}`));
+  const command =
+    install.manager === "pnpm"
+      ? `pnpm ${buildPnpmInstallArgv().join(" ")}`
+      : decision.updateCommand;
+  if (command) {
+    console.error(chalk.dim(`  Update: ${command}`));
   }
 }
 
@@ -314,7 +492,7 @@ function enforceUpdateRequired(
   decision: VersionCheckResponse,
   deps: {
     performUpdateString?: (command: string) => UpdateResult;
-    resolvePrefix?: () => string | null;
+    resolveInstall?: () => RunningInstall;
     runner?: UpdateRunner;
     cleanStale?: (prefix: string) => string[];
   } = {},
@@ -326,8 +504,14 @@ function enforceUpdateRequired(
   if (decision.message) console.error(chalk.dim(`  ${decision.message}`));
 
   const command = decision.updateCommand;
-  const prefix = (deps.resolvePrefix ?? resolveRunningPrefix)();
-  if (!command && !prefix) {
+  // 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.",
@@ -344,7 +528,10 @@ function enforceUpdateRequired(
   // the EXACT same command under elevation.
   let primaryCmd: string;
   let primaryArgs: string[];
-  if (prefix) {
+  if (isPnpm) {
+    primaryCmd = "pnpm";
+    primaryArgs = buildPnpmInstallArgv();
+  } else if (prefix) {
     primaryCmd = "npm";
     primaryArgs = buildPrefixedInstallArgv(prefix);
   } else {
@@ -353,18 +540,23 @@ function enforceUpdateRequired(
     primaryArgs = parts.slice(1);
   }
 
-  let result = prefix
-    ? (() => {
-        console.error(chalk.dim(`  Installing into npm prefix: ${prefix}`));
-        console.error(chalk.dim(`  Running: npm ${primaryArgs.join(" ")}`));
-        return performUpdateCommand("npm", primaryArgs, runner);
-      })()
-    : (() => {
-        console.error(chalk.dim(`  Running: ${command}`));
-        return deps.performUpdateString
-          ? deps.performUpdateString(command!)
-          : performUpdate(command!, runner);
-      })();
+  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
@@ -395,7 +587,11 @@ function enforceUpdateRequired(
   // 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.
-  if (!result.ok && primaryCmd) {
+  //
+  // 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(" ")}`,
@@ -413,10 +609,29 @@ function enforceUpdateRequired(
     console.error(
       chalk.red(`✗ Update failed${result.detail ? `: ${result.detail}` : ""}.`),
     );
-    const manual = prefix
-      ? `npm ${buildPrefixedInstallArgv(prefix).join(" ")}`
-      : command!;
+    // 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);
   }
 
@@ -442,11 +657,15 @@ 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); // exits process
+    enforceUpdateRequired(decision, { resolveInstall: () => install }); // exits process
   }
   if (decision.updateRecommended) {
-    nudgeUpdateRecommended(decision);
+    nudgeUpdateRecommended(decision, install);
   }
 }
 
@@ -465,12 +684,19 @@ 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,
 };