fix(plugin): read the OS version branch from the updater config on OSTree hosts (#2084)

## Summary

On Unraid OS 8 (Fedora/OSTree hosts) the Connect plugin always reported
the OS version branch as `stable`, because there is no OS plugin to read
a `CATEGORY` from. `ServerState::osVersionBranch` and the `unraidcheck`
release query now use the branch of the installed release that Core
records in the updater config.

## Why This Exists

Unraid 7 derives the branch from the `CATEGORY` attribute of the
installed OS plugin
(`/usr/local/emhttp/plugins/unRAIDServer/unRAIDServer.plg`, also linked
at `/var/log/plugins/unRAIDServer.plg`). Unraid OS 8 has no OS plugin:
neither file exists on an OSTree host (detectable by
`/run/ostree-booted`), so both call sites fell through to their `stable`
default even on a `preview` or `next` install.

Core (unraid/core#1221) records the branch of the installed release in
`/boot/config/os-update.json` as the top-level string key `branch`; the
image default `/etc/unraid/os-update.json` may exist as a read-only
fallback.

## Resolution

- Add one shared helper, `OsRelease`
(`plugins/dynamix.my.servers/include/os-release.php`), required by both
`state.php` and `UnraidCheck.php`.
- `OsRelease::branch()`: when an `unRAIDServer.plg` exists, keep using
`plugin category` (the webGui `plugin()` helper, or the CLI when the
helper is not loaded). Otherwise, when `/run/ostree-booted` exists, read
`branch` from `/boot/config/os-update.json`, then
`/etc/unraid/os-update.json`. Only values matching
`/^[a-z0-9][a-z0-9_-]{0,31}$/` are accepted; everything else, including
missing or malformed JSON, resolves to `stable` without throwing.
- `OsRelease::version()`: reads `version` from `/etc/unraid-version`
(ini-style, e.g. `version="8.0.0-preview.3"`).
- `state.php`: `osVersionBranch` uses `OsRelease::branch()`.
- `UnraidCheck.php`: the `branch` query parameter uses
`OsRelease::branch()`; `current_version` falls back to
`OsRelease::version()` before `var.ini` when there is no OS plugin
version (OS 8).

## Behavior Changes

- Unraid 7: unchanged. The branch still comes from the installed OS
plugin's `CATEGORY`; `current_version` still prefers the patcher
version, then the plugin version.
- Unraid OS 8: `osVersionBranch` and the `unraidcheck` `branch`
parameter reflect the installed release branch from
`/boot/config/os-update.json` (or the image default), and
`current_version` comes from `/etc/unraid-version`. Hosts with no
readable or valid branch still report `stable`.

## Verification

- The plugin package has no phpunit harness; its PHP tests are
standalone php-cli scripts run from `pnpm test` (CI `test-api` job
installs `php-cli` and runs `cd plugin && pnpm test`). Added
`plugin/tests/test-os-release.php` (+ `.sh` wrapper) in the same pattern
as `test-extractor` and wired it into `pnpm --filter
@unraid/connect-plugin test` as `test:os-release`.
- `bash plugin/tests/test-os-release.sh` — 21 passed, 0 failed (Unraid 7
category path, OSTree boot/etc config precedence, malformed JSON,
non-string/missing key, invalid values, trimming, 32-char limit,
`/etc/unraid-version` parsing).
- `php -l` on the three PHP files — no syntax errors.
- `git diff --check` — passed.

## Review Notes

The forecast and final AI-review receipts are committed on the branch.
The commits were made with the JS lint-staged hook skipped because it
has no rule for PHP, JSON, or shell files and the worktree has no
`node_modules`. No merge or auto-merge was performed.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **Improvements**
* Improved detection of the installed Unraid OS branch across standard
and OSTree-based systems.
* Improved current-version reporting by using the installed OS version
when other version information is unavailable.
* Update checks now use the detected OS branch, improving accuracy for
non-stable release channels.

* **Bug Fixes**
* Added safer handling for missing, malformed, or invalid OS release
information, with a stable branch fallback.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: elibosley

.limetech/ai-review-markers/codex-ostree-os-version-branch-84e4ee0b8063.json

@@ -0,0 +1,8 @@
+{
+  "disposition": "PATCH",
+  "forecast_commit": "31b615c6637c5365cf9d86b77bb607bb16806e1f",
+  "reviewed_sha": "68d6f826f43badbec4cda484975cb6f822df3a7c",
+  "schema": "limetech.ai-review-marker.v2",
+  "stage": "final",
+  "unresolved_proportionality_findings": []
+}

plugin/package.json

@@ -34,8 +34,9 @@
     "env:validate": "test -f .env || (echo 'Error: .env file missing. Run npm run env:init first' && exit 1)",
     "env:clean": "rm -f .env",
     "// Testing": "",
-    "test": "vitest && pnpm run test:extractor && pnpm run test:shell-detection && pnpm run test:txz-install",
+    "test": "vitest && pnpm run test:extractor && pnpm run test:os-release && pnpm run test:shell-detection && pnpm run test:txz-install",
     "test:extractor": "bash ./tests/test-extractor.sh",
+    "test:os-release": "bash ./tests/test-os-release.sh",
     "test:shell-detection": "bash ./tests/test-shell-detection.sh",
     "test:txz-install": "bash ./tests/test-txz-install.sh"
   },

plugin/source/dynamix.unraid.net/usr/local/emhttp/plugins/dynamix.my.servers/include/os-release.php

@@ -0,0 +1,108 @@
+<?php
+/* Copyright 2005-2026, Lime Technology
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License version 2,
+ * as published by the Free Software Foundation.
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ */
+
+/**
+ * Resolves the installed Unraid OS release branch and version.
+ *
+ * Unraid 7 derives the branch from the CATEGORY of the installed OS plugin
+ * (unRAIDServer.plg). Unraid OS 8 (OSTree hosts) has no OS plugin; Core records
+ * the branch of the installed release in /boot/config/os-update.json, with the
+ * image default in /etc/unraid/os-update.json as a read-only fallback.
+ */
+class OsRelease
+{
+    public const DEFAULT_BRANCH = 'stable';
+    public const BRANCH_PATTERN = '/^[a-z0-9][a-z0-9_-]{0,31}$/';
+    public const PLG_PATHS = [
+        '/usr/local/emhttp/plugins/unRAIDServer/unRAIDServer.plg',
+        '/var/log/plugins/unRAIDServer.plg',
+    ];
+    public const OSTREE_BOOTED_PATH = '/run/ostree-booted';
+    public const OS_UPDATE_CONFIG_PATHS = [
+        '/boot/config/os-update.json',
+        '/etc/unraid/os-update.json',
+    ];
+    public const UNRAID_VERSION_PATH = '/etc/unraid-version';
+
+    /**
+     * @param string[]|null $plgPaths
+     * @param string[]|null $osUpdateConfigPaths
+     */
+    public static function branch(?array $plgPaths = null, ?string $ostreeBootedPath = null, ?array $osUpdateConfigPaths = null): string
+    {
+        $branch = null;
+        $plgPath = self::firstFile($plgPaths ?? self::PLG_PATHS);
+        if ($plgPath !== null) {
+            $branch = self::branchFromPlugin($plgPath);
+        } elseif (is_file($ostreeBootedPath ?? self::OSTREE_BOOTED_PATH)) {
+            $branch = self::branchFromOsUpdateConfig($osUpdateConfigPaths ?? self::OS_UPDATE_CONFIG_PATHS);
+        }
+        return self::isValidBranch($branch) ? $branch : self::DEFAULT_BRANCH;
+    }
+
+    /**
+     * Installed OS version from /etc/unraid-version, or null when unavailable.
+     */
+    public static function version(?string $unraidVersionPath = null): ?string
+    {
+        $path = $unraidVersionPath ?? self::UNRAID_VERSION_PATH;
+        if (!is_file($path)) {
+            return null;
+        }
+        $info = @parse_ini_file($path);
+        $version = is_array($info) ? ($info['version'] ?? null) : null;
+        $version = is_string($version) ? trim($version) : '';
+        return $version === '' ? null : $version;
+    }
+
+    public static function isValidBranch($branch): bool
+    {
+        return is_string($branch) && preg_match(self::BRANCH_PATTERN, $branch) === 1;
+    }
+
+    private static function firstFile(array $paths): ?string
+    {
+        foreach ($paths as $path) {
+            if (is_file($path)) {
+                return $path;
+            }
+        }
+        return null;
+    }
+
+    private static function branchFromPlugin(string $plgPath): ?string
+    {
+        if (function_exists('plugin')) {
+            $branch = plugin('category', $plgPath);
+        } else {
+            $branch = @exec('plugin category ' . escapeshellarg($plgPath));
+        }
+        return is_string($branch) ? trim($branch) : null;
+    }
+
+    private static function branchFromOsUpdateConfig(array $paths): ?string
+    {
+        foreach ($paths as $path) {
+            if (!is_file($path)) {
+                continue;
+            }
+            $config = json_decode((string)@file_get_contents($path), true);
+            if (!is_array($config)) {
+                continue;
+            }
+            $branch = $config['branch'] ?? null;
+            if (is_string($branch)) {
+                return trim($branch);
+            }
+        }
+        return null;
+    }
+}

plugin/source/dynamix.unraid.net/usr/local/emhttp/plugins/dynamix.my.servers/include/state.php

@@ -18,6 +18,7 @@
 require_once "$docroot/plugins/dynamix.my.servers/include/reboot-details.php";
 require_once "$docroot/plugins/dynamix.plugin.manager/include/UnraidCheck.php";
 require_once "$docroot/plugins/dynamix.my.servers/include/api-config.php";
+require_once "$docroot/plugins/dynamix.my.servers/include/os-release.php";
 /**
  * ServerState class encapsulates server-related information and settings.
  *
@@ -112,7 +113,7 @@ public function __construct()
 
         $this->state = strtoupper(empty($this->var['regCheck']) ? $this->var['regTy'] : $this->var['regCheck']);
         $this->osVersion = $this->var['version'];
-        $this->osVersionBranch = trim(@exec('plugin category /var/log/plugins/unRAIDServer.plg') ?? 'stable');
+        $this->osVersionBranch = OsRelease::branch();
 
         $caseModelFile = '/boot/config/plugins/dynamix/case-model.cfg';
         $this->caseModel = file_exists($caseModelFile) ? htmlspecialchars(@file_get_contents($caseModelFile), ENT_HTML5, 'UTF-8') : '';

plugin/source/dynamix.unraid.net/usr/local/emhttp/plugins/dynamix.plugin.manager/include/UnraidCheck.php

@@ -30,6 +30,7 @@
 $docroot ??= ($_SERVER['DOCUMENT_ROOT'] ?: '/usr/local/emhttp');
 require_once "$docroot/webGui/include/Wrappers.php";
 require_once "$docroot/plugins/dynamix.plugin.manager/include/PluginHelpers.php";
+require_once "$docroot/plugins/dynamix.my.servers/include/os-release.php";
 
 class UnraidOsCheck
 {
@@ -165,7 +166,7 @@ function _($text) {return $text;}
         $var = (array)@parse_ini_file('/var/local/emhttp/var.ini');
 
         $params  = [];
-        $params['branch']          = plugin('category', self::PLG_PATH, 'stable');
+        $params['branch']          = OsRelease::branch();
         // Get current version from patches.json if it exists, otherwise fall back to plugin version or var.ini
         $patcherVersion = null;
         if (file_exists('/tmp/Patcher/patches.json')) {
@@ -176,7 +177,7 @@ function _($text) {return $text;}
             }
         }
 
-        $params['current_version'] = $patcherVersion ?: plugin('version', self::PLG_PATH) ?: _var($var, 'version');
+        $params['current_version'] = $patcherVersion ?: plugin('version', self::PLG_PATH) ?: OsRelease::version() ?: _var($var, 'version');
         if (_var($var,'regExp')) $params['update_exp'] = date('Y-m-d', _var($var,'regExp')*1);
         $defaultUrl = self::BASE_RELEASES_URL;
         // pass a param of altUrl to use the provided url instead of the default

plugin/tests/test-os-release.php

@@ -0,0 +1,115 @@
+#!/usr/bin/env php
+<?php
+/**
+ * OsRelease Test Suite
+ *
+ * Exit codes:
+ *   0 - All tests passed
+ *   1 - One or more tests failed
+ */
+
+// Stand-in for the webGui PluginHelpers plugin() function used on Unraid 7.
+function plugin($method, $plugin_file, $default = false) {
+    return $method === 'category' ? "next\n" : $default;
+}
+
+require_once __DIR__ . '/../source/dynamix.unraid.net/usr/local/emhttp/plugins/dynamix.my.servers/include/os-release.php';
+
+class OsReleaseTest {
+    private $dir;
+    private $passed = 0;
+    private $failed = 0;
+
+    const RED = "\033[0;31m";
+    const GREEN = "\033[0;32m";
+    const NC = "\033[0m";
+
+    public function run() {
+        $this->dir = sys_get_temp_dir() . '/os-release-test-' . uniqid();
+        mkdir($this->dir, 0755, true);
+        try {
+            $this->runTests();
+        } finally {
+            $this->cleanup($this->dir);
+        }
+        echo "\nResults: {$this->passed} passed, {$this->failed} failed\n";
+        return $this->failed === 0 ? 0 : 1;
+    }
+
+    private function path($name) {
+        return $this->dir . '/' . $name;
+    }
+
+    private function write($name, $contents) {
+        file_put_contents($this->path($name), $contents);
+        return $this->path($name);
+    }
+
+    private function branch($plg, $ostree, array $configs) {
+        return OsRelease::branch([$this->path($plg)], $this->path($ostree), array_map([$this, 'path'], $configs));
+    }
+
+    private function assertSame($expected, $actual, $label) {
+        if ($expected === $actual) {
+            $this->passed++;
+            echo self::GREEN . "PASS" . self::NC . " $label\n";
+        } else {
+            $this->failed++;
+            echo self::RED . "FAIL" . self::NC . " $label: expected " . var_export($expected, true) . ", got " . var_export($actual, true) . "\n";
+        }
+    }
+
+    private function runTests() {
+        $this->write('unRAIDServer.plg', '<PLUGIN category="next"></PLUGIN>');
+        $this->assertSame('next', $this->branch('unRAIDServer.plg', 'missing-ostree', []), 'Unraid 7 uses the OS plugin category');
+
+        $this->write('os-update.json', json_encode(['branch' => 'preview', 'other' => 1]));
+        $this->assertSame('next', $this->branch('unRAIDServer.plg', 'ostree-booted', ['os-update.json']), 'OS plugin category wins over the updater config');
+
+        $this->assertSame('stable', $this->branch('missing.plg', 'missing-ostree', ['os-update.json']), 'Non-OSTree host without an OS plugin defaults to stable');
+
+        $this->write('ostree-booted', '');
+        $this->assertSame('preview', $this->branch('missing.plg', 'ostree-booted', ['os-update.json']), 'OSTree host reads branch from os-update.json');
+
+        $this->write('etc-os-update.json', json_encode(['branch' => 'next']));
+        $this->assertSame('next', $this->branch('missing.plg', 'ostree-booted', ['missing.json', 'etc-os-update.json']), 'OSTree host falls back to the image default config');
+
+        $this->assertSame('stable', $this->branch('missing.plg', 'ostree-booted', ['missing.json']), 'OSTree host without any updater config defaults to stable');
+
+        $this->write('malformed.json', '{"branch": "preview"');
+        $this->assertSame('preview', $this->branch('missing.plg', 'ostree-booted', ['malformed.json', 'os-update.json']), 'Malformed config is skipped without throwing');
+        $this->assertSame('stable', $this->branch('missing.plg', 'ostree-booted', ['malformed.json']), 'Malformed config alone defaults to stable');
+
+        $this->write('no-branch.json', json_encode(['channel' => 'preview']));
+        $this->assertSame('next', $this->branch('missing.plg', 'ostree-booted', ['no-branch.json', 'etc-os-update.json']), 'Config without a branch key falls through');
+
+        $this->write('non-string.json', json_encode(['branch' => ['preview']]));
+        $this->assertSame('next', $this->branch('missing.plg', 'ostree-booted', ['non-string.json', 'etc-os-update.json']), 'Non-string branch falls through');
+
+        foreach (['Stable', '../etc', '-next', 'a b', str_repeat('a', 33), ''] as $bad) {
+            $this->write('bad.json', json_encode(['branch' => $bad]));
+            $this->assertSame('stable', $this->branch('missing.plg', 'ostree-booted', ['bad.json']), 'Invalid branch ' . var_export($bad, true) . ' defaults to stable');
+        }
+
+        $this->write('trimmed.json', json_encode(['branch' => " preview \n"]));
+        $this->assertSame('preview', $this->branch('missing.plg', 'ostree-booted', ['trimmed.json']), 'Branch value is trimmed');
+
+        $this->write('long.json', json_encode(['branch' => 'a' . str_repeat('b', 31)]));
+        $this->assertSame('a' . str_repeat('b', 31), $this->branch('missing.plg', 'ostree-booted', ['long.json']), 'Branch of 32 characters is accepted');
+
+        $this->write('unraid-version', "version=\"8.0.0-preview.3\"\n");
+        $this->assertSame('8.0.0-preview.3', OsRelease::version($this->path('unraid-version')), 'Version is read from /etc/unraid-version');
+        $this->assertSame(null, OsRelease::version($this->path('missing-version')), 'Missing version file yields null');
+        $this->write('empty-version', "name=\"Unraid\"\n");
+        $this->assertSame(null, OsRelease::version($this->path('empty-version')), 'Version file without version yields null');
+    }
+
+    private function cleanup($dir) {
+        foreach (glob($dir . '/*') ?: [] as $file) {
+            unlink($file);
+        }
+        rmdir($dir);
+    }
+}
+
+exit((new OsReleaseTest())->run());

plugin/tests/test-os-release.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+
+# OsRelease helper test
+#
+# Runs the PHP test suite for the shared OS release branch/version helper.
+# Exit codes:
+#   0 - All tests passed
+#   1 - One or more tests failed
+
+set -e
+
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+
+exec php "$SCRIPT_DIR/test-os-release.php" "$@"