@devicecloud.dev/dcd 5.5.0 → 5.6.0-beta.4

package/dist/mcp/tools/run-cloud-test.js

@@ -4,9 +4,11 @@ import { ApiError, ApiGateway } from '../../gateways/api-gateway.js';
 import { plan } from '../../services/execution-plan.service.js';
 import { computeCommonRoot, buildTestMetadataMap } from '../../services/flow-paths.js';
 import { DeviceValidationService } from '../../services/device-validation.service.js';
+import { platformFromAppFile } from '../../services/notices.service.js';
 import { TestSubmissionService } from '../../services/test-submission.service.js';
 import { VersionService } from '../../services/version.service.js';
 import { uploadBinary, uploadFlowZip, verifyAppZip } from '../../methods.js';
+import { refreshAuth } from '../../utils/auth.js';
 import { getCliVersion } from '../../utils/cli.js';
 import { fetchCompatibilityData } from '../../utils/compatibility.js';
 import { isEncryptionEnabled } from '../../utils/envelope.js';
@@ -100,8 +102,15 @@ export function registerRunCloudTest(server) {
         const cliVersion = getCliVersion();
         const compatibilityData = await fetchCompatibilityData(apiUrl, auth);
         const deviceValidation = new DeviceValidationService();
-        deviceValidation.validateiOSDevice(args.iosVersion, args.iosDevice, compatibilityData, { logger: logStderr });
-        deviceValidation.validateAndroidDevice(args.androidApiLevel, args.androidDevice, Boolean(args.googlePlay), compatibilityData, { logger: logStderr });
+        // Hints in validation errors name this tool's parameters, not CLI flags.
+        const argNames = {
+            androidApiLevel: 'androidApiLevel',
+            androidDevice: 'androidDevice',
+            iOSDevice: 'iosDevice',
+            iOSVersion: 'iosVersion',
+        };
+        deviceValidation.validateiOSDevice(args.iosVersion, args.iosDevice, compatibilityData, { argNames, logger: logStderr });
+        deviceValidation.validateAndroidDevice(args.androidApiLevel, args.androidDevice, Boolean(args.googlePlay), compatibilityData, { argNames, logger: logStderr });
         const resolvedMaestroVersion = new VersionService().resolveMaestroVersion(args.maestroVersion, compatibilityData, { logger: logStderr });
         // Directory inputs must end in a separator so the planner treats them
         // as a workspace rather than a single file.
@@ -120,7 +129,7 @@ export function registerRunCloudTest(server) {
             // stdout is the JSON-RPC channel — config warnings must go to stderr.
             warn: logStderr,
         });
