@indigoai-us/hq-cloud 5.39.0 → 5.41.0

package/dist/qmd-reindex.test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Unit tests for reindexAfterSync.
+ *
+ * The function shells out to the global `qmd` binary, so every test injects a
+ * fake `exec` that records the calls and returns canned results — no real qmd
+ * is invoked. We assert on the *sequence of qmd commands* the function would
+ * run, which is the contract that keeps a teammate's index fresh after sync.
+ */
+export {};
+//# sourceMappingURL=qmd-reindex.test.d.ts.map

package/dist/qmd-reindex.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"qmd-reindex.test.d.ts","sourceRoot":"","sources":["../src/qmd-reindex.test.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/qmd-reindex.test.js

@@ -0,0 +1,129 @@
+/**
+ * Unit tests for reindexAfterSync.
+ *
+ * The function shells out to the global `qmd` binary, so every test injects a
+ * fake `exec` that records the calls and returns canned results — no real qmd
+ * is invoked. We assert on the *sequence of qmd commands* the function would
+ * run, which is the contract that keeps a teammate's index fresh after sync.
+ */
+import { describe, it, expect } from "vitest";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { reindexAfterSync } from "./qmd-reindex.js";
+/** Build a fake exec that returns status 0 for everything and logs calls. */
+function fakeExec(opts) {
+    const calls = [];
+    const exec = (args) => {
+        calls.push(args);
+        if (opts?.failOn && args[0] === opts.failOn)
+            return { status: 1, stdout: "" };
+        if (args[0] === "collection" && args[1] === "list") {
+            return { status: 0, stdout: opts?.listStdout ?? "" };
+        }
+        return { status: 0, stdout: "" };
+    };
+    return { exec, calls };
+}
+describe("reindexAfterSync", () => {
+    it("no-ops when the path is not an HQ root", () => {
+        const { exec, calls } = fakeExec();
+        const r = reindexAfterSync("/tmp/not-hq", {
+            exec,
+            existsSync: () => false, // core/core.yaml absent
+        });
+        expect(r.qmdAvailable).toBe(false);
+        expect(calls).toHaveLength(0);
+    });
+    it("no-ops when qmd is unavailable (collection list errors)", () => {
+        const { exec, calls } = fakeExec({ failOn: "collection" });
+        const r = reindexAfterSync("/hq", {
+            exec,
+            existsSync: () => true, // core.yaml present
+        });
+        expect(r.qmdAvailable).toBe(false);
+        expect(r.updated).toBe(false);
+        // Only the availability probe ran, then bailed.
+        expect(calls).toEqual([["collection", "list"]]);
+    });
+    it("registers a missing company collection then runs an incremental update", () => {
+        const { exec, calls } = fakeExec({ listStdout: "Collections (1):\n\nHQ (qmd://HQ/)\n" });
+        const r = reindexAfterSync("/hq", {
+            exec,
+            existsSync: () => true,
+            readCompanies: () => ["acme"],
+            hasIndexableMarkdown: () => true,
+        });
+        expect(r.qmdAvailable).toBe(true);
+        expect(r.collectionsAdded).toEqual(["acme"]);
+        expect(r.updated).toBe(true);
+        expect(r.embedded).toBe(false);
+        // Expected command sequence: probe, add, context, update.
+        expect(calls).toEqual([
+            ["collection", "list"],
+            ["collection", "add", path.join("/hq", "companies", "acme", "knowledge"), "--name", "acme", "--mask", "**/*.md"],
+            ["context", "add", "qmd://acme", "Knowledge base for acme."],
+            ["update"],
+        ]);
+    });
+    it("skips collections that already exist", () => {
+        const { exec, calls } = fakeExec({ listStdout: "acme (qmd://acme/)\n" });
+        const r = reindexAfterSync("/hq", {
+            exec,
+            existsSync: () => true,
+            readCompanies: () => ["acme"],
+            hasIndexableMarkdown: () => true,
+        });
+        expect(r.collectionsAdded).toEqual([]);
+        // No `collection add` — straight to update.
+        expect(calls).toEqual([["collection", "list"], ["update"]]);
+    });
+    it("skips company dirs with no indexable markdown", () => {
+        const { exec, calls } = fakeExec({ listStdout: "" });
+        const r = reindexAfterSync("/hq", {
+            exec,
+            existsSync: () => true,
+            readCompanies: () => ["empty"],
+            hasIndexableMarkdown: () => false,
+        });
+        expect(r.collectionsAdded).toEqual([]);
+        expect(calls).toEqual([["collection", "list"], ["update"]]);
+    });
+    it("runs embed only when embed:true", () => {
+        const { exec, calls } = fakeExec({ listStdout: "" });
+        const r = reindexAfterSync("/hq", {
+            exec,
+            existsSync: () => true,
+            readCompanies: () => [],
+            embed: true,
+        });
+        expect(r.embedded).toBe(true);
+        expect(calls).toEqual([["collection", "list"], ["update"], ["embed"]]);
+    });
+    it("never throws even if exec misbehaves", () => {
+        const exec = () => {
+            throw new Error("boom");
+        };
+        expect(() => reindexAfterSync("/hq", { exec, existsSync: () => true })).not.toThrow();
+    });
+    it("hasIndexableMarkdown finds a real .md and ignores INDEX.md", () => {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-qmd-test-"));
+        try {
+            const hq = path.join(dir, "hq");
+            const kdir = path.join(hq, "companies", "acme", "knowledge");
+            fs.mkdirSync(kdir, { recursive: true });
+            fs.mkdirSync(path.join(hq, "core"), { recursive: true });
+            fs.writeFileSync(path.join(hq, "core", "core.yaml"), "hqVersion: 1\n");
+            fs.writeFileSync(path.join(kdir, "INDEX.md"), "# index\n");
+            fs.writeFileSync(path.join(kdir, "note.md"), "# real\n");
+            const { exec, calls } = fakeExec({ listStdout: "" });
+            const r = reindexAfterSync(hq, { exec }); // real fs walk for md detection
+            expect(r.collectionsAdded).toEqual(["acme"]);
+            expect(calls.some((c) => c[0] === "collection" && c[1] === "add")).toBe(true);
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+});
+//# sourceMappingURL=qmd-reindex.test.js.map

package/dist/qmd-reindex.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"qmd-reindex.test.js","sourceRoot":"","sources":["../src/qmd-reindex.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cloud",
-  "version": "5.39.0",
+  "version": "5.41.0",
   "description": "HQ by Indigo cloud sync engine — bidirectional S3 sync for mobile access",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

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

@@ -88,6 +88,7 @@ import type { ShareOptions, ShareResult } from "../cli/share.js";
 import type { ConflictStrategy } from "../cli/conflict.js";
 import type { UploadAuthor } from "../s3.js";
 import { collectAndSendTelemetry } from "../telemetry.js";
+import { reindexAfterSync } from "../qmd-reindex.js";
 import { describeError } from "../lib/describe-error.js";
 import { getOrCreateMachineId } from "../lib/machine-id.js";
 import {
@@ -501,6 +502,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 +540,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 +559,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 +629,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 +652,7 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
   return {
     companies,
     company,
+    personal,
     onConflict,
     hqRoot,
     direction,
@@ -774,7 +805,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 +879,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 +891,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 +909,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;
     }
   }
 
@@ -1337,6 +1390,21 @@ export async function runRunner(
     partial,
     companies,
   });
+
+  // Post-sync qmd reindex — runs AFTER `all-complete` is emitted so the
+  // menubar/CLI already shows the sync as done; this is a best-effort tail
+  // step that never affects the exit code. Only when files were actually
+  // pulled in (nothing to reindex otherwise) and not explicitly disabled.
+  // Self-contained: shells out to the global `qmd` binary, no dependency on
+  // any (possibly stale) script inside the synced HQ tree. See qmd-reindex.ts.
+  if (totalDownloaded > 0 && process.env.HQ_QMD_REINDEX_ON_SYNC !== "0") {
+    try {
+      reindexAfterSync(parsed.hqRoot);
+    } catch {
+      // Defensive: reindexAfterSync already swallows internally.
+    }
+  }
+
   // Exit 2 only when something actually threw (`errors.length > 0`). A clean
   // conflict-abort sets `partial: true` in the JSON but exits 0 — the Tauri
   // menubar's non-zero-exit Sentry capture would otherwise fire for normal