31208378856

Committed 07 Aug 2026 06:44PM UTC coverage: 73.212% (+0.3%) from 72.934%

Build # 31208378856

Build Type

push

github

Committed by

web-flow

Commit Message

Migrate to roku-deploy v4 and Roku Cloud Emulator support- #399 (#398)

Co-authored-by: Bronley Plumb <bronley@gmail.com>

Coverage Stats

3901 of 5576 branches covered (69.96%)

Branch coverage included in aggregate %.

173 of 195 new or added lines in 12 files covered. (88.72%)

3 existing lines in 2 files now uncovered.

6069 of 8042 relevant lines covered (75.47%)

49.26 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

67.3

/src/debugSession/BrightScriptDebugSession.ts

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, RokuDeploy, SideloadOptions } from 'roku-deploy';
import {
    BreakpointEvent,
    LoggingDebugSession,
    Logger as DapLogger,
    logger as dapLogger,
    CapabilitiesEvent,
    InitializedEvent,
    InvalidatedEvent,
    OutputEvent,
    ProgressEndEvent,
    ProgressStartEvent,
    ProgressUpdateEvent,
    Source,
    StackFrame,
    StoppedEvent,
    TerminatedEvent,
    Thread,
    Variable
} from '@vscode/debugadapter';
import type { SceneGraphCommandResponse } from '../SceneGraphDebugCommandController';
import { SceneGraphDebugCommandController } from '../SceneGraphDebugCommandController';
import type { DebugProtocol } from '@vscode/debugprotocol';
import { defer, util } from '../util';
import { fileUtils, standardizePath as s } from '../FileUtils';
import { ComponentLibraryServer } from '../ComponentLibraryServer';
import { ProjectManager, Project, ComponentLibraryProject } from '../managers/ProjectManager';
import type { EvaluateContainer, Thread as AdapterThread } from '../adapters/DebugProtocolAdapter';
import { DebugProtocolAdapter } from '../adapters/DebugProtocolAdapter';
import { TelnetAdapter } from '../adapters/TelnetAdapter';
import type { BSDebugDiagnostic } from '../CompileErrorProcessor';
import { RendezvousTracker } from '../RendezvousTracker';
import {
    LaunchStartEvent,
    LogOutputEvent,
    RendezvousEvent,
    DiagnosticsEvent,
    StoppedEventReason,
    ChanperfEvent,
    DebugServerLogOutputEvent,
    ChannelPublishedEvent,
    CustomRequestEvent,
    ClientToServerCustomEventName,
    ProfilingErrorEvent,
    ProfilingStartEvent,
    ProfilingStopEvent,
    ProfilingEnabledEvent as ProfilingEnableEvent,
    ProcessCrashEvent
} from './Events';
import type { ProcessCrashEventData } from './Events';
import type { LaunchConfiguration, ComponentLibraryConfiguration } from '../LaunchConfiguration';
import { FileManager } from '../managers/FileManager';
import { SourceMapManager } from '../managers/SourceMapManager';
import { LocationManager } from '../managers/LocationManager';
import type { AugmentedSourceBreakpoint } from '../managers/BreakpointManager';
import type { ResolvedLaunchConfiguration } from '../LaunchConfiguration';
import { BreakpointManager } from '../managers/BreakpointManager';
import type { LogMessage } from '../logging';
import { PerfettoManager } from '../PerfettoManager';
import { logger, FileLoggingManager, debugServerLogOutputEventTransport } from '../logging';
import { VariableType } from '../debugProtocol/events/responses/VariablesResponse';
import { DiagnosticSeverity } from 'brighterscript';
import type { ExceptionBreakpoint } from '../debugProtocol/events/requests/SetExceptionBreakpointsRequest';
import { debounce } from 'debounce';
import { interfaces, components, events } from 'brighterscript/dist/roku-types';
import { globalCallables } from 'brighterscript/dist/globalCallables';
import { bscProjectWorkerPool } from '../bsc/threading/BscProjectWorkerPool';
import { populateVariableFromRegistryEcp } from './ecpRegistryUtils';
import { AppState, rokuECP } from '../RokuECP';
import { SocketConnectionInUseError } from '../Exceptions';

const diagnosticSource = 'roku-debug';

/**
 * Sort tiers for debug-console completions. Lower values sort first, so a variable's own members rank
 * above interface methods, then the file's scope functions, and finally the (large) set of globals.
 */
enum CompletionSortTier {
    Member = '1',
    Method = '2',
    ScopeFunction = '3',
    Global = '4'
}

export class BrightScriptDebugSession extends LoggingDebugSession {
    public constructor() {
        super();

        // this debugger uses one-based lines and columns
        this.setDebuggerLinesStartAt1(false);
        this.setDebuggerColumnsStartAt1(false);

        //give util a reference to this session to assist in logging across the entire module
        util._debugSession = this;

        this.fileManager = new FileManager();
        this.sourceMapManager = new SourceMapManager();
        this.locationManager = new LocationManager(this.sourceMapManager);
        this.breakpointManager = new BreakpointManager(this.sourceMapManager, this.locationManager);
        //send newly-verified breakpoints to vscode
        this.breakpointManager.on('breakpoints-verified', (data) => this.onDeviceBreakpointsChanged('changed', data));
        this.projectManager = new ProjectManager({
            breakpointManager: this.breakpointManager,
            locationManager: this.locationManager
        });
        this.fileLoggingManager = new FileLoggingManager();
    }

    public start(inStream: NodeJS.ReadableStream, outStream: NodeJS.WritableStream): void {
        super.start(inStream, outStream);

        //When the client's pipe goes away (e.g. VS Code closed), stop forwarding output. Otherwise the
        //still-running Roku app keeps streaming output, every write to the dead pipe fails, and each
        //failure re-triggers shutdown() in a tight loop that pegs the CPU and orphans this process.
        const markClientGone = () => {
            this.clientDisconnected = true;
        };
        inStream?.on?.('close', markClientGone);
        inStream?.on?.('end', markClientGone);
        outStream?.on?.('error', markClientGone);

        // Set up DAP protocol logging as early as possible — immediately after start() so we capture
        // the initialize request and all early DAP traffic before launchRequest config is available.
        // The log file path is injected as ROKU_DAP_LOG_FILE by the extension's DebugAdapterDescriptorFactory,
        // which resolves the path from the `brightscript.debug.debugAdapterProtocolLogging` workspace setting
        // (or the equivalent launch.json property) before the debug adapter process is spawned.
        const dapLogFile = process.env.ROKU_DAP_LOG_FILE;
        if (dapLogFile) {
            // Use LogLevel.Error (not Verbose) as the console threshold so DAP messages are written
            // to the log file but are NOT forwarded to VS Code as OutputEvents, which would flood
            // the debug console and break the extension's output parsing.
            // Note: InternalLogger always writes ALL messages to the file stream regardless of level,
            // so the log file will still contain everything.
            dapLogger.setup(DapLogger.LogLevel.Error, dapLogFile);
        }
    }

    /**
     * Once the client has disconnected, drop outgoing events instead of writing to the dead stream.
     * Writing to a broken pipe re-triggers the base 'error' -> shutdown() handler in a tight loop.
     */
    public sendEvent(event: DebugProtocol.Event): void {
        if (this.clientDisconnected) {
            return;
        }
        super.sendEvent(event);
    }

    public setupProcessErrorHandlers() {
        if (this.processErrorHandlersRegistered) {
            return;
        }
        this.processErrorHandlersRegistered = true;

        this._uncaughtExceptionHandler = (error) => this.handleProcessError('uncaughtException', error);
        this._unhandledRejectionHandler = (reason) => this.handleProcessError('unhandledRejection', reason);

        process.on('uncaughtException', this._uncaughtExceptionHandler);
        process.on('unhandledRejection', this._unhandledRejectionHandler);
    }

    private handlingProcessError = false;

    /**
     * True when an error indicates the client (e.g. VS Code) has gone away, such as a broken stdout pipe
     * (EPIPE). Writing to a dead pipe just produces more EPIPEs, so we must not try to report over it.
     */
    private isClientGoneError(error: unknown): boolean {
        const code = (error as NodeJS.ErrnoException)?.code;
        const message = error instanceof Error ? error.message : String(error ?? '');
        return code === 'EPIPE' || /\bEPIPE\b|write after end/i.test(message);
    }

    /**
     * Tear down the process error handlers and forcibly exit, so we never leave an orphaned adapter
     * spinning in the background after the client is gone or a graceful shutdown has hung.
     */
    private forceExit(code = 0): void {
        this.teardownProcessErrorHandlers();
        process.exit(code);
    }

    private handleProcessError(type: 'uncaughtException' | 'unhandledRejection', error: unknown) {
        //a broken client pipe (EPIPE) means the client (e.g. VS Code) is gone. Trying to report it over
        //the now-dead stream just produces more EPIPEs, which re-enter this handler in a tight loop and
        //peg the CPU. Exit instead.
        if (this.isClientGoneError(error)) {
            this.clientDisconnected = true;
            this.forceExit();
            return;
        }
        //only handle the first error; re-entering here (e.g. from a failed write while reporting) would
        //spin the CPU and flood the logs
        if (this.handlingProcessError) {
            return;
        }
        this.handlingProcessError = true;

        const logger = this.logger.createLogger(`${type}`);
        const message = error instanceof Error ? error.message : String(error);
        const stack = error instanceof Error ? error.stack : undefined;
        logger.error(message, stack);

        let output: string;
        let debuggerVersion: string;
        let additionalInfo: ProcessCrashEventData['additionalInfo'];
        try {
            debuggerVersion = (fsExtra.readJsonSync(path.resolve(__dirname, '../../package.json')) as { version: string }).version;

            const clientName = this.initRequestArgs?.clientName ?? 'unknown';

            additionalInfo = {
                clientName: clientName,
                rokuDebugVersion: debuggerVersion,
                ecpMode: this.deviceInfo?.ecpSettingMode,
                developerMode: this.deviceInfo?.developerEnabled,
                firmware: this.deviceInfo ? `${this.deviceInfo?.softwareVersion}.${this.deviceInfo?.softwareBuild}` : undefined,
                protocolVersion: this.deviceInfo?.brightscriptDebuggerVersion,
                protocolEnabled: this.enableDebugProtocol
            };

            const lines = Object.entries(additionalInfo as Record<string, unknown>).map(([key, value]) => {
                // Insert a space before all uppercase letters preceded by a lowercase letter, then uppercase the first char
                const spacedString = key.replace(/([a-z])([A-Z])/g, '$1 $2');
                const formattedKey = spacedString.charAt(0).toUpperCase() + spacedString.slice(1);
                return `**${formattedKey}:** ${JSON.stringify(value)}`;
            });

            const issueBodyPrefix = [
                `**Error type:** ${type}`,
                `**Message:** ${message}`,
                ...lines,
                '',
                `**Steps to reproduce:**`,
                `<!-- Please describe what you were doing when this crash occurred -->`,
                '',
                '**Stack trace:**',
                '```',
                ''
            ].join('\n');
            const issueBodySuffix = '\n```';

            const issueTitle = encodeURIComponent(`[crash] ${type}: ${message}`);
            const baseUrl = 'https://github.com/RokuCommunity/roku-debug/issues/new';
            const maxUrlLength = 2000;
            const urlOverhead = `${baseUrl}?title=${issueTitle}&body=`.length;
            const bodyBudget = maxUrlLength - urlOverhead;
            const encodedPrefix = encodeURIComponent(issueBodyPrefix);
            const encodedSuffix = encodeURIComponent(issueBodySuffix);
            const stackBudget = bodyBudget - encodedPrefix.length - encodedSuffix.length;
            let truncatedStack: string;
            if (!stack) {
                truncatedStack = '(no stack trace)';
            } else if (encodeURIComponent(stack).length <= stackBudget) {
                truncatedStack = stack;
            } else {
                truncatedStack = decodeURIComponent(encodeURIComponent(stack).slice(0, stackBudget)) + '\n...(truncated)';
            }
            const issueUrl = `${baseUrl}?title=${issueTitle}&body=${encodedPrefix}${encodeURIComponent(truncatedStack)}${encodedSuffix}`;

            output = [
                '',
                '================================================================',
                '\tBRIGHTSCRIPT DEBUGGER INTERNAL ERROR',
                '\tThis is a crash in the debug adapter, not in your application.',
                '================================================================',
                `\tError type: ${type}`,
                `\tMessage: ${message}`,
                ...lines.map(l => `\t${l}`),
                '',
                '\tStack trace:',
                ...(stack ?? '(no stack trace)').split('\n').map(l => `\t${l}`),
                '',
                '\tPlease report this at:',
                `\t${issueUrl}`,
                '================================================================',
                ''
            ].join('\n');
        } catch (e) {
            output = JSON.stringify({
                name: e.name,
                message: e.message,
                stack: e.stack
            });
        }

        void this.sendLogOutput(output).catch(() => { /** best-effort */ });
        this.isCrashed = true;
        this.sendEvent(new ProcessCrashEvent({ type, message, stack, additionalInfo: additionalInfo ?? {} }));
        setTimeout(() => void this.shutdown(), 5000).unref();
    }

    public teardownProcessErrorHandlers() {
        if (this._uncaughtExceptionHandler) {
            process.removeListener('uncaughtException', this._uncaughtExceptionHandler);
            this._uncaughtExceptionHandler = undefined;
        }
        if (this._unhandledRejectionHandler) {
            process.removeListener('unhandledRejection', this._unhandledRejectionHandler);
            this._unhandledRejectionHandler = undefined;
        }
        this.processErrorHandlersRegistered = false;
    }

    private onDeviceBreakpointsChanged(eventName: 'changed' | 'new', data: { breakpoints: AugmentedSourceBreakpoint[] }) {
        this.logger.info('Sending verified device breakpoints to client', data);
        //send all verified breakpoints to the client
        for (const breakpoint of data.breakpoints) {
            const event: DebugProtocol.Breakpoint = {
                line: breakpoint.line,
                column: breakpoint.column,
                verified: breakpoint.verified,
                id: breakpoint.id,
                reason: breakpoint.reason,
                message: breakpoint.message,
                source: {
                    path: breakpoint.srcPath
                }
            };
            this.sendEvent(new BreakpointEvent(eventName, event));
        }
    }

    public logger = logger.createLogger(`[session]`);

    private readonly isWindowsPlatform = process.platform.startsWith('win');

    /**
     * A sequence used to help identify log statements for requests
     */
    private idCounter = 1;

    public fileManager: FileManager;

    public projectManager: ProjectManager;

    public fileLoggingManager: FileLoggingManager;

    private processErrorHandlersRegistered = false;
    private isCrashed = false;
    /** Set once the client (e.g. VS Code) disconnects, so we stop writing to a now-dead stream */
    private clientDisconnected = false;
    /** How long to wait for a graceful shutdown before forcibly exiting the process */
    private shutdownForceExitTimeout = 10_000;
    private _uncaughtExceptionHandler: ((error: Error) => void) | undefined;
    private _unhandledRejectionHandler: ((reason: unknown) => void) | undefined;

    public breakpointManager: BreakpointManager;

    public locationManager: LocationManager;

    public sourceMapManager: SourceMapManager;

    //set imports as class properties so they can be spied upon during testing
    public rokuDeploy = rokuDeploy as unknown as RokuDeploy;

    /**
     * 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 {
        return util.getDeviceLabel(this.launchConfiguration.device);
    }

    private componentLibraryServer = new ComponentLibraryServer();

    private rokuAdapterDeferred = defer<DebugProtocolAdapter | TelnetAdapter>();
    /**
     * A promise that is resolved whenever the app has started running for the first time
     */
    private firstRunDeferred = defer<void>();

    /**
     * Resolved whenever we're finished copying all the files to staging for all projects
     */
    private stagingDefered = defer<void>();

    private evaluateRefIdLookup: Record<string, number> = {};
    private evaluateRefIdCounter = 1;

    private variables: Record<number, AugmentedVariable> = {};

    /**
     * Caches the device lookups performed while resolving completion requests. Variables don't change
     * while the debugger is paused, so this avoids repeated round-trips for the same path. Cleared by
     * `clearState` whenever the debugger resumes or steps.
     */
    private completionParentVariableCache = new Map<string, AugmentedVariable>();

    private rokuAdapter: DebugProtocolAdapter | TelnetAdapter;

    private perfettoManager: PerfettoManager;

    private rendezvousTracker: RendezvousTracker;

    public tempVarPrefix = '__rokudebug__';

    /**
     * The progressId of the active launch progress bar, if any.
     * Cleared once the ProgressEndEvent is sent.
     */
    private launchProgressId: string | undefined;

    /**
     * Sends the deferred ProgressEndEvent for the launch progress bar (sendLaunchProgress holds it
     * back for UX). Kept here so shutdown can flush it immediately: the adapter can exit before the
     * delay elapses, which would otherwise leave the client's progress notification stuck open.
     * Cleared once the event has been sent.
     */
    private flushLaunchProgressEnd: (() => void) | undefined;

    /**
     * The first encountered compile error, will be used to send to the client as a runtime error (nicer UI presentation)
     */
    private compileError: BSDebugDiagnostic;

    /**
     * A magic number to represent a fake thread that will be used for showing compile errors in the UI as if they were runtime crashes
     */
    private COMPILE_ERROR_THREAD_ID = 7_777;

    private get enableDebugProtocol() {
        return this.launchConfiguration?.enableDebugProtocol;
    }

    /**
     * Check if the Roku firmware supports Perfetto tracing (requires OS 15.2 or higher)
     */
    private get supportsPerfettoTracing() {
        this.logger.log('Checking if device supports Perfetto tracing', this.deviceInfo.softwareVersion);
        return semver.satisfies(this.deviceInfo?.softwareVersion ?? '0.0', '>= 15.2');
    }

    /**
     * Get a promise that resolves when the roku adapter is ready to be used
     */
    private async getRokuAdapter() {
        await this.rokuAdapterDeferred.promise;
        await this.rokuAdapter.onReady();
        return this.rokuAdapter;
    }

    /**
     * The normalized launch config for this session. The resolved type has no `host` (so nothing in
     * the session can read or write it) and a concrete `device` config, which is the only way the
     * debugger addresses the device. The raw `LaunchConfiguration` exists only as launchRequest's
     * DAP input; normalizeLaunchConfig converts it.
     */
    private launchConfiguration: ResolvedLaunchConfiguration;
    private initRequestArgs: DebugProtocol.InitializeRequestArguments;

