@salesforce/command/lib/sfdxCommand.js

"use strict";
/*
 * Copyright (c) 2018, salesforce.com, inc.
 * All rights reserved.
 * SPDX-License-Identifier: BSD-3-Clause
 * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
 */
Object.defineProperty(exports, "__esModule", { value: true });
const command_1 = require("@oclif/command");
const core_1 = require("@salesforce/core");
const kit_1 = require("@salesforce/kit");
const ts_types_1 = require("@salesforce/ts-types");
const ts_types_2 = require("@salesforce/ts-types");
const chalk_1 = require("chalk");
const docOpts_1 = require("./docOpts");
const sfdxFlags_1 = require("./sfdxFlags");
const ux_1 = require("./ux");
core_1.Messages.importMessagesDirectory(__dirname);
/**
 * A class that handles command results and formatting.  Use this class
 * to override command display behavior or to get complex table formatting.
 * For simple table formatting, use {@link SfdxCommand.tableColumnData} to
 * define a string array of keys to use as table columns.
 */
class Result {
    constructor(config = {}) {
        this.tableColumnData = config.tableColumnData;
        if (config.display) {
            this.display = config.display.bind(this);
        }
    }
    display() {
        if (this.tableColumnData) {
            if (Array.isArray(this.data) && this.data.length) {
                this.ux.table(this.data, this.tableColumnData);
            }
            else {
                this.ux.log('No results found.');
            }
        }
    }
}
exports.Result = Result;
/**
 * A base command that provides convenient access to common SFDX flags, a logger,
 * CLI output formatting, scratch orgs, and devhubs.  Extend this command and set
 * various static properties and a flag configuration to add SFDX behavior.
 *
 * @extends @oclif/command
 * @see https://github.com/oclif/command
 */
