deskmeter/docs/README.md

# Deskmeter OS Integration

Display your current deskmeter task using GNOME Shell extension or standalone GTK window.

**Location**: `dmos/` (OS-specific components)

---

## Quick Start

### GTK Task Window (Immediate - No logout)

```bash
# Run with auto port detection
python3 dmos/task_window.py

# Make it always-on-top
wmctrl -r "Deskmeter Task" -b add,above,sticky
```

### GNOME Extension (Requires logout)

```bash
cd dmos/gnome-extension
./install.sh

# Enable extension
gnome-extensions enable deskmeter-indicator@local

# Log out and back in (required on Wayland)
```

---

## Components

### 1. GTK Task Window (`dmos/task_window.py`)

Standalone GTK4 window showing current task, always-on-top and visible on all workspaces.

**Features**:
- No window decorations (minimal UI)
- Updates every 500ms
- Workspace change detection (updates 2.2s after switch)
- Auto port detection (tries 10001, then 10000)

**Usage**:
```bash
# Auto-detect port
python3 dmos/task_window.py

# Specify port
python3 dmos/task_window.py 10001

# Or via environment
DESKMETER_PORT=10001 python3 dmos/task_window.py
```

**Window States**:
- `Loading...` - Initial state
- `work/default` - Current task path
- `offline - dmweb not running` (red) - Cannot connect
- `error - invalid API response` (orange) - Invalid JSON
- `no task` - Valid response, no task set

**Close**:
- `Alt+F4`
- `pkill -f task_window.py`

### 2. GNOME Extension (`dmos/gnome-extension/`)

Panel indicator integrated into GNOME Shell top bar.

