@simplysf/simply-utam-core 0.0.0 → 0.1.0

package/lib/navigator.js

@@ -14,7 +14,20 @@
  * limitations under the License.
  */
 import { applicationPath, newRecordPath, recordPath, relatedListPath } from './lightning-paths.js';
-import { TestEnvironment } from './test-environment.js';
+import { getTestEnvironment } from './test-environment.js';
+/**
+ * Resolves an active browser instance from explicit parameters or the global runtime context.
+ *
+ * @param browserInstance - Optional explicit browser instance.
+ * @returns The resolved NavigableBrowser instance.
+ */
+export function resolveBrowser(browserInstance) {
+    const resolved = browserInstance ?? (typeof browser !== 'undefined' ? browser : undefined);
+    if (!resolved || typeof resolved.navigateTo !== 'function') {
+        throw new Error('No browser to navigate: pass one as the `browser` option, or run inside WebdriverIO so the global `browser` exists');
+    }
+    return resolved;
+}
 /**
  * Logs the browser in to the test org and opens a Lightning page in one step. Every navigation
  * goes through a fresh frontdoor URL, so each one also works as the first thing a test does.
@@ -28,43 +41,48 @@ export class LightningNavigator {
      * @param options The environment and browser to use; both have defaults.
      */
     constructor(options = {}) {
-        this.#environment = options.environment ?? new TestEnvironment();
+        this.#environment = options.environment ?? getTestEnvironment();
         this.#browser = options.browser;
     }
     /**
      * Log in and open `returnUrl`, or the org's default landing page when it is omitted.
      *
      * @param returnUrl Path to open after login.
+     * @returns The resolved frontdoor URL navigated to.
      */
     async goToLoginUrl(returnUrl) {
         const url = await this.#environment.buildFrontdoorUrl(returnUrl);
-        await this.#resolveBrowser().navigateTo(url);
+        await this.resolveBrowser().navigateTo(url);
+        return url;
     }
     /**
      * Log in and open a Lightning app's home page.
      *
      * @param applicationName The app's developer name; see `lightningAppName` for namespacing.
+     * @returns The resolved application URL.
      */
     async goToApplication(applicationName) {
-        await this.goToLoginUrl(applicationPath(applicationName));
+        return this.goToLoginUrl(applicationPath(applicationName));
     }
     /**
      * Log in and open the new-record form for an object.
      *
      * @param applicationName The app's developer name.
      * @param objectApiName The object's API name.
+     * @returns The resolved record creation URL.
      */
     async goToCreateNewRecord(applicationName, objectApiName) {
-        await this.goToLoginUrl(newRecordPath(applicationName, objectApiName));
+        return this.goToLoginUrl(newRecordPath(applicationName, objectApiName));
     }
     /**
      * Log in and open a record's detail page.
      *
      * @param applicationName The app's developer name.
      * @param recordId The record's id.
+     * @returns The resolved record view URL.
      */
     async goToRecord(applicationName, recordId) {
-        await this.goToLoginUrl(recordPath(applicationName, recordId));
+        return this.goToLoginUrl(recordPath(applicationName, recordId));
     }
     /**
      * Log in and open one of a record's related lists.
@@ -72,16 +90,210 @@ export class LightningNavigator {
      * @param applicationName The app's developer name.
      * @param recordId The parent record's id.
      * @param relatedListName The relationship name.
+     * @returns The resolved related list URL.
      */
     async goToRelatedList(applicationName, recordId, relatedListName) {
-        await this.goToLoginUrl(relatedListPath(applicationName, recordId, relatedListName));
+        return this.goToLoginUrl(relatedListPath(applicationName, recordId, relatedListName));
     }
