From c5e161026dfe69ddc6542b638a47fe449b06f09d Mon Sep 17 00:00:00 2001 From: m3tm3re Date: Mon, 29 Dec 2025 19:01:37 +0100 Subject: [PATCH] docs: expand AGENTS.md with comprehensive patterns and add HM module docs --- AGENTS.md | 207 +++++++++++++++++++++++++++++---- modules/home-manager/AGENTS.md | 74 ++++++++++++ 2 files changed, 261 insertions(+), 20 deletions(-) create mode 100644 modules/home-manager/AGENTS.md diff --git a/AGENTS.md b/AGENTS.md index 67670b6..6002b46 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,26 +1,193 @@ -# Agent Guidelines for m3ta-nixpkgs +# m3ta-nixpkgs Knowledge Base -## Build/Lint/Test Commands -- `nix flake check` - Validate flake and run checks -- `nix fmt` - Format all Nix files (uses nixpkgs-fmt) -- `nix build .#` - Build a specific package -- `nix flake show` - List all available outputs -- `statix check .` - Lint Nix files (run in `nix develop` shell) -- `deadnix .` - Find dead/unused Nix code (run in `nix develop` shell) +**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//default.nix` | Register in `pkgs/default.nix` | +| Add NixOS module | `modules/nixos/.nix` | Import in `modules/nixos/default.nix` | +| Add HM module | `modules/home-manager//` | Category: cli, coding, or root | +| Override nixpkgs pkg | `overlays/mods/.nix` | Import in `overlays/mods/default.nix` | +| Add dev shell | `shells/.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 .# # 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**: Always run `nix fmt` before committing -- **Naming**: Package names use lowercase-hyphen (`my-package`), variables use camelCase -- **Imports**: Multi-line with trailing commas: `{ lib, stdenv, fetchFromGitHub, }:` -- **Modules**: Use `with lib; let cfg = config.namespace.module; in { ... }` pattern -- **Options**: Use `mkEnableOption` for enable flags, namespace under `m3ta.*` -- **Meta**: Always include description, homepage, license, platforms, mainProgram -- **Comments**: Explain "why" not "what"; document non-obvious logic -## File Organization -- One package per directory under `pkgs/`, entry point is `default.nix` -- Register packages in `pkgs/default.nix` using `callPackage` -- Modules go in `modules/nixos/` or `modules/home-manager/` by category +**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` where type is: feat, fix, docs, style, refactor, chore + +``` +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` diff --git a/modules/home-manager/AGENTS.md b/modules/home-manager/AGENTS.md new file mode 100644 index 0000000..c08b63c --- /dev/null +++ b/modules/home-manager/AGENTS.md @@ -0,0 +1,74 @@ +# Home Manager Modules + +User-level configuration modules organized by functional category. + +## Structure + +``` +home-manager/ +├── default.nix # Aggregator: imports all categories + ports.nix +├── ports.nix # Port management (HM-specific: generateEnvVars) +├── cli/ # Terminal/CLI tools +│ ├── default.nix # Category aggregator +│ └── zellij-ps.nix +└── coding/ # Development tools + ├── default.nix # Category aggregator + └── editors.nix # Neovim + Zed configs +``` + +## Where to Look + +| Task | Location | +|------|----------| +| Add CLI module | `cli/.nix`, import in `cli/default.nix` | +| Add coding module | `coding/.nix`, import in `coding/default.nix` | +| Add new category | Create `/default.nix`, import in root `default.nix` | +| Module with host ports | Import `../../lib/ports.nix`, use `mkPortHelpers` | + +## Option Namespaces + +- `cli.*` - CLI tools (e.g., `cli.zellij-ps.enable`) +- `coding.editors.*` - Editor configs (e.g., `coding.editors.neovim.enable`) +- `m3ta.ports.*` - Port management (shared with NixOS) + +## Patterns + +**Category aggregator** (`cli/default.nix`): +```nix +{ + imports = [ + ./zellij-ps.nix + # Add new modules here + ]; +} +``` + +**Simple module** (zellij-ps): +```nix +options.cli.zellij-ps = { + enable = mkEnableOption "..."; + projectFolders = mkOption { type = types.listOf types.path; ... }; +}; +config = mkIf cfg.enable { + home.packages = [ pkgs.zellij-ps ]; + home.sessionVariables.PROJECT_FOLDERS = ...; +}; +``` + +**Multi-config module** (editors.nix): +```nix +config = mkMerge [ + (mkIf cfg.neovim.enable { programs.neovim = {...}; }) + (mkIf cfg.zed.enable { programs.zed-editor = {...}; }) + (mkIf (cfg.neovim.enable || cfg.zed.enable) { home.packages = [...]; }) +]; +``` + +## HM vs NixOS Differences + +| Feature | Home Manager | NixOS | +|---------|--------------|-------| +| `currentHost` default | `null` (must set) | `config.networking.hostName` | +| `generateEnvVars` | Available | Not available | +| Output file | `~/.config/m3ta/ports.json` | `/etc/m3ta/ports.json` | +| Package access | `pkgs.*` via overlay | `pkgs.*` via overlay |