@hoardodile/sdk-server 0.0.0

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/helpers.ts","../src/detectors.ts"],"names":["files"],"mappings":"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","file":"index.js","sourcesContent":["import type {\n\tFileType,\n\tImageHash,\n\tImageHashesResult,\n\tImageHashKind,\n\tResourceAPI,\n} from \"@hoardodile/sdk-types\"\nimport {\n\tPLUGIN_IMAGE_PROBE_CONCURRENCY,\n\tPLUGIN_VIDEO_PROBE_CONCURRENCY,\n} from \"@hoardodile/sdk-types/plugin\"\nimport {\n\tRESOURCE_PREVIEW_MAX_AREA,\n\tRESOURCE_PREVIEW_SIZE_THRESHOLD,\n} from \"@hoardodile/sdk-types/resource\"\n\n/**\n * True when an image exceeds the preview thresholds — the pixel-area\n * cap **or** the byte-size threshold — and should be served through the\n * preview pipeline instead of the original. Format-driven transcode\n * needs (formats browsers cannot render natively) are decided by the\n * consuming plugin separately.\n */\nfunction exceedsPreviewThresholds(check: {\n\treadonly width: number | undefined\n\treadonly height: number | undefined\n\treadonly sizeBytes: number | undefined\n}): boolean {\n\tconst { width, height, sizeBytes } = check\n\tconst exceedsArea =\n\t\twidth !== undefined &&\n\t\theight !== undefined &&\n\t\twidth * height > RESOURCE_PREVIEW_MAX_AREA\n\tconst exceedsSize =\n\t\tsizeBytes !== undefined && sizeBytes > RESOURCE_PREVIEW_SIZE_THRESHOLD\n\treturn exceedsArea || exceedsSize\n}\n\n/** Return the lower-cased extension from the last dot, or `\"\"` when there is none. */\nexport function extname(filename: string): string {\n\tconst dot = filename.lastIndexOf(\".\")\n\tif (dot === -1) return \"\"\n\treturn filename.slice(dot).toLowerCase()\n}\n\n/** Natural-sort filenames (case-insensitive, numeric). Mutates and returns. */\nexport function naturalSort(files: readonly string[]): string[] {\n\treturn [...files].sort((a, b) =>\n\t\ta.localeCompare(b, undefined, { sensitivity: \"base\", numeric: true }),\n\t)\n}\n\n/**\n * Map items with at most `limit` promises in flight. Results keep input\n * order; the first rejection aborts the map (in-flight calls settle).\n * Probe loops use this to fan out across the host's concurrent API\n * dispatch instead of trickling one RPC at a time.\n */\nexport async function mapConcurrent<T, R>(\n\titems: readonly T[],\n\tlimit: number,\n\tfn: (item: T, index: number) => Promise<R>,\n): Promise<R[]> {\n\tconst results: R[] = new Array(items.length)\n\tlet next = 0\n\tasync function lane(): Promise<void> {\n\t\tfor (;;) {\n\t\t\tconst index = next++\n\t\t\tif (index >= items.length) return\n\t\t\tconst item = items[index]\n\t\t\tif (item === undefined) continue\n\t\t\tresults[index] = await fn(item, index)\n\t\t}\n\t}\n\tconst lanes = Math.max(1, Math.min(limit, items.length))\n\tconst runners: Promise<void>[] = []\n\tfor (let i = 0; i < lanes; i++) runners.push(lane())\n\tawait Promise.all(runners)\n\treturn results\n}\n\n/** File-list item shapes produced by the probe helpers. */\ntype ProbedImageFile = {\n\treadonly type: \"image\"\n\treadonly width?: number\n\treadonly height?: number\n\treadonly preview: boolean\n}\ntype ProbedVideoFile = {\n\treadonly type: \"video\"\n\treadonly width?: number\n\treadonly height?: number\n\treadonly durationMs?: number\n}\ntype ProbedAudioFile = {\n\treadonly type: \"audio\"\n\treadonly durationMs?: number\n\treadonly hasCoverArt?: boolean\n}\n\n/**\n * Probe a file and return the file-item shaped object matching what the\n * content actually is, or `undefined` for non-media files. This is the\n * primitive: plugins that accept mixed media route on the result\n * instead of pre-sorting by extension, and the three per-kind helpers\n * below are thin narrowings of it.\n *\n * When identification succeeds but decoding does not (no ffprobe on the\n * host, a damaged container), the file keeps its media type and simply\n * carries no dimensions — losing the entry entirely would be worse than\n * showing it undecorated.\n */\nexport async function probeMediaFile(\n\tapi: ResourceAPI,\n\tfilename: string,\n): Promise<ProbedImageFile | ProbedVideoFile | ProbedAudioFile | undefined> {\n\tconst probed = await api.probe(filename)\n\tswitch (probed.kind) {\n\t\tcase \"image\": {\n\t\t\tconst { width, height } = probed\n\t\t\tconst sizeBytes = (await api.statFile(filename))?.sizeBytes\n\t\t\treturn {\n\t\t\t\ttype: \"image\",\n\t\t\t\twidth,\n\t\t\t\theight,\n\t\t\t\tpreview: exceedsPreviewThresholds({ width, height, sizeBytes }),\n\t\t\t}\n\t\t}\n\t\tcase \"video\":\n\t\t\treturn {\n\t\t\t\ttype: \"video\",\n\t\t\t\twidth: probed.width,\n\t\t\t\theight: probed.height,\n\t\t\t\tdurationMs: probed.durationMs,\n\t\t\t}\n\t\tcase \"audio\":\n\t\t\treturn {\n\t\t\t\ttype: \"audio\",\n\t\t\t\tdurationMs: probed.durationMs,\n\t\t\t\thasCoverArt: probed.coverArt === undefined ? undefined : true,\n\t\t\t}\n\t\tcase \"other\":\n\t\t\treturn undefined\n\t\tdefault:\n\t\t\treturn undecodedItem(await api.sniff(filename))\n\t}\n}\n\n/** Bare file item for media the host identified but could not decode. */\nfunction undecodedItem(\n\ttype: FileType | undefined,\n): ProbedImageFile | ProbedVideoFile | ProbedAudioFile | undefined {\n\tswitch (type?.kind) {\n\t\tcase \"image\":\n\t\t\treturn { type: \"image\", preview: false }\n\t\tcase \"video\":\n\t\t\treturn { type: \"video\" }\n\t\tcase \"audio\":\n\t\t\treturn { type: \"audio\" }\n\t\tdefault:\n\t\t\treturn undefined\n\t}\n}\n\n/**\n * Probe a file expected to be an image. A file that turns out not to be\n * one still yields an image-shaped item (with no dimensions), so a file\n * list keeps its declared type.\n */\nexport async function probeImageFile(\n\tapi: ResourceAPI,\n\tfilename: string,\n): Promise<ProbedImageFile> {\n\tconst item = await probeMediaFile(api, filename)\n\treturn item?.type === \"image\" ? item : { type: \"image\", preview: false }\n}\n\n/** Probe a file expected to be a video. See {@link probeImageFile}. */\nexport async function probeVideoFile(\n\tapi: ResourceAPI,\n\tfilename: string,\n): Promise<ProbedVideoFile> {\n\tconst item = await probeMediaFile(api, filename)\n\treturn item?.type === \"video\" ? item : { type: \"video\" }\n}\n\n/** Probe a file expected to be audio. See {@link probeImageFile}. */\nexport async function probeAudioFile(\n\tapi: ResourceAPI,\n\tfilename: string,\n): Promise<ProbedAudioFile> {\n\tconst item = await probeMediaFile(api, filename)\n\treturn item?.type === \"audio\" ? item : { type: \"audio\" }\n}\n\n/**\n * One entry of {@link mediaFileList}: the filename plus everything the\n * probe pass learned about the file (`sniffed` is the sniffed type that\n * decided the probe lane — the same data the entry's dimensions were\n * routed on).\n */\nexport type MediaFileListEntry = {\n\treadonly filename: string\n\treadonly sniffed?: FileType\n} & (ProbedImageFile | ProbedVideoFile | ProbedAudioFile)\n\nexport type MediaFileListOptions = {\n\t/**\n\t * Candidate names to probe. When absent the helper lists the\n\t * resource itself (natural-sorted). Pass a pre-filtered list (e.g.\n\t * top-level files only) to skip names the plugin never wants.\n\t */\n\treadonly names?: readonly string[]\n}\n\n/**\n * Build a typed media file list in one pass: sniff every candidate,\n * then probe images and timed media (video/audio) in separate bounded\n * lanes — sharp header reads fan out wider than ffprobe spawns. The\n * result keeps input order and drops files that are not decodable\n * media. The one-call implementation for a `listFiles` hook over a\n * flat media resource.\n */\nexport async function mediaFileList(\n\tapi: ResourceAPI,\n\topts: MediaFileListOptions = {},\n): Promise<readonly MediaFileListEntry[]> {\n\t// `listFileNames` already returns the host's canonical order (the\n\t// `.order` upload order, natural name sort otherwise) — re-sorting\n\t// here would scramble it. Plugins wanting a different order pass\n\t// explicit `names`.\n\tconst files = opts.names ?? (await api.listFileNames())\n\tconst types = await mapConcurrent(\n\t\tfiles,\n\t\tPLUGIN_IMAGE_PROBE_CONCURRENCY,\n\t\t(name) => api.sniff(name),\n\t)\n\tconst entries = new Map<string, MediaFileListEntry>()\n\tconst imageIndexes: number[] = []\n\tconst timedIndexes: number[] = []\n\tfor (const index of files.keys()) {\n\t\tconst kind = types[index]?.kind\n\t\tif (kind === \"image\") imageIndexes.push(index)\n\t\telse if (kind === \"video\" || kind === \"audio\") timedIndexes.push(index)\n\t}\n\n\tasync function probeInto(index: number): Promise<void> {\n\t\tconst filename = files[index]\n\t\tif (filename === undefined) return\n\t\tconst probed = await probeMediaFile(api, filename)\n\t\tif (probed === undefined) return\n\t\tentries.set(filename, {\n\t\t\tfilename,\n\t\t\tsniffed: types[index],\n\t\t\t...probed,\n\t\t})\n\t}\n\n\tawait Promise.all([\n\t\tmapConcurrent(imageIndexes, PLUGIN_IMAGE_PROBE_CONCURRENCY, probeInto),\n\t\tmapConcurrent(timedIndexes, PLUGIN_VIDEO_PROBE_CONCURRENCY, probeInto),\n\t])\n\n\tconst result: MediaFileListEntry[] = []\n\tfor (const filename of files) {\n\t\tconst entry = entries.get(filename)\n\t\tif (entry !== undefined) result.push(entry)\n\t}\n\treturn result\n}\n\n/**\n * The `sourceMeta` for a bare file count — the one-liner for plugins\n * whose card needs only `fileCount`. Resolves to `undefined` for empty\n * resources, matching the host's \"nothing to report\" contract.\n */\nexport async function countSourceMeta(\n\tapi: ResourceAPI,\n): Promise<{ readonly fileCount: number } | undefined> {\n\tconst files = await api.listFileNames()\n\treturn files.length === 0 ? undefined : { fileCount: files.length }\n}\n\nexport type ReadFileChunksOptions = {\n\t/** Chunk size in bytes. Defaults to 1 MiB. */\n\treadonly chunkSize?: number\n}\n\n/**\n * Stream a file as a sequence of chunks via ranged `readFile` calls.\n * Memory stays bounded by the chunk size on both sides of the plugin\n * boundary — the host never buffers the whole file.\n */\nexport async function* readFileChunks(\n\tapi: ResourceAPI,\n\tpath: string,\n\topts: ReadFileChunksOptions = {},\n): AsyncGenerator<Uint8Array, void, undefined> {\n\tconst chunkSize = opts.chunkSize ?? 1024 * 1024\n\tlet offset = 0\n\tfor (;;) {\n\t\tconst chunk = await api.readFile(path, {\n\t\t\tstart: offset,\n\t\t\tend: offset + chunkSize,\n\t\t})\n\t\tif (chunk.byteLength === 0) return\n\t\tyield chunk\n\t\tif (chunk.byteLength < chunkSize) return\n\t\toffset += chunk.byteLength\n\t}\n}\n\n/** Per-file default hash kinds for {@link imageHashesFor}. */\nexport const DEFAULT_IMAGE_HASH_KINDS: readonly ImageHashKind[] = [\n\t\"sha256\",\n\t\"dhash\",\n]\n\nexport type ImageHashesForOptions = {\n\t/** Hash kinds per image. Defaults to sha256 + dhash. */\n\treadonly kinds?: readonly ImageHashKind[]\n}\n\n/**\n * Compute the requested hash kinds of one image file as `ImageHash`\n * entries (`scope` = the file path). Resolves to `[]` for non-image or\n * undecodable files.\n */\nexport async function imageHashesForFile(\n\tapi: ResourceAPI,\n\tscope: string,\n\tkinds: readonly ImageHashKind[] = DEFAULT_IMAGE_HASH_KINDS,\n): Promise<readonly ImageHash[]> {\n\tconst computed = await api.computeImageHashes(scope, kinds)\n\tif (computed === undefined) return []\n\tconst entries: ImageHash[] = []\n\tfor (const kind of kinds) {\n\t\tconst value = computed[kind]\n\t\tif (value !== undefined) entries.push({ scope, type: kind, value })\n\t}\n\treturn entries\n}\n\n/**\n * One-line `imageHashes` hook implementation for image plugins: hash\n * every image file of the resource (animated sources hash their first\n * frame). Image files are selected by content, so a mislabelled photo\n * is still deduplicated. Plugins facing image-less resources omit the\n * hook entirely.\n */\nexport async function imageHashesFor(\n\tapi: ResourceAPI,\n\topts: ImageHashesForOptions = {},\n): Promise<ImageHashesResult> {\n\tconst kinds = opts.kinds ?? DEFAULT_IMAGE_HASH_KINDS\n\tconst names = await api.listFileNames()\n\tconst types = await mapConcurrent(\n\t\tnames,\n\t\tPLUGIN_IMAGE_PROBE_CONCURRENCY,\n\t\t(name) => api.sniff(name),\n\t)\n\tconst images = names.filter((_, i) => types[i]?.kind === \"image\")\n\tconst hashes = (\n\t\tawait mapConcurrent(images, PLUGIN_IMAGE_PROBE_CONCURRENCY, (filename) =>\n\t\t\timageHashesForFile(api, filename, kinds),\n\t\t)\n\t).flat()\n\treturn { hashes }\n}\n","import type { Detection, ResourceAPI } from \"@hoardodile/sdk-types\"\nimport { err, ok } from \"@hoardodile/sdk-types\"\nimport type { MediaKind } from \"@hoardodile/sdk-types/media-exts\"\nimport { extname, mapConcurrent } from \"./helpers.ts\"\n\n/** A detector evaluates a resource and returns a {@link Detection}. */\nexport type Detector = (api: ResourceAPI) => Promise<Detection>\n\n/** Sniff fan-out bound: detection reads a small header per candidate. */\nconst SNIFF_CONCURRENCY = 8\n\n/** Detect when all given detectors pass. */\nexport function all(...detectors: readonly Detector[]): Detector {\n\treturn async function detectAll(api) {\n\t\tfor (const detector of detectors) {\n\t\t\tconst result = await detector(api)\n\t\t\tif (!result.ok) return result\n\t\t}\n\t\treturn ok()\n\t}\n}\n\n/** Detect when at least one given detector passes. */\nexport function any(...detectors: readonly Detector[]): Detector {\n\treturn async function detectAny(api) {\n\t\tfor (const detector of detectors) {\n\t\t\tconst result = await detector(api)\n\t\t\tif (result.ok) return ok()\n\t\t}\n\t\treturn err({ reasons: [\"no-detector-matched\"] })\n\t}\n}\n\n/** Negate a detector: passes when the wrapped detector fails. */\nexport function not(detector: Detector, reasons: readonly string[]): Detector {\n\treturn async function detectNot(api) {\n\t\tconst result = await detector(api)\n\t\treturn result.ok ? err({ reasons }) : ok()\n\t}\n}\n\n/**\n * Detect when the resource has at least one file with any of the given\n * extensions.\n *\n * Extension matching is the fast path: it costs one filename comparison\n * and no reads. It is also only as good as the names — reach for\n * {@link hasKind} or {@link hasMime} when the archive may carry\n * mislabelled or extension-less files.\n */\nexport function hasExt(extensions: ReadonlySet<string>): Detector {\n\treturn async function detectHasExt(api) {\n\t\tconst files = await api.listFileNames()\n\t\tconst has = files.some((name) => extensions.has(extname(name)))\n\t\treturn has ? ok() : err({ reasons: [\"required-extension\"] })\n\t}\n}\n\n/**\n * Detect when at least one file's **content** belongs to `kind`. Reads a\n * small header per file (bounded fan-out, short-circuits on the first\n * match), so a resource of images detects as such no matter what the\n * files are called.\n */\nexport function hasKind(kind: MediaKind): Detector {\n\treturn async function detectHasKind(api) {\n\t\tconst matched = await someFileType(api, (type) => type.kind === kind)\n\t\treturn matched ? ok() : err({ reasons: [`required-kind:${kind}`] })\n\t}\n}\n\n/**\n * Detect when at least one file's sniffed MIME type matches `pattern` —\n * the content-based counterpart of {@link hasName}, for formats a media\n * kind cannot express (`application/epub+zip`, `application/pdf`).\n *\n * A string matches by exact equality (use a `RegExp` for prefix or\n * wildcard matching).\n */\nexport function hasMime(pattern: RegExp | string): Detector {\n\treturn async function detectHasMime(api) {\n\t\tconst matched = await someFileType(api, (type) =>\n\t\t\ttypeof pattern === \"string\"\n\t\t\t\t? type.mime === pattern\n\t\t\t\t: pattern.test(type.mime),\n\t\t)\n\t\treturn matched ? ok() : err({ reasons: [\"required-mime\"] })\n\t}\n}\n\n/**\n * True when any file's sniffed type satisfies `predicate`. Files are\n * sniffed in bounded parallel batches and the walk stops at the first\n * match, so a 10k-entry archive does not pay for a full scan.\n */\nasync function someFileType(\n\tapi: ResourceAPI,\n\tpredicate: (\n\t\ttype: NonNullable<Awaited<ReturnType<ResourceAPI[\"sniff\"]>>>,\n\t) => boolean,\n): Promise<boolean> {\n\tconst files = await api.listFileNames()\n\tfor (let i = 0; i < files.length; i += SNIFF_CONCURRENCY) {\n\t\tconst batch = files.slice(i, i + SNIFF_CONCURRENCY)\n\t\tconst types = await mapConcurrent(batch, SNIFF_CONCURRENCY, (name) =>\n\t\t\tapi.sniff(name),\n\t\t)\n\t\tif (types.some((type) => type !== undefined && predicate(type))) return true\n\t}\n\treturn false\n}\n\n/** Detect when the resource has a file whose name matches the given regex. */\nexport function hasName(pattern: RegExp): Detector {\n\treturn async function detectHasName(api) {\n\t\tconst files = await api.listFileNames()\n\t\tconst has = files.some((name) => pattern.test(name))\n\t\treturn has ? ok() : err({ reasons: [\"required-file\"] })\n\t}\n}\n\n/** Detect when the resource has at least `count` files. */\nexport function minFiles(count: number): Detector {\n\treturn async function detectMinFiles(api) {\n\t\tconst files = await api.listFileNames()\n\t\treturn files.length >= count\n\t\t\t? ok()\n\t\t\t: err({ reasons: [\"insufficient-files\"] })\n\t}\n}\n\n/** File-selection helpers that operate on a {@link ResourceAPI}. */\nexport const files = {\n\t/**\n\t * Return the first file matching any of the given extension sets,\n\t * or `undefined` when none match.\n\t */\n\tasync firstMatching(\n\t\tapi: ResourceAPI,\n\t\t...extensions: readonly ReadonlySet<string>[]\n\t): Promise<string | undefined> {\n\t\tconst allFiles = await api.listFileNames()\n\t\tfor (const filename of allFiles) {\n\t\t\tconst ext = extname(filename)\n\t\t\tfor (const set of extensions) {\n\t\t\t\tif (set.has(ext)) return filename\n\t\t\t}\n\t\t}\n\t\treturn undefined\n\t},\n\n\t/**\n\t * Return the first file whose **content** belongs to one of the given\n\t * media kinds, or `undefined` when none does. The content-based\n\t * counterpart of {@link files.firstMatching} — pick it when the\n\t * chosen file is going to be decoded anyway (a cover, a first page),\n\t * where a mislabelled name would otherwise cost a failed render.\n\t */\n\tasync firstOfKind(\n\t\tapi: ResourceAPI,\n\t\t...kinds: readonly MediaKind[]\n\t): Promise<string | undefined> {\n\t\tconst wanted = new Set<MediaKind>(kinds)\n\t\tconst allFiles = await api.listFileNames()\n\t\tfor (let i = 0; i < allFiles.length; i += SNIFF_CONCURRENCY) {\n\t\t\tconst batch = allFiles.slice(i, i + SNIFF_CONCURRENCY)\n\t\t\tconst types = await mapConcurrent(batch, SNIFF_CONCURRENCY, (name) =>\n\t\t\t\tapi.sniff(name),\n\t\t\t)\n\t\t\tconst hit = types.findIndex(\n\t\t\t\t(type) => type !== undefined && wanted.has(type.kind),\n\t\t\t)\n\t\t\tif (hit !== -1) return batch[hit]\n\t\t}\n\t\treturn undefined\n\t},\n} as const\n"]}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@hoardodile/sdk-server",
+  "version": "0.0.0",
+  "license": "MIT",
+  "description": "Authoring SDK for hoardodile content plugins: definePlugin, detectors and helpers.",
+  "keywords": [
+    "hoardodile",
+    "plugin",
+    "sdk"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hoardodile/hoardodile.git",
+    "directory": "plugins/sdk-server"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "development": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./helpers": {
+      "types": "./dist/helpers.d.ts",
+      "development": "./src/helpers.ts",
+      "default": "./dist/helpers.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@hoardodile/sdk-types": "0.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "tsup": "^8.5.1",
+    "typescript": "5.9.3",
+    "vitest": "^4.1.11"
+  },
+  "scripts": {
+    "build": "tsup",
+    "lint": "tsc --noEmit",
+    "test": "vitest run --maxWorkers=2"
+  }
+}

