cursorless everywhere: add the ability to asynchronous values from Python (#2649)

## Checklist
NB: haven't tested this yet
- [ ] I have added
[tests](https://www.cursorless.org/docs/contributing/test-case-recorder/)
- [ ] I have updated the
[docs](https://github.com/cursorless-dev/cursorless/tree/main/docs) and
[cheatsheet](https://github.com/cursorless-dev/cursorless/tree/main/cursorless-talon/src/cheatsheet)
- [ ] I have not broken the cheatsheet
- [x] Test format action
- [x] Test homophones action

---------

Co-authored-by: Andreas Arvidsson <[email protected]>

Author: phillco

cursorless-everywhere-talon/cursorless_everywhere_talon.py

@@ -1,37 +1,43 @@
-from typing import TypedDict
+import json
+from typing import Any
 
-from talon import Module
+from talon import Context, Module, actions
 
+from .cursorless_everywhere_types import EditorEdit, EditorState, SelectionOffsets
 
-class SelectionOffsets(TypedDict):
-    anchor: int
-    active: int
-
-
-class EditorState(TypedDict):
-    text: str
-    selections: list[SelectionOffsets]
-
-
-class EditorChange(TypedDict):
-    text: str
-    rangeOffset: int
-    rangeLength: int
+mod = Module()
 
+mod.tag("cursorless_everywhere_talon", desc="Enable cursorless everywhere in Talon")
 
-class EditorEdit(TypedDict):
-    # The new document content after the edit
-    text: str
+ctx = Context()
+ctx.matches = r"""
+tag: user.cursorless_everywhere_talon
+"""
 
-    # A list of changes that were made to the document. If you can not handle
-    # this, you can ignore it and just replace the entire document with the
-    # value of the `text` field above.
-    changes: list[EditorChange]
 
+@ctx.action_class("user")
+class UserActions:
+    def private_cursorless_run_rpc_command_and_wait(
+        command_id: str,  # pyright: ignore [reportGeneralTypeIssues]
+        arg1: Any = None,
+        arg2: Any = None,
+    ):
+        actions.user.private_cursorless_talonjs_run_and_wait(command_id, arg1, arg2)
 
-mod = Module()
+    def private_cursorless_run_rpc_command_no_wait(
+        command_id: str,  # pyright: ignore [reportGeneralTypeIssues]
+        arg1: Any = None,
+        arg2: Any = None,
+    ):
+        actions.user.private_cursorless_talonjs_run_no_wait(command_id, arg1, arg2)
 
-mod.tag("cursorless_everywhere_talon", desc="Enable cursorless everywhere in Talon")
+    def private_cursorless_run_rpc_command_get(
+        command_id: str,  # pyright: ignore [reportGeneralTypeIssues]
+        arg1: Any = None,
+        arg2: Any = None,
+    ) -> Any:
+        actions.user.private_cursorless_talonjs_run_and_wait(command_id, arg1, arg2)
+        return json.loads(actions.user.private_cursorless_talonjs_get_response_json())
 
 
 @mod.action_class
@@ -48,3 +54,20 @@ def cursorless_everywhere_edit_text(
         edit: EditorEdit,  # pyright: ignore [reportGeneralTypeIssues]
     ):
         """Edit focused element text"""
+
+    def private_cursorless_talonjs_run_and_wait(
+        command_id: str,  # pyright: ignore [reportGeneralTypeIssues]
+        arg1: Any = None,
+        arg2: Any = None,
+    ):
+        """Executes a Cursorless command, waits for its completion, but does not return the response"""
+
+    def private_cursorless_talonjs_run_no_wait(
+        command_id: str,  # pyright: ignore [reportGeneralTypeIssues]
+        arg1: Any = None,
+        arg2: Any = None,
+    ):
+        """Executes a Cursorless command, but does not wait for it to finish, nor return the response"""
+
+    def private_cursorless_talonjs_get_response_json() -> str:
+        """Returns the response from the last Cursorless command"""

cursorless-everywhere-talon/cursorless_everywhere_types.py

@@ -0,0 +1,27 @@
+from typing import TypedDict
+
+
+class SelectionOffsets(TypedDict):
+    anchor: int
+    active: int
+
+
+class EditorState(TypedDict):
+    text: str
+    selections: list[SelectionOffsets]
+
+
+class EditorChange(TypedDict):
+    text: str
+    rangeOffset: int
+    rangeLength: int
+
+
+class EditorEdit(TypedDict):
+    # The new document content after the edit
+    text: str
+
+    # A list of changes that were made to the document. If you can not handle
+    # this, you can ignore it and just replace the entire document with the
+    # value of the `text` field above.
+    changes: list[EditorChange]

packages/cursorless-everywhere-talon-core/src/registerCommands.ts

@@ -11,19 +11,28 @@ export function registerCommands(
   const ctx = new talon.Context();
   ctx.matches = "tag: user.cursorless_everywhere_talon";
 
+  let lastCommandResponse: unknown = null;
+
   ctx.action_class("user", {
-    private_cursorless_run_rpc_command_no_wait(
+    async private_cursorless_talonjs_run_and_wait(
       commandId: string,
       command: unknown,
-    ): void {
-      void runCommand(commandId, command);
+    ): Promise<void> {
+      lastCommandResponse = await runCommand(commandId, command);
     },
 
-    async private_cursorless_run_rpc_command_get(
+    private_cursorless_talonjs_run_no_wait(
       commandId: string,
       command: unknown,
-    ): Promise<unknown> {
-      return await runCommand(commandId, command);
+    ): void {
+      void runCommand(commandId, command);
+      lastCommandResponse = null;
+    },
+
+    private_cursorless_talonjs_get_response_json(): string {
+      // Talon JS doesn't convert JS objects to Python objects, and also doesn't provide
+      // a way to inspect types, so just serialize the response to JSON
+      return JSON.stringify(lastCommandResponse);
     },
   });
 

packages/cursorless-everywhere-talon-core/src/types/talon.types.ts

@@ -21,14 +21,41 @@ export interface TalonActions {
 }
 
 export interface TalonContextActions {
-  private_cursorless_run_rpc_command_no_wait(
+  /**
+   * Executes an RPC command and waits for the result.
+   * This function is useful when the result of the command is needed
+   * immediately after execution.
+   *
+   * @param commandId - The identifier of the command to be executed.
+   * @param command - The command object containing necessary parameters.
+   * @returns A Promise that resolves with the result of the command execution.
+   */
+  private_cursorless_talonjs_run_and_wait(
     commandId: string,
     command: unknown,
-  ): void;
-  private_cursorless_run_rpc_command_get(
+  ): Promise<void>;
+  /**
+   * Executes an RPC command without waiting for the result.
+   * This function is useful for fire-and-forget operations where
+   * the result is not immediately needed.
+   *
+   * @param commandId - The identifier of the command to be executed.
+   * @param command - The command object containing necessary parameters.
+   */
+  private_cursorless_talonjs_run_no_wait(
     commandId: string,
     command: unknown,
-  ): Promise<unknown>;
+  ): void;
+  /**
+   * Retrieves the response json from the last RPC command execution.
+   *
+   * This is useful because TalonJS doesn't have a way to read the responses from promises,
+   * but it does wait for them, so we store the response in a global variable and let it be
+   * read by this action.
+   *
+   * @returns The most recent response from an RPC command (JSON stringified).
+   */
+  private_cursorless_talonjs_get_response_json(): string;
 }
 
 export interface TalonContext {

packages/cursorless-everywhere-talon-e2e/src/quickjsTest.ts

@@ -74,7 +74,7 @@ function runAction(action: ActionDescriptor) {
   };
   return talonMock
     .getTestHelpers()
-    .contextActions.private_cursorless_run_rpc_command_get(
+    .contextActions.private_cursorless_talonjs_run_and_wait(
       "cursorless.command",
       command,
     );