@indigoai-us/hq-cli 5.77.8 → 5.77.9

package/src/lib/plan-limit-nag.ts

@@ -0,0 +1,264 @@
+/**
+ * `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;
+
+export interface PlanLimitEntry {
+  used: number;
+  limit: number;
+  over: boolean;
+}
+
+/** Validated map of resource key → entry. */
+export type PlanLimitsMap = Record<string, PlanLimitEntry>;
+
+interface LastSeenStatus {
+  limits: PlanLimitsMap;
+  anyOver: boolean;
+}
+
+interface NagStateFile {
+  shownAt: number;
+}
+
+/** Module-level last-seen cell — overwritten by each successful parse. */
+let lastSeen: LastSeenStatus | null = 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(): string {
+  return path.join(os.homedir(), ".hq", "plan-limit-nag.json");
+}
+
+function isOptedOut(): boolean {
+  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: unknown): PlanLimitEntry | null {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  const rec = value as Record<string, unknown>;
+  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: unknown): PlanLimitsMap | null {
+  if (body === null || typeof body !== "object" || Array.isArray(body)) {
+    return null;
+  }
+  const planLimits = (body as Record<string, unknown>).planLimits;
+  if (
+    planLimits === null ||
+    typeof planLimits !== "object" ||
+    Array.isArray(planLimits)
+  ) {
+    return null;
+  }
+
+  const out: PlanLimitsMap = {};
+  let anyValid = false;
+  for (const [key, value] of Object.entries(
+    planLimits as Record<string, unknown>,
+  )) {
+    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: unknown): void {
+  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: PlanLimitEntry): number {
+  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: PlanLimitsMap,
+): { key: string; entry: PlanLimitEntry } | null {
+  let best: { key: string; entry: PlanLimitEntry; ratio: number } | null =
+    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: PlanLimitEntry): string {
+  if (entry.limit <= 0) return entry.used > 0 ? "∞" : "0%";
+  return `${Math.round((entry.used / entry.limit) * 100)}%`;
+}
+
+function formatEntryLine(key: string, entry: PlanLimitEntry): string {
+  return `${key} at ${entry.used}/${entry.limit} (${formatPct(entry)})`;
+}
+
+function readShownAt(statePath: string): number | null {
+  try {
+    const raw = fs.readFileSync(statePath, "utf-8");
+    const parsed = JSON.parse(raw) as Partial<NagStateFile>;
+    if (typeof parsed.shownAt !== "number" || !Number.isFinite(parsed.shownAt)) {
+      return null;
+    }
+    return parsed.shownAt;
+  } catch {
+    return null;
+  }
+}
+
+function writeShownAt(statePath: string, shownAt: number): void {
+  try {
+    fs.mkdirSync(path.dirname(statePath), { recursive: true });
+    const payload: NagStateFile = { shownAt };
+    fs.writeFileSync(statePath, JSON.stringify(payload));
+  } catch {
+    // best-effort; never break the CLI on cache write failure
+  }
+}
+
+function withinDayWindow(shownAt: number, nowMs: number): boolean {
+  return nowMs - shownAt < DAY_MS;
+}
+
+function buildOverBox(overEntries: Array<[string, PlanLimitEntry]>): string {
+  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: {
+    write?: (s: string) => void;
+    now?: () => Date;
+    statePath?: string;
+  } = {},
+): void {
+  try {
+    if (isOptedOut()) return;
+    if (lastSeen === null) return;
+
+    const write =
+      opts.write ?? ((s: string) => 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(): void {
+  lastSeen = null;
+  warningShownThisSession = false;
+  overShownThisSession = false;
+}

package/src/main.ts

@@ -76,6 +76,7 @@ import {
 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;
@@ -353,6 +354,9 @@ export async function runCli(): Promise<void> {
       process.exitCode = 1;
     }
   } 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/src/utils/vault-api.test.ts

@@ -1,3 +1,5 @@
+import * as os from 'node:os';
+import * as path from 'node:path';
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 
 vi.mock('../sentry.js', () => ({
@@ -9,6 +11,17 @@ import { getCompanyUid, getEntityUid, resolveCallerPersonUid, vaultApiFetch } fr
 import { isAuthError } from './auth-error.js';
 import { isCompanySelectionError } from './company-selection-error.js';
 import { isExpectedUserError } from './expected-cli-error.js';
+import {
+  _resetForTests,
+  emitPlanLimitNag,
+} from '../lib/plan-limit-nag.js';
+
+function tmpNagStatePath(label: string): string {
+  return path.join(
+    os.tmpdir(),
+    `hq-plan-limit-vault-api-${label}-${process.pid}-${Date.now()}.json`,
+  );
+}
 
 const fetchMock = vi.fn();
 const originalFetch = globalThis.fetch;
@@ -23,10 +36,12 @@ function mockResponse(status: number, body: unknown): Response {
 beforeEach(() => {
   fetchMock.mockReset();
   globalThis.fetch = fetchMock as unknown as typeof fetch;
+  _resetForTests();
 });
 
 afterEach(() => {
   globalThis.fetch = originalFetch;
+  _resetForTests();
 });
 
 describe('resolveCallerPersonUid', () => {
@@ -395,3 +410,127 @@ describe('vaultApiFetch abort signals', () => {
     );
   });
 });
+
+describe('vaultApiFetch plan-limit peek (US-016, no-clone body drain)', () => {
+  it('JSON ok response is still fully readable by the caller after peek', async () => {
+    const payload = { ok: true, items: [1, 2, 3], planLimits: undefined };
+    fetchMock.mockResolvedValueOnce(mockResponse(200, payload));
+
+    const res = await vaultApiFetch({ token: 'tok', path: '/v1/items' });
+    expect(res.ok).toBe(true);
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body).toEqual(payload);
+  });
+
+  it('records planLimits payload (observable via emitPlanLimitNag)', async () => {
+    fetchMock.mockResolvedValueOnce(
+      mockResponse(200, {
+        ok: true,
+        planLimits: {
+          users: { used: 9, limit: 10, over: false },
+        },
+      }),
+    );
+
+    const res = await vaultApiFetch({ token: 'tok', path: '/v1/items' });
+    // Caller can still read the body.
+    await expect(res.json()).resolves.toMatchObject({ ok: true });
+
+    const lines: string[] = [];
+    emitPlanLimitNag({
+      write: (s) => {
+        lines.push(s);
+      },
+      statePath: tmpNagStatePath('recorded'),
+    });
+    expect(lines).toHaveLength(1);
+    expect(lines[0]).toMatch(/HQ free plan/i);
+    expect(lines[0]).toMatch(/users at 9\/10/);
+  });
+
+  it('non-JSON content-type body is not buffered (response returned untouched)', async () => {
+    const original = new Response(new Uint8Array([1, 2, 3, 4]), {
+      status: 200,
+      statusText: 'OK',
+      headers: { 'Content-Type': 'application/octet-stream' },
+    });
+    fetchMock.mockResolvedValueOnce(original);
+
+    const res = await vaultApiFetch({ token: 'tok', path: '/v1/download' });
+    // Same object identity — peek must not re-wrap non-JSON bodies.
+    expect(res).toBe(original);
+    const buf = new Uint8Array(await res.arrayBuffer());
+    expect(Array.from(buf)).toEqual([1, 2, 3, 4]);
+  });
+
+  it('malformed JSON does not throw and body is still readable', async () => {
+    const raw = '{not-valid-json';
+    fetchMock.mockResolvedValueOnce(
+      new Response(raw, {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      }),
+    );
+
+    let res: Response;
+    await expect(
+      (async () => {
+        res = await vaultApiFetch({ token: 'tok', path: '/v1/broken' });
+        return res;
+      })(),
+    ).resolves.toBeDefined();
+
+    expect(res!.ok).toBe(true);
+    await expect(res!.text()).resolves.toBe(raw);
+
+    // Malformed body must not record plan limits.
+    const lines: string[] = [];
+    emitPlanLimitNag({
+      write: (s) => {
+        lines.push(s);
+      },
+      statePath: tmpNagStatePath('malformed'),
+    });
+    expect(lines).toHaveLength(0);
+  });
+
+  it('non-ok responses are returned untouched', async () => {
+    const original = mockResponse(404, { error: 'not found' });
+    fetchMock.mockResolvedValueOnce(original);
+
+    const res = await vaultApiFetch({ token: 'tok', path: '/v1/missing' });
+    expect(res).toBe(original);
+    expect(res.status).toBe(404);
+    await expect(res.json()).resolves.toEqual({ error: 'not found' });
+  });
+
+  it('accepts application/*+json content-types for peek', async () => {
+    fetchMock.mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({
+          planLimits: { seats: { used: 8, limit: 10, over: false } },
+        }),
+        {
+          status: 200,
+          headers: { 'Content-Type': 'application/vnd.api+json' },
+        },
+      ),
+    );
+
+    const res = await vaultApiFetch({ token: 'tok', path: '/v1/vnd' });
+    await expect(res.json()).resolves.toMatchObject({
+      planLimits: { seats: { used: 8, limit: 10, over: false } },
+    });
+
+    const lines: string[] = [];
+    emitPlanLimitNag({
+      write: (s) => {
+        lines.push(s);
+      },
+      statePath: tmpNagStatePath('vnd'),
+    });
+    expect(lines).toHaveLength(1);
+    expect(lines[0]).toMatch(/seats at 8\/10/);
+  });
+});

package/src/utils/vault-api.ts

@@ -2,6 +2,7 @@ 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';
 
 export interface VaultApiOptions {
   token: string;
@@ -12,6 +13,64 @@ export interface VaultApiOptions {
   signal?: AbortSignal;
 }
 
+/**
+ * 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: Response): Promise<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: ArrayBuffer;
+    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) as unknown);
+      } 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: VaultApiOptions): Promise<Response> {
   const url = new URL(opts.path, DEFAULT_VAULT_API_URL);
   if (opts.query) {
@@ -43,8 +102,9 @@ export async function vaultApiFetch(opts: VaultApiOptions): Promise<Response> {
       level: "warning",
       data: { url: safeUrl, status: response.status },
     });
+    return response;
   }
-  return response;
+  return peekPlanLimitStatus(response);
 }
 
 /**