@indigoai-us/hq-cloud 5.30.0 → 5.32.0

package/src/cli/sync.ts

@@ -91,6 +91,15 @@ export type SyncProgressEvent =
        * uploaded vs downloaded.
        */
       direction?: "up" | "down";
+      /**
+       * Email of the file's author, read from the S3 object's `created-by`
+       * user-metadata. Only set on the download/pull path (a downloaded file
+       * was authored by whoever uploaded it); push-side progress has no author
+       * because the uploader is the local user. `null`/absent when the object
+       * carries no `created-by`. The menubar activity log shows this so the
+       * user sees who authored each file they received.
+       */
+      author?: string | null;
     }
   | { type: "error"; path: string; message: string }
   | {
@@ -173,10 +182,36 @@ export interface SyncOptions {
   /**
    * When true, the caller is syncing against the caller's person-entity
    * bucket. Pulled keys whose path starts with `companies/` are dropped
-   * (belt-and-braces — the person bucket should never contain those,
-   * but the runner must not write them into the user's company folders).
+   * by default (belt-and-braces — the person bucket should never contain
+   * those, and the runner must not write them into the user's company
+   * folders). See `includeLocalCompanies` for the opt-in escape hatch.
    */
   personalMode?: boolean;
+  /**
+   * Opt-in: when `personalMode === true`, allow `companies/{slug}/...` keys
+   * through the pull filter EXCEPT for slugs in `teamSyncedSlugs` (which
+   * are orphan remnants from a company that was promoted to its own team
+   * bucket and remain pre-decommission). Mirrors the push-side
+   * `HQ_SYNC_LOCAL_COMPANIES_TO_PERSONAL=1` gate: when an operator opts
+   * into the cloud:false → personal-bucket fallback on their machine,
+   * pull must also know about the new key shape on the OTHER machine that
+   * subscribes to those keys. Without this, the feature is push-only —
+   * the destination machine never sees the keys.
+   *
+   * Default false preserves the pre-5.20 behavior (drop all
+   * `companies/...` keys in personalMode).
+   */
+  includeLocalCompanies?: boolean;
+  /**
+   * Slugs of companies the operator has an active team-bucket Membership
+   * for. Only consulted when `personalMode === true` AND
+   * `includeLocalCompanies === true`: keys under `companies/{slug}/...`
+   * for any slug in this set are dropped as orphans from a pre-promotion
+   * personal-bucket fallback. The push-side decommission cycle eventually
+   * removes these from the bucket; this filter prevents them from
+   * re-downloading into the same disk paths the team-bucket pull manages.
+   */
+  teamSyncedSlugs?: ReadonlySet<string>;
   /**
    * Override for the per-slug journal file name. Defaults to `ctx.slug`.
    * sync-runner passes `journalSlug: "personal"` for the personal slot so
@@ -258,6 +293,8 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
     companyRoot,
     shouldSync,
     options.personalMode === true,
+    options.includeLocalCompanies === true,
+    options.teamSyncedSlugs ?? null,
   );
 
   emit({
@@ -403,7 +440,8 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
 
     // Download (action === "download" or conflict resolved to "overwrite")
     try {
-      await downloadFile(ctx, remoteFile.key, localPath);
+      const { metadata } = await downloadFile(ctx, remoteFile.key, localPath);
+      const author = metadata?.["created-by"] ?? null;
 
       // Symlink records materialize as real symlinks on disk. lstat
       // (does not follow) lets us detect that case so the journal stamp
@@ -433,6 +471,7 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
         path: remoteFile.key,
         bytes: size,
         ...(remoteJournalMessage ? { message: remoteJournalMessage } : {}),
+        ...(author ? { author } : {}),
       });
 
       filesDownloaded++;
@@ -602,6 +641,8 @@ function computePullPlan(
   companyRoot: string,
   shouldSync: (filePath: string, isDir?: boolean) => boolean,
   personalMode: boolean,
+  includeLocalCompanies: boolean,
+  teamSyncedSlugs: ReadonlySet<string> | null,
 ): PullPlan {
   const items: PullPlanItem[] = [];
 
@@ -609,8 +650,30 @@ function computePullPlan(
     const localPath = path.join(companyRoot, remoteFile.key);
 
     if (personalMode && remoteFile.key.startsWith("companies/")) {
-      items.push({ action: "skip-personal-mode", remoteFile, localPath });
-      continue;
+      // Default: drop every `companies/...` key — the legacy contract
+      // is that the personal bucket should never contain them.
+      //
+      // EXCEPTION: when the operator has opted into the cloud:false →
+      // personal-bucket fallback (HQ_SYNC_LOCAL_COMPANIES_TO_PERSONAL=1
+      // on this machine), keys under `companies/{slug}/...` are
+      // legitimate — they're content a peer machine pushed for a
+      // company whose `company.yaml` declares `cloud: false`. Allow
+      // them through EXCEPT for slugs the operator has an active team-
+      // bucket Membership for: those are orphan remnants from before
+      // the company was promoted, and downloading them would clash
+      // with the team-bucket pull at the same disk path.
+      //
+      // Symmetric to the push-side `decommissionPrefixes` logic in
+      // share.ts — both target the same orphan class, both honor the
+      // same `teamSyncedSlugs` set derived from the operator's live
+      // membership at runtime.
+      const slug = remoteFile.key.split("/")[1] ?? "";
+      const isTeamSyncedOrphan =
+        teamSyncedSlugs !== null && slug !== "" && teamSyncedSlugs.has(slug);
+      if (!includeLocalCompanies || isTeamSyncedOrphan) {
+        items.push({ action: "skip-personal-mode", remoteFile, localPath });
+        continue;
+      }
     }
 
     // LIST gives us no kind signal for the remote object — we don't

package/src/index.ts

@@ -105,8 +105,11 @@ export type { CognitoAuthConfig, CognitoTokens } from "./cognito-auth.js";
 // Personal-vault scope helpers — shared between hq-sync-runner and `hq sync`
 export {
   PERSONAL_VAULT_EXCLUDED_TOP_LEVEL,
+  PERSONAL_VAULT_COMPANY_EXCLUDED_SLUGS,
   computePersonalVaultPaths,
+  computePersonalCompanySubdirs,
 } from "./personal-vault.js";
+export type { PersonalVaultOptions } from "./personal-vault.js";
 
 // Personal-vault default-exclusions (5.25+) — second-tier deep-walk filter
 // for secrets, machine-local state, scratch dirs, OS/build cruft.

package/src/lib/describe-error.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it } from "vitest";
+import { describeError } from "./describe-error.js";
+
+describe("describeError", () => {
+  it("returns String(value) for non-Error throws", () => {
+    expect(describeError("plain string")).toBe("plain string");
+    expect(describeError(42)).toBe("42");
+    expect(describeError(null)).toBe("null");
+    expect(describeError(undefined)).toBe("undefined");
+  });
+
+  it("returns just the message for a plain Error (skips generic 'Error' name)", () => {
+    expect(describeError(new Error("acme blew up"))).toBe("acme blew up");
+  });
+
+  it("includes named subclasses (TypeError, RangeError, …)", () => {
+    expect(describeError(new TypeError("nope"))).toBe("TypeError nope");
+  });
+
+  it("surfaces AWS SDK v3 UnknownError with cause chain (the bug this fixes)", () => {
+    const sdkErr = new Error("UnknownError");
+    sdkErr.name = "UnknownError";
+    const dnsErr = new Error(
+      "getaddrinfo ENOTFOUND privy.s3.us-east-1.amazonaws.com",
+    );
+    (dnsErr as Error & { code?: string; syscall?: string; hostname?: string }).code =
+      "ENOTFOUND";
+    (dnsErr as Error & { code?: string; syscall?: string; hostname?: string }).syscall =
+      "getaddrinfo";
+    (dnsErr as Error & { code?: string; syscall?: string; hostname?: string }).hostname =
+      "privy.s3.us-east-1.amazonaws.com";
+    (sdkErr as Error & { cause?: unknown }).cause = dnsErr;
+
+    const msg = describeError(sdkErr);
+    expect(msg).toContain("UnknownError");
+    expect(msg).toContain("cause=ENOTFOUND");
+    expect(msg).toContain("syscall=getaddrinfo");
+    expect(msg).toContain("host=privy.s3.us-east-1.amazonaws.com");
+  });
+
+  it("surfaces $metadata.httpStatusCode when present (AccessDenied, etc.)", () => {
+    const err = new Error("The provided credentials were not authorized.");
+    err.name = "AccessDenied";
+    (err as Error & { $metadata?: { httpStatusCode?: number } }).$metadata = {
+      httpStatusCode: 403,
+    };
+    const msg = describeError(err);
+    expect(msg).toContain("AccessDenied");
+    expect(msg).toContain("http=403");
+    expect(msg).toContain("The provided credentials");
+  });
+
+  it("includes own .code attribute on the top-level error", () => {
+    const err = new Error("connect timeout") as Error & { code?: string };
+    err.code = "ETIMEDOUT";
+    expect(describeError(err)).toContain("code=ETIMEDOUT");
+  });
+
+  it("walks up to 3 cause levels, no further", () => {
+    // top → c1 → c2 → c3 → c4 (5 errors, 4 cause hops). The walk should
+    // surface c1/c2/c3 codes but stop before c4.
+    const c4 = new Error("c4");
+    (c4 as Error & { code?: string }).code = "C4_CODE";
+    const c3 = new Error("c3");
+    (c3 as Error & { code?: string; cause?: unknown }).code = "C3_CODE";
+    (c3 as Error & { cause?: unknown }).cause = c4;
+    const c2 = new Error("c2");
+    (c2 as Error & { code?: string; cause?: unknown }).code = "C2_CODE";
+    (c2 as Error & { cause?: unknown }).cause = c3;
+    const c1 = new Error("c1");
+    (c1 as Error & { code?: string; cause?: unknown }).code = "C1_CODE";
+    (c1 as Error & { cause?: unknown }).cause = c2;
+    const top = new Error("top");
+    (top as Error & { cause?: unknown }).cause = c1;
+    const msg = describeError(top);
+    expect(msg).toContain("cause=C1_CODE");
+    expect(msg).toContain("cause=C2_CODE");
+    expect(msg).toContain("cause=C3_CODE");
+    // c4 is the 4th cause level — outside the 3-level walk
+    expect(msg).not.toContain("C4_CODE");
+  });
+
+  it("breaks on a cycle in the cause chain", () => {
+    const a = new Error("a");
+    const b = new Error("b");
+    (a as Error & { cause?: unknown }).cause = b;
+    (b as Error & { cause?: unknown }).cause = a;
+    // Should not infinite-loop; should return something containing "a" and "b".
+    const msg = describeError(a);
+    expect(msg).toContain("a");
+    expect(msg).toContain("b");
+  });
+
+  it("de-dups consecutive identical fragments (the 'UnknownError UnknownError' case)", () => {
+    const err = new Error("UnknownError");
+    err.name = "UnknownError";
+    // Without de-dup the output would start "UnknownError UnknownError".
+    expect(describeError(err)).toBe("UnknownError");
+  });
+});

package/src/lib/describe-error.ts

@@ -0,0 +1,58 @@
+/**
+ * Surface AWS SDK v3's opaque `UnknownError` wrapper.
+ *
+ * When the SDK can't match a response to a modeled exception (which includes
+ * every Node-side networking failure — `getaddrinfo ENOTFOUND`, `ECONNRESET`,
+ * `EHOSTUNREACH`, expired-DNS-cache hits, etc.) it raises an error whose
+ * `name` and `message` are both literally "UnknownError" and stashes the
+ * underlying Node error on `.cause`. Plain `err.message` extraction at the
+ * catch site loses the cause chain entirely, leaving operators with an
+ * unactionable "UnknownError" in the event stream.
+ *
+ * This walks the cause chain (capped at 3 levels) and stitches together a
+ * single diagnostic line that preserves the original failure mode.
+ *
+ * Example outputs:
+ *   "UnknownError cause=ENOTFOUND syscall=getaddrinfo host=hq-vault-cmp-…s3.us-east-1.amazonaws.com"
+ *   "AccessDenied http=403 The provided credentials …"
+ *   "Error code=ETIMEDOUT cause=ETIMEDOUT host=api.example.com"
+ */
+export function describeError(err: unknown): string {
+  if (!(err instanceof Error)) return String(err);
+
+  const parts: string[] = [];
+  const e = err as Error & {
+    code?: string;
+    $metadata?: { httpStatusCode?: number; requestId?: string };
+    cause?: unknown;
+  };
+
+  if (e.name && e.name !== "Error") parts.push(e.name);
+  if (e.code) parts.push(`code=${e.code}`);
+  if (e.$metadata?.httpStatusCode) parts.push(`http=${e.$metadata.httpStatusCode}`);
+
+  // Walk cause chain to capture the underlying syscall / hostname / code
+  // that the SDK swallowed. Cap depth at 3 and de-cycle with a Set.
+  const seen = new Set<unknown>([err]);
+  let cur: unknown = e.cause;
+  for (let i = 0; i < 3 && cur && !seen.has(cur); i++) {
+    seen.add(cur);
+    const c = cur as {
+      code?: string;
+      syscall?: string;
+      hostname?: string;
+      message?: string;
+      cause?: unknown;
+    };
+    if (c.code) parts.push(`cause=${c.code}`);
+    if (c.syscall) parts.push(`syscall=${c.syscall}`);
+    if (c.hostname) parts.push(`host=${c.hostname}`);
+    if (c.message && c.message !== e.message) parts.push(c.message);
+    cur = c.cause;
+  }
+
+  if (e.message) parts.push(e.message);
+
+  // De-dup consecutive repeats (SDK's "UnknownError UnknownError" case)
+  return parts.filter((p, i) => i === 0 || p !== parts[i - 1]).join(" ");
+}

package/src/personal-vault.test.ts

@@ -0,0 +1,231 @@
+/**
+ * Unit tests for the personal-vault path-discovery helpers.
+ *
+ * These cover the column-anchored `cloud: false` marker regex and the
+ * `companies/{slug}/` enumeration filter — both are pure functions over
+ * disk + caller-supplied option sets, so we exercise them against tmp
+ * directories rather than mocking fs.
+ *
+ * The sync-runner-level integration (env-var gate, team-synced slug
+ * derivation, end-to-end share() invocation) lives in
+ * `bin/sync-runner.test.ts` — tests G, H, I.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import {
+  computePersonalCompanySubdirs,
+  computePersonalVaultPaths,
+  PERSONAL_VAULT_COMPANY_EXCLUDED_SLUGS,
+  PERSONAL_VAULT_EXCLUDED_TOP_LEVEL,
+} from "./personal-vault.js";
+
+describe("personal-vault helpers", () => {
+  let hqRoot: string;
+
+  beforeEach(() => {
+    hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-pv-test-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(hqRoot, { recursive: true, force: true });
+  });
+
+  /** Helper: write `companies/{slug}/company.yaml` with arbitrary content. */
+  function writeCompany(slug: string, yaml: string | null): void {
+    const dir = path.join(hqRoot, "companies", slug);
+    fs.mkdirSync(dir, { recursive: true });
+    if (yaml !== null) fs.writeFileSync(path.join(dir, "company.yaml"), yaml);
+  }
+
+  /** Helper: relative-paths-sorted projection of an absolute-path list. */
+  function rel(abs: string[]): string[] {
+    return abs.map((p) => path.relative(hqRoot, p)).sort();
+  }
+
+  // ── Exported constants ─────────────────────────────────────────────────
+  it("constants: PERSONAL_VAULT_EXCLUDED_TOP_LEVEL contains the canonical four names", () => {
+    expect([...PERSONAL_VAULT_EXCLUDED_TOP_LEVEL].sort()).toEqual([
+      ".git",
+      "companies",
+      "repos",
+      "workspace",
+    ]);
+  });
+
+  it("constants: PERSONAL_VAULT_COMPANY_EXCLUDED_SLUGS hard-lists `_template`", () => {
+    expect(PERSONAL_VAULT_COMPANY_EXCLUDED_SLUGS).toContain("_template");
+  });
+
+  // ── computePersonalCompanySubdirs: marker-regex acceptance ─────────────
+  it("marker: accepts canonical `cloud: false` at column 0", () => {
+    writeCompany("foo", "cloud: false\nname: Foo\n");
+    expect(rel(computePersonalCompanySubdirs(hqRoot))).toEqual([
+      path.join("companies", "foo"),
+    ]);
+  });
+
+  it("marker: accepts `cloud:false` (no space after colon)", () => {
+    writeCompany("foo", "cloud:false\n");
+    expect(rel(computePersonalCompanySubdirs(hqRoot))).toEqual([
+      path.join("companies", "foo"),
+    ]);
+  });
+
+  it("marker: accepts trailing comment after `cloud: false`", () => {
+    writeCompany("foo", "cloud: false   # local-only, never upload to team\n");
+    expect(rel(computePersonalCompanySubdirs(hqRoot))).toEqual([
+      path.join("companies", "foo"),
+    ]);
+  });
+
+  it("marker: accepts CRLF line endings", () => {
+    writeCompany("foo", "cloud: false\r\nname: Foo\r\n");
+    expect(rel(computePersonalCompanySubdirs(hqRoot))).toEqual([
+      path.join("companies", "foo"),
+    ]);
+  });
+
+  it("marker: accepts `cloud: false` even when it is NOT the first line", () => {
+    writeCompany("foo", "name: Foo\nslug: foo\ncloud: false\n");
+    expect(rel(computePersonalCompanySubdirs(hqRoot))).toEqual([
+      path.join("companies", "foo"),
+    ]);
+  });
+
+  // ── computePersonalCompanySubdirs: marker-regex rejection ──────────────
+  it("marker: rejects `cloud: true`", () => {
+    writeCompany("foo", "cloud: true\n");
+    expect(computePersonalCompanySubdirs(hqRoot)).toEqual([]);
+  });
+
+  it("marker: rejects missing company.yaml entirely", () => {
+    writeCompany("foo", null);
+    expect(computePersonalCompanySubdirs(hqRoot)).toEqual([]);
+  });
+
+  it("marker: rejects empty company.yaml", () => {
+    writeCompany("foo", "");
+    expect(computePersonalCompanySubdirs(hqRoot)).toEqual([]);
+  });
+
+  it("marker: rejects nested `cloud: false` (column-0 anchor — false-positive guard)", () => {
+    // Regression for an audit finding: an earlier `^[ \t]*cloud:` regex
+    // allowed arbitrary leading whitespace, which silently matched
+    // nested keys like `meta.cloud = false`. The tightened `^cloud:` regex
+    // rejects this, matching the canonical column-0 shape that
+    // `/designate-team`'s awk emits.
+    writeCompany("foo", "meta:\n  cloud: false\n");
+    expect(computePersonalCompanySubdirs(hqRoot)).toEqual([]);
+  });
+
+  it("marker: rejects list-item style `- cloud: false`", () => {
+    writeCompany("foo", "tags:\n- cloud: false\n");
+    expect(computePersonalCompanySubdirs(hqRoot)).toEqual([]);
+  });
+
+  it("marker: rejects flow-mapping `{ cloud: false }`", () => {
+    writeCompany("foo", "{ cloud: false }\n");
+    expect(computePersonalCompanySubdirs(hqRoot)).toEqual([]);
+  });
+
+  it("marker: rejects YAML-alt boolean spellings (False, FALSE, no, off)", () => {
+    for (const variant of ["cloud: False\n", "cloud: FALSE\n", "cloud: no\n", "cloud: off\n"]) {
+      writeCompany("foo", variant);
+      expect(computePersonalCompanySubdirs(hqRoot)).toEqual([]);
+      fs.rmSync(path.join(hqRoot, "companies", "foo"), { recursive: true });
+    }
+  });
+
+  it("marker: rejects quoted `cloud: \"false\"` (the quote breaks the literal-false match)", () => {
+    writeCompany("foo", 'cloud: "false"\n');
+    expect(computePersonalCompanySubdirs(hqRoot)).toEqual([]);
+  });
+
+  it("marker: rejects `cloud: falsehood` (word-boundary guard)", () => {
+    writeCompany("foo", "cloud: falsehood\n");
+    expect(computePersonalCompanySubdirs(hqRoot)).toEqual([]);
+  });
+
+  // ── Subdir-level filters ───────────────────────────────────────────────
+  it("filter: skips _template even with cloud:false marker", () => {
+    writeCompany("_template", "cloud: false\n");
+    writeCompany("real", "cloud: false\n");
+    expect(rel(computePersonalCompanySubdirs(hqRoot))).toEqual([
+      path.join("companies", "real"),
+    ]);
+  });
+
+  it("filter: skips slugs in the teamSyncedSlugs set", () => {
+    writeCompany("free", "cloud: false\n");
+    writeCompany("team-acme", "cloud: false\n");
+    expect(
+      rel(computePersonalCompanySubdirs(hqRoot, new Set(["team-acme"]))),
+    ).toEqual([path.join("companies", "free")]);
+  });
+
+  it("filter: skips stray files under companies/ (only directories considered)", () => {
+    // Hypothetical: someone drops a README.md at companies/. Should not
+    // crash, should not be enumerated as a company subdir.
+    fs.mkdirSync(path.join(hqRoot, "companies"), { recursive: true });
+    fs.writeFileSync(path.join(hqRoot, "companies", "README.md"), "# README");
+    writeCompany("real", "cloud: false\n");
+    expect(rel(computePersonalCompanySubdirs(hqRoot))).toEqual([
+      path.join("companies", "real"),
+    ]);
+  });
+
+  it("filter: missing hqRoot/companies/ returns []", () => {
+    // No `companies/` dir at all (fresh install or atypical layout).
+    expect(computePersonalCompanySubdirs(hqRoot)).toEqual([]);
+  });
+
+  // ── computePersonalVaultPaths: top-level + company-subdir composition ──
+  it("composition: includeLocalCompanies=false skips companies/ entirely", () => {
+    fs.mkdirSync(path.join(hqRoot, ".claude"));
+    fs.mkdirSync(path.join(hqRoot, "knowledge"));
+    writeCompany("foo", "cloud: false\n");
+
+    const out = rel(computePersonalVaultPaths(hqRoot));
+    // Top-level entries present, no companies/* subdir.
+    expect(out).toContain(".claude");
+    expect(out).toContain("knowledge");
+    expect(out.some((p) => p.startsWith("companies"))).toBe(false);
+  });
+
+  it("composition: includeLocalCompanies=true adds opt-in company subdirs", () => {
+    fs.mkdirSync(path.join(hqRoot, "knowledge"));
+    writeCompany("foo", "cloud: false\n");
+    writeCompany("bar", "cloud: true\n");
+
+    const out = rel(computePersonalVaultPaths(hqRoot, { includeLocalCompanies: true }));
+    expect(out).toContain("knowledge");
+    expect(out).toContain(path.join("companies", "foo"));
+    expect(out).not.toContain(path.join("companies", "bar"));
+    // The companies/ top-level entry itself is never present — only specific
+    // opted-in subdirs. Preserves the invariant that share() never walks
+    // the whole companies/ tree under personalMode.
+    expect(out).not.toContain("companies");
+  });
+
+  it("composition: includeLocalCompanies=true + teamSyncedSlugs filter combine correctly", () => {
+    writeCompany("foo", "cloud: false\n");
+    writeCompany("synced", "cloud: false\n");
+
+    const out = rel(
+      computePersonalVaultPaths(hqRoot, {
+        includeLocalCompanies: true,
+        teamSyncedSlugs: new Set(["synced"]),
+      }),
+    );
+    expect(out).toContain(path.join("companies", "foo"));
+    expect(out).not.toContain(path.join("companies", "synced"));
+  });
+
+  it("composition: missing hqRoot returns []", () => {
+    fs.rmSync(hqRoot, { recursive: true });
+    expect(computePersonalVaultPaths(hqRoot, { includeLocalCompanies: true })).toEqual([]);
+  });
+});