@akanjs/devkit 3.1.0-rc.0 → 3.1.0-rc.2

package/incrementalBuilder/buildBatch.proc.ts

@@ -33,13 +33,17 @@ class BuildBatch {
   }
 
   async run(): Promise<BuildBatchResult> {
-    if (this.#request.needs.includes("base")) await this.#buildBase();
-    if (this.#request.needs.includes("csr")) await this.#buildCsr();
-    if (this.#request.needs.includes("shell")) await this.#buildShell();
-    if (this.#request.needs.includes("ssr")) await this.#buildSsrRegistry();
+    const { needs } = this.#request;
+    //? A CSR artifact inlines the stylesheets, so it waits for this batch's compile of them; the registry reads none.
+    const cssFirst = needs.includes("css") && needs.includes("csr") && resolveDevCsrMode() === "artifact";
+    if (needs.includes("base")) await this.#buildBase();
+    if (cssFirst) await this.#buildCss();
+    if (needs.includes("csr")) await this.#buildCsr();
+    if (needs.includes("shell")) await this.#buildShell();
+    if (needs.includes("ssr")) await this.#buildSsrRegistry();
     // Css before pages: it scans the sources and reads nothing pages produces, so a class edit need not wait for pages.
-    if (this.#request.needs.includes("css")) await this.#buildCss();
-    if (this.#request.needs.includes("pages")) await this.#buildPages();
+    if (needs.includes("css") && !cssFirst) await this.#buildCss();
+    if (needs.includes("pages")) await this.#buildPages();
     return this.#result;
   }
 
@@ -112,7 +116,8 @@ class BuildBatch {
   }
 
   async #rebuildCsrArtifact(started: number): Promise<void> {
-    await new CsrArtifactBuilder(this.#app, "start", "en", { cssAssets: this.#request.cssAssets }).build();
+    const cssAssets = this.#result.cssAssets ?? this.#request.cssAssets;
+    await new CsrArtifactBuilder(this.#app, "start", "en", { cssAssets }).build();
     this.#logger.verbose(`csr-rebundle ok (${Date.now() - started}ms)`);
     // A CSR tab takes none of the SSR refresh messages, so a rebuilt artifact reaches it only as this reload.
     if (this.#request.changedFiles.length === 0) return;

package/incrementalBuilder/incrementalBuilder.proc.test.ts

@@ -178,6 +178,69 @@ process.send({ type: "build-batch-result", data: { generation, errors: {}, artif
     expect(batches.filter((needs) => needs === "shell")).toHaveLength(1);
   }, 30_000);
 
+  test("builds the shell again once the css it inlined is replaced, though the generation has not moved", async () => {
+    const { root } = track(await createTempApp("demo"));
+    const appDir = path.join(root, "apps/demo");
+    const ledger = path.join(root, "batches.log");
+    const gate = path.join(root, "css-lands");
+    const landed = { "": { cssUrl: "/_akan/styles/root-next.css", cssRelPath: "styles/root-next.css" } };
+    // The registry's boot build stands in for a save's css compile, held until the first shell is built.
+    await writeText(
+      path.join(root, "pkgs/@akanjs/devkit/incrementalBuilder/buildBatch.proc.ts"),
+      `import fs from "node:fs";
+const { generation, needs, cssAssets } = JSON.parse(process.argv[2]);
+fs.appendFileSync(${JSON.stringify(ledger)}, needs.join(",") + " " + JSON.stringify(cssAssets) + "\\n");
+const orphaned = () => process.exit(1);
+process.on("disconnect", orphaned);
+const deadline = Date.now() + 15_000;
+if (needs.includes("ssr")) while (!fs.existsSync(${JSON.stringify(gate)}) && Date.now() < deadline) await Bun.sleep(20);
+const css = needs.includes("ssr") ? { cssAssets: ${JSON.stringify(landed)} } : {};
+process.send({ type: "build-batch-result", data: { generation, errors: {}, artifact: {}, optimizedFonts: { css: "", files: [] }, ...css } });
+process.off("disconnect", orphaned);
+`,
+    );
+    await writeText(path.join(appDir, "page/_index.tsx"), "export default () => null;\n");
+    const messages: BuilderMessage[] = [];
+    const proc = Bun.spawn(["bun", path.join(import.meta.dir, "incrementalBuilder.proc.ts")], {
+      cwd: appDir,
+      env: {
+        ...process.env,
+        AKAN_WORKSPACE_ROOT: root,
+        AKAN_PUBLIC_APP_NAME: "demo",
+        AKAN_PUBLIC_REPO_NAME: "repo",
+        AKAN_PUBLIC_SERVE_DOMAIN: "localhost",
+        AKAN_PUBLIC_ENV: "local",
+        AKAN_WATCH: "0",
+        AKAN_DEV_CSR_PATCHER: "off",
+      },
+      stdio: ["ignore", "ignore", "pipe"],
+      serialization: "advanced",
+      ipc: (message: BuilderMessage) => {
+        messages.push(message);
+      },
+    });
+    const answers = () => messages.filter((message) => message.type === "build-csr-res");
+    try {
+      await until(proc, "builder-ready", () => messages.some((message) => message.type === "builder-ready"));
+      proc.send({ type: "build-csr", id: 7, reason: "mcp app view", shell: true } satisfies BuilderMessage);
+      await until(proc, "the first build-csr-res", () => answers().length === 1);
+      await writeText(gate, "");
+      await until(proc, "boot-armed", () => messages.some((message) => message.type === "boot-armed"));
+      proc.send({ type: "build-csr", id: 8, reason: "mcp app view", shell: true } satisfies BuilderMessage);
+      await until(proc, "the second build-csr-res", () => answers().length === 2);
+    } finally {
+      await writeText(gate, "");
+      proc.kill();
+      await proc.exited;
+    }
+    expect(answers()).toEqual([
+      { type: "build-csr-res", id: 7, ok: true },
+      { type: "build-csr-res", id: 8, ok: true },
+    ]);
+    const shells = (await Bun.file(ledger).text()).split("\n").filter((line) => line.startsWith("shell "));
+    expect(shells).toEqual(["shell null", `shell ${JSON.stringify(landed)}`]);
+  }, 30_000);
+
   test("a killed boot build is tried again after the crash window, before boot-armed; a route build's check waits likewise", async () => {
     // Inside the checkout so the route's client bundle resolves the framework from its source.
     const { root } = track(await createTempApp("demo", path.join(import.meta.dir, "..", "local")));

package/incrementalBuilder/incrementalBuilder.proc.ts

@@ -63,7 +63,7 @@ class IncrementalBuilder {
   #autoImportSync: AutoImportSync;
   #watcher: HmrWatcher | null = null;
   #generation = 0;
-  #shellGeneration: number | null = null;
+  #shellKey: string | null = null;
   #discoveredThrough = 0;
   #csrActive = IncrementalBuilder.#csrArmedByEnv();
   #csrBundler: CsrDevBundler;
@@ -908,19 +908,21 @@ class IncrementalBuilder {
     await armed;
   }
 
-  // Asked on every view read and rebuilt only when a save moved the generation, instead of armed per save: a restarted
-  // builder has no last build to trust, and so rebuilds once on the next read.
+  // Asked on every view read and rebuilt only when a save moved the generation or the css it inlines, instead of armed
+  // per save: a restarted builder has no last build to trust, and so rebuilds once on the next read.
   async #buildShell(msg: BuilderCsrReq): Promise<void> {
     await this.#workQueue.enqueue("build-shell", async (): Promise<void> => {
       const generation = this.#generation;
+      //? A save moves the generation before its css compile lands, so a shell built in between holds the old css.
+      const shellKey = `${generation}:${JSON.stringify(this.#artifact.cssAssets)}`;
       let error: string | undefined;
-      if (this.#shellGeneration !== generation)
+      if (this.#shellKey !== shellKey)
         try {
           const result = await this.#batchRunner.run(
             await this.#batchRequest({ generation, needs: ["shell"], changedFiles: [] }),
           );
           error = result.errors.shell;
-          if (!error) this.#shellGeneration = generation;
+          if (!error) this.#shellKey = shellKey;
         } catch (err) {
           error = ApplicationBuildReporter.formatError(err, this.#app.workspace.workspaceRoot);
         }

package/mobile/desktopServerStage.test.ts

@@ -54,6 +54,19 @@ describe("DesktopServerStage", () => {
     expect(withEnv).toMatchObject({ CLOUD_ORIGIN: "https://cloud.example", AKAN_PUBLIC_OPERATION_MODE: "edge" });
   });
 
+  test("every key the stage sets over desktop.server.env is one the config refuses there, never silently replaced", () => {
+    const config = appConfig();
+    const run = { modules: ["@edge"] };
+    const owned = Object.keys(DesktopServerStage.env(config, "main", run)).filter(
+      (key) => DesktopServerStage.env(config, "main", { ...run, env: { [key]: "mine" } })[key] !== "mine",
+    );
+    expect(owned).toEqual(expect.arrayContaining(["AKAN_MCP", "AKAN_SHUTDOWN_TIMEOUT_MS", "AKAN_MODULES"]));
+    for (const key of owned)
+      expect(() => appConfig({ native: { desktop: { server: { env: { [key]: "mine" } } } } })).toThrow(
+        `sets ${key}, which the carried server's stage owns`,
+      );
+  });
+
   test("installs what the image does, minus the RSC renderer and the other modes' drivers", () => {
     const config = appConfig({ database: { modes: ["single", "cluster"] }, externalLibs: ["@external/runtime"] });
     const built = config.getProductionPackageJson();

package/mobile/desktopServerStage.ts

@@ -1,25 +1,23 @@
 import { cp, mkdir, readdir, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
+import type { ServerPolicy } from "@akanjs/native/api";
+import { toError } from "akanjs/common";
 import type { AkanAppConfig, NativeEnv } from "../akanConfig";
 import type { App } from "../commandDecorators";
 import type { PackageJson } from "../types";
 import { DesktopBin } from "./desktopBin";
 
 /** What a desktop build hands the native runtime as `desktop.server`. */
-export interface DesktopServerBundle {
+export interface DesktopServerBundle extends ServerPolicy {
   dir: string;
   entry: string;
   env: Record<string, string>;
-  restart?: "forever" | number;
-  watchdog?: { intervalMs: number; failures: number };
 }
 
 /** How the targets that carry one build's server have it run (`desktop.server`, normalized). */
-export interface DesktopServerRun {
+export interface DesktopServerRun extends ServerPolicy {
   modules?: string[];
   env?: Record<string, string>;
-  restart?: "forever" | number;
-  watchdog?: { intervalMs: number; failures: number };
 }
 
 //* A desktop app's carried server is the backend `akan build` wrote into dist, installed on its own as the image's
@@ -153,7 +151,7 @@ export class DesktopServerStage {
       await this.app.spawn(process.execPath, DesktopServerStage.installArgs(arch), { 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)}`,
+        `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${toError(error).message}`,
         { cause: error },
       );
     }

package/mobile/index.ts

@@ -5,7 +5,9 @@ export * from "./nativeApi";
 export * from "./nativeApp";
 export * from "./nativeConfig";
 export * from "./nativePluginFolders";
+export * from "./nativePublicEnv";
 export * from "./nativeWebDir";
 export * from "./placeholderAppId";
+export * from "./updatePackFolder";
 export * from "./updateUploader";
 export * from "./usageDescriptions";

package/mobile/nativeApi.test.ts

@@ -7,6 +7,19 @@ import { NativeApi } from "./nativeApi";
 const makeTempRoot = tempDirs("akan-native-api-");
 const repoApp = path.resolve(import.meta.dir, "../../../../apps/minimal");
 
+const installVendoredApi = async (version: string) => {
+  const root = await realpath(await makeTempRoot());
+  await mkdir(path.join(root, "node_modules/akanjs"), { recursive: true });
+  await writeFile(
+    path.join(root, "node_modules/akanjs/package.json"),
+    JSON.stringify({ name: "akanjs", exports: { "./package.json": "./package.json" } }),
+  );
+  const entry = NativeApi.entryOf(root);
+  await mkdir(path.dirname(entry), { recursive: true });
+  await writeFile(entry, `export const API_VERSION = ${JSON.stringify(version)};\n`);
+  return root;
+};
+
 describe("NativeApi", () => {
   test("inside this repo, loads the workspace package and checks its major", async () => {
     expect(NativeApi.entryOf(repoApp)).toBe(path.resolve(import.meta.dir, "../../native/packages/cli/src/api.ts"));
@@ -27,4 +40,17 @@ describe("NativeApi", () => {
     );
     await expect(NativeApi.load(root)).rejects.toThrow("The installed akanjs has no native build");
   });
+
+  test("refuses an API older than the one the build calls into, and another major, before anything builds", async () => {
+    await expect(NativeApi.load(await installVendoredApi("0.10.0"))).rejects.toThrow(
+      "install matching versions of akanjs and @akanjs/cli",
+    );
+    await expect(NativeApi.load(await installVendoredApi("1.0.0"))).rejects.toThrow(
+      "install matching versions of akanjs and @akanjs/cli",
+    );
+    expect((await NativeApi.load(await installVendoredApi(NativeApi.minimumVersion))).API_VERSION).toBe(
+      NativeApi.minimumVersion,
+    );
+    expect((await NativeApi.load(await installVendoredApi("0.12.0"))).API_VERSION).toBe("0.12.0");
+  });
 });

package/mobile/nativeApi.ts

@@ -6,6 +6,9 @@ export type NativeBuildApiModule = typeof NativeBuildApi;
 export class NativeApi {
   //* The build API versions itself; a major this devkit was not written against is refused before anything builds.
   static readonly supportedMajor = 0;
+  //? An update release's `revoke` and `resetSequence` arrived in 0.12.0, and an older API would publish without them;
+  //? `requestedDistribution` in 0.11.0; akanjs 3.0.x vendors 0.10.0.
+  static readonly minimumVersion = "0.12.0";
 
   /** The API of the akanjs the app installed: the workspace package inside this repo, akanjs's vendored copy elsewhere. */
   static entryOf(appDir: string): string {
@@ -22,9 +25,9 @@ export class NativeApi {
       throw new Error(`The installed akanjs has no native build at ${entry}; update akanjs.`);
     const api = (await import(entry)) as NativeBuildApiModule;
     const major = Number(api.API_VERSION.split(".")[0]);
-    if (major !== NativeApi.supportedMajor)
+    if (major !== NativeApi.supportedMajor || Bun.semver.order(api.API_VERSION, NativeApi.minimumVersion) < 0)
       throw new Error(
-        `The native build API is ${api.API_VERSION}, and this akan CLI speaks ${NativeApi.supportedMajor}.x; install matching versions of akanjs and @akanjs/cli.`,
+        `The native build API is ${api.API_VERSION}, and this akan CLI speaks ${NativeApi.minimumVersion} or a later ${NativeApi.supportedMajor}.x; install matching versions of akanjs and @akanjs/cli.`,
       );
     return api;
   }

package/mobile/nativeApp.test.ts

@@ -3,9 +3,11 @@ import path from "node:path";
 import type { AkanPlugin } from "akanjs";
 import type { AkanNativeTarget } from "../akanConfig";
 import type { App } from "../commandDecorators";
+import { CsrArtifactBuilder } from "../frontendBuild/csrArtifactBuilder";
 import { tempDirs, writeText } from "../testHelpers";
 import { NativeApp } from "./nativeApp";
 import { NativeConfig } from "./nativeConfig";
+import { NativePublicEnv } from "./nativePublicEnv";
 
 const makeTempRoot = tempDirs("akan-native-app-");
 
@@ -88,6 +90,139 @@ describe("NativeApp", () => {
     });
   });
 
+  describe("the server a release carries, signed or not", () => {
+    const releasing = async () => {
+      const root = await makeTempRoot();
+      const appPath = path.join(root, "apps/portal");
+      await writeText(
+        path.join(appPath, "env/env.server.main.ts"),
+        'export const env = { security: { jwtSecret: "main-jwt-0123456789" } };\n',
+      );
+      const server = { dir: path.join(root, "server"), entry: "main.js", env: {} };
+      await writeText(path.join(server.dir, "main.js"), 'const jwt = "main-jwt-0123456789";\n');
+      const app = {
+        ...fakeApp(),
+        cwdPath: appPath,
+        workspace: { workspaceRoot: root },
+        logger: { info: () => undefined, warn: () => undefined },
+      } as unknown as App;
+      const updates = { url: "https://releases.example.com/portal", publicKey: `${"a".repeat(43)}=` };
+      const nativeApp = new NativeApp(app, target({ updates }), "main");
+      const built: string[] = [];
+      nativeApp.assembleWeb = async () => undefined as never;
+      nativeApp.prepare = async () =>
+        ({
+          config: {},
+          api: {
+            requestedDistribution: () => ({ notice: null, unused: [] }),
+            build: async ({ profile }: { profile: string }) => {
+              built.push(profile);
+              return { artifacts: [], warnings: [] };
+            },
+            publishUpdate: async () => {
+              built.push("update");
+              return {};
+            },
+          },
+        }) as never;
+      return { appPath, server, nativeApp, built };
+    };
+
+    test("an unsigned release build and an unsigned update are refused when it holds a secret, a debug build is not searched", async () => {
+      const { server, nativeApp, built } = await releasing();
+      await expect(nativeApp.build("linux", { server })).rejects.toThrow(
+        "main.js holds apps/portal/env/env.server.main.ts security.jwtSecret",
+      );
+      await expect(nativeApp.publishUpdate("linux", { server })).rejects.toThrow("security.jwtSecret");
+      await nativeApp.build("linux", { server, profile: "debug" });
+      expect(built).toEqual(["debug"]);
+    });
+
+    test("an env file that cannot be evaluated stops the release instead of going unsearched", async () => {
+      const { appPath, server, nativeApp, built } = await releasing();
+      await writeText(path.join(server.dir, "main.js"), "\n");
+      await writeText(path.join(appPath, "env/env.server.develop.ts"), 'export { env } from "./missing";\n');
+      await expect(nativeApp.build("linux", { server })).rejects.toThrow(
+        "The server this app carries was not searched for the secret values of apps/portal/env/env.server.develop.ts",
+      );
+      expect(built).toEqual([]);
+    });
+  });
+
+  describe("the public env a build inlined, recorded in its bundle.json", () => {
+    const publicEnv = { AKAN_PUBLIC_ENV: "main", AKAN_PUBLIC_SERVE_DOMAIN: "akamir.com" };
+    const building = async (inlined: Record<string, string>, updates: object | undefined) => {
+      const root = await makeTempRoot();
+      const warned: string[] = [];
+      const app = {
+        ...fakeApp(),
+        workspace: { workspaceRoot: root },
+        dist: { cwdPath: path.join(root, "dist/apps/portal") },
+        logger: { info: () => undefined, warn: (message: string) => warned.push(message) },
+      } as unknown as App;
+      await CsrArtifactBuilder.writePublicEnv(
+        app,
+        Object.fromEntries(
+          Object.entries({ ...inlined, AKAN_PUBLIC_APP_NAME: "portal", AKAN_PUBLIC_RENDER_ENV: "csr" }).map(
+            ([key, value]) => [`process.env.${key}`, JSON.stringify(value)],
+          ),
+        ),
+      );
+      const nativeApp = new NativeApp(app, target(updates ? { updates } : {}), "main");
+      const built: string[] = [];
+      const writeBundle = async (dir: string) =>
+        await writeText(path.join(dir, "bundle.json"), JSON.stringify({ schema: 1, web: { hash: "w", files: 1 } }));
+      nativeApp.assembleWeb = async () => undefined as never;
+      nativeApp.prepare = async () =>
+        ({
+          config: { updates: { channel: "production" } },
+          api: {
+            packUpdate: async ({ out }: { out: string }) => {
+              built.push("pack");
+              await writeBundle(out);
+              return { out, manifest: { app: "com.portal.app", version: "1.0.0", nativeApi: "n", files: [] } };
+            },
+            release: async ({ outDir }: { outDir: string }) => {
+              built.push("release");
+              await writeBundle(outDir);
+              return {};
+            },
+          },
+        }) as never;
+      return { root, nativeApp, built, warned };
+    };
+    const updates = { url: "https://releases.example.com/portal", publicKey: `${"a".repeat(43)}=` };
+
+    test("a pack and a release record what the CSR build inlined, and the pack's record carries its hash", async () => {
+      const { root, nativeApp } = await building(publicEnv, updates);
+      const { pack } = await nativeApp.packUpdate("android", { out: path.join(root, "out") });
+      const bundle = await Bun.file(path.join(root, "out/bundle.json")).json();
+      expect(bundle.web).toEqual({
+        hash: "w",
+        files: 1,
+        publicEnv,
+        publicEnvHash: NativePublicEnv.hash(publicEnv),
+      });
+      expect(pack.publicEnvHash).toBe(NativePublicEnv.hash(publicEnv));
+      await nativeApp.releaseIos();
+      const release = await Bun.file(path.join(nativeApp.outDir("ios"), "bundle.json")).json();
+      expect(release.web.publicEnvHash).toBe(NativePublicEnv.hash(publicEnv));
+    });
+
+    test("an env an update cannot carry stops a target with updates before it builds, and only warns without", async () => {
+      const refused = { ...publicEnv, AKAN_PUBLIC_MAP_TOKEN: "pk.x" };
+      const withUpdates = await building(refused, updates);
+      await expect(withUpdates.nativeApp.releaseIos()).rejects.toThrow("AKAN_PUBLIC_MAP_TOKEN names a token");
+      expect(withUpdates.built).toEqual([]);
+      const without = await building(refused, undefined);
+      await without.nativeApp.releaseIos();
+      expect(without.built).toEqual(["release"]);
+      expect(without.warned.join("\n")).toContain("bundle.json records none");
+      const release = await Bun.file(path.join(without.nativeApp.outDir("ios"), "bundle.json")).json();
+      expect(release.web.publicEnv).toBeUndefined();
+    });
+  });
+
   test("a dev build bundles no page a release build left, and builds apart from the release it would empty", async () => {
     const root = await makeTempRoot();
     const app = {