@hoardodile/host 0.0.0

package/src/directory-api.ts

@@ -0,0 +1,42 @@
+import type { PluginSchema } from "@hoardodile/sdk-types"
+import { PLUGIN_READ_FILE_MAX_BYTES } from "@hoardodile/sdk-types/plugin"
+import { createPluginResourceAPI } from "./api.ts"
+import { createDirectoryContainer } from "./directory-container.ts"
+import type { ResourceAPI } from "./types.ts"
+
+/**
+ * Create a minimal {@link ResourceAPI} backed by a raw filesystem
+ * directory. Used to run plugin hooks against a plain directory — during
+ * import, before resources exist, or from the CLI. Built on the shared
+ * {@link createPluginResourceAPI} so directory behavior matches the
+ * archive-backed and fixture backends; probes are unsupported and resolve
+ * to `undefined`.
+ */
+export function createDirectoryResourceAPI<
+	TSchema extends PluginSchema = PluginSchema,
+>(
+	dir: string,
+	opts: {
+		readonly maxReadFileBytes?: number
+		/**
+		 * Writable directory for `extractArchive` materialization (the
+		 * CLI passes a temp dir). Virtual-path reads (`outer!inner`) work
+		 * without it; only the materializing hook needs it.
+		 */
+		readonly extractCacheDir?: string
+		/**
+		 * Session context handed to hooks as `api.context.detect` (see
+		 * `CreatePluginResourceAPIDeps.detectContext`).
+		 */
+		readonly detectContext?: unknown
+	} = {},
+): ResourceAPI<TSchema> {
+	return createPluginResourceAPI<TSchema>({
+		view: createDirectoryContainer(dir),
+		maxReadFileBytes: opts.maxReadFileBytes ?? PLUGIN_READ_FILE_MAX_BYTES,
+		extractCacheDir: opts.extractCacheDir,
+		detectContext: opts.detectContext,
+	})
+}
+
+export { resolveSafeImportPath } from "./directory-container.ts"

package/src/directory-container.ts

