@hoardodile/sdk-server 0.0.0

package/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 Wooloo <ayan0312000@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+# @hoardodile/sdk-server
+
+The authoring surface for hoardodile content plugin `main.js` files — the
+**only** package you need on the server side of a plugin.
+
+## Install
+
+```bash
+pnpm add @hoardodile/sdk-server
+```
+
+## What's in it
+
+- **`definePlugin()`** — declarative plugin definition with runtime shape
+  validation (unknown hooks and synchronous hooks are rejected at load
+  time, not at hook time)
+- **Composable detectors** — `hasKind`, `hasMime`, `hasExt`, `hasName`,
+  `minFiles`, `all`, `any`, `not`, `files`
+- **`ResourceAPI`** — the typed, resource-scoped API every hook receives
+  (`listFiles`, `readFile`, `statFile`, `statFiles`, `sniff`, `probe`,
+  `hashBytes`, `computeImageHashes`, scoped logging)
+- **Fixtures** — `createResourceAPIFixture`, `stubLogger` for unit tests
+
+## Quick start
+
+```ts
+// src/main.ts
+import { any, definePlugin, hasKind } from "@hoardodile/sdk-server"
+import { probeMediaFile } from "@hoardodile/sdk-server/helpers"
+
+export default definePlugin({
+	// Content decides, so mislabelled and extension-less files still match.
+	detect: any(hasKind("image"), hasKind("video")),
+	sourceMeta: async (api) => {
+		const files = await api.listFileNames()
+		return {
+			files,
+			previews: await Promise.all(files.map((f) => probeMediaFile(api, f))),
+		}
+	},
+})
+```
+
+## Subpaths
+
+| Entry | Contents |
+| ----- | -------- |
+| `@hoardodile/sdk-server` | The authoring surface (root) |
+| `@hoardodile/sdk-server/helpers` | Probe/file helpers: `extname`, `mapConcurrent`, `naturalSort`, `probeMediaFile`, `probeImageFile`, `probeVideoFile`, `probeAudioFile`, `readFileChunks` |
+
+## Where does the code live?
+
+`definePlugin`, `ResourceAPI`, the fixtures and the hook-name contract
+are implemented in `@hoardodile/sdk-types` and re-exported here so
+plugin authors have a single import root. This package is
+dependency-closed within the SDK — it never imports `@hoardodile/host`.
+Dev-time test tooling (`runPluginHook`, `createDirectoryResourceAPI`) is
+available from `@hoardodile/host` as a **devDependency** (never bundled
+into the shipped plugin): it runs hooks against a real directory for
+Layer-2 tests.
+
+## Licensing
+
+MIT. The plugin contract, the SDK packages and the plugin code you write
+are all permissive — a plugin built with this SDK is an independent
+work and can be released under any license (MIT, GPL, proprietary, or
+none at all).

package/dist/helpers.d.ts

