@indigoai-us/hq-cli 5.17.0 → 5.18.0

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.ts

@@ -28,6 +28,7 @@ import {
   computePersonalVaultPaths,
   type ConflictStrategy,
   type EntityContext,
+  type MembershipSyncConfig,
   type SyncProgressEvent,
   type UploadAuthor,
 } from "@indigoai-us/hq-cloud";
@@ -37,6 +38,12 @@ import {
   ensureCognitoToken,
   buildVaultConfig,
 } from "../utils/cognito-session.js";
+import {
+  emitNarrowHint,
+  isStrictRefusal,
+  resolveBannerLevel,
+  type BannerLevel,
+} from "../lib/narrow-hint-banner.js";
 
 interface CommonSyncOptions {
   hqRoot: string;
@@ -53,7 +60,9 @@ interface CommonSyncOptions {
 // ─────────────────────────────────────────────────────────────────────────────
 
 export interface PullAllVaultClient {
-  listMyMemberships(): Promise<Array<{ companyUid: string }>>;
+  listMyMemberships(): Promise<
+    Array<{ companyUid: string; membershipKey?: string }>
+  >;
   listPersonEntities(): Promise<
     Array<{
       uid: string;
@@ -64,6 +73,15 @@ export interface PullAllVaultClient {
     }>
   >;
   getEntity(uid: string): Promise<{ slug?: string; name?: string } | null>;
+  /**
+   * US-011: optional — when present, `pullAll` calls it once per
+   * membership to surface the narrow-hint banner for all-mode owners.
+   * Absent on legacy adapters (push-all et al.) where the banner is not
+   * applicable.
+   */
+  getMembershipSyncConfig?: (
+    membershipId: string,
+  ) => Promise<MembershipSyncConfig>;
 }
 
 export interface SyncCallOptions {
@@ -91,6 +109,22 @@ export interface PullAllDeps {
 export interface PullAllOptions {
   hqRoot: string;
   onConflict?: ConflictStrategy;
+  /**
+   * US-011: banner level for the narrow-hint nudge. Defaults to `'hint'`
+   * — see `resolveBannerLevel` for the env-driven override. The
+   * `'strict'` level causes `pullAll` to refuse to sync any membership
+   * still on `syncMode: 'all'` unless `modeAllOverride` is true.
+   *
+   * TODO(hq-core-staging release N+2): default flips to 'warning'.
+   * TODO(hq-core-staging release N+3): default flips to 'strict'.
+   */
+  narrowHintLevel?: BannerLevel;
+  /**
+   * US-011: when `true`, strict-mode does NOT refuse all-mode
+   * memberships — the operator has explicitly opted into keeping the
+   * legacy behavior for this run via `--mode-all`.
+   */
+  modeAllOverride?: boolean;
 }
 
 export interface PullAllRow {
@@ -168,6 +202,9 @@ export interface PullAllResult {
 interface PlanEntry {
   slug: string;
   syncOptions: SyncCallOptions;
+  /** US-011: tracked so we can resolve sync-config + emit the narrow hint. */
+  companyUid?: string;
+  membershipKey?: string;
 }
 
 // Oldest-first by createdAt, ties broken by uid lexicographic — matches
@@ -191,6 +228,9 @@ export async function pullAll(
   const memberships = await deps.vaultClient.listMyMemberships();
   const persons = await deps.vaultClient.listPersonEntities();
 
+  const narrowHintLevel: BannerLevel = options.narrowHintLevel ?? "hint";
+  const getSyncConfig = deps.vaultClient.getMembershipSyncConfig;
+
   const plan: PlanEntry[] = [];
   for (const m of memberships) {
     let slug = m.companyUid;
@@ -202,6 +242,8 @@ export async function pullAll(
     }
     plan.push({
       slug,
+      companyUid: m.companyUid,
+      ...(m.membershipKey ? { membershipKey: m.membershipKey } : {}),
       syncOptions: {
         company: m.companyUid,
         hqRoot: options.hqRoot,
@@ -235,12 +277,63 @@ export async function pullAll(
 
   for (const entry of plan) {
     result.attempted += 1;
+
+    // US-011: resolve the membership's effective sync mode so we can
+    // either nudge an all-mode owner toward `hq sync narrow` OR refuse
+    // the leg outright when strict-mode is on and the operator didn't
+    // pass `--mode-all`. Sync-config lookup is best-effort — a 404 or
+    // network blip should never block the sync itself, so we fall back
+    // to syncMode='all' (the legacy default) and skip the banner.
+    let resolvedMode: MembershipSyncConfig["syncMode"] | undefined;
+    if (entry.membershipKey && getSyncConfig) {
+      try {
+        const cfg = await getSyncConfig(entry.membershipKey);
+        resolvedMode = cfg.syncMode;
+      } catch {
+        resolvedMode = undefined;
+      }
+    }
+
+    if (
+      resolvedMode === "all" &&
+      isStrictRefusal(resolvedMode, narrowHintLevel) &&
+      !options.modeAllOverride &&
+      entry.companyUid
+    ) {
+      // Emit the strict-level banner once, then mark the leg as errored
+      // without invoking sync(). The operator either narrows the
+      // membership (`hq sync narrow --apply`) or passes `--mode-all` to
+      // opt back in.
+      emitNarrowHint({
+        companyUid: entry.companyUid,
+        syncMode: resolvedMode,
+        level: narrowHintLevel,
+      });
+      const message =
+        "Refusing to pull all-mode membership in strict mode. " +
+        "Run `hq sync narrow --apply` to migrate, or re-run with --mode-all.";
+      result.errors.push({ company: entry.slug, message });
+      result.perCompany.push({ slug: entry.slug, error: message });
+      continue;
+    }
+
     try {
       const r = await deps.sync(entry.syncOptions);
       result.filesDownloaded += r.filesDownloaded;
       result.bytesDownloaded += r.bytesDownloaded;
       result.conflicts += r.conflicts;
       result.perCompany.push({ slug: entry.slug, result: r });
+
+      // Banner emitted AFTER the leg succeeds so it appears alongside
+      // the per-company summary line and doesn't get scrolled off by
+      // sync chatter.
+      if (resolvedMode === "all" && entry.companyUid) {
+        emitNarrowHint({
+          companyUid: entry.companyUid,
+          syncMode: resolvedMode,
+          level: narrowHintLevel,
+        });
+      }
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       result.errors.push({ company: entry.slug, message });
@@ -681,12 +774,20 @@ export function registerCloudCommands(program: Command): void {
         "from the cached Cognito session. Mutually exclusive with --company " +
         "and --all.",
     )
+    .option(
+      "--mode-all",
+      "US-011: opt out of the strict narrow-hint refusal for this run. " +
+        "Has no effect today (default narrow-hint level is 'hint'); " +
+        "wired so future hq-core-staging releases can flip the default to " +
+        "'strict' without re-touching this command.",
+    )
     .action(
       async (
         options: CommonSyncOptions & {
           onConflict?: ConflictStrategy;
           all?: boolean;
           personal?: boolean;
+          modeAll?: boolean;
         },
       ) => {
         try {
@@ -699,7 +800,11 @@ export function registerCloudCommands(program: Command): void {
           process.exit(1);
         }
         if (options.all) {
-          await runPullAll(options.hqRoot, options.onConflict);
+          await runPullAll(
+            options.hqRoot,
+            options.onConflict,
+            options.modeAll === true,
+          );
           return;
         }
         if (options.personal) {
@@ -833,6 +938,12 @@ export function registerCloudCommands(program: Command): void {
       "Sync the caller's canonical personal vault bidirectionally. " +
         "Mutually exclusive with --company and --all.",
     )
+    .option(
+      "--mode-all",
+      "US-011: opt out of the strict narrow-hint refusal for this run. " +
+        "No-op today; wired so future hq-core-staging releases can flip " +
+        "the default narrow-hint level to 'strict'.",
+    )
     .action(
       async (
         options: CommonSyncOptions & {
@@ -840,6 +951,7 @@ export function registerCloudCommands(program: Command): void {
           message?: string;
           all?: boolean;
           personal?: boolean;
+          modeAll?: boolean;
         },
       ) => {
         try {
@@ -849,6 +961,7 @@ export function registerCloudCommands(program: Command): void {
               options.hqRoot,
               options.message,
               options.onConflict,
+              options.modeAll === true,
             );
             return;
           }
@@ -858,6 +971,7 @@ export function registerCloudCommands(program: Command): void {
             options.personal === true,
             options.message,
             options.onConflict,
+            options.modeAll === true,
           );
         } catch (err) {
           console.error(
@@ -873,6 +987,7 @@ export function registerCloudCommands(program: Command): void {
 async function runPullAll(
   hqRoot: string,
   onConflict?: ConflictStrategy,
+  modeAllOverride?: boolean,
 ): Promise<void> {
   console.log(chalk.bold("\nHQ Sync — Pull (all)"));
   console.log(`  HQ root:  ${hqRoot}`);
@@ -894,10 +1009,17 @@ async function runPullAll(
           return null;
         }
       },
+      getMembershipSyncConfig: (id: string) =>
+        realClient.getMembershipSyncConfig(id),
     };
 
     result = await pullAll(
-      { hqRoot, ...(onConflict ? { onConflict } : {}) },
+      {
+        hqRoot,
+        ...(onConflict ? { onConflict } : {}),
+        narrowHintLevel: resolveBannerLevel(),
+        ...(modeAllOverride ? { modeAllOverride: true } : {}),
+      },
       {
         vaultClient: adapter,
         sync: (opts) =>
@@ -1095,6 +1217,7 @@ async function runNowSingle(
   personal: boolean,
   message?: string,
   onConflict?: ConflictStrategy,
+  modeAllOverride?: boolean,
 ): Promise<void> {
   console.log(chalk.bold("\nHQ Sync — Now"));
   console.log(`  HQ root:  ${hqRoot}`);
@@ -1168,6 +1291,59 @@ async function runNowSingle(
       process.exit(1);
     }
 
+    // US-011: resolve membership sync-config so we can either nudge an
+    // all-mode owner or refuse the pull when strict-mode is on. Skipped
+    // for personal targets (personal vault has no membership row) and
+    // for resolution failures (best-effort — never block sync). The
+    // lookup runs BEFORE the pull leg so strict refusal can short-circuit
+    // without burning a sync.
+    const narrowHintLevel: BannerLevel = resolveBannerLevel();
+    let resolvedMode: MembershipSyncConfig["syncMode"] | undefined;
+    let resolvedCompanyUid: string | undefined;
+    if (!personalMode && targetCompany) {
+      try {
+        const client = new VaultClient(vaultConfig);
+        const memberships = await client.listMyMemberships();
+        const match = memberships.find(
+          (m) => m.companyUid === targetCompany || m.membershipKey === targetCompany,
+        );
+        if (match) {
+          resolvedCompanyUid = match.companyUid;
+          try {
+            const cfg = await client.getMembershipSyncConfig(
+              match.membershipKey,
+            );
+            resolvedMode = cfg.syncMode;
+          } catch {
+            resolvedMode = undefined;
+          }
+        }
+      } catch {
+        resolvedMode = undefined;
+      }
+    }
+
+    if (
+      resolvedMode === "all" &&
+      isStrictRefusal(resolvedMode, narrowHintLevel) &&
+      !modeAllOverride &&
+      resolvedCompanyUid
+    ) {
+      emitNarrowHint({
+        companyUid: resolvedCompanyUid,
+        syncMode: resolvedMode,
+        level: narrowHintLevel,
+      });
+      console.error(
+        chalk.red(
+          "\n✗ Sync now refused: strict narrow-hint mode is on and this " +
+            "membership still pulls everything. Run `hq sync narrow --apply` " +
+            "to migrate, or re-run with --mode-all.",
+        ),
+      );
+      process.exit(1);
+    }
+
     console.log(chalk.dim("  → pull leg"));
     const pullResult = await sync({
       company: targetCompany,
@@ -1188,6 +1364,17 @@ async function runNowSingle(
       console.log(chalk.yellow("\n⚠ Sync now finished with pull leg aborted."));
       process.exit(1);
     }
+
+    // US-011: emit the hint banner after a successful pull so it
+    // appears at the bottom of the summary rather than mid-stream.
+    if (resolvedMode === "all" && resolvedCompanyUid) {
+      emitNarrowHint({
+        companyUid: resolvedCompanyUid,
+        syncMode: resolvedMode,
+        level: narrowHintLevel,
+      });
+    }
+
     console.log(chalk.green("\n✓ Sync now complete"));
   } catch (err) {
     console.error(
@@ -1202,6 +1389,7 @@ async function runNowAll(
   hqRoot: string,
   message?: string,
   onConflict?: ConflictStrategy,
+  modeAllOverride?: boolean,
 ): Promise<void> {
   console.log(chalk.bold("\nHQ Sync — Now (all)"));
   console.log(`  HQ root:  ${hqRoot}`);
@@ -1213,7 +1401,10 @@ async function runNowAll(
   console.log(chalk.dim("→ push --all"));
   await runPushAll(hqRoot, message, onConflict);
   console.log(chalk.dim("\n→ pull --all"));
-  await runPullAll(hqRoot, onConflict);
+  // US-011: forward --mode-all so the strict refusal applies to the
+  // pull leg (push doesn't need a narrow-hint — the narrow ritual is
+  // pull-side).
+  await runPullAll(hqRoot, onConflict, modeAllOverride);
 }
 
 /**