@@ -0,0 +1,141 @@
+import { createReadStream } from "node:fs"
+import { open, readdir, stat } from "node:fs/promises"
+import { isAbsolute, join, normalize, resolve, sep } from "node:path"
+import type { Readable } from "node:stream"
+import type { ResourceContainer } from "./container.ts"
+import {
+	naturalSort,
+	orderEntries,
+	readOrderManifest,
+} from "./hoard/order-manifest.ts"
+
+/**
+ * A {@link ResourceContainer} over a raw filesystem directory. Used to
+ * run plugin hooks against a plain directory — during import, before
+ * resources exist, or from the CLI. Reads only; the directory is treated
+ * as an immutable snapshot for the container's lifetime.
+ */
+export function createDirectoryContainer(dir: string): ResourceContainer {
+	async function resolvePath(relPath: string): Promise<string> {
+		return resolveSafeImportPath(dir, relPath)
+	}
+
+	return {
+		async listEntries(): Promise<readonly string[]> {
+			const out: string[] = []
+			async function collect(current: string, prefix: string): Promise<void> {
+				const entries = await readdir(join(dir, current), {
+					withFileTypes: true,
+				}).catch(() => [] as readonly never[])
+				for (const e of entries) {
+					if (e.name.startsWith(".")) continue
+					if (e.name.includes(".uploading-")) continue
+					// Entry names always use `/` separators, mirroring zip
+					// entry names, regardless of the platform's separator.
+					const rel = prefix ? `${prefix}/${e.name}` : e.name
+					if (e.isDirectory()) {
+						await collect(join(current, e.name), rel)
+					} else if (e.isFile()) {
+						out.push(rel)
+					}
+				}
+			}
+			await collect(".", "")
+			// An explicit order manifest wins when it validates against
+			// this listing; otherwise fall back to the natural name sort.
+			const manifest = await readOrderManifest(dir)
+			if (manifest !== undefined) {
+				const ordered = orderEntries(manifest, out)
+				if (ordered !== undefined) return ordered
+			}
+			return naturalSort(out)
+		},
+
+		async readEntry(relPath: string): Promise<Buffer> {
+			const safe = await resolvePath(relPath)
+			const handle = await open(safe, "r")
+			try {
+				return await handle.readFile()
+			} finally {
+				await handle.close()
+			}
+		},
+
+		async readEntrySlice(
+			relPath: string,
+			start: number,
+			end: number,
+		): Promise<Buffer> {
+			const safe = await resolvePath(relPath)
+			const handle = await open(safe, "r")
+			try {
+				const { size } = await handle.stat()
+				const clampedStart = Math.min(Math.max(0, start), size)
+				const clampedEnd = Math.min(Math.max(clampedStart, end), size)
+				const length = Math.max(0, clampedEnd - clampedStart)
+				if (length === 0) return Buffer.alloc(0)
+				const buf = Buffer.alloc(length)
+				await handle.read(buf, 0, length, clampedStart)
+				return buf
+			} finally {
+				await handle.close()
+			}
+		},
+
+		async openEntryStream(relPath: string): Promise<{
+			readonly stream: Readable
+			readonly size: number
+			readonly mtimeMs?: number
+			readonly path?: string
+		}> {
+			const safe = await resolvePath(relPath)
+			const info = await stat(safe)
+			return {
+				stream: createReadStream(safe),
+				size: info.size,
+				mtimeMs: info.mtimeMs,
+				path: safe,
+			}
+		},
+
+		async resolveByteRange(
+			relPath: string,
+		): Promise<{ readonly size: number } | undefined> {
+			const safe = await resolvePath(relPath)
+			const info = await stat(safe).catch(() => undefined)
+			return info === undefined ? undefined : { size: info.size }
+		},
+
+		async resolveSeekablePath(relPath: string): Promise<string | undefined> {
+			const safe = await resolvePath(relPath)
+			const info = await stat(safe).catch(() => undefined)
+			return info?.isFile() === true ? safe : undefined
+		},
+	}
+}
+
+/**
+ * Resolve a plugin-supplied relative path against an import directory,
+ * rejecting attempts to escape the directory or use absolute paths.
+ */
+export function resolveSafeImportPath(dir: string, relPath: string): string {
+	if (relPath.length === 0) {
+		throw new Error("path is empty")
+	}
+	if (relPath.includes("\0")) {
+		throw new Error("path contains null byte")
+	}
+	if (isAbsolute(relPath)) {
+		throw new Error("absolute paths are not allowed")
+	}
+	const normalized = normalize(relPath)
+	if (normalized.startsWith("..") || normalized === "..") {
+		throw new Error("path escapes import directory")
+	}
+	const root = resolve(dir)
+	const candidate = resolve(root, normalized)
+	if (candidate !== root && !candidate.startsWith(root + sep)) {
+		throw new Error("path escapes import directory")
+	}
+	return candidate
+}

package/src/discovery.ts

