@akanjs/devkit 3.0.0-alpha.11 → 3.0.0-alpha.110

package/codegenLock.test.ts

@@ -0,0 +1,137 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtemp, readFile, rm, stat, utimes, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { CodegenLock } from "./codegenLock";
+
+const roots: string[] = [];
+const makeRoot = async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "akan-codegen-lock-"));
+  roots.push(root);
+  return root;
+};
+const seedHolder = async (root: string, holder: unknown) => {
+  const lockPath = CodegenLock.pathIn(root);
+  await Bun.write(lockPath, typeof holder === "string" ? holder : JSON.stringify(holder));
+  return lockPath;
+};
+/** A pid that cannot be alive: `kill(0)` on it is ESRCH on every platform this runs on. */
+const deadPid = 0x7ffffff;
+
+afterEach(async () => {
+  for (const root of roots.splice(0)) await rm(root, { recursive: true, force: true });
+});
+
+describe("CodegenLock", () => {
+  test("serializes concurrent callers in the same process", async () => {
+    const root = await makeRoot();
+    const order: string[] = [];
+    const body = async (name: string) => {
+      order.push(`${name}:in`);
+      await Bun.sleep(20);
+      order.push(`${name}:out`);
+    };
+    await Promise.all([
+      CodegenLock.run(root, "a", () => body("a")),
+      CodegenLock.run(root, "b", () => body("b")),
+      CodegenLock.run(root, "c", () => body("c")),
+    ]);
+    for (const name of ["a", "b", "c"]) {
+      const enter = order.indexOf(`${name}:in`);
+      const leave = order.indexOf(`${name}:out`);
+      expect(leave).toBe(enter + 1);
+    }
+  });
+
+  test("releases the lock file even when the body throws", async () => {
+    const root = await makeRoot();
+    const lockPath = CodegenLock.pathIn(root);
+    await expect(
+      CodegenLock.run(root, "boom", async () => {
+        expect(await Bun.file(lockPath).exists()).toBe(true);
+        throw new Error("boom");
+      }),
+    ).rejects.toThrow("boom");
+    expect(await Bun.file(lockPath).exists()).toBe(false);
+  });
+
+  test("writes a holder naming this process", async () => {
+    const root = await makeRoot();
+    const lockPath = CodegenLock.pathIn(root);
+    const holder = await CodegenLock.run(root, "scan:minimal", async () => await readFile(lockPath, "utf8"));
+    expect(JSON.parse(holder)).toMatchObject({ pid: process.pid, label: "scan:minimal" });
+  });
+
+  test("reclaims a lock whose holder is gone", async () => {
+    const root = await makeRoot();
+    const lockPath = await seedHolder(root, { pid: deadPid, at: Date.now(), label: "crashed" });
+    const started = Date.now();
+    const holder = await CodegenLock.run(root, "next", async () => await readFile(lockPath, "utf8"));
+    expect(JSON.parse(holder).pid).toBe(process.pid);
+    expect(Date.now() - started).toBeLessThan(CodegenLock.waitTimeoutMs);
+  });
+
+  test("respects a live holder until the wait expires, then proceeds without the lock", async () => {
+    const root = await makeRoot();
+    const lockPath = await seedHolder(root, { pid: process.pid, at: Date.now(), label: "other-session" });
+    const waitTimeoutMs = CodegenLock.waitTimeoutMs;
+    Object.defineProperty(CodegenLock, "waitTimeoutMs", { value: 150, configurable: true });
+    try {
+      let ran = false;
+      await CodegenLock.run(root, "blocked", async () => {
+        ran = true;
+        // The foreign holder is left in place: nothing may delete a lock it does not hold.
+        expect(JSON.parse(await readFile(lockPath, "utf8")).label).toBe("other-session");
+      });
+      expect(ran).toBe(true);
+      expect(await Bun.file(lockPath).exists()).toBe(true);
+    } finally {
+      Object.defineProperty(CodegenLock, "waitTimeoutMs", { value: waitTimeoutMs, configurable: true });
+    }
+  });
+
+  test("keeps a young unreadable lock but reclaims a stale one", async () => {
+    const young = await makeRoot();
+    await seedHolder(young, "");
+    const waitTimeoutMs = CodegenLock.waitTimeoutMs;
+    Object.defineProperty(CodegenLock, "waitTimeoutMs", { value: 150, configurable: true });
+    try {
+      await CodegenLock.run(young, "young", async () => undefined);
+      expect(await Bun.file(CodegenLock.pathIn(young)).exists()).toBe(true);
+    } finally {
+      Object.defineProperty(CodegenLock, "waitTimeoutMs", { value: waitTimeoutMs, configurable: true });
+    }
+
+    const stale = await makeRoot();
+    const stalePath = await seedHolder(stale, "");
+    const aged = new Date(Date.now() - CodegenLock.unknownHolderStaleMs - 1_000);
+    await utimes(stalePath, aged, aged);
+    const holder = await CodegenLock.run(stale, "stale", async () => await readFile(stalePath, "utf8"));
+    expect(JSON.parse(holder).pid).toBe(process.pid);
+  });
+
+  test("blocks a second process for as long as it holds the lock", async () => {
+    const root = await makeRoot();
+    const lockPath = CodegenLock.pathIn(root);
+    const script = path.join(root, "holder.ts");
+    await writeFile(
+      script,
+      `import { CodegenLock } from ${JSON.stringify(path.resolve(import.meta.dir, "codegenLock.ts"))};
+await CodegenLock.run(${JSON.stringify(root)}, "child", async () => {
+  process.stdout.write("held\\n");
+  await Bun.sleep(400);
+});
+`,
+    );
+    const child = Bun.spawn(["bun", script], { stdio: ["ignore", "pipe", "inherit"] });
+    const reader = child.stdout.getReader();
+    await reader.read();
+    reader.releaseLock();
+
+    const started = Date.now();
+    await CodegenLock.run(root, "parent", async () => undefined);
+    expect(Date.now() - started).toBeGreaterThan(100);
+    await child.exited;
+    expect(await stat(lockPath).catch(() => null)).toBeNull();
+  });
+});

