@digitalpaws/starr 0.0.1

package/src/plugins/loader.ts

@@ -0,0 +1,309 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { createContext } from "./context.js";
+import { discoverPluginDirs } from "./discovery.js";
+import type { PluginRuntime, Starr } from "../host.js";
+import type { RegisterFn } from "../types/plugin.js";
+function withTimeout<T>(
+  promise: Promise<T>,
+  ms: number,
+  label: string,
+): Promise<T> {
+  return Promise.race([
+    promise,
+    new Promise<T>((_, reject) =>
+      setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms),
+    ),
+  ]);
+}
+
+// ── Plugin registry (used for isolated reload) ────────────────────────
+
+interface PluginRecord {
+  dir: string;
+  ctx: ReturnType<typeof createContext>;
+  runtime: PluginRuntime;
+}
+
+const pluginRegistry = new Map<string, PluginRecord>();
+
+export async function loadPlugins(starr: Starr): Promise<void> {
+  const dirs = await discoverPluginDirs(starr.options.pluginsDir);
+  starr.logger.info("discovered plugins", {
+    count: dirs.length,
+    dirs: dirs.map((d) => path.basename(d)),
+  });
+
+  const db = starr.getDatabase();
+  if (!db) throw new Error("datastore not initialized; call openDatastore first");
+
+  // ── Pass 1: Discover plugin IDs ──────────────────────────
+  // Trial registration to get canonical plugin IDs before querying instances.
+  const pluginIdMap = new Map<string, { dir: string; entryUrl: string }>();
+
+  for (const dir of dirs) {
+    let pkg: { main: string };
+    try {
+      const pkgRaw = await readFile(path.join(dir, "package.json"), "utf8");
+      pkg = JSON.parse(pkgRaw) as { main: string };
+    } catch {
+      starr.logger.warn("skipping dir: no package.json", { dir });
+      continue;
+    }
+    const entryUrl = pathToFileURL(path.resolve(dir, pkg.main)).href;
+
+    // Trial context (no real config service)
+    const trialCtx = createContext(starr, dir, db, undefined);
+    try {
+      const mod = await import(entryUrl);
+      const register = mod.default as RegisterFn;
+      if (typeof register !== "function") {
+        starr.logger.warn("skipping dir: no default export function", { dir });
+        continue;
+      }
+      await register(trialCtx);
+      const meta = trialCtx.getMeta();
+      if (meta) {
+        pluginIdMap.set(meta.id, { dir, entryUrl });
+      }
+    } catch (err) {
+      starr.logger.warn("trial registration failed for dir (will retry with real instances)", { dir, error: String(err) });
+      // Guess pluginId from directory basename
+      const guessedId = path.basename(dir);
+      pluginIdMap.set(guessedId, { dir, entryUrl });
+    }
+  }
+
+  // ── Clean up trial registrations — roll back any content types ──
+  // that were registered during Pass 1, so Pass 2 can register them
+  // with the real context without triggering duplicate errors.
+  for (const pluginId of pluginIdMap.keys()) {
+    starr.contentTypeRegistry.rollbackPlugin(pluginId);
+  }
+
+  // ── Pass 2: Load instances ───────────────────────────────
+  const seenIds = new Set<string>();
+  const lifecycles: PluginRuntime[] = [];
+
+  for (const [pluginId, info] of pluginIdMap) {
+    // Get instance IDs from DB (or "default" if none)
+    const instanceRows = db
+      .prepare("SELECT DISTINCT instance_id FROM plugin_config WHERE plugin_id = ?")
+      .all(pluginId) as Array<{ instance_id: string }>;
+    const instanceIds = instanceRows.length > 0
+      ? instanceRows.map(r => r.instance_id)
+      : ["default"];
+
+    for (const instanceId of instanceIds) {
+      let ctx: ReturnType<typeof createContext> | undefined;
+      try {
+        ctx = createContext(starr, info.dir, db, starr.configService ?? undefined, instanceId);
+        const mod = await import(info.entryUrl);
+        const register = mod.default as RegisterFn;
+        if (typeof register !== "function") throw new Error("default export is not a function");
+        const lifecycle = (await register(ctx)) ?? {};
+        const meta = ctx.getMeta();
+        if (!meta) throw new Error("register did not call ctx.define");
+
+        const fullInstanceId = `${meta.id}::${instanceId}`;
+        if (seenIds.has(fullInstanceId)) {
+          throw new Error(`duplicate instance: ${fullInstanceId}`);
+        }
+        seenIds.add(fullInstanceId);
+
+        const runtime: PluginRuntime = {
+          meta: { ...meta, id: fullInstanceId },
+          lifecycle,
+          startOrder: -1,
+        };
+        lifecycles.push(runtime);
+        pluginRegistry.set(fullInstanceId, { dir: info.dir, ctx: ctx!, runtime });
+      } catch (err) {
+        starr.logger.error("instance registration failed", {
+          pluginId, instanceId, error: String(err),
+        });
+        if (ctx) {
+          ctx.unsubscribeAll();
+          ctx.deleteAllStorage().catch(e =>
+            starr.logger.error("storage rollback failed", { pluginId, instanceId, error: String(e) }),
+          );
+          const meta = ctx.getMeta();
+          if (meta) {
+            starr.contentTypeRegistry.rollbackPlugin(meta.id);
+          }
+        }
+      }
+    }
+  }
+
+  // Start pass
+  let order = 0;
+  for (const runtime of lifecycles) {
+    if (runtime.lifecycle.start) {
+      try {
+        await withTimeout(
+          Promise.resolve(runtime.lifecycle.start()),
+          30_000,
+          `start(${runtime.meta.id})`,
+        );
+        runtime.startOrder = order++;
+      } catch (err) {
+        starr.logger.error("plugin start failed", {
+          id: runtime.meta.id,
+          error: String(err),
+        });
+        runtime.startOrder = -1;
+      }
+    } else {
+      runtime.startOrder = order++;
+    }
+  }
+
+  starr.setRuntimes(lifecycles);
+}
+
+/**
+ * Reload a single plugin in isolation: stop → unregister → re-import → start.
+ * In multi-instance mode, all instances of the plugin are reloaded.
+ */
+export async function reloadPlugin(
+  starr: Starr,
+  pluginId: string,
+): Promise<void> {
+  // Find all instances matching this pluginId (pluginId::instanceId or plain pluginId)
+  const records: Array<{ fullId: string; record: PluginRecord }> = [];
+  for (const [fullId, record] of pluginRegistry) {
+    if (fullId === pluginId || fullId.startsWith(`${pluginId}::`)) {
+      records.push({ fullId, record });
+    }
+  }
+
+  if (records.length === 0) {
+    starr.logger.warn("reload requested for unknown plugin", { pluginId });
+    return;
+  }
+
+  starr.logger.info("reloading plugin instances", { pluginId, count: records.length });
+
+  // 1. Stop all instances
+  for (const { fullId, record } of records) {
+    if (record.runtime.lifecycle.stop) {
+      try {
+        await withTimeout(
+          Promise.resolve(record.runtime.lifecycle.stop()),
+          10_000,
+          `reload-stop(${fullId})`,
+        );
+      } catch (err) {
+        starr.logger.error("plugin stop failed during reload", {
+          pluginId: fullId,
+          error: String(err),
+        });
+      }
+    }
+    record.ctx.unsubscribeAll();
+  }
+
+  // 2. Remove from runtimes list
+  const runtimes = [...starr.getRuntimes()].filter(
+    (r) => !records.some(({ fullId }) => r.meta.id === fullId),
+  );
+  starr.setRuntimes(runtimes);
+
+  // 3. For each instance, re-import and start
+  for (const { fullId, record } of records) {
+    const pkgRaw = await readFile(
+      path.join(record.dir, "package.json"), "utf8",
+    );
+    const pkg = JSON.parse(pkgRaw) as { main: string };
+    const entryUrl = pathToFileURL(
+      path.resolve(record.dir, pkg.main),
+    ).href;
+    const cacheBustUrl = `${entryUrl}?reload=${Date.now()}`;
+
+    try {
+      const mod = await import(cacheBustUrl);
+      const register = mod.default as RegisterFn;
+      if (typeof register !== "function") {
+        throw new Error("default export is not a function");
+      }
+
+      const db = starr.getDatabase();
+      if (!db) throw new Error("datastore not available");
+
+      // Extract instanceId from fullId (pluginId::instanceId)
+      const instanceId = fullId.includes("::") ? fullId.split("::")[1] : "default";
+
+      const newCtx = createContext(
+        starr,
+        record.dir,
+        db,
+        starr.configService ?? undefined,
+        instanceId,
+      );
+      const lifecycle = (await register(newCtx)) ?? {};
+      const meta = newCtx.getMeta();
+      if (!meta) throw new Error("register did not call ctx.define");
+
+      const startOrder = runtimes.length;
+      if (lifecycle.start) {
+        try {
+          await withTimeout(
+            Promise.resolve(lifecycle.start()),
+            30_000,
+            `reload-start(${fullId})`,
+          );
+        } catch (err) {
+          starr.logger.error("plugin start failed during reload", {
+            pluginId: fullId,
+            error: String(err),
+          });
+        }
+      }
+
+      const newRuntime: PluginRuntime = { meta: { ...meta, id: fullId }, lifecycle, startOrder };
+      pluginRegistry.set(fullId, {
+        dir: record.dir,
+        ctx: newCtx,
+        runtime: newRuntime,
+      });
+      runtimes.push(newRuntime);
+
+      starr.logger.info("plugin instance reloaded", { pluginId: fullId });
+    } catch (err) {
+      starr.logger.error("plugin instance reload failed", {
+        pluginId: fullId,
+        error: String(err),
+      });
+      pluginRegistry.delete(fullId);
+    }
+  }
+
+  starr.setRuntimes(runtimes);
+}
+
+export async function stopPlugins(starr: Starr): Promise<void> {
+  const runtimes = [...starr.getRuntimes()]
+    .filter((r) => r.startOrder >= 0)
+    .sort((a, b) => b.startOrder - a.startOrder);
+  for (const runtime of runtimes) {
+    if (runtime.lifecycle.stop) {
+      try {
+        await withTimeout(
+          Promise.resolve(runtime.lifecycle.stop()),
+          10_000,
+          `stop(${runtime.meta.id})`,
+        );
+      } catch (err) {
+        starr.logger.error("plugin stop failed", {
+          id: runtime.meta.id,
+          error: String(err),
+        });
+      }
+    }
+  }
+}

