docs(dev): the cutover account in the map, the summary and the unified-binaries note

ARCHITECTURE-UNIFIED.md: the status line, section 1 (a table of where each platform is now),
the package paragraph (shims gone, version crate), the oracle paths (schemas/*, docs/*/cli),
section 6 (now "done / still open" instead of "what is still the old layout"), the tier-0 row,
and the helper tools paragraph (tools/ is committed now).
MIGRATION-SUMMARY.md: status line, the three-trees paragraph, the oracle paths, the known
issues paragraph, and section 7, which was "Cutover list (not done)" and is now a table of what
the cutover stack did and what is open; item 7 of "How to continue".
unified-binaries.md: the status banner (with a map from the old directory names to the new
ones), the Mac Mini commands (the shim line removed, schema.bar.json under schemas/macos,
`komorebi 0.2.0`), and "What is left for the cutover" is now a done / still open list.

Still open, as stated in the three: the one flake (flake-one is writing it), CI and release
workflows (the old ones are archived in docs/dev/old-ci), the site and repository URLs,
COMPARE.md. The 0.1.42 / 0.1.0 / 0.1.1 numbers and the old directory names that stay in
narrative sections are history and are marked as such. Not touched: build-and-test.md and
flake.md (owned by flake-one).

Verified: the relative links of the three files resolve. The statements about what the stack
did are taken from the revision descriptions of wip-cutover, not re-measured.
This commit is contained in:
LGUG2Z committed 2026-11-05 15:03:27 -08:00
1 parent f82fe692fc
commit 1b3178cede
3 files changed
+121 -76

No files matched your search

