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

package/abstractDoc.ts

@@ -26,7 +26,7 @@ export class AbstractDoc {
   static async findAll(sys: SysExecutor, { module }: { module?: string | null } = {}) {
     const filePaths = (await sys.getAllFiles(`${AbstractDoc.#facetRoots}/**/*${AbstractDoc.suffix}`))
       .map((filePath) => filePath.split(path.sep).join("/"))
-      .sort();
+      .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
     const docs = await Promise.all(filePaths.map((filePath) => AbstractDoc.read(sys, filePath)));
     if (!module) return docs;
     return docs.filter((doc) => doc.moduleName === module || doc.folderName === module);

package/agentsIndex.test.ts

@@ -86,6 +86,9 @@ describe("collectScopeRecipeSources", () => {
     await write("libs/shared/ui/Recipe/panel.ts", `export const panelRecipe = recipe(tv({ base: "y" }));`);
     await write("pkgs/akanjs/ui/recipe/buttonRecipe.ts", `export const buttonRecipe = recipe(tv({ base: "z" }));`);
     const sources = await collectScopeRecipeSources(root, { type: "app", name: "minimal" }, ["shared"]);
-    expect(sources.map((source) => source.importFrom).sort()).toEqual(["@apps/minimal/ui", "@libs/shared/ui"]);
+    expect(sources.map((source) => source.importFrom).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))).toEqual([
+      "@apps/minimal/ui",
+      "@libs/shared/ui",
+    ]);
   });
 });

package/akanConfig/akanConfig.test.ts

@@ -518,10 +518,14 @@ describe("AkanAppConfig", () => {
       watchdog: { intervalMs: 10_000, failures: 5 },
     });
     expect(() => resolve({ env: { SLACK_WEBHOOK_URL: "https://hooks" } })).toThrow("SLACK_WEBHOOK_URL");
-    expect(() => resolve({ env: { AKAN_MODULES: "@edge" } })).toThrow("the carried server's stage owns");
+    for (const key of ["AKAN_MODULES", "AKAN_MCP", "AKAN_SHUTDOWN_TIMEOUT_MS"])
+      expect(() => resolve({ env: { [key]: "1" } })).toThrow(`sets ${key}, which the carried server's stage owns`);
     expect(() => resolve({ env: { PORT: 1 } })).toThrow("must be an object of strings");
     expect(() => resolve({ restart: 0 })).toThrow('must be "forever" or a count');
