@checkstack/backend 0.16.2 → 0.17.1

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # @checkstack/backend
 
+## 0.17.1
+
+### Patch Changes
+
+- @checkstack/api-docs-common@0.1.18
+- @checkstack/auth-common@0.8.2
+- @checkstack/backend-api@0.21.3
+- @checkstack/cache-api@0.3.11
+- @checkstack/common@0.14.1
+- @checkstack/pluginmanager-common@0.2.7
+- @checkstack/queue-api@0.3.11
+- @checkstack/signal-backend@0.3.3
+- @checkstack/signal-common@0.2.8
+
+## 0.17.0
+
+### Minor Changes
+
+- 968c12f: Make installed (runtime) frontend plugins actually load, via Module Federation 2.0. Previously a packed external plugin's frontend could not run: the host only shared React/router with runtime plugins, and there was no working way to share the framework/UI singletons (hand-rolled import-map externalisation hit an unsolvable rolldown CJS-interop wall).
+
+  - **Host (`@checkstack/frontend`)** now uses `@module-federation/vite` as an MF host and loads runtime plugins through the MF runtime (`registerRemotes` + `loadRemote`) instead of a raw `import()`. The shared set (react, react-dom, react-router-dom, @tanstack/react-query, @checkstack/frontend-api) is owned by the host; plugins reuse those exact instances via the share scope. The old hand-rolled vendor build + import map are removed.
+  - **`@checkstack/ui`** is bundled per consumer (tree-shaken); its Theme / Toast / Performance React contexts are unified across the host and bundled-in-plugin copies via a registered (globalThis-keyed) context, so a plugin's `useTheme`/`useToast`/`usePerformance` resolve to the host's providers. The ONE exception is the Monaco / VS Code **CodeEditor**, now exposed as the `@checkstack/ui/code-editor` subpath and shared as an MF singleton: the host owns the single editor instance (and builds its `?worker&url` workers), and plugins reuse it. A plugin can now render `<CodeEditor>` (directly or via `ScriptTestPanel` / template/JSON fields) without bundling Monaco.
+  - **Scaffold + pack (`@checkstack/scripts`)** build frontend plugins as MF remotes (`vite build` with the federation plugin, exposing `./plugin`, manifest enabled, DTS disabled). The CodeEditor is shared with `import: false` so the plugin is a consume-only participant - it never bundles a local fallback of the editor, keeping the heavy `@codingame/*` / `monaco-languageclient` / `vscode` subtree out of the plugin entirely (so no `vscode` alias or ES-worker config is needed in the plugin build). `plugin-pack` builds frontend packages with `NODE_ENV=production` (the MF plugin skips the remote under `NODE_ENV=test`) and ships only `dist/`. The scaffolded route now declares a `nav` entry so it appears in the sidebar.
+  - **Backend (`@checkstack/backend`)** serves a plugin's MF assets under its (possibly scoped) package name (`/assets/plugins/@scope/name/*`), with correct content types, and the SPA catch-all defers those paths so the federation manifest/remoteEntry are not shadowed by `index.html`.
+
+  Verified end-to-end by the external-plugin install E2E (scaffold → pack → install via the Plugin Manager UI → frontend + backend + co-loaded core plugins all work).
+
+### Patch Changes
+
+- e434d62: Fix the runtime (installed) plugin path so an external plugin uploaded via the Plugin Manager actually installs and its backend loads. Five distinct defects, surfaced by a new full install E2E:
+
+  - **Plugin Manager access denied for admins.** The Plugin Manager's core access rules were registered _after_ `loadPlugins`, so the auth full-sync never wrote them to the DB; and the hand-rolled `upload-tarball` route checked `accessRules.includes(rule)` without honoring the admin `"*"` wildcard. Rules now register before `loadPlugins`, and the route honors `"*"` (matching `openapi-router.ts`).
+  - **Bundle installs 404'd on intra-bundle deps.** A bundle's siblings were installed one tarball at a time, so a sibling that depends on another sibling failed to resolve against the registry. `installBundleFromArtifacts` now installs the whole bundle via a throwaway manifest using `file:` deps + `overrides`, resolving siblings locally and merging the result into the shared runtime dir.
+  - **Primary artifact was the outer bundle archive.** The tarball/github installers stored the outer `bundle.json` archive as the primary's artifact instead of the primary's own package tarball; they now store the inner package tarball.
+  - **Non-backend siblings loaded as backend plugins.** The install broadcast tried to load `common`/`frontend` siblings as backend plugins ("does not export a valid BackendPlugin"). Only `type: "backend"` packages now register as backend plugins (mirroring fresh-instance bootstrap).
+  - **Runtime backend never migrated or got a scoped DB.** `loadSinglePlugin` now runs the plugin's Drizzle migrations into its isolated schema and injects the plugin-scoped `database` into `init`, matching the full-system loader.
+
+  Note: the installed _frontend_ half of a runtime plugin remains a known gap (the host only shares React/router with runtime plugins, and `plugin-pack` does not build frontends); tracked separately for a follow-up.
+
+  - @checkstack/api-docs-common@0.1.18
+  - @checkstack/auth-common@0.8.2
+  - @checkstack/backend-api@0.21.2
+  - @checkstack/cache-api@0.3.11
+  - @checkstack/common@0.14.1
+  - @checkstack/pluginmanager-common@0.2.7
+  - @checkstack/queue-api@0.3.11
+  - @checkstack/signal-backend@0.3.2
+  - @checkstack/signal-common@0.2.8
+
 ## 0.16.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/backend",
