@indigoai-us/hq-cli 5.119.12 → 5.119.13

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased]
 
+## [5.119.13] — 2026-09-18
+
+### Added
+
+- `hq version` (and `hq --version`) print the installed HQ version, the CLI
+  version labelled as CLI, and the latest hq-core release. If a newer HQ is
+  out it says to run `/update-hq`; if the lookup cannot reach the network it
+  says so instead of going quiet. `hq version --json` prints the same payload.
+
 ## [5.119.12] — 2026-09-18
 
 ### Fixed

package/dist/command-catalog.generated.d.ts

@@ -805,6 +805,18 @@ export declare const COMMAND_CATALOG: readonly [{
         readonly description: "Also report this company's workspace plan state (Starter lock)";
     }];
     readonly subcommands: readonly [];
+}, {
+    readonly name: "version";
+    readonly description: "Show HQ, CLI, and latest hq-core versions";
+    readonly aliases: readonly [];
+    readonly hidden: false;
+    readonly usage: "[options]";
+    readonly arguments: readonly [];
+    readonly options: readonly [{
+        readonly flags: "--json";
+        readonly description: "Output the same payload as JSON";
+    }];
+    readonly subcommands: readonly [];
 }, {
     readonly name: "auth";
     readonly description: "Manage the local HQ Cognito session";

package/dist/command-catalog.generated.js

@@ -1029,6 +1029,21 @@ export const COMMAND_CATALOG = [
         ],
         "subcommands": []
     },