package/src/state/request-intake.ts

@@ -0,0 +1,101 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+
+import { randomUUID } from "node:crypto";
+import type { ContentItemBase } from "@digitalpaws/starr-types-core";
+import type { EventBus, Logger } from "../types/plugin.js";
+import { computeContentIdentity, ContentTypeRegistryImpl } from "../content-types/registry.js";
+import { StateStore } from "./state-store.js";
+import type { LibraryService } from "../library/library-service.js";
+
+export interface RequestIntakeInput {
+  /** The user making the request (v1: always "admin"). */
+  userId: string;
+  /** The content item selected from browse/discovery. */
+  item: ContentItemBase;
+}
+
+/**
+ * Process a user request for content.
+ *
+ * 1. Compute the item's contentIdentity via the content-type registry.
+ * 2. Look for an existing non-failed TrackedRequest with that identity (DU1).
+ * 3. If found: add the user as a watcher and return the existing requestId (DU2).
+ * 4. If not found (or prior is failed): create a new TrackedRequest in status
+ *    "requested", then emit "content.requested" to start the pipeline (DU3).
+ *
+ * Resolves target library for the request via LibraryService (if available).
+ *
+ * @returns The requestId (either existing or newly created).
+ */
+export function requestIntake(
+  input: RequestIntakeInput,
+  store: StateStore,
+  registry: ContentTypeRegistryImpl,
+  bus: EventBus,
+  logger: Logger,
+  libraryService?: LibraryService,
+): string {
+  // 1. Compute content identity
+  const contentIdentity = computeContentIdentity(input.item, registry);
+  logger.debug("request intake: computed identity", {
+    contentTypeId: input.item.contentTypeId,
+    contentIdentity,
+  });
+
+  // 2. Look for existing non-failed request (DU1)
+  const existing = store.findByContentIdentity(contentIdentity);
+
+  if (existing) {
+    // 3. Found — attach as watcher (DU2)
+    logger.debug("request intake: attaching to existing request", {
+      existingRequestId: existing.requestId,
+      existingStatus: existing.status,
+    });
+    store.addWatcher(existing.requestId, input.userId);
+    return existing.requestId;
+  }
+
+  // 4. Not found (or only failed exists) — create new (DU3)
+  const requestId = randomUUID();
+
+  // Determine target library (FR-RIR-01)
+  let libraryId: string | undefined;
+  if (libraryService) {
+    const resolved = libraryService.resolveForContentType(input.item.contentTypeId);
+    if (resolved) {
+      libraryId = resolved.libraryId;
+      logger.debug("request intake: resolved library", {
+        contentTypeId: input.item.contentTypeId,
+        libraryId,
+      });
+    }
+  }
+
+  logger.info("request intake: creating new tracked request", {
+    requestId,
+    contentTypeId: input.item.contentTypeId,
+    contentIdentity,
+    libraryId,
+  });
+
+  store.insert({
+    requestId,
+    contentTypeId: input.item.contentTypeId,
+    contentIdentity,
+    item: input.item,
+    ownerUserId: input.userId,
+    libraryId,
+  });
+
+  // Emit content.requested to start the acquisition pipeline
+  bus.emit("content.requested", {
+    requestId,
+    userId: input.userId,
+    contentTypeId: input.item.contentTypeId,
+    item: input.item,
+    libraryId,
+  });
+
+  return requestId;
+}