@devicecloud.dev/dcd 4.1.4 → 4.1.5

package/dist/commands/cloud.d.ts

@@ -1,4 +1,16 @@
 import { Command } from '@oclif/core';
+/**
+ * Primary CLI command for executing tests on DeviceCloud.
+ * Orchestrates the complete test workflow:
+ * - Binary upload with SHA deduplication
+ * - Flow file analysis and dependency resolution
+ * - Device compatibility validation
+ * - Test submission with parallel execution
+ * - Real-time result polling with 5-second intervals
+ * - Artifact download (reports, videos, logs)
+ *
+ * Replaces `maestro cloud` with DeviceCloud-specific functionality.
+ */
 export default class Cloud extends Command {
     static args: {
         firstFile: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
@@ -50,12 +62,30 @@ export default class Cloud extends Command {
         apiKey: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
         apiUrl: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
     };
+    /** Service for device/OS compatibility validation */
     private deviceValidationService;
+    /** Service for Moropo test framework integration */
     private moropoService;
+    /** Service for downloading test reports and artifacts */
     private reportDownloadService;
+    /** Service for polling test results with 5-second intervals */
     private resultsPollingService;
+    /** Service for submitting tests to the API */
     private testSubmissionService;
+    /**
+     * Check for CLI updates and notify user if outdated
+     * Compares current version with latest npm release
+     * @returns Promise that resolves when version check is complete
+     */
     private versionCheck;
+    /** Service for CLI version checking */
     private versionService;
+    /**
+     * Main command execution entry point
+     * Orchestrates the complete test submission and monitoring workflow
+     * @returns Promise that resolves when command execution is complete
+     * @throws RunFailedError if tests fail
+     * @throws Error for infrastructure or configuration errors
+     */
     run(): Promise<any>;
 }

package/dist/commands/cloud.js

@@ -23,6 +23,18 @@ process.on('warning', (warning) => {
         // Ignore punycode deprecation warnings
     }
 });
