Add read-only Twister configuration UI

[oveddan]

Summary

• add mft-config ui, a small local web application for visually inspecting a connected MIDI Fighter Twister's complete configuration: a banked 4x4 knob grid, persistent active/inactive/detent colors, rotary and push MIDI channel/number mappings, switch action and movement mode, indicator/detent/super-knob settings, global settings, device identity/firmware details, compatibility warnings, and the complete raw JSON export
• support opening a previously exported JSON snapshot when hardware is unavailable, entirely client-side (no MIDI access on import)
• allow downloading the exact in-memory snapshot as JSON
• document the architecture and local dev workflow in docs/ui-architecture.md, and link it from the README

Architecture

A small local Node HTTP server (src/ui-server.ts) reuses the existing read-only exporter and protocol decoder that already back mft-config export, and serves dependency-free static HTML/CSS/JS (ui/). The browser never opens MIDI ports; it only talks to two endpoints on the local server: GET /api/devices and POST /api/export. This was chosen over a packaged desktop shell as the smallest approach that preserves reliable SysEx access (Node keeps the native MIDI bindings) while keeping the safety boundary in one place.

Safety boundary

The read-only guarantee is enforced at the transport layer, not just in the UI:

• the server depends on RtMidiReadOnlyBackend, which exposes only discover/connect — its type has no connectForApply, so it cannot construct the separate write-capable connection the CLI's apply command uses
• every outbound SysEx frame is independently validated by assertReadOnlyRequest immediately before the native MIDI output call, allowing only the Universal Identity request, global pull (0x02), and encoder bulk-pull (0x04/0x01) — configuration writes (0x01), system/reset/bootloader-shaped commands, and any other command are rejected with a thrown error
• the HTTP surface has exactly two routes; there is no plan, apply, write, reset, system, or bootloader route, and unknown /api/* paths return 404 without ever opening a MIDI connection

Automated tests assert both layers (test/ui-server.test.ts):

• the read-only backend's public shape has no apply-connection constructor
• the transport guard blocks mutating SysEx (0x01 write, malformed bulk push, 0x03 system command) before it reaches the MIDI output, and still permits reads
• a full snapshot export uses only allowlisted read requests (60+ frames asserted individually)
• requests to apply, plan, write, reset, bootloader, and system API paths all 404 and never open a connection
• permission, malformed-response, partial-read, and disconnected-device errors are classified and reported with distinct HTTP status/error codes

Validation

• npm run build — clean TypeScript build
• npm test — 21/21 tests pass, including the 5 UI-server tests above
• npm run test:package — packed tarball smoke test passes with the ui/ assets and docs/ui-architecture.md included
• manually started node dist/ui-server.js with no hardware attached: index page and /api/devices (empty array) respond 200, and a mutation-shaped route (/api/apply) responds 404 without opening a MIDI connection

Closes #1

Greptile Summary

The PR adds a local read-only Twister configuration viewer, supporting live MIDI exports and offline JSON snapshots, while moving apply state into a per-user directory.

• Adds a dependency-free browser UI and local HTTP server.
• Adds a transport-level read-only MIDI backend and request allowlist.
• Extends packaging, tests, documentation, and CI for the new UI.
• Adds per-user journal and backup storage.

Confidence Score: 1/5

The PR is not safe to merge until stale device selection, legacy consumed-plan detection, and mutable CI action references are fixed.

Export requests can still omit device identity and silently select another controller after discovery ordering changes; apply ignores legacy completion records and can repeat consumed writes; CI continues to execute actions through mutable tags.

Files Needing Attention: src/ui-server.ts, ui/app.js, src/cli.ts, src/journal.ts, .github/workflows/ci.yml

Important Files Changed

Filename	Overview
src/ui-server.ts	Adds the read-only HTTP surface and export orchestration, but its attempted stale-device protection remains bypassable when optional identity fields are omitted.
src/midi.ts	Adds a restricted backend whose outbound frames are checked against the read-only SysEx allowlist.
ui/app.js	Implements live discovery, export, snapshot validation, rendering, import, and download, but conditionally omits device-selection metadata.
src/cli.ts	Adds the UI command and per-user state paths, while the previously reported legacy-journal compatibility gap remains.
.github/workflows/ci.yml	Adds multi-platform checks and package smoke tests, while executable actions remain referenced through mutable tags.
README.md	Documents the UI and per-user state location, though the previously reported obsolete backup-path note remains.

Sequence Diagram

sequenceDiagram
  participant Browser
  participant Server as Local UI server
  participant MIDI as Read-only MIDI backend
  participant Device as MIDI Fighter Twister
  Browser->>Server: GET /api/devices
  Server->>MIDI: discover()
  MIDI->>Device: Identity request
  Device-->>MIDI: Identity response
  MIDI-->>Server: Device descriptors
  Server-->>Browser: Device list
  Browser->>Server: POST /api/export
  Server->>MIDI: discover() and connect()
  MIDI->>Device: Allowlisted configuration pulls
  Device-->>MIDI: Global and encoder responses
  MIDI-->>Server: Complete snapshot
  Server-->>Browser: JSON snapshot

Loading

Prompt To Fix All With AI

### Issue 1
src/ui-server.ts:166-168
**Optional identity check permits reselection**

When an export request omits `inputPort` and `outputPort` after device discovery ordering changes, the server skips the identity comparison and exports whichever controller now occupies `deviceIndex`, causing the UI to return another Twister's configuration.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (2): Last reviewed commit: "fix: address adversarial review findings..." | Re-trigger Greptile}

Greptile also left 1 inline comment on this PR.

[greptile-apps]

Workflow actions use mutable tags

The workflow executes actions/checkout@v4 and actions/setup-node@v4 rather than immutable commit SHAs, so upstream tag movement can change code executed with repository read access or alter the checkout and toolchain used by subsequent checks.

How this was verified: Both executable action references use mutable @v4 tags and the workflow grants contents: read.

Prompt To Fix With AI

This is a comment left during a code review.
Path: .github/workflows/ci.yml
Line: 30-31

Comment:
**Workflow actions use mutable tags**

The workflow executes `actions/checkout@v4` and `actions/setup-node@v4` rather than immutable commit SHAs, so upstream tag movement can change code executed with repository read access or alter the checkout and toolchain used by subsequent checks.

**How this was verified:** Both executable action references use mutable `@v4` tags and the workflow grants `contents: read`.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 28ed467b60

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Correct the MF64 hue table for blue and teal

When an MF64 snapshot contains canonical teal (index 33) or blue (index 45), this table makes the viewer render them as hsl(78 …) and hsl(0 …)—yellow-green and red, respectively—even though src/planner.ts maps those indices to teal and blue. Since the knob grid is intended to visually identify stored colors, these common MF64 settings are presented as the wrong colors; update the corresponding hue groups to match the palette.

Useful? React with 👍 / 👎.

[oveddan]

Follow-up: adversarial review fixes

An Opus adversarial review of this branch found six correctness/robustness issues (the write-safety boundary itself was verified solid and left untouched). All six are addressed in c5c32d8:

1. Malformed offline snapshot corrupting the viewer — assertSnapshot now validates globals.colorMap/superKnob/brightness/animationChannels/sleep, device.midiPorts, firmware identityBytes, and capturedAt. renderSnapshot is now transactional: it only commits state.snapshot and unhides the viewer once every render function succeeds; on failure it rolls back to the previous good snapshot (or the empty state) instead of leaving a spliced mix of new/old content with a corrupt snapshot wired to Download JSON.
2. No serialization on /api/export — added a single-flight guard; a second concurrent export now gets 409 EXPORT_IN_PROGRESS instead of racing to open the same MIDI ports.
3. No Host validation — the server now rejects requests whose Host header doesn't name it (400 INVALID_HOST), closing the cross-origin/DNS-rebinding path. MFT_CONFIG_UI_HOST is now validated/warned-on in the CLI when non-loopback.
4. RtMidiPorts.send lost its guard — re-added as a constructor-injected guard defaulting to assertReadOnlyRequest, so the innermost layer is safe by default even if a future call site bypasses the wrapper classes.
5. Response-matching regression in src/exporter.ts — pullGlobals/pullDeviceId/pullEncoderData once again check the DJTT vendor header before trusting the command byte.
6. deviceIndex TOCTOU — /api/export now also accepts the inputPort/outputPort names the browser saw at discovery time and rejects (409 DEVICE_LIST_CHANGED) if the freshly re-discovered device at that index no longer matches, instead of silently exporting a different (still read-only) device after a replug.

Added test/ui-app.test.ts (jsdom-backed) covering #1, and extended test/ui-server.test.ts with coverage for #2, #3, and #6. npm run build && npm test passes (28/28).

[greptile-apps]

Optional identity check permits reselection

When an export request omits inputPort and outputPort after device discovery ordering changes, the server skips the identity comparison and exports whichever controller now occupies deviceIndex, causing the UI to return another Twister's configuration.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/ui-server.ts
Line: 166-168

Comment:
**Optional identity check permits reselection**

When an export request omits `inputPort` and `outputPort` after device discovery ordering changes, the server skips the identity comparison and exports whichever controller now occupies `deviceIndex`, causing the UI to return another Twister's configuration.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.