@hoardodile/host 0.1.1 → 0.1.3

package/dist/chunks/worker-entry.mjs

@@ -43,6 +43,7 @@ const HOOK_NAMES = [
 	"coverLocal",
 	"listFiles",
 	"imageHashes",
+	"onInstall",
 ]
 
 const API_METHOD_NAMES = [
@@ -283,7 +284,11 @@ function send(message) {
 function approxByteSize(value) {
 	if (value instanceof Uint8Array) return value.byteLength
 	try {
-		return JSON.stringify(value).length * 2
+		// `undefined` (hooks that legitimately return nothing — e.g.
+		// `onInstall`) stringifies to `undefined`, not a string: an empty
+		// payload must size 0, never throw into the Infinity branch.
+		const text = JSON.stringify(value)
+		return (typeof text === "string" ? text : "").length * 2
 	} catch {
 		return Infinity
 	}

package/dist/hoard/index.d.ts

@@ -1,4 +1,7 @@
-import { Readable } from 'node:stream';
+export { Z as ZipStreamEntry, s as streamStoredZip } from '../pack-6IscrwYN.js';
+import 'node:stream';
+
+type ContainerFormat = "zip" | "tar" | "7z" | "rar" | "xz" | "gzip";
 
 /**
  * Whole-archive extraction. Every supported format (zip, tar, 7z, rar,
@@ -33,6 +36,14 @@ type ExtractArchiveOptions = {
     /** Optional entry-count budget (enforced on the listing). */
     readonly maxEntries?: number;
     readonly onProgress?: ZipExtractReporter;
+    /**
+     * Optional format allow-list (e.g. `["zip"]` for plugin installs).
+     * An archive sniffed outside the list is rejected up front with
+     * `resource.archive_format_not_allowed` — project-internal channels
+     * that only ever produce one format stop admitting the others
+     * instead of opening every codec to untrusted input.
+     */
+    readonly formats?: readonly ContainerFormat[];
 };
 /**
  * Stream an archive into `destDir`, format-agnostic: every supported
@@ -92,28 +103,6 @@ declare function listArchiveEntries(archivePath: string): Promise<readonly Archi
  */
 declare function validateArchiveBudget(archivePath: string, maxBytes: number): Promise<void>;
 
-/**
- * On-the-fly zip exports. Resource sources are stored as bare files on
- * disk — nothing is packed at commit time; this module streams STORED
- * zip bytes straight to the consumer without a staging file.
- */
-/**
- * A logical zip entry whose bytes are produced on demand. Streams are
- * read once, in order, when the output is consumed.
- */
-type ZipStreamEntry = {
-    readonly name: string;
-    readonly size: number;
-    readonly openStream: () => Readable;
-};
-/**
- * Stream a STORED zip from an ordered list of logical entries. Used by
- * the HTTP layer for exports (resource source packs, bulk downloads)
- * without a staging file on disk. Zero-length entries are packed as
- * empty buffers.
- */
-declare function streamStoredZip(entries: readonly ZipStreamEntry[]): NodeJS.ReadableStream;
-
 /**
  * Shared directory-size walk: the one implementation of "recursive byte
  * size of a directory tree" for host storage. Consumers opt into
@@ -199,7 +188,8 @@ declare const RESOURCE_DATA_DIR_NAME = "data";
  *   per-version database snapshot), `db-backups/` (manual backups,
  *   only kept for the current version), `snapshots/` (automatic daily
  *   snapshots, only kept for the current version), `resources/<id>/`,
- *   `characters/<id>/`, `plugins/<id>/` (installed content plugins
+ *   `characters/<id>/`, `tags/<id>/` (tag art — see {@link VersionPaths.tag}),
+ *   `plugins/<id>/` (installed content plugins
  *   frozen with that version; the builtin `file` plugin is not stored
  *   here). Old versions are FROZEN: no writes ever land in
  *   `versions/<v>` once a `versions/<v+1>` exists.
@@ -256,10 +246,18 @@ type VersionPaths = {
     resources(): string;
     /** Root folder of all characters in this version: `<root>/versions/<v>/characters`. */
     characters(): string;
+    /** Root folder of all tags in this version: `<root>/versions/<v>/tags`. */
+    tags(): string;
     /** Root folder of all documents in this version: `<root>/versions/<v>/documents`. */
     documents(): string;
     /** Root folder of a character: `<root>/versions/<v>/characters/<id>`. */
     character(id: string): string;
+    /**
+     * Root folder of a tag: `<root>/versions/<v>/tags/<id>`. Holds the
+     * tag's single image slot (`image.<ext>`), the same convention as
+     * character avatar/fullbody slots.
+     */
+    tag(id: string): string;
     /** Root of manual backups: `<root>/versions/<v>/db-backups`. */
     dbBackups(): string;
     /** Path to one manual backup: `<root>/versions/<v>/db-backups/<name>`. */
@@ -274,7 +272,7 @@ type VersionPaths = {
      * delete cannot remove a folder whose files live under frozen past
      * archives.
      */
-    deletedMarker(kind: "resources" | "characters", id: string): string;
+    deletedMarker(kind: "resources" | "characters" | "tags", id: string): string;
     /** Root folder of a document: `<root>/versions/<v>/documents/<id>`. */
     document(id: string): string;
     /**
@@ -301,11 +299,11 @@ type LocalPaths = {
     logs(): string;
     /**
      * Path to a local derived cover/thumb variant:
-     * `<localRoot>/cache/<resources|characters>/<id>/<variant>.<format>`.
+     * `<localRoot>/cache/<resources|characters|tags>/<id>/<variant>.<format>`.
      * Holds synthesized covers (resource covers, character avatars and
-     * fullbody images); re-rendered when cleared.
+     * fullbody images, tag art); re-rendered when cleared.
      */
-    localCover(subjectKind: "resource" | "character", id: string, variant: string, format?: string): string;
+    localCover(subjectKind: "resource" | "character" | "tag", id: string, variant: string, format?: string): string;
     /**
      * Per-file derived image variant:
      * `<localRoot>/cache/resources/<id>/file-preview/<sourceCacheId>__<variantKey>.<format>`.
@@ -331,6 +329,13 @@ type LocalPaths = {
      * (b) thumbnail variants (`avatar.webp`, `fullbody.webp`).
      */
     character(id: string): string;
+    /**
+     * Root of the local per-tag directory:
+     * `<localRoot>/cache/tags/<id>`.
+     * Holds (a) versioned copies of replaced tag art and (b) the tag
+     * thumbnail variant (`image.avif`).
+     */
+    tag(id: string): string;
     /** Root of the trash: `<localRoot>/trash`. */
     trash(): string;
     /** Path to a single trashed item: `<localRoot>/trash/<id>`. */
@@ -351,6 +356,14 @@ type LocalPaths = {
      * `local/` (never synced) so each host has its own seal key.
      */
     sessionKey(): string;
+    /**
+     * Path to the seed-removal marker file: `<root>/local/seed-removals.json`.
+     * Holds the plugin ids (UUIDs) whose bundled seed was deliberately
+     * uninstalled by this host, so boot-time seeding skips them until the
+     * user restores them. Host-only state — never synced, survives app
+     * updates, and stays out of the wipe-on-clear `cache/` tree.
+     */
+    seedRemovals(): string;
     /**
      * Root of the host-only temporary directory tree:
      * `<localRoot>/.tmp`. Holds the global staging pool
@@ -680,6 +693,7 @@ declare function versionedDbFile(root: string, v: number): string;
  */
 declare function versionedPath(root: string, v: number): string;
 
+type VersionedFolderSubjectKind = "resource" | "character" | "tag";
 type VersionedFolderOps = {
     /** Ensure the current-version entity folder exists. */
     ensureFolder(id: string): Promise<void>;
@@ -699,21 +713,9 @@ type VersionedFolderOps = {
      */
     moveFolderToTrash(id: string): Promise<string>;
 };
-/**
- * The four lifecycle operations shared by the resource and character
- * file-system layers. They differ only in which versioned folder they
- * target and how the trash / placeholder names are derived.
- *
- * `moveFolderToTrash` treats `EPERM`/`EBUSY`/`UNKNOWN` as transient Windows
- * locks (a file inside the folder is still open) and leaves the source in
- * place; a boot-time orphan sweep reclaims it later.
- *
- * `readOnly` is a live `{ current: boolean }` ref (the server's runtime
- * read-only flag), so a version switch mid-request re-reads it.
- */
 declare function buildVersionedFolderOps(paths: StoragePaths, readOnly: {
     readonly current: boolean;
-}, kind: "resource" | "character"): VersionedFolderOps;
+}, kind: VersionedFolderSubjectKind): VersionedFolderOps;
 /**
  * Move every file in `sourceFolder` whose name matches `match` into
  * `destFolder` under a timestamped archive name (`<prefix><stamp><ext>`, or
@@ -751,4 +753,4 @@ type VersionedWriteCommand<T> = (paths: StoragePaths["latest"]) => T | Promise<T
  */
 declare function writeVersioned<T>(paths: StoragePaths, readOnly: boolean, cmd: VersionedWriteCommand<T>): Promise<T>;
 
-export { type CreateNextVersionResult, type CreateStoragePathsOptions, type DirSizeOptions, type LocalPaths, ORDER_MANIFEST_NAME, type OccupiedNames, PluginVaultPathError, RESOURCE_DATA_DIR_NAME, type StoragePaths, type VaultCommitResult, type VersionPaths, type VersionedFolderOps, type VersionedWriteCommand, type ZipStreamEntry, 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 };
+export { type CreateNextVersionResult, type CreateStoragePathsOptions, type DirSizeOptions, type LocalPaths, ORDER_MANIFEST_NAME, type OccupiedNames, PluginVaultPathError, RESOURCE_DATA_DIR_NAME, type StoragePaths, type VaultCommitResult, type VersionPaths, type VersionedFolderOps, type VersionedFolderSubjectKind, type VersionedWriteCommand, 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, sumDirSizes, uniqueEntryName, validateArchiveBudget, vaultFileSha256, vaultReadFile, vaultRemoveFile, vaultStatFile, vaultTempFile, vaultTotalSize, versionedDbFile, versionedPath, writeActiveVersion, writeOrderManifest, writeStagedArchiveFile, writeStagedPoolFile, writeVersioned };

package/dist/hoard/index.js

@@ -573,16 +573,16 @@ function parseSltListing(stdout, legacyNames) {
       }
       continue;
     }
-    const sep3 = line.indexOf(" = ");
-    if (sep3 < 0) continue;
-    const key = line.slice(0, sep3);
+    const sep4 = line.indexOf(" = ");
+    if (sep4 < 0) continue;
+    const key = line.slice(0, sep4);
     if (key === "Path") {
-      const raw = Buffer.from(line.slice(sep3 + 3), "latin1");
+      const raw = Buffer.from(line.slice(sep4 + 3), "latin1");
       const decoded = legacyNames ? decodeLegacyZipName(raw) : raw.toString("utf8");
       name = decoded.replace(/\\/g, "/");
       continue;
     }
-    const value = line.slice(sep3 + 3);
+    const value = line.slice(sep4 + 3);
     switch (key) {
       case "Size":
         sizeBytes = Number.parseInt(value, 10) || 0;
@@ -694,6 +694,13 @@ async function extractArchiveInto(source, destDir, opts) {
       {}
     );
   }
+  if (opts.formats !== void 0 && !opts.formats.includes(format)) {
+    throw invalid(
+      "resource.archive_format_not_allowed",
+      `archive format ${format} is not allowed here (allowed: ${opts.formats.join(", ")})`,
+      { allowed: opts.formats }
+    );
+  }
   if (format === "zip" && resolveSevenZipPath() === void 0) {
     return extractZipBuffer(buffer2, destDir, opts);
   }
@@ -1359,65 +1366,69 @@ function createStoragePaths(opts) {
   }
   function versionAt(version) {
     const vSeg = assertSafeSegment(String(version));
-    const vRoot = join5(versionsRootPath, vSeg);
+    const vRoot = join6(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")
+      versionSnapshotDb: () => join6(vRoot, "app.sqlite"),
+      resource: (id) => join6(vRoot, "resources", assertSafeSegment(id)),
+      resourceData: (id) => join6(vRoot, "resources", assertSafeSegment(id), RESOURCE_DATA_DIR_NAME),
+      resources: () => join6(vRoot, "resources"),
+      characters: () => join6(vRoot, "characters"),
+      tags: () => join6(vRoot, "tags"),
+      documents: () => join6(vRoot, "documents"),
+      character: (id) => join6(vRoot, "characters", assertSafeSegment(id)),
+      tag: (id) => join6(vRoot, "tags", assertSafeSegment(id)),
+      dbBackups: () => join6(vRoot, "db-backups"),
+      dbBackup: (name) => join6(vRoot, "db-backups", assertSafeSegment(name)),
+      snapshots: () => join6(vRoot, "snapshots"),
+      snapshot: (name) => join6(vRoot, "snapshots", assertSafeSegment(name)),
+      deletedMarker: (kind, id) => join6(vRoot, kind, assertSafeSegment(id), ".deleted"),
+      document: (id) => join6(vRoot, "documents", assertSafeSegment(id)),
+      plugins: () => join6(vRoot, "plugins"),
+      pluginVaultDir: (id) => join6(vRoot, "plugins", assertSafeSegment(id), "vault")
     };
   }
   const active = versionAt(activeVersion);
   const latest = versionAt(latestVersion);
-  const uploadStagingRootPath = join5(localRoot, ".tmp");
-  const cacheRoot = join5(localRoot, "cache");
+  const uploadStagingRootPath = join6(localRoot, ".tmp");
+  const cacheRoot = join6(localRoot, "cache");
   const local = {
     root: localRoot,
     cache: () => cacheRoot,
-    logs: () => join5(localRoot, "logs"),
-    localCover: (subjectKind, id, variant, format) => join5(
+    logs: () => join6(localRoot, "logs"),
+    localCover: (subjectKind, id, variant, format) => join6(
       cacheRoot,
       localCoverSubjectDir(subjectKind),
       assertSafeSegment(id),
       `${assertSafeSegment(variant)}.${format ?? "avif"}`
     ),
-    resFileVariant: (id, filename, variantKey, format) => join5(
+    resFileVariant: (id, filename, variantKey, format) => join6(
       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"),
+    resFilePreviewDir: (id) => join6(cacheRoot, "resources", assertSafeSegment(id), "file-preview"),
+    resFilesCache: (id) => join6(cacheRoot, "resources", assertSafeSegment(id), "files-cache.json"),
+    resource: (id) => join6(cacheRoot, "resources", assertSafeSegment(id)),
+    character: (id) => join6(cacheRoot, "characters", assertSafeSegment(id)),
+    tag: (id) => join6(cacheRoot, "tags", assertSafeSegment(id)),
+    trash: () => join6(localRoot, "trash"),
+    trashItem: (id) => join6(localRoot, "trash", assertSafeSegment(id)),
+    tmp: () => join6(cacheRoot, "tmp"),
+    tmpFile: (name) => join6(cacheRoot, "tmp", assertSafeSegment(name)),
+    sessionKey: () => join6(localRoot, ".session-key"),
+    seedRemovals: () => join6(localRoot, "seed-removals.json"),
     uploadStagingRoot: () => uploadStagingRootPath,
-    stagingPoolRoot: () => join5(uploadStagingRootPath, "staging"),
-    stagingPoolFile: (fileId, ext) => join5(
+    stagingPoolRoot: () => join6(uploadStagingRootPath, "staging"),
+    stagingPoolFile: (fileId, ext) => join6(
       uploadStagingRootPath,
       "staging",
       `${assertSafeSegment(fileId)}${ext}`
     ),
-    resVideoFrame: (id, filename, timeMs) => join5(
+    resVideoFrame: (id, filename, timeMs) => join6(
       cacheRoot,
       "resources",
       assertSafeSegment(id),
@@ -1425,14 +1436,14 @@ function createStoragePaths(opts) {
       assertSafeSegment(sourceCacheId(filename)),
       `${timeMs}.avif`
     ),
-    resExtractedDir: (id, fileVersion) => join5(
+    resExtractedDir: (id, fileVersion) => join6(
       cacheRoot,
       "resources",
       assertSafeSegment(id),
       "extracted",
       `v${fileVersion}`
     ),
-    resExtractedEntry: (id, fileVersion, entryName) => join5(
+    resExtractedEntry: (id, fileVersion, entryName) => join6(
       cacheRoot,
       "resources",
       assertSafeSegment(id),
@@ -1440,7 +1451,7 @@ function createStoragePaths(opts) {
       `v${fileVersion}`,
       assertSafeSegment(sourceCacheId(entryName))
     ),
-    resExtractedArchivesDir: (id, fileVersion) => join5(
+    resExtractedArchivesDir: (id, fileVersion) => join6(
       cacheRoot,
       "resources",
       assertSafeSegment(id),
@@ -1457,11 +1468,11 @@ function createStoragePaths(opts) {
     latest,
     local,
     atVersion: (v) => versionAt(v),
-    runtimeDb: () => join5(root, "app.sqlite")
+    runtimeDb: () => join6(root, "app.sqlite")
   };
 }
 function localCoverSubjectDir(subjectKind) {
-  return subjectKind === "resource" ? "resources" : "characters";
+  return subjectKind === "resource" ? "resources" : subjectKind === "character" ? "characters" : "tags";
 }
 function toCacheBasename(filename) {
   const dot = filename.lastIndexOf(".");
@@ -1501,7 +1512,7 @@ function assertSafeSegment(segment) {
   }
   return segment;
 }
-function join5(...segments) {
+function join6(...segments) {
   return resolve(...segments);
 }
 function assertInside(ancestor, candidate) {
@@ -1850,10 +1861,25 @@ async function writeVersioned(paths, readOnly, cmd) {
 }
 
 // src/hoard/versioned-folder-ops.ts
+var KIND_LAYOUT = {
+  resource: { trashPrefix: "resources-", deletedKind: "resources" },
+  character: { trashPrefix: "characters-", deletedKind: "characters" },
+  tag: { trashPrefix: "tags-", deletedKind: "tags" }
+};
 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";
+  const folderOf = (id) => (current) => {
+    switch (kind) {
+      case "resource":
+        return current.resource(id);
+      case "character":
+        return current.character(id);
+      case "tag":
+        return current.tag(id);
+    }
+  };
+  const layout = KIND_LAYOUT[kind];
+  const trashPrefix = layout.trashPrefix;
+  const deletedKind = layout.deletedKind;
   async function ensureFolder(id) {
     await writeVersioned(
       paths,