@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.
- package/CHANGELOG.md +36 -0
- package/LICENSE.md +471 -4345
- package/README.md +26 -0
- package/dist/commands/completion-command.d.ts +6 -5
- package/dist/commands/help-command.d.ts +9 -9
- package/dist/commands/help-command.js +63 -1
- package/dist/commands/readme-command.d.ts +6 -5
- package/dist/commands/readme-command.js +1 -1
- package/dist/commands/version-command.d.ts +4 -3
- package/dist/index.d.ts +422 -95
- package/dist/index.js +2 -1
- package/dist/logger/create-pail-logger.d.ts +779 -8
- package/dist/packem_shared/{Cerebro-CXEIHSN2.js → Cerebro-C1h3DXwy.js} +66 -8
- package/dist/packem_shared/{index-DNXLgme3.js → index--1UArng3.js} +1 -2
- package/dist/packem_shared/index.d-Br8HpP0A.d.ts +93 -0
- package/dist/packem_shared/lazyNamed-B278Tf9_.js +6 -0
- package/dist/packem_shared/plugin-manager.d-Du-YXFui.d.ts +541 -0
- package/dist/plugins/error-handler-plugin.d.ts +21 -19
- package/dist/plugins/runtime-version-check-plugin.d.ts +22 -20
- package/dist/plugins/update-notifier/update-notifier-plugin.d.ts +21 -8
- package/dist/plugins/update-notifier/update-notifier-plugin.js +1 -2
- package/dist/util/general/compile-cache.d.ts +38 -38
- package/dist/util/general/heap-tuning.d.ts +14 -77
- package/package.json +18 -18
- package/dist/cli.d.ts +0 -225
- package/dist/constants.d.ts +0 -29
- package/dist/default-env.d.ts +0 -7
- package/dist/default-options.d.ts +0 -3
- package/dist/empty-toolbox.d.ts +0 -16
- package/dist/errors/cerebro-error.d.ts +0 -10
- package/dist/errors/command-not-found-error.d.ts +0 -9
- package/dist/errors/command-validation-error.d.ts +0 -10
- package/dist/errors/completion-error.d.ts +0 -9
- package/dist/errors/conflicting-options-error.d.ts +0 -10
- package/dist/errors/plugin-error.d.ts +0 -9
- package/dist/errors/update-notifier-error.d.ts +0 -7
- package/dist/plugin-manager.d.ts +0 -53
- package/dist/plugins/update-notifier/cache.d.ts +0 -11
- package/dist/plugins/update-notifier/get-distribution-version.d.ts +0 -2
- package/dist/plugins/update-notifier/has-new-version.d.ts +0 -14
- package/dist/types/cli.d.ts +0 -113
- package/dist/types/command-line-usage.d.ts +0 -37
- package/dist/types/command.d.ts +0 -136
- package/dist/types/option-types.d.ts +0 -83
- package/dist/types/options.d.ts +0 -4
- package/dist/types/plugin.d.ts +0 -53
- package/dist/types/toolbox.d.ts +0 -120
- package/dist/util/arg-processing/get-boolean-values.d.ts +0 -7
- package/dist/util/arg-processing/get-parameter-option.d.ts +0 -7
- package/dist/util/arg-processing/map-option-type-label.d.ts +0 -3
- package/dist/util/arg-processing/option-is-boolean.d.ts +0 -9
- package/dist/util/arg-processing/remove-boolean-values.d.ts +0 -9
- package/dist/util/command-line-commands.d.ts +0 -10
- package/dist/util/command-line-usage/get-terminal-width.d.ts +0 -7
- package/dist/util/command-line-usage/index.d.ts +0 -3
- package/dist/util/command-line-usage/section/base-section.d.ts +0 -8
- package/dist/util/command-line-usage/section/content-section.d.ts +0 -65
- package/dist/util/command-line-usage/section/option-list-section.d.ts +0 -44
- package/dist/util/command-processing/command-processor.d.ts +0 -37
- package/dist/util/command-processing/command-validation.d.ts +0 -17
- package/dist/util/command-processing/nested-command-parser.d.ts +0 -25
- package/dist/util/command-processing/option-processor.d.ts +0 -44
- package/dist/util/data-processing/list-missing-arguments.d.ts +0 -15
- package/dist/util/data-processing/merge-arguments.d.ts +0 -7
- package/dist/util/general/find-alternatives.d.ts +0 -8
- package/dist/util/general/hide-bin.d.ts +0 -2
- package/dist/util/general/parse-raw-command.d.ts +0 -7
- package/dist/util/general/register-exception-handler.d.ts +0 -9
- package/dist/util/general/runtime-process.d.ts +0 -65
- package/dist/util/general/semver-gt.d.ts +0 -2
- package/dist/util/general/validate-input.d.ts +0 -24
- package/dist/util/process-env-variables.d.ts +0 -9
- package/dist/util/security.d.ts +0 -58
- 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;
|
package/dist/types/cli.d.ts
DELETED
|
@@ -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;
|
package/dist/types/command.d.ts
DELETED
|
@@ -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. <string>). It's often more useful to set a more descriptive type label, like <ms>, <files>, <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. <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
|
-
};
|
package/dist/types/options.d.ts
DELETED
package/dist/types/plugin.d.ts
DELETED
|
@@ -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
|
-
}
|
package/dist/types/toolbox.d.ts
DELETED
|
@@ -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<string, unknown>)
|
|
8
|
-
* @template TEnv - The environment variables type (defaults to Record<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,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 <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;
|