@akanjs/devkit 3.1.0-rc.9 → 3.1.0

package/codeAgent/tools/deepSeekWeb.test.ts

@@ -0,0 +1,113 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { DeepSeekWeb } from "./DeepSeekWeb";
+
+interface Received {
+  path: string;
+  body: { query?: string; count?: number; url?: string };
+  auth: string | null;
+}
+
+const received: Received[] = [];
+let answers: Response[] = [];
+let server: ReturnType<typeof Bun.serve>;
+beforeAll(() => {
+  server = Bun.serve({
+    port: 0,
+    fetch: async (request) => {
+      received.push({
+        path: new URL(request.url).pathname,
+        body: (await request.json()) as Received["body"],
+        auth: request.headers.get("authorization"),
+      });
+      return answers.shift() ?? Response.json({ results: [] });
+    },
+  });
+});
+afterAll(() => server.stop(true));
+
+const client = () => new DeepSeekWeb("sk-test", `http://127.0.0.1:${server.port}/v1/tools`);
+const rateLimited = () =>
+  Response.json({ error: { message: "QPS exceeded" } }, { status: 429, headers: { "retry-after": "0.01" } });
+
+describe("DeepSeekWeb", () => {
+  test("search lists each page once, without tracking parameters, with its date and a clipped summary", async () => {
+    answers = [
+      Response.json({
+        results: [
+          {
+            title: "Bun v1.3.13",
+            url: "https://bun.com/blog/bun-v1.3.13?utm_source=x&utm_medium=y&ref=keep",
+            summary: "word ".repeat(400),
+            date: "2026-04-19T16:00:00+00:00",
+          },
+          { title: "Isolate issue", url: "https://github.com/oven-sh/bun/issues/31771#1", snippet: "only a snippet" },
+          { title: "Same issue again", url: "https://github.com/oven-sh/bun/issues/31771", summary: "dup" },
+        ],
+      }),
+    ];
+    const text = await client().search("bun isolate", 5);
+    expect(received.at(-1)).toEqual({
+      path: "/v1/tools/search",
+      body: { query: "bun isolate", count: 5 },
+      auth: "Bearer sk-test",
+    });
+    expect(text).toContain("- Bun v1.3.13\n  https://bun.com/blog/bun-v1.3.13?ref=keep · 2026-04-19\n  word word");
+    expect(text).toContain("- Isolate issue\n  https://github.com/oven-sh/bun/issues/31771\n  only a snippet");
+    expect(text).not.toContain("Same issue again");
+    expect(text.split("\n")[2]?.trim().length).toBe(DeepSeekWeb.summaryChars);
+  });
+
+  test("a query longer than DeepSeek takes is refused before any request is spent", async () => {
+    const before = received.length;
+    await expect(client().search("x".repeat(DeepSeekWeb.maxQueryChars + 1), 5)).rejects.toThrow("shorten the query");
+    expect(received.length).toBe(before);
+  });
+
+  test("search waits out a rate limit, and gives up with DeepSeek's own message after the last attempt", async () => {
+    answers = [rateLimited(), Response.json({ results: [{ title: "t", url: "https://a.com/", summary: "s" }] })];
+    expect(await client().search("q", 1)).toContain("https://a.com/");
+
+    answers = [rateLimited(), rateLimited(), rateLimited()];
+    await expect(client().search("q", 1)).rejects.toThrow("429: QPS exceeded");
+  });
+
+  test("fetch waits only on its quota and hands any other failure straight back", async () => {
+    answers = [rateLimited(), Response.json({ title: "Page", content: "body" })];
+    expect(await client().fetch("https://a.com/")).toEqual({ title: "Page", content: "body" });
+
+    const before = received.length;
+    answers = [Response.json({ error: { message: "downstream timeout" } }, { status: 504 })];
+    await expect(client().fetch("https://a.com/")).rejects.toThrow("504: downstream timeout");
+    expect(received.length).toBe(before + 1);
+  });
+
+  test("fetch hands back Markdown with its blanket escaping undone", async () => {
+    answers = [
+      Response.json({
+        title: "Example",
+        content: "\\#\\# Usage\n\nCall \\`foo\\(1\\)\\` \\- it returns 2\\.\n\nconst re \\= \\/\\\\s\\+\\/\\;",
+      }),
+    ];
+    const page = await client().fetch("https://example.com/usage");
+    expect(received.at(-1)?.body).toEqual({ url: "https://example.com/usage" });
+    expect(page).toEqual({
+      title: "Example",
+      content: "## Usage\n\nCall `foo(1)` - it returns 2.\n\nconst re = /\\s+/;",
+    });
+  });
+
+  test("a page that was never escaped keeps the backslashes it has", () => {
+    const clean = "Match a dot with `a\\.b`. See (the docs), [a link](x) and {a: 1}; done!";
+    expect(DeepSeekWeb.unescape(clean)).toBe(clean);
+  });
+
+  test("the key comes from the model runtime, and never from behind a proxy", async () => {
+    const runtime = (apiKey?: string) =>
+      ({ getAuth: async () => (apiKey ? { auth: { apiKey } } : undefined) }) as unknown as Parameters<
+        typeof DeepSeekWeb.fromRuntime
+      >[0];
+    expect(await DeepSeekWeb.fromRuntime(runtime("sk"), false)).toBeInstanceOf(DeepSeekWeb);
+    expect(await DeepSeekWeb.fromRuntime(runtime("sk"), true)).toBeUndefined();
+    expect(await DeepSeekWeb.fromRuntime(runtime(), false)).toBeUndefined();
+  });
+});

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);
@@ -360,6 +384,8 @@ export const runCommands = async (...commands: CommandCls[]) => {
 Akan CLI version is mismatch with installed package. ${process.env.AKAN_VERSION} (global) vs ${installedAkanPackageJson.version} (akanjs)
 It may cause unexpected behavior. Run \`akan update\` to update latest akanjs.`,
       ),
