feat: add rules and guidelines for Cloonar Assistant LLM

.roo/rules/rules.md

@@ -0,0 +1,157 @@
+# Cloonar Assistant LLM Rules
+
+This document defines the rules and guidelines for an LLM working with the Cloonar Assistant NixOS module project.
+
+## 1. Project Understanding
+
+### 1.1 Core Components
+- Network Infrastructure (VLANs, DHCP, DNS, Firewall)
+- Security Services (WireGuard VPN, SSL/ACME)
+- Home Automation (Home Assistant)
+- System Services (Dynamic DNS, Container Management)
+- Development Tools (ISO Builder, VM Testing)
+
+### 1.2 Module Architecture
+```mermaid
+graph TD
+    A[Cloonar Assistant] --> B[Network Management]
+    A --> C[Security]
+    A --> D[Services]
+    A --> E[Development Tools]
+
+    B --> B1[VLANs]
+    B --> B2[DHCP/Kea]
+    B --> B3[DNS/Unbound]
+    B --> B4[Firewall/nftables]
+
+    C --> C1[WireGuard VPN]
+    C --> C2[SSL/ACME]
+    C --> C3[SOPS Integration]
+
+    D --> D1[Home Assistant]
+    D --> D2[Dynamic DNS]
+    D --> D3[Container Services]
+
+    E --> E1[ISO Builder]
+    E --> E2[VM Testing]
+```
+
+## 2. NixOS Integration (REQUIRED)
+
+### 2.1 Package and Option Verification
+- ALWAYS use the NixOS MCP server to verify packages and options before suggesting them
+- Query format: `use_mcp_tool` with server "nixos" for all NixOS-related lookups
+- Verify package availability in the project's current NixOS version
+- Validate option compatibility and deprecation status
+
+### 2.2 Configuration Guidelines
+- All NixOS configurations must be validated through MCP before suggestion
+- Use proper module imports and option declarations
+- Follow NixOS naming conventions and type declarations
+- Consider module dependencies and conflicts
+
+## 3. Development Guidelines
+
+### 3.1 Code Structure
+- Maintain modular organization in `modules/cloonar-assistant/`
+- Follow existing patterns for option declarations
+- Use descriptive names for options and properties
+- Keep related functionality grouped in appropriate submodules
+
+### 3.2 Testing Protocol
+- Utilize the VM testing scripts in `scripts/`
+- Test configuration changes with `test-configuration`
+- Verify VLAN and network functionality in VM environment
+- Ensure proper service container operation
+
+## 4. Configuration Support
+
+### 4.1 Network Configuration
+- Define appropriate VLANs based on network requirements
+- Configure firewall rules using nftables syntax
+- Set up proper DHCP and DNS services
+- Implement correct routing between VLANs
+
+### 4.2 Service Configuration
+- Configure Home Assistant container with proper isolation
+- Set up SSL certificates via ACME
+- Manage WireGuard VPN peers and configurations
+- Configure dynamic DNS updates
+
+## 5. Security Best Practices
+
+### 5.1 General Security
+- Never expose sensitive information in configurations
+- Use SOPS for secrets management
+- Implement proper network segmentation
+- Follow principle of least privilege
+
+### 5.2 Network Security
+- Verify firewall rule correctness
+- Implement proper VLAN isolation
+- Secure VPN configurations
+- Validate SSL certificate management
+
+## 6. Troubleshooting Framework
+
+### 6.1 Diagnostic Approach
+```mermaid
+flowchart LR
+    A[Issue Reported] --> B{Category?}
+    B --> C[Network]
+    B --> D[Service]
+    B --> E[Build]
+    
+    C --> C1[Check VLANs]
+    C --> C2[Verify Firewall]
+    C --> C3[Test DNS]
+    
+    D --> D1[Container Status]
+    D --> D2[Service Logs]
+    D --> D3[Dependencies]
+    
+    E --> E1[Nix Errors]
+    E --> E2[Option Issues]
+    E --> E3[Build Logs]
+```
+
+### 6.2 Common Issues
+- VLAN connectivity problems
+- Container networking issues
+- SSL certificate renewal failures
+- Build and configuration errors
+
+## 7. Self-Maintenance Rules
+
+### 7.1 Rule Update Triggers
+Monitor and update rules.md when:
+- Major NixOS version changes affect module functionality
+- New security considerations emerge
+- Core module features are added/modified
+- Breaking changes in dependencies occur
+
+### 7.2 Update Protocol
+1. Identify breaking changes or important updates
+2. Document impact on existing configurations
+3. Update relevant rule sections
+4. Add new guidelines if needed
+5. Update version compatibility information
+
+### 7.3 Documentation Sync
+- Keep rules aligned with current codebase
+- Update mermaid diagrams for architectural changes
+- Maintain accurate NixOS version compatibility info
+- Document new features and deprecations
+
+### 7.4 Change Validation
+Before updating rules:
+- Verify changes against current codebase
+- Test impact on existing configurations
+- Check NixOS MCP for option/package changes
+- Validate security implications
+
+## 8. Version Information
+
+- Last Updated: 2025-06-06
+- Compatible NixOS Versions: 23.05, 23.11, 24.05
+- Project Version: Current Master

