safedep / safedep/cli

Surface useful, actionable errors in the CLI using `dry/usefulerror`

Open
#24 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation enhancement
Dominant language
Go
Stars
4
Forks
0
Avg merge
5h 55m
Merged PRs (30d)
9

Description

Problem

CLI errors are often raw gRPC/internal messages that don't help users (or agents) understand what went wrong or how to fix it. Example from query exec:

Error: cloudquery: query: rpc error: code = Internal desc = server closed the stream without sending trailers

This tells the user nothing actionable.

Proposal

Adopt usefulerror from safedep/dry across the CLI so errors carry a human message, help text, and a reference URL instead of leaking transport-level detail.

dry/usefulerror already ships gRPC converters for the standard codes, so most of the mapping comes for free — we render its fields at the CLI's top-level error boundary and add CLI-specific mappings only where the generic message isn't enough.

Docs

Add a troubleshooting page on docs.safedep.io keyed by error code, and link each error's reference URL to the relevant entry. Beyond helping users, this is especially useful for coding agents: when a command fails, an agent can look up the error code and apply the documented fix on its own, instead of the user having to stop, debug, or hunt for a workaround.

Outcome

Errors become self-explanatory and greppable by code, with a doc link for deeper guidance.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the query exec error path and the CLI's top-level error boundary, then review how dry/usefulerror maps standard gRPC codes. Add CLI-specific mappings where needed, render human messages, help text, and reference URLs, and add a docs.safedep.io troubleshooting page keyed by error code with linked guidance.

Written by the indexing model from the issue text.

Assessment

Tech stack
go, grpc
Domain
cli, documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.