nixpkgs/AGENTS.md

# m3ta-nixpkgs Knowledge Base

**Generated:** 2025-12-30
**Commit:** c5e1610
**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` |

## CONVENTIONS

**Formatter**: `nix fmt` before commit (alejandra)

**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**: `rustPlatform.buildRustPackage rec { cargoLock.lockFile = src + "/Cargo.lock"; }`

**Shell**: `writeShellScriptBin "name" ''script''` or `mkDerivation` with custom `installPhase`

**AppImage**: `appimageTools.wrapType2 { ... }`

**Custom fetcher**: `fetchFromGitea { domain = "code.m3ta.dev"; owner = "m3tam3re"; ... }`

## MODULE PATTERNS

**Simple**: `options.cli.name = { enable = mkEnableOption "..."; }; config = mkIf cfg.enable { ... };`

**Multiple**: `config = mkMerge [ (mkIf cfg.x.enable { ... }) (mkIf cfg.y.enable { ... }) ];`

**Shared lib**: `portsLib = import ../../lib/ports.nix { inherit lib; }; portHelpers = portsLib.mkPortHelpers { ... };`

## PORT MANAGEMENT

Central port management: `config.m3ta.ports.get "service"` with host-specific via `hostOverrides`

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

## COMMANDS

```bash
nix flake check              # Validate flake
nix fmt                      # Format (alejandra)
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
```

## 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`

## NOTES

- **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`

## Landing the Plane (Session Completion)

**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.

**MANDATORY WORKFLOW:**

1. **File issues for remaining work** - Create issues for anything that needs follow-up
2. **Run quality gates** (if code changed) - Tests, linters, builds
3. **Update issue status** - Close finished work, update in-progress items
4. **PUSH TO REMOTE** - This is MANDATORY:
   ```bash
   git pull --rebase
   bd sync
   git push
   git status  # MUST show "up to date with origin"
   ```
5. **Clean up** - Clear stashes, prune remote branches
6. **Verify** - All changes committed AND pushed
7. **Hand off** - Provide context for next session

**CRITICAL RULES:**
- Work is NOT complete until `git push` succeeds
- NEVER stop before pushing - that leaves work stranded locally
- NEVER say "ready to push when you are" - YOU must push
- If push fails, resolve and retry until it succeeds