@indigoai-us/hq-cli 5.17.0 → 5.18.0

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

@@ -0,0 +1,235 @@
+/**
+ * Unit tests for `narrow-hint-banner` (US-011).
+ *
+ * Coverage:
+ *   1. Emits a hint when sync mode is 'all' and not suppressed.
+ *   2. Skips emission for shared/custom memberships.
+ *   3. Dedupes per {companyUid, level} for the process lifetime.
+ *   4. Suppression via HQ_SYNC_NARROW_HINT=off (env).
+ *   5. Suppression via <hqRoot>/.hq/config.json `syncNarrowHint: 'off'`.
+ *   6. Warning + strict level messages.
+ *   7. `isStrictRefusal` only fires for strict + 'all'.
+ *   8. `resolveBannerLevel` parses env values and defaults to 'hint'.
+ */
+
+import { beforeEach, describe, expect, it } from "vitest";
+
+import {
+  _resetShownForTests,
+  emitNarrowHint,
+  isStrictRefusal,
+  resolveBannerLevel,
+  shouldShowBanner,
+} from "./narrow-hint-banner.js";
+
+function makeSink(): { lines: string[]; write: (s: string) => void } {
+  const lines: string[] = [];
+  return {
+    lines,
+    write: (s: string) => {
+      lines.push(s);
+    },
+  };
+}
+
+beforeEach(() => {
+  _resetShownForTests();
+});
+
+describe("emitNarrowHint", () => {
+  it("emits a hint message when sync mode is 'all' and not suppressed", () => {
+    const sink = makeSink();
+    emitNarrowHint(
+      { companyUid: "cmp_acme", syncMode: "all", level: "hint" },
+      { write: sink.write, showOverride: true },
+    );
+    expect(sink.lines).toHaveLength(1);
+    expect(sink.lines[0]).toMatch(/switch to shared-mode sync/i);
+    expect(sink.lines[0]).toMatch(/hq sync narrow --dry-run/);
+  });
+
+  it("skips emission when sync mode is 'shared'", () => {
+    const sink = makeSink();
+    emitNarrowHint(
+      { companyUid: "cmp_acme", syncMode: "shared", level: "hint" },
+      { write: sink.write, showOverride: true },
+    );
+    expect(sink.lines).toHaveLength(0);
+  });
+
+  it("skips emission when sync mode is 'custom'", () => {
+    const sink = makeSink();
+    emitNarrowHint(
+      { companyUid: "cmp_acme", syncMode: "custom", level: "hint" },
+      { write: sink.write, showOverride: true },
+    );
+    expect(sink.lines).toHaveLength(0);
+  });
+
+  it("dedupes per {companyUid, level} across calls", () => {
+    const sink = makeSink();
+    const input = {
+      companyUid: "cmp_acme",
+      syncMode: "all",
+      level: "hint",
+    } as const;
+    emitNarrowHint(input, { write: sink.write, showOverride: true });
+    emitNarrowHint(input, { write: sink.write, showOverride: true });
+    emitNarrowHint(input, { write: sink.write, showOverride: true });
+    expect(sink.lines).toHaveLength(1);
+  });
+
+  it("emits separately for different companies", () => {
+    const sink = makeSink();
+    emitNarrowHint(
+      { companyUid: "cmp_acme", syncMode: "all", level: "hint" },
+      { write: sink.write, showOverride: true },
+    );
+    emitNarrowHint(
+      { companyUid: "cmp_globex", syncMode: "all", level: "hint" },
+      { write: sink.write, showOverride: true },
+    );
+    expect(sink.lines).toHaveLength(2);
+  });
+
+  it("emits separately for the same company at a different level", () => {
+    const sink = makeSink();
+    emitNarrowHint(
+      { companyUid: "cmp_acme", syncMode: "all", level: "hint" },
+      { write: sink.write, showOverride: true },
+    );
+    emitNarrowHint(
+      { companyUid: "cmp_acme", syncMode: "all", level: "warning" },
+      { write: sink.write, showOverride: true },
+    );
+    expect(sink.lines).toHaveLength(2);
+  });
+
+  it("suppresses emission when showOverride=false (suppression path)", () => {
+    const sink = makeSink();
+    emitNarrowHint(
+      { companyUid: "cmp_acme", syncMode: "all", level: "hint" },
+      { write: sink.write, showOverride: false },
+    );
+    expect(sink.lines).toHaveLength(0);
+  });
+
+  it("emits the warning-level message", () => {
+    const sink = makeSink();
+    emitNarrowHint(
+      { companyUid: "cmp_acme", syncMode: "all", level: "warning" },
+      { write: sink.write, showOverride: true },
+    );
+    expect(sink.lines).toHaveLength(1);
+    expect(sink.lines[0]).toMatch(/shared-mode sync is the new default/i);
+  });
+
+  it("emits the strict-level message (does NOT throw or exit)", () => {
+    const sink = makeSink();
+    expect(() =>
+      emitNarrowHint(
+        { companyUid: "cmp_acme", syncMode: "all", level: "strict" },
+        { write: sink.write, showOverride: true },
+      ),
+    ).not.toThrow();
+    expect(sink.lines).toHaveLength(1);
+    expect(sink.lines[0]).toMatch(/--mode-all/);
+  });
+});
+
+describe("shouldShowBanner", () => {
+  it("returns true with no overrides", () => {
+    expect(shouldShowBanner({ envValue: undefined })).toBe(true);
+  });
+
+  it("returns false when env value is 'off' (case-insensitive)", () => {
+    expect(shouldShowBanner({ envValue: "off" })).toBe(false);
+    expect(shouldShowBanner({ envValue: "OFF" })).toBe(false);
+  });
+
+  it("returns true for env values other than 'off'", () => {
+    expect(shouldShowBanner({ envValue: "on" })).toBe(true);
+    expect(shouldShowBanner({ envValue: "" })).toBe(true);
+  });
+
+  it("returns false when .hq/config.json sets syncNarrowHint='off'", () => {
+    const exists = (_p: string) => true;
+    const read = (_p: string) => JSON.stringify({ syncNarrowHint: "off" });
+    expect(
+      shouldShowBanner({
+        envValue: undefined,
+        hqRoot: "/tmp/hq",
+        existsFile: exists,
+        readFile: read,
+      }),
+    ).toBe(false);
+  });
+
+  it("returns true when .hq/config.json has no syncNarrowHint key", () => {
+    const exists = (_p: string) => true;
+    const read = (_p: string) =>
+      JSON.stringify({ activeCompany: "acme" });
+    expect(
+      shouldShowBanner({
+        envValue: undefined,
+        hqRoot: "/tmp/hq",
+        existsFile: exists,
+        readFile: read,
+      }),
+    ).toBe(true);
+  });
+
+  it("tolerates malformed config.json (returns true)", () => {
+    const exists = (_p: string) => true;
+    const read = (_p: string) => "{not json";
+    expect(
+      shouldShowBanner({
+        envValue: undefined,
+        hqRoot: "/tmp/hq",
+        existsFile: exists,
+        readFile: read,
+      }),
+    ).toBe(true);
+  });
+
+  it("returns true when config file does not exist", () => {
+    expect(
+      shouldShowBanner({
+        envValue: undefined,
+        hqRoot: "/tmp/hq",
+        existsFile: () => false,
+        readFile: () => {
+          throw new Error("should not be called");
+        },
+      }),
+    ).toBe(true);
+  });
+});
+
+describe("isStrictRefusal", () => {
+  it("returns true only for level=strict + syncMode=all", () => {
+    expect(isStrictRefusal("all", "strict")).toBe(true);
+    expect(isStrictRefusal("shared", "strict")).toBe(false);
+    expect(isStrictRefusal("custom", "strict")).toBe(false);
+    expect(isStrictRefusal("all", "warning")).toBe(false);
+    expect(isStrictRefusal("all", "hint")).toBe(false);
+  });
+});
+
+describe("resolveBannerLevel", () => {
+  it("defaults to 'hint' when env is undefined", () => {
+    expect(resolveBannerLevel(undefined)).toBe("hint");
+  });
+
+  it("parses recognized values (case-insensitive)", () => {
+    expect(resolveBannerLevel("hint")).toBe("hint");
+    expect(resolveBannerLevel("warning")).toBe("warning");
+    expect(resolveBannerLevel("strict")).toBe("strict");
+    expect(resolveBannerLevel("WARNING")).toBe("warning");
+  });
+
+  it("falls back to 'hint' for unknown values", () => {
+    expect(resolveBannerLevel("loud")).toBe("hint");
+    expect(resolveBannerLevel("")).toBe("hint");
+  });
+});

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

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