plugin-helper/docs/notes/windows-compatibility.md

Windows Compatibility Tracker

Started: 2026-07-01

This note tracks the changes needed to run plugin-helper natively on Windows 11 with Python 3.13, separate from the Linux helper that manages mounted Windows instances.

Target Setup

• Install Python with:

  winget install --id Python.Python.3.13 --exact
  

• Use a separate checkout or working copy on the Windows partition.

• Use a Windows-specific config file:

  py -3.13 -m plugin_helper --config plugin-helper.windows.toml --profile windows instances
  

• Keep native Windows state local to that checkout, such as .state/, so it does not mix with the Linux .state or mounted-Windows .state-windows directories.

Current Compatibility Notes

• Core scan, plan, apply, uninstall, disable, and enable flows are mostly platform-neutral. They use pathlib, zipfile, shutil, JSON/TOML, and local file hashes.
• Native Windows defaults should not reuse Linux-mounted paths such as /home/pleb/Windows/.... A Windows-specific TOML file handles this for normal use.
• Multiple --instances-root values use os.pathsep; that means ; on Windows and : on Linux. Documentation should make this platform-specific.
• The Textual TUI dependency supports Windows and Python 3.13, but the best terminal target is Windows Terminal or a modern PowerShell host.

Work Items

• Add native Windows bootstrap support.
  • Current bootstrap assumes Proton.
  • Native Windows should run IPA.exe -n directly from the Beat Saber instance.
  • Timeout cleanup needs Windows-compatible process handling instead of POSIX process groups.
• Decide whether bootstrap-check should accept a recorded native Windows bootstrap state without a Proton launch history.
• Add Windows-aware default paths or keep requiring --config plugin-helper.windows.toml for native use.
• Update README examples for PowerShell:
  • editable install
  • --config plugin-helper.windows.toml
  • Windows path-list separator ;
• Add or adjust tests for Windows behavior.
  • Skip or rewrite the POSIX-only _run_ipa timeout test on Windows.
  • Add tests for native Windows config path resolution.
  • Add tests for native bootstrap command construction.
• Review backup and restore helpers on native Windows.
  • sync_windows_data_repo and restore_windows_data_repo should work with ordinary Windows paths.
  • The older tar-based backup_userdata helper uses NamedTemporaryFile in a way that may not be Windows-friendly if it becomes part of the CLI later.

First Manual Smoke

From the Windows checkout:

py -3.13 -m pip install -e .
py -3.13 -m plugin_helper --config plugin-helper.windows.toml --profile windows instances
py -3.13 -m plugin_helper --config plugin-helper.windows.toml --profile windows installed --instance 1.44.1

If instance discovery fails, verify the BSManager instance root in plugin-helper.windows.toml.