@indigoai-us/hq-cloud 6.14.9 → 6.14.11

package/src/s3.test.ts

@@ -95,6 +95,7 @@ import {
   FILE_BTIME_META_KEY,
   classifyVaultKey,
   validateVaultUploadKey,
+  replaceStagedPath,
 } from "./s3.js";
 import {
   setObjectIOFactory,
@@ -918,6 +919,96 @@ describe("downloadFile", () => {
     expect(fs.readFileSync(localPath, "utf-8")).toBe("existing local copy");
   });
 
+  it("replaces an existing directory link without changing its target", async () => {
+    const targetDir = path.join(tmpRoot, "generated-skill-source");
+    const localPath = path.join(tmpRoot, "generated-skill-link");
+    fs.mkdirSync(targetDir);
+    fs.writeFileSync(path.join(targetDir, "sentinel.txt"), "source-owned");
+    fs.symlinkSync(targetDir, localPath, "dir");
+
+    nextGetObjectResponse = {
+      Body: (async function* () {
+        yield Buffer.from("remote replacement");
+      })(),
+      Metadata: {},
+    };
+
+    await downloadFile(makeCtx(), "generated-skill-link", localPath);
+
+    expect(fs.lstatSync(localPath).isSymbolicLink()).toBe(false);
+    expect(fs.readFileSync(localPath, "utf8")).toBe("remote replacement");
+    expect(fs.readFileSync(path.join(targetDir, "sentinel.txt"), "utf8")).toBe(
+      "source-owned",
+    );
+  });
+
+  it("restores an existing directory link when staged replacement fails", () => {
+    const targetDir = path.join(tmpRoot, "rollback-source");
+    const localPath = path.join(tmpRoot, "rollback-link");
+    const stagedPath = path.join(tmpRoot, ".hq-tmp-rollback-test");
+    fs.mkdirSync(targetDir);
+    fs.symlinkSync(targetDir, localPath, "dir");
+    fs.writeFileSync(stagedPath, "staged replacement");
+
+    let renameCalls = 0;
+    expect(() =>
+      replaceStagedPath(stagedPath, localPath, {
+        lstat: (p) => fs.lstatSync(p),
+        rename: (from, to) => {
+          renameCalls++;
+          if (renameCalls === 2) {
+            throw Object.assign(new Error("simulated Windows replacement failure"), {
+              code: "EPERM",
+            });
+          }
+          fs.renameSync(from, to);
+        },
+        remove: (p) => fs.unlinkSync(p),
+      }),
+    ).toThrow("simulated Windows replacement failure");
+
+    expect(renameCalls).toBe(3);
+    expect(fs.lstatSync(localPath).isSymbolicLink()).toBe(true);
+    expect(fs.readlinkSync(localPath)).toBe(targetDir);
+    expect(fs.readFileSync(stagedPath, "utf8")).toBe("staged replacement");
+    expect(
+      fs.readdirSync(tmpRoot).filter((name) => name.startsWith(".hq-backup-")),
+    ).toEqual([]);
+  });
+
+  it("restores an existing directory link when backup cleanup fails", () => {
+    const targetDir = path.join(tmpRoot, "cleanup-rollback-source");
+    const localPath = path.join(tmpRoot, "cleanup-rollback-link");
+    const stagedPath = path.join(tmpRoot, ".hq-tmp-cleanup-rollback-test");
+    fs.mkdirSync(targetDir);
+    fs.symlinkSync(targetDir, localPath, "dir");
+    fs.writeFileSync(stagedPath, "staged replacement");
+
+    let renameCalls = 0;
+    expect(() =>
+      replaceStagedPath(stagedPath, localPath, {
+        lstat: (p) => fs.lstatSync(p),
+        rename: (from, to) => {
+          renameCalls++;
+          fs.renameSync(from, to);
+        },
+        remove: () => {
+          throw Object.assign(new Error("simulated backup cleanup failure"), {
+            code: "EPERM",
+          });
+        },
+      }),
+    ).toThrow("simulated backup cleanup failure");
+
+    expect(renameCalls).toBe(4);
+    expect(fs.lstatSync(localPath).isSymbolicLink()).toBe(true);
+    expect(fs.readlinkSync(localPath)).toBe(targetDir);
+    expect(fs.readFileSync(stagedPath, "utf8")).toBe("staged replacement");
+    expect(
+      fs.readdirSync(tmpRoot).filter((name) => name.startsWith(".hq-backup-")),
+    ).toEqual([]);
+  });
+
   it("R-F11: downloads to a near component-limit basename via a bounded temp name", async () => {
     nextGetObjectResponse = {
       Body: (async function* () {

package/src/s3.ts

@@ -253,6 +253,89 @@ function removeTempPath(tempPath: string): void {
   }
 }
 
+export interface ReplaceStagedPathOps {
+  lstat(path: string): fs.Stats;
+  rename(from: string, to: string): void;
+  remove(path: string): void;
+}
+
+const DEFAULT_REPLACE_STAGED_PATH_OPS: ReplaceStagedPathOps = {
+  lstat: (p) => fs.lstatSync(p),
+  rename: (from, to) => fs.renameSync(from, to),
+  remove: (p) => fs.unlinkSync(p),
+};
+
+function replacementBackupPath(localPath: string): string {
+  const dir = path.dirname(localPath);
+  const random = crypto.randomBytes(10).toString("hex");
+  return path.join(dir, `.hq-backup-${random}`);
+}
+
+/**
+ * Install a fully-staged download over its destination.
+ *
+ * A direct rename is atomic and remains the fast path for absent destinations
+ * and ordinary files. Windows cannot rename over an existing directory link,
+ * though, because MoveFileEx treats that link as an existing directory. For a
+ * symlink/junction destination, move the old link to a sibling backup first,
+ * install the staged entry, then remove the backup. Any failure after the
+ * backup move restores the exact prior link before rethrowing.
+ *
+ * The tiny operations seam keeps the Windows failure/rollback contract
+ * deterministic in ESM tests without spying on non-configurable fs exports.
+ */
+export function replaceStagedPath(
+  stagedPath: string,
+  localPath: string,
+  ops: ReplaceStagedPathOps = DEFAULT_REPLACE_STAGED_PATH_OPS,
+): void {
+  let existing: fs.Stats;
+  try {
+    existing = ops.lstat(localPath);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      ops.rename(stagedPath, localPath);
+      return;
+    }
+    throw err;
+  }
+
+  if (!existing.isSymbolicLink()) {
+    ops.rename(stagedPath, localPath);
+    return;
+  }
+
+  const backupPath = replacementBackupPath(localPath);
+  ops.rename(localPath, backupPath);
+  let stagedInstalled = false;
+  try {
+    ops.rename(stagedPath, localPath);
+    stagedInstalled = true;
+    ops.remove(backupPath);
+  } catch (primaryError) {
+    const rollbackErrors: unknown[] = [];
+    if (stagedInstalled) {
+      try {
+        ops.rename(localPath, stagedPath);
+      } catch (rollbackError) {
+        rollbackErrors.push(rollbackError);
+      }
+    }
+    try {
+      ops.rename(backupPath, localPath);
+    } catch (rollbackError) {
+      rollbackErrors.push(rollbackError);
+    }
+    if (rollbackErrors.length > 0) {
+      throw new AggregateError(
+        [primaryError, ...rollbackErrors],
+        "Staged path replacement failed and the previous directory link could not be fully restored",
+      );
+    }
+    throw primaryError;
+  }
+}
+
 async function getObjectStream(
   io: ObjectIO,
   key: string,
@@ -809,6 +892,7 @@ export async function downloadFile(
   ctx: EntityContext,
   key: string,
   localPath: string,
+  options: { beforeReplace?: () => void } = {},
 ): Promise<{
   metadata?: Record<string, string>;
   contentHash?: string;
@@ -902,7 +986,8 @@ export async function downloadFile(
     const tempPath = downloadTempPath(localPath);
     try {
       fs.symlinkSync(symlinkTarget, tempPath);
-      fs.renameSync(tempPath, localPath);
+      options.beforeReplace?.();
+      replaceStagedPath(tempPath, localPath);
     } catch (err) {
       removeTempPath(tempPath);
       throw err;
@@ -1011,7 +1096,8 @@ export async function downloadFile(
       }
     }
 
-    fs.renameSync(tempPath, localPath);
+    options.beforeReplace?.();
+    replaceStagedPath(tempPath, localPath);
     tempReady = false;
   } finally {
     if (tempReady) removeTempPath(tempPath);

package/src/types.ts

@@ -26,6 +26,8 @@ export interface JournalEntry {
   size: number;
   syncedAt: string;
   direction: "up" | "down";
+  /** Kind of local object represented by this entry. */
+  kind?: "file" | "symlink";
   /**
    * Cognito `sub` of the file's author, captured from the object's
    * `created-by-sub` S3 user-metadata at download time (zero extra network —
@@ -72,6 +74,17 @@ export interface JournalEntry {
    */
   removedAt?: string;
   removedReason?: "scope_shrink" | "narrow_apply" | "manual" | "local-delete";
+  /**
+   * Explicit local-delete intent. Unlike the legacy `removedReason` marker,
+   * this is bound to the exact synced remote revision and local object shape
+   * that the user approved for deletion.
+   */
+  localDeleteIntent?: {
+    version: 1;
+    remoteEtag: string;
+    localHash: string;
+    localKind: "file" | "symlink";
+  };
   /**
    * Durable automatic-pull retention marker. Set when a scope shrink keeps an
    * out-of-scope caller-authored or unknown-author entry on disk instead of