@akanjs/devkit 3.0.0-beta.28 → 3.0.0-beta.29

package/akanApp/akanApp.host.test.ts

@@ -1,5 +1,9 @@
 import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import { IncrementalBuilderHost } from "../incrementalBuilder";
+import { createTempApp, isolateEnv, tempRoots, writeText } from "../testHelpers";
 import { AkanAppHost } from "./akanApp.host";
+import type { DevHostEvent } from "./devHostPolicy";
 
 describe("readProcessRssBytes", () => {
   test("reads this process's own rss", async () => {
@@ -14,3 +18,54 @@ describe("readProcessRssBytes", () => {
     expect(await AkanAppHost.readProcessRssBytes(2_147_483_646)).toBeNull();
   });
 });
+
+describe("a gateway whose replica crash-loops", () => {
+  isolateEnv({ AKAN_PUBLIC_REPO_NAME: "repo", AKAN_PUBLIC_SERVE_DOMAIN: "localhost", AKAN_PUBLIC_ENV: "local" });
+  const track = tempRoots();
+  const crashLoop = "Backend replica 0/federation failed 3 consecutive boots; waiting for a code change to retry: boom";
+  const readyBuilder = {
+    status: "ready",
+    patcherOff: false,
+    start: ({ onReady }: { onReady?: () => void }) => onReady?.(),
+    send: () => true,
+    stop: () => undefined,
+  } as unknown as IncrementalBuilderHost;
+
+  test("fails the dev server at once, and leaves it running for the fix", async () => {
+    const { root, app } = track(await createTempApp("demo"));
+    await writeText(
+      path.join(root, "apps/demo/main.ts"),
+      [
+        `process.send?.({ type: "build-status", data: { generation: -1, phase: "backend", ok: false, files: [], message: ${JSON.stringify(crashLoop)} } });`,
+        "setInterval(() => undefined, 1_000);",
+        "",
+      ].join("\n"),
+    );
+    const create = IncrementalBuilderHost.create;
+    IncrementalBuilderHost.create = async () => readyBuilder;
+    const events: DevHostEvent[] = [];
+    const failed = Promise.withResolvers<void>();
+    const host = new AkanAppHost(app, {
+      env: { ...process.env } as Record<string, string>,
+      onDevEvent: (event) => {
+        events.push(event);
+        if ("state" in event && event.state === "failed") failed.resolve();
+      },
+    });
+    let beforeStop: DevHostEvent[] = [];
+    try {
+      await host.start();
+      await failed.promise;
+      await Bun.sleep(300);
+      beforeStop = [...events];
+    } finally {
+      await host.stop();
+      IncrementalBuilderHost.create = create;
+    }
+
+    expect(beforeStop).toEqual([
+      { app: "demo", state: "starting" },
+      { app: "demo", state: "failed", detail: crashLoop },
+    ]);
+  });
+});

package/akanApp/akanApp.host.ts

@@ -245,6 +245,8 @@ export class AkanAppHost {
             message: msg.data.message,
           });
           this.#sendOrQueueBuildStatus(status);
+          //? A replica crash loop leaves the gateway up, waiting for an edit: no exit reaches the host's own give-up.
+          if (!status.ok) this.#emitDevEvent("failed", status.message);
           return;
         }
         if (backendMsgTypeSet.has(msg.type)) this.#sendToBuilder(msg);

package/mobile/desktopServerStage.test.ts

@@ -2,7 +2,8 @@ import { describe, expect, test } from "bun:test";
 import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { AkanAppConfig } from "../akanConfig";
-import { tempDirs } from "../testHelpers";
+import type { App } from "../commandDecorators";
+import { tempDirs, writeText as write } from "../testHelpers";
 import type { PackageJson } from "../types";
 import { DesktopServerStage } from "./desktopServerStage";
 import { NativeApi } from "./nativeApi";
@@ -85,6 +86,80 @@ describe("DesktopServerStage", () => {
     });
   });
 