    private exceptionBreakpoints: ExceptionBreakpoint[] = [];

    /**
     * The 'initialize' request is the first request called by the frontend
     * to interrogate the features the debug adapter provides.
     */
    public initializeRequest(response: DebugProtocol.InitializeResponse, args: DebugProtocol.InitializeRequestArguments): void {
        this.initRequestArgs = args;
        this.logger.log('initializeRequest');

        response.body ||= {};

        // This debug adapter implements the configurationDoneRequest.
        response.body.supportsConfigurationDoneRequest = true;

        // The debug adapter supports the 'restart' request. In this case a client should not implement 'restart' by terminating and relaunching the adapter but by calling the RestartRequest.
        response.body.supportsRestartRequest = true;

        // make VS Code to use 'evaluate' when hovering over source
        response.body.supportsEvaluateForHovers = true;

        //NOTE: `supportsConditionalBreakpoints` and `supportsHitConditionalBreakpoints` are
        //sent later in the post-connect CapabilitiesEvent once we know which adapter is in use
        //(telnet always supports them via stop-statement rewrites; debug protocol requires v3.1.0+).
        //VS Code reads these caps per-render in the BREAKPOINTS view, so CapabilitiesEvent updates
        //take effect immediately - unlike `exceptionBreakpointFilters` / `breakpointModes` which
        //must be in the initialize response.

        //surface the filter list here so VS Code's BREAKPOINTS panel renders the checkboxes - the
        //panel only reads this list from the initialize response, not from later CapabilitiesEvents.
        //The `supportsExceptionFilterOptions` / `supportsExceptionOptions` booleans are deferred and
        //sent via CapabilitiesEvent once we know the connected device's protocol version.
        response.body.exceptionBreakpointFilters = [{
            filter: 'caught',
            supportsCondition: true,
            conditionDescription: '__brs_err__.rethrown = true',
            label: 'Caught Exceptions',
            description: `Breaks on all errors, even if they're caught later.`,
            default: false
        }, {
            filter: 'uncaught',
            supportsCondition: true,
            conditionDescription: '__brs_err__.rethrown = true',
            label: 'Uncaught Exceptions',
            description: 'Breaks only on errors that are not handled.',
            default: true
        }];

        response.body.supportsCompletionsRequest = true;
        response.body.completionTriggerCharacters = ['.', '(', '{', ',', ' '];

        this.sendResponse(response);

        //register the debug output log transport writer
        debugServerLogOutputEventTransport.setWriter((message: LogMessage) => {
            this.sendEvent(
                new DebugServerLogOutputEvent(
                    message.logger.formatMessage(message, false)
                )
            );
        });

        this.logger.log('initializeRequest finished');
    }

    protected async setExceptionBreakPointsRequest(response: DebugProtocol.SetExceptionBreakpointsResponse, args: DebugProtocol.SetExceptionBreakpointsArguments) {
        response.body ??= {};
        try {

            let filterOptions: ExceptionBreakpoint[];
            if (args.filterOptions) {
                filterOptions = args.filterOptions.map(x => ({
                    filter: x.filterId as 'caught' | 'uncaught',
                    conditionExpression: x.condition
                }));
            } else if (args.filters) {
                filterOptions = args.filters.map(x => ({
                    filter: x as 'caught' | 'uncaught'
                }));
            }
            this.exceptionBreakpoints = filterOptions;

            //wait until the adapter object exists, but don't wait for the device to come online —
            //VS Code will not send configurationDone (and we cannot launch the channel) until we
            //respond to this request.
            await this.rokuAdapterDeferred.promise;

            if (this.rokuAdapter.supportsExceptionBreakpoints) {
                //the adapter queues these filters internally if the debug protocol client hasn't
                //connected yet, and replays them once it does
                await this.rokuAdapter.setExceptionBreakpoints(filterOptions);
                response.body.breakpoints = [
                    { verified: true },
                    { verified: true }
                ];
            } else {
                response.body.breakpoints = [
                    { verified: false },
                    { verified: false }
                ];
            }
        } catch (e) {
            //if error (or not supported)
            response.body.breakpoints = [
                { verified: false },
                { verified: false }
            ];
            this.logger.error('Failed to set exception breakpoints', e);
        } finally {
            this.sendResponse(response);
        }
    }


    protected async setTransientsToInvalid() {
        let brsErr = Object.values(this.variables).find((v) => v.name === '__brs_err__');
        if (brsErr && brsErr.type !== VariableType.Uninitialized) {
            // Assigning the variable to the function call results in it becoming unintialized
            await this.rokuAdapter.evaluate(`__brs_err__ = [].clear()`, brsErr.frameId);
        }
    }

    private async showPopupMessage<T extends string>(message: string, severity: 'error' | 'warn' | 'info', modal = false, actions?: T[]): Promise<T> {
        const response = await this.sendCustomRequest('showPopupMessage', { message: message, severity: severity, modal: modal, actions: actions });
        return response.selectedAction;
    }

    private static requestIdSequence = 0;

    private async sendCustomRequest<T = any, R = any>(name: string, data: T): Promise<R> {
        const requestId = BrightScriptDebugSession.requestIdSequence++;
        const responsePromise = new Promise<R>((resolve, reject) => {
            this.on(ClientToServerCustomEventName.customRequestEventResponse, (response) => {
                if (response.requestId === requestId) {
                    if (response.error) {
                        throw response.error;
                    } else {
                        resolve(response as R);
                    }
                }
            });
        });
        this.sendEvent(
            new CustomRequestEvent({
                requestId: requestId,
                name: name,
                ...data ?? {}
            }));
        return responsePromise;
    }

    /**
      * Get the cwd from the launchConfiguration, or default to process.cwd()
      */
    private get cwd() {
        return this.launchConfiguration?.cwd ?? process.cwd();
    }

    public deviceInfo: DeviceInfo;

    /**
     * Set defaults and standardize values for all of the LaunchConfiguration values
     * @param config
     * @returns
     */
    private normalizeLaunchConfig(config: LaunchConfiguration): ResolvedLaunchConfiguration {
        //`device` is the canonical way to address the target device; `host` is a deprecated alias.
        //this is the ONLY place the debugger reads the top-level `host` field: whatever was supplied
        //is resolved to a concrete device config here, and everything downstream uses `device`.
        if (!config.device && config.host) {
            config.device = { host: config.host };
        }
        //the deprecated field is now consumed. Delete it so the runtime object matches the resolved
        //type and nothing downstream (including the configs echoed back to the client) carries it.
        delete config.host;
        //an RCE device config without a token picks one up from the environment (the extension
        //injects ROKU_RCE_TOKEN into this process so the token does not have to travel through the
        //launch config over DAP). The custom events that echo this config back to the client scrub
        //the token out again (see Events.ts), so it never rides the DAP wire in either direction.
        config.device = util.hydrateRceTokenFromEnv(config.device);
        config.cwd ??= process.cwd();
        config.outDir ??= s`${config.cwd}/out`;
        config.stagingDir ??= util.getStagingDir({ outDir: config.outDir, cwd: config.cwd });
        config.componentLibrariesPort ??= 8080;
        config.packagePort ??= 80;
        config.remotePort ??= 8060;
        config.sceneGraphDebugCommandsPort ??= 8080;
        config.controlPort ??= 8081;
        config.brightScriptConsolePort ??= 8085;
        config.stagingDir ??= config.stagingFolderPath;
        config.emitChannelPublishedEvent ??= true;
        config.rewriteDevicePathsInLogs ??= true;
        config.autoResolveVirtualVariables ??= false;
        config.enhanceREPLCompletions ??= true;
        config.username ??= 'rokudev';
        if (config.profiling?.tracing?.enable) {
            config.profiling.tracing.dir ??= s`${config.cwd}/traces/`;
            // eslint-disable-next-line no-template-curly-in-string
            config.profiling.tracing.filename ??= '${appTitle}_${timestamp}.perfetto-trace';
        }

        // migrate the old `enableVariablesPanel` setting to the new `deferScopeLoading` setting
        if (typeof config.enableVariablesPanel !== 'boolean') {
            config.enableVariablesPanel = true;
        }
        config.deferScopeLoading ??= config.enableVariablesPanel === false;
        return config as ResolvedLaunchConfiguration;
    }

    public async launchRequest(response: DebugProtocol.LaunchResponse, config: LaunchConfiguration) {
        const logEnd = this.logger.timeStart('log', '[launchRequest] launch');

        try {
            this.resetSessionState();
            this.launchConfiguration = this.normalizeLaunchConfig(config);
            //fail fast when the launch config supplied no device addressing at all, rather than
            //failing later with a confusing dns or connection error for an undefined host
            if (!this.launchConfiguration.device) {
                return await this.shutdown(`Launch config does not specify a target device. Please supply the 'device' option (or the deprecated 'host' option).`);
            }
            this.setupProcessErrorHandlers();

            //prebake some threads for our ProjectManager to use later on (1 for the main project, and 1 for every complib)
            bscProjectWorkerPool.preload(1 + (this.launchConfiguration?.componentLibraries?.length ?? 0));

            //set the logLevel provided by the launch config
            if (this.launchConfiguration.logLevel) {
                logger.logLevel = this.launchConfiguration.logLevel;
            }

            this.sendLaunchProgress('start', 'Finding device on network');

            //do a DNS lookup for the host to fix issues with roku rejecting ECP. Only local devices
            //are addressed by host; other device types (like the Roku Cloud Emulator) pass through unchanged
            try {
                this.launchConfiguration.device = await this.rokuDeploy.withDnsResolvedHost(this.launchConfiguration.device);
            } catch (e) {
                return this.shutdown(`Could not resolve ip address for host '${this.deviceLabel}'`);
            }

            // fetch device info if not supplied via launch config
            try {
                if (this.launchConfiguration.deviceInfo) {
                    this.deviceInfo = rokuDeploy.enhanceDeviceInfo(this.launchConfiguration.deviceInfo);
                } else {
                    this.deviceInfo = await rokuDeploy.getDeviceInfo({ device: this.launchConfiguration.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.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.deviceLabel})`);
                }
                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 device '${this.deviceLabel}'.`);
            }

            // everything is ready, send the response to the launch request so the UI can update and configuration can begin
            this.sendResponse(response);

            //initialize all file logging (rokuDevice, debugger, etc)
            this.fileLoggingManager.activate(this.launchConfiguration?.fileLogging, this.cwd);

            this.projectManager.launchConfiguration = this.launchConfiguration;
            this.breakpointManager.launchConfiguration = this.launchConfiguration;

            this.sendEvent(new LaunchStartEvent(this.launchConfiguration));

            this.logger.log('[launchRequest] Packaging and deploying to roku');
            const packageEnd = this.logger.timeStart('log', 'Packaging');
            this.sendLaunchProgress('update', `Packaging Project${(this.launchConfiguration?.componentLibraries?.length ?? 0) > 0 ? 's' : ''}`);
            //build the main project and all component libraries at the same time
            await Promise.all([
                this.prepareMainProject(),
                this.prepareComponentLibraries(this.launchConfiguration.componentLibraries)
            ]);

            //all of the projects have been successfully staged.
            this.stagingDefered.tryResolve();

            //if the client supports it, let it process (inspect/modify) each project's staging dir before we package them
            if (this.launchConfiguration.clientCapabilities?.supportsProcessStagingDir) {
                await this.sendCustomRequest('processStagingDir', {
                    projects: this.projectManager.getProjectStagingInfo()
                });
            }

            packageEnd();

            if (this.enableDebugProtocol) {
                util.log(`Connecting to Roku via the BrightScript debug protocol at ${this.deviceLabel}:${this.launchConfiguration.controlPort}`);
            } else {
                util.log(`Connecting to Roku via telnet at ${this.deviceLabel}:${this.launchConfiguration.brightScriptConsolePort}`);
            }

            //activate rendezvous tracking (if enabled). Log the error and move on if it crashes, this shouldn't bring down the session.
            try {
                const rendezvousEnd = this.logger.timeStart('log', 'Rendezvous tracking');
                await this.initRendezvousTracking();
                rendezvousEnd();
            } catch (e) {
                this.logger.error('Failed to initialize rendezvous tracking', e);
            }

            this.sendLaunchProgress('update', 'Connecting to debug server');
            const connectAdapterEnd = this.logger.timeStart('log', 'Connect adapter');
            this.createRokuAdapter(this.rendezvousTracker);

            // Manipulating complibs on-device autolaunches the dev app and often triggers compile errors,
            // so if we have at least one installable complib, delete the dev app and any complibs to avoid all that.
            if (this.launchConfiguration.componentLibraries?.some(x => x.install)) {
                this.sendLaunchProgress('update', 'Removing existing dev app and component libraries');
                await rokuDeploy.deleteAllSideloadedPlugins({
                    device: this.launchConfiguration.device,
                    password: this.launchConfiguration.password
                });
            }

            await this.connectRokuAdapter();
            connectAdapterEnd();

            // Capabilities that depend on the adapter or device version. The exception-breakpoint
            // FILTER LIST was surfaced in initializeRequest (VS Code only reads it from there).
            // Everything below is read per-action in VS Code, so a CapabilitiesEvent update takes
            // effect dynamically.
            const supportsExceptionBreakpoints = this.rokuAdapter.supportsExceptionBreakpoints;
            this.sendEvent(new CapabilitiesEvent({
                supportsLogPoints: !this.enableDebugProtocol,
                supportsExceptionFilterOptions: supportsExceptionBreakpoints,
                supportsExceptionOptions: supportsExceptionBreakpoints,
                supportsConditionalBreakpoints: this.rokuAdapter.supportsConditionalBreakpoints,
                supportsHitConditionalBreakpoints: this.rokuAdapter.supportsHitConditionalBreakpoints
            }));

            this.sendLaunchProgress('update', 'Configuring breakpoints');

            util.log('Done initializing');

            // notify VS Code that the adapter is ready to receive configuration (breakpoints, etc.)
            // VS Code will respond with setBreakpoints, setExceptionBreakpoints, then configurationDone
            this.sendEvent(new InitializedEvent());

            await this.initializeProfiling();

        } catch (e) {
            //if the message is anything other than compile errors, we want to display the error
            if (!(e instanceof CompileError)) {
                util.log('Encountered an issue during the launch process');
                util.log((e as Error)?.stack);

                //send any compile errors to the client
                await this.rokuAdapter?.sendErrors();

                const message = (e instanceof SocketConnectionInUseError) ? e.message : (e?.stack ?? e);
                await this.shutdown(message as string, true);
            } else {
                this.sendLaunchProgress('end', 'Aborted (compile error)');
            }
        }
        logEnd();
    }

    protected async configurationDoneRequest(response: DebugProtocol.ConfigurationDoneResponse, args: DebugProtocol.ConfigurationDoneArguments) {
        this.logger.log('configurationDoneRequest');
        super.configurationDoneRequest(response, args);

        let error: Error;
        try {
            await this.runAutomaticSceneGraphCommands(this.launchConfiguration.autoRunSgDebugCommands);

            //press the home button to ensure we're at the home screen
            await this.rokuDeploy.keyPress({ device: this.launchConfiguration.device, key: 'Home', ecpPort: this.launchConfiguration.remotePort });

            //pass the log level down thought the adapter to the RendezvousTracker and ChanperfTracker
            this.rokuAdapter.setConsoleOutput(this.launchConfiguration.consoleOutput);

            //pass along the console output
            if (this.launchConfiguration.consoleOutput === 'full') {
                this.rokuAdapter.on('console-output', (data) => {
                    this.sendLogOutput(data).catch(e => this.logger.error('Failed to send log output', e));
                });
            } else {
                this.rokuAdapter.on('unhandled-console-output', (data) => {
                    this.sendLogOutput(data).catch(e => this.logger.error('Failed to send log output', e));
                });
            }

            this.rokuAdapter.on('device-unresponsive', async (data: { lastCommand: string }) => {
                const stopDebuggerAction = 'Stop Debugger';
                const message = `Roku device ${this.deviceLabel} is not responding and may not recover.` +
                    (data.lastCommand ? `\n\nActive command:\n"${util.truncate(data.lastCommand, 30)}"` : '');
                this.logger.log(message, data);
                const response = await this.showPopupMessage(message, 'warn', false, [stopDebuggerAction]);
                if (response === stopDebuggerAction) {
                    await this.shutdown();
                }
            });

            // Send chanperf events to the extension
            this.rokuAdapter.on('chanperf', (output) => {
                this.sendEvent(new ChanperfEvent(output));
            });

            //listen for a closed connection (shut down when received)
            this.rokuAdapter.on('close', (reason = '') => {
                if (reason === 'compileErrors') {
                    error = new Error('compileErrors');
                } else {
                    error = new Error('Unable to connect to Roku. Is another device already connected?');
                }
            });

            // handle any compile errors
            this.rokuAdapter.on('diagnostics', (diagnostics: BSDebugDiagnostic[]) => {
                this.handleDiagnostics(diagnostics).catch(e => this.logger.error('Failed to handle diagnostics', e));
            });

            // close disconnect if required when the app is exited
            // eslint-disable-next-line @typescript-eslint/no-misused-promises
            this.rokuAdapter.on('app-exit', async () => {
                this.resetSessionState();

                if (this.launchConfiguration.stopDebuggerOnAppExit) {
                    let message = `App exit event detected and launchConfiguration.stopDebuggerOnAppExit is true`;
                    message += ' - shutting down debug session';

                    this.logger.log('on app-exit', message);
                    this.sendEvent(new LogOutputEvent(message));
                    await this.shutdown();
                } else {
                    const message = 'App exit detected; but launchConfiguration.stopDebuggerOnAppExit is set to false, so keeping debug session running.';
                    this.logger.log('[configurationDoneRequest]', message);
                    this.sendEvent(new LogOutputEvent(message));
                    this.rokuAdapter.once('connected').then(async () => {
                        await this.rokuAdapter.setExceptionBreakpoints(this.exceptionBreakpoints);
                    }).catch(e => this.logger.error('Failed to set exception breakpoints after reconnect', e));
                }
            });
            //profiling supports connecting to the socket BEFORE a channel is published, so go ahead and connect now
            await this.tryProfilingConnectOnStart();

            //all setBreakpoints requests have arrived by this point (configurationDone is the DAP signal
            //that the client has finished sending configuration). Validate breakpoints across every project
            //in one pass (and inject the STOPs for telnet) - validating per project would fail every other
            //project's breakpoints. Must finish before postfixing renames the complib files.
            await this.writeBreakpoints();

            //postfix each complib's own files now (still no zips. those are sealed after cross-project
            //references are rewritten).
            await this.postfixComponentLibraries(this.launchConfiguration.componentLibraries);

            //now that EVERY project (main + all complibs) is postfixed, rewrite cross-project `Library`
            //references to point at the postfixed file names. Must run before any project zip is sealed.
            await this.projectManager.applyLibraryReferencePostfixes();

            //now zip the main project, also zip and upload installable complibs, and start the webserver for non-installed complibs.
            await Promise.all([
                this.zipMainProject(),
                this.zipServeAndInstallComponentLibraries(this.launchConfiguration.componentLibraries, this.launchConfiguration.componentLibrariesPort)
            ]);

            this.sendLaunchProgress('update', 'Uploading to Roku');
            await this.publish();

            //hack for certain roku devices that lock up when this event is emitted (no idea why!).
            if (this.launchConfiguration.emitChannelPublishedEvent) {
                this.sendEvent(new ChannelPublishedEvent(
                    this.launchConfiguration
                ));
            }

            //tell the adapter adapter that the channel has been launched.
            this.sendLaunchProgress('update', 'Waiting on application');
            await this.rokuAdapter.activate();
            if (this.rokuAdapter.isDestroyed) {
                throw new Error('Debug session encountered an error');
            }
            if (!error) {
                if (this.rokuAdapter.connected) {
                    this.logger.info('Host connection was established before the main public process was completed');
                    this.logger.log(`deployed to Roku@${this.deviceLabel}`);
                } else {
                    this.logger.info('Main public process was completed but we are still waiting for a connection to the host');
                    this.rokuAdapter.on('connected', (status) => {
                        if (status) {
                            this.logger.log(`deployed to Roku@${this.deviceLabel}`);
                        }
                    });
                }
            } else {
                throw error;
            }

            //at this point, the project has been deployed. If we need to use a deep link, launch it now.
            if (this.launchConfiguration.deepLinkUrl && !this.enableDebugProtocol) {
                //wait until the first entry breakpoint has been hit
                await this.firstRunDeferred.promise;
                //if we are at a breakpoint, continue
                await this.rokuAdapter.continue();
                //kill the app on the roku
                // await this.rokuDeploy.keyPress({ device: this.launchConfiguration.device, key: 'Home', ecpPort: this.launchConfiguration.remotePort });
                //convert a hostname to an ip address
                const deepLinkUrl = await util.resolveUrl(this.launchConfiguration.deepLinkUrl);
                //send the deep link http request
                await util.httpPost(deepLinkUrl);
            }

        } catch (e) {
            //if the message is anything other than compile errors, we want to display the error
            if (!(e instanceof CompileError)) {
                util.log('Encountered an issue during the publish process');
                util.log((e as Error)?.stack);

                //send any compile errors to the client
                await this.rokuAdapter?.sendErrors();

                const message = (e instanceof SocketConnectionInUseError) ? e.message : (e?.stack ?? e);
                await this.shutdown(message as string, true);
            } else {
                this.sendLaunchProgress('end', 'Aborted (compile error)');
            }
        }
    }

