///
///
import { Readable, Writable } from 'stream';
import { CommandBuilder } from '../core';
import { ColorFormat } from '../format';
import { CommandClass, Command, Definition } from './Command';
import { CommandOption } from './options/utils';
type MakeOptional = Omit & Partial>;
type VoidIfEmpty = keyof T extends never ? void : never;
/**
* The base context of the CLI.
*
* All Contexts have to extend it.
*/
export type BaseContext = {
/**
* Environment variables.
*
* @default
* process.env
*/
env: Record;
/**
* The input stream of the CLI.
*
* @default
* process.stdin
*/
stdin: Readable;
/**
* The output stream of the CLI.
*
* @default
* process.stdout
*/
stdout: Writable;
/**
* The error stream of the CLI.
*
* @default
* process.stderr
*/
stderr: Writable;
/**
* Whether colors should be enabled.
*/
colorDepth: number;
};
export type CliContext = {
commandClass: CommandClass;
};
export type UserContextKeys = Exclude;
export type UserContext = Pick>;
export type PartialContext = UserContextKeys extends never ? Partial> | undefined | void : Partial> & UserContext;
export type RunContext = Partial> & UserContext;
export type RunCommand = Array> | CommandClass;
export type RunCommandNoContext = UserContextKeys extends never ? RunCommand : never;
export type CliOptions = Readonly<{
/**
* The label of the binary.
*
* Shown at the top of the usage information.
*/
binaryLabel?: string;
/**
* The name of the binary.
*
* Included in the path and the examples of the definitions.
*/
binaryName: string;
/**
* The version of the binary.
*
* Shown at the top of the usage information.
*/
binaryVersion?: string;
/**
* If `true`, the Cli will hook into the process standard streams to catch
* the output produced by console.log and redirect them into the context
* streams. Note: stdin isn't captured at the moment.
*
* @default
* false
*/
enableCapture: boolean;
/**
* If `true`, the Cli will use colors in the output. If `false`, it won't.
* If `undefined`, Clipanion will infer the correct value from the env.
*/
enableColors?: boolean;
}>;
export type MiniCli = CliOptions & {
/**
* Returns an Array representing the definitions of all registered commands.
*/
definitions(): Array;
/**
* Get the definition of a particular command.
*/
definition(command: CommandClass): Definition | null;
/**
* Formats errors using colors.
*
* @param error The error to format. If `error.name` is `'Error'`, it is replaced with `'Internal Error'`.
* @param opts.command The command whose usage will be included in the formatted error.
*/
error(error: Error, opts?: {
command?: Command | null;
}): string;
/**
* Returns a rich color format if colors are enabled, or a plain text format otherwise.
*
* @param colored Forcefully enable or disable colors.
*/
format(colored?: boolean): ColorFormat;
/**
* Compiles a command and its arguments using the `CommandBuilder`.
*
* @param input An array containing the name of the command and its arguments
*
* @returns The compiled `Command`, with its properties populated with the arguments.
*/
process(input: Array, context?: Partial): Command;
/**
* Runs a command.
*
* @param input An array containing the name of the command and its arguments
* @param context Overrides the Context of the main `Cli` instance
*
* @returns The exit code of the command
*/
run(input: Array, context?: Partial): Promise;
/**
* Returns the usage of a command.
*
* @param command The `Command` whose usage will be returned or `null` to return the usage of all commands.
* @param opts.detailed If `true`, the usage of a command will also include its description, details, and examples. Doesn't have any effect if `command` is `null` or doesn't have a `usage` property.
* @param opts.prefix The prefix displayed before each command. Defaults to `$`.
*/
usage(command?: CommandClass | Command | null, opts?: {
detailed?: boolean;
prefix?: string;
}): string;
};
export type MandatoryContextKeys = keyof MandatoryContext;
export type MandatoryContext = {
[K in Exclude as undefined extends Context[K] ? never : K]: Context[K];
};
export type UserProvidedContext = MandatoryContext & Partial>>;
export type MaybeProvidedContext = MandatoryContextKeys extends never ? {
context?: UserProvidedContext;
} : {
context: UserProvidedContext;
};
export type ProcessOptions = MaybeProvidedContext & {
input: Array;
/**
* @deprecated Experimental setting, exact behavior may change
*/
partial?: boolean;
};
/**
* An all-in-one helper that simultaneously instantiate a CLI and immediately
* executes it. All parameters are optional except the command classes and
* will be filled by sensible values for the current environment (for example
* the argv argument will default to `process.argv`, etc).
*
* Just like `Cli#runExit`, this function will set the `process.exitCode` value
* before returning.
*/
export declare function runExit(commandClasses: RunCommandNoContext): Promise;
export declare function runExit(commandClasses: RunCommand, context: RunContext): Promise;
export declare function runExit(options: Partial, commandClasses: RunCommandNoContext): Promise;
export declare function runExit(options: Partial, commandClasses: RunCommand, context: RunContext): Promise;
export declare function runExit(commandClasses: RunCommandNoContext, argv: Array): Promise;
export declare function runExit(commandClasses: RunCommand, argv: Array, context: RunContext): Promise;
export declare function runExit(options: Partial, commandClasses: RunCommandNoContext, argv: Array): Promise;
export declare function runExit(options: Partial, commandClasses: RunCommand, argv: Array, context: RunContext): Promise;
/**
* An all-in-one helper that simultaneously instantiate a CLI and immediately
* executes it. All parameters are optional except the command classes and
* will be filled by sensible values for the current environment (for example
* the argv argument will default to `process.argv`, etc).
*
* Unlike `runExit`, this function won't set the `process.exitCode` value
* before returning.
*/
export declare function run(commandClasses: RunCommandNoContext): Promise;
export declare function run(commandClasses: RunCommand, context: RunContext): Promise;
export declare function run(options: Partial, commandClasses: RunCommandNoContext): Promise;
export declare function run(options: Partial, commandClasses: RunCommand, context: RunContext): Promise;
export declare function run(commandClasses: RunCommandNoContext, argv: Array): Promise;
export declare function run(commandClasses: RunCommand, argv: Array, context: RunContext): Promise;
export declare function run(options: Partial, commandClasses: RunCommandNoContext, argv: Array): Promise;
export declare function run(options: Partial, commandClasses: RunCommand, argv: Array, context: RunContext): Promise;
/**
* @template Context The context shared by all commands. Contexts are a set of values, defined when calling the `run`/`runExit` functions from the CLI instance, that will be made available to the commands via `this.context`.
*/
export declare class Cli implements Omit, `process` | `run`> {
/**
* The default context of the CLI.
*
* Contains the stdio of the current `process`.
*/
static defaultContext: {
env: NodeJS.ProcessEnv;
stdin: NodeJS.ReadStream & {
fd: 0;
};
stdout: NodeJS.WriteStream & {
fd: 1;
};
stderr: NodeJS.WriteStream & {
fd: 2;
};
colorDepth: number;
};
private readonly builder;
protected readonly registrations: Map, {
index: number;
builder: CommandBuilder>;
specs: Map>;
}>;
readonly binaryLabel?: string;
readonly binaryName: string;
readonly binaryVersion?: string;
readonly enableCapture: boolean;
readonly enableColors?: boolean;
/**
* Creates a new Cli and registers all commands passed as parameters.
*
* @param commandClasses The Commands to register
* @returns The created `Cli` instance
*/
static from(commandClasses: RunCommand, options?: Partial): Cli;
constructor({ binaryLabel, binaryName: binaryNameOpt, binaryVersion, enableCapture, enableColors }?: Partial);
/**
* Registers a command inside the CLI.
*/
register(commandClass: CommandClass): void;
process(opts: ProcessOptions): Command;
process(input: Array, context: VoidIfEmpty>): Command;
process(input: Array, context: MakeOptional): Command;
run(input: Command | Array, context: VoidIfEmpty>): Promise;
run(input: Command | Array, context: MakeOptional): Promise;
/**
* Runs a command and exits the current `process` with the exit code returned by the command.
*
* @param input An array containing the name of the command and its arguments.
*
* @example
* cli.runExit(process.argv.slice(2))
*/
runExit(input: Command | Array, context: VoidIfEmpty>): Promise;
runExit(input: Command | Array, context: MakeOptional): Promise;
definition(commandClass: CommandClass, { colored }?: {
colored?: boolean;
}): Definition | null;
definitions({ colored }?: {
colored?: boolean;
}): Array;
usage(command?: CommandClass | Command | null, { colored, detailed, prefix }?: {
colored?: boolean;
detailed?: boolean;
prefix?: string;
}): string;
error(error: Error | any, { colored, command }?: {
colored?: boolean;
command?: Command | null;
}): string;
format(colored?: boolean): ColorFormat;
protected getUsageByRegistration(klass: CommandClass, opts?: {
detailed?: boolean;
inlineOptions?: boolean;
}): {
usage: string;
options: {
preferredName: string;
nameSet: string[];
definition: string;
description: string;
required: boolean;
}[];
};
protected getUsageByIndex(n: number, opts?: {
detailed?: boolean;
inlineOptions?: boolean;
}): {
usage: string;
options: {
preferredName: string;
nameSet: string[];
definition: string;
description: string;
required: boolean;
}[];
};
}
export {};