@@ -0,0 +1,121 @@
+import { ImageHashKind, FileType, ResourceAPI, ImageHashesResult, ImageHash } from '@hoardodile/sdk-types';
+
+/** Return the lower-cased extension from the last dot, or `""` when there is none. */
+declare function extname(filename: string): string;
+/** Natural-sort filenames (case-insensitive, numeric). Mutates and returns. */
+declare function naturalSort(files: readonly string[]): string[];
+/**
+ * Map items with at most `limit` promises in flight. Results keep input
+ * order; the first rejection aborts the map (in-flight calls settle).
+ * Probe loops use this to fan out across the host's concurrent API
+ * dispatch instead of trickling one RPC at a time.
+ */
+declare function mapConcurrent<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
+/** File-list item shapes produced by the probe helpers. */
+type ProbedImageFile = {
+    readonly type: "image";
+    readonly width?: number;
+    readonly height?: number;
+    readonly preview: boolean;
+};
+type ProbedVideoFile = {
+    readonly type: "video";
+    readonly width?: number;
+    readonly height?: number;
+    readonly durationMs?: number;
+};
+type ProbedAudioFile = {
+    readonly type: "audio";
+    readonly durationMs?: number;
+    readonly hasCoverArt?: boolean;
+};
+/**
+ * Probe a file and return the file-item shaped object matching what the
+ * content actually is, or `undefined` for non-media files. This is the
+ * primitive: plugins that accept mixed media route on the result
+ * instead of pre-sorting by extension, and the three per-kind helpers
+ * below are thin narrowings of it.
+ *
+ * When identification succeeds but decoding does not (no ffprobe on the
+ * host, a damaged container), the file keeps its media type and simply
+ * carries no dimensions — losing the entry entirely would be worse than
+ * showing it undecorated.
+ */
+declare function probeMediaFile(api: ResourceAPI, filename: string): Promise<ProbedImageFile | ProbedVideoFile | ProbedAudioFile | undefined>;
+/**
+ * Probe a file expected to be an image. A file that turns out not to be
+ * one still yields an image-shaped item (with no dimensions), so a file
+ * list keeps its declared type.
+ */
+declare function probeImageFile(api: ResourceAPI, filename: string): Promise<ProbedImageFile>;
+/** Probe a file expected to be a video. See {@link probeImageFile}. */
+declare function probeVideoFile(api: ResourceAPI, filename: string): Promise<ProbedVideoFile>;
+/** Probe a file expected to be audio. See {@link probeImageFile}. */
+declare function probeAudioFile(api: ResourceAPI, filename: string): Promise<ProbedAudioFile>;
+/**
+ * One entry of {@link mediaFileList}: the filename plus everything the
+ * probe pass learned about the file (`sniffed` is the sniffed type that
+ * decided the probe lane — the same data the entry's dimensions were
+ * routed on).
+ */
+type MediaFileListEntry = {
+    readonly filename: string;
+    readonly sniffed?: FileType;
+} & (ProbedImageFile | ProbedVideoFile | ProbedAudioFile);
+type MediaFileListOptions = {
+    /**
+     * Candidate names to probe. When absent the helper lists the
+     * resource itself (natural-sorted). Pass a pre-filtered list (e.g.
+     * top-level files only) to skip names the plugin never wants.
+     */
+    readonly names?: readonly string[];
+};
+/**
+ * Build a typed media file list in one pass: sniff every candidate,
+ * then probe images and timed media (video/audio) in separate bounded
+ * lanes — sharp header reads fan out wider than ffprobe spawns. The
+ * result keeps input order and drops files that are not decodable
+ * media. The one-call implementation for a `listFiles` hook over a
+ * flat media resource.
+ */
+declare function mediaFileList(api: ResourceAPI, opts?: MediaFileListOptions): Promise<readonly MediaFileListEntry[]>;
+/**
+ * The `sourceMeta` for a bare file count — the one-liner for plugins
+ * whose card needs only `fileCount`. Resolves to `undefined` for empty
+ * resources, matching the host's "nothing to report" contract.
+ */
+declare function countSourceMeta(api: ResourceAPI): Promise<{
+    readonly fileCount: number;
+} | undefined>;
+type ReadFileChunksOptions = {
+    /** Chunk size in bytes. Defaults to 1 MiB. */
+    readonly chunkSize?: number;
+};
+/**
+ * Stream a file as a sequence of chunks via ranged `readFile` calls.
+ * Memory stays bounded by the chunk size on both sides of the plugin
+ * boundary — the host never buffers the whole file.
+ */
+declare function readFileChunks(api: ResourceAPI, path: string, opts?: ReadFileChunksOptions): AsyncGenerator<Uint8Array, void, undefined>;
+/** Per-file default hash kinds for {@link imageHashesFor}. */
+declare const DEFAULT_IMAGE_HASH_KINDS: readonly ImageHashKind[];
+type ImageHashesForOptions = {
+    /** Hash kinds per image. Defaults to sha256 + dhash. */
+    readonly kinds?: readonly ImageHashKind[];
+};
+/**
+ * Compute the requested hash kinds of one image file as `ImageHash`
+ * entries (`scope` = the file path). Resolves to `[]` for non-image or
+ * undecodable files.
+ */
+declare function imageHashesForFile(api: ResourceAPI, scope: string, kinds?: readonly ImageHashKind[]): Promise<readonly ImageHash[]>;
+/**
+ * One-line `imageHashes` hook implementation for image plugins: hash
+ * every image file of the resource (animated sources hash their first
+ * frame). Image files are selected by content, so a mislabelled photo
+ * is still deduplicated. Plugins facing image-less resources omit the
+ * hook entirely.
+ */
+declare function imageHashesFor(api: ResourceAPI, opts?: ImageHashesForOptions): Promise<ImageHashesResult>;
+
+export { DEFAULT_IMAGE_HASH_KINDS, type ImageHashesForOptions, type MediaFileListEntry, type MediaFileListOptions, type ReadFileChunksOptions, countSourceMeta, extname, imageHashesFor, imageHashesForFile, mapConcurrent, mediaFileList, naturalSort, probeAudioFile, probeImageFile, probeMediaFile, probeVideoFile, readFileChunks };

