# 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.
- Copy and adjust the Windows config template:

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

- 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 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:

```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`.

## 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` |