TLS Nudge in Doctor and Service Install — Design Addendum

Goal

Surface TLS setup guidance to users at the right moments so they don't have to discover muxplex setup-tls on their own.

Background

After installing muxplex and running muxplex service install, the service works on localhost — but clipboard doesn't work from other devices over plain HTTP. Users currently have to discover muxplex setup-tls on their own; there's no guidance pointing them to it. The doctor command already shows a TLS warning, but it doesn't tell users how to fix it.

Approach

Contextual, non-blocking hints at the moments users are already looking at output. No wizard, no prompts, no blocking. Just a nudge with the exact command to run.

Three approaches were considered:

A. Nudge in doctor + service install (chosen) — one-liner hints that show the fix command. Non-blocking; user decides when to act.
B. Interactive first-run wizard — rejected; too heavy for a single optional command.
C. Auto-run setup-tls on service install — rejected; TLS setup may need sudo or has visible effects (changes URL to HTTPS), so the user should opt in explicitly.

Components

1. `doctor` output — enhanced TLS warning

Current:

  ! TLS: disabled (clipboard requires HTTPS on non-localhost)

New:

  ! TLS: disabled — clipboard won't work on remote devices
    Run: muxplex setup-tls

Condition: Only show when host != 127.0.0.1 (network access) AND TLS is not configured. On localhost-only setups, TLS is unnecessary and the nudge is hidden.

2. `service install` output — tip after service start

After the "Service started" line and the URL, if host != 127.0.0.1 and TLS is not configured, append:

  Tip: Enable HTTPS for clipboard support: muxplex setup-tls

One line, just a tip. Disappears once TLS is set up.

3. `upgrade` output — free via `doctor`

upgrade already calls doctor for its verification block, so the enhanced TLS warning shows there naturally. No extra code needed.

Files to Modify

muxplex/cli.py — doctor() function: update TLS warning text and add "Run:" hint line
muxplex/cli.py — service_install() output: add tip line after "Service started"
muxplex/tests/test_cli.py — tests for the nudge text appearing/not-appearing based on host and TLS config

Testing Strategy

Test that the nudge appears when host=0.0.0.0 and TLS is not configured
Test that the nudge does NOT appear when host=127.0.0.1
Test that the nudge does NOT appear when TLS is already configured
Test that service install includes the tip line under the right conditions

Effort Estimate

~1 hour — small, well-scoped change to two output blocks.

2.7 KiB Raw Blame History