mcdev 9.0.3 → 10.0.0

package/lib/metadataTypes/Asset.js

@@ -4,12 +4,12 @@ import MetadataType from './MetadataType.js';
 import { Util } from '../util/util.js';
 import File from '../util/file.js';
 import pLimit from 'p-limit';
-import cliProgress from 'cli-progress';
+import { ProgressBar } from '../util/progress.js';
 import cache from '../util/cache.js';
 import TriggeredSend from './TriggeredSend.js';
 import Folder from './Folder.js';
 import ReplaceCbReference from '../util/replaceContentBlockReference.js';
-import toposort from 'toposort';
+import { topologicalSort } from '../util/topological-sort.js';
 
 /**
  * @typedef {import('../../types/mcdev.d.js').BuObject} BuObject
@@ -17,6 +17,7 @@ import toposort from 'toposort';
  * @typedef {import('../../types/mcdev.d.js').CodeExtractItem} CodeExtractItem
  * @typedef {import('../../types/mcdev.d.js').MetadataTypeItem} MetadataTypeItem
  * @typedef {import('../../types/mcdev.d.js').MetadataTypeItemDiff} MetadataTypeItemDiff
+ * @typedef {import('../../types/mcdev.d.js').MetadataTypeItemObj} MetadataTypeItemObj
  * @typedef {import('../../types/mcdev.d.js').MetadataTypeMap} MetadataTypeMap
  * @typedef {import('../../types/mcdev.d.js').SoapRequestParams} SoapRequestParams
  * @typedef {import('../../types/mcdev.d.js').TemplateMap} TemplateMap
@@ -64,8 +65,8 @@ class Asset extends MetadataType {
         }
         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
+            //  1) subtypes asset, email and template reference other content blocks by id/key/objectId as part of their views
+            //  2) subtype email 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');
@@ -88,11 +89,15 @@ class Asset extends MetadataType {
         if (retrieveDir) {
             if (key) {
                 // running post-delete tasks to clean up potential old files
-                await this.postDeleteTasks(key);
+                try {
+                    await this.postDeleteTasks(key);
+                } catch (ex) {
+                    Util.logger.warn(
+                        ` - asset ${key}: cleanup failed: ${ex.message}; manual deletion of stale extracted code files may be necessary`
+                    );
+                }
                 // retrieve by key/id/name
-                items.push(
-                    ...(await this.requestSubType(null, retrieveDir, key, null, loadShared))
-                );
+                items.push(...(await this.requestSubType(null, retrieveDir, key, loadShared)));
             } else {
                 // retrieve all
                 // loop through subtypes and return results of each subType for caching (saving is handled per subtype)
@@ -100,13 +105,13 @@ class Asset extends MetadataType {
                     // 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))
+                        ...(await this.requestSubType(subType, retrieveDir, key, loadShared))
                     );
                 }
             }
         } else {
             // caching
-            items.push(...(await this.requestSubType(subTypeArr, null, null, null, loadShared)));
+            items.push(...(await this.requestSubType(subTypeArr, null, null, loadShared)));
         }
         const metadata = this.parseResponseBody({ items: items });
         if (retrieveDir) {
@@ -132,44 +137,7 @@ class Asset extends MetadataType {
     }
 
     /**
-     * Retrieves asset metadata for templating
-     *
-     * @deprecated Use `retrieve` followed by `build` instead. `retrieveAsTemplate` will be removed in a future version.
-     * @param {string} templateDir Directory where retrieved metadata directory will be saved
-     * @param {string} name name of the metadata file
-     * @param {TemplateMap} templateVariables variables to be replaced in the metadata
-     * @param {AssetSubType} [selectedSubType] optionally limit to a single subtype
-     * @returns {Promise.<{metadata: AssetItem, type: string}>} Promise
-     */
-    static async retrieveAsTemplate(templateDir, name, templateVariables, selectedSubType) {
-        Util.logDeprecated('retrieveAsTemplate', `'retrieve' followed by 'build'`);
-        const items = [];
-        const subTypes = selectedSubType ? [selectedSubType] : this._getSubTypes();
-        await File.initPrettier();
-        // loop through subtypes and return results of each subType for caching (saving is handled per subtype)
-        for (const subType of subTypes) {
-            // 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,
-                    templateDir,
-                    'name:' + name,
-                    templateVariables
-                ))
-            );
-        }
-        const metadata = this.parseResponseBody({ items: items });
-        if (!Object.keys(metadata).length) {
-            Util.logger.error(`${this.definition.type} '${name}' not found on server.`);
-        }
-        Util.logger.info(`Downloaded: ${this.definition.type} (${Object.keys(metadata).length})`);
-
-        return { metadata: Object.values(metadata)[0], type: this.definition.type };
-    }
-
-    /**
-     * helper for {@link Asset.retrieve} + {@link Asset.retrieveAsTemplate}
+     * helper for {@link Asset.retrieve}
      *
      * @private
      * @returns {string[]} AssetSubType array
@@ -178,7 +146,7 @@ class Asset extends MetadataType {
         const selectedSubTypeArr = this.properties.metaDataTypes.retrieve.filter((type) =>
             type.startsWith('asset-')
         );
-        /* eslint-disable unicorn/prefer-ternary */
+
         if (
             this.properties.metaDataTypes.retrieve.includes('asset') ||
             !selectedSubTypeArr.length
@@ -188,7 +156,6 @@ class Asset extends MetadataType {
         } else {
             return selectedSubTypeArr.map((type) => type.replace('asset-', ''));
         }
-        /* eslint-enable unicorn/prefer-ternary */
     }
 
     /**
@@ -253,7 +220,7 @@ class Asset extends MetadataType {
         }
 
         // sort list & remove the undefined dependencies
-        const flatList = toposort(dependencies).filter((a) => !!a);
+        const flatList = topologicalSort(dependencies).filter((a) => !!a);
 
         /** @type {AssetMap} */
         const metadataTypeMapSorted = {};
