@indigoai-us/hq-cli 5.12.2 → 5.12.3

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## [5.12.3] — 2026-05-12
+
+### Added
+
+- **`hq files share <prefix>...` (no `--with`) — browser-launched share-session flow.**
+  Mints an encrypted single-use token via `POST /files/{companyUid}/share-session`,
+  opens the default browser to `https://hq.{co}.com/share-session/<token>`, and lets
+  the issuer batch-pick recipients (members, groups, "Share with All") with per-recipient
+  read/write before submitting all grants in one round-trip. Variadic — accepts multiple
+  paths in a single invocation: `hq files share path/a/ path/b/ path/c/`.
+
+- **`--no-open` flag on `hq files share`** — prints the share-session URL without
+  launching a browser. Useful for headless contexts (SSH sessions, CI, paste-into-chat
+  workflows). Output includes the URL, paths, and `expiresAt` timestamp.
+
+- **`--with @all` for company-wide grants.** Writes a single ACL entry with
+  `granteeType: 'company-wide'` covering every active member of the company, replacing
+  the legacy `open: true` flag pattern with explicit, individually-revocable grants.
+  Works on both `hq files share` and `hq files unshare`. Members added after the grant
+  resolve through the company-wide entry automatically at vend-time — no ACL re-write
+  needed.
+
+### Fixed
+
+- **`hq --version` now prints the correct version.** The embedded version
+  constant had drifted from `package.json` since 5.12.1 (the 5.12.2 release
+  still reported `5.12.1`).
+
+### Backwards Compatibility
+
+- The legacy direct-grant form (`hq files share <prefix> --with <principal> --permission <level>`)
+  is unchanged. The browser flow only triggers when `--with` is absent. Scripted
+  automation calling the direct-grant form requires no changes.
+
+### Security Notes
+
+- Share-session tokens are AES-256-GCM encrypted with the master key and pin the issuer's
+  identity, the requested paths, and `maxPermissionByPath` at mint time. The web page
+  cannot grant beyond what the issuer had at mint, even if mutated client-side.
+- Default TTL: 15 minutes. Bounded `60s..7d` server-side.
+- Single-use: the submit endpoint claims the token's nonce atomically (DynamoDB
+  `attribute_not_exists`); a second submit returns 409.
+- **Treat share-session URLs as live capabilities** — do not paste them into commits,
+  thread files, journals, or any persistent surface. The 15-minute TTL is defense
+  in depth, not a license to log them.
+
 ## [5.12.2] — 2026-05-10
 
 ### Added

package/dist/commands/files.d.ts

@@ -1,3 +1,44 @@
 import { Command } from "commander";
+/**
+ * Parse a human-friendly duration string ("15m", "1h", "24h", "2d") into
+ * milliseconds. Returns null on parse failure. Mirrors the parser used in
+ * `secrets generate-link` but kept local so files.ts can be tested in
+ * isolation without importing the much larger secrets command surface.
+ */
+export declare function parseDuration(input: string): number | null;
+/** PRD upper bound on browser-launch share-session expiry. */
+export declare const MAX_SHARE_SESSION_EXPIRY_MS: number;
+export interface ShareSessionResponse {
+    url: string;
+    token?: string;
+    expiresAt: string;
+    nonce?: string;
+    paths?: string[];
+    maxPermissionByPath?: Record<string, string>;
+}
+export interface MintShareSessionParams {
+    token: string;
+    companyUid: string;
+    paths: string[];
+    expiresInMs?: number;
+}
+/**
+ * POST /files/{companyUid}/share-session — mint a browser-launch share
+ * session token. Returns the parsed response. Throws ShareSessionHttpError
+ * with a status + actionable message for any non-2xx so callers can render
+ * a single consistent error path.
+ */
+export declare function mintShareSession(params: MintShareSessionParams): Promise<ShareSessionResponse>;
+export declare class ShareSessionHttpError extends Error {
+    readonly status: number;
+    readonly path?: string | undefined;
+    constructor(status: number, message: string, path?: string | undefined);
+}
+/**
+ * Map a ShareSessionHttpError to user-facing copy. Centralizes the
+ * status → message mapping so the share command and any future caller
+ * stay in sync.
+ */
+export declare function formatShareSessionError(err: ShareSessionHttpError): string;
 export declare function registerFilesCommand(program: Command): void;
 //# sourceMappingURL=files.d.ts.map

