Accept a roku-deploy device option in the launch config, deprecate top-level host

Author: chrisdp

src/LaunchConfiguration.ts

@@ -1,4 +1,4 @@
-import type { DeviceInfoRaw, FileEntry } from 'roku-deploy';
+import type { DeviceInfoRaw, DeviceOption, FileEntry } from 'roku-deploy';
 import type { DebugProtocol } from '@vscode/debugprotocol';
 import type { LogLevel } from './logging';
 
@@ -12,8 +12,18 @@ export interface LaunchConfiguration extends DebugProtocol.LaunchRequestArgument
     cwd: string;
     /**
      * The host or ip address for the target Roku
+     * @deprecated Use `device` instead. When `device` is omitted, a local device config is built from this field.
      */
-    host: string;
+    host?: string;
+
+    /**
+     * The roku-deploy device option for the target device. This is the canonical way to address the device.
+     * Supports every roku-deploy addressing scheme: a local network device (`{ host }`) or a
+     * Roku Cloud Emulator device (`{ instanceUrl | id | esn, rceToken }`).
+     * When omitted, a local device config is built from the deprecated `host` field. When provided with a
+     * `host` property, it takes the place of the top-level `host` field.
+     */
+    device?: DeviceOption;
 
     /**
      * The raw `device-info` for the target Roku. When supplied, the debug session uses this instead of

src/debugProtocol/client/DebugProtocolClient.ts

@@ -1274,9 +1274,10 @@ export interface BreakpointSpec {
 
 export interface ConstructorOptions {
     /**
-     * The host/ip address of the Roku
+     * The host/ip address of the Roku. The debug protocol connects over the local network, so a
+     * session for a device without a host (like a Roku Cloud Emulator device) cannot connect yet.
      */
