@shisho/plugin-types 0.0.8 → 0.0.10

package/host-api.d.ts

@@ -112,8 +112,8 @@ export interface ShishoXML {
   ): XMLElement[];
 }
 
-/** Result from shisho.ffmpeg.run(). */
-export interface FFmpegResult {
+/** Result from shisho.ffmpeg.transcode(). */
+export interface TranscodeResult {
   /** Process exit code (0 = success). */
   exitCode: number;
   /** Standard output. */
@@ -122,10 +122,147 @@ export interface FFmpegResult {
   stderr: string;
 }
 
+/** Result from shisho.ffmpeg.probe(). */
+export interface ProbeResult {
+  format: ProbeFormat;
+  streams: ProbeStream[];
+  chapters: ProbeChapter[];
+  /** Standard error output (for debugging). */
+  stderr: string;
+  /** JSON parse error message if ffprobe output could not be parsed. Empty string if parsing succeeded. */
+  parseError: string;
+}
+
+/** Format information from ffprobe. */
+export interface ProbeFormat {
+  filename: string;
+  nb_streams: number;
+  nb_programs: number;
+  format_name: string;
+  format_long_name: string;
+  start_time: string;
+  duration: string;
+  size: string;
+  bit_rate: string;
+  probe_score: number;
+  tags?: Record<string, string>;
+}
+
+/** Stream information from ffprobe. */
+export interface ProbeStream {
+  index: number;
+  codec_name?: string;
+  codec_long_name?: string;
+  codec_type: "video" | "audio" | "subtitle" | "data" | "attachment";
+  codec_tag_string?: string;
+  codec_tag?: string;
+
+  // Video-specific
+  width?: number;
+  height?: number;
+  coded_width?: number;
+  coded_height?: number;
+  closed_captions?: number;
+  has_b_frames?: number;
+  sample_aspect_ratio?: string;
+  display_aspect_ratio?: string;
+  pix_fmt?: string;
+  level?: number;
+  color_range?: string;
+  color_space?: string;
+  color_transfer?: string;
+  color_primaries?: string;
+  chroma_location?: string;
+  field_order?: string;
+  refs?: number;
+
+  // Audio-specific
+  sample_fmt?: string;
+  sample_rate?: string;
+  channels?: number;
+  channel_layout?: string;
+  bits_per_sample?: number;
+
+  // Common (optional since not all stream types have these)
+  r_frame_rate?: string;
+  avg_frame_rate?: string;
+  time_base?: string;
+  start_pts?: number;
+  start_time?: string;
+  duration_ts?: number;
+  duration?: string;
+  bit_rate?: string;
+  bits_per_raw_sample?: string;
+  nb_frames?: string;
+  disposition?: ProbeDisposition;
+  tags?: Record<string, string>;
+}
+
+/** Stream disposition flags from ffprobe. */
+export interface ProbeDisposition {
+  default: number;
+  dub: number;
+  original: number;
+  comment: number;
+  lyrics: number;
+  karaoke: number;
+  forced: number;
+  hearing_impaired: number;
+  visual_impaired: number;
+  clean_effects: number;
+  attached_pic: number;
+  timed_thumbnails: number;
+}
+
+/** Chapter information from ffprobe. */
+export interface ProbeChapter {
+  id: number;
+  time_base: string;
+  start: number;
+  start_time: string;
+  end: number;
+  end_time: string;
+  tags?: Record<string, string>;
+}
+
+/** Result from shisho.ffmpeg.version(). */
+export interface VersionResult {
+  /** FFmpeg version string (e.g., "7.0"). */
+  version: string;
+  /** Build configuration flags (e.g., ["--enable-libx264", "--enable-gpl"]). */
+  configuration: string[];
+  /** Library versions (e.g., { libavcodec: "60.31.102", ... }). */
+  libraries: Record<string, string>;
+}
+
 /** FFmpeg subprocess execution. */
 export interface ShishoFFmpeg {
-  /** Run FFmpeg with the given arguments. Requires ffmpegAccess capability. */
-  run(args: string[]): FFmpegResult;
+  /** Transcode files with FFmpeg. Requires ffmpegAccess capability. */
+  transcode(args: string[]): TranscodeResult;
+  /** Probe file metadata with ffprobe. Returns parsed JSON. Requires ffmpegAccess capability. */
+  probe(args: string[]): ProbeResult;
+  /** Get FFmpeg version and configuration. Requires ffmpegAccess capability. */
+  version(): VersionResult;
+}
+
+/** Result from shisho.shell.exec(). */
+export interface ExecResult {
+  /** Process exit code (0 = success). */
+  exitCode: number;
+  /** Standard output. */
+  stdout: string;
+  /** Standard error. */
+  stderr: string;
+}
+
+/** Shell command execution (with allowlist). */
+export interface ShishoShell {
+  /**
+   * Execute an allowed command with arguments.
+   * Command must be declared in manifest shellAccess.commands.
+   * Uses exec directly (no shell) to prevent injection.
+   */
+  exec(command: string, args: string[]): ExecResult;
 }
 
 /** Top-level host API object available as the global `shisho` variable. */
@@ -137,4 +274,5 @@ export interface ShishoHostAPI {
   archive: ShishoArchive;
   xml: ShishoXML;
   ffmpeg: ShishoFFmpeg;
+  shell: ShishoShell;
 }

package/manifest.d.ts

@@ -29,11 +29,34 @@ export interface OutputGeneratorCap {
   sourceTypes: string[];
 }
 
+/** Valid metadata field names for enricher declarations. */
+export type MetadataField =
+  | "title"
+  | "subtitle"
+  | "authors"
+  | "narrators"
+  | "series"
+  | "seriesNumber"
+  | "genres"
+  | "tags"
+  | "description"
+  | "publisher"
+  | "imprint"
+  | "url"
+  | "releaseDate"
+  | "cover"
+  | "identifiers";
+
 /** Metadata enricher capability declaration. */
 export interface MetadataEnricherCap {
   description?: string;
   /** File types this enricher applies to (e.g., ["epub", "cbz"]). */
   fileTypes?: string[];
+  /**
+   * Metadata fields this enricher may set.
+   * Required for enrichers - if omitted, the enricher hook is disabled.
+   */
+  fields: MetadataField[];
 }
 
 /** Custom identifier type declaration. */
@@ -67,6 +90,13 @@ export interface FFmpegAccessCap {
   description?: string;
 }
 
+/** Shell access capability declaration. */
+export interface ShellAccessCap {
+  description?: string;
+  /** Allowed commands (e.g., ["convert", "magick", "identify"]). */
+  commands: string[];
+}
+
 /** All plugin capabilities. */
 export interface Capabilities {
   inputConverter?: InputConverterCap;
@@ -77,6 +107,7 @@ export interface Capabilities {
   httpAccess?: HTTPAccessCap;
   fileAccess?: FileAccessCap;
   ffmpegAccess?: FFmpegAccessCap;
+  shellAccess?: ShellAccessCap;
 }
 
 /** Option for select-type config fields. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shisho/plugin-types",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "description": "TypeScript type definitions for Shisho plugin development",
   "homepage": "https://github.com/shishobooks/shisho/blob/master/packages/plugin-types/README.md",
   "types": "index.d.ts",