package/codegenLock.ts

@@ -0,0 +1,136 @@
+import { mkdir, open, readFile, rm, stat } from "node:fs/promises";
+import path from "node:path";
+import { Logger } from "akanjs/common";
+
+interface LockHolder {
+  pid: number;
+  at: number;
+  label: string;
+}
+
+/**
+ * A workspace-wide mutex over the generated source files every dev server in the workspace rewrites.
+ *
+ * `WatchRootResolver` narrows each dev server to its own app and its own lib dependencies, but two apps
+ * that share a lib still both watch it, so a save there reaches both builders and both regenerate the
+ * same barrel. Whichever watcher is mid-scan then reads a half-written file back as a user edit, which is
+ * a rebuild per rewrite. `scanSync` writes the same files at boot for every mounting app.
+ *
+ * A wait that expires proceeds *without* the lock rather than failing: this sits on the dev server's
+ * hot path, and stalling the file watcher is worse than the torn read `FileSys.writeTextAtomic` already
+ * prevents on its own.
+ */
+export class CodegenLock {
+  static readonly fileName = "codegen.lock";
+  static readonly waitTimeoutMs = 10_000;
+  /**
+   * How long an unreadable lock file is respected. It covers the window between the exclusive create
+   * and the holder write, where the file exists but names no pid yet — a young one is somebody else
+   * mid-acquire, not a corpse.
+   */
+  static readonly unknownHolderStaleMs = 60_000;
+  static readonly #pollMs = 25;
+  static readonly #logger = new Logger("CodegenLock");
+  /** Serializes callers inside this process, which one `O_EXCL` file cannot tell apart. */
+  static #queue: Promise<void> = Promise.resolve();
+
+  static pathIn(workspaceRoot: string) {
+    return path.join(workspaceRoot, "local", ".akan", CodegenLock.fileName);
+  }
+
+  static async run<T>(workspaceRoot: string, label: string, fn: () => Promise<T>): Promise<T> {
+    const ahead = CodegenLock.#queue;
+    let done!: () => void;
+    CodegenLock.#queue = new Promise<void>((resolve) => {
+      done = resolve;
+    });
+    try {
+      await CodegenLock.#waitForQueue(ahead, label);
+      return await CodegenLock.#withFileLock(workspaceRoot, label, fn);
+    } finally {
+      done();
+    }
+  }
+
+  static async #waitForQueue(ahead: Promise<void>, label: string) {
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    const expired = new Promise<"expired">((resolve) => {
+      timer = setTimeout(() => resolve("expired"), CodegenLock.waitTimeoutMs);
+    });
+    try {
+      if ((await Promise.race([ahead.then(() => "done" as const), expired])) === "expired")
+        CodegenLock.#logger.warn(
+          `codegen lock queued past ${CodegenLock.waitTimeoutMs}ms in this process; continuing without waiting (${label})`,
+        );
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+
+  static async #withFileLock<T>(workspaceRoot: string, label: string, fn: () => Promise<T>): Promise<T> {
+    const lockPath = CodegenLock.pathIn(workspaceRoot);
+    await mkdir(path.dirname(lockPath), { recursive: true }).catch(() => undefined);
+    const held = await CodegenLock.#acquire(lockPath, label);
+    try {
+      return await fn();
+    } finally {
+      if (held) await rm(lockPath, { force: true }).catch(() => undefined);
+    }
+  }
+
+  static async #acquire(lockPath: string, label: string): Promise<boolean> {
+    const deadline = Date.now() + CodegenLock.waitTimeoutMs;
+    for (;;) {
+      const handle = await open(lockPath, "wx").catch(() => null);
+      if (handle) {
+        await handle
+          .writeFile(JSON.stringify({ pid: process.pid, at: Date.now(), label } satisfies LockHolder))
+          .catch(() => undefined);
+        await handle.close().catch(() => undefined);
+        return true;
+      }
+      if (await CodegenLock.#reclaimIfAbandoned(lockPath)) continue;
+      if (Date.now() >= deadline) {
+        CodegenLock.#logger.warn(
+          `codegen lock at ${lockPath} held past ${CodegenLock.waitTimeoutMs}ms; continuing without it (${label})`,
+        );
+        return false;
+      }
+      await Bun.sleep(CodegenLock.#pollMs);
+    }
+  }
+
+  /** A live holder is never reclaimed — the wait timeout is what bounds a pathologically slow one. */
+  static async #reclaimIfAbandoned(lockPath: string): Promise<boolean> {
+    const info = await stat(lockPath).catch(() => null);
+    if (!info) return true;
+    const holder = CodegenLock.#parseHolder(await readFile(lockPath, "utf8").catch(() => ""));
+    if (holder) {
+      if (CodegenLock.#isAlive(holder.pid)) return false;
+    } else if (Date.now() - info.mtimeMs < CodegenLock.unknownHolderStaleMs) return false;
+    await rm(lockPath, { force: true }).catch(() => undefined);
+    return true;
+  }
+
+  static #parseHolder(raw: string): LockHolder | null {
+    try {
+      const parsed = JSON.parse(raw) as Partial<LockHolder>;
+      if (typeof parsed.pid !== "number" || typeof parsed.at !== "number") return null;
+      return { pid: parsed.pid, at: parsed.at, label: typeof parsed.label === "string" ? parsed.label : "" };
+    } catch {
+      // A truncated holder file names no pid, so it is aged by mtime instead.
+      return null;
+    }
+  }
+
+  static #isAlive(pid: number): boolean {
+    if (!Number.isInteger(pid) || pid <= 0) return false;
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch (error) {
+      // EPERM is a pid that exists under another user, which still holds the lock.
+      return (error as NodeJS.ErrnoException).code === "EPERM";
+    }
+  }
+}