-  "version": "0.16.2",
+  "version": "0.17.1",
   "license": "Elastic-2.0",
   "checkstack": {
     "type": "backend"
@@ -16,12 +16,12 @@
   "dependencies": {
     "@checkstack/api-docs-common": "0.1.18",
     "@checkstack/auth-common": "0.8.2",
-    "@checkstack/backend-api": "0.21.2",
+    "@checkstack/backend-api": "0.21.3",
     "@checkstack/common": "0.14.1",
     "@checkstack/drizzle-helper": "0.0.5",
     "@checkstack/cache-api": "0.3.11",
     "@checkstack/queue-api": "0.3.11",
-    "@checkstack/signal-backend": "0.3.2",
+    "@checkstack/signal-backend": "0.3.3",
     "@checkstack/signal-common": "0.2.8",
     "@checkstack/pluginmanager-common": "0.2.7",
     "@hono/zod-validator": "^0.7.6",
@@ -45,8 +45,8 @@
     "@types/bun": "latest",
     "@types/semver": "^7.5.0",
     "@checkstack/tsconfig": "0.0.7",
-    "@checkstack/scripts": "0.4.2",
-    "@checkstack/test-utils-backend": "0.1.36",
+    "@checkstack/scripts": "0.6.0",
+    "@checkstack/test-utils-backend": "0.1.37",
     "drizzle-kit": "^0.31.10"
   }
 }

package/src/index.ts

@@ -395,7 +395,11 @@ if (frontendDistPath && fs.existsSync(frontendDistPath)) {
     // handlers (oRPC RPC + OpenAPI REST mounts).
     const apiPath =
       c.req.path.startsWith("/api/") || c.req.path.startsWith("/rest/");
-    if (apiPath) {
+    // Runtime frontend-plugin assets are served by the `/assets/plugins/*`
+    // route registered later during init. Defer to it here, otherwise this SPA
+    // fallback would return index.html for a plugin's mf-manifest.json /
+    // remoteEntry.js and the Module Federation runtime would fail (#RUNTIME-003).
+    if (apiPath || c.req.path.startsWith("/assets/plugins/")) {
       return next();
     }
 
@@ -522,7 +526,17 @@ const init = async () => {
       "accessRules" in user ? user.accessRules : []
     ) as string[];
     const anonymous = await authService.getAnonymousAccessRules();
-    if (!accessRules.includes(requiredAccess) && !anonymous.includes(requiredAccess)) {
+    // `enrichUser` collapses the admin role to the `"*"` wildcard (it never
+    // materialises every individual rule id), so an admin's `accessRules` is
+    // just `["*"]`. Honour that wildcard the same way the autoAuthMiddleware
+    // and oRPC procedures do (see auth-backend router.ts) - a bare
+    // `includes(requiredAccess)` would 403 every admin on this hand-rolled
+    // multipart route.
+    const hasAccess =
+      accessRules.includes("*") ||
+      accessRules.includes(requiredAccess) ||
+      anonymous.includes(requiredAccess);
+    if (!hasAccess) {
       return c.json({ error: "Access denied" }, 403);
     }
 
@@ -595,28 +609,51 @@ const init = async () => {
     });
   });
 
