@akanjs/devkit 3.0.1 → 3.0.2

package/lint/no-unguarded-endpoint.grit

@@ -0,0 +1,73 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// `SignalContext` checks `signalOption.guards ?? []`, so an endpoint, a named slice, or a slice's root query declaring
+// none is open to every HTTP and websocket caller. An option the rule cannot read, a variable or a spread, is left alone.
+or {
+  JsCallExpression(callee = $callee, arguments = JsCallArguments(args = $args)) as $call where {
+    or {
+      and {
+        $callee <: r"(?:query|mutation|pubsub|message)",
+        $call <: within JsCallExpression(callee = `endpoint`),
+        or { $args <: [$returns], $args <: [$returns, $option] }
+      },
+      and {
+        $callee <: `init`,
+        $call <: within JsCallExpression(callee = `slice`),
+        or { $args <: [], $args <: [$option] }
+      }
+    },
+    or {
+      $option <: undefined,
+      $option <: JsObjectExpression(members = $members) where {
+        or {
+          $members <: not some or {
+            JsPropertyObjectMember(name = r"(?:guards|\x22guards\x22|'guards')"),
+            JsShorthandPropertyObjectMember(name = r"guards"),
+            JsSpread()
+          },
+          $members <: some JsPropertyObjectMember(name = r"(?:guards|\x22guards\x22|'guards')", value = JsArrayExpression(elements = []))
+        }
+      }
+    },
+    register_diagnostic(
+      span = $callee,
+      message = "No `guards`, so every HTTP and websocket caller reaches this endpoint: a missing or empty `guards` fails open, which is also why MCP refuses it. Name the guards it needs, or write `guards: [Public]` when anonymous access is the intent.",
+      severity = "warn"
+    )
+  },
+  JsCallExpression(callee = `slice`, arguments = JsCallArguments(args = [$srv, $sliceOption, ...])) where {
+    $sliceOption <: JsObjectExpression(members = $sliceMembers),
+    or {
+      and {
+        $sliceMembers <: not some or {
+          JsPropertyObjectMember(name = r"(?:guards|\x22guards\x22|'guards')"),
+          JsShorthandPropertyObjectMember(name = r"guards"),
+          JsSpread()
+        },
+        register_diagnostic(
+          span = $sliceOption,
+          message = "No `guards` on this slice, so every HTTP and websocket caller reaches its root query and generated reads and writes: a missing guard fails open. Pass { guards: { root: Admin, get: …, cru: … } }, naming `Public` where anonymous access is the intent.",
+          severity = "warn"
+        )
+      },
+      and {
+        $sliceMembers <: some JsPropertyObjectMember(name = r"(?:guards|\x22guards\x22|'guards')", value = $guardMap),
+        $guardMap <: JsObjectExpression(members = $guardKeys),
+        or {
+          $guardKeys <: not some or {
+            JsPropertyObjectMember(name = r"(?:root|\x22root\x22|'root')"),
+            JsShorthandPropertyObjectMember(name = r"root"),
+            JsSpread()
+          },
+          $guardKeys <: some JsPropertyObjectMember(name = r"(?:root|\x22root\x22|'root')", value = JsArrayExpression(elements = []))
+        },
+        register_diagnostic(
+          span = $guardMap,
+          message = "No `root` guard on this slice, so its root query lists any filter to every HTTP and websocket caller: a missing or empty `root` fails open. Write `root: Admin`.",
+          severity = "warn"
+        )
+      }
+    }
+  }
+}

package/manifestDependencies.ts