package/commandDecorators/argMeta.ts

@@ -12,7 +12,7 @@ import { COMMAND_META, type CommandCls } from "./targetMeta";
 export const argTypes = ["Argument", "Option"] as const;
 export type ArgType = (typeof argTypes)[number];
 
-export const internalArgTypes = ["Workspace", "App", "Lib", "Sys", "Pkg", "Module", "Exec"] as const;
+export const internalArgTypes = ["Workspace", "App", "Apps", "Lib", "Sys", "Pkg", "Module", "Exec"] as const;
 export type InternalArgType = (typeof internalArgTypes)[number];
 
 export type PrimitiveArgType = StringConstructor | NumberConstructor | BooleanConstructor;
@@ -83,6 +83,14 @@ export const normalizePrimitiveArgType = (type: PrimitiveArgType): NormalizedPri
 export const App = createInternalArgToken<AppExecutor, "App">("App");
 export type App = AppExecutor;
 
+/**
+ * One or more apps, from a variadic positional (`akan start a b`, `akan start a,b`, `akan start all`)
+ * or a checkbox when none is named. Reach for it only where running several is meaningful — every other
+ * command takes `App`, whose single-select is unchanged.
+ */
+export const Apps = createInternalArgToken<AppExecutor[], "Apps">("Apps");
+export type Apps = AppExecutor[];
+
 export const Lib = createInternalArgToken<LibExecutor, "Lib">("Lib");
 export type Lib = LibExecutor;
 

