@akanjs/devkit 1.0.20 → 2.1.0-rc.1

package/{esm/src/extractDeps.js → extractDeps.ts}

@@ -1,4 +1,6 @@
-const NODE_NATIVE_MODULE_SET = /* @__PURE__ */ new Set([
+import type { PackageJson } from "./types";
+
+const NODE_NATIVE_MODULE_SET = new Set([
   "assert",
   "async_hooks",
   "buffer",
@@ -38,43 +40,47 @@ const NODE_NATIVE_MODULE_SET = /* @__PURE__ */ new Set([
   "vm",
   "wasi",
   "worker_threads",
-  "zlib"
+  "zlib",
 ]);
-const extractDependencies = (filepaths, pacakgeJson, defaultDependencies = []) => {
-  if (!pacakgeJson.dependencies)
-    throw new Error("No dependencies found in package.json");
-  const dependencies = new Set(defaultDependencies);
-  const existingDependencies = /* @__PURE__ */ new Set([
+
+export const extractDependencies = (
+  filepaths: { path: string; text: string }[],
+  pacakgeJson: PackageJson,
+  defaultDependencies: string[] = [],
+) => {
+  if (!pacakgeJson.dependencies) throw new Error("No dependencies found in package.json");
+  const dependencies = new Set<string>(defaultDependencies);
+
+  const existingDependencies = new Set<string>([
     ...Object.keys(pacakgeJson.dependencies ?? {}),
-    ...Object.keys(pacakgeJson.devDependencies ?? {})
+    ...Object.keys(pacakgeJson.devDependencies ?? {}),
   ]);
   const versionObj = {
-    ...pacakgeJson.dependencies ?? {},
-    ...pacakgeJson.devDependencies ?? {}
+    ...(pacakgeJson.dependencies ?? {}),
+    ...(pacakgeJson.devDependencies ?? {}),
   };
+
+  // Look for require statements: require('package-name') or import 'package-name'
   const requireRegex = /(?:require\s*\(|import\s*(?:[\w\s{},*]*\s+from\s*)?|import\s*\()\s*['"`]([^'"`]+)['"`]/g;
   for (const { text } of filepaths.filter(({ path }) => path.endsWith(".js") || path.endsWith(".ts"))) {
-    let requireMatch;
-    while ((requireMatch = requireRegex.exec(text)) !== null) {
+    let requireMatch = requireRegex.exec(text);
+    while (requireMatch !== null) {
       const moduleName = requireMatch[1];
+      if (!moduleName) throw new Error(`No module name found in ${text}`);
       const moduleNameParts = moduleName.split("/");
       const subModuleLength = moduleNameParts.length;
       for (let i = 0; i < subModuleLength; i++) {
         const libName = moduleNameParts.slice(0, i + 1).join("/");
-        if (!NODE_NATIVE_MODULE_SET.has(libName) && existingDependencies.has(libName))
-          dependencies.add(libName);
+        if (!NODE_NATIVE_MODULE_SET.has(libName) && existingDependencies.has(libName)) dependencies.add(libName);
       }
+      requireMatch = requireRegex.exec(text);
     }
   }
   return Object.fromEntries(
     [...dependencies].sort().map((dep) => {
       const version = versionObj[dep];
-      if (!version)
-        throw new Error(`No version found for ${dep}`);
+      if (!version) throw new Error(`No version found for ${dep}`);
       return [dep, version];
-    })
+    }),
   );
 };
-export {
-  extractDependencies
-};

package/{esm/src/fileEditor.js → fileEditor.ts}

@@ -1,87 +1,106 @@
-import fs from "fs";
-class FileEditor {
-  filePath;
-  content;
-  constructor(filePath) {
+export class FileEditor {
+  private filePath: string;
+  private content: string;
+
+  private constructor(filePath: string, content: string) {
     this.filePath = filePath;
-    this.content = this.#readFile();
+    this.content = content;
   }
-  #readFile() {
+
+  static async create(filePath: string): Promise<FileEditor> {
     try {
-      return fs.readFileSync(this.filePath, "utf-8");
+      const content = await Bun.file(filePath).text();
+      return new FileEditor(filePath, content);
     } catch (error) {
-      throw new Error(`Failed to read file: ${this.filePath}`);
+      throw new Error(`Failed to read file: ${filePath}`);
     }
   }
-  find(pattern) {
+
+  find(pattern: string | RegExp): number {
     const lines = this.content.split("\n");
     const regex = typeof pattern === "string" ? new RegExp(pattern) : pattern;
+
     for (let i = 0; i < lines.length; i++) {
-      if (regex.test(lines[i])) {
-        return i;
-      }
+      const line = lines[i];
+      if (!line) continue;
+      if (regex.test(line)) return i;
     }
+
     return -1;
   }
-  findAll(pattern) {
+
+  findAll(pattern: string | RegExp): number[] {
     const lines = this.content.split("\n");
     const regex = typeof pattern === "string" ? new RegExp(pattern) : pattern;
-    const matches = [];
+    const matches: number[] = [];
+
     for (let i = 0; i < lines.length; i++) {
-      if (regex.test(lines[i])) {
-        matches.push(i);
-      }
+      const line = lines[i];
+      if (!line) continue;
+      if (regex.test(line)) matches.push(i);
     }
+
     return matches;
   }
-  insertAfter(pattern, data) {
+
+  insertAfter(pattern: string | RegExp, data: string): this {
     const lineIndex = this.find(pattern);
+
     if (lineIndex === -1) {
       throw new Error(`Pattern not found: ${pattern}`);
     }
+
     const lines = this.content.split("\n");
     lines.splice(lineIndex + 1, 0, data);
     this.content = lines.join("\n");
+
     return this;
   }
-  insertBefore(pattern, data) {
+
+  insertBefore(pattern: string | RegExp, data: string): this {
     const lineIndex = this.find(pattern);
+
     if (lineIndex === -1) {
       throw new Error(`Pattern not found: ${pattern}`);
     }
+
     const lines = this.content.split("\n");
     lines.splice(lineIndex, 0, data);
     this.content = lines.join("\n");
+
     return this;
   }
-  replace(pattern, replacement) {
+
+  replace(pattern: string | RegExp, replacement: string): this {
     const regex = typeof pattern === "string" ? new RegExp(pattern, "g") : pattern;
     this.content = this.content.replace(regex, replacement);
     return this;
   }
-  append(data) {
-    this.content += "\n" + data;
+
+  append(data: string): this {
+    this.content += `\n${data}`;
     return this;
   }
-  prepend(data) {
-    this.content = data + "\n" + this.content;
+
+  prepend(data: string): this {
+    this.content = `${data}\n${this.content}`;
     return this;
   }
-  save() {
+
+  async save(): Promise<void> {
     try {
-      fs.writeFileSync(this.filePath, this.content, "utf-8");
+      await Bun.write(this.filePath, this.content);
     } catch (error) {
       throw new Error(`Failed to save file: ${this.filePath}`);
     }
   }
-  getContent() {
+
+  getContent(): string {
     return this.content;
   }
-  setContent(content) {
+
+  setContent(content: string): this {
     this.content = content;
     return this;
   }
 }
-export {
-  FileEditor
-};

package/fileSys.ts

@@ -0,0 +1,39 @@
+import { stat } from "node:fs/promises";
+import { Logger } from "akanjs/common";
+
+export class FileSys {
+  static logger = new Logger("FileSys");
+  static async fileExists(path: string) {
+    return await Bun.file(path).exists();
+  }
+  static async dirExists(path: string) {
+    return await stat(path)
+      .then((stat) => stat.isDirectory())
+      .catch(() => false);
+  }
+  static async exists(path: string) {
+    return await stat(path)
+      .then(() => true)
+      .catch(() => false);
+  }
+  static async readText(path: string) {
+    return await Bun.file(path).text();
+  }
+  static async readJson<T>(path: string): Promise<T> {
+    try {
+      return (await Bun.file(path).json()) as T;
+    } catch (error) {
+      FileSys.logger.error(`Failed to read JSON file: ${path}`);
+      throw error;
+    }
+  }
+  static async delete(path: string) {
+    return await Bun.file(path).delete();
+  }
+  static async writeText(path: string, content: string) {
+    return await Bun.file(path).write(content);
+  }
+  static async writeJson(path: string, content: object) {
+    return await Bun.file(path).write(`${JSON.stringify(content, null, 2)}\n`);
+  }
+}

package/frontendBuild/allRoutesBuilder.ts

@@ -0,0 +1,103 @@
+import path from "node:path";
+import type { BaseBuildArtifact, BuildRouteClientResult, RoutesManifest } from "akanjs/server";
+import { resolveSsrPageEntriesForApp } from "../artifact/implicitRootLayout";
+import { computeRouteSeedIndex, type RouteSeedIndex } from "../artifact/routeSeedIndex";
+import type { App } from "../commandDecorators";
+import type { ClientEntryDiscovery } from "./clientBuildTypes";
+import { GraphClientEntryDiscovery } from "./clientEntryDiscovery";
+import { RouteClientBuilder } from "./routeClientBuilder";
+import { RoutesManifestArtifactSerializer } from "./routesManifestArtifactSerializer";
+
+export interface BuildAllRoutesResult {
+  manifest: RoutesManifest;
+  manifestPath: string;
+  seedIndex: RouteSeedIndex;
+}
+
+/**
+ * Walk every route in `pages` and produce its client bundle up-front.
+ * Intended to run under `akan build` (production) so the serve path
+ * never needs to compile.
+ */
+export class AllRoutesBuilder {
+  #app: App;
+  #artifact: BaseBuildArtifact;
+  #command: "build" | "start";
+  #artifactDir: string;
+  #merged: Pick<RoutesManifest, "clientManifest" | "ssrManifest" | "knownEntries"> = {
+    clientManifest: {},
+    ssrManifest: { moduleLoading: null, moduleMap: {} },
+    knownEntries: [],
+  };
+  #knownSet = new Set<string>();
+  #routeIds: string[] = [];
+  #discovery: ClientEntryDiscovery | null = null;
+
+  constructor(app: App, artifact: BaseBuildArtifact, command: "build" | "start" = "start") {
+    this.#app = app;
+    this.#artifact = artifact;
+    this.#command = command;
+    this.#artifactDir = `${command === "build" ? app.dist.cwdPath : app.cwdPath}/.akan/artifact`;
+  }
+
+  async build(): Promise<BuildAllRoutesResult> {
+    const pageKeys = await this.#app.getPageKeys();
+    const pageEntries = await resolveSsrPageEntriesForApp(this.#app, pageKeys);
+    const seedIndex = computeRouteSeedIndex(pageEntries);
+    this.#app.verbose(`[build-all] discovered ${seedIndex.entries.length} routes`);
+    this.#discovery = await GraphClientEntryDiscovery.create(this.#app);
+
+    for (const entry of seedIndex.entries) {
+      const seeds = Array.from(new Set([...seedIndex.globalLayoutFiles, ...entry.seeds]));
+      const delta = await this.#buildRoute(entry.routeId, seeds);
+      this.#mergeRoute(entry.routeId, delta);
+    }
+    this.#merged.knownEntries = Array.from(this.#knownSet);
+
+    const manifest: RoutesManifest = {
+      routeIds: this.#routeIds,
+      ...this.#merged,
+    };
+    const manifestPath = path.join(path.resolve(this.#artifactDir), "routes-manifest.json");
+    await Bun.write(
+      manifestPath,
+      `${JSON.stringify(
+        RoutesManifestArtifactSerializer.serialize(manifest, this.#artifactDir, {
+          production: this.#command === "build",
+        }),
+        null,
+        2,
+      )}\n`,
+    );
+    this.#app.verbose(
+      `[build-all] wrote ${manifestPath} routes=${this.#routeIds.length} entries=${this.#merged.knownEntries.length}`,
+    );
+
+    return { manifest, manifestPath, seedIndex };
+  }
+
+  async #buildRoute(routeId: string, seeds: string[]): Promise<BuildRouteClientResult> {
+    if (!this.#discovery) throw new Error("[build-all] client entry discovery is not initialized");
+    const started = Date.now();
+    const delta = await new RouteClientBuilder({
+      app: this.#app,
+      routeId,
+      seeds,
+      artifact: this.#artifact,
+      knownEntries: this.#knownSet,
+      discovery: this.#discovery,
+      command: this.#command,
+    }).build();
+    this.#app.verbose(`[build-all] ${routeId} +${delta.newEntries.length} entries (${Date.now() - started}ms)`);
+    return delta;
+  }
+
+  #mergeRoute(routeId: string, delta: BuildRouteClientResult): void {
+    for (const [key, row] of Object.entries(delta.manifestDelta)) this.#merged.clientManifest[key] = row;
+    for (const [url, byName] of Object.entries(delta.ssrManifestDelta.moduleMap)) {
+      this.#merged.ssrManifest.moduleMap[url] = byName;
+    }
+    for (const abs of delta.newEntries) this.#knownSet.add(abs);
+    this.#routeIds.push(routeId);
+  }
+}

package/frontendBuild/buildRouteClient.test.ts

@@ -0,0 +1,190 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { createTsconfigPackageResolver } from "../transforms/barrelImportsPlugin";
+import { CLIENT_BUNDLE_NAMING } from "./clientBuildTypes";
+import { ClientEntriesBundler } from "./clientEntriesBundler";
+import { GraphClientEntryDiscovery } from "./clientEntryDiscovery";
+import { RouteClientBuilder } from "./routeClientBuilder";
+
+const tempRoots: string[] = [];
+
+const makeTempRoot = async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "akan-client-entry-"));
+  tempRoots.push(root);
+  return root;
+};
+
+const write = async (filePath: string, content: string) => {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, content);
+};
+
+afterEach(async () => {
+  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+describe("route client store bootstrap", () => {
+  test("wraps client entries with app client bootstrap before re-exporting components", () => {
+    const original = "/repo/pkgs/akanjs/ui/Model/NewWrapper_Client.tsx";
+    const source = RouteClientBuilder.createStoreBootstrapEntrySource({
+      appName: "angelo",
+      originalEntry: original,
+      exportNames: ["NewWrapper_Client", "default"],
+    });
+
+    expect(source).toBe(
+      [
+        'import "@apps/angelo/client";',
+        `export { NewWrapper_Client } from ${JSON.stringify(original)};`,
+        `export { default } from ${JSON.stringify(original)};`,
+        "",
+      ].join("\n"),
+    );
+  });
+
+  test("remaps wrapper manifest keys back to original client entry paths", () => {
+    const wrapper = "/repo/apps/angelo/.akan/generated/client-entry-bootstrap/NewWrapper_Client.tsx";
+    const original = "/repo/pkgs/akanjs/ui/Model/NewWrapper_Client.tsx";
+    const remapped = RouteClientBuilder.resolveOriginalManifestEntry(
+      "apps/angelo/.akan/generated/client-entry-bootstrap/NewWrapper_Client.tsx#NewWrapper_Client",
+      new Map([[wrapper, original]]),
+      new Map([[wrapper, "apps/angelo/.akan/generated/client-entry-bootstrap/NewWrapper_Client.tsx"]]),
+      "/repo",
+    );
+
+    expect(remapped).toEqual({
+      buildEntry: wrapper,
+      originalEntry: original,
+      name: "NewWrapper_Client",
+      key: "pkgs/akanjs/ui/Model/NewWrapper_Client.tsx#NewWrapper_Client",
+    });
+  });
+
+  test("emits browser chunks and assets with hash-only names", () => {
+    expect(CLIENT_BUNDLE_NAMING).toEqual({
+      entry: "[name]-[hash].[ext]",
+      chunk: "chunks/[hash].[ext]",
+      asset: "assets/[hash].[ext]",
+    });
+    expect(CLIENT_BUNDLE_NAMING.chunk.includes("[name]")).toBe(false);
+    expect(CLIENT_BUNDLE_NAMING.asset.includes("[name]")).toBe(false);
+  });
+
+  test("resolves SSR client runtime aliases from the server renderer package", () => {
+    const aliases = RouteClientBuilder.resolveSsrClientRuntimeAliases();
+
+    expect(Object.keys(aliases)).toEqual(
+      expect.arrayContaining(["react", "react-dom", "react-dom/client", "react/jsx-runtime", "react/jsx-dev-runtime"]),
+    );
+    expect(aliases.react).toBe(Bun.resolveSync("react", RouteClientBuilder.resolveAkanServerEntry()));
+    expect(aliases.react).not.toBe("react");
+    expect(aliases[Bun.resolveSync("akanjs/fetch", RouteClientBuilder.resolveAkanServerEntry())]).toBe("akanjs/fetch");
+  });
+
+  test("bundles akan fetch into production SSR client chunks", () => {
+    expect(RouteClientBuilder.resolveSsrClientExternalOptions("start")).toMatchObject({
+      external: expect.arrayContaining(["akanjs/fetch"]),
+      externalSubpaths: ["akanjs/fetch"],
+    });
+
+    expect(RouteClientBuilder.resolveSsrClientExternalOptions("build")).toEqual({
+      external: ["react", "react-dom", "react-dom/client", "react/jsx-runtime", "react/jsx-dev-runtime"],
+    });
+  });
+
+  test("rewrites SSR external imports to runtime aliases", () => {
+    const source = [
+      'import React, { useState } from "react";',
+      'import { jsxDEV } from "react/jsx-dev-runtime";',
+      'import { getRequest } from "/repo/pkgs/akanjs/fetch/index.ts";',
+      'import "react-dom/client";',
+      'import { clsx } from "clsx";',
+      "",
+    ].join("\n");
+
+    expect(
+      ClientEntriesBundler.rewriteExternalImportSpecifiers(source, {
+        react: "/runtime/react.js",
+        "react/jsx-dev-runtime": "/runtime/jsx-dev-runtime.js",
+        "/repo/pkgs/akanjs/fetch/index.ts": "akanjs/fetch",
+        "react-dom/client": "/runtime/react-dom-client.js",
+      }),
+    ).toBe(
+      [
+        'import React, { useState } from "/runtime/react.js";',
+        'import { jsxDEV } from "/runtime/jsx-dev-runtime.js";',
+        'import { getRequest } from "akanjs/fetch";',
+        'import "/runtime/react-dom-client.js";',
+        'import { clsx } from "clsx";',
+        "",
+      ].join("\n"),
+    );
+  });
+
+  test("discovers client entries from installed akanjs package sources", async () => {
+    const root = await makeTempRoot();
+    const seed = path.join(root, "apps/demo/page/_index.tsx");
+    const uiEntry = path.join(root, "node_modules/akanjs/ui/index.ts");
+    const clientEntry = path.join(root, "node_modules/akanjs/ui/System/Client.tsx");
+    await write(
+      seed,
+      'import { ClientPathWrapper } from "akanjs/ui";\nexport default function Page() { return null; }\n',
+    );
+    await write(uiEntry, 'export { ClientPathWrapper } from "./System/Client";\n');
+    await write(clientEntry, '"use client";\nexport const ClientPathWrapper = () => null;\n');
+
+    const discovery = new GraphClientEntryDiscovery(
+      { barrelImports: ["akanjs/ui"], externalLibs: [], optimizeImports: true },
+      async (specifier) => {
+        if (specifier === "akanjs/ui") {
+          return {
+            pkgName: "akanjs/ui",
+            entryFile: uiEntry,
+            pkgDir: path.dirname(uiEntry),
+            preserveFilePath: true,
+          };
+        }
+        if (specifier === "akanjs/ui/System/Client.tsx") {
+          return {
+            pkgName: "akanjs/ui/System/Client.tsx",
+            entryFile: clientEntry,
+            pkgDir: path.dirname(clientEntry),
+            preserveFilePath: true,
+          };
+        }
+        return null;
+      },
+    );
+
+    expect(await discovery.discover([seed])).toEqual([clientEntry]);
+  });
+
+  test("resolves package export wildcard subpaths for installed akanjs sources", async () => {
+    const root = await makeTempRoot();
+    const clientEntry = path.join(root, "node_modules/akanjs/ui/System/Client.tsx");
+    await write(
+      path.join(root, "node_modules/akanjs/package.json"),
+      JSON.stringify({
+        name: "akanjs",
+        exports: {
+          "./ui": "./ui/index.ts",
+          "./ui/*": "./ui/*",
+        },
+      }),
+    );
+    await write(path.join(root, "node_modules/akanjs/ui/index.ts"), "export {};\n");
+    await write(clientEntry, '"use client";\nexport const ClientPathWrapper = () => null;\n');
+
+    const resolvePackage = await createTsconfigPackageResolver({
+      workspace: { workspaceRoot: root },
+      getTsConfig: async () => ({ compilerOptions: { paths: {} } }),
+    } as never);
+
+    expect(await resolvePackage("akanjs/ui/System/Client.tsx")).toMatchObject({
+      entryFile: clientEntry,
+      preserveFilePath: true,
+    });
+  });
+});

package/frontendBuild/clientBuildTypes.ts

@@ -0,0 +1,114 @@
+import type { ClientManifest, ClientManifestEntry, SsrManifest } from "akanjs/server";
+import type { BunPlugin } from "bun";
+import type { App } from "../commandDecorators";
+
+export type { ClientManifest, ClientManifestEntry };
+
+export interface BuildClientOptions {
+  appDir: string;
+  rscClientEntry: string;
+  outputDir?: string;
+  servePrefix?: string;
+  mode?: "production" | "test";
+  /** Additional Bun plugins applied to the client bundle build. */
+  plugins?: BunPlugin[];
+  /**
+   * Legacy fallback: additional directories to filesystem-scan for
+   * `"use client"` entry points. Only used when `workspaceRoot` /
+   * `tsconfigPaths` are not provided (in which case we fall back to the old
+   * filesystem-scan strategy). Prefer the graph-based discovery.
+   */
+  extraClientScanRoots?: string[];
+  /**
+   * Environment variables to inline into the browser bundle via `define`.
+   * Keys are the original `process.env` names. Each key is emitted as
+   * `process.env.<KEY>` so existing server/client shared code that reads
+   * `process.env.AKAN_PUBLIC_*` keeps working unchanged.
+   */
+  publicEnv?: Record<string, string>;
+  /**
+   * Workspace root used by the graph-based client-entry discovery to resolve
+   * tsconfig-aliased specifiers (`@libs/shared/ui`, `@apps/<name>/client`,
+   * ...). When provided together with `tsconfigPaths`, discovery traverses
+   * the import graph starting from `appDir` instead of doing a filesystem
+   * scan, so `"use client"` files that no route transitively imports (e.g.
+   * unused editor components in a shared UI package) stay out of the client
+   * bundle.
+   */
+  workspaceRoot?: string;
+  /** Workspace tsconfig `compilerOptions.paths`. See `workspaceRoot`. */
+  tsconfigPaths?: Record<string, string[]>;
+  /**
+   * Barrel specifiers whose imports are flattened by `barrelImportsPlugin`.
+   * Discovery rewrites barrel imports with the same analyzer before scanning,
+   * so the traversal sees the same leaf files the bundler will see.
+   */
+  barrelImports?: string[];
+}
+
+export interface BuildClientResult {
+  manifest: ClientManifest;
+  ssrManifest: SsrManifest;
+  outputDir: string;
+  servePrefix: string;
+  entries: string[];
+  rscClientUrl: string;
+}
+
+export const CLIENT_BUNDLE_NAMING = {
+  entry: "[name]-[hash].[ext]",
+  chunk: "chunks/[hash].[ext]",
+  asset: "assets/[hash].[ext]",
+} as const;
+
+export interface ClientEntryDiscovery {
+  discover(seeds: string[]): Promise<string[]>;
+  invalidate?(files: string[]): void;
+}
+
+export interface BundleClientEntriesOptions {
+  app: App;
+  entries: string[];
+  plugins?: BunPlugin[];
+  outputSubdir?: string;
+  /**
+   * Future Fast Refresh hook. Bun only injects the React Refresh transform;
+   * the browser runtime/update protocol still needs to be provided by Akan.
+   */
+  reactFastRefresh?: boolean;
+}
+
+export interface BundleClientEntriesInternalOptions extends BundleClientEntriesOptions {
+  external?: readonly string[];
+  externalSubpaths?: readonly string[];
+  externalAliases?: Partial<Record<string, string>>;
+  command?: "build" | "start";
+}
+
+export interface BundleClientEntriesResult {
+  manifest: ClientManifest;
+  ssrManifest: SsrManifest;
+  /** Absolute path → serve URL for every entry point we produced. */
+  entryUrlsByAbsPath: Map<string, string>;
+  /** Absolute source entry path → emitted entry file absolute path. */
+  entryOutputAbsByAbsPath: Map<string, string>;
+  /** Absolute source files that Bun included for each client entry bundle. */
+  entryDepsByAbsPath: Map<string, string[]>;
+  /** Absolute source entry path → workspace-relative client reference id. */
+  clientReferenceIdByAbsPath: Map<string, string>;
+}
+
+export type AkanConfig = Awaited<ReturnType<App["getConfig"]>>;
+export type ScannedImport = { path: string; kind?: string };
+export type MetafileOutput = {
+  imports: ScannedImport[];
+  entryPoint?: string;
+  exports?: string[];
+  inputs?: Record<string, unknown>;
+};
+
+export interface OpaqueEntryAliases {
+  entries: string[];
+  originalByAlias: Map<string, string>;
+  aliasDir: string;
+}