@indigoai-us/hq-cli 5.115.6 → 5.116.0

package/dist/utils/version-gate.js

@@ -534,16 +534,74 @@ export function inOwnProcessGroup(options) {
 }
 /** Tail of captured installer stderr kept to explain a failure. */
 const INSTALL_DETAIL_MAX_CHARS = 400;
+/** Give a package-manager update ample time without letting it wedge every CLI call. */
+const DEFAULT_UPDATE_TIMEOUT_MS = 30 * 60 * 1_000;
+/** Node clamps longer timer delays to 1ms, so accepting them would invert the deadline. */
+const MAX_UPDATE_TIMEOUT_MS = 2_147_483_647;
+/** Let a well-behaved updater stop before force-killing the rest of its group. */
+const UPDATE_TERMINATE_GRACE_MS = 1_000;
+/** A successful group kill must still yield a close event so the supervisor reaps its child. */
+const UPDATE_REAP_GRACE_MS = 1_000;
+function updateTimeoutMs(env = process.env) {
+    const value = env.HQ_UPDATE_TIMEOUT_MS;
+    if (value === undefined || value.trim() === "")
+        return DEFAULT_UPDATE_TIMEOUT_MS;
+    const parsed = Number(value);
+    if (Number.isInteger(parsed) && parsed > 0 && parsed <= MAX_UPDATE_TIMEOUT_MS) {
+        return parsed;
+    }
+    // Falling back rather than clamping is deliberate: a clamp would silently
+    // substitute a materially different deadline. The warning tells operators
+    // their requested value was rejected before any update begins.
+    console.error(chalk.yellow(`⚠ Ignoring HQ_UPDATE_TIMEOUT_MS=${JSON.stringify(value)}: expected a positive integer no greater than ${MAX_UPDATE_TIMEOUT_MS}ms; using ${DEFAULT_UPDATE_TIMEOUT_MS}ms.`));
+    return DEFAULT_UPDATE_TIMEOUT_MS;
+}
+/**
+ * The actual installer runs in a small asynchronous supervisor, rather than
+ * directly under `spawnSync`. `spawnSync({ timeout })` only signals its direct
+ * child. That is unsafe here because the installer deliberately runs in its
+ * own process group: the leader can exit while its descendants keep the global
+ * store and registry connection alive. The CommonJS file is copied next to the
+ * compiled module for production and is directly runnable from source tests.
+ */
+const UPDATE_COMMAND_SUPERVISOR = fileURLToPath(new URL("./update-command-supervisor.cjs", import.meta.url));
+function readSupervisorSpawnError(errorMarker) {
+    try {
+        const value = JSON.parse(readFileSync(errorMarker, "utf-8"));
+        const code = typeof value.code === "string" ? value.code : undefined;
+        const detail = typeof value.detail === "string" ? value.detail : undefined;
+        return code === undefined && detail === undefined ? undefined : { code, detail };
+    }
+    catch {
+        return undefined;
+    }
+}
 export function openInstallOutput(verbose, isTty = process.stdout.isTTY === true && process.stderr.isTTY === true) {
     if (verbose && isTty) {
+        const dir = mkdtempSync(path.join(os.tmpdir(), "hq-cli-install-"));
+        const timeoutMarker = path.join(dir, "timed-out");
+        const errorMarker = path.join(dir, "spawn-error.json");
         return {
             stdio: ["ignore", "inherit", "inherit"],
             stderrTail: () => "",
-            dispose: () => { },
+            timeoutMarker,
+            errorMarker,
+            timedOut: () => existsSync(timeoutMarker),
+            spawnError: () => readSupervisorSpawnError(errorMarker),
+            dispose: () => {
+                try {
+                    rmSync(dir, { recursive: true, force: true });
+                }
+                catch {
+                    // Best-effort cleanup of the supervisor's timeout marker.
+                }
+            },
         };
     }
     const dir = mkdtempSync(path.join(os.tmpdir(), "hq-cli-install-"));
     const errPath = path.join(dir, "stderr.log");
+    const timeoutPath = path.join(dir, "timed-out");
+    const errorPath = path.join(dir, "spawn-error.json");
     const out = openSync(path.join(dir, "stdout.log"), "a");
     const err = openSync(errPath, "a");
     return {
@@ -556,6 +614,10 @@ export function openInstallOutput(verbose, isTty = process.stdout.isTTY === true
                 return "";
             }
         },
+        timeoutMarker: timeoutPath,
+        errorMarker: errorPath,
+        timedOut: () => existsSync(timeoutPath),
+        spawnError: () => readSupervisorSpawnError(errorPath),
         dispose: () => {
             for (const fd of [out, err]) {
                 try {
@@ -574,13 +636,28 @@ export function openInstallOutput(verbose, isTty = process.stdout.isTTY === true
         },
     };
 }
-export function runUpdateCommand(cmd, args, env) {
-    const output = openInstallOutput(true);
+export function runSupervisedUpdateCommand(cmd, args, output, env) {
     try {
         const plan = buildSpawnPlan(cmd, args);
-        const result = spawnSync(plan.cmd, plan.args, inOwnProcessGroup({
+        const timeoutMs = updateTimeoutMs(env);
+        // The outer sync spawn waits only for our supervisor. The supervisor owns
+        // the wall-clock deadline, sends TERM to the updater's whole process group,
+        // waits briefly, sends KILL to survivors, and waits for its direct child so
+        // the completed result leaves no zombie behind.
+        const result = spawnSync(process.execPath, [
+            UPDATE_COMMAND_SUPERVISOR,
+            JSON.stringify({
+                cmd: plan.cmd,
+                args: plan.args,
+                shell: plan.shell,
+                timeoutMs,
+                graceMs: UPDATE_TERMINATE_GRACE_MS,
+                reapMs: UPDATE_REAP_GRACE_MS,
+                timeoutMarker: output.timeoutMarker,
+                errorMarker: output.errorMarker,
+            }),
+        ], inOwnProcessGroup({
             stdio: output.stdio,
-            shell: plan.shell,
             ...(env ? { env } : {}),
         }));
         // spawnSync reports a missing executable via `error`, not a throw.
@@ -588,6 +665,26 @@ export function runUpdateCommand(cmd, args, env) {
             const code = result.error.code;
             return { ok: false, code, detail: result.error.message };
         }
+        if (output.timedOut()) {
+            const command = [cmd, ...args].join(" ");
+            const supervisorError = output.spawnError();
+            const detail = [
+                `timed out after ${timeoutMs}ms: ${command}`,
+                supervisorError?.detail,
+            ]
+                .filter(Boolean)
+                .join("; ");
+            console.error(chalk.red(`✗ Update ${detail}.`));
+            return { ok: false, code: "ETIMEDOUT", detail };
+        }
+        const spawnedError = output.spawnError();
+        if (spawnedError) {
+            return {
+                ok: false,
+                code: spawnedError.code,
+                detail: spawnedError.detail ?? "failed to start updater",
+            };
+        }
         if (result.status !== 0) {
             // When output went to a file rather than the user's terminal, its tail is
             // the only explanation anyone will ever see for this failure.
@@ -606,6 +703,12 @@ export function runUpdateCommand(cmd, args, env) {
             detail: err instanceof Error ? err.message : String(err),
         };
     }
+}
+export function runUpdateCommand(cmd, args, env) {
+    const output = openInstallOutput(true);
+    try {
+        return runSupervisedUpdateCommand(cmd, args, output, env);
+    }
     finally {
         output.dispose();
     }
@@ -796,6 +899,9 @@ export function checkUpdateConvergence(targetVersion, deps = {}) {
  * Exit codes:
  *   0 — update succeeded; user must rerun their command
  *   75 — update failed (EX_TEMPFAIL; common for sudo/EACCES on system npm)
+ *
+ * A timed-out updater is the exception: it has been forcibly reaped, so the
+ * gate returns and lets the user's command run on the current version.
  */
 function enforceUpdateRequired(decision, deps = {}) {
     const banner = chalk.red.bold(`✗ hq-cli ${decision.currentVersion} is below the minimum required version (${decision.minVersion}).`);
@@ -858,6 +964,8 @@ function enforceUpdateRequired(decision, deps = {}) {
         // unexpected throw from the install attempt.
         lock.release();
     }
+    if (exitCode === "continue")
+        return;
     process.exit(exitCode);
 }
 /**
@@ -923,7 +1031,7 @@ function attemptRequiredUpdate(decision, deps, install) {
     // 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) {
+    if (!result.ok && result.code !== "ETIMEDOUT" && prefix) {
         const cleaner = deps.cleanStale ?? cleanStalePartialInstall;
         const cleaned = cleaner(prefix);
         if (cleaned.length > 0) {
@@ -943,7 +1051,7 @@ function attemptRequiredUpdate(decision, deps, install) {
     // Never for pnpm or Bun: elevation changes the package manager's global home,
     // leaving the user's shim untouched while reporting success. A failed
     // non-npm update must surface instead.
-    if (!result.ok && primaryCmd && !isManagedOutsideNpm) {
+    if (!result.ok && result.code !== "ETIMEDOUT" && primaryCmd && !isManagedOutsideNpm) {
         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)
@@ -973,6 +1081,15 @@ function attemptRequiredUpdate(decision, deps, install) {
         if (isManagedOutsideNpm && 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.)`));
         }
+        // The self-update is allowed to fail, but a deadline expiry must not turn
+        // into a second, indefinite denial of the user's command. The supervisor
+        // either reaped the group or recorded why the OS denied that signal; in
+        // neither case did an update land. Continue on the current CLI rather than
+        // pretending it did or aborting the command that caused the gate to run.
+        if (result.code === "ETIMEDOUT") {
+            console.error(chalk.dim("  Continuing on the current hq-cli version."));
+            return "continue";
+        }
         return 75;
     }
     // Read-your-writes: a "successful" install into the npm prefix does not
@@ -1028,6 +1145,7 @@ export function shouldSkipGate(argv) {
 export const __test__ = {
     CLIENT_ID,
     CONVERGENCE_TIMEOUT_MS,
+    DEFAULT_UPDATE_TIMEOUT_MS,
     ENDPOINT_PATH,
     FETCH_TIMEOUT_MS,
     checkUpdateConvergence,
@@ -1058,5 +1176,6 @@ export const __test__ = {
     resolveRunningInstall,
     resolveRunningManager,
     resolveRunningPrefix,
+    updateTimeoutMs,
 };
 //# sourceMappingURL=version-gate.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.115.6",
+  "version": "5.116.0",
   "description": "HQ by Indigo management CLI \u2014 modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -34,7 +34,7 @@
   "dependencies": {
     "@aws-sdk/client-iot-data-plane": "^3.1096.0",
     "@aws-sdk/client-s3": "^3.1049.0",
-    "@indigoai-us/hq-cloud": "~6.16.41",
+    "@indigoai-us/hq-cloud": "~6.16.48",
     "@indigoai-us/hq-flags-client": "^0.1.2",
     "@sentry/node": "^10.49.0",
     "@tobilu/qmd": "2.5.3",