package/dist/helpers.js

@@ -0,0 +1,183 @@
+import { PLUGIN_IMAGE_PROBE_CONCURRENCY, PLUGIN_VIDEO_PROBE_CONCURRENCY } from '@hoardodile/sdk-types/plugin';
+import { RESOURCE_PREVIEW_MAX_AREA, RESOURCE_PREVIEW_SIZE_THRESHOLD } from '@hoardodile/sdk-types/resource';
+
+// src/helpers.ts
+function exceedsPreviewThresholds(check) {
+  const { width, height, sizeBytes } = check;
+  const exceedsArea = width !== void 0 && height !== void 0 && width * height > RESOURCE_PREVIEW_MAX_AREA;
+  const exceedsSize = sizeBytes !== void 0 && sizeBytes > RESOURCE_PREVIEW_SIZE_THRESHOLD;
+  return exceedsArea || exceedsSize;
+}
+function extname(filename) {
+  const dot = filename.lastIndexOf(".");
+  if (dot === -1) return "";
+  return filename.slice(dot).toLowerCase();
+}
+function naturalSort(files) {
+  return [...files].sort(
+    (a, b) => a.localeCompare(b, void 0, { sensitivity: "base", numeric: true })
+  );
+}
+async function mapConcurrent(items, limit, fn) {
+  const results = new Array(items.length);
+  let next = 0;
+  async function lane() {
+    for (; ; ) {
+      const index = next++;
+      if (index >= items.length) return;
+      const item = items[index];
+      if (item === void 0) continue;
+      results[index] = await fn(item, index);
+    }
+  }
+  const lanes = Math.max(1, Math.min(limit, items.length));
+  const runners = [];
+  for (let i = 0; i < lanes; i++) runners.push(lane());
+  await Promise.all(runners);
+  return results;
+}
+async function probeMediaFile(api, filename) {
+  const probed = await api.probe(filename);
+  switch (probed.kind) {
+    case "image": {
+      const { width, height } = probed;
+      const sizeBytes = (await api.statFile(filename))?.sizeBytes;
+      return {
+        type: "image",
+        width,
+        height,
+        preview: exceedsPreviewThresholds({ width, height, sizeBytes })
+      };
+    }
+    case "video":
+      return {
+        type: "video",
+        width: probed.width,
+        height: probed.height,
+        durationMs: probed.durationMs
+      };
+    case "audio":
+      return {
+        type: "audio",
+        durationMs: probed.durationMs,
+        hasCoverArt: probed.coverArt === void 0 ? void 0 : true
+      };
+    case "other":
+      return void 0;
+    default:
+      return undecodedItem(await api.sniff(filename));
+  }
+}
+function undecodedItem(type) {
+  switch (type?.kind) {
+    case "image":
+      return { type: "image", preview: false };
+    case "video":
+      return { type: "video" };
+    case "audio":
+      return { type: "audio" };
+    default:
+      return void 0;
+  }
+}
+async function probeImageFile(api, filename) {
+  const item = await probeMediaFile(api, filename);
+  return item?.type === "image" ? item : { type: "image", preview: false };
+}
+async function probeVideoFile(api, filename) {
+  const item = await probeMediaFile(api, filename);
+  return item?.type === "video" ? item : { type: "video" };
+}
+async function probeAudioFile(api, filename) {
+  const item = await probeMediaFile(api, filename);
+  return item?.type === "audio" ? item : { type: "audio" };
+}
+async function mediaFileList(api, opts = {}) {
+  const files = opts.names ?? await api.listFileNames();
+  const types = await mapConcurrent(
+    files,
+    PLUGIN_IMAGE_PROBE_CONCURRENCY,
+    (name) => api.sniff(name)
+  );
+  const entries = /* @__PURE__ */ new Map();
+  const imageIndexes = [];
+  const timedIndexes = [];
+  for (const index of files.keys()) {
+    const kind = types[index]?.kind;
+    if (kind === "image") imageIndexes.push(index);
+    else if (kind === "video" || kind === "audio") timedIndexes.push(index);
+  }
+  async function probeInto(index) {
+    const filename = files[index];
+    if (filename === void 0) return;
+    const probed = await probeMediaFile(api, filename);
+    if (probed === void 0) return;
+    entries.set(filename, {
+      filename,
+      sniffed: types[index],
+      ...probed
+    });
+  }
+  await Promise.all([
+    mapConcurrent(imageIndexes, PLUGIN_IMAGE_PROBE_CONCURRENCY, probeInto),
+    mapConcurrent(timedIndexes, PLUGIN_VIDEO_PROBE_CONCURRENCY, probeInto)
+  ]);
+  const result = [];
+  for (const filename of files) {
+    const entry = entries.get(filename);
+    if (entry !== void 0) result.push(entry);
+  }
+  return result;
+}
+async function countSourceMeta(api) {
+  const files = await api.listFileNames();
+  return files.length === 0 ? void 0 : { fileCount: files.length };
+}
+async function* readFileChunks(api, path, opts = {}) {
+  const chunkSize = opts.chunkSize ?? 1024 * 1024;
+  let offset = 0;
+  for (; ; ) {
+    const chunk = await api.readFile(path, {
+      start: offset,
+      end: offset + chunkSize
+    });
+    if (chunk.byteLength === 0) return;
+    yield chunk;
+    if (chunk.byteLength < chunkSize) return;
+    offset += chunk.byteLength;
+  }
+}
+var DEFAULT_IMAGE_HASH_KINDS = [
+  "sha256",
+  "dhash"
+];
+async function imageHashesForFile(api, scope, kinds = DEFAULT_IMAGE_HASH_KINDS) {
+  const computed = await api.computeImageHashes(scope, kinds);
+  if (computed === void 0) return [];
+  const entries = [];
+  for (const kind of kinds) {
+    const value = computed[kind];
+    if (value !== void 0) entries.push({ scope, type: kind, value });
+  }
+  return entries;
+}
+async function imageHashesFor(api, opts = {}) {
+  const kinds = opts.kinds ?? DEFAULT_IMAGE_HASH_KINDS;
+  const names = await api.listFileNames();
+  const types = await mapConcurrent(
+    names,
+    PLUGIN_IMAGE_PROBE_CONCURRENCY,
+    (name) => api.sniff(name)
+  );
+  const images = names.filter((_, i) => types[i]?.kind === "image");
+  const hashes = (await mapConcurrent(
+    images,
+    PLUGIN_IMAGE_PROBE_CONCURRENCY,
+    (filename) => imageHashesForFile(api, filename, kinds)
+  )).flat();
+  return { hashes };
+}
+
+export { DEFAULT_IMAGE_HASH_KINDS, countSourceMeta, extname, imageHashesFor, imageHashesForFile, mapConcurrent, mediaFileList, naturalSort, probeAudioFile, probeImageFile, probeMediaFile, probeVideoFile, readFileChunks };
+//# sourceMappingURL=helpers.js.map
+//# sourceMappingURL=helpers.js.map

