@akanjs/devkit 3.0.0-beta.19 → 3.0.0-beta.20

package/commandDecorators/command.ts

@@ -10,11 +10,8 @@ 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 and the cloud stack into
-// every process that registers a command (measured: 236MB vs 3MB).
-import { FileSys } from "../fileSys";
-import { getDirname } from "../getDirname";
+// Never the root barrel: it drags ink, @trapezedev/project, ssh2 and the cloud stack into every command process.
+import { FileSys, getDirname } from "../fileSys";
 import type { PackageJson } from "../types";
 import {
   type ArgMeta,
@@ -24,11 +21,11 @@ import {
   getArgMetas,
   type InternalArgMeta,
 } from "./argMeta";
+import { camelToKebabCase } from "./camelToKebabCase";
 import { CommandContainer } from "./dependencyBuilder";
 import { formatCommandHelp, formatHelp } from "./helpFormatter";
 import { type CommandCls, getTargetCommandNames, getTargetMetas } from "./targetMeta";
 
-const camelToKebabCase = (str: string) => str.replace(/([A-Z])/g, "-$1").toLowerCase();
 const loggedCliErrorObjects = new WeakSet<object>();
 const loggedCliErrorMessages = new Set<string>();
 
@@ -97,30 +94,16 @@ const normalizeEnumChoices = (enumChoices: EnumChoices) =>
       : { value: choice, name: choice.toString() },
   );
 
-/**
- * The interactive prompt stack, loaded on the first prompt instead of at import.
- *
- * `runCommands` lives in this module, so a static import put `@inquirer/prompts` (~24MB) in the CLI
- * entry's chunk closure — and `akan start` holds that process for the whole dev session while never
- * asking a question, because every argument it needs is already on the command line.
- *
- * The wrappers are typed from the real prompts so no call site changes, and `import type` leaves no
- * runtime edge for the bundler to follow (`entryModuleGraph.test.ts` asserts that).
- */
+// Loaded on the first prompt: a static import keeps @inquirer/prompts (~24MB) resident for a whole `akan start`.
+// The types come through `import type`, which leaves no runtime edge (entryModuleGraph.test.ts asserts that).
 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.
- */
+// A DynamicEnum is not checked: it resolves against a context the internal args have not populated yet.
+// Compared as strings: the value is still commander's raw string while a numeric choice list holds numbers.
 const assertEnumChoice = (argMeta: ArgMeta, value: unknown) => {
   const enumChoices = argMeta.argsOption.enum;
   if (!enumChoices || typeof enumChoices === "function") return;
@@ -133,17 +116,13 @@ const assertEnumChoice = (argMeta: ArgMeta, value: unknown) => {
   );
 };
 
