@arcote.tech/arc-cli 0.6.2 → 0.7.1

package/src/builder/module-builder.ts

@@ -17,6 +17,8 @@ import {
   updateCache,
   type BuildCache,
 } from "./build-cache";
+import type { ChunkPlan } from "./chunk-planner";
+import { SHELL_EXTERNALS } from "./framework-peers";
 import {
   readInstalledVersion,
   sha256Hex,
@@ -28,8 +30,92 @@ import { pAll } from "./parallel";
 
 /** Re-export for internal CLI consumers (avoid direct platform dependency in consumers). */
 export type { BuildManifest, ModuleDescriptor };
-/** Re-export hash helpers for backward compatibility (deploy/remote-sync uses sha256OfFiles). */
+/** Re-export hash helpers for backward compatibility (deploy code uses sha256OfFiles). */
 export { sha256Hex, sha256OfFiles };
+/** Re-export externals so callers (shell builder) stay decoupled from framework-peers. */
+export { SHELL_EXTERNALS };
+
+/**
+ * Bun's automatic JSX transform emits `import { jsxDEV } from "react/jsx-dev-runtime"`
+ * regardless of NODE_ENV. React's production module exports `jsxDEV` as undefined
+ * (it's a debug-only symbol). At runtime in a production container this crashes
+ * the moment a JSX call is reached. The plugin redirects `react/jsx-dev-runtime`
+ * imports to a synthetic module that re-exports `jsx` as `jsxDEV` from the
+ * production jsx-runtime — semantically equivalent at runtime, no debug data.
+ *
+ * Applied to BOTH browser and server bundles. Server bundles may import
+ * JSX-typed Trans/translation components from workspace deps; without the
+ * shim, loadServerContext fails on any server bundle that touches them.
+ */
+/**
+ * Force every `react*` and `react-dom*` import to resolve from the workspace
+ * root's node_modules. Without this, monorepo symlinks (npm-linked
+ * @arcote.tech/platform → arc workspace's react@A; @ndt/* → ndt workspace's
+ * react@B) produce two physical React copies in the bundle. Two copies =
+ * two `ReactSharedInternals` = null dispatcher = "Invalid hook call".
+ *
+ * We resolve once from `rootDir` and pin every subsequent React-related
+ * specifier to that absolute path, defeating Bun's per-importer resolution.
+ */
+/**
+ * Override `"sideEffects": false` for workspace + framework packages.
+ *
+ * Arc modules auto-register via top-level `module(...).build()` — that IS a
+ * side effect. But packages typically ship with `"sideEffects": false` (a
+ * good default for treeshake-friendly libs). Two failure modes follow:
+ *
+ *   1. Side-effect-only imports (`import "@ndt/strategy"`) get tree-shaken
+ *      to nothing — module never registers.
+ *   2. Splitting heuristics treat such modules as freely duplicatable, so
+ *      a context-package singleton (`WorkspaceContext = createContext(...)`)
+ *      ends up cloned per entry; `useWorkspace()` can't find the provider.
+ *
+ * Bun.build accepts `sideEffects: true` in `onResolve` return values (same
+ * as esbuild) — that flag overrides package.json. We flip the bit for any
+ * `@ndt/*` or `@arcote.tech/*` import. React itself is fine; it doesn't
+ * use sideEffects:false in a problematic way.
+ */
+
+function singleReactPlugin(rootDir: string): import("bun").BunPlugin {
+  const reactPkgs = ["react", "react-dom", "react-dom/client", "react/jsx-runtime"];
+  return {
+    name: "single-react",
+    setup(build) {
+      const resolved = new Map<string, string>();
+      for (const spec of reactPkgs) {
+        try {
+          resolved.set(spec, Bun.resolveSync(spec, rootDir));
+        } catch {
+          // If consumer doesn't have it installed, leave Bun's default behavior.
+        }
+      }
+      build.onResolve({ filter: /^(react|react-dom|react-dom\/client|react\/jsx-runtime)$/ }, (args) => {
+        const path = resolved.get(args.path);
+        return path ? { path } : null;
+      });
+    },
+  };
+}
+
+function jsxDevShimPlugin(): import("bun").BunPlugin {
+  return {
+    name: "jsx-dev-runtime-shim",
+    setup(build) {
+      build.onResolve({ filter: /^react\/jsx-dev-runtime$/ }, () => ({
+        path: "react-jsx-dev-runtime-shim",
+        namespace: "jsx-dev-shim",
+      }));
+      build.onLoad({ filter: /.*/, namespace: "jsx-dev-shim" }, () => ({
+        contents: `import { jsx, jsxs, Fragment } from "react/jsx-runtime";
+export const jsxDEV = jsx;
+export const jsxsDEV = jsxs;
+export { Fragment };
+`,
+        loader: "ts",
+      }));
+    },
+  };
+}
 
 /** Clients that a context package is built for. */
 const CONTEXT_CLIENTS = [
@@ -37,21 +123,6 @@ const CONTEXT_CLIENTS = [
   { name: "browser", target: "browser" as const, defines: { ONLY_SERVER: "false", ONLY_BROWSER: "true", ONLY_CLIENT: "true" } },
 ];
 
-/** Packages that shell provides — modules import them but don't bundle them. */
-export const SHELL_EXTERNALS = [
-  "react",
-  "react-dom",
-  "react/jsx-runtime",
-  "react/jsx-dev-runtime",
-  "@arcote.tech/arc",
-  "@arcote.tech/arc-ds",
-  "@arcote.tech/arc-react",
-  "@arcote.tech/arc-auth",
-  "@arcote.tech/arc-utils",
-  "@arcote.tech/arc-workspace",
-  "@arcote.tech/platform",
-];
-
 export interface WorkspacePackage {
   name: string;
   path: string;
@@ -206,9 +277,26 @@ async function buildContextClient(
 
   console.log(`  building: ${pkg.name} (${client.name})`);
 
+  // Externals: framework peers + npm dependencies + workspace deps.
+  //
+  // Workspace deps used to be bundled inline (because the deploy image has
+  // no workspace symlinks). The consequence: every context package's dist
+  // carried its own copy of every workspace dep — `@ndt/strategy/dist`
+  // shipped `@ndt/workspace` inlined, `@ndt/content/dist` shipped another
+  // copy, etc. At deploy-build time the top-level Bun.build saw N
+  // pre-inlined copies and could no longer dedupe them — context-package
+  // singletons (e.g. `WorkspaceContext = createContext`) duplicated per
+  // entry, breaking `useWorkspace()` provider lookup.
+  //
+  // Treating workspace deps as `external` makes per-package dist emit bare
+  // specifiers (`import { workspace } from "@ndt/workspace"`), which the
+  // browser-side Bun.build then resolves ONCE across all entries → single
+  // module instance, splitting hoists into a shared chunk. The deploy
+  // image is unaffected: the browser bundle is self-contained at that
+  // layer (we only ship the final chunks, not per-package dist/browser).
   const peerDeps = Object.keys(pkg.packageJson.peerDependencies ?? {});
-  const deps = Object.keys(pkg.packageJson.dependencies ?? {});
-  const externals = [...peerDeps, ...deps];
+  const allDeps = (pkg.packageJson.dependencies ?? {}) as Record<string, string>;
+  const externals = [...peerDeps, ...Object.keys(allDeps)];
 
   const result = await Bun.build({
     entrypoints: [pkg.entrypoint],
@@ -217,6 +305,7 @@ async function buildContextClient(
     format: "esm",
     naming: "index.[ext]",
     external: externals,
+    plugins: [jsxDevShimPlugin()],
     define: client.defines,
   });
 
@@ -278,140 +367,267 @@ export async function buildContextPackages(
   return { declarationErrors };
 }
 
+
 // ---------------------------------------------------------------------------
-// Modules bundle — single Bun.build of all wrapper re-exports
+// Browser app build — one Bun.build with multiple entrypoints.
+//
+// Replaces the previous architecture of 25+ separate Bun.build calls (per
+// shell peer + per context package × client + per token chunk group + initial
+// bundle). The big win is `splitting: true` across ALL entries:
+//
+//   - workspace context, framework, common deps land in ONE shared chunk
+//     referenced by both `initial.*.js` and `<token>.*.js`. No more multi-
+//     instance bugs (e.g. createWorkspace().build() running twice, each
+//     producing its own aggregate refs).
+//   - No importmap. Nothing is external — Bun bundles everything inline,
+//     dedups via shared chunks. The HTML loads `initial.<hash>.js` and that
+//     pulls shared chunks as needed.
+//   - Token chunks are first-class entries (`<token-name>.<hash>.js`) that
+//     side-effect-import all their member modules. Server signs the URL for
+//     the entry; shared chunks ride along unsigned (filenames are content-
+//     addressed so they're not enumerable without the manifest).
+//
+// Output layout under <outDir> = `<arcDir>/browser/`:
+//   initial.<hash>.js                ← public modules + bootstrap entry
+//   <tokenName>.<hash>.js × N        ← one per token group
+//   chunk-<hash>.js × N              ← auto-shared (workspace ctx, framework, etc.)
 // ---------------------------------------------------------------------------
 
-interface ModulesBundleResult {
-  modules: ModuleDescriptor[];
-  cached: boolean;
+export interface BrowserGroupEntry {
+  /** Filename relative to outDir (`<token>.<hash>.js`). */
+  readonly file: string;
+  readonly hash: string;
+  /** Module names registered by this group (for manifest filterability). */
+  readonly modules: readonly string[];
 }
 
-/**
- * Bundle all workspace packages into ESM chunks for the platform shell.
- * Cached as a single unit — any source change in any package invalidates.
- */
-export async function buildModulesBundle(
+export interface BrowserAppResult {
+  readonly initial: { file: string; hash: string };
+  /** Keyed by token.name. `initial` is NOT here — it's separate. */
+  readonly groups: Record<string, BrowserGroupEntry>;
+  /** Auto-shared chunks emitted by Bun.build splitting. Public, unsigned. */
+  readonly sharedChunks: readonly string[];
+  readonly cached: boolean;
+}
+
+export async function buildBrowserApp(
   rootDir: string,
   outDir: string,
-  packages: WorkspacePackage[],
+  plan: ChunkPlan,
   cache: BuildCache,
   noCache: boolean,
-): Promise<ModulesBundleResult> {
+  i18nCollector: Map<string, Set<string>>,
+): Promise<BrowserAppResult> {
   mkdirSync(outDir, { recursive: true });
 
-  const unitId = "modules-bundle";
+  const publicMembers = plan.groups.get("public") ?? [];
+  const protectedGroups = plan.chunks
+    .filter((c) => c !== "public")
+    .map((c) => ({ name: c, members: plan.groups.get(c) ?? [] }))
+    .filter((g) => g.members.length > 0);
 
-  // Per-package source hash — gives us deterministic input identity even though
-  // we run a single Bun.build for the whole bundle (chunk sharing wins).
-  const pkgHashes = packages.map((p) => ({
-    name: p.name,
-    safeName: basename(p.path),
-    srcHash: pkgSourceHash(p),
-  }));
+  const unitId = "browser-app";
 
+  // Cache key spans every package's source plus the build config that
+  // matters. If anything changes, full rebuild.
+  const allMembers: { name: string; group: string; srcHash: string }[] = [];
+  for (const m of publicMembers) {
+    allMembers.push({ name: m.pkg.name, group: "public", srcHash: pkgSourceHash(m.pkg) });
+  }
+  for (const g of protectedGroups) {
+    for (const m of g.members) {
+      allMembers.push({ name: m.pkg.name, group: g.name, srcHash: pkgSourceHash(m.pkg) });
+    }
+  }
   const inputHash = sha256OfJson({
-    pkgHashes,
-    externals: SHELL_EXTERNALS,
+    members: allMembers,
+    groups: [
+      "initial",
+      ...protectedGroups.map((g) => g.name).sort(),
+    ],
     define: { ONLY_SERVER: "false", ONLY_BROWSER: "true", ONLY_CLIENT: "true" },
   });
 
-  // Cache hit → reconstruct module descriptors from existing files in outDir.
   if (!noCache && isCacheHit(cache, unitId, inputHash)) {
-    const existing = cache.units[unitId]?.outputHashes ?? {};
-    const modules: ModuleDescriptor[] = [];
-    for (const { safeName, name } of pkgHashes) {
-      const file = `${safeName}.js`;
-      const filePath = join(outDir, file);
-      if (!existsSync(filePath)) {
-        // Output missing despite hash match — fall through to rebuild.
-        console.log(`  rebuilding modules-bundle: output ${file} missing`);
-        return await actuallyBuild();
+    const cached = cache.units[unitId]?.outputHashes;
+    if (cached?._manifest) {
+      try {
+        const m = JSON.parse(cached._manifest) as BrowserAppResult;
+        const allFiles = [
+          m.initial.file,
+          ...Object.values(m.groups).map((g) => g.file),
+          ...m.sharedChunks,
+        ];
+        if (allFiles.every((f) => existsSync(join(outDir, f)))) {
+          console.log(`  ✓ cached: ${unitId}`);
+          return { ...m, cached: true };
+        }
+      } catch {
+        // fall through to rebuild
       }
-      modules.push({ file, name, hash: existing[safeName] ?? sha256Hex(readFileSync(filePath)) });
     }
-    console.log(`  ✓ cached: modules-bundle (${modules.length} module(s))`);
-    return { modules, cached: true };
   }
 
-  return await actuallyBuild();
-
-  async function actuallyBuild(): Promise<ModulesBundleResult> {
-    console.log(`  building: modules-bundle (${packages.length} package(s))`);
+  console.log(
+    `  building: ${unitId} (initial: ${publicMembers.length} modules, groups: ${protectedGroups
+      .map((g) => `${g.name}=${g.members.length}`)
+      .join(",") || "none"})`,
+  );
 
-    const tmpDir = join(outDir, "_entries");
-    mkdirSync(tmpDir, { recursive: true });
+  // Wipe outDir so stale-hash files don't linger.
+  if (existsSync(outDir)) {
+    for (const f of readdirSync(outDir)) {
+      if (f.endsWith(".js")) rmSync(join(outDir, f), { force: true });
+    }
+  }
 
-    const entrypoints: string[] = [];
-    const fileToName = new Map<string, string>();
+  const tmpDir = join(outDir, "_entries");
+  mkdirSync(tmpDir, { recursive: true });
 
-    for (const pkg of packages) {
-      const safeName = basename(pkg.path);
-      const moduleName = pkg.name.includes("/") ? pkg.name.split("/").pop()! : pkg.name;
-      fileToName.set(safeName, moduleName);
+  const importLines = (pkgs: { pkg: { name: string } }[]): string =>
+    pkgs.map((m) => `import "${m.pkg.name}";`).join("\n");
 
-      const wrapperFile = join(tmpDir, `${safeName}.ts`);
-      writeFileSync(wrapperFile, `export * from "${pkg.name}";\n`);
-      entrypoints.push(wrapperFile);
-    }
+  const initialEntry = join(tmpDir, "initial.ts");
+  writeFileSync(
+    initialEntry,
+    `${importLines(publicMembers)}\nexport { startApp } from "@arcote.tech/platform";\n`,
+  );
 
-    const i18nCollector = new Map<string, Set<string>>();
+  const entryPaths: string[] = [initialEntry];
+  const groupModuleMap = new Map<string, string[]>();
+  for (const g of protectedGroups) {
+    const entry = join(tmpDir, `${g.name}.ts`);
+    writeFileSync(entry, `${importLines(g.members)}\n`);
+    entryPaths.push(entry);
+    groupModuleMap.set(g.name, g.members.map((m) => m.moduleName));
+  }
 
-    const arcExternalPlugin: import("bun").BunPlugin = {
-      name: "arc-external",
-      setup(build) {
-        build.onResolve({ filter: /^@arcote\.tech\// }, (args) => {
-          return { path: args.path, external: true };
-        });
-      },
-    };
+  // ---------------------------------------------------------------------
+  // Temporarily flip `"sideEffects"` on every workspace package's
+  // package.json from `false` to `true` for the duration of the build.
+  //
+  // Why: Arc modules auto-register via top-level `module(...).build()` —
+  // a real side effect. But packages ship with `"sideEffects": false` (a
+  // good ESM-library default), which makes Bun.build:
+  //   (1) tree-shake side-effect-only imports → module().build() never runs,
+  //   (2) freely duplicate the module across entry chunks → context
+  //       singletons (`createContext`) get cloned, breaking provider lookup.
+  //
+  // Bun has no plugin hook to override package.json `sideEffects` and
+  // `build.resolve()` is not implemented (Bun#2771), so the cleanest
+  // reliable lever is a tiny on-disk patch with guaranteed restore.
+  // ---------------------------------------------------------------------
+  const allMemberPkgs = new Map<string, WorkspacePackage>();
+  for (const m of publicMembers) allMemberPkgs.set(m.pkg.name, m.pkg);
+  for (const g of protectedGroups)
+    for (const m of g.members) allMemberPkgs.set(m.pkg.name, m.pkg);
+
+  const patchedPkgJsons: { path: string; original: string }[] = [];
+  for (const pkg of allMemberPkgs.values()) {
+    const pkgJsonPath = join(pkg.path, "package.json");
+    if (!existsSync(pkgJsonPath)) continue;
+    const original = readFileSync(pkgJsonPath, "utf-8");
+    const parsed = JSON.parse(original);
+    if (parsed.sideEffects === true) continue; // already correct
+    parsed.sideEffects = true;
+    writeFileSync(pkgJsonPath, JSON.stringify(parsed, null, 2) + "\n");
+    patchedPkgJsons.push({ path: pkgJsonPath, original });
+  }
 
-    const result = await Bun.build({
-      entrypoints,
+  let result;
+  try {
+    result = await Bun.build({
+      entrypoints: entryPaths,
       outdir: outDir,
+      // splitting:true is the whole point: shared deps (workspace context,
+      // framework, lucide, etc.) land in chunk-<hash>.js, referenced by both
+      // initial and token-group entries. One instance, no provider duplication.
       splitting: true,
       format: "esm",
       target: "browser",
-      external: SHELL_EXTERNALS,
-      plugins: [arcExternalPlugin, i18nExtractPlugin(i18nCollector, rootDir)],
+      // No externals. Framework peers (react, @arcote.tech/*) get bundled and
+      // deduped into shared chunks. No importmap needed in the HTML.
+      external: [],
+      plugins: [
+        singleReactPlugin(rootDir),
+        jsxDevShimPlugin(),
+        i18nExtractPlugin(i18nCollector, rootDir),
+      ],
       naming: "[name].[ext]",
       define: {
         ONLY_SERVER: "false",
         ONLY_BROWSER: "true",
         ONLY_CLIENT: "true",
+        // CRITICAL: React's index.js does `if (process.env.NODE_ENV === 'production') require('./cjs/react.production.js') else require('./cjs/react.development.js')`.
+        // Without inlining NODE_ENV at build time Bun bundles BOTH branches → TWO ReactSharedInternals → multi-instance "Invalid hook call" crash.
+        "process.env.NODE_ENV": '"production"',
       },
     });
+  } finally {
+    // Always restore — a crash here MUST NOT leave the user with mutated
+    // workspace package.json files.
+    for (const p of patchedPkgJsons) writeFileSync(p.path, p.original);
+  }
 
-    if (!result.success) {
-      console.error("Modules bundle build failed:");
-      for (const log of result.logs) console.error(log);
-      throw new Error("Module build failed");
-    }
+  rmSync(tmpDir, { recursive: true, force: true });
 
-    // i18n extraction → write/update .po files (compileAllCatalogs handles .json).
-    await finalizeTranslations(rootDir, join(outDir, ".."), i18nCollector);
-
-    rmSync(tmpDir, { recursive: true, force: true });
-
-    const outputHashes: Record<string, string> = {};
-    const modules: ModuleDescriptor[] = result.outputs
-      .filter((o) => o.kind === "entry-point")
-      .map((o) => {
-        const file = basename(o.path);
-        const safeName = file.replace(/\.js$/, "");
-        const bytes = readFileSync(o.path);
-        const hash = sha256Hex(bytes);
-        outputHashes[safeName] = hash;
-        return {
-          file,
-          name: fileToName.get(safeName) ?? safeName,
+  if (!result.success) {
+    for (const log of result.logs) console.error(log);
+    throw new Error("Browser app build failed");
+  }
+
+  // Bun's `[name]` in naming preserves entry filename without hash. We add
+  // content hashes ourselves so identical bytes produce identical URLs across
+  // deploys (good for browser caching). Shared chunks already have a hash in
+  // their name (Bun auto-emits `chunk-<hash>.js`); we leave those alone.
+  let initialFile = "";
+  let initialHash = "";
+  const groups: Record<string, BrowserGroupEntry> = {};
+  const sharedChunks: string[] = [];
+
+  for (const out of result.outputs) {
+    const name = basename(out.path);
+    if (out.kind === "entry-point") {
+      const bytes = readFileSync(out.path);
+      const hash = sha256Hex(bytes).slice(0, 16);
+      const stem = name.replace(/\.js$/, "");
+      const finalName = `${stem}.${hash}.js`;
+      const finalPath = join(outDir, finalName);
+      rmSync(finalPath, { force: true });
+      writeFileSync(finalPath, bytes);
+      rmSync(out.path, { force: true });
+
+      if (stem === "initial") {
+        initialFile = finalName;
+        initialHash = hash;
+      } else {
+        groups[stem] = {
+          file: finalName,
           hash,
+          modules: groupModuleMap.get(stem) ?? [],
         };
-      });
+      }
+    } else if (out.kind === "chunk") {
+      sharedChunks.push(name);
+    }
+  }
 
-    updateCache(cache, unitId, inputHash, { outputHashes });
-    return { modules, cached: false };
+  if (!initialFile) {
+    throw new Error("Browser app build: initial entry not found in outputs");
   }
+
+  const manifest: BrowserAppResult = {
+    initial: { file: initialFile, hash: initialHash },
+    groups,
+    sharedChunks,
+    cached: false,
+  };
+
+  updateCache(cache, unitId, inputHash, {
+    outputHashes: { _manifest: JSON.stringify(manifest) },
+  });
+
+  return manifest;
 }
 
 // ---------------------------------------------------------------------------

package/src/commands/platform-build.ts

@@ -3,5 +3,6 @@ import { buildAll, ok, resolveWorkspace } from "../platform/shared";
 export async function platformBuild(opts: { noCache?: boolean } = {}): Promise<void> {
   const ws = resolveWorkspace();
   const manifest = await buildAll(ws, { noCache: opts.noCache });
-  ok(`Platform built — ${manifest.modules.length} module(s)`);
+  const groupCount = Object.keys(manifest.groups).length;
+  ok(`Platform built — initial + ${groupCount} group(s)`);
 }