@akanjs/devkit 1.0.20 → 2.1.0-rc.1

package/frontendBuild/hmrWatcher.ts

@@ -0,0 +1,102 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { Logger } from "akanjs/common";
+import type { ChangeBatch, ChangeKind } from "akanjs/server";
+import { HmrChangeClassifier } from "./hmrChangeClassifier";
+
+export type { ChangeBatch, ChangeKind };
+
+export interface WatcherOptions {
+  roots: string[];
+  debounceMs?: number;
+  logger: Logger;
+  onBatch: (batch: ChangeBatch) => void | Promise<void>;
+}
+
+/**
+ * Recursive filesystem watcher with debounced batching. We deliberately keep
+ * classification coarse (`code` / `css` / `config`) so the orchestrator can
+ * decide whether a full rebuild-and-reload or a narrower action (e.g. CSS
+ * hot-swap) is sufficient.
+ */
+export class HmrWatcher {
+  readonly #roots: string[];
+  readonly #debounceMs: number;
+  readonly #onBatch: WatcherOptions["onBatch"];
+  readonly #logger: Logger;
+  readonly #watchers: fs.FSWatcher[] = [];
+  readonly #pending = new Map<string, Exclude<ChangeKind, "ignore">>();
+  readonly #classifier = new HmrChangeClassifier();
+  #timer: ReturnType<typeof setTimeout> | null = null;
+  #stopped = false;
+  #flushing = false;
+
+  constructor(opts: WatcherOptions) {
+    this.#roots = [...new Set(opts.roots.map((r) => path.resolve(r)))];
+    this.#debounceMs = opts.debounceMs ?? 80;
+    this.#onBatch = opts.onBatch;
+    this.#logger = opts.logger;
+  }
+
+  start(): void {
+    for (const root of this.#roots) {
+      try {
+        const w = fs.watch(root, { recursive: true, persistent: false }, (_event, filename) => {
+          if (!filename) return;
+          const abs = path.resolve(root, filename.toString());
+          this.#queue(abs);
+        });
+        this.#watchers.push(w);
+        this.#logger.verbose(`[hmr] watching ${root}`);
+      } catch (err) {
+        this.#logger.error(`[hmr] failed to watch ${root}: ${(err as Error).message}`);
+      }
+    }
+  }
+
+  stop(): void {
+    this.#stopped = true;
+    if (this.#timer) clearTimeout(this.#timer);
+    for (const w of this.#watchers) {
+      try {
+        w.close();
+      } catch {
+        // ignore
+      }
+    }
+  }
+
+  #queue(abs: string): void {
+    const kind = this.#classifier.classify(abs);
+    if (kind === "ignore") return;
+    this.#pending.set(abs, kind);
+    if (this.#flushing) return;
+    if (this.#timer) clearTimeout(this.#timer);
+    this.#timer = setTimeout(() => this.#flush(), this.#debounceMs);
+  }
+
+  #flush(): void {
+    this.#timer = null;
+    if (this.#stopped || this.#pending.size === 0 || this.#flushing) return;
+    void this.#drain();
+  }
+
+  async #drain(): Promise<void> {
+    this.#flushing = true;
+    try {
+      while (!this.#stopped && this.#pending.size > 0) {
+        const files = Array.from(this.#pending.keys());
+        const kinds = new Set(this.#pending.values());
+        this.#pending.clear();
+        try {
+          await this.#onBatch({ files, kinds });
+        } catch (e) {
+          this.#logger.error(`[hmr] onBatch error: ${(e as Error).message}`);
+        }
+      }
+    } finally {
+      this.#flushing = false;
+      if (!this.#stopped && this.#pending.size > 0) this.#timer = setTimeout(() => this.#flush(), this.#debounceMs);
+    }
+  }
+}

package/frontendBuild/index.ts

@@ -0,0 +1,18 @@
+export * from "./allRoutesBuilder";
+export * from "./clientBuildTypes";
+export * from "./clientEntriesBundler";
+export * from "./clientEntryDiscovery";
+export * from "./csrArtifactBuilder";
+export * from "./cssCompiler";
+export * from "./cssImportResolver";
+export * from "./fontOptimizer";
+export * from "./hmrChangeClassifier";
+export * from "./hmrWatcher";
+export * from "./pagesBundleBuilder";
+export * from "./pagesEntrySourceGenerator";
+export * from "./precompressArtifacts";
+export * from "./routeClientBuilder";
+export * from "./routesManifestArtifactSerializer";
+export * from "./ssrBaseArtifactBuilder";
+export * from "./vendorSpecifiers";
+export * from "./watchRootResolver";

package/frontendBuild/pagesBundleBuilder.ts

@@ -0,0 +1,137 @@
+import path from "node:path";
+import type { BunPlugin } from "bun";
+import type { PageEntry } from "../artifact/implicitRootLayout";
+import { resolveSsrPageEntriesForApp } from "../artifact/implicitRootLayout";
+import type { App } from "../commandDecorators";
+import { createBarrelImportsPlugin } from "../transforms/barrelImportsPlugin";
+import { createExternalizeFrameworkPlugin } from "../transforms/externalizeFrameworkPlugin";
+import { transformUseClient } from "../transforms/rscUseClientTransform";
+import { createUseClientBundlePlugin } from "../transforms/useClientBundlePlugin";
+import { PagesEntrySourceGenerator } from "./pagesEntrySourceGenerator";
+
+export interface BuildPagesBundleResult {
+  /** Absolute path to the emitted `pages-[hash].js`. */
+  bundlePath: string;
+  /**
+   * Monotonic build identifier. Bun.build emits a fresh filename whenever
+   * any input changes, but importers still benefit from a `?v=<buildId>`
+   * query-string cache bust — `buildId` is that value.
+   */
+  buildId: number;
+  splitting: boolean;
+  entryBytes: number;
+  outputBytes: number;
+  outputCount: number;
+  chunkCount: number;
+}
+
+const VIRTUAL_PAGES_ENTRY = "akan-pages-entry";
+
+/**
+ * Build the server-side pages bundle. The RSC worker loads the result with
+ * `await import(bundlePath?v=buildId)`.
+ */
+export class PagesBundleBuilder {
+  #app: App;
+  #command: "build" | "start";
+  #pageEntries?: PageEntry[];
+  #started = Date.now();
+
+  constructor(app: App, command: "build" | "start" = "start", pageEntries?: PageEntry[]) {
+    this.#app = app;
+    this.#command = command;
+    this.#pageEntries = pageEntries;
+  }
+
+  async build(): Promise<BuildPagesBundleResult> {
+    const akanConfig = await this.#app.getConfig();
+    const resolvedEntries =
+      this.#pageEntries ?? (await resolveSsrPageEntriesForApp(this.#app, await this.#app.getPageKeys()));
+    const entrySource = PagesEntrySourceGenerator.generate(resolvedEntries);
+    const workspaceRoot = this.#app.workspace.workspaceRoot;
+    const result = await Bun.build({
+      entrypoints: [VIRTUAL_PAGES_ENTRY],
+      outdir: `${this.#artifactDir}/server`,
+      target: "bun",
+      format: "esm",
+      splitting: this.#splitting,
+      minify: this.#command === "build",
+      naming: {
+        entry: "pages-[hash].[ext]",
+        chunk: "chunks/[name]-[hash].[ext]",
+        asset: "assets/[name]-[hash].[ext]",
+      },
+      define: this.#define(),
+      plugins: [
+        PagesBundleBuilder.createPagesEntryPlugin(entrySource),
+        await createExternalizeFrameworkPlugin({ app: this.#app, extra: akanConfig.externalLibs }),
+        akanConfig.barrelImports.length > 0
+          ? await createBarrelImportsPlugin(this.#app, {
+              pipeAfter: (source, args) =>
+                transformUseClient(source, {
+                  path: args.path,
+                  workspaceRoot,
+                }),
+            })
+          : createUseClientBundlePlugin({ workspaceRoot }),
+      ],
+    });
+
+    if (!result.success) throw new AggregateError(result.logs, "[PagesBundleBuilder] Bun.build failed");
+
+    const entryArtifact = result.outputs.find((a) => a.kind === "entry-point");
+    if (!entryArtifact) throw new Error("[PagesBundleBuilder] Bun.build emitted no entry-point artifact");
+
+    const bundlePath = path.resolve(entryArtifact.path);
+    const buildId = Date.now();
+    const outputBytes = result.outputs.reduce((sum, output) => sum + output.size, 0);
+    const chunkCount = result.outputs.filter((output) => output.kind === "chunk").length;
+    this.#app.verbose(
+      `[PagesBundleBuilder] ${path.basename(bundlePath)} emitted in ${Date.now() - this.#started}ms splitting=${this.#splitting} entry=${entryArtifact.size} bytes outputs=${result.outputs.length} chunks=${chunkCount} total=${outputBytes} bytes`,
+    );
+    return {
+      bundlePath,
+      buildId,
+      splitting: this.#splitting,
+      entryBytes: entryArtifact.size,
+      outputBytes,
+      outputCount: result.outputs.length,
+      chunkCount,
+    };
+  }
+
+  get #artifactDir(): string {
+    return `${this.#command === "build" ? this.#app.dist.cwdPath : this.#app.cwdPath}/.akan/artifact`;
+  }
+
+  get #splitting(): boolean {
+    return process.env.AKAN_SERVER_PAGES_SPLITTING === "1";
+  }
+
+  #define(): Record<string, string> {
+    const nodeEnv = this.#command === "build" ? "production" : (process.env.NODE_ENV ?? "development");
+    return {
+      "process.env.NODE_ENV": JSON.stringify(nodeEnv),
+      "process.env.AKAN_PUBLIC_RENDER_ENV": JSON.stringify("ssr"),
+      ...Object.fromEntries(
+        Object.entries(this.#app.getPublicEnv()).map(([key, value]) => [`process.env.${key}`, JSON.stringify(value)]),
+      ),
+    };
+  }
+
+  static createPagesEntryPlugin(source: string): BunPlugin {
+    return {
+      name: "akan-pages-entry",
+      setup(build) {
+        build.onResolve({ filter: /^akan-pages-entry$/ }, () => ({
+          path: VIRTUAL_PAGES_ENTRY,
+          namespace: "akan-virtual",
+        }));
+        build.onLoad({ filter: /^akan-pages-entry$/, namespace: "akan-virtual" }, () => ({
+          contents: source,
+          loader: "tsx",
+        }));
+      },
+    };
+  }
+}

package/frontendBuild/pagesEntrySourceGenerator.ts

@@ -0,0 +1,37 @@
+import path from "node:path";
+import type { PageEntry } from "../artifact/implicitRootLayout";
+
+export class PagesEntrySourceGenerator {
+  #pageEntries: PageEntry[];
+
+  constructor(pageEntries: PageEntry[]) {
+    this.#pageEntries = pageEntries;
+  }
+
+  static generate(pageEntries: PageEntry[]): string {
+    return new PagesEntrySourceGenerator(pageEntries).generate();
+  }
+
+  generate(): string {
+    const lines = this.#pageEntries.map(({ key, moduleAbsPath }) => {
+      const absPath = path.resolve(moduleAbsPath);
+      return `  ${JSON.stringify(key)}: () => import(${JSON.stringify(absPath)}),`;
+    });
+    return `export const pages = {\n${lines.join("\n")}\n};\n`;
+  }
+
+  static generateStatic(pageEntries: PageEntry[]): string {
+    return new PagesEntrySourceGenerator(pageEntries).generateStatic();
+  }
+
+  generateStatic(): string {
+    const imports = this.#pageEntries.map(({ moduleAbsPath }, index) => {
+      const absPath = path.resolve(moduleAbsPath);
+      return `import * as page${index} from ${JSON.stringify(absPath)};`;
+    });
+    const entries = this.#pageEntries.map(({ key }, index) => {
+      return `  ${JSON.stringify(key)}: async () => page${index},`;
+    });
+    return `${imports.join("\n")}\nexport const pages = {\n${entries.join("\n")}\n};\n`;
+  }
+}

