Installer updates

Author: cdgriffith

.claude/skills/build-installer.md

@@ -0,0 +1,78 @@
+---
+description: Build the FastFlix installer, distribution, launcher, and uninstaller
+---
+
+# Building the FastFlix Installer & Distribution
+
+## Prerequisites
+
+- Go 1.22+ installed
+- `go-winres` installed: `go install github.com/tc-hib/go-winres@latest`
+- Python 3.13+ with `uv`
+- `zstandard` Python package: `uv run pip install zstandard`
+- Internet access (first build downloads embeddable Python)
+
+## Full Build (everything from scratch)
+
+```bash
+# 1. Build the full distribution + archive
+uv run python scripts/build_distribution.py --archive
+
+# 2. Generate icon/manifest resources for installer
+cd cmd/installer && go-winres make && cd ../..
+
+# 3. Build the installer (embeds the archive)
+go build -ldflags="-s -w -H windowsgui -X main.Version=$(python -c 'from fastflix.version import __version__; print(__version__)')" -o dist/FastFlix_installer.exe ./cmd/installer
+```
+
+The build script (`scripts/build_distribution.py --archive`) handles:
+- Downloading embeddable Python 3.13
+- Installing all dependencies via pip `--target`
+- Building the Go launcher (`FastFlix.exe`) and uninstaller (`uninstall.exe`)
+- Trimming unused PySide6 modules (~527 MB savings)
+- Creating `fastflix_dist.tar.zst` archive
+- Copying `licenses.txt` and generating `terms_translations.json`
+
+## Quick Rebuild (after code changes)
+
+### Launcher only
+```bash
+go build -ldflags="-s -w -X main.Version=6.3.0" -o dist/FastFlix/FastFlix.exe ./cmd/launcher
+```
+
+### Uninstaller only
+```bash
+go build -ldflags="-s -w -H windowsgui" -o dist/FastFlix/uninstall.exe ./cmd/uninstaller
+```
+
+### Installer only (requires archive already built)
+```bash
+go build -ldflags="-s -w -H windowsgui -X main.Version=6.3.0" -o dist/FastFlix_installer.exe ./cmd/installer
+```
+
+## Important Notes
+
+- **Launcher**: Built WITHOUT `-H windowsgui` (needs console for logs)
+- **Installer/Uninstaller**: Built WITH `-H windowsgui` (no console)
+- **go-winres**: Must run `go-winres make` in each `cmd/*/` directory before building to embed icons. The `.syso` files are gitignored.
+- **licenses.txt**: Copied from `docs/build-licenses.txt` by the build script. Must exist in `cmd/installer/` before building.
+- **terms_translations.json**: Generated by the build script from `TERMS_SECTIONS` in `terms_agreement.py` + `languages.yaml`
+- **DO NOT** use `CREATE_NO_WINDOW` flag on the launcher's child process — breaks FFmpeg pipe handles
+- **DO NOT** use `walk` or other Go GUI frameworks — they have `TTM_ADDTOOL` failures on modern Windows. Use raw Win32 API.
+
+## Testing
+
+```bash
+# Test launcher
+dist/FastFlix/FastFlix.exe --version
+dist/FastFlix/FastFlix.exe --test
+
+# Test full app launch
+dist/FastFlix/FastFlix.exe
+
+# Test installer
+dist/FastFlix_installer.exe
+
+# Test standalone uninstaller (from install location)
+"%LOCALAPPDATA%\Programs\FastFlix\uninstall.exe"
+```

CLAUDE.md

@@ -29,8 +29,12 @@ uv run pytest tests/encoders/test_hevc_x265_command_builder.py -v
 # Run the application
 python -m fastflix
 
