@indigoai-us/hq-cloud 6.14.20 → 6.14.22

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