feat: nest API under /api/v1, structured error envelope, paged lists

Move every handler from /api/* to /api/v1/*. /api/* is now reserved for
future versioning.

Standardise the error response shape across the API as
{"error": {"code": "snake_case", "message": "..."}}. AppError gains a
`code()` whose top-level variants are matched exhaustively without a
wildcard — new variants are a compile error until coded. 500-class
responses always emit the fixed "internal error" string and log the
real cause via tracing only.

Lock in the list pagination envelope as {"items": [...], "page": {
"limit", "offset", "total"}} and apply it to GET /api/v1/mangas. `total`
serialises as null until feat/list-search-polish lands an indexed count.

The frontend client parses the envelope into ApiError.code with an
http_error fallback for non-JSON bodies. listMangas now returns the
paged shape; the root route consumes .items. New client.test.ts covers
envelope parsing and the fallback paths.

Lockstep version bump to 0.2.0.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

backend/tests/api_mangas.rs

@@ -8,29 +8,39 @@ use tower::ServiceExt;
 #[sqlx::test(migrations = "./migrations")]
 async fn list_is_empty_initially(pool: PgPool) {
     let h = common::harness(pool);
-    let resp = h.app.oneshot(common::get("/api/mangas")).await.unwrap();
+    let resp = h.app.oneshot(common::get("/api/v1/mangas")).await.unwrap();
     assert_eq!(resp.status(), StatusCode::OK);
-    assert_eq!(common::body_json(resp).await, json!([]));
+    let body = common::body_json(resp).await;
+    assert_eq!(body["items"], json!([]));
+    assert_eq!(body["page"]["limit"], 50);
+    assert_eq!(body["page"]["offset"], 0);
+    assert!(body["page"]["total"].is_null());
 }
 
 #[sqlx::test(migrations = "./migrations")]
 async fn create_then_list_roundtrip(pool: PgPool) {
     let h = common::harness(pool);
 
-    let created = h.app.clone().oneshot(common::post_json(
-        "/api/mangas",
-        json!({ "title": "Berserk", "author": "Kentaro Miura", "description": null }),
-    )).await.unwrap();
+    let created = h
+        .app
+        .clone()
+        .oneshot(common::post_json(
+            "/api/v1/mangas",
+            json!({ "title": "Berserk", "author": "Kentaro Miura", "description": null }),
+        ))
+        .await
+        .unwrap();
     assert_eq!(created.status(), StatusCode::OK);
     let body = common::body_json(created).await;
     assert_eq!(body["title"], "Berserk");
     assert_eq!(body["author"], "Kentaro Miura");
     assert!(body["id"].as_str().is_some());
 
-    let listed = h.app.oneshot(common::get("/api/mangas")).await.unwrap();
+    let listed = h.app.oneshot(common::get("/api/v1/mangas")).await.unwrap();
     let listed_body = common::body_json(listed).await;
-    assert_eq!(listed_body.as_array().unwrap().len(), 1);
-    assert_eq!(listed_body[0]["title"], "Berserk");
+    let items = listed_body["items"].as_array().unwrap();
+    assert_eq!(items.len(), 1);
+    assert_eq!(items[0]["title"], "Berserk");
 }
 
 #[sqlx::test(migrations = "./migrations")]
@@ -42,36 +52,78 @@ async fn search_filters_by_title_and_author(pool: PgPool) {
         ("Berserk", "Kentaro Miura"),
         ("Vinland Saga", "Makoto Yukimura"),
     ] {
-        let _ = h.app.clone().oneshot(common::post_json(
-            "/api/mangas",
-            json!({ "title": title, "author": author }),
-        )).await.unwrap();
+        let _ = h
+            .app
+            .clone()
+            .oneshot(common::post_json(
+                "/api/v1/mangas",
+                json!({ "title": title, "author": author }),
+            ))
+            .await
+            .unwrap();
     }
 
-    let resp = h.app.clone().oneshot(common::get("/api/mangas?search=miura")).await.unwrap();
+    let resp = h
+        .app
+        .clone()
+        .oneshot(common::get("/api/v1/mangas?search=miura"))
+        .await
+        .unwrap();
     let body = common::body_json(resp).await;
-    let titles: Vec<&str> = body.as_array().unwrap().iter().map(|m| m["title"].as_str().unwrap()).collect();
+    let titles: Vec<&str> = body["items"]
+        .as_array()
+        .unwrap()
+        .iter()
+        .map(|m| m["title"].as_str().unwrap())
+        .collect();
     assert_eq!(titles, vec!["Berserk"]);
 
-    let resp = h.app.oneshot(common::get("/api/mangas?search=saga")).await.unwrap();
+    let resp = h
+        .app
+        .oneshot(common::get("/api/v1/mangas?search=saga"))
+        .await
+        .unwrap();
     let body = common::body_json(resp).await;
-    let titles: Vec<&str> = body.as_array().unwrap().iter().map(|m| m["title"].as_str().unwrap()).collect();
+    let titles: Vec<&str> = body["items"]
+        .as_array()
+        .unwrap()
+        .iter()
+        .map(|m| m["title"].as_str().unwrap())
+        .collect();
     assert_eq!(titles, vec!["Vinland Saga"]);
 }
 
 #[sqlx::test(migrations = "./migrations")]
-async fn create_rejects_empty_title(pool: PgPool) {
+async fn create_rejects_empty_title_with_envelope(pool: PgPool) {
     let h = common::harness(pool);
-    let resp = h.app.oneshot(common::post_json(
-        "/api/mangas",
-        json!({ "title": "   ", "author": null }),
-    )).await.unwrap();
+    let resp = h
+        .app
+        .oneshot(common::post_json(
+            "/api/v1/mangas",
+            json!({ "title": "   ", "author": null }),
+        ))
+        .await
+        .unwrap();
     assert_eq!(resp.status(), StatusCode::BAD_REQUEST);
+    let body = common::body_json(resp).await;
+    assert_eq!(body["error"]["code"], "invalid_input");
+    let msg = body["error"]["message"].as_str().expect("message is string");
+    assert!(!msg.is_empty(), "message should be non-empty");
 }
 
 #[sqlx::test(migrations = "./migrations")]
-async fn get_unknown_id_is_404(pool: PgPool) {
+async fn get_unknown_id_is_404_with_envelope(pool: PgPool) {
     let h = common::harness(pool);
-    let resp = h.app.oneshot(common::get("/api/mangas/00000000-0000-0000-0000-000000000000")).await.unwrap();
+    let resp = h
+        .app
+        .oneshot(common::get(
+            "/api/v1/mangas/00000000-0000-0000-0000-000000000000",
+        ))
+        .await
+        .unwrap();
     assert_eq!(resp.status(), StatusCode::NOT_FOUND);
+    let body = common::body_json(resp).await;
+    assert_eq!(body["error"]["code"], "not_found");
+    let msg = body["error"]["message"].as_str().expect("message is string");
+    assert!(!msg.is_empty(), "message should be non-empty");
 }

backend/tests/common/mod.rs

@@ -1,3 +1,8 @@
+// Shared test helpers. Each integration test binary picks the subset it needs,
+// so dead-code lints on the unused helpers fire per-binary; suppress at the
+// module level.
+#![allow(dead_code)]
+
 use std::sync::Arc;
 
 use axum::body::Body;

backend/tests/health.rs

@@ -7,7 +7,7 @@ use tower::ServiceExt;
 #[sqlx::test(migrations = "./migrations")]
 async fn health_returns_ok(pool: PgPool) {
     let h = common::harness(pool);
-    let resp = h.app.oneshot(common::get("/api/health")).await.unwrap();
+    let resp = h.app.oneshot(common::get("/api/v1/health")).await.unwrap();
     assert_eq!(resp.status(), StatusCode::OK);
     let body = common::body_json(resp).await;
     assert_eq!(body["status"], "ok");