@hoardodile/workbench 0.0.0

package/dist/serve.d.mts

@@ -0,0 +1,156 @@
+import type { Server } from "node:http"
+import type { ImageVariantQuery } from "@hoardodile/sdk-types/image-variant"
+
+/**
+ * Server-side hook results captured against the selected resource. The
+ * workbench pushes these into the plugin iframe context so it renders
+ * exactly like the app does. Produced by `hoardodile plugin dev`; the
+ * workbench itself never runs a sandbox.
+ */
+export type WorkbenchHookSnapshot = {
+	readonly pluginId: string
+	readonly detect: {
+		readonly ok: boolean
+		readonly reasons?: readonly string[]
+	}
+	readonly sourceMeta: unknown
+	readonly searchMeta: unknown
+	readonly coverLocal: string | undefined
+	readonly files: readonly unknown[] | undefined
+	readonly fileStats: {
+		readonly count?: number
+		readonly sizeBytes?: number
+	}
+	readonly imageHashes?: readonly unknown[]
+	readonly errors: Readonly<Record<string, string>>
+	readonly capturedAt: number
+}
+
+/** A resource the workbench can open, as shown in the picker. */
+export type WorkbenchResource = {
+	readonly id: string
+	readonly name: string
+	/** Plugin that owns the resource in the source library, when known. */
+	readonly contentPluginId?: string
+	readonly fileVersion?: number
+}
+
+/**
+ * The plugin-visible slice of a resource's stored state. Used to seed
+ * the offline mock host so comments, danmaku, preferences and the
+ * per-resource cache are the ones the plugin would really see. Writes
+ * never leave the mock.
+ */
+export type WorkbenchResourceState = {
+	readonly name?: string
+	readonly messages?: readonly unknown[]
+	readonly danmaku?: readonly unknown[]
+	readonly prefs?: Readonly<Record<string, string>>
+	readonly cache?: Readonly<Record<string, string>>
+}
+
+/** Bytes (or a cached path) plus the content type to serve them as. */
+export type WorkbenchRendered = {
+	readonly contentType: string
+	readonly bytes?: Uint8Array
+	readonly path?: string
+}
+
+/** Read-only file access for the selected resource. */
+export type WorkbenchFileProvider = {
+	readonly list: (
+		resId: string,
+	) => Promise<readonly string[]> | readonly string[]
+	readonly stat: (
+		resId: string,
+		path: string,
+	) =>
+		| Promise<{ readonly sizeBytes: number } | undefined>
+		| { readonly sizeBytes: number }
+		| undefined
+	readonly read: (
+		resId: string,
+		path: string,
+	) => Promise<Uint8Array | undefined> | Uint8Array | undefined
+}
+
+/**
+ * Everything the workbench page can ask for. Each is optional: without
+ * a `preview` provider `?size=preview` (and the generic variant
+ * parameters) falls back to the original bytes, without `frame` the
+ * seek-preview route stays unmounted.
+ */
+export type WorkbenchProviders = {
+	readonly resources: () =>
+		| Promise<readonly WorkbenchResource[]>
+		| readonly WorkbenchResource[]
+	readonly files?: WorkbenchFileProvider
+	readonly snapshot?: (
+		resId: string,
+	) =>
+		| Promise<WorkbenchHookSnapshot | undefined>
+		| WorkbenchHookSnapshot
+		| undefined
+	readonly state?: (
+		resId: string,
+	) =>
+		| Promise<WorkbenchResourceState | undefined>
+		| WorkbenchResourceState
+		| undefined
+	readonly preview?: (
+		resId: string,
+		path: string,
+		/**
+		 * The file route's raw variant query (`size`, `fmt`, `fit`,
+		 * `area`, `q`) — parsed and validated by the provider, so the
+		 * workbench mount itself stays dependency-free.
+		 */
+		variant?: ImageVariantQuery,
+	) => Promise<WorkbenchRendered | undefined>
+	readonly frame?: (
+		resId: string,
+		path: string,
+		timeMs: number,
+	) => Promise<WorkbenchRendered | undefined>
+}
+
+/** Options for {@link serveWorkbench}. */
+export type ServeWorkbenchOptions = {
+	/** Built plugin dist dir mounted at `/plugin` (manifest + index.html). */
+	readonly pluginDir?: string
+	/**
+	 * Data root exposed as a single resource. Shorthand for the
+	 * directory providers; ignored when `providers` is given.
+	 */
+	readonly dataDir?: string
+	/** Real data sources. `hoardodile plugin dev` supplies these. */
+	readonly providers?: WorkbenchProviders
+	/**
+	 * Latest hook snapshot. Called per request so a watch-driven
+	 * recapture is picked up without restarting. Merged into
+	 * `providers` when both are given.
+	 */
+	readonly snapshot?: (
+		resId: string,
+	) =>
+		| Promise<WorkbenchHookSnapshot | undefined>
+		| WorkbenchHookSnapshot
+		| undefined
+	/** Port to listen on. Defaults to 5199. */
+	readonly port?: number
+	/** Bind host. Defaults to 127.0.0.1. */
+	readonly host?: string
+}
+
+/**
+ * Serve the published workbench SPA with the plugin bundle and the
+ * resource data mounted read-only. Resolves once the server is
+ * listening.
+ */
+export function serveWorkbench(opts: ServeWorkbenchOptions): Promise<Server>
+
+/** Providers over one plain directory, standing in for a single resource. */
+export function createDirectoryProviders(
+	dataDir: string,
+	resId?: string,
+): WorkbenchProviders

