@digitalpaws/starr 0.0.1

package/dist/datastore/migrations.js

@@ -0,0 +1,340 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+const CREATE_MIGRATIONS_TABLE = `
+  CREATE TABLE IF NOT EXISTS _migrations (
+    id         INTEGER PRIMARY KEY,
+    name       TEXT    NOT NULL UNIQUE,
+    applied_at TEXT    NOT NULL DEFAULT (datetime('now'))
+  );
+`;
+export function runMigrations(db, migrations, logger) {
+    db.exec(CREATE_MIGRATIONS_TABLE);
+    const applied = new Set(db
+        .prepare("SELECT id FROM _migrations")
+        .all()
+        .map((row) => row.id));
+    const pending = migrations
+        .filter((m) => !applied.has(m.id))
+        .sort((a, b) => a.id - b.id);
+    if (pending.length === 0) {
+        logger.debug("no pending migrations");
+        return;
+    }
+    logger.info("running migrations", { count: pending.length });
+    const insert = db.prepare("INSERT INTO _migrations (id, name) VALUES (@id, @name)");
+    const runOne = db.transaction((migrations) => {
+        for (const m of migrations) {
+            logger.debug("applying migration", { id: m.id, name: m.name });
+            db.exec(m.up);
+            insert.run({ id: m.id, name: m.name });
+        }
+    });
+    runOne(pending);
+    logger.info("migrations complete");
+}
+// ── Core migrations ──────────────────────────────────────────
+export const CORE_MIGRATIONS = [
+    {
+        id: 1,
+        name: "create_plugin_storage",
+        up: `
+      CREATE TABLE IF NOT EXISTS plugin_storage (
+        plugin_id  TEXT NOT NULL,
+        key        TEXT NOT NULL,
+        value      TEXT NOT NULL,
+        updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+        PRIMARY KEY (plugin_id, key)
+      );
+    `,
+    },
+    {
+        id: 2,
+        name: "create_plugin_config",
+        up: `
+      CREATE TABLE IF NOT EXISTS plugin_config (
+        plugin_id  TEXT NOT NULL PRIMARY KEY,
+        schema     TEXT NOT NULL DEFAULT '{}',
+        "values"     TEXT NOT NULL DEFAULT '{}',
+        updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+    `,
+    },
+    {
+        id: 3,
+        name: "create_tracked_requests",
+        up: `
+      CREATE TABLE IF NOT EXISTS tracked_requests (
+        request_id        TEXT NOT NULL PRIMARY KEY,
+        content_type_id   TEXT NOT NULL,
+        content_identity  TEXT NOT NULL,
+        item              TEXT NOT NULL,
+        owner_user_id     TEXT NOT NULL,
+        watchers          TEXT NOT NULL DEFAULT '[]',
+        status            TEXT NOT NULL,
+        status_detail     TEXT,
+        chosen_release_id TEXT,
+        attempts          INTEGER NOT NULL DEFAULT 0,
+        created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at        TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+      CREATE INDEX IF NOT EXISTS idx_tracked_requests_identity
+        ON tracked_requests(content_identity);
+    `,
+    },
+    {
+        id: 4,
+        name: "create_trace_log",
+        up: `
+      CREATE TABLE IF NOT EXISTS trace_log (
+        id           INTEGER PRIMARY KEY AUTOINCREMENT,
+        trace_id     TEXT NOT NULL,
+        request_id   TEXT NOT NULL,
+        event_type   TEXT NOT NULL,
+        event_data   TEXT NOT NULL,
+        timestamp    TEXT NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_trace_log_request
+        ON trace_log(request_id);
+      CREATE INDEX IF NOT EXISTS idx_trace_log_trace
+        ON trace_log(trace_id, id);
+    `,
+    },
+    {
+        id: 5,
+        name: "create_accounts_and_sessions",
+        up: `
+      CREATE TABLE IF NOT EXISTS admin_accounts (
+        username      TEXT NOT NULL PRIMARY KEY,
+        password_hash TEXT NOT NULL,
+        created_at    TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at    TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      CREATE TABLE IF NOT EXISTS sessions (
+        session_id TEXT NOT NULL PRIMARY KEY,
+        user_id    TEXT NOT NULL REFERENCES admin_accounts(username) ON DELETE CASCADE,
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        expires_at TEXT NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_sessions_user_id
+        ON sessions(user_id);
+    `,
+    },
+    {
+        id: 6,
+        name: "create_users_and_oidc_providers",
+        up: `
+      -- Users table: unified account for local admin and OIDC users
+      CREATE TABLE IF NOT EXISTS users (
+        id               TEXT NOT NULL PRIMARY KEY,  -- UUID
+        username         TEXT NOT NULL UNIQUE,
+        display_name     TEXT,
+        avatar_url       TEXT,
+        role             TEXT NOT NULL DEFAULT 'user' CHECK(role IN ('admin', 'user')),
+        provider         TEXT NOT NULL DEFAULT 'local' CHECK(provider IN ('local', 'oidc')),
+        oidc_sub         TEXT,  -- OIDC 'sub' claim (unique per provider)
+        oidc_provider_id TEXT REFERENCES oidc_providers(id) ON DELETE SET NULL,
+        created_at       TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at       TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_users_oidc_sub
+        ON users(oidc_sub, oidc_provider_id);
+
+      -- OIDC provider configuration
+      CREATE TABLE IF NOT EXISTS oidc_providers (
+        id              TEXT NOT NULL PRIMARY KEY,  -- UUID
+        name            TEXT NOT NULL,
+        issuer_url      TEXT NOT NULL,
+        client_id       TEXT NOT NULL,
+        client_secret   TEXT NOT NULL,  -- encrypted at rest
+        scopes          TEXT NOT NULL DEFAULT 'openid profile email',
+        role_attribute  TEXT,  -- JSONPath to a claim, e.g. "$.starr_roles"
+        default_role    TEXT NOT NULL DEFAULT 'user' CHECK(default_role IN ('admin', 'user')),
+        enabled         INTEGER NOT NULL DEFAULT 1,
+        created_at      TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at      TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      -- Temporary state for in-flight OIDC authorization flows
+      CREATE TABLE IF NOT EXISTS oidc_auth_states (
+        state         TEXT NOT NULL PRIMARY KEY,  -- random CSRF token
+        nonce         TEXT NOT NULL,
+        code_verifier TEXT NOT NULL,
+        provider_id   TEXT NOT NULL REFERENCES oidc_providers(id) ON DELETE CASCADE,
+        redirect_to   TEXT NOT NULL DEFAULT '/browse',
+        created_at    TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_oidc_auth_states_created
+        ON oidc_auth_states(created_at);
+
+      -- Recreate sessions table without FK constraint so OIDC user UUIDs work
+      CREATE TABLE IF NOT EXISTS sessions_new (
+        session_id TEXT NOT NULL PRIMARY KEY,
+        user_id    TEXT NOT NULL,
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        expires_at TEXT NOT NULL
+      );
+      INSERT INTO sessions_new (session_id, user_id, created_at, expires_at)
+        SELECT session_id, user_id, created_at, expires_at FROM sessions;
+      DROP TABLE sessions;
+      ALTER TABLE sessions_new RENAME TO sessions;
+
+      CREATE INDEX IF NOT EXISTS idx_sessions_user_id
+        ON sessions(user_id);
+
+      -- Migrate existing admin to users table
+      INSERT OR IGNORE INTO users (id, username, display_name, role, provider, created_at, updated_at)
+      SELECT
+        'admin',                                              -- id (fixed key for the local admin)
+        username,                                             -- username from admin_accounts
+        username,                                             -- display_name (same as username)
+        'admin',                                              -- role
+        'local',                                              -- provider
+        COALESCE(created_at, datetime('now')),
+        COALESCE(updated_at, datetime('now'))
+      FROM admin_accounts;
+    `,
+    },
+    {
+        id: 7,
+        name: "create_library_tracking",
+        up: `
+      -- Track the on-disk library path for each imported request
+      CREATE TABLE IF NOT EXISTS library_paths (
+        request_id     TEXT NOT NULL PRIMARY KEY REFERENCES tracked_requests(request_id) ON DELETE CASCADE,
+        library_path   TEXT NOT NULL,
+        library_root   TEXT NOT NULL,
+        file_size      INTEGER,
+        checksum       TEXT,
+        imported_at    TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at     TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      -- Add library_path column to tracked_requests for quick access
+      ALTER TABLE tracked_requests ADD COLUMN library_path TEXT;
+    `,
+    },
+    {
+        id: 8,
+        name: "create_library_cache",
+        up: `
+      -- Cache of imported item metadata for fast Browse loading.
+      -- Populated on import and refreshed on host start.
+      CREATE TABLE IF NOT EXISTS library_cache (
+        request_id       TEXT NOT NULL PRIMARY KEY REFERENCES tracked_requests(request_id) ON DELETE CASCADE,
+        content_type_id  TEXT NOT NULL,
+        content_identity TEXT NOT NULL,
+        title            TEXT NOT NULL,
+        sort_title       TEXT,
+        summary          TEXT,
+        release_date     TEXT,
+        images           TEXT,  -- JSON array of ContentImage
+        external_ids     TEXT NOT NULL,  -- JSON Record<string, string>
+        fields           TEXT,  -- JSON Record<string, unknown>
+        library_path     TEXT NOT NULL,
+        file_size        INTEGER,
+        imported_at      TEXT NOT NULL,
+        updated_at       TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_library_cache_content_type
+        ON library_cache(content_type_id);
+
+      CREATE INDEX IF NOT EXISTS idx_library_cache_identity
+        ON library_cache(content_identity);
+    `,
+    },
+    {
+        id: 9,
+        name: "create_libraries",
+        up: `
+      CREATE TABLE IF NOT EXISTS libraries (
+        id                    TEXT NOT NULL PRIMARY KEY,
+        name                  TEXT NOT NULL UNIQUE,
+        description           TEXT,
+        is_default            INTEGER NOT NULL DEFAULT 0,
+        default_library_root  TEXT NOT NULL DEFAULT '/media/library',
+        roots                 TEXT NOT NULL DEFAULT '{}',
+        link_type             TEXT NOT NULL DEFAULT 'hardlink' CHECK(link_type IN ('move','hardlink','symlink','copy')),
+        import_subtitles      INTEGER NOT NULL DEFAULT 1,
+        subtitle_extensions   TEXT NOT NULL DEFAULT '["srt","ass","ssa","sub","vtt"]',
+        created_at            TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at            TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      CREATE TABLE IF NOT EXISTS library_content_type_defaults (
+        library_id      TEXT NOT NULL REFERENCES libraries(id) ON DELETE CASCADE,
+        content_type_id TEXT NOT NULL,
+        PRIMARY KEY (content_type_id)
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_library_content_type_defaults_library
+        ON library_content_type_defaults(library_id);
+    `,
+    },
+    {
+        id: 10,
+        name: "add_instance_id_to_plugin_tables",
+        up: `
+      CREATE TABLE IF NOT EXISTS plugin_config_new (
+        plugin_id   TEXT NOT NULL,
+        instance_id TEXT NOT NULL DEFAULT 'default',
+        schema      TEXT NOT NULL DEFAULT '{}',
+        "values"    TEXT NOT NULL DEFAULT '{}',
+        updated_at  TEXT NOT NULL DEFAULT (datetime('now')),
+        PRIMARY KEY (plugin_id, instance_id)
+      );
+
+      INSERT INTO plugin_config_new (plugin_id, instance_id, schema, "values", updated_at)
+      SELECT plugin_id, 'default', schema, "values", updated_at FROM plugin_config;
+
+      DROP TABLE plugin_config;
+      ALTER TABLE plugin_config_new RENAME TO plugin_config;
+
+      CREATE TABLE IF NOT EXISTS plugin_storage_new (
+        plugin_id   TEXT NOT NULL,
+        instance_id TEXT NOT NULL DEFAULT 'default',
+        key         TEXT NOT NULL,
+        value       TEXT NOT NULL,
+        updated_at  TEXT NOT NULL DEFAULT (datetime('now')),
+        PRIMARY KEY (plugin_id, instance_id, key)
+      );
+
+      INSERT INTO plugin_storage_new (plugin_id, instance_id, key, value, updated_at)
+      SELECT plugin_id, 'default', key, value, updated_at FROM plugin_storage;
+
+      DROP TABLE plugin_storage;
+      ALTER TABLE plugin_storage_new RENAME TO plugin_storage;
+    `,
+    },
+    {
+        id: 11,
+        name: "add_library_id_to_tracked_requests",
+        up: `
+      ALTER TABLE tracked_requests ADD COLUMN library_id TEXT REFERENCES libraries(id);
+    `,
+    },
+    {
+        id: 12,
+        name: "migrate_existing_imported_to_downloaded",
+        up: `
+      UPDATE tracked_requests
+      SET status = 'downloaded', updated_at = datetime('now')
+      WHERE status = 'imported';
+    `,
+    },
+    {
+        id: 13,
+        name: "remove_orphaned_core_configs",
+        up: `
+      -- Remove leftover _core.* config rows that were replaced by the
+      -- library service and multi-instance systems (Task 039).
+      DELETE FROM plugin_config WHERE plugin_id IN ('_core.library', '_core.downloads');
+      DELETE FROM plugin_storage WHERE plugin_id IN ('_core.library', '_core.downloads');
+    `,
+    },
+];
+//# sourceMappingURL=migrations.js.map

