Skip to content

Nice errors: one plain line, and a hint - #56

Merged
2styx2 merged 6 commits into
devfrom
feat/nice-errors
Nov 10, 2026
Merged

2styx2 merged 6 commits into
devfrom
feat/nice-errors

Conversation

@2styx2

@2styx2 2styx2 commented Nov 10, 2026

Copy link
Copy Markdown
Owner

Errors now read like a normal CLI: one line, roster: SUBJECT: what happened, and a hint: line when there's a clear next step. Output from bw, keyctl, ssh, sudo, curl, ssh-keygen and tmux no longer reaches the terminal raw: known failures become roster's own words, anything else shows only the tool's last line, trimmed, colour codes stripped.

What changes

  • src/errors.rs (new, ~200 lines) is the one place that turns a tool's stderr into a message: ssh, bw, sudo, curl, plus hint, last_line, io and spawn. Modules call it instead of matching on their own.
  • Vault: a wrong master password is roster: vault unlock: wrong master password. A missing item is no vault item named "X" with a hint about the name or bw:ID. Several matches, a locked vault and bw not logged in each get their own message. keyctl missing or refusing the key says so in plain words.
  • run: a Host's stderr is held back until its stdout starts, or until the Host ends. If ssh failed (exit 255) or sudo refused, roster says why instead, e.g. can't reach 10.0.0.6:22 (timed out) with the hint roster check HOST, or sudo rejected the password from bw:ITEM. Otherwise the held lines show, labelled as before. --json is unchanged.
  • setup, Mesh, undo and check use the same ssh messages: unreachable, refused, unresolved, key or password not accepted, host key changed (the hint gives the ssh-keygen -R line; roster never runs it), host key unknown. check keeps one line per Host, so it shows the message without the hint.
  • web: curl's exit code decides the message: resolve, refused, timeout, untrusted certificate (with the verify: false / -k hint), empty reply. HTTP 401/403 reads login refused (HTTP 401). Passwords and tokens stay masked.
  • Inventory: if there's no roster.yml, the error says where roster looked and how to name a file (-c, ROSTER_CONFIG). A missing file no longer shows (os error 2). Bad YAML puts the line number up front.
  • Usage errors: (see roster -h) becomes a hint line. An unknown command also points at roster help plugins.
  • pick: fzf or tmux missing or failing gets a message. fzf keeps the terminal, the same way ssh does.
  • "N Hosts not done" names the command (setup: / setup --undo:) and puts the rerun in a hint. run's summary line is now roster: run: failed on …, and a skipped Host is roster: HOST: skipped: unreviewed, as in setup.
  • Exit codes are unchanged.

Docs

roster.1 has a new DIAGNOSTICS section that lists each message and its hint; tests/man_page.rs lists each one too. The tutorial's troubleshooting table matches the new messages. Version is 0.7.11.

Tests

The fakes can now fail the way the real tools do:

  • FAKE_SSH_ERROR (with FAKE_SSH_DOWN)
  • FAKE_CURL_ERROR
  • FAKE_KEYCTL_FULL
  • FAKE_TMUX_ERROR
  • bw prints its coloured library line before "Invalid master password."

Existing tests now assert the exact new stderr.

Size

src: +629 / -255 lines. About 200 of the added lines are errors.rs; most of web.rs's diff is re-indentation into a small Call struct. The line budget is at 4585 of 10000.

src/errors.rs turns another program's stderr into one line of roster's
own, with a hint line when there is a next step. bw's output no longer
reaches the terminal: a wrong master password, a missing item, several
matches or a locked vault each get a message. A keyring that won't take
the session key says why. In run, a Host's stderr is held until its
stdout starts or it ends, so ssh's and sudo's failures are told plainly;
the command's own stderr still shows, labelled. check gives the same
reasons, one line per Host.
A Host setup can't reach, whose password or Box key isn't accepted, or
whose host key changed, gets the same message and hint as run. The Mesh
and undo scripts' failures show their last line, with the Windows hint
on a line of its own. ssh-keygen's output is captured; file errors drop
their (os error N). "N Hosts not done" names the command and hints at
the rerun.
curl's errors are collected instead of printed, and told by its exit
code: a name that won't resolve, nothing listening, a timeout, an
untrusted certificate (with the verify: false / -k hint), an empty
reply. HTTP 401 and 403, from the request or the token login, read
"login refused", with a hint. The password stays masked.
No Inventory names where roster looked and how to name one; a missing
-c or ROSTER_CONFIG file says so without an OS error code, with the
lookup order as a hint. Bad YAML puts the line up front like every other
Inventory error. A usage error's "(see roster -h)" becomes a hint line;
an unknown command points at `roster help plugins` too.
fzf or tmux missing or failing in the picker, ssh missing, an unknown
Host, an auth: cmd: that fails, no terminal to ask on, and a locked vault
during sync's import each get one line and a hint where there's a next
step. tmux's stderr is captured; fzf keeps the terminal, as ssh does.
File errors in add drop their (os error N).
roster.1 gets a DIAGNOSTICS section listing each message and its hint,
and run and web say where their failures are told. The tutorial's
troubleshooting table matches the new messages.
@2styx2
2styx2 merged commit 669b7a4 into dev Nov 10, 2026
16 checks passed
@2styx2
2styx2 deleted the feat/nice-errors branch November 12, 2026 20:37
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