Skip to content

Major Improvements and Cool Stuffs - #44

Open
mr-pmillz wants to merge 22 commits into
ygelfand:mainfrom
mr-pmillz:main
Open

mr-pmillz wants to merge 22 commits into
ygelfand:mainfrom
mr-pmillz:main

Conversation

@mr-pmillz

Copy link
Copy Markdown

This PR expands plexctl’s terminal playback, music support, and library browsing, adds access to friends’ shared libraries, and improves navigation, reliability, documentation, and CI.

  • Complete music browsing: Navigate artists → albums → tracks with album artwork, pagination, and soundtrack/compilation contributions.
  • Album and artist queues: Play every available track from the TUI or CLI, preserving track order and updating titles, progress, and Plex playback reporting for each track.
  • Integrated music player: Listen while browsing, with keyboard and mouse controls for pause, seek, volume, mute, and stop.
  • Live audio visualizations: Add stereo waveforms, spectrum, mirrored spectrum, and compact controls inside the TUI. Separate mpv windows and terminal video support CQT, spectrum, waves, and vectorscope visualizations.
  • Terminal video: Add automatic selection and explicit overrides for Kitty, Sixel, and true-color text output, checking both terminal capabilities and mpv’s available outputs.
  • Selectable video modes: Support suspended fullscreen playback or video over the active TUI. Overlay playback hides during dialogs and restores afterward, including paused frames.
  • Visible Kitty playback controls: Add clickable controls, a draggable timeline, volume, mute, subtitles, playback speed, and keyboard focus navigation.
  • Native artwork: Render posters and album covers using Kitty/Ghostty Unicode placeholders or Sixel, with a half-cell text fallback and configurable renderer selection.
  • Rendering reliability: Preserve artwork proportions, clip images to visible areas, restore graphics after playback, and bound cached terminal images. Add a centered, configurable Sixel video width cap.
  • tmux and SSH support: Handle graphics passthrough, portable image transport, and temporary pane zooming with restoration of the previous layout and settings.
  • Friends Libraries: Discover shared servers and browse, search, and play their accessible libraries. Keep credentials, caches, artwork, and playback reporting scoped to the originating server and active Plex user.
  • Live search: Combine immediate local fuzzy matches with Plex server results, including artists, albums, and tracks, without requiring an index first.
  • Navigation improvements: Add mouse interaction throughout the TUI, directional pane focus, an accessible A–Z rail, letter jumps, page navigation, and consistent Vim-style table controls. Fix poster-row alignment and focus after navigation.
  • Playback robustness: Improve IPC synchronization, queue transitions, reconnect handling, cancellation, startup error reporting, and shutdown. Automatically retry failed graphics startup with text output; CLI playback exits when finished and responds to Ctrl+C.
  • mpv setup: Add compatibility checks and guided installation/update support with explicit user confirmation.
  • Configuration and documentation: Expose playback, artwork, and visualization preferences through Settings, configuration, and applicable CLI/environment overrides. Update the README, TUI/configuration guides, token instructions, and generated CLI reference.
  • Tooling and CI: Raise the Go requirement to 1.27.2, refresh Go and documentation dependencies, apply Go modernizations, resolve lint findings, and SHA-pin GitHub Actions. Add race/shuffle tests, integration tests, linting, module checks, and vulnerability scanning.

Validation includes passing race-enabled unit/integration tests, real-mpv playback and visualization tests, Linux builds, a Windows cross-build, clean standard/integration lint runs, module verification, and the documentation build. Vulnerability scanning found no reachable vulnerabilities. Plex tests use local fixtures; visual compatibility across terminal emulators and live-server behavior require manual acceptance testing.

Add Kitty/Sixel terminal video, a renderer chooser, native high-resolution
Kitty posters, and mouse navigation and playback controls. Preserve tmux
pane layouts and correctly detect direct terminals with inherited tmux
variables.

Support artist/album/track navigation and resolve music containers to
playable tracks. Use named mpv loadfile arguments for compatibility with
older mpv releases and report command failures.

Validated with race-enabled integration tests, go vet, cross-platform
builds, and live Kitty/tmux QA for graphics, mouse controls, and music.
Restore content focus after search results, alphabet jumps, library cycling,
and right-click Back so subsequent keys operate on the destination view.