@@ -0,0 +1,295 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs"
+import { join, resolve } from "node:path"
+import type { PluginManifest, PluginManifestId } from "@hoardodile/sdk-types"
+import { pluginManifest as pluginManifestSchema } from "@hoardodile/sdk-types/schema"
+import type { FoundPlugin, MissingPlugin } from "./api-types.ts"
+import type { PluginSettingsStore } from "./settings-store.ts"
+
+/**
+ * Default pin for plugins with no settings row yet (first install /
+ * clean state / builtin). Pinned plugins wear their name on resource
+ * cards so the type stays readable without a cover.
+ */
+const DEFAULT_PLUGIN_PINNED = true
+
+/** Default first-install priority — reorderable from the UI afterwards. */
+const DEFAULT_PLUGIN_PRIORITY = 100
+
+export type PluginDiscoveryDeps = {
+	/** Directory of the mandatory builtin plugin (`manifest.json` at its root). */
+	readonly builtinDir?: string
+	/** Extra plugin directories for development (override same-id disk plugins). */
+	readonly devPluginDirs?: readonly string[]
+	/** Directory where installed plugins live, one subdirectory per plugin. */
+	readonly pluginsDir: string
+	/** DB-backed per-plugin settings (enabled/priority/pinned/color). */
+	readonly settings: PluginSettingsStore
+	/** Skip dev plugins entirely (e.g. production configuration). */
+	readonly disableDevPlugins?: boolean
+}
+
+/**
+ * Plugin discovery: finds plugins on disk (builtin, dev, installed),
+ * merges their DB settings, and reports which known plugins are missing.
+ */
+export type PluginDiscovery = {
+	readonly discover: () => Promise<{
+		found: FoundPlugin[]
+		missing: MissingPlugin[]
+	}>
+}
+
+/**
+ * Create the discovery pipeline. Order matters: the builtin plugin wins
+ * priority, dev plugins override same-id installed ones, and anything in
+ * settings but absent from disk is reported missing.
+ */
+export function createPluginDiscovery(
+	deps: PluginDiscoveryDeps,
+): PluginDiscovery {
+	// The first loadAll runs at boot: a broken builtin there is a config
+	// error that should fail fast. Later (re)scans degrade gracefully —
+	// the loader keeps the previous registry when discovery throws.
+	let firstLoad = true
+
+	async function discover(): Promise<{
+		found: FoundPlugin[]
+		missing: MissingPlugin[]
+	}> {
+		const found: FoundPlugin[] = []
+		// Every discovered id, across all sources. Guarantees each plugin
+		// id is activated exactly once — a duplicate would make activation
+		// dispose the first worker while the registry still references it
+		// (every hook then fails with "sandbox disposed").
+		const seen = new Set<PluginManifestId>()
+
+		// 1. Builtin plugin — its id is reserved; dev/disk copies are skipped.
+		if (deps.builtinDir !== undefined) {
+			const builtin = discoverBuiltin(deps.builtinDir, firstLoad)
+			if (builtin !== undefined) {
+				found.push(builtin)
+				seen.add(builtin.id)
+			}
+		}
+		firstLoad = false
+
+		// 2. Dev plugins. Same-id dev dirs override each other (later wins,
+		//    matching the dev-over-disk precedence); the earlier entry is
+		//    replaced so activation never loads the same id twice.
+		const dev = discoverDevPlugins(
+			deps.devPluginDirs,
+			deps.settings,
+			deps.disableDevPlugins ?? false,
+		)
+		for (const plugin of dev) {
+			if (seen.has(plugin.id)) {
+				const index = found.findIndex((f) => f.id === plugin.id)
+				if (index !== -1 && found[index]?.source === "dev") {
+					// Duplicate dev dir — the later one wins.
+					found[index] = plugin
+					console.warn(
+						`[plugin-discovery] dev plugin ${plugin.id} (${plugin.manifest.name ?? plugin.id}) overrides an earlier dev dir entry`,
+					)
+				} else {
+					console.warn(
+						`[plugin-discovery] skipping dev plugin ${plugin.id}: id is reserved by the builtin plugin`,
+					)
+				}
+				continue
+			}
+			found.push(plugin)
+			seen.add(plugin.id)
+		}
+
+		// 3. Disk plugins, skipping ids overridden by dev or the builtin.
+		const disk = discoverDiskPlugins(deps.pluginsDir, deps.settings)
+		for (const plugin of disk) {
+			if (seen.has(plugin.id)) {
+				console.warn(
+					`[plugin-discovery] skipping disk plugin ${plugin.id}: id already registered (builtin or dev plugin)`,
+				)
+				continue
+			}
+			found.push(plugin)
+			seen.add(plugin.id)
+		}
+
+		// 4. Missing plugins (settings-only)
+		const missing = discoverMissingPlugins(deps.settings, seen)
+
+		return { found, missing }
+	}
+
+	return { discover }
+}
+
+function discoverBuiltin(
+	builtinDir: string,
+	failFast: boolean,
+): FoundPlugin | undefined {
+	const resolved = resolve(builtinDir)
+	const manifest = parseManifest(resolved, "builtin")
+	if (manifest === undefined) {
+		const message =
+			`Builtin plugin not found or invalid at ${resolved}. ` +
+			"Set BUILTIN_PATH env to a valid plugin directory."
+		if (failFast) {
+			throw new Error(message)
+		}
+		console.error(`[plugin-discovery] ${message}`)
+		return undefined
+	}
+	return {
+		id: manifest.id,
+		manifest,
+		diskPath: resolved,
+		source: "builtin",
+		enabled: true,
+		priority: Number.MAX_SAFE_INTEGER,
+		pinned: DEFAULT_PLUGIN_PINNED,
+		color: "",
+	}
+}
+
+function discoverDevPlugins(
+	devPluginDirs: readonly string[] | undefined,
+	settings: PluginSettingsStore,
+	disableDevPlugins: boolean,
+): FoundPlugin[] {
+	if (disableDevPlugins) {
+		console.info("[plugin-discovery] dev plugins disabled by configuration")
+		return []
+	}
+	if (devPluginDirs === undefined || devPluginDirs.length === 0) return []
+
+	const results: FoundPlugin[] = []
+	for (const dir of devPluginDirs) {
+		const resolved = resolve(dir)
+		const manifest = parseManifest(resolved, "dev")
+		if (manifest === undefined) continue
+
+		const row = settings.get(manifest.id)
+
+		results.push({
+			id: manifest.id,
+			manifest,
+			diskPath: resolved,
+			source: "dev",
+			enabled: true,
+			priority: row?.priority ?? DEFAULT_PLUGIN_PRIORITY,
+			pinned: row?.pinned ?? DEFAULT_PLUGIN_PINNED,
+			color: row?.color ?? "",
+		})
+	}
+	return results
+}
+
+function discoverDiskPlugins(
+	pluginsDir: string,
+	settings: PluginSettingsStore,
+): FoundPlugin[] {
+	if (!existsSync(pluginsDir)) return []
+
+	const dirents = readdirSync(pluginsDir, { withFileTypes: true })
+	if (dirents.length === 0) return []
+
+	const results: FoundPlugin[] = []
+	for (const dirent of dirents) {
+		if (!dirent.isDirectory()) continue
+		const dirPath = join(pluginsDir, dirent.name)
+
+		const manifest = parseManifest(dirPath, dirent.name)
+		if (manifest === undefined) continue
+
+		const row = settings.get(manifest.id)
+		const enabled = row?.enabled ?? true
+		const priority = row?.priority ?? DEFAULT_PLUGIN_PRIORITY
+		const pinned = row?.pinned ?? DEFAULT_PLUGIN_PINNED
+		const color = row?.color ?? ""
+
+		results.push({
+			id: manifest.id,
+			manifest,
+			diskPath: dirPath,
+			source: "disk",
+			enabled,
+			priority,
+			pinned,
+			color,
+		})
+	}
+	return results
+}
+
+function discoverMissingPlugins(
+	settings: PluginSettingsStore,
+	loadedIds: ReadonlySet<PluginManifestId>,
+): MissingPlugin[] {
+	const results: MissingPlugin[] = []
+	for (const row of settings.all()) {
+		if (loadedIds.has(row.id)) continue
+		let manifest: PluginManifest
+		try {
+			manifest = JSON.parse(row.manifest) as PluginManifest
+		} catch {
+			continue
+		}
+		results.push({
+			id: row.id,
+			manifest,
+			enabled: row.enabled,
+			priority: row.priority,
+			pinned: row.pinned,
+			color: row.color,
+		})
+	}
+	return results
+}
+
+/**
+ * Read and validate `manifest.json` in `dirPath` against the zod
+ * contract. Logs a warning and returns `undefined` for every failure
+ * mode (missing file, unreadable, invalid JSON, schema violation) so
+ * callers can skip the directory without crashing the scan.
+ */
+export function parseManifest(
+	dirPath: string,
+	dirName: string,
+): PluginManifest | undefined {
+	const manifestPath = join(dirPath, "manifest.json")
+	if (!existsSync(manifestPath)) {
+		console.warn(`[plugin-discovery] skipping ${dirName}: no manifest.json`)
+		return undefined
+	}
+
+	let raw: string
+	try {
+		raw = readFileSync(manifestPath, "utf-8")
+	} catch {
+		console.warn(
+			`[plugin-discovery] skipping ${dirName}: cannot read manifest.json`,
+		)
+		return undefined
+	}
+
+	let parsed: unknown
+	try {
+		parsed = JSON.parse(raw)
+	} catch {
+		console.warn(
+			`[plugin-discovery] skipping ${dirName}: manifest is not valid JSON`,
+		)
+		return undefined
+	}
+
+	const result = pluginManifestSchema.safeParse(parsed)
+	if (!result.success) {
+		console.warn(
+			`[plugin-discovery] skipping ${dirName}: invalid manifest`,
+			result.error,
+		)
+		return undefined
+	}
+
+	return result.data
+}

