isolate-package 1.33.0-0 → 1.34.0

package/src/lib/utils/reset-isolate-dir.ts

@@ -0,0 +1,147 @@
+import { randomBytes } from "node:crypto";
+import fs from "fs-extra";
+import path from "node:path";
+import { useLogger } from "../logger";
+
+/**
+ * Prefix used for trash directories created when resetting the isolate output
+ * directory. The leading dot keeps it hidden in file explorers and `ls`
+ * without `-a`, so users don't see a flash of two folders while the old
+ * contents are being reaped in the background.
+ */
+const TRASH_PREFIX = ".";
+const TRASH_INFIX = ".trash-";
+
+export type ResetIsolateDirOptions = {
+  /**
+   * Directory in which to place the temporary "trash" sibling that
+   * `isolateDir` is renamed to before being deleted in the background.
+   * Defaults to `path.dirname(isolateDir)`.
+   *
+   * Callers that pack the parent of `isolateDir` (e.g. `isolate.ts`, which
+   * later runs `npm pack` on `targetPackageDir`) should point this at a
+   * location outside of what gets packed, so the trash can't leak into the
+   * packed output and so the background delete can't race with the pack
+   * step.
+   */
+  trashParentDir?: string;
+};
+
+/**
+ * Reset the isolate output directory to a fresh empty directory, avoiding the
+ * `ENOTEMPTY` race that occurs when another process (e.g. the Firebase
+ * functions emulator, a file watcher) writes into the directory while it is
+ * being recursively deleted.
+ *
+ * Strategy:
+ *
+ * 1. Sweep any leftover trash directories from previous runs that may have
+ *    been killed mid-cleanup. Best-effort: ignore errors.
+ * 2. If the isolate directory exists, atomically `rename` it to a hidden
+ *    sibling on the same filesystem. The rename is atomic, so the moment it
+ *    returns the original path is free for a fresh empty directory and
+ *    nothing a concurrent writer does inside the old tree can affect the
+ *    new one.
+ * 3. Kick off the recursive delete of the trash directory in the background.
+ *    We don't await it: it is the slowest part of an isolate run, and any
+ *    failure (e.g. another process still holding files open) is harmless
+ *    because the logical state is already correct. Stale trash dirs are
+ *    reaped by the next run's sweep in step 1.
+ * 4. Ensure the (now-vacant) isolate directory exists.
+ */
+export async function resetIsolateDir(
+  isolateDir: string,
+  options: ResetIsolateDirOptions = {},
+): Promise<void> {
+  const log = useLogger();
+  const trashParentDir = options.trashParentDir ?? path.dirname(isolateDir);
+  const trashStem = buildTrashStem(trashParentDir, isolateDir);
+  const trashGlobPrefix = `${TRASH_PREFIX}${trashStem}${TRASH_INFIX}`;
+
+  /** Best-effort sweep of leftover trash from previously killed runs. */
+  await sweepStaleTrash(trashParentDir, trashGlobPrefix);
+
+  if (fs.existsSync(isolateDir)) {
+    const trashDir = path.join(
+      trashParentDir,
+      `${trashGlobPrefix}${process.pid}-${randomBytes(4).toString("hex")}`,
+    );
+
+    try {
+      await fs.ensureDir(trashParentDir);
+      await fs.rename(isolateDir, trashDir);
+      log.debug("Moved existing isolate output directory to trash for cleanup");
+
+      /**
+       * Fire-and-forget. A concurrent writer can cause `ENOTEMPTY` or
+       * `EBUSY` here, but the logical state is already correct: the real
+       * `isolateDir` is gone. Any debris left behind will be swept on the
+       * next run.
+       */
+      void fs.remove(trashDir).catch((error: unknown) => {
+        log.debug(
+          "Background cleanup of trashed isolate directory did not complete:",
+          error instanceof Error ? error.message : String(error),
+        );
+      });
+    } catch (error) {
+      /**
+       * `rename` can fail with `EXDEV` if `trashParentDir` ends up on a
+       * different filesystem from `isolateDir`, or with `EPERM` on platforms
+       * that disallow renaming busy directories. Fall back to the original
+       * behaviour: a straight recursive delete. This preserves correctness
+       * at the cost of the race the rename was meant to avoid.
+       */
+      log.debug(
+        "Could not rename existing isolate output directory, falling back to recursive delete:",
+        error instanceof Error ? error.message : String(error),
+      );
+
+      await fs.remove(isolateDir);
+    }
+  }
+
+  await fs.ensureDir(isolateDir);
+}
+
+/**
+ * Build a stable name stem for the trash directory. When `trashParentDir` is
+ * the direct parent of `isolateDir` (the default), this is just the isolate
+ * dir's basename. When it isn't (e.g. callers placing trash outside the
+ * packed dir), include the relative path so multiple isolate dirs sharing
+ * the same trash parent don't collide in the sweep filter.
+ */
+function buildTrashStem(trashParentDir: string, isolateDir: string): string {
+  const relative = path.relative(trashParentDir, isolateDir);
+
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+    return path.basename(isolateDir);
+  }
+
+  return relative.split(path.sep).filter(Boolean).join("-");
+}
+
+/**
+ * Best-effort sweep of leftover trash directories matching this isolate dir's
+ * stem. Failures are swallowed: stale trash is debris, not state, and a
+ * subsequent run will get another chance to reap it.
+ */
+async function sweepStaleTrash(parentDir: string, trashGlobPrefix: string) {
+  let entries: string[];
+  try {
+    entries = await fs.readdir(parentDir);
+  } catch {
+    /** Parent doesn't exist yet; nothing to sweep. */
+    return;
+  }
+
+  await Promise.all(
+    entries
+      .filter((entry) => entry.startsWith(trashGlobPrefix))
+      .map(async (entry) => {
+        await fs.remove(path.join(parentDir, entry)).catch(() => {
+          /** Best-effort. */
+        });
+      }),
+  );
+}