+      undefined,
+      "error",
     );
   }
 
@@ -372,10 +398,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 +444,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 +490,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,163 @@ 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);
+});
+
+describe("a workspace whose akanjs is not the CLI's version", () => {
+  const track = tempRoots();
+
+  test("hears so on stderr, leaving stdout to what the command prints", 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");
+    await writeText(
+      path.join(root, "node_modules", "akanjs", "package.json"),
+      '{ "name": "akanjs", "version": "0.0.1-older" }\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 PlanRunner extends runner("plan") {}',
+        'class PlanScript extends script("plan", [PlanRunner]) {}',
+        'class PlanCommand extends command("plan", [PlanScript], ({ public: target }) => ({',
+        '  plan: target({ desc: "plans", stdio: true }).exec(async function () {',
+        "    process.stdout.write(JSON.stringify({ phases: 1 }));",
+        "  }),",
+        "})) {}",
+        "await runCommands(PlanCommand);",
+        "",
+      ].join("\n"),
+    );
+    const proc = Bun.spawn(["bun", entry, "plan"], { 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,
+    ]);
+    expect(code).toBe(0);
+    expect(stdout).toBe('{"phases":1}');
+    expect(stderr).toContain("0.0.1-older (akanjs)");
+  }, 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

@@ -429,6 +429,35 @@ describe("Workspace and app executor environment contracts", () => {
     });
   });
 
+  test("reads an explicit env file as Bun's own loader does, leaving inline comments out of the values", async () => {
+    const root = await makeTempRoot();
+    await writeFile(
+      path.join(root, ".env"),
+      [
+        "# the workspace env",
+        "AKAN_PUBLIC_SERVE_DOMAIN=example.com # prod domain",
+        'AKAN_PUBLIC_REPO_NAME="file repo" # note',
+        "AKAN_PUBLIC_ENV=develop#no space needed",
+        "export AKAN_WORKSPACE_ID='ws # kept' # dropped",
+        'AKAN_PUBLIC_APP_NAME="say \\"hi\\"\\nagain" # c',
+        'AKAN_WORKSPACE_ROOT="/unterminated # c',
+        "PORT_OFFSET=7",
+        "",
+      ].join("\r\n"),
+    );
+
+    expect(WorkspaceExecutor.getBaseDevEnv(path.join(root, ".env"))).toEqual({
+      appName: 'say \\"hi\\"\nagain',
+      workspaceRoot: '"/unterminated',
+      repoName: "file repo",
+      serveDomain: "example.com",
+      env: "develop",
+      portOffset: 7,
+      workspaceId: "ws # kept",
+      defaulted: [],
+    });
+  });
+
   test("builds app command environment and prepareCommand artifacts", async () => {
     const root = await makeTempRoot();
     process.env.AKAN_PUBLIC_REPO_NAME = "repo";
@@ -1078,7 +1107,7 @@ describe("PkgExecutor package generation", () => {
     expect(distPackageJson).toMatchObject({
       name: "@sample/tool",
       type: "module",
-      engines: { bun: ">=1.4.0" },
+      engines: { bun: ">=1.4.4" },
       dependencies: { lodash: "4.0.0" },
       devDependencies: { typescript: "6.0.0" },
       peerDependencies: { react: "19.0.0" },
@@ -1151,6 +1180,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/executors.ts

@@ -140,6 +140,14 @@ export const execEmoji = {
   default: "✈️",
 };
 
+//? As Bun's own .env loader reads it (1.4.4), which fills process.env too: `#` ends an unquoted value even mid-word.
+const parseEnvValue = (value: string) => {
+  const [, quote, inner] = value.match(/^(["'`])((?:\\.|(?!\1)[^\\])*)\1/) ?? [];
+  if (!quote) return value.replace(/#.*/, "").trim();
+  if (quote !== '"') return inner;
+  return inner.replace(/\\(.)/g, (pair, char: string) => (char === "n" ? "\n" : char === "r" ? "\r" : pair));
+};
+
 const parseEnvFile = (envPath: string): Record<string, string> => {
   const env: Record<string, string> = {};
   const content = (() => {
@@ -156,11 +164,7 @@ const parseEnvFile = (envPath: string): Record<string, string> => {
     const separatorIndex = normalized.indexOf("=");
     if (separatorIndex <= 0) continue;
     const key = normalized.slice(0, separatorIndex).trim();
-    let value = normalized.slice(separatorIndex + 1).trim();
-    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
-      value = value.slice(1, -1);
-    }
-    env[key] = value;
+    env[key] = parseEnvValue(normalized.slice(separatorIndex + 1).trim());
   }
   return env;
 };
@@ -1640,7 +1644,7 @@ export class PkgExecutor extends Executor {
           default: "./index.ts",
         },
       },
-      engines: { bun: ">=1.4.0" },
+      engines: { bun: ">=1.4.4" },
       ...dependencyMaps,
     };
     await Promise.all([this.dist.writeJson("package.json", distPkgJson), this.writeJson("package.json", distPkgJson)]);