feat(cli): check the desktop

komorebi fails quietly when the desktop is not what it was made for: over ssh
there is no session bus, a daemon whose script is not in KWin tiles nothing
while it runs, and komorebi needs KWin 6. `komorebic check` now looks at the
desktop after the configuration, and `--configuration-only` leaves that out for
a machine that is not the one komorebi will run on.

It looks at the session (KDE, Wayland), the session bus, KWin on it and KWin's
version, the daemon and its script (the daemon is running when its socket takes
a connection, the script is in KWin when KWin says it has loaded it), and what
starts komorebi at login. A bus that cannot be connected to or does not answer,
and no KWin on it, are errors, and the looking stops there because nothing after
them can be answered. Every call has two seconds to answer, so a bus that never
does cannot hold the check.

The test of the missing session bus used to remove the address and the runtime
directory from the environment and so depended on it: a machine with a user bus
at /run/user/UID/bus answered it. It now gives an address with no socket behind
it. A bus that accepts and never answers, the autostart finding and
--configuration-only have tests too, and the VM suite vm-check runs the command
against a real KWin with the daemon running, with its script gone, with no
daemon and with no KWin on the bus.

It also looks at the two effects KWin draws and animates with, and at the Plasma
shell. Only komorebi's builds of them do everything komorebi asks (a color for
each kind of window, every animation style), so the check tells a build by what
it contains: the interface of the border effect in its plugin file or its object
on the bus, a Curve setting in the animation effect's script. It looks for them
where KWin looks, from KWin's own environment, and a stock effect is a warning
only when the configuration asks for what it cannot do (borders, an animation
style other than the stock curve), and so is a copy in the user's own data
directory that hides komorebi's. The Plasma shell is looked for when the file
has wallpapers. vm-check runs all of it against KWin.
This commit is contained in:
LGUG2Z committed 2026-10-28 07:20:57 -07:00
1 parent d04fc91234
commit 44f7236698
13 files changed
+1171 -23

No files matched your search

