Deamon management

AGENTS.md

@@ -1,15 +1,19 @@
 # AGENTS.md
 
 ## What this is
-A pure GTK4 C++ GUI for remapping the G1–G9 keys of a Logitech G910. Today it
-only edits and persists mappings: there is **no** hardware G-key detection and
-**no** command execution yet (a native daemon is the planned next step). The
-code is split into a few small translation units under `src/` (see below).
+A pure GTK4 C++ GUI plus a background daemon for remapping the G1–G9 keys of a
+Logitech G910. The GUI edits and persists mappings; the daemon reads the G-keys
+and replays the configured action. Hardware G-key detection and action execution
+live in the daemon, not the GUI. Code is split across `src/` (GUI), `shared/`
+(common) and `daemon/`.
 
 ## Build / run / verify
-- `make` — builds the `gkeymapper` binary **and** the `.mo` catalogs.
-  Needs `g++` (C++17), `make`, `gettext`, `libgtk-4-dev` (see README for
-  `apt install` on a fresh machine).
+- `make` — builds the `gkeymapper` GUI, the `gkeymapper-daemon` and the `.mo`
+  catalogs. Needs `g++` (C++17), `make`, `gettext`, `libgtk-4-dev`,
+  `libusb-1.0-0-dev` and `libxkbcommon-dev` (see README for `apt install` on a
+  fresh machine).
+- `make daemon` — builds only `gkeymapper-daemon` (needs libusb + xkbcommon,
+  not GTK).
 - `make translations` — only runs `msgfmt` on the existing `.po` files.
 - `make run` — builds, then runs with `GKEYMAPPER_LOCALEDIR=$PWD/locale` and
   `GKEYMAPPER_ASSETS_DIR=$PWD/assets` so the working-tree translations and
@@ -30,18 +34,34 @@ code is split into a few small translation units under `src/` (see below).
   `po/de.po`.
 
 ## Code layout and conventions
-- Modules under `src/` (shared API lives in `namespace gkeymapper`):
-  `keyrow.h` (`KeyRow`, `kNumKeys`), `mappings.{h,cpp}` (config file I/O),
-  `capturedialog.{h,cpp}` (key-capture dialog), `main.cpp` (app actions + UI).
-- The Makefile globs sources (`$(wildcard src/*.cpp)`): a new `.cpp` is compiled
-  automatically, and `src/*.h` are prerequisites of the target.
+- Modules under `src/` (GUI), `shared/` (used by both binaries) and `daemon/`
+  (the background service). Shared API lives in `namespace gkeymapper`.
+  `shared/mapping` owns the mappings file format, `shared/keys` the canonical
+  key-name table (lowercase GDK names -> Linux `KEY_*`).
+- The Makefile globs sources: `make` builds the GUI (`src/*.cpp` + `shared/*.cpp`)
+  **and** the daemon (`daemon/*.cpp` + `shared/*.cpp`, needs `libusb-1.0-0-dev`
+  and `libxkbcommon-dev`). `make daemon` builds only the daemon.
+- The daemon is split into: `device_tables` (raw HID report tables per model),
+  `g910_device` (libusb open/detach/claim/read), `uinput_keyboard` (virtual
+  keyboard), `action` (dispatch `key`/`command`/`disabled`) and `config_watch`
+  (inotify auto-reload of the mappings file). `shared/keymap` does the layout
+  lookups for both sides. The hot path never touches the GUI.
+- `make install` (PREFIX default `/usr/local`) also installs the packaging
+  files from `data/`: the udev rule, the `modules-load.d` fragment and the
+  systemd **user** unit. The unit contains an `@BINDIR@` placeholder that the
+  Makefile substitutes with `$(PREFIX)/bin`. Keep it a user service — it needs
+  the session for `/dev/uinput` and `DISPLAY`.
+- Daemon config reload: `config_watch` watches the config **directory** (so an
+  atomic save via `rename` is caught) and reports a change at most once per loop
+  iteration, which is the coalescing window. `SIGHUP`/`SIGUSR1` remain as a
+  fallback. A failed reload keeps the previous mappings on purpose.
 - `main.cpp` keeps the `rows` vector (one `KeyRow` per G key, widget pointers)
-  in an anonymous namespace; mappings functions receive it as a parameter.
-  `on_activate` registers the app actions `app.export-config`,
-  `app.import-config`, `app.about`; `build_ui` constructs the window. App id:
+  in an anonymous namespace; `src/mappings.cpp` is GUI glue that moves data
+  between the widgets and the shared `MappingSet`. App id:
   `com.example.gkeymapper`.
 - The Type dropdown index is meaningful everywhere: `0=Key`, `1=Command`,
-  `2=Disabled`. Keep that order — import/export map against it.
+  `2=Disabled`, matching `ActionType` and the `key`/`command`/`disabled` tokens
+  in the file. Keep that order.
 - The capture dialog's `CaptureSession` is heap-allocated and freed only by the
   window's `"destroy"` handler. Always close the dialog with
   `gtk_window_destroy` so the session is released.
