@digitalpaws/starr 0.0.1

package/src/main.ts

@@ -0,0 +1,364 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+
+export type {
+  PluginContext,
+  PluginLifecycle,
+  PluginMeta,
+  ConfigSchema,
+  ConfigField,
+  Logger,
+  EventBus,
+  PluginStorage,
+  ContentTypeRegistry,
+  RegisterFn,
+  StarrEvent,
+  EventHandler,
+  Unsubscribe,
+  EmitOpts,
+  RequestOpts,
+  ConnectionTestResult,
+} from "./types/plugin.js";
+
+export {
+  SPINE_EVENTS,
+  SPINE_NAMESPACES,
+  isSpineType,
+  validateSpineEmission,
+} from "./events/spine.js";
+
+export { EventBusImpl } from "./events/event-bus.js";
+
+export { Starr } from "./host.js";
+export type { StarrOptions, PluginRuntime } from "./host.js";
+export { createLogger } from "./logging/logger.js";
+export { discoverPluginDirs } from "./plugins/discovery.js";
+export { createContext } from "./plugins/context.js";
+export { loadPlugins, stopPlugins } from "./plugins/loader.js";
+
+export {
+  ContentTypeRegistryImpl,
+  validateDescriptor,
+  computeContentIdentity,
+  areSameItem,
+} from "./content-types/registry.js";
+
+export { StateStore } from "./state/state-store.js";
+export type {
+  TrackedRequest,
+  TrackedRequestData,
+  RequestStatus,
+  TraceEntry,
+} from "./state/state-store.js";
+export { requestIntake } from "./state/request-intake.js";
+export type { RequestIntakeInput } from "./state/request-intake.js";
+
+export { AuthService } from "./auth/auth-service.js";
+export { createAuthServer, authenticate, withAuth, parseCookies, COOKIE_NAME } from "./auth/http-server.js";
+export { loadJwtSecret, getJwtSecret, resetJwtSecret } from "./auth/jwt-secret.js";
+export { RateLimiter } from "./auth/rate-limiter.js";
+
+export { Importer } from "./library/importer.js";
+export type { ImportResult } from "./library/importer.js";
+export { LibraryService } from "./library/library-service.js";
+export type { Library, LibraryInput } from "./library/library-service.js";
+export { resolveNaming } from "./library/naming.js";
+export type { NamingRule, NamingSegment } from "@digitalpaws/starr-types-core";
+export { DEFAULT_LIBRARY_CONFIG } from "./library/library-config.js";
+export type { LibraryConfig, LibraryRoots } from "./library/library-config.js";
+export { LibraryCache } from "./library/library-cache.js";
+export type { CachedLibraryItem } from "./library/library-cache.js";
+export { resolveSourcePath } from "./library/source-resolver.js";
+export type { ResolvedSource } from "./library/source-resolver.js";
+export { LibraryScanner } from "./library/library-scanner.js";
+export type { DiscoveredGroup } from "./library/library-scanner.js";
+export { MetadataMatcher } from "./library/metadata-matcher.js";
+export type { MatchResult } from "./library/metadata-matcher.js";
+export { ScanController } from "./library/scan-controller.js";
+
+// Bootstrap — only run when this module is the entry point (not during tests/imports).
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const isMain = process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1]);
+
+if (isMain) {
+  const { Starr } = await import("./host.js");
+  const { createLogger } = await import("./logging/logger.js");
+  const { loadPlugins, stopPlugins } = await import("./plugins/loader.js");
+  const { openDatastore } = await import("./datastore/db.js");
+  const { runMigrations, CORE_MIGRATIONS } = await import("./datastore/migrations.js");
+  const { loadEncryptionKey } = await import("./datastore/encrypt.js");
+  const { ConfigService } = await import("./config/config-service.js");
+  const { StateStore } = await import("./state/state-store.js");
+  const { loadJwtSecret } = await import("./auth/jwt-secret.js");
+  const { AuthService } = await import("./auth/auth-service.js");
+  const { createWebServer, initAuthService, initOidcServices } = await import("./web/index.js");
+  const { initContentTypeRoutes } = await import("./web/routes/content-types.js");
+  const { initDiscoveryRoutes } = await import("./web/routes/discovery.js");
+  const { initRequestRoutes } = await import("./web/routes/requests.js");
+  const { initConfigRoutes } = await import("./web/routes/config.js");
+  const { initActivityRoutes } = await import("./web/routes/activity.js");
+  const { initSseRoutes } = await import("./web/routes/sse.js");
+  const { initAuthRoutes } = await import("./web/routes/auth.js");
+  const { initTraceStore } = await import("./state/trace-store.js");
+  const { OidcProviderService } = await import("./auth/oidc/oidc-provider-service.js");
+  const { UserService } = await import("./auth/oidc/user-service.js");
+  const { OidcFlow } = await import("./auth/oidc/oidc-flow.js");
+  const { Importer } = await import("./library/importer.js");
+  const { getNamingRule } = await import("./content-types/registry.js");
+  const { DEFAULT_LIBRARY_CONFIG } = await import("./library/library-config.js");
+  const { LibraryService } = await import("./library/library-service.js");
+  const { LibraryCache } = await import("./library/library-cache.js");
+  const { initLibraryRoutes } = await import("./web/routes/library.js");
+  const { initLibraryManagementRoutes } = await import("./web/routes/library-management.js");
+  const { initLibraryImportRoutes } = await import("./web/routes/library-import.js");
+  const { LibraryScanner } = await import("./library/library-scanner.js");
+  const { MetadataMatcher } = await import("./library/metadata-matcher.js");
+  const { ScanController } = await import("./library/scan-controller.js");
+  const { resolveSourcePath } = await import("./library/source-resolver.js");
+
+  async function main() {
+    const pluginsDir = path.resolve(process.env.STARR_PLUGINS_DIR ?? "./plugins");
+    const dataDir = path.resolve(process.env.STARR_DATA_DIR ?? "./data");
+    const apiVersion = process.env.STARR_API_VERSION ?? "1.0.0";
+    const logLevel = process.env.STARR_LOG_LEVEL ?? "info";
+
+    const logger = createLogger("core", logLevel);
+
+    // 1. Open datastore
+    const datastore = openDatastore(dataDir, logger);
+
+    // 2. Run core migrations
+    runMigrations(datastore.db, CORE_MIGRATIONS, logger);
+
+    // 3. Load encryption key
+    loadEncryptionKey(dataDir, logger);
+
+    // 3a. Load JWT secret
+    loadJwtSecret(dataDir, logger);
+
+    // 4. Create host
+    const starr = new Starr({ pluginsDir, apiVersion, logger });
+    starr.datastore = datastore;
+
+    // 5. Create ConfigService (after datastore and encryption are ready)
+    const configService = new ConfigService(
+      datastore.db,
+      logger.child("config"),
+      // Reload callback — use lazy import to avoid circular deps
+      async (pluginId: string) => {
+        const { reloadPlugin } = await import("./plugins/loader.js");
+        await reloadPlugin(starr, pluginId);
+      },
+    );
+    starr.configService = configService;
+
+    // 6. Initialize state store (subscribes to spine events)
+    const stateStore = new StateStore(
+      datastore.db,
+      starr.coreBus,
+      logger,
+    );
+    starr.stateStore = stateStore;
+
+    // 5a. Create LibraryService (after migrations so table exists)
+    const libraryService = new LibraryService(
+      datastore.db,
+      starr.coreBus,
+      logger.child("library-service"),
+    );
+    starr.libraryService = libraryService;
+
+    // Bootstrap default library if none exist
+    const defaultLib = libraryService.getGlobalDefault();
+    if (!defaultLib) {
+      libraryService.create({
+        name: "Default Library",
+        isDefault: true,
+        defaultLibraryRoot: DEFAULT_LIBRARY_CONFIG.defaultLibraryRoot,
+        linkType: DEFAULT_LIBRARY_CONFIG.linkType,
+        importSubtitles: DEFAULT_LIBRARY_CONFIG.importSubtitles,
+        subtitleExtensions: [...DEFAULT_LIBRARY_CONFIG.subtitleExtensions],
+      });
+      logger.info("created default library");
+    }
+
+    // 6a. Create importer (reacts to download.completed)
+    const importer = new Importer(
+      datastore.db,
+      starr.coreBus,
+      logger,
+      () => {
+        const defaultLib = libraryService.getGlobalDefault();
+        return {
+          defaultLibraryRoot: defaultLib?.defaultLibraryRoot ?? DEFAULT_LIBRARY_CONFIG.defaultLibraryRoot,
+          roots: defaultLib?.roots ?? {},
+          linkType: defaultLib?.linkType ?? DEFAULT_LIBRARY_CONFIG.linkType,
+          importSubtitles: defaultLib?.importSubtitles ?? DEFAULT_LIBRARY_CONFIG.importSubtitles,
+          subtitleExtensions: defaultLib?.subtitleExtensions ?? DEFAULT_LIBRARY_CONFIG.subtitleExtensions,
+        };
+      },
+      (contentTypeId: string) => getNamingRule(contentTypeId, starr.contentTypeRegistry),
+      libraryService,
+    );
+    starr.importer = importer;
+
+    // 6b. Create library cache (populated from imported items)
+    const libraryCache = new LibraryCache(datastore.db, starr.coreBus, logger);
+    libraryCache.refreshFromDb();
+    starr.libraryCache = libraryCache;
+
+    // 6c. Create library scanner, metadata matcher, and scan controller
+    const libraryScanner = new LibraryScanner(
+      datastore.db,
+      logger,
+      libraryService,
+    );
+    const metadataMatcher = new MetadataMatcher(
+      starr.coreBus,
+      starr.contentTypeRegistry,
+      logger,
+    );
+    const scanController = new ScanController(
+      libraryScanner,
+      metadataMatcher,
+      datastore.db,
+      starr.coreBus,
+      logger,
+      libraryCache,
+      starr.contentTypeRegistry,
+      importer,
+    );
+    starr.scanController = scanController;
+
+    // Subscribe importer to download.completed
+    starr.coreBus.on("download.completed", async (event) => {
+      const payload = event.payload as {
+        requestId: string; release: any; location?: string; libraryId?: string;
+      };
+      const req = stateStore.getByRequestId(payload.requestId);
+      if (!req) return;
+
+      try {
+        const resolved = await resolveSourcePath(payload.location);
+
+        // Import each media file found at the source
+        let anySucceeded = false;
+        for (const filePath of resolved.files) {
+          const ext = path.extname(filePath).slice(1).toLowerCase() || "mkv";
+          const result = await importer.import(
+            payload.requestId, filePath, req.item, req.contentTypeId, ext,
+            req.contentIdentity,
+            payload.libraryId,
+          );
+          if (result.success) {
+            anySucceeded = true;
+          } else {
+            logger.error("import failed for file", {
+              requestId: payload.requestId,
+              file: filePath,
+              error: result.error,
+            });
+          }
+        }
+
+        if (!anySucceeded) {
+          logger.error("all imports failed", { requestId: payload.requestId });
+        }
+      } catch (err) {
+        logger.error("import resolution failed", {
+          requestId: payload.requestId,
+          error: String(err),
+        });
+      }
+    });
+
+    // 7. Create AuthService (before web server so auth hook can reference it)
+    const authService = new AuthService(datastore.db, logger.child("auth"));
+
+    // 7a. Create UserService
+    const userService = new UserService(datastore.db, logger.child("users"));
+
+    // 7b. Create OIDC Provider Service
+    const { encrypt, decrypt } = await import("./datastore/encrypt.js");
+    const oidcProviderService = new OidcProviderService(
+      datastore.db,
+      (plaintext: string) => encrypt(plaintext),
+      (ciphertext: string) => decrypt(ciphertext),
+      logger.child("oidc-providers"),
+    );
+
+    // 7c. Create OIDC Flow
+    const port = parseInt(process.env.STARR_PORT ?? "3457", 10);
+    const baseUrl = process.env.STARR_BASE_URL ?? `http://localhost:${port}`;
+    const oidcFlow = new OidcFlow(
+      datastore.db,
+      oidcProviderService,
+      userService,
+      baseUrl,
+      logger.child("oidc-flow"),
+    );
+
+    // 8. Create web server (registers route stubs via dynamic import, auth hook)
+    const webServer = await createWebServer(logger.child("web"));
+    starr.webServer = webServer;
+
+    // Wire auth routes and auth hook into web server
+    initAuthService(authService);
+    initAuthRoutes(authService);
+
+    // Wire OIDC services into web server (so oidc route init gets them)
+    initOidcServices(oidcProviderService, oidcFlow, userService);
+
+    // Wire config routes (configService already exists)
+    initConfigRoutes(configService, () => starr.getRuntimes());
+
+    // Wire trace-store wrapper
+    initTraceStore(stateStore);
+
+    // 9. Load plugins (populates content-type registry, event bus handlers)
+    logger.info("booting", { pluginsDir, apiVersion, dataDir });
+    await loadPlugins(starr);
+
+    // 10. Wire remaining routes that depend on plugin-loaded data
+    initContentTypeRoutes(
+      () => starr.contentTypeRegistry.list(),
+      (id: string) => starr.contentTypeRegistry.get(id),
+    );
+    initDiscoveryRoutes(starr.coreBus);
+    initRequestRoutes(starr);
+    initActivityRoutes(starr);
+    initSseRoutes(starr.coreBus);
+    initLibraryRoutes(libraryCache);
+    initLibraryManagementRoutes(libraryService);
+    initLibraryImportRoutes(scanController);
+
+    // 11. Start web server
+    await webServer.listen({ port, host: "0.0.0.0" });
+    logger.info("web server listening", { port });
+
+    starr.markRunning();
+
+    // 12. Graceful shutdown
+    let shuttingDown = false;
+    for (const signal of ["SIGTERM", "SIGINT"]) {
+      process.on(signal, async () => {
+        if (shuttingDown) return;
+        shuttingDown = true;
+        logger.info("shutting down", { signal });
+        // Close web server first to release the port immediately
+        try { await webServer.close(); } catch { /* ignore close errors during shutdown */ }
+        await stopPlugins(starr);
+        starr.markStopped();
+        datastore.close();
+        process.exit(0);
+      });
+    }
+  }
+
+  main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}

