@checkstack/backend 0.8.2 → 0.9.1

package/src/index.ts

@@ -2,7 +2,6 @@ import type { Server } from "bun";
 import { type Context, Hono } from "hono";
 import { TrieRouter } from "hono/router/trie-router";
 import { PluginManager } from "./plugin-manager";
-import { logger } from "hono/logger";
 import { migrate } from "drizzle-orm/node-postgres/migrator";
 import { db } from "./db";
 import path from "node:path";
@@ -12,17 +11,35 @@ import { coreServices, coreHooks } from "@checkstack/backend-api";
 import { extractErrorMessage } from "@checkstack/common";
 import { plugins } from "./schema";
 import { eq, and } from "drizzle-orm";
-import { PluginLocalInstaller } from "./services/plugin-installer";
 import { QueuePluginRegistryImpl } from "./services/queue-plugin-registry";
 import { QueueManagerImpl } from "./services/queue-manager";
 import { CachePluginRegistryImpl } from "./services/cache-plugin-registry";
 import { CacheManagerImpl } from "./services/cache-manager";
+import { PostgresPluginArtifactStore } from "./services/plugin-artifact-store";
+import { DefaultPluginInstallerRegistry } from "./services/plugin-installers/installer-registry";
+import { PluginEventRecorder } from "./services/plugin-event-recorder";
+import { createPluginManagerRouter } from "./services/plugin-manager-router";
+import {
+  pluginManagerAccessRules,
+  pluginMetadata as pluginManagerMetadata,
+  pluginManagerAccess,
+} from "@checkstack/pluginmanager-common";
+import {
+  extractPackageJson,
+  tryExtractBundle,
+  MAX_TARBALL_SIZE_BYTES,
+} from "./services/plugin-installers/tarball-utils";
 import {
   createWebSocketHandler,
   SignalServiceImpl,
   type WebSocketData,
 } from "@checkstack/signal-backend";
-import type { WsConnectionHandlers } from "@checkstack/backend-api";
+import type {
+  AuthService,
+  BackendPlugin,
+  WsConnectionHandlers,
+} from "@checkstack/backend-api";
+import { createDevAuthService } from "./services/dev-auth";
 
 // =============================================================================
 // SERVER-LEVEL WEBSOCKET DATA
@@ -46,7 +63,6 @@ import {
   PLUGIN_INSTALLED,
   PLUGIN_DEREGISTERED,
 } from "@checkstack/signal-common";
-import { createPluginAdminRouter } from "./plugin-manager/plugin-admin-router";
 import {
   pluginMetadata as apiDocsMetadata,
   apiDocsAccess,
@@ -113,7 +129,38 @@ app.use(
     credentials: true,
   })
 );
-app.use("*", logger());
+// Request/response logging through our rootLogger (winston) instead of
+// hono/logger which bypasses winston and writes to stdout directly. Goes
+// at debug level for healthy responses; warn for 4xx and error for 5xx so
+// failures surface even with low verbosity. The 5xx branch additionally
+// peeks the response body so the underlying error message lands in the
+// log — Hono returns errors as JSON via `c.json({error}, 500)` which the
+// default access log strips down to just the status code.
+app.use("*", async (c, next) => {
+  const start = performance.now();
+  const method = c.req.method;
+  const path = c.req.path;
+  rootLogger.debug(`<-- ${method} ${path}`);
+  await next();
+  const elapsedMs = (performance.now() - start).toFixed(1);
+  const status = c.res.status;
+  const line = `--> ${method} ${path} ${status} ${elapsedMs}ms`;
+
+  if (status >= 500) {
+    let body: string | undefined;
+    try {
+      // Clone so the response stream remains consumable downstream.
+      body = await c.res.clone().text();
+    } catch {
+      // ignore — best-effort body capture only
+    }
+    rootLogger.error(body ? `${line} — ${body}` : line);
+  } else if (status >= 400) {
+    rootLogger.warn(line);
+  } else {
+    rootLogger.debug(line);
+  }
+});
 
 // =============================================================================
 // PLATFORM ENDPOINTS — /.checkstack/*
