ux(install): narrate the plan and confirm each step - today it is "run install and trust us", including the sudo request #162

New issue

Closed

opened 2026-07-16 17:15:21 +00:00 by hexajon · 0 comments

hexajon commented

2026-07-16 17:15:21 +00:00

(Migrated from codeberg.org)

madtea install currently does everything silently: it picks a destination, may escalate via sudo, copies the binary, and sweeps stale copies off PATH - and the user's first visible signal is either the sudo password prompt (with no statement of what will be run or why) or the final success line. That is a trust-us UX, and the sudo half is the worst of it: an unexplained privilege request from a freshly downloaded binary is exactly what security-conscious users are trained to refuse.

Ask

Print the plan before acting: source binary (path + version), destination and why it was chosen (/usr/local/bin vs ~/.local/bin fallback, the Windows location), current PATH state, and any stale copies found that would be swept - then execute step by step, narrating each.
Announce sudo before requesting it: name the exact operation that needs elevation (the single copy/remove into the privileged directory) and let the user decline into the non-privileged fallback instead of aborting.
Confirm removals: stale-copy sweeping deletes files from PATH directories; list them and confirm (or gate the sweep behind the same consent).
Non-interactive path: --yes (and/or no-TTY auto-detection) keeps scripts and the README pipe-install working unattended with the plan still printed.

Acceptance

A fresh madtea install on a clean machine shows plan -> per-step narration -> summary; nothing happens that was not announced first.
The sudo prompt is preceded by a line naming the elevated operation; declining falls back to ~/.local/bin (with the PATH note) rather than failing.
Stale-copy deletions are listed before they happen and are consented to (interactively or via --yes).
Docs/README updated where the install flow is described.

`madtea install` currently does everything silently: it picks a destination, may escalate via sudo, copies the binary, and sweeps stale copies off PATH - and the user's first visible signal is either the sudo password prompt (with no statement of what will be run or why) or the final success line. That is a trust-us UX, and the sudo half is the worst of it: an unexplained privilege request from a freshly downloaded binary is exactly what security-conscious users are trained to refuse. ## Ask - **Print the plan before acting**: source binary (path + version), destination and why it was chosen (/usr/local/bin vs ~/.local/bin fallback, the Windows location), current PATH state, and any stale copies found that would be swept - then execute step by step, narrating each. - **Announce sudo before requesting it**: name the exact operation that needs elevation (the single copy/remove into the privileged directory) and let the user decline into the non-privileged fallback instead of aborting. - **Confirm removals**: stale-copy sweeping deletes files from PATH directories; list them and confirm (or gate the sweep behind the same consent). - **Non-interactive path**: `--yes` (and/or no-TTY auto-detection) keeps scripts and the README pipe-install working unattended with the plan still printed. ## Acceptance - A fresh `madtea install` on a clean machine shows plan -> per-step narration -> summary; nothing happens that was not announced first. - The sudo prompt is preceded by a line naming the elevated operation; declining falls back to ~/.local/bin (with the PATH note) rather than failing. - Stale-copy deletions are listed before they happen and are consented to (interactively or via --yes). - Docs/README updated where the install flow is described.

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

sixfold-space/madtea#162

No description provided.

Rows
Columns