@akanjs/devkit 3.0.2 → 3.1.0-rc.1

package/cloud/updatePackUpload.test.ts

@@ -0,0 +1,250 @@
+import { afterAll, beforeEach, describe, expect, test } from "bun:test";
+import { createHash } from "node:crypto";
+import { writeFile } from "node:fs/promises";
+import path from "node:path";
+import type { Workspace } from "../commandDecorators";
+import { tempDirs } from "../testHelpers";
+import { CloudApi } from "./cloudApi";
+import { UpdatePackUpload } from "./updatePackUpload";
+
+interface Put {
+  uploadId: string;
+  headers: Record<string, string>;
+  body: Uint8Array;
+}
+
+class FakeAkasys {
+  readonly server: ReturnType<typeof Bun.serve>;
+  readonly requests: Record<string, unknown>[] = [];
+  readonly puts: Put[] = [];
+  readonly commits: string[] = [];
+  readonly registrations: Record<string, string>[] = [];
+  putStatuses: number[] = [];
+  commitAnswers: (number | [number, string])[] = [];
+  release: Record<string, unknown> = { id: "release-1", status: "published", problems: [] };
+  requestRefusal: Response | null = null;
+
+  constructor() {
+    this.server = Bun.serve({ port: 0, hostname: "127.0.0.1", fetch: (request) => this.#route(request) });
+  }
+
+  get host() {
+    return `http://127.0.0.1:${this.server.port}`;
+  }
+
+  reset() {
+    this.requests.length = 0;
+    this.puts.length = 0;
+    this.commits.length = 0;
+    this.registrations.length = 0;
+    this.putStatuses = [];
+    this.commitAnswers = [];
+    this.requestRefusal = null;
+  }
+
+  async #route(request: Request) {
+    const url = new URL(request.url);
+    if (url.pathname === "/api/requestUpdateUpload/project-1") {
+      if (this.requestRefusal) return this.requestRefusal;
+      this.requests.push({ ...(await request.json()), authorization: request.headers.get("authorization") });
+      const uploadId = `upload-${this.requests.length}`;
+      return Response.json({
+        uploadId,
+        uploadUrl: `${this.host}/storage/${uploadId}?X-Amz-Signature=secret-signature`,
+        expiresAt: new Date(Date.now() + 15 * 60_000).toISOString(),
+        contentType: "application/gzip",
+      });
+    }
+    if (url.pathname.startsWith("/storage/") && request.method === "PUT") {
+      this.puts.push({
+        uploadId: url.pathname.slice("/storage/".length),
+        headers: Object.fromEntries(request.headers),
+        body: new Uint8Array(await request.arrayBuffer()),
+      });
+      return new Response(null, { status: this.putStatuses.shift() ?? 200 });
+    }
+    if (url.pathname === "/api/commitUpdateUpload/project-1") {
+      const { uploadId } = (await request.json()) as { uploadId: string };
+      this.commits.push(uploadId);
+      const answer = this.#answer();
+      if (answer) return answer;
+      return Response.json({ ...this.release, uploadId });
+    }
+    if (url.pathname === "/api/registerAppBinary/project-1") {
+      const form = await request.formData();
+      this.registrations.push(
+        Object.fromEntries(
+          [...form.entries()].map(([key, value]) => [key, typeof value === "string" ? value : "<file>"]),
+        ),
+      );
+      return this.#answer() ?? Response.json({ id: "binary-1" });
+    }
+    return new Response("not found", { status: 404 });
+  }
+
+  #answer() {
+    const answer = this.commitAnswers.shift();
+    if (!answer) return null;
+    const [status, key] = typeof answer === "number" ? [answer, "release.error.uploadCommitInProgress"] : answer;
+    return Response.json({ error: key }, { status });
+  }
+}
+
+const makeDir = tempDirs("akan-update-upload-");
+const akasys = new FakeAkasys();
+const api = new CloudApi({} as Workspace, {
+  host: akasys.host,
+  auth: { accessToken: { jwt: "jwt-1", refreshToken: null, expiresAt: null } },
+});
+const fields = { appName: "lu", target: "default", platform: "android" as const, channel: "develop", notes: null };
+const quick = { putRetryMs: 1, commitRetryMs: 1, cutOffWindowMs: 1_000, commitLimitMs: 1_000 };
+
+const archiveOf = async (bytes: string) => {
+  const archive = path.join(await makeDir(), "pack.tgz");
+  await writeFile(archive, bytes);
+  return archive;
+};
+
+beforeEach(() => akasys.reset());
+afterAll(() => akasys.server.stop(true));
+
+describe("UpdatePackUpload", () => {
+  test("announces the archive's size and digest, PUTs it with nothing but its content type, then commits", async () => {
+    const archive = await archiveOf("pack bytes");
+
+    const release = await new UpdatePackUpload(api, "project-1", quick).send(archive, fields);
+
+    expect(release).toEqual({ id: "release-1", status: "published", problems: [], uploadId: "upload-1" });
+    expect(akasys.requests).toEqual([
+      {
+        ...fields,
+        size: 10,
+        sha256: createHash("sha256").update("pack bytes").digest("hex"),
+        authorization: "Bearer jwt-1",
+      },
+    ]);
+    const [put] = akasys.puts;
+    expect(new TextDecoder().decode(put?.body)).toBe("pack bytes");
+    expect(put?.headers["content-type"]).toBe("application/gzip");
+    expect(put?.headers["content-length"]).toBe("10");
+    expect(put?.headers.authorization).toBeUndefined();
+    expect(Object.keys(put?.headers ?? {}).filter((name) => name.startsWith("x-amz-"))).toEqual([]);
+    expect(akasys.commits).toEqual(["upload-1"]);
+  });
+
+  test("takes one fresh ticket when storage answers 403, and gives up on the second without naming the URL", async () => {
+    const archive = await archiveOf("pack");
+    akasys.putStatuses = [403];
+
+    await new UpdatePackUpload(api, "project-1", quick).send(archive, fields);
+    expect(akasys.puts.map(({ uploadId }) => uploadId)).toEqual(["upload-1", "upload-2"]);
+    expect(akasys.commits).toEqual(["upload-2"]);
+
+    akasys.reset();
+    akasys.putStatuses = [403, 403];
+    const refusal = await new UpdatePackUpload(api, "project-1", quick).send(archive, fields).catch((e: Error) => e);
+    expect(String(refusal)).toContain("HTTP 403");
+    expect(String(refusal)).not.toContain("secret-signature");
+    expect(akasys.commits).toEqual([]);
+  });
+
+  test("retries a PUT the way curl --retry does, and stops at a refusal that is not transient", async () => {
+    const archive = await archiveOf("pack");
+    akasys.putStatuses = [503, 502];
+    await new UpdatePackUpload(api, "project-1", quick).send(archive, fields);
+    expect(akasys.puts.map(({ uploadId }) => uploadId)).toEqual(["upload-1", "upload-1", "upload-1"]);
+
+    akasys.reset();
+    akasys.putStatuses = [400];
+    await expect(new UpdatePackUpload(api, "project-1", quick).send(archive, fields)).rejects.toThrow("HTTP 400");
+    expect(akasys.puts).toHaveLength(1);
+  });
+
+  test("asks again with the same id while the commit is cut off or still running, but not past a real answer", async () => {
+    const archive = await archiveOf("pack");
+    akasys.commitAnswers = [524, 409, 502];
+    await new UpdatePackUpload(api, "project-1", quick).send(archive, fields);
+    expect(akasys.commits).toEqual(["upload-1", "upload-1", "upload-1", "upload-1"]);
+
+    akasys.reset();
+    akasys.commitAnswers = [404];
+    await expect(new UpdatePackUpload(api, "project-1", quick).send(archive, fields)).rejects.toThrow("404");
+    expect(akasys.commits).toEqual(["upload-1"]);
+
+    akasys.reset();
+    akasys.commitAnswers = Array.from({ length: 100 }, () => 524);
+    const cutOff = { putRetryMs: 1, commitRetryMs: 10, cutOffWindowMs: 35, commitLimitMs: 10_000 };
+    await expect(new UpdatePackUpload(api, "project-1", cutOff).send(archive, fields)).rejects.toThrow("524");
+    expect(akasys.commits.length).toBeLessThan(6);
+  });
+
+  test("keeps waiting on a live claim past the cut-off window, up to the overall limit", async () => {
+    const archive = await archiveOf("pack");
+    akasys.commitAnswers = [...Array.from({ length: 6 }, () => 409), 524, ...Array.from({ length: 6 }, () => 409)];
+    const timing = { putRetryMs: 1, commitRetryMs: 10, cutOffWindowMs: 25, commitLimitMs: 10_000 };
+    await new UpdatePackUpload(api, "project-1", timing).send(archive, fields);
+    expect(akasys.commits).toHaveLength(14);
+
+    akasys.reset();
+    akasys.commitAnswers = Array.from({ length: 100 }, () => 409);
+    const limited = { putRetryMs: 1, commitRetryMs: 10, cutOffWindowMs: 10_000, commitLimitMs: 35 };
+    await expect(new UpdatePackUpload(api, "project-1", limited).send(archive, fields)).rejects.toThrow("409");
+    expect(akasys.commits.length).toBeLessThan(6);
+  });
+
+  test("tells a server without staged uploads apart from one whose 404 is a refusal", async () => {
+    const archive = await archiveOf("pack");
+    akasys.requestRefusal = new Response("Not Found", { status: 404 });
+    await expect(new UpdatePackUpload(api, "project-1", quick).send(archive, fields)).rejects.toThrow(
+      "does not take direct pack uploads yet",
+    );
+
+    akasys.requestRefusal = Response.json({ error: "devProject.error.appNotFound", statusCode: 404 }, { status: 404 });
+    const refusal = await new UpdatePackUpload(api, "project-1", quick).send(archive, fields).catch((e: Error) => e);
+    expect(String(refusal)).toContain("devProject.error.appNotFound");
+    expect(akasys.puts).toEqual([]);
+  });
+
+  test("stops at once on a 409 that is not a commit in progress: the upload is already used", async () => {
+    const archive = await archiveOf("pack");
+    akasys.commitAnswers = [[409, "release.error.uploadEmbedded"]];
+    await expect(new UpdatePackUpload(api, "project-1", quick).send(archive, fields)).rejects.toThrow("uploadEmbedded");
+    expect(akasys.commits).toHaveLength(1);
+  });
+
+  test("stages a binary's pack and registers it by upload id, asking again while the server is still at it", async () => {
+    const archive = await archiveOf("pack");
+    akasys.commitAnswers = [524, 409];
+    const upload = new UpdatePackUpload(api, "project-1", quick);
+    const binary = await upload.stage(archive, fields).then((packUploadId) =>
+      upload.settle(() =>
+        api.registerAppBinary("project-1", {
+          appName: "lu",
+          target: "default",
+          distribution: "playTesting",
+          bundle: new Blob(["{}"]),
+          packUploadId,
+          channel: "develop",
+        }),
+      ),
+    );
+
+    expect(binary).toEqual({ id: "binary-1" });
+    expect(akasys.commits).toEqual([]);
+    expect(akasys.registrations).toHaveLength(3);
+    expect(akasys.registrations[2]).toEqual({
+      appName: "lu",
+      target: "default",
+      distribution: "playTesting",
+      channel: "develop",
+      bundle: "<file>",
+      packUploadId: "upload-1",
+    });
+  });
+
+  test("refuses an empty archive before asking for a ticket", async () => {
+    const archive = await archiveOf("");
+    await expect(new UpdatePackUpload(api, "project-1", quick).send(archive, fields)).rejects.toThrow("0 bytes");
+    expect(akasys.requests).toEqual([]);
+  });
+});

