@indigoai-us/hq-cloud 6.14.46 → 6.14.47

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) => {