docs: expand AGENTS.md with comprehensive patterns and add HM module docs
This commit is contained in:
m3tm3re
207
AGENTS.md
207
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 .#<package>` - 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/<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**: 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`
|
||||
|
||||
74
modules/home-manager/AGENTS.md
Normal file
74
modules/home-manager/AGENTS.md
Normal file
@@ -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/<name>.nix`, import in `cli/default.nix` |
|
||||
| Add coding module | `coding/<name>.nix`, import in `coding/default.nix` |
|
||||
| Add new category | Create `<category>/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 |
|
||||
Reference in New Issue
Block a user