@visulima/cerebro 3.0.0-alpha.7 → 3.0.0-alpha.9

package/CHANGELOG.md

@@ -1,3 +1,50 @@
+## @visulima/cerebro [3.0.0-alpha.9](https://github.com/visulima/visulima/compare/@visulima/cerebro@3.0.0-alpha.8...@visulima/cerebro@3.0.0-alpha.9) (2026-03-26)
+
+### Features
+
+* **web:** auto-generate packages page from workspace metadata ([623e520](https://github.com/visulima/visulima/commit/623e5207693a7fe720f5f2f179593a3654c880e3))
+
+
+### Dependencies
+
+* **@visulima/colorize:** upgraded to 2.0.0-alpha.7
+* **@visulima/tabular:** upgraded to 4.0.0-alpha.8
+* **@visulima/boxen:** upgraded to 3.0.0-alpha.8
+* **@visulima/command-line-args:** upgraded to 2.0.0-alpha.6
+* **@visulima/error:** upgraded to 6.0.0-alpha.7
+* **@visulima/find-cache-dir:** upgraded to 3.0.0-alpha.6
+* **@visulima/pail:** upgraded to 4.0.0-alpha.9
+* **@visulima/path:** upgraded to 3.0.0-alpha.7
+* **@visulima/string:** upgraded to 3.0.0-alpha.8
+
+## @visulima/cerebro [3.0.0-alpha.8](https://github.com/visulima/visulima/compare/@visulima/cerebro@3.0.0-alpha.7...@visulima/cerebro@3.0.0-alpha.8) (2026-03-26)
+
+### Bug Fixes
+
+* **cerebro:** use workspace:* for internal [@visulima](https://github.com/visulima) deps ([6647854](https://github.com/visulima/visulima/commit/6647854b69a518466318af623938c0435f3a2579))
+* **web:** improve build setup with incremental stats caching and prod install ([fe33e75](https://github.com/visulima/visulima/commit/fe33e75827586779b4b3a0c6d57b39f889ee6207))
+
+### Miscellaneous Chores
+
+* **cerebro:** migrate deps to pnpm catalogs ([75cfac0](https://github.com/visulima/visulima/commit/75cfac01080464cc07279164520177472aff3b13))
+
+### Code Refactoring
+
+* **docs:** migrate Nextra components to fumadocs-ui, remove Nextra stripping ([484878f](https://github.com/visulima/visulima/commit/484878f01879363ef5e9a0282904dc4627d6060c))
+
+
+### Dependencies
+
+* **@visulima/colorize:** upgraded to 2.0.0-alpha.6
+* **@visulima/tabular:** upgraded to 4.0.0-alpha.7
+* **@visulima/boxen:** upgraded to 3.0.0-alpha.7
+* **@visulima/command-line-args:** upgraded to 2.0.0-alpha.5
+* **@visulima/error:** upgraded to 6.0.0-alpha.6
+* **@visulima/find-cache-dir:** upgraded to 3.0.0-alpha.5
+* **@visulima/pail:** upgraded to 4.0.0-alpha.8
+* **@visulima/path:** upgraded to 3.0.0-alpha.6
+* **@visulima/string:** upgraded to 3.0.0-alpha.7
+
 ## @visulima/cerebro [3.0.0-alpha.7](https://github.com/visulima/visulima/compare/@visulima/cerebro@3.0.0-alpha.6...@visulima/cerebro@3.0.0-alpha.7) (2026-03-16)
 
 ### Miscellaneous Chores

package/dist/commands/completion-command.js

@@ -1,5 +1,203 @@
-var g=Object.defineProperty;var a=(e,t)=>g(e,"name",{value:t,configurable:!0});import S from"@bomb.sh/tab";import{c as $}from"../packem_shared/cerebro-error-BnJTixb2.js";var w=Object.defineProperty,y=a((e,t)=>w(e,"name",{value:t,configurable:!0}),"n");class p extends ${static{a(this,"l")}static{y(this,"CompletionError")}troubleshooting;constructor(t,o,n=[]){super(t,o,{troubleshooting:n}),this.name="CompletionError",this.troubleshooting=n,n.length>0&&(this.hint=n.join(`
-`))}}var C=Object.defineProperty,s=a((e,t)=>C(e,"name",{value:t,configurable:!0}),"s");const h=["bash","zsh","fish","powershell"],d=["node","bun","deno"],v=s(e=>"Deno"in e,"hasDeno"),L=s(e=>"Bun"in e,"hasBun"),u=s(()=>v(globalThis)?"deno":L(globalThis)?"bun":"node","detectRuntime"),m=s(e=>{const t=e?.starshipShell??e?.shell;if(t){const r=t.toLowerCase();if(r.includes("zsh"))return"zsh";if(r.includes("bash"))return"bash";if(r.includes("fish"))return"fish"}const o=e?.psModulePath,n=e?.prompt;if(o||n?.includes("PS"))return"powershell";if(e?.comSpec?.toLowerCase().includes("cmd.exe"))return"bash"},"detectShell"),f=S,I=s((e,t)=>{for(const o of t)o.hidden||(o.name&&e.option(o.name,o.description||""),o.alias&&e.option(o.alias,o.description||""))},"registerCommandOptions"),P=s((e,t)=>{for(const[o,n]of t){if(n.name!==o||n.hidden)continue;const r=e.command(n.name,n.description||"");n.options&&I(r,n.options)}},"registerCommands"),E=s(e=>{if(!h.includes(e))throw new p(`Invalid shell type: ${e}`,"INVALID_SHELL",[`Valid shells are: ${h.join(", ")}`,"Shell will be auto-detected if not specified"])},"validateShell"),j=s(e=>{if(e&&!d.includes(e))throw new p(`Invalid runtime: ${e}`,"INVALID_RUNTIME",[`Valid runtimes are: ${d.join(", ")}`,"Runtime will be auto-detected if not specified"])},"validateRuntime"),z=s((e,t)=>{e.error("Could not detect current shell");const o=[`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(o)},"printUsageInstructions"),x={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:s(async({env:e,logger:t,options:o,runtime:n})=>{const r=n.getCliName(),c=o?.shell||m(e);if(!c){z(t,r);return}try{E(c),j(o?.runtime),P(f,n.getCommands());const i=`${o?.runtime||u()} ${r}`;f.setup(r,i,c)}catch(i){if(i instanceof p){const l=[`Failed to generate completion script: ${i.message}`,`Error code: ${i.code}`];throw i.troubleshooting.length>0&&l.push("","Troubleshooting:",...i.troubleshooting.map(b=>`  • ${b}`)),t.error(l.join(`
-`)),i}else{const l=["Failed to generate completion script",`Error: ${i instanceof Error?i.message:String(i)}`,"","Troubleshooting:","  • Ensure @bomb.sh/tab is installed: pnpm add @bomb.sh/tab",`  • Verify shell is supported: ${h.join(", ")}`,`  • Verify runtime is supported: ${d.join(", ")}`,"  • Check that your CLI name is correct"];t.error(l.join(`
-`))}}},"execute"),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}"},{defaultOption:!0,defaultValue:u(),description:"JavaScript runtime (node, bun, deno). Defaults to current runtime if detected.",name:"runtime",type:String,typeLabel:"{underline runtime}"}]};export{x as default};
+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 };

package/dist/commands/help-command.js

@@ -1 +1,3 @@
-import"@visulima/colorize";import{D as p}from"../packem_shared/help-command-CIRIXN03.js";import"../packem_shared/index-DQ3pvLQH.js";export{p as default};
+import '@visulima/colorize';
+export { H as default } from '../packem_shared/help-command-BY7rQUvM.js';
+import '../packem_shared/index-C2-8b3A4.js';

package/dist/commands/readme-command.js

@@ -1,36 +1,265 @@
-var O=Object.defineProperty;var f=(e,n)=>O(e,"name",{value:n,configurable:!0});import{createRequire as L}from"node:module";import G from"github-slugger";import{p as U}from"../packem_shared/index-DQ3pvLQH.js";import{g as F,a as M,b as W,c as z}from"../packem_shared/runtime-process-G-n-wOub.js";const N=L(import.meta.url),g=typeof globalThis<"u"&&typeof globalThis.process<"u"?globalThis.process:process,w=f(e=>{if(typeof g<"u"&&g.versions&&g.versions.node){const[n,t]=g.versions.node.split(".").map(Number);if(n>22||n===22&&t>=3||n===20&&t>=16)return g.getBuiltinModule(e)}return N(e)},"__cjs_getBuiltinModule"),{existsSync:E}=w("node:fs"),{readFile:T,mkdir:k,writeFile:B}=w("node:fs/promises"),{resolve:v,join:V,dirname:q}=w("node:path");var H=Object.defineProperty,d=f((e,n)=>H(e,"name",{value:n,configurable:!0}),"d");const I=new G,b=I.slug,J=d(e=>e.filter(Boolean),"compact"),K=d((e,n)=>{const t=new Set,a=[];for(const r of e){const i=n(r);t.has(i)||(t.add(i),a.push(r))}return a},"uniqBy"),D=d((e,n)=>{const t=(e.commandPath?[...e.commandPath,e.name]:[e.name]).join(" ");if(e.argument){const a=e.argument.name?.toUpperCase()??"ARG",r=e.argument.required?a:`[${a}]`;return`${n} ${t} ${r}`}return`${n} ${t}`},"formatCommandUsage"),Q=d((e,n)=>{if(!Array.isArray(e.env)||e.env.length===0)return;const t=e.env.filter(a=>!a.hidden);t.length>0&&n.push({content:t.map(a=>[a.name,a.description??""]),header:" Environment Variables "})},"addEnvironmentVariables"),X=d((e,n)=>{const t=[],a=(e.commandPath?[...e.commandPath,e.name]:[e.name]).join(" "),r=!!e.argument,i=!!e.options;if(t.push({content:`${n} ${a}${r?" [positional arguments]":""}${i?" [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(o=>typeof o=="object"&&o!==null&&(!("hidden"in o)||!o.hidden))}),Q(e,t),e.alias!==void 0&&e.alias.length>0){const o=Array.isArray(e.alias)?e.alias:[e.alias];t.splice(1,0,{content:o,header:"Alias(es)"})}return Array.isArray(e.examples)&&e.examples.length>0&&t.push({content:e.examples,header:"Examples"}),U(t)},"formatCommandHelp"),Y=d((e,n)=>{const t=e.description?.trim().split(`
-`)[0]??"",a=D(e,n),r=X(e,n);return J([`## \`${a}\``,t,`\`\`\`
-${r.trim()}
-\`\`\``]).join(`
-
-`)},"renderCommand"),Z=d((e,n,t,a)=>{const r=`(${["--version","-V"].join("|")})`,i=W(),o=z();return`\`\`\`sh-session
-$ npm install -g ${n}
-$ ${e} COMMAND
+import { createRequire as __cjs_createRequire } from "node:module";
+
+const __cjs_require = __cjs_createRequire(import.meta.url);
+
+const __cjs_getProcess = typeof globalThis !== "undefined" && typeof globalThis.process !== "undefined" ? globalThis.process : process;
+
+const __cjs_getBuiltinModule = (module) => {
+    // Check if we're in Node.js and version supports getBuiltinModule
+    if (typeof __cjs_getProcess !== "undefined" && __cjs_getProcess.versions && __cjs_getProcess.versions.node) {
+        const [major, minor] = __cjs_getProcess.versions.node.split(".").map(Number);
+        // Node.js 20.16.0+ and 22.3.0+
+        if (major > 22 || (major === 22 && minor >= 3) || (major === 20 && minor >= 16)) {
+            return __cjs_getProcess.getBuiltinModule(module);
+        }
+    }
+    // Fallback to createRequire
+    return __cjs_require(module);
+};
+
+const {
+  existsSync
+} = __cjs_getBuiltinModule("node:fs");
+const {
+  readFile,
+  mkdir,
+  writeFile
+} = __cjs_getBuiltinModule("node:fs/promises");
+const {
+  resolve,
+  join,
+  dirname
+} = __cjs_getBuiltinModule("node:path");
+import GithubSlugger from 'github-slugger';
+import { c as commandLineUsage } from '../packem_shared/index-C2-8b3A4.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();
+const slugify = slugger.slug;
+const compact = (array) => array.filter(Boolean);
+const uniqBy = (array, keyFunction) => {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const item of array) {
+    const key = keyFunction(item);
+    if (!seen.has(key)) {
+      seen.add(key);
+      result.push(item);
+    }
+  }
+  return result;
+};
+const formatCommandUsage = (command, cliName) => {
+  const fullPath = command.commandPath ? [...command.commandPath, command.name] : [command.name];
+  const commandId = fullPath.join(" ");
+  if (command.argument) {
+    const argumentName = command.argument.name?.toUpperCase() ?? "ARG";
+    const argumentString = command.argument.required ? argumentName : `[${argumentName}]`;
+    return `${cliName} ${commandId} ${argumentString}`;
+  }
+  return `${cliName} ${commandId}`;
+};
+const addEnvironmentVariables = (command, usageGroups) => {
+  if (!Array.isArray(command.env) || command.env.length === 0) {
+    return;
+  }
+  const visibleEnvVariables = command.env.filter((envVariable) => !envVariable.hidden);
+  if (visibleEnvVariables.length > 0) {
+    usageGroups.push({
+      content: visibleEnvVariables.map((envVariable) => [envVariable.name, envVariable.description ?? ""]),
+      header: " Environment Variables "
+    });
+  }
+};
+const formatCommandHelp = (command, cliName) => {
+  const usageGroups = [];
+  const fullCommandPath = command.commandPath ? [...command.commandPath, command.name] : [command.name];
+  const commandDisplay = fullCommandPath.join(" ");
+  const hasArgument = Boolean(command.argument);
+  const hasOptions = Boolean(command.options);
+  usageGroups.push({
+    content: `${cliName} ${commandDisplay}${hasArgument ? " [positional arguments]" : ""}${hasOptions ? " [options]" : ""}`,
+    header: " Usage "
+  });
+  if (command.description) {
+    usageGroups.push({ content: command.description, header: " Description " });
+  }
+  if (command.argument) {
+    usageGroups.push({ header: "Command Positional Arguments", isArgument: true, optionList: [command.argument] });
+  }
+  if (Array.isArray(command.options) && command.options.length > 0) {
+    usageGroups.push({
+      header: " Command Options ",
+      optionList: command.options.filter(
+        (option) => typeof option === "object" && option !== null && (!("hidden" in option) || !option.hidden)
+      )
+    });
+  }
+  addEnvironmentVariables(command, usageGroups);
+  if (command.alias !== void 0 && command.alias.length > 0) {
+    const alias = Array.isArray(command.alias) ? command.alias : [command.alias];
+    usageGroups.splice(1, 0, {
+      content: alias,
+      header: "Alias(es)"
+    });
+  }
+  if (Array.isArray(command.examples) && command.examples.length > 0) {
+    usageGroups.push({
+      content: command.examples,
+      header: "Examples"
+    });
+  }
+  return commandLineUsage(usageGroups);
+};
+const renderCommand = (command, cliName) => {
+  const title = command.description?.trim().split("\n")[0] ?? "";
+  const usage = formatCommandUsage(command, cliName);
+  const helpText = formatCommandHelp(command, cliName);
+  return compact([`## \`${usage}\``, title, `\`\`\`
+${helpText.trim()}
+\`\`\``]).join("\n\n");
+};
+const generateUsage = (cliName, packageName, version, nodeVersion) => {
+  const versionFlags = ["--version", "-V"];
+  const versionFlagsString = `(${versionFlags.join("|")})`;
+  const platform = getPlatform();
+  const arch = getArch();
+  return `\`\`\`sh-session
+$ npm install -g ${packageName}
+$ ${cliName} COMMAND
 running command...
-$ ${e} ${r}
-${n}/${t??"unknown"} ${i}-${o} node-v${a}
-$ ${e} --help [COMMAND]
+$ ${cliName} ${versionFlagsString}
+${packageName}/${version ?? "unknown"} ${platform}-${arch} node-v${nodeVersion}
+$ ${cliName} --help [COMMAND]
 USAGE
-  $ ${e} COMMAND
+  $ ${cliName} COMMAND
 ...
 \`\`\`
-`},"generateUsage"),R=d(async(e,n,t)=>{const a=await Promise.all(e.map(async i=>{const o=D(i,n);return`* [\`${o}\`](#${await b(o)})`})),r=e.map(i=>Y(i,n)).map(i=>`${i.trim()}
-`);return[...a,"",...r].join(`
-`).trim()},"generateCommands"),j=d(async(e,n)=>{const t=q(e);E(t)||await k(t,{recursive:!0}),await B(e,n,"utf8")},"writeFileWithDirectory"),ee=d(async(e,n,t,a)=>{const r=new Map;for(const o of e){const s=o.group??"__Other",l=r.get(s)??[];l.push(o),r.set(s,l)}const i=[...r.entries()].map(([o,s])=>o==="__Other"?["Other",s]:[o,s]);return await Promise.all(i.map(async([o,s])=>{const l=o.replaceAll(":","/"),$=V(".",n,`${l}.md`),p=`\`${t} ${o}\``,c=`${[p,"=".repeat(p.length),"",`Commands in the ${o} group.`,"",await R(s,t,a)].join(`
-`).trim()}
-`;a.dryRun||await j(v(M(),$),c)})),`${[`# Command Topics
-`,...i.map(([o])=>{const s=o.replaceAll(":","/");return`* [\`${t} ${o}\`](${n}/${s}.md)`})].join(`
-`).trim()}
-`},"generateMultiCommands"),A=d(e=>e.replaceAll(`\r
-`,`
-`).replaceAll("\r",`
-`),"normalizeLineEndings"),te=d(async e=>{const n=A(e);return(await Promise.all(n.split(`
-`).filter(t=>t.startsWith("# ")).map(t=>t.trim().slice(2)).map(async t=>`* [${t}](#${await b(t)})`))).join(`
-`)},"generateTableOfContents"),P=d(e=>e.replaceAll(/[.*+?^${}()|[\]\\]/g,String.raw`\$&`),"escapeRegex"),y=d((e,n,t)=>{const a=A(e),r=`<!-- ${n} -->`,i=`<!-- ${n}stop -->`;if(a.includes(r)&&a.includes(i)){const o=P(r),s=P(i),l=new RegExp(String.raw`${o}(.|\n)*${s}`,"m");return a.replace(l,`${r}
-${t}
-${i}`)}return a.replace(r,`${r}
-${t}
-${i}`)},"replaceTag"),se={description:"Generate README documentation for CLI commands",execute:d(async({logger:e,options:n,runtime:t})=>{const a=t.getCliName(),r=t.getPackageName()??a,i=t.getPackageVersion(),o=F().node??"unknown",s={aliases:n?.aliases,dryRun:n?.dryRun,multi:n?.multi,nestedTopicsDepth:n?.nestedTopicsDepth,outputDir:n?.outputDir??"docs",readmePath:n?.readmePath??"README.md",repositoryPrefix:n?.repositoryPrefix,version:n?.version??i??void 0},l=t.getCommands(),$=[...l.values()].filter(m=>!m.hidden).filter(m=>s.aliases?!0:m.name===l.get(m.name)?.name).toSorted((m,h)=>{const _=m.commandPath?[...m.commandPath,m.name].join(" "):m.name,S=h.commandPath?[...h.commandPath,h.name].join(" "):h.name;return _.localeCompare(S)}),p=K($,m=>m.commandPath?[...m.commandPath,m.name].join(" "):m.name);e.debug(`Processing ${p.length} commands for README generation`);let c;const u=v(M(),s.readmePath??"README.md");if(E(u)){const m=await T(u,"utf8");c=A(m)}else e.warn(`README file not found at ${u}, creating template`),c=`# ${r}
+`;
+};
+const generateCommands = async (commands, cliName, _options) => {
+  const commandList = await Promise.all(
+    commands.map(async (command) => {
+      const usage = formatCommandUsage(command, cliName);
+      return `* [\`${usage}\`](#${await slugify(usage)})`;
+    })
+  );
+  const commandDocumentation = commands.map((command) => renderCommand(command, cliName)).map((s) => `${s.trim()}
+`);
+  return [...commandList, "", ...commandDocumentation].join("\n").trim();
+};
+const writeFileWithDirectory = async (filePath, content) => {
+  const directory = dirname(filePath);
+  if (!existsSync(directory)) {
+    await mkdir(directory, { recursive: true });
+  }
+  await writeFile(filePath, content, "utf8");
+};
+const generateMultiCommands = async (commands, outputDirectory, cliName, options) => {
+  const groupedCommands = /* @__PURE__ */ new Map();
+  for (const command of commands) {
+    const group = command.group ?? "__Other";
+    const groupCommands = groupedCommands.get(group) ?? [];
+    groupCommands.push(command);
+    groupedCommands.set(group, groupCommands);
+  }
+  const groups = [...groupedCommands.entries()].map(([group, groupCommands]) => {
+    if (group === "__Other") {
+      return ["Other", groupCommands];
+    }
+    return [group, groupCommands];
+  });
+  await Promise.all(
+    groups.map(async ([group, groupCommands]) => {
+      const groupPath = group.replaceAll(":", "/");
+      const filePath = join(".", outputDirectory, `${groupPath}.md`);
+      const bin = `\`${cliName} ${group}\``;
+      const document = `${[
+        bin,
+        "=".repeat(bin.length),
+        "",
+        `Commands in the ${group} group.`,
+        "",
+        await generateCommands(groupCommands, cliName)
+      ].join("\n").trim()}
+`;
+      if (!options.dryRun) {
+        await writeFileWithDirectory(resolve(getCwd(), filePath), document);
+      }
+    })
+  );
+  const topicLinks = groups.map(([group]) => {
+    const groupPath = group.replaceAll(":", "/");
+    return `* [\`${cliName} ${group}\`](${outputDirectory}/${groupPath}.md)`;
+  });
+  return `${["# Command Topics\n", ...topicLinks].join("\n").trim()}
+`;
+};
+const normalizeLineEndings = (text) => text.replaceAll("\r\n", "\n").replaceAll("\r", "\n");
+const generateTableOfContents = async (readme) => {
+  const normalizedReadme = normalizeLineEndings(readme);
+  const toc = await Promise.all(
+    normalizedReadme.split("\n").filter((line) => line.startsWith("# ")).map((line) => line.trim().slice(2)).map(async (line) => `* [${line}](#${await slugify(line)})`)
+  );
+  return toc.join("\n");
+};
+const escapeRegex = (string_) => string_.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+const replaceTag = (readme, tag, body) => {
+  const normalizedReadme = normalizeLineEndings(readme);
+  const tagStart = `<!-- ${tag} -->`;
+  const tagStop = `<!-- ${tag}stop -->`;
+  if (normalizedReadme.includes(tagStart) && normalizedReadme.includes(tagStop)) {
+    const escapedStart = escapeRegex(tagStart);
+    const escapedStop = escapeRegex(tagStop);
+    const tagPattern = new RegExp(String.raw`${escapedStart}(.|\n)*${escapedStop}`, "m");
+    return normalizedReadme.replace(tagPattern, `${tagStart}
+${body}
+${tagStop}`);
+  }
+  return normalizedReadme.replace(tagStart, `${tagStart}
+${body}
+${tagStop}`);
+};
+const readmeCommand = {
+  description: "Generate README documentation for CLI commands",
+  execute: async ({ logger, options, runtime }) => {
+    const cliName = runtime.getCliName();
+    const packageName = runtime.getPackageName() ?? cliName;
+    const packageVersion = runtime.getPackageVersion();
+    const versions = getVersions();
+    const nodeVersion = versions.node ?? "unknown";
+    const readmeOptions = {
+      aliases: options?.aliases,
+      dryRun: options?.dryRun,
+      multi: options?.multi,
+      outputDir: options?.outputDir ?? "docs",
+      readmePath: options?.readmePath ?? "README.md",
+      version: options?.version ?? packageVersion ?? void 0
+    };
+    const commandsMap = runtime.getCommands();
+    const commands = [...commandsMap.values()].filter((c) => !c.hidden).filter((c) => {
+      if (readmeOptions.aliases) {
+        return true;
+      }
+      return c.name === commandsMap.get(c.name)?.name;
+    }).toSorted((a, b) => {
+      const aPath = a.commandPath ? [...a.commandPath, a.name].join(" ") : a.name;
+      const bPath = b.commandPath ? [...b.commandPath, b.name].join(" ") : b.name;
+      return aPath.localeCompare(bPath);
+    });
+    const uniqueCommands = uniqBy(commands, (c) => {
+      const path = c.commandPath ? [...c.commandPath, c.name].join(" ") : c.name;
+      return path;
+    });
+    logger.debug(`Processing ${uniqueCommands.length} commands for README generation`);
+    let readme;
+    const readmePath = resolve(getCwd(), readmeOptions.readmePath ?? "README.md");
+    if (existsSync(readmePath)) {
+      const rawReadme = await readFile(readmePath, "utf8");
+      readme = normalizeLineEndings(rawReadme);
+    } else {
+      logger.warn(`README file not found at ${readmePath}, creating template`);
+      readme = `# ${packageName}
 
 <!-- usage -->
 <!-- usagestop -->
@@ -40,6 +269,75 @@ ${i}`)},"replaceTag"),se={description:"Generate README documentation for CLI com
 
 <!-- toc -->
 <!-- tocstop -->
-`;const C=s.outputDir??"docs",x=s.version??i??"unknown";c=y(c,"usage",Z(a,r,x,o)),c=y(c,"commands",s.multi?await ee(p,C,a,s):await R(p,a,s)),c=y(c,"toc",await te(c)),c=`${c.trimEnd()}
-`,s.dryRun?(e.info("Dry run mode - README not written"),e.info(`Generated README content:
-${c}`)):(await j(u,c),e.info(`README generated successfully at ${u}`))},"execute"),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{se as default};
+`;
+    }
+    const outputDirectory = readmeOptions.outputDir ?? "docs";
+    const version = readmeOptions.version ?? packageVersion ?? "unknown";
+    readme = replaceTag(readme, "usage", generateUsage(cliName, packageName, version, nodeVersion));
+    readme = replaceTag(
+      readme,
+      "commands",
+      readmeOptions.multi ? await generateMultiCommands(uniqueCommands, outputDirectory, cliName, readmeOptions) : await generateCommands(uniqueCommands, cliName)
+    );
+    readme = replaceTag(readme, "toc", await generateTableOfContents(readme));
+    readme = `${readme.trimEnd()}
+`;
+    if (readmeOptions.dryRun) {
+      logger.info("Dry run mode - README not written");
+      logger.info(`Generated README content:
+${readme}`);
+    } else {
+      await writeFileWithDirectory(readmePath, readme);
+      logger.info(`README generated successfully at ${readmePath}`);
+    }
+  },
+  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 { readmeCommand as default };