Imported from jR4dh3y/nonchalant-shell (modules/services/AGENTS.md). Install upstream with npx skills add jR4dh3y/nonchalant-shell --skill services. Copyright stays with the author.

SERVICES KNOWLEDGE BASE

OVERVIEW

Backend singletons bridging Wayland protocols, CLI tools (nmcli, upower, wpctl, etc.), and AI providers to the QML UI layer. 30+ services following a "Reactive Singleton" pattern — internal state derived from async system calls, exposed as QML properties.

WHERE TO LOOK

CONVENTIONS

• Singleton pattern: pragma Singleton + Singleton { id: root } root component (never QtObject).
• Strong Typing: Always declare explicit types (list<string>, list<PwNode>, list<MprisPlayer>, list<BluetoothDevice>, list<WifiAccessPoint>). Never declare untyped property var for collections or known objects.
• Process Safety:
  • Use StdioCollector for multi-line JSON or structured text.
  • Reset busy flags (isUpdating = false) in onExited handlers (including error codes).
  • Never dynamically create uncollected Process instances via Qt.createQmlObject().
• System access: Prefer Quickshell.Io.Process with structured argument lists. Avoid sh -c string interpolation.
• Async safety: Qt.callLater() when modifying lists/models inside process handlers.
• Self-init: Services handle own lifecycle via Component.onCompleted: update().
• Safe Fallbacks: Always provide safe fallback values (available: device !== null).

ANTI-PATTERNS

• Overusing untyped property var when concrete types or typed lists are available.
• Wrapping internal child objects (Connections, Timer, Process) in property var declarations.
• Retaining obsolete compositor shims (e.g. Hyprland syntax in dispatch(), HL_INITIAL_WORKSPACE_TOKEN).
• Modifying list models synchronously inside Process.onStdout handlers.
• Leaving isUpdating flags stuck true when a process fails or exits with non-zero status.