roku-debug 0.23.13 → 0.23.15

package/dist/debugSession/BrightScriptDebugSession.js

@@ -32,9 +32,21 @@ const ecpRegistryUtils_1 = require("./ecpRegistryUtils");
 const RokuECP_1 = require("../RokuECP");
 const Exceptions_1 = require("../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.
+ */
+var CompletionSortTier;
+(function (CompletionSortTier) {
+    CompletionSortTier["Member"] = "1";
+    CompletionSortTier["Method"] = "2";
+    CompletionSortTier["ScopeFunction"] = "3";
+    CompletionSortTier["Global"] = "4";
+})(CompletionSortTier || (CompletionSortTier = {}));
 class BrightScriptDebugSession extends debugadapter_1.LoggingDebugSession {
     constructor() {
         super();
+        this.handlingProcessError = false;
         this.logger = logging_1.logger.createLogger(`[session]`);
         this.isWindowsPlatform = process.platform.startsWith('win');
         /**
@@ -43,6 +55,10 @@ class BrightScriptDebugSession extends debugadapter_1.LoggingDebugSession {
         this.idCounter = 1;
         this.processErrorHandlersRegistered = false;
         this.isCrashed = false;
+        /** Set once the client (e.g. VS Code) disconnects, so we stop writing to a now-dead stream */
+        this.clientDisconnected = false;
+        /** How long to wait for a graceful shutdown before forcibly exiting the process */
+        this.shutdownForceExitTimeout = 10000;
         //set imports as class properties so they can be spied upon during testing
         this.rokuDeploy = roku_deploy_1.rokuDeploy;
         this.componentLibraryServer = new ComponentLibraryServer_1.ComponentLibraryServer();
@@ -58,6 +74,12 @@ class BrightScriptDebugSession extends debugadapter_1.LoggingDebugSession {
         this.evaluateRefIdLookup = {};
         this.evaluateRefIdCounter = 1;
         this.variables = {};
+        /**
+         * 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.
+         */
+        this.completionParentVariableCache = new Map();
         this.tempVarPrefix = '__rokudebug__';
         /**
          * 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
@@ -95,7 +117,17 @@ class BrightScriptDebugSession extends debugadapter_1.LoggingDebugSession {
         this.fileLoggingManager = new logging_1.FileLoggingManager();
     }
     start(inStream, outStream) {
+        var _a, _b, _c;
         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;
+        };
+        (_a = inStream === null || inStream === void 0 ? void 0 : inStream.on) === null || _a === void 0 ? void 0 : _a.call(inStream, 'close', markClientGone);
+        (_b = inStream === null || inStream === void 0 ? void 0 : inStream.on) === null || _b === void 0 ? void 0 : _b.call(inStream, 'end', markClientGone);
+        (_c = outStream === null || outStream === void 0 ? void 0 : outStream.on) === null || _c === void 0 ? void 0 : _c.call(outStream, '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,
@@ -111,106 +143,147 @@ class BrightScriptDebugSession extends debugadapter_1.LoggingDebugSession {
             debugadapter_1.logger.setup(debugadapter_1.Logger.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.
+     */
+    sendEvent(event) {
+        if (this.clientDisconnected) {
+            return;
+        }
+        super.sendEvent(event);
+    }
     setupProcessErrorHandlers() {
         if (this.processErrorHandlersRegistered) {
             return;
         }
         this.processErrorHandlersRegistered = true;
-        const handleError = (type, error) => {
-            var _a, _b, _c, _d, _e, _f, _g;
-            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;
-            let debuggerVersion;
-            let additionalInfo;
-            try {
-                debuggerVersion = fsExtra.readJsonSync(path.resolve(__dirname, '../../package.json')).version;
-                const clientName = (_b = (_a = this.initRequestArgs) === null || _a === void 0 ? void 0 : _a.clientName) !== null && _b !== void 0 ? _b : 'unknown';
-                additionalInfo = {
-                    clientName: clientName,
-                    rokuDebugVersion: debuggerVersion,
-                    ecpMode: (_c = this.deviceInfo) === null || _c === void 0 ? void 0 : _c.ecpSettingMode,
-                    developerMode: (_d = this.deviceInfo) === null || _d === void 0 ? void 0 : _d.developerEnabled,
-                    firmware: this.deviceInfo ? `${(_e = this.deviceInfo) === null || _e === void 0 ? void 0 : _e.softwareVersion}.${(_f = this.deviceInfo) === null || _f === void 0 ? void 0 : _f.softwareBuild}` : undefined,
-                    protocolVersion: (_g = this.deviceInfo) === null || _g === void 0 ? void 0 : _g.brightscriptDebuggerVersion,
-                    protocolEnabled: this.enableDebugProtocol
-                };
-                const lines = Object.entries(additionalInfo).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;
-                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 !== null && stack !== void 0 ? 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(() => { });
-            this.isCrashed = true;
-            this.sendEvent(new Events_1.ProcessCrashEvent({ type, message, stack, additionalInfo: additionalInfo !== null && additionalInfo !== void 0 ? additionalInfo : {} }));
-            setTimeout(() => void this.shutdown(), 5000);
-        };
-        this._uncaughtExceptionHandler = (error) => handleError('uncaughtException', error);
-        this._unhandledRejectionHandler = (reason) => handleError('unhandledRejection', reason);
+        this._uncaughtExceptionHandler = (error) => this.handleProcessError('uncaughtException', error);
+        this._unhandledRejectionHandler = (reason) => this.handleProcessError('unhandledRejection', reason);
         process.on('uncaughtException', this._uncaughtExceptionHandler);
         process.on('unhandledRejection', this._unhandledRejectionHandler);
     }
+    /**
+     * 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.
+     */
+    isClientGoneError(error) {
+        const code = error === null || error === void 0 ? void 0 : error.code;
+        const message = error instanceof Error ? error.message : String(error !== null && error !== void 0 ? 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.
+     */
+    forceExit(code = 0) {
+        this.teardownProcessErrorHandlers();
+        process.exit(code);
+    }
+    handleProcessError(type, error) {
+        var _a, _b, _c, _d, _e, _f, _g;
+        //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;
+        let debuggerVersion;
+        let additionalInfo;
+        try {
+            debuggerVersion = fsExtra.readJsonSync(path.resolve(__dirname, '../../package.json')).version;
+            const clientName = (_b = (_a = this.initRequestArgs) === null || _a === void 0 ? void 0 : _a.clientName) !== null && _b !== void 0 ? _b : 'unknown';
+            additionalInfo = {
+                clientName: clientName,
+                rokuDebugVersion: debuggerVersion,
+                ecpMode: (_c = this.deviceInfo) === null || _c === void 0 ? void 0 : _c.ecpSettingMode,
+                developerMode: (_d = this.deviceInfo) === null || _d === void 0 ? void 0 : _d.developerEnabled,
+                firmware: this.deviceInfo ? `${(_e = this.deviceInfo) === null || _e === void 0 ? void 0 : _e.softwareVersion}.${(_f = this.deviceInfo) === null || _f === void 0 ? void 0 : _f.softwareBuild}` : undefined,
+                protocolVersion: (_g = this.deviceInfo) === null || _g === void 0 ? void 0 : _g.brightscriptDebuggerVersion,
+                protocolEnabled: this.enableDebugProtocol
+            };
+            const lines = Object.entries(additionalInfo).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;
+            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 !== null && stack !== void 0 ? 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(() => { });
+        this.isCrashed = true;
+        this.sendEvent(new Events_1.ProcessCrashEvent({ type, message, stack, additionalInfo: additionalInfo !== null && additionalInfo !== void 0 ? additionalInfo : {} }));
+        setTimeout(() => void this.shutdown(), 5000).unref();
+    }
     teardownProcessErrorHandlers() {
         if (this._uncaughtExceptionHandler) {
             process.removeListener('uncaughtException', this._uncaughtExceptionHandler);
@@ -452,9 +525,14 @@ class BrightScriptDebugSession extends debugadapter_1.LoggingDebugSession {
             catch (e) {
                 return this.shutdown(`Could not resolve ip address for host '${this.launchConfiguration.host}'`);
             }
-            // fetches the device info and parses the xml data to JSON object
+            // fetch device info if not supplied via launch config
             try {
-                this.deviceInfo = await roku_deploy_1.rokuDeploy.getDeviceInfo({ host: this.launchConfiguration.host, remotePort: this.launchConfiguration.remotePort, enhance: true, timeout: 4000 });
+                if (this.launchConfiguration.deviceInfo) {
+                    this.deviceInfo = roku_deploy_1.rokuDeploy.enhanceDeviceInfo(this.launchConfiguration.deviceInfo);
+                }
+                else {
+                    this.deviceInfo = await roku_deploy_1.rokuDeploy.getDeviceInfo({ host: this.launchConfiguration.host, remotePort: this.launchConfiguration.remotePort, enhance: true, timeout: 4000 });
+                }
                 if (this.deviceInfo.ecpSettingMode === 'limited') {
                     return await this.shutdown(`ECP access is limited on this Roku. Please change it to 'permissive' or 'enabled' and try again. (device: ${this.launchConfiguration.host})`);
                 }
@@ -1202,6 +1280,7 @@ class BrightScriptDebugSession extends debugadapter_1.LoggingDebugSession {
                 sourceDirs: componentLibrary.sourceDirs,
                 bsConst: componentLibrary.bsConst,
                 install: componentLibrary.install,
+                enablePostfix: componentLibrary.enablePostfix,
                 injectRaleTrackerTask: componentLibrary.injectRaleTrackerTask,
                 raleTrackerTaskFileLocation: componentLibrary.raleTrackerTaskFileLocation,
                 libraryIndex: libraryIndex,
@@ -1453,24 +1532,8 @@ class BrightScriptDebugSession extends debugadapter_1.LoggingDebugSession {
         logger.info('begin', { args });
         try {
             const scopes = new Array();
-            let v;
             // create the locals scope
-            let localsRefId = this.getEvaluateRefId('$$locals', args.frameId);
-            if (this.variables[localsRefId]) {
-                v = this.variables[localsRefId];
-            }
-            else {
-                v = {
-                    variablesReference: localsRefId,
-                    name: 'Locals',
-                    value: '',
-                    type: '$$Locals',
-                    frameId: args.frameId,
-                    isScope: true,
-                    childVariables: []
-                };
-                this.variables[localsRefId] = v;
-            }
+            let v = this.getOrCreateLocalsScope(args.frameId);
             let localScope = {
                 name: 'Local',
                 variablesReference: v.variablesReference,
@@ -1515,6 +1578,25 @@ class BrightScriptDebugSession extends debugadapter_1.LoggingDebugSession {
             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`.
+     */
+    getOrCreateLocalsScope(frameId) {
+        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];
+    }
     async continueRequest(response, args) {
         //if we have a compile error, we should shut down
         if (this.compileError) {
@@ -2009,7 +2091,7 @@ class BrightScriptDebugSession extends debugadapter_1.LoggingDebugSession {
         return results;
     }
     async completionsRequest(response, args, request) {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
         this.logger.log('completionsRequest', args, request);
         // this.sendEvent(new LogOutputEvent(`completionsRequest: ${args.text}`));
         // this.sendEvent(new OutputEvent(`completionsRequest: ${args.text}\n`, 'stderr'));
@@ -2025,30 +2107,41 @@ class BrightScriptDebugSession extends debugadapter_1.LoggingDebugSession {
             }
             let completions = new Map();
             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 = (_a = lines[this.toDebuggerLine(args.line, 0)]) !== null && _a !== void 0 ? _a : '';
+            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
-                let parentVariable = this.findVariableByPath(Object.values(this.variables), parentVariablePath, args.frameId);
-                if (!parentVariable || parentVariable.childVariables.length === 0) {
-                    // We did not find the parent variable, so try to look it up from the device
-                    try {
-                        let { evalArgs } = await this.evaluateExpressionToTempVar({ expression: parentVariablePath.join('.'), frameId: args.frameId }, parentVariablePath);
-                        let result = await this.rokuAdapter.getVariable(evalArgs.expression, args.frameId);
-                        parentVariable = await this.getVariableFromResult(result, args.frameId);
-                    }
-                    catch (error) {
-                        this.logger.error('Error looking up parent completions', error, { parentVariablePath });
-                    }
-                }
+                // 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) {
-                    let possibleFieldsAndMethods = [];
-                    // Filter out virtual variables
-                    possibleFieldsAndMethods = parentVariable.childVariables.filter((v) => { var _a; return ((_a = v.presentationHint) === null || _a === void 0 ? void 0 : _a.kind) !== 'virtual'; });
+                    // 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 === VariablesResponse_1.VariableType.Array ||
+                        parentVariable.type === VariablesResponse_1.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) => { var _a; return child.name && ((_a = child.presentationHint) === null || _a === void 0 ? void 0 : _a.kind) !== 'virtual'; });
                     for (let v of possibleFieldsAndMethods) {
                         // Default completion type should be variable
                         let completionType = 'variable';
@@ -2066,37 +2159,49 @@ class BrightScriptDebugSession extends debugadapter_1.LoggingDebugSession {
                                     break;
                             }
                         }
-                        let label = v.name;
-                        if (parentVariable.type === VariablesResponse_1.VariableType.Array ||
-                            parentVariable.type === VariablesResponse_1.VariableType.List ||
-                            parentVariable.type === 'roXMLList' ||
-                            parentVariable.type === 'roByteArray') {
-                            label = `[${v.name}]`;
-                        }
-                        completions.set(`${completionType}-${v.name}`, {
-                            label: label,
+                        const completionItem = {
+                            label: v.name,
                             type: completionType,
-                            sortText: '000000'
-                        });
+                            //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);
                     }
-                    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`
-                        ...(_b = (_a = roku_types_1.interfaces[parentComponentType]) === null || _a === void 0 ? void 0 : _a.methods) !== null && _b !== void 0 ? _b : [],
-                        //interfaces from component of this name (if applicable) Ex: `roSGNode` or `roDateTime`
-                        ...(_d = (_c = roku_types_1.components[parentComponentType]) === null || _c === void 0 ? void 0 : _c.interfaces.map((i) => { var _a; return (_a = roku_types_1.interfaces[i.name.toLowerCase()]) === null || _a === void 0 ? void 0 : _a.methods; })) !== null && _d !== void 0 ? _d : [],
-                        // Add parent event function completions (if applicable) Ex: `roSGNodeEvent` or `roDeviceInfoEvent`
-                        ...(_f = (_e = roku_types_1.events[parentComponentType]) === null || _e === void 0 ? void 0 : _e.methods) !== null && _f !== void 0 ? _f : []
-                    ].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: (_g = method.description) !== null && _g !== void 0 ? _g : '',
-                            sortText: '000000'
-                        });
+                    // 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`
+                            ...(_c = (_b = roku_types_1.interfaces[parentComponentType]) === null || _b === void 0 ? void 0 : _b.methods) !== null && _c !== void 0 ? _c : [],
+                            //interfaces from component of this name (if applicable) Ex: `roSGNode` or `roDateTime`
+                            ...(_e = (_d = roku_types_1.components[parentComponentType]) === null || _d === void 0 ? void 0 : _d.interfaces.map((i) => { var _a; return (_a = roku_types_1.interfaces[i.name.toLowerCase()]) === null || _a === void 0 ? void 0 : _a.methods; })) !== null && _e !== void 0 ? _e : [],
+                            // Add parent event function completions (if applicable) Ex: `roSGNodeEvent` or `roDeviceInfoEvent`
+                            ...(_g = (_f = roku_types_1.events[parentComponentType]) === null || _f === void 0 ? void 0 : _f.methods) !== null && _g !== void 0 ? _g : []
+                        ].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: (_h = method.description) !== null && _h !== void 0 ? _h : '',
+                                sortText: `${CompletionSortTier.Method}${method.name}`
+                            });
+                        }
                     }
                     // Add the global functions to the completions results
                     if (supplyLocalScopeCompletions) {
@@ -2104,8 +2209,8 @@ class BrightScriptDebugSession extends debugadapter_1.LoggingDebugSession {
                             completions.set(`function-${globalCallable.name.toLocaleLowerCase()}`, {
                                 label: globalCallable.name,
                                 type: 'function',
-                                detail: (_j = (_h = globalCallable.shortDescription) !== null && _h !== void 0 ? _h : globalCallable.documentation) !== null && _j !== void 0 ? _j : '',
-                                sortText: '000000'
+                                detail: (_k = (_j = globalCallable.shortDescription) !== null && _j !== void 0 ? _j : globalCallable.documentation) !== null && _k !== void 0 ? _k : '',
+                                sortText: `${CompletionSortTier.Global}${globalCallable.name}`
                             });
                         }
                         const frame = this.rokuAdapter.getStackFrameById(args.frameId);
@@ -2116,7 +2221,7 @@ class BrightScriptDebugSession extends debugadapter_1.LoggingDebugSession {
                                     completions.set(`${scopeFunction.completionItemKind}-${scopeFunction.name.toLocaleLowerCase()}`, {
                                         label: scopeFunction.name,
                                         type: scopeFunction.completionItemKind,
-                                        sortText: '000000'
+                                        sortText: `${CompletionSortTier.ScopeFunction}${scopeFunction.name}`
                                     });
                                 }
                             }
@@ -2127,8 +2232,14 @@ class BrightScriptDebugSession extends debugadapter_1.LoggingDebugSession {
                     }
                 }
             }
-            // this.sendEvent(new LogOutputEvent(`text: ${args.text} | completions: ${completions.map(v => v.label).join(', ')}`));
-            // this.sendEvent(new OutputEvent(`text: ${args.text} | completions: ${completions.map(v => v.label).join(', ')}\n`, 'stderr'));
+            // 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()]
             };
@@ -2144,32 +2255,76 @@ class BrightScriptDebugSession extends debugadapter_1.LoggingDebugSession {
      * Gets the closest completion details the incoming completion request.
      */
     getClosestCompletionDetails(args) {
+        var _a;
         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];
-        let variablePathString = '';
-        let i = column - 1;
+        const targetLine = (_a = lines[lineNumber]) !== null && _a !== void 0 ? _a : '';
+        const cursorIndex = column - 1;
         const variableChars = /[a-z0-9_\.]/i;
-        // If the character at immediate to the right of the cursor is a variable character, then we are not at the end of the variable path.
-        if (targetLine.length - 1 > i && variableChars.test(targetLine[i + 1])) {
+        // 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;
         }
-        // Find the start of the variable path by looking for the first non-alphanumeric or non_underscore character before the cursor
-        while (i >= 0 && (variableChars.test(targetLine[i]))) {
-            i--;
+        // 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;
+        const openBracket = this.findUnclosedOpener(targetLine, column);
+        if ((openBracket === null || openBracket === void 0 ? void 0 : 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--;
         }
-        // Pull the variable path string from the line
-        variablePathString = targetLine.slice(i + 1, column);
-        // Attempted dot access something unexpected
-        // Example: `getPerson().name` where `getPerson()` is not a valid variable
-        // and results in `.name` being the variable path string
+        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 = [];
+        let variablePath;
         if (!variablePathString.trim()) {
             // The text was empty so assume via '' that we are looking up the local scope variables and global functions
             variablePath = [''];
@@ -2185,28 +2340,170 @@ class BrightScriptDebugSession extends debugadapter_1.LoggingDebugSession {
         if (!variablePath) {
             return undefined;
         }
-        let parentVariablePath;
-        // If the last character is a period, then pull completions for the parent variable before the period
-        if (variablePathString.endsWith('.')) {
-            parentVariablePath = variablePath;
-        }
-        else {
-            // Otherwise, pull completions for the parent variable
-            parentVariablePath = variablePath.slice(0, variablePath.length - 1);
-        }
-        // If the parent variable path is empty or an empty string, then we are looking up the local scope variables and global functions
+        // 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 = [''];
         }
-        return { parentVariablePath: parentVariablePath };
+        const result = { 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.
+     */
+    getCompletionReplaceRange(args) {
+        var _a;
+        const lines = args.text.split('\n');
+        const lineNumber = this.toDebuggerLine(args.line, 0);
+        const cursorOffset = this.toDebuggerColumn(args.column);
+        const targetLine = (_a = lines[lineNumber]) !== null && _a !== void 0 ? _a : '';
+        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.
+     */
+    findUnclosedOpener(line, column) {
+        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.
+     */
+    async resolveCompletionParentVariable(parentVariablePath, frameId) {
+        // 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 });
+                }
+                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;
+        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.
+     */
+    buildVariableExpression(segments) {
+        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`).
+     */
+    normalizeVariableName(name) {
+        let value = name !== null && name !== void 0 ? 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.
+     */
+    findFrameVariableByPath(path, frameId) {
+        var _a;
+        const localsContainer = this.variables[this.getEvaluateRefId('$$locals', frameId)];
+        if (path.length === 1 && path[0] === '') {
+            return localsContainer;
+        }
+        return this.findVariableByPath((_a = localsContainer === null || localsContainer === void 0 ? void 0 : localsContainer.childVariables) !== null && _a !== void 0 ? _a : [], path, frameId);
     }
     findVariableByPath(variables, path, frameId) {
         var _a;
         let current = null;
         for (const name of path) {
-            // Find the object matching the current name in the data
+            const normalizedName = this.normalizeVariableName(name);
+            // Find the object matching the current name in the data (case-insensitive, per BrightScript)
             current = (_a = (Array.isArray(variables) ? variables : current === null || current === void 0 ? void 0 : current.childVariables)) === null || _a === void 0 ? void 0 : _a.find(obj => {
-                return obj.name === name && obj.frameId === frameId;
+                return this.normalizeVariableName(obj.name) === normalizedName && obj.frameId === frameId;
             });
             // If no match is found, return null
             if (!current) {
@@ -2597,6 +2894,7 @@ class BrightScriptDebugSession extends debugadapter_1.LoggingDebugSession {
     clearState() {
         //erase all cached variables
         this.variables = {};
+        this.completionParentVariableCache.clear();
     }
     /**
      * Sends a launch progress event to the client if the client supports progress reporting.
@@ -2700,9 +2998,19 @@ class BrightScriptDebugSession extends debugadapter_1.LoggingDebugSession {
      * the same promise on subsequent calls
      */
     async shutdown(errorMessage, modal = false) {
+        var _a;
         if (this.shutdownPromise === undefined) {
             this.logger.log('[shutdown] Beginning shutdown sequence', errorMessage);
-            this.shutdownPromise = this._shutdown(errorMessage, modal);
+            //Backstop: if the graceful shutdown hangs (e.g. pressHomeButton 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);
+            (_a = forceExitTimer.unref) === null || _a === void 0 ? void 0 : _a.call(forceExitTimer);
+            this.shutdownPromise = this._shutdown(errorMessage, modal).finally(() => {
+                clearTimeout(forceExitTimer);
+            });
         }
         else {
             this.logger.log('[shutdown] Tried to call `.shutdown()` again. Returning the same promise');