@sfdx-falcon/command
Version:
Contains SFDX-Falcon flavored extensions to @sfdx/command. Part of the SFDX-Falcon Library.
188 lines (187 loc) • 9.05 kB
TypeScript
/**
* @author Vivek M. Chawla <@VivekMChawla>
* @copyright 2019, Vivek M. Chawla / Salesforce. All rights reserved.
* @license BSD-3-Clause For full license text, see the LICENSE file in the repo root or
* `https://opensource.org/licenses/BSD-3-Clause`
* @file packages/command/src/sfdx-falcon-command.ts
* @summary Exports an abstract class that provides a framework for running an SFDX-Falcon
* flavored Salesforce CLI command.
* @description Exports an abstract class that provides a framework for running an SFDX-Falcon
* flavored Salesforce CLI command.
*/
import { OutputArgs } from '@oclif/parser';
import { OutputFlags } from '@oclif/parser';
import { flags } from '@salesforce/command';
import { SfdxCommand } from '@salesforce/command';
import { SfdxError } from '@salesforce/core';
import { SfdxFalconError } from '@sfdx-falcon/error';
import { SfdxFalconResult } from '@sfdx-falcon/status';
import { AnyJson } from '@sfdx-falcon/types';
import { JsonMap } from '@sfdx-falcon/types';
/**
* Enum. Defines the possible types of SFDX-Falcon Commands.
*/
export declare enum SfdxFalconCommandType {
STANDARD = "STANDARD",
GENERATOR = "GENERATOR",
UNKNOWN = "UNKNOWN"
}
/**
* Interface. Represents the Detail object that should be attached to the `SfdxFalconResult` object
* that's associated with the execution of an `SfdxFalconCommand`.
*/
export interface SfdxFalconCommandResultDetail {
commandName: string;
commandType: SfdxFalconCommandType;
commandFlags: OutputFlags<any>;
commandArgs: OutputArgs<any>;
commandExitCode: number;
enabledDebuggers: string[];
}
/**
* @abstract
* @class SfdxFalconCommand
* @extends SfdxCommand
* @summary Abstract base class class for building Salesforce CLI commands that use the SFDX-Falcon Library.
* @description Classes that extend SfdxFalconCommand will be able to leverage specialized "command
* and control" capabilities that the SFDX-Library adds on top of standard SFDX
* commands.
* @public
*/
export declare abstract class SfdxFalconCommand extends SfdxCommand {
protected static falconBaseflagsConfig: {
falcondebug: flags.Discriminated<flags.Array<string>>;
falcondebugerror: flags.Discriminated<flags.Boolean<boolean>>;
falcondebugsuccess: flags.Discriminated<flags.Boolean<boolean>>;
falcondebugdepth: flags.Discriminated<flags.Number>;
};
/** Name of the command defined by the derived class, eg. `falcon:adk:clone`. */
protected readonly commandName: string;
/** Type of command defined by the derived class. Possible values are `STANDARD` or `GENERATOR`. */
protected readonly commandType: SfdxFalconCommandType;
/** Reference to the package manifest (ie. `package.json`) of the package that owns the class that's extending `SfdxFalconCommand`. */
protected readonly packageJson: JsonMap;
/** Command-level `SfdxFalconResult` object. Should should be used as the ultimate parent to all other `SfdxFalconResult` objects used by logic executed by this command. */
protected readonly commandResult: SfdxFalconResult;
protected readonly commandResultDetail: SfdxFalconCommandResultDetail;
protected commandResponse: AnyJson;
protected outputDirectory: string;
protected projectDirectory: string;
protected sourceDirectory: string;
protected targetDirectory: string;
protected recipeFile: string;
protected configFile: string;
protected extendedOptions: JsonMap;
protected gitRemoteUri: string;
protected gitCloneDirectory: string;
protected falconDebugFlag: string[];
protected falconDebugErrorFlag: boolean;
protected falconDebugSuccessFlag: boolean;
protected falconDebugDepthFlag: number;
/**
* @constructs SfdxFalconCommand
* @param {any} argv Required. Part of the `oclif` command run process.
* Must be passed **unmodified** to the superclass.
* @param {any} config Required. Part of the `oclif` command run process.
* Must be passed **unmodified** to the superclass.
* @param {SfdxFalconCommandType} [commandType] Optional. Specifies the
* type of command being created. Defaults to `STANDARD`.
* @description Constructs an `SfdxFalconCommand` object.
* @private
*/
protected constructor(argv: any, config: any, commandType?: SfdxFalconCommandType);
/**
* @function run
* @returns {Promise<AnyJson>}
* @description Recieves the results from a Rejected Promise and processes
* them to settle out the ultimate exit status of this
* COMMAND Result.
* @protected
*/
run(): Promise<AnyJson>;
/** Contains all off the execution logic that is specific to the command being implemented. */
protected abstract runCommand(): Promise<unknown>;
/**
* @method buildFinalError
* @param {SfdxFalconError} cmdError Required. Error object used as
* the basis for the "friendly error message" being created
* by this method.
* @returns {SfdxError}
* @description Derived classes should override this method in order to build
* a user-friendly error message that is appropriate to the CLI
* Command that they are implementing. The output of this method
* will **always** be used by the `onError()` method of the
* `SfdxFalconCommand` base class to help communicate the
* end-of-command error state to the user.
* @protected
*/
protected buildFinalError(cmdError: SfdxFalconError): SfdxError;
/**
* @function onError
* @param {any} rejectedPromise Required.
* @param {boolean} [showErrorDebug] Optional. Determines if extended
* debugging output the Error Result can be shown.
* @param {boolean} [promptUser=true] Optional. Determines if the user
* will be prompted to display debug info. If `false`, debug info
* will be shown without requiring additional user input.
* @returns {Promise<void>}
* @description Recieves the results from a Rejected Promise and processes
* them to settle out the ultimate exit status of this
* COMMAND Result.
* @private
*/
private onError;
/**
* @function onSuccess
* @param {any} resolvedPromise Required.
* @returns {Promise<void>}
* @description Takes any resolved Promise which should be returned by some
* sort of Asynchronous call (implemented in a derived class)
* that does whatever "work" the CLI Command is meant to do and
* makes sure it's wrapped as an SFDX Falcon Result
* @protected
*/
private onSuccess;
/**
* @function getDerivedPackageJson
* @returns {JsonMap}
* @description Searches the package install location of whatever code has
* implemented a class that's derived from `SfdxFalconCommand`
* for that package's manifest (its `package.json` file), and
* loads it as a `JsonMap` via Node's `require()` method.
* @private
*/
private getDerivedPackageJson;
/**
* @function sfdxFalconCommandInit
* @returns {void}
* @description Initializes various SfdxFalconCommand structures.
* @private
*/
private sfdxFalconCommandInit;
/**
* @method prepareResponse
* @param {unknown} finalOutput Required. The ouput that came back
* from the `runCommand()` method, after being processed by
* either `onSuccess()` or `onFailure()`.
* @description Given the output returned by the `runCommand()` method and
* processed by either the `onSuccess()` or `onFailure()` methods,
* prepares the final output which will be returned from the
* `run()` method.
* @private
*/
private prepareResponse;
/**
* @method terminateWithError
* @param {boolean} [showErrorDebug=true] Optional. Determines if
* extended debugging output for the terminating Error can be shown.
* @param {boolean} [promptUser=true] Optional. Determines if the user
* will be prompted to display debug info. If `false`, debug info
* will be shown without requiring additional user input.
* @description Kills all ongoing async code (ie. Progress Notifications) and
* possibly renders an Error Debug before throwing an `SfdxError`
* so that the CLI can present user-friendly error info.
* @private
*/
private terminateWithError;
}