mcdev 3.1.1 → 4.0.0

package/lib/util/util.js

@@ -1,32 +1,12 @@
 'use strict';
 
-/**
- * @ignore @typedef {import('sfmc-fuelsdk-node')} ET_Client
- *
- * @typedef {Object} BuObject
- * @property {String} clientId installed package client id
- * @property {String} clientSecret installed package client secret
- * @property {String} tenant subdomain part of Authentication Base Uri
- * @property {String} [eid] Enterprise ID = MID of the parent BU
- * @property {String} [mid] MID of the BU to work with
- * @property {String} [businessUnit] name of the BU to interact with
- * @property {String} [credential] name of the credential to interact with
- */
-/**
- * @typedef {Object.<string,string>} TemplateMap
- */
-
-/** @type ET_Client */
-const ET_Client = require('sfmc-fuelsdk-node');
-const fs = require('fs-extra'); // ! do not switch to util/file.js to avoid circular dependency
+const TYPE = require('../../types/mcdev.d');
 const MetadataDefinitions = require('./../MetadataTypeDefinitions');
 const packageJsonMcdev = require('../../package.json');
-const path = require('path');
+const process = require('node:process');
 const toposort = require('toposort');
 const winston = require('winston');
-const inquirer = require('inquirer');
-const child_process = require('child_process');
-const semver = require('semver');
+const child_process = require('node:child_process');
 
 /**
  * Util that contains logger and simple util methods
@@ -37,119 +17,165 @@ const Util = {
     configFileName: '.mcdevrc.json',
     parentBuName: '_ParentBU_',
     standardizedSplitChar: '/',
-    expectedAuthScope: [
-        'accounts_read',
-        'accounts_write',
-        'approvals_read',
-        'approvals_write',
-        'audiences_read',
-        'audiences_write',
-        'automations_execute',
-        'automations_read',
-        'automations_write',
-        'calendar_read',
-        'calendar_write',
-        'campaign_read',
-        'campaign_write',
-        'data_extensions_read',
-        'data_extensions_write',
-        'documents_and_images_read',
-        'documents_and_images_write',
-        'email_read',
-        'email_send',
-        'email_write',
-        'event_notification_callback_create',
-        'event_notification_callback_delete',
-        'event_notification_callback_read',
-        'event_notification_callback_update',
-        'event_notification_subscription_create',
-        'event_notification_subscription_delete',
-        'event_notification_subscription_read',
-        'event_notification_subscription_update',
-        'file_locations_read',
-        'file_locations_write',
-        'journeys_execute',
-        'journeys_read',
-        'journeys_write',
-        'key_manage_revoke',
-        'key_manage_rotate',
-        'key_manage_view',
-        'list_and_subscribers_read',
-        'list_and_subscribers_write',
-        'marketing_cloud_connect_read',
-        'marketing_cloud_connect_send',
-        'marketing_cloud_connect_write',
-        'offline',
-        'ott_channels_read',
-        'ott_channels_write',
-        'ott_chat_messaging_read',
-        'ott_chat_messaging_send',
-        'push_read',
-        'push_send',
-        'push_write',
-        'saved_content_read',
-        'saved_content_write',
-        'sms_read',
-        'sms_send',
-        'sms_write',
-        'social_post',
-        'social_publish',
-        'social_read',
-        'social_write',
-        'tags_read',
-        'tags_write',
-        'tracking_events_read',
-        'tracking_events_write',
-        'users_read',
-        'users_write',
-        'web_publish',
-        'web_read',
-        'web_write',
-        'webhooks_read',
-        'webhooks_write',
-        'workflows_read',
-        'workflows_write',
-    ],
+    /** @type {TYPE.skipInteraction} */
+    skipInteraction: false,
+    packageJsonMcdev: packageJsonMcdev,
+
+    /**
+     * helper that allows filtering an object by its keys
+     *
+     * @param {Object.<string,*>} originalObj object that you want to filter
+     * @param {string[]} [whitelistArr] positive filter. if not provided, returns originalObj without filter
+     * @returns {Object.<string,*>} filtered object that only contains keys you provided
+     */
+    filterObjByKeys(originalObj, whitelistArr) {
+        if (!whitelistArr || !Array.isArray(whitelistArr)) {
+            return originalObj;
+        }
+        return Object.keys(originalObj)
+            .filter((key) => whitelistArr.includes(key))
+            .reduce((obj, key) => {
+                obj[key] = originalObj[key];
+                return obj;
+            }, {});
+    },
+    /**
+     * extended Array.includes method that allows check if an array-element starts with a certain string
+     *
+     * @param {string[]} arr your array of strigns
+     * @param {string} search the string you are looking for
+     * @returns {boolean} found / not found
+     */
+    includesStartsWith(arr, search) {
+        return this.includesStartsWithIndex(arr, search) >= 0;
+    },
+    /**
+     * extended Array.includes method that allows check if an array-element starts with a certain string
+     *
+     * @param {string[]} arr your array of strigns
+     * @param {string} search the string you are looking for
+     * @returns {number} array index 0..n or -1 of not found
+     */
+    includesStartsWithIndex(arr, search) {
+        return Array.isArray(arr) ? arr.findIndex((el) => el.startsWith(search)) : -1;
+    },
+    /**
+     * check if a market name exists in current mcdev config
+     *
+     * @param {string} market market localizations
+     * @param {TYPE.Mcdevrc} properties local mcdev config
+     * @returns {boolean} found market or not
+     */
+    checkMarket(market, properties) {
+        if (properties.markets[market]) {
+            return true;
+        } else {
+            Util.logger.error(`Could not find the market '${market}' in your configuration file.`);
+            const marketArr = Object.values(properties.markets);
+
+            if (marketArr.length) {
+                Util.logger.info('Available markets are: ' + marketArr.join(', '));
+            }
+            return false;
+        }
+    },
+    /**
+     * ensure provided MarketList exists and it's content including markets and BUs checks out
+     *
+     * @param {string} mlName name of marketList
+     * @param {TYPE.Mcdevrc} properties General configuration to be used in retrieve
+     * @returns {void} throws errors if problems were found
+     */
+    verifyMarketList(mlName, properties) {
+        if (!properties.marketList[mlName]) {
+            // ML does not exist
+            throw new Error(`Market List ${mlName} is not defined`);
+        } else {
+            // ML exists, check if it is properly set up
+
+            // check if BUs in marketList are valid
+            let buCounter = 0;
+            for (const businessUnit in properties.marketList[mlName]) {
+                if (businessUnit !== 'description') {
+                    buCounter++;
+                    const [cred, bu] = businessUnit ? businessUnit.split('/') : [null, null];
+                    if (
+                        !properties.credentials[cred] ||
+                        !properties.credentials[cred].businessUnits[bu]
+                    ) {
+                        throw new Error(`'${businessUnit}' in Market ${mlName} is not defined.`);
+                    }
+                    // check if markets are valid
+                    let marketArr = properties.marketList[mlName][businessUnit];
+                    if ('string' === typeof marketArr) {
+                        marketArr = [marketArr];
+                    }
+                    for (const market of marketArr) {
+                        if (!properties.markets[market]) {
+                            throw new Error(`Market '${market}' is not defined.`);
+                        } else {
+                            // * markets can be empty or include variables. Nothing we can test here
+                        }
+                    }
+                }
+            }
+            if (!buCounter) {
+                throw new Error(`No BUs defined in marketList ${mlName}`);
+            }
+        }
+    },
+    /**
+     * used to ensure the program tells surrounding software that an unrecoverable error occured
+     *
+     * @returns {void}
+     */
+    signalFatalError() {
+        process.exitCode = 1;
+    },
     /**
      * SFMC accepts multiple true values for Boolean attributes for which we are checking here
+     *
      * @param {*} attrValue value
      * @returns {boolean} attribute value == true ? true : false
      */
     isTrue(attrValue) {
-        return ['true', 'TRUE', 'True', '1', 1, 'Y'].includes(attrValue);
+        return ['true', 'TRUE', 'True', '1', 1, 'Y', true].includes(attrValue);
     },
     /**
      * SFMC accepts multiple false values for Boolean attributes for which we are checking here
+     *
      * @param {*} attrValue value
      * @returns {boolean} attribute value == false ? true : false
      */
     isFalse(attrValue) {
-        return ['false', 'FALSE', 'False', '0', 0, 'N'].includes(attrValue);
+        return ['false', 'FALSE', 'False', '0', 0, 'N', false].includes(attrValue);
     },
