136 lines
3.4 KiB
Markdown
136 lines
3.4 KiB
Markdown
# AGENTS.md
|
|
|
|
## ⚠️ VERSION CONTROL: JUJUTSU (jj) ONLY
|
|
**NEVER run git commands.** This repo uses Jujutsu (`jj`). Use `jj status`, `jj diff`, `jj commit`, etc.
|
|
|
|
## Build Commands
|
|
|
|
### Local Development
|
|
```bash
|
|
nix run .#build # Build current host config
|
|
nix run .#build -- <hostname> # Build specific host (chidi, jason, michael, mindy, tahani)
|
|
nix run .#apply # Build and apply locally (darwin-rebuild/nixos-rebuild switch)
|
|
nix flake check # Validate flake
|
|
```
|
|
|
|
### Remote Deployment (NixOS only)
|
|
```bash
|
|
colmena build # Build all NixOS hosts
|
|
colmena apply --on <host> # Deploy to specific NixOS host (michael, mindy, tahani)
|
|
colmena apply # Deploy to all NixOS hosts
|
|
```
|
|
|
|
### Formatting
|
|
```bash
|
|
alejandra . # Format all Nix files
|
|
```
|
|
|
|
## Code Style
|
|
|
|
### Formatter
|
|
- **Tool**: Alejandra
|
|
- **Config**: `alejandra.toml` specifies tabs for indentation
|
|
- **Command**: Run `alejandra .` before committing
|
|
|
|
### File Structure
|
|
- **Hosts**: `hosts/<hostname>/` - Per-machine configurations
|
|
- Darwin: `chidi`, `jason`
|
|
- NixOS: `michael`, `tahani`
|
|
- **Profiles**: `profiles/` - Reusable program/service configurations (imported by hosts)
|
|
- **Modules**: `modules/` - Custom NixOS/darwin modules
|
|
- **Lib**: `lib/` - Shared constants and utilities
|
|
- **Secrets**: `secrets/` - SOPS-encrypted secrets (`.sops.yaml` for config)
|
|
|
|
### Nix Language Conventions
|
|
|
|
**Function Arguments**:
|
|
```nix
|
|
{inputs, pkgs, lib, ...}:
|
|
```
|
|
Destructure arguments on separate lines. Use `...` to capture remaining args.
|
|
|
|
**Imports**:
|
|
```nix
|
|
../../profiles/foo.nix
|
|
```
|
|
Use relative paths from file location, not absolute paths.
|
|
|
|
**Attribute Sets**:
|
|
```nix
|
|
options.my.gitea = {
|
|
enable = lib.mkEnableOption "Gitea git hosting service";
|
|
bucket = lib.mkOption {
|
|
type = lib.types.str;
|
|
description = "S3 bucket name";
|
|
};
|
|
};
|
|
```
|
|
One attribute per line with trailing semicolons.
|
|
|
|
**Lists with Packages**:
|
|
```nix
|
|
with pkgs;
|
|
[
|
|
age
|
|
alejandra
|
|
ast-grep
|
|
]
|
|
```
|
|
Use `with pkgs;` for package lists, one item per line.
|
|
|
|
**Modules**:
|
|
```nix
|
|
{
|
|
config,
|
|
lib,
|
|
pkgs,
|
|
...
|
|
}:
|
|
with lib; let
|
|
cfg = config.my.feature;
|
|
in {
|
|
options.my.feature = {
|
|
enable = mkEnableOption "Feature description";
|
|
};
|
|
config = mkIf cfg.enable {
|
|
# configuration
|
|
};
|
|
}
|
|
```
|
|
- Destructure args on separate lines
|
|
- Use `with lib;` for brevity with NixOS lib functions
|
|
- Define `cfg` for config options
|
|
- Use `mkIf`, `mkForce`, `mkDefault` appropriately
|
|
|
|
**Conditional Platform-Specific Code**:
|
|
```nix
|
|
++ lib.optionals stdenv.isDarwin [
|
|
_1password-gui
|
|
dockutil
|
|
]
|
|
++ lib.optionals stdenv.isLinux [
|
|
lm_sensors
|
|
]
|
|
```
|
|
|
|
### Naming Conventions
|
|
- **Option names**: `my.<feature>.<option>` for custom modules
|
|
- **Hostnames**: Lowercase, descriptive (e.g., `michael`, `tahani`)
|
|
- **Profile files**: Descriptive, lowercase with hyphens (e.g., `homebrew.nix`)
|
|
|
|
### Secrets Management
|
|
- Use SOPS for secrets (see `.sops.yaml`)
|
|
- Never commit unencrypted secrets
|
|
- Secrets files in `hosts/<host>/secrets.nix` import SOPS-generated files
|
|
|
|
### Imports Pattern
|
|
Host configs import:
|
|
1. System modules (`modulesPath + "/..."`)
|
|
2. Host-specific files (`./disk-config.nix`, `./hardware-configuration.nix`)
|
|
3. SOPS secrets (`./secrets.nix`)
|
|
4. Custom modules (`../../modules/*.nix`)
|
|
5. Base profiles (`../../profiles/*.nix`)
|
|
6. Input modules (`inputs.<module>.xxxModules.module`)
|
|
|
|
Home-manager users import profiles in a similar manner.
|