@visulima/cerebro 3.0.0-alpha.11 → 3.0.0-alpha.13

package/README.md

@@ -158,6 +158,32 @@ You should see help output and command execution based on the options provided:
 
 ![Cli Output](./__assets__/cli_output.png)
 
+## Lazy commands
+
+For CLIs with many subcommands or heavy per-command dependencies, you can defer importing each handler until the command is actually invoked. Declare the metadata inline and point `loader` at a dynamic `import()`:
+
+```ts
+// commands/build.ts
+export default ({ logger, options }) => {
+    logger.info(`Building to ${options.output ?? "dist"}`);
+};
+```
+
+```ts
+// index.ts
+cli.addCommand({
+    name: "build",
+    description: "Build the project",
+    options: [{ name: "output", alias: "o", type: String, description: "Output directory" }],
+    argument: { name: "target", type: String },
+    loader: () => import("./commands/build"),
+});
+```
+
+`loader` is a zero-argument function that returns a promise resolving to a module — typically `() => import("./path")`. The handler module's **default export** is the toolbox-receiving function. Help, completion, and option validation work entirely from the metadata you declared on `addCommand` and never trigger the loader. The first invocation of the command imports the module; subsequent calls reuse the cached handler.
+
+A command may declare either `execute` or `loader`, but not both. If a loader rejects or returns a module without a default-exported function, a `CommandLoaderError` is thrown.
+
 ## Toolbox API
 
 When your command's `execute` function is called, it receives a toolbox object with various utilities and context. Here's what you can access:

package/dist/commands/completion-command.d.ts

@@ -1,6 +1,7 @@
-import type { Command as ICommand } from "../types/command.d.ts";
+import { C as Command } from "../packem_shared/plugin-manager.d-Du-YXFui.js";
+import '@visulima/tabular';
 /**
- * Generates shell completion scripts for the CLI application.
- */
-declare const completionCommand: ICommand;
-export default completionCommand;
+* Generates shell completion scripts for the CLI application.
+*/
+declare const completionCommand: Command;
+export { completionCommand as default };

package/dist/commands/help-command.d.ts

