@hoardodile/host 0.0.0

package/src/contract/suite.ts

@@ -0,0 +1,205 @@
+import { afterAll, describe, expect, test } from "vitest"
+import type { ResourceAPI } from "../types.ts"
+
+/**
+ * Shared contract suite for the container-backed {@link ResourceAPI}
+ * implementations. Every backend (in-memory fixture, directory, zip
+ * archive, and the server's own artifact view) must behave identically:
+ * same entries, same bytes, same clamping, same probe semantics.
+ *
+ * Consumers build each backend from a declarative file map, then run the
+ * whole suite with `containerContractSuite([...])` inside a test file.
+ */
+
+/** A declarative container case: entry name → content. */
+export type ContainerContractCase = {
+	readonly name: string
+	readonly files: Readonly<Record<string, string | Uint8Array>>
+}
+
+export const CONTAINER_CONTRACT_CASES: readonly ContainerContractCase[] = [
+	{ name: "empty container", files: {} },
+	{
+		name: "flat files",
+		files: { "a.txt": "alpha", "b.bin": "beta", "c.jpg": "gamma" },
+	},
+	{
+		name: "nested entry names",
+		files: { "dir/a.txt": "nested a", "dir/sub/b.txt": "nested b" },
+	},
+	{
+		name: "binary content",
+		files: { "blob.bin": Uint8Array.from([0, 1, 2, 250, 255, 128]) },
+	},
+	{ name: "empty entry", files: { "empty.txt": "" } },
+	{
+		name: "unicode entry names",
+		files: { "Фото/я.jpg": "unicode" },
+	},
+]
+
+export type ContractBackend = {
+	readonly name: string
+	/**
+	 * Build a {@link ResourceAPI} from a declarative file map. Called
+	 * once per case; must produce an independent instance each time.
+	 */
+	readonly build: (
+		files: Readonly<Record<string, string | Uint8Array>>,
+	) => Promise<ResourceAPI>
+	/** Optional teardown for resources created by `build` calls. */
+	readonly cleanup?: () => Promise<void> | void
+}
+
+function toBytes(content: string | Uint8Array): Uint8Array {
+	return typeof content === "string"
+		? new TextEncoder().encode(content)
+		: content
+}
+
+async function collectManifest(api: ResourceAPI): Promise<unknown> {
+	const files = [...(await api.listFileNames())].sort()
+	const manifest: Record<string, unknown> = {}
+	manifest.files = files
+	for (const name of files) {
+		manifest[`stat:${name}`] = await api.statFile(name)
+		manifest[`read:${name}`] = Array.from(await api.readFile(name))
+		manifest[`range:${name}`] = Array.from(
+			await api.readFile(name, { start: 1, end: 3 }),
+		)
+		// Identification must agree across backends too — the sniffer
+		// reads through the same container abstraction.
+		manifest[`type:${name}`] = await api.sniff(name)
+		manifest[`probe:${name}`] = await api.probe(name)
+	}
+	// Batch stat: positions preserved, missing entries undefined.
+	const batched = await api.statFiles(files)
+	manifest.statAll = files.map((name, i) => ({
+		name,
+		stat: batched[i],
+	}))
+	manifest.missingStat = await api.statFile("missing-entry.bin")
+	manifest.missingStatAll = await api.statFiles(["missing-entry.bin"])
+	return manifest
+}
+
+/**
+ * Run the full container contract suite against the given backends.
+ * Must be called from within a vitest test file.
+ */
+export function containerContractSuite(
+	backends: readonly ContractBackend[],
+): void {
+	afterAll(async () => {
+		await Promise.all(backends.map((b) => b.cleanup?.()))
+	})
+
+	describe("container contract", () => {
+		for (const backend of backends) {
+			describe(backend.name, () => {
+				for (const c of CONTAINER_CONTRACT_CASES) {
+					test(`case "${c.name}": core semantics`, async () => {
+						const api = await backend.build(c.files)
+						const names = Object.keys(c.files)
+
+						expect([...(await api.listFileNames())].sort()).toEqual(
+							[...names].sort(),
+						)
+
+						for (const name of names) {
+							const content = c.files[name]
+							if (content === undefined) continue
+							const expected = toBytes(content)
+							expect(Array.from(await api.readFile(name))).toEqual([
+								...expected,
+							])
+
+							const mid = await api.readFile(name, {
+								start: 1,
+								end: Math.min(3, expected.length),
+							})
+							expect(Array.from(mid)).toEqual([
+								...expected.slice(1, Math.min(3, expected.length)),
+							])
+
+							const past = await api.readFile(name, {
+								start: expected.length + 5,
+								end: expected.length + 9,
+							})
+							expect(past.byteLength).toBe(0)
+
+							expect(await api.statFile(name)).toEqual({
+								sizeBytes: expected.length,
+							})
+						}
+
+						// Missing entries: readFile rejects, statFile is undefined.
+						await expect(api.readFile("missing-entry.bin")).rejects.toThrow()
+						await expect(
+							api.statFile("missing-entry.bin"),
+						).resolves.toBeUndefined()
+
+						// Batch stat matches the single-stats, in order.
+						const singleStats = names.map((n) =>
+							c.files[n] !== undefined
+								? { sizeBytes: toBytes(c.files[n]!).length }
+								: undefined,
+						)
+						const batchStats = await api.statFiles(names)
+						expect(batchStats.length).toBe(names.length)
+						for (let i = 0; i < names.length; i++) {
+							expect(batchStats[i]).toEqual(singleStats[i])
+						}
+						await expect(api.statFiles(["missing-entry.bin"])).resolves.toEqual(
+							[undefined],
+						)
+
+						// Contract backends wire no probe implementations, so
+						// identified media reports the dedicated "no backend"
+						// reason instead of looking like a decode failure,
+						// while non-media entries still identify normally.
+						for (const name of names) {
+							const type = await api.sniff(name)
+							const probed = await api.probe(name)
+							if (type !== undefined && type.kind !== "other") {
+								expect(probed).toEqual({
+									kind: "unknown",
+									reason: "unavailable",
+								})
+							} else if (type !== undefined) {
+								expect(probed).toEqual({ kind: "other", mime: type.mime })
+							} else {
+								expect(probed).toEqual({
+									kind: "unknown",
+									reason: "unsupported",
+								})
+							}
+						}
+
+						// Neither call rejects on a missing entry.
+						await expect(
+							api.sniff("missing-entry.bin"),
+						).resolves.toBeUndefined()
+						await expect(api.probe("missing-entry.bin")).resolves.toEqual({
+							kind: "unknown",
+							reason: "unsupported",
+						})
+					})
+				}
+			})
+		}
+
+		for (const c of CONTAINER_CONTRACT_CASES) {
+			test(`case "${c.name}": identical results across backends`, async () => {
+				const results = []
+				for (const backend of backends) {
+					const api = await backend.build(c.files)
+					results.push(await collectManifest(api))
+				}
+				for (let i = 1; i < results.length; i++) {
+					expect(results[i]).toEqual(results[0])
+				}
+			})
+		}
+	})
+}

