nixpkgs/AGENTS.md

# m3ta-nixpkgs Knowledge Base

**Generated:** 2025-12-29
**Commit:** 9092e6d
**Branch:** master

## Overview

Personal Nix flake: custom packages, overlays, NixOS/Home Manager modules, dev shells. Flakes-only (no channels).

## Structure

```
.
├── flake.nix              # Entry: packages, overlays, modules, shells, lib
├── pkgs/                  # Custom packages (one dir each, callPackage registry)
├── modules/
│   ├── nixos/             # System modules (ports.nix)
│   └── home-manager/      # User modules by category (cli/, coding/, ports.nix)
├── lib/                   # Shared utilities (ports.nix)
├── shells/                # Dev environments (default, python, devops)
├── overlays/mods/         # Package modifications (n8n version bump)
├── templates/             # Boilerplate for new packages/modules
└── examples/              # Usage examples
```

## Where to Look

| Task | Location | Notes |
|------|----------|-------|
| Add package | `pkgs/<name>/default.nix` | Register in `pkgs/default.nix` |
| Add NixOS module | `modules/nixos/<name>.nix` | Import in `modules/nixos/default.nix` |
| Add HM module | `modules/home-manager/<category>/` | Category: cli, coding, or root |
| Override nixpkgs pkg | `overlays/mods/<name>.nix` | Import in `overlays/mods/default.nix` |
| Add dev shell | `shells/<name>.nix` | Register in `shells/default.nix` |
| Use port management | `config.m3ta.ports.get "service"` | Host-specific via `hostOverrides` |

## Commands

```bash
nix flake check              # Validate flake
nix fmt                      # Format (nixpkgs-fmt)
nix build .#<pkg>            # Build package
nix flake show               # List outputs
nix develop                  # Enter dev shell
nix develop .#python         # Python shell
nix develop .#devops         # DevOps shell

# In dev shell only:
statix check .               # Lint
deadnix .                    # Find dead code
```

## Code Style

**Formatter**: `nix fmt` before commit (nixpkgs-fmt)

**Naming**:
- Packages: `lowercase-hyphen` (e.g., `hyprpaper-random`)
- Variables: `camelCase` (e.g., `portHelpers`)
- Module options: `m3ta.*` namespace

**Imports**: Multi-line, trailing commas:
```nix
{
  lib,
  stdenv,
  fetchFromGitHub,
}:
```

**Modules**: Standard pattern:
```nix
{ config, lib, pkgs, ... }:
with lib; let
  cfg = config.m3ta.myModule;
in {
  options.m3ta.myModule = {
    enable = mkEnableOption "description";
  };
  config = mkIf cfg.enable { ... };
}
```

**Meta**: Always include all fields:
```nix
meta = with lib; {
  description = "...";
  homepage = "...";
  license = licenses.mit;
  platforms = platforms.linux;
  mainProgram = "...";
};
```

## Package Patterns

**Rust** (code2prompt):
```nix
rustPlatform.buildRustPackage rec {
  cargoLock.lockFile = src + "/Cargo.lock";
}
```

**Shell scripts** (launch-webapp):
```nix
writeShellScriptBin "name" ''script''
# Or mkDerivation with custom installPhase
```

**AppImage** (msty-studio):
```nix
appimageTools.wrapType2 { ... }
```

**Custom fetcher** (zellij-ps):
```nix
fetchFromGitea {
  domain = "code.m3ta.dev";
  owner = "m3tam3re";
  ...
}
```

## Module Patterns

**Simple enable** (zellij-ps.nix):
```nix
options.cli.zellij-ps = {
  enable = mkEnableOption "...";
  someOption = mkOption { type = types.str; default = "..."; };
};
config = mkIf cfg.enable { home.packages = [...]; };
```

**Multiple conditionals** (editors.nix):
```nix
config = mkMerge [
  (mkIf cfg.neovim.enable { ... })
  (mkIf cfg.zed.enable { ... })
  (mkIf (cfg.neovim.enable || cfg.zed.enable) { ... })
];
```

**Shared library** (ports modules):
```nix
portsLib = import ../../lib/ports.nix { inherit lib; };
portHelpers = portsLib.mkPortHelpers { ports = cfg.definitions; ... };
```

## Port Management

Central port management with host-specific overrides:

```nix
m3ta.ports = {
  enable = true;
  definitions = { nginx = 80; grafana = 3000; };
  hostOverrides.laptop = { nginx = 8080; };
  currentHost = config.networking.hostName;  # NixOS auto
};

# Usage
services.nginx.port = config.m3ta.ports.get "nginx";
```

**Generated files**: `/etc/m3ta/ports.json` (NixOS), `~/.config/m3ta/ports.json` (HM)

## Anti-Patterns

| Don't | Do Instead |
|-------|------------|
| `lib.fakeHash` in commits | Get real hash: `nix build`, copy from error |
| Flat module files | Organize by category (`cli/`, `coding/`) |
| Hardcode ports | Use `m3ta.ports` module |
| Skip meta fields | Include all: description, homepage, license, platforms, mainProgram |
| `with pkgs;` in modules | Explicit `pkgs.package` or `with pkgs; [ ... ]` in lists only |

## Commit Format

```
type: brief description
```

Types: `feat`, `fix`, `docs`, `style`, `refactor`, `chore`

## Gotchas

- **Hash fetching**: Use `lib.fakeHash` initially, build to get real hash
- **HM modules**: Category subdirs (`cli/`, `coding/`) have own `default.nix` aggregators
- **Ports module**: Different for NixOS vs HM (HM adds `generateEnvVars` option)
- **Overlays**: `modifications` overlay uses `{prev}:` pattern, not `{final, prev}:`
- **Dev shell tools**: `statix`, `deadnix` only available inside `nix develop`