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.

• Copy and adjust the Windows config template:

  Copy-Item plugin-helper.windows.toml.example plugin-helper.windows.toml
  

• 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 Linux-managed state 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 do 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. README documents this platform-specific separator.
• 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

Done

• Add native Windows bootstrap support.
  • bootstrap auto-detects Windows and runs IPA.exe "Beat Saber.exe" -n directly.
  • --native forces native mode; --proton remains for Linux/Proton installs.
  • Timeout cleanup uses process.terminate() / process.kill() on Windows instead of POSIX process groups.
  • Bootstrap state records bootstrapMode: "native" or "proton".
• bootstrap-check accepts recorded native Windows bootstrap state without Logs/_latest.log when IPA.exe "Beat Saber.exe" -n completed successfully (ipaExitCode == 0, not timed out).
• Add Windows-aware default paths when no config is present: ~/BSManager/BSInstances and %LOCALAPPDATA%/plugin-helper. Normal native use still prefers --config plugin-helper.windows.toml.
• Add --config and --profile CLI flags with [[profiles]] TOML support.
• Add plugin-helper.windows.toml.example as the committed template.
• Update README examples for PowerShell, profiles, and the ; path separator.
• Add tests for profile config resolution, native bootstrap command construction, native bootstrap health checks, and platform-gated IPA timeout behavior.
• Review backup and restore helpers on native Windows.
  • sync_windows_data_repo and restore_windows_data_repo work with ordinary Windows paths; infer_windows_appdata_path now keys off BSManager rather than the first Users path segment.
  • backup_userdata no longer uses NamedTemporaryFile while the tar archive is open, which fixes Windows permission errors.

Remaining

• Run the first manual smoke on a native Windows checkout (see below).
• Consider whether the menu TUI needs Windows-specific setup hints when plugin-helper.windows.toml is present but --profile was omitted.

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.

Implementation Map

Area	Files
Config profiles and Windows defaults	src/plugin_helper/config.py
Native bootstrap and process handling	src/plugin_helper/bootstrap.py
Native bootstrap health gate	src/plugin_helper/bsipa.py
CLI flags	src/plugin_helper/cli.py
Windows config template	plugin-helper.windows.toml.example
Tests	tests/test_plugin_helper.py