+    {
+        "name": "version",
+        "description": "Show HQ, CLI, and latest hq-core versions",
+        "aliases": [],
+        "hidden": false,
+        "usage": "[options]",
+        "arguments": [],
+        "options": [
+            {
+                "flags": "--json",
+                "description": "Output the same payload as JSON"
+            }
+        ],
+        "subcommands": []
+    },
     {
         "name": "auth",
         "description": "Manage the local HQ Cognito session",

package/dist/command-registration-plan.d.ts

@@ -171,6 +171,12 @@ export declare const REGISTRATION_PLAN: readonly [{
     readonly parent: "program";
     readonly module: "./commands/whoami.js";
     readonly exportName: "registerWhoamiCommand";
+}, {
+    readonly type: "registrar";
+    readonly root: "version";
+    readonly parent: "program";
+    readonly module: "./commands/version.js";
+    readonly exportName: "registerVersionCommand";
 }, {
     readonly type: "registrar";
     readonly root: "auth";

package/dist/command-registration-plan.js

@@ -31,6 +31,7 @@ export const REGISTRATION_PLAN = [
     { type: "registrar", root: "login", parent: "program", module: "./commands/login.js", exportName: "registerLoginCommand" },
     { type: "registrar", root: "logout", parent: "program", module: "./commands/logout.js", exportName: "registerLogoutCommand" },
     { type: "registrar", root: "whoami", parent: "program", module: "./commands/whoami.js", exportName: "registerWhoamiCommand" },
+    { type: "registrar", root: "version", parent: "program", module: "./commands/version.js", exportName: "registerVersionCommand" },
     { type: "registrar", root: "auth", parent: "program", module: "./commands/auth.js", exportName: "registerAuthCommands" },
     { type: "registrar", root: "secrets", parent: "program", module: "./commands/secrets.js", exportName: "registerSecretsCommand" },
     { type: "registrar", root: "db", parent: "program", module: "./commands/db.js", exportName: "registerDbCommand" },

package/dist/commands/version.d.ts

@@ -0,0 +1,10 @@
+/**
+ * hq version — labelled HQ vs CLI vs latest hq-core.
+ *
+ * `hq --version` is intercepted on the fast path in index.ts and prints the
+ * same report. This registrar exists so `hq --help` lists the command and so
+ * `hq version --json` still works if the fast path is skipped.
+ */
+import { Command } from "commander";
+export declare function registerVersionCommand(program: Command): void;
+//# sourceMappingURL=version.d.ts.map

package/dist/commands/version.js

@@ -0,0 +1,11 @@
+import { runVersionCommand } from "../utils/version-report.js";
+export function registerVersionCommand(program) {
+    program
+        .command("version")
+        .description("Show HQ, CLI, and latest hq-core versions")
+        .option("--json", "Output the same payload as JSON")
+        .action(async () => {
+        await runVersionCommand(process.argv);
+    });
+}
+//# sourceMappingURL=version.js.map

package/dist/index.d.ts

@@ -1,11 +1,10 @@
 #!/usr/bin/env node
 import "./node-preflight.js";
 import "./node-network-compat.js";
+import { isVersionRequest } from "./version-request.js";
 import { isFastCoreRequest } from "./commands/scaffold-fast.js";
-declare function isVersionRequest(argv: readonly string[]): boolean;
 export declare const __test__: {
     isVersionRequest: typeof isVersionRequest;
     isFastCoreRequest: typeof isFastCoreRequest;
 };
-export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -3,17 +3,13 @@
 // Node 20+ API (e.g. util.styleText) or a newer native ABI is evaluated.
 import "./node-preflight.js";
 import "./node-network-compat.js";
-import { CLI_VERSION } from "./cli-version.js";
+import { isVersionRequest } from "./version-request.js";
 // Dependency-light: a pure parser + table, no command graph. Safe to load on
 // every path (including --version) without reintroducing the heavy startup.
 import { isFastCoreRequest } from "./commands/scaffold-fast.js";
 // Also dependency-light: registers a process-level rejection boundary; its only
 // heavy import (main.js) is lazy and reached only when a rejection fires.
 import { installProcessRejectionBoundary } from "./unhandled-rejection-boundary.js";
-function isVersionRequest(argv) {
-    const args = argv.slice(2);
-    return args.length === 1 && (args[0] === "--version" || args[0] === "-V" || args[0] === "-v");
-}
 // Install BEFORE any dispatch so a floated rejection on ANY path (the command
 // graph or the fast-core forwarder) becomes a non-zero exit. @sentry/node's
 // onUnhandledRejection integration defaults to 'warn' — it captures but does
@@ -22,7 +18,9 @@ function isVersionRequest(argv) {
 // so runCli's finally still finalizes release health and flushes Sentry.
 installProcessRejectionBoundary();
 if (isVersionRequest(process.argv)) {
-    process.stdout.write(`${CLI_VERSION}\n`);
+    // Same report as `hq version`: HQ, CLI, latest hq-core. Lazy so --version
+    // still skips the command graph.
+    void import("./utils/version-report.js").then(({ runVersionCommand }) => runVersionCommand(process.argv));
 }
 else if (isFastCoreRequest(process.argv)) {
     // Hot relocated plumbing (`hq core hq-session`, `hq core checkpoint-stop-gate`)

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

@@ -347,6 +347,14 @@ declare function nudgeUpdateRecommended(decision: VersionCheckResponse, install?
  * see what the USER's next invocation resolves.
  */
 export declare function resolveHqOnPath(): string | null;
+/**
+ * Pull the CLI version out of `hq --version` output.
+ *
+ * Older builds printed a bare semver. Current builds print a labelled report
+ * (`HQ …` / `CLI 5.119.12` / …). Convergence must accept both, otherwise a
+ * successful install looks like a PATH shadow.
+ */
+export declare function parseReportedCliVersion(stdout: string): string | null;
 /** `<bin> --version` output (trimmed), or null on any failure/timeout. */
 export declare function probeCliVersion(bin: string): string | null;
 /**

package/dist/utils/version-gate.js

@@ -810,6 +810,28 @@ export function resolveHqOnPath() {
         return null;
     }
 }
+/**
+ * Pull the CLI version out of `hq --version` output.
+ *
+ * Older builds printed a bare semver. Current builds print a labelled report
+ * (`HQ …` / `CLI 5.119.12` / …). Convergence must accept both, otherwise a
+ * successful install looks like a PATH shadow.
+ */
+export function parseReportedCliVersion(stdout) {
+    const text = stdout.trim();
+    if (!text)
+        return null;
+    const labelled = /^CLI\s+(\S+)/m.exec(text);
+    if (labelled)
+        return labelled[1];
+    const lines = text
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+    if (lines.length === 1)
+        return lines[0];
+    return null;
+}
 /** `<bin> --version` output (trimmed), or null on any failure/timeout. */
 export function probeCliVersion(bin) {
     try {
@@ -819,8 +841,7 @@ export function probeCliVersion(bin) {
         });
         if (result.error || result.status !== 0)
             return null;
-        const out = (result.stdout ?? "").trim();
-        return out || null;
+        return parseReportedCliVersion(result.stdout ?? "");
     }
     catch {
         return null;
@@ -1140,7 +1161,12 @@ export async function enforceVersionGate(onUpdateRecommended, options = {}) {
  * force-upgraded.
  */
 export function shouldSkipGate(argv) {
-    return argv.some((a) => a === "--version" || a === "-V" || a === "-v" || a === "--help" || a === "-h");
+    return argv.some((a) => a === "--version" ||
+        a === "-V" ||
+        a === "-v" ||
+        a === "--help" ||
+        a === "-h" ||
+        a === "version");
 }
 export const __test__ = {
     CLIENT_ID,

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

@@ -0,0 +1,27 @@
+export declare const HQ_CORE_LATEST_URL = "https://api.github.com/repos/indigoai-us/hq-core/releases/latest";
+export declare const LATEST_FETCH_TIMEOUT_MS = 3000;
+export type LatestLookup = "ok" | "network-error";
+export interface VersionReport {
+    hq: string | null;
+    cli: string;
+    latestHqCore: string | null;
+    updateAvailable: boolean;
+    latestLookup: LatestLookup;
+}
+export interface VersionReportDeps {
+    cliVersion?: string;
+    hqRoot?: string;
+    readHq?: (hqRoot: string) => string | null;
+    fetchLatest?: () => Promise<string | null>;
+}
+export declare function normalizeHqCoreTag(tag: string): string | null;
+export declare function fetchLatestHqCoreRelease(fetchImpl?: typeof fetch, timeoutMs?: number): Promise<string | null>;
+export declare function collectVersionReport(deps?: VersionReportDeps): Promise<VersionReport>;
+export declare function formatVersionReport(report: VersionReport): string;
+export declare function versionReportJson(report: VersionReport): string;
+export { isVersionRequest } from "../version-request.js";
+export declare function wantsJson(argv: readonly string[]): boolean;
+export declare function runVersionCommand(argv?: readonly string[], deps?: VersionReportDeps, stdout?: {
+    write(chunk: string): unknown;
+}): Promise<void>;
+//# sourceMappingURL=version-report.d.ts.map

package/dist/utils/version-report.js

@@ -0,0 +1,97 @@
+/**
+ * The payload behind `hq version` / labelled `hq --version`.
+ *
+ * Prints the installed HQ scaffold version, the CLI version (labelled so it
+ * cannot be confused with HQ), and the latest hq-core GitHub release. A
+ * network failure is an explicit line, never a silent omission.
+ */
+import semver from "semver";
+import { CLI_VERSION } from "../cli-version.js";
+import { findHqRoot } from "./manifest.js";
+import { readHqVersion } from "./pack-contributions.js";
+export const HQ_CORE_LATEST_URL = "https://api.github.com/repos/indigoai-us/hq-core/releases/latest";
+export const LATEST_FETCH_TIMEOUT_MS = 3_000;
+export function normalizeHqCoreTag(tag) {
+    const version = tag.trim().replace(/^v/i, "");
+    return semver.valid(version) ? version : null;
+}
+export async function fetchLatestHqCoreRelease(fetchImpl = fetch, timeoutMs = LATEST_FETCH_TIMEOUT_MS) {
+    try {
+        const res = await fetchImpl(HQ_CORE_LATEST_URL, {
+            headers: {
+                Accept: "application/vnd.github+json",
+                "User-Agent": "hq-cli-version",
+                "X-GitHub-Api-Version": "2022-11-28",
+            },
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        if (typeof body.tag_name !== "string")
+            return null;
+        return normalizeHqCoreTag(body.tag_name);
+    }
+    catch {
+        return null;
+    }
+}
+export async function collectVersionReport(deps = {}) {
+    const cli = deps.cliVersion ?? CLI_VERSION;
+    let hq;
+    try {
+        const hqRoot = deps.hqRoot ?? findHqRoot();
+        hq = (deps.readHq ?? readHqVersion)(hqRoot);
+    }
+    catch {
+        hq = null;
+    }
+    const latestHqCore = deps.fetchLatest
+        ? await deps.fetchLatest()
+        : await fetchLatestHqCoreRelease();
+    const latestLookup = latestHqCore ? "ok" : "network-error";
+    const hqValid = hq ? semver.valid(hq) : null;
+    const latestValid = latestHqCore ? semver.valid(latestHqCore) : null;
+    const updateAvailable = Boolean(hqValid && latestValid && semver.gt(latestValid, hqValid));
+    return { hq, cli, latestHqCore, updateAvailable, latestLookup };
+}
+export function formatVersionReport(report) {
+    const lines = [
+        `HQ ${report.hq ?? "unknown"}`,
+        `CLI ${report.cli}`,
+    ];
+    if (report.latestLookup === "network-error") {
+        lines.push("Latest hq-core unknown");
+        lines.push("could not reach the network to check for a newer HQ");
+        return `${lines.join("\n")}\n`;
+    }
+    lines.push(`Latest hq-core ${report.latestHqCore}`);
+    if (!report.hq) {
+        lines.push("installed HQ version unknown, cannot tell if an update is available");
+    }
+    else if (report.updateAvailable) {
+        lines.push("update available, run /update-hq");
+    }
+    else {
+        lines.push("up to date");
+    }
+    return `${lines.join("\n")}\n`;
+}
+export function versionReportJson(report) {
+    return `${JSON.stringify({
+        hq: report.hq,
+        cli: report.cli,
+        latestHqCore: report.latestHqCore,
+        updateAvailable: report.updateAvailable,
+        latestLookup: report.latestLookup,
+    }, null, 2)}\n`;
+}
+export { isVersionRequest } from "../version-request.js";
+export function wantsJson(argv) {
+    return argv.includes("--json");
+}
+export async function runVersionCommand(argv = process.argv, deps = {}, stdout = process.stdout) {
+    const report = await collectVersionReport(deps);
+    stdout.write(wantsJson(argv) ? versionReportJson(report) : formatVersionReport(report));
+}
+//# sourceMappingURL=version-report.js.map

package/dist/version-request.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Argv predicate for the version fast path. Keep this file dependency-free so
+ * every `hq` invocation can classify `--version` / `version` without loading
+ * yaml, semver, or the command graph.
+ */
+export declare function isVersionRequest(argv: readonly string[]): boolean;
+//# sourceMappingURL=version-request.d.ts.map

package/dist/version-request.js

@@ -0,0 +1,22 @@
+/**
+ * Argv predicate for the version fast path. Keep this file dependency-free so
+ * every `hq` invocation can classify `--version` / `version` without loading
+ * yaml, semver, or the command graph.
+ */
+export function isVersionRequest(argv) {
+    const args = argv.slice(2);
+    if (args.length === 0)
+        return false;
+    if (args.includes("--help") || args.includes("-h"))
+        return false;
+    const positionals = args.filter((a) => !a.startsWith("-"));
+    const flags = args.filter((a) => a.startsWith("-"));
+    const allowedFlags = new Set(["--version", "-V", "-v", "--json"]);
+    if (!flags.every((f) => allowedFlags.has(f)))
+        return false;
+    if (positionals.length === 0) {
+        return flags.some((f) => f === "--version" || f === "-V" || f === "-v");
+    }
+    return positionals.length === 1 && positionals[0] === "version";
+}
+//# sourceMappingURL=version-request.js.map

package/package.json

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