@akanjs/devkit 3.0.2-rc.0 → 3.1.0-rc.0

package/cloud/updatePackUpload.test.ts

@@ -0,0 +1,195 @@
+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[] = [];
+  putStatuses: number[] = [];
+  commitAnswers: number[] = [];
+  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.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.commitAnswers.shift();
+      if (answer) return Response.json({ error: "release.error.uploadCommitInProgress" }, { status: answer });
+      return Response.json({ ...this.release, uploadId });
+    }
+    return new Response("not found", { status: 404 });
+  }
+}
+
+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("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,115 @@
+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 two small JSON calls: request a presigned PUT, then commit the object, which akasys re-hashes.
+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;
+  }
+
+  async send(archive: string, fields: Omit<UpdateUploadRequest, "size" | "sha256">): Promise<CloudRecord> {
+    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 await this.#commit(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));
+    }
+  }
+
+  // The server finishes a commit whoever stopped listening, and the same id answers the same release afterwards.
+  // A 409 is a live claim the server heartbeats, so only the overall limit bounds it; a run of cut-offs with no 409
+  // between them may be a server that died, whose claim lapses within minutes, so that run gets the shorter window.
+  async #commit(uploadId: string) {
+    const limit = performance.now() + this.#commitLimitMs;
+    let cutOffSince: number | null = null;
+    for (;;) {
+      try {
+        return await this.#api.commitUpdateUpload(this.#devProjectId, uploadId);
+      } catch (error) {
+        const now = performance.now();
+        if (CloudApi.statusOf(error) === 409) 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);
+      }
+    }
+  }
+
+  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/createTunnel.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, spyOn, test } from "bun:test";
+import { Client } from "ssh2";
+import { createTunnel } from "./createTunnel";
+import { createTempApp, isolateEnv, tempRoots } from "./testHelpers";
+
+describe("createTunnel", () => {
+  isolateEnv({ AKAN_PUBLIC_REPO_NAME: "repo", AKAN_PUBLIC_SERVE_DOMAIN: "localhost", AKAN_PUBLIC_ENV: "testing" });
+  const track = tempRoots();
+
+  test("describes a refused Redis SSH connection and preserves its cause", async () => {
+    const { app } = track(await createTempApp("demo"));
+    const listener = Bun.listen({ hostname: "127.0.0.1", port: 0, socket: { data() {} } });
+    const port = listener.port;
+    listener.stop(true);
+    process.env.SSH_TUNNEL_PORT = String(port);
+
+    let originalError: Error | undefined;
+    const connect = Client.prototype.connect;
+    const observeConnect = spyOn(Client.prototype, "connect").mockImplementation(function (this: Client, options) {
+      this.once("error", (error: Error) => {
+        originalError = error;
+      });
+      return connect.call(this, options);
+    });
+    let failure: unknown;
+    try {
+      await createTunnel("redis", { app, environment: "testing" });
+    } catch (error) {
+      failure = error;
+    } finally {
+      observeConnect.mockRestore();
+    }
+    expect(failure).toBeInstanceOf(Error);
+    if (!(failure instanceof Error)) throw new Error("expected tunnel failure");
+    expect(failure.message).toContain("redis");
+    expect(failure.message).toContain(`demo-testing.localhost:${port}`);
+    expect(failure.message).toContain("redis-0.redis-svc.demo-testing.svc.cluster.local:6379");
+    expect(failure.message).toContain("ECONNREFUSED");
+    expect(failure.cause).toBeInstanceOf(Error);
+    expect(failure.cause).toBe(originalError);
+    expect(failure.cause).not.toBe(failure);
+    if (!(failure.cause instanceof Error)) throw new Error("expected original SSH error");
+    const reasons = failure.cause instanceof AggregateError ? failure.cause.errors : [failure.cause];
+    expect(reasons.length).toBeGreaterThan(0);
+    for (const reason of reasons) {
+      expect(reason).toBeInstanceOf(Error);
+      expect(reason.message).toContain("ECONNREFUSED");
+      expect(failure.message).toContain(reason.message);
+    }
+  });
+});

package/createTunnel.ts

@@ -11,19 +11,37 @@ export const createTunnel = async (
   { app, environment, port = service === "postgres" ? 5432 : 6379 }: TunnelOption,
 ) => {
   const { serveDomain, repoName } = WorkspaceExecutor.getBaseDevEnv();
-  await createSshTunnel({
-    localHost: "0.0.0.0",
-    localPort: port,
-    srcHost: "0.0.0.0",
-    srcPort: port,
-    dstHost: `${service}-0.${service}-svc.${app.name}-${environment}.svc.cluster.local`,
-    dstPort: service === "postgres" ? 5432 : 6379,
-    sshOptions: {
-      host: `${app.name}-${environment}.${serveDomain}`,
-      port: process.env.SSH_TUNNEL_PORT ? parseInt(process.env.SSH_TUNNEL_PORT) : 32767,
-      username: process.env.SSH_TUNNEL_USERNAME ?? "root",
-      password: process.env.SSH_TUNNEL_PASSWORD ?? repoName,
-    },
-  });
+  const host = `${app.name}-${environment}.${serveDomain}`;
+  const sshPort = process.env.SSH_TUNNEL_PORT ? parseInt(process.env.SSH_TUNNEL_PORT) : 32767;
+  const dstHost = `${service}-0.${service}-svc.${app.name}-${environment}.svc.cluster.local`;
+  const dstPort = service === "postgres" ? 5432 : 6379;
+  try {
+    await createSshTunnel({
+      localHost: "0.0.0.0",
+      localPort: port,
+      srcHost: "0.0.0.0",
+      srcPort: port,
+      dstHost,
+      dstPort,
+      sshOptions: {
+        //? RFC 6761 makes *.localhost loopback, but only macOS resolves it; glibc without systemd-resolved and Windows answer ENOTFOUND
+        host: host.endsWith(".localhost") ? "localhost" : host,
+        port: sshPort,
+        username: process.env.SSH_TUNNEL_USERNAME ?? "root",
+        password: process.env.SSH_TUNNEL_PASSWORD ?? repoName,
+      },
+    });
+  } catch (error) {
+    const reasons =
+      error instanceof AggregateError
+        ? error.errors.map((reason) => (reason instanceof Error ? reason.message : String(reason))).join("; ")
+        : error instanceof Error
+          ? error.message
+          : String(error);
+    throw new Error(
+      `Could not open the ${service} tunnel for ${app.name}-${environment}: SSH ${host}:${sshPort} -> ${dstHost}:${dstPort} failed (${reasons})`,
+      { cause: error },
+    );
+  }
   return `localhost:${port}`;
 };

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)`,
     );