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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (74) hide show
  1. package/CHANGELOG.md +36 -0
  2. package/LICENSE.md +471 -4345
  3. package/README.md +26 -0
  4. package/dist/commands/completion-command.d.ts +6 -5
  5. package/dist/commands/help-command.d.ts +9 -9
  6. package/dist/commands/help-command.js +63 -1
  7. package/dist/commands/readme-command.d.ts +6 -5
  8. package/dist/commands/readme-command.js +1 -1
  9. package/dist/commands/version-command.d.ts +4 -3
  10. package/dist/index.d.ts +422 -95
  11. package/dist/index.js +2 -1
  12. package/dist/logger/create-pail-logger.d.ts +779 -8
  13. package/dist/packem_shared/{Cerebro-CXEIHSN2.js → Cerebro-C1h3DXwy.js} +66 -8
  14. package/dist/packem_shared/{index-DNXLgme3.js → index--1UArng3.js} +1 -2
  15. package/dist/packem_shared/index.d-Br8HpP0A.d.ts +93 -0
  16. package/dist/packem_shared/lazyNamed-B278Tf9_.js +6 -0
  17. package/dist/packem_shared/plugin-manager.d-Du-YXFui.d.ts +541 -0
  18. package/dist/plugins/error-handler-plugin.d.ts +21 -19
  19. package/dist/plugins/runtime-version-check-plugin.d.ts +22 -20
  20. package/dist/plugins/update-notifier/update-notifier-plugin.d.ts +21 -8
  21. package/dist/plugins/update-notifier/update-notifier-plugin.js +1 -2
  22. package/dist/util/general/compile-cache.d.ts +38 -38
  23. package/dist/util/general/heap-tuning.d.ts +14 -77
  24. package/package.json +18 -18
  25. package/dist/cli.d.ts +0 -225
  26. package/dist/constants.d.ts +0 -29
  27. package/dist/default-env.d.ts +0 -7
  28. package/dist/default-options.d.ts +0 -3
  29. package/dist/empty-toolbox.d.ts +0 -16
  30. package/dist/errors/cerebro-error.d.ts +0 -10
  31. package/dist/errors/command-not-found-error.d.ts +0 -9
  32. package/dist/errors/command-validation-error.d.ts +0 -10
  33. package/dist/errors/completion-error.d.ts +0 -9
  34. package/dist/errors/conflicting-options-error.d.ts +0 -10
  35. package/dist/errors/plugin-error.d.ts +0 -9
  36. package/dist/errors/update-notifier-error.d.ts +0 -7
  37. package/dist/plugin-manager.d.ts +0 -53
  38. package/dist/plugins/update-notifier/cache.d.ts +0 -11
  39. package/dist/plugins/update-notifier/get-distribution-version.d.ts +0 -2
  40. package/dist/plugins/update-notifier/has-new-version.d.ts +0 -14
  41. package/dist/types/cli.d.ts +0 -113
  42. package/dist/types/command-line-usage.d.ts +0 -37
  43. package/dist/types/command.d.ts +0 -136
  44. package/dist/types/option-types.d.ts +0 -83
  45. package/dist/types/options.d.ts +0 -4
  46. package/dist/types/plugin.d.ts +0 -53
  47. package/dist/types/toolbox.d.ts +0 -120
  48. package/dist/util/arg-processing/get-boolean-values.d.ts +0 -7
  49. package/dist/util/arg-processing/get-parameter-option.d.ts +0 -7
  50. package/dist/util/arg-processing/map-option-type-label.d.ts +0 -3
  51. package/dist/util/arg-processing/option-is-boolean.d.ts +0 -9
  52. package/dist/util/arg-processing/remove-boolean-values.d.ts +0 -9
  53. package/dist/util/command-line-commands.d.ts +0 -10
  54. package/dist/util/command-line-usage/get-terminal-width.d.ts +0 -7
  55. package/dist/util/command-line-usage/index.d.ts +0 -3
  56. package/dist/util/command-line-usage/section/base-section.d.ts +0 -8
  57. package/dist/util/command-line-usage/section/content-section.d.ts +0 -65
  58. package/dist/util/command-line-usage/section/option-list-section.d.ts +0 -44
  59. package/dist/util/command-processing/command-processor.d.ts +0 -37
  60. package/dist/util/command-processing/command-validation.d.ts +0 -17
  61. package/dist/util/command-processing/nested-command-parser.d.ts +0 -25
  62. package/dist/util/command-processing/option-processor.d.ts +0 -44
  63. package/dist/util/data-processing/list-missing-arguments.d.ts +0 -15
  64. package/dist/util/data-processing/merge-arguments.d.ts +0 -7
  65. package/dist/util/general/find-alternatives.d.ts +0 -8
  66. package/dist/util/general/hide-bin.d.ts +0 -2
  67. package/dist/util/general/parse-raw-command.d.ts +0 -7
  68. package/dist/util/general/register-exception-handler.d.ts +0 -9
  69. package/dist/util/general/runtime-process.d.ts +0 -65
  70. package/dist/util/general/semver-gt.d.ts +0 -2
  71. package/dist/util/general/validate-input.d.ts +0 -24
  72. package/dist/util/process-env-variables.d.ts +0 -9
  73. package/dist/util/security.d.ts +0 -58
  74. package/dist/util/text-processing/template-format.d.ts +0 -5
