feat: implement complete Debrief WebSocket Bridge with plot manipulation and comprehensive testing

.claude/settings.local.json

@@ -37,7 +37,9 @@
       "Bash(docker rm:*)",
       "Bash(flyctl apps:*)",
       "Bash(flyctl status:*)",
-      "Bash(flyctl:*)"
+      "Bash(flyctl:*)",
+      "Bash(npm run:*)",
+      "Bash(python:*)"
     ]
   },
   "outputStyle": "default"

.devcontainer/devcontainer.json

@@ -6,7 +6,9 @@
         "explorer.openEditors.visible": 0,
         "workbench.startupEditor": "none"
       },
-      "extensions": []
+      "extensions": [
+        "ms-python.python"
+      ]
     }
   },
   "workspaceFolder": "/workspaces/codespace-extension"

.gitignore

@@ -137,3 +137,26 @@ dist
 # Vite logs files
 vite.config.js.timestamp-*
 vite.config.ts.timestamp-*
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST

.vscode/launch.json

@@ -7,7 +7,7 @@
             "request": "launch",
             "args": [
                 "--extensionDevelopmentPath=${workspaceFolder}",
-                "--folder-uri=${workspaceFolder}/workspace"
+                "--folder-uri=file://${workspaceFolder}/workspace"
             ],
             "outFiles": [
                 "${workspaceFolder}/out/**/*.js"

.vscode/settings.json

@@ -18,5 +18,8 @@
     "titleBar.inactiveBackground": "#d7d16199",
     "titleBar.inactiveForeground": "#15202b99"
   },
-  "peacock.color": "#d7d161"
+  "peacock.color": "#d7d161",
+  "debug.focusWindowOnBreak": false,
+  "debug.openDebug": "neverOpen",
+  "workbench.view.debug.alwaysOpenWelcomeView": false
 }

CLAUDE.md

@@ -0,0 +1,129 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+- `npm install` - Install dependencies
+- `npm run compile` - Compile TypeScript to JavaScript
+- `npm run watch` - Watch mode compilation for development
+- `npm run vscode:prepublish` - Prepare for publishing (runs compile)
+
+## Testing
+
+### Extension Testing
+- Press `F5` in VS Code to launch Extension Development Host
+- Or run "Debug: Start Debugging" from Command Palette
+
+### WebSocket Bridge Testing
+Navigate to `workspace/tests/` and run:
+- `pip install -r requirements.txt` - Install Python test dependencies
+- `python test_integration.py` - Run comprehensive integration tests
+- `python test_notify_command.py` - Test VS Code notifications from Python
+- `python test_optional_filename.py` - Test optional filename functionality
+- `python test_plot_api.py` - Test full plot manipulation API with optional filename support
+
+## Architecture
+
+### Core Components
+
+**VS Code Extension (`src/extension.ts`)**
+- Main extension entry point with activate/deactivate lifecycle
+- Registers custom Plot JSON editor and GeoJSON outline view
+- Starts WebSocket server on port 60123 for Python integration
+
+**WebSocket Bridge (`src/debriefWebSocketServer.ts`)**
+- WebSocket server runs inside VS Code extension on localhost:60123
+- Handles JSON command protocol for Python-to-VS Code communication
+- Supports plot manipulation commands with **optional filename parameters**
+- Automatically starts on extension activation and stops on deactivation
+
+**Plot JSON Editor (`src/plotJsonEditor.ts`)**
+- Custom webview editor for `.plot.json` files
+- Displays GeoJSON data on Leaflet map with feature selection
+- Integrates with outline view for feature navigation
+
+**Custom Outline (`src/customOutlineTreeProvider.ts`)**
+- Tree view showing GeoJSON features from active plot files
+- Syncs with Plot JSON editor for feature highlighting and selection
+
+### Key Design Patterns
+
+- **WebSocket Integration**: Python scripts can interact with VS Code through WebSocket bridge
+- **Webview Communication**: Plot editor uses VS Code webview API with message passing
+- **Document Syncing**: Outline view automatically updates when plot files change
+- **Extension Lifecycle**: WebSocket server managed through extension activation/deactivation
+
+### File Structure
+
+```
+src/
+├── extension.ts                    # Main extension entry point
+├── debriefWebSocketServer.ts      # WebSocket bridge for Python integration
+├── plotJsonEditor.ts              # Custom editor for .plot.json files
+├── customOutlineTreeProvider.ts   # Tree view for GeoJSON features
+└── geoJsonOutlineProvider.ts      # Base outline provider
+```
+
+### WebSocket Protocol
+
+Messages are JSON-based with this structure:
+```json
+{
+  "command": "notify",
+  "params": {
+    "message": "Hello from Python!"
+  }
+}
+```
+
+**Optional Filename Support**: Most plot commands now support optional filename parameters:
+```json
+{
+  "command": "get_feature_collection",
+  "params": {}
+}
+```
+
+When filename is omitted:
+- **Single plot open**: Command executes automatically
+- **Multiple plots open**: Returns `MULTIPLE_PLOTS` error with available options
+- **No plots open**: Returns clear error message
+
+Responses:
+```json
+{
+  "result": null
+}
+```
+
+Error format:
+```json
+{
+  "error": {
+    "message": "Error description",
+    "code": 400
+  }
+}
+```
+
+Multiple plots error format:
+```json
+{
+  "error": {
+    "message": "Multiple plots open, please specify filename",
+    "code": "MULTIPLE_PLOTS",
+    "available_plots": [
+      {"filename": "mission1.plot.json", "title": "Mission 1"},
+      {"filename": "mission2.plot.json", "title": "Mission 2"}
+    ]
+  }
+}
+```
+
+## Key Integration Points
+
+- **Python Testing**: Use `workspace/tests/debrief_api.py` for WebSocket integration
+- **Plot Files**: `.plot.json` files in workspace/ for testing custom editor
+- **Port Configuration**: WebSocket bridge uses fixed port 60123
+- **Feature Selection**: Outline view and plot editor are bidirectionally linked

