@digitalpaws/starr 0.0.1

package/src/library/scan-controller.ts

@@ -0,0 +1,490 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import type Database from "better-sqlite3";
+import type { EventBus, Logger } from "../types/plugin.js";
+import type { LibraryScanCandidate, ContentItemBase } from "@digitalpaws/starr-types-core";
+import { LibraryScanner, type DiscoveredGroup } from "./library-scanner.js";
+import { MetadataMatcher } from "./metadata-matcher.js";
+import { LibraryCache } from "./library-cache.js";
+import type { ContentTypeRegistryImpl } from "../content-types/registry.js";
+import { computeContentIdentity } from "../content-types/registry.js";
+import type { Importer } from "./importer.js";
+
+/**
+ * In-memory scan state, keyed by scanId.
+ */
+interface ScanState {
+  scanId: string;
+  status: "scanning" | "matching" | "complete" | "cancelled";
+  progress: {
+    total: number;
+    completed: number;
+    matched: number;
+    noMatch: number;
+    alreadyImported: number;
+  };
+  candidates: LibraryScanCandidate[];
+}
+
+const activeScans = new Map<string, ScanState>();
+
+const DEFAULT_CONCURRENCY = 3;
+
+/**
+ * Simple semaphore for concurrency control.
+ */
+class Semaphore {
+  private current = 0;
+  private queue: (() => void)[] = [];
+
+  constructor(private max: number) {}
+
+  async acquire(): Promise<void> {
+    if (this.current < this.max) {
+      this.current++;
+      return;
+    }
+    return new Promise((resolve) => {
+      this.queue.push(resolve);
+    });
+  }
+
+  release(): void {
+    if (this.queue.length > 0) {
+      const next = this.queue.shift()!;
+      next();
+    } else {
+      this.current--;
+    }
+  }
+}
+
+export class ScanController {
+  private scanner: LibraryScanner;
+  private matcher: MetadataMatcher;
+  private db: Database.Database;
+  private bus: EventBus;
+  private logger: Logger;
+  private libraryCache: LibraryCache;
+  private contentTypeRegistry: ContentTypeRegistryImpl;
+  private importer: Importer;
+  private concurrency: number;
+
+  constructor(
+    scanner: LibraryScanner,
+    matcher: MetadataMatcher,
+    db: Database.Database,
+    bus: EventBus,
+    logger: Logger,
+    libraryCache: LibraryCache,
+    contentTypeRegistry: ContentTypeRegistryImpl,
+    importer: Importer,
+    concurrency = DEFAULT_CONCURRENCY,
+  ) {
+    this.scanner = scanner;
+    this.matcher = matcher;
+    this.db = db;
+    this.bus = bus;
+    this.logger = logger.child("scan-controller");
+    this.libraryCache = libraryCache;
+    this.contentTypeRegistry = contentTypeRegistry;
+    this.importer = importer;
+    this.concurrency = concurrency;
+  }
+
+  /**
+   * Start an async scan. Returns the scanId immediately.
+   * The scan runs in the background; progress is polled via getScan().
+   *
+   * @param libraryId Optional — scan only this library.
+   * @param contentTypeIds Optional — scan only roots for these content types.
+   */
+  startScan(libraryId?: string, contentTypeIds?: string[]): string {
+    const scanId = randomUUID();
+    const state: ScanState = {
+      scanId,
+      status: "scanning",
+      progress: { total: 0, completed: 0, matched: 0, noMatch: 0, alreadyImported: 0 },
+      candidates: [],
+    };
+    activeScans.set(scanId, state);
+
+    // Run scan in background (not awaited)
+    this.runScan(scanId, state, libraryId, contentTypeIds).catch((err) => {
+      this.logger.error("scan failed", { scanId, error: String(err) });
+      state.status = "complete";
+    });
+
+    return scanId;
+  }
+
+  /**
+   * Get the current state of a scan.
+   */
+  getScan(scanId: string): ScanState | undefined {
+    return activeScans.get(scanId);
+  }
+
+  /**
+   * Cancel a running scan.
+   */
+  cancelScan(scanId: string): boolean {
+    const state = activeScans.get(scanId);
+    if (!state || state.status === "complete") return false;
+    state.status = "cancelled";
+    return true;
+  }
+
+  /**
+   * Import accepted candidates into the library.
+   * Phase 1: Create tracked_request rows in a transaction (sync).
+   * Phase 2: Process each via the Importer (async) so library config
+   *          (roots, link type, subtitles, naming) is applied correctly.
+   */
+  async importCandidates(
+    scanId: string,
+    candidateIds: string[],
+  ): Promise<{ imported: number; failed: number; errors: Array<{ id: string; error: string }> }> {
+    const state = activeScans.get(scanId);
+    if (!state) {
+      return { imported: 0, failed: 0, errors: [] };
+    }
+
+    const errors: Array<{ id: string; error: string }> = [];
+
+    // Phase 1: Create all tracked_request rows in a single transaction.
+    // Each entry captures what the Importer needs without doing the actual file I/O.
+    const pending: Array<{
+      requestId: string;
+      primaryFile: string;
+      item: ContentItemBase;
+      contentTypeId: string;
+      extension: string;
+      contentIdentity: string;
+      libraryId?: string;
+    }> = [];
+
+    const txn = this.db.transaction(() => {
+      for (const candidateId of candidateIds) {
+        const candidate = state.candidates.find((c) => c.id === candidateId);
+        if (!candidate) {
+          errors.push({ id: candidateId, error: "candidate not found" });
+          continue;
+        }
+
+        try {
+          const result = this.createTrackedRequest(candidate);
+          if (result) pending.push(result);
+        } catch (err: any) {
+          errors.push({ id: candidateId, error: err.message });
+        }
+      }
+    });
+
+    txn();
+
+    // Phase 2: Process each candidate through the Importer.
+    // The Importer handles file transfer (link type), subtitle importing,
+    // naming-rule resolution, library_path insertion, and event emission.
+    let imported = 0;
+    for (const p of pending) {
+      try {
+        const result = await this.importer.import(
+          p.requestId,
+          p.primaryFile,
+          p.item,
+          p.contentTypeId,
+          p.extension,
+          p.contentIdentity,
+          p.libraryId,
+        );
+        if (result.success) {
+          imported++;
+        } else {
+          errors.push({ id: p.requestId, error: result.error ?? "importer returned failure" });
+        }
+      } catch (err: any) {
+        errors.push({ id: p.requestId, error: err.message });
+      }
+    }
+
+    return { imported, failed: errors.length, errors };
+  }
+
+  /**
+   * Remove a completed scan from memory.
+   */
+  cleanupScan(scanId: string): void {
+    activeScans.delete(scanId);
+  }
+
+  // ── Private ──
+
+  private async runScan(
+    scanId: string,
+    state: ScanState,
+    libraryId?: string,
+    contentTypeIds?: string[],
+  ): Promise<void> {
+    // Phase 1: Discover groups
+    this.emitProgress(scanId, state);
+    const groups = await this.scanner.discoverGroups({ libraryId, contentTypeIds });
+
+    if (state.status === "cancelled") return;
+
+    state.candidates = groups.map((g) => this.groupToCandidate(g));
+    state.progress.total = groups.length;
+
+    // Find already-imported items
+    const dirs = groups.map((g) => g.directory);
+    const existing = this.scanner.findExisting(dirs);
+    for (const candidate of state.candidates) {
+      if (existing.has(candidate.directory)) {
+        candidate.alreadyImported = true;
+        candidate.status = "already-imported";
+        candidate.accepted = false;
+        state.progress.alreadyImported++;
+      }
+    }
+
+    state.status = "matching";
+    this.emitProgress(scanId, state);
+
+    // Phase 2: Match metadata for non-imported candidates
+    const sem = new Semaphore(this.concurrency);
+    const matchTasks = state.candidates
+      .filter((c) => !c.alreadyImported)
+      .map(async (candidate) => {
+        await sem.acquire();
+        try {
+          if (state.status === "cancelled") return;
+
+          const group = groups.find((g) => g.directory === candidate.directory);
+          if (!group) return;
+
+          const matches = await this.matcher.findMatches(group);
+          if (matches.length > 0) {
+            candidate.matches = matches;
+            candidate.selectedMatchIndex = 0;
+            candidate.status = "matched";
+            candidate.accepted = true;
+            state.progress.matched++;
+          } else {
+            candidate.matches = [];
+            candidate.selectedMatchIndex = -1;
+            candidate.status = "no-match";
+            state.progress.noMatch++;
+          }
+
+          state.progress.completed++;
+          this.emitProgress(scanId, state);
+        } catch (err) {
+          candidate.status = "error";
+          candidate.error = String(err);
+          state.progress.completed++;
+          this.emitProgress(scanId, state);
+        } finally {
+          sem.release();
+        }
+      });
+
+    await Promise.all(matchTasks);
+
+    state.status = "complete";
+    this.emitProgress(scanId, state);
+    this.logger.info("scan complete", {
+      scanId,
+      total: state.progress.total,
+      matched: state.progress.matched,
+      noMatch: state.progress.noMatch,
+      alreadyImported: state.progress.alreadyImported,
+    });
+  }
+
+  /**
+   * Run a custom search for a specific candidate and update its matches.
+   * Called from the API when the user clicks "Search again".
+   */
+  async searchCandidate(
+    scanId: string,
+    candidateId: string,
+    query: string,
+  ): Promise<boolean> {
+    const state = activeScans.get(scanId);
+    if (!state) return false;
+
+    const candidate = state.candidates.find((c) => c.id === candidateId);
+    if (!candidate) return false;
+
+    try {
+      const matches = await this.matcher.searchCustom(
+        candidate.folderName,
+        query,
+        candidate.contentTypeId,
+      );
+      candidate.matches = matches;
+      candidate.selectedMatchIndex = matches.length > 0 ? 0 : -1;
+      candidate.status = matches.length > 0 ? "matched" : "no-match";
+      candidate.accepted = matches.length > 0;
+      return true;
+    } catch (err) {
+      this.logger.error("custom search failed", {
+        scanId,
+        candidateId,
+        error: String(err),
+      });
+      return false;
+    }
+  }
+
+  /**
+   * Update the user's selected match index for a candidate.
+   */
+  selectMatch(scanId: string, candidateId: string, matchIndex: number): boolean {
+    const state = activeScans.get(scanId);
+    if (!state) return false;
+    const candidate = state.candidates.find((c) => c.id === candidateId);
+    if (!candidate) return false;
+    if (matchIndex < -1 || matchIndex >= candidate.matches.length) return false;
+    candidate.selectedMatchIndex = matchIndex;
+    candidate.accepted = matchIndex >= 0;
+    return true;
+  }
+
+  private groupToCandidate(group: DiscoveredGroup): LibraryScanCandidate {
+    return {
+      id: randomUUID(),
+      directory: group.directory,
+      files: group.files,
+      contentTypeId: group.contentTypeId,
+      libraryId: group.libraryId,
+      folderName: group.folderName,
+      matches: [],
+      selectedMatchIndex: -1,
+      accepted: false,
+      alreadyImported: false,
+      status: "pending",
+    };
+  }
+
+  private emitProgress(scanId: string, state: ScanState): void {
+    this.bus.emit("library.scan.progress", {
+      scanId,
+      status: state.status,
+      progress: state.progress,
+    });
+  }
+
+  /**
+   * Create a tracked_request row for a scanned candidate.
+   * Runs inside a transaction. Returns the data the Importer needs,
+   * or null if the candidate has no media files.
+   *
+   * Unlike the old importSingleCandidate, this does NOT:
+   * - Insert into library_paths (the Importer handles that)
+   * - Set library_path on tracked_requests (the Importer sets it)
+   * - Emit events (the Importer emits them)
+   */
+  private createTrackedRequest(candidate: LibraryScanCandidate): {
+    requestId: string;
+    primaryFile: string;
+    item: ContentItemBase;
+    contentTypeId: string;
+    extension: string;
+    contentIdentity: string;
+    libraryId?: string;
+  } | null {
+    const requestId = randomUUID();
+
+    // Get the selected match, if any
+    const selectedMatch =
+      candidate.selectedMatchIndex >= 0 && candidate.selectedMatchIndex < candidate.matches.length
+        ? candidate.matches[candidate.selectedMatchIndex]
+        : null;
+
+    // Determine the correct contentTypeId: prefer the match's value when
+    // available (metadata sources return the real ID), otherwise fall back
+    // to the scanner-assigned ID (which may be "unknown" for default-root items).
+    const resolvedContentTypeId = selectedMatch
+      ? selectedMatch.item.contentTypeId
+      : candidate.contentTypeId;
+
+    // Build the ContentItemBase from selected match or folder name
+    const item: ContentItemBase = selectedMatch
+      ? { ...selectedMatch.item, contentTypeId: resolvedContentTypeId }
+      : {
+          contentTypeId: resolvedContentTypeId,
+          title: candidate.folderName,
+          externalIds: {},
+        };
+
+    // Pick the primary media file
+    const primaryFile = this.pickPrimaryFile(candidate.files);
+
+    // Compute content identity using the resolved content type ID
+    const contentIdentity = selectedMatch
+      ? computeContentIdentity(
+          { contentTypeId: resolvedContentTypeId, externalIds: item.externalIds },
+          this.contentTypeRegistry,
+        )
+      : `${resolvedContentTypeId}::local::${candidate.folderName}`;
+
+    // Determine file extension for the Importer
+    const extension = path.extname(primaryFile).slice(1).toLowerCase() || "mkv";
+
+    const now = new Date().toISOString();
+
+    // Insert into tracked_requests — no library_path set here.
+    // The Importer will update it after the file transfer.
+    this.db
+      .prepare(
+        `INSERT INTO tracked_requests
+           (request_id, content_type_id, content_identity, item,
+            owner_user_id, watchers, status, library_id, attempts, created_at, updated_at)
+         VALUES
+           (@requestId, @contentTypeId, @contentIdentity, @item,
+            @ownerUserId, '[]', 'downloaded', @libraryId, 0, @createdAt, @updatedAt)`,
+      )
+      .run({
+        requestId,
+        contentTypeId: resolvedContentTypeId,
+        contentIdentity,
+        item: JSON.stringify(item),
+        ownerUserId: "admin",
+        libraryId: candidate.libraryId ?? null,
+        createdAt: now,
+        updatedAt: now,
+      });
+
+    return {
+      requestId,
+      primaryFile,
+      item,
+      contentTypeId: resolvedContentTypeId,
+      extension,
+      contentIdentity,
+      libraryId: candidate.libraryId,
+    };
+  }
+
+  private pickPrimaryFile(files: string[]): string {
+    if (files.length === 0) throw new Error("no media files to import");
+    if (files.length === 1) return files[0];
+
+    // Prefer the file whose basename best matches the parent folder name
+    const dirName = path.basename(path.dirname(files[0]));
+    const exactMatch = files.find((f) => {
+      const base = path.basename(f, path.extname(f));
+      return base.toLowerCase() === dirName.toLowerCase();
+    });
+    if (exactMatch) return exactMatch;
+
+    // Fall back to first file
+    return files[0];
+  }
+
+
+}

