@akanjs/devkit 3.1.0-rc.1 → 3.1.0-rc.2

package/commandDecorators/command.ts

@@ -23,6 +23,7 @@ import {
 } from "./argMeta";
 import { camelToKebabCase } from "./camelToKebabCase";
 import { CommandContainer } from "./dependencyBuilder";
+import { ExitCodeError } from "./exitCodeError";
 import { formatCommandHelp, formatHelp } from "./helpFormatter";
 import { type CommandCls, getTargetCommandNames, getTargetMetas } from "./targetMeta";
 
@@ -102,6 +103,9 @@ const confirm = ((config, context) => prompts().then((m) => m.confirm(config, co
 const input = ((config, context) => prompts().then((m) => m.input(config, context))) as typeof inquirerInput;
 const checkbox = ((config, context) => prompts().then((m) => m.checkbox(config, context))) as typeof inquirerCheckbox;
 
+const argLabelOf = (argMeta: ArgMeta) =>
+  argMeta.type === "Option" ? `option '--${camelToKebabCase(argMeta.name)}'` : `argument '${argMeta.name}'`;
+
 // A DynamicEnum is not checked: it resolves against a context the internal args have not populated yet.
 // Compared as strings: the value is still commander's raw string while a numeric choice list holds numbers.
 const assertEnumChoice = (argMeta: ArgMeta, value: unknown) => {
@@ -109,10 +113,19 @@ const assertEnumChoice = (argMeta: ArgMeta, value: unknown) => {
   if (!enumChoices || typeof enumChoices === "function") return;
   const choices = normalizeEnumChoices(enumChoices);
   if (choices.some((choice) => String(choice.value) === String(value))) return;
-  const label =
-    argMeta.type === "Option" ? `option '--${camelToKebabCase(argMeta.name)}'` : `argument '${argMeta.name}'`;
   throw new Error(
-    `${label} argument '${String(value)}' is invalid. Allowed choices are ${choices.map((choice) => choice.name).join(", ")}.`,
+    `${argLabelOf(argMeta)} argument '${String(value)}' is invalid. Allowed choices are ${choices.map((choice) => choice.name).join(", ")}.`,
+  );
+};
+
+// On a piped stdin a prompt takes the pipe as its answer and echoes it: a piped secret printed as the secret's name.
+export const assertPromptable = (
+  problem: string,
+  { choices = [], remedy = "pass it on the command line" }: { choices?: readonly unknown[]; remedy?: string } = {},
+) => {
+  if (process.stdin.isTTY) return;
+  throw new Error(
+    `${problem}: stdin is not a terminal to prompt on, so ${remedy}${choices.length ? ` (choices: ${choices.join(", ")})` : ""}.`,
   );
 };
 
@@ -136,8 +149,11 @@ export const getOptionValue = async (argMeta: ArgMeta, opt: Record<string, unkno
       (typeof enumChoices === "function" ? await enumChoices(context) : enumChoices) ?? [],
     );
     if (choices.length === 1) return choices[0]?.value;
+    assertPromptable(`Missing ${argLabelOf(argMeta)}`, { choices: choices.map((choice) => choice.value) });
     return await select({ message: ask ?? desc ?? `Select the ${name} value`, choices });
-  } else if (type === "boolean") {
+  }
+  assertPromptable(`Missing ${argLabelOf(argMeta)}`);
+  if (type === "boolean") {
     const message = ask ?? desc ?? `Do you want to set ${name}? ${desc ? ` (${desc})` : ""}: `;
     return await confirm({ message });
   } else return convertArgValue(await input({ message: inputMessageOf(argMeta) }), type ?? "string");
@@ -150,6 +166,13 @@ export const getArgumentValue = async (argMeta: ArgMeta, value: string | undefin
     return convertArgValue(value, type ?? "string");
   } else if (defaultValue !== undefined) return defaultValue;
   else if (nullable) return null;
+  const { enum: enumChoices } = argMeta.argsOption;
+  assertPromptable(`Missing ${argLabelOf(argMeta)}`, {
+    choices:
+      enumChoices && typeof enumChoices !== "function"
+        ? normalizeEnumChoices(enumChoices).map(({ value }) => value)
+        : [],
+  });
   return convertArgValue(await input({ message: inputMessageOf(argMeta) }), type ?? "string");
 };
 
@@ -205,6 +228,7 @@ export const getAppsArgumentValue = async (
     return [...new Set(requested)].map((name) => AppExecutor.from(workspace, name));
   }
   if (appNames.length === 1 && appNames[0]) return [AppExecutor.from(workspace, appNames[0])];
+  assertPromptable("Missing apps", { choices: [...appNames, "all"] });
   const remembered = new Set(await AppSelectionMemory.read(workspace.workspaceRoot));
   const picked = await checkbox<string>({
     message: "Select the apps to run (space to toggle, enter to confirm)",
@@ -224,6 +248,7 @@ export const getInternalArgumentValue = async (
   if (argMeta.type === "Workspace") return workspace;
   const sysType = argMeta.type.toLowerCase();
   const [appNames, libNames, pkgNames] = await workspace.getExecs();
+  const problemOf = (kind: string) => (value ? `Unknown ${kind} '${value}'` : `Missing ${kind}`);
   if (sysType === "sys" || sysType === "exec") {
     const pkgChoices = sysType === "exec" ? pkgNames : [];
     const execOf = (name: string) => {
@@ -234,6 +259,11 @@ export const getInternalArgumentValue = async (
     };
     const found = value ? execOf(value) : null;
     if (found) return found;
+    if (!value && argMeta.option?.onlyApp && appNames.length === 1 && appNames[0])
+      return AppExecutor.from(workspace, appNames[0]);
+    assertPromptable(problemOf(sysType === "exec" ? "app, lib or pkg" : "app or lib"), {
+      choices: [...appNames, ...libNames, ...pkgChoices],
+    });
     const name = await select<string>({
       message: sysType === "exec" ? `Select the App or Lib or Pkg name` : `Select the App or Lib name`,
       choices: [...appNames, ...libNames, ...pkgChoices],
@@ -244,15 +274,18 @@ export const getInternalArgumentValue = async (
   } else if (sysType === "app") {
     if (value && appNames.includes(value)) return AppExecutor.from(workspace, value);
     if (!value && appNames.length === 1 && appNames[0]) return AppExecutor.from(workspace, appNames[0]);
+    assertPromptable(problemOf("app"), { choices: appNames });
     const appName = await select<string>({ message: `Select the ${sysType} name`, choices: appNames });
     return AppExecutor.from(workspace, appName);
   } else if (sysType === "lib") {
     if (value && libNames.includes(value)) return LibExecutor.from(workspace, value);
+    assertPromptable(problemOf("lib"), { choices: libNames });
     const libName = await select<string>({ message: `Select the ${sysType} name`, choices: libNames });
     return LibExecutor.from(workspace, libName);
   } else if (sysType === "pkg") {
     const pkgs = await workspace.getPkgs();
     if (value && pkgs.includes(value)) return PkgExecutor.from(workspace, value);
+    assertPromptable(problemOf("pkg"), { choices: pkgs });
     const pkgName = await select<string>({ message: `Select the ${sysType} name`, choices: pkgs });
     return PkgExecutor.from(workspace, pkgName);
   } else if (sysType === "module") {
@@ -270,6 +303,7 @@ export const getInternalArgumentValue = async (
         if (modules.includes(moduleName)) return ModuleExecutor.from(lib, moduleName);
       } else throw new Error(`Invalid system name: ${sysName}`);
     }
+    assertPromptable(problemOf("module"));
     const { type, name } = await select<{ type: "app" | "lib"; name: string }>({
       message: `select the App or Lib name`,
       choices: [
@@ -291,7 +325,7 @@ export const runCommands = async (...commands: CommandCls[]) => {
   let failureExitCode = 1;
   process.on("unhandledRejection", (error) => {
     printCliError(error);
-    process.exit(failureExitCode);
+    process.exit(ExitCodeError.codeOf(error) ?? failureExitCode);
   });
   const __dirname = getDirname(import.meta.url);
   const packageJsonCandidates = [`${path.dirname(Bun.main)}/package.json`, `${__dirname}/../package.json`];
@@ -419,6 +453,6 @@ It may cause unexpected behavior. Run \`akan update\` to update latest akanjs.`,
   // Handled here, not by the handler above: a rejection reaching the entry's top-level await prints Bun's own trace.
   await program.parseAsync(process.argv).catch((error: unknown) => {
     printCliError(error);
-    process.exit(failureExitCode);
+    process.exit(ExitCodeError.codeOf(error) ?? failureExitCode);
   });
 };

package/commandDecorators/commandBuilder.ts

@@ -115,7 +115,12 @@ class TargetBuilder<Deps extends readonly DependencyCls[], Params extends unknow
 
   with<const Tokens extends readonly InternalArgToken[]>(...tokens: Tokens) {
     return this.#add<AddInternalArgs<Params, Tokens>, AddInternalContext<Context, Tokens>>(
-      ...tokens.map((token, offset) => ({ key: "", idx: this.#args.length + offset, type: token.type })),
+      ...tokens.map((token, offset) => ({
+        key: "",
+        idx: this.#args.length + offset,
+        type: token.type,
+        ...(token.option ? { option: token.option } : {}),
+      })),
     );
   }
 

package/commandDecorators/commandDecorators.test.ts

@@ -1,7 +1,21 @@
-import { afterEach, describe, expect, test } from "bun:test";
-import { AppExecutor, WorkspaceExecutor } from "../executors";
-import { App, type ArgMeta, type ArgsOption, getArgMetas, Lib, Module, Pkg, Sys, Workspace } from "./argMeta";
-import { getArgumentValue, getInternalArgumentValue, getOptionValue } from "./command";
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import path from "node:path";
+import { AppExecutor, LibExecutor, WorkspaceExecutor } from "../executors";
+import { makeCliTempWorkspace, tempRoots, writeText } from "../testHelpers";
+import {
+  App,
+  type ArgMeta,
+  type ArgsOption,
+  getArgMetas,
+  type InternalArgMeta,
+  Lib,
+  Module,
+  Pkg,
+  Sys,
+  SysOrOnlyApp,
+  Workspace,
+} from "./argMeta";
+import { getAppsArgumentValue, getArgumentValue, getInternalArgumentValue, getOptionValue } from "./command";
 import { command } from "./commandBuilder";
 import {
   assertUniqueDependencies,
@@ -289,6 +303,89 @@ describe("enum arg choices", () => {
   });
 });
 
+describe("prompts on a stdin that is not a terminal", () => {
+  const ownIsTTY = Object.getOwnPropertyDescriptor(process.stdin, "isTTY");
+  beforeEach(() => {
+    Object.defineProperty(process.stdin, "isTTY", { value: undefined, configurable: true });
+  });
+  afterEach(() => {
+    if (ownIsTTY) Object.defineProperty(process.stdin, "isTTY", ownIsTTY);
+    else Reflect.deleteProperty(process.stdin, "isTTY");
+  });
+  const metaOf = (type: "Argument" | "Option", name: string, argsOption: ArgsOption = {}): ArgMeta => ({
+    name,
+    argsOption: { type: "string", ...argsOption },
+    key: "run",
+    idx: 0,
+    type,
+  });
+  const context = { values: {} };
+  const workspaceWith = (appNames: string[]) => {
+    const workspace = new WorkspaceExecutor({ workspaceRoot: "/workspace", repoName: "repo" });
+    workspace.getExecs = async () => [appNames, ["util"], []];
+    workspace.getApps = async () => appNames;
+    return workspace;
+  };
+
+  test("a missing positional is refused by name instead of read from the pipe", async () => {
+    await expect(getArgumentValue(metaOf("Argument", "name", { desc: "secret name" }), undefined)).rejects.toThrow(
+      "Missing argument 'name': stdin is not a terminal to prompt on, so pass it on the command line.",
+    );
+    await expect(getArgumentValue(metaOf("Argument", "action", { enum: ["scan", "ssr"] }), undefined)).rejects.toThrow(
+      "Missing argument 'action': stdin is not a terminal to prompt on, so pass it on the command line (choices: scan, ssr).",
+    );
+  });
+
+  test("a missing option names its flag and the values it takes", async () => {
+    await expect(
+      getOptionValue(metaOf("Option", "platform", { enum: ["ios", "android"] }), {}, context),
+    ).rejects.toThrow(
+      "Missing option '--platform': stdin is not a terminal to prompt on, so pass it on the command line (choices: ios, android).",
+    );
+    await expect(
+      getOptionValue(
+        metaOf("Option", "format", { enum: [{ label: "JSON output", value: "json" }, "text"] }),
+        {},
+        context,
+      ),
+    ).rejects.toThrow("(choices: json, text)");
+    await expect(getOptionValue(metaOf("Option", "assembleType"), {}, context)).rejects.toThrow(
+      "Missing option '--assemble-type'",
+    );
+    await expect(getOptionValue(metaOf("Option", "force", { type: "boolean" }), {}, context)).rejects.toThrow(
+      "Missing option '--force'",
+    );
+  });
+
+  test("a value given, defaulted, nullable or the only choice still resolves without a prompt", async () => {
+    expect(await getArgumentValue(metaOf("Argument", "name"), "NPM_TOKEN")).toBe("NPM_TOKEN");
+    expect(await getOptionValue(metaOf("Option", "env", { default: "main" }), {}, context)).toBe("main");
+    expect(await getOptionValue(metaOf("Option", "host", { nullable: true }), {}, context)).toBe(null);
+    expect(await getOptionValue(metaOf("Option", "target", { enum: async () => ["default"] }), {}, context)).toBe(
+      "default",
+    );
+    const [app] = await getAppsArgumentValue(undefined, workspaceWith(["web"]));
+    expect(app?.name).toBe("web");
+  });
+
+  test("an app that is missing or unknown is refused with the workspace's apps", async () => {
+    const workspace = workspaceWith(["web", "admin"]);
+    await expect(getInternalArgumentValue({ key: "", idx: 0, type: "App" }, undefined, workspace)).rejects.toThrow(
+      "Missing app: stdin is not a terminal to prompt on, so pass it on the command line (choices: web, admin).",
+    );
+    await expect(getInternalArgumentValue({ key: "", idx: 0, type: "App" }, "globex", workspace)).rejects.toThrow(
+      "Unknown app 'globex'",
+    );
+    await expect(getInternalArgumentValue({ key: "", idx: 0, type: "Sys" }, "globex", workspace)).rejects.toThrow(
+      "Unknown app or lib 'globex': stdin is not a terminal to prompt on, so pass it on the command line (choices: web, admin, util).",
+    );
+    await expect(getInternalArgumentValue({ key: "", idx: 0, type: "Module" }, undefined, workspace)).rejects.toThrow(
+      "Missing module",
+    );
+    await expect(getAppsArgumentValue(undefined, workspace)).rejects.toThrow("(choices: web, admin, all)");
+  });
+});
+
 describe("enum arg type inference", () => {
   afterEach(() => {
     CommandContainer.clear();
@@ -334,3 +431,107 @@ describe("enum arg type inference", () => {
     ]);
   });
 });
+
+describe("a Sys that defaults to the only app", () => {
+  const ownIsTTY = Object.getOwnPropertyDescriptor(process.stdin, "isTTY");
+  const asked: unknown[] = [];
+  let answer = "";
+  const setTTY = (isTTY: boolean | undefined) =>
+    Object.defineProperty(process.stdin, "isTTY", { value: isTTY, configurable: true });
+  beforeEach(() => {
+    asked.length = 0;
+    mock.module("@inquirer/prompts", () => ({
+      select: async ({ choices }: { choices: unknown[] }) => {
+        asked.push(choices);
+        return answer;
+      },
+    }));
+  });
+  afterEach(() => {
+    CommandContainer.clear();
+    if (ownIsTTY) Object.defineProperty(process.stdin, "isTTY", ownIsTTY);
+    else Reflect.deleteProperty(process.stdin, "isTTY");
+  });
+  const workspaceWith = (appNames: string[]) => {
+    const workspace = new WorkspaceExecutor({ workspaceRoot: "/workspace", repoName: "repo" });
+    workspace.getExecs = async () => [appNames, ["util"], []];
+    return workspace;
+  };
+  const sysMetaOf = (key: "typecheck" | "sync") => {
+    class OnlyAppCommand extends command("onlyApp", ({ public: target }) => ({
+      typecheck: target({ desc: "opted in" })
+        .with(SysOrOnlyApp)
+        .exec((sys) => sys),
+      sync: target({ desc: "plain" })
+        .with(Sys)
+        .exec((sys) => sys),
+    })) {}
+    const meta = getArgMetas(OnlyAppCommand, key)[0].find((arg): arg is InternalArgMeta => arg.type === "Sys");
+    if (!meta) throw new Error(`no Sys meta on ${key}`);
+    return meta;
+  };
+
+  test("the opted-in command takes a one-app workspace's app without asking, even on a piped stdin", async () => {
+    setTTY(undefined);
+    const meta = sysMetaOf("typecheck");
+    expect(meta.option).toEqual({ onlyApp: true });
+
+    const app = await getInternalArgumentValue(meta, undefined, workspaceWith(["web"]));
+    expect(app instanceof AppExecutor ? app.name : null).toBe("web");
+    expect(asked).toEqual([]);
+  });
+
+  test("a plain Sys command still asks app or library in a one-app workspace", async () => {
+    setTTY(true);
+    answer = "util";
+    const meta = sysMetaOf("sync");
+    expect(meta.option).toBeUndefined();
+
+    const lib = await getInternalArgumentValue(meta, undefined, workspaceWith(["web"]));
+    expect(lib instanceof LibExecutor ? lib.name : null).toBe("util");
+    expect(asked).toEqual([["web", "util"]]);
+  });
+
+  test("the opted-in command still asks when the workspace has two apps", async () => {
+    setTTY(true);
+    answer = "admin";
+    const app = await getInternalArgumentValue(sysMetaOf("typecheck"), undefined, workspaceWith(["web", "admin"]));
+    expect(app instanceof AppExecutor ? app.name : null).toBe("admin");
+    expect(asked).toEqual([["web", "admin", "util"]]);
+  });
+});
+
+describe("the exit code of a command that failed", () => {
+  const track = tempRoots();
+  const run = async (failure: string) => {
+    const { root } = track(await makeCliTempWorkspace());
+    await writeText(path.join(root, "package.json"), '{ "name": "repo", "version": "1.0.0" }\n');
+    await writeText(path.join(root, "tsconfig.json"), "{}\n");
+    const entry = path.join(root, "cli.ts");
+    await writeText(
+      entry,
+      [
+        `import { command, ExitCodeError, runCommands, runner, script } from ${JSON.stringify(path.join(import.meta.dir, "index.ts"))};`,
+        'class VerdictRunner extends runner("verdict") {}',
+        'class VerdictScript extends script("verdict", [VerdictRunner]) {}',
+        'class VerdictCommand extends command("verdict", [VerdictScript], ({ public: target }) => ({',
+        '  verdict: target({ desc: "fails" }).exec(async function () {',
+        `    throw ${failure};`,
+        "  }),",
+        "})) {}",
+        "await runCommands(VerdictCommand);",
+        "",
+      ].join("\n"),
+    );
+    const proc = Bun.spawn(["bun", entry, "verdict"], { cwd: root, stdout: "pipe", stderr: "pipe" });
+    const [stdout, code] = await Promise.all([new Response(proc.stdout).text(), proc.exited]);
+    return { stdout, code };
+  };
+
+  test("is the one an ExitCodeError carries, and 1 for any other error", async () => {
+    const verdict = await run('new ExitCodeError("needs a new store build", 2)');
+    expect(verdict.stdout).toContain("needs a new store build");
+    expect(verdict.code).toBe(2);
+    expect((await run('new Error("broke")')).code).toBe(1);
+  }, 30_000);
+});

package/commandDecorators/exitCodeError.ts

@@ -0,0 +1,15 @@
+//* A failure that is an answer, not a breakage: the CLI exits with its code, so a CI tells the two apart.
+export class ExitCodeError extends Error {
+  override readonly name = "ExitCodeError";
+
+  constructor(
+    message: string,
+    readonly exitCode: number,
+  ) {
+    super(message);
+  }
+
+  static codeOf(error: unknown): number | null {
+    return error instanceof ExitCodeError ? error.exitCode : null;
+  }
+}

package/commandDecorators/index.ts

@@ -2,5 +2,6 @@ export * from "./argMeta";
 export * from "./command";
 export * from "./commandBuilder";
 export * from "./dependencyBuilder";
+export * from "./exitCodeError";
 export * from "./helpFormatter";
 export * from "./targetMeta";

package/executors.test.ts

@@ -188,6 +188,35 @@ describe("Executor filesystem helpers", () => {
     expect(formatted).toEqual([path.join(root, "apps/demo/page/task/_index.tsx")]);
   });
 
+  test("hands the formatter only the files a template wrote, never one overwrite: false kept", async () => {
+    const { root, app } = trackRoot(await createTempApp("demo"));
+    const formatted: string[] = [];
+    app.getLinter = () =>
+      ({
+        fixFiles: async (filePaths: string[]) => {
+          formatted.push(...filePaths);
+          return { fixed: [] };
+        },
+      }) as unknown as ReturnType<Executor["getLinter"]>;
+    const scalarDir = path.join(root, "apps/demo/lib/__scalar/money");
+    const own = "export class Money   {}\n";
+    await writeText(path.join(scalarDir, "money.constant.ts"), own);
+
+    const applied = await app.applyTemplate({
+      basePath: "./lib/__scalar",
+      template: "__scalar",
+      dict: { model: "money", models: "moneys", sysName: "demo" },
+      overwrite: false,
+    });
+
+    expect(applied.map((fileContent) => fileContent.filePath)).toContain(path.join(scalarDir, "money.constant.ts"));
+    expect(formatted.sort((a, b) => a.localeCompare(b))).toEqual([
+      path.join(scalarDir, "money.dictionary.ts"),
+      path.join(scalarDir, "money.document.ts"),
+    ]);
+    expect(await readFile(path.join(scalarDir, "money.constant.ts"), "utf8")).toBe(own);
+  });
+
   test("a formatter that cannot run does not fail the scaffold", async () => {
     // create-akan-workspace scaffolds before `bun install`, so Biome may be absent; a lint fix beats a failed scaffold.
     const root = await makeTempRoot();
@@ -263,6 +292,23 @@ describe("Executor filesystem helpers", () => {
       await readFile(path.join(templateRoot, "favicon.ico")),
     );
   });
+
+  test("keeps a static file already there when overwrite is false, and reports it unwritten", async () => {
+    const root = await makeTempRoot();
+    const exec = new Executor("fixture", root);
+    await writeText(path.join(root, "app/public/logo.png"), "the app's own logo");
+
+    const applied = await exec.applyTemplate({
+      basePath: "app/public",
+      template: "app/public/logo.png",
+      overwrite: false,
+    });
+
+    expect(await readFile(path.join(root, "app/public/logo.png"), "utf8")).toBe("the app's own logo");
+    expect(applied).toEqual([
+      expect.objectContaining({ filePath: path.join(root, "app/public/logo.png"), written: false }),
+    ]);
+  });
 });
 
 describe("Workspace and app executor environment contracts", () => {

package/executors.ts

@@ -28,6 +28,7 @@ import {
   isRouteSourceFile,
   Logger,
   parseRouteModuleKey,
+  toError,
   validatePageSourceFile,
   validateSubRoutePageKey,
 } from "akanjs/common";
@@ -52,6 +53,7 @@ import { AppInfo, isAkanFrameworkDependency, LibInfo, PkgInfo, WorkspaceInfo } f
 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 { barrelFacetDirs } from "./workspaceLayout";
 
@@ -64,6 +66,10 @@ export interface PageRoot {
   keyPrefix: string;
 }
 
+export interface WrittenFileContent extends FileContent {
+  written: boolean;
+}
+
 const staticTemplateFileExtensions = new Set(
   ".avif .bmp .cjs .css .eot .gif .html .ico .jpeg .jpg .js .json .map .md .mjs .mp3 .mp4 .ogg .otf .pdf .png .svg"
     .split(" ")
@@ -302,17 +308,19 @@ export class Executor {
     filePath: string,
     content: string | object,
     { overwrite = true, silent = false }: { overwrite?: boolean; silent?: boolean } = {},
-  ): Promise<FileContent> {
+  ): Promise<WrittenFileContent> {
     const writePath = this.getPath(filePath);
     const dir = path.dirname(writePath);
     if (!(await FileSys.dirExists(dir))) await mkdir(dir, { recursive: true });
     let contentStr = typeof content === "string" ? content : JsonFormatter.stringify(content, writePath);
+    let written = true;
 
     if (await FileSys.fileExists(writePath)) {
       const currentContent = await FileSys.readText(writePath);
       if (currentContent === contentStr || !overwrite) {
         this.logger.verbose(`File ${writePath} is unchanged`);
         contentStr = currentContent;
+        written = false;
       } else {
         await FileSys.writeText(writePath, contentStr);
         if (Logger.isVerbose()) this.logger.rawLog(chalk.yellow(`File Update: ${filePath}`));
@@ -321,7 +329,7 @@ export class Executor {
       await FileSys.writeText(writePath, contentStr);
       if (!silent) this.logger.rawLog(chalk.green(`File Create: ${filePath}`));
     }
-    return { filePath: writePath, content: contentStr };
+    return { filePath: writePath, content: contentStr, written };
   }
   async writeJson(filePath: string, content: object) {
     await this.writeFile(filePath, content);
@@ -418,7 +426,7 @@ export class Executor {
     },
     dict: { [key: string]: string } = {},
     options: { [key: string]: unknown } = {},
-  ): Promise<FileContent | null> {
+  ): Promise<WrittenFileContent | null> {
     const convertPath = (target: string) =>
       Object.entries(dict).reduce(
         (converted, [key, value]) => converted.replace(new RegExp(`__${key}__`, "g"), value),
@@ -451,11 +459,13 @@ export class Executor {
     } else if (staticTemplateFileExtensions.has(path.extname(targetPath).toLowerCase())) {
       const convertedTargetPath = convertPath(targetPath);
       const writePath = this.getPath(convertedTargetPath);
+      if (!overwrite && (await FileSys.fileExists(writePath)))
+        return { filePath: writePath, content: "", written: false };
       const dirname = path.dirname(writePath);
       if (!(await FileSys.dirExists(dirname))) await mkdir(dirname, { recursive: true });
       await copyFile(templatePath, writePath);
       this.logger.verbose(`Apply template ${templatePath} to ${convertedTargetPath}`);
-      return { filePath: writePath, content: "" };
+      return { filePath: writePath, content: "", written: true };
     } else return null;
   }
   async _applyTemplate({
@@ -472,7 +482,7 @@ export class Executor {
     dict?: { [key: string]: string };
     options?: { [key: string]: unknown };
     overwrite?: boolean;
-  }): Promise<FileContent[]> {
+  }): Promise<WrittenFileContent[]> {
     const templateRoot = await this.#resolveTemplateRoot();
     const templatePath = `${templateRoot}${template ? `/${template}` : ""}`;
     if ((await stat(templatePath)).isFile()) {
@@ -486,7 +496,7 @@ export class Executor {
         dict,
         options,
       );
-      return fileContent ? [fileContent] : ([] as FileContent[]);
+      return fileContent ? [fileContent] : ([] as WrittenFileContent[]);
     } else {
       const subdirs = await readDirEntries(templatePath);
       const fileContents = (
@@ -504,7 +514,7 @@ export class Executor {
                 dict,
                 options,
               );
-              return fileContent ? [fileContent] : ([] as FileContent[]);
+              return fileContent ? [fileContent] : ([] as WrittenFileContent[]);
             } else
               return await this._applyTemplate({
                 basePath: path.join(basePath, subdir),
@@ -539,7 +549,7 @@ export class Executor {
     overwrite?: boolean;
   }): Promise<FileContent[]> {
     const fileContents = await this._applyTemplate({ ...options, dict: withCapitalizedDict(options.dict) });
-    await this.#formatAppliedTemplate(fileContents);
+    await this.#formatAppliedTemplate(fileContents.filter((fileContent) => fileContent.written));
     return fileContents;
   }
 
@@ -554,7 +564,7 @@ export class Executor {
       const { fixed } = await this.getLinter().fixFiles(filePaths);
       if (fixed.length > 0) this.logger.verbose(`Formatted ${fixed.length} scaffolded file(s)`);
     } catch (err) {
-      this.logger.verbose(`Skipped formatting scaffolded files: ${err instanceof Error ? err.message : String(err)}`);
+      this.logger.verbose(`Skipped formatting scaffolded files: ${toError(err).message}`);
     }
   }
   // Async so `typescript` (~65MB resident) loads only in the commands that typecheck.
@@ -572,7 +582,7 @@ export class Executor {
   }
   async typeCheckAsync(filePath: string) {
     const path = this.getPath(filePath);
-    const entry = await this.#resolveTypecheckWorkerEntry();
+    const entry = await ProjectTypecheck.workerEntry(process.cwd());
     const proc = Bun.spawn([process.execPath, entry], {
       cwd: this.cwdPath,
       env: {
@@ -603,18 +613,6 @@ export class Executor {
       message: result.message,
     };
   }
-  async #resolveTypecheckWorkerEntry() {
-    const dirname = getDirname(import.meta.url);
-    const candidates = [
-      path.join(process.cwd(), "pkgs/@akanjs/devkit/typecheck/typecheck.proc.ts"),
-      path.join(process.cwd(), "node_modules/@akanjs/devkit/typecheck/typecheck.proc.ts"),
-      path.join(dirname, "typecheck/typecheck.proc.ts"),
-      path.join(dirname, "typecheck.proc.js"),
-      path.join(dirname, "typecheck.proc.ts"),
-    ];
-    for (const candidate of candidates) if (await Bun.file(candidate).exists()) return candidate;
-    throw new Error(`[devkit] typecheck worker entry not found; looked in: ${candidates.join(", ")}`);
-  }
   getLinter() {
     this.linter ??= new Linter(this.cwdPath);
     return this.linter;
@@ -662,9 +660,14 @@ export class WorkspaceExecutor extends Executor {
   } = {}) {
     return new WorkspaceExecutor({ workspaceRoot, repoName });
   }
+  /** 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 getBaseDevEnv(envPath?: string) {
     // Bun auto-loads .env, so we use process.env directly
-    const sourceEnv = envPath ? { ...process.env, ...parseEnvFile(envPath) } : process.env;
+    const sourceEnv = {
+      ...(envPath ? { ...process.env, ...parseEnvFile(envPath) } : process.env),
+      ...WorkspaceExecutor.publicEnvPin,
+    };
 
     const appName = sourceEnv.AKAN_PUBLIC_APP_NAME;
     const workspaceRoot = sourceEnv.AKAN_WORKSPACE_ROOT;

package/frontendBuild/csrArtifactBuilder.ts

@@ -61,8 +61,9 @@ export class CsrArtifactBuilder {
       ).flat(),
     );
 
+    const options = CsrArtifactBuilder.bundleOptions(this.#app, this.#command, akanConfig.optimizeImports);
     const result = await Bun.build({
-      ...CsrArtifactBuilder.bundleOptions(this.#app, this.#command, akanConfig.optimizeImports),
+      ...options,
       entrypoints: htmlBasePaths.map((basePath) => this.#generatedPath(CsrArtifactBuilder.htmlFilename(basePath))),
       files: generatedFiles,
       root: this.#generatedDir,
@@ -75,6 +76,7 @@ export class CsrArtifactBuilder {
     }
 
     await this.#inlineCsrArtifacts(cssAssets);
+    if (this.#command === "build") await CsrArtifactBuilder.writePublicEnv(this.#app, options.define);
     this.#app.verbose(`[csr-build] output -> ${this.#outputDir}`);
     return { outputDir: this.#outputDir };
   }
@@ -92,6 +94,21 @@ export class CsrArtifactBuilder {
     };
   }
 
+  /** Where a build records the `AKAN_PUBLIC_*` it inlined, which nothing in the minified bundle names. */
+  static publicEnvPath(app: App) {
+    return path.join(app.dist.cwdPath, ".akan", "artifact", "csr-public-env.json");
+  }
+
+  static async writePublicEnv(app: App, define: Record<string, string>) {
+    const prefix = "process.env.";
+    const publicEnv = Object.fromEntries(
+      Object.entries(define)
+        .filter(([key]) => key.startsWith(`${prefix}AKAN_PUBLIC_`))
+        .map(([key, value]) => [key.slice(prefix.length), JSON.parse(value) as unknown]),
+    );
+    await Bun.write(CsrArtifactBuilder.publicEnvPath(app), `${JSON.stringify(publicEnv, null, 2)}\n`);
+  }
+
   /** The routes one basePath's HTML boots: its own plus every route outside any basePath, matching `bootCsr`. */
   static pageEntriesForBasePath(pageEntries: PageEntry[], basePath: string, basePaths: string[]): PageEntry[] {
     return CsrEntryFiles.pageEntriesForBasePath(pageEntries, basePath, basePaths);