@indigoai-us/hq-cli 5.25.0 → 5.25.1

package/src/utils/version-gate.ts

@@ -0,0 +1,219 @@
+/**
+ * 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 chalk from "chalk";
+import { 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;
+
+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";
+}
+
+/**
+ * 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.
+ */
+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);
+  try {
+    const result = spawnSync(cmd, args, { stdio: "inherit" });
+    if (result.status !== 0) {
+      return {
+        ok: false,
+        detail: `exit ${result.status ?? "signal"}`,
+      };
+    }
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, detail: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+/**
+ * Soft notify when the server says we're below `latestVersion` but still ≥
+ * `minVersion`. Single chalk-yellow line on stderr; never blocks.
+ */
+function nudgeUpdateRecommended(decision: VersionCheckResponse): 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}`));
+  }
+}
+
+/**
+ * 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): 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;
+  if (!command) {
+    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);
+  }
+
+  console.error(chalk.dim(`  Running: ${command}`));
+  const result = performUpdate(command);
+  if (!result.ok) {
+    console.error(
+      chalk.red(`✗ Update failed${result.detail ? `: ${result.detail}` : ""}.`),
+    );
+    console.error(chalk.dim(`  Try manually: ${command}`));
+    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) {
+    enforceUpdateRequired(decision); // exits process
+  }
+  if (decision.updateRecommended) {
+    nudgeUpdateRecommended(decision);
+  }
+}
+
+/**
+ * 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,
+  performUpdate,
+};

package/dist/utils/hq-root.d.ts

@@ -1,10 +0,0 @@
-/**
- * HQ root detection — walks up from cwd looking for HQ markers (US-004)
- */
-/**
- * Find the HQ root directory by walking up from cwd.
- * Looks for CLAUDE.md or .claude/ directory as markers.
- * Throws if not found.
- */
-export declare function findHqRoot(): string;
-//# sourceMappingURL=hq-root.d.ts.map

package/dist/utils/hq-root.js

@@ -1,25 +0,0 @@
-/**
- * HQ root detection — walks up from cwd looking for HQ markers (US-004)
- */
-
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="aebb967b-5f70-5107-9d81-bb495be1c405")}catch(e){}}();
-import * as fs from 'fs';
-import * as path from 'path';
-/**
- * Find the HQ root directory by walking up from cwd.
- * Looks for CLAUDE.md or .claude/ directory as markers.
- * Throws if not found.
- */
-export function findHqRoot() {
-    let dir = process.cwd();
-    while (dir !== path.dirname(dir)) {
-        if (fs.existsSync(path.join(dir, 'CLAUDE.md')) ||
-            fs.existsSync(path.join(dir, '.claude'))) {
-            return dir;
-        }
-        dir = path.dirname(dir);
-    }
-    throw new Error('Could not find HQ root. Run this command from within your HQ directory.');
-}
-//# sourceMappingURL=hq-root.js.map
-//# debugId=aebb967b-5f70-5107-9d81-bb495be1c405

package/src/utils/hq-root.ts

@@ -1,27 +0,0 @@
-/**
- * HQ root detection — walks up from cwd looking for HQ markers (US-004)
- */
-
-import * as fs from 'fs';
-import * as path from 'path';
-
-/**
- * Find the HQ root directory by walking up from cwd.
- * Looks for CLAUDE.md or .claude/ directory as markers.
- * Throws if not found.
- */
-export function findHqRoot(): string {
-  let dir = process.cwd();
-  while (dir !== path.dirname(dir)) {
-    if (
-      fs.existsSync(path.join(dir, 'CLAUDE.md')) ||
-      fs.existsSync(path.join(dir, '.claude'))
-    ) {
-      return dir;
-    }
-    dir = path.dirname(dir);
-  }
-  throw new Error(
-    'Could not find HQ root. Run this command from within your HQ directory.'
-  );
-}