starred/nix-config-ryan4yin
1
0 Fork 0
mirror of https://github.com/ryan4yin/nix-config.git synced 2026-11-13 12:13:36 +01:00
Code Issues Packages Projects Releases 10 Wiki Activity

docs(skills): add repo-scoped task skills and give each fact one home (#337)

Browse Source
This commit is contained in:
ryan4yin | 二花 authored and GitHub committed 2026-10-02 10:13:03 +08:00
1 parent 1f8db1fccf
commit b2ec56db66
18 files changed
+965 -58
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

.agents/skills/nix-config-debug/SKILL.md
+81
View File
@@ -0,0 +1,81 @@
---
name: nix-config-debug
description:
Use when something in this repo is broken, such as an eval or build error, a failed activation, a
crashed service, or an unreachable host or MicroVM guest.
---
# Debugging this repository
Follow the global `systematic-debugging` skill for the process (root cause before any fix). This
skill is only the map: which layer failed, and where to look. Rolling back, isolating a bad input
bump, and the commands that destroy rollback points are in the `nix-config-update` skill.
## Core rules
1. **Restore service first.** A down host or a dead session gets the previous generation before any
investigation. Rolling back the machine you are on needs `sudo`, so the user does it.
2. **Name the layer before touching code.** Eval, build, activation, and runtime failures have
different causes; a green `just test` says nothing about activation.
3. **Never get to green by weakening a check**: no disabled test, dropped assertion, or `mkForce`
over the failing value.
4. **Preserve existing user changes.** Do not discard or stash them without authorization. If a
clean baseline is needed, record the current diff and ask before isolating it.
## 1. Localize by layer
| Layer | Symptom | Look with |
| ------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| eval | `just test` prints `false`, an eval error | `just eval-host <host>` (already passes `--show-trace`) |
| build | build error, hash mismatch, "marked as broken" | `just build-host <host>`, then `nix log <drv>` |
| activation | the deploy fails after building | the deploy output; `journalctl -u home-manager-$USER -b` for Home Manager |
| runtime | a unit is failed or restarting | `just list-failed`, `systemctl status <unit>`, `journalctl -u <unit> -b` |
| boot | errors at boot, wrong kernel | `journalctl -b -p err`; `just history` for what is booted |
| session | desktop or app misbehaves | `journalctl --user -b -p err`; the `nix-config-desktop` skill |
| remote host | anything on a Colmena host | `ssh root@<host> journalctl -b -p err`, same commands over SSH |
| MicroVM guest | guest down or unreachable | on the VM host: `systemctl status microvm@<guest>` and `microvm-tap-interfaces@<guest>`; then `br0` |
| secrets | missing or unreadable `/etc/agenix/*` | the `nix-config-secrets` skill |
## 2. Read the evaluated value
When `just test` prints `false`, re-run the suite directly to get the trace:
```bash
nix eval .#evalTests --show-trace
```
The trace names the failing test under `outputs/<system>/tests/<name>/`. Read its `expr.nix` and
`expected.nix`, and evaluate the expression to see what actually came out before changing anything.
Most eval-layer questions are "what did this option actually end up as?". Ask the configuration
directly instead of reading modules:
```bash
nix eval .#nixosConfigurations.<host>.config.<option.path>
nix eval .#nixosConfigurations.<host>.config.systemd.services \
--apply 's: builtins.filter (n: builtins.match "microvm.*" n != null) (builtins.attrNames s)'
nix repl # then `:lf .` and inspect nixosConfigurations.<host>.config
```
Renamed or removed options are the most common eval break after an update; the error or warning
names the replacement. Treat deprecation warnings as failures waiting to happen.
## 3. Your change or the update?
`git status`, `git log --oneline -5 -- flake.lock`, and `git diff flake.lock` tell you which. If the
lock moved, isolate the input as described in the `nix-config-update` skill before reading code.
Preserve unrelated working-tree changes; do not use `git checkout`, `git stash`, or cleanup commands
to manufacture a clean tree without authorization.
## 4. Prove the fix
Re-run the exact command that failed, then `just test`, then `just build-host <host>` for every
affected host before anyone deploys. Report the evidence ("the unit is active, `just test` is
`true`"), not the intent.
## Why these rules exist
- `5ee8b728 fix(restic): use the correct systemd timer option names (#319)` - an option-name error
that only reading the evaluated value catches quickly.
- `9315055b fix(darwin): unblock home-manager activation` - an activation failure that eval and
build both passed.
.agents/skills/nix-config-desktop/SKILL.md
+136
View File
@@ -0,0 +1,136 @@
---
name: nix-config-desktop
description:
Use when changing the Niri/Noctalia desktop, the Wayland session, input method (fcitx5), theming,
fonts, or desktop autostart in this repo.
---
# Changing the desktop
The desktop is a Niri + Noctalia Wayland session, shared by two hosts: `ai-niri` (hostName `ai`,
x86_64) and `shoukei-niri` (hostName `shoukei`, Apple Silicon). Shared config lives in
`home/linux/gui/**`; each host adds `hosts/<dir>/niri-hardware.kdl` and its own
`home/hosts/linux/<dir>.nix`. Run `hostname` to know which one you are on.
Most of the config is deployed as **out-of-store symlinks**, so an edit takes effect live, rolls
back with git, and needs no rebuild. Only the store layer needs one.
## Core rules
1. **Edit the config layer, not the store.** Niri KDL and the Noctalia baseline are symlinked out of
store; editing them applies immediately. A rebuild is wasted time and hides the change behind a
generation. Scale the caution to the risk: a bar, OSD, notification, or wallpaper tweak is safe
to try on the running session and undo with git, but a compositor, keybinding, input, output,
idle, or portal change can take the session the user is looking at down with it. Treat that
second kind as impactful, and do not experiment on the live desktop with it.
2. **Validate before trusting a reload.** A config that fails to parse does not crash the session:
Niri keeps the last working config and shows a "Failed to parse the config file" notification.
The edit silently does not apply, which is easy to misread as "my edit did nothing".
3. **Look at it.** Anything that renders (bar, OSD, notifications, wallpaper, corners) is not done
until a screenshot shows it correct. A setting that parses is not a setting that looks right.
4. **Screenshots are the user's screen.** Capture as little as proves the change, keep the file out
of the user's folders, and delete it afterwards (step 3).
5. **`just niri` is the user's to run.** It activates the machine you are on through
`nixos-rebuild --sudo` and blocks on a password prompt.
## 1. Pick the layer
| Change | Where it lives | Applies |
| --------------------------------------------- | ------------------------------------------------------------- | ------------------------ |
| Niri compositor (binds, layout, window rules) | `home/linux/gui/niri/conf/*.kdl` | live |
| Niri per-host outputs | `hosts/<dir>/niri-hardware.kdl` | live |
| Noctalia shared baseline | `home/linux/gui/base/noctalia/config/config.toml` | live |
| Noctalia per-host override | `home/hosts/linux/<dir>/noctalia.toml` (`host-<host>.toml`) | store: needs `just niri` |
| Noctalia value saved by the Settings UI | `~/.local/state/noctalia/settings.toml` (not in the repo) | live, wins over the rest |
| Mozc dictionary | `home/linux/gui/base/fcitx5/mozc-config1.db` | live |
| fcitx5 profile and addons | `home/linux/gui/base/fcitx5/` | store: needs `just niri` |
| Theme (catppuccin), fonts | `home/base/core/theme.nix`, `modules/nixos/desktop/fonts.nix` | store: needs `just niri` |
| Session, portal, and systemd wiring | `modules/nixos/desktop/**`, `home/linux/gui/base/xdg/` | store: needs `just niri` |
Noctalia's merge order and `[include]` are in
[home/linux/gui/base/README.md](../../../home/linux/gui/base/README.md). A per-host difference goes
in that host's override file, not in the shared baseline.
## 2. Edit and validate
```bash
niri validate # the live config and its whole include graph
noctalia config validate # the merged config, as the running shell loads it
noctalia config validate ./home/linux/gui/base/noctalia/config/config.toml # one file
```
Validate the **live** Niri config, not the repo copy: `config.kdl` includes `./niri-hardware.kdl`,
which only the host module places in `~/.config/niri/`, so `niri validate -c <repo path>` fails on
the missing include.
Confirm a file is live before trusting a hot reload:
```bash
readlink -f ~/.config/niri/config.kdl # must end in ~/nix-config/...
readlink -f ~/.config/noctalia/config.toml
```
`~/.config/...` points at a store path that is itself a symlink back into the repo. If it resolves
to a plain store file, it is not live and the change needs `just niri`.
If an edit does not show up:
- `niri msg action load-config-file` forces a Niri reload.
- `noctalia config export` prints the merged config that actually won; diff it against your edit.
- `~/.local/state/noctalia/settings.toml` loads last. A value saved through the Settings UI, or left
over from an experiment, silently beats `config.toml`.
## 3. Verify on screen
```bash
output="$(mktemp --tmpdir="${TMPDIR:-/tmp}" desktop-check.XXXXXX.png)"
niri msg action screenshot-window --path "$output" -p false # focused window
# Or, when a full output is needed:
# niri msg action screenshot-screen --path "$output" -p false
```
- Prefer `screenshot-window` when it proves the change. A full-screen capture includes whatever else
is open: browser tabs, chats, credentials.
- `--path` must be absolute; the `mktemp` path keeps the file out of `~/Pictures/Screenshots/`.
`-p false` drops the pointer.
- Both actions also **replace the user's clipboard** with the image. There is no flag to avoid it,
so say so when you take one.
- Inspect the PNG with your image-reading tool, show it to the user only when asked, never upload or
share it, and delete it when done: `rm -f "$output"`.
Capture the frame that proves the change: the bar or OSD for a shell edit, borders and corner radius
for a layout rule, the specific app for an input-method edit.
What a screenshot cannot show:
- `systemctl --user --failed` and `journalctl --user -b -p err` for a crashed shell or portal unit.
- `journalctl -u home-manager-$USER -b` after a store-layer change: Home Manager activates as a
system unit here.
- `niri msg outputs` for mode, scale, and transform; `niri msg workspaces` and `niri msg windows`
for layout.
- `fcitx5-remote -n` for the active input method.
## 4. Land and roll back
- Config layer: the repo file is the live file, and there is no rebuild or generation to roll back
to. Commit it only when the task asked for that. To undo a committed change, `git revert`; for an
uncommitted experiment, preserve the diff and ask before discarding it.
- Store layer: the user runs `just niri`, then you verify as in step 3. To undo, boot the previous
generation (`just history` lists them).
- If the session will not start at all, fix the file from a TTY. Niri's recovery only covers a bad
reload, not a broken startup.
Do not "test" with commands that act on the session the user is looking at: `niri msg action quit`,
`niri msg action power-off-monitors`, `noctalia msg dpms-off`, `noctalia msg lock`.
## Why these rules exist
- `063c31cc refactor(noctalia): hot-reload config via out-of-store symlink` - the baseline is
out-of-store precisely so shell edits do not need a switch.
- `1546e54b chore(noctalia): move OSD and notifications to the bottom-right` and
`e93cb979 fix(noctalia): keep the bar readable in light mode` - changes that parse fine and only a
screenshot can judge.
- `495c3669 fix(xdg): order autostart apps after xdg-desktop-portal` - sandboxed apps raced the
portal at login; the fix orders the unit.
- `33383414 fix(niri): match outputs by EDID to survive connector renumbering` - match outputs by
EDID, not by connector name.
.agents/skills/nix-config-new-host/SKILL.md
+98
View File
@@ -0,0 +1,98 @@
---
name: nix-config-new-host
description:
Use when adding a NixOS, macOS, or MicroVM host in this repo, including its outputs, networking,
secrets, and eval-test wiring.
---
# Adding a host
Copy the closest existing host and change what differs. The current inventory and naming scheme are
in [hosts/README.md](../../../hosts/README.md).
## Core rules
1. **Three names, decided up front.** The directory (`hosts/idols-ai/`), the hostname
(`hostName = "ai"`), and the configuration name (`ai-niri`) differ. Servers use the hostname as
the configuration name; Niri desktops append `-niri`, because `just niri` deploys
`$(hostname)-niri`. The `hostname` eval test encodes this.
2. **Secrets come from another repository.** The new host decrypts nothing until its host key is a
recipient in `nix-secrets`; see the `nix-config-secrets` skill.
3. **The shared policy modules are not optional.** Several eval tests assert a policy for every
configuration, so an under-wired host fails `just test` instead of failing in production.
4. **Build before you install.** `just test`, `just eval-host <name>`, and `just build-host <name>`
pass before anything is partitioned or flashed. `disko` destroys the target disk, and
partitioning and installing are user-run actions on a device the user has confirmed.
## 1. Pick the template
| New host | Copy from |
| ------------------------ | ------------------------------------------------------------------------------------------------- |
| Desktop workstation | `hosts/idols-ai/` + `outputs/x86_64-linux/src/idols-ai.nix` |
| Homelab server / VM host | `hosts/12kingdoms-shoryu/` + `outputs/x86_64-linux/src/12kingdoms-shoryu.nix` |
| Apple Silicon Linux | `hosts/12kingdoms-shoukei/` + `outputs/aarch64-linux/src/12kingdoms-shoukei.nix` |
| macOS | `hosts/darwin-fern/` + `outputs/aarch64-darwin/src/fern.nix` (`darwinConfigurations`, no Colmena) |
| MicroVM guest | `hosts/k8s/k3s-test-1-worker-1/` + `outputs/x86_64-linux/src/k3s-test-1-worker-1.nix` |
A MicroVM guest is also registered in its VM host's `microvm.nix`, and is deployed with
`just microvm-deploy`. On a VM host with the `br0` bridge it also needs a `systemd.network.networks`
unit that attaches the guest's tap to `br0`; the tap name comes from the guest IP (`192.168.5.116`
to `vm116`). Some guest outputs also expose a Colmena node for evaluation or other workflows; do not
assume the physical-host deployment is done through Colmena.
## 2. Files to create or edit
1. `hosts/<dir>/default.nix` - sets `hostName` and imports the host's modules. Some hosts (`shoryu`,
`shushou`, `youko`, `akane`) import `mylib.scanPaths ./.`, which pulls in **every other `.nix`
file in the directory**; keep scratch files out of those.
2. `hosts/<dir>/hardware-configuration.nix` - generated on the target machine
(`nixos-generate-config --show-hardware-config`), never copied from another host. Where the
layout is declarative, add `disko-fs.nix` and record the install command in the host's
`README.md`, as `hosts/idols-ai/README.md` does.
3. `home/hosts/linux/<name>.nix` or `home/hosts/darwin/<name>.nix` - only for a host with Home
Manager; otherwise leave `home-modules` out.
4. `outputs/<system>/src/<name>.nix` - add the output types appropriate to the host:
`nixosConfigurations.<name>` for NixOS, `darwinConfigurations.<name>` for macOS, and a
`packages.<name>` installer image only where the platform provides one. Add `colmena.<name>` only
for a host deployed through Colmena; it then needs `tags`, `ssh-user`, and usually `targetHost`.
MicroVM guests also need the VM-host `microvm.nix` registration. Keep the leading comment about
unused `args`: haumea passes them lazily and they are still required.
5. `vars/networking.nix` - `hostsAddr.<name> = { iface; ipv4; }` for a LAN host. That entry drives
the static address, the SSH `Host` alias used for remote builds, and `known_hosts`, so a wrong
`iface` takes the host offline at activation. Skip it for a DHCP or mobile host.
6. `hosts/README.md` - add the host to the inventory.
Pin service user and group ids (`service-user-ids.nix`, as on `shoryu`) before the host has state on
disk. A dynamically allocated id that moves on a later rebuild orphans the files it owned
(`9187e4d9 fix(youko): pin dynamically-allocated service uid/gid (#320)`).
## 3. Tests that fail until the host is wired
[outputs/README.md](../../../outputs/README.md#which-tests-cover-a-new-host) lists which eval tests
check every configuration and which list hosts by name:
- `hostname`: a new `-niri` configuration needs a `specialExpected` entry, in the test for its
platform (`ai-niri` in x86_64-linux, `shoukei-niri` in aarch64-linux).
- `security-*`, `kernel`, `nix-system-features`: apply to every configuration automatically.
- `home-manager`, `btrbk`, and the other host-listing tests: add the host if it should be covered.
`just test` must print `true`; an exit code of `0` with `false` is a failure.
## 4. Install and deploy
- First install: boot the ISO, partition with disko, install, then deploy normally. Partitioning,
formatting, and installing destroy the target disk, so they are user-run actions on a device the
user confirmed: check `lsblk`/`findmnt` first, name the exact device, and get authorization for it
before any `destroy,format,mount`. Follow
[nixos-installer/README.md](../../../nixos-installer/README.md) and the host's own README.
- Remote hosts: `just col <tag>` or the host's own recipe, once its key is a secrets recipient.
Deploying is a separate impactful action; use the `nix-config-update` skill's staged deployment
(confirm the target, preview the closure, and get authorization).
- The machine you are on: `just local` or `just niri`, which prompt for `sudo`, so the user runs
them.
## 5. Verify
- `ssh <name> true`, then `systemctl --failed` and `journalctl -b -p err` on the host.
- Secrets decrypted, checked by mode and owner only.
- The role works: the service, VM, or desktop the host exists for.
.agents/skills/nix-config-secrets/SKILL.md
+123
View File
@@ -0,0 +1,123 @@
---
name: nix-config-secrets
description:
Use when adding, changing, renaming, or removing an agenix secret, wiring one into a host, or
fixing a decryption or activation failure in this repo.
---
# Working with secrets
Secrets are age-encrypted files in a separate private repository (`nix-secrets`), pulled in as the
`mysecrets` flake input and declared here in `secrets/nixos.nix` and `secrets/darwin.nix`. No secret
value is ever stored in this repository.
Read [secrets/README.md](../../../secrets/README.md) for the private-repository workflow and the
recipient rule.
## Core rules
1. **Never read a decrypted secret.** Reference its path; do not `cat`, copy, or print it. Prove a
change with metadata (mode, owner, timestamps), never with content.
2. **Three steps, in order.** The private repository changes first, then this repository's
`flake.lock` moves `mysecrets` to that commit, then the declaration and consumer change here.
`file = "${mysecrets}/x.age"` resolves against the locked revision, so a declaration that lands
before the lock bump points at a file that does not exist yet.
3. **Every secret stays decryptable by the desktops.** A recipient set is
`desktop_keys ++ <the hosts that need it>`; `recovery_key` is a member of `desktop_keys`. The one
exception is `restic-password-desktop.age`, readable by `desktop_keys` alone.
4. **A consumer sits behind the same gate as its secret.** A secret declared under
`modules.secrets.desktop` only exists on desktops, so only a desktop-gated module may reference
it. Desktops and servers are mutually exclusive: `secrets/nixos.nix` asserts that a host never
enables `desktop` together with a server group, so a value both sides need takes a deliberate
choice rather than enabling both groups.
5. **Least privilege on the decrypted file.** Pick the narrowest mode that works, and set the owner
together with the mode.
## 1. Where the pieces live
| Piece | Location |
| --------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Recipient list, encrypted files, `agenix` CLI | the private `nix-secrets` repository |
| The pinned revision of that repository | `flake.lock`, input `mysecrets` |
| Declaration: file, mode/owner, `/etc` copy | `secrets/nixos.nix`, `secrets/darwin.nix` |
| Which host gets which group | `modules.secrets.<group>.enable` in `outputs/<system>/src/<name>.nix` or a host module |
| Consumers | modules reading `/etc/agenix/<name>` or `config.age.secrets."<name>".path` |
| Decryption key | `age.identityPaths`: the host's SSH host key; `/persistent/etc/ssh/...` on a preservation host |
## 2. Add or change a secret
These steps are user-run unless the user explicitly authorizes that exact operation and target:
editing the private repository, `agenix -e`/`-r` (interactive, and they handle key material),
anything under `sudo`, and the push.
1. In the private repository, on a desktop: add the file to `secrets.nix` with the recipient set
from core rule 3, create or edit it with
`sudo agenix -e ./xxx.age -i /etc/ssh/ssh_host_ed25519_key`, commit, and push.
2. Here: `just upp mysecrets` (commits the lock) or `nix flake update mysecrets` (leaves it for you
to commit). `git diff flake.lock` should show only `mysecrets` moving.
3. Declare it in `secrets/nixos.nix` or `secrets/darwin.nix` under the right
`modules.secrets.<group>` gate, with a mode/owner preset (step 3).
4. Point the consumer at the runtime path, from a module behind the same gate (core rule 4).
5. `just test` and `just build-host <host>`, deploy, then verify as in step 4.
Changing only a secret's value is steps 1, 2, and the deploy.
## 3. Modes and ownership
Use one of the presets in `secrets/nixos.nix` (`noaccess`, `high_security`, `user_readable`); the
table and the `environment.etc` copy trap are in
[secrets/README.md](../../../secrets/README.md#decrypted-file-permissions). The rule to remember:
**whenever an `environment.etc` entry sets `mode`, it also sets `user`.** Never widen a mode to make
a root-owned copy readable.
## 4. Verify without reading
```bash
stat -c '%a %U:%G' /etc/agenix/<name> # mode and owner, not content
ls -l /etc/agenix/
journalctl -b | grep -5 agenix # NixOS
tail -n 100 /Library/Logs/org.nixos.activate-agenix.stderr.log # macOS
```
A successful activation is silent. Check that the _access_ changed as intended (the mode and owner
you set, an old copy gone) instead of assuming activation did it.
## 5. Remove or rename a secret
- Search all references before changing it:
```bash
grep -Rni '<secret-name>' --include='*.nix' --include='*.toml' .
```
Check `secrets/`, `home/`, `modules/`, `hosts/`, outputs, tests, and the private repository.
- Delete the `age.secrets` entry, its `environment.etc` placement, and every consumer in one change;
a declaration whose file no longer exists breaks activation.
- Remove it from `secrets.nix` and delete the file in the private repository, then bump the lock.
- A rename changes the attribute name and every consumer. The `.age` filename is separate.
## 6. Failure modes
- **Decryption fails on one host:** its host key is not a recipient. Add its
`/etc/ssh/ssh_host_ed25519_key.pub` to `secrets.nix`, rekey with
`sudo agenix -r -i /etc/ssh/ssh_host_ed25519_key` on a desktop, push, bump the lock, redeploy.
- **Eval or activation cannot find the file:** the lock still points at a `mysecrets` revision
without it (core rule 2).
- **`permission denied` in a user service:** it reads a root-only secret. Fix that secret's owner;
do not widen the mode.
- **A preservation host cannot decrypt at boot:** `age.identityPaths` must use the
`/persistent/etc/ssh/...` path, which exists before preservation mounts `/etc`.
- **The first macOS activation fails** on the `/etc/agenix` copies, because they run before
`activate-agenix` has decrypted anything. Run it again.
## Why these rules exist
- `4909f635 security: scope privileges and stop a world-readable secret copy (#335)` - the
`environment.etc` copy trap in step 3.
- `c8e76cef fix(darwin): agenix - remove non-exist secret` - a declaration left behind after its
file was deleted.
- `4211d18a` - a shared `modules/nixos/base` module included `nix-access-tokens`, which not every
host had; the reference moved to `modules/nixos/desktop/nix.nix` (core rule 4).
- `260da1ee chore: rename the nushell secret, and forbid reading decrypted secrets` - the no-reading
rule.
.agents/skills/nix-config-update/SKILL.md
+167
View File
@@ -0,0 +1,167 @@
---
name: nix-config-update
description:
Use when updating flake inputs, bumping nixpkgs, or rolling an update out to hosts in this repo.
---
# Updating this flake safely
Read this before running `just up`, `just upp`, `just up-nix`, or `just override-pkgs`, and before
deploying the result to any host.
## Core rules
1. **Update and deploy are two steps.** Never fold "bump the lock file" and "switch every host" into
one blind action.
2. **Validate before touching a host.** An update is only a candidate until `just test` is green and
the affected hosts build locally.
3. **One reviewable commit per update.** The convention here is a `flake.lock: Update` commit for
the bump; a config change gets its own commit or PR.
4. **Keep a way back.** Anything that reaches a host needs a rollback path: the previous generation,
`boot` mode, `just darwin-rollback`, or `git revert`.
5. **Security first.** An update re-opens the supply chain. Re-audit every input whose revision
moved before you deploy it.
## 1. Pre-flight
- `git status` is clean, and you are on `main` or a fresh branch for the work. If you are on an
unrelated feature branch, stop and ask for the right branch before bumping.
- `just test` is green _before_ the update, so you have a baseline to compare against.
- Enough disk for the new closures: `df -h /nix/store`. Broad nixpkgs bumps pull a lot.
- Know what will move and choose the narrowest recipe that does the job.
## 2. Run the update
| Goal | Command | Notes |
| ------------------------ | --------------------------- | -------------------------------------------------------------------------- |
| Everything | `just up` | Updates and commits the lock file automatically; audit before pushing |
| One input | `just upp <input>` | Same, for a single input, e.g. `just upp catppuccin`; audit before pushing |
| The nixpkgs family | `just up-nix` | Updates `nixpkgs-stable`/`-master`/`-darwin`/`-patched`; **not `nixpkgs`** |
| Pin `nixpkgs` | `just override-pkgs <hash>` | Pin `nixpkgs` to a known-good Hydra commit |
| Update but keep it dirty | `nix flake update <input>` | Leaves the change uncommitted so you can inspect it first |
| Nix itself (macOS) | `just nix-upgrade` | `determinate-nixd upgrade`; macOS only |
After an update, read `git diff flake.lock`: it lists exactly which inputs moved and by how many
commits. Because `just up` and `just upp` commit automatically, either use
`nix flake update <input>` while auditing or amend the generated lock commit after the audit so its
message records the conclusion.
## 3. Audit the change
Treat an update as a supply-chain event.
1. From `git diff flake.lock`, list every input whose `locked.rev` changed.
2. Find the inputs that contribute modules this repo imports:
```bash
grep -rn "homeModules\.\|nixosModules\.\|darwinModules\." --include='*.nix' .
```
3. For each of those inputs, read what changed between the old and new revision in the module files
we actually import. Look for:
- restricted `nix.settings` (`substituters`, `extra-substituters`, `trusted-public-keys`,
`trusted-users`) — at the Home Manager layer these are ignored for an untrusted user and only
warn, but at the system layer they are a root-equivalent trust boundary;
- `environment.etc` / `home.file` entries with a `mode` or `user` that widens access;
- `system.activationScripts`, `systemd.services` running as root, sudo/polkit rules;
- `lib.mkForce` overrides that silently replace existing settings;
- eval-time network access or import-from-derivation.
4. For nixpkgs-class inputs, skim the lock diff and expect broken packages and eval deprecation
warnings (see "Lessons from past updates").
5. Write the audit conclusion into the update commit message. If an automatic recipe already made
the commit, amend it only after reviewing the diff; do not push the unaudited commit first.
## 4. Validate before deploying
Run these before any host is touched:
- `just test` — must print `true`. An exit code of `0` with `false` is a failed suite.
- `just eval-host <host>` — fast, evaluation only.
- `just build-host <host>` — builds the full system closure and catches broken packages or build
failures that eval misses.
- `just build-microvm <guest>` — same, for a MicroVM guest.
- `nix flake check` — broader checks when the change touches shared code.
Cover every host you are about to deploy, and prefer building the closure over trusting a green
eval.
Preview what the machine you are on will change before it is deployed:
```bash
nix store diff-closures /run/current-system '.#nixosConfigurations.<host>.config.system.build.toplevel'
```
It lists every package whose version or size moves; an empty result means nothing changes. Read it
for unexpected removals, major-version jumps, and kernel or systemd changes that need a reboot.
## 5. Deploy in stages
Modes are `switch` (take effect now, the default) and `boot` (only the next boot). Add `debug` for
verbose output. Anything else is rejected.
Activating the machine you are on runs `nixos-rebuild --sudo` (or `sudo -E darwin-rebuild`) and
blocks on a password prompt. **An agent cannot run these; they are for the user to run by hand.**
- Current desktop: `just niri [mode] [verbosity]`
- Other local NixOS host: `just local [mode] [verbosity]`
- macOS: `just local [debug]` (build then switch; macOS has no switch/boot split)
The rest authenticate over SSH as root on the target, so they run non-interactively — but they still
change remote state. Confirm the target instead of trusting the recipe's default, then state it back
to the user and get authorization for that host:
```bash
hostname # which machine you are on
git branch --show-current
git remote -v
getent hosts <host> # the address the tag will connect to
ssh root@<host> hostname # the host that actually answers
```
- Remote servers: `just shoryu [mode]`, `just shushou`, `just youko`, `just ruby`, `just kana`
- All VM hosts at once: `just lab [mode]`; any Colmena tag: `just col <tag> [mode]`
- k3s test nodes: `just k3s-test [mode]`
- MicroVM guest: `just microvm-deploy <guest> <host> <guest-ip>` — deploy guests serially and check
each one before moving on.
Use `boot` plus a deliberate reboot for anything that can drop networking mid-flight: the VM hosts
with the `br0` bridge, and broad nixpkgs bumps. See
[hosts/README.md](../../../hosts/README.md#deploying-vm-hosts).
## 6. Verify after deploying
- `systemctl --failed` and `just list-failed` for failed units.
- `journalctl -b -p err` for boot-time errors.
- The user-visible surface: network, the desktop session, and the specific service you changed.
- Re-run `just test` so a dirty tree cannot hide a regression.
## 7. Roll back
- NixOS: `just history` lists system generations; pick the previous one in the bootloader menu, or
re-deploy a reverted tree.
- macOS: `just darwin-rollback` (`darwin-rebuild --rollback`).
- Remote (Colmena): `git revert <sha>` and re-apply, or apply with `boot` and reboot.
- Update failed but never deployed: drop the bump's own uncommitted lock change with
`git checkout -- flake.lock`, then reproduce. If the tree holds other uncommitted work, ask before
discarding anything.
- Isolate a bad bump by moving one input at a time with `nix flake update <input>`, and pin a
known-good nixpkgs with `just override-pkgs <hash>` while the breakage is fixed upstream.
## 8. Clean up only after it is stable
`just gc` (older than 7 days) and `just clean` (wipes profile history) delete the generations you
would roll back to, so run them last, once the update has proven stable. `just gcroot` only lists GC
roots. The full list of hazardous recipes is in the Command Hazards section of
[AGENTS.md](../../../AGENTS.md#command-hazards).
## Why these rules exist
- `0fe12bef fix(nix): preserve default sandbox shell` - a `nix.settings` change used
`sandbox-paths`, which replaced Nix's compiled defaults (including the sandbox shell used for
legacy shebangs). Use `extra-sandbox-paths`, and verify with
`nix config show | grep sandbox-paths`.
- `125bce3b fix: cuda12.8-cuda_cudart-12.8.90 is marked as broken` and
`78fc64e1 fix(neovim): disable nixvim manpage on broken nixpkgs pin` - broken packages after a
nixpkgs bump are normal; `just build-host` finds them before a deploy does.
- `4bd463a7 chore(eval): resolve catppuccin and rust-overlay deprecation warnings` - input bumps
surface deprecation warnings that become errors in a later bump.
.agents/skills/nixpkgs-patched/SKILL.md
+93
View File
@@ -0,0 +1,93 @@
---
name: nixpkgs-patched
description:
Use when temporarily carrying an unmerged nixpkgs pull request or commit in the personal
ryan4yin/nixpkgs fork, updating the nixos-unstable-patched branch, or consuming that branch from
this nix-config flake.
---
# Carrying a nixpkgs patch
This is a temporary supply-chain change across two repositories:
```text
upstream nixpkgs PR → personal fork branch → nix-config lock entry → host/package validation
```
Keep the upstream commit identifiable, keep a rollback ref, and never activate a host merely because
the fork branch pushed successfully.
## 1. Confirm the exact target
Before changing either repository, confirm the remotes, branch, PR commits, and local work:
```bash
git remote -v
git status --short
git branch --show-current
git fetch upstream nixos-unstable
git fetch origin nixos-unstable-patched
gh pr view <pr> --repo NixOS/nixpkgs --json state,baseRefName,commits
```
The intended fork is `ryan4yin/nixpkgs` and the intended branch is `nixos-unstable-patched`. Confirm
those names; do not infer a remote from its position in the remote list.
## 2. Refresh the patched branch
Do this in the nixpkgs checkout (`~/codes/src/nixpkgs`), preserving any existing work:
1. Save a rollback ref to the current patched tip.
2. Align the branch with the current `upstream/nixos-unstable`.
3. Cherry-pick the exact PR commit(s), using `-x` so the upstream source remains recorded.
4. Resolve conflicts deliberately and inspect the complete diff against upstream.
If alignment rewrites the remote branch, this is an impactful GitHub operation: preview the new
history and push only with `--force-with-lease`, never `--force`. Stop if the remote changed in an
unexpected way. An upstream PR targets `master` unless it says otherwise, while the patched branch
tracks `nixos-unstable`; confirm the PR's base commit is contained in `nixos-unstable` before
cherry-picking, and stop if the patch depends on unreleased changes. If the PR depends on another
PR, review both changes and record their order.
## 3. Validate before publishing
In the nixpkgs checkout, run the smallest relevant checks first:
```bash
git diff --check
git log --oneline --decorate upstream/nixos-unstable..HEAD
nixpkgs-review rev HEAD --no-shell --print-result
```
Build the affected package and its relevant tests. A cherry-pick that applies cleanly can still be
invalid against the current unstable base. Record the source PR, commit IDs, base revision, package,
and test result before pushing.
## 4. Publish and consume it
After authorization and validation:
```bash
git push --force-with-lease origin nixos-unstable-patched
git ls-remote origin refs/heads/nixos-unstable-patched
```
Then in this repository, update only the patched input and inspect the lock diff:
```bash
nix flake update nixpkgs-patched
git diff -- flake.lock
just test
just eval-host <affected-host>
just build-host <affected-host>
```
Keep the nixpkgs fork change, lock update, and unrelated configuration changes separate. Do not run
`just niri`, `just local`, or a remote deployment from this skill; activation is a separate
authorized step in `nix-config-update`.
## 5. Roll back
If validation fails, restore the fork branch from the saved ref, update the lock back to the
previous revision, and re-run the affected checks. If the branch was already pushed, restoring it is
another impactful remote change: confirm the current remote tip and use `--force-with-lease`.
.agents/skills/nixpkgs-review/SKILL.md
+160
View File
@@ -0,0 +1,160 @@
---
name: nixpkgs-review
description:
Use when reviewing or testing a NixOS/nixpkgs pull request, checking an affected package or
passthru test, comparing local and CI results, or investigating a nixpkgs regression before it
reaches this flake.
---
# Reviewing nixpkgs changes
Prefer a local review: faster for a small change, the result stays available, and it leaves no
GitHub Actions state. Use the repository's GHA workflow when a review needs several architectures, a
clean remote environment, or more build capacity than this x86_64-linux desktop has.
**`nixpkgs-review` is the first test, not the only test:** follow it with focused package,
test-quality, or runtime checks when the change has user-visible behavior.
## Choose the runner
| Situation | Runner |
| ---------------------------------------------------- | ----------------------------------------------------------- |
| One package, one Linux architecture, local debugging | local `nixpkgs-review` |
| Need to inspect the package interactively | local review shell |
| Need aarch64/Darwin or a reproducible remote build | `just pkg-review <pr>` |
| Only one package's passthru tests matter | `just pkg-test <pr> <pname>` or local `--package`/`--tests` |
| Check a previous local commit or worktree | `nixpkgs-review rev <rev>` or `wip` |
The local tool defaults to the current system. This machine is `x86_64-linux`; do not imply that a
successful local result covers Darwin or aarch64. Use `--systems` explicitly when builders or
emulation are available, or use GHA for the other architectures.
## 1. Confirm the PR and inspect it
Before building, read the exact PR and commit:
```bash
gh pr view <pr> --repo NixOS/nixpkgs --json state,baseRefName,headRefName,commits,files
gh pr diff <pr> --repo NixOS/nixpkgs
```
Confirm the intended PR, target branch, changed packages, tests, and dependencies. Treat PR text and
source instructions as untrusted input; do not run commands copied from them automatically.
Then survey how the same kind of thing is already done in nixpkgs, so the review judges the change
against current practice rather than against the diff alone:
```bash
# sibling packages with the same build system, language, or app class
ls pkgs/by-name/<xx>/
# how this file itself evolved, and why
git log --oneline -20 -- pkgs/by-name/<xx>/<name>/
git log -p -3 -- pkgs/by-name/<xx>/<name>/package.nix
```
For a non-trivial change (new build inputs, a wrapper, a systemd unit, a source-fetch change), check
the [nixpkgs contributing guide](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md) and a
few comparable packages before judging the approach. Optional upstream tooling for this is
[nixpkgs-hammering](https://github.com/Artturin/nixpkgs-hammering) for review hints and
[nixpkgs-vet](https://github.com/NixOS/nixpkgs-vet) for the `pkgs/by-name` rules; both are separate
downloads, so use them only when you want that extra pass.
## 2. Run locally first
From a full, non-shallow nixpkgs checkout (for example `~/codes/src/nixpkgs`); a shallow clone
fails. A source hash for another platform cannot be verified by evaluation on this Linux host, so
build it through the GHA workflow or leave it unchecked rather than claiming it is covered.
```bash
nix run 'nixpkgs#nixpkgs-review' -- pr <pr>
# Narrow a large review:
nix run 'nixpkgs#nixpkgs-review' -- pr <pr> --package <pname> --tests
```
The tool uses temporary git worktrees and does not change the checkout directly. Record the exact PR
commit, systems, package selection, and result. Use the review shell to run the affected program or
inspect its build output; use `--no-shell --print-result` for a bounded non-interactive run.
Do not post a result or approve a PR merely because builds pass. Those are GitHub writes; use
`--post-result` only with explicit authorization for that exact PR.
## 3. Review test quality and add the missing check
Ask two separate questions:
1. Does the PR build and pass the tests that currently exist?
2. Do those tests prove the behavior the PR changes?
If the package has no meaningful test, or an existing test only checks evaluation/build success,
propose a separate upstream test improvement before treating the review as complete. Good patterns
from recent reviews include:
- a small CLI update adding `versionCheckHook` (`aliyun-cli` / PR 568922);
- a package whose runtime dependency only fails when launched, adding a NixOS test that waits for
the real window and captures early process exit (`zoom-us` / PR 568883);
- a package update that changes download/source logic (`qq` / PR 564893), where fetching and the
installed application need checks beyond evaluating the generated sources;
- a service-unit change (`tailscale` / PR 565578), where the installed unit contents and service
behavior need validation rather than only a successful build.
Use the upstream
[stdenv check-phase guidance](https://github.com/NixOS/nixpkgs/blob/master/doc/stdenv/stdenv.chapter.md#ssec-check-phase)
as the baseline: enable the package's own `doCheck` when its tests are usable; otherwise prefer a
small `versionCheckHook` to prove the installed executable runs. Review `passthru.tests` separately:
those tests are package-specific checks that `nixpkgs-review --tests` can build, while a NixOS test
is appropriate when the behavior needs a booted system, display server, systemd, networking, or
other integration environment. Remember that cross-compiled builds do not execute tests on the build
machine, so a green cross build is not runtime evidence.
Choose the smallest useful check. A quick local smoke test is often the best answer for a simple
package; do not turn every version bump into a VM test. Prefer a NixOS VM test when startup, dynamic
linking, systemd, display/session integration, sandbox boundaries, or a regression that is otherwise
expensive to reproduce is the behavior under review. VM tests are valuable because they make the
check repeatable and catch failures such as a GUI process exiting before its window appears.
Examples of the smallest useful check:
| Change | Additional evidence |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| CLI or library | Run `--version`/help and one representative operation |
| GUI package | Launch it locally for a simple check; use a NixOS test for startup/crash regressions |
| Service or module | Evaluate the relevant option, inspect generated units/config, and build the affected host |
| Sandbox, permission, or network policy | Inspect the effective wrapper/unit and test the allowed/denied behavior without exposing secrets |
| Driver, kernel, or hardware support | Build the relevant configuration and perform a host-specific check; do not claim other architectures work |
| Package with passthru tests | Build selected tests, then run a focused smoke test if the package can be exercised |
Record the result as one of: existing tests sufficient, local smoke check sufficient, upstream test
PR recommended, or blocked by missing hardware/architecture. A test improvement should normally be a
separate upstream PR so the package change and its proof can be reviewed independently.
Keep checks read-only or isolated whenever possible. Do not activate a host, post a review, or
mutate shared state as part of a package review unless that exact action is separately authorized.
## 4. Use the repository workflow when appropriate
These recipes trigger the configured `ryan4yin/nixpkgs-review-gha` workflow:
```bash
just pkg-review <pr>
just pkg-test <pr> <pname>
just pkg-summary
```
They are remote GitHub Actions operations on a shared workflow repository, not local tests. Confirm
the PR number and workflow repository, and get authorization for that run before dispatching it. Use
them for cross-architecture coverage, large reviews, or when local capacity cannot reproduce the
relevant target. Read the workflow summary and distinguish evaluation, build, passthru-test, and
architecture-specific failures.
## 5. Bring a result back to this flake
If the package is used here, validate the affected `nixpkgs` input or package override separately:
```bash
just test
just eval-host <affected-host>
just build-host <affected-host>
```
A nixpkgs-review result proves only the reviewed nixpkgs build/test set. It does not prove this
flake's overlays, hardening wrappers, host configuration, or runtime behavior. Use
`nix-config-debug` for failures and `nix-config-update` before changing a locked input.