-const resolveEnumChoices = async (argMeta: ArgMeta, context: CommandContext) => {
-  const enumChoices = argMeta.argsOption.enum;
-  if (!enumChoices) return null;
-  if (typeof enumChoices === "function") return await enumChoices(context);
-  return enumChoices;
-};
+const inputMessageOf = ({ name, argsOption: { desc, example, ask } }: ArgMeta) =>
+  ask ? `${ask}: ` : desc ? `${desc}: ` : `Enter the ${name} value${example ? ` (example: ${example})` : ""}: `;
 
 export const getOptionValue = async (argMeta: ArgMeta, opt: Record<string, unknown>, context: CommandContext) => {
   const {
     name,
-    argsOption: { enum: enumChoices, default: defaultValue, type, desc, nullable, example, ask },
+    argsOption: { enum: enumChoices, default: defaultValue, type, desc, nullable, ask },
   } = argMeta;
   if (opt[argMeta.name] !== undefined) {
     assertEnumChoice(argMeta, opt[argMeta.name]);
@@ -151,42 +130,26 @@ export const getOptionValue = async (argMeta: ArgMeta, opt: Record<string, unkno
   } else if (defaultValue !== undefined) return defaultValue;
 
   if (enumChoices) {
-    const choices = normalizeEnumChoices((await resolveEnumChoices(argMeta, context)) ?? []);
+    const choices = normalizeEnumChoices(
+      (typeof enumChoices === "function" ? await enumChoices(context) : enumChoices) ?? [],
+    );
     if (choices.length === 1) return choices[0]?.value;
-    const choice = await select({ message: ask ?? desc ?? `Select the ${name} value`, choices });
-    return choice;
+    return await select({ message: ask ?? desc ?? `Select the ${name} value`, choices });
   } else if (nullable) return null;
   else if (type === "boolean") {
     const message = ask ?? desc ?? `Do you want to set ${name}? ${desc ? ` (${desc})` : ""}: `;
     return await confirm({ message });
-  } else {
-    const message = ask
-      ? `${ask}: `
-      : desc
-        ? `${desc}: `
-        : `Enter the ${name} value${example ? ` (example: ${example})` : ""}: `;
-    if (argMeta.argsOption.nullable) return await input({ message });
-    else return convertArgValue(await input({ message }), type ?? "string");
-  }
+  } else return convertArgValue(await input({ message: inputMessageOf(argMeta) }), type ?? "string");
 };
 
 export const getArgumentValue = async (argMeta: ArgMeta, value: string | undefined) => {
-  const {
-    name,
-    argsOption: { default: defaultValue, type, desc, nullable, example, ask },
-  } = argMeta;
+  const { default: defaultValue, type, nullable } = argMeta.argsOption;
   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
-    ? `${ask}: `
-    : desc
-      ? `${desc}: `
-      : `Enter the ${name} value${example ? ` (example: ${example})` : ""}: `;
-  return convertArgValue(await input({ message }), type ?? "string");
+  return convertArgValue(await input({ message: inputMessageOf(argMeta) }), type ?? "string");
 };
 
 const assignCommandContext = (context: CommandContext, argMeta: ArgMeta | InternalArgMeta, value: unknown) => {
@@ -217,18 +180,13 @@ 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.
- */
+// Kept out of getInternalArgumentValue: Apps is the only internal arg whose positional is variadic (an array).
 export const getAppsArgumentValue = async (
   value: string | string[] | undefined,
   workspace: WorkspaceExecutor,
@@ -265,32 +223,23 @@ export const getInternalArgumentValue = async (
   if (argMeta.type === "Workspace") return workspace;
   const sysType = argMeta.type.toLowerCase();
   const [appNames, libNames, pkgNames] = await workspace.getExecs();
-  if (sysType === "sys") {
-    if (value && appNames.includes(value)) return AppExecutor.from(workspace, value);
-    else if (value && libNames.includes(value)) return LibExecutor.from(workspace, value);
-    else {
-      const sysName = await select<string>({
-        message: `Select the App or Lib name`,
-        choices: [...appNames, ...libNames],
-      });
-      if (appNames.includes(sysName)) return AppExecutor.from(workspace, sysName);
-      else if (libNames.includes(sysName)) return LibExecutor.from(workspace, sysName);
-      else throw new Error(`Invalid system name: ${sysName}`);
-    }
-  } else if (sysType === "exec") {
-    if (value && appNames.includes(value)) return AppExecutor.from(workspace, value);
-    else if (value && libNames.includes(value)) return LibExecutor.from(workspace, value);
-    else if (value && pkgNames.includes(value)) return PkgExecutor.from(workspace, value);
-    else {
-      const execName = await select<string>({
-        message: `Select the App or Lib or Pkg name`,
-        choices: [...appNames, ...libNames, ...pkgNames],
-      });
-      if (appNames.includes(execName)) return AppExecutor.from(workspace, execName);
-      else if (libNames.includes(execName)) return LibExecutor.from(workspace, execName);
-      else if (pkgNames.includes(execName)) return PkgExecutor.from(workspace, execName);
-      else throw new Error(`Invalid system name: ${execName}`);
-    }
+  if (sysType === "sys" || sysType === "exec") {
+    const pkgChoices = sysType === "exec" ? pkgNames : [];
+    const execOf = (name: string) => {
+      if (appNames.includes(name)) return AppExecutor.from(workspace, name);
+      if (libNames.includes(name)) return LibExecutor.from(workspace, name);
+      if (pkgChoices.includes(name)) return PkgExecutor.from(workspace, name);
+      return null;
+    };
+    const found = value ? execOf(value) : null;
+    if (found) return found;
+    const name = await select<string>({
+      message: sysType === "exec" ? `Select the App or Lib or Pkg name` : `Select the App or Lib name`,
+      choices: [...appNames, ...libNames, ...pkgChoices],
+    });
+    const picked = execOf(name);
+    if (!picked) throw new Error(`Invalid system name: ${name}`);
+    return picked;
   } else if (sysType === "app") {
     if (value && appNames.includes(value)) return AppExecutor.from(workspace, value);
     if (!value && appNames.length === 1 && appNames[0]) return AppExecutor.from(workspace, appNames[0]);
@@ -355,17 +304,10 @@ export const runCommands = async (...commands: CommandCls[]) => {
   }
   process.env.AKAN_VERSION = cliPackageJson?.version ?? "0.0.1";
 
-  // Custom help handling
   const hasHelpFlag = process.argv.includes("--help") || process.argv.includes("-h");
-  const hasCommand = process.argv.length > 2 && !process.argv[2]?.startsWith("-");
-
-  // Show help if: 1) explicit --help flag, or 2) no command provided (just "akan")
-  if (hasHelpFlag || !hasCommand) {
-    if (process.argv.length === 2 || (process.argv.length === 3 && hasHelpFlag)) {
-      // Global help (no specific command)
-      Logger.rawLog(formatHelp(commands, process.env.AKAN_VERSION));
-      process.exit(0);
-    }
+  if (process.argv.length === 2 || (process.argv.length === 3 && hasHelpFlag)) {
+    Logger.rawLog(formatHelp(commands, process.env.AKAN_VERSION));
+    process.exit(0);
   }
 
   program.version(process.env.AKAN_VERSION).description("Akan CLI").configureHelp({
@@ -416,8 +358,6 @@ It may cause unexpected behavior. Run \`akan update\` to update latest akanjs.`,
           }
         }
         programCommand = programCommand.option(`-v, --verbose [boolean]`, `verbose output`);
-
-        // Override help completely for each command
         programCommand.helpInformation = () => {
           return formatCommandHelp(command, targetMeta.key);
         };
@@ -446,11 +386,9 @@ It may cause unexpected behavior. Run \`akan update\` to update latest akanjs.`,
                 cmdArgs[argMeta.idx] as string,
                 workspace,
               );
-            // 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.
+            //? Only for a single app: with several, every env-derived answer would belong to whichever came 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;
@@ -471,5 +409,9 @@ It may cause unexpected behavior. Run \`akan update\` to update latest akanjs.`,
       }
     }
   }
-  await program.parseAsync(process.argv);
+  // 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) => {
+    printCliError(error);
+    process.exit(1);
+  });
 };