package/dist/datastore/migrations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.js","sourceRoot":"","sources":["../../src/datastore/migrations.ts"],"names":[],"mappings":"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"}

package/dist/datastore/storage.d.ts

@@ -0,0 +1,4 @@
+import type Database from "better-sqlite3";
+import type { PluginStorage } from "../types/plugin.js";
+export declare function createPluginStorage(db: Database.Database, pluginId: string, instanceId?: string): PluginStorage;
+//# sourceMappingURL=storage.d.ts.map

package/dist/datastore/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/datastore/storage.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAC3C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,QAAQ,EAAE,MAAM,EAChB,UAAU,SAAY,GACrB,aAAa,CAwEf"}

package/dist/datastore/storage.js

@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+export function createPluginStorage(db, pluginId, instanceId = "default") {
+    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(key) {
+            const row = getStmt.get({ pluginId, instanceId, key });
+            if (!row)
+                return undefined;
+            try {
+                return JSON.parse(row.value);
+            }
+            catch {
+                return undefined;
+            }
+        },
+        async set(key, value) {
+            setStmt.run({ pluginId, instanceId, key, value: JSON.stringify(value) });
+        },
+        async delete(key) {
+            deleteStmt.run({ pluginId, instanceId, key });
+        },
+        async list(prefix) {
+            const stmt = prefix !== undefined ? listPrefixStmt : listAllStmt;
+            const params = prefix !== undefined
+                ? { pluginId, instanceId, prefix: `${prefix}%` }
+                : { pluginId, instanceId };
+            const rows = stmt.all(params);
+            return rows.map((row) => {
+                let value;
+                try {
+                    value = JSON.parse(row.value);
+                }
+                catch {
+                    value = undefined;
+                }
+                return { key: row.key, value: value };
+            });
+        },
+        async deleteAll() {
+            deleteAllStmt.run({ pluginId, instanceId });
+        },
+    };
+}
+//# sourceMappingURL=storage.js.map