Dockerfile

@@ -4,15 +4,21 @@ FROM codercom/code-server:latest
 # Set the working directory
 WORKDIR /home/coder
 
-# Install Node.js and npm (required for VS Code extension builds)
+# Install Node.js, npm, and Python (required for VS Code extension builds and testing)
 USER root
 RUN apt-get update && apt-get install -y \
     curl \
+    python3 \
+    python3-pip \
+    python3-venv \
     && curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
     && apt-get install -y nodejs \
     && apt-get clean \
     && rm -rf /var/lib/apt/lists/*
 
+# Create symlink for python command
+RUN ln -s /usr/bin/python3 /usr/bin/python
+
 # Switch back to coder user
 USER coder
 
@@ -37,11 +43,23 @@ RUN vsce package --out extension.vsix
 # Install the extension in code-server
 RUN code-server --install-extension ./extension.vsix
 
+# Install Python extension for code-server
+RUN code-server --install-extension ms-python.python
+
 # Copy workspace files to the workspace directory
 RUN cp -r workspace/* /home/coder/workspace/
 
+# Create VS Code settings to use virtual environment Python
+RUN mkdir -p /home/coder/workspace/.vscode && \
+    echo '{\n  "python.defaultInterpreterPath": "/home/coder/workspace/tests/venv/bin/python"\n}' > /home/coder/workspace/.vscode/settings.json
+
+# Create and activate virtual environment, then install Python test requirements
+RUN cd /home/coder/workspace/tests && \
+    python3 -m venv venv && \
+    venv/bin/pip install -r requirements.txt
+
 # Create a simple README for the workspace
-RUN echo "# Debrief Extension Preview\n\nThis is a preview environment for the Debrief VS Code extension.\n\n## Sample Files\n\n- \`*.rep\` files: Debrief replay files\n- \`*.plot.json\` files: Plot data visualization files\n\n## Usage\n\n1. Open any .plot.json file to see the custom Plot JSON editor\n2. Use Ctrl+Shift+P to access the 'Hello World' command\n3. Check the 'Hello World' view in the Explorer panel\n\nThis environment includes sample data files for testing the extension features." > /home/coder/workspace/README.md
+RUN echo "# Debrief Extension Preview\n\nThis is a preview environment for the Debrief VS Code extension.\n\n## Sample Files\n\n- \`*.rep\` files: Debrief replay files\n- \`*.plot.json\` files: Plot data visualization files\n\n## Usage\n\n1. Open any .plot.json file to see the custom Plot JSON editor\n2. Use Ctrl+Shift+P to access the 'Hello World' command\n3. Check the 'Hello World' view in the Explorer panel\n\n## Python Scripts\n\nPython scripts can be run directly with F5 or using the Run button in VS Code. The environment is pre-configured to use the virtual environment automatically.\n\nAlternatively, you can run scripts manually:\n\n\`\`\`bash\ncd tests\n./venv/bin/python move_point_north_simple.py\n\`\`\`\n\nThis environment includes sample data files for testing the extension features." > /home/coder/workspace/README.md
 
 # Set workspace as the default directory
 WORKDIR /home/coder/workspace