51.5-354 updates

docs/PORT_DETECTION_README.md

@@ -0,0 +1,148 @@
+# Port Auto-Detection
+
+Both the task window and GNOME extension now automatically detect which port dmweb is running on.
+
+## How It Works
+
+### Automatic Detection
+
+Both apps try ports in this order:
+1. **10001** - Worktree instance (tried first)
+2. **10000** - Default instance (fallback)
+
+The first port that responds successfully is used.
+
+### Task Window (task_window.py)
+
+**Auto-detection** (recommended):
+```bash
+./task_window.py
+# OR
+python3 task_window.py
+```
+
+Output will show:
+```
+Found dmweb API on port 10001
+API URL: http://localhost:10001/api/current_task
+```
+
+**Manual port specification:**
+```bash
+# Specify custom port as argument
+python3 task_window.py 10001
+python3 task_window.py 10000
+python3 task_window.py 9999
+```
+
+**Environment variable:**
+```bash
+# Set port via environment variable
+DESKMETER_PORT=10001 python3 task_window.py
+```
+
+Priority order: Command line arg > Environment variable > Auto-detection
+
+### GNOME Extension
+
+The extension automatically tries ports 10001 and 10000 when it starts.
+
+You'll see "detecting..." in the panel while it searches, then it will show:
+- The task name when port is found
+- "offline" if no port responds
+
+## Testing
+
+### Test with curl
+
+```bash
+# Check which ports are running
+curl http://localhost:10000/api/current_task  # default
+curl http://localhost:10001/api/current_task  # worktree
+```
+
+### Test task window
+
+```bash
+# Auto-detect (will find port 10001 first)
+python3 task_window.py
+
+# Force specific port
+python3 task_window.py 10000
+```
+
+Watch the console output to see which port was detected/used.
+
+## Configuration
+
+### Changing Port Priority
+
+Edit `task_window.py` line 16:
+```python
+DEFAULT_PORTS = [10001, 10000]  # Try in this order
+```
+
+Edit `gnome-extension/deskmeter-indicator@local/extension.js` line 11:
+```javascript
+const DEFAULT_PORTS = [10001, 10000];  // Try in this order
+```
+
+### Adding More Ports
+
+```python
+# In task_window.py
+DEFAULT_PORTS = [10001, 10000, 9999, 8080]
+```
+
+```javascript
+// In extension.js
+const DEFAULT_PORTS = [10001, 10000, 9999, 8080];
+```
+
+## Troubleshooting
+
+### Window shows "offline - dmweb not running"
+
+```bash
+# Check if any dmweb is running
+ps aux | grep dmweb
+
+# Check what ports are listening
+ss -tlnp | grep -E "(10000|10001)"
+
+# Test ports manually
+curl http://localhost:10000/api/current_task
+curl http://localhost:10001/api/current_task
+```
+
+### Extension shows "detecting..." forever
+
+The extension couldn't connect to any port. Check:
+
+```bash
+# View extension logs
+journalctl --user -u org.gnome.Shell@wayland.service -f | grep deskmeter
+```
+
+Common issues:
+- dmweb not running
+- Firewall blocking localhost connections
+- Wrong API endpoint (make sure `/api/current_task` exists)
+
+### Force specific port for extension
+
+Edit `~/.local/share/gnome-shell/extensions/deskmeter-indicator@local/extension.js` line 11:
+
+```javascript
+// Only try one port
+const DEFAULT_PORTS = [10001];
+```
+
+Then log out and back in to reload the extension.
+
+## Summary
+
+✅ **Task window**: Auto-detects ports 10001, 10000 (can override with arg or env var)
+✅ **GNOME extension**: Auto-detects ports 10001, 10000
+✅ **Worktree-first**: Both try port 10001 before 10000
+✅ **Configurable**: Easy to change port list or add more ports