@indigoai-us/hq-cli 5.25.0 → 5.25.1

package/.github/workflows/publish.yml

@@ -80,9 +80,29 @@ jobs:
             echo "published=true" >> "$GITHUB_OUTPUT"
           fi
 
+      # Sentry sourcemap upload runs on every tag push regardless of whether
+      # this run was the one that actually published to npm. The previous
+      # `if: steps.publish.outputs.published == 'true'` gate made re-runs
+      # useless when only the Sentry upload failed — the publish step's
+      # short-circuit (`npm view @ver already published`) zeroed out the
+      # output, so the upload step was skipped on every re-run. dist/ is
+      # rebuilt by the Build + Inject steps each run, so the upload is
+      # always operating on fresh, debug-id-stamped artifacts.
       - name: Upload sourcemaps to Sentry
-        if: steps.publish.outputs.published == 'true'
         run: |
+          # Defang paste-time whitespace in SENTRY_AUTH_TOKEN. Sentry's
+          # auth-header parser returns HTTP 401 "Token string should not
+          # contain spaces" when the secret has a trailing \n or any
+          # embedded whitespace — observed on the v5.25.0 release after a
+          # copy-paste into the GH repo secret carried a literal \n. `tr -d`
+          # is the cheap structural guard so the workflow doesn't blow up
+          # on the next dirty paste.
+          SENTRY_AUTH_TOKEN=$(printf %s "$SENTRY_AUTH_TOKEN" | tr -d '[:space:]')
+          if [ -z "$SENTRY_AUTH_TOKEN" ]; then
+            echo "::error::SENTRY_AUTH_TOKEN secret is empty (or all whitespace) after sanitization — cannot upload sourcemaps"
+            exit 1
+          fi
+          export SENTRY_AUTH_TOKEN
           VER=$(jq -r .version package.json)
           npx -y @sentry/cli@^2 sourcemaps upload --release "hq-cli@$VER" dist/
         env:

package/dist/commands/pkg-install.js

@@ -13,7 +13,7 @@
  * 9. Print next-step message
  */
 
-!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]="874fe8a4-2348-5f03-8600-c545cac13fc9")}catch(e){}}();
+!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]="c6ab4668-f147-5612-bbfc-e1e80b2f018a")}catch(e){}}();
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
@@ -21,7 +21,7 @@ import * as yaml from 'js-yaml';
 import { execSync } from 'child_process';
 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, } from '../utils/registry-client.js';
 import { verifySha256, verifyRsaSignature } from '../utils/integrity.js';
 import { addToRegistry } from '../utils/registry.js';
@@ -93,7 +93,7 @@ async function installPackage(slug, company) {
             }
         }
         // 7. Extract
-        const hqRoot = findHqRoot();
+        const hqRoot = resolveDefaultHqRoot({ onMissing: 'throw' });
         const installDir = path.resolve(hqRoot, 'packages', 'installed', slug);
         // Clean existing installation
         if (fs.existsSync(installDir)) {
@@ -156,4 +156,4 @@ async function installPackage(slug, company) {
     }
 }
 //# sourceMappingURL=pkg-install.js.map
-//# debugId=874fe8a4-2348-5f03-8600-c545cac13fc9
+//# debugId=c6ab4668-f147-5612-bbfc-e1e80b2f018a

package/dist/commands/pkg-list.js

@@ -4,9 +4,9 @@
  * Graceful offline: if registry is unreachable, show cached data with a note.
  */
 
-!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]="ce4886ce-109a-5ace-b8d9-4e5bed61978a")}catch(e){}}();
+!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]="2ca922cd-1115-5059-850d-3927226eb9ee")}catch(e){}}();
 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 { getRegistryUrl, RegistryClient, } from '../utils/registry-client.js';
