@akanjs/devkit 3.0.0-alpha.7 → 3.0.0-alpha.70

package/akanConfig/akanConfig.ts

@@ -5,19 +5,26 @@ import type { AkanPlugin } from "akanjs";
 import { type AkanI18nConfig, resolveAkanI18nConfig } from "akanjs/common";
 import type { AkanImageConfig } from "akanjs/server";
 import type { App, Lib } from "../commandDecorators";
-import { WorkspaceExecutor } from "../executors";
+import { LibExecutor, WorkspaceExecutor } from "../executors";
 import type { BaseDevEnv, PackageJson } from "../types";
 import {
+  type AkanAssetsConfig,
   type AkanMobileConfig,
   type AkanMobileTargetConfig,
   type AkanRouteConfig,
+  type AkanWebConfig,
+  type AkanWebOption,
   type AppConfigResult,
   type Arch,
   archs,
   type DatabaseMode,
   type DeepPartial,
   type DockerConfig,
+  type DockerOption,
+  type DockerRun,
+  type LibAssetsConfig,
   type LibConfigResult,
+  type LibDockerConfig,
 } from "./types";
 
 const DEFAULT_BARREL_IMPORTS = ["akanjs/webkit", "akanjs/common", "akanjs/ui", "akanjs/server"];
@@ -49,9 +56,8 @@ const DEFAULT_OPTIMIZE_IMPORTS = [
   "react-icons/*",
 ];
 const WORKSPACE_BARREL_FACETS = ["ui", "webkit", "common", "client", "server"] as const;
+const DEFAULT_DOCKER_IMAGE = "oven/bun:1-slim";
 const SSR_RUNTIME_PACKAGES = ["react", "react-dom", "react-server-dom-webpack"] as const;
-const NATIVE_RUNTIME_PACKAGES = ["sharp"] as const;
-const DEFAULT_BACKEND_RUNTIME_PACKAGES = ["croner"] as const;
 // The firebase client (push tokens) and the Capacitor toolchain — `@capacitor/cli` (`npx cap`),
 // `@capacitor/assets` (`npx @capacitor/assets`) plus the `@capacitor/core`/`ios`/`android` runtime
 // and native-platform packages that `npx cap add`/`sync` resolve from the workspace node_modules.
@@ -92,8 +98,6 @@ const DATABASE_MODE_RUNTIME_PACKAGES = {
 } satisfies Record<DatabaseMode, readonly string[]>;
 const AKAN_RUNTIME_PACKAGES = new Set<string>([
   ...SSR_RUNTIME_PACKAGES,
-  ...NATIVE_RUNTIME_PACKAGES,
-  ...DEFAULT_BACKEND_RUNTIME_PACKAGES,
   ...MOBILE_RUNTIME_PACKAGES,
   ...Object.values(DATABASE_MODE_RUNTIME_PACKAGES).flat(),
 ]);
