rosett-ai 1.3.3

data/conf/design/desktop_integration.yml

@@ -0,0 +1,289 @@
+---
+name: desktop_integration
+domain: ui
+version: 0.1.0
+status: implemented
+priority: 3
+author: hugo
+created_at: "2026-02-24"
+modified_at: "2026-03-16"
+modified_by: claude
+depends_on:
+  - architecture
+  - ui_framework
+  - accessibility
+  - i18n
+  - security
+  - error_handling
+
+intent: |
+  Define how rosett-ai integrates with Linux desktop environments via a D-Bus
+  session bus service (be.neatnerds.rosettai) and optional desktop-specific
+  frontends. The D-Bus service is the central IPC layer — all desktop
+  variants (GTK4 standalone app, KDE KCM plugin, CLI tools, tiling WM
+  scripts) consume the same D-Bus API. Includes system tray presence via
+  StatusNotifierItem and global hotkey registration via XDG GlobalShortcuts
+  portal.
+
+  The D-Bus service is implemented in Ruby using the ruby-dbus gem. It
+  exposes interfaces for configuration management, focus monitoring, and
+  automatic context switching. The service auto-activates via a standard
+  D-Bus .service file — no manual startup required. Rosett-AI core remains
+  fully functional without D-Bus (CLI/TUI degraded mode).
+
+  Focus monitoring uses compositor-specific adapters (GNOME D-Bus
+  extension, KWin D-Bus scripting, i3ipc gem, Hyprland socket2) that
+  feed into a unified FocusChanged D-Bus signal. This enables automatic
+  context switching when the user changes application focus.
+
+  Phased implementation:
+
+  Phase 1 — D-Bus Service Foundation:
+    be.neatnerds.rosettai D-Bus service (ruby-dbus)
+    StatusNotifierItem for system tray
+    FocusMonitor with compositor adapters
+    GlobalShortcuts portal registration
+    CLI command: bin/raictl --dbus-service
+
+  Phase 2 — GTK4 Desktop App (rosett-ai-gtk4):
+    Standalone libadwaita app consuming D-Bus service
+    AdwPreferencesDialog for settings
+    GNOME HIG compliance
+    Dogtail integration tests
+    .desktop file with DBusActivatable=true
+
+  Phase 3 — KDE KCM Module (rosett-ai-kde):
+    C++/QML thin shim consuming D-Bus service via QtDBus
+    KCMUtils.SimpleKCM + Kirigami.FormLayout
+    KDE HIG compliance
+    Spix / Dogtail integration tests
+
+  This design governs D-Bus IPC, compositor adapters, and desktop service
+  architecture. Pluggable GUI gem packaging and plugin lifecycle management
+  is governed by gui_plugins.yml. Accessibility requirements are governed
+  by accessibility.yml. Error handling follows error_handling.yml.
+
+constraints:
+  - "D-Bus session bus is the sole IPC mechanism between rosett-ai backend and desktop frontends"
+  - "The D-Bus service is implemented in Ruby using ruby-dbus gem — no C/C++ daemon"
+  - "D-Bus service auto-activates via .service file — no manual startup required"
+  - "Rosett-AI core package must remain functional without D-Bus (CLI/TUI degraded mode)"
+  - "GNOME frontend is a standalone libadwaita app (no gnome-control-center plugin — impossible)"
+  - "KDE frontend is a KCM plugin (C++/QML thin shim) consuming the D-Bus service"
+  - "StatusNotifierItem is implemented in the D-Bus service itself — no GUI dependency for tray"
+  - "Global hotkeys use org.freedesktop.portal.GlobalShortcuts where available;
+    compositor-specific config as documented fallback"
+  - "All D-Bus interfaces provide introspection XML"
+  - "Security constraints from security.yml apply to all D-Bus method handlers"
+  - "Follow reverse-DNS naming — bus name be.neatnerds.rosettai, object path /be/neatnerds/rosett-ai"
+  - "This design governs D-Bus IPC, compositor adapters, and desktop service
+    architecture. Pluggable GUI gem packaging is governed by gui_plugins.yml"
+
+acceptance_criteria:
+  - "be.neatnerds.rosettai service starts on D-Bus session bus via bin/raictl --dbus-service"
+  - "Service auto-activates when any client calls a method (via .service file)"
+  - "busctl --user introspect be.neatnerds.rosettai /be/neatnerds/rosett-ai shows all interfaces"
+  - "GTK4 app communicates exclusively via D-Bus (no direct Ruby API calls)"
+  - "KDE KCM communicates exclusively via D-Bus (via QtDBus)"
+  - "CLI command bin/raictl dbus status shows service state"
+  - "StatusNotifierItem appears in KDE Plasma system tray and Waybar without GTK4 app running"
+  - "bin/raictl --dbus-service gracefully degrades if D-Bus session bus unavailable"
+  - "Focus monitor detects compositor type and subscribes to focus events"
+  - "FocusChanged signal emitted on D-Bus when active window changes"
+  - "Global hotkey registration succeeds on KDE Plasma via GlobalShortcuts portal"
+  - "Exit code 0 on success, 1 on D-Bus connection failure, 5 on missing ruby-dbus dependency"
+  - "TTY-aware output: formatted status when interactive, JSON when piped"
+
+examples:
+  - scenario: "D-Bus service on sway — user runs sway, installs Rosett-AI core only"
+    expected: |
+      bin/raictl compile works via CLI. D-Bus service auto-activates when
+      Waybar's SNI module queries the tray. Tray icon appears. Focus monitor
+      uses i3ipc adapter for sway IPC socket.
+    not: "Service crashes because no GNOME/KDE present. Tray requires GTK4 app."
+  - scenario: "GTK4 app on GNOME — user installs rosett-ai + rosett-ai-gtk4"
+    expected: |
+      Launches via desktop file. App connects to be.neatnerds.rosettai via
+      GDBus. All operations go through D-Bus. Settings use
+      AdwPreferencesDialog with instant-apply pattern.
+    not: "GTK4 app imports Ruby Rosett-AI modules directly. Uses OK/Apply buttons."
+  - scenario: "Focus-based context switching — user has VS Code and Firefox open"
+    expected: |
+      User switches to Firefox. Focus monitor detects app_id change, emits
+      FocusChanged('firefox', ...). Manager loads browser memory profile.
+      ContextChanged signal emitted on D-Bus.
+    not: "Polling loop checks focus every N seconds. Context switch requires manual action."
+  - scenario: "Hotkey triggers compile — user presses configured hotkey"
+    expected: |
+      GlobalShortcuts portal delivers event to D-Bus service. Service runs
+      compile. Notification sent via org.freedesktop.Notifications.
+    not: "rosett-ai grabs keyboard input directly. Hotkey only works under specific compositor."
+
+anti_patterns:
+  - "QProcess/subprocess calls from GUI to Rosett-AI CLI (bypasses D-Bus)"
+  - "Polling for focus changes instead of event-driven subscription"
+  - "Implementing SNI in the GTK4 app instead of the D-Bus service"
+  - "Assuming GlobalShortcuts portal is available on all compositors"
+  - "Business logic in KCM C++/QML layer or GTK4 UI layer"
+  - "Hardcoded compositor detection instead of environment variable + D-Bus name probing"
+
+gui_notes: |
+  Document interactions (cross-references):
+
+  1. gui_plugins.yml: desktop_integration provides D-Bus service and
+     compositor adapters. gui_plugins governs pluggable GUI gem packaging,
+     plugin lifecycle management, and PackageManager abstraction.
+
+  2. accessibility.yml: desktop integration implements EN 301 549
+     requirements for D-Bus service responses, SNI tray, and focus
+     announcements.
+
+  3. security.yml: all D-Bus method handlers follow security constraints.
+     No secret exposure via D-Bus properties or signals.
+
+  4. error_handling.yml: D-Bus method errors map to structured error
+     hierarchy. Exit codes for dbus status command.
+
+  5. ui_framework.yml: TUI is the primary interface. Desktop integration
+     adds D-Bus IPC layer for optional GUI frontends.
+
+  6. i18n.yml: D-Bus service status messages and error responses are
+     localised via gettext.
+
+  D-Bus Interfaces:
+
+  be.neatnerds.rosettai.Manager:
+    Methods:
+      Compile() -> s                   # Run compilation, return status
+      SwitchContext(s context_name)     # Switch AI context by name
+      GetStatus() -> a{sv}             # Return service status as dict
+    Properties:
+      Version: s (read)                # Service version string
+    Signals:
+      ContextChanged(s context_name)   # Emitted after context switch
+
+  be.neatnerds.rosettai.FocusMonitor:
+    Methods:
+      GetCurrentFocus() -> (ss)        # Return (app_id, window_title)
+    Signals:
+      FocusChanged(s app_id, s title)  # Emitted on active window change
+
+  org.kde.StatusNotifierItem:
+    Standard SNI interface for system tray icon. Implemented in the D-Bus
+    service itself — no GTK4 or Qt6 dependency. Consumed by KDE Plasma
+    system tray, Waybar, swaybar, and other SNI-capable panels.
+
+  org.freedesktop.portal.GlobalShortcuts:
+    Consumer (not provider). The D-Bus service registers hotkey bindings
+    via the XDG GlobalShortcuts portal. Specific key bindings are
+    user-configurable — not hardcoded. Fallback: compositor-specific
+    config documentation (sway bindsym, Hyprland bind, etc.).
+
+  D-Bus Service File (/usr/share/dbus-1/services/be.neatnerds.rosettai.service):
+    [D-BUS Service]
+    Name=be.neatnerds.rosettai
+    Exec=/usr/bin/raictl --dbus-service
+
+  Compositor Detection (auto):
+    1. HYPRLAND_INSTANCE_SIGNATURE → :hyprland
+    2. SWAYSOCK → :sway
+    3. I3SOCK → :i3
+    4. D-Bus name org.gnome.Shell active → :gnome
+    5. D-Bus name org.kde.KWin active → :kwin
+    6. DISPLAY set, WAYLAND_DISPLAY unset → :x11
+    7. else → :unknown
+
+  Focus Adapter Mapping:
+    :gnome   → GNOME Shell extension D-Bus interface
+    :kwin    → KWin D-Bus scripting API (org.kde.KWin)
+    :sway    → i3ipc gem (window::focus event)
+    :i3      → i3ipc gem (window::focus event)
+    :hyprland → Hyprland IPC socket2 (activewindow>> event)
+    :x11     → _NET_ACTIVE_WINDOW property change (xprop)
+    :unknown → no focus monitoring (degraded mode)
+
+interactions:
+  - action: "View rosett-ai status"
+    tui: "bin/raictl status"
+    gtk4: "Preferences dialog status page"
+    qt6: "KCM panel status section"
+  - action: "Switch AI context"
+    tui: "bin/raictl context switch <name>"
+    gtk4: "Tray menu context submenu"
+    qt6: "KCM dropdown or tray menu"
+  - action: "Trigger compile"
+    tui: "bin/raictl compile"
+    gtk4: "Hotkey or tray action"
+    qt6: "KCM button or hotkey"
+  - action: "View D-Bus service state"
+    tui: "bin/raictl dbus status"
+    gtk4: "Status indicator in preferences"
+    qt6: "KCM status widget"
+
+accessibility:
+  roles:
+    - element: "tray_menu"
+      role: "menu"
+      label: "Rosett-AI tray menu"
+      description: "System tray context menu for quick actions"
+    - element: "preferences_dialog"
+      role: "dialog"
+      label: "Rosett-AI preferences"
+      description: "Configuration dialog (GTK4: AdwPreferencesDialog)"
+    - element: "focus_indicator"
+      role: "status"
+      label: "Current focus application"
+      description: "Shows which application currently has focus"
+    - element: "context_selector"
+      role: "listbox"
+      label: "AI context selector"
+      description: "Dropdown or list for switching AI context"
+  keyboard:
+    - key: "Menu key or right-click"
+      action: "Open tray context menu"
+    - key: "Arrow keys"
+      action: "Navigate tray menu items"
+    - key: "Enter"
+      action: "Activate selected tray menu item"
+    - key: "Escape"
+      action: "Close tray menu or preferences dialog"
+  announcements:
+    - event: "context_switch"
+      announce: "Context switched to <name>"
+      priority: "polite"
+    - event: "compile_complete"
+      announce: "Compilation completed successfully"
+      priority: "polite"
+    - event: "compile_error"
+      announce: "Compilation failed: <error>"
+      priority: "assertive"
+    - event: "service_unavailable"
+      announce: "D-Bus service unavailable — running in degraded mode"
+      priority: "assertive"
+    - event: "focus_change"
+      announce: "Focus changed to <app_id>"
+      priority: "polite"
+
+preferences:
+  language: ruby
+  patterns:
+    - "Adapter pattern for compositor-specific focus monitors"
+    - "Event-driven subscription (not polling)"
+    - "Graceful degradation when D-Bus unavailable"
+    - "Reverse-DNS naming (be.neatnerds.rosettai)"
+  testing: rspec with D-Bus service unit tests, compositor adapter mock
+    scenarios, focus monitor event subscription, SNI interface validation,
+    graceful degradation tests, and dogtail integration tests for GUI variants
+  gems:
+    - ruby-dbus
+    - i3ipc (sway/i3 focus adapter)
+    - gtk4 (rosett-ai-gtk4 package only)
+    - adwaita (rosett-ai-gtk4 package only)
+  kde_build:
+    - cmake
+    - extra-cmake-modules
+    - kf6-kcmutils
+    - kf6-ki18n
+    - kf6-kcoreaddons
+    - qt6-base-dev
+    - qt6-declarative-dev