-    expect(() => resolve({ watchdog: { intervalMs: -1 } })).toThrow("watchdog in apps/");
+    for (const watchdog of [{ intervalMs: -1 }, null, 5, [], { interval: 5_000 }])
+      expect(() => resolve({ watchdog })).toThrow(
+        "native.desktop.server.watchdog in apps/portal/akan.config.ts must be",
+      );
   });
 
   test("an app without basePaths has one target, default, with no basePath and the section's settings", () => {
@@ -630,6 +634,30 @@ describe("AkanAppConfig", () => {
     ).toThrow("native.updates in apps/portal/akan.config.ts has no url or publicKeys.");
   });
 
+  test("refuses updates holding both publicKey and publicKeys, a target's own key beside the section's list included", () => {
+    const url = "https://releases.example.com/portal";
+    const resolve = (native: object) =>
+      new AkanAppConfig(app, [], packageJson, { native } as never, baseDevEnv).native.targets;
+
+    expect(() =>
+      resolve({
+        updates: { url, publicKeys: ["a="] },
+        targets: { store: {}, pilot: { updates: { publicKey: "p=" } } },
+      }),
+    ).toThrow(
+      "native.targets.pilot.updates in apps/portal/akan.config.ts has both publicKey and publicKeys, native.updates merged in",
+    );
+    expect(() => resolve({ updates: { url, publicKey: "a=", publicKeys: ["b="] } })).toThrow(
+      "native.updates in apps/portal/akan.config.ts has both publicKey and publicKeys: give one.",
+    );
+    expect(
+      resolve({
+        updates: { url, publicKeys: ["a="] },
+        targets: { store: {}, pilot: { updates: { publicKeys: ["p="] } } },
+      }).pilot.updates,
+    ).toEqual({ url, publicKeys: ["p="] });
+  });
+
   test("merges the desktop settings field by field, the target winning", () => {
     const config = new AkanAppConfig(
       app,
@@ -949,7 +977,7 @@ describe("pipeline and workspace keys in app and lib configs", () => {
       "export default { subspace: { subspaces: [] } };\n",
       "export default {};\n",
     );
-    expect(loading).rejects.toThrow("a workspace setting");
+    await expect(loading).rejects.toThrow("a workspace setting");
   });
 
   test("a lib takes neither a pipeline nor a subspace", async () => {
@@ -957,11 +985,29 @@ describe("pipeline and workspace keys in app and lib configs", () => {
     try {
       const lib = { name: "extlib", cwdPath: root } as never;
       fs.writeFileSync(path.join(root, "akan.config.ts"), "export default { pipeline: { stages: [] } };\n");
-      expect(AkanLibConfig.from(lib)).rejects.toThrow("which a lib does not take");
+      await expect(AkanLibConfig.from(lib)).rejects.toThrow("which a lib does not take");
       fs.writeFileSync(path.join(root, "akan.config.ts"), "export default { subspace: { subspaces: [] } };\n");
-      expect(AkanLibConfig.from(lib, { bustImportCache: true })).rejects.toThrow("a workspace setting");
+      await expect(AkanLibConfig.from(lib, { bustImportCache: true })).rejects.toThrow("a workspace setting");
     } finally {
       fs.rmSync(root, { recursive: true, force: true });
     }
   });
+
+  test("a lib's refused key fails the app's load instead of skipping the lib and its docker steps", async () => {
+    const loading = loadExtAppConfig(
+      "akan-config-lib-refused-",
+      "export default {};\n",
+      "export default { docker: { preRuns: ['apt-get install -y ffmpeg'] }, pipeline: { stages: [] } };\n",
+    );
+    await expect(loading).rejects.toThrow("libs/extlib/akan.config.ts declares `pipeline`, which a lib does not take");
+  });
+
+  test("a lib config that fails to load is still skipped with a warning, the app loading without it", async () => {
+    const config = await loadExtAppConfig(
+      "akan-config-lib-broken-",
+      "export default { externalLibs: ['shiki'] };\n",
+      'throw new Error("half-written");\nexport default {};\n',
+    );
+    expect(config.externalLibs).toEqual(["shiki"]);
+  });
 });

package/akanConfig/akanConfig.ts

@@ -1,9 +1,10 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import type { ServerPolicy } from "@akanjs/native/api";
 import type { AkanPlugin } from "akanjs";
 import { DatabaseModes, normalizeRoutePrefix } from "akanjs/base";
-import { type AkanI18nConfig, resolveAkanI18nConfig } from "akanjs/common";
+import { type AkanI18nConfig, resolveAkanI18nConfig, trimSlashes } from "akanjs/common";
 import type { AkanImageConfig } from "akanjs/server";
 import type { App, Lib } from "../commandDecorators";
 import { LibExecutor, WorkspaceExecutor } from "../executors";
@@ -152,6 +153,8 @@ const dedupeDockerRuns = (runs: DockerRun[]): DockerRun[] => {
   return [...byKey.values()];
 };
 
+class LibConfigRefusal extends Error {}
+
 export class AkanAppConfig implements AppConfigResult {
   app: App;
   rootPackageJson: PackageJson;
@@ -285,6 +288,11 @@ export class AkanAppConfig implements AppConfigResult {
           throw new Error(
             `${where}.updates in ${configPath} has no url or publicKeys${named ? "; give them in native.updates or the target's own" : ""}.`,
           );
+        //? NativeConfig prefers publicKeys to publicKey, so a target's own key beside the section's list would be lost.
+        if (updates?.publicKey !== undefined && updates.publicKeys !== undefined)
+          throw new Error(
+            `${where}.updates in ${configPath} has both publicKey and publicKeys${named ? ", native.updates merged in: give one, in native.updates' own form when overriding its keys" : ": give one"}.`,
+          );
         AkanAppConfig.#assertFiles(own ?? {}, where, configPath);
         const {
           basePath: _basePath,
@@ -370,13 +378,16 @@ export class AkanAppConfig implements AppConfigResult {
       },
     };
   }
-  //? The stage owns these: the operation mode, the database mode and what is served are what make it the carried server.
+  //? The stage owns these: the operation mode, the database mode, what is served and the shutdown budget the shell's
+  //? quit waits on are what make it the carried server.
   static readonly #stagedServerEnv = new Set([
     "AKAN_PUBLIC_OPERATION_MODE",
     "AKAN_DATABASE_MODE",
     "AKAN_DATABASE_MODES",
     "AKAN_SSR",
     "AKAN_CSR",
+    "AKAN_MCP",
+    "AKAN_SHUTDOWN_TIMEOUT_MS",
     "AKAN_MODULES",
   ]);
   static #desktopServerEnv(env: unknown, where: string, configPath: string): Record<string, string> {
@@ -395,19 +406,25 @@ export class AkanAppConfig implements AppConfigResult {
       );
     return env as Record<string, string>;
   }
-  static #desktopServerWatchdog(
-    watchdog: unknown,
-    where: string,
-    configPath: string,
-  ): { intervalMs: number; failures: number } | null {
+  //? The akan.config.ts shape, which takes `true` and fills in what is left out; the launcher reads what this returns
+  //? with serverPolicyOf in @akanjs/native, which devkit cannot load while it reads a config.
+  static #desktopServerWatchdog(watchdog: unknown, where: string, configPath: string): ServerPolicy["watchdog"] | null {
     if (watchdog === undefined || watchdog === false) return null;
-    const { intervalMs = 10_000, failures = 3 } = (watchdog === true ? {} : watchdog) as Record<string, unknown>;
-    const whole = (value: unknown) => Number.isInteger(value) && (value as number) > 0;
-    if ((watchdog !== true && !AkanAppConfig.#isPlainObject(watchdog)) || !whole(intervalMs) || !whole(failures))
+    const options = watchdog === true ? {} : watchdog;
+    const whole = (value: unknown) => value === undefined || (Number.isInteger(value) && (value as number) > 0);
+    if (
+      !AkanAppConfig.#isPlainObject(options) ||
+      Object.keys(options).some((key) => key !== "intervalMs" && key !== "failures") ||
+      !whole(options.intervalMs) ||
+      !whole(options.failures)
+    )
       throw new Error(
         `${where}.watchdog in ${configPath} must be true or { intervalMs, failures }, whole numbers from 1.`,
       );
-    return { intervalMs: intervalMs as number, failures: failures as number };
+    return {
+      intervalMs: (options.intervalMs as number | undefined) ?? 10_000,
+      failures: (options.failures as number | undefined) ?? 3,
+    };
   }
   static #platformIndexPath<T extends { indexPath?: string }>(section: T): T {
     const { indexPath: rawIndexPath, ...rest } = section;
@@ -550,7 +567,7 @@ export class AkanAppConfig implements AppConfigResult {
   }
   #applyRoutes(routes: AkanRouteConfig[] = []) {
     for (const route of routes) {
-      const basePath = route.basePath ? route.basePath.replace(/^\/+|\/+$/g, "") : null;
+      const basePath = route.basePath ? trimSlashes(route.basePath) : null;
       if (basePath !== null) this.basePaths.add(basePath);
       const domains = basePath !== null ? this.subRoutes.getOrInsert(basePath, new Set()) : this.domains;
       for (const branch of Object.keys(route.domains)) this.branches.add(branch);
@@ -685,6 +702,8 @@ CMD [${command.map((c) => `"${c}"`).join(",")}]`;
         LibExecutor.from(app, libName)
           .getConfig({ refresh: bustImportCache })
           .catch((error: unknown) => {
+            //? Skipping a refused lib config would build the image without its docker steps, and the build would pass.
+            if (error instanceof LibConfigRefusal) throw error;
             app.logger.warn(`Skipped libs/${libName}/akan.config.ts contributions: ${String(error)}`);
             return null;
           }),
@@ -843,11 +862,11 @@ export class AkanLibConfig implements LibConfigResult {
     const resolved = typeof configImp === "function" ? configImp(lib) : configImp;
     const { plugins, ...config } = (resolved ?? {}) as LibConfigDeclaration & { plugins?: AkanPlugin[] };
     if ("pipeline" in config)
-      throw new Error(
+      throw new LibConfigRefusal(
         `libs/${lib.name}/akan.config.ts declares \`pipeline\`, which a lib does not take: pipelines belong to apps and the workspace root, and a lib's build-time work goes in an akan build plugin.`,
       );
     if ("subspace" in config)
-      throw new Error(
+      throw new LibConfigRefusal(
         `libs/${lib.name}/akan.config.ts declares \`subspace\`, a workspace setting: it belongs in the workspace root akan.config.ts.`,
       );
     return new AkanLibConfig(lib, config, plugins ?? []);

package/akanConfig/akanWorkspaceConfig.test.ts

@@ -51,7 +51,7 @@ describe("AkanWorkspaceConfig", () => {
     expect(hostOf(undefined)).toBeNull();
     expect(hostOf({})).toBeNull();
     expect(hostOf({ host: "https://cloud.example.com/" })).toBe("https://cloud.example.com");
-    expect(hostOf({ host: "https://example.com/akasys//" })).toBe("https://example.com/akasys");
+    expect(hostOf({ host: "https://example.com/control//" })).toBe("https://example.com/control");
     expect(hostOf({ host: "http://localhost:8283" })).toBe("http://localhost:8283");
     expect(() => hostOf({ host: "http://cloud.example.com" })).toThrow("https only");
     expect(() => hostOf({ host: "cloud.example.com" })).toThrow("is not a URL");
@@ -59,21 +59,21 @@ describe("AkanWorkspaceConfig", () => {
     expect(() => hostOf({ host: "https://cloud.example.com", token: "x" })).toThrow("keys it does not take: token");
 
     const workspace = (cloudHost: string | null) => ({ getConfig: async () => ({ cloudHost }) });
-    expect(await GlobalConfig.hostFor(workspace("https://akasys.example.com"), "https://given.example.com")).toBe(
+    expect(await GlobalConfig.hostFor(workspace("https://control.example.com"), "https://given.example.com")).toBe(
       "https://given.example.com",
     );
-    expect(await GlobalConfig.hostFor(workspace("https://akasys.example.com"), null)).toBe(
-      "https://akasys.example.com",
+    expect(await GlobalConfig.hostFor(workspace("https://control.example.com"), null)).toBe(
+      "https://control.example.com",
     );
     expect(await GlobalConfig.hostFor(workspace(null))).toBe(GlobalConfig.akanCloudHost);
   });
 
   test("refuses app settings and a default export that is not an object", async () => {
     await withWorkspace({ "akan.config.ts": 'export default { docker: { image: "x" } };\n' }, async (workspace) => {
-      expect(AkanWorkspaceConfig.from(workspace)).rejects.toThrow("declares `docker`, which it does not take");
+      await expect(AkanWorkspaceConfig.from(workspace)).rejects.toThrow("declares `docker`, which it does not take");
     });
     await withWorkspace({ "akan.config.ts": "export default () => ({});\n" }, async (workspace) => {
-      expect(AkanWorkspaceConfig.from(workspace)).rejects.toThrow("must default-export a WorkspaceConfig object");
+      await expect(AkanWorkspaceConfig.from(workspace)).rejects.toThrow("must default-export a WorkspaceConfig object");
     });
   });
 });

package/akanConfig/akanWorkspaceConfig.ts

@@ -4,7 +4,7 @@ import type { WorkspaceExecutor } from "../executors";
 import { FileSys } from "../fileSys";
 import { AkanAppConfig } from "./akanConfig";
 
-/** The workspace root's own `akan.config.ts`: settings that belong to no app. Absent, it is an empty one. */
+/** The workspace root's own `akan.config.ts`: settings that belong to no app. */
 export class AkanWorkspaceConfig {
   static readonly fileName = "akan.config.ts";
   static readonly #keys = ["subspace", "pipeline", "cloud"];

package/akanContext.ts

@@ -209,7 +209,7 @@ export const upsertCodexMcpServerBlock = (
   const match = existing.match(codexAkanTablePattern);
   if (!match) {
     if (!existing.trim()) return nextBlock;
-    return `${existing.replace(/\s*$/, "")}\n\n${nextBlock}`;
+    return `${existing.trimEnd()}\n\n${nextBlock}`;
   }
   if (match[0].trim() === nextBlock.trim()) return existing;
   if (!force)
@@ -847,8 +847,8 @@ export class AkanContextAnalyzer {
       const listed = listedByImport(sectionOf(agentsMd, "## Recipes")).get("akanjs/ui") ?? new Set<string>();
       pushIndexDiagnostic(
         "AGENTS.md",
-        [...frameworkDeclared].filter((name) => !listed.has(name)).sort(),
-        [...listed].filter((name) => !frameworkDeclared.has(name)).sort(),
+        [...frameworkDeclared].filter((name) => !listed.has(name)).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)),
+        [...listed].filter((name) => !frameworkDeclared.has(name)).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)),
         "akan agent install agents-md",
       );
     }
@@ -859,7 +859,7 @@ export class AkanContextAnalyzer {
         .catch(() => "");
       const groups = listedByImport(sectionOf(scopeMd, "## Recipes In Scope"));
       const ownListed = groups.get(`@${sys.path}/ui`) ?? new Set<string>();
-      const missing = [...own].filter((name) => !ownListed.has(name)).sort();
+      const missing = [...own].filter((name) => !ownListed.has(name)).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
       // Every listed name — the scope's own and its dependency libs' — must still exist at its owner.
       const stale = [...groups.entries()]
         .flatMap(([importFrom, names]) =>

package/akanMcpContract.ts

@@ -113,7 +113,7 @@ const slugPart = (value: unknown) =>
     ? value
         .trim()
         .replace(/[^a-zA-Z0-9]+/g, "-")
-        .replace(/^-+|-+$/g, "")
+        .replace(/^-|-$/g, "")
         .toLowerCase()
     : "";
 

package/applicationBuildRunner.test.ts

@@ -1,11 +1,13 @@
 import { describe, expect, test } from "bun:test";
-import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { AkanAppConfig } from "./akanConfig";
 import { AKAN_BACKEND_MINIFY, AKAN_OPTIONAL_BACKEND_EXTERNALS, ApplicationBuildRunner } from "./applicationBuildRunner";
 import type { App } from "./commandDecorators";
-import { Executor } from "./executors";
+import { AppExecutor, Executor } from "./executors";
+import { bundleDefine } from "./frontendBuild/bundleDefine";
+import { createTempApp } from "./testHelpers";
 
 describe("ApplicationBuildRunner", () => {
   test("externalizes Akan optional backend dependencies", () => {
@@ -78,4 +80,57 @@ console.info(new SampleService().name);
       await rm(root, { recursive: true, force: true });
     }
   });
+
+  test("bakes into the route bundles the env their server env is, not the shell's that the root .env outranks", async () => {
+    const { root, workspace } = await createTempApp("portal");
+    const shellEnv = process.env.AKAN_PUBLIC_ENV;
+    const stoppedBeforePhases = (app: AppExecutor) => {
+      app.prepareCommand = async () => {
+        throw new Error("stopped before the phases");
+      };
+      return app;
+    };
+    const bakedEnv = (app: AppExecutor) =>
+      (bundleDefine(app, "build", "ssr") as { [key: string]: string })["process.env.AKAN_PUBLIC_ENV"];
+    try {
+      process.env.AKAN_PUBLIC_ENV = "main";
+      const app = stoppedBeforePhases(AppExecutor.from(workspace, "portal"));
+      await expect(new ApplicationBuildRunner(app).build()).rejects.toThrow("stopped before the phases");
+      expect(bakedEnv(app)).toBe(JSON.stringify("local"));
+
+      process.env.AKAN_PUBLIC_ENV = "main";
+      const desktop = stoppedBeforePhases(AppExecutor.from(workspace, "portal"));
+      await expect(new ApplicationBuildRunner(desktop, { environment: "debug" }).build()).rejects.toThrow(
+        "stopped before the phases",
+      );
+      expect(bakedEnv(desktop)).toBe(JSON.stringify("debug"));
+    } finally {
+      if (shellEnv === undefined) delete process.env.AKAN_PUBLIC_ENV;
+      else process.env.AKAN_PUBLIC_ENV = shellEnv;
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("a build for a real environment stops before any phase when the serve domain is only the local default", async () => {
+    const { root, workspace } = await createTempApp("portal");
+    await writeFile(path.join(root, ".env"), "AKAN_PUBLIC_REPO_NAME=repo\n");
+    const shellDomain = process.env.AKAN_PUBLIC_SERVE_DOMAIN;
+    delete process.env.AKAN_PUBLIC_SERVE_DOMAIN;
+    const app = AppExecutor.from(workspace, "portal");
+    let prepared = false;
+    app.prepareCommand = async () => {
+      prepared = true;
+      throw new Error("prepared");
+    };
+    try {
+      await expect(new ApplicationBuildRunner(app, { environment: "main" }).build()).rejects.toThrow(
+        'akan build for the "main" environment needs AKAN_PUBLIC_SERVE_DOMAIN (would be "localhost") set',
+      );
+      expect(prepared).toBe(false);
+      await expect(new ApplicationBuildRunner(app, { environment: "local" }).build()).rejects.toThrow("prepared");
+    } finally {
+      if (shellDomain !== undefined) process.env.AKAN_PUBLIC_SERVE_DOMAIN = shellDomain;
+      await rm(root, { recursive: true, force: true });
+    }
+  });
 });

package/applicationBuildRunner.ts

@@ -6,6 +6,7 @@ import type {
   ApplicationBuildResult,
 } from "./applicationBuildReporter";
 import type { App } from "./commandDecorators";
+import { WorkspaceExecutor } from "./executors";
 import {
   AllRoutesBuilder,
   CsrArtifactBuilder,
@@ -100,13 +101,13 @@ export class ApplicationBuildRunner {
     // serial build is needed because of Bun.build is unstable for parallel build
     this.#spinner = spinner;
     const { web, assets, baseDevEnv } = await this.#app.getConfig();
+    const environment = this.#environment ?? baseDevEnv.env;
+    WorkspaceExecutor.assertDeployableEnv(baseDevEnv, environment, "akan build");
+    //? Bundles bake AKAN_PUBLIC_ENV from process.env, where the shell outranks the .env that picked the server env.
+    process.env.AKAN_PUBLIC_ENV = environment;
     //? Before any phase: a profile that would ship a secret stops the build, not the image after it.
     if (this.#profile)
-      await ServerEnvProfile.assertShippable({
-        envDir: this.#envDir,
-        environment: this.#environment ?? baseDevEnv.env,
-        profile: this.#profile,
-      });
+      await ServerEnvProfile.assertShippable({ envDir: this.#envDir, environment, profile: this.#profile });
     await this.#runPhase("prepare", "Preparing output directory", () => this.#app.prepareCommand("build"));
     if (!this.#fast) await this.#runPhase("typecheck", "Typechecking", () => this.typecheck());
     await this.#runPhase(
@@ -363,9 +364,17 @@ void run().catch((error) => {
     return { base, allRoutes };
   }
 
+  //? Opt-in and outside `dist/`: a metafile is the size of the module graph, and `dist/` is what the image copies.
   async #buildOrThrow(label: string, config: Bun.BuildConfig): Promise<Bun.BuildOutput> {
-    const result = await Bun.build(config);
+    const metafileDir = process.env.AKAN_BUILD_METAFILE
+      ? path.join(this.#app.workspace.workspaceRoot, "local", "build-meta", path.basename(this.#app.cwdPath))
+      : null;
+    const result = await Bun.build(metafileDir ? { ...config, metafile: true } : config);
     if (!result.success) throw new AggregateError(result.logs, `[${label}] Bun.build failed`);
+    if (metafileDir && result.metafile) {
+      const entry = path.parse(String(config.entrypoints[0] ?? label)).name;
+      await Bun.write(path.join(metafileDir, `${entry}.json`), JSON.stringify(result.metafile));
+    }
     return result;
   }
 

package/artifact/implicitRootLayout.test.ts

@@ -46,6 +46,8 @@ describe("resolveSsrPageEntries", () => {
     expect(generatedSource).toContain("export const NotFound = userLayout.NotFound ?? inheritedLayout.NotFound;");
     expect(generatedSource).toContain("export const Error = userLayout.Error ?? inheritedLayout.Error;");
     expect(generatedSource).toContain("export const pageConfig = userLayout.pageConfig ?? inheritedLayout.pageConfig;");
+    // The ancestor root is its own level of the stack, so inheriting its loading would nest it inside itself.
+    expect(generatedSource).toContain("export const Loading = userLayout.Loading;");
     expect(generatedSource).toContain(
       "<UserLayout params={params} searchParams={searchParams}>{children}</UserLayout>",
     );

package/artifact/implicitRootLayout.ts

@@ -201,6 +201,7 @@ async function writeGeneratedRootLayoutFile(opts: {
 export const NotFound = userLayout.NotFound ?? inheritedLayout.NotFound;
 export const Error = userLayout.Error ?? inheritedLayout.Error;
 export const pageConfig = userLayout.pageConfig ?? inheritedLayout.pageConfig;
+export const Loading = userLayout.Loading;
 
 ${layoutSignature}({ children, params, searchParams }: LayoutProps) {
 ${layoutBinding}  return `;

package/biome.base.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.5.12/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.5.14/schema.json",
   "vcs": {
     "enabled": true,
     "clientKind": "git",
@@ -85,16 +85,6 @@
   "overrides": [
     {
       "includes": [
-        "**/env.client.local.ts",
-        "**/env.client.debug.ts",
-        "**/env.client.develop.ts",
-        "**/env.client.main.ts",
-        "**/env.client.testing.ts",
-        "**/env.server.local.ts",
-        "**/env.server.develop.ts",
-        "**/env.server.main.ts",
-        "**/env.server.testing.ts",
-        "**/env.server.type.ts",
         "apps/*/lib/cnst.ts",
         "apps/*/lib/dict.ts",
         "apps/*/lib/db.ts",

package/biomeBase.ts

@@ -3,4 +3,4 @@ export const biomeBaseConfig = "@akanjs/devkit/biome.base.json";
 
 // Pinned: Biome moves rules between groups across minors and a stale position is a hard config error. Bump it with
 // `biome.base.json` in one commit, running `biome migrate --write` in the workspace root and in this package.
-export const biomeVersion = "2.5.12";
+export const biomeVersion = "2.5.14";

package/cloud/cloudApi.ts

@@ -1,4 +1,5 @@
 import type { Workspace } from "../commandDecorators";
+import { CloudHttpError } from "./cloudHttpError";
 import type { AccessToken, AccessTokenDto, HostConfig } from "./constants";
 import { GlobalConfig } from "./globalConfig";
 
@@ -25,7 +26,7 @@ class HttpClient {
     const response = await fetch(`${this.baseUrl}${url}`, {
       headers: { ...this.headers, ...headers },
     });
-    if (!response.ok) throw new Error(`Failed to download file: ${response.status} ${response.statusText}`);
+    if (!response.ok) throw await CloudHttpError.of(response, url);
     await Bun.write(localPath, response);
   }
   async post<T>(url: string, data: unknown, { headers, signal }: HttpRequestOptions = {}): Promise<T> {
@@ -42,9 +43,8 @@ class HttpClient {
   }
   // A missing route answers an HTML error page, so the status is read before the body is parsed as JSON.
   static async #body<T>(response: Response, url: string): Promise<T> {
-    const text = await response.text();
-    if (!response.ok) throw new Error(`${response.status} ${response.statusText} from ${url}: ${text.slice(0, 200)}`);
-    return JSON.parse(text) as T;
+    if (!response.ok) throw await CloudHttpError.of(response, url);
+    return JSON.parse(await response.text()) as T;
   }
   setHeaders(headers: Record<string, string>) {
     Object.assign(this.headers, headers);
@@ -71,10 +71,10 @@ export interface PipelineSecretSummary {
 }
 
 export interface PipelineSecretListing extends PipelineSecretSummary {
-  updatedBy: string;
+  updatedBy: string | null;
 }
 
-/** What akasys answers for an uploaded pack or a registered binary; a pack's release also says how it was taken. */
+/** What Akan Cloud answers for an uploaded pack or a registered binary; a pack's release also says how it was taken. */
 export interface CloudRecord {
   id: string;
   status?: string;
@@ -113,10 +113,19 @@ export interface TunnelSummary {
 }
 
 export class CloudApi {
-  /** The HTTP status an error from this client carries, or null for one without (a dropped connection, a timeout). */
-  static statusOf(error: unknown) {
-    const status = Number(/(?:^|: )(\d{3}) /.exec(error instanceof Error ? error.message : String(error))?.[1]);
-    return Number.isNaN(status) ? null : status;
+  //* The project's guards answer by status: 401 no sign-in it accepts, 403 not allowed, 400 a refused request.
+  static refusal(error: unknown, who: string, { unavailable }: { unavailable?: string } = {}) {
+    if (!(error instanceof CloudHttpError)) return error;
+    if (error.status === 401)
+      return new Error("The server did not accept your sign-in: run `akan login`, then try again.", { cause: error });
+    if (error.status === 403) return new Error(`The project refused: ${who}.`, { cause: error });
+    if (error.status === 400)
+      return new Error(`The project refused the request${error.error ? `: ${error.error}` : ""}.`, { cause: error });
+    //? A proxy, or the gateway with no replica ready, answers 503 too; only the server's own names a domain Err key.
+    const { errKey } = error;
+    if (error.status === 503 && unavailable && errKey && errKey !== "base.error.serverUnavailable")
+      return new Error(`${unavailable}: ${errKey}.`, { cause: error });
+    return error;
   }
   readonly #api: HttpClient;
   #accessToken: AccessToken | null = null;
@@ -184,7 +193,8 @@ export class CloudApi {
       target: string;
       distribution: AppBinaryDistribution;
       bundle: Blob;
-      pack?: Blob;
+      /** The pack staged with UpdatePackUpload.stage. */
+      packUploadId: string;
       channel?: string;
     },
   ) {
@@ -192,8 +202,10 @@ export class CloudApi {
     for (const key of ["appName", "target", "distribution"] as const) formData.append(key, binary[key]);
     if (binary.channel) formData.append("channel", binary.channel);
     formData.append("bundle", binary.bundle, "bundle.json");
-    if (binary.pack) formData.append("pack", binary.pack, "pack.tgz");
-    return await this.#api.post<CloudRecord>(`/registerAppBinary/${encodeURIComponent(devProjectId)}`, formData);
+    formData.append("packUploadId", binary.packUploadId);
+    return await this.#api.post<CloudRecord>(`/registerAppBinary/${encodeURIComponent(devProjectId)}`, formData, {
+      signal: AbortSignal.timeout(11 * 60_000),
+    });
   }
   async downloadEnv(devProjectId: string): Promise<unknown> {
     const localPath = `${this.#workspace.workspaceRoot}/local/env.tar`;

package/cloud/cloudHttpError.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, test } from "bun:test";
+import { CloudHttpError } from "./cloudHttpError";
+
+describe("CloudHttpError", () => {
+  test("reads the server's Err key from the whole body, while the message keeps 200 characters of it", () => {
+    const body = JSON.stringify({ details: "x".repeat(300), error: "release.error.uploadEmbedded", statusCode: 409 });
+    const error = new CloudHttpError(409, "Conflict", "/commitUpdateUpload/p", body);
+
+    expect(error.status).toBe(409);
+    expect(error.errKey).toBe("release.error.uploadEmbedded");
+    expect(error.message).toBe(`409 Conflict from /commitUpdateUpload/p: ${body.slice(0, 200)}`);
+    expect(CloudHttpError.statusOf(error)).toBe(409);
+    expect(CloudHttpError.statusOf(new Error("409 Conflict from /x: {}"))).toBeNull();
+  });
+
+  test("names no Err key for a proxy's page or an error that is not one", () => {
+    expect(new CloudHttpError(503, "Service Unavailable", "/x", "<html>503</html>").errKey).toBeNull();
+    const plain = new CloudHttpError(400, "Bad Request", "/x", '{"error":"Bad Request"}');
+    expect(plain.error).toBe("Bad Request");
+    expect(plain.errKey).toBeNull();
+  });
+
+  test("takes Retry-After as seconds or as a date, and nothing else", () => {
+    expect(CloudHttpError.retryAfterMs("7")).toBe(7000);
+    expect(CloudHttpError.retryAfterMs(new Date(Date.now() + 60_000).toUTCString())).toBeGreaterThan(55_000);
+    expect(CloudHttpError.retryAfterMs(new Date(Date.now() - 60_000).toUTCString())).toBe(0);
+    expect(CloudHttpError.retryAfterMs("soon")).toBeNull();
+    expect(CloudHttpError.retryAfterMs(null)).toBeNull();
+    const headers = new Headers({ "Retry-After": "3" });
+    expect(new CloudHttpError(429, "Too Many Requests", "/x", "", headers).retryAfterMs).toBe(3000);
+  });
+});