package/commandDecorators/commandBuilder.ts

@@ -2,6 +2,7 @@ import type {
   App,
   ArgMeta,
   ArgsOption,
+  ArgType,
   CommandContext,
   Exec,
   InternalArgMeta,
@@ -13,9 +14,14 @@ import type {
   Sys,
 } from "./argMeta";
 import { normalizePrimitiveArgType } from "./argMeta";
-import { assertUniqueDependencies, type DependencyInstanceMap, injectDependencies } from "./dependencyBuilder";
+import {
+  assertUniqueDependencies,
+  type DependencyCls,
+  type DependencyInstanceMap,
+  type DependencyKey,
+  injectDependencies,
+} from "./dependencyBuilder";
 import { COMMAND_META, type CommandCls, type TargetMeta, type TargetOption } from "./targetMeta";
-import type { DependencyCls, DependencyKey } from "./types";
 
 type PrimitiveValue<T extends PrimitiveArgType> = T extends StringConstructor
   ? string
@@ -23,11 +29,7 @@ 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`.
- */
+// A DynamicEnum yields never (a function is no readonly array), so ArgValue falls back to the primitive type.
 type EnumValue<Option> = Option extends { enum: infer Choices }
   ? Choices extends readonly (infer Choice)[]
     ? Choice extends { value: infer Value }
@@ -73,6 +75,14 @@ type CommandHandler<Deps extends readonly DependencyCls[], Params extends unknow
   ...args: Params
 ) => unknown | Promise<unknown>;
 
+const argMetaOf = (
+  type: ArgType,
+  name: string,
+  primitive: PrimitiveArgType,
+  argsOption: object | undefined,
+  idx: number,
+): ArgMeta => ({ name, argsOption: { ...argsOption, type: normalizePrimitiveArgType(primitive) }, key: "", idx, type });
+
 class TargetBuilder<Deps extends readonly DependencyCls[], Params extends unknown[] = [], Context = object> {
   readonly #args: (ArgMeta | InternalArgMeta)[];
 
@@ -83,56 +93,29 @@ class TargetBuilder<Deps extends readonly DependencyCls[], Params extends unknow
     this.#args = args;
   }
 
+  #add<NextParams extends unknown[], NextContext = Context>(...argMetas: (ArgMeta | InternalArgMeta)[]) {
+    return new TargetBuilder<Deps, NextParams, NextContext>(this.targetOption, [...this.#args, ...argMetas]);
+  }
+
   arg<Type extends PrimitiveArgType, const Option extends ArgsOption<Context> = ArgsOption<Context>>(
     name: string,
     type: Type,
     argsOption: Option = {} as Option,
-  ): TargetBuilder<Deps, AddArg<Params, Type, Option>, Context> {
-    return new TargetBuilder<Deps, AddArg<Params, Type, Option>, Context>(this.targetOption, [
-      ...this.#args,
-      {
-        name,
-        argsOption: { ...argsOption, type: normalizePrimitiveArgType(type) },
-        key: "",
-        idx: this.#args.length,
-        type: "Argument",
-      } as ArgMeta<CommandContext>,
-    ]);
+  ) {
+    return this.#add<AddArg<Params, Type, Option>>(argMetaOf("Argument", name, type, argsOption, this.#args.length));
   }
 
   option<Type extends PrimitiveArgType, const Option extends ArgsOption<Context> = ArgsOption<Context>>(
     name: string,
     type: Type,
     argsOption: Option = {} as Option,
-  ): TargetBuilder<Deps, AddArg<Params, Type, Option>, Context> {
-    return new TargetBuilder<Deps, AddArg<Params, Type, Option>, Context>(this.targetOption, [
-      ...this.#args,
-      {
-        name,
-        argsOption: { ...argsOption, type: normalizePrimitiveArgType(type) },
-        key: "",
-        idx: this.#args.length,
-        type: "Option",
-      } as ArgMeta<CommandContext>,
-    ]);
+  ) {
+    return this.#add<AddArg<Params, Type, Option>>(argMetaOf("Option", name, type, argsOption, this.#args.length));
   }
 
-  with<const Tokens extends readonly InternalArgToken[]>(
-    ...tokens: Tokens
-  ): TargetBuilder<Deps, AddInternalArgs<Params, Tokens>, AddInternalContext<Context, Tokens>> {
-    return new TargetBuilder<Deps, AddInternalArgs<Params, Tokens>, AddInternalContext<Context, Tokens>>(
-      this.targetOption,
-      [
-        ...this.#args,
-        ...tokens.map(
-          (token, offset) =>
-            ({
-              key: "",
-              idx: this.#args.length + offset,
-              type: token.type,
-            }) satisfies InternalArgMeta,
-        ),
-      ],
+  with<const Tokens extends readonly InternalArgToken[]>(...tokens: Tokens) {
+    return this.#add<AddInternalArgs<Params, Tokens>, AddInternalContext<Context, Tokens>>(
+      ...tokens.map((token, offset) => ({ key: "", idx: this.#args.length + offset, type: token.type })),
     );
   }
 
@@ -174,22 +157,8 @@ const createContext = <Deps extends readonly DependencyCls[]>(): CommandBuilderC
   public: createTarget<Deps>("public"),
   cloud: createTarget<Deps>("cloud"),
   dev: createTarget<Deps>("dev"),
-  arg: (name, type, argsOption) =>
-    ({
-      name,
-      argsOption: { ...(argsOption ?? {}), type: normalizePrimitiveArgType(type) },
-      key: "",
-      idx: -1,
-      type: "Argument",
-    }) as ArgMeta<CommandContext>,
-  option: (name, type, argsOption) =>
-    ({
-      name,
-      argsOption: { ...(argsOption ?? {}), type: normalizePrimitiveArgType(type) },
-      key: "",
-      idx: -1,
-      type: "Option",
-    }) as ArgMeta<CommandContext>,
+  arg: (name, type, argsOption) => argMetaOf("Argument", name, type, argsOption, -1),
+  option: (name, type, argsOption) => argMetaOf("Option", name, type, argsOption, -1),
 });
 
 const buildCommandMeta = (definitions: Record<string, TargetDefinition>) => {

package/commandDecorators/commandDecorators.test.ts

@@ -243,8 +243,6 @@ describe("enum arg choices", () => {
     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.",
@@ -269,8 +267,6 @@ describe("enum arg choices", () => {
     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(
@@ -291,11 +287,7 @@ describe("enum arg type inference", () => {
     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.
-   */
+  //? Compile-time only: if `enum` stops narrowing, the parameter widens and these calls stop typechecking.
   const expectLiteral = <Expected>(_value: Expected) => undefined;
 
   test("a static enum narrows the exec parameter to its declared choices", () => {

package/commandDecorators/dependencyBuilder.ts

@@ -1,4 +1,13 @@
-import type { DependencyCls, DependencyKey, DependencyKind } from "./types";
+export type Cls<T = unknown> = new (...args: unknown[]) => T;
+
+export type DependencyKind = "command" | "script" | "runner";
+export type DependencyKey<RefName extends string, Kind extends DependencyKind> = `${RefName}${Capitalize<Kind>}`;
+
+export type DependencyCls<T = unknown, Key extends string = string> = (new () => T) & {
+  readonly dependencyKey: Key;
+  readonly dependencyKind: DependencyKind;
+  readonly refName: string;
+};
 
 type UnionToIntersection<Union> = (Union extends unknown ? (value: Union) => void : never) extends (
   value: infer Intersection,