@visulima/cerebro 3.0.6 → 3.1.1

package/README.md

@@ -158,6 +158,46 @@ You should see help output and command execution based on the options provided:
 
 ![Cli Output](./__assets__/cli_output.png)
 
+### Typed commands with `defineCommand`
+
+`options` and `env` can also be given as records keyed by name. Wrap the command in
+`defineCommand` and the toolbox types are inferred from those definitions — no separate
+options interface to keep in sync, and a renamed option becomes a compile error rather
+than a silent `undefined`. `arguments` stays an array, because slot order is
+load-bearing, and its names stay typed without an `as const`:
+
+```ts
+import { Cerebro, defineCommand } from "@visulima/cerebro";
+
+const build = defineCommand({
+    name: "build",
+    description: "Build the project",
+    arguments: [{ name: "target", type: String, required: true, description: "Build target" }],
+    options: {
+        "output-dir": { alias: "o", type: String, defaultValue: "dist" },
+        production: { alias: "p", type: Boolean },
+        tags: { type: String, multiple: true },
+    },
+    env: {
+        NODE_ENV: { type: String },
+    },
+    execute: ({ args, env, logger, options }) => {
+        args.target; // string                — required
+        options.outputDir; // string                — has a defaultValue
+        options.production; // boolean | undefined
+        options.tags; // string[] | undefined
+        env.nodeEnv; // string | undefined
+
+        logger.info(`Building ${args.target} into ${options.outputDir}`);
+    },
+});
+
+new Cerebro("my-cli").addCommand(build);
+```
+
+The array form of `options`/`env` and the single `argument` field keep working unchanged —
+`defineCommand`, the record forms, and `arguments` are all purely additive.
+
 ## 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()`:
@@ -194,6 +234,7 @@ When your command's `execute` function is called, it receives a toolbox object w
 - **`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
+- **`args`**: Named positional arguments (camelCase keys) from the command's `arguments: [ ... ]` definitions; empty when none are declared
 - **`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.

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

