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

package/akanConfig/akanConfig.test.ts

@@ -518,10 +518,14 @@ describe("AkanAppConfig", () => {
       watchdog: { intervalMs: 10_000, failures: 5 },
     });
     expect(() => resolve({ env: { SLACK_WEBHOOK_URL: "https://hooks" } })).toThrow("SLACK_WEBHOOK_URL");
-    expect(() => resolve({ env: { AKAN_MODULES: "@edge" } })).toThrow("the carried server's stage owns");
+    for (const key of ["AKAN_MODULES", "AKAN_MCP", "AKAN_SHUTDOWN_TIMEOUT_MS"])
+      expect(() => resolve({ env: { [key]: "1" } })).toThrow(`sets ${key}, which the carried server's stage owns`);
     expect(() => resolve({ env: { PORT: 1 } })).toThrow("must be an object of strings");
     expect(() => resolve({ restart: 0 })).toThrow('must be "forever" or a count');
-    expect(() => resolve({ watchdog: { intervalMs: -1 } })).toThrow("watchdog in apps/");
+    for (const watchdog of [{ intervalMs: -1 }, null, 5, [], { interval: 5_000 }])
+      expect(() => resolve({ watchdog })).toThrow(
+        "native.desktop.server.watchdog in apps/portal/akan.config.ts must be",
+      );
   });
 
   test("an app without basePaths has one target, default, with no basePath and the section's settings", () => {
@@ -630,6 +634,30 @@ describe("AkanAppConfig", () => {
     ).toThrow("native.updates in apps/portal/akan.config.ts has no url or publicKeys.");
   });
 
+  test("refuses updates holding both publicKey and publicKeys, a target's own key beside the section's list included", () => {
+    const url = "https://releases.example.com/portal";
+    const resolve = (native: object) =>
+      new AkanAppConfig(app, [], packageJson, { native } as never, baseDevEnv).native.targets;
+
+    expect(() =>
+      resolve({
+        updates: { url, publicKeys: ["a="] },
+        targets: { store: {}, pilot: { updates: { publicKey: "p=" } } },
+      }),
+    ).toThrow(
+      "native.targets.pilot.updates in apps/portal/akan.config.ts has both publicKey and publicKeys, native.updates merged in",
+    );
+    expect(() => resolve({ updates: { url, publicKey: "a=", publicKeys: ["b="] } })).toThrow(
+      "native.updates in apps/portal/akan.config.ts has both publicKey and publicKeys: give one.",
+    );
+    expect(
+      resolve({
+        updates: { url, publicKeys: ["a="] },
+        targets: { store: {}, pilot: { updates: { publicKeys: ["p="] } } },
+      }).pilot.updates,
+    ).toEqual({ url, publicKeys: ["p="] });
+  });
+
   test("merges the desktop settings field by field, the target winning", () => {
     const config = new AkanAppConfig(
       app,
@@ -949,7 +977,7 @@ describe("pipeline and workspace keys in app and lib configs", () => {
       "export default { subspace: { subspaces: [] } };\n",
       "export default {};\n",
     );
-    expect(loading).rejects.toThrow("a workspace setting");
+    await expect(loading).rejects.toThrow("a workspace setting");
   });
 
   test("a lib takes neither a pipeline nor a subspace", async () => {
@@ -957,11 +985,29 @@ describe("pipeline and workspace keys in app and lib configs", () => {
     try {
       const lib = { name: "extlib", cwdPath: root } as never;
       fs.writeFileSync(path.join(root, "akan.config.ts"), "export default { pipeline: { stages: [] } };\n");
-      expect(AkanLibConfig.from(lib)).rejects.toThrow("which a lib does not take");
+      await expect(AkanLibConfig.from(lib)).rejects.toThrow("which a lib does not take");
       fs.writeFileSync(path.join(root, "akan.config.ts"), "export default { subspace: { subspaces: [] } };\n");
-      expect(AkanLibConfig.from(lib, { bustImportCache: true })).rejects.toThrow("a workspace setting");
+      await expect(AkanLibConfig.from(lib, { bustImportCache: true })).rejects.toThrow("a workspace setting");
     } finally {
       fs.rmSync(root, { recursive: true, force: true });
     }
   });
+
+  test("a lib's refused key fails the app's load instead of skipping the lib and its docker steps", async () => {
+    const loading = loadExtAppConfig(
+      "akan-config-lib-refused-",
+      "export default {};\n",
+      "export default { docker: { preRuns: ['apt-get install -y ffmpeg'] }, pipeline: { stages: [] } };\n",
+    );
+    await expect(loading).rejects.toThrow("libs/extlib/akan.config.ts declares `pipeline`, which a lib does not take");
+  });
+
+  test("a lib config that fails to load is still skipped with a warning, the app loading without it", async () => {
+    const config = await loadExtAppConfig(
+      "akan-config-lib-broken-",
+      "export default { externalLibs: ['shiki'] };\n",
+      'throw new Error("half-written");\nexport default {};\n',
+    );
+    expect(config.externalLibs).toEqual(["shiki"]);
+  });
 });

package/akanConfig/akanConfig.ts

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import type { ServerPolicy } from "@akanjs/native/api";
 import type { AkanPlugin } from "akanjs";
 import { DatabaseModes, normalizeRoutePrefix } from "akanjs/base";
 import { type AkanI18nConfig, resolveAkanI18nConfig } from "akanjs/common";
@@ -152,6 +153,8 @@ const dedupeDockerRuns = (runs: DockerRun[]): DockerRun[] => {
   return [...byKey.values()];
 };
 
+class LibConfigRefusal extends Error {}
+
 export class AkanAppConfig implements AppConfigResult {
   app: App;
   rootPackageJson: PackageJson;
@@ -285,6 +288,11 @@ export class AkanAppConfig implements AppConfigResult {
           throw new Error(
             `${where}.updates in ${configPath} has no url or publicKeys${named ? "; give them in native.updates or the target's own" : ""}.`,
           );
+        //? NativeConfig prefers publicKeys to publicKey, so a target's own key beside the section's list would be lost.
+        if (updates?.publicKey !== undefined && updates.publicKeys !== undefined)
+          throw new Error(
+            `${where}.updates in ${configPath} has both publicKey and publicKeys${named ? ", native.updates merged in: give one, in native.updates' own form when overriding its keys" : ": give one"}.`,
+          );
         AkanAppConfig.#assertFiles(own ?? {}, where, configPath);
         const {
           basePath: _basePath,
@@ -370,13 +378,16 @@ export class AkanAppConfig implements AppConfigResult {
       },
     };
   }
-  //? The stage owns these: the operation mode, the database mode and what is served are what make it the carried server.
+  //? The stage owns these: the operation mode, the database mode, what is served and the shutdown budget the shell's
+  //? quit waits on are what make it the carried server.
   static readonly #stagedServerEnv = new Set([
     "AKAN_PUBLIC_OPERATION_MODE",
     "AKAN_DATABASE_MODE",
     "AKAN_DATABASE_MODES",
     "AKAN_SSR",
     "AKAN_CSR",
+    "AKAN_MCP",
+    "AKAN_SHUTDOWN_TIMEOUT_MS",
     "AKAN_MODULES",
   ]);
   static #desktopServerEnv(env: unknown, where: string, configPath: string): Record<string, string> {
@@ -395,19 +406,25 @@ export class AkanAppConfig implements AppConfigResult {
       );
     return env as Record<string, string>;
   }
-  static #desktopServerWatchdog(
-    watchdog: unknown,
-    where: string,
-    configPath: string,
-  ): { intervalMs: number; failures: number } | null {
+  //? The akan.config.ts shape, which takes `true` and fills in what is left out; the launcher reads what this returns
+  //? with serverPolicyOf in @akanjs/native, which devkit cannot load while it reads a config.
+  static #desktopServerWatchdog(watchdog: unknown, where: string, configPath: string): ServerPolicy["watchdog"] | null {
     if (watchdog === undefined || watchdog === false) return null;
-    const { intervalMs = 10_000, failures = 3 } = (watchdog === true ? {} : watchdog) as Record<string, unknown>;
-    const whole = (value: unknown) => Number.isInteger(value) && (value as number) > 0;
-    if ((watchdog !== true && !AkanAppConfig.#isPlainObject(watchdog)) || !whole(intervalMs) || !whole(failures))
+    const options = watchdog === true ? {} : watchdog;
+    const whole = (value: unknown) => value === undefined || (Number.isInteger(value) && (value as number) > 0);
+    if (
+      !AkanAppConfig.#isPlainObject(options) ||
+      Object.keys(options).some((key) => key !== "intervalMs" && key !== "failures") ||
+      !whole(options.intervalMs) ||
+      !whole(options.failures)
+    )
       throw new Error(
         `${where}.watchdog in ${configPath} must be true or { intervalMs, failures }, whole numbers from 1.`,
       );
-    return { intervalMs: intervalMs as number, failures: failures as number };
+    return {
+      intervalMs: (options.intervalMs as number | undefined) ?? 10_000,
+      failures: (options.failures as number | undefined) ?? 3,
+    };
   }
   static #platformIndexPath<T extends { indexPath?: string }>(section: T): T {
     const { indexPath: rawIndexPath, ...rest } = section;
@@ -685,6 +702,8 @@ CMD [${command.map((c) => `"${c}"`).join(",")}]`;
         LibExecutor.from(app, libName)
           .getConfig({ refresh: bustImportCache })
           .catch((error: unknown) => {
+            //? Skipping a refused lib config would build the image without its docker steps, and the build would pass.
+            if (error instanceof LibConfigRefusal) throw error;
             app.logger.warn(`Skipped libs/${libName}/akan.config.ts contributions: ${String(error)}`);
             return null;
           }),
@@ -843,11 +862,11 @@ export class AkanLibConfig implements LibConfigResult {
     const resolved = typeof configImp === "function" ? configImp(lib) : configImp;
     const { plugins, ...config } = (resolved ?? {}) as LibConfigDeclaration & { plugins?: AkanPlugin[] };
     if ("pipeline" in config)
-      throw new Error(
+      throw new LibConfigRefusal(
         `libs/${lib.name}/akan.config.ts declares \`pipeline\`, which a lib does not take: pipelines belong to apps and the workspace root, and a lib's build-time work goes in an akan build plugin.`,
       );
     if ("subspace" in config)
-      throw new Error(
+      throw new LibConfigRefusal(
         `libs/${lib.name}/akan.config.ts declares \`subspace\`, a workspace setting: it belongs in the workspace root akan.config.ts.`,
       );
     return new AkanLibConfig(lib, config, plugins ?? []);

package/akanConfig/akanWorkspaceConfig.test.ts

@@ -51,7 +51,7 @@ describe("AkanWorkspaceConfig", () => {
     expect(hostOf(undefined)).toBeNull();
     expect(hostOf({})).toBeNull();
     expect(hostOf({ host: "https://cloud.example.com/" })).toBe("https://cloud.example.com");
-    expect(hostOf({ host: "https://example.com/akasys//" })).toBe("https://example.com/akasys");
+    expect(hostOf({ host: "https://example.com/control//" })).toBe("https://example.com/control");
     expect(hostOf({ host: "http://localhost:8283" })).toBe("http://localhost:8283");
     expect(() => hostOf({ host: "http://cloud.example.com" })).toThrow("https only");
     expect(() => hostOf({ host: "cloud.example.com" })).toThrow("is not a URL");
@@ -59,21 +59,21 @@ describe("AkanWorkspaceConfig", () => {
     expect(() => hostOf({ host: "https://cloud.example.com", token: "x" })).toThrow("keys it does not take: token");
 
     const workspace = (cloudHost: string | null) => ({ getConfig: async () => ({ cloudHost }) });
-    expect(await GlobalConfig.hostFor(workspace("https://akasys.example.com"), "https://given.example.com")).toBe(
+    expect(await GlobalConfig.hostFor(workspace("https://control.example.com"), "https://given.example.com")).toBe(
       "https://given.example.com",
     );
-    expect(await GlobalConfig.hostFor(workspace("https://akasys.example.com"), null)).toBe(
-      "https://akasys.example.com",
+    expect(await GlobalConfig.hostFor(workspace("https://control.example.com"), null)).toBe(
+      "https://control.example.com",
     );
     expect(await GlobalConfig.hostFor(workspace(null))).toBe(GlobalConfig.akanCloudHost);
   });
 
   test("refuses app settings and a default export that is not an object", async () => {
     await withWorkspace({ "akan.config.ts": 'export default { docker: { image: "x" } };\n' }, async (workspace) => {
-      expect(AkanWorkspaceConfig.from(workspace)).rejects.toThrow("declares `docker`, which it does not take");
+      await expect(AkanWorkspaceConfig.from(workspace)).rejects.toThrow("declares `docker`, which it does not take");
     });
     await withWorkspace({ "akan.config.ts": "export default () => ({});\n" }, async (workspace) => {
-      expect(AkanWorkspaceConfig.from(workspace)).rejects.toThrow("must default-export a WorkspaceConfig object");
+      await expect(AkanWorkspaceConfig.from(workspace)).rejects.toThrow("must default-export a WorkspaceConfig object");
     });
   });
 });

package/akanConfig/akanWorkspaceConfig.ts

@@ -4,7 +4,7 @@ import type { WorkspaceExecutor } from "../executors";
 import { FileSys } from "../fileSys";
 import { AkanAppConfig } from "./akanConfig";
 
-/** The workspace root's own `akan.config.ts`: settings that belong to no app. Absent, it is an empty one. */
+/** The workspace root's own `akan.config.ts`: settings that belong to no app. */
 export class AkanWorkspaceConfig {
   static readonly fileName = "akan.config.ts";
   static readonly #keys = ["subspace", "pipeline", "cloud"];

package/applicationBuildRunner.test.ts

@@ -5,7 +5,9 @@ import path from "node:path";
 import { AkanAppConfig } from "./akanConfig";
 import { AKAN_BACKEND_MINIFY, AKAN_OPTIONAL_BACKEND_EXTERNALS, ApplicationBuildRunner } from "./applicationBuildRunner";
 import type { App } from "./commandDecorators";
-import { Executor } from "./executors";
+import { AppExecutor, Executor } from "./executors";
+import { bundleDefine } from "./frontendBuild/bundleDefine";
+import { createTempApp } from "./testHelpers";
 
 describe("ApplicationBuildRunner", () => {
   test("externalizes Akan optional backend dependencies", () => {
@@ -78,4 +80,34 @@ console.info(new SampleService().name);
       await rm(root, { recursive: true, force: true });
     }
   });
+
+  test("bakes into the route bundles the env their server env is, not the shell's that the root .env outranks", async () => {
+    const { root, workspace } = await createTempApp("portal");
+    const shellEnv = process.env.AKAN_PUBLIC_ENV;
+    const stoppedBeforePhases = (app: AppExecutor) => {
+      app.prepareCommand = async () => {
+        throw new Error("stopped before the phases");
+      };
+      return app;
+    };
+    const bakedEnv = (app: AppExecutor) =>
+      (bundleDefine(app, "build", "ssr") as { [key: string]: string })["process.env.AKAN_PUBLIC_ENV"];
+    try {
+      process.env.AKAN_PUBLIC_ENV = "main";
+      const app = stoppedBeforePhases(AppExecutor.from(workspace, "portal"));
+      await expect(new ApplicationBuildRunner(app).build()).rejects.toThrow("stopped before the phases");
+      expect(bakedEnv(app)).toBe(JSON.stringify("local"));
+
+      process.env.AKAN_PUBLIC_ENV = "main";
+      const desktop = stoppedBeforePhases(AppExecutor.from(workspace, "portal"));
+      await expect(new ApplicationBuildRunner(desktop, { environment: "debug" }).build()).rejects.toThrow(
+        "stopped before the phases",
+      );
+      expect(bakedEnv(desktop)).toBe(JSON.stringify("debug"));
+    } finally {
+      if (shellEnv === undefined) delete process.env.AKAN_PUBLIC_ENV;
+      else process.env.AKAN_PUBLIC_ENV = shellEnv;
+      await rm(root, { recursive: true, force: true });
+    }
+  });
 });

package/applicationBuildRunner.ts

@@ -100,13 +100,12 @@ export class ApplicationBuildRunner {
     // serial build is needed because of Bun.build is unstable for parallel build
     this.#spinner = spinner;
     const { web, assets, baseDevEnv } = await this.#app.getConfig();
+    const environment = this.#environment ?? baseDevEnv.env;
+    //? Bundles bake AKAN_PUBLIC_ENV from process.env, where the shell outranks the .env that picked the server env.
+    process.env.AKAN_PUBLIC_ENV = environment;
     //? Before any phase: a profile that would ship a secret stops the build, not the image after it.
     if (this.#profile)
-      await ServerEnvProfile.assertShippable({
-        envDir: this.#envDir,
-        environment: this.#environment ?? baseDevEnv.env,
-        profile: this.#profile,
-      });
+      await ServerEnvProfile.assertShippable({ envDir: this.#envDir, environment, profile: this.#profile });
     await this.#runPhase("prepare", "Preparing output directory", () => this.#app.prepareCommand("build"));
     if (!this.#fast) await this.#runPhase("typecheck", "Typechecking", () => this.typecheck());
     await this.#runPhase(

package/cloud/cloudApi.ts

@@ -1,4 +1,5 @@
 import type { Workspace } from "../commandDecorators";
+import { CloudHttpError } from "./cloudHttpError";
 import type { AccessToken, AccessTokenDto, HostConfig } from "./constants";
 import { GlobalConfig } from "./globalConfig";
 
@@ -25,7 +26,7 @@ class HttpClient {
     const response = await fetch(`${this.baseUrl}${url}`, {
       headers: { ...this.headers, ...headers },
     });
-    if (!response.ok) throw new Error(`Failed to download file: ${response.status} ${response.statusText}`);
+    if (!response.ok) throw await CloudHttpError.of(response, url);
     await Bun.write(localPath, response);
   }
   async post<T>(url: string, data: unknown, { headers, signal }: HttpRequestOptions = {}): Promise<T> {
@@ -42,9 +43,8 @@ class HttpClient {
   }
   // A missing route answers an HTML error page, so the status is read before the body is parsed as JSON.
   static async #body<T>(response: Response, url: string): Promise<T> {
-    const text = await response.text();
-    if (!response.ok) throw new Error(`${response.status} ${response.statusText} from ${url}: ${text.slice(0, 200)}`);
-    return JSON.parse(text) as T;
+    if (!response.ok) throw await CloudHttpError.of(response, url);
+    return JSON.parse(await response.text()) as T;
   }
   setHeaders(headers: Record<string, string>) {
     Object.assign(this.headers, headers);
@@ -71,10 +71,10 @@ export interface PipelineSecretSummary {
 }
 
 export interface PipelineSecretListing extends PipelineSecretSummary {
-  updatedBy: string;
+  updatedBy: string | null;
 }
 
-/** What akasys answers for an uploaded pack or a registered binary; a pack's release also says how it was taken. */
+/** What Akan Cloud answers for an uploaded pack or a registered binary; a pack's release also says how it was taken. */
 export interface CloudRecord {
   id: string;
   status?: string;
@@ -113,10 +113,19 @@ export interface TunnelSummary {
 }
 
 export class CloudApi {
-  /** The HTTP status an error from this client carries, or null for one without (a dropped connection, a timeout). */
-  static statusOf(error: unknown) {
-    const status = Number(/(?:^|: )(\d{3}) /.exec(error instanceof Error ? error.message : String(error))?.[1]);
-    return Number.isNaN(status) ? null : status;
+  //* The project's guards answer by status: 401 no sign-in it accepts, 403 not allowed, 400 a refused request.
+  static refusal(error: unknown, who: string, { unavailable }: { unavailable?: string } = {}) {
+    if (!(error instanceof CloudHttpError)) return error;
+    if (error.status === 401)
+      return new Error("The server did not accept your sign-in: run `akan login`, then try again.", { cause: error });
+    if (error.status === 403) return new Error(`The project refused: ${who}.`, { cause: error });
+    if (error.status === 400)
+      return new Error(`The project refused the request${error.error ? `: ${error.error}` : ""}.`, { cause: error });
+    //? A proxy, or the gateway with no replica ready, answers 503 too; only the server's own names a domain Err key.
+    const { errKey } = error;
+    if (error.status === 503 && unavailable && errKey && errKey !== "base.error.serverUnavailable")
+      return new Error(`${unavailable}: ${errKey}.`, { cause: error });
+    return error;
   }
   readonly #api: HttpClient;
   #accessToken: AccessToken | null = null;
@@ -184,9 +193,8 @@ export class CloudApi {
       target: string;
       distribution: AppBinaryDistribution;
       bundle: Blob;
-      /** The pack staged with UpdatePackUpload.stage; the multipart `pack` is for a server older than staging. */
-      packUploadId?: string;
-      pack?: Blob;
+      /** The pack staged with UpdatePackUpload.stage. */
+      packUploadId: string;
       channel?: string;
     },
   ) {
@@ -194,8 +202,7 @@ export class CloudApi {
     for (const key of ["appName", "target", "distribution"] as const) formData.append(key, binary[key]);
     if (binary.channel) formData.append("channel", binary.channel);
     formData.append("bundle", binary.bundle, "bundle.json");
-    if (binary.packUploadId) formData.append("packUploadId", binary.packUploadId);
-    if (binary.pack) formData.append("pack", binary.pack, "pack.tgz");
+    formData.append("packUploadId", binary.packUploadId);
     return await this.#api.post<CloudRecord>(`/registerAppBinary/${encodeURIComponent(devProjectId)}`, formData, {
       signal: AbortSignal.timeout(11 * 60_000),
     });

package/cloud/cloudHttpError.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, test } from "bun:test";
+import { CloudHttpError } from "./cloudHttpError";
+
+describe("CloudHttpError", () => {
+  test("reads the server's Err key from the whole body, while the message keeps 200 characters of it", () => {
+    const body = JSON.stringify({ details: "x".repeat(300), error: "release.error.uploadEmbedded", statusCode: 409 });
+    const error = new CloudHttpError(409, "Conflict", "/commitUpdateUpload/p", body);
+
+    expect(error.status).toBe(409);
+    expect(error.errKey).toBe("release.error.uploadEmbedded");
+    expect(error.message).toBe(`409 Conflict from /commitUpdateUpload/p: ${body.slice(0, 200)}`);
+    expect(CloudHttpError.statusOf(error)).toBe(409);
+    expect(CloudHttpError.statusOf(new Error("409 Conflict from /x: {}"))).toBeNull();
+  });
+
+  test("names no Err key for a proxy's page or an error that is not one", () => {
+    expect(new CloudHttpError(503, "Service Unavailable", "/x", "<html>503</html>").errKey).toBeNull();
+    const plain = new CloudHttpError(400, "Bad Request", "/x", '{"error":"Bad Request"}');
+    expect(plain.error).toBe("Bad Request");
+    expect(plain.errKey).toBeNull();
+  });
+
+  test("takes Retry-After as seconds or as a date, and nothing else", () => {
+    expect(CloudHttpError.retryAfterMs("7")).toBe(7000);
+    expect(CloudHttpError.retryAfterMs(new Date(Date.now() + 60_000).toUTCString())).toBeGreaterThan(55_000);
+    expect(CloudHttpError.retryAfterMs(new Date(Date.now() - 60_000).toUTCString())).toBe(0);
+    expect(CloudHttpError.retryAfterMs("soon")).toBeNull();
+    expect(CloudHttpError.retryAfterMs(null)).toBeNull();
+    const headers = new Headers({ "Retry-After": "3" });
+    expect(new CloudHttpError(429, "Too Many Requests", "/x", "", headers).retryAfterMs).toBe(3000);
+  });
+});

package/cloud/cloudHttpError.ts

@@ -0,0 +1,54 @@
+import { isRecord } from "akanjs/common";
+
+//? The body is kept whole for reading the server's answer; only the message is cut, as it lands in a terminal.
+export class CloudHttpError extends Error {
+  static readonly #errKey = /^[\w$-]+\.error\.[\w$-]+$/;
+
+  override readonly name = "CloudHttpError";
+
+  constructor(
+    readonly status: number,
+    readonly statusText: string,
+    readonly url: string,
+    readonly body: string,
+    readonly headers: Headers = new Headers(),
+  ) {
+    super(`${status} ${statusText} from ${url}: ${body.slice(0, 200)}`);
+  }
+
+  static async of(response: Response, url: string) {
+    return new CloudHttpError(response.status, response.statusText, url, await response.text(), response.headers);
+  }
+
+  static statusOf(error: unknown) {
+    return error instanceof CloudHttpError ? error.status : null;
+  }
+
+  /** The `error` of a JSON refusal: an Err key from the server itself, or whatever a proxy put there. */
+  get error(): string | null {
+    try {
+      const parsed: unknown = JSON.parse(this.body);
+      return isRecord(parsed) && typeof parsed.error === "string" ? parsed.error : null;
+    } catch {
+      return null;
+    }
+  }
+
+  /** `error` when it is an Err key (`release.error.uploadCommitInProgress`), which only the server's own answer names. */
+  get errKey(): string | null {
+    const { error } = this;
+    return error && CloudHttpError.#errKey.test(error) ? error : null;
+  }
+
+  get retryAfterMs(): number | null {
+    return CloudHttpError.retryAfterMs(this.headers.get("retry-after"));
+  }
+
+  /** Retry-After in milliseconds from now: whole seconds, or an HTTP date. */
+  static retryAfterMs(header: string | null): number | null {
+    const value = header?.trim() ?? "";
+    if (!value) return null;
+    const ms = /^\d+$/.test(value) ? Number(value) * 1000 : Date.parse(value) - Date.now();
+    return Number.isFinite(ms) ? Math.max(0, ms) : null;
+  }
+}

package/cloud/cloudUpdates.ts

@@ -0,0 +1,138 @@
+import path from "node:path";
+import { Logger } from "akanjs/common";
+import type { NativeEnv } from "../akanConfig";
+import type { App } from "../commandDecorators";
+import { ExitCodeError } from "../commandDecorators/exitCodeError";
+import { type MobilePlatform, resolveMobileTargets } from "../mobile/mobileTarget";
+import { NativeApp } from "../mobile/nativeApp";
+import { NativePublicEnv } from "../mobile/nativePublicEnv";
+import { type NativeUpdatePack, UpdatePackFolder } from "../mobile/updatePackFolder";
+import { type AppBinaryDistribution, CloudApi } from "./cloudApi";
+import { UpdatePackUpload } from "./updatePackUpload";
+
+//* A phone app's over-the-air updates through an Akan Cloud project, which keeps the signing key: a pack uploaded for
+//* it to sign and publish, and the store build a pack of the same commit is embedded in.
+export class CloudUpdates {
+  constructor(
+    readonly cloudApi: CloudApi,
+    readonly devProjectId: string,
+  ) {}
+
+  /** The bundle.json the target's last `akan release-<platform>` wrote. */
+  static async storeBundlePath(app: App, target: string | undefined, platform: MobilePlatform) {
+    const [mobileTarget] = await resolveMobileTargets(app, target);
+    if (!mobileTarget) throw new Error(`Native target '${target}' was not found.`);
+    return path.join(new NativeApp(app, mobileTarget).outDir(platform), UpdatePackFolder.bundleFile);
+  }
+
+  /** A pack `akan pack-update` wrote, refused unless it is this app's and agrees with every flag given beside it. */
+  static async readPack(
+    app: App,
+    dir: string,
+    {
+      platform,
+      target,
+      env,
+      allowLocalRelease,
+    }: { platform: MobilePlatform | null; target: string | null; env: NativeEnv | null; allowLocalRelease: boolean },
+  ) {
+    const pack = await UpdatePackFolder.read(dir);
+    const what = `The pack in ${pack.out} is ${pack.app} ${pack.target} ${pack.platform} --env ${pack.env}`;
+    if (pack.app !== app.name) throw new Error(`${what}, not ${app.name}'s.`);
+    if (platform && platform !== pack.platform) throw new Error(`${what}, not ${platform}.`);
+    if (env && env !== pack.env) throw new Error(`${what}, not --env ${env}.`);
+    if (target) {
+      const targets = (await resolveMobileTargets(app, target)).map(({ name }) => name);
+      if (targets.length !== 1 || targets[0] !== pack.target)
+        throw new Error(`${what}, not --target ${target} (${targets.join(", ")}).`);
+    }
+    if (pack.env === "local" && !allowLocalRelease)
+      throw new Error(
+        `${what}, and a local pack is blocked. Pass --allow-local-release only for explicit local release testing.`,
+      );
+    return pack;
+  }
+
+  async push(pack: NativeUpdatePack, { channel, notes }: { channel: string | null; notes: string | null }) {
+    const target = channel ?? pack.channel;
+    return await UpdatePackFolder.withArchive(pack, async (archive) => {
+      const release = await new UpdatePackUpload(this.cloudApi, this.devProjectId)
+        .send(archive, { appName: pack.app, target: pack.target, platform: pack.platform, channel: target, notes })
+        .catch((error: unknown) => {
+          throw CloudApi.refusal(error, "a pack is uploaded by a project member signed in with `akan login`");
+        });
+      const label = `${pack.app} ${pack.target} ${pack.platform} on channel ${target}: release ${release.id}`;
+      if (release.status === "rejected")
+        throw new ExitCodeError(
+          `The project rejected ${label}:\n${(release.problems ?? []).map((problem) => `  - ${problem}`).join("\n")}`,
+          2,
+        );
+      if (release.status === "published")
+        Logger.rawLog(`Published ${label} (${pack.files} files, native API ${pack.nativeApi}).`);
+      else
+        Logger.rawLog(
+          `Staged ${label} (${pack.files} files, native API ${pack.nativeApi}). Publish it from the project's release screen.`,
+        );
+      return release;
+    });
+  }
+
+  //? The store build first, then a pack of the same commit: a server that registers the binary checks the pack runs in it.
+  async registerBinary(
+    app: App,
+    pack: NativeUpdatePack,
+    { distribution, env }: { distribution: AppBinaryDistribution; env: NativeEnv },
+  ) {
+    const { cloudApi, devProjectId } = this;
+    const bundlePath = await CloudUpdates.storeBundlePath(app, pack.target, pack.platform);
+    const bundleFile = Bun.file(bundlePath);
+    const rebuild = `akan release-${pack.platform} ${app.name} --target ${pack.target} --env ${env}`;
+    if (!(await bundleFile.exists())) throw new Error(`No store build at ${bundlePath}: run \`${rebuild}\` first.`);
+    const bundle = await UpdatePackFolder.readBundle(bundlePath);
+    if (!bundle.updates)
+      throw new Error(`The store build at ${bundlePath} takes no updates: give the target native.updates.`);
+    const packBundle = path.join(pack.out, UpdatePackFolder.bundleFile);
+    const envProblem = await NativePublicEnv.problemAgainst(bundlePath, packBundle);
+    if (envProblem) throw new ExitCodeError(`The pack in ${pack.out} cannot run in the store build: ${envProblem}.`, 2);
+    //? Every native build of the target rewrites this file, so a debug or another env's build replaces the release's.
+    if (bundle.web.hash !== pack.webHash)
+      throw new Error(
+        `The store build at ${bundlePath} is not this commit's --env ${env} build: its web bundle differs from the pack's. Run \`${rebuild}\`, then register that build.`,
+      );
+    const compat = await NativeApp.compareBundles(app.cwdPath, bundlePath, packBundle);
+    const verdict = UpdatePackFolder.storeBuildVerdict(
+      { out: pack.out, compat: { against: bundlePath, ...compat } },
+      `Run \`${rebuild}\`, then register that build.`,
+    );
+    if (verdict) throw verdict;
+    if (bundle.updates.channel !== pack.channel)
+      throw new Error(
+        `The store build at ${bundlePath} reads updates channel ${bundle.updates.channel}, and this commit's --env ${env} pack is for ${pack.channel}. Run \`${rebuild}\`, then register that build.`,
+      );
+    const { channel } = pack;
+    const upload = new UpdatePackUpload(cloudApi, devProjectId);
+    return await UpdatePackFolder.withArchive(pack, async (archive) => {
+      const binary = await upload
+        .stage(archive, { appName: pack.app, target: pack.target, platform: pack.platform, channel, notes: null })
+        .then((packUploadId) =>
+          upload.settle(() =>
+            cloudApi.registerAppBinary(devProjectId, {
+              appName: pack.app,
+              target: pack.target,
+              distribution,
+              bundle: bundleFile,
+              packUploadId,
+              channel,
+            }),
+          ),
+        )
+        .catch((error: unknown) => {
+          throw CloudApi.refusal(error, "a binary is registered by a project member signed in with `akan login`");
+        });
+      Logger.rawLog(
+        `Registered ${pack.app} ${pack.target} ${pack.platform} (${distribution}): binary ${binary.id}, native API ${pack.nativeApi}.`,
+      );
+      return binary;
+    });
+  }
+}

package/cloud/globalConfig.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, test } from "bun:test";
+import { GlobalConfig } from "./globalConfig";
+
+const workspace = (cloudHost: string | null) => ({ getConfig: async () => ({ cloudHost }) });
+
+describe("GlobalConfig", () => {
+  test("hostFor spells --host the way the workspace's cloud.host is spelled, so one login serves both", async () => {
+    for (const given of ["https://cloud.example.com/", "https://Cloud.Example.com:443", "https://cloud.example.com//"])
+      expect(await GlobalConfig.hostFor(workspace(null), given)).toBe("https://cloud.example.com");
+    expect(await GlobalConfig.hostFor(workspace("https://cloud.example.com"), "https://cloud.example.com/")).toBe(
+      await GlobalConfig.hostFor(workspace("https://cloud.example.com"), null),
+    );
+    expect(await GlobalConfig.hostFor(workspace(null), "https://example.com/cloud/")).toBe("https://example.com/cloud");
+    expect(await GlobalConfig.hostFor(workspace(null), "http://localhost:8283/")).toBe("http://localhost:8283");
+    expect(await GlobalConfig.hostFor(workspace(null))).toBe(GlobalConfig.akanCloudHost);
+  });
+});