@akanjs/devkit 2.4.0 → 2.4.1-rc.1

package/akanApp/akanApp.host.ts

@@ -6,7 +6,7 @@ import { createTunnel } from "../createTunnel";
 import { WorkspaceExecutor } from "../executors";
 import { IncrementalBuilderHost } from "../incrementalBuilder";
 
-const backendMsgTypeSet = new Set<BuilderMessage["type"]>(["build-route"]);
+const backendMsgTypeSet = new Set<BuilderMessage["type"]>(["build-route", "build-csr"]);
 const BACKEND_RESTART_DEBOUNCE_MS = 120;
 // Must exceed the gateway's child-wait budget (AkanApp child shutdown, ~5s in dev) so the gateway
 // is never SIGKILLed while its replicas are still shutting down — that's what strands orphans.
@@ -955,13 +955,30 @@ export class AkanAppHost {
     });
   }
   #sendToBuilder(message: BuilderMessage): void {
+    // The builder skips dev CSR artifacts until a `?csr=true` request needs one. Remember that this
+    // session armed it and pass the flag through `env`, which is re-read on every builder spawn, so a
+    // builder restart re-arms itself instead of silently breaking an in-progress mobile dev session.
+    if (message.type === "build-csr" && this.env.AKAN_DEV_CSR_REBUILD !== "1") {
+      Object.assign(this.env, { AKAN_DEV_CSR_REBUILD: "1" });
+      this.logger.verbose(`[csr] armed dev CSR rebuilds (${message.reason})`);
+    }
     if (this.#builder?.send(message)) return;
+    const status = this.#builder?.status ?? "stopped";
     if (message.type === "build-route") {
       this.#sendToBackend({
         type: "build-route-res",
         id: message.id,
         ok: false,
-        error: `builder is ${this.#builder?.status ?? "stopped"}; reload after the builder is ready`,
+        error: `builder is ${status}; reload after the builder is ready`,
+      });
+      return;
+    }
+    if (message.type === "build-csr") {
+      this.#sendToBackend({
+        type: "build-csr-res",
+        id: message.id,
+        ok: false,
+        error: `builder is ${status}; reload after the builder is ready`,
       });
       return;
     }

package/cloud/constants.ts

@@ -1,6 +1,6 @@
 import type { Dayjs } from "dayjs";
-import { GlobalConfig } from "..";
 import type { SupportedLlmModel } from "../aiEditor";
+import { GlobalConfig } from "./globalConfig";
 
 export const basePath = `${Bun.env.HOME ?? Bun.env.USERPROFILE}/.akan`;
 export const configPath = `${basePath}/config.json`;

package/commandDecorators/command.ts

@@ -3,9 +3,13 @@ import { confirm, input, select } from "@inquirer/prompts";
 import { Logger } from "akanjs/common";
 import chalk from "chalk";
 import { type Command, program } from "commander";
-
-import { FileSys, getDirname, type PackageJson } from "..";
 import { AppExecutor, Executor, LibExecutor, ModuleExecutor, PkgExecutor, WorkspaceExecutor } from "../executors";