**Features**:
- Native panel integration (left side)
- Workspace switch detection with 2.2s debounce
- Auto port detection (10001, 10000)
- Error handling (won't crash GNOME Shell)
- Auto-truncates long paths (shows `.../last/two`)

**Files**:
- `extension.js` - Main extension code
- `metadata.json` - Extension metadata (GNOME 40-49)
- `stylesheet.css` - Panel styling

**Installation**:
```bash
cd dmos/gnome-extension
./install.sh                    # First install
# OR
./update.sh                     # After code changes

# Restart GNOME Shell:
# X11: Alt+F2 → 'r' → Enter
# Wayland: Log out and back in
```

**Check Status**:
```bash
# List enabled extensions
gnome-extensions list --enabled | grep deskmeter

# View logs
journalctl --user -u org.gnome.Shell@wayland.service -f | grep deskmeter

# Debug with Looking Glass
# Alt+F2 → 'lg' → Extensions tab
```

---

## Port Auto-Detection

Both components automatically detect dmweb port:

**Priority Order**:
1. Command line argument (window only)
2. Environment variable `DESKMETER_PORT` (window only)
3. Auto-detection: tries 10001, then 10000

**Test Ports**:
```bash
curl http://localhost:10001/api/current_task
curl http://localhost:10000/api/current_task
```

**Configure Ports**:
```python
# In dmos/task_window.py (line 36)
DEFAULT_PORTS = [10001, 10000]
```

```javascript
// In dmos/gnome-extension/deskmeter-indicator@local/extension.js (line 11)
const DEFAULT_PORTS = [10001, 10000];
```

---

## Requirements

### Both Components
- dmweb Flask server running (`cd dmapp/dmweb && python3 run.py`)
- `/api/current_task` endpoint accessible

### GTK Window
- Python 3 with GTK4: `sudo apt install python3-gi gir1.2-gtk-4.0`
- wmctrl: `sudo apt install wmctrl`

### GNOME Extension
- GNOME Shell 40-49
- Works on X11 and Wayland

---

## Troubleshooting

### dmweb Not Running

```bash
# Check if dmweb is running
ps aux | grep dmweb

# Check listening ports
ss -tlnp | grep -E "(10000|10001)"

# Start dmweb
cd dmapp/dmweb
python3 run.py

# Test API
curl http://localhost:10000/api/current_task
# Expected: {"task_id":"abc12345","task_path":"work/default"}
```

### GTK Window Issues

**"offline - dmweb not running"**:
- Start dmweb (see above)

**Window not staying on top**:
```bash
wmctrl -r "Deskmeter Task" -b add,above,sticky
```

**GTK4 not found**:
```bash
sudo apt install python3-gi gir1.2-gtk-4.0
```

**Window doesn't update on workspace change**:
```bash
# Test wmctrl
wmctrl -d
# Should show workspaces with * marking current
```

### GNOME Extension Issues

**Extension not showing in panel**:
```bash
# Check if enabled
gnome-extensions list --enabled | grep deskmeter

# Re-enable
gnome-extensions enable deskmeter-indicator@local

# View errors
journalctl --user -u org.gnome.Shell@wayland.service --since "5 minutes ago" | grep -i deskmeter
```

**Shows "detecting..." forever**:
- dmweb not running on 10001 or 10000
- Start dmweb and log out/in

**Shows "offline"**:
```bash
# Test API endpoint
curl http://localhost:10000/api/current_task

# Check dmweb logs for errors
```

**Changes not appearing after update**:
- Ensure `./update.sh` ran successfully
- Must restart GNOME Shell (X11) or logout/login (Wayland)
- Check logs: `journalctl -f -o cat /usr/bin/gnome-shell`

---

## Comparison: Window vs Extension

| Feature | GTK Window | GNOME Extension |
|---------|------------|-----------------|
| Visibility | Separate window | Panel indicator |
| Screen space | Takes window space | Minimal (panel) |
| Setup | Run anytime | Requires logout |
| Restart needed | No | Yes (Wayland) |
| All workspaces | ✅ (sticky) | ✅ (panel) |
| Integration | Standalone | Native GNOME |

**Use GTK window for**:
- Quick testing
- No logout required
- Temporary usage

**Use GNOME extension for**:
- Permanent setup
- Cleaner integration
- Less screen clutter

---

## Configuration

### GTK Window Settings

Edit `dmos/task_window.py`:

```python
# Update frequency (line 37)
UPDATE_INTERVAL = 2000  # milliseconds

# Workspace check frequency (line 38)
WORKSPACE_CHECK_INTERVAL = 200  # milliseconds

# Window size (line ~50)
self.set_default_size(400, 60)  # width x height

# Font size (line ~27)
self.label.set_markup('<span font_desc="14">Loading...</span>')
```

### GNOME Extension Settings

Edit `dmos/gnome-extension/deskmeter-indicator@local/extension.js`:

```javascript
// Debounce delay (line 10)
const DEBOUNCE_DELAY = 2200; // milliseconds

// Port list (line 11)
const DEFAULT_PORTS = [10001, 10000];

// Update interval (line 12)
const UPDATE_INTERVAL = 30000; // 30 seconds
```

---

## Auto-start (Optional)

### GTK Window on Login

```bash
# Create desktop entry
cat > ~/.config/autostart/deskmeter-task-window.desktop <<EOF
[Desktop Entry]
Type=Application
Name=Deskmeter Task Window
Exec=/home/mariano/wdir/dm/dmos/task_window.py
Hidden=false
NoDisplay=false
X-GNOME-Autostart-enabled=true
EOF
```

### GNOME Extension

Enabled extensions auto-start with GNOME Shell. Just ensure it's enabled:
```bash
gnome-extensions enable deskmeter-indicator@local
```

---

## Files Structure

```
dmos/
├── gnome-extension/
│   ├── deskmeter-indicator@local/
│   │   ├── extension.js          # Main extension code
│   │   ├── metadata.json         # GNOME metadata
│   │   ├── stylesheet.css        # Panel styling
│   │   └── deskmeter-indicator@local.zip  # Packaged extension
│   ├── install.sh                # Initial installation
│   └── update.sh                 # Update after changes
└── task_window.py                # GTK4 window app
```

---

## Testing Checklist

### GTK Window
- [ ] Window appears without decorations
- [ ] Shows current task path
- [ ] Can be moved/positioned
- [ ] Closes with Alt+F4
- [ ] Updates on workspace change (~2s delay)
- [ ] Can set always-on-top with wmctrl
- [ ] Auto-detects port (check console)

### GNOME Extension
- [ ] Shows in panel (left side)
- [ ] Displays current task
- [ ] Updates on workspace switch (~2s delay)
- [ ] Doesn't crash GNOME Shell if dmweb offline
- [ ] Can disable: `gnome-extensions disable deskmeter-indicator@local`
- [ ] Truncates long paths correctly

---

## Performance

### GTK Window
- Workspace checks: 200ms interval (lightweight wmctrl)
- Task updates: 2000ms interval
- Post-switch delay: 2200ms (allows dmcore to update)
- CPU usage: ~0.1-0.2%

### GNOME Extension
- Event-driven (workspace switches)
- Periodic refresh: 30s
- Debounce delay: 2200ms
- Minimal overhead (GNOME Shell event loop)

---

## Development

### Updating Extension

```bash
cd dmos/gnome-extension

# 1. Edit extension.js, metadata.json, or stylesheet.css

# 2. Update installed version
./update.sh

# 3. Restart GNOME Shell
# X11: Alt+F2 → 'r' → Enter
# Wayland: Log out and back in

# 4. Check logs for errors
journalctl -f -o cat /usr/bin/gnome-shell | grep deskmeter
```

### Updating Window

```bash
# 1. Edit dmos/task_window.py

# 2. Kill running instance
pkill -f task_window.py

# 3. Run updated version
python3 dmos/task_window.py
```

---

## API Endpoint

Both components use the same endpoint:

**URL**: `http://localhost:{PORT}/api/current_task`

**Response**:
```json
{
  "task_id": "abc12345",
  "task_path": "work/default"
}
```

**Error Handling**:
- Connection refused → "offline"
- Invalid JSON → "error"
- Missing task_path → "no task"

---

## Need Help?

1. **Start dmweb**: `cd dmapp/dmweb && python3 run.py`
2. **Test API**: `curl http://localhost:10000/api/current_task`
3. **Try window first**: `python3 dmos/task_window.py` (no logout)
4. **Check logs**: `journalctl` for extension, console for window
5. **Verify ports**: `ss -tlnp | grep -E "(10000|10001)"`

---

**Ready to test!** Start with the GTK window for immediate feedback, then try the extension for permanent integration.