@akanjs/devkit 3.0.0-beta.9 → 3.0.0

package/codeAgent/tools/mcpServerConfig.test.ts

@@ -0,0 +1,212 @@
+import { afterEach, beforeAll, describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { akanCodePaths } from "../agent/akanCodePaths";
+import { McpServerConfig, type McpServerScope } from "./McpServerConfig";
+
+const roots: string[] = [];
+
+// Without this every add() writes into the real ~/.akan/code/mcp.json of whoever runs the suite.
+beforeAll(() => {
+  const home = mkdtempSync(path.join(tmpdir(), "akan-home-"));
+  roots.push(home);
+  process.env.AKAN_CODE_HOME = home;
+  expect(akanCodePaths.globalMcpFile().startsWith(home)).toBe(true);
+});
+
+const globalFile = (file: string) => {
+  const target = akanCodePaths.globalMcpFile();
+  mkdirSync(path.dirname(target), { recursive: true });
+  writeFileSync(target, file);
+};
+
+const workspace = (file?: string) => {
+  const root = mkdtempSync(path.join(tmpdir(), "akan-mcp-"));
+  roots.push(root);
+  if (file === undefined) return root;
+  const target = McpServerConfig.file(root);
+  mkdirSync(path.dirname(target), { recursive: true });
+  writeFileSync(target, file);
+  return root;
+};
+
+const written = (root: string) =>
+  JSON.parse(readFileSync(McpServerConfig.file(root), "utf8")) as Record<string, object>;
+
+afterEach(() => {
+  rmSync(akanCodePaths.globalMcpFile(), { force: true });
+  for (const root of roots.slice(1)) rmSync(root, { recursive: true, force: true });
+  roots.splice(1);
+});
+
+describe("MCP server config", () => {
+  test("an editor's own block is read as it is written", () => {
+    const root = workspace(
+      JSON.stringify({
+        mcpServers: {
+          github: { command: "npx", args: ["-y", "@modelcontextprotocol/server-github"] },
+          linear: { url: "https://mcp.linear.app/sse" },
+        },
+      }),
+    );
+    expect(McpServerConfig.read(root)).toEqual([
+      { name: "github", transport: "stdio", command: "npx", args: ["-y", "@modelcontextprotocol/server-github"] },
+      { name: "linear", transport: "http", url: "https://mcp.linear.app/sse" },
+    ]);
+  });
+
+  test("a static token and a hand-issued oauth client travel from the file", () => {
+    const root = workspace(
+      JSON.stringify({
+        mcpServers: {
+          sentry: {
+            url: "https://mcp.sentry.dev/mcp",
+            headers: { "x-api-key": "from-the-file" },
+            oauth: { clientId: "abc", scope: "project:read" },
+          },
+        },
+      }),
+    );
+    expect(McpServerConfig.read(root)[0]).toMatchObject({
+      headers: { "x-api-key": "from-the-file" },
+      oauth: { clientId: "abc", scope: "project:read" },
+    });
+  });
+
+  test("a disabled server is declared but never connected", () => {
+    const root = workspace(JSON.stringify({ mcpServers: { off: { command: "x", disabled: true } } }));
+    expect(McpServerConfig.read(root)).toEqual([]);
+    expect(McpServerConfig.declared(root)).toEqual([
+      { ref: { name: "off", transport: "stdio", command: "x" }, disabled: true, scope: "workspace" },
+    ]);
+  });
+
+  test("a url is an http server and anything else is a command with its argv", () => {
+    const root = workspace();
+    expect(McpServerConfig.add(root, "linear", ["https://mcp.linear.app/sse"], "workspace")).toEqual({
+      name: "linear",
+      transport: "http",
+      url: "https://mcp.linear.app/sse",
+    });
+    expect(McpServerConfig.add(root, "github", ["npx", "-y", "server-github"], "workspace")).toEqual({
+      name: "github",
+      transport: "stdio",
+      command: "npx",
+      args: ["-y", "server-github"],
+    });
+    expect(Object.keys(written(root).mcpServers ?? {})).toEqual(["linear", "github"]);
+  });
+
+  test("a VS Code file keeps its own spelling through a write", () => {
+    const root = workspace(JSON.stringify({ servers: { a: { command: "a" } } }));
+    McpServerConfig.add(root, "b", ["b"], "workspace");
+    const file = written(root);
+    expect(Object.keys(file)).toEqual(["servers"]);
+    expect(Object.keys(file.servers ?? {})).toEqual(["a", "b"]);
+  });
+
+  test("adding the same name twice replaces the entry rather than doubling it", () => {
+    const root = workspace();
+    McpServerConfig.add(root, "a", ["old"], "workspace");
+    McpServerConfig.add(root, "a", ["new", "--flag"], "workspace");
+    expect(McpServerConfig.read(root)).toEqual([{ name: "a", transport: "stdio", command: "new", args: ["--flag"] }]);
+  });
+
+  test("removing says whether it removed anything", () => {
+    const root = workspace(JSON.stringify({ mcpServers: { a: { command: "a" } } }));
+    expect(McpServerConfig.remove(root, "nope")).toBe(false);
+    expect(McpServerConfig.remove(root, "a")).toBe("workspace");
+    expect(McpServerConfig.read(root)).toEqual([]);
+  });
+
+  test("a server with nothing to reach it by is refused", () => {
+    expect(() => McpServerConfig.add(workspace(), "a", [], "workspace")).toThrow();
+  });
+
+  test("a malformed file costs its servers and is named rather than thrown", () => {
+    const root = workspace("{ not json");
+    expect(McpServerConfig.read(root)).toEqual([]);
+    expect(McpServerConfig.problem(root)).toContain("not valid JSON");
+  });
+
+  test("no file at all is not a problem", () => {
+    const root = workspace();
+    expect(McpServerConfig.read(root)).toEqual([]);
+    expect(McpServerConfig.problem(root)).toBeUndefined();
+  });
+
+  test("a server declared in the home file is read from a workspace that declares nothing", () => {
+    globalFile(JSON.stringify({ mcpServers: { office: { url: "https://office.example/mcp" } } }));
+    const root = workspace();
+    expect(McpServerConfig.read(root)).toEqual([
+      { name: "office", transport: "http", url: "https://office.example/mcp" },
+    ]);
+    expect(McpServerConfig.declared(root)[0]?.scope).toBe("global");
+  });
+
+  test("both files are merged, and the workspace wins the name they share", () => {
+    globalFile(JSON.stringify({ mcpServers: { office: { url: "https://home/mcp" }, shared: { command: "home" } } }));
+    const root = workspace(JSON.stringify({ mcpServers: { shared: { command: "repo" } } }));
+    expect(McpServerConfig.declared(root).map((entry) => [entry.ref.name, entry.scope])).toEqual([
+      ["office", "global"],
+      ["shared", "workspace"],
+    ]);
+    expect(McpServerConfig.read(root).find((ref) => ref.name === "shared")?.command).toBe("repo");
+  });
+
+  test("a write goes to the scope it was asked for, and leaves the other file alone", () => {
+    const root = workspace();
+    McpServerConfig.add(root, "office", ["https://office.example/mcp"]);
+    expect(McpServerConfig.declared(root)).toEqual([
+      {
+        ref: { name: "office", transport: "http", url: "https://office.example/mcp" },
+        disabled: false,
+        scope: "global",
+      },
+    ]);
+    expect(existsSync(McpServerConfig.file(root, "workspace"))).toBe(false);
+  });
+
+  test("removing finds the file the server is actually in", () => {
+    globalFile(JSON.stringify({ mcpServers: { office: { command: "x" } } }));
+    const root = workspace(JSON.stringify({ mcpServers: { repobot: { command: "y" } } }));
+    expect(McpServerConfig.remove(root, "office")).toBe("global");
+    expect(McpServerConfig.remove(root, "repobot")).toBe("workspace");
+    expect(McpServerConfig.read(root)).toEqual([]);
+  });
+
+  test("removing a name both files declare takes the workspace's, and the home file's then applies", () => {
+    globalFile(JSON.stringify({ mcpServers: { shared: { command: "home" } } }));
+    const root = workspace(JSON.stringify({ mcpServers: { shared: { command: "repo" } } }));
+    expect(McpServerConfig.remove(root, "shared")).toBe("workspace");
+    expect(McpServerConfig.declared(root)).toEqual([
+      { ref: { name: "shared", transport: "stdio", command: "home" }, disabled: false, scope: "global" },
+    ]);
+  });
+
+  test("a remove that names a scope touches only that file", () => {
+    globalFile(JSON.stringify({ mcpServers: { office: { command: "x" }, shared: { command: "home" } } }));
+    const root = workspace(JSON.stringify({ mcpServers: { shared: { command: "repo" } } }));
+    expect(McpServerConfig.remove(root, "office", "workspace")).toBe(false);
+    expect(McpServerConfig.remove(root, "shared", "global")).toBe("global");
+    expect(McpServerConfig.declared(root).map((entry) => [entry.ref.name, entry.scope])).toEqual([
+      ["office", "global"],
+      ["shared", "workspace"],
+    ]);
+  });
+
+  test("a scope is what a caller names, never guessed from the shape", () => {
+    const root = workspace();
+    const scopes: McpServerScope[] = ["global", "workspace"];
+    for (const scope of scopes) McpServerConfig.add(root, `in-${scope}`, ["x"], scope);
+    expect(McpServerConfig.declared(root).map((entry) => entry.scope)).toEqual(["global", "workspace"]);
+  });
+
+  test("a server reads back as the one line it is reached at", () => {
+    expect(McpServerConfig.targetOf({ name: "a", transport: "stdio", command: "npx", args: ["-y", "x"] })).toBe(
+      "npx -y x",
+    );
+    expect(McpServerConfig.targetOf({ name: "a", transport: "http", url: "https://x" })).toBe("https://x");
+  });
+});

package/codegenLock.test.ts

@@ -1,15 +1,10 @@
-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 { describe, expect, test } from "bun:test";
+import { readFile, stat, utimes, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { CodegenLock } from "./codegenLock";
+import { tempDirs } from "./testHelpers";
 
-const roots: string[] = [];
-const makeRoot = async () => {
-  const root = await mkdtemp(path.join(tmpdir(), "akan-codegen-lock-"));
-  roots.push(root);
-  return root;
-};
+const makeRoot = tempDirs("akan-codegen-lock-");
 const seedHolder = async (root: string, holder: unknown) => {
   const lockPath = CodegenLock.pathIn(root);
   await Bun.write(lockPath, typeof holder === "string" ? holder : JSON.stringify(holder));
@@ -18,10 +13,6 @@ const seedHolder = async (root: string, holder: unknown) => {
 /** 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();

package/codegenLock.ts

@@ -8,26 +8,12 @@ interface LockHolder {
   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.
- */
+// Two dev servers sharing a lib both regenerate its barrels, and a mid-scan watcher reads a half-written one as a user
+// edit. An expired wait proceeds unlocked: stalling the watcher is worse than the torn read `writeTextAtomic` prevents.
 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.
-   */
+  /** A holder-less lock file younger than this is someone mid-acquire (between the exclusive create and the write). */
   static readonly unknownHolderStaleMs = 60_000;
   static readonly #pollMs = 25;
   static readonly #logger = new Logger("CodegenLock");

package/commandDecorators/argMeta.ts

@@ -83,11 +83,7 @@ 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.
- */
+/** One or more apps: `akan start a b`, `a,b` or `all`, or a checkbox when none is named. */
 export const Apps = createInternalArgToken<AppExecutor[], "Apps">("Apps");
 export type Apps = AppExecutor[];
 

package/commandDecorators/camelToKebabCase.ts

@@ -0,0 +1 @@
+export const camelToKebabCase = (str: string) => str.replace(/([A-Z])/g, "-$1").toLowerCase();

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, @langchain/* 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, 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>();
 
@@ -71,6 +68,8 @@ const handleOption = (programCommand: Command, argMeta: ArgMeta) => {
     `-${flag}, --${kebabName}${type === "boolean" ? " [boolean]" : ` <${kebabName}>`}`,
     `${desc}${ask ? ` (${ask})` : ""}${example ? ` (example: ${example})` : ""}${choices ? ` (choices: ${choices.map((choice) => choice.name).join(", ")})` : ""}`,
   );
+  if (type === "boolean" && argMeta.argsOption.default === true)
+    programCommand.option(`--no-${kebabName}`, `turn off --${kebabName}`);
   return programCommand;
 };
 const handleArgument = (programCommand: Command, argMeta: ArgMeta) => {
@@ -95,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;
@@ -131,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]);
@@ -149,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) => {
@@ -215,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,
@@ -263,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]);
@@ -353,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({
@@ -414,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);
         };
@@ -444,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;
@@ -469,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);
+  });
 };