<!-- Copyright (C) 2026 Stefy Lanza <stefy@nexlab.net> -->
<!-- SPDX-License-Identifier: GPL-3.0-or-later -->
<!-- Copyleft: GNU GPLv3 or later applies to this file. -->

# Hermes Node Protocol
# Copyright (c) 2026 Stefy (nextime) Lanza <stefy@nexlab.net>
# All rights reserved.
# 
# This software is released under the MIT License with a copyleft clause.
# See the LICENSE file for full terms.
# Hermes Node Agent — Windows Package Build Instructions

This directory contains the Windows-specific components for building a professional installer.

## Components

```
windows/
├── agent-manager.py          # System tray GUI application
├── installer.iss             # Inno Setup installer script
├── build.py                  # Automated build script
├── nssm.exe                  # Service wrapper (download separately)
├── icon.ico                  # Application icon (optional)
├── dist/                     # PyInstaller output (generated)
│   ├── hermes-node-agent.exe
│   └── hermes-node-manager.exe
├── build/                    # PyInstaller temp files (generated)
└── Output/                   # Inno Setup output (generated)
    └── hermes-node-agent-installer.exe
```

## Prerequisites

### Required Software

1. **Python 3.9+** with pip
   - Download: https://www.python.org/downloads/
   - Ensure "Add Python to PATH" is checked during install

2. **PyInstaller** (for creating .exe files)
   ```cmd
   pip install pyinstaller
   ```

3. **Inno Setup 6** (for creating installer)
   - Download: https://jrsoftware.org/isdl.php
   - Install to default location: `C:\Program Files (x86)\Inno Setup 6\`

4. **NSSM** (Non-Sucking Service Manager)
   - Download: https://nssm.cc/download
   - Extract `nssm.exe` (64-bit version) to this `windows/` directory

### Python Dependencies

```cmd
pip install websockets pystray pillow wxpython win10toast pyinstaller
```

## Building the Installer

### Automated Build (Recommended)

Run the build script from the project root:

```cmd
cd hermes-node-protocol
python windows\build.py
```

This will:
1. Clean previous builds
2. Install Python dependencies
3. Build `hermes-node-agent.exe` with PyInstaller
4. Build `hermes-node-manager.exe` with PyInstaller
5. Verify NSSM is present
6. Compile the installer with Inno Setup

**Output:** `windows\Output\hermes-node-agent-installer.exe`

### Manual Build

If the automated script fails, build manually:

#### Step 1: Build Agent Executable

```cmd
cd hermes-node-protocol
pyinstaller --onefile --name hermes-node-agent --console node-agent\hermes_node_agent.py
```

Output: `dist\hermes-node-agent.exe`

#### Step 2: Build Manager GUI Executable

```cmd
pyinstaller --onefile --name hermes-node-manager --windowed windows\agent-manager.py
```

Output: `dist\hermes-node-manager.exe`

#### Step 3: Move Executables

```cmd
move dist\hermes-node-agent.exe windows\dist\
move dist\hermes-node-manager.exe windows\dist\
```

#### Step 4: Compile Installer

```cmd
"C:\Program Files (x86)\Inno Setup 6\ISCC.exe" windows\installer.iss
```

Output: `windows\Output\hermes-node-agent-installer.exe`

## Testing the Installer

### Test on Clean VM

1. Create a Windows 10/11 VM (VirtualBox, Hyper-V, VMware)
2. **Do not** install Python or any dependencies
3. Copy `hermes-node-agent-installer.exe` to the VM
4. Run the installer as Administrator
5. Verify:
   - Service installs: `sc query HermesNodeAgent`
   - Manager starts: Check system tray for "H" icon
   - Config editor opens: Right-click tray → Configuration
   - Logs viewer works: Right-click tray → Logs

### Test Service Management

```cmd
REM Start service
sc start HermesNodeAgent

REM Check status
sc query HermesNodeAgent

REM Stop service
sc stop HermesNodeAgent
```

### Test Uninstaller

1. Open **Settings** → **Apps** → **Apps & features**
2. Find **Hermes Node Agent**
3. Click **Uninstall**
4. Verify all files removed except config/logs

## Customization

### Change Application Icon

1. Create or download a `.ico` file (16x16, 32x32, 48x48, 256x256)
2. Save as `windows\icon.ico`
3. Rebuild with `python windows\build.py`

### Modify Installer Appearance

Edit `windows\installer.iss`:

- **App name/version**: `[Setup]` section
- **Install location**: `DefaultDirName`
- **Start menu group**: `DefaultGroupName`
- **License agreement**: Add `LicenseFile=LICENSE.txt` to `[Setup]`
- **Wizard images**: Add `WizardImageFile` and `WizardSmallImageFile`

### Add Custom Files

Edit `windows\installer.iss` → `[Files]` section:

```iss
Source: "path\to\file.txt"; DestDir: "{app}"; Flags: ignoreversion
```

## Troubleshooting

### PyInstaller: "Module not found"

Install missing module:
```cmd
pip install <module-name>
```

Then rebuild.

### PyInstaller: "Failed to execute script"

Run the .exe from command line to see error:
```cmd
cd windows\dist
hermes-node-agent.exe --config test.json
```

### Inno Setup: "Cannot find file"

Verify all `Source:` paths in `installer.iss` exist:
- `windows\nssm.exe`
- `windows\dist\hermes-node-agent.exe`
- `windows\dist\hermes-node-manager.exe`
- `node-agent\hermes_node_agent.py`

### Manager GUI: "wxPython not found"

```cmd
pip install wxpython
```

Note: wxPython can take 5-10 minutes to install (large package).

### Service won't start after install

Check Event Viewer:
1. Press `Win+R`, type `eventvwr.msc`, press Enter
2. Navigate to **Windows Logs** → **Application**
3. Look for errors from source "HermesNodeAgent"

Common causes:
- Config file missing or invalid JSON
- Python runtime not bundled correctly (use PyInstaller `--onefile`)
- Missing DLL dependencies (use `--hidden-import` in PyInstaller)

## Distribution

### Signing the Installer (Optional but Recommended)

Sign with a code signing certificate to avoid Windows SmartScreen warnings:

```cmd
signtool sign /f certificate.pfx /p password /t http://timestamp.digicert.com windows\Output\hermes-node-agent-installer.exe
```

### Creating a Portable Version

To create a portable (no-install) version:

1. Copy `windows\dist\hermes-node-agent.exe` to a folder
2. Copy `windows\dist\hermes-node-manager.exe` to the same folder
3. Create `config.json` in the same folder
4. Zip the folder

Users can run `hermes-node-agent.exe --config config.json` directly (no service).

## File Sizes (Approximate)

- `hermes-node-agent.exe`: ~15 MB (includes Python runtime)
- `hermes-node-manager.exe`: ~25 MB (includes wxPython)
- `hermes-node-agent-installer.exe`: ~45 MB (compressed)

## Build Environment

Tested on:
- Windows 10 21H2 (x64)
- Windows 11 22H2 (x64)
- Python 3.9.13, 3.10.11, 3.11.4
- PyInstaller 5.13.0
- Inno Setup 6.2.2

## Support

For build issues:
- Check PyInstaller docs: https://pyinstaller.org/
- Check Inno Setup docs: https://jrsoftware.org/ishelp/
- Review `windows\build.py` for detailed steps