package/src/detectors.test.ts

@@ -0,0 +1,115 @@
+import { createResourceAPIFixture } from "@hoardodile/sdk-types"
+import { describe, expect, test } from "vitest"
+import { files, hasExt, hasKind, hasMime } from "./detectors.ts"
+
+/**
+ * The content-aware detectors are what make a plugin robust against
+ * mislabelled archives, so every case here pits the filename against
+ * the sniffed type.
+ */
+
+describe("hasKind", () => {
+	test("matches on content even when the extension lies", async () => {
+		const { api } = createResourceAPIFixture({
+			files: ["scan.dat"],
+			types: {
+				"scan.dat": {
+					mime: "image/jpeg",
+					ext: ".jpg",
+					kind: "image",
+					source: "magic",
+				},
+			},
+		})
+		await expect(hasKind("image")(api)).resolves.toEqual({ ok: true })
+		// The extension detector, by contrast, sees nothing.
+		await expect(hasExt(new Set([".jpg"]))(api)).resolves.toEqual({
+			ok: false,
+			reasons: ["required-extension"],
+		})
+	})
+
+	test("misses when no file carries the kind", async () => {
+		const { api } = createResourceAPIFixture({ files: ["notes.txt"] })
+		await expect(hasKind("video")(api)).resolves.toEqual({
+			ok: false,
+			reasons: ["required-kind:video"],
+		})
+	})
+
+	test("scans past the first batch of files", async () => {
+		const names = Array.from({ length: 30 }, (_, i) => `${i}.txt`)
+		const { api } = createResourceAPIFixture({
+			files: [...names, "late.png"],
+		})
+		await expect(hasKind("image")(api)).resolves.toEqual({ ok: true })
+	})
+})
+
+describe("hasMime", () => {
+	test("matches formats a media kind cannot express", async () => {
+		const { api } = createResourceAPIFixture({
+			files: ["book.bin"],
+			types: {
+				"book.bin": {
+					mime: "application/epub+zip",
+					ext: ".epub",
+					kind: "other",
+					source: "magic",
+				},
+			},
+		})
+		await expect(hasMime(/^application\/epub/)(api)).resolves.toEqual({
+			ok: true,
+		})
+		await expect(hasMime(/^application\/pdf/)(api)).resolves.toEqual({
+			ok: false,
+			reasons: ["required-mime"],
+		})
+	})
+
+	test("a string matches by exact equality", async () => {
+		const { api } = createResourceAPIFixture({
+			files: ["book.bin"],
+			types: {
+				"book.bin": {
+					mime: "application/epub+zip",
+					ext: ".epub",
+					kind: "other",
+					source: "magic",
+				},
+			},
+		})
+		await expect(hasMime("application/epub+zip")(api)).resolves.toEqual({
+			ok: true,
+		})
+		await expect(hasMime("application/pdf")(api)).resolves.toEqual({
+			ok: false,
+			reasons: ["required-mime"],
+		})
+	})
+})
+
+describe("files.firstOfKind", () => {
+	test("returns the first file whose content matches", async () => {
+		const { api } = createResourceAPIFixture({
+			files: ["readme.txt", "cover.bin", "page.png"],
+			types: {
+				"cover.bin": {
+					mime: "image/webp",
+					ext: ".webp",
+					kind: "image",
+					source: "magic",
+				},
+			},
+		})
+		await expect(files.firstOfKind(api, "image")).resolves.toBe("cover.bin")
+	})
+
+	test("resolves to undefined when nothing matches", async () => {
+		const { api } = createResourceAPIFixture({ files: ["readme.txt"] })
+		await expect(
+			files.firstOfKind(api, "image", "video"),
+		).resolves.toBeUndefined()
+	})
+})

