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

package/commandDecorators/argMeta.ts

@@ -41,6 +41,7 @@ export interface ArgsOption<Context = CommandContext> {
   example?: string | number | boolean;
   enum?: EnumChoices | DynamicEnum<Context>;
   ask?: string;
+  multiple?: boolean;
 }
 export interface ArgMeta<Context = CommandContext> {
   name: string;

package/commandDecorators/command.ts

@@ -25,11 +25,15 @@ import { camelToKebabCase } from "./camelToKebabCase";
 import { CommandContainer } from "./dependencyBuilder";
 import { ExitCodeError } from "./exitCodeError";
 import { formatCommandHelp, formatHelp } from "./helpFormatter";
-import { type CommandCls, getTargetCommandNames, getTargetMetas } from "./targetMeta";
+import { type CommandCls, getTargetCommandNames, getTargetMetas, type TargetFailure } from "./targetMeta";
 
 const loggedCliErrorObjects = new WeakSet<object>();
 const loggedCliErrorMessages = new Set<string>();
 
+export const markCliErrorPrinted = (error: unknown) => {
+  if (typeof error === "object" && error !== null) loggedCliErrorObjects.add(error);
+};
+
 const formatCliError = (error: unknown): string => {
   if (error instanceof Error) return error.message || error.name;
   if (typeof error === "string") return error.trim() || "Unknown error";
@@ -65,10 +69,11 @@ const handleOption = (programCommand: Command, argMeta: ArgMeta) => {
   } = argMeta.argsOption;
   const kebabName = camelToKebabCase(argMeta.name);
   const choices = enumChoices && typeof enumChoices !== "function" ? normalizeEnumChoices(enumChoices) : null;
-  programCommand.option(
-    `-${flag}, --${kebabName}${type === "boolean" ? " [boolean]" : ` <${kebabName}>`}`,
-    `${desc}${ask ? ` (${ask})` : ""}${example ? ` (example: ${example})` : ""}${choices ? ` (choices: ${choices.map((choice) => choice.name).join(", ")})` : ""}`,
-  );
+  const flags = `-${flag}, --${kebabName}${type === "boolean" ? " [boolean]" : ` <${kebabName}>`}`;
+  const description = `${desc}${ask ? ` (${ask})` : ""}${example ? ` (example: ${example})` : ""}${choices ? ` (choices: ${choices.map((choice) => choice.name).join(", ")})` : ""}`;
+  if (argMeta.argsOption.multiple)
+    programCommand.option(flags, description, (value: string, previous: string[] = []) => [...previous, value]);
+  else programCommand.option(flags, description);
   if (type === "boolean" && argMeta.argsOption.default === true)
     programCommand.option(`--no-${kebabName}`, `turn off --${kebabName}`);
   return programCommand;
@@ -88,6 +93,19 @@ const convertArgValue = (value: string | boolean, type: "string" | "number" | "b
   else return value === true || value === "true";
 };
 
+const givenOptionsOf = (argMetas: (ArgMeta | InternalArgMeta)[], opt: Record<string, unknown>) => {
+  const given: TargetFailure["given"] = {};
+  for (const argMeta of argMetas) {
+    if (argMeta.type !== "Option" || opt[argMeta.name] === undefined) continue;
+    const type = argMeta.argsOption.type ?? "string";
+    const value = opt[argMeta.name] as string | boolean | string[];
+    given[argMeta.name] = Array.isArray(value)
+      ? value.map((each) => convertArgValue(each, type))
+      : convertArgValue(value, type);
+  }
+  return given;
+};
+
 const normalizeEnumChoices = (enumChoices: EnumChoices) =>
   enumChoices.map((choice: EnumChoice) =>
     typeof choice === "object"
@@ -135,8 +153,13 @@ const inputMessageOf = ({ name, argsOption: { desc, example, ask } }: ArgMeta) =
 export const getOptionValue = async (argMeta: ArgMeta, opt: Record<string, unknown>, context: CommandContext) => {
   const {
     name,
-    argsOption: { enum: enumChoices, default: defaultValue, type, desc, nullable, ask },
+    argsOption: { enum: enumChoices, default: defaultValue, type, desc, nullable, ask, multiple },
   } = argMeta;
+  if (multiple) {
+    const values = (opt[argMeta.name] as string[] | undefined) ?? [];
+    for (const value of values) assertEnumChoice(argMeta, value);
+    return values.map((value) => convertArgValue(value, type ?? "string"));
+  }
   if (opt[argMeta.name] !== undefined) {
     assertEnumChoice(argMeta, opt[argMeta.name]);
     return convertArgValue(opt[argMeta.name] as string, type ?? "string");
@@ -186,20 +209,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"),
   );
 };
@@ -323,6 +347,7 @@ export const getInternalArgumentValue = async (
 
 export const runCommands = async (...commands: CommandCls[]) => {
   let failureExitCode = 1;
+  let reportFailure = async (_error: unknown) => {};
   process.on("unhandledRejection", (error) => {
     printCliError(error);
     process.exit(ExitCodeError.codeOf(error) ?? failureExitCode);
@@ -371,10 +396,20 @@ It may cause unexpected behavior. Run \`akan update\` to update latest akanjs.`,
           hidden: targetMeta.targetOption.devOnly,
         });
         const targetFailureExitCode = targetMeta.targetOption.failureExitCode;
-        //? commander exits 1 on a flag or argument it refuses, before any action runs.
-        if (targetFailureExitCode !== undefined)
-          programCommand.exitOverride((error) => process.exit(error.exitCode === 0 ? 0 : targetFailureExitCode));
+        const usageExitCode = targetMeta.targetOption.usageExitCode ?? targetFailureExitCode;
+        const { onFailure } = targetMeta.targetOption;
         const [allArgMetas] = getArgMetas(command, targetMeta.key);
+        //? commander exits 1 on a flag or argument it refuses, before any action runs, having printed why.
+        //? Thrown, not exited: the failure path below awaits onFailure, and an exit drops what a pipe still buffers.
+        if (usageExitCode !== undefined || onFailure)
+          programCommand.exitOverride((error) => {
+            if (error.exitCode === 0) process.exit(0);
+            const refused = new ExitCodeError(error.message.replace(/^error: /, ""), usageExitCode ?? error.exitCode);
+            markCliErrorPrinted(refused);
+            const given = givenOptionsOf(allArgMetas, programCommand.opts());
+            reportFailure = async (failure) => await onFailure?.(failure, { usage: true, given });
+            throw refused;
+          });
         for (const argMeta of allArgMetas) {
           if (argMeta.type === "Option") programCommand = handleOption(programCommand, argMeta);
           else if (argMeta.type === "Argument") programCommand = handleArgument(programCommand, argMeta);
@@ -407,6 +442,8 @@ It may cause unexpected behavior. Run \`akan update\` to update latest akanjs.`,
           if (!targetMeta.targetOption.stdio) Logger.rawLog();
           const cmdArgs = args.slice(0, args.length - 2);
           const opt = args[args.length - 2] as Record<string, unknown>;
+          reportFailure = async (failure) =>
+            await onFailure?.(failure, { usage: false, given: givenOptionsOf(allArgMetas, opt) });
           const commandArgs = [] as unknown[];
           if (targetMeta.targetOption.runsOnWorkspaceRoot) await assertCurrentDirectoryIsWorkspaceRoot();
           const workspace = WorkspaceExecutor.fromRoot();
@@ -451,8 +488,9 @@ 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) => {
+  await program.parseAsync(process.argv).catch(async (error: unknown) => {
     printCliError(error);
+    await reportFailure(error).catch(printCliError);
     process.exit(ExitCodeError.codeOf(error) ?? failureExitCode);
   });
 };

package/commandDecorators/commandBuilder.ts

@@ -42,7 +42,7 @@ type ArgValue<Type extends PrimitiveArgType, Option> = [EnumValue<Option>] exten
   : EnumValue<Option>;
 type AddArg<Params extends unknown[], Type extends PrimitiveArgType, Option> = [
   ...Params,
-  MaybeNullable<ArgValue<Type, Option>, Option>,
+  Option extends { multiple: true } ? ArgValue<Type, Option>[] : MaybeNullable<ArgValue<Type, Option>, Option>,
 ];
 type AddInternalArg<Params extends unknown[], Token extends InternalArgToken> = [...Params, Token["_value"]];
 type AddInternalArgs<Params extends unknown[], Tokens extends readonly InternalArgToken[]> = Tokens extends readonly [
@@ -79,9 +79,12 @@ const argMetaOf = (
   type: ArgType,
   name: string,
   primitive: PrimitiveArgType,
-  argsOption: object | undefined,
+  argsOption: Pick<ArgsOption, "multiple"> | undefined,
   idx: number,
-): ArgMeta => ({ name, argsOption: { ...argsOption, type: normalizePrimitiveArgType(primitive) }, key: "", idx, type });
+): ArgMeta => {
+  if (type === "Argument" && argsOption?.multiple) throw new Error(`argument '${name}' cannot be multiple`);
+  return { name, argsOption: { ...argsOption, type: normalizePrimitiveArgType(primitive) }, key: "", idx, type };
+};
 
 class TargetBuilder<Deps extends readonly DependencyCls[], Params extends unknown[] = [], Context = object> {
   readonly #args: (ArgMeta | InternalArgMeta)[];

package/commandDecorators/commandDecorators.test.ts

@@ -503,7 +503,7 @@ describe("a Sys that defaults to the only app", () => {
 
 describe("the exit code of a command that failed", () => {
   const track = tempRoots();
-  const run = async (failure: string) => {
+  const run = async (failure: string, { option = "", args = [] as 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");
@@ -511,11 +511,11 @@ describe("the exit code of a command that failed", () => {
     await writeText(
       entry,
       [
-        `import { command, ExitCodeError, runCommands, runner, script } from ${JSON.stringify(path.join(import.meta.dir, "index.ts"))};`,
+        `import { command, ExitCodeError, markCliErrorPrinted, 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 () {',
+        `  verdict: target({ desc: "fails"${option} }).exec(async function () {`,
         `    throw ${failure};`,
         "  }),",
         "})) {}",
@@ -523,9 +523,13 @@ describe("the exit code of a command that failed", () => {
         "",
       ].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 };
+    const proc = Bun.spawn(["bun", entry, "verdict", ...args], { cwd: root, stdout: "pipe", stderr: "pipe" });
+    const [stdout, stderr, code] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+    return { stdout, stderr, code };
   };
 
   test("is the one an ExitCodeError carries, and 1 for any other error", async () => {
@@ -534,4 +538,124 @@ describe("the exit code of a command that failed", () => {
     expect(verdict.code).toBe(2);
     expect((await run('new Error("broke")')).code).toBe(1);
   }, 30_000);
+
+  test("is usageExitCode for a flag commander refuses before the command runs, failureExitCode after", async () => {
+    const option = ", failureExitCode: 4, usageExitCode: 2";
+    expect((await run('new Error("broke")', { option, args: ["--nope"] })).code).toBe(2);
+    expect((await run('new Error("broke")', { option })).code).toBe(4);
+  }, 30_000);
+
+  test("runs onFailure last, told whether commander refused the line and what was given", async () => {
+    const report = [
+      ", stdio: true, usageExitCode: 2, onFailure: async (error, failure) => {",
+      '  const line = JSON.stringify({ message: error.message, ...failure }) + "\\n";',
+      "  await new Promise((resolve) => process.stdout.write(line, resolve));",
+      "}",
+    ].join("\n");
+    const option = `${report} }).option("json", Boolean, { default: false }).option("count", Number, { nullable: true`;
+    const lastOf = (stdout: string) => JSON.parse(stdout.trim().split("\n").at(-1) ?? "null");
+
+    const refused = await run('new Error("broke")', { option, args: ["--count", "3", "--nope", "--json"] });
+    expect(refused.code).toBe(2);
+    expect(refused.stderr).toContain("unknown option '--nope'");
+    expect(lastOf(refused.stdout)).toEqual({
+      message: "unknown option '--nope'",
+      usage: true,
+      given: { count: 3, json: true },
+    });
+
+    const thrown = await run('new Error("broke")', { option, args: ["--json"] });
+    expect(thrown.code).toBe(1);
+    expect(thrown.stdout).toContain("broke\n");
+    expect(lastOf(thrown.stdout)).toEqual({ message: "broke", usage: false, given: { json: true } });
+
+    const help = await run('new Error("broke")', { option, args: ["--help"] });
+    expect(help.code).toBe(0);
+    expect(help.stdout).not.toContain('"usage"');
+  }, 60_000);
+
+  test("prints nothing more for an error the command marked as printed", async () => {
+    const marked = await run(
+      '(() => { const error = new Error("printed already"); markCliErrorPrinted(error); return error; })()',
+    );
+    expect(marked.code).toBe(1);
+    expect(`${marked.stdout}${marked.stderr}`).not.toContain("printed already");
+  }, 30_000);
+});
+
+describe("a repeatable option", () => {
+  const track = tempRoots();
+  const meta: ArgMeta = {
+    name: "param",
+    argsOption: { type: "string", multiple: true },
+    key: "run",
+    idx: 0,
+    type: "Option",
+  };
+  afterEach(() => {
+    CommandContainer.clear();
+  });
+
+  test("reads every value given, in order, each against the choices, and an empty list when left out", async () => {
+    expect(await getOptionValue(meta, { param: ["a=1", "b=2"] }, { values: {} })).toEqual(["a=1", "b=2"]);
+    expect(await getOptionValue(meta, {}, { values: {} })).toEqual([]);
+    const choices = { ...meta, argsOption: { ...meta.argsOption, enum: ["a", "b"] } };
+    await expect(getOptionValue(choices, { param: ["a", "c"] }, { values: {} })).rejects.toThrow(
+      "option '--param' argument 'c' is invalid",
+    );
+  });
+
+  test("types the exec parameter as a list, and a positional argument cannot repeat", () => {
+    const expectType = <Expected>(_value: Expected) => undefined;
+    class RepeatRunner extends runner("repeat") {}
+    class RepeatScript extends script("repeat", [RepeatRunner]) {}
+    class RepeatCommand extends command("repeat", [RepeatScript], ({ public: target }) => ({
+      run: target({ desc: "run" })
+        .option("param", String, { multiple: true })
+        .option("mode", String, { enum: ["a", "b"], multiple: true })
+        .exec(async (param, mode) => {
+          expectType<string[]>(param);
+          expectType<("a" | "b")[]>(mode);
+        }),
+    })) {}
+    expect(getTargetMetas(RepeatCommand)[0]?.key).toBe("run");
+    expect(() =>
+      command("repeatArg", [RepeatScript], ({ public: target }) => ({
+        run: target({ desc: "run" })
+          .arg("names", String, { multiple: true })
+          .exec(async () => undefined),
+      })),
+    ).toThrow("argument 'names' cannot be multiple");
+  });
+
+  test("collects each time the flag is given, long or short", async () => {
+    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, runCommands, runner, script } from ${JSON.stringify(path.join(import.meta.dir, "index.ts"))};`,
+        'class CollectRunner extends runner("collect") {}',
+        'class CollectScript extends script("collect", [CollectRunner]) {}',
+        'class CollectCommand extends command("collect", [CollectScript], ({ public: target }) => ({',
+        '  collect: target({ desc: "collects", stdio: true })',
+        '    .option("param", String, { multiple: true })',
+        "    .exec(async function (param) {",
+        "      process.stdout.write(JSON.stringify(param));",
+        "    }),",
+        "})) {}",
+        "await runCommands(CollectCommand);",
+        "",
+      ].join("\n"),
+    );
+    const collect = async (...args: string[]) => {
+      const proc = Bun.spawn(["bun", entry, "collect", ...args], { cwd: root, stdout: "pipe", stderr: "pipe" });
+      const [stdout] = await Promise.all([new Response(proc.stdout).text(), proc.exited]);
+      return JSON.parse(stdout) as unknown;
+    };
+    expect(await collect("--param", "a=1", "-p", "b=x=y")).toEqual(["a=1", "b=x=y"]);
+    expect(await collect()).toEqual([]);
+  }, 30_000);
 });

package/commandDecorators/helpFormatter.ts

@@ -143,12 +143,13 @@ export const formatCommandHelp = (command: CommandCls, key: string) => {
       const optName = `${flag}--${kebabName}${negation}`;
       const optDesc = opt.desc ?? "";
       const defaultVal = opt.default !== undefined ? chalk.gray(` [default: ${String(opt.default)}]`) : "";
+      const repeatable = opt.multiple ? chalk.gray(" (repeatable)") : "";
       const choices = opt.enum
         ? chalk.gray(
             typeof opt.enum === "function" ? " ([dynamic choices])" : ` (${opt.enum.map(formatChoice).join(", ")})`,
           )
         : "";
-      lines.push(`      ${chalk.green(optName)}      ${chalk.gray(optDesc)}${defaultVal}${choices}`);
+      lines.push(`      ${chalk.green(optName)}      ${chalk.gray(optDesc)}${defaultVal}${choices}${repeatable}`);
     }
     lines.push("");
   }

package/commandDecorators/targetMeta.ts

@@ -44,6 +44,16 @@ export interface TargetOption {
   runsOnWorkspaceRoot?: boolean;
   stdio?: boolean;
   failureExitCode?: number;
+  usageExitCode?: number;
+  /** Runs after the CLI printed a failure and before it exits, so what it writes ends the output. */
+  onFailure?: (error: unknown, failure: TargetFailure) => void | Promise<void>;
+}
+
+export interface TargetFailure {
+  /** commander refused a flag or argument before the command ran, and printed why. */
+  usage: boolean;
+  /** The options given on the command line as the command would receive them, without defaults or prompts. */
+  given: { [name: string]: unknown };
 }
 
 export const Commands = () => {

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");
@@ -312,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";
@@ -328,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 () => {
@@ -359,6 +425,7 @@ describe("Workspace and app executor environment contracts", () => {
       env: "develop",
       portOffset: 7,
       workspaceId: undefined,
+      defaulted: [],
     });
   });
 
@@ -417,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";
@@ -1069,6 +1151,29 @@ describe("scan info construction", () => {
     expect(info.file.dictionary.services.has("auth")).toBe(true);
     expect(info.file.document.scalars.has("money")).toBe(true);
   });
+
+  test("lists script/migration by id with a checksum that ignores line endings and a BOM, and skips tests", async () => {
+    const { root, app } = await createTempApp("migrating");
+    expect(await AppInfo.scanMigrations(app)).toEqual([]);
+    const dir = path.join(root, "apps", "migrating", "script", "migration");
+    await writeText(path.join(dir, "202610211000_ownership.ts"), "export default 1;\r\nexport const a = 2;\r\n");
+    await writeText(path.join(dir, "202609010900_backfill.ts"), "export default 1;\n");
+    await writeText(path.join(dir, "202609010900_backfill.test.ts"), "test;\n");
+    await writeText(path.join(dir, "202609010900_backfill.d.ts"), "export {};\n");
+    await writeText(path.join(dir, "README.md"), "# notes\n");
+    await writeText(path.join(root, "apps", "migrating", "script", "seed.ts"), "export {};\n");
+
+    const scanned = await AppInfo.scanMigrations(app);
+    expect(scanned.map(({ id }) => id)).toEqual(["202609010900_backfill", "202610211000_ownership"]);
+    await writeText(path.join(dir, "202610211000_ownership.ts"), "export default 1;\nexport const a = 2;\n");
+    expect(await AppInfo.scanMigrations(app)).toEqual(scanned);
+    await writeText(path.join(dir, "202610211000_ownership.ts"), "\uFEFFexport default 1;\nexport const a = 2;\n");
+    expect(await AppInfo.scanMigrations(app)).toEqual(scanned);
+    expect(scanned[0]?.checksum).toMatch(/^[0-9a-f]{64}$/);
+
+    await writeText(path.join(dir, "fixOwners.ts"), "export default 1;\n");
+    await expect(AppInfo.scanMigrations(app)).rejects.toThrow("akan create-migration");
+  });
 });
 
 describe("WorkspaceExecutor listing", () => {