package/cloud/updatePackUpload.ts

@@ -0,0 +1,132 @@
+import { Logger, sleep } from "akanjs/common";
+import type { BunFile } from "bun";
+import { CloudApi, type CloudRecord, type UpdateUploadRequest } from "./cloudApi";
+
+interface UpdatePackUploadOptions {
+  putRetryMs?: number;
+  commitRetryMs?: number;
+  cutOffWindowMs?: number;
+  commitLimitMs?: number;
+}
+
+//* akasys sits behind Cloudflare's 100 s request cut, so the pack goes straight to its staging bucket and akasys
+//* only sees small calls: request a presigned PUT, then commit the object, or register a binary with it as its
+//* 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 #transientPut = new Set([0, 408, 429, 500, 502, 503, 504]);
+  readonly #api: CloudApi;
+  readonly #devProjectId: string;
+  readonly #putRetryMs: number;
+  readonly #commitRetryMs: number;
+  readonly #cutOffWindowMs: number;
+  readonly #commitLimitMs: number;
+
+  constructor(
+    api: CloudApi,
+    devProjectId: string,
+    {
+      putRetryMs = 1_000,
+      commitRetryMs = 10_000,
+      cutOffWindowMs = 15 * 60_000,
+      commitLimitMs = 60 * 60_000,
+    }: UpdatePackUploadOptions = {},
+  ) {
+    this.#api = api;
+    this.#devProjectId = devProjectId;
+    this.#putRetryMs = putRetryMs;
+    this.#commitRetryMs = commitRetryMs;
+    this.#cutOffWindowMs = cutOffWindowMs;
+    this.#commitLimitMs = commitLimitMs;
+  }
+
+  /** Stages the pack and commits it as a release of `fields.channel`. */
+  async send(archive: string, fields: Omit<UpdateUploadRequest, "size" | "sha256">): Promise<CloudRecord> {
+    const uploadId = await this.stage(archive, fields);
+    return await this.settle(() => this.#api.commitUpdateUpload(this.#devProjectId, uploadId));
+  }
+
+  /** 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)
+      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);
+    const upload = { ...fields, size: file.size, sha256: hasher.digest("hex") };
+    //? A URL lives 15 minutes and storage answers 403 past it: one fresh ticket, then the refusal is real.
+    for (let ticket = 1; ; ticket++) {
+      const { uploadId, uploadUrl, contentType } = await this.#request(upload);
+      const status = await this.#put(uploadUrl, contentType, file);
+      if (status >= 200 && status < 300) return uploadId;
+      if (status !== 403 || ticket === 2)
+        throw new Error(`The storage refused the pack upload (${status ? `HTTP ${status}` : "no response"}).`);
+    }
+  }
+
+  async #request(upload: UpdateUploadRequest) {
+    return await this.#api.requestUpdateUpload(this.#devProjectId, upload).catch((error: unknown) => {
+      //? A server older than staged uploads has no such route: its 404 is a page, where every refusal is an Err key.
+      const message = error instanceof Error ? error.message : String(error);
+      if (CloudApi.statusOf(error) === 404 && !/"error"\s*:\s*"[\w$-]+\.error\.[\w$-]+"/.test(message))
+        throw new Error(
+          "The project's server does not take direct pack uploads yet: update akasys and try again, or upload the pack from the project's release screen.",
+        );
+      throw error;
+    });
+  }
+
+  // The URL signs only its host: an unsigned x-amz-* header (a checksum included) makes storage refuse the PUT.
+  // A Bun fetch error names the URL, a bearer credential, so nothing but the status leaves this method.
+  async #put(url: string, contentType: string, file: BunFile) {
+    for (let retry = 0; ; retry++) {
+      const status = await fetch(url, { method: "PUT", body: file, headers: { "Content-Type": contentType } })
+        .then(async (response) => {
+          await response.arrayBuffer().catch(() => undefined);
+          return response.status;
+        })
+        .catch(() => 0);
+      if (retry === 3 || !UpdatePackUpload.#transientPut.has(status)) return status;
+      await sleep(this.#putRetryMs * (retry + 1));
+    }
+  }
+
+  /**
+   * Sends `call`, which consumes a staged upload, until the server answers it: the server finishes whoever stopped
+   * listening, and the same upload id answers the same record afterwards.
+   */
+  // `uploadCommitInProgress` is a live claim the server heartbeats, so only the overall limit bounds it; a run of
+  // cut-offs with none between them may be a server that died, whose claim lapses within minutes: the shorter window.
+  async settle<T>(call: () => Promise<T>): Promise<T> {
+    const limit = performance.now() + this.#commitLimitMs;
+    let cutOffSince: number | null = null;
+    for (;;) {
+      try {
+        return await call();
+      } catch (error) {
+        const now = performance.now();
+        if (UpdatePackUpload.#inProgress(error)) cutOffSince = null;
+        else if (UpdatePackUpload.#cutOff(error)) cutOffSince ??= now;
+        else throw error;
+        const deadline = cutOffSince === null ? limit : Math.min(limit, cutOffSince + this.#cutOffWindowMs);
+        if (now + this.#commitRetryMs > deadline) throw error;
+        Logger.rawLog(
+          `The project is still taking the pack; asking again in ${Math.round(this.#commitRetryMs / 1000)}s.`,
+        );
+        await sleep(this.#commitRetryMs);
+      }
+    }
+  }
+
+  //? Not every 409: an upload already committed or embedded is answered 409 too, and asking again changes nothing.
+  static #inProgress(error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    return CloudApi.statusOf(error) === 409 && message.includes("uploadCommitInProgress");
+  }
+
+  static #cutOff(error: unknown) {
+    const status = CloudApi.statusOf(error);
+    if (status === null) return !(error instanceof SyntaxError);
+    return status === 502 || status === 504 || (status >= 520 && status <= 527);
+  }
+}

package/commandDecorators/command.ts

@@ -288,9 +288,10 @@ export const getInternalArgumentValue = async (
 };
 
 export const runCommands = async (...commands: CommandCls[]) => {
+  let failureExitCode = 1;
   process.on("unhandledRejection", (error) => {
     printCliError(error);
-    process.exit(1);
+    process.exit(failureExitCode);
   });
   const __dirname = getDirname(import.meta.url);
   const packageJsonCandidates = [`${path.dirname(Bun.main)}/package.json`, `${__dirname}/../package.json`];
@@ -335,6 +336,10 @@ It may cause unexpected behavior. Run \`akan update\` to update latest akanjs.`,
         let programCommand = program.command(commandName, {
           hidden: targetMeta.targetOption.devOnly,
         });
+        const targetFailureExitCode = targetMeta.targetOption.failureExitCode;
+        //? commander exits 1 on a flag or argument it refuses, before any action runs.
+        if (targetFailureExitCode !== undefined)
+          programCommand.exitOverride((error) => process.exit(error.exitCode === 0 ? 0 : targetFailureExitCode));
         const [allArgMetas] = getArgMetas(command, targetMeta.key);
         for (const argMeta of allArgMetas) {
           if (argMeta.type === "Option") programCommand = handleOption(programCommand, argMeta);
@@ -364,6 +369,7 @@ It may cause unexpected behavior. Run \`akan update\` to update latest akanjs.`,
         };
 
         programCommand.action(async (...args: unknown[]) => {
+          failureExitCode = targetFailureExitCode ?? 1;
           if (!targetMeta.targetOption.stdio) Logger.rawLog();
           const cmdArgs = args.slice(0, args.length - 2);
           const opt = args[args.length - 2] as Record<string, unknown>;
@@ -413,6 +419,6 @@ It may cause unexpected behavior. Run \`akan update\` to update latest akanjs.`,
   // Handled here, not by the handler above: a rejection reaching the entry's top-level await prints Bun's own trace.
   await program.parseAsync(process.argv).catch((error: unknown) => {
     printCliError(error);
-    process.exit(1);
+    process.exit(failureExitCode);
   });
 };

package/commandDecorators/targetMeta.ts

@@ -43,6 +43,7 @@ export interface TargetOption {
   desc?: string;
   runsOnWorkspaceRoot?: boolean;
   stdio?: boolean;
+  failureExitCode?: number;
 }
 
 export const Commands = () => {

package/executors.test.ts

@@ -14,6 +14,7 @@ import {
 import { DevGeneratedIndexSync } from "./frontendBuild/devGeneratedIndexSync";
 import { AppInfo } from "./scanInfo";
 import {
+  createTempApp,
   createTempLib,
   formatWithBiome,
   hasBiome,
@@ -167,6 +168,26 @@ describe("Executor filesystem helpers", () => {
     expect(formatted).toEqual([path.join(root, "apps/demo/page/task/_index.tsx")]);
   });
 
+  test("an app hands its scaffolded files to the formatter too", async () => {
+    const { root, app } = trackRoot(await createTempApp("demo"));
+    const formatted: string[] = [];
+    app.getLinter = () =>
+      ({
+        fixFiles: async (filePaths: string[]) => {
+          formatted.push(...filePaths);
+          return { fixed: [] };
+        },
+      }) as unknown as ReturnType<Executor["getLinter"]>;
+
+    await app.applyTemplate({
+      basePath: "page/task",
+      template: "crudSinglePage",
+      dict: { model: "task", appName: "demo" },
+    });
+
+    expect(formatted).toEqual([path.join(root, "apps/demo/page/task/_index.tsx")]);
+  });
+
   test("a formatter that cannot run does not fail the scaffold", async () => {
     // create-akan-workspace scaffolds before `bun install`, so Biome may be absent; a lint fix beats a failed scaffold.
     const root = await makeTempRoot();

package/executors.ts

@@ -40,7 +40,7 @@ import {
   scanScopeRecipes,
   upsertAgentBlock,
 } from "./agentsIndex";
-import { AkanAppConfig, AkanLibConfig, decreaseBuildNum, increaseBuildNum } from "./akanConfig";
+import { AkanAppConfig, AkanLibConfig, AkanWorkspaceConfig, decreaseBuildNum, increaseBuildNum } from "./akanConfig";
 import { getRootBoundarySegments, isRootBoundarySegments } from "./artifact/implicitRootLayout";
 import { CodegenLock } from "./codegenLock";
 import { FileSys, getDirname } from "./fileSys";
@@ -533,6 +533,7 @@ export class Executor {
   async applyTemplate(options: {
     basePath: string;
     template: string;
+    scanInfo?: AppInfo | LibInfo | null;
     dict?: { [key: string]: string };
     options?: { [key: string]: unknown };
     overwrite?: boolean;
@@ -707,6 +708,12 @@ export class WorkspaceExecutor extends Executor {
   async scan(): Promise<WorkspaceInfo> {
     return await WorkspaceInfo.fromExecutor(this);
   }
+  #akanConfig: AkanWorkspaceConfig | null = null;
+  async getConfig({ refresh }: { refresh?: boolean } = {}) {
+    if (this.#akanConfig && !refresh) return this.#akanConfig;
+    this.#akanConfig = await AkanWorkspaceConfig.from(this, { bustImportCache: refresh });
+    return this.#akanConfig;
+  }
   async getApps() {
     return await this.#getDirHasFile(`${this.workspaceRoot}/apps`, "akan.config.ts");
   }
@@ -1091,7 +1098,7 @@ export class SysExecutor extends Executor {
     overwrite?: boolean;
   }): Promise<FileContent[]> {
     const scanInfo = await this.scan();
-    const fileContents = await this._applyTemplate({ ...options, scanInfo, dict: withCapitalizedDict(options.dict) });
+    const fileContents = await super.applyTemplate({ ...options, scanInfo });
     await this.scan();
     return fileContents;
   }

package/frontendBuild/csrArtifactBuilder.ts

@@ -18,11 +18,19 @@ export class CsrArtifactBuilder {
   #app: App;
   #command: "build" | "start";
   #lang: string;
+  #cssAssets: Record<string, CssAsset> | null;
 
-  constructor(app: App, command: "build" | "start" = "start", lang = "en") {
+  //? `cssAssets` is a dev batch's current stylesheets: `base-artifact.json` keeps the ones the boot build compiled.
+  constructor(
+    app: App,
+    command: "build" | "start" = "start",
+    lang = "en",
+    { cssAssets = null }: { cssAssets?: Record<string, CssAsset> | null } = {},
+  ) {
     this.#app = app;
     this.#command = command;
     this.#lang = lang;
+    this.#cssAssets = cssAssets;
   }
 
   async build(): Promise<BuildCsrArtifactResult | null> {
@@ -152,6 +160,7 @@ void bootCsr(pages);
   }
 
   async #loadCssAssets(): Promise<Record<string, CssAsset>> {
+    if (this.#cssAssets) return this.#cssAssets;
     const artifactFile = Bun.file(path.join(this.#artifactDir, "base-artifact.json"));
     if (!(await artifactFile.exists())) return {};
     const artifact = (await artifactFile.json()) as Partial<Pick<BaseBuildArtifact, "cssAssets">>;

package/frontendBuild/cssCandidateCache.test.ts

@@ -23,6 +23,16 @@ describe("CssCandidateCache token extraction", () => {
     expect(candidates).not.toContain("_td");
   });
 
+  test("keeps Tailwind v4's variable shorthand whole, and leaves a call's argument its own candidate", async () => {
+    const candidates = await scan(
+      `const c = "max-md:top-(--keyboard-top) min-h-(--x) bg-(color:--brand)/50"; cn("flex"); fn(value);`,
+    );
+    expect(candidates).toEqual(
+      expect.arrayContaining(["max-md:top-(--keyboard-top)", "min-h-(--x)", "bg-(color:--brand)/50", "flex"]),
+    );
+    expect(candidates).not.toContain("-keyboard-top");
+  });
+
   test("ignores a labelled tuple type that only looks like an arbitrary property", async () => {
     const candidates = await scan(
       `type A = [key: string, make: () => unknown][];\ntype B = [setQueryArgs: (a: Args) => Args, options?: Policy];`,

package/frontendBuild/cssCandidateCache.ts

@@ -2,7 +2,9 @@ import { stat } from "node:fs/promises";
 
 // The leading `[` alternation keeps arbitrary variants (`[&_td]:px-3`) whole. Brackets hold no whitespace: a labelled
 // tuple type scanned as a class compiles to a rule lightningcss cannot parse, and it then drops every variant rule.
-const CANDIDATE_RE = /-?(?:[\w@]|\[[^\]\s]+\])[\w:/.-]*(?:\[[^\]\s]+\][\w:/.-]*)*/g;
+// Parentheses pass only as Tailwind v4's variable shorthand, `(--x)` or `(length:--x)`, so `cn("flex")` still yields
+// `flex` on its own.
+const CANDIDATE_RE = /-?(?:[\w@]|\[[^\]\s]+\])[\w:/.-]*(?:(?:\[[^\]\s]+\]|\((?:[a-z-]+:)?--[^)\s]+\))[\w:/.-]*)*/g;
 
 interface CachedFile {
   mtimeMs: number;
@@ -18,7 +20,7 @@ interface CacheFile {
 /** Tailwind candidates per source file, on disk: the batch worker that compiles CSS exits before the next save. */
 export class CssCandidateCache {
   // Bump when the token regex or the entry shape changes, so stale extractions are not reused.
-  static readonly #version = 3;
+  static readonly #version = 4;
   readonly #path: string;
   readonly #entries = new Map<string, CachedFile>();
   #dirty = false;

package/frontendBuild/pagesBundleBuilder.ts

@@ -32,11 +32,13 @@ export class PagesBundleBuilder {
   #command: "build" | "start";
   #pageEntries?: PageEntry[];
   #started = Date.now();
+  #serverEnv: BunPlugin | undefined;
 
-  constructor(app: App, command: "build" | "start" = "start", pageEntries?: PageEntry[]) {
+  constructor(app: App, command: "build" | "start" = "start", pageEntries?: PageEntry[], serverEnv?: BunPlugin) {
     this.#app = app;
     this.#command = command;
     this.#pageEntries = pageEntries;
+    this.#serverEnv = serverEnv;
   }
 
   async build(): Promise<BuildPagesBundleResult> {
@@ -67,6 +69,8 @@ export class PagesBundleBuilder {
       define: bundleDefine(this.#app, this.#command, "ssr"),
       metafile: dev,
       plugins: [
+        //? First: the use-client plugins below load every module, and an env file must be swapped before they do.
+        ...(this.#serverEnv ? [this.#serverEnv] : []),
         PagesBundleBuilder.createPagesEntryPlugin(entrySource),
         PagesBundleBuilder.createCssStubPlugin(),
         PagesBundleBuilder.createServerUseClientFetchPlugin(),

package/frontendBuild/ssrBaseArtifactBuilder.ts

@@ -2,6 +2,7 @@ import path from "node:path";
 import { optimize } from "@tailwindcss/node";
 import type { AkanNativeAppId, AkanWebConfig } from "akanjs";
 import type { BaseBuildArtifact } from "akanjs/server";
+import type { BunPlugin } from "bun";
 import { resolveSsrPageEntriesForApp } from "../artifact/implicitRootLayout";
 import { computeRouteSeedIndex, type RouteSeedIndex, saveRouteSeedIndex } from "../artifact/routeSeedIndex";
 import type { App } from "../commandDecorators";
@@ -29,10 +30,13 @@ export class SsrBaseArtifactBuilder {
   #artifactDir: string;
   #absArtifactDir: string;
   #started = Date.now();
+  #serverEnv: BunPlugin | undefined;
 
-  constructor(app: App, command: "build" | "start" = "start") {
+  /** `serverEnv`: the build's server env plugin, so the route bundle carries the env files the backend does and no more. */
+  constructor(app: App, command: "build" | "start" = "start", { serverEnv }: { serverEnv?: BunPlugin } = {}) {
     this.#app = app;
     this.#command = command;
+    this.#serverEnv = serverEnv;
     this.#artifactDir = `${command === "build" ? app.dist.cwdPath : app.cwdPath}/.akan/artifact`;
     this.#absArtifactDir = path.resolve(this.#artifactDir);
   }
@@ -52,7 +56,7 @@ export class SsrBaseArtifactBuilder {
 
     const pageEntries = await resolveSsrPageEntriesForApp(this.#app, pageKeys);
     const { cssCompiler, optimizedFonts, cssAssets } = await this.#buildStyleAssets();
-    const pagesBundle = await new PagesBundleBuilder(this.#app, this.#command, pageEntries).build();
+    const pagesBundle = await new PagesBundleBuilder(this.#app, this.#command, pageEntries, this.#serverEnv).build();
     this.#app.verbose(
       `[base-artifact] pages bundle -> ${pagesBundle.bundlePath} (buildId=${pagesBundle.buildId}, splitting=${pagesBundle.splitting}, entry=${pagesBundle.entryBytes} bytes, outputs=${pagesBundle.outputCount}, chunks=${pagesBundle.chunkCount}, total=${pagesBundle.outputBytes} bytes)`,
     );

package/incrementalBuilder/buildBatch.proc.ts

@@ -35,6 +35,7 @@ class BuildBatch {
   async run(): Promise<BuildBatchResult> {
     if (this.#request.needs.includes("base")) await this.#buildBase();
     if (this.#request.needs.includes("csr")) await this.#buildCsr();
+    if (this.#request.needs.includes("shell")) await this.#buildShell();
     if (this.#request.needs.includes("ssr")) await this.#buildSsrRegistry();
     // Css before pages: it scans the sources and reads nothing pages produces, so a class edit need not wait for pages.
     if (this.#request.needs.includes("css")) await this.#buildCss();
@@ -72,7 +73,7 @@ class BuildBatch {
     const message = ApplicationBuildReporter.formatError(err, this.#request.workspaceRoot);
     this.#logger.error(`${label} failed: ${message}`);
     this.#result.errors[need] = message;
-    if (need !== "base") this.#emitStatus(need, message);
+    if (need !== "base" && need !== "shell") this.#emitStatus(need, message);
   }
 
   // Streams nothing: the builder is not serving yet, so the watcher reads the outcome from the batch result.
@@ -99,8 +100,19 @@ class BuildBatch {
     }
   }
 
+  //? No `csr-updated`: under the registry no tab runs this build, and the reload would send every CSR tab back to it.
+  async #buildShell(): Promise<void> {
+    const started = Date.now();
+    try {
+      await new CsrArtifactBuilder(this.#app, "start", "en", { cssAssets: this.#request.cssAssets }).build();
+      this.#logger.verbose(`csr-shell ok (${Date.now() - started}ms)`);
+    } catch (err) {
+      this.#fail("shell", "csr-shell", err);
+    }
+  }
+
   async #rebuildCsrArtifact(started: number): Promise<void> {
-    await new CsrArtifactBuilder(this.#app).build();
+    await new CsrArtifactBuilder(this.#app, "start", "en", { cssAssets: this.#request.cssAssets }).build();
     this.#logger.verbose(`csr-rebundle ok (${Date.now() - started}ms)`);
     // A CSR tab takes none of the SSR refresh messages, so a rebuilt artifact reaches it only as this reload.
     if (this.#request.changedFiles.length === 0) return;