Skip to content

fix(html-documents): make library errors readable - #223

Merged
MikeChenWM merged 1 commit into
mainfrom
cursor/html-documents-errors-dd48
Nov 17, 2026
Merged

MikeChenWM merged 1 commit into
mainfrom
cursor/html-documents-errors-dd48

Conversation

@MikeChenWM

Copy link
Copy Markdown
Contributor

Why

Mike (CTO) wants museoncli html-documents errors to be clear. Production QA of 2.3.0 found four failures:

  1. Server business errors are double-encoded. The HTML document API returns {"detail": {"code": "folder_not_found"}} (and folder_name_taken) with no message. The shared envelope copied that object into error.message as "{\"code\": \"folder_not_found\"}", so an agent saw JSON instead of a sentence. When the body was itself a JSON string, server_code was missing too.
  2. A bad id said "Look the ID up first with the matching +list or +get command", but html-documents has +list and no +get.
  3. --folder ROOT / Root was rejected as not a UUID. The valid literal is root.
  4. +list --q "" (and whitespace) was treated as no search, even though the schema says minLength 1.

What changed

  • The shared error envelope decodes one JSON encoding of a {"code": ...} body. HTML-document codes become server_code plus a sentence (Folder not found, A folder with this name already exists, and the other codes that endpoint returns with no message). A body that already has its own message is unchanged. An unknown code-only object keeps the JSON text it showed before; decoding a string body also sets server_code.
  • The id hint for this domain names only shortcuts that exist (+list). Other commands still say +list or +get.
  • --folder accepts root in any case and sends root. Any other value says root is valid.
  • Empty or whitespace --q is a usage error (exit 2) and sends no request.

No version bump.

Tests

uv run ruff check . and uv run pytest -q (1949 passed).

Open in Web Open in Cursor 

Decode a code-only API body into server_code and a sentence, name only
shortcuts that exist, accept folder root in any case, and reject an empty --q.

Co-authored-by: Weimeng Chen <MikeChenWM@users.noreply.github.com>
@MikeChenWM
MikeChenWM merged commit d0bcb49 into main Nov 17, 2026
10 checks passed
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.

2 participants