package/src/detectors.ts

@@ -0,0 +1,177 @@
+import type { Detection, ResourceAPI } from "@hoardodile/sdk-types"
+import { err, ok } from "@hoardodile/sdk-types"
+import type { MediaKind } from "@hoardodile/sdk-types/media-exts"
+import { extname, mapConcurrent } from "./helpers.ts"
+
+/** A detector evaluates a resource and returns a {@link Detection}. */
+export type Detector = (api: ResourceAPI) => Promise<Detection>
+
+/** Sniff fan-out bound: detection reads a small header per candidate. */
+const SNIFF_CONCURRENCY = 8
+
+/** Detect when all given detectors pass. */
+export function all(...detectors: readonly Detector[]): Detector {
+	return async function detectAll(api) {
+		for (const detector of detectors) {
+			const result = await detector(api)
+			if (!result.ok) return result
+		}
+		return ok()
+	}
+}
+
+/** Detect when at least one given detector passes. */
+export function any(...detectors: readonly Detector[]): Detector {
+	return async function detectAny(api) {
+		for (const detector of detectors) {
+			const result = await detector(api)
+			if (result.ok) return ok()
+		}
+		return err({ reasons: ["no-detector-matched"] })
+	}
+}
+
+/** Negate a detector: passes when the wrapped detector fails. */
+export function not(detector: Detector, reasons: readonly string[]): Detector {
+	return async function detectNot(api) {
+		const result = await detector(api)
+		return result.ok ? err({ reasons }) : ok()
+	}
+}
+
+/**
+ * Detect when the resource has at least one file with any of the given
+ * extensions.
+ *
+ * Extension matching is the fast path: it costs one filename comparison
+ * and no reads. It is also only as good as the names — reach for
+ * {@link hasKind} or {@link hasMime} when the archive may carry
+ * mislabelled or extension-less files.
+ */
+export function hasExt(extensions: ReadonlySet<string>): Detector {
+	return async function detectHasExt(api) {
+		const files = await api.listFileNames()
+		const has = files.some((name) => extensions.has(extname(name)))
+		return has ? ok() : err({ reasons: ["required-extension"] })
+	}
+}
+
+/**
+ * Detect when at least one file's **content** belongs to `kind`. Reads a
+ * small header per file (bounded fan-out, short-circuits on the first
+ * match), so a resource of images detects as such no matter what the
+ * files are called.
+ */
+export function hasKind(kind: MediaKind): Detector {
+	return async function detectHasKind(api) {
+		const matched = await someFileType(api, (type) => type.kind === kind)
+		return matched ? ok() : err({ reasons: [`required-kind:${kind}`] })
+	}
+}
+
+/**
+ * Detect when at least one file's sniffed MIME type matches `pattern` —
+ * the content-based counterpart of {@link hasName}, for formats a media
+ * kind cannot express (`application/epub+zip`, `application/pdf`).
+ *
+ * A string matches by exact equality (use a `RegExp` for prefix or
+ * wildcard matching).
+ */
+export function hasMime(pattern: RegExp | string): Detector {
+	return async function detectHasMime(api) {
+		const matched = await someFileType(api, (type) =>
+			typeof pattern === "string"
+				? type.mime === pattern
+				: pattern.test(type.mime),
+		)
+		return matched ? ok() : err({ reasons: ["required-mime"] })
+	}
+}
+
+/**
+ * True when any file's sniffed type satisfies `predicate`. Files are
+ * sniffed in bounded parallel batches and the walk stops at the first
+ * match, so a 10k-entry archive does not pay for a full scan.
+ */
+async function someFileType(
+	api: ResourceAPI,
+	predicate: (
+		type: NonNullable<Awaited<ReturnType<ResourceAPI["sniff"]>>>,
+	) => boolean,
+): Promise<boolean> {
+	const files = await api.listFileNames()
+	for (let i = 0; i < files.length; i += SNIFF_CONCURRENCY) {
+		const batch = files.slice(i, i + SNIFF_CONCURRENCY)
+		const types = await mapConcurrent(batch, SNIFF_CONCURRENCY, (name) =>
+			api.sniff(name),
+		)
+		if (types.some((type) => type !== undefined && predicate(type))) return true
+	}
+	return false
+}
+
+/** Detect when the resource has a file whose name matches the given regex. */
+export function hasName(pattern: RegExp): Detector {
+	return async function detectHasName(api) {
+		const files = await api.listFileNames()
+		const has = files.some((name) => pattern.test(name))
+		return has ? ok() : err({ reasons: ["required-file"] })
+	}
+}
+
+/** Detect when the resource has at least `count` files. */
+export function minFiles(count: number): Detector {
+	return async function detectMinFiles(api) {
+		const files = await api.listFileNames()
+		return files.length >= count
+			? ok()
+			: err({ reasons: ["insufficient-files"] })
+	}
+}
+
+/** File-selection helpers that operate on a {@link ResourceAPI}. */
+export const files = {
+	/**
+	 * Return the first file matching any of the given extension sets,
+	 * or `undefined` when none match.
+	 */
+	async firstMatching(
+		api: ResourceAPI,
+		...extensions: readonly ReadonlySet<string>[]
+	): Promise<string | undefined> {
+		const allFiles = await api.listFileNames()
+		for (const filename of allFiles) {
+			const ext = extname(filename)
+			for (const set of extensions) {
+				if (set.has(ext)) return filename
+			}
+		}
+		return undefined
+	},
+
+	/**
+	 * Return the first file whose **content** belongs to one of the given
+	 * media kinds, or `undefined` when none does. The content-based
+	 * counterpart of {@link files.firstMatching} — pick it when the
+	 * chosen file is going to be decoded anyway (a cover, a first page),
+	 * where a mislabelled name would otherwise cost a failed render.
+	 */
+	async firstOfKind(
+		api: ResourceAPI,
+		...kinds: readonly MediaKind[]
+	): Promise<string | undefined> {
+		const wanted = new Set<MediaKind>(kinds)
+		const allFiles = await api.listFileNames()
+		for (let i = 0; i < allFiles.length; i += SNIFF_CONCURRENCY) {
+			const batch = allFiles.slice(i, i + SNIFF_CONCURRENCY)
+			const types = await mapConcurrent(batch, SNIFF_CONCURRENCY, (name) =>
+				api.sniff(name),
+			)
+			const hit = types.findIndex(
+				(type) => type !== undefined && wanted.has(type.kind),
+			)
+			if (hit !== -1) return batch[hit]
+		}
+		return undefined
+	},
+} as const

