Plan for Windows compat

2026-07-01 13:24:18 -07:00
parent c0a167dc67
commit 1be1353835
2 changed files with 78 additions and 0 deletions
@@ -0,0 +1,77 @@
+# 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:
+
+  ```powershell
+  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:
+
+  ```powershell
+  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:
+
+```powershell
+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`.