@salesforce/plugin-omnistudio-migration-tool 2.0.0-rc.60 → 2.0.0-rc.61

package/lib/migration/flexcard.js

@@ -8,6 +8,7 @@ const VlocityCard_1 = __importDefault(require("../mappings/VlocityCard"));
 const utils_1 = require("../utils");
 const net_1 = require("../utils/net");
 const base_1 = require("./base");
+const CustomCssRegistry_1 = require("./CustomCssRegistry");
 const interfaces_1 = require("./interfaces");
 const logger_1 = require("../utils/logger");
 const base_2 = require("./base");
@@ -16,11 +17,14 @@ const storageUtil_1 = require("../utils/storageUtil");
 const stringUtils_1 = require("../utils/stringUtils");
 const dataModelService_1 = require("../utils/dataModelService");
 const recordPrioritization_1 = require("../utils/recordPrioritization");
+const ApexNamespaceRegistry_1 = require("./ApexNamespaceRegistry");
 class CardMigrationTool extends base_1.BaseMigrationTool {
     constructor(namespace, connection, logger, messages, ux, allVersions) {
         super(namespace, connection, logger, messages, ux);
+        this.apexNamespaceRegistry = ApexNamespaceRegistry_1.ApexNamespaceRegistry.getInstance();
         this.IS_STANDARD_DATA_MODEL = (0, dataModelService_1.isStandardDataModel)();
         this.allVersions = allVersions;
+        CustomCssRegistry_1.CustomCssRegistry.getInstance().init(connection, namespace, messages);
     }
     getName() {
         return 'Flexcards';
@@ -160,6 +164,7 @@ class CardMigrationTool extends base_1.BaseMigrationTool {
                     dependenciesOS: [],
                     dependenciesLWC: [],
                     dependenciesApexRemoteAction: [],
+                    dependenciesVlocityAction: [],
                     infos: [],
                     warnings: [],
                     errors: [this.messages.getMessage('unexpectedError')],
@@ -187,6 +192,7 @@ class CardMigrationTool extends base_1.BaseMigrationTool {
             dependenciesFC: [],
             dependenciesLWC: [],
             dependenciesApexRemoteAction: [],
+            dependenciesVlocityAction: [],
             infos: [],
             warnings: [],
             errors: [],
@@ -237,6 +243,17 @@ class CardMigrationTool extends base_1.BaseMigrationTool {
         };
         flexCardAssessmentInfo.migrationStatus = assessmentStatus;
         this.updateDependencies(flexCard, flexCardAssessmentInfo);
+        // Scan custom CSS (both StaticResource-backed and inline) for managed-package
+        // namespace references. The helper updates `migrationStatus` itself via
+        // `getUpdatedAssessmentStatus`, so it never downgrades a stricter status.
+        await this.collectStylesheetNamespaceDependencies(flexCard, flexCardAssessmentInfo);
+        if (flexCardAssessmentInfo.errors.length > 0) {
+            flexCardAssessmentInfo.migrationStatus = 'Needs manual intervention';
+        }
+        else if (flexCardAssessmentInfo.warnings.length > 0 &&
+            flexCardAssessmentInfo.migrationStatus === 'Ready for migration') {
+            flexCardAssessmentInfo.migrationStatus = 'Warnings';
+        }
         // Deduplicate all dependency arrays to ensure no duplicates
         flexCardAssessmentInfo.dependenciesIP = [...new Set(flexCardAssessmentInfo.dependenciesIP)];
         flexCardAssessmentInfo.dependenciesDR = [...new Set(flexCardAssessmentInfo.dependenciesDR)];
@@ -246,8 +263,77 @@ class CardMigrationTool extends base_1.BaseMigrationTool {
         flexCardAssessmentInfo.dependenciesApexRemoteAction = [
             ...new Set(flexCardAssessmentInfo.dependenciesApexRemoteAction),
         ];
+        flexCardAssessmentInfo.dependenciesVlocityAction = [...new Set(flexCardAssessmentInfo.dependenciesVlocityAction)];
         return flexCardAssessmentInfo;
     }
+    /**
+     * Scan a FlexCard for two distinct kinds of namespace-bound custom CSS:
+     *
+     *  1. **StaticResource-backed stylesheet** — `Definition__c.customStyleSheet`
+     *     stores the *Name* of a Static Resource. We look it up, fetch its body,
+     *     and substring-check for the org's managed-package namespace. Same flow
+     *     and same warning message as the OmniScript implementation; resource
+     *     scans are cached by name in {@link CustomCssRegistry}, so a stylesheet
+     *     shared between OmniScripts and FlexCards is only fetched once per run.
+     *
+     *  2. **Inline CSS** — `Styles__c.customStyles` stores raw CSS text. We
+     *     substring-check the namespace directly against that string. No
+     *     SOQL/REST traffic and no caching (the CSS is per-FlexCard and not
+     *     shared across records).
+     *
+     * Both checks emit a warning into `flexCardAssessmentInfo.warnings` and bump
+     * `migrationStatus` to 'Needs manual intervention' (via
+     * `getUpdatedAssessmentStatus`, which never downgrades a stricter status).
+     */
+    async collectStylesheetNamespaceDependencies(flexCard, flexCardAssessmentInfo) {
+        const registry = CustomCssRegistry_1.CustomCssRegistry.getInstance();
+        if (!registry.isEnabled()) {
+            return;
+        }
+        // ---- 1. Definition__c.customStyleSheet (StaticResource name) ----
+        const definitionRaw = flexCard[this.getFieldKey('Definition__c')];
+        if (definitionRaw) {
+            let definition;
+            try {
+                definition = JSON.parse(definitionRaw);
+            }
+            catch (ex) {
+                logger_1.Logger.error(`Failed to parse Definition__c for stylesheet scan: ${flexCard['Name']}`);
+                definition = null;
+            }
+            const resourceName = ((definition === null || definition === void 0 ? void 0 : definition.customStyleSheet) || '').toString().trim();
+            if (resourceName) {
+                const verdict = await registry.scanResource(resourceName);
+                if (verdict === 'namespaceFound') {
+                    const message = registry.buildFlexCardNamespaceWarning(resourceName);
+                    if (message) {
+                        flexCardAssessmentInfo.warnings.push(message);
+                        flexCardAssessmentInfo.migrationStatus = (0, stringUtils_1.getUpdatedAssessmentStatus)(flexCardAssessmentInfo.migrationStatus, 'Needs manual intervention');
+                    }
+                }
+            }
+        }
+        // ---- 2. Styles__c.customStyles (raw inline CSS) ----
+        const stylesRaw = flexCard[this.getFieldKey('Styles__c')];
+        if (stylesRaw) {
+            let styles;
+            try {
+                styles = JSON.parse(stylesRaw);
+            }
+            catch (ex) {
+                logger_1.Logger.error(`Failed to parse Styles__c for stylesheet scan: ${flexCard['Name']}`);
+                styles = null;
+            }
+            const inlineCss = styles === null || styles === void 0 ? void 0 : styles.customStyles;
+            if (registry.containsNamespaceInText(inlineCss)) {
+                const message = registry.buildInlineCssNamespaceWarning();
+                if (message) {
+                    flexCardAssessmentInfo.warnings.push(message);
+                    flexCardAssessmentInfo.migrationStatus = (0, stringUtils_1.getUpdatedAssessmentStatus)(flexCardAssessmentInfo.migrationStatus, 'Needs manual intervention');
+                }
+            }
+        }
+    }
     updateDependencies(flexCard, flexCardAssessmentInfo) {
         var _a, _b, _c, _d;
         const dataSourceConfig = JSON.parse(flexCard[this.getFieldKey('Datasource__c')] || '{}');
@@ -271,10 +357,19 @@ class CardMigrationTool extends base_1.BaseMigrationTool {
             else if (ds.type === stringContants_1.Constants.ApexRemoteComponentName) {
                 const remoteClass = (_c = ds.value) === null || _c === void 0 ? void 0 : _c.remoteClass;
                 const remoteMethod = (_d = ds.value) === null || _d === void 0 ? void 0 : _d.remoteMethod;
-                if (remoteClass &&
-                    remoteMethod &&
-                    !flexCardAssessmentInfo.dependenciesApexRemoteAction.includes(`${remoteClass}.${remoteMethod}`)) {
-                    flexCardAssessmentInfo.dependenciesApexRemoteAction.push(`${remoteClass}.${remoteMethod}`);
+                if (remoteClass && remoteMethod) {
+                    const status = this.apexNamespaceRegistry.resolveStatus(remoteClass);
+                    const qualifiedClass = this.apexNamespaceRegistry.getQualifiedClassName(remoteClass);
+                    const qualifiedEntry = `${qualifiedClass}.${remoteMethod}`;
+                    if (!flexCardAssessmentInfo.dependenciesApexRemoteAction.includes(qualifiedEntry)) {
+                        flexCardAssessmentInfo.dependenciesApexRemoteAction.push(qualifiedEntry);
+                    }
+                    if (status === ApexNamespaceRegistry_1.ApexResolveStatus.NAMESPACED) {
+                        flexCardAssessmentInfo.warnings.push(this.messages.getMessage('apexRemoteDatasourceNamespaceWarning', [remoteClass, qualifiedClass]));
+                    }
+                    else if (status === ApexNamespaceRegistry_1.ApexResolveStatus.NOT_FOUND) {
+                        flexCardAssessmentInfo.errors.push(this.messages.getMessage('apexClassNotFound', [remoteClass, flexCardAssessmentInfo.name]));
+                    }
                 }
             }
         }
@@ -330,6 +425,10 @@ class CardMigrationTool extends base_1.BaseMigrationTool {
                     continue;
                 }
                 const stateAction = action.stateAction;
+                // Detect Vlocity Action (not supported in standard runtime FlexCards)
+                if (stateAction.type === stringContants_1.Constants.VlocityAction) {
+                    this.addVlocityActionDependency(stateAction, flexCardAssessmentInfo);
+                }
                 // 1-2. Handle message.value.bundle (DataRaptor) and message.value.ipMethod (Integration Procedure)
                 this.processStateActionMessageForDependencies(stateAction, flexCardAssessmentInfo);
                 // 3. Handle cardName (FlexCard - Flyout childCard)
@@ -411,6 +510,15 @@ class CardMigrationTool extends base_1.BaseMigrationTool {
                     flexCardAssessmentInfo.dependenciesLWC.push(customLwcName);
                 }
             }
+            // "action" is a reserved keyword in the core runtime; flag any Custom LWC
+            // that defines it as a property so the user removes/renames it pre-migration.
+            if (Object.prototype.hasOwnProperty.call(component.property, 'action')) {
+                const lwcLabel = component.property.customlwcname || component.elementLabel || stringContants_1.Constants.CustomLwc;
+                const reservedActionMessage = this.messages.getMessage('customLwcReservedActionKey', [lwcLabel]);
+                flexCardAssessmentInfo.errors.push(reservedActionMessage);
+                flexCardAssessmentInfo.warnings.push(reservedActionMessage);
+                flexCardAssessmentInfo.migrationStatus = 'Needs manual intervention';
+            }
         }
     }
     /**
@@ -573,12 +681,16 @@ class CardMigrationTool extends base_1.BaseMigrationTool {
         }
         return childs;
     }
-    checkComponentForDependencies(component, flexCardAssessmentInfo) {
+    checkComponentForDependencies(component, flexCardAssessmentInfo, omniScriptNavigateURLWarningKeys = new Set()) {
         // Check if this component is an action element
         if (component.element === 'action' && component.property && component.property.actionList) {
             // Process each action in the actionList
             for (const action of component.property.actionList) {
                 if (action.stateAction) {
+                    // Detect Vlocity Action (not supported in standard runtime FlexCards)
+                    if (action.stateAction.type === stringContants_1.Constants.VlocityAction) {
+                        this.addVlocityActionDependency(action.stateAction, flexCardAssessmentInfo);
+                    }
                     // Handle message field (contains DataRaptor/IP references as JSON string)
                     this.processStateActionMessageForDependencies(action.stateAction, flexCardAssessmentInfo);
                     // Case 1: Direct OmniScript reference
@@ -619,6 +731,9 @@ class CardMigrationTool extends base_1.BaseMigrationTool {
                     else if (this.hasCustomLwcFlyoutDependency(action.stateAction)) {
                         this.addCfPrefixedFlexCardDependency(action.stateAction.flyoutLwc, flexCardAssessmentInfo);
                     }
+                    else if (this.isCustomWebPageAction(action.stateAction)) {
+                        this.addOmniScriptNavigateURLAssessmentWarning(action.stateAction, flexCardAssessmentInfo, omniScriptNavigateURLWarningKeys);
+                    }
                 }
             }
         }
@@ -659,6 +774,9 @@ class CardMigrationTool extends base_1.BaseMigrationTool {
             if (this.hasCustomLwcFlyoutDependency(component.property.stateAction)) {
                 this.addCfPrefixedFlexCardDependency(component.property.stateAction.flyoutLwc, flexCardAssessmentInfo);
             }
+            else if (this.isCustomWebPageAction(component.property.stateAction)) {
+                this.addOmniScriptNavigateURLAssessmentWarning(component.property.stateAction, flexCardAssessmentInfo, omniScriptNavigateURLWarningKeys);
+            }
         }
         // MISSING PATTERN FIXED: Handle omni-flyout elements (from tests)
         if (component.element === stringContants_1.Constants.OmniFlyout && component.property && component.property.flyoutOmniScript) {
@@ -675,11 +793,80 @@ class CardMigrationTool extends base_1.BaseMigrationTool {
         }
         // Check child components recursively
         if (component.children && Array.isArray(component.children)) {
-            for (const child of component.children) {
-                this.checkComponentForDependencies(child, flexCardAssessmentInfo);
+            for (let childIndex = 0; childIndex < component.children.length; childIndex++) {
+                const child = component.children[childIndex];
+                this.checkComponentForDependencies(child, flexCardAssessmentInfo, omniScriptNavigateURLWarningKeys);
             }
         }
     }
+    addOmniScriptNavigateURLAssessmentWarning(stateAction, flexCardAssessmentInfo, warningKeys) {
+        if (this.IS_STANDARD_DATA_MODEL) {
+            return;
+        }
+        const rewrite = this.getOmniScriptURLRewrite(stateAction);
+        if (!rewrite) {
+            return;
+        }
+        const { targetName, updatedURL, malformedTokens } = rewrite;
+        const summary = this.formatURLRewriteSummary(targetName, updatedURL);
+        if (warningKeys.has(summary)) {
+            return;
+        }
+        warningKeys.add(summary);
+        // Emit a single warning per URL: when fragment tokens are malformed, the
+        // dedicated malformed-token warning is the authoritative one (it already
+        // contains both the original URL and the "will get replaced with" line,
+        // PLUS the malformed-token list and the verify instruction). For clean
+        // URLs we fall back to the plain rewrite warning. Defense-in-depth: if
+        // the malformed formatter unexpectedly returns empty, fall back to the
+        // plain rewrite warning so the customer still sees something.
+        const hasMalformedTokens = Array.isArray(malformedTokens) && malformedTokens.length > 0;
+        let warningText = '';
+        if (hasMalformedTokens) {
+            warningText = this.formatMalformedFragmentTokenWarning(targetName, updatedURL, malformedTokens);
+        }
+        if (!warningText) {
+            warningText = this.messages.getMessage('webPageOmniScriptNavigationDetected', [
+                this.toReadableURL(targetName),
+                this.toReadableURL(updatedURL),
+            ]);
+        }
+        flexCardAssessmentInfo.warnings.push(warningText);
+        flexCardAssessmentInfo.migrationStatus = (0, stringUtils_1.getUpdatedAssessmentStatus)(flexCardAssessmentInfo.migrationStatus, 'Warnings');
+    }
+    /**
+     * Build the customer-facing warning shown when a Web Page action URL contains
+     * fragment tokens that decodeURIComponent couldn't parse. Centralised here so
+     * the assessment and migration paths emit byte-identical text.
+     *
+     * Returns an empty string when the helper is called with no malformed tokens
+     * (defense in depth: callers already guard, but a future caller that forgets
+     * shouldn't be able to produce a degenerate warning with an empty bracket).
+     * Non-string entries are coerced via String() so a misbehaving caller can't
+     * surface "undefined" / "[object Object]" to customers; duplicates are
+     * suppressed so a fragment like `#/Foo%/Bar/Foo%/Baz` doesn't render as
+     * `["Foo%", "Foo%"]`.
+     */
+    formatMalformedFragmentTokenWarning(targetName, updatedURL, malformedTokens) {
+        if (!Array.isArray(malformedTokens) || malformedTokens.length === 0) {
+            return '';
+        }
+        const seen = new Set();
+        const uniqueTokens = [];
+        for (const raw of malformedTokens) {
+            const t = typeof raw === 'string' ? raw : String(raw);
+            if (!seen.has(t)) {
+                seen.add(t);
+                uniqueTokens.push(t);
+            }
+        }
+        const tokenList = uniqueTokens.map((t) => `"${t}"`).join(', ');
+        return this.messages.getMessage('webPageOmniScriptUrlMalformedToken', [
+            tokenList,
+            this.toReadableURL(targetName),
+            this.toReadableURL(updatedURL),
+        ]);
+    }
     async getAllCards() {
         //DebugTimer.getInstance().lap('Query Vlocity Cards');
         const filters = new Map();
@@ -752,7 +939,12 @@ class CardMigrationTool extends base_1.BaseMigrationTool {
             }
             // Perform the transformation
             const invalidIpNames = new Map();
-            const transformedCard = this.mapVlocityCardRecord(card, cardsUploadInfo, invalidIpNames); // This only has the card structure, card definition is not there
+            const urlUpdateSummaries = new Set();
+            // Map keyed by rewrite summary so the emission step below can subtract
+            // malformed URLs from the aggregate "Updated URLs:" locations message.
+            // Same key for two actions on the same card => one entry (deduped).
+            const malformedFragmentWarnings = new Map();
+            const transformedCard = this.mapVlocityCardRecord(card, cardsUploadInfo, invalidIpNames, urlUpdateSummaries, malformedFragmentWarnings); // This only has the card structure, card definition is not there
             // Verify duplicated names
             let transformedCardName;
             if (this.allVersions) {
@@ -822,6 +1014,25 @@ class CardMigrationTool extends base_1.BaseMigrationTool {
                 if (transformedCard['Name'] !== card['Name']) {
                     uploadResult.warnings.unshift(this.messages.getMessage('cardNameChangeMessage', [transformedCardName]));
                 }
+                // The count summary describes ONLY URLs that were converted cleanly
+                // to the standard URL format. Malformed URLs were rewritten with
+                // their bad tokens kept as-is -- claiming they were "updated to
+                // standard URL format" alongside their own malformed warning would
+                // contradict that warning and confuse the customer. Each malformed
+                // URL is surfaced via its own dedicated bullet below which already
+                // names the original URL, the rewritten URL, and the verify
+                // instruction.
+                const cleanRewriteSummaries = Array.from(urlUpdateSummaries).filter((summary) => !malformedFragmentWarnings.has(summary));
+                if (cleanRewriteSummaries.length > 0) {
+                    uploadResult.warnings.unshift(this.messages.getMessage('flexCardOmniScriptNavigateURLUpdated', [String(cleanRewriteSummaries.length)]));
+                }
+                // Surface malformed-fragment-token warnings (one per affected URL).
+                // These are intentionally emitted *instead of* the count bullet
+                // above so the customer sees a single, actionable bullet per
+                // malformed URL: original URL, rewrite, verify instruction.
+                for (const malformedWarning of malformedFragmentWarnings.values()) {
+                    uploadResult.warnings.push(malformedWarning);
+                }
                 if (uploadResult.id && invalidIpNames.size > 0) {
                     const val = Array.from(invalidIpNames.entries())
                         .map((e) => e[0])
@@ -1002,7 +1213,7 @@ class CardMigrationTool extends base_1.BaseMigrationTool {
         card[this.getFieldKey('Definition__c')] = JSON.stringify(definition);
     }
     // Maps an indivitdual VlocityCard__c record to an OmniUiCard record.
-    mapVlocityCardRecord(cardRecord, cardsUploadInfo, invalidIpNames) {
+    mapVlocityCardRecord(cardRecord, cardsUploadInfo, invalidIpNames, urlUpdateSummaries, malformedFragmentWarnings) {
         var _a, _b;
         // Transformed object
         let mappedObject = {};
@@ -1082,7 +1293,7 @@ class CardMigrationTool extends base_1.BaseMigrationTool {
         const isCardActive = cardRecord[this.getFieldKey('Active__c')];
         this.ensureCommunityTargets(mappedObject, isCardActive);
         // Update all dependencies comprehensively
-        this.updateAllDependenciesWithRegistry(mappedObject, invalidIpNames);
+        this.updateAllDependenciesWithRegistry(mappedObject, invalidIpNames, urlUpdateSummaries, malformedFragmentWarnings);
         mappedObject['attributes'] = {
             type: CardMigrationTool.OMNIUICARD_NAME,
             referenceId: cardRecord['Id'],
@@ -1092,7 +1303,7 @@ class CardMigrationTool extends base_1.BaseMigrationTool {
     /**
      * Comprehensive dependency update using NameMappingRegistry - mirrors assessment logic
      */
-    updateAllDependenciesWithRegistry(mappedObject, invalidIpNames) {
+    updateAllDependenciesWithRegistry(mappedObject, invalidIpNames, urlUpdateSummaries, malformedFragmentWarnings) {
         // Handle propertySet (Definition) - update all dependency references
         const propertySet = JSON.parse(mappedObject[VlocityCard_1.default.Definition__c] || '{}');
         if (propertySet) {
@@ -1127,7 +1338,7 @@ class CardMigrationTool extends base_1.BaseMigrationTool {
                         for (const componentKey in state.components) {
                             if (state.components.hasOwnProperty(componentKey)) {
                                 const component = state.components[componentKey];
-                                this.updateComponentDependenciesWithRegistry(component);
+                                this.updateComponentDependenciesWithRegistry(component, urlUpdateSummaries, malformedFragmentWarnings);
                             }
                         }
                     }
@@ -1183,7 +1394,7 @@ class CardMigrationTool extends base_1.BaseMigrationTool {
      * Update dataSource (DataRaptor, Integration Procedures, Apex Remote) using registry
      */
     updateDataSourceWithRegistry(dataSource, invalidIpNames, context) {
-        var _a, _b;
+        var _a, _b, _c;
         const type = dataSource.type;
         if (type === stringContants_1.Constants.DataRaptorComponentName) {
             // Handle DataRaptor using registry
@@ -1214,6 +1425,11 @@ class CardMigrationTool extends base_1.BaseMigrationTool {
                 }
             }
         }
+        else if (type === stringContants_1.Constants.ApexRemoteComponentName) {
+            if ((_c = dataSource.value) === null || _c === void 0 ? void 0 : _c.remoteClass) {
+                dataSource.value.remoteClass = this.apexNamespaceRegistry.getQualifiedClassName(dataSource.value.remoteClass);
+            }
+        }
     }
     /**
      * Update OmniScript reference using registry
@@ -1247,7 +1463,7 @@ class CardMigrationTool extends base_1.BaseMigrationTool {
     /**
      * Update component dependencies comprehensively
      */
-    updateComponentDependenciesWithRegistry(component) {
+    updateComponentDependenciesWithRegistry(component, urlUpdateSummaries, malformedFragmentWarnings) {
         // Handle action elements with actionList (like assessment)
         if (component.element === 'action' && component.property && component.property.actionList) {
             for (const action of component.property.actionList) {
@@ -1266,6 +1482,10 @@ class CardMigrationTool extends base_1.BaseMigrationTool {
                     else if (this.hasFlyoutLwc(action.stateAction)) {
                         this.updateFlyoutLwcValue(action.stateAction);
                     }
+                    // Case A: Custom Web Page action referencing OmniScript Universal Page
+                    else if (this.isCustomWebPageAction(action.stateAction)) {
+                        this.applyOmniScriptURLRewrite(action.stateAction, urlUpdateSummaries, malformedFragmentWarnings);
+                    }
                 }
             }
         }
@@ -1291,6 +1511,9 @@ class CardMigrationTool extends base_1.BaseMigrationTool {
             if (this.hasFlyoutLwc(component.property.stateAction)) {
                 this.updateFlyoutLwcValue(component.property.stateAction);
             }
+            if (this.isCustomWebPageAction(component.property.stateAction)) {
+                this.applyOmniScriptURLRewrite(component.property.stateAction, urlUpdateSummaries, malformedFragmentWarnings);
+            }
         }
         // Handle childCardPreview elements (from old fixChildren method)
         if (component.element === stringContants_1.Constants.ChildCardPreview && component.property) {
@@ -1337,9 +1560,201 @@ class CardMigrationTool extends base_1.BaseMigrationTool {
         // Check child components recursively
         if (component.children && Array.isArray(component.children)) {
             for (const child of component.children) {
-                this.updateComponentDependenciesWithRegistry(child);
+                this.updateComponentDependenciesWithRegistry(child, urlUpdateSummaries, malformedFragmentWarnings);
+            }
+        }
+    }
+    applyOmniScriptURLRewrite(stateAction, urlUpdateSummaries, malformedFragmentWarnings) {
+        if (this.IS_STANDARD_DATA_MODEL) {
+            return;
+        }
+        const rewrite = this.getOmniScriptURLRewrite(stateAction);
+        if (!rewrite) {
+            return;
+        }
+        const { targetName, updatedURL, malformedTokens } = rewrite;
+        stateAction[stringContants_1.Constants.WebPageTargetType].targetName = updatedURL;
+        const summary = this.formatURLRewriteSummary(targetName, updatedURL);
+        urlUpdateSummaries.add(summary);
+        // Per-card collector is optional so internal/test callers can omit it
+        // without forcing a signature update. The Map is keyed by the rewrite
+        // summary so the emission step can later subtract malformed URLs from
+        // the aggregate "Updated URLs: ..." locations message -- each malformed
+        // entry already carries the original URL, the rewritten URL, and the
+        // verify instruction inside its own warning, so listing it twice would
+        // be redundant. Same key for two actions on the same card => one entry.
+        // Defense-in-depth: skip if the formatter returns an empty string so we
+        // never store a blank warning under a real summary key.
+        if (malformedFragmentWarnings && Array.isArray(malformedTokens) && malformedTokens.length > 0) {
+            const malformedWarning = this.formatMalformedFragmentTokenWarning(targetName, updatedURL, malformedTokens);
+            if (malformedWarning) {
+                malformedFragmentWarnings.set(summary, malformedWarning);
+            }
+        }
+    }
+    /** Build a human-readable "before -> after" string for warning messages only. */
+    formatURLRewriteSummary(originalURL, updatedURL) {
+        return `${this.toReadableURL(originalURL)} -> ${this.toReadableURL(updatedURL)}`;
+    }
+    /**
+     * Decode a URL for DISPLAY purposes only (warning/log messages). The output
+     * is lossy with respect to URL parsing semantics (e.g. an encoded `%26`
+     * becomes a literal `&`) and must NOT be re-fed into a URL parser. Falls
+     * back to the raw input on malformed percent sequences.
+     */
+    toReadableURL(url) {
+        try {
+            return decodeURIComponent(url);
+        }
+        catch {
+            return url;
+        }
+    }
+    getOmniScriptURLRewrite(stateAction) {
+        var _a;
+        const targetName = (_a = stateAction[stringContants_1.Constants.WebPageTargetType]) === null || _a === void 0 ? void 0 : _a.targetName;
+        if (typeof targetName !== 'string') {
+            return undefined;
+        }
+        // Fast reject: if the raw text doesn't even mention the universal-page
+        // path or token, skip URL parsing entirely. This is a substring screen,
+        // not a security check; the strict structural validation happens after
+        // parsing in isValidOmniScriptNavigationURL.
+        if (!targetName.includes(stringContants_1.Constants.OmniScriptUniversalPagePath) ||
+            !targetName.includes(stringContants_1.Constants.OmniScriptUniversalPageToken)) {
+            return undefined;
+        }
+        const parsedURL = this.tryParseURL(targetName);
+        if (!parsedURL || !this.isValidOmniScriptNavigationURL(parsedURL)) {
+            return undefined;
+        }
+        const updatedURL = this.convertToStandardOmniScriptURL(parsedURL);
+        // Re-parse the fragment once more here purely to capture malformed-token
+        // diagnostics for the caller. Cheap (single split + map over a short
+        // string) and keeps `convertToStandardOmniScriptURL` focused on rewriting.
+        const { malformedTokens } = this.parseSlashFragmentParams(parsedURL.hash);
+        return { targetName, updatedURL, malformedTokens };
+    }
+    isCustomWebPageAction(stateAction) {
+        return (stateAction === null || stateAction === void 0 ? void 0 : stateAction.type) === stringContants_1.Constants.CustomActionType && (stateAction === null || stateAction === void 0 ? void 0 : stateAction.targetType) === stringContants_1.Constants.WebPageTargetType;
+    }
+    /**
+     * Parse a URL string without throwing. Returns the parsed URL on success or
+     * undefined for:
+     *   - syntactically invalid input (e.g. `https://[bad`, raw spaces in host,
+     *     `http:///` with no host), or
+     *   - URLs whose scheme is not `http:` or `https:` (e.g. `javascript:`,
+     *     `data:`, `file:`, `mailto:`).
+     *
+     * See URL_PARSE_BASE for why a synthetic base is supplied.
+     */
+    tryParseURL(input) {
+        let parsed;
+        try {
+            parsed = new URL(input, CardMigrationTool.URL_PARSE_BASE);
+        }
+        catch {
+            return undefined;
+        }
+        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+            return undefined;
+        }
+        return parsed;
+    }
+    /**
+     * Verify a parsed URL has the OmniScript Navigate shape. We validate against
+     * the parsed components (pathname / searchParams / hash) rather than doing
+     * substring matches on the raw input so callers cannot smuggle the required
+     * tokens in unrelated positions (e.g. inside another query value).
+     *
+     * The pathname must START WITH `/apex/` and contain the universal-page
+     * token. Anchoring to the prefix rejects non-http(s) schemes such as
+     * `javascript:alert(1)//apex/...` whose parsed pathname does not begin
+     * with `/` (it begins with the opaque body of the scheme).
+     *
+     * Two legitimate shapes are accepted:
+     *   1. Path + query:    /apex/<ns>__OmniScriptUniversalPage?OmniScriptType=...&OmniScriptSubType=...&OmniScriptLang=...
+     *   2. Path + fragment: /apex/<ns>__OmniScriptUniversalPage?...#/OmniScriptType/.../OmniScriptSubType/.../OmniScriptLang/...
+     */
+    isValidOmniScriptNavigationURL(parsedURL) {
+        if (!parsedURL.pathname.startsWith(`${stringContants_1.Constants.OmniScriptUniversalPagePath}/`)) {
+            return false;
+        }
+        if (!parsedURL.pathname.includes(stringContants_1.Constants.OmniScriptUniversalPageToken)) {
+            return false;
+        }
+        const fragmentKeys = new Set(this.parseSlashFragmentParams(parsedURL.hash).pairs.map(([key]) => key));
+        const hasParam = (key) => parsedURL.searchParams.has(key) || fragmentKeys.has(key);
+        return (hasParam(stringContants_1.Constants.OmniScriptTypeParam) &&
+            hasParam(stringContants_1.Constants.OmniScriptSubTypeParam) &&
+            hasParam(stringContants_1.Constants.OmniScriptLangParam));
+    }
+    convertToStandardOmniScriptURL(parsedURL) {
+        var _a;
+        const paramRenames = {
+            [stringContants_1.Constants.OmniScriptTypeParam]: stringContants_1.Constants.OmniScriptStandardTypeParam,
+            [stringContants_1.Constants.OmniScriptSubTypeParam]: stringContants_1.Constants.OmniScriptStandardSubTypeParam,
+            [stringContants_1.Constants.OmniScriptLangParam]: stringContants_1.Constants.OmniScriptStandardLanguageParam,
+            [stringContants_1.Constants.OmniScriptLayoutParam]: stringContants_1.Constants.OmniScriptStandardThemeParam,
+        };
+        const paramsToClean = new Set([stringContants_1.Constants.OmniScriptTypeParam, stringContants_1.Constants.OmniScriptSubTypeParam]);
+        // Merge query-string params with fragment params. Query-string entries win on conflict.
+        const mergedEntries = [];
+        const seenKeys = new Set();
+        parsedURL.searchParams.forEach((value, key) => {
+            mergedEntries.push([key, value]);
+            seenKeys.add(key);
+        });
+        for (const [key, value] of this.parseSlashFragmentParams(parsedURL.hash).pairs) {
+            if (!seenKeys.has(key)) {
+                mergedEntries.push([key, value]);
+                seenKeys.add(key);
+            }
+        }
+        const newSearchParams = new URLSearchParams();
+        for (const [key, value] of mergedEntries) {
+            const newKey = (_a = paramRenames[key]) !== null && _a !== void 0 ? _a : key;
+            const newValue = paramsToClean.has(key) ? this.cleanName(value) : value;
+            newSearchParams.append(newKey, newValue);
+        }
+        return `${stringContants_1.Constants.OmniScriptStandardPagePath}?${newSearchParams.toString()}`;
+    }
+    /**
+     * Parse a slash-separated OmniScript fragment of the form
+     *   #/Key1/Value1/Key2/Value2/...
+     * into [key, value] pairs. Tolerates leading `#`, leading `/`, empty values
+     * (consecutive slashes), and a trailing orphan token (which is dropped).
+     *
+     * Tokens with malformed percent sequences (e.g. `Foo%`, `Bar%E2`) are kept
+     * as-is rather than throwing; decodeURIComponent raises URIError on invalid
+     * escape sequences and we don't want one bad token to crash the whole
+     * FlexCard's URL rewrite. The raw (still-encoded) tokens are also returned
+     * via `malformedTokens` so callers can surface them to customers as a
+     * "please verify" warning rather than silently shipping a best-effort guess.
+     */
+    parseSlashFragmentParams(hash) {
+        if (!hash) {
+            return { pairs: [], malformedTokens: [] };
+        }
+        const trimmed = hash.replace(/^#\/?/, '');
+        if (!trimmed) {
+            return { pairs: [], malformedTokens: [] };
+        }
+        const malformedTokens = [];
+        const tokens = trimmed.split('/').map((t) => {
+            try {
+                return decodeURIComponent(t);
+            }
+            catch {
+                malformedTokens.push(t);
+                return t;
             }
+        });
+        const pairs = [];
+        for (let i = 0; i + 1 < tokens.length; i += 2) {
+            pairs.push([tokens[i], tokens[i + 1]]);
         }
+        return { pairs, malformedTokens };
     }
     /**
      * Update omniType.Name using registry (handles Type/SubType/Language format)
@@ -1517,6 +1932,23 @@ class CardMigrationTool extends base_1.BaseMigrationTool {
             flexCardAssessmentInfo.migrationStatus = (0, stringUtils_1.getUpdatedAssessmentStatus)(flexCardAssessmentInfo.migrationStatus, 'Warnings');
         }
     }
+    /**
+     * Helper method to flag a Vlocity Action dependency during assessment.
+     * Vlocity Actions are not supported in standard runtime FlexCards, so the
+     * FlexCard cannot be auto-migrated and must be manually reimplemented using
+     * the FlexCard Action (cardAction) feature.
+     */
+    addVlocityActionDependency(stateAction, flexCardAssessmentInfo) {
+        const actionName = stateAction.name || stateAction.displayName || 'Unnamed Vlocity Action';
+        if (!flexCardAssessmentInfo.dependenciesVlocityAction.includes(actionName)) {
+            flexCardAssessmentInfo.dependenciesVlocityAction.push(actionName);
+        }
+        const warning = this.messages.getMessage('vlocityActionNotSupportedMessage', [actionName]);
+        if (!flexCardAssessmentInfo.warnings.includes(warning)) {
+            flexCardAssessmentInfo.warnings.push(warning);
+        }
+        flexCardAssessmentInfo.migrationStatus = (0, stringUtils_1.getUpdatedAssessmentStatus)(flexCardAssessmentInfo.migrationStatus, 'Needs manual intervention');
+    }
     // ==================== End Assessment Helper Methods ====================
     getCardFields() {
         return this.IS_STANDARD_DATA_MODEL
@@ -1789,4 +2221,5 @@ exports.CardMigrationTool = CardMigrationTool;
 CardMigrationTool.VLOCITYCARD_NAME = 'VlocityCard__c';
 CardMigrationTool.OMNIUICARD_NAME = 'OmniUiCard';
 CardMigrationTool.VERSION_PROP = 'Version__c';
+CardMigrationTool.URL_PARSE_BASE = 'https://placeholder.local';
 //# sourceMappingURL=flexcard.js.map