+lib +portshelper

README.md

@@ -8,6 +8,7 @@ My personal Nix repository containing custom packages, overlays, NixOS modules,
 - 🔄 **Overlays**: Package modifications and enhancements
 - ⚙️ **NixOS Modules**: System-level configuration modules
 - 🏠 **Home Manager Modules**: User-level configuration modules
+- 📚 **Library Functions**: Helper utilities for configuration management
 - ❄️ **Flakes Only**: Modern Nix flakes support (no channels)
 
 ## Repository Structure
@@ -35,6 +36,11 @@ m3ta-nixpkgs/
 │   └── home-manager/           # Home Manager modules
 │       ├── default.nix
 │       └── zellij-ps.nix
+├── lib/                         # Library functions
+│   ├── default.nix             # Library entry point
+│   └── ports.nix               # Port management utilities
+├── examples/                    # Usage examples
+│   └── ports-example.nix
 └── templates/                   # Templates for new packages/modules
 ```
 
@@ -233,6 +239,80 @@ homeManagerModules = {
 };
 ```
 
+### Using Library Functions
+
+The repository includes helper functions to simplify common configuration tasks.
+
+#### Port Management
+
+Centrally manage service ports across multiple hosts with automatic host-specific overrides:
+
+```nix
+# In your flake.nix or configuration
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    m3ta-nixpkgs.url = "git+https://code.m3ta.dev/m3tam3re/nixpkgs";
+  };
+
+  outputs = { self, nixpkgs, m3ta-nixpkgs, ... }: {
+    nixosConfigurations.laptop = nixpkgs.lib.nixosSystem {
+      system = "x86_64-linux";
+      specialArgs = { inherit inputs; system = "x86_64-linux"; };
+      modules = [
+        ({ inputs, system, config, ... }: let
+          # Import the library
+          m3taLib = inputs.m3ta-nixpkgs.lib.${system};
+
+          # Define all ports in one place
+          myPorts = {
+            ports = {
+              nginx = 80;
+              grafana = 3000;
+              prometheus = 9090;
+            };
+            hostPorts = {
+              laptop = {
+                nginx = 8080;  # Non-privileged port on laptop
+              };
+            };
+          };
+
+          # Create helper functions
+          ports = m3taLib.ports.mkPortHelpers myPorts;
+          hostname = config.networking.hostName;
+        in {
+          # Use in your configuration
+          services.nginx.defaultHTTPListenPort = ports.getPort "nginx" hostname;
+          services.grafana.settings.server.http_port = ports.getPort "grafana" hostname;
+
+          # Get all ports for current host
+          environment.etc."service-ports.json".text =
+            builtins.toJSON (ports.getHostPorts hostname);
+        })
+      ];
+    };
+  };
+}
+```
+
+**Benefits:**
+
+- Single source of truth for all port assignments
+- Automatic host-specific overrides (laptop, server, VM, etc.)
+- Works across both NixOS and Home Manager configurations
+- Easy to see and manage all ports in one place
+
+**Available Functions:**
+
+- `mkPortHelpers`: Create port helper functions from a configuration
+- `getPort`: Get port for a service with optional host override
+- `getHostPorts`: Get all ports for a specific host (merged defaults + overrides)
+- `getDefaultPort`: Get default port without host override
+- `listServices`: List all defined service names
+
+See `examples/ports-example.nix` for comprehensive usage examples.
+
 ## Available Packages
 
 | Package            | Description                           |