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

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/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("'", `'\\''`)}'`;
+  }
+}

package/mobile/desktopServerStage.ts

@@ -24,11 +24,13 @@ export interface DesktopServerRun extends ServerPolicy {
 //* `bun install --production` does. It is staged outside dist: installing there would put host packages into the
 //* image's `COPY . .`.
 export class DesktopServerStage {
-  //? An API-only server starts neither the RSC worker nor the akan console and serves no CSR, public/ or SSR artifact,
-  //? and `install` wrote its own package.json. The rest of dist is the server's: its chunks, a `.node`, a `.wasm`.
+  //? An API-only server starts neither the RSC worker nor the akan console and serves no CSR, public/ or SSR
+  //? artifact, and `install` wrote its own package.json and bun.lock. The rest of dist is the server's: its chunks,
+  //? a `.node`, a `.wasm`.
   static readonly uncarried = new Set([
     "Dockerfile",
     "package.json",
+    "bun.lock",
     "rscWorker.js",
     "console.js",
     "console-runtime.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.1.1-rc.5",
+  "version": "3.1.1-rc.6",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -48,7 +48,7 @@
     "@earendil-works/pi-tui": "1.3.0",
     "@inquirer/prompts": "^8.7.3",
     "@tailwindcss/node": "^4.3.3",
-    "akanjs": "3.1.1-rc.5",
+    "akanjs": "3.1.1-rc.6",
     "chalk": "^6.0.1",
     "commander": "^15.0.0",
     "dayjs": "^1.11.23",