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

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/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/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"],
       });