@salesforce/command/lib/sfdxFlags.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
 */
var __rest = (this && this.__rest) || function (s, e) {
    var t = {};
    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
        t[p] = s[p];
    if (s != null && typeof Object.getOwnPropertySymbols === "function")
        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) if (e.indexOf(p[i]) < 0)
            t[p[i]] = s[p[i]];
    return t;
};
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 url_1 = require("url");
core_1.Messages.importMessagesDirectory(__dirname);
const messages = core_1.Messages.loadMessages('@salesforce/command', 'flags');
function merge(kind, flag, describable) {
    if (ts_types_1.has(flag, 'validate') && ts_types_1.hasFunction(flag, 'parse')) {
        const parse = flag.parse;
        flag.parse = (val, ctx) => {
            validateValue(toValidatorFn(flag.validate)(val), val, kind);
            return parse(val, ctx);
        };
    }
    return Object.assign({ kind }, flag, { description: describable.description, longDescription: describable.longDescription });
}
function option(kind, options, parse) {
    return merge(kind, command_1.flags.build(Object.assign(options, { parse }))(), options);
}
// oclif
function buildBoolean(options) {
    return merge('boolean', command_1.flags.boolean(options), options);
}
function buildEnum(options) {
    return Object.assign({ kind: 'enum', type: 'option' }, command_1.flags.enum(options), { options: options.options, description: options.description, longDescription: options.longDescription });
}
function buildHelp(options) {
    const flag = command_1.flags.help(options);
    return merge('help', command_1.flags.help(options), {
        description: ts_types_1.ensure(flag.description)
    });
}
function buildInteger(options) {
    const kind = 'integer';
    return option(kind, options, (val) => {
        const parsed = kit_1.toNumber(val);
        validateValue(Number.isInteger(parsed), val, kind);
        return validateBounds(kind, parsed, options, (t) => t);
    });
}
function buildOption(options) {
    return merge('option', command_1.flags.option(options), options);
}
function buildString(options) {
    return merge('string', command_1.flags.string(options), options);
}
function buildVersion(options) {
    const flag = command_1.flags.version(options);
    return merge('version', flag, {
        description: ts_types_1.ensure(flag.description)
    });
}
function buildArray(options) {
    const kind = 'array';
    return 'map' in options ? buildMappedArray(kind, options) : buildStringArray(kind, options);
}
function buildStringArray(kind, options) {
    const { options: values, validate } = options, rest = __rest(options, ["options", "validate"]);
    const allowed = new Set(values);
    return option(kind, rest, val => {
        const vals = val.split(options.delimiter || ',');
        validateArrayValues(kind, val, vals, options.validate);
        validateArrayOptions(kind, val, vals, allowed);
        return vals;
    });
}
function buildMappedArray(kind, options) {
    const { options: values, validate } = options, rest = __rest(options, ["options", "validate"]);
    const allowed = new Set(values);
    return option(kind, rest, (val) => {
        const vals = val.split(options.delimiter || ',');
        validateArrayValues(kind, val, vals, options.validate);
        const mappedVals = vals.map(options.map);
        validateArrayOptions(kind, val, mappedVals, allowed);
        return mappedVals;
    });
}
function buildDate(options) {
    const kind = 'date';
    return option(kind, options, (val) => {
        const parsed = Date.parse(val);
        validateValue(!isNaN(parsed), val, kind, ` ${messages.getMessage('FormattingMessageDate')}`);
        return new Date(parsed);
    });
}
function buildDatetime(options) {
    const kind = 'datetime';
    return option(kind, options, (val) => {
        const parsed = Date.parse(val);
        validateValue(!isNaN(parsed), val, kind, ` ${messages.getMessage('FormattingMessageDate')}`);
        return new Date(parsed);
    });
}
function buildDirectory(options) {
    return option('directory', options, (val) => {
        return validateValue(core_1.sfdc.validatePathDoesNotContainInvalidChars(val), val, 'directory');
    });
}
function buildEmail(options) {
    return option('email', options, (val) => {
        return validateValue(core_1.sfdc.validateEmail(val), val, 'email');
    });
}
function buildFilepath(options) {
    return option('filepath', options, (val) => {
        return validateValue(core_1.sfdc.validatePathDoesNotContainInvalidChars(val), val, 'filepath');
    });
}
function buildId(options) {
    return option('id', options, (val) => {
        return validateValue(core_1.sfdc.validateSalesforceId(val), val, 'id', ` ${messages.getMessage('FormattingMessageId')}`);
    });
}
function buildMilliseconds(options) {
    const kind = 'milliseconds';
    return option(kind, options, (val) => {
        const parsed = kit_1.toNumber(val);
        validateValue(Number.isInteger(parsed), val, kind);
        return kit_1.Duration.milliseconds(validateBounds(kind, parsed, options, v => (ts_types_1.isNumber(v) ? v : v[kind])));
    });
}
function buildMinutes(options) {
    const kind = 'minutes';
    return option(kind, options, (val) => {
        const parsed = kit_1.toNumber(val);
        validateValue(Number.isInteger(parsed), val, kind);
        return kit_1.Duration.minutes(validateBounds(kind, parsed, options, v => (ts_types_1.isNumber(v) ? v : v[kind])));
    });
}
function buildNumber(options) {
    const kind = 'number';
    return option(kind, options, (val) => {
        const parsed = kit_1.toNumber(val);
        validateValue(isFinite(parsed), val, kind);
        return validateBounds(kind, parsed, options, (t) => t);
    });
}
function buildSeconds(options) {
    const kind = 'seconds';
    return option(kind, options, (val) => {
        const parsed = kit_1.toNumber(val);
        validateValue(Number.isInteger(parsed), val, kind);
        return kit_1.Duration.seconds(validateBounds(kind, parsed, options, v => (ts_types_1.isNumber(v) ? v : v[kind])));
    });
}
function buildUrl(options) {
    return option('url', options, (val) => {
        try {
            return new url_1.URL(val);
        }
        catch (err) {
            const correct = ` ${messages.getMessage('FormattingMessageUrl')}`;
            throw core_1.SfdxError.create('@salesforce/command', 'flags', 'InvalidFlagTypeError', [val, 'url', correct || '']);
        }
    });
}
function buildBuiltin(options = {}) {
    return Object.assign({}, options, { type: 'builtin' });
}
exports.flags = {
    // oclif
    /**
     * A flag type whose presence indicates a `true` boolean value. Produces false when not present.
     */
    boolean: buildBoolean,
    /**
     * A flag type with a fixed enumeration of possible option values. Produces a validated string from the `options` list.
     */
    enum: buildEnum,
    /**
     * A flag type useful for overriding the short `char` trigger for emitting CLI help. Emits help and exits the CLI.
     */
    help: buildHelp,
    /**
     * A flag type that accepts basic integer values. For floats, binary, octal, and hex, see {@link flags.number}.
     * Produces an integer `number`.
     */
    integer: buildInteger,
    /**
     * A flag type for custom string processing. Accepts a `parse` function that converts a `string` value to a type `T`.
     * Produces a type `T`.
     */
    option: buildOption,
    /**
     * A flag type for returning a raw `string` value without further preprocessing. Produces a string.
     */
    string: buildString,
    /**
     * A flag type for emitting CLI version information. Emits the CLI version and exits the CLI.
     */
    version: buildVersion,
    // sfdx
    /**
     * A flag type for a delimited list of strings with the delimiter defaulting to `,`, e.g., "one,two,three". Accepts
     * an optional `delimiter` `string` and/or a custom `map` function for converting parsed `string` values into
     * a type `T`. Produces a parsed (and possibly mapped) array of type `T` where `T` defaults to `string` if no
     * custom `map` function was provided.
     */
    array: buildArray,
    /**
     * A flag type for a valid date, e.g., "01-02-2000" or "01/02/2000 01:02:34". Produces a parsed `Date`.
     */
    date: buildDate,
    /**
     * A flag type for a valid datetime, e.g., "01-02-2000" or "01/02/2000 01:02:34". Produces a parsed `Date`.
     */
    datetime: buildDatetime,
    /**
     * A flag type for valid directory paths. Produces a validated string.
     *
     * **See** [@salesforce/core#sfdc.validatePathDoesNotContainInvalidChars](https://forcedotcom.github.io/sfdx-core/globals.html#sfdc), e.g. "this/is/my/path".
     */
    directory: buildDirectory,
    /**
     * A flag type for valid email addresses. Produces a validated string.
     *
     * **See** [@salesforce/core#sfdc.validateEmail](https://forcedotcom.github.io/sfdx-core/globals.html#sfdc), e.g., "me@my.org".
     */
    email: buildEmail,
    /**
     * A flag type for valid file paths. Produces a validated string.
     *
     * **See** [@salesforce/core#sfdc.validatePathDoesNotContainInvalidChars](https://forcedotcom.github.io/sfdx-core/globals.html#sfdc), e.g. "this/is/my/path".
     */
    filepath: buildFilepath,
    /**
     * A flag type for valid Salesforce IDs. Produces a validated string.
     *
     * **See** [@salesforce/core#sfdc.validateSalesforceId](https://forcedotcom.github.io/sfdx-core/globals.html#sfdc), e.g., "00Dxxxxxxxxxxxx".
     */
    id: buildId,
    /**
     * A flag type for a valid `Duration` in milliseconds, e.g., "5000".
     */
    milliseconds: buildMilliseconds,
    /**
     * A flag type for a valid `Duration` in minutes, e.g., "2".
     */
    minutes: buildMinutes,
    /**
     * A flag type for valid integer or floating point number, e.g., "42". Additionally supports binary, octal, and hex
     * notation. Produces a parsed `number`.
     */
    number: buildNumber,
    /**
     * A flag type for a valid `Duration` in seconds, e.g., "5".
     */
    seconds: buildSeconds,
    /**
     * A flag type for a valid url, e.g., "http://www.salesforce.com". Produces a parsed `URL` instance.
     */
    url: buildUrl,
    // builtins
    /**
     * Declares a flag definition to be one of the builtin types, for automatic configuration.
     */
    builtin: buildBuiltin
};
exports.requiredBuiltinFlags = {
    json() {
        return exports.flags.boolean({
            description: messages.getMessage('jsonFlagDescription'),
            longDescription: messages.getMessage('jsonFlagLongDescription')
        });
    },
    loglevel() {
        return exports.flags.enum({
            options: core_1.Logger.LEVEL_NAMES.concat(core_1.Logger.LEVEL_NAMES.map(l => l.toUpperCase())),
            default: core_1.LoggerLevel[core_1.Logger.DEFAULT_LEVEL].toLowerCase(),
            required: false,
            description: messages.getMessage('loglevelFlagDescription'),
            longDescription: messages.getMessage('loglevelFlagLongDescription'),
            parse: (val) => {
                val = val.toLowerCase();
                if (core_1.Logger.LEVEL_NAMES.includes(val))
                    return val;
                throw core_1.SfdxError.create('@salesforce/command', 'flags', 'InvalidLoggerLevelError', [val]);
            }
        });
    }
};
exports.optionalBuiltinFlags = {
    apiversion(opts) {
        return Object.assign(opts || {}, exports.flags.string({
            description: resolve(opts, 'description', messages.getMessage('apiversionFlagDescription')),
            longDescription: resolve(opts, 'longDescription', messages.getMessage('apiversionFlagLongDescription')),
            parse: (val) => {
                if (core_1.sfdc.validateApiVersion(val))
                    return val;
                throw core_1.SfdxError.create('@salesforce/command', 'flags', 'InvalidApiVersionError', [val]);
            }
        }));
    },
    concise(opts) {
        return Object.assign(opts || {}, exports.flags.boolean({
            description: resolve(opts, 'description', messages.getMessage('conciseFlagDescription')),
            longDescription: resolve(opts, 'longDescription', messages.getMessage('conciseFlagLongDescription'))
        }));
    },
    quiet(opts) {
        return Object.assign(opts || {}, exports.flags.boolean({
            description: resolve(opts, 'description', messages.getMessage('quietFlagDescription')),
            longDescription: resolve(opts, 'longDescription', messages.getMessage('quietFlagLongDescription'))
        }));
    },
    targetdevhubusername(opts) {
        return Object.assign(opts || {}, exports.flags.string({
            char: 'v',
            description: resolve(opts, 'description', messages.getMessage('targetdevhubusernameFlagDescription')),
            longDescription: resolve(opts, 'longDescription', messages.getMessage('targetdevhubusernameFlagLongDescription'))
        }));
    },
    targetusername(opts) {
        return Object.assign(opts || {}, exports.flags.string({
            char: 'u',
            description: resolve(opts, 'description', messages.getMessage('targetusernameFlagDescription')),
            longDescription: resolve(opts, 'longDescription', messages.getMessage('targetusernameFlagLongDescription'))
        }));
    },
    verbose(opts) {
        return Object.assign(opts || {}, exports.flags.boolean({
            description: resolve(opts, 'description', messages.getMessage('verboseFlagDescription')),
            longDescription: resolve(opts, 'longDescription', messages.getMessage('verboseFlagLongDescription'))
        }));
    }
};
function resolve(opts, key, def) {
    return ts_types_1.hasString(opts, key) ? opts[key] : def;
}
function validateValue(isValid, value, kind, correct) {
    if (isValid)
        return value;
    throw core_1.SfdxError.create('@salesforce/command', 'flags', 'InvalidFlagTypeError', [value, kind, correct || '']);
}
function validateBounds(kind, value, bounds, extract) {
    if (bounds.min != null && value < extract(bounds.min)) {
        throw new core_1.SfdxError(`Expected ${kind} greater than or equal to ${extract(bounds.min)} but received ${value}`, 'InvalidFlagNumericBoundsError');
    }
    if (bounds.max != null && value > extract(bounds.max)) {
        throw new core_1.SfdxError(`Expected ${kind} less than or equal to ${extract(bounds.max)} but received ${value}`, 'InvalidFlagNumericBoundsError');
    }
    return value;
}
function toValidatorFn(validator) {
    return (val) => {
        if (ts_types_1.isString(validator))
            return new RegExp(validator).test(val);
        if (ts_types_1.isInstance(validator, RegExp))
            return validator.test(val);
        if (ts_types_1.isFunction(validator))
            return !!validator(val);
        return true;
    };
}
function validateArrayValues(kind, raw, vals, validator) {
    validateValue(vals.every(toValidatorFn(validator)), raw, kind, ` ${messages.getMessage('FormattingMessageArrayValue')}`);
}
function validateArrayOptions(kind, raw, vals, allowed) {
    validateValue(allowed.size === 0 || vals.every(t => allowed.has(t)), raw, kind, ` ${messages.getMessage('FormattingMessageArrayOption', [Array.from(allowed).toString()])}`);
}
/**
 * Validate the custom flag configuration. This includes:
 *
 * 1. The flag name is in all lowercase.
 * 2. A string description is provided.
 * 3. If a char attribute is provided, it is one alphabetical character in length.
 * 4. If a long description is provided, it is a string.
 *
 * @param {SfdxFlagDefinition} flag The flag configuration.
 * @param {string} key The flag name.
 * @throws SfdxError If the criteria is not meet.
 */
