@akanjs/devkit 3.1.0-rc.1 → 3.1.0-rc.3

package/executors.ts

@@ -28,6 +28,7 @@ import {
   isRouteSourceFile,
   Logger,
   parseRouteModuleKey,
+  toError,
   validatePageSourceFile,
   validateSubRoutePageKey,
 } from "akanjs/common";
@@ -52,6 +53,7 @@ import { AppInfo, isAkanFrameworkDependency, LibInfo, PkgInfo, WorkspaceInfo } f
 import { Spinner } from "./spinner";
 // Type-only: `getTypeChecker` loads it on demand to keep `typescript` out of the resident module graph.
 import type { TypeChecker } from "./typeChecker";
+import { ProjectTypecheck } from "./typecheck/projectTypecheck";
 import type { FileContent, PackageJson, TsConfigJson } from "./types";
 import { barrelFacetDirs } from "./workspaceLayout";
 
@@ -64,6 +66,10 @@ export interface PageRoot {
   keyPrefix: string;
 }
 
+export interface WrittenFileContent extends FileContent {
+  written: boolean;
+}
+
 const staticTemplateFileExtensions = new Set(
   ".avif .bmp .cjs .css .eot .gif .html .ico .jpeg .jpg .js .json .map .md .mjs .mp3 .mp4 .ogg .otf .pdf .png .svg"
     .split(" ")
@@ -265,20 +271,20 @@ export class Executor {
     const readPath = this.getPath(dirPath);
     try {
       const glob = new Bun.Glob("*");
-      return Array.from(glob.scanSync({ cwd: readPath, onlyFiles: false }));
+      return Array.from(glob.scanSync({ cwd: readPath, onlyFiles: false })).sort();
     } catch {
       return [];
     }
   }
   async getAllFiles(pattern = "**/*", { cwd }: { cwd?: string } = {}): Promise<string[]> {
     const glob = new Bun.Glob(pattern);
-    return Array.from(glob.scanSync({ cwd: cwd ?? this.cwdPath, onlyFiles: true }));
+    return Array.from(glob.scanSync({ cwd: cwd ?? this.cwdPath, onlyFiles: true })).sort();
   }
   async getFilesAndDirs(dirPath: string): Promise<{ files: string[]; dirs: string[] }> {
     const fullDirPath = this.getPath(dirPath);
     const glob = new Bun.Glob("*");
-    const files = Array.from(glob.scanSync({ cwd: fullDirPath, onlyFiles: true }));
-    const allEntries = Array.from(glob.scanSync({ cwd: fullDirPath, onlyFiles: false }));
+    const files = Array.from(glob.scanSync({ cwd: fullDirPath, onlyFiles: true })).sort();
+    const allEntries = Array.from(glob.scanSync({ cwd: fullDirPath, onlyFiles: false })).sort();
     const dirs = allEntries.filter((entry) => !files.includes(entry));
     return { files, dirs };
   }
@@ -302,17 +308,19 @@ export class Executor {
     filePath: string,
     content: string | object,
     { overwrite = true, silent = false }: { overwrite?: boolean; silent?: boolean } = {},
-  ): Promise<FileContent> {
+  ): Promise<WrittenFileContent> {
     const writePath = this.getPath(filePath);
     const dir = path.dirname(writePath);
     if (!(await FileSys.dirExists(dir))) await mkdir(dir, { recursive: true });
     let contentStr = typeof content === "string" ? content : JsonFormatter.stringify(content, writePath);
+    let written = true;
 
     if (await FileSys.fileExists(writePath)) {
       const currentContent = await FileSys.readText(writePath);
       if (currentContent === contentStr || !overwrite) {
         this.logger.verbose(`File ${writePath} is unchanged`);
         contentStr = currentContent;
+        written = false;
       } else {
         await FileSys.writeText(writePath, contentStr);
         if (Logger.isVerbose()) this.logger.rawLog(chalk.yellow(`File Update: ${filePath}`));
@@ -321,7 +329,7 @@ export class Executor {
       await FileSys.writeText(writePath, contentStr);
       if (!silent) this.logger.rawLog(chalk.green(`File Create: ${filePath}`));
     }
-    return { filePath: writePath, content: contentStr };
+    return { filePath: writePath, content: contentStr, written };
   }
   async writeJson(filePath: string, content: object) {
     await this.writeFile(filePath, content);
@@ -418,7 +426,7 @@ export class Executor {
     },
     dict: { [key: string]: string } = {},
     options: { [key: string]: unknown } = {},
-  ): Promise<FileContent | null> {
+  ): Promise<WrittenFileContent | null> {
     const convertPath = (target: string) =>
       Object.entries(dict).reduce(
         (converted, [key, value]) => converted.replace(new RegExp(`__${key}__`, "g"), value),
@@ -451,11 +459,13 @@ export class Executor {
     } else if (staticTemplateFileExtensions.has(path.extname(targetPath).toLowerCase())) {
       const convertedTargetPath = convertPath(targetPath);
       const writePath = this.getPath(convertedTargetPath);
+      if (!overwrite && (await FileSys.fileExists(writePath)))
+        return { filePath: writePath, content: "", written: false };
       const dirname = path.dirname(writePath);
       if (!(await FileSys.dirExists(dirname))) await mkdir(dirname, { recursive: true });
       await copyFile(templatePath, writePath);
       this.logger.verbose(`Apply template ${templatePath} to ${convertedTargetPath}`);
-      return { filePath: writePath, content: "" };
+      return { filePath: writePath, content: "", written: true };
     } else return null;
   }
   async _applyTemplate({
@@ -472,7 +482,7 @@ export class Executor {
     dict?: { [key: string]: string };
     options?: { [key: string]: unknown };
     overwrite?: boolean;
-  }): Promise<FileContent[]> {
+  }): Promise<WrittenFileContent[]> {
     const templateRoot = await this.#resolveTemplateRoot();
     const templatePath = `${templateRoot}${template ? `/${template}` : ""}`;
     if ((await stat(templatePath)).isFile()) {
@@ -486,7 +496,7 @@ export class Executor {
         dict,
         options,
       );
-      return fileContent ? [fileContent] : ([] as FileContent[]);
+      return fileContent ? [fileContent] : ([] as WrittenFileContent[]);
     } else {
       const subdirs = await readDirEntries(templatePath);
       const fileContents = (
@@ -504,7 +514,7 @@ export class Executor {
                 dict,
                 options,
               );
-              return fileContent ? [fileContent] : ([] as FileContent[]);
+              return fileContent ? [fileContent] : ([] as WrittenFileContent[]);
             } else
               return await this._applyTemplate({
                 basePath: path.join(basePath, subdir),
@@ -539,7 +549,7 @@ export class Executor {
     overwrite?: boolean;
   }): Promise<FileContent[]> {
     const fileContents = await this._applyTemplate({ ...options, dict: withCapitalizedDict(options.dict) });
-    await this.#formatAppliedTemplate(fileContents);
+    await this.#formatAppliedTemplate(fileContents.filter((fileContent) => fileContent.written));
     return fileContents;
   }
 
@@ -554,7 +564,7 @@ export class Executor {
       const { fixed } = await this.getLinter().fixFiles(filePaths);
       if (fixed.length > 0) this.logger.verbose(`Formatted ${fixed.length} scaffolded file(s)`);
     } catch (err) {
-      this.logger.verbose(`Skipped formatting scaffolded files: ${err instanceof Error ? err.message : String(err)}`);
+      this.logger.verbose(`Skipped formatting scaffolded files: ${toError(err).message}`);
     }
   }
   // Async so `typescript` (~65MB resident) loads only in the commands that typecheck.
@@ -572,7 +582,7 @@ export class Executor {
   }
   async typeCheckAsync(filePath: string) {
     const path = this.getPath(filePath);
-    const entry = await this.#resolveTypecheckWorkerEntry();
+    const entry = await ProjectTypecheck.workerEntry(process.cwd());
     const proc = Bun.spawn([process.execPath, entry], {
       cwd: this.cwdPath,
       env: {
@@ -603,18 +613,6 @@ export class Executor {
       message: result.message,
     };
   }
-  async #resolveTypecheckWorkerEntry() {
-    const dirname = getDirname(import.meta.url);
-    const candidates = [
-      path.join(process.cwd(), "pkgs/@akanjs/devkit/typecheck/typecheck.proc.ts"),
-      path.join(process.cwd(), "node_modules/@akanjs/devkit/typecheck/typecheck.proc.ts"),
-      path.join(dirname, "typecheck/typecheck.proc.ts"),
-      path.join(dirname, "typecheck.proc.js"),
-      path.join(dirname, "typecheck.proc.ts"),
-    ];
-    for (const candidate of candidates) if (await Bun.file(candidate).exists()) return candidate;
-    throw new Error(`[devkit] typecheck worker entry not found; looked in: ${candidates.join(", ")}`);
-  }
   getLinter() {
     this.linter ??= new Linter(this.cwdPath);
     return this.linter;
@@ -662,9 +660,14 @@ export class WorkspaceExecutor extends Executor {
   } = {}) {
     return new WorkspaceExecutor({ workspaceRoot, repoName });
   }
+  /** The public env a native build was told to reproduce (`--public-env`): it outranks `.env`, which outranks the rest. */
+  static publicEnvPin: Record<string, string> | null = null;
   static getBaseDevEnv(envPath?: string) {
     // Bun auto-loads .env, so we use process.env directly
-    const sourceEnv = envPath ? { ...process.env, ...parseEnvFile(envPath) } : process.env;
+    const sourceEnv = {
+      ...(envPath ? { ...process.env, ...parseEnvFile(envPath) } : process.env),
+      ...WorkspaceExecutor.publicEnvPin,
+    };
 
     const appName = sourceEnv.AKAN_PUBLIC_APP_NAME;
     const workspaceRoot = sourceEnv.AKAN_WORKSPACE_ROOT;

package/frontendBuild/csrArtifactBuilder.ts

@@ -61,8 +61,9 @@ export class CsrArtifactBuilder {
       ).flat(),
     );
 
+    const options = CsrArtifactBuilder.bundleOptions(this.#app, this.#command, akanConfig.optimizeImports);
     const result = await Bun.build({
-      ...CsrArtifactBuilder.bundleOptions(this.#app, this.#command, akanConfig.optimizeImports),
+      ...options,
       entrypoints: htmlBasePaths.map((basePath) => this.#generatedPath(CsrArtifactBuilder.htmlFilename(basePath))),
       files: generatedFiles,
       root: this.#generatedDir,
@@ -75,6 +76,7 @@ export class CsrArtifactBuilder {
     }
 
     await this.#inlineCsrArtifacts(cssAssets);
+    if (this.#command === "build") await CsrArtifactBuilder.writePublicEnv(this.#app, options.define);
     this.#app.verbose(`[csr-build] output -> ${this.#outputDir}`);
     return { outputDir: this.#outputDir };
   }
@@ -92,6 +94,21 @@ export class CsrArtifactBuilder {
     };
   }
 
+  /** Where a build records the `AKAN_PUBLIC_*` it inlined, which nothing in the minified bundle names. */
+  static publicEnvPath(app: App) {
+    return path.join(app.dist.cwdPath, ".akan", "artifact", "csr-public-env.json");
+  }
+
+  static async writePublicEnv(app: App, define: Record<string, string>) {
+    const prefix = "process.env.";
+    const publicEnv = Object.fromEntries(
+      Object.entries(define)
+        .filter(([key]) => key.startsWith(`${prefix}AKAN_PUBLIC_`))
+        .map(([key, value]) => [key.slice(prefix.length), JSON.parse(value) as unknown]),
+    );
+    await Bun.write(CsrArtifactBuilder.publicEnvPath(app), `${JSON.stringify(publicEnv, null, 2)}\n`);
+  }
+
   /** The routes one basePath's HTML boots: its own plus every route outside any basePath, matching `bootCsr`. */
   static pageEntriesForBasePath(pageEntries: PageEntry[], basePath: string, basePaths: string[]): PageEntry[] {
     return CsrEntryFiles.pageEntriesForBasePath(pageEntries, basePath, basePaths);

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;
   }