package/frontendBuild/precompressArtifacts.ts

@@ -0,0 +1,59 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { App } from "../commandDecorators";
+
+const COMPRESSIBLE_EXTS = new Set([".css", ".html", ".js", ".json", ".svg"]);
+const MIN_COMPRESS_BYTES = 1024;
+
+export interface PrecompressArtifactsResult {
+  files: number;
+  inputBytes: number;
+  outputBytes: number;
+}
+
+export async function precompressArtifacts(app: App): Promise<PrecompressArtifactsResult> {
+  const roots = [path.join(app.dist.cwdPath, ".akan/artifact/client")];
+  const result: PrecompressArtifactsResult = { files: 0, inputBytes: 0, outputBytes: 0 };
+
+  await Promise.all(roots.map((root) => precompressRoot(root, result)));
+  if (result.files > 0) {
+    app.verbose(
+      `[precompress] wrote ${result.files} gzip sidecars (${formatBytes(result.inputBytes)} -> ${formatBytes(
+        result.outputBytes,
+      )})`,
+    );
+  }
+  return result;
+}
+
+async function precompressRoot(root: string, result: PrecompressArtifactsResult): Promise<void> {
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) return;
+  const glob = new Bun.Glob("**/*");
+  for await (const filePath of glob.scan({ cwd: root, absolute: true })) {
+    if (!(await shouldPrecompress(filePath))) continue;
+    const bytes = await Bun.file(filePath).bytes();
+    const gz = Bun.gzipSync(toArrayBuffer(bytes));
+    await Bun.write(`${filePath}.gz`, gz);
+    result.files += 1;
+    result.inputBytes += bytes.byteLength;
+    result.outputBytes += gz.byteLength;
+  }
+}
+
+async function shouldPrecompress(filePath: string): Promise<boolean> {
+  if (filePath.endsWith(".gz")) return false;
+  if (!COMPRESSIBLE_EXTS.has(path.extname(filePath).toLowerCase())) return false;
+  const file = Bun.file(filePath);
+  if (!(await file.exists())) return false;
+  return file.size >= MIN_COMPRESS_BYTES;
+}
+
+function toArrayBuffer(bytes: Uint8Array): ArrayBuffer {
+  return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+  return `${(bytes / 1024 / 1024).toFixed(1)}MB`;
+}

