@rudderhq/server 0.2.5-canary.9 → 0.2.5

package/dist/services/plugin-loader.helpers.js

@@ -0,0 +1,263 @@
+/**
+ * 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
+ *    (`~/.rudder/plugins/`) and `node_modules` for packages matching
+ *    the `rudder-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 { readFile } 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";
+export const execFileAsync = promisify(execFile);
+export const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/**
+ * Naming convention for npm-published Rudder plugins.
+ * Packages matching this pattern are considered Rudder plugins.
+ *
+ * @see PLUGIN_SPEC.md §10 — Package Contract
+ */
+export const NPM_PLUGIN_PACKAGE_PREFIX = "rudder-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(), ".rudder", "plugins");
+export const DEV_TSX_LOADER_PATH = path.resolve(__dirname, "../../../cli/node_modules/tsx/dist/loader.mjs");
+export 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 Rudder plugin naming convention.
+ * Accepts both the "rudder-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 @rudderhq/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.
+ */
+export 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 "rudderPlugin" 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
+ */
+export function resolveManifestPath(packageRoot, pkgJson) {
+    const rudderPlugin = pkgJson["rudderPlugin"];
+    if (rudderPlugin !== null &&
+        typeof rudderPlugin === "object" &&
+        !Array.isArray(rudderPlugin)) {
+        const manifestRelPath = rudderPlugin["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;
+}
+export 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(".") : [],
+    };
+}
+export 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);
+}
+export 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;
+}
+export 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: "rudder-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
+ */
+//# sourceMappingURL=plugin-loader.helpers.js.map

package/dist/services/plugin-loader.helpers.js.map

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