mcdev 7.0.4 → 7.1.0

package/lib/metadataTypes/Asset.js

@@ -19,6 +19,7 @@ import ReplaceCbReference from '../util/replaceContentBlockReference.js';
  * @typedef {import('../../types/mcdev.d.js').MetadataTypeMap} MetadataTypeMap
  * @typedef {import('../../types/mcdev.d.js').SoapRequestParams} SoapRequestParams
  * @typedef {import('../../types/mcdev.d.js').TemplateMap} TemplateMap
+ * @typedef {import('../../types/mcdev.d.js').TypeKeyCombo} TypeKeyCombo
  */
 /**
  * @typedef {import('../../types/mcdev.d.js').AssetSubType} AssetSubType
@@ -58,11 +59,40 @@ class Asset extends MetadataType {
         if (retrieveDir) {
             await File.initPrettier();
         }
-        // loop through subtypes and return results of each subType for caching (saving is handled per subtype)
-        for (const subType of subTypeArr) {
-            // each subtype contains multiple different specific types (images contains jpg and png for example)
-            // we use await here to limit the risk of too many concurrent api requests at time
-            items.push(...(await this.requestSubType(subType, retrieveDir, key, null, loadShared)));
+        if (retrieveDir && !cache.getCache()?.asset) {
+            // cache this for 3 reasons:
+            //  1) subtypes asset, message and template reference other content blocks by id/key/objectId as part of their views
+            //  2) subtype message references a template if it is template-based
+            //  3) all non-binary subtypes support ampscript / ssjs which can load otherc content blocks via ContentBlockyByX()
+
+            Util.logger.info(' - Caching dependent Metadata: asset');
+            const resultLocal = await this.retrieveForCache(
+                undefined,
+                this.definition.selflinkedSubTypes,
+                undefined,
+                false
+            );
+            cache.mergeMetadata('asset', resultLocal.metadata);
+            Util.logger.info(' - Caching dependent Metadata: shared asset');
+            const resultShared = await this.retrieveForCache(
+                undefined,
+                this.definition.selflinkedSubTypes,
+                undefined,
+                true
+            );
+            cache.mergeMetadata('asset', resultShared.metadata);
+        }
+        if (retrieveDir) {
+            // loop through subtypes and return results of each subType for caching (saving is handled per subtype)
+            for (const subType of subTypeArr) {
+                // each subtype contains multiple different specific types (images contains jpg and png for example)
+                // we use await here to limit the risk of too many concurrent api requests at time
+                items.push(
+                    ...(await this.requestSubType(subType, retrieveDir, key, null, loadShared))
+                );
+            }
+        } else {
+            items.push(...(await this.requestSubType(subTypeArr, null, key, null, loadShared)));
         }
         const metadata = this.parseResponseBody({ items: items });
         if (retrieveDir) {
@@ -73,44 +103,6 @@ class Asset extends MetadataType {
         }
         return { metadata: metadata, type: this.definition.type };
     }
-    /**
-     * Helper for writing Metadata to disk, used for Retrieve and deploy
-     *
-     * @param {MetadataTypeMap} results metadata results from deploy
-     * @param {string} retrieveDir directory where metadata should be stored after deploy/retrieve
-     * @param {string} [overrideType] for use when there is a subtype (such as folder-queries)
-     * @param {TemplateMap} [templateVariables] variables to be replaced in the metadata
-     * @returns {Promise.<MetadataTypeMap>} Promise of saved metadata
-     */
-    static async saveResults(results, retrieveDir, overrideType, templateVariables) {
-        if (Object.keys(results).length) {
-            // only execute the following if records were found
-            await this._postRetrieveTasksBulk(results);
-        }
-        return super.saveResults(results, retrieveDir, overrideType, templateVariables);
-    }
-    /**
-     * helper for Journey's {@link Asset.saveResults}. Gets executed after retreive of metadata type and
-     *
-     * @param {MetadataTypeMap} metadataMap key=customer key, value=metadata
-     */
-    static async _postRetrieveTasksBulk(metadataMap) {
-        // Template-Based Email
-        let needTemplates = false;
-        for (const key in metadataMap) {
-            if (metadataMap[key].assetType.name == 'templatebasedemail') {
-                needTemplates = true;
-                break;
-            }
-        }
-
-        if (needTemplates && !cache.getCache()?.asset) {
-            // for
-            Util.logger.info(' - Caching dependent Metadata: asset-template');
-            const result = await this.retrieveForCache(undefined, ['template']);
-            cache.setMetadata('asset', result.metadata);
-        }
-    }
 
     /**
      * Retrieves asset metadata for caching
@@ -207,7 +199,7 @@ class Asset extends MetadataType {
     /**
      * Retrieves Metadata of a specific asset type
      *
-     * @param {string} subType group of similar assets to put in a folder (ie. images)
+     * @param {string|string[]} subType group of similar assets to put in a folder (ie. images)
      * @param {string} [retrieveDir] target directory for saving assets
      * @param {string} [key] key/id/name to filter by
      * @param {TemplateMap} [templateVariables] variables to be replaced in the metadata
@@ -215,15 +207,29 @@ class Asset extends MetadataType {
      * @returns {Promise.<object[]>} Promise
      */
     static async requestSubType(subType, retrieveDir, key, templateVariables, loadShared = false) {
+        const subTypeArr = Array.isArray(subType) ? subType : [subType];
         if (retrieveDir) {
-            Util.logger.info(`- Retrieving Subtype: ${subType}`);
+            if (Array.isArray(subType)) {
+                throw new TypeError(
+                    'requestSubType should not be called with multiple subtypes when retrieving to disk.'
+                );
+            } else {
+                Util.logger.info(`- Retrieving Subtype: ${subType}`);
+            }
         } else {
-            Util.logger.info(` - Caching Subtype: ${subType}`);
+            // in this mode we can accept arrays because we don't need to save this to a subtype folder but just want the records
+            Util.logSubtypes(subTypeArr);
         }
         /** @type {AssetSubType[]} */
-        const extendedSubTypeArr = this.definition.extendedSubTypes[subType];
-        const subtypeIds = extendedSubTypeArr?.map(
-            (subTypeItemName) => Asset.definition.typeMapping[subTypeItemName]
+        const extendedSubTypeArr = subTypeArr.flatMap(
+            (subType) => this.definition.extendedSubTypes[subType]
+        );
+        // the API can only assetType.ids at a time or else will throw: "DbUtility.GetPagedCollection passing through non-timeout DB error (30001)"
+        const subtypeIdsList = Util.chunk(
+            extendedSubTypeArr?.map(
+                (subTypeItemName) => this.definition.typeMapping[subTypeItemName]
+            ),
+            50
         );
         const uri = '/asset/v1/content/assets/query' + (loadShared ? '?scope=shared' : '');
         /** @type {AssetRequestParams} */
@@ -233,46 +239,15 @@ class Asset extends MetadataType {
                 pageSize: 50,
             },
             query: null,
-            fields: ['category', 'createdDate', 'createdBy', 'modifiedDate', 'modifiedBy'], // get folder to allow duplicate name check against cache
+            fields: [
+                'category',
+                'createdDate',
+                'createdBy',
+                'modifiedDate',
+                'modifiedBy',
+                'objectID',
+            ], // get folder to allow duplicate name check against cache
         };
-
-        if (key) {
-            payload.query = {
-                leftOperand: {
-                    property: 'assetType.id',
-                    simpleOperator: 'in',
-                    value: subtypeIds,
-                },
-                logicalOperator: 'AND',
-            };
-            if (key.startsWith('id:')) {
-                payload.query.rightOperand = {
-                    property: this.definition.idField,
-                    simpleOperator: 'equal',
-                    value: key.slice(3),
-                };
-            } else if (key.startsWith('name:')) {
-                payload.query.rightOperand = {
-                    property: this.definition.nameField,
-                    simpleOperator: 'equal',
-                    value: key.slice(5),
-                };
-            } else {
-                payload.query.rightOperand = {
-                    property: this.definition.keyField,
-                    simpleOperator: 'equal',
-                    value: key,
-                };
-            }
-        } else {
-            payload.query = {
-                property: 'assetType.id',
-                simpleOperator: 'in',
-                value: subtypeIds,
-            };
-            payload.sort = [{ property: 'id', direction: 'ASC' }];
-        }
-        // for caching we do not need these fields
         if (retrieveDir) {
             payload.fields = [
                 'fileProperties',
@@ -287,21 +262,11 @@ class Asset extends MetadataType {
                 'tags',
             ];
         }
-        let moreResults = false;
-        let lastPage = 0;
+
         let items = [];
-        do {
-            payload.page.page = lastPage + 1;
-            const response = await this.client.rest.post(uri, payload);
-            if (response?.items?.length) {
-                // sometimes the api will return a payload without items
-                // --> ensure we only add proper items-arrays here
-                items = items.concat(response.items);
-            }
-            // check if any more records
-            if (response?.message?.includes('all shards failed')) {
-                // When running certain filters, there is a limit of 10k on ElastiCache.
-                // Since we sort by ID, we can get the last ID then run new requests from there
+
+        for (const subtypeIds of subtypeIdsList) {
+            if (key) {
                 payload.query = {
                     leftOperand: {
                         property: 'assetType.id',
@@ -309,24 +274,75 @@ class Asset extends MetadataType {
                         value: subtypeIds,
                     },
                     logicalOperator: 'AND',
-                    rightOperand: {
-                        property: 'id',
-                        simpleOperator: 'greaterThan',
-                        value: items.at(-1).id,
-                    },
                 };
-                lastPage = 0;
-                moreResults = true;
-            } else if (response.page * response.pageSize < response.count) {
-                moreResults = true;
-                lastPage = Number(response.page);
+                if (key.startsWith('id:')) {
+                    payload.query.rightOperand = {
+                        property: this.definition.idField,
+                        simpleOperator: 'equal',
+                        value: key.slice(3),
+                    };
+                } else if (key.startsWith('name:')) {
+                    payload.query.rightOperand = {
+                        property: this.definition.nameField,
+                        simpleOperator: 'equal',
+                        value: key.slice(5),
+                    };
+                } else {
+                    payload.query.rightOperand = {
+                        property: this.definition.keyField,
+                        simpleOperator: 'equal',
+                        value: key,
+                    };
+                }
             } else {
-                moreResults = false;
+                payload.query = {
+                    property: 'assetType.id',
+                    simpleOperator: 'in',
+                    value: subtypeIds,
+                };
+                // payload.sort = [{ property: 'id', direction: 'ASC' }];
             }
-        } while (moreResults);
+            // for caching we do not need these fields
+            let moreResults = false;
+            let lastPage = 0;
+            do {
+                payload.page.page = lastPage + 1;
+                const response = await this.client.rest.post(uri, payload);
+                if (response?.items?.length) {
+                    // sometimes the api will return a payload without items
+                    // --> ensure we only add proper items-arrays here
+                    items = items.concat(response.items);
+                }
+                // check if any more records
+                if (response?.message?.includes('all shards failed')) {
+                    // When running certain filters, there is a limit of 10k on ElastiCache.
+                    // Since we sort by ID, we can get the last ID then run new requests from there
+                    payload.query = {
+                        leftOperand: {
+                            property: 'assetType.id',
+                            simpleOperator: 'in',
+                            value: subtypeIds,
+                        },
+                        logicalOperator: 'AND',
+                        rightOperand: {
+                            property: 'id',
+                            simpleOperator: 'greaterThan',
+                            value: items.at(-1).id,
+                        },
+                    };
+                    lastPage = 0;
+                    moreResults = true;
+                } else if (response.page * response.pageSize < response.count) {
+                    moreResults = true;
+                    lastPage = Number(response.page);
+                } else {
+                    moreResults = false;
+                }
+            } while (moreResults);
+        }
 
         // only when we save results do we need the complete metadata or files. caching can skip these
-        if (retrieveDir) {
+        if (retrieveDir && !Array.isArray(subType)) {
             if (items.length > 0) {
                 for (const item of items) {
                     if (item.customerKey.trim() !== item.customerKey) {
@@ -344,10 +360,7 @@ class Asset extends MetadataType {
             Util.logger.info(`  Downloaded asset-${subType}: ${items.length}`);
         }
 
-        return items.map((item) => {
-            item._subType = subType;
-            return item;
-        });
+        return items;
     }
     /**
      * Retrieves extended metadata (files or extended content) of asset
@@ -389,6 +402,8 @@ class Asset extends MetadataType {
                 const promiseMap = await Promise.all(
                     items.map((item, index) =>
                         rateLimit(async () => {
+                            const metadataMapSaveSingle = {};
+
                             // this is a file so extended is at another endpoint
                             if (item?.fileProperties?.extension && !completed.includes(item.id)) {
                                 try {
@@ -397,8 +412,10 @@ class Asset extends MetadataType {
                                 } catch (ex) {
                                     failed.push({ item: item, error: ex });
                                 }
-                                // even if the extended file failed, still save the metadata
+                                // still return even if extended failed
                                 metadataMap[item.customerKey] = item;
+                                // even if the extended file failed, still save the metadata
+                                metadataMapSaveSingle[item.customerKey] = item;
                             }
                             // this is a complex type which stores data in the asset itself
                             else if (!completed.includes(item.id)) {
@@ -406,8 +423,10 @@ class Asset extends MetadataType {
                                     const extendedItem = await this.client.rest.get(
                                         'asset/v1/content/assets/' + item.id
                                     );
-                                    // only save the metadata if we have extended content
+                                    // only return the metadata if we have extended content
                                     metadataMap[item.customerKey] = extendedItem;
+                                    // only save the metadata if we have extended content
+                                    metadataMapSaveSingle[item.customerKey] = extendedItem;
                                     // overwrite the original item with the extended content to ensure retrieve() returns it
                                     items[index] = extendedItem;
                                 } catch (ex) {
@@ -415,9 +434,9 @@ class Asset extends MetadataType {
                                 }
                             }
                             completed.push(item.id);
-                            if (metadataMap[item.customerKey]) {
+                            if (metadataMapSaveSingle[item.customerKey]) {
                                 await this.saveResults(
-                                    metadataMap,
+                                    metadataMapSaveSingle,
                                     retrieveDir,
                                     'asset-' + subType,
                                     templateVariables
@@ -730,6 +749,9 @@ class Asset extends MetadataType {
         // define asset's subtype
         const subType = this._getSubtype(metadata);
 
+        // #0 format blocks in slots for deployment
+        await this._preDeployTasksBocks(metadata);
+
         // #1 get text extracts back into the JSON
         await this._mergeCode(metadata, deployDir, subType);
 
@@ -738,7 +760,7 @@ class Asset extends MetadataType {
 
         // only execute #3 if we are deploying / copying from one BU to another, not while using mcdev as a developer tool
         if (
-            !Util.OPTIONS.noMidSuffix &&
+            Util.OPTIONS.autoMidSuffix &&
             this.buObject.mid &&
             metadata.memberId != this.buObject.mid && // soft comparison to accomodate for string-version of mid
             !metadata[this.definition.keyField].endsWith(this.buObject.mid)
@@ -928,9 +950,17 @@ class Asset extends MetadataType {
                     }: ${extractedFile.fileName}.${extractedFile.fileExt}.`
                 );
             }
+
+            // apply templating to subfolders
             extractedFile.subFolder = extractedFile.subFolder
                 .map((el) => (el === templateName ? metadata[this.definition.keyField] : el))
                 .map((el) => this.applyTemplateValues(el, templateVariables));
+
+            // apply templating to filenames of extracted code
+            extractedFile.fileName = extractedFile.fileName
+                .split('.')
+                .map((el) => (el === templateName ? metadata[this.definition.keyField] : el))
+                .join('.');
         }
 
         // #2 binary extracts
@@ -1017,11 +1047,83 @@ class Asset extends MetadataType {
             );
         }
         metadata.category = {
-            id: cache.searchForField('folder', metadata.r__folder_Path, 'Path', 'ID'),
+            id: cache.getFolderId(metadata.r__folder_Path),
         };
         delete metadata.r__folder_Path;
     }
 
+    /**
+     * helper for {@link Asset.preDeployTasks} that loads extracted code content back into JSON
+     *
+     * @param {AssetItem} metadata a single asset definition
+     * @returns {Promise.<void>} fileList for templating (disregarded during deployment)
+     */
+    static async _preDeployTasksBocks(metadata) {
+        switch (metadata.assetType.name) {
+            case 'templatebasedemail': // message
+            case 'htmlemail':
+            case 'webpage': {
+                // metadata.views.html.slots.<>.blocks.<>.content (optional)
+                if (metadata?.views?.html?.slots) {
+                    await this._preDeployTasksBocks_slots(metadata.views.html.slots);
+                }
+                break;
+            }
+            case 'template': {
+                // metadata.slots.<>.blocks.<>.content (optional)
+                if (metadata?.slots) {
+                    await this._preDeployTasksBocks_slots(metadata.slots);
+                }
+
+                break;
+            }
+        }
+    }
+    /**
+     * helper for {@link Asset.preDeployTasks} that loads extracted code content back into JSON
+     *
+     * @param {object} metadataSlots metadata.views.html.slots or deeper slots.<>.blocks.<>.slots
+     * @returns {Promise.<void>} -
+     */
+    static async _preDeployTasksBocks_slots(metadataSlots) {
+        for (const slot in metadataSlots) {
+            if (Object.prototype.hasOwnProperty.call(metadataSlots, slot)) {
+                const slotObj = metadataSlots[slot];
+                // found slot
+                if (slotObj.blocks) {
+                    for (const block in slotObj.blocks) {
+                        if (Object.prototype.hasOwnProperty.call(slotObj.blocks, block)) {
+                            const asset = slotObj.blocks[block];
+                            if (asset.r__asset_key) {
+                                // by only running the following if r__asset_key was set, we simply skip anything that wasnt resolved during retrieve
+                                asset.customerKey = asset.r__asset_key;
+                                asset.id = cache.searchForField(
+                                    'asset',
+                                    asset.r__asset_key,
+                                    'customerKey',
+                                    'id'
+                                );
+                                asset.objectID = cache.searchForField(
+                                    'asset',
+                                    asset.r__asset_key,
+                                    'customerKey',
+                                    'objectID'
+                                );
+                                delete asset.r__asset_key;
+                                asset.thumbnail = {
+                                    thumbnailUrl: '/v1/assets/' + asset.id + '/thumbnail',
+                                };
+
+                                this.setFolderId(asset);
+                            }
+                            await this._preDeployTasksBocks(asset);
+                        }
+                    }
+                }
+            }
+        }
+    }
+
     /**
      * helper for {@link Asset.preDeployTasks} that loads extracted code content back into JSON
      *
@@ -1406,6 +1508,7 @@ class Asset extends MetadataType {
                 if (slotObj.blocks) {
                     for (const block in slotObj.blocks) {
                         if (Object.prototype.hasOwnProperty.call(slotObj.blocks, block)) {
+                            const asset = slotObj.blocks[block];
                             const fileName = `${prefix}.[${slot}-${block}]${subtypeExtension}`;
                             if (
                                 await File.pathExists(
@@ -1419,7 +1522,7 @@ class Asset extends MetadataType {
                                 // the main content can be empty (=not set up yet) hence check if we did extract sth or else readFile() will print error msgs
                                 // if an extracted block was found, save it back into JSON
                                 if (!fileListOnly) {
-                                    slotObj.blocks[block].content = await File.readFilteredFilename(
+                                    asset.content = await File.readFilteredFilename(
                                         [...readDirArr, 'blocks'],
                                         fileName,
                                         'html'
@@ -1431,21 +1534,35 @@ class Asset extends MetadataType {
                                         subFolder: [...subDirArr, templateFileName, 'blocks'],
                                         fileName: fileName,
                                         fileExt: 'html',
-                                        content: slotObj.blocks[block].content,
+                                        content: asset.content,
                                     });
                                 }
                             }
-                            if (slotObj.blocks[block].slots) {
+                            if (asset.slots) {
                                 // * recursion: each block can have slots of its own
                                 await this._mergeCode_slots(
                                     `${prefix}.[${slot}-${block}]`,
-                                    slotObj.blocks[block].slots,
+                                    asset.slots,
                                     readDirArr,
                                     subtypeExtension,
                                     subDirArr,
                                     fileList,
                                     customerKey,
-                                    templateName
+                                    templateName,
+                                    fileListOnly
+                                );
+                            } else if (asset?.views?.html?.slots) {
+                                // * recursion: each block can have slots of its own
+                                await this._mergeCode_slots(
+                                    `${prefix}.[${slot}-${block}]`,
+                                    asset.views.html.slots,
+                                    readDirArr,
+                                    subtypeExtension,
+                                    subDirArr,
+                                    fileList,
+                                    customerKey,
+                                    templateName,
+                                    fileListOnly
                                 );
                             }
                         }
@@ -1635,6 +1752,8 @@ class Asset extends MetadataType {
         }
     }
     /**
+     * helper for {@link Asset.postRetrieveTasks} via {@link Asset._extractCode}
+     *
      * @param {string} prefix usually the customerkey
      * @param {object} metadataSlots metadata.views.html.slots or deeper slots.<>.blocks.<>.slots
      * @param {object[]} codeArr to be extended array for extracted code
@@ -1647,22 +1766,47 @@ class Asset extends MetadataType {
                 // found slot
                 for (const block in slotObj.blocks) {
                     if (Object.prototype.hasOwnProperty.call(slotObj.blocks, block)) {
-                        if (slotObj.blocks[block].content) {
+                        const asset = slotObj.blocks[block];
+                        if (asset.content) {
                             // found content block
-                            const code = slotObj.blocks[block].content;
+                            const code = asset.content;
                             codeArr.push({
                                 subFolder: ['blocks'],
                                 fileName: `${prefix}.[${slot}-${block}]`,
                                 fileExt: 'html',
                                 content: code,
                             });
-                            delete slotObj.blocks[block].content;
+                            delete asset.content;
+                        }
+                        // clean up fields from the other content block
+                        if (asset.id) {
+                            try {
+                                asset.r__asset_key = cache.searchForField(
+                                    'asset',
+                                    asset.id,
+                                    'id',
+                                    'customerKey'
+                                );
+                                // only delete this if we found the asset in cache, otherwise ignore
+                                delete asset.id;
+                                delete asset.objectID;
+                                delete asset.customerKey;
+                                delete asset.thumbnail;
+                            } catch {
+                                Util.logger.debug(
+                                    ` - asset id:${asset.id} / key:${asset.customerKey} / name:${asset.name} not found in cache`
+                                );
+                            }
                         }
-                        if (slotObj.blocks[block].slots) {
+                        if (asset.category?.id) {
+                            this.setFolderPath(asset);
+                        }
+
+                        if (asset.slots) {
                             // * recursion: each block can have slots of its own
                             this._extractCode_slots(
                                 `${prefix}.[${slot}-${block}]`,
-                                slotObj.blocks[block].slots,
+                                asset.slots,
                                 codeArr
                             );
                         }
@@ -1674,9 +1818,9 @@ class Asset extends MetadataType {
     /**
      * Returns file contents mapped to their fileName without '.json' ending
      *
-     * @param {string} dir directory that contains '.json' files to be read
-     * @param {boolean} _ unused parameter
-     * @param {string[]} selectedSubType asset, message, ...
+     * @param {string} dir directory with json files, e.g. /retrieve/cred/bu/asset, /deploy/cred/bu/asset, /template/asset
+     * @param {boolean} [_] unused parameter
+     * @param {string[]} [selectedSubType] asset, message, ...
      * @returns {Promise.<MetadataTypeMap>} fileName => fileContent map
      */
     static async getJsonFromFS(dir, _, selectedSubType) {
@@ -1691,46 +1835,7 @@ class Asset extends MetadataType {
                     continue;
                 }
                 const currentdir = File.normalizePath([dir, subtype]);
-                if (await File.pathExists(currentdir)) {
-                    const files = await File.readdir(currentdir, { withFileTypes: true });
-
-                    for (const dirent of files) {
-                        try {
-                            let thisDir = currentdir;
-                            let fileName = dirent.name;
-                            if (dirent.isDirectory()) {
-                                // complex types with more than one extracted piece of code are saved in their
-                                // own subfolder (with folder name = CustomerKey)
-                                // this section aims to find that json in the subfolder
-                                const subfolderFiles = await File.readdir(
-                                    File.normalizePath([currentdir, dirent.name])
-                                );
-                                for (const subFileName of subfolderFiles) {
-                                    if (subFileName.endsWith('-meta.json')) {
-                                        fileName = subFileName;
-                                        thisDir = File.normalizePath([currentdir, dirent.name]);
-                                    }
-                                }
-                            }
-                            if (fileName.endsWith('-meta.json')) {
-                                const fileContent = await File.readJSONFile(
-                                    thisDir,
-                                    fileName,
-                                    false
-                                );
-                                // subtype will change the metadata suffix length
-                                const fileNameWithoutEnding = fileName.slice(
-                                    0,
-                                    -17 - subtype.length
-                                );
-                                fileName2FileContent[fileNameWithoutEnding] = fileContent;
-                            }
-                        } catch (ex) {
-                            // by catching this in the loop we gracefully handle the issue and move on to the next file
-                            Util.metadataLogger('debug', this.definition.type, 'getJsonFromFS', ex);
-                        }
-                    }
-                }
+                await this._getJsonFromFS(currentdir, subtype, fileName2FileContent);
             }
         } catch (ex) {
             // this will catch issues with readdir
@@ -1739,6 +1844,41 @@ class Asset extends MetadataType {
         }
         return fileName2FileContent;
     }
+    /**
+     * helper for {@link Asset.getJsonFromFS} that reads the file system for metadata files
+     *
+     * @param {string} currentdir directory to scan
+     * @param {string} subtype single subtype of asset
+     * @param {MetadataTypeMap} fileName2FileContent fileName => fileContent map
+     */
+    static async _getJsonFromFS(currentdir, subtype, fileName2FileContent) {
+        if (await File.pathExists(currentdir)) {
+            const fileEnding = `.asset-${subtype}-meta.json`;
+            const fileEndingLength = fileEnding.length;
+            const files = await File.readdir(currentdir, { withFileTypes: true });
+            for (const dirent of files) {
+                const fileName = dirent.name;
+                try {
+                    if (dirent.isDirectory()) {
+                        await this._getJsonFromFS(
+                            File.normalizePath([currentdir, fileName]),
+                            subtype,
+                            fileName2FileContent
+                        );
+                    } else if (fileName.endsWith(fileEnding)) {
+                        const fileContent = await File.readJSONFile(currentdir, fileName, false);
+                        // subtype will change the metadata suffix length
+                        const fileNameWithoutEnding = fileName.slice(0, -fileEndingLength);
+                        fileName2FileContent[fileNameWithoutEnding] = fileContent;
+                    }
+                } catch (ex) {
+                    // by catching this in the loop we gracefully handle the issue and move on to the next file
+                    Util.metadataLogger('debug', this.definition.type, 'getJsonFromFS', ex);
+                }
+            }
+        }
+    }
+
     /**
      * check template directory for complex types that open subfolders for their subtypes
      *
@@ -2058,7 +2198,7 @@ class Asset extends MetadataType {
                 }
                 if (json.sharedWith && Array.isArray(json.sharedWith)) {
                     Util.logger.warn(
-                        `          with: ${json.sharedWith
+                        ` - Shared with: ${json.sharedWith
                             .map(
                                 (mid) =>
                                     Util.inverseGet(
@@ -2169,9 +2309,10 @@ class Asset extends MetadataType {
      *
      * @param {MetadataTypeItem} item single metadata item
      * @param {string} retrieveDir directory where metadata is saved
+     * @param {Set.<string>} [findAssetKeys] list of keys that were found referenced via ContentBlockByX; if set, method only gets keys and runs no updates
      * @returns {Promise.<MetadataTypeItem>} key of the item that was updated
      */
-    static async replaceCbReference(item, retrieveDir) {
+    static async replaceCbReference(item, retrieveDir, findAssetKeys) {
         const responseItem = structuredClone(item);
         const parentName = `${this.definition.type} ${item[this.definition.keyField]}`;
         let changes = false;
@@ -2190,7 +2331,11 @@ class Asset extends MetadataType {
         const fileListChanged = [];
         for (const file of fileList) {
             try {
-                file.content = ReplaceCbReference.replaceReference(file.content, parentName);
+                file.content = ReplaceCbReference.replaceReference(
+                    file.content,
+                    parentName,
+                    findAssetKeys
+                );
                 changes = true;
                 fileListChanged.push(file);
             } catch (ex) {
@@ -2199,16 +2344,17 @@ class Asset extends MetadataType {
                 }
             }
         }
-
-        // save what was changed regardless of other errors
-        for (const extractedFile of fileListChanged) {
-            File.writeToFile(
-                [retrieveDir, ...extractedFile.subFolder],
-                extractedFile.fileName,
-                extractedFile.fileExt,
-                extractedFile.content,
-                extractedFile.encoding || null
-            );
+        if (!findAssetKeys) {
+            // save what was changed regardless of other errors
+            for (const extractedFile of fileListChanged) {
+                File.writeToFile(
+                    [retrieveDir, ...extractedFile.subFolder],
+                    extractedFile.fileName,
+                    extractedFile.fileExt,
+                    extractedFile.content,
+                    extractedFile.encoding || null
+                );
+            }
         }
 
         if (error) {
@@ -2217,7 +2363,7 @@ class Asset extends MetadataType {
 
         if (!changes) {
             const ex = new Error('No changes made to the code.');
-            // @ts-expect-error TODO: create custom Error object
+            // @ts-expect-error custom error object
             ex.code = 200;
             throw ex;
         }
@@ -2232,9 +2378,10 @@ class Asset extends MetadataType {
      *
      * @param {MetadataTypeMap} metadataMap list of metadata (keyField => metadata)
      * @param {string} retrieveDir retrieve dir including cred and bu
+     * @param {Set.<string>} [findAssetKeys] list of keys that were found referenced via ContentBlockByX; if set, method only gets keys and runs no updates
      * @returns {Promise.<string[]>} Returns list of keys for which references were replaced
      */
-    static async replaceCbReferenceLoop(metadataMap, retrieveDir) {
+    static async replaceCbReferenceLoop(metadataMap, retrieveDir, findAssetKeys) {
         const keysForDeploy = [];
         if (!metadataMap) {
             // if a type was skipped e.g. because it shall only be looked at on the parent then we would expect metadataMap to be undefined
@@ -2246,8 +2393,7 @@ class Asset extends MetadataType {
             .join(' and ');
 
         if (Object.keys(metadataMap).length) {
-            Util.logger.info(`Searching ${this.definition.type} for ${fromDescription}:`);
-            // const baseDir = [retrieveDir, ...this.definition.type.split('-')];
+            Util.logger.debug(` - Searching in ${this.definition.type} `);
             const deployMap = {};
 
             for (const key in metadataMap) {
@@ -2260,34 +2406,133 @@ class Asset extends MetadataType {
 
                 try {
                     // add key but make sure to turn it into string or else numeric keys will be filtered later
-                    deployMap[key] = await this.replaceCbReference(item, retrieveDir);
+                    deployMap[key] = await this.replaceCbReference(
+                        item,
+                        retrieveDir,
+                        findAssetKeys
+                    );
 
                     // ! this method is equal to the super version except that it does not run saveToDisk here
                     // await this.saveToDisk(deployMap, key, baseDir);
-
-                    keysForDeploy.push(key + '');
-                    Util.logger.info(` - added ${this.definition.type} to update queue: ${key}`);
+                    if (findAssetKeys) {
+                        keysForDeploy.push(...[...findAssetKeys].map((key) => key + ''));
+                    } else {
+                        keysForDeploy.push(key + '');
+                        Util.logger.info(
+                            ` - added ${this.definition.type} to update queue: ${key}`
+                        );
+                    }
                 } catch (ex) {
                     if (ex.code !== 200) {
                         // dont print error if we simply did not find relevant content blocks
                         Util.logger.errorStack(ex, ex.message);
                     }
-                    Util.logger.info(
-                        Util.getGrayMsg(
-                            ` ☇ skipping ${this.definition.type} ${
-                                item[this.definition.keyField]
-                            }: no ${fromDescription} found`
-                        )
-                    );
+                    if (!findAssetKeys) {
+                        Util.logger.info(
+                            Util.getGrayMsg(
+                                ` ☇ skipping ${this.definition.type} ${
+                                    item[this.definition.keyField]
+                                }: no ${fromDescription} found`
+                            )
+                        );
+                    }
                 }
             }
-
-            Util.logger.info(
-                `Found ${keysForDeploy.length} ${this.definition.type}${keysForDeploy.length === 1 ? '' : 's'} to update`
-            );
+            if (!findAssetKeys) {
+                Util.logger.info(
+                    `Found ${keysForDeploy.length} ${this.definition.type}${keysForDeploy.length === 1 ? '' : 's'} to update`
+                );
+            }
         }
         return keysForDeploy;
     }
+    /**
+     *
+     * @param {string[]} keyArr limit retrieval to given metadata type
+     * @param {string} retrieveDir retrieve dir including cred and bu
+     * @param {Set.<string>} findAssetKeys list of keys that were found referenced via ContentBlockByX; if set, method only gets keys and runs no updates
+     * @returns {Promise.<Set.<string>>} found asset keys
+     */
+    static async getCbReferenceKeys(keyArr, retrieveDir, findAssetKeys) {
+        if (!Object.prototype.hasOwnProperty.call(this, 'replaceCbReference')) {
+            // only types that have a replaceCbReference method actually have ampscript/ssjs
+            return;
+        }
+        if (!this.getJsonFromFSCache) {
+            // avoid re-reading the same files in every recursive iteration
+            this.getJsonFromFSCache = await this.getJsonFromFS(
+                File.normalizePath([retrieveDir, this.definition.type])
+            );
+        }
+        // get all metadata of the current type; then filter by keys in selectedTypes
+        const metadataMap = Util.filterObjByKeys(this.getJsonFromFSCache, [...findAssetKeys]);
+        const newKeysFound = new Set(
+            await this.replaceCbReferenceLoop(metadataMap, retrieveDir, findAssetKeys)
+        );
+        if (newKeysFound.size) {
+            const keysToCrawl = [];
+            for (const value of newKeysFound) {
+                if (!keyArr.includes(value)) {
+                    keyArr.push(value);
+                    keysToCrawl.push(value);
+                }
+            }
+            Util.logger.info(Util.getGrayMsg(` - asset: ${keysToCrawl.join(', ')}`));
+
+            if (keysToCrawl.length) {
+                findAssetKeys = new Set([
+                    ...findAssetKeys,
+                    ...(await this.getCbReferenceKeys(keyArr, retrieveDir, new Set(keysToCrawl))),
+                ]);
+            }
+        }
+        return findAssetKeys;
+    }
+
+    /**
+     * optional helper for {@link this.getDependentTypes}
+     *
+     * @param {object} metadataItem metadata json read from filesystem
+     * @param {TypeKeyCombo} dependentTypeKeyCombo list started in this.getDependentTypes
+     */
+    static getDependentFilesExtra(metadataItem, dependentTypeKeyCombo) {
+        const dependentKeyArr = [];
+        // search:
+        // - metadata.views.html.slots
+        // - metadata.slots
+        if (metadataItem.views?.html?.slots) {
+            this._getDependentFilesExtra(metadataItem.views.html.slots, dependentKeyArr);
+        }
+        if (metadataItem.slots) {
+            this._getDependentFilesExtra(metadataItem.slots, dependentKeyArr);
+        }
+        if (dependentKeyArr.length) {
+            dependentTypeKeyCombo.asset ||= [];
+            dependentTypeKeyCombo.asset.push(...dependentKeyArr);
+        }
+    }
+    /**
+     * @param {object} slots metadata.views.html.slots or deeper slots.<>.blocks.<>.slots
+     * @param {string[]} dependentKeyArr list of found keys
+     */
+    static _getDependentFilesExtra(slots, dependentKeyArr) {
+        for (const slot in slots) {
+            for (const block in slots[slot].blocks) {
+                const asset = slots[slot].blocks[block];
+                if (asset.r__asset_key) {
+                    dependentKeyArr.push(asset.r__asset_key);
+                }
+                if (asset.views?.html?.slots) {
+                    // * recursion: each block can have slots of its own
+                    this._getDependentFilesExtra(asset.views.html.slots, dependentKeyArr);
+                }
+                if (asset.slots) {
+                    // * recursion: each block can have slots of its own
+                    this._getDependentFilesExtra(asset.slots, dependentKeyArr);
+                }
+            }
+        }
+    }
 }
 
 // Assign definition to static attributes