@indigoai-us/hq-cli 5.18.0 → 5.18.1

package/dist/commands/cloud.d.ts

@@ -163,5 +163,42 @@ export declare function assertSingleSelector(opts: {
     personal?: boolean;
     company?: string;
 }, command: string): void;
+/**
+ * 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 declare function resolvePerCompanyPullPlan(client: PerCompanyPullResolveClient, targetCompany: string | undefined): Promise<PerCompanyPullResolveResult>;
 export declare function registerCloudCommands(program: Command): void;
 //# sourceMappingURL=cloud.d.ts.map

package/dist/commands/cloud.js

@@ -13,7 +13,7 @@
  *   hq sync status            — show local journal summary
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="2eb7da1d-e84f-591c-b930-b84c5c96986b")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="4672d875-1dc8-56a2-bef1-49c7f4ff6c76")}catch(e){}}();
 import chalk from "chalk";
 import * as fs from "fs";
 import * as path from "path";
@@ -252,6 +252,54 @@ export function assertSingleSelector(opts, command) {
             `--company; got: ${selectors.join(", ")}.`);
     }
 }
+export async function resolvePerCompanyPullPlan(client, targetCompany) {
+    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;
+            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;
+                    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) {
     program
         .command("push")
@@ -482,10 +530,37 @@ export function registerCloudCommands(program) {
             console.log(`  HQ root:  ${options.hqRoot}`);
             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 = 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,
             });
             if (result.aborted) {
@@ -493,6 +568,16 @@ export function registerCloudCommands(program) {
                 process.exit(1);
             }
             console.log(chalk.green(`\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:"), err instanceof Error ? err.message : String(err));
@@ -978,4 +1063,4 @@ function resolveUploadAuthorFromCache() {
     }
 }
 //# sourceMappingURL=cloud.js.map
-//# debugId=2eb7da1d-e84f-591c-b930-b84c5c96986b
+//# debugId=4672d875-1dc8-56a2-bef1-49c7f4ff6c76

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.18.0",
+  "version": "5.18.1",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {

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");
+  });
+});

package/src/commands/cloud.ts

@@ -473,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")
@@ -817,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,
           });
 
@@ -838,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:"),