@hoardodile/host 0.1.1 → 0.1.3

package/dist/pack-6IscrwYN.d.ts

@@ -0,0 +1,35 @@
+import { Readable } from 'node:stream';
+
+/**
+ * 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;
+/**
+ * Pack the *contents* of `srcDir` (its entries at the archive root) into
+ * a deflated zip written to `zipPath`. Entry names use forward slashes,
+ * the file order is sorted by relative path, and the output is streamed
+ * to disk — deterministic on every platform, memory-bounded regardless
+ * of dist size. The canonical packer for project-internal zips (the
+ * plugin release artifact via the CLI); resource exports use
+ * {@link streamStoredZip} instead.
+ */
+declare function packZipDirectory(srcDir: string, zipPath: string): Promise<void>;
+
+export { type ZipStreamEntry as Z, packZipDirectory as p, streamStoredZip as s };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hoardodile/host",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "license": "MIT",
   "description": "hoardodile plugin runtime host: sandbox, hook strategy, ResourceAPI, containers and the test runner.",
   "keywords": [
@@ -67,7 +67,7 @@
     "file-type": "^22.0.2",
     "yauzl": "^3.4.0",
     "yazl": "^3.3.1",
-    "@hoardodile/sdk-types": "0.1.1"
+    "@hoardodile/sdk-types": "0.1.3"
   },
   "optionalDependencies": {
     "@derhuerst/ffprobe-static": "^5.3.0",

package/src/archive/archive-ops.test.ts

@@ -14,7 +14,7 @@ import {
 	normalizeExtractedTree,
 } from "./extract.ts"
 import { listArchiveEntries, validateArchiveBudget } from "./listing.ts"
-import { streamStoredZip } from "./pack.ts"
+import { packZipDirectory, streamStoredZip } from "./pack.ts"
 import {
 	createFileArchiveSource,
 	listZipEntries,
@@ -232,6 +232,30 @@ describe("extractArchiveInto", () => {
 		).rejects.toMatchObject({ kind: "resource.archive_open_failed" })
 	})
 
+	test("rejects formats outside the allow-list without touching the destination", async () => {
+		const root = tempRoot()
+		const dest = join(root, "out")
+		await expect(
+			extractArchiveInto(
+				Readable.from(await buildZip([["a.txt", "alpha"]])),
+				dest,
+				{ maxBytes: 1_000_000, formats: ["tar"] },
+			),
+		).rejects.toMatchObject({ kind: "resource.archive_format_not_allowed" })
+		expect(existsSync(join(dest, "a.txt"))).toBe(false)
+	})
+
+	test("accepts a zip under a zip-only allow-list", async () => {
+		const root = tempRoot()
+		const dest = join(root, "out")
+		await extractArchiveInto(
+			Readable.from(await buildZip([["a.txt", "alpha"]])),
+			dest,
+			{ maxBytes: 1_000_000, formats: ["zip"] },
+		)
+		expect(await readFile(join(dest, "a.txt"), "utf8")).toBe("alpha")
+	})
+
 	test("rejects a corrupt zip with the archive-open error", async () => {
 		const root = tempRoot()
 		const dest = join(root, "out")
@@ -575,6 +599,30 @@ describe("streamStoredZip", () => {
 	})
 })
 
+describe("packZipDirectory", () => {
+	test("packs a directory's contents at the zip root, sorted, with forward slashes", async () => {
+		const root = tempRoot()
+		const src = join(root, "src")
+		await mkdir(join(src, "nested"), { recursive: true })
+		await writeFile(join(src, "manifest.json"), '{"id":"x"}')
+		await writeFile(join(src, "a.txt"), "a")
+		await writeFile(join(src, "nested", "b.txt"), "b")
+		const zipPath = join(root, "out.zip")
+
+		await packZipDirectory(src, zipPath)
+
+		const entries = await listZipEntries(zipPath)
+		expect(entries.map((entry) => entry.name)).toEqual([
+			"a.txt",
+			"manifest.json",
+			"nested/b.txt",
+		])
+		expect(await readEntryContent(zipPath, "nested/b.txt")).toEqual(
+			Buffer.from("b"),
+		)
+	})
+})
+
 describe("normalizeExtractedTree", () => {
 	test("renames macOS %XX-escaped legacy names to the decoded listing name", async () => {
 		const root = tempRoot()

package/src/archive/extract.ts

@@ -66,6 +66,14 @@ export 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[]
 }
 
 /**
@@ -100,6 +108,13 @@ export async function extractArchiveInto(
 			{},
 		)
 	}
+	if (opts.formats !== undefined && !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() === undefined) {
 		return extractZipBuffer(buffer, destDir, opts)
 	}

package/src/archive/index.ts

@@ -102,7 +102,7 @@ export {
 	VIRTUAL_PATH_SEPARATOR,
 } from "./nested-entry.ts"
 export type { ZipStreamEntry } from "./pack.ts"
-export { streamStoredZip } from "./pack.ts"
+export { packZipDirectory, streamStoredZip } from "./pack.ts"
 export type { ArchiveSource, ZipEntry } from "./zip-entries.ts"
 export {
 	createFileArchiveSource,

package/src/archive/pack.ts

@@ -1,4 +1,7 @@
+import { createWriteStream, readdirSync } from "node:fs"
+import { join, resolve, sep } from "node:path"
 import type { Readable } from "node:stream"
+import { pipeline } from "node:stream/promises"
 import yazl from "yazl"
 
 /**
@@ -38,3 +41,50 @@ export function streamStoredZip(entries: readonly ZipStreamEntry[]) {
 	zip.end()
 	return zip.outputStream
 }
+
+/**
+ * Pack the *contents* of `srcDir` (its entries at the archive root) into
+ * a deflated zip written to `zipPath`. Entry names use forward slashes,
+ * the file order is sorted by relative path, and the output is streamed
+ * to disk — deterministic on every platform, memory-bounded regardless
+ * of dist size. The canonical packer for project-internal zips (the
+ * plugin release artifact via the CLI); resource exports use
+ * {@link streamStoredZip} instead.
+ */
+export async function packZipDirectory(
+	srcDir: string,
+	zipPath: string,
+): Promise<void> {
+	const root = resolve(srcDir)
+	const files = listFilesSorted(root)
+	const zip = new yazl.ZipFile()
+	for (const abs of files) {
+		// yazl wants metadata names with forward slashes; the local-path
+		// basename order is deterministic thanks to listFilesSorted.
+		const rel = abs
+			.slice(root.length + 1)
+			.split(sep)
+			.join("/")
+		zip.addFile(abs, rel, { compress: true })
+	}
+	zip.end()
+	await pipeline(zip.outputStream, createWriteStream(resolve(zipPath)))
+}
+
+/** Every regular file under `root`, sorted by relative path (recursive). */
+function listFilesSorted(root: string): string[] {
+	const out: string[] = []
+	const walk = (dir: string) => {
+		for (const entry of readdirSync(dir, { withFileTypes: true })) {
+			const abs = join(dir, entry.name)
+			if (entry.isDirectory()) {
+				walk(abs)
+				continue
+			}
+			if (!entry.isFile()) continue
+			out.push(abs)
+		}
+	}
+	walk(root)
+	return out.sort()
+}

package/src/hoard/index.ts

@@ -75,7 +75,10 @@ export {
 	versionedPath,
 	writeActiveVersion,
 } from "./version.ts"
-export type { VersionedFolderOps } from "./versioned-folder-ops.ts"
+export type {
+	VersionedFolderOps,
+	VersionedFolderSubjectKind,
+} from "./versioned-folder-ops.ts"
 export {
 	archiveStaleFiles,
 	buildVersionedFolderOps,

package/src/hoard/paths.test.ts

@@ -100,6 +100,7 @@ describe("createStoragePaths", () => {
 			paths.local.trash(),
 			paths.local.logs(),
 			paths.local.sessionKey(),
+			paths.local.seedRemovals(),
 			paths.local.uploadStagingRoot(),
 			paths.local.stagingPoolRoot(),
 		]

package/src/hoard/paths.ts

@@ -71,7 +71,8 @@ function hasForbiddenVisibleChar(segment: string): boolean {
  *   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.
@@ -129,10 +130,18 @@ export 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>`. */
@@ -147,7 +156,7 @@ export 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
 	/**
@@ -175,12 +184,12 @@ export 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",
+		subjectKind: "resource" | "character" | "tag",
 		id: string,
 		variant: string,
 		format?: string,
@@ -215,6 +224,13 @@ export 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>`. */
@@ -235,6 +251,14 @@ export 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
@@ -348,8 +372,10 @@ export function createStoragePaths(
 				join(vRoot, "resources", assertSafeSegment(id), RESOURCE_DATA_DIR_NAME),
 			resources: () => join(vRoot, "resources"),
 			characters: () => join(vRoot, "characters"),
+			tags: () => join(vRoot, "tags"),
 			documents: () => join(vRoot, "documents"),
 			character: (id) => join(vRoot, "characters", assertSafeSegment(id)),
+			tag: (id) => join(vRoot, "tags", assertSafeSegment(id)),
 			dbBackups: () => join(vRoot, "db-backups"),
 			dbBackup: (name) => join(vRoot, "db-backups", assertSafeSegment(name)),
 			snapshots: () => join(vRoot, "snapshots"),
@@ -393,11 +419,13 @@ export function createStoragePaths(
 			join(cacheRoot, "resources", assertSafeSegment(id), "files-cache.json"),
 		resource: (id) => join(cacheRoot, "resources", assertSafeSegment(id)),
 		character: (id) => join(cacheRoot, "characters", assertSafeSegment(id)),
+		tag: (id) => join(cacheRoot, "tags", assertSafeSegment(id)),
 		trash: () => join(localRoot, "trash"),
 		trashItem: (id) => join(localRoot, "trash", assertSafeSegment(id)),
 		tmp: () => join(cacheRoot, "tmp"),
 		tmpFile: (name) => join(cacheRoot, "tmp", assertSafeSegment(name)),
 		sessionKey: () => join(localRoot, ".session-key"),
+		seedRemovals: () => join(localRoot, "seed-removals.json"),
 		uploadStagingRoot: () => uploadStagingRootPath,
 		stagingPoolRoot: () => join(uploadStagingRootPath, "staging"),
 		stagingPoolFile: (fileId, ext) =>
@@ -456,13 +484,20 @@ export function createStoragePaths(
 }
 
 /**
- * Map a {@link LocalPaths.thumb} subjectKind onto its on-disk subdirectory.
- * Variants now live flat inside the per-id local directory (no enclosing
- * `thumbs/` parent), so `resource` -> `resources` and `character` ->
- * `characters` (both plural to match the storage layout convention).
+ * Map a {@link LocalPaths.localCover} subjectKind onto its on-disk
+ * subdirectory. Variants now live flat inside the per-id local directory
+ * (no enclosing `thumbs/` parent), so `resource` -> `resources`,
+ * `character` -> `characters`, `tag` -> `tags` (all plural to match the
+ * storage layout convention).
  */
-function localCoverSubjectDir(subjectKind: "resource" | "character"): string {
-	return subjectKind === "resource" ? "resources" : "characters"
+function localCoverSubjectDir(
+	subjectKind: "resource" | "character" | "tag",
+): string {
+	return subjectKind === "resource"
+		? "resources"
+		: subjectKind === "character"
+			? "characters"
+			: "tags"
 }
 
 /**

package/src/hoard/versioned-folder-ops.ts

@@ -3,6 +3,8 @@ import { extname, join } from "node:path"
 import type { StoragePaths } from "./paths.ts"
 import { writeVersioned } from "./write-versioned.ts"
 
+export type VersionedFolderSubjectKind = "resource" | "character" | "tag"
+
 export type VersionedFolderOps = {
 	/** Ensure the current-version entity folder exists. */
 	ensureFolder(id: string): Promise<void>
@@ -24,7 +26,7 @@ export type VersionedFolderOps = {
 }
 
 /**
- * The four lifecycle operations shared by the resource and character
+ * The four lifecycle operations shared by the resource, character and tag
  * file-system layers. They differ only in which versioned folder they
  * target and how the trash / placeholder names are derived.
  *
@@ -35,17 +37,38 @@ export type VersionedFolderOps = {
  * `readOnly` is a live `{ current: boolean }` ref (the server's runtime
  * read-only flag), so a version switch mid-request re-reads it.
  */
+const KIND_LAYOUT: Record<
+	VersionedFolderSubjectKind,
+	{
+		readonly trashPrefix: string
+		readonly deletedKind: "resources" | "characters" | "tags"
+	}
+> = {
+	resource: { trashPrefix: "resources-", deletedKind: "resources" },
+	character: { trashPrefix: "characters-", deletedKind: "characters" },
+	tag: { trashPrefix: "tags-", deletedKind: "tags" },
+}
+
 export function buildVersionedFolderOps(
 	paths: StoragePaths,
 	readOnly: { readonly current: boolean },
-	kind: "resource" | "character",
+	kind: VersionedFolderSubjectKind,
 ): VersionedFolderOps {
 	const folderOf =
 		(id: string) =>
-		(current: StoragePaths["latest"]): string =>
-			kind === "resource" ? current.resource(id) : current.character(id)
-	const trashPrefix = kind === "resource" ? "resources-" : "characters-"
-	const deletedKind = kind === "resource" ? "resources" : "characters"
+		(current: StoragePaths["latest"]): string => {
+			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: string): Promise<void> {
 		await writeVersioned(paths, readOnly.current, (current) =>

package/src/hooks.test.ts

@@ -526,3 +526,73 @@ describe("plugin hooks: imageHashes", () => {
 		).resolves.toBeUndefined()
 	})
 })
+
+describe("runInstallHook", () => {
+	const installEntry = (onInstall: PluginDefinition["onInstall"]) => ({
+		id: PAGES_ID,
+		manifest: manifestFor(PAGES_ID, "Pages"),
+		enabled: true,
+		priority: 50,
+		pinned: false,
+		color: "",
+		missing: false,
+		builtin: false,
+		dev: false,
+		plugin: { ...createPagesPlugin(), onInstall },
+	})
+
+	test("invokes onInstall with an install-scoped API (empty file surface)", async () => {
+		const seen: ResourceAPI[] = []
+		const hooks = createPluginHooks({
+			getRegistry: () =>
+				buildRegistry([
+					installEntry(async (api) => {
+						seen.push(api)
+					}),
+				]),
+		})
+
+		await hooks.runInstallHook(PAGES_ID)
+
+		expect(seen).toHaveLength(1)
+		expect(await seen[0]!.listFileNames()).toEqual([])
+		expect(seen[0]!.context.detect).toBeUndefined()
+	})
+
+	test("no-ops when the plugin declares no onInstall", async () => {
+		const hooks = createPluginHooks({
+			getRegistry: () => buildRegistry([installEntry(undefined)]),
+		})
+
+		await expect(hooks.runInstallHook(PAGES_ID)).resolves.toBeUndefined()
+	})
+
+	test("a throwing hook is logged and swallowed", async () => {
+		const warn = vi.spyOn(console, "warn").mockImplementation(() => {})
+		try {
+			const hooks = createPluginHooks({
+				getRegistry: () =>
+					buildRegistry([
+						installEntry(async () => {
+							throw new Error("boom")
+						}),
+					]),
+			})
+
+			await expect(hooks.runInstallHook(PAGES_ID)).resolves.toBeUndefined()
+			expect(warn).toHaveBeenCalledWith(
+				expect.stringContaining("onInstall failed for plugin"),
+			)
+		} finally {
+			warn.mockRestore()
+		}
+	})
+
+	test("an unknown plugin id is a no-op", async () => {
+		const hooks = createPluginHooks({
+			getRegistry: () => buildRegistry([]),
+		})
+
+		await expect(hooks.runInstallHook(PAGES_ID)).resolves.toBeUndefined()
+	})
+})

package/src/hooks.ts

@@ -6,6 +6,7 @@ import type {
 } from "@hoardodile/sdk-types"
 import type { PluginRegistry, PluginRegistryEntry } from "./api-types.ts"
 import { createCapabilityGuard } from "./capability-guard.ts"
+import { createInstallScopeApi } from "./install-api.ts"
 import type { Detection, ResourceAPI } from "./types.ts"
 
 /** Absolute cap of hash rows one resource may contribute (host policy). */
@@ -161,6 +162,18 @@ export type PluginHooks = {
 		api: ResourceAPI,
 		pluginId: PluginManifestId,
 	) => Promise<ImageHashesResult | undefined>
+	/**
+	 * Run the plugin's optional `onInstall` hook — best-effort, invoked
+	 * by the host after a successful install/update commit (marketplace
+	 * install/update or a zip upload; never seed/dev plugins). The hook
+	 * receives an install-scoped {@link ResourceAPI}: no resource is
+	 * attached (the file surface answers empty, `context.detect` is
+	 * `undefined`), while the asset methods still work and stay gated by
+	 * the shared consent dialog. A throwing (or consent-denied) hook is
+	 * logged via `hookFailureText` and swallowed — the install itself is
+	 * never failed; plugins must re-check at runtime.
+	 */
+	readonly runInstallHook: (pluginId: PluginManifestId) => Promise<void>
 }
 
 export function createPluginHooks(deps: PluginHooksDeps): PluginHooks {
@@ -364,6 +377,18 @@ export function createPluginHooks(deps: PluginHooksDeps): PluginHooks {
 		)
 	}
 
+	async function runInstallHook(pluginId: PluginManifestId): Promise<void> {
+		const entry = getRegistry().getById(pluginId)
+		if (entry === undefined) return
+		await invokeHook(
+			entry,
+			entry.plugin.onInstall,
+			createInstallScopeApi(),
+			"onInstall",
+			"warn",
+		)
+	}
+
 	return {
 		defaultPluginId,
 		getEffectiveEntry,
@@ -376,6 +401,7 @@ export function createPluginHooks(deps: PluginHooksDeps): PluginHooks {
 		runMetaHooks,
 		supportsImageHashes,
 		runImageHashes,
+		runInstallHook,
 	}
 }
 

package/src/index.ts

@@ -37,6 +37,7 @@ export {
 	createNestedCdCache,
 	listZipEntries,
 	materializeFile,
+	packZipDirectory,
 } from "./archive/index.ts"
 export type {
 	CapabilityGuard,

package/src/install-api.ts

@@ -0,0 +1,68 @@
+import { pluginAssetError } from "@hoardodile/sdk-types"
+import type { ResourceAPI } from "./types.ts"
+
+/**
+ * The ResourceAPI handed to a plugin's `onInstall` hook: there is no
+ * resource attached, so the file surface answers empty (or throws a
+ * clear "no resource" error) and `context.detect` is `undefined`.
+ *
+ * The asset surface stays honest: in the app server the sandbox
+ * intercepts these methods before the API object is consulted and
+ * routes them to the consent-gated asset service with the owning
+ * plugin id — the onInstall download flow is identical to the runtime
+ * one. In-process hosts (fixtures, dev runner, CLI) answer
+ * `UNAVAILABLE` exactly like every other host without a consent
+ * channel.
+ */
+export function createInstallScopeApi(): ResourceAPI {
+	const noResource = (method: string): Error =>
+		new Error(
+			`${method}() — no resource is attached to the onInstall hook; use the asset methods (download/statAsset/readAsset/deleteAsset) for install-time work`,
+		)
+	return {
+		logInfo() {},
+		logWarn() {},
+		logError() {},
+		context: { detect: undefined },
+		listFileNames: async () => [],
+		readFile: async () => {
+			throw noResource("readFile")
+		},
+		statFile: async () => undefined,
+		statFiles: async (paths) => paths.map(() => undefined),
+		sniff: async () => undefined,
+		probe: async () => ({ kind: "unknown", reason: "unavailable" }),
+		hashBytes: async () => {
+			throw noResource("hashBytes")
+		},
+		computeImageHashes: async () => undefined,
+		listContainer: async () => {
+			throw noResource("listContainer")
+		},
+		extractArchive: async () => {
+			throw noResource("extractArchive")
+		},
+		download: async () => {
+			throw pluginAssetError(
+				"UNAVAILABLE",
+				"download() — this host has no plugin asset service; only the app server host can download into the plugin vault",
+			)
+		},
+		statAsset: async () => {
+			throw unavailableAsset("statAsset")
+		},
+		readAsset: async () => {
+			throw unavailableAsset("readAsset")
+		},
+		deleteAsset: async () => {
+			throw unavailableAsset("deleteAsset")
+		},
+	}
+}
+
+function unavailableAsset(method: string): Error {
+	return pluginAssetError(
+		"UNAVAILABLE",
+		`${method}() — this host has no plugin asset vault; only the app server host manages vault files`,
+	)
+}