feat: document and stabilize exit codes and error.code values
- Dominant language
- TypeScript
- Stars
- 41
- Forks
- 24
- Avg merge
- 1d 3h
- Merged PRs (30d)
- 56
Description
We almost always exit 1. JSON errors use ad hoc `error.code` strings (`transport_error`, `confirmation_required`, `input_validation_failed`, `command_blocked`) with no catalog.
For agents this is the difference between retry with `--yes` and give up.
1. Publish a table (help topic in #630): 0 success, 1 generic, then reserve 2 usage, 3 validation, 4 auth/config, 5 network. Implementing the split can follow the table. Do not silently change codes on existing scripts without a changelog note.
2. Freeze `error.code` strings in `AGENTS.md`. Add codes for `auth_required`, `config_invalid`, `not_found` if we do not already emit them.
3. `elastic status --json` should be the probe agents run after `auth_required` / `transport_error`.
Acceptance: help topic lists codes. `--json` errors on a missing config use a documented code. One test per code.
Contributor guide
Research direction
Read AGENTS.md and the help topic work in #630 to identify the existing error.code strings and documented exit-code expectations. Probe `elastic status --json` for the auth_required and transport_error flows, then add one test per documented code and verify missing-config JSON errors and the changelog note for any changed codes.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- cli, documentation, testing
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100