@devicecloud.dev/dcd 4.4.9 → 5.0.0-beta.1

package/dist/services/device-validation.service.d.ts

@@ -1,4 +1,4 @@
-import { CompatibilityData } from '../utils/compatibility';
+import { CompatibilityData } from '../utils/compatibility.js';
 export interface DeviceValidationOptions {
     debug?: boolean;
     logger?: (message: string) => void;
@@ -28,4 +28,12 @@ export declare class DeviceValidationService {
      * @throws Error if device/version combination is not supported
      */
     validateiOSDevice(iOSVersion: string | undefined, iOSDevice: string | undefined, compatibilityData: CompatibilityData, options?: DeviceValidationOptions): void;
+    /**
+     * Shared validation flow for both platforms: apply the default device,
+     * look up its supported versions, then check the requested version
+     * @param config Platform-specific lookup table, defaults, and messages
+     * @returns void
+     * @throws Error if device/version combination is not supported
+     */
+    private validateDevice;
 }

package/dist/services/device-validation.service.js

@@ -1,10 +1,7 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DeviceValidationService = void 0;
 /**
  * Service for validating device configurations against compatibility data
  */
-class DeviceValidationService {
+export class DeviceValidationService {
     /**
      * Validate Android device configuration
      * @param androidApiLevel Android API level to validate
@@ -16,29 +13,24 @@ class DeviceValidationService {
      * @throws Error if device/API level combination is not supported
      */
     validateAndroidDevice(androidApiLevel, androidDevice, googlePlay, compatibilityData, options = {}) {
-        const { debug = false, logger } = options;
-        if (!androidApiLevel && !androidDevice) {
-            return;
-        }
-        const androidDeviceID = androidDevice || 'pixel-7';
-        const lookup = googlePlay
-            ? compatibilityData.androidPlay
-            : compatibilityData.android;
-        const supportedAndroidVersions = lookup?.[androidDeviceID] || [];
-        const version = androidApiLevel || '34';
-        if (supportedAndroidVersions.length === 0) {
-            throw new Error(`We don't support that device configuration - please check the docs for supported devices: https://docs.devicecloud.dev/getting-started/devices-configuration`);
-        }
-        if (Array.isArray(supportedAndroidVersions) &&
-            !supportedAndroidVersions.includes(version)) {
-            throw new Error(`${androidDeviceID} ${googlePlay ? '(Play Store) ' : ''}only supports these Android API levels: ${supportedAndroidVersions.join(', ')}`);
-        }
-        if (debug && logger) {
-            logger(`[DEBUG] Android device: ${androidDeviceID}`);
-            logger(`[DEBUG] Android API level: ${version}`);
-            logger(`[DEBUG] Google Play enabled: ${googlePlay}`);
-            logger(`[DEBUG] Supported Android versions: ${supportedAndroidVersions.join(', ')}`);
-        }
+        this.validateDevice({
+            debugLines: (deviceID, version, supportedVersions) => [
+                `[DEBUG] Android device: ${deviceID}`,
+                `[DEBUG] Android API level: ${version}`,
+                `[DEBUG] Google Play enabled: ${googlePlay}`,
+                `[DEBUG] Supported Android versions: ${supportedVersions.join(', ')}`,
+            ],
+            defaultDevice: 'pixel-7',
+            defaultVersion: '34',
+            device: androidDevice,
+            lookup: googlePlay
+                ? compatibilityData.androidPlay
+                : compatibilityData.android,
+            noSupportMessage: () => `We don't support that device configuration - please check the docs for supported devices: https://docs.devicecloud.dev/getting-started/devices-configuration`,
+            options,
+            unsupportedVersionMessage: (deviceID, supportedVersions) => `${deviceID} ${googlePlay ? '(Play Store) ' : ''}only supports these Android API levels: ${supportedVersions.join(', ')}`,
+            version: androidApiLevel,
+        });
     }
     /**
      * Validate iOS device configuration
@@ -50,25 +42,49 @@ class DeviceValidationService {
      * @throws Error if device/version combination is not supported
      */
     validateiOSDevice(iOSVersion, iOSDevice, compatibilityData, options = {}) {
+        this.validateDevice({
+            debugLines: (deviceID, version, supportedVersions) => [
+                `[DEBUG] iOS device: ${deviceID}`,
+                `[DEBUG] iOS version: ${version}`,
+                `[DEBUG] Supported iOS versions: ${supportedVersions.join(', ')}`,
+            ],
+            defaultDevice: 'iphone-14',
+            defaultVersion: '17',
+            device: iOSDevice,
+            lookup: compatibilityData?.ios,
+            noSupportMessage: (deviceID) => `Device ${deviceID} is not supported. Please check the docs for supported devices: https://docs.devicecloud.dev/getting-started/devices-configuration`,
+            options,
+            unsupportedVersionMessage: (deviceID, supportedVersions) => `${deviceID} only supports these iOS versions: ${supportedVersions.join(', ')}`,
+            version: iOSVersion,
+        });
+    }
+    /**
+     * Shared validation flow for both platforms: apply the default device,
+     * look up its supported versions, then check the requested version
+     * @param config Platform-specific lookup table, defaults, and messages
+     * @returns void
+     * @throws Error if device/version combination is not supported
+     */
+    validateDevice(config) {
+        const { debugLines, defaultDevice, defaultVersion, device, lookup, noSupportMessage, options, unsupportedVersionMessage, version, } = config;
         const { debug = false, logger } = options;
-        if (!iOSVersion && !iOSDevice) {
+        if (!version && !device) {
             return;
         }
-        const iOSDeviceID = iOSDevice || 'iphone-14';
-        const supportediOSVersions = compatibilityData?.ios?.[iOSDeviceID] || [];
-        const version = iOSVersion || '17';
-        if (supportediOSVersions.length === 0) {
-            throw new Error(`Device ${iOSDeviceID} is not supported. Please check the docs for supported devices: https://docs.devicecloud.dev/getting-started/devices-configuration`);
+        const deviceID = device || defaultDevice;
+        const supportedVersions = lookup?.[deviceID] || [];
+        const requestedVersion = version || defaultVersion;
+        if (supportedVersions.length === 0) {
+            throw new Error(noSupportMessage(deviceID));
         }
-        if (Array.isArray(supportediOSVersions) &&
-            !supportediOSVersions.includes(version)) {
-            throw new Error(`${iOSDeviceID} only supports these iOS versions: ${supportediOSVersions.join(', ')}`);
+        if (Array.isArray(supportedVersions) &&
+            !supportedVersions.includes(requestedVersion)) {
+            throw new Error(unsupportedVersionMessage(deviceID, supportedVersions));
         }
         if (debug && logger) {
-            logger(`[DEBUG] iOS device: ${iOSDeviceID}`);
-            logger(`[DEBUG] iOS version: ${version}`);
-            logger(`[DEBUG] Supported iOS versions: ${supportediOSVersions.join(', ')}`);
+            for (const line of debugLines(deviceID, requestedVersion, supportedVersions)) {
+                logger(line);
+            }
         }
     }
 }
-exports.DeviceValidationService = DeviceValidationService;

package/dist/services/execution-plan.service.js

@@ -1,10 +1,6 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.plan = plan;
-const glob_1 = require("glob");
-const fs = require("node:fs");
-const path = require("node:path");
-const execution_plan_utils_1 = require("./execution-plan.utils");
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { getFlowsToRunInSequence, isFlowFile, processDependencies, readDirectory, readTestYamlFileAsJson, readYamlFileAsJson, } from './execution-plan.utils.js';
 /**
  * Recursively check and resolve all dependencies for a flow file
  * Includes runFlow references, JavaScript scripts, and media files
@@ -17,8 +13,8 @@ async function checkDependencies(input) {
     const uncheckedDependencies = [input];
     while (uncheckedDependencies.length > 0) {
         const fileToCheck = uncheckedDependencies.shift();
-        const { config, testSteps } = (0, execution_plan_utils_1.readTestYamlFileAsJson)(fileToCheck);
-        const { allErrors, allFiles } = (0, execution_plan_utils_1.processDependencies)({
+        const { config, testSteps } = readTestYamlFileAsJson(fileToCheck);
+        const { allErrors, allFiles } = processDependencies({
             config,
             input: fileToCheck,
             testSteps,
@@ -28,7 +24,7 @@ async function checkDependencies(input) {
                 allErrors.join('\n'));
         }
         for (const file of allFiles) {
-            if (!(0, execution_plan_utils_1.isFlowFile)(file)) {
+            if (!isFlowFile(file)) {
                 // js/media files don't have dependencies
                 checkedDependencies.push(file);
             }
@@ -64,7 +60,7 @@ function getWorkspaceConfig(input, unfilteredFlowFiles) {
     const possibleConfigPaths = new Set([path.join(input, 'config.yaml'), path.join(input, 'config.yml')].map((p) => path.normalize(p)));
     const configFilePath = unfilteredFlowFiles.find((file) => possibleConfigPaths.has(path.normalize(file)));
     const config = configFilePath
-        ? (0, execution_plan_utils_1.readYamlFileAsJson)(configFilePath)
+        ? readYamlFileAsJson(configFilePath)
         : {};
     return config;
 }
@@ -100,7 +96,7 @@ async function planSingleFile(normalizedInput, configFile) {
         normalizedInput.endsWith('config.yml')) {
         throw new Error('If using config.yaml, pass the workspace folder path, not the config file or a custom path via --config');
     }
-    const { config } = (0, execution_plan_utils_1.readTestYamlFileAsJson)(normalizedInput);
+    const { config } = readTestYamlFileAsJson(normalizedInput);
     const flowMetadata = {};
     const flowOverrides = {};
     if (config) {
@@ -113,7 +109,7 @@ async function planSingleFile(normalizedInput, configFile) {
         if (!fs.existsSync(configFilePath)) {
             throw new Error(`Config file does not exist: ${configFilePath}`);
         }
-        workspaceConfig = (0, execution_plan_utils_1.readYamlFileAsJson)(configFilePath);
+        workspaceConfig = readYamlFileAsJson(configFilePath);
     }
     const checkedDependancies = await checkDependencies(normalizedInput);
     return {
@@ -131,16 +127,24 @@ async function planSingleFile(normalizedInput, configFile) {
  * @param normalizedInput - Normalized path to the workspace directory
  * @param unfilteredFlowFiles - List of all discovered flow files
  * @param configFile - Optional custom config file path
+ * @param excludeFlows - --exclude-flows patterns to re-apply to glob matches
  * @returns Filtered list of flow file paths matching the globs
  */
-async function applyFlowGlobs(workspaceConfig, normalizedInput, unfilteredFlowFiles, configFile) {
+async function applyFlowGlobs(workspaceConfig, normalizedInput, unfilteredFlowFiles, configFile, excludeFlows) {
     if (workspaceConfig.flows) {
         const globs = workspaceConfig.flows.map((g) => g);
-        const matchedFiles = await (0, glob_1.glob)(globs, {
-            cwd: normalizedInput,
-            nodir: true,
+        // fs.globSync lands in Node 22; the CLI's `engines.node` already requires it.
+        // No `nodir` option — we strip directories with a stat check below.
+        const allMatches = fs.globSync(globs, { cwd: normalizedInput });
+        const matchedFiles = allMatches.filter((file) => {
+            try {
+                return fs.statSync(path.resolve(normalizedInput, file)).isFile();
+            }
+            catch {
+                return false;
+            }
         });
-        return matchedFiles
+        const globbedFlowFiles = matchedFiles
             .filter((file) => {
             if (file === 'config.yaml' || file === 'config.yml')
                 return false;
@@ -156,6 +160,9 @@ async function applyFlowGlobs(workspaceConfig, normalizedInput, unfilteredFlowFi
             return true;
         })
             .map((file) => path.resolve(normalizedInput, file));
+        // Re-globbing from disk bypasses the earlier --exclude-flows filter, so
+        // re-apply it here or excluded flows sneak back in via `flows:` globs.
+        return filterFlowFiles(globbedFlowFiles, excludeFlows);
     }
     return unfilteredFlowFiles.filter((file) => !file.endsWith('config.yaml') &&
         !file.endsWith('config.yml') &&
@@ -176,14 +183,16 @@ function resolveSequentialFlows(workspaceConfig, pathsByName, debug) {
         console.log('[DEBUG] executionOrder.flowsOrder:', workspaceConfig.executionOrder.flowsOrder);
         console.log('[DEBUG] Available flow names:', Object.keys(pathsByName));
     }
-    const flowsToRunInSequence = workspaceConfig.executionOrder.flowsOrder
-        .flatMap((flowOrder) => {
-        const normalizedFlowOrder = flowOrder.replace(/\.ya?ml$/i, '');
-        if (debug && flowOrder !== normalizedFlowOrder) {
-            console.log(`[DEBUG] Stripping trailing extension: "${flowOrder}" -> "${normalizedFlowOrder}"`);
-        }
-        return (0, execution_plan_utils_1.getFlowsToRunInSequence)(pathsByName, [normalizedFlowOrder], debug);
-    });
+    // Dedupe so a flow listed twice in flowsOrder isn't run twice.
+    const flowsToRunInSequence = [
+        ...new Set(workspaceConfig.executionOrder.flowsOrder.flatMap((flowOrder) => {
+            const normalizedFlowOrder = flowOrder.replace(/\.ya?ml$/i, '');
+            if (debug && flowOrder !== normalizedFlowOrder) {
+                console.log(`[DEBUG] Stripping trailing extension: "${flowOrder}" -> "${normalizedFlowOrder}"`);
+            }
+            return getFlowsToRunInSequence(pathsByName, [normalizedFlowOrder], debug);
+        })),
+    ];
     if (debug) {
         console.log(`[DEBUG] Sequential flows resolved: ${flowsToRunInSequence.length} flow(s)`);
     }
@@ -213,7 +222,7 @@ function resolveSequentialFlows(workspaceConfig, pathsByName, debug) {
  * @returns Complete execution plan with flows, dependencies, and metadata
  * @throws Error if input path doesn't exist, no flows found, or dependencies missing
  */
-async function plan(options) {
+export async function plan(options) {
     const { input, includeTags = [], excludeTags = [], excludeFlows, configFile, debug = false, } = options;
     const normalizedInput = path.normalize(input);
     const flowMetadata = {};
@@ -223,7 +232,7 @@ async function plan(options) {
     if (fs.lstatSync(normalizedInput).isFile()) {
         return planSingleFile(normalizedInput, configFile);
     }
-    let unfilteredFlowFiles = await (0, execution_plan_utils_1.readDirectory)(normalizedInput, execution_plan_utils_1.isFlowFile);
+    let unfilteredFlowFiles = await readDirectory(normalizedInput, isFlowFile);
     if (unfilteredFlowFiles.length === 0) {
         throw new Error(`Flow directory does not contain any Flow files: ${path.resolve(normalizedInput)}`);
     }
@@ -234,12 +243,12 @@ async function plan(options) {
         if (!fs.existsSync(configFilePath)) {
             throw new Error(`Config file does not exist: ${configFilePath}`);
         }
-        workspaceConfig = (0, execution_plan_utils_1.readYamlFileAsJson)(configFilePath);
+        workspaceConfig = readYamlFileAsJson(configFilePath);
     }
     else {
         workspaceConfig = getWorkspaceConfig(normalizedInput, unfilteredFlowFiles);
     }
-    unfilteredFlowFiles = await applyFlowGlobs(workspaceConfig, normalizedInput, unfilteredFlowFiles, configFile);
+    unfilteredFlowFiles = await applyFlowGlobs(workspaceConfig, normalizedInput, unfilteredFlowFiles, configFile, excludeFlows);
     if (unfilteredFlowFiles.length === 0) {
         const error = workspaceConfig.flows
             ? new Error(`Flow inclusion pattern(s) did not match any Flow files:\n${workspaceConfig.flows.join('\n')}`)
@@ -248,7 +257,7 @@ async function plan(options) {
     }
     // eslint-disable-next-line unicorn/no-array-reduce
     const configPerFlowFile = unfilteredFlowFiles.reduce((acc, filePath) => {
-        const { config } = (0, execution_plan_utils_1.readTestYamlFileAsJson)(filePath);
+        const { config } = readTestYamlFileAsJson(filePath);
         acc[filePath] = config;
         return acc;
     }, {});

package/dist/services/execution-plan.utils.d.ts

@@ -6,6 +6,9 @@ export declare const readYamlFileAsJson: (filePath: string) => unknown;
 export declare const readTestYamlFileAsJson: (filePath: string) => {
     config: Record<string, unknown>;
     testSteps: Record<string, unknown>[];
+} | {
+    config: null;
+    testSteps: Record<string, unknown>[];
 };
 export declare function readDirectory(dir: string, filterFunction?: (filePath: string) => boolean): Promise<string[]>;
 export declare const checkIfFilesExistInWorkspace: (commandName: string, command: Record<string, string> | string | string[], absoluteFilePath: string) => {

package/dist/services/execution-plan.utils.js

@@ -1,60 +1,33 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.processDependencies = exports.checkIfFilesExistInWorkspace = exports.readTestYamlFileAsJson = exports.readYamlFileAsJson = void 0;
-exports.getFlowsToRunInSequence = getFlowsToRunInSequence;
-exports.isFlowFile = isFlowFile;
-exports.readDirectory = readDirectory;
-const yaml = require("js-yaml");
-const fs = require("node:fs");
-const path = require("node:path");
+import * as yaml from 'js-yaml';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
 const commandsThatRequireFiles = new Set(['addMedia', 'runFlow', 'runScript']);
-function getFlowsToRunInSequence(paths, flowOrder, debug = false) {
+export function getFlowsToRunInSequence(paths, flowOrder, debug = false) {
     if (flowOrder.length === 0) {
         if (debug) {
             console.log('[DEBUG] getFlowsToRunInSequence: flowOrder is empty, returning []');
         }
         return [];
     }
-    const orderSet = new Set(flowOrder);
     const availableNames = Object.keys(paths);
     if (debug) {
-        console.log(`[DEBUG] getFlowsToRunInSequence: Looking for flows in order: [${[...orderSet].join(', ')}]`);
+        console.log(`[DEBUG] getFlowsToRunInSequence: Looking for flows in order: [${flowOrder.join(', ')}]`);
         console.log(`[DEBUG] getFlowsToRunInSequence: Available flow names: [${availableNames.join(', ')}]`);
     }
-    const namesInOrder = availableNames.filter((key) => orderSet.has(key));
+    const namesInOrder = flowOrder.filter((name) => Object.hasOwn(paths, name));
     if (debug) {
         console.log(`[DEBUG] getFlowsToRunInSequence: Matched ${namesInOrder.length} flow(s): [${namesInOrder.join(', ')}]`);
     }
     if (namesInOrder.length === 0) {
-        const notFound = [...orderSet].filter((item) => !availableNames.includes(item));
+        const notFound = flowOrder.filter((name) => !availableNames.includes(name));
         console.warn(`Warning: Could not find flows specified in executionOrder.flowsOrder: ${notFound.join(', ')}\n` +
             `This may be intentional if flows were excluded by tags.\n` +
             `Available flow names:\n${availableNames.join('\n')}`);
         return [];
     }
-    const result = [...orderSet].filter((item) => namesInOrder.includes(item));
-    if (result.length === 0) {
-        const notFound = [...orderSet].filter((item) => !namesInOrder.includes(item));
-        console.warn(`Warning: Could not find flows needed for execution in order: ${notFound.join(', ')}\n` +
-            `This may be intentional if flows were excluded by tags.\n` +
-            `Available flow names:\n${availableNames.join('\n')}`);
-        return [];
-    }
-    if (flowOrder
-        .slice(0, result.length)
-        .every((value, index) => value === result[index])) {
-        const resolvedPaths = result.map((item) => paths[item]);
-        if (debug) {
-            console.log(`[DEBUG] getFlowsToRunInSequence: Order matches, returning ${resolvedPaths.length} path(s)`);
-        }
-        return resolvedPaths;
-    }
-    throw new Error(`Flow order mismatch in executionOrder.flowsOrder.\n\n` +
-        `Expected order: [${flowOrder.slice(0, result.length).join(', ')}]\n` +
-        `Actual order: [${result.join(', ')}]\n\n` +
-        `Please ensure flows are specified in the correct order.`);
+    return namesInOrder.map((name) => paths[name]);
 }
-function isFlowFile(filePath) {
+export function isFlowFile(filePath) {
     // Exclude files inside .app bundles
     // Check if any directory in the path ends with .app
     const pathParts = filePath.split(path.sep);
@@ -65,7 +38,7 @@ function isFlowFile(filePath) {
     }
     return filePath.endsWith('.yaml') || filePath.endsWith('.yml');
 }
-const readYamlFileAsJson = (filePath) => {
+export const readYamlFileAsJson = (filePath) => {
     try {
         const normalizedPath = path.normalize(filePath);
         const yamlText = fs.readFileSync(normalizedPath, 'utf8');
@@ -82,11 +55,12 @@ const readYamlFileAsJson = (filePath) => {
         return result;
     }
     catch (error) {
-        throw new Error(`Error parsing YAML file ${filePath}: ${error}`);
+        throw new Error(`Error parsing YAML file ${filePath}: ${error}`, {
+            cause: error,
+        });
     }
 };
-exports.readYamlFileAsJson = readYamlFileAsJson;
-const readTestYamlFileAsJson = (filePath) => {
+export const readTestYamlFileAsJson = (filePath) => {
     try {
         const normalizedPath = path.normalize(filePath);
         const yamlText = fs.readFileSync(normalizedPath, 'utf8');
@@ -96,25 +70,23 @@ const readTestYamlFileAsJson = (filePath) => {
         if (normalizedText.includes('\n---\n')) {
             const yamlTexts = normalizedText.split('\n---\n');
             const config = yaml.load(yamlTexts[0]);
-            const testSteps = yaml.load(yamlTexts[1]);
-            if (Object.keys(config ?? {}).length > 0) {
+            // Rejoin everything after the first separator so step documents beyond
+            // a second `---` aren't silently dropped.
+            const testSteps = yaml.load(yamlTexts.slice(1).join('\n'));
+            if (config && Object.keys(config).length > 0) {
                 return { config, testSteps };
             }
         }
         const testSteps = yaml.load(yamlText);
-        if (Object.keys(testSteps).length > 0) {
-            return { config: null, testSteps };
-        }
         return { config: null, testSteps };
     }
     catch (error) {
         const message = `Error parsing YAML file ${filePath}: ${error}`;
         console.error(message);
-        throw new Error(message);
+        throw new Error(message, { cause: error });
     }
 };
-exports.readTestYamlFileAsJson = readTestYamlFileAsJson;
-async function readDirectory(dir, filterFunction) {
+export async function readDirectory(dir, filterFunction) {
     const readDirResult = await fs.promises.readdir(dir);
     const files = await Promise.all(readDirResult.map(async (file) => {
         const filePath = path.join(dir, file);
@@ -130,7 +102,7 @@ async function readDirectory(dir, filterFunction) {
     }));
     return files.flat().filter(Boolean);
 }
-const checkIfFilesExistInWorkspace = (commandName, command, absoluteFilePath) => {
+export const checkIfFilesExistInWorkspace = (commandName, command, absoluteFilePath) => {
     const errors = [];
     const files = [];
     const directory = path.dirname(absoluteFilePath);
@@ -142,9 +114,9 @@ const checkIfFilesExistInWorkspace = (commandName, command, absoluteFilePath) =>
             errors.push(buildError(error));
         files.push(absoluteFilePath);
     };
-    // simple command
+    // simple command — processFilePath already resolves against `directory`
     if (typeof command === 'string') {
-        processFilePath(path.normalize(path.join(directory, command)));
+        processFilePath(command);
     }
     // array command
     if (Array.isArray(command)) {
@@ -158,7 +130,6 @@ const checkIfFilesExistInWorkspace = (commandName, command, absoluteFilePath) =>
         processFilePath(x.file);
     return { errors, files };
 };
-exports.checkIfFilesExistInWorkspace = checkIfFilesExistInWorkspace;
 const checkFile = (filePath) => {
     if (!fs.existsSync(filePath))
         return `non-existent file`;
@@ -171,7 +142,7 @@ const checkStepsArray = (steps, absoluteFilePath) => {
             continue;
         for (const [commandName, commandValue] of Object.entries(command)) {
             if (commandsThatRequireFiles.has(commandName)) {
-                const { errors: newErrors, files: newFiles } = (0, exports.checkIfFilesExistInWorkspace)(commandName, commandValue, path.normalize(absoluteFilePath));
+                const { errors: newErrors, files: newFiles } = checkIfFilesExistInWorkspace(commandName, commandValue, path.normalize(absoluteFilePath));
                 errors = [...errors, ...newErrors];
                 files = [...files, ...newFiles];
             }
@@ -186,7 +157,7 @@ const checkStepsArray = (steps, absoluteFilePath) => {
     }
     return { errors, files };
 };
-const processDependencies = ({ config, input, testSteps, }) => {
+export const processDependencies = ({ config, input, testSteps, }) => {
     let allErrors = [];
     let allFiles = [];
     const { onFlowComplete, onFlowStart } = config ?? {};
@@ -208,4 +179,3 @@ const processDependencies = ({ config, input, testSteps, }) => {
     }
     return { allErrors, allFiles };
 };
-exports.processDependencies = processDependencies;

package/dist/services/flow-paths.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Longest whole-segment directory prefix shared by every flow + referenced
+ * file path. Segment comparison (not `startsWith`) so sibling dirs like
+ * `flows`/`flows-extra` can't merge, and the file segment itself is never
+ * consumed. Returns '' when the paths share no root at all (or none are given).
+ */
+export declare function computeCommonRoot(testFileNames: string[], referencedFiles: string[]): string;
+export interface FlowMetadataEntry {
+    flowName: string;
+    tags: string[];
+}
+/**
+ * Build the portable-relative-path → {flowName, tags} map that results are
+ * keyed by. Flow name comes from the YAML `name` field, falling back to the
+ * filename without extension; tags are normalized to a string array.
+ */
+export declare function buildTestMetadataMap(flowMetadata: Record<string, Record<string, unknown> | null>, commonRoot: string): Record<string, FlowMetadataEntry>;

package/dist/services/flow-paths.js

@@ -0,0 +1,52 @@
+/**
+ * Pure helpers for turning absolute flow paths into the server-side relative
+ * keys that submission, the polling layer, and JSON output all share.
+ *
+ * Extracted from the cloud command so the MCP `dcd_run_cloud_test` tool builds
+ * byte-identical paths without duplicating the logic.
+ */
+import * as path from 'node:path';
+import { toPortableRelativePath } from '../utils/paths.js';
+/**
+ * Longest whole-segment directory prefix shared by every flow + referenced
+ * file path. Segment comparison (not `startsWith`) so sibling dirs like
+ * `flows`/`flows-extra` can't merge, and the file segment itself is never
+ * consumed. Returns '' when the paths share no root at all (or none are given).
+ */
+export function computeCommonRoot(testFileNames, referencedFiles) {
+    const pathsShortestToLongest = [...testFileNames, ...referencedFiles].sort((a, b) => a.split(path.sep).length - b.split(path.sep).length);
+    if (pathsShortestToLongest.length === 0)
+        return '';
+    const splitPaths = pathsShortestToLongest.map((p) => p.split(path.sep));
+    const shortestSegments = splitPaths[0];
+    let matchedSegments = 0;
+    for (let i = 0; i < shortestSegments.length - 1; i++) {
+        if (splitPaths.every((segments) => segments[i] === shortestSegments[i])) {
+            matchedSegments = i + 1;
+        }
+        else {
+            break;
+        }
+    }
+    return shortestSegments.slice(0, matchedSegments).join(path.sep);
+}
+/**
+ * Build the portable-relative-path → {flowName, tags} map that results are
+ * keyed by. Flow name comes from the YAML `name` field, falling back to the
+ * filename without extension; tags are normalized to a string array.
+ */
+export function buildTestMetadataMap(flowMetadata, commonRoot) {
+    const map = {};
+    for (const [absolutePath, meta] of Object.entries(flowMetadata)) {
+        const normalizedPath = toPortableRelativePath(absolutePath, commonRoot);
+        const flowName = meta?.name || path.parse(absolutePath).name;
+        const rawTags = meta?.tags;
+        const tags = Array.isArray(rawTags)
+            ? rawTags.map(String)
+            : rawTags
+                ? [String(rawTags)]
+                : [];
+        map[normalizedPath] = { flowName, tags };
+    }
+    return map;
+}

package/dist/services/metadata-extractor.service.d.ts

@@ -22,7 +22,6 @@ export declare class AndroidMetadataExtractor implements IMetadataExtractor {
 export declare class IosAppMetadataExtractor implements IMetadataExtractor {
     canHandle(filePath: string): boolean;
     extract(filePath: string): Promise<TAppMetadata>;
-    private parseInfoPlist;
 }
 /**
  * Extracts metadata from iOS .zip files containing .app bundles
@@ -30,7 +29,6 @@ export declare class IosAppMetadataExtractor implements IMetadataExtractor {
 export declare class IosZipMetadataExtractor implements IMetadataExtractor {
     canHandle(filePath: string): boolean;
     extract(filePath: string): Promise<TAppMetadata>;
-    private parseInfoPlist;
 }
 /**
  * Extracts metadata from Expo iOS .tar.gz archives by extracting the