@indigoai-us/hq-cli 5.77.14 → 5.79.0

package/src/lib/narrow-hint-banner.ts

@@ -1,212 +0,0 @@
-/**
- * `narrow-hint-banner` (US-011) — one-time-per-session hint nudging
- * existing all-mode owners to switch to shared-mode sync.
- *
- * Emitted from `hq sync pull --all` and `hq sync now` after the per-target
- * fanout resolves each membership's sync config. Suppressed when:
- *
- *   - the membership is NOT on `syncMode: 'all'` (shared / custom users
- *     have already opted in to narrowing, so there is nothing to nudge),
- *   - the env var `HQ_SYNC_NARROW_HINT=off` is set,
- *   - the per-hqRoot CLI config (`<hqRoot>/.hq/config.json`) has
- *     `syncNarrowHint: 'off'`,
- *   - or the same `{companyUid, level}` pair has already been shown this
- *     process (module-singleton dedupe; the runner imports the same module
- *     once per `hq` invocation so a single invocation prints at most one
- *     banner per company per level).
- *
- * Three escalating levels — `'hint' | 'warning' | 'strict'`. Today's
- * default level is `'hint'`; this release ships the plumbing so a future
- * hq-core-staging release can flip the default to `'warning'` and then
- * `'strict'` without re-touching the call sites.
- *
- * - hint    → dim suggestion to stderr, never blocks.
- * - warning → yellow note to stderr, never blocks.
- * - strict  → red error to stderr; callers are expected to refuse to
- *             proceed unless the operator passes `--mode-all`. The
- *             helper itself never throws or exits — the decision lives at
- *             the call site so tests don't have to stub `process.exit`.
- *
- * The level is selected by the caller (typically from the
- * `HQ_SYNC_NARROW_HINT_LEVEL` env var). See `resolveBannerLevel` for the
- * default-and-override ladder.
- *
- * TODO(hq-core-staging release N+2): bump default level to 'warning'.
- * TODO(hq-core-staging release N+3): bump default level to 'strict' and
- *   wire `--mode-all` as the only opt-out.
- */
-
-import chalk from "chalk";
-import * as fs from "node:fs";
-import * as path from "node:path";
-
-export type BannerLevel = "hint" | "warning" | "strict";
-
-export interface BannerInput {
-  /** Company UID — used to dedupe per-process so each company emits once. */
-  companyUid: string;
-  /** Effective sync mode resolved from `getMembershipSyncConfig`. */
-  syncMode: "shared" | "all" | "custom";
-  /** Escalation level — see file header. */
-  level: BannerLevel;
-}
-
-export interface ShouldShowBannerOpts {
-  /**
-   * Optional hqRoot — when provided, the helper checks
-   * `<hqRoot>/.hq/config.json` for a `syncNarrowHint: 'off'` key in
-   * addition to the env override. Falsy paths skip the file check.
-   */
-  hqRoot?: string;
-  /**
-   * Test seam: override `process.env` lookup. Defaults to
-   * `process.env.HQ_SYNC_NARROW_HINT`.
-   */
-  envValue?: string | undefined;
-  /**
-   * Test seam: override `fs.readFileSync`. Defaults to `node:fs`.
-   */
-  readFile?: (p: string) => string;
-  /** Test seam: override `fs.existsSync`. */
-  existsFile?: (p: string) => boolean;
-}
-
-const SHOWN = new Set<string>();
-
-/**
- * Decides whether a banner should be printed AT ALL — independent of
- * dedupe and `syncMode` gating. Exposed for tests and for the strict-mode
- * call site (which needs to know whether to refuse-to-proceed even if the
- * banner itself is suppressed).
- */
-export function shouldShowBanner(opts: ShouldShowBannerOpts = {}): boolean {
-  const envValue =
-    opts.envValue !== undefined
-      ? opts.envValue
-      : process.env.HQ_SYNC_NARROW_HINT;
-  if (typeof envValue === "string" && envValue.toLowerCase() === "off") {
-    return false;
-  }
-
-  if (opts.hqRoot) {
-    const configPath = path.join(opts.hqRoot, ".hq", "config.json");
-    const exists = opts.existsFile ?? fs.existsSync;
-    const read = opts.readFile ?? ((p: string) => fs.readFileSync(p, "utf-8"));
-    if (exists(configPath)) {
-      try {
-        const cfg = JSON.parse(read(configPath)) as {
-          syncNarrowHint?: unknown;
-        };
-        if (
-          typeof cfg.syncNarrowHint === "string" &&
-          cfg.syncNarrowHint.toLowerCase() === "off"
-        ) {
-          return false;
-        }
-      } catch {
-        // Malformed config is best-effort — fall through and assume "on".
-      }
-    }
-  }
-
-  return true;
-}
-
-/**
- * Resolve the banner level from environment overrides. Defaults to
- * `'hint'`. Recognized values for `HQ_SYNC_NARROW_HINT_LEVEL`:
- * `hint`, `warning`, `strict` (case-insensitive). Unknown values fall
- * back to the default rather than throwing — the env var is operator-
- * facing and a typo shouldn't break a sync.
- */
-export function resolveBannerLevel(
-  envValue: string | undefined = process.env.HQ_SYNC_NARROW_HINT_LEVEL,
-): BannerLevel {
-  if (typeof envValue !== "string") return "hint";
-  const v = envValue.toLowerCase();
-  if (v === "warning" || v === "strict" || v === "hint") return v;
-  return "hint";
-}
-
-/**
- * Returns `true` when the strict-mode rollout has been opted into AND
- * the membership in question is still on `'all'`. Call sites should
- * refuse to proceed (exit non-zero) when this returns true and the
- * operator hasn't passed `--mode-all`.
- */
-export function isStrictRefusal(
-  syncMode: BannerInput["syncMode"],
-  level: BannerLevel,
-): boolean {
-  return level === "strict" && syncMode === "all";
-}
-
-/**
- * Emit a one-time-per-{company,level} banner. Writes to `stderr` by
- * default; tests inject a sink. Idempotent — repeated calls with the
- * same `{companyUid, level}` are no-ops for the lifetime of the
- * process.
- */
-export function emitNarrowHint(
-  input: BannerInput,
-  opts: {
-    hqRoot?: string;
-    write?: (s: string) => void;
-    /** Test seam — overrides `shouldShowBanner` env/config lookups. */
-    showOverride?: boolean;
-  } = {},
-): void {
-  // Only nudge 'all'-mode memberships — shared/custom callers already
-  // opted in to narrowing, so the hint would just be noise.
-  if (input.syncMode !== "all") return;
-
-  const show =
-    opts.showOverride !== undefined
-      ? opts.showOverride
-      : shouldShowBanner({ ...(opts.hqRoot ? { hqRoot: opts.hqRoot } : {}) });
-  if (!show) return;
-
-  const key = `${input.companyUid}:${input.level}`;
-  if (SHOWN.has(key)) return;
-  SHOWN.add(key);
-
-  const write =
-    opts.write ?? ((s: string) => process.stderr.write(s + "\n"));
-
-  if (input.level === "hint") {
-    write(
-      chalk.dim(
-        "Tip: switch to shared-mode sync — fewer files, same visibility. " +
-          "Run `hq sync narrow --dry-run` to preview.",
-      ),
-    );
-    return;
-  }
-
-  if (input.level === "warning") {
-    write(
-      chalk.yellow(
-        "Warning: shared-mode sync is the new default; this membership " +
-          "still pulls everything. Run `hq sync narrow --dry-run` to " +
-          "preview the migration before the next release flips the " +
-          "default to strict.",
-      ),
-    );
-    return;
-  }
-
-  // strict — caller is responsible for refusing to proceed unless
-  // --mode-all was passed. We only emit the message here.
-  write(
-    chalk.red(
-      "Error: shared-mode sync is now strict; pass --mode-all to keep " +
-        "all-mode behavior for this run, or run `hq sync narrow --apply` " +
-        "to migrate this membership.",
-    ),
-  );
-}
-
-/** Test-only helper — clears the per-process dedupe set. */
-export function _resetShownForTests(): void {
-  SHOWN.clear();
-}

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

@@ -1,317 +0,0 @@
-/**
- * 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();
-  });
-});