-    host: string;
+    host?: string;
     /**
      * The port number used to send all debugger commands. This is static/unchanging for Roku devices,
      * but is configurable here to support unit testing or alternate runtimes (i.e. https://www.npmjs.com/package/brs)

src/debugSession/BrightScriptDebugSession.spec.ts

@@ -3093,6 +3093,62 @@ describe('BrightScriptDebugSession', () => {
         });
     });
 
+    describe('device option', () => {
+        it('builds a local device config from host when no device is provided', () => {
+            (session as any).launchConfiguration = { host: '1.2.3.4' };
+            expect(session['device']).to.eql({ host: '1.2.3.4' });
+            expect(session['isLocalDevice']).to.be.true;
+            expect(session['deviceLabel']).to.equal('1.2.3.4');
+        });
+
+        it('builds the device option from the deprecated host field during normalize', () => {
+            const config = session['normalizeLaunchConfig']({ host: '1.2.3.4' } as any);
+            expect(config.device).to.eql({ host: '1.2.3.4' });
+        });
+
+        it('takes host from a local device config during normalize', () => {
+            const config = session['normalizeLaunchConfig']({ device: { host: '5.6.7.8' }, host: '1.2.3.4' } as any);
+            expect(config.host).to.equal('5.6.7.8');
+            (session as any).launchConfiguration = config;
+            expect(session['device']).to.eql({ host: '5.6.7.8' });
+            expect(session['isLocalDevice']).to.be.true;
+        });
+
+        it('passes a cloud emulator device config through untouched and never leaks the token in the label', () => {
+            const device = { instanceUrl: 'https://device.rce.roku.com/instance/abc', rceToken: 'secret' };
+            (session as any).launchConfiguration = { device: device };
+            expect(session['device']).to.equal(device);
+            expect(session['isLocalDevice']).to.be.false;
+            expect(session['deviceLabel']).to.equal('https://device.rce.roku.com/instance/abc');
+            expect(session['deviceLabel']).not.to.include('secret');
+        });
+
+        it('labels id-addressed and esn-addressed cloud emulator devices by their identifier', () => {
+            (session as any).launchConfiguration = { device: { id: '83', rceToken: 'secret' } };
+            expect(session['deviceLabel']).to.equal('83');
+            (session as any).launchConfiguration = { device: { esn: 'XY020078HH5S', rceToken: 'secret' } };
+            expect(session['deviceLabel']).to.equal('XY020078HH5S');
+        });
+
+        it('sends the launch config device to sideload', async () => {
+            const device = { instanceUrl: 'https://device.rce.roku.com/instance/abc', rceToken: 'secret' };
+            (session as any).launchConfiguration = {
+                ...session['launchConfiguration'],
+                device: device,
+                outDir: tempDir
+            };
+            rokuAdapter.connected = true;
+            const sideloadStub = sinon.stub(session.rokuDeploy, 'sideload').callsFake(() => {
+                (session['rokuAdapter'] as TelnetAdapter)['emit']('app-ready');
+                return Promise.resolve({ message: 'success', results: [] });
+            });
+
+            await (session as any).publish();
+
+            expect(sideloadStub.getCall(0).args[0].device).to.equal(device);
+        });
+    });
+
     describe('publish', () => {
         it('waits 60 seconds before aborting when the app never becomes ready', async () => {
             session['publishTimeout'] = 60_000;

src/debugSession/BrightScriptDebugSession.ts

@@ -2,8 +2,8 @@ import * as fsExtra from 'fs-extra';
 import { orderBy } from 'natural-orderby';
 import * as path from 'path';
 import * as semver from 'semver';
-import { rokuDeploy, CompileError, isUpdateCheckRequiredError, isConnectionResetError, EcpNetworkAccessModeDisabledError } from 'roku-deploy';
-import type { DeviceInfo, DeviceOption, RokuDeploy, SideloadOptions } from 'roku-deploy';
+import { rokuDeploy, CompileError, isUpdateCheckRequiredError, isConnectionResetError, EcpNetworkAccessModeDisabledError, isLocalDeviceConfig, isRceDeviceConfig, isRceByUrl, isRceById } from 'roku-deploy';
+import type { DeviceInfo, DeviceOption, LocalDeviceConfig, RokuDeploy, SideloadOptions } from 'roku-deploy';
 import {
     BreakpointEvent,
     LoggingDebugSession,
@@ -359,12 +359,39 @@ export class BrightScriptDebugSession extends LoggingDebugSession {
     public rokuDeploy = rokuDeploy as unknown as RokuDeploy;
 
     /**
-     * The roku-deploy `device` option for the target device. This is the single place where the launch
-     * configuration is converted into a device config, so future device addressing schemes (like the
-     * Roku Cloud Emulator) only need to be handled here.
+     * The roku-deploy `device` option for the target device. This is the canonical way to address the
+     * device; the deprecated `launchConfiguration.host` field is only used as a fallback when the
+     * config has not been normalized yet (normalizeLaunchConfig always sets `device`).
      */
     private get device(): DeviceOption {
-        return { host: this.launchConfiguration.host };
+        return this.launchConfiguration.device ?? { host: this.launchConfiguration.host };
+    }
+
+    /**
+     * Is the target device addressed over the local network (by host/ip)? Only local devices get
+     * host-based treatment like DNS resolution.
+     */
+    private get isLocalDevice(): boolean {
+        const device = this.device;
+        return typeof device === 'object' && isLocalDeviceConfig(device);
+    }
+
+    /**
+     * A short human-readable identifier for the target device, safe for log and error messages
+     * (never includes credentials like the rceToken)
+     */
+    private get deviceLabel(): string {
+        const device = this.device;
+        if (typeof device === 'string') {
+            return device;
+        }
+        if (isRceDeviceConfig(device)) {
+            if (isRceByUrl(device)) {
+                return device.instanceUrl;
+            }
+            return isRceById(device) ? device.id : device.esn;
+        }
+        return device.host ?? this.launchConfiguration.host;
     }
 
     private componentLibraryServer = new ComponentLibraryServer();