data/conf/design/distribution.yml

@@ -0,0 +1,216 @@
+---
+name: distribution
+domain: ci
+version: 0.2.0
+status: implemented
+priority: 5
+author: claude
+created_at: "2026-02-22"
+modified_at: "2026-03-16"
+modified_by: claude
+depends_on:
+  - ci_pipeline
+  - release_management
+  - documentation
+  - security
+  - error_handling
+
+intent: |
+  Define how built packages reach end users through a self-hosted,
+  multi-format repository backed by Pulp (pulpproject.org).
+
+  The build pipeline (P1 ci_pipeline) already produces .deb packages, and
+  the release process (P5 release_management) creates versioned tags. This
+  document closes the gap: how does a tagged release become an installable
+  package for users — and how does that scale to multiple distributions and
+  operating systems?
+
+  Without distribution:
+  - Users must manually download .deb files from GitLab releases
+  - No automatic security updates via apt upgrade / dnf upgrade
+  - No GPG verification of package authenticity
+  - No separation between stable and development channels
+  - Adding RPM or other formats requires standing up a new tool each time
+
+  With distribution:
+  - Users add the NeatNerds repo once, then 'apt install rosett-ai' or 'dnf install rosett-ai'
+  - Security updates arrive via the native package manager
+  - Every package is GPG-signed and verifiable
+  - Stable and unstable channels serve different audiences
+  - New formats (RPM, generic, container, Homebrew tap) are added as Pulp
+    plugins without replacing the core infrastructure
+
+  Why Pulp over aptly:
+  - aptly is Debian-only. Pulp supports DEB, RPM, Python, Container, Ansible,
+    and generic file repositories via its plugin architecture
+  - Pulp is used in production by Microsoft (packages.microsoft.com) and
+    Red Hat (Satellite/Katello)
+  - Adding RPM support later is 'pulp_rpm plugin install', not 'deploy a
+    second repository server'
+  - Pulp's REST API is CI-friendly for automated publishing
+
+  Deployment phases:
+  Phase 1 — DEB only (Debian Bookworm, amd64 + arm64). Pulp with pulp_deb.
+  Phase 2 — Add RPM (Fedora/RHEL). Install pulp_rpm plugin, add CI matrix.
+  Phase 3 — Generic files (AppImage, standalone tarballs). Install pulp_file.
+
+  Phase 1 is the scope of this design document. Phases 2-3 are noted in
+  constraints and acceptance criteria to ensure Phase 1 decisions do not
+  block them.
+
+  CI/CD recipes are documented as reusable pipeline patterns: multi-format
+  builds (DEB for amd64 and arm64 in parallel), release automation (tag →
+  build → sign → publish → smoke test), and integration test recipes (install
+  package in clean container, verify rosett-ai version, verify rai doctor passes).
+  These recipes are documented in doc/CI_CD_RECIPES.md and implemented as
+  CI job templates in the shared ci-components repository.
+
+  Distribution complements release management (release_management.yml):
+  release management creates versioned tags and changelogs, distribution
+  delivers the built packages to end users via native package managers.
+  The handoff point is the CI tag event — release creates the tag,
+  distribution publishes the artifact.
+
+constraints:
+  - Package repository managed by Pulp 3 (pulpproject.org) with OCI container deployment
+  - DEB support via pulp_deb plugin (Phase 1)
+  - RPM support via pulp_rpm plugin MUST NOT be blocked by Phase 1 infrastructure decisions (Phase 2 readiness)
+  - Generic file support via pulp_file MUST NOT be blocked (Phase 3 readiness)
+  - All packages are GPG-signed using repository-level detached signing (InRelease for DEB, repomd.xml.asc for RPM)
+  - GPG signing key uses Ed25519 or RSA-4096 with SHA256+ digest (SHA1 rejected by apt after Feb 2026)
+  - CI publishes packages only on annotated tag push events (never on branch commits to stable)
+  - Two distribution channels — stable (tagged releases) and unstable (main branch builds)
+  - The GPG public key is distributed via HTTPS from the repository server
+  - Repository configuration documented in INSTALL.md
+  - Package publishing is idempotent — re-publishing the same version is a no-op, not an error
+  - The private GPG signing key is stored as a CI/CD variable (protected, masked) — never in the repository
+  - Repository serves amd64 and arm64 architectures (DEB Phase 1); x86_64 and aarch64 (RPM Phase 2)
+  - HTTPS only for repository access (no plain HTTP)
+  - Pulp deployment uses the official OCI images (pulp/pulp-minimal or pulp/pulp)
+  - Pulp API access from CI uses token authentication (not username/password)
+  - Repository metadata is generated by Pulp (never manually crafted)
+  - Infrastructure configuration is reproducible (container compose file versioned in a separate ops repository)
+  - "doc/CI_CD_RECIPES.md must document reusable pipeline patterns for
+    multi-format builds, release automation, and integration testing"
+  - "CI/CD recipes must be engine-agnostic — applicable to any engine that
+    produces a distributable artifact"
+  - "This design governs package distribution (delivering built packages to
+    users). Release management (versioning, tagging, changelogs) is governed
+    by release_management.yml. Package building is governed by ci_pipeline.yml.
+    The CI tag event is the handoff point between release and distribution"
+
+acceptance_criteria:
+  - A GitLab CI job deploy:publish runs on tag push and publishes the .deb to the Pulp DEB repository
+  - apt install rosett-ai works after adding the NeatNerds repository and GPG key
+  - apt upgrade picks up new rosett-ai versions when published to stable
+  - Repository serves signed InRelease files verifiable by apt
+  - CI job uses Pulp REST API (via pulp-cli or curl) to upload package and trigger publication
+  - GPG public key downloadable via HTTPS at a documented URL
+  - INSTALL.md contains copy-pasteable commands for repository setup (DEB)
+  - Stable channel only receives packages from annotated tags matching v*.*.*
+  - Unstable channel receives packages from main branch CI builds (latest commit)
+  - Repository supports both amd64 and arm64 packages in the same DEB distribution
+  - Pulp container deployment is defined in a docker-compose.yml (or podman equivalent)
+  - pulp_rpm plugin can be added to the running Pulp instance without rebuilding (Phase 2 readiness)
+  - A CI smoke test verifies the published package is installable in a clean Debian container
+  - "CI publish job exits 0 on success, 1 on upload failure, 2 on
+    authentication failure, 3 on package validation failure"
+  - "doc/CI_CD_RECIPES.md documents multi-format build, release automation,
+    and integration test pipeline patterns"
+
+examples:
+  - scenario: "CI publishes v0.2.0 after tag push"
+    expected: |
+      1. Developer pushes tag v0.2.0
+      2. CI pipeline triggers on tag event
+      3. build:package jobs produce rosett-ai_0.2.0_amd64.deb and rosett-ai_0.2.0_arm64.deb
+      4. deploy:publish job authenticates to Pulp API via token
+      5. Job uploads .deb artifacts to Pulp content endpoint
+      6. Job adds packages to the 'stable' DEB repository
+      7. Job triggers Pulp publication (regenerates InRelease, Packages.gz)
+      8. Users see update via 'apt update && apt list --upgradable'
+    not: |
+      Publishing happens on every commit. Publishing overwrites existing
+      version without warning. Publishing uses unsigned repository.
+      CI SSHes directly to a server (use API instead).
+
+  - scenario: "User adds NeatNerds APT repository for the first time"
+    expected: |
+      # Commands from INSTALL.md:
+      curl -fsSL https://repo.neatnerds.be/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/neatnerds.gpg
+      echo "deb [signed-by=/usr/share/keyrings/neatnerds.gpg] https://repo.neatnerds.be/stable bookworm main" \
+        | sudo tee /etc/apt/sources.list.d/neatnerds.list
+      sudo apt update
+      sudo apt install rosett-ai
+      raictl version  # → rai version 0.2.0
+    not: |
+      Using deprecated apt-key add. Downloading GPG key over HTTP.
+      Using unsigned repository. Instructions that don't work on copy-paste.
+
+  - scenario: "Attempting to publish without API credentials"
+    expected: |
+      CI job fails with clear error: "Pulp API token not configured.
+      Set CI variable PULP_API_TOKEN (protected, masked)."
+      No package is published. Pipeline status: failed.
+    not: |
+      Publish unsigned package to repository. Silently skip authentication.
+      Fall back to anonymous upload.
+
+  - scenario: "Phase 2 — adding RPM support"
+    expected: |
+      1. Ops installs pulp_rpm plugin into the running Pulp container
+      2. CI matrix adds Fedora/RHEL build jobs producing .rpm files
+      3. deploy:publish job extended with RPM upload path
+      4. Users on Fedora: dnf config-manager --add-repo https://repo.neatnerds.be/stable/rpm
+      5. Same GPG key, same server, same CI pipeline structure
+    not: |
+      Standing up a second repository server. Migrating from Pulp to
+      another tool. Changing the DEB pipeline to accommodate RPM.
+
+anti_patterns:
+  - Publishing packages on every commit (stable channel is for releases only)
+  - Using apt-key add (deprecated since Debian 11, removed in Debian 12)
+  - Distributing GPG key over plain HTTP (MITM risk)
+  - Storing GPG private key in the git repository
+  - Using SHA1-based GPG keys (rejected by apt after Feb 2026)
+  - Manual package uploading to the repository server (must be CI-automated)
+  - Mixing stable and unstable packages in the same repository component
+  - Publishing without verifying the package installs correctly (smoke test)
+  - Using aptly or other Debian-only tools that block future RPM/generic expansion
+  - SSHing to the repository server from CI (use Pulp REST API instead)
+  - Running Pulp on bare metal without containerisation (reproducibility risk)
+  - Crafting repository metadata manually instead of letting Pulp generate it
+#
+gui_notes: |
+  Document interactions (cross-references):
+
+  1. release_management.yml: release creates versioned tags and changelogs.
+     Distribution publishes the built packages. Tag event is the handoff.
+
+  2. ci_pipeline.yml: CI builds the packages. Distribution publishes them.
+     The publish job runs after the build job in the same pipeline.
+
+  3. security.yml: GPG signing, HTTPS transport, token authentication,
+     private key storage as CI/CD variable.
+
+  4. documentation.yml: INSTALL.md contains repository setup instructions
+     that must be kept in sync with distribution changes.
+
+  5. error_handling.yml: CI job exit codes follow structured error conventions.
+#
+preferences:
+  language: bash
+  patterns:
+    - "Immutable releases (publish once, never overwrite)"
+    - "Signed artifacts (GPG-signed packages and repository metadata)"
+    - "Infrastructure as code (container compose versioned in ops repo)"
+    - "Plugin architecture (Pulp plugins for format expansion)"
+  tools:
+    repository: pulp (pulpproject.org)
+    plugins_phase1: pulp_deb
+    plugins_phase2: pulp_rpm
+    plugins_phase3: pulp_file
+    signing: gpg (Ed25519 or RSA-4096, SHA256+)
+    transport: pulp REST API over HTTPS
+    deployment: OCI containers (docker-compose or podman)
+    ci: gitlab-ci with protected variables