function validateCustomFlag(key, flag) {
    if (!/^(?!(?:[-]|[0-9]*$))[a-z0-9-]+$/.test(key)) {
        throw core_1.SfdxError.create('@salesforce/command', 'flags', 'InvalidFlagName', [key]);
    }
    if (flag.char && (flag.char.length !== 1 || !/[a-zA-Z]/.test(flag.char))) {
        throw core_1.SfdxError.create('@salesforce/command', 'flags', 'InvalidFlagChar', [key]);
    }
    if (!flag.description || !ts_types_1.isString(flag.description)) {
        throw core_1.SfdxError.create('@salesforce/command', 'flags', 'MissingOrInvalidFlagDescription', [key]);
    }
    if (flag.longDescription !== undefined && !ts_types_1.isString(flag.longDescription)) {
        throw core_1.SfdxError.create('@salesforce/command', 'flags', 'InvalidLongDescriptionFormat', [key]);
    }
    return flag;
}
/**
 * Builds flags for a command given a configuration object.  Supports the following use cases:
 *     1. Enabling common SFDX flags. E.g., { verbose: true }
 *     4. Defining typed flags. E.g., { myFlag: Flags.array({ char: '-a' }) }
 *     4. Defining custom typed flags. E.g., { myFlag: Flags.custom({ parse: (val) => parseInt(val, 10) }) }
 *
 * @param {FlagsConfig} flagsConfig The configuration object for a flag.  @see {@link FlagsConfig}
 * @param options Extra configuration options.
 * @returns {flags.Output} The flags for the command.
 * @ignore
 */
