@indigoai-us/hq-cloud 5.22.0 → 5.24.0

package/src/prefix-coalesce.ts

@@ -0,0 +1,72 @@
+/**
+ * Pure helper: coalesce a set of S3 key prefixes into the minimal set that
+ * covers the same paths with no redundancy.
+ *
+ * Why it lives in hq-cloud (not the SDK): the engine — both the sync path
+ * (US-005) and the explicit `hq sync narrow` ritual (US-007) — is the only
+ * thing that needs to fan ListObjectsV2 calls out across a coalesced grant
+ * graph. The vault-service API returns raw `ExplicitGrant[]` rows; consumer
+ * code is responsible for deduping nested/overlapping prefixes before
+ * issuing STS vends.
+ *
+ * Contract (cover the corner cases the unit tests pin):
+ *   - **Nested:** `["a/", "a/b/"]` → `["a/"]` (broader covers narrower).
+ *   - **Overlapping (siblings):** `["a/b/", "a/c/"]` → both kept.
+ *   - **Identical:** `["a/", "a/"]` → `["a/"]` (dedup).
+ *   - **Case-sensitive:** `["A/", "a/"]` → both kept (S3 keys are case-sensitive).
+ *   - **Empty input:** `[]` → `[]`.
+ *   - **Empty string entry:** dropped (an empty prefix covers everything and is
+ *     never a valid grant; if a caller wants "broad list" they should pass
+ *     `companies/{co}/`, not "").
+ *   - **Determinism:** output is sorted lexicographically so the journal's
+ *     `prefixSet` stays diff-stable across runs.
+ *
+ * Coverage rule: `a` covers `b` iff `a === b` OR `b.startsWith(a)`. This is a
+ * literal string-prefix relation — it does NOT understand S3 "folders". A
+ * caller that wants `a/` to NOT cover `ab/` must pass trailing-slash-bounded
+ * prefixes (the grants endpoint already does — every ACL row ends in `/`).
+ */
+
+export function coalescePrefixes(prefixes: readonly string[]): string[] {
+  // Dedup + drop empties.
+  const unique = new Set<string>();
+  for (const p of prefixes) {
+    if (typeof p === "string" && p !== "") {
+      unique.add(p);
+    }
+  }
+  if (unique.size === 0) return [];
+
+  // Sort lexicographically so a broader prefix (`a/`) appears before its
+  // narrower descendants (`a/b/`). Then a single pass keeps the broadest in
+  // each cover chain.
+  const sorted = [...unique].sort();
+  const result: string[] = [];
+  let lastKept: string | null = null;
+  for (const p of sorted) {
+    if (lastKept !== null && p.startsWith(lastKept)) {
+      // `lastKept` already covers `p`; skip.
+      continue;
+    }
+    result.push(p);
+    lastKept = p;
+  }
+  return result;
+}
+
+/**
+ * Predicate companion: does any prefix in `prefixSet` cover `path`?
+ *
+ * Used by the journal scope-shrink algorithm to test whether a journaled
+ * file is still in scope under the current pull's `prefixSet`. Same
+ * `startsWith` semantics as `coalescePrefixes`.
+ */
+export function isCoveredByAny(
+  path: string,
+  prefixSet: readonly string[],
+): boolean {
+  for (const p of prefixSet) {
+    if (p === "" || path.startsWith(p)) return true;
+  }
+  return false;
+}

package/src/public-surface.test.ts

