add property for controlling escaping arguments for the runInTerminal request (#305)

Fixes #146

Author: roblourens

changelog.md

@@ -6,6 +6,9 @@ sectionid: changelog
 
 #### All notable changes to the specification will be documented in this file.
 
+* 1.57.X:
+  * Add the `argsCanBeInterpretedByShell` property to the `RunInTerminalRequest`
+
 * 1.56.X:
   * Add additional information to the `StepInTarget`
   * Clarification around wording for "clients"

debugAdapterProtocol.json

@@ -734,7 +734,7 @@
 			"allOf": [ { "$ref": "#/definitions/Request" }, {
 				"type": "object",
 				"title": "Reverse Requests",
-				"description": "This optional request is sent from the debug adapter to the client to run a command in a terminal.\nThis is typically used to launch the debuggee in a terminal provided by the client.\nThis request should only be called if the corresponding capability `supportsRunInTerminalRequest` is true.",
+				"description": "This optional request is sent from the debug adapter to the client to run a command in a terminal.\nThis is typically used to launch the debuggee in a terminal provided by the client.\nThis request should only be called if the corresponding capability `supportsRunInTerminalRequest` is true.\nClient implementations of `runInTerminal` are free to run the command however they choose including issuing the command to a command line interpreter (aka 'shell'). Argument strings passed to the `runInTerminal` request must arrive verbatim in the command to be run. As a consequence, clients which use a shell are responsible for escaping any special shell characters in the argument strings to prevent them from being interpreted (and modified) by the shell.\nSome users may wish to take advantage of shell processing in the argument strings. For clients which implement `runInTerminal` using an intermediary shell, the `argsCanBeInterpretedByShell` property can be set to true. In this case the client is requested not to escape any special shell characters in the argument strings.",
 				"properties": {
 					"command": {
 						"type": "string",
@@ -778,6 +778,10 @@
 						"type": [ "string", "null" ],
 						"description": "Proper values must be strings. A value of `null` removes the variable from the environment."
 					}
+				},
+				"argsCanBeInterpretedByShell": {
+					"type": "boolean",
+					"description": "This property should only be set if the client has passed the value true for the 'supportsArgsCanBeInterpretedByShell' capability of the 'initialize' request. If the client uses an intermediary shell to launch the application, then the client must not attempt to escape characters with special meanings for the shell. The user is fully responsible for escaping as needed and that arguments using special characters may not be portable across shells."
 				}
 			},
 			"required": [ "args", "cwd" ]
@@ -882,6 +886,10 @@
 				"supportsMemoryEvent": {
 					"type": "boolean",
 					"description": "Client supports the memory event."
+				},
+				"supportsArgsCanBeInterpretedByShell": {
+					"type": "boolean",
+					"description": "Client supports the 'argsCanBeInterpretedByShell' attribute on the 'runInTerminal' request."
 				}
 			},
 			"required": [ "adapterID" ]

index.html

@@ -86,7 +86,7 @@ <h1 class="text-center"><i class="fa fa-cogs" aria-hidden="true"></i></h1>
             <h1 class="text-center"><i class="fas fa-book" aria-hidden="true"></i></h1>
             <a href='{{ "/specification" | prepend: site.baseurl }}'><h3 class="text-center">Specification</h3></a>
             <p>
-                The latest version of the protocol specification is version 1.56.0.
+                The latest version of the protocol specification is version 1.57.0.
             </p>
             <p>
                 <a href='{{ "/changelog" | prepend: site.baseurl }}'>Change History</a>

overview.md

@@ -130,11 +130,8 @@ It is not necessary to return an explicit `false` for unsupported capabilities.
 After the debug adapter has been initialized, it is ready to accept requests for starting debugging.
 Two requests exist for this:
 - [**launch**](./specification#Requests_Launch) request: the debug adapter launches the program ("debuggee") in debug mode and then starts to communicate with it.
-Since the debug adapter is responsible for the debuggee, it should provide options for the end user to interact with the debuggee.
-Basically there are three options how the debuggee can be launched. Two of the options are available to the debug adapter via the [**RunInTerminal**](./specification#Reverse_Requests_RunInTerminal) request.
-  - the **_debug console_**: this is an interactive REPL environment which allows the user to evaluate expressions in the context of the debuggee. Program output shows up in the debug console too, but the program cannot read input through it (because of the REPL functionality).
-  - an **_integrated terminal_**: this is a terminal emulator integrated in the development tool. It supports the usual terminal control codes and supports reading program input.
-  - in an **_external terminal_**: similar to the integrated terminal, but the terminal runs outside of the development tool.
+Since the debug adapter is responsible for launching the debuggee, it should provide a mechanism for the end user to configure the debuggee. For example, passing arguments or specifying a working directory.
+   - Debug adapters are free to launch the debuggee however they choose. Typically the debuggee is launched as a child process and its output channels are connected to a client's debug console via [**output**](./specification.md#Events_Output) events. However, this has certain limitations, such as not being able to write to the terminal device directly and not being able to accept standard input. For those cases, launching the debuggee in a terminal is preferable. A debug adapter can use the the [**runInTerminal**](./specification#Reverse_Requests_RunInTerminal) request to ask the client to launch the debuggee in a terminal that is integrated into the client or in a terminal that runs outside of the client (but still configured and managed from the client).
 - [**attach**](./specification#Requests_Attach) request: the debug adapter connects to an already running program. Here the end user is responsible for launching and terminating the program.
 
 Since arguments for both requests are highly dependent on a specific debugger and debug adapter implementation, the Debug Adapter Protocol does not specify any arguments for these requests.

specification.md

@@ -796,6 +796,10 @@ This is typically used to launch the debuggee in a terminal provided by the clie
 
 This request should only be called if the client has passed the value true for the 'supportsRunInTerminalRequest' capability of the 'initialize' request.
 
+Client implementations of runInTerminal are free to run the command however they choose including issuing the command to a command line interpreter (aka 'shell'). Argument strings passed to the runInTerminal request must arrive verbatim in the command to be run. As a consequence, clients which use a shell are responsible for escaping any special shell characters in the argument strings to prevent them from being interpreted (and modified) by the shell
+
+Some users may wish to take advantage of shell processing in the argument strings. For clients which implement runInTerminal using an intermediary shell, the 'argsCanBeInterpretedByShell' property can be set to true. In this case the client is requested not to escape any special shell characters in the argument strings.
+
 ```typescript
 interface RunInTerminalRequest extends Request {
   command: 'runInTerminal';
@@ -836,6 +840,17 @@ interface RunInTerminalRequestArguments {
    * environment.
    */
   env?: { [key: string]: string | null; };
+
+  /**
+   * This property should only be set if the client has passed the value true
+   * for the 'supportsArgsCanBeInterpretedByShell' capability of the
+   * 'initialize' request. If the client uses an intermediary shell to launch
+   * the application, then the client must not attempt to escape characters with
+   * special meanings for the shell. The user is fully responsible for escaping
+   * as needed and that arguments using special characters may not be portable
+   * across shells.
+   */
+  argsCanBeInterpretedByShell?: boolean;
 }
 ```
 
@@ -956,6 +971,12 @@ interface InitializeRequestArguments {
    * Client supports the memory event.
    */
   supportsMemoryEvent?: boolean;
+
+  /**
+   * Client supports the 'argsCanBeInterpretedByShell' attribute on the
+   * 'runInTerminal' request.
+   */
+  supportsArgsCanBeInterpretedByShell?: boolean;
 }
 ```