@digitalpaws/starr 0.0.1

package/src/datastore/storage.ts

@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+
+import type Database from "better-sqlite3";
+import type { PluginStorage } from "../types/plugin.js";
+
+export function createPluginStorage(
+  db: Database.Database,
+  pluginId: string,
+  instanceId = "default",
+): PluginStorage {
+  const getStmt = db.prepare(
+    "SELECT value FROM plugin_storage WHERE plugin_id = @pluginId AND instance_id = @instanceId AND key = @key",
+  );
+  const setStmt = db.prepare(`
+    INSERT INTO plugin_storage (plugin_id, instance_id, key, value, updated_at)
+    VALUES (@pluginId, @instanceId, @key, @value, datetime('now'))
+    ON CONFLICT(plugin_id, instance_id, key) DO UPDATE SET
+      value = @value,
+      updated_at = datetime('now')
+  `);
+  const deleteStmt = db.prepare(
+    "DELETE FROM plugin_storage WHERE plugin_id = @pluginId AND instance_id = @instanceId AND key = @key",
+  );
+  const listAllStmt = db.prepare(
+    `SELECT key, value FROM plugin_storage
+     WHERE plugin_id = @pluginId AND instance_id = @instanceId
+     ORDER BY key`,
+  );
+  const listPrefixStmt = db.prepare(
+    `SELECT key, value FROM plugin_storage
+     WHERE plugin_id = @pluginId AND instance_id = @instanceId AND key LIKE @prefix
+     ORDER BY key`,
+  );
+  const deleteAllStmt = db.prepare(
+    "DELETE FROM plugin_storage WHERE plugin_id = @pluginId AND instance_id = @instanceId",
+  );
+
+  return {
+    async get<T>(key: string): Promise<T | undefined> {
+      const row = getStmt.get({ pluginId, instanceId, key }) as
+        | { value: string }
+        | undefined;
+      if (!row) return undefined;
+      try {
+        return JSON.parse(row.value) as T;
+      } catch {
+        return undefined;
+      }
+    },
+
+    async set<T>(key: string, value: T): Promise<void> {
+      setStmt.run({ pluginId, instanceId, key, value: JSON.stringify(value) });
+    },
+
+    async delete(key: string): Promise<void> {
+      deleteStmt.run({ pluginId, instanceId, key });
+    },
+
+    async list<T>(
+      prefix?: string,
+    ): Promise<Array<{ key: string; value: T }>> {
+      const stmt = prefix !== undefined ? listPrefixStmt : listAllStmt;
+      const params = prefix !== undefined
+        ? { pluginId, instanceId, prefix: `${prefix}%` }
+        : { pluginId, instanceId };
+      const rows = stmt.all(params) as Array<{ key: string; value: string }>;
+      return rows.map((row) => {
+        let value: T | undefined;
+        try {
+          value = JSON.parse(row.value) as T;
+        } catch {
+          value = undefined;
+        }
+        return { key: row.key, value: value as T };
+      });
+    },
+
+    async deleteAll(): Promise<void> {
+      deleteAllStmt.run({ pluginId, instanceId });
+    },
+  };
+}

package/src/events/event-bus.ts