package/dist/serve.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+/**
+ * Standalone server for the published workbench bundle: the prebuilt SPA
+ * from `dist/` plus the read-only mounts the page needs at runtime. The
+ * routing itself lives in `mounts.mjs`, shared with the vite dev server
+ * so the two can never drift.
+ *
+ * Usage:
+ *   node serve.mjs --plugin <plugin-dist-dir> --data <data-dir> [--port 5199]
+ *                  [--snapshot <hooks.json>]
+ *
+ * Also exported so the plugin CLI's `dev` subcommand can serve the
+ * workbench with richer providers (real storage, preview variants,
+ * video frames): `import { serveWorkbench } from "@hoardodile/workbench"`.
+ */
+import { existsSync, readFileSync, statSync } from "node:fs"
+import { createServer } from "node:http"
+import { dirname, join, resolve, sep } from "node:path"
+import { fileURLToPath } from "node:url"
+import {
+	contentTypeOf,
+	createDirectoryProviders,
+	createWorkbenchMounts,
+} from "./mounts.mjs"
+
+const DIST_DIR = resolve(dirname(fileURLToPath(import.meta.url)))
+
+/**
+ * Serve the published workbench on `port`. Pass `providers` for real
+ * data (the CLI does), or `dataDir` for the plain-directory default.
+ * Returns the http.Server.
+ */
+export function serveWorkbench(opts) {
+	const { pluginDir, dataDir, port = 5199, host = "127.0.0.1" } = opts
+	if (pluginDir === undefined) {
+		console.warn("[workbench] no plugin dir — pass --plugin <dist-dir>")
+	}
+	const base =
+		opts.providers ??
+		(dataDir === undefined
+			? { resources: () => [] }
+			: createDirectoryProviders(dataDir))
+	if (opts.providers === undefined && dataDir === undefined) {
+		console.warn("[workbench] no data dir — pass --data <data-dir>")
+	}
+	// A snapshot provider passed on its own (the classic `--snapshot`
+	// shape) still works: it is just one more provider.
+	const providers =
+		opts.snapshot === undefined ? base : { ...base, snapshot: opts.snapshot }
+
+	// Plugin asset vault: the dev server performs the user-consented
+	// downloads (browser fetch would hit CORS) into this local scratch
+	// root. The CLI passes `<pluginDir>/.hoardodile/vault`; the
+	// standalone default sits next to the data dir.
+	const vaultRoot =
+		opts.vaultRoot ?? join(resolve(dataDir ?? "."), ".workbench-vault")
+
+	const mounts = createWorkbenchMounts({
+		pluginDir,
+		providers,
+		vault: vaultRoot,
+	})
+
+	const server = createServer((req, res) => {
+		void (async () => {
+			try {
+				for (const mount of mounts) {
+					if (await mount(req, res)) return
+				}
+				serveSpa(req, res)
+			} catch (err) {
+				console.error("[workbench] request failed:", err)
+				if (!res.headersSent) res.statusCode = 500
+				res.end("workbench error")
+			}
+		})()
+	})
+
+	return new Promise((resolveStart) => {
+		server.listen(port, host, () => {
+			console.log(`[workbench] serving on http://${host}:${port}`)
+			resolveStart(server)
+		})
+	})
+}
+
+function serveSpa(req, res) {
+	const url = new URL(req.url ?? "/", "http://workbench.local")
+	if (url.pathname === "/") {
+		res.setHeader("content-type", "text/html; charset=utf-8")
+		res.end(readFileSync(join(DIST_DIR, "index.html")))
+		return
+	}
+	const rel = decodeURIComponent(url.pathname).replace(/^\/+/, "")
+	const abs = resolve(DIST_DIR, rel)
+	if (
+		abs === DIST_DIR ||
+		!abs.startsWith(DIST_DIR + sep) ||
+		!existsSync(abs) ||
+		statSync(abs).isDirectory()
+	) {
+		res.statusCode = 404
+		res.end("not found")
+		return
+	}
+	res.setHeader("content-type", contentTypeOf(abs))
+	res.end(readFileSync(abs))
+}
+
+// CLI entry when run directly.
+const isMain =
+	process.argv[1] !== undefined &&
+	resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+if (isMain) {
+	const args = process.argv.slice(2)
+	const flagValue = (name) => {
+		const i = args.indexOf(name)
+		return i !== -1 ? args[i + 1] : undefined
+	}
+	const snapshotPath = flagValue("--snapshot")
+	// Re-read on every request: a `plugin dev` style watcher may rewrite
+	// the file as the plugin rebuilds.
+	const snapshot =
+		snapshotPath === undefined
+			? undefined
+			: () => {
+					try {
+						return JSON.parse(readFileSync(resolve(snapshotPath), "utf8"))
+					} catch {
+						return undefined
+					}
+				}
+	await serveWorkbench({
+		pluginDir: flagValue("--plugin"),
+		dataDir: flagValue("--data"),
+		port: Number(flagValue("--port") ?? 5199),
+		snapshot,
+	})
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@hoardodile/workbench",
+  "version": "0.0.0",
+  "license": "MIT",
+  "description": "Offline dev workbench for hoardodile content plugins.",
+  "keywords": [
+    "hoardodile",
+    "plugin",
+    "workbench",
+    "dev",
+    "mock"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hoardodile/hoardodile.git",
+    "directory": "plugins/workbench"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/serve.d.mts",
+      "default": "./dist/serve.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.62.1",
+    "@rolldown/plugin-babel": "^0.2.3",
+    "@tailwindcss/vite": "^4.3.3",
+    "@types/node": "^26.2.0",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.4",
+    "@vitejs/plugin-react": "^6.1.0",
+    "babel-plugin-react-compiler": "^1.0.0",
+    "i18next": "^26.4.0",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "react-i18next": "^17.0.12",
+    "tailwindcss": "^4.3.3",
+    "typescript": "^7.0.2",
+    "vite": "^8.2.2",
+    "vitest": "^4.1.11",
+    "zod": "^4.4.3",
+    "@hoardodile/host-web": "0.0.0",
+    "@hoardodile/ui": "0.0.0",
+    "@hoardodile/i18n": "0.0.0",
+    "@hoardodile/sdk-web": "0.0.0",
+    "@hoardodile/sdk-types": "0.0.0"
+  },
+  "scripts": {
+    "dev": "node scripts/dev.mjs",
+    "build": "vite build && node scripts/copy-serve.mjs",
+    "lint": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}