@arcote.tech/arc-cli 0.7.25 → 0.7.26

package/dist/index.js

@@ -34512,6 +34512,7 @@ import {
   writeFileSync as writeFileSync6
 } from "fs";
 import { basename as basename2, dirname as dirname6, join as join8, relative as relative3 } from "path";
+import { builtinModules } from "module";
 init_i18n();
 init_compile();
 
@@ -34712,14 +34713,54 @@ function singleReactPlugin(rootDir) {
     }
   };
 }
-function serverExternalsPlugin() {
+var BUILTIN_SET = new Set(builtinModules);
+function pkgNameOf(spec) {
+  if (spec.startsWith("@"))
+    return spec.split("/").slice(0, 2).join("/");
+  return spec.split("/")[0];
+}
+function isBuiltinSpec(spec) {
+  if (spec.startsWith("node:") || spec.startsWith("bun:") || spec === "bun")
+    return true;
+  return BUILTIN_SET.has(spec) || BUILTIN_SET.has(pkgNameOf(spec));
+}
+function versionFromImporter(importer, name) {
+  let dir = importer ? dirname6(importer) : "";
+  while (dir && dir !== dirname6(dir)) {
+    const pj = join8(dir, "package.json");
+    if (existsSync7(pj)) {
+      try {
+        const json = JSON.parse(readFileSync7(pj, "utf-8"));
+        const spec = json.dependencies?.[name] ?? json.peerDependencies?.[name] ?? json.devDependencies?.[name];
+        if (typeof spec === "string")
+          return spec;
+      } catch {}
+    }
+    dir = dirname6(dir);
+  }
+  return;
+}
+function npmExternalsPlugin(workspaceNames, recorded) {
   return {
-    name: "server-externals",
+    name: "npm-externals",
     setup(build2) {
-      build2.onResolve({ filter: /^(@aws-sdk|@smithy)\// }, (args) => ({
-        path: args.path,
-        external: true
-      }));
+      build2.onResolve({ filter: /^[^./]/ }, (args) => {
+        if (isBuiltinSpec(args.path)) {
+          return { path: args.path, external: true };
+        }
+        const name = pkgNameOf(args.path);
+        if (workspaceNames.has(name))
+          return null;
+        if (name.startsWith("@arcote.tech/") && !FRAMEWORK_PEER_SET.has(name)) {
+          return null;
+        }
+        const version = versionFromImporter(args.importer, name);
+        if (version?.startsWith("workspace:"))
+          return null;
+        if (!recorded.has(name))
+          recorded.set(name, version);
+        return { path: args.path, external: true };
+      });
     }
   };
 }
@@ -34758,6 +34799,7 @@ var CONTEXT_CLIENTS = [
 ];
 var SERVER_DEFINES = { ONLY_SERVER: "true", ONLY_BROWSER: "false", ONLY_CLIENT: "false" };
 var SERVER_ENTRY_FILE = "_server.js";
+var SERVER_EXTERNALS_FILE = "_externals.json";
 function discoverPackages(rootDir) {
   const rootPkg = JSON.parse(readFileSync7(join8(rootDir, "package.json"), "utf-8"));
   const workspaceGlobs = rootPkg.workspaces ?? [];
@@ -34944,9 +34986,14 @@ async function buildServerApp(rootDir, serverDir, packages, cache, noCache) {
     defines: SERVER_DEFINES
   });
   const entryFileAbs = join8(serverDir, SERVER_ENTRY_FILE);