+68 -40
View File
@@ -1,29 +1,36 @@
# komorebi after the consolidation: a map of the repository
Status (wip-cand4): current map. Windows, KDE Plasma and macOS build from one workspace and one
`komorebi`, one `komorebic`, one `komorebi-client` and one `komorebi-bar` package, the platform chosen by
`cfg(target_os)`. The cutover (shim packages, one flake, final directories, one version number) is not done;
section 6 lists what is still old. macOS has only been type-checked on Linux and compiled/unit-tested on a
Mac Mini; no macOS daemon behaviour has been observed.
Status (the cutover stack, `wip-cutover`): current map. Windows, KDE Plasma and macOS build from one
workspace (version 0.2.0) and one `komorebi`, one `komorebic`, one `komorebi-client` and one `komorebi-bar`
package, the platform chosen by `cfg(target_os)`. The shim packages are gone, the directories are the final
ones and there is one `komorebi-version` crate; the one flake is being written by another agent
(`flake-one`) and CI and releases are not done: section 6 says what is done and what is open. macOS has
only been type-checked on Linux and compiled/unit-tested on a Mac Mini; no macOS daemon behaviour has been
observed. Documents below that give a measurement or a decision keep the paths and numbers of their time
(`komorebi-for-kde/`, `komorebi-for-mac/`, 0.1.42, `kfde-*`); the table in section 1 says where things are now.
How to build and test: [build-and-test.md](build-and-test.md). Why things are shaped as they are:
[seam.md](seam.md) (the `Backend` trait), [core-model.md](core-model.md) (the shared model),
[settings.md](settings.md), [unified-binaries.md](unified-binaries.md), [bar-unification.md](bar-unification.md),
[backend-switch.md](backend-switch.md). What a person with a Mac has to check: [macos-handcheck.md](macos-handcheck.md).
## 1. Three platform trees, one workspace
## 1. Three platforms, one workspace, one directory level
The root `Cargo.toml` is the only workspace. It has members in three places:
The root `Cargo.toml` is the only workspace. Its members are all at the top level or under `crates/`;
the platform-specific parts are:
| Tree | What is in it | Platform |
| Platform | Where it is | What is in it |
|---|---|---|
| the repository root (`komorebi/`, `komorebi-bar/`, `komorebic/`, ...) | the Windows daemon library, the unified packages, the Windows-only tools (`komorebi-gui`, `komorebi-shortcuts`, `komorebic-no-console`), `komorebi-layouts`, `komorebi-scrolling`, `komorebi-themes`, `e2e/`, `wix/` | Windows (the original) |
| `komorebi-for-kde/` | the KDE daemon library `komorebi-linux` (`komorebi/`), `komorebi-hotkeys/`, the `version-linux` crate, the NixOS module, the VM test suites (`nix/tests/vm`), KDE docs (`docs/dev`) | Linux, KDE Plasma on KWin (Wayland) |
| `komorebi-for-mac/` | the macOS daemon library `komorebi-macos` (`komorebi/`), the `version-macos` crate, the nix darwin module, macOS docs | macOS |
| Windows (the original) | `komorebi-windows/` (the daemon library), `komorebi-bar/`, `komorebic/`, `komorebi-gui/`, `komorebi-shortcuts/`, `komorebic-no-console/`, `komorebi-layouts/`, `komorebi-scrolling/`, `komorebi-themes/`, `e2e/`, `wix/`; docs in `docs/` | the Windows daemon library, the unified packages, the Windows-only tools |
| Linux, KDE Plasma on KWin (Wayland) | `komorebi-linux/` (the daemon library), `komorebi-hotkeys/`, `nix/linux/` (NixOS module, VM test suites in `nix/linux/tests/vm`, KWin effects), `scripts/linux/`, `spikes/`; docs in `docs/linux/` | the KDE daemon library, the key binding crate, the NixOS module and the VM tests |
| macOS | `komorebi-macos/` (the daemon library), `nix/macos/`; docs in `docs/macos/` | the macOS daemon library and the nix-darwin module |
`komorebi-for-kde/` and `komorebi-for-mac/` still have their own flakes, `justfile`s and docs; the root flake
imports them as `kfde-*` and `kfm-*` (section 5). They have no `Cargo.toml` workspace of their own any more:
`cargo` run inside them uses the root one.
Shared: `crates/` (including `crates/komorebi-version`, the version string of the Linux and macOS
binaries), `schemas/{windows,linux,macos}/` (the generated JSON schemas), one `deny.toml`, `rustfmt.toml`,
`rust-toolchain.toml`, `.gitignore`, `LICENSE.md` and `justfile` at the root. The old repositories'
workflows, dependabot files, the Homebrew formula template and the macOS docs-site files are kept, inert, in
`docs/dev/old-ci/{linux,macos}/` for the CI and release plan. There is no `komorebi-for-kde/` or
`komorebi-for-mac/` any more except the two flakes that `flake-one` is replacing.
## 2. The packages (what a user runs)
@@ -34,14 +41,14 @@ imports them as `kfde-*` and `kfm-*` (section 5). They have no `Cargo.toml` work
| `komorebi-client` (library) | `komorebi-client/` | `src/windows.rs`, `src/linux.rs`, `src/macos.rs` re-export the daemon library of the target OS behind one `Connection` |
| `komorebi-bar` (`komorebi-bar`) | `komorebi-bar/` | `src/windows/` and `src/macos/` modules; shared code in `crates/komorebi-bar-core`. **KDE has no bar** |
The daemon libraries are `komorebi-windows` (`komorebi/`), `komorebi-linux` (`komorebi-for-kde/komorebi/`) and
`komorebi-macos` (`komorebi-for-mac/komorebi/`). They have no binary: each has a `daemon.rs` with
`run()`, the old `main`. `-p komorebi-windows` etc. still build, as libraries.
The daemon libraries are `komorebi-windows` (`komorebi-windows/`), `komorebi-linux` (`komorebi-linux/`) and
`komorebi-macos` (`komorebi-macos/`). They have no binary: each has a `daemon.rs` with
`run()`, the old `main`. `-p komorebi-windows` etc. build them, as libraries.
Shim packages exist until the cutover (each is a `#[path]` include of the unified module, same binary
name): `komorebic-linux`, `komorebic-macos`, `komorebi-client-linux`, `komorebi-client-macos`,
`komorebi-bar-macos`. Never build `komorebic` together with `komorebic-linux` or `komorebic-macos`: the
binary name is the same.
The shim packages (`komorebic-linux`, `komorebic-macos`, `komorebi-client-linux`, `komorebi-client-macos`,
`komorebi-bar-macos`, each a `#[path]` include of the unified module) were deleted in the cutover stack, and
so were `version-linux` and `version-macos` (now `crates/komorebi-version`). To build a platform use the
one package name, for example `-p komorebic -p komorebi-client -p komorebi-bar -p komorebi-macos` on macOS.
## 3. The shared crates (`crates/`)
@@ -76,7 +83,7 @@ These are intentional, not leftovers; before "unifying" one, read the document n
- The bar: [bar-unification.md](bar-unification.md): one package, one module per OS; rendering code differs
(frame margins, `network.rs`, window seams) and B4 (merging it) was not done.
- Command line: each platform keeps its help text and its own commands (Windows 34, KDE 2, macOS 1 are
platform-only; most are common). `komorebic` pages in `docs/cli` of each tree are the oracle.
platform-only; most are common). `komorebic` pages in `docs/cli`, `docs/linux/cli` and `docs/macos/cli` are the oracle.
- macOS: everything except compile and unit tests is unverified; [macos-handcheck.md](macos-handcheck.md).
- KDE: no bar; hotkeys through `komorebi-hotkeys` and exported KDE shortcuts; the module is NixOS.
- Windows: the e2e under QEMU (`e2e/`), `komorebi-gui`, `komorebi-shortcuts`, `komorebic-no-console`, wix.
@@ -86,10 +93,10 @@ These are intentional, not leftovers; before "unifying" one, read the document n
| Oracle | Where | Detects | Run by |
|---|---|---|---|
| Wire goldens | `crates/komorebi-protocol/tests/golden*` | a change of what each daemon sends or accepts on the socket | `cargo test -p komorebi-protocol` |
| Config schemas | `schema.json`, `schema.asc.json` of the three trees; `crates/komorebi-config/tests/schemas.rs`; KDE `komorebi/tests/schemas.rs` | a changed key of `komorebi.json` | `cargo test -p komorebi-config` (KDE: `-p komorebi-linux --test schemas -- --test-threads=1`) |
| Bar schema views | `schema.bar.json` (Windows), `komorebi-for-mac/schema.bar.json`; `crates/komorebi-bar-core/tests/schema_oracle.rs` pins size and hash; `komorebi-bar --schema` prints the view of the target OS | a changed bar configuration | `cargo test -p komorebi-bar-core`; Windows e2e scenario `bar` compares `--schema` byte for byte |
| CLI docs | `docs/cli` of each tree; `crates/komorebic-core/tests/docs_cli.rs` and `platforms.rs` | a changed subcommand or help text | `cargo test -p komorebic-core`; `komorebic docgen --output DIR` regenerates |
| Schema docs completeness | `check_schema_docs.py` (root) | schema entries with no description | by hand |
| Config schemas | `schemas/{windows,linux,macos}/schema.json` and `schema.asc.json`; `crates/komorebi-config/tests/schemas.rs`; KDE `komorebi-linux/tests/schemas.rs` | a changed key of `komorebi.json` | `cargo test -p komorebi-config` (KDE: `-p komorebi-linux --test schemas -- --test-threads=1`) |
| Bar schema views | `schemas/windows/schema.bar.json`, `schemas/macos/schema.bar.json`; `crates/komorebi-bar-core/tests/schema_oracle.rs` pins size and hash; `komorebi-bar --schema` prints the view of the target OS | a changed bar configuration | `cargo test -p komorebi-bar-core`; Windows e2e scenario `bar` compares `--schema` byte for byte |
| CLI docs | `docs/cli`, `docs/linux/cli`, `docs/macos/cli`; `crates/komorebic-core/tests/docs_cli.rs` and `platforms.rs` | a changed subcommand or help text | `cargo test -p komorebic-core`; `komorebic docgen --output DIR` regenerates |
| Schema docs completeness | `check_schema_docs.py` (root; the macOS copy is archived in `docs/dev/old-ci/macos/`) | schema entries with no description | by hand |
| Drift of derivations | `nix eval .#packages.x86_64-linux.default.drvPath` and the check derivations | an unintended change of what nix builds | by hand (see build-and-test.md) |
| Backend contract | `komorebi-backend/src/contract.rs` | a backend that breaks a rule of the trait | `cargo test -p komorebi-backend` and each daemon's tests |
| Runtime | Windows e2e (QEMU), KDE VM suites | real behaviour | tier 3 below |
@@ -97,37 +104,58 @@ These are intentional, not leftovers; before "unifying" one, read the document n
Windows `docs/cli` was found stale against the binary in the step-4 measurement (see the progress notes,
decision D20); regenerate before treating it as an oracle.
## 6. What is still the old layout (cutover list)
## 6. The cutover: done, and still open
Shim packages and their directories under `komorebi-for-kde/` and `komorebi-for-mac/`; `version-linux` and
`version-macos`; three flakes (the root one imports the other two as `kfde-*` and `kfm-*`); three `deny.toml`;
three version numbers (Windows libraries and packages 0.1.42, KDE 0.1.0, macOS library 0.1.1 and its `version` crate 0.1.0). Some docs still describe the old layout; those that were
found wrong have been corrected, [COMPARE.md](../../komorebi-for-kde/docs/dev/COMPARE.md) is marked stale.
`komorebi-for-kde/justfile` still has recipes written for a KDE-only workspace (`just check` runs
`cargo test --workspace`, which on Linux would build the Windows crates): use the commands in
build-and-test.md.
Done in the cutover stack (`jj log -r 'wip-main..wip-cutover'`, one revision per concern):
- one workspace version, 0.2.0, for every package (the tables of older documents that say 0.1.42, 0.1.0
and 0.1.1 are history); one `komorebi-version` crate instead of `version-linux` and `version-macos`;
- the shim packages `komorebic-linux`, `komorebic-macos`, `komorebi-client-linux`, `komorebi-client-macos`
and `komorebi-bar-macos` deleted;
- the directories renamed: `komorebi/` to `komorebi-windows/`, the KDE and macOS libraries to
`komorebi-linux/` and `komorebi-macos/`, `komorebi-hotkeys/` to the top level; `docs/{linux,macos}`,
`nix/{linux,macos}`, `scripts/linux`, `spikes/`, `schemas/{windows,linux,macos}`;
- one `deny.toml`, `rustfmt.toml`, `rust-toolchain.toml`, `.gitignore`, `LICENSE.md` and `justfile`;
`tools/format-all` checks one group;
- the documents, scripts and comments that named the old paths name the new ones (the Windows docs site
excludes `docs/linux`, `docs/macos` and `docs/dev`).
Still open:
- the one root flake: three flakes become one, written by the agent `flake-one`; until it lands the
nix commands in [build-and-test.md](build-and-test.md) and the flake attribute names in the scripts and
runbooks (`.#kfde-...`, `.#kfm-...`, `legacyPackages.*.vm.NAME`) are the old ones;
- CI and release: the workflows of the old repositories are archived, inert, in `docs/dev/old-ci/`; no
workflow builds the Linux or macOS packages, and there is one release plan to write;
- where the repository and the sites are published: URLs of the old projects
(`LGUG2Z/komorebi-for-kde`, `LGUG2Z/komorebi-for-mac`, `komorebi-for-mac.lgug2z.com`, the update check of
the macOS bar, `$schema` URLs of example configs and schemas) are unchanged;
- `docs/linux/dev/COMPARE.md` and `scripts/linux/compare-gen.py` are stale (marked so);
- `docs/linux/dev/ARCHITECTURE.md` and the other KDE documents were written for a KDE-only repository;
their paths were fixed, their prose about "this repository" was not rewritten.
## 7. Feedback loops, from cheap to expensive
| Tier | What | Time | How |
|---|---|---|---|
| 0 | docs and links | none | nothing builds; a docs-only commit leaves every nix check a cache hit, except text under `komorebi-for-kde/` and `komorebi-for-mac/`, which are inputs of their derivations |
| 0 | docs and links | none | nothing builds; a docs-only commit leaves every nix check a cache hit, except text under `nix/linux/` and `nix/macos/` and the sources the derivations use |
| 1 | native Linux: `cargo check/test` of the shared crates and the KDE daemon | seconds to minutes | build-and-test.md, section 2 |
| 2 | cross-compile and nix checks: Windows clippy, macOS type-check with a fake C compiler, KDE non-VM checks, schema and CLI oracles | minutes | build-and-test.md, sections 1 and 3 |
| 3 | e2e: Windows QEMU scenarios, KDE VM suites (`fast`, `slow`) | tens of minutes, batched | build-and-test.md, sections 4 and 5 |
| 4 | a real Mac | by hand | macos-handcheck.md |
### The helper tools (outside the repository)
### The helper tools
The agents that did the consolidation used scripts that live outside the repository, in
`/home/jado/komomono-work/tools` on the build host. They are not part of the repository. Proposal, not
done: commit the ones that encode project knowledge under `scripts/dev/`, and leave the host-specific ones out.
The agents that did the consolidation used these scripts. They were first kept outside the repository (at
the time of the table below, `/home/jado/komomono-work/tools` on the build host); the cutover stack has them
in `tools/` (see `tools/README.md`); `host-sample`, `jitter-probe` and `mini`, which are about one host, were
left out. The table is the original assessment.
| Tool | What it does | Worth committing? |
|---|---|---|
| `fast-check` (+ its README) | runs only the checks that the touched paths need (tier 1 and 2), with persistent target dirs | yes: it is the quickest way to get the right gate for a change; needs its scratch paths made configurable (`FAST_CHECK_SCRATCH`, already an env var) |
| `mac-check.sh` | macOS type-check through a fake C compiler | yes, merged into `fast-check` (it has hard-coded paths to a workspace) |
| `kde-closure-check` | fails when `komorebi-for-kde/nix/root-crates.json` and the KDE cargo closure differ | yes: it protects the KDE source filter; run after any dependency change in the KDE tree or the crates it uses |
| `kde-closure-check` | fails when `nix/linux/root-crates.json` and the KDE cargo closure differ (the script in `tools/` still reads the old path `komorebi-for-kde/nix/root-crates.json`) | yes: it protects the KDE source filter; run after any dependency change in the KDE tree or the crates it uses |
| `lite-env` | env vars for builds without debug info | optional (one `.env` file) |
| `gate-lock` | host-wide FIFO lock so heavy gates and timing-sensitive e2e do not overlap | host policy; commit only if more than one person shares a build host |
| `e2e-needed` | says whether a diff touches anything the Windows e2e binaries are built from (decides whether the e2e gate is owed) | yes, next to `fast-check` |