feat(cheats): add Cloudflare Worker cheat proxy for GameHacking.org

- Add Scripts/cheat-proxy/worker.js — Cloudflare Workers script that
  scrapes GameHacking.org and returns normalised JSON cheat entries
- Add Scripts/cheat-proxy/wrangler.toml — worker deployment config
- Add Scripts/cheat-proxy/README.md — deployment instructions
- Add PVSettings keys: useCheatProxy (Bool, default true) and
  cheatProxyURL (String, default empty)
- Update GameHackingOrgLookup to call proxy first when configured,
  falling back to direct scraping on empty result or network error

Part of #3072

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

Author: github-actions[bot]

PVLibrary/Sources/PVLibrary/Cheat/GameHackingOrgLookup.swift

@@ -21,6 +21,7 @@
 
 import Foundation
 import PVLogging
+import PVSettings
 
 // MARK: - GameHackingOrgLookup
 
@@ -49,6 +50,10 @@ public actor GameHackingOrgLookup {
     private static let maxMemoryCacheEntries = 50
     /// Minimum seconds between requests to be polite to the server.
     private static let minRequestInterval: TimeInterval = 1.0
+    /// Compile-time default proxy URL. Can be overridden via PVSettings `cheatProxyURL`.
+    /// Set to a non-empty string after deploying the Cloudflare Worker
+    /// (see `Scripts/cheat-proxy/README.md`).
+    static let defaultProxyURL: String = ""
 
     // MARK: - State
 
@@ -83,9 +88,23 @@ public actor GameHackingOrgLookup {
             return diskHit.entries
         }
 
-        // 3. Network fetch — never throws outward; always returns empty on failure.
+        // 3. Network fetch — try proxy first (if enabled), then fall back to direct scraping.
         DLOG("GameHackingOrgLookup: fetching online for title='\(title)' slug=\(systemSlug ?? "nil")")
-        let results = await fetchWithFallback(title: title, systemSlug: systemSlug)
+        let results: [CheatDatabaseEntry]
+
+        let proxyURL = resolvedProxyURL()
+        if !proxyURL.isEmpty, Defaults[.useCheatProxy] {
+            let proxyResults = await fetchFromProxy(title: title, systemSlug: systemSlug, proxyBaseURL: proxyURL)
+            if !proxyResults.isEmpty {
+                DLOG("GameHackingOrgLookup: proxy returned \(proxyResults.count) codes for '\(title)'")
+                results = proxyResults
+            } else {
+                DLOG("GameHackingOrgLookup: proxy empty, falling back to direct scrape for '\(title)'")
+                results = await fetchWithFallback(title: title, systemSlug: systemSlug)
+            }
+        } else {
+            results = await fetchWithFallback(title: title, systemSlug: systemSlug)
+        }
 
         evictMemoryCacheIfNeeded()
         memoryCache[key] = (Date(), results)
@@ -95,8 +114,75 @@ public actor GameHackingOrgLookup {
         return results
     }
 
+    // MARK: - Proxy URL Resolution
+
+    /// Returns the effective proxy base URL, preferring the user-configured value over the compile-time default.
+    private func resolvedProxyURL() -> String {
+        let stored = Defaults[.cheatProxyURL].trimmingCharacters(in: .whitespacesAndNewlines)
+        if !stored.isEmpty { return stored }
+        return Self.defaultProxyURL
+    }
+
     // MARK: - Fetch Logic
 
+    /// Fetch cheat entries from the Provenance cheat proxy worker.
+    ///
+    /// The proxy endpoint is `GET <proxyBaseURL>/cheats?title=<title>&system=<slug>`.
+    /// Returns an empty array when the proxy is unreachable or returns no results.
+    private func fetchFromProxy(title: String, systemSlug: String?, proxyBaseURL: String) async -> [CheatDatabaseEntry] {
+        var components = URLComponents(string: proxyBaseURL.hasSuffix("/")
+            ? proxyBaseURL + "cheats"
+            : proxyBaseURL + "/cheats")
+        var queryItems = [URLQueryItem(name: "title", value: title)]
+        if let slug = systemSlug {
+            queryItems.append(URLQueryItem(name: "system", value: slug))
+        }
+        components?.queryItems = queryItems
+
+        guard let url = components?.url else {
+            WLOG("GameHackingOrgLookup: invalid proxy URL '\(proxyBaseURL)'")
+            return []
+        }
+
+        do {
+            var request = URLRequest(url: url)
+            request.setValue("Provenance-Emu/1.0", forHTTPHeaderField: "User-Agent")
+            request.timeoutInterval = 10
+            let (data, response) = try await URLSession.shared.data(for: request)
+            guard let http = response as? HTTPURLResponse,
+                  (200..<300).contains(http.statusCode) else {
+                WLOG("GameHackingOrgLookup: proxy non-200 for '\(title)'")
+                return []
+            }
+
+            let raw = try JSONDecoder().decode([ProxyCheatEntry].self, from: data)
+            return raw.enumerated().map { index, entry in
+                CheatDatabaseEntry(
+                    id: Self.idOffset + index,
+                    cheatName: entry.name,
+                    cheatCode: entry.code,
+                    cheatDescription: nil,
+                    deviceName: "GameHacking.org",
+                    deviceFormat: nil,
+                    category: entry.category ?? "General",
+                    romTitle: title,
+                    systemName: systemSlug,
+                    isOnlineResult: true
+                )
+            }
+        } catch {
+            WLOG("GameHackingOrgLookup: proxy fetch error for '\(title)': \(error)")
+            return []
+        }
+    }
+
+    /// JSON model returned by the cheat proxy worker.
+    private struct ProxyCheatEntry: Decodable {
+        let name: String
+        let code: String
+        let category: String?
+    }
+
     /// Try fetching with system filter first; fall back to no-system search on failure.
     private func fetchWithFallback(title: String, systemSlug: String?) async -> [CheatDatabaseEntry] {
         // Strategy 1: search with system filter (if we have a slug)

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

@@ -301,6 +301,19 @@ public extension Defaults.Keys {
     static let coreLanguage = Key<CoreLanguageSetting>("coreLanguage", default: .systemLocale)
 }
 
+// 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.
+    static let useCheatProxy = Key<Bool>("useCheatProxy", default: true)
+
+    /// Base URL of the deployed Provenance cheat proxy worker.
+    /// Set to empty string to disable the proxy and always use direct scraping.
+    /// See `Scripts/cheat-proxy/README.md` for deployment instructions.
+    static let cheatProxyURL = Key<String>("cheatProxyURL", default: "")
+}
+
 public enum ButtonPressEffect: String, Codable, Equatable, UserDefaultsRepresentable, Defaults.Serializable, CaseIterable {
     case bubble = "bubble"
     case ring = "ring"

Scripts/cheat-proxy/README.md

@@ -0,0 +1,86 @@
+# Provenance Cheat Proxy
+
+A thin Cloudflare Workers middleware that scrapes [GameHacking.org](https://gamehacking.org)
+and returns normalized JSON cheat entries with server-side KV caching (24 h TTL).
+
+## Endpoint
+
+```
+GET /cheats?title=<game title>&system=<system slug>
+```
+
+**Parameters:**
+- `title` (required) — The game title to search for.
+- `system` (optional) — The GameHacking.org system slug (e.g. `n64`, `gba`, `gc`).
+
+**Response:**
+```json
+[
+  { "name": "Infinite Lives", "code": "8107A5C02400", "category": "General" },
+  { "name": "Max Health",     "code": "8107A5C40064", "category": "General" }
+]
+```
+
+Returns an empty array `[]` when no cheats are found. HTTP 4xx/5xx are not returned
+for failed lookups — the caller should fall back to direct scraping on an empty result.
+
+## Health check
+
+```
+GET /health  →  { "status": "ok" }
+```
+
+## Deployment (manual — requires a Cloudflare account)
+
+> **Note:** Deployment is manual and requires a free [Cloudflare](https://cloudflare.com)
+> account and the [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/).
+
+1. **Install Wrangler:**
+   ```bash
+   npm install -g wrangler
+   wrangler login
+   ```
+
+2. **Create the KV namespace:**
+   ```bash
+   wrangler kv:namespace create CHEAT_CACHE
+   ```
+   Copy the `id` from the output and paste it into `wrangler.toml` replacing
+   `REPLACE_WITH_YOUR_KV_NAMESPACE_ID`.
+
+3. **Deploy:**
+   ```bash
+   cd Scripts/cheat-proxy
+   wrangler deploy
+   ```
+   Wrangler will print the worker URL, e.g.:
+   `https://provenance-cheat-proxy.<your-subdomain>.workers.dev`
+
+4. **Configure the app:**
+   Set the proxy URL in Provenance settings (Settings → Cheats → Proxy URL) or
+   update the compile-time default in
+   `PVLibrary/Sources/PVLibrary/Cheat/GameHackingOrgLookup.swift`:
+   ```swift
+   static let defaultProxyURL = "https://provenance-cheat-proxy.<your-subdomain>.workers.dev"
+   ```
+
+## Local development
+
+```bash
+cd Scripts/cheat-proxy
+wrangler dev
+```
+
+The worker is then available at `http://localhost:8787/cheats?title=Mario&system=n64`.
+
+## Rate limits (Cloudflare free tier)
+
+| Limit            | Value             |
+|------------------|-------------------|
+| Requests/day     | 100,000           |
+| KV reads/day     | 100,000           |
+| KV writes/day    | 1,000             |
+| CPU time/request | 10 ms (bundled)   |
+
+The 24 h KV cache ensures that repeated lookups for the same title+system pair
+use only one KV write per day and hit the fast read path for all subsequent requests.