+  const externalsFileAbs = join8(serverDir, SERVER_EXTERNALS_FILE);
   if (!noCache && isCacheHit(cache, unitId, inputHash, [entryFileAbs])) {
     console.log(`  \u2713 cached: ${unitId}`);
-    return { entryFile: SERVER_ENTRY_FILE, cached: true };
+    return {
+      entryFile: SERVER_ENTRY_FILE,
+      cached: true,
+      externals: readServerExternals(externalsFileAbs)
+    };
   }
   console.log(`  building: ${unitId} (${contexts.length} server modules)`);
   for (const f of readdirSync4(serverDir)) {
@@ -34959,6 +35006,7 @@ async function buildServerApp(rootDir, serverDir, packages, cache, noCache) {
   writeFileSync6(entrySrc, contexts.map((p) => `import "${p.name}";`).join(`
 `) + `
 `);
+  const recorded = new Map;
   let result;
   try {
     result = await Bun.build({
@@ -34971,8 +35019,8 @@ async function buildServerApp(rootDir, serverDir, packages, cache, noCache) {
       external,
       plugins: [
         jsxDevShimPlugin(),
-        serverExternalsPlugin(),
-        workspaceSourcePlugin(srcByName)
+        workspaceSourcePlugin(srcByName),
+        npmExternalsPlugin(new Set(srcByName.keys()), recorded)
       ],
       define: SERVER_DEFINES
     });
@@ -34991,9 +35039,22 @@ async function buildServerApp(rootDir, serverDir, packages, cache, noCache) {
   if (basename2(entryOut.path) !== SERVER_ENTRY_FILE) {
     throw new Error(`Server app build: unexpected entry name ${basename2(entryOut.path)} (wanted ${SERVER_ENTRY_FILE})`);
   }
+  const externals = [...recorded].filter(([name]) => !FRAMEWORK_PEER_SET.has(name)).map(([name, version]) => ({ name, version })).sort((a, b) => a.name.localeCompare(b.name));
+  writeFileSync6(externalsFileAbs, JSON.stringify(externals, null, 2) + `
+`);
   const outputHash = sha256OfDir(serverDir);
   updateCache(cache, unitId, inputHash, { outputHash });
-  return { entryFile: SERVER_ENTRY_FILE, cached: false };
+  return { entryFile: SERVER_ENTRY_FILE, cached: false, externals };
+}
+function readServerExternals(path4) {
+  if (!existsSync7(path4))
+    return [];
+  try {
+    const parsed = JSON.parse(readFileSync7(path4, "utf-8"));
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
 }
 async function buildBrowserApp(rootDir, outDir, plan, cache, noCache, i18nCollector) {
   mkdirSync6(outDir, { recursive: true });
@@ -35476,9 +35537,10 @@ import { createHash } from "crypto";
 import { existsSync as existsSync9, mkdirSync as mkdirSync8, readFileSync as readFileSync10, writeFileSync as writeFileSync8 } from "fs";
 import { basename as basename4, dirname as dirname7, join as join11 } from "path";
 import { fileURLToPath as fileURLToPath6 } from "url";
-function collectFrameworkDeps(arcDir, rootDir, packages, sharedDeps = []) {
+function collectFrameworkDeps(arcDir, rootDir, packages, sharedDeps = [], serverExternals = []) {
   mkdirSync8(arcDir, { recursive: true });
   const versions = resolveFrameworkVersions(rootDir, packages);
+  mergeServerExternals(versions, rootDir, packages, serverExternals);
   for (const { name, version } of sharedDeps) {
     versions[name] = version;
   }
@@ -35529,18 +35591,10 @@ function resolveFrameworkVersions(rootDir, packages) {
   const required = new Set(FRAMEWORK_PEERS);
   for (const pkg of packages) {
     const peers = pkg.packageJson.peerDependencies ?? {};
-    const deps = pkg.packageJson.dependencies ?? {};
     for (const name of Object.keys(peers)) {
       if (name.startsWith("@arcote.tech/"))
         required.add(name);
     }
-    for (const [name, spec] of Object.entries(deps)) {
-      if (spec.startsWith("workspace:"))
-        continue;
-      if (name.startsWith("@arcote.tech/") || !isFrameworkExternal(name))
-        continue;
-      required.add(name);
-    }
   }
   const out = {};
   for (const name of required) {
@@ -35549,20 +35603,28 @@ function resolveFrameworkVersions(rootDir, packages) {
       out[name] = rootSpec;
       continue;
     }
-    let found;
-    for (const pkg of packages) {
-      const spec = (pkg.packageJson.dependencies ?? {})[name] ?? (pkg.packageJson.peerDependencies ?? {})[name];
-      if (spec) {
-        found = spec;
-        break;
-      }
-    }
-    out[name] = found ?? "*";
+    out[name] = findWorkspaceSpec(packages, name) ?? "*";
   }
   return out;
 }
-function isFrameworkExternal(_name) {
-  return true;
+function findWorkspaceSpec(packages, name) {
+  for (const pkg of packages) {
+    const spec = (pkg.packageJson.dependencies ?? {})[name] ?? (pkg.packageJson.peerDependencies ?? {})[name];
+    if (spec)
+      return spec;
+  }
+  return;
+}
+function mergeServerExternals(versions, rootDir, packages, externals) {
+  const rootPkg = JSON.parse(readFileSync10(join11(rootDir, "package.json"), "utf-8"));
+  const rootDeps = rootPkg.dependencies ?? {};
+  const rootDevDeps = rootPkg.devDependencies ?? {};
+  for (const { name, version } of externals) {
+    if (versions[name])
+      continue;
+    const installed = readInstalledVersion(rootDir, name);
+    versions[name] = rootDeps[name] ?? rootDevDeps[name] ?? version ?? findWorkspaceSpec(packages, name) ?? (installed ? `^${installed}` : "*");
+  }
 }
 
 // src/platform/shared.ts
@@ -35631,7 +35693,7 @@ async function buildAll(ws, opts = {}) {
   assertOneModulePerPackage(ws.packages);
   await buildContextPackages(ws.rootDir, ws.packages, cache, noCache);
   const serverDir = join12(ws.arcDir, "server");
-  const { entryFile: serverEntry } = await buildServerApp(ws.rootDir, serverDir, ws.packages, cache, noCache);
+  const { entryFile: serverEntry, externals: serverExternals } = await buildServerApp(ws.rootDir, serverDir, ws.packages, cache, noCache);
   const accessMap = await extractAccessMap(ws.rootDir, join12(serverDir, serverEntry));
   mkdirSync9(ws.arcDir, { recursive: true });
   writeFileSync9(join12(ws.arcDir, "access.json"), JSON.stringify(accessMap, null, 2) + `
@@ -35647,7 +35709,7 @@ async function buildAll(ws, opts = {}) {
   ]);
   const { finalizeTranslations: finalizeTranslations3 } = await Promise.resolve().then(() => (init_i18n(), exports_i18n));
   await finalizeTranslations3(ws.rootDir, ws.arcDir, i18nCollector);
-  collectFrameworkDeps(ws.arcDir, ws.rootDir, ws.packages);
+  collectFrameworkDeps(ws.arcDir, ws.rootDir, ws.packages, [], serverExternals);
   saveBuildCache(ws.arcDir, cache);
   const finalManifest = assembleManifest(ws, browserResult, cache);
   writeFileSync9(join12(ws.arcDir, "manifest.json"), JSON.stringify(finalManifest, null, 2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcote.tech/arc-cli",
-  "version": "0.7.25",
+  "version": "0.7.26",
   "description": "CLI tool for Arc framework",
   "module": "index.ts",
   "main": "dist/index.js",
@@ -12,13 +12,13 @@
     "build": "bun build --target=bun ./src/index.ts --outdir=dist --external @arcote.tech/arc --external @arcote.tech/arc-ds --external @arcote.tech/arc-react --external @arcote.tech/platform --external '@opentelemetry/*' && chmod +x dist/index.js"
   },
   "dependencies": {
-    "@arcote.tech/arc": "^0.7.25",
-    "@arcote.tech/arc-ds": "^0.7.25",
-    "@arcote.tech/arc-react": "^0.7.25",
-    "@arcote.tech/arc-host": "^0.7.25",
-    "@arcote.tech/arc-adapter-db-sqlite": "^0.7.25",
-    "@arcote.tech/arc-adapter-db-postgres": "^0.7.25",
-    "@arcote.tech/arc-otel": "^0.7.25",
+    "@arcote.tech/arc": "^0.7.26",
+    "@arcote.tech/arc-ds": "^0.7.26",
+    "@arcote.tech/arc-react": "^0.7.26",
+    "@arcote.tech/arc-host": "^0.7.26",
+    "@arcote.tech/arc-adapter-db-sqlite": "^0.7.26",
+    "@arcote.tech/arc-adapter-db-postgres": "^0.7.26",
+    "@arcote.tech/arc-otel": "^0.7.26",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/api-logs": "^0.57.0",
     "@opentelemetry/core": "^1.30.0",
@@ -31,7 +31,7 @@
     "@opentelemetry/sdk-trace-base": "^1.30.0",
     "@opentelemetry/sdk-trace-node": "^1.30.0",
     "@opentelemetry/semantic-conventions": "^1.27.0",
-    "@arcote.tech/platform": "^0.7.25",
+    "@arcote.tech/platform": "^0.7.26",
     "@clack/prompts": "^0.9.0",
     "commander": "^11.1.0",
     "chokidar": "^3.5.3",

package/src/builder/dependency-collector.ts

@@ -3,7 +3,8 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { basename, dirname, join } from "path";
 import { fileURLToPath } from "node:url";
 import { FRAMEWORK_PEERS, FRAMEWORK_PEER_SET } from "./framework-peers";
-import type { WorkspacePackage } from "./module-builder";
+import { readInstalledVersion } from "./hash";
+import type { ServerExternal, WorkspacePackage } from "./module-builder";
 
 export { FRAMEWORK_PEERS };
 
@@ -37,10 +38,17 @@ export function collectFrameworkDeps(
   rootDir: string,
   packages: WorkspacePackage[],
   sharedDeps: ReadonlyArray<{ name: string; version: string }> = [],
+  serverExternals: ReadonlyArray<ServerExternal> = [],
 ): CollectedDeps {
   mkdirSync(arcDir, { recursive: true });
 
   const versions = resolveFrameworkVersions(rootDir, packages);
+  // npm packages the server bundle left external — the runtime image must
+  // install them into /app/node_modules. This is the ONLY source for deps
+  // reached through a fragment the consumer never declares (e.g.
+  // `@arcote.tech/arc-files` → `@aws-sdk/client-s3`): the bundle records what
+  // it actually externalized, so the manifest tracks real usage, no whitelist.
+  mergeServerExternals(versions, rootDir, packages, serverExternals);
   // Shared deps (discovered across ≥ 2 workspace packages) join the framework
   // in the global manifest — installed once into <arcDir>/node_modules/ and
   // served via the shell so each module's browser bundle leaves them external.
@@ -178,12 +186,13 @@ function resolveFrameworkVersions(
   packages: WorkspacePackage[],
 ): Record<string, string> {
   // The framework manifest installs into /app/node_modules in the deploy
-  // image. It needs to cover:
+  // image. resolveFrameworkVersions covers the singleton @arcote.tech/* set:
   //   1. Static framework peers (FRAMEWORK_PEERS) — always present
   //   2. User-extension @arcote.tech/* peers (e.g. arc-ai-openai) declared
   //      as peerDeps on user context packages
-  //   3. npm runtime deps that server bundles leave external (non-workspace
-  //      deps not yet bundled inline)
+  // Plain npm runtime deps the server bundle leaves external are added
+  // separately by mergeServerExternals (driven by what the bundle actually
+  // externalized, not by what workspace packages happen to declare).
   // Resolution order for each: root package.json wins, then any workspace
   // package's deps/peerDeps, then "*" as last resort.
   const rootPkg = JSON.parse(
@@ -196,18 +205,10 @@ function resolveFrameworkVersions(
   const required = new Set<string>(FRAMEWORK_PEERS);
   for (const pkg of packages) {
     const peers = pkg.packageJson.peerDependencies ?? {};
-    const deps = (pkg.packageJson.dependencies ?? {}) as Record<string, string>;
     // Any @arcote.tech/* peer beyond the static list (e.g. arc-ai adapters).
     for (const name of Object.keys(peers)) {
       if (name.startsWith("@arcote.tech/")) required.add(name);
     }
-    // npm deps (non-workspace) — server bundles leave them external, so the
-    // image needs them in /app/node_modules.
-    for (const [name, spec] of Object.entries(deps)) {
-      if (spec.startsWith("workspace:")) continue;
-      if (name.startsWith("@arcote.tech/") || !isFrameworkExternal(name)) continue;
-      required.add(name);
-    }
   }
 
   const out: Record<string, string> = {};
@@ -217,32 +218,58 @@ function resolveFrameworkVersions(
       out[name] = rootSpec;
       continue;
     }
-    let found: string | undefined;
-    for (const pkg of packages) {
-      const spec =
-        (pkg.packageJson.dependencies ?? {})[name] ??
-        (pkg.packageJson.peerDependencies ?? {})[name];
-      if (spec) {
-        found = spec;
-        break;
-      }
-    }
-    out[name] = found ?? "*";
+    out[name] = findWorkspaceSpec(packages, name) ?? "*";
   }
   return out;
 }
 
+/** Version spec for `name` declared by any workspace package, if any. */
+function findWorkspaceSpec(
+  packages: WorkspacePackage[],
+  name: string,
+): string | undefined {
+  for (const pkg of packages) {
+    const spec =
+      (pkg.packageJson.dependencies ?? {})[name] ??
+      (pkg.packageJson.peerDependencies ?? {})[name];
+    if (spec) return spec;
+  }
+  return undefined;
+}
+
 /**
- * True if a non-arc npm dep is one the image must install globally for
- * runtime resolution. Today we include everything that user context packages
- * declare as deps but isn't `workspace:` — server bundles leave them external
- * so they MUST be present in /app/node_modules.
- *
- * Future optimization: bundle these inline into the server bundle to avoid
- * the install layer entirely. Left as a follow-up.
+ * Add server-bundle externals to the install manifest. For each, resolve a
+ * version spec by cascade so the image installs something compatible even when
+ * the consumer never declared the dep:
+ *   1. consumer root deps/devDeps   (their explicit pin — wins)
+ *   2. spec recorded from the importing package (e.g. arc-files peerDeps)
+ *   3. any workspace package's declaration
+ *   4. the version actually installed in node_modules (caret-ranged)
+ *   5. "*" as last resort
+ * Already-resolved names (framework peers) are left untouched.
  */
-function isFrameworkExternal(_name: string): boolean {
-  return true;
+function mergeServerExternals(
+  versions: Record<string, string>,
+  rootDir: string,
+  packages: WorkspacePackage[],
+  externals: ReadonlyArray<ServerExternal>,
+): void {
+  const rootPkg = JSON.parse(
+    readFileSync(join(rootDir, "package.json"), "utf-8"),
+  );
+  const rootDeps = (rootPkg.dependencies ?? {}) as Record<string, string>;
+  const rootDevDeps = (rootPkg.devDependencies ?? {}) as Record<string, string>;
+
+  for (const { name, version } of externals) {
+    if (versions[name]) continue;
+    const installed = readInstalledVersion(rootDir, name);
+    versions[name] =
+      rootDeps[name] ??
+      rootDevDeps[name] ??
+      version ??
+      findWorkspaceSpec(packages, name) ??
+      (installed ? `^${installed}` : "*");
+  }
 }
 
 function sha256OfFiles(paths: string[]): string {

package/src/builder/module-builder.ts

@@ -8,6 +8,7 @@ import {
   writeFileSync,
 } from "fs";
 import { basename, dirname, join, relative } from "path";
+import { builtinModules } from "node:module";
 import type { BuildManifest, ModuleDescriptor } from "@arcote.tech/platform";
 import { buildTypeDeclarations } from "../utils/build";
 import { i18nExtractPlugin, finalizeTranslations } from "../i18n";
@@ -18,7 +19,11 @@ import {
   type BuildCache,
 } from "./build-cache";
 import type { ChunkPlan } from "./chunk-planner";
-import { SHELL_EXTERNALS, FRAMEWORK_PEERS } from "./framework-peers";
+import {
+  SHELL_EXTERNALS,
+  FRAMEWORK_PEERS,
+  FRAMEWORK_PEER_SET,
+} from "./framework-peers";
 import {
   readInstalledVersion,
   sha256Hex,
@@ -97,30 +102,101 @@ function singleReactPlugin(rootDir: string): import("bun").BunPlugin {
   };
 }
 
+/** One external the server bundle leaves for the deploy image to install. */
+export interface ServerExternal {
+  /** Package name (subpath stripped): `@aws-sdk/client-s3`, `react`, … */
+  readonly name: string;
+  /** Version spec read from the importing package's package.json, if found. */
+  readonly version?: string;
+}
+
+const BUILTIN_SET = new Set<string>(builtinModules);
+
+/** Package name from a bare specifier, dropping any subpath. */
+function pkgNameOf(spec: string): string {
+  if (spec.startsWith("@")) return spec.split("/").slice(0, 2).join("/");
+  return spec.split("/")[0];
+}
+
+/** node:/bun: builtins — external by `target: "bun"`, never installed. */
+function isBuiltinSpec(spec: string): boolean {
+  if (spec.startsWith("node:") || spec.startsWith("bun:") || spec === "bun")
+    return true;
+  return BUILTIN_SET.has(spec) || BUILTIN_SET.has(pkgNameOf(spec));
+}
+
 /**
- * Marks heavy server-side packages as external. Bun.build's `external: string[]`
- * accepts only literal package names — wildcard like `@aws-sdk/*` is treated
- * verbatim and doesn't match anything. This plugin uses `onResolve` regex to
- * catch any subpackage matching the prefix and marks it external.
- *
- * Removes ~10-15 MB of AWS SDK v3 from every server bundle that transitively
- * pulls `@arcote.tech/arc-files` (e.g. `@ndt/content` was 340 MB before).
+ * Best-effort version spec for `name` as declared by the package that imports
+ * it. Walks up from the importer to the nearest package.json that lists `name`
+ * in deps/peerDeps/devDeps — e.g. `@aws-sdk/client-s3` resolves to the
+ * `^3.x` spec in `@arcote.tech/arc-files`'s peerDependencies. The collector
+ * falls back to root deps / installed version when this returns undefined.
+ */
+function versionFromImporter(importer: string, name: string): string | undefined {
+  let dir = importer ? dirname(importer) : "";
+  while (dir && dir !== dirname(dir)) {
+    const pj = join(dir, "package.json");
+    if (existsSync(pj)) {
+      try {
+        const json = JSON.parse(readFileSync(pj, "utf-8"));
+        const spec =
+          json.dependencies?.[name] ??
+          json.peerDependencies?.[name] ??
+          json.devDependencies?.[name];
+        if (typeof spec === "string") return spec;
+      } catch {
+        // unreadable package.json — keep walking
+      }
+    }
+    dir = dirname(dir);
+  }
+  return undefined;
+}
+
+/**
+ * Structural externalization for the combined server bundle: inline only
+ * first-party code (workspace `@ndt/*` source — handled earlier by
+ * `workspaceSourcePlugin` — plus non-peer `@arcote.tech/*` fragments like
+ * `arc-files`), and leave EVERY third-party npm package external. The deploy
+ * image installs externals into `/app/node_modules` anyway, so inlining them
+ * only bloats the bundle. Replaces the old hardcoded `@aws-sdk|@smithy` regex
+ * (a band-aid from the 1.1 GB nested-dist era, since fixed by the single
+ * source-based build) — no package-name whitelist to keep in sync.
  *
- * Runtime requirement: each external package must be available in
- * `node_modules/` at server startup (Bun resolves bare specifiers). Consumer
- * apps declare them in root `package.json` dependencies.
+ * Records each externalized package + the version spec of the package that
+ * imports it, so `collectFrameworkDeps` can emit them into the install
+ * manifest. This is what closes the gap for deps reached through a fragment
+ * the consumer never declares (arc-files → aws-sdk).
  */
-function serverExternalsPlugin(): import("bun").BunPlugin {
+function npmExternalsPlugin(
+  workspaceNames: ReadonlySet<string>,
+  recorded: Map<string, string | undefined>,
+): import("bun").BunPlugin {
   return {
-    name: "server-externals",
+    name: "npm-externals",
     setup(build) {
-      // @aws-sdk/* and @smithy/* — full AWS SDK v3 + low-level signing/HTTP
-      // primitives it depends on. Add more prefixes here if other heavy
-      // server-only libs appear (e.g. `@google-cloud/*`).
-      build.onResolve({ filter: /^(@aws-sdk|@smithy)\// }, (args) => ({
-        path: args.path,
-        external: true,
-      }));
+      // Bare specifiers only. An exact workspace name (`@ndt/foo`) is resolved
+      // to source earlier by workspaceSourcePlugin and never reaches here; a
+      // workspace SUBPATH (`@ndt/foo/bar`) does, and must NOT be externalized.
+      build.onResolve({ filter: /^[^./]/ }, (args) => {
+        if (isBuiltinSpec(args.path)) {
+          return { path: args.path, external: true };
+        }
+        const name = pkgNameOf(args.path);
+        // First-party workspace package (subpath import) — let Bun resolve and
+        // inline it; `workspace:*` is not installable from npm.
+        if (workspaceNames.has(name)) return null;
+        // First-party non-peer fragments inline from source/dist so
+        // SERVER_DEFINES (ONLY_SERVER…) apply and import cycles stay safe.
+        if (name.startsWith("@arcote.tech/") && !FRAMEWORK_PEER_SET.has(name)) {
+          return null;
+        }
+        const version = versionFromImporter(args.importer, name);
+        // Defensive: any `workspace:` dep is first-party — never externalize it.
+        if (version?.startsWith("workspace:")) return null;
+        if (!recorded.has(name)) recorded.set(name, version);
+        return { path: args.path, external: true };
+      });
     },
   };
 }
@@ -201,6 +277,11 @@ const SERVER_DEFINES = { ONLY_SERVER: "true", ONLY_BROWSER: "false", ONLY_CLIENT
  *  auto-emitted `chunk-<hash>.js` siblings are pulled in transitively. */
 export const SERVER_ENTRY_FILE = "_server.js";
 
+/** Sidecar listing third-party packages the server bundle left external.
+ *  Written next to the bundle so a cached rebuild can still feed the install
+ *  manifest (collectFrameworkDeps) without re-running Bun.build. */
+export const SERVER_EXTERNALS_FILE = "_externals.json";
+
 export interface WorkspacePackage {
   name: string;
   path: string;
@@ -502,6 +583,12 @@ export async function buildContextPackages(
 export interface ServerAppResult {
   readonly entryFile: string;
   readonly cached: boolean;
+  /**
+   * Third-party npm packages the bundle left external — the deploy image must
+   * install exactly these. Fed to `collectFrameworkDeps`. Empty on a cache hit
+   * (the manifest from the cached build is already on disk).
+   */
+  readonly externals: ReadonlyArray<ServerExternal>;
 }
 
 export async function buildServerApp(
@@ -548,9 +635,17 @@ export async function buildServerApp(
   });
 
   const entryFileAbs = join(serverDir, SERVER_ENTRY_FILE);
+  const externalsFileAbs = join(serverDir, SERVER_EXTERNALS_FILE);
   if (!noCache && isCacheHit(cache, unitId, inputHash, [entryFileAbs])) {
     console.log(`  ✓ cached: ${unitId}`);
-    return { entryFile: SERVER_ENTRY_FILE, cached: true };
+    // collectFrameworkDeps runs every build (uncached) and needs the external
+    // set to build the install manifest — reload it from the sidecar written
+    // by the last real build so a cache hit doesn't drop deps from the manifest.
+    return {
+      entryFile: SERVER_ENTRY_FILE,
+      cached: true,
+      externals: readServerExternals(externalsFileAbs),
+    };
   }
 
   console.log(`  building: ${unitId} (${contexts.length} server modules)`);
@@ -571,6 +666,10 @@ export async function buildServerApp(
     contexts.map((p) => `import "${p.name}";`).join("\n") + "\n",
   );
 
+  // npmExternalsPlugin records every third-party package it leaves external,
+  // plus the version spec of whatever imports it (best-effort).
+  const recorded = new Map<string, string | undefined>();
+
   let result;
   try {
     result = await Bun.build({
@@ -586,8 +685,11 @@ export async function buildServerApp(
       external,
       plugins: [
         jsxDevShimPlugin(),
-        serverExternalsPlugin(),
+        // workspaceSourcePlugin MUST precede npmExternalsPlugin: the first
+        // onResolve to return a result wins, so `@ndt/*` source is pinned
+        // before the catch-all externalizer can mark it external.
         workspaceSourcePlugin(srcByName),
+        npmExternalsPlugin(new Set(srcByName.keys()), recorded),
       ],
       define: SERVER_DEFINES,
     });
@@ -610,9 +712,28 @@ export async function buildServerApp(
     );
   }
 
+  // Third-party externals only — framework peers carry their own resolution in
+  // collectFrameworkDeps, so drop them here to avoid double-sourcing versions.
+  const externals: ServerExternal[] = [...recorded]
+    .filter(([name]) => !FRAMEWORK_PEER_SET.has(name))
+    .map(([name, version]) => ({ name, version }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+  writeFileSync(externalsFileAbs, JSON.stringify(externals, null, 2) + "\n");
+
   const outputHash = sha256OfDir(serverDir);
   updateCache(cache, unitId, inputHash, { outputHash });
-  return { entryFile: SERVER_ENTRY_FILE, cached: false };
+  return { entryFile: SERVER_ENTRY_FILE, cached: false, externals };
+}
+
+/** Read the externals sidecar written by the last real server build. */
+function readServerExternals(path: string): ServerExternal[] {
+  if (!existsSync(path)) return [];
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf-8"));
+    return Array.isArray(parsed) ? (parsed as ServerExternal[]) : [];
+  } catch {
+    return [];
+  }
 }
 
 

package/src/platform/shared.ts

@@ -172,13 +172,8 @@ export async function buildAll(
   // into multi-hundred-MB files. The deploy image COPYs this dir wholesale;
   // loadServerContext + the access extractor import the entry, chunks ride along.
   const serverDir = join(ws.arcDir, "server");
-  const { entryFile: serverEntry } = await buildServerApp(
-    ws.rootDir,
-    serverDir,
-    ws.packages,
-    cache,
-    noCache,
-  );
+  const { entryFile: serverEntry, externals: serverExternals } =
+    await buildServerApp(ws.rootDir, serverDir, ws.packages, cache, noCache);
 
   // Phase 2 — extract access metadata (token name + hasCheck per module) in
   // an isolated subprocess that imports the combined server bundle. MUST run
@@ -223,7 +218,7 @@ export async function buildAll(
   // Phase 5 — framework peer manifest at `<arcDir>/package.json`. Used by
   // the deploy image build (single `bun install` for all peers, one copy
   // shared across module bundles).
-  collectFrameworkDeps(ws.arcDir, ws.rootDir, ws.packages);
+  collectFrameworkDeps(ws.arcDir, ws.rootDir, ws.packages, [], serverExternals);
 
   saveBuildCache(ws.arcDir, cache);