Brian Krabach
68 lines
2.7 KiB
Markdown
68 lines
2.7 KiB
Markdown
# 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.
|