@hoardodile/host 0.0.0

package/dist/hoard/index.js

@@ -0,0 +1,1939 @@
+import { randomUUID, createHash } from 'crypto';
+import { existsSync, createWriteStream, readdirSync, readFileSync, mkdirSync, writeFileSync, rmSync, cpSync, createReadStream } from 'fs';
+import { writeFile, mkdir, rm, readdir, rename, chmod, lstat, stat, readFile } from 'fs/promises';
+import { tmpdir } from 'os';
+import { resolve, join, sep, dirname, normalize, isAbsolute, extname, basename } from 'path';
+import { Readable, Transform } from 'stream';
+import { pipeline } from 'stream/promises';
+import yauzl from 'yauzl';
+import { spawn } from 'child_process';
+import { createRequire } from 'module';
+import { buffer } from 'stream/consumers';
+import 'zlib';
+import yazl from 'yazl';
+import { pluginAssetError } from '@hoardodile/sdk-types';
+
+// src/archive/extract.ts
+
+// src/errors.ts
+var DomainError = class extends Error {
+  code;
+  kind;
+  details;
+  constructor(code, kind, message, details) {
+    super(message);
+    this.name = "DomainError";
+    this.code = code;
+    this.kind = kind;
+    if (details !== void 0) this.details = details;
+  }
+};
+function invalid(kind, message, details) {
+  return new DomainError("VALIDATION", kind, message, details);
+}
+function conflict(kind, message, details) {
+  return new DomainError("CONFLICT", kind, message, details);
+}
+function notFound(kind, message, details) {
+  return new DomainError("NOT_FOUND", kind, message, details);
+}
+
+// src/archive/format.ts
+var SNIFF_WINDOW_BYTES = 4100;
+function hasMagic(head, magic) {
+  if (head.byteLength < magic.length) return false;
+  for (let i = 0; i < magic.length; i++) {
+    if (head[i] !== magic[i]) return false;
+  }
+  return true;
+}
+function sniffContainerFormat(head) {
+  if (hasMagic(head, [80, 75, 3, 4])) return "zip";
+  if (hasMagic(head, [80, 75, 5, 6])) return "zip";
+  if (head.byteLength >= 262) {
+    const magic = String.fromCharCode(
+      head[257],
+      head[258],
+      head[259],
+      head[260],
+      head[261]
+    );
+    if (magic === "ustar") return "tar";
+  }
+  if (hasMagic(head, [55, 122, 188, 175, 39, 28])) return "7z";
+  if (hasMagic(head, [82, 97, 114, 33, 26, 7])) return "rar";
+  if (hasMagic(head, [253, 55, 122, 88, 90, 0])) return "xz";
+  if (hasMagic(head, [31, 139, 8])) return "gzip";
+  return void 0;
+}
+
+// src/archive/name-decode.ts
+var CP437 = String.fromCharCode(
+  0,
+  9786,
+  9787,
+  9829,
+  9830,
+  9827,
+  9824,
+  8226,
+  9688,
+  9675,
+  9689,
+  9794,
+  9792,
+  9834,
+  9835,
+  9788,
+  9658,
+  9668,
+  8597,
+  8252,
+  182,
+  167,
+  9644,
+  8616,
+  8593,
+  8595,
+  8594,
+  8592,
+  8735,
+  8596,
+  9650,
+  9660,
+  32,
+  33,
+  34,
+  35,
+  36,
+  37,
+  38,
+  39,
+  40,
+  41,
+  42,
+  43,
+  44,
+  45,
+  46,
+  47,
+  48,
+  49,
+  50,
+  51,
+  52,
+  53,
+  54,
+  55,
+  56,
+  57,
+  58,
+  59,
+  60,
+  61,
+  62,
+  63,
+  64,
+  65,
+  66,
+  67,
+  68,
+  69,
+  70,
+  71,
+  72,
+  73,
+  74,
+  75,
+  76,
+  77,
+  78,
+  79,
+  80,
+  81,
+  82,
+  83,
+  84,
+  85,
+  86,
+  87,
+  88,
+  89,
+  90,
+  91,
+  92,
+  93,
+  94,
+  95,
+  96,
+  97,
+  98,
+  99,
+  100,
+  101,
+  102,
+  103,
+  104,
+  105,
+  106,
+  107,
+  108,
+  109,
+  110,
+  111,
+  112,
+  113,
+  114,
+  115,
+  116,
+  117,
+  118,
+  119,
+  120,
+  121,
+  122,
+  123,
+  124,
+  125,
+  126,
+  8962,
+  199,
+  252,
+  233,
+  226,
+  228,
+  224,
+  229,
+  231,
+  234,
+  235,
+  232,
+  239,
+  238,
+  236,
+  196,
+  197,
+  201,
+  230,
+  198,
+  244,
+  246,
+  242,
+  251,
+  249,
+  255,
+  214,
+  220,
+  162,
+  163,
+  165,
+  8359,
+  402,
+  225,
+  237,
+  243,
+  250,
+  241,
+  209,
+  170,
+  186,
+  191,
+  8976,
+  172,
+  189,
+  188,
+  161,
+  171,
+  187,
+  9617,
+  9618,
+  9619,
+  9474,
+  9508,
+  9569,
+  9570,
+  9558,
+  9557,
+  9571,
+  9553,
+  9559,
+  9565,
+  9564,
+  9563,
+  9488,
+  9492,
+  9524,
+  9516,
+  9500,
+  9472,
+  9532,
+  9566,
+  9567,
+  9562,
+  9556,
+  9577,
+  9574,
+  9568,
+  9552,
+  9580,
+  9575,
+  9576,
+  9572,
+  9573,
+  9561,
+  9560,
+  9554,
+  9555,
+  9579,
+  9578,
+  9496,
+  9484,
+  9608,
+  9604,
+  9612,
+  9616,
+  9600,
+  945,
+  223,
+  915,
+  960,
+  931,
+  963,
+  181,
+  964,
+  934,
+  920,
+  937,
+  948,
+  8734,
+  966,
+  949,
+  8745,
+  8801,
+  177,
+  8805,
+  8804,
+  8992,
+  8993,
+  247,
+  8776,
+  176,
+  8729,
+  183,
+  8730,
+  8319,
+  178,
+  9632,
+  160
+);
+function decodeLegacyZipName(bytes) {
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    let out = "";
+    for (const b of bytes) out += CP437[b] ?? "\uFFFD";
+    return out;
+  }
+}
+var RANGE_READ_CHUNK_BYTES = 256 * 1024;
+async function createFileArchiveSource(zipPath) {
+  const info = await stat(zipPath);
+  return {
+    size: info.size,
+    readRange: (start, end) => readFileRange(zipPath, start, end)
+  };
+}
+async function listZipEntriesFromSource(source, opts = {}) {
+  const zipfile = await openZipFromSource(source);
+  const records = [];
+  try {
+    for await (const entry of zipfile.eachEntry()) {
+      if (entry.fileName.endsWith("/")) continue;
+      const dataOffset = opts.dataOffsets === false ? 0 : await resolveDataOffsetFromSource(
+        source,
+        entry.relativeOffsetOfLocalHeader
+      );
+      records.push({
+        name: entry.fileName,
+        compressionMethod: entry.compressionMethod,
+        encrypted: entry.isEncrypted(),
+        uncompressedSize: entry.uncompressedSize,
+        compressedSize: entry.compressedSize,
+        crc32: entry.crc32,
+        localHeaderOffset: entry.relativeOffsetOfLocalHeader,
+        dataOffset,
+        dataSize: entry.compressedSize,
+        modifiedAt: entry.getLastModDate().getTime()
+      });
+    }
+  } catch (err) {
+    throw invalid(
+      "resource.archive_open_failed",
+      err instanceof Error ? err.message : "could not read archive entries",
+      { size: source.size }
+    );
+  } finally {
+    zipfile.close();
+  }
+  return records;
+}
+async function listZipEntries(zipPath, opts = {}) {
+  return listZipEntriesFromSource(await createFileArchiveSource(zipPath), opts);
+}
+function streamRange(source, start, end) {
+  return Readable.from(
+    (async function* rangeChunks() {
+      let pos = start;
+      while (pos <= end) {
+        const to = Math.min(end, pos + RANGE_READ_CHUNK_BYTES - 1);
+        const chunk = await source.readRange(pos, to);
+        if (chunk.length === 0) return;
+        yield chunk;
+        pos += chunk.length;
+      }
+    })()
+  );
+}
+function readZipRange(zipPath, start, end) {
+  return createReadStream(zipPath, { start, end });
+}
+async function readFileRange(path, start, end) {
+  if (!Number.isFinite(start) || !Number.isFinite(end) || !Number.isInteger(start) || !Number.isInteger(end) || start < 0 || end < start) {
+    throw invalid(
+      "resource.file_read_failed",
+      `invalid byte range ${start}..${end}`,
+      { path, start, end }
+    );
+  }
+  const length = end - start + 1;
+  if (length <= 0) return Buffer.alloc(0);
+  return buffer(readZipRange(path, start, end));
+}
+function openZipFromSource(source) {
+  const reader = new RangeReader(source);
+  return yauzl.fromRandomAccessReaderPromise(reader, source.size, {
+    lazyEntries: true,
+    decodeStrings: true
+  }).catch((err) => {
+    reader.close(() => {
+    });
+    throw invalid(
+      "resource.archive_open_failed",
+      err instanceof Error ? err.message : "could not open archive",
+      { size: source.size }
+    );
+  });
+}
+var RangeReader = class extends yauzl.RandomAccessReader {
+  // Explicit field + assignment: this package ships source to Node's
+  // type-stripping loader (no build step), which rejects parameter
+  // properties.
+  source;
+  constructor(source) {
+    super();
+    this.source = source;
+  }
+  _readStreamForRange(start, end) {
+    return streamRange(this.source, start, end - 1);
+  }
+  // yauzl's runtime contract calls `_close` even though the shipped
+  // types only expose the public `close` — no `override` here.
+  _close(callback) {
+    callback(null);
+  }
+};
+async function resolveDataOffsetFromSource(source, localHeaderOffset) {
+  if (localHeaderOffset + 30 > source.size) {
+    throw invalid(
+      "resource.archive_open_failed",
+      `truncated local file header at offset ${localHeaderOffset}`,
+      { localHeaderOffset }
+    );
+  }
+  const head = await source.readRange(localHeaderOffset, localHeaderOffset + 29);
+  if (head.length < 30) {
+    throw invalid(
+      "resource.archive_open_failed",
+      `truncated local file header at offset ${localHeaderOffset}`,
+      { localHeaderOffset }
+    );
+  }
+  const sig = head.readUInt32LE(0);
+  if (sig !== 67324752) {
+    throw invalid(
+      "resource.archive_open_failed",
+      `bad local file header signature at offset ${localHeaderOffset}`,
+      { localHeaderOffset, sig: sig.toString(16) }
+    );
+  }
+  const nameLen = head.readUInt16LE(26);
+  const extraLen = head.readUInt16LE(28);
+  return localHeaderOffset + 30 + nameLen + extraLen;
+}
+function normalizeZipError(err) {
+  if (!(err instanceof Error)) return err;
+  const message = err.message;
+  if (message.startsWith("invalid relative path: ") || message.startsWith("absolute path: ") || message.startsWith("invalid characters in fileName: ")) {
+    return invalid("resource.archive_invalid_entry", message, {});
+  }
+  return err;
+}
+
+// src/archive/7z.ts
+var requireCjs = createRequire(import.meta.url);
+var SEVEN_ZIP_PATH_ENV = "7Z_BIN_PATH";
+function resolveSevenZipPath() {
+  const fromEnv = process.env[SEVEN_ZIP_PATH_ENV];
+  if (fromEnv !== void 0 && fromEnv.length > 0) return fromEnv;
+  try {
+    const mod = requireCjs("@hoardodile/7z-bin");
+    if (typeof mod === "string" && mod.length > 0) return mod;
+    return void 0;
+  } catch {
+    return void 0;
+  }
+}
+function sevenZipUnavailable() {
+  return invalid(
+    "resource.archive_open_failed",
+    "7-Zip is not installed \u2014 install @hoardodile/7z-bin or set 7Z_BIN_PATH to enable archive extraction",
+    {}
+  );
+}
+function run7z(bin, args, timeoutMs) {
+  return new Promise((resolveDone, rejectDone) => {
+    const child = spawn(bin, [...args], {
+      stdio: ["ignore", "pipe", "pipe"],
+      windowsHide: true
+    });
+    const stdout = [];
+    const stderr = [];
+    let settled = false;
+    child.stdout.on("data", (chunk) => stdout.push(chunk));
+    child.stderr.on("data", (chunk) => stderr.push(chunk));
+    const fail = (err) => {
+      if (settled) return;
+      settled = true;
+      rejectDone(err);
+    };
+    const timer = setTimeout(() => {
+      child.kill();
+      fail(
+        invalid(
+          "resource.archive_open_failed",
+          `7-Zip timed out after ${timeoutMs}ms`,
+          { timeoutMs }
+        )
+      );
+    }, timeoutMs);
+    timer.unref();
+    child.on("error", (err) => {
+      fail(
+        invalid(
+          "resource.archive_open_failed",
+          `could not start 7-Zip: ${err.message}`,
+          {}
+        )
+      );
+    });
+    child.on("close", (code, signal) => {
+      clearTimeout(timer);
+      if (settled) return;
+      if (code === 0) {
+        settled = true;
+        resolveDone({ stdout: Buffer.concat(stdout) });
+        return;
+      }
+      const detail = signal !== null ? `killed by ${signal}` : `exit ${code ?? "?"}`;
+      const tail = Buffer.concat(stderr).toString("utf8").trim().split("\n").at(-1);
+      fail(
+        invalid(
+          "resource.archive_open_failed",
+          `7-Zip ${detail}${tail !== void 0 && tail.length > 0 ? `: ${tail}` : ""}`,
+          { code }
+        )
+      );
+    });
+  });
+}
+function isEncryptedField(value) {
+  return value === "+";
+}
+function parseSltListing(stdout, legacyNames) {
+  const entries = [];
+  let name;
+  let sizeBytes = 0;
+  let folder = false;
+  let encrypted = false;
+  for (const line of stdout.toString("latin1").split(/\r?\n/)) {
+    if (line.length === 0) {
+      if (name !== void 0) {
+        entries.push({ name, sizeBytes, folder, encrypted });
+        name = void 0;
+      }
+      continue;
+    }
+    const sep3 = line.indexOf(" = ");
+    if (sep3 < 0) continue;
+    const key = line.slice(0, sep3);
+    if (key === "Path") {
+      const raw = Buffer.from(line.slice(sep3 + 3), "latin1");
+      const decoded = legacyNames ? decodeLegacyZipName(raw) : raw.toString("utf8");
+      name = decoded.replace(/\\/g, "/");
+      continue;
+    }
+    const value = line.slice(sep3 + 3);
+    switch (key) {
+      case "Size":
+        sizeBytes = Number.parseInt(value, 10) || 0;
+        break;
+      case "Attributes":
+        folder = value.includes("D");
+        break;
+      case "Encrypted":
+        encrypted = isEncryptedField(value);
+        break;
+    }
+  }
+  if (name !== void 0) {
+    entries.push({ name, sizeBytes, folder, encrypted });
+  }
+  return entries;
+}
+async function isZipArchive(archivePath) {
+  const head = await readFileRange(
+    archivePath,
+    0,
+    SNIFF_WINDOW_BYTES - 1
+  ).catch(() => void 0);
+  if (head === void 0 || head.length === 0) return false;
+  return sniffContainerFormat(head) === "zip";
+}
+async function listSevenZipEntries(archivePath, opts = {}) {
+  const bin = resolveSevenZipPath();
+  if (bin === void 0) throw sevenZipUnavailable();
+  const args = ["l", "-slt", "-ba", "-sccUTF-8"];
+  const legacyNames = await isZipArchive(archivePath);
+  args.push(archivePath);
+  const { stdout } = await run7z(bin, args, opts.timeoutMs ?? 12e4);
+  return parseSltListing(stdout, legacyNames);
+}
+async function extractSevenZipInto(archivePath, destDir, opts = {}) {
+  const bin = resolveSevenZipPath();
+  if (bin === void 0) throw sevenZipUnavailable();
+  const args = ["x", archivePath, `-o${destDir}`, "-y", "-bd"];
+  await run7z(bin, args, opts.timeoutMs ?? 10 * 6e4);
+}
+
+// src/archive/listing.ts
+async function listArchiveEntries(archivePath) {
+  const head = await readFileRange(archivePath, 0, SNIFF_WINDOW_BYTES - 1);
+  const format = sniffContainerFormat(head);
+  if (format === "zip") {
+    const records = await listZipEntries(archivePath);
+    return records.map((r) => ({ name: r.name, sizeBytes: r.uncompressedSize }));
+  }
+  if (format === void 0) {
+    throw invalid(
+      "resource.archive_open_failed",
+      "not a supported archive (zip/tar/7z/rar/xz/gzip)",
+      {}
+    );
+  }
+  if (resolveSevenZipPath() === void 0) {
+    throw invalid(
+      "resource.archive_open_failed",
+      "7-Zip is not installed \u2014 cannot list tar/7z/rar/xz/gzip archives",
+      {}
+    );
+  }
+  const entries = await listSevenZipEntries(archivePath);
+  return entries.filter((e) => !e.folder).map((e) => ({ name: e.name, sizeBytes: e.sizeBytes }));
+}
+function listingBudgetExceeded(entries, opts) {
+  if (opts.maxEntries !== void 0 && entries.length > opts.maxEntries) {
+    return {
+      kind: "entries",
+      count: entries.length,
+      maxEntries: opts.maxEntries
+    };
+  }
+  let totalBytes = 0;
+  for (const entry of entries) {
+    totalBytes += entry.sizeBytes;
+    if (totalBytes > opts.maxBytes) {
+      return {
+        kind: "bytes",
+        totalBytes,
+        maxBytes: opts.maxBytes
+      };
+    }
+  }
+  return void 0;
+}
+async function validateArchiveBudget(archivePath, maxBytes) {
+  const entries = await listArchiveEntries(archivePath);
+  const exceeded = listingBudgetExceeded(entries, { maxBytes });
+  if (exceeded?.kind === "bytes") {
+    throw invalid(
+      "resource.archive_too_large",
+      `archive uncompressed size exceeds ${maxBytes} bytes`,
+      { maxBytes }
+    );
+  }
+}
+
+// src/archive/extract.ts
+async function extractArchiveInto(source, destDir, opts) {
+  const buffer2 = await readToBuffer(source);
+  const format = sniffContainerFormat(buffer2.subarray(0, SNIFF_WINDOW_BYTES));
+  if (format === void 0) {
+    throw invalid(
+      "resource.archive_open_failed",
+      "not a supported archive (zip/tar/7z/rar/xz/gzip)",
+      {}
+    );
+  }
+  if (format === "zip" && resolveSevenZipPath() === void 0) {
+    return extractZipBuffer(buffer2, destDir, opts);
+  }
+  return extractViaSevenZip(buffer2, destDir, opts, format);
+}
+async function extractZipBuffer(buffer2, destDir, opts) {
+  const { maxBytes, maxEntries, onProgress } = opts;
+  const zipfile = await openZipFromBuffer(buffer2);
+  if (maxEntries !== void 0 && zipfile.entryCount > maxEntries) {
+    zipfile.close();
+    throw invalid(
+      "resource.archive_too_large",
+      `archive has ${zipfile.entryCount} entries, exceeding the limit of ${maxEntries}`,
+      { maxEntries }
+    );
+  }
+  const root = resolve(destDir);
+  const budget = { remaining: maxBytes, max: maxBytes };
+  const totalEntries = zipfile.entryCount;
+  const counters = { entriesDone: 0, bytesDone: 0, totalBytes: 0 };
+  if (onProgress !== void 0) {
+    onProgress({ phase: "started", totalEntries, totalBytes: 0 });
+  }
+  try {
+    await new Promise((resolveDone, rejectDone) => {
+      zipfile.on("error", (err) => rejectDone(normalizeZipError(err)));
+      zipfile.on("end", resolveDone);
+      zipfile.on("entry", (entry) => {
+        handleExtractEntry(zipfile, entry, root, budget).then(() => {
+          counters.entriesDone += 1;
+          counters.bytesDone += entry.uncompressedSize;
+          counters.totalBytes += entry.uncompressedSize;
+          if (onProgress !== void 0) {
+            onProgress({
+              phase: "entry",
+              entriesDone: counters.entriesDone,
+              totalEntries,
+              bytesDone: counters.bytesDone,
+              totalBytes: counters.totalBytes
+            });
+          }
+          zipfile.readEntry();
+        }, rejectDone);
+      });
+      zipfile.readEntry();
+    });
+  } finally {
+    zipfile.close();
+  }
+  if (onProgress !== void 0) {
+    onProgress({ phase: "done" });
+  }
+}
+async function extractViaSevenZip(buffer2, destDir, opts, format) {
+  const { maxBytes, maxEntries, onProgress } = opts;
+  const tempPath = join(
+    tmpdir(),
+    `hoardodile-7z-${process.pid}-${randomUUID().slice(0, 8)}`
+  );
+  await writeFile(tempPath, buffer2);
+  try {
+    const entries = await listSevenZipEntries(tempPath);
+    const files = entries.filter((e) => !e.folder);
+    const exceeded = listingBudgetExceeded(files, { maxBytes, maxEntries });
+    if (exceeded?.kind === "bytes") {
+      throw invalid(
+        "resource.archive_too_large",
+        `archive extracts to more than ${maxBytes} bytes`,
+        { maxExtractedBytes: maxBytes }
+      );
+    }
+    if (exceeded?.kind === "entries") {
+      throw invalid(
+        "resource.archive_too_large",
+        `archive has ${files.length} entries, exceeding the limit of ${maxEntries}`,
+        { maxEntries }
+      );
+    }
+    if (entries.some((e) => e.encrypted)) {
+      throw invalid(
+        "resource.archive_invalid_entry",
+        "archive is password-protected \u2014 encrypted archives are not supported",
+        {}
+      );
+    }
+    for (const entry of files) assertSafeEntryPath(entry.name);
+    const root = resolve(destDir);
+    await mkdir(root, { recursive: true });
+    const totalBytes = files.reduce((acc, e) => acc + e.sizeBytes, 0);
+    onProgress?.({ phase: "started", totalEntries: files.length, totalBytes });
+    await extractSevenZipInto(tempPath, root);
+    const decoded = format === "zip" ? await decodeZipNames(
+      tempPath,
+      files.map((e) => ({ name: e.name, sizeBytes: e.sizeBytes }))
+    ) : void 0;
+    await normalizeExtractedTree(root, {
+      legacyZipNames: format === "zip",
+      expectedNames: decoded?.paths
+    });
+    await assertExtractedTree(root, maxBytes);
+    onProgress?.({ phase: "done" });
+  } finally {
+    await rm(tempPath, { force: true }).catch(() => {
+    });
+  }
+}
+async function assertExtractedTree(root, maxBytes) {
+  let total = 0;
+  async function walk(dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const full = join(dir, entry.name);
+      const info = await lstat(full);
+      if (info.isSymbolicLink()) {
+        throw invalid(
+          "resource.archive_invalid_entry",
+          `extracted entry is a symlink: ${entry.name}`,
+          { name: entry.name }
+        );
+      }
+      if (info.isDirectory()) {
+        await walk(full);
+        continue;
+      }
+      if (!info.isFile()) {
+        throw invalid(
+          "resource.archive_invalid_entry",
+          `extracted entry is not a regular file: ${entry.name}`,
+          { name: entry.name }
+        );
+      }
+      total += info.size;
+      if (total > maxBytes) {
+        throw invalid(
+          "resource.archive_too_large",
+          `archive extracts to more than ${maxBytes} bytes`,
+          { maxExtractedBytes: maxBytes }
+        );
+      }
+    }
+  }
+  await walk(root);
+}
+async function normalizeExtractedTree(root, opts) {
+  if (opts.legacyZipNames) {
+    const expected = opts.expectedNames ? new Set(opts.expectedNames.map((n) => n.replace(/\/+$/, ""))) : void 0;
+    await renameLegacyZipNames(Buffer.from(root), root, root, expected);
+  }
+  await makeReadable(root);
+}
+async function decodeZipNames(zipPath, fallback) {
+  try {
+    const records = await listZipEntries(zipPath, { dataOffsets: false });
+    const files = records.map((e) => ({
+      name: e.name,
+      sizeBytes: e.uncompressedSize
+    }));
+    const paths = /* @__PURE__ */ new Set();
+    for (const file of files) {
+      const segments = file.name.split("/");
+      for (let i = 1; i < segments.length; i++) {
+        paths.add(segments.slice(0, i).join("/"));
+      }
+      paths.add(file.name);
+    }
+    return { files, paths: [...paths] };
+  } catch {
+    return { files: fallback, paths: fallback.map((e) => e.name) };
+  }
+}
+async function renameLegacyZipNames(rawRoot, decodedRoot, root, expected) {
+  const entries = await readdir(rawRoot, {
+    withFileTypes: true,
+    encoding: "buffer"
+  });
+  for (const entry of entries) {
+    const childRaw = Buffer.concat([rawRoot, Buffer.from(sep), entry.name]);
+    const decoded = decodeLegacyZipName(entry.name);
+    const target = legacyRenameTarget(
+      entry.name,
+      decoded,
+      decodedRoot,
+      root,
+      expected
+    );
+    if (entry.isDirectory()) {
+      if (target !== void 0 && !existsSync(target)) {
+        await rename(childRaw, target);
+        await renameLegacyZipNames(Buffer.from(target), target, root, expected);
+        continue;
+      }
+      await renameLegacyZipNames(
+        childRaw,
+        target ?? `${decodedRoot}/${decoded}`,
+        root,
+        expected
+      );
+      continue;
+    }
+    if (target === void 0 || existsSync(target)) continue;
+    await rename(childRaw, target);
+  }
+}
+function legacyRenameTarget(rawName, decoded, decodedRoot, root, expected) {
+  const utf8Name = rawName.toString("utf8");
+  if (decoded !== utf8Name) {
+    return `${decodedRoot}/${decoded}`;
+  }
+  const raw = recoverRawLegacyName(rawName);
+  if (raw === void 0) return void 0;
+  const recovered = decodeLegacyZipName(raw);
+  if (recovered === utf8Name || expected === void 0) return void 0;
+  const rel = decodedRoot === root ? recovered : `${decodedRoot.slice(root.length + 1)}/${recovered}`;
+  return expected.has(rel) ? `${decodedRoot}/${recovered}` : void 0;
+}
+function recoverRawLegacyName(name) {
+  const escaped = unescapePercentEscapes(name);
+  if (escaped !== void 0) return escaped;
+  const text = name.toString("utf8");
+  const out = [];
+  for (const ch of text) {
+    const code = ch.codePointAt(0) ?? 0;
+    if (code >= 61312 && code <= 61439) {
+      out.push(code - 61184);
+      continue;
+    }
+    if (code > 127) return void 0;
+    out.push(code);
+  }
+  return out.length === text.length ? Buffer.from(out) : void 0;
+}
+function unescapePercentEscapes(name) {
+  const text = name.toString("latin1");
+  if (!text.includes("%")) return void 0;
+  const out = [];
+  let changed = false;
+  for (let i = 0; i < text.length; i++) {
+    const hex = i + 2 < text.length ? text.slice(i + 1, i + 3) : void 0;
+    if (text[i] === "%" && hex !== void 0 && /^[0-9a-fA-F]{2}$/.test(hex)) {
+      out.push(Number.parseInt(hex, 16));
+      changed = true;
+      i += 2;
+      continue;
+    }
+    out.push(text.charCodeAt(i));
+  }
+  return changed ? Buffer.from(out) : void 0;
+}
+async function makeReadable(root) {
+  const entries = await readdir(root, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = join(root, entry.name);
+    if (entry.isDirectory()) {
+      await chmod(full, (await lstat(full)).mode | 448);
+      await makeReadable(full);
+      continue;
+    }
+    if (entry.isFile()) {
+      await chmod(full, (await lstat(full)).mode | 384);
+    }
+  }
+}
+function assertSafeEntryPath(rawName) {
+  if (rawName.length === 0 || /^([a-zA-Z]:)?[\\/]/.test(rawName) || rawName.split("/").includes("..")) {
+    throw invalid(
+      "resource.archive_invalid_entry",
+      `archive entry has an unsafe path: ${rawName}`,
+      { rawName }
+    );
+  }
+}
+async function handleExtractEntry(zipfile, entry, root, budget) {
+  const safe = safeExtractEntryPath(entry.fileName, root);
+  if (entry.fileName.endsWith("/")) {
+    await mkdir(safe, { recursive: true });
+    return;
+  }
+  await mkdir(dirname(safe), { recursive: true });
+  const stream = await openZipEntryStream(zipfile, entry);
+  await pipeline(stream, makeByteBudgetCounter(budget), createWriteStream(safe));
+}
+function safeExtractEntryPath(rawName, root) {
+  if (rawName.length === 0) {
+    throw invalid(
+      "resource.archive_invalid_entry",
+      "archive entry has empty name",
+      { rawName }
+    );
+  }
+  if (/^([a-zA-Z]:)?[\\/]/.test(rawName)) {
+    throw invalid(
+      "resource.archive_invalid_entry",
+      `archive entry has absolute path: ${rawName}`,
+      { rawName }
+    );
+  }
+  const normalised = normalize(rawName).replace(/\\/g, "/");
+  if (normalised.startsWith("../") || normalised === "..") {
+    throw invalid(
+      "resource.archive_invalid_entry",
+      `archive entry escapes destination: ${rawName}`,
+      { rawName }
+    );
+  }
+  const candidate = resolve(root, normalised);
+  if (candidate !== root && !candidate.startsWith(root + sep)) {
+    throw invalid(
+      "resource.archive_invalid_entry",
+      `archive entry escapes destination: ${rawName}`,
+      { rawName }
+    );
+  }
+  return candidate;
+}
+function makeByteBudgetCounter(budget) {
+  return new Transform({
+    transform(chunk, _enc, cb) {
+      const len = Buffer.isBuffer(chunk) ? chunk.length : Buffer.byteLength(chunk);
+      budget.remaining -= len;
+      if (budget.remaining < 0) {
+        cb(
+          invalid(
+            "resource.archive_too_large",
+            `archive extracts to more than ${budget.max} bytes`,
+            { maxExtractedBytes: budget.max }
+          )
+        );
+        return;
+      }
+      cb(void 0, chunk);
+    }
+  });
+}
+async function readToBuffer(source) {
+  const chunks = [];
+  for await (const chunk of source) {
+    chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+  }
+  return Buffer.concat(chunks);
+}
+function openZipFromBuffer(buffer2) {
+  return new Promise((res, rej) => {
+    yauzl.fromBuffer(
+      buffer2,
+      { lazyEntries: true },
+      (err, zip) => {
+        if (err !== null || zip === void 0) {
+          rej(
+            invalid(
+              "resource.archive_open_failed",
+              err?.message ?? "could not open archive",
+              {}
+            )
+          );
+          return;
+        }
+        res(zip);
+      }
+    );
+  });
+}
+function openZipEntryStream(zipfile, entry) {
+  return new Promise((res, rej) => {
+    zipfile.openReadStream(entry, (err, stream) => {
+      if (err !== null && err !== void 0 || stream === void 0) {
+        rej(
+          invalid(
+            "resource.archive_entry_unreadable",
+            err?.message ?? `could not read archive entry: ${entry.fileName}`,
+            { entry: entry.fileName }
+          )
+        );
+        return;
+      }
+      res(stream);
+    });
+  });
+}
+function streamStoredZip(entries) {
+  const zip = new yazl.ZipFile();
+  for (const entry of entries) {
+    if (entry.size === 0) {
+      zip.addBuffer(Buffer.alloc(0), entry.name, { compress: false });
+      continue;
+    }
+    zip.addReadStream(entry.openStream(), entry.name, {
+      compress: false,
+      size: entry.size
+    });
+  }
+  zip.end();
+  return zip.outputStream;
+}
+async function sumDirSizes(root, opts = {}) {
+  let total = 0;
+  const stack = [root];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    if (dir === void 0) continue;
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (entry.isSymbolicLink()) continue;
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(full);
+      } else if (entry.isFile()) {
+        if (opts.excludeDotPrefix === true && entry.name.startsWith(".")) {
+          continue;
+        }
+        try {
+          const info = await stat(full);
+          total += info.size;
+        } catch {
+        }
+      }
+    }
+  }
+  return total;
+}
+var ORDER_MANIFEST_NAME = ".order";
+function orderManifestPath(dataDir) {
+  return join(dataDir, ORDER_MANIFEST_NAME);
+}
+async function writeOrderManifest(dataDir, names) {
+  const dest = orderManifestPath(dataDir);
+  const tmp = `${dest}.writing-${process.pid}-${Date.now()}`;
+  try {
+    await writeFile(tmp, JSON.stringify(names), "utf8");
+    await rename(tmp, dest);
+  } catch (err) {
+    await rm(tmp, { force: true }).catch(() => {
+    });
+    throw err;
+  }
+}
+async function readOrderManifest(dataDir) {
+  let raw;
+  try {
+    raw = await readFile(orderManifestPath(dataDir), "utf8");
+  } catch {
+    return void 0;
+  }
+  return parseOrderManifest(raw);
+}
+function parseOrderManifest(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return void 0;
+  }
+  if (!Array.isArray(parsed) || parsed.length === 0) return void 0;
+  const names = [];
+  for (const entry of parsed) {
+    if (typeof entry !== "string") return void 0;
+    if (!isManifestPathSafe(entry)) return void 0;
+    names.push(entry);
+  }
+  if (names.length === 0) return void 0;
+  return names;
+}
+function orderEntries(manifest, listed) {
+  const available = new Set(listed);
+  const uniqueManifest = /* @__PURE__ */ new Set();
+  for (const name of manifest) {
+    if (uniqueManifest.has(name)) return void 0;
+    uniqueManifest.add(name);
+    if (!available.has(name)) return void 0;
+  }
+  const ordered = manifest.filter((name) => available.has(name));
+  const rest = naturalSort(listed.filter((name) => !uniqueManifest.has(name)));
+  return [...ordered, ...rest];
+}
+function naturalSort(names) {
+  return [...names].sort(
+    (a, b) => a.localeCompare(b, void 0, { sensitivity: "base", numeric: true })
+  );
+}
+function isManifestPathSafe(entry) {
+  if (entry.length === 0 || entry.includes("\0") || entry.includes("\\")) {
+    return false;
+  }
+  const segments = entry.split("/");
+  for (const segment of segments) {
+    if (segment.length === 0 || segment === "." || segment === "..") {
+      return false;
+    }
+  }
+  return true;
+}
+var STATE_FILENAME = "version-state.json";
+function versionsRoot(root) {
+  return resolve(root, "versions");
+}
+function stateFile(root) {
+  return resolve(root, "local", STATE_FILENAME);
+}
+function listVersions(root) {
+  const dir = versionsRoot(root);
+  if (!existsSync(dir)) return [];
+  const names = readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
+  const nums = [];
+  for (const n of names) {
+    if (!/^[1-9][0-9]*$/.test(n)) continue;
+    nums.push(Number.parseInt(n, 10));
+  }
+  nums.sort((a, b) => a - b);
+  return nums;
+}
+function currentVersion(root) {
+  const all = listVersions(root);
+  return all.length === 0 ? 0 : all[all.length - 1] ?? 0;
+}
+function readActiveVersion(root) {
+  const cur = currentVersion(root);
+  const file = stateFile(root);
+  if (!existsSync(file)) return cur;
+  try {
+    const parsed = JSON.parse(
+      readFileSync(file, "utf8")
+    );
+    const active = typeof parsed.active === "number" ? parsed.active : cur;
+    const all = listVersions(root);
+    if (all.includes(active)) return active;
+    return cur;
+  } catch {
+    return cur;
+  }
+}
+function writeActiveVersion(root, version) {
+  const all = listVersions(root);
+  if (!all.includes(version)) {
+    throw notFound("version.not_found", `version ${version} does not exist`, {
+      version
+    });
+  }
+  const file = stateFile(root);
+  mkdirSync(resolve(root, "local"), { recursive: true });
+  const payload = { active: version };
+  writeFileSync(file, JSON.stringify(payload), "utf8");
+}
+function ensureBootstrapVersion(root) {
+  const cur = currentVersion(root);
+  if (cur > 0) return cur;
+  const v1 = resolve(versionsRoot(root), "1");
+  mkdirSync(v1, { recursive: true });
+  return 1;
+}
+function createNextVersion(root, vacuumInto) {
+  const prev = currentVersion(root);
+  if (prev === 0) {
+    throw conflict(
+      "version.bootstrap_required",
+      "no current version to snapshot from"
+    );
+  }
+  const next = prev + 1;
+  const prevDir = resolve(versionsRoot(root), String(prev));
+  const nextDir = resolve(versionsRoot(root), String(next));
+  const dest = resolve(prevDir, "app.sqlite");
+  if (existsSync(dest)) {
+    throw conflict(
+      "version.already_exists",
+      `app.sqlite already exists for version ${next}`,
+      { version: next }
+    );
+  }
+  mkdirSync(nextDir, { recursive: true });
+  try {
+    copyVersionPlugins(prevDir, nextDir);
+    vacuumInto(dest);
+  } catch (err) {
+    rmSync(nextDir, { recursive: true, force: true });
+    throw err;
+  }
+  return { previous: prev, created: next };
+}
+function copyVersionPlugins(prevDir, nextDir) {
+  const src = join(prevDir, "plugins");
+  if (!existsSync(src)) return;
+  const entries = readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name.startsWith(".")) continue;
+    const from = join(src, entry.name);
+    if (!existsSync(join(from, "manifest.json"))) continue;
+    cpSync(from, join(nextDir, "plugins", entry.name), { recursive: true });
+  }
+}
+function versionedDbFile(root, v) {
+  return resolve(versionsRoot(root), String(v), "app.sqlite");
+}
+function versionedPath(root, v) {
+  return resolve(versionsRoot(root), String(v));
+}
+
+// src/hoard/paths.ts
+var WINDOWS_RESERVED = /* @__PURE__ */ new Set([
+  "CON",
+  "PRN",
+  "AUX",
+  "NUL",
+  "COM1",
+  "COM2",
+  "COM3",
+  "COM4",
+  "COM5",
+  "COM6",
+  "COM7",
+  "COM8",
+  "COM9",
+  "LPT1",
+  "LPT2",
+  "LPT3",
+  "LPT4",
+  "LPT5",
+  "LPT6",
+  "LPT7",
+  "LPT8",
+  "LPT9"
+]);
+var RESOURCE_DATA_DIR_NAME = "data";
+var FORBIDDEN_VISIBLE_CHARS = '<>:"|?*';
+function hasControlChar(segment) {
+  for (let i = 0; i < segment.length; i++) {
+    if (segment.charCodeAt(i) < 32) return true;
+  }
+  return false;
+}
+function hasForbiddenVisibleChar(segment) {
+  for (let i = 0; i < segment.length; i++) {
+    const ch = segment[i];
+    if (ch !== void 0 && FORBIDDEN_VISIBLE_CHARS.includes(ch)) return true;
+  }
+  return false;
+}
+function createStoragePaths(opts) {
+  if (!isAbsolute(opts.root)) {
+    throw new Error(`storage root must be an absolute path: ${opts.root}`);
+  }
+  const root = resolve(opts.root);
+  const versionsRootPath = resolve(root, "versions");
+  const localRoot = resolve(root, "local");
+  const diskMax = currentVersion(root);
+  let latestVersion;
+  if (opts.latestVersion !== void 0) {
+    latestVersion = opts.latestVersion;
+  } else {
+    latestVersion = diskMax > 0 ? diskMax : 1;
+  }
+  let activeVersion;
+  if (opts.activeVersion !== void 0) {
+    activeVersion = opts.activeVersion;
+  } else if (opts.latestVersion !== void 0) {
+    activeVersion = latestVersion;
+  } else {
+    activeVersion = diskMax > 0 ? readActiveVersion(root) : latestVersion;
+  }
+  function versionAt(version) {
+    const vSeg = assertSafeSegment(String(version));
+    const vRoot = join5(versionsRootPath, vSeg);
+    return {
+      root: vRoot,
+      version,
+      versionSnapshotDb: () => join5(vRoot, "app.sqlite"),
+      resource: (id) => join5(vRoot, "resources", assertSafeSegment(id)),
+      resourceData: (id) => join5(vRoot, "resources", assertSafeSegment(id), RESOURCE_DATA_DIR_NAME),
+      resources: () => join5(vRoot, "resources"),
+      characters: () => join5(vRoot, "characters"),
+      documents: () => join5(vRoot, "documents"),
+      character: (id) => join5(vRoot, "characters", assertSafeSegment(id)),
+      dbBackups: () => join5(vRoot, "db-backups"),
+      dbBackup: (name) => join5(vRoot, "db-backups", assertSafeSegment(name)),
+      snapshots: () => join5(vRoot, "snapshots"),
+      snapshot: (name) => join5(vRoot, "snapshots", assertSafeSegment(name)),
+      deletedMarker: (kind, id) => join5(vRoot, kind, assertSafeSegment(id), ".deleted"),
+      document: (id) => join5(vRoot, "documents", assertSafeSegment(id)),
+      plugins: () => join5(vRoot, "plugins"),
+      pluginVaultDir: (id) => join5(vRoot, "plugins", assertSafeSegment(id), "vault")
+    };
+  }
+  const active = versionAt(activeVersion);
+  const latest = versionAt(latestVersion);
+  const uploadStagingRootPath = join5(localRoot, ".tmp");
+  const cacheRoot = join5(localRoot, "cache");
+  const local = {
+    root: localRoot,
+    cache: () => cacheRoot,
+    logs: () => join5(localRoot, "logs"),
+    localCover: (subjectKind, id, variant, format) => join5(
+      cacheRoot,
+      localCoverSubjectDir(subjectKind),
+      assertSafeSegment(id),
+      `${assertSafeSegment(variant)}.${format ?? "avif"}`
+    ),
+    resFileVariant: (id, filename, variantKey, format) => join5(
+      cacheRoot,
+      "resources",
+      assertSafeSegment(id),
+      "file-preview",
+      `${assertSafeSegment(sourceCacheId(filename))}__${assertSafeSegment(variantKey)}.${format ?? "avif"}`
+    ),
+    resFilePreviewDir: (id) => join5(cacheRoot, "resources", assertSafeSegment(id), "file-preview"),
+    resFilesCache: (id) => join5(cacheRoot, "resources", assertSafeSegment(id), "files-cache.json"),
+    resource: (id) => join5(cacheRoot, "resources", assertSafeSegment(id)),
+    character: (id) => join5(cacheRoot, "characters", assertSafeSegment(id)),
+    trash: () => join5(localRoot, "trash"),
+    trashItem: (id) => join5(localRoot, "trash", assertSafeSegment(id)),
+    tmp: () => join5(cacheRoot, "tmp"),
+    tmpFile: (name) => join5(cacheRoot, "tmp", assertSafeSegment(name)),
+    sessionKey: () => join5(localRoot, ".session-key"),
+    uploadStagingRoot: () => uploadStagingRootPath,
+    stagingPoolRoot: () => join5(uploadStagingRootPath, "staging"),
+    stagingPoolFile: (fileId, ext) => join5(
+      uploadStagingRootPath,
+      "staging",
+      `${assertSafeSegment(fileId)}${ext}`
+    ),
+    resVideoFrame: (id, filename, timeMs) => join5(
+      cacheRoot,
+      "resources",
+      assertSafeSegment(id),
+      "frames",
+      assertSafeSegment(sourceCacheId(filename)),
+      `${timeMs}.avif`
+    ),
+    resExtractedDir: (id, fileVersion) => join5(
+      cacheRoot,
+      "resources",
+      assertSafeSegment(id),
+      "extracted",
+      `v${fileVersion}`
+    ),
+    resExtractedEntry: (id, fileVersion, entryName) => join5(
+      cacheRoot,
+      "resources",
+      assertSafeSegment(id),
+      "extracted",
+      `v${fileVersion}`,
+      assertSafeSegment(sourceCacheId(entryName))
+    ),
+    resExtractedArchivesDir: (id, fileVersion) => join5(
+      cacheRoot,
+      "resources",
+      assertSafeSegment(id),
+      "extracted",
+      `v${fileVersion}`,
+      "archives"
+    )
+  };
+  return {
+    root,
+    activeVersion,
+    latestVersion,
+    active,
+    latest,
+    local,
+    atVersion: (v) => versionAt(v),
+    runtimeDb: () => join5(root, "app.sqlite")
+  };
+}
+function localCoverSubjectDir(subjectKind) {
+  return subjectKind === "resource" ? "resources" : "characters";
+}
+function toCacheBasename(filename) {
+  const dot = filename.lastIndexOf(".");
+  if (dot <= 0) return filename.replace(/[/\\]/g, "__");
+  const stem = filename.slice(0, dot).replace(/[/\\]/g, "__");
+  const ext = filename.slice(dot + 1);
+  return `${stem}__${ext}`;
+}
+function sourceCacheId(filename) {
+  return `${toCacheBasename(filename)}__${shortHash(filename)}`;
+}
+function shortHash(input) {
+  return createHash("sha256").update(input).digest("hex").slice(0, 8);
+}
+function imageVariantKey(canonical) {
+  return shortHash(canonical);
+}
+function assertSafeSegment(segment) {
+  if (segment.length === 0) throw new Error("path segment must not be empty");
+  if (segment === "." || segment === "..") {
+    throw new Error(`path segment must not be '${segment}'`);
+  }
+  if (segment.includes("/") || segment.includes("\\")) {
+    throw new Error(`path segment must not contain separators: ${segment}`);
+  }
+  if (hasForbiddenVisibleChar(segment) || hasControlChar(segment)) {
+    throw new Error(`path segment contains disallowed characters: ${segment}`);
+  }
+  if (segment.endsWith(".") || segment.endsWith(" ")) {
+    throw new Error(
+      `path segment must not end with dot or space: ${JSON.stringify(segment)}`
+    );
+  }
+  const base = segment.split(".")[0]?.toUpperCase();
+  if (base !== void 0 && WINDOWS_RESERVED.has(base)) {
+    throw new Error(`path segment is a reserved name: ${segment}`);
+  }
+  return segment;
+}
+function join5(...segments) {
+  return resolve(...segments);
+}
+function assertInside(ancestor, candidate) {
+  const resolved = resolve(candidate);
+  const base = resolve(ancestor);
+  if (resolved !== base && !resolved.startsWith(base + sep)) {
+    throw new Error(`path ${resolved} escapes ${base}`);
+  }
+  return resolved;
+}
+var PluginVaultPathError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PluginVaultPathError";
+  }
+};
+function parsePluginVaultDest(vaultDir, dest) {
+  if (dest.length === 0) {
+    throw new PluginVaultPathError("plugin vault destination must not be empty");
+  }
+  const segments = dest.split("/");
+  let abs = vaultDir;
+  for (const segment of segments) {
+    if (segment.length === 0) {
+      throw new PluginVaultPathError(
+        `plugin vault destination must not contain empty segments: ${JSON.stringify(dest)}`
+      );
+    }
+    try {
+      abs = join(abs, assertSafeSegment(segment));
+    } catch (err) {
+      throw new PluginVaultPathError(
+        err instanceof Error ? err.message : String(err)
+      );
+    }
+  }
+  try {
+    const resolved = assertInside(vaultDir, abs);
+    return { rel: segments.join("/"), abs: resolved };
+  } catch (err) {
+    throw new PluginVaultPathError(
+      err instanceof Error ? err.message : String(err)
+    );
+  }
+}
+async function vaultStatFile(vaultDir, rel) {
+  const { abs } = parsePluginVaultDest(vaultDir, rel);
+  const info = await stat(abs).catch(() => void 0);
+  if (info === void 0 || !info.isFile()) return void 0;
+  return { sizeBytes: info.size };
+}
+async function vaultReadFile(vaultDir, rel, maxBytes) {
+  const { abs } = parsePluginVaultDest(vaultDir, rel);
+  const info = await stat(abs).catch(() => void 0);
+  if (info === void 0 || !info.isFile()) {
+    throw pluginAssetError("POLICY", `plugin vault file not found: ${rel}`);
+  }
+  if (info.size > maxBytes) {
+    throw pluginAssetError(
+      "POLICY",
+      `plugin vault file "${rel}" exceeds the ${maxBytes}-byte read cap`
+    );
+  }
+  const bytes = await readFile(abs);
+  return new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+}
+async function vaultRemoveFile(vaultDir, rel) {
+  const { abs } = parsePluginVaultDest(vaultDir, rel);
+  const info = await stat(abs).catch(() => void 0);
+  if (info === void 0) return false;
+  if (!info.isFile()) {
+    throw pluginAssetError(
+      "POLICY",
+      `plugin vault destination is not a file: ${rel}`
+    );
+  }
+  await rm(abs);
+  return true;
+}
+function vaultTempFile(vaultDir) {
+  return join(vaultDir, `.${randomUUID()}.tmp`);
+}
+async function discardVaultTempFile(tempPath) {
+  await rm(tempPath, { force: true }).catch(() => {
+  });
+}
+async function commitVaultFile(opts) {
+  const { abs } = parsePluginVaultDest(opts.vaultDir, opts.rel);
+  const existing = await stat(abs).catch(() => void 0);
+  if (existing !== void 0 && !existing.isFile()) {
+    throw pluginAssetError(
+      "POLICY",
+      `plugin vault destination is not a file: ${opts.rel}`
+    );
+  }
+  const tempInfo = await stat(opts.tempPath).catch(() => void 0);
+  if (tempInfo === void 0 || !tempInfo.isFile()) {
+    throw pluginAssetError(
+      "POLICY",
+      `plugin vault download lost its staging file: ${opts.rel}`
+    );
+  }
+  if (tempInfo.size > opts.maxFileBytes) {
+    throw pluginAssetError(
+      "POLICY",
+      `plugin vault file "${opts.rel}" exceeds the ${opts.maxFileBytes}-byte download cap`
+    );
+  }
+  const currentTotal = await vaultTotalSize(opts.vaultDir);
+  const replacedBytes = existing?.isFile() ? existing.size : 0;
+  if (currentTotal - replacedBytes + tempInfo.size > opts.maxTotalBytes) {
+    throw pluginAssetError(
+      "POLICY",
+      `plugin vault "${opts.rel}" would exceed the ${opts.maxTotalBytes}-byte plugin quota (current ${currentTotal})`
+    );
+  }
+  await mkdir(resolve(abs, ".."), { recursive: true });
+  await rename(opts.tempPath, abs);
+  return { sizeBytes: tempInfo.size, sha256: await hashFileAbs(abs) };
+}
+async function vaultTotalSize(vaultDir) {
+  return sumDirSizes(vaultDir, { excludeDotPrefix: true });
+}
+async function vaultFileSha256(vaultDir, rel) {
+  const { abs } = parsePluginVaultDest(vaultDir, rel);
+  const info = await stat(abs).catch(() => void 0);
+  if (info === void 0 || !info.isFile()) {
+    throw pluginAssetError("POLICY", `plugin vault file not found: ${rel}`);
+  }
+  return hashFileAbs(abs);
+}
+async function hashFileAbs(abs) {
+  const hash = createHash("sha256");
+  await new Promise((resolveDone, reject) => {
+    const stream = createReadStream(abs);
+    stream.on("data", (chunk) => hash.update(chunk));
+    stream.on("end", () => resolveDone());
+    stream.on("error", reject);
+  });
+  return hash.digest("hex");
+}
+
+// src/hoard/sanitize.ts
+var FORBIDDEN_VISIBLE_CHARS2 = '<>:"|?*';
+var MAX_SEGMENT_BYTES = 240;
+var MAX_REL_PATH_CHARS = 700;
+var MAX_UNIQUE_RETRIES = 1e4;
+var WINDOWS_RESERVED2 = /* @__PURE__ */ new Set([
+  "CON",
+  "PRN",
+  "AUX",
+  "NUL",
+  "COM0",
+  "COM1",
+  "COM2",
+  "COM3",
+  "COM4",
+  "COM5",
+  "COM6",
+  "COM7",
+  "COM8",
+  "COM9",
+  "LPT0",
+  "LPT1",
+  "LPT2",
+  "LPT3",
+  "LPT4",
+  "LPT5",
+  "LPT6",
+  "LPT7",
+  "LPT8",
+  "LPT9",
+  "CONIN$",
+  "CONOUT$",
+  "COM\xB9",
+  "COM\xB2",
+  "COM\xB3",
+  "LPT\xB9",
+  "LPT\xB2",
+  "LPT\xB3"
+]);
+function sanitizeEntryName(name) {
+  if (name.length === 0 || name.includes("\0")) return void 0;
+  const normalized = name.normalize("NFC");
+  const rawSegments = normalized.replace(/\\/g, "/").split("/");
+  const segments = [];
+  for (const raw of rawSegments) {
+    const cleaned = cleanSegment(raw);
+    if (cleaned === void 0) continue;
+    segments.push(cleaned);
+  }
+  if (segments.length === 0) return void 0;
+  const relPath = segments.join("/");
+  if (relPath.length > MAX_REL_PATH_CHARS) return void 0;
+  return relPath;
+}
+function cleanSegment(raw) {
+  if (raw.length === 0 || raw === "." || raw === "..") return void 0;
+  let out = "";
+  for (const ch of raw) {
+    const code = ch.codePointAt(0);
+    if (code !== void 0 && code < 32) continue;
+    if (FORBIDDEN_VISIBLE_CHARS2.includes(ch)) {
+      out += "_";
+      continue;
+    }
+    out += ch;
+  }
+  let trimmed = out.replace(/^\.+/, "").replace(/[. ]+$/, "");
+  if (trimmed.length === 0) return void 0;
+  trimmed = truncateUtf8(trimmed, MAX_SEGMENT_BYTES);
+  if (trimmed.length === 0) return void 0;
+  const base = trimmed.split(".")[0]?.toUpperCase();
+  if (base !== void 0 && WINDOWS_RESERVED2.has(base)) {
+    trimmed = `_${trimmed}`;
+  }
+  return trimmed;
+}
+function truncateUtf8(value, maxBytes) {
+  let bytes = 0;
+  let out = "";
+  for (const ch of value) {
+    const len = Buffer.byteLength(ch, "utf8");
+    if (bytes + len > maxBytes) break;
+    bytes += len;
+    out += ch;
+  }
+  return out;
+}
+function createOccupiedNames(existing) {
+  return {
+    files: new Set(existing?.files ?? []),
+    dirs: new Set(existing?.dirs ?? [])
+  };
+}
+function occupyEntryName(occupied, relPath) {
+  occupied.files.add(relPath);
+  let prefix = "";
+  for (const segment of relPath.split("/").slice(0, -1)) {
+    prefix = prefix.length > 0 ? `${prefix}/${segment}` : segment;
+    occupied.dirs.add(prefix);
+  }
+}
+function uniqueEntryName(occupied, relPath) {
+  const lowerFiles = new Set([...occupied.files].map((p) => p.toLowerCase()));
+  const lowerDirs = new Set([...occupied.dirs].map((p) => p.toLowerCase()));
+  let candidate = relPath;
+  for (let guard = 0; guard < MAX_UNIQUE_RETRIES; guard += 1) {
+    const segIdx = collidingSegment(lowerFiles, lowerDirs, candidate);
+    if (segIdx < 0) return candidate;
+    const segments = candidate.split("/");
+    const target = segments[segIdx];
+    const dot = target.lastIndexOf(".");
+    const stem = dot > 0 ? target.slice(0, dot) : target;
+    const ext = dot > 0 ? target.slice(dot) : "";
+    for (let i = 1; ; i += 1) {
+      const next = `${stem}-${i}${ext}`;
+      const rebuilt = segments.map((seg, idx) => idx === segIdx ? next : seg).join("/");
+      if (collidingSegment(lowerFiles, lowerDirs, rebuilt) < 0) {
+        candidate = rebuilt;
+        break;
+      }
+    }
+  }
+  throw new Error(`unable to resolve a unique name for ${relPath}`);
+}
+function collidingSegment(lowerFiles, lowerDirs, candidate) {
+  const segments = candidate.split("/");
+  const lower = candidate.toLowerCase();
+  if (lowerFiles.has(lower) || lowerDirs.has(lower)) return segments.length - 1;
+  let prefix = "";
+  for (let i = 0; i < segments.length - 1; i += 1) {
+    prefix = prefix.length > 0 ? `${prefix}/${segments[i]}` : segments[i];
+    if (lowerFiles.has(prefix.toLowerCase())) return i;
+  }
+  return -1;
+}
+var STAGED_ARCHIVE_EXT = ".zip";
+async function findStagedPoolFile(paths, fileId) {
+  const poolDir = paths.local.stagingPoolRoot();
+  const names = await readdir(poolDir).catch(() => []);
+  for (const name of names) {
+    const ext = extname(name);
+    const stem = basename(name, ext);
+    if (stem === fileId) return join(poolDir, name);
+  }
+  return void 0;
+}
+async function resolveStagedPoolFiles(paths, fileIds) {
+  const poolDir = paths.local.stagingPoolRoot();
+  const names = await readdir(poolDir).catch(() => []);
+  const byStem = /* @__PURE__ */ new Map();
+  for (const name of names) {
+    const ext = extname(name);
+    const stem = basename(name, ext);
+    if (!byStem.has(stem)) byStem.set(stem, join(poolDir, name));
+  }
+  const out = /* @__PURE__ */ new Map();
+  for (const fileId of fileIds) {
+    const hit = byStem.get(fileId);
+    if (hit !== void 0) out.set(fileId, hit);
+  }
+  return out;
+}
+async function writeStagedPoolFile(paths, fileId, filename, stream) {
+  await mkdir(paths.local.stagingPoolRoot(), { recursive: true });
+  const ext = extname(filename).toLowerCase();
+  const dest = paths.local.stagingPoolFile(fileId, ext);
+  const tmp = `${dest}.tmp-${Date.now()}`;
+  try {
+    await pipeline(stream, createWriteStream(tmp));
+    await rename(tmp, dest);
+    return dest;
+  } catch (err) {
+    await rm(tmp, { force: true }).catch(() => {
+    });
+    throw err;
+  }
+}
+async function writeStagedArchiveFile(paths, fileId, stream) {
+  return writeStagedPoolFile(paths, fileId, "archive.zip", stream);
+}
+async function findStagedArchiveFile(paths, fileId) {
+  const existing = await findStagedPoolFile(paths, fileId);
+  if (existing === void 0) return void 0;
+  return extname(existing).toLowerCase() === STAGED_ARCHIVE_EXT ? existing : void 0;
+}
+async function removeStagedPoolFile(paths, fileId) {
+  const existing = await findStagedPoolFile(paths, fileId);
+  if (existing === void 0) return false;
+  await rm(existing, { force: true }).catch(() => {
+  });
+  const stillThere = await stat(existing).catch(() => void 0);
+  return stillThere === void 0;
+}
+
+// src/hoard/write-versioned.ts
+async function writeVersioned(paths, readOnly, cmd) {
+  if (readOnly) {
+    throw conflict(
+      "server.read_only_archive",
+      "server is viewing a read-only archive; versioned writes are blocked"
+    );
+  }
+  return await cmd(paths.latest);
+}
+
+// src/hoard/versioned-folder-ops.ts
+function buildVersionedFolderOps(paths, readOnly, kind) {
+  const folderOf = (id) => (current) => kind === "resource" ? current.resource(id) : current.character(id);
+  const trashPrefix = kind === "resource" ? "resources-" : "characters-";
+  const deletedKind = kind === "resource" ? "resources" : "characters";
+  async function ensureFolder(id) {
+    await writeVersioned(
+      paths,
+      readOnly.current,
+      (current) => mkdir(folderOf(id)(current), { recursive: true })
+    );
+  }
+  async function removeFolder(id) {
+    await writeVersioned(
+      paths,
+      readOnly.current,
+      (current) => rm(folderOf(id)(current), {
+        recursive: true,
+        force: true
+      }).catch(() => {
+      })
+    );
+  }
+  async function markDeleted(id) {
+    return writeVersioned(paths, readOnly.current, async (current) => {
+      const folder = folderOf(id)(current);
+      await mkdir(folder, { recursive: true });
+      const marker = current.deletedMarker(deletedKind, id);
+      await writeFile(marker, "");
+      return marker;
+    });
+  }
+  async function moveFolderToTrash(id) {
+    await mkdir(paths.local.trash(), { recursive: true });
+    return writeVersioned(paths, readOnly.current, async (current) => {
+      const src = folderOf(id)(current);
+      const dest = join(
+        paths.local.trash(),
+        `${trashPrefix}${id}-${Date.now()}`
+      );
+      try {
+        await rename(src, dest);
+      } catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+          return dest;
+        }
+        if (code === "EPERM" || code === "EBUSY" || code === "UNKNOWN") {
+          return src;
+        }
+        throw err;
+      }
+      return dest;
+    });
+  }
+  return {
+    ensureFolder,
+    removeFolder,
+    markDeleted,
+    moveFolderToTrash
+  };
+}
+async function archiveStaleFiles(args) {
+  const { sourceFolder, destFolder, match, archivePrefix } = args;
+  const entries = await readdir(sourceFolder).catch(() => []);
+  const stale = entries.filter(match);
+  if (stale.length === 0) return;
+  await mkdir(destFolder, { recursive: true });
+  const stamp = Date.now();
+  await Promise.all(
+    stale.map(async (name, i) => {
+      const ext = extname(name);
+      const archiveName = stale.length === 1 ? `${archivePrefix}${stamp}${ext}` : `${archivePrefix}${stamp}_${i}${ext}`;
+      try {
+        await rename(join(sourceFolder, name), join(destFolder, archiveName));
+      } catch (err) {
+        if (!isEnoentError(err)) throw err;
+      }
+    })
+  );
+}
+function isEnoentError(err) {
+  return err instanceof Error && "code" in err && err.code === "ENOENT";
+}
+
+export { ORDER_MANIFEST_NAME, PluginVaultPathError, RESOURCE_DATA_DIR_NAME, archiveStaleFiles, assertInside, assertSafeSegment, buildVersionedFolderOps, commitVaultFile, createNextVersion, createOccupiedNames, createStoragePaths, currentVersion, discardVaultTempFile, ensureBootstrapVersion, extractArchiveInto, findStagedArchiveFile, findStagedPoolFile, imageVariantKey, listArchiveEntries, listVersions, naturalSort, occupyEntryName, orderEntries, orderManifestPath, parseOrderManifest, parsePluginVaultDest, readActiveVersion, readOrderManifest, removeStagedPoolFile, resolveStagedPoolFiles, sanitizeEntryName, streamStoredZip, sumDirSizes, uniqueEntryName, validateArchiveBudget, vaultFileSha256, vaultReadFile, vaultRemoveFile, vaultStatFile, vaultTempFile, vaultTotalSize, versionedDbFile, versionedPath, writeActiveVersion, writeOrderManifest, writeStagedArchiveFile, writeStagedPoolFile, writeVersioned };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map