scripts/run-vm

@@ -2,12 +2,11 @@
 set -Euo pipefail
 
 # -----------------------------------------------------------------------------
-# This script sets up and launches a QEMU virtual machine with OVMF (UEFI).
+# This script sets up and launches (or stops) a QEMU virtual machine with OVMF.
-# It checks for the necessary files, creates directories/images as needed,
+#
-# and provides clear, user-friendly output along the way.
 # Usage:
-#   ./run-vm.sh [install]
+#   ./run-vm.sh [install]     # starts (and backgrounds) the VM; use "install" to attach the ISO
-#   - Pass "install" to attach the ISO as a CD-ROM for installation.
+#   ./run-vm.sh stop          # kills the running QEMU VM (reads PID from .vm/qemu.pid)
 # -----------------------------------------------------------------------------
 
 # Paths to OVMF firmware (pflash)
@@ -17,9 +16,33 @@ OVMF_VARS_DEFAULT="/run/libvirt/nix-ovmf/OVMF_VARS.fd"
 # Determine where this script lives and compute related paths
 SCRIPT_DIR=$(dirname "$(readlink -f "$0")")
 TARGET_DIR=$(readlink -f "$SCRIPT_DIR/../.vm")
-OVMF_VARS_PATH=$(readlink -f "$SCRIPT_DIR/../.vm/OVMF_VARS-myvm.fd")
+OVMF_VARS_PATH="$TARGET_DIR/OVMF_VARS-myvm.fd"
-IMG_PATH=$(readlink -f "$SCRIPT_DIR/../.vm/disk.img")
+IMG_PATH="$TARGET_DIR/disk.img"
 ISO_DIR=$(readlink -f "$SCRIPT_DIR/../iso/result/iso")
+PID_FILE="$TARGET_DIR/qemu.pid"
+
+# If first argument is "stop", then kill the running VM and exit:
+if [ "${1-}" = "stop" ]; then
+  if [ -f "$PID_FILE" ]; then
+    VM_PID=$(<"$PID_FILE")
+    if kill -0 "$VM_PID" 2>/dev/null; then
+      echo "Killing QEMU (PID $VM_PID)..."
+      kill "$VM_PID"
+      # Optionally wait for it to die:
+      wait "$VM_PID" 2>/dev/null || true
+      echo "✅ VM stopped."
+      rm -f "$PID_FILE"
+      exit 0
+    else
+      echo "⚠️  No running QEMU process with PID $VM_PID. Removing stale PID file."
+      rm -f "$PID_FILE"
+      exit 1
+    fi
+  else
+    echo "⚠️  No PID file found at $PID_FILE. Is the VM running?"
+    exit 1
+  fi
+fi
 
 echo
 echo "============================================================"
@@ -92,7 +115,8 @@ fi
 
 if [ "$INSTALL_MODE" -eq 1 ]; then
   echo "[5/6] Install mode enabled: CD-ROM will be attached"
-  CDROM_OPTS="-drive file=\"$ISO_FILE\",format=raw,if=none,media=cdrom,id=cd1,readonly=on -device ahci,id=ahci0 -device ide-cd,bus=ahci0.0,drive=cd1,bootindex=1"
+  CDROM_OPTS="-drive file=\"$ISO_FILE\",format=raw,if=none,media=cdrom,id=cd1,readonly=on \
+-device ahci,id=ahci0 -device ide-cd,bus=ahci0.0,drive=cd1,bootindex=1"
 else
   echo "[5/6] Normal boot mode: No CD-ROM attached"
   CDROM_OPTS=""
@@ -100,9 +124,9 @@ fi
 echo
 
 # -----------------------------------------------------------------------------
-# 6. Launch QEMU
+# 6. Launch QEMU (in the background)
 # -----------------------------------------------------------------------------
-echo "[6/6] Launching QEMU VM now..."
+echo "[6/6] Launching QEMU VM now (in background)..."
 echo "------------------------------------------------------------"
 echo "  • Machine: q35, KVM acceleration"
 echo "  • Memory: 4096 MB"
@@ -122,7 +146,7 @@ echo
 # Construct network options
 NET_OPTS="-netdev user,id=net0,hostfwd=tcp::2222-:22 -device e1000,netdev=net0"
 
-# Run QEMU using eval to allow variable expansion in CDROM_OPTS
+# Run QEMU in the background and store its PID
 eval qemu-system-x86_64 \
   -machine type=q35,accel=kvm \
   -m 4096 \
@@ -137,9 +161,14 @@ eval qemu-system-x86_64 \
   $CDROM_OPTS \
   \
   $NET_OPTS \
-  -vga virtio
+  -vga virtio \
+  &
 
+VM_PID=$!
+echo "$VM_PID" > "$PID_FILE"
+echo "✅ QEMU started with PID $VM_PID. PID file: $PID_FILE"
 echo
-echo "============================================================"
+echo "To stop the VM at any time, run:"
-echo "                 QEMU VM has exited"
+echo "    $0 stop"
-echo "============================================================"
+echo
+exit 0