@@ -26,7 +26,7 @@ export function registerPackageListCommand(parent) {
     });
 }
 async function listPackages() {
-    const hqRoot = findHqRoot();
+    const hqRoot = resolveDefaultHqRoot({ onMissing: 'throw' });
     const installed = readRegistry(hqRoot);
     // Print installed packages
     if (installed.length > 0) {
@@ -70,4 +70,4 @@ async function listPackages() {
     }
 }
 //# sourceMappingURL=pkg-list.js.map
-//# debugId=ce4886ce-109a-5ace-b8d9-4e5bed61978a
+//# debugId=2ca922cd-1115-5059-850d-3927226eb9ee

package/dist/commands/pkg-remove.js

@@ -6,11 +6,11 @@
  * 3. Print next-step message
  */
 
-!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]="b54529d6-de12-595e-b1c7-ab50b9f22eb5")}catch(e){}}();
+!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]="e44da498-3e38-5643-b124-49aa2e91f42b")}catch(e){}}();
 import * as fs from 'fs';
 import * as path from 'path';
 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) {
     parent
@@ -27,7 +27,7 @@ export function registerPackageRemoveCommand(parent) {
     });
 }
 async function removePackage(slug) {
-    const hqRoot = findHqRoot();
+    const hqRoot = resolveDefaultHqRoot({ onMissing: 'throw' });
     const installDir = path.resolve(hqRoot, 'packages', 'installed', slug);
     // Verify it is actually installed
     const entries = readRegistry(hqRoot);
@@ -53,4 +53,4 @@ async function removePackage(slug) {
     console.log(chalk.cyan('Run /package-remove ' + slug + ' in Claude to clean up merged content.'));
 }
 //# sourceMappingURL=pkg-remove.js.map
-//# debugId=b54529d6-de12-595e-b1c7-ab50b9f22eb5
+//# debugId=e44da498-3e38-5643-b124-49aa2e91f42b

package/dist/commands/pkg-update.js

@@ -5,7 +5,7 @@
  * If slug given: update only that package.
  */
 
-!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]="3ef2968d-eb65-594b-a506-4314b70dd3dc")}catch(e){}}();
+!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]="35fae6a0-f8e1-5fde-90d8-34ae4adb3c1c")}catch(e){}}();
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
@@ -13,7 +13,7 @@ import * as yaml from 'js-yaml';
 import { execSync } from 'child_process';
 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, } from '../utils/registry-client.js';
 import { verifySha256, verifyRsaSignature } from '../utils/integrity.js';
 import { readRegistry, addToRegistry, } from '../utils/registry.js';
@@ -32,7 +32,7 @@ export function registerPackageUpdateCommand(parent) {
     });
 }
 async function updatePackages(slug) {
-    const hqRoot = findHqRoot();
+    const hqRoot = resolveDefaultHqRoot({ onMissing: 'throw' });
     const entries = readRegistry(hqRoot);
     if (entries.length === 0) {
         console.log('No packages installed. Use "hq packages install <slug>" to install one.');
@@ -124,4 +124,4 @@ async function updatePackages(slug) {
     console.log(`\n${updatedCount} package(s) updated${updatedCount > 0 ? '.' : ' — everything is current.'}`);
 }
 //# sourceMappingURL=pkg-update.js.map
-//# debugId=3ef2968d-eb65-594b-a506-4314b70dd3dc
+//# debugId=35fae6a0-f8e1-5fde-90d8-34ae4adb3c1c

package/dist/commands/team-sync.js

@@ -10,13 +10,13 @@
  * 6. Gracefully handle conflicts (warn, don't force overwrite)
  */
 
-!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]="4c9a650e-05ed-5e33-b5de-b6d521ecdf4f")}catch(e){}}();
+!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]="2b2504c1-06d5-59f8-a9b3-41d1af7f745f")}catch(e){}}();
 import * as fs from 'fs';
 import * as path from 'path';
 import { execSync } from 'child_process';
 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';
 // ─── API helpers ────────────────────────────────────────────────────────────
 const API_BASE = 'https://example.com/api';
