mcdev 4.0.2 → 4.1.0

package/README.md

@@ -123,7 +123,7 @@ If you experience issues installing Accenture SFMC DevTools, please check out th
 1. Install Accenture SFMC DevTools by running `npm install -g mcdev` (prefix with `sudo` on MacOS)
    - If you get an error, please see the below troubleshooting section.
 
-When completed run `mcdev --version` and it will show you which version you installed (e.g. `4.0.2`).
+When completed run `mcdev --version` and it will show you which version you installed (e.g. `4.1.0`).
 
 > **_Side note for proud nerds_:**
 >
@@ -277,10 +277,10 @@ _Note: Regardless of which tag or branch you install_
 **Install specific version (using a version tag on npm):**
 
 ```bash
-npm install -g mcdev@4.0.2
+npm install -g mcdev@4.1.0
 ```
 
-**Warning**: When you used the above method to install Accenture SFMC DevTools for a specific version or tag, trying to [update Accenture SFMC DevTools](#updating-mcdev) might not download the most recently published official version but instead stay on the version or branch you previously selected (in the above examples: develop, 4.0.2)!
+**Warning**: When you used the above method to install Accenture SFMC DevTools for a specific version or tag, trying to [update Accenture SFMC DevTools](#updating-mcdev) might not download the most recently published official version but instead stay on the version or branch you previously selected (in the above examples: develop, 4.1.0)!
 
 > **Note**: The version is currently _not_ updated on the developer branch until a new release is published. Hence, you will not see a change if you run `mcdev --version`.
 
@@ -1485,25 +1485,21 @@ If you want to enhance Accenture SFMC DevTools you are welcome to fork the repo
 
 Instead of installing Accenture SFMC DevTools as a npm dependency from our git repo, we recommend cloning our repo and then linking it locally:
 
-Assuming you cloned Accenture SFMC DevTools into `C:\repos\sfmc-devtools\` (or `~/repos/sfmc-devtools/` on Mac) you can then go into your project directory, open a terminal there and run:
+Assuming you cloned Accenture SFMC DevTools into `C:\repos\sfmc-devtools\` (or `~/repos/sfmc-devtools/` on Mac):
 
-_Local install:_
+1. Open a terminal in your repo folder (`repos/sfmc-devtools/`)
+2. Execute `npm install` to download all the dependencies.
+3. Execute `npx husky install` to enable our git hooks.
+4. Execute `npm install -g "C:\repos\sfmc-devtools"` (this installs mcdev globally on your computer based on your cloned repo folder. Any changes you make in there will take immediate effect without the need for publishing or re-installing it).
 
-```bash
-npm install --save-dev "C:\repos\sfmc-devtools"
-```
+This should tell npm to create a symlink to your cloned local directoty, allowing you to see updates you make in your mcdev repo instantly.
 
-or
+To test your new **global** developer setup, run `mcdev --version` in CLI which should return the current version (e.g. `4.1.0`). Then, go into your mcdev repo and update the version with the suffix `-dev`, e.g. to `4.1.0-dev` and then run `mcdev --version` again to verify that your change propagates instantly.
 
-_Global install **(recommended)**:_
+> **Not recommended:** Alternatively, you can install it locally only by opening a terminal in your project directory and executing `npm install --save-dev "C:\repos\sfmc-devtools"`
+> To run the local version you need to prepend "npx" before your commands, e.g. `npx mcdev --version`
 
-```bash
-npm install -g "C:\repos\sfmc-devtools"
-```
-
-This should tell npm to create a symlink to your cloned local directoty, allowing you to see updates you make in your mcdev repo instantly.
-
-> Note: on MacOS you might need to prepend `sudo` to elevate your command.
+**Note:** On MacOS you might need to prepend `sudo` to elevate your command.
 
 **Local vs. Global developer installation:**
 
@@ -1511,8 +1507,6 @@ If you use Accenture SFMC DevTools in your team it is recommended to install you
 
 If you do need to install it locally, make sure you don't commit your project's package.json with this change or you might break mcdev for other developers in your team that either didn't clone the Accenture SFMC DevTools repo or stored in a different directory.
 
-To test your new **global** developer setup, run `mcdev --version` in CLI which should return the current version (e.g. `4.0.2`). Then, go into your mcdev repo and update the version with the suffix `-dev`, e.g. to `4.0.2-dev` and then run `mcdev --version` again to verify that your change propagates instantly.
-
 <a name="local-install"></a>
 
 ### 9.2. Local install
@@ -1538,7 +1532,7 @@ The following explains how you _could_ install it locally for certain edge cases
 4. Afterwards, install Accenture SFMC DevTools by running `npm install --save-dev mcdev`
    - If you get an error, please see the below troubleshooting section.
 
-When completed run `mcdev --version` and it will show you which version you installed (e.g. `4.0.2`).
+When completed run `mcdev --version` and it will show you which version you installed (e.g. `4.1.0`).
 
 ### 9.3. NPM Scripts
 

package/docs/dist/documentation.md

@@ -180,8 +180,9 @@ Provides default functionality that can be overwritten by child metadata type cl
 ## Typedefs
 
 <dl>
-<dt><a href="#SupportedMetadataTypes">SupportedMetadataTypes</a> : <code>Object.&lt;string, string&gt;</code></dt>
-<dd></dd>
+<dt><a href="#TypeKeyCombo">TypeKeyCombo</a> : <code>Object.&lt;string, string&gt;</code></dt>
+<dd><p>object-key=metadata type, value=array of external keys</p>
+</dd>
 <dt><a href="#Cache">Cache</a> : <code>Object.&lt;string, any&gt;</code></dt>
 <dd><p>key=customer key</p>
 </dd>
@@ -346,7 +347,6 @@ Source and target business units are also compared before the deployment to appl
     * _instance_
         * [.metadata](#Deployer+metadata) : <code>TYPE.MultiMetadataTypeMap</code>
         * [._deploy([typeArr], [keyArr], [fromRetrieve])](#Deployer+_deploy) ⇒ <code>Promise</code>
-        * [.deployCallback(result, metadataType)](#Deployer+deployCallback) ⇒ <code>void</code>
     * _static_
         * [.deploy(businessUnit, [selectedTypesArr], [keyArr], [fromRetrieve])](#Deployer.deploy) ⇒ <code>Promise.&lt;void&gt;</code>
         * [._deployBU(cred, bu, properties, [typeArr], [keyArr], [fromRetrieve])](#Deployer._deployBU) ⇒ <code>Promise</code>
@@ -378,22 +378,10 @@ Deploy all metadata that is located in the deployDir
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [typeArr] | <code>Array.&lt;string&gt;</code> | limit deployment to given metadata type (can include subtype) |
+| [typeArr] | <code>Array.&lt;TYPE.SupportedMetadataTypes&gt;</code> | limit deployment to given metadata type (can include subtype) |
 | [keyArr] | <code>Array.&lt;string&gt;</code> | limit deployment to given metadata keys |
 | [fromRetrieve] | <code>boolean</code> | if true, no folders will be updated/created |
 
-<a name="Deployer+deployCallback"></a>
-
-### deployer.deployCallback(result, metadataType) ⇒ <code>void</code>
-Gets called for every deployed metadata entry
-
-**Kind**: instance method of [<code>Deployer</code>](#Deployer)  
-
-| Param | Type | Description |
-| --- | --- | --- |
-| result | <code>object</code> | Deployment result |
-| metadataType | <code>string</code> | Name of metadata type |
-
 <a name="Deployer.deploy"></a>
 
 ### Deployer.deploy(businessUnit, [selectedTypesArr], [keyArr], [fromRetrieve]) ⇒ <code>Promise.&lt;void&gt;</code>
@@ -405,7 +393,7 @@ Deploys all metadata located in the 'deploy' directory to the specified business
 | Param | Type | Description |
 | --- | --- | --- |
 | businessUnit | <code>string</code> | references credentials from properties.json |
-| [selectedTypesArr] | <code>Array.&lt;string&gt;</code> | limit deployment to given metadata type |
+| [selectedTypesArr] | <code>Array.&lt;TYPE.SupportedMetadataTypes&gt;</code> | limit deployment to given metadata type |
 | [keyArr] | <code>Array.&lt;string&gt;</code> | limit deployment to given metadata keys |
 | [fromRetrieve] | <code>boolean</code> | optionally deploy whats defined via selectedTypesArr + keyArr directly from retrieve folder instead of from deploy folder |
 
@@ -422,7 +410,7 @@ helper for deploy()
 | cred | <code>string</code> | name of Credential |
 | bu | <code>string</code> | name of BU |
 | properties | <code>TYPE.Mcdevrc</code> | General configuration to be used in retrieve |
-| [typeArr] | <code>Array.&lt;string&gt;</code> | limit deployment to given metadata type |
+| [typeArr] | <code>Array.&lt;TYPE.SupportedMetadataTypes&gt;</code> | limit deployment to given metadata type |
 | [keyArr] | <code>Array.&lt;string&gt;</code> | limit deployment to given metadata keys |
 | [fromRetrieve] | <code>boolean</code> | optionally deploy whats defined via selectedTypesArr + keyArr directly from retrieve folder instead of from deploy folder |
 
@@ -518,6 +506,7 @@ handler for 'mcdev createDeltaPkg
 | argv | <code>object</code> | yargs parameters |
 | [argv.range] | <code>string</code> | git commit range     into deploy directory |
 | [argv.filter] | <code>string</code> | filter file paths that start with any |
+| [argv.diffArr] | <code>Array.&lt;TYPE.DeltaPkgItem&gt;</code> | list of files to include in delta package (skips git diff when provided) |
 | [argv.skipInteraction] | <code>TYPE.skipInteraction</code> | allows to skip interactive wizard |
 
 <a name="Mcdev.selectTypes"></a>
@@ -550,7 +539,7 @@ Retrieve all metadata from the specified business unit into the local file syste
 | Param | Type | Description |
 | --- | --- | --- |
 | businessUnit | <code>string</code> | references credentials from properties.json |
-| [selectedTypesArr] | <code>Array.&lt;string&gt;</code> | limit retrieval to given metadata type |
+| [selectedTypesArr] | <code>Array.&lt;TYPE.SupportedMetadataTypes&gt;</code> \| <code>TYPE.TypeKeyCombo</code> | limit retrieval to given metadata type |
 | [keys] | <code>Array.&lt;string&gt;</code> | limit retrieval to given metadata key |
 | [changelogOnly] | <code>boolean</code> | skip saving, only create json in memory |
 
@@ -565,7 +554,7 @@ Deploys all metadata located in the 'deploy' directory to the specified business
 | Param | Type | Default | Description |
 | --- | --- | --- | --- |
 | businessUnit | <code>string</code> |  | references credentials from properties.json |
-| [selectedTypesArr] | <code>Array.&lt;string&gt;</code> |  | limit deployment to given metadata type |
+| [selectedTypesArr] | <code>Array.&lt;TYPE.SupportedMetadataTypes&gt;</code> |  | limit deployment to given metadata type |
 | [keyArr] | <code>Array.&lt;string&gt;</code> |  | limit deployment to given metadata keys |
 | [fromRetrieve] | <code>boolean</code> | <code>false</code> | optionally deploy whats defined via selectedTypesArr + keyArr directly from retrieve folder instead of from deploy folder |
 
@@ -840,7 +829,7 @@ FileTransfer MetadataType
     * [.requestSubType(subType, subTypeArray, [retrieveDir], [templateName], [templateVariables], key)](#Asset.requestSubType) ⇒ <code>Promise</code>
     * [.requestAndSaveExtended(items, subType, retrieveDir, [templateVariables])](#Asset.requestAndSaveExtended) ⇒ <code>Promise</code>
     * [._retrieveExtendedFile(metadata, subType, retrieveDir)](#Asset._retrieveExtendedFile) ⇒ <code>Promise.&lt;void&gt;</code>
-    * [._readExtendedFileFromFS(metadata, subType, deployDir)](#Asset._readExtendedFileFromFS) ⇒ <code>Promise.&lt;void&gt;</code>
+    * [._readExtendedFileFromFS(metadata, subType, deployDir, [pathOnly])](#Asset._readExtendedFileFromFS) ⇒ <code>Promise.&lt;string&gt;</code>
     * [.postRetrieveTasks(metadata)](#Asset.postRetrieveTasks) ⇒ <code>TYPE.CodeExtractItem</code>
     * [.preDeployTasks(metadata, deployDir, buObject)](#Asset.preDeployTasks) ⇒ <code>Promise.&lt;TYPE.AssetItem&gt;</code>
     * [._getMainSubtype(extendedSubType)](#Asset._getMainSubtype) ⇒ <code>string</code>
@@ -974,19 +963,20 @@ This method retrieves these and saves them alongside the metadata json
 
 <a name="Asset._readExtendedFileFromFS"></a>
 
-### Asset.\_readExtendedFileFromFS(metadata, subType, deployDir) ⇒ <code>Promise.&lt;void&gt;</code>
+### Asset.\_readExtendedFileFromFS(metadata, subType, deployDir, [pathOnly]) ⇒ <code>Promise.&lt;string&gt;</code>
 helper for this.preDeployTasks()
 Some metadata types store their actual content as a separate file, e.g. images
 This method reads these from the local FS stores them in the metadata object allowing to deploy it
 
 **Kind**: static method of [<code>Asset</code>](#Asset)  
-**Returns**: <code>Promise.&lt;void&gt;</code> - -  
+**Returns**: <code>Promise.&lt;string&gt;</code> - if found will return the path of the binary file  
 
-| Param | Type | Description |
-| --- | --- | --- |
-| metadata | <code>TYPE.AssetItem</code> | a single asset |
-| subType | <code>TYPE.AssetSubType</code> | group of similar assets to put in a folder (ie. images) |
-| deployDir | <code>string</code> | directory of deploy files |
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| metadata | <code>TYPE.AssetItem</code> |  | a single asset |
+| subType | <code>TYPE.AssetSubType</code> |  | group of similar assets to put in a folder (ie. images) |
+| deployDir | <code>string</code> |  | directory of deploy files |
+| [pathOnly] | <code>boolean</code> | <code>false</code> | used by getFilesToCommit which does not need the binary file to be actually read |
 
 <a name="Asset.postRetrieveTasks"></a>
 
@@ -4418,8 +4408,8 @@ Retrieve metadata of specified types into local file system and Retriever.metada
 
 | Param | Type | Description |
 | --- | --- | --- |
-| metadataTypes | <code>Array.&lt;string&gt;</code> | String list of metadata types to retrieve |
-| [namesOrKeys] | <code>Array.&lt;string&gt;</code> | name of Metadata to retrieveAsTemplate or list of keys for normal retrieval |
+| metadataTypes | <code>Array.&lt;TYPE.SupportedMetadataTypes&gt;</code> | list of metadata types to retrieve; can include subtypes! |
+| [namesOrKeys] | <code>Array.&lt;string&gt;</code> \| <code>TYPE.TypeKeyCombo</code> | name of Metadata to retrieveAsTemplate or list of keys for normal retrieval |
 | [templateVariables] | <code>TYPE.TemplateMap</code> | Object of values which can be replaced (in case of templating) |
 | [changelogOnly] | <code>boolean</code> | skip saving, only create json in memory |
 
@@ -4943,7 +4933,7 @@ DevOps helper class
     * [.getDeltaList(properties, [range], [saveToDeployDir], [filterPaths])](#DevOps.getDeltaList) ⇒ <code>Promise.&lt;Array.&lt;TYPE.DeltaPkgItem&gt;&gt;</code>
         * [~delta](#DevOps.getDeltaList..delta) : <code>Array.&lt;TYPE.DeltaPkgItem&gt;</code>
         * [~copied](#DevOps.getDeltaList..copied) : <code>TYPE.DeltaPkgItem</code>
-    * [.buildDeltaDefinitions(properties, range, [skipInteraction])](#DevOps.buildDeltaDefinitions) ⇒ <code>Promise.&lt;Array.&lt;TYPE.DeltaPkgItem&gt;&gt;</code>
+    * [.buildDeltaDefinitions(properties, range, [diffArr], [skipInteraction])](#DevOps.buildDeltaDefinitions) ⇒ <code>Promise.&lt;Array.&lt;TYPE.DeltaPkgItem&gt;&gt;</code>
         * [~deltaDeployAll](#DevOps.buildDeltaDefinitions..deltaDeployAll) : <code>Array.&lt;TYPE.DeltaPkgItem&gt;</code>
     * [.document(directory, jsonReport)](#DevOps.document) ⇒ <code>void</code>
     * [.getFilesToCommit(properties, buObject, metadataType, keyArr)](#DevOps.getFilesToCommit) ⇒ <code>Promise.&lt;Array.&lt;string&gt;&gt;</code>
@@ -4979,7 +4969,7 @@ Interactive commit selection if no commits are passed.
 **Kind**: inner constant of [<code>getDeltaList</code>](#DevOps.getDeltaList)  
 <a name="DevOps.buildDeltaDefinitions"></a>
 
-### DevOps.buildDeltaDefinitions(properties, range, [skipInteraction]) ⇒ <code>Promise.&lt;Array.&lt;TYPE.DeltaPkgItem&gt;&gt;</code>
+### DevOps.buildDeltaDefinitions(properties, range, [diffArr], [skipInteraction]) ⇒ <code>Promise.&lt;Array.&lt;TYPE.DeltaPkgItem&gt;&gt;</code>
 wrapper around DevOps.getDeltaList, Builder.buildTemplate and M
 
 **Kind**: static method of [<code>DevOps</code>](#DevOps)  
@@ -4989,6 +4979,7 @@ wrapper around DevOps.getDeltaList, Builder.buildTemplate and M
 | --- | --- | --- |
 | properties | <code>TYPE.Mcdevrc</code> | project config file |
 | range | <code>string</code> | git commit range |
+| [diffArr] | <code>Array.&lt;TYPE.DeltaPkgItem&gt;</code> | instead of running git diff the method can also get a list of files to process |
 | [skipInteraction] | <code>TYPE.SkipInteraction</code> | allows to skip interactive wizard |
 
 <a name="DevOps.buildDeltaDefinitions..deltaDeployAll"></a>
@@ -6493,9 +6484,11 @@ wrapper around our standard winston logging to console and logfile
 initiate winston logger
 
 **Kind**: global function  
-<a name="SupportedMetadataTypes"></a>
+<a name="TypeKeyCombo"></a>
+
+## TypeKeyCombo : <code>Object.&lt;string, string&gt;</code>
+object-key=metadata type, value=array of external keys
 
-## SupportedMetadataTypes : <code>Object.&lt;string, string&gt;</code>
 **Kind**: global typedef  
 <a name="Cache"></a>
 
@@ -6778,7 +6771,7 @@ SOAP format
 | binary | <code>boolean</code> | is a binary file |
 | moved | <code>boolean</code> | git thinks this file was moved |
 | [fromPath] | <code>string</code> | git thinks this relative path is where the file was before |
-| type | [<code>SupportedMetadataTypes</code>](#SupportedMetadataTypes) | metadata type |
+| type | <code>SupportedMetadataTypes</code> | metadata type |
 | externalKey | <code>string</code> | key |
 | name | <code>string</code> | name |
 | gitAction | <code>&#x27;move&#x27;</code> \| <code>&#x27;add/update&#x27;</code> \| <code>&#x27;delete&#x27;</code> | what git recognized as an action |

package/lib/Deployer.js

@@ -45,7 +45,7 @@ class Deployer {
      * Deploys all metadata located in the 'deploy' directory to the specified business unit
      *
      * @param {string} businessUnit references credentials from properties.json
-     * @param {string[]} [selectedTypesArr] limit deployment to given metadata type
+     * @param {TYPE.SupportedMetadataTypes[]} [selectedTypesArr] limit deployment to given metadata type
      * @param {string[]} [keyArr] limit deployment to given metadata keys
      * @param {boolean} [fromRetrieve] optionally deploy whats defined via selectedTypesArr + keyArr directly from retrieve folder instead of from deploy folder
      * @returns {Promise.<void>} -
@@ -158,7 +158,7 @@ class Deployer {
      * @param {string} cred name of Credential
      * @param {string} bu name of BU
      * @param {TYPE.Mcdevrc} properties General configuration to be used in retrieve
-     * @param {string[]} [typeArr] limit deployment to given metadata type
+     * @param {TYPE.SupportedMetadataTypes[]} [typeArr] limit deployment to given metadata type
      * @param {string[]} [keyArr] limit deployment to given metadata keys
      * @param {boolean} [fromRetrieve] optionally deploy whats defined via selectedTypesArr + keyArr directly from retrieve folder instead of from deploy folder
      * @returns {Promise} ensure that BUs are worked on sequentially
@@ -182,7 +182,7 @@ class Deployer {
     /**
      * Deploy all metadata that is located in the deployDir
      *
-     * @param {string[]} [typeArr] limit deployment to given metadata type (can include subtype)
+     * @param {TYPE.SupportedMetadataTypes[]} [typeArr] limit deployment to given metadata type (can include subtype)
      * @param {string[]} [keyArr] limit deployment to given metadata keys
      * @param {boolean} [fromRetrieve] if true, no folders will be updated/created
      * @returns {Promise} Promise
@@ -247,28 +247,10 @@ class Deployer {
                     this.buObject
                 );
                 cache.mergeMetadata(type, result);
-                this.deployCallback(result, type);
             }
         }
     }
 
-    /**
-     * Gets called for every deployed metadata entry
-     *
-     * @param {object} result Deployment result
-     * @param {string} metadataType Name of metadata type
-     * @returns {void}
-     */
-    deployCallback(result, metadataType) {
-        if (result) {
-            File.writeJSONToFile('logs/', 'deployResult_' + metadataType, result);
-            Util.logger.verbose(
-                'Deployer.deployCallback:: Results written to: ' +
-                    path.normalize(process.cwd() + '/logs/deployResult_' + metadataType + '.json')
-            );
-        }
-    }
-
     /**
      * Returns metadata of a business unit that is saved locally
      *

package/lib/Retriever.js

@@ -31,8 +31,8 @@ class Retriever {
     /**
      * Retrieve metadata of specified types into local file system and Retriever.metadata
      *
-     * @param {string[]} metadataTypes String list of metadata types to retrieve
-     * @param {string[]} [namesOrKeys] name of Metadata to retrieveAsTemplate or list of keys for normal retrieval
+     * @param {TYPE.SupportedMetadataTypes[]} metadataTypes list of metadata types to retrieve; can include subtypes!
+     * @param {string[]|TYPE.TypeKeyCombo} [namesOrKeys] name of Metadata to retrieveAsTemplate or list of keys for normal retrieval
      * @param {TYPE.TemplateMap} [templateVariables] Object of values which can be replaced (in case of templating)
      * @param {boolean} [changelogOnly] skip saving, only create json in memory
      * @returns {Promise.<TYPE.MultiMetadataTypeList>} Promise of a list of retrieved items grouped by type {automation:[...], query:[...]}
@@ -42,12 +42,31 @@ class Retriever {
          * @type {TYPE.MultiMetadataTypeList}
          */
         const retrieveChangelog = {};
-        if (!namesOrKeys || !namesOrKeys.length) {
-            // make iterating over namesOrKeys easier
+        if (!namesOrKeys || (Array.isArray(namesOrKeys) && !namesOrKeys.length)) {
+            // no keys were provided, ensure we retrieve all
             namesOrKeys = [null];
         }
+        /** @type {TYPE.TypeKeyCombo} */
+        let typeKeyMap = {};
+        if (Array.isArray(namesOrKeys)) {
+            // no keys or array of keys was provided (likely called via CLI or to retrieve all)
+            // transform into TypeKeyCombo to iterate over it
+            for (const type of metadataTypes) {
+                typeKeyMap[type] = namesOrKeys;
+            }
+        } else {
+            // assuming TypeKeyCombo was provided
+            typeKeyMap = namesOrKeys;
+        }
+        // defined colors for optionally printing the keys we filtered by
+        const color = {
+            reset: '\x1B[0m',
+            dim: '\x1B[2m',
+        };
         for (const metadataType of Util.getMetadataHierachy(metadataTypes)) {
             const [type, subType] = metadataType.split('-');
+            // if types were added by getMetadataHierachy() for caching, make sure the key-list is set to [null] for them which will retrieve all
+            typeKeyMap[metadataType] = typeKeyMap[metadataType] || [null];
             // add client to metadata process class instead of passing every time
             MetadataTypeInfo[type].client = auth.getSDK(this.buObject);
             MetadataTypeInfo[type].properties = this.properties;
@@ -65,7 +84,7 @@ class Retriever {
                     Util.logger.info(`Retrieving as Template: ${metadataType}`);
 
                     result = await Promise.all(
-                        namesOrKeys.map((name) =>
+                        typeKeyMap[metadataType].map((name) =>
                             MetadataTypeInfo[type].retrieveAsTemplate(
                                 this.templateDir,
                                 name,
@@ -75,11 +94,18 @@ class Retriever {
                         )
                     );
                 } else {
-                    Util.logger.info('Retrieving: ' + metadataType);
+                    Util.logger.info(
+                        `Retrieving: ${metadataType}` +
+                            (typeKeyMap[metadataType][0] !== null
+                                ? ` ${color.dim}(Keys: ${typeKeyMap[metadataType].join(', ')})${
+                                      color.reset
+                                  }`
+                                : '')
+                    );
                     result = await (changelogOnly
                         ? MetadataTypeInfo[type].retrieveChangelog(this.buObject, null, subType)
                         : Promise.all(
-                              namesOrKeys.map((key) =>
+                              typeKeyMap[metadataType].map((key) =>
                                   MetadataTypeInfo[type].retrieve(
                                       this.savePath,
                                       null,

package/lib/index.js

@@ -49,6 +49,7 @@ class Mcdev {
      * @param {string} [argv.range] git commit range
     into deploy directory
      * @param {string} [argv.filter] filter file paths that start with any
+     * @param {TYPE.DeltaPkgItem[]} [argv.diffArr] list of files to include in delta package (skips git diff when provided)
      * @param {TYPE.skipInteraction} [argv.skipInteraction] allows to skip interactive wizard
      * @returns {Promise.<TYPE.DeltaPkgItem[]>} list of changed items
      */
@@ -64,7 +65,12 @@ class Mcdev {
             ? // get source market and source BU from config
               DevOps.getDeltaList(properties, argv.range, true, argv.filter)
             : // If no custom filter was provided, use deployment marketLists & templating
-              DevOps.buildDeltaDefinitions(properties, argv.range, argv.skipInteraction);
+              DevOps.buildDeltaDefinitions(
+                  properties,
+                  argv.range,
+                  argv.diffArr,
+                  argv.skipInteraction
+              );
     }
 
     /**
@@ -105,7 +111,7 @@ class Mcdev {
      * Retrieve all metadata from the specified business unit into the local file system.
      *
      * @param {string} businessUnit references credentials from properties.json
-     * @param {string[]} [selectedTypesArr] limit retrieval to given metadata type
+     * @param {TYPE.SupportedMetadataTypes[]|TYPE.TypeKeyCombo} [selectedTypesArr] limit retrieval to given metadata type
      * @param {string[]} [keys] limit retrieval to given metadata key
      * @param {boolean} [changelogOnly] skip saving, only create json in memory
      * @returns {Promise.<object>} -
@@ -120,7 +126,9 @@ class Mcdev {
 
         // assume a list was passed in and check each entry's validity
         if (selectedTypesArr) {
-            for (const selectedType of selectedTypesArr) {
+            for (const selectedType of Array.isArray(selectedTypesArr)
+                ? selectedTypesArr
+                : Object.keys(selectedTypesArr)) {
                 if (!Util._isValidType(selectedType)) {
                     return;
                 }
@@ -195,7 +203,7 @@ class Mcdev {
      * @private
      * @param {string} cred name of Credential
      * @param {string} bu name of BU
-     * @param {string[]} [selectedTypesArr] limit retrieval to given metadata type/subtype
+     * @param {TYPE.SupportedMetadataTypes[]|TYPE.TypeKeyCombo} [selectedTypesArr] limit retrieval to given metadata type/subtype
      * @param {string[]} [keys] limit retrieval to given metadata key
      * @param {boolean} [changelogOnly] skip saving, only create json in memory
      * @returns {Promise.<object>} ensure that BUs are worked on sequentially
@@ -218,7 +226,9 @@ class Mcdev {
             Util.logger.info(`\n               :: Retrieving ${cred}/${bu}\n`);
             const retrieveTypesArr = [];
             if (selectedTypesArr) {
-                for (const selectedType of selectedTypesArr) {
+                for (const selectedType of Array.isArray(selectedTypesArr)
+                    ? selectedTypesArr
+                    : Object.keys(selectedTypesArr)) {
                     const [type, subType] = selectedType ? selectedType.split('-') : [];
                     const removePathArr = [properties.directories.retrieve, cred, bu, type];
                     if (
@@ -255,7 +265,7 @@ class Mcdev {
                 // await is required or the calls end up conflicting
                 const retrieveChangelog = await retriever.retrieve(
                     retrieveTypesArr,
-                    keys,
+                    Array.isArray(selectedTypesArr) ? keys : selectedTypesArr,
                     null,
                     changelogOnly
                 );
@@ -272,7 +282,7 @@ class Mcdev {
      * Deploys all metadata located in the 'deploy' directory to the specified business unit
      *
      * @param {string} businessUnit references credentials from properties.json
-     * @param {string[]} [selectedTypesArr] limit deployment to given metadata type
+     * @param {TYPE.SupportedMetadataTypes[]} [selectedTypesArr] limit deployment to given metadata type
      * @param {string[]} [keyArr] limit deployment to given metadata keys
      * @param {boolean} [fromRetrieve] optionally deploy whats defined via selectedTypesArr + keyArr directly from retrieve folder instead of from deploy folder
      * @returns {Promise.<void>} -

package/lib/metadataTypes/Asset.js

@@ -276,7 +276,11 @@ class Asset extends MetadataType {
         } else if (retrieveDir && !items.length) {
             Util.logger.info(`  Downloaded asset-${subType}: ${items.length}`);
         }
-        return items;
+
+        return items.map((item) => {
+            item._subType = subType;
+            return item;
+        });
     }
     /**
      * Retrieves extended metadata (files or extended content) of asset
@@ -446,20 +450,33 @@ class Asset extends MetadataType {
      * @param {TYPE.AssetItem} metadata a single asset
      * @param {TYPE.AssetSubType} subType group of similar assets to put in a folder (ie. images)
      * @param {string} deployDir directory of deploy files
-     * @returns {Promise.<void>} -
+     * @param {boolean} [pathOnly=false] used by getFilesToCommit which does not need the binary file to be actually read
+     * @returns {Promise.<string>} if found will return the path of the binary file
      */
-    static async _readExtendedFileFromFS(metadata, subType, deployDir) {
-        if (metadata.fileProperties && metadata.fileProperties.extension) {
-            // to handle uploaded files that bear the same name, SFMC engineers decided to add a number after the fileName
-            // however, their solution was not following standards: fileName="header.png (4) " and then extension="png (4) "
-            const fileExt = metadata.fileProperties.extension.split(' ')[0];
+    static async _readExtendedFileFromFS(metadata, subType, deployDir, pathOnly = false) {
+        // to handle uploaded files that bear the same name, SFMC engineers decided to add a number after the fileName
+        // however, their solution was not following standards: fileName="header.png (4) " and then extension="png (4) "
+        if (!metadata?.fileProperties?.extension) {
+            return;
+        }
+        const fileExt = metadata.fileProperties.extension.split(' ')[0];
 
-            metadata.file = await File.readFilteredFilename(
-                [deployDir, this.definition.type, subType],
-                metadata.customerKey,
-                fileExt,
-                'base64'
-            );
+        const path = File.normalizePath([
+            deployDir,
+            this.definition.type,
+            subType,
+            `${metadata.customerKey}.${fileExt}`,
+        ]);
+        if (await File.pathExists(path)) {
+            if (!pathOnly) {
+                metadata.file = await File.readFilteredFilename(
+                    [deployDir, this.definition.type, subType],
+                    metadata.customerKey,
+                    fileExt,
+                    'base64'
+                );
+            }
+            return path;
         }
     }
     /**
@@ -512,8 +529,8 @@ class Asset extends MetadataType {
             metadata.memberId !== buObject.mid &&
             !metadata[this.definition.keyField].startsWith(buObject.mid)
         ) {
-            // #3 make sure customer key is unique by prefixing it with target MID (unless we are deploying to the same MID)
-            // check if this prefixed with the source MID
+            // #3 make sure customer key is unique by suffixing it with target MID (unless we are deploying to the same MID)
+            // check if this suffixed with the source MID
             const suffix = '-' + buObject.mid;
             // for customer key max is 36 chars
             metadata[this.definition.keyField] =
@@ -1362,6 +1379,7 @@ class Asset extends MetadataType {
         const fileList = (
             await Promise.all(
                 keyArr.map(async (key) => {
+                    // get subType, path an fileName by scanning the retrieve folder
                     let subType;
                     let filePath;
                     let fileName;
@@ -1391,8 +1409,13 @@ class Asset extends MetadataType {
                             break;
                         }
                     }
-                    if (await File.pathExists(File.normalizePath([...filePath, fileName]))) {
+                    if (
+                        Array.isArray(filePath) &&
+                        (await File.pathExists(File.normalizePath([...filePath, fileName])))
+                    ) {
+                        // #1 load json to be able to find extracted text files & binary files
                         const metadata = File.readJSONFile(filePath, fileName, true, false);
+                        // #2 find all extracted text files
                         const fileListNested = (
                             await this._mergeCode(metadata, basePath, subType, metadata.customerKey)
                         ).map((item) =>
@@ -1402,8 +1425,22 @@ class Asset extends MetadataType {
                                 `${item.fileName}.${item.fileExt}`,
                             ])
                         );
+                        const response = [
+                            File.normalizePath([...filePath, fileName]),
+                            ...fileListNested,
+                        ];
+                        // #3 get binary file
+                        const binaryFilePath = await this._readExtendedFileFromFS(
+                            metadata,
+                            subType,
+                            basePath,
+                            false
+                        );
+                        if (binaryFilePath) {
+                            response.push(binaryFilePath);
+                        }
 
-                        return [File.normalizePath([...filePath, fileName]), ...fileListNested];
+                        return response;
                     } else {
                         return [];
                     }

package/lib/metadataTypes/Script.js

@@ -284,7 +284,7 @@ class Script extends MetadataType {
             ssjs = metadata.script;
             fileExt = 'html';
             Util.logger.warn(
-                ' - Could not find script tags, saving whole text in SSJS: ' + metadata.name
+                ` - Could not find script tags, saving code in ${metadata.name}.script-meta.html instead of as SSJS file.`
             );
         }
         delete metadata.script;
@@ -315,6 +315,7 @@ class Script extends MetadataType {
         const fileList = keyArr.flatMap((key) => [
             File.normalizePath([path, `${key}.${this.definition.type}-meta.json`]),
             File.normalizePath([path, `${key}.${this.definition.type}-meta.ssjs`]),
+            File.normalizePath([path, `${key}.${this.definition.type}-meta.html`]),
         ]);
         return fileList;
     }

package/lib/util/devops.js

@@ -248,10 +248,11 @@ const DevOps = {
      *
      * @param {TYPE.Mcdevrc} properties project config file
      * @param {string} range git commit range
+     * @param {TYPE.DeltaPkgItem[]} [diffArr] instead of running git diff the method can also get a list of files to process
      * @param {TYPE.SkipInteraction} [skipInteraction] allows to skip interactive wizard
      * @returns {Promise.<TYPE.DeltaPkgItem[]>} -
      */
-    async buildDeltaDefinitions(properties, range, skipInteraction) {
+    async buildDeltaDefinitions(properties, range, diffArr, skipInteraction) {
         // check if sourceTargetMapping is valid
         if (
             !properties.options.deployment.sourceTargetMapping ||
@@ -304,7 +305,9 @@ const DevOps = {
             const sourceBU = Object.keys(properties.marketList[sourceMlName])[0];
             const sourceMarket = Object.values(properties.marketList[sourceMlName])[0];
 
-            const delta = await DevOps.getDeltaList(properties, range, false, sourceBU);
+            const delta = Array.isArray(diffArr)
+                ? diffArr
+                : await DevOps.getDeltaList(properties, range, false, sourceBU);
             // If only chaing templating and buildDefinition if required
             if (!delta || delta.length === 0) {
                 // info/error messages was printed by DevOps.createDeltaPkg() already

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "mcdev",
-    "version": "4.0.2",
+    "version": "4.1.0",
     "description": "Accenture Salesforce Marketing Cloud DevTools",
     "author": "joern.berkefeld, douglas.midgley, robert.zimmermann, maciej.barnas",
     "license": "MIT",
@@ -36,7 +36,7 @@
         "lint-type": "eslint types/*.js",
         "lint-test": "eslint test/**/*.js",
         "upgrade": "npm-check --update",
-        "prepare": "husky install",
+        "manual-prepare": "husky install",
         "test": "mocha"
     },
     "dependencies": {
@@ -67,14 +67,14 @@
         "eslint": "8.25.0",
         "eslint-config-prettier": "8.5.0",
         "eslint-config-ssjs": "1.1.11",
-        "eslint-plugin-jsdoc": "39.3.6",
+        "eslint-plugin-jsdoc": "39.3.13",
         "eslint-plugin-mocha": "10.1.0",
         "eslint-plugin-prettier": "4.2.1",
         "eslint-plugin-unicorn": "44.0.2",
         "husky": "8.0.1",
         "jsdoc-to-markdown": "7.1.1",
         "lint-staged": "13.0.3",
-        "mocha": "10.0.0",
+        "mocha": "10.1.0",
         "mock-fs": "5.1.4",
         "npm-check": "6.0.1",
         "npm-run-all": "4.1.5",

package/types/mcdev.d.js

@@ -12,7 +12,8 @@ const SDK = require('sfmc-sdk');
  */
 /**
  * @typedef {Object.<string, string>} TemplateMap
- * @typedef {'accountUser'|'asset'|'attributeGroup'|'automation'|'campaign'|'contentArea'|'dataExtension'|'dataExtensionField'|'dataExtensionTemplate'|'dataExtract'|'dataExtractType'|'discovery'|'email'|'emailSendDefinition'|'eventDefinition'|'fileTransfer'|'filter'|'folder'|'ftpLocation'|'importFile'|'interaction'|'list'|'mobileCode'|'mobileKeyword'|'query'|'role'|'script'|'setDefinition'|'triggeredSendDefinition'} SupportedMetadataTypes
+ * @typedef {'accountUser'|'asset'|'asset-archive'|'asset-asset'|'asset-audio'|'asset-block'|'asset-code'|'asset-document'|'asset-image'|'asset-message'|'asset-other'|'asset-rawimage'|'asset-template'|'asset-textfile'|'asset-video'|'attributeGroup'|'automation'|'campaign'|'contentArea'|'dataExtension'|'dataExtensionField'|'dataExtensionTemplate'|'dataExtract'|'dataExtractType'|'discovery'|'email'|'emailSendDefinition'|'eventDefinition'|'fileTransfer'|'filter'|'folder'|'ftpLocation'|'importFile'|'interaction'|'list'|'mobileCode'|'mobileKeyword'|'query'|'role'|'script'|'setDefinition'|'triggeredSendDefinition'} SupportedMetadataTypes
+ * @typedef {Object.<SupportedMetadataTypes, string[]>} TypeKeyCombo object-key=metadata type, value=array of external keys
  */
 
 /**