@akanjs/devkit 3.1.1-rc.1 → 3.1.1-rc.11

package/akanApp/akanApp.host.test.ts

@@ -13,6 +13,18 @@ describe("readProcessRssBytes", () => {
     expect(rssBytes).toBeLessThan(64 * 1024 * 1024 * 1024);
   });
 
+  // The builder's own report triggers a recycle and this reading settles it, so the two must agree.
+  test.skipIf(process.platform !== "darwin")("reads what the process reports once it frees memory", async () => {
+    let held: number[][] | null = Array.from({ length: 64 }, (_, idx) => new Array<number>(500_000).fill(idx + 0.5));
+    expect(held.length).toBe(64);
+    held = null;
+    Bun.gc(true);
+    await Bun.sleep(500);
+    const rssBytes = await AkanAppHost.readProcessRssBytes(process.pid);
+    if (rssBytes === null) throw new Error("expected to read this process's own rss");
+    expect(Math.abs(rssBytes - process.memoryUsage.rss())).toBeLessThan(64 * 1024 * 1024);
+  });
+
   // A 0 would read as "settled below the ceiling" and cancel a recycle that should happen.
   test("returns null for a pid that does not exist", async () => {
     expect(await AkanAppHost.readProcessRssBytes(2_147_483_646)).toBeNull();

package/akanApp/akanApp.host.ts

@@ -651,6 +651,13 @@ export class AkanAppHost {
         ["tasklist", "/FI", `PID eq ${pid}`, "/FO", "CSV", "/NH"],
         AkanAppHost.#tasklistRssKb,
       );
+    if (process.platform === "darwin") {
+      const footprintBytes = await AkanAppHost.#readRssKbVia(
+        ["footprint", "-p", String(pid), "-f", "bytes"],
+        AkanAppHost.#footprintKb,
+      );
+      if (footprintBytes !== null) return footprintBytes;
+    }
     const status = await Bun.file(`/proc/${pid}/status`)
       .text()
       .catch(() => null);
@@ -687,6 +694,11 @@ export class AkanAppHost {
     const memUsage = /"([^"]*)"\s*$/m.exec(output)?.[1];
     return memUsage ? Number(memUsage.replace(/\D/g, "")) : Number.NaN;
   }
+  // The footprint is what `process.memoryUsage.rss()` reports on macOS; `ps` also counts pages freed for reuse.
+  static #footprintKb(output: string): number {
+    const bytes = /Footprint: (\d+) B\b/.exec(output)?.[1];
+    return bytes ? Number(bytes) / 1024 : Number.NaN;
+  }
   #cancelRssRecycle(): void {
     this.#rssRecycleReason = null;
     this.#rssRecycleOver = null;

package/akanConfig/akanConfig.test.ts

@@ -154,6 +154,17 @@ describe("AkanAppConfig", () => {
     expect(config.dockerfile).toContain('RUN if [ "$TARGETARCH" = "arm64"');
   });
 