+/**
+ * Primary CLI command for executing tests on DeviceCloud.
+ * Orchestrates the complete test workflow:
+ * - Binary upload with SHA deduplication
+ * - Flow file analysis and dependency resolution
+ * - Device compatibility validation
+ * - Test submission with parallel execution
+ * - Real-time result polling with 5-second intervals
+ * - Artifact download (reports, videos, logs)
+ *
+ * Replaces `maestro cloud` with DeviceCloud-specific functionality.
+ */
 class Cloud extends core_1.Command {
     static args = {
         firstFile: core_1.Args.string({
@@ -40,11 +52,21 @@ class Cloud extends core_1.Command {
     static enableJsonFlag = true;
     static examples = ['<%= config.bin %> <%= command.id %>'];
     static flags = constants_1.flags;
+    /** Service for device/OS compatibility validation */
     deviceValidationService = new device_validation_service_1.DeviceValidationService();
+    /** Service for Moropo test framework integration */
     moropoService = new moropo_service_1.MoropoService();
+    /** Service for downloading test reports and artifacts */
     reportDownloadService = new report_download_service_1.ReportDownloadService();
+    /** Service for polling test results with 5-second intervals */
     resultsPollingService = new results_polling_service_1.ResultsPollingService();
+    /** Service for submitting tests to the API */
     testSubmissionService = new test_submission_service_1.TestSubmissionService();
+    /**
+     * Check for CLI updates and notify user if outdated
+     * Compares current version with latest npm release
+     * @returns Promise that resolves when version check is complete
+     */
     versionCheck = async () => {
         const latestVersion = await this.versionService.checkLatestCliVersion();
         if (latestVersion &&
@@ -57,7 +79,15 @@ class Cloud extends core_1.Command {
   `);
         }
     };
+    /** Service for CLI version checking */
     versionService = new version_service_1.VersionService();
+    /**
+     * Main command execution entry point
+     * Orchestrates the complete test submission and monitoring workflow
+     * @returns Promise that resolves when command execution is complete
+     * @throws RunFailedError if tests fail
+     * @throws Error for infrastructure or configuration errors
+     */
     async run() {
         let output = null;
         // Store debug flag outside try/catch to access it in catch block

package/dist/config/flags/execution.flags.js

@@ -44,7 +44,7 @@ exports.executionFlags = {
     }),
     'runner-type': core_1.Flags.string({
         default: 'default',
-        description: '[experimental] The type of runner to use - note: anything other than default will incur premium pricing tiers, see https://docs.devicecloud.dev/reference/runner-type for more information. gpu1 is Android-only and requires contacting support to enable, otherwise reverts to default.',
-        options: ['default', 'm4', 'm1', 'gpu1'],
+        description: '[experimental] The type of runner to use - note: anything other than default will incur premium pricing tiers, see https://docs.devicecloud.dev/reference/runner-type for more information. gpu1 and cpu1 are Android-only and require contacting support to enable, otherwise reverts to default.',
+        options: ['default', 'm4', 'm1', 'gpu1', 'cpu1'],
     }),
 };

package/dist/gateways/api-gateway.d.ts

@@ -14,14 +14,14 @@ export declare const ApiGateway: {
     downloadArtifactsZip(baseUrl: string, apiKey: string, uploadId: string, results: "ALL" | "FAILED", artifactsPath?: string): Promise<void>;
     finaliseUpload(baseUrl: string, apiKey: string, id: string, metadata: TAppMetadata, path: string, sha: string): Promise<Record<string, never>>;
     getBinaryUploadUrl(baseUrl: string, apiKey: string, platform: "android" | "ios"): Promise<{
-        id: string;
         message: string;
         path: string;
         token: string;
+        id: string;
     }>;
     getResultsForUpload(baseUrl: string, apiKey: string, uploadId: string): Promise<{
-        results?: import("../types/generated/schema.types").components["schemas"]["TResultResponse"][];
         statusCode?: number;
+        results?: import("../types/generated/schema.types").components["schemas"]["TResultResponse"][];
     }>;
     getUploadStatus(baseUrl: string, apiKey: string, options: {
         name?: string;

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

@@ -1,3 +1,4 @@
+/** Email notification configuration */
 interface INotificationsConfig {
     email?: {
         enabled?: boolean;
@@ -5,6 +6,7 @@ interface INotificationsConfig {
         recipients?: string[];
     };
 }
+/** Workspace configuration from config.yaml */
 interface IWorkspaceConfig {
     excludeTags?: null | string[];
     executionOrder?: IExecutionOrder | null;
@@ -13,13 +15,16 @@ interface IWorkspaceConfig {
     local?: ILocal | null;
     notifications?: INotificationsConfig;
 }
+/** Local execution configuration */
 interface ILocal {
     deterministicOrder: boolean | null;
 }
+/** Sequential execution configuration */
 interface IExecutionOrder {
     continueOnFailure: boolean;
     flowsOrder: string[];
 }
+/** Options for execution plan generation */
 export interface PlanOptions {
     configFile?: string;
     debug?: boolean;
@@ -28,6 +33,7 @@ export interface PlanOptions {
     includeTags?: string[];
     input: string;
 }
+/** Execution plan containing all flows to run with metadata and dependencies */
 export interface IExecutionPlan {
     allExcludeTags?: null | string[];
     allIncludeTags?: null | string[];
@@ -39,9 +45,26 @@ export interface IExecutionPlan {
     totalFlowFiles: number;
     workspaceConfig?: IWorkspaceConfig;
 }
+/** Flow sequence configuration for ordered execution */
 interface IFlowSequence {
     continueOnFailure?: boolean;
     flows: string[];
 }
+/**
+ * Generate execution plan for test flows
+ *
+ * Handles:
+ * - Single file or directory input
+ * - Workspace configuration (config.yaml)
+ * - Flow inclusion/exclusion patterns
+ * - Tag-based filtering (include/exclude)
+ * - Dependency resolution (runFlow, scripts, media)
+ * - Sequential execution ordering
+ * - DeviceCloud-specific overrides
+ *
+ * @param options - Plan generation options
+ * @returns Complete execution plan with flows, dependencies, and metadata
+ * @throws Error if input path doesn't exist, no flows found, or dependencies missing
+ */
 export declare function plan(options: PlanOptions): Promise<IExecutionPlan>;
 export {};

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

@@ -5,6 +5,13 @@ const glob_1 = require("glob");
 const fs = require("node:fs");
 const path = require("node:path");
 const execution_plan_utils_1 = require("./execution-plan.utils");
+/**
+ * Recursively check and resolve all dependencies for a flow file
+ * Includes runFlow references, JavaScript scripts, and media files
+ * @param input - Path to flow file to check
+ * @returns Array of all dependency file paths (deduplicated)
+ * @throws Error if any referenced files are missing
+ */
 async function checkDependencies(input) {
     const checkedDependencies = [];
     const uncheckedDependencies = [input];
@@ -35,12 +42,24 @@ async function checkDependencies(input) {
     }
     return checkedDependencies;
 }
+/**
+ * Filter flow files based on exclude patterns
+ * @param unfilteredFlowFiles - All discovered flow files
+ * @param excludeFlows - Patterns to exclude
+ * @returns Filtered array of flow file paths
+ */
 function filterFlowFiles(unfilteredFlowFiles, excludeFlows) {
     if (excludeFlows) {
         return unfilteredFlowFiles.filter((file) => !excludeFlows.some((flow) => path.normalize(file).startsWith(path.normalize(path.resolve(flow)))));
     }
     return unfilteredFlowFiles;
 }
+/**
+ * Load workspace configuration from config.yaml/yml if present
+ * @param input - Input directory path
+ * @param unfilteredFlowFiles - List of discovered flow files
+ * @returns Workspace configuration object (empty if no config file found)
+ */
 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)));
@@ -49,6 +68,12 @@ function getWorkspaceConfig(input, unfilteredFlowFiles) {
         : {};
     return config;
 }
+/**
+ * Extract DeviceCloud-specific override environment variables
+ * Looks for env vars prefixed with DEVICECLOUD_OVERRIDE_
+ * @param config - Flow configuration object
+ * @returns Object containing override key-value pairs
+ */
 function extractDeviceCloudOverrides(config) {
     if (!config || !config.env || typeof config.env !== 'object') {
         return {};
@@ -64,6 +89,22 @@ function extractDeviceCloudOverrides(config) {
     }
     return overrides;
 }
+/**
+ * Generate execution plan for test flows
+ *
+ * Handles:
+ * - Single file or directory input
+ * - Workspace configuration (config.yaml)
+ * - Flow inclusion/exclusion patterns
+ * - Tag-based filtering (include/exclude)
+ * - Dependency resolution (runFlow, scripts, media)
+ * - Sequential execution ordering
+ * - DeviceCloud-specific overrides
+ *
+ * @param options - Plan generation options
+ * @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) {
     const { input, includeTags = [], excludeTags = [], excludeFlows, configFile, debug = false, } = options;
     const normalizedInput = path.normalize(input);