package/dist/commands/files.js

@@ -1,86 +1,133 @@
 
-!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]="a754383e-f129-5052-a8d8-59ea590b4f3d")}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]="50b160eb-d996-5ac2-8efc-b1791b469f3a")}catch(e){}}();
 import chalk from "chalk";
+import open from "open";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch, getCompanyUid } from "./secrets.js";
 import { GROUP_ID_PATTERN, EMAIL_PATTERN, normalizeFilePrefix } from "./_patterns.js";
+// ---------------------------------------------------------------------------
+// Pure helpers (exported for unit tests)
+// ---------------------------------------------------------------------------
+/**
+ * Parse a human-friendly duration string ("15m", "1h", "24h", "2d") into
+ * milliseconds. Returns null on parse failure. Mirrors the parser used in
+ * `secrets generate-link` but kept local so files.ts can be tested in
+ * isolation without importing the much larger secrets command surface.
+ */
+export function parseDuration(input) {
+    const match = input.match(/^(\d+)(m|h|d)$/);
+    if (!match)
+        return null;
+    const value = parseInt(match[1], 10);
+    const unit = match[2];
+    if (unit === "m")
+        return value * 60 * 1000;
+    if (unit === "h")
+        return value * 60 * 60 * 1000;
+    if (unit === "d")
+        return value * 24 * 60 * 60 * 1000;
+    return null;
+}
+/** PRD upper bound on browser-launch share-session expiry. */
+export const MAX_SHARE_SESSION_EXPIRY_MS = 24 * 60 * 60 * 1000; // 24h
+/**
+ * POST /files/{companyUid}/share-session — mint a browser-launch share
+ * session token. Returns the parsed response. Throws ShareSessionHttpError
+ * with a status + actionable message for any non-2xx so callers can render
+ * a single consistent error path.
+ */
+export async function mintShareSession(params) {
+    const body = { paths: params.paths };
+    if (params.expiresInMs != null)
+        body.expiresInMs = params.expiresInMs;
+    const res = await vaultApiFetch({
+        token: params.token,
+        path: `/files/${encodeURIComponent(params.companyUid)}/share-session`,
+        method: "POST",
+        body,
+    });
+    if (!res.ok) {
+        const errBody = (await res.json().catch(() => ({})));
+        throw new ShareSessionHttpError(res.status, errBody.message ?? errBody.error ?? res.statusText, errBody.path);
+    }
+    return (await res.json());
+}
+export class ShareSessionHttpError extends Error {
+    status;
+    path;
+    constructor(status, message, path) {
+        super(message);
+        this.status = status;
+        this.path = path;
+        this.name = "ShareSessionHttpError";
+    }
+}
+/**
+ * Map a ShareSessionHttpError to user-facing copy. Centralizes the
+ * status → message mapping so the share command and any future caller
+ * stay in sync.
+ */
+export function formatShareSessionError(err) {
+    if (err.status === 401) {
+        return "Not authenticated — please run `hq login`";
+    }
+    if (err.status === 403) {
+        if (err.path) {
+            return `Not authorized to share '${err.path}' — you need read access on every path`;
+        }
+        return "Not authorized — you need to be a company member with read access on every path";
+    }
+    if (err.status === 400) {
+        return `Invalid request: ${err.message}`;
+    }
+    if (err.status >= 500) {
+        return `Server error: ${err.message}`;
+    }
+    return err.message || `Request failed (${err.status})`;
+}
+// ---------------------------------------------------------------------------
+// Command registration
+// ---------------------------------------------------------------------------
 export function registerFilesCommand(program) {
     const files = program
         .command("files")
         .description("Manage file access controls in HQ vault")
         .option("--company <slug>", "Company slug (resolves to companyUid)");
     files
-        .command("share <prefix>")
-        .description("Share a file prefix with a person or group")
-        .requiredOption("--with <principal>", "Email address or group id to share with")
-        .requiredOption("--permission <level>", "Permission level: read | write")
-        .action(async (prefix, opts) => {
+        .command("share [paths...]")
+        .description("Share file paths. Without --with: mint a share-session URL and open it in the browser. With --with: grant access directly to a person, group, or @all.")
+        .option("--with <principal>", "Email address, group id, or '@all' to share with every active company member")
+        .option("--permission <level>", "Permission level (only with --with): read | write")
+        .option("--expires <duration>", "Token expiry duration for share-session URL (e.g. 15m, 1h, 24h). Default 15m. Max 24h.")
+        .option("--no-open", "Print the share-session URL but do not launch the browser")
+        .action(async (paths, opts) => {
         try {
-            const canonicalPrefix = normalizeFilePrefix(prefix);
-            if (!["read", "write"].includes(opts.permission)) {
-                console.error(chalk.red(`Invalid permission '${opts.permission}': must be one of read, write`));
+            if (!paths || paths.length === 0) {
+                console.error(chalk.red("usage: hq files share <paths...> [--with <principal>]"));
                 process.exit(1);
             }
-            const principal = opts.with;
-            const isEmail = EMAIL_PATTERN.test(principal);
-            const isGroup = GROUP_ID_PATTERN.test(principal);
-            if (!isEmail && !isGroup) {
-                console.error(chalk.red(`Invalid principal '${principal}': must be an email address or a group id matching grp_<alphanumeric>`));
-                process.exit(1);
-            }
-            const granteeType = isEmail ? "email" : "group";
-            const granteeId = isEmail ? principal.trim().toLowerCase() : principal;
-            const token = await ensureCognitoToken();
-            const companySlug = files.opts().company;
-            const companyUid = await getCompanyUid(token, companySlug);
-            let res = await vaultApiFetch({
-                token,
-                path: `/files/${encodeURIComponent(companyUid)}/acl/grant`,
-                method: "POST",
-                body: { prefix: canonicalPrefix, granteeType, granteeId, permission: opts.permission },
-            });
-            // No ACL row exists yet for this prefix. Auto-create one with this
-            // grant as its first entry, then report success — saves the caller
-            // from needing a separate "create" step.
-            let autoCreated = false;
-            if (res.status === 404) {
-                res = await vaultApiFetch({
-                    token,
-                    path: `/files/${encodeURIComponent(companyUid)}/acl`,
-                    method: "POST",
-                    body: {
-                        prefix: canonicalPrefix,
-                        entries: [{ granteeType, granteeId, permission: opts.permission }],
-                    },
-                });
-                autoCreated = res.ok;
-            }
-            if (!res.ok) {
-                const body = await res.json().catch(() => ({}));
-                if (res.status === 401) {
-                    console.error(chalk.red("Not authenticated — please run `hq login`"));
-                }
-                else if (res.status === 403) {
-                    console.error(chalk.red("Not authorized to share this file prefix"));
-                }
-                else if (res.status === 404) {
-                    console.error(chalk.red("ACL record not found — the prefix may not have an ACL yet"));
-                }
-                else if (res.status === 409) {
-                    console.error(chalk.red("Concurrent modification — please retry"));
+            // Fork: --with present → existing direct-grant path. No --with →
+            // browser-launch share-session path. Per PRD, the direct-grant
+            // path is unchanged from US-001 and operates on a single prefix.
+            if (opts.with !== undefined) {
+                if (paths.length !== 1) {
+                    console.error(chalk.red("Direct grant (--with) takes exactly one prefix. Pass multiple paths only when minting a share-session URL."));
+                    process.exit(1);
                 }
-                else if (res.status >= 500) {
-                    console.error(chalk.red(`Server error: ${body.error ?? res.statusText}`));
-                }
-                else {
-                    console.error(chalk.red(body.message ?? body.error ?? "Invalid request"));
-                }
-                process.exit(1);
+                await runDirectGrant({
+                    prefix: paths[0],
+                    principal: opts.with,
+                    permission: opts.permission,
+                    companySlug: files.opts().company,
+                });
+                return;
             }
-            const data = await res.json();
-            const printedPrefix = data.acl?.path ?? data.acl?.prefix ?? canonicalPrefix;
-            const verb = autoCreated ? "Created ACL and granted" : "Granted";
-            console.log(chalk.green(`${verb} ${opts.permission} on ${printedPrefix} to ${granteeId}`));
+            await runShareSession({
+                paths,
+                expires: opts.expires,
+                launchBrowser: opts.open,
+                companySlug: files.opts().company,
+            });
         }
         catch (err) {
             console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
@@ -90,19 +137,29 @@ export function registerFilesCommand(program) {
     files
         .command("unshare <prefix>")
         .description("Remove a file access grant")
-        .requiredOption("--with <principal>", "Email address or group id to remove")
+        .requiredOption("--with <principal>", "Email address, group id, or '@all' to remove the company-wide grant")
         .action(async (prefix, opts) => {
         try {
             const canonicalPrefix = normalizeFilePrefix(prefix);
             const principal = opts.with;
-            const isEmail = EMAIL_PATTERN.test(principal);
-            const isGroup = GROUP_ID_PATTERN.test(principal);
-            if (!isEmail && !isGroup) {
-                console.error(chalk.red(`Invalid principal '${principal}': must be an email address or a group id matching grp_<alphanumeric>`));
+            const isAll = principal === "@all";
+            const isEmail = !isAll && EMAIL_PATTERN.test(principal);
+            const isGroup = !isAll && GROUP_ID_PATTERN.test(principal);
+            if (!isAll && !isEmail && !isGroup) {
+                console.error(chalk.red(`Invalid principal '${principal}': must be '@all', an email address, or a group id matching grp_<alphanumeric>`));
                 process.exit(1);
             }
-            const granteeType = isEmail ? "email" : "group";
-            const granteeId = isEmail ? principal.trim().toLowerCase() : principal;
+            const granteeType = isAll
+                ? "company-wide"
+                : isEmail
+                    ? "email"
+                    : "group";
+            const granteeId = isAll
+                ? ""
+                : isEmail
+                    ? principal.trim().toLowerCase()
+                    : principal;
+            const principalLabel = isAll ? "everyone in the company" : granteeId;
             const token = await ensureCognitoToken();
             const companySlug = files.opts().company;
             const companyUid = await getCompanyUid(token, companySlug);
@@ -121,7 +178,7 @@ export function registerFilesCommand(program) {
                     console.error(chalk.red("Not authorized to modify this file prefix's ACL"));
                 }
                 else if (res.status === 404) {
-                    console.log(chalk.green(`Grant already absent for '${canonicalPrefix}' / ${granteeId}`));
+                    console.log(chalk.green(`Grant already absent for '${canonicalPrefix}' / ${principalLabel}`));
                     return;
                 }
                 else if (res.status >= 500) {
@@ -132,7 +189,7 @@ export function registerFilesCommand(program) {
                 }
                 process.exit(1);
             }
-            console.log(chalk.green(`Removed grant for ${granteeId} on '${canonicalPrefix}'`));
+            console.log(chalk.green(`Removed grant for ${principalLabel} on '${canonicalPrefix}'`));
         }
         catch (err) {
             console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
@@ -206,9 +263,17 @@ export function registerFilesCommand(program) {
             else {
                 console.log(chalk.gray("No direct ACL row — access flows from the inherited/descendant grants below."));
             }
+            // Display labels for grantee identifiers — `company-wide` entries
+            // store `granteeId === ""` on the wire, but a blank cell is confusing
+            // in tabular output, so we render a human-readable phrase instead.
+            function displayGrantee(e) {
+                if (e.granteeType === "company-wide")
+                    return "Everyone in company";
+                return e.granteeId;
+            }
             function printEntryTable(rows, showSource) {
                 const TYPE_W = Math.max(4, ...rows.map((e) => e.granteeType.length));
-                const GRANTEE_W = Math.max(7, ...rows.map((e) => e.granteeId.length));
+                const GRANTEE_W = Math.max(7, ...rows.map((e) => displayGrantee(e).length));
                 const PERM_W = Math.max(10, ...rows.map((e) => e.permission.length));
                 const BY_W = Math.max(10, ...rows.map((e) => e.grantedBy.length));
                 const SRC_W = showSource
@@ -228,7 +293,7 @@ export function registerFilesCommand(program) {
                     const grantedAt = e.grantedAt.slice(0, 10);
                     const cols = [
                         e.granteeType.padEnd(TYPE_W),
-                        e.granteeId.padEnd(GRANTEE_W),
+                        displayGrantee(e).padEnd(GRANTEE_W),
                         e.permission.padEnd(PERM_W),
                         e.grantedBy.padEnd(BY_W),
                         grantedAt,
@@ -266,5 +331,144 @@ export function registerFilesCommand(program) {
         }
     });
 }
+async function runDirectGrant(params) {
+    const canonicalPrefix = normalizeFilePrefix(params.prefix);
+    if (!params.permission) {
+        console.error(chalk.red("--permission is required when --with is set (read | write)"));
+        process.exit(1);
+    }
+    if (!["read", "write"].includes(params.permission)) {
+        console.error(chalk.red(`Invalid permission '${params.permission}': must be one of read, write`));
+        process.exit(1);
+    }
+    const principal = params.principal;
+    // `@all` is the company-wide sentinel — maps to a single typed
+    // 'company-wide' ACL entry whose applicability is computed at resolve
+    // time from the active-member list. We send granteeId as the empty
+    // string to match the canonical storage form on the server.
+    const isAll = principal === "@all";
+    const isEmail = !isAll && EMAIL_PATTERN.test(principal);
+    const isGroup = !isAll && GROUP_ID_PATTERN.test(principal);
+    if (!isAll && !isEmail && !isGroup) {
+        console.error(chalk.red(`Invalid principal '${principal}': must be '@all', an email address, or a group id matching grp_<alphanumeric>`));
+        process.exit(1);
+    }
+    const granteeType = isAll ? "company-wide" : isEmail ? "email" : "group";
+    const granteeId = isAll
+        ? ""
+        : isEmail
+            ? principal.trim().toLowerCase()
+            : principal;
+    // Display label used in success messages — `@all` reads better than `""`.
+    const principalLabel = isAll ? "everyone in the company" : granteeId;
+    const token = await ensureCognitoToken();
+    const companyUid = await getCompanyUid(token, params.companySlug);
+    let res = await vaultApiFetch({
+        token,
+        path: `/files/${encodeURIComponent(companyUid)}/acl/grant`,
+        method: "POST",
+        body: {
+            prefix: canonicalPrefix,
+            granteeType,
+            granteeId,
+            permission: params.permission,
+        },
+    });
+    // No ACL row exists yet for this prefix. Auto-create one with this
+    // grant as its first entry, then report success — saves the caller
+    // from needing a separate "create" step.
+    let autoCreated = false;
+    if (res.status === 404) {
+        res = await vaultApiFetch({
+            token,
+            path: `/files/${encodeURIComponent(companyUid)}/acl`,
+            method: "POST",
+            body: {
+                prefix: canonicalPrefix,
+                entries: [{ granteeType, granteeId, permission: params.permission }],
+            },
+        });
+        autoCreated = res.ok;
+    }
+    if (!res.ok) {
+        const body = (await res.json().catch(() => ({})));
+        if (res.status === 401) {
+            console.error(chalk.red("Not authenticated — please run `hq login`"));
+        }
+        else if (res.status === 403) {
+            console.error(chalk.red("Not authorized to share this file prefix"));
+        }
+        else if (res.status === 404) {
+            console.error(chalk.red("ACL record not found — the prefix may not have an ACL yet"));
+        }
+        else if (res.status === 409) {
+            console.error(chalk.red("Concurrent modification — please retry"));
+        }
+        else if (res.status >= 500) {
+            console.error(chalk.red(`Server error: ${body.error ?? res.statusText}`));
+        }
+        else {
+            console.error(chalk.red(body.message ?? body.error ?? "Invalid request"));
+        }
+        process.exit(1);
+    }
+    const data = (await res.json());
+    const printedPrefix = data.acl?.path ?? data.acl?.prefix ?? canonicalPrefix;
+    const verb = autoCreated ? "Created ACL and granted" : "Granted";
+    console.log(chalk.green(`${verb} ${params.permission} on ${printedPrefix} to ${principalLabel}`));
+}
+async function runShareSession(params) {
+    // Normalize every path through the shared prefix helper so a trailing
+    // `/` becomes `/*` consistently with the direct-grant path.
+    const normalizedPaths = params.paths.map(normalizeFilePrefix);
+    let expiresInMs;
+    if (params.expires !== undefined) {
+        const parsed = parseDuration(params.expires);
+        if (parsed === null) {
+            console.error(chalk.red(`Invalid duration '${params.expires}'. Use formats like 15m, 1h, 24h.`));
+            process.exit(1);
+        }
+        if (parsed > MAX_SHARE_SESSION_EXPIRY_MS) {
+            console.error(chalk.red("Maximum share-session expiry is 24h. For longer sharing, use `hq files share <prefix> --with <principal>`."));
+            process.exit(1);
+        }
+        expiresInMs = parsed;
+    }
+    const token = await ensureCognitoToken();
+    const companyUid = await getCompanyUid(token, params.companySlug);
+    let session;
+    try {
+        session = await mintShareSession({
+            token,
+            companyUid,
+            paths: normalizedPaths,
+            expiresInMs,
+        });
+    }
+    catch (err) {
+        if (err instanceof ShareSessionHttpError) {
+            console.error(chalk.red(formatShareSessionError(err)));
+            process.exit(1);
+        }
+        throw err;
+    }
+    console.log(chalk.green("Share-session URL generated:"));
+    console.log(`\n  ${session.url}\n`);
+    console.log(chalk.dim(`  Paths:   ${normalizedPaths.join(", ")}`));
+    console.log(chalk.dim(`  Expires: ${session.expiresAt}`));
+    if (params.launchBrowser) {
+        // Best-effort browser launch — failures (no display, missing handler)
+        // shouldn't fail the command since the URL is already printed.
+        try {
+            await open(session.url);
+        }
+        catch (err) {
+            console.error(chalk.yellow(`Couldn't launch browser automatically (${err instanceof Error ? err.message : String(err)}). Copy the URL above.`));
+        }
+    }
+    else {
+        console.log(chalk.dim("  --no-open: copy the URL above to share manually."));
+    }
+}
 //# sourceMappingURL=files.js.map
-//# debugId=a754383e-f129-5052-a8d8-59ea590b4f3d
+//# debugId=50b160eb-d996-5ac2-8efc-b1791b469f3a

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]="65033669-3ba8-5aac-8a98-49827f627ff9")}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]="efa927a6-3cad-5122-928e-f7b055b533e8")}catch(e){}}();
 import { Command } from "commander";
 import { initSentry, Sentry } from "./sentry.js";
 import { registerAddCommand } from "./commands/add.js";
@@ -30,12 +30,14 @@ import { registerFilesCommand } from "./commands/files.js";
 import { registerMembersCommand } from "./commands/members.js";
 import { registerFeedbackCommand } from "./commands/feedback.js";
 import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
+import { maybeWarnNewVersion, refreshVersionCache, } from "./utils/version-check.js";
 initSentry();
+maybeWarnNewVersion();
 const program = new Command();
 program
     .name("hq")
     .description("HQ management CLI — modules, packages, and cloud sync")
-    .version("5.12.1");
+    .version("5.12.3");
 // Module management subcommand group
 const modulesCmd = program
     .command("modules")
@@ -104,8 +106,8 @@ registerFeedbackCommand(program);
         process.exitCode = 1;
     }
     finally {
-        await Sentry.flush(2000);
+        await Promise.allSettled([refreshVersionCache(), Sentry.flush(2000)]);
     }
 })();
 //# sourceMappingURL=index.js.map
-//# debugId=65033669-3ba8-5aac-8a98-49827f627ff9
+//# debugId=efa927a6-3cad-5122-928e-f7b055b533e8

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

@@ -0,0 +1,3 @@
+export declare function maybeWarnNewVersion(): void;
+export declare function refreshVersionCache(): Promise<void>;
+//# sourceMappingURL=version-check.d.ts.map

package/dist/utils/version-check.js

@@ -0,0 +1,80 @@
+
+!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]="99545a82-414c-5fed-a478-ea8e63009643")}catch(e){}}();
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import semver from "semver";
+import chalk from "chalk";
+import { CLI_VERSION } from "../cli-version.js";
+const PACKAGE_NAME = "@indigoai-us/hq-cli";
+const REGISTRY_URL = `https://registry.npmjs.org/${encodeURIComponent(PACKAGE_NAME)}/latest`;
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 3_000;
+function cachePath() {
+    return path.join(os.homedir(), ".hq", "version-check.json");
+}
+function isOptedOut() {
+    return process.env.HQ_NO_UPDATE_CHECK === "1";
+}
+function readCache() {
+    try {
+        const raw = fs.readFileSync(cachePath(), "utf-8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.latest !== "string" ||
+            typeof parsed.fetchedAt !== "number") {
+            return null;
+        }
+        return { latest: parsed.latest, fetchedAt: parsed.fetchedAt };
+    }
+    catch {
+        return null;
+    }
+}
+function writeCache(entry) {
+    try {
+        const file = cachePath();
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(entry));
+    }
+    catch {
+        // best-effort; never break the CLI on cache write failure
+    }
+}
+export function maybeWarnNewVersion() {
+    if (isOptedOut())
+        return;
+    const entry = readCache();
+    if (!entry)
+        return;
+    if (Date.now() - entry.fetchedAt > CACHE_TTL_MS)
+        return;
+    const current = semver.valid(CLI_VERSION);
+    const latest = semver.valid(entry.latest);
+    if (!current || !latest)
+        return;
+    if (!semver.gt(latest, current))
+        return;
+    const msg = chalk.yellow(`⚠ A new version of hq is available: ${entry.latest} (current: ${CLI_VERSION}). It's recommended to update.`);
+    console.error(msg);
+}
+export async function refreshVersionCache() {
+    if (isOptedOut())
+        return;
+    try {
+        const res = await fetch(REGISTRY_URL, {
+            headers: { Accept: "application/json" },
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+        });
+        if (!res.ok)
+            return;
+        const body = (await res.json());
+        if (typeof body.version !== "string")
+            return;
+        writeCache({ latest: body.version, fetchedAt: Date.now() });
+    }
+    catch {
+        // best-effort; offline / registry down / timeout — silent
+    }
+}
+//# sourceMappingURL=version-check.js.map
+//# debugId=99545a82-414c-5fed-a478-ea8e63009643

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.12.2",
+  "version": "5.12.3",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -21,6 +21,7 @@
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
     "js-yaml": "^4.1.0",
+    "open": "^10.1.0",
     "simple-git": "^3.27.0",
     "semver": "^7.6.3",
     "varlock": "1.0.0"