@akanjs/devkit 3.0.0-beta.24 → 3.0.0-beta.26

package/akanApp/devHostPolicy.ts

@@ -61,12 +61,20 @@ export type BackendLifecycleState = "starting" | "ready" | "restart-pending" | "
 /** Reported, not scraped: in interleaved child output "this app is up" reads like any line mentioning it. */
 export type DevHostState = "starting" | "ready" | "restarting" | "recovering" | "suspended" | "failed" | "stopped";
 
-export interface DevHostEvent {
+export interface DevHostStateEvent {
   app: string;
   state: DevHostState;
   detail?: string;
 }
 
+/** Sent once: the app serves and its boot builds have settled, which is what the next boot wave waits for. */
+export interface DevHostBootEvent {
+  app: string;
+  booted: true;
+}
+
+export type DevHostEvent = DevHostStateEvent | DevHostBootEvent;
+
 const devHostStateByBackendState = {
   starting: "starting",
   ready: "ready",
@@ -112,14 +120,29 @@ export const isLegacyBackendFallbackFile = (file: string, workspaceRoot: string)
   );
 };
 
+//? The backend's rule (akanjs `DevBuildRecovery`), copied: no exported akanjs subpath reaches it from the CLI bundle.
 export const shouldMarkBuildPhaseRecovered = (
   previousByPhase: ReadonlyMap<BuildPhase, DevBuildStatus>,
   status: DevBuildStatus,
 ): boolean => {
   const previous = previousByPhase.get(status.phase);
-  return Boolean(previous && status.ok && !previous.ok && generationValue(status.generation) >= previous.generation);
+  if (!previous || previous.ok || !status.ok) return false;
+  const generation = generationValue(status.generation);
+  if (status.phase === "route" && status.scope !== undefined && previous.scope !== undefined)
+    return status.scope === previous.scope && generation >= previous.generation;
+  if (generation !== previous.generation) return generation > previous.generation;
+  return status.phase === "backend";
 };
 
