Add WebSocket Terminal support

docs/RunDebug.md

@@ -128,3 +128,37 @@ If you are experiencing issues using the debugger, please follow these steps bef
 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:
+
+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": "editorLangId =~ /^objectscript/ && 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) => {