haylan/DotFiles
1
0
Fork 0
Code Pull Requests Actions Activity

Document the confd/hyprpaper config rewrite traps and pin known versions

Browse Source 
Both bugs fixed in the preceding commits came from assuming an older
config syntax was still valid. Recorded the gotcha directly on the
relevant Architecture bullets, plus a version table for every
dotfiles-managed package so future edits check the installed version
against upstream's current schema instead of repeating the mistake.
This commit is contained in:
haylan
2026-07-07 23:27:34 +02:00
parent 4ad70d24eb
commit 2227a23630
1 changed files with 14 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+14 -2
View File
@@ -34,11 +34,23 @@ There is no build step — `tsx` runs the TypeScript directly.
## Architecture
- `src/packages.ts` — the package model. Each entry has a `tier` (`required` installs with no prompt; `recommended` is offered via checkbox), an optional `group` for mutually-exclusive alternatives (e.g. `waybar` vs an alternative both having `group: "bar"`, only one gets picked via a select prompt — `bar` and `launcher` currently each have just one member but are kept as groups so alternatives can be added the same way), and an optional `dir` for when a package's Stow directory name needs to differ from the package name. `toDirs()` converts chosen package names to their Stow directory names.
- `src/gpu.ts` — `detectGpuVendors()` shells out to `lspci` and matches VGA/3D controller lines against NVIDIA/AMD/Intel keywords (word-boundary regexes — a naive `/amd|ati/i` used to false-positive on the "ati" inside "Corporation"); `driverPackagesFor()` maps detected vendors to their Arch driver packages. `install.ts` shows every detected vendor's packages in a pre-checked confirm prompt (installing all of them on hybrid/Optimus laptops), and if NVIDIA is kept, `stow.ts`'s `writeNvidiaEnvConfig()` writes `~/.config/hypr/conf.d/nvidia.lua` (machine-generated, not stowed) with the Wayland env vars Hyprland's NVIDIA docs recommend.
- `src/gpu.ts` — `detectGpuVendors()` shells out to `lspci` and matches VGA/3D controller lines against NVIDIA/AMD/Intel keywords (word-boundary regexes — a naive `/amd|ati/i` used to false-positive on the "ati" inside "Corporation"); `driverPackagesFor()` maps detected vendors to their Arch driver packages. `install.ts` shows every detected vendor's packages in a pre-checked confirm prompt (installing all of them on hybrid/Optimus laptops), and if NVIDIA is kept, `stow.ts`'s `writeNvidiaEnvConfig()` writes `~/.config/hypr/confd/nvidia.lua` (machine-generated, not stowed) with the Wayland env vars Hyprland's NVIDIA docs recommend.
- `src/stow.ts` — all filesystem/process side effects live here: bootstrapping `yay` and oh-my-zsh/zinit if missing, installing packages via `yay`, enabling the `sddm` systemd service (`ensureSddmEnabled`), backing up real (non-symlink) files that would collide with a Stow target into `~/.dotfiles-backup/<timestamp>/`, and wrapping `stow`/`--restow`/`-D` (always invoked with an explicit `-d <PACKAGES_DIR>` so behavior doesn't depend on cwd). Also reads/writes `~/.config/dotfiles/state.json`, which records which package dirs were chosen at install time — `update` and `remove` act on this list rather than re-prompting.
- `src/install.ts`, `src/update.ts`, `src/remove.ts` — the three subcommands, each a thin sequence of calls into `stow.ts`, using `@clack/prompts` for interactive selection in `install.ts`.
- `src/cli.ts` — dispatches `install|update|remove` via Node's built-in `node:util.parseArgs`.
- `packages/hyprland/.config/hypr/hyprland.lua` — Hyprland's config, in its **current Lua format** (`hl.config`/`hl.bind`/`hl.monitor`/`hl.on`/`hl.env`), not the old `hyprland.conf` ini/hyprlang syntax deprecated since Hyprland 0.55. Easy detail to get wrong when editing — check `wiki.hypr.land` (or the raw `hyprland-wiki` GitHub markdown) for current syntax rather than assuming the old ini style.
- `packages/hyprland/.config/hypr/hyprland.lua` — Hyprland's config, in its **current Lua format** (`hl.config`/`hl.bind`/`hl.monitor`/`hl.on`/`hl.env`), not the old `hyprland.conf` ini/hyprlang syntax deprecated since Hyprland 0.55. Easy detail to get wrong when editing — check `wiki.hypr.land` (or the raw `hyprland-wiki` GitHub markdown) for current syntax rather than assuming the old ini style. `require()` inside it resolves dots in the module string as directory separators (standard Lua `package.path` behavior) — that's why the machine-generated config dir is named `confd`, not `conf.d`: a literal dot in the directory name would make `require("conf.d.foo")` look for `conf/d/foo.lua` instead and silently fail (wrapped in `pcall`, so it fails with no visible error).
- `packages/hyprpaper/.config/hypr/hyprpaper.conf` — hyprpaper's config, in its **current hyprlang block format** (`wallpaper { monitor = ... path = ... fit_mode = ... }`), not the old `preload =` / `wallpaper = monitor,path` key=value syntax removed in hyprpaper 0.8.0. `preload` doesn't exist anymore at all. Verify against `src/config/ConfigManager.cpp` in the `hyprwm/hyprpaper` repo (`m_config.addSpecialConfigValue(...)` calls list every valid key) rather than assuming the old ini style — same trap as `hyprland.lua` above.
### Pinned reference versions (Arch, checked 2026-07-07)
These packages have had **breaking, from-scratch config rewrites** in living memory — don't assume a config snippet found online (or from an older revision of this repo) is still valid without checking the installed version against the package's current source/changelog:
| package | version | note |
|---|---|---|
| `hyprland` | 0.55.4 | Lua config (`hyprland.lua`) since 0.55; older configs use `hyprland.conf` hyprlang/ini syntax. |
| `hyprpaper` | 0.8.4 | Rewritten onto `hyprtoolkit` in 0.8.0 ("configs are broken and much simplified" — upstream's own words); new block-based `wallpaper { }` syntax, `preload` removed. |
Other managed packages (`waybar` 0.15.0, `mako` 1.11.0, `hyprlauncher` 0.1.6, `kitty` 0.47.4, `foot` 1.27.0, `zsh` 5.9.1, `xdg-desktop-portal-hyprland` 1.3.12, `sddm` 0.21.0, `stow` 2.4.1) are recorded here for reference, but haven't been confirmed to carry a similar breaking-rewrite risk — re-check versions with `pacman -Qi <pkg>` before trusting this table, since this is a rolling-release Arch machine and it will drift.
### Adding a new app