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

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,80 @@
+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, quoted for the shell it runs in", async () => {
+    const root = await makeWorkspace({ akanjs: "3.1.0-rc.6" });
+    const platform = Object.getOwnPropertyDescriptor(process, "platform");
+    const warningOn = (os: NodeJS.Platform) => {
+      Object.defineProperty(process, "platform", { value: os });
+      return WorkspaceVersionCheck.warning("3.1.0", argv("sync", "demo", "--title", "it's"), root);
+    };
+    try {
+      const posix = warningOn("linux");
+      expect(posix).toContain("@akanjs/cli 3.1.0, but this workspace has akanjs 3.1.0-rc.6");
+      expect(posix).toContain(`Run the matching CLI: bunx -p @akanjs/cli@3.1.0-rc.6 akan sync demo --title 'it'\\''s'`);
+      expect(posix).toEndWith("together: akan update");
+      expect(warningOn("win32")).toContain(
+        `Run the matching CLI: bunx -p @akanjs/cli@3.1.0-rc.6 akan sync demo --title "it's"`,
+      );
+    } finally {
+      if (platform) Object.defineProperty(process, "platform", platform);
+    }
+  });
+
+  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,53 @@
+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) {
+    if (/^[\w@%+=:,./-]+$/.test(arg)) return arg;
+    //? cmd and PowerShell take neither single quotes nor '\'' as POSIX shells do.
+    if (process.platform === "win32") return `"${arg.replaceAll('"', '\\"')}"`;
+    return `'${arg.replaceAll("'", `'\\''`)}'`;
+  }
+}

package/csrE2e/ssrRegistry.e2e.test.ts

@@ -61,7 +61,12 @@ describe.skipIf(!CsrE2eHarness.enabled)("SSR dev registry (minimal)", () => {
   let ssr: CsrE2eHarness;
 
   beforeAll(async () => {
-    ssr = await CsrE2eHarness.start({ app: "minimal", port, env: { AKAN_DEV_SSR_ARM_DELAY_MS: "3000" } });
+    ssr = await CsrE2eHarness.start({
+      app: "minimal",
+      port,
+      // The server-log assertions match verbose-level lines, which a workspace `.env` may or may not turn on.
+      env: { AKAN_DEV_SSR_ARM_DELAY_MS: "3000", AKAN_PUBLIC_LOG_LEVEL: "verbose" },
+    });
   }, 240_000);
 
   afterAll(async () => {

package/executors.test.ts

@@ -1383,7 +1383,13 @@ describe("SysExecutor scan", () => {
     expect(await lib.readFile("srvkit/index.ts")).toBe(
       ["a9", "a10", "aa", "aB"].map((name) => `export * from "./${name}";\n`).join(""),
     );
-    for (const file of ["ui/index.ts", "srvkit/index.ts", "lib/post/index.ts", "akan.lib.json"]) {
+    for (const file of [
+      "ui/index.ts",
+      "srvkit/index.ts",
+      "lib/post/index.ts",
+      "akan.lib.json",
+      "env/env.server.type.ts",
+    ]) {
       const generated = await lib.readFile(file);
       expect(await formatWithBiome(generated, `libs/biomestable/${file}`)).toBe(generated);
     }
@@ -1392,6 +1398,20 @@ describe("SysExecutor scan", () => {
     expect(await devSync.syncForBatch(events)).toEqual({ changedFiles: [], errors: [] });
   });
 
+  test.skipIf(!hasBiome)(
+    "writes env.server.type.ts the way Biome prints it, spreading libs in dependency order",
+    async () => {
+      const { default: getContent } = (await import("../cli/templates/env/_env.server.type")) as {
+        default: (scanInfo: unknown) => { content: string };
+      };
+      const libs = ["util", "shared", "shopAdmin", "shop", "a10", "a9"];
+      const { content } = getContent({ getLibs: () => libs });
+
+      expect(await formatWithBiome(content, "apps/biomestable/env/env.server.type.ts")).toBe(content);
+      expect([...content.matchAll(/\.\.\.(\w+)Option/g)].map(([, lib]) => lib)).toEqual(libs);
+    },
+  );
+
   test("refuses a hand-written ui/index.tsx beside the generated barrel, naming the file and the fix", async () => {
     const { lib } = await createScannableLib("shadowedbarrel", {
       files: {

package/integration/devStability.integration.test.ts

@@ -1,4 +1,5 @@
 import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
+import { AkanAppHost } from "../akanApp";
 import { DevGeneratedIndexSync } from "../frontendBuild";
 import { DevStabilityHarness, type DevStabilityHmrProbe } from "./devStabilityHarness";
 
@@ -467,7 +468,8 @@ export class FixtureService extends serve("fixture" as const, { serverMode: "bat
     const harness = await createHarness();
     const port = await harness.resolvePort();
     // Child 0's deterministic ws port, held the way an orphaned replica from a killed run would hold it.
-    const blocker = Bun.serve({ port: port + 10_000, fetch: () => new Response("occupied") });
+    //? On the child's own 127.0.0.1: macOS lets a loopback bind share a port a wildcard listener holds.
+    const blocker = Bun.serve({ port: port + 10_000, hostname: "127.0.0.1", fetch: () => new Response("occupied") });
     try {
       const host = await harness.startHost();
       await host.waitForLog(/falling back to an ephemeral port/);
@@ -583,9 +585,9 @@ describe("dev resource budgets", () => {
     expect(await DevStabilityHarness.buildWorkerProcess(host.proc.pid)).toBeNull();
   });
 
-  //? Between a fresh builder and one that has built a route, or the host stops enforcing it or never recycles.
-  //? macOS keeps the bundler arenas (~380MiB built); Linux measured 101-115MiB fresh, 157-176MiB built and settled.
-  const CEILING_MB = process.platform === "linux" ? 135 : 200;
+  //? Between a fresh builder and one that has built a route, or the host stops enforcing it or never recycles. Linux
+  //? measured 101-115MiB fresh, 157-176MiB built and settled; macOS's footprint (Bun 1.4.4) 65MiB fresh, 109MiB built.
+  const CEILING_MB = process.platform === "darwin" ? 87 : 135;
 
   budgetTest("recycles the builder at an unmeetable ceiling and keeps developing through it", async () => {
     const harness = await createHarness();
@@ -635,9 +637,11 @@ describe("dev resource budgets", () => {
       await host.waitForLogSince(mark, /pages-rebundle ok/, WAIT_MS).catch(() => undefined);
     }
     const settled = await DevStabilityHarness.builderProcess(host.proc.pid);
+    //? Read as the host reads it: on macOS `ps` also counts the pages the builder freed.
+    const settledRss = settled ? await AkanAppHost.readProcessRssBytes(settled.pid) : null;
     const warned = /ceiling costs about one boot build per interval/.test(host.logs.join("").slice(start));
     //? Past the interval (a slow machine) the next report recycles instead of warning: either answer settles it.
-    if ((settled?.rssBytes ?? 0) >= CEILING_MB * MB && !warned)
+    if ((settledRss ?? 0) >= CEILING_MB * MB && !warned)
       await host.waitForLogSince(
         settledFrom,
         /ceiling costs about one boot build per interval|recycling builder pid=\d+|skipped: the builder fell to/,

package/lint/gritRules.test.ts

@@ -11,7 +11,7 @@ import { Linter } from "../linter";
 const lintDir = import.meta.dir;
 const fixturesDir = path.join(lintDir, "__fixtures__");
 const workspaceRoot = path.resolve(lintDir, "../../../..");
-const biomeBin = path.join(workspaceRoot, "node_modules", ".bin", Linter.biomeBinName);
+const [biome, ...biomeArgs] = Linter.biomeCommand(workspaceRoot);
 
 interface BiomeDiagnostic {
   severity: string;
@@ -42,7 +42,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()));
@@ -127,7 +127,7 @@ const fixtures = await collectCases();
 
 describe("grit lint rules", () => {
   test("the harness found the biome binary and at least one fixture", () => {
-    expect(existsSync(biomeBin)).toBe(true);
+    expect(biome).toBe(process.execPath);
     expect(fixtures.length).toBeGreaterThan(0);
   });
 

package/linter.test.ts

@@ -1,5 +1,8 @@
 import { describe, expect, test } from "bun:test";
-import { type BiomeReport, parseBiomeReport } from "./linter";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { type BiomeReport, Linter, parseBiomeReport } from "./linter";
+import { hasBiome } from "./testHelpers";
 
 const reportOf = (diagnostics: BiomeReport["diagnostics"]): string =>
   JSON.stringify({ summary: { errors: diagnostics?.length ?? 0, warnings: 0 }, diagnostics });
@@ -77,3 +80,17 @@ describe("parseBiomeReport", () => {
     expect(() => parseBiomeReport("   \n")).toThrow("No Biome JSON output");
   });
 });
+
+describe("Linter", () => {
+  test.skipIf(!hasBiome || process.platform === "win32")("runs Biome where no node is on PATH", async () => {
+    const pathBefore = process.env.PATH;
+    process.env.PATH = path.join(tmpdir(), "akan-path-without-node");
+    try {
+      const { results, errors } = await new Linter(import.meta.dir).lintFile(path.join(import.meta.dir, "linter.ts"));
+      expect(results).toHaveLength(1);
+      expect(errors).toEqual([]);
+    } finally {
+      process.env.PATH = pathBefore;
+    }
+  });
+});

package/linter.ts

@@ -113,18 +113,21 @@ const emptyResult = (filePath: string): LintResult => ({
 });
 
 export class Linter {
-  //? Bun links a package bin as `<name>.exe` (plus a `.bunx` stub) on Windows, and a bare `<name>` elsewhere.
-  static readonly biomeBinName = process.platform === "win32" ? "biome.exe" : "biome";
+  //? The package's bin is npm's `#!/usr/bin/env node` wrapper, which picks the platform binary; run through the Bun
+  //? running akan, it works in an image with no Node (exit 127 otherwise). A Biome on PATH is the fallback.
+  static biomeCommand(root: string): [string, ...string[]] {
+    const wrapper = path.join(root, "node_modules", "@biomejs", "biome", "bin", "biome");
+    return existsSync(wrapper) ? [process.execPath, wrapper] : ["biome"];
+  }
 
   lintRoot: string;
   configPath: string;
-  #biomeBin: string;
+  #biomeCommand: [string, ...string[]];
 
   constructor(cwdPath: string) {
     this.lintRoot = this.#findBiomeRootPath(cwdPath);
     this.configPath = Linter.#configPathIn(this.lintRoot) ?? path.join(this.lintRoot, "biome.json");
-    const localBiomeBin = path.join(this.lintRoot, "node_modules", ".bin", Linter.biomeBinName);
-    this.#biomeBin = existsSync(localBiomeBin) ? localBiomeBin : "biome";
+    this.#biomeCommand = Linter.biomeCommand(this.lintRoot);
   }
 
   static #configPathIn(dir: string): string | null {
@@ -158,7 +161,8 @@ export class Linter {
       stderr: string;
       code: number | null;
     }>((resolve, reject) => {
-      const proc = spawn(this.#biomeBin, args, {
+      const [command, ...prefixArgs] = this.#biomeCommand;
+      const proc = spawn(command, [...prefixArgs, ...args], {
         cwd: this.lintRoot,
         stdio: ["pipe", "pipe", "pipe"],
       });