Add WebSocket Terminal support (#1150)

Author: isc-bsaviano

docs/RunDebug.md

@@ -121,10 +121,44 @@ The InterSystems ObjectScript Extension provides a [Webview](https://code.visual
 
 ## Troubleshooting Debugger Issues
 
-If you are experiencing issues using the debugger, please follow these steps before opening an issue on GitHub:
+If you are experiencing issues using the debugger, please follow these steps before opening an issue on GitHub. Note that the trace global may contain confidential information, so you should review the contents and mask/remove anything that you want to keep private.
 
 1. Open a terminal on your server and `zn` to the namespace containing the class or routine you are debugging.
 2. Run the command `Kill ^IRIS.Temp.Atelier("debug")`, then `Set ^IRIS.Temp.Atelier("debug") = 1` to turn on the Atelier API debug logging feature. If you are on Caché or Ensemble, the global is `^CacheTemp.ISC.Atelier("debug")`.
 3. In VS Code, start a debugging session using the configuration that produces the error.
 4. Once the error appears, copy the contents of the `^IRIS.Temp.Atelier("debug")` global and add it to your GitHub issue.
 5. After you capture the log, run the command `Kill ^IRIS.Temp.Atelier("debug")`, then `Set ^IRIS.Temp.Atelier("debug") = 0` to turn logging back off again.
+
+{: #terminal}
+## Using the WebSocket Terminal
+
+The InterSystems ObjectScript Extension provides support for a WebSocket-based command-line interface for executing ObjectScript commands on a connected server. The server can be on the same system as VS Code, or a remote system. This feature is only supported when connecting to InterSystems IRIS version 2023.2 or later. 
+
+The WebSocket terminal supports the following features:
+
+- VS Code's [shell integration](https://code.visualstudio.com/docs/terminal/shell-integration) feature so your command history and output will be captured by VS Code and can be accessed by its UI.
+- Multi-line editing. An additional editable line will be added when the user presses `Enter` and there are unclosed `{` or `(` in the command input.
+- Syntax coloring for command input. (Toggleable using the `objectscript.webSocketTerminal.syntaxColoring` setting)
+- Syntax checking for entered command input with detailed error messages reported along with the standard `<SYNTAX>` error.
+- Many features of the [standard terminal](https://docs.intersystems.com/irislatest/csp/docbook/DocBook.UI.Page.cls?KEY=GTER_intro), including:
+  - The Read command
+  - Interrupts (`Ctrl-C`)
+  - Namespace switches
+  - [Custom terminal prompts](https://irisdocs.intersystems.com/irislatest/csp/documatic/%25CSP.Documatic.cls?LIBRARY=%25SYS&CLASSNAME=%25SYSTEM.Process#TerminalPrompt) (except code 7)
+  - Shells like SQL (`Do $SYSTEM.SQL.Shell()`) and Python (`Do $SYSTEM.Python.Shell()`) 
+
+The WebSocket terminal does not support [command-line debugging](https://docs.intersystems.com/irislatest/csp/docbook/DocBook.UI.Page.cls?KEY=GCOS_debug) since the InterSystems ObjectScript Extension contains an interactive debugger. Users are also discouraged from using [routine editing commands](https://docs.intersystems.com/irislatest/csp/docbook/DocBook.UI.Page.cls?KEY=RCOS_ZCOMMANDS) since VS Code with the InterSystems ObjectScript Extension Pack provides an excellent ObjectScript editing experience.
+
+Note that the terminal process is started using the JOB command, so if you have a [`^%ZSTART` routine](https://docs.intersystems.com/iris20223/csp/docbook/Doc.View.cls?KEY=GSTU_customize_startstop) enabled the `JOB` subroutine will be called at the start of the process, not `LOGIN` like the standard terminal. Also, the [`ZWELCOME` routine](https://docs.intersystems.com/irislatest/csp/docbook/DocBook.UI.Page.cls?KEY=GTER_intro#GTER_zwelcome) will not be run before the first command prompt is shown.
+
+The WebSocket terminal can be opened from [the command palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette) using the `ObjectScript: Launch WebSocket Terminal` command. The WebSocket terminal connection will be established using the current server connection. A WebSocket terminal connection can also be opened from the [Terminal Profiles menu](https://code.visualstudio.com/docs/terminal/basics#_terminal-shells).
+
+## Troubleshooting WebSocket Terminal Issues
+
+If you are experiencing issues using the WebSocket terminal, please follow these steps before opening an issue on GitHub. Note that the trace global may contain confidential information, so you should review the contents and mask/remove anything that you want to keep private.
+
+1. Open a standard terminal on your server and `zn` to the namespace containing the class or routine you are debugging.
+2. Run the command `Kill ^IRIS.Temp.Atelier("terminal")`, then `Set ^IRIS.Temp.Atelier("terminal") = 1` to turn on the Atelier API terminal logging feature.
+3. In VS Code, launch the WebSocket terminal and run the commands that produce the error.
+4. Once the error appears, copy the contents of the `^IRIS.Temp.Atelier("terminal")` global and add it to your GitHub issue.
+5. After you capture the log, run the command `Kill ^IRIS.Temp.Atelier("terminal")`, then `Set ^IRIS.Temp.Atelier("terminal") = 0` to turn logging back off again.

docs/SettingsReference.md

@@ -82,6 +82,7 @@ The extensions in the InterSystems ObjectScript Extension Pack provide many sett
 | `"objectscript.studioActionDebugOutput"` | Log in JSON format the action that VS Code should perform as requested by the server. | `boolean` | `false` | Actions will be logged to the `ObjectScript` Output channel. |
 | `"objectscript.suppressCompileErrorMessages"` | Suppress popup messages about errors during compile, but still focus on Output view. | `boolean` | `false` | |
 | `"objectscript.suppressCompileMessages"` | Suppress popup messages about successful compile. | `boolean` | `true` | |
+| `"objectscript.webSocketTerminal.syntaxColoring"` | Enable syntax coloring for command input in the InterSystems WebSocket Terminal. | `boolean` | `true` | |
 
 {: #intersystems-servermanager}
 ## InterSystems Server Manager

package.json

@@ -89,6 +89,8 @@
     "onCommand:vscode-objectscript.newFile.dtl",
     "onCommand:vscode-objectscript.modifyWsFolder",
     "onCommand:vscode-objectscript.openErrorLocation",
+    "onCommand:vscode-objectscript.launchWebSocketTerminal",
+    "onTerminalProfile:vscode-objectscript.webSocketTerminal",
     "onLanguage:objectscript",
     "onLanguage:objectscript-int",
     "onLanguage:objectscript-class",
@@ -343,6 +345,10 @@
         {
           "command": "vscode-objectscript.openErrorLocation",
           "when": "vscode-objectscript.connectActive && workspaceFolderCount != 0"
+        },
+        {
+          "command": "vscode-objectscript.launchWebSocketTerminal",
+          "when": "vscode-objectscript.connectActive"
         }
       ],
       "view/title": [
@@ -1119,6 +1125,11 @@
         "category": "ObjectScript",
         "command": "vscode-objectscript.openErrorLocation",
         "title": "Open Error Location..."
+      },
+      {
+        "category": "ObjectScript",
+        "command": "vscode-objectscript.launchWebSocketTerminal",
+        "title": "Launch WebSocket Terminal"
       }
     ],
     "keybindings": [
@@ -1478,6 +1489,11 @@
           "type": "boolean",
           "default": true
         },
+        "objectscript.webSocketTerminal.syntaxColoring": {
+          "description": "Enable syntax coloring for command input in the InterSystems WebSocket Terminal.",
+          "type": "boolean",
+          "default": true
+        },
         "objectscript.showProposedApiPrompt": {
           "description": "Controls whether a prompt to enable VS Code proposed APIs is shown when a server-side workspace folder is opened.",
           "type": "boolean",
@@ -1624,7 +1640,16 @@
         ],
         "priority": "option"
       }
-    ]
+    ],
+    "terminal": {
+      "profiles": [
+        {
+          "id": "vscode-objectscript.webSocketTerminal",
+          "title": "InterSystems WebSocket Terminal",
+          "icon": "./images/fileIcon.svg"
+        }
+      ]
+    }
   },
   "scripts": {
     "vscode:prepublish": "webpack --mode production",

src/api/index.ts

@@ -150,6 +150,13 @@ export class AtelierAPI {
     return `${proto}://${host}:${port}${pathPrefix}/api/atelier/v${apiVersion}/%25SYS/debug`;
   }
 
+  public terminalUrl(): string {
+    const { host, https, port, apiVersion, pathPrefix } = this.config;
+    return apiVersion >= 7
+      ? `${https ? "wss" : "ws"}://${host}:${port}${pathPrefix}/api/atelier/v${apiVersion}/%25SYS/terminal`
+      : "";
+  }
+
   public async updateCookies(newCookies: string[]): Promise<void> {
     const cookies = this.cache.get("cookies", []);
     newCookies.forEach((cookie) => {