@digitalpaws/starr 0.0.1

package/src/library/library-service.ts

@@ -0,0 +1,282 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+
+import type Database from "better-sqlite3";
+import type { EventBus, Logger } from "../types/plugin.js";
+import { randomUUID } from "node:crypto";
+
+export interface Library {
+  id: string;
+  name: string;
+  description?: string;
+  isDefault: boolean;
+  defaultLibraryRoot: string;
+  roots: Record<string, string>;
+  linkType: "move" | "hardlink" | "symlink" | "copy";
+  importSubtitles: boolean;
+  subtitleExtensions: string[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface LibraryInput {
+  name: string;
+  description?: string;
+  isDefault?: boolean;
+  defaultLibraryRoot?: string;
+  roots?: Record<string, string>;
+  linkType?: "move" | "hardlink" | "symlink" | "copy";
+  importSubtitles?: boolean;
+  subtitleExtensions?: string[];
+}
+
+export class LibraryService {
+  private db: Database.Database;
+  private bus: EventBus;
+  private logger: Logger;
+
+  // Prepared statements
+  private stmtList: Database.Statement;
+  private stmtGetById: Database.Statement;
+  private stmtInsert: Database.Statement;
+  private stmtUpdate: Database.Statement;
+  private stmtDelete: Database.Statement;
+  private stmtGetDefault: Database.Statement;
+  private stmtClearDefault: Database.Statement;
+  private stmtSetDefault: Database.Statement;
+  private stmtGetContentTypeDefaults: Database.Statement;
+  private stmtSetContentTypeDefault: Database.Statement;
+  private stmtDeleteContentTypeDefaults: Database.Statement;
+  private stmtCountConnectedDownloaders: Database.Statement;
+  private stmtCountContentTypeDefaults: Database.Statement;
+
+  constructor(
+    db: Database.Database,
+    bus: EventBus,
+    logger: Logger,
+  ) {
+    this.db = db;
+    this.bus = bus;
+    this.logger = logger.child("library-service");
+
+    this.stmtList = db.prepare("SELECT * FROM libraries ORDER BY name");
+    this.stmtGetById = db.prepare("SELECT * FROM libraries WHERE id = ?");
+    this.stmtInsert = db.prepare(`
+      INSERT INTO libraries (id, name, description, is_default, default_library_root, roots, link_type, import_subtitles, subtitle_extensions, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, datetime('now'), datetime('now'))
+    `);
+    this.stmtUpdate = db.prepare(`
+      UPDATE libraries
+      SET name = ?, description = ?, is_default = ?, default_library_root = ?, roots = ?, link_type = ?, import_subtitles = ?, subtitle_extensions = ?, updated_at = datetime('now')
+      WHERE id = ?
+    `);
+    this.stmtDelete = db.prepare("DELETE FROM libraries WHERE id = ?");
+    this.stmtGetDefault = db.prepare("SELECT * FROM libraries WHERE is_default = 1 LIMIT 1");
+    this.stmtClearDefault = db.prepare("UPDATE libraries SET is_default = 0 WHERE is_default = 1");
+    this.stmtSetDefault = db.prepare("UPDATE libraries SET is_default = 1, updated_at = datetime('now') WHERE id = ?");
+    this.stmtGetContentTypeDefaults = db.prepare("SELECT content_type_id FROM library_content_type_defaults WHERE library_id = ?");
+    this.stmtSetContentTypeDefault = db.prepare("INSERT OR REPLACE INTO library_content_type_defaults (library_id, content_type_id) VALUES (?, ?)");
+    this.stmtDeleteContentTypeDefaults = db.prepare("DELETE FROM library_content_type_defaults WHERE library_id = ?");
+    this.stmtCountConnectedDownloaders = db.prepare("SELECT COUNT(*) AS count FROM plugin_config WHERE json_extract(\"values\", '$.libraryId') = ?");
+    this.stmtCountContentTypeDefaults = db.prepare("SELECT COUNT(*) AS count FROM library_content_type_defaults WHERE library_id = ?");
+  }
+
+  // ── CRUD ─────────────────────────────────────────────────
+
+  list(): Library[] {
+    const rows = this.stmtList.all() as Array<Record<string, unknown>>;
+    return rows.map(this.rowToLibrary);
+  }
+
+  get(id: string): Library | undefined {
+    const row = this.stmtGetById.get(id) as Record<string, unknown> | undefined;
+    return row ? this.rowToLibrary(row) : undefined;
+  }
+
+  create(data: LibraryInput): Library {
+    const id = randomUUID();
+    const txn = this.db.transaction(() => {
+      const isDefault = data.isDefault ?? false;
+
+      // If this library is being set as default, clear any existing default
+      if (isDefault) {
+        this.stmtClearDefault.run();
+      }
+
+      // Parse roots
+      const roots = data.roots ?? {};
+      const subtitleExtensions = data.subtitleExtensions ?? ["srt", "ass", "ssa", "sub", "vtt"];
+
+      this.stmtInsert.run(
+        id,
+        data.name,
+        data.description ?? null,
+        isDefault ? 1 : 0,
+        data.defaultLibraryRoot ?? "/media/library",
+        JSON.stringify(roots),
+        data.linkType ?? "hardlink",
+        data.importSubtitles ?? true ? 1 : 0,
+        JSON.stringify(subtitleExtensions),
+      );
+    });
+    txn();
+
+    const lib = this.get(id);
+    if (!lib) throw new Error("failed to create library");
+    this.bus.emit("library.created", { libraryId: id, library: lib });
+    return lib;
+  }
+
+  update(id: string, data: LibraryInput): Library {
+    const existing = this.get(id);
+    if (!existing) throw new Error(`Library not found: ${id}`);
+
+    const txn = this.db.transaction(() => {
+      const isDefault = data.isDefault ?? existing.isDefault;
+
+      // If setting as default, clear any previous default
+      if (isDefault && !existing.isDefault) {
+        this.stmtClearDefault.run();
+      }
+
+      const roots = data.roots ?? existing.roots;
+      const subtitleExtensions = data.subtitleExtensions ?? existing.subtitleExtensions;
+
+      this.stmtUpdate.run(
+        data.name ?? existing.name,
+        data.description !== undefined ? data.description : existing.description ?? null,
+        isDefault ? 1 : 0,
+        data.defaultLibraryRoot ?? existing.defaultLibraryRoot,
+        JSON.stringify(roots),
+        data.linkType ?? existing.linkType,
+        data.importSubtitles ?? existing.importSubtitles ? 1 : 0,
+        JSON.stringify(subtitleExtensions),
+        id,
+      );
+    });
+    txn();
+
+    const updated = this.get(id);
+    if (!updated) throw new Error("failed to update library");
+    this.bus.emit("library.updated", { libraryId: id, library: updated });
+    return updated;
+  }
+
+  delete(id: string): void {
+    const lib = this.get(id);
+    if (!lib) throw new Error(`Library not found: ${id}`);
+
+    const txn = this.db.transaction(() => {
+      // 1. Check for downloader instances connected to this library
+      const connected = this.stmtCountConnectedDownloaders.get(id) as { count: number };
+      if (connected.count > 0) {
+        throw new Error(
+          `Cannot delete library: ${connected.count} downloader instance(s) are connected to it. Disconnect them first.`,
+        );
+      }
+
+      // 2. Check for content type defaults
+      const defaults = this.stmtCountContentTypeDefaults.get(id) as { count: number };
+      if (defaults.count > 0) {
+        throw new Error(
+          `Cannot delete library: ${defaults.count} content type(s) have this library as default. Reassign them first.`,
+        );
+      }
+
+      // 3. Delete content type defaults (cascade should handle, but be explicit)
+      this.stmtDeleteContentTypeDefaults.run(id);
+
+      // 4. Delete the library
+      this.stmtDelete.run(id);
+    });
+    txn();
+
+    this.bus.emit("library.deleted", { libraryId: id, name: lib.name });
+  }
+
+  // ── Default library ──────────────────────────────────────
+
+  getGlobalDefault(): Library | undefined {
+    const row = this.stmtGetDefault.get() as Record<string, unknown> | undefined;
+    return row ? this.rowToLibrary(row) : undefined;
+  }
+
+  // ── Content type defaults ────────────────────────────────
+
+  getContentTypeDefaults(libraryId: string): string[] {
+    const rows = this.stmtGetContentTypeDefaults.all(libraryId) as Array<{ content_type_id: string }>;
+    return rows.map(r => r.content_type_id);
+  }
+
+  setContentTypeDefaults(libraryId: string, contentTypeIds: string[]): void {
+    const lib = this.get(libraryId);
+    if (!lib) throw new Error(`Library not found: ${libraryId}`);
+
+    const txn = this.db.transaction(() => {
+      this.stmtDeleteContentTypeDefaults.run(libraryId);
+      for (const ctId of contentTypeIds) {
+        this.stmtSetContentTypeDefault.run(libraryId, ctId);
+      }
+    });
+    txn();
+
+    this.bus.emit("library.content-types.updated", { libraryId, contentTypeIds });
+  }
+
+  /**
+   * Resolve which library should be used for a given content type.
+   * Priority:
+   * 1. Content type has explicit default library → use that.
+   * 2. Global default library → use that.
+   * 3. No libraries → undefined.
+   */
+  resolveForContentType(contentTypeId: string): { library: Library; libraryId: string } | undefined {
+    // Check content type defaults
+    const ctLibRow = this.db
+      .prepare("SELECT library_id FROM library_content_type_defaults WHERE content_type_id = ?")
+      .get(contentTypeId) as { library_id: string } | undefined;
+
+    if (ctLibRow) {
+      const lib = this.get(ctLibRow.library_id);
+      if (lib) return { library: lib, libraryId: lib.id };
+    }
+
+    // Fall back to global default
+    const globalDefault = this.getGlobalDefault();
+    if (globalDefault) return { library: globalDefault, libraryId: globalDefault.id };
+
+    return undefined;
+  }
+
+  // ── Helpers ──────────────────────────────────────────────
+
+  private rowToLibrary(row: Record<string, unknown>): Library {
+    let roots: Record<string, string>;
+    try {
+      roots = JSON.parse(row.roots as string);
+    } catch {
+      roots = {};
+    }
+
+    let subtitleExtensions: string[];
+    try {
+      subtitleExtensions = JSON.parse(row.subtitle_extensions as string);
+    } catch {
+      subtitleExtensions = ["srt", "ass", "ssa", "sub", "vtt"];
+    }
+
+    return {
+      id: row.id as string,
+      name: row.name as string,
+      description: (row.description as string) || undefined,
+      isDefault: (row.is_default as number) === 1,
+      defaultLibraryRoot: row.default_library_root as string,
+      roots,
+      linkType: row.link_type as "move" | "hardlink" | "symlink" | "copy",
+      importSubtitles: (row.import_subtitles as number) === 1,
+      subtitleExtensions,
+      createdAt: row.created_at as string,
+      updatedAt: row.updated_at as string,
+    };
+  }
+}

package/src/library/metadata-matcher.ts

@@ -0,0 +1,285 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+
+import type { ContentItemBase } from "@digitalpaws/starr-types-core";
+import type { EventBus, Logger, StarrEvent } from "../types/plugin.js";
+import type { ContentTypeRegistryImpl } from "../content-types/registry.js";
+import type { DiscoveredGroup } from "./library-scanner.js";
+
+export interface MatchResult {
+  item: ContentItemBase;
+  source: string; // plugin id
+  confidence: number; // 0..1
+}
+
+/**
+ * Default timeout for collecting discovery.results.
+ * Can be overridden via constructor for testing.
+ */
+const DEFAULT_DISCOVERY_WINDOW_MS = 10_000;
+
+/**
+ * Derive search terms from a folder name by stripping quality tags,
+ * group names, and normalizing separators.
+ *
+ * Examples:
+ *   "Dune (2021) [2160p]" → { title: "Dune", year: "2021", clean: "Dune" }
+ *   "The.Matrix.1999.1080p" → { title: "The Matrix", year: "1999", clean: "The Matrix" }
+ *   "A.Movie.Name.2020.REMASTERED.1080p.BluRay.x264-GROUP"
+ *     → { title: "A Movie Name", year: "2020", clean: "A Movie Name" }
+ */
+export function deriveSearchTerms(
+  folderName: string,
+): { title: string; year?: string; cleanTitle: string } {
+  let name = folderName;
+
+  // Step 1: Remove content in square brackets (quality tags, group names)
+  name = name.replace(/\[.*?\]/g, "");
+
+  // Step 2: Extract year from parentheses (YYYY) and remove them
+  let year: string | undefined;
+  const parenYearMatch = name.match(/\((\d{4})\)/);
+  if (parenYearMatch) {
+    year = parenYearMatch[1];
+    name = name.replace(/\(\s*\d{4}\s*\)/, "");
+  }
+
+  // Step 3: Replace dots and underscores with spaces
+  name = name.replace(/[._]/g, " ");
+
+  // Step 4: Remove trailing scene group tag: -GROUP at end
+  name = name.replace(/\s*-\s*\w+$/, "");
+
+  // Step 5: Remove common quality/resolution/format tags (as whole words)
+  name = name.replace(
+    /\s*(2160p|1080p|720p|480p|BluRay|WEB-?DL|WEBRip|HDRip|DVDRip|BRRip|x264|x265|HEVC|AAC|DTS|AC3|REMASTERED|EXTENDED|UNCUT|REMUX|PROPER|REPACK|INTERNAL|DIRECTORS?\s*CUT)\s*/gi,
+    " ",
+  );
+
+  // Step 6: If no year found yet, look for a bare 4-digit year (1900-2099)
+  // that appears as a separate token
+  if (!year) {
+    const bareYearMatch = name.match(/(?:^|\s)((?:19|20)\d{2})(?:$|\s)/);
+    if (bareYearMatch) {
+      year = bareYearMatch[1];
+      name = name.replace(bareYearMatch[0], " ");
+    }
+  }
+
+  // Step 7: Collapse whitespace and trim
+  const cleanTitle = name.replace(/\s+/g, " ").trim();
+
+  return { title: cleanTitle, year, cleanTitle };
+}
+
+/**
+ * Simple title similarity using Jaro-Winkler-like comparison.
+ * Returns a score between 0 (completely different) and 1 (exact match).
+ */
+function titleSimilarity(a: string, b: string): number {
+  const aLower = a.toLowerCase().trim();
+  const bLower = b.toLowerCase().trim();
+
+  if (aLower === bLower) return 1.0;
+
+  // Check if one contains the other
+  if (aLower.includes(bLower) || bLower.includes(aLower)) {
+    const shorter = Math.min(a.length, b.length);
+    const longer = Math.max(a.length, b.length);
+    return shorter / longer;
+  }
+
+  // Simple character overlap
+  const aChars = new Set(aLower.split(""));
+  const bChars = new Set(bLower.split(""));
+  const intersection = new Set([...aChars].filter((c) => bChars.has(c)));
+  const union = new Set([...aChars, ...bChars]);
+
+  return intersection.size / union.size;
+}
+
+export class MetadataMatcher {
+  private bus: EventBus;
+  private contentTypeRegistry: ContentTypeRegistryImpl;
+  private logger: Logger;
+  private discoveryWindowMs: number;
+
+  constructor(
+    bus: EventBus,
+    contentTypeRegistry: ContentTypeRegistryImpl,
+    logger: Logger,
+    discoveryWindowMs = DEFAULT_DISCOVERY_WINDOW_MS,
+  ) {
+    this.bus = bus;
+    this.contentTypeRegistry = contentTypeRegistry;
+    this.logger = logger.child("metadata-matcher");
+    this.discoveryWindowMs = discoveryWindowMs;
+  }
+
+  /**
+   * Attempt to find metadata matches for a discovered group.
+   * Returns up to 5 scored candidates, or an empty array if no match found.
+   * The first result is the best match. Also supports custom search queries.
+   */
+  async findMatches(group: DiscoveredGroup): Promise<MatchResult[]> {
+    const { folderName, contentTypeId } = group;
+    const searchTerms = deriveSearchTerms(folderName);
+    const contentTypeIds =
+      contentTypeId !== "unknown" ? [contentTypeId] : undefined;
+
+    if (!searchTerms.cleanTitle) {
+      this.logger.debug("empty search terms for folder", { folderName });
+      return [];
+    }
+
+    const terms = [searchTerms.cleanTitle];
+    if (searchTerms.year) {
+      terms.push(searchTerms.year);
+    }
+
+    return this.searchAndScore(terms, contentTypeIds, folderName);
+  }
+
+  /**
+   * Run a custom search for a folder and return scored results.
+   * Used when the user clicks "Search again" in the UI.
+   */
+  async searchCustom(
+    folderName: string,
+    query: string,
+    contentTypeId?: string,
+  ): Promise<MatchResult[]> {
+    const contentTypeIds =
+      contentTypeId && contentTypeId !== "unknown" ? [contentTypeId] : undefined;
+    const terms = query.split(/\s+/).filter(Boolean);
+    if (terms.length === 0) return [];
+    return this.searchAndScore(terms, contentTypeIds, folderName);
+  }
+
+  /**
+   * Low-level: emit discovery.search, collect results, score, return top N.
+   */
+  private async searchAndScore(
+    terms: string[],
+    contentTypeIds: string[] | undefined,
+    folderName: string,
+  ): Promise<MatchResult[]> {
+    if (!terms.length) return [];
+
+    try {
+      const results = await this.collectResults(terms, contentTypeIds);
+
+      if (results.length === 0) {
+        this.logger.debug("no metadata results for folder", { folderName });
+        return [];
+      }
+
+      // Score each result and pick the best
+      const searchTerms = deriveSearchTerms(folderName);
+      const scored = results
+        .map((r) => ({
+          item: r.item as ContentItemBase,
+          source: r.source,
+          confidence: this.scoreConfidence(r.item, searchTerms),
+        }))
+        .sort((a, b) => b.confidence - a.confidence);
+
+      const aboveThreshold = scored.filter((m) => m.confidence >= 0.1);
+
+      if (aboveThreshold.length === 0) {
+        this.logger.debug("all matches below confidence threshold", {
+          folderName,
+        });
+        return [];
+      }
+
+      this.logger.debug("metadata matches found", {
+        folderName,
+        count: aboveThreshold.length,
+        best: aboveThreshold[0].item.title,
+      });
+
+      // Return top 5
+      return aboveThreshold.slice(0, 5);
+    } catch (err) {
+      this.logger.error("metadata matching failed", {
+        folderName,
+        error: String(err),
+      });
+      return [];
+    }
+  }
+
+  /**
+   * Emit discovery.search and collect results within the timeout window.
+   */
+  private async collectResults(
+    terms: string[],
+    contentTypeIds?: string[],
+  ): Promise<Array<{ item: ContentItemBase; source: string }>> {
+    const results: Array<{ item: ContentItemBase; source: string }> = [];
+
+    return new Promise<Array<{ item: ContentItemBase; source: string }>>(
+      (resolve) => {
+        const unsub = this.bus.on(
+          "discovery.results",
+          (event: StarrEvent<{ contentTypeId: string; items: ContentItemBase[] }>) => {
+            for (const item of event.payload.items) {
+              results.push({ item, source: event.source });
+            }
+          },
+        );
+
+        // Timeout to stop collecting
+        const timer = setTimeout(() => {
+          unsub();
+          resolve(results);
+        }, this.discoveryWindowMs);
+
+        // Also stop on first result to reduce latency
+        // (we collect all within the window and score later)
+        // No early return — we want to collect all candidates for scoring.
+
+        // Emit the search
+        this.bus.emit("discovery.search", {
+          query: terms.join(" "),
+          contentTypeIds,
+          offset: 0,
+          limit: 10,
+        });
+
+        // Ensure cleanup if window expires
+        timer.unref?.();
+      },
+    );
+  }
+
+  /**
+   * Score a matched item against the search terms.
+   * Returns a value between 0 and 1.
+   */
+  private scoreConfidence(
+    item: ContentItemBase,
+    search: { title: string; year?: string; cleanTitle: string },
+  ): number {
+    let score = 0;
+
+    // Title similarity (0-0.6)
+    const sim = titleSimilarity(item.title, search.cleanTitle);
+    score += sim * 0.6;
+
+    // Year match bonus (0-0.2)
+    if (search.year) {
+      const itemYear = item.releaseDate?.slice(0, 4);
+      if (itemYear === search.year) {
+        score += 0.2;
+      }
+    }
+
+    // External ID bonus (0-0.2) — items with more IDs are more complete matches
+    const extIdCount = Object.keys(item.externalIds || {}).length;
+    score += Math.min(extIdCount / 5, 0.2);
+
+    return Math.min(score, 1.0);
+  }
+}

package/src/library/naming.ts

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+
+import type { ContentItemBase, NamingRule, NamingSegment } from "@digitalpaws/starr-types-core";
+
+/**
+ * Resolve a naming rule against an item's field values.
+ * Returns a relative path like "Movies/Dune (2021)/Dune (2021) [2160p].mkv".
+ * The caller joins this with the library root and appends the actual extension.
+ */
+export function resolveNaming(
+  rule: NamingRule,
+  item: ContentItemBase,
+  extension: string,
+): string {
+  const resolveSegments = (segments: NamingSegment[][]): string => {
+    return segments
+      .map((segmentGroup) =>
+        segmentGroup
+          .map((seg) => {
+            if (seg.type === "literal") return seg.value;
+            return resolveField(seg.value, item);
+          })
+          .join(""),
+      )
+      .join(" ");
+  };
+
+  const dirName = resolveSegments(rule.directory);
+  const baseName = resolveSegments(rule.filename);
+
+  return `${dirName}/${baseName}.${extension}`;
+}
+
+function resolveField(fieldName: string, item: ContentItemBase): string {
+  if (fieldName === "Title") return sanitise(item.title);
+  if (fieldName === "Year") {
+    const year = (item as any).year ?? (item as any).releaseDate?.slice(0, 4);
+    return year ? String(year) : "";
+  }
+  if (fieldName === "ContentType") return item.contentTypeId;
+
+  if (item.externalIds && fieldName in item.externalIds) {
+    return sanitise(String((item.externalIds as Record<string, unknown>)[fieldName]));
+  }
+
+  const fields = (item as any).fields as Record<string, unknown> | undefined;
+  if (fields && fieldName in fields) {
+    return sanitise(String(fields[fieldName]));
+  }
+
+  return "";
+}
+
+/** Remove characters that are problematic in filenames. */
+function sanitise(s: string): string {
+  // eslint-disable-next-line no-control-regex
+  return s.replace(/[<>:"\\|?*\x00-\x1f]/g, "").replace(/\s+/g, " ").trim();
+}