@shisho/plugin-sdk 0.0.33 → 0.0.35

package/hooks.d.ts

@@ -36,6 +36,18 @@ export interface SearchContext {
   file?: {
     /** File type extension (e.g., "epub", "cbz", "m4b", "pdf"). */
     fileType?: string;
+    /**
+     * Absolute path to the enrichment target file. The runtime grants the
+     * enricher scoped **read-only** access to exactly this one file, so
+     * `shisho.fs.readFile(context.file.filePath)` works without the plugin
+     * declaring the broader `fileAccess` capability. Writes to this path
+     * are NOT granted — a plugin that needs to modify the file must declare
+     * `fileAccess: { level: "readwrite" }` in its manifest. Sibling files
+     * (sidecars, covers) are also not included; the scope is the target
+     * file only. Omitted when there is no target file (e.g. a pre-scan
+     * enrichment with no file yet).
+     */
+    filePath?: string;
     /** Audiobook duration in seconds. */
     duration?: number;
     /** Number of pages (CBZ/PDF). */

package/host-api.d.ts

@@ -238,6 +238,35 @@ export interface ShishoHTML {
   querySelectorAll(doc: HtmlElement, selector: string): HtmlElement[];
 }
 
+/**
+ * YAML parsing and serialization. No capability required.
+ *
+ * Backed by Go's gopkg.in/yaml.v3, which does not instantiate arbitrary
+ * objects from custom tags (unlike PyYAML's full loader or Ruby's Psych),
+ * so parsing untrusted YAML cannot execute code. Oversized inputs are still
+ * bounded by the plugin hook timeout.
+ */
+export interface ShishoYAML {
+  /**
+   * Parse a YAML string into a plain JS value (object, array, string, number, boolean, or null).
+   * Throws on invalid YAML.
+   *
+   * @example
+   * var config = shisho.yaml.parse("title: My Book\nauthor: Alice");
+   * config.title // "My Book"
+   */
+  parse(content: string): unknown;
+
+  /**
+   * Serialize a JS value to a YAML string.
+   *
+   * @example
+   * shisho.yaml.stringify({ title: "My Book", pages: 100 });
+   * // "title: My Book\npages: 100\n"
+   */
+  stringify(value: unknown): string;
+}
+
 /** Result from shisho.ffmpeg.transcode(). */
 export interface TranscodeResult {
   /** Process exit code (0 = success). */
@@ -425,6 +454,7 @@ export interface ShishoHostAPI {
   archive: ShishoArchive;
   xml: ShishoXML;
   html: ShishoHTML;
+  yaml: ShishoYAML;
   ffmpeg: ShishoFFmpeg;
   shell: ShishoShell;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shisho/plugin-sdk",
-  "version": "0.0.33",
+  "version": "0.0.35",
   "description": "TypeScript SDK for Shisho plugin development — types, host API declarations, and test utilities",
   "homepage": "https://github.com/shishobooks/shisho/blob/master/packages/plugin-sdk/README.md",
   "types": "index.d.ts",
@@ -27,6 +27,7 @@
   },
   "dependencies": {
     "fast-xml-parser": "^5.7.1",
-    "linkedom": "^0.18.12"
+    "linkedom": "^0.18.12",
+    "yaml": "^2.6.1"
   }
 }

package/testing/index.d.ts

@@ -37,7 +37,7 @@ export interface MockShishoOptions {
  * Create a mock `shisho` host API object for testing plugins.
  *
  * Provides mock implementations of log, config, http, url, and fs.
- * Provides real implementations of xml and html (backed by fast-xml-parser and linkedom).
+ * Provides real implementations of xml, html, and yaml (backed by fast-xml-parser, linkedom, and the `yaml` package).
  *
  * @example
  * ```ts

package/testing/index.js

@@ -1,5 +1,6 @@
 import { XMLParser } from "fast-xml-parser";
 import { parseHTML } from "linkedom";
+import { parse as parseYAML, stringify as stringifyYAML } from "yaml";
 function statusText(status) {
     const texts = {
         200: "OK",
@@ -230,13 +231,44 @@ function createHTMLImpl() {
     };
 }
 // ---------------------------------------------------------------------------
+// YAML implementation (eemeli/yaml — real parser, matches Go's yaml.v3 shape)
+//
+// Both this mock and the production runtime (gopkg.in/yaml.v3) target YAML
+// 1.2 semantics, so booleans like `yes`/`no`/`on`/`off` stay as strings in
+// both. Divergence is still possible on edge cases — empty documents,
+// non-string mapping keys, mapping-key ordering — so plugin authors should
+// run the real runtime when asserting against anything subtle.
+// ---------------------------------------------------------------------------
+function createYAMLImpl() {
+    return {
+        parse(content) {
+            try {
+                return parseYAML(content);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                throw new Error(`shisho.yaml.parse: ${message}`);
+            }
+        },
+        stringify(value) {
+            try {
+                return stringifyYAML(value);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                throw new Error(`shisho.yaml.stringify: ${message}`);
+            }
+        },
+    };
+}
+// ---------------------------------------------------------------------------
 // Main factory
 // ---------------------------------------------------------------------------
 /**
  * Create a mock `shisho` host API object for testing plugins.
  *
  * Provides mock implementations of log, config, http, url, and fs.
- * Provides real implementations of xml and html (backed by fast-xml-parser and linkedom).
+ * Provides real implementations of xml, html, and yaml (backed by fast-xml-parser, linkedom, and the `yaml` package).
  *
  * @example
  * ```ts
@@ -447,6 +479,7 @@ export function createMockShisho(options = {}) {
         },
         xml: createXMLImpl(),
         html: createHTMLImpl(),
+        yaml: createYAMLImpl(),
         ffmpeg: {
             transcode: notImplemented("ffmpeg.transcode"),
             probe: notImplemented("ffmpeg.probe"),

package/testing/index.ts

@@ -1,5 +1,6 @@
 import { XMLParser } from "fast-xml-parser";
 import { parseHTML } from "linkedom";
+import { parse as parseYAML, stringify as stringifyYAML } from "yaml";
 
 import type {
   FetchResponse,
@@ -13,6 +14,7 @@ import type {
   ShishoLog,
   ShishoURL,
   ShishoXML,
+  ShishoYAML,
   XMLElement,
 } from "../index";
 
@@ -337,6 +339,37 @@ function createHTMLImpl(): ShishoHTML {
   };
 }
 
+// ---------------------------------------------------------------------------
+// YAML implementation (eemeli/yaml — real parser, matches Go's yaml.v3 shape)
+//
+// Both this mock and the production runtime (gopkg.in/yaml.v3) target YAML
+// 1.2 semantics, so booleans like `yes`/`no`/`on`/`off` stay as strings in
+// both. Divergence is still possible on edge cases — empty documents,
+// non-string mapping keys, mapping-key ordering — so plugin authors should
+// run the real runtime when asserting against anything subtle.
+// ---------------------------------------------------------------------------
+
+function createYAMLImpl(): ShishoYAML {
+  return {
+    parse(content: string): unknown {
+      try {
+        return parseYAML(content);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`shisho.yaml.parse: ${message}`);
+      }
+    },
+    stringify(value: unknown): string {
+      try {
+        return stringifyYAML(value);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`shisho.yaml.stringify: ${message}`);
+      }
+    },
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Main factory
 // ---------------------------------------------------------------------------
@@ -345,7 +378,7 @@ function createHTMLImpl(): ShishoHTML {
  * Create a mock `shisho` host API object for testing plugins.
  *
  * Provides mock implementations of log, config, http, url, and fs.
- * Provides real implementations of xml and html (backed by fast-xml-parser and linkedom).
+ * Provides real implementations of xml, html, and yaml (backed by fast-xml-parser, linkedom, and the `yaml` package).
  *
  * @example
  * ```ts
@@ -606,6 +639,7 @@ export function createMockShisho(
     },
     xml: createXMLImpl(),
     html: createHTMLImpl(),
+    yaml: createYAMLImpl(),
     ffmpeg: {
       transcode: notImplemented("ffmpeg.transcode") as never,
       probe: notImplemented("ffmpeg.probe") as never,