+// Import the owning modules directly, never the root barrel: `..` re-exports all 41 devkit modules,
+// so a barrel import here drags ink, @trapezedev/project, ssh2, @langchain/* and the cloud stack into
+// every process that registers a command (measured: 236MB vs 3MB).
+import { FileSys } from "../fileSys";
+import { getDirname } from "../getDirname";
+import type { PackageJson } from "../types";
 import {
   type ArgMeta,
   type CommandContext,
@@ -16,7 +20,7 @@ import {
 } from "./argMeta";
 import { CommandContainer } from "./dependencyBuilder";
 import { formatCommandHelp, formatHelp } from "./helpFormatter";
-import { type CommandCls, getTargetMetas } from "./targetMeta";
+import { type CommandCls, getTargetCommandNames, getTargetMetas } from "./targetMeta";
 
 const camelToKebabCase = (str: string) => str.replace(/([A-Z])/g, "-$1").toLowerCase();
 const loggedCliErrorObjects = new WeakSet<object>();
@@ -295,19 +299,7 @@ It may cause unexpected behavior. Run \`akan update\` to update latest akanjs.`,
   for (const command of commands) {
     const targetMetas = getTargetMetas(command);
     for (const targetMeta of targetMetas) {
-      const kebabKey = camelToKebabCase(targetMeta.key);
-      const commandNames =
-        targetMeta.targetOption.short === true
-          ? [
-              kebabKey,
-              typeof targetMeta.targetOption.short === "string"
-                ? targetMeta.targetOption.short
-                : kebabKey
-                    .split("-")
-                    .map((s) => s.slice(0, 1))
-                    .join(""),
-            ]
-          : [kebabKey];
+      const commandNames = getTargetCommandNames(targetMeta);
       for (const commandName of commandNames) {
         let programCommand = program.command(commandName, {
           hidden: targetMeta.targetOption.devOnly,

package/commandDecorators/targetMeta.ts

@@ -22,6 +22,24 @@ export const getTargetMetas = (command: CommandCls): TargetMeta[] => {
   return [...targetMetaMap.values()];
 };
 
+const camelToKebabCase = (str: string) => str.replace(/([A-Z])/g, "-$1").toLowerCase();
+
+/**
+ * CLI names a target answers to. Shared with the command-manifest generator so a lazily-loaded CLI
+ * resolves `argv[2]` to the same module that `runCommands` would have registered it under.
+ */
+export const getTargetCommandNames = (targetMeta: TargetMeta): string[] => {
+  const kebabKey = camelToKebabCase(targetMeta.key);
+  if (targetMeta.targetOption.short !== true) return [kebabKey];
+  return [
+    kebabKey,
+    kebabKey
+      .split("-")
+      .map((s) => s.slice(0, 1))
+      .join(""),
+  ];
+};
+
 export interface TargetOption {
   type: "public" | "cloud" | "dev";
   short?: string | true;

package/executors.ts

@@ -22,14 +22,15 @@ import {
 } from "akanjs/common";
 import { $ } from "bun";
 import chalk from "chalk";
-import ts from "typescript";
 import { AkanAppConfig, AkanLibConfig, decreaseBuildNum, increaseBuildNum } from "./akanConfig";
 import { FileSys } from "./fileSys";
 import { getDirname } from "./getDirname";
 import { Linter } from "./linter";
 import { AppInfo, LibInfo, PkgInfo, WorkspaceInfo } from "./scanInfo";
 import { Spinner } from "./spinner";
-import { TypeChecker } from "./typeChecker";
+// Type-only: the implementation is loaded on demand in `getTypeChecker` to keep `typescript` out of
+// the resident module graph.
+import type { TypeChecker } from "./typeChecker";
 import type { FileContent, PackageJson, TsConfigJson } from "./types";
 
 const staticTemplateFileExtensions = new Set([
@@ -153,148 +154,6 @@ const parseEnvFile = (envPath: string): Record<string, string> => {
   return env;
 };
 
-const PAGE_ROUTE_EXPORTS = new Set([
-  "default",
-  "pageConfig",
-  "head",
-  "metadata",
-  "generateHead",
-  "generateMetadata",
-  "Loading",
-]);
-const ROOT_LAYOUT_EXPORTS = new Set([
-  "default",
-  "pageConfig",
-  "head",
-  "metadata",
-  "generateHead",
-  "generateMetadata",
-  "fonts",
-  "manifest",
-  "theme",
-  "reconnect",
-  "layoutStyle",
-  "gaTrackingId",
-  "Loading",
-  "NotFound",
-  "Error",
-]);
-const LAYOUT_ROUTE_EXPORTS = new Set([
-  "default",
-  "pageConfig",
-  "head",
-  "metadata",
-  "generateHead",
-  "generateMetadata",
-  "Loading",
-  "NotFound",
-  "Error",
-]);
-
-function validateRouteSourceExports(
-  source: string,
-  filePath: string,
-  kind: "page" | "layout",
-  options: { rootLayout?: boolean } = {},
-) {
-  const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
-  const allowed =
-    kind === "page" ? PAGE_ROUTE_EXPORTS : options.rootLayout ? ROOT_LAYOUT_EXPORTS : LAYOUT_ROUTE_EXPORTS;
-  const exported = new Set<string>();
-  const assertExport = (name: string) => {
-    if (!allowed.has(name)) {
-      throw new Error(`[route-convention] unsupported export "${name}" in ${filePath}`);
-    }
-    exported.add(name);
-  };
-
-  for (const statement of sourceFile.statements) {
-    if (ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement)) continue;
-    if (ts.isExportDeclaration(statement)) {
-      if (statement.isTypeOnly) continue;
-      const clause = statement.exportClause;
-      if (!clause) throw new Error(`[route-convention] export * is not allowed in route modules: ${filePath}`);
-      if (ts.isNamedExports(clause)) {
-        for (const element of clause.elements) {
-          if (element.isTypeOnly) continue;
-          assertExport(element.name.text);
-        }
-      }
-      continue;
-    }
-    const modifiers = ts.canHaveModifiers(statement) ? ts.getModifiers(statement) : undefined;
-    const isExported = modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ?? false;
-    if (!isExported) continue;
-    const isDefault = modifiers?.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword) ?? false;
-    if (isDefault) {
-      assertExport("default");
-      continue;
-    }
-    if (ts.isVariableStatement(statement)) {
-      for (const declaration of statement.declarationList.declarations) {
-        if (ts.isIdentifier(declaration.name)) assertExport(declaration.name.text);
-      }
-      continue;
-    }
-    const name = (statement as unknown as { name?: ts.Node }).name;
-    if (name && ts.isIdentifier(name)) {
-      assertExport(name.text);
-    }
-  }
-  if (exported.has("head") && exported.has("generateHead")) {
-    throw new Error(`[route-convention] head and generateHead cannot both be exported in ${filePath}`);
-  }
-  if (
-    !options.rootLayout &&
-    (exported.has("head") || exported.has("generateHead")) &&
-    (exported.has("metadata") || exported.has("generateMetadata"))
-  ) {
-    throw new Error(
-      `[route-convention] head/generateHead and metadata/generateMetadata cannot both be exported in ${filePath}`,
-    );
-  }
-  if (exported.has("metadata") && exported.has("generateMetadata")) {
-    throw new Error(`[route-convention] metadata and generateMetadata cannot both be exported in ${filePath}`);
-  }
-}
-
-/**
- * Statically enforces that a `_overrides.tsx` route file is a logic-free activation manifest: a plain module
- * (no `"use client"` — the framework generates the client wrapper) that only imports components and binds them
- * to slots through a single `export default override({ Modal: BrandModal })`. It must not declare components
- * inline or run logic — that keeps the override contract a thin binding layer rather than a second place to
- * author UI. Slot names and value types are validated at compile time by `override`.
- */
-function validateOverridesSourceExports(source: string, filePath: string) {
-  const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
-  const fail = (message: string): never => {
-    throw new Error(`[route-convention] ${message}: ${filePath}`);
-  };
-  let defaultOverride: ts.ExportAssignment | null = null;
-  for (const statement of sourceFile.statements) {
-    // A "use client" directive is unnecessary (the framework wraps the manifest) but harmless if present.
-    if (ts.isExpressionStatement(statement) && ts.isStringLiteral(statement.expression)) continue;
-    // The manifest imports the app components it binds; imports and type-only decls carry no runtime logic.
-    if (ts.isImportDeclaration(statement)) continue;
-    if (ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement)) continue;
-    if (ts.isExportAssignment(statement) && !statement.isExportEquals) {
-      defaultOverride = statement;
-      continue;
-    }
-    fail(`_overrides.tsx may only contain imports and a single "export default override({ ... })"`);
-  }
-  if (!defaultOverride) fail(`_overrides.tsx must "export default override({ ... })"`);
-  const expression = defaultOverride.expression;
-  if (
-    !ts.isCallExpression(expression) ||
-    !ts.isIdentifier(expression.expression) ||
-    expression.expression.text !== "override"
-  )
-    fail(
-      `_overrides.tsx default export must be a call to "override", e.g. "export default override({ Modal: BrandModal })"`,
-    );
-}
-
 export class Executor {
   static verbose = false;
   static setVerbose(verbose: boolean) {
@@ -798,13 +657,17 @@ export class Executor {
     };
     return this._applyTemplate({ ...options, dict });
   }
-  getTypeChecker() {
+  // Async so `typescript` (~65MB resident) is loaded only by the commands that actually typecheck,
+  // not by every process that imports an executor. `typeCheckAsync` below runs in a subprocess and
+  // never touches this path.
+  async getTypeChecker() {
+    const { TypeChecker } = await import("./typeChecker");
     this.typeChecker ??= new TypeChecker(this);
     return this.typeChecker;
   }
-  typeCheck(filePath: string) {
+  async typeCheck(filePath: string) {
     const path = this.getPath(filePath);
-    const typeChecker = this.getTypeChecker();
+    const typeChecker = await this.getTypeChecker();
     const { fileDiagnostics, fileErrors, fileWarnings } = typeChecker.check(path);
     const message = typeChecker.formatDiagnostics(fileDiagnostics);
     return { fileDiagnostics, fileErrors, fileWarnings, message };
@@ -1370,6 +1233,13 @@ interface AppExecutorOptions {
   name: string;
 }
 export class AppExecutor extends SysExecutor {
+  // `typescript` costs ~65MB resident, so keep it out of the module graph of every process that only
+  // ever imports an executor. Route validation is the sole consumer here and is already async.
+  static #routeSourceValidator: typeof import("./routeSourceValidator").RouteSourceValidator | null = null;
+  static async #getRouteSourceValidator() {
+    AppExecutor.#routeSourceValidator ??= (await import("./routeSourceValidator")).RouteSourceValidator;
+    return AppExecutor.#routeSourceValidator;
+  }
   dist: Executor;
   override emoji = execEmoji.app;
   constructor({ workspace, name }: AppExecutorOptions) {
@@ -1502,8 +1372,9 @@ export class AppExecutor extends SysExecutor {
       }
       const isRootLayout = parsed.kind === "layout" && parsed.moduleSegments.at(-1) === "_layout";
       const routeSource = await Bun.file(absPath).text();
-      if (parsed.kind === "overrides") validateOverridesSourceExports(routeSource, absPath);
-      else validateRouteSourceExports(routeSource, absPath, parsed.kind, { rootLayout: isRootLayout });
+      const validator = await AppExecutor.#getRouteSourceValidator();
+      if (parsed.kind === "overrides") validator.validateOverridesSourceExports(routeSource, absPath);
+      else validator.validateRouteSourceExports(routeSource, absPath, parsed.kind, { rootLayout: isRootLayout });
       pageKeys.push(key);
     }
     pageKeys.sort();

package/incrementalBuilder/incrementalBuilder.host.ts

@@ -5,6 +5,7 @@ import type { App } from "../commandDecorators";
 
 const builderMsgTypeSet = new Set<BuilderMessage["type"]>([
   "build-route-res",
+  "build-csr-res",
   "builder-ready",
   "invalidate",
   "css-updated",

package/incrementalBuilder/incrementalBuilder.proc.ts

@@ -1,7 +1,9 @@
 import path from "node:path";
+// Subpath imports only: the `@akanjs/devkit` root barrel re-exports all 41 modules, which would drag
+// @trapezedev/project, the @langchain stack, ssh2, ink and the cloud stack into the builder process.
+import type { App } from "@akanjs/devkit/commandDecorators";
+import { AppExecutor, WorkspaceExecutor } from "@akanjs/devkit/executors";
 import {
-  type App,
-  AppExecutor,
   AutoImportSync,
   type ChangeBatch,
   type ClientEntryDiscovery,
@@ -16,11 +18,12 @@ import {
   RouteClientBuilder,
   SsrBaseArtifactBuilder,
   WatchRootResolver,
-  WorkspaceExecutor,
-} from "@akanjs/devkit";
+} from "@akanjs/devkit/frontendBuild";
 import { Logger } from "akanjs/common";
 import type {
   BaseBuildArtifact,
+  BuilderCsrReq,
+  BuilderCsrRes,
   BuilderMessage,
   BuilderReq,
   BuilderRes,
@@ -56,6 +59,7 @@ class IncrementalBuilder {
   #generatedIndexSync: DevGeneratedIndexSync;
   #autoImportSync: AutoImportSync;
   #generation = 0;
+  #csrActive = IncrementalBuilder.#csrArmedByEnv();
   #workQueue: Promise<void> = Promise.resolve();
   #cssRebuildQueue: Promise<void> = Promise.resolve();
   #cssRebuildTimer: ReturnType<typeof setTimeout> | null = null;
@@ -346,7 +350,9 @@ class IncrementalBuilder {
         this.#sendBuildStatus("csr", { generation, ok: false, files, message });
       }
     } else if (kinds.includes("code") && rebuildClient) {
-      this.#logger.verbose(`csr-rebundle skipped; set AKAN_DEV_CSR_REBUILD=1 to enable per-save CSR rebuilds`);
+      this.#logger.verbose(
+        `csr-rebundle skipped; request /__csr or ?csr=true (or set AKAN_DEV_CSR_REBUILD=1) to enable per-save CSR rebuilds`,
+      );
     }
 
     process.send?.(event);
@@ -404,14 +410,40 @@ class IncrementalBuilder {
     });
   }
 
+  /**
+   * Build the dev CSR artifact because a request asked for it, and keep it in sync from now on. The
+   * dev server only serves CSR through the opt-in `/__csr` and `?csr=true` routes — mobile local dev
+   * points a device WebView at the latter — so nothing needs the artifact until one of them is hit.
+   */
+  async handleBuildCsr(msg: BuilderCsrReq): Promise<BuilderCsrRes> {
+    return this.#enqueueWork("build-csr", async (): Promise<BuilderCsrRes> => {
+      const started = Date.now();
+      try {
+        await new CsrArtifactBuilder(this.#app).build();
+        this.#csrActive = true;
+        this.#logger.info(`csr-build ok on demand (${Date.now() - started}ms); rebuilding CSR on every save now`);
+        return { type: "build-csr-res", id: msg.id, ok: true };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        this.#logger.error(`csr-build failed: ${message}`);
+        return { type: "build-csr-res", id: msg.id, ok: false, error: message };
+      }
+    });
+  }
+
   #shouldRebuildCsr() {
-    // CSR is served by `akn start`, so rebuild dev CSR artifacts until incremental CSR HMR is implemented.
-    return true;
+    return this.#csrActive;
+  }
+
+  static #csrArmedByEnv() {
+    return process.env.AKAN_DEV_CSR_REBUILD === "1";
   }
 
   static async #buildBootDeps(app: App): Promise<IncrementalBuilderBootDeps> {
     const { artifact, cssCompiler, optimizedFonts } = await new SsrBaseArtifactBuilder(app).build();
-    await new CsrArtifactBuilder(app).build();
+    //* A full minified browser-target build of every page costs ~350MB of bundler arena the process
+    //* never returns, so skip it until a `/__csr` or `?csr=true` request arms it via `build-csr`.
+    if (IncrementalBuilder.#csrArmedByEnv()) await new CsrArtifactBuilder(app).build();
     const discovery = await GraphClientEntryDiscovery.create(app);
     return { artifact, cssCompiler, optimizedFonts, discovery };
   }
@@ -476,20 +508,26 @@ class IncrementalBuilder {
     const app = AppExecutor.from(workspace, appName);
     const watch = process.env.AKAN_WATCH !== "0";
     let builder: IncrementalBuilder | null = null;
-    // Registered before the boot build so build-route requests get an error response (instead of
-    // hanging the backend) while the builder is still booting or recovering from a failed build.
+    // Registered before the boot build so backend requests get an error response (instead of hanging
+    // the backend) while the builder is still booting or recovering from a failed build.
+    const bootingError = "builder is recovering from a failed boot build; retry after the build error is fixed";
     process.on("message", (msg: BuilderMessage) => {
-      if (!msg || typeof msg !== "object" || msg.type !== "build-route") return;
-      if (!builder) {
-        process.send?.({
-          type: "build-route-res",
-          id: msg.id,
-          ok: false,
-          error: "builder is recovering from a failed boot build; retry after the build error is fixed",
-        });
+      if (!msg || typeof msg !== "object") return;
+      if (msg.type === "build-route") {
+        if (!builder) {
+          process.send?.({ type: "build-route-res", id: msg.id, ok: false, error: bootingError });
+          return;
+        }
+        void builder.handleBuildRoute(msg).then((res) => process.send?.(res));
         return;
       }
-      void builder.handleBuildRoute(msg).then((res) => process.send?.(res));
+      if (msg.type === "build-csr") {
+        if (!builder) {
+          process.send?.({ type: "build-csr-res", id: msg.id, ok: false, error: bootingError });
+          return;
+        }
+        void builder.handleBuildCsr(msg).then((res) => process.send?.(res));
+      }
     });
     // The IPC channel closes when the dev host dies (including SIGKILL); exit instead of running
     // as an orphaned watcher that keeps rebuilding for nobody.

package/index.ts

@@ -1,41 +1,54 @@
-export * from "./aiEditor";
-export * from "./akanApp";
-export * from "./akanConfig";
-export * from "./akanContext";
-export * from "./akanMcpContract";
-export * from "./applicationBuildReporter";
-export * from "./applicationBuildRunner";
-export * from "./applicationReleasePackager";
-export * from "./applicationTestPreload";
-export * from "./artifact";
-export * from "./builder";
-export * from "./capacitorApp";
-export * from "./cloud";
-export * from "./cloud";
-export * from "./commandDecorators";
-export * from "./createTunnel";
-export * from "./dependencyScanner";
-export * from "./executors";
-export * from "./extractDeps";
-export * from "./fileSys";
-export * from "./frontendBuild";
-export * from "./getCredentials";
-export * from "./getDirname";
-export * from "./getModelFileData";
-export * from "./getRelatedCnsts";
-export * from "./guideline";
-export * from "./incrementalBuilder";
-export * from "./mobile";
-export * from "./prompter";
-export * from "./qualityScanner";
-export * from "./scanInfo";
-export * from "./selectModel";
-export * from "./spinner";
-export * from "./streamAi";
-export * from "./transforms";
-export * from "./typeChecker";
-export * from "./types";
-export * from "./ui";
-export * from "./uploadRelease";
-export * from "./useStdoutDimensions";
-export * from "./workflow";
+// Types only, deliberately. This barrel re-exports all 40 devkit facets, so a single *value* import
+// from it loads every one of them — measured at 417MB / 654ms, versus 38MB / 38ms for the one subpath
+// the caller actually needed. That is how `commandDecorators/command.ts` silently put ink, typescript,
+// ssh2, @trapezedev/project, @langchain/* and the cloud stack into every process that registered a CLI
+// command, and it is the single largest regression this package can suffer from a one-line edit.
+//
+// `export type *` erases at runtime (verified on Bun 1.3.14: the re-exported module is never loaded),
+// so `import type { App } from "@akanjs/devkit"` stays free and readable while a value import fails to
+// compile with a self-explaining error:
+//
+//   TS1362: 'FileSys' cannot be used as a value because it was exported using 'export type'.
+//
+// Import values from the owning facet instead: `import { FileSys } from "@akanjs/devkit/fileSys"`.
+// Keep this file type-only; do not "fix" a TS1362 by widening an entry back to `export *`.
+export type * from "./aiEditor";
+export type * from "./akanApp";
+export type * from "./akanConfig";
+export type * from "./akanContext";
+export type * from "./akanMcpContract";
+export type * from "./applicationBuildReporter";
+export type * from "./applicationBuildRunner";
+export type * from "./applicationReleasePackager";
+export type * from "./applicationTestPreload";
+export type * from "./artifact";
+export type * from "./builder";
+export type * from "./capacitorApp";
+export type * from "./cloud";
+export type * from "./commandDecorators";
+export type * from "./createTunnel";
+export type * from "./dependencyScanner";
+export type * from "./executors";
+export type * from "./extractDeps";
+export type * from "./fileSys";
+export type * from "./frontendBuild";
+export type * from "./getCredentials";
+export type * from "./getDirname";
+export type * from "./getModelFileData";
+export type * from "./getRelatedCnsts";
+export type * from "./guideline";
+export type * from "./incrementalBuilder";
+export type * from "./mobile";
+export type * from "./prompter";
+export type * from "./qualityScanner";
+export type * from "./scanInfo";
+export type * from "./selectModel";
+export type * from "./spinner";
+export type * from "./streamAi";
+export type * from "./transforms";
+export type * from "./typeChecker";
+export type * from "./types";
+export type * from "./ui";
+export type * from "./uploadRelease";
+export type * from "./useStdoutDimensions";
+export type * from "./workflow";

package/integration/devStability.integration.test.ts

@@ -4,6 +4,7 @@ import { DevStabilityHarness } from "./devStabilityHarness";
 
 const integrationEnabled = process.env.AKAN_DEV_STABILITY_INTEGRATION === "1";
 const INTEGRATION_TIMEOUT_MS = 120_000;
+const MB = 1024 * 1024;
 const harnesses: DevStabilityHarness[] = [];
 
 const integrationTest = (name: string, fn: () => Promise<void>): void => {
@@ -404,3 +405,100 @@ export class FixtureService extends serve("fixture" as const, { serverMode: "bat
     expect(manualSmoke).toHaveLength(2);
   });
 });
+
+/**
+ * Resource budgets for `akan start`. A dev sandbox holds this process tree for a whole session, so
+ * every regression here multiplies by the number of tenants. Budgets are deliberately loose (they
+ * carry headroom over the measured values) — they exist to catch a *reintroduced* eager import or an
+ * unbounded per-save ratchet, not to pin exact numbers. Raising one should be a visible diff.
+ *
+ * Deliberately two tests, not one per property: each boots a full dev server, and four boots after
+ * the eleven tests above pushed cold boot from 3s to 21-55s through sheer machine contention, which
+ * silently exhausted the waits and looked like product failures. Both tests therefore assert several
+ * related properties against a single boot, with explicit generous waits. Run the block on its own
+ * (`-t "dev resource budgets"`) when timing matters.
+ */
+describe("dev resource budgets", () => {
+  const BOOT_MS = 150_000;
+  const WAIT_MS = 90_000;
+  const budgetTest = (name: string, fn: () => Promise<void>): void => {
+    if (integrationEnabled) test(name, fn, 300_000);
+    else test.skip(name, fn);
+  };
+
+  budgetTest("builds the dev CSR artifact only once a request needs it, then keeps it in sync", async () => {
+    const harness = await createHarness();
+    const host = await harness.startHost({ timeoutMs: BOOT_MS });
+    const port = await harness.resolvePort();
+
+    // A full minified browser-target build of every page, only reachable via `/__csr` and `?csr=true`.
+    expect(host.logs.join("")).not.toMatch(/\[csr-build\] output ->/);
+
+    // Mobile local dev points a device WebView at this URL, so it must serve HTML, not a 404. Wait
+    // for the app to actually serve first: `backend ready` fires before the gateway routes to the
+    // replica, and a too-early request 503s without reaching the router that arms CSR.
+    await harness.waitForHttpText("initial-client-marker", WAIT_MS);
+    const armMark = host.markLog();
+    const res = await fetch(`http://127.0.0.1:${port}/?csr=true`);
+    expect(res.status).toBe(200);
+    expect(await res.text()).toContain("<html");
+    expect(host.logs.join("").slice(armMark)).toMatch(/csr-build ok on demand/);
+
+    // Armed: from here on every save rebuilds CSR, which is what keeps a live mobile session working.
+    //
+    // The settle wait is not padding. Bun's recursive `fs.watch` on macOS silently drops a file event
+    // that lands in the same FSEvents coalescing window as a burst of writes elsewhere in the tree, and
+    // the CSR build above emits exactly such a burst into `.akan/artifact/csr`. Saving immediately after
+    // the request returns therefore loses the event 100% of the time — a Bun bug this test must not
+    // depend on. See `local/optimize-resource/06-watcher-dropped-event.md` for the 30-line repro.
+    await Bun.sleep(500);
+    const resyncMark = host.markLog();
+    await harness.replaceText("ui/ClientMarker.tsx", "initial-client-marker", "csr-armed-marker");
+    await host.waitForLogSince(resyncMark, /csr-rebundle ok/, WAIT_MS);
+  });
+
+  budgetTest("bounds the rsc worker and the tree across repeated saves", async () => {
+    const harness = await createHarness();
+    const host = await harness.startHost({
+      // Recycle on the second reload so this needs a couple of saves rather than the ten a
+      // default-threshold run would take, and take the burst-coalescing floor out of the equation.
+      timeoutMs: BOOT_MS,
+      env: { AKAN_RSC_WORKER_MAX_RELOADS: "1", AKAN_RSC_WORKER_MIN_RECYCLE_INTERVAL_MS: "1" },
+    });
+    await harness.waitForHttpText("initial-client-marker", WAIT_MS);
+
+    const idleTotal = await DevStabilityHarness.processTreeRssBytes(host.proc.pid);
+    const idleWithoutBuilder = await DevStabilityHarness.processTreeRssBytes(host.proc.pid, { excludeBuilder: true });
+    // Measured ~670MB for this fixture; the headroom covers machine variance, not a reintroduced
+    // eager import (the cheapest of those is ~30MB, and the devkit barrel cycle was 236MB).
+    expect(idleTotal).toBeLessThan(1_000 * MB);
+
+    const start = host.markLog();
+    for (let i = 1; i <= 3; i++) {
+      const mark = host.markLog();
+      await harness.replaceText("ui/ClientMarker.tsx", /marker(-\d+)?/, `marker-${i}`);
+      await host.waitForLogSince(mark, /pages-rebundle ok/, WAIT_MS);
+      // CSR was never requested in this fixture, so no save may pay for a CSR rebuild.
+      const afterSave = host.logs.join("").slice(mark);
+      expect(afterSave).toMatch(/csr-rebundle skipped/);
+      expect(afterSave).not.toMatch(/csr-rebundle ok/);
+      // The debounced CSS rebuild is still writing after `pages-rebundle ok`, and Bun drops a watcher
+      // event that lands in the same window as a write burst (`06-watcher-dropped-event.md`). Saving
+      // again before this save's last artifact write lands loses the next edit outright, which showed
+      // up as this test hanging for the full 90s wait on iteration 2.
+      await host.waitForLogSince(mark, /css-rebuild checked/, WAIT_MS);
+    }
+
+    // Each in-place reload re-imports the pages bundle under a fresh `?v=`, and Bun's ESM registry
+    // never evicts — so without a recycle the worker grows for the life of the process.
+    await host.waitForLogSince(start, /rolling recycle worker reason=pages-reload-accumulation/, WAIT_MS);
+
+    // The dev host, gateway, replica and rsc worker must all stay flat across saves. The builder is
+    // still expected to grow — `Bun.build` retains native arenas that no GC reclaims, which the
+    // bounded-builder work addresses — so it is excluded here rather than silently tolerated.
+    const afterWithoutBuilder = await DevStabilityHarness.processTreeRssBytes(host.proc.pid, {
+      excludeBuilder: true,
+    });
+    expect(afterWithoutBuilder - idleWithoutBuilder).toBeLessThan(120 * MB);
+  });
+});

package/integration/devStabilityHarness.ts

@@ -252,7 +252,13 @@ export const dictionary = serviceDictionary(["en", "ko"])
     await rm(this.appDir, { recursive: true, force: true });
   }
 
-  async startHost(timeoutMs = DEFAULT_TIMEOUT_MS): Promise<DevStabilityHost> {
+  async startHost({
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    env = {},
+  }: {
+    timeoutMs?: number;
+    env?: Record<string, string>;
+  } = {}): Promise<DevStabilityHost> {
     const logs: string[] = [];
     const proc = Bun.spawn(["bash", "-lc", `bun run akan start ${JSON.stringify(this.appName)}`], {
       cwd: this.workspaceRoot,
@@ -264,6 +270,7 @@ export const dictionary = serviceDictionary(["en", "ko"])
         AKAN_PUBLIC_LOG_LEVEL: "verbose",
         NODE_NO_WARNINGS: "1",
         PORT_OFFSET: String(this.portOffset),
+        ...env,
       },
       stdout: "pipe",
       stderr: "pipe",
@@ -292,9 +299,14 @@ export const dictionary = serviceDictionary(["en", "ko"])
       waitForLog: (pattern, waitMs) => waitForLog(logs, pattern, waitMs),
       waitForLogSince: (mark, pattern, waitMs) => waitForLogSince(logs, mark, pattern, waitMs),
       stop: async () => {
-        proc.kill("SIGTERM");
+        // The host runs under `bash -lc`, so killing `proc` only kills the shell: the dev host, its
+        // builder and its backend outlive it as orphans that keep watching a deleted fixture app and
+        // interfere with later tests. Collect the descendants first, then signal all of them.
+        const pids = await DevStabilityHarness.descendantPids(proc.pid);
+        DevStabilityHarness.#signalPids(pids, "SIGTERM");
         await Promise.race([proc.exited.catch(() => undefined), wait(3_000)]);
-        if (!proc.killed) proc.kill("SIGKILL");
+        DevStabilityHarness.#signalPids(await DevStabilityHarness.descendantPids(proc.pid), "SIGKILL");
+        DevStabilityHarness.#signalPids(pids, "SIGKILL");
       },
     };
     this.#host = host;
@@ -441,6 +453,75 @@ export const dictionary = serviceDictionary(["en", "ko"])
     );
     return 8282 + Math.max(apps.indexOf(this.appName), 0) + this.portOffset;
   }
+
+  /**
+   * Resident set size of the whole `akan start` process tree, which is what a dev sandbox actually
+   * costs: supervisor, builder, gateway, replica and rsc worker. `excludeBuilder` drops the bundler
+   * process, whose growth across saves is `Bun.build` native arena retention rather than a leak the
+   * other processes could be blamed for.
+   */
+  static async processTreeRssBytes(
+    rootPid: number,
+    { excludeBuilder = false }: { excludeBuilder?: boolean } = {},
+  ): Promise<number> {
+    const rows = await DevStabilityHarness.#psRows();
+    const pids = DevStabilityHarness.#collectDescendants(rows, rootPid);
+    return (
+      rows
+        .filter((row) => pids.has(row.pid))
+        // `bun run akan …` is the npm-script shell wrapper, not a dev process.
+        .filter((row) => !row.cmd.startsWith("bash -lc") && !row.cmd.includes("cli/build.ts"))
+        .filter((row) => !excludeBuilder || !row.cmd.includes("incrementalBuilder"))
+        .reduce((total, row) => total + row.rssKb * 1024, 0)
+    );
+  }
+
+  /** Pids of `rootPid` and everything under it, deepest first, so callers can signal children before parents. */
+  static async descendantPids(rootPid: number | undefined): Promise<number[]> {
+    if (!rootPid) return [];
+    const pids = DevStabilityHarness.#collectDescendants(await DevStabilityHarness.#psRows(), rootPid);
+    return [...pids].reverse();
+  }
+
+  static async #psRows(): Promise<Array<{ pid: number; ppid: number; rssKb: number; cmd: string }>> {
+    const output = await Bun.$`ps -eo pid,ppid,rss,command`.text().catch(() => "");
+    return output
+      .split("\n")
+      .slice(1)
+      .flatMap((line) => {
+        const match = /^\s*(\d+)\s+(\d+)\s+(\d+)\s+(.*)$/.exec(line);
+        return match
+          ? [{ pid: Number(match[1]), ppid: Number(match[2]), rssKb: Number(match[3]), cmd: match[4] ?? "" }]
+          : [];
+      });
+  }
+
+  static #collectDescendants(rows: Array<{ pid: number; ppid: number }>, rootPid: number): Set<number> {
+    // Iterate to a fixpoint rather than a fixed depth: the tree is `bash -lc` -> `bun run` -> the `&&`
+    // shell -> dev host -> gateway -> replica -> rsc worker, and a pass only guarantees one new
+    // generation when `ps` happens to list parents before children. A capped walk silently leaves the
+    // deepest processes unsignalled, which is how orphaned dev hosts survived `stop()`.
+    const pids = new Set([rootPid]);
+    for (let added = 1; added > 0; ) {
+      added = 0;
+      for (const row of rows)
+        if (pids.has(row.ppid) && !pids.has(row.pid)) {
+          pids.add(row.pid);
+          added++;
+        }
+    }
+    return pids;
+  }
+
+  static #signalPids(pids: number[], signal: NodeJS.Signals): void {
+    for (const pid of pids) {
+      try {
+        process.kill(pid, signal);
+      } catch {
+        // Already exited, or reaped between the `ps` snapshot and here.
+      }
+    }
+  }
 }
 
 export async function waitForHmrMessageSince(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "2.4.0",
+  "version": "2.4.1-rc.1",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -23,7 +23,19 @@
       "default": "./index.ts"
     },
     "./package.json": "./package.json",
-    "./*": "./*"
+    "./akanApp": "./akanApp/index.ts",
+    "./akanConfig": "./akanConfig/index.ts",
+    "./artifact": "./artifact/index.ts",
+    "./cloud": "./cloud/index.ts",
+    "./commandDecorators": "./commandDecorators/index.ts",
+    "./frontendBuild": "./frontendBuild/index.ts",
+    "./incrementalBuilder": "./incrementalBuilder/index.ts",
+    "./mobile": "./mobile/index.ts",
+    "./transforms": "./transforms/index.ts",
+    "./ui": "./ui/index.ts",
+    "./workflow": "./workflow/index.ts",
+    "./*.ts": "./*.ts",
+    "./*": "./*.ts"
   },
   "dependencies": {
     "@inquirer/prompts": "^8.4.3",
@@ -32,7 +44,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "2.4.0",
+    "akanjs": "2.4.1-rc.1",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "daisyui": "5.5.23",

package/routeSourceValidator.ts

@@ -0,0 +1,158 @@
+import ts from "typescript";
+
+/**
+ * Static enforcement of the `page/` route conventions, split out of `executors.ts` so that importing
+ * an executor does not pull `typescript` (+65MB resident) into the module graph. Both validators need
+ * a real AST — modifier inspection, `export *` rejection, statement-kind walking and call-expression
+ * identity — so `Bun.Transpiler.scan()`, which only reports export names, cannot replace them.
+ *
+ * Import it dynamically (`await import("./routeSourceValidator")`) so long-lived processes that never
+ * validate a route source stay lean.
+ */
+export class RouteSourceValidator {
+  static readonly #pageExports = new Set([
+    "default",
+    "pageConfig",
+    "head",
+    "metadata",
+    "generateHead",
+    "generateMetadata",
+    "Loading",
+  ]);
+  static readonly #rootLayoutExports = new Set([
+    "default",
+    "pageConfig",
+    "head",
+    "metadata",
+    "generateHead",
+    "generateMetadata",
+    "fonts",
+    "manifest",
+    "theme",
+    "reconnect",
+    "layoutStyle",
+    "gaTrackingId",
+    "Loading",
+    "NotFound",
+    "Error",
+  ]);
+  static readonly #layoutExports = new Set([
+    "default",
+    "pageConfig",
+    "head",
+    "metadata",
+    "generateHead",
+    "generateMetadata",
+    "Loading",
+    "NotFound",
+    "Error",
+  ]);
+
+  static validateRouteSourceExports(
+    source: string,
+    filePath: string,
+    kind: "page" | "layout",
+    options: { rootLayout?: boolean } = {},
+  ) {
+    const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+    const allowed =
+      kind === "page"
+        ? RouteSourceValidator.#pageExports
+        : options.rootLayout
+          ? RouteSourceValidator.#rootLayoutExports
+          : RouteSourceValidator.#layoutExports;
+    const exported = new Set<string>();
+    const assertExport = (name: string) => {
+      if (!allowed.has(name)) {
+        throw new Error(`[route-convention] unsupported export "${name}" in ${filePath}`);
+      }
+      exported.add(name);
+    };
+
+    for (const statement of sourceFile.statements) {
+      if (ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement)) continue;
+      if (ts.isExportDeclaration(statement)) {
+        if (statement.isTypeOnly) continue;
+        const clause = statement.exportClause;
+        if (!clause) throw new Error(`[route-convention] export * is not allowed in route modules: ${filePath}`);
+        if (ts.isNamedExports(clause)) {
+          for (const element of clause.elements) {
+            if (element.isTypeOnly) continue;
+            assertExport(element.name.text);
+          }
+        }
+        continue;
+      }
+      const modifiers = ts.canHaveModifiers(statement) ? ts.getModifiers(statement) : undefined;
+      const isExported = modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+      if (!isExported) continue;
+      const isDefault = modifiers?.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword) ?? false;
+      if (isDefault) {
+        assertExport("default");
+        continue;
+      }
+      if (ts.isVariableStatement(statement)) {
+        for (const declaration of statement.declarationList.declarations) {
+          if (ts.isIdentifier(declaration.name)) assertExport(declaration.name.text);
+        }
+        continue;
+      }
+      const name = (statement as unknown as { name?: ts.Node }).name;
+      if (name && ts.isIdentifier(name)) {
+        assertExport(name.text);
+      }
+    }
+    if (exported.has("head") && exported.has("generateHead")) {
+      throw new Error(`[route-convention] head and generateHead cannot both be exported in ${filePath}`);
+    }
+    if (
+      !options.rootLayout &&
+      (exported.has("head") || exported.has("generateHead")) &&
+      (exported.has("metadata") || exported.has("generateMetadata"))
+    ) {
+      throw new Error(
+        `[route-convention] head/generateHead and metadata/generateMetadata cannot both be exported in ${filePath}`,
+      );
+    }
+    if (exported.has("metadata") && exported.has("generateMetadata")) {
+      throw new Error(`[route-convention] metadata and generateMetadata cannot both be exported in ${filePath}`);
+    }
+  }
+
+  /**
+   * Statically enforces that a `_overrides.tsx` route file is a logic-free activation manifest: a plain module
+   * (no `"use client"` — the framework generates the client wrapper) that only imports components and binds them
+   * to slots through a single `export default override({ Modal: BrandModal })`. It must not declare components
+   * inline or run logic — that keeps the override contract a thin binding layer rather than a second place to
+   * author UI. Slot names and value types are validated at compile time by `override`.
+   */
+  static validateOverridesSourceExports(source: string, filePath: string) {
+    const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+    const fail = (message: string): never => {
+      throw new Error(`[route-convention] ${message}: ${filePath}`);
+    };
+    let defaultOverride: ts.ExportAssignment | null = null;
+    for (const statement of sourceFile.statements) {
+      // A "use client" directive is unnecessary (the framework wraps the manifest) but harmless if present.
+      if (ts.isExpressionStatement(statement) && ts.isStringLiteral(statement.expression)) continue;
+      // The manifest imports the app components it binds; imports and type-only decls carry no runtime logic.
+      if (ts.isImportDeclaration(statement)) continue;
+      if (ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement)) continue;
+      if (ts.isExportAssignment(statement) && !statement.isExportEquals) {
+        defaultOverride = statement;
+        continue;
+      }
+      fail(`_overrides.tsx may only contain imports and a single "export default override({ ... })"`);
+    }
+    if (!defaultOverride) return fail(`_overrides.tsx must "export default override({ ... })"`);
+    const expression = defaultOverride.expression;
+    if (
+      !ts.isCallExpression(expression) ||
+      !ts.isIdentifier(expression.expression) ||
+      expression.expression.text !== "override"
+    )
+      fail(
+        `_overrides.tsx default export must be a call to "override", e.g. "export default override({ Modal: BrandModal })"`,
+      );
+  }
+}