+  test("installs from the build's bun.lock frozen, or unlocked when the build wrote none", () => {
+    const config = new AkanAppConfig(app, [], packageJson, { docker: { postRuns: ["echo after"] } }, baseDevEnv);
+    const locked = config.dockerfileFor("main");
+    const unlocked = config.dockerfileFor("main", { lockfile: false });
+
+    expect(locked).toContain("COPY ./package.json ./bun.lock ./\nRUN bun install --production --frozen-lockfile\n");
+    expect(locked.indexOf("--frozen-lockfile")).toBeLessThan(locked.indexOf("echo after"));
+    expect(unlocked).toContain("COPY ./package.json ./package.json\nRUN bun install --production\n");
+    expect(unlocked).not.toContain("bun.lock");
+  });
+
   test("defaults both web surfaces on and keeps the image free of web env overrides", () => {
     const config = new AkanAppConfig(app, [], packageJson, {}, baseDevEnv);
 
@@ -219,8 +230,8 @@ describe("AkanAppConfig", () => {
       "",
       "RUN mkdir -p /workspace",
       "WORKDIR /workspace",
-      "COPY ./package.json ./package.json",
-      "RUN bun install --production",
+      "COPY ./package.json ./bun.lock ./",
+      "RUN bun install --production --frozen-lockfile",
       "",
       "COPY . .",
       "ENV PORT=8282",
@@ -306,6 +317,36 @@ describe("AkanAppConfig", () => {
     expect(() => brokenConfig.getProductionPackageJson()).toThrow("Dependency missing-lib not found");
   });
 
+  test("carries the root's overrides and resolutions, so the image resolves what the workspace locked", () => {
+    const pinned = new AkanAppConfig(
+      app,
+      [],
+      { ...packageJson, overrides: { "js-tokens": "2.0.0" }, resolutions: { ms: "2.0.0" } },
+      {},
+      baseDevEnv,
+    );
+    expect(pinned.getProductionPackageJson()).toMatchObject({
+      overrides: { "js-tokens": "2.0.0" },
+      resolutions: { ms: "2.0.0" },
+    });
+    const local = new AkanAppConfig(
+      app,
+      [],
+      {
+        ...packageJson,
+        overrides: { "js-tokens": "2.0.0", patched: "file:./patches/patched", shared: "workspace:*" },
+        resolutions: { ms: "link:../ms" },
+      },
+      {},
+      baseDevEnv,
+    ).getProductionPackageJson();
+    expect(local.overrides).toEqual({ "js-tokens": "2.0.0" });
+    expect(local).not.toHaveProperty("resolutions");
+    const unpinned = new AkanAppConfig(app, [], packageJson, {}, baseDevEnv).getProductionPackageJson();
+    expect(unpinned).not.toHaveProperty("overrides");
+    expect(unpinned).not.toHaveProperty("resolutions");
+  });
+
   test("falls back to akanjs package versions for built-in runtime dependencies", () => {
     const runtimeDependencies = {
       ...akanPackageJson.dependencies,

package/akanConfig/akanConfig.ts

@@ -634,10 +634,10 @@ export class AkanAppConfig implements AppConfigResult {
       ...(this.web.csr ? {} : { AKAN_CSR: "false" }),
     };
   }
-  dockerfileFor(environment: string): string {
-    return this.#makeDockerfile(environment);
+  dockerfileFor(environment: string, { lockfile = true }: { lockfile?: boolean } = {}): string {
+    return this.#makeDockerfile(environment, lockfile);
   }
-  #makeDockerfile(environment?: string): string {
+  #makeDockerfile(environment?: string, lockfile = true): string {
     if (typeof this.docker === "string") return this.docker;
     const { image, preRuns, postRuns, command } = this.docker;
     const preRunScripts = this.#getDockerRunScripts(preRuns);
@@ -651,8 +651,8 @@ ARG TARGETARCH
 ${preRunScripts.join("\n")}
 RUN mkdir -p /workspace
 WORKDIR /workspace
-COPY ./package.json ./package.json
-RUN bun install --production
+${lockfile ? "COPY ./package.json ./bun.lock ./" : "COPY ./package.json ./package.json"}
+RUN bun install --production${lockfile ? " --frozen-lockfile" : ""}
 ${postRunScripts.join("\n")}
 COPY . .
 ${envLines.join("\n")}
@@ -776,7 +776,15 @@ CMD [${command.map((c) => `"${c}"`).join(",")}]`;
   static get akanVersion() {
     return getAkanPackageJson().version;
   }
+  //? The image installs from the registry alone: a pin to a path or a workspace package resolves nowhere there.
+  static #registryPins(pins: Record<string, string> | undefined) {
+    if (!pins) return undefined;
+    const kept = Object.entries(pins).filter(([, spec]) => !/^(?:file:|link:|workspace:|portal:|[./~])/.test(spec));
+    return kept.length ? Object.fromEntries(kept) : undefined;
+  }
   getProductionPackageJson(data: Partial<PackageJson> = {}): PackageJson {
+    const overrides = AkanAppConfig.#registryPins(this.rootPackageJson.overrides);
+    const resolutions = AkanAppConfig.#registryPins(this.rootPackageJson.resolutions);
     return {
       name: this.app.name,
       description: this.app.name,
@@ -789,6 +797,8 @@ CMD [${command.map((c) => `"${c}"`).join(",")}]`;
         ]),
       ),
       ...(this.trustedDependencies.length ? { trustedDependencies: this.trustedDependencies } : {}),
+      ...(overrides ? { overrides } : {}),
+      ...(resolutions ? { resolutions } : {}),
       ...data,
     };
   }

package/akanConfig/productionLockfile.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { ProductionLockfile } from "./productionLockfile";
+
+// js-tokens 3.0.2 is locked although 4.0.0 satisfies the range: a re-resolve would move it.
+const workspaceLock = `{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "repo",
+      "dependencies": {
+        "loose-envify": "^1.4.0",
+        "ms": "^2.0.0",
+      },
+    },
+  },
+  "packages": {
+    "js-tokens": ["js-tokens@3.0.2", "", {}, "sha512-RjTcuD4xjtthQkaWH7dFlH85L+QaVtSoOyGdZ3g6HFhS9dFNDfLyqgm2NFe2X6cQpeFmt0452FJjFG5UameExg=="],
+
+    "loose-envify": ["loose-envify@1.4.0", "", { "dependencies": { "js-tokens": "^3.0.0 || ^4.0.0" }, "bin": { "loose-envify": "cli.js" } }, "sha512-lyuxPGr/Wfhrlem2CL/UcnUc1zcqKAImBDzukY7Y5F/yQiNdko6+fRLevlw1HgMySw7f611UIY408EtxRSoK3Q=="],
+
+    "ms": ["ms@2.0.0", "", {}, "sha512-Tpp60P6IUJDTuOq/5Z8cdskzJujfwqfOTkrwIwj7IRISpnkJnT6SyJ4PCPnGMoFjC9ddhal5KVIYtAt97ix05A=="],
+  }
+}
+`;
+
+const productionPackageJson = {
+  name: "portal",
+  description: "portal",
+  version: "1.0.0",
+  dependencies: { "loose-envify": "^1.4.0" },
+};
+
+const withWorkspace = async (lock: string | null, run: (root: string) => Promise<void>) => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "akan-production-lock-test-"));
+  try {
+    if (lock !== null) await writeFile(path.join(root, "bun.lock"), lock);
+    await run(root);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+};
+
+describe("ProductionLockfile", () => {
+  test("keeps the workspace's locked versions and drops what the production package.json does not reach", async () => {
+    await withWorkspace(workspaceLock, async (root) => {
+      const lock = await ProductionLockfile.prune(root, productionPackageJson);
+      expect(lock).toContain('"loose-envify": ["loose-envify@1.4.0"');
+      expect(lock).toContain('"js-tokens": ["js-tokens@3.0.2"');
+      expect(lock).not.toContain("ms@2.0.0");
+      expect(lock).not.toContain('"ms": "^2.0.0"');
+    });
+  });
+
+  test("a bun install --frozen-lockfile of the pruned lockfile changes nothing", async () => {
+    await withWorkspace(workspaceLock, async (root) => {
+      const lock = await ProductionLockfile.prune(root, productionPackageJson);
+      await writeFile(path.join(root, "package.json"), JSON.stringify(productionPackageJson, null, 2));
+      await writeFile(path.join(root, "bun.lock"), lock);
+      const install = Bun.spawn([process.execPath, "install", "--lockfile-only", "--frozen-lockfile"], {
+        cwd: root,
+        stdout: "ignore",
+        stderr: "pipe",
+      });
+      expect(await install.exited).toBe(0);
+      expect(await Bun.file(path.join(root, "bun.lock")).text()).toBe(lock);
+    });
+  });
+
+  test("keeps a version an override pinned outside its parent's range", async () => {
+    const overriddenLock = `{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "repo",
+      "dependencies": {
+        "loose-envify": "^1.4.0",
+      },
+    },
+  },
+  "overrides": {
+    "js-tokens": "2.0.0",
+  },
+  "packages": {
+    "js-tokens": ["js-tokens@2.0.0", "", {}, "sha512-kk4RjoztHFeAlCNPdTr/uF04oN5z53L18LJfADBQ7YHkO3iR2rP2ZwOH0n33r2FRw0psRmjTDEkOWPE//zmujg=="],
+
+    "loose-envify": ["loose-envify@1.4.0", "", { "dependencies": { "js-tokens": "^3.0.0 || ^4.0.0" }, "bin": { "loose-envify": "cli.js" } }, "sha512-lyuxPGr/Wfhrlem2CL/UcnUc1zcqKAImBDzukY7Y5F/yQiNdko6+fRLevlw1HgMySw7f611UIY408EtxRSoK3Q=="],
+  }
+}
+`;
+    await withWorkspace(overriddenLock, async (root) => {
+      const lock = await ProductionLockfile.prune(root, {
+        ...productionPackageJson,
+        overrides: { "js-tokens": "2.0.0" },
+      });
+      expect(lock).toContain('"js-tokens": ["js-tokens@2.0.0"');
+    });
+  });
+
+  test("refuses a workspace without a bun.lock, so the build can fall back to an unlocked install", async () => {
+    await withWorkspace(null, async (root) => {
+      await expect(ProductionLockfile.prune(root, productionPackageJson)).rejects.toThrow(
+        "the workspace root has no bun.lock",
+      );
+    });
+  });
+});

package/akanConfig/productionLockfile.ts

@@ -0,0 +1,34 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import type { PackageJson } from "../types";
+
+export class ProductionLockfile {
+  static readonly fileName = "bun.lock";
+
+  //? Beside a copy of the workspace lockfile, Bun keeps each version it locked and drops what the package.json no
+  //? longer reaches; only a package the workspace never locked is resolved from the registry.
+  static async prune(workspaceRoot: string, packageJson: PackageJson): Promise<string> {
+    const workspaceLock = Bun.file(path.join(workspaceRoot, ProductionLockfile.fileName));
+    if (!(await workspaceLock.exists())) throw new Error(`the workspace root has no ${ProductionLockfile.fileName}`);
+    const dir = await mkdtemp(path.join(os.tmpdir(), "akan-production-lock-"));
+    try {
+      const npmrc = Bun.file(path.join(workspaceRoot, ".npmrc"));
+      await Promise.all([
+        Bun.write(path.join(dir, "package.json"), JSON.stringify(packageJson, null, 2)),
+        Bun.write(path.join(dir, ProductionLockfile.fileName), workspaceLock),
+        ...((await npmrc.exists()) ? [Bun.write(path.join(dir, ".npmrc"), npmrc)] : []),
+      ]);
+      const install = Bun.spawn([process.execPath, "install", "--lockfile-only", "--no-progress"], {
+        cwd: dir,
+        stdout: "ignore",
+        stderr: "pipe",
+      });
+      const [exitCode, stderr] = await Promise.all([install.exited, new Response(install.stderr).text()]);
+      if (exitCode !== 0) throw new Error(stderr.trim() || `bun install --lockfile-only exited with ${exitCode}`);
+      return await Bun.file(path.join(dir, ProductionLockfile.fileName)).text();
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  }
+}

package/akanContext.ts

@@ -632,6 +632,28 @@ export class AkanContextAnalyzer {
     };
   }
 
+  //? Older templates wrote these for Next.js: nothing installs or reads them, and editors warn about the plugin.
+  static async #configLeftovers(workspace: WorkspaceExecutor, sysPaths: string[]) {
+    const leftovers: { path: string; message: string }[] = [];
+    for (const sysPath of sysPaths) {
+      const tsconfigPath = `${sysPath}/tsconfig.json`;
+      const tsconfig = await safeReadText(path.join(workspace.workspaceRoot, tsconfigPath));
+      if (tsconfig && (/"name"\s*:\s*"next"/.test(tsconfig) || tsconfig.includes(".next/types")))
+        leftovers.push({
+          path: tsconfigPath,
+          message: `${tsconfigPath} still names the Next.js TS plugin or .next/types, which Akan never uses — delete the "next" plugin entry and the ".next/types/**/*.ts" include.`,
+        });
+    }
+    const bunfig = await safeReadText(path.join(workspace.workspaceRoot, "bunfig.toml"));
+    if (bunfig?.includes("bun-plugin-tailwind"))
+      leftovers.push({
+        path: "bunfig.toml",
+        message:
+          "bunfig.toml still loads bun-plugin-tailwind, which is not installed and which Akan never uses (it compiles Tailwind itself) — delete the [serve.static] section, which Akan never reads.",
+      });
+    return leftovers;
+  }
+
   static async doctor(
     workspace: WorkspaceExecutor,
     {
@@ -701,6 +723,9 @@ export class AkanContextAnalyzer {
         { severity: "warning", code: agentDrift.code, path: "AGENTS.md", message: agentDrift.message },
         repairAction("generated", "akan agent install agents-md", agentDrift.hint, true),
       );
+    const sysPaths = [...context.apps, ...context.libs].map((sys) => sys.path);
+    for (const leftover of await AkanContextAnalyzer.#configLeftovers(workspace, sysPaths))
+      diagnostics.push({ severity: "warning", code: "config-leftover", ...leftover });
 
     for (const sys of [...context.apps, ...context.libs]) {
       for (const module of sys.modules) {

package/applicationBuildRunner.test.ts

@@ -3,6 +3,7 @@ import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { AkanAppConfig } from "./akanConfig";
+import { ProductionLockfile } from "./akanConfig/productionLockfile";
 import { AKAN_BACKEND_MINIFY, AKAN_OPTIONAL_BACKEND_EXTERNALS, ApplicationBuildRunner } from "./applicationBuildRunner";
 import type { App } from "./commandDecorators";
 import { AppExecutor, Executor } from "./executors";
@@ -70,6 +71,7 @@ console.info(new SampleService().name);
       getConfig: async () => config,
       dist: new Executor("dist", root),
       workspace: { workspaceRoot: root },
+      logger: { warn: () => undefined },
     } as unknown as App;
     try {
       await new ApplicationBuildRunner(app, { environment: "debug" }).buildAppMeta();
@@ -81,6 +83,45 @@ console.info(new SampleService().name);
     }
   });
 
+  test("writes the pruned lockfile beside package.json, or warns and leaves the image's install unlocked", async () => {
+    const root = await mkdtemp(path.join(os.tmpdir(), "akan-build-meta-"));
+    const config = new AkanAppConfig(
+      { name: "portal" } as never,
+      [],
+      { name: "repo", version: "1.0.0", description: "repo" },
+      {},
+      { repoName: "akanjs", serveDomain: "akanjs.com", env: "local", portOffset: 0, workspaceRoot: root },
+    );
+    const warnings: string[] = [];
+    const app = {
+      getConfig: async () => config,
+      dist: new Executor("dist", root),
+      workspace: { workspaceRoot: root },
+      logger: { warn: (message: string) => warnings.push(message) },
+    } as unknown as App;
+    const prune = spyOn(ProductionLockfile, "prune");
+    try {
+      prune.mockResolvedValueOnce('{ "lockfileVersion": 1 }\n');
+      await new ApplicationBuildRunner(app).buildAppMeta();
+      expect(prune.mock.calls[0]?.[1]).toEqual(JSON.parse(await readFile(path.join(root, "package.json"), "utf8")));
+      expect(await readFile(path.join(root, "bun.lock"), "utf8")).toBe('{ "lockfileVersion": 1 }\n');
+      expect(await readFile(path.join(root, "Dockerfile"), "utf8")).toContain("--frozen-lockfile");
+      expect(warnings).toEqual([]);
+
+      await rm(path.join(root, "bun.lock"));
+      prune.mockRejectedValueOnce(new Error("the workspace root has no bun.lock"));
+      await new ApplicationBuildRunner(app).buildAppMeta();
+      expect(await Bun.file(path.join(root, "bun.lock")).exists()).toBe(false);
+      expect(await readFile(path.join(root, "Dockerfile"), "utf8")).toContain("RUN bun install --production\n");
+      expect(warnings).toEqual([
+        "The image installs its dependencies unlocked, at the newest versions package.json allows: the workspace root has no bun.lock",
+      ]);
+    } finally {
+      prune.mockRestore();
+      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;

package/applicationBuildRunner.ts

@@ -1,5 +1,7 @@
 import path from "node:path";
+import { toError } from "akanjs/common";
 import type { BunPlugin } from "bun";
+import { ProductionLockfile } from "./akanConfig/productionLockfile";
 import type {
   ApplicationBuildPhaseResult,
   ApplicationBuildProgressReporter,
@@ -18,7 +20,7 @@ import { Spinner } from "./spinner";
 import { createServerEnvPlugin } from "./transforms/serverEnvPlugin";
 import { ServerEnvProfile } from "./transforms/serverEnvProfile";
 import { ProjectTypecheck } from "./typecheck/projectTypecheck";
-import type { BaseDevEnv } from "./types";
+import type { BaseDevEnv, PackageJson } from "./types";
 
 export interface TypecheckOptions {
   clean?: boolean;
@@ -236,9 +238,16 @@ export class ApplicationBuildRunner {
 
   async buildAppMeta() {
     const akanConfig = await this.#app.getConfig();
-    const dockerfile = akanConfig.dockerfileFor(this.#environment ?? akanConfig.baseDevEnv.env);
+    const packageJson = akanConfig.getProductionPackageJson();
+    const lockfile = await this.#pruneLockfile(packageJson);
+    const dockerfile = akanConfig.dockerfileFor(this.#environment ?? akanConfig.baseDevEnv.env, {
+      lockfile: lockfile !== null,
+    });
     await Promise.all([
-      this.#app.dist.writeJson("package.json", akanConfig.getProductionPackageJson()),
+      this.#app.dist.writeJson("package.json", packageJson),
+      ...(lockfile !== null
+        ? [this.#app.dist.writeFile(`${this.#app.dist.cwdPath}/${ProductionLockfile.fileName}`, lockfile)]
+        : []),
       this.#app.dist.writeFile(`${this.#app.dist.cwdPath}/Dockerfile`, dockerfile),
       this.#app.dist.writeJson("akan.build.json", {
         buildId: await this.#resolveBuildId(),
@@ -248,6 +257,17 @@ export class ApplicationBuildRunner {
     ]);
   }
 
+  async #pruneLockfile(packageJson: PackageJson): Promise<string | null> {
+    try {
+      return await ProductionLockfile.prune(this.#app.workspace.workspaceRoot, packageJson);
+    } catch (error) {
+      this.#app.logger.warn(
+        `The image installs its dependencies unlocked, at the newest versions package.json allows: ${toError(error).message}`,
+      );
+      return null;
+    }
+  }
+
   //* Read back at runtime as `buildId` on the ops channel; a deployment's own AKAN_BUILD_ID still wins over it there.
   async #resolveBuildId() {
     const fromEnv = process.env.AKAN_BUILD_ID?.trim();

package/biomeBase.test.ts

@@ -7,7 +7,7 @@ import { biomeBaseConfig } from "./biomeBase";
 import { Linter, parseBiomeReport } from "./linter";
 
 const devkitDir = import.meta.dir;
-const biomeBin = path.resolve(devkitDir, "../../../node_modules/.bin", Linter.biomeBinName);
+const [biome, ...biomeArgs] = Linter.biomeCommand(path.resolve(devkitDir, "../../.."));
 
 const hookProbe = `export const Early = ({ id }: { id?: string }) => {
   if (!id) return null;
@@ -28,7 +28,7 @@ afterAll(async () => {
 
 const runBiome = (args: string[], cwd: string) =>
   new Promise<string>((resolve, reject) => {
-    const proc = spawn(biomeBin, args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+    const proc = spawn(biome, [...biomeArgs, ...args], { cwd, stdio: ["ignore", "pipe", "pipe"] });
     let stdout = "";
     let stderr = "";
     proc.stdout.on("data", (chunk: Buffer) => (stdout += chunk.toString()));

package/cloud/cloudApi.ts

@@ -1,4 +1,4 @@
-import { isRecord } from "akanjs/common";
+import { isRecord, Logger } from "akanjs/common";
 import type { Workspace } from "../commandDecorators";
 import { CloudHttpError } from "./cloudHttpError";
 import type { AccessToken, AccessTokenDto, HostConfig } from "./constants";
@@ -86,7 +86,10 @@ export interface CloudRecord {
 export interface UpdateUploadRequest {
   appName: string;
   target: string;
-  platform: "ios" | "android";
+  platform: "ios" | "android" | "macos" | "windows" | "linux";
+  //? Absent is a phone's web bundle, so a phone request reads as it did before desktop releases.
+  kind?: "app";
+  arch?: "arm64" | "x64";
   channel: string;
   notes: string | null;
   size: number;
@@ -120,8 +123,11 @@ export class CloudApi {
     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 });
+    if (error.status === 400) {
+      const { data } = error;
+      const why = `${error.error ? `: ${error.error}` : ""}${data ? ` ${Logger.inlineData(data)}` : ""}`;
+      return new Error(`The project refused the request${why}.`, { 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")

package/cloud/cloudHttpError.test.ts

@@ -20,6 +20,14 @@ describe("CloudHttpError", () => {
     expect(plain.errKey).toBeNull();
   });
 
+  test("reads the data a server Err carried, and none from a body without it", () => {
+    const body = JSON.stringify({ error: "release.error.desktopMalformed", data: { reason: "a directory entry" } });
+
+    expect(new CloudHttpError(400, "Bad Request", "/x", body).data).toEqual({ reason: "a directory entry" });
+    expect(new CloudHttpError(400, "Bad Request", "/x", '{"error":"Bad Request","data":"x"}').data).toBeNull();
+    expect(new CloudHttpError(502, "Bad Gateway", "/x", "<html>502</html>").data).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);

package/cloud/cloudHttpError.ts

@@ -26,9 +26,19 @@ export class CloudHttpError extends Error {
 
   /** The `error` of a JSON refusal: an Err key from the server itself, or whatever a proxy put there. */
   get error(): string | null {
+    const error = this.#payload?.error;
+    return typeof error === "string" ? error : null;
+  }
+
+  get data(): Record<string, unknown> | null {
+    const data = this.#payload?.data;
+    return isRecord(data) ? data : null;
+  }
+
+  get #payload(): Record<string, unknown> | null {
     try {
       const parsed: unknown = JSON.parse(this.body);
-      return isRecord(parsed) && typeof parsed.error === "string" ? parsed.error : null;
+      return isRecord(parsed) ? parsed : null;
     } catch {
       return null;
     }

package/cloud/cloudUpdates.ts

@@ -3,15 +3,18 @@ import { Logger } from "akanjs/common";
 import type { NativeEnv } from "../akanConfig";
 import type { App } from "../commandDecorators";
 import { ExitCodeError } from "../commandDecorators/exitCodeError";
+import type { DesktopRelease, DesktopSigner } from "../mobile/desktopRelease";
 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 { CloudHttpError } from "./cloudHttpError";
 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.
+//* it to sign and publish, and the store build a pack of the same commit is embedded in. A desktop release is signed
+//* where it was published, and goes up as it is.
 export class CloudUpdates {
   constructor(
     readonly cloudApi: CloudApi,
@@ -59,7 +62,7 @@ export class CloudUpdates {
       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`");
+          throw CloudUpdates.#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")
@@ -77,6 +80,49 @@ export class CloudUpdates {
     });
   }
 
+  //? `manifestUrl` is where the project serves the channel once published; before that, the URL the app was built with.
+  async pushRelease(
+    release: DesktopRelease,
+    {
+      appName,
+      target,
+      notes,
+      signer,
+      url,
+    }: { appName: string; target: string; notes: string | null; signer: DesktopSigner; url: string },
+  ) {
+    const { platform, arch, channel } = release;
+    return await release.withArchive(release.record(signer), async (archive) => {
+      const record = await new UpdatePackUpload(this.cloudApi, this.devProjectId)
+        .send(archive, { appName, target, platform, kind: "app", arch, channel, notes })
+        .catch((error: unknown) => {
+          throw CloudUpdates.#refusal(error, "a release is uploaded by a project member signed in with `akan login`");
+        });
+      const label = `${appName} ${target} ${platform}-${arch} on channel ${channel}: release ${record.id}`;
+      const problems = (record.problems ?? []).map((problem) => `  - ${problem}`).join("\n");
+      if (record.status === "rejected") throw new ExitCodeError(`The project rejected ${label}:\n${problems}`, 2);
+      const manifestUrl =
+        typeof record.manifestUrl === "string" ? record.manifestUrl : `${url}/${platform}-${arch}/${channel}/app.json`;
+      const files = 1 + release.manifestFiles.length + release.payloads.length;
+      const what = `${label} (${release.manifest.bundle}, ${files} files)`;
+      Logger.rawLog(
+        record.status === "published"
+          ? `Published ${what}. Installed apps read ${manifestUrl}.`
+          : `Staged ${what}. Publish it from the project's release screen; installed apps read ${manifestUrl}.`,
+      );
+      if (problems) Logger.rawLog(`The project noted:\n${problems}`);
+      return record;
+    });
+  }
+
+  //? A 400 naming a release Err key is the project's verdict on the release, as a rejected one is: a retry changes nothing.
+  static #refusal(error: unknown, who: string) {
+    const refusal = CloudApi.refusal(error, who);
+    const verdict =
+      error instanceof CloudHttpError && error.status === 400 && !!error.errKey?.startsWith("release.error.");
+    return verdict && refusal instanceof Error ? new ExitCodeError(refusal.message, 2) : refusal;
+  }
+
   //? 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,