@indigoai-us/hq-cloud 5.43.0 → 5.45.0

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

@@ -19,6 +19,7 @@ import {
   routeChangeToTarget,
   buildTargetedPushArgv,
   resolvePullScope,
+  readPinnedPrefixes,
 } from "./sync-runner.js";
 import type {
   RunnerEvent,
@@ -3338,4 +3339,138 @@ describe("resolvePullScope", () => {
     );
     expect(scope).toEqual({ syncMode: "all" });
   });
+
+  // ── pin union (Phase C: hq files get) ──────────────────────────────────────
+
+  it("unions pinned prefixes into a shared-mode scope", async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "hq-pins-shared-"));
+    try {
+      fs.mkdirSync(path.join(root, ".hq"), { recursive: true });
+      fs.writeFileSync(
+        path.join(root, ".hq", "pins.json"),
+        JSON.stringify({ version: 1, pins: { acme: ["pinned/dir/"] } }),
+      );
+      const scope = await resolvePullScope(
+        stubClient({
+          listMyMemberships: async () => [membership("cmp_a", "mk_a")],
+          getMembershipSyncConfig: async () => ({
+            membershipId: "mk_a",
+            syncMode: "shared",
+            isDefault: false,
+          }),
+          listMyExplicitGrants: async () =>
+            [{ companyUid: "cmp_a", path: "knowledge/", permission: "read", source: "person" }] as never,
+        }),
+        "cmp_a",
+        "acme",
+        root,
+      );
+      expect(scope.syncMode).toBe("shared");
+      // Grant prefix + pinned prefix, coalesced + sorted.
+      expect(scope.prefixSet).toEqual(["knowledge/", "pinned/dir/"]);
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it("unions pinned prefixes into a custom-mode scope", async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "hq-pins-custom-"));
+    try {
+      fs.mkdirSync(path.join(root, ".hq"), { recursive: true });
+      fs.writeFileSync(
+        path.join(root, ".hq", "pins.json"),
+        JSON.stringify({ version: 1, pins: { acme: ["extra/"] } }),
+      );
+      const scope = await resolvePullScope(
+        stubClient({
+          listMyMemberships: async () => [membership("cmp_a", "mk_a")],
+          getMembershipSyncConfig: async () => ({
+            membershipId: "mk_a",
+            syncMode: "custom",
+            customPaths: ["projects/x/"],
+            isDefault: false,
+          }),
+        }),
+        "cmp_a",
+        "acme",
+        root,
+      );
+      expect(scope.syncMode).toBe("custom");
+      expect(scope.prefixSet).toEqual(["extra/", "projects/x/"]);
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it("ignores pins for other companies (per-slug isolation)", async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "hq-pins-iso-"));
+    try {
+      fs.mkdirSync(path.join(root, ".hq"), { recursive: true });
+      fs.writeFileSync(
+        path.join(root, ".hq", "pins.json"),
+        JSON.stringify({ version: 1, pins: { beta: ["beta-only/"] } }),
+      );
+      const scope = await resolvePullScope(
+        stubClient({
+          listMyMemberships: async () => [membership("cmp_a", "mk_a")],
+          getMembershipSyncConfig: async () => ({
+            membershipId: "mk_a",
+            syncMode: "shared",
+            isDefault: false,
+          }),
+          listMyExplicitGrants: async () =>
+            [{ companyUid: "cmp_a", path: "knowledge/", permission: "read", source: "person" }] as never,
+        }),
+        "cmp_a",
+        "acme",
+        root,
+      );
+      // beta's pin must not leak into acme's scope.
+      expect(scope.prefixSet).toEqual(["knowledge/"]);
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// readPinnedPrefixes — per-machine pin set reader
+// ---------------------------------------------------------------------------
+
+describe("readPinnedPrefixes", () => {
+  let root: string;
+  beforeEach(() => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), "hq-readpins-"));
+  });
+  afterEach(() => {
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  it("returns [] when the pins file is missing", () => {
+    expect(readPinnedPrefixes(root, "acme")).toEqual([]);
+  });
+
+  it("returns the company's pinned prefixes", () => {
+    fs.mkdirSync(path.join(root, ".hq"), { recursive: true });
+    fs.writeFileSync(
+      path.join(root, ".hq", "pins.json"),
+      JSON.stringify({ version: 1, pins: { acme: ["a/", "b/"], beta: ["c/"] } }),
+    );
+    expect(readPinnedPrefixes(root, "acme")).toEqual(["a/", "b/"]);
+  });
+
+  it("drops empty-string entries (an everything-pin is meaningless here)", () => {
+    fs.mkdirSync(path.join(root, ".hq"), { recursive: true });
+    fs.writeFileSync(
+      path.join(root, ".hq", "pins.json"),
+      JSON.stringify({ version: 1, pins: { acme: ["", "real/"] } }),
+    );
+    expect(readPinnedPrefixes(root, "acme")).toEqual(["real/"]);
+  });
+
+  it("returns [] on a corrupt pins file", () => {
+    fs.mkdirSync(path.join(root, ".hq"), { recursive: true });
+    fs.writeFileSync(path.join(root, ".hq", "pins.json"), "{ not json");
+    expect(readPinnedPrefixes(root, "acme")).toEqual([]);
+  });
 });