    /**
     * Activate all required functionality for profiling
     */
    private async initializeProfiling() {

        // Initialize PerfettoManager
        this.perfettoManager = new PerfettoManager({
            device: this.launchConfiguration.device,
            rootDir: this.launchConfiguration.rootDir,
            remotePort: this.launchConfiguration.remotePort,
            ...this.launchConfiguration.profiling?.tracing
        });

        //send certain profiling events back to the client
        this.perfettoManager.on('enable', (event) => {
            this.sendEvent(new ProfilingEnableEvent({
                types: event.types
            }));
        });
        this.perfettoManager.on('start', (event) => {
            this.sendEvent(new ProfilingStartEvent({
                type: event.type
            }));
        });
        this.perfettoManager.on('stop', (event) => {
            this.sendEvent(new ProfilingStopEvent({
                type: event.type,
                result: event.result
            }));
        });
        this.perfettoManager.on('error', (event) => {
            this.sendEvent(new ProfilingErrorEvent({
                error: event.error
            }));
        });

        //tracing is explicitly enabled. Turn it on
        if (this.launchConfiguration.profiling?.tracing?.enable && this.supportsPerfettoTracing) {
            this.logger.info('Enabling perfetto tracing because it is supported by the device and enabled in the launch configuration');
            try {
                await this.perfettoManager?.enableTracing?.();
            } catch (e) {
                this.logger.error('Failed to enable perfetto tracing', e);
            }

            //tracing is expicitly DISabled. turn it off
        } else if (this.launchConfiguration.profiling?.tracing?.enable === false && this.supportsPerfettoTracing) {
            this.logger.info('Disabling perfetto tracing because it is disabled in the launch configuration');
            //TODO implement a way to disable perfetto tracing on the device

            //tracing was requested but the device firmware does not meet the minimum requirement
        } else if (this.launchConfiguration.profiling?.tracing?.enable && !this.supportsPerfettoTracing) {
            const firmwareVersion = this.deviceInfo?.softwareVersion ?? 'unknown';
            const message = `Perfetto profiling is not available: device firmware ${firmwareVersion} is below the minimum required version (15.2). The Perfetto profiling buttons will not be available during this session.`;
            this.logger.warn(message);
            this.showPopupMessage(message, 'warn').catch(e => this.logger.error('Failed to show Perfetto unavailable notification', e));

            //profiling.tracing.enabled is set to `undefined`, which means we should do nothing
        } else {
            this.logger.info('Skipping perfetto initalization because `profiling.tracing.enable` is not defined in the launch configuration');
        }
    }

    /**
     * If profiling was marked "connectOnStart", try connecting right away
     */
    private async tryProfilingConnectOnStart() {
        if (this.launchConfiguration.profiling?.tracing?.connectOnStart && this.supportsPerfettoTracing) {
            try {
                await this.perfettoManager?.startTracing?.();
            } catch (e) {
                this.logger.error('Failed to start perfetto tracing on start', e);
            }
        } else if (this.launchConfiguration.profiling?.tracing?.connectOnStart && !this.supportsPerfettoTracing) {
            const firmwareVersion = this.deviceInfo?.softwareVersion ?? 'unknown';
            const message = `Perfetto profiling is not available: device firmware ${firmwareVersion} is below the minimum required version (15.2). Tracing will not start automatically.`;
            this.logger.warn(message);
            this.showPopupMessage(message, 'warn').catch(e => this.logger.error('Failed to show Perfetto unavailable notification', e));
        }
    }

    /**
     * Clear certain properties that need reset whenever a debug session is restarted (via vscode or launched from the Roku home screen)
     */
    private resetSessionState() {
        // launchRequest gets invoked by our restart session flow.
        // We need to clear/reset some state to avoid issues.
        this.entryBreakpointWasHandled = false;
        //reset all per-session breakpoint state (diff baseline + cached parsed ASTs) since a restart
        //re-stages the project
        this.breakpointManager.reset();
    }

    /**
     * Activate rendezvous tracking (IF enabled in the LaunchConfig)
     */
    public async initRendezvousTracking() {
        const timeout = 5000;
        let initCompleted = false;
        await Promise.race([
            util.sleep(timeout),
            this._initRendezvousTracking().finally(() => {
                initCompleted = true;
            })
        ]);

        if (initCompleted === false) {
            this.showPopupMessage(`Rendezvous tracking timed out after ${timeout}ms. Consider setting "rendezvousTracking": false in launch.json`, 'warn').catch((error) => {
                this.logger.error('Error showing popup message', { error });
            });
        }
    }

    private async _initRendezvousTracking() {
        this.rendezvousTracker = new RendezvousTracker(this.deviceInfo, this.launchConfiguration);

        //pass the debug functions used to locate the client files and lines thought the adapter to the RendezvousTracker
        this.rendezvousTracker.registerSourceLocator(async (debuggerPath: string, lineNumber: number) => {
            return this.projectManager.getSourceLocation(debuggerPath, lineNumber);
        });

        // Send rendezvous events to the debug protocol client
        this.rendezvousTracker.on('rendezvous', (output) => {
            this.sendEvent(new RendezvousEvent(output));
        });

        //clear the history so the user doesn't have leftover rendezvous data from a previous session
        this.rendezvousTracker.clearHistory();

        //if rendezvous tracking is enabled, then enable it on the device
        if (this.launchConfiguration.rendezvousTracking !== false) {
            // start ECP rendezvous tracking (if possible)
            await this.rendezvousTracker.activate();
        }
    }

    /**
     * Anytime a roku adapter emits diagnostics, this method is called to handle it.
     */
    private async handleDiagnostics(diagnostics: BSDebugDiagnostic[]) {
        // Roku device and sourcemap work with 1-based line numbers, VSCode expects 0-based lines.
        for (let diagnostic of diagnostics) {
            diagnostic.source = diagnosticSource;
            let sourceLocation = await this.projectManager.getSourceLocation(diagnostic.path, diagnostic.range.start.line + 1);
            if (sourceLocation) {
                diagnostic.path = sourceLocation.filePath;
                diagnostic.range.start.line = sourceLocation.lineNumber - 1; //sourceLocation is 1-based, but we need 0-based
                diagnostic.range.end.line = sourceLocation.lineNumber - 1; //sourceLocation is 1-based, but we need 0-based
            } else {
                // TODO: may need to add a custom event if the source location could not be found by the ProjectManager
                diagnostic.path = fileUtils.removeLeadingSlash(util.removeFileScheme(diagnostic.path));
            }
        }

        //find the first compile error (i.e. first DiagnosticSeverity.Error) if there is one
        this.compileError = diagnostics.find(x => x.severity === DiagnosticSeverity.Error);
        if (this.compileError) {
            this.sendLaunchProgress('end', 'Aborted (compile error)');
            this.sendEvent(new StoppedEvent(
                StoppedEventReason.exception,
                this.COMPILE_ERROR_THREAD_ID,
                `CompileError: ${this.compileError.message}`
            ));
        }

        this.sendEvent(new DiagnosticsEvent(diagnostics));
    }

    private publishTimeout = 60_000;

    private async publish() {
        const uploadingEnd = this.logger.timeStart('log', 'Uploading zip');
        let packageIsPublished = false;

        //delete any currently installed dev channel (if enabled to do so)
        try {
            if (this.launchConfiguration.deleteDevChannelBeforeInstall === true) {
                await this.rokuDeploy.deleteDevChannel({
                    device: this.launchConfiguration.device,
                    password: this.launchConfiguration.password,
                    username: this.launchConfiguration.username,
                    packagePort: this.launchConfiguration.packagePort
                });
            }
        } catch (e) {
            const statusCode = e?.results?.response?.statusCode;
            const message = e.message as string;
            if (statusCode === 401) {
                await this.shutdown(message, true);
                throw e;
            }
            this.logger.warn('Failed to delete the dev channel...probably not a big deal', e);
        }

        const isConnected = this.rokuAdapter.once('app-ready');
        const options: SideloadOptions = {
            device: this.launchConfiguration.device,
            password: this.launchConfiguration.password,
            username: this.launchConfiguration.username,
            packagePort: this.launchConfiguration.packagePort,
            ecpPort: this.launchConfiguration.remotePort,
            //sideload the zip that was already built from the staging folder (or supplied via packagePath)
            zip: this.launchConfiguration.packagePath ?? util.getOutputZipPath({ outDir: this.launchConfiguration.outDir }),
            // enable the debug protocol if true
            remoteDebug: this.enableDebugProtocol,
            //necessary for capturing compile errors from the protocol (has no effect on telnet)
            remoteDebugConnectEarly: false,
            //we don't want to fail if there were compile errors...we'll let our compile error processor handle that
            failOnCompileError: true,
            //deleting the dev channel (when enabled) was already handled at the start of this function
            deleteDevChannel: false,
            //the device was already sent to the home screen during configurationDone
            close: false,
            //pass any upload form overrides the client may have configured
            packageUploadOverrides: this.launchConfiguration.packageUploadOverrides
        };

        //publish the package to the target Roku
        const publishPromise = this.rokuDeploy.sideload(options).then(() => {
            packageIsPublished = true;
        }).catch(async (e) => {
            const statusCode = e?.results?.response?.statusCode;
            const message = e.message as string;
            if ((statusCode && statusCode !== 200) || isUpdateCheckRequiredError(e) || isConnectionResetError(e)) {
                await this.shutdown(message, true);
                throw e;
            }
            this.logger.error(e);
        });

        await publishPromise;

        uploadingEnd();

        //the channel has been deployed. Wait for the adapter to finish connecting.
        //if it hasn't connected after 60 seconds, abort the launch.
        let didTimeOut = false;
        await Promise.race([
            isConnected,
            util.sleep(this.publishTimeout).then(() => {
                didTimeOut = true;
            })
        ]);
        this.logger.log('Finished racing promises');
        if (didTimeOut) {
            this.logger.warn('Timed out waiting for roku to connect');
        }
        //if the adapter is still not connected, then it will probably never connect. Abort.
        if (packageIsPublished && !this.rokuAdapter.connected) {
            return this.shutdown('Debug session cancelled: failed to connect to debug protocol control port.');
        }
    }

    private pendingSendLogPromise = Promise.resolve();

    /**
     * Send log output to the "client" (i.e. vscode)
     * @param logOutput
     */
    private sendLogOutput(logOutput: string) {
        if (this.isCrashed) {
            return Promise.resolve();
        }
        this.fileLoggingManager.writeRokuDeviceLog(logOutput);

        this.pendingSendLogPromise = this.pendingSendLogPromise.then(async () => {
            logOutput = await this.convertBacktracePaths(logOutput);

            const lines = logOutput.split(/\r?\n/g);
            for (let i = 0; i < lines.length; i++) {
                let line = lines[i];
                if (i < lines.length - 1) {
                    line += '\n';
                }

                if (this.launchConfiguration.rewriteDevicePathsInLogs) {
                    let potentialPaths = this.getPotentialPkgPaths(line);
                    for (let potentialPath of potentialPaths) {
                        let originalLocation = await this.projectManager.getSourceLocation(potentialPath.path, potentialPath.lineNumber, potentialPath.columnNumber);
                        if (originalLocation) {
                            let replacement: string;
                            replacement = originalLocation.filePath.replaceAll(' ', '%20');
                            if (replacement !== originalLocation.filePath) {
                                if (this.isWindowsPlatform) {
                                    replacement = `vscode://file/${replacement}`;
                                } else {
                                    replacement = `file://${replacement}`;
                                }
                            }
                            replacement += `:${originalLocation.lineNumber}`;
                            if (potentialPath.columnNumber !== undefined) {
                                replacement += `:${originalLocation.columnIndex + 1}`;
                            }

                            line = line.replaceAll(potentialPath.fullMatch, replacement);
                        }
                    }
                }
                this.sendEvent(new OutputEvent(line, 'stdout'));
                this.sendEvent(new LogOutputEvent(line));
            }
        });
        return this.pendingSendLogPromise;
    }

    /**
     * Extracts potential package paths from a given line of text.
     *
     * This method uses a regular expression to find matches in the provided line
     * and returns an array of objects containing details about each match.
     *
     * @param input - The line of text to search for potential package paths.
     * @returns An array of objects, each containing:
     *   - `fullMatch`: The full matched string.
     *   - `path`: The extracted path from the match.
     *   - `lineNumber`: The line number extracted from the match.
     *   - `columnNumber`: The column number extracted from the match, or `undefined` if not found.
     */
    private getPotentialPkgPaths(input: string): Array<{ fullMatch: string; path: string; lineNumber: number; columnNumber: number }> {
        // https://regex101.com/r/ixpQiq/1
        let matches = input.matchAll(/((?:\.\.\.|[A-Za-z_0-9]*pkg\:\/)[A-Za-z_0-9 \/\.]+\.[A-Za-z_0-9 \/]+)(?:(?:\:)(\d+)(?:\:(\d+))?|\((\d+)(?:\:(\d+))?\))/ig);
        let paths: ReturnType<BrightScriptDebugSession['getPotentialPkgPaths']> = [];
        if (matches) {
            for (let match of matches) {
                let fullMatch = match[0];
                let path = match[1];
                let lineNumber = parseInt(match[2] ?? match[4]);
                let columnNumber = parseInt(match[3] ?? match[5]);
                if (isNaN(columnNumber)) {
                    columnNumber = undefined;
                }
                paths.push({
                    fullMatch: fullMatch,
                    path: path,
                    lineNumber: lineNumber,
                    columnNumber: columnNumber
                });
            }
        }
        return paths;
    }

    /**
     * Converts the filename property in backtrace objects in the given input string to source paths if found
     */
    private async convertBacktracePaths(input: string) {
        if (!this.launchConfiguration.rewriteDevicePathsInLogs) {
            return input;
        }
        // Why does this not work? It should work, but it doesn't. I'm not sure why.
        // let matches = input.matchAll(this.deviceBacktraceObjectRegex);

        // https://regex101.com/r/y1koaV/2
        let deviceBacktraceObjectRegex = /{\s+filename:\s+"([A-Za-z0-9_\.\/\: ]+)"\s+function\:\s+".+"\s+(line_number\:\s+(\d+))\s+}/gi;
        let matches = [];
        let match = deviceBacktraceObjectRegex.exec(input);
        while (match) {
            matches.push(match);
            match = deviceBacktraceObjectRegex.exec(input);
        }

        if (matches) {
            for (let match of matches) {
                let fullMatch = match[0] as string;
                let filePath = match[1] as string;
                let fullLineNumber = match[2] as string;
                let lineNumber = parseInt(match[3] as string);
                let originalLocation = await this.projectManager.getSourceLocation(filePath, lineNumber);
                if (originalLocation) {
                    let fileReplacement: string;
                    fileReplacement = originalLocation.filePath.replaceAll(' ', '%20');
                    if (fileReplacement !== originalLocation.filePath) {
                        if (this.isWindowsPlatform) {
                            fileReplacement = `vscode://file/${fileReplacement}`;
                        } else {
                            fileReplacement = `file://${fileReplacement}`;
                        }
                    }
                    fileReplacement += `:${originalLocation.lineNumber}`;

                    let lineNumberReplacement = fullLineNumber.replace(lineNumber.toString(), originalLocation.lineNumber.toString());

                    // replace the full backtrace object with the an updated version so we don't modify other parts of the log output that might contain the same file path
                    let completeReplacement = fullMatch.replace(filePath, fileReplacement);
                    completeReplacement = completeReplacement.replace(fullLineNumber, lineNumberReplacement);
                    input = input.replaceAll(fullMatch, completeReplacement);
                }

            }
        }

        return input;
    }

