@hoardodile/host 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hoardodile/host",
-  "version": "0.1.2",
+  "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.2"
+    "@hoardodile/sdk-types": "0.1.3"
   },
   "optionalDependencies": {
     "@derhuerst/ffprobe-static": "^5.3.0",

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.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>`. */
@@ -356,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"),
@@ -401,6 +419,7 @@ 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"),
@@ -465,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/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`,
+	)
+}

package/src/sandbox/host.ts

@@ -337,7 +337,14 @@ export function createPluginSandbox(
 			await teardownChild(previous)
 		}
 		if (!opts.eager) {
-			void teardownChild(state)
+			// AWAITED, not fire-and-forget: the hook list was probed by
+			// this load, and the loader returns the sandboxed definition
+			// the moment we resolve. A caller that invokes a hook
+			// immediately after (e.g. the post-install `onInstall`) must
+			// not find a half-alive child: `ensureLoaded` would see the
+			// not-yet-torn-down child and post its invocation into a
+			// dying process (rejected as "worker stopped").
+			await teardownChild(state)
 		}
 		return createSandboxedPlugin(state.hooks ?? ["detect"], (hook, api) =>
 			invoke(state, hook, api),
@@ -611,6 +618,28 @@ export function createPluginSandbox(
 			throw new Error(`plugin ${state.id} sandbox unavailable`)
 		}
 
+		try {
+			return await invokeOnChild(state, child, hook, api)
+		} finally {
+			// An install hook is one-shot and the host may immediately
+			// re-commit the same plugin (an update): a kept-alive worker
+			// holding the plugin directory (Windows keeps directory ops
+			// pinned while a child is alive) would make the vault-move
+			// during the next commit fail with EPERM. Drop the child right
+			// after an `onInstall`; the next invocation respawns it.
+			if (hook === "onInstall") {
+				state.respawnTimes = []
+				await teardownChild(state)
+			}
+		}
+	}
+
+	function invokeOnChild(
+		state: PluginState,
+		child: ChildProcess,
+		hook: HookName,
+		api: ResourceAPI,
+	): Promise<unknown> {
 		const callId = nextCallId++
 		return new Promise((resolveCall, reject) => {
 			const call: PendingCall = {

package/src/sandbox/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
 	}