@akanjs/devkit 3.1.0-rc.3 → 3.1.0-rc.5

package/abstractDoc.ts

@@ -26,7 +26,7 @@ export class AbstractDoc {
   static async findAll(sys: SysExecutor, { module }: { module?: string | null } = {}) {
     const filePaths = (await sys.getAllFiles(`${AbstractDoc.#facetRoots}/**/*${AbstractDoc.suffix}`))
       .map((filePath) => filePath.split(path.sep).join("/"))
-      .sort();
+      .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
     const docs = await Promise.all(filePaths.map((filePath) => AbstractDoc.read(sys, filePath)));
     if (!module) return docs;
     return docs.filter((doc) => doc.moduleName === module || doc.folderName === module);

package/agentsIndex.test.ts

@@ -86,6 +86,9 @@ describe("collectScopeRecipeSources", () => {
     await write("libs/shared/ui/Recipe/panel.ts", `export const panelRecipe = recipe(tv({ base: "y" }));`);
     await write("pkgs/akanjs/ui/recipe/buttonRecipe.ts", `export const buttonRecipe = recipe(tv({ base: "z" }));`);
     const sources = await collectScopeRecipeSources(root, { type: "app", name: "minimal" }, ["shared"]);
-    expect(sources.map((source) => source.importFrom).sort()).toEqual(["@apps/minimal/ui", "@libs/shared/ui"]);
+    expect(sources.map((source) => source.importFrom).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))).toEqual([
+      "@apps/minimal/ui",
+      "@libs/shared/ui",
+    ]);
   });
 });

package/akanConfig/akanConfig.ts

@@ -4,7 +4,7 @@ import { fileURLToPath } from "node:url";
 import type { ServerPolicy } from "@akanjs/native/api";
 import type { AkanPlugin } from "akanjs";
 import { DatabaseModes, normalizeRoutePrefix } from "akanjs/base";
-import { type AkanI18nConfig, resolveAkanI18nConfig } from "akanjs/common";
+import { type AkanI18nConfig, resolveAkanI18nConfig, trimSlashes } from "akanjs/common";
 import type { AkanImageConfig } from "akanjs/server";
 import type { App, Lib } from "../commandDecorators";
 import { LibExecutor, WorkspaceExecutor } from "../executors";
@@ -567,7 +567,7 @@ export class AkanAppConfig implements AppConfigResult {
   }
   #applyRoutes(routes: AkanRouteConfig[] = []) {
     for (const route of routes) {
-      const basePath = route.basePath ? route.basePath.replace(/^\/+|\/+$/g, "") : null;
+      const basePath = route.basePath ? trimSlashes(route.basePath) : null;
       if (basePath !== null) this.basePaths.add(basePath);
       const domains = basePath !== null ? this.subRoutes.getOrInsert(basePath, new Set()) : this.domains;
       for (const branch of Object.keys(route.domains)) this.branches.add(branch);

package/akanContext.ts

@@ -209,7 +209,7 @@ export const upsertCodexMcpServerBlock = (
   const match = existing.match(codexAkanTablePattern);
   if (!match) {
     if (!existing.trim()) return nextBlock;
-    return `${existing.replace(/\s*$/, "")}\n\n${nextBlock}`;
+    return `${existing.trimEnd()}\n\n${nextBlock}`;
   }
   if (match[0].trim() === nextBlock.trim()) return existing;
   if (!force)
@@ -847,8 +847,8 @@ export class AkanContextAnalyzer {
       const listed = listedByImport(sectionOf(agentsMd, "## Recipes")).get("akanjs/ui") ?? new Set<string>();
       pushIndexDiagnostic(
         "AGENTS.md",
-        [...frameworkDeclared].filter((name) => !listed.has(name)).sort(),
-        [...listed].filter((name) => !frameworkDeclared.has(name)).sort(),
+        [...frameworkDeclared].filter((name) => !listed.has(name)).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)),
+        [...listed].filter((name) => !frameworkDeclared.has(name)).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)),
         "akan agent install agents-md",
       );
     }