    private async runAutomaticSceneGraphCommands(commands: string[]) {
        if (commands) {
            let connection = new SceneGraphDebugCommandController(this.launchConfiguration.device, this.launchConfiguration.sceneGraphDebugCommandsPort);

            try {
                await connection.connect();
                for (let command of this.launchConfiguration.autoRunSgDebugCommands) {
                    let response: SceneGraphCommandResponse;
                    switch (command) {
                        case 'chanperf':
                            util.log('Enabling Chanperf Tracking');
                            response = await connection.chanperf({ interval: 1 });
                            if (!response.error) {
                                util.log(response.result.rawResponse);
                            }
                            break;

                        case 'fpsdisplay':
                            util.log('Enabling FPS Display');
                            response = await connection.fpsDisplay('on');
                            if (!response.error) {
                                util.log(response.result.data as string);
                            }
                            break;

                        case 'logrendezvous':
                            util.log('Enabling Rendezvous Logging:');
                            response = await connection.logrendezvous('on');
                            if (!response.error) {
                                util.log(response.result.rawResponse);
                            }
                            break;

                        default:
                            util.log(`Running custom SceneGraph debug command on port 8080 '${command}':`);
                            response = await connection.exec(command);
                            if (!response.error) {
                                util.log(response.result.rawResponse);
                            }
                            break;
                    }
                }
                await connection.end();
            } catch (error) {
                util.log(`Error connecting to port 8080: ${error.message}`);
            }
        }
    }

    /**
     * Stage, insert breakpoints, and package the main project
     */
    public async prepareMainProject() {
        //add the main project
        this.projectManager.mainProject = new Project({
            rootDir: this.launchConfiguration.rootDir,
            files: this.launchConfiguration.files,
            outDir: this.launchConfiguration.outDir,
            sourceDirs: this.launchConfiguration.sourceDirs,
            bsConst: this.launchConfiguration.bsConst,
            injectRaleTrackerTask: this.launchConfiguration.injectRaleTrackerTask,
            raleTrackerTaskFileLocation: this.launchConfiguration.raleTrackerTaskFileLocation,
            injectRdbOnDeviceComponent: this.launchConfiguration.injectRdbOnDeviceComponent,
            rdbFilesBasePath: this.launchConfiguration.rdbFilesBasePath,
            stagingDir: this.launchConfiguration.stagingDir,
            packagePath: this.launchConfiguration.packagePath,
            enhanceREPLCompletions: this.launchConfiguration.enhanceREPLCompletions
        });

        util.log('Moving selected files to staging area');
        await this.projectManager.mainProject.stage();

        //add the entry breakpoint if stopOnEntry is true
        await this.handleEntryBreakpoint();
    }

    /**
     * Validate every breakpoint against the staged projects and (telnet only) write STOP statements into the
     * staged .brs files. Runs after the DAP `InitializedEvent` so client-side `setBreakpoints` requests have
     * landed before any STOPs are written. Validates the main project and every component library in ONE pass:
     * a breakpoint is only failed when it can't be placed in any project, so validating per project would fail
     * every other project's breakpoints. Must complete before `postfixComponentLibraries` renames the complib
     * files so telnet STOPs are written to the original file names.
     */
    private async writeBreakpoints() {
        //add breakpoint lines to source files and then publish
        util.log('Adding stop statements for active breakpoints');

        //validate breakpoints for all debugger types (and write `stop` statements for telnet — decided internally)
        await this.breakpointManager.validateAndWriteBreakpointsForProjects(this.projectManager.getAllProjects());
    }

    /**
     * Create the main project's zip package (or run the configured packageTask). Must run AFTER
     * `applyLibraryReferencePostfixes` so any rewritten `Library` statements are included in the zip.
     */
    private async zipMainProject() {
        if (this.launchConfiguration.packageTask) {
            util.log(`Executing task '${this.launchConfiguration.packageTask}' to assemble the app`);
            await this.sendCustomRequest('executeTask', { task: this.launchConfiguration.packageTask });

            const packagePath = this.launchConfiguration.packagePath ?? util.getOutputZipPath({ outDir: this.launchConfiguration.outDir });

            if (!fsExtra.pathExistsSync(packagePath)) {
                return this.shutdown(`Cancelling debug session. Package does not exist at '${packagePath}'`);
            }
        } else {
            //create zip package from staging folder
            util.log('Creating zip archive from project sources');
            await this.projectManager.mainProject.zipPackage({ retainStagingFolder: true });
        }
    }

    /**
     * Accepts custom events and requests from the extension
     * @param command name of the command to execute
     */
    protected async customRequest(command: string, response: DebugProtocol.Response, args: any) {
        if (command === 'rendezvous.clearHistory') {
            this.rokuAdapter.clearRendezvousHistory();
        } else if (command === 'chanperf.clearHistory') {
            this.rokuAdapter.clearChanperfHistory();

        } else if (command === 'customRequestEventResponse') {
            this.emit('customRequestEventResponse', args);

        } else if (command === 'popupMessageEventResponse') {
            this.emit('popupMessageEventResponse', args);

        } else if (command === 'captureHeapSnapshot') {
            this.perfettoManager?.captureHeapSnapshot?.().catch((e) => this.logger.error('Failed to capture heap snapshot', e));

        } else if (command === 'startPerfettoTracing') {
            try {
                await this.perfettoManager?.startTracing?.();
            } catch (e) {
                response.success = false;
                response.body = { message: e?.message || String(e) };
            }

        } else if (command === 'stopPerfettoTracing') {
            try {
                await this.perfettoManager?.stopTracing?.();
            } catch (e) {
                response.success = false;
                response.body = { message: e?.message || String(e) };
            }

        }
        this.sendResponse(response);
    }

    /**
     * Stores the path to the staging folder for each component library
     */
    protected async prepareComponentLibraries(componentLibraries: ComponentLibraryConfiguration[]) {
        if (!componentLibraries || componentLibraries.length === 0) {
            return;
        }
        let componentLibrariesOutDir = s`${this.launchConfiguration.outDir}/component-libraries`;
        //make sure this folder exists (and is empty)
        await fsExtra.ensureDir(componentLibrariesOutDir);
        await fsExtra.emptyDir(componentLibrariesOutDir);

        //create a ComponentLibraryProject for each component library
        for (let libraryIndex = 0; libraryIndex < componentLibraries.length; libraryIndex++) {
            let componentLibrary = componentLibraries[libraryIndex];

            this.projectManager.componentLibraryProjects.push(
                new ComponentLibraryProject({
                    rootDir: componentLibrary.rootDir,
                    files: componentLibrary.files,
                    outDir: componentLibrariesOutDir,
                    outFile: componentLibrary.outFile,
                    sourceDirs: componentLibrary.sourceDirs,
                    bsConst: componentLibrary.bsConst,
                    install: componentLibrary.install,
                    enablePostfix: componentLibrary.enablePostfix,
                    injectRaleTrackerTask: componentLibrary.injectRaleTrackerTask,
                    raleTrackerTaskFileLocation: componentLibrary.raleTrackerTaskFileLocation,
                    libraryIndex: libraryIndex,
                    enhanceREPLCompletions: this.launchConfiguration.enhanceREPLCompletions
                })
            );
        }

        //stage all of the libraries in parallel
        await Promise.all(
            this.projectManager.componentLibraryProjects.map(compLibProject => compLibProject.stage())
        );
    }

    /**
     * Postfix each staged complib's own files (rename its `.brs` files with the `__lib<index>` postfix and
     * rewrite its `uri=` references). Runs in `configurationDoneRequest` AFTER `writeBreakpoints` so any
     * telnet STOPs have already been written to the original file names. Kept separate from zipping so the
     * cross-project `Library` reference rewrite can run after EVERY project is postfixed but before any zip
     * is sealed.
     */
    protected async postfixComponentLibraries(componentLibraries: ComponentLibraryConfiguration[]) {
        if (!componentLibraries || componentLibraries.length === 0) {
            return;
        }

        //postfix each complib's own files in parallel
        await Promise.all(
            this.projectManager.componentLibraryProjects.map(compLibProject => compLibProject.postfixFiles())
        );
    }

    /**
     * Seal every component library's zip, install the installable ones (in order), and start static file
     * hosting. Must run AFTER `applyLibraryReferencePostfixes` so each zip contains the rewritten `Library`
     * statements.
     */
    protected async zipServeAndInstallComponentLibraries(componentLibraries: ComponentLibraryConfiguration[], port: number) {
        if (!componentLibraries || componentLibraries.length === 0) {
            return;
        }
        const componentLibrariesOutDir = s`${this.launchConfiguration.outDir}/component-libraries`;

        const needToDeleteComplibs = this.projectManager.componentLibraryProjects.some(x => x.install);
        if (needToDeleteComplibs) {
            //deleteAllComponentLibraries pauses compile-error reporting (to swallow deletion-induced errors) and
            //leaves it paused. Now that deletion is done and we're about to put libraries back on the device, settle
            //(draining any lingering deletion output) and resume reporting so real install errors are surfaced.
            await this.deleteAllComponentLibraries();
        }

        //zip each complib in parallel
        const packagePromises = this.projectManager.componentLibraryProjects.map(
            compLibProject => compLibProject.zipPackage({ retainStagingFolder: true })
        );

        //install component libraries strictly in their declared order (which must be dependency order:
        //a library may only depend on libraries declared before it). Each install is fully awaited before the
        //next begins, and a failure aborts the launch. Installing out of order, or continuing past a failed
        //install, leaves the device with dangling `Library` references that fail to compile.
        for (let i = 0; i < this.projectManager.componentLibraryProjects.length; i++) {
            const compLibProject = this.projectManager.componentLibraryProjects[i];

            if (compLibProject.install === true) {
                //wait for this complib to finish being packaged
                await packagePromises[i];

                if (componentLibraries[i].packageTask) {
                    await this.sendCustomRequest('executeTask', { task: componentLibraries[i].packageTask });
                }

                const options: SideloadOptions = {
                    device: this.launchConfiguration.device,
                    password: this.launchConfiguration.password,
                    username: this.launchConfiguration.username || 'rokudev',
                    packagePort: this.launchConfiguration.packagePort,
                    ecpPort: this.launchConfiguration.remotePort,
                    zip: componentLibraries[i].packagePath ?? util.getOutputZipPath({ outDir: compLibProject.outDir, outFile: compLibProject.outFile }),
                    failOnCompileError: true,
                    appType: 'dcl',
                    //installing a component library should never close or delete the sideloaded channel
                    close: false,
                    deleteDevChannel: false,
                    packageUploadOverrides: componentLibraries[i].packageUploadOverrides || {}
                };

                util.log(`Installing component library ${i} (${compLibProject.outFile})`);
                try {
                    await rokuDeploy.sideload(options);
                    util.log(`Installed component library ${i} (${compLibProject.outFile})`);
                } catch (error) {
                    //do NOT continue installing further libraries (or publishing the main app) - a failed install
                    //here means later libraries and the main app would reference a library that isn't on the device
                    this.logger.error(`Error installing component library ${i} (${compLibProject.outFile})`, error);
                    throw error;
                }
            }
        }

        const hostingPromise = this.componentLibraryServer.startStaticFileHosting(componentLibrariesOutDir, port, (message: string) => {
            util.log(message);
        });

        //wait for all complib packaging to finish and the file hosting to start
        await Promise.all([
            ...packagePromises,
            hostingPromise
        ]);
    }

    /**
     * Delete every component library installed on the device.
     *
     * A complib can only depend on complibs the user declared BEFORE it, so the user's configured order is already
     * dependency order. Deleting in the REVERSE of that order therefore deletes each complib before the ones it
     * depends on, avoiding compile errors entirely. We use that reverse order as the delete priority.
     *
     * Anything still installed that the user did NOT configure (e.g. leftovers from a previous session) has no known
     * order, so we fall back to compile-error tolerance for those: deleting a complib while another still references
     * it fails with a compile error, which we ignore and retry later (after its dependent is gone). We finish when
     * every complib is gone, and fail if the only complibs left are ones that can never be deleted.
     */
    private async deleteAllComponentLibraries() {
        const deviceOptions = {
            device: this.launchConfiguration.device,
            password: this.launchConfiguration.password,
            username: this.launchConfiguration.username || 'rokudev'
        };

        //The user's configured complibs, in REVERSE declaration order (dependents before their dependencies). A
        //complib's position here is its delete priority; complibs the user didn't configure aren't in this list.
        const deletePriority = this.projectManager.componentLibraryProjects
            .map(complib => complib.outFile)
            .reverse();
        //sort key for a complib: its index in `deletePriority`, or Infinity (delete last) if it wasn't configured
        const priorityOf = (fileName: string) => {
            const index = deletePriority.indexOf(fileName);
            return index === -1 ? Infinity : index;
        };

        const maxAttempts = 5;
        //how many times we've tried to delete each complib, and the ones we've given up on after maxAttempts
        const attempts = new Map<string, number>();
        const failed = new Set<string>();

        while (true) {
            //re-fetch the installed complibs after each iteration: deleting one complib can cascade-delete others, so never delete a stale entry
            const installed = (await rokuDeploy.listSideloadedPlugins(deviceOptions)).filter(x => x.appType === 'dcl');

            const attemptCount = (complib: { archiveFileName: string }) => attempts.get(complib.archiveFileName) ?? 0;

            //of the complibs we haven't given up on, pick the next to delete: fewest attempts first (spreads retries
            //evenly so a dependent gets deleted before we circle back to a complib that previously failed), and among
            //equal attempts, follow the reverse-configured delete priority (dependents before dependencies).
            const candidates = installed.filter(complib => !failed.has(complib.archiveFileName));
            const next = candidates.sort((a, b) =>
                attemptCount(a) - attemptCount(b) ||
                priorityOf(a.archiveFileName) - priorityOf(b.archiveFileName)
            )[0];

            //nothing left to try — done if the device is clear, otherwise hard-fail with whatever remains
            if (!next) {
                if (installed.length > 0) {
                    throw new Error(`Failed to delete existing component libraries on device; ${installed.length} still installed: ${installed.map(x => x.archiveFileName).join(', ')}`);
                }
                return;
            }

            const fileName = next.archiveFileName;
            attempts.set(fileName, (attempts.get(fileName) ?? 0) + 1);
            try {
                await rokuDeploy.deleteComponentLibrary({ ...deviceOptions, fileName: fileName });
            } catch (error) {
                //re-throw anything that isn't a dependency compile error (auth, network, etc.)
                if (!this.isComponentLibraryDependencyCompileError(error)) {
                    throw error;
                }
                //Deleting a complib that a dependent still references produces a compile error - but the delete may
                //STILL have succeeded (the device reports both a compile error and 'Delete Succeeded'). If it actually
                //deleted, treat it as done. Only if it did NOT succeed do we defer and retry it later.
                if (this.wasComponentLibraryDeleteSuccessful(error)) {
                    this.logger.trace(`Deleted '${fileName}' (device reported a compile error but the delete succeeded)`);
                } else {
                    //another not-yet-deleted complib still depends on this one. Give up on it once it's out of
                    //attempts; otherwise leave it pending so we retry after its dependents are gone.
                    if (attempts.get(fileName) >= maxAttempts) {
                        failed.add(fileName);
                    }
                    this.logger.log(`Deferring delete of '${fileName}'; another component library still depends on it`);
                }
            }

            //the Roku doesn't appreciate back-to-back deletes; give it a moment between requests
            await util.sleep(10);
        }
    }

    /**
     * Is this error the device reporting a compile failure (which, during complib deletion, means another
     * installed complib still references the one we tried to delete)?
     */
    private isComponentLibraryDependencyCompileError(error: any): boolean {
        const message = `${error?.message ?? ''}`;
        return /compile error|compilation failed/i.test(message);
    }

    /**
     * Did the component-library delete actually succeed, even though the device also reported a compile error?
     * When we delete a complib that a dependent still references, the device reports BOTH a compile error AND a
     * `Delete Succeeded` message - meaning the complib really was removed. roku-deploy attaches the parsed device
     * messages (`{ errors, infos, successes }`) to the thrown error as `rokuMessages`; we look for the success there.
     * Absence of that success message means the delete did NOT happen, so it should be treated as a failure/retry.
     */
    private wasComponentLibraryDeleteSuccessful(error: any): boolean {
        const successes: string[] = error?.rokuMessages?.successes ?? [];
        return successes.some(message => /delete succeeded/i.test(message));
    }

    protected sourceRequest(response: DebugProtocol.SourceResponse, args: DebugProtocol.SourceArguments) {
        this.logger.log('sourceRequest');
        let old = this.sendResponse;
        this.sendResponse = function sendResponse(...args) {
            old.apply(this, args);
            this.sendResponse = old;
        };
        super.sourceRequest(response, args);
    }

    /**
     * Called every time a breakpoint is created, modified, or deleted, for each file. This receives the entire list of breakpoints every time.
     */
    public async setBreakPointsRequest(response: DebugProtocol.SetBreakpointsResponse, args: DebugProtocol.SetBreakpointsArguments) {
        this.logger.log('setBreakpointsRequest', args);
        let sanitizedBreakpoints = this.breakpointManager.replaceBreakpoints(args.source.path, args.breakpoints);
        //sort the breakpoints
        let sortedAndFilteredBreakpoints = orderBy(sanitizedBreakpoints, [x => x.line, x => x.column]);

        response.body = {
            breakpoints: sortedAndFilteredBreakpoints
        };
        this.sendResponse(response);

        //ensure we've staged all the files
        await this.stagingDefered.promise;

        await this.rokuAdapter?.syncBreakpoints();
    }