-        const commonRoot = computeCommonRoot(executionPlan.flowsToRun, executionPlan.referencedFiles);
+        const commonRoot = computeCommonRoot(executionPlan.flowsToRun, executionPlan.referencedFiles, executionPlan.includedFiles);
         const testMetadataMap = buildTestMetadataMap(executionPlan.flowMetadata, commonRoot);
         if (args.dryRun) {
             return jsonResult({
@@ -162,6 +171,8 @@ export function registerRunCloudTest(server) {
         const { buffer, fields } = await testSubmissionService.buildTestPayload({
             apiUrl,
             appBinaryId,
+            // Picks the workspace config's per-platform disableAnimations.
+            appPlatform: args.appBinaryId ? undefined : platformFromAppFile(args.appFile),
             cliVersion,
             commonRoot,
             continueOnFailure,
@@ -221,8 +232,13 @@ export function registerRunCloudTest(server) {
         // Bounded poll. The run continues in the cloud regardless of timeout —
         // the caller can resume with dcd_get_status using the returned uploadId.
         const deadline = Date.now() + (args.waitTimeoutSeconds ?? 600) * 1000;
+        let pollAuth = auth;
         for (;;) {
-            const status = await ApiGateway.getUploadStatus(apiUrl, auth, { uploadId });
+            // A wait of up to an hour can outlast a `dcd login` access token.
+            pollAuth = await refreshAuth(pollAuth);
+            const status = await ApiGateway.getUploadStatus(apiUrl, pollAuth, {
+                uploadId,
+            });
             if (TERMINAL_STATUSES.has(status.status)) {
                 return jsonResult({ uploadId, consoleUrl, status: status.status, tests: status.tests });
             }

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

@@ -1,10 +1,25 @@
-import { CompatibilityData } from '../utils/compatibility.js';
+import type { CompatibilityData } from '../utils/compatibility.js';
+/** The device / OS inputs a caller exposes, named for "pass it explicitly" hints. */
+export interface DeviceArgNames {
+    androidApiLevel: string;
+    androidDevice: string;
+    iOSDevice: string;
+    iOSVersion: string;
+}
 export interface DeviceValidationOptions {
+    /** How the caller names its inputs in error hints. Defaults to the CLI flags. */
+    argNames?: DeviceArgNames;
     debug?: boolean;
     logger?: (message: string) => void;
 }
 /**
- * Service for validating device configurations against compatibility data
+ * Validates requested devices against the compatibility matrix the API serves
+ * from `GET /results/compatibility/data`, which is the only authority on what
+ * can run. Nothing here consults the CLI's device and OS enums
+ * (src/types/domain/device.types.ts) — those only feed `--help` — so a device
+ * or OS version the API adds is accepted without a CLI release, and one it
+ * withdraws is refused, before anything is uploaded, with the list the API
+ * offers today.
  */
 export declare class DeviceValidationService {
     /**

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

@@ -1,5 +1,35 @@
+const DEVICES_DOCS_URL = 'https://docs.devicecloud.dev/getting-started/devices-configuration';
+/** `dcd cloud`'s spelling; the MCP tool passes its own parameter names. */
+const CLI_ARG_NAMES = {
+    androidApiLevel: '--android-api-level',
+    androidDevice: '--android-device',
+    iOSDevice: '--ios-device',
+    iOSVersion: '--ios-version',
+};
+/** The versions a lookup offers for one device; empty when it offers none. */
+function versionsFor(lookup, device) {
+    // hasOwn, so a slug like "constructor" can't resolve to a prototype member.
+    if (!lookup || !Object.hasOwn(lookup, device))
+        return [];
+    const versions = lookup[device];
+    return Array.isArray(versions) ? versions : [];
+}
+/**
+ * Devices the lookup can actually run, in the API's order. A rollout gate can
+ * leave a device with no versions (every non-Play device has an empty Google
+ * Play list), and those must not be offered as alternatives.
+ */
+function offeredDevices(lookup) {
+    return Object.keys(lookup ?? {}).filter((device) => versionsFor(lookup, device).length > 0);
+}
 /**
- * Service for validating device configurations against compatibility data
+ * Validates requested devices against the compatibility matrix the API serves
+ * from `GET /results/compatibility/data`, which is the only authority on what
+ * can run. Nothing here consults the CLI's device and OS enums
+ * (src/types/domain/device.types.ts) — those only feed `--help` — so a device
+ * or OS version the API adds is accepted without a CLI release, and one it
+ * withdraws is refused, before anything is uploaded, with the list the API
+ * offers today.
  */
 export class DeviceValidationService {
     /**
@@ -13,6 +43,10 @@ export class DeviceValidationService {
      * @throws Error if device/API level combination is not supported
      */
     validateAndroidDevice(androidApiLevel, androidDevice, googlePlay, compatibilityData, options = {}) {
+        const lookup = googlePlay
+            ? compatibilityData.androidPlay
+            : compatibilityData.android;
+        const argNames = options.argNames ?? CLI_ARG_NAMES;
         this.validateDevice({
             debugLines: (deviceID, version, supportedVersions) => [
                 `[DEBUG] Android device: ${deviceID}`,
@@ -20,16 +54,27 @@ export class DeviceValidationService {
                 `[DEBUG] Google Play enabled: ${googlePlay}`,
                 `[DEBUG] Supported Android versions: ${supportedVersions.join(', ')}`,
             ],
+            // Mirrors the API, which applies these same global defaults to a
+            // request that omits either half (test-request-validator.service.ts)
+            // and then rejects an incompatible pair.
             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`,
+            deviceArg: argNames.androidDevice,
+            deviceKind: googlePlay ? 'Google Play' : 'Android',
+            formatVersion: (version) => `API level ${version}`,
+            lookup,
             options,
+            platform: 'Android',
+            // A real device that merely has no Google Play image deserves a sharper
+            // answer than "not supported".
+            unknownDeviceMessage: (deviceID) => googlePlay && versionsFor(compatibilityData.android, deviceID).length > 0
+                ? `Android device "${deviceID}" is not available with Google Play. Google Play devices: ${offeredDevices(lookup).join(', ')}. See ${DEVICES_DOCS_URL}`
+                : undefined,
             unsupportedVersionMessage: (deviceID, supportedVersions) => `${deviceID} ${googlePlay ? '(Play Store) ' : ''}only supports these Android API levels: ${supportedVersions.join(', ')}`,
             version: androidApiLevel,
+            versionArg: argNames.androidApiLevel,
+            versionName: 'Android API level',
         });
     }
     /**
@@ -42,20 +87,27 @@ export class DeviceValidationService {
      * @throws Error if device/version combination is not supported
      */
     validateiOSDevice(iOSVersion, iOSDevice, compatibilityData, options = {}) {
+        const argNames = options.argNames ?? CLI_ARG_NAMES;
         this.validateDevice({
             debugLines: (deviceID, version, supportedVersions) => [
                 `[DEBUG] iOS device: ${deviceID}`,
                 `[DEBUG] iOS version: ${version}`,
                 `[DEBUG] Supported iOS versions: ${supportedVersions.join(', ')}`,
             ],
+            // Mirrors the API's global defaults, as for Android above.
             defaultDevice: 'iphone-14',
             defaultVersion: '17',
             device: iOSDevice,
+            deviceArg: argNames.iOSDevice,
+            deviceKind: 'iOS',
+            formatVersion: (version) => `iOS ${version}`,
             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,
+            platform: 'iOS',
             unsupportedVersionMessage: (deviceID, supportedVersions) => `${deviceID} only supports these iOS versions: ${supportedVersions.join(', ')}`,
             version: iOSVersion,
+            versionArg: argNames.iOSVersion,
+            versionName: 'iOS version',
         });
     }
     /**
@@ -66,20 +118,49 @@ export class DeviceValidationService {
      * @throws Error if device/version combination is not supported
      */
     validateDevice(config) {
-        const { debugLines, defaultDevice, defaultVersion, device, lookup, noSupportMessage, options, unsupportedVersionMessage, version, } = config;
+        const { debugLines, defaultDevice, defaultVersion, device, deviceArg, deviceKind, formatVersion, lookup, options, platform, unknownDeviceMessage, unsupportedVersionMessage, version, versionArg, versionName, } = config;
         const { debug = false, logger } = options;
         if (!version && !device) {
             return;
         }
         const deviceID = device || defaultDevice;
-        const supportedVersions = lookup?.[deviceID] || [];
+        const supportedVersions = versionsFor(lookup, deviceID);
         const requestedVersion = version || defaultVersion;
         if (supportedVersions.length === 0) {
-            throw new Error(noSupportMessage(deviceID));
+            if (!device) {
+                // Only a version was requested, and the API no longer offers the
+                // device the CLI assumes it defaults to. That assumption is what's
+                // stale, not the request: the API resolves and validates its own
+                // default device when the run is submitted.
+                if (debug && logger) {
+                    logger(`[DEBUG] Default ${platform} device ${deviceID} is not in the compatibility data; leaving the ${versionName} check to the API`);
+                }
+                return;
+            }
+            const offered = offeredDevices(lookup);
+            throw new Error(unknownDeviceMessage?.(deviceID) ??
+                (offered.length > 0
+                    ? `${platform} device "${deviceID}" is not supported. Supported ${deviceKind} devices: ${offered.join(', ')}. See ${DEVICES_DOCS_URL}`
+                    : `${platform} device "${deviceID}" is not supported. See ${DEVICES_DOCS_URL}`));
         }
-        if (Array.isArray(supportedVersions) &&
-            !supportedVersions.includes(requestedVersion)) {
-            throw new Error(unsupportedVersionMessage(deviceID, supportedVersions));
+        if (!supportedVersions.includes(requestedVersion)) {
+            const unsupported = unsupportedVersionMessage(deviceID, supportedVersions);
+            if (!version) {
+                // Device-only request. The API fills in the same global default
+                // version rather than one this device runs, so the submission would
+                // be refused there too — say so, and how to avoid it.
+                throw new Error(`${unsupported}. No ${versionName} was given, so the default (${defaultVersion}) was checked: pass one of those explicitly with ${versionArg}`);
+            }
+            if (!device) {
+                // Version-only request: name the device that was assumed, and the
+                // devices that do offer the requested version.
+                const devicesWithVersion = offeredDevices(lookup).filter((d) => versionsFor(lookup, d).includes(requestedVersion));
+                throw new Error(`${unsupported}. No ${platform} device was given, so the default (${deviceID}) was checked: ` +
+                    (devicesWithVersion.length > 0
+                        ? `pass one that offers ${formatVersion(requestedVersion)} with ${deviceArg}: ${devicesWithVersion.join(', ')}`
+                        : `no ${deviceKind} device offers ${formatVersion(requestedVersion)}`));
+            }
+            throw new Error(unsupported);
         }
         if (debug && logger) {
             for (const line of debugLines(deviceID, requestedVersion, supportedVersions)) {

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

@@ -21,6 +21,12 @@ export interface IExecutionPlan {
     flowMetadata: Record<string, Record<string, unknown>>;
     flowOverrides: Record<string, Record<string, unknown>>;
     flowsToRun: string[];
+    /**
+     * Extra files pulled in by `config.yaml`'s `includedPaths`. Kept separate
+     * from `referencedFiles` (which is derived from flow commands) so the zip
+     * manifest and the common-root calculation can tell the two apart.
+     */
+    includedFiles: string[];
     referencedFiles: string[];
     sequence?: IFlowSequence | null;
     totalFlowFiles: number;

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

@@ -90,7 +90,7 @@ function extractDeviceCloudOverrides(config) {
  * @param resolvedConfigFile - Optional absolute path to a custom config file
  * @returns Execution plan for the single file with dependencies
  */
-async function planSingleFile(normalizedInput, warn, resolvedConfigFile) {
+async function planSingleFile(normalizedInput, warn, resolvedConfigFile, debug = false) {
     const inputBasename = path.basename(normalizedInput);
     if (inputBasename === 'config.yaml' ||
         inputBasename === 'config.yml' ||
@@ -118,11 +118,18 @@ async function planSingleFile(normalizedInput, warn, resolvedConfigFile) {
                 `Pass the workspace folder instead so the named flows can be discovered and sequenced.`);
         }
     }
+    // A single-file input has no workspace directory, so `includedPaths` (which
+    // only reaches here via --config) anchors on the flow file's own directory —
+    // the same place Maestro resolves an assertScreenshot baseline from.
+    const includedFiles = workspaceConfig
+        ? resolveIncludedPaths(workspaceConfig, path.dirname(normalizedInput), warn, debug)
+        : [];
     const checkedDependancies = await checkDependencies(normalizedInput);
     return {
         flowMetadata,
         flowOverrides,
         flowsToRun: [normalizedInput],
+        includedFiles,
         referencedFiles: [...new Set(checkedDependancies)],
         totalFlowFiles: 1,
         workspaceConfig,
@@ -176,6 +183,94 @@ async function applyFlowGlobs(workspaceConfig, normalizedInput, unfilteredFlowFi
     }
     return unfilteredFlowFiles.filter((file) => !isExcludedConfig(file));
 }
+/**
+ * The whole archive is buffered in memory by `compressFilesFromRelativePath`,
+ * so an unbounded `**` glob is a real footgun. These are warn thresholds, not
+ * hard limits — a legitimately large baseline set should still upload.
+ */
+const INCLUDED_PATHS_FILE_WARN_THRESHOLD = 200;
+const INCLUDED_PATHS_BYTES_WARN_THRESHOLD = 50 * 1024 * 1024;
+/**
+ * Resolve `config.yaml`'s `includedPaths` globs into absolute file paths.
+ *
+ * This is the general-purpose escape hatch for shipping files the flow
+ * commands don't reference: `assertScreenshot` baselines above all, but also
+ * fixtures, test data and certificates. Only `addMedia` / `runFlow` /
+ * `runScript` arguments are discovered by walking the flows, so without this
+ * key such files are silently absent from the uploaded zip.
+ *
+ * Glob semantics deliberately mirror `flows:` (`applyFlowGlobs`): patterns
+ * resolve against the workspace root, never the config file's directory, so
+ * `--config ci/workspace.yaml` behaves identically to an auto-detected config.
+ *
+ * @param workspaceConfig - Validated workspace config
+ * @param normalizedInput - Normalized path to the workspace directory
+ * @param warn - Sink for non-fatal problems
+ * @param debug - Whether to emit debug logging
+ * @returns Absolute paths of every matched file, deduped and sorted
+ * @throws Error if a pattern escapes the workspace root
+ */
+function resolveIncludedPaths(workspaceConfig, normalizedInput, warn, debug = false) {
+    const patterns = workspaceConfig.includedPaths;
+    if (!patterns || patterns.length === 0)
+        return [];
+    const workspaceRoot = path.resolve(normalizedInput);
+    const resolved = new Set();
+    const unmatched = [];
+    for (const pattern of patterns) {
+        // fs.globSync lands in Node 22; the CLI's `engines.node` already requires
+        // it. No `nodir` option — directories are stripped by the stat check below.
+        const matches = fs.globSync(pattern, { cwd: normalizedInput });
+        let matchedFile = false;
+        for (const match of matches) {
+            const absolute = path.resolve(normalizedInput, match);
+            // Containment guard: `flows:` has none because its matches are only ever
+            // parsed as YAML, but this key ships arbitrary bytes to a remote runner,
+            // so a `../../../` climb must not silently leave the workspace.
+            const relative = path.relative(workspaceRoot, absolute);
+            if (relative.startsWith('..') || path.isAbsolute(relative)) {
+                throw new Error(`\`includedPaths\` pattern "${pattern}" resolves outside the workspace: ${absolute}\n\n` +
+                    `Included paths must stay within ${workspaceRoot}.`);
+            }
+            try {
+                if (!fs.statSync(absolute).isFile())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            matchedFile = true;
+            resolved.add(absolute);
+        }
+        if (!matchedFile)
+            unmatched.push(pattern);
+    }
+    if (unmatched.length > 0) {
+        warn(`Warning: \`includedPaths\` pattern(s) in config matched no files:\n` +
+            `${unmatched.map((pattern) => `  ${pattern}`).join('\n')}\n\n` +
+            `Patterns are resolved relative to ${workspaceRoot}.`);
+    }
+    const files = [...resolved].sort((a, b) => a.localeCompare(b));
+    let totalBytes = 0;
+    for (const file of files) {
+        try {
+            totalBytes += fs.statSync(file).size;
+        }
+        catch {
+            // Raced away between glob and stat; the zip step reports it properly.
+        }
+    }
+    if (files.length > INCLUDED_PATHS_FILE_WARN_THRESHOLD ||
+        totalBytes > INCLUDED_PATHS_BYTES_WARN_THRESHOLD) {
+        warn(`Warning: \`includedPaths\` matched ${files.length} file(s) totalling ` +
+            `${Math.round(totalBytes / (1024 * 1024))} MB. The flow archive is built in ` +
+            `memory, so consider narrowing the patterns.`);
+    }
+    if (debug) {
+        console.log(`[DEBUG] includedPaths matched ${files.length} file(s):\n${files.join('\n')}`);
+    }
+    return files;
+}
 /**
  * Resolve sequential execution order from workspace config
  * @param workspaceConfig - Workspace configuration with executionOrder
@@ -241,7 +336,7 @@ export async function plan(options) {
         throw new Error(`Flow path does not exist: ${path.resolve(normalizedInput)}`);
     }
     if (fs.lstatSync(normalizedInput).isFile()) {
-        return planSingleFile(normalizedInput, warn, resolvedConfigFile);
+        return planSingleFile(normalizedInput, warn, resolvedConfigFile, debug);
     }
     let unfilteredFlowFiles = await readDirectory(normalizedInput, isFlowFile);
     if (unfilteredFlowFiles.length === 0) {
@@ -325,6 +420,7 @@ export async function plan(options) {
         flowMetadata,
         flowOverrides,
         flowsToRun: normalFlows,
+        includedFiles: resolveIncludedPaths(workspaceConfig, normalizedInput, warn, debug),
         referencedFiles: [...new Set(allFiles)],
         sequence: {
             continueOnFailure: workspaceConfig.executionOrder?.continueOnFailure,

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

@@ -2,7 +2,50 @@ import * as yaml from 'js-yaml';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { parseWorkspaceConfig, WORKSPACE_CONFIG_KEYS, } from './workspace-config.schema.js';
-const commandsThatRequireFiles = new Set(['addMedia', 'runFlow', 'runScript']);
+const commandsThatRequireFiles = new Set([
+    'addMedia',
+    'assertScreenshot',
+    'runFlow',
+    'runScript',
+]);
+/**
+ * Commands whose file references are best-effort rather than mandatory.
+ *
+ * `assertScreenshot` baselines are legitimately absent on a first run, and
+ * Maestro's own "Screenshot file not found — searched in: …" error is more
+ * useful than ours, so a missing baseline must not abort the upload the way a
+ * missing `addMedia` file does.
+ */
+const commandsWithOptionalFiles = new Set(['assertScreenshot']);
+/**
+ * Extensions Maestro's `normalizeScreenshotPath` recognises; anything else
+ * gets `.png` appended, so `assertScreenshot: home` means `home.png`.
+ */
+const SCREENSHOT_EXTENSIONS = new Set([
+    '.bmp',
+    '.gif',
+    '.heic',
+    '.heif',
+    '.jpeg',
+    '.jpg',
+    '.png',
+    '.tiff',
+    '.wbmp',
+]);
+/**
+ * Mirror Maestro's `Orchestra.normalizeScreenshotPath`: a screenshot path with
+ * no image extension gets `.png`. Without this, `assertScreenshot: home` looks
+ * like a missing file here while resolving fine on the device.
+ *
+ * @param relativePath - The path as written in the flow
+ * @returns The path with an image extension guaranteed
+ */
+function normalizeScreenshotPath(relativePath) {
+    const extension = path.extname(relativePath).toLowerCase();
+    return SCREENSHOT_EXTENSIONS.has(extension)
+        ? relativePath
+        : `${relativePath}.png`;
+}
 export function getFlowsToRunInSequence(paths, flowOrder, debug = false) {
     if (flowOrder.length === 0) {
         if (debug) {
@@ -145,12 +188,27 @@ export const checkIfFilesExistInWorkspace = (commandName, command, absoluteFileP
     const errors = [];
     const files = [];
     const directory = path.dirname(absoluteFilePath);
+    const isScreenshot = commandName === 'assertScreenshot';
+    const isOptional = commandsWithOptionalFiles.has(commandName);
     const buildError = (error) => `Flow file "${absoluteFilePath}" has a command "${commandName}" that references a ${error} ${JSON.stringify(command)}`;
     const processFilePath = (relativePath) => {
-        const absoluteFilePath = path.normalize(path.resolve(directory, relativePath));
+        // A JS/variable-interpolated path (`screenshots/${DCD_DEVICE}/home`) can't
+        // be resolved without running the flow. Skip it rather than guessing — the
+        // config.yaml `includedPaths` key is how those files get bundled.
+        if (relativePath.includes('${'))
+            return;
+        const resolvedRelativePath = isScreenshot
+            ? normalizeScreenshotPath(relativePath)
+            : relativePath;
+        const absoluteFilePath = path.normalize(path.resolve(directory, resolvedRelativePath));
         const error = checkFile(absoluteFilePath);
-        if (error)
+        if (error) {
+            // Optional references drop out entirely when missing: pushing them onto
+            // `files` would put a non-existent path into the zip manifest.
+            if (isOptional)
+                return;
             errors.push(buildError(error));
+        }
         files.push(absoluteFilePath);
     };
     // simple command — processFilePath already resolves against `directory`
@@ -163,10 +221,15 @@ export const checkIfFilesExistInWorkspace = (commandName, command, absoluteFileP
             processFilePath(file);
         }
     }
-    // object command
+    // object command. `file` is addMedia/runFlow/runScript; `path` is
+    // assertScreenshot's own key for the same thing.
     const x = command; // prevent annoying ts error
-    if (typeof command === 'object' && x?.file)
-        processFilePath(x.file);
+    if (typeof command === 'object' && !Array.isArray(command)) {
+        if (x?.file)
+            processFilePath(x.file);
+        if (isScreenshot && typeof x?.path === 'string')
+            processFilePath(x.path);
+    }
     return { errors, files };
 };
 const checkFile = (filePath) => {

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

@@ -3,8 +3,16 @@
  * 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).
+ *
+ * `includedFiles` (config.yaml `includedPaths`) must be folded in for the same
+ * reason referenced files are: the zip strips this root as an anchored prefix,
+ * so a file outside it would get a non-relative entry name. Folding them in
+ * can raise the root — flows in `flows/` beside baselines in `screenshots/`
+ * shifts it from `<root>/flows` to `<root>`, so flow keys gain a `flows/`
+ * segment. That shift is what preserves the flow→baseline relative offset
+ * Maestro resolves against, and is already how `addMedia` behaves.
  */
-export declare function computeCommonRoot(testFileNames: string[], referencedFiles: string[]): string;
+export declare function computeCommonRoot(testFileNames: string[], referencedFiles: string[], includedFiles?: string[]): string;
 export interface FlowMetadataEntry {
     flowName: string;
     tags: string[];

package/dist/services/flow-paths.js

@@ -12,9 +12,21 @@ import { toPortableRelativePath } from '../utils/paths.js';
  * 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).
+ *
+ * `includedFiles` (config.yaml `includedPaths`) must be folded in for the same
+ * reason referenced files are: the zip strips this root as an anchored prefix,
+ * so a file outside it would get a non-relative entry name. Folding them in
+ * can raise the root — flows in `flows/` beside baselines in `screenshots/`
+ * shifts it from `<root>/flows` to `<root>`, so flow keys gain a `flows/`
+ * segment. That shift is what preserves the flow→baseline relative offset
+ * Maestro resolves against, and is already how `addMedia` behaves.
  */
-export function computeCommonRoot(testFileNames, referencedFiles) {
-    const pathsShortestToLongest = [...testFileNames, ...referencedFiles].sort((a, b) => a.split(path.sep).length - b.split(path.sep).length);
+export function computeCommonRoot(testFileNames, referencedFiles, includedFiles = []) {
+    const pathsShortestToLongest = [
+        ...testFileNames,
+        ...referencedFiles,
+        ...includedFiles,
+    ].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));

package/dist/services/notices.service.js

@@ -80,6 +80,9 @@ function renderNotice(notice, opts) {
 export function platformFromAppFile(appFile) {
     if (!appFile)
         return undefined;
+    // Expo iOS simulator builds (`dcd cloud` extracts these to a .app first).
+    if (appFile.split('?')[0].toLowerCase().endsWith('.tar.gz'))
+        return 'ios';
     const ext = appFile.split('?')[0].toLowerCase().match(/.([a-z0-9]+)$/)?.[1];
     if (ext === 'apk' || ext === 'aab')
         return 'android';

package/dist/services/report-download.service.js

@@ -1,5 +1,6 @@
 import * as path from 'node:path';
 import { ApiGateway } from '../gateways/api-gateway.js';
+import { refreshAuth } from '../utils/auth.js';
 /**
  * Service for downloading test artifacts and reports
  */
@@ -15,7 +16,9 @@ export class ReportDownloadService {
             if (debug && logger) {
                 logger(`[DEBUG] Downloading artifacts: ${downloadType}`);
             }
-            await ApiGateway.downloadArtifactsZip(apiUrl, auth, uploadId, downloadType, artifactsPath);
+            // `dcd cloud` downloads after polling, which can outlast a `dcd login`
+            // token; a failed refresh lands in the warning below like any failure.
+            await ApiGateway.downloadArtifactsZip(apiUrl, await refreshAuth(auth), uploadId, downloadType, artifactsPath);
             if (logger) {
                 logger('\n');
                 logger(`Test artifacts have been downloaded to ${artifactsPath}`);
@@ -54,7 +57,9 @@ export class ReportDownloadService {
             }
             case 'html':
             case 'html-detailed': {
-                const htmlReportPath = path.resolve(process.cwd(), htmlPath || 'report.html');
+                // The HTML report is a ZIP (report.html plus its screenshots and
+                // assets), so the default name says so. An explicit path is kept as-is.
+                const htmlReportPath = path.resolve(process.cwd(), htmlPath || 'report.zip');
                 await this.downloadReport('html', htmlReportPath, {
                     ...downloadOptions,
                     warnLogger,
@@ -81,7 +86,8 @@ export class ReportDownloadService {
             if (debug && logger) {
                 logger(`[DEBUG] Downloading ${type.toUpperCase()} report`);
             }
-            await ApiGateway.downloadReportGeneric(apiUrl, auth, uploadId, type, filePath);
+            // As for artifacts: this can run after a poll that outlasted the token.
+            await ApiGateway.downloadReportGeneric(apiUrl, await refreshAuth(auth), uploadId, type, filePath);
             if (logger) {
                 logger(`${type.toUpperCase()} test report has been downloaded to ${filePath}`);
             }