fix: address PR review on debug guard and API docs

- Simplify 127.x.x.x loopback check; reject empty host in format_listen_url
- Add malformed 127.* tests; search endpoint stability column
- CHANGELOG [0.1.0] footer link; SPA two-release deprecation note
- README inline warning on 0.0.0.0 example

Author: clean6378-max-it

CHANGELOG.md

@@ -20,3 +20,5 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 ### Deprecated
 
 - `export_count` on `GET /api/export/state` (documented only; still returned). Use `last_export_session_count`. Removal planned in a follow-up release per [deprecation policy](docs/deprecation-policy.md).
+
+[0.1.0]: https://github.com/cppalliance/claude-code-chat-browser/releases/tag/v0.1.0

README.md

@@ -58,7 +58,7 @@ python app.py
 
 Options:
 ```bash
-python app.py --port 8080 --host 0.0.0.0
+python app.py --port 8080 --host 0.0.0.0   # never add --debug on 0.0.0.0
 python app.py --base-dir /path/to/claude/projects
 ```
 

app.py

@@ -23,7 +23,7 @@ def is_loopback_host(host: str) -> bool:
     if h.startswith("127.") and h.count(".") == 3:
         parts = h.split(".")
         try:
-            return len(parts) == 4 and all(0 <= int(p) <= 255 for p in parts)
+            return all(0 <= int(p) <= 255 for p in parts)
         except ValueError:
             return False
     return False
@@ -32,6 +32,8 @@ def is_loopback_host(host: str) -> bool:
 def format_listen_url(host: str, port: int) -> str:
     """Return a valid ``http://`` URL for the startup banner (IPv6 hosts bracketed)."""
     h = (host or "").strip()
+    if not h:
+        raise ValueError("host must not be empty")
     if h.startswith("[") and h.endswith("]"):
         display_host = h
     elif ":" in h:
@@ -51,7 +53,7 @@ def validate_startup_cli(args: argparse.Namespace) -> None:
             "Werkzeug debugger and session data to other machines.",
             file=sys.stderr,
         )
-        raise SystemExit(1)
+        sys.exit(1)
 
 
 def create_app(

docs/api-reference.md

@@ -292,14 +292,14 @@ Case-insensitive substring search across all non-excluded messages in all projec
 
 `application/json` — array of hit objects:
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `project` | string | Project `name` |
-| `session_id` | string | Session id |
-| `title` | string | Session title |
-| `role` | string | Message role (`human`, `assistant`, …) |
-| `timestamp` | string \| null | Message timestamp |
-| `snippet` | string | ~160 chars around match |
+| Field | Type | Stability | Description |
+|-------|------|-----------|-------------|
+| `project` | string | stable | Project `name` |
+| `session_id` | string | stable | Session id |
+| `title` | string | stable | Session title |
+| `role` | string | stable | Message role (`human`, `assistant`, …) |
+| `timestamp` | string \| null | stable | Message timestamp |
+| `snippet` | string | experimental | ~160 chars around match; length may change |
 
 #### Errors
 

docs/deprecation-policy.md

@@ -25,6 +25,8 @@ A deprecated field may be removed when:
 - The bundled SPA no longer reads the field, and
 - Tests and CHANGELOG document the removal.
 
+For fields actively read by the bundled SPA (which does not track an external API version), the deprecation period will span **at least two releases** so the SPA and policy can be updated in the same release cycle as the final removal.
+
 ## Example (in progress)
 
 | Field | Endpoint | Status | Replacement |

tests/test_cli_args.py

@@ -325,7 +325,18 @@ def test_debug_explicit_true(self):
     def test_is_loopback_host_accepts_loopback(self, host: str) -> None:
         assert is_loopback_host(host)
 
-    @pytest.mark.parametrize("host", ["0.0.0.0", "192.168.1.1", "", "example.com"])
+    @pytest.mark.parametrize(
+        "host",
+        [
+            "0.0.0.0",
+            "192.168.1.1",
+            "",
+            "example.com",
+            "127.0.0.",
+            "127.256.0.0",
+            "127.-1.0.0",
+        ],
+    )
     def test_is_loopback_host_rejects_non_loopback(self, host: str) -> None:
         assert not is_loopback_host(host)
 
@@ -357,6 +368,10 @@ def test_validate_startup_cli_rejects_non_loopback_debug(
     def test_format_listen_url(self, host: str, port: int, expected: str) -> None:
         assert format_listen_url(host, port) == expected
 
+    def test_format_listen_url_rejects_empty_host(self) -> None:
+        with pytest.raises(ValueError, match="host must not be empty"):
+            format_listen_url("", 5000)
+
     def test_validate_startup_cli_allows_non_loopback_without_debug(self) -> None:
         parser = build_cli_parser()
         args = parser.parse_args(["--host", "0.0.0.0"])