package/src/library/source-resolver.ts

@@ -0,0 +1,92 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const MEDIA_EXTENSIONS = new Set([
+  "mkv", "mp4", "avi", "mov", "wmv", "flv", "webm",
+  "m4v", "mpg", "mpeg", "ts", "m2ts",
+]);
+
+export interface ResolvedSource {
+  /** The directory containing the source files. */
+  sourceDir: string;
+  /** All media files found at the source location. */
+  files: string[];
+}
+
+/**
+ * Return true if the file extension looks like a media file.
+ */
+function isMediaFile(filePath: string): boolean {
+  const ext = path.extname(filePath).slice(1).toLowerCase();
+  return MEDIA_EXTENSIONS.has(ext);
+}
+
+/**
+ * Scan a directory (non-recursive) for media files.
+ * Skips hidden directories and common non-content subdirectories.
+ */
+async function scanDirectory(dir: string): Promise<string[]> {
+  const results: string[] = [];
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      // Skip common non-content directories
+      if (entry.name.startsWith(".")) continue;
+      if (entry.name === "Extras" || entry.name === "Sample" || entry.name === "samples") continue;
+      const nested = await scanDirectory(fullPath);
+      results.push(...nested);
+    } else if (entry.isFile() && isMediaFile(fullPath)) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+
+/**
+ * Resolve the source path from a download.completed event.
+ *
+ * Resolution order:
+ * 1. If location is provided and the stripped path exists:
+ *    - If it is a file → return it as the only file
+ *    - If it is a directory → scan for media files
+ * 2. If all fail → throw with a descriptive message.
+ */
+export async function resolveSourcePath(
+  location: string | undefined,
+): Promise<ResolvedSource> {
+  if (!location) {
+    throw new Error(
+      "Cannot resolve source path: no location provided on download.completed",
+    );
+  }
+
+  // Strip protocol prefix (e.g. "qbittorrent:/path" → "/path")
+  const colonIdx = location.indexOf(":");
+  const strippedPath = colonIdx >= 0 ? location.slice(colonIdx + 1) : location;
+
+  try {
+    const stat = await fs.stat(strippedPath);
+    if (stat.isFile()) {
+      const dir = path.dirname(strippedPath);
+      return { sourceDir: dir, files: [strippedPath] };
+    }
+    if (stat.isDirectory()) {
+      const files = await scanDirectory(strippedPath);
+      if (files.length === 0) {
+        throw new Error(`No media files found in directory: ${strippedPath}`);
+      }
+      return { sourceDir: strippedPath, files };
+    }
+  } catch (err: any) {
+    throw new Error(
+      `Cannot access source path "${strippedPath}": ${err.message}`,
+      { cause: err },
+    );
+  }
+
+  throw new Error(`Source path is neither a file nor a directory: ${strippedPath}`);
+}