@@ -859,7 +859,7 @@ export class AkanContextAnalyzer {
         .catch(() => "");
       const groups = listedByImport(sectionOf(scopeMd, "## Recipes In Scope"));
       const ownListed = groups.get(`@${sys.path}/ui`) ?? new Set<string>();
-      const missing = [...own].filter((name) => !ownListed.has(name)).sort();
+      const missing = [...own].filter((name) => !ownListed.has(name)).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
       // Every listed name — the scope's own and its dependency libs' — must still exist at its owner.
       const stale = [...groups.entries()]
         .flatMap(([importFrom, names]) =>

package/akanMcpContract.ts

@@ -113,7 +113,7 @@ const slugPart = (value: unknown) =>
     ? value
         .trim()
         .replace(/[^a-zA-Z0-9]+/g, "-")
-        .replace(/^-+|-+$/g, "")
+        .replace(/^-|-$/g, "")
         .toLowerCase()
     : "";
 

package/applicationBuildRunner.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { AkanAppConfig } from "./akanConfig";
@@ -110,4 +110,27 @@ console.info(new SampleService().name);
       await rm(root, { recursive: true, force: true });
     }
   });
+
+  test("a build for a real environment stops before any phase when the serve domain is only the local default", async () => {
+    const { root, workspace } = await createTempApp("portal");
+    await writeFile(path.join(root, ".env"), "AKAN_PUBLIC_REPO_NAME=repo\n");
+    const shellDomain = process.env.AKAN_PUBLIC_SERVE_DOMAIN;
+    delete process.env.AKAN_PUBLIC_SERVE_DOMAIN;
+    const app = AppExecutor.from(workspace, "portal");
+    let prepared = false;
+    app.prepareCommand = async () => {
+      prepared = true;
+      throw new Error("prepared");
+    };
+    try {
+      await expect(new ApplicationBuildRunner(app, { environment: "main" }).build()).rejects.toThrow(
+        'akan build for the "main" environment needs AKAN_PUBLIC_SERVE_DOMAIN (would be "localhost") set',
+      );
+      expect(prepared).toBe(false);
+      await expect(new ApplicationBuildRunner(app, { environment: "local" }).build()).rejects.toThrow("prepared");
+    } finally {
+      if (shellDomain !== undefined) process.env.AKAN_PUBLIC_SERVE_DOMAIN = shellDomain;
+      await rm(root, { recursive: true, force: true });
+    }
+  });
 });

package/applicationBuildRunner.ts

@@ -6,6 +6,7 @@ import type {
   ApplicationBuildResult,
 } from "./applicationBuildReporter";
 import type { App } from "./commandDecorators";
