@akanjs/devkit 3.0.0-beta.25 → 3.0.0-beta.27

package/incrementalBuilder/incrementalBuilder.proc.ts

@@ -165,7 +165,7 @@ class IncrementalBuilder {
       this.#logger.verbose(`build-route ok routeId=${msg.routeId} newEntries=${delta.newEntries.length}`);
       //? The builder's generation, not the route cache's: the cache's does not move when a fixed file maps to no entry,
       //? so the rebuild's ok would carry the failure's own number.
-      this.#sendBuildStatus("route", { generation: this.#generation, ok: true, files: msg.seeds });
+      this.#sendBuildStatus("route", { generation: this.#generation, ok: true, files: msg.seeds, scope: msg.routeId });
       return {
         type: "build-route-res",
         id: msg.id,
@@ -185,24 +185,30 @@ class IncrementalBuilder {
     } catch (err) {
       const errMsg = ApplicationBuildReporter.formatError(err, this.#app.workspace.workspaceRoot);
       this.#logger.error(`build-route failed routeId=${msg.routeId}: ${errMsg}`);
-      this.#sendBuildStatus("route", { generation: this.#generation, ok: false, files: msg.seeds, message: errMsg });
+      this.#sendBuildStatus("route", {
+        generation: this.#generation,
+        ok: false,
+        files: msg.seeds,
+        message: errMsg,
+        scope: msg.routeId,
+      });
       return { type: "build-route-res", id: msg.id, ok: false, error: errMsg };
     }
   }
   #sendBuildStatus(
     phase: BuildPhase,
-    { generation, ok, files, message }: { generation?: number; ok: boolean; files?: string[]; message?: string },
+    {
+      generation,
+      ok,
+      files,
+      message,
+      scope,
+    }: { generation?: number; ok: boolean; files?: string[]; message?: string; scope?: string },
   ): void {
     if (typeof generation !== "number") return;
     BuilderChannel.emit({
       type: "build-status",
-      data: {
-        generation,
-        phase,
-        ok,
-        files: files ?? [],
-        message,
-      },
+      data: { generation, phase, ok, files: files ?? [], message, ...(scope !== undefined ? { scope } : {}) },
     });
   }
   async #enqueueFast<T>(label: string, fn: () => Promise<T>): Promise<T> {
@@ -445,11 +451,8 @@ class IncrementalBuilder {
       if (ssrToWorker) needs.unshift("ssr");
       const batch: BatchJob = { generation, needs, changedFiles: files, trace, ...(discovery ? { discovery } : {}) };
       // A worker's registry build rewrites the directory its patcher reads, so the next save waits for it.
-      if (needs.includes("csr") || needs.includes("ssr")) {
-        await this.#workQueue.enqueueBatch(batch);
-        if (needs.includes("csr")) this.#patcher?.forget();
-        if (needs.includes("ssr")) this.#ssrPatcher?.forget();
-      } else void this.#workQueue.enqueueBatch(batch).catch(this.#slowLaneFailed("batch"));
+      if (needs.includes("csr") || needs.includes("ssr")) await this.#workQueue.enqueueBatch(batch);
+      else void this.#workQueue.enqueueBatch(batch).catch(this.#slowLaneFailed("batch"));
       return;
     }
     if (discovery)
