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

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"]
     },

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.1.0-rc.20",
+  "version": "3.1.0-rc.21",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -48,7 +48,7 @@
     "@earendil-works/pi-tui": "1.3.0",
     "@inquirer/prompts": "^8.7.3",
     "@tailwindcss/node": "^4.3.3",
-    "akanjs": "3.1.0-rc.20",
+    "akanjs": "3.1.0-rc.21",
     "chalk": "^6.0.1",
     "commander": "^15.0.0",
     "dayjs": "^1.11.23",

package/scanInfo.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import path from "node:path";
 import type {
   AppConfigResult,
@@ -295,11 +296,19 @@ class ScanInfo {
 }
 
 export const isAkanFrameworkDependency = (dep: string) => dep === "akanjs" || dep.startsWith("akanjs/");
+export interface MigrationScanEntry {
+  id: string;
+  checksum: string;
+}
+
 export class AppInfo extends ScanInfo {
+  static readonly migrationDir = "script/migration";
+  static readonly #migrationIdRe = /^\d{12}_[A-Za-z][A-Za-z0-9]*$/;
   readonly type = "app";
   readonly exec: AppExecutor;
   readonly akanConfig: AppConfigResult;
   readonly libDeps: string[];
+  readonly migrations: MigrationScanEntry[];
 
   static appInfos = new Map<string, AppInfo>();
   static async fromExecutor(exec: AppExecutor, options: { refresh?: boolean } = {}) {
@@ -314,17 +323,21 @@ export class AppInfo extends ScanInfo {
         LibInfo.libInfos.set(libName, await LibInfo.fromExecutor(libExecutor));
       }),
     );
-    const libDeps = await AppInfo.#getAllLibDeps(exec, scanResult.libDeps);
-    const appInfo = new AppInfo(exec, scanResult as AppScanResult, libDeps);
+    const [libDeps, migrations] = await Promise.all([
+      AppInfo.#getAllLibDeps(exec, scanResult.libDeps),
+      AppInfo.scanMigrations(exec),
+    ]);
+    const appInfo = new AppInfo(exec, scanResult as AppScanResult, libDeps, migrations);
     AppInfo.appInfos.set(exec.name, appInfo);
     return appInfo;
   }
 
-  constructor(exec: AppExecutor, scanResult: AppScanResult, libDeps: string[]) {
+  constructor(exec: AppExecutor, scanResult: AppScanResult, libDeps: string[], migrations: MigrationScanEntry[] = []) {
     super(scanResult);
     this.exec = exec;
     this.akanConfig = scanResult.akanConfig;
     this.libDeps = libDeps;
+    this.migrations = migrations;
   }
   override getScanResult(): AppScanResult {
     return this.scanResult as AppScanResult;
@@ -334,6 +347,26 @@ export class AppInfo extends ScanInfo {
     (this.scanResult as AppScanResult).routes = routes;
   }
 
+  //* Line endings and a BOM dropped: an editor or autocrlf would otherwise record another checksum for the same script.
+  static async scanMigrations(exec: AppExecutor) {
+    const files = (await exec.readdir(AppInfo.migrationDir)).filter(
+      (file) => file.endsWith(".ts") && !/\.(test|spec|d)\.ts$/.test(file),
+    );
+    return await Promise.all(
+      files.map(async (file) => {
+        const id = file.slice(0, -".ts".length);
+        if (!AppInfo.#migrationIdRe.test(id))
+          throw new Error(
+            `${AppInfo.migrationDir}/${file}: a migration is named <yyyyMMddHHmm>_<camelName>.ts; create one with \`akan create-migration\``,
+          );
+        const source = (await exec.readFile(`${AppInfo.migrationDir}/${file}`))
+          .replace(/^\uFEFF/, "")
+          .replaceAll("\r\n", "\n");
+        return { id, checksum: createHash("sha256").update(source).digest("hex") };
+      }),
+    );
+  }
+
   static async #getAllLibDeps(exec: AppExecutor, libDeps: string[], libSet = new Set<string>()) {
     await Promise.all(
       libDeps.map(async (libName) => {