@@ -0,0 +1,180 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+
+import { randomUUID } from "node:crypto";
+import type { Logger } from "../types/plugin.js";
+import type {
+  StarrEvent,
+  EventBus,
+  EventHandler,
+  EmitOpts,
+  RequestOpts,
+  Unsubscribe,
+} from "../types/plugin.js";
+import { runInTraceContext, getCurrentTraceId } from "./trace.js";
+import { getSpineSchemaVersion, validateSpineEmission } from "./spine.js";
+
+export class EventBusImpl {
+  private subscriptions = new Map<string, Set<EventHandler>>();
+  private logger: Logger;
+
+  constructor(logger: Logger) {
+    this.logger = logger.child("event-bus");
+  }
+
+  // ---- Public factory methods ---- //
+
+  /** Returns an EventBus bound to the given plugin id. */
+  pluginBus(pluginId: string): EventBus {
+    return {
+      on: <P>(type: string, handler: EventHandler<P>) => this._on(type, handler),
+      emit: <P>(type: string, payload: P, opts?: EmitOpts) =>
+        this._emit(pluginId, type, payload, opts),
+      request: (type: string, payload: unknown, opts: RequestOpts) =>
+        this._request(pluginId, type, payload, opts),
+    };
+  }
+
+  /** Returns an EventBus with source="core". */
+  coreBus(): EventBus {
+    return this.pluginBus("core");
+  }
+
+  // ---- Private implementation ---- //
+
+  private _on<P>(type: string, handler: EventHandler<P>): Unsubscribe {
+    if (!this.subscriptions.has(type)) {
+      this.subscriptions.set(type, new Set());
+    }
+    const handlers = this.subscriptions.get(type)!;
+    handlers.add(handler as EventHandler);
+    return () => {
+      handlers.delete(handler as EventHandler);
+      if (handlers.size === 0) {
+        this.subscriptions.delete(type);
+      }
+    };
+  }
+
+  private _emit(
+    source: string,
+    type: string,
+    payload: unknown,
+    opts?: EmitOpts,
+  ): void {
+    const event: StarrEvent = {
+      id: randomUUID(),
+      traceId: getCurrentTraceId(),
+      correlationId: opts?.correlationId,
+      source,
+      type,
+      timestamp: new Date().toISOString(),
+      schemaVersion: getSpineSchemaVersion(type),
+      payload,
+      reply: <R>(replyType: string, replyPayload: R) => {
+        this._emit(source, replyType, replyPayload, {
+          correlationId: event.correlationId,
+        });
+      },
+    };
+
+    // Immutability (EN2)
+    Object.freeze(event);
+
+    this.logger.debug("emitting event", {
+      eventType: type,
+      source,
+      correlationId: event.correlationId,
+    });
+
+    // Spine validation — log at warn level if suspect (EBQ4, §9 CE2–CE3)
+    const violation = validateSpineEmission(source, type);
+    if (violation) {
+      this.logger.warn("spine emission warning", {
+        source,
+        eventType: type,
+        detail: violation,
+      });
+    }
+
+    // Look up handlers
+    const handlers = this.subscriptions.get(type);
+    if (!handlers || handlers.size === 0) {
+      return; // silently dropped (DL5)
+    }
+
+    // Dispatch to each handler — error isolation per handler (DL2)
+    const logger = this.logger;
+    for (const handler of handlers) {
+      try {
+        const result = runInTraceContext(event, () => handler(event));
+        if (result instanceof Promise) {
+          result.catch((err: unknown) => {
+            logger.error("event handler rejected", {
+              eventType: type,
+              handlerSource: source,
+              error: String(err),
+            });
+          });
+        }
+      } catch (err) {
+        logger.error("event handler threw", {
+          eventType: type,
+          handlerSource: source,
+          error: String(err),
+        });
+      }
+    }
+  }
+
+  private _request<Res>(
+    source: string,
+    type: string,
+    payload: unknown,
+    opts: RequestOpts,
+  ): Promise<StarrEvent<Res>[]> {
+    // Validate opts — programming errors, fail fast
+    if (!opts.responseType || opts.responseType.trim() === "") {
+      throw new Error("request(): responseType is required and must be non-empty");
+    }
+    if (!Number.isFinite(opts.windowMs) || opts.windowMs <= 0) {
+      throw new Error(
+        `request(): windowMs must be a positive number, got ${opts.windowMs}`,
+      );
+    }
+    if (opts.max !== undefined && (!Number.isInteger(opts.max) || opts.max < 1)) {
+      throw new Error(
+        `request(): max must be a positive integer, got ${opts.max}`,
+      );
+    }
+
+    const correlationId = randomUUID();
+    const replies: StarrEvent<Res>[] = [];
+
+    return new Promise((resolve) => {
+      let settled = false;
+      const timer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        unsub();
+        resolve(replies);
+      }, opts.windowMs);
+
+      const unsub = this._on(opts.responseType, (evt: StarrEvent) => {
+        if (settled) return;
+        if (evt.correlationId === correlationId) {
+          replies.push(evt as StarrEvent<Res>);
+          if (opts.max !== undefined && replies.length >= opts.max) {
+            settled = true;
+            clearTimeout(timer);
+            unsub();
+            resolve(replies);
+          }
+        }
+      });
+
+      // Emit AFTER subscribing so synchronous replies are not missed
+      this._emit(source, type, payload, { correlationId });
+    });
+  }
+}