package/src/define-plugin.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest"
+import { assertPluginShape, definePlugin } from "./define-plugin.ts"
+
+/** Cast a deliberately-broken definition past the type level. */
+const broken = (value: unknown) => value as Parameters<typeof definePlugin>[0]
+
+describe("definePlugin", () => {
+	it("freezes a valid definition", () => {
+		const plugin = definePlugin({ detect: async () => ({ ok: true }) })
+		expect(Object.isFrozen(plugin)).toBe(true)
+	})
+
+	it("rejects unknown hook keys with a friendly error", () => {
+		expect(() =>
+			definePlugin(
+				broken({
+					detect: async () => ({ ok: true }),
+					sourceMetaa: async () => ({}),
+				}),
+			),
+		).toThrow(/unknown hook\(s\) "sourceMetaa"/)
+	})
+
+	it("rejects a missing detect", () => {
+		expect(() =>
+			definePlugin(broken({ sourceMeta: async () => ({}) })),
+		).toThrow(/missing detect\(\)/)
+	})
+
+	it("rejects synchronous hooks", () => {
+		expect(() =>
+			definePlugin(broken({ detect: () => ({ ok: true }) })),
+		).toThrow(/"detect" must be an async function/)
+	})
+
+	it("accepts every optional hook when async", () => {
+		expect(() =>
+			definePlugin({
+				detect: async () => ({ ok: true }),
+				sourceMeta: async () => ({}),
+				searchMeta: async () => ({}),
+				coverLocal: async () => undefined,
+				listFiles: async () => [],
+			}),
+		).not.toThrow()
+	})
+
+	it("assertPluginShape narrows valid values", () => {
+		const value: unknown = { detect: async () => ({ ok: true }) }
+		assertPluginShape(value)
+		expect(typeof value.detect).toBe("function")
+	})
+})

