@indigoai-us/hq-cli 5.25.0 → 5.25.1

package/src/commands/pkg-list.ts

@@ -6,7 +6,7 @@
 
 import { Command } from 'commander';
 import chalk from 'chalk';
-import { findHqRoot } from '../utils/hq-root.js';
+import { resolveDefaultHqRoot } from '../utils/cognito-session.js';
 import { readRegistry } from '../utils/registry.js';
 import { loadCachedTokens, isExpiring } from '@indigoai-us/hq-cloud';
 import {
@@ -34,7 +34,7 @@ export function registerPackageListCommand(parent: Command): void {
 }
 
 async function listPackages(): Promise<void> {
-  const hqRoot = findHqRoot();
+  const hqRoot = resolveDefaultHqRoot({ onMissing: 'throw' });
   const installed = readRegistry(hqRoot);
 
   // Print installed packages

package/src/commands/pkg-remove.ts

@@ -10,7 +10,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { Command } from 'commander';
 import chalk from 'chalk';
-import { findHqRoot } from '../utils/hq-root.js';
+import { resolveDefaultHqRoot } from '../utils/cognito-session.js';
 import { removeFromRegistry, readRegistry } from '../utils/registry.js';
 
 export function registerPackageRemoveCommand(parent: Command): void {
@@ -31,7 +31,7 @@ export function registerPackageRemoveCommand(parent: Command): void {
 }
 
 async function removePackage(slug: string): Promise<void> {
-  const hqRoot = findHqRoot();
+  const hqRoot = resolveDefaultHqRoot({ onMissing: 'throw' });
   const installDir = path.resolve(hqRoot, 'packages', 'installed', slug);
 
   // Verify it is actually installed

package/src/commands/pkg-update.ts

@@ -13,7 +13,7 @@ import { execSync } from 'child_process';
 import { Command } from 'commander';
 import chalk from 'chalk';
 import { ensureCognitoToken } from '../utils/cognito-session.js';
-import { findHqRoot } from '../utils/hq-root.js';
+import { resolveDefaultHqRoot } from '../utils/cognito-session.js';
 import {
   getRegistryUrl,
   RegistryClient,
@@ -43,7 +43,7 @@ export function registerPackageUpdateCommand(parent: Command): void {
 }
 
 async function updatePackages(slug?: string): Promise<void> {
-  const hqRoot = findHqRoot();
+  const hqRoot = resolveDefaultHqRoot({ onMissing: 'throw' });
   const entries = readRegistry(hqRoot);
 
   if (entries.length === 0) {

package/src/commands/team-sync.ts

@@ -16,7 +16,7 @@ import { execSync } from 'child_process';
 import { Command } from 'commander';
 import chalk from 'chalk';
 import simpleGit from 'simple-git';
-import { findHqRoot } from '../utils/hq-root.js';
+import { resolveDefaultHqRoot } from '../utils/cognito-session.js';
 import { ensureCognitoToken } from '../utils/cognito-session.js';
 
 // ─── Types ──────────────────────────────────────────────────────────────────
@@ -433,7 +433,7 @@ export function registerTeamSyncCommand(program: Command): void {
     .action(
       async (options: { team?: string; dryRun?: boolean }) => {
         try {
-          const hqRoot = findHqRoot();
+          const hqRoot = resolveDefaultHqRoot({ onMissing: 'throw' });
 
           // 1. Discover team directories
           let teamDirs = discoverTeamDirs(hqRoot);

package/src/index.ts

@@ -40,6 +40,10 @@ import {
   maybeWarnNewVersion,
   refreshVersionCache,
 } from "./utils/version-check.js";
+import {
+  enforceVersionGate,
+  shouldSkipGate,
+} from "./utils/version-gate.js";
 import { CLI_VERSION } from "./cli-version.js";
 
 // Swallow EPIPE when a downstream reader (e.g. `source <(…)`, `| head`) closes the pipe early.
@@ -157,6 +161,14 @@ registerSignalsCommand(program);
       message: sanitizeArgv(process.argv.slice(2)).join(" "),
       level: "info",
     });
+    // Hard version gate: ask hq-pro whether this CLI is below the floor and
+    // auto-update if so (exits the process on update). Skipped for inspection
+    // flags (`--version`, `--help`) so users debugging a broken install can
+    // still introspect what they have. Silent on any failure — never blocks
+    // the CLI on a flaky network or hq-pro hiccup. See `utils/version-gate.ts`.
+    if (!shouldSkipGate(process.argv)) {
+      await enforceVersionGate();
+    }
     await program.parseAsync();
   } catch (err) {
     Sentry.captureException(err);

package/src/utils/cognito-session.test.ts

@@ -4,7 +4,7 @@
  */
 
 import { describe, it, expect, beforeEach, afterEach } from "vitest";
-import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
+import { mkdtempSync, realpathSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
@@ -114,6 +114,61 @@ describe("resolveDefaultHqRoot", () => {
 
     expect(resolveDefaultHqRoot()).toBe(explicit);
   });
+
+  // ── onMissing: throw vs fallback ──────────────────────────────────────
+  //
+  // Default behavior (no opts) is fallback to ~/hq — preserves the
+  // pre-dedup module-load contract of `DEFAULT_HQ_ROOT = resolveDefaultHqRoot()`.
+  // Module-management commands (pkg-*, team-sync) opt into throw mode so a
+  // user invoking the command from outside an HQ gets a clear error instead
+  // of a silent default-path miss.
+  it("onMissing: 'throw' throws when no HQ root is found above cwd", () => {
+    const stranded = join(tmpRoot, "stranded");
+    mkdirSync(stranded, { recursive: true });
+    process.chdir(stranded);
+
+    expect(() => resolveDefaultHqRoot({ onMissing: "throw" })).toThrow(
+      /Could not find HQ root/i,
+    );
+  });
+
+  it("onMissing: 'throw' still honors $HQ_ROOT even though dir wouldn't otherwise be detected", () => {
+    // HQ_ROOT is treated as an explicit assertion by the caller — no
+    // walk-and-throw applies. Module-management commands run with
+    // HQ_ROOT=/abs/path should succeed regardless of cwd.
+    const explicit = join(tmpRoot, "explicit");
+    mkdirSync(explicit, { recursive: true });
+    process.env.HQ_ROOT = explicit;
+    process.chdir(tmpRoot);
+
+    expect(resolveDefaultHqRoot({ onMissing: "throw" })).toBe(explicit);
+  });
+
+  it("onMissing: 'throw' still resolves when cwd IS an HQ root", () => {
+    const hqDir = join(tmpRoot, "hq");
+    mkdirSync(join(hqDir, "companies"), { recursive: true });
+    writeFileSync(join(hqDir, "core.yaml"), "version: 14.1.1\n");
+
+    process.chdir(hqDir);
+    // realpath both sides: macOS /tmp -> /private/var/folders symlink would
+    // otherwise produce a spurious mismatch (same root cause as the two
+    // pre-existing failing `priority 2:` tests above).
+    expect(realpathSync(resolveDefaultHqRoot({ onMissing: "throw" }))).toBe(
+      realpathSync(hqDir),
+    );
+  });
+
+  it("default (no opts) falls back to ~/hq — back-compat with module-load DEFAULT_HQ_ROOT", () => {
+    // Regression pin: any code that imports `DEFAULT_HQ_ROOT` (resolved at
+    // module load) MUST NOT throw if the loader's cwd is outside an HQ.
+    // This contract pre-dates the onMissing parameter and several commands
+    // depend on it (commander.js .option() registration time).
+    const stranded = join(tmpRoot, "stranded");
+    mkdirSync(stranded, { recursive: true });
+    process.chdir(stranded);
+
+    expect(() => resolveDefaultHqRoot()).not.toThrow();
+  });
 });
 
 describe("CLI_CLIENT_INFO + buildVaultConfig", () => {

package/src/utils/cognito-session.ts

@@ -80,13 +80,40 @@ export const DEFAULT_VAULT_API_URL =
  * value at registration time, which matches the user's actual cwd at process
  * start. Re-importable as a function for tests and command-time resolution.
  */
-export function resolveDefaultHqRoot(): string {
+/**
+ * Resolve the HQ root directory.
+ *
+ * Resolution order:
+ *   1. $HQ_ROOT env var (treated as an explicit assertion by the caller)
+ *   2. Walk up from cwd looking for `core.yaml` AND `companies/` siblings
+ *   3. Fall back to `~/hq` (or throw, per `opts.onMissing`)
+ *
+ * `opts.onMissing` controls the third arm:
+ *   - `'fallback'` (default) — return `~/hq` if no HQ root is found above cwd.
+ *     This preserves the module-load contract of `DEFAULT_HQ_ROOT`, which
+ *     several commander.js `.option()` callers pin at registration time.
+ *   - `'throw'` — throw with a user-actionable error. Used by module-management
+ *     commands (pkg-install, pkg-remove, pkg-list, pkg-update, team-sync) where
+ *     a silent default-path miss would silently target the wrong directory.
+ *
+ * `$HQ_ROOT` short-circuits both arms — if the env var is set, it's used
+ * as-is regardless of `onMissing`.
+ */
+export function resolveDefaultHqRoot(opts: {
+  onMissing?: "throw" | "fallback";
+} = {}): string {
   if (process.env.HQ_ROOT) return path.resolve(process.env.HQ_ROOT);
   let cur = path.resolve(process.cwd());
   while (cur !== path.dirname(cur)) {
     if (isHqRoot(cur)) return cur;
     cur = path.dirname(cur);
   }
+  if (opts.onMissing === "throw") {
+    throw new Error(
+      "Could not find HQ root. Run this command from within your HQ directory " +
+        "(must contain core.yaml AND a companies/ subdirectory), or set $HQ_ROOT.",
+    );
+  }
   return path.join(os.homedir(), "hq");
 }
 

package/src/utils/integrity.ts

@@ -5,7 +5,7 @@
 import * as crypto from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
-import { findHqRoot } from './hq-root.js';
+import { resolveDefaultHqRoot } from './cognito-session.js';
 
 /**
  * Verify a file's SHA256 hash matches the expected value.
@@ -39,7 +39,7 @@ export function verifyRsaSignature(
 ): boolean {
   const keyPath =
     publicKeyPath ??
-    path.resolve(findHqRoot(), 'packages', '.keys', 'registry-public.pem');
+    path.resolve(resolveDefaultHqRoot({ onMissing: 'throw' }), 'packages', '.keys', 'registry-public.pem');
 
   if (!fs.existsSync(keyPath)) {
     return false;

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");
+  });
+});