@indigoai-us/hq-cli 5.18.3 → 5.20.0

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

@@ -493,4 +493,102 @@ describe("pullAll", () => {
       expect(call.hqRoot).toBe("/Users/me/scratch/hq");
     }
   });
+
+  // ── 11. skipPersonal — fanout omits the canonical-person leg ──────────────
+  //
+  // Mirrors the upstream `hq-sync-runner --skip-personal` flag (hq-cloud
+  // 5.25.0) plumbed through to the CLI as `hq sync pull --all --no-personal`.
+  // When the option is true, `pullAll` must (a) skip the canonical-person
+  // bucket even when one exists, and (b) leave companies untouched.
+
+  it("skipPersonal=true omits the personal leg even when a person entity exists", async () => {
+    const vaultClient = makeVaultClient({
+      memberships: [
+        { companyUid: "cmp_acme" },
+        { companyUid: "cmp_globex" },
+      ],
+      persons: [
+        {
+          uid: "psn_alice",
+          type: "person",
+          slug: "alice",
+          bucketName: "hq-vault-psn-alice",
+          createdAt: "2026-01-01T00:00:00Z",
+        },
+      ],
+      entitiesBySlug: {
+        cmp_acme: { slug: "acme" },
+        cmp_globex: { slug: "globex" },
+      },
+    });
+    const sync = makeSyncSpy();
+
+    const result = await pullAll(
+      { hqRoot: "/tmp/hq", skipPersonal: true },
+      { vaultClient, sync: sync.fn },
+    );
+
+    expect(sync.calls.map((c) => c.company)).toEqual([
+      "cmp_acme",
+      "cmp_globex",
+    ]);
+    for (const call of sync.calls) {
+      expect(call.personalMode).toBeUndefined();
+      expect(call.journalSlug).toBeUndefined();
+    }
+    expect(result.attempted).toBe(2);
+    expect(result.perCompany.map((r) => r.slug)).toEqual(["acme", "globex"]);
+  });
+
+  it("skipPersonal omitted/false keeps the personal leg in the fanout (baseline)", async () => {
+    const vaultClient = makeVaultClient({
+      memberships: [{ companyUid: "cmp_acme" }],
+      persons: [
+        {
+          uid: "psn_alice",
+          type: "person",
+          slug: "alice",
+          createdAt: "2026-01-01T00:00:00Z",
+        },
+      ],
+      entitiesBySlug: { cmp_acme: { slug: "acme" } },
+    });
+    const sync = makeSyncSpy();
+
+    await pullAll(
+      { hqRoot: "/tmp/hq" },
+      { vaultClient, sync: sync.fn },
+    );
+
+    expect(sync.calls.map((c) => c.company)).toEqual([
+      "cmp_acme",
+      "psn_alice",
+    ]);
+    expect(sync.calls[1].personalMode).toBe(true);
+    expect(sync.calls[1].journalSlug).toBe("personal");
+  });
+
+  it("skipPersonal=true with empty memberships produces zero sync calls", async () => {
+    const vaultClient = makeVaultClient({
+      memberships: [],
+      persons: [
+        {
+          uid: "psn_alice",
+          type: "person",
+          slug: "alice",
+          createdAt: "2026-01-01T00:00:00Z",
+        },
+      ],
+    });
+    const sync = makeSyncSpy();
+
+    const result = await pullAll(
+      { hqRoot: "/tmp/hq", skipPersonal: true },
+      { vaultClient, sync: sync.fn },
+    );
+
+    expect(sync.calls).toEqual([]);
+    expect(result.attempted).toBe(0);
+    expect(result.perCompany).toEqual([]);
+  });
 });

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

@@ -378,4 +378,79 @@ describe("pushAll", () => {
     expect(result.filesUploaded).toBe(3);
     expect(result.filesDeleted).toBe(4);
   });