-    #resolveBrowser() {
-        const browser = this.#browser ?? globalThis.browser;
-        if (!browser) {
-            throw new Error('No browser to navigate: pass one as the `browser` option, or run inside WebdriverIO so the global `browser` exists');
+    /**
+     * Navigates the browser to a specific Experience Cloud site page via UI Bridge frontdoor login.
+     *
+     * @param sitePrefix - The URL prefix of the Experience site.
+     * @param pageName - The Experience page name (relative to /s/).
+     * @returns The resolved Experience frontdoor URL navigated to.
+     */
+    async goToExperiencePage(sitePrefix, pageName) {
+        const cleanPageName = pageName.startsWith('/') ? pageName.slice(1) : pageName;
+        let frontdoorUrl;
+        if (typeof this.#environment.buildExperienceFrontdoorUrl === 'function') {
+            frontdoorUrl = await this.#environment.buildExperienceFrontdoorUrl(sitePrefix, `/s/${cleanPageName}`);
+        }
+        else {
+            const env = getTestEnvironment();
+            frontdoorUrl = await env.buildExperienceFrontdoorUrl(sitePrefix, `/s/${cleanPageName}`);
         }
-        return browser;
+        await this.resolveBrowser().navigateTo(frontdoorUrl);
+        return frontdoorUrl;
+    }
+    /**
+     * Logs in as a specific user using Salesforce user impersonation.
+     *
+     * @param username - The target user's username.
+     * @param returnUrl - The target page to land on once logged in. Defaults to '/'.
+     * @returns The resolved impersonation redirect URL.
+     */
+    async loginAsUser(username, returnUrl = '/') {
+        const browserTarget = this.resolveBrowser();
+        await this.goToLoginUrl('/');
+        const env = this.#environment;
+        const orgId = typeof env.getOrgId === 'function' ? await env.getOrgId() : await getTestEnvironment().getOrgId();
+        const userId = typeof env.getUserIdByUsername === 'function'
+            ? await env.getUserIdByUsername(username)
+            : await getTestEnvironment().getUserIdByUsername(username);
+        const instanceUrl = typeof env.getInstanceUrl === 'function'
+            ? await env.getInstanceUrl()
+            : await getTestEnvironment().getInstanceUrl();
+        const loginAsUrl = `${instanceUrl}/servlet/servlet.su?oid=${orgId}&suorgadminid=${userId}&targetURL=${encodeURIComponent(returnUrl)}`;
+        await browserTarget.navigateTo(loginAsUrl);
+        return loginAsUrl;
     }
+    /**
+     * Logs in as a specific user and navigates directly to an Experience Cloud site.
+     *
+     * @param username - The target user's username.
+     * @param sitePrefix - The URL prefix of the Experience site.
+     * @param pageName - The Experience page name (relative to /s/).
+     * @returns The resolved Experience site page URL.
+     */
+    async loginAsExperienceUser(username, sitePrefix, pageName) {
+        const browserTarget = this.resolveBrowser();
+        await this.loginAsUser(username, '/');
+        const env = this.#environment;
+        const networkId = typeof env.getNetworkIdByPrefix === 'function'
+            ? await env.getNetworkIdByPrefix(sitePrefix)
+            : await getTestEnvironment().getNetworkIdByPrefix(sitePrefix);
+        const instanceUrl = typeof env.getInstanceUrl === 'function'
+            ? await env.getInstanceUrl()
+            : await getTestEnvironment().getInstanceUrl();
+        const networkSwitchUrl = `${instanceUrl}/servlet/networks/switch?networkId=${networkId}`;
+        await browserTarget.navigateTo(networkSwitchUrl);
+        const cleanPageName = pageName.startsWith('/') ? pageName.slice(1) : pageName;
+        const experienceUrl = typeof env.buildExperienceUrl === 'function'
+            ? await env.buildExperienceUrl(sitePrefix, `/s/${cleanPageName}`)
+            : await getTestEnvironment().buildExperienceUrl(sitePrefix, `/s/${cleanPageName}`);
+        await browserTarget.navigateTo(experienceUrl);
+        return experienceUrl;
+    }
+    resolveBrowser() {
+        return resolveBrowser(this.#browser);
+    }
+}
+/**
+ * Functional helper: Navigates the browser to the Salesforce Frontdoor login URL.
+ *
+ * @param returnUrl - Optional landing page path after login.
+ * @param browserInstance - Optional browser instance overriding the global runner.
+ * @param testEnvironment - Optional TestEnvironment instance.
+ * @returns The resolved frontdoor URL navigated to.
+ */
+export async function goToLoginUrl(returnUrl, browserInstance, testEnvironment) {
+    const navigator = new LightningNavigator({
+        browser: browserInstance,
+        environment: testEnvironment,
+    });
+    return navigator.goToLoginUrl(returnUrl);
+}
+/**
+ * Functional helper: Navigates the browser to an Experience Cloud page.
+ *
+ * @param sitePrefix - The URL prefix of the Experience site.
+ * @param pageName - The Experience page name.
+ * @param browserInstance - Optional browser instance overriding the global runner.
+ * @param testEnvironment - Optional TestEnvironment instance.
+ * @returns The resolved Experience frontdoor URL navigated to.
+ */
+export async function goToExperiencePage(sitePrefix, pageName, browserInstance, testEnvironment) {
+    const navigator = new LightningNavigator({
+        browser: browserInstance,
+        environment: testEnvironment,
+    });
+    return navigator.goToExperiencePage(sitePrefix, pageName);
+}
+/**
+ * Functional helper: Logs in as a specific user using Salesforce user impersonation.
+ *
+ * @param username - The target user's username.
+ * @param returnUrl - Landing path after impersonation.
+ * @param browserInstance - Optional browser instance overriding the global runner.
+ * @param testEnvironment - Optional TestEnvironment instance.
+ * @returns The resolved impersonation redirect URL.
+ */
+export async function loginAsUser(username, returnUrl = '/', browserInstance, testEnvironment) {
+    const navigator = new LightningNavigator({
+        browser: browserInstance,
+        environment: testEnvironment,
+    });
+    return navigator.loginAsUser(username, returnUrl);
+}
+/**
+ * Functional helper: Logs in as a user and navigates directly to an Experience Cloud site.
+ *
+ * @param username - The target user's username.
+ * @param sitePrefix - The URL prefix of the Experience site.
+ * @param pageName - The Experience page name.
+ * @param browserInstance - Optional browser instance overriding the global runner.
+ * @param testEnvironment - Optional TestEnvironment instance.
+ * @returns The resolved Experience site page URL.
+ */
+export async function loginAsExperienceUser(username, sitePrefix, pageName, browserInstance, testEnvironment) {
+    const navigator = new LightningNavigator({
+        browser: browserInstance,
+        environment: testEnvironment,
+    });
+    return navigator.loginAsExperienceUser(username, sitePrefix, pageName);
+}
+/**
+ * Functional helper: Navigates to a standard Lightning Application home page.
+ *
+ * @param applicationName - The developer name of the Lightning application.
+ * @param browserInstance - Optional browser instance.
+ * @param testEnvironment - Optional TestEnvironment instance.
+ * @returns The resolved frontdoor application URL.
+ */
+export async function goToApplication(applicationName, browserInstance, testEnvironment) {
+    const navigator = new LightningNavigator({
+        browser: browserInstance,
+        environment: testEnvironment,
+    });
+    return navigator.goToApplication(applicationName);
+}
+/**
+ * Functional helper: Navigates to a new record creation page for a specific sObject in an application.
+ *
+ * @param applicationName - The developer name of the Lightning application.
+ * @param objectName - The API name of the sObject.
+ * @param browserInstance - Optional browser instance.
+ * @param testEnvironment - Optional TestEnvironment instance.
+ * @returns The resolved frontdoor URL.
+ */
+export async function goToCreateNewRecord(applicationName, objectName, browserInstance, testEnvironment) {
+    const navigator = new LightningNavigator({
+        browser: browserInstance,
+        environment: testEnvironment,
+    });
+    return navigator.goToCreateNewRecord(applicationName, objectName);
+}
+/**
+ * Functional helper: Navigates to a record view page in a Lightning application.
+ *
+ * @param applicationName - The developer name of the Lightning application.
+ * @param recordId - The 15 or 18 character Salesforce record ID.
+ * @param browserInstance - Optional browser instance.
+ * @param testEnvironment - Optional TestEnvironment instance.
+ * @returns The resolved frontdoor URL.
+ */
+export async function goToRecord(applicationName, recordId, browserInstance, testEnvironment) {
+    const navigator = new LightningNavigator({
+        browser: browserInstance,
+        environment: testEnvironment,
+    });
+    return navigator.goToRecord(applicationName, recordId);
+}
+/**
+ * Functional helper: Navigates to a related list view for a specific record in a Lightning application.
+ *
+ * @param applicationName - The developer name of the Lightning application.
+ * @param recordId - The 15 or 18 character parent record ID.
+ * @param relatedListName - The relationship name of the related list.
+ * @param browserInstance - Optional browser instance.
+ * @param testEnvironment - Optional TestEnvironment instance.
+ * @returns The resolved frontdoor URL.
+ */
+export async function goToRelatedList(applicationName, recordId, relatedListName, browserInstance, testEnvironment) {
+    const navigator = new LightningNavigator({
+        browser: browserInstance,
+        environment: testEnvironment,
+    });
+    return navigator.goToRelatedList(applicationName, recordId, relatedListName);
 }
 //# sourceMappingURL=navigator.js.map

package/lib/navigator.js.map

@@ -1 +1 @@
-{"version":3,"file":"navigator.js","sourceRoot":"","sources":["../src/navigator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACnG,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAmBxD;;;GAGG;AACH,MAAM,OAAO,kBAAkB;IACpB,YAAY,CAAqB;IACjC,QAAQ,CAAoB;IAErC;;;;OAIG;IACH,YAAmB,UAAqC,EAAE;QACxD,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,WAAW,IAAI,IAAI,eAAe,EAAE,CAAC;QACjE,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;IAClC,CAAC;IAED;;;;OAIG;IACI,KAAK,CAAC,YAAY,CAAC,SAAkB;QAC1C,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAC;QACjE,MAAM,IAAI,CAAC,eAAe,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IAC/C,CAAC;IAED;;;;OAIG;IACI,KAAK,CAAC,eAAe,CAAC,eAAuB;QAClD,MAAM,IAAI,CAAC,YAAY,CAAC,eAAe,CAAC,eAAe,CAAC,CAAC,CAAC;IAC5D,CAAC;IAED;;;;;OAKG;IACI,KAAK,CAAC,mBAAmB,CAAC,eAAuB,EAAE,aAAqB;QAC7E,MAAM,IAAI,CAAC,YAAY,CAAC,aAAa,CAAC,eAAe,EAAE,aAAa,CAAC,CAAC,CAAC;IACzE,CAAC;IAED;;;;;OAKG;IACI,KAAK,CAAC,UAAU,CAAC,eAAuB,EAAE,QAAgB;QAC/D,MAAM,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,eAAe,EAAE,QAAQ,CAAC,CAAC,CAAC;IACjE,CAAC;IAED;;;;;;OAMG;IACI,KAAK,CAAC,eAAe,CAAC,eAAuB,EAAE,QAAgB,EAAE,eAAuB;QAC7F,MAAM,IAAI,CAAC,YAAY,CAAC,eAAe,CAAC,eAAe,EAAE,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC;IACvF,CAAC;IAED,eAAe;QACb,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,IAAK,UAA6C,CAAC,OAAO,CAAC;QACxF,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CACb,oHAAoH,CACrH,CAAC;QACJ,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;CACF"}
+{"version":3,"file":"navigator.js","sourceRoot":"","sources":["../src/navigator.ts"],"names":[],"mappings":"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"}

package/lib/overrides/index.d.ts

@@ -0,0 +1 @@
+export * from './overrides-merger.js';

package/lib/overrides/index.js

@@ -0,0 +1,17 @@
+/*
+ * Copyright (c) 2026, SimplySF.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export * from './overrides-merger.js';
+//# sourceMappingURL=index.js.map

package/lib/overrides/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/overrides/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,cAAc,uBAAuB,CAAC"}

package/lib/overrides/overrides-merger.d.ts

@@ -0,0 +1,63 @@
+export interface ApplyOverridesOptions {
+    rootDir?: string;
+    sourceDirs?: string[];
+    dryRun?: boolean;
+    verbose?: boolean;
+}
+export interface OverrideChange {
+    elementName: string;
+    matchCount: number;
+}
+export interface FileOverrideResult {
+    overrideFilePath: string;
+    generatedUtamFilePath: string;
+    changes: OverrideChange[];
+    applied: boolean;
+    error?: string;
+}
+export interface ApplyOverridesResult {
+    scannedFilesCount: number;
+    modifiedFilesCount: number;
+    totalOverridesApplied: number;
+    dryRun: boolean;
+    results: FileOverrideResult[];
+}
+export interface UtamOverrideItem {
+    name: string;
+    element: Record<string, unknown>;
+}
+/**
+ * Detects indentation of a JSON string content (e.g. 2 spaces, 4 spaces, or tabs).
+ *
+ * @param content - Raw JSON string content.
+ * @returns Indentation string sequence (spaces or tab).
+ */
+export declare function detectIndentation(content: string): string;
+/**
+ * Recursively locates all *.utam-overrides.json files in a directory.
+ *
+ * @param dirPath - Directory to search within.
+ * @returns Array of absolute paths to discovered *.utam-overrides.json files.
+ */
+export declare function findUtamOverridesFiles(dirPath: string): string[];
+/**
+ * Recursively walks the UTAM JSON structure to find element nodes.
+ *
+ * @param node - Current AST node.
+ * @param callback - Function invoked for each element object encountered.
+ */
+export declare function walkElements(node: unknown, callback: (element: Record<string, unknown>) => void): void;
+/**
+ * Safely merges the override element properties into the target element.
+ *
+ * @param target - Target AST element node to mutate.
+ * @param source - Override properties to merge into target.
+ */
+export declare function mergeElements(target: Record<string, unknown>, source: Record<string, unknown>): void;
+/**
+ * Merges custom overrides from *.utam-overrides.json files into generated UTAM schemas.
+ *
+ * @param options - Override application options.
+ * @returns Summary of scanned and modified UTAM schemas.
+ */
+export declare function applyUtamOverrides(options?: ApplyOverridesOptions): ApplyOverridesResult;

package/lib/overrides/overrides-merger.js

@@ -0,0 +1,280 @@
+/*
+ * Copyright (c) 2026, SimplySF.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { discoverProject } from '../discovery/index.js';
+/**
+ * Detects indentation of a JSON string content (e.g. 2 spaces, 4 spaces, or tabs).
+ *
+ * @param content - Raw JSON string content.
+ * @returns Indentation string sequence (spaces or tab).
+ */
+export function detectIndentation(content) {
+    const match = content.match(/^[ \t]+(?=")/m);
+    return match ? match[0] : '    ';
+}
+/**
+ * Recursively locates all *.utam-overrides.json files in a directory.
+ *
+ * @param dirPath - Directory to search within.
+ * @returns Array of absolute paths to discovered *.utam-overrides.json files.
+ */
+export function findUtamOverridesFiles(dirPath) {
+    const filesList = [];
+    try {
+        if (!fs.existsSync(dirPath)) {
+            return filesList;
+        }
+        const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dirPath, entry.name);
+            if (entry.isDirectory()) {
+                const name = entry.name;
+                if (name !== 'node_modules' &&
+                    name !== '.git' &&
+                    name !== 'dist' &&
+                    name !== 'lib' &&
+                    name !== '.wireit' &&
+                    name !== 'pageObjects' &&
+                    name !== 'allure-results') {
+                    filesList.push(...findUtamOverridesFiles(fullPath));
+                }
+            }
+            else if (entry.isFile() && entry.name.endsWith('.utam-overrides.json')) {
+                filesList.push(fullPath);
+            }
+        }
+    }
+    catch {
+        // Gracefully ignore directory read errors
+    }
+    return filesList;
+}
+/**
+ * Recursively walks the UTAM JSON structure to find element nodes.
+ *
+ * @param node - Current AST node.
+ * @param callback - Function invoked for each element object encountered.
+ */
+export function walkElements(node, callback) {
+    if (!node || typeof node !== 'object') {
+        return;
+    }
+    if (Array.isArray(node)) {
+        for (const item of node) {
+            if (item && typeof item === 'object' && !Array.isArray(item)) {
+                const itemObj = item;
+                if (typeof itemObj['name'] === 'string') {
+                    callback(itemObj);
+                }
+                if (itemObj['elements']) {
+                    walkElements(itemObj['elements'], callback);
+                }
+                if (itemObj['shadow'] &&
+                    typeof itemObj['shadow'] === 'object' &&
+                    itemObj['shadow']['elements']) {
+                    walkElements(itemObj['shadow']['elements'], callback);
+                }
+            }
+        }
+        return;
+    }
+    const objNode = node;
+    if (objNode['elements']) {
+        walkElements(objNode['elements'], callback);
+    }
+    if (objNode['shadow'] &&
+        typeof objNode['shadow'] === 'object' &&
+        objNode['shadow']['elements']) {
+        walkElements(objNode['shadow']['elements'], callback);
+    }
+}
+/**
+ * Safely merges the override element properties into the target element.
+ *
+ * @param target - Target AST element node to mutate.
+ * @param source - Override properties to merge into target.
+ */
+export function mergeElements(target, source) {
+    for (const [key, val] of Object.entries(source)) {
+        if (val !== null && typeof val === 'object' && !Array.isArray(val)) {
+            if (typeof target[key] !== 'object' || target[key] === null || Array.isArray(target[key])) {
+                target[key] = {};
+            }
+            mergeElements(target[key], val);
+        }
+        else {
+            target[key] = val;
+        }
+    }
+}
+function applyItemsToUtam(utamJson, overrides) {
+    const changes = [];
+    let count = 0;
+    for (const item of overrides) {
+        if (!item || typeof item !== 'object' || Array.isArray(item)) {
+            continue;
+        }
+        const overrideItem = item;
+        const { name, element } = overrideItem;
+        if (typeof name !== 'string' || !element || typeof element !== 'object' || Array.isArray(element)) {
+            continue;
+        }
+        let matchCount = 0;
+        walkElements(utamJson, (elementNode) => {
+            if (elementNode['name'] === name) {
+                mergeElements(elementNode, element);
+                matchCount++;
+            }
+        });
+        if (matchCount > 0) {
+            count += matchCount;
+            changes.push({ elementName: name, matchCount });
+        }
+    }
+    return { changes, count };
+}
+function processSingleOverrideFile(overrideFile, dryRun) {
+    let overrides;
+    try {
+        overrides = JSON.parse(fs.readFileSync(overrideFile, 'utf-8'));
+    }
+    catch (err) {
+        return {
+            result: {
+                overrideFilePath: overrideFile,
+                generatedUtamFilePath: '',
+                changes: [],
+                applied: false,
+                error: `Failed to parse overrides file: ${err.message}`,
+            },
+            appliedCount: 0,
+        };
+    }
+    if (!Array.isArray(overrides)) {
+        return {
+            result: {
+                overrideFilePath: overrideFile,
+                generatedUtamFilePath: '',
+                changes: [],
+                applied: false,
+                error: 'Overrides content is not a JSON array',
+            },
+            appliedCount: 0,
+        };
+    }
+    const componentDir = path.dirname(overrideFile);
+    const componentName = path.basename(overrideFile).replace('.utam-overrides.json', '');
+    const generatedFilePath = path.join(componentDir, '__utam__', `${componentName}.utam.json`);
+    if (!fs.existsSync(generatedFilePath)) {
+        return {
+            result: {
+                overrideFilePath: overrideFile,
+                generatedUtamFilePath: generatedFilePath,
+                changes: [],
+                applied: false,
+                error: 'Target generated UTAM file does not exist',
+            },
+            appliedCount: 0,
+        };
+    }
+    let fileContent;
+    let utamJson;
+    try {
+        fileContent = fs.readFileSync(generatedFilePath, 'utf-8');
+        utamJson = JSON.parse(fileContent);
+    }
+    catch (err) {
+        return {
+            result: {
+                overrideFilePath: overrideFile,
+                generatedUtamFilePath: generatedFilePath,
+                changes: [],
+                applied: false,
+                error: `Failed to parse target UTAM JSON: ${err.message}`,
+            },
+            appliedCount: 0,
+        };
+    }
+    const { changes, count } = applyItemsToUtam(utamJson, overrides);
+    if (changes.length > 0) {
+        if (!dryRun) {
+            const indent = detectIndentation(fileContent);
+            const endsWithNewline = fileContent.endsWith('\n');
+            let outputContent = JSON.stringify(utamJson, null, indent);
+            if (endsWithNewline && !outputContent.endsWith('\n')) {
+                outputContent += '\n';
+            }
+            fs.writeFileSync(generatedFilePath, outputContent, 'utf-8');
+        }
+        return {
+            result: {
+                overrideFilePath: overrideFile,
+                generatedUtamFilePath: generatedFilePath,
+                changes,
+                applied: true,
+            },
+            appliedCount: count,
+        };
+    }
+    return {
+        result: {
+            overrideFilePath: overrideFile,
+            generatedUtamFilePath: generatedFilePath,
+            changes: [],
+            applied: false,
+        },
+        appliedCount: 0,
+    };
+}
+/**
+ * Merges custom overrides from *.utam-overrides.json files into generated UTAM schemas.
+ *
+ * @param options - Override application options.
+ * @returns Summary of scanned and modified UTAM schemas.
+ */
+export function applyUtamOverrides(options = {}) {
+    const rootDir = path.resolve(options.rootDir ?? process.cwd());
+    const dryRun = Boolean(options.dryRun);
+    let sourceDirs = options.sourceDirs;
+    if (!sourceDirs || sourceDirs.length === 0) {
+        const discovered = discoverProject(rootDir);
+        sourceDirs = discovered.packageDirectories.length > 0 ? discovered.packageDirectories : ['./sfdx-source'];
+    }
+    const allOverrideFiles = [];
+    for (const sourceDir of sourceDirs) {
+        const resolvedSource = path.isAbsolute(sourceDir) ? sourceDir : path.resolve(rootDir, sourceDir);
+        allOverrideFiles.push(...findUtamOverridesFiles(resolvedSource));
+    }
+    const uniqueOverrideFiles = Array.from(new Set(allOverrideFiles));
+    const result = {
+        scannedFilesCount: uniqueOverrideFiles.length,
+        modifiedFilesCount: 0,
+        totalOverridesApplied: 0,
+        dryRun,
+        results: [],
+    };
+    for (const overrideFile of uniqueOverrideFiles) {
+        const { result: fileResult, appliedCount } = processSingleOverrideFile(overrideFile, dryRun);
+        if (fileResult.applied) {
+            result.modifiedFilesCount++;
+            result.totalOverridesApplied += appliedCount;
+        }
+        result.results.push(fileResult);
+    }
+    return result;
+}
+//# sourceMappingURL=overrides-merger.js.map