+  const stageApp = async (spawn: (...args: unknown[]) => Promise<string> = async () => "") => {
+    const root = await makeTempRoot();
+    const dist = path.join(root, "dist/apps/portal");
+    const config = appConfig();
+    const app = {
+      cwdPath: path.join(root, "apps/portal"),
+      dist: { cwdPath: dist },
+      getConfig: async () => config,
+      getScanInfo: () => ({ getLibs: () => [] }),
+      logger: { info: () => undefined, warn: () => undefined },
+      spawn,
+    } as unknown as App;
+    return { dist, app, stage: new DesktopServerStage(app) };
+  };
+
+  test("carries everything the backend build wrote beside main.js but what only the image reads", async () => {
+    const { dist, stage } = await stageApp();
+    const carried = [
+      "main.js",
+      "server.js",
+      "chunk-5eap2n9b.js",
+      "akan.build.json",
+      "better-sqlite3-a1b2c3d4.node",
+      "engine-e5f6a7b8.wasm",
+      "model-c9d0e1f2.bin",
+      "private/service-account.json",
+    ];
+    const imageOnly = [
+      "Dockerfile",
+      "package.json",
+      "rscWorker.js",
+      "console.js",
+      "console-runtime.js",
+      "csr/index.html",
+      "public/favicon.ico",
+      ".akan/artifact/base-artifact.json",
+    ];
+    for (const file of [...carried, ...imageOnly]) await write(path.join(dist, file), file);
+
+    await stage.prepare("main");
+
+    const staged = await Array.fromAsync(new Bun.Glob("**/*").scan({ cwd: stage.dir, dot: true }));
+    expect(staged.map((file) => file.split(path.sep).join("/")).sort()).toEqual(carried.sort());
+    expect(await Bun.file(path.join(stage.dir, "better-sqlite3-a1b2c3d4.node")).text()).toBe(
+      "better-sqlite3-a1b2c3d4.node",
+    );
+  });
+
+  test("installs from the config alone, offline when Bun's cache holds the packages", async () => {
+    const spawned: unknown[][] = [];
+    const { stage } = await stageApp(async (...args) => {
+      spawned.push(args);
+      return "";
+    });
+
+    await stage.install();
+
+    expect(spawned).toEqual([[process.execPath, ["install", "--production", "--prefer-offline"], { cwd: stage.dir }]]);
+    const installed = (await Bun.file(path.join(stage.dir, "package.json")).json()) as PackageJson;
+    expect(Object.keys(installed.dependencies ?? {}).sort()).toEqual(["react", "react-dom"]);
+  });
+
+  test("an install that fails says it needs the registry or a Bun cache that holds the packages", async () => {
+    const { stage } = await stageApp(async () => {
+      throw new Error("error: GET https://registry.npmjs.org/scheduler - ConnectionRefused");
+    });
+
+    const failed = stage.install();
+
+    await expect(failed).rejects.toThrow(
+      "it needs the npm registry, or a Bun cache that already holds every one of them.\nerror: GET https://registry.npmjs.org/scheduler",
+    );
+  });
+
   test("refuses an app whose database modes leave out single", () => {
     expect(() => DesktopServerStage.assertCarriable(appConfig({ database: { modes: ["cluster"] } }))).toThrow(
       "only database mode single runs",

package/mobile/desktopServerStage.ts

@@ -16,8 +16,18 @@ export interface DesktopServerBundle {
 //* `bun install --production` does. It is staged outside dist: installing there would put host packages into the
 //* image's `COPY . .`.
 export class DesktopServerStage {
-  //? The RSC worker's and the akan console's bundles: an API-only server starts neither.
-  static readonly skippedFiles = new Set(["rscWorker.js", "console.js", "console-runtime.js"]);
+  //? An API-only server starts neither the RSC worker nor the akan console and serves no CSR, public/ or SSR artifact,
+  //? and `install` wrote its own package.json. The rest of dist is the server's: its chunks, a `.node`, a `.wasm`.
+  static readonly uncarried = new Set([
+    "Dockerfile",
+    "package.json",
+    "rscWorker.js",
+    "console.js",
+    "console-runtime.js",
+    "csr",
+    "public",
+    ".akan",
+  ]);
   //? Only the RSC worker loads it, and its peer webpack makes 35 of the 43 MB an install would add.
   static readonly rscRenderer = "react-server-dom-webpack";
 
@@ -88,29 +98,37 @@ export class DesktopServerStage {
     return { ...built, dependencies: Object.fromEntries(dependencies) };
   }
 
-  async prepare(environment: MobileEnv): Promise<DesktopServerBundle> {
+  //* The packages come from the config alone, so they install before `akan build` runs: a machine that cannot install
+  //* them stops at once instead of after the whole build.
+  async install() {
     const config = await this.app.getConfig();
     DesktopServerStage.assertCarriable(config);
-    const dist = this.app.dist.cwdPath;
     await rm(this.dir, { recursive: true, force: true });
     await mkdir(this.dir, { recursive: true });
-    const entries = await readdir(dist, { withFileTypes: true });
-    for (const entry of entries) {
-      const carried =
-        (entry.isFile() &&
-          ((entry.name.endsWith(".js") && !DesktopServerStage.skippedFiles.has(entry.name)) ||
-            entry.name === "akan.build.json")) ||
-        (entry.isDirectory() && entry.name === "private");
-      if (carried) await cp(path.join(dist, entry.name), path.join(this.dir, entry.name), { recursive: true });
-    }
-    const built = (await Bun.file(path.join(dist, "package.json")).json()) as PackageJson;
     await writeFile(
       path.join(this.dir, "package.json"),
-      JSON.stringify(DesktopServerStage.packageJson(config, built), null, 2),
+      JSON.stringify(DesktopServerStage.packageJson(config, config.getProductionPackageJson()), null, 2),
     );
-    await this.app.spawn(process.execPath, ["install", "--production"], { cwd: this.dir });
+    try {
+      await this.app.spawn(process.execPath, ["install", "--production", "--prefer-offline"], { cwd: this.dir });
+    } catch (error) {
+      throw new Error(
+        `The desktop app's server could not install its packages in ${this.dir}: it needs the npm registry, or a Bun cache that already holds every one of them.\n${error instanceof Error ? error.message : String(error)}`,
+        { cause: error },
+      );
+    }
     //? Launcher links only: a link out of the app bundle breaks its signature, and the server runs none of them.
     await rm(path.join(this.dir, "node_modules", ".bin"), { recursive: true, force: true });
+  }
+
+  //? Copies the build beside what `install` put in the stage, so it runs after both.
+  async prepare(environment: MobileEnv): Promise<DesktopServerBundle> {
+    const config = await this.app.getConfig();
+    const dist = this.app.dist.cwdPath;
+    await mkdir(this.dir, { recursive: true });
+    for (const name of await readdir(dist))
+      if (!DesktopServerStage.uncarried.has(name))
+        await cp(path.join(dist, name), path.join(this.dir, name), { recursive: true });
     const scanInfo = this.app.getScanInfo({ allowEmpty: true }) ?? (await this.app.scan({ write: false }));
     const carried = [...DesktopBin.select(config, scanInfo.getLibs()).keys()];
     const notice = DesktopServerStage.imageStepsNotice(config, carried);

package/mobile/nativeApp.test.ts

@@ -3,9 +3,12 @@ import path from "node:path";
 import type { AkanPlugin } from "akanjs";
 import type { AkanMobileTargetConfig } from "../akanConfig";
 import type { App } from "../commandDecorators";
+import { tempDirs, writeText } from "../testHelpers";
 import { NativeApp } from "./nativeApp";
 import { NativeConfig } from "./nativeConfig";
 
+const makeTempRoot = tempDirs("akan-native-app-");
+
 const target = (config: Partial<AkanMobileTargetConfig> = {}) => ({
   name: config.name ?? "default",
   config: {
@@ -39,6 +42,33 @@ describe("NativeApp", () => {
     expect(admin.web.dir).toBe(path.join(appDir, ".akan/mobile/admin/web"));
     expect(admin.outDir("ios")).toBe(path.join(appDir, ".akan/mobile/admin/native/ios"));
     expect(admin.outDir("android")).toBe(path.join(appDir, ".akan/mobile/admin/native/android"));
+    expect(admin.devOutDir("macos")).toBe(path.join(appDir, ".akan/mobile/admin/dev/macos"));
+  });
+
+  test("a dev build bundles no page a release build left, and builds apart from the release it would empty", async () => {
+    const app = {
+      ...fakeApp(),
+      cwdPath: await makeTempRoot(),
+      logger: { info: () => undefined, debug: () => undefined, warn: () => undefined },
+    } as unknown as App;
+    const nativeApp = new NativeApp(app, target());
+    await writeText(path.join(nativeApp.web.dir, "index.html"), "<html>the last release</html>");
+    const seen: { outDir?: string; leftover: boolean }[] = [];
+    nativeApp.prepare = async () =>
+      ({
+        config: {},
+        api: {
+          dev: async ({ outDir }: { outDir?: string }) => {
+            seen.push({ outDir, leftover: await Bun.file(path.join(nativeApp.web.dir, "index.html")).exists() });
+            return { gateway: "http://127.0.0.1:9", exited: Promise.resolve(0), stop: async () => undefined };
+          },
+        },
+      }) as never;
+
+    await nativeApp.dev("windows", { upstream: "http://localhost:8282", lang: "en" });
+
+    expect(seen).toEqual([{ outDir: nativeApp.devOutDir("windows"), leftover: false }]);
+    expect(path.relative(nativeApp.outDir("windows"), nativeApp.devOutDir("windows"))).toStartWith("..");
   });
 
   test("a dev boot that came up says so in one line: platform, device, dev server, time", () => {

package/mobile/nativeApp.ts

@@ -1,4 +1,3 @@
-import { mkdir } from "node:fs/promises";
 import path from "node:path";
 import type { AkanNativeConfig } from "@akanjs/native/config";
 import type { MobileEnv } from "akanjs";
@@ -70,6 +69,11 @@ export class NativeApp {
     return path.join(this.targetRoot, "native", platform);
   }
 
+  //? Apart from the builds: a desktop build empties its folder first, which would take a release and its installer.
+  devOutDir(platform: NativePlatform) {
+    return path.join(this.targetRoot, "dev", platform);
+  }
+
   /** The web root, from the production build the mobile commands run first. */
   async assembleWeb() {
     const dist = this.app.dist.cwdPath;
@@ -123,12 +127,16 @@ export class NativeApp {
       this.config({ platform, ...(server ? { server } : {}) }),
     ]);
     for (const warning of warnings) this.app.logger.warn(warning);
+    this.#assertValid(api, config);
+    return { api, config };
+  }
+
+  #assertValid(api: NativeBuildApiModule, config: AkanNativeConfig) {
     const problems = api.validateConfig(config, { appDir: this.app.cwdPath });
     if (problems.length)
       throw new Error(
         `Mobile target '${this.target.name}' makes an invalid native config:\n- ${problems.join("\n- ")}`,
       );
-    return { api, config };
   }
 
   //? The app's own output: its console (mirrored by a dev build), the simulator log stream or logcat.
@@ -139,12 +147,12 @@ export class NativeApp {
   };
 
   //* `AKAN_PUBLIC_*` is already inlined into the CSR bundle, so the runtime reads no .env file of its own.
-  #task(platform: NativePlatform, config: AkanNativeConfig): TaskOptions {
+  #task(platform: NativePlatform, config: AkanNativeConfig, outDir = this.outDir(platform)): TaskOptions {
     return {
       appDir: this.app.cwdPath,
       config,
       platform,
-      outDir: this.outDir(platform),
+      outDir,
       envFiles: false,
       skipWebBuild: true,
       log: (event) => {
@@ -192,10 +200,11 @@ export class NativeApp {
     const boot: NativeDevBoot = { steps: [], lines: [] };
     this.#boot = boot;
     try {
-      await mkdir(this.web.dir, { recursive: true });
+      //? The runtime bundles an index.html it finds here as the dev build's page, and a release build leaves one.
+      await this.web.clear();
       const [{ api, config }, { api: routes }] = await Promise.all([this.prepare(platform), this.app.getConfig()]);
       const session = await api.dev({
-        ...this.#task(platform, config),
+        ...this.#task(platform, config, this.devOutDir(platform)),
         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.
@@ -253,10 +262,7 @@ export class NativeApp {
     { channel, server }: { channel?: string; server?: DesktopServerBundle } = {},
   ) {
     NativeApp.#assertServerPlatform(platform, server);
-    if (!this.target.config.updates)
-      throw new Error(
-        `Mobile target '${this.target.name}' has no updates: { url, publicKey } in akan.config.ts; \`akan update-keygen ${this.app.name}\` prints the key.`,
-      );
+    this.#assertUpdates();
     await this.assembleWeb();
     const { api, config } = await this.prepare(platform, server);
     return await api.publishUpdate({
@@ -267,6 +273,46 @@ export class NativeApp {
     });
   }
 
+  /**
+   * What publishing refuses once the release is built: no updates settings, an invalid config, no signing key or
+   * another app's, and a desktop release whose server presence is not its channel's previous release's.
+   */
+  async assertPublishable(
+    platform: NativePlatform,
+    { channel, server = false }: { channel?: string; server?: boolean } = {},
+  ) {
+    this.#assertUpdates();
+    const [api, { config }] = await Promise.all([
+      NativeApi.load(this.app.cwdPath),
+      this.config({ platform, stageBin: false }),
+    ]);
+    this.#assertValid(api, config);
+    try {
+      api.checkPublishUpdate({
+        appDir: this.app.cwdPath,
+        config,
+        platform,
+        out: this.updatesDir,
+        server,
+        ...(channel ? { channel } : {}),
+      });
+    } catch (error) {
+      throw new Error(
+        `Mobile target '${this.target.name}': ${error instanceof Error ? error.message : String(error)}`,
+        {
+          cause: error,
+        },
+      );
+    }
+  }
+
+  #assertUpdates() {
+    if (!this.target.config.updates)
+      throw new Error(
+        `Mobile target '${this.target.name}' has no updates: { url, publicKey } in akan.config.ts; \`akan update-keygen ${this.app.name}\` prints the key.`,
+      );
+  }
+
   /** The key update releases of this target's app id on `platform` are signed with: made once, then read. */
   async updateKeygen(platform: NativePlatform) {
     const [api, { config }] = await Promise.all([

package/mobile/nativeWebDir.ts

@@ -34,12 +34,16 @@ export class NativeWebDir {
   }
   static readonly #targetTag = "<script>window.__AKAN_MOBILE_TARGET__=";
 
+  async clear() {
+    await rm(this.dir, { recursive: true, force: true });
+    await mkdir(this.dir, { recursive: true });
+  }
+
   /** Rebuilds the folder from scratch and answers its files as web paths: relative, `/`-separated and sorted. */
   async assemble(target: AkanMobileTargetConfig, { html, publicDir, fontsDir }: NativeWebDirSources) {
     if (!(await Bun.file(html).exists()))
       throw new Error(`CSR html for mobile target '${target.name}' not found: ${html}`);
-    await rm(this.dir, { recursive: true, force: true });
-    await mkdir(this.dir, { recursive: true });
+    await this.clear();
     if (publicDir && (await NativeWebDir.#isDir(publicDir))) await cp(publicDir, this.dir, { recursive: true });
     if (fontsDir && (await NativeWebDir.#isDir(fontsDir)))
       await cp(fontsDir, path.join(this.dir, "_akan", "fonts"), { recursive: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.0.0-beta.28",
+  "version": "3.0.0-beta.29",
   "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.28",
+    "akanjs": "3.0.0-beta.29",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",

package/transforms/serverEnvPlugin.test.ts

@@ -76,6 +76,9 @@ describe("createServerEnvPlugin", () => {
     expect(proc.stderr.toString()).toContain(
       "env/env.server.develop.ts is not in this build: `akan build` bundles the server env of AKAN_PUBLIC_ENV=main alone",
     );
+    expect(proc.stderr.toString()).toContain(
+      "To run develop, build for it: AKAN_PUBLIC_ENV=develop in the workspace's .env, which outranks the shell, or --env develop on a desktop or mobile build.",
+    );
   });
 
   test("a custom branch is its own environment", async () => {

package/transforms/serverEnvPlugin.ts

@@ -26,7 +26,7 @@ export const createServerEnvPlugin = ({ envDir, environment, environments }: Ser
       build.onLoad({ filter }, async (args) => {
         const name = path.basename(args.path, ".ts").slice("env.server.".length);
         const { exports } = new Bun.Transpiler({ loader: "ts" }).scan(await Bun.file(args.path).text());
-        const message = `env/env.server.${name}.ts is not in this build: \`akan build\` bundles the server env of AKAN_PUBLIC_ENV=${environment} alone, the environment its image runs. Build with AKAN_PUBLIC_ENV=${name} to run ${name}.`;
+        const message = `env/env.server.${name}.ts is not in this build: \`akan build\` bundles the server env of AKAN_PUBLIC_ENV=${environment} alone, the environment its image runs. To run ${name}, build for it: AKAN_PUBLIC_ENV=${name} in the workspace's .env, which outranks the shell, or --env ${name} on a desktop or mobile build.`;
         return {
           loader: "js",
           contents: [