-
     /**
-     * defines how the properties.json should look like
-     * used for creating a template and for checking if variables are set
+     * helper for retrieve, retrieveAsTemplate and deploy
      *
-     * @returns {object} default properties
+     * @param {TYPE.SupportedMetadataTypes} selectedType type or type-subtype
+     * @returns {boolean} type ok or not
      */
-    getDefaultProperties: function () {
-        const configFileName = path.resolve(__dirname, this.boilerplateDirectory, 'config.json');
-        if (!fs.existsSync(configFileName)) {
-            this.logger.debug(`Default config file file not found in ${configFileName}`);
-            return false;
+    _isValidType(selectedType) {
+        const [type, subType] = selectedType ? selectedType.split('-') : [];
+        if (type && !MetadataDefinitions[type]) {
+            Util.logger.error(`:: '${type}' is not a valid metadata type`);
+            return;
+        } else if (
+            type &&
+            subType &&
+            (!MetadataDefinitions[type] || !MetadataDefinitions[type].subTypes.includes(subType))
+        ) {
+            Util.logger.error(`:: '${selectedType}' is not a valid metadata type`);
+            return;
         }
-        const defaultProperties = fs.readJsonSync(configFileName);
-        // set default name for parent BU
-        defaultProperties.credentials.default.businessUnits[this.parentBuName] = '000000000';
-        // set default retrieve values
-        defaultProperties.metaDataTypes.retrieve = this.getRetrieveTypeChoices();
-
-        return defaultProperties;
+        return true;
     },
+
     /**
      * helper for getDefaultProperties()
-     * @returns {string[]} type choices
+     *
+     * @returns {TYPE.SupportedMetadataTypes[]} type choices
      */
     getRetrieveTypeChoices() {
         const typeChoices = [];
@@ -177,234 +203,23 @@ const Util = {
 
         return typeChoices;
     },
-    /**
-     * check if the config file is correctly formatted and has values
-     *
-     * @param {object} properties javascript object in .mcdevrc.json
-     * @param {boolean} [silent] set to true for internal use w/o cli output
-     * @returns {boolean|String[]} file structure ok OR list of fields to be fixed
-     */
-    checkProperties: function (properties, silent) {
-        if (!fs.existsSync(Util.configFileName) || !properties) {
-            Util.logger.error(`\nCould not find ${Util.configFileName} in ${process.cwd()}.`);
-            Util.logger.error(`Run 'mcdev init' to initialize your project.\n`);
-            return false;
-        }
-        if (!fs.existsSync(Util.authFileName) || !properties) {
-            Util.logger.error(`\nCould not find ${Util.authFileName} in ${process.cwd()}.`);
-            Util.logger.error(`Run 'mcdev init' to initialize your project.\n`);
-            return false;
-        }
-
-        // check if user is running older mcdev version than whats saved to the config
-        if (properties.version && semver.gt(properties.version, packageJsonMcdev.version)) {
-            // dont run this for Catalyst to MC DevTools migration
-            Util.logger.error(
-                `Your Accenture SFMC DevTools version ${packageJsonMcdev.version} is lower than your project's config version ${properties.version}`
-            );
-            const questions = [
-                {
-                    type: 'confirm',
-                    name: 'runUpgradeNow',
-                    message: `Do you want to run 'npm update -g mcdev' now? This may take a few minutes.`,
-                    default: true,
-                },
-            ];
-            inquirer.prompt(questions).then((responses) => {
-                if (responses.runUpgradeNow) {
-                    // use _execSync here to avoid a circular dependency
-                    this.execSync('npm', ['update', '-g', 'mcdev']);
-                }
-            });
-            return false;
-        }
-
-        // check config properties
-        const defaultProps = this.getDefaultProperties();
-        const errorMsgs = [];
-        const solutionSet = new Set();
-        const missingFields = [];
-        for (const key in defaultProps) {
-            if (Object.prototype.hasOwnProperty.call(defaultProps, key)) {
-                if (!Object.prototype.hasOwnProperty.call(properties, key)) {
-                    errorMsgs.push(`${key}{} missing`);
-                    solutionSet.add(
-                        `Run 'mcdev upgrade' to fix missing or changed configuration options`
-                    );
-                    missingFields.push(key);
-                } else {
-                    if (!silent && key === 'credentials') {
-                        if (!Object.keys(properties.credentials)) {
-                            errorMsgs.push(`no Credential defined`);
-                        } else {
-                            for (const cred in properties.credentials) {
-                                if (cred.includes('/') || cred.includes('\\')) {
-                                    errorMsgs.push(
-                                        `Credential names may not includes slashes: ${cred}`
-                                    );
-                                    solutionSet.add('Apply manual fix in your config.');
-                                }
-                                if (
-                                    !properties.credentials[cred].clientId ||
-                                    properties.credentials[cred].clientId === '--- update me ---'
-                                ) {
-                                    errorMsgs.push(`invalid ClientId on ${cred}`);
-                                    solutionSet.add(`Run 'mcdev init ${cred}'`);
-                                }
-                                if (
-                                    !properties.credentials[cred].clientSecret ||
-                                    properties.credentials[cred].clientSecret ===
-                                        '--- update me ---'
-                                ) {
-                                    errorMsgs.push(`invalid ClientSecret on ${cred}`);
-                                    solutionSet.add(`Run 'mcdev init ${cred}'`);
-                                }
-                                if (
-                                    !properties.credentials[cred].tenant ||
-                                    properties.credentials[cred].tenant === '--- update me ---'
-                                ) {
-                                    errorMsgs.push(`invalid tenant on ${cred}`);
-                                    solutionSet.add(`Run 'mcdev init ${cred}'`);
-                                }
-                                if (
-                                    !properties.credentials[cred].eid ||
-                                    properties.credentials[cred].eid === '000000000'
-                                ) {
-                                    errorMsgs.push(`invalid eid on ${cred}`);
-                                    solutionSet.add(`Run 'mcdev init ${cred}'`);
-                                }
-                                let i = 0;
-                                for (const buName in properties.credentials[cred].businessUnits) {
-                                    if (buName.includes('/') || buName.includes('\\')) {
-                                        errorMsgs.push(
-                                            `Business Unit names may not includes slashes: ${cred}: ${buName}`
-                                        );
-                                        solutionSet.add(`Run 'mcdev reloadBUs ${cred}'`);
-                                    }
-                                    if (
-                                        Object.prototype.hasOwnProperty.call(
-                                            properties.credentials[cred].businessUnits,
-                                            buName
-                                        ) &&
-                                        properties.credentials[cred].businessUnits[buName] !==
-                                            '000000000'
-                                    ) {
-                                        i++;
-                                    }
-                                }
-                                if (!i) {
-                                    errorMsgs.push(`no Business Units defined`);
-                                    solutionSet.add(`Run 'mcdev reloadBUs ${cred}'`);
-                                }
-                            }
-                        }
-                    } else if (['directories', 'metaDataTypes', 'options'].includes(key)) {
-                        for (const subkey in defaultProps[key]) {
-                            if (
-                                Object.prototype.hasOwnProperty.call(defaultProps[key], subkey) &&
-                                !Object.prototype.hasOwnProperty.call(properties[key], subkey)
-                            ) {
-                                errorMsgs.push(
-                                    `${key}.${subkey} missing. Default value (${
-                                        Array.isArray(defaultProps[key][subkey])
-                                            ? 'Array'
-                                            : typeof defaultProps[key][subkey]
-                                    }): ${defaultProps[key][subkey]}`
-                                );
-                                solutionSet.add(
-                                    `Run 'mcdev upgrade' to fix missing or changed configuration options`
-                                );
-                                missingFields.push(`${key}.${subkey}`);
-                            } else if (subkey === 'deployment') {
-                                for (const dkey in defaultProps[key][subkey]) {
-                                    if (
-                                        Object.prototype.hasOwnProperty.call(
-                                            defaultProps[key][subkey],
-                                            dkey
-                                        ) &&
-                                        !Object.prototype.hasOwnProperty.call(
-                                            properties[key][subkey],
-                                            dkey
-                                        )
-                                    ) {
-                                        errorMsgs.push(
-                                            `${key}.${subkey} missing. Default value (${
-                                                Array.isArray(defaultProps[key][subkey][dkey])
-                                                    ? 'Array'
-                                                    : typeof defaultProps[key][subkey][dkey]
-                                            }): ${defaultProps[key][subkey][dkey]}`
-                                        );
-                                        solutionSet.add(
-                                            `Run 'mcdev upgrade' to fix missing or changed configuration options`
-                                        );
-                                        missingFields.push(`${key}.${subkey}.${dkey}`);
-                                    }
-                                }
-                            }
-                        }
-                    }
-                }
-            }
-        }
-        // check if project config version is outdated compared to user's mcdev version
-        if (!properties.version || semver.gt(packageJsonMcdev.version, properties.version)) {
-            errorMsgs.push(
-                `Your project's config version ${properties.version} is lower than your Accenture SFMC DevTools version ${packageJsonMcdev.version}`
-            );
-            solutionSet.add(`Run 'mcdev upgrade' to ensure optimal performance`);
-            missingFields.push('version');
-        }
-        if (silent) {
-            return missingFields;
-        } else {
-            if (errorMsgs.length) {
-                const errorMsgOutput = [
-                    `Found problems in your ./${Util.configFileName} that you need to fix first:`,
-                ];
-                for (const msg of errorMsgs) {
-                    errorMsgOutput.push(' - ' + msg);
-                }
-                Util.logger.error(errorMsgOutput.join('\n'));
-                Util.logger.info(
-                    [
-                        'Here is what you can do to fix these issues:',
-                        ...Array.from(solutionSet),
-                    ].join('\n- ')
-                );
-                const questions = [
-                    {
-                        type: 'confirm',
-                        name: 'runUpgradeNow',
-                        message: `Do you want to run 'mcdev upgrade' now?`,
-                        default: true,
-                    },
-                ];
-                inquirer.prompt(questions).then((responses) => {
-                    if (responses.runUpgradeNow) {
-                        // use _execSync here to avoid a circular dependency
-                        this.execSync('mcdev', ['upgrade']);
-                    }
-                });
 
-                return false;
-            } else {
-                return true;
-            }
-        }
-    },
     loggerTransports: null,
     /**
      * Logger that creates timestamped log file in 'logs/' directory
+     *
+     * @type {TYPE.Logger}
      */
     logger: null,
     restartLogger: startLogger,
     /**
      * Logger helper for Metadata functions
-     * @param {String} level of log (error, info, warn)
-     * @param {String} type of metadata being referenced
-     * @param {String} method name which log was called from
+     *
+     * @param {string} level of log (error, info, warn)
+     * @param {string} type of metadata being referenced
+     * @param {string} method name which log was called from
      * @param {*} payload generic object which details the error
-     * @param {String} [source] key/id of metadata which relates to error
+     * @param {string} [source] key/id of metadata which relates to error
      * @returns {void}
      */
     metadataLogger: function (level, type, method, payload, source) {
@@ -426,9 +241,10 @@ const Util = {
     /**
      * replaces values in a JSON object string, based on a series of
      * key-value pairs (obj)
-     * @param {String|Object} str JSON object or its stringified version, which has values to be replaced
-     * @param {TemplateMap} obj key value object which contains keys to be replaced and values to be replaced with
-     * @returns {String|Object} replaced version of str
+     *
+     * @param {string | object} str JSON object or its stringified version, which has values to be replaced
+     * @param {TYPE.TemplateMap} obj key value object which contains keys to be replaced and values to be replaced with
+     * @returns {string | object} replaced version of str
      */
     replaceByObject: function (str, obj) {
         let convertType = false;
@@ -445,11 +261,9 @@ const Util = {
             }
         }
 
-        sortable.sort(function (a, b) {
-            return b[1].length - a[1].length;
-        });
+        sortable.sort((a, b) => b[1].length - a[1].length);
         for (const pair of sortable) {
-            const escVal = pair[1].replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&');
+            const escVal = pair[1].toString().replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&');
             const regString = new RegExp(escVal, 'g');
             str = str.replace(regString, '{{{' + pair[0] + '}}}');
         }
@@ -460,9 +274,10 @@ const Util = {
     },
     /**
      * get key of an object based on the first matching value
-     * @param {Object} objs object of objects to be searched
-     * @param {String} val value to be searched for
-     * @returns {String} key
+     *
+     * @param {object} objs object of objects to be searched
+     * @param {string} val value to be searched for
+     * @returns {string} key
      */
     inverseGet: function (objs, val) {
         for (const obj in objs) {
@@ -475,8 +290,9 @@ const Util = {
 
     /**
      * Returns Order in which metadata needs to be retrieved/deployed
-     * @param {String[]} metadataTypes which should be retrieved/deployed
-     * @returns {String[]} retrieve/deploy order as array
+     *
+     * @param {string[]} metadataTypes which should be retrieved/deployed
+     * @returns {string[]} retrieve/deploy order as array
      */
     getMetadataHierachy(metadataTypes) {
         const dependencies = [];
@@ -504,238 +320,37 @@ const Util = {
             }
         }
         // remove subtypes if main type is in the list
-        Object.keys(subTypeDeps)
+        for (const type of Object.keys(subTypeDeps)
             // only look at subtype deps that are also supposed to be retrieved fully
-            .filter((type) => metadataTypes.includes(type))
-            // Rewrite the subtype dependecies to main types.
-            .forEach((type) => {
-                // convert set into array to walk its elements
-                [...subTypeDeps[type]].forEach((subType) => {
-                    dependencies.forEach((item) => {
-                        if (item[0] === subType) {
-                            // if subtype recognized, replace with main type
-                            item[0] = type;
-                        }
-                    });
-                });
-            });
-
-        // sort list & remove the undefined dependencies
-        return toposort(dependencies).filter((a) => !!a);
-    },
-    /**
-     * signs in with SFMC
-     *
-     * @param {BuObject} buObject properties for auth
-     * @returns {Promise<ET_Client>} auth object
-     */
-    async getETClient(buObject) {
-        /** @type ET_Client */
-        const myClient = new ET_Client(buObject.clientId, buObject.clientSecret, null, {
-            authOptions: {
-                authVersion: 2,
-                accountId: buObject.mid,
-            },
-            globalReqOptions: {},
-            authOrigin: 'https://' + buObject.tenant + '.auth.marketingcloudapis.com',
-            origin: null,
-            soapOrigin: null,
-        });
-        try {
-            // check credentials to allow clear log output and stop execution
-            const test = await myClient.FuelAuthClient.getAccessToken();
-            if (test.error) {
-                throw new Error(test.error_description);
-            } else if (test.scope) {
-                // find missing rights
-                const currentScope = test.scope.split(' ');
-                const missingAccess = Util.expectedAuthScope.filter(
-                    (element) => !currentScope.includes(element)
-                );
-                const excessAccess = currentScope.filter(
-                    (element) => !Util.expectedAuthScope.includes(element)
-                );
-                if (excessAccess.length) {
-                    Util.logger.debug('Extra access found:' + excessAccess.join(', '));
-                }
-                if (missingAccess.length) {
-                    Util.logger.warn(
-                        'Installed package has insufficient access. You might encounter malfunctions!'
-                    );
-                    Util.logger.warn('Missing scope: ' + missingAccess.join(', '));
-                }
-            }
-        } catch (ex) {
-            throw new Error(ex.message);
-        }
-        return myClient;
-    },
-
-    /**
-     * standardized method for getting data from cache.
-     *
-     * @param {Object} cache data retrieved from sfmc instance
-     * @param {String} metadataType metadata type ie. query
-     * @param {String} searchValue unique identifier of metadata being looked for
-     * @param {String} searchField field name (key in object) which contains the unique identifer
-     * @param {String} returnField field which should be returned
-     * @returns {String} unique user definable metadata key (usually external/customer key)
-     */
-    getFromCache(cache, metadataType, searchValue, searchField, returnField) {
-        for (const key in cache[metadataType]) {
-            if (Util.resolveObjPath(searchField, cache[metadataType][key]) == searchValue) {
-                try {
-                    if (Util.resolveObjPath(returnField, cache[metadataType][key])) {
-                        return Util.resolveObjPath(returnField, cache[metadataType][key]);
-                    } else {
-                        throw new Error();
+            .filter((type) => metadataTypes.includes(type))) {
+            // convert set into array to walk its elements
+            for (const subType of subTypeDeps[type]) {
+                for (const item of dependencies) {
+                    if (item[0] === subType) {
+                        // if subtype recognized, replace with main type
+                        item[0] = type;
                     }
-                } catch (ex) {
-                    throw new Error(
-                        `${metadataType} with ${searchField} '${searchValue}' does not have field '${returnField}'`
-                    );
                 }
             }
         }
-        throw new Error(
-            `Missing one or more dependent metadata. ${metadataType} with ${searchField}='${searchValue}' was not found on your BU`
-        );
+
+        // sort list & remove the undefined dependencies
+        return toposort(dependencies).filter((a) => !!a);
     },
+
     /**
      * let's you dynamically walk down an object and get a value
-     * @param {String} path 'fieldA.fieldB.fieldC'
-     * @param {Object} obj some parent object
+     *
+     * @param {string} path 'fieldA.fieldB.fieldC'
+     * @param {object} obj some parent object
      * @returns {any} value of obj.path
      */
     resolveObjPath(path, obj) {
-        return path.split('.').reduce(function (prev, curr) {
-            return prev ? prev[curr] : null;
-        }, obj);
-    },
-    /**
-     * standardized method for getting data from cache - adapted for special case of lists
-     * ! keeping this in util/util.js rather than in metadataTypes/List.js to avoid potential circular dependencies
-     *
-     * @param {Object} cache data retrieved from sfmc instance
-     * @param {String} listPathName folderPath/ListName combo of list
-     * @param {String} returnField ObjectID or ID
-     * @returns {String} unique ObjectId of list
-     */
-    getListObjectIdFromCache(cache, listPathName, returnField) {
-        let folderPath = listPathName.split('/');
-        const listName = folderPath.pop();
-        folderPath = folderPath.join('/');
-        for (const key in cache['list']) {
-            if (
-                cache['list'][key].ListName === listName &&
-                cache['list'][key].r__folder_Path === folderPath
-            ) {
-                try {
-                    if (cache['list'][key][returnField]) {
-                        return cache['list'][key][returnField];
-                    } else {
-                        throw new Error();
-                    }
-                } catch (ex) {
-                    throw new Error(
-                        `${'list'} with ListName='${listName}' and r__folder_Path='${folderPath}' does not have field '${returnField}'`
-                    );
-                }
-            }
-        }
-        throw new Error(
-            `Missing one or more dependent metadata. list with ListName='${listName}' and r__folder_Path='${folderPath}' was not found on your BU`
-        );
-    },
-
-    /**
-     * standardized method for getting data from cache - adapted for special case of lists
-     * ! keeping this in util/util.js rather than in metadataTypes/List.js to avoid potential circular dependencies
-     *
-     * @param {Object} cache data retrieved from sfmc instance
-     * @param {String} searchValue unique identifier of metadata being looked for
-     * @param {String} searchField ObjectID or ID
-     * @returns {String} unique folderPath/ListName combo of list
-     */
-    getListPathNameFromCache(cache, searchValue, searchField) {
-        const returnField1 = 'r__folder_Path';
-        const returnField2 = 'ListName';
-        for (const key in cache['list']) {
-            if (cache['list'][key][searchField] === searchValue) {
-                try {
-                    if (cache['list'][key][returnField1] && cache['list'][key][returnField2]) {
-                        return (
-                            cache['list'][key][returnField1] +
-                            '/' +
-                            cache['list'][key][returnField2]
-                        );
-                    } else {
-                        throw new Error();
-                    }
-                } catch (ex) {
-                    throw new Error(
-                        `${'list'} with ${searchField}='${searchValue}' does not have the fields ${returnField1} and ${returnField2}`
-                    );
-                }
-            }
-        }
-        throw new Error(
-            `Missing one or more dependent metadata. list with ${searchField}='${searchValue}' was not found on your BU`
-        );
-    },
-    /**
-     * retry on network issues
-     * @param {String} errorMsg what to print behind "Connection error. "
-     * @param {Function} callback what to try executing
-     * @param {Boolean} [silentError=false] prints retry messages to log only; default=false
-     * @param {Number} [retries=1] number of retries; default=1
-     * @returns {Promise<void>} -
-     */
-    async retryOnError(errorMsg, callback, silentError, retries) {
-        if ('undefined' === typeof retries || retries === null) {
-            retries = 3;
-        }
-        try {
-            await callback();
-        } catch (ex) {
-            if (
-                retries > 0 &&
-                ex.code &&
-                ['ETIMEDOUT', 'EHOSTUNREACH', 'ENOTFOUND', 'ECONNRESET'].includes(ex.code)
-            ) {
-                retries--;
-                Util.logger.debug(ex.stack);
-                const msg = `Connection problem. ${errorMsg} (${retries + 1} tries left)`;
-                if (silentError) {
-                    Util.logger.debug(msg);
-                } else {
-                    Util.logger.warn(msg);
-                }
-                await this.retryOnError(errorMsg, callback, silentError, retries);
-            } else if (
-                ex.code &&
-                ['ETIMEDOUT', 'EHOSTUNREACH', 'ENOTFOUND', 'ECONNRESET'].includes(ex.code)
-            ) {
-                Util.logger.debug(ex.stack);
-                Util.logger.error(
-                    `"${errorMsg}" Failed due to a Connection Error (${ex.code}) - Please check your network connection and try again`
-                );
-                if (Util.logger.level === 'debug') {
-                    console.log(ex.stack);
-                }
-                throw ex;
-            } else {
-                Util.logger.debug(ex.stack);
-                if (Util.logger.level === 'debug') {
-                    console.log(ex.stack);
-                }
-                Util.logger.error(ex.message);
-                throw ex;
-            }
-        }
+        return path.split('.').reduce((prev, curr) => (prev ? prev[curr] : null), obj);
     },
     /**
      * helper to run other commands as if run manually by user
+     *
      * @param {string} cmd to be executed command
      * @param {string[]} [args] list of arguments
      * @returns {undefined}
@@ -749,9 +364,66 @@ const Util = {
         const options = { stdio: [0, 1, 2] };
         return child_process.execSync(cmd + ' ' + args.join(' '), options);
     },
+    /**
+     * standardize check to ensure only one result is returned from template search
+     *
+     * @param {TYPE.MetadataTypeItem[]} results array of metadata
+     * @param {string} keyToSearch the field which contains the searched value
+     * @param {string} searchValue the value which is being looked for
+     * @returns {TYPE.MetadataTypeItem} metadata to be used in building template
+     */
+    templateSearchResult(results, keyToSearch, searchValue) {
+        const matching = results.filter((item) => item[keyToSearch] === searchValue);
+
+        if (matching.length === 0) {
+            throw new Error(`No metadata found with name "${searchValue}"`);
+        } else if (matching.length > 1) {
+            throw new Error(
+                `Multiple metadata with name "${searchValue}" please rename to be unique to avoid issues`
+            );
+        } else {
+            return matching[0];
+        }
+    },
+    /**
+     * configures what is displayed in the console
+     *
+     * @param {object} argv list of command line parameters given by user
+     * @param {boolean} [argv.silent] only errors printed to CLI
+     * @param {boolean} [argv.verbose] chatty user CLI output
+     * @param {boolean} [argv.debug] enables developer output & features
+     * @returns {void}
+     */
+    setLoggingLevel(argv) {
+        Util.loggerTransports.console.file = 'debug';
+        if (argv.silent) {
+            // only errors printed to CLI
+            Util.logger.level = 'error';
+            Util.loggerTransports.console.level = 'error';
+            Util.logger.debug('CLI logger set to: silent');
+        } else if (argv.verbose) {
+            // chatty user cli logs
+            Util.logger.level = 'verbose';
+            Util.loggerTransports.console.level = 'verbose';
+            Util.logger.debug('CLI logger set to: verbose');
+        } else {
+            // default user cli logs
+            // TODO to be switched to "warn" when cli-process is integrated
+            Util.logger.level = 'info';
+            Util.loggerTransports.console.level = 'info';
+            Util.logger.debug('CLI logger set to: info / default');
+        }
+        if (argv.debug) {
+            // enables developer output & features. no change to actual logs
+            Util.logger.level = 'debug';
+            Util.loggerTransports.console.level = 'debug';
+            Util.logger.debug('CLI logger set to: debug');
+        }
+    },
 };
 /**
  * wrapper around our standard winston logging to console and logfile
+ *
  * @returns {object} initiated logger for console and file
  */
 function createNewLoggerTransport() {
@@ -781,14 +453,58 @@ function createNewLoggerTransport() {
 }
 /**
  * initiate winston logger
+ *
  * @returns {void}
  */
 function startLogger() {
     Util.loggerTransports = createNewLoggerTransport();
-    Util.logger = winston.createLogger({
+    const myWinston = winston.createLogger({
         levels: winston.config.npm.levels,
         transports: [Util.loggerTransports.console, Util.loggerTransports.file],
     });
+    const winstonError = myWinston.error;
+    const winstonExtension = {
+        /**
+         * helper that prints better stack trace for errors
+         *
+         * @param {Error} ex the error
+         * @param {string} [message] optional custom message to be printed as error together with the exception's message
+         * @returns {void}
+         */
+        errorStack: function (ex, message) {
+            if (message) {
+                myWinston.error(message + ': ' + ex.message);
+            }
+            let stack;
+            /* eslint-disable unicorn/prefer-ternary */
+            if (
+                ['ETIMEDOUT', 'EHOSTUNREACH', 'ENOTFOUND', 'ECONNRESET', 'ECONNABORTED'].includes(
+                    ex.code
+                )
+            ) {
+                // the stack would just return a one-liner that does not help
+                stack = new Error().stack; // eslint-disable-line unicorn/error-message
+            } else {
+                stack = ex.stack;
+            }
+            /* eslint-enable unicorn/prefer-ternary */
+            myWinston.debug(stack);
+            Util.signalFatalError();
+        },
+        /**
+         * errors should cause surrounding applications to take notice
+         * hence we overwrite the default error function here
+         *
+         * @param {string} msg - the message to log
+         * @returns {void}
+         */
+        error: function (msg) {
+            winstonError(msg);
+            Util.signalFatalError();
+        },
+    };
+    Util.logger = Object.assign(myWinston, winstonExtension);
+
     Util.logger.debug(`:: mcdev ${packageJsonMcdev.version} ::`);
 }
 startLogger();