@trolleroof/tui 0.2.3

package/README.md

@@ -0,0 +1,349 @@
+# tui-gamepigeon
+
+Play familiar single-player games in a lightweight HTML overlay while your agents work. Game engines are shared between the overlay and the recording pipeline so interaction traces stay game-agnostic when recording is enabled.
+
+## Play
+
+Build the overlay once, then launch the arcade menu or a specific game:
+
+```bash
+bun install
+bun run build:overlay   # web bundle + native Tauri shell (needs Rust)
+bun start               # overlay menu
+bun start snake         # jump straight into Snake
+# or after `bun run build`: gamepigeon / gamepigeon snake
+```
+
+In the overlay: arrow keys or WASD to move, `Enter` to select, `r` to restart, `Esc` or `q` to hide. Drag the top bar to move the window; use the expand control to resize it.
+
+## Install: local vs. global
+
+There are two ways to run the Arcade overlay. **Local** runs it straight from this
+checkout for development. **Global** installs it once so the plain `claude` command
+opens Arcade in every project.
+
+Both need [Bun](https://bun.sh) (`>=1.3`), macOS 11+ or Windows 10+, and Rust only
+when building the overlay binary from source.
+
+### Local (from this checkout)
+
+Build the overlay and wire the harness adapters to this working copy:
+
+```bash
+bun install
+bun run build:overlay      # overlay web bundle + native Tauri shell (needs Rust)
+bun run install:adapters   # installs Codex / Claude / OpenCode adapters -> this checkout
+```
+
+Restart your harness. The generated adapters live at `~/.codex/skills/arcade`,
+`~/.claude/skills/arcade`, and `~/.config/opencode/commands/arcade.md`; all execute
+`scripts/overlay.ts` from this checkout.
+
+For local harness development, one command builds the current checkout, replaces any
+stale overlay, and points at the debug Tauri binary instead of the packaged release:
+
+```bash
+bun run claude:dev        # Claude Code — loads this checkout via --plugin-dir .
+bun run codex:dev         # Codex — workspace plugin + $arcade adapter from this checkout
+bun run antigravity:dev   # Antigravity — .agents/plugins/ workspace plugin + agy
+```
+
+Claude appears as `/tui-gamepigeon:arcade`. Codex uses the `$arcade` skill (or `/arcade` picker).
+Antigravity picks up `.agents/plugins/tui-gamepigeon/` from the repo root. All three set
+`GAMEPIGEON_SKIP_UPDATE_CHECK=1` so local dev is not fighting the release auto-updater.
+
+To open the overlay directly without a harness:
+
+```bash
+bun run start            # menu
+bun run start 2048       # a specific game
+bun run preview:overlay  # browser preview at 470×650 (no Tauri)
+bun run dev:overlay      # rebuild web bundle + debug shell, then show
+```
+
+#### Browser preview
+
+Agents (and humans) can iterate on overlay layout without a Rust build:
+
+```bash
+bun run preview:overlay
+# → http://127.0.0.1:4173/ (opens your browser)
+bun run preview:overlay -- --game=connect4
+```
+
+The preview frames the real overlay UI at the production sizes (**470×650** compact, **720×780** expanded). Titlebar **↗ / ↙** toggles the frame; Hide and Shutdown are no-ops in the browser. Open a game from the menu, or pass `--game=<id>` / use `?game=<id>` (optional `&variation=classic`).
+
+### Global (installed once, works everywhere)
+
+For Codex (or another supported harness), the one-command install is:
+
+```bash
+npx -y bunx @trolleroof/tui@latest install --codex
+```
+
+Replace `--codex` with `--claude`, `--opencode`, `--hermes`, `--openclaw`, or
+`--all`. This uses npm to fetch Bun for the command, then writes the harness adapter.
+Restart the harness when it finishes.
+
+Install the plugin from the GitHub marketplace so the normal `claude` command runs
+the lifecycle hooks in every project:
+
+```bash
+claude plugin marketplace add Trolleroof/tui-gamepigeon
+claude plugin install tui-gamepigeon@tui-gamepigeon --scope user
+```
+
+Optionally enable Claude's marketplace refresh under `/plugin` → **Marketplaces** →
+**tui-gamepigeon**, and point the status line at the Arcade update shim once:
+
+```json
+"statusLine": {
+  "type": "command",
+  "command": "bun ~/.gamepigeon/status-line.ts"
+}
+```
+
+The packaged plugin exposes `/tui-gamepigeon:arcade` and `/tui-gamepigeon:arcade-update`;
+the standalone adapter provides Claude's shorter `/arcade`.
+
+## Optional account
+
+Arcade requires an account. On first launch the plugin opens the shared web login, where a new player can create an account or sign in with email, Google, or GitHub. Later launches reuse the private local session.
+
+```bash
+gamepigeon auth signup
+gamepigeon auth login
+gamepigeon auth oauth google
+gamepigeon auth oauth github
+gamepigeon auth status
+gamepigeon auth logout
+```
+
+Production defaults to `https://runretroarcade.com/login.html`, `https://auth.runretroarcade.com`, and `https://api.runretroarcade.com`. Override them for local development with `GAMEPIGEON_LOGIN_URL`, `GAMEPIGEON_AUTH_URL`, and `GAMEPIGEON_BACKEND_URL`. The browser returns the Better Auth bearer to a localhost callback; it is stored in `auth.json` and atomically mirrored to `backend.conf`, both with user-only permissions. That same bearer authenticates `/v1/me`, trace uploads, and completed-game results. If that validation or an upload fails, Arcade marks the account chip **Sync paused** while keeping gameplay data queued locally. Logout clears both credentials without deleting local games or traces.
+
+## Coding harness adapters
+
+The bundled adapters give Codex CLI, Claude Code, and OpenCode the same Arcade launcher. GamePigeon opens a centered, borderless HTML overlay above the active desktop. It uses the operating system's installed webview through a small Tauri shell, not Chrome or Electron.
+
+Requirements:
+
+- Bun
+- macOS 11+ or Windows 10+
+- A packaged overlay binary, or Rust when building it from source
+
+The overlay is a single-instance helper with no Dock icon on macOS and no taskbar or console entry on Windows. Hiding it keeps the game state alive; invoking Arcade again restores and centers the existing window. It works from regular terminals and does not require tmux, a browser, a local server, or an extra setup command after plugin installation.
+
+Install the dependencies and all three harness adapters from this checkout:
+
+```bash
+bun install
+bun run build:overlay
+bun run install:adapters
+```
+
+Restart the harness after installation. In Claude Code, submitting any prompt opens or restores Arcade while Claude works. In Codex, invoke `$arcade` directly, or type `/arcade` to filter the picker and select **Arcade**. Claude Code and OpenCode receive a bare `/arcade` command. The packaged Claude plugin uses its required namespace: `/tui-gamepigeon:arcade`. Codex does not register custom top-level slash commands; its `/arcade` interaction is picker discovery for the `$arcade` skill, like other Codex skills.
+
+For local harness development, one command builds the current checkout, replaces any stale overlay, and loads this repo instead of an installed copy:
+
+```bash
+bun run claude:dev        # Claude Code
+bun run codex:dev         # Codex CLI
+bun run antigravity:dev   # Antigravity (agy)
+```
+
+`SessionStart` snaps a still-running overlay back to the menu (without popping the window open) so a new session never resumes mid-game, `UserPromptSubmit` shows the overlay, `Stop` pauses it with an `Enter` shortcut back to the coding prompt, and `SessionEnd` shuts down the helper.
+
+To enable the hooks for the normal `claude` command, install the GitHub marketplace once:
+
+```bash
+claude plugin marketplace add Trolleroof/tui-gamepigeon
+claude plugin install tui-gamepigeon@tui-gamepigeon --scope user
+```
+
+Claude Code does not silently install plugin updates. Arcade uses a WOZ-style detect-and-nudge flow instead (see **Auto-updates** below).
+
+The generated adapters live at `~/.codex/skills/arcade`, `~/.claude/skills/arcade`, and `~/.config/opencode/commands/arcade.md`; all execute `scripts/overlay.ts` from this checkout. The installer refuses to replace an unrelated command with the same name. Press `Esc` or `q` to hide the game, drag its top bar to move it, and use the expand button to resize it.
+
+## Auto-updates
+
+Arcade updates in three layers. Claude Code cannot silently install a new plugin package for you — the user still confirms the upgrade — but detection and overlay binaries are automatic.
+
+1. **Detect + nudge (plugin scripts/hooks)**  
+   On every new session, a `SessionStart` hook runs `scripts/plugin-update.ts --check`. It compares the installed plugin's `gitCommitSha` against `main` on GitHub. When they differ, it writes `~/.gamepigeon/update-available.json` and refreshes `~/.gamepigeon/status-line.ts`. The first prompt of the session also runs `--nudge`, which injects a reminder to run `/tui-gamepigeon:arcade-update`. Local directory marketplaces and `bun run claude:dev` (`GAMEPIGEON_SKIP_UPDATE_CHECK=1`) skip the check.
+
+2. **Manual plugin upgrade**  
+   Run `/tui-gamepigeon:arcade-update` (or the equivalent `claude plugin marketplace update tui-gamepigeon` + `claude plugin update tui-gamepigeon@tui-gamepigeon`). Then `/reload-plugins` or restart Claude Code so the new scripts load. The skill clears the update flag on success.
+
+3. **Overlay binary download**  
+   Overlay UI changes ship as new binaries. Pushing anything under `overlay/`, `tauri/`, `scripts/overlay*`, or the shared game code triggers the `Overlay` workflow, which builds and tests macOS and Windows binaries. Publishing is a separate, deliberate step: the workflow cuts a release only when `package.json`'s version names one that does not exist yet (see [Releasing](#releasing)). When it does, it publishes the binaries as `overlay-v<version>` and commits `overlay-release.json` pointing at it. On the next session, `scripts/overlay.ts` compares that manifest against `~/.gamepigeon/bin/current`, downloads the new binary (via `gh` for private repos, plain HTTPS once public), quits any overlay still running the old build, and launches the fresh one. Download failures fall back to the previously installed binary, so offline sessions keep working.
+
+One-time status line setup (optional, but closest to the WOZ experience):
+
+```json
+"statusLine": {
+  "type": "command",
+  "command": "bun ~/.gamepigeon/status-line.ts"
+}
+```
+
+Add that under `~/.claude/settings.json`. The shim is rewritten on each session check and does not hardcode a plugin cache path, so it stays valid across upgrades.
+
+The repository also includes native plugin manifests for marketplace distribution. Local dev commands build the checkout and load it directly:
+
+```bash
+bun run claude:dev        # Claude Code — --plugin-dir .
+bun run codex:dev         # Codex — workspace plugin + adapter
+bun run antigravity:dev   # Antigravity — .agents/plugins/ at repo root
+```
+
+Claude namespaces plugin-provided skills, so the packaged forms appear as `/tui-gamepigeon:arcade` and `/tui-gamepigeon:arcade-update`. The standalone adapter provides Claude's shorter `/arcade` form.
+
+Codex CLI and OpenCode invoke the overlay through their Arcade adapter. Claude Code additionally exposes lifecycle hooks, which is why prompt-start and response-stop behavior is automatic there.
+
+To bypass a harness and open the overlay directly:
+
+```bash
+bun run start
+bun run start 2048
+```
+
+## Launch games
+
+| Game | Status | Controls |
+|---|---|---|
+| 2048 | ✅ playable | arrows/wasd slide |
+| Tetris | ✅ playable | arrows move, z/x rotate, space drop |
+| Snake | ✅ playable | arrows/wasd steer |
+| Minesweeper | ✅ playable | arrows move, space reveal, f flag |
+| Sokoban | ✅ playable | arrows push, z undo |
+| Connect Four | ✅ playable | ←/→ aim, space drop |
+| Sudoku | ✅ playable | arrows move, 1-9 place, 0/x clear |
+
+## Interaction traces
+
+The recording layer under `src/recording/` durably journals episodes under `~/.tui-gamepigeon/recordings/` and splits them into immutable upload chunks. Every schema-v2 event includes `event_id`, `user_id`, `chunk_id`, and `game_id`.
+
+- Policy-visible events preserve input impulses, timing, score/reward changes, and episode completion.
+- Privileged engine checkpoints and realized random effects support deterministic replay without leaking hidden state into policy input.
+- Local writes continue when upload is disabled or temporarily unavailable; pending chunks retry on later sessions.
+- Completed games also enter a separate durable score outbox. Quits, restarts, and client shutdowns never submit a score.
+
+## Local score history
+
+Every naturally completed overlay game appends one JSON object to
+`~/.tui-gamepigeon/scores/history.jsonl`, even without a network connection.
+The directory is user-only (`0700`) and the JSONL file is `0600`. Quits,
+restarts, and shutdowns do not create entries.
+
+Each schema-v1 row contains `game_id`, `game_type`, `variation_id`, `score`,
+`success`, `completed_at` (the game-end timestamp), `duration_ms`, and
+`platform`, plus the resulting `personal_best` and `high_score_updated`.
+Personal bests are calculated per `game_type`; duplicate `game_id` writes are
+idempotent.
+
+The history is device-only today. A future remote score feature belongs in the
+sync backend, not the auth Worker D1; it should merge records by `game_id` and
+keep local logging independent of account and network availability.
+
+Set the opaque per-user bearer token issued by Retro Backend. Requests default
+to the sync backend at `https://api.runretroarcade.com`; set
+`GAMEPIGEON_BACKEND_URL` only when targeting local or staging infrastructure:
+
+```bash
+export GAMEPIGEON_BACKEND_TOKEN=retro_...
+# optional override:
+# export GAMEPIGEON_BACKEND_URL=http://127.0.0.1:8787
+```
+
+The HTML overlay journals each seeded action sequence in local storage, rebuilds replay-safe schema-v2 engine-state traces at episode end, and hands immutable chunks plus completed-game results to Tauri. Tauri validates and durably queues them before any network call, then resolves the canonical `/v1/me` user and drains both outboxes in the background. Chunks live under `~/.tui-gamepigeon/recordings/overlay-pending/` until `/v1/game-event-chunks` accepts them; results live under `~/.tui-gamepigeon/recordings/results/overlay-pending/` until `/v1/game-results` accepts them. Interrupted and offline sessions recover on the next launch, while cloud-acknowledged payloads move to the matching `overlay-completed/` directory.
+
+Export policy-visible human demonstrations into leakage-safe BC splits:
+
+```bash
+bun run export:bc -- --output ./bc-dataset
+```
+
+The exporter reads completed terminal and overlay chunks by default, joins each human control to its referenced observation and outcome across chunk boundaries, drops environment actions and no-op controls, and writes `train.jsonl`, `validation.jsonl`, `test.jsonl`, and `manifest.json`. Splits are deterministic by `game_id`, keeping every episode in only one split. Use repeatable `--input <file-or-directory>` arguments for backend downloads or `--include-noops` when those actions are intentionally part of the policy.
+
+Before recording, the client finishes local recovery and resolves the token's canonical user through `GET /v1/me`. It uploads only trace chunks and results owned by that user; pending data from another local account is left untouched. If configured identity lookup fails, gameplay starts without recording that episode and retries identity on later games and drains. `GAMEPIGEON_INGEST_URL` and `GAMEPIGEON_INGEST_API_KEY` are deprecated compatibility aliases retained through `0.x` and scheduled for removal in `1.0`. They do not opt into the default backend: a legacy key set without `GAMEPIGEON_INGEST_URL` leaves sync disabled rather than uploading to `https://api.runretroarcade.com`.
+
+This repository owns the client-side producer and versioned wire contracts. The ingestion service, score database, queue consumers, and object-storage archive live in the backend repository. The v1 and v2 request fixtures under `contracts/` can be reused by that backend's contract tests.
+
+## Analytics
+
+Basic product analytics (DAU / feature usage) via PostHog are separate from interaction traces, which are for policy training rather than usage metrics.
+
+```bash
+export POSTHOG_API_KEY=phc_...
+# optional, defaults to https://us.i.posthog.com
+export POSTHOG_HOST=https://us.i.posthog.com
+```
+
+Without `POSTHOG_API_KEY` set, analytics calls are no-ops — gameplay is never affected. Events currently captured: `app.opened`, `account.signed_up`, `account.signed_in`, `game.started`, `game.ended`. Signed-in events use the account's pseudonymous user ID; guest events use an anonymous per-install ID stored at `~/.tui-gamepigeon/device_id`.
+
+The PostHog SDK batches events with its defaults, uses the CloudEvent ID as `$insert_id` for retry deduplication, and flushes during graceful shutdown.
+
+Product events use a CloudEvents 1.0 envelope with `specversion`, `id`, `source`, `type`, `time`, `datacontenttype`, optional `subject`, and typed `data`. Client events default to source `/tui-gamepigeon/client`; plugin, website, and backend producers use their own source. Event IDs reuse the recording layer's `evt_` identifier format.
+
+| Funnel | Event types | Allowed data |
+| --- | --- | --- |
+| Awareness | `site.visited` | `referrer_host`, `campaign` |
+| Acquisition | `account.signed_up`, `account.signed_in` | `method` |
+| Activation | `game.started`, `game.ended` | `game_type`, `variation_id`, outcome, score, success |
+| Retention | `app.opened`, gameplay events | `app_version`, platform, gameplay data |
+| Revenue | `payment.succeeded` | `plan`, `currency`, `amount_minor` |
+| Referral | `referral.created`, `referral.redeemed` | channel |
+| Plugin lifecycle | `plugin.launched`, `plugin.reattached`, `agent.task_completed` | harness |
+
+The website owns `site.visited`; invite and payment services own their corresponding events. Until those producers exist, the names above reserve the shared contract without fabricating client events. Analytics must never include terminal frames, trajectories, prompts, repository contents, credentials, email addresses, or raw provider payloads.
+
+The live [GamePigeon AARRR client dashboard](https://us.posthog.com/project/434929/dashboard/1866662) covers the client-owned acquisition, activation, and retention signals. See [`docs/analytics.md`](docs/analytics.md) for event ownership, saved insights, and the CLI verification runbook.
+
+## Architecture
+
+- `src/index.ts` — thin CLI: `gamepigeon` opens the overlay; `gamepigeon auth` handles accounts.
+- `src/core/game.ts` — gym-style `Game` interface every title implements (`reset(seed)` / `step(action)` / `state()`), shared by the overlay and recorder.
+- `src/core/rng.ts` — seedable PRNG (mulberry32) for reproducible episodes.
+- `src/games/*/` — pure game engines (unit-tested); HTML rendering lives in `overlay/renderers.ts`.
+- `src/recording/` — causal events, durable chunks, recovery, and upload transport.
+- `src/results/` — completed-game result outbox, recovery, and score delivery.
+- `src/sync/` — authoritative backend identity and the single-flight upload coordinator.
+- `src/analytics/posthog.ts` — PostHog Node client wrapper for product analytics.
+- `scripts/overlay.ts` — launcher, release download, and harness hook entry point.
+- `overlay/` — bundled HTML/CSS/TypeScript frontend and deterministic local game session.
+- `tauri/` — single-instance native shell with hidden Dock/taskbar presence.
+
+## Development
+
+```bash
+bun run test
+bun run test:adapters
+bun run test:launcher
+bun run typecheck
+bun run build              # emits dist/, exposes the `gamepigeon` bin
+bun run build:overlay:web  # overlay bundle only
+bun run preview:overlay    # browser preview (470×650 / 720×780 frame)
+bun run dev:overlay        # debug Tauri shell + show overlay
+```
+
+Bun runs the TypeScript source directly in development and builds a Bun-targeted executable for distribution.
+
+## Releasing
+
+Releases are gated on the version, not on commits. Pushing to `main` builds and tests the overlay but publishes nothing; a release appears only when `package.json`'s version names one that has no release yet. This keeps routine pushes from minting a release each time.
+
+To cut one, bump the version and push:
+
+```bash
+bun run version:bump          # 0.2.1 -> 0.2.2
+bun run version:bump minor    # 0.2.1 -> 0.3.0
+bun run version:bump major    # 0.2.1 -> 1.0.0
+bun run version:bump 1.4.0    # explicit
+bun run version:bump --no-commit
+```
+
+The version lives in four manifests — `package.json`, `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json`, and `.claude-plugin/marketplace.json` — and the script rewrites all of them together. Bump by hand and they drift, which is why `scripts/version-bump.test.ts` asserts they agree.
+
+The script commits but never pushes; publishing stays an explicit action. On the next push to `main`, CI builds the binaries, publishes them as `overlay-v<version>`, and commits an `overlay-release.json` pointing at that tag, which is what installed plugins download on their next session.
+
+Adding a new file that carries the version means adding it to `VERSION_FILES` in `scripts/version-bump.ts`, or it silently stops being bumped.