@akanjs/devkit 3.2.0-rc.0 → 3.2.0-rc.10

package/commandDecorators/command.ts

@@ -7,9 +7,17 @@ import type {
 } from "@inquirer/prompts";
 import { Logger } from "akanjs/common";
 import chalk from "chalk";
-import { type Command, program } from "commander";
+import { type Command, type CommanderError, program } from "commander";
 import { AppSelectionMemory } from "../appSelectionMemory";
-import { AppExecutor, Executor, LibExecutor, ModuleExecutor, PkgExecutor, WorkspaceExecutor } from "../executors";
+import {
+  AppExecutor,
+  Executor,
+  LibExecutor,
+  ModuleExecutor,
+  PkgExecutor,
+  type SysExecutor,
+  WorkspaceExecutor,
+} from "../executors";
 // 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";
@@ -22,41 +30,68 @@ import {
   type InternalArgMeta,
 } from "./argMeta";
 import { camelToKebabCase } from "./camelToKebabCase";
+import { CliError, type CliErrorCode } from "./cliError";
 import { CommandContainer } from "./dependencyBuilder";
-import { ExitCodeError } from "./exitCodeError";
 import { formatCommandHelp, formatHelp } from "./helpFormatter";
-import { type CommandCls, getTargetCommandNames, getTargetMetas, type TargetFailure } from "./targetMeta";
+import {
+  type CommandCls,
+  getTargetCommandNames,
+  getTargetMetas,
+  type TargetFailure,
+  type TargetOption,
+} from "./targetMeta";
 import { WorkspaceVersionCheck } from "./workspaceVersionCheck";
 
 const loggedCliErrorObjects = new WeakSet<object>();
+const answeredCliErrors = 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";
-  if (error === null || error === undefined) return "Unknown error";
-  try {
-    const json = JSON.stringify(error);
-    if (json) return json;
-  } catch {
-    return String(error);
-  }
-  return String(error) || "Unknown error";
+  if (typeof error !== "object" || error === null) return;
+  loggedCliErrorObjects.add(error);
+  answeredCliErrors.add(error);
 };
 