-# Build executables
-uv run pyinstaller FastFlix_Windows_OneFile.spec
+# Build Windows distribution + installer (Go-based, replaces PyInstaller)
+uv run python scripts/build_distribution.py --archive  # Full dist + archive
+cd cmd/installer && go-winres make && cd ../..          # Icon/manifest resources
+go build -ldflags="-s -w -H windowsgui -X main.Version=6.3.0 -X main.BuildDate=$(date +%Y-%m-%d)" -o dist/FastFlix_installer.exe ./cmd/installer
+
+# Build Linux/macOS executables (still uses PyInstaller)
 uv run pyinstaller FastFlix_Nix_OneFile.spec
 ```
 

WINDOWS_BUILD.md

@@ -1,133 +1,187 @@
 # Building FastFlix on Windows
 
-This guide explains how to build FastFlix executables on Windows.
+This guide explains how to build FastFlix executables and the installer on Windows.
 
 ## Prerequisites
 
 1. **Python 3.13 or higher**
    - Download from [python.org](https://www.python.org/downloads/)
    - Make sure to check "Add Python to PATH" during installation
 
-2. **Git** (to clone/update the repository)
-   - Download from [git-scm.com](https://git-scm.com/download/win)
+2. **Go 1.22 or higher**
+   - Download from [go.dev](https://go.dev/dl/)
+   - Needed for the launcher, installer, and uninstaller binaries
 
-## Build Steps
+3. **go-winres** (for embedding icons and manifests)
+   ```bash
+   go install github.com/tc-hib/go-winres@latest
+   ```
 
-### 1. Open Command Prompt or PowerShell
+4. **uv** (Python package manager)
+   ```bash
+   pip install uv
+   ```
 
-Navigate to where you want to clone/have the FastFlix repository:
+5. **Git** (to clone/update the repository)
+   - Download from [git-scm.com](https://git-scm.com/download/win)
 
-```bash
-cd C:\path\to\your\projects
-git clone https://github.com/cdgriffith/FastFlix.git
-cd FastFlix
-```
+## Quick Build (Full Installer)
 
-Or if you already have it:
+If you just want to build the installer from scratch:
 
 ```bash
 cd C:\path\to\FastFlix
-```
 
-### 2. Create and Activate Virtual Environment
+# Install Python dependencies
+uv sync --frozen
 
-```bash
-python -m venv venv
-venv\Scripts\activate
-```
+# Install zstandard for archive compression
+uv run pip install zstandard
 
-You should see `(venv)` in your command prompt.
+# Build the full distribution + archive (downloads embeddable Python, installs deps, builds Go binaries)
+uv run python scripts/build_distribution.py --archive
 
-### 3. Install Dependencies
+# Generate icon/manifest resources for the installer
+cd cmd\installer
+go-winres make
+cd ..\..
 
-```bash
-pip install --upgrade pip
-pip install -e ".[dev]"
+# Build the installer
+go build -ldflags="-s -w -H windowsgui -X main.Version=6.3.0" -o dist\FastFlix_installer.exe .\cmd\installer
 ```
 
-This installs FastFlix in editable mode with all development dependencies including PyInstaller.
+The installer will be at `dist\FastFlix_installer.exe` (~87 MB).
 
-### 4. Build the Executable
+## What the Build Script Does
 
-You have two options:
+`scripts/build_distribution.py --archive` performs these steps automatically:
 
-#### Option A: Single Executable (Recommended for distribution)
+1. Downloads the official Python 3.13 embeddable distribution (~11 MB)
+2. Configures the embeddable Python to find installed packages
+3. Builds a FastFlix wheel and installs it with all dependencies
+4. Builds the Go launcher (`FastFlix.exe`) and uninstaller (`uninstall.exe`)
+5. Trims unused PySide6 modules (~527 MB savings)
+6. Copies licenses and generates translated terms text
+7. Creates a compressed `tar.zst` archive (~83 MB)
 
-```bash
-pyinstaller FastFlix_Windows_OneFile.spec
-```
+The archive is then embedded into the Go installer binary via `go:embed`.
 
-The executable will be in: `dist\FastFlix.exe`
+## Building Individual Components
 
-#### Option B: Directory with Multiple Files (Faster startup)
+### Launcher Only
 
 ```bash
-pyinstaller FastFlix_Windows_Installer.spec
+go build -ldflags="-s -w -X main.Version=6.3.0" -o dist\FastFlix\FastFlix.exe .\cmd\launcher
 ```
 
-The executable will be in: `dist\FastFlix\FastFlix.exe`
+### Uninstaller Only
 
-### 5. Test the Build
+```bash
+cd cmd\uninstaller
+go-winres make
+cd ..\..
+go build -ldflags="-s -w -H windowsgui" -o dist\FastFlix\uninstall.exe .\cmd\uninstaller
+```
+
+### Installer Only (requires archive already built)
 
 ```bash
-cd dist
-FastFlix.exe
+cd cmd\installer
+go-winres make
+cd ..\..
+go build -ldflags="-s -w -H windowsgui -X main.Version=6.3.0" -o dist\FastFlix_installer.exe .\cmd\installer
 ```
 
-Or for the installer version:
+## Testing the Build
 
 ```bash
