@indigoai-us/hq-cloud 6.14.45 → 6.14.47

package/src/cli/sync.ts

@@ -398,10 +398,14 @@ export type SyncProgressEvent =
     }
   | {
       /**
-       * Emitted by the PULL leg once per remote key skipped because the server
-       * will never presign it (for example, a `companies/…`-prefixed key in a
-       * company-scoped vault or a key with control characters). Such keys are
-       * bucket poisoning from an outdated direct-S3 client. Like
+       * Emitted once per key skipped because it is permanently unstorable.
+       *
+       * PULL leg: a remote key the server will never presign (for example, a
+       * `companies/…`-prefixed key in a company-scoped vault or a key with
+       * control characters) — bucket poisoning from an outdated direct-S3
+       * client. PUSH leg: a local key the upload validator would reject, so
+       * the upload can only ever throw — a doubled-tree `companies/…` key, or
+       * a control-character path such as a macOS Finder `Icon\r` file. Like
        * `skip-size-limit`, this is deliberately NOT `type: "error"` — one bad
        * object must never error a whole company sync (erroring gated
        * heartbeat toolset refreshes fleet-wide in the incident). Surfaced for

package/src/ignore.test.ts

@@ -33,6 +33,24 @@ describe("isExpectedIgnore", () => {
     expect(isExpectedIgnore(".claude/skills/foo/.skill-media/hero.png")).toBe(true);
   });
 
+  it("classifies macOS Finder Icon\\r files as expected noise", () => {
+    // Finder scatters one into every directory it renders a custom icon for,
+    // and a folder-level cloud-sync agent propagates them tree-wide. Treated
+    // exactly like .DS_Store so a seeded tree stays silent rather than firing
+    // the "EXCLUDED from sync — review in case this is unintended" warning
+    // once per file.
+    expect(isExpectedIgnore("Icon\r")).toBe(true);
+    expect(isExpectedIgnore("companies/indigo/Icon\r")).toBe(true);
+  });
+
+  it("keeps a real file named Icons noteworthy (no `Icon?` over-match)", () => {
+    // The `Icon?` gitignore workaround would swallow these. Dropping real
+    // user content is a worse failure than the cruft being excluded.
+    expect(isExpectedIgnore("companies/indigo/Icons")).toBe(false);
+    expect(isExpectedIgnore("companies/indigo/Icon")).toBe(false);
+    expect(isExpectedIgnore("companies/indigo/Icons.md")).toBe(false);
+  });
+
   it("keeps nested repos/workspace and ordinary content noteworthy", () => {
     expect(isExpectedIgnore("companies/indigo/knowledge/repos/foo/notes.md")).toBe(false);
     expect(isExpectedIgnore("companies/indigo/knowledge/overview.md")).toBe(false);
@@ -85,6 +103,43 @@ describe("createIgnoreFilter", () => {
     expect(shouldSync(path.join(hqRoot, "node_modules/react/index.js"))).toBe(false);
   });
 
+  it("permissive mode: macOS Finder Icon\\r files never enter the walk", () => {
+    // A CR is a control character, so the vault key validator rejects the key
+    // (INVALID_KEY_CONTROL_CHARS) and the upload can only ever throw. Dropping
+    // them during the walk is what keeps them off the upload path entirely.
+    const shouldSync = createIgnoreFilter(hqRoot);
+    expect(shouldSync(path.join(hqRoot, "Icon\r"))).toBe(false);
+    expect(shouldSync(path.join(hqRoot, "companies/indigo/Icon\r"))).toBe(false);
+    expect(shouldSync(path.join(hqRoot, ".agents/Icon\r"))).toBe(false);
+    // Caught at any depth, like the other OS-cruft exclusions.
+    expect(shouldSync(path.join(hqRoot, "a/b/c/d/Icon\r"))).toBe(false);
+  });
+
+  it("permissive mode: a real file named Icons still syncs", () => {
+    // Regression guard for the `Icon?` gitignore workaround, whose `?`
+    // single-char wildcard also matches Icons / Icon1 / IconX. This exclusion
+    // matches the exact Finder byte sequence instead, so real content survives.
+    const shouldSync = createIgnoreFilter(hqRoot);
+    expect(shouldSync(path.join(hqRoot, "companies/indigo/Icons"))).toBe(true);
+    expect(shouldSync(path.join(hqRoot, "companies/indigo/Icon"))).toBe(true);
+    expect(shouldSync(path.join(hqRoot, "companies/indigo/Icon1"))).toBe(true);
+    expect(shouldSync(path.join(hqRoot, "companies/indigo/Icons.md"))).toBe(true);
+  });
+
+  it("a literal Icon+CR line in .gitignore does NOT reach the ignore lib", () => {
+    // This is why the exclusion is a predicate and not a DEFAULT_IGNORES
+    // entry. ignore@5 strips a trailing CR from a pattern line, so the
+    // spelling git itself requires silently never matches. Pinning the
+    // upstream behavior here means a future ignore-lib bump that changes it
+    // surfaces as a failing test rather than a silent double-exclusion.
+    fs.writeFileSync(path.join(hqRoot, ".gitignore"), "Icon\r\n");
+    const shouldSync = createIgnoreFilter(hqRoot);
+    // Still excluded — by the predicate, not by the pattern.
+    expect(shouldSync(path.join(hqRoot, "Icon\r"))).toBe(false);
+    // Proof the pattern itself is inert: it did not take `Icons` with it.
+    expect(shouldSync(path.join(hqRoot, "Icons"))).toBe(true);
+  });
+
   it("repos/ exclusion is root-anchored to hqRoot (DEV-1791)", () => {
     const shouldSync = createIgnoreFilter(hqRoot);
     expect(shouldSync(path.join(hqRoot, "repos/private/hq-cloud/src/x.ts"))).toBe(false);

package/src/ignore.ts

@@ -244,6 +244,52 @@ function segmentToRegex(seg: string): RegExp {
   return new RegExp(`^${body}$`);
 }
 
+/**
+ * Match a path whose basename is the macOS Finder custom-icon file: the
+ * literal `Icon` followed by a carriage return (U+000D).
+ *
+ * This CANNOT be expressed as a `DEFAULT_IGNORES` entry, which is why it is a
+ * predicate instead of a pattern string. Two independent reasons:
+ *
+ *   1. A pattern line ending in a literal CR is inert. The `ignore` package
+ *      strips the trailing CR, so the line degrades to `Icon` and never
+ *      matches — verified against ignore@5.3.2:
+ *      `ignore().add("Icon\r\n").ignores("Icon\r") === false`. Git does the
+ *      same thing (it reads the CR as part of the line ending), which is why
+ *      the GitHub macOS template has to end that line with TWO CRs.
+ *   2. The usual workaround pattern `Icon?` DOES match, but `?` is a
+ *      single-character wildcard in gitignore syntax, so it also swallows any
+ *      real file named `Icons`, `Icon1`, `IconX`. Silently dropping user
+ *      content is worse than the cruft we are excluding.
+ *
+ * Matching the exact byte sequence keeps the exclusion precise. Finder writes
+ * these into every directory it renders a custom icon for, and a folder-level
+ * cloud-sync agent (iCloud Desktop, backup tooling) propagates them across an
+ * entire tree — including into `.git/`. They carry no user content.
+ *
+ * They are also unsyncable by construction: a CR is a control character, so
+ * the vault key validator rejects the key outright
+ * (INVALID_KEY_CONTROL_CHARS). Excluding them at the walk is what keeps them
+ * from reaching the upload path at all.
+ */
+export function isMacFinderIconFile(relPath: string): boolean {
+  const basename = relPath.replace(/\/$/, "").split("/").pop() ?? "";
+  return basename === "Icon\r";
+}
+
+/**
+ * True when any segment of `relPath` contains a character the vault key
+ * validator rejects (see `KEY_CONTROL_CHARS` in s3.ts — C0 controls plus DEL).
+ *
+ * Kept in lock-step with that validator on purpose: a key this returns `true`
+ * for can never be stored, so planning an upload for it only produces a
+ * guaranteed per-file failure.
+ */
+export function hasControlCharacters(relPath: string): boolean {
+  // eslint-disable-next-line no-control-regex
+  return /[\x00-\x1F\x7F]/.test(relPath);
+}
+
 export const EXPECTED_IGNORE_SEGMENTS = new Set([
   ".git",
   "node_modules",
@@ -307,6 +353,11 @@ export function isExpectedIgnore(relPath: string): boolean {
   return (
     basename === ".DS_Store" ||
     basename === "Thumbs.db" ||
+    // Same class as .DS_Store: OS-generated, zero user content. Classified
+    // expected so a tree full of them stays silent instead of firing the
+    // "EXCLUDED from sync — review in case this is unintended" warning once
+    // per file (Finder scatters one into every directory it touches).
+    basename === "Icon\r" ||
     basename === "company.yaml" ||
     basename === "INDEX.md" ||
     basename === "modules.lock" ||
@@ -373,6 +424,12 @@ export function createIgnoreFilter(
     const relative = path.relative(hqRoot, filePath);
     if (!relative || relative.startsWith("..")) return true; // outside HQ root
 
+    // macOS Finder custom-icon files. Excluded here rather than as a
+    // DEFAULT_IGNORES pattern because neither available spelling works —
+    // see isMacFinderIconFile for the ignore@5 CR-stripping proof and the
+    // `Icon?` over-match hazard.
+    if (isMacFinderIconFile(relative)) return false;
+
     // Gitignore dir-only patterns (`foo/`) only match candidate paths that
     // end with `/`. The `ignore` lib has no stat awareness, so when the
     // caller knows the entry is a directory we hand the matcher the

package/src/s3.test.ts

@@ -1679,6 +1679,12 @@ describe("validateVaultUploadKey — direct-S3 key poisoning guard (incident 202
     ["a/../b.md", "INVALID_KEY_DOT_COMPONENT"],
     ["a/./b.md", "INVALID_KEY_DOT_COMPONENT"],
     ["bad\x00key.md", "INVALID_KEY_CONTROL_CHARS"],
+    // macOS Finder custom-icon file. Named explicitly because this is the
+    // spelling that reaches the validator in the wild: Finder writes one into
+    // every directory it renders a custom icon for, and the push walker now
+    // excludes them precisely because this throw is unavoidable.
+    ["Icon\r", "INVALID_KEY_CONTROL_CHARS"],
+    ["docs/Icon\r", "INVALID_KEY_CONTROL_CHARS"],
   ])(
     "validateVaultUploadKey mirrors the server rule set: %j → %s",
     (key, code) => {

package/test/joiner-manifest-reconcile.integration.test.ts

@@ -50,13 +50,21 @@ interface CompanyFixture {
   name: string;
 }
 
-function makeJoinerRoot(companies: readonly CompanyFixture[]): string {
+function makeJoinerRoot(
+  companies: readonly CompanyFixture[],
+  opts: { createCompanyDirs?: boolean } = {},
+): string {
+  const createCompanyDirs = opts.createCompanyDirs ?? true;
   const root = fs.mkdtempSync(path.join(os.tmpdir(), "hq-joiner-"));
   fs.mkdirSync(path.join(root, "companies"), { recursive: true });
   // The pull materializes the company directory; the manifest entry is the
-  // thing that was missing.
-  for (const c of companies) {
-    fs.mkdirSync(path.join(root, "companies", c.slug), { recursive: true });
+  // thing that was missing. When `createCompanyDirs` is false we DON'T
+  // pre-create them — that models a company with zero shared files, where the
+  // runner itself must materialize the directory (see the zero-file test).
+  if (createCompanyDirs) {
+    for (const c of companies) {
+      fs.mkdirSync(path.join(root, "companies", c.slug), { recursive: true });
+    }
   }
   fs.writeFileSync(
     path.join(root, "companies", "manifest.yaml"),
@@ -202,6 +210,37 @@ describe("joiner manifest reconciliation (end to end)", () => {
     expect(readConfig(hqRoot).activeCompany).toBe("boring-ecom");
   });
 
+  it("materializes the company directory and writes the manifest entry even when zero files are shared", async () => {
+    // The agency/client-sharing case: a member genuinely belongs to a company,
+    // but nothing has been shared into their scope yet, so the pull downloads
+    // zero files and never creates `companies/<slug>/`. Before the fix the
+    // reconciler (which gates on that directory) skipped the slug and HQ never
+    // learned about the company. The runner now materializes the directory on a
+    // completed pull leg regardless of file count, so the manifest entry lands.
+    hqRoot = makeJoinerRoot([BORING_ECOM], { createCompanyDirs: false });
+    const deps = makeDeps([BORING_ECOM]);
+
+    // Precondition: the directory does NOT exist yet.
+    expect(fs.existsSync(path.join(hqRoot, "companies", "boring-ecom"))).toBe(
+      false,
+    );
+
+    expect(await runRunner(["--companies", "--hq-root", hqRoot], deps)).toBe(0);
+
+    // The runner created the directory even though the pull shared nothing...
+    expect(fs.existsSync(path.join(hqRoot, "companies", "boring-ecom"))).toBe(
+      true,
+    );
+    // ...and the manifest entry is present, so HQ now knows about the company.
+    const companies = readManifest(hqRoot);
+    expect(companies["boring-ecom"]).toEqual({
+      name: "Boring Ecom",
+      cloud_uid: "cmp_01KR1QTBSATVKFRTZ5CFNEYA0Q",
+      bucket_name: "hq-vault-boring-ecom",
+    });
+    expect(readConfig(hqRoot).activeCompany).toBe("boring-ecom");
+  });
+
   it("writes both entries but refuses to guess activeCompany for a two-company member", async () => {
     const acme: CompanyFixture = { uid: "cmp_acme", slug: "acme", name: "Acme" };
     hqRoot = makeJoinerRoot([BORING_ECOM, acme]);