akanjs 0.0.1 → 2.0.0-beta.0

package/devkit/extractDeps.ts

@@ -0,0 +1,85 @@
+import type { PackageJson } from "./types";
+
+const NODE_NATIVE_MODULE_SET = new Set([
+  "assert",
+  "async_hooks",
+  "buffer",
+  "child_process",
+  "cluster",
+  "console",
+  "constants",
+  "crypto",
+  "dgram",
+  "dns",
+  "domain",
+  "events",
+  "fs",
+  "http",
+  "http2",
+  "https",
+  "inspector",
+  "module",
+  "net",
+  "os",
+  "path",
+  "perf_hooks",
+  "process",
+  "punycode",
+  "querystring",
+  "readline",
+  "repl",
+  "stream",
+  "string_decoder",
+  "timers",
+  "tls",
+  "trace_events",
+  "tty",
+  "url",
+  "util",
+  "v8",
+  "vm",
+  "wasi",
+  "worker_threads",
+  "zlib",
+]);
+
+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 ?? {}),
+  ]);
+  const versionObj = {
+    ...(pacakgeJson.dependencies ?? {}),
+    ...(pacakgeJson.devDependencies ?? {}),
+  };
+
+  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 = 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);
+      }
+      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}`);
+      return [dep, version];
+    }),
+  );
+};

package/devkit/fileEditor.ts

@@ -0,0 +1,106 @@
+export class FileEditor {
+  private filePath: string;
+  private content: string;
+
+  private constructor(filePath: string, content: string) {
+    this.filePath = filePath;
+    this.content = content;
+  }
+
+  static async create(filePath: string): Promise<FileEditor> {
+    try {
+      const content = await Bun.file(filePath).text();
+      return new FileEditor(filePath, content);
+    } catch (error) {
+      throw new Error(`Failed to read file: ${filePath}`);
+    }
+  }
+
+  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++) {
+      const line = lines[i];
+      if (!line) continue;
+      if (regex.test(line)) return i;
+    }
+
+    return -1;
+  }
+
+  findAll(pattern: string | RegExp): number[] {
+    const lines = this.content.split("\n");
+    const regex = typeof pattern === "string" ? new RegExp(pattern) : pattern;
+    const matches: number[] = [];
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (!line) continue;
+      if (regex.test(line)) matches.push(i);
+    }
+
+    return matches;
+  }
+
+  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: 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: 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: string): this {
+    this.content += `\n${data}`;
+    return this;
+  }
+
+  prepend(data: string): this {
+    this.content = `${data}\n${this.content}`;
+    return this;
+  }
+
+  async save(): Promise<void> {
+    try {
+      await Bun.write(this.filePath, this.content);
+    } catch (error) {
+      throw new Error(`Failed to save file: ${this.filePath}`);
+    }
+  }
+
+  getContent(): string {
+    return this.content;
+  }
+
+  setContent(content: string): this {
+    this.content = content;
+    return this;
+  }
+}

package/devkit/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/devkit/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/devkit/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;
+}