package/src/lib/utils/unpack.test.ts

@@ -0,0 +1,76 @@
+import fs from "fs-extra";
+import { createWriteStream } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { pipeline } from "node:stream/promises";
+import { createGzip } from "node:zlib";
+import { pack as packTar } from "tar-fs";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { unpack } from "./unpack";
+
+async function createTarball(srcDir: string, tarballPath: string) {
+  await pipeline(packTar(srcDir), createGzip(), createWriteStream(tarballPath));
+}
+
+describe("unpack", () => {
+  let tempDir: string;
+
+  beforeEach(async () => {
+    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "isolate-unpack-test-"));
+  });
+
+  afterEach(async () => {
+    await fs.remove(tempDir);
+  });
+
+  it("extracts a valid gzipped tarball into the destination directory", async () => {
+    const srcDir = path.join(tempDir, "src");
+    await fs.ensureDir(path.join(srcDir, "nested"));
+    await fs.writeFile(path.join(srcDir, "root.txt"), "hello");
+    await fs.writeFile(path.join(srcDir, "nested", "leaf.txt"), "world");
+
+    const tarballPath = path.join(tempDir, "archive.tgz");
+    await createTarball(srcDir, tarballPath);
+
+    const unpackDir = path.join(tempDir, "out");
+    await unpack(tarballPath, unpackDir);
+
+    expect(await fs.readFile(path.join(unpackDir, "root.txt"), "utf8")).toBe(
+      "hello",
+    );
+    expect(
+      await fs.readFile(path.join(unpackDir, "nested", "leaf.txt"), "utf8"),
+    ).toBe("world");
+  });
+
+  it("rejects with an error when the tarball is truncated", async () => {
+    const srcDir = path.join(tempDir, "src");
+    await fs.ensureDir(srcDir);
+    await fs.writeFile(path.join(srcDir, "file.txt"), "a".repeat(8192));
+
+    const tarballPath = path.join(tempDir, "archive.tgz");
+    await createTarball(srcDir, tarballPath);
+
+    const truncatedPath = path.join(tempDir, "truncated.tgz");
+    const fullData = await fs.readFile(tarballPath);
+    await fs.writeFile(truncatedPath, fullData.subarray(0, 32));
+
+    const unpackDir = path.join(tempDir, "out");
+
+    /**
+     * Pre-fix, the gunzip error from a truncated archive surfaced as an
+     * unhandled stream error and crashed the process. With `pipeline` the
+     * same scenario must reject the returned promise so callers can handle
+     * it.
+     */
+    await expect(unpack(truncatedPath, unpackDir)).rejects.toThrow();
+  });
+
+  it("rejects when the source path does not exist", async () => {
+    const unpackDir = path.join(tempDir, "out");
+
+    await expect(
+      unpack(path.join(tempDir, "does-not-exist.tgz"), unpackDir),
+    ).rejects.toThrow();
+  });
+});

