@akanjs/devkit 3.0.0-beta.9 → 3.0.0

package/transforms/externalizeFrameworkPlugin.ts

@@ -2,64 +2,19 @@ import path from "node:path";
 import type { BunPlugin } from "bun";
 import type { App } from "../commandDecorators";
 
-/**
- * Keep framework/runtime singletons external while bundling authored
- * workspace sources and ordinary npm dependencies into the pages bundle.
- *
- * Why a plugin instead of `Bun.build({ external })` or
- * `Bun.build({ packages: "external" })`:
- *   - `packages: "external"` externalizes every bare specifier, including
- *     `@apps/*` / `@libs/*` — workspace packages that must stay bundled
- *     so the `"use client"` plugin can rewrite their exports — and ordinary
- *     npm dependencies like `dayjs` / `tailwind-merge`, which the production runtime
- *     package.json does not install for the SSR pages artifact.
- *   - Top-level `external: [...]` applies to macro-time module resolution
- *     too; any `with { type: "macro" }` import chain that transitively
- *     resolves `react` during build then fails with `ENOENT "react"`.
- *
- * An `onResolve` plugin only participates in the output-graph walk, so
- * macros evaluate against the real modules in node_modules while the
- * emitted bundle keeps bare specifiers only for runtime singletons that
- * are installed in the generated production package.json.
- *
- * Externalization rules (applied in order):
- *   1. Relative specifiers (`./`, `../`) are NEVER externalized — they
- *      always resolve to the current package's source tree and must be
- *      inlined so transitive `"use client"` stubs work.
- *   2. Specifiers listed in `include` (workspace aliases like
- *      `@apps/*`, `@libs/*`) are NEVER externalized.
- *   3. React / RSC runtime packages and build-time tooling packages are
- *      externalized so the runtime supplies a single shared instance.
- *   4. Other bare npm packages are bundled so the Docker runtime does not
- *      need to install every transitive page dependency separately.
- */
 export interface ExternalizeFrameworkOptions {
   app: App;
-  /**
-   * Prefixes that should be BUNDLED (kept internal). Defaults to
-   * `@apps/` and `@libs/` which are the workspace aliases used by the
-   * framework's app template.
-   */
+  /** Prefixes to bundle rather than externalize; defaults to `akanjs/`, `@apps/`, `@libs/`. */
   include?: string[];
-  /**
-   * Extra bare specifiers to force-externalize beyond the allowlist
-   * defaults. Not commonly needed since the default rule already
-   * externalizes every non-workspace specifier.
-   */
+  /** Bare specifiers to force-externalize, overriding `include`. */
   extra?: string[];
 }
 
-// Workspace package prefixes that must be BUNDLED so their sources go
-// through the barrel-imports + `"use client"` transforms. Without this
-// the RSC worker would resolve them at runtime — skipping the
-// transforms entirely, which re-introduces the react-dom/client
-// side-effects we wanted to strip from the server graph.
+// Bundled so they pass the barrel and `"use client"` transforms; resolved at runtime they would drag
+// react-dom/client side effects into the server graph.
 const DEFAULT_INCLUDE = ["akanjs/", "@apps/", "@libs/"];
 
