feat: Added home manager module

HOME-MANAGER.md

@@ -0,0 +1,228 @@
+# Home Manager Module for Hyprmonitors
+
+This directory contains a Home Manager module for installing and configuring hyprmonitors, a Rust web server that provides an HTTP API for controlling Hyprland desktop monitors.
+
+## What is Hyprmonitors?
+
+Hyprmonitors is a lightweight web server that exposes a RESTful API to control your Hyprland monitors using `hyprctl dispatch dpms` commands. It allows you to:
+
+- Turn all monitors on/off via HTTP requests
+- Control individual monitors by name
+- Get current monitor status
+- Integrate monitor control into web applications or scripts
+
+## Installation
+
+### Method 1: Direct Import
+
+Add the module to your Home Manager configuration:
+
+```nix
+{
+  imports = [
+    /path/to/hyprmonitors/home-manager-module.nix
+  ];
+
+  # Enable Hyprland (required)
+  wayland.windowManager.hyprland.enable = true;
+
+  # Enable hyprmonitors service
+  services.hyprmonitors.enable = true;
+}
+```
+
+### Method 2: As a Flake Input
+
+Add hyprmonitors as a flake input in your `flake.nix`:
+
+```nix
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    home-manager.url = "github:nix-community/home-manager";
+    hyprmonitors.url = "path:/path/to/hyprmonitors";
+  };
+
+  outputs = { nixpkgs, home-manager, hyprmonitors, ... }: {
+    homeConfigurations.youruser = home-manager.lib.homeManagerConfiguration {
+      modules = [
+        hyprmonitors.homeManagerModules.default
+        {
+          wayland.windowManager.hyprland.enable = true;
+          services.hyprmonitors.enable = true;
+        }
+      ];
+    };
+  };
+}
+```
+
+## Configuration Options
+
+The module provides several configuration options:
+
+```nix
+services.hyprmonitors = {
+  enable = true;                    # Enable the service
+  
+  host = "127.0.0.1";              # Host to bind to (default: 127.0.0.1)
+  port = 3000;                     # Port to bind to (default: 3000)
+  
+  logLevel = "info";               # Log level: error, warn, info, debug, trace
+  
+  package = pkgs.hyprmonitors;     # Override the package (optional)
+  
+  environmentVariables = {         # Additional environment variables
+    HYPRLAND_INSTANCE_SIGNATURE = "your-signature";
+  };
+  
+  settings = {                     # Future configuration options
+    timeout_seconds = 30;
+  };
+};
+```
+
+## Usage
+
+Once installed and configured, the module provides several convenient tools:
+
+### Shell Aliases
+
+The module automatically adds these shell aliases:
+
+- `hyprmonitors-start` - Start the service
+- `hyprmonitors-stop` - Stop the service  
+- `hyprmonitors-restart` - Restart the service
+- `hyprmonitors-status` - Check service status
+- `hyprmonitors-logs` - View service logs
+- `hyprmonitors-test` - Test if the API is responding
+
+### API Helper Script
+
+The `hyprmonitors-curl` script provides easy access to the API:
+
+```bash
+# Check if the service is running
+hyprmonitors-curl health
+
+# Get status of all monitors
+hyprmonitors-curl status
+
+# Turn all monitors on/off
+hyprmonitors-curl on
+hyprmonitors-curl off
+
+# Control specific monitors
+hyprmonitors-curl on DP-1
+hyprmonitors-curl off HDMI-A-1
+```
+
+### Manual API Access
+
+You can also use curl directly:
+
+```bash
+# Health check
+curl http://localhost:3000/health
+
+# Monitor status
+curl http://localhost:3000/monitors/status
+
+# Turn all monitors on/off
+curl -X POST http://localhost:3000/monitors/on
+curl -X POST http://localhost:3000/monitors/off
+
+# Control specific monitors
+curl -X POST http://localhost:3000/monitors/DP-1/on
+curl -X POST http://localhost:3000/monitors/HDMI-A-1/off
+```
+
+## Service Management
+
+The service is automatically managed by systemd:
+
+```bash
+# Check service status
+systemctl --user status hyprmonitors.service
+
+# View logs
+journalctl --user -u hyprmonitors.service -f
+
+# Manual start/stop (if needed)
+systemctl --user start hyprmonitors.service
+systemctl --user stop hyprmonitors.service
+```
+
+## Integration with Hyprland
+
+You can integrate hyprmonitors with Hyprland keybinds:
+
+```nix
+wayland.windowManager.hyprland.settings = {
+  bind = [
+    # Turn all monitors off/on
+    "SUPER SHIFT, M, exec, hyprmonitors-curl off"
+    "SUPER CTRL, M, exec, hyprmonitors-curl on"
+    
+    # Control specific monitors
+    "SUPER SHIFT, 1, exec, hyprmonitors-curl off DP-1"
+    "SUPER SHIFT, 2, exec, hyprmonitors-curl off HDMI-A-1"
+    "SUPER CTRL, 1, exec, hyprmonitors-curl on DP-1"
+    "SUPER CTRL, 2, exec, hyprmonitors-curl on HDMI-A-1"
+  ];
+};
+```
+
+## Desktop Entry
+
+The module creates a desktop entry "Hyprmonitors Control" that opens the health endpoint in your browser for quick access to verify the service is running.
+
+## Finding Monitor Names
+
+To find your monitor names for use with the API:
+
+```bash
+hyprctl monitors
+```
+
+Common monitor names include:
+- `DP-1`, `DP-2` (DisplayPort)
+- `HDMI-A-1`, `HDMI-A-2` (HDMI)
+- `eDP-1` (Laptop screen)
+
+## Troubleshooting
+
+### Service won't start
+
+1. Ensure Hyprland is running and properly configured
+2. Check that the port isn't already in use
+3. View logs: `journalctl --user -u hyprmonitors.service`
+
+### API requests fail
+
+1. Verify the service is running: `hyprmonitors-test`
+2. Check monitor names: `hyprctl monitors`
+3. Ensure you're running commands in a Hyprland session
+
+### Permission issues
+
+The service runs as your user and should automatically have access to Hyprland's IPC socket. If you encounter permission issues, ensure:
+
+1. You're running the service as the same user running Hyprland
+2. The `XDG_RUNTIME_DIR` environment variable is properly set
+
+## Security Considerations
+
+- The service binds to localhost by default for security
+- If you need remote access, change the host to `0.0.0.0` but ensure proper firewall configuration
+- The service has restricted permissions and resource limits applied
+
+## Complete Example
+
+See `example-home-manager-config.nix` for a complete working example configuration.
+
+## Requirements
+
+- NixOS or Nix with Home Manager
+- Hyprland window manager
+- The module automatically handles all dependencies