feat(linux): show notifications and alerts through freedesktop D-Bus (#1471)

Author: y3owk1n

docs/CROSS_PLATFORM.md

@@ -65,7 +65,7 @@ reference implementation, and a gap on this platform is a bug.
 
 **Beta** — good for daily driving. Every navigation mode works and behaves the
 same as it does on a stable platform; what is missing sits around the edges
-(notifications, alerts, a few animations) rather than in your way.
+(a few animations, the OCR hint strategy) rather than in your way.
 
 **Alpha** — worth trying, not yet worth switching to. Core navigation works, but
 hint coverage is incomplete and per-app config does not re-apply on focus
@@ -157,8 +157,8 @@ that is what [Known Gaps](#known-gaps) tracks, per
 | **Dark mode detection**       | ✅ Cocoa appearance      | ✅ xdg appearance portal | ✅ xdg appearance portal   | ✅ kdeglobals + portal  | ✅ registry                  |
 | **Font resolution**           | ✅ NSFont                | ✅ fontconfig          | ✅ fontconfig                | ✅ fontconfig           | ⚠️ generic-alias map only ²  |
 | **System tray**               | ✅ NSStatusItem          | ✅ D-Bus StatusNotifierItem | ✅ StatusNotifierItem        | ✅ StatusNotifierItem   | ✅ Win32 notification area   |
-| **Native alerts**             | ✅ NSAlert               | 🟡                     | 🟡                           | 🟡                      | ✅ `MessageBoxW`             |
-| **Native notifications**      | ✅ UNNotification        | 🟡                     | 🟡                           | 🟡                      | 🟡                           |
+| **Native alerts**             | ✅ NSAlert               | ⚠️ D-Bus, not modal    | ⚠️ D-Bus, not modal          | ⚠️ D-Bus, not modal     | ✅ `MessageBoxW`             |
+| **Native notifications**      | ✅ UNNotification        | ✅ `org.freedesktop.Notifications` | ✅ `org.freedesktop.Notifications` | ✅ `org.freedesktop.Notifications` | 🟡          |
 | **Secure input detection**    | ✅                       | ➖ always false        | ➖ always false              | ➖ always false         | ➖ always false              |
 | **System cursor hide**        | ✅ `CGDisplayHideCursor` | ➖                     | ➖                           | ➖                      | ➖                           |
 | **`monitor_select` mode**     | ✅ native panels         | ✅ Cairo panels        | ✅ Cairo panels              | ✅ Cairo panels         | 🟡 `CodeNotSupported`        |
@@ -250,6 +250,24 @@ binary was compiled. Both name the same fallback — bind `neru <mode>` as a
 compositor keybinding. While a mode is active the in-mode event tap grabs the
 same devices, so the listener naturally goes quiet until the mode exits.
 
+**Native alerts on Linux.** Notifications and alerts both go to the session's
+freedesktop notification daemon over D-Bus — the same session bus the tray's
+StatusNotifierItem uses, in pure Go, so a `CGO_ENABLED=0` build shows them too.
+An alert differs from a notification only in insistence: critical urgency and no
+expiry, which the specification requires a daemon to leave on screen until it is
+dismissed. What it is *not* is modal. macOS's `NSAlert` stops the world and
+returns which button was pressed; no ordinary Wayland or X11 client can do that,
+so a Linux alert informs rather than asks, and callers that would have branched
+on the answer take the safe default. The two startup alerts are where that shows
+up: a missing config file starts Neru on built-in defaults and says so, instead
+of offering create / defaults / quit. Delivery depends on the session having a
+notification daemon (mako, dunst, or the desktop's own) — either running, or
+registered with the bus to be started on demand, which is how most desktops ship
+theirs and which `neru doctor` counts as present. With none, `ShowNotification`
+and `ShowAlert` report `CodeNotSupported` naming what is absent, `neru doctor`
+probes the session and downgrades the notifications row with a line saying what
+to install, and the two startup alerts fall back to stderr.
+
 **Smooth cursor animation on Linux.** Off by default; opt in with
 `smooth_cursor.move_mouse_enabled` (the same cross-platform `SmoothCursorConfig`
 macOS uses). When enabled, `SystemAdapter.MoveCursorToPoint` routes through
@@ -751,49 +769,45 @@ command — that means less here than it does on macOS, whether or not the
 
 **Linux**
 
-1. Native notifications and alerts — both stubs; target freedesktop D-Bus
-   notifications. `ShowNotification` has an empty body and no error to carry,
-   `ShowAlert` returns `CodeNotSupported`, and the config-onboarding and
-   validation-error alerts silently return defaults instead of prompting
-2. `neru services` — no systemd user unit, so install/uninstall/start/stop/
+1. `neru services` — no systemd user unit, so install/uninstall/start/stop/
    restart/status all return `CodeNotSupported` where macOS writes a launchd
    plist. Scope is systemd; other init systems stay `CodeNotSupported`
-3. `neru docs` — returns `CodeNotSupported` although the tray already opens
+2. `neru docs` — returns `CodeNotSupported` although the tray already opens
    URLs through `xdg-open` in the same repo
-4. Smooth scroll animation — not implemented, and `smooth_scroll.*` is parsed,
+3. Smooth scroll animation — not implemented, and `smooth_scroll.*` is parsed,
    validated and then silently ignored. Spike `REL_WHEEL_HI_RES` (uinput),
    continuous `wl_pointer` axis values and libei scroll deltas before
    committing
-5. Hints search input badge — not drawn; the overlay manager reports
+4. Hints search input badge — not drawn; the overlay manager reports
    `CodeNotSupported` and the query goes on reaching hints through the event
    tap's key stream
-6. Screen capture — no code path anywhere in the tree. Prerequisite for the OCR
+5. Screen capture — no code path anywhere in the tree. Prerequisite for the OCR
    strategy below and the missing half of `ports.Vision`. Take it per backend:
    `wlr-screencopy` on wlroots, `XGetImage` on X11, the portal only for KDE
-7. `vision` hint strategy — no engine. Met by linking one through
+6. `vision` hint strategy — no engine. Met by linking one through
    `#cgo pkg-config`, as every other native dependency here is, with the engine
    added to the required Linux library list and its language data checked at
    use so a missing `tessdata` reports `CodeNotSupported` naming what is
    absent. Note the strategy is wider than OCR: macOS also runs rectangle
    detection and saliency, which no OCR engine answers, so
    `hints.vision.detect_rectangles` and the four `rectangle_*` options are
-   declared macOS-only and Linux `vision` is text-only. Needs 6
-8. X11 unmodified scroll — a scroll with no `--modifier` presses nothing, so the
+   declared macOS-only and Linux `vision` is text-only. Needs 5
+7. X11 unmodified scroll — a scroll with no `--modifier` presses nothing, so the
    `XTestFakeButtonEvent` still carries whatever the X server records the user as
    physically holding. Binding `Ctrl+J` to a plain `scroll_down` therefore sends
    ctrl+scroll for as long as ctrl is down. macOS forces the empty set onto the
    event instead; a real-key backend has no per-event field to zero, so closing
    this means reading the live key state through `XQueryKeymap` in the C bridge
-9. KDE RemoteDesktop portal grant — does not survive a daemon restart, so the
+8. KDE RemoteDesktop portal grant — does not survive a daemon restart, so the
    consent prompt returns on every start
-10. Grid virtual-pointer indicator — a no-op on Linux, while recursive grid
-    draws it on all three platforms
-11. `FocusedWindowBounds` — returns not-found on KWin, so callers silently fall
+9. Grid virtual-pointer indicator — a no-op on Linux, while recursive grid
+   draws it on all three platforms
+10. `FocusedWindowBounds` — returns not-found on KWin, so callers silently fall
     back to the active screen
-12. Wayland global hotkeys — a setup requirement rather than missing code: they
+11. Wayland global hotkeys — a setup requirement rather than missing code: they
     need `input`-group membership and a CGO build. Failing loudly with the
     remedy, and documenting it as a first-class setup step, is the work
-13. Tail — the tray tooltip is a no-op (dbusmenu carries no such property), the
+12. Tail — the tray tooltip is a no-op (dbusmenu carries no such property), the
     tray has one icon for both running and paused states where macOS has two,
     and the `CGO_ENABLED=0` build should announce its boundary once at startup
     rather than failing feature by feature

docs/LINUX_SETUP.md

@@ -311,7 +311,12 @@ systemctl --user enable --now neru
    by app. DE-specific coordinate details: [LINUX_DESKTOPS.md](./LINUX_DESKTOPS.md).
 3. **Dark mode** — Via `org.freedesktop.appearance` portal, with session-specific
    fallbacks where the portal is unavailable.
-4. **Notifications** — May log instead of using `org.freedesktop.Notifications`.
+4. **Notifications** — Delivered over `org.freedesktop.Notifications` on the
+   session bus, so a notification daemon (mako, dunst, or your desktop's own)
+   has to be running — or installed as a D-Bus service the bus starts on
+   demand, as most desktops ship theirs. What Neru does when neither, and why
+   an alert is not modal here: "Native alerts on Linux" under the
+   [Capability Matrix](./CROSS_PLATFORM.md#capability-matrix).
 5. **Wayland modified clicks** — Need `evdev` access (see [keyboard permissions](#wayland-keyboard-capture-permissions)).
 6. **Monitor hotplug** — Adding/removing a monitor is tracked live (RandR on X11,
    `wl_output` on Wayland) and the overlay follows; a relaunch is only needed for a

docs/ROADMAP.md

@@ -40,7 +40,7 @@ wlroots Wayland with a CGO build, with a closed set of macOS-only exemptions.
 
 The two largest open areas:
 
-- **Linux** — freedesktop notifications and alerts across all backends, and
+- **Linux** — screen capture and the OCR hint strategy it unblocks, and
   persisting the KDE RemoteDesktop portal grant across daemon restarts.
 - **Windows** — foreground-window and display-hotplug events, which currently
   block per-app config re-application and monitor tracking.

internal/adapter/platform/darwin/system.go

@@ -188,8 +188,14 @@ func (s *SystemAdapter) ShowAlert(ctx context.Context, title, message string) er
 }
 
 // ShowNotification displays a lightweight toast/banner notification on macOS.
-func (s *SystemAdapter) ShowNotification(title, message string) {
+//
+// The UserNotifications path is fire-and-forget, so this returns as soon as
+// the request is handed to the notification center; there is no failure to
+// report at this point and it always reports success.
+func (s *SystemAdapter) ShowNotification(_ context.Context, title, message string) error {
 	ShowNotification(title, message)
+
+	return nil
 }
 
 // CheckScreenCapturePermission reports whether macOS screen recording is

internal/adapter/platform/factory_linux.go

@@ -3,6 +3,10 @@
 package platform
 
 import (
+	"context"
+	"fmt"
+	"os"
+
 	"github.com/y3owk1n/neru/internal/adapter/platform/linux"
 	"github.com/y3owk1n/neru/internal/ports"
 )
@@ -25,13 +29,49 @@ func NewFontResolver() ports.FontResolver {
 	return linux.NewFontResolver()
 }
 
-// ShowConfigOnboardingAlert is a stub on Linux.
-func ShowConfigOnboardingAlert(_ string) int {
+// ShowConfigOnboardingAlert tells a first-time user that Neru started on
+// built-in defaults, and how to get a config file, then answers with that
+// choice.
+//
+// macOS asks the question in a modal NSAlert and waits — create, use defaults,
+// or quit. Linux answers it instead of asking, deliberately. A modal dialog
+// here needs a toolkit Neru does not link or a helper (zenity, kdialog) a
+// minimal wlroots session need not have, so the honest choices were a prompt
+// that may never appear or a message plus a safe default. Blocking startup on
+// a dialog nobody can see is worse than starting; a keyboard-driven tool whose
+// first act is to seize the session for a question is worse still. So the
+// question is answered the way the user could only have answered it after
+// being asked — run, on defaults, changing nothing on disk — and they are told
+// what happened and what to type.
+func ShowConfigOnboardingAlert(configPath string) int {
+	title := "Neru is running on built-in defaults"
+	message := "No configuration file at " + configPath +
+		". Run `neru config init` to create one."
+
+	// Bounded by the adapter's own notify deadline; these run before the daemon
+	// is up, so a wedged session bus costs a moment rather than the launch.
+	err := linux.ShowAlert(context.Background(), title, message)
+	if err != nil {
+		// Onboarding has no other channel: nothing upstream prints this, so a
+		// session with no notification daemon would otherwise learn nothing.
+		fmt.Fprintf(os.Stderr, "⚠️  %s.\n%s\n\n", title, message)
+	}
+
 	return ConfigOnboardingDefaults
 }
 
-// ShowConfigValidationErrorAlert is a stub on Linux.
-func ShowConfigValidationErrorAlert(_, _ string) int {
+// ShowConfigValidationErrorAlert puts a rejected configuration in front of the
+// user before Neru exits, then answers as the dismissed macOS dialog does.
+//
+// It is a notification rather than a dialog for the reasons above; the alert
+// shape it uses stays on screen until dismissed, so a message that arrives
+// while the user is looking elsewhere is still there when they look back.
+func ShowConfigValidationErrorAlert(errorMessage, configPath string) int {
+	// The launcher has already written the same failure to stderr, so a
+	// missing notification daemon costs the desktop copy rather than the
+	// message — nothing to fall back to here.
+	_ = linux.ShowAlert(context.Background(), "Neru could not load "+configPath, errorMessage)
+
 	return ConfigValidationOK
 }
 

internal/adapter/platform/linux/system_common.go

@@ -6,6 +6,7 @@ package linux
 import (
 	"bufio"
 	"context"
+	"errors"
 	"image"
 	"io"
 	"os"
@@ -84,6 +85,12 @@ func (s *SystemAdapter) Capabilities() ports.PlatformCapabilities {
 	value, source, ok := darkModePreference()
 	capabilities.DarkModeDetection = darkModeCapability(value, source, ok)
 
+	// Notifications are live-probed for the same reason dark mode is: the code
+	// path exists on every backend, but whether the user will see anything
+	// depends on a notification daemon being installed, which is a session fact
+	// rather than a build one.
+	capabilities.Notifications = s.notificationCapability(capabilities.Notifications)
+
 	// Screen, cursor and process support is what this binary and session can
 	// actually reach, not what the build target intends — the static preset is
 	// wrong for CGO_ENABLED=0, for compositors without the wlroots stack, and
@@ -491,15 +498,20 @@ func (s *SystemAdapter) IsSecureInputEnabled() bool {
 // ShowSecureInputNotification is a no-op on Linux — secure input is a macOS-only concept.
 func (s *SystemAdapter) ShowSecureInputNotification() {}
 
-// ShowAlert displays a native system alert on Linux.
-// TODO(linux): implement using libnotify, zenity, or kdialog.
+// ShowAlert displays a message the user has to dismiss, through the session's
+// freedesktop notification daemon. Delivery does not depend on the display
+// server, so every Linux backend takes the same path; see alertNotification
+// for why this is a critical-urgency notification rather than a modal dialog.
 func (s *SystemAdapter) ShowAlert(ctx context.Context, title, message string) error {
-	return derrors.New(derrors.CodeNotSupported, "ShowAlert not yet implemented on linux")
+	return ShowAlert(ctx, title, message)
 }
 
-// ShowNotification displays a lightweight notification on Linux.
-// TODO(linux): implement using org.freedesktop.Notifications D-Bus interface.
-func (s *SystemAdapter) ShowNotification(title, message string) {}
+// ShowNotification displays a lightweight notification through the session's
+// freedesktop notification daemon, reporting CodeNotSupported when the session
+// has no bus or no daemon to show it rather than dropping the message.
+func (s *SystemAdapter) ShowNotification(ctx context.Context, title, message string) error {
+	return ShowNotification(ctx, title, message)
+}
 
 // CheckScreenCapturePermission reports true: Linux does not gate screen capture
 // behind a permission.
@@ -553,6 +565,67 @@ func (s *SystemAdapter) probedCapability(
 	}
 }
 
+// notificationFeature names the notification probe's slot in capabilityProbes,
+// and opens the detail it reports.
+const notificationFeature = "desktop notifications"
+
+// notificationCapability live-probes whether a notification daemon is
+// reachable right now. The question a user runs `neru doctor` to answer is
+// "will I see notifications?", and on Linux that is answered by the session
+// rather than by this code: every backend can send one, and a session with no
+// daemon shows none. Reporting the static "supported" there would be the same
+// lie the empty ShowNotification body used to tell.
+//
+// It shares the probe slots and the budget with probedCapability but not its
+// body: that one explains a failure in terms of the display-server backend,
+// which decides nothing here — notifications are a session-bus service every
+// backend reaches the same way. The budget has to be the full one because the
+// first probe of a daemon's life pays for the session-bus connect as well as
+// the question, and reporting "could not be confirmed" on a session where
+// notifications work is the same dishonesty in the other direction.
+func (s *SystemAdapter) notificationCapability(
+	declared ports.FeatureCapability,
+) ports.FeatureCapability {
+	completed, err := s.probes.run(
+		notificationFeature,
+		capabilityProbeTimeout,
+		func() error {
+			ctx, cancel := context.WithTimeout(context.Background(), capabilityProbeTimeout)
+			defer cancel()
+
+			return sessionNotifier.daemonReachable(ctx)
+		},
+	)
+
+	switch {
+	case !completed:
+		return ports.FeatureCapability{
+			Status: ports.FeatureStatusStub,
+			Detail: notificationFeature + " could not be confirmed: the session bus did not " +
+				"answer within " + capabilityProbeTimeout.String(),
+		}
+	case err != nil:
+		return ports.FeatureCapability{
+			Status: ports.FeatureStatusStub,
+			Detail: notificationFeature + " are unavailable: " + userFacingReason(err),
+		}
+	default:
+		return declared
+	}
+}
+
+// userFacingReason unwraps a domain error to the sentence written for the
+// user, leaving the "[CODE] …" prefix out of a capability detail that `neru
+// doctor` prints verbatim.
+func userFacingReason(err error) string {
+	var domainErr *derrors.Error
+	if errors.As(err, &domainErr) {
+		return domainErr.Message()
+	}
+
+	return err.Error()
+}
+
 // unavailableDetail explains why a probed capability is unavailable, in terms
 // the user can act on.
 func (s *SystemAdapter) unavailableDetail(feature string, cause error) string {