games/AGENTS.md

# AGENTS.md

Instructions for AI coding agents working in this repository.

## Quick Reference

```bash
# Development
task live              # Hot-reload dev server (templ + tailwind + air)
task build             # Production build to bin/games
task run               # Build and run server
task download          # Download pinned client-side libs (datastar-pro, daisyui)

# Quality
task test              # Run all tests: go test ./...
task lint              # Run linter: golangci-lint run

# Single test
go test -run TestName ./path/to/package
go test -v -run TestHandleLogin_Success ./features/auth

# Code generation
task build:templ       # Compile .templ files (go tool templ generate)
task build:styles      # Build TailwindCSS (go tool gotailwind)
```

Tools (templ, air, gotailwind, goose, sqlc) are managed via Go 1.25's `tool` directive in go.mod — no separate installs needed.

## Workflow Rules

- **Never merge PRs without explicit user approval.** Create the PR, push changes, then wait.
- Always use PRs via `tea` CLI — never push directly to main.
- Write semantic commit messages focusing on "why" not "what".

## Project Structure

```
games/
├── connect4/, snake/       # Game logic packages (pure Go, no HTTP)
├── features/               # Feature modules (handlers, routes, templates)
│   ├── auth/               # Login/register (standard HTTP, not SSE)
│   ├── c4game/             # Connect 4 UI + services
│   ├── snakegame/          # Snake UI + services
│   ├── lobby/              # Game lobby
│   └── common/             # Shared components, layouts
├── chat/                   # Reusable chat room (NATS + optional DB persistence)
├── auth/                   # Password hashing/validation (pure, no HTTP)
├── db/                     # SQLite, migrations, sqlc queries
├── cmd/downloader/         # Build-time tool: fetches datastar-pro + daisyui
├── assets/                 # Static files (embedded in prod, filesystem in dev)
└── config/, logging/, nats/, sessions/, router/, player/, version/
```

## Code Style

### Imports

Three groups separated by blank lines: stdlib, third-party, local. Enforced by goimports with `local-prefixes: github.com/ryanhamamura/games`.

```go
import (
    "fmt"
    "net/http"

    "github.com/go-chi/chi/v5"

    "github.com/ryanhamamura/games/connect4"
)
```

### Error Handling

```go
// Wrap errors with context
return fmt.Errorf("loading game %s: %w", id, err)

// Combine cleanup errors with errors.Join
return nil, errors.Join(fmt.Errorf("pinging database: %w", err), DB.Close())

// Best-effort operations
nc.Publish(subject, nil) //nolint:errcheck // best-effort notification

// HTTP errors
http.Error(w, "game not found", http.StatusNotFound)
http.Error(w, http.StatusText(http.StatusInternalServerError), http.StatusInternalServerError)

```

### Comments

- Focus on **why**, not **how**. Avoid superfluous comments.
- Package comments at top of primary file.
- Function comments for exported functions.

## Go Patterns

### Dependency Injection via Closures

Handlers receive dependencies and return `http.HandlerFunc`:

```go
func HandleGamePage(store *connect4.Store, sm *scs.SessionManager) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) { /* ... */ }
}
```

### Cleanup Function Returns

Infrastructure init functions return a cleanup func the caller defers:

```go
cleanupDB, err := db.Init(cfg.DBPath)
defer cleanupDB()
```

### Store/Instance Pattern

Game state uses a two-tier pattern: a thread-safe **Store** (map + RWMutex) holding **Instance** wrappers (individual game + own mutex + DB queries). Stores lazy-load from DB on cache miss.

### Build Tags

`//go:build dev` and `//go:build !dev` switch behavior for static asset serving (filesystem vs embedded hashfs) and config loading.

## Templ + Datastar Patterns

### Architecture: Everything Is a Stream

The core mental model: **the server owns all state and continuously projects it to the browser over SSE**. There is no client-side state management. The browser connects to an event stream, and the server pushes full HTML fragments whenever something changes. Datastar morphs these into the DOM — the client is a thin rendering surface.