+
+  // ── skipPersonal — fanout omits the canonical-person leg ──────────────────
+  //
+  // Symmetric with the `pullAll` skipPersonal coverage in
+  // `cloud.pull-all.test.ts`. Wired through from `hq sync push --all
+  // --no-personal` (Commander's `--no-personal` is the auto-negation of the
+  // `--personal` single-target selector). Verifies (a) the personal leg is
+  // dropped even when a canonical person exists, and (b) the baseline
+  // behavior — no flag → personal stays in the plan.
+
+  it("skipPersonal=true omits the personal leg even when a person entity exists", async () => {
+    const hqRoot = makeHqRoot([".git", "companies", "repos", "workspace"]);
+    const vaultClient = makeVaultClient({
+      memberships: [
+        { companyUid: "cmp_acme" },
+        { companyUid: "cmp_globex" },
+      ],
+      persons: [
+        {
+          uid: "psn_alice",
+          type: "person",
+          slug: "alice",
+          bucketName: "hq-vault-psn-alice",
+          createdAt: "2026-01-01T00:00:00Z",
+        },
+      ],
+      entitiesBySlug: {
+        cmp_acme: { slug: "acme" },
+        cmp_globex: { slug: "globex" },
+      },
+    });
+    const share = makeShareSpy();
+
+    const result = await pushAll(
+      { hqRoot, skipPersonal: true },
+      { vaultClient, share: share.fn },
+    );
+
+    expect(share.calls.map((c) => c.company)).toEqual([
+      "cmp_acme",
+      "cmp_globex",
+    ]);
+    for (const call of share.calls) {
+      expect(call.personalMode).toBeUndefined();
+      expect(call.journalSlug).toBeUndefined();
+    }
+    expect(result.attempted).toBe(2);
+    expect(result.perCompany.map((r) => r.slug)).toEqual(["acme", "globex"]);
+  });
+
+  it("skipPersonal omitted keeps the personal leg in the plan (baseline)", async () => {
+    const hqRoot = makeHqRoot([".git", "companies", "repos", "workspace"]);
+    const vaultClient = makeVaultClient({
+      memberships: [{ companyUid: "cmp_acme" }],
+      persons: [
+        {
+          uid: "psn_alice",
+          type: "person",
+          slug: "alice",
+          createdAt: "2026-01-01T00:00:00Z",
+        },
+      ],
+      entitiesBySlug: { cmp_acme: { slug: "acme" } },
+    });
+    const share = makeShareSpy();
+
+    await pushAll({ hqRoot }, { vaultClient, share: share.fn });
+
+    expect(share.calls.map((c) => c.company)).toEqual([
+      "cmp_acme",
+      "psn_alice",
+    ]);
+    expect(share.calls[1].personalMode).toBe(true);
+    expect(share.calls[1].journalSlug).toBe("personal");
+  });
 });

package/src/commands/cloud.selectors.test.ts

@@ -11,6 +11,7 @@
 import { describe, expect, it, vi } from "vitest";
 
 import {
+  assertNoPersonalPositionalPaths,
   assertSingleSelector,
   resolveCanonicalPersonUid,
   type PullAllVaultClient,
@@ -76,6 +77,58 @@ describe("assertSingleSelector", () => {
   });
 });
 
