Improve robustness

Author: pokey

README.md

@@ -44,7 +44,8 @@ from tempfile import gettempdir
 
 
 port_file_path = Path(gettempdir()) / "vscode-port"
-port = port_file_path.read_text()
+contents = json.loads(port_file_path.read_text())
+port = contents["port"]
 
 response = requests.post(
     f"http://localhost:{port}/execute-command",
@@ -57,6 +58,50 @@ response = requests.post(
 response.raise_for_status()
 ```
 
+## Troubleshooting
+
+If you're running into issues with commands interleaving with keystrokes, or the extension not responding, the server supports a command `command-server.writePort`, which will cause the extension to update the port and write a monotonically increasing counter variable to the port file.  You can run this command (via keyboard shortcut) and then wait for the file to update to ensure you're talking to the right vscode instance and to ensure that the command will not interleave with other keyboard shortcuts issued to VSCode.
+
+Here's some example code for this mode of operation. Note that this assumes
+that you have a function `actions.key` that presses the given key (eg
+[talon](https://talonvoice.com/)):
+
+```py
+    port_file_path = Path(gettempdir()) / "vscode-port"
+    original_contents = port_file_path.read_text()
+
+    # Issue command to VSCode telling it to update the port file.  Because only
+    # the active VSCode instance will accept keypresses, we can be sure that
+    # the active VSCode instance will be the one to write the port.
+    if is_mac:
+        actions.key("cmd-shift-alt-p")
+    else:
+        actions.key("ctrl-shift-alt-p")
+
+    # Wait for the VSCode instance to update the port file.  This generally
+    # happens within the first millisecond, but we give it 3 seconds just in
+    # case.
+    start_time = time.monotonic()
+    new_contents = port_file_path.read_text()
+    while original_contents == new_contents:
+        time.sleep(0.001)
+        if time.monotonic() - start_time > 3.0:
+            raise Exception("Timed out waiting for VSCode to update port file")
+        new_contents = port_file_path.read_text()
+
+    port = json.loads(new_contents)["port"]
+
+    response = requests.post(
+        f"http://localhost:{port}/execute-command",
+        json={
+            "commandId": "some-command-id",
+            "args": ["some-argument"],
+        },
+        timeout=(0.05, 3.05),
+    )
+    response.raise_for_status()
+```
+
 ## Known issues
 
 - The server won't respond until the extension is loaded.  This may be obvious,

package.json

@@ -8,7 +8,7 @@
 		"type": "git",
 		"url": "https://github.com/pokey/command-server"
 	},
-	"version": "0.2.2",
+	"version": "0.3.2",
 	"engines": {
 		"vscode": "^1.53.0"
 	},
@@ -19,7 +19,21 @@
 		"*"
 	],
 	"main": "./out/extension.js",
-	"contributes": {},
+	"contributes": {
+		"commands": [
+			{
+				"command": "command-server.writePort",
+				"title": "Write port to file"
+			}
+		],
+		"keybindings": [
+			{
+				"command": "command-server.writePort",
+				"key": "ctrl+shift+alt+p",
+				"mac": "cmd+shift+alt+p"
+			}
+		]
+	},
 	"scripts": {
 		"vscode:prepublish": "yarn run compile",
 		"compile": "tsc -p ./",

src/extension.ts

@@ -58,17 +58,6 @@ export function activate(context: vscode.ExtensionContext) {
     }
   });
 
-  setInterval(() => {
-    const path = getPortPath();
-
-    if (
-      vscode.window.state.focused &&
-      (!existsSync(path) || parseInt(readFileSync(path).toString()) !== port)
-    ) {
-      writePort();
-    }
-  }, 500);
-
   const windowStateDisposable = vscode.window.onDidChangeWindowState(
     (event) => {
       if (event.focused && port !== null) {
@@ -77,13 +66,32 @@ export function activate(context: vscode.ExtensionContext) {
     }
   );
 
+  // We keep a monotonically increasing write counter so that the port file is
+  // guaranteed to change every time we write to it.  This way a client can use
+  // the `command-server.writePort` command to request us to update the port
+  // file, and then wait for it to change.
+  var fileWriteCounter = 0;
+
   function writePort() {
     const path = getPortPath();
     console.log(`Saving port ${port} to path ${path}`);
-    writeFileSync(path, `${port}`);
+
+    const portInfo = {
+      port,
+      fileWriteCounter,
+    };
+
+    fileWriteCounter++;
+
+    writeFileSync(path, JSON.stringify(portInfo));
   }
 
-  context.subscriptions.push(windowStateDisposable, {
+  let disposable = vscode.commands.registerCommand(
+    "command-server.writePort",
+    writePort
+  );
+
+  context.subscriptions.push(disposable, windowStateDisposable, {
     dispose() {
       server.close();
     },