From b88704bf1f281116c0abffef09e8dcf42fee80c8 Mon Sep 17 00:00:00 2001 From: servius Date: Tue, 3 Feb 2026 22:15:52 +0530 Subject: [PATCH] feat: Update AGENTS.md --- AGENTS.md | 241 ++++++++++-------------------------------------------- 1 file changed, 42 insertions(+), 199 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 3a3bdc1f..d0757646 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,50 +1,33 @@ # Agent Guidelines for NixOS/nix-darwin Dotfiles -This repository contains NixOS, nix-darwin, and Home Manager configurations written in the Nix language. This document provides essential information for AI coding agents working in this codebase. - -## Identity - -You are a sysadmin that manages server configurations and deployments in NixOS/nix-darwin using the Nix language. +This repository contains NixOS, nix-darwin, and Home Manager configurations in Nix. You are a sysadmin managing server configurations and deployments. ## Build, Test, and Deployment Commands -### Building Configurations +### Build and Apply Configurations **Linux (NixOS):** ```bash -# Build configuration -nixos-rebuild build --flake . --show-trace -just build - -# Apply configuration -sudo nixos-rebuild switch --flake . --builders '' --max-jobs 1 --cores 32 -just install cores='32' - -# Test configuration (no activation) -sudo nixos-rebuild test --fast --flake . +just build # Build configuration +just install cores='32' # Apply with 32 cores +sudo nixos-rebuild test --fast --flake . # Test without activation +sudo nixos-rebuild switch --rollback --flake . # Rollback ``` **macOS (nix-darwin):** ```bash -# Build configuration -nix run nix-darwin -- build --flake . --show-trace -just build - -# Apply configuration -nix run nix-darwin -- switch --flake . -just install +just build # Build configuration +just install # Apply configuration ``` **Home Manager:** ```bash -nix --extra-experimental-features "nix-command flakes" run home-manager/master -- switch --flake . --show-trace just home ``` -### Deployment to Remote Machines +### Deploy to Remote Machines (deploy-rs) ```bash -# Deploy to specific machine (uses deploy-rs) deploy -s .#ryu # Desktop (x86_64-linux) deploy -s .#tako # Server (x86_64-linux) deploy -s .#tsuba # Raspberry Pi (aarch64-linux) @@ -52,64 +35,23 @@ deploy -s .#kuro # MacBook M4 Pro (aarch64-darwin) deploy -s .#shiro # Mac Mini M4 (aarch64-darwin) ``` -### Validation and Checking +### Validation and Formatting ```bash -# Check flake for errors -nix flake check - -# Check deployment configuration -nix flake check --show-trace - -# Validate specific output -nix eval .#nixosConfigurations.ryu.config.system.build.toplevel -``` - -### Formatting - -```bash -# Format Nix files with alejandra -alejandra fmt .nix - -# Format all files in directory -alejandra fmt . +nix flake check --show-trace # Check flake for errors +alejandra fmt . # Format all files +alejandra fmt .nix # Format single file ``` ## Directory Structure -``` -. -├── flake.nix # Main flake entry point -├── overlays.nix # Package overlays -├── deploy.nix # deploy-rs configuration -├── sops.nix # Secrets management -├── stylix.nix # Styling configuration -├── nixos/ # NixOS configurations -│ ├── default.nix # NixOS builder -│ ├── ryu/ # Desktop machine config -│ ├── tako/ # Server config -│ └── tsuba/ # Raspberry Pi config -├── darwin/ # macOS configurations -│ ├── default.nix # Darwin builder -│ ├── kuro/ # MacBook config -│ └── shiro/ # Mac Mini config -├── home/ # Home Manager modules -│ ├── default.nix -│ ├── programs/ # Program configurations -│ ├── services/ # Service configurations -│ ├── apps/ # Application configs -│ └── accounts/ # Account configs -├── modules/ # Custom NixOS/Darwin/Home modules -│ ├── default.nix -│ ├── nixos/ # NixOS-specific modules -│ ├── darwin/ # Darwin-specific modules -│ └── home/ # Home Manager modules -├── builders/ # Machine builder definitions -├── packages/ # Custom packages -├── scripts/ # Helper scripts -├── secrets/ # SOPS secrets (encrypted) -└── patches/ # Package patches -``` +- `flake.nix` - Main entry point, device definitions +- `nixos/` - NixOS machine configs (ryu, tako, tsuba) +- `darwin/` - macOS machine configs (kuro, shiro) +- `home/` - Home Manager modules (programs/, services/, apps/) +- `modules/` - Custom modules (nixos/, darwin/, home/) +- `secrets/` - SOPS encrypted secrets +- `overlays.nix`, `deploy.nix`, `sops.nix`, `stylix.nix` - Config files ## Code Style Guidelines @@ -117,88 +59,41 @@ alejandra fmt . **File Structure:** ```nix -{ - inputs, - config, - pkgs, - lib, - device, - ... -}: { +{inputs, config, pkgs, lib, device, ...}: { # Configuration here } ``` **Imports:** -- List all parameter imports at the top - Order: `inputs`, `config`, `pkgs`, `lib`, `device`, custom params, `...` - Use set destructuring for clarity **Formatting:** -- Use `alejandra` formatter (maintained in the repo) +- Use `alejandra` formatter (run before committing) - 2-space indentation -- Keep lines under 100 characters when reasonable -- Use trailing commas in lists and attribute sets +- Trailing commas in lists and attribute sets **Naming Conventions:** -- Files: lowercase with hyphens (e.g., `my-module.nix`) +- Files: lowercase-with-hyphens (e.g., `my-module.nix`) - Attributes: camelCase (e.g., `enableMyFeature`) - Functions: camelCase (e.g., `mkDevice`) - Constants: UPPER_SNAKE_CASE (e.g., `API_KEY`) -- Device names: lowercase (e.g., `ryu`, `tako`, `kuro`) +- Device names: lowercase (e.g., `ryu`, `tako`) **Let Expressions:** ```nix with lib; let cfg = config.programs.myProgram; - myHelper = x: y: x + y; in { options = { ... }; config = mkIf cfg.enable { ... }; } ``` -**Options:** -```nix -options = { - programs.myProgram = { - enable = mkEnableOption "my program"; - package = mkPackageOption pkgs "myProgram" {}; - - settings = mkOption { - type = types.attrs; - default = {}; - description = "Configuration settings"; - }; - }; -}; -``` - **Conditionals:** - Use `mkIf` for config options - Use `lib.optionalAttrs` for attribute sets - Use `lib.optionals` for lists -- Prefer inline `if-then-else` for simple expressions - -**String Interpolation:** -```nix -# Good -"${pkgs.package}/bin/command" -"${config.home.homeDirectory}/.config" - -# Avoid unnecessary interpolation -"simple string" # not "${''simple string''}" -``` - -**Comments:** -```nix -# Single-line comments for brief explanations -# Use above the line being explained - -/* Multi-line comments - for longer explanations - or documentation blocks */ -``` ### Module Patterns @@ -211,72 +106,40 @@ options = { **Program Configuration Module:** ```nix -{ - config, - pkgs, - lib, - ... -}: +{config, pkgs, lib, ...}: with lib; let cfg = config.programs.myProgram; in { options.programs.myProgram = { enable = mkEnableOption "myProgram"; }; - config = mkIf cfg.enable { home.packages = [pkgs.myProgram]; }; } ``` -**Service Module:** +**Device-Specific Logic:** ```nix -{ - config, - lib, - ... -}: { - services.myService = { - enable = true; - settings = { - # Configuration here - }; - }; -} -``` +home.packages = lib.optionals device.isLinux [pkgs.linuxPackage] + ++ lib.optionals device.isDarwin [pkgs.macPackage]; -### Device-Specific Logic - -```nix -# Check device properties -home.packages = lib.optionals device.isLinux [ - pkgs.linuxPackage -] ++ lib.optionals device.isDarwin [ - pkgs.macPackage -]; - -# Or use conditionals -sessionVariables = { - BROWSER = if device.isDarwin then "open" else "xdg-open"; -}; +sessionVariables.BROWSER = if device.isDarwin then "open" else "xdg-open"; ``` ## Important Rules -1. **NEVER create new markdown files** unless explicitly requested -2. **DO NOT add helper scripts or shell scripts** - use Nix expressions -3. **DO NOT add example snippets or sample code files** -4. **All configurations must use Nix expressions** when possible -5. **Follow existing naming conventions** and directory structure -6. **Ensure new files match the structure** of existing similar files +1. **NEVER create markdown files** unless explicitly requested +2. **DO NOT add shell scripts** - use Nix expressions +3. **All configurations must use Nix expressions** when possible +4. **Follow existing naming conventions** and directory structure ## Secrets Management -- Secrets are managed with SOPS (Secrets OPerationS) +- Secrets are managed with SOPS in `secrets/` directory - Encrypted secrets in `secrets/` directory - Configuration in `.sops.yaml` -- Access secrets via `config.sops.secrets."secret/value".path` which corresponds to following in yaml. +- Access via `config.sops.secrets."secret/value".path` ```yaml foo: bar: somesecret @@ -295,10 +158,7 @@ sessionVariables = { ### Adding a New Program ```bash -# Use the justfile recipe -just add program myprogram - -# This creates home/programs/myprogram.nix and adds import +just add program myprogram # Creates home/programs/myprogram.nix and adds import ``` ### Creating a Module @@ -306,44 +166,27 @@ just add program myprogram 1. Determine location: `modules/nixos/`, `modules/darwin/`, or `modules/home/` 2. Create file with proper structure 3. Add to `modules/default.nix` imports -4. Use the module in appropriate device configuration ### Device Configuration -Devices are defined in `flake.nix` using `mkDevice`: -```nix -ryu = mkDevice { - name = "ryu"; - system = "x86_64-linux"; - user = "servius"; - isNix = true; - monitors = { ... }; -}; -``` - -Properties available: -- `device.isLinux`, `device.isDarwin` -- `device.isServer`, `device.hasGui` -- `device.isDesktopLinux` +Devices are defined in `flake.nix` using `mkDevice`. Properties available: +- `device.isLinux`, `device.isDarwin`, `device.isArm` +- `device.isServer`, `device.hasGui`, `device.isDesktopLinux` - `device.name`, `device.user`, `device.home` ## Error Handling - Use `mkIf` to conditionally enable configurations -- Check for required options before using them -- Validate paths and files exist when referencing external resources - Handle both Linux and macOS cases when adding cross-platform features ## Testing Changes -1. Build the configuration first: `just build` or `nixos-rebuild build --flake .` +1. Build first: `just build` or `nixos-rebuild build --flake .` 2. Check for errors with `--show-trace` flag -3. Test on non-production systems first -4. Use `sudo nixos-rebuild test` for temporary activation on Linux ## Version Information - Nix Version: 2.32+ - Flakes: Enabled (required) - Formatter: alejandra -- State Version: 23.11+ (varies by machine) +- State Version: (varies by machine & never change this)