diff options
| -rw-r--r-- | .github/copilot-instructions.md | 6 | ||||
| -rw-r--r-- | README.md | 62 |
2 files changed, 37 insertions, 31 deletions
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index ff8178f..e7e3b7d 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -14,14 +14,14 @@ The repo root is a chezmoi source directory. Files targeting `$HOME` use chezmoi - `dot_config/`, `private_dot_gnupg/`, `private_dot_ssh/`, etc. — chezmoi source state mapping to `$HOME`. Prefix meanings: `dot_` → leading `.`, `private_` → restricted permissions, `executable_` → `+x` bit. - `etc/` contains system-level configs (`/etc/` targets) — systemd units, pacman hooks, sysctl tunables, kernel module loading. Deployed by `run_onchange_after_deploy-etc.sh.tmpl`. -- `meta/` contains plain text package lists for Arch Linux (one package per line, `#` comments). Each `.txt` file represents a group (e.g. `base.txt`, `dev.txt`, `wayland.txt`). Install with `just install base dev` or `just install-all`. Detect drift with `just status`. -- `systemd-units/` contains plain text systemd unit lists paired by name with `meta/` groups (e.g. `systemd-units/base.txt` ↔ `meta/base.txt`). Units listed here are enabled by `just services-enable` (run automatically by `just init`). Inspect with `just services`, detect drift with `just services-drift`. +- `meta/` contains plain text package lists for Arch Linux (one package per line, `#` comments). Each `.txt` file represents a group (e.g. `base.txt`, `dev.txt`, `wayland.txt`). Install with `just pkg-apply base dev` or `just pkg-apply` (all groups). Detect drift with `just pkg-status` (or `just status` for the aggregate). +- `systemd-units/` contains plain text systemd unit lists paired by name with `meta/` groups (e.g. `systemd-units/base.txt` ↔ `meta/base.txt`). Units listed here are enabled by `just unit-apply` (run automatically by `just init`). Inspect with `just unit-list`, detect drift with `just unit-status`. - `firefox/` contains Firefox/LibreWolf hardening overrides (`user-overrides.js`) and custom CSS (`chrome/userChrome.css`). Deployed by `run_onchange_after_deploy-firefox.sh.tmpl`. - `dot_local/bin/executable_create-efi` is an interactive EFI boot entry creation script using `efibootmgr` (deployed to `~/.local/bin/create-efi`). - `bootstrap.sh` at the repo root is a POSIX shell script that takes a fresh minimal Arch install (only `base`) to a fully deployed state. It installs prerequisites, enables `%wheel` sudoers, bootstraps `paru-bin` from the AUR, clones the repo, runs `just init`, and optionally invokes `create-efi`. Designed to be curlable: `curl -fsSL .../bootstrap.sh | sh`. - `.chezmoiignore` excludes non-home files (`etc/`, `meta/`, `systemd-units/`, `firefox/`, docs) from deployment to `$HOME`. - `.githooks/` contains git hooks: `pre-commit` runs `just check` as a code quality gate (bypass with `--no-verify`); `post-commit` runs `chezmoi apply`. Activated by `just init`. -- `justfile` provides recipes: `init` (first-time setup), `sync` (apply + fix), `apply`, `readd`, `fix`, `fmt`, `check-fmt`, `lint`, `check`, `status`, `pkg-drift`, `dotfile-drift`, `undeclared`, `diff`, `merge`, `groups`, `install`, `install-all`, `add`, `remove`, `services`, `services-enable`, `services-drift`, `etc`, `etc-diff`, `etc-upstream-diff`, `etc-add`, `etc-readd`, `etc-rm`, `etc-reset`, `etc-untrack`, `etc-restore`. Run `just` or `just --list` to see them. +- `justfile` uses a `DOMAIN-VERB` scheme across four domains (`dotfiles`, `etc`, `pkg`, `unit`) with chezmoi-aligned verbs (`add`, `forget`, `re-add`, `apply`, `diff`, `merge`, `status`). Top-level dispatchers (`add`, `forget`, `re-add`, `diff`, `merge`) sniff argument shape and delegate: args containing `/` → path (prefix `/?etc` → etc, else dotfiles); args ending in `.service`/`.timer`/`.socket`/`.mount`/`.target`/`.path` → unit; otherwise bare words → pkg. Full list: `init`, `sync`, `apply`, top-level `add`/`forget`/`re-add`/`diff`/`merge`/`status`; `dotfiles-add`/`forget`/`re-add`/`diff`/`merge`/`status`; `etc-add`/`forget`/`re-add`/`diff`/`merge`/`status`/`reset`/`restore`/`untrack`/`upstream-diff`; `pkg-add`/`forget`/`apply`/`fix`/`list`/`status` + `undeclared`; `unit-add`/`forget`/`apply`/`list`/`status`; `fmt`, `check-fmt`, `lint`, `check`, `doctor`. Run `just` or `just --list` for the menu. ## Window manager @@ -39,34 +39,40 @@ chezmoi apply -v Everything is driven by [just](https://just.systems/) recipes against four parallel models: -| Directory | Managed by | Purpose | -| ------------------------ | --------------------------------------------- | ------------------------------------------------------------------------------------------------ | -| `dot_*`, `private_dot_*` | chezmoi | Dotfiles deployed to `$HOME`. Prefixes: `dot_` → `.`, `private_` → `0600`, `executable_` → `+x`. | -| `meta/*.txt` | `just install`, `just pkg-drift` | Plain-text package lists (one per line, `#` comments). Groups: `base`, `dev`, `wayland`, etc. | -| `systemd-units/*.txt` | `just services-enable`, `just services-drift` | Units to enable, paired by name with a `meta/` group (`base.txt` ↔ `base.txt`). | -| `etc/` | `run_onchange_after_deploy-etc.sh.tmpl` | System-level configs deployed to `/etc/` via a chezmoi onchange hook. | -| `firefox/` | `run_onchange_after_deploy-firefox.sh.tmpl` | LibreWolf `user-overrides.js` + `userChrome.css` (kept under the familiar `firefox/` name). | +| Directory | Managed by | Purpose | +| ------------------------ | ------------------------------------------- | ------------------------------------------------------------------------------------------------ | +| `dot_*`, `private_dot_*` | chezmoi | Dotfiles deployed to `$HOME`. Prefixes: `dot_` → `.`, `private_` → `0600`, `executable_` → `+x`. | +| `meta/*.txt` | `just pkg-apply`, `just pkg-status` | Plain-text package lists (one per line, `#` comments). Groups: `base`, `dev`, `wayland`, etc. | +| `systemd-units/*.txt` | `just unit-apply`, `just unit-status` | Units to enable, paired by name with a `meta/` group (`base.txt` ↔ `base.txt`). | +| `etc/` | `run_onchange_after_deploy-etc.sh.tmpl` | System-level configs deployed to `/etc/` via a chezmoi onchange hook. | +| `firefox/` | `run_onchange_after_deploy-firefox.sh.tmpl` | LibreWolf `user-overrides.js` + `userChrome.css` (kept under the familiar `firefox/` name). | ## Recipes at a glance -Run `just` or `just --list` for the full menu. Main recipes: +Run `just` or `just --list` for the full menu. Recipes follow a `DOMAIN-VERB` scheme across four domains (`dotfiles`, `etc`, `pkg`, `unit`) with chezmoi-aligned verbs (`add`, `forget`, `re-add`, `apply`, `diff`, `merge`, `status`). Top-level dispatchers sniff argument shape and delegate. -| Category | Recipe | Effect | -| ------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | -| Setup | `just init` | First-time machine setup: chezmoi init, git hooks, apply, base group, services | -| Day-to-day | `just sync` | `apply` + `fix` (deploy dotfiles + top up partially-installed groups) | -| | `just apply` | `chezmoi apply` | -| | `just readd` | Pull live changes back into the repo (chezmoi re-add + `etc-readd`) | -| Packages | `just install GROUP [GROUP...]` | Install the listed `meta/*.txt` groups | -| | `just install-all` | Install every group | -| | `just add GROUP PKG`, `just remove GROUP PKG` | Edit a group list and install/remove | -| Services | `just services-enable` | Enable every unit in the enabled-group `systemd-units/*.txt` lists | -| /etc | `just etc-diff`, `just etc-readd`, `just etc-restore`, `just etc-untrack` | See /etc workflow below | -| Inspection | `just status` | Combined dotfile + package + /etc + service drift | -| | `just doctor` | Verify tooling for `just check` is installed | -| Quality gates | `just fmt [PATH]`, `just check-fmt [PATH]` | Format / check formatting (all languages below) | -| | `just lint [PATH]` | Run linters (selene, shellcheck, ruff, taplo) | -| | `just check [PATH]` | `check-fmt` + `lint` (the pre-commit hook and CI both run this) | +| Category | Recipe | Effect | +| ------------- | ------------------------------------------ | ---------------------------------------------------------------------------------- | +| Setup | `just init` | First-time setup: chezmoi init, git hooks, apply, base packages, curated units | +| Day-to-day | `just sync` | `apply` + `pkg-fix` + `unit-apply` (full reconcile) | +| | `just apply` | `chezmoi apply` — atomically deploys dotfiles AND /etc | +| | `just re-add [PATH]` | Pull live changes back into the repo (dotfiles + /etc) | +| Add / forget | `just add PATH` | Dispatches to `dotfiles-add` (path) or `etc-add` (`/etc/...`) | +| | `just add GROUP NAME…` | Dispatches to `pkg-add` (bare names) or `unit-add` (ends in `.service`/`.timer`/…) | +| | `just forget …` | Same shape as `add`; delegates to the right `*-forget` | +| Packages | `just pkg-apply [GROUP…]` | Install listed groups, or every group if none given | +| | `just pkg-fix` | Top up missing packages in already-adopted groups | +| | `just pkg-list [GROUP]` | Show per-group install coverage | +| Units | `just unit-apply` | Enable every unit in the adopted `systemd-units/*.txt` lists | +| | `just unit-list [GROUP]` | List curated units with their state | +| /etc | `just etc-diff`, `just etc-re-add`, | See /etc workflow below | +| | `just etc-restore`, `just etc-untrack` | | +| Inspection | `just status` | Combined dotfile + /etc + package + unit drift | +| | `just diff [PATH]`, `just merge [PATH]` | Dispatch to `dotfiles-*` or `etc-*` by path | +| | `just doctor` | Verify tooling for `just check` is installed | +| Quality gates | `just fmt [PATH]`, `just check-fmt [PATH]` | Format / check formatting (all languages below) | +| | `just lint [PATH]` | Run linters (selene, shellcheck, ruff, taplo) | +| | `just check [PATH]` | `check-fmt` + `lint` (the pre-commit hook and CI both run this) | `fmt` / `check-fmt` / `lint` cover: Lua (stylua, selene), shell (shfmt, shellcheck), Python (ruff), TOML (taplo), justfile (`just --fmt`), plus Markdown/JSON/YAML/CSS (prettier). Each accepts either no argument (whole repo) or a single file path. @@ -74,10 +80,10 @@ Run `just` or `just --list` for the full menu. Main recipes: Four sources of drift are tracked independently and combined by `just status`: -- **Dotfiles** (`chezmoi status`): live `$HOME` files differ from the repo. Resolve with `just apply` (repo → home), `just readd` (home → repo), `just diff`, or `just merge PATH`. -- **Packages** (`just pkg-drift`): installed but undeclared, or declared but missing. Resolve by adding to a `meta/` group (`just add GROUP PKG`) or by uninstalling. -- **/etc** (`just etc` / `just etc-diff`): installed package configs or user-created files in `/etc` that aren't in the repo. Resolve with `just etc-readd PATH` (track), `just etc-restore PATH` (revert to package default), or `just etc-untrack PATH`. -- **Services** (`just services-drift`): enabled units not in any `systemd-units/*.txt`, or declared units that aren't enabled. +- **Dotfiles** (`just dotfiles-status`): live `$HOME` files differ from the repo. Resolve with `just apply` (repo → home), `just re-add PATH` (home → repo), `just diff PATH`, or `just merge PATH`. +- **Packages** (`just pkg-status`): installed but undeclared, or declared but missing. Resolve by adding to a `meta/` group (`just add GROUP PKG`) or uninstalling. +- **/etc** (`just etc-status` / `just etc-diff`): modified package configs or user-created files in `/etc` that aren't in the repo. Resolve with `just etc-re-add PATH` (track), `just etc-restore PATH` (revert to package default), or `just etc-untrack PATH`. +- **Units** (`just unit-status`): enabled units not in any `systemd-units/*.txt`, or declared units that aren't enabled. ## Git hooks |