@hoardodile/host 0.1.0 → 0.1.2

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.0",
+  "version": "0.1.2",
   "license": "MIT",
   "description": "hoardodile plugin runtime host: sandbox, hook strategy, ResourceAPI, containers and the test runner.",
   "keywords": [
@@ -67,11 +67,11 @@
     "file-type": "^22.0.2",
     "yauzl": "^3.4.0",
     "yazl": "^3.3.1",
-    "@hoardodile/sdk-types": "0.1.0"
+    "@hoardodile/sdk-types": "0.1.2"
   },
   "optionalDependencies": {
     "@derhuerst/ffprobe-static": "^5.3.0",
-    "@hoardodile/7z-bin": "^1.1.0",
+    "@hoardodile/7z-bin": "^1.1.3",
     "ffmpeg-static": "^5.3.0"
   },
   "peerDependencies": {

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/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

@@ -235,6 +235,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
@@ -398,6 +406,7 @@ export function createStoragePaths(
 		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) =>

package/src/index.ts

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

package/src/sandbox/fixtures/asset-plugin.mjs

@@ -1,6 +1,7 @@
 // Sandbox fixture: exercises the plugin asset API within detect — reads
-// the vault stat, then performs a consent-gated download. Used to verify
-// the manifest permission gate and the wired plugin asset handler.
+// the vault stat, performs a consent-gated single download and a batch
+// download. Used to verify the manifest permission gate and the wired
+// plugin asset handler (single in → single out, array in → array out).
 export default {
 	detect: async (api) => {
 		const stat = await api.statAsset("runtime/a.mjs")
@@ -8,6 +9,10 @@ export default {
 			url: "https://example.com/runtime/a.mjs",
 			dest: "runtime/a.mjs",
 		})
-		return { ok: true, stat, downloaded }
+		const batched = await api.download([
+			{ url: "https://example.com/runtime/b.mjs", dest: "runtime/b.mjs" },
+			{ url: "https://example.com/runtime/c.mjs", dest: "runtime/c.mjs" },
+		])
+		return { ok: true, stat, downloaded, batched }
 	},
 }

package/src/sandbox/host.test.ts

@@ -548,12 +548,13 @@ describe("plugin sandbox", () => {
 				pluginAssets: {
 					download: async (pluginId, request) => {
 						seen.push([pluginId, request])
-						return {
-							path: request.dest,
+						const requests = Array.isArray(request) ? request : [request]
+						return requests.map((req) => ({
+							path: req.dest,
 							sizeBytes: 3,
 							sha256: "a".repeat(64),
 							cached: false,
-						}
+						}))
 					},
 					statAsset: async (pluginId, path) => {
 						seen.push([pluginId, path])
@@ -574,12 +575,27 @@ describe("plugin sandbox", () => {
 		await expect(plugin.detect(createStubApi())).resolves.toEqual({
 			ok: true,
 			stat: undefined,
+			// Single in → single result out, batch in → array out.
 			downloaded: {
 				path: "runtime/a.mjs",
 				sizeBytes: 3,
 				sha256: "a".repeat(64),
 				cached: false,
 			},
+			batched: [
+				{
+					path: "runtime/b.mjs",
+					sizeBytes: 3,
+					sha256: "a".repeat(64),
+					cached: false,
+				},
+				{
+					path: "runtime/c.mjs",
+					sizeBytes: 3,
+					sha256: "a".repeat(64),
+					cached: false,
+				},
+			],
 		})
 		expect(seen[0]).toEqual(["asset-allowed", "runtime/a.mjs"])
 		expect(seen[1]).toEqual([
@@ -589,6 +605,13 @@ describe("plugin sandbox", () => {
 				dest: "runtime/a.mjs",
 			},
 		])
+		expect(seen[2]).toEqual([
+			"asset-allowed",
+			[
+				{ url: "https://example.com/runtime/b.mjs", dest: "runtime/b.mjs" },
+				{ url: "https://example.com/runtime/c.mjs", dest: "runtime/c.mjs" },
+			],
+		])
 	})
 
 	test("a log flood exceeds the per-hook budget and fails the hook", async () => {

package/src/sandbox/host.ts

@@ -33,10 +33,15 @@ import { createSandboxedPlugin } from "./sandboxed-plugin.ts"
  * workbench) omit it and the methods answer `UNAVAILABLE`.
  */
 export type PluginAssetHandler = {
+	/**
+	 * Download one request or a batch of requests. Answers with the
+	 * result array (batch shape) — this adapter unwraps the single
+	 * result for a single request (see {@link dispatchApi}).
+	 */
 	readonly download: (
 		pluginId: string,
-		request: PluginDownloadRequest,
-	) => Promise<PluginDownloadResult>
+		request: PluginDownloadRequest | readonly PluginDownloadRequest[],
+	) => Promise<readonly PluginDownloadResult[]>
 	readonly statAsset: (
 		pluginId: string,
 		path: string,
@@ -804,13 +809,15 @@ export function createPluginSandbox(
 					return
 				}
 				// RPC boundary: the child-side proxy forwards args verbatim,
-				// so the contract order is guaranteed (request object for
-				// `download`, string path for the rest).
+				// so the contract order is guaranteed (request object or
+				// request array for `download`, string path for the rest).
 				if (method === "download") {
-					respond(
-						true,
-						await handler.download(state.id, args[0] as PluginDownloadRequest),
-					)
+					const request = args[0] as
+						| PluginDownloadRequest
+						| readonly PluginDownloadRequest[]
+					const results = await handler.download(state.id, request)
+					// Wire rule: array in → array out, single in → single out.
+					respond(true, Array.isArray(request) ? results : results[0])
 				} else if (method === "statAsset") {
 					respond(true, await handler.statAsset(state.id, args[0] as string))
 				} else if (method === "readAsset") {