Feat/dual os

.cortex/plans/dual-os-plan.md

@@ -0,0 +1,46 @@
+# Plan: Dual-OS Build for avior-go (Windows + Linux)
+
+## Context
+
+avior-go currently only compiles for Windows because `encoder/encoder.go` directly uses
+the Windows API (`golang.org/x/sys/windows`: `OpenProcess`, `SetPriorityClass`,
+`CloseHandle`) to set the process priority of the spawned `ffmpeg` process.
+Goal: The same code should optionally produce a Windows executable (`avior-go.exe`) or a
+Linux binary (`avior-go`) via Go build tags / `GOOS`, so that avior-go instances can run
+under Linux in Docker in the future.
+
+Facts from the code (verified in this session):
+- Only Windows dependency in the entire repo: `encoder/encoder.go` lines 176–188
+  (`windows.OpenProcess` / `windows.SetPriorityClass` / `windows.CloseHandle`), plus the
+  import `"golang.org/x/sys/windows"` on line 23.
+- All path operations already use `filepath.Join` (app.go, config/config.go,
+  api/api.go) — OS-agnostic. UNC paths exist only in config JSONs (user data, not a
+  code problem).
+- All Go dependencies in `go.mod` are pure Go (gorilla, redis, mongo-driver, glg,
+  godirwalk, lumberjack …) → `CGO_ENABLED=0` cross-compile is possible, no C toolchain
+  needed.
+- CI: `.github/workflows/go.yml` currently builds only `goos: windows`, `goarch: amd64`
+  via `wangyoucao577/go-release-action@v1.18`.
+- Go version per go.mod: `go 1.25.0`.
+
+End state: `GOOS=windows go build` and `GOOS=linux go build` both work; ffmpeg priority
+is set per OS via build-tag files (Windows: PriorityClass, Linux: nice level); CI builds
+both artifacts.
+## Tasks (one MD file each)
+
+1. `dual-os-task-01-priority-build-tags.md` — Extract OS-specific priority setting
+   from `encoder/encoder.go` into build-tag files.
+2. `dual-os-task-02-build-switches.md` — Build switches (Makefile + scripts) for
+   Windows and Linux executables.
+3. `dual-os-task-03-ci-matrix.md` — Extend GitHub Actions workflow to a
+   Windows+Linux matrix.
+4. `dual-os-task-04-verification.md` — Verification: cross-compile both targets,
+   tests, smoke check.
+5. `dual-os-task-05-docker-compose.md` — Dockerfile + compose.yaml for Komodo deployment
+   (mount `/mnt/user/media` → `/media`).
+
+Dependencies: Task 01 first (otherwise Linux won't compile). Tasks 02 and 03 are
+independent of each other, but both require Task 01. Task 05 requires Task 01 (uses the
+same Linux build). Task 04 last.
+
+

.cortex/plans/dual-os-task-01-priority-build-tags.md

@@ -0,0 +1,124 @@
+# Task 01: OS-specific ffmpeg Priority via Build Tags
+
+## Goal
+
+`encoder/encoder.go` won't compile under Linux (direct import of
+`golang.org/x/sys/windows`). The priority setting is extracted into two build-tag files;
+`encoder.go` only calls an OS-neutral helper function.
+
+## Edits
+
+### 1. New file `encoder/priority_windows.go`
+
+```go
+//go:build windows
+
+package encoder
+
+import (
+	"os/exec"
+
+	"github.com/Spiritreader/avior-go/config"
+	"github.com/kpango/glg"
+	"golang.org/x/sys/windows"
+)
+
+// setProcessPriority sets the Windows PriorityClass of the spawned ffmpeg process.
+// Errors are only logged (as before), since the encoding itself doesn't depend on it.
+func setProcessPriority(cmd *exec.Cmd, cfg *config.Data) {
+	hProcess, err := windows.OpenProcess(0x0400|0x0200, false, uint32(cmd.Process.Pid))
+	if err != nil {
+		_ = glg.Warnf("could not get ffmpeg handle using pid %d, err: %s", cmd.Process.Pid, err)
+		return
+	}
+	defer func() {
+		if err := windows.CloseHandle(hProcess); err != nil {
+			_ = glg.Errorf("could not close handle for pid %d, err: %s", cmd.Process.Pid, err)
+		}
+	}()
+	if err := windows.SetPriorityClass(hProcess, config.PriorityUint32(cfg.Local.EncoderPriority)); err != nil {
+		_ = glg.Warnf("could not set priority %s for ffmpeg handle using pid %d, err: %s",
+			cfg.Local.EncoderPriority, cmd.Process.Pid, err)
+	}
+}
+```
+
+Behavior change over the original: `return` after `OpenProcess` error (avoids
+`SetPriorityClass` on invalid handle) and `CloseHandle` via `defer`. This is the
+correct version of the existing code — no functional change in the success case. Log
+strings remain identical, except the `SetPriorityClass` log outputs
+`cfg.Local.EncoderPriority` instead of `cfg.Local.EncoderConfig` (fix for a copy-paste
+error in the original, line 183).
+
+### 2. New file `encoder/priority_linux.go`
+
+```go
+//go:build linux
+
+package encoder
+
+import (
+	"os/exec"
+	"syscall"
+
+	"github.com/Spiritreader/avior-go/config"
+	"github.com/kpango/glg"
+)
+
+// niceLevel maps the configured Windows priority level to a Linux nice value.
+// Mapping: HIGH/ABOVE_NORMAL -> -5 (higher priority, requires root/CAP_SYS_NICE),
+// NORMAL -> 0, BELOW_NORMAL -> 10, IDLE -> 19.
+// Unknown values fall back to 19 (idle) — analogous to the Windows fallback in
+// config.PriorityUint32, which returns IDLE for unknown values.
+func niceLevel(priority string) int {
+	switch priority {
+	case config.PRIORITY_HIGH.String(), config.PRIORITY_ABOVE_NORMAL.String():
+		return -5
+	case config.PRIORITY_NORMAL.String():
+		return 0
+	case config.PRIORITY_BELOW_NORMAL.String():
+		return 10
+	default:
+		return 19
+	}
+}
+
+// setProcessPriority sets the nice level of the spawned ffmpeg process.
+// An error (e.g. missing permissions for negative nice values in a Docker container)
+// is only logged as a warning; encoding proceeds normally.
+func setProcessPriority(cmd *exec.Cmd, cfg *config.Data) {
+	if err := syscall.Setpriority(syscall.PRIO_PROCESS, cmd.Process.Pid, niceLevel(cfg.Local.EncoderPriority)); err != nil {
+		_ = glg.Warnf("could not set priority %s for ffmpeg process with pid %d, err: %s",
+			cfg.Local.EncoderPriority, cmd.Process.Pid, err)
+	}
+}
+```
+
+Note: In Docker without `CAP_SYS_NICE`, negative nice values will fail — this is
+acceptable (warning in log, encoding runs with default priority). The container docs
+may later recommend `--cap-add SYS_NICE`, but that is not part of this plan.
+
+### 3. Adapt `encoder/encoder.go`
+
+- Remove import `"golang.org/x/sys/windows"` (line 23). `config` stays imported
+  (still used elsewhere in the file — verified: `cfg.Local.*` throughout).
+- Replace the block on lines 176–188 (the three `windows.*` calls with error logs) with:
+
+```go
+	setProcessPriority(cmd, cfg)
+```
+
+The call goes directly after the successful `cmd.Start()`, exactly where the old block
+was.
+
+## No further callsites
+
+`grep` for `x/sys` and `windows\.` in the entire repo: only `encoder/encoder.go`.
+`config.PriorityUint32` remains unchanged (still used by `priority_windows.go`).
+Clean cutover: no compatibility code.
+
+## Check
+
+- `GOOS=windows go build ./...` and `GOOS=linux go build ./...` from the repo root
+  both compile without errors.
+- `go vet ./encoder` without findings.

