akanjs 2.4.1-rc.3 → 2.4.1-rc.5

package/base/baseEnv.ts

@@ -128,9 +128,11 @@ export const getEnv = (): ClientEnv => {
           ? (window.location.host.split(":")[0] ?? "unknown")
           : "localhost");
 
-  const serverPort = parseInt(
-    process.env.AKAN_PUBLIC_SERVER_PORT ?? (operationMode === "local" || side === "server" ? "8282" : "443"),
-  );
+  const serverPort =
+    side === "server"
+      ? parseInt(process.env.AKAN_PUBLIC_SERVER_PORT ?? (operationMode === "local" ? "8282" : "443"))
+      : parseInt(window.location.port || (window.location.protocol === "https:" ? "443" : "80"));
+
   const serverHttpProtocol: "http:" | "https:" =
     (process.env.SERVER_HTTP_PROTOCOL as "http:" | "https:" | undefined) ??
     (operationMode === "local"

package/dictionary/dictionaryRegistry.ts

@@ -0,0 +1,87 @@
+import { ModelDictInfo, ScalarDictInfo, ServiceDictInfo } from "./dictInfo";
+import type { DictModule } from "./locale";
+import type { DictionaryNode, RootDictionary } from "./trans";
+
+export type DictionaryModuleKind = "model" | "scalar" | "service";
+
+export interface DictionaryModuleInfo {
+  kind: DictionaryModuleKind;
+  languages: string[];
+}
+
+/**
+ * Collects every dictionary tree built by `makeTrans` so a server process can read the merged result.
+ *
+ * `makeTrans` keeps its `rootDictionary` in a closure and `AkanLib` carries no dictionary, so without this
+ * the i18n tree is unreachable from `AkanServer`. Registration happens at module-evaluation time, which the
+ * API process reaches because it imports the generated `server.ts` (which re-exports `lib/dict.ts`) whole.
+ */
+export class DictionaryRegistry {
+  static readonly #roots: RootDictionary[] = [];
+  static readonly #modules = new Map<string, DictionaryModuleInfo>();
+
+  /** Registration order is base → libs → app, matching `makeDictionary`, so a later root wins on conflict. */
+  static register(root: RootDictionary, transMap: Record<string, DictModule<string, string>>) {
+    DictionaryRegistry.#roots.push(root);
+    Object.entries(transMap).forEach(([refName, trans]) => {
+      DictionaryRegistry.#modules.set(refName, {
+        kind: DictionaryRegistry.#resolveKind(trans),
+        languages: [...((trans.dict as { languages?: string[] }).languages ?? [])],
+      });
+    });
+  }
+
+  static getRoot(): RootDictionary {
+    const merged = {} as RootDictionary;
+    DictionaryRegistry.#roots.forEach((root) => {
+      Object.entries(root).forEach(([language, models]) => {
+        merged[language] = { ...(merged[language] ?? {}), ...models };
+      });
+    });
+    return merged;
+  }
+
+  static getLanguages(): string[] {
+    return [...new Set(DictionaryRegistry.#roots.flatMap((root) => Object.keys(root)))];
+  }
+
+  static getModules(): Record<string, DictionaryModuleInfo> {
+    return Object.fromEntries([...DictionaryRegistry.#modules.entries()].map(([key, info]) => [key, { ...info }]));
+  }
+
+  /** Flattened dotted paths of every leaf translation, e.g. `"user.signal.createUser.arg.data"`. */
+  static getKeys(root: RootDictionary = DictionaryRegistry.getRoot()): string[] {
+    const keys = new Set<string>();
+    Object.values(root).forEach((models) => {
+      Object.entries(models).forEach(([refName, node]) => {
+        DictionaryRegistry.#collectKeys(refName, node, keys);
+      });
+    });
+    return [...keys].sort();
+  }
+
+  /** Test-only reset; the registry is module-level global state. */
+  static clear() {
+    DictionaryRegistry.#roots.length = 0;
+    DictionaryRegistry.#modules.clear();
+  }
+
+  static #collectKeys(path: string, node: DictionaryNode, keys: Set<string>) {
+    if (typeof node.t === "string") keys.add(path);
+    Object.entries(node).forEach(([key, value]) => {
+      if (key === "t" || !DictionaryRegistry.#isNode(value)) return;
+      DictionaryRegistry.#collectKeys(`${path}.${key}`, value, keys);
+    });
+  }
+
+  static #isNode(value: unknown): value is DictionaryNode {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+  }
+
+  static #resolveKind(trans: DictModule<string, string>): DictionaryModuleKind {
+    if (trans.dict instanceof ModelDictInfo) return "model";
+    if (trans.dict instanceof ScalarDictInfo) return "scalar";
+    if (trans.dict instanceof ServiceDictInfo) return "service";
+    return "service";
+  }
+}

package/dictionary/index.ts

@@ -8,5 +8,6 @@ export {
   getDictionary,
   translate,
 } from "./dictionary";
+export * from "./dictionaryRegistry";
 export * from "./locale";
 export * from "./trans";

package/dictionary/trans.ts

@@ -1,6 +1,7 @@
 import type { GetStateObject, ObjectAssign, Prettify } from "akanjs/base";
 import { pathGet } from "akanjs/common";
 
+import { DictionaryRegistry } from "./dictionaryRegistry";
 import type { DictModule } from "./locale";
 
 type TranslationSingle = readonly [string, string] | readonly [string, string, string, string];
@@ -106,6 +107,7 @@ export const makeTrans = <
   Object.entries(transMap).forEach(([refName, trans]) => {
     trans.dict._registerToRoot(refName, rootDictionary);
   });
+  DictionaryRegistry.register(rootDictionary, transMap);
   class Err extends Error {
     readonly error: string;
     readonly statusCode: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "2.4.1-rc.3",
+  "version": "2.4.1-rc.5",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -170,6 +170,11 @@
       "types": "./types/server/memoryLimit.d.ts",
       "import": "./server/memoryLimit.ts",
       "default": "./server/memoryLimit.ts"
+    },
+    "./server/lifecycle/portInUse": {
+      "types": "./types/server/lifecycle/portInUse.d.ts",
+      "import": "./server/lifecycle/portInUse.ts",
+      "default": "./server/lifecycle/portInUse.ts"
     }
   },
   "dependencies": {

package/server/SSR_MEMORY_DIAGNOSIS.md

@@ -121,3 +121,34 @@ Both resolve through `MemoryLimit.resolveMaxRssBytes`, so `AKAN_MEMORY_LIMIT` or
 applies (the builder takes 35% of it, the RSC worker 55%). Look for `recycling builder pid=…` followed
 by `exiting for recycle` and `announced boot state after recycle`; the last line is what re-points a
 running backend at the replacement's artifact.
+
+**How much of that RSS is actually unreclaimable is platform-specific.** Measured on Bun 1.3.14: macOS
+returns none of the bundler arenas (0% after 60s idle) while Linux purges them after ~10-15s of quiet,
+46-59% of the builder's peak. Since the builder reports its RSS only when its queues drain, that sample
+is its *peak* — so before committing, the host waits 20s and re-reads the builder's RSS from the OS,
+and skips the recycle if the allocator gave the memory back by itself:
+
+```
+[builder-recycle] holding 20s to see whether the allocator returns it (rss=522MiB>=400MiB after 6 build(s))
+[builder-recycle] skipped: the builder fell to 214MiB (ceiling 400MiB) on its own, …
+```
+
+A builder more than 1.5× over the ceiling skips the wait, since no purge would rescue it. On macOS the
+re-read returns the same value, so the only cost there is the delay.
+
+## Dev Idle Suspend
+
+A dev server that nobody is editing still pays for a builder. After five minutes with no build
+activity and no route request, `AkanAppHost` releases the builder entirely and watches for edits with
+a plain `fs.watch` instead. The backend stays up, so the preview URL keeps serving; only build
+capacity goes away. The next edit — or the first request that needs a build — brings it back, paying
+one cold boot build (~3.5s on `apps/akan`, ~0.3s on a single-route app).
+
+```sh
+AKAN_DEV_IDLE_SUSPEND_MS=300000   # default; 0 keeps the builder resident for the whole session
+```
+
+Requests that arrive mid-wake are held and replayed against the new builder rather than answered with
+`builder is stopped`. A suspend is skipped while a build is red, while any restart or recovery is
+pending, or within 30s of a previous wake. Look for `[idle-suspend] … released the builder`, then
+`[idle-suspend] waking (…)` and `[idle-suspend] awake in …ms`.

package/server/akanServer.ts

@@ -14,6 +14,7 @@ import { createOpenApiDocument } from "../signal/openapi";
 import { FetchSerializer } from "../signal/serializer";
 import type { AkanLib, AkanLibProps } from "./akanLib";
 import type { BuilderRpc } from "./artifact";
+import { DevtoolsRouter } from "./devtools";
 import { DiLifecycle } from "./di/diLifecycle";
 import type { HmrWsData, HmrWsHub } from "./hmr/wsHub";
 import { isPortInUseError } from "./lifecycle/portInUse";
@@ -449,19 +450,32 @@ export class AkanServer {
   }
 
   #createBuiltinRoutes(): HttpRoutes {
-    if (!this.openapi) return {};
-    return {
-      "/openapi.json": {
-        GET: () =>
-          Response.json(
-            createOpenApiDocument(FetchSerializer.serializeRegistry(this.#di.live).signal, {
-              title: `${this.env.appName} API`,
-              version: "0.0.0",
-              servers: this.#getOpenApiServers(),
-            }),
-          ),
-      },
-    };
+    const openapiRoutes: HttpRoutes = this.openapi
+      ? {
+          "/openapi.json": {
+            GET: () =>
+              Response.json(
+                createOpenApiDocument(FetchSerializer.serializeRegistry(this.#di.live).signal, {
+                  title: `${this.env.appName} API`,
+                  version: "0.0.0",
+                  servers: this.#getOpenApiServers(),
+                }),
+              ),
+          },
+        }
+      : {};
+
+    const devtoolsRoutes = new DevtoolsRouter({
+      di: this.#di,
+      env: this.env,
+      name: this.name,
+      serverMode: this.serverMode,
+      prefix: this.prefix,
+      websocketPrefix: this.websocketPrefix,
+      openapi: this.openapi,
+      getStatus: () => this.status,
+    }).createRoutes();
+    return { ...openapiRoutes, ...devtoolsRoutes };
   }
 
   #getOpenApiServers() {

package/server/artifact/builderRpc.ts

@@ -96,10 +96,9 @@ export class BuilderRpc {
   ): Promise<BuildRouteClientResult> {
     if (this.#disposed) throw new Error("[builder] rpc is disposed");
     const id = this.#nextId++;
-    const payload = await new Promise<BuildRouteResultPayload>((resolve, reject) => {
-      this.#pending.set(id, { resolve: resolve as (v: unknown) => void, reject });
-      this.#send({ type: "build-route", id, routeId, seeds, knownEntries: [...knownEntries], generation });
-    });
+    const payload = await this.#request<BuildRouteResultPayload>(id, `build-route ${routeId}`, () =>
+      this.#send({ type: "build-route", id, routeId, seeds, knownEntries: [...knownEntries], generation }),
+    );
     return {
       manifestDelta: payload.manifestDelta,
       ssrManifestDelta: { moduleLoading: null, moduleMap: payload.ssrManifestDelta },
@@ -118,9 +117,54 @@ export class BuilderRpc {
   async buildCsr(reason: string): Promise<void> {
     if (this.#disposed) throw new Error("[builder] rpc is disposed");
     const id = this.#nextId++;
-    await new Promise<void>((resolve, reject) => {
-      this.#pending.set(id, { resolve: resolve as (v: unknown) => void, reject });
-      this.#send({ type: "build-csr", id, reason });
+    await this.#request<void>(id, `build-csr (${reason})`, () => this.#send({ type: "build-csr", id, reason }));
+  }
+
+  /**
+   * How long to wait for the builder before failing a request. `AKAN_BUILDER_RPC_TIMEOUT_MS` overrides.
+   *
+   * Generous, because a cold CSR build of every page legitimately takes tens of seconds; the point is not
+   * to be tight but to be finite.
+   */
+  static #timeoutMs(): number {
+    const configured = Number(process.env.AKAN_BUILDER_RPC_TIMEOUT_MS);
+    if (Number.isFinite(configured) && configured > 0) return configured;
+    return 120_000;
+  }
+
+  /**
+   * One builder request, which fails rather than waiting forever.
+   *
+   * Nothing answers a request whose builder exits after receiving it: the dev host replies `ok:false` only
+   * when the *send* fails, and it does not track in-flight ids. The builder exits routinely — it is recycled
+   * every few builds once its RSS passes the ceiling — so a page request that happens to be mid route-build
+   * left this promise pending forever, and the browser tab span with no error, no log and nothing to retry.
+   * Observed from the other side as a `fetch` that sat for 225s against a 60s budget.
+   */
+  async #request<T>(id: number, label: string, send: () => void): Promise<T> {
+    const timeoutMs = BuilderRpc.#timeoutMs();
+    return await new Promise<T>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.#pending.delete(id);
+        reject(
+          new Error(
+            `[builder] ${label} got no answer in ${timeoutMs}ms; the builder was likely recycled or restarted mid-request — reload to retry`,
+          ),
+        );
+      }, timeoutMs);
+      
+      timer.unref?.();
+      this.#pending.set(id, {
+        resolve: (value) => {
+          clearTimeout(timer);
+          resolve(value as T);
+        },
+        reject: (error) => {
+          clearTimeout(timer);
+          reject(error);
+        },
+      });
+      send();
     });
   }
 

