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

package/CHANGELOG.md

@@ -1,3 +1,33 @@
+## @visulima/cerebro [3.0.0-alpha.11](https://github.com/visulima/visulima/compare/@visulima/cerebro@3.0.0-alpha.10...@visulima/cerebro@3.0.0-alpha.11) (2026-04-22)
+
+### Features
+
+* **cerebro:** expose rawUnknown on the Toolbox ([0d92cdf](https://github.com/visulima/visulima/commit/0d92cdf22270db5420af8b639b135b75e043de08))
+
+### Bug Fixes
+
+* **cerebro:** cast positionals argument to string array ([432ac5d](https://github.com/visulima/visulima/commit/432ac5dab63a71583e3d170dc1c014dc735d6a1d))
+* **cerebro:** resolve eslint and formatting issues ([d362f80](https://github.com/visulima/visulima/commit/d362f8011afa2fdf7195544a05468ad425904c27))
+* Remove JSR configuration generation script and generated jsr.json files ([#616](https://github.com/visulima/visulima/issues/616)) ([533744b](https://github.com/visulima/visulima/commit/533744b103b74896941db5b727173e617a27a63b))
+* **terminal:** resolve eslint and formatting issues ([12ef283](https://github.com/visulima/visulima/commit/12ef283684d1808fbcfe44077a0cfe8324801485))
+* **terminal:** resolve eslint and formatting issues ([8f30389](https://github.com/visulima/visulima/commit/8f30389deb9ff81e7afce0aa064ef11fcb179f23))
+
+### Miscellaneous Chores
+
+* bump engines.node to ^22.14.0 || >=24.10.0 ([c3d0931](https://github.com/visulima/visulima/commit/c3d0931d1504e4f21ebf50ea680cfa7ce4ba15ce))
+* **cerebro:** apply formatter and lint fixes ([25aedfa](https://github.com/visulima/visulima/commit/25aedfa32a9476e8a127580e2a4154bca512342d))
+* **cerebro:** apply formatter and lint fixes ([f2d19a1](https://github.com/visulima/visulima/commit/f2d19a167b8ebef07e2c2cce241673a6c34a8112))
+* **cerebro:** apply pending changes ([5502fd8](https://github.com/visulima/visulima/commit/5502fd8399ef704bf9d5c192642aef35b73275ef))
+* **cerebro:** apply pending lint and source updates ([727956c](https://github.com/visulima/visulima/commit/727956c737b9a1f811bc71c5343bcc56f91e5097))
+* **cerebro:** enforce curly braces and apply lint fixes ([79f5b19](https://github.com/visulima/visulima/commit/79f5b19bf8f1c6e6f4d2c47f4a160bfcf44b6bb4))
+* fixed jsr.json ([5d85e51](https://github.com/visulima/visulima/commit/5d85e5179de38e284ec433b14d77c71a1619c8d6))
+
+
+### Dependencies
+
+* **@visulima/boxen:** upgraded to 3.0.0-alpha.10
+* **@visulima/pail:** upgraded to 4.0.0-alpha.11
+
 ## @visulima/cerebro [3.0.0-alpha.10](https://github.com/visulima/visulima/compare/@visulima/cerebro@3.0.0-alpha.9...@visulima/cerebro@3.0.0-alpha.10) (2026-04-08)
 
 ### Features

package/dist/commands/help-command.js

@@ -1,5 +1,5 @@
 import { inverse, cyan, green, yellow } from '@visulima/colorize';
-import { t as templateFormat, c as commandLineUsage } from '../packem_shared/index-CS31xKFe.js';
+import { t as templateFormat, c as commandLineUsage } from '../packem_shared/index-DNXLgme3.js';
 
 const defaultEnv = [
   {

package/dist/commands/readme-command.js

@@ -31,7 +31,7 @@ const {
   dirname
 } = __cjs_getBuiltinModule("node:path");
 import GithubSlugger from 'github-slugger';
-import { c as commandLineUsage } from '../packem_shared/index-CS31xKFe.js';
+import { c as commandLineUsage } from '../packem_shared/index-DNXLgme3.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();
@@ -90,9 +90,7 @@ const formatCommandHelp = (command, cliName) => {
   if (Array.isArray(command.options) && command.options.length > 0) {
     usageGroups.push({
       header: " Command Options ",
-      optionList: command.options.filter(
-        (option) => !option.hidden
-      )
+      optionList: command.options.filter((option) => !option.hidden)
     });
   }
   addEnvironmentVariables(command, usageGroups);
@@ -172,14 +170,7 @@ const generateMultiCommands = async (commands, outputDirectory, cliName, options
       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.`,
-        "",
-        generateCommands(groupCommands, cliName)
-      ].join("\n").trim()}
+      const document = `${[bin, "=".repeat(bin.length), "", `Commands in the ${group} group.`, "", generateCommands(groupCommands, cliName)].join("\n").trim()}
 `;
       if (!options.dryRun) {
         await writeFileWithDirectory(resolve(getCwd(), filePath), document);

package/dist/empty-toolbox.d.ts

@@ -10,6 +10,7 @@ declare class EmptyToolbox implements Partial<IToolbox> {
     env?: IToolbox["env"];
     logger?: IToolbox["logger"];
     runtime?: IToolbox["runtime"];
+    rawUnknown?: IToolbox["rawUnknown"];
     constructor(commandName: IToolbox["commandName"], command: IToolbox["command"]);
 }
 export default EmptyToolbox;

package/dist/index.js

@@ -1,4 +1,4 @@
-import { Cli } from './packem_shared/Cerebro-bgCm5Tb1.js';
+import { Cli } from './packem_shared/Cerebro-CXEIHSN2.js';
 export { VERBOSITY_DEBUG, VERBOSITY_NORMAL, VERBOSITY_QUIET, VERBOSITY_VERBOSE } from './packem_shared/VERBOSITY_QUIET-Dp46zlLW.js';
 export { VisulimaError } from './packem_shared/VisulimaError-DA7QsCxH.js';
 

package/dist/packem_shared/{Cerebro-bgCm5Tb1.js → Cerebro-CXEIHSN2.js}

@@ -1126,6 +1126,7 @@ class EmptyToolbox {
   env;
   logger;
   runtime;
+  rawUnknown;
   constructor(commandName, command) {
     this.commandName = commandName;
     this.command = command;
@@ -1286,13 +1287,14 @@ const buildOptionMaps = (commandOptions) => {
 };
 const prepareToolbox = (command, parsedArgs, booleanValues, extraOptions) => {
   const toolbox = new EmptyToolbox(command.name, command);
-  const { _all, positionals } = parsedArgs;
+  const { _all, _unknown, positionals } = parsedArgs;
   const hasBooleanValues = Object.keys(booleanValues).length > 0;
   const mergedAll = hasBooleanValues ? { ..._all, ...booleanValues } : _all;
   if (POSITIONALS_KEY in mergedAll) {
     delete mergedAll[POSITIONALS_KEY];
   }
   toolbox.argument = positionals?.[POSITIONALS_KEY] ?? [];
+  toolbox.rawUnknown = (_unknown ?? []).slice();
   const hasExtraOptions = Object.keys(extraOptions).length > 0;
   toolbox.options = hasExtraOptions ? { ...mergedAll, ...extraOptions } : mergedAll;
   toolbox.env = processEnvVariables(command.env);
@@ -2820,7 +2822,10 @@ class Cli {
     this.#logger.debug(`command '${pathKey}' found, parsing command args: ${commandArguments.join(", ")}`);
     const { arguments_, booleanValues, parsedArgs } = processCommandArgs(command, commandArguments, this.#getAllGlobalOptions());
     const hasBooleanValues = Object.keys(booleanValues).length > 0;
-    const commandArgs = hasBooleanValues ? { ...parsedArgs, _all: { ...parsedArgs._all, ...booleanValues } } : parsedArgs;
+    let commandArgs = parsedArgs;
+    if (hasBooleanValues) {
+      commandArgs = { ...parsedArgs, _all: { ...parsedArgs._all, ...booleanValues } };
+    }
     validateRequiredOptions(arguments_, commandArgs, command);
     const toolbox = prepareToolbox(command, parsedArgs, booleanValues, extraOptions);
     toolbox.runtime = this;
@@ -3102,7 +3107,9 @@ class Cli {
     }
     const existingNames = new Set(this.#customGlobalOptions.map((o) => o.name));
     if (existingNames.has(optionDefinition.name)) {
-      throw new CerebroError(`Global option "--${optionDefinition.name}" has already been added`, "DUPLICATE_OPTION", { optionName: optionDefinition.name });
+      throw new CerebroError(`Global option "--${optionDefinition.name}" has already been added`, "DUPLICATE_OPTION", {
+        optionName: optionDefinition.name
+      });
     }
     optionDefinition.group = "global";
     mapOptionTypeLabel(optionDefinition);

package/dist/packem_shared/{index-CS31xKFe.js → index-DNXLgme3.js}

@@ -124,7 +124,8 @@ class ContentSection extends BaseSection {
       table.addRow([templateFormat(content)]);
       return table.toString();
     }
-    if (Array.isArray(content) && content.every((value) => typeof value === "string" || Array.isArray(value) && value.every((value2) => typeof value2 === "string"))) {
+    if (Array.isArray(content) && // eslint-disable-next-line @typescript-eslint/no-shadow
+    content.every((value) => typeof value === "string" || Array.isArray(value) && value.every((value2) => typeof value2 === "string"))) {
       const table = createTable({
         showHeader: false,
         style: {
@@ -213,7 +214,10 @@ class OptionListSection extends BaseSection {
     });
     definitions.forEach((definition) => {
       const typedDefinition = definition;
-      table.addRow([this.getOptionNames(typedDefinition, data.reverseNameOrder ?? false, data.isArgument ?? false), templateFormat(typedDefinition.description)]);
+      table.addRow([
+        this.getOptionNames(typedDefinition, data.reverseNameOrder ?? false, data.isArgument ?? false),
+        templateFormat(typedDefinition.description)
+      ]);
     });
     this.add(table.toString());
     this.lines.push("");

package/dist/plugins/update-notifier/update-notifier-plugin.js

@@ -482,7 +482,8 @@ const updateNotifierPlugin = (options = {}) => {
         updateCheckInterval: 1e3 * 60 * 60 * 24,
         ...options
       };
-      const shouldCheck = Boolean(updateNotifierOptions.alwaysRun) || !(env.NO_UPDATE_NOTIFIER || env.NODE_ENV === "test" || toolbox.argv.includes("--no-update-notifier") || ciInfoExports.isCI);
+      const shouldCheck = Boolean(updateNotifierOptions.alwaysRun) || // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- intentional boolean coercion for truthy check
+      !(env.NO_UPDATE_NOTIFIER || env.NODE_ENV === "test" || toolbox.argv.includes("--no-update-notifier") || ciInfoExports.isCI);
       if (!shouldCheck) {
         logger.debug("Update notifier: skipping check (disabled by environment or flags)");
         return;

package/dist/types/toolbox.d.ts

@@ -89,6 +89,30 @@ export interface Toolbox<TLogger extends Console = Console, TOptions extends Rec
      * ```
      */
     options: TOptions;
+    /**
+     * Raw tokens that command-line-args could not assign to a defined
+     * option — typically everything after a `--` separator, since
+     * cerebro runs the parser with `stopAtFirstUnknown: true`.
+     *
+     * Use this for passthrough patterns like
+     * `my-cmd foo bar -- --flag=value --other`, where everything after
+     * `--` is forwarded to an inner tool (`create-vite`, a template
+     * runner, etc.). Empty array when there was no `--` segment.
+     * @example
+     * ```typescript
+     * cli.addCommand({
+     *   name: "create",
+     *   argument: { name: "template", type: String },
+     *   execute: ({ argument, rawUnknown }) => {
+     *     // `vis create vite my-app -- --template react-ts`
+     *     // → argument === ["vite", "my-app"]
+     *     // → rawUnknown === ["--template", "react-ts"]
+     *     spawnSync("npm", ["create", "vite", ...rawUnknown]);
+     *   },
+     * });
+     * ```
+     */
+    rawUnknown: ReadonlyArray<string>;
     /**
      * This is the instance of the CLI that is running the command.
      */

package/dist/util/general/register-exception-handler.d.ts

@@ -5,5 +5,5 @@
  * @param logger Console-like logger instance for error reporting
  * @returns Cleanup function to remove event listeners
  */
-declare const registerExceptionHandler: (logger: Console) => () => void;
+declare const registerExceptionHandler: (logger: Console) => (() => void);
 export default registerExceptionHandler;

package/dist/util/general/runtime-process.d.ts

@@ -62,4 +62,4 @@ export type ProcessEventHandler = (...args: unknown[]) => void;
  * @param handler Handler function
  * @returns Cleanup function to remove the handler
  */
-export declare const onProcessEvent: (event: ProcessEventType, handler: ProcessEventHandler) => () => void;
+export declare const onProcessEvent: (event: ProcessEventType, handler: ProcessEventHandler) => (() => void);

package/dist/util/general/validate-input.d.ts

@@ -9,7 +9,7 @@ export declare const validateStringArray: (value: unknown, fieldName: string) =>
 /**
  * Validates that a value is a function.
  */
-export declare const validateFunction: (value: unknown, fieldName: string) => (...args: unknown[]) => unknown;
+export declare const validateFunction: (value: unknown, fieldName: string) => ((...args: unknown[]) => unknown);
 /**
  * Validates that a value is an object (but not null).
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@visulima/cerebro",
-  "version": "3.0.0-alpha.10",
+  "version": "3.0.0-alpha.11",
   "description": "A delightful toolkit for building cross-runtime CLIs for Node.js, Deno, and Bun.",
   "keywords": [
     "visulima",
@@ -111,15 +111,15 @@
     "LICENSE.md"
   ],
   "dependencies": {
-    "@visulima/colorize": "2.0.0-alpha.8",
-    "@visulima/tabular": "4.0.0-alpha.9",
+    "@visulima/colorize": "2.0.0-alpha.10",
+    "@visulima/tabular": "4.0.0-alpha.11",
     "fastest-levenshtein": "^1.0.16"
   },
   "peerDependencies": {
     "@bomb.sh/tab": "0.0.14",
-    "@visulima/boxen": "3.0.0-alpha.9",
-    "@visulima/find-cache-dir": "3.0.0-alpha.7",
-    "@visulima/pail": "4.0.0-alpha.10",
+    "@visulima/boxen": "3.0.0-alpha.10",
+    "@visulima/find-cache-dir": "3.0.0-alpha.9",
+    "@visulima/pail": "4.0.0-alpha.11",
     "github-slugger": "2.0.0"
   },
   "peerDependenciesMeta": {
@@ -140,7 +140,7 @@
     }
   },
   "engines": {
-    "node": ">=22.13 <=25.x"
+    "node": "^22.14.0 || >=24.10.0"
   },
   "os": [
     "darwin",