Validate regression tests and mouse/keyboard navigation in a separate tmux
pane inside Kitty using a local Plex fixture.
Handle parse, output, registration, and cleanup failures instead of discarding
them. Reject malformed or overflowing history durations, preserve existing
icons on invalid glyph input, and simplify the static-analysis findings.

Keep standard linters enabled with unlimited issue reporting. Exclude only
npm dependency directories, which contain unrelated third-party Go examples.

Validation: golangci-lint v2.14.0 reports zero issues with default and integration
build tags; go test -race -shuffle=on -count=1 -tags=integration ./... passes.
Upgrade Go 1.25.6 -> 1.27.2 and document the macOS 13 minimum and development
checks. Tidy consolidates existing direct and indirect require blocks.

Upgrade golang.org/x/text v0.37.0 -> v0.43.0, the latest stable release resolved
2026-10-10 through the Go module proxy. govulncheck reproduced GO-2026-5970 on
untouched HEAD: AlphabetTitle calls the affected normalization API. Invalid
UTF-8 can trigger an infinite loop in old releases; this removes the affected
dependency. Canonical JSON input normally replaces invalid UTF-8 already.

The module graph requires these accompanying upgrades:
- x/crypto v0.51.0 -> v0.57.0
- x/mod v0.35.0 -> v0.41.0
- x/net v0.55.0 -> v0.59.0
- x/sync v0.20.0 -> v0.24.0
- x/sys v0.45.0 -> v0.48.0
- x/term v0.43.0 -> v0.46.0
- x/tools v0.44.0 -> v0.51.0

Sources: https://go.dev/doc/devel/release#go1.27.2
https://pkg.go.dev/vuln/GO-2026-5970
golang/text@v0.37.0...v0.43.0

Validation: module verification/tidy, race-enabled integration tests, lint,
five GoReleaser platform builds, and zero reachable govulncheck findings.
Rollback: restore Go 1.25.6 and the old module versions listed above.
Resolve approved stable major upgrades from upstream releases on 2026-10-10;
verify each full SHA against its upstream release tag with git ls-remote:
- actions/checkout v4 (docs), v5 (release) -> v7.0.1
- actions/setup-node v4 -> v7.1.0
- actions/setup-go v6 -> v7.0.0
- actions/configure-pages v4 -> v6.0.0
- actions/upload-pages-artifact v3 -> v5.0.0
- actions/deploy-pages v4 -> v5.0.1
- goreleaser/goreleaser-action v6 -> v7.2.3

The Node 24 action runtimes are compatible with hosted Ubuntu runners. Keep
explicit npm caching and preserve hidden Pages export files across the upload
action's changed default. Select the release compiler from go.mod.

Security verdict: defensive upgrades and immutable pins. The checkout fork-head
restriction does not affect our push/dispatch release and Pages workflows;
there are no privileged PR triggers. Disable persisted checkout credentials
and grant Pages/OIDC and release write permissions only to publishing jobs.

Add read-only PR checks for race-enabled tests, lint, module integrity, builds,
and govulncheck with exact analysis-tool versions compiled using project Go.

Validation: actionlint and YAML/pin checks; Node 24 docs build (47 pages) and
Pages archive; GoReleaser v2.18.3 config check and five snapshot build targets.
Workflows were validated locally; no remote workflow was triggered.
Rollback: restore the action majors listed above, Go 1.25 release selection,
and remove the new CI workflow.
Reconcile upstream docs Dependabot PRs ygelfand#33 and ygelfand#35-40 on current fork
HEAD. Regenerate the npm lockfile instead of copying the upstream diff.
Keep the existing package.json semver ranges and lockfile format.

Resolved targets (official npm registry checked 2026-10-10):
- next and @next/env: 16.3.0 -> 16.4.0
- @next/eslint-plugin-next and eslint-config-next: 16.1.6 -> 16.4.0
- sharp and platform binaries: 0.35.3 -> 0.35.5
- sharp-libvips platform binaries: 1.3.2 -> 1.3.4
- nanoid: 3.3.17 -> 3.3.20
- js-yaml: 4.3.1 -> 4.3.2
- dompurify: 3.4.13 -> 3.4.16
- @humanfs/node: 0.16.7 -> 0.16.8
- @humanfs/core: 0.19.1 -> 0.19.2; add required @humanfs/types 0.15.0
- brace-expansion: 1.1.18 -> 1.1.21 and 5.0.9 -> 5.0.12
- remove the obsolete brace-expansion 2.1.4 copy as the updated
  TypeScript ESLint tree reuses minimatch 10 and brace-expansion 5