package/src/lib/utils/unpack.ts

@@ -1,13 +1,19 @@
-import fs from "fs-extra";
-import tar from "tar-fs";
-import { createGunzip } from "zlib";
+import { createReadStream } from "node:fs";
+import { pipeline } from "node:stream/promises";
+import { createGunzip } from "node:zlib";
+import { extract as extractTar } from "tar-fs";
 
+/**
+ * Extract a gzipped tar archive into the given directory.
+ *
+ * Uses `stream/promises.pipeline` so that errors at any stage (file read,
+ * gunzip, tar extract) propagate as a rejected promise rather than crashing
+ * the process as unhandled stream errors.
+ */
 export async function unpack(filePath: string, unpackDir: string) {
-  await new Promise<void>((resolve, reject) => {
-    fs.createReadStream(filePath)
-      .pipe(createGunzip())
-      .pipe(tar.extract(unpackDir))
-      .on("finish", () => resolve())
-      .on("error", (err) => reject(err));
-  });
+  await pipeline(
+    createReadStream(filePath),
+    createGunzip(),
+    extractTar(unpackDir),
+  );
 }

package/src/lib/utils/wait-for-complete-file.test.ts

@@ -0,0 +1,105 @@
+import fs from "fs-extra";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { waitForCompleteFile } from "./wait-for-complete-file";
+
+describe("waitForCompleteFile", () => {
+  let tempDir: string;
+
+  beforeEach(async () => {
+    tempDir = await fs.mkdtemp(
+      path.join(os.tmpdir(), "isolate-wait-for-file-"),
+    );
+  });
+
+  afterEach(async () => {
+    await fs.remove(tempDir);
+  });
+
+  it("resolves for a file that already exists with stable size", async () => {
+    const filePath = path.join(tempDir, "ready.bin");
+    await fs.writeFile(filePath, Buffer.alloc(1024, 0x42));
+
+    await expect(
+      waitForCompleteFile(filePath, { timeoutMs: 1000, pollMs: 20 }),
+    ).resolves.toBeUndefined();
+  });
+
+  it("waits until a file that appears late is written", async () => {
+    const filePath = path.join(tempDir, "late.bin");
+
+    const write = setTimeout(() => {
+      void fs.writeFile(filePath, Buffer.alloc(512, 0x01));
+    }, 60);
+
+    try {
+      await expect(
+        waitForCompleteFile(filePath, { timeoutMs: 1000, pollMs: 20 }),
+      ).resolves.toBeUndefined();
+
+      const { size } = await fs.stat(filePath);
+      expect(size).toBe(512);
+    } finally {
+      clearTimeout(write);
+    }
+  });
+
+  it("waits for size to stabilize when a file grows in chunks", async () => {
+    const filePath = path.join(tempDir, "growing.bin");
+    const pollMs = 100;
+    /**
+     * The total write window (`chunkIntervalMs * chunkCount` = 150ms) is
+     * shorter than two poll intervals, so the wait cannot observe two
+     * consecutive equal sizes until after the final chunk has landed. That
+     * is what guards against a false-positive return at a partial size, not
+     * the per-chunk spacing.
+     */
+    const chunkIntervalMs = 30;
+    const chunkCount = 5;
+
+    const writes = Array.from({ length: chunkCount }, (_, i) =>
+      setTimeout(
+        () => {
+          const op =
+            i === 0
+              ? fs.writeFile(filePath, Buffer.alloc(100, i + 1))
+              : fs.appendFile(filePath, Buffer.alloc(100, i + 1));
+          void op;
+        },
+        chunkIntervalMs * (i + 1),
+      ),
+    );
+
+    try {
+      await waitForCompleteFile(filePath, { timeoutMs: 2000, pollMs });
+
+      /**
+       * Returning before the file finished growing would leave size below
+       * chunkCount * 100. Observing the full size confirms the wait did not
+       * exit mid-write.
+       */
+      const { size } = await fs.stat(filePath);
+      expect(size).toBe(chunkCount * 100);
+    } finally {
+      writes.forEach((t) => clearTimeout(t));
+    }
+  });
+
+  it("rejects with a timeout error when the file never appears", async () => {
+    const filePath = path.join(tempDir, "missing.bin");
+
+    await expect(
+      waitForCompleteFile(filePath, { timeoutMs: 150, pollMs: 20 }),
+    ).rejects.toThrow(/Timed out after 150ms/);
+  });
+
+  it("rejects with a timeout error when the file stays empty", async () => {
+    const filePath = path.join(tempDir, "empty.bin");
+    await fs.writeFile(filePath, "");
+
+    await expect(
+      waitForCompleteFile(filePath, { timeoutMs: 150, pollMs: 20 }),
+    ).rejects.toThrow(/Timed out/);
+  });
+});

