rosett-ai 1.3.3

data/doc/DESKTOP.md

@@ -0,0 +1,447 @@
+# Desktop Integration
+
+raictl provides Linux desktop integration through a D-Bus service and
+GTK4/Adwaita GUI application. The architecture separates the IPC service
+(always running) from the GUI (launched on demand).
+
+## Architecture Overview
+
+```mermaid
+graph TB
+    subgraph User["User Interaction"]
+        TERM["Terminal<br/>bin/raictl compile"]
+        GTK4["GTK4 App<br/>bin/raictl desktop gtk4"]
+        KDE["KDE KCM<br/>(future)"]
+    end
+
+    subgraph DBUS["D-Bus Session Bus"]
+        BUS["be.neatnerds.rosettai"]
+    end
+
+    subgraph Service["D-Bus Service (bin/raictl dbus start)"]
+        MGR["ManagerInterface"]
+        FOCUS["FocusMonitorInterface"]
+        SNI["StatusNotifierInterface"]
+    end
+
+    subgraph Core["rosett-ai Core"]
+        COMP["Compiler"]
+        CONFIG["Configuration"]
+        ENGINES["Engine Registry"]
+    end
+
+    subgraph System["System"]
+        COMPOSITOR["Compositor<br/>(GNOME, KDE, i3, Hyprland, X11)"]
+    end
+
+    TERM --> Core
+    GTK4 -->|D-Bus IPC| BUS
+    KDE -->|D-Bus IPC| BUS
+    BUS --> Service
+    Service --> Core
+    FOCUS --> COMPOSITOR
+```
+
+## D-Bus Service
+
+### Starting the Service
+
+```bash
+# Start in foreground
+bin/raictl dbus start
+
+# The service registers on the session bus as:
+#   Bus name:    be.neatnerds.rosettai
+#   Object path: /be/neatnerds/rosett-ai
+```
+
+### Interfaces
+
+```mermaid
+classDiagram
+    class Service {
+        +run()
+        -setup_manager_interface()
+        -setup_focus_monitor()
+        -export_status_notifier()
+        -export_interfaces()
+    }
+
+    class ManagerInterface {
+        <<D-Bus Interface>>
+        +Compile(engine: s) s
+        +SwitchContext(context_name: s)
+        +GetStatus() a_sv_
+        +Shutdown()
+        +SetConfig(key: s, value: s) s
+        signal ContextChanged(context_name: s)
+        property Version: s [read]
+    }
+
+    class FocusMonitorInterface {
+        <<D-Bus Interface>>
+        +GetCurrentFocus() (ss)
+        signal FocusChanged(app_id: s, title: s)
+    }
+
+    class StatusNotifierInterface {
+        <<D-Bus Interface: org.kde.StatusNotifierItem>>
+        +Activate(x: i, y: i)
+        +ContextMenu(x: i, y: i)
+        signal NewStatus(status: s)
+        signal NewTitle()
+        property Id: s [read]
+        property Category: s [read]
+        property Status: s [read]
+        property Title: s [read]
+        property IconName: s [read]
+    }
+
+    Service --> ManagerInterface
+    Service --> FocusMonitorInterface
+    Service --> StatusNotifierInterface
+```
+
+### D-Bus Method Reference
+
+| Interface | Method | Arguments | Returns | Description |
+|-----------|--------|-----------|---------|-------------|
+| Manager | `Compile` | `engine: s` | `s` (result) | Run compilation for specified engine |
+| Manager | `SwitchContext` | `context_name: s` | -- | Switch AI context |
+| Manager | `GetStatus` | -- | `a{sv}` (dict) | Service status dictionary |
+| Manager | `Shutdown` | -- | -- | Gracefully stop the D-Bus service |
+| Manager | `SetConfig` | `key: s, value: s` | `s` (result) | Update rai config value |
+| FocusMonitor | `GetCurrentFocus` | -- | `(ss)` (tuple) | Current (app_id, window_title) |
+| StatusNotifier | `Activate` | `x: i, y: i` | -- | Primary activation (click) |
+| StatusNotifier | `ContextMenu` | `x: i, y: i` | -- | Context menu activation |
+
+### D-Bus Signals
+
+| Interface | Signal | Arguments | Description |
+|-----------|--------|-----------|-------------|
+| Manager | `ContextChanged` | `context_name: s` | Emitted after context switch |
+| FocusMonitor | `FocusChanged` | `app_id: s, title: s` | Emitted on active window change |
+| StatusNotifier | `NewStatus` | `status: s` | Emitted when tray status changes |
+| StatusNotifier | `NewTitle` | -- | Emitted when tooltip title changes |
+
+### Stopping the Service
+
+```bash
+# Stop a running D-Bus service
+bin/raictl dbus stop
+
+# The stop command connects to the session bus and calls Shutdown
+```
+
+## Focus Monitoring
+
+### Compositor Detection
+
+```mermaid
+flowchart TD
+    A[CompositorDetector.detect] --> B{XDG_CURRENT_DESKTOP?}
+    B -->|GNOME| C[return :gnome]
+    B -->|KDE| D[return :kde]
+    B -->|Not set| E{WAYLAND_DISPLAY?}
+    E -->|Yes| F{HYPRLAND_INSTANCE_SIGNATURE?}
+    F -->|Yes| G[return :hyprland]
+    F -->|No| H{SWAYSOCK?}
+    H -->|Yes| I[return :sway]
+    H -->|No| J{I3SOCK?}
+    J -->|Yes| K[return :i3]
+    J -->|No| L[return :unknown]
+    E -->|No| M{DISPLAY?}
+    M -->|Yes| N[return :x11]
+    M -->|No| O[return :unknown]
+```
+
+### Focus Adapter Selection
+
+```mermaid
+flowchart LR
+    DET[CompositorDetector] --> |:gnome| GA[GnomeAdapter<br/>D-Bus org.gnome.Shell]
+    DET --> |:kde| KA[KwinAdapter<br/>D-Bus org.kde.KWin]
+    DET --> |:i3| IA[I3Adapter<br/>i3-msg -t get_tree]
+    DET --> |:hyprland| HA[HyprlandAdapter<br/>hyprctl activewindow]
+    DET --> |:x11| XA[X11Adapter<br/>xdotool getactivewindow]
+```
+
+### Focus Adapter Hierarchy
+
+```mermaid
+classDiagram
+    class Base {
+        <<abstract>>
+        +current_focus() Array
+        +poll_interval() Integer
+        #parse_focus(raw) Array
+    }
+
+    class GnomeAdapter {
+        D-Bus: org.gnome.Shell
+        +current_focus() [app_id, title]
+    }
+
+    class KwinAdapter {
+        D-Bus: org.kde.KWin
+        +current_focus() [app_id, title]
+    }
+
+    class I3Adapter {
+        CLI: i3-msg -t get_tree
+        +current_focus() [app_id, title]
+    }
+
+    class HyprlandAdapter {
+        CLI: hyprctl activewindow -j
+        +current_focus() [app_id, title]
+    }
+
+    class X11Adapter {
+        CLI: xdotool getactivewindow
+        +current_focus() [app_id, title]
+    }
+
+    Base <|-- GnomeAdapter
+    Base <|-- KwinAdapter
+    Base <|-- I3Adapter
+    Base <|-- HyprlandAdapter
+    Base <|-- X11Adapter
+```
+
+## GTK4 Application
+
+### Safety Architecture
+
+The GTK4 app is designed to **never crash** on user interaction. Every event
+handler is wrapped in a safety layer.
+
+```mermaid
+flowchart TB
+    subgraph Principle1["Principle 1: Wrap All Handlers"]
+        P1["Every signal_connect callback<br/>passes through safe_action()"]
+    end
+
+    subgraph Principle2["Principle 2: Safe D-Bus Client"]
+        P2["DbusClient never raises<br/>Returns SAFE_STATUS, SAFE_FOCUS<br/>on any error"]
+    end
+
+    subgraph Principle3["Principle 3: Graceful Degradation"]
+        P3["defined?(Adw::PreferencesDialog)<br/>falls back to PreferencesWindow<br/>falls back to nil"]
+    end
+
+    subgraph Principle4["Principle 4: Error Dialogs"]
+        P4["Errors shown as Adw::MessageDialog<br/>App continues running"]
+    end
+
+    Principle1 --> Principle2
+    Principle2 --> Principle3
+    Principle3 --> Principle4
+```
+
+### Application Structure
+
+```mermaid
+classDiagram
+    class Gtk4App {
+        -application Adw::Application
+        -window Adw::ApplicationWindow
+        -dbus_client DbusClient
+        -toast_overlay Adw::ToastOverlay
+        +run(argv) Integer
+        -safe_action(name)
+        -on_activate()
+        -show_preferences()
+        -show_about()
+        -on_compile_clicked()
+        -show_toast(message)
+        -show_error_dialog(title, message)
+    }
+
+    class Gtk4Preferences {
+        -parent Adw::Window
+        -dbus_client DbusClient
+        -dialog Adw::PreferencesDialog
+        +build() PreferencesDialog
+        +present()
+        -safe_callback(name)
+        -create_preferences_dialog()
+        -add_general_page()
+        -add_context_page()
+        -add_advanced_page()
+    }
+
+    class DbusClient {
+        -bus DBus::SessionBus
+        -connected Boolean
+        +connect() Boolean
+        +service_available?() Boolean
+        +status() Hash
+        +compile() String
+        +current_focus() Array
+        +set_config(key, value) Boolean
+        +on_focus_changed(block)
+        SAFE_STATUS Hash
+        SAFE_FOCUS Array
+        SAFE_COMPILE_RESULT String
+    }
+
+    class GuiLogger {
+        -enabled Boolean
+        -log_file String
+        -level Symbol
+        -mutex Mutex
+        +action(name, &block)
+        +action_start(name)
+        +action_end(name)
+        +callback(name)
+        +widget_event(type, event)
+        +dbus_call(operation)
+        +error(message, exception)
+    }
+
+    Gtk4App --> DbusClient
+    Gtk4App --> Gtk4Preferences
+    Gtk4App --> GuiLogger
+    Gtk4Preferences --> DbusClient
+    Gtk4Preferences --> GuiLogger
+```
+
+### safe_action() Flow
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant GTK as Gtk4App
+    participant Logger as GuiLogger
+    participant Logic as Business Logic
+    participant Dialog as Error Dialog
+
+    User->>GTK: Click button
+    GTK->>GTK: safe_action(:on_compile_clicked)
+    GTK->>Logger: action_start(:on_compile_clicked)
+
+    alt Success
+        GTK->>Logic: on_compile_clicked()
+        Logic-->>GTK: result
+        GTK->>Logger: action_end(status: :success)
+        GTK->>User: show_toast(result)
+    else Error
+        Logic-->>GTK: raise StandardError
+        GTK->>Logger: action_end(status: :error)
+        GTK->>Dialog: show_error_dialog(title, message)
+        Dialog-->>User: Error shown, app continues
+    end
+```
+
+### Version Compatibility
+
+The system GTK4/libadwaita version affects available widgets:
+
+```mermaid
+flowchart TD
+    A[Create Preferences] --> B{defined? Adw::PreferencesDialog}
+    B -->|Yes libadwaita >= 1.4| C[Use PreferencesDialog]
+    B -->|No| D{defined? Adw::PreferencesWindow}
+    D -->|Yes libadwaita >= 1.0| E[Use PreferencesWindow]
+    D -->|No| F[Return nil, log error]
+
+    C --> G["present(parent_window)"]
+    E --> H["transient_for = parent"]
+    H --> I["present()"]
+```
+
+| Widget | Minimum libadwaita | Fallback |
+|--------|-------------------|----------|
+| `PreferencesDialog` | 1.4 | `PreferencesWindow` |
+| `SwitchRow` | 1.4 | Skip widget |
+| `ComboRow` | 1.0 | Always available |
+| `ActionRow` | 1.0 | Always available |
+| `Toast` | 1.0 | Always available |
+| `AboutWindow` | 1.2 | Always available |
+
+## GUI Logging
+
+### Environment Variables
+
+| Variable | Values | Default | Description |
+|----------|--------|---------|-------------|
+| `RAI_GUI_LOG` | `1` | unset | Enable logging |
+| `RAI_GUI_LOG_FILE` | path | none | Also write to file |
+| `RAI_GUI_LOG_LEVEL` | `debug`, `info`, `warn`, `error` | `info` | Minimum level |
+
+### Usage
+
+```bash
+# Log to stderr only
+RAI_GUI_LOG=1 bin/raictl desktop gtk4
+
+# Log to file with debug level
+RAI_GUI_LOG=1 \
+  RAI_GUI_LOG_LEVEL=debug \
+  RAI_GUI_LOG_FILE=/tmp/rosett-ai-gui.log \
+  bin/raictl desktop gtk4
+```
+
+### Log Format (JSON Lines)
+
+```json
+{"timestamp":"2026-02-28T06:21:05.991Z","level":"info","event":"action_start","pid":12345,"action":"on_activate"}
+{"timestamp":"2026-02-28T06:21:06.590Z","level":"info","event":"action_end","pid":12345,"action":"on_activate","status":"success","duration_ms":599.12}
+{"timestamp":"2026-02-28T06:21:08.100Z","level":"error","event":"error","pid":12345,"message":"D-Bus service not available","error_class":"DBus::Error","component":"DbusClient"}
+```
+
+### Logger Architecture
+
+```mermaid
+flowchart TB
+    subgraph Env["Environment"]
+        E1["RAI_GUI_LOG=1"]
+        E2["RAI_GUI_LOG_FILE=/tmp/log"]
+        E3["RAI_GUI_LOG_LEVEL=debug"]
+    end
+
+    subgraph Logger["GuiLogger (Singleton)"]
+        CHECK{enabled?}
+        LEVEL{level >= threshold?}
+        ENTRY["Build JSON entry:<br/>timestamp, level, event,<br/>pid, action_stack"]
+        MUTEX["Mutex.synchronize"]
+    end
+
+    subgraph Output["Output"]
+        STDERR["stderr (warn)"]
+        FILE["File handle (sync: true)"]
+    end
+
+    subgraph Safety["Safety"]
+        RESCUE["rescue StandardError → nil<br/>Never let logging crash app"]
+    end
+
+    Env --> CHECK
+    CHECK -->|Yes| LEVEL
+    CHECK -->|No| SKIP[Return immediately]
+    LEVEL -->|Yes| ENTRY
+    LEVEL -->|No| SKIP
+    ENTRY --> MUTEX
+    MUTEX --> STDERR
+    MUTEX --> FILE
+    MUTEX --> RESCUE
+```
+
+## Pending Work
+
+### Immediate
+
+1. Integration tests for GUI resilience
+2. Consider upgrading `gir1.2-adw-1` for `PreferencesDialog` support
+
+### Future (Desktop Phase 3)
+
+- KDE KCM (KDE Control Module) via Qt6
+- Desktop notifications via `org.freedesktop.Notifications`
+- Auto-compile on focus change
+- GlobalShortcuts portal registration
+
+---
+
+*Generated: 2026-03-02 | rosett-ai v1.0.0*