User actions (clicks, keypresses) trigger short POST/DELETE requests back to the server. The server mutates state, publishes a NATS signal, and every connected SSE stream picks up the change and re-renders. The client never needs to know what changed — it just receives the new truth and morphs to match.

This means: **always send whole components down the wire.** Don't try to diff or send minimal patches. Render the full templ component, call `sse.PatchElementTempl()`, and let Datastar's morph handle the rest. The only exception is appending to a list (e.g. chat messages).

**Signals follow command-query segregation.** Signals are *commands* — they carry the user's intent to the server (form input values, button clicks). The SSE stream is the *query* — it continuously projects the server's truth into the DOM. Keep signals thin: form input buffers (`chatMsg`, `nickname`), pure UI state the server never needs (`activeTab`), and request indicators. Don't use signals to hold application state — that arrives from the server via SSE.

### SSE Event Loop

Both game event handlers follow the same structure:
1. Subscribe to NATS channels **before** creating SSE (avoids missed messages)
2. Send initial full-state patch
3. `select` loop over: context done, game updates (drain channel first), chat messages (append), 1-second heartbeat (full re-render)

```go
// Handler side — long-lived SSE with Brotli compression
sse := datastar.NewSSE(w, r, datastar.WithCompression(
    datastar.WithBrotli(datastar.WithBrotliLevel(5)),
))
sse.PatchElementTempl(components.GameBoard(game))

// Template side — disable Datastar's default SSE cancellation on interaction
data-init={ fmt.Sprintf("@get('/games/%s/events',{requestCancellation:'disabled'})", g.ID) }
```

### Client-Server Interactions

```go
// Trigger SSE actions from templates
data-on:click={ datastar.PostSSE("/games/%s/drop?col=%d", g.ID, colIdx) }
data-on:click={ datastar.DeleteSSE("/games/%s", g.ID) }

// Read client signals in handlers
var signals struct { ChatMsg string `json:"chatMsg"` }
datastar.ReadSignals(r, &signals)

// Clear input after submission
sse.MarshalAndPatchSignals(map[string]any{"chatMsg": ""})

// Redirect via SSE
sse.Redirectf("/games/%s", newGame.ID())
```

### Appending Elements (Chat Messages)

The one exception to whole-component morphing is chat, where messages are appended individually:

```go
sse.PatchElementTempl(
    chatcomponents.ChatMessage(msg, cfg),
    datastar.WithSelectorID("c4-chat-history"),
    datastar.WithModeAppend(),
)
```

### Datastar Template Attributes

- `data-signals` — declare reactive state
- `data-bind` — two-way input binding
- `data-show` — conditional visibility
- `data-class` — reactive CSS classes
- `data-morph-ignore` — prevent SSE from overwriting an element (e.g. chat input)

## Testing

```bash
task test                                          # All tests
go test -run TestHandleLogin_Success ./features/auth  # Single test
go test -v ./features/auth                         # Verbose package
```

- Use `testutil.NewTestDB(t)` for tests needing a database
- Use `testutil.NewTestSessionManager(db)` for session-aware tests
- Use `config.LoadForTest()` to set safe defaults without .env
- Tests use external test packages (`package auth_test`)

## Tech Stack

| Layer | Technology |
|-------|------------|
| Templates | templ (type-safe HTML) |
| Reactivity | Datastar Pro (SSE-driven) |
| CSS | TailwindCSS v4 + daisyUI |
| Router | chi/v5 |
| Sessions | scs/v2 (SQLite-backed) |
| Database | SQLite (modernc.org/sqlite) |
| Migrations | goose (embedded SQL) |
| SQL codegen | sqlc |
| Pub/sub | Embedded NATS (nil-payload signals) |
| Logging | zerolog + slog (bridged via slog-zerolog) |