@unotest/core 0.25.0 → 0.26.1

package/dist/index.js

@@ -298,9 +298,9 @@ async function startDebugCommandsWatcher(deps) {
     if (stopped || !handle) return;
     inflight = inflight.then(async () => {
       if (stopped || !handle) return;
-      const stat = await handle.stat();
-      if (stat.size <= offset) return;
-      const len = stat.size - offset;
+      const stat2 = await handle.stat();
+      if (stat2.size <= offset) return;
+      const len = stat2.size - offset;
       const buf = Buffer.alloc(len);
       const { bytesRead } = await handle.read(buf, 0, len, offset);
       offset += bytesRead;
@@ -586,26 +586,1007 @@ var UnotestError = class extends Error {
     }
   }
 };
+
+// src/index.ts
+import { isRecord } from "@unotest/protocol";
+
+// src/run-queue/fs-run-queue.ts
+import { mkdir as mkdir6 } from "fs/promises";
+import { join as join10 } from "path";
+import {
+  QUEUE_GLOBAL_DIR_ENV,
+  QUEUE_GLOBAL_SLOTS_ENV,
+  QUEUE_LEASE_ENV,
+  QUEUE_MUTEX_FILE,
+  QUEUE_RUNNING_DIR,
+  QUEUE_SCHEMA_VERSION,
+  QUEUE_SLOTS_DIR,
+  QUEUE_TICKETS_DIR,
+  compareQueueTicketNames,
+  makeQueueTicketName,
+  parseQueueTicket,
+  parseQueueTicketName,
+  queuePriorityRank
+} from "@unotest/protocol";
+
+// src/run-queue/errors.ts
+var QueueTicketLostError = class extends UnotestError {
+  static {
+    __name(this, "QueueTicketLostError");
+  }
+  constructor(ticketName) {
+    super(
+      `queue ticket ${ticketName} is gone \u2014 it was cancelled or reaped while waiting for a slot`,
+      { ticketName }
+    );
+  }
+};
+var QueueWaitAbortedError = class extends UnotestError {
+  static {
+    __name(this, "QueueWaitAbortedError");
+  }
+  constructor(ticketName) {
+    super(`stopped waiting for a queue slot (ticket ${ticketName} withdrawn)`, {
+      ticketName
+    });
+  }
+};
+var QueueUnavailableError = class extends UnotestError {
+  static {
+    __name(this, "QueueUnavailableError");
+  }
+  constructor(root, cause) {
+    super(
+      `run queue at ${root} is unusable: ${cause}. Fix the directory permissions, or set UNOTEST_NO_QUEUE=1 to run without queueing.`,
+      { root, cause }
+    );
+  }
+};
+
+// src/run-queue/fs-primitives.ts
+import { unlinkSync } from "fs";
+import {
+  open as open2,
+  readFile,
+  readdir,
+  rename as rename4,
+  stat,
+  unlink,
+  utimes as utimes2,
+  writeFile as writeFile6
+} from "fs/promises";
+import { dirname as dirname3, join as join8 } from "path";
+async function createExclusive(path, contents) {
+  let handle;
+  try {
+    handle = await open2(path, "wx");
+  } catch (e) {
+    if (isErrno(e, "EEXIST")) return false;
+    throw e;
+  }
+  try {
+    await handle.writeFile(contents, "utf8");
+  } finally {
+    await handle.close();
+  }
+  return true;
+}
+__name(createExclusive, "createExclusive");
+async function writeFileAtomic(path, contents, tmpToken) {
+  const tmp = join8(dirname3(path), `.tmp-${tmpToken}`);
+  await writeFile6(tmp, contents, "utf8");
+  await rename4(tmp, path);
+}
+__name(writeFileAtomic, "writeFileAtomic");
+async function touchFile(path, now) {
+  const seconds = now / 1e3;
+  try {
+    await utimes2(path, seconds, seconds);
+  } catch (e) {
+    if (!isErrno(e, "ENOENT")) throw e;
+  }
+}
+__name(touchFile, "touchFile");
+async function fileAgeMs(path, now) {
+  try {
+    const s = await stat(path);
+    return now - s.mtimeMs;
+  } catch (e) {
+    if (isErrno(e, "ENOENT")) return null;
+    throw e;
+  }
+}
+__name(fileAgeMs, "fileAgeMs");
+async function removeFile(path) {
+  try {
+    await unlink(path);
+    return true;
+  } catch (e) {
+    if (isErrno(e, "ENOENT")) return false;
+    throw e;
+  }
+}
+__name(removeFile, "removeFile");
+async function readTextFile(path) {
+  try {
+    return await readFile(path, "utf8");
+  } catch (e) {
+    if (isErrno(e, "ENOENT")) return null;
+    throw e;
+  }
+}
+__name(readTextFile, "readTextFile");
+function removeFileSync(path) {
+  try {
+    unlinkSync(path);
+  } catch (e) {
+    if (!isErrno(e, "ENOENT")) throw e;
+  }
+}
+__name(removeFileSync, "removeFileSync");
+async function listDir(dir) {
+  try {
+    return await readdir(dir);
+  } catch (e) {
+    if (isErrno(e, "ENOENT")) return [];
+    throw e;
+  }
+}
+__name(listDir, "listDir");
+async function quarantineAndRemove(path, token) {
+  const dir = dirname3(path);
+  const quarantined = join8(dir, `stale-${token}`);
+  try {
+    await rename4(path, quarantined);
+  } catch (e) {
+    if (isErrno(e, "ENOENT")) return false;
+    throw e;
+  }
+  await removeFile(quarantined);
+  return true;
+}
+__name(quarantineAndRemove, "quarantineAndRemove");
+async function moveFile(from, to) {
+  try {
+    await rename4(from, to);
+    return true;
+  } catch (e) {
+    if (isErrno(e, "ENOENT")) return false;
+    throw e;
+  }
+}
+__name(moveFile, "moveFile");
+function isErrno(e, code) {
+  return typeof e === "object" && e !== null && e.code === code;
+}
+__name(isErrno, "isErrno");
+
+// src/run-queue/slot-pool.ts
+import { mkdir as mkdir5 } from "fs/promises";
+import { join as join9 } from "path";
+var SLOT_PREFIX = "slot-";
+var SlotPool = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  opts;
+  static {
+    __name(this, "SlotPool");
+  }
+  get total() {
+    return this.opts.total;
+  }
+  /** Take `count` leases, all or nothing. Returns the lease names, or
+   *  null when the pool cannot satisfy the request right now — a normal
+   *  outcome the caller answers by waiting. */
+  async claim(count, payload) {
+    if (count > this.opts.total) return null;
+    await mkdir5(this.opts.dir, { recursive: true });
+    if (!this.opts.mutex) return this.claimUnguarded(count, payload);
+    const claimed = await this.withMutex(
+      (keepAlive) => this.claimUnguarded(count, payload, keepAlive)
+    );
+    return claimed ?? null;
+  }
+  async release(names) {
+    for (const name of names) await removeFile(join9(this.opts.dir, name));
+  }
+  /** For a holder that is exiting inside a signal handler. */
+  releaseSync(names) {
+    for (const name of names) removeFileSync(join9(this.opts.dir, name));
+  }
+  /** Keep the leases alive. A holder that stops touching is treated as
+   *  dead after `staleAfterMs` and its leases are reaped. */
+  async touch(names) {
+    const now = this.opts.now();
+    for (const name of names) await touchFile(join9(this.opts.dir, name), now);
+  }
+  /** Reap dead leases, then report what is left. */
+  sweep() {
+    return this.scan(true);
+  }
+  /** Report without reaping — for a snapshot the UI renders. */
+  inspect() {
+    return this.scan(false);
+  }
+  async claimUnguarded(count, payload, keepAlive) {
+    const taken = [];
+    const body = JSON.stringify(payload);
+    for (let n = 0; n < this.opts.total && taken.length < count; n++) {
+      await keepAlive?.();
+      const name = `${SLOT_PREFIX}${n}`;
+      if (await createExclusive(join9(this.opts.dir, name), body)) {
+        taken.push(name);
+      }
+    }
+    if (taken.length < count) {
+      await this.release(taken);
+      return null;
+    }
+    return taken;
+  }
+  async scan(reap) {
+    const runIds = /* @__PURE__ */ new Set();
+    let used = 0;
+    for (const name of await listDir(this.opts.dir)) {
+      if (!name.startsWith(SLOT_PREFIX)) continue;
+      const path = join9(this.opts.dir, name);
+      const age = await fileAgeMs(path, this.opts.now());
+      if (age === null) continue;
+      if (age > this.opts.staleAfterMs) {
+        if (reap) {
+          await quarantineAndRemove(path, `${name}-${this.opts.token()}`);
+          continue;
+        }
+      }
+      used++;
+      const payload = parseSlotPayload(await readTextFile(path));
+      if (payload) runIds.add(payload.runId);
+    }
+    return { total: this.opts.total, used, runIds };
+  }
+  /** Run `body` while holding the pool's mutex. Returns undefined when
+   *  the mutex could not be taken in time — the caller retries on its
+   *  own cadence. `body` receives a keep-alive callback it should invoke
+   *  between filesystem operations so a slow critical section is not
+   *  mistaken for a dead holder. */
+  async withMutex(body) {
+    const mutex = this.opts.mutex;
+    if (!mutex) return body(async () => {
+    });
+    const token = this.opts.token();
+    for (let attempt = 0; attempt < mutex.attempts; attempt++) {
+      if (await createExclusive(mutex.path, token)) {
+        try {
+          return await body(() => touchFile(mutex.path, this.opts.now()));
+        } finally {
+          if (await readTextFile(mutex.path) === token) {
+            await removeFile(mutex.path);
+          }
+        }
+      }
+      const age = await fileAgeMs(mutex.path, this.opts.now());
+      if (age !== null && age > mutex.staleAfterMs) {
+        await quarantineAndRemove(mutex.path, `mutex-${this.opts.token()}`);
+        continue;
+      }
+      await this.opts.sleep(mutex.waitMs);
+    }
+    return void 0;
+  }
+};
+function parseSlotPayload(text) {
+  if (text === null) return null;
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (typeof value !== "object" || value === null) return null;
+  const { runId, ticket, pid, host, at } = value;
+  if (typeof runId !== "string" || typeof ticket !== "string") return null;
+  if (typeof pid !== "number" || typeof host !== "string") return null;
+  return { runId, ticket, pid, host, at: typeof at === "number" ? at : 0 };
+}
+__name(parseSlotPayload, "parseSlotPayload");
+
+// src/run-queue/fs-run-queue.ts
+var DEFAULT_STALE_AFTER_MS = 6e4;
+var DEFAULT_TOUCH_INTERVAL_MS = 1e4;
+var DEFAULT_POLL_INTERVAL_MS = 500;
+var MUTEX_STALE_MS = 1e4;
+var MUTEX_ATTEMPTS = 20;
+var MUTEX_WAIT_MS = 25;
+var MAINTENANCE_PREFIX = `${queuePriorityRank("maintenance")}-`;
+function globalPoolFromEnv(env = process.env) {
+  const dir = env[QUEUE_GLOBAL_DIR_ENV]?.trim();
+  if (!dir) return null;
+  const raw = env[QUEUE_GLOBAL_SLOTS_ENV]?.trim();
+  const slots = raw ? Number(raw) : NaN;
+  return {
+    dir,
+    // A pool directory without a usable size is a configuration slip, not
+    // a reason to refuse to run: fall back to one, which is the safest
+    // possible host budget.
+    slots: Number.isInteger(slots) && slots > 0 ? slots : 1
+  };
+}
+__name(globalPoolFromEnv, "globalPoolFromEnv");
+var FsRunQueue = class {
+  static {
+    __name(this, "FsRunQueue");
+  }
+  root;
+  ticketsDir;
+  runningDir;
+  staleAfterMs;
+  touchIntervalMs;
+  pollIntervalMs;
+  now;
+  random;
+  sleep;
+  envPool;
+  globalPool;
+  constructor(opts) {
+    this.root = opts.root;
+    this.ticketsDir = join10(opts.root, QUEUE_TICKETS_DIR);
+    this.runningDir = join10(opts.root, QUEUE_RUNNING_DIR);
+    this.staleAfterMs = opts.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;
+    this.touchIntervalMs = opts.touchIntervalMs ?? DEFAULT_TOUCH_INTERVAL_MS;
+    this.pollIntervalMs = opts.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    this.now = opts.now ?? (() => Date.now());
+    this.random = opts.random ?? randomToken;
+    this.sleep = opts.sleep ?? ((ms) => new Promise((r) => {
+      setTimeout(r, ms);
+    }));
+    const shared = {
+      staleAfterMs: this.staleAfterMs,
+      now: this.now,
+      token: this.random,
+      sleep: this.sleep
+    };
+    this.envPool = new SlotPool({
+      dir: join10(opts.root, QUEUE_SLOTS_DIR),
+      total: Math.max(1, Math.floor(opts.slots)),
+      ...shared
+    });
+    this.globalPool = opts.global ? new SlotPool({
+      dir: join10(opts.global.dir, QUEUE_SLOTS_DIR),
+      total: Math.max(1, Math.floor(opts.global.slots)),
+      mutex: {
+        path: join10(opts.global.dir, QUEUE_MUTEX_FILE),
+        staleAfterMs: MUTEX_STALE_MS,
+        attempts: MUTEX_ATTEMPTS,
+        waitMs: MUTEX_WAIT_MS
+      },
+      ...shared
+    }) : null;
+  }
+  async enqueue(input) {
+    const createdAt = this.now();
+    const priority = input.kind === "maintenance" ? "maintenance" : input.priority;
+    const ticket = {
+      schemaVersion: QUEUE_SCHEMA_VERSION,
+      runId: input.runId,
+      kind: input.kind,
+      ref: input.ref,
+      priority,
+      // A weight larger than the pool would never be satisfiable; the
+      // run still has to happen, so it takes the whole pool instead.
+      weight: this.clampWeight(input.weight ?? 1),
+      producer: input.producer,
+      createdAt,
+      ...input.env ? { env: input.env } : {},
+      // Recorded at ENQUEUE time on purpose: an environment switched while
+      // this ticket waits must not change what it runs.
+      ...input.source ? { source: input.source } : {},
+      ...input.ci ? { ci: input.ci } : {}
+    };
+    const name = makeQueueTicketName(priority, createdAt, this.random());
+    try {
+      await mkdir6(this.ticketsDir, { recursive: true });
+      await mkdir6(this.runningDir, { recursive: true });
+      await writeFileAtomic(
+        join10(this.ticketsDir, name),
+        JSON.stringify(ticket),
+        `${name}-${this.random()}`
+      );
+    } catch (e) {
+      throw new QueueUnavailableError(
+        this.root,
+        e instanceof Error ? e.message : String(e)
+      );
+    }
+    return new FsTicketHandle(this, name, ticket);
+  }
+  async snapshot() {
+    const waiting = await this.readEntries(this.ticketsDir);
+    const running = await this.readEntries(this.runningDir);
+    const slots = await this.envPool.inspect();
+    const global = this.globalPool ? await this.globalPool.inspect() : null;
+    return {
+      waiting,
+      running,
+      slots: { total: slots.total, used: slots.used },
+      ...global ? { global: { total: global.total, used: global.used } } : {}
+    };
+  }
+  async cancel(ticketName) {
+    if (parseQueueTicketName(ticketName) === null) return false;
+    return removeFile(join10(this.ticketsDir, ticketName));
+  }
+  /** Reap what died, then drop `running/` entries with no lease behind
+   *  them. Every producer calls this on its way past — a queue with any
+   *  traffic needs no janitor process. */
+  async sweep() {
+    const now = this.now();
+    for (const name of await listDir(this.ticketsDir)) {
+      const path = join10(this.ticketsDir, name);
+      const age = await fileAgeMs(path, now);
+      if (age === null || age <= this.staleAfterMs) continue;
+      await quarantineAndRemove(path, `${name}-${this.random()}`);
+    }
+    const live = await this.envPool.sweep();
+    if (this.globalPool) await this.globalPool.sweep();
+    for (const name of await listDir(this.runningDir)) {
+      const path = join10(this.runningDir, name);
+      const age = await fileAgeMs(path, now);
+      if (age === null || age <= this.staleAfterMs) continue;
+      const ticket = parseQueueTicket(await readJson(path));
+      if (ticket && live.runIds.has(ticket.runId)) continue;
+      await quarantineAndRemove(path, `${name}-${this.random()}`);
+    }
+  }
+  /** Wait until `handle` owns a slot. Public only for the handle it
+   *  belongs to. */
+  async acquire(handle, signal) {
+    let lastTouch = this.now();
+    for (; ; ) {
+      if (signal?.aborted) {
+        await this.cancel(handle.name);
+        throw new QueueWaitAbortedError(handle.name);
+      }
+      await this.sweep();
+      const order = await this.waitingOrder();
+      const index = order.indexOf(handle.name);
+      if (index < 0) throw new QueueTicketLostError(handle.name);
+      const lease = await this.tryClaim(handle, index, order);
+      if (lease) return lease;
+      const now = this.now();
+      if (now - lastTouch >= this.touchIntervalMs) {
+        await touchFile(join10(this.ticketsDir, handle.name), now);
+        lastTouch = now;
+      }
+      await this.sleep(this.pollIntervalMs);
+    }
+  }
+  /** One claim attempt for the ticket sitting at `index` of the live
+   *  queue. Null means "not now" — the caller waits and retries.
+   *
+   *  Position rule: a ticket may attempt a claim when its index is below
+   *  the environment's slot count. With the default concurrency of 1
+   *  that is strict FIFO; above it, two eligible tickets may take a
+   *  freed slot out of order, which is the price of not serialising
+   *  every waiter behind the head of the queue.
+   *
+   *  A maintenance ticket is exclusive: it waits for the head position
+   *  and then takes EVERY slot, so nothing else runs while it mutates
+   *  the environment. While one is at the head, NOBODY else may claim —
+   *  without that drain rule a steady stream of later tickets would keep
+   *  grabbing each freed slot and the head's all-or-nothing claim would
+   *  starve forever. Detected from ticket names (the maintenance rank is
+   *  the first character), so waiters never read each other's files. */
+  async tryClaim(handle, index, order) {
+    const exclusive = handle.ticket.kind === "maintenance";
+    if (exclusive ? index !== 0 : index >= this.envPool.total) return null;
+    if (!exclusive && index > 0 && order[0].startsWith(MAINTENANCE_PREFIX)) {
+      return null;
+    }
+    const payload = {
+      runId: handle.ticket.runId,
+      ticket: handle.name,
+      pid: handle.ticket.producer.pid,
+      host: handle.ticket.producer.host,
+      at: this.now()
+    };
+    const envSlots = await this.envPool.claim(
+      exclusive ? this.envPool.total : 1,
+      payload
+    );
+    if (!envSlots) return null;
+    let globalSlots = null;
+    if (this.globalPool) {
+      globalSlots = await this.globalPool.claim(handle.ticket.weight, payload);
+      if (!globalSlots) {
+        await this.envPool.release(envSlots);
+        return null;
+      }
+    }
+    const promoted = await moveFile(
+      join10(this.ticketsDir, handle.name),
+      join10(this.runningDir, handle.name)
+    );
+    if (!promoted) {
+      await this.envPool.release(envSlots);
+      if (globalSlots) await this.globalPool?.release(globalSlots);
+      throw new QueueTicketLostError(handle.name);
+    }
+    return new FsLease(this, handle, envSlots, globalSlots);
+  }
+  /** Live waiting tickets, in service order. */
+  async waitingOrder() {
+    return (await listDir(this.ticketsDir)).filter((name) => parseQueueTicketName(name) !== null).sort(compareQueueTicketNames);
+  }
+  async readEntries(dir) {
+    const names = (await listDir(dir)).filter((name) => parseQueueTicketName(name) !== null).sort(compareQueueTicketNames);
+    const out = [];
+    for (const name of names) {
+      const ticket = parseQueueTicket(await readJson(join10(dir, name)));
+      if (ticket) out.push({ name, ticket });
+    }
+    return out;
+  }
+  clampWeight(weight) {
+    const w = Number.isFinite(weight) ? Math.floor(weight) : 1;
+    const capped = this.globalPool ? Math.min(w, this.globalPool.total) : w;
+    return Math.max(1, capped);
+  }
+  /** Heartbeat + teardown for a lease — kept here so `FsLease` stays a
+   *  handle and the filesystem knowledge stays in one class. */
+  async releaseLease(handle, envSlots, globalSlots) {
+    await removeFile(join10(this.runningDir, handle.name));
+    if (globalSlots) await this.globalPool?.release(globalSlots);
+    await this.envPool.release(envSlots);
+  }
+  releaseLeaseSync(handle, envSlots, globalSlots) {
+    removeFileSync(join10(this.runningDir, handle.name));
+    if (globalSlots) this.globalPool?.releaseSync(globalSlots);
+    this.envPool.releaseSync(envSlots);
+  }
+  async touchLease(handle, envSlots, globalSlots) {
+    await touchFile(join10(this.runningDir, handle.name), this.now());
+    await this.envPool.touch(envSlots);
+    if (globalSlots) await this.globalPool?.touch(globalSlots);
+  }
+  get heartbeatIntervalMs() {
+    return this.touchIntervalMs;
+  }
+};
+var FsTicketHandle = class {
+  constructor(queue, name, ticket) {
+    this.queue = queue;
+    this.name = name;
+    this.ticket = ticket;
+  }
+  queue;
+  name;
+  ticket;
+  static {
+    __name(this, "FsTicketHandle");
+  }
+  acquire(opts) {
+    return this.queue.acquire(this, opts?.signal);
+  }
+  async cancel() {
+    await this.queue.cancel(this.name);
+  }
+};
+var FsLease = class {
+  constructor(queue, handle, envSlots, globalSlots) {
+    this.queue = queue;
+    this.handle = handle;
+    this.envSlots = envSlots;
+    this.globalSlots = globalSlots;
+    this.heartbeat = setInterval(() => {
+      void this.queue.touchLease(this.handle, this.envSlots, this.globalSlots).catch(() => {
+      });
+    }, this.queue.heartbeatIntervalMs);
+    this.heartbeat.unref?.();
+  }
+  queue;
+  handle;
+  envSlots;
+  globalSlots;
+  static {
+    __name(this, "FsLease");
+  }
+  released = false;
+  heartbeat;
+  get runId() {
+    return this.handle.ticket.runId;
+  }
+  get ticketName() {
+    return this.handle.name;
+  }
+  get env() {
+    return leaseEnv(this.handle.ticket.runId);
+  }
+  async release() {
+    if (this.released) return;
+    this.released = true;
+    clearInterval(this.heartbeat);
+    await this.queue.releaseLease(this.handle, this.envSlots, this.globalSlots);
+  }
+  releaseSync() {
+    if (this.released) return;
+    this.released = true;
+    clearInterval(this.heartbeat);
+    this.queue.releaseLeaseSync(this.handle, this.envSlots, this.globalSlots);
+  }
+};
+function leaseEnv(runId) {
+  return Object.freeze({ [QUEUE_LEASE_ENV]: runId });
+}
+__name(leaseEnv, "leaseEnv");
+async function readJson(path) {
+  const text = await readTextFile(path);
+  if (text === null) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+__name(readJson, "readJson");
+function randomToken() {
+  const bytes = new Uint8Array(6);
+  globalThis.crypto.getRandomValues(bytes);
+  let out = "";
+  for (const b of bytes) out += b.toString(16).padStart(2, "0");
+  return out;
+}
+__name(randomToken, "randomToken");
+
+// src/bundle/bundle-archive.ts
+import {
+  BUNDLE_MANIFEST_FILE,
+  BUNDLE_SCHEMA_VERSION,
+  parseBundleManifest
+} from "@unotest/protocol";
+import { createHash } from "crypto";
+import { gunzipSync, gzipSync } from "zlib";
+
+// src/bundle/errors.ts
+var BundleFormatError = class extends UnotestError {
+  static {
+    __name(this, "BundleFormatError");
+  }
+  constructor(reason, context = {}) {
+    super(`not a readable test bundle: ${reason}`, { reason, ...context });
+  }
+};
+var BundlePathError = class extends UnotestError {
+  static {
+    __name(this, "BundlePathError");
+  }
+  constructor(path, reason) {
+    super(`bundle path "${path}" is not allowed: ${reason}`, { path, reason });
+  }
+};
+var BundleTooLargeError = class extends UnotestError {
+  static {
+    __name(this, "BundleTooLargeError");
+  }
+  constructor(limitBytes) {
+    super(
+      `test bundle unpacks to more than ${limitBytes} bytes \u2014 the limit is there because a bundle is unpacked before anything about it is known`,
+      { limitBytes }
+    );
+  }
+};
+var BundleIdMismatchError = class extends UnotestError {
+  static {
+    __name(this, "BundleIdMismatchError");
+  }
+  constructor(claimed, computed) {
+    super(
+      `bundle content hashes to ${computed} but the manifest says ${claimed} \u2014 the archive was altered or truncated in transit`,
+      { claimed, computed }
+    );
+  }
+};
+
+// src/bundle/ustar.ts
+var BLOCK = 512;
+var NAME_FIELD = 100;
+var PREFIX_FIELD = 155;
+var FILE_MODE = 420;
+var EXEC_MODE = 493;
+function assertSafeBundlePath(path) {
+  if (path.length === 0) throw new BundlePathError(path, "it is empty");
+  if (path.includes("\0")) throw new BundlePathError(path, "it contains a NUL byte");
+  if (path.includes("\\")) {
+    throw new BundlePathError(path, "paths are posix \u2014 use `/`, never `\\`");
+  }
+  if (path.startsWith("/")) throw new BundlePathError(path, "it is absolute");
+  if (/^[a-zA-Z]:/.test(path)) {
+    throw new BundlePathError(path, "it carries a Windows drive letter");
+  }
+  for (const segment of path.split("/")) {
+    if (segment === "") throw new BundlePathError(path, "it has an empty segment");
+    if (segment === "." || segment === "..") {
+      throw new BundlePathError(path, "it walks out of the bundle with `.` / `..`");
+    }
+  }
+}
+__name(assertSafeBundlePath, "assertSafeBundlePath");
+function splitUstarPath(path) {
+  if (Buffer.byteLength(path) <= NAME_FIELD) return { name: path, prefix: "" };
+  const cut = path.lastIndexOf("/", PREFIX_FIELD);
+  const prefix = cut > 0 ? path.slice(0, cut) : "";
+  const name = cut > 0 ? path.slice(cut + 1) : path;
+  if (prefix === "" || Buffer.byteLength(name) > NAME_FIELD || Buffer.byteLength(prefix) > PREFIX_FIELD) {
+    throw new BundlePathError(
+      path,
+      `it does not fit the tar header (${NAME_FIELD} bytes of file name, ${PREFIX_FIELD} of directory) \u2014 shorten it`
+    );
+  }
+  return { name, prefix };
+}
+__name(splitUstarPath, "splitUstarPath");
+function writeString(block, value, offset, size) {
+  const bytes = Buffer.from(value, "utf8");
+  if (bytes.length > size) {
+    throw new BundleFormatError(`"${value}" does not fit a ${size}-byte header field`);
+  }
+  bytes.copy(block, offset);
+}
+__name(writeString, "writeString");
+function writeOctal(block, value, offset, size) {
+  const text = value.toString(8).padStart(size - 1, "0");
+  if (text.length > size - 1) {
+    throw new BundleFormatError(`value ${value} does not fit a ${size}-byte octal field`);
+  }
+  block.write(`${text}\0`, offset, "ascii");
+}
+__name(writeOctal, "writeOctal");
+function readOctal(block, offset, size) {
+  const raw = Buffer.from(block.subarray(offset, offset + size)).toString("ascii").replace(/\0.*$/s, "").trim();
+  if (raw === "") return 0;
+  if (!/^[0-7]+$/.test(raw)) {
+    throw new BundleFormatError(`"${raw}" is not an octal header field`);
+  }
+  return parseInt(raw, 8);
+}
+__name(readOctal, "readOctal");
+function checksum(header) {
+  let sum = 0;
+  for (let i = 0; i < BLOCK; i++) {
+    sum += i >= 148 && i < 156 ? 32 : header[i];
+  }
+  return sum;
+}
+__name(checksum, "checksum");
+function buildHeader(entry) {
+  const { name, prefix } = splitUstarPath(entry.path);
+  const header = Buffer.alloc(BLOCK);
+  writeString(header, name, 0, NAME_FIELD);
+  writeOctal(header, entry.executable ? EXEC_MODE : FILE_MODE, 100, 8);
+  writeOctal(header, 0, 108, 8);
+  writeOctal(header, 0, 116, 8);
+  writeOctal(header, entry.content.byteLength, 124, 12);
+  writeOctal(header, 0, 136, 12);
+  header.fill(32, 148, 156);
+  header.write("0", 156, "ascii");
+  header.write("ustar\0", 257, "ascii");
+  header.write("00", 263, "ascii");
+  writeString(header, prefix, 345, PREFIX_FIELD);
+  header.write(`${checksum(header).toString(8).padStart(6, "0")}\0 `, 148, "ascii");
+  return header;
+}
+__name(buildHeader, "buildHeader");
+function writeTar(entries) {
+  const seen = /* @__PURE__ */ new Set();
+  const sorted = [...entries].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+  const blocks = [];
+  for (const entry of sorted) {
+    assertSafeBundlePath(entry.path);
+    if (seen.has(entry.path)) {
+      throw new BundleFormatError(`"${entry.path}" appears twice`, { path: entry.path });
+    }
+    seen.add(entry.path);
+    blocks.push(buildHeader(entry));
+    const padded = Math.ceil(entry.content.byteLength / BLOCK) * BLOCK;
+    const body = Buffer.alloc(padded);
+    Buffer.from(entry.content).copy(body);
+    blocks.push(body);
+  }
+  blocks.push(Buffer.alloc(BLOCK * 2));
+  return Buffer.concat(blocks);
+}
+__name(writeTar, "writeTar");
+function isZeroBlock(block) {
+  return block.every((byte) => byte === 0);
+}
+__name(isZeroBlock, "isZeroBlock");
+function readTar(data) {
+  const entries = [];
+  let offset = 0;
+  while (offset + BLOCK <= data.byteLength) {
+    const header = data.subarray(offset, offset + BLOCK);
+    if (isZeroBlock(header)) break;
+    const magic = Buffer.from(header.subarray(257, 262)).toString("ascii");
+    if (magic !== "ustar") {
+      throw new BundleFormatError("a header without the ustar magic", { offset });
+    }
+    const stored = readOctal(header, 148, 8);
+    if (stored !== checksum(header)) {
+      throw new BundleFormatError("a header whose checksum does not match", { offset });
+    }
+    const typeflag = String.fromCharCode(header[156]);
+    if (typeflag !== "0" && typeflag !== "\0") {
+      throw new BundleFormatError(
+        `a member of type "${typeflag}" \u2014 a bundle carries plain files only`,
+        { offset, typeflag }
+      );
+    }
+    const name = Buffer.from(header.subarray(0, NAME_FIELD)).toString("utf8").replace(/\0.*$/s, "");
+    const prefix = Buffer.from(header.subarray(345, 345 + PREFIX_FIELD)).toString("utf8").replace(/\0.*$/s, "");
+    const path = prefix === "" ? name : `${prefix}/${name}`;
+    assertSafeBundlePath(path);
+    const size = readOctal(header, 124, 12);
+    const start = offset + BLOCK;
+    if (start + size > data.byteLength) {
+      throw new BundleFormatError(`"${path}" is truncated`, { path });
+    }
+    const mode = readOctal(header, 100, 8);
+    entries.push({
+      path,
+      // Copied, not a view: a caller that keeps one small file must not
+      // pin the whole uploaded archive in memory.
+      content: Buffer.from(data.subarray(start, start + size)),
+      ...(mode & 73) !== 0 ? { executable: true } : {}
+    });
+    offset = start + Math.ceil(size / BLOCK) * BLOCK;
+  }
+  return entries;
+}
+__name(readTar, "readTar");
+
+// src/bundle/bundle-archive.ts
+var BUNDLE_ID_CHARS = 16;
+function byPath(a, b) {
+  return a.path < b.path ? -1 : a.path > b.path ? 1 : 0;
+}
+__name(byPath, "byPath");
+function computeTreeSha256(files) {
+  const tree = createHash("sha256");
+  for (const file of [...files].sort(byPath)) {
+    const content = createHash("sha256").update(file.content).digest("hex");
+    tree.update(`${file.path}\0${file.executable ? "1" : "0"}\0${content}
+`);
+  }
+  return tree.digest("hex");
+}
+__name(computeTreeSha256, "computeTreeSha256");
+function computeBundleId(files) {
+  return computeTreeSha256(files).slice(0, BUNDLE_ID_CHARS);
+}
+__name(computeBundleId, "computeBundleId");
+function packBundle(files, provenance) {
+  if (files.length === 0) {
+    throw new BundleFormatError("there is nothing to pack");
+  }
+  if (files.some((file) => file.path === BUNDLE_MANIFEST_FILE)) {
+    throw new BundleFormatError(
+      `${BUNDLE_MANIFEST_FILE} is the manifest's own name and cannot be a suite file`
+    );
+  }
+  const sha256 = computeTreeSha256(files);
+  const manifest = {
+    schemaVersion: BUNDLE_SCHEMA_VERSION,
+    bundleId: sha256.slice(0, BUNDLE_ID_CHARS),
+    sha256,
+    createdAt: provenance.createdAt,
+    webVersion: provenance.webVersion,
+    fileCount: files.length,
+    byteSize: files.reduce((total, file) => total + file.content.byteLength, 0),
+    ...provenance.author !== void 0 ? { author: provenance.author } : {},
+    ...provenance.git !== void 0 ? { git: provenance.git } : {},
+    ...provenance.declaredVariables && provenance.declaredVariables.length > 0 ? { declaredVariables: [...provenance.declaredVariables] } : {}
+  };
+  const archive = writeTar([
+    ...files,
+    {
+      path: BUNDLE_MANIFEST_FILE,
+      content: Buffer.from(`${JSON.stringify(manifest, null, 2)}
+`, "utf8")
+    }
+  ]);
+  return {
+    bundleId: manifest.bundleId,
+    manifest,
+    // Level 9: a bundle is written once and uploaded once, and the box's
+    // size limit is the thing this is competing against.
+    archive: gzipSync(archive, { level: 9 })
+  };
+}
+__name(packBundle, "packBundle");
+function unpackBundle(archive, options = {}) {
+  const tar = gunzip(archive, options.maxBytes);
+  const entries = readTar(tar);
+  const manifestEntry = entries.find((entry) => entry.path === BUNDLE_MANIFEST_FILE);
+  if (!manifestEntry) {
+    throw new BundleFormatError(`it has no ${BUNDLE_MANIFEST_FILE}`);
+  }
+  let parsedJson;
+  try {
+    parsedJson = JSON.parse(Buffer.from(manifestEntry.content).toString("utf8"));
+  } catch {
+    throw new BundleFormatError(`${BUNDLE_MANIFEST_FILE} is not JSON`);
+  }
+  const manifest = parseBundleManifest(parsedJson);
+  if (!manifest) {
+    throw new BundleFormatError(
+      `${BUNDLE_MANIFEST_FILE} is not a manifest this version understands (schema ${BUNDLE_SCHEMA_VERSION})`
+    );
+  }
+  const files = entries.filter((entry) => entry.path !== BUNDLE_MANIFEST_FILE);
+  const computed = computeTreeSha256(files);
+  if (manifest.sha256 !== void 0 && computed !== manifest.sha256) {
+    throw new BundleIdMismatchError(manifest.sha256, computed);
+  }
+  if (computed.slice(0, manifest.bundleId.length) !== manifest.bundleId) {
+    throw new BundleIdMismatchError(manifest.bundleId, computed);
+  }
+  return { manifest, files };
+}
+__name(unpackBundle, "unpackBundle");
+function gunzip(archive, maxBytes) {
+  if (archive.byteLength < 2 || archive[0] !== 31 || archive[1] !== 139) {
+    throw new BundleFormatError("it is not gzip data");
+  }
+  try {
+    return gunzipSync(archive, maxBytes !== void 0 ? { maxOutputLength: maxBytes } : {});
+  } catch (e) {
+    if (maxBytes !== void 0 && typeof e.code === "string" && e.code === "ERR_BUFFER_TOO_LARGE") {
+      throw new BundleTooLargeError(maxBytes);
+    }
+    throw new BundleFormatError(
+      `gzip could not be read (${e instanceof Error ? e.message : String(e)})`
+    );
+  }
+}
+__name(gunzip, "gunzip");
 export {
+  BundleFormatError,
+  BundleIdMismatchError,
+  BundlePathError,
+  BundleTooLargeError,
+  FsRunQueue,
   JsonlRunArtifactWriter,
+  QueueTicketLostError,
+  QueueUnavailableError,
+  QueueWaitAbortedError,
   UnotestError,
   appendUniqueLines,
   applyEnvLayers,
+  assertSafeBundlePath,
   buildRuntimeInspection,
+  computeBundleId,
+  computeTreeSha256,
   createRunArtifactWriter,
   createRuntimeStateWriter,
   currentLocation,
   extractCallStack,
+  globalPoolFromEnv,
+  isRecord,
+  leaseEnv,
   levenshteinDistance,
+  packBundle,
   parseE2EFlags,
   readDebuggerBreakpoints,
   readEnvFile,
   readEnvLayers,
+  readTar,
   startDebugCommandsWatcher,
   startRunHeartbeat,
   suggestClosest,
   toProtocolRuntimeState,
+  unpackBundle,
   writeRunManifest,
-  writeRunSources
+  writeRunSources,
+  writeTar
 };
 //# sourceMappingURL=index.js.map