@@ -1,4 +1,4 @@
-import { C as Command } from "../packem_shared/command.d-B_G9vIYJ.js";
+import { C as Command } from "../packem_shared/command.d-Dz7hkMI0.js";
 import '@visulima/tabular';
 /**
  * Generates shell completion scripts for the CLI application.

package/dist/commands/completion-command.js

@@ -1,5 +1,5 @@
-import{t as u}from"../packem_shared/cerebro-error-DWpjBY_M.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};
+import{C as u}from"../packem_shared/cerebro-error-Dv3FuXO8.js";class d extends u{troubleshooting;constructor(t,n,o=[]){super(t,n,{troubleshooting:o}),this.name="CompletionError",this.troubleshooting=o,o.length>0&&(this.hint=o.join(`
+`))}}const c=["bash","zsh","fish","powershell"],h=["node","bun","deno"],f=e=>"Deno"in e,S=e=>"Bun"in e,p=()=>f(globalThis)?"deno":S(globalThis)?"bun":"node",m=e=>{const n=e?.starshipShell??e?.shell;if(n){const s=n.toLowerCase();if(s.includes("zsh"))return"zsh";if(s.includes("bash"))return"bash";if(s.includes("fish"))return"fish"}const o=e?.psModulePath,i=e?.prompt;if(o||i?.includes("PS"))return"powershell";if(e?.comSpec?.toLowerCase().includes("cmd.exe"))return"bash"},b=async()=>(await import("@bomb.sh/tab")).default,g=(e,t)=>{for(const n of t)n.hidden||(n.name&&e.option(n.name,n.description??""),n.alias&&e.option(n.alias,n.description??""))},w=(e,t)=>{for(const[n,o]of t){if(o.name!==n||o.hidden)continue;const i=e.command(o.name,o.description??"");o.options&&g(i,o.options)}},$=e=>{if(!c.includes(e))throw new d(`Invalid shell type: ${e}`,"INVALID_SHELL",[`Valid shells are: ${c.join(", ")}`,"Shell will be auto-detected if not specified"])},y=e=>{if(e&&!h.includes(e))throw new d(`Invalid runtime: ${e}`,"INVALID_RUNTIME",[`Valid runtimes are: ${h.join(", ")}`,"Runtime will be auto-detected if not specified"])},C=(e,t)=>{e.error("Could not detect current shell");const n=[`Usage: ${t} completion --shell=<bash|zsh|fish|powershell> [--runtime=<node|bun|deno>]`,"","Examples:","  # Install completions for zsh:",`  ${t} completion --shell=zsh > ~/.${t}-completion.zsh`,`  echo 'source ~/.${t}-completion.zsh' >> ~/.zshrc`,"","  # Install completions for bash with custom runtime:",`  ${t} completion --shell=bash --runtime=bun > ~/.${t}-completion.bash`,`  echo 'source ~/.${t}-completion.bash' >> ~/.bashrc`,"","  # Install completions for fish:",`  ${t} completion --shell=fish > ~/.config/fish/completions/${t}.fish`].join(`
+`);e.info(n)},L={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:t,options:n,runtime:o})=>{const i=o.getCliName(),l=n.shell??m(e);if(!l){C(t,i);return}try{$(l),y(n.runtime);const s=await b();w(s,o.getCommands());const r=`${n.runtime??p()} ${i}`;s.setup(i,r,l)}catch(s){if(s instanceof d){const a=[`Failed to generate completion script: ${s.message}`,`Error code: ${s.code}`];throw s.troubleshooting.length>0&&a.push("","Troubleshooting:",...s.troubleshooting.map(r=>`  • ${r}`)),t.error(a.join(`
+`)),s}else{const r=["Failed to generate completion script",`Error: ${s instanceof Error?s.message:String(s)}`,"","Troubleshooting:","  • Ensure @bomb.sh/tab is installed: pnpm add @bomb.sh/tab",`  • Verify shell is supported: ${c.join(", ")}`,`  • Verify runtime is supported: ${h.join(", ")}`,"  • Check that your CLI name is correct"];t.error(r.join(`
+`))}}},name:"completion",options:[{defaultOption:!0,defaultValue:m(),description:"Shell type (bash, zsh, fish, powershell). Defaults to current shell if detected.",name:"shell",type:String,typeLabel:"{underline shell}"},{defaultValue:p(),description:"JavaScript runtime (node, bun, deno). Defaults to current runtime if detected.",name:"runtime",type:String,typeLabel:"{underline runtime}"}]};export{L as default};

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

@@ -1,4 +1,4 @@
-import { O as OptionDefinition, A as ArgumentDefinition, C as Command, T as Toolbox } from "../packem_shared/command.d-B_G9vIYJ.js";
+import { O as OptionDefinition, A as ArgumentDefinition, C as Command, T as Toolbox } from "../packem_shared/command.d-Dz7hkMI0.js";
 import '@visulima/tabular';
 declare class HelpCommand<TLogger extends Console = Console> implements Command<OptionDefinition<string>, TLogger> {
   argument: ArgumentDefinition<string>;

package/dist/commands/help-command.js

@@ -1 +1 @@
-import{inverse as p,cyan as u,green as h,yellow as g}from"@visulima/colorize";import{o as y,r as f}from"../packem_shared/index-Dpm7gUHe.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};
+import{inverse as d,cyan as f,green as h,yellow as y}from"@visulima/colorize";import{t as v,c as b,f as E}from"../packem_shared/format-positional-usage-DWL9qN10.js";const N=[{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}],$="__Other",C=r=>r.charAt(0).toUpperCase()+r.slice(1),w=(r,s,l,o)=>{r.debug("no command given, printing general help...");let m=[...new Set(l.values())].filter(t=>!t.hidden);o&&(m=m.filter(t=>t.group===o));const e=m.reduce((t,i)=>{const p=i.group??$;return t[p]??=[],t[p].push(i),t},{}),a=t=>t.map(i=>{let p="";typeof i.alias=="string"?p=i.alias:Array.isArray(i.alias)&&(p=i.alias.join(", ")),p!==""&&(p=` [${p}]`);let u=i.name;return i.commandPath&&i.commandPath.length>0&&(u=`${i.commandPath.join(" ")} ${i.name}`),[`${h(u)}${p}`,i.description??""]});(r.raw??r.log)(b([{content:`${f(s.getCliName())} ${h("<command>")} [positional arguments] ${y("[options]")}`,header:d.cyan(" Usage ")},...Object.keys(e).map(t=>{const i=o?` ${C(o)}`:"";return{content:a(e[t]),header:t===$||o?d.green(` Available${i} Commands `):` ${d.green(` ${C(t)} `)}`}}),l.has("help")?{header:d.yellow(" Command Options "),optionList:l.get("help").options?.filter(t=>!t.hidden)}:void 0,{header:d.yellow(" Global Options "),optionList:s.getGlobalOptions()},{content:N.filter(t=>!t.hidden).map(t=>[t.name,t.description??""]),header:d.magenta(" Environment Variables ")},{content:`Run "${f(s.getCliName())} ${h("help <command>")}" or "${f(s.getCliName())} ${h("<command>")} ${y("--help")}" for help with a specific command.`,raw:!0}].filter(Boolean)))},P=(r,s)=>{const l=[];for(const o of r.values()){if(o.hidden)continue;const m=o.commandPath??[];if(m.length!==s.length)continue;let e=!0;for(const[a,t]of s.entries())if(m[a]!==t){e=!1;break}e&&l.push(o)}return l},O=(r,s,l,o)=>{const m=l.join(" "),e=[{content:`${f(s.getCliName())} ${h(m)} ${h("<subcommand>")} [positional arguments] ${y("[options]")}`,header:d.cyan(" Usage ")},{content:o.map(a=>{const t=[...a.commandPath??[],a.name].join(" ");return[h(t),a.description??""]}),header:d.green(" Subcommands ")},{header:d.yellow(" Global Options "),optionList:s.getGlobalOptions()},{content:`Run "${f(s.getCliName())} ${h(`${m} <subcommand>`)} ${y("--help")}" for help with a specific subcommand.`,raw:!0}];(r.raw??r.log)(b(e))},A=(r,s,l,o,m)=>{let e=m??l.get(o);if(!e)for(const n of l.values()){const c=n.commandPath?[...n.commandPath,n.name]:[n.name];if(c.at(-1)===o||c.join(" ")===o){e=n;break}}if(!e){const n=o.split(" ").filter(Boolean),c=n.length>0?P(l,n):[];if(c.length>0){O(r,s,n,c);return}r.error(`Command "${o}" not found`);return}const a=[],i=(e.commandPath?[...e.commandPath,e.name]:[e.name]).join(" ");a.push({content:`${f(s.getCliName())} ${h(i)}${E(e)}${e.options?" [options]":""}`,header:d.cyan(" Usage ")}),e.description&&a.push({content:e.description,header:d.green(" Description ")});const p=(e.argument?[e.argument]:e.arguments??[]).filter(n=>!n.hidden);if(p.length>0&&a.push({header:"Command Positional Arguments",isArgument:!0,optionList:p}),Array.isArray(e.options)&&e.options.length>0&&a.push({header:d.yellow(" Command Options "),optionList:e.options.filter(n=>!n.hidden)}),a.push({header:d.yellow(" Global Options "),optionList:s.getGlobalOptions()}),Array.isArray(e.env)&&e.env.length>0){const n=e.env.filter(c=>!c.hidden);n.length>0&&a.push({content:n.map(c=>[c.name,c.description??""]),header:d.magenta(" Environment Variables ")})}if(e.alias!==void 0&&e.alias.length>0){let n=e.alias;typeof e.alias=="string"&&(n=[e.alias]),a.splice(1,0,{content:n,header:"Alias(es)"})}Array.isArray(e.examples)&&e.examples.length>0&&a.push({content:e.examples,header:"Examples"});const u=[...e.commandPath??[],e.name],g=P(l,u);g.length>0&&a.push({content:g.map(n=>{const c=[...n.commandPath??[],n.name].join(" ");return[h(c),n.description??""]}),header:d.green(" Subcommands ")}),(r.raw??r.log)(b(a))};class S{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(s){this.commands=s}execute(s){const{argument:l,command:o,commandName:m,logger:e,options:a,runtime:t}=s,{footer:i,header:p}=t.getCommandSection();p&&(e.raw??e.log)(v(p));const u=m==="help"&&Array.isArray(l)&&l.length>0?l.join(" "):void 0;if(m==="help"&&u===void 0)w(e,t,this.commands,typeof a?.group=="string"?a.group:void 0);else{const g=u!==void 0||o===void 0||o.name==="help"?void 0:o;A(e,t,this.commands,u??m,g)}i&&(e.raw??e.log)(v(i))}}export{S as default};

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

@@ -1,4 +1,4 @@
-import { C as Command } from "../packem_shared/command.d-B_G9vIYJ.js";
+import { C as Command } from "../packem_shared/command.d-Dz7hkMI0.js";
 import '@visulima/tabular';
 /**
  * Generates README documentation for cerebro CLI commands.

package/dist/commands/readme-command.js

@@ -1,36 +1,36 @@
-import{createRequire as x}from"node:module";import{r as N}from"../packem_shared/index-Dpm7gUHe.js";import{g as q,a as V,b as G}from"../packem_shared/runtime-process-BEw54Ar-.js";let S;const O=e=>(S??=x(import.meta.url))(e),h=typeof globalThis<"u"&&typeof globalThis.process<"u"?globalThis.process:process,k=e=>{if(typeof h<"u"&&h.versions&&h.versions.node){const[n,t]=h.versions.node.split(".").map(Number);if(n>22||n===22&&t>=3||n===20&&t>=16)return h.getBuiltinModule(e)}return O(e)},{resolve:P,join:B,dirname:L}=k("node:path"),v=async(e,n)=>{try{return await e.access(n),!0}catch{return!1}},T=async()=>{const{default:e}=await import("github-slugger"),n=new e;return t=>n.slug(t)},U=e=>e.filter(Boolean),F=(e,n)=>{const t=new Set,r=[];for(const a of e){const o=n(a);t.has(o)||(t.add(o),r.push(a))}return r},_=(e,n)=>{const t=(e.commandPath?[...e.commandPath,e.name]:[e.name]).join(" ");if(e.argument){const r=e.argument.name.toUpperCase(),a=e.argument.required?r:`[${r}]`;return`${n} ${t} ${a}`}return`${n} ${t}`},I=(e,n)=>{if(!Array.isArray(e.env)||e.env.length===0)return;const t=e.env.filter(r=>!r.hidden);t.length>0&&n.push({content:t.map(r=>[r.name,r.description??""]),header:" Environment Variables "})},W=(e,n)=>{const t=[],r=(e.commandPath?[...e.commandPath,e.name]:[e.name]).join(" "),a=!!e.argument,o=!!e.options;if(t.push({content:`${n} ${r}${a?" [positional arguments]":""}${o?" [options]":""}`,header:" Usage "}),e.description&&t.push({content:e.description,header:" Description "}),e.argument&&t.push({header:"Command Positional Arguments",isArgument:!0,optionList:[e.argument]}),Array.isArray(e.options)&&e.options.length>0&&t.push({header:" Command Options ",optionList:e.options.filter(i=>!i.hidden)}),I(e,t),e.alias!==void 0&&e.alias.length>0){const i=Array.isArray(e.alias)?e.alias:[e.alias];t.splice(1,0,{content:i,header:"Alias(es)"})}return Array.isArray(e.examples)&&e.examples.length>0&&t.push({content:e.examples,header:"Examples"}),N(t)},z=(e,n)=>{const t=e.description?.trim().split(`
-`)[0]??"",r=_(e,n),a=W(e,n);return U([`## \`${r}\``,t,`\`\`\`
-${a.trim()}
+import{createRequire as L}from"node:module";import{f as R,c as F}from"../packem_shared/format-positional-usage-DWL9qN10.js";import{g as q,a as G,b as U}from"../packem_shared/runtime-process-BN-eTlwy.js";let k;const O=e=>(k??=L(import.meta.url))(e),$=typeof globalThis<"u"&&typeof globalThis.process<"u"?globalThis.process:process,T=e=>{if(typeof $<"u"&&$.versions&&$.versions.node){const[n,t]=$.versions.node.split(".").map(Number);if(n>22||n===22&&t>=3||n===20&&t>=16)return $.getBuiltinModule(e)}return O(e)},{resolve:v,join:V,dirname:B}=T("node:path"),C=async(e,n)=>{try{return await e.access(n),!0}catch{return!1}},z=async()=>{const{default:e}=await import("github-slugger"),n=new e;return t=>n.slug(t)},I=e=>e.filter(Boolean),W=(e,n)=>{const t=new Set,o=[];for(const s of e){const r=n(s);t.has(r)||(t.add(r),o.push(s))}return o},D=(e,n)=>{const o=(e.commandPath?[...e.commandPath,e.name]:[e.name]).join(" ");return`${n} ${o}${R(e,"readme")}`},H=(e,n)=>{if(!Array.isArray(e.env)||e.env.length===0)return;const t=e.env.filter(o=>!o.hidden);t.length>0&&n.push({content:t.map(o=>[o.name,o.description??""]),header:" Environment Variables "})},N=(e,n)=>{const t=[],s=(e.commandPath?[...e.commandPath,e.name]:[e.name]).join(" "),r=!!e.options;t.push({content:`${n} ${s}${R(e)}${r?" [options]":""}`,header:" Usage "}),e.description&&t.push({content:e.description,header:" Description "});const c=(e.argument?[e.argument]:e.arguments??[]).filter(a=>!a.hidden);if(c.length>0&&t.push({header:"Command Positional Arguments",isArgument:!0,optionList:c}),Array.isArray(e.options)&&e.options.length>0&&t.push({header:" Command Options ",optionList:e.options.filter(a=>!a.hidden)}),H(e,t),e.alias!==void 0&&e.alias.length>0){const a=Array.isArray(e.alias)?e.alias:[e.alias];t.splice(1,0,{content:a,header:"Alias(es)"})}return Array.isArray(e.examples)&&e.examples.length>0&&t.push({content:e.examples,header:"Examples"}),F(t)},J=(e,n)=>{const t=e.description?.trim().split(`
+`)[0]??"",o=D(e,n),s=N(e,n);return I([`## \`${o}\``,t,`\`\`\`
+${s.trim()}
 \`\`\``]).join(`
 
-`)},H=(e,n,t,r)=>{const a=`(${["--version","-V"].join("|")})`,o=V(),i=G();return`\`\`\`sh-session
+`)},K=(e,n,t,o)=>{const r=`(${["--version","-V"].join("|")})`,c=G(),a=U();return`\`\`\`sh-session
 $ npm install -g ${n}
 $ ${e} COMMAND
 running command...
-$ ${e} ${a}
-${n}/${t??"unknown"} ${o}-${i} node-v${r}
+$ ${e} ${r}
+${n}/${t??"unknown"} ${c}-${a} node-v${o}
 $ ${e} --help [COMMAND]
 USAGE
   $ ${e} COMMAND
 ...
 \`\`\`
-`},M=(e,n,t,r)=>{const a=e.map(i=>{const u=_(i,n);return`* [\`${u}\`](#${r(u)})`}),o=e.map(i=>z(i,n)).map(i=>`${i.trim()}
-`);return[...a,"",...o].join(`
-`).trim()},R=async(e,n,t)=>{const r=L(n);await v(e,r)||await e.mkdir(r,{recursive:!0}),await e.writeFile(n,t,"utf8")},J=async(e,n,t,r,a,o,i)=>{const u=new Map;for(const m of t){const s=m.group??"__Other",d=u.get(s)??[];d.push(m),u.set(s,d)}const p=Array.from(u.entries(),([m,s])=>m==="__Other"?["Other",s]:[m,s]);return await Promise.all(p.map(async([m,s])=>{const d=m.replaceAll(":","/"),y=B(".",r,`${d}.md`),g=`\`${a} ${m}\``,l=`${[g,"=".repeat(g.length),"",`Commands in the ${m} group.`,"",M(s,a,o,i)].join(`
+`},M=(e,n,t,o)=>{const s=e.map(c=>{const a=D(c,n);return`* [\`${a}\`](#${o(a)})`}),r=e.map(c=>J(c,n)).map(c=>`${c.trim()}
+`);return[...s,"",...r].join(`
+`).trim()},_=async(e,n,t)=>{const o=B(n);await C(e,o)||await e.mkdir(o,{recursive:!0}),await e.writeFile(n,t,"utf8")},Q=async(e,n,t,o,s,r,c)=>{const a=new Map;for(const l of t){const i=l.group??"__Other",p=a.get(i)??[];p.push(l),a.set(i,p)}const h=Array.from(a.entries(),([l,i])=>l==="__Other"?["Other",i]:[l,i]);return await Promise.all(h.map(async([l,i])=>{const p=l.replaceAll(":","/"),y=V(".",o,`${p}.md`),m=`\`${s} ${l}\``,u=`${[m,"=".repeat(m.length),"",`Commands in the ${l} group.`,"",M(i,s,r,c)].join(`
 `).trim()}
-`;o.dryRun||await R(e,P(n,y),l)})),`${[`# Command Topics
-`,...p.map(([m])=>{const s=m.replaceAll(":","/");return`* [\`${a} ${m}\`](${r}/${s}.md)`})].join(`
+`;r.dryRun||await _(e,v(n,y),u)})),`${[`# Command Topics
+`,...h.map(([l])=>{const i=l.replaceAll(":","/");return`* [\`${s} ${l}\`](${o}/${i}.md)`})].join(`
 `).trim()}
-`},A=e=>e.replaceAll(`\r
+`},P=e=>e.replaceAll(`\r
 `,`
 `).replaceAll("\r",`
-`),K=(e,n)=>A(e).split(`
-`).filter(t=>t.startsWith("# ")).map(t=>t.trim().slice(2)).map(t=>`* [${t}](#${n(t)})`).join(`
-`),E=e=>e.replaceAll(/[.*+?^${}()|[\]\\]/g,String.raw`\$&`),w=(e,n,t)=>{const r=A(e),a=`<!-- ${n} -->`,o=`<!-- ${n}stop -->`;if(r.includes(a)&&r.includes(o)){const i=E(a),u=E(o),p=new RegExp(String.raw`${i}(.|\n)*${u}`,"m");return r.replace(p,`${a}
+`),X=(e,n)=>P(e).split(`
+`).filter(s=>s.startsWith("# ")).map(s=>s.trim().slice(2)).map(s=>`* [${s}](#${n(s)})`).join(`
+`),E=e=>e.replaceAll(/[.*+?^${}()|[\]\\]/g,String.raw`\$&`),w=(e,n,t)=>{const o=P(e),s=`<!-- ${n} -->`,r=`<!-- ${n}stop -->`;if(o.includes(s)&&o.includes(r)){const c=E(s),a=E(r),h=new RegExp(String.raw`${c}(.|\n)*${a}`,"m");return o.replace(h,`${s}
 ${t}
-${o}`)}return r.replace(a,`${a}
+${r}`)}return o.replace(s,`${s}
 ${t}
-${o}`)},Z={description:"Generate README documentation for CLI commands",execute:async({fs:e,logger:n,options:t,process:r,runtime:a})=>{const o=a.getCliName(),i=a.getPackageName()??o,u=a.getPackageVersion(),p=q().node??"unknown",m=await T(),s={aliases:t.aliases,dryRun:t.dryRun,multi:t.multi,outputDir:t.outputDir??"docs",readmePath:t.readmePath??"README.md",version:t.version??u??void 0},d=a.getCommands(),y=[...d.values()].filter(c=>!c.hidden).filter(c=>s.aliases?!0:c.name===d.get(c.name)?.name).toSorted((c,f)=>{const b=c.commandPath?[...c.commandPath,c.name].join(" "):c.name,C=f.commandPath?[...f.commandPath,f.name].join(" "):f.name;return b.localeCompare(C)}),g=F(y,c=>c.commandPath?[...c.commandPath,c.name].join(" "):c.name);n.debug(`Processing ${String(g.length)} commands for README generation`);let l;const $=P(r.cwd,s.readmePath??"README.md");if(await v(e,$)){const c=await e.readFile($,"utf8");l=A(c)}else n.warn(`README file not found at ${$}, creating template`),l=`# ${i}
+${r}`)},te={description:"Generate README documentation for CLI commands",execute:async({fs:e,logger:n,options:t,process:o,runtime:s})=>{const r=s.getCliName(),c=s.getPackageName()??r,a=s.getPackageVersion(),A=q().node??"unknown",l=await z(),i={aliases:t.aliases,dryRun:t.dryRun,multi:t.multi,nestedTopicsDepth:t.nestedTopicsDepth,outputDir:t.outputDir??"docs",readmePath:t.readmePath??"README.md",repositoryPrefix:t.repositoryPrefix,version:t.version??a??void 0},p=s.getCommands(),y=[...p.values()].filter(d=>!d.hidden).filter(d=>i.aliases?!0:d.name===p.get(d.name)?.name).toSorted((d,f)=>{const S=d.commandPath?[...d.commandPath,d.name].join(" "):d.name,b=f.commandPath?[...f.commandPath,f.name].join(" "):f.name;return S.localeCompare(b)}),m=W(y,d=>d.commandPath?[...d.commandPath,d.name].join(" "):d.name);n.debug(`Processing ${String(m.length)} commands for README generation`);let u;const g=v(o.cwd,i.readmePath??"README.md");if(await C(e,g)){const d=await e.readFile(g,"utf8");u=P(d)}else n.warn(`README file not found at ${g}, creating template`),u=`# ${c}
 
 <!-- usage -->
 <!-- usagestop -->
@@ -40,6 +40,6 @@ ${o}`)},Z={description:"Generate README documentation for CLI commands",execute:
 
 <!-- toc -->
 <!-- tocstop -->
-`;const j=s.outputDir??"docs",D=s.version??u??"unknown";l=w(l,"usage",H(o,i,D,p)),l=w(l,"commands",s.multi?await J(e,r.cwd,g,j,o,s,m):M(g,o,s,m)),l=w(l,"toc",K(l,m)),l=`${l.trimEnd()}
-`,s.dryRun?(n.info("Dry run mode - README not written"),n.info(`Generated README content:
-${l}`)):(await R(e,$,l),n.info(`README generated successfully at ${$}`))},name:"readme",options:[{description:"Include aliases in command list",name:"aliases",type:Boolean},{description:"Show what would be generated without writing files",name:"dry-run",type:Boolean},{description:"Generate multi-file documentation by command groups",name:"multi",type:Boolean},{description:"Maximum depth for nested topics when using multi-file mode",name:"nested-topics-depth",type:Number},{description:"Output directory for multi-file documentation",name:"output-dir",type:String,typeLabel:"{underline directory}"},{description:"Path to README file to generate",name:"readme-path",type:String,typeLabel:"{underline path}"},{description:"Repository prefix for code links",name:"repository-prefix",type:String,typeLabel:"{underline prefix}"},{description:"Version to use in generated documentation",name:"version",type:String,typeLabel:"{underline version}"}]};export{Z as default};
+`;const j=i.outputDir??"docs",x=i.version??a??"unknown";u=w(u,"usage",K(r,c,x,A)),u=w(u,"commands",i.multi?await Q(e,o.cwd,m,j,r,i,l):M(m,r,i,l)),u=w(u,"toc",X(u,l)),u=`${u.trimEnd()}
+`,i.dryRun?(n.info("Dry run mode - README not written"),n.info(`Generated README content:
+${u}`)):(await _(e,g,u),n.info(`README generated successfully at ${g}`))},name:"readme",options:[{description:"Include aliases in command list",name:"aliases",type:Boolean},{description:"Show what would be generated without writing files",name:"dry-run",type:Boolean},{description:"Generate multi-file documentation by command groups",name:"multi",type:Boolean},{description:"Maximum depth for nested topics when using multi-file mode",name:"nested-topics-depth",type:Number},{description:"Output directory for multi-file documentation",name:"output-dir",type:String,typeLabel:"{underline directory}"},{description:"Path to README file to generate",name:"readme-path",type:String,typeLabel:"{underline path}"},{description:"Repository prefix for code links",name:"repository-prefix",type:String,typeLabel:"{underline prefix}"},{description:"Version to use in generated documentation",name:"version",type:String,typeLabel:"{underline version}"}]};export{te as default};

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

@@ -1,4 +1,4 @@
-import { C as Command } from "../packem_shared/command.d-B_G9vIYJ.js";
+import { C as Command } from "../packem_shared/command.d-Dz7hkMI0.js";
 import '@visulima/tabular';
 declare const _default: Command;
 export { _default as default };

package/dist/commands/version-command.js

@@ -1 +1 @@
-const r={alias:["v","V"],description:"Output the version number",execute:({logger:e,runtime:o})=>{const n=o.getPackageVersion();n===void 0?(e.warn("Unknown version"),e.debug("The version number was not provided by the cli constructor.")):e.info(n)},name:"version",options:[],usage:[]};export{r as default};
+const s={alias:["v","V"],description:"Output the version number",execute:({logger:e,runtime:o})=>{const n=o.getPackageVersion();n===void 0?(e.warn("Unknown version"),e.debug("The version number was not provided by the cli constructor.")):e.info(n)},name:"version",options:[],usage:[]};export{s as default};

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { a as CerebroFs, b as CommandSection, O as OptionDefinition, C as Command, P as Plugin, c as PluginManager, d as CliRunOptions, R as RunCommandOptions, T as Toolbox, e as CommandExecute, f as Cli$1, L as LazyCommandModule } from "./packem_shared/command.d-B_G9vIYJ.js";
-export type { A as ArgumentDefinition, g as CerebroProcess, E as EnvDefinition, h as OutputType, i as PluginContext, V as VERBOSITY_LEVEL } from "./packem_shared/command.d-B_G9vIYJ.js";
-export { V as VisulimaError } from "./packem_shared/index.d-CnnVYgSZ.js";
+import { a as CerebroFs, b as CommandSection, O as OptionDefinition, T as Toolbox, c as CommandInput, P as Plugin, d as PluginManager, C as Command, e as CliRunOptions, R as RunCommandOptions, f as CommandExecute, g as Cli$1, h as OptionDefinitionRecord, E as EnvDefinitionRecord, A as ArgumentDefinition, L as LazyCommandModule } from "./packem_shared/command.d-Dz7hkMI0.js";
+export type { i as AnyCommandInput, j as CerebroProcess, k as EnvDefinition, l as OutputType, m as PluginContext, V as VERBOSITY_LEVEL } from "./packem_shared/command.d-Dz7hkMI0.js";
+import { V as VisulimaError } from "./packem_shared/index.d-CnnVYgSZ.js";
 import '@visulima/tabular';
 type CliOptions<T extends Console = Console> = {
   argv?: ReadonlyArray<string>;
@@ -106,7 +106,8 @@ declare class Cli<T extends Console = Console> implements Cli$1<T> {
    * Commands define the available operations that users can execute.
    * Each command can have options, arguments, aliases, and custom execution logic.
    * @template OD - The option definition type for the command
-   * @param command The command configuration object
+   * @template TContext - The toolbox shape the command's handler receives
+   * @param commandInput The command configuration object
    * @returns The CLI instance for method chaining
    * @throws {CerebroError} If the command name already exists or validation fails
    * @example
@@ -128,7 +129,7 @@ declare class Cli<T extends Console = Console> implements Cli$1<T> {
    * });
    * ```
    */