package/src/events/spine.ts

@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+
+/**
+ * Reserved spine namespace prefixes.
+ * The dotted unprefixed namespace is reserved for the core spine.
+ */
+export const SPINE_NAMESPACES = [
+  "content.",
+  "release.",
+  "download.",
+  "import.",
+  "library.",
+  "discovery.",
+  "item.",
+] as const;
+
+export interface SpineEventMeta {
+  kind: "request" | "reply" | "notification";
+  /** Who is allowed to emit this event. */
+  producers:
+    | "core"
+    | "metadata-plugin"
+    | "indexer-plugin"
+    | "selection-plugin"
+    | "downloader-plugin";
+  schemaVersion: number;
+}
+
+/**
+ * The v1 spine event catalog (spec §8).
+ */
+export const SPINE_EVENTS: Record<string, SpineEventMeta> = {
+  "discovery.search":     { kind: "request",      producers: "core",               schemaVersion: 1 },
+  "discovery.results":    { kind: "reply",         producers: "metadata-plugin",     schemaVersion: 1 },
+  "content.requested":    { kind: "request",      producers: "core",               schemaVersion: 2 },
+  "release.found":        { kind: "reply",         producers: "indexer-plugin",      schemaVersion: 1 },
+  "release.chosen":       { kind: "notification", producers: "selection-plugin",    schemaVersion: 1 },
+  "download.started":     { kind: "notification", producers: "downloader-plugin",   schemaVersion: 1 },
+  "download.completed":   { kind: "notification", producers: "downloader-plugin",   schemaVersion: 1 },
+  "download.failed":      { kind: "notification", producers: "downloader-plugin",   schemaVersion: 1 },
+  "request.failed":       { kind: "notification", producers: "selection-plugin",    schemaVersion: 1 },
+  "item.updated":         { kind: "notification", producers: "core",               schemaVersion: 1 },
+  "request.deleted":      { kind: "notification", producers: "core",               schemaVersion: 1 },
+
+  "import.started":     { kind: "notification", producers: "core", schemaVersion: 1 },
+  "import.completed":   { kind: "notification", producers: "core", schemaVersion: 1 },
+  "import.failed":      { kind: "notification", producers: "core", schemaVersion: 1 },
+  "library.file_added": { kind: "notification", producers: "core", schemaVersion: 1 },
+};
+
+/**
+ * Check whether an event type falls within the reserved spine namespace.
+ */
+export function isSpineType(type: string): boolean {
+  return SPINE_NAMESPACES.some((ns) => type.startsWith(ns));
+}
+
+/**
+ * Return the schemaVersion for a spine type, or 1 as default for custom events.
+ */
+export function getSpineSchemaVersion(type: string): number {
+  return SPINE_EVENTS[type]?.schemaVersion ?? 1;
+}
+
+/**
+ * Validate whether a source is allowed to emit the given spine event type.
+ *
+ * Returns an error message string if the emission is suspect, or null if it is fine.
+ * Per EBQ4 resolution, this only logs warnings; it does not reject.
+ */
+export function validateSpineEmission(source: string, type: string): string | null {
+  if (!isSpineType(type)) return null; // custom event, fine
+
+  const meta = SPINE_EVENTS[type];
+  if (!meta) {
+    return `Unknown spine event type "${type}" emitted by "${source}"`;
+  }
+
+  // For v1 we are lenient: log but don't block.
+  // Only flag if core events are emitted by non-core sources.
+  if (meta.producers === "core" && source !== "core") {
+    return `Spine event "${type}" is reserved for core, but was emitted by "${source}"`;
+  }
+
+  return null;
+}