function buildSfdxFlags(flagsConfig, options
// tslint:disable-next-line:no-any matches oclif
) {
    const output = {};
    // Required flag options for all SFDX commands
    output.json = exports.requiredBuiltinFlags.json();
    output.loglevel = exports.requiredBuiltinFlags.loglevel();
    if (options.targetdevhubusername)
        output.targetdevhubusername = exports.optionalBuiltinFlags.targetdevhubusername();
    if (options.targetusername)
        output.targetusername = exports.optionalBuiltinFlags.targetusername();
    if (options.targetdevhubusername || options.targetusername)
        output.apiversion = exports.optionalBuiltinFlags.apiversion();
    // Process configuration for custom and builtin flags
    ts_types_1.definiteEntriesOf(flagsConfig).forEach(([key, flag]) => {
        if (isBuiltin(flag)) {
            if (!ts_types_1.isKeyOf(exports.optionalBuiltinFlags, key)) {
                throw core_1.SfdxError.create('@salesforce/command', 'flags', 'UnknownBuiltinFlagType', [key]);
            }
            output[key] = exports.optionalBuiltinFlags[key](flag);
        }
        else {
            output[key] = validateCustomFlag(key, flag);
        }
    });
    return output;
}
exports.buildSfdxFlags = buildSfdxFlags;
function isBuiltin(flag) {
    return ts_types_1.hasString(flag, 'type') && flag.type === 'builtin';
}
//# sourceMappingURL=sfdxFlags.js.map