+35 -3
View File
@@ -967,6 +967,28 @@ file's when it has none). [`check_configuration`] also returns the [`Wants`] of
it draws borders, which animation style it asks for and whether it has wallpapers. `komorebic`
prints [`Report::render`] and exits with status 1 if [`Report::has_errors`].
[`check_environment`] looks at the desktop, with D-Bus calls of its own on the session bus (they
are in the table of [PLATFORM.md](PLATFORM.md#d-bus)), and `komorebic check --configuration-only`
leaves it out. It looks in this order at the session (`XDG_CURRENT_DESKTOP` and
`XDG_SESSION_TYPE`, each a warning when it is not what komorebi is made for), the session bus, KWin
on it (`NameHasOwner`), KWin's version (the line `KWin version:` of `supportInformation`), the daemon
(a connection to `komorebi.sock`) and its script (`isScriptLoaded`), the two effects, the Plasma
shell when the file has wallpapers (`NameHasOwner` of `org.kde.plasmashell`), and last at what
starts komorebi at login. A bus that cannot be connected to or does not answer, and no KWin on it,
are errors, and the looking stops there: everything after depends on them. Every call has two
seconds to answer, so a bus that never does cannot hold the check.
The two effects are not part of KWin, and only komorebi's builds of them do everything komorebi
asks: a color for each kind of window (KDE Rounded Corners) and every `animation.style` (Geometry
Change). The stock builds have a color for the active window and one for the others, and one curve,
an exponential ease out. The check tells a build by what it contains: the plugin file of the border
effect has the name of the interface `org.komorebi.BorderColours1` (or its object is on the bus),
and the script of the animation effect reads a `Curve` setting. It looks for them where KWin looks,
which it reads from KWin's own environment (`/proc/PID/environ`, PID being the owner of
`org.kde.KWin`), because the shell the command is typed in has other directories than a session.
What the file asks of the effects is its [`Wants`]: a stock effect is a warning only when the file
asks for what it cannot do.
| Rule | Enforced by | Proof | Escape hatch |
|---|---|---|---|
| A key komorebi does not read does not stop a configuration from loading | serde: [`StaticConfig`] ignores unknown keys, and a key of another platform is a field nothing reads | `the_keys_that_do_nothing_on_kde_are_accepted_and_ignored`, `fixtures_load_round_trip_and_only_lose_windows_only_keys` | none |
@@ -978,6 +1000,12 @@ prints [`Report::render`] and exits with status 1 if [`Report::has_errors`].
| The keys the check knows are the ones komorebi reads, at every level | framework path: [`known_keys`] reads them from the schema of [`StaticConfig`] | `the_keys_come_from_the_schema_at_every_level`, `a_whole_example_configuration_has_nothing_the_check_does_not_know` | built without the `schemars` feature, the check does not look at keys |
| Placement rules that are not used while windows are appended are a note, and a workspace that creates containers is not told so whatever the file says | framework path: [`check_configuration`] reads the workspace's `window_container_behaviour` before the file's | `placement_rules_that_are_not_used_while_windows_are_appended_are_noted` | none |
| A wallpaper that is not a file is an error, and a picture no theme can be made from is a warning | framework path: [`check_configuration`] looks at the wallpaper of each monitor and workspace once, and asks the theme generator for a palette when the wallpaper does not turn it off | `a_wallpaper_that_is_not_there_and_a_rules_file_that_is_not_there_are_found`, the `vm-check` VM suite for the warning | none |
| No session bus, or no KWin on it, is an error, and the desktop is looked at no further | framework path: [`check_environment`] returns at the first finding the rest depends on | `without_a_session_bus_the_desktop_is_an_error`, `vm-check` | none |
| An effect is komorebi's build because of what it contains, not because of its name | framework path: [`check_environment`] looks for the colors interface in the border effect's plugin file (or its object on the bus) and for a `Curve` setting in the animation effect's script | `the_border_effect_is_komorebis_when_it_has_the_colours_interface`, `the_effects_are_told_apart_by_what_they_contain` | none |
| Effects are looked for where KWin looks, not where the shell that runs the command would | framework path: [`check_environment`] reads KWin's environment from `/proc` | `vm-check` | none |
| A daemon that is running without its script in KWin is an error | framework path: [`check_environment`] compares the connection to the daemon's socket with KWin's answer to `isScriptLoaded` | `vm-check` | none |
| No call of the desktop check delays it by more than two seconds | convention: every call goes through one timeout (`within`) | `a_session_bus_that_never_answers_is_given_up_on` | none |
| `--configuration-only` leaves the desktop out | framework path: the section is pushed only without it | `configuration_only_leaves_the_desktop_out` | none |
| `komorebic check` exits with status 1 if and only if a finding is an error | framework path: `komorebic` exits through [`Report::has_errors`] | `a_good_configuration_passes`, `a_typo_is_a_warning_with_the_word_that_was_meant_and_does_not_fail`, `a_file_that_is_not_json_fails_and_shows_the_line` | none |
| The rules of an applications file and of the configuration add up | framework path: both are appended to the process-wide lists | `the_rules_of_the_configuration_and_of_the_file_add_up`, `every_file_of_a_list_is_read` | none |
| `schema.json` and `schema.asc.json` are what the Rust types print | Nix check `schema-fresh`, and a test that compares them with `komorebic`'s output | `schema-fresh`, `the_schema_files_of_the_repository_are_what_the_subcommands_print` | `just jsonschema` |
@@ -1251,8 +1279,9 @@ module's unit.
see-through, and the opacity they are given.
- [`kwin::effects`](../../komorebi/src/kwin/effects.rs): the KWin effect that draws the border,
its settings and the state komorebi keeps of it.
- [`check`](../../komorebi/src/check.rs): the checks behind `komorebic check`, the [`Finding`]s
they return and the [`Report`] `komorebic` gathers them in.
- [`check`](../../komorebi/src/check.rs): the checks behind `komorebic check` (the configuration,
and the desktop it runs on), the [`Finding`]s they return and the [`Report`] `komorebic` gathers
them in.
- [`process_command`](../../komorebi/src/process_command.rs): the thread that listens on the
socket, and what the window manager does with each message.
- [`state`](../../komorebi/src/state.rs): the [`State`] a `State` message is answered with,
@@ -1566,7 +1595,9 @@ A window is shown, and ends up on a tile:
format.
- [`komorebi/src/check.rs`](../../komorebi/src/check.rs): the checks of `komorebic check`, with
their tests; [`komorebic/tests/check.rs`](../../komorebic/tests/check.rs) runs the command on
configurations and reads what it prints and its exit status.
configurations and on buses that are not there, and reads what it prints and its exit status;
[`nix/tests/vm/suites/check`](../../nix/tests/vm/suites/check/test.py), the desktop check against
a real KWin, with the daemon running, with its script gone, with no daemon and with no KWin.
- [`komorebi/src/process_event.rs`](../../komorebi/src/process_event.rs): what each event
does, and the thread that handles them.
- [`komorebi/src/process_command.rs`](../../komorebi/src/process_command.rs): the socket, what
@@ -1727,6 +1758,7 @@ A window is shown, and ends up on a tile:
[`Report::render`]: ../../komorebi/src/check.rs
[`Report::has_errors`]: ../../komorebi/src/check.rs
[`check_configuration`]: ../../komorebi/src/check.rs
[`check_environment`]: ../../komorebi/src/check.rs
[`check_keys`]: ../../komorebi/src/check.rs
[`known_keys`]: ../../komorebi/src/check.rs
[`snippet`]: ../../komorebi/src/check.rs
+9
View File
@@ -367,6 +367,15 @@ read the file (a daemon that is running keeps what it had), so the check shows t
with status 1. A workspace that is only a name is a warning too: it is not tiled, which is easy to
do without meaning to.
## Why is a daemon that runs without its script in KWin an error, and one that does not run a note?
A daemon without its script in KWin cannot see a window, so it tiles nothing while it runs: that
is an error, the one finding of the desktop check that says a daemon which is running is broken.
A daemon that is not running is not broken, so it is a note, with the command that starts it. A
script that is still in KWin when its daemon is gone is a warning, since starting the daemon
replaces it. The check tells which of the three it is by connecting to the daemon's socket and by
asking KWin whether it has loaded `komorebi-bridge`.
## Why does `nix/komorebi-options.nix` start with the hash of the schema?
Because the check that the options are fresh cannot make them again. `schemars-nixgen` makes
+40 -1
View File
@@ -275,6 +275,23 @@ The property `desktops` is introspected as `a(iss)`, a position, an id and a nam
desktop, and the value on the wire is `a(uss)`: komorebi reads it as that. It is read uncached,
since a read right after `createDesktop` has to see the new desktop.
What `komorebic check` calls, in this order, each with two seconds to answer:
| Name | Object | Interface | Member | For |
|---|---|---|---|---|
| `org.freedesktop.DBus` | `/org/freedesktop/DBus` | `org.freedesktop.DBus` | `NameHasOwner(s) -> b` | whether `org.kde.KWin` is on the bus |
| `org.freedesktop.DBus` | `/org/freedesktop/DBus` | `org.freedesktop.DBus` | `GetConnectionUnixProcessID(s) -> u` | the process that owns `org.kde.KWin`, whose environment says where KWin looks for effects |
| `org.kde.KWin` | `/KWin` | `org.kde.KWin` | `supportInformation() -> s` | KWin's version: the line `KWin version: X.Y.Z` of the text |
| `org.kde.KWin` | `/Scripting` | `org.kde.kwin.Scripting` | `isScriptLoaded(s) -> b` | whether the script `komorebi-bridge` is loaded |
| `org.kde.KWin` | `/Effects` | `org.kde.kwin.Effects` | `isEffectSupported(s) -> b` | whether the border effect (`kwin4_effect_shapecorners`) and the animation effect (`kwin4_effect_geometry_change`) are installed |
| `org.kde.KWin` | `/org/komorebi/BorderColours` | `org.freedesktop.DBus.Introspectable` | `Introspect() -> s` | whether komorebi's build of the border effect is loaded: its object has the interface `org.komorebi.BorderColours1` |
| `org.freedesktop.DBus` | `/org/freedesktop/DBus` | `org.freedesktop.DBus` | `NameHasOwner(s) -> b` | whether `org.kde.plasmashell` is on the bus, when there are wallpapers |
At time of writing (2026-10-27), the headless KWin of the VM tests (Plasma 6.8) answers
`supportInformation` with a text that has that line, and `vm-check` has `komorebic check` read the
major version from it. The check does not need the answer: without the line it says that KWin is
there and its version could not be read.
## Files and directories
| Path | What | Lifetime |
@@ -296,13 +313,35 @@ since a read right after `createDesktop` has to see the new desktop.
Without `XDG_RUNTIME_DIR` the bridge and the socket are in `komorebi` in the local data
directory instead, with the logs (see [`XDG_DATA_HOME`](#xdg_data_home)).
## What `komorebic check` looks at
Apart from the bus, it looks at the files that start komorebi at login, in this order, and says which
it found first: `$XDG_CONFIG_HOME/autostart/komorebi.desktop` (the autostart entry),
`$XDG_CONFIG_HOME/systemd/user/komorebi.service`, `/etc/systemd/user/komorebi.service` and
`/run/current-system/etc/systemd/user/komorebi.service`, where the NixOS module's unit is. Whether
the daemon is running is whether `komorebi.sock` in the runtime directory takes a connection, and
the session is the environment of the command itself: `XDG_CURRENT_DESKTOP` has to name KDE, and
`XDG_SESSION_TYPE` or `WAYLAND_DISPLAY` Wayland.
The effects are looked for where KWin looks, which is not where the shell that runs the command
looks: KWin is started by the session, with a `QT_PLUGIN_PATH`, an `XDG_DATA_HOME` and an
`XDG_DATA_DIRS` of its own. `komorebic check` reads them from `/proc/PID/environ`, PID being what
the bus says owns `org.kde.KWin`, and falls back to its own environment and to the places NixOS and
the common distributions put plugins and data. The border effect is a plugin file,
`kwin/effects/plugins/kwin4_effect_shapecorners.so`, in a Qt plugin directory, and the animation
effect a script, `kwin/effects/kwin4_effect_geometry_change/contents/code/main.js`, in a data
directory, where KWin takes the user's before the system's. A build is komorebi's by what it
contains: the plugin file has the name of the interface `org.komorebi.BorderColours1` (or its object
is on the bus), and the script reads a setting called `Curve`.
## Environment variables
### `DBUS_SESSION_BUS_ADDRESS`
The address of the session bus. If it is not set, komorebi uses `$XDG_RUNTIME_DIR/bus`, where
systemd puts the session bus, and `/run/user/<uid>/bus` when `XDG_RUNTIME_DIR` is not set
either. An address with no bus behind it is the first error under [No KWin](#no-kwin).
either. An address with no bus behind it is the first error under [No KWin](#no-kwin), and the one
`komorebic check` reports as "could not connect to the session bus".
### `KOMOREBI_CONFIG_HOME`