@akanjs/devkit 3.1.0-rc.20 → 3.1.0-rc.22

package/applicationBuildRunner.test.ts

@@ -1,5 +1,5 @@
-import { describe, expect, test } from "bun:test";
-import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { describe, expect, spyOn, test } from "bun:test";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { AkanAppConfig } from "./akanConfig";
@@ -111,6 +111,45 @@ console.info(new SampleService().name);
     }
   });
 
+  test("bakes into the bundles every AKAN_PUBLIC_* its Dockerfile carries, and names the shell values it outranked", async () => {
+    const { root, workspace } = await createTempApp("portal");
+    const keys = ["AKAN_PUBLIC_ENV", "AKAN_PUBLIC_REPO_NAME", "AKAN_PUBLIC_SERVE_DOMAIN"] as const;
+    const shellEnv = Object.fromEntries(keys.map((key) => [key, process.env[key]]));
+    await writeFile(
+      path.join(root, ".env"),
+      "AKAN_PUBLIC_ENV=main\nAKAN_PUBLIC_REPO_NAME=repo\nAKAN_PUBLIC_SERVE_DOMAIN=akanjs.com\n",
+    );
+    await Promise.all(["private", "public"].map((dir) => mkdir(path.join(root, "apps", "portal", dir))));
+    Object.assign(process.env, {
+      AKAN_PUBLIC_ENV: "local",
+      AKAN_PUBLIC_REPO_NAME: "shell-repo",
+      AKAN_PUBLIC_SERVE_DOMAIN: "localhost",
+    });
+    const app = AppExecutor.from(workspace, "portal");
+    const warn = spyOn(app.logger, "warn").mockImplementation(() => undefined);
+    const runner = new ApplicationBuildRunner(app);
+    runner.typecheck = async () => {
+      throw new Error("stopped after prepare");
+    };
+    try {
+      await expect(runner.build()).rejects.toThrow("stopped after prepare");
+      const define = bundleDefine(app, "build", "csr") as { [key: string]: string };
+      const imageEnv = (await app.getConfig()).getProductionEnv();
+      for (const key of keys) expect(define[`process.env.${key}`]).toBe(JSON.stringify(imageEnv[key]));
+      expect(imageEnv.AKAN_PUBLIC_SERVE_DOMAIN).toBe("akanjs.com");
+      expect(warn).toHaveBeenCalledTimes(1);
+      expect(warn.mock.calls[0]?.[0]).toBe(
+        "The workspace .env outranks this process's environment: the bundles and the image take AKAN_PUBLIC_ENV=main (not local), AKAN_PUBLIC_REPO_NAME=repo (not shell-repo), AKAN_PUBLIC_SERVE_DOMAIN=akanjs.com (not localhost).",
+      );
+    } finally {
+      for (const key of keys) {
+        if (shellEnv[key] === undefined) delete process.env[key];
+        else process.env[key] = shellEnv[key];
+      }
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
   test("a build for a real environment stops before any phase when the serve domain is only the local default", async () => {
     const { root, workspace } = await createTempApp("portal");
     await writeFile(path.join(root, ".env"), "AKAN_PUBLIC_REPO_NAME=repo\n");

package/applicationBuildRunner.ts

@@ -18,6 +18,7 @@ import { Spinner } from "./spinner";
 import { createServerEnvPlugin } from "./transforms/serverEnvPlugin";
 import { ServerEnvProfile } from "./transforms/serverEnvProfile";
 import { ProjectTypecheck } from "./typecheck/projectTypecheck";
+import type { BaseDevEnv } from "./types";
 
 export interface TypecheckOptions {
   clean?: boolean;
@@ -97,14 +98,34 @@ export class ApplicationBuildRunner {
     return path.join(this.#app.cwdPath, "env");
   }
 
+  //? Bundles bake AKAN_PUBLIC_* from process.env, where the shell outranks the .env that the server env and the
+  //? Dockerfile read: a page built otherwise drops the image's tokens as foreign or dials another serve domain.
+  #pinImageEnv(baseDevEnv: BaseDevEnv, environment: string) {
+    const imageEnv = {
+      AKAN_PUBLIC_ENV: environment,
+      AKAN_PUBLIC_REPO_NAME: baseDevEnv.repoName,
+      AKAN_PUBLIC_SERVE_DOMAIN: baseDevEnv.serveDomain,
+    };
+    const outranked = Object.entries(imageEnv).filter(([key, value]) => {
+      const given = process.env[key];
+      return !!given && given !== value && !(key === "AKAN_PUBLIC_ENV" && this.#environment);
+    });
+    if (outranked.length)
+      this.#app.logger.warn(
+        `The workspace .env outranks this process's environment: the bundles and the image take ${outranked
+          .map(([key, value]) => `${key}=${value} (not ${process.env[key]})`)
+          .join(", ")}.`,
+      );
+    Object.assign(process.env, imageEnv);
+  }
+
   async build({ spinner = false }: BuildOptions = {}): Promise<BuildResult> {
     // serial build is needed because of Bun.build is unstable for parallel build
     this.#spinner = spinner;
     const { web, assets, baseDevEnv } = await this.#app.getConfig();
     const environment = this.#environment ?? baseDevEnv.env;
     WorkspaceExecutor.assertDeployableEnv(baseDevEnv, environment, "akan build");
-    //? Bundles bake AKAN_PUBLIC_ENV from process.env, where the shell outranks the .env that picked the server env.
-    process.env.AKAN_PUBLIC_ENV = environment;
+    this.#pinImageEnv(baseDevEnv, environment);
     //? Before any phase: a profile that would ship a secret stops the build, not the image after it.
     if (this.#profile)
       await ServerEnvProfile.assertShippable({ envDir: this.#envDir, environment, profile: this.#profile });

package/artifact/implicitRootLayout.test.ts

@@ -36,7 +36,9 @@ describe("resolveSsrPageEntries", () => {
     const generatedSource = await Bun.file(groupedRoot?.moduleAbsPath ?? "").text();
     // Both user modules go through the route resolver, so a `rootLayout()` chain and the legacy exports read alike.
     expect(generatedSource).toContain('import * as inheritedModule from "../../../page/_layout.tsx";');
-    expect(generatedSource).toContain("const inheritedLayout = resolveRouteModule(inheritedModule as never");
+    expect(generatedSource).toContain(
+      'const inheritedLayout = assertGuardOnChain("page/_layout.tsx", resolveRouteModule(inheritedModule as never',
+    );
     expect(generatedSource).not.toContain("<System.Provider");
     expect(generatedSource).toContain("export async function generateHead(props: PageProps)");
     // The ancestor root is a level of the route tree, which merges its head; this boundary returns only its own.
@@ -48,6 +50,9 @@ describe("resolveSsrPageEntries", () => {
     expect(generatedSource).toContain("export const pageConfig = userLayout.pageConfig ?? inheritedLayout.pageConfig;");
     // The ancestor root is its own level of the stack, so inheriting its loading would nest it inside itself.
     expect(generatedSource).toContain("export const Loading = userLayout.Loading;");
+    // Its guard runs from that level too, ahead of this one, and an MCP view takes its providers from there.
+    expect(generatedSource).toContain("export const guard = userLayout.guard;");
+    expect(generatedSource).not.toContain("McpAppRoot");
     expect(generatedSource).toContain(
       "<UserLayout params={params} searchParams={searchParams}>{children}</UserLayout>",
     );
@@ -77,6 +82,11 @@ describe("resolveSsrPageEntries", () => {
     expect(generatedSource).toContain("export const viewport = userLayout.viewport ?? inheritedLayout.viewport;");
     expect(generatedSource).toContain("viewport={viewport}");
     expect(generatedSource).toContain("[inheritedLayout, userLayout].map((layout)");
+    expect(generatedSource).toContain(
+      "export const guard = RouteGuards.compose(inheritedLayout.guard, userLayout.guard);",
+    );
+    expect(generatedSource).toContain("export function McpAppRoot({ children, params, path }: McpAppRootProps) {");
+    expect(generatedSource).toContain("<System.App");
     expect(generatedSource).toContain('import { allDictionary } from "../dict/useDict.ts";');
     expect(generatedSource).toContain(
       'allDictionary={process.env.AKAN_PUBLIC_RENDER_ENV === "ssr" ? allDictionary : undefined}',

package/artifact/implicitRootLayout.ts

@@ -16,8 +16,11 @@ const IMPLICIT_DICT_DIR = path.join(".akan", "generated", "dict");
 const IMPLICIT_OVERRIDES_DIR = path.join(".akan", "generated", "overrides");
 const OVERRIDES_KEY_RE = /^\.\/(.+\/)?_overrides\.(tsx|ts|jsx|js)$/;
 
+const posixRelative = (fromDir: string, toAbsPath: string) =>
+  path.relative(fromDir, toAbsPath).split(path.sep).join("/");
+
 const importSpecifier = (fromAbsPath: string, toAbsPath: string) => {
-  const rel = path.relative(path.dirname(fromAbsPath), toAbsPath).split(path.sep).join("/");
+  const rel = posixRelative(path.dirname(fromAbsPath), toAbsPath);
   return rel.startsWith(".") ? rel : `./${rel}`;
 };
 
@@ -162,14 +165,14 @@ async function writeGeneratedRootLayoutFile(opts: {
     ? `import { st } from "@apps/${opts.appName}/client";\nvoid st;\n`
     : `import "@apps/${opts.appName}/client";\n`;
   //? resolveRouteModule reads a rootLayout() chain and the legacy named exports alike.
-  const inheritedLabel = inheritedSourceAbsPath ? path.relative(opts.appCwdPath, inheritedSourceAbsPath) : "";
+  const inheritedLabel = inheritedSourceAbsPath ? posixRelative(opts.appCwdPath, inheritedSourceAbsPath) : "";
   const inheritedImport = inheritedSourceSpecifier
-    ? `import * as inheritedModule from ${JSON.stringify(inheritedSourceSpecifier)};\nconst inheritedLayout = resolveRouteModule(inheritedModule as never, ${JSON.stringify(inheritedLabel)}).module as LayoutModule;\n`
+    ? `import * as inheritedModule from ${JSON.stringify(inheritedSourceSpecifier)};\nconst inheritedLayout = assertGuardOnChain(${JSON.stringify(inheritedLabel)}, resolveRouteModule(inheritedModule as never, ${JSON.stringify(inheritedLabel)})).module as LayoutModule;\n`
     : "const inheritedLayout: LayoutModule = {};\n";
   const prefix = opts.boundary.segments.find((segment) => !/^\(.+\)$/.test(segment)) ?? null;
-  const userLabel = opts.boundary.sourceAbsPath ? path.relative(opts.appCwdPath, opts.boundary.sourceAbsPath) : "";
+  const userLabel = opts.boundary.sourceAbsPath ? posixRelative(opts.appCwdPath, opts.boundary.sourceAbsPath) : "";
   const userImport = sourceSpecifier
-    ? `import * as userModule from ${JSON.stringify(sourceSpecifier)};\nconst userLayout = resolveRouteModule(userModule as never, ${JSON.stringify(userLabel)}).module as LayoutModule;\nconst UserLayout = userLayout.default as (props: LayoutProps) => ReactNode | Promise<ReactNode>;\n`
+    ? `import * as userModule from ${JSON.stringify(sourceSpecifier)};\nconst userLayout = assertGuardOnChain(${JSON.stringify(userLabel)}, resolveRouteModule(userModule as never, ${JSON.stringify(userLabel)})).module as LayoutModule;\nconst UserLayout = userLayout.default as (props: LayoutProps) => ReactNode | Promise<ReactNode>;\n`
     : "const UserLayout = ({ children }: LayoutProps) => children;\nconst userLayout: LayoutModule = {};\n";
   const isAsyncUserLayout = opts.boundary.sourceAbsPath
     ? await AsyncDefaultExportDetector.detect(opts.boundary.sourceAbsPath)
@@ -191,6 +194,10 @@ async function writeGeneratedRootLayoutFile(opts: {
   const layoutReturn = isAsyncUserLayout ? "layout" : userLayoutElement;
   //? Under an ancestor root boundary the route tree merges that root's head itself; merging it here would repeat it.
   const headLayouts = opts.includeSystemProvider ? "[inheritedLayout, userLayout]" : "[userLayout]";
+  //? Likewise for the guard: an ancestor root boundary runs its own from its own layer.
+  const guardExport = opts.includeSystemProvider
+    ? "export const guard = RouteGuards.compose(inheritedLayout.guard, userLayout.guard);"
+    : "export const guard = userLayout.guard;";
   const layoutExports = `export async function generateHead(props: PageProps) {
   const heads = await Promise.all(
     ${headLayouts}.map((layout) => (layout.generateHead ? layout.generateHead(props) : layout.head)),
@@ -202,14 +209,16 @@ export const NotFound = userLayout.NotFound ?? inheritedLayout.NotFound;
 export const Error = userLayout.Error ?? inheritedLayout.Error;
 export const pageConfig = userLayout.pageConfig ?? inheritedLayout.pageConfig;
 export const Loading = userLayout.Loading;
+${guardExport}
 
 ${layoutSignature}({ children, params, searchParams }: LayoutProps) {
 ${layoutBinding}  return `;
   const source = opts.includeSystemProvider
     ? `import type { LayoutModule, LayoutProps, PageProps } from "akanjs/client";
-import { loadFonts, resolveRouteModule, RouteHead } from "akanjs/client";
+import { assertGuardOnChain, loadFonts, RouteGuards, resolveRouteModule, RouteHead } from "akanjs/client";
 import type { ReactNode } from "react";
 import { System } from "akanjs/ui";
+import type { McpAppRootProps } from "akanjs/webkit";
 import { env } from "@apps/${opts.appName}/env/env.client";
 import { allDictionary } from ${JSON.stringify(dictMacroSpecifier)};
 ${clientImport}${inheritedImport}${userImport}
@@ -242,9 +251,25 @@ ${layoutExports}(
     </System.Provider>
   );
 }
+
+export function McpAppRoot({ children, params, path }: McpAppRootProps) {
+  return (
+    <System.App
+      params={params}
+      path={path}
+      env={env}
+      theme={theme}
+      viewport={viewport}
+      fonts={loadFonts(userFonts)}
+      className={defaultFontClassName}
+    >
+      {children}
+    </System.App>
+  );
+}
 `
     : `import type { LayoutModule, LayoutProps, PageProps } from "akanjs/client";
-import { resolveRouteModule, RouteHead } from "akanjs/client";
+import { assertGuardOnChain, resolveRouteModule, RouteHead } from "akanjs/client";
 import type { ReactNode } from "react";
 ${inheritedImport}${userImport}
 ${layoutExports}${layoutReturn};

package/biome.base.json

@@ -128,7 +128,8 @@
         "!**/*.constant.ts",
         "!**/common/**",
         "!**/env/**",
-        "!{apps,libs}/*/native/**"
+        "!{apps,libs}/*/native/**",
+        "!apps/*/script/migration/**"
       ],
       "plugins": ["./node_modules/@akanjs/devkit/lint/no-throw-raw-error.grit"]
     },
@@ -195,7 +196,10 @@
     },
     {
       "includes": ["{apps,libs}/**/*.tsx", "!**/*.test.tsx", "!**/*.spec.tsx"],
-      "plugins": ["./node_modules/@akanjs/devkit/lint/no-unpublished-form-setter.grit"]
+      "plugins": [
+        "./node_modules/@akanjs/devkit/lint/no-unpublished-form-setter.grit",
+        "./node_modules/@akanjs/devkit/lint/no-conditional-st-hook.grit"
+      ]
     },
     {
       "includes": [

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");
@@ -324,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);
@@ -372,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);
@@ -408,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();
@@ -452,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/executors.test.ts

@@ -1151,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", () => {