@crewspaceai/server 2026.412.0-canary.0

package/dist/services/plugin-dev-watcher.js

@@ -0,0 +1,241 @@
+/**
+ * PluginDevWatcher — watches local-path plugin directories for file changes
+ * and triggers worker restarts so plugin authors get a fast rebuild-and-reload
+ * cycle without manually restarting the server.
+ *
+ * Only plugins installed from a local path (i.e. those with a non-null
+ * `packagePath` in the DB) are watched. File changes in the plugin's package
+ * directory trigger a debounced worker restart via the lifecycle manager.
+ *
+ * Uses chokidar rather than raw fs.watch so we get a production-grade watcher
+ * backend across platforms and avoid exhausting file descriptors as quickly in
+ * large dev workspaces.
+ *
+ * @see PLUGIN_SPEC.md §27.2 — Local Development Workflow
+ */
+import chokidar from "chokidar";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { logger } from "../middleware/logger.js";
+const log = logger.child({ service: "plugin-dev-watcher" });
+/** Debounce interval for file changes (ms). */
+const DEBOUNCE_MS = 500;
+function shouldIgnorePath(filename) {
+    if (!filename)
+        return false;
+    const normalized = filename.replace(/\\/g, "/");
+    const segments = normalized.split("/").filter(Boolean);
+    return segments.some((segment) => segment === "node_modules" ||
+        segment === ".git" ||
+        segment === ".vite" ||
+        segment === ".crewspace-sdk" ||
+        segment.startsWith("."));
+}
+export function resolvePluginWatchTargets(packagePath, fsDeps) {
+    const fileExists = fsDeps?.existsSync ?? existsSync;
+    const readFile = fsDeps?.readFileSync ?? readFileSync;
+    const readDir = fsDeps?.readdirSync ?? readdirSync;
+    const statFile = fsDeps?.statSync ?? statSync;
+    const absPath = path.resolve(packagePath);
+    const targets = new Map();
+    function addWatchTarget(targetPath, recursive, kind) {
+        const resolved = path.resolve(targetPath);
+        if (!fileExists(resolved))
+            return;
+        const inferredKind = kind ?? (statFile(resolved).isDirectory() ? "dir" : "file");
+        const existing = targets.get(resolved);
+        if (existing) {
+            existing.recursive = existing.recursive || recursive;
+            return;
+        }
+        targets.set(resolved, { path: resolved, recursive, kind: inferredKind });
+    }
+    function addRuntimeFilesFromDir(dirPath) {
+        if (!fileExists(dirPath))
+            return;
+        for (const entry of readDir(dirPath, { withFileTypes: true })) {
+            const entryPath = path.join(dirPath, entry.name);
+            if (entry.isDirectory()) {
+                addRuntimeFilesFromDir(entryPath);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            if (!entry.name.endsWith(".js") && !entry.name.endsWith(".css"))
+                continue;
+            addWatchTarget(entryPath, false, "file");
+        }
+    }
+    const packageJsonPath = path.join(absPath, "package.json");
+    addWatchTarget(packageJsonPath, false, "file");
+    if (!fileExists(packageJsonPath)) {
+        return [...targets.values()];
+    }
+    let packageJson = null;
+    try {
+        packageJson = JSON.parse(readFile(packageJsonPath, "utf8"));
+    }
+    catch {
+        packageJson = null;
+    }
+    const entrypointPaths = [
+        packageJson?.crewspacePlugin?.manifest,
+        packageJson?.crewspacePlugin?.worker,
+        packageJson?.crewspacePlugin?.ui,
+    ].filter((value) => typeof value === "string" && value.length > 0);
+    if (entrypointPaths.length === 0) {
+        addRuntimeFilesFromDir(path.join(absPath, "dist"));
+        return [...targets.values()];
+    }
+    for (const relativeEntrypoint of entrypointPaths) {
+        const resolvedEntrypoint = path.resolve(absPath, relativeEntrypoint);
+        if (!fileExists(resolvedEntrypoint))
+            continue;
+        const stat = statFile(resolvedEntrypoint);
+        if (stat.isDirectory()) {
+            addRuntimeFilesFromDir(resolvedEntrypoint);
+        }
+        else {
+            addWatchTarget(resolvedEntrypoint, false, "file");
+        }
+    }
+    return [...targets.values()].sort((a, b) => a.path.localeCompare(b.path));
+}
+/**
+ * Create a PluginDevWatcher that monitors local plugin directories and
+ * restarts workers on file changes.
+ */
+export function createPluginDevWatcher(lifecycle, resolvePluginPackagePath, fsDeps) {
+    const watchers = new Map();
+    const debounceTimers = new Map();
+    const fileExists = fsDeps?.existsSync ?? existsSync;
+    function watchPlugin(pluginId, packagePath) {
+        // Don't double-watch
+        if (watchers.has(pluginId))
+            return;
+        const absPath = path.resolve(packagePath);
+        if (!fileExists(absPath)) {
+            log.warn({ pluginId, packagePath: absPath }, "plugin-dev-watcher: package path does not exist, skipping watch");
+            return;
+        }
+        try {
+            const watcherTargets = resolvePluginWatchTargets(absPath, fsDeps);
+            if (watcherTargets.length === 0) {
+                log.warn({ pluginId, packagePath: absPath }, "plugin-dev-watcher: no valid watch targets found, skipping watch");
+                return;
+            }
+            const watcher = chokidar.watch(watcherTargets.map((target) => target.path), {
+                ignoreInitial: true,
+                awaitWriteFinish: {
+                    stabilityThreshold: 200,
+                    pollInterval: 100,
+                },
+                ignored: (watchedPath) => {
+                    const relativePath = path.relative(absPath, watchedPath);
+                    return shouldIgnorePath(relativePath);
+                },
+            });
+            watcher.on("all", (_eventName, changedPath) => {
+                const relativePath = path.relative(absPath, changedPath);
+                if (shouldIgnorePath(relativePath))
+                    return;
+                const existing = debounceTimers.get(pluginId);
+                if (existing)
+                    clearTimeout(existing);
+                debounceTimers.set(pluginId, setTimeout(() => {
+                    debounceTimers.delete(pluginId);
+                    log.info({ pluginId, changedFile: relativePath || path.basename(changedPath) }, "plugin-dev-watcher: file change detected, restarting worker");
+                    lifecycle.restartWorker(pluginId).catch((err) => {
+                        log.warn({
+                            pluginId,
+                            err: err instanceof Error ? err.message : String(err),
+                        }, "plugin-dev-watcher: failed to restart worker after file change");
+                    });
+                }, DEBOUNCE_MS));
+            });
+            watcher.on("error", (err) => {
+                log.warn({
+                    pluginId,
+                    packagePath: absPath,
+                    err: err instanceof Error ? err.message : String(err),
+                }, "plugin-dev-watcher: watcher error, stopping watch for this plugin");
+                unwatchPlugin(pluginId);
+            });
+            watchers.set(pluginId, watcher);
+            log.info({
+                pluginId,
+                packagePath: absPath,
+                watchTargets: watcherTargets.map((target) => ({
+                    path: target.path,
+                    kind: target.kind,
+                })),
+            }, "plugin-dev-watcher: watching local plugin for changes");
+        }
+        catch (err) {
+            log.warn({
+                pluginId,
+                packagePath: absPath,
+                err: err instanceof Error ? err.message : String(err),
+            }, "plugin-dev-watcher: failed to start file watcher");
+        }
+    }
+    function unwatchPlugin(pluginId) {
+        const pluginWatcher = watchers.get(pluginId);
+        if (pluginWatcher) {
+            void pluginWatcher.close();
+            watchers.delete(pluginId);
+        }
+        const timer = debounceTimers.get(pluginId);
+        if (timer) {
+            clearTimeout(timer);
+            debounceTimers.delete(pluginId);
+        }
+    }
+    function close() {
+        lifecycle.off("plugin.loaded", handlePluginLoaded);
+        lifecycle.off("plugin.enabled", handlePluginEnabled);
+        lifecycle.off("plugin.disabled", handlePluginDisabled);
+        lifecycle.off("plugin.unloaded", handlePluginUnloaded);
+        for (const [pluginId] of watchers) {
+            unwatchPlugin(pluginId);
+        }
+    }
+    async function watchLocalPluginById(pluginId) {
+        if (!resolvePluginPackagePath)
+            return;
+        try {
+            const packagePath = await resolvePluginPackagePath(pluginId);
+            if (!packagePath)
+                return;
+            watchPlugin(pluginId, packagePath);
+        }
+        catch (err) {
+            log.warn({
+                pluginId,
+                err: err instanceof Error ? err.message : String(err),
+            }, "plugin-dev-watcher: failed to resolve plugin package path");
+        }
+    }
+    function handlePluginLoaded(payload) {
+        void watchLocalPluginById(payload.pluginId);
+    }
+    function handlePluginEnabled(payload) {
+        void watchLocalPluginById(payload.pluginId);
+    }
+    function handlePluginDisabled(payload) {
+        unwatchPlugin(payload.pluginId);
+    }
+    function handlePluginUnloaded(payload) {
+        unwatchPlugin(payload.pluginId);
+    }
+    lifecycle.on("plugin.loaded", handlePluginLoaded);
+    lifecycle.on("plugin.enabled", handlePluginEnabled);
+    lifecycle.on("plugin.disabled", handlePluginDisabled);
+    lifecycle.on("plugin.unloaded", handlePluginUnloaded);
+    return {
+        watch: watchPlugin,
+        unwatch: unwatchPlugin,
+        close,
+    };
+}
+//# sourceMappingURL=plugin-dev-watcher.js.map

package/dist/services/plugin-dev-watcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-dev-watcher.js","sourceRoot":"","sources":["../../src/services/plugin-dev-watcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,QAA4B,MAAM,UAAU,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC1E,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAGjD,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,oBAAoB,EAAE,CAAC,CAAC;AAE5D,+CAA+C;AAC/C,MAAM,WAAW,GAAG,GAAG,CAAC;AAoCxB,SAAS,gBAAgB,CAAC,QAAmC;IAC3D,IAAI,CAAC,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5B,MAAM,UAAU,GAAG,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAChD,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACvD,OAAO,QAAQ,CAAC,IAAI,CAClB,CAAC,OAAO,EAAE,EAAE,CACV,OAAO,KAAK,cAAc;QAC1B,OAAO,KAAK,MAAM;QAClB,OAAO,KAAK,OAAO;QACnB,OAAO,KAAK,gBAAgB;QAC5B,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAC1B,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,yBAAyB,CACvC,WAAmB,EACnB,MAAiG;IAEjG,MAAM,UAAU,GAAG,MAAM,EAAE,UAAU,IAAI,UAAU,CAAC;IACpD,MAAM,QAAQ,GAAG,MAAM,EAAE,YAAY,IAAI,YAAY,CAAC;IACtD,MAAM,OAAO,GAAG,MAAM,EAAE,WAAW,IAAI,WAAW,CAAC;IACnD,MAAM,QAAQ,GAAG,MAAM,EAAE,QAAQ,IAAI,QAAQ,CAAC;IAC9C,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC1C,MAAM,OAAO,GAAG,IAAI,GAAG,EAA6B,CAAC;IAErD,SAAS,cAAc,CAAC,UAAkB,EAAE,SAAkB,EAAE,IAAqB;QACnF,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QAC1C,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;YAAE,OAAO;QAClC,MAAM,YAAY,GAAG,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QAEjF,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACvC,IAAI,QAAQ,EAAE,CAAC;YACb,QAAQ,CAAC,SAAS,GAAG,QAAQ,CAAC,SAAS,IAAI,SAAS,CAAC;YACrD,OAAO;QACT,CAAC;QAED,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,CAAC;IAC3E,CAAC;IAED,SAAS,sBAAsB,CAAC,OAAe;QAC7C,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;YAAE,OAAO;QAEjC,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,OAAO,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;YAC9D,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YACjD,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;gBACxB,sBAAsB,CAAC,SAAS,CAAC,CAAC;gBAClC,SAAS;YACX,CAAC;YAED,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE;gBAAE,SAAS;YAC9B,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;gBAAE,SAAS;YAC1E,cAAc,CAAC,SAAS,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;QAC3C,CAAC;IACH,CAAC;IAED,MAAM,eAAe,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;IAC3D,cAAc,CAAC,eAAe,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;IAC/C,IAAI,CAAC,UAAU,CAAC,eAAe,CAAC,EAAE,CAAC;QACjC,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC/B,CAAC;IAED,IAAI,WAAW,GAA6B,IAAI,CAAC;IACjD,IAAI,CAAC;QACH,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC,CAAsB,CAAC;IACnF,CAAC;IAAC,MAAM,CAAC;QACP,WAAW,GAAG,IAAI,CAAC;IACrB,CAAC;IAED,MAAM,eAAe,GAAG;QACtB,WAAW,EAAE,eAAe,EAAE,QAAQ;QACtC,WAAW,EAAE,eAAe,EAAE,MAAM;QACpC,WAAW,EAAE,eAAe,EAAE,EAAE;KACjC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAmB,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAEpF,IAAI,eAAe,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjC,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;QACnD,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC/B,CAAC;IAED,KAAK,MAAM,kBAAkB,IAAI,eAAe,EAAE,CAAC;QACjD,MAAM,kBAAkB,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,kBAAkB,CAAC,CAAC;QACrE,IAAI,CAAC,UAAU,CAAC,kBAAkB,CAAC;YAAE,SAAS;QAE9C,MAAM,IAAI,GAAG,QAAQ,CAAC,kBAAkB,CAAC,CAAC;QAC1C,IAAI,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;YACvB,sBAAsB,CAAC,kBAAkB,CAAC,CAAC;QAC7C,CAAC;aAAM,CAAC;YACN,cAAc,CAAC,kBAAkB,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;QACpD,CAAC;IACH,CAAC;IAED,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AAC5E,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CACpC,SAAiC,EACjC,wBAAmD,EACnD,MAA+B;IAE/B,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAqB,CAAC;IAC9C,MAAM,cAAc,GAAG,IAAI,GAAG,EAAyC,CAAC;IACxE,MAAM,UAAU,GAAG,MAAM,EAAE,UAAU,IAAI,UAAU,CAAC;IAEpD,SAAS,WAAW,CAAC,QAAgB,EAAE,WAAmB;QACxD,qBAAqB;QACrB,IAAI,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC;YAAE,OAAO;QAEnC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QAC1C,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YACzB,GAAG,CAAC,IAAI,CACN,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,EAClC,iEAAiE,CAClE,CAAC;YACF,OAAO;QACT,CAAC;QAED,IAAI,CAAC;YACH,MAAM,cAAc,GAAG,yBAAyB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YAClE,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAChC,GAAG,CAAC,IAAI,CACN,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,EAClC,kEAAkE,CACnE,CAAC;gBACF,OAAO;YACT,CAAC;YAED,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,CAC5B,cAAc,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,EAC3C;gBACE,aAAa,EAAE,IAAI;gBACnB,gBAAgB,EAAE;oBAChB,kBAAkB,EAAE,GAAG;oBACvB,YAAY,EAAE,GAAG;iBAClB;gBACD,OAAO,EAAE,CAAC,WAAW,EAAE,EAAE;oBACvB,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;oBACzD,OAAO,gBAAgB,CAAC,YAAY,CAAC,CAAC;gBACxC,CAAC;aACF,CACF,CAAC;YAEF,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,UAAU,EAAE,WAAW,EAAE,EAAE;gBAC5C,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;gBACzD,IAAI,gBAAgB,CAAC,YAAY,CAAC;oBAAE,OAAO;gBAE3C,MAAM,QAAQ,GAAG,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;gBAC9C,IAAI,QAAQ;oBAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;gBAErC,cAAc,CAAC,GAAG,CAChB,QAAQ,EACR,UAAU,CAAC,GAAG,EAAE;oBACd,cAAc,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;oBAChC,GAAG,CAAC,IAAI,CACN,EAAE,QAAQ,EAAE,WAAW,EAAE,YAAY,IAAI,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,EACrE,6DAA6D,CAC9D,CAAC;oBAEF,SAAS,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;wBAC9C,GAAG,CAAC,IAAI,CACN;4BACE,QAAQ;4BACR,GAAG,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;yBACtD,EACD,gEAAgE,CACjE,CAAC;oBACJ,CAAC,CAAC,CAAC;gBACL,CAAC,EAAE,WAAW,CAAC,CAChB,CAAC;YACJ,CAAC,CAAC,CAAC;YAEH,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;gBAC1B,GAAG,CAAC,IAAI,CACN;oBACE,QAAQ;oBACR,WAAW,EAAE,OAAO;oBACpB,GAAG,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;iBACtD,EACD,mEAAmE,CACpE,CAAC;gBACF,aAAa,CAAC,QAAQ,CAAC,CAAC;YAC1B,CAAC,CAAC,CAAC;YAEH,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YAChC,GAAG,CAAC,IAAI,CACN;gBACE,QAAQ;gBACR,WAAW,EAAE,OAAO;gBACpB,YAAY,EAAE,cAAc,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;oBAC5C,IAAI,EAAE,MAAM,CAAC,IAAI;oBACjB,IAAI,EAAE,MAAM,CAAC,IAAI;iBAClB,CAAC,CAAC;aACJ,EACD,uDAAuD,CACxD,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,GAAG,CAAC,IAAI,CACN;gBACE,QAAQ;gBACR,WAAW,EAAE,OAAO;gBACpB,GAAG,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;aACtD,EACD,kDAAkD,CACnD,CAAC;QACJ,CAAC;IACH,CAAC;IAED,SAAS,aAAa,CAAC,QAAgB;QACrC,MAAM,aAAa,GAAG,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC7C,IAAI,aAAa,EAAE,CAAC;YAClB,KAAK,aAAa,CAAC,KAAK,EAAE,CAAC;YAC3B,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC5B,CAAC;QACD,MAAM,KAAK,GAAG,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC3C,IAAI,KAAK,EAAE,CAAC;YACV,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,cAAc,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;IAED,SAAS,KAAK;QACZ,SAAS,CAAC,GAAG,CAAC,eAAe,EAAE,kBAAkB,CAAC,CAAC;QACnD,SAAS,CAAC,GAAG,CAAC,gBAAgB,EAAE,mBAAmB,CAAC,CAAC;QACrD,SAAS,CAAC,GAAG,CAAC,iBAAiB,EAAE,oBAAoB,CAAC,CAAC;QACvD,SAAS,CAAC,GAAG,CAAC,iBAAiB,EAAE,oBAAoB,CAAC,CAAC;QAEvD,KAAK,MAAM,CAAC,QAAQ,CAAC,IAAI,QAAQ,EAAE,CAAC;YAClC,aAAa,CAAC,QAAQ,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;IAED,KAAK,UAAU,oBAAoB,CAAC,QAAgB;QAClD,IAAI,CAAC,wBAAwB;YAAE,OAAO;QAEtC,IAAI,CAAC;YACH,MAAM,WAAW,GAAG,MAAM,wBAAwB,CAAC,QAAQ,CAAC,CAAC;YAC7D,IAAI,CAAC,WAAW;gBAAE,OAAO;YACzB,WAAW,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;QACrC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,GAAG,CAAC,IAAI,CACN;gBACE,QAAQ;gBACR,GAAG,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;aACtD,EACD,2DAA2D,CAC5D,CAAC;QACJ,CAAC;IACH,CAAC;IAED,SAAS,kBAAkB,CAAC,OAA6B;QACvD,KAAK,oBAAoB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC9C,CAAC;IAED,SAAS,mBAAmB,CAAC,OAA6B;QACxD,KAAK,oBAAoB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC9C,CAAC;IAED,SAAS,oBAAoB,CAAC,OAA6B;QACzD,aAAa,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAClC,CAAC;IAED,SAAS,oBAAoB,CAAC,OAA6B;QACzD,aAAa,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAClC,CAAC;IAED,SAAS,CAAC,EAAE,CAAC,eAAe,EAAE,kBAAkB,CAAC,CAAC;IAClD,SAAS,CAAC,EAAE,CAAC,gBAAgB,EAAE,mBAAmB,CAAC,CAAC;IACpD,SAAS,CAAC,EAAE,CAAC,iBAAiB,EAAE,oBAAoB,CAAC,CAAC;IACtD,SAAS,CAAC,EAAE,CAAC,iBAAiB,EAAE,oBAAoB,CAAC,CAAC;IAEtD,OAAO;QACL,KAAK,EAAE,WAAW;QAClB,OAAO,EAAE,aAAa;QACtB,KAAK;KACN,CAAC;AACJ,CAAC"}

package/dist/services/plugin-event-bus.d.ts

@@ -0,0 +1,149 @@
+/**
+ * PluginEventBus — typed in-process event bus for the CrewSpace plugin system.
+ *
+ * Responsibilities:
+ * - Deliver core domain events to subscribing plugin workers (server-side).
+ * - Apply `EventFilter` server-side so filtered-out events never reach the handler.
+ * - Namespace plugin-emitted events as `plugin.<pluginId>.<eventName>`.
+ * - Guard the core namespace: plugins may not emit events with the `plugin.` prefix.
+ * - Isolate subscriptions per plugin — a plugin cannot enumerate or interfere with
+ *   another plugin's subscriptions.
+ * - Support wildcard subscriptions via prefix matching (e.g. `plugin.acme.linear.*`).
+ *
+ * The bus operates in-process. In the full out-of-process architecture the host
+ * calls `bus.emit()` after receiving events from the DB/queue layer, and the bus
+ * forwards to handlers that proxy the call to the relevant worker process via IPC.
+ * That IPC layer is separate; this module only handles routing and filtering.
+ *
+ * @see PLUGIN_SPEC.md §16 — Event System
+ * @see PLUGIN_SPEC.md §16.1 — Event Filtering
+ * @see PLUGIN_SPEC.md §16.2 — Plugin-to-Plugin Events
+ */
+import type { PluginEventType } from "@crewspaceai/shared";
+import type { PluginEvent, EventFilter } from "@crewspaceai/plugin-sdk";
+/**
+ * Creates and returns a new `PluginEventBus` instance.
+ *
+ * A single bus instance should be shared across the server process. Each
+ * plugin interacts with the bus through a scoped handle obtained via
+ * {@link PluginEventBus.forPlugin}.
+ *
+ * @example
+ * ```ts
+ * const bus = createPluginEventBus();
+ *
+ * // Give the Linear plugin a scoped handle
+ * const linearBus = bus.forPlugin("acme.linear");
+ *
+ * // Subscribe from the plugin's perspective
+ * linearBus.subscribe("issue.created", async (event) => {
+ *   // handle event
+ * });
+ *
+ * // Emit a core domain event (called by the host, not the plugin)
+ * await bus.emit({
+ *   eventId: "evt-1",
+ *   eventType: "issue.created",
+ *   occurredAt: new Date().toISOString(),
+ *   entityId: "iss-1",
+ *   entityType: "issue",
+ *   payload: { title: "Fix login bug", projectId: "proj-1" },
+ * });
+ * ```
+ */
+export declare function createPluginEventBus(): PluginEventBus;
+/**
+ * Result returned from `emit()`. Handler errors are collected and returned
+ * rather than thrown so a single misbehaving plugin cannot block delivery to
+ * other plugins.
+ */
+export interface PluginEventBusEmitResult {
+    /** Errors thrown by individual handlers, keyed by the plugin that failed. */
+    errors: Array<{
+        pluginId: string;
+        error: unknown;
+    }>;
+}
+/**
+ * The full event bus — held by the host process.
+ *
+ * Call `forPlugin(id)` to obtain a `ScopedPluginEventBus` for each plugin worker.
+ */
+export interface PluginEventBus {
+    /**
+     * Emit a typed domain event to all matching subscribers.
+     *
+     * Called by the host when a domain event occurs (e.g. from the DB layer or
+     * message queue). All registered subscriptions across all plugins are checked.
+     */
+    emit(event: PluginEvent): Promise<PluginEventBusEmitResult>;
+    /**
+     * Get a scoped handle for a specific plugin worker.
+     *
+     * The scoped handle isolates the plugin's subscriptions and enforces the
+     * plugin namespace on outbound events.
+     */
+    forPlugin(pluginId: string): ScopedPluginEventBus;
+    /**
+     * Remove all subscriptions for a plugin (called on worker shutdown/uninstall).
+     */
+    clearPlugin(pluginId: string): void;
+    /**
+     * Return the total number of active subscriptions, or the count for a
+     * specific plugin if `pluginId` is provided.
+     */
+    subscriptionCount(pluginId?: string): number;
+}
+/**
+ * A plugin-scoped view of the event bus. Handed to the plugin worker (or its
+ * host-side proxy) during initialisation.
+ *
+ * Plugins use this to:
+ * 1. Subscribe to domain events (with optional server-side filter).
+ * 2. Emit plugin-namespaced events for other plugins to consume.
+ *
+ * Note: `subscribe` overloads mirror the `PluginEventsClient.on()` interface
+ * from the SDK. `emit` intentionally returns `PluginEventBusEmitResult` rather
+ * than `void` so the host layer can inspect handler errors; the SDK-facing
+ * `PluginEventsClient.emit()` wraps this and returns `void`.
+ */
+export interface ScopedPluginEventBus {
+    /**
+     * Subscribe to a core domain event or a plugin-namespaced event.
+     *
+     * **Pattern syntax:**
+     * - Exact match: `"issue.created"` — receives only that event type.
+     * - Wildcard suffix: `"plugin.acme.linear.*"` — receives all events emitted by
+     *   the `acme.linear` plugin. The `*` is supported only as a trailing token after
+     *   a `.` separator; no other glob syntax is supported.
+     * - Top-level plugin wildcard: `"plugin.*"` — receives all plugin-emitted events
+     *   regardless of which plugin emitted them.
+     *
+     * Wildcards apply only to the `plugin.*` namespace. Core domain events must be
+     * subscribed to by exact name (e.g. `"issue.created"`, not `"issue.*"`).
+     *
+     * An optional `EventFilter` can be passed as the second argument to perform
+     * server-side pre-filtering; filtered-out events are never delivered to the handler.
+     */
+    subscribe(eventPattern: PluginEventType | `plugin.${string}`, fn: (event: PluginEvent) => Promise<void>): void;
+    subscribe(eventPattern: PluginEventType | `plugin.${string}`, filter: EventFilter, fn: (event: PluginEvent) => Promise<void>): void;
+    /**
+     * Emit a plugin-namespaced event. The bus automatically prepends
+     * `plugin.<pluginId>.` to the `name`, so passing `"sync-done"` from plugin
+     * `"acme.linear"` produces the event type `"plugin.acme.linear.sync-done"`.
+     *
+     * @param name  Bare event name (e.g. `"sync-done"`). Must be non-empty and
+     *   must not include the `plugin.` prefix — the bus adds that automatically.
+     * @param companyId  UUID of the company this event belongs to.
+     * @param payload  Arbitrary JSON-serializable data to attach to the event.
+     *
+     * @throws {Error} if `name` is empty or whitespace-only.
+     * @throws {Error} if `name` starts with `"plugin."` (namespace spoofing guard).
+     */
+    emit(name: string, companyId: string, payload: unknown): Promise<PluginEventBusEmitResult>;
+    /**
+     * Remove all subscriptions registered by this plugin.
+     */
+    clear(): void;
+}
+//# sourceMappingURL=plugin-event-bus.d.ts.map

package/dist/services/plugin-event-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-event-bus.d.ts","sourceRoot":"","sources":["../../src/services/plugin-event-bus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AA+FxE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,oBAAoB,IAAI,cAAc,CAyJrD;AAMD;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,6EAA6E;IAC7E,MAAM,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACrD;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,IAAI,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAAC;IAE5D;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,oBAAoB,CAAC;IAElD;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAEpC;;;OAGG;IACH,iBAAiB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC9C;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;;;;;;;;;OAgBG;IACH,SAAS,CACP,YAAY,EAAE,eAAe,GAAG,UAAU,MAAM,EAAE,EAClD,EAAE,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,GACxC,IAAI,CAAC;IACR,SAAS,CACP,YAAY,EAAE,eAAe,GAAG,UAAU,MAAM,EAAE,EAClD,MAAM,EAAE,WAAW,EACnB,EAAE,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,GACxC,IAAI,CAAC;IAER;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAAC;IAE3F;;OAEG;IACH,KAAK,IAAI,IAAI,CAAC;CACf"}

package/dist/services/plugin-event-bus.js

@@ -0,0 +1,258 @@
+/**
+ * PluginEventBus — typed in-process event bus for the CrewSpace plugin system.
+ *
+ * Responsibilities:
+ * - Deliver core domain events to subscribing plugin workers (server-side).
+ * - Apply `EventFilter` server-side so filtered-out events never reach the handler.
+ * - Namespace plugin-emitted events as `plugin.<pluginId>.<eventName>`.
+ * - Guard the core namespace: plugins may not emit events with the `plugin.` prefix.
+ * - Isolate subscriptions per plugin — a plugin cannot enumerate or interfere with
+ *   another plugin's subscriptions.
+ * - Support wildcard subscriptions via prefix matching (e.g. `plugin.acme.linear.*`).
+ *
+ * The bus operates in-process. In the full out-of-process architecture the host
+ * calls `bus.emit()` after receiving events from the DB/queue layer, and the bus
+ * forwards to handlers that proxy the call to the relevant worker process via IPC.
+ * That IPC layer is separate; this module only handles routing and filtering.
+ *
+ * @see PLUGIN_SPEC.md §16 — Event System
+ * @see PLUGIN_SPEC.md §16.1 — Event Filtering
+ * @see PLUGIN_SPEC.md §16.2 — Plugin-to-Plugin Events
+ */
+// ---------------------------------------------------------------------------
+// Pattern matching helpers
+// ---------------------------------------------------------------------------
+/**
+ * Returns true if the event type matches the subscription pattern.
+ *
+ * Matching rules:
+ * - Exact match: `"issue.created"` matches `"issue.created"`.
+ * - Wildcard suffix: `"plugin.acme.*"` matches any event type that starts with
+ *   `"plugin.acme."`. The wildcard `*` is only supported as a trailing token.
+ *
+ * No full glob syntax is supported — only trailing `*` after a `.` separator.
+ */
+function matchesPattern(eventType, pattern) {
+    if (pattern === eventType)
+        return true;
+    // Trailing wildcard: "plugin.foo.*" → prefix is "plugin.foo."
+    if (pattern.endsWith(".*")) {
+        const prefix = pattern.slice(0, -1); // remove the trailing "*", keep the "."
+        return eventType.startsWith(prefix);
+    }
+    return false;
+}
+/**
+ * Returns true if the event passes all fields of the filter.
+ * A `null` or empty filter object passes all events.
+ *
+ * **Resolution strategy per field:**
+ *
+ * - `projectId` — checked against `event.entityId` when `entityType === "project"`,
+ *   otherwise against `payload.projectId`. This covers both direct project events
+ *   (e.g. `project.created`) and secondary events that embed a project reference in
+ *   their payload (e.g. `issue.created` with `payload.projectId`).
+ *
+ * - `companyId` — always resolved from `payload.companyId`. Core domain events that
+ *   belong to a company embed the company ID in their payload.
+ *
+ * - `agentId` — checked against `event.entityId` when `entityType === "agent"`,
+ *   otherwise against `payload.agentId`. Covers both direct agent lifecycle events
+ *   (e.g. `agent.created`) and run-level events with `payload.agentId` (e.g.
+ *   `agent.run.started`).
+ *
+ * Multiple filter fields are ANDed — all specified fields must match.
+ */
+function passesFilter(event, filter) {
+    if (!filter)
+        return true;
+    const payload = event.payload;
+    if (filter.projectId !== undefined) {
+        const projectId = event.entityType === "project"
+            ? event.entityId
+            : (typeof payload?.projectId === "string" ? payload.projectId : undefined);
+        if (projectId !== filter.projectId)
+            return false;
+    }
+    if (filter.companyId !== undefined) {
+        if (event.companyId !== filter.companyId)
+            return false;
+    }
+    if (filter.agentId !== undefined) {
+        const agentId = event.entityType === "agent"
+            ? event.entityId
+            : (typeof payload?.agentId === "string" ? payload.agentId : undefined);
+        if (agentId !== filter.agentId)
+            return false;
+    }
+    return true;
+}
+// ---------------------------------------------------------------------------
+// Event bus factory
+// ---------------------------------------------------------------------------
+/**
+ * Creates and returns a new `PluginEventBus` instance.
+ *
+ * A single bus instance should be shared across the server process. Each
+ * plugin interacts with the bus through a scoped handle obtained via
+ * {@link PluginEventBus.forPlugin}.
+ *
+ * @example
+ * ```ts
+ * const bus = createPluginEventBus();
+ *
+ * // Give the Linear plugin a scoped handle
+ * const linearBus = bus.forPlugin("acme.linear");
+ *
+ * // Subscribe from the plugin's perspective
+ * linearBus.subscribe("issue.created", async (event) => {
+ *   // handle event
+ * });
+ *
+ * // Emit a core domain event (called by the host, not the plugin)
+ * await bus.emit({
+ *   eventId: "evt-1",
+ *   eventType: "issue.created",
+ *   occurredAt: new Date().toISOString(),
+ *   entityId: "iss-1",
+ *   entityType: "issue",
+ *   payload: { title: "Fix login bug", projectId: "proj-1" },
+ * });
+ * ```
+ */
+export function createPluginEventBus() {
+    // Subscription registry: pluginKey → list of subscriptions
+    const registry = new Map();
+    /**
+     * Retrieve or create the subscription list for a plugin.
+     */
+    function subsFor(pluginId) {
+        let subs = registry.get(pluginId);
+        if (!subs) {
+            subs = [];
+            registry.set(pluginId, subs);
+        }
+        return subs;
+    }
+    /**
+     * Emit an event envelope to all matching subscribers across all plugins.
+     *
+     * Subscribers are called concurrently (Promise.all). Each handler's errors
+     * are caught individually and collected in the returned `errors` array so a
+     * single misbehaving plugin cannot interrupt delivery to other plugins.
+     */
+    async function emit(event) {
+        const errors = [];
+        const promises = [];
+        for (const [pluginId, subs] of registry) {
+            for (const sub of subs) {
+                if (!matchesPattern(event.eventType, sub.eventPattern))
+                    continue;
+                if (!passesFilter(event, sub.filter))
+                    continue;
+                // Use Promise.resolve().then() so that synchronous throws from handlers
+                // are also caught inside the promise chain. Calling
+                // Promise.resolve(syncThrowingFn()) does NOT catch sync throws — the
+                // throw escapes before Promise.resolve() can wrap it. Using .then()
+                // ensures the call is deferred into the microtask queue where all
+                // exceptions become rejections. Each .catch() swallows the rejection
+                // and records it — the promise always resolves, so Promise.all never rejects.
+                promises.push(Promise.resolve().then(() => sub.handler(event)).catch((error) => {
+                    errors.push({ pluginId, error });
+                }));
+            }
+        }
+        await Promise.all(promises);
+        return { errors };
+    }
+    /**
+     * Remove all subscriptions for a plugin (e.g. on worker shutdown or uninstall).
+     */
+    function clearPlugin(pluginId) {
+        registry.delete(pluginId);
+    }
+    /**
+     * Return a scoped handle for a specific plugin. The handle exposes only the
+     * plugin's own subscription list and enforces the plugin namespace on `emit`.
+     */
+    function forPlugin(pluginId) {
+        return {
+            /**
+             * Subscribe to a core domain event or a plugin-namespaced event.
+             *
+             * For wildcard subscriptions use a trailing `.*` pattern, e.g.
+             * `"plugin.acme.linear.*"`.
+             *
+             * Requires the `events.subscribe` capability (capability enforcement is
+             * done by the host layer before calling this method).
+             */
+            subscribe(eventPattern, fnOrFilter, maybeFn) {
+                let filter = null;
+                let handler;
+                if (typeof fnOrFilter === "function") {
+                    handler = fnOrFilter;
+                }
+                else {
+                    filter = fnOrFilter;
+                    if (!maybeFn)
+                        throw new Error("Handler function is required when a filter is provided");
+                    handler = maybeFn;
+                }
+                subsFor(pluginId).push({ eventPattern, filter, handler });
+            },
+            /**
+             * Emit a plugin-namespaced event. The event type is automatically
+             * prefixed with `plugin.<pluginId>.` so:
+             * - `emit("sync-done", payload)` becomes `"plugin.acme.linear.sync-done"`.
+             *
+             * Requires the `events.emit` capability (enforced by the host layer).
+             *
+             * @throws {Error} if `name` already contains the `plugin.` prefix
+             *   (prevents cross-namespace spoofing).
+             */
+            async emit(name, companyId, payload) {
+                if (!name || name.trim() === "") {
+                    throw new Error(`Plugin "${pluginId}" must provide a non-empty event name.`);
+                }
+                if (!companyId || companyId.trim() === "") {
+                    throw new Error(`Plugin "${pluginId}" must provide a companyId when emitting events.`);
+                }
+                if (name.startsWith("plugin.")) {
+                    throw new Error(`Plugin "${pluginId}" must not include the "plugin." prefix when emitting events. ` +
+                        `Emit the bare event name (e.g. "sync-done") and the bus will namespace it automatically.`);
+                }
+                const eventType = `plugin.${pluginId}.${name}`;
+                const event = {
+                    eventId: crypto.randomUUID(),
+                    eventType,
+                    companyId,
+                    occurredAt: new Date().toISOString(),
+                    actorType: "plugin",
+                    actorId: pluginId,
+                    payload,
+                };
+                return emit(event);
+            },
+            /** Remove all subscriptions registered by this plugin. */
+            clear() {
+                clearPlugin(pluginId);
+            },
+        };
+    }
+    return {
+        emit,
+        forPlugin,
+        clearPlugin,
+        /** Expose subscription count for a plugin (useful for tests and diagnostics). */
+        subscriptionCount(pluginId) {
+            if (pluginId !== undefined) {
+                return registry.get(pluginId)?.length ?? 0;
+            }
+            let total = 0;
+            for (const subs of registry.values())
+                total += subs.length;
+            return total;
+        },
+    };
+}
+//# sourceMappingURL=plugin-event-bus.js.map