package/dist/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/helpers.ts"],"names":[],"mappings":"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","file":"helpers.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"]}

package/dist/index.d.ts

@@ -0,0 +1,60 @@
+import { ResourceAPI, Detection } from '@hoardodile/sdk-types';
+export { ArchiveExtraction, ArchiveExtractionEntry, AudioCoverArt, AudioInfo, AudioTags, ContainerListing, Detection, FileType, ImageHash, ImageHashKind, ImageHashesResult, ImageInfo, Logger, MediaKind, PluginAssetDeleteResult, PluginAssetError, PluginAssetErrorName, PluginDefinition, PluginDownloadRequest, PluginDownloadResult, ProbeResult, ReadFileRange, ResourceAPI, ResourceAPIFixtureConfig, VideoInfo, assertPluginShape, createFailingPlugin, createResourceAPIFixture, definePlugin, err, fileTypeFromName, isDetected, isErr, isMissed, isOk, isPluginAssetError, matchResult, ok, pluginAssetError, stubLogger } from '@hoardodile/sdk-types';
+import { MediaKind } from '@hoardodile/sdk-types/media-exts';
+
+/** A detector evaluates a resource and returns a {@link Detection}. */
+type Detector = (api: ResourceAPI) => Promise<Detection>;
+/** Detect when all given detectors pass. */
+declare function all(...detectors: readonly Detector[]): Detector;
+/** Detect when at least one given detector passes. */
+declare function any(...detectors: readonly Detector[]): Detector;
+/** Negate a detector: passes when the wrapped detector fails. */
+declare function not(detector: Detector, reasons: readonly string[]): Detector;
+/**
+ * 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.
+ */
+declare function hasExt(extensions: ReadonlySet<string>): Detector;
+/**
+ * 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.
+ */
+declare function hasKind(kind: MediaKind): Detector;
+/**
+ * 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).
+ */
+declare function hasMime(pattern: RegExp | string): Detector;
+/** Detect when the resource has a file whose name matches the given regex. */
+declare function hasName(pattern: RegExp): Detector;
+/** Detect when the resource has at least `count` files. */
+declare function minFiles(count: number): Detector;
+/** File-selection helpers that operate on a {@link ResourceAPI}. */
+declare const files: {
+    /**
+     * Return the first file matching any of the given extension sets,
+     * or `undefined` when none match.
+     */
+    readonly firstMatching: (api: ResourceAPI, ...extensions: readonly ReadonlySet<string>[]) => Promise<string | 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.
+     */
+    readonly firstOfKind: (api: ResourceAPI, ...kinds: readonly MediaKind[]) => Promise<string | undefined>;
+};
+
+export { type Detector, all, any, files, hasExt, hasKind, hasMime, hasName, minFiles, not };

