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
|
**Generated:** 2025-12-29
|
||||||
- `nix flake check` - Validate flake and run checks
|
**Commit:** 9092e6d
|
||||||
- `nix fmt` - Format all Nix files (uses nixpkgs-fmt)
|
**Branch:** master
|
||||||
- `nix build .#<package>` - Build a specific package
|
|
||||||
- `nix flake show` - List all available outputs
|
## Overview
|
||||||
- `statix check .` - Lint Nix files (run in `nix develop` shell)
|
|
||||||
- `deadnix .` - Find dead/unused Nix code (run in `nix develop` shell)
|
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
|
## 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
|
**Formatter**: `nix fmt` before commit (nixpkgs-fmt)
|
||||||
- One package per directory under `pkgs/`, entry point is `default.nix`
|
|
||||||
- Register packages in `pkgs/default.nix` using `callPackage`
|
**Naming**:
|
||||||
- Modules go in `modules/nixos/` or `modules/home-manager/` by category
|
- 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
|
## 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