package/dist/datastore/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../../src/datastore/storage.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,4DAA4D;AAK5D,MAAM,UAAU,mBAAmB,CACjC,EAAqB,EACrB,QAAgB,EAChB,UAAU,GAAG,SAAS;IAEtB,MAAM,OAAO,GAAG,EAAE,CAAC,OAAO,CACxB,2GAA2G,CAC5G,CAAC;IACF,MAAM,OAAO,GAAG,EAAE,CAAC,OAAO,CAAC;;;;;;GAM1B,CAAC,CAAC;IACH,MAAM,UAAU,GAAG,EAAE,CAAC,OAAO,CAC3B,qGAAqG,CACtG,CAAC;IACF,MAAM,WAAW,GAAG,EAAE,CAAC,OAAO,CAC5B;;kBAEc,CACf,CAAC;IACF,MAAM,cAAc,GAAG,EAAE,CAAC,OAAO,CAC/B;;kBAEc,CACf,CAAC;IACF,MAAM,aAAa,GAAG,EAAE,CAAC,OAAO,CAC9B,sFAAsF,CACvF,CAAC;IAEF,OAAO;QACL,KAAK,CAAC,GAAG,CAAI,GAAW;YACtB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,EAAE,CAExC,CAAC;YACd,IAAI,CAAC,GAAG;gBAAE,OAAO,SAAS,CAAC;YAC3B,IAAI,CAAC;gBACH,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAM,CAAC;YACpC,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,SAAS,CAAC;YACnB,CAAC;QACH,CAAC;QAED,KAAK,CAAC,GAAG,CAAI,GAAW,EAAE,KAAQ;YAChC,OAAO,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC3E,CAAC;QAED,KAAK,CAAC,MAAM,CAAC,GAAW;YACtB,UAAU,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC;QAChD,CAAC;QAED,KAAK,CAAC,IAAI,CACR,MAAe;YAEf,MAAM,IAAI,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,WAAW,CAAC;YACjE,MAAM,MAAM,GAAG,MAAM,KAAK,SAAS;gBACjC,CAAC,CAAC,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,EAAE;gBAChD,CAAC,CAAC,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC;YAC7B,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAA0C,CAAC;YACvE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;gBACtB,IAAI,KAAoB,CAAC;gBACzB,IAAI,CAAC;oBACH,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAM,CAAC;gBACrC,CAAC;gBAAC,MAAM,CAAC;oBACP,KAAK,GAAG,SAAS,CAAC;gBACpB,CAAC;gBACD,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,KAAU,EAAE,CAAC;YAC7C,CAAC,CAAC,CAAC;QACL,CAAC;QAED,KAAK,CAAC,SAAS;YACb,aAAa,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC,CAAC;QAC9C,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/events/event-bus.d.ts