-  addCommand<OD extends OptionDefinition<unknown> = OptionDefinition<unknown>>(command: Command<OD, T>): this;
+  addCommand<OD extends OptionDefinition<unknown> = OptionDefinition<unknown>, TContext extends Toolbox<T> = Toolbox<T>>(commandInput: CommandInput<OD, T, TContext>): this;
   /**
    * Adds a global option available to all commands.
    *
@@ -388,6 +389,15 @@ declare const VERBOSITY_DEBUG = 128;
 type OptionNameToCamelCase<T extends string> = T extends `${infer Start}-${infer Rest}` ? `${Lowercase<Start>}${Capitalize<OptionNameToCamelCase<Rest>>}` : T extends `${infer Start}_${infer Rest}` ? `${Lowercase<Start>}${Capitalize<OptionNameToCamelCase<Rest>>}` : Lowercase<T>;
 /**
  * Helper type to create a type-safe options object from option definitions.
+ *
+ * Prefer `defineCommand`, which infers this shape from the definitions
+ * themselves instead of restating their names. Reach for `CreateOptions` when
+ * you are annotating a `Toolbox` by hand — typically because the command uses
+ * the array form of `options`, which carries no inferable key information.
+ *
+ * Note that this type lowercases a name with no separator in it (`outputDir`
+ * becomes `outputdir`), which matches how environment variables are folded but
+ * not* how the option parser folds option names.
  * @example
  * ```typescript
  * type MyOptions = CreateOptions<{
@@ -401,6 +411,9 @@ type OptionNameToCamelCase<T extends string> = T extends `${infer Start}-${infer
 type CreateOptions<T extends Record<string, unknown>> = { [K in keyof T as OptionNameToCamelCase<K & string>]: T[K]; };
 /**
  * Helper type to create a type-safe environment variables object from env definitions.
+ *
+ * Prefer `defineCommand`, which infers this shape from the definitions
+ * themselves. This type matches the env folding rules exactly.
  * Environment variable names are converted from UPPER_SNAKE_CASE to camelCase.
  * @example
  * ```typescript
@@ -412,6 +425,239 @@ type CreateOptions<T extends Record<string, unknown>> = { [K in keyof T as Optio
  * ```
  */
 type CreateEnv<T extends Record<string, unknown>> = { [K in keyof T as OptionNameToCamelCase<K & string>]: T[K]; };
