diff --git a/CLAUDE.md b/CLAUDE.md index 983c043..e0072fc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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//`, and wrapping `stow`/`--restow`/`-D` (always invoked with an explicit `-d ` 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 ` before trusting this table, since this is a rolling-release Arch machine and it will drift. ### Adding a new app