-const printCliError = (error: unknown) => {
+const printCliError = (error: unknown, stream: "log" | "error" = "log") => {
   if (typeof error === "object" && error !== null) {
     if (loggedCliErrorObjects.has(error)) return;
     loggedCliErrorObjects.add(error);
   }
-  const message = formatCliError(error);
+  const message = CliError.messageOf(error);
   if (loggedCliErrorMessages.has(message)) return;
   loggedCliErrorMessages.add(message);
-  Logger.rawLog(`\n${chalk.red(message)}`);
+  Logger.rawLog(`\n${chalk.red(message)}`, undefined, stream);
+};
+
+//? The default counts: `akan mcp-call` answers JSON only.
+const asksJson = (argMetas: (ArgMeta | InternalArgMeta)[], opt: Record<string, unknown>) =>
+  argMetas.some((argMeta) => {
+    if (argMeta.type !== "Option") return false;
+    const value = opt[argMeta.name] ?? argMeta.argsOption.default;
+    if (argMeta.name === "json") return value === true || value === "true";
+    return argMeta.name === "format" && value === "json";
+  });
+
+//* Waits for stdout to take the line: the CLI exits right after, and an exit drops what a pipe still buffers.
+const writeJsonFailure = async (error: unknown) => {
+  if (typeof error === "object" && error !== null && answeredCliErrors.has(error)) return;
+  const line = `${JSON.stringify(CliError.failureOf(error))}\n`;
+  await new Promise<void>((resolve) => process.stdout.write(line, () => resolve()));
+};
+
+const failureReporterOf =
+  (json: boolean, onFailure: TargetOption["onFailure"], failure: TargetFailure) => async (error: unknown) => {
+    if (onFailure) await onFailure(error, failure);
+    else if (json) await writeJsonFailure(error);
+  };
+
+//? commander refuses a flag, an argument or a command before any action runs, having printed why to stderr.
+//? Thrown, not exited: the failure path awaits onFailure, and an exit drops what a pipe still buffers.
+const usageRefusalOf = (error: CommanderError) => {
+  if (error.exitCode === 0) process.exit(0);
+  const refused = new CliError("usage", error.message.replace(/^error: /, ""));
+  loggedCliErrorObjects.add(refused);
+  return refused;
 };
 
 const handleOption = (programCommand: Command, argMeta: ArgMeta) => {
@@ -132,22 +167,34 @@ const assertEnumChoice = (argMeta: ArgMeta, value: unknown) => {
   if (!enumChoices || typeof enumChoices === "function") return;
   const choices = normalizeEnumChoices(enumChoices);
   if (choices.some((choice) => String(choice.value) === String(value))) return;
-  throw new Error(
+  throw new CliError(
+    "usage",
     `${argLabelOf(argMeta)} argument '${String(value)}' is invalid. Allowed choices are ${choices.map((choice) => choice.name).join(", ")}.`,
   );
 };
 
 // On a piped stdin a prompt takes the pipe as its answer and echoes it: a piped secret printed as the secret's name.
-export const assertPromptable = (
-  problem: string,
-  { choices = [], remedy = "pass it on the command line" }: { choices?: readonly unknown[]; remedy?: string } = {},
-) => {
+export const assertPromptable = (problem: string, refusal: Refusal = {}) => {
   if (process.stdin.isTTY) return;
-  throw new Error(
-    `${problem}: stdin is not a terminal to prompt on, so ${remedy}${choices.length ? ` (choices: ${choices.join(", ")})` : ""}.`,
-  );
+  throw refusalOf(problem, "stdin is not a terminal to prompt on", refusal);
 };
 
+interface Refusal {
+  choices?: readonly unknown[];
+  remedy?: string;
+  code?: CliErrorCode;
+}
+
+const refusalOf = (
+  problem: string,
+  reason: string,
+  { choices = [], remedy = "pass it on the command line", code = "usage" }: Refusal,
+) =>
+  new CliError(
+    code,
+    `${problem}: ${reason}, so ${remedy}${choices.length ? ` (choices: ${choices.join(", ")})` : ""}.`,
+  );
+
 const inputMessageOf = ({ name, argsOption: { desc, example, ask } }: ArgMeta) =>
   ask ? `${ask}: ` : desc ? `${desc}: ` : `Enter the ${name} value${example ? ` (example: ${example})` : ""}: `;
 
@@ -220,7 +267,8 @@ const assertCurrentDirectoryIsWorkspaceRoot = async () => {
   ]);
   if (hasPackageJson && hasTsConfig && hasMemberDirs.some(Boolean)) return;
 
-  throw new Error(
+  throw new CliError(
+    "usage",
     [
       "Akan CLI commands must be run from the workspace root.",
       `Current directory: ${cwd}`,
@@ -270,7 +318,8 @@ export const getAppsArgumentValue = async (
   if (requested.length) {
     const unknown = requested.filter((name) => !appNames.includes(name));
     if (unknown.length)
-      throw new Error(
+      throw new CliError(
+        "unknownTarget",
         `Unknown app${unknown.length > 1 ? "s" : ""}: ${unknown.join(", ")}. Available: ${appNames.join(", ")}, all`,
       );
     return [...new Set(requested)].map((name) => AppExecutor.from(workspace, name));
@@ -293,11 +342,29 @@ export const getInternalArgumentValue = async (
   value: string | undefined,
   workspace: WorkspaceExecutor,
   rerun?: RerunOf,
+  { destructive = false }: { destructive?: boolean } = {},
 ) => {
   if (argMeta.type === "Workspace") return workspace;
   const sysType = argMeta.type.toLowerCase();
   const [appNames, libNames, pkgNames] = await workspace.getExecs();
   const problemOf = (kind: string) => (value ? `Unknown ${kind} '${value}'` : `Missing ${kind}`);
+  //? Refused in a terminal too: a select deletes on a stray Enter, its cursor resting on the first choice.
+  const assertAskable = (kind: string, choices: readonly unknown[], placeholder: string) => {
+    const refusal: Refusal = { choices, code: value ? "unknownTarget" : "usage", ...rerunRemedyOf(rerun, placeholder) };
+    if (destructive) throw refusalOf(problemOf(kind), "this command deletes files and never picks its target", refusal);
+    assertPromptable(problemOf(kind), refusal);
+  };
+  const takeOnly = <Target>(kind: string, names: readonly string[], take: (name: string) => Target) => {
+    const [only] = names;
+    if (value || destructive || process.stdin.isTTY || names.length !== 1 || !only) return null;
+    const how = rerun ? `: ${rerun(only)}` : "";
+    Logger.rawLog(
+      `No ${kind} named, so this runs on '${only}', the only one in this workspace${how}`,
+      undefined,
+      "error",
+    );
+    return take(only);
+  };
   if (sysType === "sys" || sysType === "exec") {
     const pkgChoices = sysType === "exec" ? pkgNames : [];
     const execOf = (name: string) => {
@@ -308,70 +375,73 @@ export const getInternalArgumentValue = async (
     };
     const found = value ? execOf(value) : null;
     if (found) return found;
-    if (!value && argMeta.option?.onlyApp && appNames.length === 1 && appNames[0])
+    if (!value && !destructive && argMeta.option?.onlyApp && appNames.length === 1 && appNames[0])
       return AppExecutor.from(workspace, appNames[0]);
     const [kind, placeholder] =
       sysType === "exec" ? ["app, lib or pkg", "<app-lib-or-pkg>"] : ["app or lib", "<app-or-lib>"];
     const choices = [...appNames, ...libNames, ...pkgChoices];
-    const only = choices.length === 1 ? execOf(choices[0] ?? "") : null;
-    //? Not for Lib, Pkg or Module, which name what a command acts on: `akan remove-library` would delete the only one.
-    if (!value && only && !process.stdin.isTTY) {
-      const how = rerun ? `: ${rerun(only.name)}` : "";
-      Logger.rawLog(
-        `No ${kind} named, so this runs on '${only.name}', the only one in this workspace${how}`,
-        undefined,
-        "error",
-      );
-      return only;
-    }
-    assertPromptable(problemOf(kind), { choices, ...rerunRemedyOf(rerun, placeholder) });
+    const only = takeOnly(kind, choices, execOf);
+    if (only) return only;
+    assertAskable(kind, choices, placeholder);
     const name = await select<string>({
       message: sysType === "exec" ? `Select the App or Lib or Pkg name` : `Select the App or Lib name`,
       choices,
     });
     const picked = execOf(name);
-    if (!picked) throw new Error(`Invalid system name: ${name}`);
+    if (!picked) throw new CliError("unknownTarget", `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]);
-    assertPromptable(problemOf("app"), { choices: appNames, ...rerunRemedyOf(rerun, "<app>") });
+    if (!value && !destructive && appNames.length === 1 && appNames[0]) return AppExecutor.from(workspace, appNames[0]);
+    assertAskable("app", appNames, "<app>");
     const appName = await select<string>({ message: `Select the ${sysType} name`, choices: appNames });
     return AppExecutor.from(workspace, appName);
   } else if (sysType === "lib") {
     if (value && libNames.includes(value)) return LibExecutor.from(workspace, value);
-    assertPromptable(problemOf("lib"), { choices: libNames, ...rerunRemedyOf(rerun, "<lib>") });
+    const only = takeOnly("lib", libNames, (name) => LibExecutor.from(workspace, name));
+    if (only) return only;
+    assertAskable("lib", libNames, "<lib>");
     const libName = await select<string>({ message: `Select the ${sysType} name`, choices: libNames });
     return LibExecutor.from(workspace, libName);
   } else if (sysType === "pkg") {
     const pkgs = await workspace.getPkgs();
     if (value && pkgs.includes(value)) return PkgExecutor.from(workspace, value);
-    assertPromptable(problemOf("pkg"), { choices: pkgs, ...rerunRemedyOf(rerun, "<pkg>") });
+    const only = takeOnly("pkg", pkgs, (name) => PkgExecutor.from(workspace, name));
+    if (only) return only;
+    assertAskable("pkg", pkgs, "<pkg>");
     const pkgName = await select<string>({ message: `Select the ${sysType} name`, choices: pkgs });
     return PkgExecutor.from(workspace, pkgName);
   } else if (sysType === "module") {
-    if (value) {
-      const [sysName, moduleName] = value.split(":");
-      if (!sysName || !moduleName) throw new Error(`Invalid module name: ${value}`);
-      if (appNames.includes(sysName)) {
-        const app = AppExecutor.from(workspace, sysName);
-        const modules = await app.getModules();
-        if (modules.includes(moduleName)) return ModuleExecutor.from(app, moduleName);
-        else throw new Error(`Invalid module name: ${moduleName}`);
-      } else if (libNames.includes(sysName)) {
-        const lib = LibExecutor.from(workspace, sysName);
-        const modules = await lib.getModules();
-        if (modules.includes(moduleName)) return ModuleExecutor.from(lib, moduleName);
-      } else throw new Error(`Invalid system name: ${sysName}`);
-    }
     const systems = [
       ...appNames.map((name) => AppExecutor.from(workspace, name)),
       ...libNames.map((name) => LibExecutor.from(workspace, name)),
     ];
-    const choices = process.stdin.isTTY
-      ? []
-      : (await Promise.all(systems.map(async (sys) => (await sys.getModules()).map((m) => `${sys.name}:${m}`)))).flat();
-    assertPromptable(problemOf("module"), { choices, ...rerunRemedyOf(rerun, "<sys:module>") });
+    const modulesOf = async (sys: SysExecutor) => [
+      ...(await sys.getModules()),
+      ...(argMeta.option?.services ? await sys.getServiceModules() : []),
+    ];
+    const listModules = async () =>
+      (await Promise.all(systems.map(async (sys) => (await modulesOf(sys)).map((m) => `${sys.name}:${m}`)))).flat();
+    if (value) {
+      const [sysName, moduleName] = value.split(":");
+      if (!sysName || !moduleName) throw new CliError("usage", `Invalid module name: ${value}`);
+      const sys = systems.find((each) => each.name === sysName);
+      if (!sys) throw new CliError("unknownTarget", `Invalid system name: ${sysName}`);
+      if ((await modulesOf(sys)).includes(moduleName)) return ModuleExecutor.from(sys, moduleName);
+      throw refusalOf(problemOf("module"), `${sysName} has no such module`, {
+        code: "unknownTarget",
+        choices: await listModules(),
+        ...rerunRemedyOf(rerun, "<sys:module>"),
+      });
+    }
+    const choices = process.stdin.isTTY && !destructive ? [] : await listModules();
+    const only = takeOnly("module", choices, (label) => {
+      const [sysName, moduleName = ""] = label.split(":");
+      const sys = systems.find((each) => each.name === sysName);
+      return sys ? ModuleExecutor.from(sys, moduleName) : null;
+    });
+    if (only) return only;
+    assertAskable("module", choices, "<sys:module>");
     const { type, name } = await select<{ type: "app" | "lib"; name: string }>({
       message: `select the App or Lib name`,
       choices: [
@@ -380,7 +450,7 @@ export const getInternalArgumentValue = async (
       ],
     });
     const executor = type === "app" ? AppExecutor.from(workspace, name) : LibExecutor.from(workspace, name);
-    const modules = await executor.getModules();
+    const modules = await modulesOf(executor);
     const moduleName = await select<string>({
       message: `Select the module name`,
       choices: modules.map((name) => ({ name: `${executor.name}:${name}`, value: name })),
@@ -389,13 +459,33 @@ export const getInternalArgumentValue = async (
   } else throw new Error(`Invalid system type: ${argMeta.type}`);
 };
 
+const cliFailureOf = () => {
+  let failing = false;
+  const failure = {
+    exitCode: 1,
+    usageExitCode: undefined as number | undefined,
+    stream: "log" as "log" | "error",
+    report: async (_error: unknown) => {},
+    exitCodeOf: (error: unknown) => {
+      const { usageExitCode } = failure;
+      if (usageExitCode !== undefined && error instanceof CliError && CliError.usageCodes.includes(error.code))
+        return usageExitCode;
+      return CliError.exitCodeOf(error) ?? failure.exitCode;
+    },
+    fail: async (error: unknown) => {
+      if (failing) return;
+      failing = true;
+      printCliError(error, failure.stream);
+      await failure.report(error).catch((reportError: unknown) => printCliError(reportError, "error"));
+      process.exit(failure.exitCodeOf(error));
+    },
+  };
+  return failure;
+};
+
 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);
-  });
+  const failure = cliFailureOf();
+  process.on("unhandledRejection", (error) => void failure.fail(error));
   const __dirname = getDirname(import.meta.url);
   const packageJsonCandidates = [`${path.dirname(Bun.main)}/package.json`, `${__dirname}/../package.json`];
   let cliPackageJson: PackageJson | null = null;
@@ -429,21 +519,16 @@ export const runCommands = async (...commands: CommandCls[]) => {
         let programCommand = program.command(commandName, {
           hidden: targetMeta.targetOption.devOnly,
         });
-        const targetFailureExitCode = targetMeta.targetOption.failureExitCode;
-        const usageExitCode = targetMeta.targetOption.usageExitCode ?? targetFailureExitCode;
+        const { failureExitCode: targetFailureExitCode, usageExitCode: targetUsageExitCode } = targetMeta.targetOption;
         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;
-          });
+        programCommand.exitOverride((error) => {
+          const refused = usageRefusalOf(error);
+          failure.usageExitCode = targetUsageExitCode;
+          const given = givenOptionsOf(allArgMetas, programCommand.opts());
+          failure.report = failureReporterOf(asksJson(allArgMetas, given), onFailure, { 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);
@@ -472,12 +557,17 @@ export const runCommands = async (...commands: CommandCls[]) => {
         };
 
         programCommand.action(async (...args: unknown[]) => {
-          failureExitCode = targetFailureExitCode ?? 1;
+          failure.exitCode = targetFailureExitCode ?? 1;
+          failure.usageExitCode = targetUsageExitCode;
           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 json = asksJson(allArgMetas, opt);
+          failure.stream = json ? "error" : "log";
+          failure.report = failureReporterOf(json, onFailure, {
+            usage: false,
+            given: givenOptionsOf(allArgMetas, opt),
+          });
           const commandArgs = [] as unknown[];
           if (targetMeta.targetOption.runsOnWorkspaceRoot) {
             await assertCurrentDirectoryIsWorkspaceRoot();
@@ -503,6 +593,7 @@ export const runCommands = async (...commands: CommandCls[]) => {
                 cmdArgs[argMeta.idx] as string,
                 workspace,
                 rerun,
+                { destructive: targetMeta.targetOption.destructive },
               );
             if (commandArgs[argMeta.idx] instanceof AppExecutor)
               process.env.AKAN_PUBLIC_APP_NAME = (commandArgs[argMeta.idx] as AppExecutor).name;
@@ -520,17 +611,16 @@ export const runCommands = async (...commands: CommandCls[]) => {
             await targetMeta.handler.call(cmd, ...commandArgs);
             if (!targetMeta.targetOption.stdio) Logger.rawLog();
           } catch (e) {
-            printCliError(e);
+            printCliError(e, failure.stream);
             throw e;
           }
         });
       }
     }
   }
-  // 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(async (error: unknown) => {
-    printCliError(error);
-    await reportFailure(error).catch(printCliError);
-    process.exit(ExitCodeError.codeOf(error) ?? failureExitCode);
+  program.exitOverride((error) => {
+    throw usageRefusalOf(error);
   });
+  // 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(failure.fail);
 };