package/src/helpers.test.ts

@@ -0,0 +1,250 @@
+import { createResourceAPIFixture } from "@hoardodile/sdk-types"
+import { describe, expect, test } from "vitest"
+import {
+	countSourceMeta,
+	imageHashesFor,
+	imageHashesForFile,
+	mapConcurrent,
+	mediaFileList,
+} from "./helpers.ts"
+
+describe("mapConcurrent", () => {
+	test("maps every item and preserves input order", async () => {
+		const items = Array.from({ length: 20 }, (_, i) => i)
+		const result = await mapConcurrent(items, 4, async (n) => {
+			// Later items resolve faster — order must still follow the input.
+			await new Promise((resolve) => setTimeout(resolve, 20 - n))
+			return n * 10
+		})
+		expect(result).toEqual(items.map((n) => n * 10))
+	})
+
+	test("never exceeds the concurrency limit", async () => {
+		let inFlight = 0
+		let maxInFlight = 0
+		const items = Array.from({ length: 30 }, (_, i) => i)
+		await mapConcurrent(items, 5, async () => {
+			inFlight++
+			maxInFlight = Math.max(maxInFlight, inFlight)
+			await new Promise((resolve) => setTimeout(resolve, 2))
+			inFlight--
+		})
+		expect(maxInFlight).toBe(5)
+	})
+
+	test("runs fully in parallel when the limit covers all items", async () => {
+		let inFlight = 0
+		let maxInFlight = 0
+		await mapConcurrent([1, 2, 3], 10, async () => {
+			inFlight++
+			maxInFlight = Math.max(maxInFlight, inFlight)
+			await new Promise((resolve) => setTimeout(resolve, 2))
+			inFlight--
+		})
+		expect(maxInFlight).toBe(3)
+	})
+
+	test("propagates the first rejection", async () => {
+		await expect(
+			mapConcurrent([1, 2, 3], 2, async (n) => {
+				if (n === 2) throw new Error("boom")
+				await new Promise((resolve) => setTimeout(resolve, 5))
+				return n
+			}),
+		).rejects.toThrow("boom")
+	})
+
+	test("handles an empty input", async () => {
+		await expect(mapConcurrent([], 4, async () => 1)).resolves.toEqual([])
+	})
+})
+
+describe("imageHashesForFile", () => {
+	test("maps the requested kinds to ImageHash entries", async () => {
+		const fixture = createResourceAPIFixture({
+			imageHashes: {
+				"1.jpg": {
+					hashes: [
+						{ scope: "1.jpg", type: "sha256", value: "aa" },
+						{ scope: "1.jpg", type: "dhash", value: "bb" },
+						{ scope: "1.jpg", type: "phash", value: "cc" },
+					],
+				},
+			},
+		})
+		await expect(
+			imageHashesForFile(fixture.api, "1.jpg", ["sha256", "dhash", "phash"]),
+		).resolves.toEqual([
+			{ scope: "1.jpg", type: "sha256", value: "aa" },
+			{ scope: "1.jpg", type: "dhash", value: "bb" },
+			{ scope: "1.jpg", type: "phash", value: "cc" },
+		])
+	})
+
+	test("only returns the requested kinds", async () => {
+		const fixture = createResourceAPIFixture({
+			imageHashes: {
+				"1.jpg": {
+					hashes: [
+						{ scope: "1.jpg", type: "sha256", value: "aa" },
+						{ scope: "1.jpg", type: "dhash", value: "bb" },
+					],
+				},
+			},
+		})
+		await expect(
+			imageHashesForFile(fixture.api, "1.jpg", ["dhash"]),
+		).resolves.toEqual([{ scope: "1.jpg", type: "dhash", value: "bb" }])
+	})
+
+	test("resolves to [] for undecodable files", async () => {
+		const fixture = createResourceAPIFixture()
+		await expect(
+			imageHashesForFile(fixture.api, "broken.png"),
+		).resolves.toEqual([])
+	})
+})
+
+describe("imageHashesFor", () => {
+	test("hashes every image file and skips non-images", async () => {
+		const fixture = createResourceAPIFixture({
+			files: ["1.jpg", "2.png", "readme.txt"],
+			imageHashes: {
+				"1.jpg": {
+					hashes: [
+						{ scope: "1.jpg", type: "sha256", value: "aa" },
+						{ scope: "1.jpg", type: "dhash", value: "bb" },
+					],
+				},
+				"2.png": {
+					hashes: [
+						{ scope: "2.png", type: "sha256", value: "cc" },
+						{ scope: "2.png", type: "dhash", value: "dd" },
+					],
+				},
+			},
+		})
+		await expect(imageHashesFor(fixture.api)).resolves.toEqual({
+			hashes: [
+				{ scope: "1.jpg", type: "sha256", value: "aa" },
+				{ scope: "1.jpg", type: "dhash", value: "bb" },
+				{ scope: "2.png", type: "sha256", value: "cc" },
+				{ scope: "2.png", type: "dhash", value: "dd" },
+			],
+		})
+	})
+
+	test("defaults to sha256 + dhash and tolerates partial results", async () => {
+		const fixture = createResourceAPIFixture({
+			files: ["1.jpg"],
+			imageHashes: {
+				"1.jpg": {
+					hashes: [{ scope: "1.jpg", type: "dhash", value: "bb" }],
+				},
+			},
+		})
+		await expect(imageHashesFor(fixture.api)).resolves.toEqual({
+			hashes: [{ scope: "1.jpg", type: "dhash", value: "bb" }],
+		})
+	})
+
+	test("returns an empty list for image-less resources", async () => {
+		const fixture = createResourceAPIFixture({ files: ["notes.txt"] })
+		await expect(imageHashesFor(fixture.api)).resolves.toEqual({ hashes: [] })
+	})
+})
+
+describe("mediaFileList", () => {
+	test("lists every decodable media file in canonical order", async () => {
+		const fixture = createResourceAPIFixture({
+			files: ["10.jpg", "2.jpg", "01.mp4", "track.mp3", "readme.txt"],
+			probes: {
+				".mp4": {
+					kind: "video",
+					mime: "video/mp4",
+					width: 640,
+					height: 480,
+					durationMs: 1000,
+				},
+				".mp3": { kind: "audio", mime: "audio/mpeg", durationMs: 3000 },
+				"": {
+					kind: "image",
+					mime: "image/jpeg",
+					width: 800,
+					height: 1200,
+					animated: false,
+				},
+			},
+		})
+		const result = await mediaFileList(fixture.api)
+		expect(result.map((entry) => entry.filename)).toEqual([
+			"10.jpg",
+			"2.jpg",
+			"01.mp4",
+			"track.mp3",
+		])
+		expect(result[0]).toMatchObject({ type: "image", width: 800 })
+		expect(result[1]).toMatchObject({ type: "image", width: 800 })
+		expect(result[2]).toMatchObject({
+			type: "video",
+			width: 640,
+			durationMs: 1000,
+			sniffed: { mime: "video/mp4" },
+		})
+		expect(result[3]).toMatchObject({ type: "audio", durationMs: 3000 })
+	})
+
+	test("accepts a pre-filtered name list without re-listing", async () => {
+		const fixture = createResourceAPIFixture({
+			files: ["a.jpg", "sub/b.jpg"],
+			probes: {
+				"": {
+					kind: "image",
+					mime: "image/jpeg",
+					width: 10,
+					height: 10,
+					animated: false,
+				},
+			},
+		})
+		const result = await mediaFileList(fixture.api, {
+			names: ["a.jpg"],
+		})
+		expect(result.map((entry) => entry.filename)).toEqual(["a.jpg"])
+	})
+
+	test("drops files that are not decodable media", async () => {
+		const fixture = createResourceAPIFixture({
+			files: ["a.jpg", "notes.txt"],
+			probes: {
+				"": {
+					kind: "other",
+					mime: "text/plain",
+				},
+			},
+			types: {
+				"a.jpg": {
+					mime: "image/jpeg",
+					ext: ".jpg",
+					kind: "image",
+					source: "magic",
+				},
+			},
+		})
+		await expect(mediaFileList(fixture.api)).resolves.toEqual([])
+	})
+})
+
+describe("countSourceMeta", () => {
+	test("reports the file count", async () => {
+		const fixture = createResourceAPIFixture({ files: ["a", "b", "c"] })
+		await expect(countSourceMeta(fixture.api)).resolves.toEqual({
+			fileCount: 3,
+		})
+	})
+
+	test("resolves to undefined for empty resources", async () => {
+		const fixture = createResourceAPIFixture()
+		await expect(countSourceMeta(fixture.api)).resolves.toBeUndefined()
+	})
+})