Add plugin helper with agent skill for updating plugins

2026-06-14 10:26:22 -07:00
parent a9881ebec4
commit caaa4a6558
23 changed files with 1604 additions and 0 deletions
@@ -0,0 +1,80 @@
+# 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?