.cortex/plans/dual-os-task-02-build-switches.md

@@ -0,0 +1,82 @@
+# Task 02: Build Switches for Windows and Linux Executables
+
+## Goal
+
+One command per target platform produces the final binary. Go compiles cross-platform
+natively via the `GOOS` switch; all dependencies are pure Go, therefore `CGO_ENABLED=0`
+(static binary, ideal for slim Docker images).
+
+## Edits
+
+### 1. New `Makefile` in repo root
+
+```make
+BINARY := avior-go
+VERSION := $(shell git describe --tags --always --dirty 2>/dev/null || echo dev)
+LDFLAGS := -s -w -X main.buildVersion=$(VERSION)
+
+.PHONY: build-windows build-linux build all
+
+build-windows:
+	CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -ldflags "$(LDFLAGS)" -o dist/$(BINARY)-windows-amd64.exe app.go
+
+build-linux:
+	CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags "$(LDFLAGS)" -o dist/$(BINARY)-linux-amd64 app.go
+
+build: build-windows
+
+all: build-windows build-linux
+```
+
+Notes:
+- Entry point is `app.go` (package main in the repo root; verified via
+  `.vscode/launch.json`, which launches `app.go` as the program).
+- `-ldflags "-s -w"` strips symbols (smaller binary for containers).
+- `main.buildVersion` is only set if the variable exists — unverified whether
+  `buildVersion` exists in app.go. If `go build` fails with "no such variable":
+  reduce ldflags to `-s -w` (fallback, no code requirement).
+
+### 2. Alternative scripts for systems without make
+
+`tools/build.ps1` (Windows development, reusing existing `tools/` convention):
+
+```powershell
+param([ValidateSet("windows","linux","all")][string]$Target = "windows")
+$env:CGO_ENABLED = "0"
+switch ($Target) {
+  "windows" { $env:GOOS="windows"; $env:GOARCH="amd64"; go build -ldflags "-s -w" -o dist/avior-go-windows-amd64.exe app.go }
+  "linux"   { $env:GOOS="linux";   $env:GOARCH="amd64"; go build -ldflags "-s -w" -o dist/avior-go-linux-amd64 app.go }
+  "all"     { & $PSCommandPath -Target windows; & $PSCommandPath -Target linux }
+}
+```
+
+`tools/build.sh` (Linux/macOS):
+
+```sh
+#!/bin/sh
+set -e
+target="${1:-linux}"
+export CGO_ENABLED=0 GOARCH=amd64
+case "$target" in
+  windows) GOOS=windows go build -ldflags "-s -w" -o dist/avior-go-windows-amd64.exe app.go ;;
+  linux)   GOOS=linux   go build -ldflags "-s -w" -o dist/avior-go-linux-amd64 app.go ;;
+  all)     "$0" windows && "$0" linux ;;
+  *) echo "usage: $0 [windows|linux|all]" >&2; exit 1 ;;
+esac
+```
+
+### 3. Update `.gitignore`
+
+Add `dist/` (the `*.exe` line already exists, but doesn't cover `dist/` on Linux where
+binaries have no `.exe` extension).
+
+## Usage (the "switches")
+
+- Windows executable: `make build-windows`  or  `./tools/build.ps1 -Target windows`
+- Linux binary:      `make build-linux`    or  `./tools/build.sh linux`
+
+## Check
+
+From repo root:
+- `make all` produces `dist/avior-go-windows-amd64.exe` AND `dist/avior-go-linux-amd64`.
+- `file dist/avior-go-linux-amd64` (under WSL/Git Bash) reports `ELF 64-bit ... statically linked`.