@@ -0,0 +1,65 @@
+import { LibSource } from "./libSource";
+import type { PackageJson } from "./types";
+
+type DependencyMap = Record<string, string>;
+
+export interface ScannedImports {
+  runtime: readonly string[];
+  typeOnly: readonly string[];
+}
+
+export class ManifestDependencies {
+  readonly #root: PackageJson;
+  readonly #runtime: Set<string>;
+  readonly #typeOnly: Set<string>;
+  readonly #isKept: (dep: string) => boolean;
+
+  constructor(root: PackageJson, { runtime, typeOnly }: ScannedImports, isKept: (dep: string) => boolean) {
+    this.#root = root;
+    this.#runtime = new Set(runtime);
+    this.#typeOnly = new Set(typeOnly);
+    this.#isKept = isKept;
+  }
+
+  static keptBy(manifest: PackageJson): string[] {
+    const { keepDependencies } = (manifest[LibSource.manifestKey] ?? {}) as { keepDependencies?: unknown };
+    return Array.isArray(keepDependencies)
+      ? keepDependencies.filter((dep): dep is string => typeof dep === "string")
+      : [];
+  }
+
+  //* The scan recognises only the names the root declares, so only those can be proven unused and pruned.
+  realign(manifest: PackageJson) {
+    const removed: string[] = [];
+    const unverifiable: string[] = [];
+    const dependencies: DependencyMap = {};
+    for (const [dep, version] of Object.entries(manifest.dependencies ?? {})) {
+      if (this.#typeOnly.has(dep)) continue;
+      const rootVersion = this.#rootVersionOf(dep);
+      if (!rootVersion) {
+        unverifiable.push(dep);
+        dependencies[dep] = version;
+      } else if (this.#runtime.has(dep) || this.#isKept(dep)) dependencies[dep] = rootVersion;
+      else removed.push(dep);
+    }
+    const runtimeOfRootDependencies = [...this.#runtime].filter((dep) => this.#root.dependencies?.[dep]);
+    this.#append(dependencies, runtimeOfRootDependencies);
+
+    const devDependencies: DependencyMap = {};
+    for (const [dep, version] of Object.entries(manifest.devDependencies ?? {}))
+      if (!Object.hasOwn(dependencies, dep)) devDependencies[dep] = this.#rootVersionOf(dep) ?? version;
+    this.#append(devDependencies, [...this.#typeOnly]);
+    return { dependencies, devDependencies, removed, unverifiable };
+  }
+
+  #append(map: DependencyMap, deps: string[]) {
+    for (const dep of deps.filter((dep) => !Object.hasOwn(map, dep)).sort((a, b) => (a < b ? -1 : 1))) {
+      const rootVersion = this.#rootVersionOf(dep);
+      if (rootVersion) map[dep] = rootVersion;
+    }
+  }
+
+  #rootVersionOf(dep: string) {
+    return this.#root.dependencies?.[dep] ?? this.#root.devDependencies?.[dep];
+  }
+}

package/mobile/desktopBin.test.ts

@@ -28,7 +28,7 @@ const stage = async (
   bin: AkanBinConfig,
   { libBins = [], libs = [] }: { libBins?: { lib: string; bin: AkanBinConfig }[]; libs?: string[] } = {},
 ) => {
-  const binDir = path.join(root, "apps/portal/.akan/native/default/bin");
+  const binDir = path.join(root, "dist/native/portal/default/bin");
   const config = { app: { name: "portal" }, bin, libBins } as never;
   const carried = await new DesktopBin(fakeApp(path.join(root, "apps/portal"), libs), config).stage(binDir);
   return { carried, binDir };

package/mobile/desktopServerStage.test.ts

@@ -241,10 +241,13 @@ describe("DesktopServerStage", () => {
   });
 
   test("a phone build cannot carry the server", async () => {
-    const app = new NativeApp({ cwdPath: "/repo/apps/portal" } as never, {
-      name: "default",
-      config: { name: "default", appName: "Portal", appId: "com.portal.app", version: "1.0.0", buildNum: 1 },
-    });
+    const app = new NativeApp(
+      { name: "portal", cwdPath: "/repo/apps/portal", workspace: { workspaceRoot: "/repo" } } as never,
+      {
+        name: "default",
+        config: { name: "default", appName: "Portal", appId: "com.portal.app", version: "1.0.0", buildNum: 1 },
+      },
+    );
     const server = { dir: "/tmp/server", entry: "main.js", env: {} };
     await expect(app.build("ios", { server })).rejects.toThrow("Only a desktop app carries its server");
     await expect(app.run("android", { server })).rejects.toThrow("Only a desktop app carries its server");

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.1",
+  "version": "3.0.2",
   "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",
     "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(