@visulima/cerebro 3.0.0-alpha.9 → 3.0.1

package/dist/util/general/heap-tuning.d.ts

@@ -0,0 +1,18 @@
+interface HeapTuningOptions {
+  /**
+  * Fraction of total system memory to allocate as `--max-old-space-size`.
+  * Must be between 0 and 1. Default: `0.75` (75%).
+  */
+  maxOldSpacePercent?: number;
+}
+/**
+* Apply heap memory tuning to the current process.
+*
+* When tuning is needed, this function re-spawns the process with computed
+* V8 memory flags and **never returns** — the parent exits with the child's
+* exit code. When no tuning is needed (flags already set), it returns
+* immediately.
+* @param options Optional configuration for heap tuning.
+*/
+declare const applyHeapTuning: (options?: HeapTuningOptions) => void;
+export { type HeapTuningOptions, applyHeapTuning };

package/dist/util/general/heap-tuning.js

@@ -0,0 +1 @@
+import{createRequire as g}from"node:module";import{d as x,h as y,c as b,e as d,i as j}from"../../packem_shared/runtime-process-Dmz0vCJy.js";const h=g(import.meta.url),t=typeof globalThis<"u"&&typeof globalThis.process<"u"?globalThis.process:process,u=e=>{if(typeof t<"u"&&t.versions&&t.versions.node){const[o,s]=t.versions.node.split(".").map(Number);if(o>22||o===22&&s>=3||o===20&&s>=16)return t.getBuiltinModule(e)}return h(e)},{execFileSync:_}=u("node:child_process"),{totalmem:v}=u("node:os"),M=/--max-old-space-size=(\d+)/,z=/--max-semi-space-size=(\d+)/,E=e=>Math.floor(v()/1024/1024*e),P=e=>e<=512?4:e<=1024?8:e<=2048?16:e<=4096?32:e<=8192?64:Math.floor(Math.log2(e))*8,l=(e,o)=>{for(const s of o){const i=e.exec(s);if(i)return Number.parseInt(i[1],10)}},q=e=>{const o=e?.maxOldSpacePercent??.75,s=[...j()],i=[...x()],n=l(M,s),c=l(z,s);if(n!==void 0&&c!==void 0)return;const a=n??E(o),m=c??P(a),r=[];if(n===void 0&&r.push(`--max-old-space-size=${String(a)}`),c===void 0&&r.push(`--max-semi-space-size=${String(m)}`),r.length!==0)try{_(y(),[...r,...s,...i.slice(1)],{env:b(),stdio:"inherit"}),d(0)}catch(f){const p=f.status;d(typeof p=="number"?p:1)}};export{q as applyHeapTuning};

package/package.json

@@ -1,39 +1,42 @@
 {
   "name": "@visulima/cerebro",
-  "version": "3.0.0-alpha.9",
+  "version": "3.0.1",
   "description": "A delightful toolkit for building cross-runtime CLIs for Node.js, Deno, and Bun.",
   "keywords": [
-    "visulima",
-    "command",
-    "line",
-    "class",
-    "terminal",
     "ansi",
-    "cli",
-    "opts",
-    "nopt",
-    "options",
     "args",
+    "argument",
     "argv",
-    "interactive",
-    "commander",
     "clap",
+    "class",
+    "cli",
     "cli-app",
-    "minimist",
+    "command",
     "command line apps",
     "command-line-usage",
-    "option",
-    "parser",
-    "argument",
+    "commander",
     "flag",
     "gluegun",
+    "interactive",
+    "line",
     "meow",
+    "minimist",
+    "nopt",
     "oclif",
+    "option",
+    "options",
+    "opts",
+    "parser",
+    "terminal",
+    "visulima",
     "yargs"
   ],
   "homepage": "https://visulima.com/packages/cerebro",
-  "bugs": {
-    "url": "https://github.com/visulima/visulima/issues"
+  "bugs": "https://github.com/visulima/visulima/issues",
+  "license": "MIT",
+  "author": {
+    "name": "Daniel Bannert",
+    "email": "d.bannert@anolilab.de"
   },
   "repository": {
     "type": "git",
@@ -50,13 +53,19 @@
       "url": "https://anolilab.com/support"
     }
   ],
-  "license": "MIT",
-  "author": {
-    "name": "Daniel Bannert",
-    "email": "d.bannert@anolilab.de"
-  },
-  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE.md"
+  ],
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
   "type": "module",
+  "sideEffects": false,
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -90,29 +99,35 @@
       "types": "./dist/plugins/update-notifier/update-notifier-plugin.d.ts",
       "default": "./dist/plugins/update-notifier/update-notifier-plugin.js"
     },
