@adonisjs/ace
Version:
A CLI framework for Node.js
350 lines (349 loc) • 9.67 kB
TypeScript
import Macroable from '@poppinss/macroable';
import type { Prompt } from '@poppinss/prompts';
import type { Colors } from '@poppinss/cliui/types';
import type { Kernel } from '../kernel.ts';
import type { Flag, Argument, ParsedOutput, UIPrimitives, CommandOptions, CommandMetaData, FlagsParserOptions, ArgumentsParserOptions } from '../types.ts';
/**
* The base command sets the foundation for defining ace commands.
* Every command should inherit from the base command.
*
* @example
* ```ts
* export class MyCommand extends BaseCommand {
* static commandName = 'my:command'
* static description = 'My custom command'
*
* async run() {
* this.logger.info('Hello from my command!')
* }
* }
* ```
*/
export declare class BaseCommand extends Macroable {
protected kernel: Kernel<any>;
protected parsed: ParsedOutput;
ui: UIPrimitives;
prompt: Prompt;
/**
* Whether the command class has been booted
*/
static booted: boolean;
/**
* Configuration options accepted by the command
*/
static options: CommandOptions;
/**
* A collection of aliases for the command
*/
static aliases: string[];
/**
* The command name one can type to run the command
*/
static commandName: string;
/**
* The command description
*/
static description: string;
/**
* The help text for the command. Help text can be a multiline
* string explaining the usage of command
*/
static help?: string | string[];
/**
* Registered arguments
*/
static args: Argument[];
/**
* Registered flags
*/
static flags: Flag[];
/**
* Define static properties on the class. During inheritance, certain
* properties must inherit from the parent.
*
* @example
* ```ts
* MyCommand.boot()
* ```
*/
static boot(): void;
/**
* Specify the argument the command accepts. The arguments via the CLI
* will be accepted in the same order as they are defined.
*
* Mostly, you will be using the `@args` decorator to define the arguments.
*
* @param name - The name of the argument
* @param options - Configuration options for the argument
*
* @example
* ```ts
* Command.defineArgument('entity', { type: 'string' })
* Command.defineArgument('files', { type: 'spread', required: false })
* ```
*/
static defineArgument(name: string, options: Partial<Argument> & {
type: 'string' | 'spread';
}): void;
/**
* Specify a flag the command accepts.
*
* Mostly, you will be using the `@flags` decorator to define a flag.
*
* @param name - The name of the flag
* @param options - Configuration options for the flag
*
* @example
* ```ts
* Command.defineFlag('connection', { type: 'string', required: true })
* Command.defineFlag('force', { type: 'boolean' })
* Command.defineFlag('tags', { type: 'array' })
* ```
*/
static defineFlag(name: string, options: Partial<Flag> & {
type: 'string' | 'boolean' | 'array' | 'number';
}): void;
/**
* Returns the options for parsing flags and arguments
*
* @param options - Optional parser options to merge
*/
static getParserOptions(options?: FlagsParserOptions): {
flagsParserOptions: Required<FlagsParserOptions>;
argumentsParserOptions: ArgumentsParserOptions[];
};
/**
* Serializes the command to JSON. The return value satisfies the
* {@link CommandMetaData}
*
* @example
* ```ts
* const metadata = MyCommand.serialize()
* console.log(metadata.commandName) // 'my:command'
* ```
*/
static serialize(): CommandMetaData;
/**
* Validate the yargs parsed output against the command.
*
* @param parsedOutput - The parsed CLI input to validate
*
* @example
* ```ts
* const parsed = { args: ['value'], flags: { force: true }, unknownFlags: [] }
* MyCommand.validate(parsed)
* ```
*/
static validate(parsedOutput: ParsedOutput): void;
/**
* Check if a command has been hydrated
*/
protected hydrated: boolean;
/**
* The exit code for the command
*/
exitCode?: number;
/**
* The error raised at the time of executing the command.
* The value is undefined if no error is raised.
*/
error?: any;
/**
* The result property stores the return value of the "run"
* method (unless command sets it explicitly)
*/
result?: any;
/**
* Logger to log messages
*
* @example
* ```ts
* this.logger.info('Command executed successfully')
* this.logger.error('Something went wrong')
* ```
*/
get logger(): import("@poppinss/cliui").Logger;
/**
* Add colors to console messages
*
* @example
* ```ts
* this.logger.info(this.colors.green('Success!'))
* this.logger.error(this.colors.red('Error!'))
* ```
*/
get colors(): Colors;
/**
* Is the current command the main command executed from the CLI
*
* @example
* ```ts
* if (this.isMain) {
* this.logger.info('This is the main command')
* }
* ```
*/
get isMain(): boolean;
/**
* Reference to the command name
*/
get commandName(): string;
/**
* Reference to the command options
*/
get options(): CommandOptions;
/**
* Reference to the command args
*/
get args(): Argument[];
/**
* Reference to the command flags
*/
get flags(): Flag[];
/**
* Create a new base command instance
*
* @param kernel - The Ace kernel instance
* @param parsed - The parsed CLI input
* @param ui - UI primitives for output
* @param prompt - Prompt utilities for user interaction
*/
constructor(kernel: Kernel<any>, parsed: ParsedOutput, ui: UIPrimitives, prompt: Prompt);
/**
* Hydrate command by setting class properties from the parsed output
*
* @example
* ```ts
* command.hydrate()
* console.log(command.name) // Argument value
* console.log(command.force) // Flag value
* ```
*/
hydrate(): void;
/**
* The run method should include the implementation for the command.
*
* @param _ - Additional arguments (not used in base implementation)
*
* @example
* ```ts
* async run() {
* this.logger.info('Running my command')
* return 'Command completed'
* }
* ```
*/
run(..._: any[]): Promise<any>;
/**
* Executes the command by running the command's run method.
*
* @example
* ```ts
* const result = await command.exec()
* console.log('Exit code:', command.exitCode)
* ```
*/
exec(): Promise<any>;
/**
* JSON representation of the command
*
* @example
* ```ts
* const json = command.toJSON()
* console.log(json.commandName, json.exitCode)
* ```
*/
toJSON(): {
commandName: string;
options: CommandOptions;
args: any[];
flags: {
[argName: string]: any;
};
error: any;
result: any;
exitCode: number | undefined;
};
/**
* Assert the command exits with a given exit code
*
* @param code - The expected exit code
*
* @example
* ```ts
* command.assertExitCode(0) // Assert successful execution
* command.assertExitCode(1) // Assert failure
* ```
*/
assertExitCode(code: number): void;
/**
* Assert the command does not exit with a given exit code
*
* @param code - The exit code that should not be used
*
* @example
* ```ts
* command.assertNotExitCode(1) // Assert no failure
* ```
*/
assertNotExitCode(code: number): void;
/**
* Assert the command exits with zero exit code
*
* @example
* ```ts
* command.assertSucceeded() // Assert success
* ```
*/
assertSucceeded(): void;
/**
* Assert the command exits with non-zero exit code
*
* @example
* ```ts
* command.assertFailed() // Assert failure
* ```
*/
assertFailed(): void;
/**
* Assert command logs the expected message
*
* @param message - The expected log message
* @param stream - Optional stream to check ('stdout' or 'stderr')
*
* @example
* ```ts
* command.assertLog('Command executed successfully')
* command.assertLog('Error occurred', 'stderr')
* ```
*/
assertLog(message: string, stream?: 'stdout' | 'stderr'): void;
/**
* Assert command logs a message matching the given regex
*
* @param matchingRegex - The regex pattern to match against log messages
* @param stream - Optional stream to check ('stdout' or 'stderr')
*
* @example
* ```ts
* command.assertLogMatches(/^Command.*completed$/)
* command.assertLogMatches(/error/i, 'stderr')
* ```
*/
assertLogMatches(matchingRegex: RegExp, stream?: 'stdout' | 'stderr'): void;
/**
* Assert the command prints a table with the expected rows to stdout
*
* @param rows - The expected table rows as arrays of strings
*
* @example
* ```ts
* command.assertTableRows([
* ['Name', 'Age'],
* ['John', '25'],
* ['Jane', '30']
* ])
* ```
*/
assertTableRows(rows: string[][]): void;
}