+/**
+ * Folds a name the way the parser folds it.
+ *
+ * A direct transcription of `command-line-args`' `/-([a-z])/g`: a hyphen folds
+ * into the following character *only* when that character is an ASCII lowercase
+ * letter. `a-1` and `x-` are left alone, `A-b` becomes `AB`, and a name with no
+ * hyphen is returned untouched — including `outputDir`, `UPPER` and `HTTPProxy`.
+ *
+ * Positional names go through the same fold at runtime (`foldName` in
+ * `resolve-arguments.ts`), so one type serves both surfaces. Environment
+ * variables do not — they lowercase first, which is what
+ * {@link OptionNameToCamelCase} models.
+ */
+type FoldName<T extends string> = T extends `${infer Head}-${infer Tail}` ? Tail extends `${infer First}${infer Rest}` ? Lowercase<First> extends First ? Uppercase<First> extends Lowercase<First> ? `${Head}-${FoldName<Tail>}` : `${Head}${Uppercase<First>}${FoldName<Rest>}` : `${Head}-${FoldName<Tail>}` : `${Head}-` : T;
+/**
+ * The value a `type` constructor produces. Falls back to `string` when no `type`
+ * is declared, matching the parser, which leaves untyped values as raw strings.
+ *
+ * Not modelled: `TypeConstructor&lt;T>` is declared as returning `T | undefined`, so
+ * a transform that genuinely returns `undefined` is still typed as `T` here.
+ */
+type TypeConstructorResult<D> = D extends {
+  type: (...arguments_: never[]) => infer R;
+} ? Exclude<R, undefined> : string;
+/** `multiple` / `lazyMultiple` collect every occurrence into an array. */
+type Collected<D> = D extends {
+  lazyMultiple: true;
+} | {
+  multiple: true;
+} ? TypeConstructorResult<D>[] : TypeConstructorResult<D>;
+/** Whether a `defaultValue` was declared, which fills the gap when the flag is absent. */
+type HasDefault<D> = "defaultValue" extends keyof D ? true : false;
+/**
+ * Whether a **boolean** option is declared. `listMissingArguments` short-circuits
+ * missing required booleans instead of raising, and the substituted `false` never
+ * reaches `parsedArgs._all` — so a required boolean can still be absent from the
+ * toolbox at runtime and must keep its `| undefined`.
+ */
+type IsBooleanOption<D> = D extends {
+  type: BooleanConstructor;
+} ? true : false;
+/**
+ * Whether an **option** is guaranteed a value.
+ *
+ * `required` is enforced before `execute` runs, and a `defaultValue` fills the
+ * gap when the flag is absent — except for booleans, which
+ * `listMissingArguments` lets through (see {@link IsBooleanOption}).
+ */
+type IsOptionAlwaysPresent<D> = D extends {
+  required: true;
+} ? (IsBooleanOption<D> extends true ? HasDefault<D> : true) : HasDefault<D>;
+/**
+ * Whether a **positional** is guaranteed a value.
+ *
+ * No boolean exception here: `resolveArguments` reports every unfilled
+ * `required` slot whatever its `type`, and `applyNamedArguments` raises before
+ * `execute` runs. A required boolean positional really is always present.
+ */
+type IsArgumentAlwaysPresent<D> = D extends {
+  required: true;
+} ? true : HasDefault<D>;
+/**
+ * Keys declared as `no-x` produce an `x` option instead. `addNegatableOptions`
+ * generates the counterpart definition and `mapNegatableOptions` rewrites the
+ * parsed value onto the non-negated key, deleting `noX` — so `no-x` never
+ * surfaces on the toolbox under its own name.
+ */
+type PositiveOptionKeys<R> = { [K in keyof R]: K extends `no-${string}` ? never : K; }[keyof R];
+/**
+ * The positive names cerebro *generates* from a `no-x` declaration.
+ *
+ * Only when `x` is not declared itself. `negatable()` declares both halves, and
+ * a positive half without a `defaultValue` stays `undefined` when neither flag
+ * is passed — `mapNegatableOptions` rewrites nothing because the negated key
+ * never reaches the parsed options. Claiming `boolean` there would erase a
+ * deliberate tri-state.
+ */
+type NegatedOptionKeys<R> = { [K in keyof R]: K extends `no-${infer Rest}` ? (Rest extends keyof R ? never : Rest) : never; }[keyof R];
+/** Collapses an intersection into a single object literal so tooltips stay readable. */
+type Simplify<T> = { [K in keyof T]: T[K]; } & {};
+/**
+ * Infers the shape of `toolbox.options` from a record of option definitions.
+ *
+ * Option names are folded the way the parser folds them, `required: true` or a
+ * `defaultValue` drops the `| undefined`, and `multiple` produces an array.
+ *
+ * Not modelled: values injected by `implies`, which is an untyped
+ * `Record&lt;string, unknown>` and can name any option.
+ * @example
+ * ```typescript
+ * type Options = InferOptions<{
+ *   "output-dir": { required: true; type: StringConstructor };
+ *   verbose: { type: BooleanConstructor };
+ * }>;
+ * // { outputDir: string; verbose: boolean | undefined }
+ * ```
+ */
+type InferOptions<R extends OptionDefinitionRecord> = Simplify<{ [K in NegatedOptionKeys<R> & string as FoldName<K>]: boolean; } & { [K in PositiveOptionKeys<R> & string as FoldName<K>]: IsOptionAlwaysPresent<R[K]> extends true ? Collected<R[K]> : Collected<R[K]> | undefined; }>;
+/**
+ * Infers the shape of `toolbox.env` from a record of environment definitions.
+ *
+ * `processEnvVariables` lowercases the whole name before folding snake segments,
+ * so `API_KEY` becomes `apiKey` and an already-camelCase `apiKey` becomes
+ * `apikey` — which is what {@link OptionNameToCamelCase} models. Only a
+ * `defaultValue` removes the `| undefined`; environment variables have no
+ * `required` concept.
+ * @example
+ * ```typescript
+ * type Env = InferEnv<{ API_KEY: { type: StringConstructor } }>;
+ * // { apiKey: string | undefined }
+ * ```
+ */
+type InferEnv<R extends EnvDefinitionRecord> = Simplify<{ [K in keyof R & string as OptionNameToCamelCase<K>]: HasDefault<R[K]> extends true ? TypeConstructorResult<R[K]> : TypeConstructorResult<R[K]> | undefined; }>;
+/** Picks the positional definition carrying a given name out of the tuple. */
+type ArgumentNamed<T extends ReadonlyArray<ArgumentDefinition>, N extends string> = Extract<T[number], {
+  name: N;
+}>;
+/**
+ * Infers the shape of `toolbox.args` from a tuple of positional definitions.
+ *
+ * Positional names are camelCased, `multiple: true` on the final entry produces
+ * an array, and `required: true` or a `defaultValue` drops the `| undefined`.
+ *
+ * Slot order matters, so `arguments` is an array rather than a record. The tuple
+ * is captured by a `const` type parameter on `defineCommand`, so no `as const` is
+ * needed at the call site.
+ * @example
+ * ```typescript
+ * type Args = InferArguments<
+ *     [{ name: "source"; required: true; type: StringConstructor }, { multiple: true; name: "targets"; type: StringConstructor }]
+ * >;
+ * // { source: string; targets: string[] | undefined }
+ * ```
+ */
+type InferArguments<T extends ReadonlyArray<ArgumentDefinition>> = Simplify<{ [K in T[number]["name"] as FoldName<K>]: IsArgumentAlwaysPresent<ArgumentNamed<T, K>> extends true ? Collected<ArgumentNamed<T, K>> : Collected<ArgumentNamed<T, K>> | undefined; }>;
+/**
+ * The toolbox a command declared through {@link defineCommand} receives, with
+ * `options`, `env` and `args` inferred from the command's own definitions.
+ */
+type InferredToolbox<TOptions extends OptionDefinitionRecord, TEnv extends EnvDefinitionRecord, TArguments extends ReadonlyArray<ArgumentDefinition>, TLogger extends Console = Console> = Toolbox<TLogger, InferOptions<TOptions>, InferEnv<TEnv>, InferArguments<TArguments>>;
+/**
+ * A command whose `execute` / `loader` handler is typed from its own `options`,
+ * `env` and `arguments` declarations.
+ */
+type DefinedCommand<TOptions extends OptionDefinitionRecord, TEnv extends EnvDefinitionRecord, TArguments extends ReadonlyArray<ArgumentDefinition>, TLogger extends Console = Console> = Omit<CommandInput<OptionDefinition<unknown>, TLogger>, "arguments" | "env" | "execute" | "loader" | "options"> & {
+  arguments?: TArguments;
+  env?: TEnv;
+  execute?: CommandExecute<NoInfer<InferredToolbox<TOptions, TEnv, TArguments, TLogger>>>;
+  loader?: () => Promise<LazyCommandModule<NoInfer<InferredToolbox<TOptions, TEnv, TArguments, TLogger>>>>;
+  options?: TOptions;
+};
+/**
+ * Declares a command with a single source of truth for its options and
+ * environment variables.
+ *
+ * `options` and `env` are records keyed by name, and the `execute` handler's
+ * `toolbox.options` / `toolbox.env` are inferred from them — no second type
+ * declaration, no `Toolbox&lt;...>` annotation, and a renamed option becomes a
+ * compile error at every use site instead of a silent `undefined`.
+ *
+ * Identity at runtime: it exists only to capture the literal types of the
+ * definitions, so it costs nothing beyond the call itself.
+ * @param command The command definition.
+ * @returns The same object, with its definition types preserved.
+ * @example
+ * ```typescript
+ * import { defineCommand } from "@visulima/cerebro";
+ *
+ * const build = defineCommand({
+ *     name: "build",
+ *     options: {
+ *         "output-dir": { required: true, type: String },
+ *         verbose: { defaultValue: false, type: Boolean },
+ *     },
+ *     env: {
+ *         API_KEY: { type: String },
+ *     },
+ *     arguments: [{ name: "entry", required: true, type: String }],
+ *     execute: ({ args, env, options }) => {
+ *         args.entry; // string
+ *         options.outputDir; // string
+ *         options.verbose; // boolean
+ *         env.apiKey; // string | undefined
+ *     },
+ * });
+ *
+ * cli.addCommand(build);
+ * ```
+ */
+declare const defineCommand: <TOptions extends OptionDefinitionRecord = {}, TEnv extends EnvDefinitionRecord = {}, const TArguments extends ReadonlyArray<ArgumentDefinition> = [], TLogger extends Console = Console>(command: DefinedCommand<TOptions, TEnv, TArguments, TLogger>) => DefinedCommand<TOptions, TEnv, TArguments, TLogger>;
+/**
+ * Base error class for Cerebro CLI operations.
+ */
+declare class CerebroError extends VisulimaError {
+  readonly code: string;
+  readonly context?: Record<string, unknown>;
+  constructor(message: string, code: string, context?: Record<string, unknown>);
+}
+/**
+ * Error thrown when a positional argument's value is not one of its declared
+ * `choices`.
+ *
+ * Distinct from `InvalidChoiceError`, which phrases its hint as `--&lt;option>
+ * &lt;value>`. A positional has no flag, so that hint would name something the
+ * command does not declare.
+ */
+declare class InvalidArgumentChoiceError extends CerebroError {
+  readonly argument: string;
+  readonly choices: ReadonlyArray<string>;
+  readonly value: string;
+  constructor(argument: string, value: string, choices: ReadonlyArray<string>);
+}
+/**
+ * Error thrown when a command is invoked without one of its required positional
+ * arguments. Distinct from `CommandValidationError`, which reports missing
+ * options* — telling a user to "provide the required option" for a positional
+ * sends them looking for a `--flag` that does not exist.
+ */
+declare class MissingArgumentError extends CerebroError {
+  readonly commandName: string;
+  readonly missingArguments: string[];
+  constructor(commandName: string, missingArguments: string[]);
+}
+/**
+ * Error thrown when more positional arguments were supplied than the command
+ * declares. A command using named `arguments` knows its exact arity, so a
+ * surplus token is a mistake worth reporting rather than discarding in silence.
+ */
+declare class SurplusArgumentError extends CerebroError {
+  readonly commandName: string;
+  readonly surplusArguments: ReadonlyArray<string>;
+  constructor(commandName: string, surplusArguments: ReadonlyArray<string>, expected: number);
+}
 /**
  * Builds a `loader` for commands whose handler lives as a named export in a
  * shared handler module (the typical pattern when one file holds multiple
@@ -429,7 +675,7 @@ type CreateEnv<T extends Record<string, unknown>> = { [K in keyof T as OptionNam
  * });
  * ```
  */