package/src/lib/utils/wait-for-complete-file.ts

@@ -0,0 +1,44 @@
+import fs from "node:fs";
+
+/**
+ * Wait until the given file exists and its size has stopped changing across
+ * two consecutive polls. Resolves once the file is considered fully written,
+ * rejects with a timeout error otherwise.
+ *
+ * This is a cheap proxy for "the writer has finished flushing" without
+ * inspecting file contents or relying on platform-specific signals. It is
+ * intended for cases where an external process (e.g. `pnpm pack`) may report
+ * completion before its output is fully visible on disk.
+ */
+export async function waitForCompleteFile(
+  filePath: string,
+  { timeoutMs, pollMs }: { timeoutMs: number; pollMs: number },
+) {
+  const deadline = Date.now() + timeoutMs;
+  let lastSize = -1;
+
+  while (Date.now() < deadline) {
+    try {
+      const { size } = await fs.promises.stat(filePath);
+
+      if (size > 0 && size === lastSize) {
+        return;
+      }
+
+      lastSize = size;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+        throw error;
+      }
+      /** File not visible yet; keep polling. */
+    }
+
+    await new Promise<void>((resolve) => {
+      setTimeout(resolve, pollMs);
+    });
+  }
+
+  throw new Error(
+    `Timed out after ${timeoutMs}ms waiting for file to be written: ${filePath}`,
+  );
+}

package/src/lib/utils/yaml.ts

@@ -2,21 +2,20 @@ import fs from "fs-extra";
 import yaml from "yaml";
 import { getErrorMessage } from "./get-error-message";
 
-export function readTypedYamlSync<T>(filePath: string) {
+/** @todo Add some zod validation maybe */
+export function readTypedYamlSync(filePath: string): unknown {
   try {
     const rawContent = fs.readFileSync(filePath, "utf-8");
-    const data = yaml.parse(rawContent);
-    /** @todo Add some zod validation maybe */
-    return data as T;
-  } catch (err) {
+    return yaml.parse(rawContent) as unknown;
+  } catch (error) {
     throw new Error(
-      `Failed to read YAML from ${filePath}: ${getErrorMessage(err)}`,
-      { cause: err },
+      `Failed to read YAML from ${filePath}: ${getErrorMessage(error)}`,
+      { cause: error },
     );
   }
 }
 
-export function writeTypedYamlSync<T>(filePath: string, content: T) {
-  /** @todo Add some zod validation maybe */
+/** @todo Add some zod validation maybe */
+export function writeTypedYamlSync(filePath: string, content: unknown) {
   fs.writeFileSync(filePath, yaml.stringify(content), "utf-8");
 }

package/src/testing/setup.ts

@@ -1,7 +1,7 @@
 import { vi } from "vitest";
 
 /** Mock the logger for all tests to prevent console output during tests */
-vi.mock("~/lib/logger", () => ({
+vi.mock("#/lib/logger", () => ({
   useLogger: () => ({
     debug: vi.fn(),
     info: vi.fn(),