@browserstack/mcp-server 1.2.3 → 1.2.5

package/dist/tools/sdk-utils/common/device-validator.js

@@ -0,0 +1,368 @@
+import { getDevicesAndBrowsers, BrowserStackProducts, } from "../../../lib/device-cache.js";
+import { resolveVersion } from "../../../lib/version-resolver.js";
+import { customFuzzySearch } from "../../../lib/fuzzy.js";
+import { SDKSupportedBrowserAutomationFrameworkEnum } from "./types.js";
+const DEFAULTS = {
+    windows: { browser: "chrome" },
+    macos: { browser: "safari" },
+    android: { device: "Samsung Galaxy S24", browser: "chrome" },
+    ios: { device: "iPhone 15", browser: "safari" },
+};
+// ============================================================================
+// AUTOMATE SECTION (Desktop + Mobile for BrowserStack SDK)
+// ============================================================================
+// Helper functions to build device entries and eliminate duplication
+function buildDesktopEntries(automateData) {
+    if (!automateData.desktop) {
+        return [];
+    }
+    return automateData.desktop.flatMap((platform) => platform.browsers.map((browser) => ({
+        os: platform.os,
+        os_version: platform.os_version,
+        browser: browser.browser,
+        browser_version: browser.browser_version,
+    })));
+}
+function buildMobileEntries(appAutomateData, platform) {
+    if (!appAutomateData.mobile) {
+        return [];
+    }
+    return appAutomateData.mobile
+        .filter((group) => group.os === platform)
+        .flatMap((group) => group.devices.map((device) => ({
+        os: group.os,
+        os_version: device.os_version,
+        display_name: device.display_name,
+        browsers: device.browsers || [
+            {
+                browser: device.browser || (platform === "android" ? "chrome" : "safari"),
+            },
+        ],
+    })));
+}
+// Performance optimization: Create indexed maps for faster lookups
+function createDesktopIndex(entries) {
+    const byOS = new Map();
+    const byOSVersion = new Map();
+    const byBrowser = new Map();
+    const nested = new Map();
+    for (const entry of entries) {
+        // Index by OS
+        if (!byOS.has(entry.os)) {
+            byOS.set(entry.os, []);
+        }
+        byOS.get(entry.os).push(entry);
+        // Index by OS version
+        if (!byOSVersion.has(entry.os_version)) {
+            byOSVersion.set(entry.os_version, []);
+        }
+        byOSVersion.get(entry.os_version).push(entry);
+        // Index by browser
+        if (!byBrowser.has(entry.browser)) {
+            byBrowser.set(entry.browser, []);
+        }
+        byBrowser.get(entry.browser).push(entry);
+        // Build nested index: Map<os, Map<os_version, Map<browser, DesktopBrowserEntry[]>>>
+        if (!nested.has(entry.os)) {
+            nested.set(entry.os, new Map());
+        }
+        const osMap = nested.get(entry.os);
+        if (!osMap.has(entry.os_version)) {
+            osMap.set(entry.os_version, new Map());
+        }
+        const osVersionMap = osMap.get(entry.os_version);
+        if (!osVersionMap.has(entry.browser)) {
+            osVersionMap.set(entry.browser, []);
+        }
+        osVersionMap.get(entry.browser).push(entry);
+    }
+    return { byOS, byOSVersion, byBrowser, nested };
+}
+function createMobileIndex(entries) {
+    const byPlatform = new Map();
+    const byDeviceName = new Map();
+    const byOSVersion = new Map();
+    for (const entry of entries) {
+        // Index by platform
+        if (!byPlatform.has(entry.os)) {
+            byPlatform.set(entry.os, []);
+        }
+        byPlatform.get(entry.os).push(entry);
+        // Index by device name (case-insensitive)
+        const deviceKey = entry.display_name.toLowerCase();
+        if (!byDeviceName.has(deviceKey)) {
+            byDeviceName.set(deviceKey, []);
+        }
+        byDeviceName.get(deviceKey).push(entry);
+        // Index by OS version
+        if (!byOSVersion.has(entry.os_version)) {
+            byOSVersion.set(entry.os_version, []);
+        }
+        byOSVersion.get(entry.os_version).push(entry);
+    }
+    return { byPlatform, byDeviceName, byOSVersion };
+}
+export async function validateDevices(devices, framework) {
+    const validatedEnvironments = [];
+    if (!devices || devices.length === 0) {
+        // Use centralized default fallback
+        return [
+            {
+                platform: "windows",
+                osVersion: "11",
+                browser: DEFAULTS.windows.browser,
+                browserVersion: "latest",
+            },
+        ];
+    }
+    // Determine what data we need to fetch
+    const needsDesktop = devices.some((env) => ["windows", "macos"].includes((env[0] || "").toLowerCase()));
+    const needsMobile = devices.some((env) => ["android", "ios"].includes((env[0] || "").toLowerCase()));
+    // Fetch data using framework-specific endpoint for both desktop and mobile
+    let deviceData = null;
+    try {
+        if (needsDesktop || needsMobile) {
+            if (framework === SDKSupportedBrowserAutomationFrameworkEnum.playwright) {
+                deviceData = (await getDevicesAndBrowsers(BrowserStackProducts.PLAYWRIGHT_AUTOMATE));
+            }
+            else {
+                deviceData = (await getDevicesAndBrowsers(BrowserStackProducts.SELENIUM_AUTOMATE));
+            }
+        }
+    }
+    catch (error) {
+        throw new Error(`Failed to fetch device data: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    // Preprocess data into indexed maps for better performance
+    let desktopIndex = null;
+    let androidIndex = null;
+    let iosIndex = null;
+    if (needsDesktop && deviceData) {
+        const desktopEntries = buildDesktopEntries(deviceData);
+        desktopIndex = createDesktopIndex(desktopEntries);
+    }
+    if (needsMobile && deviceData) {
+        const androidEntries = buildMobileEntries(deviceData, "android");
+        const iosEntries = buildMobileEntries(deviceData, "ios");
+        androidIndex = createMobileIndex(androidEntries);
+        iosIndex = createMobileIndex(iosEntries);
+    }
+    for (const env of devices) {
+        const discriminator = (env[0] || "").toLowerCase();
+        let validatedEnv;
+        if (discriminator === "windows") {
+            validatedEnv = validateDesktopEnvironment(env, desktopIndex, "windows", DEFAULTS.windows.browser);
+        }
+        else if (discriminator === "macos") {
+            validatedEnv = validateDesktopEnvironment(env, desktopIndex, "macos", DEFAULTS.macos.browser);
+        }
+        else if (discriminator === "android") {
+            validatedEnv = validateMobileEnvironment(env, androidIndex, "android", DEFAULTS.android.device, DEFAULTS.android.browser);
+        }
+        else if (discriminator === "ios") {
+            validatedEnv = validateMobileEnvironment(env, iosIndex, "ios", DEFAULTS.ios.device, DEFAULTS.ios.browser);
+        }
+        else {
+            throw new Error(`Unsupported platform: ${discriminator}`);
+        }
+        validatedEnvironments.push(validatedEnv);
+    }
+    return validatedEnvironments;
+}
+// Optimized desktop validation using nested indexed maps for O(1) lookups
+function validateDesktopEnvironment(env, index, platform, defaultBrowser) {
+    const [, osVersion, browser, browserVersion] = env;
+    const osKey = platform === "windows" ? "Windows" : "OS X";
+    // Use nested index for O(1) lookup instead of filtering
+    const osMap = index.nested.get(osKey);
+    if (!osMap) {
+        throw new Error(`No ${platform} devices available`);
+    }
+    // Get available OS versions for this platform
+    const availableOSVersions = Array.from(osMap.keys());
+    const validatedOSVersion = resolveVersion(osVersion || "latest", availableOSVersions);
+    // Use nested index for O(1) lookup
+    const osVersionMap = osMap.get(validatedOSVersion);
+    if (!osVersionMap) {
+        throw new Error(`OS version "${validatedOSVersion}" not available for ${platform}`);
+    }
+    // Get available browsers for this OS version
+    const availableBrowsers = Array.from(osVersionMap.keys());
+    const validatedBrowser = validateBrowserExact(browser || defaultBrowser, availableBrowsers);
+    // Use nested index for O(1) lookup
+    const browserEntries = osVersionMap.get(validatedBrowser);
+    if (!browserEntries || browserEntries.length === 0) {
+        throw new Error(`Browser "${validatedBrowser}" not available for ${platform} ${validatedOSVersion}`);
+    }
+    const availableBrowserVersions = [
+        ...new Set(browserEntries.map((e) => e.browser_version)),
+    ];
+    const validatedBrowserVersion = resolveVersion(browserVersion || "latest", availableBrowserVersions);
+    return {
+        platform,
+        osVersion: validatedOSVersion,
+        browser: validatedBrowser,
+        browserVersion: validatedBrowserVersion,
+    };
+}
+// Optimized mobile validation using indexed maps
+function validateMobileEnvironment(env, index, platform, defaultDevice, defaultBrowser) {
+    const [, deviceName, osVersion, browser] = env;
+    const platformEntries = index.byPlatform.get(platform) || [];
+    if (platformEntries.length === 0) {
+        throw new Error(`No ${platform} devices available`);
+    }
+    // Use fuzzy search only for device names (as suggested in feedback)
+    const deviceMatches = customFuzzySearch(platformEntries, ["display_name"], deviceName || defaultDevice, 5);
+    if (deviceMatches.length === 0) {
+        throw new Error(`No ${platform} devices matching "${deviceName}". Available devices: ${platformEntries
+            .map((d) => d.display_name || "unknown")
+            .slice(0, 5)
+            .join(", ")}`);
+    }
+    // Try to find exact match first
+    const exactMatch = deviceMatches.find((m) => m.display_name.toLowerCase() === (deviceName || "").toLowerCase());
+    // If no exact match, throw error instead of using fuzzy match
+    if (!exactMatch) {
+        const suggestions = deviceMatches.map((m) => m.display_name).join(", ");
+        throw new Error(`Device "${deviceName}" not found exactly for ${platform}. Available similar devices: ${suggestions}. Please use the exact device name.`);
+    }
+    // Use index for faster filtering
+    const deviceKey = exactMatch.display_name.toLowerCase();
+    const deviceFiltered = index.byDeviceName.get(deviceKey) || [];
+    const availableOSVersions = [
+        ...new Set(deviceFiltered.map((d) => d.os_version)),
+    ];
+    const validatedOSVersion = resolveVersion(osVersion || "latest", availableOSVersions);
+    // Use index for faster filtering
+    const osVersionEntries = index.byOSVersion.get(validatedOSVersion) || [];
+    const osFiltered = osVersionEntries.filter((d) => d.display_name.toLowerCase() === deviceKey);
+    // Validate browser if provided - use exact matching for browsers
+    let validatedBrowser = browser || defaultBrowser;
+    if (browser && osFiltered.length > 0) {
+        // Extract browsers more carefully - handle different possible structures
+        const availableBrowsers = [
+            ...new Set(osFiltered.flatMap((d) => {
+                if (d.browsers && Array.isArray(d.browsers)) {
+                    // If browsers is an array of objects with browser property
+                    return d.browsers
+                        .map((b) => {
+                        // Use display_name for user-friendly browser names, fallback to browser field
+                        return b.display_name || b.browser;
+                    })
+                        .filter(Boolean);
+                }
+                // For mobile devices, provide default browsers if none found
+                return platform === "android" ? ["chrome"] : ["safari"];
+            })),
+        ].filter(Boolean);
+        if (availableBrowsers.length > 0) {
+            try {
+                validatedBrowser = validateBrowserExact(browser, availableBrowsers);
+            }
+            catch (error) {
+                // Add more context to browser validation errors
+                throw new Error(`Failed to validate browser "${browser}" for ${platform} device "${exactMatch.display_name}" on OS version "${validatedOSVersion}". ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        else {
+            // For mobile, if no specific browsers found, just use the requested browser
+            // as most mobile devices support standard browsers
+            validatedBrowser = browser || defaultBrowser;
+        }
+    }
+    return {
+        platform,
+        osVersion: validatedOSVersion,
+        deviceName: exactMatch.display_name,
+        browser: validatedBrowser,
+    };
+}
+// ============================================================================
+// APP AUTOMATE SECTION (Mobile devices for App Automate)
+// ============================================================================
+export async function validateAppAutomateDevices(devices) {
+    const validatedDevices = [];
+    if (!devices || devices.length === 0) {
+        // Use centralized default fallback
+        return [
+            {
+                platform: "android",
+                osVersion: "latest",
+                deviceName: DEFAULTS.android.device,
+            },
+        ];
+    }
+    let appAutomateData;
+    try {
+        // Fetch app automate device data
+        appAutomateData = (await getDevicesAndBrowsers(BrowserStackProducts.APP_AUTOMATE));
+    }
+    catch (error) {
+        // Only wrap fetch-related errors
+        throw new Error(`Failed to fetch device data: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    for (const device of devices) {
+        // Parse device array in format ["android", "Device Name", "OS Version"]
+        const [platform, deviceName, osVersion] = device;
+        // Find matching device in the data
+        let validatedDevice = null;
+        if (!appAutomateData.mobile) {
+            throw new Error("No mobile device data available");
+        }
+        // Filter by platform first
+        const platformGroup = appAutomateData.mobile.find((group) => group.os === platform.toLowerCase());
+        if (!platformGroup) {
+            throw new Error(`Platform "${platform}" not supported for App Automate`);
+        }
+        const platformDevices = platformGroup.devices;
+        // Find exact device name match (case-insensitive)
+        const exactMatch = platformDevices.find((d) => d.display_name.toLowerCase() === deviceName.toLowerCase());
+        if (exactMatch) {
+            // Check if the OS version is available for this device
+            const deviceVersions = platformDevices
+                .filter((d) => d.display_name === exactMatch.display_name)
+                .map((d) => d.os_version);
+            const validatedOSVersion = resolveVersion(osVersion || "latest", deviceVersions);
+            validatedDevice = {
+                platform: platformGroup.os,
+                osVersion: validatedOSVersion,
+                deviceName: exactMatch.display_name,
+            };
+        }
+        if (!validatedDevice) {
+            // If no exact match found, suggest similar devices from the SAME platform only
+            const platformDevicesForSearch = platformDevices.map((d) => ({
+                ...d,
+                platform: platformGroup.os,
+            }));
+            // Try fuzzy search with a more lenient threshold
+            const deviceMatches = customFuzzySearch(platformDevicesForSearch, ["display_name"], deviceName, 5, 0.8);
+            const suggestions = deviceMatches
+                .map((m) => `${m.display_name}`)
+                .join(", ");
+            // If no fuzzy matches, show some available devices as fallback
+            const fallbackDevices = platformDevicesForSearch
+                .slice(0, 5)
+                .map((d) => d.display_name)
+                .join(", ");
+            const errorMessage = suggestions
+                ? `Device "${deviceName}" not found for platform "${platform}".\nAvailable similar devices: ${suggestions}`
+                : `Device "${deviceName}" not found for platform "${platform}".\nAvailable devices: ${fallbackDevices}`;
+            throw new Error(errorMessage);
+        }
+        validatedDevices.push(validatedDevice);
+    }
+    return validatedDevices;
+}
+// ============================================================================
+// SHARED UTILITY FUNCTIONS
+// ============================================================================
+// Exact browser validation (preferred for structured fields)
+function validateBrowserExact(requestedBrowser, availableBrowsers) {
+    const exactMatch = availableBrowsers.find((b) => b.toLowerCase() === requestedBrowser.toLowerCase());
+    if (exactMatch) {
+        return exactMatch;
+    }
+    throw new Error(`Browser "${requestedBrowser}" not found. Available options: ${availableBrowsers.join(", ")}`);
+}

package/dist/tools/sdk-utils/common/formatUtils.d.ts

@@ -0,0 +1,5 @@
+export declare function formatInstructionsWithNumbers(instructionText: string, separator?: string): {
+    formattedSteps: string;
+    stepCount: number;
+};
+export declare function generateVerificationMessage(stepCount: number): string;

package/dist/tools/sdk-utils/common/formatUtils.js

@@ -0,0 +1,27 @@
+export function formatInstructionsWithNumbers(instructionText, separator = "---STEP---") {
+    // Split the instructions by the separator
+    const steps = instructionText
+        .split(separator)
+        .map((step) => step.trim())
+        .filter((step) => step.length > 0);
+    // If no separators found, treat the entire text as one step
+    if (steps.length === 1 && !instructionText.includes(separator)) {
+        return {
+            formattedSteps: `**Step 1:**\n${instructionText.trim()}`,
+            stepCount: 1,
+        };
+    }
+    // Format each step with numbering
+    const formattedSteps = steps
+        .map((step, index) => {
+        return `**Step ${index + 1}:**\n${step.trim()}`;
+    })
+        .join("\n\n");
+    return {
+        formattedSteps,
+        stepCount: steps.length,
+    };
+}
+export function generateVerificationMessage(stepCount) {
+    return `**✅ Verification:**\nPlease verify that you have completed all ${stepCount} steps above to ensure proper setup. If you encounter any issues, double-check each step and ensure all commands executed successfully.`;
+}

package/dist/tools/sdk-utils/common/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export * from "./constants.js";
+export * from "./formatUtils.js";

package/dist/tools/sdk-utils/common/index.js

@@ -0,0 +1,4 @@
+// Common utilities and types for SDK tools
+export * from "./types.js";
+export * from "./constants.js";
+export * from "./formatUtils.js";

package/dist/tools/sdk-utils/common/instructionUtils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Core instruction configuration utilities for runTestsOnBrowserStack tool.
+ */
+import { SDKSupportedLanguage, SDKSupportedBrowserAutomationFramework, SDKSupportedTestingFramework } from "./types.js";
+export declare const getInstructionsForProjectConfiguration: (detectedBrowserAutomationFramework: SDKSupportedBrowserAutomationFramework, detectedTestingFramework: SDKSupportedTestingFramework, detectedLanguage: SDKSupportedLanguage, username: string, accessKey: string) => {
+    setup: string;
+    run: string;
+};

package/dist/tools/sdk-utils/common/instructionUtils.js

@@ -0,0 +1,20 @@
+/**
+ * Core instruction configuration utilities for runTestsOnBrowserStack tool.
+ */
+import { SUPPORTED_CONFIGURATIONS } from "../bstack/frameworks.js";
+const errorMessageSuffix = "Please open an issue at our Github repo: https://github.com/browserstack/browserstack-mcp-server/issues to request support for your project configuration";
+export const getInstructionsForProjectConfiguration = (detectedBrowserAutomationFramework, detectedTestingFramework, detectedLanguage, username, accessKey) => {
+    const configuration = SUPPORTED_CONFIGURATIONS[detectedLanguage];
+    if (!configuration) {
+        throw new Error(`BrowserStack MCP Server currently does not support ${detectedLanguage}, ${errorMessageSuffix}`);
+    }
+    if (!configuration[detectedBrowserAutomationFramework]) {
+        throw new Error(`BrowserStack MCP Server currently does not support ${detectedBrowserAutomationFramework} for ${detectedLanguage}, ${errorMessageSuffix}`);
+    }
+    if (!configuration[detectedBrowserAutomationFramework][detectedTestingFramework]) {
+        throw new Error(`BrowserStack MCP Server currently does not support ${detectedTestingFramework} for ${detectedBrowserAutomationFramework} on ${detectedLanguage}, ${errorMessageSuffix}`);
+    }
+    const instructionFunction = configuration[detectedBrowserAutomationFramework][detectedTestingFramework]
+        .instructions;
+    return instructionFunction(username, accessKey);
+};

package/dist/tools/sdk-utils/common/schema.d.ts

@@ -0,0 +1,93 @@
+import { z } from "zod";
+import { PercyIntegrationTypeEnum } from "./types.js";
+import { SDKSupportedBrowserAutomationFrameworkEnum, SDKSupportedTestingFrameworkEnum, SDKSupportedLanguageEnum } from "./types.js";
+export declare const PlatformEnum: {
+    readonly WINDOWS: "windows";
+    readonly MACOS: "macos";
+    readonly ANDROID: "android";
+    readonly IOS: "ios";
+};
+export declare const WindowsPlatformEnum: {
+    readonly WINDOWS: "windows";
+};
+export declare const MacOSPlatformEnum: {
+    readonly MACOS: "macos";
+};
+export declare const SetUpPercyParamsShape: {
+    projectName: z.ZodString;
+    detectedLanguage: z.ZodNativeEnum<typeof SDKSupportedLanguageEnum>;
+    detectedBrowserAutomationFramework: z.ZodNativeEnum<typeof SDKSupportedBrowserAutomationFrameworkEnum>;
+    detectedTestingFramework: z.ZodNativeEnum<typeof SDKSupportedTestingFrameworkEnum>;
+    integrationType: z.ZodNativeEnum<typeof PercyIntegrationTypeEnum>;
+    folderPaths: z.ZodArray<z.ZodString, "many">;
+};
+export declare const RunTestsOnBrowserStackParamsShape: {
+    projectName: z.ZodString;
+    detectedLanguage: z.ZodNativeEnum<typeof SDKSupportedLanguageEnum>;
+    detectedBrowserAutomationFramework: z.ZodNativeEnum<typeof SDKSupportedBrowserAutomationFrameworkEnum>;
+    detectedTestingFramework: z.ZodNativeEnum<typeof SDKSupportedTestingFrameworkEnum>;
+    devices: z.ZodDefault<z.ZodArray<z.ZodUnion<[z.ZodTuple<[z.ZodNativeEnum<{
+        readonly WINDOWS: "windows";
+    }>, z.ZodString, z.ZodString, z.ZodString], null>, z.ZodTuple<[z.ZodLiteral<"android">, z.ZodString, z.ZodString, z.ZodString], null>, z.ZodTuple<[z.ZodLiteral<"ios">, z.ZodString, z.ZodString, z.ZodString], null>, z.ZodTuple<[z.ZodNativeEnum<{
+        readonly MACOS: "macos";
+    }>, z.ZodString, z.ZodString, z.ZodString], null>]>, "many">>;
+};
+export declare const SetUpPercySchema: z.ZodObject<{
+    projectName: z.ZodString;
+    detectedLanguage: z.ZodNativeEnum<typeof SDKSupportedLanguageEnum>;
+    detectedBrowserAutomationFramework: z.ZodNativeEnum<typeof SDKSupportedBrowserAutomationFrameworkEnum>;
+    detectedTestingFramework: z.ZodNativeEnum<typeof SDKSupportedTestingFrameworkEnum>;
+    integrationType: z.ZodNativeEnum<typeof PercyIntegrationTypeEnum>;
+    folderPaths: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    projectName: string;
+    detectedLanguage: SDKSupportedLanguageEnum;
+    detectedBrowserAutomationFramework: SDKSupportedBrowserAutomationFrameworkEnum;
+    detectedTestingFramework: SDKSupportedTestingFrameworkEnum;
+    integrationType: PercyIntegrationTypeEnum;
+    folderPaths: string[];
+}, {
+    projectName: string;
+    detectedLanguage: SDKSupportedLanguageEnum;
+    detectedBrowserAutomationFramework: SDKSupportedBrowserAutomationFrameworkEnum;
+    detectedTestingFramework: SDKSupportedTestingFrameworkEnum;
+    integrationType: PercyIntegrationTypeEnum;
+    folderPaths: string[];
+}>;
+export declare const RunTestsOnBrowserStackSchema: z.ZodObject<{
+    projectName: z.ZodString;
+    detectedLanguage: z.ZodNativeEnum<typeof SDKSupportedLanguageEnum>;
+    detectedBrowserAutomationFramework: z.ZodNativeEnum<typeof SDKSupportedBrowserAutomationFrameworkEnum>;
+    detectedTestingFramework: z.ZodNativeEnum<typeof SDKSupportedTestingFrameworkEnum>;
+    devices: z.ZodDefault<z.ZodArray<z.ZodUnion<[z.ZodTuple<[z.ZodNativeEnum<{
+        readonly WINDOWS: "windows";
+    }>, z.ZodString, z.ZodString, z.ZodString], null>, z.ZodTuple<[z.ZodLiteral<"android">, z.ZodString, z.ZodString, z.ZodString], null>, z.ZodTuple<[z.ZodLiteral<"ios">, z.ZodString, z.ZodString, z.ZodString], null>, z.ZodTuple<[z.ZodNativeEnum<{
+        readonly MACOS: "macos";
+    }>, z.ZodString, z.ZodString, z.ZodString], null>]>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    projectName: string;
+    detectedLanguage: SDKSupportedLanguageEnum;
+    detectedBrowserAutomationFramework: SDKSupportedBrowserAutomationFrameworkEnum;
+    detectedTestingFramework: SDKSupportedTestingFrameworkEnum;
+    devices: (["windows", string, string, string] | ["android", string, string, string] | ["ios", string, string, string] | ["macos", string, string, string])[];
+}, {
+    projectName: string;
+    detectedLanguage: SDKSupportedLanguageEnum;
+    detectedBrowserAutomationFramework: SDKSupportedBrowserAutomationFrameworkEnum;
+    detectedTestingFramework: SDKSupportedTestingFrameworkEnum;
+    devices?: (["windows", string, string, string] | ["android", string, string, string] | ["ios", string, string, string] | ["macos", string, string, string])[] | undefined;
+}>;
+export type SetUpPercyInput = z.infer<typeof SetUpPercySchema>;
+export type RunTestsOnBrowserStackInput = z.infer<typeof RunTestsOnBrowserStackSchema>;
+export declare const RunPercyScanParamsShape: {
+    projectName: z.ZodString;
+    percyRunCommand: z.ZodOptional<z.ZodString>;
+    integrationType: z.ZodNativeEnum<typeof PercyIntegrationTypeEnum>;
+};
+export declare const FetchPercyChangesParamsShape: {
+    project_name: z.ZodString;
+};
+export declare const ManagePercyBuildApprovalParamsShape: {
+    buildId: z.ZodString;
+    action: z.ZodEnum<["approve", "unapprove", "reject"]>;
+};

package/dist/tools/sdk-utils/common/schema.js

@@ -0,0 +1,105 @@
+import { z } from "zod";
+import { PercyIntegrationTypeEnum } from "./types.js";
+import { SDKSupportedBrowserAutomationFrameworkEnum, SDKSupportedTestingFrameworkEnum, SDKSupportedLanguageEnum, } from "./types.js";
+// Platform enums for better validation
+export const PlatformEnum = {
+    WINDOWS: "windows",
+    MACOS: "macos",
+    ANDROID: "android",
+    IOS: "ios",
+};
+export const WindowsPlatformEnum = {
+    WINDOWS: "windows",
+};
+export const MacOSPlatformEnum = {
+    MACOS: "macos",
+};
+export const SetUpPercyParamsShape = {
+    projectName: z.string().describe("A unique name for your Percy project."),
+    detectedLanguage: z.nativeEnum(SDKSupportedLanguageEnum),
+    detectedBrowserAutomationFramework: z.nativeEnum(SDKSupportedBrowserAutomationFrameworkEnum),
+    detectedTestingFramework: z.nativeEnum(SDKSupportedTestingFrameworkEnum),
+    integrationType: z
+        .nativeEnum(PercyIntegrationTypeEnum)
+        .describe("Specify the Percy integration type: web (Percy Web) or automate (Percy Automate). If not provided, always prompt the user with: 'Please specify the Percy integration type.' Do not proceed without an explicit selection. Never use a default."),
+    folderPaths: z
+        .array(z.string())
+        .describe("An array of absolute folder paths containing UI test files. If not provided, analyze codebase for UI test folders by scanning for test patterns which contain UI test cases as per framework. Return empty array if none found."),
+};
+export const RunTestsOnBrowserStackParamsShape = {
+    projectName: z
+        .string()
+        .describe("A single name for your project to organize all your tests."),
+    detectedLanguage: z.nativeEnum(SDKSupportedLanguageEnum),
+    detectedBrowserAutomationFramework: z.nativeEnum(SDKSupportedBrowserAutomationFrameworkEnum),
+    detectedTestingFramework: z.nativeEnum(SDKSupportedTestingFrameworkEnum),
+    devices: z
+        .array(z.union([
+        // Windows: [windows, osVersion, browser, browserVersion]
+        z.tuple([
+            z
+                .nativeEnum(WindowsPlatformEnum)
+                .describe("Platform identifier: 'windows'"),
+            z.string().describe("Windows version, e.g. '10', '11'"),
+            z.string().describe("Browser name, e.g. 'chrome', 'firefox', 'edge'"),
+            z
+                .string()
+                .describe("Browser version, e.g. '132', 'latest', 'oldest'"),
+        ]),
+        // Android: [android, name, model, osVersion, browser]
+        z.tuple([
+            z
+                .literal(PlatformEnum.ANDROID)
+                .describe("Platform identifier: 'android'"),
+            z
+                .string()
+                .describe("Device name, e.g. 'Samsung Galaxy S24', 'Google Pixel 8'"),
+            z.string().describe("Android version, e.g. '14', '16', 'latest'"),
+            z.string().describe("Browser name, e.g. 'chrome', 'samsung browser'"),
+        ]),
+        // iOS: [ios, name, model, osVersion, browser]
+        z.tuple([
+            z.literal(PlatformEnum.IOS).describe("Platform identifier: 'ios'"),
+            z.string().describe("Device name, e.g. 'iPhone 12 Pro'"),
+            z.string().describe("iOS version, e.g. '17', 'latest'"),
+            z.string().describe("Browser name, typically 'safari'"),
+        ]),
+        // macOS: [mac|macos, name, model, browser, browserVersion]
+        z.tuple([
+            z
+                .nativeEnum(MacOSPlatformEnum)
+                .describe("Platform identifier: 'mac' or 'macos'"),
+            z.string().describe("macOS version name, e.g. 'Sequoia', 'Ventura'"),
+            z.string().describe("Browser name, e.g. 'safari', 'chrome'"),
+            z.string().describe("Browser version, e.g. 'latest'"),
+        ]),
+    ]))
+        .max(3)
+        .default([])
+        .describe("Preferred tuples of target devices.Add device only when user asks explicitly for it. Defaults to [] . Example: [['windows', '11', 'chrome', 'latest']]"),
+};
+export const SetUpPercySchema = z.object(SetUpPercyParamsShape);
+export const RunTestsOnBrowserStackSchema = z.object(RunTestsOnBrowserStackParamsShape);
+export const RunPercyScanParamsShape = {
+    projectName: z.string().describe("The name of the project to run Percy on."),
+    percyRunCommand: z
+        .string()
+        .optional()
+        .describe("The test command to run with Percy. Optional — the LLM should try to infer it first from project context."),
+    integrationType: z
+        .nativeEnum(PercyIntegrationTypeEnum)
+        .describe("Specifies whether to integrate with Percy Web or Percy Automate. If not explicitly provided, prompt the user to select the desired integration type."),
+};
+export const FetchPercyChangesParamsShape = {
+    project_name: z
+        .string()
+        .describe("The name of the BrowserStack project. If not found, ask user directly."),
+};
+export const ManagePercyBuildApprovalParamsShape = {
+    buildId: z
+        .string()
+        .describe("The ID of the Percy build to approve or reject."),
+    action: z
+        .enum(["approve", "unapprove", "reject"])
+        .describe("The action to perform on the Percy build."),
+};