@@ -68,13 +88,69 @@ G3=disabled:
 
 `<type>:<target>`, one line per key. `key` is a captured sequence (lowercase
 `gdk_keyval_name` output; modifiers joined with `+`, steps joined with `,`),
-`command` is a program/file path, `disabled` is inactive.
+`command` is a program path or command line, `disabled` is inactive. The
+canonical modifier order is `ctrl`, `alt`, `shift`, `super`, `altgr`
+(`format_shortcut_step()`; parsing accepts any order).
+
+Key names are **layout independent**: `shared/keymap` resolves a name like `z`
+to the key that produces `z` on the active layout (read from
+`/etc/default/keyboard`, `XKBLAYOUT`) via xkbcommon — on a German keyboard `z` is
+evdev 21, not the US position 44. `shared/keys` maps names to the US positions
+and is only the fallback. When you add key names, keep them lowercase GDK keysym
+names. `parse_shortcut()` takes an optional resolver for this (the daemon passes
+one).
+
+The capture dialog stores the **base (level 0) key**: it uses
+`Keymap::base_key_name(keycode)` instead of GDK's shifted keyval, so
+`Shift`+ß becomes `shift+ssharp` (not `shift+question`, which would double the
+shift). `format_shortcut_step()` — not the dialog — renders a step from a
+`ModifierBit` mask, so the order stays in one place.
+
+AltGr (level 3) is recorded as the `altgr` modifier plus the base key
+(`AltGr`+7 → `altgr+7`). GTK4 dropped the `GDK_MOD5_MASK` name, so the dialog
+tracks `ISO_Level3_Shift` / `Mode_switch` through its own key press/release
+(`CaptureSession::altGrHeld`) instead of a state bit. On the replay side
+`kModAltGr` maps to `KEY_RIGHTALT`.
 
 ## Assets
 `find_asset()` resolves in order: `$GKEYMAPPER_ASSETS_DIR` → `./assets` →
 compiled-in `ASSETS_DIR` (`/usr/local/share/gkeymapper/assets`). The icon
 (`assets/icon.png`) is used in the header bar and the About dialog.
 
+## Driving the daemon for manual checks
+- The process name is truncated by the kernel to 15 chars, so `pkill -x
+  gkeymapper-daemon` and `pgrep -x gkeymapper-daemon` **never match**. Use
+  `pkill -x gkeymapper-daem` / `pgrep -x gkeymapper-daem` (or `pkill -f
+  './gkeymapper-daemon'`).
+- Run it in the background with `setsid nohup ./gkeymapper-daemon [config]
+  > /tmp/daemon.log 2>&1 < /dev/null &`; it survives across shell calls. It
+  takes an optional config path as `argv[1]` (default
+  `~/.config/gKeyMapper/mappings.conf`).
+- `SIGHUP`/`SIGUSR1` reload the mappings
+  (`kill -HUP $(pgrep -x gkeymapper-daem)`). Normally you do not need them: the
+  config file is watched, so saving in the GUI reloads within about half a
+  second. Use `SIGHUP` to check the signal path after touching it.
+- Test the auto-reload without hardware: write the config through the shared
+  save path (atomic temp+rename, as the GUI does) and watch `/tmp/daemon.log`
+  for a second `loaded ...` line. `daemon/config_watch.cpp` also has a
+  standalone test shape: create a `ConfigWatcher`, `poll_events()` then
+  `take_change()` per simulated loop iteration.
+- `make install DESTDIR=/tmp/stage` stages the packaging files; inspect
+  `/tmp/stage/usr/local/lib/...` to verify the unit's `ExecStart` substitution.
+  `systemd-analyze --user verify <unit>` checks the unit. There is no
+  `udevadm verify` on systemd 249, so the udev rule is checked by eye against
+  the reference project's rule.
+- Starting it detaches the kernel driver from the vendor interface and creates a
+  `/dev/uinput` keyboard. Warn the user first: while it runs the media keys may
+  not work, and `key` mappings are injected into the **focused** window.
+- The keyboard is `046d:c32b` (also handle `046d:c335`); on this machine the USB
+  device and `/dev/uinput` already carry ACLs for the user, so no root is needed.
+- Verify decoding by pressing G keys and reading `/tmp/daemon.log` (it logs
+  `G1 -> key:...` per press). Verify what the virtual keyboard emits at the X
+  level with `xinput test <keyboard-id>` (`gKeyMapper virtual keyboard` shows up
+  as both a pointer and a keyboard — use the **keyboard** id). X keycodes are
+  evdev codes + 8. There is no `xdotool`/`wtype`.
+
 ## Driving the GUI for manual checks
 There is no `xdotool`/`wtype` on this machine, and the capture-dialog buttons
 (`Clear`/`Cancel`/`Done`) expose an empty AT-SPI accessible name — the text is in