feat: add outputformat api support

ben-zhang-at-salesforce · ben-zhang-at-salesforce · commit 34ddee2455e3 · 2025-11-03T16:18:58.000-08:00
diff --git a/messages/app-install.md b/messages/app-install.md
@@ -32,5 +32,5 @@ error encountered
 
 # examples
 
--   <%= config.bin %> <%= command.id %> -p ios -t MyNewVirtualDevice -a \users\bob\myapp\myApp.app
--   <%= config.bin %> <%= command.id %> -p android -t MyNewVirtualDevice -a \users\bob\myapp\myApp.apk
+- <%= config.bin %> <%= command.id %> -p ios -t MyNewVirtualDevice -a \users\bob\myapp\myApp.app
+- <%= config.bin %> <%= command.id %> -p android -t MyNewVirtualDevice -a \users\bob\myapp\myApp.apk
diff --git a/messages/app-launch.md b/messages/app-launch.md
@@ -40,5 +40,5 @@ error encountered
 
 # examples
 
--   <%= config.bin %> <%= command.id %> -p ios -t MyNewVirtualDevice -i com.company.app -a \users\bob\myapp\myApp.app
--   <%= config.bin %> <%= command.id %> -p android -t MyNewVirtualDevice -i com.company.app/.mainActivity -a \users\bob\myapp\myApp.apk
+- <%= config.bin %> <%= command.id %> -p ios -t MyNewVirtualDevice -i com.company.app -a \users\bob\myapp\myApp.app
+- <%= config.bin %> <%= command.id %> -p android -t MyNewVirtualDevice -i com.company.app/.mainActivity -a \users\bob\myapp\myApp.apk
diff --git a/messages/device-start.md b/messages/device-start.md
@@ -32,6 +32,6 @@ 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
diff --git a/src/cli/commands/force/lightning/local/app/install.ts b/src/cli/commands/force/lightning/local/app/install.ts
@@ -19,6 +19,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', 'app-install');
@@ -30,6 +32,7 @@ export class Install 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({
@@ -62,28 +65,58 @@ export class Install extends BaseCommand {
         return this.flagValues.appbundlepath as string;
     }
 
-    public async run(): Promise<void> {
+    protected static getOutputSchema(): z.ZodTypeAny {
+        return DeviceOperationResultSchema;
+    }
+
+    public async run(): Promise<DeviceOperationResultType | void> {
         this.logger.info(`app install command invoked for ${this.platform}`);
 
-        return RequirementProcessor.execute(this.commandRequirements)
-            .then(() => {
-                // environment requirements met, continue with app install
+        const successMessage = messages.getMessage('app.install.successStatus', [this.appBundlePath, this.target]);
+
+        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 app install');
                 CommonUtils.startCliAction(
                     messages.getMessage('app.install.action'),
                     messages.getMessage('app.install.status', [this.appBundlePath, this.target])
                 );
-                return this.executeAppInstall();
-            })
-            .then(() => {
-                const message = messages.getMessage('app.install.successStatus', [this.appBundlePath, this.target]);
-                CommonUtils.stopCliAction(message);
-            })
-            .catch((error: Error) => {
-                this.logger.warn(`App Install failed for ${this.platform} - ${error.message}`);
+            }
+
+            // execute the app install command
+            await this.executeAppInstall();
+
+            if (this.jsonEnabled()) {
+                // In JSON mode, get the device and return it in the format of the DeviceSchema
+                const deviceManager = CommandLineUtils.platformFlagIsAndroid(this.platform)
+                    ? new AndroidDeviceManager()
+                    : new AppleDeviceManager();
+                const device = await deviceManager.getDevice(this.target);
+
+                if (!device) {
+                    throw new Error(messages.getMessage('error.target.doesNotExist', [this.target]));
+                }
+
+                const deviceInfo = DeviceSchema.parse(device);
+                return {
+                    device: deviceInfo,
+                    success: true,
+                    message: successMessage
+                };
+            } else {
+                // if cli mode, stop the CLI action
+                CommonUtils.stopCliAction(successMessage);
+            }
+        } catch (error) {
+            if (!this.jsonEnabled()) {
+                // if cli mode, stop the CLI action
                 CommonUtils.stopCliAction(messages.getMessage('app.install.failureStatus'));
-                return Promise.reject(error);
-            });
+            }
+            this.logger.warn(`App Install failed for ${this.platform} - ${(error as Error).message}`);
+            throw error;
+        }
     }
 
     protected populateCommandRequirements(): void {
diff --git a/src/cli/commands/force/lightning/local/app/launch.ts b/src/cli/commands/force/lightning/local/app/launch.ts
@@ -20,6 +20,8 @@ import {
     LaunchArgument,
     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', 'app-launch');
@@ -31,6 +33,7 @@ export class Launch 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({
@@ -119,28 +122,58 @@ export class Launch extends BaseCommand {
         return this.flagValues.bundleid as string;
     }
 
-    public async run(): Promise<void> {
+    protected static getOutputSchema(): z.ZodTypeAny {
+        return DeviceOperationResultSchema;
+    }
+
+    public async run(): Promise<DeviceOperationResultType | void> {
         this.logger.info(`app launch command invoked for ${this.platform}`);
 
-        return RequirementProcessor.execute(this.commandRequirements)
-            .then(() => {
-                // environment requirements met, continue with app launch
+        const successMessage = messages.getMessage('app.launch.successStatus', [this.bundleId, this.target]);
+
+        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 app launch');
                 CommonUtils.startCliAction(
                     messages.getMessage('app.launch.action'),
                     messages.getMessage('app.launch.status', [this.bundleId, this.target])
                 );
-                return this.executeAppLaunch();
-            })
-            .then(() => {
-                const message = messages.getMessage('app.launch.successStatus', [this.bundleId, this.target]);
-                CommonUtils.stopCliAction(message);
-            })
-            .catch((error: Error) => {
-                this.logger.warn(`App launch failed for ${this.platform} - ${error.message}`);
+            }
+
+            // execute the app launch command
+            await this.executeAppLaunch();
+
+            if (this.jsonEnabled()) {
+                // In JSON mode, get the device and return it in the format of the DeviceSchema
+                const deviceManager = CommandLineUtils.platformFlagIsAndroid(this.platform)
+                    ? new AndroidDeviceManager()
+                    : new AppleDeviceManager();
+                const device = await deviceManager.getDevice(this.target);
+
+                if (!device) {
+                    throw new Error(messages.getMessage('error.target.doesNotExist', [this.target]));
+                }
+
+                const deviceInfo = DeviceSchema.parse(device);
+                return {
+                    device: deviceInfo,
+                    success: true,
+                    message: successMessage
+                };
+            } else {
+                // if cli mode, stop the CLI action
+                CommonUtils.stopCliAction(successMessage);
+            }
+        } catch (error) {
+            if (!this.jsonEnabled()) {
+                // if cli mode, stop the CLI action
                 CommonUtils.stopCliAction(messages.getMessage('app.launch.failureStatus'));
-                return Promise.reject(error);
-            });
+            }
+            this.logger.warn(`App launch failed for ${this.platform} - ${(error as Error).message}`);
+            throw error;
+        }
     }
 
     protected populateCommandRequirements(): void {
diff --git a/test/unit/cli/commands/force/lightning/local/app/install.test.ts b/test/unit/cli/commands/force/lightning/local/app/install.test.ts
@@ -10,10 +10,16 @@ import { Logger } from '@salesforce/core';
 import { TestContext } from '@salesforce/core/testSetup';
 import { stubMethod } from '@salesforce/ts-sinon';
 import {
+    AndroidDevice,
     AndroidDeviceManager,
+    AndroidOSType,
+    AppleDevice,
     AppleDeviceManager,
+    AppleOSType,
     CommonUtils,
-    RequirementProcessor
+    DeviceType,
+    RequirementProcessor,
+    Version
 } from '@salesforce/lwc-dev-mobile-core';
 import { expect } from 'chai';
 import { Install } from '../../../../../../../../src/cli/commands/force/lightning/local/app/install.js';
@@ -48,7 +54,7 @@ describe('App Install Tests', () => {
     });
 
     describe('Android Platform Tests', () => {
-        it('Should successfully install app on Android device', async () => {
+        it('Should successfully install app on Android device for cli mode', async () => {
             const mockDevice = {
                 boot: sinon.stub().resolves(),
                 installApp: sinon.stub().resolves()
@@ -68,7 +74,39 @@ describe('App Install Tests', () => {
             expect(loggerInfoMock.called).to.be.true;
         });
 
-        it('Should handle Android device not found error', async () => {
+        it('Should successfully install app on Android device for JSON mode', async () => {
+            const androidDevice = new AndroidDevice(
+                androidTarget,
+                'Test Android Device',
+                DeviceType.mobile,
+                AndroidOSType.googleAPIs,
+                new Version(35, 0, 0),
+                false
+            );
+
+            const bootMock = stubMethod($$.SANDBOX, AndroidDevice.prototype, 'boot');
+            bootMock.resolves();
+            const installAppMock = stubMethod($$.SANDBOX, AndroidDevice.prototype, 'installApp');
+            installAppMock.resolves();
+
+            const getDeviceMock = stubMethod($$.SANDBOX, AndroidDeviceManager.prototype, 'getDevice');
+            getDeviceMock.resolves(androidDevice);
+
+            const result = await Install.run(['-p', 'android', '-t', androidTarget, '-a', appBundlePath, '--json']);
+
+            expect(executeSetupMock.called).to.be.false;
+            expect(getDeviceMock.calledWith(androidTarget)).to.be.true;
+            expect(bootMock.calledWith(true)).to.be.true;
+            expect(installAppMock.calledWith(appBundlePath)).to.be.true;
+            expect(startCliActionMock.called).to.be.false;
+            expect(stopCliActionMock.called).to.be.false;
+            expect(loggerInfoMock.called).to.be.true;
+            expect(result).to.have.property('success', true);
+            expect(result).to.have.property('device');
+            expect(result).to.have.property('message');
+        });
+
+        it('Should handle Android device not found error for cli mode', async () => {
             const getDeviceMock = stubMethod($$.SANDBOX, AndroidDeviceManager.prototype, 'getDevice');
             getDeviceMock.resolves(null);
 
@@ -84,6 +122,22 @@ describe('App Install Tests', () => {
             }
         });
 
+        it('Should handle Android device not found error for JSON mode', async () => {
+            const getDeviceMock = stubMethod($$.SANDBOX, AndroidDeviceManager.prototype, 'getDevice');
+            getDeviceMock.resolves(null);
+
+            try {
+                await Install.run(['-p', 'android', '-t', androidTarget, '-a', appBundlePath, '--json']);
+                expect.fail('Should have thrown an error');
+            } catch (error) {
+                expect(executeSetupMock.called).to.be.false;
+                expect(getDeviceMock.calledWith(androidTarget)).to.be.true;
+                expect(startCliActionMock.called).to.be.false;
+                expect(stopCliActionMock.called).to.be.false;
+                expect(loggerWarnMock.called).to.be.true;
+            }
+        });
+
         it('Should handle Android device boot failure', async () => {
             const mockDevice = {
                 boot: sinon.stub().rejects(new Error('Boot failed')),
@@ -146,7 +200,7 @@ describe('App Install Tests', () => {
     });
 
     describe('iOS Platform Tests', () => {
-        it('Should successfully install app on iOS device', async () => {
+        it('Should successfully install app on iOS device cli mode', async () => {
             const mockDevice = {
                 boot: sinon.stub().resolves(),
                 installApp: sinon.stub().resolves()
@@ -166,7 +220,38 @@ describe('App Install Tests', () => {
             expect(loggerInfoMock.called).to.be.true;
         });
 
-        it('Should handle iOS device not found error', async () => {
+        it('Should successfully install app on iOS device for JSON mode', async () => {
+            const appleDevice = new AppleDevice(
+                iosTarget,
+                'Test iOS Device',
+                DeviceType.mobile,
+                AppleOSType.iOS,
+                new Version(18, 0, 0)
+            );
+
+            const bootMock = stubMethod($$.SANDBOX, AppleDevice.prototype, 'boot');
+            bootMock.resolves();
+            const installAppMock = stubMethod($$.SANDBOX, AppleDevice.prototype, 'installApp');
+            installAppMock.resolves();
+
+            const getDeviceMock = stubMethod($$.SANDBOX, AppleDeviceManager.prototype, 'getDevice');
+            getDeviceMock.resolves(appleDevice);
+
+            const result = await Install.run(['-p', 'ios', '-t', iosTarget, '-a', iosAppBundlePath, '--json']);
+
+            expect(executeSetupMock.called).to.be.false;
+            expect(getDeviceMock.calledWith(iosTarget)).to.be.true;
+            expect(bootMock.calledWith(true)).to.be.true;
+            expect(installAppMock.calledWith(iosAppBundlePath)).to.be.true;
+            expect(startCliActionMock.called).to.be.false;
+            expect(stopCliActionMock.called).to.be.false;
+            expect(loggerInfoMock.called).to.be.true;
+            expect(result).to.have.property('success', true);
+            expect(result).to.have.property('device');
+            expect(result).to.have.property('message');
+        });
+
+        it('Should handle iOS device not found error for cli mode', async () => {
             const getDeviceMock = stubMethod($$.SANDBOX, AppleDeviceManager.prototype, 'getDevice');
             getDeviceMock.resolves(null);
 
@@ -182,6 +267,22 @@ describe('App Install Tests', () => {
             }
         });
 
+        it('Should handle iOS device not found error for JSON mode', async () => {
+            const getDeviceMock = stubMethod($$.SANDBOX, AppleDeviceManager.prototype, 'getDevice');
+            getDeviceMock.resolves(null);
+
+            try {
+                await Install.run(['-p', 'ios', '-t', iosTarget, '-a', iosAppBundlePath, '--json']);
+                expect.fail('Should have thrown an error');
+            } catch (error) {
+                expect(executeSetupMock.called).to.be.false;
+                expect(getDeviceMock.calledWith(iosTarget)).to.be.true;
+                expect(startCliActionMock.called).to.be.false;
+                expect(stopCliActionMock.called).to.be.false;
+                expect(loggerWarnMock.called).to.be.true;
+            }
+        });
+
         it('Should handle iOS device boot failure', async () => {
             const mockDevice = {
                 boot: sinon.stub().rejects(new Error('Boot failed')),
diff --git a/test/unit/cli/commands/force/lightning/local/app/launch.test.ts b/test/unit/cli/commands/force/lightning/local/app/launch.test.ts
