@indigoai-us/hq-cli 5.77.8 → 5.77.10

package/CHANGELOG.md

@@ -2,7 +2,25 @@
 
 ## [Unreleased]
 
-## [5.77.8]
+## [5.77.9]
+
+### Added
+
+- The CLI now surfaces a plan-limit warning when an account approaches its
+  configured limits. (#265)
+
+### Fixed
+
+- A pnpm-managed global install now self-updates with
+  `pnpm add -g @indigoai-us/hq-cli@latest` instead of an npm `--prefix`
+  install into pnpm's content store. The npm path exited 0 while the PATH shim
+  kept running the old build, so the version gate reported success and the
+  next invocation detected the same stale version — an update loop that could
+  never converge. Detection is restricted to genuinely global pnpm layouts, so
+  a local project dependency or a `pnpm dlx` cache is not mistaken for the
+  global install. A missing `pnpm`/`npm` on PATH now exits 75 with an explicit
+  message instead of failing unexplained under minimal-PATH parents such as
+  launchd or cron. (#266)
 
 ### Fixed
 

package/dist/lib/plan-limit-nag.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `plan-limit-nag` (US-016) — non-blocking plan-limit warning surface.
+ *
+ * hq-pro shallow-merges a `planLimits` status payload into the top level of
+ * some 2xx JSON response bodies (US-012). This module:
+ *
+ *   1. Best-effort records the last-seen status from decoded JSON bodies
+ *      (`recordPlanLimitStatus`).
+ *   2. Emits a stderr nag at command completion (`emitPlanLimitNag`):
+ *      - entries present, none over (≥80% warning): one-line yellow warning,
+ *        once per process session
+ *      - any resource over: boxed notice, at most once per day (persisted in
+ *        `~/.hq/plan-limit-nag.json`) and once per session
+ *
+ * Additive only — never throws, never touches `process.exitCode`, never
+ * writes to stdout. Env off-switch: `HQ_NO_PLAN_LIMIT_NAG=1`.
+ */
+export declare const PLAN_LIMIT_UPGRADE_URL = "https://app.indigo-hq.com/billing/upgrade";
+export interface PlanLimitEntry {
+    used: number;
+    limit: number;
+    over: boolean;
+}
+/** Validated map of resource key → entry. */
+export type PlanLimitsMap = Record<string, PlanLimitEntry>;
+/**
+ * Record plan-limit status from a decoded JSON response body.
+ * Never throws. Overwrites the last-seen cell when a well-formed
+ * `planLimits` object is present; ignores malformed / absent payloads.
+ */
+export declare function recordPlanLimitStatus(body: unknown): void;
+/**
+ * Emit a plan-limit nag to stderr at command completion.
+ *
+ * Never throws, never touches `process.exitCode`. Default sink is
+ * `process.stderr.write`. Tests inject `write`, `now`, and `statePath`.
+ */
+export declare function emitPlanLimitNag(opts?: {
+    write?: (s: string) => void;
+    now?: () => Date;
+    statePath?: string;
+}): void;
+/** Test-only helper — clears last-seen status and session dedupe flags. */
+export declare function _resetForTests(): void;
+//# sourceMappingURL=plan-limit-nag.d.ts.map

package/dist/lib/plan-limit-nag.js

@@ -0,0 +1,212 @@
+/**
+ * `plan-limit-nag` (US-016) — non-blocking plan-limit warning surface.
+ *
+ * hq-pro shallow-merges a `planLimits` status payload into the top level of
+ * some 2xx JSON response bodies (US-012). This module:
+ *
+ *   1. Best-effort records the last-seen status from decoded JSON bodies
+ *      (`recordPlanLimitStatus`).
+ *   2. Emits a stderr nag at command completion (`emitPlanLimitNag`):
+ *      - entries present, none over (≥80% warning): one-line yellow warning,
+ *        once per process session
+ *      - any resource over: boxed notice, at most once per day (persisted in
+ *        `~/.hq/plan-limit-nag.json`) and once per session
+ *
+ * Additive only — never throws, never touches `process.exitCode`, never
+ * writes to stdout. Env off-switch: `HQ_NO_PLAN_LIMIT_NAG=1`.
+ */
+import chalk from "chalk";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+export const PLAN_LIMIT_UPGRADE_URL = "https://app.indigo-hq.com/billing/upgrade";
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** Module-level last-seen cell — overwritten by each successful parse. */
+let lastSeen = null;
+/** Session dedupe for the ≥80% one-line warning. */
+let warningShownThisSession = false;
+/** Session dedupe for the over-limit boxed notice. */
+let overShownThisSession = false;
+function defaultStatePath() {
+    return path.join(os.homedir(), ".hq", "plan-limit-nag.json");
+}
+function isOptedOut() {
+    return process.env.HQ_NO_PLAN_LIMIT_NAG === "1";
+}
+/**
+ * Defensively parse a single planLimits entry. Returns null if the shape is
+ * not well-formed (non-numeric used/limit, non-boolean over, etc.).
+ */
+function parseEntry(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return null;
+    }
+    const rec = value;
+    if (typeof rec.used !== "number" ||
+        !Number.isFinite(rec.used) ||
+        typeof rec.limit !== "number" ||
+        !Number.isFinite(rec.limit) ||
+        typeof rec.over !== "boolean") {
+        return null;
+    }
+    return { used: rec.used, limit: rec.limit, over: rec.over };
+}
+/**
+ * Defensively parse a decoded JSON body for a well-formed top-level
+ * `planLimits` object. Malformed or absent → null. Never throws.
+ */
+function parsePlanLimits(body) {
+    if (body === null || typeof body !== "object" || Array.isArray(body)) {
+        return null;
+    }
+    const planLimits = body.planLimits;
+    if (planLimits === null ||
+        typeof planLimits !== "object" ||
+        Array.isArray(planLimits)) {
+        return null;
+    }
+    const out = {};
+    let anyValid = false;
+    for (const [key, value] of Object.entries(planLimits)) {
+        const entry = parseEntry(value);
+        if (entry === null)
+            continue;
+        out[key] = entry;
+        anyValid = true;
+    }
+    return anyValid ? out : null;
+}
+/**
+ * Record plan-limit status from a decoded JSON response body.
+ * Never throws. Overwrites the last-seen cell when a well-formed
+ * `planLimits` object is present; ignores malformed / absent payloads.
+ */
+export function recordPlanLimitStatus(body) {
+    try {
+        const limits = parsePlanLimits(body);
+        if (limits === null)
+            return;
+        const anyOver = Object.values(limits).some((e) => e.over);
+        lastSeen = { limits, anyOver };
+    }
+    catch {
+        // Never throw from record path.
+    }
+}
+function usageRatio(entry) {
+    if (entry.limit <= 0)
+        return entry.used > 0 ? Infinity : 0;
+    return entry.used / entry.limit;
+}
+/** Pick the resource with the highest used/limit ratio (worst headroom). */
+function worstResource(limits) {
+    let best = null;
+    for (const [key, entry] of Object.entries(limits)) {
+        const ratio = usageRatio(entry);
+        if (best === null || ratio > best.ratio) {
+            best = { key, entry, ratio };
+        }
+    }
+    return best ? { key: best.key, entry: best.entry } : null;
+}
+function formatPct(entry) {
+    if (entry.limit <= 0)
+        return entry.used > 0 ? "∞" : "0%";
+    return `${Math.round((entry.used / entry.limit) * 100)}%`;
+}
+function formatEntryLine(key, entry) {
+    return `${key} at ${entry.used}/${entry.limit} (${formatPct(entry)})`;
+}
+function readShownAt(statePath) {
+    try {
+        const raw = fs.readFileSync(statePath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.shownAt !== "number" || !Number.isFinite(parsed.shownAt)) {
+            return null;
+        }
+        return parsed.shownAt;
+    }
+    catch {
+        return null;
+    }
+}
+function writeShownAt(statePath, shownAt) {
+    try {
+        fs.mkdirSync(path.dirname(statePath), { recursive: true });
+        const payload = { shownAt };
+        fs.writeFileSync(statePath, JSON.stringify(payload));
+    }
+    catch {
+        // best-effort; never break the CLI on cache write failure
+    }
+}
+function withinDayWindow(shownAt, nowMs) {
+    return nowMs - shownAt < DAY_MS;
+}
+function buildOverBox(overEntries) {
+    const title = "⚠ HQ plan limit exceeded";
+    const upgrade = `Upgrade: ${PLAN_LIMIT_UPGRADE_URL}`;
+    const resourceLines = overEntries.map(([key, entry]) => `  ${key}: ${entry.used}/${entry.limit}`);
+    const contentLines = [title, "", ...resourceLines, "", upgrade];
+    const innerWidth = Math.max(...contentLines.map((l) => l.length), 40);
+    const top = `┌${"─".repeat(innerWidth + 2)}┐`;
+    const bot = `└${"─".repeat(innerWidth + 2)}┘`;
+    const mid = contentLines
+        .map((l) => `│ ${l.padEnd(innerWidth)} │`)
+        .join("\n");
+    return `${top}\n${mid}\n${bot}`;
+}
+/**
+ * Emit a plan-limit nag to stderr at command completion.
+ *
+ * Never throws, never touches `process.exitCode`. Default sink is
+ * `process.stderr.write`. Tests inject `write`, `now`, and `statePath`.
+ */
+export function emitPlanLimitNag(opts = {}) {
+    try {
+        if (isOptedOut())
+            return;
+        if (lastSeen === null)
+            return;
+        const write = opts.write ?? ((s) => process.stderr.write(s));
+        const now = opts.now ?? (() => new Date());
+        const statePath = opts.statePath ?? defaultStatePath();
+        const { limits, anyOver } = lastSeen;
+        const entries = Object.entries(limits);
+        if (entries.length === 0)
+            return;
+        if (anyOver) {
+            if (overShownThisSession)
+                return;
+            const nowMs = now().getTime();
+            const prev = readShownAt(statePath);
+            if (prev !== null && withinDayWindow(prev, nowMs))
+                return;
+            overShownThisSession = true;
+            const overEntries = entries.filter(([, e]) => e.over);
+            const box = buildOverBox(overEntries);
+            write(chalk.yellow(box) + "\n");
+            writeShownAt(statePath, nowMs);
+            return;
+        }
+        // Warning path: entries present, none over (≥80% resources only appear).
+        if (warningShownThisSession)
+            return;
+        const worst = worstResource(limits);
+        if (worst === null)
+            return;
+        warningShownThisSession = true;
+        const line = `⚠ HQ free plan: ${formatEntryLine(worst.key, worst.entry)}. Upgrade: ${PLAN_LIMIT_UPGRADE_URL}`;
+        write(chalk.yellow(line) + "\n");
+    }
+    catch {
+        // Never throw from emit path.
+    }
+}
+/** Test-only helper — clears last-seen status and session dedupe flags. */
+export function _resetForTests() {
+    lastSeen = null;
+    warningShownThisSession = false;
+    overShownThisSession = false;
+}
+//# sourceMappingURL=plan-limit-nag.js.map

package/dist/main.js

@@ -68,6 +68,7 @@ import { enforceVersionGate, shouldSkipGate, } from "./utils/version-gate.js";
 import { CLI_VERSION } from "./cli-version.js";
 import { emitCliSessionStarted } from "./utils/cli-telemetry.js";
 import { settleWithin } from "./utils/settle-with-timeout.js";
+import { emitPlanLimitNag } from "./lib/plan-limit-nag.js";
 /** Hard upper bound for non-user-visible release-health finalization. */
 const RELEASE_HEALTH_SETTLE_TIMEOUT_MS = 3_000;
 // Swallow EPIPE when a downstream reader (e.g. `source <(…)`, `| head`) closes
@@ -307,6 +308,9 @@ export async function runCli() {
         }
     }
     finally {
+        // Plan-limit nag (US-016): stderr-only, never throws, never touches
+        // process.exitCode — safe to run after exit codes have been set.
+        emitPlanLimitNag();
         // Release health: finalize the per-run session before the flush.
         Sentry.endSession();
         // Neither task may turn a successful command into Node's

package/dist/utils/vault-api.js

@@ -2,6 +2,66 @@ import { DEFAULT_VAULT_API_URL } from './cognito-session.js';
 import { Sentry } from '../sentry.js';
 import { AuthError } from './auth-error.js';
 import { CompanySelectionError } from './company-selection-error.js';
+import { recordPlanLimitStatus } from '../lib/plan-limit-nag.js';
+/**
+ * Best-effort peek of a 2xx JSON body for plan-limit status (US-016).
+ *
+ * For ok JSON responses: read the body ONCE, record planLimits (best-effort),
+ * and return a NEW Response built from the buffered body so callers can still
+ * call .json()/.text()/.arrayBuffer(). Non-JSON and non-ok responses are
+ * returned untouched (streamed binary downloads must never be buffered).
+ *
+ * Never throws. On any error: return the original response if its body has
+ * not been consumed, otherwise the re-wrapped one.
+ *
+ * Why not response.clone()? Cloning tees the undici body stream; when a
+ * caller never consumes the original Response body (many commands only check
+ * response.ok/status), the unused tee branch keeps the connection/handle
+ * referenced and the process (or vitest worker / spawned CLI child) never
+ * exits on Linux CI. Reading once + re-wrapping fully drains the stream.
+ */
+async function peekPlanLimitStatus(response) {
+    try {
+        if (!response.ok)
+            return response;
+        const ct = response.headers.get('content-type') ?? '';
+        if (!ct.includes('application/json') && !ct.includes('+json')) {
+            return response;
+        }
+        let buf;
+        try {
+            buf = await response.arrayBuffer();
+        }
+        catch {
+            // Body may be locked/errored; original is the only thing we can return.
+            return response;
+        }
+        try {
+            const text = new TextDecoder().decode(buf);
+            try {
+                recordPlanLimitStatus(JSON.parse(text));
+            }
+            catch {
+                // Malformed JSON must be ignored silently.
+            }
+        }
+        catch {
+            // Best-effort record only — still re-wrap so body is readable.
+        }
+        // Body was consumed; always return a re-wrapped Response so callers can
+        // still read it (even if parse/record failed).
+        return new Response(buf, {
+            status: response.status,
+            statusText: response.statusText,
+            headers: response.headers,
+        });
+    }
+    catch {
+        // Outer safety net: never throw from the peek path. If we never consumed
+        // the body, the original is still usable.
+        return response;
+    }
+}
 export async function vaultApiFetch(opts) {
     const url = new URL(opts.path, DEFAULT_VAULT_API_URL);
     if (opts.query) {
@@ -33,8 +93,9 @@ export async function vaultApiFetch(opts) {
             level: "warning",
             data: { url: safeUrl, status: response.status },
         });
+        return response;
     }
-    return response;
+    return peekPlanLimitStatus(response);
 }
 /**
  * Public (NONE-auth) GET against the vault API — no bearer token. The

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

@@ -27,6 +27,8 @@
  * Opt-out: `HQ_NO_UPDATE_CHECK=1` (same env as `version-check.ts` — one knob
  * to silence both check + gate).
  */
