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

package/akanApp/akanApp.host.ts

@@ -104,6 +104,9 @@ export class AkanAppHost {
   #backendGaveUp = false;
   #backendLifecycleState: BackendLifecycleState = "stopped";
   #pendingRestartReason: BackendRestartReason | null = null;
+  //? One replacement at a time: `#stopBackend` clears `#backend` only once the old process exits, so a second restart
+  //? inside that wait signals the same pid and spawns a second backend, and the one the host stops tracking keeps the port.
+  #backendRestart: Promise<void> | null = null;
   #pendingRecycle: {
     message: Extract<BuilderMessage, { type: "invalidate" }>;
     refreshConfig: boolean;
@@ -181,8 +184,10 @@ export class AkanAppHost {
     this.#cancelIdleSuspend();
     this.#stopIdleWatcher();
     this.#clearRestartTimers();
+    this.#pendingRestartReason = null;
     // Before the backend goes away, while it can still receive the answer.
     this.#failPendingBuilderMessages("dev server is shutting down");
+    await this.#backendRestart;
     await this.#stopBackend();
     this.#stopBuilder();
     return this;
@@ -202,6 +207,11 @@ export class AkanAppHost {
     return await createTunnel(type, { app: this.app, environment });
   }
   #startBackend(startStatus: { generation?: number; files: string[] } | null = null) {
+    if (this.#stopping) return;
+    if (this.#backend) {
+      this.logger.warn(`backend pid=${this.#backend.pid} is still running; not starting a second one`);
+      return;
+    }
     // Before the spawn: the new backend numbers its requests from 1 again, so old answers must not reach it.
     this.#builderRequests.startGeneration();
     this.#discardPendingBuilderMessages("the backend restarted while the builder was away");
@@ -386,10 +396,18 @@ export class AkanAppHost {
     if (this.#restartTimer) clearTimeout(this.#restartTimer);
     this.#restartTimer = setTimeout(() => {
       this.#restartTimer = null;
+      this.#backendRestart ??= this.#drainBackendRestarts().finally(() => {
+        this.#backendRestart = null;
+      });
+    }, BACKEND_RESTART_DEBOUNCE_MS);
+  }
+  //? A reason that arrived during a restart runs after it; one whose debounce is still pending waits for its timer.
+  async #drainBackendRestarts() {
+    while (this.#pendingRestartReason && !this.#restartTimer && !this.#stopping) {
       const next = this.#pendingRestartReason;
       this.#pendingRestartReason = null;
-      if (next) void this.#restartBackend(next);
-    }, BACKEND_RESTART_DEBOUNCE_MS);
+      await this.#restartBackend(next);
+    }
   }
   async #restartBackend(reason: BackendRestartReason) {
     this.logger.verbose(
@@ -719,6 +737,7 @@ export class AkanAppHost {
     return !!(
       this.#pendingRecycle ||
       this.#restartTimer ||
+      this.#backendRestart ||
       this.#backendRecoveryTimer ||
       this.#builderRecoveryTimer ||
       this.#rssRecycleReason
@@ -1053,6 +1072,7 @@ export class AkanAppHost {
     this.#clearRestartTimers();
     this.#builderRecoveryAttempts = 0;
     this.#pendingRestartReason = null;
+    await this.#backendRestart;
     this.#lastGoodFrontend = {};
     this.#buildStatusByPhase.clear();
     this.#pendingBuildStatusReplay = [];

package/akanConfig/akanBin.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import { AkanBin } from "./akanBin";
+
+const owner = "apps/portal/akan.config.ts";
+const sha256 = "A".repeat(64);
+
+describe("AkanBin.parse", () => {
+  test("takes a download checked by its hash, or a file relative to the declaring folder", () => {
+    expect(
+      AkanBin.parse(
+        {
+          ffmpeg: {
+            "linux-x64": { url: "https://files.test/ffmpeg-linux64-lgpl.tar.xz", sha256, file: "./ffmpeg\\bin/ffmpeg" },
+            "darwin-arm64": { path: "tools/ffmpeg" },
+          },
+        },
+        owner,
+        "/repo/apps/portal",
+      ),
+    ).toEqual({
+      ffmpeg: {
+        "linux-x64": {
+          url: "https://files.test/ffmpeg-linux64-lgpl.tar.xz",
+          sha256: "a".repeat(64),
+          file: "ffmpeg/bin/ffmpeg",
+        },
+        "darwin-arm64": { path: path.resolve("/repo/apps/portal/tools/ffmpeg") },
+      },
+    });
+    expect(AkanBin.parse(undefined, owner, "/repo/apps/portal")).toEqual({});
+  });
+
+  test("names the declaration that is wrong", () => {
+    const parse = (bin: unknown) => () => AkanBin.parse(bin, owner, "/repo/apps/portal");
+    expect(parse(["ffmpeg"])).toThrow(`${owner}: bin maps each executable's name`);
+    expect(parse({ "../ffmpeg": {} })).toThrow("bin.../ffmpeg is not a file name");
+    expect(parse({ ffmpeg: { "darwin-universal": { path: "x" } } })).toThrow(
+      "bin.ffmpeg.darwin-universal is not one of darwin-arm64",
+    );
+    expect(parse({ ffmpeg: { "linux-x64": { url: "https://x.test/ffmpeg", sha256, path: "x" } } })).toThrow(
+      "takes either url and sha256, or path",
+    );
+    expect(parse({ ffmpeg: { "linux-x64": { url: "ftp://x.test/ffmpeg", sha256 } } })).toThrow(
+      "url must be an http(s) address",
+    );
+    expect(parse({ ffmpeg: { "linux-x64": { url: "https://x.test/ffmpeg", sha256: "abc" } } })).toThrow(
+      "sha256 must be the downloaded file's 64-digit hex digest",
+    );
+    expect(parse({ ffmpeg: { "linux-x64": { path: "ffmpeg", sha256 } } })).toThrow("a path source downloads nothing");
+    expect(parse({ ffmpeg: { "linux-x64": { url: "https://x.test/ffmpeg.zip", sha256 } } })).toThrow(
+      "names an archive: file picks the executable inside it",
+    );
+    expect(parse({ ffmpeg: { "linux-x64": { path: "ffmpeg", file: "bin/ffmpeg" } } })).toThrow(
+      "file picks the executable out of an archive",
+    );
+    expect(parse({ ffmpeg: { "linux-x64": { path: "ffmpeg.tar.gz", file: "../ffmpeg" } } })).toThrow(
+      "file must be a path inside the archive",
+    );
+    expect(parse({ ffmpeg: { "linux-x64": { path: "ffmpeg", mode: 755 } } })).toThrow("unknown key mode");
+  });
+});

package/akanConfig/akanBin.ts

@@ -0,0 +1,78 @@
+import path from "node:path";
+import {
+  type AkanBinConfig,
+  type AkanBinPathSource,
+  type AkanBinSource,
+  type AkanBinUrlSource,
+  type BinPlatform,
+  binPlatforms,
+} from "./types";
+
+//* Checked when the config loads, and a `path` source is made absolute against the folder that declares it: a lib's
+//* relative path has to find its file from every app that carries it.
+export class AkanBin {
+  static readonly archive = /\.(zip|tar\.gz|tgz|tar\.xz|txz|tar\.bz2|tbz2|tar)$/i;
+  static readonly fileName = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+  static parse(declared: unknown, owner: string, baseDir: string): AkanBinConfig {
+    if (declared === undefined) return {};
+    if (!declared || typeof declared !== "object" || Array.isArray(declared))
+      throw new Error(`${owner}: bin maps each executable's name to its platforms`);
+    return Object.fromEntries(
+      Object.entries(declared).map(([name, platforms]) => [name, AkanBin.#platforms(name, platforms, owner, baseDir)]),
+    );
+  }
+
+  static isArchive(source: AkanBinSource): boolean {
+    return AkanBin.archive.test("url" in source ? new URL(source.url).pathname : source.path);
+  }
+
+  static #platforms(name: string, platforms: unknown, owner: string, baseDir: string) {
+    if (!AkanBin.fileName.test(name)) throw new Error(`${owner}: bin.${name} is not a file name`);
+    if (!platforms || typeof platforms !== "object" || Array.isArray(platforms))
+      throw new Error(`${owner}: bin.${name} maps platforms (${binPlatforms.join(", ")}) to where the file comes from`);
+    const resolved: { [platform in BinPlatform]?: AkanBinSource } = {};
+    for (const [platform, source] of Object.entries(platforms)) {
+      if (!(binPlatforms as readonly string[]).includes(platform))
+        throw new Error(`${owner}: bin.${name}.${platform} is not one of ${binPlatforms.join(", ")}`);
+      resolved[platform as BinPlatform] = AkanBin.#source(`${owner}: bin.${name}.${platform}`, source, baseDir);
+    }
+    return resolved;
+  }
+
+  static #source(at: string, source: unknown, baseDir: string): AkanBinSource {
+    if (!source || typeof source !== "object" || Array.isArray(source))
+      throw new Error(`${at} must be { url, sha256 } or { path }`);
+    const { url, sha256, path: localPath, file, ...rest } = source as Record<string, unknown>;
+    const extra = Object.keys(rest);
+    if (extra.length) throw new Error(`${at}: unknown key ${extra.join(", ")}`);
+    if ((url === undefined) === (localPath === undefined))
+      throw new Error(`${at} takes either url and sha256, or path`);
+    const resolved =
+      url !== undefined ? AkanBin.#urlSource(at, url, sha256) : AkanBin.#pathSource(at, localPath, sha256, baseDir);
+    const archive = AkanBin.isArchive(resolved);
+    if (file === undefined) {
+      if (archive) throw new Error(`${at} names an archive: file picks the executable inside it`);
+      return resolved;
+    }
+    if (!archive) throw new Error(`${at}: file picks the executable out of an archive, and this source is none`);
+    const parts = typeof file === "string" ? file.split(/[\\/]/).filter((part) => part && part !== ".") : [];
+    if (!parts.length || path.isAbsolute(file as string) || parts.includes(".."))
+      throw new Error(`${at}: file must be a path inside the archive (got ${JSON.stringify(file)})`);
+    return { ...resolved, file: parts.join("/") };
+  }
+
+  static #urlSource(at: string, url: unknown, sha256: unknown): AkanBinUrlSource {
+    if (typeof url !== "string" || !URL.canParse(url) || !/^https?:$/.test(new URL(url).protocol))
+      throw new Error(`${at}: url must be an http(s) address`);
+    if (typeof sha256 !== "string" || !/^[0-9a-f]{64}$/i.test(sha256))
+      throw new Error(`${at}: sha256 must be the downloaded file's 64-digit hex digest`);
+    return { url, sha256: sha256.toLowerCase() };
+  }
+
+  static #pathSource(at: string, localPath: unknown, sha256: unknown, baseDir: string): AkanBinPathSource {
+    if (typeof localPath !== "string" || !localPath) throw new Error(`${at}: path must name a file`);
+    if (sha256 !== undefined) throw new Error(`${at}: sha256 checks a download, and a path source downloads nothing`);
+    return { path: path.resolve(baseDir, localPath) };
+  }
+}

package/akanConfig/akanConfig.test.ts

@@ -6,7 +6,7 @@ import { fileURLToPath } from "node:url";
 import { AppExecutor, WorkspaceExecutor } from "../executors";
 import type { PackageJson } from "../types";
 import { AkanAppConfig, AkanLibConfig, deriveDefaultAppId } from "./akanConfig";
-import type { DeepPartial, LibConfigResult } from "./types";
+import type { LibConfigInput } from "./types";
 
 const akanPackageJson = JSON.parse(
   fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "../../../akanjs/package.json"), "utf8"),
@@ -172,6 +172,75 @@ describe("AkanAppConfig", () => {
     expect(new AkanAppConfig(app, [], packageJson, { web: true }, baseDevEnv).web).toEqual({ ssr: true, csr: true });
   });
 
+  test("writes the image env from getProductionEnv, one ENV line per key in its order", () => {
+    const config = new AkanAppConfig(
+      app,
+      [],
+      packageJson,
+      { routes: [{ basePath: "admin", domains: {} }], web: false, database: { modes: ["single", "cluster"] } },
+      baseDevEnv,
+    );
+
+    expect(config.getProductionEnv()).toEqual({
+      PORT: "8282",
+      NODE_ENV: "production",
+      AKAN_PUBLIC_REPO_NAME: "akanjs",
+      AKAN_PUBLIC_SERVE_DOMAIN: "akanjs.com",
+      AKAN_PUBLIC_APP_NAME: "portal",
+      AKAN_PUBLIC_ENV: "debug",
+      AKAN_PUBLIC_BASE_PATHS: "admin",
+      AKAN_PUBLIC_DEFAULT_LOCALE: "en",
+      AKAN_PUBLIC_LOCALES: config.i18n.locales.join(","),
+      AKAN_PUBLIC_API_PREFIX: "/api",
+      AKAN_PUBLIC_WS_PREFIX: "/ws",
+      AKAN_PUBLIC_OPERATION_MODE: "cloud",
+      AKAN_DATABASE_MODES: "single,cluster",
+      AKAN_LOG_TO_FILE: "0",
+      AKAN_SSR: "false",
+      AKAN_CSR: "false",
+    });
+    const envBlock = Object.entries(config.getProductionEnv())
+      .map(([key, value]) => `ENV ${key}=${value}`)
+      .join("\n");
+    expect(config.dockerfile).toContain(`COPY . .\n${envBlock}\nCMD ["bun","main.js"]`);
+  });
+
+  test("writes the Dockerfile instructions it wrote before its env came from getProductionEnv", () => {
+    //? 9adfb95c's output for this config; only the blank lines its empty interpolations left are gone since.
+    const before = [
+      "FROM oven/bun:1-slim",
+      "RUN apt-get update && apt-get upgrade -y && apt-get install -y --no-install-recommends ca-certificates tzdata && rm -rf /var/lib/apt/lists/*",
+      "RUN ln -sf /usr/share/zoneinfo/Asia/Seoul /etc/localtime",
+      "ARG TARGETARCH",
+      "",
+      "RUN mkdir -p /workspace",
+      "WORKDIR /workspace",
+      "COPY ./package.json ./package.json",
+      "RUN bun install --production",
+      "",
+      "COPY . .",
+      "ENV PORT=8282",
+      "ENV NODE_ENV=production",
+      "ENV AKAN_PUBLIC_REPO_NAME=akanjs",
+      "ENV AKAN_PUBLIC_SERVE_DOMAIN=akanjs.com",
+      "ENV AKAN_PUBLIC_APP_NAME=portal",
+      "ENV AKAN_PUBLIC_ENV=debug",
+      "",
+      "ENV AKAN_PUBLIC_DEFAULT_LOCALE=en",
+      "ENV AKAN_PUBLIC_LOCALES=en,ko",
+      "ENV AKAN_PUBLIC_API_PREFIX=/api",
+      "ENV AKAN_PUBLIC_WS_PREFIX=/ws",
+      "ENV AKAN_PUBLIC_OPERATION_MODE=cloud",
+      "ENV AKAN_DATABASE_MODES=single",
+      "ENV AKAN_LOG_TO_FILE=0",
+      "",
+      'CMD ["bun","main.js"]',
+    ];
+    const lines = (text: string) => text.split("\n").filter((line) => line !== "");
+
+    expect(lines(new AkanAppConfig(app, [], packageJson, {}, baseDevEnv).dockerfile)).toEqual(lines(before.join("\n")));
+  });
+
   test("refuses a csr-less build that ships a mobile app", () => {
     expect(
       () => new AkanAppConfig(app, [], packageJson, { web: { csr: false }, mobile: { appName: "portal" } }, baseDevEnv),
@@ -458,6 +527,84 @@ describe("AkanAppConfig", () => {
     });
   });
 
+  test("gives every target the mobile-wide updates, a target overriding a field", () => {
+    const updates = { url: "https://releases.example.com/portal", publicKey: "key=" };
+    const config = new AkanAppConfig(
+      app,
+      [],
+      packageJson,
+      {
+        mobile: {
+          updates,
+          targets: { default: {}, pilot: { updates: { channel: "pilot" } } },
+        },
+      },
+      baseDevEnv,
+    );
+
+    expect(config.mobile.targets.default?.updates).toEqual(updates);
+    expect(config.mobile.targets.pilot?.updates).toEqual({ ...updates, channel: "pilot" });
+    expect(
+      () =>
+        new AkanAppConfig(
+          app,
+          [],
+          packageJson,
+          { mobile: { targets: { pilot: { updates: { channel: "pilot" } } } } },
+          baseDevEnv,
+        ),
+    ).toThrow("mobile.targets.pilot.updates in apps/portal/akan.config.ts has no url or publicKey");
+  });
+
+  test("merges the desktop settings field by field, the target winning", () => {
+    const config = new AkanAppConfig(
+      app,
+      [],
+      packageJson,
+      {
+        mobile: {
+          native: { desktop: { recovery: "reload", window: { fullscreen: true } } },
+          targets: { default: { native: { desktop: { window: { skipTaskbar: true } } } } },
+        },
+      },
+      baseDevEnv,
+    );
+
+    expect(config.mobile.targets.default?.native?.desktop).toEqual({
+      recovery: "reload",
+      window: { fullscreen: true, skipTaskbar: true },
+    });
+  });
+
+  test("merges the mobile-wide updates, push and privacy into each target field by field, the target winning", () => {
+    const publicKey = Buffer.alloc(32, 7).toString("base64");
+    const config = new AkanAppConfig(
+      app,
+      [],
+      packageJson,
+      {
+        mobile: {
+          updates: { url: "https://updates.example.com/portal", publicKey },
+          native: { push: { android: { color: "#ff5a5f" } }, privacy: { tracking: false } },
+          targets: {
+            default: {},
+            beta: {
+              updates: { channel: "beta" },
+              native: { push: { android: { smallIcon: "assets/noti.png" } } },
+            },
+          },
+        },
+      } as never,
+      baseDevEnv,
+    );
+
+    expect(config.mobile.targets.default?.updates).toEqual({ url: "https://updates.example.com/portal", publicKey });
+    expect(config.mobile.targets.beta).toMatchObject({
+      updates: { url: "https://updates.example.com/portal", publicKey, channel: "beta" },
+      native: { push: { android: { color: "#ff5a5f", smallIcon: "assets/noti.png" } }, privacy: { tracking: false } },
+    });
+  });
+
   test("refuses the Capacitor-era keys with the setting that replaces them", () => {
     const make = (mobile: Record<string, unknown>) => () =>
       new AkanAppConfig(app, [], packageJson, { mobile } as never, baseDevEnv);
@@ -587,12 +734,75 @@ describe("AkanAppConfig lib docker runs", () => {
   });
 });
 
+describe("AkanAppConfig trustedDependencies and bin", () => {
+  const sha256 = "b".repeat(64);
+  const libBin = { ffmpeg: { "linux-x64": { url: "https://files.test/ffmpeg.tar.xz", sha256, file: "bin/ffmpeg" } } };
+
+  test("the production package.json trusts the app's and its libs' packages, and nothing when none are named", () => {
+    const withTrusted = new AkanAppConfig(
+      app,
+      [],
+      packageJson,
+      { trustedDependencies: [" rclnodejs ", "sharp"] },
+      baseDevEnv,
+      [],
+      {
+        externalLibs: [],
+        trustedDependencies: ["sharp", "@serialport/bindings-cpp"],
+        docker: { preRuns: [], postRuns: [] },
+      },
+    );
+    expect(withTrusted.getProductionPackageJson().trustedDependencies).toEqual([
+      "rclnodejs",
+      "sharp",
+      "@serialport/bindings-cpp",
+    ]);
+    expect(new AkanAppConfig(app, [], packageJson, {}, baseDevEnv).getProductionPackageJson()).not.toHaveProperty(
+      "trustedDependencies",
+    );
+    expect(() => new AkanAppConfig(app, [], packageJson, { trustedDependencies: [""] }, baseDevEnv)).toThrow(
+      "apps/portal/akan.config.ts: trustedDependencies lists package names",
+    );
+  });
+
+  test("keeps the app's bin apart from each lib's, with paths made absolute where they were declared", () => {
+    const config = new AkanAppConfig(
+      { name: "portal", cwdPath: "/repo/apps/portal" } as never,
+      [],
+      packageJson,
+      { bin: { ffmpeg: { "darwin-arm64": { path: "tools/ffmpeg" } } } },
+      baseDevEnv,
+      [],
+      { externalLibs: [], docker: { preRuns: [], postRuns: [] }, bin: [{ lib: "media", bin: libBin }] },
+    );
+    expect(config.bin).toEqual({
+      ffmpeg: { "darwin-arm64": { path: path.resolve("/repo/apps/portal/tools/ffmpeg") } },
+    });
+    expect(config.libBins).toEqual([{ lib: "media", bin: libBin }]);
+    expect(
+      new AkanLibConfig({ name: "media", cwdPath: "/repo/libs/media" } as never, {
+        bin: { ffprobe: { "linux-x64": { path: "../../tools/ffprobe" } } },
+      }).bin,
+    ).toEqual({ ffprobe: { "linux-x64": { path: path.resolve("/repo/tools/ffprobe") } } });
+  });
+
+  test("reads them off every workspace lib config on load", async () => {
+    const config = await loadExtAppConfig(
+      "akan-config-libbin-",
+      "export default { trustedDependencies: ['sharp'] };\n",
+      `export default { trustedDependencies: ['rclnodejs'], bin: ${JSON.stringify(libBin)} };\n`,
+    );
+    expect(config.trustedDependencies).toEqual(["sharp", "rclnodejs"]);
+    expect(config.libBins).toEqual([{ lib: "extlib", bin: libBin }]);
+  });
+});
+
 describe("AkanLibConfig", () => {
   test("uses empty external libs by default and preserves explicit libs", () => {
     const lib = { name: "shared" } as never;
     expect(new AkanLibConfig(lib, {}).externalLibs).toEqual([]);
 
-    const config: DeepPartial<LibConfigResult> = {
+    const config: LibConfigInput = {
       externalLibs: ["firebase-admin"],
     };
     expect(new AkanLibConfig(lib, config).externalLibs).toEqual(["firebase-admin"]);