Skip to content

Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.

perf(build): stop unpacking node_modules wholesale from the Windows asar (#5877)

Tyler7e01d33f0eeb
diff --git a/apps/desktop/src/wsl/DesktopWslEnvironment.ts b/apps/desktop/src/wsl/DesktopWslEnvironment.ts
index c6c274d85..164117727 100644
--- a/apps/desktop/src/wsl/DesktopWslEnvironment.ts
+++ b/apps/desktop/src/wsl/DesktopWslEnvironment.ts
@@ -229,15 +229,18 @@ const NODE_PTY_PROBE_SCRIPT = (
printf 'nodeVersion:%s\\n' "$(node -p 'process.versions.node' 2>/dev/null)"
printf 'resolvedPath:%s\\n' "$PATH"
cd ${shellQuote(linuxServerDir)} && node <<'NODE' >/dev/null 2>&1
-// The server bundle externalizes its deps to node_modules, and the WSL Node
-// can't read inside app.asar, so confirm those deps are unpacked on the real
-// filesystem before reporting the backend healthy. "effect" is the framework
-// every server module imports; resolving it validates the whole node_modules
-// tree. Exit 3 marks this distinct from a node-pty problem so the caller can
-// report it accurately instead of letting the server crash on
-// ERR_MODULE_NOT_FOUND at launch (which, in wsl-only mode, would just fail to
-// launch with no fallback).
-try { require.resolve("effect"); } catch (_e) { process.exit(3); }
+// The WSL Node can't read inside app.asar, so confirm what the server needs is
+// unpacked on the real filesystem before reporting the backend healthy. Exit 3
+// marks this distinct from a node-pty prebuild problem so the caller can report
+// it accurately instead of letting the server crash on ERR_MODULE_NOT_FOUND at
+// launch (which, in wsl-only mode, would just fail to launch with no fallback).
+//
+// The sentinel must be a package the CLI bundle leaves external. It used to be
+// "effect", back when the bundle externalized its runtime deps and the whole
+// node_modules tree was unpacked. The bundle now inlines its JS dependencies,
+// so "effect" no longer exists on disk and only the native packages do —
+// resolving node-pty is what actually validates the unpacked tree.
+try { require.resolve("node-pty/package.json"); } catch (_e) { process.exit(3); }
const fs = require("node:fs");
const path = require("node:path");
const pkgDir = path.dirname(require.resolve("node-pty/package.json"));
@@ -462,16 +465,17 @@ const ensureNodePtyImpl = (
} as const;
}
- // Server dependencies (e.g. "effect") couldn't be resolved on the WSL
- // filesystem — a packaging regression, since the server bundle needs its
- // node_modules unpacked from the asar. Fatal so wsl-only mode falls back to
- // Windows and dual mode surfaces the reason inline, instead of the server
- // crash-looping on ERR_MODULE_NOT_FOUND once it actually launches.
+ // The packages the server bundle leaves external (node-pty and the other
+ // native addons) couldn't be resolved on the WSL filesystem — a packaging
+ // regression, since those must be unpacked from the asar. Fatal so wsl-only
+ // mode falls back to Windows and dual mode surfaces the reason inline,
+ // instead of the server crash-looping on ERR_MODULE_NOT_FOUND once it
+ // actually launches.
if (probe.exitCode === 3) {
return {
ok: false,
reason:
- "WSL server dependencies could not be loaded (for example \"effect\"). The server's bundled node_modules is not readable by the WSL distro's Node — this is a packaging problem with this build. Please report it.",
+ 'WSL server dependencies could not be loaded (for example "node-pty"). The native packages the server needs are not unpacked where the WSL distro\'s Node can read them — this is a packaging problem with this build. Please report it.',
fatal: true,
} as const;
}
diff --git a/apps/server/vite.config.ts b/apps/server/vite.config.ts
index 521654f32..647af2a88 100644
--- a/apps/server/vite.config.ts
+++ b/apps/server/vite.config.ts
@@ -5,16 +5,20 @@ import baseConfig from "../../vite.config.ts";
import { loadRepoEnv } from "../../scripts/lib/public-config.ts";
import packageJson from "./package.json" with { type: "json" };
-const bundledPackagePrefixes = [
- "@pierre/diffs",
- "@t3tools/",
- "effect-acp",
- "effect-codex-app-server",
-];
+// The bundle used to inline only workspace packages, leaving every third-party
+// runtime dep external. External deps must exist on the real filesystem (the WSL
+// backend runs plain `wsl.exe -- node`, which cannot read inside an asar), so the
+// desktop build unpacked `**\/node_modules\/**` wholesale: 13,875 loose files to
+// support 20 native binaries. NSIS install time tracks file count, not bytes.
+//
+// Inverted here — bundle everything except the packages that genuinely cannot be
+// inlined. See scripts/lib/cli-external-packages.ts for what earns an exemption.
+import {
+ isExternalCliDependency,
+ shouldBundleCliDependency,
+} from "../../scripts/lib/cli-external-packages.ts";
-export function shouldBundleCliDependency(id: string): boolean {
- return bundledPackagePrefixes.some((prefix) => id.startsWith(prefix));
-}
+export { shouldBundleCliDependency };
const repoEnv = loadRepoEnv();
const cliBuildChannel = packageJson.version.includes("-nightly.") ? "nightly" : "latest";
@@ -37,7 +41,14 @@ export default mergeConfig(
sourcemap: true,
clean: true,
deps: {
+ // Both halves are required. `alwaysBundle` forces the JS dependencies in
+ // (declared deps are external by default, which is what this change is
+ // undoing). `neverBundle` forces the native packages out: returning
+ // false from `alwaysBundle` only means "no opinion", so a transitive
+ // dependency would still be bundled — which silently inlined
+ // msgpackr-extract and its loader, losing native acceleration.
alwaysBundle: shouldBundleCliDependency,
+ neverBundle: (id: string) => isExternalCliDependency(id),
onlyBundle: false,
},
banner: {
diff --git a/scripts/build-desktop-artifact.test.ts b/scripts/build-desktop-artifact.test.ts
index 7d2b7410a..6b04d6587 100644
--- a/scripts/build-desktop-artifact.test.ts
+++ b/scripts/build-desktop-artifact.test.ts
@@ -1,6 +1,8 @@
import * as NodeServices from "@effect/platform-node/NodeServices";
import { assert, it } from "@effect/vitest";
import * as ConfigProvider from "effect/ConfigProvider";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
@@ -43,6 +45,8 @@ import {
stageLinuxIconSize,
STAGE_INSTALL_ARGS,
WINDOWS_ASAR_UNPACK,
+ ancestorNodeModulesPaths,
+ copyDirectoryPreservingSymlinks,
} from "./build-desktop-artifact.ts";
import { BRAND_ASSET_PATHS } from "./lib/brand-assets.ts";
import { HostProcessArchitecture, HostProcessPlatform } from "@t3tools/shared/hostProcess";
@@ -767,3 +771,85 @@ it.layer(NodeServices.layer)("build-desktop-artifact", (it) => {
}),
);
});
+
+// The self-containment check runs the packaged tree in a scratch directory. Its
+// own node_modules holds the unpacked externals and must be ignored, but any
+// node_modules *above* it would let Node's parent walk satisfy an import that is
+// missing from the package, so the probe refuses to run in that case.
+it("lists ancestor node_modules, nearest first, excluding the start directory", () => {
+ assert.deepStrictEqual(ancestorNodeModulesPaths("C:\\tmp\\probe\\app", "\\"), [
+ "C:\\tmp\\probe\\node_modules",
+ "C:\\tmp\\node_modules",
+ "C:\\node_modules",
+ ]);
+});
+
+it("includes the filesystem root for posix paths", () => {
+ assert.deepStrictEqual(ancestorNodeModulesPaths("/tmp/probe", "/"), [
+ "/tmp/node_modules",
+ "/node_modules",
+ ]);
+});
+
+// A UNC root must keep its \\server\share prefix. Rebuilding it from segments
+// produced relative paths, which fs.exists resolves against the build cwd, so
+// the guard checked directories that do not exist and silently passed.
+it("keeps the prefix of a UNC path instead of going relative", () => {
+ const paths = ancestorNodeModulesPaths("\\\\server\\share\\tmp\\app", "\\");
+ for (const candidate of paths) {
+ assert.ok(candidate.startsWith("\\\\server\\share"), candidate);
+ }
+ assert.deepStrictEqual(paths[0], "\\\\server\\share\\tmp\\node_modules");
+});
+
+it.effect("rebases packaged links into the isolated tree", () =>
+ Effect.gen(function* () {
+ const fs = yield* FileSystem.FileSystem;
+ const path = yield* Path.Path;
+ const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3code-copy-symlinks-" });
+ const source = path.join(root, "source");
+ const destination = path.join(root, "destination");
+ const packageDir = path.join(source, "node_modules/.pnpm/example@1/node_modules/example");
+ const relativePackageLink = path.join(source, "node_modules/example-relative");
+ const absolutePackageLink = path.join(source, "node_modules/example-absolute");
+
+ yield* fs.makeDirectory(packageDir, { recursive: true });
+ yield* fs.writeFileString(path.join(packageDir, "index.js"), "module.exports = true;\n");
+ yield* fs.symlink(
+ path.join(".pnpm", "example@1", "node_modules", "example"),
+ relativePackageLink,
+ );
+ yield* fs.symlink(packageDir, absolutePackageLink);
+
+ yield* copyDirectoryPreservingSymlinks(source, destination);
+
+ const copiedPackage = path.join(
+ destination,
+ "node_modules/.pnpm/example@1/node_modules/example",
+ );
+ const resolvedCopiedPackage = yield* fs.realPath(copiedPackage);
+ assert.equal(
+ yield* fs.readLink(path.join(destination, "node_modules/example-relative")),
+ copiedPackage,
+ );
+ assert.equal(
+ yield* fs.readLink(path.join(destination, "node_modules/example-absolute")),
+ copiedPackage,
+ );
+ assert.equal(
+ yield* fs.realPath(path.join(destination, "node_modules/example-relative")),
+ resolvedCopiedPackage,
+ );
+ assert.equal(
+ yield* fs.realPath(path.join(destination, "node_modules/example-absolute")),
+ resolvedCopiedPackage,
+ );
+ }).pipe(Effect.provide(NodeServices.layer)),
+);
+
+it("ignores trailing separators", () => {
+ assert.deepStrictEqual(
+ ancestorNodeModulesPaths("C:\\tmp\\probe\\app\\", "\\"),
+ ancestorNodeModulesPaths("C:\\tmp\\probe\\app", "\\"),
+ );
+});
diff --git a/scripts/build-desktop-artifact.ts b/scripts/build-desktop-artifact.ts
index a30b6d4a9..c86f0c38c 100644
--- a/scripts/build-desktop-artifact.ts
+++ b/scripts/build-desktop-artifact.ts
@@ -1,5 +1,7 @@
#!/usr/bin/env node
+// @effect-diagnostics nodeBuiltinImport:off - Node's typed junction API avoids Windows symlink privileges while keeping the probe isolated.
+import * as NodeFSP from "node:fs/promises";
import * as NodeModule from "node:module";
import { fromYaml } from "@t3tools/shared/schemaYaml";
@@ -17,17 +19,23 @@ import {
type WebAssetBrand,
} from "./lib/brand-assets.ts";
import { getDefaultBuildArch } from "./lib/build-target-arch.ts";
+import {
+ CLI_EXTERNAL_PACKAGE_UNPACK_GLOBS,
+ findInlinedExternalPackages,
+} from "./lib/cli-external-packages.ts";
import { loadRepoEnv } from "./lib/public-config.ts";
import { resolveCatalogDependencies } from "./lib/resolve-catalog.ts";
import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
import * as NodeServices from "@effect/platform-node/NodeServices";
import * as Config from "effect/Config";
+import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
import * as Layer from "effect/Layer";
import * as Logger from "effect/Logger";
import * as Option from "effect/Option";
+import type { PlatformError } from "effect/PlatformError";
import * as Path from "effect/Path";
import * as Schema from "effect/Schema";
import * as Stream from "effect/Stream";
@@ -375,6 +383,52 @@ const desktopBuildInputArtifactNames = {
"bundled-server-client": "bundled server client",
} satisfies Record<DesktopBuildInputArtifact, string>;
+/**
+ * Imported by every server module, so it is inlined in any correctly bundled
+ * build. Its absence means the bundle went back to externalizing its
+ * dependencies, which the unpack globs do not cover.
+ */
+const BUNDLE_SELF_CONTAINED_SENTINEL = "effect";
+
+const BUNDLE_SELF_CHECK_TIMEOUT = Duration.seconds(120);
+
+export class ExternalizedBundleError extends Schema.TaggedErrorClass<ExternalizedBundleError>()(
+ "ExternalizedBundleError",
+ { sentinel: Schema.String, inlinedPackageCount: Schema.Number },
+) {
+ override get message(): string {
+ return `The server bundle did not inline "${this.sentinel}" (${this.inlinedPackageCount} packages inlined). The bundle is meant to be self-contained apart from the native externals; if its dependencies are external again they will not be unpacked, and the WSL backend will fail with ERR_MODULE_NOT_FOUND. Check the deps.alwaysBundle wiring in apps/server/vite.config.ts.`;
+ }
+}
+
+export class BundleNotSelfContainedError extends Schema.TaggedErrorClass<BundleNotSelfContainedError>()(
+ "BundleNotSelfContainedError",
+ { exitCode: Schema.Number, output: Schema.String },
+) {
+ override get message(): string {
+ return `The packaged server bundle could not load with only its unpacked dependencies present (exit ${this.exitCode}). Anything it imports that is neither a Node built-in nor an unpacked external is unreachable to the WSL backend, which runs plain node and cannot read app.asar. Output:
+${this.output}`;
+ }
+}
+
+export class InlinedNativePackageError extends Schema.TaggedErrorClass<InlinedNativePackageError>()(
+ "InlinedNativePackageError",
+ { packages: Schema.Array(Schema.String) },
+) {
+ override get message(): string {
+ return `The server bundle inlined packages that load native binaries: ${this.packages.join(", ")}. A node-gyp-build style loader resolves prebuilds relative to its own file, so inlined into a chunk it finds none and the importer quietly falls back to a slower JS path. Add them to CLI_RUNTIME_EXTERNAL_PREFIXES in scripts/lib/cli-external-packages.ts so they stay external and get unpacked.`;
+ }
+}
+
+export class InlinedExternalPackageError extends Schema.TaggedErrorClass<InlinedExternalPackageError>()(
+ "InlinedExternalPackageError",
+ { packages: Schema.Array(Schema.String) },
+) {
+ override get message(): string {
+ return `The server bundle inlined packages that must stay external: ${this.packages.join(", ")}. These are native addons or their loaders; inlined, they resolve prebuilds relative to the bundle and silently lose native acceleration. Check the deps.neverBundle wiring in apps/server/vite.config.ts.`;
+ }
+}
+
export class MissingDesktopBuildInputError extends Schema.TaggedErrorClass<MissingDesktopBuildInputError>()(
"MissingDesktopBuildInputError",
{
@@ -633,13 +687,21 @@ export const DESKTOP_FILE_EXCLUSIONS = [
// are dead weight. The trailing dash keeps the SDK's own JS package.
"!**/node_modules/@anthropic-ai/claude-agent-sdk-*/**/*",
] as const;
-// The WSL backend launches the server with plain `wsl.exe -- node`, which
-// cannot read inside an asar archive — and the server bundle externalizes its
-// runtime deps, so the whole node_modules tree must be unpacked, not just the
-// bundle (otherwise ERR_MODULE_NOT_FOUND: "Cannot find package 'effect'").
-// The Windows primary backend reads the same files through the asar redirect,
-// so nothing is duplicated.
-export const WINDOWS_ASAR_UNPACK = ["apps/server/dist/**", "**/node_modules/**"] as const;
+// The WSL backend launches the server with plain `wsl.exe -- node`, which cannot
+// read inside an asar archive, so everything it loads must be on the real
+// filesystem. This used to unpack `**\/node_modules\/**` wholesale, because the
+// server bundle externalized its runtime deps and the Linux Node would fail with
+// ERR_MODULE_NOT_FOUND ("Cannot find package 'effect'") before it even reached
+// node-pty.
+//
+// The CLI bundle now inlines its JS dependencies, so the only things that still
+// have to be loose are the server bundle itself and the packages the bundle
+// leaves external — derived from the same list the bundler uses, so the two
+// cannot drift apart.
+export const WINDOWS_ASAR_UNPACK = [
+ "apps/server/dist/**",
+ ...CLI_EXTERNAL_PACKAGE_UNPACK_GLOBS,
+] as const;
export const DESKTOP_EXTRA_RESOURCES = [
{
from: "apps/desktop/prod-resources/resource-monitor",
@@ -1178,6 +1240,278 @@ const runCommand = Effect.fn("runCommand")(function* (
}
});
+/**
+ * Every `node_modules` directory that would be visible from `startDir`.
+ *
+ * The self-containment check is only meaningful in a directory with none of
+ * these: Node walks parents when resolving a bare import, so a stray
+ * node_modules above the probe would satisfy imports that are missing from the
+ * packaged tree and turn the check into a silent pass.
+ */
+function trimTrailingSeparators(value: string): string {
+ let end = value.length;
+ while (end > 1 && (value[end - 1] === "/" || value[end - 1] === "\\")) end -= 1;
+ return value.slice(0, end);
+}
+
+/**
+ * Length of the `\\server\share` prefix, or 0 when the path is not UNC.
+ *
+ * The share is the highest real directory on a UNC path: `\\server` on its own
+ * is not one, so the ancestor walk must stop there.
+ */
+function uncShareRootLength(value: string): number {
+ const isUnc = value.startsWith("\\\\") || value.startsWith("//");
+ if (!isUnc) return 0;
+ const separator = /[\\/]/;
+ const serverEnd = value.slice(2).search(separator);
+ if (serverEnd < 0) return value.length;
+ const shareStart = 2 + serverEnd + 1;
+ const shareEnd = value.slice(shareStart).search(separator);
+ return shareEnd < 0 ? value.length : shareStart + shareEnd;
+}
+
+export function ancestorNodeModulesPaths(
+ startDir: string,
+ separator: string,
+): ReadonlyArray<string> {
+ // Walks with lastIndexOf rather than splitting into segments so UNC roots
+ // (\\server\share) and drive roots keep their prefix instead of being
+ // rebuilt into a relative path that silently resolves against the build cwd.
+ const paths: string[] = [];
+ let current = trimTrailingSeparators(startDir);
+ // On a UNC path the share itself is the root: \\server is not a directory, so
+ // walking past \\server\share would emit paths that cannot exist.
+ const uncRootLength = uncShareRootLength(current);
+ for (;;) {
+ const cut = Math.max(current.lastIndexOf("/"), current.lastIndexOf("\\"));
+ if (cut < 0 || (uncRootLength > 0 && cut < uncRootLength)) break;
+ const parent = cut === 0 ? current.slice(0, 1) : current.slice(0, cut);
+ if (parent === current) break;
+ paths.push(
+ parent.endsWith(separator) ? `${parent}node_modules` : `${parent}${separator}node_modules`,
+ );
+ if (cut === 0) break;
+ current = parent;
+ }
+ return paths;
+}
+
+const NativeMarkerManifest = Schema.Struct({
+ dependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+ optionalDependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+});
+const decodeNativeMarkerManifest = Schema.decodeUnknownSync(
+ Schema.fromJsonString(NativeMarkerManifest),
+);
+
+/** Locate a package inside the pnpm store, which is where the real files live. */
+const findStorePackageDirectory = Effect.fn("findStorePackageDirectory")(function* (
+ repoRoot: string,
+ packageName: string,
+) {
+ const fs = yield* FileSystem.FileSystem;
+ const path = yield* Path.Path;
+ const storeDir = path.join(repoRoot, "node_modules/.pnpm");
+ const exists = (candidate: string) =>
+ fs.exists(candidate).pipe(Effect.orElseSucceed(() => false));
+ if (!(yield* exists(storeDir))) return null;
+
+ const flattened = `${packageName.replace("/", "+")}@`;
+ const entries = yield* fs
+ .readDirectory(storeDir)
+ .pipe(Effect.orElseSucceed(() => [] as string[]));
+ for (const entry of entries) {
+ if (!entry.startsWith(flattened)) continue;
+ const candidate = path.join(storeDir, entry, "node_modules", packageName);
+ if (yield* exists(candidate)) return candidate;
+ }
+ return null;
+});
+
+/** Whether a package builds or ships a native addon it loads at runtime. */
+const hasNativeLoaderMarkers = Effect.fn("hasNativeLoaderMarkers")(function* (packageDir: string) {
+ const fs = yield* FileSystem.FileSystem;
+ const path = yield* Path.Path;
+ const exists = (candidate: string) =>
+ fs.exists(candidate).pipe(Effect.orElseSucceed(() => false));
+
+ if (yield* exists(path.join(packageDir, "binding.gyp"))) return true;
+ if (yield* exists(path.join(packageDir, "prebuilds"))) return true;
+
+ const manifestPath = path.join(packageDir, "package.json");
+ if (!(yield* exists(manifestPath))) return false;
+ const source = yield* fs.readFileString(manifestPath).pipe(Effect.orElseSucceed(() => ""));
+ if (source === "") return false;
+ const manifest = yield* Effect.try(() => decodeNativeMarkerManifest(source)).pipe(
+ Effect.orElseSucceed(() => null),
+ );
+ if (manifest === null) return false;
+ return Object.keys({ ...manifest.dependencies, ...manifest.optionalDependencies }).some(
+ (dependency) => dependency.startsWith("node-gyp-build"),
+ );
+});
+
+export const copyDirectoryPreservingSymlinks = Effect.fn("copyDirectoryPreservingSymlinks")(
+ function* (source: string, destination: string) {
+ const fs = yield* FileSystem.FileSystem;
+ const path = yield* Path.Path;
+
+ // Effect's Node implementation delegates directory copies to fs.cp, whose
+ // default rewrites links into absolute source-tree references. Recreate every
+ // in-tree directory link as a junction rooted in the isolated copy so the
+ // probe cannot resolve through staging and Windows needs no symlink privilege.
+ yield* fs.copy(source, destination);
+
+ const restoreRelativeSymlinks = (
+ sourceDirectory: string,
+ destinationDirectory: string,
+ ): Effect.Effect<void, PlatformError | BundleNotSelfContainedError> =>
+ Effect.gen(function* () {
+ for (const entry of yield* fs.readDirectory(sourceDirectory)) {
+ const sourceEntry = path.join(sourceDirectory, entry);
+ const destinationEntry = path.join(destinationDirectory, entry);
+ const linkTarget = yield* fs.readLink(sourceEntry).pipe(Effect.option);
+ if (Option.isSome(linkTarget)) {
+ const absoluteSourceTarget = path.isAbsolute(linkTarget.value)
+ ? linkTarget.value
+ : path.resolve(path.dirname(sourceEntry), linkTarget.value);
+ const sourceRelativeTarget = path.relative(source, absoluteSourceTarget);
+ if (
+ sourceRelativeTarget === ".." ||
+ sourceRelativeTarget.startsWith(`..${path.sep}`) ||
+ path.isAbsolute(sourceRelativeTarget)
+ ) {
+ return yield* new BundleNotSelfContainedError({
+ exitCode: -1,
+ output: `Refusing to copy symlink ${sourceEntry}: its target ${absoluteSourceTarget} escapes the packaged tree.`,
+ });
+ }
+ const target = path.join(destination, sourceRelativeTarget);
+ yield* fs.remove(destinationEntry, { recursive: true, force: true });
+ yield* Effect.tryPromise({
+ try: () => NodeFSP.symlink(target, destinationEntry, "junction"),
+ catch: (cause) =>
+ new BundleNotSelfContainedError({
+ exitCode: -1,
+ output: `Could not isolate ${sourceEntry}: ${String(cause)}`,
+ }),
+ });
+ } else {
+ const info = yield* fs.stat(sourceEntry);
+ if (info.type === "Directory") {
+ yield* restoreRelativeSymlinks(sourceEntry, destinationEntry);
+ }
+ }
+ }
+ });
+
+ yield* restoreRelativeSymlinks(source, destination);
+ },
+);
+
+const verifyPackagedBundleIsSelfContained = Effect.fn("verifyPackagedBundleIsSelfContained")(
+ function* (input: { readonly stageDistDir: string; readonly verbose: boolean }) {
+ const fs = yield* FileSystem.FileSystem;
+ const path = yield* Path.Path;
+
+ // electron-builder names this win-unpacked, win-arm64-unpacked, and so on.
+ const distEntries = yield* fs
+ .readDirectory(input.stageDistDir)
+ .pipe(Effect.orElseSucceed(() => [] as Array<string>));
+ let unpackedRoot: string | null = null;
+ for (const entry of distEntries) {
+ const candidate = path.join(input.stageDistDir, entry, "resources/app.asar.unpacked");
+ if (yield* fs.exists(candidate).pipe(Effect.orElseSucceed(() => false))) {
+ unpackedRoot = candidate;
+ break;
+ }
+ }
+ // Nothing to verify rather than silently passing: a packaging layout change
+ // should surface here instead of turning the check into a no-op.
+ if (unpackedRoot === null) {
+ return yield* new BundleNotSelfContainedError({
+ exitCode: -1,
+ output: `No */resources/app.asar.unpacked directory under ${input.stageDistDir}; the bundle self-containment check found nothing to verify.`,
+ });
+ }
+
+ const probeRoot = yield* fs.makeTempDirectoryScoped({
+ prefix: "t3code-bundle-selfcheck-",
+ });
+ const probeApp = path.join(probeRoot, "app");
+ yield* copyDirectoryPreservingSymlinks(unpackedRoot, probeApp);
+
+ // Guard the guard: if anything above the probe provides a node_modules, a
+ // missing dependency would resolve there and the check would pass while the
+ // packaged tree is broken.
+ for (const candidate of ancestorNodeModulesPaths(probeApp, path.sep)) {
+ if (yield* fs.exists(candidate).pipe(Effect.orElseSucceed(() => false))) {
+ return yield* new BundleNotSelfContainedError({
+ exitCode: -1,
+ output: `Refusing to report success: ${candidate} is visible from the probe directory, so bare imports could resolve outside the packaged tree. Remove or rename it, or point TMPDIR somewhere without one.`,
+ });
+ }
+ }
+
+ const entryPoint = path.join(probeApp, "apps/server/dist/bin.mjs");
+ if (!(yield* fs.exists(entryPoint).pipe(Effect.orElseSucceed(() => false)))) {
+ return yield* new BundleNotSelfContainedError({
+ exitCode: -1,
+ output: `Expected the server entry at ${entryPoint}.`,
+ });
+ }
+
+ // --version exercises the eagerly loaded module graph, which is where a
+ // missing dependency shows up, without starting a server or touching disk
+ // state. It does not cover lazily imported externals: node-pty is checked
+ // by the WSL preflight probe at runtime, while ffi-rs, @ff-labs/fff-node
+ // and the bun adapters are only covered by the unpack globs and the
+ // inlined-native check below.
+ yield* runCommand(
+ ChildProcess.make(
+ process.execPath,
+ // --no-global-search-paths because clearing NODE_PATH is not enough:
+ // CommonJS resolution still falls back to $HOME/.node_modules,
+ // $HOME/.node_libraries and the install prefix, so a globally installed
+ // copy of a missing dependency would quietly satisfy this check.
+ ["--no-global-search-paths", entryPoint, "--version"],
+ {
+ cwd: probeApp,
+ stdout: "pipe",
+ stderr: "pipe",
+ // NODE_PATH would let a createRequire call inside the bundle resolve
+ // a missing external from outside the packaged tree, which is the
+ // whole thing this is trying to rule out.
+ env: { ...process.env, NODE_PATH: "" },
+ },
+ ),
+ { label: "bundle self-containment check (node bin.mjs --version)", verbose: input.verbose },
+ ).pipe(
+ // Printing a version should be immediate. A regression that blocks (on
+ // stdin, a port, a lock) would otherwise hang release CI until the job
+ // times out with nothing useful in the log.
+ Effect.timeout(BUNDLE_SELF_CHECK_TIMEOUT),
+ Effect.catchTag("TimeoutError", () =>
+ Effect.fail(
+ new BundleNotSelfContainedError({
+ exitCode: -1,
+ output: `The packaged bundle did not print its version within ${Duration.toSeconds(BUNDLE_SELF_CHECK_TIMEOUT)}s; it is hanging rather than failing to resolve.`,
+ }),
+ ),
+ ),
+ Effect.catchTag("BuildCommandFailedError", (error) =>
+ Effect.fail(
+ new BundleNotSelfContainedError({
+ exitCode: error.exitCode,
+ output: `${error.stderrTail ?? ""}${error.stdoutTail ?? ""}`.trim(),
+ }),
+ ),
+ ),
+ );
+ },
+);
+
const stageResourceMonitor = Effect.fn("stageResourceMonitor")(function* (input: {
readonly repoRoot: string;
readonly stageResourcesDir: string;
@@ -1817,6 +2151,68 @@ const buildDesktopArtifact = Effect.fn("buildDesktopArtifact")(function* (
}
}
+ // Assert against the emitted bundle, not the bundler config. `alwaysBundle`
+ // only forces packages IN, so a transitive dependency of an external package
+ // is bundled by default however the predicate is written — that silently
+ // inlined msgpackr-extract and its native loader while every list-based test
+ // still passed. An inlined native loader resolves its prebuilds relative to
+ // the bundle and quietly falls back to a slower pure-JS path, so this fails
+ // the build rather than shipping a silent regression.
+ {
+ const chunkNames = (yield* fs.readDirectory(distDirs.serverDist)).filter((entry) =>
+ entry.endsWith(".mjs"),
+ );
+ let totalRegions = 0;
+ const inlined = new Set<string>();
+ const inlinedPackages = new Set<string>();
+ for (const chunkName of chunkNames) {
+ const source = yield* fs.readFileString(path.join(distDirs.serverDist, chunkName));
+ const scan = findInlinedExternalPackages(source);
+ totalRegions += scan.regionCount;
+ for (const name of scan.inlined) inlined.add(name);
+ for (const name of scan.inlinedPackages) inlinedPackages.add(name);
+ }
+ if (inlined.size > 0) {
+ return yield* new InlinedExternalPackageError({
+ packages: [...inlined].sort(),
+ });
+ }
+ // No regions at all means the scan went blind (marker format changed), not
+ // that the bundle is clean.
+ if (totalRegions === 0) {
+ return yield* new InlinedExternalPackageError({
+ packages: ["<no module regions found; the bundle scan needs updating>"],
+ });
+ }
+ // The check above is one-directional: it only proves nothing external got
+ // inlined. A regression to externalizing everything would also pass it,
+ // since source-file regions still exist -- and that is the failure this
+ // whole change exists to prevent, because those packages are not in the
+ // unpack globs and the WSL backend would die on ERR_MODULE_NOT_FOUND.
+ // `effect` is imported by every server module, so it is inlined in any
+ // correctly bundled build.
+ // The list-based check above only sees packages someone already thought to
+ // list. bufferutil and utf-8-validate were inlined for exactly that reason:
+ // native, but absent from the list, so nothing flagged them. Ask the store
+ // what each inlined package actually is instead.
+ const nativeInlined: string[] = [];
+ for (const name of [...inlinedPackages].sort()) {
+ const packageDir = yield* findStorePackageDirectory(repoRoot, name);
+ if (packageDir === null) continue;
+ if (yield* hasNativeLoaderMarkers(packageDir)) nativeInlined.push(name);
+ }
+ if (nativeInlined.length > 0) {
+ return yield* new InlinedNativePackageError({ packages: nativeInlined });
+ }
+
+ if (!inlinedPackages.has(BUNDLE_SELF_CONTAINED_SENTINEL)) {
+ return yield* new ExternalizedBundleError({
+ sentinel: BUNDLE_SELF_CONTAINED_SENTINEL,
+ inlinedPackageCount: inlinedPackages.size,
+ });
+ }
+ }
+
if (!(yield* fs.exists(bundledClientEntry))) {
return yield* new MissingDesktopBuildInputError({
artifact: "bundled-server-client",
@@ -2056,6 +2452,21 @@ const buildDesktopArtifact = Effect.fn("buildDesktopArtifact")(function* (
});
}
+ // Prove the packaged bundle is self-contained by loading it the way the WSL
+ // backend does, rather than by reasoning about the emitted source.
+ //
+ // Static analysis kept getting this wrong here. Scanning for bare imports
+ // matched specifiers inside effect's JSDoc examples and inside ajv's runtime
+ // codegen template, and asserting that one sentinel package was inlined
+ // missed a build that inlined `effect` while leaving `yaml` external. Node's
+ // resolver has no such ambiguity: it either finds every import or it does not.
+ //
+ // Only Windows unpacks anything; macOS and Linux keep the whole tree inside
+ // the asar, where this check has nothing to look at.
+ if (options.platform === "win") {
+ yield* verifyPackagedBundleIsSelfContained({ stageDistDir, verbose: options.verbose });
+ }
+
const stageEntries = yield* fs.readDirectory(stageDistDir);
yield* fs.makeDirectory(options.outputDir, { recursive: true });
diff --git a/scripts/lib/cli-external-packages.test.ts b/scripts/lib/cli-external-packages.test.ts
new file mode 100644
index 000000000..189634dfe
--- /dev/null
+++ b/scripts/lib/cli-external-packages.test.ts
@@ -0,0 +1,275 @@
+import * as NodeURL from "node:url";
+
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, describe, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+
+import {
+ CLI_EXTERNAL_PACKAGE_PREFIXES,
+ CLI_EXTERNAL_PACKAGE_UNPACK_GLOBS,
+ CLI_RUNTIME_EXTERNAL_PREFIXES,
+ findInlinedExternalPackages,
+ shouldBundleCliDependency,
+} from "./cli-external-packages.ts";
+
+// Only the field this test cares about; decoding ignores everything else.
+// optionalDependencies matter as much as dependencies here: every native family
+// in the list declares its actual platform bindings there (ffi-rs -> @yuuang/*,
+// msgpackr-extract -> @msgpackr-extract/*, fff-node -> @ff-labs/fff-bin-*), so
+// reading only `dependencies` would check nothing for exactly those packages.
+const PackageManifest = Schema.Struct({
+ dependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+ optionalDependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+ peerDependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+});
+type PackageManifest = typeof PackageManifest.Type;
+
+const decodeManifest = Schema.decodeUnknownSync(Schema.fromJsonString(PackageManifest));
+
+describe("shouldBundleCliDependency", () => {
+ it("bundles ordinary runtime dependencies", () => {
+ for (const id of ["effect", "@effect/platform", "hono", "@t3tools/shared/hostProcess"]) {
+ assert.strictEqual(shouldBundleCliDependency(id), true, id);
+ }
+ });
+
+ it("never bundles node: builtins", () => {
+ assert.strictEqual(shouldBundleCliDependency("node:fs"), false);
+ });
+
+ it("leaves native addons and their dlopen wrappers external", () => {
+ for (const id of [
+ "node-pty",
+ "ffi-rs",
+ "@yuuang/ffi-rs-win32-x64-msvc",
+ "@ff-labs/fff-node",
+ "@clerk/electron-passkeys",
+ "msgpackr-extract",
+ "@msgpackr-extract/msgpackr-extract-win32-x64",
+ ]) {
+ assert.strictEqual(shouldBundleCliDependency(id), false, id);
+ }
+ });
+
+ it("leaves bun-only entry points external", () => {
+ assert.strictEqual(shouldBundleCliDependency("@effect/platform-bun"), false);
+ assert.strictEqual(shouldBundleCliDependency("@effect/sql-sqlite-bun"), false);
+ });
+
+ // The real package is `node-gyp-build-optional-packages`, reached by prefix.
+ // Matching it as external while failing to unpack it is invisible on the
+ // Windows primary (which reads app.asar) and breaks only under WSL.
+ it("treats prefix-matched siblings as external", () => {
+ assert.strictEqual(shouldBundleCliDependency("node-gyp-build-optional-packages"), false);
+ });
+});
+
+describe("CLI_EXTERNAL_PACKAGE_UNPACK_GLOBS", () => {
+ it("unpacks every external prefix from both the top level and the pnpm store", () => {
+ for (const prefix of CLI_EXTERNAL_PACKAGE_PREFIXES) {
+ assert.include(CLI_EXTERNAL_PACKAGE_UNPACK_GLOBS, `node_modules/${prefix}*/**/*`, prefix);
+ assert.include(
+ CLI_EXTERNAL_PACKAGE_UNPACK_GLOBS,
+ `node_modules/.pnpm/**/node_modules/${prefix}*/**/*`,
+ prefix,
+ );
+ }
+ });
+
+ // Without the trailing `*` the globs stop covering prefix-matched siblings,
+ // which is exactly how a package ends up external but not unpacked.
+ it("keeps the trailing wildcard that matches prefix siblings", () => {
+ assert.include(CLI_EXTERNAL_PACKAGE_UNPACK_GLOBS, "node_modules/node-gyp-build*/**/*");
+ });
+});
+
+// The failure this guards is invisible on Windows and fatal under WSL.
+//
+// An external package is loaded from the real filesystem, so its own `require`
+// also resolves from the real filesystem. If one of its dependencies was
+// bundled away instead of left external, that dependency exists only inside
+// app.asar — which the Windows primary reads transparently under
+// ELECTRON_RUN_AS_NODE, and plain `node` under WSL cannot.
+//
+// Found the hard way: node-gyp-build-optional-packages requires detect-libc,
+// which was bundled. Windows was fine; WSL got MODULE_NOT_FOUND.
+it.layer(NodeServices.layer)("external package dependency closure", (it) => {
+ // Read manifests off disk from the pnpm store rather than resolving them.
+ // `require("<name>/package.json")` cannot do this job: under pnpm isolation a
+ // transitive package (detect-libc, msgpackr-extract, ffi-rs) is not reachable
+ // by name from this file at all, and an `exports` map can refuse the
+ // `/package.json` subpath outright (@ff-labs/fff-node). Both surface as "not
+ // installed", which would let this test skip everything and pass while
+ // checking nothing. The store is also what asarUnpack globs target, so this
+ // reads the same tree the build packages.
+ const readInstalledPackages = Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const path = yield* Path.Path;
+ const storeDir = path.resolve(
+ path.dirname(NodeURL.fileURLToPath(import.meta.url)),
+ "../../node_modules/.pnpm",
+ );
+
+ // The store holds regular files too (lock.yaml), so a path built under one
+ // raises ENOTDIR rather than reporting absence. That throws on Linux while
+ // Windows quietly returns false, which is exactly the kind of difference
+ // this test exists to catch, so treat any failure as "not there".
+ const isPresent = (candidate: string) =>
+ fileSystem.exists(candidate).pipe(Effect.orElseSucceed(() => false));
+
+ const installed = new Map<string, PackageManifest>();
+ if (!(yield* isPresent(storeDir))) return installed;
+
+ for (const entry of yield* fileSystem.readDirectory(storeDir)) {
+ const modulesDir = path.join(storeDir, entry, "node_modules");
+ if (!(yield* isPresent(modulesDir))) continue;
+
+ for (const owner of yield* fileSystem.readDirectory(modulesDir)) {
+ const names = owner.startsWith("@")
+ ? (yield* fileSystem.readDirectory(path.join(modulesDir, owner))).map(
+ (scoped) => `${owner}/${scoped}`,
+ )
+ : [owner];
+
+ for (const name of names) {
+ if (installed.has(name)) continue;
+ const manifestPath = path.join(modulesDir, name, "package.json");
+ if (!(yield* isPresent(manifestPath))) continue;
+ installed.set(name, decodeManifest(yield* fileSystem.readFileString(manifestPath)));
+ }
+ }
+ }
+ return installed;
+ }).pipe(Effect.cached, Effect.runSync);
+
+ // Runtime-external only. The build-only entries resolve `bun:*` and are never
+ // loaded by Node, so their closure genuinely does not need to be external.
+ const isRuntimeExternal = (name: string) =>
+ CLI_RUNTIME_EXTERNAL_PREFIXES.some((prefix) => name.startsWith(prefix));
+
+ it.effect("finds the runtime-external packages on disk", () =>
+ Effect.gen(function* () {
+ const installed = yield* readInstalledPackages;
+ const found = [...installed.keys()].filter(isRuntimeExternal);
+
+ // Without this the closure check below can pass vacuously: if nothing is
+ // read, nothing is checked. These are the packages whose closure actually
+ // broke WSL, so require them by name.
+ for (const required of ["node-pty", "node-gyp-build-optional-packages", "detect-libc"]) {
+ assert.ok(
+ found.includes(required),
+ `expected ${required} in the pnpm store; the closure check is only meaningful if it can read these (found ${found.length})`,
+ );
+ }
+ }),
+ );
+
+ it.effect("keeps every runtime dependency of an external package external too", () =>
+ Effect.gen(function* () {
+ const installed = yield* readInstalledPackages;
+ const violations: string[] = [];
+ const seen = new Set<string>();
+ // Seeded from what is actually installed and matches a prefix, so scoped
+ // prefixes like "@yuuang/" and "@ff-labs/" are covered too. Seeding from
+ // the prefix strings themselves would skip every scoped entry, since a
+ // prefix is not a package name.
+ const queue = [...installed.keys()].filter(isRuntimeExternal);
+
+ for (const name of queue) {
+ if (seen.has(name)) continue;
+ seen.add(name);
+
+ const manifest = installed.get(name);
+ if (!manifest) continue;
+
+ const declared = {
+ ...(manifest.dependencies ?? {}),
+ ...(manifest.optionalDependencies ?? {}),
+ ...(manifest.peerDependencies ?? {}),
+ };
+ for (const dependency of Object.keys(declared)) {
+ if (!isRuntimeExternal(dependency)) {
+ violations.push(`${name} -> ${dependency}`);
+ }
+ if (!seen.has(dependency)) queue.push(dependency);
+ }
+ }
+
+ assert.deepStrictEqual(
+ violations,
+ [],
+ `these dependencies of external packages would be bundled away and fail to resolve under WSL: ${violations.join(", ")}`,
+ );
+ }),
+ );
+});
+
+// Configuring the bundler is not the same as checking what it emitted. These
+// exercise the scanner against the marker shape rolldown actually produces.
+describe("findInlinedExternalPackages", () => {
+ const region = (path: string) => `//#region ${path}
+var x = 1;
+//#endregion
+`;
+
+ it("flags an external package that was inlined", () => {
+ const source =
+ region("../../node_modules/.pnpm/[email protected]/node_modules/detect-libc/lib/process.js") +
+ region(
+ "../../node_modules/.pnpm/[email protected]/node_modules/msgpackr-extract/index.js",
+ );
+ const result = findInlinedExternalPackages(source);
+
+ assert.deepStrictEqual(result.inlined, ["detect-libc", "msgpackr-extract"]);
+ assert.strictEqual(result.regionCount, 2);
+ });
+
+ it("flags scoped external packages", () => {
+ const result = findInlinedExternalPackages(
+ region("../../node_modules/@ff-labs/fff-node/dist/src/index.js"),
+ );
+ assert.deepStrictEqual(result.inlined, ["@ff-labs/fff-node"]);
+ });
+
+ it("ignores packages that are meant to be bundled", () => {
+ const source =
+ region("../../node_modules/.pnpm/[email protected]/node_modules/effect/dist/index.js") +
+ region("../../src/server/main.ts");
+ const result = findInlinedExternalPackages(source);
+
+ assert.deepStrictEqual(result.inlined, []);
+ assert.strictEqual(result.regionCount, 2);
+ });
+
+ // regionCount is what separates "clean" from "this scan went blind because the
+ // marker format changed". A caller that ignores it gets a vacuous pass.
+ // The scan has to answer both directions. Checking only that externals are
+ // absent still passes on a bundle that externalized everything, which is the
+ // failure this whole change prevents.
+ it("reports the packages that were inlined, not just the violations", () => {
+ const source =
+ region("../../node_modules/.pnpm/[email protected]/node_modules/effect/dist/index.js") +
+ region("../../node_modules/.pnpm/[email protected]/node_modules/yaml/dist/index.js") +
+ region("../../src/server/main.ts");
+ const result = findInlinedExternalPackages(source);
+
+ assert.deepStrictEqual(result.inlinedPackages, ["effect", "yaml"]);
+ assert.deepStrictEqual(result.inlined, []);
+ });
+
+ it("does not report the pnpm store directory as a package", () => {
+ const result = findInlinedExternalPackages(
+ region("../../node_modules/.pnpm/[email protected]/node_modules/effect/dist/index.js"),
+ );
+ assert.deepStrictEqual(result.inlinedPackages, ["effect"]);
+ });
+
+ it("reports no regions when the marker format is absent", () => {
+ const result = findInlinedExternalPackages("var x = 1; // node_modules/detect-libc/lib.js");
+ assert.strictEqual(result.regionCount, 0);
+ assert.deepStrictEqual(result.inlined, []);
+ });
+});
diff --git a/scripts/lib/cli-external-packages.ts b/scripts/lib/cli-external-packages.ts
new file mode 100644
index 000000000..f50718af4
--- /dev/null
+++ b/scripts/lib/cli-external-packages.ts
@@ -0,0 +1,156 @@
+/**
+ * The single source of truth for packages the server CLI bundle must NOT inline.
+ *
+ * Two consumers derive from this list, and they must never disagree:
+ *
+ * - apps/server/vite.config.ts decides what stays external to the bundle.
+ * - scripts/build-desktop-artifact.ts decides what gets unpacked out of the asar.
+ *
+ * A package that is external but not unpacked still resolves on the Windows
+ * primary, which runs under ELECTRON_RUN_AS_NODE and reads app.asar
+ * transparently. It fails only under WSL, where the backend is launched as plain
+ * `wsl.exe -- node` and cannot read inside an archive. That asymmetry makes the
+ * drift invisible on the platform you are most likely to test on, which is why
+ * both consumers derive from one list instead of maintaining their own.
+ *
+ * Entries are matched as prefixes (`id.startsWith(prefix)`), so they also cover
+ * a package's platform-specific siblings — `node-gyp-build` covers
+ * `node-gyp-build-optional-packages`, `@yuuang/` covers every `ffi-rs-*` binding.
+ */
+/**
+ * External because Node actually loads them from disk at runtime.
+ *
+ * Native addons (.node), the JS wrappers that dlopen them by real path, and —
+ * critically — the ordinary JS packages those wrappers require. An external
+ * package is loaded from the real filesystem, so its own `require` also
+ * resolves from the real filesystem; a dependency that was bundled away exists
+ * only inside app.asar and is unreachable there. This closure is enforced by a
+ * test, not by inspection.
+ */
+export const CLI_RUNTIME_EXTERNAL_PREFIXES = [
+ "node-pty",
+ "ffi-rs",
+ "@yuuang/",
+ "@ff-labs/",
+ "@clerk/electron-passkeys",
+ "@msgpackr-extract/",
+ "msgpackr-extract",
+ "node-gyp-build",
+ "node-addon-api",
+ // Required by node-gyp-build-optional-packages. Not native, but in the
+ // closure: without it, WSL gets MODULE_NOT_FOUND while Windows is fine.
+ "detect-libc",
+ // ws's optional accelerators. Nothing in this repo declares them, so they are
+ // not in the staged production install and the packaged app does not ship
+ // them either way -- ws wraps the require in try/catch and falls back to its
+ // JS paths. They are listed because they were being inlined from the dev
+ // store: both carry binding.gyp and prebuilds and load through
+ // node-gyp-build, and a native loader inlined into a bundle chunk searches
+ // for prebuilds that cannot be beside it. Listing them keeps that from
+ // becoming real if either is ever declared as a dependency.
+ "bufferutil",
+ "utf-8-validate",
+] as const;
+
+/**
+ * External only so the bundler never has to resolve them.
+ *
+ * These are reached through a runtime-conditional dynamic import that Node
+ * never takes, and they resolve `bun:*` specifiers that do not exist when
+ * bundling for Node. Because Node never loads them, their dependency closure
+ * does not need to be external — only the entry point must stay unbundled.
+ */
+export const CLI_BUILD_ONLY_EXTERNAL_PREFIXES = [
+ "@effect/platform-bun",
+ "@effect/sql-sqlite-bun",
+] as const;
+
+export const CLI_EXTERNAL_PACKAGE_PREFIXES = [
+ ...CLI_RUNTIME_EXTERNAL_PREFIXES,
+ ...CLI_BUILD_ONLY_EXTERNAL_PREFIXES,
+] as const;
+
+/**
+ * True when `id` must stay out of the bundle.
+ *
+ * This has to be wired to the bundler's `neverBundle`, not just to
+ * `alwaysBundle`. `alwaysBundle` only forces packages IN — returning false from
+ * it means "no opinion", and the default then applies: a declared dependency
+ * stays external, but a transitive one gets bundled. That is how
+ * msgpackr-extract, node-gyp-build-optional-packages and detect-libc ended up
+ * inlined while node-pty (a declared dependency) stayed external.
+ */
+export function isExternalCliDependency(id: string): boolean {
+ return CLI_EXTERNAL_PACKAGE_PREFIXES.some((prefix) => id.startsWith(prefix));
+}
+
+/** True when the CLI bundle should inline `id` rather than leave it external. */
+export function shouldBundleCliDependency(id: string): boolean {
+ if (id.startsWith("node:")) return false;
+ return !isExternalCliDependency(id);
+}
+
+/**
+ * asar-unpack globs covering every external package.
+ *
+ * The trailing `*` is what keeps these aligned with the prefix matching above:
+ * without it, `node-gyp-build` would be left external by the bundler and then
+ * not unpacked, because the real package is `node-gyp-build-optional-packages`.
+ *
+ * pnpm stores real files under `.pnpm` and symlinks the top-level names, so both
+ * paths are unpacked for the link target to exist on disk.
+ */
+export const CLI_EXTERNAL_PACKAGE_UNPACK_GLOBS = CLI_EXTERNAL_PACKAGE_PREFIXES.flatMap(
+ (prefix) =>
+ [`node_modules/${prefix}*/**/*`, `node_modules/.pnpm/**/node_modules/${prefix}*/**/*`] as const,
+);
+
+/**
+ * Scan an emitted bundle chunk for runtime-external packages that were inlined.
+ *
+ * Configuring the bundler is not the same as checking what it produced. The
+ * `alwaysBundle` predicate only forces packages IN; returning false from it
+ * means "no opinion", so a transitive dependency still gets bundled by default.
+ * msgpackr-extract, node-gyp-build-optional-packages and detect-libc were
+ * inlined that way while every list-based test passed, which is why this reads
+ * the artifact instead.
+ *
+ * `regionCount` is reported so the caller can tell "nothing was inlined" apart
+ * from "the marker format changed and this scan no longer sees anything".
+ *
+ * `inlinedPackages` is every package seen in a region, which lets the caller
+ * check the opposite direction too. Verifying only that externals are absent
+ * would still pass if the bundler reverted to leaving everything external: the
+ * scan would see source-file regions, report nothing inlined, and the packaged
+ * WSL backend would then fail with ERR_MODULE_NOT_FOUND because those packages
+ * are not in the unpack globs either.
+ */
+export function findInlinedExternalPackages(source: string): {
+ readonly regionCount: number;
+ readonly inlined: ReadonlyArray<string>;
+ readonly inlinedPackages: ReadonlyArray<string>;
+} {
+ // Rolldown marks each inlined module with a `//#region <path>` comment.
+ const regionPattern = /\/\/#region\s+(\S+)/g;
+ const packagePattern = /node_modules\/((?:@[^/\s]+\/)?[^/\s]+)\//g;
+
+ let regionCount = 0;
+ const inlined = new Set<string>();
+ const inlinedPackages = new Set<string>();
+ for (const region of source.matchAll(regionPattern)) {
+ regionCount += 1;
+ const regionPath = region[1] ?? "";
+ for (const candidate of regionPath.matchAll(packagePattern)) {
+ const name = candidate[1];
+ if (name === undefined || name === ".pnpm") continue;
+ inlinedPackages.add(name);
+ if (isExternalCliDependency(name)) inlined.add(name);
+ }
+ }
+
+ return {
+ regionCount,
+ inlined: [...inlined].sort(),
+ inlinedPackages: [...inlinedPackages].sort(),
+ };
+}