@indigoai-us/hq-cli 5.77.7 → 5.77.9

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

@@ -0,0 +1,317 @@
+/**
+ * Unit tests for `plan-limit-nag` (US-016).
+ *
+ * Coverage:
+ *   1. Warning renders when ≥80% metadata present; absent → no output.
+ *   2. Malformed planLimits ignored (no output, no throw).
+ *   3. Once-per-session: second emit prints nothing.
+ *   4. Over-limit boxed notice; same-day state suppresses; >24h re-prints.
+ *   5. HQ_NO_PLAN_LIMIT_NAG=1 disables all output.
+ *   6. emit never throws even when statePath unwritable.
+ *   7. Exit-code neutrality: emit does not touch process.exitCode.
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import {
+  PLAN_LIMIT_UPGRADE_URL,
+  _resetForTests,
+  emitPlanLimitNag,
+  recordPlanLimitStatus,
+} from "./plan-limit-nag.js";
+
+function makeSink(): { lines: string[]; write: (s: string) => void } {
+  const lines: string[] = [];
+  return {
+    lines,
+    write: (s: string) => {
+      lines.push(s);
+    },
+  };
+}
+
+function tmpStatePath(): string {
+  return path.join(
+    os.tmpdir(),
+    `hq-plan-limit-nag-test-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}.json`,
+  );
+}
+
+/**
+ * Portable unwritable statePath: join under a plain FILE so
+ * mkdirSync/writeFileSync/readFileSync fail immediately with ENOTDIR
+ * on every platform (unlike /proc paths, which hang on Linux procfs).
+ */
+function unwritableStatePath(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-nag-"));
+  const file = path.join(dir, "not-a-dir");
+  fs.writeFileSync(file, "x");
+  return path.join(file, "x", "plan-limit-nag.json");
+}
+
+const ENV_KEY = "HQ_NO_PLAN_LIMIT_NAG";
+let prevEnv: string | undefined;
+
+beforeEach(() => {
+  _resetForTests();
+  prevEnv = process.env[ENV_KEY];
+  delete process.env[ENV_KEY];
+});
+
+afterEach(() => {
+  if (prevEnv === undefined) {
+    delete process.env[ENV_KEY];
+  } else {
+    process.env[ENV_KEY] = prevEnv;
+  }
+  _resetForTests();
+});
+
+describe("recordPlanLimitStatus + emitPlanLimitNag (warning path)", () => {
+  it("renders a one-line warning when planLimits has a ≥80% entry", () => {
+    const sink = makeSink();
+    recordPlanLimitStatus({
+      ok: true,
+      planLimits: {
+        users: { used: 9, limit: 10, over: false },
+      },
+    });
+    emitPlanLimitNag({ write: sink.write, statePath: tmpStatePath() });
+    expect(sink.lines).toHaveLength(1);
+    expect(sink.lines[0]).toMatch(/HQ free plan/i);
+    expect(sink.lines[0]).toMatch(/users at 9\/10 \(90%\)/);
+    expect(sink.lines[0]).toContain(PLAN_LIMIT_UPGRADE_URL);
+  });
+
+  it("produces no output when planLimits metadata is absent", () => {
+    const sink = makeSink();
+    recordPlanLimitStatus({ ok: true, items: [] });
+    emitPlanLimitNag({ write: sink.write, statePath: tmpStatePath() });
+    expect(sink.lines).toHaveLength(0);
+  });
+
+  it("produces no output when recordPlanLimitStatus was never called", () => {
+    const sink = makeSink();
+    emitPlanLimitNag({ write: sink.write, statePath: tmpStatePath() });
+    expect(sink.lines).toHaveLength(0);
+  });
+
+  it("lists the worst resource when multiple ≥80% entries exist", () => {
+    const sink = makeSink();
+    recordPlanLimitStatus({
+      planLimits: {
+        users: { used: 8, limit: 10, over: false },
+        secrets: { used: 19, limit: 20, over: false },
+      },
+    });
+    emitPlanLimitNag({ write: sink.write, statePath: tmpStatePath() });
+    expect(sink.lines).toHaveLength(1);
+    expect(sink.lines[0]).toMatch(/secrets at 19\/20/);
+  });
+});
+
+describe("malformed planLimits", () => {
+  it("ignores wrong types — no output, no throw", () => {
+    const sink = makeSink();
+    expect(() =>
+      recordPlanLimitStatus({
+        planLimits: {
+          users: { used: "9", limit: 10, over: false },
+          secrets: { used: 5, limit: "10", over: true },
+          agents: null,
+          integrations: "nope",
+        },
+      }),
+    ).not.toThrow();
+    expect(() =>
+      emitPlanLimitNag({ write: sink.write, statePath: tmpStatePath() }),
+    ).not.toThrow();
+    expect(sink.lines).toHaveLength(0);
+  });
+
+  it("ignores non-object planLimits", () => {
+    const sink = makeSink();
+    recordPlanLimitStatus({ planLimits: "not-an-object" });
+    recordPlanLimitStatus({ planLimits: [1, 2, 3] });
+    recordPlanLimitStatus({ planLimits: null });
+    recordPlanLimitStatus(null);
+    recordPlanLimitStatus("string");
+    emitPlanLimitNag({ write: sink.write, statePath: tmpStatePath() });
+    expect(sink.lines).toHaveLength(0);
+  });
+
+  it("accepts only well-formed entries and still emits when mixed", () => {
+    const sink = makeSink();
+    recordPlanLimitStatus({
+      planLimits: {
+        bad: { used: "x", limit: 1, over: false },
+        users: { used: 9, limit: 10, over: false },
+      },
+    });
+    emitPlanLimitNag({ write: sink.write, statePath: tmpStatePath() });
+    expect(sink.lines).toHaveLength(1);
+    expect(sink.lines[0]).toMatch(/users at 9\/10/);
+  });
+});
+
+describe("once-per-session dedupe", () => {
+  it("second emit prints nothing for the warning path", () => {
+    const sink = makeSink();
+    const statePath = tmpStatePath();
+    recordPlanLimitStatus({
+      planLimits: { users: { used: 9, limit: 10, over: false } },
+    });
+    emitPlanLimitNag({ write: sink.write, statePath });
+    emitPlanLimitNag({ write: sink.write, statePath });
+    expect(sink.lines).toHaveLength(1);
+  });
+});
+
+describe("over-limit boxed notice", () => {
+  it("prints a boxed over-limit notice listing over resources", () => {
+    const sink = makeSink();
+    const statePath = tmpStatePath();
+    recordPlanLimitStatus({
+      planLimits: {
+        users: { used: 11, limit: 10, over: true },
+        secrets: { used: 5, limit: 20, over: false },
+      },
+      requiredPlan: "agents-500",
+    });
+    emitPlanLimitNag({
+      write: sink.write,
+      statePath,
+      now: () => new Date("2026-03-01T12:00:00.000Z"),
+    });
+    expect(sink.lines).toHaveLength(1);
+    const out = sink.lines[0] ?? "";
+    expect(out).toMatch(/plan limit exceeded/i);
+    expect(out).toMatch(/users:\s*11\/10/);
+    expect(out).toContain(PLAN_LIMIT_UPGRADE_URL);
+    expect(out).toMatch(/[┌└│─]/);
+    // Non-over resources should not appear in the over box resource list.
+    expect(out).not.toMatch(/secrets:\s*5\/20/);
+  });
+
+  it("second emit same day (fresh shownAt in statePath) prints nothing", () => {
+    const sink = makeSink();
+    const statePath = tmpStatePath();
+    const now = new Date("2026-03-01T12:00:00.000Z");
+    fs.writeFileSync(
+      statePath,
+      JSON.stringify({ shownAt: now.getTime() - 60 * 60 * 1000 }),
+    );
+    recordPlanLimitStatus({
+      planLimits: { users: { used: 11, limit: 10, over: true } },
+    });
+    emitPlanLimitNag({ write: sink.write, statePath, now: () => now });
+    expect(sink.lines).toHaveLength(0);
+  });
+
+  it("shownAt older than 24h prints again", () => {
+    const sink = makeSink();
+    const statePath = tmpStatePath();
+    const now = new Date("2026-03-02T13:00:00.000Z");
+    fs.writeFileSync(
+      statePath,
+      JSON.stringify({
+        shownAt: now.getTime() - 25 * 60 * 60 * 1000,
+      }),
+    );
+    recordPlanLimitStatus({
+      planLimits: { users: { used: 11, limit: 10, over: true } },
+    });
+    emitPlanLimitNag({ write: sink.write, statePath, now: () => now });
+    expect(sink.lines).toHaveLength(1);
+    expect(sink.lines[0]).toMatch(/plan limit exceeded/i);
+  });
+
+  it("session-dedupes over notice even without state file", () => {
+    const sink = makeSink();
+    // Unwritable parent: skip persistence but still session-dedupe.
+    const statePath = unwritableStatePath();
+    recordPlanLimitStatus({
+      planLimits: { users: { used: 11, limit: 10, over: true } },
+    });
+    emitPlanLimitNag({
+      write: sink.write,
+      statePath,
+      now: () => new Date("2026-03-01T12:00:00.000Z"),
+    });
+    emitPlanLimitNag({
+      write: sink.write,
+      statePath,
+      now: () => new Date("2026-03-01T12:00:00.000Z"),
+    });
+    expect(sink.lines).toHaveLength(1);
+  });
+});
+
+describe("env off-switch", () => {
+  it("HQ_NO_PLAN_LIMIT_NAG=1 produces no output", () => {
+    process.env[ENV_KEY] = "1";
+    const sink = makeSink();
+    recordPlanLimitStatus({
+      planLimits: {
+        users: { used: 11, limit: 10, over: true },
+      },
+    });
+    emitPlanLimitNag({ write: sink.write, statePath: tmpStatePath() });
+    expect(sink.lines).toHaveLength(0);
+  });
+});
+
+describe("resilience + exit-code neutrality", () => {
+  it("emit never throws even when statePath is unwritable", () => {
+    const sink = makeSink();
+    const statePath = unwritableStatePath();
+    recordPlanLimitStatus({
+      planLimits: { users: { used: 12, limit: 10, over: true } },
+    });
+    expect(() =>
+      emitPlanLimitNag({
+        write: sink.write,
+        statePath,
+        now: () => new Date("2026-03-01T12:00:00.000Z"),
+      }),
+    ).not.toThrow();
+    // Still attempted to print (write may succeed even if state write fails).
+    expect(sink.lines.length).toBeGreaterThanOrEqual(0);
+  });
+
+  it("does not touch process.exitCode", () => {
+    const prev = process.exitCode;
+    process.exitCode = 0;
+    try {
+      const sink = makeSink();
+      recordPlanLimitStatus({
+        planLimits: { users: { used: 9, limit: 10, over: false } },
+      });
+      emitPlanLimitNag({ write: sink.write, statePath: tmpStatePath() });
+      expect(process.exitCode).toBe(0);
+
+      process.exitCode = 1;
+      _resetForTests();
+      recordPlanLimitStatus({
+        planLimits: { users: { used: 11, limit: 10, over: true } },
+      });
+      emitPlanLimitNag({
+        write: sink.write,
+        statePath: tmpStatePath(),
+        now: () => new Date("2026-04-01T00:00:00.000Z"),
+      });
+      expect(process.exitCode).toBe(1);
+    } finally {
+      process.exitCode = prev;
+    }
+  });
+
+  it("recordPlanLimitStatus never throws on garbage input", () => {
+    expect(() => recordPlanLimitStatus(undefined)).not.toThrow();
+    expect(() => recordPlanLimitStatus(42)).not.toThrow();
+    expect(() => recordPlanLimitStatus([])).not.toThrow();
+  });
+});

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