package/src/define-plugin.ts

@@ -0,0 +1,12 @@
+/**
+ * The plugin definition factories 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 {
+	assertPluginShape,
+	createFailingPlugin,
+	definePlugin,
+	isDetected,
+	isMissed,
+} from "@hoardodile/sdk-types"

package/src/dev-runner.test.ts

@@ -0,0 +1,98 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { afterEach, beforeEach, describe, expect, test } from "vitest"
+import { runPluginHook } from "./dev-runner.ts"
+
+const FIXTURE_PLUGIN = `
+export default {
+	async detect(api) {
+		const files = await api.listFileNames()
+		return files.some((f) => f.endsWith(".hdtpl"))
+			? { ok: true }
+			: { ok: false, reasons: ["no .hdtpl file"] }
+	},
+}
+`
+
+describe("runPluginHook", () => {
+	let rootDir: string
+	let dir: string
+	let mainPath: string
+
+	beforeEach(() => {
+		rootDir = mkdtempSync(join(tmpdir(), "dev-runner-test-"))
+		dir = join(rootDir, "resource")
+		mkdirSync(dir)
+		writeFileSync(join(dir, "chapter.hdtpl"), "tpl")
+		mainPath = join(rootDir, "main.js")
+		writeFileSync(mainPath, FIXTURE_PLUGIN)
+	})
+
+	afterEach(() => {
+		rmSync(rootDir, { recursive: true, force: true })
+	})
+
+	test("runs the hook with a directory-backed ResourceAPI", async () => {
+		const { result, durationMs } = await runPluginHook({
+			mainPath,
+			hook: "detect",
+			dir,
+		})
+		expect(result).toEqual({ ok: true })
+		expect(durationMs).toBeGreaterThanOrEqual(0)
+	})
+
+	test("throws a clear error when the hook is missing", async () => {
+		await expect(
+			runPluginHook({ mainPath, hook: "sourceMeta", dir }),
+		).rejects.toThrow(/no "sourceMeta" hook/)
+	})
+
+	test("throws when the module has no default-export definition", async () => {
+		writeFileSync(mainPath, "export const x = 1\n")
+		await expect(
+			runPluginHook({ mainPath, hook: "detect", dir }),
+		).rejects.toThrow(/default-export a plugin definition/)
+	})
+
+	test("runs detect first so later hooks see the payload via api.context", async () => {
+		writeFileSync(
+			mainPath,
+			`export default {
+				async detect() {
+					return { ok: true, shape: { hasChapter: true } }
+				},
+				async sourceMeta(api) {
+					return { context: api.context.detect }
+				},
+			}`,
+		)
+		const { result } = await runPluginHook({
+			mainPath,
+			hook: "sourceMeta",
+			dir,
+		})
+		expect(result).toEqual({ context: { shape: { hasChapter: true } } })
+	})
+
+	test("a failed detection leaves the context absent", async () => {
+		writeFileSync(
+			mainPath,
+			`export default {
+				async detect() {
+					return { ok: false, reasons: ["no match"] }
+				},
+				async sourceMeta(api) {
+					return { context: api.context.detect }
+				},
+			}`,
+		)
+		const { result } = await runPluginHook({
+			mainPath,
+			hook: "sourceMeta",
+			dir,
+		})
+		expect(result).toEqual({ context: undefined })
+	})
+})

package/src/dev-runner.ts

@@ -0,0 +1,73 @@
+import { pathToFileURL } from "node:url"
+import { createDirectoryResourceAPI } from "./directory-api.ts"
+import type { HookName } from "./sandbox/protocol.ts"
+
+/**
+ * Plugin hooks the dev runner can invoke against a directory — the
+ * contract-order list shared with the sandbox host and the CLI.
+ */
+export type PluginHookName = HookName
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null
+}
+
+/**
+ * Load a built plugin `main.js` and invoke one hook with a
+ * directory-backed {@link ResourceAPI}. Development aid only — the plugin
+ * runs unsandboxed in the current process, so only run code you trust.
+ * Consumed from plugin tests as a devDependency; never bundled into a
+ * shipped plugin.
+ *
+ * Before the target hook runs, `detect` is invoked once (when the
+ * target is not detect itself) so hooks see the session context a real
+ * sandbox session would have — `api.context.detect` carries the
+ * detection payload. A throwing or missed detection leaves the context
+ * absent, exactly like a fresh worker in production.
+ */
+export async function runPluginHook(opts: {
+	readonly mainPath: string
+	readonly hook: PluginHookName
+	readonly dir: string
+	/** Scratch dir for `extractArchive` materialization. */
+	readonly extractCacheDir?: string
+}): Promise<{ readonly result: unknown; readonly durationMs: number }> {
+	const mod: unknown = await import(pathToFileURL(opts.mainPath).href)
+	if (!isRecord(mod) || !isRecord(mod.default)) {
+		throw new Error(
+			`Plugin at ${opts.mainPath} must default-export a plugin definition`,
+		)
+	}
+	const hook = mod.default[opts.hook]
+	if (typeof hook !== "function") {
+		throw new Error(
+			`Plugin at ${opts.mainPath} has no "${opts.hook}" hook (expected a function on the default export)`,
+		)
+	}
+
+	let detectContext: unknown
+	if (opts.hook !== "detect" && typeof mod.default.detect === "function") {
+		try {
+			const detected = await mod.default.detect(
+				createDirectoryResourceAPI(opts.dir, {
+					extractCacheDir: opts.extractCacheDir,
+				}),
+			)
+			if (isRecord(detected) && detected.ok === true) {
+				const { ok: _ok, ...payload } = detected
+				if (Object.keys(payload).length > 0) detectContext = payload
+			}
+		} catch {
+			// A throwing detector leaves the context absent — same as a
+			// fresh worker in production.
+		}
+	}
+
+	const api = createDirectoryResourceAPI(opts.dir, {
+		extractCacheDir: opts.extractCacheDir,
+		detectContext,
+	})
+	const started = performance.now()
+	const result: unknown = await hook(api)
+	return { result, durationMs: performance.now() - started }
+}

