@akanjs/devkit 3.0.2 → 3.1.0-rc.0

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/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;

package/incrementalBuilder/buildBatchProtocol.ts

@@ -3,8 +3,9 @@ import type { BaseBuildArtifact, CssPayload, HmrTrace, PagesBundlePayload } from
 
 export type OptimizedFonts = Awaited<ReturnType<FontOptimizer["optimize"]>>;
 
-// `base` is the boot build: it always runs alone, before the builder can serve anything.
-export type BuildBatchNeed = "base" | "pages" | "css" | "csr" | "ssr";
+// `base` is the boot build: it always runs alone, before the builder can serve anything. `shell` is the single-file
+// CSR build an MCP Apps view needs under the dev CSR registry, made on request and reported to no tab.
+export type BuildBatchNeed = "base" | "pages" | "css" | "csr" | "ssr" | "shell";
 
 // JSON only: the worker is spawned per batch and receives this in its argv.
 export interface BuildBatchRequest {

package/incrementalBuilder/incrementalBuilder.proc.test.ts

@@ -82,6 +82,102 @@ process.send({ type: "build-batch-result", data: { generation, errors: {}, artif
     expect(log).toContain(reason);
   }, 30_000);
 
+  test("builds a view's shell once on request, answers with its failure, and reports it to no tab", async () => {
+    const { root } = track(await createTempApp("demo"));
+    const appDir = path.join(root, "apps/demo");
+    // A stand-in batch: boots, and fails a shell batch by naming the needs it was handed.
+    await writeText(
+      path.join(root, "pkgs/@akanjs/devkit/incrementalBuilder/buildBatch.proc.ts"),
+      `const { generation, needs } = JSON.parse(process.argv[2]);
+const errors = needs.includes("base") ? {} : { shell: "handed " + needs.join(",") };
+process.send({ type: "build-batch-result", data: { generation, errors, artifact: {}, optimizedFonts: { css: "", files: [] } } });
+`,
+    );
+    await writeText(path.join(appDir, "page/_index.tsx"), "export default () => null;\n");
+    const messages: BuilderMessage[] = [];
+    const proc = Bun.spawn(["bun", path.join(import.meta.dir, "incrementalBuilder.proc.ts")], {
+      cwd: appDir,
+      env: {
+        ...process.env,
+        AKAN_WORKSPACE_ROOT: root,
+        AKAN_PUBLIC_APP_NAME: "demo",
+        AKAN_PUBLIC_REPO_NAME: "repo",
+        AKAN_PUBLIC_SERVE_DOMAIN: "localhost",
+        AKAN_PUBLIC_ENV: "local",
+        AKAN_WATCH: "0",
+      },
+      stdio: ["ignore", "ignore", "pipe"],
+      serialization: "advanced",
+      ipc: (message: BuilderMessage) => {
+        messages.push(message);
+      },
+    });
+    try {
+      await until(proc, "builder-ready", () => messages.some((message) => message.type === "builder-ready"));
+      proc.send({ type: "build-csr", id: 7, reason: "mcp app view", shell: true } satisfies BuilderMessage);
+      await until(proc, "build-csr-res", () => messages.some((message) => message.type === "build-csr-res"));
+    } finally {
+      proc.kill();
+      await proc.exited;
+    }
+    expect(messages.find((message) => message.type === "build-csr-res")).toEqual({
+      type: "build-csr-res",
+      id: 7,
+      ok: false,
+      error: "handed shell",
+    });
+    expect(messages.some((message) => message.type === "build-status")).toBe(false);
+  }, 30_000);
+
+  test("answers a second shell request in the same generation without building again", async () => {
+    const { root } = track(await createTempApp("demo"));
+    const appDir = path.join(root, "apps/demo");
+    const ledger = path.join(root, "batches.log");
+    await writeText(
+      path.join(root, "pkgs/@akanjs/devkit/incrementalBuilder/buildBatch.proc.ts"),
+      `const { generation, needs } = JSON.parse(process.argv[2]);
+require("node:fs").appendFileSync(${JSON.stringify(ledger)}, needs.join(",") + "\\n");
+process.send({ type: "build-batch-result", data: { generation, errors: {}, artifact: {}, optimizedFonts: { css: "", files: [] } } });
+`,
+    );
+    await writeText(path.join(appDir, "page/_index.tsx"), "export default () => null;\n");
+    const messages: BuilderMessage[] = [];
+    const proc = Bun.spawn(["bun", path.join(import.meta.dir, "incrementalBuilder.proc.ts")], {
+      cwd: appDir,
+      env: {
+        ...process.env,
+        AKAN_WORKSPACE_ROOT: root,
+        AKAN_PUBLIC_APP_NAME: "demo",
+        AKAN_PUBLIC_REPO_NAME: "repo",
+        AKAN_PUBLIC_SERVE_DOMAIN: "localhost",
+        AKAN_PUBLIC_ENV: "local",
+        AKAN_WATCH: "0",
+      },
+      stdio: ["ignore", "ignore", "pipe"],
+      serialization: "advanced",
+      ipc: (message: BuilderMessage) => {
+        messages.push(message);
+      },
+    });
+    const answers = () => messages.filter((message) => message.type === "build-csr-res");
+    try {
+      await until(proc, "builder-ready", () => messages.some((message) => message.type === "builder-ready"));
+      proc.send({ type: "build-csr", id: 7, reason: "mcp app view", shell: true } satisfies BuilderMessage);
+      await until(proc, "the first build-csr-res", () => answers().length === 1);
+      proc.send({ type: "build-csr", id: 8, reason: "mcp app view", shell: true } satisfies BuilderMessage);
+      await until(proc, "the second build-csr-res", () => answers().length === 2);
+    } finally {
+      proc.kill();
+      await proc.exited;
+    }
+    expect(answers()).toEqual([
+      { type: "build-csr-res", id: 7, ok: true },
+      { type: "build-csr-res", id: 8, ok: true },
+    ]);
+    const batches = (await Bun.file(ledger).text()).trim().split("\n");
+    expect(batches.filter((needs) => needs === "shell")).toHaveLength(1);
+  }, 30_000);
+
   test("a killed boot build is tried again after the crash window, before boot-armed; a route build's check waits likewise", async () => {
     // Inside the checkout so the route's client bundle resolves the framework from its source.
     const { root } = track(await createTempApp("demo", path.join(import.meta.dir, "..", "local")));

package/incrementalBuilder/incrementalBuilder.proc.ts

@@ -63,6 +63,7 @@ class IncrementalBuilder {
   #autoImportSync: AutoImportSync;
   #watcher: HmrWatcher | null = null;
   #generation = 0;
+  #shellGeneration: number | null = null;
   #discoveredThrough = 0;
   #csrActive = IncrementalBuilder.#csrArmedByEnv();
   #csrBundler: CsrDevBundler;
@@ -798,7 +799,7 @@ class IncrementalBuilder {
       if (crashedNeeds.includes("ssr")) this.#ssrPatcher?.releaseHandedOver();
       // `base` is not a `BuildPhase` and never comes through here: `#buildBootDeps` throws into the degraded boot.
       for (const need of crashedNeeds)
-        if (need !== "base")
+        if (need !== "base" && need !== "shell")
           this.#sendBuildStatus(need, {
             generation,
             ok: false,
@@ -874,6 +875,10 @@ class IncrementalBuilder {
 
   // On demand: dev serves CSR only via the opt-in `/__csr` and `?csr=true` routes; once built, it rebuilds every save.
   async handleBuildCsr(msg: BuilderCsrReq): Promise<void> {
+    if (msg.shell) {
+      await this.#buildShell(msg);
+      return;
+    }
     //? Armed now, not when the build lands: a save handled meanwhile then patches CSR behind #csrGate instead of skipping.
     this.#beginCsrArm();
     this.#csrActive = true;
@@ -903,6 +908,30 @@ class IncrementalBuilder {
     await armed;
   }
 
+  // Asked on every view read and rebuilt only when a save moved the generation, instead of armed per save: a restarted
+  // builder has no last build to trust, and so rebuilds once on the next read.
+  async #buildShell(msg: BuilderCsrReq): Promise<void> {
+    await this.#workQueue.enqueue("build-shell", async (): Promise<void> => {
+      const generation = this.#generation;
+      let error: string | undefined;
+      if (this.#shellGeneration !== generation)
+        try {
+          const result = await this.#batchRunner.run(
+            await this.#batchRequest({ generation, needs: ["shell"], changedFiles: [] }),
+          );
+          error = result.errors.shell;
+          if (!error) this.#shellGeneration = generation;
+        } catch (err) {
+          error = ApplicationBuildReporter.formatError(err, this.#app.workspace.workspaceRoot);
+        }
+      await BuilderChannel.send(
+        error
+          ? { type: "build-csr-res", id: msg.id, ok: false, error }
+          : { type: "build-csr-res", id: msg.id, ok: true },
+      );
+    });
+  }
+
   //? Settled by the last of the arming builds in flight, not by each: two requests that both fail would otherwise leave
   //? CSR on (the second saw the first's optimistic flag as where it started), and the first to finish would let saves
   //? patch CSR first while the second still builds.

package/lint/__fixtures__/no-import-external-library-in-test/bad.tsx

@@ -0,0 +1,6 @@
+import dayjs from "dayjs"; // @flag
+import { z } from "zod"; // @flag
+import fs from "node:fs"; // @ok
+import { Database } from "bun:sqlite"; // @ok
+import { describe } from "bun:test"; // @ok
+import { cnst } from "../cnst"; // @ok

package/lint/__fixtures__/no-import-external-library-in-test/good.tsx

@@ -0,0 +1,6 @@
+import { mkdtemp } from "node:fs/promises"; // @ok
+import { createServer } from "node:net"; // @ok
+import { tmpdir } from "node:os"; // @ok
+import { Database } from "bun:sqlite"; // @ok
+import { describe, expect, test } from "bun:test"; // @ok
+import { fetch } from "../sig"; // @ok

package/lint/no-import-external-library-in-test.grit

@@ -0,0 +1,24 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// A module test still reaches vendors through a lib, but it may use the runtime's own primitives — a temp dir, a
+// socket, sqlite — that a module file leaves to srvkit/.
+JsModuleSource() as $source where {
+  $source <: within JsImport(),
+  not $source <: or {
+    r"\"\..*",
+    r"\"akanjs.*",
+    r"\"@akanjs.*",
+    r"\"@playwright.*",
+    r"\"@apps/.*",
+    r"\"@libs/.*",
+    r"\"@pkgs/.*",
+    r"\"bun:.*",
+    r"\"node:.*",
+    r"\"react.*"
+  },
+  register_diagnostic(
+    span = $source,
+    message = "External libraries should not be imported in a module test. Only internal packages and the runtime's node: and bun: modules are permitted."
+  )
+}

package/mobile/desktopServerStage.test.ts

@@ -46,6 +46,12 @@ describe("DesktopServerStage", () => {
     });
     expect(env.PORT).toBeUndefined();
     expect(env.AKAN_LOG_TO_FILE).toBeUndefined();
+    expect(env.AKAN_MODULES).toBeUndefined();
+    expect(DesktopServerStage.env(appConfig(), "main", { modules: ["@edge", "edgeAgent"] }).AKAN_MODULES).toBe(
+      "@edge,edgeAgent",
+    );
+    const withEnv = DesktopServerStage.env(appConfig(), "main", { env: { CLOUD_ORIGIN: "https://cloud.example" } });
+    expect(withEnv).toMatchObject({ CLOUD_ORIGIN: "https://cloud.example", AKAN_PUBLIC_OPERATION_MODE: "edge" });
   });
 
   test("installs what the image does, minus the RSC renderer and the other modes' drivers", () => {