@@ -1,14 +0,0 @@
1
- declare const hasNewVersion: ({ alwaysRun, debug, distTag: distributionTag, pkg, registryUrl, updateCheckInterval, }: UpdateNotifierOptions) => Promise<string | undefined>;
2
- export type UpdateNotifierOptions = {
3
- alwaysRun?: boolean;
4
- debug?: boolean;
5
- distTag?: string;
6
- pkg: {
7
- name: string;
8
- version: string;
9
- };
10
- registryUrl?: string;
11
- shouldNotifyInNpmScript?: boolean;
12
- updateCheckInterval?: number;
13
- };
14
- export default hasNewVersion;
@@ -1,113 +0,0 @@
1
- import type PluginManager from "../plugin-manager.d.ts";
2
- import type { Command as ICommand, OptionDefinition } from "./command.d.ts";
3
- import type { Plugin } from "./plugin.d.ts";
4
- export type CommandSection = {
5
- footer?: string;
6
- header?: string;
7
- };
8
- export type CliRunOptions = {
9
- [key: string]: unknown;
10
- /**
11
- * Whether to automatically dispose/cleanup the CLI instance after execution
12
- * @default true
13
- */
14
- autoDispose?: boolean;
15
- shouldExitProcess?: boolean;
16
- };
17
- export type RunCommandOptions = {
18
- /**
19
- * Extra options to merge into the command's options.
20
- * These will be merged with the command's default options and parsed arguments.
21
- * Use this to override or add additional options programmatically.
22
- * @default Empty object
23
- */
24
- [key: string]: unknown;
25
- /**
26
- * Command-line arguments to pass to the command.
27
- * If not provided, uses the default argv from the CLI instance.
28
- * These arguments will be parsed and merged with the command's options.
29
- * @default Empty array
30
- */
31
- argv?: string[];
32
- };
33
- export interface Cli<T extends Console> {
34
- /**
35
- * Add an arbitrary command to the CLI.
36
- * @param command The command to add.
37
- * @returns self
38
- */
39
- addCommand: <OD extends OptionDefinition<unknown> = OptionDefinition<unknown>>(command: ICommand<OD, T>) => this;
40
- /**
41
- * Add a global option available to all commands.
42
- * Global options are parsed alongside command options and shown in help output.
43
- * @param option The option definition
44
- * @returns self
45
- */
46
- addGlobalOption: <V = unknown>(option: OptionDefinition<V>) => this;
47
- /**
48
- * Add a plugin to extend the CLI functionality
49
- * @param plugin The plugin to add.
50
- * @returns self
51
- */
52
- addPlugin: (plugin: Plugin<T>) => this;
53
- /**
54
- * Disposes the CLI instance and cleans up resources
55
- * @returns void
56
- */
57
- dispose: () => void;
58
- getCliName: () => string;
59
- getCommands: () => Map<string, ICommand<OptionDefinition<unknown>, T>>;
60
- getCommandSection: () => CommandSection;
61
- getCwd: () => string;
62
- /**
63
- * Gets all global options (built-in + custom).
64
- */
65
- getGlobalOptions: () => OptionDefinition<unknown>[];
66
- getPackageName: () => string | undefined;
67
- getPackageVersion: () => string | undefined;
68
- /**
69
- * Get the plugin manager instance
70
- * @returns The plugin manager
71
- */
72
- getPluginManager: () => PluginManager<T>;
73
- run: (extraOptions?: CliRunOptions) => Promise<void>;
74
- /**
75
- * Runs a command programmatically from within another command.
76
- * This allows commands to call other commands during execution.
77
- * @param commandName The name of the command to execute
78
- * @param options Optional options including argv and other command options
79
- * @returns A promise that resolves with the command's result (or void if command doesn't return a value)
80
- * @throws {Error} If the specified command doesn't exist or command arguments are invalid
81
- * @example
82
- * ```typescript
83
- * cli.addCommand({
84
- * name: 'deploy',
85
- * execute: async ({ runtime, logger }) => {
86
- * logger.info('Building...');
87
- * const buildResult = await runtime.runCommand('build', { argv: ['--production'] });
88
- * // buildResult is the return value from the build command's execute function
89
- *
90
- * logger.info('Testing...');
91
- * await runtime.runCommand('test', { argv: ['--coverage'] });
92
- * }
93
- * });
94
- * ```
95
- */
96
- runCommand: (commandName: string, options?: RunCommandOptions) => Promise<unknown>;
97
- setCommandSection: (commandSection: CommandSection) => this;
98
- /**
99
- * Set a default command, to display a different command if cli is call without command.
100
- * @param commandName
101
- * @returns self
102
- */
103
- setDefaultCommand: (commandName: string) => this;
104
- }
105
- /**
106
- * Any of the output types [[OUTPUT_NORMAL]], [[OUTPUT_RAW]] and [[OUTPUT_PLAIN]].
107
- */
108
- export type OutputType = 1 | 2 | 4;
109
- /**
110
- * Any of the verbosity types
111
- * [[VERBOSITY_QUIET]], [[VERBOSITY_NORMAL]], [[VERBOSITY_VERBOSE]] and [[VERBOSITY_DEBUG]].
112
- */
113
- export type VERBOSITY_LEVEL = 16 | 32 | 64 | 128 | 256;
@@ -1,37 +0,0 @@
1
- import type { TableOptions } from "@visulima/tabular";
2
- import type { ArgumentDefinition, OptionDefinition } from "./command.d.ts";
3
- /** A Content section comprises a header and one or more lines of content. */
4
- export interface Content {
5
- /**
6
- * Overloaded property, accepting data in one of four formats.
7
- * 1. A single string (one line of text).
8
- * 2. An array of strings (multiple lines of text).
9
- * 3. An array of arrays (recordset-style data). In this case, the data will be rendered in table format.
10
- * 4. An object with two properties - data and options. In this case, the data and options will be passed directly to the underlying table module for rendering.
11
- */
12
- content?: string[] | string[][] | string | {
13
- data: string[][];
14
- options: TableOptions;
15
- };
16
- /** The section header, always bold and underlined. */
17
- header?: string;
18
- /** Set to true to avoid indentation and wrapping. Useful for banners. */
19
- raw?: boolean;
20
- }
21
- /** A OptionList section adds a table displaying details of the available options. */
22
- export interface OptionList<O extends OptionDefinition<any> = any> {
23
- /** If specified, only options from this particular group will be printed. */
24
- group?: string[] | string;
25
- header?: string;
26
- /** The names of one of more option definitions to hide from the option list. */
27
- hide?: string[] | string;
28
- /** If specified, the -- prefix will be omitted from the option name. */
29
- isArgument?: boolean;
30
- /** An array of option definition objects. */
31
- optionList?: (ArgumentDefinition | O | OptionDefinition<boolean[]> | OptionDefinition<boolean> | OptionDefinition<number[]> | OptionDefinition<number> | OptionDefinition<string[]> | OptionDefinition<string>)[];
32
- /** If true, the option alias will be displayed after the name, i.e. --verbose, -v instead of -v, --verbose). */
33
- reverseNameOrder?: boolean;
34
- /** An options object suitable for passing into table. */
35
- tableOptions?: TableOptions;
36
- }
37
- export type Section = Content | OptionList;
@@ -1,136 +0,0 @@
1
- import type { OptionDefinition as BaseOptionDefinition } from "@visulima/command-line-args";
2
- import type { Content } from "./command-line-usage.d.ts";
3
- import type { Toolbox as IToolbox } from "./toolbox.d.ts";
4
- type TypeConstructor<T> = (value: unknown) => T extends (infer R)[] ? R | undefined : T | undefined;
5
- /**
6
- * Type constructor for environment variables.
7
- * Environment variables are always strings (or undefined), so the transform function receives string | undefined.
8
- */
9
- type EnvTypeConstructor<T> = (value: string | undefined) => T extends (infer R)[] ? R | undefined : T | undefined;
10
- type MultiplePropertyOptions<T> = T extends ReadonlyArray<unknown> ? {
11
- lazyMultiple: true;
12
- } | {
13
- multiple: true;
14
- } : unknown;
15
- export type OptionDefinition<T> = MultiplePropertyOptions<T> & Omit<BaseOptionDefinition, "type|defaultValue"> & {
16
- __camelCaseName__?: string;
17
- __negated__?: true;
18
- /**
19
- * A string or array of strings indicating the conflicting option(s).
20
- * Note: The default value for an option does not cause a conflict.
21
- */
22
- conflicts?: string[] | string;
23
- /** An initial value for the option. */
24
- defaultValue?: T;
25
- /** A string describing the option. */
26
- description?: string;
27
- /** Option is hidden from help */
28
- hidden?: boolean;
29
- implies?: Record<string, unknown>;
30
- /** Specifies whether the variable is required. */
31
- required?: boolean;
32
- /**
33
- * A setter function (you receive the output from this) enabling you to be specific about the type and value received. Typical values
34
- * are `String`, `Number` and `Boolean` but you can use a custom function.
35
- */
36
- type?: TypeConstructor<T>;
37
- /** A string to replace the default type string (e.g. &lt;string>). It's often more useful to set a more descriptive type label, like &lt;ms>, &lt;files>, &lt;command>, etc.. */
38
- typeLabel?: string;
39
- };
40
- export type PossibleOptionDefinition<OD> = OD | OptionDefinition<boolean[]> | OptionDefinition<boolean> | OptionDefinition<number[]> | OptionDefinition<number> | OptionDefinition<string[]> | OptionDefinition<string>;
41
- export type ArgumentDefinition<T = unknown> = Omit<OptionDefinition<T>, "multiple|lazyMultiple|defaultOption|alias|group|defaultValue">;
42
- /**
43
- * Environment variable definition for commands.
44
- * Used to document and provide type-safe access to environment variables a command supports.
45
- * @template T The type of the environment variable value
46
- */
47
- export interface EnvDefinition<T = string> {
48
- /** Default value if the environment variable is not set */
49
- defaultValue?: T;
50
- /** A description of what the environment variable does */
51
- description?: string;
52
- /** Environment variable is hidden from help */
53
- hidden?: boolean;
54
- /** The name of the environment variable */
55
- name: string;
56
- /**
57
- * A transform function to convert the string environment variable value to the desired type.
58
- * Typical values are `String`, `Number`, `Boolean` or custom functions.
59
- * The function receives `string | undefined` and should return the transformed value.
60
- */
61
- type?: EnvTypeConstructor<T>;
62
- /** A string to replace the default type string (e.g. &lt;string>). Useful for more descriptive type labels. */
63
- typeLabel?: string;
64
- }
65
- export type PossibleEnvDefinition = EnvDefinition<boolean> | EnvDefinition<number> | EnvDefinition;
66
- /**
67
- * Command interface with type-safe options and environment variables.
68
- * @template O - The option definition type
69
- * @template TContext - The toolbox context type (allows custom typing for better autocomplete)
70
- * @example
71
- * ```typescript
72
- * // Define your options type for autocomplete
73
- * type BuildOptions = {
74
- * output?: string;
75
- * production?: boolean;
76
- * watch?: boolean;
77
- * };
78
- *
79
- * type BuildEnv = {
80
- * apiKey?: string;
81
- * debug?: boolean;
82
- * };
83
- *
84
- * cli.addCommand({
85
- * name: "build",
86
- * options: [
87
- * { name: "output", type: String, alias: "o" },
88
- * { name: "production", type: Boolean },
89
- * { name: "watch", type: Boolean }
90
- * ],
91
- * env: [
92
- * { name: "API_KEY", type: String },
93
- * { name: "DEBUG", type: Boolean }
94
- * ],
95
- * execute: ({ options, env }: Toolbox<Console, BuildOptions, BuildEnv>) => {
96
- * // Full autocomplete on options and env!
97
- * console.log(options.output, options.production, env.apiKey);
98
- * }
99
- * });
100
- * ```
101
- */
102
- export interface Command<O extends OptionDefinition<unknown> = OptionDefinition<unknown>, TLogger extends Console = Console, TContext extends IToolbox<TLogger> = IToolbox<TLogger>> {
103
- /**
104
- * @internal
105
- */
106
- __conflictingOptions__?: PossibleOptionDefinition<O>[];
107
- /**
108
- * @internal
109
- */
110
- __requiredOptions__?: PossibleOptionDefinition<O>[];
111
- /** Potential other names for this command */
112
- alias?: string[] | string;
113
- /** Positional argument */
114
- argument?: ArgumentDefinition;
115
- /** The command path, an array that describes how to get to this command */
116
- commandPath?: string[];
117
- /** A tweet-sized summary of your command */
118
- description?: string;
119
- /** Environment variables supported by this command */
120
- env?: (EnvDefinition<boolean> | EnvDefinition<number> | EnvDefinition)[];
121
- /** The full command examples, can be multiple lines */
122
- examples?: string[] | string[][];
123
- /** The function for running your command, can be async */
124
- execute: ((toolbox: TContext) => Promise<void>) | ((toolbox: TContext) => void);
125
- /** The path to the file name for this command. */
126
- file?: string;
127
- /** Group commands together under a heading */
128
- group?: string;
129
- /** Should your command be shown in the listings */
130
- hidden?: boolean;
131
- /** The name of your command */
132
- name: string;
133
- options?: (O | OptionDefinition<boolean[]> | OptionDefinition<boolean> | OptionDefinition<number[]> | OptionDefinition<number> | OptionDefinition<string[]> | OptionDefinition<string>)[];
134
- usage?: Content[];
135
- }
136
- export {};
@@ -1,83 +0,0 @@
1
- /**
2
- * Helper types for creating type-safe commands with autocomplete support.
3
- * These types help you define your options and environment variables with full TypeScript autocomplete.
4
- * Use these types to create type-safe Toolbox interfaces for your commands.
5
- * @example
6
- * ```typescript
7
- * import { CreateOptions, CreateEnv, type Toolbox } from '@visulima/cerebro';
8
- *
9
- * // Define options with their original names (they'll be converted to camelCase)
10
- * type BuildOptions = CreateOptions<{
11
- * "output-dir": string | undefined;
12
- * "verbose": boolean | undefined;
13
- * "port": number | undefined;
14
- * }>;
15
- * // Result: { outputDir: string | undefined, verbose: boolean | undefined, port: number | undefined }
16
- *
17
- * // Define environment variables (UPPER_SNAKE_CASE -> camelCase)
18
- * type BuildEnv = CreateEnv<{
19
- * "API_KEY": string | undefined;
20
- * "DEBUG": boolean | undefined;
21
- * }>;
22
- * // Result: { apiKey: string | undefined, debug: boolean | undefined }
23
- *
24
- * // Use in your command
25
- * cli.addCommand({
26
- * name: "build",
27
- * options: [
28
- * { name: "output-dir", type: String },
29
- * { name: "verbose", type: Boolean },
30
- * { name: "port", type: Number }
31
- * ],
32
- * env: [
33
- * { name: "API_KEY", type: String },
34
- * { name: "DEBUG", type: Boolean }
35
- * ],
36
- * execute: ({ options, env }: Toolbox<Console, BuildOptions, BuildEnv>) => {
37
- * // Full autocomplete on options.outputDir, options.verbose, env.apiKey, etc.
38
- * console.log(options.outputDir, options.verbose, env.apiKey);
39
- * }
40
- * });
41
- * ```
42
- */
43
- /**
44
- * Converts option names to camelCase for the options object.
45
- * Options like "output-dir" become "outputDir" in the toolbox.
46
- * @example
47
- * ```typescript
48
- * // Option name: "output-dir" -> options.outputDir
49
- * // Option name: "api_key" -> options.apiKey
50
- * // Option name: "verbose" -> options.verbose
51
- * ```
52
- */
53
- export 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>;
54
- /**
55
- * Helper type to create a type-safe options object from option definitions.
56
- * @example
57
- * ```typescript
58
- * type MyOptions = CreateOptions<{
59
- * "output-dir": string | undefined;
60
- * "verbose": boolean | undefined;
61
- * "port": number | undefined;
62
- * }>;
63
- * // Result: { outputDir: string | undefined, verbose: boolean | undefined, port: number | undefined }
64
- * ```
65
- */
66
- export type CreateOptions<T extends Record<string, unknown>> = {
67
- [K in keyof T as OptionNameToCamelCase<K & string>]: T[K];
68
- };
69
- /**
70
- * Helper type to create a type-safe environment variables object from env definitions.
71
- * Environment variable names are converted from UPPER_SNAKE_CASE to camelCase.
72
- * @example
73
- * ```typescript
74
- * type MyEnv = CreateEnv<{
75
- * "API_KEY": string | undefined;
76
- * "DEBUG": boolean | undefined;
77
- * }>;
78
- * // Result: { apiKey: string | undefined, debug: boolean | undefined }
79
- * ```
80
- */
81
- export type CreateEnv<T extends Record<string, unknown>> = {
82
- [K in keyof T as OptionNameToCamelCase<K & string>]: T[K];
83
- };
@@ -1,4 +0,0 @@
1
- /**
2
- * A flexible object for the many "options" objects we throw around in cerebro.
3
- */
4
- export type Options = Record<string | symbol, unknown>;
@@ -1,53 +0,0 @@
1
- import type { Cli } from "./cli.d.ts";
2
- import type { Toolbox } from "./toolbox.d.ts";
3
- /**
4
- * Context provided to plugins during initialization
5
- */
6
- export interface PluginContext<T extends Console = Console> {
7
- /** The CLI instance */
8
- cli: Cli<T>;
9
- /** Current working directory */
10
- cwd: string;
11
- /** Logger instance */
12
- logger: T;
13
- }
14
- /**
15
- * Plugin interface with lifecycle hooks
16
- */
17
- export interface Plugin<T extends Console = Console> {
18
- /**
19
- * Called after command execution completes successfully
20
- * @param toolbox The command toolbox
21
- * @param result The result returned by the command
22
- */
23
- afterCommand?: (toolbox: Toolbox<T>, result: unknown) => Promise<void> | void;
24
- /**
25
- * Called before command execution
26
- * @param toolbox The command toolbox
27
- */
28
- beforeCommand?: (toolbox: Toolbox<T>) => Promise<void> | void;
29
- /** Plugin dependencies (other plugin names that must be loaded first) */
30
- dependencies?: string[];
31
- /** Plugin description */
32
- description?: string;
33
- /**
34
- * Called during command execution (for plugins that extend toolbox functionality)
35
- * @param toolbox The command toolbox
36
- */
37
- execute?: (toolbox: Toolbox<T>) => Promise<void> | void;
38
- /**
39
- * Called once during plugin initialization
40
- * @param context The plugin context
41
- */
42
- init?: (context: PluginContext<T>) => Promise<void> | void;
43
- /** Plugin name (must be unique) */
44
- name: string;
45
- /**
46
- * Called when an error occurs during command execution
47
- * @param error The error that occurred
48
- * @param toolbox The command toolbox
49
- */
50
- onError?: (error: Error, toolbox: Toolbox<T>) => Promise<void> | void;
51
- /** Plugin version */
52
- version?: string;
53
- }
@@ -1,120 +0,0 @@
1
- import type { Cli as ICli } from "./cli.d.ts";
2
- import type { Command as ICommand } from "./command.d.ts";
3
- import type { Options } from "./options.d.ts";
4
- /**
5
- * Type-safe Toolbox interface with customizable options and environment variable types.
6
- * @template TLogger - The logger type (defaults to Console)
7
- * @template TOptions - The options type (defaults to Options/Record&lt;string, unknown>)
8
- * @template TEnv - The environment variables type (defaults to Record&lt;string, unknown>)
9
- */
10
- export interface Toolbox<TLogger extends Console = Console, TOptions extends Record<string, unknown> = Options, TEnv extends Record<string, unknown> = Record<string, unknown>> extends Cerebro.ExtensionOverrides {
11
- /**
12
- * The argument passed to the command.
13
- * For example, if you run `cerebro foo bar baz`, then this will be `["foo", "bar", "baz"]`.
14
- * @example
15
- * ```typescript
16
- * cli.addCommand({
17
- * name: "copy",
18
- * argument: {
19
- * name: "files",
20
- * type: String,
21
- * description: "Files to copy"
22
- * },
23
- * execute: ({ argument }) => {
24
- * // argument is an array of strings
25
- * // argument[0] is the first file, argument[1] is the second, etc.
26
- * argument.forEach((file) => console.log(`Copying ${file}...`));
27
- * }
28
- * });
29
- * ```
30
- */
31
- argument: string[];
32
- argv: ReadonlyArray<string>;
33
- /**
34
- * The command that is being executed.
35
- */
36
- command: ICommand;
37
- /**
38
- * The name of the command that is being executed.
39
- */
40
- commandName: string;
41
- /**
42
- * Environment variables processed from the command definition.
43
- * Values are transformed according to their type definitions and default values.
44
- * @example
45
- * ```typescript
46
- * // Define env types when creating command
47
- * type MyEnv = { apiKey: string; debug: boolean };
48
- *
49
- * cli.addCommand({
50
- * name: "build",
51
- * env: [
52
- * { name: "API_KEY", type: String },
53
- * { name: "DEBUG", type: Boolean }
54
- * ],
55
- * execute: ({ env }) => {
56
- * // env.apiKey and env.debug are now typed!
57
- * console.log(env.apiKey, env.debug);
58
- * }
59
- * });
60
- * ```
61
- */
62
- env: TEnv;
63
- /** The logger instance. */
64
- logger: TLogger;
65
- /**
66
- * Any optional parameters. Typically coming from command-line
67
- * argument like this: `--force -p tsconfig-mjson`.
68
- * @example
69
- * ```typescript
70
- * // Define options type for better autocomplete
71
- * type MyOptions = {
72
- * output?: string;
73
- * verbose?: boolean;
74
- * port?: number;
75
- * };
76
- *
77
- * cli.addCommand({
78
- * name: "serve",
79
- * options: [
80
- * { name: "output", type: String },
81
- * { name: "verbose", type: Boolean },
82
- * { name: "port", type: Number }
83
- * ],
84
- * execute: ({ options }: { options: MyOptions }) => {
85
- * // options.output, options.verbose, options.port are typed!
86
- * console.log(options.output, options.verbose, options.port);
87
- * }
88
- * });
89
- * ```
90
- */
91
- options: TOptions;
92
- /**
93
- * Raw tokens that command-line-args could not assign to a defined
94
- * option — typically everything after a `--` separator, since
95
- * cerebro runs the parser with `stopAtFirstUnknown: true`.
96
- *
97
- * Use this for passthrough patterns like
98
- * `my-cmd foo bar -- --flag=value --other`, where everything after
99
- * `--` is forwarded to an inner tool (`create-vite`, a template
100
- * runner, etc.). Empty array when there was no `--` segment.
101
- * @example
102
- * ```typescript
103
- * cli.addCommand({
104
- * name: "create",
105
- * argument: { name: "template", type: String },
106
- * execute: ({ argument, rawUnknown }) => {
107
- * // `vis create vite my-app -- --template react-ts`
108
- * // → argument === ["vite", "my-app"]
109
- * // → rawUnknown === ["--template", "react-ts"]
110
- * spawnSync("npm", ["create", "vite", ...rawUnknown]);
111
- * },
112
- * });
113
- * ```
114
- */
115
- rawUnknown: ReadonlyArray<string>;
116
- /**
117
- * This is the instance of the CLI that is running the command.
118
- */
119
- runtime: ICli<TLogger>;
120
- }
@@ -1,7 +0,0 @@
1
- import type { OptionDefinition, PossibleOptionDefinition } from "../../types/command.d.ts";
2
- /**
3
- * Gets the values of any boolean arguments that were specified on the command line with a value.
4
- * These arguments were removed by removeBooleanValues.
5
- */
6
- declare const getBooleanValues: <OD extends OptionDefinition<unknown>>(arguments_: string[], options: PossibleOptionDefinition<OD>[], optionMapByName?: Map<string, PossibleOptionDefinition<OD>>, optionMapByAlias?: Map<string, PossibleOptionDefinition<OD>>) => Partial<OD>;
7
- export default getBooleanValues;
@@ -1,7 +0,0 @@
1
- import type { OptionDefinition, PossibleOptionDefinition } from "../../types/command.d.ts";
2
- declare const getParameterOption: <OD extends OptionDefinition<unknown>>(argument: string, options: PossibleOptionDefinition<OD>[], optionMapByName?: Map<string, PossibleOptionDefinition<OD>>, optionMapByAlias?: Map<string, PossibleOptionDefinition<OD>>) => {
3
- argName?: string;
4
- argValue?: string;
5
- option?: PossibleOptionDefinition<OD>;
6
- };
7
- export default getParameterOption;
@@ -1,3 +0,0 @@
1
- import type { OptionDefinition, PossibleOptionDefinition } from "../../types/command.d.ts";
2
- declare const mapOptionTypeLabel: <OD extends OptionDefinition<any>>(definition: PossibleOptionDefinition<OD>) => PossibleOptionDefinition<OD>;
3
- export default mapOptionTypeLabel;
@@ -1,9 +0,0 @@
1
- import type { OptionDefinition, PossibleOptionDefinition } from "../../types/command.d.ts";
2
- /**
3
- * Determines whether an option definition is typed as Boolean.
4
- * @template OD
5
- * @param option Option definition to inspect.
6
- * @returns True when the option's type constructor is the built-in `Boolean`.
7
- */
8
- declare const optionIsBoolean: <OD extends OptionDefinition<unknown>>(option: PossibleOptionDefinition<OD>) => boolean;
9
- export default optionIsBoolean;
@@ -1,9 +0,0 @@
1
- import type { OptionDefinition, PossibleOptionDefinition } from "../../types/command.d.ts";
2
- /**
3
- * Removes boolean values from arguments to prevent commandLineArgs errors.
4
- * commandLineArgs throws an error if we pass a value for a boolean arg as follows:
5
- * myCommand -a=true --booleanArg=false --otherArg true
6
- * This function removes these booleans to avoid errors from commandLineArgs.
7
- */
8
- declare const removeBooleanValues: <OD extends OptionDefinition<any>>(arguments_: string[], options: PossibleOptionDefinition<OD>[], optionMapByName?: Map<string, PossibleOptionDefinition<OD>>, optionMapByAlias?: Map<string, PossibleOptionDefinition<OD>>) => string[];
9
- export default removeBooleanValues;
@@ -1,10 +0,0 @@
1
- /**
2
- * Copied from
3
- * The MIT License (MIT)
4
- * Copyright (c) 2015-21 Lloyd Brookes &lt;75pound@gmail.com>
5
- */
6
- declare const commandLineCommands: (commands: (string | null)[], argv: string[]) => {
7
- argv: string[];
8
- command: string | null;
9
- };
10
- export default commandLineCommands;
@@ -1,7 +0,0 @@
1
- /**
2
- * Gets the terminal width from the CEREBRO_TERMINAL_WIDTH environment variable.
3
- * Falls back to undefined if not set, allowing the tabular package to detect it automatically.
4
- * @returns The terminal width as a number, or undefined if not set
5
- */
6
- declare const getTerminalWidth: () => number | undefined;
7
- export default getTerminalWidth;
@@ -1,3 +0,0 @@
1
- import type { Section as ISection } from "../../types/command-line-usage.d.ts";
2
- declare const commandLineUsage: (sections: ISection[]) => string;
3
- export default commandLineUsage;
@@ -1,8 +0,0 @@
1
- declare class BaseSection {
2
- protected lines: string[];
3
- constructor();
4
- add(line: string): void;
5
- toString(): string;
6
- header(text: string): void;
7
- }
8
- export default BaseSection;