package/src/directory-api.test.ts

@@ -0,0 +1,229 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { afterEach, beforeEach, describe, expect, test } from "vitest"
+import {
+	createDirectoryResourceAPI,
+	resolveSafeImportPath,
+} from "./directory-api.ts"
+
+describe("createDirectoryResourceAPI", () => {
+	let rootDir: string
+
+	beforeEach(() => {
+		rootDir = mkdtempSync(join(tmpdir(), "directory-api-test-"))
+		mkdirSync(join(rootDir, "sub"))
+		writeFileSync(join(rootDir, "inside.txt"), "inside")
+		writeFileSync(join(rootDir, "sub", "nested.txt"), "nested")
+	})
+
+	afterEach(() => {
+		rmSync(rootDir, { recursive: true, force: true })
+	})
+
+	test("readFile allows paths inside the directory", async () => {
+		const api = createDirectoryResourceAPI(rootDir)
+		const data = await api.readFile("inside.txt")
+		expect(new TextDecoder().decode(data)).toBe("inside")
+	})
+
+	test("readFile rejects parent directory traversal", async () => {
+		const api = createDirectoryResourceAPI(rootDir)
+		await expect(api.readFile("../outside.txt")).rejects.toThrow(
+			"escapes import directory",
+		)
+	})
+
+	test("readFile rejects nested traversal", async () => {
+		const api = createDirectoryResourceAPI(rootDir)
+		await expect(api.readFile("sub/../../outside.txt")).rejects.toThrow(
+			"escapes import directory",
+		)
+	})
+
+	test("readFile rejects absolute paths", async () => {
+		const api = createDirectoryResourceAPI(rootDir)
+		await expect(api.readFile("/etc/passwd")).rejects.toThrow(
+			"absolute paths are not allowed",
+		)
+	})
+
+	test("readFile rejects empty paths", async () => {
+		const api = createDirectoryResourceAPI(rootDir)
+		await expect(api.readFile("")).rejects.toThrow("path is empty")
+	})
+
+	test("readFile rejects null bytes", async () => {
+		const api = createDirectoryResourceAPI(rootDir)
+		await expect(api.readFile("inside.txt\0extra")).rejects.toThrow("null byte")
+	})
+
+	test("statFile validates paths and reports real sizes", async () => {
+		const api = createDirectoryResourceAPI(rootDir)
+		await expect(api.statFile("../outside.txt")).rejects.toThrow(
+			"escapes import directory",
+		)
+		expect(await api.statFile("inside.txt")).toEqual({ sizeBytes: 6 })
+	})
+
+	test("sniffing works without probe backends", async () => {
+		const api = createDirectoryResourceAPI(rootDir)
+		// Identification only reads bytes, so the directory API answers it
+		// in full — decoding is what has no backend here.
+		expect(await api.sniff("inside.txt")).toEqual({
+			mime: "text/plain",
+			ext: ".txt",
+			kind: "other",
+			source: "extension",
+		})
+		expect(await api.probe("inside.txt")).toEqual({
+			kind: "other",
+			mime: "text/plain",
+		})
+	})
+
+	test("listFileNames stays within the directory", async () => {
+		const api = createDirectoryResourceAPI(rootDir)
+		const files = await api.listFileNames()
+		expect([...files].sort()).toEqual(["inside.txt", "sub/nested.txt"])
+	})
+})
+
+describe("createDirectoryResourceAPI listFileNames", () => {
+	let rootDir: string
+
+	beforeEach(() => {
+		rootDir = mkdtempSync(join(tmpdir(), "directory-api-list-"))
+		writeFileSync(join(rootDir, "page10.txt"), "")
+		writeFileSync(join(rootDir, "page2.txt"), "")
+		writeFileSync(join(rootDir, "page1.txt"), "")
+		writeFileSync(join(rootDir, ".hidden"), "")
+		writeFileSync(join(rootDir, "cover.uploading-abc123"), "")
+		mkdirSync(join(rootDir, ".hiddendir"))
+		writeFileSync(join(rootDir, ".hiddendir", "secret.txt"), "")
+	})
+
+	afterEach(() => {
+		rmSync(rootDir, { recursive: true, force: true })
+	})
+
+	test("skips dotfiles and .uploading- entries", async () => {
+		const api = createDirectoryResourceAPI(rootDir)
+		const files = await api.listFileNames()
+		expect(files.every((f) => !f.includes(".hidden"))).toBe(true)
+		expect(files.some((f) => f.includes(".uploading-"))).toBe(false)
+	})
+
+	test("sorts with localeCompare numeric ordering", async () => {
+		const api = createDirectoryResourceAPI(rootDir)
+		expect(await api.listFileNames()).toEqual([
+			"page1.txt",
+			"page2.txt",
+			"page10.txt",
+		])
+	})
+})
+
+describe("createDirectoryResourceAPI order manifest", () => {
+	let rootDir: string
+
+	beforeEach(() => {
+		rootDir = mkdtempSync(join(tmpdir(), "directory-api-order-"))
+		writeFileSync(join(rootDir, "b.txt"), "")
+		writeFileSync(join(rootDir, "a.txt"), "")
+		writeFileSync(join(rootDir, "c.txt"), "")
+	})
+
+	afterEach(() => {
+		rmSync(rootDir, { recursive: true, force: true })
+	})
+
+	test("honors a valid .order manifest over the natural sort", async () => {
+		writeFileSync(
+			join(rootDir, ".order"),
+			JSON.stringify(["c.txt", "a.txt", "b.txt"]),
+		)
+		const api = createDirectoryResourceAPI(rootDir)
+		expect(await api.listFileNames()).toEqual(["c.txt", "a.txt", "b.txt"])
+	})
+
+	test("appends entries the manifest does not mention, naturally sorted", async () => {
+		writeFileSync(join(rootDir, ".order"), JSON.stringify(["c.txt"]))
+		const api = createDirectoryResourceAPI(rootDir)
+		expect(await api.listFileNames()).toEqual(["c.txt", "a.txt", "b.txt"])
+	})
+
+	test("ignores a manifest whose entries do not resolve", async () => {
+		writeFileSync(
+			join(rootDir, ".order"),
+			JSON.stringify(["gone.txt", "b.txt"]),
+		)
+		const api = createDirectoryResourceAPI(rootDir)
+		expect(await api.listFileNames()).toEqual(["a.txt", "b.txt", "c.txt"])
+	})
+
+	test("ignores a malformed stray .order in an arbitrary import dir", async () => {
+		writeFileSync(join(rootDir, ".order"), "not json")
+		const api = createDirectoryResourceAPI(rootDir)
+		expect(await api.listFileNames()).toEqual(["a.txt", "b.txt", "c.txt"])
+	})
+})
+
+describe("createDirectoryResourceAPI ranged reads", () => {
+	let rootDir: string
+
+	beforeEach(() => {
+		rootDir = mkdtempSync(join(tmpdir(), "directory-api-range-"))
+		writeFileSync(join(rootDir, "data.bin"), Buffer.from([1, 2, 3, 4, 250]))
+	})
+
+	afterEach(() => {
+		rmSync(rootDir, { recursive: true, force: true })
+	})
+
+	test("range returns the requested slice", async () => {
+		const api = createDirectoryResourceAPI(rootDir)
+		expect([...(await api.readFile("data.bin", { start: 1, end: 4 }))]).toEqual(
+			[2, 3, 4],
+		)
+	})
+
+	test("end defaults to file size and clamps", async () => {
+		const api = createDirectoryResourceAPI(rootDir)
+		expect([...(await api.readFile("data.bin", { start: 3 }))]).toEqual([
+			4, 250,
+		])
+		expect([
+			...(await api.readFile("data.bin", { start: 0, end: 10_000 })),
+		]).toEqual([1, 2, 3, 4, 250])
+	})
+
+	test("start past the end returns empty", async () => {
+		const api = createDirectoryResourceAPI(rootDir)
+		expect(
+			(await api.readFile("data.bin", { start: 100, end: 200 })).byteLength,
+		).toBe(0)
+	})
+
+	test("full reads above the byte cap are rejected with guidance", async () => {
+		const api = createDirectoryResourceAPI(rootDir, { maxReadFileBytes: 4 })
+		await expect(api.readFile("data.bin")).rejects.toThrow(/byte range/)
+	})
+
+	test("ranged reads above the byte cap are rejected too", async () => {
+		const api = createDirectoryResourceAPI(rootDir, { maxReadFileBytes: 3 })
+		await expect(
+			api.readFile("data.bin", { start: 0, end: 5 }),
+		).rejects.toThrow(/byte range/)
+		await expect(
+			api.readFile("data.bin", { start: 0, end: 3 }),
+		).resolves.toHaveLength(3)
+	})
+})
+
+describe("resolveSafeImportPath", () => {
+	test("resolves a valid relative path against the directory", () => {
+		const resolved = resolveSafeImportPath("root", "a/b.txt")
+		expect(resolved.endsWith(join("root", "a", "b.txt"))).toBe(true)
+	})
+})