@indigoai-us/hq-cli 5.24.0 → 5.25.1

package/src/utils/registry-client.ts

@@ -8,7 +8,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'js-yaml';
-import { findHqRoot } from './hq-root.js';
+import { resolveDefaultHqRoot } from './cognito-session.js';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -76,7 +76,7 @@ export interface DownloadResponse {
  * Throws if sources.yaml is missing or has no sources.
  */
 export function getRegistryUrl(): string {
-  const hqRoot = findHqRoot();
+  const hqRoot = resolveDefaultHqRoot({ onMissing: 'throw' });
   const sourcesPath = path.join(hqRoot, 'packages', 'sources.yaml');
 
   if (!fs.existsSync(sourcesPath)) {

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

@@ -0,0 +1,245 @@
+/**
+ * Tests for the version-gate module. Hermetic — no network, no spawn.
+ *
+ * Pinning CLI_VERSION via the same mock pattern used by version-check.test.ts
+ * (`vi.mock('../cli-version.js', …)`) so the gate request body is
+ * deterministic.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("../cli-version.js", () => ({
+  CLI_VERSION: "5.10.0",
+  CLI_NAME: "@indigoai-us/hq-cli",
+}));
+
+beforeEach(() => {
+  vi.unstubAllEnvs();
+  vi.restoreAllMocks();
+});
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+  vi.restoreAllMocks();
+});
+
+async function loadModule() {
+  vi.resetModules();
+  return await import("./version-gate.js");
+}
+
+describe("shouldSkipGate", () => {
+  it("returns true for --version", async () => {
+    const { shouldSkipGate } = await loadModule();
+    expect(shouldSkipGate(["node", "hq", "--version"])).toBe(true);
+  });
+
+  it("returns true for -V, -v, --help, -h", async () => {
+    const { shouldSkipGate } = await loadModule();
+    expect(shouldSkipGate(["node", "hq", "-V"])).toBe(true);
+    expect(shouldSkipGate(["node", "hq", "-v"])).toBe(true);
+    expect(shouldSkipGate(["node", "hq", "--help"])).toBe(true);
+    expect(shouldSkipGate(["node", "hq", "-h"])).toBe(true);
+  });
+
+  it("returns false for a regular subcommand", async () => {
+    const { shouldSkipGate } = await loadModule();
+    expect(shouldSkipGate(["node", "hq", "sync"])).toBe(false);
+    expect(shouldSkipGate(["node", "hq", "members", "list"])).toBe(false);
+  });
+});
+
+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");
+    const fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+    const { enforceVersionGate } = await loadModule();
+    await enforceVersionGate();
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("is silent on non-200 response (treats as no-gate)", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue(
+        new Response("", { status: 500 }),
+      ),
+    );
+    // process.exit must HALT execution — mocking it as undefined lets code
+    // fall through past the exit point and crash on later lines. Throwing a
+    // sentinel error reproduces the "never returns" semantics in unit tests.
+    const exitSpy = vi
+      .spyOn(process, "exit")
+      .mockImplementation(((code?: number) => {
+        throw new Error(`__process_exit__:${code ?? 0}`);
+      }) as never);
+    const { enforceVersionGate } = await loadModule();
+    await enforceVersionGate();
+    expect(exitSpy).not.toHaveBeenCalled();
+  });
+
+  it("is silent on malformed response body", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue(
+        new Response(JSON.stringify({ ok: true }), { status: 200 }),
+      ),
+    );
+    // process.exit must HALT execution — mocking it as undefined lets code
+    // fall through past the exit point and crash on later lines. Throwing a
+    // sentinel error reproduces the "never returns" semantics in unit tests.
+    const exitSpy = vi
+      .spyOn(process, "exit")
+      .mockImplementation(((code?: number) => {
+        throw new Error(`__process_exit__:${code ?? 0}`);
+      }) as never);
+    const { enforceVersionGate } = await loadModule();
+    await enforceVersionGate();
+    expect(exitSpy).not.toHaveBeenCalled();
+  });
+
+  it("is silent on fetch rejection (network down / timeout)", async () => {
+    vi.stubGlobal("fetch", vi.fn().mockRejectedValue(new Error("network down")));
+    // process.exit must HALT execution — mocking it as undefined lets code
+    // fall through past the exit point and crash on later lines. Throwing a
+    // sentinel error reproduces the "never returns" semantics in unit tests.
+    const exitSpy = vi
+      .spyOn(process, "exit")
+      .mockImplementation(((code?: number) => {
+        throw new Error(`__process_exit__:${code ?? 0}`);
+      }) as never);
+    const { enforceVersionGate } = await loadModule();
+    await expect(enforceVersionGate()).resolves.toBeUndefined();
+    expect(exitSpy).not.toHaveBeenCalled();
+  });
+
+  it("nudges on updateRecommended without exiting", async () => {
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    // process.exit must HALT execution — mocking it as undefined lets code
+    // fall through past the exit point and crash on later lines. Throwing a
+    // sentinel error reproduces the "never returns" semantics in unit tests.
+    const exitSpy = vi
+      .spyOn(process, "exit")
+      .mockImplementation(((code?: number) => {
+        throw new Error(`__process_exit__:${code ?? 0}`);
+      }) as never);
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue(
+        new Response(
+          JSON.stringify({
+            clientId: "hq-cli",
+            currentVersion: "5.10.0",
+            minVersion: "5.0.0",
+            latestVersion: "5.24.0",
+            updateRequired: false,
+            updateRecommended: true,
+            updateCommand: "npm install -g @indigoai-us/hq-cli@latest",
+          }),
+          { status: 200 },
+        ),
+      ),
+    );
+    const { enforceVersionGate } = await loadModule();
+    await enforceVersionGate();
+    expect(exitSpy).not.toHaveBeenCalled();
+    const printed = errSpy.mock.calls.map((c) => c.join(" ")).join("\n");
+    expect(printed).toContain("5.24.0");
+  });
+
+  it("does NOT nudge or block when current = latest", async () => {
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    // process.exit must HALT execution — mocking it as undefined lets code
+    // fall through past the exit point and crash on later lines. Throwing a
+    // sentinel error reproduces the "never returns" semantics in unit tests.
+    const exitSpy = vi
+      .spyOn(process, "exit")
+      .mockImplementation(((code?: number) => {
+        throw new Error(`__process_exit__:${code ?? 0}`);
+      }) as never);
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue(
+        new Response(
+          JSON.stringify({
+            clientId: "hq-cli",
+            currentVersion: "5.10.0",
+            minVersion: "5.0.0",
+            latestVersion: "5.10.0",
+            updateRequired: false,
+            updateRecommended: false,
+          }),
+          { status: 200 },
+        ),
+      ),
+    );
+    const { enforceVersionGate } = await loadModule();
+    await enforceVersionGate();
+    expect(exitSpy).not.toHaveBeenCalled();
+    expect(errSpy).not.toHaveBeenCalled();
+  });
+});
+
+describe("enforceVersionGate — hard-update path", () => {
+  it("calls process.exit when updateRequired is true and no updateCommand", async () => {
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    // process.exit must HALT execution — mocking it as undefined lets code
+    // fall through past the exit point and crash on later lines. Throwing a
+    // sentinel error reproduces the "never returns" semantics in unit tests.
+    const exitSpy = vi
+      .spyOn(process, "exit")
+      .mockImplementation(((code?: number) => {
+        throw new Error(`__process_exit__:${code ?? 0}`);
+      }) as never);
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue(
+        new Response(
+          JSON.stringify({
+            clientId: "hq-cli",
+            currentVersion: "5.10.0",
+            minVersion: "5.20.0",
+            latestVersion: "5.24.0",
+            updateRequired: true,
+            updateRecommended: false,
+            // no updateCommand — exits with code 75 (manual update needed)
+          }),
+          { status: 200 },
+        ),
+      ),
+    );
+    const { enforceVersionGate } = await loadModule();
+    await expect(enforceVersionGate()).rejects.toThrow(/__process_exit__:75/);
+    expect(exitSpy).toHaveBeenCalledWith(75);
+    const printed = errSpy.mock.calls.map((c) => c.join(" ")).join("\n");
+    expect(printed).toContain("below the minimum");
+  });
+
+  it("posts the expected request body to /v1/client-version/check", async () => {
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          clientId: "hq-cli",
+          currentVersion: "5.10.0",
+          minVersion: "5.0.0",
+          latestVersion: "5.10.0",
+          updateRequired: false,
+          updateRecommended: false,
+        }),
+        { status: 200 },
+      ),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+    const { enforceVersionGate } = await loadModule();
+    await enforceVersionGate();
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchMock.mock.calls[0]!;
+    expect(String(url)).toContain("/v1/client-version/check");
+    const body = JSON.parse((init as RequestInit).body as string);
+    expect(body.clientId).toBe("hq-cli");
+    expect(body.currentVersion).toBe("5.10.0");
+    expect(typeof body.platform).toBe("string");
+  });
+});

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.'
-  );
-}