-cd dist\FastFlix
-FastFlix.exe
+# Test launcher
+dist\FastFlix\FastFlix.exe --version
+dist\FastFlix\FastFlix.exe --test
+
+# Launch the full app
+dist\FastFlix\FastFlix.exe
+
+# Test the installer
+dist\FastFlix_installer.exe
 ```
 
-## Running Without Building (For Testing)
+## Running Without Building (For Development)
 
-If you just want to test changes without building an executable:
+If you just want to test changes without building executables:
 
 ```bash
+uv sync --frozen
 python -m fastflix
 ```
 
 ## Troubleshooting
 
-### Missing Dependencies
-
-If you get import errors, try reinstalling:
+### Missing Go
 
+If `go build` fails with "go: command not found", ensure Go is installed and in your PATH:
 ```bash
-pip install --upgrade --force-reinstall -e ".[dev]"
+go version
 ```
 
-### Build Errors
+### Missing go-winres
 
-1. Make sure you're in the FastFlix root directory
-2. Ensure the virtual environment is activated (you see `(venv)`)
-3. Try deleting `build` and `dist` folders and rebuilding:
+The installer and uninstaller need `go-winres` to embed icons:
+```bash
+go install github.com/tc-hib/go-winres@latest
+```
+
+### Missing licenses.txt or terms_translations.json
 
+These are generated by the build script. If building the installer manually:
 ```bash
-rmdir /s /q build dist
-pyinstaller FastFlix_Windows_OneFile.spec
+copy docs\build-licenses.txt cmd\installer\licenses.txt
+uv run python scripts/build_distribution.py --archive
 ```
 
+### Build Errors
+
+1. Make sure you're in the FastFlix root directory
+2. Try deleting `dist` and rebuilding:
+   ```bash
+   rmdir /s /q dist
+   uv run python scripts/build_distribution.py --archive
+   ```
+
 ### FFmpeg Not Found
 
-The FastFlix executable doesn't include FFmpeg. You need to:
+The FastFlix distribution doesn't include FFmpeg. You need to:
 
 1. Download FFmpeg from [ffmpeg.org](https://ffmpeg.org/download.html#build-windows)
 2. Extract it somewhere
 3. Add the `bin` folder to your PATH, or configure it in FastFlix settings
 
-## Known Limitations
+## Architecture
+
+The Windows distribution uses three Go binaries instead of PyInstaller:
+
+| Binary | Purpose | Console |
+|--------|---------|---------|
+| `FastFlix.exe` | Go launcher — sets up Python environment and runs `python.exe -m fastflix` | Yes (for logs) |
+| `uninstall.exe` | Standalone uninstaller — registered with Windows Add/Remove Programs | No (GUI) |
+| `FastFlix_installer.exe` | Dark-themed installer with embedded distribution archive | No (GUI) |
 
-### PGS to SRT OCR (PyInstaller builds)
+The installer supports two modes:
+- **Install for just me** — installs to `%LOCALAPPDATA%\Programs\FastFlix` (no admin required)
+- **Install for all users** — installs to `%ProgramFiles%\FastFlix` (triggers UAC)
 
-Due to an upstream issue in pgsrip v0.1.12, PGS to SRT OCR conversion does not work in PyInstaller-built executables. The feature works perfectly when running from source (`python -m fastflix`).
+## Linux/macOS
 
-If you need PGS OCR functionality, please run FastFlix from source instead of using the compiled executable.
+Linux and macOS builds still use PyInstaller:
+
+```bash
+uv run pyinstaller FastFlix_Nix_OneFile.spec
+```
 
 ## Notes
 
-- The build process creates a `portable.py` file temporarily (it's removed after)
-- The `.spec` files automatically collect all dependencies from `pyproject.toml`
-- The icon is located at `fastflix\data\icon.ico`
+- The Go launcher is built as a **console app** (not GUI) so users can see log output
+- The installer and uninstaller are built with `-H windowsgui` (no console window)
+- Icons are embedded via `go-winres` — `.syso` files are gitignored
+- The distribution archive uses Zstandard compression (level 22) for best ratio
+- PySide6 trimming removes WebEngine (193 MB), Quick/QML, 3D, Designer, and other unused Qt modules

cmd/installer/main.go

@@ -17,8 +17,9 @@ import (
 	"unsafe"
 )
 
-// Version is set at build time via -ldflags="-X main.Version=6.3.0"
+// Version and BuildDate are set at build time via -ldflags
 var Version = "dev"
+var BuildDate = "" // format: 2006-01-02
 
 func main() {
 	runtime.LockOSThread()