http-latency-prober/docs/plans/2026-07-02-10-22-hxprobe-usage-doc-and-makefile.md

Plan: hxprobe-specific usage doc (case-by-case) + hxprobe-specific Makefile

Context

hxprobe is a fully standalone project (own pyproject.toml, uv.lock, README.md — see docs/summaries/2026-07-02-09-32-hxprobe-standalone-project.md and ...-toolchain-modernization.md). Two gaps remain versus the other Python implementations and versus hxprobe's own "could be cp -r'd to its own repo" design goal:

1. Docs: latprobe/phases.py/simple.py each have two usage docs — the CLAUDE.md-mandated docs/usage/py-<name>.md (what/flags/one example) and a much richer python/configs/usage-<name>.md "Runnable Usage Reference" walking through a full set of concrete cases with real captured output (confirmed by reading python/configs/usage-latprobe.md, 313 lines: basic, verbose × 4 variants, sampling, multi-URL, --fail, JSON × 2, timeout, exit-codes table, Makefile shortcuts). hxprobe only has the first kind. User confirmed: add the second kind, placed inside hxprobe/ itself (not under python/configs/, since hxprobe no longer lives there) so the doc travels with the project if extracted.
2. Makefile: hxprobe currently has no Makefile of its own — the only way to run/test/lint it is through the parent repo's root Makefile. Extracted to its own repo, there'd be no make interface left. User confirmed: add hxprobe/Makefile, fully independent from the root Makefile's existing hx-* targets (no delegation either direction — both keep their own complete logic, at the cost of some duplication).

Confirmed: neither latprobe nor hxprobe accept a config file (both take URLs as positional CLI args — only simple.py/phases.py read the python/configs/*.txt files), so no .txt-config-file equivalent is needed for hxprobe; this is a docs+Makefile-only task.

Changes

hxprobe/USAGE.md (new) — modeled directly on python/configs/usage-latprobe.md's structure and tone (concrete sh command blocks immediately followed by real captured output, real IPs/certs/ timings, brief explanatory notes, --- section separators). Cases, in order:

1. Basic — single URL
2. Verbose — HTTPS site (shows Protocol: HTTP/2, TLS, cert)
3. Verbose — plain HTTP (no TLS block)
4. Verbose — redirect followed by default (http://github.com → 200, Protocol: HTTP/2 (1 redirect)) — hxprobe-specific, latprobe has no equivalent
5. --no-follow-redirects — same URL, raw 301 instead — hxprobe-specific
6. --no-http2 — forces Protocol: HTTP/1.1 — hxprobe-specific
7. Verbose — TLS failure (expired cert, badssl.com)
8. Verbose — DNS failure (empty verbose block, suppressed)
9. Sampling (-n) — min/avg/max table, plus verbose+sampling
10. Multiple URLs (parallel probing)
11. --fail flag — exit 6 on HTTP 4xx
12. JSON output
13. JSON + verbose (includes http_version/redirect_count keys)
14. Timeout
15. Exit codes table (same 0–6 scheme as latprobe/Go)
16. Makefile shortcuts — both the new hxprobe/Makefile (make run, make test, etc., run from inside hxprobe/) and the parent repo's root shortcuts (make hx-run, run from the repo root)

Cases 1, 2, 3, 4, 5, 6, 8, 11 can reuse real output already captured earlier in this session (still accurate — no code changed since). Cases 7, 9, 10, 12, 13, 14 need fresh live runs during implementation to get real numbers (same standard the other usage-*.md docs hold themselves to — no fabricated timings).

docs/usage/hxprobe.md (edit) — add a one-line pointer near the top: "For a full case-by-case runnable reference, see hxprobe/USAGE.md." No other changes; it stays the CLAUDE.md-mandated summary doc.

hxprobe/Makefile (new) — fully self-sufficient, same auto-generated ## comment help style as the root Makefile, short target names (no hx- prefix needed since it's already scoped by being inside hxprobe/):

PYTHON ?= python3.14
ARGS   ?=
.DEFAULT_GOAL := help

help          # auto-generated from ## comments, same style as root Makefile
deps          # uv sync
run           # uv run python -m hxprobe $(ARGS)          (deps: deps)
lint          # uv run ruff check .                        (deps: deps)
fmt           # uv run ruff format .                       (deps: deps)
test          # uv run pytest tests -m "not integration" -v $(ARGS)   (deps: deps)
test-integration  # uv run pytest tests -m integration -v $(ARGS)     (deps: deps)
check         # lint + test
clean         # remove __pycache__/*.pyc/*.egg-info/.pytest_cache/.ruff_cache

No changes to the root Makefile — its existing hx-* targets are left exactly as-is per the "keep both independent" decision.

Docs housekeeping (per CLAUDE.md convention): save this plan to docs/plans/<timestamp>-hxprobe-usage-doc-and-makefile.md, write a summary to docs/summaries/<timestamp>-hxprobe-usage-doc-and-makefile.md after implementation, and append a CHANGELOG.md entry.

Verification

1. cd hxprobe && make help — lists all targets with descriptions, works with zero dependency on the parent repo's Makefile.
2. cd hxprobe && make run ARGS="-v https://example.com" — same output as make hx-run ARGS="-v https://example.com" from the repo root (proves the two Makefiles agree, without one calling the other).
3. cd hxprobe && make check — lint + hermetic tests pass (28 tests).
4. cd hxprobe && make test-integration — 9 live tests pass.
5. Re-run every command block in hxprobe/USAGE.md and confirm the captured output matches what's printed in the doc (structure must be stable even if exact millisecond timings drift).
6. Confirm the root Makefile's hx-* targets are byte-for-byte unchanged (git diff Makefile shows no hx-* section changes from this task).