package/src/events/trace.ts

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+import type { StarrEvent } from "../types/plugin.js";
+
+/**
+ * Singleton AsyncLocalStorage that holds the "current event" during handler dispatch.
+ * This is the core trace-propagation mechanism (spec §5 PS2, EBQ5).
+ */
+export const traceStore = new AsyncLocalStorage<StarrEvent>();
+
+/**
+ * Run a function within the trace context of the given event.
+ * Any emit() calls inside fn will inherit this event's traceId.
+ */
+export function runInTraceContext<R>(event: StarrEvent, fn: () => R): R {
+  return traceStore.run(event, fn);
+}
+
+/**
+ * Return the traceId of the currently handled event, or mint a fresh one
+ * if called outside any handler (root emission — spec §5 PS3).
+ */
+export function getCurrentTraceId(): string {
+  const event = traceStore.getStore();
+  return event ? event.traceId : randomUUID();
+}
+
+/**
+ * Return the correlationId of the currently handled event, or undefined.
+ * correlationId is NOT automatically propagated by plain emit() —
+ * it is only attached via explicit opts or the reply() sugar (§5 PS2, §6.1).
+ */
+export function getCurrentCorrelationId(): string | undefined {
+  return traceStore.getStore()?.correlationId;
+}

package/src/host.ts

@@ -0,0 +1,130 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+
+import type { EventBus, Logger, PluginLifecycle, PluginMeta } from "./types/plugin.js";
+import type { Datastore } from "./datastore/db.js";
+import type { ConfigService } from "./config/config-service.js";
+import type { FastifyInstance } from "fastify";
+import type Database from "better-sqlite3";
+import { EventBusImpl } from "./events/event-bus.js";
+import { ContentTypeRegistryImpl } from "./content-types/registry.js";
+import type { StateStore } from "./state/state-store.js";
+import type { Importer } from "./library/importer.js";
+import type { LibraryCache } from "./library/library-cache.js";
+import type { LibraryService } from "./library/library-service.js";
+import type { ScanController } from "./library/scan-controller.js";
+
+export interface StarrOptions {
+  pluginsDir: string;
+  apiVersion: string;
+  logger: Logger;
+}
+
+export interface PluginRuntime {
+  meta: PluginMeta;
+  lifecycle: PluginLifecycle;
+  startOrder: number;
+}
+
+export class Starr {
+  readonly options: StarrOptions;
+  readonly logger: Logger;
+  readonly apiVersion: string;
+
+  // Service slots to be wired by later tasks.
+  datastore: Datastore | null = null;
+  private _eventBus: EventBusImpl;
+
+  /**
+   * Public EventBus interface (exposed for wiring context).
+   */
+  get eventBus(): EventBus {
+    return this._eventBus.coreBus();
+  }
+
+  /**
+   * Internal accessor for EventBusImpl (used by context to create plugin-bound buses).
+   */
+  get busImpl(): EventBusImpl {
+    return this._eventBus;
+  }
+
+  /**
+   * Core event bus with source="core". Convenience for emitting spine events from the host.
+   */
+  get coreBus(): EventBus {
+    return this._eventBus.coreBus();
+  }
+  contentTypeRegistry: ContentTypeRegistryImpl = new ContentTypeRegistryImpl();
+  configService: ConfigService | null = null;
+  stateStore: StateStore | null = null;
+  importer: Importer | null = null;
+  libraryCache: LibraryCache | null = null;
+  libraryService: LibraryService | null = null;
+  scanController: ScanController | null = null;
+  webServer: FastifyInstance | null = null;
+
+  private pluginRuntimes: PluginRuntime[] = [];
+  private running = false;
+
+  getScanController(): ScanController {
+    if (!this.scanController) throw new Error("scan controller not initialized");
+    return this.scanController;
+  }
+
+  getLibraryCache(): LibraryCache {
+    if (!this.libraryCache) throw new Error("library cache not initialized");
+    return this.libraryCache;
+  }
+
+  getLibraryService(): LibraryService {
+    if (!this.libraryService) throw new Error("library service not initialized");
+    return this.libraryService;
+  }
+
+  getImporter(): Importer {
+    if (!this.importer) throw new Error("importer not initialized");
+    return this.importer;
+  }
+
+  /** Convenience: get the state store or throw if not initialized. */
+  getStateStore(): StateStore {
+    if (!this.stateStore) {
+      throw new Error("state store not initialized");
+    }
+    return this.stateStore;
+  }
+
+  getDatabase(): Database.Database | null {
+    return this.datastore?.db ?? null;
+  }
+
+  constructor(options: StarrOptions) {
+    this.options = options;
+    this.logger = options.logger.child("host");
+    this.apiVersion = options.apiVersion;
+    this._eventBus = new EventBusImpl(this.logger);
+  }
+
+  markRunning(): void {
+    this.running = true;
+    this.logger.info("running");
+  }
+
+  markStopped(): void {
+    this.running = false;
+    this.logger.info("stopped");
+  }
+
+  get isRunning(): boolean {
+    return this.running;
+  }
+
+  setRuntimes(runtimes: PluginRuntime[]): void {
+    this.pluginRuntimes = runtimes;
+  }
+
+  getRuntimes(): readonly PluginRuntime[] {
+    return this.pluginRuntimes;
+  }
+}

