fix: merge main

Author: ben-zhang-at-salesforce

messages/device-start.md

@@ -24,14 +24,14 @@ starting device %s
 
 # device.start.successStatus.android
 
-device %s started on port %s, writable system = %s
+device '%s' started on port %s, writable system = %s
 
 # device.start.successStatus.ios
 
-device %s started
+device '%s' started
 
 # examples
 
-- <%= config.bin %> <%= command.id %> -p ios -t 'iPhone 16'
-- <%= config.bin %> <%= command.id %> -p ios -t '3627EBD5-E9EC-4EC4-8E89-C6A0232C920D'
-- <%= config.bin %> <%= command.id %> -p android -t 'Pixel 9 API 35' -w
+-   <%= config.bin %> <%= command.id %> -p ios -t 'iPhone 16'
+-   <%= config.bin %> <%= command.id %> -p ios -t '3627EBD5-E9EC-4EC4-8E89-C6A0232C920D'
+-   <%= config.bin %> <%= command.id %> -p android -t 'Pixel 9 API 35' -w

package.json

@@ -1,7 +1,7 @@
 {
     "name": "@salesforce/lwc-dev-mobile",
     "description": "Salesforce CLI plugin for mobile extensions to Local Development",
-    "version": "3.0.0-alpha.1",
+    "version": "3.0.0-alpha.2",
     "author": {
         "name": "Meisam Seyed Aliroteh",
         "email": "maliroteh@salesforce.com",
@@ -36,12 +36,13 @@
     ],
     "bugs": "https://github.com/forcedotcom/lwc-dev-mobile/issues",
     "dependencies": {
-        "@oclif/core": "^4.4.0",
-        "@salesforce/core": "^8.15.0",
-        "@salesforce/lwc-dev-mobile-core": "^4.0.0-alpha.13",
-        "@salesforce/sf-plugins-core": "^12.2.3",
+        "@oclif/core": "^4.8.0",
+        "@salesforce/core": "^8.23.4",
+        "@salesforce/lwc-dev-mobile-core": "^4.0.0-alpha.14",
+        "@salesforce/sf-plugins-core": "^12.2.5",
         "archy": "^1.0.0",
-        "chalk": "^5.4.1"
+        "chalk": "^5.6.2",
+        "zod": "^4.1.12"
     },
     "devDependencies": {
         "@oclif/plugin-command-snapshot": "^5.3.2",

src/cli/commands/force/lightning/local/device/create.ts

@@ -23,6 +23,8 @@ import {
     Requirement,
     RequirementProcessor
 } from '@salesforce/lwc-dev-mobile-core';
+import { z } from 'zod';
+import { DeviceOperationResultSchema, DeviceOperationResultType, DeviceSchema } from '../schema/device.js';
 
 Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
 const messages = Messages.loadMessages('@salesforce/lwc-dev-mobile', 'device-create');
@@ -34,6 +36,7 @@ export class Create extends BaseCommand {
     // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
     public static readonly flags = {
         ...CommandLineUtils.createFlag(FlagsConfigType.JsonFlag, false),
+        ...CommandLineUtils.createFlag(FlagsConfigType.OutputFormatFlag, false),
         ...CommandLineUtils.createFlag(FlagsConfigType.LogLevelFlag, false),
         ...CommandLineUtils.createFlag(FlagsConfigType.ApiLevelFlag, false),
         ...CommandLineUtils.createFlag(FlagsConfigType.PlatformFlag, true),
@@ -70,28 +73,58 @@ export class Create extends BaseCommand {
         return this.flagValues.apilevel as string | undefined;
     }
 
-    public async run(): Promise<void> {
+    protected static getOutputSchema(): z.ZodTypeAny {
+        return DeviceOperationResultSchema;
+    }
+
+    public async run(): Promise<DeviceOperationResultType | void> {
         this.logger.info(`Device Create command invoked for ${this.platform}`);
 
-        return RequirementProcessor.execute(this.commandRequirements)
-            .then(() => {
-                // execute the create command
+        const creationSuccessMessage = messages.getMessage('device.create.successStatus', [
+            this.deviceName,
+            this.deviceType
+        ]);
+
+        try {
+            // if not in JSON mode, execute the requirements and start the CLI action
+            if (!this.jsonEnabled()) {
+                await RequirementProcessor.execute(this.commandRequirements);
                 this.logger.info('Setup requirements met, continuing with Device Create');
+
                 CommonUtils.startCliAction(
                     messages.getMessage('device.create.action'),
                     messages.getMessage('device.create.status', [this.deviceName, this.deviceType])
                 );
-                return this.executeDeviceCreate();
-            })
-            .then(() => {
-                const message = messages.getMessage('device.create.successStatus', [this.deviceName, this.deviceType]);
-                CommonUtils.stopCliAction(message);
-            })
-            .catch((error: Error) => {
+            }
+
+            // execute the device create command
+            await this.executeDeviceCreate();
+
+            if (this.jsonEnabled()) {
+                // In JSON mode, get the device and return it in the format of the DeviceSchema
+                const device = await (CommandLineUtils.platformFlagIsAndroid(this.platform)
+                    ? new AndroidDeviceManager()
+                    : new AppleDeviceManager()
+                ).getDevice(this.deviceName);
+
+                const deviceInfo = DeviceSchema.parse(device);
+                return {
+                    device: deviceInfo,
+                    success: true,
+                    message: creationSuccessMessage
+                };
+            } else {
+                // if cli mode, stop the CLI action
+                CommonUtils.stopCliAction(creationSuccessMessage);
+            }
+        } catch (error) {
+            if (!this.jsonEnabled()) {
+                // if cli mode, stop the CLI action
                 CommonUtils.stopCliAction(messages.getMessage('device.create.failureStatus'));
-                this.logger.warn(`Device Create failed for ${this.platform} - ${error.message}`);
-                return Promise.reject(error);
-            });
+            }
+            this.logger.warn(`Device Create failed for ${this.platform} - ${(error as Error).message}`);
+            throw error;
+        }
     }
 
     protected populateCommandRequirements(): void {

src/cli/commands/force/lightning/local/device/list.ts

@@ -8,6 +8,8 @@
 import chalk from 'chalk';
 import archy from 'archy';
 import { Messages } from '@salesforce/core';
+import { z } from 'zod';
+
 import {
     AndroidDevice,
     AndroidDeviceManager,
@@ -19,6 +21,7 @@ import {
     FlagsConfigType,
     PerformanceMarkers
 } from '@salesforce/lwc-dev-mobile-core';
+import { DeviceListSchema } from '../schema/device.js';
 
 Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
 const messages = Messages.loadMessages('@salesforce/lwc-dev-mobile', 'device-list');
@@ -30,6 +33,7 @@ export class List extends BaseCommand {
     // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
     public static readonly flags = {
         ...CommandLineUtils.createFlag(FlagsConfigType.JsonFlag, false),
+        ...CommandLineUtils.createFlag(FlagsConfigType.OutputFormatFlag, false),
         ...CommandLineUtils.createFlag(FlagsConfigType.LogLevelFlag, false),
         ...CommandLineUtils.createFlag(FlagsConfigType.PlatformFlag, true)
     };
@@ -43,36 +47,32 @@ export class List extends BaseCommand {
         return this.flagValues.platform as string;
     }
 
+    protected static getOutputSchema(): z.ZodTypeAny {
+        return DeviceListSchema;
+    }
+
     public async run(): Promise<AndroidDevice[] | AppleDevice[]> {
         this.logger.info(`Device List command invoked for ${this.platform}`);
 
-        return CommandLineUtils.platformFlagIsIOS(this.platform) ? this.iOSDeviceList() : this.androidDeviceList();
-    }
-
-    private async iOSDeviceList(): Promise<AppleDevice[]> {
-        CommonUtils.startCliAction(
-            messages.getMessage('device.list.action'),
-            messages.getMessage('device.list.status')
-        );
+        if (!this.jsonEnabled()) {
+            CommonUtils.startCliAction(
+                messages.getMessage('device.list.action'),
+                messages.getMessage('device.list.status')
+            );
+        }
         performance.mark(this.perfMarker.startMarkName);
-        const devices = await new AppleDeviceManager().enumerateDevices();
-        performance.mark(this.perfMarker.endMarkName);
-        CommonUtils.stopCliAction();
-        this.showDeviceList(devices);
-        return Promise.resolve(devices);
-    }
 
-    private async androidDeviceList(): Promise<AndroidDevice[]> {
-        CommonUtils.startCliAction(
-            messages.getMessage('device.list.action'),
-            messages.getMessage('device.list.status')
-        );
-        performance.mark(this.perfMarker.startMarkName);
-        const devices = await new AndroidDeviceManager().enumerateDevices();
+        const devices = CommandLineUtils.platformFlagIsAndroid(this.platform)
+            ? await new AndroidDeviceManager().enumerateDevices()
+            : await new AppleDeviceManager().enumerateDevices();
+
         performance.mark(this.perfMarker.endMarkName);
-        CommonUtils.stopCliAction();
-        this.showDeviceList(devices);
-        return Promise.resolve(devices);
+        if (!this.jsonEnabled()) {
+            CommonUtils.stopCliAction();
+            this.showDeviceList(devices);
+        }
+
+        return devices;
     }
 
     private showDeviceList(devices: AndroidDevice[] | AppleDevice[]): void {

src/cli/commands/force/lightning/local/device/start.ts

@@ -22,6 +22,8 @@ import {
     IOSEnvironmentRequirements,
     RequirementProcessor
 } from '@salesforce/lwc-dev-mobile-core';
+import { z } from 'zod';
+import { DeviceOperationResultSchema, DeviceOperationResultType, DeviceSchema } from '../schema/device.js';
 
 Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
 const messages = Messages.loadMessages('@salesforce/lwc-dev-mobile', 'device-start');
@@ -33,6 +35,7 @@ export class Start extends BaseCommand {
     // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
     public static readonly flags = {
         ...CommandLineUtils.createFlag(FlagsConfigType.JsonFlag, false),
+        ...CommandLineUtils.createFlag(FlagsConfigType.OutputFormatFlag, false),
         ...CommandLineUtils.createFlag(FlagsConfigType.LogLevelFlag, false),
         ...CommandLineUtils.createFlag(FlagsConfigType.PlatformFlag, true),
         target: Flags.string({
@@ -64,10 +67,29 @@ export class Start extends BaseCommand {
         return this.flagValues.writablesystem as boolean;
     }
 
-    public async run(): Promise<void> {
+    protected static getOutputSchema(): z.ZodTypeAny {
+        return DeviceOperationResultSchema;
+    }
+
+    public async run(): Promise<DeviceOperationResultType | void> {
         this.logger.info(`Device Start command invoked for ${this.platform}`);
 
-        return RequirementProcessor.execute(this.commandRequirements).then(() => {
+        if (this.jsonEnabled()) {
+            // if in JSON mode, just execute the start command and return the device
+            const device = await this.executeDeviceStart();
+            const deviceInfo = DeviceSchema.parse(device);
+            const message = CommandLineUtils.platformFlagIsAndroid(this.platform)
+                ? this.getAndroidSuccessMessage(device as AndroidDevice)
+                : this.getIOSSuccessMessage();
+            return {
+                device: deviceInfo,
+                success: true,
+                message
+            };
+        }
+
+        // do the RequirementProcessor.execute if not in JSON mode
+        await RequirementProcessor.execute(this.commandRequirements).then(() => {
             // execute the start command
             this.logger.info('Setup requirements met, continuing with Device Start');
             return this.executeDeviceStart();
@@ -84,7 +106,7 @@ export class Start extends BaseCommand {
         this.commandRequirements = requirements;
     }
 
-    private async executeDeviceStart(): Promise<void> {
+    private async executeDeviceStart(): Promise<AndroidDevice | AppleDevice> {
         const isAndroid = CommandLineUtils.platformFlagIsAndroid(this.platform);
 
         const device = isAndroid
@@ -95,24 +117,38 @@ export class Start extends BaseCommand {
             return Promise.reject(messages.getMessage('error.target.doesNotExist', [this.target]));
         }
 
-        CommonUtils.startCliAction(
-            messages.getMessage('device.start.action'),
-            messages.getMessage('device.start.status', [this.target])
-        );
+        if (!this.jsonEnabled()) {
+            CommonUtils.startCliAction(
+                messages.getMessage('device.start.action'),
+                messages.getMessage('device.start.status', [this.target])
+            );
+        }
 
         if (isAndroid) {
             const avd = device as AndroidDevice;
             await avd.boot(true, this.writablesystem ? BootMode.systemWritableMandatory : BootMode.normal);
-            CommonUtils.stopCliAction(
-                messages.getMessage('device.start.successStatus.android', [
-                    this.target,
-                    avd.emulatorPort(),
-                    this.writablesystem
-                ])
-            );
+            if (!this.jsonEnabled()) {
+                CommonUtils.stopCliAction(this.getAndroidSuccessMessage(device as AndroidDevice));
+            }
         } else {
             await (device as AppleDevice).boot(true);
-            CommonUtils.stopCliAction(messages.getMessage('device.start.successStatus.ios', [this.target]));
+            if (!this.jsonEnabled()) {
+                CommonUtils.stopCliAction(this.getIOSSuccessMessage());
+            }
         }
+
+        return device;
+    }
+
+    private getAndroidSuccessMessage(deviceInfo: AndroidDevice): string {
+        return messages.getMessage('device.start.successStatus.android', [
+            this.target,
+            deviceInfo.emulatorPort(),
+            this.writablesystem
+        ]);
+    }
+
+    private getIOSSuccessMessage(): string {
+        return messages.getMessage('device.start.successStatus.ios', [this.target]);
     }
 }

src/cli/commands/force/lightning/local/schema/device.ts

@@ -0,0 +1,39 @@
+/*
+ * Copyright (c) 2025, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+
+import { z } from 'zod';
+
+// Define the schema for the nested 'osVersion' object
+const OsVersionSchema = z.object({
+    major: z.number(),
+    minor: z.number(),
+    patch: z.number()
+});
+
+export const DeviceSchema = z.object({
+    // Required fields present in boto ios and android devices
+    id: z.string().describe('The ID of the device'),
+    name: z.string().describe('The name of the device'),
+    deviceType: z.string().describe('The type of the device'),
+    osType: z.string().describe('The type of the operating system'),
+    osVersion: z.union([z.string(), OsVersionSchema]).describe('The version of the operating system'),
+
+    // fields for Android devices
+    isPlayStore: z.boolean().optional().describe('Whether the android device has google Play Store enabled'),
+    port: z.number().optional().describe('The port number the android device is running on')
+});
+
+// Define the main schema for the device
+export const DeviceListSchema = z.array(DeviceSchema);
+
+export const DeviceOperationResultSchema = z.object({
+    device: DeviceSchema.describe('The device that was operated on'),
+    success: z.boolean().describe('Whether the operation was successful'),
+    message: z.string().optional().describe('The message from the operation')
+});
+
+export type DeviceOperationResultType = z.infer<typeof DeviceOperationResultSchema>;

src/cli/commands/force/lightning/local/setup.ts

@@ -5,10 +5,10 @@
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
  */
 
-import { Setup as CoreSetup } from '@salesforce/lwc-dev-mobile-core';
+import { Setup as CoreSetup, RequirementCheckResultType } from '@salesforce/lwc-dev-mobile-core';
 
 export class Setup extends CoreSetup {
-    public async run(): Promise<void> {
+    public async run(): Promise<RequirementCheckResultType | void> {
         return super.run();
     }
 }