@@ -304,7 +271,6 @@ class Asset extends MetadataType {
      * @returns {Promise} Promise
      */
     static create(metadata) {
-        delete metadata.businessUnitAvailability;
         const uri = '/asset/v1/content/assets/';
         return super.createREST(metadata, uri);
     }
@@ -345,17 +311,37 @@ class Asset extends MetadataType {
         return super.updateREST(metadata, uri);
     }
 
+    /**
+     * helper for {@link MetadataType.buildTemplate}
+     *
+     * @param {string} retrieveDir Directory where retrieved metadata directory is stored
+     * @param {string} templateDir Directory where metadata templates are stored
+     * @param {string} key name of the metadata file
+     * @param {TemplateMap} templateVariables variables to be replaced in the metadata
+     * @returns {Promise.<MetadataTypeItemObj>} single metadata
+     */
+    static async buildTemplate(retrieveDir, templateDir, key, templateVariables) {
+        if (Util.OPTIONS.shareAsset) {
+            this._toggleShareAssetTemplating(true);
+        }
+        const result = await super.buildTemplate(retrieveDir, templateDir, key, templateVariables);
+        if (Util.OPTIONS.shareAsset) {
+            // return values to normal
+            this._toggleShareAssetTemplating(false);
+        }
+        return result;
+    }
+
     /**
      * Retrieves Metadata of a specific asset type
      *
      * @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
      * @param {boolean} [loadShared] optionally retrieve assets from other BUs that were shared with the current
      * @returns {Promise.<object[]>} Promise
      */
-    static async requestSubType(subType, retrieveDir, key, templateVariables, loadShared = false) {
+    static async requestSubType(subType, retrieveDir, key, loadShared = false) {
         const subTypeArr = Array.isArray(subType) ? subType : [subType];
         if (retrieveDir) {
             if (Array.isArray(subType)) {
@@ -505,12 +491,7 @@ class Asset extends MetadataType {
                     }
                 }
                 // we have to wait on execution or it potentially causes memory reference issues when changing between BUs
-                downloadedItemsMap = await this.requestAndSaveExtended(
-                    items,
-                    subType,
-                    retrieveDir,
-                    templateVariables
-                );
+                downloadedItemsMap = await this.requestAndSaveExtended(items, subType, retrieveDir);
             }
             // always show the summary even if we already had the progress bar in the console
             Util.logger.info(
@@ -528,24 +509,20 @@ class Asset extends MetadataType {
      * @param {Array} items array of items to retrieve
      * @param {string} subType group of similar assets to put in a folder (ie. images)
      * @param {string} retrieveDir target directory for saving assets
-     * @param {TemplateMap} [templateVariables] variables to be replaced in the metadata
      * @returns {Promise.<MetadataTypeMap>} Promise
      */
-    static async requestAndSaveExtended(items, subType, retrieveDir, templateVariables) {
+    static async requestAndSaveExtended(items, subType, retrieveDir) {
         // disable CLI logs other than error while retrieving subtype
         const loggerLevelBak = Util.logger.level;
         if (loggerLevelBak !== 'error') {
             // disable logging to cli other than Errors
             Util.setLoggingLevel({ silent: true });
         }
-        const extendedBar = new cliProgress.SingleBar(
-            {
-                format:
-                    '                 Downloading [{bar}] {percentage}% | {value}/{total} | asset-' +
-                    subType,
-            },
-            cliProgress.Presets.shades_classic
-        );
+        const extendedBar = new ProgressBar({
+            format:
+                '                 Downloading [{bar}] {percentage}% | {value}/{total} | asset-' +
+                subType,
+        });
 
         const completed = [];
         const failed = [];
@@ -599,8 +576,7 @@ class Asset extends MetadataType {
                                 const savedItem = await this.saveResults(
                                     metadataMapSaveSingle,
                                     retrieveDir,
-                                    'asset-' + subType,
-                                    templateVariables
+                                    'asset-' + subType
                                 );
                                 if (!savedItem[item.customerKey]) {
                                     // filtered by like-option
@@ -682,7 +658,7 @@ class Asset extends MetadataType {
                         fail.error.endpoint
                             ? Util.getGrayMsg(
                                   ' - ' +
-                                      fail.error.endpoint.split('rest.marketingcloudapis.com')[1]
+                                      fail.error.endpoint.split('rest.marketingcloudapis.com', 2)[1]
                               )
                             : ''
                     }`
@@ -708,7 +684,7 @@ class Asset extends MetadataType {
 
         // 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];
+        const fileExt = metadata.fileProperties.extension.split(' ', 1)[0];
 
         File.writeToFile(
             [retrieveDir, this.definition.type, subType],
@@ -736,7 +712,7 @@ class Asset extends MetadataType {
         if (!metadata?.fileProperties?.extension) {
             return;
         }
-        const fileExt = metadata.fileProperties.extension.split(' ')[0];
+        const fileExt = metadata.fileProperties.extension.split(' ', 1)[0];
 
         const path = File.normalizePath([
             deployDir,
@@ -848,7 +824,7 @@ class Asset extends MetadataType {
         if (Util.OPTIONS.refresh) {
             if (createdUpdated.updated) {
                 // only run this if assets were updated. for created assets we do not expect
-                await this._refreshTriggeredSend(metadata);
+                await this.refresh(Object.keys(metadata));
             } else {
                 Util.logger.warn(
                     'You set the --refresh flag but no updated assets found. Skipping refresh of triggeredSendDefinitions.'
@@ -856,13 +832,147 @@ class Asset extends MetadataType {
             }
         }
     }
+    /**
+     * helper for {@link Asset}. finds active emails that reference the updated block
+     *
+     * @private
+     * @param {AssetMap[]} blocks block metadata
+     * @param {AssetMap} _foundEmails map of found emails
+     * @param {Set} _searchedKeys set of searched block keys
+     * @returns {Promise.<AssetMap[]>} - map of assets keyed by their keyField
+     */
+    static async _findEmailsUsingBlock(blocks, _foundEmails = {}, _searchedKeys = new Set()) {
+        const uri = '/asset/v1/content/assets/query';
+
+        // Mark all current blocks as searched
+        for (const block of blocks) {
+            _searchedKeys.add(block.customerKey);
+        }
+
+        /** @type {AssetRequestParams} */
+        const payload = {
+            page: { page: 1, pageSize: 50 },
+            sort: [{ property: 'id', direction: 'ASC' }],
+            // @ts-ignore
+            query: ['Key', 'Id', 'Name']
+                .map((by) => ({
+                    property: 'content',
+                    simpleOperator: 'mustContain',
+                    value: `ContentBlockBy${by}`,
+                }))
+                .reduce((acc, condition, index) => {
+                    if (index === 0) {
+                        return condition;
+                    }
+                    return { leftOperand: acc, logicalOperator: 'OR', rightOperand: condition };
+                }, null),
+        };
+
+        const dependencyQuery = payload.query;
+        let items = [];
+        let moreResults;
+        let lastPage = 0;
+        let cursor = 0;
+
+        try {
+            do {
+                payload.page.page = lastPage + 1;
+                const response = await this.client.rest.post(uri, payload);
+                // sometimes the api will return a payload without items
+                // --> ensure we only add proper items-arrays here
+                if (response?.items?.length) {
+                    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
+                    const lastId = Number(items.at(-1)?.id);
+                    if (!Number.isSafeInteger(lastId) || lastId <= cursor) {
+                        throw new Error(
+                            'Asset dependency query failed: all shards failed without a usable ID cursor.'
+                        );
+                    }
+                    cursor = lastId;
+                    payload.query = {
+                        leftOperand: dependencyQuery,
+                        logicalOperator: 'AND',
+                        rightOperand: {
+                            property: 'id',
+                            simpleOperator: 'greaterThan',
+                            value: cursor,
+                        },
+                    };
+                    lastPage = 0;
+                    moreResults = true;
+                } else if (response.page * response.pageSize < response.count) {
+                    moreResults = true;
+                    lastPage = Number(response.page);
+                } else {
+                    moreResults = false;
+                }
+            } while (moreResults);
+        } catch (ex) {
+            Util.logger.error(`An error occurred while attempting to query assets. ${ex.message}`);
+            throw ex;
+        }
+
+        // The API filter finds candidates only; verify exact literal arguments locally.
+        const references = { key: new Set(), id: new Set(), name: new Set() };
+        for (const block of blocks) {
+            references.key.add(block.customerKey);
+            if (block.id) {
+                references.id.add(String(block.id));
+            }
+            const namedBlock = structuredClone(block);
+            if (!namedBlock.r__folder_Path) {
+                this.setFolderPath(namedBlock, true);
+            }
+            if (namedBlock.r__folder_Path && namedBlock.name) {
+                references.name.add(
+                    namedBlock.r__folder_Path.replaceAll('/', '\\') + '\\' + namedBlock.name
+                );
+            }
+        }
+        const verifiedItems = [];
+        for (let item of items) {
+            let contents = this._getReferenceContents(item);
+            if (!contents.length) {
+                item = await this.client.rest.get('/asset/v1/content/assets/' + item.id);
+                contents = this._getReferenceContents(item);
+            }
+            if (contents.some((content) => this._hasLiteralBlockReference(content, references))) {
+                verifiedItems.push(item);
+            }
+        }
+        items = verifiedItems;
+
+        const emailTypes = this.definition.extendedSubTypes.email;
+        const foundEmails = items.filter((item) => emailTypes.includes(item.assetType.name));
+        const foundBlocks = items.filter((item) => !emailTypes.includes(item.assetType.name));
+
+        for (const email of foundEmails) {
+            _foundEmails[email.customerKey] = email;
+        }
+
+        // Recurse with all unsearched blocks in one call
+        const unsearchedBlocks = foundBlocks.filter(
+            (block) => !_searchedKeys.has(block.customerKey)
+        );
+        if (unsearchedBlocks.length) {
+            await this._findEmailsUsingBlock(unsearchedBlocks, _foundEmails, _searchedKeys);
+        }
+
+        // @ts-ignore
+        return _foundEmails;
+    }
 
     /**
-     * helper for {@link Asset.postDeployTasks}. triggers a refresh of active triggerredSendDefinitions associated with the updated asset-message items. Gets executed if refresh option has been set.
+     * helper for {@link Asset.postDeployTasks}. triggers a refresh of active triggerredSendDefinitions associated with the updated asset-email items. Gets executed if refresh option has been set.
      *
      * @private
      * @param {MetadataTypeMap} metadata metadata mapped by their keyField
-     * @returns {Promise.<void>} -
+     * @returns {Promise.<string[]>} Returns list of keys that were refreshed
      */
     static async _refreshTriggeredSend(metadata) {
         // get legacyData.legacyId from assets to compare to TSD's metadata.Email.ID to
@@ -874,36 +984,33 @@ class Asset extends MetadataType {
             Util.logger.warn(
                 'No legacyId found in updated emails. Skipping refresh of triggeredSendDefinitions.'
             );
-            return;
+            return [];
         }
         // prep triggeredSendDefinition class
         TriggeredSend.properties = this.properties;
         TriggeredSend.buObject = this.buObject;
         TriggeredSend.client = this.client;
-        try {
-            // find refreshable TSDs
-            const tsdObj = (await TriggeredSend.findRefreshableItems(true))?.metadata;
+        // find refreshable TSDs; discovery errors must reach the refresh/deploy handler
+        const tsdObj = (await TriggeredSend.findRefreshableItems(true))?.metadata;
 
-            const tsdCountInitial = Object.keys(tsdObj).length;
-            const emailCount = legacyIdArr.length;
-            // filter TSDs by legacyId
-            for (const key in tsdObj) {
-                if (!legacyIdArr.includes(tsdObj[key].Email.ID)) {
-                    delete tsdObj[key];
-                }
+        const tsdCountInitial = Object.keys(tsdObj).length;
+        const emailCount = legacyIdArr.length;
+        // filter TSDs by legacyId
+        for (const key in tsdObj) {
+            if (!legacyIdArr.includes(tsdObj[key].Email.ID)) {
+                delete tsdObj[key];
             }
-            const tsdCountFiltered = Object.keys(tsdObj).length;
-            Util.logger.info(
-                `Found ${tsdCountFiltered} out of ${tsdCountInitial} total triggeredSendDefinitions for ${emailCount} deployed emails. Commencing validation...`
-            );
+        }
+        const tsdCountFiltered = Object.keys(tsdObj).length;
+        Util.logger.info(
+            `Found ${tsdCountFiltered} out of ${tsdCountInitial} total triggeredSendDefinitions for ${emailCount} deployed emails. Commencing validation...`
+        );
 
-            // get keys of TSDs to refresh
-            const keyArr = await TriggeredSend.getKeysForValidTSDs(tsdObj);
+        // get keys of TSDs to refresh
+        const keyArr = await TriggeredSend.getKeysForValidTSDs(tsdObj);
 
-            await TriggeredSend.refresh(keyArr);
-        } catch {
-            Util.logger.warn('Failed to refresh triggeredSendDefinition');
-        }
+        // Never pass an empty selection to a refresh-all-capable method.
+        return keyArr.length ? await TriggeredSend.refresh(keyArr) : [];
     }
 
     /**
@@ -931,10 +1038,7 @@ class Asset extends MetadataType {
                     'CloudPage content cannot be created via mcdev. Please create it via the UI first, then you can update the content or key.'
                 );
             }
-            if (
-                this.definition.extendedSubTypes.cloudpage.includes(metadata.assetType.name) ||
-                this.definition.extendedSubTypes.coderesource.includes(metadata.assetType.name)
-            ) {
+            if (this.definition.extendedSubTypes.webstudio.includes(metadata.assetType.name)) {
                 // if we do create those, we get the error "Asset <id> not found" because the internal endpoint internal/v2/cloudpages/sites won't find it.
                 throw new Error(
                     'CloudPage assets cannot be created via mcdev. Please create it via the UI first, then you can update the content or key.'
@@ -1013,6 +1117,8 @@ class Asset extends MetadataType {
 
         // #1 get text extracts back into the JSON
         await this._mergeCode(metadata, deployDir, subType);
+        // Keep preview tokens through Mustache builds; restore only the final deployment source.
+        this._restoreMobilePreview(metadata);
 
         // #2 get file from local disk and insert as base64
         await this._readExtendedFileFromFS(metadata, subType, deployDir);
@@ -1057,7 +1163,7 @@ class Asset extends MetadataType {
      * find the subType matching the extendedSubType
      *
      * @param {string} extendedSubType webpage, htmlblock, etc
-     * @returns {string} subType: block, message, other, etc
+     * @returns {string} subType: block, email, other, etc
      */
     static #getMainSubtype(extendedSubType) {
         return Object.keys(this.definition.extendedSubTypes).find((subType) =>
@@ -1206,7 +1312,7 @@ class Asset extends MetadataType {
         if (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];
+            const fileExt = metadata.fileProperties.extension.split(' ', 1)[0];
 
             const filecontent = await File.readFilteredFilename(
                 [templateDir, this.definition.type, subType],
@@ -1239,7 +1345,7 @@ class Asset extends MetadataType {
                         extractedFile.content = ssjs;
                     }
                 }
-                File.writeToFile(
+                await File.writeToFile(
                     [targetDir, ...extractedFile.subFolder],
                     extractedFile.fileName,
                     extractedFile.fileExt,
@@ -1330,7 +1436,7 @@ class Asset extends MetadataType {
      */
     static async _preDeployTasksBocks(metadata) {
         switch (metadata.assetType.name) {
-            case 'templatebasedemail': // message
+            case 'templatebasedemail': // email
             case 'htmlemail':
             case 'webpage': {
                 // metadata.views.html.slots.<>.blocks.<>.content (optional)
@@ -1358,40 +1464,44 @@ class Asset extends MetadataType {
      */
     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',
-                                };
-                            }
-                            if (asset.r__folder_Path) {
-                                // if we convert this into a folder path then renamed folders might end up blocking deployments, therefore, we instead omit this detail from now on
-                                delete asset.r__folder_Path;
-                            }
-                            await this._preDeployTasksBocks(asset);
-                        }
+            if (!Object.prototype.hasOwnProperty.call(metadataSlots, slot)) {
+                continue;
+            }
+
+            const slotObj = metadataSlots[slot];
+            // found slot
+            if (slotObj.blocks) {
+                for (const block in slotObj.blocks) {
+                    if (!Object.prototype.hasOwnProperty.call(slotObj.blocks, block)) {
+                        continue;
+                    }
+
+                    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',
+                        };
+                    }
+                    if (asset.r__folder_Path) {
+                        // if we convert this into a folder path then renamed folders might end up blocking deployments, therefore, we instead omit this detail from now on
+                        delete asset.r__folder_Path;
                     }
+                    await this._preDeployTasksBocks(asset);
                 }
             }
         }
@@ -1416,9 +1526,41 @@ class Asset extends MetadataType {
         const customerKey = metadata.customerKey.trim();
         const templateFileName = templateName || customerKey;
         switch (metadata.assetType.name) {
-            case 'templatebasedemail': // message
+            case 'jsonmessage': {
+                subDirArr = [this.definition.type, subType, templateFileName.trim()];
+                readDirArr = [deployDir, ...subDirArr];
+                for (const { field, companion, data } of this._getMobileCodeFields(metadata)) {
+                    const fileName = `${field.replaceAll(':', '_')}${subtypeExtension}`;
+                    const path = File.normalizePath([
+                        ...readDirArr,
+                        File.filterIllegalFilenames(`${fileName}.amp`),
+                    ]);
+                    if (!(await File.pathExists(path))) {
+                        if (!fileListOnly) {
+                            // Missing source is not an explicitly empty sidecar.
+                            delete data[field];
+                            delete data[companion];
+                        }
+                        continue;
+                    }
+
+                    if (!fileListOnly) {
+                        data[field] = await File.readFilteredFilename(readDirArr, fileName, 'amp');
+                        // The sidecar is authoritative for both duplicate source fields.
+                        data[companion] = data[field];
+                    }
+                    fileList.push({
+                        subFolder: subDirArr,
+                        fileName,
+                        fileExt: 'amp',
+                        content: data[field],
+                    });
+                }
+                break;
+            }
+            case 'templatebasedemail': // email
             case 'htmlemail': {
-                // message
+                // email
                 // this complex type always creates its own subdir per asset
                 subDirArr = [this.definition.type, subType];
                 readDirArr = [deployDir, ...subDirArr, templateFileName];
@@ -1586,7 +1728,7 @@ class Asset extends MetadataType {
                 break;
             }
             case 'textonlyemail': {
-                // message
+                // email
                 // metadata.views.text.content
                 subDirArr = [this.definition.type, subType];
                 readDirArr = [deployDir, ...subDirArr];
@@ -1792,70 +1934,70 @@ class Asset extends MetadataType {
         const templateFileName = templateName || customerKey;
 
         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];
-                            const fileName = `${prefix}.[${slot}-${block}]${subtypeExtension}`;
-                            if (
-                                await File.pathExists(
-                                    File.normalizePath([
-                                        ...readDirArr,
-                                        'blocks',
-                                        `${fileName}.html`,
-                                    ])
-                                )
-                            ) {
-                                // 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) {
-                                    asset.content = await File.readFilteredFilename(
-                                        [...readDirArr, 'blocks'],
-                                        fileName,
-                                        'html'
-                                    );
-                                }
-                                if (templateName) {
-                                    // to use this method in templating, store a copy of the info in fileList
-                                    fileList.push({
-                                        subFolder: [...subDirArr, templateFileName, 'blocks'],
-                                        fileName: fileName,
-                                        fileExt: 'html',
-                                        content: asset.content,
-                                    });
-                                }
-                            }
-                            if (asset.slots) {
-                                // * recursion: each block can have slots of its own
-                                await this._mergeCode_slots(
-                                    `${prefix}.[${slot}-${block}]`,
-                                    asset.slots,
-                                    readDirArr,
-                                    subtypeExtension,
-                                    subDirArr,
-                                    fileList,
-                                    customerKey,
-                                    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
-                                );
-                            }
+            if (!Object.prototype.hasOwnProperty.call(metadataSlots, slot)) {
+                continue;
+            }
+
+            const slotObj = metadataSlots[slot];
+            // found slot
+            if (slotObj.blocks) {
+                for (const block in slotObj.blocks) {
+                    if (!Object.prototype.hasOwnProperty.call(slotObj.blocks, block)) {
+                        continue;
+                    }
+
+                    const asset = slotObj.blocks[block];
+                    const fileName = `${prefix}.[${slot}-${block}]${subtypeExtension}`;
+                    if (
+                        await File.pathExists(
+                            File.normalizePath([...readDirArr, 'blocks', `${fileName}.html`])
+                        )
+                    ) {
+                        // 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) {
+                            asset.content = await File.readFilteredFilename(
+                                [...readDirArr, 'blocks'],
+                                fileName,
+                                'html'
+                            );
                         }
+                        if (templateName) {
+                            // to use this method in templating, store a copy of the info in fileList
+                            fileList.push({
+                                subFolder: [...subDirArr, templateFileName, 'blocks'],
+                                fileName: fileName,
+                                fileExt: 'html',
+                                content: asset.content,
+                            });
+                        }
+                    }
+                    if (asset.slots) {
+                        // * recursion: each block can have slots of its own
+                        await this._mergeCode_slots(
+                            `${prefix}.[${slot}-${block}]`,
+                            asset.slots,
+                            readDirArr,
+                            subtypeExtension,
+                            subDirArr,
+                            fileList,
+                            customerKey,
+                            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
+                        );
                     }
                 }
             }
@@ -1867,7 +2009,299 @@ class Asset extends MetadataType {
      * to allow saving that separately and formatted
      *
      * @param {AssetItem} metadata a single asset definition
-     * @returns {CodeExtractItem} { json: metadata, codeArr: object[], subFolder: string[] }
+     * @returns {{channel: 'push' | 'sms' | 'inApp', field: 'display:title' | 'display:message', companion: 'display:title:display' | 'display:message:display', data: object}[]} editable mobile fields
+     */
+    static _getMobileCodeFields(metadata) {
+        /** @type {{channel: 'push' | 'sms' | 'inApp', field: 'display:title' | 'display:message', companion: 'display:title:display' | 'display:message:display', data: object}[]} */
+        const fields = [];
+        // Only real message source is editable; views.<channel>.content is generated preview HTML.
+        // Keep the allowlist narrow: push/inApp title/message and SMS message, not UI options.
+        const channels = /** @type {const} */ (['push', 'sms', 'inApp']);
+        if (
+            channels.filter((channel) => metadata.views?.[channel]?.meta?.options?.customBlockData)
+                .length > 1
+        ) {
+            throw new TypeError('Cannot process mobile source with multiple supported channels');
+        }
+        for (const channel of channels) {
+            const data = metadata.views?.[channel]?.meta?.options?.customBlockData;
+            if (data) {
+                for (const field of channel === 'sms'
+                    ? /** @type {const} */ (['display:message'])
+                    : /** @type {const} */ (['display:title', 'display:message'])) {
+                    fields.push({ channel, field, companion: `${field}:display`, data });
+                }
+            }
+        }
+        return fields;
+    }
+
+    /**
+     * Escape literal mobile source for an existing HTML text slot, without rendering it.
+     *
+     * @param {string} value source text
+     * @returns {string} escaped text
+     */
+    static _escapeMobilePreview(value) {
+        return value
+            .replaceAll('&', '&amp;')
+            .replaceAll('<', '&lt;')
+            .replaceAll('>', '&gt;')
+            .replaceAll('"', '&quot;')
+            .replaceAll("'", '&#39;');
+    }
+
+    /**
+     * Escape a URL for the generated unquoted CSS url slot, including HTML style boundaries.
+     *
+     * @param {string} value source URL
+     * @returns {string} escaped CSS URL
+     */
+    static _escapeMobilePreviewUrl(value) {
+        return value.replaceAll(
+            /[\s()"'\\<>]/g,
+            (char) => `\\${char.codePointAt(0).toString(16)} `
+        );
+    }
+
+    /**
+     * Tokenize only known, source-equal mobile preview text slots before extracting source.
+     *
+     * @param {AssetItem} metadata asset with inline source
+     * @returns {void} -
+     */
+    static _tokenizeMobilePreview(metadata) {
+        for (const channel of /** @type {const} */ (['push', 'sms', 'inApp'])) {
+            const view = metadata.views?.[channel];
+            const data = view?.meta?.options?.customBlockData;
+            if (typeof view?.content !== 'string' || !data) {
+                continue;
+            }
+            const replaceSlot = (slot, field, context) => {
+                const value = data[field];
+                if (typeof value !== 'string' || !value) {
+                    return slot;
+                }
+                const escaped =
+                    context === 'url'
+                        ? this._escapeMobilePreviewUrl(value)
+                        : this._escapeMobilePreview(value);
+                // Field identity keeps equal title/message source independently editable.
+                return context
+                    ? this._replaceMobilePreviewPadding(slot, escaped, `[[[${field}]]]`)
+                    : slot === escaped
+                      ? `[[[${field}]]]`
+                      : slot;
+            };
+            view.content = this._replaceMobilePreviewSlots(view.content, channel, replaceSlot);
+        }
+    }
+
+    /**
+     * Replace an exact source value with whitespace allowed only outside that value.
+     *
+     * @param {string} slot complete preview slot
+     * @param {string} source escaped source or field token
+     * @param {string} replacement updated slot value
+     * @returns {string} slot with external padding preserved
+     */
+    static _replaceMobilePreviewPadding(slot, source, replacement) {
+        const start = slot.indexOf(source);
+        if (start === -1) {
+            return slot;
+        }
+        const before = slot.slice(0, start);
+        const after = slot.slice(start + source.length);
+        return /^\s*$/.test(before) && /^\s*$/.test(after) ? before + replacement + after : slot;
+    }
+
+    /**
+     * Replace text only in recognized mobile preview slots, preserving wrapper bytes.
+     *
+     * @param {string} content preview HTML
+     * @param {'push' | 'sms' | 'inApp'} channel mobile view
+     * @param {(text: string, field: 'display:title' | 'display:subtitle' | 'display:message' | 'button1:title' | 'button2:title' | 'display:media:url', context?: 'url' | 'padded') => string} replaceSlot slot replacement
+     * @returns {string} updated HTML
+     */
+    static _replaceMobilePreviewSlots(content, channel, replaceSlot) {
+        // Consume comments as opaque matches so apparent slots inside them remain untouched.
+        if (channel === 'inApp') {
+            // One pass over original wrappers: inserted source is never visited as another slot.
+            return content.replaceAll(
+                /<!--[\s\S]*?-->|<script\b[^>]*>[\s\S]*?<\/script\s*>|(<style\b[^>]*>)([\s\S]*?)(<\/style\s*>)|(<header\b(?:[^>"']|"[^"]*"|'[^']*')*>\s*<h1\b[^>]*>)([^<]*)(<\/h1\s*>\s*<\/header\s*>)|(<(?:p|button)\b(?:[^>"']|"[^"]*"|'[^']*')*>)([^<]*)(<\/(?:p|button)\s*>)|<(?:[^>"']|"[^"]*"|'[^']*')*>/gi,
+                (
+                    match,
+                    styleOpen,
+                    css,
+                    styleClose,
+                    header,
+                    title,
+                    headerClose,
+                    open,
+                    text,
+                    close
+                ) => {
+                    if (styleOpen) {
+                        return (
+                            styleOpen +
+                            css.replaceAll(
+                                /((?:^|[{}])(?:\s|\/\*[^*]*\*+(?:[^/*][^*]*\*+)*\/)*)(\.jmb-image\s*\{(?:[^{}/]|\/(?!\*)|\/\*[^*]*\*+(?:[^/*][^*]*\*+)*\/)*\})|(\/\*[^*]*\*+(?:[^/*][^*]*\*+)*\/)/g,
+                                (rule, prefix, block, comment) =>
+                                    comment
+                                        ? rule
+                                        : prefix +
+                                          block.replaceAll(
+                                              /\/\*[^*]*\*+(?:[^/*][^*]*\*+)*\/|([{;](?:\s|\/\*[^*]*\*+(?:[^/*][^*]*\*+)*\/)*background(?:-image)?\s*:\s*url\()([^()]*)(\))/g,
+                                              (url, before, value, after) =>
+                                                  before
+                                                      ? before +
+                                                        replaceSlot(
+                                                            value,
+                                                            'display:media:url',
+                                                            'url'
+                                                        ) +
+                                                        after
+                                                      : url
+                                          )
+                            ) +
+                            styleClose
+                        );
+                    }
+                    const attributes = [
+                        ...(header || open || '').matchAll(/\s([\w:-]+)\s*=\s*(["'])(.*?)\2/gs),
+                    ];
+                    const classes =
+                        attributes
+                            .find((attribute) => attribute[1].toLowerCase() === 'class')?.[3]
+                            .split(/\s+/) || [];
+                    if (header) {
+                        return classes.includes('jmb-header')
+                            ? header + replaceSlot(title, 'display:title') + headerClose
+                            : match;
+                    }
+                    if (!open) {
+                        return match;
+                    }
+                    if (/^<p\b/i.test(open) && classes.includes('jmb-message')) {
+                        return open + replaceSlot(text, 'display:message') + close;
+                    }
+                    const buttons = classes.filter((name) =>
+                        ['jmb-button-1', 'jmb-button-2'].includes(name)
+                    );
+                    if (!/^<button\b/i.test(open) || buttons.length !== 1) {
+                        return match;
+                    }
+                    const field = /** @type {'button1:title' | 'button2:title'} */ (
+                        `button${buttons[0].at(-1)}:title`
+                    );
+                    return (
+                        open.replaceAll(
+                            /(\s([\w:-]+)\s*=\s*)(["'])(.*?)\3/gs,
+                            (attribute, before, name, quote, value) =>
+                                name.toLowerCase() === 'title'
+                                    ? before + quote + replaceSlot(value, field) + quote
+                                    : attribute
+                        ) +
+                        replaceSlot(text, field, 'padded') +
+                        close
+                    );
+                }
+            );
+        }
+        if (channel === 'push') {
+            // Match text-only divs with an exact class-list member, retaining every wrapper byte.
+            return content.replaceAll(
+                /<!--[\s\S]*?-->|<script\b[^>]*>[\s\S]*?<\/script\s*>|<style\b[^>]*>[\s\S]*?<\/style\s*>|(<div\b(?:[^>"']|"[^"]*"|'[^']*')*?\sclass\s*=\s*(["'])([^"']*)\2(?:[^>"']|"[^"]*"|'[^']*')*>)([^<]*)(<\/div\s*>)|<(?:[^>"']|"[^"]*"|'[^']*')*>/gi,
+                (match, open, quote, classes, text, close) => {
+                    if (!open) {
+                        return match;
+                    }
+                    const fields = classes
+                        .split(/\s+/)
+                        .filter((name) => ['title', 'subtitle', 'message'].includes(name));
+                    return fields.length === 1
+                        ? open +
+                              replaceSlot(
+                                  text,
+                                  /** @type {'display:title' | 'display:subtitle' | 'display:message'} */ (
+                                      `display:${fields[0]}`
+                                  )
+                              ) +
+                              close
+                        : match;
+                }
+            );
+        }
+        // SMS embeds its message in a span inside the generated text-bubble div.
+        return content.replaceAll(
+            /<!--[\s\S]*?-->|<script\b[^>]*>[\s\S]*?<\/script\s*>|<style\b[^>]*>[\s\S]*?<\/style\s*>|(<div\b(?:[^>"']|"[^"]*"|'[^']*')*?\sclass\s*=\s*(["'])([^"']*)\2(?:[^>"']|"[^"]*"|'[^']*')*>\s*<span\b(?:[^>"']|"[^"]*"|'[^']*')*>)([^<]*)(<\/span\s*>\s*<\/div\s*>)|<(?:[^>"']|"[^"]*"|'[^']*')*>/gi,
+            (match, open, quote, classes, text, close) =>
+                open && classes.split(/\s+/).includes('text-bubble')
+                    ? open + replaceSlot(text, 'display:message') + close
+                    : match
+        );
+    }
+
+    /**
+     * Restore mapped preview slots after final source merging, never during Mustache builds.
+     *
+     * @param {AssetItem} metadata asset with merged source
+     * @returns {void} -
+     */
+    static _restoreMobilePreview(metadata) {
+        if (metadata.assetType.name !== 'jsonmessage') {
+            return;
+        }
+        for (const channel of /** @type {const} */ (['push', 'sms', 'inApp'])) {
+            const view = metadata.views?.[channel];
+            const data = view?.meta?.options?.customBlockData;
+            if (typeof view?.content !== 'string' || !data) {
+                continue;
+            }
+            // One slot pass cannot rescan placeholder-like source inserted by another slot.
+            view.content = this._replaceMobilePreviewSlots(
+                view.content,
+                channel,
+                (text, field, context) => {
+                    const token = `[[[${field}]]]`;
+                    if (
+                        context
+                            ? this._replaceMobilePreviewPadding(text, token, '') === text
+                            : text !== token
+                    ) {
+                        return text;
+                    }
+                    let value = data[field];
+                    if (typeof value !== 'string') {
+                        // Only extracted title/message source can be absent after merging.
+                        if (
+                            this._getMobileCodeFields(metadata).every(
+                                (source) => !(source.channel === channel && source.field === field)
+                            )
+                        ) {
+                            throw new TypeError(
+                                `Missing mobile preview source: ${channel}.${field}`
+                            );
+                        }
+                        value = '';
+                    }
+                    const escaped =
+                        context === 'url'
+                            ? this._escapeMobilePreviewUrl(value)
+                            : this._escapeMobilePreview(value);
+                    return context
+                        ? this._replaceMobilePreviewPadding(text, token, escaped)
+                        : escaped;
+                }
+            );
+        }
+    }
+
+    /**
+     * Extract editable source into sidecars.
+     *
+     * @param {AssetItem} metadata a single asset definition
+     * @returns {CodeExtractItem} extracted source and JSON
      */
     static _extractCode(metadata) {
         const codeArr = [];
@@ -1875,9 +2309,33 @@ class Asset extends MetadataType {
         // unfortunately, asset's key can contain spaces at beginning/end which can break the file system when folders are created with it
         const customerKey = metadata.customerKey.trim();
         switch (metadata.assetType.name) {
-            case 'templatebasedemail': // message-templatebasedemail
+            case 'jsonmessage': {
+                const fields = this._getMobileCodeFields(metadata);
+                this._tokenizeMobilePreview(metadata);
+                for (const { field, companion, data } of fields) {
+                    // Empty and plain strings are source too, matching the same editable file layout.
+                    if (typeof data[field] !== 'string') {
+                        continue;
+                    }
+                    codeArr.push({
+                        subFolder: null,
+                        fileName: `${field.replaceAll(':', '_')}`,
+                        fileExt: 'amp',
+                        content: data[field],
+                    });
+                    // Keep a single editable source; deployment normalizes the duplicate field.
+                    delete data[companion];
+                    delete data[field];
+                }
+                return {
+                    json: metadata,
+                    codeArr,
+                    subFolder: codeArr.length ? [customerKey] : null,
+                };
+            }
+            case 'templatebasedemail': // email-templatebasedemail
             case 'htmlemail': {
-                // message-htmlemail
+                // email-htmlemail
                 // metadata.views.html.content (mandatory)
                 if (metadata.views?.html?.content?.length) {
                     codeArr.push({
@@ -1946,7 +2404,7 @@ class Asset extends MetadataType {
                 };
             }
             case 'textonlyemail': {
-                // message-textonlyemail
+                // email-textonlyemail
                 // metadata.views.text.content
                 if (metadata.views?.text?.content?.length) {
                     codeArr.push({
@@ -2077,58 +2535,58 @@ class Asset extends MetadataType {
      */
     static _extractCode_slots(prefix, metadataSlots, codeArr) {
         for (const slot in metadataSlots) {
-            if (Object.prototype.hasOwnProperty.call(metadataSlots, slot)) {
-                const slotObj = metadataSlots[slot];
-                // found slot
-                for (const block in slotObj.blocks) {
-                    if (Object.prototype.hasOwnProperty.call(slotObj.blocks, block)) {
-                        const asset = slotObj.blocks[block];
-                        if (asset.content) {
-                            // found content block
-                            const code = asset.content;
-                            codeArr.push({
-                                subFolder: ['blocks'],
-                                fileName: `${prefix}.[${slot}-${block}]`,
-                                fileExt: 'html',
-                                content: code,
-                            });
-                            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 (asset.category?.id) {
-                            // if we convert this into a folder path then renamed folders might end up blocking deployments, therefore, we instead omit this detail from now on
-                            delete asset.category;
-                        }
+            if (!Object.prototype.hasOwnProperty.call(metadataSlots, slot)) {
+                continue;
+            }
 
-                        if (asset.slots) {
-                            // * recursion: each block can have slots of its own
-                            this._extractCode_slots(
-                                `${prefix}.[${slot}-${block}]`,
-                                asset.slots,
-                                codeArr
-                            );
-                        }
+            const slotObj = metadataSlots[slot];
+            // found slot
+            for (const block in slotObj.blocks) {
+                if (!Object.prototype.hasOwnProperty.call(slotObj.blocks, block)) {
+                    continue;
+                }
+
+                const asset = slotObj.blocks[block];
+                if (asset.content) {
+                    // found content block
+                    const code = asset.content;
+                    codeArr.push({
+                        subFolder: ['blocks'],
+                        fileName: `${prefix}.[${slot}-${block}]`,
+                        fileExt: 'html',
+                        content: code,
+                    });
+                    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 (asset.category?.id) {
+                    // if we convert this into a folder path then renamed folders might end up blocking deployments, therefore, we instead omit this detail from now on
+                    delete asset.category;
+                }
+
+                if (asset.slots) {
+                    // * recursion: each block can have slots of its own
+                    this._extractCode_slots(`${prefix}.[${slot}-${block}]`, asset.slots, codeArr);
+                }
             }
         }
     }
@@ -2138,7 +2596,7 @@ class Asset extends MetadataType {
      *
      * @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, ...
+     * @param {string[]} [selectedSubType] asset, email, ...
      * @returns {Promise.<MetadataTypeMap>} fileName => fileContent map
      */
     static async getJsonFromFS(dir, _, selectedSubType) {
@@ -2171,52 +2629,54 @@ class Asset extends MetadataType {
      * @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
+        if (!(await File.pathExists(currentdir))) {
+            return;
+        }
+
+        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('.json')) {
+                    const errorDir = currentdir.replaceAll('\\', '/');
+                    const fileContent = await File.readJSONFile(currentdir, fileName, false);
+                    // ! convert numbers to string to allow numeric keys to be checked properly
+                    const key = Number.isInteger(fileContent[this.definition.keyField])
+                        ? fileContent[this.definition.keyField].toString()
+                        : fileContent[this.definition.keyField];
+                    if (fileName.endsWith(fileEnding)) {
+                        // subtype will change the metadata suffix length
+                        const fileNameWithoutEnding = File.reverseFilterIllegalFilenames(
+                            fileName.slice(0, -fileEndingLength)
                         );
-                    } else if (fileName.endsWith('.json')) {
-                        const errorDir = currentdir.split('\\').join('/');
-                        const fileContent = await File.readJSONFile(currentdir, fileName, false);
-                        // ! convert numbers to string to allow numeric keys to be checked properly
-                        const key = Number.isInteger(fileContent[this.definition.keyField])
-                            ? fileContent[this.definition.keyField].toString()
-                            : fileContent[this.definition.keyField];
-                        if (fileName.endsWith(fileEnding)) {
-                            // subtype will change the metadata suffix length
-                            const fileNameWithoutEnding = File.reverseFilterIllegalFilenames(
-                                fileName.slice(0, -fileEndingLength)
-                            );
-                            if (key === fileNameWithoutEnding) {
-                                fileName2FileContent[fileNameWithoutEnding] = fileContent;
-                            } else {
-                                Util.logger.error(
-                                    ` ☇ skipping ${this.definition.type} ${key}: Name of the metadata file and the JSON-key (${this.definition.keyField}) must match. Expected: ${key}${fileEnding}. Actual: ` +
-                                        Util.getGrayMsg(`${errorDir}/`) +
-                                        fileName
-                                );
-                            }
+                        if (key === fileNameWithoutEnding) {
+                            fileName2FileContent[fileNameWithoutEnding] = fileContent;
                         } else {
                             Util.logger.error(
-                                ` ☇ skipping ${this.definition.type} ${key}: Name of the metadata file must end on the extended metadata suffix. Expected: ${key}${fileEnding}. Actual: ` +
+                                ` ☇ skipping ${this.definition.type} ${key}: Name of the metadata file and the JSON-key (${this.definition.keyField}) must match. Expected: ${key}${fileEnding}. Actual: ` +
                                     Util.getGrayMsg(`${errorDir}/`) +
                                     fileName
                             );
                         }
+                    } else {
+                        Util.logger.error(
+                            ` ☇ skipping ${this.definition.type} ${key}: Name of the metadata file must end on the extended metadata suffix. Expected: ${key}${fileEnding}. Actual: ` +
+                                Util.getGrayMsg(`${errorDir}/`) +
+                                fileName
+                        );
                     }
-                } 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);
                 }
+            } 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);
             }
         }
     }
@@ -2316,14 +2776,25 @@ class Asset extends MetadataType {
                     ) {
                         // #1 load json to be able to find extracted text files & binary files
                         const metadata = await File.readJSONFile(filePath, fileName, false);
+                        if (!metadata) {
+                            throw new Error(
+                                `Cannot discover associated asset files: invalid JSON in ${File.normalizePath([...filePath, fileName])}`
+                            );
+                        }
                         // #2 find all extracted text files
                         const fileListNested = (
-                            await this._mergeCode(metadata, basePath, subType, metadata.customerKey)
+                            await this._mergeCode(
+                                metadata,
+                                basePath,
+                                subType,
+                                metadata.customerKey,
+                                true
+                            )
                         ).map((item) =>
                             File.normalizePath([
                                 basePath,
                                 ...item.subFolder,
-                                `${item.fileName}.${item.fileExt}`,
+                                File.filterIllegalFilenames(`${item.fileName}.${item.fileExt}`),
                             ])
                         );
                         // ensure we dont overlook other versions when using this logic to auto-delete older files
@@ -2605,7 +3076,6 @@ class Asset extends MetadataType {
                             `404. Try running mcdev r ${this.buObject.credential}/${ownerBUName} ${this.definition.type}-${subType} ${item[this.definition.keyField]}`)
                 );
             }
-            return json;
         } else {
             json.error = 'id not found';
             delete json.key;
@@ -2621,8 +3091,8 @@ class Asset extends MetadataType {
                 return json;
             }
             Util.logger.error(` - ${this.definition.type} with id ${id} not found on BU`);
-            return json;
         }
+        return json;
     }
 
     /**
@@ -2692,7 +3162,7 @@ class Asset extends MetadataType {
         const subType = this.#getMainSubtype(item.assetType.name);
         /** @type {CodeExtract[]} */
         const fileList = await this._mergeCode(
-            item,
+            structuredClone(item),
             retrieveDir,
             subType,
             item[this.definition.keyField],
@@ -2714,10 +3184,42 @@ class Asset extends MetadataType {
                 }
             }
         }
+        // Inline companions without a canonical sidecar still participate in reference replacement.
+        let companionsChanged = false;
+        if (item.assetType.name === 'jsonmessage') {
+            for (const { field, companion: alias, data } of this._getMobileCodeFields(
+                responseItem
+            )) {
+                if (
+                    fileList.some((file) =>
+                        file.fileName.startsWith(`${field.replaceAll(':', '_')}.`)
+                    ) ||
+                    typeof data[alias] !== 'string'
+                ) {
+                    continue;
+                }
+                try {
+                    const content = ReplaceCbReference.replaceReference(
+                        data[alias],
+                        parentName,
+                        findAssetKeys
+                    );
+                    if (!findAssetKeys) {
+                        data[alias] = content;
+                        companionsChanged = true;
+                    }
+                    changes = true;
+                } catch (ex) {
+                    if (ex.code !== 200) {
+                        error = ex;
+                    }
+                }
+            }
+        }
         if (!findAssetKeys) {
             // save what was changed regardless of other errors
             for (const extractedFile of fileListChanged) {
-                File.writeToFile(
+                await File.writeToFile(
                     [retrieveDir, ...extractedFile.subFolder],
                     extractedFile.fileName,
                     extractedFile.fileExt,
@@ -2725,6 +3227,18 @@ class Asset extends MetadataType {
                     extractedFile.encoding || null
                 );
             }
+            if (companionsChanged) {
+                // Asset's replacement loop deliberately skips saveToDisk to preserve extracts.
+                const customerKey = item[this.definition.keyField].trim();
+                const fileName = `${customerKey}.${this.definition.type}-${subType}-meta`;
+                const baseDir = [retrieveDir, this.definition.type, subType];
+                const jsonDir = (await File.pathExists(
+                    File.normalizePath([...baseDir, customerKey, `${fileName}.json`])
+                ))
+                    ? [...baseDir, customerKey]
+                    : baseDir;
+                await File.writeJSONToFile(jsonDir, fileName, responseItem);
+            }
         }
 
         if (error) {
@@ -2847,10 +3361,12 @@ class Asset extends MetadataType {
         if (newKeysFound.size) {
             const keysToCrawl = [];
             for (const value of newKeysFound) {
-                if (!keyArr.includes(value)) {
-                    keyArr.push(value);
-                    keysToCrawl.push(value);
+                if (keyArr.includes(value)) {
+                    continue;
                 }
+
+                keyArr.push(value);
+                keysToCrawl.push(value);
             }
             Util.logger.info(Util.getGrayMsg(` - asset: ${keysToCrawl.join(', ')}`));
 
@@ -2910,6 +3426,55 @@ class Asset extends MetadataType {
         }
     }
 
+    /**
+     * Collect content strings from an asset and its nested views, slots and blocks.
+     *
+     * @param {object} item asset or nested content node
+     * @returns {string[]} content strings available in the query response
+     */
+    static _getReferenceContents(item) {
+        const contents = [];
+        if (typeof item?.content === 'string') {
+            contents.push(item.content);
+        }
+        for (const field of ['views', 'slots', 'blocks']) {
+            for (const child of Object.values(item?.[field] || {})) {
+                contents.push(...this._getReferenceContents(child));
+            }
+        }
+        return contents;
+    }
+
+    /**
+     * Match literal first arguments only, without evaluating dynamic expressions.
+     *
+     * @param {string} content asset content
+     * @param {{key: Set.<string>, id: Set.<string>, name: Set.<string>}} references target identifiers
+     * @returns {boolean} whether the content references a target block
+     */
+    static _hasLiteralBlockReference(content, references) {
+        const regex =
+            /(?<![\w.])(?<ssjs>Platform\.Function\.)?ContentBlockBy(?<by>Key|Id|Name)\s*\(\s*(?:"(?<double>[^"]*)"|'(?<single>[^']*)'|(?<numeric>[0-9]+))\s*(?=[,)])/gim;
+        for (const match of content.matchAll(regex)) {
+            const { ssjs, by, double, single, numeric } = match.groups;
+            const kind = by.toLowerCase();
+            if (numeric !== undefined && kind !== 'id') {
+                continue;
+            }
+            let identifier = double ?? single ?? numeric;
+            if (kind === 'id' && !/^[0-9]+$/.test(identifier)) {
+                continue;
+            }
+            if (kind === 'name' && ssjs) {
+                identifier = identifier.replaceAll('\\\\', '\\');
+            }
+            if (references[kind].has(identifier)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
     /**
      * helper for {@link MetadataType.createOrUpdate}
      *
@@ -2980,11 +3545,97 @@ class Asset extends MetadataType {
         }
         return cacheMatchedByName;
     }
+    /**
+     * Finds emails in running journeys, filters out the ones that reference the block (if it's a block) and refreshes related TSDs
+     *
+     * @param {string[]} keyArr metadata keys
+     * @returns {Promise.<string[]>} Returns list of keys that were refreshed
+     */
+    static async refresh(keyArr) {
+        if (!Array.isArray(keyArr)) {
+            throw new TypeError('Asset.refresh requires an explicit array of keys');
+        }
+        if (!keyArr.length) {
+            return [];
+        }
+        const codeBlocks = [];
+        const toPublish = [];
+
+        Util.logger.info(' - Caching dependent Metadata: asset');
+        const assets = await this.retrieveForCache(undefined, undefined, undefined, false);
+        cache.mergeMetadata('asset', assets.metadata);
+
+        Util.logger.info(' - Caching dependent Metadata: shared-asset');
+        const sharedAssets = await this.retrieveForCache(undefined, undefined, undefined, true);
+        cache.mergeMetadata('asset', sharedAssets.metadata);
+
+        for (const key of keyArr) {
+            const item = cache.getByKey(this.definition.type, key);
+            if (!item) {
+                Util.logger.warn(` - Could not find asset in cache for key: ${key}, skipping`);
+                continue;
+            }
+            if (this.definition.extendedSubTypes.email.includes(item?.assetType?.name)) {
+                toPublish.push(item);
+                // refreshing code blocks referenced with ContentBlockBy
+            } else if (
+                this.definition.extendedSubTypes.block.includes(item?.assetType?.name) ||
+                this.definition.extendedSubTypes.other.includes(item?.assetType?.name)
+            ) {
+                codeBlocks.push(item);
+            }
+        }
+        if (codeBlocks.length > 0) {
+            if (!cache.getCache().folder) {
+                // Name-based block references require local and shared Content Builder paths.
+                Folder.client = this.client;
+                Folder.buObject = this.buObject;
+                Folder.properties = this.properties;
+                const folders = await Folder.retrieveForCache(null, ['asset', 'asset-shared']);
+                cache.setMetadata('folder', folders.metadata);
+            }
+            toPublish.push(...Object.values(await this._findEmailsUsingBlock(codeBlocks)));
+        }
+        Util.logger.info(
+            ` - Found ${toPublish.length} assets to publish. Looking up triggered sends for the following emails: ${toPublish.map((e) => e.name)}`
+        );
+        return toPublish.length ? await this._refreshTriggeredSend(toPublish) : [];
+    }
+
+    /**
+     * enables metadata definitions required for sharing assets
+     *
+     * @param {boolean} keepSharingInfo true to enable, false to disable
+     * @returns {void}
+     */
+    static _toggleShareAssetTemplating(keepSharingInfo) {
+        const sharingProperties = [
+            'businessUnitAvailability',
+            'businessUnitAvailability.%',
+            'businessUnitAvailability[].view',
+            'businessUnitAvailability[].update',
+            'businessUnitAvailability[].delete',
+            'businessUnitAvailability[].memberId',
+            'businessUnitAvailability[].transferOwnership',
+            'sharingProperties',
+            'sharingProperties.sharedWith',
+            'sharingProperties.sharingType',
+        ];
+
+        // the above fields are already creatable, updateable and and retrievable - but they are filtered for templating which we seek to override
+        for (const property of sharingProperties) {
+            this.definition.fields[property] = {
+                // isCreateable: true,
+                // isUpdateable: true,
+                // retrieving: true,
+                template: keepSharingInfo,
+            };
+        }
+    }
 }
 
 // Assign definition to static attributes
 import MetadataTypeDefinitions from '../MetadataTypeDefinitions.js';
-
 Asset.definition = MetadataTypeDefinitions.asset;
 
 export default Asset;