package/src/logging/logger.ts

@@ -0,0 +1,115 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+
+import { env } from "node:process";
+import path from "node:path";
+import fs from "node:fs";
+
+import type { Logger } from "../types/plugin.js";
+
+const LEVELS: Record<string, number> = { debug: 10, info: 20, warn: 30, error: 40 };
+
+function resolveLogFilePath(): string | undefined {
+  const explicit = env.STARR_LOG_FILE;
+  if (explicit === "") return undefined; // disabled
+  if (explicit) return path.resolve(explicit);
+
+  const dataDir = env.STARR_DATA_DIR ?? "./data";
+  return path.resolve(dataDir, "logs", "starr.log");
+}
+
+function ensureLogDir(logPath: string): void {
+  const dir = path.dirname(logPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+export function createLogger(tag = "core", levelName = "info"): Logger {
+  const consoleLevel = LEVELS[levelName] ?? LEVELS.info;
+  const fileLevelName = env.STARR_LOG_FILE_LEVEL ?? levelName;
+  const fileLevel = LEVELS[fileLevelName] ?? consoleLevel;
+
+  const logFilePath = resolveLogFilePath();
+  let fileHandle: number | undefined;
+  let fileErrorLogged = false;
+
+  function openFile(): number | undefined {
+    if (!logFilePath) return undefined;
+    try {
+      ensureLogDir(logFilePath);
+      return fs.openSync(logFilePath, "a");
+    } catch (err) {
+      if (!fileErrorLogged) {
+        console.warn(JSON.stringify({
+          timestamp: new Date().toISOString(),
+          level: "warn",
+          tag: "core/logging",
+          message: "Failed to open log file",
+          path: logFilePath,
+          error: String(err),
+        }));
+        fileErrorLogged = true;
+      }
+      return undefined;
+    }
+  }
+
+  function log(level: string, message: string, meta?: Record<string, unknown>) {
+    const levelValue = LEVELS[level] ?? LEVELS.info;
+    const line: Record<string, unknown> = {
+      timestamp: new Date().toISOString(),
+      level,
+      tag,
+      message,
+      ...(meta ?? {}),
+    };
+
+    // Console sink
+    if (levelValue >= consoleLevel) {
+      console.log(JSON.stringify(line));
+    }
+
+    // File sink
+    if (logFilePath && levelValue >= fileLevel) {
+      if (fileHandle === undefined) {
+        fileHandle = openFile();
+      }
+      if (fileHandle !== undefined) {
+        try {
+          fs.writeSync(fileHandle, JSON.stringify(line) + "\n");
+        } catch (err) {
+          if (!fileErrorLogged) {
+            console.warn(JSON.stringify({
+              timestamp: new Date().toISOString(),
+              level: "warn",
+              tag: "core/logging",
+              message: "Failed to write to log file",
+              path: logFilePath,
+              error: String(err),
+            }));
+            fileErrorLogged = true;
+          }
+        }
+      }
+    }
+  }
+
+  if (fileHandle !== undefined) {
+    process.once("exit", () => {
+      try {
+        fs.closeSync(fileHandle!);
+      } catch {
+        // ignore close errors
+      }
+    });
+  }
+
+  return {
+    debug: (m, meta) => log("debug", m, meta),
+    info: (m, meta) => log("info", m, meta),
+    warn: (m, meta) => log("warn", m, meta),
+    error: (m, meta) => log("error", m, meta),
+    child: (childTag) => createLogger(`${tag}/${childTag}`, levelName),
+  };
+}