@akanjs/devkit 3.1.1-rc.9 → 3.1.2-rc.0

package/akanConfig/akanConfig.ts

@@ -227,6 +227,7 @@ export class AkanAppConfig implements AppConfigResult {
     this.i18n = resolveAkanI18nConfig(config?.i18n);
     process.env.AKAN_PUBLIC_DEFAULT_LOCALE = this.i18n.defaultLocale;
     process.env.AKAN_PUBLIC_LOCALES = this.i18n.locales.join(",");
+    process.env.AKAN_PUBLIC_LOCALE_PREFIX = this.i18n.localePrefix ?? "always";
     this.api = {
       prefix: normalizeRoutePrefix(config?.api?.prefix) ?? "/api",
       websocketPrefix: normalizeRoutePrefix(config?.api?.websocketPrefix) ?? "/ws",
@@ -468,6 +469,8 @@ export class AkanAppConfig implements AppConfigResult {
       "deepLinks",
       "updates",
       "devtools",
+      "csp",
+      "openUrls",
       "ios",
       "android",
       "desktop",
@@ -623,6 +626,7 @@ export class AkanAppConfig implements AppConfigResult {
       ...(this.basePaths.size ? { AKAN_PUBLIC_BASE_PATHS: [...this.basePaths].join(",") } : {}),
       AKAN_PUBLIC_DEFAULT_LOCALE: this.i18n.defaultLocale,
       AKAN_PUBLIC_LOCALES: this.i18n.locales.join(","),
+      ...(this.i18n.localePrefix === "as-needed" ? { AKAN_PUBLIC_LOCALE_PREFIX: this.i18n.localePrefix } : {}),
       AKAN_PUBLIC_API_PREFIX: this.api.prefix,
       AKAN_PUBLIC_WS_PREFIX: this.api.websocketPrefix,
       AKAN_PUBLIC_OPERATION_MODE: "cloud",
@@ -634,6 +638,11 @@ export class AkanAppConfig implements AppConfigResult {
       ...(this.web.csr ? {} : { AKAN_CSR: "false" }),
     };
   }
+  //? An image runs where the build cannot see, and AKAN_PUBLIC_ENV=local serves the dev routes to every caller there.
+  static readonly localImageGuard = [
+    "ARG AKAN_ALLOW_LOCAL_IMAGE",
+    `RUN if [ "$AKAN_ALLOW_LOCAL_IMAGE" != "1" ]; then echo "This build ran with AKAN_PUBLIC_ENV=local, which serves the dev routes to every caller. Build with the environment it deploys to, or pass --build-arg AKAN_ALLOW_LOCAL_IMAGE=1." >&2; exit 1; fi`,
+  ].join("\n");
   dockerfileFor(environment: string, { lockfile = true }: { lockfile?: boolean } = {}): string {
     return this.#makeDockerfile(environment, lockfile);
   }
@@ -643,8 +652,9 @@ export class AkanAppConfig implements AppConfigResult {
     const preRunScripts = this.#getDockerRunScripts(preRuns);
     const postRunScripts = this.#getDockerRunScripts(postRuns);
     const imageScript = this.#getDockerImageScript(image, DEFAULT_DOCKER_IMAGE);
+    const isLocal = (environment ?? this.baseDevEnv.env) === "local";
     const envLines = Object.entries(this.getProductionEnv(environment)).map(([key, value]) => `ENV ${key}=${value}`);
-    return `${imageScript}
+    return `${imageScript}${isLocal ? `\n${AkanAppConfig.localImageGuard}` : ""}
 RUN apt-get update && apt-get upgrade -y && apt-get install -y --no-install-recommends ca-certificates tzdata && rm -rf /var/lib/apt/lists/*
 RUN ln -sf /usr/share/zoneinfo/Asia/Seoul /etc/localtime
 ARG TARGETARCH
@@ -776,7 +786,15 @@ CMD [${command.map((c) => `"${c}"`).join(",")}]`;
   static get akanVersion() {
     return getAkanPackageJson().version;
   }
+  //? The image installs from the registry alone: a pin to a path or a workspace package resolves nowhere there.
+  static #registryPins(pins: Record<string, string> | undefined) {
+    if (!pins) return undefined;
+    const kept = Object.entries(pins).filter(([, spec]) => !/^(?:file:|link:|workspace:|portal:|[./~])/.test(spec));
+    return kept.length ? Object.fromEntries(kept) : undefined;
+  }
   getProductionPackageJson(data: Partial<PackageJson> = {}): PackageJson {
+    const overrides = AkanAppConfig.#registryPins(this.rootPackageJson.overrides);
+    const resolutions = AkanAppConfig.#registryPins(this.rootPackageJson.resolutions);
     return {
       name: this.app.name,
       description: this.app.name,
@@ -789,6 +807,8 @@ CMD [${command.map((c) => `"${c}"`).join(",")}]`;
         ]),
       ),
       ...(this.trustedDependencies.length ? { trustedDependencies: this.trustedDependencies } : {}),
+      ...(overrides ? { overrides } : {}),
+      ...(resolutions ? { resolutions } : {}),
       ...data,
     };
   }

package/akanConfig/productionLockfile.test.ts

@@ -70,6 +70,37 @@ describe("ProductionLockfile", () => {
     });
   });
 
+  test("keeps a version an override pinned outside its parent's range", async () => {
+    const overriddenLock = `{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "repo",
+      "dependencies": {
+        "loose-envify": "^1.4.0",
+      },
+    },
+  },
+  "overrides": {
+    "js-tokens": "2.0.0",
+  },
+  "packages": {
+    "js-tokens": ["js-tokens@2.0.0", "", {}, "sha512-kk4RjoztHFeAlCNPdTr/uF04oN5z53L18LJfADBQ7YHkO3iR2rP2ZwOH0n33r2FRw0psRmjTDEkOWPE//zmujg=="],
+
+    "loose-envify": ["loose-envify@1.4.0", "", { "dependencies": { "js-tokens": "^3.0.0 || ^4.0.0" }, "bin": { "loose-envify": "cli.js" } }, "sha512-lyuxPGr/Wfhrlem2CL/UcnUc1zcqKAImBDzukY7Y5F/yQiNdko6+fRLevlw1HgMySw7f611UIY408EtxRSoK3Q=="],
+  }
+}
+`;
+    await withWorkspace(overriddenLock, async (root) => {
+      const lock = await ProductionLockfile.prune(root, {
+        ...productionPackageJson,
+        overrides: { "js-tokens": "2.0.0" },
+      });
+      expect(lock).toContain('"js-tokens": ["js-tokens@2.0.0"');
+    });
+  });
+
   test("refuses a workspace without a bun.lock, so the build can fall back to an unlocked install", async () => {
     await withWorkspace(null, async (root) => {
       await expect(ProductionLockfile.prune(root, productionPackageJson)).rejects.toThrow(

package/akanConfig/productionLockfile.ts

@@ -13,9 +13,11 @@ export class ProductionLockfile {
     if (!(await workspaceLock.exists())) throw new Error(`the workspace root has no ${ProductionLockfile.fileName}`);
     const dir = await mkdtemp(path.join(os.tmpdir(), "akan-production-lock-"));
     try {
+      const npmrc = Bun.file(path.join(workspaceRoot, ".npmrc"));
       await Promise.all([
         Bun.write(path.join(dir, "package.json"), JSON.stringify(packageJson, null, 2)),
         Bun.write(path.join(dir, ProductionLockfile.fileName), workspaceLock),
+        ...((await npmrc.exists()) ? [Bun.write(path.join(dir, ".npmrc"), npmrc)] : []),
       ]);
       const install = Bun.spawn([process.execPath, "install", "--lockfile-only", "--no-progress"], {
         cwd: dir,

package/akanContext.ts

@@ -1,6 +1,6 @@
 import { readdir } from "node:fs/promises";
 import path from "node:path";
-import { capitalize, isRecord } from "akanjs/common";
+import { capitalize, isRecord, parseRouteModuleKey } from "akanjs/common";
 import { extractBlockVersion, readDevkitVersion } from "./agentsIndex";
 import { AppExecutor, LibExecutor, type SysExecutor, type WorkspaceExecutor } from "./executors";
 import { FileSys } from "./fileSys";
@@ -48,12 +48,25 @@ export interface AkanModuleContext {
   files: string[];
 }
 
+export interface AkanRouteContext {
+  /** The URL pattern without the `/:lang` segment every route starts with. */
+  path: string;
+  file: string;
+  search: string[];
+  /** The page or a layout above it calls `.guard()`. */
+  guarded: boolean;
+  devOnly: boolean;
+}
+
 export interface AkanSysContext {
   type: "app" | "lib";
   name: string;
   path: string;
   hasConfig: boolean;
   modules: AkanModuleContext[];
+  /** Listed for the app `--app` names only; reading them parses every route file. */
+  routes?: AkanRouteContext[];
+  routeError?: string;
 }
 
 export interface AkanPackageContext {
@@ -280,6 +293,7 @@ const generatedFiles = [
 ];
 
 const validationCommands = [
+  "akan verify [<app-or-lib-or-pkg>]",
   "akan sync <app-or-lib>",
   "akan lint <app-or-lib-or-pkg>",
   "akan typecheck <app-or-lib>",
@@ -294,7 +308,7 @@ const unknownGeneratedFilesFreshness: GeneratedFilesFreshness = {
   status: "unknown" as const,
   message: "Run sync before validation so generated Akan files match the current source conventions.",
   refreshCommand: "akan sync <app-or-lib>",
-  verifyingCommands: ["akan lint <app-or-lib-or-pkg>", "akan build <app-name>"],
+  verifyingCommands: ["akan verify <app-or-lib>"],
 };
 
 const repairAction = (
@@ -454,7 +468,7 @@ const generatedFreshnessFromStates = async (workspace: WorkspaceExecutor): Promi
       ? `Generated files were refreshed for ${lastFresh.target} at ${lastFresh.lastSyncedAt}.`
       : "Generated sync state exists, but the last recorded repair did not pass.",
     refreshCommand: "akan sync <app-or-lib>",
-    verifyingCommands: ["akan lint <app-or-lib-or-pkg>", "akan build <app-name>"],
+    verifyingCommands: ["akan verify <app-or-lib>"],
     targets,
   };
 };
@@ -556,6 +570,34 @@ const getSysModules = async (
   return modules.sort((a, b) => `${a.sysName}:${a.path}`.localeCompare(`${b.sysName}:${b.path}`));
 };
 
+const getAppRoutes = async (app: AppExecutor, workspaceRoot: string): Promise<AkanRouteContext[]> => {
+  const sources = await app.getRouteSources();
+  const guardedLayouts = new Set<string>();
+  const pages: { source: (typeof sources)[number]; parsed: ReturnType<typeof parseRouteModuleKey> }[] = [];
+  for (const source of sources) {
+    const parsed = parseRouteModuleKey(source.key);
+    if (parsed.kind === "layout" && source.info.chain?.guarded) guardedLayouts.add(parsed.routeSegments.join("/"));
+    else if (parsed.kind === "page") pages.push({ source, parsed });
+  }
+  return pages
+    .map(({ source, parsed }) => {
+      const segments = parsed.routeSegments;
+      //? The layouts that wrap a page, as the route seed index walks them: an `_index` sits inside its own folder.
+      const reach = parsed.leaf === "_index" ? segments.length : segments.length - 1;
+      const underGuard = Array.from({ length: reach + 1 }, (_, idx) => segments.slice(0, idx).join("/")).some(
+        (prefix) => guardedLayouts.has(prefix),
+      );
+      return {
+        path: parsed.pattern.replace(/^\/:lang/, "") || "/",
+        file: path.relative(workspaceRoot, source.absPath).replaceAll(path.sep, "/"),
+        search: source.info.chain?.search ?? [],
+        guarded: !!source.info.chain?.guarded || underGuard,
+        devOnly: source.info.devOnly,
+      };
+    })
+    .sort((a, b) => a.path.localeCompare(b.path));
+};
+
 const getSysContext = async (
   workspace: WorkspaceExecutor,
   type: "app" | "lib",
@@ -563,7 +605,7 @@ const getSysContext = async (
   options: AkanContextOptions,
 ): Promise<AkanSysContext> => {
   const sys = type === "app" ? AppExecutor.from(workspace, name) : LibExecutor.from(workspace, name);
-  return {
+  const context: AkanSysContext = {
     type,
     name,
     path: `${type}s/${name}`,
@@ -573,6 +615,12 @@ const getSysContext = async (
       module: options.module,
     }),
   };
+  if (sys instanceof AppExecutor && options.app === name)
+    await getAppRoutes(sys, workspace.workspaceRoot).then(
+      (routes) => (context.routes = routes),
+      (error: unknown) => (context.routeError = error instanceof Error ? error.message : String(error)),
+    );
+  return context;
 };
 
 export class AkanContextAnalyzer {
@@ -632,6 +680,42 @@ export class AkanContextAnalyzer {
     };
   }
 
+  //? Codex joins every AGENTS.md from the repo root down to its folder and drops what passes 32 KiB (`project_doc_max_bytes`).
+  static async #agentGuideOversize(workspace: WorkspaceExecutor, sysPaths: string[]) {
+    const sizeOf = async (file: string) => {
+      const content = await safeReadText(path.join(workspace.workspaceRoot, file));
+      return { file, bytes: content === null ? 0 : Buffer.byteLength(content) };
+    };
+    const root = await sizeOf("AGENTS.md");
+    if (root.bytes === 0) return null;
+    const scoped = await Promise.all(sysPaths.map((sysPath) => sizeOf(`${sysPath}/AGENTS.md`)));
+    const largest = scoped.reduce((max, entry) => (entry.bytes > max.bytes ? entry : max), { file: "", bytes: 0 });
+    const total = root.bytes + largest.bytes;
+    if (total <= 32 * 1024 * 0.8) return null;
+    const subject = largest.bytes ? `AGENTS.md and ${largest.file} add up to` : "AGENTS.md is";
+    return `${subject} ${Math.ceil(total / 1024)} KiB of the 32 KiB Codex reads — run \`akan agent install\`, then shorten the text outside the akan:agent markers or move it into a skill.`;
+  }
+
+  static async #agentGuideLeftovers(workspace: WorkspaceExecutor) {
+    const root = workspace.workspaceRoot;
+    const guide = (await safeReadText(path.join(root, "AGENTS.md"))) ?? "";
+    const leftovers: { path: string; message: string }[] = [];
+    for (const doc of ["docs/AI-DEVELOPMENT.md", "docs/GENERATED.md"]) {
+      const pointer = guide.includes(doc);
+      if ((await safeReadText(path.join(root, doc))) !== null)
+        leftovers.push({
+          path: doc,
+          message: `${doc} is an older template's copy of the agent guide, and nothing reads it now — delete it${pointer ? " and the AGENTS.md sentence that points to it" : ""}.`,
+        });
+      else if (pointer)
+        leftovers.push({
+          path: "AGENTS.md",
+          message: `AGENTS.md points to ${doc}, which is gone — delete that sentence.`,
+        });
+    }
+    return leftovers;
+  }
+
   //? Older templates wrote these for Next.js: nothing installs or reads them, and editors warn about the plugin.
   static async #configLeftovers(workspace: WorkspaceExecutor, sysPaths: string[]) {
     const leftovers: { path: string; message: string }[] = [];
@@ -724,6 +808,11 @@ export class AkanContextAnalyzer {
         repairAction("generated", "akan agent install agents-md", agentDrift.hint, true),
       );
     const sysPaths = [...context.apps, ...context.libs].map((sys) => sys.path);
+    const oversize = await AkanContextAnalyzer.#agentGuideOversize(workspace, sysPaths);
+    if (oversize)
+      diagnostics.push({ severity: "warning", code: "agent-guide-oversized", path: "AGENTS.md", message: oversize });
+    for (const leftover of await AkanContextAnalyzer.#agentGuideLeftovers(workspace))
+      diagnostics.push({ severity: "warning", code: "agent-guide-leftover", ...leftover });
     for (const leftover of await AkanContextAnalyzer.#configLeftovers(workspace, sysPaths))
       diagnostics.push({ severity: "warning", code: "config-leftover", ...leftover });
 
@@ -944,6 +1033,12 @@ export class AkanContextAnalyzer {
       ...context.pkgs.map((pkg) => `- ${pkg.name}${pkg.version ? ` (${pkg.version})` : ""}`),
     );
 
+    for (const app of context.apps) {
+      if (app.routeError) lines.push("", `## Routes: ${app.name}`, `- Not read: ${app.routeError}`);
+      else if (app.routes)
+        lines.push("", `## Routes: ${app.name}`, ...AkanContextAnalyzer.#routeLines(app.name, app.routes));
+    }
+
     const modules = AkanContextAnalyzer.findModules(context, moduleName);
     lines.push("", "## Modules");
     for (const module of modules) {
@@ -958,4 +1053,34 @@ export class AkanContextAnalyzer {
     lines.push("", "## Validation", ...context.validationCommands.map((command) => `- \`${command}\``));
     return `${lines.join("\n")}\n`;
   }
+
+  static readonly routeListLimit = 60;
+
+  //? Past the limit the biggest top folders fold into one line each: a docs section alone would fill the context.
+  static #routeLines(appName: string, routes: AkanRouteContext[]) {
+    const folderOf = (route: AkanRouteContext) => route.file.split("/").slice(0, 4).join("/");
+    const groups = Map.groupBy(routes, folderOf);
+    const folded = new Set<string>();
+    let listed = routes.length;
+    for (const [folder, members] of [...groups].sort((a, b) => b[1].length - a[1].length)) {
+      if (listed <= AkanContextAnalyzer.routeListLimit) break;
+      folded.add(folder);
+      listed -= members.length;
+    }
+    const lines = [`Paths omit the \`/:lang\` prefix; \`akan preview ${appName} <path>\` opens one.`];
+    for (const route of routes) {
+      if (folded.has(folderOf(route))) continue;
+      const search = route.search.length ? ` ?${route.search.join("&")}` : "";
+      const marks = `${route.guarded ? " (guarded)" : ""}${route.devOnly ? " (dev only)" : ""}`;
+      lines.push(`- ${route.path}${search}${marks} — ${route.file}`);
+    }
+    for (const folder of folded) {
+      const members = groups.get(folder) ?? [];
+      const examples = members.slice(0, 3).map((route) => route.path);
+      lines.push(
+        `- ${folder}/: ${members.length} routes folded (${examples.join(", ")}, …); \`--format json\` lists every route`,
+      );
+    }
+    return lines;
+  }
 }

package/akanMcpContract.test.ts

@@ -1,5 +1,10 @@
 import { describe, expect, test } from "bun:test";
-import { createAkanValidationContract } from "./akanMcpContract";
+import { mkdir, symlink } from "node:fs/promises";
+import path from "node:path";
+import { createAkanValidationContract, workflowArtifactPath } from "./akanMcpContract";
+import { createTempApp, tempRoots } from "./testHelpers";
+
+const track = tempRoots();
 
 describe("createAkanValidationContract", () => {
   test("exposes reference-first tooling rollout gate semantics", () => {
@@ -35,3 +40,25 @@ describe("createAkanValidationContract", () => {
     );
   });
 });
+
+describe("workflowArtifactPath", () => {
+  test("keeps the plans and reports an MCP call names inside the workspace's workflow folder", async () => {
+    const { root, workspace } = track(await createTempApp("demo"));
+    const workflows = path.join(root, ".akan/workflows");
+    await mkdir(path.join(workflows, "plans"), { recursive: true });
+    await symlink(path.join(root, "package.json"), path.join(workflows, "plans/linked.json"));
+
+    expect(workflowArtifactPath(workspace, ".akan/workflows/plans/a.json")).toBe(path.join(workflows, "plans/a.json"));
+    expect(workflowArtifactPath(workspace, `${workflows}/runs/b.json`)).toBe(path.join(workflows, "runs/b.json"));
+    expect(workflowArtifactPath(workspace, "add-field-123")).toBe(path.join(workflows, "runs/add-field-123.json"));
+    for (const outside of [
+      "package.json",
+      `${root}/package.json`,
+      ".akan/workflows/../../package.json",
+      ".akan/workflows",
+      ".akan/workflows/plans/linked.json",
+      "/tmp/plan.json",
+    ])
+      expect(() => workflowArtifactPath(workspace, outside)).toThrow("MCP workflow files live under .akan/workflows/");
+  });
+});

package/akanMcpContract.ts

@@ -1,3 +1,4 @@
+import { lstatSync, realpathSync } from "node:fs";
 import path from "node:path";
 import { isRecord } from "akanjs/common";
 import { AkanContextAnalyzer, type AkanDiagnostic, type AkanModuleContext } from "./akanContext";
@@ -127,8 +128,55 @@ const isInspectAkanContextRequestType = (value: unknown): value is InspectAkanCo
 
 export const parseJsonOutput = (output: string) => JSON.parse(output) as unknown;
 
-export const workspacePath = (workspace: Workspace, filePath: string) =>
-  path.isAbsolute(filePath) ? filePath : path.join(workspace.workspaceRoot, filePath);
+const workflowArtifactDir = ".akan/workflows";
+const workflowRunIdPattern = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+const isInside = (base: string, target: string) => {
+  const relative = path.relative(base, target);
+  return !!relative && !relative.startsWith("..") && !path.isAbsolute(relative);
+};
+
+const hasEntry = (filePath: string) => {
+  try {
+    lstatSync(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const realPathOfNearest = (filePath: string) => {
+  const rest: string[] = [];
+  let current = filePath;
+  while (!hasEntry(current) && path.dirname(current) !== current) {
+    rest.unshift(path.basename(current));
+    current = path.dirname(current);
+  }
+  return path.join(realpathSync(current), ...rest);
+};
+
+const staysInside = (workspaceRoot: string, root: string, resolved: string) => {
+  try {
+    const realRoot = realPathOfNearest(root);
+    return isInside(realPathOfNearest(workspaceRoot), realRoot) && isInside(realRoot, realPathOfNearest(resolved));
+  } catch {
+    return false;
+  }
+};
+
+//? An MCP caller acts on text it was shown, so the plans and reports it names stay in the workspace's workflow folder.
+export const workflowArtifactPath = (workspace: Workspace, filePath: string) => {
+  const root = path.resolve(workspace.workspaceRoot, workflowArtifactDir);
+  const resolved =
+    workflowRunIdPattern.test(filePath) && !filePath.endsWith(".json")
+      ? path.join(root, "runs", `${filePath}.json`)
+      : path.resolve(workspace.workspaceRoot, filePath);
+  if (!isInside(root, resolved) || !staysInside(workspace.workspaceRoot, root, resolved))
+    throw new Error(
+      `MCP workflow files live under ${workflowArtifactDir}/ of the workspace, not ${JSON.stringify(filePath)}.`,
+    );
+  return resolved;
+};
 
 export const defaultWorkflowPlanPath = (workflow: string, inputs: WorkflowPlanInputs) => {
   const slug = [
@@ -490,7 +538,7 @@ export const inspectAkanContext = async (
   if (props.request.type === "workflowDiagnostics") {
     const doctor = await AkanContextAnalyzer.doctor(workspace, {
       strict: true,
-      runIdOrPlan: workspacePath(workspace, props.request.runIdOrPlan),
+      runIdOrPlan: workflowArtifactPath(workspace, props.request.runIdOrPlan),
     });
     const toWorkflowDiagnostic = (
       { severity, code, message, scope }: AkanDiagnostic,

package/applicationBuildRunner.test.ts

@@ -9,6 +9,7 @@ import type { App } from "./commandDecorators";
 import { AppExecutor, Executor } from "./executors";
 import { bundleDefine } from "./frontendBuild/bundleDefine";
 import { createTempApp } from "./testHelpers";
+import { ProjectTypecheck } from "./typecheck/projectTypecheck";
 
 describe("ApplicationBuildRunner", () => {
   test("externalizes Akan optional backend dependencies", () => {
@@ -83,6 +84,42 @@ console.info(new SampleService().name);
     }
   });
 
+  test("writes beside main.js the env its Dockerfile sets, so a host without the image runs the build as is", async () => {
+    const root = await mkdtemp(path.join(os.tmpdir(), "akan-build-meta-"));
+    const config = new AkanAppConfig(
+      { name: "portal" } as never,
+      [],
+      { name: "repo", version: "1.0.0", description: "repo" },
+      {},
+      { repoName: "akanjs", serveDomain: "akanjs.com", env: "local", portOffset: 0, workspaceRoot: root },
+    );
+    const app = {
+      getConfig: async () => config,
+      dist: new Executor("dist", root),
+      workspace: { workspaceRoot: root },
+      logger: { warn: () => undefined },
+    } as unknown as App;
+    const builtEnv = async () => JSON.parse(await readFile(path.join(root, "akan.env.json"), "utf8")) as object;
+    const dockerfileEnv = async () =>
+      Object.fromEntries(
+        (await readFile(path.join(root, "Dockerfile"), "utf8"))
+          .split("\n")
+          .filter((line) => line.startsWith("ENV "))
+          .map((line) => line.slice("ENV ".length).split(/=(.*)/s).slice(0, 2)),
+      );
+    try {
+      await new ApplicationBuildRunner(app, { environment: "debug" }).buildAppMeta();
+      expect(await builtEnv()).toEqual(config.getProductionEnv("debug"));
+      expect(await builtEnv()).toEqual(await dockerfileEnv());
+      expect(await builtEnv()).toMatchObject({ AKAN_PUBLIC_APP_NAME: "portal", AKAN_PUBLIC_ENV: "debug" });
+      await new ApplicationBuildRunner(app).buildAppMeta();
+      expect(await builtEnv()).toMatchObject({ AKAN_PUBLIC_ENV: "local" });
+      expect(await builtEnv()).toEqual(await dockerfileEnv());
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
   test("writes the pruned lockfile beside package.json, or warns and leaves the image's install unlocked", async () => {
     const root = await mkdtemp(path.join(os.tmpdir(), "akan-build-meta-"));
     const config = new AkanAppConfig(
@@ -249,4 +286,20 @@ console.info(new SampleService().name);
       await rm(root, { recursive: true, force: true });
     }
   });
+
+  test("akan typecheck names the script/ files nothing imports, and a build's typecheck leaves them out", async () => {
+    const { root, app } = await createTempApp("portal");
+    const run = spyOn(ProjectTypecheck.prototype, "run").mockImplementation(async () => "");
+    try {
+      const runner = new ApplicationBuildRunner(app);
+      await runner.typecheck({ tests: true });
+      await runner.typecheck();
+      const [checked, built] = run.mock.calls.map(([entries]) => entries);
+      expect(checked).toContain("../../script/**/*.ts");
+      expect(built).not.toContain("../../script/**/*.ts");
+    } finally {
+      run.mockRestore();
+      await rm(root, { recursive: true, force: true });
+    }
+  });
 });

package/applicationBuildRunner.ts

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { toError } from "akanjs/common";
+import { BUILD_ENV_FILE } from "akanjs/server/lifecycle/buildEnv";
 import type { BunPlugin } from "bun";
 import { ProductionLockfile } from "./akanConfig/productionLockfile";
 import type {
@@ -25,8 +26,9 @@ import type { BaseDevEnv, PackageJson } from "./types";
 export interface TypecheckOptions {
   clean?: boolean;
   incremental?: boolean;
-  /** The app's own tests and specs too (`akan typecheck`); a build leaves them out. */
+  /** The app's own tests, specs and `script/` files too (`akan typecheck`); a build leaves them out. */
   tests?: boolean;
+  report?: "pretty" | "records";
 }
 
 export type BuildPhaseId = "prepare" | "typecheck" | "backend" | "ssr" | "csr" | "assets" | "compress" | "metadata";
@@ -205,6 +207,7 @@ export class ApplicationBuildRunner {
         "../../page/**/*.ts",
         "../../page/**/*.tsx",
         ...libPageIncludes,
+        ...(options.tests ? ["../../script/**/*.ts"] : []),
         "../../../../pkgs/akanjs/*/types/**/*.d.ts",
       ],
       options,
@@ -238,13 +241,13 @@ export class ApplicationBuildRunner {
 
   async buildAppMeta() {
     const akanConfig = await this.#app.getConfig();
+    const environment = this.#environment ?? akanConfig.baseDevEnv.env;
     const packageJson = akanConfig.getProductionPackageJson();
     const lockfile = await this.#pruneLockfile(packageJson);
-    const dockerfile = akanConfig.dockerfileFor(this.#environment ?? akanConfig.baseDevEnv.env, {
-      lockfile: lockfile !== null,
-    });
+    const dockerfile = akanConfig.dockerfileFor(environment, { lockfile: lockfile !== null });
     await Promise.all([
       this.#app.dist.writeJson("package.json", packageJson),
+      this.#app.dist.writeJson(BUILD_ENV_FILE, akanConfig.getProductionEnv(environment)),
       ...(lockfile !== null
         ? [this.#app.dist.writeFile(`${this.#app.dist.cwdPath}/${ProductionLockfile.fileName}`, lockfile)]
         : []),

package/artifact/implicitRootLayout.ts

@@ -33,7 +33,7 @@ async function writeGeneratedOverridesLayoutFile(opts: {
   const filename = `${opts.key.replace(/^\.\//, "").replace(/[^a-zA-Z0-9]+/g, "_")}.tsx`;
   const absPath = path.join(path.resolve(opts.appCwdPath), IMPLICIT_OVERRIDES_DIR, filename);
   const source = `"use client";
-import { UiOverrideProvider } from "akanjs/ui";
+import { UiOverrideProvider } from "akanjs/ui/UiOverride/UiOverride.tsx";
 import { createElement, type ReactNode } from "react";
 import value from ${JSON.stringify(importSpecifier(absPath, opts.userAbsPath))};
 
@@ -213,11 +213,13 @@ ${guardExport}
 
 ${layoutSignature}({ children, params, searchParams }: LayoutProps) {
 ${layoutBinding}  return `;
+  //? System from its file, not the barrel: a dev registry compiles every module the barrel names, and with them the
+  //? optional peers (react-icons) an app drawing none of those components never installs.
   const source = opts.includeSystemProvider
     ? `import type { LayoutModule, LayoutProps, PageProps } from "akanjs/client";
 import { assertGuardOnChain, loadFonts, RouteGuards, resolveRouteModule, RouteHead } from "akanjs/client";
 import type { ReactNode } from "react";
-import { System } from "akanjs/ui";
+import { System } from "akanjs/ui/System/index.tsx";
 import type { McpAppRootProps } from "akanjs/webkit";
 import { env } from "@apps/${opts.appName}/env/env.client";
 import { allDictionary } from ${JSON.stringify(dictMacroSpecifier)};

package/biome.base.json

@@ -211,7 +211,10 @@
         "!**/*.spec.ts",
         "!**/*.spec.tsx"
       ],
-      "plugins": ["./node_modules/@akanjs/devkit/lint/no-init-fetch-in-client.grit"]
+      "plugins": [
+        "./node_modules/@akanjs/devkit/lint/no-init-fetch-in-client.grit",
+        "./node_modules/@akanjs/devkit/lint/no-oversized-list-limit.grit"
+      ]
     },
     {
       "includes": [

package/cloud/globalConfig.test.ts

@@ -1,6 +1,24 @@
 import { describe, expect, test } from "bun:test";
+import { mkdir, stat } from "node:fs/promises";
+import path from "node:path";
+import { tempDirs } from "../testHelpers";
 import { GlobalConfig } from "./globalConfig";
 
+const tempHome = tempDirs("akan-global-config-");
+//* A child process, so `~/.akan` resolves under the temp HOME and never the person's own.
+const writeConfigUnder = async (home: string) => {
+  const proc = Bun.spawn(
+    [
+      "bun",
+      "-e",
+      `await (await import(${JSON.stringify(path.join(import.meta.dir, "globalConfig.ts"))})).GlobalConfig.setTestTargets({});`,
+    ],
+    { env: { ...process.env, HOME: home, USERPROFILE: home }, stdout: "pipe", stderr: "pipe" },
+  );
+  expect(await proc.exited).toBe(0);
+};
+const modeOf = async (target: string) => (await stat(target)).mode & 0o777;
+
 const workspace = (cloudHost: string | null) => ({ getConfig: async () => ({ cloudHost }) });
 
 describe("GlobalConfig", () => {
@@ -14,4 +32,20 @@ describe("GlobalConfig", () => {
     expect(await GlobalConfig.hostFor(workspace(null), "http://localhost:8283/")).toBe("http://localhost:8283");
     expect(await GlobalConfig.hostFor(workspace(null))).toBe(GlobalConfig.akanCloudHost);
   });
+
+  test.skipIf(process.platform === "win32")(
+    "keeps ~/.akan to its owner: a new one is made 0700 and a looser one it owns is tightened",
+    async () => {
+      const fresh = await tempHome();
+      await writeConfigUnder(fresh);
+      expect(await modeOf(path.join(fresh, ".akan"))).toBe(0o700);
+      expect(await modeOf(path.join(fresh, ".akan", "config.json"))).toBe(0o600);
+
+      const loose = await tempHome();
+      await mkdir(path.join(loose, ".akan"), { mode: 0o755 });
+      await writeConfigUnder(loose);
+      expect(await modeOf(path.join(loose, ".akan"))).toBe(0o700);
+    },
+    20_000,
+  );
 });

package/cloud/globalConfig.ts

@@ -1,4 +1,4 @@
-import { mkdir, rm, writeFile } from "node:fs/promises";
+import { rm, writeFile } from "node:fs/promises";
 import { trimTrailingSlashes } from "akanjs/common";
 import dayjs from "dayjs";
 import { FileSys } from "../fileSys";
@@ -36,7 +36,7 @@ export class GlobalConfig {
   // Holds the cloud jwt and refresh token, so owner-only 0600: written to a 0600 sibling and renamed over the file,
   // which also replaces a world-readable one and never shows another CLI process a half-written file.
   static async #setAkanGlobalConfig(akanConfig: AkanGlobalConfig) {
-    await mkdir(basePath, { recursive: true, mode: 0o700 });
+    FileSys.ensurePrivateDir(basePath);
     const temp = `${configPath}.${process.pid}.${crypto.randomUUID()}.tmp`;
     try {
       await writeFile(temp, JSON.stringify(akanConfig, null, 2), { mode: 0o600 });