@@ -0,0 +1,15 @@
+import type { Logger } from "../types/plugin.js";
+import type { EventBus } from "../types/plugin.js";
+export declare class EventBusImpl {
+    private subscriptions;
+    private logger;
+    constructor(logger: Logger);
+    /** Returns an EventBus bound to the given plugin id. */
+    pluginBus(pluginId: string): EventBus;
+    /** Returns an EventBus with source="core". */
+    coreBus(): EventBus;
+    private _on;
+    private _emit;
+    private _request;
+}
+//# sourceMappingURL=event-bus.d.ts.map

package/dist/events/event-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.d.ts","sourceRoot":"","sources":["../../src/events/event-bus.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAEV,QAAQ,EAKT,MAAM,oBAAoB,CAAC;AAI5B,qBAAa,YAAY;IACvB,OAAO,CAAC,aAAa,CAAwC;IAC7D,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,EAAE,MAAM;IAM1B,wDAAwD;IACxD,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ;IAUrC,8CAA8C;IAC9C,OAAO,IAAI,QAAQ;IAMnB,OAAO,CAAC,GAAG;IAcX,OAAO,CAAC,KAAK;IAuEb,OAAO,CAAC,QAAQ;CAkDjB"}

package/dist/events/event-bus.js

@@ -0,0 +1,140 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+import { randomUUID } from "node:crypto";
+import { runInTraceContext, getCurrentTraceId } from "./trace.js";
+import { getSpineSchemaVersion, validateSpineEmission } from "./spine.js";
+export class EventBusImpl {
+    subscriptions = new Map();
+    logger;
+    constructor(logger) {
+        this.logger = logger.child("event-bus");
+    }
+    // ---- Public factory methods ---- //
+    /** Returns an EventBus bound to the given plugin id. */
+    pluginBus(pluginId) {
+        return {
+            on: (type, handler) => this._on(type, handler),
+            emit: (type, payload, opts) => this._emit(pluginId, type, payload, opts),
+            request: (type, payload, opts) => this._request(pluginId, type, payload, opts),
+        };
+    }
+    /** Returns an EventBus with source="core". */
+    coreBus() {
+        return this.pluginBus("core");
+    }
+    // ---- Private implementation ---- //
+    _on(type, handler) {
+        if (!this.subscriptions.has(type)) {
+            this.subscriptions.set(type, new Set());
+        }
+        const handlers = this.subscriptions.get(type);
+        handlers.add(handler);
+        return () => {
+            handlers.delete(handler);
+            if (handlers.size === 0) {
+                this.subscriptions.delete(type);
+            }
+        };
+    }
+    _emit(source, type, payload, opts) {
+        const event = {
+            id: randomUUID(),
+            traceId: getCurrentTraceId(),
+            correlationId: opts?.correlationId,
+            source,
+            type,
+            timestamp: new Date().toISOString(),
+            schemaVersion: getSpineSchemaVersion(type),
+            payload,
+            reply: (replyType, replyPayload) => {
+                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) => {
+                        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),
+                });
+            }
+        }
+    }
+    _request(source, type, payload, opts) {
+        // 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 = [];
+        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) => {
+                if (settled)
+                    return;
+                if (evt.correlationId === correlationId) {
+                    replies.push(evt);
+                    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 });
+        });
+    }
+}
+//# sourceMappingURL=event-bus.js.map