package/src/errors.ts

@@ -0,0 +1,74 @@
+/**
+ * Host-local domain error. Mirrors the wire-format taxonomy of the app's
+ * domain errors (`@hoardodile/shared`) so errors raised here keep their
+ * code/kind/details across the package boundary — the server's error
+ * translation recognizes this shape structurally via `isDomainError`.
+ *
+ * The host deliberately keeps its dependency graph minimal (consts +
+ * sdk-types only) and does not depend on `@hoardodile/shared`; the
+ * mirror is kept in sync by the bridge test in
+ * `apps/server/src/infra/host-errors.test.ts`.
+ */
+export const domainErrorCodes = [
+	"NOT_FOUND",
+	"CONFLICT",
+	"VALIDATION",
+	"UNAUTHORIZED",
+	"FORBIDDEN",
+	"RATE_LIMITED",
+	"UNSUPPORTED",
+	"INTERNAL",
+] as const
+
+export type DomainErrorCode = (typeof domainErrorCodes)[number]
+
+/**
+ * Host-local domain error carrying a wire-compatible code/kind/details
+ * triple. Thrown by host services (containers, loaders, hooks) so the
+ * server can translate them into its own domain errors verbatim.
+ */
+export class DomainError extends Error {
+	readonly code: DomainErrorCode
+	readonly kind: string
+	readonly details?: Readonly<Record<string, unknown>>
+
+	constructor(
+		code: DomainErrorCode,
+		kind: string,
+		message: string,
+		details?: Readonly<Record<string, unknown>>,
+	) {
+		super(message)
+		this.name = "DomainError"
+		this.code = code
+		this.kind = kind
+		if (details !== undefined) this.details = details
+	}
+}
+
+/** Convenience constructor for `VALIDATION` errors. */
+export function invalid(
+	kind: string,
+	message: string,
+	details?: Readonly<Record<string, unknown>>,
+): DomainError {
+	return new DomainError("VALIDATION", kind, message, details)
+}
+
+/** Convenience constructor for `CONFLICT` errors. */
+export function conflict(
+	kind: string,
+	message: string,
+	details?: Readonly<Record<string, unknown>>,
+): DomainError {
+	return new DomainError("CONFLICT", kind, message, details)
+}
+
+/** Convenience constructor for `NOT_FOUND` errors. */
+export function notFound(
+	kind: string,
+	message: string,
+	details?: Readonly<Record<string, unknown>>,
+): DomainError {
+	return new DomainError("NOT_FOUND", kind, message, details)
+}

package/src/fixtures.ts

@@ -0,0 +1,8 @@
+/**
+ * The ResourceAPI fixtures now live in `@hoardodile/sdk-types` — the
+ * shared contract (see `plugin-definition.ts` there). This module keeps
+ * the module path so internal imports stay untouched.
+ */
+
+export type { ResourceAPIFixtureConfig } from "@hoardodile/sdk-types"
+export { createResourceAPIFixture, stubLogger } from "@hoardodile/sdk-types"