.cortex/plans/dual-os-task-03-ci-matrix.md

@@ -0,0 +1,58 @@
+# Task 03: Extend CI Workflow to Windows+Linux
+
+## Goal
+
+`.github/workflows/go.yml` builds both binaries on release and attaches them to the
+release. The existing `wangyoucao577/go-release-action@v1.18` step is parameterized
+per OS (matrix) instead of introducing a second mechanism (preserving the existing
+convention).
+
+## Edit: Replace `.github/workflows/go.yml` entirely with
+
+```yaml
+name: Go
+
+on:
+  release:
+    types: [created, edited]
+    branches: [ master ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - goos: windows
+            goarch: amd64
+            binary_name: avior-go
+          - goos: linux
+            goarch: amd64
+            binary_name: avior-go
+    steps:
+    - uses: actions/checkout@v2
+    - uses: wangyoucao577/go-release-action@v1.18
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        goos: ${{ matrix.goos }}
+        goarch: ${{ matrix.goarch }}
+        binary_name: ${{ matrix.binary_name }}
+        ldflags: -s -w
+```
+
+Reason: matrix instead of two hard jobs: same configuration, artifacts both land on the
+same release (`go-release-action` attaches one asset per `goos`; Windows asset is
+named `avior-go_windows_amd64.exe.zip`, Linux `avior-go_linux_amd64.tar.gz` —
+naming convention of the action, verify on first release).
+
+## Check
+
+- Validate workflow YAML locally: `python -c "import yaml,sys; yaml.safe_load(open('.github/workflows/go.yml'))"`.
+- Real check only possible on next release tag — alternative verification:
+  simulate the matrix run locally with the same commands
+  (`CGO_ENABLED=0 GOOS=linux go build ./...`, see Task 04).
+
+## Dependency
+
+Task 01 must be merged, otherwise the Linux target will fail in CI.

