0 Fork 0

mirror of https://github.com/ryan4yin/nix-config.git synced 2026-11-13 12:13:36 +01:00

Files

T

Ryan Yin be592ae75c refactor(mihomo): link geodata from nixpkgs instead of seeding it by hand

`just mihomo-geo` copied geodata into the state dir so a cold start never
fetched it. tmpfiles now links v2ray-rules-dat and the DB-IP lite mmdbs
there, so geo-auto-update moves to the gateway config only.

Assisted-by: Claude Code (claude-opus-5-5)

2026-11-01 11:55:14 -06:00

9.6 KiB

Raw Blame History

Repository Agent Guide

This flake manages NixOS hosts, macOS via nix-darwin, shared Home Manager profiles, and Colmena deployments. Keep repository guidance here; the global rules and global skills shared across projects live in agents/.

Where Changes Belong

flake.nix defines inputs; outputs/default.nix composes outputs for x86_64-linux, aarch64-linux, and aarch64-darwin.
modules/ contains system modules; home/ contains Home Manager modules. Put shared behavior here rather than duplicating it in host configurations.
hosts/ contains host-specific configuration; outputs/<system>/src/ wires hosts into outputs.
vars/ and lib/ provide shared values and helpers. Use myvars and existing abstractions instead of hardcoding usernames or paths.
secrets/ contains agenix definitions. The encrypted .age files live in the private ~/codes/nix-secrets repository, never in this public one — never copy a .age file here. Use the nix-config-secrets skill.
overlays/ and hardening/ hold package overlays and hardened (nixpak/bwrap) wrappers.
Desktop (Niri and Noctalia) config is mostly out-of-store symlinks that hot-reload without a rebuild; use the nix-config-desktop skill before changing it.

Commands and Platforms

Prefer recipes in Justfile; use just --list to discover available commands and just --show <recipe> to inspect behavior before running them.
The Justfile uses Nushell. Preserve [linux] / [macos] guards and host naming conventions.
Deploy by hostname: NixOS desktops are <hostname>-niri (just niri); other NixOS hosts, VMs, and macOS hosts use the bare hostname (just local, mapping to nixos-switch, or darwin-build / darwin-switch on macOS). Arguments differ per platform; check both when changing shared behavior.
nix develop provides formatters and linters. If needed, nix shell nixpkgs#just nixpkgs#nushell provides the task runner and its shell.

Validation

For Nix changes, run just fmt and inspect the diff: it formats all Nix files. Nix style is nixfmt, whose default width is 100.
For supported non-Nix files, use prettier --write <file> and prettier --check <file>; configuration lives in .prettierrc.yaml. Spelling checks use typos and .typos.toml.
Run just test for configuration changes; it evaluates .#evalTests across Linux and Darwin and exits non-zero unless the result is true. The bare nix eval .#evalTests exits 0 even on false, so run just test or compare its --json output yourself.
Eval tests are expr.nix / expected.nix pairs under outputs/<system>/tests/. Update focused cases when changing behavior covered by those tests.
Use nix flake check for broader flake checks. A host build can validate changes beyond eval: nix build .#nixosConfigurations.<host>.config.system.build.toplevel.
Documentation-only changes need formatting checks and git diff --check; Nix tests may be skipped. Report checks run, skipped, or blocked, including the command and reason for failures.

Nix Conventions

Before a non-trivial change, find how nixpkgs (or the upstream project) already does it and follow that shape instead of inventing a local convention. This covers a new package or overlay, a hardening wrapper, a systemd unit, a kernel or driver option, and a version bump that changes the build inputs. Look at the by-name siblings under pkgs/by-name/<xx>/<name>/, the recent history of the file you are changing, and the upstream contributing docs.
Use kebab-case.nix filenames and inherit (...) for attribute imports.
Prefer lib.mkIf, lib.optional, and lib.optionals for conditional configuration.
Use lib.mkDefault for defaults and lib.mkForce only when necessary.
Give module options a description and preserve platform-specific conditions.

AI Disclosure

Follow the Nixpkgs Automation/AI policy for disclosure of AI-assisted contributions:

Every commit containing non-trivial AI-generated code, documentation, or commit-message text MUST include an Assisted-by: Git trailer, even when the generated text was subsequently edited.
The trailer MUST identify the tool and the primary model's name and version, for example: Assisted-by: DeepSeek Harness (gpt-6.1-sol). Record the actual identifiers used; if unavailable, obtain them before committing rather than guessing. Co-authored-by: does not satisfy this rule.
Preserve applicable Assisted-by: trailers when amending, rebasing, or squashing commits. Before committing, verify that the final message contains the required disclosure.
AI-generated PR descriptions, reviews, and issue comments MUST disclose AI assistance separately; commit trailers alone do not cover them. Routine formatting and short boilerplate completions are exempt. Research, testing, debugging, and private review are exempt when no substantial generated output is included in the contribution; disclose significant technical influence where relevant.

Security

Security architecture, control limitations, rollout checks, and prioritized work are documented in SECURITY.md. Keep it consistent with changes to security boundaries or defaults.

Workarounds

Temporary workarounds, version pins, carried patches, and known gaps are recorded in WORKAROUNDS.md, each with a removal condition. Add a row in the same change that introduces one, and re-evaluate entries when their Revisit trigger comes up.

Command Hazards

just eval-host <host>, just build-host <host>, just build-microvm <guest>, and just test evaluate or build without activating a system. Use these commands for previews and validation.
just up, just upp, just up-nix, and just override-pkgs <hash> update flake inputs and commit the lock file. Use nix flake update <input> when the update should remain uncommitted.
git push publishes: to GitHub and, through the mirror workflow, to Gitee. Commit locally as needed; ask the user before pushing.
just niri and just local activate the machine you are on through sudo and block on a password prompt; just darwin-rollback switches the macOS generation on the machine you are on, and a bare sudo systemctl restart <unit> activates a running service the same way. just shoukei-home-wifi (a persistent NetworkManager profile) changes the local machine through sudo too. The user runs these, not an agent.
just shoryu, just shushou, just youko, just aquamarine, just ruby, just kana, just lab, just k3s-test, and just col <tag> activate systems through Colmena. Use the narrower recipe that matches the intended host scope.
just microvm-deploy <guest> <physical-host> installs one MicroVM guest's runner on the physical host and restarts its unit there. A later host activation re-points the guest at the runner baked into the host's system; see WA-026 in WORKAROUNDS.md before deploying. Deploy guests serially and check the guest Node and host services after each activation.
VM hosts (shoryu, shushou, youko) carry the br0 bridge for their guests. Use the boot-based host deployment procedure for network stack or broad nixpkgs changes; see hosts/README.md.
MicroVM state is stored in /var/lib/microvms/<name>/{etc,var,home}.img. Preserve these images when changing the guest configuration.
just clean, just gc, just ggc, and just game remove state or rewrite history. Use them only for the intended cleanup or history operation.
just penvof reads a process environment and can expose secrets. Use normal process inspection commands when environment values are not required.
just del-failed deletes failed pods in every namespace of the current kube context.
just pkg-review <pr> and just pkg-test <pr> <pname> dispatch a workflow in ryan4yin/nixpkgs-review-gha that posts its result on the nixpkgs PR, a public GitHub write.

Task Skills

Repo-scoped task procedures live in .agents/skills/ (leading dot; agents discover them and list them in their skill catalog). agents/ without the dot holds the global rules and skills.

When a change here affects one of these, make both edits in the same task, one branch or PR per repository, and cross-link them — no need to be told.

~/codes/k8s-gitops — Flux cluster state for the k3s cluster whose hosts are defined in hosts/k8s and hosts/12kingdoms-youko (NFS golden store, kube-vip block, br0). Host networking, VM images, or cluster addons usually change both repositories together.
~/codes/containers — container images consumed by k8s-gitops; a tag bump is often a two-repo change.
~/codes/nix-secrets — the private agenix store behind secrets/ and the mysecrets input: ciphertext and recipient rules for the secrets declared here.
wallpapers, nur-ryan4yin, nu_scripts, mattpocock-skills, i-have-adhd — flake inputs from the user's own repositories; bump with just upp <input> after their source changes, do not edit them from here.

9.6 KiB Raw Blame History