From 7db56e600f60da40b2e6353b75c422982f098634 Mon Sep 17 00:00:00 2001 From: Brian Krabach Date: Sat, 4 Apr 2026 03:29:36 -0700 Subject: [PATCH] =?UTF-8?q?docs:=20TLS=20nudge=20design=20=E2=80=94=20cont?= =?UTF-8?q?extual=20hints=20in=20doctor=20+=20service=20install?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/plans/2026-04-04-tls-nudge-design.md | 67 +++++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 docs/plans/2026-04-04-tls-nudge-design.md diff --git a/docs/plans/2026-04-04-tls-nudge-design.md b/docs/plans/2026-04-04-tls-nudge-design.md new file mode 100644 index 0000000..c816d67 --- /dev/null +++ b/docs/plans/2026-04-04-tls-nudge-design.md @@ -0,0 +1,67 @@ +# 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.