package/dist/events/event-bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.js","sourceRoot":"","sources":["../../src/events/event-bus.ts"],"names":[],"mappings":"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"}

package/dist/events/spine.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Reserved spine namespace prefixes.
+ * The dotted unprefixed namespace is reserved for the core spine.
+ */
+export declare const SPINE_NAMESPACES: readonly ["content.", "release.", "download.", "import.", "library.", "discovery.", "item."];
+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 declare const SPINE_EVENTS: Record<string, SpineEventMeta>;
+/**
+ * Check whether an event type falls within the reserved spine namespace.
+ */
+export declare function isSpineType(type: string): boolean;
+/**
+ * Return the schemaVersion for a spine type, or 1 as default for custom events.
+ */
+export declare function getSpineSchemaVersion(type: string): number;
+/**
+ * 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 declare function validateSpineEmission(source: string, type: string): string | null;
+//# sourceMappingURL=spine.d.ts.map

package/dist/events/spine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spine.d.ts","sourceRoot":"","sources":["../../src/events/spine.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,eAAO,MAAM,gBAAgB,8FAQnB,CAAC;AAEX,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,SAAS,GAAG,OAAO,GAAG,cAAc,CAAC;IAC3C,yCAAyC;IACzC,SAAS,EACL,MAAM,GACN,iBAAiB,GACjB,gBAAgB,GAChB,kBAAkB,GAClB,mBAAmB,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAiBvD,CAAC;AAEF;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAejF"}