@devicecloud.dev/dcd 5.3.0 → 5.3.1-beta.2

package/dist/commands/cloud.js

@@ -366,6 +366,9 @@ export const cloudCommand = defineCommand({
                     excludeFlows,
                     configFile,
                     debug,
+                    // Not warnOut: config problems are worth surfacing even under --json,
+                    // and logger.warn writes to stderr so stdout stays parseable.
+                    warn: (m) => logger.warn(m),
                 });
                 if (debug) {
                     out(`[DEBUG] Execution plan generated`);

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

@@ -117,6 +117,8 @@ export function registerRunCloudTest(server) {
             excludeTags: args.excludeTags ?? [],
             excludeFlows: args.excludeFlows,
             configFile: args.configFile,
+            // stdout is the JSON-RPC channel — config warnings must go to stderr.
+            warn: logStderr,
         });
         const commonRoot = computeCommonRoot(executionPlan.flowsToRun, executionPlan.referencedFiles);
         const testMetadataMap = buildTestMetadataMap(executionPlan.flowMetadata, commonRoot);

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

@@ -1,37 +1,4 @@
-/** Email notification configuration */
-interface INotificationsConfig {
-    email?: {
-        enabled?: boolean;
-        onSuccess?: boolean;
-        recipients?: string[];
-    };
-}
-/** Workspace configuration from config.yaml */
-interface IWorkspaceConfig {
-    excludeTags?: null | string[];
-    executionOrder?: IExecutionOrder | null;
-    flows?: null | string[];
-    includeTags?: null | string[];
-    local?: ILocal | null;
-    notifications?: INotificationsConfig;
-    platform?: {
-        android?: {
-            disableAnimations?: boolean;
-        };
-        ios?: {
-            disableAnimations?: boolean;
-        };
-    };
-}
-/** Local execution configuration */
-interface ILocal {
-    deterministicOrder: boolean | null;
-}
-/** Sequential execution configuration */
-interface IExecutionOrder {
-    continueOnFailure: boolean;
-    flowsOrder: string[];
-}
+import { IWorkspaceConfig } from './workspace-config.schema.js';
 /** Options for execution plan generation */
 export interface PlanOptions {
     configFile?: string;
@@ -40,6 +7,12 @@ export interface PlanOptions {
     excludeTags?: string[];
     includeTags?: string[];
     input: string;
+    /**
+     * Sink for non-fatal config problems. Injected rather than imported so the
+     * MCP server can route warnings to stderr — its stdout is the JSON-RPC
+     * channel.
+     */
+    warn?: (message: string) => void;
 }
 /** Execution plan containing all flows to run with metadata and dependencies */
 export interface IExecutionPlan {

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

@@ -1,6 +1,6 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { getFlowsToRunInSequence, isFlowFile, processDependencies, readDirectory, readTestYamlFileAsJson, readYamlFileAsJson, } from './execution-plan.utils.js';
+import { getFlowsToRunInSequence, isFlowFile, isWorkspaceConfigFile, loadWorkspaceConfig, processDependencies, readDirectory, readTestYamlFileAsJson, } from './execution-plan.utils.js';
 /**
  * Recursively check and resolve all dependencies for a flow file
  * Includes runFlow references, JavaScript scripts, and media files
@@ -54,15 +54,13 @@ function filterFlowFiles(unfilteredFlowFiles, excludeFlows) {
  * Load workspace configuration from config.yaml/yml if present
  * @param input - Input directory path
  * @param unfilteredFlowFiles - List of discovered flow files
+ * @param warn - Sink for non-fatal config problems
  * @returns Workspace configuration object (empty if no config file found)
  */
-function getWorkspaceConfig(input, unfilteredFlowFiles) {
+function getWorkspaceConfig(input, unfilteredFlowFiles, warn) {
     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
-        ? readYamlFileAsJson(configFilePath)
-        : {};
-    return config;
+    return configFilePath ? loadWorkspaceConfig(configFilePath, warn) : {};
 }
 /**
  * Extract DeviceCloud-specific override environment variables
@@ -88,12 +86,15 @@ function extractDeviceCloudOverrides(config) {
 /**
  * Generate execution plan for a single flow file
  * @param normalizedInput - Normalized path to the flow file
- * @param configFile - Optional custom config file path
+ * @param warn - Sink for non-fatal config problems
+ * @param resolvedConfigFile - Optional absolute path to a custom config file
  * @returns Execution plan for the single file with dependencies
  */
-async function planSingleFile(normalizedInput, configFile) {
-    if (normalizedInput.endsWith('config.yaml') ||
-        normalizedInput.endsWith('config.yml')) {
+async function planSingleFile(normalizedInput, warn, resolvedConfigFile) {
+    const inputBasename = path.basename(normalizedInput);
+    if (inputBasename === 'config.yaml' ||
+        inputBasename === 'config.yml' ||
+        isWorkspaceConfigFile(normalizedInput)) {
         throw new Error('If using config.yaml, pass the workspace folder path, not the config file or a custom path via --config');
     }
     const { config } = readTestYamlFileAsJson(normalizedInput);
@@ -104,12 +105,18 @@ async function planSingleFile(normalizedInput, configFile) {
         flowOverrides[normalizedInput] = extractDeviceCloudOverrides(config);
     }
     let workspaceConfig;
-    if (configFile) {
-        const configFilePath = path.resolve(process.cwd(), configFile);
-        if (!fs.existsSync(configFilePath)) {
-            throw new Error(`Config file does not exist: ${configFilePath}`);
+    if (resolvedConfigFile) {
+        if (!fs.existsSync(resolvedConfigFile)) {
+            throw new Error(`Config file does not exist: ${resolvedConfigFile}`);
+        }
+        workspaceConfig = loadWorkspaceConfig(resolvedConfigFile, warn);
+        // Sequencing is resolved against a workspace's discovered flows, which a
+        // single-file input doesn't have — so executionOrder is ignored here. Say so
+        // rather than accepting a config that reads as if it applied (dcd-cli#110).
+        if (workspaceConfig.executionOrder?.flowsOrder.length) {
+            warn(`Warning: \`executionOrder\` in ${resolvedConfigFile} is ignored when a single flow file is passed.\n` +
+                `Pass the workspace folder instead so the named flows can be discovered and sequenced.`);
         }
-        workspaceConfig = readYamlFileAsJson(configFilePath);
     }
     const checkedDependancies = await checkDependencies(normalizedInput);
     return {
@@ -126,11 +133,24 @@ async function planSingleFile(normalizedInput, configFile) {
  * @param workspaceConfig - Workspace configuration containing flow globs
  * @param normalizedInput - Normalized path to the workspace directory
  * @param unfilteredFlowFiles - List of all discovered flow files
- * @param configFile - Optional custom config file path
+ * @param resolvedConfigFile - Optional absolute path to a custom config file
  * @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, excludeFlows) {
+async function applyFlowGlobs(workspaceConfig, normalizedInput, unfilteredFlowFiles, resolvedConfigFile, excludeFlows) {
+    // Both branches compare absolute paths, so `--config ./x.yml` and
+    // `--config /abs/x.yml` behave identically, and a same-named file in a
+    // sibling directory is never mistaken for the active config.
+    const activeConfig = resolvedConfigFile
+        ? path.normalize(resolvedConfigFile)
+        : undefined;
+    const isExcludedConfig = (absolutePath) => {
+        const base = path.basename(absolutePath);
+        if (base === 'config.yaml' || base === 'config.yml')
+            return true;
+        return (activeConfig !== undefined &&
+            path.normalize(absolutePath) === activeConfig);
+    };
     if (workspaceConfig.flows) {
         const globs = workspaceConfig.flows.map((g) => g);
         // fs.globSync lands in Node 22; the CLI's `engines.node` already requires it.
@@ -144,29 +164,17 @@ async function applyFlowGlobs(workspaceConfig, normalizedInput, unfilteredFlowFi
                 return false;
             }
         });
+        // Resolve before filtering: glob matches are relative to normalizedInput,
+        // so comparing them against the config path only ever worked when the
+        // config happened to sit at the workspace root.
         const globbedFlowFiles = matchedFiles
-            .filter((file) => {
-            if (file === 'config.yaml' || file === 'config.yml')
-                return false;
-            if (configFile && file === path.basename(configFile))
-                return false;
-            if (!file.endsWith('.yaml') && !file.endsWith('.yml'))
-                return false;
-            const pathParts = file.split(path.sep);
-            for (const part of pathParts) {
-                if (part.endsWith('.app'))
-                    return false;
-            }
-            return true;
-        })
-            .map((file) => path.resolve(normalizedInput, file));
+            .map((file) => path.resolve(normalizedInput, file))
+            .filter((file) => !isExcludedConfig(file) && isFlowFile(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') &&
-        (!configFile || !file.endsWith(configFile)));
+    return unfilteredFlowFiles.filter((file) => !isExcludedConfig(file));
 }
 /**
  * Resolve sequential execution order from workspace config
@@ -223,14 +231,17 @@ function resolveSequentialFlows(workspaceConfig, pathsByName, debug) {
  * @throws Error if input path doesn't exist, no flows found, or dependencies missing
  */
 export async function plan(options) {
-    const { input, includeTags = [], excludeTags = [], excludeFlows, configFile, debug = false, } = options;
+    const { input, includeTags = [], excludeTags = [], excludeFlows, configFile, debug = false, warn = (message) => console.warn(message), } = options;
     const normalizedInput = path.normalize(input);
     const flowMetadata = {};
+    const resolvedConfigFile = configFile
+        ? path.resolve(process.cwd(), configFile)
+        : undefined;
     if (!fs.existsSync(normalizedInput)) {
         throw new Error(`Flow path does not exist: ${path.resolve(normalizedInput)}`);
     }
     if (fs.lstatSync(normalizedInput).isFile()) {
-        return planSingleFile(normalizedInput, configFile);
+        return planSingleFile(normalizedInput, warn, resolvedConfigFile);
     }
     let unfilteredFlowFiles = await readDirectory(normalizedInput, isFlowFile);
     if (unfilteredFlowFiles.length === 0) {
@@ -238,17 +249,30 @@ export async function plan(options) {
     }
     unfilteredFlowFiles = filterFlowFiles(unfilteredFlowFiles, excludeFlows);
     let workspaceConfig;
-    if (configFile) {
-        const configFilePath = path.resolve(process.cwd(), configFile);
-        if (!fs.existsSync(configFilePath)) {
-            throw new Error(`Config file does not exist: ${configFilePath}`);
+    if (resolvedConfigFile) {
+        if (!fs.existsSync(resolvedConfigFile)) {
+            throw new Error(`Config file does not exist: ${resolvedConfigFile}`);
         }
-        workspaceConfig = readYamlFileAsJson(configFilePath);
+        workspaceConfig = loadWorkspaceConfig(resolvedConfigFile, warn);
     }
     else {
-        workspaceConfig = getWorkspaceConfig(normalizedInput, unfilteredFlowFiles);
+        workspaceConfig = getWorkspaceConfig(normalizedInput, unfilteredFlowFiles, warn);
+    }
+    unfilteredFlowFiles = await applyFlowGlobs(workspaceConfig, normalizedInput, unfilteredFlowFiles, resolvedConfigFile, excludeFlows);
+    // The exclusions above are filename-based: they only catch
+    // `config.yaml`/`config.yml` and the active --config target. Any other
+    // workspace config sharing the folder (a second CI workflow's, say) is still
+    // on the list and would be parsed as a flow, so drop config-shaped files by
+    // shape — see dcd-cli#99.
+    const configShapedFiles = new Set(unfilteredFlowFiles.filter((file) => isWorkspaceConfigFile(file)));
+    if (configShapedFiles.size > 0) {
+        if (debug) {
+            console.log(`[DEBUG] Skipping ${configShapedFiles.size} workspace config file(s): ${[
+                ...configShapedFiles,
+            ].join(', ')}`);
+        }
+        unfilteredFlowFiles = unfilteredFlowFiles.filter((file) => !configShapedFiles.has(file));
     }
-    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')}`)

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

@@ -1,8 +1,38 @@
+import { IWorkspaceConfig } from './workspace-config.schema.js';
 export declare function getFlowsToRunInSequence(paths: {
     [key: string]: string;
 }, flowOrder: string[], debug?: boolean): string[];
 export declare function isFlowFile(filePath: string): boolean;
+/**
+ * True when a YAML file is a workspace config rather than a runnable flow.
+ *
+ * A flow is either `front matter --- steps` or a bare steps array; a
+ * single-document top-level map carrying workspace-config keys is neither, and
+ * left in the flow list it blows up processDependencies with "Expected an array
+ * of steps". Detection is by shape, not filename, so several named configs can
+ * coexist in one folder (dcd-cli#99). Requiring a recognised config key — not
+ * just "single document, top-level map" — keeps a flow that is merely *missing*
+ * its `---` separator loud rather than silently dropped.
+ *
+ * @param filePath - Path to the YAML file to classify
+ * @returns Whether the file is a workspace config rather than a flow
+ */
+export declare function isWorkspaceConfigFile(filePath: string): boolean;
 export declare const readYamlFileAsJson: (filePath: string) => unknown;
+/**
+ * Load and validate a workspace config file.
+ *
+ * The single chokepoint for reading a config: every caller gets a
+ * runtime-validated object instead of an unchecked `as IWorkspaceConfig` cast.
+ * Scalar-to-array coercion for `includeTags`/`excludeTags` lives in the schema,
+ * so `readYamlFileAsJson` stays a plain YAML read.
+ *
+ * @param filePath - Path to the config file
+ * @param warn - Sink for non-fatal problems (unrecognised keys)
+ * @returns The validated workspace config
+ * @throws Error if the file is unparseable or the config is invalid
+ */
+export declare function loadWorkspaceConfig(filePath: string, warn: (message: string) => void): IWorkspaceConfig;
 export declare const readTestYamlFileAsJson: (filePath: string) => {
     config: Record<string, unknown>;
     testSteps: Record<string, unknown>[];

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

@@ -1,6 +1,7 @@
 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']);
 export function getFlowsToRunInSequence(paths, flowOrder, debug = false) {
     if (flowOrder.length === 0) {
@@ -38,21 +39,43 @@ export function isFlowFile(filePath) {
     }
     return filePath.endsWith('.yaml') || filePath.endsWith('.yml');
 }
+/**
+ * True when a YAML file is a workspace config rather than a runnable flow.
+ *
+ * A flow is either `front matter --- steps` or a bare steps array; a
+ * single-document top-level map carrying workspace-config keys is neither, and
+ * left in the flow list it blows up processDependencies with "Expected an array
+ * of steps". Detection is by shape, not filename, so several named configs can
+ * coexist in one folder (dcd-cli#99). Requiring a recognised config key — not
+ * just "single document, top-level map" — keeps a flow that is merely *missing*
+ * its `---` separator loud rather than silently dropped.
+ *
+ * @param filePath - Path to the YAML file to classify
+ * @returns Whether the file is a workspace config rather than a flow
+ */
+export function isWorkspaceConfigFile(filePath) {
+    let parsed;
+    try {
+        parsed = readTestYamlFileAsJson(filePath);
+    }
+    catch {
+        // Unparseable — leave it in the flow list so the existing error path reports it.
+        return false;
+    }
+    const { config, testSteps } = parsed;
+    if (config !== null)
+        return false; // has `---` front matter → flow
+    if (Array.isArray(testSteps))
+        return false; // bare steps array → flow
+    if (!testSteps || typeof testSteps !== 'object')
+        return false;
+    return Object.keys(testSteps).some((key) => WORKSPACE_CONFIG_KEYS.has(key));
+}
 export const readYamlFileAsJson = (filePath) => {
     try {
         const normalizedPath = path.normalize(filePath);
         const yamlText = fs.readFileSync(normalizedPath, 'utf8');
-        const result = yaml.load(yamlText);
-        // Ensure includeTags and excludeTags are always arrays if present
-        if (result && typeof result === 'object') {
-            if ('includeTags' in result && !Array.isArray(result.includeTags)) {
-                result.includeTags = result.includeTags ? [result.includeTags] : [];
-            }
-            if ('excludeTags' in result && !Array.isArray(result.excludeTags)) {
-                result.excludeTags = result.excludeTags ? [result.excludeTags] : [];
-            }
-        }
-        return result;
+        return yaml.load(yamlText);
     }
     catch (error) {
         throw new Error(`Error parsing YAML file ${filePath}: ${error}`, {
@@ -60,6 +83,22 @@ export const readYamlFileAsJson = (filePath) => {
         });
     }
 };
+/**
+ * Load and validate a workspace config file.
+ *
+ * The single chokepoint for reading a config: every caller gets a
+ * runtime-validated object instead of an unchecked `as IWorkspaceConfig` cast.
+ * Scalar-to-array coercion for `includeTags`/`excludeTags` lives in the schema,
+ * so `readYamlFileAsJson` stays a plain YAML read.
+ *
+ * @param filePath - Path to the config file
+ * @param warn - Sink for non-fatal problems (unrecognised keys)
+ * @returns The validated workspace config
+ * @throws Error if the file is unparseable or the config is invalid
+ */
+export function loadWorkspaceConfig(filePath, warn) {
+    return parseWorkspaceConfig(readYamlFileAsJson(filePath), { filePath, warn });
+}
 export const readTestYamlFileAsJson = (filePath) => {
     try {
         const normalizedPath = path.normalize(filePath);

package/dist/services/workspace-config.schema.d.ts

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+/**
+ * `looseObject`, not `object`: unknown keys are reported as warnings but must
+ * survive parsing, because the whole config is forwarded to the API as
+ * `fields.workspaceConfig` and stripping keys would silently alter that
+ * payload.
+ */
+export declare const WorkspaceConfigSchema: z.ZodObject<{
+    excludeTags: z.ZodOptional<z.ZodNullable<z.ZodPreprocess<z.ZodArray<z.ZodString>>>>;
+    executionOrder: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        continueOnFailure: z.ZodDefault<z.ZodBoolean>;
+        flowsOrder: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>>;
+    flows: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    includeTags: z.ZodOptional<z.ZodNullable<z.ZodPreprocess<z.ZodArray<z.ZodString>>>>;
+    local: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        deterministicOrder: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    }, z.core.$loose>>>;
+    notifications: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        email: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodOptional<z.ZodBoolean>;
+            onSuccess: z.ZodOptional<z.ZodBoolean>;
+            recipients: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>>;
+    platform: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        android: z.ZodOptional<z.ZodObject<{
+            disableAnimations: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$loose>>;
+        ios: z.ZodOptional<z.ZodObject<{
+            disableAnimations: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>>;
+}, z.core.$loose>;
+/** Workspace configuration from config.yaml */
+export type IWorkspaceConfig = z.infer<typeof WorkspaceConfigSchema>;
+/**
+ * Top-level keys that only ever appear in a workspace config, derived from the
+ * schema so the two can't drift. Deliberately excludes keys Maestro also allows
+ * in flow front matter — appId, name, tags, env, onFlowStart, onFlowComplete,
+ * jsEngine — because this set also drives config-vs-flow detection
+ * (`isWorkspaceConfigFile`).
+ */
+export declare const WORKSPACE_CONFIG_KEYS: ReadonlySet<string>;
+/**
+ * Validate a parsed workspace config.
+ *
+ * Hard errors (thrown): the config isn't a map, or `executionOrder` is present
+ * but malformed. Both are unambiguous mistakes with no valid interpretation, so
+ * failing fast beats a warning that scrolls past in CI.
+ *
+ * Soft problems (warned): unknown top-level keys. These are preserved, not
+ * stripped, and warned about once.
+ *
+ * @param raw - The result of loading the YAML file
+ * @param options - Config file path (for messages) and a warning sink
+ * @returns The validated config, with defaults applied
+ * @throws Error if the config is not a map or `executionOrder` is malformed
+ */
+export declare function parseWorkspaceConfig(raw: unknown, options: {
+    filePath: string;
+    warn: (message: string) => void;
+}): IWorkspaceConfig;

package/dist/services/workspace-config.schema.js

@@ -0,0 +1,206 @@
+import * as yaml from 'js-yaml';
+import { z } from 'zod';
+/**
+ * Runtime schema for a workspace `config.yaml`.
+ *
+ * This is the single source of truth for the config's shape — the TypeScript
+ * type is inferred from it (`IWorkspaceConfig`) rather than declared alongside
+ * it, so the compile-time and runtime views cannot drift. Before this existed
+ * the config was `yaml.load`ed and straight-cast, which meant an
+ * `executionOrder` written in the wrong shape was silently ignored and every
+ * flow ran in parallel (dcd-cli#110).
+ */
+/**
+ * Tags may be written as a bare scalar (`includeTags: smoke`) or a list.
+ * Scalars are wrapped, and primitive members are coerced to strings so a
+ * YAML-numeric tag (`includeTags: [2]`) still compares against flow tags
+ * instead of silently matching nothing.
+ */
+const tagList = z.preprocess((value) => {
+    if (value === null || value === undefined)
+        return value;
+    const members = Array.isArray(value) ? value : [value];
+    return members.map((member) => typeof member === 'number' || typeof member === 'boolean'
+        ? String(member)
+        : member);
+}, z.array(z.string()));
+/** Sequential execution configuration */
+const ExecutionOrderSchema = z.object({
+    // Defaults to true: a failing flow does not stop the rest of the sequence.
+    // Declared here so the default lives in one place instead of being
+    // re-specified at each read site.
+    continueOnFailure: z.boolean().default(true),
+    flowsOrder: z.array(z.string()),
+});
+/**
+ * `looseObject`, not `object`: unknown keys are reported as warnings but must
+ * survive parsing, because the whole config is forwarded to the API as
+ * `fields.workspaceConfig` and stripping keys would silently alter that
+ * payload.
+ */
+export const WorkspaceConfigSchema = z.looseObject({
+    excludeTags: tagList.nullish(),
+    executionOrder: ExecutionOrderSchema.nullish(),
+    flows: z.array(z.string()).nullish(),
+    includeTags: tagList.nullish(),
+    local: z
+        .looseObject({ deterministicOrder: z.boolean().nullish() })
+        .nullish(),
+    notifications: z
+        .looseObject({
+        email: z
+            .looseObject({
+            enabled: z.boolean().optional(),
+            onSuccess: z.boolean().optional(),
+            recipients: z.array(z.string()).optional(),
+        })
+            .optional(),
+    })
+        .nullish(),
+    platform: z
+        .looseObject({
+        android: z
+            .looseObject({ disableAnimations: z.boolean().optional() })
+            .optional(),
+        ios: z
+            .looseObject({ disableAnimations: z.boolean().optional() })
+            .optional(),
+    })
+        .nullish(),
+});
+/**
+ * Top-level keys that only ever appear in a workspace config, derived from the
+ * schema so the two can't drift. Deliberately excludes keys Maestro also allows
+ * in flow front matter — appId, name, tags, env, onFlowStart, onFlowComplete,
+ * jsEngine — because this set also drives config-vs-flow detection
+ * (`isWorkspaceConfigFile`).
+ */
+export const WORKSPACE_CONFIG_KEYS = new Set(Object.keys(WorkspaceConfigSchema.shape));
+/**
+ * Near-misses that aren't just a casing slip on a real key. Keyed lowercase.
+ */
+const KEY_ALIASES = {
+    continueonfailure: 'executionOrder.continueOnFailure',
+    excludetag: 'excludeTags',
+    floworder: 'executionOrder.flowsOrder',
+    flowsorder: 'executionOrder.flowsOrder',
+    includetag: 'includeTags',
+    tags: 'includeTags / excludeTags',
+};
+/**
+ * Suggest the key the author probably meant.
+ * @param unknownKey - Unrecognised top-level key from the config
+ * @returns The suggested key name, or undefined if there's no close match
+ */
+function suggestKey(unknownKey) {
+    const lowered = unknownKey.toLowerCase();
+    const casingSlip = [...WORKSPACE_CONFIG_KEYS].find((key) => key.toLowerCase() === lowered);
+    return casingSlip ?? KEY_ALIASES[lowered];
+}
+/**
+ * Describe how an `executionOrder` value is malformed, in prose.
+ *
+ * Split out so the most likely mistake — a bare list of flow names — gets a
+ * message showing the expected shape rather than a generic schema dump.
+ *
+ * @param value - The raw `executionOrder` value from the config
+ * @returns A description of the problem, or undefined if the shape is valid
+ */
+function describeExecutionOrderShape(value) {
+    if (value === null || value === undefined)
+        return undefined;
+    if (Array.isArray(value))
+        return 'a bare list of flow names';
+    if (typeof value !== 'object')
+        return `a ${typeof value} value`;
+    const { flowsOrder } = value;
+    if (flowsOrder === undefined)
+        return 'a map with no `flowsOrder` key';
+    if (!Array.isArray(flowsOrder)) {
+        return 'a map whose `flowsOrder` is not a list';
+    }
+    return undefined;
+}
+/** Indent a YAML fragment so it reads as a block inside an error message. */
+function indentYaml(value) {
+    return yaml
+        .dump(value, { lineWidth: -1 })
+        .trimEnd()
+        .split('\n')
+        .map((line) => `    ${line}`)
+        .join('\n');
+}
+/**
+ * Build the error for a malformed `executionOrder`, showing what was found
+ * next to what was expected.
+ * @param filePath - Path to the config file, for the message
+ * @param problem - Prose description from describeExecutionOrderShape
+ * @param found - The raw `executionOrder` value that failed
+ * @returns The error to throw
+ */
+function executionOrderError(filePath, problem, found) {
+    return new Error(`Invalid \`executionOrder\` in ${filePath}\n\n` +
+        `\`executionOrder\` must be a map containing a \`flowsOrder\` list, but it is ${problem}.\n\n` +
+        `Found:\n${indentYaml({ executionOrder: found })}\n\n` +
+        `Expected:\n${indentYaml({
+            executionOrder: {
+                continueOnFailure: true,
+                flowsOrder: ['first-flow', 'second-flow'],
+            },
+        })}\n\n` +
+        `Without \`flowsOrder\` the flows are not sequenced — they all run in parallel.`);
+}
+/**
+ * Validate a parsed workspace config.
+ *
+ * Hard errors (thrown): the config isn't a map, or `executionOrder` is present
+ * but malformed. Both are unambiguous mistakes with no valid interpretation, so
+ * failing fast beats a warning that scrolls past in CI.
+ *
+ * Soft problems (warned): unknown top-level keys. These are preserved, not
+ * stripped, and warned about once.
+ *
+ * @param raw - The result of loading the YAML file
+ * @param options - Config file path (for messages) and a warning sink
+ * @returns The validated config, with defaults applied
+ * @throws Error if the config is not a map or `executionOrder` is malformed
+ */
+export function parseWorkspaceConfig(raw, options) {
+    const { filePath, warn } = options;
+    if (raw === null || raw === undefined)
+        return {};
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new Error(`Invalid workspace config in ${filePath}\n\n` +
+            `Expected a map of configuration keys (${[...WORKSPACE_CONFIG_KEYS].join(', ')}), but found ${Array.isArray(raw) ? 'a list' : `a ${typeof raw} value`}.`);
+    }
+    const rawConfig = raw;
+    // Checked ahead of the schema so this specific mistake gets a targeted
+    // message; the schema would otherwise report "expected object, received array".
+    const executionOrderProblem = describeExecutionOrderShape(rawConfig.executionOrder);
+    if (executionOrderProblem) {
+        throw executionOrderError(filePath, executionOrderProblem, rawConfig.executionOrder);
+    }
+    const unknownKeys = Object.keys(rawConfig).filter((key) => !WORKSPACE_CONFIG_KEYS.has(key));
+    if (unknownKeys.length > 0) {
+        const lines = unknownKeys.map((key) => {
+            const suggestion = suggestKey(key);
+            return suggestion
+                ? `  ${key} — did you mean ${suggestion}?`
+                : `  ${key}`;
+        });
+        warn(`Warning: unrecognised key(s) in ${filePath} — these are ignored:\n` +
+            `${lines.join('\n')}\n\n` +
+            `Supported keys: ${[...WORKSPACE_CONFIG_KEYS].join(', ')}`);
+    }
+    const result = WorkspaceConfigSchema.safeParse(rawConfig);
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((issue) => {
+            const location = issue.path.length > 0 ? issue.path.join('.') : '(root)';
+            return `  ${location}: ${issue.message}`;
+        })
+            .join('\n');
+        throw new Error(`Invalid workspace config in ${filePath}\n\n${issues}`);
+    }
+    return result.data;
+}

package/package.json

@@ -31,7 +31,7 @@
     "chai": "^6.2.2",
     "eslint": "^10.5.0",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-unicorn": "^72.0.0",
+    "eslint-plugin-unicorn": "^73.0.0",
     "husky": "^9.1.7",
     "mocha": "^11.7.6",
     "prettier": "^3.8.4",
@@ -59,7 +59,7 @@
     "type": "git",
     "url": "https://devicecloud.dev"
   },
-  "version": "5.3.0",
+  "version": "5.3.1-beta.2",
   "bugs": {
     "url": "https://discord.gg/gm3mJwcNw8"
   },