nixpkgs/README.md

# m3ta-nixpkgs

My personal Nix repository containing custom packages, overlays, NixOS modules, and Home Manager modules.

## Features

- 🎁 **Custom Packages**: Collection of personal Nix packages
- 🔄 **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

```
m3ta-nixpkgs/
├── flake.nix                    # Main flake configuration
├── pkgs/                        # Custom packages
│   ├── default.nix             # Package registry
│   ├── code2prompt/
│   ├── hyprpaper-random/
│   ├── launch-webapp/
│   ├── msty-studio/
│   ├── pomodoro-timer/
│   ├── tuxedo-backlight/
│   └── zellij-ps/
├── overlays/                    # Overlays
│   ├── default.nix
│   └── mods/                   # Package modifications
│       ├── default.nix
│       └── n8n.nix
├── modules/
│   ├── nixos/                  # NixOS modules
│   │   └── default.nix
│   └── 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
```

## Usage

### Adding to Your Flake

Add this repository to your flake inputs:

```nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    m3ta-nixpkgs.url = "git+https://code.m3ta.dev/m3tam3re/nixpkgs";
  };
}
```

### Using Packages in NixOS Configuration

#### Method 1: Using the Overlay

```nix
{
  nixpkgs.overlays = [
    inputs.m3ta-nixpkgs.overlays.default
  ];

  environment.systemPackages = with pkgs; [
    code2prompt
    hyprpaper-random
    msty-studio
    # ... any other custom packages
  ];
}
```

#### Method 2: Direct Package Reference

```nix
{
  environment.systemPackages = [
    inputs.m3ta-nixpkgs.packages.${system}.code2prompt
    inputs.m3ta-nixpkgs.packages.${system}.hyprpaper-random
  ];
}
```

### Using in Home Manager

#### With Overlay

```nix
{
  nixpkgs.overlays = [
    inputs.m3ta-nixpkgs.overlays.default
  ];

  home.packages = with pkgs; [
    zellij-ps
    pomodoro-timer
  ];
}
```

#### With Home Manager Modules

```nix
{
  imports = [
    inputs.m3ta-nixpkgs.homeManagerModules.default
    # Or specific modules:
    # inputs.m3ta-nixpkgs.homeManagerModules.zellij-ps
  ];

  # Module-specific configuration here
}
```

### Using NixOS Modules

```nix
{
  imports = [
    inputs.m3ta-nixpkgs.nixosModules.default
  ];

  # Your custom module options will be available here
}
```

### Building Packages Directly

```bash
# Build a specific package
nix build git+https://code.m3ta.dev/m3tam3re/nixpkgs#code2prompt

# Run a package without installing
nix run git+https://code.m3ta.dev/m3tam3re/nixpkgs#zellij-ps

# Install to your profile
nix profile install git+https://code.m3ta.dev/m3tam3re/nixpkgs#msty-studio

# List all available packages
nix flake show git+https://code.m3ta.dev/m3tam3re/nixpkgs
```

## Development

### Setting Up Development Environment

```bash
# Clone the repository
git clone https://code.m3ta.dev/m3tam3re/nixpkgs
cd m3ta-nixpkgs

# Enter development shell
nix develop

# Check flake validity
nix flake check

# Format code
nix fmt
```

### Adding a New Package

1. Create a new directory under `pkgs/`:

```bash
mkdir pkgs/my-package
```

2. Create `pkgs/my-package/default.nix`:

```nix
{
  lib,
  stdenv,
  fetchFromGitHub,
}:
stdenv.mkDerivation rec {
  pname = "my-package";
  version = "1.0.0";

  src = fetchFromGitHub {
    owner = "owner";
    repo = "repo";
    rev = "v${version}";
    hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
  };

  meta = with lib; {
    description = "Description of my package";
    homepage = "https://github.com/owner/repo";
    license = licenses.mit;
    maintainers = with maintainers; [ ];
    platforms = platforms.linux;
  };
}
```

3. Add to `pkgs/default.nix`:

```nix
{
  # ... existing packages ...
  my-package = pkgs.callPackage ./my-package {};
}
```

### Adding a New NixOS Module

1. Create `modules/nixos/my-module.nix`
2. Add import to `modules/nixos/default.nix`
3. Update `flake.nix` to expose it:

```nix
nixosModules = {
  default = ./modules/nixos;
  my-module = ./modules/nixos/my-module.nix;
};
```

### Adding a New Home Manager Module

1. Create `modules/home-manager/my-module.nix`
2. Add to `modules/home-manager/default.nix`
3. Update `flake.nix` to expose it:

```nix
homeManagerModules = {
  default = import ./modules/home-manager;
  my-module = import ./modules/home-manager/my-module.nix;
};
```

### 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                           |
| ------------------ | ------------------------------------- |
| `code2prompt`      | Convert code to prompts               |
| `hyprpaper-random` | Random wallpaper setter for Hyprpaper |
| `launch-webapp`    | Launch web applications               |
| `msty-studio`      | Msty Studio application               |
| `pomodoro-timer`   | Pomodoro timer utility                |
| `tuxedo-backlight` | Backlight control for Tuxedo laptops  |
| `zellij-ps`        | Process viewer for Zellij             |

## License

Individual packages may have their own licenses. Check each package's `meta.license` attribute.

## Maintainer

[@m3tam3re](https://github.com/m3tam3re)