@@ -1,10 +1,10 @@
-import type { Command as ICommand, OptionDefinition } from "../types/command.d.ts";
-import type { Toolbox as IToolbox } from "../types/toolbox.d.ts";
-declare class HelpCommand<TLogger extends Console = Console> implements ICommand<OptionDefinition<string>, TLogger> {
-    name: string;
-    options: OptionDefinition<string>[];
-    private readonly commands;
-    constructor(commands: Map<string, ICommand<OptionDefinition<unknown>, TLogger>>);
-    execute(toolbox: IToolbox<TLogger>): void;
+import { O as OptionDefinition, C as Command, T as Toolbox } from "../packem_shared/plugin-manager.d-Du-YXFui.js";
+import '@visulima/tabular';
+declare class HelpCommand<TLogger extends Console = Console> implements Command<OptionDefinition<string>, TLogger> {
+  name: string;
+  options: OptionDefinition<string>[];
+  private readonly commands;
+  constructor(commands: Map<string, Command<OptionDefinition<unknown>, TLogger>>);
+  execute(toolbox: Toolbox<TLogger>): void;
 }
-export default HelpCommand;
+export { HelpCommand as default };

package/dist/commands/help-command.js

@@ -1,5 +1,5 @@
 import { inverse, cyan, green, yellow } from '@visulima/colorize';
-import { t as templateFormat, c as commandLineUsage } from '../packem_shared/index-DNXLgme3.js';
+import { t as templateFormat, c as commandLineUsage } from '../packem_shared/index--1UArng3.js';
 
 const defaultEnv = [
   {
@@ -98,6 +98,51 @@ const printGeneralHelp = (logger, runtime, commands, groupOption) => {
     )
   );
 };
+const findChildren = (commands, parentPath) => {
+  const matches = [];
+  for (const cmd of commands.values()) {
+    if (cmd.hidden) {
+      continue;
+    }
+    const commandPath = cmd.commandPath ?? [];
+    if (commandPath.length !== parentPath.length) {
+      continue;
+    }
+    let isMatch = true;
+    for (let index = 0; index < parentPath.length; index += 1) {
+      if (commandPath[index] !== parentPath[index]) {
+        isMatch = false;
+        break;
+      }
+    }
+    if (isMatch) {
+      matches.push(cmd);
+    }
+  }
+  return matches;
+};
+const printParentHelp = (logger, runtime, parentPath, children) => {
+  const parentDisplay = parentPath.join(" ");
+  const usageGroups = [
+    {
+      content: `${cyan(runtime.getCliName())} ${green(parentDisplay)} ${green("<subcommand>")} [positional arguments] ${yellow("[options]")}`,
+      header: inverse.cyan(" Usage ")
+    },
+    {
+      content: children.map((child) => {
+        const fullPath = [...child.commandPath ?? [], child.name].join(" ");
+        return [green(fullPath), child.description ?? ""];
+      }),
+      header: inverse.green(" Subcommands ")
+    },
+    { header: inverse.yellow(" Global Options "), optionList: runtime.getGlobalOptions() },
+    {
+      content: `Run "${cyan(runtime.getCliName())} ${green(`${parentDisplay} <subcommand>`)} ${yellow("--help")}" for help with a specific subcommand.`,
+      raw: true
+    }
+  ];
+  (logger.raw ?? logger.log)(commandLineUsage(usageGroups));
+};
 const printCommandHelp = (logger, runtime, commands, name) => {
   let command = commands.get(name);
   if (!command) {
@@ -110,6 +155,12 @@ const printCommandHelp = (logger, runtime, commands, name) => {
     }
   }
   if (!command) {
+    const parentPath = name.split(" ").filter(Boolean);
+    const children = parentPath.length > 0 ? findChildren(commands, parentPath) : [];
+    if (children.length > 0) {
+      printParentHelp(logger, runtime, parentPath, children);
+      return;
+    }
     logger.error(`Command "${name}" not found`);
     return;
   }
@@ -159,6 +210,17 @@ const printCommandHelp = (logger, runtime, commands, name) => {
       header: "Examples"
     });
   }
+  const ownPath = [...command.commandPath ?? [], command.name];
+  const ownChildren = findChildren(commands, ownPath);
+  if (ownChildren.length > 0) {
+    usageGroups.push({
+      content: ownChildren.map((child) => {
+        const fullPath = [...child.commandPath ?? [], child.name].join(" ");
+        return [green(fullPath), child.description ?? ""];
+      }),
+      header: inverse.green(" Subcommands ")
+    });
+  }
   (logger.raw ?? logger.log)(commandLineUsage(usageGroups));
 };
 class HelpCommand {

package/dist/commands/readme-command.d.ts

@@ -1,6 +1,7 @@
-import type { Command as ICommand } from "../types/command.d.ts";
+import { C as Command } from "../packem_shared/plugin-manager.d-Du-YXFui.js";
+import '@visulima/tabular';
 /**
- * Generates README documentation for cerebro CLI commands.
- */
-declare const readmeCommand: ICommand;
-export default readmeCommand;
+* Generates README documentation for cerebro CLI commands.
+*/
+declare const readmeCommand: Command;
+export { readmeCommand as default };

package/dist/commands/readme-command.js

@@ -31,7 +31,7 @@ const {
   dirname
 } = __cjs_getBuiltinModule("node:path");
 import GithubSlugger from 'github-slugger';
-import { c as commandLineUsage } from '../packem_shared/index-DNXLgme3.js';
+import { c as commandLineUsage } from '../packem_shared/index--1UArng3.js';
 import { g as getCwd, a as getVersions, b as getPlatform, c as getArch } from '../packem_shared/runtime-process-B6ZplyWn.js';
 
 const slugger = new GithubSlugger();

package/dist/commands/version-command.d.ts

@@ -1,3 +1,4 @@
-import type { Command as ICommand } from "../types/command.d.ts";
-declare const _default: ICommand;
-export default _default;
+import { C as Command } from "../packem_shared/plugin-manager.d-Du-YXFui.js";
+import '@visulima/tabular';
+declare const _default: Command;
+export { _default as default };