package/scanInfo.ts

@@ -10,7 +10,6 @@ import type {
   ScanResult,
 } from "./akanConfig";
 
-import { TypeScriptDependencyScanner } from "./dependencyScanner";
 import { AppExecutor, LibExecutor, PkgExecutor, WorkspaceExecutor } from "./executors";
 
 const scalarFileTypes = ["constant", "dictionary", "document", "template", "unit", "util", "view", "zone"] as const;
@@ -98,6 +97,11 @@ const moduleUiFileTypes = {
 const testFilePattern = /\.(test|spec)\.(ts|tsx)$/;
 const rootSignalTestFilePattern = /^[A-Za-z][A-Za-z0-9_-]*\.signal\.(test|spec)\.(ts|tsx)$/;
 
+// The dependency scanner needs `typescript` (~65MB resident). Only the scan/sync commands run it, so
+// load it on demand rather than through the module graph of every process that imports scan info.
+const createDependencyScanner = async (exec: AppExecutor | LibExecutor | PkgExecutor) =>
+  (await import("./dependencyScanner")).TypeScriptDependencyScanner.from(exec);
+
 const isAllowedTestFile = (filename: string) => testFilePattern.test(filename);
 const isAllowedLibRootFile = (filename: string) =>
   libRootAllowedFiles.has(filename) || rootSignalTestFilePattern.test(filename);
@@ -241,7 +245,7 @@ class ScanInfo {
   static async getScanResult(exec: AppExecutor | LibExecutor) {
     const [akanConfig, scanner, pkgs, libs] = await Promise.all([
       exec.getConfig(),
-      TypeScriptDependencyScanner.from(exec),
+      createDependencyScanner(exec),
       exec.workspace.getPkgs(),
       exec.workspace.getLibs(),
     ]);
@@ -546,7 +550,7 @@ export class PkgInfo {
 
   static async scanExecutor(exec: PkgExecutor) {
     const [tsconfig, rootPackageJson] = await Promise.all([exec.getTsConfig(), exec.workspace.getPackageJson()]);
-    const scanner = await TypeScriptDependencyScanner.from(exec);
+    const scanner = await createDependencyScanner(exec);
     const npmSet = new Set(Object.keys({ ...rootPackageJson.dependencies, ...rootPackageJson.devDependencies }));
     const pkgPathSet = new Set(
       Object.keys(tsconfig.compilerOptions.paths ?? {})

package/src/capacitorApp.ts

@@ -1,4 +1,5 @@
-import { type AppExecutor, FileSys } from "@akanjs/devkit";
+import type { AppExecutor } from "@akanjs/devkit/executors";
+import { FileSys } from "@akanjs/devkit/fileSys";
 import type { CapacitorConfig } from "@capacitor/cli";
 import { MobileProject } from "@trapezedev/project";
 import type { AndroidProject } from "@trapezedev/project/dist/android/project";