Document the command in the package comment

[korya]

Problem

pkg.go.dev says there is no documentation for this package, and the README links to that page with a badge.

Measured against the currently-indexed v0.0.7, the page renders exactly one thing:

"There is no documentation for this package": True

main.go opened with a bare package main, and pkg.go.dev renders a command's doc comment or nothing at all. So the Go Reference badge on line 1 of the README has been advertising documentation that does not exist.

Solution

Write the package comment, and make the README agree with it about exit codes.

The comment covers the four things somebody arriving from that badge is trying to learn: what the tool is for, the shape of an invocation, the exit codes, and which options read the environment. Every example in it was run against a live endpoint before being written down, and each documented exit code was reproduced:

$ http-assert --log-level nope --assert-ok https://example.com   # exit=71
$ http-assert -X 'BAD METHOD' --assert-ok https://example.com    # exit=91
$ http-assert --assert-ok                                        # exit=103

Writing those down exposed that the README listed three of the five. 71 has been returned since unparseable environment values started being rejected, and 91 for as long as a malformed method or URL has been possible — neither was ever documented. That gap is worse than a missing table row: a monitoring script that reads every non-zero code as "the service is down" reports a typo in HTTP_ASSERT_MAX_TIME as an outage, which inverts the tool's purpose.

Documentation only — no behaviour change, and the end-to-end suite is untouched.

Other Changes

None.

Notes for the reviewer

This lands on the next tag, not retroactively on v0.1.0; pkg.go.dev renders whatever the tagged commit contained.

The exit codes now appear in three places — the package comment, the README, and e2e_harness_test.go's constants. Only the last is enforced. Worth an issue if the duplication bothers you; I did not want to invent a doc-linting mechanism inside a docs PR.

🤖 Generated with Claude Code