diff --git a/README.md b/README.md index 73e64b5..ff0c0cd 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,8 @@ If `XDG_STATE_HOME` is not set, the state directory defaults to: Override the instance root with `--instances-root`, `PLUGIN_HELPER_INSTANCES_ROOT`, or `plugin-helper.local.toml`. To search -multiple explicit roots, separate them with `:`. +multiple explicit roots, separate them with `:` on Linux/macOS or `;` on +Windows. Override the state directory with `--state-dir`, `PLUGIN_HELPER_STATE_DIR`, or `plugin-helper.local.toml`. @@ -73,6 +74,45 @@ state_dir = "~/Windows/Users/pleb/ops/plugin-helper/.state" CLI flags override environment variables, environment variables override local config, and local config overrides built-in defaults. +## Native Windows + +For a separate checkout on a Windows partition, copy the Windows example config +and adjust paths if needed: + +```powershell +Copy-Item plugin-helper.windows.toml.example plugin-helper.windows.toml +``` + +`plugin-helper.windows.toml` is ignored by git. It uses profile entries: + +```toml +[[profiles]] +id = "windows" +label = "Native Windows BSManager" +instances_root = "~/BSManager/BSInstances" +state_dir = ".state" +``` + +Run commands with `--config` and `--profile` so native Windows state stays in +that checkout's `.state/` directory. If `plugin-helper.windows.toml` has only +one `[[profiles]]` entry, that profile is selected automatically when +`--profile` is omitted: + +```powershell +py -m venv .venv +.\.venv\Scripts\Activate.ps1 +py -m pip install -e . +py -m plugin_helper menu +py -m plugin_helper --config plugin-helper.windows.toml --profile windows installed --instance 1.44.1 +``` + +On native Windows, `bootstrap` runs `IPA.exe -n` directly instead of through +Proton. `bootstrap-check` accepts a recorded native bootstrap without requiring +`Logs/_latest.log` when `IPA.exe -n` completed successfully. + +When no config file is present on Windows, defaults are +`~/BSManager/BSInstances` and `%LOCALAPPDATA%/plugin-helper`. + ## Commands For normal use, run the Textual menu from the repo root: @@ -170,9 +210,10 @@ custom content or non-obvious user choices rather than pure cache data. arguments such as `--no-yeet fpfc` can make the game fail command-line parsing after BSIPA and plugins have already loaded. - BSIPA is managed as a first-class bootstrap phase. The `bootstrap` command - applies the locked `bsipa` root archive, runs `IPA.exe -n` through Proton, and - records every bootstrap-relevant file under root `IPA.exe*`, `winhttp.dll`, - `Libs/`, and `IPA/`, including backups created during patching. + applies the locked `bsipa` root archive, runs `IPA.exe -n` (natively on + Windows or through Proton on Linux), and records every bootstrap-relevant + file under root `IPA.exe*`, `winhttp.dll`, `Libs/`, and `IPA/`, including + backups created during patching. - If an instance lockfile includes `bsipa`, ordinary plugin plans require a recorded bootstrap state plus a `Logs/_latest.log` that shows BSIPA startup. Use `bootstrap-check` before planning a batch when you want a quick gate. diff --git a/docs/notes/windows-compatibility.md b/docs/notes/windows-compatibility.md index a655760..c4c6383 100644 --- a/docs/notes/windows-compatibility.md +++ b/docs/notes/windows-compatibility.md @@ -15,6 +15,12 @@ Windows instances. ``` - 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 @@ -30,38 +36,48 @@ Windows instances. - 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 +- 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. Documentation should make this platform-specific. + 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. - - 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. + - `bootstrap` auto-detects Windows and runs `IPA.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 -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` 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. + - `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 @@ -75,3 +91,14 @@ py -3.13 -m plugin_helper --config plugin-helper.windows.toml --profile windows 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` |