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

Issue Tracking

This project uses bd (beads) for issue tracking. Run bd prime for workflow context, or install hooks (bd hooks install) for auto-injection.

Quick reference:

• bd ready - Find unblocked work
• bd create "Title" --type task --priority 2 - Create issue
• bd close <id> - Complete work
• bd sync - Sync with git (run at session end)

For full workflow details: bd prime