package/commandDecorators/command.ts

@@ -1,8 +1,14 @@
 import path from "node:path";
-import type { confirm as inquirerConfirm, input as inquirerInput, select as inquirerSelect } from "@inquirer/prompts";
+import type {
+  checkbox as inquirerCheckbox,
+  confirm as inquirerConfirm,
+  input as inquirerInput,
+  select as inquirerSelect,
+} from "@inquirer/prompts";
 import { Logger } from "akanjs/common";
 import chalk from "chalk";
 import { type Command, program } from "commander";
+import { AppSelectionMemory } from "../appSelectionMemory";
 import { AppExecutor, Executor, LibExecutor, ModuleExecutor, PkgExecutor, WorkspaceExecutor } from "../executors";
 // Import the owning modules directly, never the root barrel: `..` re-exports all 41 devkit modules,
 // so a barrel import here drags ink, @trapezedev/project, ssh2, @langchain/* and the cloud stack into
@@ -103,6 +109,27 @@ const prompts = async () => await import("@inquirer/prompts");
 const select = ((config, context) => prompts().then((m) => m.select(config, context))) as typeof inquirerSelect;
 const confirm = ((config, context) => prompts().then((m) => m.confirm(config, context))) as typeof inquirerConfirm;
 const input = ((config, context) => prompts().then((m) => m.input(config, context))) as typeof inquirerInput;
+const checkbox = ((config, context) => prompts().then((m) => m.checkbox(config, context))) as typeof inquirerCheckbox;
+
+/**
+ * Rejects a value that is not one of the declared choices, in commander's own wording.
+ *
+ * Only a static choice list can be checked: a `DynamicEnum` resolves against the command context, which
+ * is not populated until the internal args are resolved, and it is the interactive `select` that consumes
+ * it. Comparison is stringly on purpose — the value still carries commander's raw string here, while a
+ * numeric choice list holds numbers.
+ */
+const assertEnumChoice = (argMeta: ArgMeta, value: unknown) => {
+  const enumChoices = argMeta.argsOption.enum;
+  if (!enumChoices || typeof enumChoices === "function") return;
+  const choices = normalizeEnumChoices(enumChoices);
+  if (choices.some((choice) => String(choice.value) === String(value))) return;
+  const label =
+    argMeta.type === "Option" ? `option '--${camelToKebabCase(argMeta.name)}'` : `argument '${argMeta.name}'`;
+  throw new Error(
+    `${label} argument '${String(value)}' is invalid. Allowed choices are ${choices.map((choice) => choice.name).join(", ")}.`,
+  );
+};
 
 const resolveEnumChoices = async (argMeta: ArgMeta, context: CommandContext) => {
   const enumChoices = argMeta.argsOption.enum;
@@ -111,13 +138,15 @@ const resolveEnumChoices = async (argMeta: ArgMeta, context: CommandContext) =>
   return enumChoices;
 };
 
