@akanjs/devkit 3.0.1 → 3.0.2-rc.0

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.1",
+  "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.1",
+    "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/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__"]
 }

package/workspaceLayout.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
 import {
   appRootAllowedDirs,
   appRootAllowedFiles,
+  facetIndexShadowOf,
   isAllowedLibFacetRootFile,
   isScannedRootEntry,
   libRootAllowedDirs,
@@ -34,7 +35,7 @@ describe("app root layout allowlist", () => {
   test("names what a Capacitor app kept in its root as a leftover, not an unknown entry", () => {
     for (const name of ["android", "ios", "mobile", "capacitor.config.ts", "capacitor.config.json"]) {
       expect(appRootAllowedFiles.has(name) || appRootAllowedDirs.has(name)).toBe(false);
-      expect(rootEntryHintOf("app", name)).toContain(".akan/native/<target>");
+      expect(rootEntryHintOf("app", name)).toContain("dist/native/<app>/<target>");
     }
     expect(rootEntryHintOf("app", "base")).toBeNull();
     expect(rootEntryHintOf("lib", "ios")).toBeNull();
@@ -78,6 +79,28 @@ describe("lib root layout allowlist", () => {
   });
 });
 
+describe("hand-written facet index", () => {
+  test("flags every index Bun resolves ahead of the generated barrel, at the root of each barrel facet", () => {
+    for (const facet of ["ui", "webkit", "srvkit", "common", "plugin"])
+      for (const filename of ["index.tsx", "index.jsx", "index.mts"])
+        expect(facetIndexShadowOf(`${facet}/${filename}`)).toContain(`shadows the generated ${facet}/index.ts`);
+    expect(facetIndexShadowOf("ui/index.tsx")).toContain("Delete it");
+  });
+
+  test("leaves the generated barrel, a folder namespace, and folders without a barrel alone", () => {
+    for (const relativePath of [
+      "ui/index.ts",
+      "ui/index.js",
+      "ui/Chat/index.tsx",
+      "ui/Chat/index_.tsx",
+      "page/index.tsx",
+      "lib/index.tsx",
+      "index.tsx",
+    ])
+      expect(facetIndexShadowOf(relativePath)).toBeNull();
+  });
+});
+
 describe("lib facet root allowlist", () => {
   test("admits the generated support facets and a root signal test", () => {
     expect(isAllowedLibFacetRootFile("cnst.ts")).toBe(true);

package/workspaceLayout.ts

@@ -84,7 +84,24 @@ const libFacetRootTestPattern = /^[A-Za-z][A-Za-z0-9_-]*\.signal\.(test|spec)\.(
 export const isAllowedLibFacetRootFile = (filename: string) =>
   libFacetRootAllowedFiles.has(filename) || libFacetRootTestPattern.test(filename);
 
-//* What a Capacitor app kept in its root. The native runtime generates its projects under `.akan/native/<target>`, so
+export const barrelFacetDirs = ["ui", "webkit", "srvkit", "common", "plugin"] as const;
+
+//* Bun resolves a folder import to `index.tsx`, `index.jsx` or `index.mts` ahead of `index.ts`, and TypeScript to
+//* `index.ts` first, so one of these beside the generated barrel typechecks every name the barrel adds and serves none.
+const barrelShadowingIndexFiles = new Set(["index.tsx", "index.jsx", "index.mts"]);
+
+export const facetIndexShadowOf = (sysRelativePath: string) => {
+  const [facet, filename = "", ...nested] = sysRelativePath.split("/");
+  if (nested.length || !barrelShadowingIndexFiles.has(filename) || !barrelFacetDirs.some((dir) => dir === facet))
+    return null;
+  return (
+    `shadows the generated ${facet}/index.ts: Bun loads ${filename} and TypeScript checks index.ts, so a name only ` +
+    `the generated barrel exports typechecks and is undefined at runtime. Delete it, since the generated barrel ` +
+    `re-exports every file and folder in ${facet}/; a namespace it builds belongs in ${facet}/<Folder>/index.tsx`
+  );
+};
+
+//* What a Capacitor app kept in its root. The native runtime generates its projects under `dist/native/<app>/<target>`, so
 //* these are named as leftovers instead of as unknown entries.
 const retiredAppRootEntries = new Set([
   "android",
@@ -97,7 +114,7 @@ const retiredAppRootEntries = new Set([
 
 export const rootEntryHintOf = (type: SysType, name: string) =>
   type === "app" && retiredAppRootEntries.has(name)
-    ? "a Capacitor-era entry; the native runtime generates its projects under .akan/native/<target>, so delete it"
+    ? "a Capacitor-era entry; the native runtime generates its projects under dist/native/<app>/<target>, so delete it"
     : null;
 
 // scanSync reads roots through `Bun.Glob("*")`, which skips dotfiles, so doctor skips them the same way.