docs: generate an HTTP API listing for the hub and the node control API

docs/MESHBAY_HTTP_API.md lists every route of the hub (by domain, with the
authentication each requires) and of the node's loopback control API. It is
written by docs/generate_http_api.py from the routes and their docstrings;
test_http_api_doc.py fails when the file drifts from the code or when a
route has no docstring, so a new route must say what it does.

79 routes had no docstring and get a one-line description; a few whose first
line did not describe the route get a summary line.

The login page's developer docs gain an API link next to Design and
Protocol, in every language. README, MESHBAY_DESIGN.md (§0.1, §6.7, §7) and
CLAUDE.md point to the listing; README also points to examples/.

The examples scripts with a shebang become executable.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

1 files changed, 30 insertions, 0 deletions

diff --git a/packages/meshbay-hub/tests/test_http_api_doc.py b/packages/meshbay-hub/tests/test_http_api_doc.py
new file mode 100644
index 0000000..5568e63
--- /dev/null
+++ b/packages/meshbay-hub/tests/test_http_api_doc.py
@@ -0,0 +1,30 @@
+"""
+docs/MESHBAY_HTTP_API.md is generated from the routes of the hub and of the
+node's control API. A route added, removed or redescribed without running
+`python docs/generate_http_api.py` fails here.
+"""
+
+import importlib.util
+from pathlib import Path
+
+GENERATOR = Path(__file__).resolve().parents[3] / "docs" / "generate_http_api.py"
+
+
+def _generator():
+    spec = importlib.util.spec_from_file_location("generate_http_api", GENERATOR)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def test_the_api_listing_matches_the_routes():
+    gen = _generator()
+    assert gen.OUT.read_text(encoding="utf-8") == gen.render(), (
+        "docs/MESHBAY_HTTP_API.md is out of date: run python docs/generate_http_api.py")
+
+
+def test_every_route_says_what_it_does():
+    gen = _generator()
+    bare = [f"{gen.method(r)} {r.path}" for r in gen.hub_routes() + gen.node_routes()
+            if not gen.summary(r)]
+    assert not bare, f"give these routes a docstring, it is their line in the listing: {bare}"