@indigoai-us/hq-cli 5.17.0 → 5.18.1

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 });
@@ -380,6 +473,86 @@ export function assertSingleSelector(opts: {
   }
 }
 
+/**
+ * Per-company pull resolution helper used by `hq sync pull --company <slug>`
+ * (US-011 fix, 2026-05-21). Mirrors the inline lookup that `runNowSingle`
+ * does for sync-now. Pulled out so the action handler stays thin AND so
+ * unit tests can exercise the banner / strict-refusal decision without
+ * spinning up commander + a real VaultClient.
+ *
+ * Input shape:
+ *   - `targetCompany` — slug or UID the caller passed to `--company`. If
+ *     undefined, the helper short-circuits to a "no resolution" result
+ *     (the action handler falls back to .hq/config.json via sync()).
+ *   - `client` — minimal VaultClient surface: listMyMemberships + entity.get
+ *     + getMembershipSyncConfig.
+ *
+ * Output: `{ resolvedCompanyUid, resolvedMode }` — either may be undefined
+ * if the membership / sync-config call failed. Both undefined is a clean
+ * degradation — the caller pulls without a banner.
+ */
+export interface PerCompanyPullResolveClient {
+  listMyMemberships(): Promise<Array<{ companyUid: string; membershipKey: string }>>;
+  getMembershipSyncConfig(
+    membershipKey: string,
+  ): Promise<{ syncMode: MembershipSyncConfig["syncMode"] }>;
+  entity: { get(uid: string): Promise<{ slug?: string }> };
+}
+
+export interface PerCompanyPullResolveResult {
+  resolvedCompanyUid: string | undefined;
+  resolvedMode: MembershipSyncConfig["syncMode"] | undefined;
+}
+
+export async function resolvePerCompanyPullPlan(
+  client: PerCompanyPullResolveClient,
+  targetCompany: string | undefined,
+): Promise<PerCompanyPullResolveResult> {
+  if (!targetCompany) return { resolvedCompanyUid: undefined, resolvedMode: undefined };
+  try {
+    const memberships = await client.listMyMemberships();
+    // Direct UID / membershipKey match first (cheapest).
+    const direct = memberships.find(
+      (m) => m.companyUid === targetCompany || m.membershipKey === targetCompany,
+    );
+    if (direct) {
+      let mode: MembershipSyncConfig["syncMode"] | undefined;
+      try {
+        const cfg = await client.getMembershipSyncConfig(direct.membershipKey);
+        mode = cfg.syncMode;
+      } catch {
+        mode = undefined;
+      }
+      return { resolvedCompanyUid: direct.companyUid, resolvedMode: mode };
+    }
+    // Slug match — listMyMemberships returns companyUid only, so fan out
+    // entity.get to find the row whose slug matches the caller's input.
+    for (const m of memberships) {
+      try {
+        const entity = await client.entity.get(m.companyUid);
+        if (entity.slug === targetCompany) {
+          let mode: MembershipSyncConfig["syncMode"] | undefined;
+          try {
+            const cfg = await client.getMembershipSyncConfig(m.membershipKey);
+            mode = cfg.syncMode;
+          } catch {
+            mode = undefined;
+          }
+          return { resolvedCompanyUid: m.companyUid, resolvedMode: mode };
+        }
+      } catch {
+        // Entity not visible — skip and continue. Worst case the loop ends
+        // with no match and we return undefined for both — the pull still
+        // proceeds, banner just stays quiet.
+      }
+    }
+  } catch {
+    // listMyMemberships failed — degrade silently. Sync still works without
+    // the banner; this matches the runPullAll catch behavior.
+  }
+  return { resolvedCompanyUid: undefined, resolvedMode: undefined };
+}
+
 export function registerCloudCommands(program: Command): void {
   program
     .command("push")
@@ -681,12 +854,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 +880,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) {
@@ -712,10 +897,50 @@ export function registerCloudCommands(program: Command): void {
           console.log(`  Company:  ${options.company ?? "(from .hq/config.json)"}\n`);
 
           const accessToken = await ensureCognitoToken();
+          const vaultConfig = buildVaultConfig(accessToken);
+
+          // US-011 (2026-05-21 fix): resolve the caller's sync-config for
+          // the targeted membership BEFORE the pull, so we can (a) emit the
+          // narrow-hint banner after success if still on all-mode and
+          // (b) respect strict-mode refusal mirror of the --all + sync-now
+          // paths. Failure to resolve degrades silently — pull still works,
+          // banner just stays quiet (same as the catch in runPullAll).
+          const narrowHintLevel: BannerLevel = resolveBannerLevel();
+          const { resolvedCompanyUid, resolvedMode } =
+            await resolvePerCompanyPullPlan(
+              new VaultClient(vaultConfig),
+              options.company,
+            );
+
+          // Strict-mode refusal: matches runPullAll + runNowSingle behavior.
+          // Default banner level is 'hint' which never triggers refusal —
+          // wired now so future hq-core-staging releases can flip the
+          // default to 'strict' without re-touching this command.
+          if (
+            resolvedMode === "all" &&
+            isStrictRefusal(resolvedMode, narrowHintLevel) &&
+            options.modeAll !== true &&
+            resolvedCompanyUid
+          ) {
+            emitNarrowHint({
+              companyUid: resolvedCompanyUid,
+              syncMode: resolvedMode,
+              level: narrowHintLevel,
+            });
+            console.error(
+              chalk.red(
+                "\n✗ Pull 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);
+          }
+
           const result = await sync({
             company: options.company,
             onConflict: options.onConflict,
-            vaultConfig: buildVaultConfig(accessToken),
+            vaultConfig,
             hqRoot: options.hqRoot,
           });
 
@@ -733,6 +958,17 @@ export function registerCloudCommands(program: Command): void {
               `\n✓ Pulled ${result.filesDownloaded} file(s) (${formatBytes(result.bytesDownloaded)}, ${result.filesSkipped} skipped, ${result.conflicts} conflicts)`,
             ),
           );
+
+          // US-011 (2026-05-21 fix): emit the hint banner after success
+          // so it appears alongside the summary line. Mirrors the wiring
+          // in runPullAll (cloud.ts:331) and runNowSingle (cloud.ts:1371).
+          if (resolvedMode === "all" && resolvedCompanyUid) {
+            emitNarrowHint({
+              companyUid: resolvedCompanyUid,
+              syncMode: resolvedMode,
+              level: narrowHintLevel,
+            });
+          }
         } catch (err) {
           console.error(
             chalk.red("\n✗ Pull failed:"),
@@ -833,6 +1069,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 +1082,7 @@ export function registerCloudCommands(program: Command): void {
           message?: string;
           all?: boolean;
           personal?: boolean;
+          modeAll?: boolean;
         },
       ) => {
         try {
@@ -849,6 +1092,7 @@ export function registerCloudCommands(program: Command): void {
               options.hqRoot,
               options.message,
               options.onConflict,
+              options.modeAll === true,
             );
             return;
           }
@@ -858,6 +1102,7 @@ export function registerCloudCommands(program: Command): void {
             options.personal === true,
             options.message,
             options.onConflict,
+            options.modeAll === true,
           );
         } catch (err) {
           console.error(
@@ -873,6 +1118,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 +1140,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 +1348,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 +1422,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 +1495,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 +1520,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 +1532,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);
 }
 
 /**