@indigoai-us/hq-cloud 5.39.0 → 5.40.0

package/src/bin/sync-runner.test.ts

@@ -205,7 +205,7 @@ describe("argv parsing", () => {
     const deps = makeDeps();
     const code = await runRunner([], deps);
     expect(code).toBe(1);
-    expect(deps.stderr.raw()).toContain("--companies or --company");
+    expect(deps.stderr.raw()).toContain("--personal");
     expect(deps.stdout.events()).toEqual([]);
   });
 
@@ -582,6 +582,227 @@ describe("target resolution", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// --personal mode (personal-vault-only, skip company fanout)
+// ---------------------------------------------------------------------------
+//
+// `--personal` is mutually exclusive with `--companies` and `--company`. It
+// runs ONLY the personal-vault target — no listMyMemberships call, no
+// claim-dance, no cloud-company fanout. Designed as the replacement
+// pathway for Rust's `personal.rs::run_personal_first_push` (the menubar's
+// first-push), so the entire personal-vault walker lives in one place
+// (hq-cloud TS) and not in two duplicate engines.
+
+describe("--personal mode", () => {
+  it("argv: --personal + --companies is rejected", async () => {
+    const deps = makeDeps();
+    const code = await runRunner(["--personal", "--companies"], deps);
+    expect(code).toBe(1);
+    expect(deps.stderr.raw()).toContain("mutually exclusive");
+  });
+
+  it("argv: --personal + --company X is rejected", async () => {
+    const deps = makeDeps();
+    const code = await runRunner(["--personal", "--company", "cmp_x"], deps);
+    expect(code).toBe(1);
+    expect(deps.stderr.raw()).toContain("mutually exclusive");
+  });
+
+  it("argv: --personal + --skip-personal is rejected (contradictory)", async () => {
+    const deps = makeDeps();
+    const code = await runRunner(["--personal", "--skip-personal"], deps);
+    expect(code).toBe(1);
+    expect(deps.stderr.raw()).toContain("contradictory");
+  });
+
+  it("does NOT call listMyMemberships (skips company-discovery API entirely)", async () => {
+    const listSpy = vi.fn();
+    const deps = makeDeps({
+      createVaultClient: () => ({
+        ...makeVaultStub({
+          listPersons: () =>
+            Promise.resolve([
+              {
+                uid: "ent_person_1",
+                type: "person",
+                bucketName: "hq-vault-personal-1",
+                status: "active",
+              } as unknown as EntityInfo,
+            ]),
+        }),
+        listMyMemberships: listSpy as unknown as () => Promise<Membership[]>,
+      }),
+    });
+    const code = await runRunner(["--personal"], deps);
+    expect(code).toBe(0);
+    expect(listSpy).not.toHaveBeenCalled();
+  });
+
+  it("does NOT run claim-dance (skips pending-invites + ensurePerson)", async () => {
+    const claimSpy = vi.fn();
+    const ensureSpy = vi.fn();
+    const deps = makeDeps({
+      createVaultClient: () => ({
+        ...makeVaultStub({
+          listPersons: () =>
+            Promise.resolve([
+              {
+                uid: "ent_person_1",
+                type: "person",
+                bucketName: "hq-vault-personal-1",
+                status: "active",
+              } as unknown as EntityInfo,
+            ]),
+        }),
+        claimPendingInvitesByEmail:
+          claimSpy as unknown as (uid: string) => Promise<void>,
+        ensureMyPersonEntity:
+          ensureSpy as unknown as VaultClientSurface["ensureMyPersonEntity"],
+      }),
+      getIdTokenClaims: () => ({
+        sub: "sub-abc",
+        email: "user@example.com",
+        name: "User Name",
+      }),
+    });
+    const code = await runRunner(["--personal"], deps);
+    expect(code).toBe(0);
+    expect(claimSpy).not.toHaveBeenCalled();
+    expect(ensureSpy).not.toHaveBeenCalled();
+  });
+
+  it("emits fanout-plan with exactly one personal entry", async () => {
+    const deps = makeDeps({
+      createVaultClient: () =>
+        makeVaultStub({
+          listPersons: () =>
+            Promise.resolve([
+              {
+                uid: "ent_person_1",
+                type: "person",
+                bucketName: "hq-vault-personal-1",
+                status: "active",
+              } as unknown as EntityInfo,
+            ]),
+        }),
+    });
+    const code = await runRunner(["--personal"], deps);
+    expect(code).toBe(0);
+    const plan = deps.stdout
+      .events()
+      .find((e) => e.type === "fanout-plan") as Extract<
+        RunnerEvent,
+        { type: "fanout-plan" }
+      >;
+    expect(plan).toBeDefined();
+    expect(plan.companies).toHaveLength(1);
+    expect(plan.companies[0]).toMatchObject({ slug: "personal" });
+  });
+
+  it("calls syncFn ONCE with personalMode=true (default direction=pull)", async () => {
+    const deps = makeDeps({
+      createVaultClient: () =>
+        makeVaultStub({
+          listPersons: () =>
+            Promise.resolve([
+              {
+                uid: "ent_person_1",
+                type: "person",
+                bucketName: "hq-vault-personal-1",
+                status: "active",
+              } as unknown as EntityInfo,
+            ]),
+        }),
+    });
+    const code = await runRunner(["--personal"], deps);
+    expect(code).toBe(0);
+    expect(deps.sync).toHaveBeenCalledTimes(1);
+    const call = (deps.sync as ReturnType<typeof vi.fn>).mock
+      .calls[0][0] as SyncOptions;
+    expect(call.personalMode).toBe(true);
+  });
+
+  it("--personal --direction push calls shareFn with personalMode + computePersonalVaultPaths", async () => {
+    const shareSpy = vi.fn().mockResolvedValue({
+      filesUploaded: 0,
+      bytesUploaded: 0,
+      filesSkipped: 0,
+      filesDeleted: 0,
+      conflictPaths: [],
+      aborted: false,
+    });
+    const deps = makeDeps({
+      share: shareSpy as unknown as RunnerDeps["share"],
+      createVaultClient: () =>
+        makeVaultStub({
+          listPersons: () =>
+            Promise.resolve([
+              {
+                uid: "ent_person_1",
+                type: "person",
+                bucketName: "hq-vault-personal-1",
+                status: "active",
+              } as unknown as EntityInfo,
+            ]),
+        }),
+    });
+    const code = await runRunner(["--personal", "--direction", "push"], deps);
+    expect(code).toBe(0);
+    expect(shareSpy).toHaveBeenCalledTimes(1);
+    const opts = shareSpy.mock.calls[0][0];
+    expect(opts.personalMode).toBe(true);
+    // paths come from computePersonalVaultPaths — non-empty array of
+    // absolute hqRoot-anchored paths. Don't pin the exact contents
+    // (depends on hqRoot's local layout); just confirm the shape.
+    expect(Array.isArray(opts.paths)).toBe(true);
+  });
+
+  it("no person entity → emits setup-needed event, exit 0 (same shape as --companies)", async () => {
+    const deps = makeDeps({
+      createVaultClient: () =>
+        makeVaultStub({
+          listPersons: () => Promise.resolve([]),
+        }),
+    });
+    const code = await runRunner(["--personal"], deps);
+    expect(code).toBe(0);
+    expect(
+      deps.stdout.events().some((e) => e.type === "setup-needed"),
+    ).toBe(true);
+    expect(deps.sync).not.toHaveBeenCalled();
+  });
+
+  it("--personal honors --direction both (calls both shareFn and syncFn)", async () => {
+    const shareSpy = vi.fn().mockResolvedValue({
+      filesUploaded: 0,
+      bytesUploaded: 0,
+      filesSkipped: 0,
+      filesDeleted: 0,
+      conflictPaths: [],
+      aborted: false,
+    });
+    const deps = makeDeps({
+      share: shareSpy as unknown as RunnerDeps["share"],
+      createVaultClient: () =>
+        makeVaultStub({
+          listPersons: () =>
+            Promise.resolve([
+              {
+                uid: "ent_person_1",
+                type: "person",
+                bucketName: "hq-vault-personal-1",
+                status: "active",
+              } as unknown as EntityInfo,
+            ]),
+        }),
+    });
+    const code = await runRunner(["--personal", "--direction", "both"], deps);
+    expect(code).toBe(0);
+    expect(shareSpy).toHaveBeenCalledTimes(1);
+    expect(deps.sync).toHaveBeenCalledTimes(1);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // fanout-plan
 // ---------------------------------------------------------------------------

package/src/bin/sync-runner.ts

@@ -501,6 +501,16 @@ async function runClaimDance(
 interface ParsedArgs {
   companies: boolean;
   company?: string;
+  /**
+   * Personal-vault-only mode. Mutually exclusive with `--companies` and
+   * `--company`. Skips `listMyMemberships` (and therefore the claim-dance);
+   * builds a fanout plan containing ONLY the personal target. Designed as
+   * the runner-side entry point that replaces Rust's
+   * `personal.rs::run_personal_first_push` first-push walker — so the
+   * personal-vault scope (`computePersonalVaultPaths`) lives in exactly
+   * one place (this TS engine) and not duplicated across engines.
+   */
+  personal: boolean;
   onConflict: ConflictStrategy;
   hqRoot: string;
   direction: Direction;
@@ -529,6 +539,7 @@ interface ParsedArgs {
 function parseArgs(argv: string[]): ParsedArgs | { error: string } {
   let companies = false;
   let company: string | undefined;
+  let personal = false;
   let onConflict: ConflictStrategy = "abort";
   let hqRoot = DEFAULT_HQ_ROOT;
   let direction: Direction = "pull";
@@ -547,6 +558,14 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
         company = argv[++i];
         if (!company) return { error: "--company requires a value" };
         break;
+      case "--personal":
+        // Personal-vault-only mode. Skips listMyMemberships + claim-dance
+        // entirely; builds a fanout plan containing only the personal target.
+        // Replaces Rust's personal.rs::run_personal_first_push walker —
+        // the personal-vault scope (computePersonalVaultPaths) is owned
+        // by this engine, not duplicated across Rust + TS.
+        personal = true;
+        break;
       case "--on-conflict": {
         const val = argv[++i];
         if (val !== "abort" && val !== "overwrite" && val !== "keep") {
@@ -609,8 +628,18 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
   if (companies && company) {
     return { error: "Pass --companies OR --company <slug>, not both" };
   }
-  if (!companies && !company) {
-    return { error: "Pass --companies or --company <slug>" };
+  if (personal && (companies || company)) {
+    return {
+      error: "--personal is mutually exclusive with --companies / --company",
+    };
+  }
+  if (personal && skipPersonal) {
+    return {
+      error: "--personal and --skip-personal are contradictory",
+    };
+  }
+  if (!companies && !company && !personal) {
+    return { error: "Pass --companies, --company <slug>, or --personal" };
   }
   if (pollRemoteMs !== undefined && !watch) {
     return { error: "--poll-remote-ms requires --watch" };
@@ -622,6 +651,7 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
   return {
     companies,
     company,
+    personal,
     onConflict,
     hqRoot,
     direction,
@@ -774,7 +804,15 @@ export async function runRunner(
   // ---- resolve targets --------------------------------------------------
   let memberships: Pick<Membership, "companyUid">[];
   try {
-    if (parsed.companies) {
+    if (parsed.personal) {
+      // Personal-vault-only mode: skip listMyMemberships entirely (and
+      // therefore the claim-dance). The fanout plan is built solely from
+      // the person-entity lookup below — no cloud-company targets, no
+      // /membership/me round-trip. setup-needed is deferred to the
+      // person-entity check (firing only when the personal entity is
+      // also absent, not when memberships are empty by design).
+      memberships = [];
+    } else if (parsed.companies) {
       // Before giving up on memberships, run the claim-dance: new users signed
       // in via the tray may have email-keyed invites waiting for them. Without
       // this, an invited user would see "setup-needed" on every tray click.
@@ -840,7 +878,10 @@ export async function runRunner(
     plan.push({ uid: m.companyUid, slug, ...(name ? { name } : {}) });
   }
 
-  if (parsed.companies && !resolveSkipPersonal(parsed.skipPersonal)) {
+  if (
+    (parsed.companies || parsed.personal) &&
+    !resolveSkipPersonal(parsed.skipPersonal)
+  ) {
     // Personal-target fanout slot. Skipped entirely when --skip-personal
     // (or HQ_SYNC_SKIP_PERSONAL=1) is set — see resolveSkipPersonal doc for
     // the rationale (menubar opt-out for users who only want company sync).
@@ -849,6 +890,9 @@ export async function runRunner(
     // workspaces row, status surfaces) should already tolerate that
     // shape since pre-5.25 fanout often had it (a user with no person
     // entity yet, or before the canonical-person-entity machinery landed).
+    //
+    // `--personal` mode reaches this block with an empty `plan` and
+    // empty `memberships`; only the personal target gets added below.
     const persons = await client.entity.listByType("person");
     const pick = pickCanonicalPersonEntity(persons);
     if (pick?.bucketName) {
@@ -864,6 +908,14 @@ export async function runRunner(
         // root-cause writeup.
         journalSlug: PERSONAL_VAULT_JOURNAL_SLUG,
       });
+    } else if (parsed.personal) {
+      // --personal mode with no canonical personal entity → setup-needed.
+      // (In --companies mode this state is silent — companies still sync
+      // and the missing personal target just shows an empty workspaces row.
+      // In --personal mode it's the ONLY signal, so it gets surfaced as
+      // setup-needed with the same shape as the empty-memberships case.)
+      emit({ type: "setup-needed" });
+      return 0;
     }
   }