@indigoai-us/hq-cli 5.17.0 → 5.18.1

package/src/commands/cloud.pull-all.test.ts

@@ -14,9 +14,12 @@
  *   5. Empty memberships AND no person entity → no sync calls, clean result.
  *   6. Multiple person entities → canonical pick (oldest createdAt, uid tiebreak).
  *   7. hqRoot is forwarded verbatim to every sync() call.
+ *   8. US-011 — narrow-hint banner emits per all-mode membership.
+ *   9. US-011 — strict-mode refuses all-mode legs without --mode-all.
+ *   10. US-011 — strict-mode + --mode-all proceeds.
  */
 
-import { describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import {
   pullAll,
@@ -25,6 +28,7 @@ import {
   type SyncCallOptions,
   type SyncCallResult,
 } from "./cloud.js";
+import { _resetShownForTests } from "../lib/narrow-hint-banner.js";
 
 // ── Helpers ─────────────────────────────────────────────────────────────────
 
@@ -299,6 +303,171 @@ describe("pullAll", () => {
     expect(sync.calls[0].journalSlug).toBe("personal");
   });
 
+  // ── 8/9/10. US-011 narrow-hint banner ─────────────────────────────────────
+
+  describe("narrow-hint banner (US-011)", () => {
+    let stderrSpy: ReturnType<typeof vi.spyOn>;
+    let captured: string[];
+
+    beforeEach(() => {
+      _resetShownForTests();
+      captured = [];
+      stderrSpy = vi
+        .spyOn(process.stderr, "write")
+        .mockImplementation((chunk: string | Uint8Array) => {
+          captured.push(typeof chunk === "string" ? chunk : chunk.toString());
+          return true;
+        });
+    });
+
+    afterEach(() => {
+      stderrSpy.mockRestore();
+      delete process.env.HQ_SYNC_NARROW_HINT;
+      delete process.env.HQ_SYNC_NARROW_HINT_LEVEL;
+    });
+
+    function makeVaultClientWithSyncConfig(opts: {
+      memberships: Array<{ companyUid: string; membershipKey: string }>;
+      syncModes: Record<string, "shared" | "all" | "custom">;
+      entitiesBySlug?: Record<string, { slug: string; name?: string }>;
+    }): PullAllVaultClient {
+      return {
+        listMyMemberships: vi.fn().mockResolvedValue(opts.memberships),
+        listPersonEntities: vi.fn().mockResolvedValue([]),
+        getEntity: vi
+          .fn()
+          .mockImplementation(async (uid: string) =>
+            opts.entitiesBySlug?.[uid] ?? null,
+          ),
+        getMembershipSyncConfig: vi
+          .fn()
+          .mockImplementation(async (membershipKey: string) => {
+            const m = opts.memberships.find(
+              (m) => m.membershipKey === membershipKey,
+            );
+            const companyUid = m?.companyUid ?? "";
+            return {
+              membershipId: membershipKey,
+              syncMode: opts.syncModes[companyUid] ?? "all",
+            };
+          }),
+      };
+    }
+
+    it("emits one hint per all-mode membership and skips shared/custom", async () => {
+      const vaultClient = makeVaultClientWithSyncConfig({
+        memberships: [
+          { companyUid: "cmp_acme", membershipKey: "psn_1#cmp_acme" },
+          { companyUid: "cmp_globex", membershipKey: "psn_1#cmp_globex" },
+          { companyUid: "cmp_init", membershipKey: "psn_1#cmp_init" },
+        ],
+        syncModes: {
+          cmp_acme: "all",
+          cmp_globex: "shared",
+          cmp_init: "custom",
+        },
+        entitiesBySlug: {
+          cmp_acme: { slug: "acme" },
+          cmp_globex: { slug: "globex" },
+          cmp_init: { slug: "init" },
+        },
+      });
+      const sync = makeSyncSpy();
+
+      const result = await pullAll(
+        { hqRoot: "/tmp/hq", narrowHintLevel: "hint" },
+        { vaultClient, sync: sync.fn },
+      );
+
+      expect(result.errors).toEqual([]);
+      expect(result.attempted).toBe(3);
+      // sync ran for all three (no strict refusal at 'hint' level)
+      expect(sync.calls).toHaveLength(3);
+
+      const joined = captured.join("");
+      expect(joined).toMatch(/switch to shared-mode sync/i);
+      // exactly one banner line — only cmp_acme is on 'all'
+      const bannerLines = captured.filter((c) => /shared-mode sync/i.test(c));
+      expect(bannerLines).toHaveLength(1);
+    });
+
+    it("strict-mode refuses all-mode legs and short-circuits sync()", async () => {
+      const vaultClient = makeVaultClientWithSyncConfig({
+        memberships: [
+          { companyUid: "cmp_acme", membershipKey: "psn_1#cmp_acme" },
+          { companyUid: "cmp_globex", membershipKey: "psn_1#cmp_globex" },
+        ],
+        syncModes: {
+          cmp_acme: "all",
+          cmp_globex: "shared",
+        },
+        entitiesBySlug: {
+          cmp_acme: { slug: "acme" },
+          cmp_globex: { slug: "globex" },
+        },
+      });
+      const sync = makeSyncSpy();
+
+      const result = await pullAll(
+        { hqRoot: "/tmp/hq", narrowHintLevel: "strict" },
+        { vaultClient, sync: sync.fn },
+      );
+
+      // acme refused (no sync() call), globex still synced
+      expect(sync.calls.map((c) => c.company)).toEqual(["cmp_globex"]);
+      expect(result.errors).toEqual([
+        {
+          company: "acme",
+          message: expect.stringContaining("Refusing to pull all-mode"),
+        },
+      ]);
+    });
+
+    it("strict-mode + modeAllOverride lets all-mode legs proceed", async () => {
+      const vaultClient = makeVaultClientWithSyncConfig({
+        memberships: [
+          { companyUid: "cmp_acme", membershipKey: "psn_1#cmp_acme" },
+        ],
+        syncModes: { cmp_acme: "all" },
+        entitiesBySlug: { cmp_acme: { slug: "acme" } },
+      });
+      const sync = makeSyncSpy();
+
+      const result = await pullAll(
+        {
+          hqRoot: "/tmp/hq",
+          narrowHintLevel: "strict",
+          modeAllOverride: true,
+        },
+        { vaultClient, sync: sync.fn },
+      );
+
+      expect(sync.calls).toHaveLength(1);
+      expect(result.errors).toEqual([]);
+    });
+
+    it("HQ_SYNC_NARROW_HINT=off suppresses the banner", async () => {
+      process.env.HQ_SYNC_NARROW_HINT = "off";
+      const vaultClient = makeVaultClientWithSyncConfig({
+        memberships: [
+          { companyUid: "cmp_acme", membershipKey: "psn_1#cmp_acme" },
+        ],
+        syncModes: { cmp_acme: "all" },
+        entitiesBySlug: { cmp_acme: { slug: "acme" } },
+      });
+      const sync = makeSyncSpy();
+
+      await pullAll(
+        { hqRoot: "/tmp/hq", narrowHintLevel: "hint" },
+        { vaultClient, sync: sync.fn },
+      );
+
+      const joined = captured.join("");
+      expect(joined).not.toMatch(/switch to shared-mode sync/i);
+      expect(sync.calls).toHaveLength(1);
+    });
+  });
+
   // ── 7. hqRoot passthrough ─────────────────────────────────────────────────
 
   it("forwards hqRoot verbatim to every sync() call", async () => {

package/src/commands/cloud.pull-per-company.test.ts

@@ -0,0 +1,188 @@
+/**
+ * Unit tests for `resolvePerCompanyPullPlan` — the helper extracted from the
+ * `hq sync pull --company <slug>` action handler so the US-011 banner +
+ * strict-refusal wiring can be exercised without commander / a real
+ * VaultClient (US-011 fix, 2026-05-21).
+ *
+ * The action handler itself stays a thin orchestrator. These tests cover
+ * the membership-resolution decision tree, which is the part that broke
+ * on the pre-fix code path (banner silently never fired because the
+ * handler never looked up the sync-config).
+ *
+ * Coverage:
+ *   1. Undefined targetCompany short-circuits to no-op.
+ *   2. Direct UID match returns mode + companyUid.
+ *   3. Direct membershipKey match returns mode + companyUid.
+ *   4. Slug match via entity.get returns mode + companyUid.
+ *   5. listMyMemberships error degrades silently to no resolution.
+ *   6. getMembershipSyncConfig error degrades to undefined mode but keeps companyUid.
+ *   7. Slug iteration stops at first match (doesn't fan out to all entities).
+ *   8. No matching membership returns no resolution.
+ */
+
+import { describe, expect, it, vi } from "vitest";
+import {
+  resolvePerCompanyPullPlan,
+  type PerCompanyPullResolveClient,
+} from "./cloud.js";
+
+function makeClient(opts: {
+  memberships?: Array<{ companyUid: string; membershipKey: string }>;
+  syncConfigs?: Record<string, { syncMode: "shared" | "all" | "custom" }>;
+  entities?: Record<string, { slug?: string }>;
+  failListMemberships?: boolean;
+  failSyncConfigFor?: Set<string>;
+  failEntityFor?: Set<string>;
+}): PerCompanyPullResolveClient & {
+  _entityCalls: () => string[];
+} {
+  const entityCalls: string[] = [];
+  return {
+    listMyMemberships: vi.fn(async () => {
+      if (opts.failListMemberships) throw new Error("listMyMemberships boom");
+      return opts.memberships ?? [];
+    }),
+    getMembershipSyncConfig: vi.fn(async (key: string) => {
+      if (opts.failSyncConfigFor?.has(key))
+        throw new Error(`getMembershipSyncConfig boom for ${key}`);
+      const cfg = (opts.syncConfigs ?? {})[key];
+      if (!cfg) throw new Error(`no fake config for ${key}`);
+      return cfg;
+    }),
+    entity: {
+      get: vi.fn(async (uid: string) => {
+        entityCalls.push(uid);
+        if (opts.failEntityFor?.has(uid))
+          throw new Error(`entity.get boom for ${uid}`);
+        return (opts.entities ?? {})[uid] ?? {};
+      }),
+    },
+    _entityCalls: () => entityCalls,
+  };
+}
+
+describe("resolvePerCompanyPullPlan (US-011 per-company pull fix)", () => {
+  it("returns undefined+undefined when targetCompany is undefined", async () => {
+    const client = makeClient({});
+    const result = await resolvePerCompanyPullPlan(client, undefined);
+    expect(result.resolvedCompanyUid).toBeUndefined();
+    expect(result.resolvedMode).toBeUndefined();
+    // Should not call any API — short-circuit.
+    expect(client.listMyMemberships).not.toHaveBeenCalled();
+  });
+
+  it("matches by direct companyUid and returns the live syncMode", async () => {
+    const client = makeClient({
+      memberships: [
+        { companyUid: "cmp_personal", membershipKey: "mbr_personal" },
+        { companyUid: "cmp_indigo", membershipKey: "mbr_indigo" },
+      ],
+      syncConfigs: {
+        mbr_personal: { syncMode: "all" },
+        mbr_indigo: { syncMode: "shared" },
+      },
+    });
+    const result = await resolvePerCompanyPullPlan(client, "cmp_indigo");
+    expect(result.resolvedCompanyUid).toBe("cmp_indigo");
+    expect(result.resolvedMode).toBe("shared");
+    // Slug-fallback loop must not fire — no entity calls.
+    expect(client._entityCalls()).toEqual([]);
+  });
+
+  it("matches by direct membershipKey", async () => {
+    const client = makeClient({
+      memberships: [
+        { companyUid: "cmp_x", membershipKey: "mbr_special" },
+      ],
+      syncConfigs: { mbr_special: { syncMode: "custom" } },
+    });
+    const result = await resolvePerCompanyPullPlan(client, "mbr_special");
+    expect(result.resolvedCompanyUid).toBe("cmp_x");
+    expect(result.resolvedMode).toBe("custom");
+  });
+
+  it("matches by slug via entity.get fan-out", async () => {
+    const client = makeClient({
+      memberships: [
+        { companyUid: "cmp_one", membershipKey: "mbr_one" },
+        { companyUid: "cmp_two", membershipKey: "mbr_two" },
+      ],
+      syncConfigs: { mbr_two: { syncMode: "all" } },
+      entities: {
+        cmp_one: { slug: "foo" },
+        cmp_two: { slug: "personal" },
+      },
+    });
+    const result = await resolvePerCompanyPullPlan(client, "personal");
+    expect(result.resolvedCompanyUid).toBe("cmp_two");
+    expect(result.resolvedMode).toBe("all");
+  });
+
+  it("stops slug iteration at the first match — does not fan out", async () => {
+    const client = makeClient({
+      memberships: [
+        { companyUid: "cmp_a", membershipKey: "mbr_a" },
+        { companyUid: "cmp_b", membershipKey: "mbr_b" },
+        { companyUid: "cmp_c", membershipKey: "mbr_c" },
+      ],
+      syncConfigs: { mbr_b: { syncMode: "shared" } },
+      entities: {
+        cmp_a: { slug: "alpha" },
+        cmp_b: { slug: "beta" },
+        cmp_c: { slug: "gamma" },
+      },
+    });
+    const result = await resolvePerCompanyPullPlan(client, "beta");
+    expect(result.resolvedCompanyUid).toBe("cmp_b");
+    expect(result.resolvedMode).toBe("shared");
+    // cmp_a was probed, cmp_b matched, cmp_c never touched.
+    expect(client._entityCalls()).toEqual(["cmp_a", "cmp_b"]);
+  });
+
+  it("returns undefined for both when no matching membership/slug", async () => {
+    const client = makeClient({
+      memberships: [
+        { companyUid: "cmp_x", membershipKey: "mbr_x" },
+      ],
+      entities: { cmp_x: { slug: "foo" } },
+    });
+    const result = await resolvePerCompanyPullPlan(client, "doesnotexist");
+    expect(result.resolvedCompanyUid).toBeUndefined();
+    expect(result.resolvedMode).toBeUndefined();
+  });
+
+  it("degrades silently when listMyMemberships fails — no banner, pull continues", async () => {
+    const client = makeClient({ failListMemberships: true });
+    const result = await resolvePerCompanyPullPlan(client, "personal");
+    expect(result.resolvedCompanyUid).toBeUndefined();
+    expect(result.resolvedMode).toBeUndefined();
+    // Sync-config never reached.
+    expect(client.getMembershipSyncConfig).not.toHaveBeenCalled();
+  });
+
+  it("on direct match, keeps companyUid even when getMembershipSyncConfig throws", async () => {
+    const client = makeClient({
+      memberships: [{ companyUid: "cmp_p", membershipKey: "mbr_p" }],
+      failSyncConfigFor: new Set(["mbr_p"]),
+    });
+    const result = await resolvePerCompanyPullPlan(client, "cmp_p");
+    expect(result.resolvedCompanyUid).toBe("cmp_p");
+    // Mode unknown — caller will skip banner emit (it only fires when mode='all').
+    expect(result.resolvedMode).toBeUndefined();
+  });
+
+  it("on slug-fallback match, skips broken entity rows and keeps looking", async () => {
+    const client = makeClient({
+      memberships: [
+        { companyUid: "cmp_broken", membershipKey: "mbr_broken" },
+        { companyUid: "cmp_good", membershipKey: "mbr_good" },
+      ],
+      syncConfigs: { mbr_good: { syncMode: "all" } },
+      entities: { cmp_good: { slug: "wanted" } },
+      failEntityFor: new Set(["cmp_broken"]),
+    });
+    const result = await resolvePerCompanyPullPlan(client, "wanted");
+    expect(result.resolvedCompanyUid).toBe("cmp_good");
+    expect(result.resolvedMode).toBe("all");
+  });
+});