@growthub/cli 0.3.11 → 0.3.13

package/dist/runtime/server/dist/services/plugin-loader.js

@@ -1,1192 +0,0 @@
-/**
- * PluginLoader — discovery, installation, and runtime activation of plugins.
- *
- * This service is the entry point for the plugin system's I/O boundary:
- *
- * 1. **Discovery** — Scans the local plugin directory
- *    (`~/.paperclip/plugins/`) and `node_modules` for packages matching
- *    the `paperclip-plugin-*` naming convention. Aggregates results with
- *    path-based deduplication.
- *
- * 2. **Installation** — `installPlugin()` downloads from npm (or reads a
- *    local path), validates the manifest, checks capability consistency,
- *    and persists the install record.
- *
- * 3. **Runtime activation** — `activatePlugin()` wires up a loaded plugin
- *    with all runtime services: resolves its entrypoint, builds
- *    capability-gated host handlers, spawns a worker process, syncs job
- *    declarations, registers event subscriptions, and discovers tools.
- *
- * 4. **Shutdown** — `shutdownAll()` gracefully stops all active workers
- *    and unregisters runtime hooks.
- *
- * @see PLUGIN_SPEC.md §8 — Plugin Discovery
- * @see PLUGIN_SPEC.md §10 — Package Contract
- * @see PLUGIN_SPEC.md §12 — Process Model
- */
-import { existsSync } from "node:fs";
-import { readdir, readFile, rm, stat } from "node:fs/promises";
-import { execFile } from "node:child_process";
-import os from "node:os";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { promisify } from "node:util";
-import { logger } from "../middleware/logger.js";
-import { pluginManifestValidator } from "./plugin-manifest-validator.js";
-import { pluginCapabilityValidator } from "./plugin-capability-validator.js";
-import { pluginRegistryService } from "./plugin-registry.js";
-const execFileAsync = promisify(execFile);
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-/**
- * Naming convention for npm-published Paperclip plugins.
- * Packages matching this pattern are considered Paperclip plugins.
- *
- * @see PLUGIN_SPEC.md §10 — Package Contract
- */
-export const NPM_PLUGIN_PACKAGE_PREFIX = "paperclip-plugin-";
-/**
- * Default local plugin directory.  The loader scans this directory for
- * locally-installed plugin packages.
- *
- * @see PLUGIN_SPEC.md §8.1 — On-Disk Layout
- */
-export const DEFAULT_LOCAL_PLUGIN_DIR = path.join(os.homedir(), ".paperclip", "plugins");
-const DEV_TSX_LOADER_PATH = path.resolve(__dirname, "../../../cli/node_modules/tsx/dist/loader.mjs");
-function getDeclaredPageRoutePaths(manifest) {
-    return (manifest.ui?.slots ?? [])
-        .filter((slot) => slot.type === "page" && typeof slot.routePath === "string" && slot.routePath.length > 0)
-        .map((slot) => slot.routePath);
-}
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-/**
- * Check whether a package name matches the Paperclip plugin naming convention.
- * Accepts both the "paperclip-plugin-" prefix and scoped "@scope/plugin-" packages.
- *
- * @see PLUGIN_SPEC.md §10 — Package Contract
- */
-export function isPluginPackageName(name) {
-    if (name.startsWith(NPM_PLUGIN_PACKAGE_PREFIX))
-        return true;
-    // Also accept scoped packages like @acme/plugin-linear or @paperclipai/plugin-*
-    if (name.includes("/")) {
-        const localPart = name.split("/")[1] ?? "";
-        return localPart.startsWith("plugin-");
-    }
-    return false;
-}
-/**
- * Read and parse a package.json from a directory path.
- * Returns null if no package.json exists.
- */
-async function readPackageJson(dir) {
-    const pkgPath = path.join(dir, "package.json");
-    if (!existsSync(pkgPath))
-        return null;
-    try {
-        const raw = await readFile(pkgPath, "utf-8");
-        return JSON.parse(raw);
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Resolve the manifest entrypoint from a package.json and package root.
- *
- * The spec defines a "paperclipPlugin" key in package.json with a "manifest"
- * subkey pointing to the manifest module.  This helper resolves the path.
- *
- * @see PLUGIN_SPEC.md §10 — Package Contract
- */
-function resolveManifestPath(packageRoot, pkgJson) {
-    const paperclipPlugin = pkgJson["paperclipPlugin"];
-    if (paperclipPlugin !== null &&
-        typeof paperclipPlugin === "object" &&
-        !Array.isArray(paperclipPlugin)) {
-        const manifestRelPath = paperclipPlugin["manifest"];
-        if (typeof manifestRelPath === "string") {
-            // NOTE: the resolved path is returned as-is even if the file does not yet
-            // exist on disk (e.g. the package has not been built).  Callers MUST guard
-            // with existsSync() before passing the path to loadManifestFromPath().
-            return path.resolve(packageRoot, manifestRelPath);
-        }
-    }
-    // Fallback: look for dist/manifest.js as a convention
-    const conventionalPath = path.join(packageRoot, "dist", "manifest.js");
-    if (existsSync(conventionalPath)) {
-        return conventionalPath;
-    }
-    // Fallback: look for manifest.js at package root
-    const rootManifestPath = path.join(packageRoot, "manifest.js");
-    if (existsSync(rootManifestPath)) {
-        return rootManifestPath;
-    }
-    return null;
-}
-function parseSemver(version) {
-    const match = version.match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/);
-    if (!match)
-        return null;
-    return {
-        major: Number(match[1]),
-        minor: Number(match[2]),
-        patch: Number(match[3]),
-        prerelease: match[4] ? match[4].split(".") : [],
-    };
-}
-function compareIdentifiers(left, right) {
-    const leftIsNumeric = /^\d+$/.test(left);
-    const rightIsNumeric = /^\d+$/.test(right);
-    if (leftIsNumeric && rightIsNumeric) {
-        return Number(left) - Number(right);
-    }
-    if (leftIsNumeric)
-        return -1;
-    if (rightIsNumeric)
-        return 1;
-    return left.localeCompare(right);
-}
-function compareSemver(left, right) {
-    const leftParsed = parseSemver(left);
-    const rightParsed = parseSemver(right);
-    if (!leftParsed || !rightParsed) {
-        throw new Error(`Invalid semver comparison: '${left}' vs '${right}'`);
-    }
-    const coreOrder = ["major", "minor", "patch"].map((key) => leftParsed[key] - rightParsed[key]).find((delta) => delta !== 0);
-    if (coreOrder) {
-        return coreOrder;
-    }
-    if (leftParsed.prerelease.length === 0 && rightParsed.prerelease.length === 0) {
-        return 0;
-    }
-    if (leftParsed.prerelease.length === 0)
-        return 1;
-    if (rightParsed.prerelease.length === 0)
-        return -1;
-    const maxLength = Math.max(leftParsed.prerelease.length, rightParsed.prerelease.length);
-    for (let index = 0; index < maxLength; index += 1) {
-        const leftId = leftParsed.prerelease[index];
-        const rightId = rightParsed.prerelease[index];
-        if (leftId === undefined)
-            return -1;
-        if (rightId === undefined)
-            return 1;
-        const diff = compareIdentifiers(leftId, rightId);
-        if (diff !== 0)
-            return diff;
-    }
-    return 0;
-}
-function getMinimumHostVersion(manifest) {
-    return manifest.minimumHostVersion ?? manifest.minimumPaperclipVersion;
-}
-/**
- * Extract UI contribution metadata from a manifest for route serialization.
- *
- * Returns `null` when the plugin does not declare any UI slots or launchers.
- * Launcher declarations are aggregated from both the legacy top-level
- * `launchers` field and the preferred `ui.launchers` field.
- */
-export function getPluginUiContributionMetadata(manifest) {
-    const slots = manifest.ui?.slots ?? [];
-    const launchers = [
-        ...(manifest.launchers ?? []),
-        ...(manifest.ui?.launchers ?? []),
-    ];
-    if (slots.length === 0 && launchers.length === 0) {
-        return null;
-    }
-    return {
-        uiEntryFile: "index.js",
-        slots,
-        launchers,
-    };
-}
-// ---------------------------------------------------------------------------
-// Factory
-// ---------------------------------------------------------------------------
-/**
- * Create a PluginLoader service.
- *
- * The loader is responsible for plugin discovery, installation, and runtime
- * activation.  It reads plugin packages from the local filesystem and npm,
- * validates their manifests, registers them in the database, and — when
- * runtime services are provided — initialises worker processes, event
- * subscriptions, job schedules, webhook endpoints, and agent tools.
- *
- * Usage (discovery & install only):
- * ```ts
- * const loader = pluginLoader(db, { enableLocalFilesystem: true });
- *
- * // Discover all available plugins
- * const result = await loader.discoverAll();
- * for (const plugin of result.discovered) {
- *   console.log(plugin.packageName, plugin.manifest?.id);
- * }
- *
- * // Install a specific plugin
- * const discovered = await loader.installPlugin({
- *   packageName: "paperclip-plugin-linear",
- *   version: "^1.0.0",
- * });
- * ```
- *
- * Usage (full runtime activation at server startup):
- * ```ts
- * const loader = pluginLoader(db, loaderOpts, {
- *   workerManager,
- *   eventBus,
- *   jobScheduler,
- *   jobStore,
- *   toolDispatcher,
- *   lifecycleManager,
- *   buildHostHandlers: (pluginId, manifest) => ({ ... }),
- *   instanceInfo: { instanceId: "inst-1", hostVersion: "1.0.0" },
- * });
- *
- * // Load all ready plugins at startup
- * const loadResult = await loader.loadAll();
- * console.log(`Loaded ${loadResult.succeeded}/${loadResult.total} plugins`);
- *
- * // Load a single plugin after install
- * const singleResult = await loader.loadSingle(pluginId);
- *
- * // Shutdown all plugin workers on server exit
- * await loader.shutdownAll();
- * ```
- *
- * @see PLUGIN_SPEC.md §8.1 — On-Disk Layout
- * @see PLUGIN_SPEC.md §8.3 — Install Process
- * @see PLUGIN_SPEC.md §12 — Process Model
- */
-export function pluginLoader(db, options = {}, runtimeServices) {
-    const { localPluginDir = DEFAULT_LOCAL_PLUGIN_DIR, enableLocalFilesystem = true, enableNpmDiscovery = true, } = options;
-    const registry = pluginRegistryService(db);
-    const manifestValidator = pluginManifestValidator();
-    const capabilityValidator = pluginCapabilityValidator();
-    const log = logger.child({ service: "plugin-loader" });
-    const hostVersion = runtimeServices?.instanceInfo.hostVersion;
-    async function assertPageRoutePathsAvailable(manifest) {
-        const requestedRoutePaths = getDeclaredPageRoutePaths(manifest);
-        if (requestedRoutePaths.length === 0)
-            return;
-        const uniqueRequested = new Set(requestedRoutePaths);
-        if (uniqueRequested.size !== requestedRoutePaths.length) {
-            throw new Error(`Plugin ${manifest.id} declares duplicate page routePath values`);
-        }
-        const installedPlugins = await registry.listInstalled();
-        for (const plugin of installedPlugins) {
-            if (plugin.pluginKey === manifest.id)
-                continue;
-            const installedManifest = plugin.manifestJson;
-            if (!installedManifest)
-                continue;
-            const installedRoutePaths = new Set(getDeclaredPageRoutePaths(installedManifest));
-            const conflictingRoute = requestedRoutePaths.find((routePath) => installedRoutePaths.has(routePath));
-            if (conflictingRoute) {
-                throw new Error(`Plugin ${manifest.id} routePath "${conflictingRoute}" conflicts with installed plugin ${plugin.pluginKey}`);
-            }
-        }
-    }
-    // -------------------------------------------------------------------------
-    // Internal helpers
-    // -------------------------------------------------------------------------
-    /**
-     * Fetch a plugin from npm or local path, then parse and validate its manifest.
-     *
-     * This internal helper encapsulates the core plugin retrieval and validation
-     * logic used by both install and upgrade operations. It handles:
-     * 1. Resolving the package from npm or local filesystem.
-     * 2. Installing the package via npm if necessary.
-     * 3. Reading and parsing the plugin manifest.
-     * 4. Validating API version compatibility.
-     * 5. Validating manifest capabilities.
-     *
-     * @param installOptions - Options specifying the package to fetch.
-     * @returns A `DiscoveredPlugin` object containing the validated manifest.
-     */
-    async function fetchAndValidate(installOptions) {
-        const { packageName, localPath, version, installDir } = installOptions;
-        if (!packageName && !localPath) {
-            throw new Error("Either packageName or localPath must be provided");
-        }
-        const targetInstallDir = installDir ?? localPluginDir;
-        // Step 1 & 2: Resolve and install package
-        let resolvedPackagePath;
-        let resolvedPackageName;
-        if (localPath) {
-            // Local path install — validate the directory exists
-            const absLocalPath = path.resolve(localPath);
-            if (!existsSync(absLocalPath)) {
-                throw new Error(`Local plugin path does not exist: ${absLocalPath}`);
-            }
-            resolvedPackagePath = absLocalPath;
-            const pkgJson = await readPackageJson(absLocalPath);
-            resolvedPackageName =
-                typeof pkgJson?.["name"] === "string"
-                    ? pkgJson["name"]
-                    : path.basename(absLocalPath);
-            log.info({ localPath: absLocalPath, packageName: resolvedPackageName }, "plugin-loader: fetching plugin from local path");
-        }
-        else {
-            // npm install
-            const spec = version ? `${packageName}@${version}` : packageName;
-            log.info({ spec, installDir: targetInstallDir }, "plugin-loader: fetching plugin from npm");
-            try {
-                // Use execFile (not exec) to avoid shell injection from package name/version.
-                // --ignore-scripts prevents preinstall/install/postinstall hooks from
-                // executing arbitrary code on the host before manifest validation.
-                await execFileAsync("npm", ["install", spec, "--prefix", targetInstallDir, "--save", "--ignore-scripts"], { timeout: 120_000 });
-            }
-            catch (err) {
-                throw new Error(`npm install failed for ${spec}: ${String(err)}`);
-            }
-            // Resolve the package path after installation
-            const nodeModulesPath = path.join(targetInstallDir, "node_modules");
-            resolvedPackageName = packageName;
-            // Handle scoped packages
-            if (resolvedPackageName.startsWith("@")) {
-                const [scope, name] = resolvedPackageName.split("/");
-                resolvedPackagePath = path.join(nodeModulesPath, scope, name);
-            }
-            else {
-                resolvedPackagePath = path.join(nodeModulesPath, resolvedPackageName);
-            }
-            if (!existsSync(resolvedPackagePath)) {
-                throw new Error(`Package directory not found after installation: ${resolvedPackagePath}`);
-            }
-        }
-        // Step 3: Read and validate plugin manifest
-        // Note: this.loadManifest (used via current context)
-        const pkgJson = await readPackageJson(resolvedPackagePath);
-        if (!pkgJson)
-            throw new Error(`Missing package.json at ${resolvedPackagePath}`);
-        const manifestPath = resolveManifestPath(resolvedPackagePath, pkgJson);
-        if (!manifestPath || !existsSync(manifestPath)) {
-            throw new Error(`Package ${resolvedPackageName} at ${resolvedPackagePath} does not appear to be a Paperclip plugin (no manifest found).`);
-        }
-        const manifest = await loadManifestFromPath(manifestPath);
-        // Step 4: Reject incompatible plugin API versions
-        if (!manifestValidator.getSupportedVersions().includes(manifest.apiVersion)) {
-            throw new Error(`Plugin ${manifest.id} declares apiVersion ${manifest.apiVersion} which is not supported by this host. ` +
-                `Supported versions: ${manifestValidator.getSupportedVersions().join(", ")}`);
-        }
-        // Step 5: Validate manifest capabilities are consistent
-        const capResult = capabilityValidator.validateManifestCapabilities(manifest);
-        if (!capResult.allowed) {
-            throw new Error(`Plugin ${manifest.id} manifest has inconsistent capabilities. ` +
-                `Missing required capabilities for declared features: ${capResult.missing.join(", ")}`);
-        }
-        await assertPageRoutePathsAvailable(manifest);
-        // Step 6: Reject plugins that require a newer host than the running server
-        const minimumHostVersion = getMinimumHostVersion(manifest);
-        if (minimumHostVersion && hostVersion) {
-            if (compareSemver(hostVersion, minimumHostVersion) < 0) {
-                throw new Error(`Plugin ${manifest.id} requires host version ${minimumHostVersion} or newer, ` +
-                    `but this server is running ${hostVersion}`);
-            }
-        }
-        // Use the version declared in the manifest (required field per the spec)
-        const resolvedVersion = manifest.version;
-        return {
-            packagePath: resolvedPackagePath,
-            packageName: resolvedPackageName,
-            version: resolvedVersion,
-            source: localPath ? "local-filesystem" : "npm",
-            manifest,
-        };
-    }
-    /**
-     * Attempt to load and validate a plugin manifest from a resolved path.
-     * Returns the manifest on success or throws with a descriptive error.
-     */
-    async function loadManifestFromPath(manifestPath) {
-        let raw;
-        try {
-            // Dynamic import works for both .js (ESM) and .cjs (CJS) manifests
-            const mod = await import(manifestPath);
-            // The manifest may be the default export or the module itself
-            raw = mod["default"] ?? mod;
-        }
-        catch (err) {
-            throw new Error(`Failed to load manifest module at ${manifestPath}: ${String(err)}`);
-        }
-        return manifestValidator.parseOrThrow(raw);
-    }
-    /**
-     * Build a DiscoveredPlugin from a resolved package directory, or null
-     * if the package is not a Paperclip plugin.
-     */
-    async function buildDiscoveredPlugin(packagePath, source) {
-        const pkgJson = await readPackageJson(packagePath);
-        if (!pkgJson)
-            return null;
-        const packageName = typeof pkgJson["name"] === "string" ? pkgJson["name"] : "";
-        const version = typeof pkgJson["version"] === "string" ? pkgJson["version"] : "0.0.0";
-        // Determine if this is a plugin package at all
-        const hasPaperclipPlugin = "paperclipPlugin" in pkgJson;
-        const nameMatchesConvention = isPluginPackageName(packageName);
-        if (!hasPaperclipPlugin && !nameMatchesConvention) {
-            return null;
-        }
-        const manifestPath = resolveManifestPath(packagePath, pkgJson);
-        if (!manifestPath || !existsSync(manifestPath)) {
-            // Found a potential plugin package but no manifest entry point — treat
-            // as a discovery-only result with no manifest
-            return {
-                packagePath,
-                packageName,
-                version,
-                source,
-                manifest: null,
-            };
-        }
-        try {
-            const manifest = await loadManifestFromPath(manifestPath);
-            return {
-                packagePath,
-                packageName,
-                version,
-                source,
-                manifest,
-            };
-        }
-        catch (err) {
-            // Rethrow with context — callers catch and route to the errors array
-            throw new Error(`Plugin ${packageName}: ${String(err)}`);
-        }
-    }
-    // -------------------------------------------------------------------------
-    // Public API
-    // -------------------------------------------------------------------------
-    return {
-        // -----------------------------------------------------------------------
-        // discoverAll
-        // -----------------------------------------------------------------------
-        async discoverAll(npmSearchDirs) {
-            const allDiscovered = [];
-            const allErrors = [];
-            const sources = [];
-            if (enableLocalFilesystem) {
-                sources.push("local-filesystem");
-                const fsResult = await this.discoverFromLocalFilesystem();
-                allDiscovered.push(...fsResult.discovered);
-                allErrors.push(...fsResult.errors);
-            }
-            if (enableNpmDiscovery) {
-                sources.push("npm");
-                const npmResult = await this.discoverFromNpm(npmSearchDirs);
-                // Deduplicate against already-discovered packages (same package path)
-                const existingPaths = new Set(allDiscovered.map((d) => d.packagePath));
-                for (const plugin of npmResult.discovered) {
-                    if (!existingPaths.has(plugin.packagePath)) {
-                        allDiscovered.push(plugin);
-                    }
-                }
-                allErrors.push(...npmResult.errors);
-            }
-            // Future: registry source (options.registryUrl)
-            if (options.registryUrl) {
-                sources.push("registry");
-                log.warn({ registryUrl: options.registryUrl }, "plugin-loader: remote registry discovery is not yet implemented");
-            }
-            log.info({
-                discovered: allDiscovered.length,
-                errors: allErrors.length,
-                sources,
-            }, "plugin-loader: discovery complete");
-            return { discovered: allDiscovered, errors: allErrors, sources };
-        },
-        // -----------------------------------------------------------------------
-        // discoverFromLocalFilesystem
-        // -----------------------------------------------------------------------
-        async discoverFromLocalFilesystem(dir) {
-            const scanDir = dir ?? localPluginDir;
-            const discovered = [];
-            const errors = [];
-            if (!existsSync(scanDir)) {
-                log.debug({ dir: scanDir }, "plugin-loader: local plugin directory does not exist, skipping");
-                return { discovered, errors, sources: ["local-filesystem"] };
-            }
-            let entries;
-            try {
-                entries = await readdir(scanDir);
-            }
-            catch (err) {
-                log.warn({ dir: scanDir, err }, "plugin-loader: failed to read local plugin directory");
-                return { discovered, errors, sources: ["local-filesystem"] };
-            }
-            for (const entry of entries) {
-                const entryPath = path.join(scanDir, entry);
-                // Check if entry is a directory
-                let entryStat;
-                try {
-                    entryStat = await stat(entryPath);
-                }
-                catch {
-                    continue;
-                }
-                if (!entryStat.isDirectory())
-                    continue;
-                // Handle scoped packages: @scope/plugin-name is a subdirectory
-                if (entry.startsWith("@")) {
-                    let scopedEntries;
-                    try {
-                        scopedEntries = await readdir(entryPath);
-                    }
-                    catch {
-                        continue;
-                    }
-                    for (const scopedEntry of scopedEntries) {
-                        const scopedPath = path.join(entryPath, scopedEntry);
-                        try {
-                            const scopedStat = await stat(scopedPath);
-                            if (!scopedStat.isDirectory())
-                                continue;
-                            const plugin = await buildDiscoveredPlugin(scopedPath, "local-filesystem");
-                            if (plugin)
-                                discovered.push(plugin);
-                        }
-                        catch (err) {
-                            errors.push({
-                                packagePath: scopedPath,
-                                packageName: `${entry}/${scopedEntry}`,
-                                error: String(err),
-                            });
-                        }
-                    }
-                    continue;
-                }
-                try {
-                    const plugin = await buildDiscoveredPlugin(entryPath, "local-filesystem");
-                    if (plugin)
-                        discovered.push(plugin);
-                }
-                catch (err) {
-                    const pkgJson = await readPackageJson(entryPath);
-                    const packageName = typeof pkgJson?.["name"] === "string" ? pkgJson["name"] : entry;
-                    errors.push({ packagePath: entryPath, packageName, error: String(err) });
-                }
-            }
-            log.debug({ dir: scanDir, discovered: discovered.length, errors: errors.length }, "plugin-loader: local filesystem scan complete");
-            return { discovered, errors, sources: ["local-filesystem"] };
-        },
-        // -----------------------------------------------------------------------
-        // discoverFromNpm
-        // -----------------------------------------------------------------------
-        async discoverFromNpm(searchDirs) {
-            const discovered = [];
-            const errors = [];
-            // Determine the node_modules directories to search.
-            // When searchDirs is undefined OR empty, fall back to the conventional
-            // defaults (cwd/node_modules and localPluginDir/node_modules).
-            // To search nowhere explicitly, pass a non-empty array of non-existent paths.
-            const dirsToSearch = searchDirs && searchDirs.length > 0 ? searchDirs : [];
-            if (dirsToSearch.length === 0) {
-                // Default: search node_modules relative to the process working directory
-                // and also the local plugin dir's node_modules
-                const cwdNodeModules = path.join(process.cwd(), "node_modules");
-                const localNodeModules = path.join(localPluginDir, "node_modules");
-                if (existsSync(cwdNodeModules))
-                    dirsToSearch.push(cwdNodeModules);
-                if (existsSync(localNodeModules))
-                    dirsToSearch.push(localNodeModules);
-            }
-            for (const nodeModulesDir of dirsToSearch) {
-                if (!existsSync(nodeModulesDir))
-                    continue;
-                let entries;
-                try {
-                    entries = await readdir(nodeModulesDir);
-                }
-                catch {
-                    continue;
-                }
-                for (const entry of entries) {
-                    const entryPath = path.join(nodeModulesDir, entry);
-                    // Handle scoped packages (@scope/*)
-                    if (entry.startsWith("@")) {
-                        let scopedEntries;
-                        try {
-                            scopedEntries = await readdir(entryPath);
-                        }
-                        catch {
-                            continue;
-                        }
-                        for (const scopedEntry of scopedEntries) {
-                            const fullName = `${entry}/${scopedEntry}`;
-                            if (!isPluginPackageName(fullName))
-                                continue;
-                            const scopedPath = path.join(entryPath, scopedEntry);
-                            try {
-                                const plugin = await buildDiscoveredPlugin(scopedPath, "npm");
-                                if (plugin)
-                                    discovered.push(plugin);
-                            }
-                            catch (err) {
-                                errors.push({
-                                    packagePath: scopedPath,
-                                    packageName: fullName,
-                                    error: String(err),
-                                });
-                            }
-                        }
-                        continue;
-                    }
-                    // Non-scoped packages: check naming convention
-                    if (!isPluginPackageName(entry))
-                        continue;
-                    let entryStat;
-                    try {
-                        entryStat = await stat(entryPath);
-                    }
-                    catch {
-                        continue;
-                    }
-                    if (!entryStat.isDirectory())
-                        continue;
-                    try {
-                        const plugin = await buildDiscoveredPlugin(entryPath, "npm");
-                        if (plugin)
-                            discovered.push(plugin);
-                    }
-                    catch (err) {
-                        const pkgJson = await readPackageJson(entryPath);
-                        const packageName = typeof pkgJson?.["name"] === "string" ? pkgJson["name"] : entry;
-                        errors.push({ packagePath: entryPath, packageName, error: String(err) });
-                    }
-                }
-            }
-            log.debug({ searchDirs: dirsToSearch, discovered: discovered.length, errors: errors.length }, "plugin-loader: npm discovery scan complete");
-            return { discovered, errors, sources: ["npm"] };
-        },
-        // -----------------------------------------------------------------------
-        // loadManifest
-        // -----------------------------------------------------------------------
-        async loadManifest(packagePath) {
-            const pkgJson = await readPackageJson(packagePath);
-            if (!pkgJson)
-                return null;
-            const hasPaperclipPlugin = "paperclipPlugin" in pkgJson;
-            const packageName = typeof pkgJson["name"] === "string" ? pkgJson["name"] : "";
-            const nameMatchesConvention = isPluginPackageName(packageName);
-            if (!hasPaperclipPlugin && !nameMatchesConvention) {
-                return null;
-            }
-            const manifestPath = resolveManifestPath(packagePath, pkgJson);
-            if (!manifestPath || !existsSync(manifestPath))
-                return null;
-            return loadManifestFromPath(manifestPath);
-        },
-        // -----------------------------------------------------------------------
-        // installPlugin
-        // -----------------------------------------------------------------------
-        async installPlugin(installOptions) {
-            const discovered = await fetchAndValidate(installOptions);
-            // Step 6: Persist install record in Postgres (include packagePath for local installs so the worker can be resolved)
-            await registry.install({
-                packageName: discovered.packageName,
-                packagePath: discovered.source === "local-filesystem" ? discovered.packagePath : undefined,
-            }, discovered.manifest);
-            log.info({
-                pluginId: discovered.manifest.id,
-                packageName: discovered.packageName,
-                version: discovered.version,
-                capabilities: discovered.manifest.capabilities,
-            }, "plugin-loader: plugin installed successfully");
-            return discovered;
-        },
-        // -----------------------------------------------------------------------
-        // upgradePlugin
-        // -----------------------------------------------------------------------
-        /**
-         * Upgrade an already-installed plugin to a newer version.
-         *
-         * This method:
-         * 1. Fetches and validates the new plugin package using `fetchAndValidate`.
-         * 2. Ensures the new manifest ID matches the existing plugin ID for safety.
-         * 3. Updates the plugin record in the registry with the new version and manifest.
-         *
-         * @param pluginId - The UUID of the plugin to upgrade.
-         * @param upgradeOptions - Options for the upgrade (packageName, localPath, version).
-         * @returns The old and new manifests, along with the discovery metadata.
-         * @throws {Error} If the plugin is not found or if the new manifest ID differs.
-         */
-        async upgradePlugin(pluginId, upgradeOptions) {
-            const plugin = (await registry.getById(pluginId));
-            if (!plugin)
-                throw new Error(`Plugin not found: ${pluginId}`);
-            const oldManifest = plugin.manifestJson;
-            const { packageName = plugin.packageName, 
-            // For local-path installs, fall back to the stored packagePath so
-            // `upgradePlugin` can re-read the manifest from disk without needing
-            // the caller to re-supply the path every time.
-            localPath = plugin.packagePath ?? undefined, version, } = upgradeOptions;
-            log.info({ pluginId, packageName, version, localPath }, "plugin-loader: upgrading plugin");
-            // 1. Fetch/Install the new version
-            const discovered = await fetchAndValidate({
-                packageName,
-                localPath,
-                version,
-                installDir: localPluginDir,
-            });
-            const newManifest = discovered.manifest;
-            // 2. Validate it's the same plugin ID
-            if (newManifest.id !== oldManifest.id) {
-                throw new Error(`Upgrade failed: new manifest ID '${newManifest.id}' does not match existing plugin ID '${oldManifest.id}'`);
-            }
-            // 3. Detect capability escalation — new capabilities not in the old manifest
-            const oldCaps = new Set(oldManifest.capabilities ?? []);
-            const newCaps = newManifest.capabilities ?? [];
-            const escalated = newCaps.filter((c) => !oldCaps.has(c));
-            if (escalated.length > 0) {
-                log.warn({ pluginId, escalated, oldVersion: oldManifest.version, newVersion: newManifest.version }, "plugin-loader: upgrade introduces new capabilities — requires admin approval");
-                throw new Error(`Upgrade for "${pluginId}" introduces new capabilities that require approval: ${escalated.join(", ")}. ` +
-                    `The previous version declared [${[...oldCaps].join(", ")}]. ` +
-                    `Please review and approve the capability escalation before upgrading.`);
-            }
-            // 4. Update the existing record
-            await registry.update(pluginId, {
-                packageName: discovered.packageName,
-                version: discovered.version,
-                manifest: newManifest,
-            });
-            return {
-                oldManifest,
-                newManifest,
-                discovered,
-            };
-        },
-        // -----------------------------------------------------------------------
-        // isSupportedApiVersion
-        // -----------------------------------------------------------------------
-        isSupportedApiVersion(apiVersion) {
-            return manifestValidator.getSupportedVersions().includes(apiVersion);
-        },
-        // -----------------------------------------------------------------------
-        // cleanupInstallArtifacts
-        // -----------------------------------------------------------------------
-        async cleanupInstallArtifacts(plugin) {
-            const managedTargets = new Set();
-            const managedNodeModulesDir = resolveManagedInstallPackageDir(localPluginDir, plugin.packageName);
-            const directManagedDir = path.join(localPluginDir, plugin.packageName);
-            managedTargets.add(managedNodeModulesDir);
-            if (isPathInsideDir(directManagedDir, localPluginDir)) {
-                managedTargets.add(directManagedDir);
-            }
-            if (plugin.packagePath && isPathInsideDir(plugin.packagePath, localPluginDir)) {
-                managedTargets.add(path.resolve(plugin.packagePath));
-            }
-            const packageJsonPath = path.join(localPluginDir, "package.json");
-            if (existsSync(packageJsonPath)) {
-                try {
-                    await execFileAsync("npm", ["uninstall", plugin.packageName, "--prefix", localPluginDir, "--ignore-scripts"], { timeout: 120_000 });
-                }
-                catch (err) {
-                    log.warn({
-                        pluginId: plugin.id,
-                        pluginKey: plugin.pluginKey,
-                        packageName: plugin.packageName,
-                        err: err instanceof Error ? err.message : String(err),
-                    }, "plugin-loader: npm uninstall failed during cleanup, falling back to direct removal");
-                }
-            }
-            for (const target of managedTargets) {
-                if (!existsSync(target))
-                    continue;
-                await rm(target, { recursive: true, force: true });
-            }
-        },
-        // -----------------------------------------------------------------------
-        // getLocalPluginDir
-        // -----------------------------------------------------------------------
-        getLocalPluginDir() {
-            return localPluginDir;
-        },
-        // -----------------------------------------------------------------------
-        // hasRuntimeServices
-        // -----------------------------------------------------------------------
-        hasRuntimeServices() {
-            return runtimeServices !== undefined;
-        },
-        // -----------------------------------------------------------------------
-        // -----------------------------------------------------------------------
-        // loadAll
-        // -----------------------------------------------------------------------
-        /**
-         * loadAll — Loads and activates all plugins that are currently in 'ready' status.
-         *
-         * This method is typically called during server startup. It fetches all ready
-         * plugins from the registry and attempts to activate them in parallel using
-         * Promise.allSettled. Failures in individual plugins do not prevent others from loading.
-         *
-         * @returns A promise that resolves with summary statistics of the load operation.
-         */
-        async loadAll() {
-            if (!runtimeServices) {
-                throw new Error("Cannot loadAll: no PluginRuntimeServices provided. " +
-                    "Pass runtime services as the third argument to pluginLoader().");
-            }
-            log.info("plugin-loader: loading all ready plugins");
-            // Fetch all plugins in ready status, ordered by installOrder
-            const readyPlugins = (await registry.listByStatus("ready"));
-            if (readyPlugins.length === 0) {
-                log.info("plugin-loader: no ready plugins to load");
-                return { total: 0, succeeded: 0, failed: 0, results: [] };
-            }
-            log.info({ count: readyPlugins.length }, "plugin-loader: found ready plugins to load");
-            // Load plugins in parallel
-            const results = await Promise.allSettled(readyPlugins.map((plugin) => activatePlugin(plugin)));
-            const loadResults = results.map((r, i) => {
-                if (r.status === "fulfilled")
-                    return r.value;
-                return {
-                    plugin: readyPlugins[i],
-                    success: false,
-                    error: String(r.reason),
-                    registered: { worker: false, eventSubscriptions: 0, jobs: 0, webhooks: 0, tools: 0 },
-                };
-            });
-            const succeeded = loadResults.filter((r) => r.success).length;
-            const failed = loadResults.filter((r) => !r.success).length;
-            log.info({
-                total: readyPlugins.length,
-                succeeded,
-                failed,
-            }, "plugin-loader: loadAll complete");
-            return {
-                total: readyPlugins.length,
-                succeeded,
-                failed,
-                results: loadResults,
-            };
-        },
-        // -----------------------------------------------------------------------
-        // loadSingle
-        // -----------------------------------------------------------------------
-        /**
-         * loadSingle — Loads and activates a single plugin by its ID.
-         *
-         * This method retrieves the plugin from the registry, ensures it's in a valid
-         * state, and then calls activatePlugin to start its worker and register its
-         * capabilities (tools, jobs, etc.).
-         *
-         * @param pluginId - The UUID of the plugin to load.
-         * @returns A promise that resolves with the result of the activation.
-         */
-        async loadSingle(pluginId) {
-            if (!runtimeServices) {
-                throw new Error("Cannot loadSingle: no PluginRuntimeServices provided. " +
-                    "Pass runtime services as the third argument to pluginLoader().");
-            }
-            const plugin = (await registry.getById(pluginId));
-            if (!plugin) {
-                throw new Error(`Plugin not found: ${pluginId}`);
-            }
-            // If the plugin is in 'installed' status, transition it to 'ready' first.
-            // lifecycleManager.load() transitions the status AND activates the plugin
-            // via activateReadyPlugin() → loadSingle() (recursive call with 'ready'
-            // status) → activatePlugin(). We must NOT call activatePlugin() again here,
-            // as that would double-start the worker and duplicate registrations.
-            if (plugin.status === "installed") {
-                await runtimeServices.lifecycleManager.load(pluginId);
-                const updated = (await registry.getById(pluginId));
-                if (!updated)
-                    throw new Error(`Plugin not found after status update: ${pluginId}`);
-                return {
-                    plugin: updated,
-                    success: true,
-                    registered: { worker: true, eventSubscriptions: 0, jobs: 0, webhooks: 0, tools: 0 },
-                };
-            }
-            if (plugin.status !== "ready") {
-                throw new Error(`Cannot load plugin in status '${plugin.status}'. ` +
-                    `Plugin must be in 'installed' or 'ready' status.`);
-            }
-            return activatePlugin(plugin);
-        },
-        // -----------------------------------------------------------------------
-        // unloadSingle
-        // -----------------------------------------------------------------------
-        async unloadSingle(pluginId, pluginKey) {
-            if (!runtimeServices) {
-                throw new Error("Cannot unloadSingle: no PluginRuntimeServices provided.");
-            }
-            log.info({ pluginId, pluginKey }, "plugin-loader: unloading single plugin");
-            const { workerManager, eventBus, jobScheduler, toolDispatcher, } = runtimeServices;
-            // 1. Unregister from job scheduler (cancels in-flight runs)
-            try {
-                await jobScheduler.unregisterPlugin(pluginId);
-            }
-            catch (err) {
-                log.warn({ pluginId, err: err instanceof Error ? err.message : String(err) }, "plugin-loader: failed to unregister from job scheduler (best-effort)");
-            }
-            // 2. Clear event subscriptions
-            eventBus.clearPlugin(pluginKey);
-            // 3. Unregister agent tools
-            toolDispatcher.unregisterPluginTools(pluginKey);
-            // 4. Stop the worker process
-            try {
-                if (workerManager.isRunning(pluginId)) {
-                    await workerManager.stopWorker(pluginId);
-                }
-            }
-            catch (err) {
-                log.warn({ pluginId, err: err instanceof Error ? err.message : String(err) }, "plugin-loader: failed to stop worker during unload (best-effort)");
-            }
-            log.info({ pluginId, pluginKey }, "plugin-loader: plugin unloaded successfully");
-        },
-        // -----------------------------------------------------------------------
-        // shutdownAll
-        // -----------------------------------------------------------------------
-        async shutdownAll() {
-            if (!runtimeServices) {
-                throw new Error("Cannot shutdownAll: no PluginRuntimeServices provided.");
-            }
-            log.info("plugin-loader: shutting down all plugins");
-            const { workerManager, jobScheduler } = runtimeServices;
-            // 1. Stop the job scheduler tick loop
-            jobScheduler.stop();
-            // 2. Stop all worker processes
-            await workerManager.stopAll();
-            log.info("plugin-loader: all plugins shut down");
-        },
-    };
-    // -------------------------------------------------------------------------
-    // Internal: activatePlugin — shared logic for loadAll and loadSingle
-    // -------------------------------------------------------------------------
-    /**
-     * Activate a single plugin: spawn its worker, register event subscriptions,
-     * sync jobs, register tools.
-     *
-     * This is the core orchestration logic shared by `loadAll()` and `loadSingle()`.
-     * Failures are caught and reported in the result; the plugin is marked as
-     * `error` in the database when activation fails.
-     */
-    async function activatePlugin(plugin) {
-        const manifest = plugin.manifestJson;
-        const pluginId = plugin.id;
-        const pluginKey = plugin.pluginKey;
-        const registered = {
-            worker: false,
-            eventSubscriptions: 0,
-            jobs: 0,
-            webhooks: 0,
-            tools: 0,
-        };
-        // Guard: runtime services must exist (callers already checked)
-        if (!runtimeServices) {
-            return {
-                plugin,
-                success: false,
-                error: "No runtime services available",
-                registered,
-            };
-        }
-        const { workerManager, eventBus, jobScheduler, jobStore, toolDispatcher, lifecycleManager, buildHostHandlers, instanceInfo, } = runtimeServices;
-        try {
-            log.info({ pluginId, pluginKey, version: plugin.version }, "plugin-loader: activating plugin");
-            // ------------------------------------------------------------------
-            // 1. Resolve worker entrypoint
-            // ------------------------------------------------------------------
-            const workerEntrypoint = resolveWorkerEntrypoint(plugin, localPluginDir);
-            // ------------------------------------------------------------------
-            // 2. Build host handlers for this plugin
-            // ------------------------------------------------------------------
-            const hostHandlers = buildHostHandlers(pluginId, manifest);
-            // ------------------------------------------------------------------
-            // 3. Retrieve plugin config (if any)
-            // ------------------------------------------------------------------
-            let config = {};
-            try {
-                const configRow = await registry.getConfig(pluginId);
-                if (configRow && typeof configRow === "object" && "configJson" in configRow) {
-                    config = configRow.configJson ?? {};
-                }
-            }
-            catch {
-                // Config may not exist yet — use empty object
-                log.debug({ pluginId }, "plugin-loader: no config found, using empty config");
-            }
-            // ------------------------------------------------------------------
-            // 4. Spawn worker process
-            // ------------------------------------------------------------------
-            const workerOptions = {
-                entrypointPath: workerEntrypoint,
-                manifest,
-                config,
-                instanceInfo,
-                apiVersion: manifest.apiVersion,
-                hostHandlers,
-                autoRestart: true,
-            };
-            // Repo-local plugin installs can resolve workspace TS sources at runtime
-            // (for example @paperclipai/shared exports). Run those workers through
-            // the tsx loader so first-party example plugins work in development.
-            if (plugin.packagePath && existsSync(DEV_TSX_LOADER_PATH)) {
-                workerOptions.execArgv = ["--import", DEV_TSX_LOADER_PATH];
-            }
-            await workerManager.startWorker(pluginId, workerOptions);
-            registered.worker = true;
-            log.info({ pluginId, pluginKey }, "plugin-loader: worker started");
-            // ------------------------------------------------------------------
-            // 5. Sync job declarations and register with scheduler
-            // ------------------------------------------------------------------
-            const jobDeclarations = manifest.jobs ?? [];
-            if (jobDeclarations.length > 0) {
-                await jobStore.syncJobDeclarations(pluginId, jobDeclarations);
-                await jobScheduler.registerPlugin(pluginId);
-                registered.jobs = jobDeclarations.length;
-                log.info({ pluginId, pluginKey, jobs: jobDeclarations.length }, "plugin-loader: job declarations synced and plugin registered with scheduler");
-            }
-            // ------------------------------------------------------------------
-            // 6. Register event subscriptions
-            //
-            // Note: Event subscriptions are declared at runtime by the plugin
-            // worker via the SDK's ctx.events.on() calls. The event bus manages
-            // per-plugin subscription scoping. Here we ensure the event bus has
-            // a scoped handle ready for this plugin — the actual subscriptions
-            // are registered by the host handler layer when the worker calls
-            // events.subscribe via RPC.
-            //
-            // The bus.forPlugin() call creates the scoped handle if needed;
-            // any previous subscriptions for this plugin are preserved if the
-            // worker is restarting.
-            // ------------------------------------------------------------------
-            const _scopedBus = eventBus.forPlugin(pluginKey);
-            registered.eventSubscriptions = eventBus.subscriptionCount(pluginKey);
-            log.debug({ pluginId, pluginKey }, "plugin-loader: event bus scoped handle ready");
-            // ------------------------------------------------------------------
-            // 7. Register webhook endpoints (manifest-declared)
-            //
-            // Webhooks are statically declared in the manifest. The actual
-            // endpoint routing is handled by the plugin routes module which
-            // checks the manifest for declared webhooks. No explicit
-            // registration step is needed here — the manifest is persisted
-            // in the DB and the route handler reads it at request time.
-            //
-            // We track the count for the result reporting.
-            // ------------------------------------------------------------------
-            const webhookDeclarations = manifest.webhooks ?? [];
-            registered.webhooks = webhookDeclarations.length;
-            if (webhookDeclarations.length > 0) {
-                log.info({ pluginId, pluginKey, webhooks: webhookDeclarations.length }, "plugin-loader: webhook endpoints declared in manifest");
-            }
-            // ------------------------------------------------------------------
-            // 8. Register agent tools
-            // ------------------------------------------------------------------
-            const toolDeclarations = manifest.tools ?? [];
-            if (toolDeclarations.length > 0) {
-                toolDispatcher.registerPluginTools(pluginKey, manifest);
-                registered.tools = toolDeclarations.length;
-                log.info({ pluginId, pluginKey, tools: toolDeclarations.length }, "plugin-loader: agent tools registered");
-            }
-            // ------------------------------------------------------------------
-            // Done — plugin fully activated
-            // ------------------------------------------------------------------
-            log.info({
-                pluginId,
-                pluginKey,
-                version: plugin.version,
-                registered,
-            }, "plugin-loader: plugin activated successfully");
-            return { plugin, success: true, registered };
-        }
-        catch (err) {
-            const errorMessage = err instanceof Error ? err.message : String(err);
-            log.error({ pluginId, pluginKey, err: errorMessage }, "plugin-loader: failed to activate plugin");
-            // Mark the plugin as errored in the database so it is not retried
-            // automatically on next startup without operator intervention.
-            try {
-                await lifecycleManager.markError(pluginId, `Activation failed: ${errorMessage}`);
-            }
-            catch (markErr) {
-                log.error({
-                    pluginId,
-                    err: markErr instanceof Error ? markErr.message : String(markErr),
-                }, "plugin-loader: failed to mark plugin as error after activation failure");
-            }
-            return {
-                plugin,
-                success: false,
-                error: errorMessage,
-                registered,
-            };
-        }
-    }
-}
-// ---------------------------------------------------------------------------
-// Worker entrypoint resolution
-// ---------------------------------------------------------------------------
-/**
- * Resolve the absolute path to a plugin's worker entrypoint from its manifest
- * and known install locations.
- *
- * The manifest `entrypoints.worker` field is relative to the package root.
- * We check the local plugin directory (where the package was installed) and
- * also the package directory if it was a local-path install.
- *
- * @see PLUGIN_SPEC.md §10 — Package Contract
- */
-function resolveWorkerEntrypoint(plugin, localPluginDir) {
-    const manifest = plugin.manifestJson;
-    const workerRelPath = manifest.entrypoints.worker;
-    // For local-path installs we persist the resolved package path; use it first
-    if (plugin.packagePath && existsSync(plugin.packagePath)) {
-        const entrypoint = path.resolve(plugin.packagePath, workerRelPath);
-        if (entrypoint.startsWith(path.resolve(plugin.packagePath)) && existsSync(entrypoint)) {
-            return entrypoint;
-        }
-    }
-    // Try the local plugin directory (standard npm install location)
-    const packageName = plugin.packageName;
-    let packageDir;
-    if (packageName.startsWith("@")) {
-        // Scoped package: @scope/plugin-name → localPluginDir/node_modules/@scope/plugin-name
-        const [scope, name] = packageName.split("/");
-        packageDir = path.join(localPluginDir, "node_modules", scope, name);
-    }
-    else {
-        packageDir = path.join(localPluginDir, "node_modules", packageName);
-    }
-    // Also check if the package exists directly under localPluginDir
-    // (for direct local-path installs or symlinked packages)
-    const directDir = path.join(localPluginDir, packageName);
-    // Try in order: node_modules path, direct path
-    for (const dir of [packageDir, directDir]) {
-        const entrypoint = path.resolve(dir, workerRelPath);
-        // Security: ensure entrypoint is actually inside the directory (prevent path traversal)
-        if (!entrypoint.startsWith(path.resolve(dir))) {
-            continue;
-        }
-        if (existsSync(entrypoint)) {
-            return entrypoint;
-        }
-    }
-    // Fallback: try the worker path as-is (absolute or relative to cwd)
-    // ONLY if it's already an absolute path and we trust the manifest (which we've already validated)
-    if (path.isAbsolute(workerRelPath) && existsSync(workerRelPath)) {
-        return workerRelPath;
-    }
-    throw new Error(`Worker entrypoint not found for plugin "${plugin.pluginKey}". ` +
-        `Checked: ${path.resolve(packageDir, workerRelPath)}, ` +
-        `${path.resolve(directDir, workerRelPath)}`);
-}
-function resolveManagedInstallPackageDir(localPluginDir, packageName) {
-    if (packageName.startsWith("@")) {
-        return path.join(localPluginDir, "node_modules", ...packageName.split("/"));
-    }
-    return path.join(localPluginDir, "node_modules", packageName);
-}
-function isPathInsideDir(candidatePath, parentDir) {
-    const resolvedCandidate = path.resolve(candidatePath);
-    const resolvedParent = path.resolve(parentDir);
-    const relative = path.relative(resolvedParent, resolvedCandidate);
-    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
-}
-//# sourceMappingURL=plugin-loader.js.map