package/src/bin/sync-runner.ts

@@ -379,6 +379,9 @@ export async function resolvePullScope(
   // Company slug — required to normalize grant paths (which may be anchored
   // at `companies/<slug>/` or `<slug>/`) into the company-relative namespace.
   slug: string,
+  // Local HQ root — used to read the per-machine pin set (`.hq/pins.json`).
+  // When omitted, pins are simply not unioned (no behavior change).
+  hqRoot?: string,
 ): Promise<PullScope> {
   if (!client.getMembershipSyncConfig) return { syncMode: "all" };
   try {
@@ -387,6 +390,14 @@ export async function resolvePullScope(
     if (!m) return { syncMode: "all" };
     const cfg = await client.getMembershipSyncConfig(m.membershipKey);
     if (cfg.syncMode === "all") return { syncMode: "all" };
+
+    // Pins are company-relative prefixes a user explicitly materialized via
+    // `hq files get`. They're unioned into the scope so a scoped pull keeps
+    // them instead of pruning them as out-of-scope orphans. Pins only WIDEN
+    // scope, never narrow — and `all` mode (handled above) ignores them since
+    // it pulls everything anyway.
+    const pinPrefixes = hqRoot ? readPinnedPrefixes(hqRoot, slug) : [];
+
     if (cfg.syncMode === "custom") {
       const customPrefixes = (cfg.customPaths ?? []).map((p) =>
         grantPathToPrefix(p, slug),
@@ -395,7 +406,10 @@ export async function resolvePullScope(
       // `coalescePrefixes` (which drops empties) to "nothing", which would
       // prune the whole tree. An everything-scope is semantically `all`.
       if (customPrefixes.some((p) => p === "")) return { syncMode: "all" };
-      return { syncMode: "custom", prefixSet: coalescePrefixes(customPrefixes) };
+      return {
+        syncMode: "custom",
+        prefixSet: coalescePrefixes([...customPrefixes, ...pinPrefixes]),
+      };
     }
     // shared: scope to the caller's explicit grants. Real grant paths are
     // inconsistent — full (`companies/<slug>/x/*`), slug-anchored
@@ -416,13 +430,42 @@ export async function resolvePullScope(
     // `coalescePrefixes` drops empties (collapsing "everything" to "nothing"),
     // treat any such grant as full-access `all` rather than risk pruning.
     if (sharedPrefixes.some((p) => p === "")) return { syncMode: "all" };
-    return { syncMode: "shared", prefixSet: coalescePrefixes(sharedPrefixes) };
+    return {
+      syncMode: "shared",
+      prefixSet: coalescePrefixes([...sharedPrefixes, ...pinPrefixes]),
+    };
   } catch {
     // Degrade to `all` — never prune on a resolution failure.
     return { syncMode: "all" };
   }
 }
 
+/**
+ * Read the per-machine pin set (`<hqRoot>/.hq/pins.json`) and return the
+ * company-relative pinned prefixes for `slug`. These are prefixes the user
+ * materialized on demand via `hq files get` that must survive a scoped pull.
+ *
+ * Tolerant by construction: a missing, unreadable, or malformed file yields
+ * `[]` (no pins) — pins only ever widen scope, so "no pins" is the safe
+ * default. Empty-string entries are dropped (an everything-pin is meaningless
+ * here; `all` mode already covers that case).
+ */
+export function readPinnedPrefixes(hqRoot: string, slug: string): string[] {
+  try {
+    const raw = fs.readFileSync(path.join(hqRoot, ".hq", "pins.json"), "utf-8");
+    const parsed = JSON.parse(raw) as { pins?: Record<string, unknown> };
+    const list = parsed?.pins?.[slug];
+    if (Array.isArray(list)) {
+      return list.filter(
+        (p): p is string => typeof p === "string" && p.length > 0,
+      );
+    }
+  } catch {
+    /* missing / unreadable / malformed → no pins */
+  }
+  return [];
+}
+
 /**
  * Backoff schedule (in ms) between attempts 2 and 3 of
  * `listMembershipsWithRetry`. Short on purpose — memberships is a single
@@ -1259,7 +1302,12 @@ export async function runRunner(
         const pullScope: PullScope =
           target.personalMode === true
             ? { syncMode: "all" }
-            : await resolvePullScope(client, target.uid, target.slug);
+            : await resolvePullScope(
+                client,
+                target.uid,
+                target.slug,
+                parsed.hqRoot,
+              );
         pullResult = await syncFn({
           company: target.uid,
           vaultConfig,

package/src/cli/sync.test.ts

@@ -1233,6 +1233,87 @@ describe("sync", () => {
     );
   });
 
+  it("reports new files to POST /v1/notify/file-added with company + file metadata", async () => {
+    vi.mocked(s3Module.headRemoteFile).mockImplementation(async (_ctx, key) => {
+      if (key === "docs/handoff.md") {
+        return {
+          lastModified: new Date(),
+          etag: '"abc123"',
+          size: 42,
+          metadata: { "created-by": "alice@example.com" } as Record<string, string>,
+        };
+      }
+      if (key === "knowledge/readme.md") {
+        return {
+          lastModified: new Date(),
+          etag: '"def456"',
+          size: 100,
+          metadata: {} as Record<string, string>,
+        };
+      }
+      return null;
+    });
+
+    await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      onEvent: () => {},
+    });
+
+    const calls = vi.mocked(globalThis.fetch).mock.calls as Array<
+      [string, RequestInit?]
+    >;
+    const post = calls.find(([u]) =>
+      String(u).includes("/v1/notify/file-added"),
+    );
+    expect(post).toBeDefined();
+    expect(String(post![0])).toBe("https://vault-api.test/v1/notify/file-added");
+    const init = post![1]!;
+    expect(init.method).toBe("POST");
+    expect((init.headers as Record<string, string>).Authorization).toMatch(
+      /^Bearer /,
+    );
+    const body = JSON.parse(String(init.body));
+    expect(body.companySlug).toBe("acme");
+    expect(body.companyUid).toBe("cmp_01ABCDEF");
+    expect(body.files).toEqual(
+      expect.arrayContaining([
+        { path: "docs/handoff.md", bytes: 42, addedBy: "alice@example.com" },
+        { path: "knowledge/readme.md", bytes: 100 }, // null addedBy omitted
+      ]),
+    );
+  });
+
+  it("never lets a file-added report failure break the sync (best-effort)", async () => {
+    vi.mocked(s3Module.headRemoteFile).mockResolvedValue(null);
+    // Make ONLY the notify report throw; delegate everything else to the
+    // default mock so the sync itself still runs.
+    const base = vi.mocked(globalThis.fetch).getMockImplementation()!;
+    vi.mocked(globalThis.fetch).mockImplementation(
+      async (url: unknown, init?: unknown) => {
+        if (String(url).includes("/v1/notify/file-added")) {
+          throw new Error("notify endpoint down");
+        }
+        return base(url as string, init as RequestInit);
+      },
+    );
+
+    const newFilesEvents: Array<{ type: string }> = [];
+    await expect(
+      sync({
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+        onEvent: (e) => {
+          if (e.type === "new-files") newFilesEvents.push(e);
+        },
+      }),
+    ).resolves.toBeDefined();
+    // Sync still completed and emitted its new-files event.
+    expect(newFilesEvents).toHaveLength(1);
+  });
+
   it("sets addedBy to null when HeadObject fails (best-effort)", async () => {
     vi.mocked(s3Module.headRemoteFile).mockRejectedValue(new Error("S3 transient error"));
 

package/src/cli/sync.ts

@@ -382,6 +382,73 @@ export function resolveAutoPruneCap(): number {
   return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
 }
 
+/** Max time to wait on the best-effort new-files notification POST. */
+const NOTIFY_FILE_ADDED_TIMEOUT_MS = 5000;
+
+/**
+ * Best-effort report of the files that were new to this drive during the sync,
+ * so the HQ Sync app can show a persistent cross-session "new files" history.
+ *
+ * POSTs to `${apiUrl}/v1/notify/file-added`, which writes per-recipient
+ * FILE_EVENT rows for the calling user (the one the files are new for). Fully
+ * non-fatal: any error, non-2xx, or timeout is swallowed — the durable signal
+ * is the synced file itself; this is only a notification mirror. Bounded by a
+ * 5s timeout so a hung endpoint can't stall sync completion. No-op when there
+ * are no new files.
+ */
+async function reportNewFilesToNotify(
+  vaultConfig: VaultServiceConfig,
+  companyUid: string,
+  companySlug: string,
+  files: Array<{ path: string; bytes: number; addedBy: string | null }>,
+): Promise<void> {
+  if (files.length === 0) return;
+  try {
+    const token =
+      typeof vaultConfig.authToken === "function"
+        ? await vaultConfig.authToken()
+        : vaultConfig.authToken;
+    const base = vaultConfig.apiUrl.replace(/\/+$/, "");
+    const controller = new AbortController();
+    const timer = setTimeout(
+      () => controller.abort(),
+      NOTIFY_FILE_ADDED_TIMEOUT_MS,
+    );
+    try {
+      await fetch(`${base}/v1/notify/file-added`, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${token}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          companyUid,
+          companySlug,
+          files: files.map((f) => ({
+            path: f.path,
+            bytes: f.bytes,
+            ...(f.addedBy ? { addedBy: f.addedBy } : {}),
+          })),
+        }),
+        signal: controller.signal,
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+  } catch (err) {
+    // Best-effort: never let notification reporting affect the sync result.
+    try {
+      console.error(
+        `[hq-sync] new-files notify report failed (non-fatal): ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+    } catch {
+      // swallow — logging must never break sync
+    }
+  }
+}
+
 /**
  * Sync (pull) all allowed files from the entity vault.
  */
@@ -932,6 +999,14 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
   }
   emit({ type: "new-files", files: enrichedNewFiles });
 
+  // Report new files to the notification service so they persist as a
+  // cross-session "new files" history in the HQ Sync app (POST
+  // /v1/notify/file-added → per-recipient FILE_EVENT rows for THIS user, who is
+  // the one the files are new for). Best-effort and bounded: a failure or a
+  // hung request must never delay or break the sync — the durable signal is the
+  // synced file itself, this is only a notification mirror.
+  await reportNewFilesToNotify(vaultConfig, ctx.uid, ctx.slug, enrichedNewFiles);
+
   // Codex P1 (PR #24 follow-up): scope-gate tombstone candidates with
   // a per-object HEAD before unlinking. `listRemoteFiles` is STS-scoped
   // (guest sessions with `allowedPrefixes`, role downgrade, custom