@visulima/cerebro 3.0.0-alpha.9 → 3.0.0

package/README.md

@@ -158,16 +158,45 @@ 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:
 
 ### Core Properties
 
-- **`logger`**: Logger instance for output (debug, info, warn, error)
+- **`logger`**: Logger instance for output (debug, info, warn, error). Verbosity-gated via `--quiet`/`--verbose`/`--debug`.
+- **`console`**: Alias for `logger`. Use it when porting goke-style code or when a `console`-named parameter reads more naturally.
 - **`options`**: Parsed command-line options (camelCase keys)
 - **`argument`**: Array of positional arguments
-- **`env`**: Environment variables (camelCase keys)
+- **`env`**: Environment variables (camelCase keys) processed from the command's `env: [...]` definitions
+- **`fs`**: Injected filesystem adapter (subset of `node:fs/promises`). Swap via `CliOptions.fs` for tests or sandboxed runtimes.
+- **`process`**: Runtime snapshot — `cwd`, `env`, `argv`, `stdin`, `exit`, `platform`, `arch`. Prefer this over the global `process` so commands stay portable across Node, Deno, Bun, and mocked test runtimes.
 - **`runtime`**: Reference to the CLI instance
 - **`argv`**: Original command-line arguments array
 
@@ -215,6 +244,157 @@ cli.addCommand({
 });
 ```
 
+## Runtime Injection
+
+Commands receive an injected `{ fs, console, process }` context on the toolbox. Prefer reading from these over reaching for `node:fs/promises`, the global `console`, or the global `process` — commands written against the injected context stay testable, portable across Node/Deno/Bun, and ready to run inside sandboxed environments like MCP servers.
+
+```ts
+import { Cerebro } from "@visulima/cerebro";
+
+const cli = new Cerebro("acme");
+
+cli.addCommand({
+    name: "login",
+    description: "Save an auth token",
+    options: [{ name: "token", type: String, description: "API token" }],
+    execute: async ({ fs, console, process, options }) => {
+        await fs.mkdir(".acme", { recursive: true });
+        await fs.writeFile(".acme/auth.json", JSON.stringify({ token: options.token }), "utf8");
+        console.log("saved credentials in", process.cwd);
+    },
+});
+
+await cli.run();
+```
+
+### Overriding the runtime
+
+Pass any of the new `CliOptions` to swap the runtime context. Each override defaults to a sensible host value:
+
+| Option          | Default                      | Used for                                                                           |
+| --------------- | ---------------------------- | ---------------------------------------------------------------------------------- |
+| `fs`            | `node:fs/promises` adapter   | Filesystem operations from `toolbox.fs`                                            |
+| `exit`          | Runtime-agnostic exit helper | `toolbox.process.exit`                                                             |
+| `env`           | Host `process.env`           | `toolbox.process.env` (does **not** affect `toolbox.env`)                          |
+| `stdin`         | `""` (empty string)          | `toolbox.process.stdin`                                                            |
+| `cwd`           | Runtime cwd                  | `toolbox.process.cwd`                                                              |
+| `logger`        | Verbosity-aware console shim | `toolbox.logger` and `toolbox.console`                                             |
+| `maxArguments`  | A very generous cap          | Upper bound on argv tokens; set `Number.POSITIVE_INFINITY` to disable entirely     |
+| `strictOptions` | `false`                      | Reject unknown `--options` (before `--`) with a did-you-mean instead of swallowing |
+
+```ts
+const exitSpy = vi.fn();
+const fakeFs = new InMemoryFs();
+
+const cli = new Cerebro("acme", {
+    cwd: "/virtual/project",
+    fs: fakeFs,
+    exit: exitSpy,
+    env: { NODE_ENV: "test" },
+    stdin: "y\n",
+});
+```
+
+### Testing with mocked runtime
+
+The runtime overrides remove the need for `vi.spyOn(process, "exit")` or `vi.spyOn(console, "log")` in command tests. Pass mocks at CLI construction; assert on them directly.
+
+```ts
+import { describe, expect, test, vi } from "vitest";
+import { Cerebro } from "@visulima/cerebro";
+
+describe("deploy command", () => {
+    test("exits with code 2 when env is missing", async () => {
+        const exit = vi.fn();
+        const calls: string[] = [];
+        const logger = {
+            log: (...args: unknown[]) => calls.push(String(args[0])),
+            info: () => {},
+            warn: () => {},
+            error: () => {},
+            debug: () => {},
+        };
+
+        const cli = new Cerebro("acme", { argv: ["deploy"], exit, logger });
+        cli.addCommand({
+            name: "deploy",
+            execute: ({ console, process, options }) => {
+                if (!options.env) {
+                    console.log("missing --env");
+                    process.exit(2);
+                }
+            },
+        });
+
+        await cli.run({ shouldExitProcess: false });
+
+        expect(exit).toHaveBeenCalledWith(2);
+        expect(calls).toStrictEqual(["missing --env"]);
+    });
+});
+```
+
+### `cli.clone(options?)`
+
+Creates an independent CLI sharing the same command definitions. The clone has its own commands map, global options, default-command setting, and plugin manager — so adding commands or changing options on the clone never mutates the original. Primarily useful in tests to run the same CLI with different `argv`/`exit`/`fs` overrides without rebuilding the command tree.
+
+```ts
+const cli = new Cerebro("acme");
+cli.addCommand({ name: "build", execute: ({ console }) => console.log("building") });
+
+// In tests: clone with mocked exit + captured argv
+const isolatedExit = vi.fn();
+const isolated = cli.clone({ argv: ["build"], exit: isolatedExit });
+await isolated.run({ shouldExitProcess: false });
+```
+
+### `cli.getAction(commandName)`
+
+Returns the resolved `execute` function for a registered command. For lazy commands defined with `loader`, the module is loaded once and cached. Supports space-separated nested command paths.
+
+```ts
+const cli = new Cerebro("acme");
+
+cli.addCommand({
+    name: "deploy",
+    execute: ({ console, options }) => console.log("deploying to", options.env),
+});
+
+// Call the action directly with a synthesized toolbox — no argv parsing.
+const action = await cli.getAction("deploy");
+await action({ console: fakeConsole, options: { env: "staging" } } as never);
+```
+
+Use this when you want to unit-test a command action in isolation without going through `run()`'s full lifecycle (plugin init, exception handlers, exit). For end-to-end tests that exercise argv parsing and lifecycle hooks, prefer `cli.clone(...).run(...)` instead.
+
+## Validating option values with `choices`
+
+Restrict an option to a fixed set of values, validated at parse time (like commander's `.choices()` / yargs `choices`). For `multiple` options every provided value must be a member of the set. An invalid value throws an `InvalidChoiceError` with a hint listing the allowed values.
+
+```ts
+cli.addCommand({
+    name: "fmt",
+    options: [{ name: "format", type: String, choices: ["json", "yaml", "table"] }],
+    execute: ({ options }) => {
+        // options.format is guaranteed to be one of json | yaml | table
+    },
+});
+
+// `mycli fmt --format xml` →  Invalid value "xml" for option "format". Allowed values: json, yaml, table
+```
+
+## Strict unknown-option handling
+
+By default, unknown long options on commands that accept a positional `argument` are routed to `toolbox.rawUnknown` (the passthrough buffer) rather than rejected. Set `strictOptions: true` to fail fast on a typo'd flag — tokens after a `--` separator are always preserved as passthrough.
+
+```ts
+const cli = new Cerebro("mycli", { argv: ["build", "app", "--produciton"], strictOptions: true });
+// → throws UnknownOptionError: Found unknown option: --produciton  (Did you mean: --production?)
+
+// Tokens after `--` are still passthrough, even in strict mode:
+// `mycli build app -- --produciton`  →  toolbox.rawUnknown === ["--produciton"]
+```
+
 ## Built-in Commands
 
 Cerebro comes with several built-in commands that are automatically available:

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/command.d-DbhtfXF4.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/completion-command.js

@@ -1,203 +1,5 @@
-import tab from '@bomb.sh/tab';
-import { C as CerebroError } from '../packem_shared/cerebro-error-GmJ3jN7Q.js';
-
-class CompletionError extends CerebroError {
-  troubleshooting;
-  constructor(message, code, troubleshooting = []) {
-    super(message, code, { troubleshooting });
-    this.name = "CompletionError";
-    this.troubleshooting = troubleshooting;
-    if (troubleshooting.length > 0) {
-      this.hint = troubleshooting.join("\n");
-    }
-  }
-}
-
-const validShells = ["bash", "zsh", "fish", "powershell"];
-const validRuntimes = ["node", "bun", "deno"];
-const hasDeno = (global) => "Deno" in global;
-const hasBun = (global) => "Bun" in global;
-const detectRuntime = () => {
-  if (hasDeno(globalThis)) {
-    return "deno";
-  }
-  if (hasBun(globalThis)) {
-    return "bun";
-  }
-  return "node";
-};
-const detectShell = (toolboxEnv) => {
-  const starshipShell = toolboxEnv?.starshipShell;
-  const shell = starshipShell ?? toolboxEnv?.shell;
-  if (shell) {
-    const shellPath = shell.toLowerCase();
-    if (shellPath.includes("zsh")) {
-      return "zsh";
-    }
-    if (shellPath.includes("bash")) {
-      return "bash";
-    }
-    if (shellPath.includes("fish")) {
-      return "fish";
-    }
-  }
-  const psModulePath = toolboxEnv?.psModulePath;
-  const prompt = toolboxEnv?.prompt;
-  if (psModulePath || prompt?.includes("PS")) {
-    return "powershell";
-  }
-  const comSpec = toolboxEnv?.comSpec;
-  if (comSpec?.toLowerCase().includes("cmd.exe")) {
-    return "bash";
-  }
-  return void 0;
-};
-const tabInstance = tab;
-const registerCommandOptions = (cmd, options) => {
-  for (const option of options) {
-    if (option.hidden) {
-      continue;
-    }
-    if (option.name) {
-      cmd.option(option.name, option.description || "");
-    }
-    if (option.alias) {
-      cmd.option(option.alias, option.description || "");
-    }
-  }
-};
-const registerCommands = (tabInstance2, commands) => {
-  for (const [commandName, command] of commands) {
-    if (command.name !== commandName || command.hidden) {
-      continue;
-    }
-    const cmd = tabInstance2.command(command.name, command.description || "");
-    if (command.options) {
-      registerCommandOptions(cmd, command.options);
-    }
-  }
-};
-const validateShell = (shell) => {
-  if (!validShells.includes(shell)) {
-    throw new CompletionError(`Invalid shell type: ${shell}`, "INVALID_SHELL", [
-      `Valid shells are: ${validShells.join(", ")}`,
-      "Shell will be auto-detected if not specified"
-    ]);
-  }
-};
-const validateRuntime = (runtime) => {
-  if (runtime && !validRuntimes.includes(runtime)) {
-    throw new CompletionError(`Invalid runtime: ${runtime}`, "INVALID_RUNTIME", [
-      `Valid runtimes are: ${validRuntimes.join(", ")}`,
-      "Runtime will be auto-detected if not specified"
-    ]);
-  }
-};
-const printUsageInstructions = (logger, cliName) => {
-  logger.error("Could not detect current shell");
-  const usageInfo = [
-    `Usage: ${cliName} completion --shell=<bash|zsh|fish|powershell> [--runtime=<node|bun|deno>]`,
-    "",
-    "Examples:",
-    `  # Install completions for zsh:`,
-    `  ${cliName} completion --shell=zsh > ~/.${cliName}-completion.zsh`,
-    `  echo 'source ~/.${cliName}-completion.zsh' >> ~/.zshrc`,
-    "",
-    `  # Install completions for bash with custom runtime:`,
-    `  ${cliName} completion --shell=bash --runtime=bun > ~/.${cliName}-completion.bash`,
-    `  echo 'source ~/.${cliName}-completion.bash' >> ~/.bashrc`,
-    "",
-    `  # Install completions for fish:`,
-    `  ${cliName} completion --shell=fish > ~/.config/fish/completions/${cliName}.fish`
-  ].join("\n");
-  logger.info(usageInfo);
-};
-const completionCommand = {
-  description: "Generate shell completion scripts",
-  env: [
-    {
-      description: "Shell path (Unix-like systems). Used for shell detection.",
-      name: "SHELL",
-      type: String
-    },
-    {
-      description: "Starship shell configuration. Takes precedence over SHELL for detection.",
-      name: "STARSHIP_SHELL",
-      type: String
-    },
-    {
-      description: "PowerShell module path (Windows). Used for PowerShell detection.",
-      name: "PSModulePath",
-      type: String
-    },
-    {
-      description: "Command prompt variable (Windows). Used for PowerShell detection.",
-      name: "PROMPT",
-      type: String
-    },
-    {
-      description: "Command processor (Windows). Used for Windows Command Prompt detection.",
-      name: "ComSpec",
-      type: String
-    }
-  ],
-  execute: async ({ env: toolboxEnv, logger, options, runtime }) => {
-    const cliName = runtime.getCliName();
-    const shell = options?.shell || detectShell(toolboxEnv);
-    if (!shell) {
-      printUsageInstructions(logger, cliName);
-      return;
-    }
-    try {
-      validateShell(shell);
-      validateRuntime(options?.runtime);
-      registerCommands(tabInstance, runtime.getCommands());
-      const jsRuntime = options?.runtime || detectRuntime();
-      const scriptPath = `${jsRuntime} ${cliName}`;
-      tabInstance.setup(cliName, scriptPath, shell);
-    } catch (error) {
-      if (error instanceof CompletionError) {
-        const errorMessages = [`Failed to generate completion script: ${error.message}`, `Error code: ${error.code}`];
-        if (error.troubleshooting.length > 0) {
-          errorMessages.push("", "Troubleshooting:", ...error.troubleshooting.map((tip) => `  • ${tip}`));
-        }
-        logger.error(errorMessages.join("\n"));
-        throw error;
-      } else {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        const errorMessages = [
-          "Failed to generate completion script",
-          `Error: ${errorMessage}`,
-          "",
-          "Troubleshooting:",
-          "  • Ensure @bomb.sh/tab is installed: pnpm add @bomb.sh/tab",
-          `  • Verify shell is supported: ${validShells.join(", ")}`,
-          `  • Verify runtime is supported: ${validRuntimes.join(", ")}`,
-          "  • Check that your CLI name is correct"
-        ];
-        logger.error(errorMessages.join("\n"));
-      }
-    }
-  },
-  name: "completion",
-  options: [
-    {
-      defaultOption: true,
-      defaultValue: detectShell(),
-      description: "Shell type (bash, zsh, fish, powershell). Defaults to current shell if detected.",
-      name: "shell",
-      type: String,
-      typeLabel: "{underline shell}"
-    },
-    {
-      defaultOption: true,
-      defaultValue: detectRuntime(),
-      description: "JavaScript runtime (node, bun, deno). Defaults to current runtime if detected.",
-      name: "runtime",
-      type: String,
-      typeLabel: "{underline runtime}"
-    }
-  ]
-};
-
-export { completionCommand as default };
+import{t as u}from"../packem_shared/cerebro-error-BjBcYVRO.js";class h extends u{troubleshooting;constructor(o,t,i=[]){super(o,t,{troubleshooting:i}),this.name="CompletionError",this.troubleshooting=i,i.length>0&&(this.hint=i.join(`
+`))}}const a=["bash","zsh","fish","powershell"],c=["node","bun","deno"],f=e=>"Deno"in e,b=e=>"Bun"in e,d=()=>f(globalThis)?"deno":b(globalThis)?"bun":"node",p=e=>{const o=e?.starshipShell??e?.shell;if(o){const s=o.toLowerCase();if(s.includes("zsh"))return"zsh";if(s.includes("bash"))return"bash";if(s.includes("fish"))return"fish"}const t=e?.psModulePath,i=e?.prompt;if(t||i?.includes("PS"))return"powershell";if(e?.comSpec?.toLowerCase().includes("cmd.exe"))return"bash"},g=async()=>(await import("@bomb.sh/tab")).default,S=(e,o)=>{for(const t of o)t.hidden||(t.name&&e.option(t.name,t.description??""),t.alias&&e.option(t.alias,t.description??""))},w=(e,o)=>{for(const[t,i]of o){if(i.name!==t||i.hidden)continue;const s=e.command(i.name,i.description??"");i.options&&S(s,i.options)}},$=e=>{if(!a.includes(e))throw new h(`Invalid shell type: ${e}`,"INVALID_SHELL",[`Valid shells are: ${a.join(", ")}`,"Shell will be auto-detected if not specified"])},y=e=>{if(e&&!c.includes(e))throw new h(`Invalid runtime: ${e}`,"INVALID_RUNTIME",[`Valid runtimes are: ${c.join(", ")}`,"Runtime will be auto-detected if not specified"])},L=(e,o)=>{e.error("Could not detect current shell");const t=[`Usage: ${o} completion --shell=<bash|zsh|fish|powershell> [--runtime=<node|bun|deno>]`,"","Examples:","  # Install completions for zsh:",`  ${o} completion --shell=zsh > ~/.${o}-completion.zsh`,`  echo 'source ~/.${o}-completion.zsh' >> ~/.zshrc`,"","  # Install completions for bash with custom runtime:",`  ${o} completion --shell=bash --runtime=bun > ~/.${o}-completion.bash`,`  echo 'source ~/.${o}-completion.bash' >> ~/.bashrc`,"","  # Install completions for fish:",`  ${o} completion --shell=fish > ~/.config/fish/completions/${o}.fish`].join(`
+`);e.info(t)},I={description:"Generate shell completion scripts",env:[{description:"Shell path (Unix-like systems). Used for shell detection.",name:"SHELL",type:String},{description:"Starship shell configuration. Takes precedence over SHELL for detection.",name:"STARSHIP_SHELL",type:String},{description:"PowerShell module path (Windows). Used for PowerShell detection.",name:"PSModulePath",type:String},{description:"Command prompt variable (Windows). Used for PowerShell detection.",name:"PROMPT",type:String},{description:"Command processor (Windows). Used for Windows Command Prompt detection.",name:"ComSpec",type:String}],execute:async({env:e,logger:o,options:t,runtime:i})=>{const s=i.getCliName(),l=t.shell??p(e);if(!l){L(o,s);return}try{$(l),y(t.runtime);const n=await g();w(n,i.getCommands());const r=`${t.runtime??d()} ${s}`;n.setup(s,r,l)}catch(n){if(n instanceof h){const r=[`Failed to generate completion script: ${n.message}`,`Error code: ${n.code}`];throw n.troubleshooting.length>0&&r.push("","Troubleshooting:",...n.troubleshooting.map(m=>`  • ${m}`)),o.error(r.join(`
+`)),n}else{const r=["Failed to generate completion script",`Error: ${n instanceof Error?n.message:String(n)}`,"","Troubleshooting:","  • Ensure @bomb.sh/tab is installed: pnpm add @bomb.sh/tab",`  • Verify shell is supported: ${a.join(", ")}`,`  • Verify runtime is supported: ${c.join(", ")}`,"  • Check that your CLI name is correct"];o.error(r.join(`
+`))}}},name:"completion",options:[{defaultOption:!0,defaultValue:p(),description:"Shell type (bash, zsh, fish, powershell). Defaults to current shell if detected.",name:"shell",type:String,typeLabel:"{underline shell}"},{defaultValue:d(),description:"JavaScript runtime (node, bun, deno). Defaults to current runtime if detected.",name:"runtime",type:String,typeLabel:"{underline runtime}"}]};export{I as default};

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