+import { WorkspaceExecutor } from "./executors";
 import {
   AllRoutesBuilder,
   CsrArtifactBuilder,
@@ -101,6 +102,7 @@ export class ApplicationBuildRunner {
     this.#spinner = spinner;
     const { web, assets, baseDevEnv } = await this.#app.getConfig();
     const environment = this.#environment ?? baseDevEnv.env;
+    WorkspaceExecutor.assertDeployableEnv(baseDevEnv, environment, "akan build");
     //? Bundles bake AKAN_PUBLIC_ENV from process.env, where the shell outranks the .env that picked the server env.
     process.env.AKAN_PUBLIC_ENV = environment;
     //? Before any phase: a profile that would ship a secret stops the build, not the image after it.
@@ -362,9 +364,17 @@ void run().catch((error) => {
     return { base, allRoutes };
   }
 
+  //? Opt-in and outside `dist/`: a metafile is the size of the module graph, and `dist/` is what the image copies.
   async #buildOrThrow(label: string, config: Bun.BuildConfig): Promise<Bun.BuildOutput> {
-    const result = await Bun.build(config);
+    const metafileDir = process.env.AKAN_BUILD_METAFILE
+      ? path.join(this.#app.workspace.workspaceRoot, "local", "build-meta", path.basename(this.#app.cwdPath))
+      : null;
+    const result = await Bun.build(metafileDir ? { ...config, metafile: true } : config);
     if (!result.success) throw new AggregateError(result.logs, `[${label}] Bun.build failed`);
+    if (metafileDir && result.metafile) {
+      const entry = path.parse(String(config.entrypoints[0] ?? label)).name;
+      await Bun.write(path.join(metafileDir, `${entry}.json`), JSON.stringify(result.metafile));
+    }
     return result;
   }
 

package/artifact/implicitRootLayout.test.ts

@@ -46,6 +46,8 @@ describe("resolveSsrPageEntries", () => {
     expect(generatedSource).toContain("export const NotFound = userLayout.NotFound ?? inheritedLayout.NotFound;");
     expect(generatedSource).toContain("export const Error = userLayout.Error ?? inheritedLayout.Error;");
     expect(generatedSource).toContain("export const pageConfig = userLayout.pageConfig ?? inheritedLayout.pageConfig;");
+    // The ancestor root is its own level of the stack, so inheriting its loading would nest it inside itself.
+    expect(generatedSource).toContain("export const Loading = userLayout.Loading;");
     expect(generatedSource).toContain(
       "<UserLayout params={params} searchParams={searchParams}>{children}</UserLayout>",
     );

package/artifact/implicitRootLayout.ts

@@ -201,6 +201,7 @@ async function writeGeneratedRootLayoutFile(opts: {
 export const NotFound = userLayout.NotFound ?? inheritedLayout.NotFound;
 export const Error = userLayout.Error ?? inheritedLayout.Error;
 export const pageConfig = userLayout.pageConfig ?? inheritedLayout.pageConfig;
+export const Loading = userLayout.Loading;
 
 ${layoutSignature}({ children, params, searchParams }: LayoutProps) {
 ${layoutBinding}  return `;

package/biome.base.json

@@ -85,16 +85,6 @@
   "overrides": [
     {
       "includes": [
-        "**/env.client.local.ts",
-        "**/env.client.debug.ts",
-        "**/env.client.develop.ts",
-        "**/env.client.main.ts",
-        "**/env.client.testing.ts",
-        "**/env.server.local.ts",
-        "**/env.server.develop.ts",
-        "**/env.server.main.ts",
-        "**/env.server.testing.ts",
-        "**/env.server.type.ts",
         "apps/*/lib/cnst.ts",
         "apps/*/lib/dict.ts",
         "apps/*/lib/db.ts",

package/cloud/configLock.ts

@@ -36,7 +36,8 @@ export class ConfigLock {
 
   static async #take(lockPath: string) {
     const handle = await open(lockPath, "wx", 0o600).catch((error: NodeJS.ErrnoException) => {
-      if (error.code === "EEXIST") return null;
+      // Windows answers EPERM, not EEXIST, while a released lock file is still pending delete behind an open handle.
+      if (error.code === "EEXIST" || (process.platform === "win32" && error.code === "EPERM")) return null;
       throw error;
     });
     if (!handle) return false;

package/cloud/globalConfig.ts

@@ -1,4 +1,5 @@
 import { mkdir, rm, writeFile } from "node:fs/promises";
+import { trimTrailingSlashes } from "akanjs/common";
 import dayjs from "dayjs";
 import { FileSys } from "../fileSys";
 import { ConfigLock } from "./configLock";
@@ -60,8 +61,8 @@ export class GlobalConfig {
   static #normalizeHost(host: string) {
     const url = URL.canParse(host) ? new URL(host) : null;
     return url && (url.protocol === "https:" || url.protocol === "http:")
-      ? `${url.origin}${url.pathname.replace(/\/+$/, "")}`
-      : host.replace(/\/+$/, "");
+      ? `${url.origin}${trimTrailingSlashes(url.pathname)}`
+      : trimTrailingSlashes(host);
   }
   static async getHostConfig(host = GlobalConfig.akanCloudHost): Promise<HostConfig> {
     const akanConfig = await GlobalConfig.#getAkanGlobalConfig();

package/codeAgent/agent/CodeAgentProxy.ts

@@ -1,6 +1,6 @@
 import { readFile } from "node:fs/promises";
 import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
-import type { CodeAgentProfile } from "akanjs/common";
+import { type CodeAgentProfile, trimTrailingSlashes } from "akanjs/common";
 import { akanCodeDefaultModel } from "./akanCodeModel";
 
 interface PreparedRequest {
@@ -27,7 +27,7 @@ export class CodeAgentProxy {
   readonly #token?: string;
 
   constructor({ baseUrl, providers, tokenFile, token }: CodeAgentProxyOptions) {
-    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.baseUrl = trimTrailingSlashes(baseUrl);
     this.providers = providers;
     this.#tokenFile = tokenFile;
     this.#token = token;

package/codeAgent/agent/akanCodeModel.ts

@@ -8,7 +8,7 @@ export interface CodeAgentModelRef {
   id: string;
 }
 
-/** DeepSeek's million-token window is what makes a 26k-token `AGENTS.md` affordable on every turn. */
+/** DeepSeek's million-token window is what makes the always-loaded `AGENTS.md` affordable on every turn. */
 export const akanCodeDefaultModel: CodeAgentModelRef = { provider: "deepseek", id: "deepseek-flash" };
 
 // Declared text-only by the catalogue, yet verified against the provider to see images.

package/codeAgent/agent/akanContextFiles.test.ts

@@ -73,7 +73,9 @@ describe("workspace context files", () => {
   test("a rule with no frontmatter at all is unconditional, and so is .cursorrules", () => {
     const root = workspace({ ".cursor/rules/plain.mdc": "just do it", ".cursorrules": "the legacy file" });
     const files = AkanContextFiles.extend(loaded(root), { workspaceRoot: root, cwd: root });
-    expect(namesOf(files, root).sort()).toEqual([".cursorrules", ".cursor/rules/plain.mdc", "AGENTS.md"].sort());
+    expect(namesOf(files, root).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))).toEqual(
+      [".cursorrules", ".cursor/rules/plain.mdc", "AGENTS.md"].sort(),
+    );
   });
 
   test("rules nested under the rules directory are found, in a stable order", () => {

package/codeAgent/tools/WebToolPack.ts

@@ -132,14 +132,14 @@ export class WebToolPack {
   /** Enough to read a documentation page; a full HTML parser is not worth a dependency for that. */
   static #readable(html: string) {
     return html
-      .replace(/<script[\s\S]*?<\/script>/gi, " ")
-      .replace(/<style[\s\S]*?<\/style>/gi, " ")
-      .replace(/<[^>]+>/g, " ")
+      .replace(/<script[\s\S]*?<\/script[^<>]*>/gi, " ")
+      .replace(/<style[\s\S]*?<\/style[^<>]*>/gi, " ")
+      .replace(/<[^<>]+>/g, " ")
       .replace(/&nbsp;/g, " ")
-      .replace(/&amp;/g, "&")
       .replace(/&lt;/g, "<")
       .replace(/&gt;/g, ">")
       .replace(/&quot;/g, '"')
+      .replace(/&amp;/g, "&")
       .replace(/[ \t]+/g, " ")
       .replace(/\n{3,}/g, "\n\n")
       .trim();

package/codeAgent/tools/akanCodePlugins.test.ts

@@ -247,22 +247,26 @@ describe("PreviewView", () => {
     expect(typeof PreviewView.available).toBe("boolean");
   });
 
-  test.skipIf(!PreviewView.available)("finds an empty body and a console error on a real page", async () => {
-    const server = Bun.serve({
-      port: 0,
-      fetch: () =>
-        new Response('<!doctype html><html><body></body><script>console.error("boom")</script></html>', {
-          headers: { "content-type": "text/html" },
-        }),
-    });
-    try {
-      const probe = await PreviewView.probe(`http://localhost:${server.port}/`);
-      expect(probe.pageErrors.join(" ")).toContain("rendered empty");
-      expect(probe.consoleErrors.join(" ")).toContain("boom");
-    } finally {
-      server.stop(true);
-    }
-  });
+  test.skipIf(!PreviewView.available)(
+    "finds an empty body and a console error on a real page",
+    async () => {
+      const server = Bun.serve({
+        port: 0,
+        fetch: () =>
+          new Response('<!doctype html><html><body></body><script>console.error("boom")</script></html>', {
+            headers: { "content-type": "text/html" },
+          }),
+      });
+      try {
+        const probe = await PreviewView.probe(`http://localhost:${server.port}/`);
+        expect(probe.pageErrors.join(" ")).toContain("rendered empty");
+        expect(probe.consoleErrors.join(" ")).toContain("boom");
+      } finally {
+        server.stop(true);
+      }
+    },
+    30_000,
+  );
 });
 
 describe("SubagentPool", () => {

package/commandDecorators/command.ts

@@ -186,20 +186,21 @@ const assignCommandContext = (context: CommandContext, argMeta: ArgMeta | Intern
   else context.values[argMeta.type.toLowerCase()] = value;
 };
 
+//? Not `.env`, which a fresh clone lacks; an app or a package folder has a package.json and tsconfig.json of its own.
 const assertCurrentDirectoryIsWorkspaceRoot = async () => {
   const cwd = process.cwd();
-  const [hasPackageJson, hasTsConfig, hasEnv] = await Promise.all([
+  const [hasPackageJson, hasTsConfig, ...hasMemberDirs] = await Promise.all([
     FileSys.fileExists(`${cwd}/package.json`),
     FileSys.fileExists(`${cwd}/tsconfig.json`),
-    FileSys.fileExists(`${cwd}/.env`),
+    ...["apps", "libs", "pkgs"].map((dir) => FileSys.dirExists(`${cwd}/${dir}`)),
   ]);
-  if (hasPackageJson && hasTsConfig && hasEnv) return;
+  if (hasPackageJson && hasTsConfig && hasMemberDirs.some(Boolean)) return;
 
   throw new Error(
     [
       "Akan CLI commands must be run from the workspace root.",
       `Current directory: ${cwd}`,
-      "Move to the directory that contains package.json, tsconfig.json, and .env, then run the command again.",
+      "Move to the directory that contains package.json, tsconfig.json, and an apps/, libs/ or pkgs/ folder, then run the command again.",
     ].join("\n"),
   );
 };

package/createTunnel.test.ts

@@ -48,4 +48,18 @@ describe("createTunnel", () => {
       expect(failure.message).toContain(reason.message);
     }
   });
+
+  test("refuses to dial a cluster host built on the local default serve domain", async () => {
+    const { app } = track(await createTempApp("demo"));
+    delete process.env.AKAN_PUBLIC_SERVE_DOMAIN;
+    const connect = spyOn(Client.prototype, "connect");
+    try {
+      await expect(createTunnel("redis", { app, environment: "debug" })).rejects.toThrow(
+        'The redis tunnel for the "debug" environment needs AKAN_PUBLIC_SERVE_DOMAIN (would be "localhost") set',
+      );
+      expect(connect).not.toHaveBeenCalled();
+    } finally {
+      connect.mockRestore();
+    }
+  });
 });

package/createTunnel.ts

@@ -10,7 +10,9 @@ export const createTunnel = async (
   service: "redis" | "postgres",
   { app, environment, port = service === "postgres" ? 5432 : 6379 }: TunnelOption,
 ) => {
-  const { serveDomain, repoName } = WorkspaceExecutor.getBaseDevEnv();
+  const baseDevEnv = WorkspaceExecutor.getBaseDevEnv();
+  WorkspaceExecutor.assertDeployableEnv(baseDevEnv, environment, `The ${service} tunnel`);
+  const { serveDomain, repoName } = baseDevEnv;
   const host = `${app.name}-${environment}.${serveDomain}`;
   const sshPort = process.env.SSH_TUNNEL_PORT ? parseInt(process.env.SSH_TUNNEL_PORT) : 32767;
   const dstHost = `${service}-0.${service}-svc.${app.name}-${environment}.svc.cluster.local`;

package/dependencyScanner.ts

@@ -107,7 +107,7 @@ export class TypeScriptDependencyScanner {
     return {
       npmDeps: [...runtimeDeps].sort(),
       npmDevDeps: [...devDeps].sort(),
-      missingDeps: missingDeps.sort(),
+      missingDeps: missingDeps.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)),
     };
   }
 

package/devkitUtils.test.ts

@@ -76,7 +76,7 @@ describe("TypeScriptDependencyScanner", () => {
     });
     expect(deps.pkgDeps).toEqual(["akanjs/tool"]);
     expect(deps.libDeps).toEqual(["shared"]);
-    expect(deps.npmDeps.sort()).toEqual(["lodash", "react"]);
+    expect(deps.npmDeps.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))).toEqual(["lodash", "react"]);
     expect(deps.npmDevDeps).toEqual(["typescript"]);
 
     const graph = scanner.generateDependencyGraph();

package/executors.test.ts

@@ -335,7 +335,7 @@ describe("Executor filesystem helpers", () => {
 });
 
 describe("Workspace and app executor environment contracts", () => {
-  test("reads base development environment and reports required missing values", () => {
+  test("reads base development environment", () => {
     process.env.AKAN_PUBLIC_REPO_NAME = "repo";
     process.env.AKAN_PUBLIC_SERVE_DOMAIN = "example.com";
     process.env.AKAN_PUBLIC_ENV = "local";
@@ -351,10 +351,53 @@ describe("Workspace and app executor environment contracts", () => {
       env: "local",
       portOffset: 10,
       workspaceId: undefined,
+      defaulted: [],
     });
+  });
 
-    delete process.env.AKAN_PUBLIC_REPO_NAME;
-    expect(() => WorkspaceExecutor.getBaseDevEnv()).toThrow("AKAN_PUBLIC_REPO_NAME is not set");
+  test("unset, the repo name is the origin remote's and the serve domain localhost, both marked defaulted", async () => {
+    const root = await makeTempRoot();
+    for (const args of [
+      ["init", "-q"],
+      ["remote", "add", "origin", "git@github.com:akan-team/fixture-repo.git"],
+    ])
+      expect(Bun.spawnSync(["git", ...args], { cwd: root }).exitCode).toBe(0);
+    for (const key of ["AKAN_PUBLIC_REPO_NAME", "AKAN_PUBLIC_SERVE_DOMAIN", "AKAN_PUBLIC_ENV", "AKAN_WORKSPACE_ROOT"])
+      delete process.env[key];
+
+    expect(WorkspaceExecutor.getBaseDevEnv(path.join(root, ".env"))).toMatchObject({
+      repoName: "fixture-repo",
+      serveDomain: "localhost",
+      env: "debug",
+      defaulted: ["AKAN_PUBLIC_REPO_NAME", "AKAN_PUBLIC_SERVE_DOMAIN"],
+    });
+
+    process.env.AKAN_PUBLIC_SERVE_DOMAIN = "example.com";
+    expect(WorkspaceExecutor.getBaseDevEnv(path.join(root, ".env"))).toMatchObject({
+      repoName: "fixture-repo",
+      serveDomain: "example.com",
+      defaulted: ["AKAN_PUBLIC_REPO_NAME"],
+    });
+  });
+
+  test("a build or tunnel for a real environment refuses a defaulted value, and a local one takes it", () => {
+    const baseDevEnv = {
+      repoName: "fixture-repo",
+      serveDomain: "localhost",
+      env: "debug" as const,
+      portOffset: 0,
+      workspaceRoot: undefined,
+    };
+    const defaulted = { ...baseDevEnv, defaulted: ["AKAN_PUBLIC_SERVE_DOMAIN" as const] };
+
+    expect(() => WorkspaceExecutor.assertDeployableEnv(defaulted, "main", "akan build")).toThrow(
+      'akan build for the "main" environment needs AKAN_PUBLIC_SERVE_DOMAIN (would be "localhost") set',
+    );
+    expect(() => WorkspaceExecutor.assertDeployableEnv(defaulted, "local", "akan build")).not.toThrow();
+    expect(() =>
+      WorkspaceExecutor.assertDeployableEnv({ ...baseDevEnv, defaulted: [] }, "main", "akan build"),
+    ).not.toThrow();
+    expect(() => WorkspaceExecutor.assertDeployableEnv(baseDevEnv, "main", "akan build")).not.toThrow();
   });
 
   test("reads base development environment from an explicit env file", async () => {
@@ -382,6 +425,7 @@ describe("Workspace and app executor environment contracts", () => {
       env: "develop",
       portOffset: 7,
       workspaceId: undefined,
+      defaulted: [],
     });
   });
 
@@ -440,6 +484,21 @@ describe("Workspace and app executor environment contracts", () => {
     expect((await stat(path.join(root, "dist/apps/demo/public"))).isDirectory()).toBe(true);
   });
 
+  test("the app command env hands the dev server the local defaults that stood in for unset values", async () => {
+    const root = await makeTempRoot();
+    delete process.env.AKAN_PUBLIC_REPO_NAME;
+    delete process.env.AKAN_PUBLIC_SERVE_DOMAIN;
+    process.env.AKAN_WORKSPACE_ROOT = root;
+    const app = AppExecutor.from(new WorkspaceExecutor({ workspaceRoot: root, repoName: "repo" }), "defaults");
+
+    const env = app.getCommandEnv();
+    expect(env.AKAN_PUBLIC_SERVE_DOMAIN).toBe("localhost");
+    expect(env.AKAN_PUBLIC_REPO_NAME).toBe(WorkspaceExecutor.getBaseDevEnv().repoName);
+
+    process.env.AKAN_PUBLIC_SERVE_DOMAIN = "example.com";
+    expect(app.getCommandEnv().AKAN_PUBLIC_SERVE_DOMAIN).toBe("example.com");
+  });
+
   test("akan start clears the dev output and keeps the bin downloads and a native folder from before dist/native", async () => {
     const root = await makeTempRoot();
     process.env.AKAN_PUBLIC_REPO_NAME = "repo";

package/executors.ts

@@ -54,7 +54,7 @@ import { Spinner } from "./spinner";
 // Type-only: `getTypeChecker` loads it on demand to keep `typescript` out of the resident module graph.
 import type { TypeChecker } from "./typeChecker";
 import { ProjectTypecheck } from "./typecheck/projectTypecheck";
-import type { FileContent, PackageJson, TsConfigJson } from "./types";
+import type { BaseDevEnv, FileContent, PackageJson, TsConfigJson } from "./types";
 import { barrelFacetDirs } from "./workspaceLayout";
 
 export interface PageRoot {
@@ -662,6 +662,7 @@ export class WorkspaceExecutor extends Executor {
   }
   /** The public env a native build was told to reproduce (`--public-env`): it outranks `.env`, which outranks the rest. */
   static publicEnvPin: Record<string, string> | null = null;
+  static readonly localServeDomain = "localhost";
   static getBaseDevEnv(envPath?: string) {
     // Bun auto-loads .env, so we use process.env directly
     const sourceEnv = {
@@ -673,11 +674,11 @@ export class WorkspaceExecutor extends Executor {
     const workspaceRoot = sourceEnv.AKAN_WORKSPACE_ROOT;
     const workspaceId = sourceEnv.AKAN_WORKSPACE_ID;
 
-    const repoName = sourceEnv.AKAN_PUBLIC_REPO_NAME;
-    if (!repoName) throw new Error("AKAN_PUBLIC_REPO_NAME is not set");
-
-    const serveDomain = sourceEnv.AKAN_PUBLIC_SERVE_DOMAIN;
-    if (!serveDomain) throw new Error("AKAN_PUBLIC_SERVE_DOMAIN is not set");
+    const repoName =
+      sourceEnv.AKAN_PUBLIC_REPO_NAME ||
+      resolveRepoName(envPath ? path.dirname(envPath) : (workspaceRoot ?? process.cwd()));
+    const serveDomain = sourceEnv.AKAN_PUBLIC_SERVE_DOMAIN || WorkspaceExecutor.localServeDomain;
+    const defaulted = (["AKAN_PUBLIC_REPO_NAME", "AKAN_PUBLIC_SERVE_DOMAIN"] as const).filter((key) => !sourceEnv[key]);
 
     const portOffset = parseInt(sourceEnv.PORT_OFFSET ?? "0");
 
@@ -697,8 +698,20 @@ export class WorkspaceExecutor extends Executor {
       env,
       portOffset,
       workspaceId,
+      defaulted,
     };
   }
+  //? A build or tunnel for a real environment carries these into an image, a bundle or a host name it dials.
+  static assertDeployableEnv(baseDevEnv: BaseDevEnv, environment: string, purpose: string) {
+    const defaulted = environment === "local" ? [] : (baseDevEnv.defaulted ?? []);
+    if (!defaulted.length) return;
+    const values = { AKAN_PUBLIC_REPO_NAME: baseDevEnv.repoName, AKAN_PUBLIC_SERVE_DOMAIN: baseDevEnv.serveDomain };
+    const standIns = defaulted.map((key) => `${key} (would be "${values[key]}")`).join(" and ");
+    throw new Error(
+      `${purpose} for the "${environment}" environment needs ${standIns} set, not a local default. ` +
+        `Set ${defaulted.length > 1 ? "them" : "it"} in the workspace .env or the shell, or use AKAN_PUBLIC_ENV=local.`,
+    );
+  }
   getWorkspaceId<AllowEmpty extends boolean = false>({
     allowEmpty,
   }: {
@@ -1159,10 +1172,12 @@ export class AppExecutor extends SysExecutor {
     return basePort + appIndex + portOffset;
   }
   getCommandEnv(env: Record<string, string> = {}): Record<string, string> {
-    const { portOffset } = WorkspaceExecutor.getBaseDevEnv();
+    const { portOffset, repoName, serveDomain } = WorkspaceExecutor.getBaseDevEnv();
     const PORT = (8282 + portOffset).toString();
     return {
       ...process.env,
+      AKAN_PUBLIC_REPO_NAME: repoName,
+      AKAN_PUBLIC_SERVE_DOMAIN: serveDomain,
       AKAN_PUBLIC_APP_NAME: this.name,
       AKAN_WORKSPACE_ROOT: this.workspace.workspaceRoot,
       NODE_NO_WARNINGS: "1",
@@ -1323,7 +1338,7 @@ export class AppExecutor extends SysExecutor {
         pageKeys.push(key);
       }
     }
-    pageKeys.sort();
+    pageKeys.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
     this.#pageKeys = this.#excludeDevOnlyPages ? this.#dropDevOnlyPages(pageKeys, devOnlyKeys, devOnlyDirs) : pageKeys;
     return this.#pageKeys;
   }
@@ -1581,7 +1596,9 @@ export class PkgExecutor extends Executor {
     devDependencies: string[] = [],
   ): Promise<Pick<PackageJson, "dependencies" | "devDependencies">> {
     const dependencyNames = [...new Set(dependencies)].sort();
-    const devDependencyNames = [...new Set(devDependencies)].filter((dep) => !dependencyNames.includes(dep)).sort();
+    const devDependencyNames = [...new Set(devDependencies)]
+      .filter((dep) => !dependencyNames.includes(dep))
+      .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
     const dependencyVersions = new Map<string, string>();
     const missingDeps: string[] = [];
     for (const dep of [...dependencyNames, ...devDependencyNames]) {

package/frontendBuild/autoImportSync.test.ts

@@ -253,7 +253,9 @@ describe("AutoImportSync.syncForBatch", () => {
 
     const result = await sync.syncForBatch([uiFile, pageFile, webkitFile]);
     expect(result.errors).toEqual([]);
-    expect(result.changedFiles.sort()).toEqual([pageFile, webkitFile, uiFile].sort());
+    expect(result.changedFiles.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))).toEqual(
+      [pageFile, webkitFile, uiFile].sort(),
+    );
     expect(await readFile(uiFile, "utf8")).toContain(`import { st } from "@apps/akan/client";`);
     expect(await readFile(pageFile, "utf8")).toContain(`import { cnst } from "@apps/akan/client";`);
     expect(await readFile(webkitFile, "utf8")).toContain(`import { fetch } from "@libs/shared/client";`);

package/frontendBuild/clientEntryDiscovery.ts

@@ -6,7 +6,7 @@ import { BarrelAnalyzer } from "../transforms/barrelAnalyzer";
 import { createTsconfigPackageResolver, rewriteBarrelImports } from "../transforms/barrelImportsPlugin";
 import type { AkanConfig, ClientEntryDiscovery, ScannedImport } from "./clientBuildTypes";
 
-const USE_CLIENT_RE = /^\s*(?:\/\*[\s\S]*?\*\/\s*|\/\/[^\n]*\n\s*)*["']use client["']/;
+const USE_CLIENT_RE = /^\s*(?:\/\*[^*]*\*+(?:[^/*][^*]*\*+)*\/\s*|\/\/[^\n]*\n\s*)*["']use client["']/;
 const NODE_MODULES_RE = /[\\/]node_modules[\\/]/;
 const AKANJS_NODE_MODULE_RE = /[\\/]node_modules[\\/]akanjs[\\/]/;
 // Bun's scanImports also surfaces CSS and asset imports, none of which can be a client component.