@@ -606,6 +633,15 @@ export class BrightScriptDebugSession extends LoggingDebugSession {
      * @returns
      */
     private normalizeLaunchConfig(config: LaunchConfiguration) {
+        //`device` is the canonical way to address the target device; `host` is a deprecated alias.
+        //when a local device config is supplied, its host takes the place of the top-level `host` field
+        //(which every host-based connection like telnet and the debug protocol still reads).
+        //when no device is supplied, build one from the deprecated `host` field.
+        if (typeof config.device === 'object' && isLocalDeviceConfig(config.device) && config.device.host) {
+            config.host = config.device.host;
+        } else if (!config.device) {
+            config.device = { host: config.host };
+        }
         config.cwd ??= process.cwd();
         config.outDir ??= s`${config.cwd}/out`;
         config.stagingDir ??= rokuDeploy.getStagingDir({ outDir: config.outDir, cwd: config.cwd });
@@ -653,11 +689,17 @@ export class BrightScriptDebugSession extends LoggingDebugSession {
 
             this.sendLaunchProgress('start', 'Finding device on network');
 
-            //do a DNS lookup for the host to fix issues with roku rejecting ECP
-            try {
-                this.launchConfiguration.host = await util.dnsLookup(this.launchConfiguration.host);
-            } catch (e) {
-                return this.shutdown(`Could not resolve ip address for host '${this.launchConfiguration.host}'`);
+            //do a DNS lookup for the host to fix issues with roku rejecting ECP.
+            //only applies to local devices; other device types (like the Roku Cloud Emulator) are not addressed by host
+            if (this.isLocalDevice) {
+                try {
+                    const resolvedHost = await util.dnsLookup(this.launchConfiguration.host);
+                    //keep the device config and the deprecated top-level host field in sync with the resolved host
+                    this.launchConfiguration.host = resolvedHost;
+                    (this.launchConfiguration.device as LocalDeviceConfig).host = resolvedHost;
+                } catch (e) {
+                    return this.shutdown(`Could not resolve ip address for host '${this.launchConfiguration.host}'`);
+                }
             }
 
             // fetch device info if not supplied via launch config
@@ -668,17 +710,17 @@ export class BrightScriptDebugSession extends LoggingDebugSession {
                     this.deviceInfo = await rokuDeploy.getDeviceInfo({ device: this.device, ecpPort: this.launchConfiguration.remotePort, enhance: true, timeout: 4_000 });
                 }
                 if (this.deviceInfo.ecpSettingMode === 'limited') {
-                    return await this.shutdown(`To allow the debugger to communicate properly, please ensure on the Roku device that 'Settings' > 'System' > 'Advanced system settings' > 'Control by mobile apps' is set to "Enabled" or "Permissive". Current mode: Limited (device: ${this.launchConfiguration.host})`);
+                    return await this.shutdown(`To allow the debugger to communicate properly, please ensure on the Roku device that 'Settings' > 'System' > 'Advanced system settings' > 'Control by mobile apps' is set to "Enabled" or "Permissive". Current mode: Limited (device: ${this.deviceLabel})`);
                 }
             } catch (e) {
                 if (e instanceof EcpNetworkAccessModeDisabledError) {
-                    return this.shutdown(`To allow the debugger to communicate properly, please ensure on the Roku device that 'Settings' > 'System' > 'Advanced system settings' > 'Control by mobile apps' is set to "Enabled" or "Permissive". Current mode: Disabled (device: ${this.launchConfiguration.host})`);
+                    return this.shutdown(`To allow the debugger to communicate properly, please ensure on the Roku device that 'Settings' > 'System' > 'Advanced system settings' > 'Control by mobile apps' is set to "Enabled" or "Permissive". Current mode: Disabled (device: ${this.deviceLabel})`);
                 }
-                return this.shutdown(`Unable to connect to roku at '${this.launchConfiguration.host}'. Verify the IP address is correct and that the device is powered on and connected to same network as this computer.`);
+                return this.shutdown(`Unable to connect to roku at '${this.deviceLabel}'. Verify the device address is correct and that the device is powered on and reachable.`);
             }
 
             if (this.deviceInfo && !this.deviceInfo.developerEnabled) {
-                return await this.shutdown(`Developer mode is not enabled for host '${this.launchConfiguration.host}'.`);
+                return await this.shutdown(`Developer mode is not enabled for device '${this.deviceLabel}'.`);
             }
 
             // everything is ready, send the response to the launch request so the UI can update and configuration can begin

src/interfaces.ts

@@ -16,7 +16,12 @@ export interface RokuAdapterEvaluateResponse {
 }
 
 export interface AdapterOptions {
-    host: string;
+    /**
+     * The host or ip address of the target device. The telnet and debug-protocol adapters connect
+     * over the local network, so a session for a device without a host (like a Roku Cloud Emulator
+     * device) cannot connect an adapter yet.
+     */
+    host?: string;
     brightScriptConsolePort?: number;
     remotePort?: number;
     /**