class SfdxCommand extends command_1.default {
    constructor() {
        super(...arguments);
        this.isJson = false;
    }
    // Overrides @oclif/command static flags property.  Adds username flags
    // if the command supports them.  Builds flags defined by the command's
    // flagsConfig static property.
    // tslint:disable-next-line no-any (matches oclif)
    static get flags() {
        return sfdxFlags_1.buildSfdxFlags(this.flagsConfig, {
            targetdevhubusername: !!(this.supportsDevhubUsername || this.requiresDevhubUsername),
            targetusername: !!(this.supportsUsername || this.requiresUsername)
        });
    }
    static get usage() {
        return docOpts_1.DocOpts.generate(this);
    }
    static getVarArgsConfig() {
        if (ts_types_1.isBoolean(this.varargs)) {
            return this.varargs ? {} : undefined;
        }
        // Don't let others muck with this commands config
        return Object.assign({}, this.varargs);
    }
    // TypeScript does not yet have assertion-free polymorphic access to a class's static side from the instance side
    get statics() {
        return this.constructor;
    }
    async _run() {
        // If a result is defined for the command, use that.  Otherwise check for a
        // tableColumnData definition directly on the command.
        if (!this.statics.result.tableColumnData && this.statics.tableColumnData) {
            this.statics.result.tableColumnData = this.statics.tableColumnData;
        }
        this.result = new Result(this.statics.result);
        let err;
        try {
            await this.init();
            return (this.result.data = await this.run());
        }
        catch (e) {
            err = e;
            await this.catch(e);
        }
        finally {
            await this.finally(err);
        }
    }
    // Assign this.project if the command requires to be run from within a project.
    async assignProject() {
        // Throw an error if the command requires to be run from within an SFDX project but we
        // don't have a local config.
        try {
            this.project = await core_1.SfdxProject.resolve();
        }
        catch (err) {
            if (err.name === 'InvalidProjectWorkspace') {
                throw core_1.SfdxError.create('@salesforce/command', 'command', 'RequiresProjectError');
            }
            throw err;
        }
    }
    // Assign this.org if the command supports or requires a username.
    async assignOrg() {
        // Create an org from the username and set on this
        try {
            this.org = await core_1.Org.create({
                aliasOrUsername: this.flags.targetusername,
                aggregator: this.configAggregator
            });
            if (this.flags.apiversion) {
                this.org.getConnection().setApiVersion(this.flags.apiversion);
            }
        }
        catch (err) {
            if (this.statics.requiresUsername) {
                if (err.name === 'NoUsername') {
                    throw core_1.SfdxError.create('@salesforce/command', 'command', 'RequiresUsernameError');
                }
                throw err;
            }
        }
    }
    // Assign this.hubOrg if the command supports or requires a devhub username.
    async assignHubOrg() {
        // Create an org from the devhub username and set on this
        try {
            this.hubOrg = await core_1.Org.create({
                aliasOrUsername: this.flags.targetdevhubusername,
                aggregator: this.configAggregator,
                isDevHub: true
            });
            if (this.flags.apiversion) {
                this.hubOrg.getConnection().setApiVersion(this.flags.apiversion);
            }
        }
        catch (err) {
            // Throw an error if the command requires a devhub and there is no targetdevhubusername
            // flag set and no defaultdevhubusername set.
            if (this.statics.requiresDevhubUsername) {
                if (err.name === 'AuthInfoCreationError' || err.name === 'NoUsername') {
                    throw core_1.SfdxError.create('@salesforce/command', 'command', 'RequiresDevhubUsernameError');
                }
                throw core_1.SfdxError.wrap(err);
            }
        }
    }
    shouldEmitHelp() {
        // If -h was given and this command does not define its own flag with `char: 'h'`,
        // indicate that help should be emitted.
        if (!this.argv.includes('-h')) {
            // If -h was not given, nothing else to do here.
            return false;
        }
        // Check each flag config to see if -h has been overridden...
        const flags = this.statics.flags || {};
        for (const k of Object.keys(flags)) {
            if (k !== 'help' && flags[k].char === 'h') {
                // If -h is configured for anything but help, the subclass should handle it itself.
                return false;
            }
        }
        // Otherwise, -h was either not overridden by the subclass, or the subclass includes a specific help flag config.
        return true;
    }
    async init() {
        // If we made it to the init method, the exit code should not be set yet. It will be
        // successful unless the base init or command throws an error.
        process.exitCode = 0;
        // Ensure this.isJson, this.logger, and this.ux are set before super init, flag parsing, or help generation
        // (all of which can throw and prevent these from being available for command error handling).
        const isContentTypeJSON = kit_1.env.getString('SFDX_CONTENT_TYPE', '').toUpperCase() === 'JSON';
        this.isJson = this.argv.includes('--json') || isContentTypeJSON;
        // Regex match on loglevel flag in argv and set on the root logger so the proper log level
        // is used.  If no match, the default root log level is used.
        const loglevel = this.argv.join(' ').match(/--loglevel\s*=?\s*([a-z]+)/);
        if (loglevel) {
            (await core_1.Logger.root()).setLevel(core_1.Logger.getLevelByName(loglevel[1]));
        }
        await this.initLoggerAndUx();
        // If the -h flag is set in argv and not overridden by the subclass, emit help and exit.
        if (this.shouldEmitHelp()) {
            this._help();
        }
        // Finally invoke the super init now that this.ux is properly configured.
        await super.init();
        // Load messages
        const messages = core_1.Messages.loadMessages('@salesforce/command', 'command');
        // Turn off strict parsing if varargs are set.  Otherwise use static strict setting.
        const strict = this.statics.varargs ? !this.statics.varargs : this.statics.strict;
        // Parse the command to get flags and args
        const { args, flags, argv } = this.parse({
            flags: this.statics.flags,
            args: this.statics.args,
            strict
        });
        this.flags = flags;
        this.args = args;
        // The json flag was set by the environment variables
        if (isContentTypeJSON) {
            this.flags.json = true;
        }
        this.warnIfDeprecated();
        // If this command supports varargs, parse them from argv.
        if (this.statics.varargs) {
            const argVals = Object.values(args);
            const varargs = argv.filter(val => !argVals.includes(val));
            this.varargs = this.parseVarargs(varargs);
        }
        this.logger.info(`Running command [${this.statics.name}] with flags [${JSON.stringify(flags)}] and args [${JSON.stringify(args)}]`);
        //
        // Verify the command args and flags meet the requirements
        //
        this.configAggregator = await core_1.ConfigAggregator.create();
        // Assign this.project if the command requires to be run from within a project.
        if (this.statics.requiresProject) {
            await this.assignProject();
        }
        // Get the apiVersion from the config aggregator and display a warning
        // if it's overridden.
        const apiVersion = this.configAggregator.getInfo('apiVersion');
        if (apiVersion && apiVersion.value && !flags.apiversion) {
            this.ux.warn(messages.getMessage('apiVersionOverrideWarning', [JSON.stringify(apiVersion.value)]));
        }
        // Assign this.org if the command supports or requires a username.
        if (this.statics.supportsUsername || this.statics.requiresUsername) {
            await this.assignOrg();
        }
        // Assign this.hubOrg if the command supports or requires a devhub username.
        if (this.statics.supportsDevhubUsername || this.statics.requiresDevhubUsername) {
            await this.assignHubOrg();
        }
    }
    // tslint:disable no-reserved-keywords
    // tslint:disable-next-line no-any (matches oclif)
    async catch(err) {
        // Let oclif handle exit signal errors.
        if (err.code === 'EEXIT') {
            throw err;
        }
        await this.initLoggerAndUx();
        // Convert all other errors to SfdxErrors for consistency and set the command name on the error.
        const error = err.setCommandName ? err : core_1.SfdxError.wrap(err);
        error.setCommandName(this.statics.name);
        process.exitCode = process.exitCode || error.exitCode || 1;
        const userDisplayError = Object.assign(this.getJsonResultObject(error.data, error.exitCode), Object.assign({}, error.toObject(), { stack: error.stack, warnings: Array.from(ux_1.UX.warnings) }));
        if (this.isJson) {
            // This should default to true, which will require a major version bump.
            const sendToStdout = kit_1.env.getBoolean('SFDX_JSON_TO_STDOUT');
            if (sendToStdout) {
                this.ux.logJson(userDisplayError);
            }
            else {
                this.ux.errorJson(userDisplayError);
            }
        }
        else {
            this.ux.error(...this.formatError(error));
            if (err.data) {
                this.result.data = err.data;
                this.result.display();
            }
        }
        // Emit an event for the analytics plugin.  The ts-ignore is necessary
        // because TS is strict about the events that can be emitted on process.
        // @ts-ignore
        process.emit('cmdError', err, Object.assign({}, this.flags, this.varargs), this.org || this.hubOrg);
    }
    async finally(err) {
        // Only handle success since we're handling errors in the catch
        if (!err) {
            if (this.isJson) {
                let output = this.getJsonResultObject();
                if (ux_1.UX.warnings.size > 0) {
                    output = Object.assign(output, {
                        warnings: Array.from(ux_1.UX.warnings)
                    });
                }
                this.ux.logJson(output);
            }
            else {
                this.result.display();
            }
        }
    }
    // If this command is deprecated, emit a warning
    warnIfDeprecated() {
        if (this.statics.deprecated) {
            let def;
            if (ts_types_2.has(this.statics.deprecated, 'version')) {
                def = Object.assign({ name: this.statics.name, type: 'command' }, this.statics.deprecated);
            }
            else {
                def = this.statics.deprecated;
            }
            this.ux.warn(ux_1.UX.formatDeprecationWarning(def));
        }
        if (this.statics.flagsConfig) {
            // If any deprecated flags were passed, emit warnings
            for (const flag of Object.keys(this.flags)) {
                const def = this.statics.flagsConfig[flag];
                if (def && def.deprecated) {
                    this.ux.warn(ux_1.UX.formatDeprecationWarning(Object.assign({ name: flag, type: 'flag' }, def.deprecated)));
                }
            }
        }
    }
    getJsonResultObject(result = this.result.data, status = process.exitCode || 0) {
        return { status, result };
    }
    parseVarargs(args = []) {
        const varargs = {};
        const descriptor = this.statics.varargs;
        // If this command requires varargs, throw if none are provided.
        if (!args.length && !ts_types_1.isBoolean(descriptor) && descriptor.required) {
            throw core_1.SfdxError.create('@salesforce/command', 'command', 'VarargsRequired');
        }
        // Validate the format of the varargs
        args.forEach(arg => {
            const split = arg.split('=');
            if (split.length !== 2) {
                throw core_1.SfdxError.create('@salesforce/command', 'command', 'InvalidVarargsFormat', [arg]);
            }
            const [name, value] = split;
            if (varargs[name]) {
                throw core_1.SfdxError.create('@salesforce/command', 'command', 'DuplicateVararg', [name]);
            }
            if (!ts_types_1.isBoolean(descriptor) && descriptor.validator) {
                descriptor.validator(name, value);
            }
            varargs[name] = value || undefined;
        });
        return varargs;
    }
    /**
     * Format errors and actions for human consumption. Adds 'ERROR running <command name>',
     * and outputs all errors in red.  When there are actions, we add 'Try this:' in blue
     * followed by each action in red on its own line.
     * @returns {string[]} Returns decorated messages.
     */
    formatError(error) {
        const colorizedArgs = [];
        // We should remove error.commandName since we should always use the actual command id.
        const commandName = this.id || error.commandName;
        const runningWith = commandName ? ` running ${commandName}` : '';
        colorizedArgs.push(chalk_1.default.bold(`ERROR${runningWith}: `));
        colorizedArgs.push(chalk_1.default.red(error.message));
        // Format any actions.
        if (ts_types_1.get(error, 'actions.length')) {
            colorizedArgs.push(`\n\n${chalk_1.default.blue(chalk_1.default.bold('Try this:'))}`);
            if (error.actions) {
                error.actions.forEach(action => {
                    colorizedArgs.push(`\n${chalk_1.default.red(action)}`);
                });
            }
        }
        if (error.stack && core_1.Global.getEnvironmentMode() === core_1.Mode.DEVELOPMENT) {
            colorizedArgs.push(chalk_1.default.red(`\n*** Internal Diagnostic ***\n\n${error.stack}\n******\n`));
        }
        return colorizedArgs;
    }
    /**
     * Initialize logger and ux for the command
     */
    async initLoggerAndUx() {
        if (!this.logger) {
            this.logger = await core_1.Logger.child(this.statics.name);
        }
        if (!this.ux) {
            this.ux = new ux_1.UX(this.logger, !this.isJson);
        }
        if (this.result && !this.result.ux) {
            this.result.ux = this.ux;
        }
    }
}
// Set to true to add the "targetusername" flag to this command.
SfdxCommand.supportsUsername = false;
// Set to true if this command MUST have a targetusername set, either via
// a flag or by having a default.
SfdxCommand.requiresUsername = false;
// Set to true to add the "targetdevhubusername" flag to this command.
SfdxCommand.supportsDevhubUsername = false;
// Set to true if this command MUST have a targetdevhubusername set, either via
// a flag or by having a default.
SfdxCommand.requiresDevhubUsername = false;
// Set to true if this command MUST be run within a SFDX project.
SfdxCommand.requiresProject = false;
// Use for full control over command output formating and display, or to override
// certain pieces of default display behavior.
SfdxCommand.result = {};
// Use to enable or configure varargs style (key=value) parameters.
SfdxCommand.varargs = false;
exports.SfdxCommand = SfdxCommand;
//# sourceMappingURL=sfdxCommand.js.map