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:

{
  lib,
  stdenv,
  fetchFromGitHub,
}:

Modules: Standard pattern:

{ 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:

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

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:

   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