@@ -308,7 +308,7 @@ export function registerTeamSyncCommand(program) {
         .option('--dry-run', 'Show what would be synced without making changes')
         .action(async (options) => {
         try {
-            const hqRoot = findHqRoot();
+            const hqRoot = resolveDefaultHqRoot({ onMissing: 'throw' });
             // 1. Discover team directories
             let teamDirs = discoverTeamDirs(hqRoot);
             if (teamDirs.length === 0) {
@@ -422,4 +422,4 @@ export function registerTeamSyncCommand(program) {
     });
 }
 //# sourceMappingURL=team-sync.js.map
-//# debugId=4c9a650e-05ed-5e33-b5de-b6d521ecdf4f
+//# debugId=2b2504c1-06d5-59f8-a9b3-41d1af7f745f

package/dist/index.js

@@ -3,7 +3,7 @@
  * HQ CLI - Module management, package management, and cloud sync for HQ
  */
 
-!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]="a9b69c08-39a6-58c3-a4b6-a309d0ab8254")}catch(e){}}();
+!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]="0ed956d3-5fde-54aa-96cb-1859a15f7723")}catch(e){}}();
 import { Command } from "commander";
 import { initSentry, Sentry } from "./sentry.js";
 import { registerAddCommand } from "./commands/add.js";
@@ -37,6 +37,7 @@ import { registerSourcesCommand } from "./commands/sources.js";
 import { registerSignalsCommand } from "./commands/signals.js";
 import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
 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.
 const onPipeError = (err) => {
@@ -126,6 +127,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) {
@@ -137,4 +146,4 @@ registerSignalsCommand(program);
     }
 })();
 //# sourceMappingURL=index.js.map
-//# debugId=a9b69c08-39a6-58c3-a4b6-a309d0ab8254
+//# debugId=0ed956d3-5fde-54aa-96cb-1859a15f7723

package/dist/utils/cognito-session.d.ts

@@ -45,7 +45,28 @@ export declare const DEFAULT_VAULT_API_URL: string;
  * 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 declare 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 declare function resolveDefaultHqRoot(opts?: {
+    onMissing?: "throw" | "fallback";
+}): string;
 export declare const DEFAULT_HQ_ROOT: string;
 /**
  * Return a non-expired Cognito access token, refreshing or browser-logging-in

package/dist/utils/cognito-session.js

@@ -19,7 +19,7 @@
  *   HQ_VAULT_API_URL           — vault-service API Gateway URL
  */
 
-!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]="d16ef3c7-eead-5307-aaa7-ca5fc828102b")}catch(e){}}();
+!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]="cd9690e0-c7b0-5e26-a3ee-7f7bc98a0fe2")}catch(e){}}();
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
@@ -67,7 +67,26 @@ export const DEFAULT_VAULT_API_URL = process.env.HQ_VAULT_API_URL ?? "https://hq
  * 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() {
+/**
+ * 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 = {}) {
     if (process.env.HQ_ROOT)
         return path.resolve(process.env.HQ_ROOT);
     let cur = path.resolve(process.cwd());
@@ -76,6 +95,10 @@ export function resolveDefaultHqRoot() {
             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");
 }
 /** True iff `dir` looks like an HQ root (has core.yaml + companies/ dir). */
@@ -170,4 +193,4 @@ export async function refreshCachedSession() {
     }
 }
 //# sourceMappingURL=cognito-session.js.map
-//# debugId=d16ef3c7-eead-5307-aaa7-ca5fc828102b
+//# debugId=cd9690e0-c7b0-5e26-a3ee-7f7bc98a0fe2

package/dist/utils/integrity.js

@@ -2,11 +2,11 @@
  * Integrity verification — SHA256 hash and RSA signature checks (US-005)
  */
 
-!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]="19765c32-6c3d-5477-bf80-0f7d08197d29")}catch(e){}}();
+!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]="820f12b3-4caf-5f08-9add-621628715744")}catch(e){}}();
 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.
  */
