cheapo/AGENTS.md

AGENTS.md — guidelines for coding agents

Project

cheapo — CLI in Go (Cobra) to fetch and observe current free game offers. Later planned: exposing the tools as an MCP server (see README.md, section "Roadmap / MCP").

Reference project

free-games-claimer — https://github.com/DoSpamu/free-games-claimer (fork of https://github.com/vogler/free-games-claimer). How it gets the free-games info:

• The fork (DoSpamu) is only an overlay (runner run.js, Discord notify, logger) on the upstream Docker image. The actual logic lives upstream in vogler/free-games-claimer (epic-games.js, prime-gaming.js, gog.js, steam-games.js, aliexpress.js).
• Upstream uses Playwright (Firefox) with a persistent session: it opens the store page "Free Games", detects games via the locator a:has(span:text-is("Free Now")), follows the links and claims them in the browser (login per cookie session, 2FA via OTP key, captcha handling).
• Important (comment in epic-games.js, ~line 151): the page is built from the JSON of the public backend: https://store-site-backend-static.ak.epicgames.com/freeGamesPromotions (filter data.Catalog.searchStore.elements on active promotions.promotionalOffers with 100 % discount; slug preferably from catalogNs.mappings[0].pageSlug, since urlSlug is sometimes wrong).
• Our approach (Go): we query this endpoint directly — no browser, no login needed, as long as we only want to detect (list + watch). The actual claiming of the games (like in the reference project) is deliberate not part of this project.

Second reference project

free-games-notifier — https://github.com/jaixmario/free-games-notifier (Python, GitHub-Actions cron every 6 h; notifications via e-mail, Telegram, Discord, WhatsApp; state in free.json/free-steam.json).

How it gets the info:

• Epic (epic.py): same public endpoint store-site-backend-static.ak.epicgames.com/freeGamesPromotions?locale=en-US (HTTP GET, no login) — confirms our Go approach. Filter: discountSetting.discountPercentage == 0; distinguishes current (promotionalOffers) and upcoming (upcomingPromotionalOffers — preview window for future free games). Change detection via signature (CURRENT:t1,t2|UPCOMING:...) + detail comparison per (title, link) keys; only notify on new offers, removals are silently written to state.
• Steam (steam.py), two sources:
  1. Free to Keep: HTML scrape of https://store.steampowered.com/search/?maxprice=free&specials=1 (BeautifulSoup; .search_result_row, price "Free"/100 %).
  2. Free Weekend: JSON API https://store.steampowered.com/api/featuredcategories/ — items with "Free Weekend"/"play for free" in name/body; title fallback via store.steampowered.com/api/appdetails?appids=<id>.
• Useful patterns for us: state signature + diff (notify only on real additions, removals silently into state) and current vs. upcoming separation. Both could be adopted.

Toolchain & linting

• Go ≥ 1.27 (go version).
• Formatting: gofmt -w . (mandatory before every commit; CI checks gofmt -l . = empty).
• Linting/analysis: gopls (install: go install golang.org/x/tools/gopls@latest). Use in editors as LSP; additionally go vet ./... before every commit.
• Build & test: bash go build ./... && go vet ./... && go test ./... gofmt -l . # must be empty ## Conventions - Module path: gogs.netdome.biz/paul/cheapo. - CLI framework: Cobra (github.com/spf13/cobra), commands in cmd/cheapo/main.go. - Internal code under internal/ (epic: store client, watch: polling/eventing). - Wrap errors with context: fmt.Errorf("epic: ...: %w", err). - User-facing strings in German (CLI output, help texts, error messages), code comments in English. - Provider pattern: every store lives in internal/<store>/ and implements game.Provider (Name() + GetFreeGames(ctx) ([]game.Game, error)); the shared type is game.Game (internal/game). New stores (e.g. GOG) follow this pattern and are registered in newProviders() (cmd/cheapo/main.go). - Chatto client: internal/chatto is a hand-built Connect-JSON client (Chatto's generated code is internal/ and not importable). Credentials ONLY via CHATTO_BASE_URL/CHATTO_TOKEN env from the operator — the tool never fetches credentials itself, and the agent does not use its own plugin credentials for it. - New store platforms (Prime, GOG, …) follow the provider pattern (above).