+/** Which package manager owns the running global install. */
+export type InstallManager = "npm" | "pnpm";
 interface VersionCheckResponse {
     clientId: string;
     currentVersion: string;
@@ -39,8 +41,65 @@ interface VersionCheckResponse {
     message?: string;
 }
 export declare function npmPrefixFromPackageDir(pkgDir: string): string | null;
+/**
+ * Whether the running package lives inside a pnpm-managed **global** install.
+ *
+ * pnpm does not use npm's `<prefix>/lib/node_modules` layout. A global
+ * `pnpm add -g` puts the package in a versioned content store under the
+ * `global/<store-layout-version>` root and exposes it through a generated shim
+ * on PATH:
+ *
+ *   $PNPM_HOME/hq                                        <- shim on PATH
+ *   $PNPM_HOME/global/5/node_modules/@indigoai-us/hq-cli <- symlink
+ *   $PNPM_HOME/global/5/.pnpm/@indigoai-us+hq-cli@5.61.0/node_modules/…
+ *
+ * Both the symlinked and the resolved (`.pnpm`) form are recognised, because
+ * whether `import.meta.url` reports the link or its target depends on how node
+ * resolved the entrypoint.
+ *
+ * A bare `.pnpm` segment is deliberately NOT enough. It also appears in a local
+ * project dependency (`<proj>/node_modules/.pnpm/@indigoai-us+hq-cli@…`) and in
+ * a `pnpm dlx` cache. Neither of those is what `pnpm add -g` updates, so
+ * treating them as global would mutate the user's global install as a side
+ * effect of a local invocation while the copy actually running stayed stale —
+ * i.e. the gate would re-fire and re-install globally on every subsequent run.
+ * Those layouts fall through to the ordinary npm-prefix/manual handling.
+ */
+export declare function isPnpmManagedPackageDir(pkgDir: string): boolean;
+/**
+ * Where the running CLI is installed and who owns it. Resolved in ONE pass so
+ * the package-root walk (which reads and parses a `package.json` per directory
+ * level) happens once per invocation, and so the manager and the prefix can
+ * never disagree because the filesystem shifted between two separate walks.
+ *
+ * `prefix` is `null` for a pnpm-managed install even though a prefix-shaped
+ * string *can* be derived from those paths: `npmPrefixFromPackageDir` would
+ * happily hand back the pnpm store directory, and `npm install -g --prefix
+ * <store>` then unpacks a fresh copy into `<store>/lib/node_modules`, which
+ * pnpm's shim never reads. npm exits 0, the gate reports success, and the next
+ * `hq` invocation still runs the old version — the reported loop where a stale
+ * pnpm shim kept resolving 5.61.0 after every "successful" update.
+ *
+ * Defaults to npm with no prefix when the layout can't be determined — that is
+ * the historical behaviour and the common case.
+ */
+export interface RunningInstall {
+    manager: InstallManager;
+    prefix: string | null;
+    packageRoot: string | null;
+}
+export declare function resolveRunningInstall(): RunningInstall;
+/** Convenience view of {@link resolveRunningInstall} for callers needing one field. */
+export declare function resolveRunningManager(): InstallManager;
+/** Convenience view of {@link resolveRunningInstall} for callers needing one field. */
 export declare function resolveRunningPrefix(): string | null;
 export declare function buildPrefixedInstallArgv(prefix: string): string[];
+/**
+ * Argv for updating a pnpm-managed global install. `pnpm add -g` rewrites the
+ * PATH shim as part of the install, so the next invocation genuinely resolves
+ * the new version — which is the whole point of routing here instead of npm.
+ */
+export declare function buildPnpmInstallArgv(): string[];
 /**
  * Filesystem surface used by {@link cleanStalePartialInstall}. Injected so the
  * cleanup logic is unit-testable without touching a real global prefix.
@@ -84,11 +143,41 @@ export declare function cleanStalePartialInstall(prefix: string, fs?: StaleInsta
 type UpdateResult = {
     ok: boolean;
     detail?: string;
+    code?: string;
 };
 type UpdateRunner = (cmd: string, args: string[]) => UpdateResult;
+/**
+ * Quote an argv entry for a Windows `cmd.exe` invocation. Needed because Node
+ * does NOT quote argv when spawning with `shell: true` on Windows — it joins
+ * the array with spaces — so an npm prefix like `C:\Program Files\…` would be
+ * split into two arguments.
+ */
+export declare function quoteForWindowsShell(arg: string): string;
+/**
+ * How to hand `<cmd> <args…>` to `spawnSync` on this platform.
+ *
+ * On Windows both `npm` and `pnpm` are `.cmd` shims, and since the
+ * CVE-2024-27980 hardening Node refuses to spawn a `.cmd`/`.bat` file without
+ * a shell. Without this the update would fail with EINVAL/ENOENT on every
+ * Windows install — including the pnpm layouts this gate claims to detect.
+ */
+export declare function buildSpawnPlan(cmd: string, args: readonly string[], platform?: NodeJS.Platform): {
+    cmd: string;
+    args: string[];
+    shell: boolean;
+};
 declare function runUpdateCommand(cmd: string, args: string[]): UpdateResult;
 declare function performUpdateCommand(cmd: string, args: string[], runner?: UpdateRunner): UpdateResult;
 declare function performUpdate(command: string, runner?: UpdateRunner): UpdateResult;
+/**
+ * Soft notify when the server says we're below `latestVersion` but still ≥
+ * `minVersion`. Single chalk-yellow line on stderr; never blocks.
+ *
+ * This path fires for EVERY version below latest (the hard gate only fires
+ * below `minVersion`), so it is the far more frequently seen of the two and
+ * must be manager-aware for the same reason the gate is.
+ */
+declare function nudgeUpdateRecommended(decision: VersionCheckResponse, install?: RunningInstall): void;
 /**
  * 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
@@ -101,7 +190,7 @@ declare function performUpdate(command: string, runner?: UpdateRunner): UpdateRe
  */
 declare function enforceUpdateRequired(decision: VersionCheckResponse, deps?: {
     performUpdateString?: (command: string) => UpdateResult;
-    resolvePrefix?: () => string | null;
+    resolveInstall?: () => RunningInstall;
     runner?: UpdateRunner;
     cleanStale?: (prefix: string) => string[];
 }): never;
@@ -126,13 +215,20 @@ export declare const __test__: {
     CLIENT_ID: string;
     ENDPOINT_PATH: string;
     FETCH_TIMEOUT_MS: number;
+    buildPnpmInstallArgv: typeof buildPnpmInstallArgv;
     buildPrefixedInstallArgv: typeof buildPrefixedInstallArgv;
+    buildSpawnPlan: typeof buildSpawnPlan;
     cleanStalePartialInstall: typeof cleanStalePartialInstall;
     enforceUpdateRequired: typeof enforceUpdateRequired;
+    isPnpmManagedPackageDir: typeof isPnpmManagedPackageDir;
     npmPrefixFromPackageDir: typeof npmPrefixFromPackageDir;
+    nudgeUpdateRecommended: typeof nudgeUpdateRecommended;
     performUpdate: typeof performUpdate;
     performUpdateCommand: typeof performUpdateCommand;
+    quoteForWindowsShell: typeof quoteForWindowsShell;
     runUpdateCommand: typeof runUpdateCommand;
+    resolveRunningInstall: typeof resolveRunningInstall;
+    resolveRunningManager: typeof resolveRunningManager;
     resolveRunningPrefix: typeof resolveRunningPrefix;
 };
 export {};