-declare const lazyNamed: <M extends Record<string, unknown>, K extends keyof M, TContext>(load: () => Promise<M>, key: K) => () => Promise<LazyCommandModule<TContext>>;
+declare const lazyNamed: <M extends Record<string, unknown>>(load: () => Promise<M>, key: keyof M) => () => Promise<LazyCommandModule<Toolbox>>;
 declare global {
   namespace Cerebro {
     /**
@@ -487,4 +733,35 @@ declare global {
  * ```
  */
 declare const createCerebro: <T extends Console = Console>(name: string, options?: CliOptions<T>) => InstanceType<typeof Cli<T>>;
-export { Cli as Cerebro, type CerebroFs, type Cli$1 as Cli, type CliOptions, type CliRunOptions, type Command, type CommandExecute, type CreateEnv, type CreateOptions, type LazyCommandModule, type OptionDefinition, type OptionNameToCamelCase, type Plugin, type RunCommandOptions, type Toolbox, VERBOSITY_DEBUG, VERBOSITY_NORMAL, VERBOSITY_QUIET, VERBOSITY_VERBOSE, createCerebro, lazyNamed };
+export { type ArgumentDefinition, Cli as Cerebro, type CerebroFs, type Cli$1 as Cli,
+/**
+ * Main entry point for the Cerebro CLI framework.
+ *
+ * This module provides a lightweight, extensible CLI framework for building command-line applications.
+ * It supports plugins, subcommands, argument parsing, help generation, and more.
+ * @example
+ * ```typescript
+ * import { createCerebro } from '@visulima/cerebro';
+ *
+ * const cli = createCerebro('my-app', {
+ *   packageName: 'my-app',
+ *   packageVersion: '1.0.0'
+ * });
+ *
+ * cli.addCommand({
+ *   name: 'greet',
+ *   description: 'Greet someone',
+ *   argument: {
+ *     name: 'name',
+ *     description: 'Name to greet',
+ *     type: String
+ *   },
+ *   execute: ({ argument }) => {
+ *     console.log(`Hello, ${argument[0]}!`);
+ *   }
+ * });
+ *
+ * cli.run();
+ * ```
+ */
+type CliOptions, type CliRunOptions, type Command, type CommandExecute, type CommandInput, type CreateEnv, type CreateOptions, type DefinedCommand, type EnvDefinitionRecord, type InferArguments, type InferEnv, type InferOptions, type InferredToolbox, InvalidArgumentChoiceError, type LazyCommandModule, MissingArgumentError, type OptionDefinition, type OptionDefinitionRecord, type OptionNameToCamelCase, type Plugin, type RunCommandOptions, SurplusArgumentError, type Toolbox, VERBOSITY_DEBUG, VERBOSITY_NORMAL, VERBOSITY_QUIET, VERBOSITY_VERBOSE, VisulimaError, createCerebro, defineCommand, lazyNamed };

package/dist/index.js

@@ -1 +1 @@
-import{Cli as e}from"./packem_shared/Cerebro-58LHN3_T.js";import{VERBOSITY_DEBUG as B,VERBOSITY_NORMAL as O,VERBOSITY_QUIET as R,VERBOSITY_VERBOSE as V}from"./packem_shared/VERBOSITY_DEBUG-XPultrIA.js";import{lazyNamed as I}from"./packem_shared/lazyNamed-DMUm8mZe.js";import{h as T}from"./packem_shared/VisulimaError-DTMgXonA-CzaryRgZ.js";const m=(r,o)=>new e(r,o);export{e as Cerebro,B as VERBOSITY_DEBUG,O as VERBOSITY_NORMAL,R as VERBOSITY_QUIET,V as VERBOSITY_VERBOSE,T as VisulimaError,m as createCerebro,I as lazyNamed};
+import{Cli as o}from"./packem_shared/Cerebro-B02RU3RC.js";import{VERBOSITY_DEBUG as E,VERBOSITY_NORMAL as s,VERBOSITY_QUIET as p,VERBOSITY_VERBOSE as u}from"./packem_shared/VERBOSITY_DEBUG-D7HfSD5l.js";import{default as l}from"./packem_shared/defineCommand-C_isHeEs.js";import{default as d}from"./packem_shared/InvalidArgumentChoiceError-BpovuqrZ.js";import{default as B}from"./packem_shared/MissingArgumentError-D78kza2a.js";import{default as O}from"./packem_shared/SurplusArgumentError-BLwT9lo0.js";import{lazyNamed as S}from"./packem_shared/lazyNamed-BKSCmVsV.js";import{c as C}from"./packem_shared/VisulimaError-BDqtOVL5-Db_MJ_p7.js";const a=(r,e)=>new o(r,e);export{o as Cerebro,d as InvalidArgumentChoiceError,B as MissingArgumentError,O as SurplusArgumentError,E as VERBOSITY_DEBUG,s as VERBOSITY_NORMAL,p as VERBOSITY_QUIET,u as VERBOSITY_VERBOSE,C as VisulimaError,a as createCerebro,l as defineCommand,S as lazyNamed};