@@ -29,7 +29,7 @@ export async function verifySha256(filePath, expectedHash) {
  */
 export function verifyRsaSignature(sha256Hash, signature, publicKeyPath) {
     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;
     }
@@ -40,4 +40,4 @@ export function verifyRsaSignature(sha256Hash, signature, publicKeyPath) {
     return verifier.verify(publicKey, Buffer.from(signature, 'base64'));
 }
 //# sourceMappingURL=integrity.js.map
-//# debugId=19765c32-6c3d-5477-bf80-0f7d08197d29
+//# debugId=820f12b3-4caf-5f08-9add-621628715744

package/dist/utils/registry-client.js

@@ -5,11 +5,11 @@
  * Auth tokens are NEVER written to stdout or logs.
  */
 
-!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]="ffe2dc58-fb20-5566-a56c-1b1c26999bba")}catch(e){}}();
+!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]="43d1600f-1bf7-5a52-819b-83e71ba30c73")}catch(e){}}();
 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';
 // ---------------------------------------------------------------------------
 // URL helper (unchanged from US-004)
 // ---------------------------------------------------------------------------
@@ -19,7 +19,7 @@ import { findHqRoot } from './hq-root.js';
  * Throws if sources.yaml is missing or has no sources.
  */
 export function getRegistryUrl() {
-    const hqRoot = findHqRoot();
+    const hqRoot = resolveDefaultHqRoot({ onMissing: 'throw' });
     const sourcesPath = path.join(hqRoot, 'packages', 'sources.yaml');
     if (!fs.existsSync(sourcesPath)) {
         throw new Error(`No packages/sources.yaml found at ${sourcesPath}. Is your HQ packages directory set up?`);
@@ -102,4 +102,4 @@ export class RegistryClient {
     }
 }
 //# sourceMappingURL=registry-client.js.map
-//# debugId=ffe2dc58-fb20-5566-a56c-1b1c26999bba
+//# debugId=43d1600f-1bf7-5a52-819b-83e71ba30c73

package/dist/utils/version-gate.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 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).
+ */
+/**
+ * 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.
+ */
+declare function performUpdate(command: string): {
+    ok: boolean;
+    detail?: string;
+};
+/**
+ * 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 declare function enforceVersionGate(): Promise<void>;
+/**
+ * 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 declare function shouldSkipGate(argv: readonly string[]): boolean;
+export declare const __test__: {
+    CLIENT_ID: string;
+    ENDPOINT_PATH: string;
+    FETCH_TIMEOUT_MS: number;
+    performUpdate: typeof performUpdate;
+};
+export {};
+//# sourceMappingURL=version-gate.d.ts.map

package/dist/utils/version-gate.js

@@ -0,0 +1,185 @@
+/**
+ * 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).
+ */
+
+!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]="d7d58261-f0e4-56bc-b6eb-4117731744f9")}catch(e){}}();
+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;
+function isOptedOut() {
+    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() {
+    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());
+        if (typeof body.minVersion !== "string" ||
+            typeof body.latestVersion !== "string" ||
+            typeof body.updateRequired !== "boolean") {
+            return null;
+        }
+        return body;
+    }
+    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) {
+    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) {
+    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) {
+    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() {
+    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) {
+    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,
+};
+//# sourceMappingURL=version-gate.js.map
+//# debugId=d7d58261-f0e4-56bc-b6eb-4117731744f9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.25.0",
+  "version": "5.25.1",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {

package/src/commands/pkg-install.ts

@@ -21,7 +21,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,
@@ -124,7 +124,7 @@ async function installPackage(
     }
 
     // 7. Extract
-    const hqRoot = findHqRoot();
+    const hqRoot = resolveDefaultHqRoot({ onMissing: 'throw' });
     const installDir = path.resolve(hqRoot, 'packages', 'installed', slug);
 
     // Clean existing installation