@indigoai-us/hq-cloud 6.14.19 → 6.14.21

package/src/s3.test.ts

@@ -98,6 +98,7 @@ import {
   createStagedSymlink,
   replaceStagedPath,
   sweepStaleStagedFiles,
+  DanglingSymlinkParentError,
 } from "./s3.js";
 import {
   setObjectIOFactory,
@@ -841,6 +842,50 @@ describe("downloadFile", () => {
     expect(fs.readlinkSync(localPath)).toBe(target);
   });
 
+  it("skips (typed, non-fatal) when the parent directory is a DANGLING symlink", async () => {
+    // The vault stores directory symlinks as objects (e.g.
+    // companies/<co>/.obsidian -> ../../.obsidian) AND files beneath them. On a
+    // machine where the link target is absent, mkdir of the parent throws
+    // ENOENT — not EEXIST — because mkdir(2) returns EEXIST for the link and
+    // Node's recursive impl then stats it, which fails on a dangling link.
+    // Raw, that marked the WHOLE company errored/partial on every sync cycle
+    // (2026-07-24 dogfood box). It must be a typed per-object skip instead.
+    nextGetObjectResponse = {
+      Body: (async function* () {
+        yield new TextEncoder().encode("hotkeys");
+      })(),
+      Metadata: {},
+    };
+
+    const parent = path.join(tmpRoot, ".obsidian");
+    fs.symlinkSync(path.join(tmpRoot, "does-not-exist"), parent);
+    // Precondition: existsSync follows the link and reports absent, while
+    // lstat still sees it — the exact shape the fix keys on.
+    expect(fs.existsSync(parent)).toBe(false);
+    expect(fs.lstatSync(parent).isSymbolicLink()).toBe(true);
+
+    await expect(
+      downloadFile(makeCtx(), ".obsidian/hotkeys.json", path.join(parent, "hotkeys.json")),
+    ).rejects.toBeInstanceOf(DanglingSymlinkParentError);
+
+    // The link is left exactly as found — no target materialized outside the
+    // directory being synced, which the caller's containment guard refuses.
+    expect(fs.lstatSync(parent).isSymbolicLink()).toBe(true);
+    expect(fs.existsSync(path.join(tmpRoot, "does-not-exist"))).toBe(false);
+  });
+
+  it("still creates an ordinary missing parent directory", async () => {
+    nextGetObjectResponse = {
+      Body: (async function* () {
+        yield new TextEncoder().encode("plain");
+      })(),
+      Metadata: {},
+    };
+    const localPath = path.join(tmpRoot, "deep", "nested", "file.md");
+    await downloadFile(makeCtx(), "deep/nested/file.md", localPath);
+    expect(fs.readFileSync(localPath, "utf8")).toBe("plain");
+  });
+
   it("recovers the target from legacy metadata-only uploads (body lacks the prefix)", async () => {
     // Backward-compat: an in-flight upload from earlier in this
     // PR's lifetime stored the target in metadata (raw or base64'd)

package/src/s3.ts

@@ -1003,6 +1003,59 @@ export interface DownloadModeWarning {
   fallback?: "preserved-local-mode" | "receiver-default";
 }
 
+/**
+ * A download whose parent directory exists as a DANGLING symlink.
+ *
+ * The vault stores directory symlinks as first-class objects (e.g.
+ * `companies/<co>/.obsidian -> ../../.obsidian`) AND stores files beneath them.
+ * When the link's target is absent on this machine, the child write fails —
+ * and it fails as ENOENT rather than EEXIST, because `mkdir(2)` returns EEXIST
+ * for the link and Node's `recursive: true` implementation then stats it, which
+ * fails on a dangling link. Raw, that surfaced as a hard error that marked the
+ * WHOLE company `errored`/`partial` on every sync cycle (2026-07-24 dogfood box:
+ * `.obsidian/hotkeys.json: ENOENT ... mkdir '.../companies/indigo/.obsidian'`).
+ *
+ * It is a per-object condition, not a company-level failure, so it is typed and
+ * the pull loop skips the object loudly instead of failing the run. We do NOT
+ * materialize the link target: the target is by definition outside the
+ * directory being synced, and creating it would write through a path the
+ * caller's containment guard deliberately refuses.
+ */
+export class DanglingSymlinkParentError extends Error {
+  readonly key: string;
+  readonly dir: string;
+  constructor(key: string, dir: string) {
+    super(
+      `download skipped: parent directory is a dangling symlink (${dir}) — ` +
+        `the vault stores it as a link whose target is absent locally`,
+    );
+    this.name = "DanglingSymlinkParentError";
+    this.key = key;
+    this.dir = dir;
+  }
+}
+
+/**
+ * Create the parent directory for a download, distinguishing the
+ * dangling-symlink case from a genuine mkdir failure.
+ *
+ * Callers must have already established that `dir` does not resolve
+ * (`fs.existsSync(dir) === false`); `existsSync` FOLLOWS symlinks, so a
+ * dangling link reports absent here while `lstat` still sees the link.
+ */
+function ensureDownloadParentDir(dir: string, key: string): void {
+  let link: fs.Stats | null = null;
+  try {
+    link = fs.lstatSync(dir);
+  } catch {
+    // Genuinely absent — the ordinary first-write path.
+  }
+  if (link?.isSymbolicLink()) {
+    throw new DanglingSymlinkParentError(key, dir);
+  }
+  fs.mkdirSync(dir, { recursive: true });
+}
+
 export async function downloadFile(
   ctx: EntityContext,
   key: string,
@@ -1032,7 +1085,7 @@ export async function downloadFile(
 
   const dir = path.dirname(localPath);
   if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
+    ensureDownloadParentDir(dir, key);
   }
 
   // Symlink path: presence of SYMLINK_TARGET_META_KEY (any non-empty