package/frontendBuild/routeClientBuilder.ts

@@ -0,0 +1,290 @@
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import type { BaseBuildArtifact, ClientManifest, SsrManifest } from "akanjs/server";
+import type { App } from "../commandDecorators";
+import { createBarrelImportsPlugin } from "../transforms/barrelImportsPlugin";
+import { toClientReferencePath } from "../transforms/rscUseClientTransform";
+import type { ClientEntryDiscovery } from "./clientBuildTypes";
+import { ClientEntriesBundler } from "./clientEntriesBundler";
+import { GraphClientEntryDiscovery } from "./clientEntryDiscovery";
+import { VENDOR_SPECIFIERS } from "./vendorSpecifiers";
+
+const SSR_CLIENT_EXTERNALS = [
+  "react",
+  "react-dom",
+  "react-dom/client",
+  "react/jsx-runtime",
+  "react/jsx-dev-runtime",
+  "akanjs/fetch",
+] as const;
+const SSR_CLIENT_ALIAS_EXTERNALS = [
+  "react",
+  "react-dom",
+  "react-dom/client",
+  "react/jsx-runtime",
+  "react/jsx-dev-runtime",
+] as const;
+
+export interface BuildRouteClientOptions {
+  app: App;
+  seeds: string[];
+  artifact: BaseBuildArtifact;
+  knownEntries?: Set<string>;
+  routeId?: string;
+  command?: "build" | "start";
+  discovery?: ClientEntryDiscovery;
+}
+
+export interface BuildRouteClientResult {
+  /** Newly-emitted manifest rows keyed by `${absEntry}#${exportName}`. */
+  manifestDelta: ClientManifest;
+  /** Newly-emitted ssrManifest rows keyed by entry URL. */
+  ssrManifestDelta: SsrManifest;
+  /** Absolute paths of the `"use client"` leaves this build added. */
+  newEntries: string[];
+  /** Absolute paths of all `"use client"` leaves discovered from this route's seeds. */
+  discoveredEntries?: string[];
+  /** Absolute source files included in the browser bundles for new entries. */
+  clientDeps: string[];
+  /** Absolute source files included in the browser bundle, grouped by original client entry. */
+  clientDepsByEntry?: Record<string, string[]>;
+}
+
+interface BootstrapEntries {
+  buildEntries: string[];
+  originalByBuildEntry: Map<string, string>;
+}
+
+export class RouteClientBuilder {
+  #app: App;
+  #seeds: string[];
+  #knownEntries: Set<string>;
+  #command: "build" | "start";
+  #discovery?: ClientEntryDiscovery;
+
+  constructor(options: BuildRouteClientOptions) {
+    this.#app = options.app;
+    this.#seeds = options.seeds;
+    this.#knownEntries = options.knownEntries ?? new Set<string>();
+    this.#command = options.command ?? "start";
+    this.#discovery = options.discovery;
+  }
+
+  async build(): Promise<BuildRouteClientResult> {
+    const discovery = this.#discovery ?? (await GraphClientEntryDiscovery.create(this.#app));
+    const discovered = await discovery.discover(this.#seeds);
+    const entries = discovered.filter((e) => !this.#knownEntries.has(e));
+    if (entries.length === 0) return this.#emptyResult(discovered);
+
+    const bootstrapEntries = await this.#createBootstrapEntries(entries);
+    const browserBundle = await this.#buildBrowserBundle(bootstrapEntries);
+    const ssrBundle = await this.#buildSsrBundle(bootstrapEntries);
+
+    const acceptedEntries = new Set(entries);
+    const manifestDelta: ClientManifest = {};
+    const ssrModuleMap: SsrManifest["moduleMap"] = {};
+    const clientDeps = new Set<string>();
+    const clientDepsByEntry: Record<string, string[]> = {};
+    for (const [key, row] of Object.entries(browserBundle.manifest)) {
+      const manifestEntry = RouteClientBuilder.resolveOriginalManifestEntry(
+        key,
+        bootstrapEntries.originalByBuildEntry,
+        browserBundle.clientReferenceIdByAbsPath,
+        this.#app.workspace.workspaceRoot,
+      );
+      if (!manifestEntry) continue;
+      if (!acceptedEntries.has(manifestEntry.originalEntry)) continue;
+      manifestDelta[manifestEntry.key] = row;
+
+      const ssrOutput = ssrBundle.entryOutputAbsByAbsPath.get(manifestEntry.buildEntry);
+      if (!ssrOutput) continue;
+
+      ssrModuleMap[row.id] ??= {};
+      ssrModuleMap[row.id][row.name] = { id: ssrOutput, chunks: [ssrOutput, ssrOutput], name: row.name, async: true };
+    }
+    for (const entry of bootstrapEntries.buildEntries) {
+      const buildEntry = path.resolve(entry);
+      const originalEntry = path.resolve(bootstrapEntries.originalByBuildEntry.get(buildEntry) ?? buildEntry);
+      if (!acceptedEntries.has(originalEntry)) continue;
+      const deps = new Set<string>([originalEntry]);
+      for (const dep of browserBundle.entryDepsByAbsPath.get(buildEntry) ?? []) deps.add(path.resolve(dep));
+      const sortedDeps = [...deps].sort();
+      clientDepsByEntry[originalEntry] = sortedDeps;
+      for (const dep of sortedDeps) clientDeps.add(dep);
+    }
+
+    return {
+      manifestDelta,
+      ssrManifestDelta: { moduleLoading: null, moduleMap: ssrModuleMap },
+      newEntries: entries,
+      discoveredEntries: discovered,
+      clientDeps: [...clientDeps].sort(),
+      clientDepsByEntry,
+    };
+  }
+
+  #emptyResult(discoveredEntries: string[] = []): BuildRouteClientResult {
+    return {
+      manifestDelta: {},
+      ssrManifestDelta: { moduleLoading: null, moduleMap: {} },
+      newEntries: [],
+      discoveredEntries,
+      clientDeps: [],
+      clientDepsByEntry: {},
+    };
+  }
+
+  async #buildBrowserBundle(bootstrapEntries: BootstrapEntries) {
+    const reactFastRefresh = process.env.AKAN_REACT_FAST_REFRESH !== "0";
+    return new ClientEntriesBundler({
+      app: this.#app,
+      entries: bootstrapEntries.buildEntries,
+      plugins: [
+        await createBarrelImportsPlugin(this.#app, {
+          pipeAfter: reactFastRefresh ? RouteClientBuilder.normalizeNamedDefaultFunctionForFastRefresh : undefined,
+        }),
+      ],
+      external: VENDOR_SPECIFIERS,
+      command: this.#command,
+      reactFastRefresh,
+    }).bundle();
+  }
+
+  async #buildSsrBundle(bootstrapEntries: BootstrapEntries) {
+    const externalOptions = RouteClientBuilder.resolveSsrClientExternalOptions(this.#command);
+    return new ClientEntriesBundler({
+      app: this.#app,
+      entries: bootstrapEntries.buildEntries,
+      plugins: [await createBarrelImportsPlugin(this.#app)],
+      ...externalOptions,
+      outputSubdir: "client-ssr",
+      command: this.#command,
+    }).bundle();
+  }
+
+  async #createBootstrapEntries(entries: string[]): Promise<BootstrapEntries> {
+    if (!(await Bun.file(path.join(this.#app.cwdPath, "lib", "st.ts")).exists())) {
+      return { buildEntries: entries, originalByBuildEntry: new Map() };
+    }
+
+    const outdir = path.join(this.#app.cwdPath, ".akan", "generated", "client-entry-bootstrap");
+    await mkdir(outdir, { recursive: true });
+
+    const originalByBuildEntry = new Map<string, string>();
+    const buildEntries = await Promise.all(
+      entries.map(async (entry) => {
+        const absEntry = path.resolve(entry);
+        const hash = Bun.hash(`${this.#app.name}\n${absEntry}`).toString(36);
+        const base = path.basename(absEntry).replace(/[^A-Za-z0-9._-]/g, "_");
+        const wrapperEntry = path.join(outdir, `${base}-${hash}.tsx`);
+        const exportNames = await this.#scanExportNames(absEntry);
+        await Bun.write(
+          wrapperEntry,
+          RouteClientBuilder.createStoreBootstrapEntrySource({
+            appName: this.#app.name,
+            originalEntry: absEntry,
+            exportNames,
+          }),
+        );
+        originalByBuildEntry.set(path.resolve(wrapperEntry), absEntry);
+        return wrapperEntry;
+      }),
+    );
+
+    return { buildEntries, originalByBuildEntry };
+  }
+
+  async #scanExportNames(absEntry: string): Promise<string[]> {
+    const source = await Bun.file(absEntry).text();
+    const transpiler = new Bun.Transpiler({ loader: this.#loaderFor(absEntry) });
+    return transpiler.scan(source).exports;
+  }
+
+  #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";
+  }
+
+  static normalizeNamedDefaultFunctionForFastRefresh(source: string): string | null {
+    let changed = false;
+    const defaultNames: string[] = [];
+    const next = source.replace(
+      /(^|\n)(\s*)export\s+default\s+(async\s+)?function\s+([A-Za-z_$][\w$]*)(?=\s*(?:<|\())/g,
+      (match, lineStart: string, indent: string, asyncKeyword: string | undefined, name: string) => {
+        changed = true;
+        defaultNames.push(name);
+        return `${lineStart}${indent}${asyncKeyword ?? ""}function ${name}`;
+      },
+    );
+    if (!changed) return null;
+    return `${next}\n${defaultNames.map((name) => `export default ${name};`).join("\n")}\n`;
+  }
+
+  static resolveSsrClientRuntimeAliases(): Record<string, string> {
+    const serverEntry = RouteClientBuilder.resolveAkanServerEntry();
+    const aliases = Object.fromEntries(
+      SSR_CLIENT_ALIAS_EXTERNALS.map((specifier) => [specifier, Bun.resolveSync(specifier, serverEntry)]),
+    ) as Record<string, string>;
+    aliases[Bun.resolveSync("akanjs/fetch", serverEntry)] = "akanjs/fetch";
+    return aliases;
+  }
+
+  static resolveSsrClientExternalOptions(command: "build" | "start"): {
+    external: readonly string[];
+    externalSubpaths?: readonly string[];
+    externalAliases?: Record<string, string>;
+  } {
+    if (command === "start") {
+      return {
+        external: SSR_CLIENT_EXTERNALS,
+        externalSubpaths: ["akanjs/fetch"],
+        externalAliases: RouteClientBuilder.resolveSsrClientRuntimeAliases(),
+      };
+    }
+
+    return { external: SSR_CLIENT_ALIAS_EXTERNALS };
+  }
+
+  static resolveAkanServerEntry(): string {
+    try {
+      return Bun.resolveSync("akanjs/server", import.meta.dir);
+    } catch {
+      return path.resolve(import.meta.dir, "../../../server/index.ts");
+    }
+  }
+
+  static createStoreBootstrapEntrySource(args: {
+    appName: string;
+    originalEntry: string;
+    exportNames: string[];
+  }): string {
+    const originalEntry = JSON.stringify(path.resolve(args.originalEntry));
+    const namedExports = args.exportNames.filter((name) => name !== "default");
+    const lines = [
+      `import ${JSON.stringify(`@apps/${args.appName}/client`)};`,
+      ...(namedExports.length > 0 ? [`export { ${namedExports.join(", ")} } from ${originalEntry};`] : []),
+    ];
+    if (args.exportNames.includes("default")) lines.push(`export { default } from ${originalEntry};`);
+    return `${lines.join("\n")}\n`;
+  }
+
+  static resolveOriginalManifestEntry(
+    manifestKey: string,
+    originalByBuildEntry: Map<string, string>,
+    clientReferenceIdByBuildEntry: Map<string, string> = new Map(),
+    workspaceRoot = process.cwd(),
+  ): { buildEntry: string; originalEntry: string; name: string; key: string } | null {
+    const hashIdx = manifestKey.lastIndexOf("#");
+    if (hashIdx < 0) return null;
+    const buildReferenceId = manifestKey.slice(0, hashIdx);
+    const name = manifestKey.slice(hashIdx + 1);
+    const buildEntry =
+      [...clientReferenceIdByBuildEntry.entries()].find(([, referenceId]) => referenceId === buildReferenceId)?.[0] ??
+      buildReferenceId;
+    const originalEntry = originalByBuildEntry.get(buildEntry) ?? buildEntry;
+    const originalReferenceId = toClientReferencePath(originalEntry, workspaceRoot);
+    return { buildEntry, originalEntry, name, key: `${originalReferenceId}#${name}` };
+  }
+}