package/dist/index.js

@@ -0,0 +1,148 @@
+import { ok, err } from '@hoardodile/sdk-types';
+export { assertPluginShape, createFailingPlugin, createResourceAPIFixture, definePlugin, err, fileTypeFromName, isDetected, isErr, isMissed, isOk, isPluginAssetError, matchResult, ok, pluginAssetError, stubLogger } from '@hoardodile/sdk-types';
+import '@hoardodile/sdk-types/plugin';
+import '@hoardodile/sdk-types/resource';
+
+// src/index.ts
+function extname(filename) {
+  const dot = filename.lastIndexOf(".");
+  if (dot === -1) return "";
+  return filename.slice(dot).toLowerCase();
+}
+async function mapConcurrent(items, limit, fn) {
+  const results = new Array(items.length);
+  let next = 0;
+  async function lane() {
+    for (; ; ) {
+      const index = next++;
+      if (index >= items.length) return;
+      const item = items[index];
+      if (item === void 0) continue;
+      results[index] = await fn(item, index);
+    }
+  }
+  const lanes = Math.max(1, Math.min(limit, items.length));
+  const runners = [];
+  for (let i = 0; i < lanes; i++) runners.push(lane());
+  await Promise.all(runners);
+  return results;
+}
+
+// src/detectors.ts
+var SNIFF_CONCURRENCY = 8;
+function all(...detectors) {
+  return async function detectAll(api) {
+    for (const detector of detectors) {
+      const result = await detector(api);
+      if (!result.ok) return result;
+    }
+    return ok();
+  };
+}
+function any(...detectors) {
+  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"] });
+  };
+}
+function not(detector, reasons) {
+  return async function detectNot(api) {
+    const result = await detector(api);
+    return result.ok ? err({ reasons }) : ok();
+  };
+}
+function hasExt(extensions) {
+  return async function detectHasExt(api) {
+    const files2 = await api.listFileNames();
+    const has = files2.some((name) => extensions.has(extname(name)));
+    return has ? ok() : err({ reasons: ["required-extension"] });
+  };
+}
+function hasKind(kind) {
+  return async function detectHasKind(api) {
+    const matched = await someFileType(api, (type) => type.kind === kind);
+    return matched ? ok() : err({ reasons: [`required-kind:${kind}`] });
+  };
+}
+function hasMime(pattern) {
+  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"] });
+  };
+}
+async function someFileType(api, predicate) {
+  const files2 = await api.listFileNames();
+  for (let i = 0; i < files2.length; i += SNIFF_CONCURRENCY) {
+    const batch = files2.slice(i, i + SNIFF_CONCURRENCY);
+    const types = await mapConcurrent(
+      batch,
+      SNIFF_CONCURRENCY,
+      (name) => api.sniff(name)
+    );
+    if (types.some((type) => type !== void 0 && predicate(type))) return true;
+  }
+  return false;
+}
+function hasName(pattern) {
+  return async function detectHasName(api) {
+    const files2 = await api.listFileNames();
+    const has = files2.some((name) => pattern.test(name));
+    return has ? ok() : err({ reasons: ["required-file"] });
+  };
+}
+function minFiles(count) {
+  return async function detectMinFiles(api) {
+    const files2 = await api.listFileNames();
+    return files2.length >= count ? ok() : err({ reasons: ["insufficient-files"] });
+  };
+}
+var files = {
+  /**
+   * Return the first file matching any of the given extension sets,
+   * or `undefined` when none match.
+   */
+  async firstMatching(api, ...extensions) {
+    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 void 0;
+  },
+  /**
+   * 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, ...kinds) {
+    const wanted = new Set(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 !== void 0 && wanted.has(type.kind)
+      );
+      if (hit !== -1) return batch[hit];
+    }
+    return void 0;
+  }
+};
+
+export { all, any, files, hasExt, hasKind, hasMime, hasName, minFiles, not };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map