    protected exceptionInfoRequest(response: DebugProtocol.ExceptionInfoResponse, args: DebugProtocol.ExceptionInfoArguments) {
        this.logger.log('exceptionInfoRequest');
    }

    protected async threadsRequest(response: DebugProtocol.ThreadsResponse) {
        this.logger.log('threadsRequest');

        let threads = [];

        //This is a bit of a hack. If there's a compile error, send a thread to represent it so we can show the compile error like a runtime exception
        if (this.compileError) {
            threads.push(new Thread(this.COMPILE_ERROR_THREAD_ID, 'Compile Error'));
        } else {
            //wait for the roku adapter to load
            await this.getRokuAdapter();

            //only send the threads request if we are at the debugger prompt
            if (this.rokuAdapter.isAtDebuggerPrompt) {
                let rokuThreads = await this.rokuAdapter.getThreads();

                for (let thread of rokuThreads) {
                    const threadName = this.getThreadName(thread as AdapterThread);
                    threads.push(
                        new Thread(thread.threadId, threadName)
                    );
                }

                if (threads.length === 0) {
                    threads = [{
                        id: 1001,
                        name: 'unable to retrieve threads: not stopped',
                        isFake: true
                    }];
                }

            } else {
                this.logger.log('Skipped getting threads because the RokuAdapter is not accepting input at this time.');
            }

        }

        response.body = {
            threads: threads
        };

        this.sendResponse(response);
    }

    /**
     * Get the thread name to display in the UI based on the thread info we have.
     * This is what displays in the `call stack` region in vscode
     * @param thread
     * @returns
     */
    private getThreadName(thread: AdapterThread) {
        let threadName = '';
        if (thread.type || thread.name || thread.osThreadId) {
            //build the name from only the parts that are present, so missing values don't leak into the name
            const parts: string[] = [];
            if (thread.type) {
                parts.push(`[${thread.type}]`);
            }
            if (thread.name) {
                parts.push(thread.name);
            }
            if (thread.osThreadId) {
                parts.push(thread.osThreadId);
            }
            threadName = parts.join(' ');
        }
        //remove any extraneous whitespace to deal with missing values
        threadName = threadName.replace(/\s+/g, ' ').trim();

        if (threadName === '') {
            threadName = `Thread ${thread.threadId}`;
        }

        if (thread.isDetached) {
            threadName += ' [detached]';
        }

        //remove any extraneous whitespace to deal with missing values
        threadName = threadName.replace(/\s+/g, ' ').trim();

        return threadName;
    }

    protected async stackTraceRequest(response: DebugProtocol.StackTraceResponse, args: DebugProtocol.StackTraceArguments) {
        try {
            this.logger.log('stackTraceRequest');
            let frames: DebugProtocol.StackFrame[] = [];

            //this is a bit of a hack. If there's a compile error, send a full stack frame so we can show the compile error like a runtime crash
            if (this.compileError) {
                frames.push(new StackFrame(
                    0,
                    'Compile Error',
                    new Source(path.basename(this.compileError.path), this.compileError.path),
                    // range is 0-based; toClientLine/toClientColumn handle client coordinate conversion
                    this.toClientLine(this.compileError.range.start.line),
                    this.toClientColumn(this.compileError.range.start.character)
                ));
            } else if (args.threadId === 1001) {
                frames.push(new StackFrame(
                    0,
                    'ERROR: threads would not stop',
                    new Source('main.brs', s`${this.launchConfiguration.stagingDir}/manifest`),
                    this.toClientLine(0),
                    this.toClientColumn(0)
                ));
                this.showPopupMessage('Unable to suspend threads. Debugger is in an unstable state, please press Continue to resume debugging', 'warn').catch((error) => {
                    this.logger.error('Error showing popup message', { error });
                });
            } else {
                //ensure the rokuAdapter is loaded
                await this.getRokuAdapter();

                if (this.rokuAdapter.isAtDebuggerPrompt) {
                    let stackTrace = await this.rokuAdapter.getStackTrace(args.threadId);
                    if (stackTrace.length === 0) {
                        // Thread is detached or encountered an error requesting Stack Trace — show a non-interactive label so VS Code can display
                        // the thread without letting the user navigate to a source location
                        const frame = new StackFrame(0, '[unavailable]');
                        frame.presentationHint = 'label';
                        frames.push(frame);
                    } else {
                        for (let debugFrame of stackTrace) {
                            let sourceLocation = await this.projectManager.getSourceLocation(debugFrame.filePath, debugFrame.lineNumber);

                            //the stacktrace returns function identifiers in all lower case. Try to get the actual case
                            //load the contents of the file and get the correct casing for the function identifier
                            try {
                                let functionName = this.fileManager.getCorrectFunctionNameCase(sourceLocation?.filePath, debugFrame.functionIdentifier);
                                if (functionName) {

                                    //search for original function name if this is an anonymous function.
                                    //anonymous function names are prefixed with $ in the stack trace (i.e. $anon_1 or $functionname_40002)
                                    if (functionName.startsWith('$')) {
                                        functionName = this.fileManager.getFunctionNameAtPosition(
                                            sourceLocation.filePath,
                                            sourceLocation.lineNumber - 1,
                                            functionName
                                        );
                                    }
                                    debugFrame.functionIdentifier = functionName;
                                }
                            } catch (error) {
                                this.logger.error('Error correcting function identifier case', { error, sourceLocation, debugFrame });
                            }
                            const filePath = sourceLocation?.filePath ?? debugFrame.filePath;

                            const frame: DebugProtocol.StackFrame = new StackFrame(
                                debugFrame.frameId,
                                `${debugFrame.functionIdentifier}`,
                                new Source(path.basename(filePath), filePath),
                                // lineNumber is 1-based from Roku; toClientLine expects 0-based
                                this.toClientLine((sourceLocation?.lineNumber ?? debugFrame.lineNumber) - 1),
                                this.toClientColumn(0)
                            );
                            if (!sourceLocation) {
                                frame.presentationHint = 'subtle';
                            }
                            frames.push(frame);
                        }
                    }
                } else {
                    this.logger.log('Skipped calculating stacktrace because the RokuAdapter is not accepting input at this time');
                }
            }
            response.body = {
                stackFrames: frames,
                totalFrames: frames.length
            };
            this.sendResponse(response);
        } catch (error) {
            this.logger.error('Error getting stacktrace', { error, args });
        }
    }

    protected async scopesRequest(response: DebugProtocol.ScopesResponse, args: DebugProtocol.ScopesArguments) {
        const logger = this.logger.createLogger(`scopesRequest ${this.idCounter}`);
        logger.info('begin', { args });
        try {
            const scopes = new Array<DebugProtocol.Scope>();

            // create the locals scope
            let v = this.getOrCreateLocalsScope(args.frameId);

            let localScope: DebugProtocol.Scope = {
                name: 'Local',
                variablesReference: v.variablesReference,
                // Flag the locals scope as expensive if the client asked that it be loaded lazily
                expensive: this.launchConfiguration.deferScopeLoading,
                presentationHint: 'locals'
            };

            const frame = this.rokuAdapter.getStackFrameById(args.frameId);
            if (frame) {
                const scopeRange = await this.projectManager.getScopeRange(frame.filePath, { line: frame.lineNumber - 1, character: 0 });

                if (scopeRange) {
                    localScope.line = this.toClientLine(scopeRange.start.line - 1);
                    localScope.column = this.toClientColumn(scopeRange.start.column);
                    localScope.endLine = this.toClientLine(scopeRange.end.line - 1);
                    localScope.endColumn = this.toClientColumn(scopeRange.end.column);
                }
            }

            scopes.push(localScope);

            // create the registry scope
            let registryRefId = this.getEvaluateRefId('$$registry', Infinity);
            scopes.push(<DebugProtocol.Scope>{
                name: 'Registry',
                variablesReference: registryRefId,
                expensive: true
            });

            this.variables[registryRefId] = {
                variablesReference: registryRefId,
                name: 'Registry',
                value: '',
                type: '$$Registry',
                isScope: true,
                childVariables: []
            };

            response.body = {
                scopes: scopes
            };
            logger.debug('send response', { response });
            this.sendResponse(response);
            logger.info('end');
        } catch (error) {
            logger.error('Error getting scopes', { error, args });
        }
    }

    /**
     * Get the locals scope container for a frame, creating an (unpopulated) one if it doesn't exist yet.
     * The child variables are filled in lazily by `populateScopeVariables`.
     */
    private getOrCreateLocalsScope(frameId: number): AugmentedVariable {
        const refId = this.getEvaluateRefId('$$locals', frameId);
        if (!this.variables[refId]) {
            this.variables[refId] = {
                variablesReference: refId,
                name: 'Locals',
                value: '',
                type: '$$Locals',
                frameId: frameId,
                isScope: true,
                childVariables: []
            };
        }
        return this.variables[refId];
    }

    protected async continueRequest(response: DebugProtocol.ContinueResponse, args: DebugProtocol.ContinueArguments) {
        //if we have a compile error, we should shut down
        if (this.compileError) {
            this.sendResponse(response);
            await this.shutdown();
            return;
        }

        this.logger.log('continueRequest');
        await this.setTransientsToInvalid(); // call before clearState
        this.clearState();

        // The debug session ends after the next line. Do not put new work after this line.
        await this.rokuAdapter.continue();
        this.sendResponse(response);
    }

    protected async pauseRequest(response: DebugProtocol.PauseResponse, args: DebugProtocol.PauseArguments) {
        this.logger.log('pauseRequest');

        //if we have a compile error, we should shut down
        if (this.compileError) {
            this.sendResponse(response);
            await this.shutdown();
            return;
        }

        await this.rokuAdapter.pause();
        this.sendResponse(response);
    }

    protected reverseContinueRequest(response: DebugProtocol.ReverseContinueResponse, args: DebugProtocol.ReverseContinueArguments) {
        this.logger.log('reverseContinueRequest');
        this.sendResponse(response);
    }

    /**
     * Clicked the "Step Over" button
     * @param response
     * @param args
     */
    protected async nextRequest(response: DebugProtocol.NextResponse, args: DebugProtocol.NextArguments) {
        this.logger.log('[nextRequest] begin');

        //if we have a compile error, we should shut down
        if (this.compileError) {
            this.sendResponse(response);
            await this.shutdown();
            return;
        }

        await this.setTransientsToInvalid(); // call before clearState
        this.clearState();

        // The debug session ends after the next line. Do not put new work after this line.
        try {
            await this.rokuAdapter.stepOver(args.threadId);
            this.logger.info('[nextRequest] end');
        } catch (error) {
            this.logger.error(`[nextRequest] Error running '${BrightScriptDebugSession.prototype.nextRequest.name}()'`, error);
        }
        this.sendResponse(response);
    }

    protected async stepInRequest(response: DebugProtocol.StepInResponse, args: DebugProtocol.StepInArguments) {
        this.logger.log('[stepInRequest]');

        //if we have a compile error, we should shut down
        if (this.compileError) {
            this.sendResponse(response);
            await this.shutdown();
            return;
        }

        await this.setTransientsToInvalid(); // call before clearState
        this.clearState();
        // The debug session ends after the next line. Do not put new work after this line.
        await this.rokuAdapter.stepInto(args.threadId);
        this.sendResponse(response);
        this.logger.info('[stepInRequest] end');
    }

    protected async stepOutRequest(response: DebugProtocol.StepOutResponse, args: DebugProtocol.StepOutArguments) {
        this.logger.log('[stepOutRequest] begin');

        //if we have a compile error, we should shut down
        if (this.compileError) {
            this.sendResponse(response);
            await this.shutdown();
            return;
        }

        await this.setTransientsToInvalid(); // call before clearState
        this.clearState();

        // The debug session ends after the next line. Do not put new work after this line.
        await this.rokuAdapter.stepOut(args.threadId);
        this.sendResponse(response);
        this.logger.info('[stepOutRequest] end');
    }

    protected stepBackRequest(response: DebugProtocol.StepBackResponse, args: DebugProtocol.StepBackArguments) {
        this.logger.log('[stepBackRequest] begin');
        this.sendResponse(response);
        this.logger.info('[stepBackRequest] end');
    }

    public async variablesRequest(response: DebugProtocol.VariablesResponse, args: DebugProtocol.VariablesArguments) {
        const logger = this.logger.createLogger('[variablesRequest]');
        let sendInvalidatedEvent = false;
        let frameId: number = null;
        try {
            logger.log('begin', { args });

            //ensure the rokuAdapter is loaded
            await this.getRokuAdapter();

            let updatedVariables: AugmentedVariable[] = [];
            //wait for any `evaluate` commands to finish so we have a higher likely hood of being at a debugger prompt
            await this.evaluateRequestPromise;
            if (this.rokuAdapter?.isAtDebuggerPrompt !== true) {
                logger.log('Skipped getting variables because the RokuAdapter is not accepting input at this time');
                response.success = false;
                response.message = 'Debug session is not paused';
                return this.sendResponse(response);
            }

            //find the variable with this reference
            let v = this.variables[args.variablesReference];
            if (!v) {
                response.success = false;
                response.message = `Variable reference has expired`;
                return this.sendResponse(response);
            }
            logger.log('variable', v);

            // Populate scope level values if needed
            if (v.isScope) {
                await this.populateScopeVariables(v, args);
            }

            //query for child vars if we haven't done it yet or DAP is asking to resolve a lazy variable
            if (v.childVariables.length === 0 || v.isResolved) {
                let tempVar: AugmentedVariable;
                if (!v.isResolved) {
                    // Evaluate the variable
                    try {
                        let { evalArgs } = await this.evaluateExpressionToTempVar({ expression: v.evaluateName, frameId: v.frameId }, util.getVariablePath(v.evaluateName));
                        let result = await this.rokuAdapter.getVariable(evalArgs.expression, v.frameId);
                        tempVar = await this.getVariableFromResult(result, v.frameId);
                        tempVar.frameId = v.frameId;
                        // Determine if the variable has changed
                        sendInvalidatedEvent = v.type !== tempVar.type || v.indexedVariables !== tempVar.indexedVariables;
                    } catch (error) {
                        logger.error('Error getting variables', error);
                        tempVar = new Variable('Error', `❌ Error: ${error.message}`);
                        tempVar.type = '';
                        tempVar.childVariables = [];
                        sendInvalidatedEvent = true;
                        response.success = false;
                        response.message = error.message;
                    }

                    // Merge the resulting updates together
                    v.childVariables = tempVar.childVariables;
                    v.value = tempVar.value;
                    v.type = tempVar.type;
                    v.indexedVariables = tempVar.indexedVariables;
                    v.namedVariables = tempVar.namedVariables;
                }
                frameId = v.frameId;

                if (v?.presentationHint?.lazy || v.isResolved) {
                    // If this was a lazy variable we need to respond with the updated variable and not the children
                    if (v.isResolved && v.childVariables.length > 0) {
                        updatedVariables = v.childVariables;
                    } else {
                        updatedVariables = [v];
                    }
                    v.isResolved = true;
                } else {
                    updatedVariables = v.childVariables;
                }

                // If the variable has no children, set the reference to 0
                // so it does not look expandable in the Ui
                if (v.childVariables.length === 0) {
                    v.variablesReference = 0;
                }

                // If the variable was resolve in the past we may not have fetched a new temp var
                tempVar ??= v;
                if (v?.presentationHint) {
                    v.presentationHint.lazy = tempVar.presentationHint?.lazy;
                } else {
                    v.presentationHint = tempVar.presentationHint;
                }

            } else {
                updatedVariables = v.childVariables;
            }

            // Only send the updated variables if we are not going to trigger an invalidated event.
            // This is to prevent the UI from updating twice and makes the experience much smoother to the end user.
            response.body = {
                variables: this.filterVariablesUpdates(updatedVariables, args, this.variables[args.variablesReference])
                // TODO: Re-enable this when we can send the correct variables based on the initial inspect context
                // variables: sendInvalidatedEvent ? [] : this.filterVariablesUpdates(updatedVariables, args, this.variables[args.variablesReference])
            };
        } catch (error) {
            logger.error('Error during variablesRequest', error, { args });
            response.success = false;
            response.message = error?.message ?? 'Error during variablesRequest';
        } finally {
            logger.info('end', { response });
        }
        this.sendResponse(response);
        if (sendInvalidatedEvent) {
            this.debounceSendInvalidatedEvent(null, frameId);
        }
    }

    private debounceSendInvalidatedEvent = debounce((threadId: number, frameId: number) => {
        this.sendInvalidatedEvent(threadId, frameId);
    }, 50);


    private filterVariablesUpdates(updatedVariables: Array<AugmentedVariable>, args: DebugProtocol.VariablesArguments, v: DebugProtocol.Variable): Array<AugmentedVariable> {
        if (!updatedVariables || !v) {
            return [];
        }

        let start = args.start ?? 0;

        //if the variable is an array, send only the requested range
        if (Array.isArray(updatedVariables) && args.filter === 'indexed') {
            //only send the variable range requested by the debugger
            if (!args.count) {
                updatedVariables = updatedVariables.slice(0, v.indexedVariables);
            } else {
                updatedVariables = updatedVariables.slice(start, start + args.count);
            }
        }

        if (Array.isArray(updatedVariables) && args.filter === 'named') {
            // We currently do not support named variable paging so we always send all named variables
            updatedVariables = updatedVariables.slice(v.indexedVariables);
        }

        let filteredUpdatedVariables = this.launchConfiguration.showHiddenVariables !== true ? updatedVariables.filter(
            (child: AugmentedVariable) => !child.name.startsWith(this.tempVarPrefix)) : updatedVariables;

        if (this.launchConfiguration.showHiddenVariables !== true) {
            filteredUpdatedVariables = filteredUpdatedVariables.filter((child: AugmentedVariable) => {
                //A transient variable that we show when there is a value
                if (child.name === '__brs_err__' && child.type !== VariableType.Uninitialized) {
                    return true;
                } else if (util.isTransientVariable(child.name)) {
                    return false;
                } else {
                    return true;
                }
            });
        }

        return filteredUpdatedVariables;
    }

