infra/AGENTS.md

AGENTS.md

This document outlines the development conventions for this NixOS-based infrastructure repository.

Build & Deployment

• Build/Deploy: Use nixos-rebuild switch --flake .#<hostname> to build and deploy the configuration for a specific host.
• CRITICAL — Validate before pushing: Always nix build --no-link '.#nixosConfigurations.<hostname>.config.system.build.toplevel' (or nh os build) and confirm it succeeds before pushing any changes. Never push untested NixOS configs.
• Development Shell: Activate the development environment with nix develop.

Linting & Formatting

• Formatting: This project uses nixpkgs-fmt for automatic formatting. Ensure it is run before committing changes.
  • nixpkgs-fmt .
• Linting: No specific linter is configured, but adhere to standard Nix language conventions.

Testing

• No automated testing suite is configured. Manually verify changes by deploying to a non-critical host.

Code Style & Conventions

• Imports: Keep module imports clean and organized at the top of files.
• Naming: Follow Nix community conventions for variable and function names (e.g., camelCase for variables, kebab-case for package names).
• Secrets: Secrets are managed with agenix. Edit encrypted files with agenix -e <file>.
• Modularity: Structure configurations into logical, reusable modules under modules/. New modules should be registered in modules/nixos/default.nix to be available to all hosts.
• Error Handling: Ensure Nix expressions are robust and handle potential evaluation errors gracefully.

Workflow

• New feature → clean branch from origin/master → push → PR on Gitea
• Branch naming: feat/description (features), fix/description (bugs/docs)
• Always branch from origin/master, never from another feature branch
• Submodule changes: commit submodule update in parent repo (the parent commit pins the submodule commit)
• PR title should describe the change; body should explain motivation + summary
• After PR merge, delete the feature branch