fix: address Copilot review — proxy fetchHTML, doc comments, test assertions

- worker.js: fetchHTML now throws on 5xx/network errors so transient
  upstream failures set X-Proxy-Status: error and are not KV-cached;
  4xx still returns null (legitimate "not found")
- PVSettingsModel: correct useCheatProxy doc comment — fallback only
  on proxy error/unreachable, not on empty result with ok status
- GameHackingOrgLookupTests: assert URLProtocol.registerClass return
  value so test fails fast instead of silently hitting real network
- cheat-proxy README: document X-Proxy-Status header semantics and
  correct fallback behaviour description

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: github-actions[bot]

PVLibrary/Tests/PVLibraryTests/GameHackingOrgLookupTests.swift

@@ -120,7 +120,7 @@ final class GameHackingOrgLookupTests: XCTestCase {
     // MARK: - Proxy Path (URLProtocol stubs)
 
     func testSearchCheats_proxyReturnsResults() async {
-        URLProtocol.registerClass(ProxyCannedProtocol.self)
+        XCTAssertTrue(URLProtocol.registerClass(ProxyCannedProtocol.self), "URLProtocol registration failed — test may hit real network")
         defer { URLProtocol.unregisterClass(ProxyCannedProtocol.self) }
 
         let json = #"[{"name":"Infinite Lives","code":"DEADBEEF00000001","category":"General"}]"#
@@ -157,8 +157,8 @@ final class GameHackingOrgLookupTests: XCTestCase {
         // Proxy returns [] with X-Proxy-Status: ok — meaning "upstream confirmed no cheats".
         // searchCheats should trust this and NOT fall back to direct scraping.
         // DirectScrapeBlockerProtocol is registered to ensure no gamehacking.org request is made.
-        URLProtocol.registerClass(ProxyCannedProtocol.self)
-        URLProtocol.registerClass(DirectScrapeBlockerProtocol.self)
+        XCTAssertTrue(URLProtocol.registerClass(ProxyCannedProtocol.self), "URLProtocol registration failed — test may hit real network")
+        XCTAssertTrue(URLProtocol.registerClass(DirectScrapeBlockerProtocol.self), "URLProtocol registration failed — test may hit real network")
         defer {
             URLProtocol.unregisterClass(ProxyCannedProtocol.self)
             URLProtocol.unregisterClass(DirectScrapeBlockerProtocol.self)
@@ -196,8 +196,8 @@ final class GameHackingOrgLookupTests: XCTestCase {
         // Proxy is disabled — only the direct scrape path runs.
         // DirectScrapeBlockerProtocol intercepts gamehacking.org requests so no real
         // network call is made; it returns empty HTML so the scrape yields no results.
-        URLProtocol.registerClass(ProxyCannedProtocol.self)
-        URLProtocol.registerClass(DirectScrapeBlockerProtocol.self)
+        XCTAssertTrue(URLProtocol.registerClass(ProxyCannedProtocol.self), "URLProtocol registration failed — test may hit real network")
+        XCTAssertTrue(URLProtocol.registerClass(DirectScrapeBlockerProtocol.self), "URLProtocol registration failed — test may hit real network")
         defer {
             URLProtocol.unregisterClass(ProxyCannedProtocol.self)
             URLProtocol.unregisterClass(DirectScrapeBlockerProtocol.self)

PVSettings/Sources/PVSettings/Settings/Model/PVSettingsModel.swift

@@ -304,8 +304,10 @@ public extension Defaults.Keys {
 // MARK: Cheats
 public extension Defaults.Keys {
     /// When `true`, the app first queries the cheat proxy endpoint for GameHacking.org
-    /// cheats instead of scraping the site directly.  Falls back to direct scraping
-    /// if the proxy returns an empty result or is unreachable.
+    /// cheats instead of scraping the site directly. Falls back to direct scraping only
+    /// if the proxy is unreachable, returns a non-2xx status, or returns an empty result
+    /// without confirming success via `X-Proxy-Status: ok`. An empty result with
+    /// `X-Proxy-Status: ok` is treated as "no cheats found" and skips the fallback.
     static let useCheatProxy = Key<Bool>("useCheatProxy", default: true)
 
     /// Base URL of the deployed Provenance cheat proxy worker.

Scripts/cheat-proxy/README.md

@@ -24,8 +24,12 @@ GET /cheats?title=<game title>&system=<system slug>
 Returns an empty array `[]` when no cheats are found or when the request is invalid
 (e.g. missing `title`, unknown path). The response is always HTTP 200 with a JSON array
 so clients can safely decode without checking the status code. Invalid requests also
-include an `X-Validation-Error` header with a short description. The caller should fall
-back to direct scraping on an empty result.
+include an `X-Validation-Error` header with a short description.
+
+Responses include an `X-Proxy-Status` header (`ok` or `error`) indicating whether the
+proxy successfully contacted GameHacking.org. Callers should treat an empty array with
+`X-Proxy-Status: ok` as "confirmed no cheats found" and skip the direct-scrape fallback;
+fall back only when the proxy request fails or `X-Proxy-Status` is missing or `error`.
 
 ## Health check
 

Scripts/cheat-proxy/worker.js

@@ -214,18 +214,18 @@ function buildSearchURL(title, systemSlug) {
 }
 
 async function fetchHTML(url) {
-    try {
-        const resp = await fetch(url, {
-            headers: {
-                "User-Agent": USER_AGENT,
-                "Accept": "text/html,application/xhtml+xml",
-            },
-        });
-        if (!resp.ok) return null;
-        return await resp.text();
-    } catch {
-        return null;
+    const resp = await fetch(url, {
+        headers: {
+            "User-Agent": USER_AGENT,
+            "Accept": "text/html,application/xhtml+xml",
+        },
+    });
+    if (resp.status >= 500) {
+        // Server error — treat as transient failure so it is not KV-cached
+        throw new Error(`Upstream HTTP ${resp.status} from ${url}`);
     }
+    if (!resp.ok) return null; // 4xx → legitimate "not found"
+    return await resp.text();
 }
 
 // ─── Search result parsing ────────────────────────────────────────────────────