@@ -1,10 +1,11 @@
-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, A as ArgumentDefinition, C as Command, T as Toolbox } from "../packem_shared/command.d-DbhtfXF4.js";
+import '@visulima/tabular';
+declare class HelpCommand<TLogger extends Console = Console> implements Command<OptionDefinition<string>, TLogger> {
+  argument: ArgumentDefinition<string>;
+  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,3 +1 @@
-import '@visulima/colorize';
-export { H as default } from '../packem_shared/help-command-BY7rQUvM.js';
-import '../packem_shared/index-C2-8b3A4.js';
+import{inverse as p,cyan as u,green as h,yellow as g}from"@visulima/colorize";import{a as y,r as f}from"../packem_shared/index-B7-8G-9s.js";const O=[{defaultValue:"32",description:"Controls the verbosity level of output. Valid values: '16' (quiet), '32' (normal), '64' (verbose), '128' (debug)",name:"CEREBRO_OUTPUT_LEVEL",type:String},{description:"Sets the minimum required Node.js version. Overrides the default minimum version check",name:"CEREBRO_MIN_NODE_VERSION",type:Number},{defaultValue:!1,description:"When set, disables the update notifier check",name:"NO_UPDATE_NOTIFIER",type:Boolean},{description:"Standard Node.js environment variable. When set to 'test', disables update notifier",name:"NODE_ENV",type:String},{defaultValue:!1,description:"When set, enables debug output (same as --debug flag)",name:"DEBUG",type:Boolean},{description:"Sets the terminal width for table rendering. Useful for testing and consistent output",name:"CEREBRO_TERMINAL_WIDTH",type:Number}],b="__Other",v=s=>s.charAt(0).toUpperCase()+s.slice(1),w=(s,r,l,o)=>{s.debug("no command given, printing general help...");let m=[...new Set(l.values())].filter(n=>!n.hidden);o&&(m=m.filter(n=>n.group===o));const e=m.reduce((n,i)=>{const d=i.group??b;return n[d]??=[],n[d].push(i),n},{}),a=n=>n.map(i=>{let d="";typeof i.alias=="string"?d=i.alias:Array.isArray(i.alias)&&(d=i.alias.join(", ")),d!==""&&(d=` [${d}]`);let t=i.name;return i.commandPath&&i.commandPath.length>0&&(t=`${i.commandPath.join(" ")} ${i.name}`),[`${h(t)}${d}`,i.description??""]});(s.raw??s.log)(f([{content:`${u(r.getCliName())} ${h("<command>")} [positional arguments] ${g("[options]")}`,header:p.cyan(" Usage ")},...Object.keys(e).map(n=>{const i=o?` ${v(o)}`:"";return{content:a(e[n]),header:n===b||o?p.green(` Available${i} Commands `):` ${p.green(` ${v(n)} `)}`}}),l.has("help")?{header:p.yellow(" Command Options "),optionList:l.get("help").options?.filter(n=>!n.hidden)}:void 0,{header:p.yellow(" Global Options "),optionList:r.getGlobalOptions()},{content:O.filter(n=>!n.hidden).map(n=>[n.name,n.description??""]),header:p.magenta(" Environment Variables ")},{content:`Run "${u(r.getCliName())} ${h("help <command>")}" or "${u(r.getCliName())} ${h("<command>")} ${g("--help")}" for help with a specific command.`,raw:!0}].filter(Boolean)))},$=(s,r)=>{const l=[];for(const o of s.values()){if(o.hidden)continue;const m=o.commandPath??[];if(m.length!==r.length)continue;let e=!0;for(const[a,n]of r.entries())if(m[a]!==n){e=!1;break}e&&l.push(o)}return l},E=(s,r,l,o)=>{const m=l.join(" "),e=[{content:`${u(r.getCliName())} ${h(m)} ${h("<subcommand>")} [positional arguments] ${g("[options]")}`,header:p.cyan(" Usage ")},{content:o.map(a=>{const n=[...a.commandPath??[],a.name].join(" ");return[h(n),a.description??""]}),header:p.green(" Subcommands ")},{header:p.yellow(" Global Options "),optionList:r.getGlobalOptions()},{content:`Run "${u(r.getCliName())} ${h(`${m} <subcommand>`)} ${g("--help")}" for help with a specific subcommand.`,raw:!0}];(s.raw??s.log)(f(e))},N=(s,r,l,o,m)=>{let e=m??l.get(o);if(!e)for(const t of l.values()){const c=t.commandPath?[...t.commandPath,t.name]:[t.name];if(c.at(-1)===o||c.join(" ")===o){e=t;break}}if(!e){const t=o.split(" ").filter(Boolean),c=t.length>0?$(l,t):[];if(c.length>0){E(s,r,t,c);return}s.error(`Command "${o}" not found`);return}const a=[],n=(e.commandPath?[...e.commandPath,e.name]:[e.name]).join(" ");if(a.push({content:`${u(r.getCliName())} ${h(n)}${e.argument?" [positional arguments]":""}${e.options?" [options]":""}`,header:p.cyan(" Usage ")}),e.description&&a.push({content:e.description,header:p.green(" Description ")}),e.argument&&a.push({header:"Command Positional Arguments",isArgument:!0,optionList:[e.argument]}),Array.isArray(e.options)&&e.options.length>0&&a.push({header:p.yellow(" Command Options "),optionList:e.options.filter(t=>!t.hidden)}),a.push({header:p.yellow(" Global Options "),optionList:r.getGlobalOptions()}),Array.isArray(e.env)&&e.env.length>0){const t=e.env.filter(c=>!c.hidden);t.length>0&&a.push({content:t.map(c=>[c.name,c.description??""]),header:p.magenta(" Environment Variables ")})}if(e.alias!==void 0&&e.alias.length>0){let t=e.alias;typeof e.alias=="string"&&(t=[e.alias]),a.splice(1,0,{content:t,header:"Alias(es)"})}Array.isArray(e.examples)&&e.examples.length>0&&a.push({content:e.examples,header:"Examples"});const i=[...e.commandPath??[],e.name],d=$(l,i);d.length>0&&a.push({content:d.map(t=>{const c=[...t.commandPath??[],t.name].join(" ");return[h(c),t.description??""]}),header:p.green(" Subcommands ")}),(s.raw??s.log)(f(a))};class P{argument={description:"Command to show help for (subcommand path supported, e.g. `cli help docker build`)",name:"command",type:String};name="help";options=[{description:"Display only the specified group",name:"group",type:String}];commands;constructor(r){this.commands=r}execute(r){const{argument:l,command:o,commandName:m,logger:e,options:a,runtime:n}=r,{footer:i,header:d}=n.getCommandSection();d&&(e.raw??e.log)(y(d));const t=m==="help"&&Array.isArray(l)&&l.length>0?l.join(" "):void 0;if(m==="help"&&t===void 0)w(e,n,this.commands,typeof a?.group=="string"?a.group:void 0);else{const c=t!==void 0||o===void 0||o.name==="help"?void 0:o;N(e,n,this.commands,t??m,c)}i&&(e.raw??e.log)(y(i))}}export{P as default};

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/command.d-DbhtfXF4.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 };