.cortex/plans/dual-os-task-04-verification.md

@@ -0,0 +1,62 @@
+# Task 04: Verification of the Dual-OS Build
+
+## Goal
+
+Prove that both targets compile from the same code and that the behavior of the
+changed code paths (Task 01) is unchanged or correct.
+
+Working directory for all commands: repo root `C:/repos/avior-go`. No env vars or
+fixtures needed; ffmpeg/ffprobe are not required for the pure build checks.
+
+## Checks (in this order)
+
+1. **Both targets compile** (exercises Tasks 01 + 02):
+   ```
+   CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -o dist/avior-go-windows-amd64.exe app.go
+   CGO_ENABLED=0 GOOS=linux   GOARCH=amd64 go build -o dist/avior-go-linux-amd64 app.go
+   ```
+   Expected: both commands exit 0, both files exist. Before Task 01, the Linux command
+   failed with `build constraints exclude all Go files ... x/sys/windows` — exactly
+   this error must be gone.
+
+2. **Linux binary is static** (Docker suitability):
+   ```
+   file dist/avior-go-linux-amd64
+   ```
+   Expected: `ELF 64-bit LSB executable, x86-64, ... statically linked`.
+   (`file` via Git Bash/WSL; if unavailable: skip — building with `CGO_ENABLED=0`
+   guarantees static linking.)
+
+3. **Vet + existing tests** (regression):
+   ```
+   go vet ./...
+   go test ./...
+   ```
+   Expected: no new findings; existing tests (including the `config` package) pass.
+   Windows-specific paths are tested on the dev Windows machine; the Linux path
+   (`priority_linux.go`) has no unit tests — intentional, it only wraps a syscall
+   with logging.
+
+4. **Windows smoke test (behavior unchanged)**:
+   Start `avior-go-windows-amd64.exe` with the existing `config_dev.json`, run an
+   encode job, and verify in the log (`log/main.log`) that NO new warning
+   `could not set priority ... for ffmpeg handle` appears — priority setting works
+   as before.
+
+5. **Linux smoke test (new behavior)**:
+   Start the Linux binary in a container or via WSL (`./avior-go-linux-amd64` alongside
+   a `config.json` with Linux paths in `MediaPaths`/`OutDirectory` and reachable
+   MongoDB/Redis). Once an encode job runs: the log must not contain a
+   `could not set priority` warning (unless the container runs without permissions
+   for negative nice values at `HIGH`/`ABOVE_NORMAL` — then exactly one warning is
+   acceptable and documented; encoding continues).
+   Additionally during an encode: `ps -o pid,ni,cmd -C ffmpeg` — the `NI` field must
+   match the configured mapping (IDLE → 19, NORMAL → 0, BELOW_NORMAL → 10).
+
+## Abort criteria / fallbacks
+
+- Check 1 fails for Linux with import error on `x/sys/windows`: Task 01 incomplete
+  (import not removed or build tag missing/misspelled — tag must be exactly
+  `//go:build windows` or `//go:build linux` as the first line).
+- Check 3 fails in `encoder` package: signature
+  `setProcessPriority(cmd *exec.Cmd, cfg *config.Data)` must be identical in both files.