-  // 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
-  app.use("/assets/plugins/:pluginName/*", async (c, next) => {
-    const pluginName = c.req.param("pluginName");
-    // Find plugin in DB to get path
+  // Serve static assets for runtime frontend plugins (built Module Federation
+  // remotes). The plugin is served under its package name, which may be SCOPED
+  // (e.g. /assets/plugins/@scope/name/mf-manifest.json) — so a single-segment
+  // `:pluginName` route can't capture it. Use a catch-all and split the package
+  // name (two segments when it starts with `@`) from the asset path.
+  // e.g. /assets/plugins/@acme/widget-frontend/mf-manifest.json ->
+  //      runtime_plugins/node_modules/@acme/widget-frontend/dist/mf-manifest.json
+  const ASSET_CONTENT_TYPES: Record<string, string> = {
+    ".js": "text/javascript",
+    ".mjs": "text/javascript",
+    ".css": "text/css",
+    ".json": "application/json",
+    ".map": "application/json",
+    ".wasm": "application/wasm",
+  };
+  app.use("/assets/plugins/*", async (c, next) => {
+    const rest = c.req.path.split("/assets/plugins/")[1] ?? "";
+    const segments = rest.split("/").filter(Boolean);
+    const scoped = rest.startsWith("@");
+    const pluginName = scoped
+      ? segments.slice(0, 2).join("/")
+      : segments[0];
+    const assetPath = scoped
+      ? segments.slice(2).join("/")
+      : segments.slice(1).join("/");
+    // Reject path traversal and empty lookups.
+    if (!pluginName || !assetPath || assetPath.includes("..")) {
+      return next();
+    }
+
     const results = await db
       .select()
       .from(plugins)
       .where(eq(plugins.name, pluginName));
     const plugin = results[0];
-
-    // Only serve assets for frontend plugins
     if (!plugin || plugin.type !== "frontend") {
       return next();
     }
 
-    // We assume plugins are built into 'dist' folder
-    const assetPath = c.req.path.split(`/assets/plugins/${pluginName}/`)[1];
     const filePath = path.join(plugin.path, "dist", assetPath);
-
     if (fs.existsSync(filePath)) {
+      const type =
+        ASSET_CONTENT_TYPES[path.extname(filePath)] ??
+        "application/octet-stream";
+      c.header("Content-Type", type);
       return c.body(fs.readFileSync(filePath));
     }
     return next();
@@ -763,6 +800,20 @@ const init = async () => {
     }
   }
 
+  // Register the plugin-manager's core access rules + metadata BEFORE
+  // loadPlugins. The auth-backend's full access-rule sync to the DB runs in
+  // `afterPluginsReady`, which fires *inside* loadPlugins and reads
+  // `pluginManager.getAllAccessRules()` at that moment. Registering these
+  // core rules after loadPlugins (where the router is wired up below) would
+  // miss that sync entirely, so the admin role would never be granted
+  // `pluginmanager.plugin.manage` and the install endpoints would 403 even
+  // for operators. The ids land prefixed as e.g. `pluginmanager.plugin.manage`.
+  pluginManager.registerCoreAccessRules(
+    pluginManagerMetadata.pluginId,
+    pluginManagerAccessRules,
+  );
+  pluginManager.registerCorePluginMetadata(pluginManagerMetadata);
+
   await pluginManager.loadPlugins(app, manualPlugins, {
     skipDiscovery: !!devPluginPath,
     manualPluginPaths,
@@ -785,15 +836,9 @@ const init = async () => {
   }
 
   // 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);
+  // plugin). Its access rules + metadata were registered before loadPlugins
+  // above so the auth-backend full sync picks them up; here we only wire the
+  // router now that plugin services are available.
   const pluginManagerRouter = createPluginManagerRouter({
     db,
     pluginManager,

package/src/plugin-manager.ts

@@ -24,6 +24,11 @@ import { createExtensionPointManager } from "./plugin-manager/extension-points";
 import { loadPlugins as loadPluginsImpl } from "./plugin-manager/plugin-loader";
 import { rootLogger } from "./logger";
 import type { PluginEventRecorder } from "./services/plugin-event-recorder";
+import { installBundleFromArtifacts } from "./services/plugin-installers/install-from-tarball";
+import { getPluginSchemaName } from "@checkstack/drizzle-helper";
+import { stripPublicSchemaFromMigrations } from "./utils/strip-public-schema";
+import { runPluginMigrations } from "./utils/run-plugin-migrations";
+import { createScopedDb } from "./utils/scoped-db";
 
 export interface DeregisterOptions {
   deleteSchema: boolean;
@@ -70,6 +75,14 @@ export class PluginManager {
   // and writes to here when handling broadcast install hooks.
   private runtimeDir: string | undefined;
 
+  // In-process dedupe for bundle installs: the install broadcast fans out one
+  // `pluginInstallationRequested` event PER package, so all siblings of a
+  // bundle race to install the same set of tarballs into `runtimeDir`. Keyed
+  // by bundleId, the first handler runs the single co-install and the rest
+  // await the same promise (cross-pod isolation is inherent — each pod has its
+  // own filesystem and its own map).
+  private bundleInstallLocks = new Map<string, Promise<void>>();
+
   // Resolves once `/api/:pluginId/*` is registered on the root router and
   // Phase 2 (per-plugin init) is starting. The HTTP server awaits this
   // promise to know when it is safe to stop gating incoming requests.
@@ -507,7 +520,9 @@ export class PluginManager {
 
     // Fast path: monorepo-local plugin, just load by package name / path.
     if (!row.isUninstallable) {
-      await this.loadSinglePlugin(pluginId, row.path);
+      if (row.type === "backend") {
+        await this.loadSinglePlugin(pluginId, row.path);
+      }
       return;
     }
 
@@ -519,41 +534,123 @@ export class PluginManager {
 
     const pkgDir = path.join(this.runtimeDir, "node_modules", pluginId);
     if (!fs.existsSync(path.join(pkgDir, "package.json"))) {
-      // Module not installed yet — pull from artifact store and install.
-      const artifactStore = await this.registry.get(
-        coreServices.pluginArtifactStore,
-        { pluginId: "core" },
+      // Module not installed yet — pull from the artifact store and install.
+      if (row.bundleId) {
+        // Multi-package bundle: install ALL siblings in one `bun install` so a
+        // sibling that depends on another sibling resolves from the bundled
+        // tarballs instead of 404ing against a registry (the siblings are
+        // shipped inside the bundle and are usually unpublished). Deduped per
+        // bundleId so the parallel per-package broadcast handlers cooperate.
+        await this.ensureBundleInstalled(row.bundleId);
+      } else {
+        const artifactStore = await this.registry.get(
+          coreServices.pluginArtifactStore,
+          { pluginId: "core" },
+        );
+        const artifact = await artifactStore.fetch({
+          pluginName: pluginId,
+          version: row.version,
+        });
+        if (!artifact) {
+          throw new Error(
+            `No tarball found in plugin_artifacts for ${pluginId}@${row.version}. ` +
+              `The plugin row exists but its artifact is missing — re-install from the original source.`,
+          );
+        }
+        const allowInstallScripts =
+          (row.metadata as { checkstack?: { allowInstallScripts?: boolean } })
+            ?.checkstack?.allowInstallScripts === true;
+
+        const installerRegistry = await this.registry.get(
+          coreServices.pluginInstallerRegistry,
+          { pluginId: "core" },
+        );
+        // Any installer's installFromArtifact does the same thing (delegates
+        // to the shared install-from-tarball helper) — pick npm.
+        await installerRegistry
+          .forSource("npm")
+          .installFromArtifact({
+            tarball: artifact.tarball,
+            pluginName: pluginId,
+            allowInstallScripts,
+          });
+      }
+    }
+
+    // Only BACKEND packages register as backend plugins. A bundle's `common`
+    // (a plain library) and `frontend` (served to the browser via
+    // /api/plugins) siblings still need to be installed on disk — done above —
+    // but they export no `BackendPlugin`, so loading them here would throw.
+    // This mirrors the fresh-instance bootstrap, which installs every package
+    // but only imports `type = 'backend'` rows.
+    if (row.type === "backend") {
+      await this.loadSinglePlugin(pluginId, pkgDir);
+    }
+  }
+
+  /**
+   * Install every package of a bundle into `runtimeDir` in a single
+   * `bun install`, deduped per bundleId so the N parallel per-package install
+   * broadcasts run it exactly once. Resolves when the bundle is on disk.
+   */
+  private async ensureBundleInstalled(bundleId: string): Promise<void> {
+    const inflight = this.bundleInstallLocks.get(bundleId);
+    if (inflight) return inflight;
+    const promise = this.installBundleNow(bundleId).finally(() => {
+      this.bundleInstallLocks.delete(bundleId);
+    });
+    this.bundleInstallLocks.set(bundleId, promise);
+    return promise;
+  }
+
+  private async installBundleNow(bundleId: string): Promise<void> {
+    if (!this.runtimeDir) {
+      throw new Error(
+        `Runtime plugin dir not configured — call setRuntimeDir before hydrating runtime plugins.`,
       );
+    }
+    const { plugins: pluginsTable } = await import("./schema");
+    const { eq } = await import("drizzle-orm");
+
+    const siblings = await db
+      .select()
+      .from(pluginsTable)
+      .where(eq(pluginsTable.bundleId, bundleId));
+    if (siblings.length === 0) {
+      throw new Error(`Bundle '${bundleId}' has no rows in 'plugins' table`);
+    }
+
+    const artifactStore = await this.registry.get(
+      coreServices.pluginArtifactStore,
+      { pluginId: "core" },
+    );
+    const packages: Array<{ tarball: Uint8Array; pluginName: string }> = [];
+    for (const sib of siblings) {
       const artifact = await artifactStore.fetch({
-        pluginName: pluginId,
-        version: row.version,
+        pluginName: sib.name,
+        version: sib.version,
       });
       if (!artifact) {
         throw new Error(
-          `No tarball found in plugin_artifacts for ${pluginId}@${row.version}. ` +
-            `The plugin row exists but its artifact is missing — re-install from the original source.`,
+          `No tarball found in plugin_artifacts for ${sib.name}@${sib.version} ` +
+            `(bundle ${bundleId}). Re-install from the original source.`,
         );
       }
-      const allowInstallScripts =
-        (row.metadata as { checkstack?: { allowInstallScripts?: boolean } })
-          ?.checkstack?.allowInstallScripts === true;
-
-      const installerRegistry = await this.registry.get(
-        coreServices.pluginInstallerRegistry,
-        { pluginId: "core" },
-      );
-      // Any installer's installFromArtifact does the same thing (delegates
-      // to the shared install-from-tarball helper) — pick npm.
-      await installerRegistry
-        .forSource("npm")
-        .installFromArtifact({
-          tarball: artifact.tarball,
-          pluginName: pluginId,
-          allowInstallScripts,
-        });
+      packages.push({ tarball: artifact.tarball, pluginName: sib.name });
     }
 
-    await this.loadSinglePlugin(pluginId, pkgDir);
+    // `--ignore-scripts` is all-or-nothing for one command; gate on the
+    // primary package the operator chose to trust.
+    const primary = siblings.find((s) => s.isPrimary) ?? siblings[0];
+    const allowInstallScripts =
+      (primary.metadata as { checkstack?: { allowInstallScripts?: boolean } })
+        ?.checkstack?.allowInstallScripts === true;
+
+    await installBundleFromArtifacts({
+      packages,
+      allowInstallScripts,
+      runtimeDir: this.runtimeDir,
+    });
   }
 
   /**
@@ -617,6 +714,16 @@ export class PluginManager {
                   backendPlugin.metadata
                 );
               }
+              // Inject the plugin-scoped database when a schema is declared —
+              // mirrors the full-system loader (plugin-loader Phase 2). Without
+              // this the `database` init arg is undefined and the plugin's
+              // service throws on its first query.
+              if (args.schema) {
+                resolvedDeps["database"] = createScopedDb(
+                  db,
+                  getPluginSchemaName(metaPluginId),
+                );
+              }
               await args.init(resolvedDeps as never);
             },
           });
@@ -667,6 +774,20 @@ export class PluginManager {
         },
       });
 
+      // 2.5. Run this plugin's Drizzle migrations into its isolated schema
+      // before init, so its tables exist when the service issues its first
+      // query. Mirrors the full-system loader; a runtime-installed plugin
+      // ships its `drizzle/` folder inside the package.
+      const migrationsFolder = path.join(pluginPath, "drizzle");
+      if (fs.existsSync(migrationsFolder)) {
+        stripPublicSchemaFromMigrations(migrationsFolder);
+        await runPluginMigrations({
+          pool: adminPool,
+          migrationsFolder,
+          migrationsSchema: getPluginSchemaName(metaPluginId),
+        });
+      }
+
       // 3. Initialize plugin (Phase 2)
       for (const pending of pendingInits) {
         await pending.init();

package/src/services/plugin-installers/github-installer.ts

@@ -182,7 +182,10 @@ export class GithubPluginInstaller implements PluginInstaller {
           `Bundle manifest in '${asset.name}' names primary '${bundle.manifest.primary}' but no matching sibling tarball was found.`,
         );
       }
-      return { tarball: buf, packageJson: primary.packageJson, bundle };
+      // Persist/install the primary's INNER package tarball (a plain
+      // `package/package.json` tarball), not the outer bundle archive `buf`;
+      // the bundle is exposed via `bundle` for sibling resolution only.
+      return { tarball: primary.tarball, packageJson: primary.packageJson, bundle };
     }
 
     let packageJson;

package/src/services/plugin-installers/install-from-tarball.it.test.ts

@@ -0,0 +1,122 @@
+/**
+ * Integration test for `installBundleFromArtifacts`: a bundle whose primary
+ * depends on a sibling must install WITHOUT reaching a registry — the sibling
+ * ships inside the bundle and is (deliberately) not published anywhere.
+ *
+ * The packages use a `@cstest/*` scope that exists on no registry, and the
+ * registry env is pointed at an unroutable address, so a successful install
+ * can only mean bun resolved the intra-bundle dependency from the co-provided
+ * tarball. Before the bundle-aware co-install fix, each sibling was installed
+ * via its own `bun install <one.tgz>`, which 404s on the sibling dep.
+ *
+ * Shells out to a real `bun install`, so it's gated behind `CHECKSTACK_IT=1`
+ * (the same gate as the other integration tests) to keep the default unit
+ * lane fast and network-free.
+ */
+import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import path from "node:path";
+import os from "node:os";
+import fs from "node:fs/promises";
+import { installBundleFromArtifacts } from "./install-from-tarball";
+
+async function shellTar(args: {
+  cwd: string;
+  tarPath: string;
+  entries: string[];
+}): Promise<void> {
+  const proc = Bun.spawn(["tar", "-czf", args.tarPath, ...args.entries], {
+    cwd: args.cwd,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const exitCode = await proc.exited;
+  if (exitCode !== 0) {
+    const stderr = await new Response(proc.stderr).text();
+    throw new Error(`tar exited with status ${exitCode}: ${stderr}`);
+  }
+}
+
+async function buildTarball(pkgJson: Record<string, unknown>): Promise<Uint8Array> {
+  const stage = await fs.mkdtemp(path.join(os.tmpdir(), "bundle-install-test-"));
+  try {
+    const pkgDir = path.join(stage, "package");
+    await fs.mkdir(pkgDir, { recursive: true });
+    await fs.writeFile(
+      path.join(pkgDir, "package.json"),
+      JSON.stringify(pkgJson, undefined, 2),
+    );
+    await fs.writeFile(path.join(pkgDir, "index.js"), "module.exports = {};");
+    const tarPath = path.join(stage, "out.tgz");
+    await shellTar({ cwd: stage, tarPath, entries: ["package"] });
+    return new Uint8Array(await fs.readFile(tarPath));
+  } finally {
+    await fs.rm(stage, { recursive: true, force: true });
+  }
+}
+
+describe.skipIf(!process.env.CHECKSTACK_IT)(
+  "installBundleFromArtifacts (real bun install)",
+  () => {
+    let runtimeDir: string;
+    let savedRegistry: string | undefined;
+
+    beforeAll(async () => {
+      runtimeDir = await fs.mkdtemp(path.join(os.tmpdir(), "bundle-runtime-"));
+      // Force any registry round-trip to fail fast, so a passing install
+      // proves the sibling dep resolved from the co-provided tarball.
+      savedRegistry = process.env.BUN_CONFIG_REGISTRY;
+      process.env.BUN_CONFIG_REGISTRY = "http://127.0.0.1:1/";
+    });
+
+    afterAll(async () => {
+      if (savedRegistry === undefined) delete process.env.BUN_CONFIG_REGISTRY;
+      else process.env.BUN_CONFIG_REGISTRY = savedRegistry;
+      await fs.rm(runtimeDir, { recursive: true, force: true });
+    });
+
+    it("resolves an intra-bundle sibling dependency without a registry", async () => {
+      const common = await buildTarball({
+        name: "@cstest/widget-common",
+        version: "0.0.1",
+        description: "test common",
+        author: "test",
+        license: "Elastic-2.0",
+        checkstack: { type: "common", pluginId: "widget" },
+      });
+      // The primary DEPENDS on the (unpublished) sibling — the exact shape
+      // that 404s when installed one-tarball-at-a-time.
+      const backend = await buildTarball({
+        name: "@cstest/widget-backend",
+        version: "0.0.1",
+        description: "test backend",
+        author: "test",
+        license: "Elastic-2.0",
+        dependencies: { "@cstest/widget-common": "^0.0.1" },
+        checkstack: { type: "backend", pluginId: "widget" },
+      });
+
+      const installed = await installBundleFromArtifacts({
+        packages: [
+          { tarball: common, pluginName: "@cstest/widget-common" },
+          { tarball: backend, pluginName: "@cstest/widget-backend" },
+        ],
+        runtimeDir,
+      });
+
+      expect(installed.map((i) => i.name).sort()).toEqual([
+        "@cstest/widget-backend",
+        "@cstest/widget-common",
+      ]);
+      // Both packages physically landed under the runtime dir's node_modules.
+      for (const name of ["@cstest/widget-common", "@cstest/widget-backend"]) {
+        const pkgJsonPath = path.join(
+          runtimeDir,
+          "node_modules",
+          name,
+          "package.json",
+        );
+        expect(await fs.exists(pkgJsonPath)).toBe(true);
+      }
+    }, 60_000);
+  },
+);

package/src/services/plugin-installers/install-from-tarball.ts

@@ -67,3 +67,112 @@ export async function installFromArtifact({
     await fs.rm(tmpDir, { recursive: true, force: true });
   }
 }
+
+/**
+ * Install every package of a multi-package bundle so that intra-bundle
+ * dependencies (a sibling depending on `@scope/other-sibling`) resolve from
+ * the co-shipped tarballs instead of being fetched from a registry — those
+ * siblings live inside the bundle and are typically not published anywhere.
+ *
+ * `bun install a.tgz b.tgz` does NOT make one CLI-provided tarball satisfy
+ * another's named dependency range; bun still resolves `@scope/sibling@^x`
+ * against the registry and 404s. The reliable mechanism is a throwaway
+ * manifest that lists every sibling as a `file:` dependency AND pins every
+ * sibling name in `overrides` to that same `file:` tarball, so any sibling's
+ * range is forced to the local tarball. External deps (`@checkstack/*` and
+ * their transitive deps) still resolve from the registry as normal.
+ *
+ * We install into a temp root (a manifest-driven install would PRUNE the
+ * shared runtime dir down to just this bundle), then merge the resulting
+ * `node_modules` into `runtimeDir/node_modules` additively — bun's default
+ * layout is hoisted real directories (no symlinks), so a recursive copy is a
+ * safe per-entry merge that leaves previously-installed plugins intact.
+ *
+ * `allowInstallScripts` is bundle-wide: `--ignore-scripts` is all-or-nothing
+ * for one command, so callers pass the primary package's opt-in (the package
+ * the operator chose to trust).
+ */
+export async function installBundleFromArtifacts({
+  packages,
+  allowInstallScripts,
+  runtimeDir,
+}: {
+  packages: Array<{ tarball: Uint8Array; pluginName: string }>;
+  allowInstallScripts?: boolean;
+  runtimeDir: string;
+}): Promise<InstalledArtifact[]> {
+  if (packages.length === 0) {
+    throw new Error("installBundleFromArtifacts: no packages to install");
+  }
+  await fs.mkdir(runtimeDir, { recursive: true });
+
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "checkstack-bundle-"));
+  try {
+    const stageDir = path.join(tmpDir, "stage");
+    const rootDir = path.join(tmpDir, "root");
+    await fs.mkdir(stageDir, { recursive: true });
+    await fs.mkdir(rootDir, { recursive: true });
+
+    // Stage each tarball and validate its name up front.
+    const dependencies: Record<string, string> = {};
+    const overrides: Record<string, string> = {};
+    for (const [i, pkg] of packages.entries()) {
+      const expected = await extractPackageJson(pkg.tarball);
+      if (expected.name !== pkg.pluginName) {
+        throw new Error(
+          `Tarball name mismatch: expected '${pkg.pluginName}', got '${expected.name}'`,
+        );
+      }
+      const tarPath = path.join(stageDir, `pkg-${i}.tgz`);
+      await fs.writeFile(tarPath, pkg.tarball);
+      const fileSpecifier = `file:${tarPath}`;
+      dependencies[expected.name] = fileSpecifier;
+      overrides[expected.name] = fileSpecifier;
+    }
+
+    await fs.writeFile(
+      path.join(rootDir, "package.json"),
+      JSON.stringify(
+        { name: "_checkstack-bundle-install", version: "0.0.0", dependencies, overrides },
+        undefined,
+        2,
+      ),
+    );
+
+    const ignoreScripts = allowInstallScripts ? "" : "--ignore-scripts";
+    const cmd =
+      `bun install --cwd "${rootDir}" --no-save ${ignoreScripts}`.trim();
+    rootLogger.info(`📦 Running (bundle): ${cmd}`);
+    const { stderr } = await execAsync(cmd);
+    if (stderr) rootLogger.debug(stderr);
+
+    // Merge the resolved tree into the shared runtime dir, per top-level
+    // entry, so existing plugins' node_modules entries are preserved.
+    const srcModules = path.join(rootDir, "node_modules");
+    const destModules = path.join(runtimeDir, "node_modules");
+    await fs.mkdir(destModules, { recursive: true });
+    for (const entry of await fs.readdir(srcModules)) {
+      await fs.cp(
+        path.join(srcModules, entry),
+        path.join(destModules, entry),
+        { recursive: true, force: true },
+      );
+    }
+
+    const installed: InstalledArtifact[] = [];
+    for (const pkg of packages) {
+      const pkgDir = path.join(destModules, pkg.pluginName);
+      const installedPkgJson = JSON.parse(
+        await fs.readFile(path.join(pkgDir, "package.json"), "utf8"),
+      );
+      installed.push({
+        name: installedPkgJson.name,
+        path: pkgDir,
+        version: installedPkgJson.version,
+      });
+    }
+    return installed;
+  } finally {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  }
+}

package/src/services/plugin-installers/tarball-installer.ts

@@ -41,7 +41,6 @@ export class TarballPluginInstaller implements PluginInstaller {
 
     const bundle = await tryExtractBundle(stored.tarball);
     if (bundle) {
-      // For bundles, the outer tarball's "package.json" is the primary's.
       const primary = bundle.siblings.find(
         (s) => s.packageJson.name === bundle.manifest.primary,
       );
@@ -51,8 +50,13 @@ export class TarballPluginInstaller implements PluginInstaller {
           `Bundle manifest names primary '${bundle.manifest.primary}' but no matching sibling tarball was found in the uploaded archive.`,
         );
       }
+      // `tarball` is the primary's INNER package tarball (not the outer bundle
+      // archive): it's what gets persisted as the primary's artifact and what
+      // the runtime installs, so it must be a plain `package/package.json`
+      // tarball. The outer bundle is exposed via `bundle` for sibling
+      // resolution only.
       return {
-        tarball: stored.tarball,
+        tarball: primary.tarball,
         packageJson: primary.packageJson,
         bundle,
       };