+/** An ok that recovers nothing leaves the failure standing, for hello and for whatever waits on a clean build. */
+export const shouldKeepBuildFailure = (
+  previousByPhase: ReadonlyMap<BuildPhase, DevBuildStatus>,
+  status: DevBuildStatus,
+): boolean =>
+  status.ok &&
+  previousByPhase.get(status.phase)?.ok === false &&
+  !shouldMarkBuildPhaseRecovered(previousByPhase, status);
+
 export const createBackendBuildStatus = ({
   generation,
   ok,
@@ -180,7 +203,8 @@ export const hasBuildFailureForGeneration = (
 ): boolean => {
   if (typeof generation !== "number") return false;
   for (const status of statusByPhase.values()) {
-    if (!status.ok && status.generation === generation) return true;
+    //? Not a route's: a replacement builder or a restarted dev host boots without building one, so it cannot hit it.
+    if (!status.ok && status.phase !== "route" && status.generation === generation) return true;
   }
   return false;
 };
@@ -268,8 +292,9 @@ export const resolveIdleSuspendMs = (raw: string | undefined): number | null =>
   return Math.round(parsed);
 };
 
+//? Not a route's: a broken route builds again on its next request, which wakes a suspended builder anyway.
 export const hasAnyBuildFailure = (statusByPhase: ReadonlyMap<BuildPhase, DevBuildStatus>): boolean =>
-  [...statusByPhase.values()].some((status) => !status.ok);
+  [...statusByPhase.values()].some((status) => !status.ok && status.phase !== "route");
 
 export const shouldRefreshConfigOnIdleWake = (batch: ChangeBatch | null): boolean =>
   !!batch && batch.kinds.has("config");

package/cloud/globalConfig.ts

@@ -1,4 +1,4 @@
-import { mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { mkdir, rm, writeFile } from "node:fs/promises";
 import dayjs from "dayjs";
 import { FileSys } from "../fileSys";
 import { ConfigLock } from "./configLock";
@@ -39,27 +39,13 @@ export class GlobalConfig {
     const temp = `${configPath}.${process.pid}.${crypto.randomUUID()}.tmp`;
     try {
       await writeFile(temp, JSON.stringify(akanConfig, null, 2), { mode: 0o600 });
-      await GlobalConfig.#replace(temp, configPath);
+      // Every CLI reads this file outside the lock, which on Windows makes the rename wait for the reader.
+      await FileSys.replace(temp, configPath);
     } catch (error) {
       await rm(temp, { force: true });
       throw error;
     }
   }
-  static readonly #replaceAttempts = 100;
-  // Windows refuses to rename over a file another process has open (EPERM, or EACCES/EBUSY), and every CLI reads this
-  // one outside the lock. A reader holds it for one read, so the rename is retried for a few seconds instead of failing.
-  static async #replace(temp: string, target: string) {
-    for (let attempt = 1; ; attempt++) {
-      try {
-        return await rename(temp, target);
-      } catch (error) {
-        const code = (error as NodeJS.ErrnoException).code;
-        const busy = process.platform === "win32" && (code === "EPERM" || code === "EACCES" || code === "EBUSY");
-        if (!busy || attempt >= GlobalConfig.#replaceAttempts) throw error;
-        await Bun.sleep(Math.min(10 * attempt, 50));
-      }
-    }
-  }
   static readonly #lockPath = `${configPath}.lock`;
   // Every write re-reads under the lock: one built on an earlier read could restore a rotated-away refresh token.
   static async #update(mutate: (akanConfig: AkanGlobalConfig) => AkanGlobalConfig) {

package/csrE2e/csrE2eHarness.fixture.ts

@@ -46,7 +46,7 @@ const RELOAD_MARKER = "__akanE2eBootMarker";
 //? Longer than the frame's navigation lock (360ms after a transition commits, `webkit/useCsrValues.ts`).
 const SETTLE_MS = 450;
 
-/** Drives a CSR page (`?csr=true` + a mobile target) of a running `akan start` in a headless `Bun.WebView`. */
+/** Drives a page of a running `akan start` in a headless `Bun.WebView`: CSR (`?csr=true` + a mobile target) or SSR. */
 export class CsrE2eHarness {
   readonly origin: string;
   readonly #view: Bun.WebView;
@@ -55,6 +55,7 @@ export class CsrE2eHarness {
   readonly #mobileTarget: string;
   readonly #edited = new Map<string, string>();
   #marker = "";
+  #csr: boolean = true;
 
   private constructor(options: {
     origin: string;
@@ -78,6 +79,11 @@ export class CsrE2eHarness {
   static async start(options: CsrE2eOptions): Promise<CsrE2eHarness> {
     const workspaceRoot = options.workspaceRoot ?? CsrE2eHarness.#findWorkspaceRoot();
     const url = options.url ?? process.env.AKAN_CSR_E2E_URL;
+    //? A running server took its env when it started: a suite's hooks would be dropped and its checks pass for nothing.
+    if (url && Object.keys(options.env ?? {}).length > 0)
+      throw new Error(
+        `[csr-e2e] this suite starts its dev server with ${Object.keys(options.env ?? {}).join(", ")}, which the server at ${url} does not have; unset AKAN_CSR_E2E_URL`,
+      );
     const port = options.port ?? Number(process.env.AKAN_CSR_E2E_PORT ?? DEFAULT_PORT);
     const server = url ? null : await CsrE2eHarness.#startServer({ ...options, workspaceRoot, port });
     const origin = new URL(url ?? `http://localhost:${port}`).origin;
@@ -90,6 +96,8 @@ export class CsrE2eHarness {
         width,
         height,
         backend: backend === "chrome" ? { type: "chrome", url: false } : backend,
+        //? AKAN_CSR_E2E_CONSOLE=1 prints the page's console: the only view of a hydration warning or a failed patch.
+        ...(process.env.AKAN_CSR_E2E_CONSOLE === "1" ? { console: globalThis.console } : {}),
       });
       return new CsrE2eHarness({
         origin,
@@ -104,28 +112,43 @@ export class CsrE2eHarness {
     }
   }
 
-  /** Loads `path` (without the locale) as a CSR page and plants the marker `reloaded()` checks. */
-  async open(path: string) {
+  /** Loads `path` (without the locale), as CSR unless `csr: false`, and plants the marker `reloaded()` checks. */
+  async open(path: string, { csr = true }: { csr?: boolean } = {}) {
     const url = new URL(`/${this.#lang}${path === "/" ? "" : path}`, this.origin);
-    url.searchParams.set("csr", "true");
-    url.searchParams.set("akanMobileTarget", this.#mobileTarget);
+    if (csr) {
+      url.searchParams.set("csr", "true");
+      url.searchParams.set("akanMobileTarget", this.#mobileTarget);
+    }
+    this.#csr = csr;
     await this.#view.navigate(url.toString());
     await this.#markBoot();
   }
 
-  /** Reloads the page where it is, as a WebView does after its content process died, and marks the new boot. */
-  async reload() {
+  /**
+   * Reloads the page where it is, as a WebView does after its content process died, and marks the new boot. Returns
+   * the `performance.timeOrigin` of the first document seen after it: one that differs later was reloaded again.
+   */
+  async reload(): Promise<number> {
     await this.#view.reload();
     //? On the WebKit backend `reload()` resolves before the old document is gone; its marker going is the reload.
     await this.waitFor(
       (key: string, previous: string) => (window as unknown as Record<string, string | undefined>)[key] !== previous,
       { args: [RELOAD_MARKER, this.#marker], timeout: 30_000 },
     );
+    const timeOrigin = await this.evaluate(() => performance.timeOrigin);
     await this.#markBoot();
+    return timeOrigin;
   }
 
+  //? An SSR page has no page stack; `rscClient` installs its refresh hook in the root's layout effect, once hydrated.
   async #markBoot() {
-    await this.waitFor(() => document.querySelector('[id^="pageContainer-"]') !== null, { timeout: 30_000 });
+    if (this.#csr)
+      await this.waitFor(() => document.querySelector('[id^="pageContainer-"]') !== null, { timeout: 30_000 });
+    else
+      await this.waitFor(
+        () => typeof (globalThis as unknown as { __AKAN_RSC_REFRESH__?: unknown }).__AKAN_RSC_REFRESH__ === "function",
+        { timeout: 30_000 },
+      );
     await Bun.sleep(SETTLE_MS);
     this.#marker = Math.random().toString(36).slice(2);
     await this.evaluate(
@@ -296,6 +319,33 @@ export class CsrE2eHarness {
     await this.#view.type(text);
   }
 
+  /** The process group of the `akan start` this harness spawned; null when it drives a running one. */
+  get serverGroup(): number | null {
+    return this.#server?.proc.pid ?? null;
+  }
+
+  /** Where the spawned `akan start`'s stdout and stderr end now, for `serverLogSince`. */
+  async serverLogMark(): Promise<{ out: number; err: number }> {
+    const [out, err] = await this.#serverLogs();
+    return { out: out.length, err: err.length };
+  }
+
+  /** What the spawned `akan start` wrote to stdout and stderr since `mark`; empty when it drives a running one. */
+  async serverLogSince(mark: { out: number; err: number } = { out: 0, err: 0 }): Promise<string> {
+    const [out, err] = await this.#serverLogs();
+    return `${out.slice(mark.out)}${err.slice(mark.err)}`;
+  }
+
+  async #serverLogs(): Promise<[string, string]> {
+    if (!this.#server) return ["", ""];
+    const read = async (file: string) =>
+      await Bun.file(file)
+        .text()
+        .catch(() => "");
+    const { logPath } = this.#server;
+    return [await read(logPath), await read(logPath.replace(/\.log$/, ".err.log"))];
+  }
+
   /** Whether the page reloaded since `open()`: the boot marker lives only in the page `open()` loaded. */
   async reloaded() {
     const marker = await this.evaluate(
@@ -350,18 +400,23 @@ export class CsrE2eHarness {
     env = {},
     workspaceRoot,
   }: CsrE2eOptions & { port: number; workspaceRoot: string }): Promise<CsrE2eServer> {
+    //? The dev host runs from the CLI's dist bundle while the builder runs from source: a stale dist tests an old host.
+    //? The build is a no-op when its stamp matches the sources.
+    const built = Bun.spawnSync(["bun", path.join(workspaceRoot, "pkgs/@akanjs/cli/build.ts")], { cwd: workspaceRoot });
+    if (built.exitCode !== 0) throw new Error(`[csr-e2e] building the CLI failed: ${built.stderr.toString()}`);
     const cli = path.join(workspaceRoot, "dist/pkgs/@akanjs/cli/index.js");
-    if (!(await Bun.file(cli).exists()))
-      throw new Error(`[csr-e2e] ${cli} is missing; build the CLI first (bun pkgs/@akanjs/cli/build.ts)`);
     const logDir = path.join(workspaceRoot, "local", "csr-e2e");
     await mkdir(logDir, { recursive: true });
     const logPath = path.join(logDir, `${app}-${port}.log`);
+    const errPath = logPath.replace(/\.log$/, ".err.log");
+    //? A `Bun.file` sink writes from offset 0 without truncating, so the last run's tail would outlive this one's start.
+    await Promise.all([Bun.write(logPath, ""), Bun.write(errPath, "")]);
     //? Its own process group, so stopping it reaches the gateway, the builder and every replica it spawned.
     const proc = Bun.spawn(["bun", cli, "start", app, "--plain"], {
       cwd: workspaceRoot,
       env: { ...process.env, AKAN_DEV_PORT: String(port), ...env },
       stdout: Bun.file(logPath),
-      stderr: Bun.file(logPath.replace(/\.log$/, ".err.log")),
+      stderr: Bun.file(errPath),
       detached: true,
     });
     return { proc, logPath };

package/csrE2e/csrPatchFirst.e2e.test.ts

@@ -0,0 +1,87 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import path from "node:path";
+import { CsrE2eHarness } from "./csrE2eHarness.fixture";
+
+const workspaceRoot = path.resolve(import.meta.dir, "../../../..");
+const probeFile = path.join(workspaceRoot, "apps/minimal/ui/StackProbe.tsx");
+const port = Number(process.env.AKAN_CSR_E2E_PATCH_FIRST_PORT ?? 8493);
+
+interface CsrWindow {
+  __akan?: { generation: number };
+}
+
+//? AKAN_CSR_DEV_APP_WRITE_DELAY_MS holds app.js back after the patch is announced, so a tab can boot inside the gap.
+describe.skipIf(!CsrE2eHarness.enabled)("CSR patch before app.js (minimal, app.js written 1.5s late)", () => {
+  let csr: CsrE2eHarness | null = null;
+  const harness = () => {
+    if (!csr) throw new Error("[csr-e2e] the harness did not start");
+    return csr;
+  };
+
+  beforeAll(async () => {
+    csr = await CsrE2eHarness.start({
+      app: "minimal",
+      port,
+      workspaceRoot,
+      env: { AKAN_CSR_DEV_APP_WRITE_DELAY_MS: "1500" },
+    });
+  }, 240_000);
+
+  afterAll(async () => {
+    await csr?.close();
+  }, 60_000);
+
+  const generation = async () =>
+    await harness().evaluate(() => (window as unknown as CsrWindow).__akan?.generation ?? 0);
+  const hot = async () =>
+    await harness().evaluate(
+      () => document.querySelector('[data-e2e-probe="tab-a"]')?.getAttribute("data-e2e-hot") ?? null,
+    );
+
+  test("an open tab takes the patch before app.js is rewritten", async () => {
+    await harness().open("/e2e/stack/tab-a");
+    const before = await generation();
+    await harness().editSource(
+      probeFile,
+      (source) => source.replace("data-e2e-probe={name}>", 'data-e2e-probe={name} data-e2e-hot="early">'),
+      async () => {
+        const startedAt = Date.now();
+        await harness().waitFor(
+          () => document.querySelector('[data-e2e-probe="tab-a"]')?.getAttribute("data-e2e-hot") === "early",
+          { timeout: 20_000 },
+        );
+        expect(Date.now() - startedAt).toBeLessThan(1_500);
+        expect(await generation()).toBeGreaterThan(before);
+      },
+    );
+    expect(await harness().reloaded()).toBe(false);
+  }, 120_000);
+
+  test("a tab booting between the patch and app.js starts at the new generation with no second reload", async () => {
+    await harness().open("/e2e/stack/tab-a");
+    //? The previous test's restore may still be on its way: wait until the page shows it.
+    await harness().waitFor(
+      () => document.querySelector('[data-e2e-probe="tab-a"]')?.getAttribute("data-e2e-hot") === null,
+      { timeout: 20_000 },
+    );
+    await harness().editSource(
+      probeFile,
+      (source) => source.replace("data-e2e-probe={name}>", 'data-e2e-probe={name} data-e2e-hot="booted">'),
+      async () => {
+        await harness().waitFor(
+          () => document.querySelector('[data-e2e-probe="tab-a"]')?.getAttribute("data-e2e-hot") === "booted",
+          { timeout: 20_000 },
+        );
+        const target = await generation();
+        //? The first document after the reload: a second reload inside the harness's settle would take the marker.
+        const booted = await harness().reload();
+        expect(await generation()).toBe(target);
+        expect(await hot()).toBe("booted");
+        await Bun.sleep(2_000);
+        expect(await harness().reloaded()).toBe(false);
+        expect(await harness().evaluate(() => performance.timeOrigin)).toBe(booted);
+        expect(await generation()).toBe(target);
+      },
+    );
+  }, 120_000);
+});