Use newer compatible targets than upstream for Next.js (16.3.4), sharp
(0.35.4), and nanoid (3.3.18), including subsequent security fixes.
Align Next.js lint companions with its runtime; this refreshes their
TypeScript ESLint family 8.54.0 -> 8.71.1, React Hooks plugin
7.0.1 -> 7.1.1, Babel 7.29.x, and browser compatibility data. The parser
now requires a nested eslint-visitor-keys 5.0.1; Node 24 satisfies its
engine requirement. @swc/helpers moves 0.5.15 -> 0.5.23 with Next.js.
No direct major upgrades or release-channel changes.

Security verdict: the lockfile contained affected dependency versions;
these upgrades clear audit findings for all seven target groups and
Babel. Published docs use output: export and unoptimized images, so the
Next.js server/cache/image-optimizer advisories do not affect that static
deployment: defensive bump. No project usage of IN_PLACE sanitizer
hooks, humanfs copyAll, nanoid custom generators, or untrusted YAML/glob
input was found. Audit improves from 25 to 17 findings (critical 1 -> 0),
with no new findings. The remaining advisories predate this update.

Validation: npm ci on Node 24.21.0/npm 11.19.0; npm ls for every target;
source ESLint (existing no-img-element warning); production build with
all 47 exported routes unchanged and referenced assets present; browser
homepage, TUI Guide and CLI play navigation with no console errors;
git diff --check. Default ESLint already includes generated out/ files
and fails on the original lockfile; source lint ignores out/**.

Upstream PRs are already merged; their states were not changed.
Rollback: revert this commit to restore the previous versions above,
then run npm ci in docs.
Lowercase h was intercepted by the global Home shortcut before reaching
poster lists and grids. Use uppercase H for Home, restore content focus
when it is invoked, and update help and the TUI guide.

Moving between Home rows now selects the poster in the same visible
column using each row's own horizontal offset, instead of restoring its
previous cursor. Short rows clamp to the nearest available poster.
Resizing a horizontal row also keeps its selected poster visible.

Regression tests reproduced the intercepted h key, stale row selections,
and selection disappearing after resize before the fix. Cover both key
families, independent offsets, short rows, edges, and the Home shortcut.

Validation: race/shuffled integration suite; standard and integration
golangci-lint (0 issues); Go build; 47-page docs build; 17 selection
checks and the Home shortcut in a separate tmux pane using a local Plex
fixture. Rebuild and install the binary for the corrected key bindings.
Move right from content with Ctrl+L, select a letter with j/k or arrows,
and press Enter to jump and return to content. Ctrl+H or Escape cancels.
Preserve the visible letter cursor through resizing and nested music views,
and release focus when the active view no longer has a visible rail.

Document the controls and cover focus routing, cancellation, folded mouse
targets, library resizing, and artist/album/track navigation with tests.

Validation: race/shuffled integration suite, both golangci-lint modes,
docs build, and 12 keyboard QA scenarios in an isolated tmux pane.
Allow h/l and arrow keys to pan wide tables without changing the selected
row. Size status tables to the content pane so j/k keep selection visible
and horizontal scrolling can reveal every column. Preserve mouse targeting
and support Shift+wheel and horizontal wheels.

Put search Status in a scrollable viewport, retain navigation during
indexing, and clamp offsets after resizing. Correct reversed j/k help
labels and document the controls across content views.

Validation: full race/shuffled integration suite, both golangci-lint modes,
docs build, and 11 tmux QA checks with local sessions/history/tasks data.
Queue full albums and artists with ordered per-track Plex reporting, cancellation, and reconnect support. Include soundtrack and compilation contributions.

Add a poster renderer registry with Ghostty and Sixel support, live TUI video overlays, Sixel sizing, automatic text fallback, and selectable mpv music visualizers.

Document settings and CLI flags, and cover playback, rendering, and shutdown with regression and real-mpv integration tests.
Address adversarial review findings in credential handling, URL validation, configuration persistence, caches, malformed metadata, asynchronous views, and subprocess lifetimes.

Add regression coverage, update vulnerable dependencies, and document validation and remaining upstream documentation advisories.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant