@akanjs/devkit 3.1.1-rc.5 → 3.1.1-rc.7

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",

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")}

package/akanConfig/productionLockfile.test.ts

@@ -0,0 +1,80 @@
+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("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,32 @@
+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 {
+      await Promise.all([
+        Bun.write(path.join(dir, "package.json"), JSON.stringify(packageJson, null, 2)),
+        Bun.write(path.join(dir, ProductionLockfile.fileName), workspaceLock),
+      ]);
+      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/cloud/cloudApi.ts

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

package/cloud/cloudUpdates.ts

@@ -3,6 +3,7 @@ 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";
@@ -11,7 +12,8 @@ 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.
+//* 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,
@@ -77,6 +79,40 @@ 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 CloudApi.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}.json`;
+      const what = `${label} (${release.manifest.bundle}, ${release.payloads.length + 3} 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;
+    });
+  }
+
   //? 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,

package/cloud/updatePackUpload.test.ts

@@ -1,6 +1,6 @@
 import { afterAll, beforeEach, describe, expect, test } from "bun:test";
 import { createHash } from "node:crypto";
-import { writeFile } from "node:fs/promises";
+import { truncate, writeFile } from "node:fs/promises";
 import path from "node:path";
 import type { Workspace } from "../commandDecorators";
 import { tempDirs } from "../testHelpers";
@@ -24,6 +24,7 @@ class FakeCloudHost {
   commitAnswers: (number | [number, string] | Response)[] = [];
   release: Record<string, unknown> = { id: "release-1", status: "published", problems: [] };
   requestRefusal: Response | null = null;
+  contentType = "application/gzip";
 
   constructor() {
     this.server = Bun.serve({ port: 0, hostname: "127.0.0.1", fetch: (request) => this.#route(request) });
@@ -42,6 +43,7 @@ class FakeCloudHost {
     this.stallPuts = false;
     this.commitAnswers = [];
     this.requestRefusal = null;
+    this.contentType = "application/gzip";
   }
 
   async #route(request: Request) {
@@ -54,7 +56,7 @@ class FakeCloudHost {
         uploadId,
         uploadUrl: `${this.host}/storage/${uploadId}?X-Amz-Signature=secret-signature`,
         expiresAt: new Date(Date.now() + 15 * 60_000).toISOString(),
-        contentType: "application/gzip",
+        contentType: this.contentType,
       });
     }
     if (url.pathname.startsWith("/storage/") && request.method === "PUT") {
@@ -302,4 +304,38 @@ describe("UpdatePackUpload", () => {
     await expect(new UpdatePackUpload(api, "project-1", quick).send(archive, fields)).rejects.toThrow("0 bytes");
     expect(cloudHost.requests).toEqual([]);
   });
+
+  test("announces a desktop release with its kind and CPU, a phone pack with neither, and PUTs the ticket's type", async () => {
+    const desktop = { ...fields, platform: "macos" as const, kind: "app" as const, arch: "arm64" as const };
+    cloudHost.contentType = "application/x-tar";
+
+    await new UpdatePackUpload(api, "project-1", quick).send(await archiveOf("release tar"), desktop);
+    await new UpdatePackUpload(api, "project-1", quick).send(await archiveOf("pack bytes"), fields);
+
+    expect(cloudHost.requests[0]).toMatchObject({ platform: "macos", kind: "app", arch: "arm64", size: 11 });
+    expect(Object.keys(cloudHost.requests[1] ?? {}).filter((key) => key === "kind" || key === "arch")).toEqual([]);
+    expect(cloudHost.puts.map((put) => put.headers["content-type"])).toEqual([
+      "application/x-tar",
+      "application/x-tar",
+    ]);
+  });
+
+  test("takes a desktop release up to 1 GiB and a phone pack up to 200 MiB, refusing more before a ticket", async () => {
+    const desktop = { ...fields, platform: "windows" as const, kind: "app" as const, arch: "x64" as const };
+    const sparse = async (bytes: number) => {
+      const archive = await archiveOf("");
+      await truncate(archive, bytes);
+      return archive;
+    };
+    const upload = new UpdatePackUpload(api, "project-1", quick);
+
+    await expect(upload.send(await sparse(UpdatePackUpload.maxBytes + 1), fields)).rejects.toThrow(
+      `The pack archive is ${UpdatePackUpload.maxBytes + 1} bytes; a project takes 1 byte to 200 MiB.`,
+    );
+    await expect(upload.send(await sparse(UpdatePackUpload.maxAppBytes + 1), desktop)).rejects.toThrow(
+      `The release archive is ${UpdatePackUpload.maxAppBytes + 1} bytes; a project takes 1 byte to 1 GiB.`,
+    );
+    expect(cloudHost.requests).toEqual([]);
+    expect(UpdatePackUpload.maxAppBytes).toBe(1_073_741_824);
+  });
 });

package/cloud/updatePackUpload.ts

@@ -16,6 +16,7 @@ interface UpdatePackUploadOptions {
 //* embedded pack; either re-hashes it, and an upload is used once, one way.
 export class UpdatePackUpload {
   static readonly maxBytes = 200 * 1024 * 1024;
+  static readonly maxAppBytes = 1024 * 1024 * 1024;
   static readonly #transientPut = new Set([0, 408, 429, 500, 502, 503, 504]);
   //? A stalled PUT never fails on its own, so each try ends once the pack would be through even at this crawl.
   static readonly #putFloorBytesPerSecond = 64 * 1024;
@@ -57,7 +58,10 @@ export class UpdatePackUpload {
   /** Puts the pack in the project's staging storage and answers the upload id a commit or a registration names. */
   async stage(archive: string, fields: Omit<UpdateUploadRequest, "size" | "sha256">): Promise<string> {
     const file = Bun.file(archive);
-    if (file.size < 1 || file.size > UpdatePackUpload.maxBytes)
+    if (fields.kind === "app") {
+      if (file.size < 1 || file.size > UpdatePackUpload.maxAppBytes)
+        throw new Error(`The release archive is ${file.size} bytes; a project takes 1 byte to 1 GiB.`);
+    } else if (file.size < 1 || file.size > UpdatePackUpload.maxBytes)
       throw new Error(`The pack archive is ${file.size} bytes; a project takes 1 byte to 200 MiB.`);
     const hasher = new Bun.CryptoHasher("sha256");
     for await (const chunk of file.stream()) hasher.update(chunk);

package/commandDecorators/command.ts

@@ -26,6 +26,7 @@ import { CommandContainer } from "./dependencyBuilder";
 import { ExitCodeError } from "./exitCodeError";
 import { formatCommandHelp, formatHelp } from "./helpFormatter";
 import { type CommandCls, getTargetCommandNames, getTargetMetas, type TargetFailure } from "./targetMeta";
+import { WorkspaceVersionCheck } from "./workspaceVersionCheck";
 
 const loggedCliErrorObjects = new WeakSet<object>();
 const loggedCliErrorMessages = new Set<string>();
@@ -374,20 +375,8 @@ export const runCommands = async (...commands: CommandCls[]) => {
   program.version(process.env.AKAN_VERSION).description("Akan CLI").configureHelp({
     helpWidth: 100,
   });
-  const installedAkanPackageJson = (await FileSys.fileExists("./node_modules/akanjs/package.json"))
-    ? await FileSys.readJson<PackageJson>("./node_modules/akanjs/package.json")
-    : null;
-  if (installedAkanPackageJson && installedAkanPackageJson.version !== process.env.AKAN_VERSION) {
-    Logger.rawLog(
-      chalk.yellow(
-        `
-Akan CLI version is mismatch with installed package. ${process.env.AKAN_VERSION} (global) vs ${installedAkanPackageJson.version} (akanjs)
-It may cause unexpected behavior. Run \`akan update\` to update latest akanjs.`,
-      ),
-      undefined,
-      "error",
-    );
-  }
+  const versionWarning = WorkspaceVersionCheck.warning(cliPackageJson?.version, process.argv, process.cwd());
+  if (versionWarning) Logger.rawLog(chalk.yellow(`\n${versionWarning}`), undefined, "error");
 
   for (const command of commands) {
     const targetMetas = getTargetMetas(command);

package/commandDecorators/commandDecorators.test.ts

@@ -695,6 +695,6 @@ describe("a workspace whose akanjs is not the CLI's version", () => {
     ]);
     expect(code).toBe(0);
     expect(stdout).toBe('{"phases":1}');
-    expect(stderr).toContain("0.0.1-older (akanjs)");
+    expect(stderr).toContain("this workspace has akanjs 0.0.1-older");
   }, 30_000);
 });

package/commandDecorators/workspaceVersionCheck.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, test } from "bun:test";
+import { mkdir, symlink } from "node:fs/promises";
+import path from "node:path";
+import { tempDirs, writeJson } from "../testHelpers";
+import { WorkspaceVersionCheck } from "./workspaceVersionCheck";
+
+const makeRoot = tempDirs("akan-version-check-");
+const argv = (...args: string[]) => ["bun", "akan", ...args];
+
+const makeWorkspace = async ({ akanjs, cli }: { akanjs?: string; cli?: string }) => {
+  const root = await makeRoot();
+  if (akanjs) await writeJson(path.join(root, "node_modules/akanjs/package.json"), { name: "akanjs", version: akanjs });
+  if (cli)
+    await writeJson(path.join(root, "node_modules/@akanjs/cli/package.json"), { name: "@akanjs/cli", version: cli });
+  return root;
+};
+
+describe("WorkspaceVersionCheck", () => {
+  test("stays quiet when the CLI and the workspace's akanjs match, or when akanjs is not installed", async () => {
+    expect(
+      WorkspaceVersionCheck.warning("3.1.1-rc.5", argv("sync", "demo"), await makeWorkspace({ akanjs: "3.1.1-rc.5" })),
+    ).toBeNull();
+    expect(WorkspaceVersionCheck.warning("3.1.1-rc.5", argv("sync", "demo"), await makeWorkspace({}))).toBeNull();
+  });
+
+  test("names both versions and the matching CLI with the same arguments", async () => {
+    const root = await makeWorkspace({ akanjs: "3.1.0-rc.6" });
+
+    const warning = WorkspaceVersionCheck.warning("3.1.0", argv("sync", "demo", "--title", "it's"), root);
+
+    expect(warning).toContain("@akanjs/cli 3.1.0, but this workspace has akanjs 3.1.0-rc.6");
+    expect(warning).toContain(`Run the matching CLI: bunx -p @akanjs/cli@3.1.0-rc.6 akan sync demo --title 'it'\\''s'`);
+    expect(warning).toEndWith("together: akan update");
+  });
+
+  test("offers akan update with the CLI's prerelease tag only when the CLI is the newer one", async () => {
+    const older = await makeWorkspace({ akanjs: "3.1.1-rc.4" });
+    expect(WorkspaceVersionCheck.warning("3.1.1-rc.5", argv("build", "demo"), older)).toEndWith("akan update --tag rc");
+
+    const newer = await makeWorkspace({ akanjs: "3.1.1-rc.5" });
+    const warning = WorkspaceVersionCheck.warning("3.1.0", argv("build", "demo"), newer);
+    expect(warning).not.toContain("akan update");
+    expect(warning).toEndWith("Pin it so `bunx akan` runs it: bun add -d @akanjs/cli@3.1.1-rc.5");
+  });
+
+  test("points at the workspace's own pinned CLI when it matches akanjs", async () => {
+    const root = await makeWorkspace({ akanjs: "3.1.1-rc.5", cli: "3.1.1-rc.5" });
+
+    const warning = WorkspaceVersionCheck.warning("3.1.0", argv("start", "demo"), root);
+
+    expect(warning).toContain("Run the matching CLI: bunx akan start demo");
+    expect(warning).not.toContain("bun add -d");
+  });
+
+  test("leaves update, create-workspace, help and version alone", async () => {
+    const root = await makeWorkspace({ akanjs: "3.1.0-rc.6" });
+    for (const args of [["update"], ["create-workspace", "next"], ["--version"], ["-V"], ["sync", "--help"]])
+      expect(WorkspaceVersionCheck.warning("3.1.0", argv(...args), root)).toBeNull();
+  });
+
+  test("skips a workspace that links akanjs from its own source", async () => {
+    const root = await makeWorkspace({});
+    await writeJson(path.join(root, "pkgs/akanjs/package.json"), { name: "akanjs", version: "3.1.1-rc.4" });
+    await mkdir(path.join(root, "node_modules"), { recursive: true });
+    await symlink(path.join(root, "pkgs/akanjs"), path.join(root, "node_modules/akanjs"), "dir");
+
+    expect(WorkspaceVersionCheck.installedAkanVersion(root)).toBeNull();
+    expect(WorkspaceVersionCheck.warning("3.1.0", argv("sync", "demo"), root)).toBeNull();
+  });
+});

package/commandDecorators/workspaceVersionCheck.ts

@@ -0,0 +1,50 @@
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import path from "node:path";
+import type { PackageJson } from "../types";
+
+export class WorkspaceVersionCheck {
+  static readonly #exemptCommands = new Set(["update", "create-workspace"]);
+  static readonly #infoFlags = new Set(["--help", "-h", "--version", "-V"]);
+  static readonly #updateTags = new Set(["dev", "canary", "beta", "rc", "alpha"]);
+
+  static warning(cliVersion: string | undefined, argv: string[], workspaceRoot: string) {
+    const args = argv.slice(2);
+    if (!cliVersion || WorkspaceVersionCheck.#exemptCommands.has(args[0] ?? "")) return null;
+    if (args.some((arg) => WorkspaceVersionCheck.#infoFlags.has(arg))) return null;
+    const installed = WorkspaceVersionCheck.installedAkanVersion(workspaceRoot);
+    if (!installed || installed === cliVersion) return null;
+    const pinnedCli = WorkspaceVersionCheck.#versionAt(path.join(workspaceRoot, "node_modules/@akanjs/cli"));
+    const runner = pinnedCli === installed ? ["bunx"] : ["bunx", "-p", `@akanjs/cli@${installed}`];
+    const rerun = [...runner, "akan", ...args].map(WorkspaceVersionCheck.#quote).join(" ");
+    const [, prerelease = ""] = cliVersion.split("-");
+    const tag = prerelease.split(".")[0];
+    const update = `akan update${WorkspaceVersionCheck.#updateTags.has(tag) ? ` --tag ${tag}` : ""}`;
+    const lines = [
+      `This akan is @akanjs/cli ${cliVersion}, but this workspace has akanjs ${installed}: what it generates may not match the installed framework.`,
+      `Run the matching CLI: ${rerun}`,
+    ];
+    if (Bun.semver.order(cliVersion, installed) > 0)
+      lines.push(`Or move the workspace and this CLI to the newest release of the line together: ${update}`);
+    else if (pinnedCli !== installed)
+      lines.push(`Pin it so \`bunx akan\` runs it: bun add -d @akanjs/cli@${installed}`);
+    return lines.join("\n");
+  }
+
+  static installedAkanVersion(workspaceRoot: string) {
+    const packageDir = path.join(workspaceRoot, "node_modules", "akanjs");
+    if (!existsSync(packageDir)) return null;
+    //? A workspace link (the framework's own repo) runs akanjs from source, so no installed release can differ.
+    if (!realpathSync(packageDir).split(path.sep).includes("node_modules")) return null;
+    return WorkspaceVersionCheck.#versionAt(packageDir);
+  }
+
+  static #versionAt(packageDir: string) {
+    const packageJsonPath = path.join(packageDir, "package.json");
+    if (!existsSync(packageJsonPath)) return null;
+    return (JSON.parse(readFileSync(packageJsonPath, "utf8")) as Partial<PackageJson>).version ?? null;
+  }
+
+  static #quote(arg: string) {
+    return /^[\w@%+=:,./-]+$/.test(arg) ? arg : `'${arg.replaceAll("'", `'\\''`)}'`;
+  }
+}