    /**
     * Takes a scope variable and populates its child variables based on the scope type and the current adapter type.
     * @param v scope variable to populate
     * @param args
     */
    private async populateScopeVariables(v: AugmentedVariable, args: DebugProtocol.VariablesArguments) {
        if (v.childVariables.length > 0) {
            // Already populated
            return;
        }

        let tempVar: AugmentedVariable;
        try {
            if (v.type === '$$Locals') {
                if (this.rokuAdapter.isDebugProtocolAdapter()) {
                    let result = await this.rokuAdapter.getLocalVariables(v.frameId);
                    tempVar = await this.getVariableFromResult(result, v.frameId);
                } else if (this.rokuAdapter.isTelnetAdapter()) {
                    // NOTE: Legacy telnet support
                    let variables: AugmentedVariable[] = [];
                    const varNames = await this.rokuAdapter.getScopeVariables();

                    // Fetch each variable individually
                    for (const varName of varNames) {
                        let { evalArgs } = await this.evaluateExpressionToTempVar({ expression: varName, frameId: -1 }, util.getVariablePath(varName));
                        let result = await this.rokuAdapter.getVariable(evalArgs.expression, -1);
                        let tempLocalsVar = await this.getVariableFromResult(result, -1);
                        variables.push(tempLocalsVar);
                    }
                    tempVar = {
                        ...v,
                        childVariables: variables,
                        namedVariables: variables.length,
                        indexedVariables: 0
                    };
                }

                // Merge the resulting updates together onto the original variable
                v.childVariables = tempVar.childVariables;
                v.namedVariables = tempVar.namedVariables;
                v.indexedVariables = tempVar.indexedVariables;
            } else if (v.type === '$$Registry') {
                // This is a special scope variable used to load registry data via an ECP call
                // Send the registry ECP call for the `dev` app as side loaded apps are always `dev`
                await populateVariableFromRegistryEcp({ remotePort: this.launchConfiguration.remotePort, device: this.launchConfiguration.device, appId: 'dev' }, v, this.variables, this.getEvaluateRefId.bind(this));
            }
        } catch (error) {
            logger.error(`Error getting variables for scope ${v.type}`, error);
            tempVar = {
                name: '',
                value: `❌ Error: ${error.message}`,
                variablesReference: 0,
                childVariables: []
            };
            v.childVariables = [tempVar];
            v.namedVariables = 1;
            v.indexedVariables = 0;
        }

        // Mark the scope as resolved so we don't re-fetch the variables
        v.isResolved = true;

        // If the scope has no children, add a single child to indicate there are no values
        if (v.childVariables.length === 0) {
            tempVar = {
                name: '',
                value: `No values for scope '${v.name}'`,
                variablesReference: 0,
                childVariables: []
            };
            v.childVariables = [tempVar];
            v.namedVariables = 1;
            v.indexedVariables = 0;
        }
    }

    private evaluateRequestPromise = Promise.resolve();
    private evaluateVarIndexByFrameId = new Map<number, number>();

    private getNextVarIndex(frameId: number): number {
        if (!this.evaluateVarIndexByFrameId.has(frameId)) {
            this.evaluateVarIndexByFrameId.set(frameId, 0);
        }
        let value = this.evaluateVarIndexByFrameId.get(frameId);
        this.evaluateVarIndexByFrameId.set(frameId, value + 1);
        return value;
    }

    public async evaluateRequest(response: DebugProtocol.EvaluateResponse, args: DebugProtocol.EvaluateArguments) {
        //ensure the rokuAdapter is loaded
        await this.getRokuAdapter();

        let deferred = defer<void>();
        if (args.context === 'repl' && this.rokuAdapter.isTelnetAdapter() && args.expression.trim().startsWith('>')) {
            this.clearState();
            this.rokuAdapter.clearCache();
            const expression = args.expression.replace(/^\s*>\s*/, '');
            this.logger.log('Sending raw telnet command...I sure hope you know what you\'re doing', { expression });
            this.rokuAdapter.requestPipeline.client.write(`${expression}\r\n`);
            this.sendResponse(response);
            return deferred.promise;
        }

        try {
            this.evaluateRequestPromise = this.evaluateRequestPromise.then(() => {
                return deferred.promise;
            });

            //fix vscode hover bug that excludes closing quotemark sometimes.
            if (args.context === 'hover') {
                args.expression = util.ensureClosingQuote(args.expression);
            }

            if (!this.rokuAdapter.isAtDebuggerPrompt) {
                let message = 'Skipped evaluate request because RokuAdapter is not accepting requests at this time';
                if (args.context === 'repl') {
                    this.sendEvent(new OutputEvent(message, 'stderr'));
                    response.body = {
                        result: 'invalid',
                        variablesReference: 0
                    };
                } else {
                    throw new Error(message);
                }

                //is at debugger prompt
            } else if (args.expression.trim()) {
                // We trim and check that the expression is not an empty string so that we do not send empty expressions to the Roku
                // This happens mostly when hovering over leading whitespace in the editor

                let { evalArgs, variablePath } = await this.evaluateExpressionToTempVar(args, util.getVariablePath(args.expression));

                //if we found a variable path (e.g. ['a', 'b', 'c']) then do a variable lookup because it's faster and more widely supported than `evaluate`
                if (variablePath) {
                    let refId = this.getEvaluateRefId(evalArgs.expression, evalArgs.frameId);
                    let v: AugmentedVariable;
                    //if we already looked this item up, return it
                    if (this.variables[refId]) {
                        v = this.variables[refId];
                    } else {
                        let result = await this.rokuAdapter.getVariable(evalArgs.expression, evalArgs.frameId);
                        if (!result) {
                            throw new Error('Error: unable to evaluate expression');
                        }

                        v = await this.getVariableFromResult(result, evalArgs.frameId);
                        //TODO - testing something, remove later
                        // eslint-disable-next-line camelcase
                        v.request_seq = response.request_seq;
                        v.frameId = evalArgs.frameId;
                    }
                    response.body = {
                        result: v.value,
                        type: v.type,
                        variablesReference: v.variablesReference,
                        namedVariables: v.namedVariables || 0,
                        indexedVariables: v.indexedVariables || 0
                    };

                    //run an `evaluate` call
                } else {
                    let commandResults = await this.rokuAdapter.evaluate(evalArgs.expression, evalArgs.frameId);

                    commandResults.message = util.trimDebugPrompt(commandResults.message);
                    if (args.context === 'repl') {
                        // Clear variable cache since this action could have side-effects
                        // Only do this for REPL requests as hovers and watches should not clear the cache
                        this.clearState();
                        this.sendInvalidatedEvent(null, evalArgs.frameId);
                    }

                    // If the adapter captured output (probably only telnet), log the results
                    if (typeof commandResults.message === 'string') {
                        this.logger.debug('evaluateRequest', { commandResults });
                        if (args.context === 'repl') {
                            // If the command was a repl command, send the output to the debug console for the developer as well
                            // We limit this to repl only so you don't get extra logs when hovering over variables ro running watches
                            this.sendEvent(new OutputEvent(commandResults.message, commandResults.type === 'error' ? 'stderr' : 'stdio'));
                        }
                    }

                    if (this.enableDebugProtocol || (typeof commandResults.message !== 'string')) {
                        response.body = {
                            result: 'invalid',
                            variablesReference: 0
                        };
                    } else {
                        response.body = {
                            result: commandResults.message === '\r\n' ? 'invalid' : commandResults.message,
                            variablesReference: 0
                        };
                    }
                }
            }
        } catch (error) {
            this.logger.error('Error during variables request', error);
            response.success = false;
            response.message = error?.message ?? error;
        }
        try {
            this.sendResponse(response);
        } catch { }
        deferred.resolve();
    }

    private async evaluateExpressionToTempVar(args: DebugProtocol.EvaluateArguments, variablePath: string[]): Promise<{ evalArgs: DebugProtocol.EvaluateArguments; variablePath: string[] }> {
        let returnVal = { evalArgs: args, variablePath };
        if (!variablePath && util.isAssignableExpression(args.expression)) {
            let varIndex = this.getNextVarIndex(args.frameId);
            let arrayVarName = this.tempVarPrefix + 'eval';
            let command = '';
            if (varIndex === 0) {
                await this.rokuAdapter.evaluate(`if type(${arrayVarName}) = "<uninitialized>" then ${arrayVarName} = []\n`, args.frameId);
            }
            let statement = `${arrayVarName}[${varIndex}] = ${args.expression}`;
            returnVal.evalArgs.expression = `${arrayVarName}[${varIndex}]`;
            command += statement;
            let commandResults = await this.rokuAdapter.evaluate(command, args.frameId);
            if (commandResults.type === 'error') {
                throw new Error(commandResults.message);
            }
            returnVal.variablePath = [arrayVarName, varIndex.toString()];
        }
        return returnVal;
    }

    private async bulkEvaluateExpressionToTempVar(frameId: number, argsArray: Array<DebugProtocol.EvaluateArguments>, variablePathArray: Array<string[]>): Promise<{ evaluations: Array<{ evalArgs: DebugProtocol.EvaluateArguments; variablePath: string[] }>; bulkVarName: string }> {
        let results = {
            evaluations: [],
            bulkVarName: ''
        };
        let storedVariables = [];
        let command = '';
        for (let i = 0; i < argsArray.length; i++) {
            let args = argsArray[i];
            let variablePath = variablePathArray[i];
            let returnVal = { evalArgs: args, variablePath };
            if (!variablePath && util.isAssignableExpression(args.expression)) {
                let varIndex = this.getNextVarIndex(frameId);
                let arrayVarName = this.tempVarPrefix + 'eval';
                if (varIndex === 0) {
                    command += `if type(${arrayVarName}) = "<uninitialized>" then ${arrayVarName} = []\n`;
                }
                let statement = `${arrayVarName}[${varIndex}] = ${args.expression}\n`;
                returnVal.evalArgs.expression = `${arrayVarName}[${varIndex}]`;
                command += statement;

                storedVariables.push(`${arrayVarName}[${varIndex}]`);
                returnVal.variablePath = [arrayVarName, varIndex.toString()];
            }

            results.evaluations[i] = returnVal;
        }

        if (command) {

            // create a bulk container for the command results
            let varIndex = this.getNextVarIndex(frameId);
            let arrayVarName = this.tempVarPrefix + 'eval';
            let bulkContainerStatement = `${arrayVarName}[${varIndex}] = [\n`;
            for (let storedVariable of storedVariables) {
                bulkContainerStatement += `${storedVariable},\n`;
            }
            bulkContainerStatement += `]`;

            command += bulkContainerStatement;

            results.bulkVarName = `${arrayVarName}[${varIndex}]`;

            let commandResults = await this.rokuAdapter.evaluate(command, frameId);
            if (commandResults.type === 'error') {
                throw new Error(commandResults.message);
            }
        }

        return results;
    }

    protected async completionsRequest(response: DebugProtocol.CompletionsResponse, args: DebugProtocol.CompletionsArguments, request?: DebugProtocol.Request) {
        this.logger.log('completionsRequest', args, request);
        // this.sendEvent(new LogOutputEvent(`completionsRequest: ${args.text}`));
        // this.sendEvent(new OutputEvent(`completionsRequest: ${args.text}\n`, 'stderr'));

        try {
            let supplyLocalScopeCompletions = false;

            let closestCompletionDetails = this.getClosestCompletionDetails(args);

            if (!closestCompletionDetails) {
                // If the cursor is not at the end of the line, then we should not supply completions at this time
                response.body = {
                    targets: []
                };
                return this.sendResponse(response);
            }
            let completions = new Map<string, DebugProtocol.CompletionItem>();

            let parentVariablePath = closestCompletionDetails.parentVariablePath;
            // When set, the user is typing a string key (ex: `m["fo`) and completions should insert the
            // key wrapped to close the access (ex: `firstName"]`) rather than appending a bare label. The
            // value is the closing text to append (empty when a closing bracket is already present).
            const stringKeyClosing = closestCompletionDetails.stringKeyClosing;

            // The span of input each completion replaces. The client requests completions once (at the first
            // character) and then filters the list as the user keeps typing, so without an explicit range that
            // incremental filtering is anchored incorrectly.
            const replaceRange = this.getCompletionReplaceRange(args);
            // Whether the character immediately before the replaced span is a `.` (ie. the user is doing dot
            // member access). A key that can't be dot-accessed (ex: `my key`) is rewritten as bracket access,
            // which has to consume that `.` so `m.` becomes `m["my key"]` rather than `m.["my key"]`.
            const lines = args.text.split('\n');
            const targetLine = lines[this.toDebuggerLine(args.line, 0)] ?? '';
            const precededByDot = targetLine[replaceRange.start - 1] === '.';

            // Get the completions if the variable path was valid
            if (parentVariablePath) {

                // If the parent variable path is an empty string, then we are looking up the local scope variables and global functions
                if (parentVariablePath.length === 1 && parentVariablePath[0] === '') {
                    supplyLocalScopeCompletions = true;
                }

                // Look up the parent variable (in-memory first, then the device), scoped to the current frame.
                let parentVariable = await this.resolveCompletionParentVariable(parentVariablePath, args.frameId);

                // provide completions for the parent variable if one was found
                if (parentVariable) {
                    // arrays and lists are integer-indexed; their `[N]` elements aren't valid `.` or `["..."]`
                    // completions (you can't write `arr.[0]` or `arr["0"]`), so don't offer them as members.
                    // Only the interface methods below (Count, Push, ...) apply to these containers.
                    const isIntegerIndexed = parentVariable.type === VariableType.Array ||
                        parentVariable.type === VariableType.List ||
                        parentVariable.type === 'roXMLList' ||
                        parentVariable.type === 'roByteArray';

                    const possibleFieldsAndMethods = isIntegerIndexed
                        ? []
                        // Filter out virtual variables and the empty-named placeholder used for empty scopes
                        : parentVariable.childVariables.filter((child) => child.name && child.presentationHint?.kind !== 'virtual');

                    for (let v of possibleFieldsAndMethods) {
                        // Default completion type should be variable
                        let completionType: DebugProtocol.CompletionItemType = 'variable';
                        if (!supplyLocalScopeCompletions) {
                            // We are not supplying local scope completions, so we need to determine the completion type relative to the parent variable
                            if (parentVariable.type === 'roSGNode' || parentVariable.type === VariableType.AssociativeArray || parentVariable.type === VariableType.Object) {
                                completionType = 'field';
                            }

                            switch (v.type) {
                                case VariableType.Function:
                                case VariableType.Subroutine:
                                    completionType = 'method';
                                    break;
                                default:
                                    break;
                            }
                        }

                        const completionItem: DebugProtocol.CompletionItem = {
                            label: v.name,
                            type: completionType,
                            //rank a variable's own members/locals above everything else
                            sortText: `${CompletionSortTier.Member}${v.name}`
                        };
                        if (stringKeyClosing !== undefined) {
                            // Insert the key and close the access, ex: `firstName"]` (the replacement range is applied
                            // below). A `"` inside the key is escaped as `""` so the inserted string literal stays valid
                            // (ex: a key of `a"b` is inserted as `a""b`).
                            completionItem.text = `${v.name.replace(/"/g, '""')}${stringKeyClosing}`;
                        } else if (!supplyLocalScopeCompletions && precededByDot && !/^[a-z_][a-z0-9_]*$/i.test(v.name)) {
                            // The key can't be dot-accessed (ex: it has a space or a quote), so rewrite the access as
                            // bracket notation and consume the `.` before the cursor: `m.` -> `m["my key"]`. A `"` in
                            // the key is escaped as `""` so the inserted string literal stays valid.
                            completionItem.text = `["${v.name.replace(/"/g, '""')}"]`;
                            completionItem.start = replaceRange.start - 1;
                            completionItem.length = replaceRange.length + 1;
                        }
                        completions.set(`${completionType}-${v.name}`, completionItem);
                    }

                    // Interface methods aren't valid string keys, so skip them when completing a string key
                    if (stringKeyClosing === undefined) {
                        let parentComponentType = this.debuggerVarTypeToRoType(parentVariable.type).toLowerCase();
                        //assemble a list of all methods on the parent component
                        const methods = [
                            //if the parent variable is an actual interface (if applicable) Ex: `ifString` or `ifArray`
                            ...interfaces[parentComponentType as 'ifappinfo']?.methods ?? [],
                            //interfaces from component of this name (if applicable) Ex: `roSGNode` or `roDateTime`
                            ...components[parentComponentType as 'roappinfo']?.interfaces.map((i) => interfaces[i.name.toLowerCase() as 'ifappinfo']?.methods) ?? [],
                            // Add parent event function completions (if applicable) Ex: `roSGNodeEvent` or `roDeviceInfoEvent`
                            ...events[parentComponentType as 'roappmemorymonitorevent']?.methods ?? []
                        ].flat();

                        // Based on the results of interface, component, and event looks up, add all the methods to the completions
                        for (const method of methods) {
                            completions.set(`method-${method.name}`, {
                                label: method.name,
                                type: 'method',
                                detail: method.description ?? '',
                                sortText: `${CompletionSortTier.Method}${method.name}`
                            });
                        }
                    }

                    // Add the global functions to the completions results
                    if (supplyLocalScopeCompletions) {
                        for (let globalCallable of globalCallables) {
                            completions.set(`function-${globalCallable.name.toLocaleLowerCase()}`, {
                                label: globalCallable.name,
                                type: 'function',
                                detail: globalCallable.shortDescription ?? globalCallable.documentation ?? '',
                                sortText: `${CompletionSortTier.Global}${globalCallable.name}`
                            });
                        }

                        const frame = this.rokuAdapter.getStackFrameById(args.frameId);

                        try {
                            let scopeFunctions = await this.projectManager.getScopeFunctionsForFile(frame.filePath as string);
                            for (let scopeFunction of scopeFunctions) {
                                if (!completions.has(`${scopeFunction.completionItemKind}-${scopeFunction.name.toLocaleLowerCase()}`)) {
                                    completions.set(`${scopeFunction.completionItemKind}-${scopeFunction.name.toLocaleLowerCase()}`, {
                                        label: scopeFunction.name,
                                        type: scopeFunction.completionItemKind,
                                        sortText: `${CompletionSortTier.ScopeFunction}${scopeFunction.name}`
                                    });
                                }
                            }
                        } catch (e) {
                            this.logger.warn('Could not build list of scope functions for file', e);
                        }
                    }
                }
            }

            // Apply the default replacement span to every completion that didn't already set its own (bracket
            // rewrites above use an extended range that also consumes the preceding `.`).
            for (const target of completions.values()) {
                if (target.start === undefined) {
                    target.start = replaceRange.start;
                    target.length = replaceRange.length;
                }
            }

            response.body = {
                targets: [...completions.values()]
            };
        } catch (error) {
            // this.sendEvent(new LogOutputEvent(`text: ${args.text} | ${error}`));
            // this.sendEvent(new OutputEvent(`text: ${args.text} | ${error}\n`, 'stderr'));
            this.logger.error('Error during completionsRequest', error, { args });
        }
        this.sendResponse(response);
    }