@@ -525,6 +528,9 @@ class IncrementalBuilder {
     const hold = await ServerGraphFile.touches(await ServerGraphFile.read(this.#artifactDir), files, (file) =>
       ServerGraphFile.clientExportsOf(file),
     );
+    //? Ahead of this save's own discovery job in the slow lane: which client entries a page still names decides which
+    //? pending roots this patch keeps.
+    this.#discovery.invalidate?.(files);
     return await this.#withSsrLock(
       async () => await this.#runSsrPatcher(patcher, files, { trace, hold, batchGeneration: generation }),
     );
@@ -532,14 +538,16 @@ class IncrementalBuilder {
 
   //* Adds the entries a route build names to the registry, since the tab requires them by id. A registry that cannot
   //* take them fails no route build: the page answers, and its tab waits for the registry while the overlay says why.
-  async #ensureSsrEntries(entries: string[]): Promise<void> {
+  async #ensureSsrEntries(entries: string[], { crashRetry = false }: { crashRetry?: boolean } = {}): Promise<void> {
     if (entries.length === 0) return;
     //? The boot build takes every entry the routes reach, so the first page answers now and its tab waits for the
     //? registry (boot.json) instead; whatever that build missed is added right after it lands.
     const arming = this.#ssrArming;
     if (arming) {
       void this.#runBeside(
-        arming.then(async () => await this.#ensureSsrEntries(entries)).catch(this.#slowLaneFailed("ssr-ensure")),
+        arming
+          .then(async () => await this.#ensureSsrEntries(entries, { crashRetry }))
+          .catch(this.#slowLaneFailed("ssr-ensure")),
       );
       return;
     }
@@ -558,6 +566,8 @@ class IncrementalBuilder {
       //? the SSR lock that save's patch waits on.
       if (this.#ssrBroken) return;
       if (this.#ssrCrashedAt !== null && Date.now() - this.#ssrCrashedAt < IncrementalBuilder.#crashRetryMs) {
+        //? Handed over just now with nothing run for them: the retry must find them to hand over again.
+        patcher?.releaseHandedOver();
         this.#retryAfterCrash(this.#ssrCrashedAt, entries);
         return;
       }
@@ -566,6 +576,9 @@ class IncrementalBuilder {
           `ssr-registry could not take a route's entries; the save that fixes it rebuilds it: ${ApplicationBuildReporter.formatError(err, this.#app.workspace.workspaceRoot)}`,
         );
       });
+      //? A worker that died took these entries with it and left them pending nowhere: they are tried once more after the
+      //? crash window, but a retry that crashes again waits for the next route build or save.
+      if (this.#ssrCrashedAt !== null && !crashRetry) this.#retryAfterCrash(this.#ssrCrashedAt, entries);
     });
   }
 
@@ -580,7 +593,9 @@ class IncrementalBuilder {
         const retried = [...this.#crashRetryEntries];
         this.#crashRetryEntries.clear();
         if (this.shuttingDown || retried.length === 0) return;
-        void this.#runBeside(this.#ensureSsrEntries(retried)).catch(this.#slowLaneFailed("ssr-crash-retry"));
+        void this.#runBeside(this.#ensureSsrEntries(retried, { crashRetry: true })).catch(
+          this.#slowLaneFailed("ssr-crash-retry"),
+        );
       },
       Math.max(0, crashedAt + IncrementalBuilder.#crashRetryMs - Date.now()),
     );
@@ -654,8 +669,12 @@ class IncrementalBuilder {
 
   // Runs the worker directly, under the SSR lock its callers hold: queueing it could wait on a batch that waits on them.
   async #runSsrWorker(generation: number): Promise<void> {
-    const result = await this.#runBatch({ generation, needs: ["ssr"], changedFiles: [] });
-    this.#ssrPatcher?.forget();
+    let result: BuildBatchResult;
+    try {
+      result = await this.#runBatch({ generation, needs: ["ssr"], changedFiles: [] });
+    } finally {
+      this.#ssrPatcher?.forget();
+    }
     this.#noteSsrWorker(result);
     if (result.errors.ssr) throw new Error(result.errors.ssr);
   }
@@ -741,9 +760,20 @@ class IncrementalBuilder {
     //? The slow lane runs in order, so every batch up to this one has had its discovery job.
     this.#discoveredThrough = Math.max(this.#discoveredThrough, work.generation);
     // A worker writing ssr-dev must not overlap the boot build, which no longer runs in this lane.
-    if (work.needs.includes("ssr"))
-      await this.#withSsrLock(async () => this.#noteSsrWorker(await this.#runBatch(work)));
-    else await this.#runBatch(work);
+    //? Forgotten inside the lock: a route build's check waiting on it would patch the old state over the worker's.
+    try {
+      if (work.needs.includes("ssr"))
+        await this.#withSsrLock(async () => {
+          try {
+            this.#noteSsrWorker(await this.#runBatch(work));
+          } finally {
+            this.#ssrPatcher?.forget();
+          }
+        });
+      else await this.#runBatch(work);
+    } finally {
+      if (work.needs.includes("csr")) this.#patcher?.forget();
+    }
   }
 
   async #refreshDiscovery({ files, refresh, generation }: DiscoveryJob): Promise<void> {
@@ -762,8 +792,12 @@ class IncrementalBuilder {
     if (result.cssAssets) this.#artifact = { ...this.#artifact, cssAssets: result.cssAssets };
     // A need the worker died before reporting goes red here instead of looking silently successful.
     if (result.crashed) {
+      const crashedNeeds = result.crashedNeeds ?? needs;
+      //? A worker that died wrote no failure for the roots handed to it: they must not wait on one that never comes.
+      if (crashedNeeds.includes("csr")) this.#patcher?.releaseHandedOver();
+      if (crashedNeeds.includes("ssr")) this.#ssrPatcher?.releaseHandedOver();
       // `base` is not a `BuildPhase` and never comes through here: `#buildBootDeps` throws into the degraded boot.
-      for (const need of result.crashedNeeds ?? needs)
+      for (const need of crashedNeeds)
         if (need !== "base")
           this.#sendBuildStatus(need, {
             generation,

package/integration/devStability.integration.test.ts

@@ -589,6 +589,7 @@ describe("dev resource budgets", () => {
     // A ceiling the replacement is back over within the interval is reported, and still enforced (recycles are
     // throttled), never disabled for the session. Whether it is back over depends on the machine's allocator, so the
     // warning is asserted only when it is; the decision itself is unit-tested (devHostPolicy).
+    const settledFrom = host.markLog();
     for (let i = 1; i <= 3; i++) {
       const { mark } = await harness.editUntilSeen(host, (attempt) =>
         harness.replaceText("ui/ClientMarker.tsx", /marker(-[\w-]+)?/, `marker-settled-${i}-${attempt}`),
@@ -596,8 +597,14 @@ describe("dev resource budgets", () => {
       await host.waitForLogSince(mark, /pages-rebundle ok/, WAIT_MS).catch(() => undefined);
     }
     const settled = await DevStabilityHarness.builderProcess(host.proc.pid);
-    if ((settled?.rssBytes ?? 0) >= 200 * MB)
-      await host.waitForLogSince(start, /ceiling costs about one boot build per interval/, WAIT_MS);
+    const warned = /ceiling costs about one boot build per interval/.test(host.logs.join("").slice(start));
+    //? Past the interval (a slow machine) the next report recycles instead of warning: either answer settles it.
+    if ((settled?.rssBytes ?? 0) >= 200 * MB && !warned)
+      await host.waitForLogSince(
+        settledFrom,
+        /ceiling costs about one boot build per interval|recycling builder pid=\d+|skipped: the builder fell to/,
+        WAIT_MS,
+      );
     expect(host.logs.join("").slice(start)).not.toMatch(/no longer enforcing it this session/);
   });
 

package/mobile/nativeApp.test.ts

@@ -38,6 +38,21 @@ describe("NativeApp", () => {
     expect(admin.outDir("android")).toBe(path.join(appDir, ".akan/mobile/admin/native/android"));
   });
 
+  test("a dev boot that came up says so in one line: platform, device, dev server, time", () => {
+    const app = { ...fakeApp(), name: "portal" } as unknown as App;
+    const startedAt = performance.now() - 12_400;
+    expect(new NativeApp(app, target()).readyLine("macos", { upstream: "http://localhost:8283", startedAt })).toMatch(
+      /^portal desktop ready · http:\/\/localhost:8283 · 12\.\ds$/,
+    );
+    expect(
+      new NativeApp(app, target({ name: "admin" })).readyLine("ios", {
+        upstream: "http://localhost:8283",
+        device: { name: "iPhone 16" },
+        startedAt,
+      }),
+    ).toMatch(/^portal\/admin ios ready · iPhone 16 · http:\/\/localhost:8283 · 12\.\ds$/);
+  });
+
   test("opens a dev build on its target's home, the CSR shell under the locale", () => {
     expect(new NativeApp(fakeApp(), target({ indexPath: "/explore" })).startPath("en")).toBe(
       "/en/explore?csr=true&akanMobileTarget=default&akanMobileIndexPath=%2Fexplore",

package/mobile/nativeApp.ts

@@ -2,6 +2,7 @@ import { mkdir } from "node:fs/promises";
 import path from "node:path";
 import type { AkanNativeConfig } from "@akanjs/native/config";
 import type { App } from "../commandDecorators";
+import { Executor } from "../executors";
 import {
   type DesktopPlatform,
   type MobilePlatform,
@@ -10,6 +11,7 @@ import {
   targetHtmlFilename,
 } from "./mobileTarget";
 import { NativeApi, type NativeBuildApiModule } from "./nativeApi";
+import { NativeAppLine, type NativeAppLineRead } from "./nativeAppLine";
 import { NativeConfig } from "./nativeConfig";
 import { NativeWebDir } from "./nativeWebDir";
 
@@ -24,6 +26,11 @@ export interface NativeRunOptions {
   teamId?: string;
 }
 
+interface NativeDevBoot {
+  steps: string[];
+  lines: NativeAppLineRead[];
+}
+
 export interface NativeDevOptions extends NativeRunOptions {
   /** The akan dev server the gateway proxies. */
   upstream: string;
@@ -35,6 +42,8 @@ export interface NativeDevOptions extends NativeRunOptions {
 export class NativeApp {
   readonly targetRoot: string;
   readonly web: NativeWebDir;
+  //? A dev boot holds its steps and the app's first lines back: one line says it is up, all of it when it failed.
+  #boot: NativeDevBoot | null = null;
 
   constructor(
     readonly app: App,
@@ -83,7 +92,9 @@ export class NativeApp {
 
   //? The app's own output: its console (mirrored by a dev build), the simulator log stream or logcat.
   #appLine = (line: string) => {
-    this.app.logger.info(`[${this.target.name}] ${line}`);
+    const read = NativeAppLine.read(line, { verbose: Executor.verbose });
+    if (this.#boot) this.#boot.lines.push(read);
+    else this.app.logger[read.level](read.message);
   };
 
   //* `AKAN_PUBLIC_*` is already inlined into the CSR bundle, so the runtime reads no .env file of its own.
@@ -98,6 +109,7 @@ export class NativeApp {
       log: (event) => {
         if (event.level === "error") this.app.logger.error(event.message);
         else if (event.level === "warn") this.app.logger.warn(event.message);
+        else if (this.#boot) this.#boot.steps.push(event.message);
         else if (event.level === "tool") this.app.logger.verbose(event.message);
         else this.app.logger.info(event.message);
       },
@@ -128,19 +140,47 @@ export class NativeApp {
   //* The gateway serves the page and its HMR socket on the app origin; API calls go to the dev server itself (baseEnv),
   //* which an Android device reaches through the reversed port.
   async dev(platform: NativePlatform, { upstream, lang, device, teamId }: NativeDevOptions) {
-    await mkdir(this.web.dir, { recursive: true });
-    const [{ api, config }, { api: routes }] = await Promise.all([this.prepare(), this.app.getConfig()]);
-    return await api.dev({
-      ...this.#task(platform, config),
-      upstream,
-      hmrPath: "/_akan/hmr",
-      //? A dev page calls its own origin (akanjs baseEnv), so the gateway relays the socket it opens for the API too.
-      wsPaths: [`${routes.prefix}${routes.websocketPrefix}`],
-      onLine: this.#appLine,
-      startPath: this.startPath(lang),
-      ...(device ? { device } : {}),
-      ...(teamId ? { ios: { signing: { teamId } } } : {}),
-    });
+    const startedAt = performance.now();
+    const boot: NativeDevBoot = { steps: [], lines: [] };
+    this.#boot = boot;
+    try {
+      await mkdir(this.web.dir, { recursive: true });
+      const [{ api, config }, { api: routes }] = await Promise.all([this.prepare(), this.app.getConfig()]);
+      const session = await api.dev({
+        ...this.#task(platform, config),
+        upstream,
+        hmrPath: "/_akan/hmr",
+        //? A dev page calls its own origin (akanjs baseEnv), so the gateway relays the socket it opens for the API too.
+        wsPaths: [`${routes.prefix}${routes.websocketPrefix}`],
+        onLine: this.#appLine,
+        startPath: this.startPath(lang),
+        ...(device ? { device } : {}),
+        ...(teamId ? { ios: { signing: { teamId } } } : {}),
+      });
+      this.#boot = null;
+      this.app.logger.info(this.readyLine(platform, { upstream, device: session.device, startedAt }));
+      for (const step of [...boot.steps, `pages through ${session.gateway}`]) this.app.logger.debug(step);
+      for (const line of boot.lines) this.app.logger[line.level](line.message);
+      return session;
+    } catch (error) {
+      this.#boot = null;
+      for (const step of boot.steps) this.app.logger.info(step);
+      for (const line of boot.lines) this.app.logger[line.level === "debug" ? "info" : line.level](line.message);
+      throw error;
+    }
+  }
+
+  /** What a dev boot that came up says, and all it says: `cmdc ios ready · iPhone 16 · http://localhost:8283 · 12.4s`. */
+  readyLine(
+    platform: NativePlatform,
+    { upstream, device, startedAt }: { upstream: string; device?: { name: string }; startedAt: number },
+  ) {
+    const label = platform === "ios" || platform === "android" ? platform : "desktop";
+    const target = this.target.name === "default" ? "" : `/${this.target.name}`;
+    const seconds = ((performance.now() - startedAt) / 1000).toFixed(1);
+    return [`${this.app.name}${target} ${label} ready`, ...(device ? [device.name] : []), upstream, `${seconds}s`].join(
+      " · ",
+    );
   }
 
   async releaseIos({ teamId, adHoc = false }: { teamId?: string; adHoc?: boolean } = {}) {

package/mobile/nativeAppLine.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test } from "bun:test";
+import { NativeAppLine } from "./nativeAppLine";
+
+describe("NativeAppLine", () => {
+  test("a page logger line keeps its level and its logger's name", () => {
+    expect(NativeAppLine.read("[page warn] [WsClient] WebSocket message process failed")).toEqual({
+      level: "warn",
+      message: "[page:WsClient] WebSocket message process failed",
+    });
+  });
+
+  test("a bare console call keeps its level, `log` reading as info", () => {
+    expect(NativeAppLine.read("[page log] hello")).toEqual({ level: "info", message: "[page] hello" });
+    expect(NativeAppLine.read("[page debug] [akan:frame:x:1] csr.render {}")).toEqual({
+      level: "debug",
+      message: "[page:akan:frame:x:1] csr.render {}",
+    });
+  });
+
+  test("a continuation line follows its message's level without a prefix of its own", () => {
+    expect(NativeAppLine.read("[page+ error]     at run (app.js:1:2)")).toEqual({
+      level: "error",
+      message: "      at run (app.js:1:2)",
+    });
+  });
+
+  test("a second window is named, the first is not", () => {
+    expect(NativeAppLine.read("[page#2 info] [App] ready")).toEqual({ level: "info", message: "[page#2:App] ready" });
+  });
+
+  test("logcat lines read by tag and priority", () => {
+    expect(NativeAppLine.read("W/AkanNativeConsole( 1234): [WsClient] failed")).toEqual({
+      level: "warn",
+      message: "[page:WsClient] failed",
+    });
+    expect(NativeAppLine.read("E/AndroidRuntime( 1234): FATAL EXCEPTION: main")).toEqual({
+      level: "error",
+      message: "[AndroidRuntime] FATAL EXCEPTION: main",
+    });
+    expect(
+      NativeAppLine.read("I/AkanNative( 1234): pages from http://10.0.2.2:5000 (akan-native dev --hmr)").level,
+    ).toBe("debug");
+  });
+
+  test("the host's own lines stay visible but for where its pages come from", () => {
+    expect(NativeAppLine.read("[akan-native] opened in the browser: https://x.test")).toEqual({
+      level: "info",
+      message: "[akan-native] opened in the browser: https://x.test",
+    });
+    expect(
+      NativeAppLine.read("[akan-native native] pages from http://127.0.0.1:6000 (akan-native dev --hmr)").level,
+    ).toBe("debug");
+  });
+
+  test("a line no page or host wrote is kept for debug, or for info when verbose", () => {
+    expect(NativeAppLine.read("WebContent[123] Could not signal service")).toEqual({
+      level: "debug",
+      message: "WebContent[123] Could not signal service",
+    });
+    expect(NativeAppLine.read("WebContent[123] Could not signal service", { verbose: true }).level).toBe("info");
+  });
+});

package/mobile/nativeAppLine.ts

@@ -0,0 +1,63 @@
+import type { LogLevel } from "akanjs/common";
+
+export interface NativeAppLineRead {
+  level: LogLevel;
+  message: string;
+}
+
+//* A line a native dev build prints — the page console its host mirrors, the simulator's console, logcat — read back
+//* at the level the page logged it, so the terminal shows it once, stamped by the app's own logger.
+export class NativeAppLine {
+  //? The host's grammar (desktop host.ts, iOS AkanNativeShell.swift): `[page<+><#window> <level>] text`, where `+`
+  //? marks a continuation line of a multi-line message and `#n` any window but the first.
+  static readonly #page = /^\[page(\+)?(?:#(\d+))? (trace|verbose|debug|log|info|warn|error)\] ?(.*)$/;
+  static readonly #logcat = /^([VDIWEFA])\/([^(]+?)\s*\(\s*\d+\):\s?(.*)$/;
+  static readonly #named = /^\[([^\]\s]+)\] ([\s\S]*)$/;
+  static readonly #logcatLevels: { [priority: string]: LogLevel } = {
+    V: "verbose",
+    D: "debug",
+    I: "info",
+    W: "warn",
+    E: "error",
+    F: "error",
+    A: "error",
+  };
+
+  /** `verbose` keeps the lines no page or host wrote (WebKit, the simulator) at info instead of debug. */
+  static read(line: string, { verbose = false }: { verbose?: boolean } = {}): NativeAppLineRead {
+    const logcat = NativeAppLine.#logcat.exec(line);
+    if (logcat) {
+      const [, priority = "I", tag = "", text = ""] = logcat;
+      const level = NativeAppLine.#logcatLevels[priority] ?? "info";
+      if (tag === "AkanNativeConsole") return NativeAppLine.#pageLine(level, text, { continuation: false });
+      if (tag === "AkanNative") return NativeAppLine.#hostLine(`[akan-native] ${text}`, level);
+      return { level, message: `[${tag}] ${text}` };
+    }
+    const page = NativeAppLine.#page.exec(line);
+    if (page) {
+      const [, continuation, window, level = "info", text = ""] = page;
+      return NativeAppLine.#pageLine(level === "log" ? "info" : (level as LogLevel), text, {
+        continuation: continuation === "+",
+        window,
+      });
+    }
+    if (line.startsWith("[akan-native")) return NativeAppLine.#hostLine(line, "info");
+    return { level: verbose ? "info" : "debug", message: line };
+  }
+
+  static #pageLine(
+    level: LogLevel,
+    text: string,
+    { continuation, window }: { continuation: boolean; window?: string },
+  ): NativeAppLineRead {
+    if (continuation) return { level, message: `  ${text}` };
+    const named = NativeAppLine.#named.exec(text);
+    const scope = `page${window ? `#${window}` : ""}${named ? `:${named[1]}` : ""}`;
+    return { level, message: `[${scope}] ${named ? named[2] : text}` };
+  }
+
+  //? The host's own lines are about the host, not the app: where its pages come from is boot detail.
+  static #hostLine(line: string, level: LogLevel): NativeAppLineRead {
+    return { level: /\bpages from\b/.test(line) ? "debug" : level, message: line };
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.0.0-beta.25",
+  "version": "3.0.0-beta.27",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -47,7 +47,7 @@
     "@earendil-works/pi-tui": "0.86.1",
     "@inquirer/prompts": "^8.4.3",
     "@tailwindcss/node": "^4.3.0",
-    "akanjs": "3.0.0-beta.25",
+    "akanjs": "3.0.0-beta.27",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",