-const getOptionValue = async (argMeta: ArgMeta, opt: Record<string, unknown>, context: CommandContext) => {
+export const getOptionValue = async (argMeta: ArgMeta, opt: Record<string, unknown>, context: CommandContext) => {
   const {
     name,
     argsOption: { enum: enumChoices, default: defaultValue, type, desc, nullable, example, ask },
   } = argMeta;
-  if (opt[argMeta.name] !== undefined) return convertArgValue(opt[argMeta.name] as string, type ?? "string");
-  else if (defaultValue !== undefined) return defaultValue;
+  if (opt[argMeta.name] !== undefined) {
+    assertEnumChoice(argMeta, opt[argMeta.name]);
+    return convertArgValue(opt[argMeta.name] as string, type ?? "string");
+  } else if (defaultValue !== undefined) return defaultValue;
 
   if (enumChoices) {
     const choices = normalizeEnumChoices((await resolveEnumChoices(argMeta, context)) ?? []);
@@ -139,13 +168,15 @@ const getOptionValue = async (argMeta: ArgMeta, opt: Record<string, unknown>, co
   }
 };
 
-const getArgumentValue = async (argMeta: ArgMeta, value: string | undefined) => {
+export const getArgumentValue = async (argMeta: ArgMeta, value: string | undefined) => {
   const {
     name,
     argsOption: { default: defaultValue, type, desc, nullable, example, ask },
   } = argMeta;
-  if (value !== undefined) return convertArgValue(value, type ?? "string");
-  else if (defaultValue !== undefined) return defaultValue;
+  if (value !== undefined) {
+    assertEnumChoice(argMeta, value);
+    return convertArgValue(value, type ?? "string");
+  } else if (defaultValue !== undefined) return defaultValue;
   else if (nullable) return null;
 
   const message = ask
@@ -184,6 +215,46 @@ const assertCurrentDirectoryIsWorkspaceRoot = async () => {
   );
 };
 
+/** A variadic positional arrives as an array, and each entry may itself be a comma-separated list. */
+const parseAppNameList = (value: string | string[] | undefined): string[] =>
+  (Array.isArray(value) ? value : value === undefined ? [] : [value])
+    .flatMap((entry) => entry.split(","))
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+
+/**
+ * The `Apps` token: named apps, `all`, or a checkbox when the command line names none. Kept out of
+ * `getInternalArgumentValue` because it is the only internal arg whose positional is variadic, so it is
+ * the only one whose raw value is an array.
+ */
+export const getAppsArgumentValue = async (
+  value: string | string[] | undefined,
+  workspace: WorkspaceExecutor,
+): Promise<AppExecutor[]> => {
+  const appNames = await workspace.getApps();
+  if (appNames.length === 0) throw new Error("No apps found in this workspace (apps/<appName>/akan.config.ts)");
+  const requested = parseAppNameList(value);
+  if (requested.includes("all")) return appNames.map((name) => AppExecutor.from(workspace, name));
+  if (requested.length) {
+    const unknown = requested.filter((name) => !appNames.includes(name));
+    if (unknown.length)
+      throw new Error(
+        `Unknown app${unknown.length > 1 ? "s" : ""}: ${unknown.join(", ")}. Available: ${appNames.join(", ")}, all`,
+      );
+    return [...new Set(requested)].map((name) => AppExecutor.from(workspace, name));
+  }
+  if (appNames.length === 1 && appNames[0]) return [AppExecutor.from(workspace, appNames[0])];
+  const remembered = new Set(await AppSelectionMemory.read(workspace.workspaceRoot));
+  const picked = await checkbox<string>({
+    message: "Select the apps to run (space to toggle, enter to confirm)",
+    choices: appNames.map((name) => ({ name, value: name, checked: remembered.has(name) })),
+    // Enter with nothing ticked is a mis-keypress far more often than an intent to run nothing.
+    required: true,
+  });
+  await AppSelectionMemory.write(workspace.workspaceRoot, picked);
+  return picked.map((name) => AppExecutor.from(workspace, name));
+};
+
 export const getInternalArgumentValue = async (
   argMeta: InternalArgMeta,
   value: string | undefined,
@@ -329,6 +400,11 @@ It may cause unexpected behavior. Run \`akan update\` to update latest akanjs.`,
               `[sys-name:module-name]`,
               `${argMeta.type} in this workspace (apps|libs)/<sys-name>/lib/<module-name>`,
             );
+          } else if (argMeta.type === "Apps") {
+            programCommand = programCommand.argument(
+              `[apps...]`,
+              `apps in this workspace apps/<appName>, or all (space- or comma-separated; omit to pick interactively)`,
+            );
           } else {
             const sysType = argMeta.type.toLowerCase();
             programCommand = programCommand.argument(
@@ -357,6 +433,11 @@ It may cause unexpected behavior. Run \`akan update\` to update latest akanjs.`,
               commandArgs[argMeta.idx] = await getOptionValue(argMeta, opt, commandContext);
             else if (argMeta.type === "Argument")
               commandArgs[argMeta.idx] = await getArgumentValue(argMeta, cmdArgs[argMeta.idx] as string);
+            else if (argMeta.type === "Apps")
+              commandArgs[argMeta.idx] = await getAppsArgumentValue(
+                cmdArgs[argMeta.idx] as string | string[] | undefined,
+                workspace,
+              );
             else
               commandArgs[argMeta.idx] = await getInternalArgumentValue(
                 argMeta as InternalArgMeta,
@@ -366,6 +447,12 @@ It may cause unexpected behavior. Run \`akan update\` to update latest akanjs.`,
             // set app name to env
             if (commandArgs[argMeta.idx] instanceof AppExecutor)
               process.env.AKAN_PUBLIC_APP_NAME = (commandArgs[argMeta.idx] as AppExecutor).name;
+            //? Only when exactly one app resolved. Publishing a name while several are in play would make
+            //? every env-derived answer in this process belong to whichever app happened to be last.
+            else if (Array.isArray(commandArgs[argMeta.idx])) {
+              const apps = commandArgs[argMeta.idx] as AppExecutor[];
+              if (apps.length === 1 && apps[0]) process.env.AKAN_PUBLIC_APP_NAME = apps[0].name;
+            }
             assignCommandContext(commandContext, argMeta, commandArgs[argMeta.idx]);
             if ((opt as { verbose?: boolean }).verbose) Executor.setVerbose(true);
           }

package/commandDecorators/commandBuilder.ts

@@ -23,9 +23,24 @@ type PrimitiveValue<T extends PrimitiveArgType> = T extends StringConstructor
     ? number
     : boolean;
 type MaybeNullable<Value, Option> = Option extends { nullable: true } ? Value | null : Value;
+/**
+ * The literal union a static `enum` declares, or `never` for a `DynamicEnum` — a function does not extend
+ * a readonly array, so a runtime-resolved choice list falls back to the primitive type. `{ label, value }`
+ * choices contribute their `value`.
+ */
+type EnumValue<Option> = Option extends { enum: infer Choices }
+  ? Choices extends readonly (infer Choice)[]
+    ? Choice extends { value: infer Value }
+      ? Value
+      : Choice
+    : never
+  : never;
+type ArgValue<Type extends PrimitiveArgType, Option> = [EnumValue<Option>] extends [never]
+  ? PrimitiveValue<Type>
+  : EnumValue<Option>;
 type AddArg<Params extends unknown[], Type extends PrimitiveArgType, Option> = [
   ...Params,
-  MaybeNullable<PrimitiveValue<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 [
@@ -68,7 +83,7 @@ class TargetBuilder<Deps extends readonly DependencyCls[], Params extends unknow
     this.#args = args;
   }
 
-  arg<Type extends PrimitiveArgType, Option extends ArgsOption<Context> = ArgsOption<Context>>(
+  arg<Type extends PrimitiveArgType, const Option extends ArgsOption<Context> = ArgsOption<Context>>(
     name: string,
     type: Type,
     argsOption: Option = {} as Option,
@@ -85,7 +100,7 @@ class TargetBuilder<Deps extends readonly DependencyCls[], Params extends unknow
     ]);
   }
 
-  option<Type extends PrimitiveArgType, Option extends ArgsOption<Context> = ArgsOption<Context>>(
+  option<Type extends PrimitiveArgType, const Option extends ArgsOption<Context> = ArgsOption<Context>>(
     name: string,
     type: Type,
     argsOption: Option = {} as Option,
@@ -135,12 +150,12 @@ type CommandBuilderContext<Deps extends readonly DependencyCls[]> = {
   public: (targetOption?: Omit<TargetOption, "type">) => TargetBuilder<Deps>;
   cloud: (targetOption?: Omit<TargetOption, "type">) => TargetBuilder<Deps>;
   dev: (targetOption?: Omit<TargetOption, "type">) => TargetBuilder<Deps>;
-  arg: <Type extends PrimitiveArgType, Option extends ArgsOption<CommandContext> = ArgsOption<CommandContext>>(
+  arg: <Type extends PrimitiveArgType, const Option extends ArgsOption<CommandContext> = ArgsOption<CommandContext>>(
     name: string,
     type: Type,
     argsOption?: Option,
   ) => ArgMeta;
-  option: <Type extends PrimitiveArgType, Option extends ArgsOption<CommandContext> = ArgsOption<CommandContext>>(
+  option: <Type extends PrimitiveArgType, const Option extends ArgsOption<CommandContext> = ArgsOption<CommandContext>>(
     name: string,
     type: Type,
     argsOption?: Option,

package/commandDecorators/commandDecorators.test.ts

@@ -1,7 +1,7 @@
 import { afterEach, describe, expect, test } from "bun:test";
 import { AppExecutor, WorkspaceExecutor } from "../executors";
-import { App, getArgMetas, Lib, Module, Pkg, Sys, Workspace } from "./argMeta";
-import { getInternalArgumentValue } from "./command";
+import { App, type ArgMeta, type ArgsOption, getArgMetas, Lib, Module, Pkg, Sys, Workspace } from "./argMeta";
+import { getArgumentValue, getInternalArgumentValue, getOptionValue } from "./command";
 import { command } from "./commandBuilder";
 import {
   assertUniqueDependencies,
@@ -136,7 +136,7 @@ describe("command helper metadata", () => {
 
     const app = await getInternalArgumentValue({ key: "", idx: 0, type: "App" }, undefined, workspace);
 
-    expect(app).toBeInstanceOf(AppExecutor);
+    if (!(app instanceof AppExecutor)) throw new Error(`expected an AppExecutor, got ${app.constructor.name}`);
     expect(app.name).toBe("single-command-test-app");
     expect(app.workspace).toBe(workspace);
   });
@@ -223,3 +223,115 @@ describe("command helper dependency injection", () => {
     expect(descriptor?.writable).toBe(false);
   });
 });
+
+describe("enum arg choices", () => {
+  const optionMeta = (enumChoices: ArgsOption["enum"]): ArgMeta => ({
+    name: "format",
+    argsOption: { type: "string", enum: enumChoices },
+    key: "run",
+    idx: 0,
+    type: "Option",
+  });
+  const argumentMeta = (enumChoices: ArgsOption["enum"]): ArgMeta => ({
+    ...optionMeta(enumChoices),
+    name: "action",
+    type: "Argument",
+  });
+  const context = { values: {} };
+
+  test("passes a declared choice through", async () => {
+    expect(await getOptionValue(optionMeta(["text", "json"]), { format: "json" }, context)).toBe("json");
+  });
+
+  // Before this check `akan quality --format yaml` reached the script as "yaml" while the declaration
+  // claimed the parameter was "text" | "json".
+  test("rejects an undeclared value in commander's wording", async () => {
+    await expect(getOptionValue(optionMeta(["text", "json"]), { format: "yaml" }, context)).rejects.toThrow(
+      "option '--format' argument 'yaml' is invalid. Allowed choices are text, json.",
+    );
+  });
+
+  test("names a positional argument as an argument", async () => {
+    await expect(getArgumentValue(argumentMeta(["scan", "ssr"]), "sssr")).rejects.toThrow(
+      "argument 'action' argument 'sssr' is invalid. Allowed choices are scan, ssr.",
+    );
+  });
+
+  test("kebab-cases a camelCase option name the way the flag is spelled", async () => {
+    await expect(
+      getOptionValue({ ...optionMeta(["apk", "aab"]), name: "assembleType" }, { assembleType: "ipa" }, context),
+    ).rejects.toThrow("option '--assemble-type'");
+  });
+
+  test("compares a labelled choice by its value, not its label", async () => {
+    const labelled = optionMeta([{ label: "JSON output", value: "json" }]);
+    expect(await getOptionValue(labelled, { format: "json" }, context)).toBe("json");
+    await expect(getOptionValue(labelled, { format: "JSON output" }, context)).rejects.toThrow("is invalid");
+  });
+
+  // A DynamicEnum resolves against a context that is not populated yet, and the interactive select is its
+  // only consumer, so an explicit value passes through unchecked rather than being rejected wrongly.
+  test("leaves a dynamic choice list unchecked", async () => {
+    expect(
+      await getOptionValue(
+        optionMeta(() => ["text"]),
+        { format: "anything" },
+        context,
+      ),
+    ).toBe("anything");
+  });
+
+  test("an option with no enum is unaffected", async () => {
+    expect(await getOptionValue(optionMeta(undefined), { format: "whatever" }, context)).toBe("whatever");
+  });
+});
+
+describe("enum arg type inference", () => {
+  afterEach(() => {
+    CommandContainer.clear();
+  });
+
+  /**
+   * Compile-time only. Nothing here can fail at runtime: if `enum` stops narrowing, the parameter widens
+   * to the primitive and these calls stop typechecking, so the regression surfaces in `akan typecheck`
+   * rather than in fifteen `as "a" | "b"` casts creeping back into the command files.
+   */
+  const expectLiteral = <Expected>(_value: Expected) => undefined;
+
+  test("a static enum narrows the exec parameter to its declared choices", () => {
+    class InferenceRunner extends runner("inference") {}
+    class InferenceScript extends script("inference", [InferenceRunner]) {}
+
+    class InferenceCommand extends command("inference", [InferenceScript], ({ public: target }) => ({
+      run: target({ desc: "run" })
+        .arg("action", String, { enum: ["scan", "ssr"] })
+        .option("format", String, { enum: ["text", "json"], default: "text" })
+        .option("count", Number, { enum: [1, 2] })
+        .option("scope", String, { enum: ["all", "one"], nullable: true })
+        .option("label", String, { enum: [{ label: "JSON output", value: "json" }] })
+        .option("plain", String, { desc: "no choices declared" })
+        .option("dynamic", String, { enum: () => ["a", "b"] })
+        .exec(async (action, format, count, scope, label, plain, dynamic) => {
+          expectLiteral<"scan" | "ssr">(action);
+          expectLiteral<"text" | "json">(format);
+          expectLiteral<1 | 2>(count);
+          expectLiteral<"all" | "one" | null>(scope);
+          expectLiteral<"json">(label);
+          expectLiteral<string>(plain);
+          expectLiteral<string>(dynamic);
+        }),
+    })) {}
+
+    const [targetMeta] = getTargetMetas(InferenceCommand);
+    expect(targetMeta?.key).toBe("run");
+    expect(targetMeta?.args.map((arg) => ("name" in arg ? arg.name : arg.type))).toEqual([
+      "action",
+      "format",
+      "count",
+      "scope",
+      "label",
+      "plain",
+      "dynamic",
+    ]);
+  });
+});

package/commandDecorators/helpFormatter.ts

@@ -159,6 +159,7 @@ export const formatCommandHelp = (command: CommandCls, key: string) => {
     .map((arg) => {
       if (arg.type === "Workspace") return "";
       if (arg.type === "Module") return "[sys:module]";
+      if (arg.type === "Apps") return "[apps...]";
       if (arg.type === "Argument") {
         return `[${camelToKebabCase(arg.name)}]`;
       }
@@ -192,6 +193,9 @@ export const formatCommandHelp = (command: CommandCls, key: string) => {
       } else if (arg.type === "Module") {
         argName = "sys:module";
         argDesc = "Module in format: app-name:module-name or lib-name:module-name";
+      } else if (arg.type === "Apps") {
+        argName = "apps...";
+        argDesc = "App names, space- or comma-separated, or all. Omit to pick them interactively";
       } else {
         argName = arg.type.toLowerCase();
         argDesc = `${arg.type} name in this workspace`;