package/src/library/importer.ts

@@ -0,0 +1,174 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import type Database from "better-sqlite3";
+import type { EventBus, Logger } from "../types/plugin.js";
+import type { ContentItemBase, NamingRule } from "@digitalpaws/starr-types-core";
+import { resolveNaming } from "./naming.js";
+import type { LibraryConfig } from "./library-config.js";
+import type { LibraryService } from "./library-service.js";
+
+export interface ImportResult {
+  success: boolean;
+  libraryPath?: string;
+  error?: string;
+}
+
+export class Importer {
+  private db: Database.Database;
+  private bus: EventBus;
+  private logger: Logger;
+  private getConfig: () => LibraryConfig;
+  private getNamingRule: (contentTypeId: string) => NamingRule;
+  private libraryService?: LibraryService;
+
+  private stmtUpsertPath: Database.Statement;
+  private stmtUpdateRequestPath: Database.Statement;
+
+  constructor(
+    db: Database.Database,
+    bus: EventBus,
+    logger: Logger,
+    getConfig: () => LibraryConfig,
+    getNamingRule: (contentTypeId: string) => NamingRule,
+    libraryService?: LibraryService,
+  ) {
+    this.db = db;
+    this.bus = bus;
+    this.logger = logger.child("importer");
+    this.getConfig = getConfig;
+    this.getNamingRule = getNamingRule;
+    this.libraryService = libraryService;
+
+    this.stmtUpsertPath = db.prepare(`
+      INSERT INTO library_paths (request_id, library_path, library_root, imported_at, updated_at)
+      VALUES (@requestId, @libraryPath, @libraryRoot, datetime('now'), datetime('now'))
+      ON CONFLICT(request_id) DO UPDATE SET
+        library_path = excluded.library_path,
+        updated_at = datetime('now')
+    `);
+
+    this.stmtUpdateRequestPath = db.prepare(`
+      UPDATE tracked_requests
+      SET library_path = @libraryPath, updated_at = datetime('now')
+      WHERE request_id = @requestId
+    `);
+  }
+
+  async import(
+    requestId: string,
+    sourcePath: string,
+    item: ContentItemBase,
+    contentTypeId: string,
+    extension: string,
+    /** The pre-computed content identity for this item. */
+    contentIdentity: string,
+    /** Optional library ID for multi-library support. */
+    libraryId?: string,
+  ): Promise<ImportResult> {
+    try {
+      this.bus.emit("import.started", { requestId });
+
+      // Determine library config
+      let libraryRoot: string;
+      let linkType: string;
+      let importSubtitles: boolean;
+      let subtitleExtensions: string[];
+
+      if (libraryId && this.libraryService) {
+        const lib = this.libraryService.get(libraryId);
+        if (lib) {
+          libraryRoot = lib.roots[contentTypeId] ?? lib.defaultLibraryRoot;
+          linkType = lib.linkType;
+          importSubtitles = lib.importSubtitles;
+          subtitleExtensions = lib.subtitleExtensions;
+        } else {
+          // Fallback to global config
+          const cfg = this.getConfig();
+          libraryRoot = cfg.roots[contentTypeId] ?? cfg.defaultLibraryRoot;
+          linkType = cfg.linkType;
+          importSubtitles = cfg.importSubtitles;
+          subtitleExtensions = cfg.subtitleExtensions;
+        }
+      } else {
+        // Fallback to global config
+        const cfg = this.getConfig();
+        libraryRoot = cfg.roots[contentTypeId] ?? cfg.defaultLibraryRoot;
+        linkType = cfg.linkType;
+        importSubtitles = cfg.importSubtitles;
+        subtitleExtensions = cfg.subtitleExtensions;
+      }
+
+      const namingRule = this.getNamingRule(contentTypeId);
+      const relativePath = resolveNaming(namingRule, item, extension);
+      const destPath = path.join(libraryRoot, relativePath);
+
+      await fs.mkdir(path.dirname(destPath), { recursive: true });
+      await this.transferFile(sourcePath, destPath, linkType);
+
+      if (importSubtitles) {
+        await this.importSubtitles(sourcePath, destPath, subtitleExtensions);
+      }
+
+      this.stmtUpsertPath.run({
+        requestId,
+        libraryPath: destPath,
+        libraryRoot,
+      });
+      this.stmtUpdateRequestPath.run({ requestId, libraryPath: destPath });
+
+      this.bus.emit("import.completed", { requestId, libraryPath: destPath });
+      this.bus.emit("library.file_added", {
+        requestId,
+        libraryPath: destPath,
+        contentTypeId,
+        contentIdentity,
+      });
+
+      return { success: true, libraryPath: destPath };
+    } catch (err) {
+      const error = String(err);
+      this.bus.emit("import.failed", { requestId, error });
+      return { success: false, error };
+    }
+  }
+
+  private async transferFile(src: string, dest: string, linkType: string): Promise<void> {
+    switch (linkType) {
+      case "move":    await fs.rename(src, dest); break;
+      case "hardlink": await fs.link(src, dest); break;
+      case "symlink": await fs.symlink(src, dest); break;
+      case "copy":    await fs.copyFile(src, dest); break;
+      default:        throw new Error(`Unknown link type: ${linkType}`);
+    }
+  }
+
+  private async importSubtitles(
+    src: string, dest: string, subtitleExtensions: string[],
+  ): Promise<void> {
+    const srcDir = path.dirname(src);
+    const baseName = path.basename(src, path.extname(src));
+    const destDir = path.dirname(dest);
+    const destBaseName = path.basename(dest, path.extname(dest));
+
+    const entries = await fs.readdir(srcDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isFile()) continue;
+      const ext = path.extname(entry.name).slice(1).toLowerCase();
+      if (!subtitleExtensions.includes(ext)) continue;
+      const entryBaseName = path.basename(entry.name, path.extname(entry.name));
+      if (!entryBaseName.startsWith(baseName)) continue;
+
+      const srcSub = path.join(srcDir, entry.name);
+      const destSubName = entry.name.replace(baseName, destBaseName);
+      const destSub = path.join(destDir, destSubName);
+      try {
+        await this.transferFile(srcSub, destSub, "copy");
+      } catch (err) {
+        this.logger.warn("failed to import subtitle", { src: srcSub, error: String(err) });
+      }
+    }
+  }
+}