fix(release): declare the npm platform packages' shipped node_modules as bundled dependencies

The platform packages carry the executable's native addons inside
node_modules but declared none of them, so npm treated the tree as
extraneous and pruned it on the next npm install in the same project. The
executable then failed with "Cannot find module '@ff-labs/fff-node'". Every
top-level package in the shipped tree is now listed in dependencies at its
on-disk version and in bundleDependencies, which is how npm is told the
tree belongs to the package.

Reported by @Nipsuli against 0.0.41-nightly.20260914.1707 on macOS.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: juliusmarminge

scripts/build-npm-platform-packages.test.ts

@@ -55,9 +55,22 @@ const makeFakeArchives = Effect.fn("test.makeFakeArchives")(function* () {
     const stem = `t3-${VERSION}-${key}`;
     const stage = path.join(root, "stage", key);
     const contentDir = path.join(stage, stem);
-    for (const dir of ["client", "resource-monitor", "node_modules/node-pty"]) {
+    for (const dir of [
+      "client",
+      "resource-monitor",
+      "node_modules/node-pty",
+      "node_modules/@ff-labs/fff-node",
+    ]) {
       yield* fs.makeDirectory(path.join(contentDir, dir), { recursive: true });
     }
+    yield* fs.writeFileString(
+      path.join(contentDir, "node_modules/node-pty/package.json"),
+      '{ "name": "node-pty", "version": "1.1.0" }\n',
+    );
+    yield* fs.writeFileString(
+      path.join(contentDir, "node_modules/@ff-labs/fff-node/package.json"),
+      '{ "name": "@ff-labs/fff-node", "version": "0.9.4" }\n',
+    );
     yield* fs.writeFileString(path.join(contentDir, "client/index.html"), "<html></html>\n");
     yield* fs.writeFileString(
       path.join(contentDir, "t3"),
@@ -127,6 +140,13 @@ it.layer(NodeServices.layer)("build-npm-platform-packages", (it) => {
       ]);
       assert.equal(linuxManifest.preferUnplugged, true);
       assert.isUndefined(linuxManifest.bin);
+      // The shipped node_modules is declared, or npm prunes it as extraneous
+      // on the next install in the same project and the executable breaks.
+      assert.deepStrictEqual(linuxManifest.dependencies, {
+        "@ff-labs/fff-node": "0.9.4",
+        "node-pty": "1.1.0",
+      });
+      assert.deepStrictEqual(linuxManifest.bundleDependencies, ["@ff-labs/fff-node", "node-pty"]);
       // Archive contents sit at the package root, not under the archive stem.
       assert.isTrue(yield* fs.exists(path.join(linuxDir, "client/index.html")));
       // A root README, or npm would display a bundled dependency's.

scripts/build-npm-platform-packages.ts

@@ -88,9 +88,22 @@ export function npmPlatformPackageName(platformKey: CliArchivePlatformKey): stri
   return `${NPM_PLATFORM_PACKAGE_SCOPE}/t3-${platformKey}`;
 }
 
-/** package.json for one platform package; `os`/`cpu` let npm skip the other five. */
-export function npmPlatformPackageManifest(platformKey: CliArchivePlatformKey, version: string) {
+/**
+ * package.json for one platform package; `os`/`cpu` let npm skip the other
+ * five. The archive's runtime `node_modules` (native addons and their
+ * loaders) ships inside the tarball, and npm only keeps a nested tree it can
+ * account for: anything not declared is extraneous and pruned on the next
+ * `npm install` in that project, which then breaks the executable. Declaring
+ * every bundled package as a bundled dependency at the exact version on disk
+ * makes npm treat the tree as part of this package and leave it alone.
+ */
+export function npmPlatformPackageManifest(
+  platformKey: CliArchivePlatformKey,
+  version: string,
+  bundled: Readonly<Record<string, string>>,
+) {
   const [os, cpu] = platformKey.split("-") as [string, string];
+  const bundleDependencies = Object.keys(bundled).sort();
   return {
     name: npmPlatformPackageName(platformKey),
     version,
@@ -101,9 +114,38 @@ export function npmPlatformPackageManifest(platformKey: CliArchivePlatformKey, v
     cpu: [cpu],
     files: ["t3", "t3.exe", "client", "resource-monitor", "node_modules"],
     preferUnplugged: true,
+    dependencies: Object.fromEntries(bundleDependencies.map((name) => [name, bundled[name]])),
+    bundleDependencies,
   };
 }
 
+const PackageVersion = Schema.Struct({ version: Schema.String });
+const decodePackageVersion = Schema.decodeUnknownEffect(Schema.fromJsonString(PackageVersion));
+
+/** Every top-level package under `node_modules`, scoped ones included, at the version its manifest names. */
+const readBundledPackages = Effect.fn("readBundledPackages")(function* (nodeModulesDir: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const bundled: Record<string, string> = {};
+  const packageDirs: Array<{ readonly name: string; readonly dir: string }> = [];
+  for (const entry of yield* fs.readDirectory(nodeModulesDir)) {
+    if (entry.startsWith(".")) continue;
+    const dir = path.join(nodeModulesDir, entry);
+    if (entry.startsWith("@")) {
+      for (const scoped of yield* fs.readDirectory(dir)) {
+        packageDirs.push({ name: `${entry}/${scoped}`, dir: path.join(dir, scoped) });
+      }
+    } else {
+      packageDirs.push({ name: entry, dir });
+    }
+  }
+  for (const { name, dir } of packageDirs) {
+    const manifest = yield* fs.readFileString(path.join(dir, "package.json"));
+    bundled[name] = (yield* decodePackageVersion(manifest)).version;
+  }
+  return bundled;
+});
+
 /**
  * README for one platform package. Without one at the package root, npm
  * shows the first README it finds in the tarball, which is a bundled
@@ -302,9 +344,10 @@ const stagePlatformPackage = Effect.fn("stagePlatformPackage")(function* (input:
   if (executableName === "t3") {
     yield* fs.chmod(executable, 0o755);
   }
+  const bundled = yield* readBundledPackages(path.join(contentDir, "node_modules"));
   yield* fs.writeFileString(
     path.join(contentDir, "package.json"),
-    `${yield* encodePackageJson(npmPlatformPackageManifest(input.key, input.version))}\n`,
+    `${yield* encodePackageJson(npmPlatformPackageManifest(input.key, input.version, bundled))}\n`,
   );
   yield* fs.writeFileString(
     path.join(contentDir, "README.md"),