    /**
     * Gets the closest completion details the incoming completion request.
     */
    private getClosestCompletionDetails(args: DebugProtocol.CompletionsArguments): { parentVariablePath: string[]; stringKeyClosing?: string } {
        const incomingText = args.text;
        const lines = incomingText.split('\n');
        let lineNumber = this.toDebuggerLine(args.line, 0);
        let column = this.toDebuggerColumn(args.column);

        const targetLine = lines[lineNumber] ?? '';

        const cursorIndex = column - 1;
        const variableChars = /[a-z0-9_\.]/i;

        // If the character immediately to the right of the cursor is a variable character, then we are
        // in the middle of a token and should not supply completions yet.
        if (cursorIndex + 1 < targetLine.length && variableChars.test(targetLine[cursorIndex + 1])) {
            return undefined;
        }

        // Determine where the expression we want to complete ends, and whether we are completing the
        // members of that expression. A trailing `.` or being inside an unclosed string-key bracket
        // (ex: `m["fo`) are both treated as member access on the parent expression.
        let endColumn = column;
        let isMemberAccess = false;
        //when set (including ''), the user is completing a string key; the value is the text to append to
        //close the access (ex: `"]`), empty when a closing bracket is already present
        let stringKeyClosing: string;

        const openBracket = this.findUnclosedOpener(targetLine, column);
        if (openBracket?.char === '[') {
            // find the opening quote (skipping any whitespace after the `[`)
            let quoteIndex = openBracket.index + 1;
            while (targetLine[quoteIndex] === ' ' || targetLine[quoteIndex] === '\t') {
                quoteIndex++;
            }
            const quote = targetLine[quoteIndex];
            if (quote === '"' || quote === `'`) {
                // The user is typing a string key, so complete the keys of the expression before the `[`
                endColumn = openBracket.index;
                isMemberAccess = true;
                // close the string and bracket only when there is nothing meaningful after the cursor
                stringKeyClosing = targetLine.slice(column).trim() === '' ? `${quote}]` : '';
            }
        }

        // Walk backwards from `endColumn` to find the start of the variable path, stepping over balanced
        // `[...]` index access so paths like `arr[0].name` are captured as a whole.
        let startIndex = endColumn - 1;
        let bracketDepth = 0;
        while (startIndex >= 0) {
            const char = targetLine[startIndex];
            if (char === ']') {
                bracketDepth++;
            } else if (char === '[') {
                if (bracketDepth === 0) {
                    // An unbalanced `[` means we hit the start of an index/key being typed; stop here.
                    break;
                }
                bracketDepth--;
            } else if (bracketDepth === 0 && (char === undefined || !variableChars.test(char))) {
                break;
            }
            startIndex--;
        }

        const variablePathString = targetLine.slice(startIndex + 1, endColumn);

        // Attempted dot access on something unexpected.
        // Example: `getPerson().name` where `getPerson()` is not a valid variable path,
        // which leaves `.name` as the variable path string.
        if (variablePathString.startsWith('.')) {
            return undefined;
        }

        if (variablePathString.endsWith('.')) {
            isMemberAccess = true;
        }

        // Get the variable path from the text
        let variablePath: string[];
        if (!variablePathString.trim()) {
            // The text was empty so assume via '' that we are looking up the local scope variables and global functions
            variablePath = [''];
        } else if (variablePathString.endsWith('.')) {
            // supplied text ends with a period, so strip it off to create a valid variable path
            variablePath = util.getVariablePath(variablePathString.slice(0, -1));
        } else {
            variablePath = util.getVariablePath(variablePathString);
        }

        // the target string is not a valid variable path
        if (!variablePath) {
            return undefined;
        }

        // For member access we complete the members of the full expression. Otherwise we complete the
        // siblings of the final (partial) segment, so drop it to get the parent.
        let parentVariablePath = isMemberAccess ? variablePath : variablePath.slice(0, variablePath.length - 1);

        // An empty parent path means we are looking up the local scope variables and global functions
        if (parentVariablePath.length === 0) {
            parentVariablePath = [''];
        }

        const result: { parentVariablePath: string[]; stringKeyClosing?: string } = { parentVariablePath: parentVariablePath };
        // Only attach the string-key context when we actually resolved a parent object to complete keys on
        if (stringKeyClosing !== undefined && !(parentVariablePath.length === 1 && parentVariablePath[0] === '')) {
            result.stringKeyClosing = stringKeyClosing;
        }
        return result;
    }

    /**
     * Compute the span of input text that a completion replaces: the run of identifier characters
     * immediately before the cursor. This lets the client filter the list correctly as the user keeps
     * typing past the first character.
     *
     * `start` is a 0-based offset into the line, NOT a client column. Per the Debug Adapter Protocol,
     * `CompletionItem.start` is measured in UTF-16 code units and the client maps it to a position
     * itself, so it must not be run through `toClientColumn` (unlike stack-frame, breakpoint, and scope
     * positions). Our debugger column base is already 0-based, so the internal offset is sent as-is.
     */
    private getCompletionReplaceRange(args: DebugProtocol.CompletionsArguments): { start: number; length: number } {
        const lines = args.text.split('\n');
        const lineNumber = this.toDebuggerLine(args.line, 0);
        const cursorOffset = this.toDebuggerColumn(args.column);
        const targetLine = lines[lineNumber] ?? '';

        const identifierChars = /[a-z0-9_]/i;
        let wordStart = cursorOffset;
        while (wordStart > 0 && identifierChars.test(targetLine[wordStart - 1])) {
            wordStart--;
        }
        return {
            start: wordStart,
            length: cursorOffset - wordStart
        };
    }

    /**
     * Scan backwards from `column` to find the nearest opening bracket (`(`, `[`, or `{`) that has not
     * been closed before the cursor. Returns the opener's index and character, or undefined if none.
     */
    private findUnclosedOpener(line: string, column: number): { index: number; char: string } {
        let depth = 0;
        for (let i = column - 1; i >= 0; i--) {
            const char = line[i];
            if (char === ')' || char === ']' || char === '}') {
                depth++;
            } else if (char === '(' || char === '[' || char === '{') {
                if (depth === 0) {
                    return { index: i, char: char };
                }
                depth--;
            }
        }
        return undefined;
    }

    /**
     * Resolve the parent variable for a completion request. Prefers the in-memory locals for the frame,
     * then falls back to a device lookup. Device lookups are cached for the duration of the paused state
     * (cleared by `clearState`) so repeated completion requests on the same path don't hammer the device.
     */
    private async resolveCompletionParentVariable(parentVariablePath: string[], frameId: number): Promise<AugmentedVariable> {
        // For local-scope completions, make sure the frame's locals are fetched on demand. Otherwise they
        // would only appear once the user expands the Variables panel (which is what triggers the fetch).
        const isLocalScope = parentVariablePath.length === 1 && parentVariablePath[0] === '';
        if (isLocalScope) {
            const localsScope = this.getOrCreateLocalsScope(frameId);
            if (!localsScope.isResolved) {
                try {
                    await this.populateScopeVariables(localsScope, { variablesReference: localsScope.variablesReference } as DebugProtocol.VariablesArguments);
                } catch (error) {
                    this.logger.debug('Could not populate locals for completions', error, { frameId });
                }
            }
        }

        const inMemory = this.findFrameVariableByPath(parentVariablePath, frameId);
        if (inMemory && inMemory.childVariables.length > 0) {
            return inMemory;
        }

        // Rebuild a valid accessor expression for the device lookup. Joining with `.` is wrong for indexed
        // segments (ex: `m.services[0]` would become the invalid `m.services.0` and the index gets dropped).
        const expression = this.buildVariableExpression(parentVariablePath);

        const cacheKey = `${frameId}:${expression}`;
        if (this.completionParentVariableCache.has(cacheKey)) {
            return this.completionParentVariableCache.get(cacheKey);
        }

        let parentVariable: AugmentedVariable;
        try {
            let { evalArgs } = await this.evaluateExpressionToTempVar({ expression: expression, frameId: frameId }, parentVariablePath);
            let result = await this.rokuAdapter.getVariable(evalArgs.expression, frameId);
            parentVariable = await this.getVariableFromResult(result, frameId);
        } catch (error) {
            // A failed lookup is expected while the user is still typing an incomplete expression, so keep it quiet.
            this.logger.debug('Could not resolve parent variable for completions', error, { parentVariablePath });
            parentVariable = undefined;
        }

        this.completionParentVariableCache.set(cacheKey, parentVariable);
        return parentVariable;
    }

    /**
     * Rebuild a valid BrightScript accessor expression from a resolved variable path. String-literal keys
     * arrive already quoted from `getVariablePath` and are emitted as `["key"]` so they stay case-sensitive
     * on the device (Roku AAs can be set case-sensitive); numeric segments use `[index]`, and identifiers
     * use dot access. This keeps array indices and string keys correct through the device lookup.
     */
    private buildVariableExpression(segments: string[]): string {
        return segments.reduce((expression, segment, index) => {
            if (index === 0) {
                return segment;
            }
            //already-quoted string key (preserve the quotes so the device matches it case-sensitively).
            //A lone `"` is not a quoted literal (the shortest is `""`), so require at least 2 chars.
            if (segment.length >= 2 && segment.startsWith('"') && segment.endsWith('"')) {
                return `${expression}[${segment}]`;
            }
            if (/^[0-9]+$/.test(segment)) {
                return `${expression}[${segment}]`;
            }
            if (/^[a-z_][a-z0-9_]*$/i.test(segment)) {
                return `${expression}.${segment}`;
            }
            return `${expression}["${segment.replace(/"/g, '""')}"]`;
        }, '');
    }