+    "./compile-cache": {
+      "types": "./dist/util/general/compile-cache.d.ts",
+      "default": "./dist/util/general/compile-cache.js"
+    },
+    "./heap-tuning": {
+      "types": "./dist/util/general/heap-tuning.d.ts",
+      "default": "./dist/util/general/heap-tuning.js"
+    },
     "./logger/pail": {
       "types": "./dist/logger/create-pail-logger.d.ts",
       "default": "./dist/logger/create-pail-logger.js"
     },
     "./package.json": "./package.json"
   },
-  "files": [
-    "dist",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE.md"
-  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "dependencies": {
-    "@visulima/colorize": "2.0.0-alpha.7",
-    "@visulima/tabular": "4.0.0-alpha.8",
+    "@visulima/colorize": "2.0.0",
+    "@visulima/tabular": "4.0.0",
     "fastest-levenshtein": "^1.0.16"
   },
   "peerDependencies": {
-    "@bomb.sh/tab": "0.0.14",
-    "@visulima/boxen": "3.0.0-alpha.8",
-    "@visulima/find-cache-dir": "3.0.0-alpha.6",
-    "@visulima/pail": "4.0.0-alpha.9",
-    "github-slugger": "2.0.0"
+    "@bomb.sh/tab": ">=0.0.16",
+    "@visulima/boxen": "3.0.0",
+    "@visulima/find-cache-dir": "3.0.0",
+    "@visulima/pail": "4.0.0",
+    "github-slugger": ">=2.0.0"
   },
   "peerDependenciesMeta": {
     "@bomb.sh/tab": {
@@ -131,17 +146,7 @@
       "optional": true
     }
   },
-  "optionalDependencies": {},
   "engines": {
-    "node": ">=22.13 <=25.x"
-  },
-  "os": [
-    "darwin",
-    "linux",
-    "win32"
-  ],
-  "publishConfig": {
-    "access": "public",
-    "provenance": true
+    "node": "^22.14.0 || >=24.10.0"
   }
 }

package/dist/cli.d.ts

