113 lines
5.2 KiB
Markdown
113 lines
5.2 KiB
Markdown
---
|
|
name: beatsaber-plugin-update-auditor
|
|
description: Audit Beat Saber plugin-helper locks for available plugin updates and follow-up work. Use when the user asks to check all Beat Saber plugins for updates, compare locked mods against GitHub or BeatMods, review plugin/version compatibility tracking notes, identify PR/local/manual builds that need follow-up, or skip paid/private Patreon and Discord plugin sources during update checks. Read docs/notes/update-checks/<version>/ before the audit and add a new markdown file there when the audit finishes.
|
|
---
|
|
|
|
# Beat Saber Plugin Update Auditor
|
|
|
|
Use this skill from the `plugin-helper` repo to produce an update audit, not to
|
|
blindly update plugins. Keep public, private, and experimental sources distinct.
|
|
|
|
Before auditing, read the shared policy references:
|
|
|
|
- [repo-workflow.md](../references/repo-workflow.md) for repo root, `.venv`, `PYTHONPATH=src`, dirty worktree handling, and validation commands.
|
|
- [state-and-profiles.md](../references/state-and-profiles.md) for `.state`, profiles, install identity, instance selection, and checkout locations.
|
|
- [artifact-policy.md](../references/artifact-policy.md) for GitHub/BeatMods/private-source/checksum policy.
|
|
- [live-validation.md](../references/live-validation.md) only when reviewing smoke-test notes or launch failures.
|
|
|
|
## Workflow
|
|
|
|
1. Confirm repo context:
|
|
|
|
```bash
|
|
test -f pyproject.toml && test -d src/plugin_helper && test -d locks && test -d registry/plugins
|
|
git status --short
|
|
```
|
|
|
|
2. Choose the instance from the user request. If omitted, use the latest
|
|
available BSInstance unless the current task context clearly points at
|
|
another instance:
|
|
|
|
```bash
|
|
PYTHONPATH=src .venv/bin/python -m plugin_helper instances
|
|
```
|
|
|
|
3. Read the update journal for that Beat Saber version before drawing
|
|
conclusions. Journals live under `docs/notes/update-checks/<version>/`, one
|
|
directory per game version, with as many markdown files as needed (usually
|
|
one dated file per check). List the directory and read the recent files.
|
|
Treat them as prior findings, not as a substitute for a fresh audit. If the
|
|
directory does not exist yet, create it when recording this check.
|
|
|
|
4. Run the update audit with repo-local state unless the user explicitly targets
|
|
another configured profile:
|
|
|
|
```bash
|
|
PYTHONPATH=src .venv/bin/python -m plugin_helper --state-dir .state updates --instance <instance>
|
|
PYTHONPATH=src .venv/bin/python -m plugin_helper --state-dir .state updates --instance <instance> --json
|
|
```
|
|
|
|
The command checks ordinary GitHub locks, `beatmods-*` locks via BeatMods
|
|
verified metadata, skips `patreon/` and `discord/` sources, and marks local,
|
|
PR, manual, failed-trial, or pending-smoke entries as review items.
|
|
|
|
5. Read the active compatibility tracker before proposing updates for review
|
|
items. For the current migration notes, inspect:
|
|
|
|
```bash
|
|
sed -n '1,380p' docs/notes/install-and-verify-plugins-1.44.1.md
|
|
sed -n '1,220p' docs/notes/naluluna-mod-assistant.md
|
|
```
|
|
|
|
Follow up on rows marked failed, omitted, currently failed, smoke blocked,
|
|
manual resmoke pending, local build, PR build, or local/private. The lock
|
|
`reason` and `docs/notes/update-checks/<version>/` are the current record.
|
|
When an older note says a plugin was removed and the lock still has a local
|
|
or pull-request build, the lock wins. Correct that note in the same change.
|
|
Do not reinstall failed or omitted plugins unless the lock or journal
|
|
identifies a newer compatible source.
|
|
|
|
To see what BeatMods has for one mod, query `status=all` for that game
|
|
version and filter by mod name in the client. BeatMods ignores `search` and
|
|
`name`. An empty verified list is not the whole catalog.
|
|
|
|
6. For each public update candidate, inspect source notes before changing the
|
|
lock. Follow the shared artifact policy for GitHub-first sourcing and
|
|
BeatMods fallback cases.
|
|
|
|
7. Do not attempt automated public update checks for:
|
|
|
|
- `patreon/NalulunaModAssistant` or Naluluna bundles
|
|
- `discord/BeatSaberPlus` or BeatSaberPlus/ChatPlexSDK bundles
|
|
- other paid or closed-source plugin zips
|
|
|
|
Report them as skipped/manual follow-up only.
|
|
|
|
8. If the user asks to apply an update, switch to the `beatsaber-plugin-manager`
|
|
workflow for download, lock update, planning, apply, and smoketest.
|
|
|
|
## Output
|
|
|
|
Summarize in four groups:
|
|
|
|
- Public updates found: plugin, current version, candidate version, source.
|
|
- Current public locks: count only unless the user asks for every row.
|
|
- Review follow-ups: local builds, PR builds, failed trials, blocked smokes,
|
|
or notes saying compatibility work is pending.
|
|
- Skipped private sources: Patreon/Discord paid or closed-source packages.
|
|
|
|
Mention BeatMods/GitHub API errors separately from "no update found"; those are
|
|
unknowns, not proof that the plugin is current.
|
|
|
|
## Journal
|
|
|
|
After the audit, add a new markdown file. Do not rewrite earlier journal files.
|
|
|
|
```text
|
|
docs/notes/update-checks/<beat-saber-version>/<YYYY-MM-DD>.md
|
|
```
|
|
|
|
Use `<YYYY-MM-DD>-<short-slug>.md` when that date already has an entry. Keep
|
|
the note short: date, instance, the four summary groups, and any comparison
|
|
that changed a recommendation. A version directory may hold many files.
|