kfm/niveum
1
0
Fork 0
mirror of https://github.com/kmein/niveum synced 2026-03-16 10:11:08 +01:00
Code Releases Activity

update AGENTS.md with current state

Browse Source 
- Remove resolved issues (broken refs, orphaned packages, dead code)
- Add coding conventions section (lib.getExe, writer patterns)
- Fix machine table (kibbeh/zaatar/tabula/tahina profiles are correct now)
- Trim improvement ideas to remaining items only
This commit is contained in:
Kierán Meinhardt
2026-02-17 21:36:09 +01:00
parent e67d6d7df2
commit 6fe970ae3a
1 changed files with 46 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files

99
AGENTS.md
View File

@@ -8,8 +8,8 @@ Levantine food-themed hostnames: fatteh, kabsa, kibbeh, makanek, manakish, tabul
## Repository Structure ## Repository Structure
``` ```
flake.nix # ~650 lines — everything: inputs, overlay, nixosConfigurations, apps, packages flake.nix # ~670 lines — inputs, overlay, nixosConfigurations, apps, packages output
configs/ # ~50 NixOS config fragments imported by systems (desktop defaults, programs, services) configs/ # ~50 NixOS config fragments imported by systems
default.nix # 200+ line mega-module for desktop machines (user, shell, gnupg, i18n, etc.) default.nix # 200+ line mega-module for desktop machines (user, shell, gnupg, i18n, etc.)
graphical/ # Hyprland + home-manager config (415 lines in home-manager.nix) graphical/ # Hyprland + home-manager config (415 lines in home-manager.nix)
packages.nix # ~250 lines of environment.systemPackages packages.nix # ~250 lines of environment.systemPackages
@@ -30,74 +30,67 @@ secrets/ # agenix-encrypted .age files (empty dir in checkout, tracked
- **profiles** (in flake.nix): `profiles.default`, `profiles.desktop`, `profiles.server` — lists of modules composed per machine. - **profiles** (in flake.nix): `profiles.default`, `profiles.desktop`, `profiles.server` — lists of modules composed per machine.
- **lib.niveum**: Custom lib injected via overlay (`pkgs.lib.niveum`) — used everywhere for machine addresses, SSH port, helper functions. - **lib.niveum**: Custom lib injected via overlay (`pkgs.lib.niveum`) — used everywhere for machine addresses, SSH port, helper functions.
## Coding Conventions
- Packages use `writers.writeDashBin`, `writers.writeBashBin`, or `writers.writePython3Bin`
- Dependencies are referenced via `lib.getExe pkg` (main executable) or `lib.getExe' pkg "name"` (specific binary)
- For packages needing many commands via PATH, use `lib.makeBinPath` instead (see `packages/prospekte.nix`)
- Overlay entries use `prev.callPackage packages/foo.nix { }` pattern
- Packages are exported via `inherit (pkgs) ...` in the `packages` output
## Known Bugs / Broken References ## Known Bugs / Broken References
All previously broken references have been fixed. See git log for details. All previously broken references have been fixed (see commits `36132b04`, `e67d6d7d`).
The deleted files (`configs/admin-essentials.nix`, `configs/nix.nix`, `configs/zsh.nix`,
`configs/tmux.nix`) were superseded by niphas modules already present in `profiles.default`. Remaining issues:
- `modules/retiolum.nix` uses `<retiolum/hosts>` and `<system-secrets/...>` NIX_PATH lookups — breaks flake purity but works with current `NIX_PATH` setup
## Architectural Issues ## Architectural Issues
### 1. flake.nix is a monolith (636 lines) ### 1. configs/default.nix is a grab-bag (200+ lines, ~15 inline anonymous modules)
The overlay alone is ~180 lines. The nixosConfigurations block is ~170 lines. Overlay, apps, packages output, nixosConfigurations, profiles — all in one file. It's a list of `imports` mixing inline `{ ... }` blocks with file imports. Hard to find what's defined where.
### 2. configs/default.nix is a grab-bag (200+ lines, ~15 inline anonymous modules) ### 2. Retiolum secret boilerplate repeated 9 times
It's a list of `imports` mixing inline `{ ... }` blocks with file imports. Hard to find what's defined where. Many of these inline blocks should be their own files (user config, i18n, gnupg, dconf, xdg dirs, etc.).
### 3. Retiolum secret boilerplate repeated 9 times
Every system has a near-identical block: Every system has a near-identical block:
```nix ```nix
age.secrets.retiolum-rsa = { file = ../../secrets/${hostname}-retiolum-privateKey-rsa.age; mode = "400"; owner = "tinc-retiolum"; group = "tinc-retiolum"; }; age.secrets.retiolum-rsa = { file = ../../secrets/${hostname}-retiolum-privateKey-rsa.age; mode = "400"; owner = "tinc-retiolum"; ... };
age.secrets.retiolum-ed25519 = { ... same ... }; age.secrets.retiolum-ed25519 = { ... same ... };
``` ```
This could be a function or module parameterized by hostname. Could be a function or module parameterized by hostname.
### 4. Nginx + ACME boilerplate duplicated ### 3. Nginx + ACME boilerplate duplicated
ful and makanek have identical nginx recommended settings + ACME config. Should be a shared server profile. ful and makanek have identical nginx recommended settings + ACME config.
### 5. modules/retiolum.nix uses NIX_PATH lookups (`<retiolum/hosts>`, `<system-secrets/...>`) ### 4. niveum-* overlay aliases
This breaks flake purity. The `configs/retiolum.nix` partially overrides the key paths to use agenix, but the hosts file and extraHosts still use `<retiolum/...>`. `niveum-terminal`, `niveum-browser`, `niveum-filemanager` are aliases to niphas equivalents. Could be removed by updating ~6 references in configs/ to use niphas-* names directly.
### 6. Orphaned packages ### 5. The `pkgs.lib.niveum` pattern
- `packages/gpt.nix`, `packages/hora.nix`, `packages/k-lock.nix` — not in overlay, not referenced anywhere Custom lib injected via overlay into `pkgs.lib`. Unconventional — only available where overlay is applied. A `specialArgs` approach or standalone lib would be cleaner.
- `wallpapers` flake input — declared but never referenced in outputs
- `naersk` and `fenix` inputs — only used transitively via `follows`, not directly
### 7. niveum-* overlay aliases ### 6. Restic backup config scattered
After our cleanup, `niveum-terminal`, `niveum-browser`, `niveum-filemanager` are aliases to niphas equivalents. These could be removed by updating the ~6 references in configs/i3.nix, configs/graphical/home-manager.nix, configs/default.nix to use niphas-* names directly. `services.restic.backups.niveum` is configured in configs/backup.nix, configs/applicative.nix, and extended in 5+ system files. Hard to see what a given machine backs up.
### 8. The `pkgs.lib.niveum` pattern ### 7. configs/ vs modules/ distinction blurry
Custom lib is injected via overlay into `pkgs.lib`. This works but is unconventional — it means the lib is only available where the overlay is applied, and it pollutes the pkgs namespace. A `specialArgs` approach or a standalone lib would be cleaner. `configs/` has both stateless config fragments (spacetime.nix = timezone) and stateful ones (backup.nix, cloud.nix). `modules/` has proper option-declaring modules. Some configs/ files import from modules/.
### 9. Restic backup config scattered
`services.restic.backups.niveum` is configured in configs/backup.nix, configs/applicative.nix, and extended in 5+ system files. The module system merges these, but it's hard to see what a given machine backs up without reading multiple files.
### 10. configs/ vs modules/ distinction is unclear
`configs/` has both stateless config fragments (spacetime.nix = timezone) and stateful ones (backup.nix, cloud.nix). `modules/` has proper option-declaring modules. Some configs/ files (like power-action.nix) are actually imported from modules/. The boundary is blurry.
## Machines Overview ## Machines Overview
| Machine | Role | Profile | Arch | Notes | | Machine | Role | Profile | Arch | Notes |
|-----------|--------------|------------------|--------------|------------------------------------| |-----------|--------------|------------------|---------|---------------------------------------|
| fatteh | Desktop | default+desktop | x86_64 | ThinkPad T480, CUDA, main daily | | fatteh | Desktop | default+desktop | x86_64 | ThinkPad T480, CUDA, main daily |
| kabsa | Desktop | default+desktop | x86_64 | ThinkPad X220, constrained (2 jobs)| | kabsa | Desktop | default+desktop | x86_64 | ThinkPad X220, constrained (2 jobs) |
| manakish | Desktop | default+desktop | x86_64 | ThinkPad X230 | | manakish | Desktop | default+desktop | x86_64 | ThinkPad X230 |
| kibbeh | Desktop | custom (broken!) | x86_64 | Pantheon DE, travel laptop | | kibbeh | Desktop | default+desktop | x86_64 | Pantheon DE, travel laptop |
| ful | Server | default+server | aarch64 | Oracle/Hetzner, nginx, web services| | ful | Server | default+server | aarch64 | Oracle/Hetzner, nginx, web services |
| makanek | Server | default+server | x86_64 | Hetzner, gitea, nextcloud, weechat | | makanek | Server | default+server | x86_64 | Hetzner, gitea, nextcloud, weechat |
| zaatar | Server/Home | custom (broken!) | x86_64 | Home assistant, backup server | | zaatar | Server/Home | default+server | x86_64 | Home assistant, backup server |
| tabula | Family laptop| custom (broken!) | x86_64 | LXQt, user "xenos" | | tabula | Family laptop| default | x86_64 | LXQt, user "xenos" |
| tahina | Family laptop| custom (broken!) | x86_64 | Pantheon, user "xenos", German | | tahina | Family laptop| default | x86_64 | Pantheon, user "xenos", German |
## Improvement Ideas (Prioritized) ## Remaining Improvement Ideas
1. **Fix broken references** (5 files reference deleted configs) 1. **Extract retiolum secret boilerplate** into a function/module
2. **Extract retiolum secret boilerplate** into a function/module 2. **Break up configs/default.nix** into proper named files
3. **Split flake.nix** — at minimum extract the overlay to `overlay.nix` 3. **Extract nginx+ACME server profile**
4. **Break up configs/default.nix** into proper named files 4. **Replace niveum-* aliases** with direct niphas-* references
5. **Remove orphaned packages** (gpt.nix, hora.nix, k-lock.nix) 5. **Fix modules/retiolum.nix** NIX_PATH usage for flake purity
6. **Remove unused flake inputs** (wallpapers)
7. **Clean up nixosModules.zsh-kmein** (references deleted file)
8. **Extract nginx+ACME server profile**
9. **Replace niveum-* aliases** with direct niphas-* references
10. **Fix modules/retiolum.nix** NIX_PATH usage for flake purity