[removed from main] fix(plugin): read the OS version branch from the updater config on OSTree hosts

[Eli Bosley (elibosley)]

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.

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.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Advanced

Run ID: 9c326514-9dcd-4f33-a608-2c1ed49e7c0f

📥 Commits

Reviewing files that changed from the base of the PR and between d061525 and 4640728.

📒 Files selected for processing (7)

• .limetech/ai-review-markers/codex-ostree-os-version-branch-84e4ee0b8063.json
• plugin/package.json
• plugin/source/dynamix.unraid.net/usr/local/emhttp/plugins/dynamix.my.servers/include/os-release.php
• plugin/source/dynamix.unraid.net/usr/local/emhttp/plugins/dynamix.my.servers/include/state.php
• plugin/source/dynamix.unraid.net/usr/local/emhttp/plugins/dynamix.plugin.manager/include/UnraidCheck.php
• plugin/tests/test-os-release.php
• plugin/tests/test-os-release.sh

Included review availability: Your plan provides up to 2 included reviews per hour; 1 remains after this review.

---

Walkthrough

Adds OsRelease to resolve Unraid OS branches and versions. Server state and update checks use the resolver. New PHP tests, a shell wrapper, and test-pipeline wiring cover fallback and validation behavior.

Changes

OS release resolution

Layer / File(s)	Summary
OS release resolver and test coverage plugin/source/.../include/os-release.php, plugin/tests/test-os-release.php, plugin/tests/test-os-release.sh	Adds branch and version resolution with validation, fallbacks, configurable paths, and automated tests.
Consumer integration plugin/source/.../include/state.php, plugin/source/.../include/UnraidCheck.php	Uses OsRelease::branch() for server state and update requests. Uses OsRelease::version() in the current-version fallback chain.
Test pipeline and review record plugin/package.json, .limetech/ai-review-markers/...	Adds the OS release test to the package test pipeline and records the final review marker.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant UnraidCheck
  participant OsRelease
  participant Filesystem
  participant UpdateRequest
  UnraidCheck->>OsRelease: Resolve branch and version
  OsRelease->>Filesystem: Read plugin, OSTree, and version files
  Filesystem-->>OsRelease: Return release metadata
  OsRelease-->>UnraidCheck: Return validated values
  UnraidCheck->>UpdateRequest: Send branch and current_version

Loading

Merge Risk: ⚪ Minimal · up to 46407

This change centralizes OS branch/version detection behind a new shared helper and wires it into server state and update-check requests, replacing ad-hoc shell/plugin lookups. Review confirmed the new file dependencies are packaged together (so the optional Connect plugin still deploys consistently) and that branch values are validated with a safe fallback before being used, so no new correctness or availability risk was found. The change appears safe to merge.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 31.25% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 16 functions across 5 files. (2 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the primary change: reading the OS version branch from updater configuration on OSTree hosts.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 31.25% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 16 functions across 5 files. (2 skipped: 2 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/ostree-os-version-branch

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{A rabbit reads each line,
The patch grows clear beneath the moon,
Small changes hop in place,
Tests guard the garden path,
Reviews bloom before the dawn.}

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 53.38%. Comparing base (d061525) to head (4640728).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2084      +/-   ##
==========================================
- Coverage   53.39%   53.38%   -0.02%     
==========================================
  Files        1044     1044              
  Lines       72705    72705              
  Branches     8406     8399       -7     
==========================================
- Hits        38821    38811      -10     
- Misses      33757    33767      +10     
  Partials      127      127              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

This plugin has been deployed to Cloudflare R2 and is available for testing.
Download it at this URL:

https://preview.dl.unraid.net/unraid-api/tag/PR2084/dynamix.unraid.net.plg

[github-actions]

🔄 PR Merged - Plugin Redirected to Staging

This PR has been merged and the preview plugin has been updated to redirect to the staging version.

For users testing this PR:

• Your plugin will automatically update to the staging version on the next update check
• The staging version includes all merged changes from this PR
• No manual intervention required

Staging URL:

https://preview.dl.unraid.net/unraid-api/dynamix.unraid.net.plg

Thank you for testing! 🚀

[Eli Bosley (elibosley)]

Not on main. This PR's squash commit (8300eb8) and its revert (#2085, 54d6647) were removed from main by a force-push back to d061525 on 2026-09-15: the unraid-api plugin is not used on Unraid 8, so the OSTree branch source belongs in Core (unraid/core#1221), not here. GitHub keeps the "Merged" badge, but no commit from this PR is on any protected branch. The branch codex/ostree-os-version-branch is kept only for archival.