+// ── assertNoPersonalPositionalPaths (hq-cli#25) ─────────────────────────────
+//
+// The combination `--personal <path>` silently bypasses
+// PERSONAL_VAULT_EXCLUDED_TOP_LEVEL (which is only applied by
+// computePersonalVaultPaths). Real incident: 196 companies/{slug}/** objects
+// uploaded to a personal vault. Refusal forces the operator to drop one of
+// the two — either `--personal` (full vault scope) or the positional paths
+// (specific subset against the active company).
+
+describe("assertNoPersonalPositionalPaths", () => {
+  it("accepts --personal alone (no positional paths)", () => {
+    expect(() => assertNoPersonalPositionalPaths({ personal: true }, undefined)).not.toThrow();
+    expect(() => assertNoPersonalPositionalPaths({ personal: true }, [])).not.toThrow();
+  });
+
+  it("accepts positional paths without --personal", () => {
+    expect(() => assertNoPersonalPositionalPaths({ personal: false }, ["./scratch"])).not.toThrow();
+    expect(() => assertNoPersonalPositionalPaths({}, ["./scratch"])).not.toThrow();
+  });
+
+  it("accepts neither --personal nor positional paths", () => {
+    expect(() => assertNoPersonalPositionalPaths({}, undefined)).not.toThrow();
+    expect(() => assertNoPersonalPositionalPaths({}, [])).not.toThrow();
+  });
+
+  it("throws when --personal combines with one positional path", () => {
+    expect(() => assertNoPersonalPositionalPaths({ personal: true }, ["./scratch"])).toThrow(
+      /--personal.*cannot be combined with explicit \[paths\]/,
+    );
+  });
+
+  it("throws when --personal combines with multiple positional paths", () => {
+    expect(() =>
+      assertNoPersonalPositionalPaths({ personal: true }, ["./a", "./b", "./c"]),
+    ).toThrow(/PERSONAL_VAULT_EXCLUDED_TOP_LEVEL/);
+  });
+
+  it("error message names the dangerous prefixes so the operator understands the risk", () => {
+    let caught: Error | null = null;
+    try {
+      assertNoPersonalPositionalPaths({ personal: true }, ["/Users/corey/Documents/HQ"]);
+    } catch (e) {
+      caught = e as Error;
+    }
+    expect(caught).not.toBeNull();
+    expect(caught!.message).toContain(".git/");
+    expect(caught!.message).toContain("companies/");
+    expect(caught!.message).toContain("repos/");
+    expect(caught!.message).toContain("workspace/");
+  });
+});
+
 // ── resolveCanonicalPersonUid ──────────────────────────────────────────────
 
 function makeClient(persons: Array<{

package/src/commands/cloud.ts

@@ -125,6 +125,17 @@ export interface PullAllOptions {
    * legacy behavior for this run via `--mode-all`.
    */
   modeAllOverride?: boolean;
+  /**
+   * When `true`, skip the canonical-person-entity leg entirely — the
+   * fanout only visits the caller's company memberships. Mirrors the
+   * `--skip-personal` flag and `HQ_SYNC_SKIP_PERSONAL` env var that
+   * `@indigoai-us/hq-cloud`'s `sync-runner` exposes in `--companies`
+   * mode (see hq-cloud 5.25.0 `resolveSkipPersonal`). Surfaced on the
+   * CLI as `hq sync pull --all --no-personal` so the AppBar HQ Sync
+   * menubar toggle (and CLI users opting out one-off) can drop the
+   * personal vault from the run without touching the rest of the plan.
+   */
+  skipPersonal?: boolean;
 }
 
 export interface PullAllRow {
@@ -173,6 +184,13 @@ export interface PushAllOptions {
   hqRoot: string;
   onConflict?: ConflictStrategy;
   message?: string;
+  /**
+   * When `true`, skip the canonical-person-entity leg entirely — the
+   * fanout only visits the caller's company memberships. Symmetric with
+   * `PullAllOptions.skipPersonal`; surfaced on the CLI as
+   * `hq sync push --all --no-personal`.
+   */
+  skipPersonal?: boolean;
 }
 
 export interface PushAllRow {
@@ -252,7 +270,7 @@ export async function pullAll(
     });
   }
 
-  const personal = pickCanonicalPerson(persons);
+  const personal = options.skipPersonal ? null : pickCanonicalPerson(persons);
   if (personal) {
     plan.push({
       slug: "personal",
@@ -385,7 +403,7 @@ export async function pushAll(
     });
   }
 
-  const personal = pickCanonicalPerson(persons);
+  const personal = options.skipPersonal ? null : pickCanonicalPerson(persons);
   if (personal) {
     plan.push({
       slug: "personal",
@@ -451,6 +469,35 @@ export async function resolveCanonicalPersonUid(
   return pick.uid;
 }
 
+/**
+ * Refuse `hq sync push --personal <path>` — the combination silently
+ * bypasses `PERSONAL_VAULT_EXCLUDED_TOP_LEVEL` (which is only applied by
+ * `computePersonalVaultPaths`), risking cross-scope upload of `companies/`,
+ * `repos/`, `workspace/`, or `.git/` content to the personal vault. Real
+ * incident (2026-05-21): a single command uploaded 196 `companies/{slug}/**`
+ * objects to a personal vault before being killed. Cleanup required a
+ * hand-rolled S3 sweep. Closes hq-cli#25.
+ *
+ * Refusal — not silent filtering — is intentional: explicit is better than
+ * implicit guesswork, and the legitimate "I want to push a subset of my
+ * personal vault" use case has a clean workaround (drop `--personal`, the
+ * subset upload targets the active company via standard semantics).
+ */
+export function assertNoPersonalPositionalPaths(opts: {
+  personal?: boolean;
+}, paths: string[] | undefined): void {
+  if (opts.personal && paths && paths.length > 0) {
+    throw new Error(
+      "`--personal` cannot be combined with explicit [paths]: " +
+        "positional paths bypass the PERSONAL_VAULT_EXCLUDED_TOP_LEVEL " +
+        "guard (skips .git/, companies/, repos/, workspace/), risking " +
+        "cross-scope upload of company data to the personal vault. " +
+        "Use bare `--personal` to push the whole personal scope, OR " +
+        "drop `--personal` to push specific paths to the active company.",
+    );
+  }
+}
+
 /**
  * Refuse ambiguous selector combinations. `--all`, `--personal`, and
  * `--company` are mutually exclusive — at most one may be set per
@@ -608,6 +655,15 @@ export function registerCloudCommands(program: Command): void {
         "(.git, companies, repos, workspace) — same scope as `--all`'s " +
         "personal slot. Mutually exclusive with --company and --all.",
     )
+    .option(
+      "--no-personal",
+      "In `--all` mode, skip the canonical-person leg of the fanout — " +
+        "only push to the caller's company memberships. Mirrors the " +
+        "upstream `hq-sync-runner --skip-personal` flag (hq-cloud 5.25.0); " +
+        "wired so the AppBar HQ Sync menubar can drop personal sync via " +
+        "a toggle, and so CLI users can opt out one-off. Ignored outside " +
+        "`--all`.",
+    )
     .action(
       async (
         paths: string[],
@@ -649,10 +705,17 @@ export function registerCloudCommands(program: Command): void {
             );
             process.exit(1);
           }
+          // `options.personal === false` happens when the user passed
+          // `--no-personal` (Commander's auto-negation of the `--personal`
+          // selector). In `--all` mode that means "skip the personal leg of
+          // the fanout" — wired through to `pushAll.skipPersonal`. Outside
+          // `--all` the flag has no effect (logged above as part of the
+          // option's help text).
           await runPushAll(
             options.hqRoot,
             options.message,
             options.onConflict,
+            options.personal === false,
           );
           return;
         }
@@ -675,6 +738,8 @@ export function registerCloudCommands(program: Command): void {
                 "to have already resolved entity + credentials. Pick one.",
             );
           }
+          // Closes hq-cli#25 — see `assertNoPersonalPositionalPaths` doc-block.
+          assertNoPersonalPositionalPaths(options, paths);
 
           log(chalk.bold("\nHQ Sync — Push"));
           log(`  HQ root:  ${options.hqRoot}`);
@@ -854,6 +919,13 @@ export function registerCloudCommands(program: Command): void {
         "from the cached Cognito session. Mutually exclusive with --company " +
         "and --all.",
     )
+    .option(
+      "--no-personal",
+      "In `--all` mode, skip the canonical-person leg of the fanout — " +
+        "only pull the caller's company memberships. Mirrors the upstream " +
+        "`hq-sync-runner --skip-personal` flag (hq-cloud 5.25.0). Ignored " +
+        "outside `--all`.",
+    )
     .option(
       "--mode-all",
       "US-011: opt out of the strict narrow-hint refusal for this run. " +
@@ -880,10 +952,14 @@ export function registerCloudCommands(program: Command): void {
           process.exit(1);
         }
         if (options.all) {
+          // `options.personal === false` is Commander's auto-negation of
+          // `--personal`; in `--all` mode that means "drop the personal
+          // leg from the fanout" (see `--no-personal` option above).
           await runPullAll(
             options.hqRoot,
             options.onConflict,
             options.modeAll === true,
+            options.personal === false,
           );
           return;
         }
@@ -1069,6 +1145,13 @@ export function registerCloudCommands(program: Command): void {
       "Sync the caller's canonical personal vault bidirectionally. " +
         "Mutually exclusive with --company and --all.",
     )
+    .option(
+      "--no-personal",
+      "In `--all` mode, skip the canonical-person leg of both the push " +
+        "and pull fanouts — only sync the caller's company memberships. " +
+        "Mirrors the upstream `hq-sync-runner --skip-personal` flag " +
+        "(hq-cloud 5.25.0). Ignored outside `--all`.",
+    )
     .option(
       "--mode-all",
       "US-011: opt out of the strict narrow-hint refusal for this run. " +
@@ -1088,11 +1171,16 @@ export function registerCloudCommands(program: Command): void {
         try {
           assertSingleSelector(options, "now");
           if (options.all) {
+            // `options.personal === false` is Commander's auto-negation
+            // of `--personal`; in `--all` mode that means "drop the
+            // personal leg from both legs of the bidirectional fanout"
+            // (see `--no-personal` option above).
             await runNowAll(
               options.hqRoot,
               options.message,
               options.onConflict,
               options.modeAll === true,
+              options.personal === false,
             );
             return;
           }
@@ -1119,10 +1207,15 @@ async function runPullAll(
   hqRoot: string,
   onConflict?: ConflictStrategy,
   modeAllOverride?: boolean,
+  skipPersonal?: boolean,
 ): Promise<void> {
   console.log(chalk.bold("\nHQ Sync — Pull (all)"));
   console.log(`  HQ root:  ${hqRoot}`);
-  console.log(`  Strategy: ${onConflict ?? "(interactive)"}\n`);
+  console.log(`  Strategy: ${onConflict ?? "(interactive)"}`);
+  if (skipPersonal) {
+    console.log(`  Personal: skipped (--no-personal)`);
+  }
+  console.log("");
 
   let result: PullAllResult;
   try {
@@ -1150,6 +1243,7 @@ async function runPullAll(
         ...(onConflict ? { onConflict } : {}),
         narrowHintLevel: resolveBannerLevel(),
         ...(modeAllOverride ? { modeAllOverride: true } : {}),
+        ...(skipPersonal ? { skipPersonal: true } : {}),
       },
       {
         vaultClient: adapter,
@@ -1254,10 +1348,15 @@ async function runPushAll(
   hqRoot: string,
   message?: string,
   onConflict?: ConflictStrategy,
+  skipPersonal?: boolean,
 ): Promise<void> {
   console.log(chalk.bold("\nHQ Sync — Push (all)"));
   console.log(`  HQ root:  ${hqRoot}`);
-  console.log(`  Strategy: ${onConflict ?? "(interactive)"}\n`);
+  console.log(`  Strategy: ${onConflict ?? "(interactive)"}`);
+  if (skipPersonal) {
+    console.log(`  Personal: skipped (--no-personal)`);
+  }
+  console.log("");
 
   let result: PushAllResult;
   try {
@@ -1283,6 +1382,7 @@ async function runPushAll(
         hqRoot,
         ...(onConflict ? { onConflict } : {}),
         ...(message ? { message } : {}),
+        ...(skipPersonal ? { skipPersonal: true } : {}),
       },
       {
         vaultClient: adapter,
@@ -1521,21 +1621,26 @@ async function runNowAll(
   message?: string,
   onConflict?: ConflictStrategy,
   modeAllOverride?: boolean,
+  skipPersonal?: boolean,
 ): Promise<void> {
   console.log(chalk.bold("\nHQ Sync — Now (all)"));
   console.log(`  HQ root:  ${hqRoot}`);
-  console.log(`  Strategy: ${onConflict ?? "(interactive)"}\n`);
+  console.log(`  Strategy: ${onConflict ?? "(interactive)"}`);
+  if (skipPersonal) {
+    console.log(`  Personal: skipped (--no-personal)`);
+  }
+  console.log("");
 
   // Push first (matches runner), then pull. Re-uses the per-leg orchestrators
   // so the per-target rendering, error isolation, and exit codes are
   // identical to running `push --all` then `pull --all` back-to-back.
   console.log(chalk.dim("→ push --all"));
-  await runPushAll(hqRoot, message, onConflict);
+  await runPushAll(hqRoot, message, onConflict, skipPersonal);
   console.log(chalk.dim("\n→ pull --all"));
   // 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);
+  await runPullAll(hqRoot, onConflict, modeAllOverride, skipPersonal);
 }
 
 /**