package/server/artifact/ipcTypes.ts

@@ -98,10 +98,14 @@ export interface PagesBundlePayload {
 }
 
 /**
- * `Bun.build` retains native bundler arenas the process never returns — `Bun.gc(true)` reclaims
- * nothing and the JS heap stays flat while RSS climbs — so the builder's memory only comes back when
- * it exits. It reports its own RSS here whenever its queues drain, and the dev host recycles it past
- * a ceiling to turn unbounded growth into a bounded sawtooth.
+ * `Bun.build` retains native bundler arenas that `Bun.gc(true)` never reclaims — the JS heap stays flat
+ * while RSS climbs. **How much comes back without exiting is platform-specific**: measured on Bun
+ * 1.3.14, macOS returns none of it (0% after 60s idle) while Linux purges 46-59% after ~10-15s idle.
+ * The dev host recycles past a ceiling to bound the macOS case.
+ *
+ * Because this is only reported when the builder's queues drain, `rssBytes` is a *peak* sample. On
+ * Linux it goes stale within seconds, so the host re-reads the builder's RSS from the OS before acting
+ * on it. See `local/optimize-resource/09-linux-retention-measurement.md`.
  */
 export interface BuilderMetrics {
   rssBytes: number;
@@ -112,7 +116,8 @@ export interface BuilderMetrics {
 }
 
 export type BuilderEvent =
-  | { type: "builder-ready"; buildId: string }
+
+  | { type: "builder-ready"; buildId?: string }
   | { type: "backend-ready"; pid: number }
   | {
       type: "invalidate";