plugin-helper Roadmap

This roadmap tracks ideas that are useful but not part of the first safe CLI slice.

Current Direction

The initial tool should stay conservative:

Python owns instance discovery, dry-run plans, activation, install state, uninstall, and UserData backups.
Release assets are selected through registry and lockfile data.
Mutating operations apply an explicit plan and record exact file hashes.
Nix packages plugin-helper, but does not directly manage the mutable Beat Saber tree.

This works well while Beat Saber is still launched from a Windows install or a mounted Windows filesystem.

Future: Nix-Orchestrated Plugin Sets

Once Beat Saber is running on Linux through Steam Proton, it may make sense to let Nix orchestrate the plugin payload itself.

The core idea:

Nix flake / plugin set
  fetch exact GitHub release assets
  verify hashes
  unpack and normalize Plugins/, Libs/, IPA/Pending/
  produce /nix/store/...-beatsaber-plugins-<game-version>/

plugin-helper
  run nix build .#pluginSets.<game-version>
  compare the resulting tree to the target Beat Saber instance
  create a normal dry-run plan
  copy or link files into the instance
  record activation state

In that model, the plugin folder effectively gets a reproducible lock:

flake.lock pins Nix inputs.
A plugin-set definition pins plugin repositories, tags, release assets, and hashes.
The generated Nix output is a canonical, immutable plugin tree for one Beat Saber version.
plugin-helper remains the safety layer around activation and rollback.

Why Wait For Proton

For the current dual-boot Windows path, a pure Nix-store plugin tree is awkward:

Windows cannot use /nix/store paths directly.
Linux symlinks inside a mounted Windows filesystem may not behave the way native Windows Beat Saber expects.
Some plugins may create or expect colocated mutable files.

When running through Proton on Linux, Nix-store outputs and symlink activation become much more practical. Even then, copy mode should remain available for plugins that expect writable colocated files.

Activation Modes

A future Nix-backed planner should support at least these activation modes:

copy: materialize files into the Beat Saber instance. Best compatibility, including mounted Windows trees.
symlink: link plugin files from the Nix output. Best reproducibility and cleanup on Linux/Proton.
materialize: link immutable files where safe and copy known-mutable files.

All modes should still produce the same kind of explicit plan before applying.

Proposed Milestones

Keep the Python safety harness stable: scan, plan, apply, uninstall, and backups.
Model one real plugin end to end with the current TOML lockfile and local asset planning.
Add a Nix function that fetches and unpacks one locked plugin asset into a normalized tree.
Generate a full plugin-set derivation for one Beat Saber version.
Teach plugin-helper plan to compare a Nix output tree against an instance.
Add --activation-mode copy|symlink|materialize.
Move compatibility and dependency metadata toward shared data that both Python and Nix can consume.

Open Questions

Should the human-edited source of truth be TOML, Nix, or TOML that generates Nix?
How should plugin-specific unpack rules be represented without making Nix expressions too noisy?
Which plugin files are known to need mutability after install?
Should the Nix output include BSIPA itself, or continue assuming BSIPA is provided by the game instance manager?
How should updates be proposed: Python querying GitHub, Nix update scripts, or both?

3.6 KiB Raw Blame History