feat: auto-legalize endpoint (POST /api/legalize)

Author: tasken

API.md

@@ -6,7 +6,7 @@ Base URL: `http://<your-ip>:8082`
 
 **Full** (default): everything - GPSS server, web viewer, database, all endpoints below.
 
-**Legality-only**: just `POST /api/legality` and `GET /api/status`. No database, no UI.
+**Legality-only**: just `POST /api/legality`, `POST /api/legalize`, and `GET /api/status`. No database, no UI.
 
 ```bash
 LEGALITY_ONLY=1 docker compose up -d
@@ -40,6 +40,53 @@ curl -X POST http://192.168.1.3:8082/api/legality \
 
 ---
 
+## POST /api/legalize
+
+Auto-legalize a Pokemon using PKHeX. Tries to fix legality issues and returns the corrected bytes. Works in both modes.
+
+| Header | Required | Description |
+|--------|----------|-------------|
+| `X-Generation` | Yes | `1`-`9`, `BDSP`, or `PLA` |
+| `X-Version` | No | Game version (`Scarlet`, `Diamond`, `Sun`, etc). Defaults to `Any` |
+
+Body: raw `.pkm` bytes (max 1 MB).
+
+```bash
+curl -X POST http://192.168.1.3:8082/api/legalize \
+  -H "X-Generation: 7" \
+  -H "X-Version: Sun" \
+  --data-binary @my_pokemon.pkm
+```
+
+Successfully fixed:
+```json
+{
+  "legal": true,
+  "modified": true,
+  "pokemon": "<base64 corrected bytes>",
+  "report_before": ["Invalid: Nickname does not match species name."],
+  "report_after": []
+}
+```
+
+Already legal (nothing to do):
+```json
+{"legal": true, "modified": false, "pokemon": null, "report_before": [], "report_after": []}
+```
+
+Can't fix:
+```json
+{
+  "legal": false,
+  "modified": true,
+  "pokemon": null,
+  "report_before": ["Invalid: Move 1 PP is above the amount allowed (99)."],
+  "report_after": ["Invalid: Move 1 PP is above the amount allowed (99)."]
+}
+```
+
+---
+
 ## GET /api/pokemon
 
 Search the database. Full mode only.

viewer/legality.py

@@ -107,6 +107,47 @@ def _is_generic_gpss_error(msg: str) -> bool:
     return msg.strip().lower() == "gpss console returned an error"
 
 
+def _legalize_via_console(generation: str, pkm_bytes: bytes, version: str) -> dict:
+    """Run GpssConsole in legalize mode."""
+    bin_path = gpss_console_bin()
+    if not bin_path:
+        raise FileNotFoundError("GpssConsole binary not found")
+
+    b64 = base64.b64encode(pkm_bytes).decode("ascii")
+    proc = subprocess.run(
+        [
+            str(bin_path),
+            "--mode",
+            "legalize",
+            "--pokemon",
+            b64,
+            "--generation",
+            generation,
+            "--ver",
+            version,
+        ],
+        capture_output=True,
+        text=True,
+        timeout=90,
+    )
+    stdout = (proc.stdout or "").strip()
+    if not stdout:
+        err = (proc.stderr or "").strip() or f"GpssConsole exited {proc.returncode}"
+        raise RuntimeError(err)
+    return json.loads(stdout)
+
+
+def legalize_pkm(generation: str, pkm_bytes: bytes, version: str) -> dict:
+    """Auto-legalize a Pokemon via GpssConsole."""
+    gen = legality_generation(generation)
+    for payload in _legality_payloads(pkm_bytes, generation):
+        try:
+            return _legalize_via_console(gen, payload, version)
+        except (json.JSONDecodeError, RuntimeError, OSError) as err:
+            return {"error": str(err)}
+    return {"error": "Could not parse PKM for legalization"}
+
+
 def legality_check_pkm(
     generation: str, pkm_bytes: bytes, backend: str | None
 ) -> dict:

viewer/routes.py

@@ -21,6 +21,7 @@
     gpss_console_bin,
     legality_check_pkm,
     legality_generation,
+    legalize_pkm,
 )
 from pkm import (
     effective_nickname,
@@ -385,6 +386,8 @@ def do_POST(self) -> None:
         parsed = urlparse(self.path)
         if parsed.path == "/api/legality":
             return self._legality_check()
+        if parsed.path == "/api/legalize":
+            return self._legalize()
 
         self.send_error(HTTPStatus.METHOD_NOT_ALLOWED)
 
@@ -427,6 +430,51 @@ def _legality_check(self) -> None:
         except Exception as err:
             return self._json(500, {"error": f"legality check failed: {err}"})
 
+    def _legalize(self) -> None:
+        """Auto-legalize a Pokemon: POST raw PKM bytes + generation + version."""
+        length = int(self.headers.get("Content-Length", 0))
+        if not length:
+            return self._json(400, {"error": "empty body"})
+        if length > 1_000_000:
+            return self._json(413, {"error": "payload too large"})
+
+        generation = self.headers.get("X-Generation", "").strip()
+        if not generation:
+            return self._json(400, {"error": "missing X-Generation header"})
+
+        version = self.headers.get("X-Version", "Any").strip()
+
+        pkm_bytes = self.rfile.read(length)
+
+        if gpss_console_bin() is None:
+            return self._json(503, {"error": "legality engine not available"})
+
+        try:
+            check = legality_check_pkm(generation, pkm_bytes, None)
+            report_before = [
+                line.strip()
+                for line in check.get("report", [])
+                if line and line.strip() and line.strip() != "Legal!"
+            ] if "error" not in check else []
+
+            result = legalize_pkm(generation, pkm_bytes, version)
+            if "error" in result:
+                return self._json(200, {"error": str(result["error"])})
+            report_after = [
+                line.strip()
+                for line in result.get("report", [])
+                if line and line.strip() and line.strip() != "Legal!"
+            ]
+            return self._json(200, {
+                "legal": bool(result.get("legal", False)),
+                "modified": bool(result.get("ran", False)),
+                "pokemon": result.get("pokemon"),
+                "report_before": report_before,
+                "report_after": report_after,
+            })
+        except Exception as err:
+            return self._json(500, {"error": f"legalization failed: {err}"})
+
     _SORT_ORDERS = {
         "recent": "upload_datetime DESC, id DESC",
         "dl": "download_count DESC, id DESC",
@@ -679,19 +727,30 @@ def do_GET(self) -> None:
             })
         self.send_error(HTTPStatus.NOT_FOUND)
 
+    def _read_pkm_request(self):
+        length = int(self.headers.get("Content-Length", 0))
+        if not length:
+            self._json(400, {"error": "empty body"})
+            return None, None, None
+        if length > 1_000_000:
+            self._json(413, {"error": "payload too large"})
+            return None, None, None
+        generation = self.headers.get("X-Generation", "").strip()
+        if not generation:
+            self._json(400, {"error": "missing X-Generation header"})
+            return None, None, None
+        if gpss_console_bin() is None:
+            self._json(503, {"error": "legality engine not available"})
+            return None, None, None
+        pkm_bytes = self.rfile.read(length)
+        return pkm_bytes, generation, self.headers.get("X-Version", "Any").strip()
+
     def do_POST(self) -> None:
-        if urlparse(self.path).path == "/api/legality":
-            length = int(self.headers.get("Content-Length", 0))
-            if not length:
-                return self._json(400, {"error": "empty body"})
-            if length > 1_000_000:
-                return self._json(413, {"error": "payload too large"})
-            generation = self.headers.get("X-Generation", "").strip()
-            if not generation:
-                return self._json(400, {"error": "missing X-Generation header"})
-            pkm_bytes = self.rfile.read(length)
-            if gpss_console_bin() is None:
-                return self._json(503, {"error": "legality engine not available"})
+        path = urlparse(self.path).path
+        if path == "/api/legality":
+            pkm_bytes, generation, _ = self._read_pkm_request()
+            if pkm_bytes is None:
+                return
             try:
                 result = legality_check_pkm(generation, pkm_bytes, None)
                 if "error" in result:
@@ -711,4 +770,33 @@ def do_POST(self) -> None:
                 })
             except Exception as err:
                 return self._json(500, {"error": f"legality check failed: {err}"})
+        if path == "/api/legalize":
+            pkm_bytes, generation, version = self._read_pkm_request()
+            if pkm_bytes is None:
+                return
+            try:
+                check = legality_check_pkm(generation, pkm_bytes, None)
+                report_before = [
+                    line.strip()
+                    for line in check.get("report", [])
+                    if line and line.strip() and line.strip() != "Legal!"
+                ] if "error" not in check else []
+
+                result = legalize_pkm(generation, pkm_bytes, version)
+                if "error" in result:
+                    return self._json(200, {"error": str(result["error"])})
+                report_after = [
+                    line.strip()
+                    for line in result.get("report", [])
+                    if line and line.strip() and line.strip() != "Legal!"
+                ]
+                return self._json(200, {
+                    "legal": bool(result.get("legal", False)),
+                    "modified": bool(result.get("ran", False)),
+                    "pokemon": result.get("pokemon"),
+                    "report_before": report_before,
+                    "report_after": report_after,
+                })
+            except Exception as err:
+                return self._json(500, {"error": f"legalization failed: {err}"})
         self.send_error(HTTPStatus.NOT_FOUND)