@@ -316,12 +363,6 @@ if (frontendDistPath && fs.existsSync(frontendDistPath)) {
 const init = async () => {
   rootLogger.info("🚀 Starting Checkstack Core...");
 
-  // Register Plugin Installer Service
-  const installer = new PluginLocalInstaller(
-    path.join(process.cwd(), "runtime_plugins")
-  );
-  pluginManager.registerService(coreServices.pluginInstaller, installer);
-
   // 1. Run Core Migrations
   rootLogger.info("🔄 Running core migrations...");
   try {
@@ -373,6 +414,128 @@ const init = async () => {
   );
   pluginManager.registerService(coreServices.cacheManager, cacheManager);
 
+  // 1.9. Register Plugin Install Services (artifact store + installer registry)
+  rootLogger.debug("Registering plugin install services...");
+  const runtimePluginsDir = path.join(process.cwd(), "runtime_plugins");
+  fs.mkdirSync(runtimePluginsDir, { recursive: true });
+  const pluginArtifactStore = new PostgresPluginArtifactStore(db);
+  const pluginInstallerRegistry = new DefaultPluginInstallerRegistry({
+    runtimeDir: runtimePluginsDir,
+    artifactStore: pluginArtifactStore,
+  });
+  pluginManager.registerService(
+    coreServices.pluginArtifactStore,
+    pluginArtifactStore,
+  );
+  pluginManager.registerService(
+    coreServices.pluginInstallerRegistry,
+    pluginInstallerRegistry,
+  );
+  // Per-instance event recorder (instanceId is the bun process pid for now;
+  // upgrade to a stable instance id when multi-region deploys land).
+  const eventRecorder = new PluginEventRecorder(db, `bun-${process.pid}`);
+  pluginManager.setEventRecorder(eventRecorder);
+  pluginManager.setRuntimeDir(runtimePluginsDir);
+
+  // Tarball-upload endpoint backing the install UI's "Tarball Upload" tab.
+  //
+  // The user uploads a `.tgz` produced by `bunx @checkstack/scripts plugin-pack`
+  // (single-package or `--bundle` mode). We peek the bytes to derive the
+  // primary `(name, version)`, persist the artifact to plugin_artifacts, and
+  // return the `artifactId`. The frontend then submits a `PluginSource` of
+  // type "tarball" with that id to `previewInstall` / `install`.
+  //
+  // We deliberately keep this as a plain Hono route (not an oRPC procedure)
+  // because oRPC contracts are JSON-only — multipart bodies can't be
+  // expressed there. Auth + access are enforced manually below using the
+  // same access service the rest of the platform uses.
+  app.post("/api/pluginmanager/upload-tarball", async (c) => {
+    const authService = await pluginManager.getService(coreServices.auth);
+    if (!authService) {
+      return c.json({ error: "Auth service not available" }, 503);
+    }
+    const user = await authService.authenticate(c.req.raw);
+    if (!user || user.type === "service") {
+      return c.json({ error: "Authentication required" }, 401);
+    }
+    const requiredAccess = `${pluginManagerMetadata.pluginId}.${pluginManagerAccess.install.id}`;
+    const accessRules = (
+      "accessRules" in user ? user.accessRules : []
+    ) as string[];
+    const anonymous = await authService.getAnonymousAccessRules();
+    if (!accessRules.includes(requiredAccess) && !anonymous.includes(requiredAccess)) {
+      return c.json({ error: "Access denied" }, 403);
+    }
+
+    const formData = await c.req.formData();
+    const file = formData.get("file");
+    if (!file || typeof file === "string") {
+      return c.json({ error: "Missing 'file' field in multipart body" }, 400);
+    }
+    const bytes = new Uint8Array(await file.arrayBuffer());
+    if (bytes.byteLength === 0) {
+      return c.json({ error: "Uploaded file is empty" }, 400);
+    }
+    if (bytes.byteLength > MAX_TARBALL_SIZE_BYTES) {
+      return c.json(
+        {
+          error: `Tarball exceeds maximum size: ${bytes.byteLength} > ${MAX_TARBALL_SIZE_BYTES} bytes`,
+        },
+        413,
+      );
+    }
+
+    // Derive (name, version) by peeking the tarball. For bundle tarballs,
+    // use the primary's manifest entry; for single packages, the embedded
+    // package.json. Validation happens here too — a malformed tarball is
+    // rejected before any DB write.
+    let pluginName: string;
+    let version: string;
+    try {
+      const bundle = await tryExtractBundle(bytes);
+      if (bundle) {
+        pluginName = bundle.manifest.primary;
+        const primaryEntry = bundle.manifest.packages.find(
+          (p) => p.name === bundle.manifest.primary,
+        );
+        if (!primaryEntry) {
+          return c.json(
+            { error: `Bundle manifest missing primary entry '${pluginName}'` },
+            400,
+          );
+        }
+        version = primaryEntry.version;
+      } else {
+        const meta = await extractPackageJson(bytes);
+        pluginName = meta.name;
+        version = meta.version;
+      }
+    } catch (error) {
+      return c.json(
+        { error: `Failed to peek tarball: ${extractErrorMessage(error)}` },
+        400,
+      );
+    }
+
+    const { artifactId, contentHash } = await pluginArtifactStore.store({
+      pluginName,
+      version,
+      tarball: bytes,
+    });
+
+    rootLogger.info(
+      `📦 Tarball uploaded: ${pluginName}@${version} (artifactId=${artifactId}, ${bytes.byteLength} bytes)`,
+    );
+
+    return c.json({
+      artifactId,
+      pluginName,
+      version,
+      contentHash,
+      sizeBytes: bytes.byteLength,
+    });
+  });
+
   // Serve static assets for runtime frontend plugins only
   // Backend plugins don't need public assets - only frontend plugins do
   // e.g. /assets/plugins/my-plugin-frontend/index.js -> runtime_plugins/node_modules/my-plugin-frontend/dist/index.js
@@ -437,7 +600,88 @@ const init = async () => {
   }
 
   // 3. Load Plugins
-  await pluginManager.loadPlugins(app);
+  //
+  // Dev-server mode (entered via `bunx @checkstack/scripts dev` from a
+  // plugin author's repo). Two env vars control it:
+  //
+  //   - CHECKSTACK_DEV_PLUGIN_PATH: absolute path to a plugin module's
+  //     directory whose `default` export is the BackendPlugin to load.
+  //     When set, filesystem discovery is skipped — only this plugin and
+  //     core services are loaded. Lets a plugin author iterate without
+  //     a workspace checkout.
+  //   - CHECKSTACK_DEV_AUTH=true: registers a synthetic auth service that
+  //     auto-grants every access rule. Skips login flow entirely. Strictly
+  //     refused on a known-prod NODE_ENV value to make accidental misuse
+  //     loud.
+  const devPluginPath = process.env.CHECKSTACK_DEV_PLUGIN_PATH;
+  const devAuth = process.env.CHECKSTACK_DEV_AUTH === "true";
+  if (devAuth) {
+    if (process.env.NODE_ENV === "production") {
+      throw new Error(
+        "CHECKSTACK_DEV_AUTH=true is refused when NODE_ENV=production. " +
+          "Dev auth bypasses every access guard and must never run in prod.",
+      );
+    }
+    rootLogger.warn(
+      "🛠 Dev auth ENABLED — every access rule is auto-granted. Do NOT use in production.",
+    );
+    const devAuthService: AuthService = createDevAuthService({
+      getAllAccessRules: () => pluginManager.getAllAccessRules(),
+    });
+    pluginManager.registerService(coreServices.auth, devAuthService);
+  }
+
+  const manualPlugins: BackendPlugin[] = [];
+  if (devPluginPath) {
+    rootLogger.info(`🛠 Dev mode — loading plugin from ${devPluginPath}`);
+
+    // Co-load `@checkstack/*` backend deps the dev command resolved from
+    // the plugin's package.json. Without these, the plugin under dev's
+    // `init()` would hit unregistered services. The dev command always
+    // includes in-memory queue+cache providers when no other provider
+    // is in the dep graph, so coreServices.queueManager /
+    // coreServices.cacheManager have a registered strategy on boot.
+    const extraPathsRaw = process.env.CHECKSTACK_DEV_EXTRA_PLUGIN_PATHS;
+    const extraPaths: string[] = extraPathsRaw ? JSON.parse(extraPathsRaw) : [];
+    for (const extra of extraPaths) {
+      try {
+        const mod = await import(extra);
+        const exp = mod.default as BackendPlugin | undefined;
+        if (!exp || typeof exp.register !== "function") {
+          throw new Error(
+            `Module at ${extra} does not export a default BackendPlugin`,
+          );
+        }
+        manualPlugins.push(exp);
+      } catch (error) {
+        throw new Error(
+          `Failed to import co-loaded core plugin from ${extra}: ${extractErrorMessage(error)}`,
+        );
+      }
+    }
+
+    // Plugin under dev loads last; the platform's pendingInits topo-sort
+    // takes care of actual init order, but importing it last makes the
+    // boot log easier to read.
+    try {
+      const pluginModule = await import(devPluginPath);
+      const pluginExport = pluginModule.default as BackendPlugin | undefined;
+      if (!pluginExport || typeof pluginExport.register !== "function") {
+        throw new Error(
+          `Module at ${devPluginPath} does not export a default BackendPlugin`,
+        );
+      }
+      manualPlugins.push(pluginExport);
+    } catch (error) {
+      throw new Error(
+        `Failed to import dev plugin from ${devPluginPath}: ${extractErrorMessage(error)}`,
+      );
+    }
+  }
+
+  await pluginManager.loadPlugins(app, manualPlugins, {
+    skipDiscovery: !!devPluginPath,
+  });
 
   // 4. Wire up auth client for access-based signal filtering
   // This must happen AFTER plugins load so auth-backend is available
@@ -455,13 +699,28 @@ const init = async () => {
     );
   }
 
-  // 5. Register plugin admin router (core admin endpoints)
-  const pluginAdminRouter = createPluginAdminRouter({
+  // 4.5. Register the plugin-manager admin router (core router, not a regular
+  // plugin). Access rules from `@checkstack/pluginmanager-common` are also
+  // pushed into the access registry here so the autoAuthMiddleware can
+  // resolve them. We use the existing access-rule prefix scheme so the
+  // ids land as e.g. `pluginmanager.plugin.manage`.
+  pluginManager.registerCoreAccessRules(
+    pluginManagerMetadata.pluginId,
+    pluginManagerAccessRules,
+  );
+  pluginManager.registerCorePluginMetadata(pluginManagerMetadata);
+  const pluginManagerRouter = createPluginManagerRouter({
+    db,
     pluginManager,
-    installer,
+    registry: pluginManager.getRegistry(),
+    eventRecorder,
+    workspaceRoot: path.resolve(import.meta.dir, "..", "..", ".."),
+    runtimeDir: runtimePluginsDir,
   });
-  // Register as core router - available at /api/core/
-  pluginManager.registerCoreRouter("core", pluginAdminRouter);
+  pluginManager.registerCoreRouter(
+    pluginManagerMetadata.pluginId,
+    pluginManagerRouter,
+  );
 
   // 5. Setup lifecycle listeners for multi-instance coordination
   await pluginManager.setupLifecycleListeners();

package/src/plugin-deregistration.test.ts

@@ -0,0 +1,137 @@
+import { describe, it, expect, mock, beforeEach } from "bun:test";
+import { PluginManager } from "./plugin-manager";
+
+/**
+ * Integration test for the originator/in-process split introduced in the
+ * runtime plugin system.
+ *
+ * Key contract: `deregisterPluginInProcess` must NOT touch any persistent
+ * state. It runs on every instance via the broadcast hook; the destructive
+ * cleanup (drop schema, delete plugin_configs, delete plugin_artifacts,
+ * delete plugins rows) only runs on the originator via `deletePluginData`.
+ *
+ * If a future refactor accidentally pushes destructive ops back into the
+ * in-process path, these tests fire.
+ */
+
+describe("deregisterPluginInProcess", () => {
+  let pluginManager: PluginManager;
+
+  beforeEach(() => {
+    pluginManager = new PluginManager();
+  });
+
+  it("clears in-memory cleanup handlers and runs them in LIFO order", async () => {
+    const order: string[] = [];
+    const handlerA = mock(async () => {
+      order.push("a");
+    });
+    const handlerB = mock(async () => {
+      order.push("b");
+    });
+
+    // Inject cleanup handlers using the same mechanism plugins use during
+    // registration. We poke the private map because the public path (full
+    // backendPlugin.register) needs a real plugin module.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const handlers = (pluginManager as any).cleanupHandlers as Map<
+      string,
+      Array<() => Promise<void>>
+    >;
+    handlers.set("test-plugin", [handlerA, handlerB]);
+
+    await pluginManager.deregisterPluginInProcess("test-plugin");
+
+    // LIFO: handlerB ran before handlerA
+    expect(order).toEqual(["b", "a"]);
+    expect(handlers.has("test-plugin")).toBe(false);
+  });
+
+  it("removes router, contract, metadata and access-rule entries", async () => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const pm = pluginManager as any;
+    pm.pluginRpcRouters.set("foo", { router: true });
+    pm.pluginContractRegistry.set("foo", { contract: true });
+    pm.pluginMetadataRegistry.set("foo", { pluginId: "foo" });
+    pm.registeredAccessRules.push({
+      id: "foo.something",
+      pluginId: "foo",
+      action: "read",
+      resourceType: "thing",
+      description: "test",
+    });
+
+    await pluginManager.deregisterPluginInProcess("foo");
+
+    expect(pm.pluginRpcRouters.has("foo")).toBe(false);
+    expect(pm.pluginContractRegistry.has("foo")).toBe(false);
+    expect(pm.pluginMetadataRegistry.has("foo")).toBe(false);
+    expect(
+      pm.registeredAccessRules.some(
+        (r: { pluginId: string }) => r.pluginId === "foo",
+      ),
+    ).toBe(false);
+  });
+
+  it("does not invoke any artifact-store or destructive ops", async () => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const pm = pluginManager as any;
+
+    const artifactStoreCalls: string[] = [];
+    const fakeArtifactStore = {
+      maxArtifactSize: 1,
+      store: () => {
+        artifactStoreCalls.push("store");
+        return Promise.resolve({ artifactId: "x", contentHash: "x" });
+      },
+      fetch: () => {
+        artifactStoreCalls.push("fetch");
+        return Promise.resolve(undefined);
+      },
+      fetchById: () => {
+        artifactStoreCalls.push("fetchById");
+        return Promise.resolve(undefined);
+      },
+      delete: () => {
+        artifactStoreCalls.push("delete");
+        return Promise.resolve();
+      },
+      deleteByBundle: () => {
+        artifactStoreCalls.push("deleteByBundle");
+        return Promise.resolve();
+      },
+    };
+    // The artifact store is registered via coreServices.pluginArtifactStore.
+    // Even when present, deregisterPluginInProcess should not consult it.
+    pm.registry.register(
+      { id: "core.pluginArtifactStore" },
+      fakeArtifactStore,
+    );
+
+    pm.cleanupHandlers.set("foo", []);
+    await pluginManager.deregisterPluginInProcess("foo");
+
+    expect(artifactStoreCalls).toEqual([]);
+  });
+
+  it("handler errors do not block subsequent cleanup or remove-from-registry", async () => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const pm = pluginManager as any;
+
+    const goodHandler = mock(async () => {});
+    const badHandler = mock(async () => {
+      throw new Error("intentional");
+    });
+
+    pm.cleanupHandlers.set("plugin-a", [goodHandler, badHandler]);
+    pm.pluginRpcRouters.set("plugin-a", {});
+
+    await pluginManager.deregisterPluginInProcess("plugin-a");
+
+    expect(badHandler).toHaveBeenCalled();
+    expect(goodHandler).toHaveBeenCalled();
+    // Even though one handler threw, the in-memory state was cleared:
+    expect(pm.pluginRpcRouters.has("plugin-a")).toBe(false);
+    expect(pm.cleanupHandlers.has("plugin-a")).toBe(false);
+  });
+});

package/src/plugin-manager/api-router.ts

@@ -20,6 +20,8 @@ import type {
 import type { ServiceRegistry } from "../services/service-registry";
 import type { EventBus } from "@checkstack/backend-api";
 import type { PluginMetadata } from "@checkstack/common";
+import { rootLogger } from "../logger";
+import { extractErrorMessage } from "@checkstack/common";
 
 /**
  * Creates the API route handler for Hono.
@@ -71,17 +73,18 @@ export function createApiRouteHandler({
             try {
               return await next(rest);
             } catch (error) {
-              if (logger) {
-                logger.error(`RPC procedure error: ${String(error)}`);
-                const stack =
-                  error !== null &&
-                  typeof error === "object" &&
-                  "stack" in error
-                    ? (error as { stack: string }).stack
-                    : undefined;
-                if (stack) {
-                  logger.error(`Stack trace: ${stack}`);
-                }
+              const target = (logger ?? rootLogger) as Logger;
+              target.error(
+                `RPC ${pathname} failed: ${extractErrorMessage(error)}`,
+              );
+              const stack =
+                error !== null &&
+                typeof error === "object" &&
+                "stack" in error
+                  ? (error as { stack: string }).stack
+                  : undefined;
+              if (stack) {
+                target.error(`Stack trace: ${stack}`);
               }
               throw error;
             }
@@ -121,6 +124,22 @@ export function createApiRouteHandler({
       !cacheManager ||
       !eventBus
     ) {
+      const missing = [
+        !auth && "auth",
+        !logger && "logger",
+        !db && "db",
+        !fetch && "fetch",
+        !healthCheckRegistry && "healthCheckRegistry",
+        !collectorRegistry && "collectorRegistry",
+        !queuePluginRegistry && "queuePluginRegistry",
+        !queueManager && "queueManager",
+        !cachePluginRegistry && "cachePluginRegistry",
+        !cacheManager && "cacheManager",
+        !eventBus && "eventBus",
+      ].filter(Boolean).join(", ");
+      (logger ?? rootLogger).error(
+        `${pathname}: core services not initialized — missing: ${missing}`,
+      );
       return c.json({ error: "Core services not initialized" }, 500);
     }
 
@@ -136,6 +155,11 @@ export function createApiRouteHandler({
       pluginMetadataRegistry.get(pluginId);
 
     if (!pluginMetadata) {
+      (logger as Logger).error(
+        `${pathname}: no plugin metadata registered for pluginId='${pluginId}'. ` +
+          `Regular plugins populate this during register(); core routers must call ` +
+          `pluginManager.registerCorePluginMetadata().`,
+      );
       return c.json({ error: "Plugin metadata not found in registry" }, 500);
     }
 

package/src/plugin-manager/plugin-loader.ts

@@ -224,6 +224,14 @@ export async function loadPlugins({
     // 2. Sync local plugins to database
     await syncPluginsToDatabase({ localPlugins, db: deps.db });
 
+    // 2.5 Bootstrap runtime-installed plugins missing from node_modules.
+    // For every `is_uninstallable=true` row in `plugins`, ensure the
+    // package is installed in the runtime dir. If not, fetch its tarball
+    // from `plugin_artifacts` and run `bun install` so the import below
+    // resolves. This is what lets a freshly spun replica recover the
+    // full plugin set from Postgres alone.
+    await bootstrapRuntimePlugins({ db: deps.db, registry: deps.registry });
+
     // 3. Load all enabled BACKEND plugins from database
     allPlugins = await deps.db
       .select()
@@ -641,3 +649,68 @@ function validateContractAccessRules({
     }
   }
 }
+
+/**
+ * Fresh-instance bootstrap.
+ *
+ * Walks every `is_uninstallable=true` row in the `plugins` table and ensures
+ * the corresponding package is installed under the runtime dir. Missing
+ * packages are recovered from `plugin_artifacts` (bytea) and installed with
+ * `bun install --no-save --ignore-scripts`. Once this returns, the normal
+ * `pluginModule = await import(...)` in Phase 1 below resolves.
+ */
+async function bootstrapRuntimePlugins({
+  db,
+  registry,
+}: {
+  db: SafeDatabase<Record<string, unknown>>;
+  registry: ServiceRegistry;
+}): Promise<void> {
+  const installerRegistry = await registry
+    .get(coreServices.pluginInstallerRegistry, { pluginId: "core" })
+    .catch(() => {});
+  const artifactStore = await registry
+    .get(coreServices.pluginArtifactStore, { pluginId: "core" })
+    .catch(() => {});
+  if (!installerRegistry || !artifactStore) {
+    rootLogger.debug(
+      "   -> Skipping runtime plugin bootstrap (services not registered)",
+    );
+    return;
+  }
+
+  const remoteRows = await db
+    .select()
+    .from(plugins)
+    .where(eq(plugins.isUninstallable, true));
+
+  for (const row of remoteRows) {
+    if (!row.path) continue;
+    const pkgJsonPath = path.join(row.path, "package.json");
+    if (fs.existsSync(pkgJsonPath)) {
+      rootLogger.debug(`   -> ${row.name} already present, skipping bootstrap`);
+      continue;
+    }
+    rootLogger.info(
+      `🔌 Bootstrapping runtime plugin from artifact store: ${row.name}@${row.version}`,
+    );
+    const artifact = await artifactStore.fetch({
+      pluginName: row.name,
+      version: row.version,
+    });
+    if (!artifact) {
+      rootLogger.warn(
+        `   -> No artifact for ${row.name}@${row.version} — skipping. Re-install from the original source.`,
+      );
+      continue;
+    }
+    const allowInstallScripts =
+      (row.metadata as { checkstack?: { allowInstallScripts?: boolean } })
+        ?.checkstack?.allowInstallScripts === true;
+    await installerRegistry.forSource("npm").installFromArtifact({
+      tarball: artifact.tarball,
+      pluginName: row.name,
+      allowInstallScripts,
+    });
+  }
+}