@@ -1,203 +0,0 @@
-import PluginManager from "./plugin-manager.d.ts";
-import type { Cli as ICli, CliRunOptions, CommandSection as ICommandSection, RunCommandOptions } from "./types/cli.d.ts";
-import type { Command as ICommand, OptionDefinition } from "./types/command.d.ts";
-import type { Plugin } from "./types/plugin.d.ts";
-export type CliOptions<T extends Console = Console> = {
-    argv?: ReadonlyArray<string>;
-    cwd?: string;
-    logger?: T;
-    packageName?: string;
-    packageVersion?: string;
-};
-export declare class Cli<T extends Console = Console> implements ICli<T> {
-    #private;
-    /**
-     * Create a new CLI instance.
-     * @param cliName
-     * @param options The options for the CLI.
-     * @param options.argv The command line arguments.
-     * @param options.cwd The current working directory.
-     * @param options.logger The logger to use.
-     * @param options.packageName
-     * @param options.packageVersion
-     */
-    constructor(cliName: string, options?: CliOptions<T>);
-    /**
-     * Sets the command section configuration for help display.
-     *
-     * This affects how the CLI name and version are displayed in help output.
-     * @param commandSection The command section configuration
-     * @returns The CLI instance for method chaining
-     * @example
-     * ```typescript
-     * cli.setCommandSection({
-     *   header: 'My App v2.0.0',
-     *   footer: 'For more info, visit https://example.com'
-     * });
-     * ```
-     */
-    setCommandSection(commandSection: ICommandSection): this;
-    /**
-     * Gets the current command section configuration.
-     * @returns The command section configuration
-     */
-    getCommandSection(): ICommandSection;
-    /**
-     * Sets the default command to run when no command is specified.
-     *
-     * By default, this is set to 'help'. The command must already be registered
-     * with the CLI instance.
-     * @param commandName The command name to use as the default
-     * @returns The CLI instance for method chaining
-     * @example
-     * ```typescript
-     * cli.setDefaultCommand('start');
-     * ```
-     */
-    setDefaultCommand(commandName: string): this;
-    /**
-     * Gets the current default command.
-     * @returns The name of the default command
-     */
-    get defaultCommand(): string;
-    /**
-     * Adds a command to the CLI.
-     *
-     * 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
-     * @returns The CLI instance for method chaining
-     * @throws {CerebroError} If the command name already exists or validation fails
-     * @example
-     * ```typescript
-     * cli.addCommand({
-     *   name: 'build',
-     *   description: 'Build the project',
-     *   options: [
-     *     {
-     *       name: 'output',
-     *       alias: 'o',
-     *       type: String,
-     *       description: 'Output directory'
-     *     }
-     *   ],
-     *   execute: ({ options }) => {
-     *     console.log(`Building to ${options.output || 'dist'}`);
-     *   }
-     * });
-     * ```
-     */
-    addCommand<OD extends OptionDefinition<unknown> = OptionDefinition<unknown>>(command: ICommand<OD, T>): this;
-    /**
-     * Adds a plugin to extend the CLI functionality.
-     *
-     * Plugins can hook into various lifecycle events and modify the toolbox
-     * to provide additional functionality to commands.
-     * @param plugin The plugin to register
-     * @returns The CLI instance for method chaining
-     * @example
-     * ```typescript
-     * cli.addPlugin({
-     *   name: 'logger',
-     *   execute: (toolbox) => {
-     *     toolbox.logger = createCustomLogger();
-     *   }
-     * });
-     * ```
-     */
-    addPlugin(plugin: Plugin<T>): this;
-    /**
-     * Gets the plugin manager instance for advanced plugin management.
-     * @returns The plugin manager instance
-     */
-    getPluginManager(): PluginManager<T>;
-    /**
-     * Gets the CLI application name.
-     */
-    getCliName(): string;
-    /**
-     * Gets the package version if configured.
-     * @returns The package version or undefined
-     */
-    getPackageVersion(): string | undefined;
-    /**
-     * Gets the package name if configured.
-     * @returns The package name or undefined
-     */
-    getPackageName(): string | undefined;
-    /**
-     * Gets all registered commands.
-     * @returns A map of command names to command definitions
-     */
-    getCommands(): Map<string, ICommand<OptionDefinition<unknown>, T>>;
-    /**
-     * Gets the current working directory.
-     * @returns The current working directory path
-     */
-    getCwd(): string;
-    /**
-     * Disposes the CLI instance and cleans up resources.
-     *
-     * This method removes event listeners and performs cleanup to prevent memory leaks.
-     * Call this method when the CLI instance is no longer needed, especially in long-running
-     * processes or when creating multiple CLI instances.
-     * @example
-     * ```typescript
-     * const cli = new Cerebro('my-app');
-     * // ... use the cli
-     * cli.dispose(); // Clean up when done
-     * ```
-     */
-    dispose(): void;
-    /**
-     * Runs the CLI application.
-     *
-     * This method parses command line arguments, executes the appropriate command,
-     * and handles the complete CLI lifecycle including plugin initialization,
-     * error handling, process termination, and automatic cleanup.
-     * @param extraOptions Additional options to pass to commands
-     * @param extraOptions.shouldExitProcess Whether to exit the process after execution (default: true)
-     * @param extraOptions.autoDispose Whether to automatically cleanup/dispose resources after execution (default: true)
-     * @returns A promise that resolves when execution completes
-     * @throws {CommandNotFoundError} If the specified command doesn't exist
-     * @throws {Error} If command arguments are invalid or conflicting options are provided
-     * @example
-     * ```typescript
-     * // Run with default behavior (exits process and auto-disposes)
-     * await cli.run();
-     *
-     * // Run without exiting (for testing)
-     * await cli.run({ shouldExitProcess: false });
-     *
-     * // Run without auto-disposing (for reuse)
-     * await cli.run({ autoDispose: false });
-     * ```
-     */
-    run(extraOptions?: CliRunOptions): Promise<void>;
-    /**
-     * Runs a command programmatically from within another command.
-     *
-     * This method allows commands to call other commands during execution,
-     * enabling composition of commands and reusable command logic.
-     * @param commandName The name of the command to execute
-     * @param options Optional options including argv and other command options
-     * @returns A promise that resolves with the command's result
-     * @throws {CommandNotFoundError} If the specified command doesn't exist
-     * @throws {CerebroError} If command validation fails
-     * @example
-     * ```typescript
-     * cli.addCommand({
-     *   name: 'deploy',
-     *   execute: async ({ runtime, logger }) => {
-     *     logger.info('Building...');
-     *     await runtime.runCommand('build', { argv: ['--production'] });
-     *
-     *     logger.info('Testing...');
-     *     await runtime.runCommand('test', { argv: ['--coverage'] });
-     *   }
-     * });
-     * ```
-     */
-    runCommand(commandName: string, options?: RunCommandOptions): Promise<unknown>;
-}

package/dist/constants.d.ts

