@akanjs/devkit 3.1.0-rc.0 → 3.1.0-rc.10

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");
 };
 
@@ -163,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"),
   );
 };
@@ -205,6 +229,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 +249,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 +260,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 +275,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 +304,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 +326,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 +454,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/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

@@ -99,6 +99,29 @@ describe("Executor filesystem helpers", () => {
     expect(entries.dirs).toContain("nested");
   });
 
+  test("lists a folder in name order, whatever order the filesystem keeps it in", async () => {
+    const root = await makeTempRoot();
+    const exec = new Executor("fixture", root);
+    for (const name of ["summary", "file", "banner", "_noti", "admin"]) await exec.mkdir(`lib/${name}`);
+    for (const name of ["st.ts", "cnst.ts", "dict.ts"]) await exec.writeFile(`lib/${name}`, "");
+
+    expect(await exec.readdir("lib")).toEqual([
+      "_noti",
+      "admin",
+      "banner",
+      "cnst.ts",
+      "dict.ts",
+      "file",
+      "st.ts",
+      "summary",
+    ]);
+    expect(await exec.getFilesAndDirs("lib")).toEqual({
+      files: ["cnst.ts", "dict.ts", "st.ts"],
+      dirs: ["_noti", "admin", "banner", "file", "summary"],
+    });
+    expect(await exec.getAllFiles("**/*", { cwd: exec.getPath("lib") })).toEqual(["cnst.ts", "dict.ts", "st.ts"]);
+  });
+
   test("a refreshed tsconfig re-reads the config it extends", async () => {
     const root = await makeTempRoot();
     const appDir = path.join(root, "apps/demo");
@@ -188,6 +211,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,10 +315,27 @@ 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", () => {
-  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";
@@ -282,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 () => {
@@ -313,6 +425,7 @@ describe("Workspace and app executor environment contracts", () => {
       env: "develop",
       portOffset: 7,
       workspaceId: undefined,
+      defaulted: [],
     });
   });
 
@@ -371,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";