rosett-ai 1.3.3 → 1.5.10

data/doc/DESKTOP.md

@@ -1,447 +0,0 @@
-# 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*