package/src/plugins/context.ts

@@ -0,0 +1,138 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+
+import semver from "semver";
+import path from "node:path";
+import type Database from "better-sqlite3";
+import type { ConfigSchema, Logger, PluginContext, PluginMeta, PluginStorage, EventBus, EmitOpts, RequestOpts } from "../types/plugin.js";
+import type { Starr } from "../host.js";
+import type { ConfigService } from "../config/config-service.js";
+
+import { createPluginStorage } from "../datastore/storage.js";
+
+export function createContext(
+  starr: Starr,
+  pluginDir: string,
+  db: Database.Database,
+  configService?: ConfigService,
+  instanceId = "default",
+): PluginContext & {
+  getMeta: () => PluginMeta | undefined;
+  unsubscribeAll: () => void;
+  deleteAllStorage: () => Promise<void>;
+} {
+  let meta: PluginMeta | undefined;
+  let defined = false;
+  let _storage: PluginStorage | null = null;
+  let _subscriptions: Array<() => void> = [];
+
+  const guard = () => {
+    if (!defined) throw new Error("ctx.define must be called before any other context method");
+  };
+
+  let logger: Logger = starr.logger.child(path.basename(pluginDir));
+
+  const context: PluginContext & {
+    getMeta: () => PluginMeta | undefined;
+    unsubscribeAll: () => void;
+    deleteAllStorage: () => Promise<void>;
+  } = {
+    apiVersion: starr.apiVersion,
+
+    define(m) {
+      if (defined) throw new Error("ctx.define can only be called once");
+      if (!m.id) throw new Error("plugin id is required");
+      if (!semver.valid(m.version)) throw new Error(`invalid plugin version: ${m.version}`);
+      if (!semver.validRange(m.starrApiVersion))
+        throw new Error(`invalid api range: ${m.starrApiVersion}`);
+      if (!semver.satisfies(starr.apiVersion, m.starrApiVersion)) {
+        throw new Error(
+          `API version mismatch: host ${starr.apiVersion} does not satisfy ${m.starrApiVersion}`,
+        );
+      }
+      meta = m;
+      defined = true;
+      logger = starr.logger.child(m.id);
+      logger.debug("defined", { meta: m });
+    },
+
+    config<T>(schema: ConfigSchema<T>) {
+      guard();
+      if (!meta) throw new Error("ctx.config called before ctx.define");
+      if (configService) {
+        return configService.register(meta.id, schema, instanceId) as Readonly<T>;
+      }
+      // Fallback for tests / bootstrap paths that do not provide a ConfigService
+      const values: Record<string, unknown> = {};
+      for (const [key, field] of Object.entries(schema)) {
+        values[key] = (field as { default?: unknown }).default ?? undefined;
+      }
+      return Object.freeze(values) as Readonly<T>;
+    },
+
+    events: (() => {
+      let _pluginBus: EventBus | null = null;
+      const getBus = (): EventBus => {
+        if (!_pluginBus) {
+          _pluginBus = starr.busImpl.pluginBus(meta!.id);
+        }
+        return _pluginBus;
+      };
+      return {
+        on<P>(type: string, handler: (event: import("../types/plugin.js").StarrEvent<P>) => void | Promise<void>) {
+          guard();
+          const unsub = getBus().on(type, handler);
+          _subscriptions.push(unsub);
+          return unsub;
+        },
+        emit<P>(type: string, payload: P, opts?: EmitOpts) {
+          guard();
+          getBus().emit(type, payload, opts);
+        },
+        request<Res>(type: string, payload: unknown, opts: RequestOpts) {
+          guard();
+          return getBus().request<Res>(type, payload, opts);
+        },
+      };
+    })(),
+
+    get storage(): PluginStorage {
+      if (!_storage && defined && meta) {
+        _storage = createPluginStorage(db, meta.id, instanceId);
+      }
+      if (!_storage) {
+        throw new Error("ctx.storage called before ctx.define");
+      }
+      return _storage;
+    },
+
+    contentTypes: {
+      register(descriptor) {
+        guard();
+        if (!meta) throw new Error("ctx.contentTypes.register called before ctx.define");
+        starr.contentTypeRegistry.register(descriptor, meta.id);
+        logger.debug("registered content type", { typeId: descriptor.id });
+      },
+    },
+
+    get logger() {
+      return logger;
+    },
+
+    getMeta: () => meta,
+
+    unsubscribeAll: () => {
+      for (const unsub of _subscriptions) unsub();
+      _subscriptions = [];
+    },
+
+    deleteAllStorage: async () => {
+      if (_storage) {
+        await _storage.deleteAll();
+        _storage = null;
+      }
+    },
+  };
+
+  return context;
+}

package/src/plugins/discovery.ts

@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+
+import { readdir, stat } from "node:fs/promises";
+import path from "node:path";
+
+export async function discoverPluginDirs(pluginsDir: string): Promise<string[]> {
+  let entries;
+  try {
+    entries = await readdir(pluginsDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const dirs: string[] = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name.startsWith(".")) continue;
+    if (entry.name === "node_modules") continue;
+    const full = path.join(pluginsDir, entry.name);
+    try {
+      await stat(path.join(full, "package.json"));
+      dirs.push(full);
+    } catch {
+      // not a plugin package
+    }
+  }
+  return dirs.sort((a, b) => path.basename(a).localeCompare(path.basename(b)));
+}