@@ -1,29 +0,0 @@
-/**
- * Output with this option will be formatted.
- */
-export declare const OUTPUT_NORMAL = 1;
-/**
- * Output with this option will be passed as-is.
- */
-export declare const OUTPUT_RAW = 2;
-/**
- * Output with this option will have any formatting stripped away.
- */
-export declare const OUTPUT_PLAIN = 4;
-/**
- * Output with this verbosity won't write anything at all.
- */
-export declare const VERBOSITY_QUIET = 16;
-/**
- * Output with this verbosity will write default content.
- */
-export declare const VERBOSITY_NORMAL = 32;
-/**
- * Output with this verbosity will be more detailed.
- */
-export declare const VERBOSITY_VERBOSE = 64;
-/**
- * Output with this verbosity will reveal internals.
- */
-export declare const VERBOSITY_DEBUG = 128;
-export declare const POSITIONALS_KEY = "positionals";

package/dist/default-env.d.ts

@@ -1,7 +0,0 @@
-import type { EnvDefinition } from "./types/command.d.ts";
-/**
- * Default environment variables used by Cerebro CLI framework.
- * These are displayed in the help output.
- */
-declare const defaultEnv: (EnvDefinition<string> | EnvDefinition<number> | EnvDefinition<boolean>)[];
-export default defaultEnv;

package/dist/default-options.d.ts

@@ -1,3 +0,0 @@
-import type { OptionDefinition } from "./types/command.d.ts";
-declare const defaultOptions: OptionDefinition<boolean>[];
-export default defaultOptions;

package/dist/empty-toolbox.d.ts

@@ -1,15 +0,0 @@
-import type { Toolbox as IToolbox } from "./types/toolbox.d.ts";
-declare class EmptyToolbox implements Partial<IToolbox> {
-    [x: string]: unknown;
-    result?: unknown;
-    argv?: IToolbox["argv"];
-    options?: IToolbox["options"];
-    argument?: IToolbox["argument"];
-    command: IToolbox["command"];
-    commandName: IToolbox["commandName"];
-    env?: IToolbox["env"];
-    logger?: IToolbox["logger"];
-    runtime?: IToolbox["runtime"];
-    constructor(commandName: IToolbox["commandName"], command: IToolbox["command"]);
-}
-export default EmptyToolbox;

package/dist/errors/cerebro-error.d.ts

@@ -1,10 +0,0 @@
-import { VisulimaError } from "@visulima/error";
-/**
- * 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>);
-}
-export default CerebroError;

package/dist/errors/command-not-found-error.d.ts

@@ -1,9 +0,0 @@
-import CerebroError from "./cerebro-error.d.ts";
-/**
- * Error thrown when a command is not found.
- */
-declare class CommandNotFoundError extends CerebroError {
-    readonly commandName: string;
-    constructor(commandName: string, suggestions?: string[]);
-}
-export default CommandNotFoundError;

package/dist/errors/command-validation-error.d.ts

@@ -1,10 +0,0 @@
-import CerebroError from "./cerebro-error.d.ts";
-/**
- * Error thrown when command validation fails.
- */
-declare class CommandValidationError extends CerebroError {
-    readonly commandName: string;
-    readonly missingOptions: string[];
-    constructor(commandName: string, missingOptions: string[]);
-}
-export default CommandValidationError;

package/dist/errors/completion-error.d.ts

@@ -1,9 +0,0 @@
-import CerebroError from "./cerebro-error.d.ts";
-/**
- * Error thrown when completion command operations fail.
- */
-declare class CompletionError extends CerebroError {
-    readonly troubleshooting: string[];
-    constructor(message: string, code: string, troubleshooting?: string[]);
-}
-export default CompletionError;

package/dist/errors/conflicting-options-error.d.ts

@@ -1,10 +0,0 @@
-import CerebroError from "./cerebro-error.d.ts";
-/**
- * Error thrown when there are conflicting options.
- */
-declare class ConflictingOptionsError extends CerebroError {
-    readonly option1: string;
-    readonly option2: string;
-    constructor(option1: string, option2: string);
-}
-export default ConflictingOptionsError;

package/dist/errors/plugin-error.d.ts

@@ -1,9 +0,0 @@
-import CerebroError from "./cerebro-error.d.ts";
-/**
- * Error thrown when plugin operations fail.
- */
-declare class PluginError extends CerebroError {
-    readonly pluginName: string;
-    constructor(pluginName: string, message: string, originalError?: Error);
-}
-export default PluginError;

package/dist/errors/update-notifier-error.d.ts

@@ -1,7 +0,0 @@
-import CerebroError from "./cerebro-error.d.ts";
-/**
- * Error thrown when update notifier operations fail.
- */
-export default class UpdateNotifierError extends CerebroError {
-    constructor(message: string, code?: string, context?: Record<string, unknown>);
-}