diff options
| -rw-r--r-- | CLAUDE.md | 139 |
1 files changed, 0 insertions, 139 deletions
diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index b6b3f04..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,139 +0,0 @@ -# Archsetup Project Context - -## Overview -Arch Linux installation and configuration scripts with dotfiles managed via GNU Stow. Supports both X11 (DWM) and Wayland (Hyprland) setups. - -## Project Structure -``` -archsetup Main installation script -archsetup.conf.example Configuration template -init Bootstrap script for live ISO -Makefile VM integration testing + project dependencies -todo.org Active task list - -scripts/ Utility scripts (wireguard, post-install, wipedisk, etc.) -assets/ Reference documents and archived files - color-themes/ Theme palettes, generation scripts - outbox/ Processed inbox items - wireguard-config/ Proton VPN configs -.ai/ Claude tooling: session docs, workflows, protocols (gitignored) -inbox/ Unprocessed documents for session review -reference-repos/ External dotfile references -scripts/testing/ VM-based integration test framework -test-results/ Test run output -vm-images/ VM disk images for testing -``` - -## Makefile Targets -``` -make deps # Install VM-testing dependencies -make test-unit # Run fast unit tests for installer helpers (no VM) -make test # Run full VM integration test (creates base VM if needed) -make test-keep # Run test and keep the VM up for manual poking -make test-vm-base # Create the base VM only -``` -Dotfile stow operations live in the dotfiles repo's own Makefile, not here. -Run them from `~/.dotfiles`: -``` -cd ~/.dotfiles && make stow hyprland # common + hyprland + host tier -cd ~/.dotfiles && make restow hyprland # refresh links after git pull -cd ~/.dotfiles && make reset hyprland # fix conflicts, keep repo version -cd ~/.dotfiles && make unstow hyprland # remove symlinks -cd ~/.dotfiles && make import common # fzf select → import to common/ -cd ~/.dotfiles && make test # run the dotfile-script unit suites -``` -Per-host overrides live in a stow tier named after the machine (`ratio/`, -`velox/`), auto-included by every stow target when the directory exists -(`HOST=<name>` overrides detection; hostname binary is absent — `uname -n`). -The tier holds only files no shared package owns: hypr `conf.d/local.conf` -(velox: HiDPI scale + XWayland toolkit env), `pypr/config.toml`, and foot's -`host.ini` (the shared foot.ini sets no font — it's per-host via include). - -## Dotfiles Repository - -Dotfiles live in their own repo at `git.cjennings.net/dotfiles.git` -(read: `https://git.cjennings.net/dotfiles.git`, push: `git@cjennings.net:dotfiles.git`). -A fresh `archsetup` install clones it to `~/.dotfiles` and stows per `DESKTOP_ENV`: - -``` -dwm → common/ + dwm/ -hyprland → common/ + hyprland/ -none → minimal/ (standalone headless tree, not common/) -``` - -Config keys (in `archsetup.conf`, all optional — defaults shown): -``` -DOTFILES_REPO=https://git.cjennings.net/dotfiles.git -DOTFILES_BRANCH=main -DOTFILES_DIR= # defaults to the target user's ~/.dotfiles -``` - -Pull dotfile changes after install: -``` -cd ~/.dotfiles && git pull -cd ~/.dotfiles && make restow hyprland -``` - -Setting up a new machine by hand (outside the installer): -``` -git clone https://git.cjennings.net/dotfiles.git ~/.dotfiles -cd ~/.dotfiles && make stow hyprland -``` -**Quit Hyprland before an unstow/restow.** Unstowing while Hyprland runs makes -it write a stub `hyprland.conf` into the gap, which then blocks the restow. Do -it from a TTY, or with the session stopped. - -## Dotfile Script Counts -The scripts live in the dotfiles repo (`~/.dotfiles`), not here: -``` -~/.dotfiles/common/.local/bin/ → 33 universal scripts -~/.dotfiles/dwm/.local/bin/ → 8 X11/DWM scripts -~/.dotfiles/hyprland/.local/bin/ → 7 Hyprland scripts -``` - -## Shell Configuration -``` -~/.profile → Environment variables only (POSIX compatible) -~/.bash_profile → Sources .profile + .bashrc for login shells -~/.bashrc → Bash-specific settings, sources .bashrc.d/ -~/.zshrc → Zsh-specific settings, sources .zshrc.d/ -~/.profile.d/ → Modular env vars (display, framework, auto-tmux, hyprland) -~/.bashrc.d/ → Modular bash configs (aliases, fzf, git, media, utilities, emacs) -~/.zshrc.d/ → Modular zsh configs (same + arch-downgrade) -``` - -## Theme System -Two themes available: dupre (default) and hudson. Switched via `set-theme` script. - -Full palette reference: `assets/color-themes/dupre/dupre-palette.org` - -- **GTK**: Adwaita-dark -- **Qt**: Adwaita-Dark (via adwaita-qt5/qt6, QT_STYLE_OVERRIDE) -- **Icons**: Papirus-Dark -- **Cursors**: Bibata-Modern-Ice (size 24) -- **Font**: BerkeleyMono Nerd Font (13pt terminal, 14px waybar) -- **Theme configs**: `~/.dotfiles/hyprland/.config/themes/dupre/` - -## Key Configuration Files -- `~/.dotfiles/hyprland/.config/hypr/hyprland.conf` - Main Hyprland config -- `~/.dotfiles/hyprland/.config/themes/dupre/` - Dupre theme files (foot, fuzzel, waybar, dunst, hyprlock, Xresources) -- `~/.dotfiles/common/.profile.d/` - Shell environment scripts -- `~/.dotfiles/common/.config/qt5ct/qt5ct.conf` - Qt5 theming -- `~/.dotfiles/common/.config/qt6ct/qt6ct.conf` - Qt6 theming - -## Notes -- Desktop file overrides go in `~/.dotfiles/hyprland/.local/share/applications/` -- MPD is configured but mpv handles audio file associations -- Firewall is ufw (configured in `archsetup`, default-deny incoming, explicit allow list). Tailscale traffic **does** traverse ufw on ratio — a probe from a tailnet IP is still blocked unless a rule covers the port. Don't assume tailnet-only services bypass the firewall; they need an explicit ufw rule like any other. -- Never assume which machine this is — always run `uname -n` to find the hostname (the `hostname` binary is absent, so `uname -n` is the source of truth; `uname -r` is the kernel release, not the host). The fleet is **ratio** (workstation) and **velox** (laptop), both Hyprland (Wayland). archsetup still supports dwm/X11, but no current machine uses it. -- Remote repository on cjennings.net -- .ai/ is gitignored; living project context is in .ai/notes.org - -## Codified Insights - -- **VM tests run committed code, not your working tree.** `scripts/testing/run-test.sh` provisions the VM from `git bundle create <file> HEAD` (it simulates `git clone`), so an uncommitted edit to `archsetup` or the pytest suite silently runs the old code. Commit (even a throwaway WIP commit) before `make test FS_PROFILE=...`, or the change isn't exercised. (`gotcha` — 2026-06-25) -- **Iterate the pytest sweep against a kept VM, not a reinstall.** `make test-keep FS_PROFILE=...` leaves the VM up after the install and writes `testinfra_ssh_config` + `root_key` into `test-results/<timestamp>/`. Point pytest at that ssh-config to re-run only the Testinfra checks in ~30s instead of a ~70-minute full reinstall. Use it when iterating test assertions, not installer logic. (`pattern` — 2026-06-25) -- **VM UEFI NVRAM lives outside the qcow2 and must be per-profile.** OVMF boot entries live in the `OVMF_VARS` file, not the disk image, so reverting the `clean-install` snapshot does NOT restore them. The base ESPs have no removable `\EFI\BOOT\BOOTX64.EFI` fallback, so a base boots only via its NVRAM entry — lose or overwrite it and the VM dies in UEFI ("No bootable option") and SSH-times-out before archsetup runs. `init_vm_paths` now suffixes `OVMF_VARS` per `FS_PROFILE` (matching the disk image); never share one NVRAM file across btrfs/zfs. (`gotcha` — 2026-06-28) -- **sed/awk function extraction breaks on column-0 `}` inside heredocs.** The `tests/` harness and any `/^name() {/,/^}/` extraction stop at the first line beginning with `}` — but a JSON heredoc body (e.g. the docker `daemon.json` in `developer_workstation`) has a column-0 `}` that is NOT the function's close. Find the real closing brace before slicing, or the bounds are silently wrong. (`gotcha` — 2026-06-28) -- **AUR builds need ≥8 GiB VM RAM.** `makepkg` runs `-j$VM_CPUS`, and parallel `cc1plus` (~700 MB each on heavy C++ AUR packages) OOM-killed under the old 4 GiB `VM_RAM` default; the install still passed (yay retries) but the kills showed as attributed issues. Default is now 8192 MB. If you raise `VM_CPUS`, raise `VM_RAM` with it. (`threshold` — 2026-06-28) -- **Guard live upgrades with a PreTransaction hook, not a wrapper.** `hypr-live-update-guard` is a pacman `PreTransaction` hook (`AbortOnFail` + `NeedsTargets`) so it fires no matter how the upgrade launches (pacman, yay, topgrade) and aborts before any package is swapped — the safe point, since nothing is replaced yet. A shell wrapper around `pacman` would be bypassed by the other front-ends. (`pattern` — 2026-06-28) |