@akanjs/devkit 3.0.1 → 3.0.2

package/executors.test.ts

@@ -1,15 +1,33 @@
-import { describe, expect, test } from "bun:test";
+import { describe, expect, spyOn, test } from "bun:test";
 import { existsSync } from "node:fs";
 import { lstat, mkdir, readFile, readlink, rm, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { AkanAppConfig } from "./akanConfig";
-import { AppExecutor, CommandExecutionError, Executor, PkgExecutor, WorkspaceExecutor } from "./executors";
+import {
+  AppExecutor,
+  CommandExecutionError,
+  Executor,
+  type LibExecutor,
+  PkgExecutor,
+  WorkspaceExecutor,
+} from "./executors";
+import { DevGeneratedIndexSync } from "./frontendBuild/devGeneratedIndexSync";
 import { AppInfo } from "./scanInfo";
-import { isolateEnv, tempDirs, writeJson, writeText } from "./testHelpers";
+import {
+  createTempLib,
+  formatWithBiome,
+  hasBiome,
+  isolateEnv,
+  tempDirs,
+  tempRoots,
+  writeJson,
+  writeText,
+} from "./testHelpers";
 import type { PackageJson } from "./types";
 
 isolateEnv();
 const makeTempRoot = tempDirs("akan-devkit-");
+const trackRoot = tempRoots();
 
 const PAGE_SOURCE = "export default function Page() {\n  return null;\n}\n";
 
@@ -309,11 +327,16 @@ describe("Workspace and app executor environment contracts", () => {
     expect(env.EXTRA).toBe("ok");
 
     const shellOperationMode = process.env.AKAN_PUBLIC_OPERATION_MODE;
+    const shellServerPort = process.env.AKAN_PUBLIC_SERVER_PORT;
     process.env.AKAN_PUBLIC_OPERATION_MODE = "local";
+    process.env.AKAN_PUBLIC_SERVER_PORT = "8282";
     const prepared = await app.prepareCommand("build");
     const bakedOperationMode = process.env.AKAN_PUBLIC_OPERATION_MODE;
+    const bakedServerPort = process.env.AKAN_PUBLIC_SERVER_PORT;
     if (shellOperationMode === undefined) delete process.env.AKAN_PUBLIC_OPERATION_MODE;
     else process.env.AKAN_PUBLIC_OPERATION_MODE = shellOperationMode;
+    if (shellServerPort !== undefined) process.env.AKAN_PUBLIC_SERVER_PORT = shellServerPort;
+    expect(bakedServerPort).toBeUndefined();
     expect(bakedOperationMode).toBeUndefined();
     expect(prepared.env.AKAN_COMMAND_TYPE).toBe("build");
     expect(prepared.env.AKAN_PUBLIC_BASE_PATHS).toBe("admin");
@@ -327,7 +350,7 @@ describe("Workspace and app executor environment contracts", () => {
     expect((await stat(path.join(root, "dist/apps/demo/public"))).isDirectory()).toBe(true);
   });
 
-  test("akan start clears the dev output and keeps native builds, update releases and the bin downloads", async () => {
+  test("akan start clears the dev output and keeps the bin downloads and a native folder from before dist/native", async () => {
     const root = await makeTempRoot();
     process.env.AKAN_PUBLIC_REPO_NAME = "repo";
     process.env.AKAN_PUBLIC_SERVE_DOMAIN = "example.com";
@@ -1055,3 +1078,305 @@ describe("SysExecutor module listing", () => {
     ]);
   });
 });
+
+interface ScannableLibOptions {
+  root?: Pick<PackageJson, "dependencies" | "devDependencies">;
+  manifest?: Partial<PackageJson>;
+  config?: string;
+  files?: Record<string, string>;
+}
+
+//* `LibInfo.libInfos` caches a scan by lib name for the whole file, so every test passes a name of its own.
+const createScannableLib = async (
+  libName: string,
+  { root = {}, manifest = {}, config = "export default {};\n", files = {} }: ScannableLibOptions = {},
+) => {
+  const temp = trackRoot(await createTempLib(libName));
+  const libDir = path.join(temp.root, "libs", libName);
+  await writeJson(path.join(temp.root, "package.json"), {
+    name: "repo",
+    version: "1.0.0",
+    description: "repo",
+    ...root,
+  });
+  await writeJson(path.join(libDir, "package.json"), {
+    type: "module",
+    name: `@${libName}`,
+    version: "0.0.1",
+    ...manifest,
+  });
+  await writeJson(path.join(libDir, "tsconfig.json"), { compilerOptions: { target: "ESNext", paths: {} } });
+  await writeText(path.join(libDir, "akan.config.ts"), config);
+  await mkdir(path.join(libDir, "lib", "__scalar"), { recursive: true });
+  for (const [file, content] of Object.entries(files)) await writeText(path.join(libDir, file), content);
+  return { ...temp, libDir };
+};
+
+describe("SysExecutor scan", () => {
+  test("gives a facet folder with nothing to export an empty barrel, so a barrel a deleted file left heals", async () => {
+    const { lib } = await createScannableLib("barrelheal", {
+      files: {
+        "common/index.ts": 'export * from "./commonLogic";\n',
+        "webkit/thing.helper.ts": "export const thing = 1;\n",
+      },
+    });
+
+    await lib.scan();
+
+    expect(await lib.readFile("common/index.ts")).toBe("export {};\n");
+    expect(await lib.readFile("webkit/index.ts")).toBe("export {};\n");
+    expect(await lib.exists("ui")).toBe(false);
+  });
+
+  test("imports into the generated lib/dict.ts and lib/srv.ts only the helpers their code calls", async () => {
+    const { lib: bare } = await createScannableLib("nomodulelib");
+    await bare.scan();
+    expect(await bare.readFile("lib/dict.ts")).toContain(
+      'import { makeDictionary, makeTrans, dictionary as base } from "akanjs/dictionary";',
+    );
+    const bareSrv = await bare.readFile("lib/srv.ts");
+    for (const unused of ["ServiceModel", '"./cnst"', '"./db"']) expect(bareSrv).not.toContain(unused);
+
+    const { lib: full } = await createScannableLib("allmodulelib", {
+      files: {
+        "lib/post/post.constant.ts": "export class Post {}\n",
+        "lib/post/post.service.ts": "export class PostService {}\n",
+        "lib/_mail/mail.service.ts": "export class MailService {}\n",
+        "lib/__scalar/money/money.constant.ts": "export class Money {}\n",
+      },
+    });
+    await full.scan();
+    expect(await full.readFile("lib/dict.ts")).toContain(
+      "import { makeDictionary, makeTrans, registerScalarTrans, registerServiceTrans, registerModelTrans, dictionary as base }",
+    );
+    const fullSrv = await full.readFile("lib/srv.ts");
+    expect(fullSrv).toContain('import { ServiceModel } from "akanjs/service";');
+    expect(fullSrv).toContain('import * as cnst from "./cnst";\nimport * as db from "./db";');
+  });
+
+  test.skipIf(!hasBiome)("writes barrels, module indexes and akan.lib.json the way Biome prints them", async () => {
+    const component = "export const C = () => null;\n";
+    const uiFiles = ["QRCode", "Qa", "SSOButton", "Select", "Icon10", "Icon2"].map((name) => [
+      `ui/${name}.tsx`,
+      component,
+    ]);
+    const srvkitFiles = ["aB", "aa", "a10", "a9"].map((name) => [`srvkit/${name}.ts`, "export const x = 1;\n"]);
+    const moduleFiles = ["Template", "Unit", "View"].map((role) => [`lib/post/Post.${role}.tsx`, component]);
+    const { root, lib, libDir } = await createScannableLib("biomestable", {
+      files: Object.fromEntries([
+        ...uiFiles,
+        ...srvkitFiles,
+        ...moduleFiles,
+        ["lib/post/post.constant.ts", "export class Post {}\n"],
+      ]),
+    });
+    expect(await formatWithBiome('export * from "./b";\nexport * from "./a";\n', "libs/x/srvkit/index.ts")).toBe(
+      'export * from "./a";\nexport * from "./b";\n',
+    );
+
+    await lib.scan();
+
+    expect(await lib.readFile("ui/index.ts")).toBe(
+      ["Icon2", "Icon10", "Qa", "QRCode", "Select", "SSOButton"].map((name) => `export * from "./${name}";\n`).join(""),
+    );
+    expect(await lib.readFile("srvkit/index.ts")).toBe(
+      ["a9", "a10", "aa", "aB"].map((name) => `export * from "./${name}";\n`).join(""),
+    );
+    for (const file of ["ui/index.ts", "srvkit/index.ts", "lib/post/index.ts", "akan.lib.json"]) {
+      const generated = await lib.readFile(file);
+      expect(await formatWithBiome(generated, `libs/biomestable/${file}`)).toBe(generated);
+    }
+    const devSync = new DevGeneratedIndexSync({ workspaceRoot: root });
+    const events = ["ui/QRCode.tsx", "srvkit/a9.ts", "lib/post"].map((file) => path.join(libDir, file));
+    expect(await devSync.syncForBatch(events)).toEqual({ changedFiles: [], errors: [] });
+  });
+
+  test("refuses a hand-written ui/index.tsx beside the generated barrel, naming the file and the fix", async () => {
+    const { lib } = await createScannableLib("shadowedbarrel", {
+      files: {
+        "ui/Chat.tsx": "export const Chat = () => null;\n",
+        "ui/index.tsx": 'export { Chat } from "./Chat";\n',
+        "ui/Page/index.tsx": 'export { Inner } from "./Inner";\n',
+        "ui/Page/index_.tsx": '"use client";\nexport { Inner } from "./Inner";\n',
+      },
+    });
+
+    const error = await lib.scan().catch((caught: unknown) => caught);
+
+    expect(error).toBeInstanceOf(Error);
+    const { message } = error as Error;
+    expect(message).toContain("libs/shadowedbarrel/ui/index.tsx: shadows the generated ui/index.ts");
+    expect(message).toContain("Delete it");
+    expect(message).not.toContain("ui/Page/");
+  });
+});
+
+describe("SysExecutor dependency sync", () => {
+  const root: Pick<PackageJson, "dependencies" | "devDependencies"> = {
+    dependencies: {
+      chalk: "^5.6.2",
+      esbuild: "^0.25.0",
+      lodash: "^4.17.21",
+      react: "19.3.0",
+      "react-dom": "19.3.0",
+      sharp: "^0.34.0",
+      zod: "3.25.76",
+    },
+    devDependencies: { dayjs: "^1.11.20", "happy-dom": "20.11.2", typescript: "^6.0.3" },
+  };
+  const readManifest = async (libDir: string) =>
+    (await Bun.file(path.join(libDir, "package.json")).json()) as PackageJson;
+  const silenced = (lib: LibExecutor) => ({
+    info: spyOn(lib.logger, "info").mockImplementation(() => undefined),
+    warn: spyOn(lib.logger, "warn").mockImplementation(() => undefined),
+  });
+
+  test("prunes what the root declares and nothing imports, and keeps and warns once about what it does not", async () => {
+    const { lib, libDir } = await createScannableLib("prunedeps", {
+      root,
+      manifest: {
+        dependencies: { lodash: "^4.0.0", "react-dom": "19.2.6", "left-pad": "^1.3.0", "is-odd": "^3.0.1" },
+        devDependencies: {},
+      },
+      files: { "srvkit/pad.ts": 'import padStart from "lodash/padStart";\nexport const pad = padStart;\n' },
+    });
+    const { info, warn } = silenced(lib);
+
+    await lib.scan();
+
+    expect((await readManifest(libDir)).dependencies).toEqual({
+      lodash: "^4.17.21",
+      "left-pad": "^1.3.0",
+      "is-odd": "^3.0.1",
+    });
+    expect(info).toHaveBeenCalledTimes(1);
+    expect(info.mock.calls[0]?.[0]).toContain(": react-dom (");
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(warn.mock.calls[0]?.[0]).toContain("libs/prunedeps/package.json lists left-pad, is-odd");
+  });
+
+  test("keeps what externalLibs, trustedDependencies or akan.keepDependencies names", async () => {
+    const akan = { keepDependencies: ["chalk"] };
+    const { lib, libDir } = await createScannableLib("keptdeps", {
+      root,
+      config: 'export default { externalLibs: ["sharp"], trustedDependencies: ["esbuild"] };\n',
+      manifest: {
+        dependencies: { sharp: "^0.33.0", esbuild: "^0.24.0", chalk: "^5.0.0", "react-dom": "19.2.6" },
+        devDependencies: {},
+        akan,
+      },
+    });
+    silenced(lib);
+
+    await lib.scan();
+
+    const manifest = await readManifest(libDir);
+    expect(manifest.dependencies).toEqual({ sharp: "^0.34.0", esbuild: "^0.25.0", chalk: "^5.6.2" });
+    expect(manifest.akan).toEqual(akan);
+  });
+
+  test("gives every surviving entry the root version, leaving peer, optional and the akan source alone", async () => {
+    const untouched = {
+      peerDependencies: { react: "^19.0.0" },
+      optionalDependencies: { fsevents: "^2.3.3" },
+      akan: { source: { origin: "akanjs", sha: "3.0.0", hash: "0f0f", syncedAt: "2026-01-01T00:00:00.000Z" } },
+    };
+    const { lib, libDir } = await createScannableLib("realigneddeps", {
+      root,
+      manifest: {
+        dependencies: { react: "19.2.7", lodash: "^4.0.0" },
+        devDependencies: { dayjs: "^1.11.13" },
+        ...untouched,
+      },
+      files: {
+        "ui/Thing.tsx": 'import { useState } from "react";\nexport const Thing = () => useState(0);\n',
+        "srvkit/pick.ts": 'import pick from "lodash/pick";\nexport const pickOf = pick;\n',
+      },
+    });
+    silenced(lib);
+
+    await lib.scan();
+
+    const manifest = await readManifest(libDir);
+    expect(manifest.dependencies).toEqual({ react: "19.3.0", lodash: "^4.17.21" });
+    expect(manifest.devDependencies).toEqual({ dayjs: "^1.11.20" });
+    expect(manifest).toMatchObject(untouched);
+  });
+
+  test("keeps the existing order, appends new names sorted, and a second scan rewrites nothing", async () => {
+    const { lib, libDir } = await createScannableLib("ordereddeps", {
+      root,
+      manifest: { dependencies: { zod: "3.25.76", lodash: "^4.17.21" }, devDependencies: {} },
+      files: {
+        "srvkit/uses.ts": [
+          'import { z } from "zod";',
+          'import chunk from "lodash/chunk";',
+          'import { createElement } from "react";',
+          'import chalk from "chalk";',
+          "export const uses = [z, chunk, createElement, chalk];",
+          "",
+        ].join("\n"),
+      },
+    });
+    silenced(lib);
+
+    await lib.scan();
+    const manifestFile = path.join(libDir, "package.json");
+    const [first, { mtimeMs }] = await Promise.all([readFile(manifestFile, "utf8"), stat(manifestFile)]);
+    expect(Object.keys((JSON.parse(first) as PackageJson).dependencies ?? {})).toEqual([
+      "zod",
+      "lodash",
+      "chalk",
+      "react",
+    ]);
+
+    await lib.scan({ refresh: true });
+    expect(await readFile(manifestFile, "utf8")).toBe(first);
+    expect((await stat(manifestFile)).mtimeMs).toBe(mtimeMs);
+  });
+
+  test("moves a type-only import to devDependencies", async () => {
+    const { lib, libDir } = await createScannableLib("typeonlydeps", {
+      root,
+      manifest: { dependencies: { zod: "3.25.76" }, devDependencies: {} },
+      files: { "common/schema.ts": 'import type { ZodType } from "zod";\nexport type Schema = ZodType;\n' },
+    });
+    silenced(lib);
+
+    await lib.scan();
+
+    const manifest = await readManifest(libDir);
+    expect(manifest.dependencies).toEqual({});
+    expect(manifest.devDependencies).toEqual({ zod: "3.25.76" });
+  });
+
+  test("leaves a runtime import the root lists only in devDependencies in devDependencies", async () => {
+    const { lib, libDir } = await createScannableLib("devonlydeps", {
+      root,
+      manifest: { dependencies: {}, devDependencies: { "happy-dom": "20.0.0" } },
+      files: {
+        "srvkit/dom.ts": 'import { Window } from "happy-dom";\nexport const createWindow = () => new Window();\n',
+      },
+    });
+    silenced(lib);
+
+    await lib.scan();
+
+    const manifest = await readManifest(libDir);
+    expect(manifest.dependencies).toEqual({});
+    expect(manifest.devDependencies).toEqual({ "happy-dom": "20.11.2" });
+  });
+
+  test("has written the manifest by the time scan returns", async () => {
+    const { lib, libDir } = await createScannableLib("settleddeps", {
+      root,
+      manifest: { dependencies: { "react-dom": "19.2.6" }, devDependencies: {} },
+      files: { "srvkit/pick.ts": 'import pick from "lodash/pick";\nexport const pickOf = pick;\n' },
+    });
+    silenced(lib);
+
+    await lib.scan({ writeLib: false });
+
+    expect((await readManifest(libDir)).dependencies).toEqual({ lodash: "^4.17.21" });
+  });
+});

package/executors.ts

@@ -44,13 +44,16 @@ import { AkanAppConfig, AkanLibConfig, decreaseBuildNum, increaseBuildNum } from
 import { getRootBoundarySegments, isRootBoundarySegments } from "./artifact/implicitRootLayout";
 import { CodegenLock } from "./codegenLock";
 import { FileSys, getDirname } from "./fileSys";
+import { JsonFormatter } from "./jsonFormatter";
 import { Linter } from "./linter";
+import { ManifestDependencies } from "./manifestDependencies";
 import { resolveRepoName } from "./repoIdentity";
-import { AppInfo, LibInfo, PkgInfo, WorkspaceInfo } from "./scanInfo";
+import { AppInfo, isAkanFrameworkDependency, LibInfo, PkgInfo, WorkspaceInfo } from "./scanInfo";
 import { Spinner } from "./spinner";
 // Type-only: `getTypeChecker` loads it on demand to keep `typescript` out of the resident module graph.
 import type { TypeChecker } from "./typeChecker";
 import type { FileContent, PackageJson, TsConfigJson } from "./types";
+import { barrelFacetDirs } from "./workspaceLayout";
 
 export interface PageRoot {
   /** App-relative location of the route files, i.e. the symlink for a synced lib. */
@@ -303,8 +306,7 @@ export class Executor {
     const writePath = this.getPath(filePath);
     const dir = path.dirname(writePath);
     if (!(await FileSys.dirExists(dir))) await mkdir(dir, { recursive: true });
-    //? Biome ends every .json with a newline; without one, `akan lint` and `akan sync` would flip-flop the file.
-    let contentStr = typeof content === "string" ? content : `${JSON.stringify(content, null, 2)}\n`;
+    let contentStr = typeof content === "string" ? content : JsonFormatter.stringify(content, writePath);
 
     if (await FileSys.fileExists(writePath)) {
       const currentContent = await FileSys.readText(writePath);
@@ -839,8 +841,6 @@ interface SysExecutorOptions extends NamedExecutorOptions {
   type: "app" | "lib";
 }
 
-const scanFacetDirs = ["ui", "webkit", "srvkit", "common", "plugin"] as const;
-
 export class SysExecutor extends Executor {
   workspace: WorkspaceExecutor;
   override name: string;
@@ -896,7 +896,7 @@ export class SysExecutor extends Executor {
       this._applyTemplate({ basePath: ".", template: "server.ts", scanInfo }),
       this._applyTemplate({ basePath: ".", template: "client.ts", scanInfo }),
       this.type === "lib" ? this._applyTemplate({ basePath: ".", template: "index.ts", scanInfo }) : null,
-      ...scanFacetDirs.map((facet) =>
+      ...barrelFacetDirs.map((facet) =>
         this._applyTemplate({
           basePath: facet,
           template: "facetIndex/index.ts",
@@ -936,11 +936,9 @@ export class SysExecutor extends Executor {
       await CodegenLock.run(this.workspace.workspaceRoot, `scan:${this.name}`, async () => {
         await Promise.all(this.#getScanTemplateTasks(scanInfo));
         await this.writeJson(`akan.${this.type}.json`, scanInfo.getScanResult());
-        if (this.type === "lib") this.#updateDependencies(scanInfo);
-
+        await this.#updateDependencies(scanInfo);
         if (writeLib) {
           const libInfos = [...scanInfo.getLibInfos().values()];
-          await this.#updateDependencies(scanInfo);
           await Promise.all(libInfos.flatMap((libInfo) => libInfo.exec.#getScanTemplateTasks(libInfo)));
         }
         await this.syncAgentsIndex(scanInfo);
@@ -962,39 +960,35 @@ export class SysExecutor extends Executor {
     // CLAUDE.md 는 얇은 포인터라 최초 1회만 깔아준다 — 사용자가 지우거나 고친 것을 되살리지 않는다.
     if (!(await this.exists("CLAUDE.md"))) await this.writeFile("CLAUDE.md", renderScopeClaudeMd(scope));
   }
+  //* The root is the cached copy the dependency scan read, so a name it declares is judged by the same snapshot.
   async #updateDependencies(scanInfo: AppInfo | LibInfo) {
-    const rootPackageJson = await this.workspace.getPackageJson();
-    const libPackageJson = await this.getPackageJson();
-    const dependencies = scanInfo.getScanResult().dependencies;
-    const devDependencies = scanInfo.getScanResult().devDependencies;
-    const dependencySet = new Set(dependencies);
-    const devDependencySet = new Set(devDependencies);
-    const libPkgJsonWithDeps: PackageJson = {
-      ...libPackageJson,
-      dependencies: {
-        ...Object.fromEntries(
-          Object.entries(libPackageJson.dependencies ?? {}).filter(([dep]) => !devDependencySet.has(dep)),
-        ),
-        ...(Object.fromEntries(
-          dependencies
-            .filter((dep) => rootPackageJson.dependencies?.[dep])
-            .sort()
-            .map((dep) => [dep, rootPackageJson.dependencies?.[dep]]),
-        ) as Record<string, string>),
-      },
-      devDependencies: {
-        ...Object.fromEntries(
-          Object.entries(libPackageJson.devDependencies ?? {}).filter(([dep]) => !dependencySet.has(dep)),
-        ),
-        ...(Object.fromEntries(
-          devDependencies
-            .filter((dep) => rootPackageJson.dependencies?.[dep] || rootPackageJson.devDependencies?.[dep])
-            .sort()
-            .map((dep) => [dep, rootPackageJson.devDependencies?.[dep] ?? rootPackageJson.dependencies?.[dep]]),
-        ) as Record<string, string>),
-      },
-    };
-    await this.setPackageJson(libPkgJsonWithDeps);
+    const [rootPackageJson, packageJson] = await Promise.all([
+      this.workspace.getPackageJson(),
+      this.getPackageJson({ refresh: true }),
+    ]);
+    const { dependencies: runtime, devDependencies: typeOnly, akanConfig } = scanInfo.getScanResult();
+    const kept = new Set([
+      ...ManifestDependencies.keptBy(packageJson),
+      ...akanConfig.externalLibs,
+      ...akanConfig.trustedDependencies,
+    ]);
+    //? The scan leaves the framework out of its imports on purpose, so it is never a prune candidate.
+    const isKept = (dep: string) => kept.has(dep) || isAkanFrameworkDependency(dep);
+    const { dependencies, devDependencies, removed, unverifiable } = new ManifestDependencies(
+      rootPackageJson,
+      { runtime, typeOnly },
+      isKept,
+    ).realign(packageJson);
+    const manifestPath = `${this.type}s/${this.name}/package.json`;
+    if (removed.length)
+      this.logger.info(
+        `Removed from ${manifestPath}, declared by the root and imported nowhere: ${removed.join(", ")} (list one in akan.keepDependencies to keep it)`,
+      );
+    if (unverifiable.length)
+      this.logger.warn(
+        `${manifestPath} lists ${unverifiable.join(", ")}, which the root package.json does not declare, so sync cannot tell whether it is used; kept as is`,
+      );
+    await this.setPackageJson({ ...packageJson, dependencies, devDependencies });
   }
   override async getLocalFile(targetPath: string) {
     const filePath = path.isAbsolute(targetPath) ? targetPath : `${this.type}s/${this.name}/${targetPath}`;
@@ -1119,13 +1113,21 @@ export class AppExecutor extends SysExecutor {
   static from(executor: SysExecutor | WorkspaceExecutor, name: string) {
     return new AppExecutor({ workspace: executor instanceof WorkspaceExecutor ? executor : executor.workspace, name });
   }
-  //* Not dev output: native builds and the update releases waiting to be uploaded, and the downloaded `bin` sources.
-  static readonly #keptOnStart = [path.join(".akan", "native"), path.join(".akan", "cache", "bin")];
+  //* Not dev output: the downloaded `bin` sources.
+  static readonly #keptOnStart = [path.join(".akan", "cache", "bin")];
+  //* Native builds moved to dist/native/<app>; the old folder may hold a signed release nobody uploaded yet.
+  static readonly #legacyNative = path.join(".akan", "native");
   async #removeDevOutput(dir = ".akan") {
     const entries = await readDirEntries(this.getPath(dir)).catch(() => [] as string[]);
     await Promise.all(
       entries.map(async (name) => {
         const entry = path.join(dir, name);
+        if (entry === AppExecutor.#legacyNative) {
+          this.logger.warn(
+            `apps/${this.name}/.akan/native holds native builds from before they moved to dist/native/${this.name}: upload any release waiting in its updates folders, then delete it.`,
+          );
+          return;
+        }
         if (AppExecutor.#keptOnStart.includes(entry)) return;
         if (AppExecutor.#keptOnStart.some((kept) => kept.startsWith(`${entry}${path.sep}`)))
           return await this.#removeDevOutput(entry);
@@ -1209,10 +1211,10 @@ export class AppExecutor extends SysExecutor {
     // Ports and the operation mode are dropped: `define` would bake them in and outrank the container's own values.
     if (type === "build") {
       const buildEnv = { ...env };
-      delete buildEnv.AKAN_PUBLIC_CLIENT_PORT;
-      delete buildEnv.AKAN_PUBLIC_SERVER_PORT;
-      delete buildEnv.AKAN_PUBLIC_OPERATION_MODE;
-      delete process.env.AKAN_PUBLIC_OPERATION_MODE;
+      for (const key of ["AKAN_PUBLIC_CLIENT_PORT", "AKAN_PUBLIC_SERVER_PORT", "AKAN_PUBLIC_OPERATION_MODE"]) {
+        delete buildEnv[key];
+        delete process.env[key];
+      }
       Object.assign(process.env, buildEnv);
     }
     return { env };

package/frontendBuild/csrArtifactBuilder.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import { tempDirs, writeText } from "../testHelpers";
+
+const makeTempRoot = tempDirs("akan-csr-artifact-");
+
+describe("CsrArtifactBuilder.bundleOptions", () => {
+  //? A child process: Bun reads `.env` only at start, and the bug was that this snapshot outranked `define`.
+  test("bakes the env a native build sets on process.env, not the .env value Bun loaded at start", async () => {
+    const root = await makeTempRoot();
+    await writeText(path.join(root, ".env"), "AKAN_PUBLIC_ENV=local\n");
+    await writeText(path.join(root, "entry.ts"), 'console.info("envmark:" + process.env.AKAN_PUBLIC_ENV);\n');
+    await writeText(
+      path.join(root, "build.ts"),
+      `import { CsrArtifactBuilder } from ${JSON.stringify(path.join(import.meta.dir, "csrArtifactBuilder.ts"))};
+process.env.AKAN_PUBLIC_ENV = "debug";
+const app = { getPublicEnv: () => ({ AKAN_PUBLIC_ENV: process.env.AKAN_PUBLIC_ENV }) };
+const result = await Bun.build({ ...CsrArtifactBuilder.bundleOptions(app as never, "build"), entrypoints: ["./entry.ts"] });
+console.info(await result.outputs[0].text());
+`,
+    );
+    const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith("AKAN_PUBLIC_")));
+    const proc = Bun.spawn([process.execPath, "build.ts"], { cwd: root, env, stdout: "pipe", stderr: "pipe" });
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+    expect(stderr).toBe("");
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain("envmark:debug");
+    expect(stdout).not.toContain("envmark:local");
+  });
+});

package/frontendBuild/csrArtifactBuilder.ts

@@ -54,18 +54,11 @@ export class CsrArtifactBuilder {
     );
 
     const result = await Bun.build({
-      target: "browser",
+      ...CsrArtifactBuilder.bundleOptions(this.#app, this.#command, akanConfig.optimizeImports),
       entrypoints: htmlBasePaths.map((basePath) => this.#generatedPath(CsrArtifactBuilder.htmlFilename(basePath))),
       files: generatedFiles,
       root: this.#generatedDir,
       outdir: this.#outputDir,
-      splitting: false,
-      minify: true,
-      env: "AKAN_PUBLIC_*",
-      define: bundleDefine(this.#app, this.#command, "csr"),
-      optimizeImports: akanConfig.optimizeImports,
-      // A raw `.css` in the route graph is Tailwind source; the base artifact's compiled sheet is the only stylesheet.
-      plugins: [PagesBundleBuilder.createCssStubPlugin()],
     });
 
     if (!result.success) {
@@ -78,6 +71,19 @@ export class CsrArtifactBuilder {
     return { outputDir: this.#outputDir };
   }
 
+  //? No `env` option: Bun inlines the `.env` it read at process start over `define`, so a native build's `--env` lost.
+  static bundleOptions(app: App, command: "build" | "start", optimizeImports: string[] = []) {
+    return {
+      target: "browser" as const,
+      splitting: false,
+      minify: true,
+      define: bundleDefine(app, command, "csr"),
+      optimizeImports,
+      // A raw `.css` in the route graph is Tailwind source; the base artifact's compiled sheet is the only stylesheet.
+      plugins: [PagesBundleBuilder.createCssStubPlugin()],
+    };
+  }
+
   /** The routes one basePath's HTML boots: its own plus every route outside any basePath, matching `bootCsr`. */
   static pageEntriesForBasePath(pageEntries: PageEntry[], basePath: string, basePaths: string[]): PageEntry[] {
     return CsrEntryFiles.pageEntriesForBasePath(pageEntries, basePath, basePaths);

package/frontendBuild/csrDevModuleCompiler.ts

@@ -154,7 +154,6 @@ export class CsrDevModuleCompiler {
         naming: { entry: "[dir]/[name].[ext]", asset: "assets/[name]-[hash].[ext]" },
         publicPath: this.#routePrefix,
         metafile: true,
-        env: "AKAN_PUBLIC_*",
         //? A factory runs as a classic script, where `import.meta` is a SyntaxError that takes the whole vendor file
         //? down, and Bun's cjs output keeps `import.meta.env` and spells `import.meta.url` as this disk's `file://` path.
         define: { ...this.#context.define, "import.meta": "__akanMeta" },

package/frontendBuild/csrDevResolver.ts

@@ -88,7 +88,6 @@ export class CsrDevResolver {
       target: "browser",
       metafile: true,
       external: [...(this.#context.externals ?? [])],
-      env: "AKAN_PUBLIC_*",
       define: this.#context.define,
       optimizeImports: this.#context.optimizeImports,
       plugins: [PagesBundleBuilder.createCssStubPlugin()],
@@ -112,7 +111,6 @@ export class CsrDevResolver {
       metafile: true,
       throw: false,
       external: [...(this.#context.externals ?? [])],
-      env: "AKAN_PUBLIC_*",
       define: this.#context.define,
       plugins: [
         {

package/frontendBuild/devGeneratedIndexSync.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { tempDirs } from "../testHelpers";
 import { DevGeneratedIndexSync } from "./devGeneratedIndexSync";
@@ -40,6 +40,18 @@ describe("DevGeneratedIndexSync facet barrels", () => {
     expect(content).toBe(`export * from "./aes";\nexport * from "./cloudflareApi";\nexport * from "./storageApi";\n`);
   });
 
+  test("a facet with nothing to export keeps an empty barrel, and a deleted facet gets none", async () => {
+    const root = await makeTempRoot();
+    const content = await barrelFor(root, "common", { files: ["foo.helper.ts"], dirs: [], trigger: "foo.helper.ts" });
+    expect(content).toBe("export {};\n");
+
+    const dir = path.join(root, "libs", "util", "common");
+    await rm(dir, { recursive: true });
+    const sync = new DevGeneratedIndexSync({ workspaceRoot: root });
+    expect(await sync.syncForBatch([path.join(dir, "foo.helper.ts")])).toEqual({ changedFiles: [], errors: [] });
+    expect(await Bun.file(path.join(dir, "index.ts")).exists()).toBe(false);
+  });
+
   test("ui facet exports only clean PascalCase names", async () => {
     const content = await barrelFor(await makeTempRoot(), "ui", {
       files: ["Globe.tsx", "AkanLogo.tsx", "Globe_Dynamic.tsx", "lowerStart.tsx"],