mirror of https://github.com/got-feedBack/feedBack.git synced 2026-07-27 23:31:54 +00:00

Addresses 12 of 13 review comments from Copilot and CodeRabbit on
PR #332. One comment (no-manifests in validate-plugins.yml) is
declined and answered inline; the rest are applied here.

Substantive fixes:

- .github/workflows/validate-plugins.yml — add --noconftest to the
  schema-tests step. tests/conftest.py imports structlog at module
  level, but the CI job only installs requirements-test.txt
  (pytest/httpx/jsonschema), so pytest collection would fail at
  conftest import. The schema tests don't use shared fixtures, so
  skipping conftest is safe and avoids dragging the full runtime
  requirements into a 2 KB validation job. (Copilot)

- schema/plugin.schema.json — tighten the server_files regex on both
  settings.server_files and diagnostics.server_files to match the
  runtime _validate_relpath rules in plugins/__init__.py. The
  previous regex only blocked absolute paths, drive letters,
  backslashes, and "..". The runtime also rejects "//", "./",
  "/./", and leading-dotfile segments. Schema-valid manifests are
  now also load-time-valid. Verified the regex against 12 cases:
  the 3 in-tree manifests still validate. (Copilot)

- .claude/skills/plugin-validate/SKILL.md — add a per-iteration
  plugin_ok flag so we no longer print "OK <path>" after an earlier
  FAIL in the same manifest. Schema-pass + id-mismatch previously
  produced both FAIL and OK lines for one plugin. (CodeRabbit)

- docs/websocket-protocol.md — clarify song_info.tuning array length
  is source-dependent (typically 6 guitar, 4 bass, but extended-range
  GP imports can be 7/8/5/6). Recommend highway.getStringCount() for
  the authoritative count. Line 30 already said this; the table row
  on line 12 was the stale half. (CodeRabbit)

Trivial fixes:

- .claude/rules/plugin-author.md — "wants included" -> "wants to
  include" in the settings.server_files rule. (CodeRabbit)

- Markdown MD040 — add `text` language tags to 7 bare-fence code
  blocks across AGENTS.md, docs/PLUGIN_AUTHORING.md,
  docs/testing-plugins.md, docs/plugin-logging.md, .claude/README.md,
  .claude/agents/slopsmith-reviewer.md, and
  .claude/skills/plugin-validate/SKILL.md (two fences). (CodeRabbit)

Declined:

- .github/workflows/validate-plugins.yml no-manifests -> exit 0
  (CodeRabbit suggested exit 1). Plugins in this repo are in-tree,
  not submodules (no .gitmodules, git submodule status empty), and
  the workflow has a path filter on plugins/**/plugin.json so it
  only runs when a manifest actually changes. Exit 0 is correct.
  Answered inline on the PR.

Verification:
  pytest tests/test_plugin_schema.py -v --noconftest    # 8 passed
  python -c "import json,glob,jsonschema; s=json.load(open('schema/plugin.schema.json')); [jsonschema.validate(json.load(open(p)), s) for p in sorted(glob.glob('plugins/*/plugin.json'))]"
  # ok — all 3 in-tree manifests validate against tightened schema
Signed-off-by: Miguel_LZPF <mgcdreamer@gmail.com>

2026-06-18 00:38:51 -07:00

4.4 KiB

Raw Blame History

Highway WebSocket protocol reference

The highway WebSocket at /ws/highway/{filename}?arrangement={index} streams a song's chart data to the player. Plugins that drive their own highway, replace the renderer (see plugin-visualization-contracts.md), or consume the stream directly all read these frames.

Message order

Each connection receives the following JSON frames, roughly in this order:

Message	Shape	Description
`loading`	`{ type: 'loading', stage }`	Status/progress message during extraction or conversion.
`song_info`	`{ type, title, artist, arrangement, arrangement_index, arrangements, duration, tuning, capo, format, audio_url, audio_error, stems }`	Song metadata. `arrangements` is the full list for the switcher. `audio_url` is `null` when audio is unavailable, in which case `audio_error` is non-null; otherwise `audio_error` is `null`. `stems` is always present — an empty array for non-sloppak songs or sloppak songs with no split stems. `tuning` is an array whose length depends on the source arrangement (typically 6 for guitar, 4 for bass, but extended-range GP imports can be 7/8 for guitar or 5/6 for bass — use `highway.getStringCount()` for the authoritative count).
`beats`	`{ type, data: [{ time, measure }] }`	Beat timestamps with measure numbers.
`sections`	`{ type, data: [{ time, name }] }`	Named sections (Intro, Verse, Chorus, etc.).
`anchors`	`{ type, data: [{ time, fret, width }] }`	Fret zoom anchors.
`chord_templates`	`{ type, data: [{ name, frets: [6] }] }`	Named chord shapes.
`lyrics`	`{ type, data: [{ w, t, d }] }`	Syllables: `w`=word, `t`=time, `d`=duration. `-` joins to previous, `+` = line break.
`tone_changes`	`{ type: 'tone_changes', base, data: [{ time, name }] }`	Optional — tone change events relative to the arrangement base tone; only sent if tones were found.
`notes`	`{ type, data: [{ t, s, f, sus, ho, po, sl, bn, ... }] }`	Single notes.
`chords`	`{ type, data: [{ t, notes: [{ s, f, sus, ... }] }] }`	Chord events.
`phrases`	`{ type, data: [{ start_time, end_time, max_difficulty, levels: [...] }], total }`	Optional — per-phrase difficulty ladder for master-difficulty slider (slopsmith#48). Only sent when the source chart carries multi-level phrase data (PSARC / phrase-aware sloppak). Sent in chunks (`data` is a batch, `total` is the full count across messages) to avoid multi-MB single frames. Absent for GP imports and legacy sloppak; consumers must treat missing message as "single fixed difficulty — slider disabled".
`ready`	`{ type: 'ready' }`	All data sent — safe to finalize and start rendering.

Delivery guarantees

Message delivery is incremental. You may receive loading updates and lyrics before note/chord payloads. tone_changes comes after lyrics when present and may be omitted entirely. Do not finalize rendering until you receive ready.

Consumer notes

Tuning array length follows arrangement. 6 strings for guitar, 4 for bass, more for extended-range GP imports. Use highway.getStringCount() for the authoritative count rather than tuning.length (which can be the RS-XML padded 6-string form).
Chord templates are static. Every chord_id referenced by chords is guaranteed to be present in chord_templates.
Notes carry technique fields. ho = hammer-on, po = pull-off, sl = slide target, bn = bend amount. The full set is defined in lib/song.py.
Multiple connections are supported. Split-screen panels, lyrics panes, and jumping-tab panes each open their own WebSocket. By design — don't try to multiplex.

Phrase payload (slopsmith#48)

phrases.data is an array of phrase objects. Each phrase has start_time, end_time, max_difficulty, and levels. Each level has difficulty, notes, chords, anchors, handshapes — fully scoped to that phrase. The master-difficulty slider applies a single difficulty across all phrases by selecting the matching level.

PLUGIN_AUTHORING.md — guide index
plugin-visualization-contracts.md — bundle shape passed to draw()
sloppak-spec.md — sloppak format these messages are derived from
lib/song.py — server-side Note, Chord, Arrangement, Song data models

4.4 KiB Raw Blame History