@@ -109,6 +113,7 @@ const DEFAULT_AKAN_IMAGE_CONFIG: AkanImageConfig = {
   maximumRedirects: 3,
   fetchTimeoutMs: 7000,
   maxRemoteBytes: 25 * 1024 * 1024,
+  maxConcurrency: 0,
 };
 
 const normalizeIndexPath = (indexPath: string | undefined): string | undefined => {
@@ -167,11 +172,45 @@ const normalizeDeepLinks = (deepLinks: DeepPartial<AkanMobileTargetConfig["deepL
   } satisfies AkanMobileTargetConfig["deepLinks"];
 };
 
+/** What `akan.config.ts` may write: the resolved shape made partial, with `docker` and `web` in their unions. */
+type AppConfigDeclaration = Omit<DeepPartial<AppConfigResult>, "docker" | "web"> & {
+  docker?: DockerOption;
+  web?: AkanWebOption;
+};
+
+/** What the workspace's libs add to an app's build, read off each `libs/<lib>/akan.config.ts`. */
+export interface LibContributions {
+  externalLibs: string[];
+  docker: LibDockerConfig;
+  /** Keep globs rewritten to the app's own `public/`, where `akan sync` mounts each lib's assets. */
+  keepFonts?: string[];
+}
+
+const emptyLibContributions = (): LibContributions => ({
+  externalLibs: [],
+  docker: { preRuns: [], postRuns: [] },
+  keepFonts: [],
+});
+
+const normalizeKeepFonts = (keepFonts: string[] | undefined) => [
+  ...new Set((keepFonts ?? []).map((glob) => glob.trim().replace(/^\/+/, "")).filter(Boolean)),
+];
+
+/** First occurrence wins, so a step a lib and its app both declare becomes one layer. */
+const dedupeDockerRuns = (runs: DockerRun[]): DockerRun[] => {
+  const byKey = new Map<string, DockerRun>();
+  for (const run of runs) byKey.set(typeof run === "string" ? run : JSON.stringify(run), run);
+  return [...byKey.values()];
+};
+
 export class AkanAppConfig implements AppConfigResult {
   app: App;
   rootPackageJson: PackageJson;
   docker: DockerConfig;
+  /** The Dockerfile `akan build` writes: the declared string verbatim, or one assembled from the parts. */
+  dockerfile: string;
   defaultDatabaseMode: DatabaseMode;
+  web: AkanWebConfig;
   externalLibs: string[];
   barrelImports: string[];
   optimizeImports: string[];
@@ -182,6 +221,7 @@ export class AkanAppConfig implements AppConfigResult {
   /** True only when the app's akan.config.ts explicitly declares a `mobile` section (vs. the synthesized default). */
   hasMobileConfig: boolean;
   secrets: string[];
+  assets: AkanAssetsConfig;
   /** Raw setting; resolved against the app's lib deps at sync time (see `AppExecutor.syncPages`). */
   syncPageLibs: string[] | boolean;
   baseDevEnv: BaseDevEnv;
@@ -196,9 +236,10 @@ export class AkanAppConfig implements AppConfigResult {
     app: App,
     libs: string[],
     rootPackageJson: PackageJson,
-    config: DeepPartial<AppConfigResult>,
+    config: AppConfigDeclaration,
     baseDevEnv: BaseDevEnv,
     plugins: AkanPlugin[] = [],
+    libContributions: LibContributions = emptyLibContributions(),
   ) {
     this.app = app;
     this.rootPackageJson = rootPackageJson;
@@ -207,7 +248,7 @@ export class AkanAppConfig implements AppConfigResult {
     this.plugins = plugins;
     this.#applyRoutes(config?.routes);
     this.defaultDatabaseMode = config?.defaultDatabaseMode ?? "single";
-    this.externalLibs = config?.externalLibs ?? [];
+    this.externalLibs = [...new Set([...(config?.externalLibs ?? []), ...libContributions.externalLibs])];
     this.barrelImports = [
       ...DEFAULT_BARREL_IMPORTS,
       ...WORKSPACE_BARREL_FACETS.map((facet) => `@apps/${app.name}/${facet}`),
@@ -221,10 +262,28 @@ export class AkanAppConfig implements AppConfigResult {
     process.env.AKAN_PUBLIC_LOCALES = this.i18n.locales.join(",");
     this.publicEnv = (config?.publicEnv as string[] | undefined) ?? ([] as string[]);
     this.secrets = (config?.secrets as string[] | undefined) ?? ([] as string[]);
+    this.assets = {
+      pruneFonts: config?.assets?.pruneFonts ?? true,
+      keepFonts: [
+        ...normalizeKeepFonts(config?.assets?.keepFonts as string[] | undefined),
+        ...(libContributions.keepFonts ?? []),
+      ],
+    };
     this.syncPageLibs = (config?.syncPageLibs as string[] | boolean | undefined) ?? false;
     this.hasMobileConfig = Boolean(config.mobile);
     this.mobile = this.#resolveMobileConfig(config.mobile);
-    this.docker = this.#makeDockerContent(config?.docker ?? {});
+    this.web = this.#resolveWebConfig(config.web);
+    this.docker = AkanAppConfig.#resolveDocker(config.docker, libContributions.docker);
+    this.dockerfile = this.#makeDockerfile();
+  }
+  #resolveWebConfig(web: AkanWebOption | undefined): AkanWebConfig {
+    const resolved = typeof web === "object" ? { ssr: true, csr: web.csr } : { ssr: web ?? true, csr: web ?? true };
+    // `akan build-ios` / `build-android` copy `dist/apps/<app>/csr/<target>.html` into the native project.
+    if (!resolved.csr && this.hasMobileConfig)
+      throw new Error(
+        `apps/${this.app.name}/akan.config.ts turns the CSR bundle off but declares mobile targets; the Capacitor build ships that bundle. Drop the mobile section or leave CSR on.`,
+      );
+    return resolved;
   }
   #resolveMobileConfig(mobile: DeepPartial<AkanMobileConfig> | undefined): AkanMobileConfig {
     const {
@@ -325,7 +384,7 @@ export class AkanAppConfig implements AppConfigResult {
         this.branches.forEach((domain) => void domains.add(`${basePath}-${domain}.${serveDomain}`));
       });
   }
-  #getDockerRunScripts(runs: (string | { [key in Arch]?: string })[]) {
+  #getDockerRunScripts(runs: DockerRun[]) {
     return runs.map((run) => {
       if (typeof run === "string") return `RUN ${run}`;
       else
@@ -342,26 +401,31 @@ export class AkanAppConfig implements AppConfigResult {
     if (typeof image === "string") return `FROM ${image}`;
     else return archs.map((arch) => `FROM ${image[arch] ?? defaultImage} AS ${arch}`).join("\n");
   }
-  #makeDockerContent(docker: DeepPartial<DockerConfig>): DockerConfig {
-    if (docker.content)
-      return {
-        content: docker.content,
-        image: {},
-        preRuns: [],
-        postRuns: [],
-        command: [],
-      };
-    const preRunScripts = this.#getDockerRunScripts(docker.preRuns ?? []);
-    const postRunScripts = this.#getDockerRunScripts(docker.postRuns ?? []);
-
-    const imageScript = docker.image
-      ? this.#getDockerImageScript(docker.image, "oven/bun:1-slim")
-      : "FROM oven/bun:1-slim";
-    const command = docker.command ?? ["bun", "main.js"];
-    const content = `${imageScript}
+  /** A declared Dockerfile string is verbatim, so a lib's steps are dropped rather than silently unapplied. */
+  static #resolveDocker(docker: DockerOption | undefined, libDocker: LibDockerConfig): DockerConfig {
+    if (typeof docker === "string") return docker;
+    return {
+      image: docker?.image ?? DEFAULT_DOCKER_IMAGE,
+      preRuns: dedupeDockerRuns([...libDocker.preRuns, ...(docker?.preRuns ?? [])]),
+      postRuns: dedupeDockerRuns([...libDocker.postRuns, ...(docker?.postRuns ?? [])]),
+      command: docker?.command ?? ["bun", "main.js"],
+    };
+  }
+  #makeDockerfile(): string {
+    if (typeof this.docker === "string") return this.docker;
+    const { image, preRuns, postRuns, command } = this.docker;
+    const preRunScripts = this.#getDockerRunScripts(preRuns);
+    const postRunScripts = this.#getDockerRunScripts(postRuns);
+    const imageScript = this.#getDockerImageScript(image, DEFAULT_DOCKER_IMAGE);
+    // The image default matches what the build actually produced; a deployment narrows it further with its
+    // own env, and can never widen it past the artifacts that are in the image.
+    const webEnvLines = [
+      ...(this.web.ssr ? [] : ["ENV AKAN_SSR=false"]),
+      ...(this.web.csr ? [] : ["ENV AKAN_CSR=false"]),
+    ].join("\n");
+    return `${imageScript}
+RUN apt-get update && apt-get upgrade -y && apt-get install -y --no-install-recommends ca-certificates tzdata && rm -rf /var/lib/apt/lists/*
 RUN ln -sf /usr/share/zoneinfo/Asia/Seoul /etc/localtime
-RUN apt-get update && apt-get upgrade -y
-RUN apt-get install -y --no-install-recommends git redis build-essential python3 ca-certificates fonts-liberation libappindicator3-1 libasound2 libatk-bridge2.0-0 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgbm1 libgcc1 libglib2.0-0 libgtk-3-0 libnspr4 libnss3 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 lsb-release wget xdg-utils udev ffmpeg
 ARG TARGETARCH
 ${preRunScripts.join("\n")}
 RUN mkdir -p /workspace
@@ -380,15 +444,8 @@ ${this.basePaths.size ? `ENV AKAN_PUBLIC_BASE_PATHS=${[...this.basePaths].join("
 ENV AKAN_PUBLIC_DEFAULT_LOCALE=${this.i18n.defaultLocale}
 ENV AKAN_PUBLIC_LOCALES=${this.i18n.locales.join(",")}
 ENV AKAN_PUBLIC_OPERATION_MODE=cloud
-
+${webEnvLines}
 CMD [${command.map((c) => `"${c}"`).join(",")}]`;
-    return {
-      content,
-      image: imageScript,
-      preRuns: docker.preRuns ?? [],
-      postRuns: docker.postRuns ?? [],
-      command,
-    };
   }
   static #importGeneration = 0;
   /**
@@ -415,8 +472,34 @@ CMD [${command.map((c) => `"${c}"`).join(",")}]`;
       app.workspace.getPackageJson(),
     ]);
     const resolved = typeof configImp === "function" ? configImp(app) : configImp;
-    const { plugins, ...config } = (resolved ?? {}) as DeepPartial<AppConfigResult> & { plugins?: AkanPlugin[] };
-    return new AkanAppConfig(app, libs, rootPackageJson, config, baseDevEnv, plugins ?? []);
+    const { plugins, ...config } = (resolved ?? {}) as AppConfigDeclaration & { plugins?: AkanPlugin[] };
+    const libContributions = await AkanAppConfig.#collectLibContributions(app, libs, bustImportCache);
+    return new AkanAppConfig(app, libs, rootPackageJson, config, baseDevEnv, plugins ?? [], libContributions);
+  }
+  //* Every workspace lib is read, not just this app's lib deps: narrowing the set needs the dependency
+  //* scan, and the incremental page rebundle re-reads this config on every file change.
+  static async #collectLibContributions(app: App, libs: string[], bustImportCache: boolean): Promise<LibContributions> {
+    const libConfigs = await Promise.all(
+      libs.map(async (libName) =>
+        LibExecutor.from(app, libName)
+          .getConfig({ refresh: bustImportCache })
+          .catch((error: unknown) => {
+            app.logger.warn(`Skipped libs/${libName}/akan.config.ts contributions: ${String(error)}`);
+            return null;
+          }),
+      ),
+    );
+    return {
+      externalLibs: libConfigs.flatMap((libConfig) => libConfig?.externalLibs ?? []),
+      docker: {
+        preRuns: libConfigs.flatMap((libConfig) => libConfig?.docker.preRuns ?? []),
+        postRuns: libConfigs.flatMap((libConfig) => libConfig?.docker.postRuns ?? []),
+      },
+      //* A lib writes the glob against its own `public/`; `akan sync` mounts that at `public/libs/<lib>`.
+      keepFonts: libConfigs.flatMap((libConfig) =>
+        (libConfig?.assets.keepFonts ?? []).map((glob) => `libs/${libConfig?.lib.name}/${glob}`),
+      ),
+    };
   }
   #resolveProductionDependencyVersion(lib: string) {
     const rootVersion = this.rootPackageJson.dependencies?.[lib] ?? this.rootPackageJson.devDependencies?.[lib];
@@ -428,13 +511,7 @@ CMD [${command.map((c) => `"${c}"`).join(",")}]`;
     return akanPackageJson.dependencies?.[lib] ?? akanPackageJson.peerDependencies?.[lib];
   }
   #getProductionRuntimePackages() {
-    return [
-      ...this.externalLibs,
-      ...SSR_RUNTIME_PACKAGES,
-      ...NATIVE_RUNTIME_PACKAGES,
-      ...DEFAULT_BACKEND_RUNTIME_PACKAGES,
-      ...this.getDatabaseModeRuntimePackages(),
-    ];
+    return [...this.externalLibs, ...SSR_RUNTIME_PACKAGES, ...this.getDatabaseModeRuntimePackages()];
   }
   getDatabaseModeRuntimePackages(databaseMode: DatabaseMode = this.defaultDatabaseMode) {
     return [...DATABASE_MODE_RUNTIME_PACKAGES[databaseMode]];
@@ -532,15 +609,19 @@ function mergeImageConfig(config: Partial<AkanImageConfig> = {}): AkanImageConfi
 export class AkanLibConfig implements LibConfigResult {
   lib: Lib;
   externalLibs: string[];
+  docker: LibDockerConfig;
+  assets: LibAssetsConfig;
   /** Live-only: plugins declared in this lib's `akan.config.ts` (never serialized). */
   plugins: AkanPlugin[];
   constructor(lib: Lib, config: DeepPartial<LibConfigResult>, plugins: AkanPlugin[] = []) {
     this.lib = lib;
     this.externalLibs = config?.externalLibs ?? [];
+    this.docker = { preRuns: config?.docker?.preRuns ?? [], postRuns: config?.docker?.postRuns ?? [] };
+    this.assets = { keepFonts: normalizeKeepFonts(config?.assets?.keepFonts as string[] | undefined) };
     this.plugins = plugins;
   }
-  static async from(lib: Lib) {
-    const [configImp] = await Promise.all([import(`${lib.cwdPath}/akan.config.ts`).then((mod) => mod.default)]);
+  static async from(lib: Lib, { bustImportCache = false }: { bustImportCache?: boolean } = {}) {
+    const configImp = await AkanAppConfig.importConfigModule(lib.cwdPath, { bustImportCache });
     const resolved = typeof configImp === "function" ? configImp(lib) : configImp;
     const { plugins, ...config } = (resolved ?? {}) as DeepPartial<LibConfigResult> & { plugins?: AkanPlugin[] };
     return new AkanLibConfig(lib, config, plugins ?? []);

package/akanConfig/types.ts

@@ -1,4 +1,5 @@
 export type {
+  AkanAssetsConfig,
   AkanConfigFile,
   AkanExecutor,
   AkanMobileConfig,
@@ -9,6 +10,8 @@ export type {
   AkanRouteConfig,
   AkanScanInfo,
   AkanSyncContext,
+  AkanWebConfig,
+  AkanWebOption,
   AppConfig,
   AppConfigInput,
   AppConfigResult,
@@ -17,10 +20,15 @@ export type {
   DatabaseMode,
   DeepPartial,
   DockerConfig,
+  DockerImageConfig,
+  DockerOption,
+  DockerRun,
   FileConventionScanResult,
+  LibAssetsConfig,
   LibConfig,
   LibConfigInput,
   LibConfigResult,
+  LibDockerConfig,
   LibScanResult,
   MobileEnv,
   MobilePermission,

package/akanContext.ts

@@ -1,6 +1,7 @@
 import { readdir } from "node:fs/promises";
 import path from "node:path";
 import { capitalize } from "akanjs/common";
+import { extractBlockVersion, readDevkitVersion } from "./agentsIndex";
 import { AppExecutor, LibExecutor, type SysExecutor, type WorkspaceExecutor } from "./executors";
 import { FileSys } from "./fileSys";
 import { collectRecipeSources, findInlineRecipeDuplicates, scanRecipes } from "./recipeScanner";
@@ -14,7 +15,7 @@ import {
   workflowRunArtifactPath,
   workflowSyncDir,
 } from "./workflow";
-import { appRootAllowedDirs, appRootAllowedFiles, isScannedAppRootEntry } from "./workspaceLayout";
+import { isScannedRootEntry, rootAllowedDirs, rootAllowedFiles } from "./workspaceLayout";
 
 export type AkanContextFormat = "json" | "markdown";
 export type AkanModuleKind = "domain" | "service" | "scalar";
@@ -276,6 +277,8 @@ const validationCommands = [
   "akan test <app-or-lib-or-pkg>",
   "akan build <app-name>",
   "akan doctor --strict --format json",
+  "akan quality scan [--format json]",
+  "akan quality ssr [--format json]",
 ];
 
 const unknownGeneratedFilesFreshness: GeneratedFilesFreshness = {
@@ -618,6 +621,30 @@ export class AkanContextAnalyzer {
     };
   }
 
+  // The conventions in AGENTS.md ship with the package, but nothing re-renders them on `bun update` — a workspace
+  // keeps whichever release wrote its block until someone re-runs the install. Comparing the stamp against the
+  // running devkit is the only signal that the guide an agent is reading is older than the framework it describes.
+  static async #agentGuideDrift(workspace: WorkspaceExecutor) {
+    const installed = await readDevkitVersion();
+    if (!installed) return null;
+    const content = await safeReadText(path.join(workspace.workspaceRoot, "AGENTS.md"));
+    if (content === null) return null;
+    const stamped = extractBlockVersion(content);
+    if (stamped === installed) return null;
+    const hint = "Re-render the AGENTS.md managed block from the installed framework release.";
+    if (!stamped)
+      return {
+        code: "agent-guide-unstamped",
+        message: `AGENTS.md carries no generated-version stamp, so its conventions may predate @akanjs/devkit ${installed}`,
+        hint,
+      };
+    return {
+      code: "agent-guide-stale",
+      message: `AGENTS.md was generated by @akanjs/devkit ${stamped}, but ${installed} is installed`,
+      hint,
+    };
+  }
+
   static async doctor(
     workspace: WorkspaceExecutor,
     {
@@ -639,23 +666,25 @@ export class AkanContextAnalyzer {
       ),
     ];
 
-    for (const app of context.apps) {
-      const appPath = path.join(workspace.workspaceRoot, app.path);
-      for (const entry of await safeReadDir(appPath)) {
-        if (!isScannedAppRootEntry(entry.name)) continue;
-        const allowed = entry.isDirectory() ? appRootAllowedDirs.has(entry.name) : appRootAllowedFiles.has(entry.name);
+    for (const sys of [...context.apps, ...context.libs]) {
+      const sysPath = path.join(workspace.workspaceRoot, sys.path);
+      for (const entry of await safeReadDir(sysPath)) {
+        if (!isScannedRootEntry(sys.type, entry.name)) continue;
+        const allowed = entry.isDirectory()
+          ? rootAllowedDirs[sys.type].has(entry.name)
+          : rootAllowedFiles[sys.type].has(entry.name);
         if (!allowed) {
           const action = repairAction(
             "module-shape",
-            `akan repair module-shape --app ${app.name}`,
-            "Review app root shape and remove or move the unknown entry.",
+            `akan repair module-shape --app ${sys.name}`,
+            `Review ${sys.type} root shape and remove or move the unknown entry.`,
             false,
           );
           diagnostics.push({
             severity: "error",
-            code: "app-root-unknown-entry",
-            path: `${app.path}/${entry.name}`,
-            message: `Unexpected ${entry.isDirectory() ? "folder" : "file"} in app root: ${app.path}/${entry.name}`,
+            code: `${sys.type}-root-unknown-entry`,
+            path: `${sys.path}/${entry.name}`,
+            message: `Unexpected ${entry.isDirectory() ? "folder" : "file"} in ${sys.type} root: ${sys.path}/${entry.name}`,
             repairActions: [action],
           });
           repairActions.push(action);
@@ -663,6 +692,19 @@ export class AkanContextAnalyzer {
       }
     }
 
+    const agentDrift = await AkanContextAnalyzer.#agentGuideDrift(workspace);
+    if (agentDrift) {
+      const action = repairAction("generated", "akan agent install agents-md", agentDrift.hint, true);
+      diagnostics.push({
+        severity: "warning",
+        code: agentDrift.code,
+        path: "AGENTS.md",
+        message: agentDrift.message,
+        repairActions: [action],
+      });
+      repairActions.push(action);
+    }
+
     for (const sys of [...context.apps, ...context.libs]) {
       for (const module of sys.modules) {
         if (!module.abstract.exists) {

package/applicationBuildRunner.test.ts

@@ -4,7 +4,7 @@ import { AKAN_OPTIONAL_BACKEND_EXTERNALS } from "./applicationBuildRunner";
 describe("ApplicationBuildRunner", () => {
   test("externalizes Akan optional backend dependencies", () => {
     expect(AKAN_OPTIONAL_BACKEND_EXTERNALS).toEqual(
-      expect.arrayContaining(["@libsql/client", "bullmq", "croner", "ioredis", "postgres", "protobufjs"]),
+      expect.arrayContaining(["@libsql/client", "bullmq", "ioredis", "postgres", "protobufjs"]),
     );
   });
 });

package/applicationBuildRunner.ts

@@ -7,7 +7,13 @@ import type {
   ApplicationBuildResult,
 } from "./applicationBuildReporter";
 import type { App } from "./commandDecorators";
-import { AllRoutesBuilder, CsrArtifactBuilder, precompressArtifacts, SsrBaseArtifactBuilder } from "./frontendBuild";
+import {
+  AllRoutesBuilder,
+  CsrArtifactBuilder,
+  FontPruner,
+  precompressArtifacts,
+  SsrBaseArtifactBuilder,
+} from "./frontendBuild";
 import { Spinner } from "./spinner";
 
 export interface TypecheckOptions {
@@ -15,7 +21,7 @@ export interface TypecheckOptions {
   incremental?: boolean;
 }
 
-export type BuildPhaseId = "prepare" | "typecheck" | "backend" | "ssr" | "csr" | "compress" | "metadata";
+export type BuildPhaseId = "prepare" | "typecheck" | "backend" | "ssr" | "csr" | "assets" | "compress" | "metadata";
 
 export type BuildPhaseResult = ApplicationBuildPhaseResult & { id: BuildPhaseId };
 export type BuildResult = ApplicationBuildResult;
@@ -37,6 +43,7 @@ const BUILD_PHASE_EMOJIS: Record<BuildPhaseId, string> = {
   backend: "📦",
   ssr: "🧭",
   csr: "🎨",
+  assets: "✂️",
   compress: "🗜️",
   metadata: "📝",
 };
@@ -56,7 +63,6 @@ const SSR_RENDER_EXTERNALS = [
 export const AKAN_OPTIONAL_BACKEND_EXTERNALS = [
   "@libsql/client",
   "bullmq",
-  "croner",
   "ioredis",
   "postgres",
   "protobufjs",
@@ -78,6 +84,7 @@ export class ApplicationBuildRunner {
   async build({ spinner = false }: BuildOptions = {}): Promise<BuildResult> {
     // serial build is needed because of Bun.build is unstable for parallel build
     const phaseOptions = { spinner };
+    const { web, assets } = await this.#app.getConfig();
     await this.#runPhase("prepare", "Preparing output directory", () => this.#app.prepareCommand("build"), undefined, {
       spinner,
     });
@@ -92,18 +99,30 @@ export class ApplicationBuildRunner {
     await this.#runPhase(
       "ssr",
       "Building SSR route artifacts",
-      () => this.#buildSsr(),
+      async () => (web.ssr ? await this.#buildSsr() : null),
       (result) =>
         result
           ? `${result.allRoutes.manifest.routeIds.length} routes, ${result.allRoutes.manifest.knownEntries.length} entries`
-          : "skipped",
+          : web.ssr
+            ? "skipped"
+            : "disabled by akan.config.ts web.ssr",
       phaseOptions,
     );
     await this.#runPhase(
       "csr",
       "Building CSR assets",
-      () => this.#buildCsr(),
-      (result) => result?.outputDir ?? "skipped",
+      async () => (web.csr ? await this.#buildCsr() : null),
+      (result) => result?.outputDir ?? (web.csr ? "skipped" : "disabled by akan.config.ts web.csr"),
+      phaseOptions,
+    );
+    await this.#runPhase(
+      "assets",
+      "Trimming unread static assets",
+      async () => (assets.pruneFonts ? await new FontPruner(this.#app, assets).prune() : null),
+      (result) =>
+        result
+          ? `${result.removed.length} font file(s) dropped, ${ApplicationBuildRunner.formatBytes(result.freedBytes)} freed; ${result.kept.length} kept`
+          : "disabled by akan.config.ts assets.pruneFonts",
       phaseOptions,
     );
     await this.#runPhase(
@@ -166,7 +185,7 @@ export class ApplicationBuildRunner {
     const akanConfig = await this.#app.getConfig();
     await Promise.all([
       this.#app.dist.writeJson("package.json", akanConfig.getProductionPackageJson()),
-      this.#app.dist.writeFile(`${this.#app.dist.cwdPath}/Dockerfile`, akanConfig.docker.content),
+      this.#app.dist.writeFile(`${this.#app.dist.cwdPath}/Dockerfile`, akanConfig.dockerfile),
     ]);
   }
 
@@ -175,6 +194,7 @@ export class ApplicationBuildRunner {
     const backendExternals = [
       ...new Set([...akanConfig.externalLibs, ...SSR_RENDER_EXTERNALS, ...AKAN_OPTIONAL_BACKEND_EXTERNALS]),
     ];
+    const { web } = akanConfig;
     const backendEntryPoints = [`${this.#app.cwdPath}/main.ts`, `${this.#app.cwdPath}/server.ts`];
     for (const entrypoint of backendEntryPoints) {
       if (!(await Bun.file(entrypoint).exists())) throw new Error(`Backend entrypoint not found: ${entrypoint}`);
@@ -188,17 +208,20 @@ export class ApplicationBuildRunner {
       define: { "process.env.NODE_ENV": JSON.stringify("production") },
       plugins: backendExternals.length > 0 ? [this.#createExternalSpecifiersPlugin(backendExternals)] : [],
     });
-    const rscWorkerResult = await this.#buildOrThrow("rsc-worker", {
-      entrypoints: [this.#resolveRscWorkerBuildEntry()],
-      outdir: this.#app.dist.cwdPath,
-      target: "bun",
-      minify: true,
-      naming: { entry: "[name].[ext]", chunk: "chunk-[hash].[ext]" },
-      conditions: ["react-server"],
-      // `akan build` must embed production react-server-dom regardless of the shell's NODE_ENV.
-      define: { "process.env.NODE_ENV": JSON.stringify("production") },
-      plugins: backendExternals.length > 0 ? [this.#createExternalSpecifiersPlugin(backendExternals)] : [],
-    });
+    // Nothing spawns the RSC worker without SSR, so an api-only image does not carry it.
+    const rscWorkerResult = web.ssr
+      ? await this.#buildOrThrow("rsc-worker", {
+          entrypoints: [this.#resolveRscWorkerBuildEntry()],
+          outdir: this.#app.dist.cwdPath,
+          target: "bun",
+          minify: true,
+          naming: { entry: "[name].[ext]", chunk: "chunk-[hash].[ext]" },
+          conditions: ["react-server"],
+          // `akan build` must embed production react-server-dom regardless of the shell's NODE_ENV.
+          define: { "process.env.NODE_ENV": JSON.stringify("production") },
+          plugins: backendExternals.length > 0 ? [this.#createExternalSpecifiersPlugin(backendExternals)] : [],
+        })
+      : null;
     const consoleRuntimeResult = await this.#buildOrThrow("console-runtime", {
       entrypoints: [this.#resolveConsoleRuntimeBuildEntry()],
       outdir: this.#app.dist.cwdPath,
@@ -209,8 +232,9 @@ export class ApplicationBuildRunner {
     });
     await this.#writeConsoleShim();
     return {
-      entrypoints: backendEntryPoints.length + 2,
-      outputs: backendResult.outputs.length + rscWorkerResult.outputs.length + consoleRuntimeResult.outputs.length + 1,
+      entrypoints: backendEntryPoints.length + (rscWorkerResult ? 2 : 1),
+      outputs:
+        backendResult.outputs.length + (rscWorkerResult?.outputs.length ?? 0) + consoleRuntimeResult.outputs.length + 1,
     };
   }
 

package/artifact/implicitRootLayout.ts

@@ -55,7 +55,7 @@ interface RootBoundary {
   segments: string[];
 }
 
-function getRootBoundarySegments(key: string): string[] | null {
+export function getRootBoundarySegments(key: string): string[] | null {
   const match = LAYOUT_KEY_RE.exec(key);
   if (!match) return null;
   const prefix = match[1]?.replace(/\/$/, "");
@@ -76,7 +76,7 @@ function implicitDictionaryMacroAbsPath(appCwdPath: string): string {
   return path.join(path.resolve(appCwdPath), IMPLICIT_DICT_DIR, "useDict.ts");
 }
 
-function isRootBoundarySegments(segments: string[], basePaths: Iterable<string>): boolean {
+export function isRootBoundarySegments(segments: string[], basePaths: Iterable<string>): boolean {
   const firstVisibleIndex = segments.findIndex((segment) => !/^\(.+\)$/.test(segment));
   if (firstVisibleIndex === -1) return segments.length <= 1;
   if (segments.slice(firstVisibleIndex + 1).some((segment) => /^\(.+\)$/.test(segment))) return false;