@akanjs/devkit 3.0.0 → 3.0.2-rc.0

package/mobile/nativeApp.test.ts

@@ -22,6 +22,7 @@ const target = (config: Partial<AkanNativeTarget> = {}) => ({
 });
 
 const appDir = "/repo/apps/portal";
+const nativeDir = "/repo/dist/native/portal";
 
 const fakeApp = (plugins: AkanPlugin[] = []) =>
   ({
@@ -31,24 +32,67 @@ const fakeApp = (plugins: AkanPlugin[] = []) =>
     getScanInfo: () => ({ getLibs: () => [] }),
     dist: { cwdPath: "/repo/dist/apps/portal" },
     getConfig: async () => ({ i18n: { locales: ["en", "ko"] }, api: { prefix: "/api", websocketPrefix: "/ws" } }),
+    getDevPort: async () => 8284,
     collectPlugins: async () => plugins,
     logger: { warn: () => undefined },
   }) as unknown as App;
 
 describe("NativeApp", () => {
-  test("keeps each target's web root and each platform's output apart", () => {
+  test("keeps each target's web root and each platform's output apart, outside the dist akan build empties", () => {
     const admin = new NativeApp(fakeApp(), target({ name: "admin", basePath: "admin" }));
 
-    expect(admin.web.dir).toBe(path.join(appDir, ".akan/native/admin/web"));
-    expect(admin.outDir("ios")).toBe(path.join(appDir, ".akan/native/admin/build/ios"));
-    expect(admin.outDir("android")).toBe(path.join(appDir, ".akan/native/admin/build/android"));
-    expect(admin.devOutDir("macos")).toBe(path.join(appDir, ".akan/native/admin/dev/macos"));
+    expect(admin.web.dir).toBe(path.join(nativeDir, "admin/web"));
+    expect(admin.outDir("ios")).toBe(path.join(nativeDir, "admin/build/ios"));
+    expect(admin.outDir("android")).toBe(path.join(nativeDir, "admin/build/android"));
+    expect(admin.devOutDir("macos")).toBe(path.join(nativeDir, "admin/dev/macos"));
+    expect(admin.updatesDir).toBe(path.join(nativeDir, "admin/updates"));
+    expect(path.relative("/repo/dist/apps/portal", admin.targetRoot)).toStartWith("..");
+  });
+
+  describe("the server a release build's page calls", () => {
+    const runtimeEnvOf = async (env: "local" | "debug", options: { server?: boolean } = {}) => {
+      const nativeApp = new NativeApp(fakeApp(), target(), env);
+      let seen: Record<string, string> | undefined;
+      nativeApp.assembleWeb = async () => undefined as never;
+      nativeApp.prepare = async () =>
+        ({
+          config: {},
+          api: {
+            build: async ({ env }: { env?: Record<string, string> }) => {
+              seen = env;
+              return { artifacts: [], warnings: [] };
+            },
+          },
+        }) as never;
+      await nativeApp.build("linux", options.server ? { server: { dir: "/s", entry: "main.js", env: {} } } : {});
+      return seen;
+    };
+
+    test("a local release calls the app's own dev server, not 8282", async () => {
+      expect(await runtimeEnvOf("local")).toEqual({ PUBLIC_AKAN_SERVER_URL: "http://localhost:8284" });
+    });
+
+    test("a cloud release and a release carrying its server name none", async () => {
+      expect(await runtimeEnvOf("debug")).toEqual({});
+      expect(await runtimeEnvOf("local", { server: true })).toEqual({});
+    });
+
+    test("an AKAN_PUBLIC_SERVER_URL the bundle was built with is left to win", async () => {
+      process.env.AKAN_PUBLIC_SERVER_URL = "http://192.168.0.10:8284";
+      try {
+        expect(await runtimeEnvOf("local")).toEqual({});
+      } finally {
+        delete process.env.AKAN_PUBLIC_SERVER_URL;
+      }
+    });
   });
 
   test("a dev build bundles no page a release build left, and builds apart from the release it would empty", async () => {
+    const root = await makeTempRoot();
     const app = {
       ...fakeApp(),
-      cwdPath: await makeTempRoot(),
+      cwdPath: path.join(root, "apps/portal"),
+      workspace: { workspaceRoot: root },
       logger: { info: () => undefined, debug: () => undefined, warn: () => undefined },
     } as unknown as App;
     const nativeApp = new NativeApp(app, target());
@@ -118,7 +162,12 @@ describe("NativeApp", () => {
   test("assembles each platform's web root with that platform's indexPath", async () => {
     const root = await makeTempRoot();
     await writeText(path.join(root, "dist/csr/index.html"), "<html><head></head><body></body></html>");
-    const app = { ...fakeApp(), cwdPath: root, dist: { cwdPath: path.join(root, "dist") } } as unknown as App;
+    const app = {
+      ...fakeApp(),
+      cwdPath: root,
+      workspace: { workspaceRoot: root },
+      dist: { cwdPath: path.join(root, "dist") },
+    } as unknown as App;
     const nativeApp = new NativeApp(app, target({ indexPath: "/mobile", desktop: { indexPath: "/console" } }));
     const injected = async () => await Bun.file(path.join(nativeApp.web.dir, "index.html")).text();
 
@@ -139,7 +188,7 @@ describe("NativeApp", () => {
 
     expect(warnings).toEqual([]);
     expect(config.plugins).toEqual([...NativeConfig.basePlugins, "push"]);
-    expect(config.web.dir).toBe(path.join(appDir, ".akan/native/default/web"));
+    expect(config.web.dir).toBe(path.join(nativeDir, "default/web"));
   });
 
   test("a config nothing is built from (the update key's) stages no desktop bin", async () => {

package/mobile/nativeApp.ts

@@ -63,7 +63,8 @@ export class NativeApp {
     readonly target: ResolvedMobileTarget,
     readonly env?: NativeEnv,
   ) {
-    this.targetRoot = path.join(app.cwdPath, ".akan", "native", target.name);
+    //* Outside `dist/apps/<app>`, which every `akan build` empties: a signed release waiting for upload lives here.
+    this.targetRoot = path.join(app.workspace.workspaceRoot, "dist", "native", app.name, target.name);
     this.web = new NativeWebDir(path.join(this.targetRoot, "web"));
   }
 
@@ -161,13 +162,18 @@ export class NativeApp {
   };
 
   //* `AKAN_PUBLIC_*` is already inlined into the CSR bundle, so the runtime reads no .env file of its own.
-  #task(platform: NativePlatform, config: AkanNativeConfig, outDir = this.outDir(platform)): TaskOptions {
+  #task(
+    platform: NativePlatform,
+    config: AkanNativeConfig,
+    { outDir = this.outDir(platform), env = {} }: { outDir?: string; env?: Record<string, string> } = {},
+  ): TaskOptions {
     return {
       appDir: this.app.cwdPath,
       config,
       platform,
       outDir,
       envFiles: false,
+      env,
       skipWebBuild: true,
       log: (event) => {
         if (event.level === "error") this.app.logger.error(event.message);
@@ -179,6 +185,13 @@ export class NativeApp {
     };
   }
 
+  //* A local release has no dev gateway behind it, so its page calls the app's dev server (baseEnv csrServerUrl), on
+  //* the port `akan start` gives this app. A carried server hands the page its own URL at launch instead.
+  async #runtimeEnv(server?: DesktopServerBundle): Promise<Record<string, string>> {
+    if (this.env !== "local" || server || process.env.AKAN_PUBLIC_SERVER_URL) return {};
+    return { PUBLIC_AKAN_SERVER_URL: `http://localhost:${await this.app.getDevPort()}` };
+  }
+
   async build(
     platform: NativePlatform,
     { profile = "release", server, installer = false, arch }: NativeBuildOptions = {},
@@ -188,7 +201,7 @@ export class NativeApp {
     await this.assembleWeb(platform);
     const { api, config } = await this.prepare(platform, server, arch);
     return await api.build({
-      ...this.#task(platform, config),
+      ...this.#task(platform, config, { env: await this.#runtimeEnv(server) }),
       profile,
       ...(arch ? { arch } : {}),
       ...(platform === "windows"
@@ -219,7 +232,7 @@ export class NativeApp {
     await this.assembleWeb(platform);
     const { api, config } = await this.prepare(platform, server);
     return await api.run({
-      ...this.#task(platform, config),
+      ...this.#task(platform, config, { env: await this.#runtimeEnv(server) }),
       profile,
       onLine: this.#appLine,
       ...(device ? { device } : {}),
@@ -238,7 +251,7 @@ export class NativeApp {
       await this.web.clear();
       const [{ api, config }, { api: routes }] = await Promise.all([this.prepare(platform), this.app.getConfig()]);
       const session = await api.dev({
-        ...this.#task(platform, config, this.devOutDir(platform)),
+        ...this.#task(platform, config, { outDir: this.devOutDir(platform) }),
         upstream,
         hmrPath: "/_akan/hmr",
         //? A dev page calls its own origin (akanjs baseEnv), so the gateway relays the socket it opens for the API too.
@@ -279,7 +292,7 @@ export class NativeApp {
     await this.assembleWeb("ios");
     const { api, config } = await this.prepare("ios");
     return await api.release({
-      ...this.#task("ios", config),
+      ...this.#task("ios", config, { env: await this.#runtimeEnv() }),
       platform: "ios",
       signing: { ...(teamId ? { teamId } : {}), ...(adHoc ? { distribution: "ad-hoc" as const } : {}) },
     });
@@ -300,7 +313,7 @@ export class NativeApp {
     await this.assembleWeb(platform);
     const { api, config } = await this.prepare(platform, server);
     return await api.publishUpdate({
-      ...this.#task(platform, config),
+      ...this.#task(platform, config, { env: await this.#runtimeEnv(server) }),
       platform,
       out: this.updatesDir,
       ...(channel ? { channel } : {}),
@@ -363,7 +376,12 @@ export class NativeApp {
     const signing = NativeApp.androidSigning();
     await this.assembleWeb("android");
     const { api, config } = await this.prepare("android");
-    return await api.release({ ...this.#task("android", config), platform: "android", signing, formats });
+    return await api.release({
+      ...this.#task("android", config, { env: await this.#runtimeEnv() }),
+      platform: "android",
+      signing,
+      formats,
+    });
   }
 
   /** An unsigned OTA update of this target's web bundle for `platform`, and the channel its binary follows. */
@@ -377,7 +395,7 @@ export class NativeApp {
     const packed = await api.packUpdate({
       ...this.#task(platform, config),
       platform,
-      out: out ?? path.join(this.targetRoot, "updates", platform),
+      out: out ?? path.join(this.updatesDir, platform),
     });
     return { ...packed, channel: config.updates.channel ?? "production" };
   }

package/mobile/nativeConfig.test.ts

@@ -45,11 +45,33 @@ const adminTarget: AkanNativeTarget = {
 const updatesKey = Buffer.alloc(32, 7).toString("base64");
 
 describe("NativeConfig.build", () => {
+  test("hands the dmg window over with its pictures resolved against the app folder", () => {
+    const build = (dmg: NonNullable<AkanNativeTarget["desktop"]>["dmg"]) =>
+      NativeConfig.build({
+        appPath: "/repo/apps/minimal",
+        target: { ...minimalTarget, desktop: { dmg } },
+        webDir: "/repo/dist/native/minimal/default/web",
+        contributions: [],
+        locales: ["en"],
+        platform: "macos",
+      }).config.desktop?.dmg;
+
+    expect(build({ background: "assets/dmg.png", background2x: "assets/dmg@2x.png", app: { x: 150, y: 190 } })).toEqual(
+      {
+        background: path.resolve("/repo/apps/minimal", "assets/dmg.png"),
+        background2x: path.resolve("/repo/apps/minimal", "assets/dmg@2x.png"),
+        app: { x: 150, y: 190 },
+      },
+    );
+    expect(build({ background: false, iconSize: 96 })).toEqual({ background: false, iconSize: 96 });
+    expect(build(undefined)).toBeUndefined();
+  });
+
   test("turns the minimal app's push target into the runtime's config, single-instance carrying its link scheme", () => {
     const { config, warnings } = NativeConfig.build({
       appPath: "/repo/apps/minimal",
       target: minimalTarget,
-      webDir: "/repo/apps/minimal/.akan/native/default/web",
+      webDir: "/repo/dist/native/minimal/default/web",
       contributions: [{ permission: "push", plugins: ["push"] }],
       locales: ["en", "ko"],
       platform: "android",
@@ -58,7 +80,7 @@ describe("NativeConfig.build", () => {
     expect(warnings).toEqual([]);
     expect(config).toEqual({
       app: { id: "com.minimal.dev.app", name: "minimal", fileName: "minimal", version: "0.0.1", build: 1 },
-      web: { dir: "/repo/apps/minimal/.akan/native/default/web" },
+      web: { dir: "/repo/dist/native/minimal/default/web" },
       plugins: [...NativeConfig.basePlugins, "single-instance", "push"],
       capabilities: [
         {
@@ -80,7 +102,7 @@ describe("NativeConfig.build", () => {
     const { config, warnings } = NativeConfig.build({
       appPath: "/repo/apps/portal",
       target: adminTarget,
-      webDir: "/repo/apps/portal/.akan/native/admin/web",
+      webDir: "/repo/dist/native/portal/admin/web",
       contributions: [],
       locales: ["en", "ko"],
       platform: "android",
@@ -89,7 +111,7 @@ describe("NativeConfig.build", () => {
     expect(warnings).toEqual(["Permission 'speech' has no native plugin yet; the app ships without it."]);
     expect(config).toEqual({
       app: { id: "com.portal.admin", name: "Portal Admin", fileName: "portal-admin", version: "2.1.0", build: 42 },
-      web: { dir: "/repo/apps/portal/.akan/native/admin/web" },
+      web: { dir: "/repo/dist/native/portal/admin/web" },
       plugins: [...NativeConfig.basePlugins, "camera", "geolocation", "contacts", "iap"],
       capabilities: [
         {

package/mobile/nativeConfig.ts

@@ -1,7 +1,14 @@
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import type { AkanNativeConfig } from "@akanjs/native/config";
-import type { AkanNativeTarget, AkanNativeValue, AkanPluginNativeConfig, NativeEnv, NativePermission } from "akanjs";
+import type {
+  AkanNativeDmgConfig,
+  AkanNativeTarget,
+  AkanNativeValue,
+  AkanPluginNativeConfig,
+  NativeEnv,
+  NativePermission,
+} from "akanjs";
 import type { DesktopServerBundle } from "./desktopServerStage";
 import { type NativePlatform, resolveAppId } from "./mobileTarget";
 import type { NativePluginFolder } from "./nativePluginFolders";
@@ -171,6 +178,7 @@ export class NativeConfig {
       window: NativeConfig.#compact({ ...target.desktop?.window }),
       server: desktopServer,
       bin: desktopBin,
+      dmg: NativeConfig.#dmg(target.desktop?.dmg, abs),
     });
     const config: AkanNativeConfig = {
       app: {
@@ -234,6 +242,16 @@ export class NativeConfig {
     return { ...splash, ...(splash.image ? { image: abs(splash.image) } : {}) };
   }
 
+  static #dmg(dmg: AkanNativeDmgConfig | undefined, abs: (relative: string) => string) {
+    if (!dmg) return undefined;
+    const { background, background2x, ...layout } = dmg;
+    return {
+      ...layout,
+      ...(background === undefined ? {} : { background: background === false ? false : abs(background) }),
+      ...(background2x ? { background2x: abs(background2x) } : {}),
+    };
+  }
+
   //? akanConfig refuses a target whose merged updates lack url or publicKey; the type still has them optional.
   static #updates(target: AkanNativeTarget, env?: NativeEnv): NonNullable<AkanNativeConfig["updates"]> | undefined {
     const { url, publicKey, channel = env, ...rest } = target.updates ?? {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.0.0",
+  "version": "3.0.2-rc.0",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -47,7 +47,7 @@
     "@earendil-works/pi-tui": "0.86.1",
     "@inquirer/prompts": "^8.4.3",
     "@tailwindcss/node": "^4.3.0",
-    "akanjs": "3.0.0",
+    "akanjs": "3.0.2-rc.0",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",

package/platformTest/LinuxDockerTarget.ts

@@ -73,7 +73,7 @@ export class LinuxDockerTarget extends PlatformTestTarget {
       [
         "docker",
         "exec",
-        ...Object.entries(PlatformTestTarget.gitIdentityEnv).flatMap(([key, value]) => ["-e", `${key}=${value}`]),
+        ...Object.entries(PlatformTestTarget.remoteEnv).flatMap(([key, value]) => ["-e", `${key}=${value}`]),
         container,
         "sh",
         "-c",

package/platformTest/PlatformTestTarget.ts

@@ -36,7 +36,9 @@ export interface PlatformRunContext {
 export abstract class PlatformTestTarget {
   static readonly installIdleMs = 5 * 60_000;
   static readonly testIdleMs = 2 * 60_000;
-  protected static readonly gitIdentityEnv = {
+  protected static readonly remoteEnv = {
+    //? No suite drives puppeteer's Chrome, and downloading it into every fresh container fails install on a DNS blip.
+    PUPPETEER_SKIP_DOWNLOAD: "true",
     GIT_AUTHOR_NAME: "akan-test",
     GIT_AUTHOR_EMAIL: "akan-test@localhost",
     GIT_COMMITTER_NAME: "akan-test",

package/platformTest/WindowsSshTarget.ts

@@ -71,7 +71,7 @@ export class WindowsSshTarget extends PlatformTestTarget {
       "$ProgressPreference = 'SilentlyContinue'",
       "[Console]::OutputEncoding = [Text.Encoding]::UTF8",
       "'PID=' + $PID",
-      ...Object.entries(PlatformTestTarget.gitIdentityEnv).map(([key, value]) => `$env:${key} = '${value}'`),
+      ...Object.entries(PlatformTestTarget.remoteEnv).map(([key, value]) => `$env:${key} = '${value}'`),
       `Set-Location -LiteralPath '${runDir}\\w'`,
       `cmd /c "${command} 2>&1"`,
       "exit $LASTEXITCODE",

package/qualityScanner.test.ts

@@ -219,6 +219,20 @@ describe("AkanQualityScanner layout rules", () => {
     ]);
   });
 
+  test("flags a hand-written facet index beside the generated barrel, but not a folder namespace", async () => {
+    const root = await makeWorkspace({
+      "libs/demo/ui/index.tsx": 'export { Chat } from "./Chat";\n',
+      "libs/demo/ui/Chat.tsx": "export const Chat = () => null;\n",
+      "libs/demo/ui/Page/index.tsx": 'export { Inner } from "./Inner";\n',
+    });
+
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.layout.facet-index-shadow");
+
+    expect(warnings.map((warning) => warning.file)).toEqual(["libs/demo/ui/index.tsx"]);
+    expect(warnings[0]?.message).toContain("index.tsx shadows the generated ui/index.ts");
+    expect(warnings[0]?.fix).toContain("akan sync");
+  });
+
   test("keeps a root signal test out of the lib facet rule", async () => {
     const root = await makeWorkspace({
       "libs/demo/lib/cnst.ts": "export const cnst = 1;\n",
@@ -233,6 +247,43 @@ describe("AkanQualityScanner layout rules", () => {
   });
 });
 
+describe("AkanQualityScanner class export files", () => {
+  test("allow a type only the class reads, and flag an exported type and any helper beside the class", async () => {
+    const root = await makeWorkspace({
+      "libs/demo/srvkit/vendorApi.ts": [
+        "interface VendorUser {",
+        "  id: string;",
+        "}",
+        "type VendorPage = { items: VendorUser[] };",
+        "export interface VendorApiOptions {",
+        "  key: string;",
+        "}",
+        "export interface VendorReceipt {",
+        "  id: string;",
+        "}",
+        'export type VendorStatus = "ok" | "fail";',
+        "enum VendorRegion {",
+        "  Kr,",
+        "}",
+        "const pageSize = 100;",
+        "const toUser = (page: VendorPage) => page.items[0];",
+        "export class VendorApi {}",
+        "",
+      ].join("\n"),
+    });
+
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.file.class-export-global-declaration");
+
+    expect(warnings.map((warning) => /"(\w+)"/.exec(warning.message)?.[1])).toEqual([
+      "VendorReceipt",
+      "VendorStatus",
+      "VendorRegion",
+      "pageSize",
+      "toUser",
+    ]);
+  });
+});
+
 describe("bang comments in browser-reachable files", () => {
   const bangWarningsIn = async (files: Record<string, string>) => {
     const result = await new AkanQualityScanner().scan(await makeWorkspace(files));

package/qualityScanner.ts

@@ -7,7 +7,13 @@ import ts from "typescript";
 import { AbstractDoc } from "./abstractDoc";
 import { FormSetterScanner } from "./formSetterScanner";
 import { fileWarning, formatSsrBalance, type SsrBalanceEntry, SsrScanner } from "./ssrScanner";
-import { isAllowedLibFacetRootFile, rootAllowedDirs, rootAllowedFiles, rootEntryHintOf } from "./workspaceLayout";
+import {
+  facetIndexShadowOf,
+  isAllowedLibFacetRootFile,
+  rootAllowedDirs,
+  rootAllowedFiles,
+  rootEntryHintOf,
+} from "./workspaceLayout";
 
 type QualitySeverity = "warning";
 type QualityScope = "global" | "file" | "convention" | "layout" | "ssr" | "agent";
@@ -140,6 +146,8 @@ const RULE_FIXES: Record<string, string> = {
     "Move the folder's contents into a conventional lib folder (common, env, lib, page, private, public, srvkit, ui, or webkit) and delete it.",
   "akan.layout.lib-facet-file":
     "Move the file into a domain module folder under lib/; keep the lib facet root limited to generated support facets.",
+  "akan.layout.facet-index-shadow":
+    "Delete the hand-written index file and run akan sync; move a namespace it builds into <facet>/<Folder>/index.tsx.",
   "akan.layout.module-ui-file":
     "Rename the file to an allowed module UI name, or move it to ui/ if it is not a module component.",
   "akan.ssr.unnecessary-use-client":
@@ -325,6 +333,8 @@ export class AkanQualityScanner {
     for (const declaration of getTopLevelDeclarations(sourceFile)) {
       if (declaration.kind === "class" && exportedClassNames.includes(declaration.name)) continue;
       if (declaration.kind === "interface" && allowedInterfaceNames.has(declaration.name)) continue;
+      //? A shape only this class reads (a vendor response it parses) is erased at build; a sibling file buys nothing.
+      if ((declaration.kind === "interface" || declaration.kind === "type") && !declaration.exported) continue;
       warnings.push(
         fileWarning(
           "akan.file.class-export-global-declaration",
@@ -432,6 +442,17 @@ export class AkanQualityScanner {
         );
     }
 
+    const facetShadow = rootEntry?.isDir ? facetIndexShadowOf(sourceFile.file.split("/").slice(2).join("/")) : null;
+    if (facetShadow)
+      warnings.push(
+        fileWarning(
+          "akan.layout.facet-index-shadow",
+          "layout",
+          sourceFile.file,
+          `${path.basename(sourceFile.file)} ${facetShadow}.`,
+        ),
+      );
+
     const libFacetFile = getLibFacetRootFile(sourceFile.file);
     if (libFacetFile && !isAllowedLibFacetRootFile(libFacetFile))
       warnings.push(

package/scanInfo.ts

@@ -10,7 +10,14 @@ import type {
 } from "./akanConfig";
 import { AkanAppConfig } from "./akanConfig";
 import { AppExecutor, LibExecutor, PkgExecutor, WorkspaceExecutor } from "./executors";
-import { isAllowedLibFacetRootFile, rootAllowedDirs, rootAllowedFiles, rootEntryHintOf } from "./workspaceLayout";
+import {
+  barrelFacetDirs,
+  facetIndexShadowOf,
+  isAllowedLibFacetRootFile,
+  rootAllowedDirs,
+  rootAllowedFiles,
+  rootEntryHintOf,
+} from "./workspaceLayout";
 
 const scalarFileTypes = ["constant", "dictionary", "document", "template", "unit", "util", "view", "zone"] as const;
 type ScalarFileType = (typeof scalarFileTypes)[number];
@@ -74,6 +81,11 @@ async function assertScanConvention(exec: AppExecutor | LibExecutor, libRoot: {
   for (const dirname of dirs)
     if (!allowedRootDirs.has(dirname))
       addViolation(dirname, rootEntryHintOf(exec.type, dirname) ?? `unsupported ${exec.type} root folder`);
+  for (const facet of barrelFacetDirs)
+    for (const filename of await exec.readdir(facet)) {
+      const shadow = facetIndexShadowOf(`${facet}/${filename}`);
+      if (shadow) addViolation(path.join(facet, filename), shadow);
+    }
 
   //* A lib has no `getPageKeys`, so its own route files are validated here.
   if (exec.type === "lib")
@@ -275,7 +287,7 @@ class ScanInfo {
   }
 }
 
-const isAkanFrameworkDependency = (dep: string) => dep === "akanjs" || dep.startsWith("akanjs/");
+export const isAkanFrameworkDependency = (dep: string) => dep === "akanjs" || dep.startsWith("akanjs/");
 export class AppInfo extends ScanInfo {
   readonly type = "app";
   readonly exec: AppExecutor;

package/subspace.test.ts

@@ -10,7 +10,16 @@ import { isolateEnv, tempDirs, writeText as write } from "./testHelpers";
 //? Each case drives several real git clones and pushes; on a 4-core Windows VM that alone lands at 2-5s.
 setDefaultTimeout(20_000);
 
-isolateEnv({ AKAN_PUBLIC_REPO_NAME: "workspace", AKAN_PUBLIC_SERVE_DOMAIN: "example.com", AKAN_PUBLIC_ENV: "local" });
+//? Subspace commits in its clone with the host's identity, and a CI host has none configured.
+isolateEnv({
+  AKAN_PUBLIC_REPO_NAME: "workspace",
+  AKAN_PUBLIC_SERVE_DOMAIN: "example.com",
+  AKAN_PUBLIC_ENV: "local",
+  GIT_AUTHOR_NAME: "t",
+  GIT_AUTHOR_EMAIL: "t@t",
+  GIT_COMMITTER_NAME: "t",
+  GIT_COMMITTER_EMAIL: "t@t",
+});
 const makeTempRoot = tempDirs("akan-subspace-");
 
 const git = async (cwd: string, args: string[]) =>

package/testHelpers.ts

@@ -1,4 +1,5 @@
 import { afterEach, beforeEach } from "bun:test";
+import { existsSync } from "node:fs";
 import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -122,6 +123,22 @@ export const writeJson = async (filePath: string, value: object) => {
   await writeText(filePath, `${JSON.stringify(value, null, 2)}\n`);
 };
 
+const repoRoot = path.resolve(import.meta.dir, "../../..");
+const biomeBin = path.join(repoRoot, "node_modules", ".bin", process.platform === "win32" ? "biome.exe" : "biome");
+export const hasBiome = existsSync(biomeBin);
+
+//? Through stdin under a repo-relative name, so the repo's own Biome config and overrides judge content kept elsewhere.
+export const formatWithBiome = async (content: string, repoPath: string) => {
+  const proc = Bun.spawn([biomeBin, "check", "--write", `--stdin-file-path=${repoPath}`], {
+    cwd: repoRoot,
+    stdin: new Blob([content]),
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [output] = await Promise.all([new Response(proc.stdout).text(), proc.exited]);
+  return output;
+};
+
 const tsconfigJson = { compilerOptions: { target: "ESNext", paths: {} } };
 
 export const createTempApp = async (appName = "demo", parentDir?: string) => {

package/transforms/transforms.test.ts

@@ -230,6 +230,19 @@ describe("BarrelAnalyzer and rewriteBarrelImports", () => {
     expect(secondMap?.get("b2")).toEqual({ subpath: "second/b2", originalName: "b2" });
   });
 
+  test("an empty facet barrel maps no name, so an import from it is left as written", async () => {
+    const root = await makeTempRoot();
+    const pkgDir = path.join(root, "common");
+    await write(path.join(pkgDir, "index.ts"), "export {};\n");
+    const analyzer = new BarrelAnalyzer({
+      resolvePackage: async () => ({ pkgName: "@libs/util/common", entryFile: path.join(pkgDir, "index.ts"), pkgDir }),
+    });
+
+    expect(await analyzer.analyze("@libs/util/common")).toEqual(new Map());
+    const source = 'import { pad } from "@libs/util/common";\n';
+    expect(await rewriteBarrelImports(source, ["@libs/util/common"], analyzer)).toBeNull();
+  });
+
   test("rewrites flattenable named imports and preserves default, type, and unknown imports", async () => {
     const analyzer = fakeAnalyzer([
       ["A", { subpath: "@scope/pkg/leaf", originalName: "A" }],

package/tsconfig.json

@@ -1,17 +1,12 @@
 {
   "compilerOptions": {
-    "lib": [
-      "ESNext",
-      "DOM"
-    ],
+    "lib": ["ESNext", "DOM"],
     "target": "ESNext",
     "module": "esnext",
     "moduleDetection": "force",
     "jsx": "react-jsx",
     "allowJs": true,
-    "types": [
-      "bun"
-    ],
+    "types": ["bun"],
     "moduleResolution": "bundler",
     "allowImportingTsExtensions": true,
     "verbatimModuleSyntax": true,
@@ -30,12 +25,6 @@
   },
   "extends": "../../../tsconfig.json",
   "files": [],
-  "include": [
-    "**/*.ts",
-    "**/*.tsx",
-    "../../akanjs/server/types/*.d.ts"
-  ],
-  "exclude": [
-    "lint/__fixtures__"
-  ]
+  "include": ["**/*.ts", "**/*.tsx", "../../akanjs/server/types/*.d.ts"],
+  "exclude": ["lint/__fixtures__"]
 }