    /**
     * Normalize a variable path segment or variable name for matching: drop surrounding string-key quotes
     * and lower-case it. BrightScript variables and dotted access are case-insensitive, and the device
     * reports names lower-cased, so this lets the in-memory lookup find the parent regardless of the casing
     * the user typed (ex: `topRef` matching the cached `topref`).
     */
    private normalizeVariableName(name: string): string {
        let value = name ?? '';
        if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
            value = value.slice(1, -1).replace(/""/g, '"');
        }
        return value.toLowerCase();
    }

    /**
     * Resolve a variable path against the current frame's local scope. The first path segment is matched
     * against the frame's locals (not the global pool of every materialized variable), then we walk down
     * the child variables. The empty path (`['']`) resolves to the locals scope container itself.
     */
    private findFrameVariableByPath(path: string[], frameId: number): AugmentedVariable {
        const localsContainer = this.variables[this.getEvaluateRefId('$$locals', frameId)];
        if (path.length === 1 && path[0] === '') {
            return localsContainer;
        }
        return this.findVariableByPath(localsContainer?.childVariables ?? [], path, frameId);
    }

    private findVariableByPath(variables: AugmentedVariable[], path: string[], frameId: number) {
        let current: AugmentedVariable = null;
        for (const name of path) {
            const normalizedName = this.normalizeVariableName(name);
            // Find the object matching the current name in the data (case-insensitive, per BrightScript)
            current = (Array.isArray(variables) ? variables : current?.childVariables)?.find(obj => {
                return this.normalizeVariableName(obj.name) === normalizedName && obj.frameId === frameId;
            });

            // If no match is found, return null
            if (!current) {
                return null;
            }

            // Move to the children for the next iteration
            variables = current.childVariables;
        }
        return current;
    }

    private debuggerVarTypeToRoType(type: string): string {
        switch (type) {
            case VariableType.Function:
            case VariableType.Subroutine:
                return 'roFunction';
            case VariableType.AssociativeArray:
                return 'roAssociativeArray';
            case VariableType.List:
                return 'roList';
            case VariableType.Array:
                return 'roArray';
            case VariableType.Boolean:
                return 'roBoolean';
            case VariableType.Double:
                return 'roDouble';
            case VariableType.Float:
                return 'roFloat';
            case VariableType.Integer:
                return 'roInteger';
            case VariableType.LongInteger:
                return 'roLongInteger';
            case VariableType.String:
                return 'roString';
            default:
                return type;
        }
    }

    /**
     * Called when the host stops debugging
     * @param response
     * @param args
     */
    protected async disconnectRequest(response: DebugProtocol.DisconnectResponse, args: DebugProtocol.DisconnectArguments, request?: DebugProtocol.Request) {
        //return to the home screen — best effort. The device may already be powered off or unreachable
        //at disconnect time; without a guard the home key press rejects (EHOSTDOWN / ECONNREFUSED / etc)
        //and because @vscode/debugadapter dispatches this method without awaiting the returned Promise,
        //that rejection escapes as an unhandledRejection and crashes the DAP process.
        //See https://github.com/rokucommunity/vscode-brightscript-language/issues/807
        //    https://github.com/rokucommunity/roku-debug/issues/332
        if (!this.enableDebugProtocol) {
            try {
                await this.rokuDeploy.keyPress({ device: this.launchConfiguration.device, key: 'Home', ecpPort: this.launchConfiguration.remotePort });
            } catch (e) {
                this.logger.warn('Failed to press home button during disconnect; device may be unreachable', e);
            }
        }
        this.sendResponse(response);
        await this.shutdown();
    }

    private createRokuAdapter(rendezvousTracker: RendezvousTracker) {
        if (this.enableDebugProtocol) {
            this.rokuAdapter = new DebugProtocolAdapter(this.launchConfiguration, this.projectManager, this.breakpointManager, rendezvousTracker, this.deviceInfo);
        } else {
            this.rokuAdapter = new TelnetAdapter(this.launchConfiguration, rendezvousTracker);
        }
    }

    protected async restartRequest(response: DebugProtocol.RestartResponse, args: DebugProtocol.RestartArguments, request?: DebugProtocol.Request) {
        this.logger.log('[restartRequest] begin');
        if (this.rokuAdapter) {
            if (!this.enableDebugProtocol) {
                this.rokuAdapter.removeAllListeners();
            }
            await this.rokuAdapter.destroy();
            await this.ensureAppIsInactive();
            this.rokuAdapterDeferred = defer();
            this.stagingDefered.tryResolve();
            this.stagingDefered = defer();
        }
        await this.launchRequest(response, args.arguments as LaunchConfiguration);
    }

    private exitAppTimeout = 5000;
    private async ensureAppIsInactive() {
        const startTime = Date.now();

        while (true) {
            if (Date.now() - startTime > this.exitAppTimeout) {
                return;
            }

            try {
                let appStateResult = await rokuECP.getAppState({
                    remotePort: this.launchConfiguration.remotePort,
                    device: this.launchConfiguration.device,
                    appId: 'dev',
                    requestOptions: { timeout: 300 }
                });

                const state = appStateResult.state;

                if (state === AppState.active || state === AppState.background) {
                    // Suspends or terminates an app that is running:
                    // If the app supports Instant Resume and is running in the foreground, sending this command suspends the app (the app runs in the background).
                    // If the app supports Instant Resume and is running in the background or the app does not support Instant Resume and is running, sending this command terminates the app.
                    // This means that we might need to send this command twice to terminate the app.
                    await rokuECP.exitApp({
                        remotePort: this.launchConfiguration.remotePort,
                        device: this.launchConfiguration.device,
                        appId: 'dev',
                        requestOptions: { timeout: 300 }
                    });
                } else if (state === AppState.inactive) {
                    return;
                }
            } catch (e) {
                this.logger.error('Error attempting to exit application', e);
            }

            await util.sleep(200);
        }
    }

    /**
     * Used to track whether the entry breakpoint has already been handled
     */
    private entryBreakpointWasHandled = false;

    /**
     * Registers the main events for the RokuAdapter
     */
    private async connectRokuAdapter() {
        this.rokuAdapter.on('start', () => {
            this.sendLaunchProgress('end', 'Complete');
            if (!this.firstRunDeferred.isCompleted) {
                this.firstRunDeferred.resolve();
            }
        });

        this.rokuAdapter.on('launch-status', (message) => {
            this.sendLaunchProgress('update', message);
        });

        //when the debugger suspends (pauses for debugger input)
        // eslint-disable-next-line @typescript-eslint/no-misused-promises
        this.rokuAdapter.on('suspend', async () => {
            await this.onSuspend();
        });

        //anytime the adapter encounters an exception on the roku,
        // eslint-disable-next-line @typescript-eslint/no-misused-promises
        this.rokuAdapter.on('runtime-error', async (exception) => {
            await this.getRokuAdapter();
            const threads = await this.setupSuspendedState();
            let threadId = threads[0]?.threadId;
            this.sendEvent(new StoppedEvent(StoppedEventReason.exception, threadId, exception.message));
        });

        // If the roku says it can't continue, we are no longer able to debug, so kill the debug session
        this.rokuAdapter.on('cannot-continue', () => {
            this.shutdown().catch(e => this.logger.error(e));
        });

        //make the connection
        await this.rokuAdapter.connect();
        this.rokuAdapterDeferred.resolve(this.rokuAdapter);
        return this.rokuAdapter;
    }

    private async onSuspend() {
        const threads = await this.setupSuspendedState();
        const activeThread = threads.find(x => x.isSelected);

        //if !stopOnEntry, and we haven't encountered a suspend yet, THIS is the entry breakpoint. auto-continue
        if (!this.entryBreakpointWasHandled && !this.launchConfiguration.stopOnEntry) {
            this.entryBreakpointWasHandled = true;
            //if there's a user-defined breakpoint at this exact position, it needs to be handled like a regular breakpoint (i.e. suspend). So only auto-continue if there's no breakpoint here
            if (activeThread && !await this.breakpointManager.lineHasBreakpoint(this.projectManager.getAllProjects(), activeThread.filePath, activeThread.lineNumber - 1)) {
                this.logger.info('Encountered entry breakpoint and `stopOnEntry` is disabled. Continuing...');
                return this.rokuAdapter.continue();
            }
        }

        const event: StoppedEvent = new StoppedEvent(
            StoppedEventReason.breakpoint,
            //Not sure why, but sometimes there is no active thread. Just pick thread 0 to prevent the app from totally crashing
            activeThread?.threadId ?? 0,
            '' //exception text
        );
        // Socket debugger will always stop all threads and supports multi thread inspection.
        (event.body as any).allThreadsStopped = this.enableDebugProtocol;
        this.sendEvent(event);
    }

    private async setupSuspendedState() {
        //clear the index for storing evalutated expressions
        this.evaluateVarIndexByFrameId.clear();

        const threads = await this.rokuAdapter.getThreads();

        //TODO remove this once Roku fixes their threads off-by-one line number issues
        //look up the correct line numbers for each thread from the StackTrace
        await Promise.all(
            threads.map(async (thread) => {
                const stackTrace = await this.rokuAdapter.getStackTrace(thread.threadId);
                const stackTraceLineNumber = stackTrace[0]?.lineNumber;
                const stackTraceFilePath = stackTrace[0]?.filePath;
                // Only apply the line correction when we actually have valid data — never clobber
                // thread.filePath with undefined, which would crash getSourceLocation downstream.
                if (stackTraceLineNumber !== undefined && stackTraceLineNumber !== thread.lineNumber) {
                    this.logger.warn(`Thread ${thread.threadId} reported incorrect line (${thread.lineNumber}). Using line from stack trace instead (${stackTraceLineNumber})`, thread, stackTrace);
                    thread.lineNumber = stackTraceLineNumber;
                    thread.filePath = stackTraceFilePath ?? thread.filePath;
                }
            })
        );

        outer: for (const bp of this.breakpointManager.failedDeletions) {
            for (const thread of threads) {
                let sourceLocation = await this.projectManager.getSourceLocation(thread.filePath, thread.lineNumber);
                // This stop was due to a breakpoint that we tried to delete, but couldn't.
                // Now that we are stopped, we can delete it. We won't stop here again unless you re-add the breakpoint. You're welcome.
                if (sourceLocation && (bp.srcPath === sourceLocation.filePath) && (bp.line === sourceLocation.lineNumber)) {
                    this.showPopupMessage(`Stopped at breakpoint that failed to delete. Deleting now, and should not cause future stops.`, 'info').catch((error) => {
                        this.logger.error('Error showing popup message', { error });
                    });
                    this.logger.warn(`Stopped at breakpoint that failed to delete. Deleting now, and should not cause future stops`, bp, thread, sourceLocation);
                    break outer;
                }
            }
        }

        //sync breakpoints
        await this.rokuAdapter?.syncBreakpoints();

        this.logger.info('received "suspend" event from adapter');

        this.clearState();
        return threads;
    }

    private async getVariableFromResult(result: EvaluateContainer, frameId: number, maxDepth = 1) {
        let v: AugmentedVariable;

        if (result) {
            if (this.rokuAdapter.isDebugProtocolAdapter()) {
                let refId = this.getEvaluateRefId(result.evaluateName, frameId);
                if (result.isCustom && !result.presentationHint?.lazy && result.evaluateNow) {
                    try {
                        // We should not wait to resolve this variable later. Fetch, store, and merge the results right away.
                        let { evalArgs } = await this.evaluateExpressionToTempVar({ expression: result.evaluateName, frameId: frameId }, util.getVariablePath(result.evaluateName));
                        let newResult = await this.rokuAdapter.getVariable(evalArgs.expression, frameId);
                        this.mergeEvaluateContainers(result, newResult);
                    } catch (error) {
                        logger.error('Error getting variables', error);
                        this.mergeEvaluateContainers(result, {
                            name: result.name,
                            evaluateName: result.evaluateName,
                            children: [],
                            value: `❌ Error: ${error.message}`,
                            type: '',
                            highLevelType: undefined,
                            keyType: undefined
                        });
                    }
                }

                if (result.keyType) {
                    let value = `${result.value ?? result.type}`;
                    let indexedVariables = result.indexedVariables;
                    let namedVariables = result.namedVariables;

                    if (indexedVariables === undefined || namedVariables === undefined) {
                        // If either indexed or named variables are undefined, we should tell the debugger to ask for everything
                        // by supplying undefined values for both
                        indexedVariables = undefined;
                        namedVariables = undefined;
                    }

                    // check to see if this is an dictionary or a list
                    if (result.keyType === 'Integer') {
                        // list type
                        v = new Variable(result.name, value, refId, indexedVariables as number, namedVariables as number);
                    } else if (result.keyType === 'String') {
                        // dictionary type
                        v = new Variable(result.name, value, refId, indexedVariables as number, namedVariables as number);
                    }
                    v.type = result.type;
                } else {

                    let value: string;
                    if (result.type === VariableType.Invalid) {
                        value = result.value ?? 'Invalid';
                    } else if (result.type === VariableType.Uninitialized) {
                        value = 'Uninitialized';
                    } else {
                        value = `${result.value}`;
                    }
                    // If the variable is lazy we must assign a refId to inform the system
                    // to request this variable again in the future for value resolution
                    v = new Variable(result.name, value, result?.presentationHint?.lazy ? refId : 0);
                }
                this.variables[refId] = v;
            } else if (this.rokuAdapter.isTelnetAdapter()) {
                if (result.highLevelType === 'primative' || result.highLevelType === 'uninitialized') {
                    v = new Variable(result.name, `${result.value}`);
                } else if (result.highLevelType === 'array') {
                    let refId = this.getEvaluateRefId(result.evaluateName, frameId);
                    v = new Variable(result.name, result.type, refId, result.children?.length ?? 0, 0);
                    this.variables[refId] = v;
                } else if (result.highLevelType === 'object') {
                    let refId: number;
                    //handle collections
                    if (this.rokuAdapter.isScrapableContainObject(result.type)) {
                        refId = this.getEvaluateRefId(result.evaluateName, frameId);
                    }
                    v = new Variable(result.name, result.type, refId, 0, result.children?.length ?? 0);
                    this.variables[refId] = v;
                } else if (result.highLevelType === 'function') {
                    v = new Variable(result.name, `${result.value}`);
                } else {
                    //all other cases, but mostly for HighLevelType.unknown
                    v = new Variable(result.name, `${result.value}`);
                }
            }

            v.type = result.type;
            v.evaluateName = result.evaluateName;
            v.frameId = frameId;
            v.type = result.type;
            v.presentationHint = result.presentationHint ? { kind: result.presentationHint?.kind, lazy: result.presentationHint?.lazy } : undefined;
            if (util.isTransientVariable(v.name)) {
                v.presentationHint = { kind: 'virtual' };
            }

            if (result.children && maxDepth > 0) {
                if (!v.childVariables) {
                    v.childVariables = [];
                }

                // Create a mapping of the children to their index so we can evaluate them in bulk
                let indexMappedChildren = result.children.map((child, index) => {
                    let remapped = { child: child, index: index, evaluate: !!(child.isCustom && !child.presentationHint?.lazy && child.evaluateNow) };
                    return remapped;
                });
                if (this.enableDebugProtocol) {
                    let childrenToEvaluate = indexMappedChildren.filter(x => x.evaluate);
                    let evaluateArgsArray = childrenToEvaluate.map(x => {
                        return { expression: x.child.evaluateName, frameId: frameId };
                    });

                    let variablePathArray = childrenToEvaluate.map(x => {
                        return util.getVariablePath(x.child.evaluateName);
                    });

                    try {
                        let bulkEvaluations = await this.bulkEvaluateExpressionToTempVar(frameId, evaluateArgsArray, variablePathArray);
                        if (bulkEvaluations.bulkVarName) {
                            let newResults = await this.rokuAdapter.getVariable(bulkEvaluations.bulkVarName, frameId);
                            childrenToEvaluate.map((mappedChild, index) => {
                                let newResult = newResults.children[index];
                                this.mergeEvaluateContainers(mappedChild.child, newResult);
                                mappedChild.child.evaluateNow = false;
                                return mappedChild;
                            });
                        }
                    } catch (error) {
                        this.logger.error('Error getting bulk variables, will fall back to var by var lookups', error);
                    }
                }
                // If bulk evaluations failed, there is fall back logic in `getVariableFromResult` to do individual evaluations
                v.childVariables = await Promise.all(indexMappedChildren.map(async (mappedChild) => {
                    return this.getVariableFromResult(mappedChild.child, frameId, maxDepth - 1);
                }));
            } else {
                v.childVariables = [];
            }

            // if the var is an array and debugProtocol is enabled, include the array size
            if (this.enableDebugProtocol && v.type === VariableType.Array) {
                if (isNaN(result.indexedVariables as number)) {
                    v.value = v.type;
                } else {
                    v.value = `${v.type}(${result.indexedVariables})`;
                }
            }
        }
        return v;
    }

    /**
     * Helper function to merge the results of an evaluate call into an existing EvaluateContainer
     * Used primarily for custom variables
     */
    private mergeEvaluateContainers(original: EvaluateContainer, updated: EvaluateContainer) {
        original.children = updated.children;
        original.value = updated.value;
        original.type = updated.type;
        original.highLevelType = updated.highLevelType;
        original.keyType = updated.keyType;
        original.indexedVariables = updated.indexedVariables;
        original.namedVariables = updated.namedVariables;
    }

    private getEvaluateRefId(expression: string, frameId: number) {
        let evaluateRefId = `${expression}-${frameId}`;
        if (!this.evaluateRefIdLookup[evaluateRefId]) {
            this.evaluateRefIdLookup[evaluateRefId] = this.evaluateRefIdCounter++;
        }
        return this.evaluateRefIdLookup[evaluateRefId];
    }

    private clearState() {
        //erase all cached variables
        this.variables = {};
        this.completionParentVariableCache.clear();
    }

    /**
     * Sends a launch progress event to the client if the client supports progress reporting.
     * - `'start'`: begins a new progress bar with the given message. Assigns a new progressId.
     * - `'update'`: updates the message on the active progress bar.
     * - `'end'`: dismisses the active progress bar with an optional final message.
     */
    private sendLaunchProgress(type: 'start' | 'update' | 'end', message?: string) {
        if (!this.initRequestArgs?.supportsProgressReporting) {
            return;
        }
        if (type === 'start') {
            this.launchProgressId = `rokudebug-launch-${this.idCounter++}`;
            this.sendEvent(new ProgressStartEvent(this.launchProgressId, 'Launching', `${message}...`));
        } else if (this.launchProgressId) {
            if (type === 'update') {
                this.sendEvent(new ProgressUpdateEvent(this.launchProgressId, `${message}...`));
            } else {
                const lastId = this.launchProgressId;
                this.sendEvent(new ProgressUpdateEvent(lastId, message));
                const endTimer = setTimeout(() => this.flushLaunchProgressEnd?.(), 1000); // add a slight delay before ending the progress to improve UX
                this.flushLaunchProgressEnd = () => {
                    clearTimeout(endTimer);
                    this.flushLaunchProgressEnd = undefined;
                    this.sendEvent(new ProgressEndEvent(lastId, message));
                };
                this.launchProgressId = undefined;
            }
        }
    }

    /**
     * Tells the client to re-request all variables because we've invalidated them
     * @param threadId
     * @param stackFrameId
     */
    private sendInvalidatedEvent(threadId?: number, stackFrameId?: number) {
        //if the client supports this request, send it
        if (this.initRequestArgs.supportsInvalidatedEvent) {
            this.sendEvent(new InvalidatedEvent(['variables'], threadId, stackFrameId));
        }
    }

    /**
     * If `stopOnEntry` is enabled, register the entry breakpoint.
     */
    public async handleEntryBreakpoint() {
        if (!this.enableDebugProtocol) {
            this.entryBreakpointWasHandled = true;
            if (this.launchConfiguration.stopOnEntry || this.launchConfiguration.deepLinkUrl) {
                await this.projectManager.registerEntryBreakpoint(this.projectManager.mainProject.stagingDir);
            }
        }
    }

    /**
     * Converts a debugger line number to a client line number.
     *
     * @param debuggerLine - The line number from the debugger as zero based.
     * @param defaultDebuggerLine - An optional default line number, as zero based, to use if `debuggerLine` is not provided.
     * @returns The corresponding client line number.
     */
    private toClientLine(debuggerLine: number, defaultDebuggerLine?: number) {
        return this.convertDebuggerLineToClient(debuggerLine ?? defaultDebuggerLine);
    }

    /**
     * Converts a debugger column number to a client column number.
     *
     * @param debuggerLine - The column number from the debugger as zero based.
     * @param defaultDebuggerLine - An optional default column number, as zero based, to use if `debuggerLine` is not provided.
     * @returns The corresponding client column number.
     */
    private toClientColumn(debuggerLine: number, defaultDebuggerLine?: number) {
        return this.convertDebuggerColumnToClient(debuggerLine ?? defaultDebuggerLine);
    }

    /**
     * Converts a client line number to a debugger line number.
     *
     * @param clientLine - The line number from the client.
     * @param defaultDebuggerLine - An optional default line number, as zero based, to use if `clientLine` is not provided.
     * @returns The corresponding debugger line number as zero based.
     */
    private toDebuggerLine(clientLine: number, defaultDebuggerLine?: number) {
        if (typeof clientLine === 'number') {
            return this.convertClientLineToDebugger(clientLine);
        }
        return defaultDebuggerLine;
    }

    /**
     * Converts a client column number to a debugger column number.
     *
     * @param clientLine - The column number from the client.
     * @param defaultDebuggerLine - An optional default column number, as zero based, to use if `clientLine` is not provided.
     * @returns The corresponding debugger column number as zero based.
     */
    private toDebuggerColumn(clientLine: number, defaultDebuggerLine?: number) {
        if (typeof clientLine === 'number') {
            return this.convertClientColumnToDebugger(clientLine);
        }
        return defaultDebuggerLine;
    }

    private shutdownPromise: Promise<void> | undefined = undefined;

    /**
     * Called when the debugger is terminated. Feel free to call this as frequently as you want; we'll only run the shutdown process the first time, and return
     * the same promise on subsequent calls
     */
    public async shutdown(errorMessage?: string, modal = false): Promise<void> {
        if (this.shutdownPromise === undefined) {
            this.logger.log('[shutdown] Beginning shutdown sequence', errorMessage);
            //Backstop: if the graceful shutdown hangs (e.g. a home key press against an unreachable
            //device), force-exit anyway so we never leave an orphaned adapter running forever
            const forceExitTimer = setTimeout(() => {
                this.logger.error('[shutdown] graceful shutdown timed out; forcing exit');
                this.forceExit();
            }, this.shutdownForceExitTimeout);
            forceExitTimer.unref?.();
            this.shutdownPromise = this._shutdown(errorMessage, modal).finally(() => {
                clearTimeout(forceExitTimer);
            });
        } else {
            this.logger.log('[shutdown] Tried to call `.shutdown()` again. Returning the same promise');
        }
        return this.shutdownPromise;
    }

    private async _shutdown(errorMessage?: string, modal = false): Promise<void> {
        // Ensure any active launch progress bar is dismissed before showing error messages or the terminated event.
        this.sendLaunchProgress('end', 'Complete');
        // 'end' defers its ProgressEndEvent for UX; deliver it right now (whether from the line above or from an
        // earlier 'end' whose delay has not elapsed yet) - the adapter exits before a pending timer would fire,
        // which would leave the client's progress notification stuck open
        this.flushLaunchProgressEnd?.();

        //send the message FIRST before anything else. This improves the chances that the message will be displayed to the user
        try {
            if (errorMessage) {
                this.logger.error(errorMessage);
                this.showPopupMessage(errorMessage, 'error', modal).catch((error) => {
                    this.logger.error('Error showing popup message', { error });
                });
            }
        } catch (e) {
            this.logger.error(e);
        }
        // stop perfetto tracing if it's running
        try {
            await this.perfettoManager?.stopTracing?.();
        } catch (e) {
            this.logger.error('Error stopping perfetto tracing', e);
        }

        try {
            await this.perfettoManager?.dispose?.();
        } catch (e) {
            this.logger.error('Error disposing perfetto manager', e);
        }

        //close the debugger connection
        try {
            this.logger.log('Destroy rokuAdapter');
            await this.rokuAdapter?.destroy?.();
            //press the home button to return to the home screen
            try {
                this.logger.log('Press home button');
                await this.rokuDeploy.keyPress({ device: this.launchConfiguration.device, key: 'Home', ecpPort: this.launchConfiguration.remotePort });
            } catch (e) {
                this.logger.error(e);
            }
        } catch (e) {
            this.logger.error(e);
        }

        try {
            this.projectManager?.dispose?.();
        } catch (e) {
            this.logger.error(e);
        }

        try {
            this.componentLibraryServer?.stop();
        } catch (e) {
            this.logger.error(e);
        }

        try {
            await this.rendezvousTracker?.destroy?.();
        } catch (e) {
            this.logger.error(e);
        }

        try {
            await this.sourceMapManager?.destroy?.();
        } catch (e) {
            this.logger.error(e);
        }

        try {
            //if configured, delete the staging directory
            if (!this.launchConfiguration.retainStagingFolder) {
                const stagingDirs = this.projectManager?.getStagingDirs() ?? [];
                this.logger.info('deleting staging folders', stagingDirs);
                for (let stagingDir of stagingDirs) {
                    try {
                        fsExtra.removeSync(stagingDir);
                    } catch (e) {
                        this.logger.error(e);
                        util.log(`Error removing staging directory '${stagingDir}': ${JSON.stringify(e)}`);
                    }
                }
            }
        } catch (e) {
            this.logger.error(e);
        }

        try {
            this.logger.log('Send terminated event');
            this.sendEvent(new TerminatedEvent());

            //shut down the process
            this.logger.log('super.shutdown()');
            super.shutdown();
            this.logger.log('shutdown complete');
        } catch (e) {
            this.logger.error(e);
        }

        try {
            this.teardownProcessErrorHandlers();
        } catch (e) {
            this.logger.error(e);
        }
    }
}

export interface AugmentedVariable extends DebugProtocol.Variable {
    childVariables?: AugmentedVariable[];
    // eslint-disable-next-line camelcase
    request_seq?: number;
    frameId?: number;
    /**
     * only used for lazy variables
     */
    isResolved?: boolean;
    /**
     * used to indicate that this variable is a scope variable
     * and may require special handling
     */
    isScope?: boolean;
}

rokucommunity / roku-debug / 31208378856

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous