Merge pull request #4 from jtpio/discover-execute-commands

Discover and execute JupyterLab commands

Author: Zsailer

README.md

@@ -10,15 +10,12 @@ for the frontend extension.
 
 ## Features
 
-- **Document Management**: Open documents in JupyterLab with various layout modes
-- **Markdown Preview**: Open markdown files in rendered preview mode
-- **Notebook Operations**: Clear outputs and show diffs for notebooks
-- **Jupyter AI Integration**: Tools available for use with Jupyter AI
+- **Command Discovery**: List all available JupyterLab commands with their metadata
+- **Command Execution**: Execute any JupyterLab command programmatically from Python
 
 ## Requirements
 
-- JupyterLab >= 4.0.0
-- jupyter-ai (for AI toolkit functionality)
+- JupyterLab >= 4.5.0a3
 
 ## Install
 
@@ -30,47 +27,29 @@ pip install jupyterlab_commands_toolkit
 
 ## Usage
 
-### With Jupyter AI
-
-The extension provides a toolkit for Jupyter AI with the following tools:
-
-1. **open_document_tool**: Open documents in JupyterLab with various layout modes
-2. **open_markdown_preview_tool**: Open markdown files in rendered preview mode  
-3. **clear_notebook_outputs_tool**: Clear all outputs in the active notebook
-4. **show_notebook_diff_tool**: Show git diff for the current notebook using nbdime
+Use the toolkit to execute any JupyterLab command from Python:
 
 ```python
-# Access the AI toolkit
-from jupyterlab_commands_toolkit import ai_toolkit
+import asyncio
+from jupyterlab_commands_toolkit.tools import execute_command, list_all_commands
 
-# The toolkit is automatically available to Jupyter AI when installed
-```
+# Execute a command (requires running in an async context)
+async def main():
+    # List all available commands
+    commands = await list_all_commands()
 
-### Direct Usage
+    # Toggle the file browser
+    result = await execute_command("filebrowser:toggle-main")
 
-You can also use the commands directly:
-
-```python
-from jupyterlab_commands_toolkit.tools import (
-    open_document,
-    open_markdown_file_in_preview_mode,
-    clear_all_outputs_in_notebook,
-    show_diff_of_current_notebook
-)
+    # Run notebook cells
+    result = await execute_command("notebook:run-all-cells")
 
-# Open a document
-open_document("notebook.ipynb", mode="split-right")
-
-# Open markdown in preview
-open_markdown_file_in_preview_mode("README.md")
-
-# Clear notebook outputs
-clear_all_outputs_in_notebook(True)
-
-# Show notebook diff
-show_diff_of_current_notebook(True)
+# Run in JupyterLab environment
+asyncio.run(main())
 ```
 
+For a full list of available commands in JupyterLab, refer to the [JupyterLab Command Registry documentation](https://jupyterlab.readthedocs.io/en/latest/user/commands.html#commands-list).
+
 ## Uninstall
 
 To remove the extension, execute:

jupyterlab_commands_toolkit/__init__.py

@@ -5,34 +5,73 @@
     # in editable mode with pip. It is highly recommended to install
     # the package from a stable release or in editable mode: https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs
     import warnings
-    warnings.warn("Importing 'jupyterlab_commands_toolkit' outside a proper installation.")
+
+    warnings.warn(
+        "Importing 'jupyterlab_commands_toolkit' outside a proper installation."
+    )
     __version__ = "dev"
 
 import pathlib
 
 from jupyter_server.serverapp import ServerApp
-from .toolkit import toolkit
 
-# Export the AI toolkit for jupyter-ai integration
-try:
-    from .toolkit import toolkit as ai_toolkit
-except ImportError:
-    # If jupyter-ai is not available, the AI toolkit won't be available
-    toolkit = None
 
 def _jupyter_labextension_paths():
-    return [{
-        "src": "labextension",
-        "dest": "jupyterlab-commands-toolkit"
-    }]
+    return [{"src": "labextension", "dest": "jupyterlab-commands-toolkit"}]
 
 
 def _jupyter_server_extension_points():
-    return [{
-        "module": "jupyterlab_commands_toolkit"
-    }]
+    return [{"module": "jupyterlab_commands_toolkit"}]
+
 
 def _load_jupyter_server_extension(serverapp: ServerApp):
-    schema_path = pathlib.Path(__file__).parent / "events" / "jupyterlab-command.yml"
-    serverapp.event_logger.register_event_schema(schema_path)
-    serverapp.log.info("jupyterlab_commands_toolkit extension loaded.")
+    command_schema_path = (
+        pathlib.Path(__file__).parent / "events" / "jupyterlab-command.yml"
+    )
+    serverapp.event_logger.register_event_schema(command_schema_path)
+
+    result_schema_path = (
+        pathlib.Path(__file__).parent / "events" / "jupyterlab-command-result.yml"
+    )
+    serverapp.event_logger.register_event_schema(result_schema_path)
+
+    async def command_result_listener(logger, schema_id: str, data: dict) -> None:
+        """
+        Handle command result events from the frontend.
+
+        This listener receives the results of JupyterLab commands that were
+        executed in the frontend and processes them accordingly.
+        """
+        from .tools import handle_command_result
+
+        try:
+            request_id = data.get("requestId", "unknown")
+            success = data.get("success", False)
+            result = data.get("result")
+            error = data.get("error")
+
+            serverapp.log.info(
+                f"Received command result for request {request_id}: success={success}"
+            )
+
+            if success:
+                if result is not None:
+                    serverapp.log.debug(f"Command result: {result}")
+            else:
+                serverapp.log.warning(f"Command failed: {error}")
+
+            handle_command_result(data)
+
+        except Exception as e:
+            serverapp.log.error(f"Error processing command result: {e}")
+
+    result_schema_id = (
+        "https://events.jupyter.org/jupyterlab_command_toolkit/lab_command_result/v1"
+    )
+    serverapp.event_logger.add_listener(
+        schema_id=result_schema_id, listener=command_result_listener
+    )
+
+    serverapp.log.info(
+        "jupyterlab_commands_toolkit extension loaded with bidirectional event communication."
+    )

jupyterlab_commands_toolkit/events/jupyterlab-command-result.yml

@@ -0,0 +1,22 @@
+"$id": https://events.jupyter.org/jupyterlab_command_toolkit/lab_command_result/v1
+version: 1
+title: A JupyterLab Command Execution Result
+personal-data: true
+description: |
+  Result of a JupyterLab Command execution
+type: object
+required:
+  - requestId
+  - success
+properties:
+  requestId:
+    type: string
+    description: The unique identifier for the command request
+  success:
+    type: boolean
+    description: Whether the command executed successfully
+  result:
+    description: The result data from the command execution
+  error:
+    type: string
+    description: Error message if the command failed