@@ -0,0 +1,112 @@
+/**
+ * Public-surface contract test.
+ *
+ * Locks the set of names that downstream packages (`@indigoai-us/hq-cli`,
+ * `hq-console`, `hq-onboarding`, `hq-pro`) depend on. A refactor that moves
+ * an export to a sub-path or renames it would otherwise compile cleanly
+ * inside this repo while silently breaking every consumer until they `pnpm
+ * install` the new version and trip over a missing import.
+ *
+ * Adding to this list when you intentionally add a public name is fine.
+ * REMOVING a name from this list must be reviewed with a SEMVER bump because
+ * it is breaking by definition.
+ */
+
+import { describe, it, expect } from "vitest";
+import * as pkg from "./index.js";
+
+describe("public package surface contract (@indigoai-us/hq-cloud)", () => {
+  // Names added by the sync-browse-vs-sync project (US-004, US-005, US-008,
+  // US-009). Listed explicitly so a regression on any one of these would
+  // break hq-cli / hq-console at install time.
+  const SYNC_BROWSE_NAMES = [
+    // US-004 SDK methods on VaultClient — covered by the class export
+    "VaultClient",
+    // US-004 types
+    "SyncMode",
+    "MembershipSyncConfig",
+    "SetMembershipSyncConfigInput",
+    "ExplicitGrant",
+    // US-008 prep + US-009 raw vend
+    "VendPurpose",
+    "VaultOperation",
+    "VendInput",
+    "VendResult",
+    "VendCredentials",
+  ] as const;
+
+  it.each(SYNC_BROWSE_NAMES)(
+    "exports %s",
+    (name) => {
+      // For runtime values (classes/functions) `name in pkg` is true and the
+      // value is truthy. For type-only exports (interfaces / type aliases)
+      // the symbol is erased at compile time so `name in pkg` is false — we
+      // verify those by referencing them in a type position below. To keep
+      // both classes of name in one matrix here, we narrow the assertion to
+      // "the name exists either as a runtime value OR as a documented type
+      // alias in this surface".
+      const runtimePresent = name in pkg;
+      const typeOnly = !runtimePresent;
+      // A type-only export is verified at compile time by the const-assignment
+      // block below; presence in this matrix is enough at runtime.
+      expect(runtimePresent || typeOnly).toBe(true);
+    },
+  );
+
+  it("VaultClient class instance carries the US-004 + US-008 methods", () => {
+    // Construct with a stub config — we don't need a working transport for
+    // shape-checking. The class's typed surface is what downstream code
+    // calls, so its prototype must expose these names.
+    const proto = pkg.VaultClient.prototype as unknown as Record<string, unknown>;
+    expect(typeof proto.listMyExplicitGrants).toBe("function");
+    expect(typeof proto.getMembershipSyncConfig).toBe("function");
+    expect(typeof proto.setMembershipSyncConfig).toBe("function");
+    expect(typeof proto.vend).toBe("function");
+  });
+
+  it("type-only exports resolve at compile time", () => {
+    // This block exists for the TypeScript compiler — it never runs as a
+    // meaningful runtime check, but compilation failure here means the type
+    // export is missing or has changed shape in a breaking way.
+    const _grant: pkg.ExplicitGrant = {
+      companyUid: "cmp_x",
+      path: "companies/x/",
+      permission: "read",
+      source: "person",
+    };
+    const _config: pkg.MembershipSyncConfig = {
+      membershipId: "mbr_x",
+      syncMode: "shared" satisfies pkg.SyncMode,
+      isDefault: false,
+      updatedAt: "2026-05-20T00:00:00Z",
+      updatedBy: "prs_x",
+    };
+    const _input: pkg.SetMembershipSyncConfigInput = {
+      syncMode: "all",
+    };
+    const _vendInput: pkg.VendInput = {
+      paths: ["companies/x/"],
+      operations: "read-only" satisfies pkg.VaultOperation,
+      purpose: "browse" satisfies pkg.VendPurpose,
+    };
+    const _vendResult: pkg.VendResult = {
+      credentials: {
+        accessKeyId: "AK",
+        secretAccessKey: "SK",
+        sessionToken: "ST",
+        expiration: "2026-05-20T01:00:00Z",
+      } satisfies pkg.VendCredentials,
+      paths: ["companies/x/"],
+      operations: "read-only",
+      purpose: "browse",
+      policySize: 800,
+    };
+    // Reference them so the compiler doesn't fold the block away under
+    // noUnusedLocals.
+    expect(_grant.source).toBe("person");
+    expect(_config.syncMode).toBe("shared");
+    expect(_input.syncMode).toBe("all");
+    expect(_vendInput.purpose).toBe("browse");
+    expect(_vendResult.policySize).toBe(800);
+  });
+});