-// Packages that must stay external even when a broad allowlist would
-// otherwise bundle them. These are runtime hosts or shared singleton
-// framework packages; ordinary npm dependencies intentionally fall through
-// to Bun's resolver and get bundled.
+// Runtime hosts and singleton framework packages stay external; ordinary npm dependencies are bundled.
 const DEFAULT_EXCLUDE_EXACT = new Set<string>(["akanjs/webkit", "@akanjs/cli", "@akanjs/devkit"]);
 const DEFAULT_EXCLUDE_PREFIX = ["@akanjs/cli/", "@akanjs/devkit/"];
 const OPTIONAL_BACKEND_EXTERNAL_EXACT = new Set<string>([
@@ -81,19 +36,17 @@ const RUNTIME_EXTERNAL_EXACT = new Set<string>([
 ]);
 const RUNTIME_EXTERNAL_PREFIX = ["react-dom/", "react-server-dom-webpack/"];
 
-// File extensions Bun can load when a bare subpath points at an
-// extensionless path. Ordered to prefer TS over JS, since workspace
-// sources are authored in TypeScript.
+// TS before JS: workspace sources are authored in TypeScript.
 const CANDIDATE_EXTS = [".tsx", ".ts", ".jsx", ".js", ".mjs", ".cjs"];
 
+// Rejected `Bun.build` options: `external` also applies at macro time (ENOENT "react"), and `packages: "external"`
+// externalizes workspace and npm packages the runtime does not install. onResolve shapes only the output graph.
 export async function createExternalizeFrameworkPlugin(options: ExternalizeFrameworkOptions): Promise<BunPlugin> {
   const tsconfig = await options.app.getTsConfig();
   const includePrefixes = options.include ?? DEFAULT_INCLUDE;
   const extraExact = new Set(options.extra ?? []);
   const workspaceRoot = options.app.workspace.workspaceRoot;
   const tsconfigPaths = tsconfig.compilerOptions.paths ?? {};
-  // Pre-compute the tsconfig root-only entries (`akanjs/client` → …)
-  // so we can resolve their subpaths by concatenating the remainder.
   const rootEntries = Object.entries(tsconfigPaths)
     .filter(([k]) => !k.endsWith("/*"))
     .map(([k, v]) => ({ pkg: k, entryFile: v[0] ?? null }))
@@ -105,7 +58,6 @@ export async function createExternalizeFrameworkPlugin(options: ExternalizeFrame
 
   async function resolveWorkspaceSubpath(spec: string): Promise<string | null> {
     if (!workspaceRoot) return null;
-    // Wildcard `@apps/*` / `@libs/*` → direct filesystem path.
     for (const { prefix, replacements } of wildcardEntries) {
       if (!spec.startsWith(prefix)) continue;
       const suffix = spec.slice(prefix.length);
@@ -117,12 +69,8 @@ export async function createExternalizeFrameworkPlugin(options: ExternalizeFrame
         if (hit) return hit;
       }
     }
-    // Root-only tsconfig entries — resolve the subpath against the
-    // package directory. E.g. `akanjs/client` → `pkgs/akanjs/client/index.ts`
-    // so `akanjs/client/cookie` → `pkgs/akanjs/client/cookie`.
     for (const { pkg, entryFile } of rootEntries) {
-      if (spec !== pkg && !spec.startsWith(`${pkg}/`)) continue;
-      if (spec === pkg) continue; // the package root itself — let Bun's tsconfig resolver handle it
+      if (!spec.startsWith(`${pkg}/`)) continue;
       const suffix = spec.slice(pkg.length + 1);
       const pkgDir = path.dirname(path.resolve(workspaceRoot, entryFile));
       const candidate = path.join(pkgDir, suffix);
@@ -137,13 +85,8 @@ export async function createExternalizeFrameworkPlugin(options: ExternalizeFrame
     setup(build) {
       build.onResolve({ filter: /.*/ }, async (args) => {
         const spec = args.path;
-        // Relative imports always stay inlined — they anchor to the
-        // current package's source tree and cannot leak cross-package.
-        // `.` and `..` (without trailing slash) are valid relative
-        // specifiers too (equivalent to `./index` / `../index`).
         if (spec === "." || spec === ".." || spec.startsWith("./") || spec.startsWith("../") || spec.startsWith("/"))
           return undefined;
-        // Force-external first (overrides the include allowlist).
         if (extraExact.has(spec) || DEFAULT_EXCLUDE_EXACT.has(spec)) return { path: spec, external: true };
         for (const prefix of DEFAULT_EXCLUDE_PREFIX) {
           if (spec.startsWith(prefix)) return { path: spec, external: true };
@@ -153,38 +96,21 @@ export async function createExternalizeFrameworkPlugin(options: ExternalizeFrame
         for (const prefix of RUNTIME_EXTERNAL_PREFIX) {
           if (spec.startsWith(prefix)) return { path: spec, external: true };
         }
-        // Workspace allowlist — resolve the subpath to an absolute
-        // on-disk file so Bun.build can read it. Without this, bare
-        // specifiers like `akanjs/client/cookie` (produced by the
-        // barrel rewriter) fail Bun's default resolution (only root
-        // tsconfig-paths entry exists for `akanjs/client`) and get
-        // silently left as externals.
-        for (const prefix of includePrefixes) {
-          if (!spec.startsWith(prefix)) continue;
-          const resolved = await resolveWorkspaceSubpath(spec);
-          if (resolved) return { path: resolved };
-          // Fall through to let Bun attempt its own resolution for the
-          // package root (`akanjs/client`) — tsconfig `paths` handles
-          // that case directly.
-          return undefined;
-        }
-        // Everything else (ordinary npm dependencies like dayjs / tailwind-merge /
-        // immer) is bundled into the pages artifact.
-        return undefined;
+        // Bun resolves only root tsconfig `paths`, so a rewritten `akanjs/client/cookie` would silently stay external.
+        if (!includePrefixes.some((prefix) => spec.startsWith(prefix))) return undefined;
+        const resolved = await resolveWorkspaceSubpath(spec);
+        return resolved ? { path: resolved } : undefined;
       });
     },
   };
 }
 
 async function firstExisting(basePath: string): Promise<string | null> {
-  // Direct file with its own extension.
   if (await Bun.file(basePath).exists()) return basePath;
-  // Try each candidate extension.
   for (const ext of CANDIDATE_EXTS) {
     const candidate = `${basePath}${ext}`;
     if (await Bun.file(candidate).exists()) return candidate;
   }
-  // Directory with `index.<ext>` inside.
   for (const ext of CANDIDATE_EXTS) {
     const candidate = path.join(basePath, `index${ext}`);
     if (await Bun.file(candidate).exists()) return candidate;

package/transforms/moduleSyntax.ts

@@ -0,0 +1,32 @@
+export interface NamedItem {
+  imported: string;
+  local: string;
+  isType: boolean;
+}
+
+export const loaderFor = (absPath: string): "ts" | "tsx" | "js" | "jsx" => {
+  if (absPath.endsWith(".tsx")) return "tsx";
+  if (absPath.endsWith(".jsx")) return "jsx";
+  if (absPath.endsWith(".ts")) return "ts";
+  return "js";
+};
+
+export const parseNamedList = (listBody: string): NamedItem[] => {
+  const out: NamedItem[] = [];
+  for (const raw of listBody.split(",")) {
+    let rest = raw.trim();
+    if (!rest) continue;
+    let isType = false;
+    if (rest.startsWith("type ")) {
+      isType = true;
+      rest = rest.slice(5).trim();
+    }
+    const asMatch = /^(\w+)\s+as\s+(\w+)$/.exec(rest);
+    if (asMatch) {
+      out.push({ imported: asMatch[1] ?? "", local: asMatch[2] ?? "", isType });
+      continue;
+    }
+    if (/^\w+$/.test(rest)) out.push({ imported: rest, local: rest, isType });
+  }
+  return out;
+};

package/transforms/rscUseClientTransform.ts

@@ -1,35 +1,64 @@
 import path from "node:path";
+import ts from "typescript";
+import { loaderFor } from "./moduleSyntax";
 
-// Pure "use client" transform: when `source` starts with the `"use client"`
-// directive, replace its exports with `registerClientReference` stubs so the
-// RSC renderer can serialize them as client component references instead of
-// trying to run them on the server.
-
-// Matches `"use client"` or `'use client'` at the start of a file,
-// optionally after leading whitespace and JS comments.
 const USE_CLIENT_RE = /^\s*(?:\/\*[\s\S]*?\*\/\s*|\/\/[^\n]*\n\s*)*["']use client["']/;
 const IMPLICIT_ROOT_LAYOUT_RE =
   /[/\\]\.akan[/\\]generated[/\\](?:implicit-root-layout|root-layouts[/\\].*__root_layout)\.(tsx|ts|jsx|js)$/;
+const STAR_REEXPORT_HINT_RE = /\bexport\s*\*\s*from\b/;
 
 export interface UseClientTransformArgs {
   path: string;
   workspaceRoot?: string;
+  /** Told each `"use client"` module's export names, the only part of it the server graph holds. */
+  onClientModule?: (path: string, exports: string[]) => void;
 }
 
+export const hasUseClientDirective = (source: string): boolean => USE_CLIENT_RE.test(source);
+
 export function toClientReferencePath(absPath: string, workspaceRoot: string): string {
   return path.relative(path.resolve(workspaceRoot), path.resolve(absPath)).split(path.sep).join("/");
 }
 
-/**
- * Returns the stubbed module source if `source` is a client module, else null.
- * The returned source is TypeScript-compatible (loader "ts" is safe).
- */
+const starReexportSpecifiers = (source: string, filePath: string) =>
+  ts
+    .createSourceFile(filePath, source, ts.ScriptTarget.Latest)
+    .statements.filter(
+      (statement): statement is ts.ExportDeclaration & { moduleSpecifier: ts.StringLiteral } =>
+        ts.isExportDeclaration(statement) &&
+        !statement.exportClause &&
+        !statement.isTypeOnly &&
+        !!statement.moduleSpecifier &&
+        ts.isStringLiteral(statement.moduleSpecifier),
+    )
+    .map((statement) => statement.moduleSpecifier.text);
+
+// `Bun.Transpiler.scan` reports no name through `export *`, so the server could register none of a star's names as
+// client references; they would be undefined in a server component. Refused as Next.js refuses it.
+export const scanUseClientExports = (source: string, filePath: string, workspaceRoot?: string): string[] => {
+  const stars =
+    USE_CLIENT_RE.test(source) && STAR_REEXPORT_HINT_RE.test(source) ? starReexportSpecifiers(source, filePath) : [];
+  if (stars.length) {
+    const file = workspaceRoot ? toClientReferencePath(filePath, workspaceRoot) : filePath;
+    const listed = stars.slice(0, 3).map((specifier) => `\`export * from ${JSON.stringify(specifier)}\``);
+    const written = stars.length > 3 ? `${listed.join(", ")} (and ${stars.length - 3} more)` : listed.join(", ");
+    throw new Error(
+      `${file} is a "use client" module, so it cannot ${written}: the server sees only the names a client module ` +
+        `declares, and a star re-export declares none. Re-export them by name — \`export { … } from ${JSON.stringify(stars[0])}\`.`,
+    );
+  }
+  return new Bun.Transpiler({ loader: loaderFor(filePath) }).scan(source).exports;
+};
+
+/** `null` unless `source` is a `"use client"` module; the stub source is valid under loader `"ts"`. */
 export function transformUseClient(source: string, args: UseClientTransformArgs): string | null {
   if (!USE_CLIENT_RE.test(source)) return null;
   if (IMPLICIT_ROOT_LAYOUT_RE.test(args.path)) return null;
-  const transpiler = new Bun.Transpiler({ loader: loaderFor(args.path) });
-  const { exports } = transpiler.scan(source);
+  const exports = scanUseClientExports(source, args.path, args.workspaceRoot);
+  //? Not reported without exports: the module then stays in the server bundle as it is, so a save of it changes what
+  //? the server runs, which a client module's edit that kept its export names does not.
   if (exports.length === 0) return null;
+  args.onClientModule?.(args.path, exports);
 
   const referencePath = args.workspaceRoot ? toClientReferencePath(args.path, args.workspaceRoot) : args.path;
   const filePathLit = JSON.stringify(referencePath);
@@ -50,10 +79,3 @@ export function transformUseClient(source: string, args: UseClientTransformArgs)
 
   return lines.join("\n");
 }
-
-function loaderFor(absPath: string): "ts" | "tsx" | "js" | "jsx" {
-  if (absPath.endsWith(".tsx")) return "tsx";
-  if (absPath.endsWith(".jsx")) return "jsx";
-  if (absPath.endsWith(".ts")) return "ts";
-  return "js";
-}

package/transforms/serverEnvPlugin.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import { tempDirs, writeText as write } from "../testHelpers";
+import { createServerEnvPlugin } from "./serverEnvPlugin";
+
+const makeTempRoot = tempDirs("akan-devkit-server-env-");
+const environments = ["local", "testing", "debug", "develop", "main", "qa"];
+
+const writeApp = async (root: string) => {
+  const envDir = path.join(root, "apps/demo/env");
+  await write(
+    path.join(envDir, "env.server.ts"),
+    [
+      ...environments.map((name) => `import { env as ${name} } from "./env.server.${name}";`),
+      `const envConfigs = { ${environments.join(", ")} };`,
+      'const currentEnv = process.env.AKAN_PUBLIC_ENV ?? "local";',
+      "export const env = envConfigs[currentEnv as keyof typeof envConfigs];",
+      "",
+    ].join("\n"),
+  );
+  await write(path.join(envDir, "env.server.type.ts"), 'export const libEnv = { shared: "shared-value" };\n');
+  for (const name of environments)
+    await write(
+      path.join(envDir, `env.server.${name}.ts`),
+      [
+        'import { libEnv } from "./env.server.type";',
+        `export const env = { ...libEnv, secret: "${name}-secret" };`,
+        `export default "${name}-default";`,
+        "",
+      ].join("\n"),
+    );
+  const entry = path.join(root, "apps/demo/server.ts");
+  await write(entry, 'import { env } from "./env/env.server";\nconsole.info(JSON.stringify({ ...env }));\n');
+  return { envDir, entry };
+};
+
+const build = async (root: string, environment: string) => {
+  const { envDir, entry } = await writeApp(root);
+  const result = await Bun.build({
+    entrypoints: [entry],
+    outdir: path.join(root, "out"),
+    target: "bun",
+    plugins: [createServerEnvPlugin({ envDir, environment, environments })],
+  });
+  expect(result.success).toBe(true);
+  const output = result.outputs.find((artifact) => artifact.kind === "entry-point");
+  if (!output) throw new Error("no entry output");
+  return { file: output.path, text: await output.text() };
+};
+
+const run = (file: string, environment: string) =>
+  Bun.spawnSync([process.execPath, file], { env: { ...process.env, AKAN_PUBLIC_ENV: environment } });
+
+describe("createServerEnvPlugin", () => {
+  test("bundles only the environment the image runs", async () => {
+    const { text } = await build(await makeTempRoot(), "main");
+    expect(text).toContain("main-secret");
+    expect(text).toContain("shared-value");
+    for (const name of environments.filter((name) => name !== "main")) {
+      expect(text).not.toContain(`${name}-secret`);
+      expect(text).not.toContain(`${name}-default`);
+    }
+  });
+
+  test("the built environment boots with its own values", async () => {
+    const { file } = await build(await makeTempRoot(), "main");
+    const proc = run(file, "main");
+    expect(proc.exitCode).toBe(0);
+    expect(JSON.parse(proc.stdout.toString())).toEqual({ shared: "shared-value", secret: "main-secret" });
+  });
+
+  test("another environment refuses to boot and names the build to make", async () => {
+    const { file } = await build(await makeTempRoot(), "main");
+    const proc = run(file, "develop");
+    expect(proc.exitCode).not.toBe(0);
+    expect(proc.stderr.toString()).toContain(
+      "env/env.server.develop.ts is not in this build: `akan build` bundles the server env of AKAN_PUBLIC_ENV=main alone",
+    );
+    expect(proc.stderr.toString()).toContain(
+      "To run develop, build for it: AKAN_PUBLIC_ENV=develop in the workspace's .env, which outranks the shell, or --env develop on a desktop or mobile build.",
+    );
+  });
+
+  test("a custom branch is its own environment", async () => {
+    const { text } = await build(await makeTempRoot(), "qa");
+    expect(text).toContain("qa-secret");
+    expect(text).not.toContain("main-secret");
+  });
+
+  test("leaves env files outside the app's env directory alone", async () => {
+    const root = await makeTempRoot();
+    const other = path.join(root, "libs/shared/env/env.server.testing.ts");
+    await write(other, 'export const env = { secret: "lib-testing-secret" };\n');
+    const { envDir, entry } = await writeApp(root);
+    await write(entry, `import { env } from ${JSON.stringify(other)};\nconsole.info(env.secret);\n`);
+    const result = await Bun.build({
+      entrypoints: [entry],
+      target: "bun",
+      plugins: [createServerEnvPlugin({ envDir, environment: "main", environments })],
+    });
+    expect(await result.outputs[0]?.text()).toContain("lib-testing-secret");
+  });
+});

package/transforms/serverEnvPlugin.ts

@@ -0,0 +1,41 @@
+import { existsSync, realpathSync } from "node:fs";
+import path from "node:path";
+import type { BunPlugin } from "bun";
+
+export interface ServerEnvPluginOptions {
+  envDir: string;
+  /** The environment the image runs: its Dockerfile fixes `AKAN_PUBLIC_ENV` to it. */
+  environment: string;
+  environments: Iterable<string>;
+}
+
+const escapeRegExp = (value: string) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+//* `env.server.ts` imports every environment's file, so an image would hand out the secrets of each environment it
+//* never runs. Every file but the image's own is swapped for exports that refuse to be read.
+export const createServerEnvPlugin = ({ envDir, environment, environments }: ServerEnvPluginOptions): BunPlugin => {
+  const others = [...new Set(environments)].filter((name) => name !== environment);
+  //? Bun hands onLoad the real path, which differs from the given one under a symlink (macOS's /var -> /private/var).
+  const dirs = new Set([path.resolve(envDir), existsSync(envDir) ? realpathSync.native(envDir) : envDir]);
+  const names = others.map(escapeRegExp).join("|");
+  const filter = new RegExp(`^(?:${[...dirs].map(escapeRegExp).join("|")})[\\\\/]env\\.server\\.(?:${names})\\.ts$`);
+  return {
+    name: "akan-server-env",
+    setup(build) {
+      if (!others.length) return;
+      build.onLoad({ filter }, async (args) => {
+        const name = path.basename(args.path, ".ts").slice("env.server.".length);
+        const { exports } = new Bun.Transpiler({ loader: "ts" }).scan(await Bun.file(args.path).text());
+        const message = `env/env.server.${name}.ts is not in this build: \`akan build\` bundles the server env of AKAN_PUBLIC_ENV=${environment} alone, the environment its image runs. To run ${name}, build for it: AKAN_PUBLIC_ENV=${name} in the workspace's .env, which outranks the shell, or --env ${name} on a desktop or mobile build.`;
+        return {
+          loader: "js",
+          contents: [
+            `const refuse = () => { throw new Error(${JSON.stringify(message)}); };`,
+            "const unbuilt = new Proxy({}, { get: refuse, has: refuse, ownKeys: refuse, getOwnPropertyDescriptor: refuse });",
+            `export { ${exports.map((exported) => `unbuilt as ${JSON.stringify(exported)}`).join(", ")} };`,
+          ].join("\n"),
+        };
+      });
+    },
+  };
+};