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

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

1. Keep the Python safety harness stable: scan, plan, apply, uninstall, and backups.
2. Model one real plugin end to end with the current TOML lockfile and local asset planning.
3. Add a Nix function that fetches and unpacks one locked plugin asset into a normalized tree.
4. Generate a full plugin-set derivation for one Beat Saber version.
5. Teach `plugin-helper plan` to compare a Nix output tree against an instance.
6. Add `--activation-mode copy|symlink|materialize`.
7. 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?