docs: add AGENTS.md with coding guidelines for AI agents

Includes build/test commands, code style guidelines, naming conventions,
error handling patterns, and Go/templ/Datastar patterns used in this repo.

.gitea/workflows/deploy.yml

@@ -48,6 +48,8 @@ jobs:
     runs-on: games
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Need full history for git describe
 
       - name: Sync to deploy directory
         run: |
@@ -59,4 +61,8 @@ jobs:
           mkdir -p $DEPLOY_DIR/data
 
       - name: Rebuild and restart
-        run: cd $DEPLOY_DIR && docker compose up -d --build --remove-orphans
+        run: |
+          cd $DEPLOY_DIR
+          VERSION=$(git describe --tags --always)
+          COMMIT=$(git rev-parse --short HEAD)
+          VERSION=$VERSION COMMIT=$COMMIT docker compose up -d --build --remove-orphans

.gitignore

@@ -19,6 +19,7 @@
 
 !.env.example
 !LICENSE
+!AGENTS.md
 
 !assets/**/*
 

AGENTS.md

@@ -0,0 +1,253 @@
+# 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
+
+# Quality
+task test              # Run all tests: go test ./...
+task lint              # Run linter: golangci-lint run
+
+# Single test
+go test -run TestName ./path/to/package
+
+# Code generation
+task build:templ       # Compile .templ files
+task build:styles      # Build TailwindCSS
+go generate ./...      # Run sqlc for DB queries
+```
+
+## 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)
+├── features/               # Feature modules (handlers, routes, templates)
+│   ├── auth/               # Login/register
+│   ├── c4game/             # Connect 4 UI
+│   ├── snakegame/          # Snake UI
+│   ├── lobby/              # Game lobby
+│   └── common/             # Shared components, layouts
+├── chat/                   # Reusable chat room (NATS + persistence)
+├── db/                     # SQLite, migrations, sqlc queries
+├── assets/                 # Static files (embedded)
+└── config/, logging/, nats/, sessions/, router/  # Infrastructure
+```
+
+## Code Style
+
+### Imports
+
+Organize in three groups: stdlib, third-party, local. The linter enforces this.
+
+```go
+import (
+    "context"
+    "fmt"
+    "net/http"
+
+    "github.com/go-chi/chi/v5"
+    "github.com/rs/zerolog/log"
+
+    "github.com/ryanhamamura/games/connect4"
+    "github.com/ryanhamamura/games/db/repository"
+)
+```
+
+### Naming Conventions
+
+| Type | Convention | Examples |
+|------|------------|----------|
+| Files | lowercase, underscores | `config_dev.go`, `handlers.go` |
+| HTTP handlers | `Handle` prefix | `HandleGamePage`, `HandleLogin` |
+| Constructors | `New` prefix | `NewStore`, `NewRoom` |
+| Getters | `Get` prefix | `GetPlayerID`, `GetGame` |
+| Setup functions | `Setup` prefix | `SetupRoutes`, `SetupLogger` |
+| Types | PascalCase | `Game`, `Player`, `Instance` |
+| Status enums | `Status` prefix | `StatusWaitingForPlayer`, `StatusInProgress` |
+| Session keys | `Key` prefix | `KeyPlayerID`, `KeyUserID` |
+
+### Error Handling
+
+1. **Wrap errors with context:**
+   ```go
+   return fmt.Errorf("loading game %s: %w", id, err)
+   ```
+
+2. **Return (result, error) tuples:**
+   ```go
+   func loadGame(queries *repository.Queries, id string) (*Game, error)
+   ```
+
+3. **Best-effort operations** - use nolint comment:
+   ```go
+   nc.Publish(subject, nil) //nolint:errcheck // best-effort notification
+   ```
+
+4. **HTTP errors:**
+   ```go
+   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:
+  ```go
+  // Package connect4 implements Connect 4 game logic, state management, and persistence.
+  package connect4
+  ```
+- Function comments for exported functions:
+  ```go
+  // DropPiece attempts to drop a piece in the given column.
+  // Returns (row placed, success).
+  func (g *Game) DropPiece(col, playerColor int) (int, bool)
+  ```
+
+## 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) {
+        // use store, sm here
+    }
+}
+```
+
+### Mutex for Concurrent Access
+
+```go
+type Store struct {
+    games   map[string]*Instance
+    gamesMu sync.RWMutex
+}
+
+func (s *Store) Get(id string) (*Instance, bool) {
+    s.gamesMu.RLock()
+    defer s.gamesMu.RUnlock()
+    inst, ok := s.games[id]
+    return inst, ok
+}
+```
+
+### Build Tags for Environment
+
+```go
+//go:build dev
+
+//go:build !dev
+```
+
+### Embedded Filesystems
+
+```go
+//go:embed assets
+var assets embed.FS
+
+//go:embed migrations/*.sql
+var MigrationFS embed.FS
+```
+
+### Graceful Shutdown
+
+```go
+eg, egctx := errgroup.WithContext(ctx)
+eg.Go(func() error { return server.ListenAndServe() })
+eg.Go(func() error {
+    <-egctx.Done()
+    return server.Shutdown(context.Background())
+})
+return eg.Wait()
+```
+
+## Templ + Datastar Patterns
+
+### SSE Connection with Disabled Cancellation
+
+Datastar cancels SSE on user interaction by default. Disable for persistent connections:
+
+```go
+data-init={ fmt.Sprintf("@get('/games/%s/events',{requestCancellation:'disabled'})", g.ID) }
+```
+
+### Prevent Script Duplication on SSE Patches
+
+Use `templ.NewOnceHandle()` for scripts in components that get patched:
+
+```go
+var scriptHandle = templ.NewOnceHandle()
+
+templ MyComponent() {
+    <div id="my-component">...</div>
+    @scriptHandle.Once() {
+        @myScript()
+    }
+}
+```
+
+### Conditional Classes with templ.KV
+
+```go
+class={
+    "status status-sm",
+    templ.KV("status-success", isConnected),
+    templ.KV("status-error", !isConnected),
+}
+```
+
+### Datastar SSE Responses
+
+```go
+sse := datastar.NewSSE(w, r)
+sse.MergeFragmentTempl(components.GameBoard(game))
+```
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|------------|
+| Templates | templ (type-safe HTML) |
+| Reactivity | Datastar (SSE-driven) |
+| CSS | TailwindCSS v4 + daisyUI |
+| Router | chi/v5 |
+| Sessions | scs/v2 |
+| Database | SQLite (modernc.org/sqlite) |
+| Migrations | goose |
+| SQL codegen | sqlc |
+| Pub/sub | Embedded NATS |
+| Logging | zerolog |
+
+## Testing
+
+```bash
+# All tests
+task test
+
+# Single test
+go test -run TestDropPiece ./connect4
+
+# With verbose output
+go test -v -run TestDropPiece ./connect4
+
+# Test a package
+go test ./connect4/...
+```
+
+Use `testutil.SetupTestDB()` for tests requiring database access.

Dockerfile

@@ -1,6 +1,9 @@
 FROM docker.io/golang:1.25.4-alpine AS build
 
-RUN apk add --no-cache upx git
+ARG VERSION=dev
+ARG COMMIT=unknown
+
+RUN apk add --no-cache upx
 
 WORKDIR /src
 COPY go.mod go.sum ./
@@ -10,9 +13,8 @@ COPY . .
 RUN go tool templ generate
 RUN go tool gotailwind -i assets/css/input.css -o assets/css/output.css --minify
 RUN --mount=type=cache,target=/root/.cache/go-build \
-    VERSION=$(git describe --tags --always) && \
-    COMMIT=$(git rev-parse --short HEAD) && \
-    CGO_ENABLED=0 go build -ldflags="-s -X github.com/ryanhamamura/games/version.Version=$VERSION -X github.com/ryanhamamura/games/version.Commit=$COMMIT" -o /bin/games .
+    MODULE=$(head -1 go.mod | awk '{print $2}') && \
+    CGO_ENABLED=0 go build -ldflags="-s -X $MODULE/version.Version=$VERSION -X $MODULE/version.Commit=$COMMIT" -o /bin/games .
 RUN upx -9 -k /bin/games
 
 FROM scratch

chat/chat.go

@@ -76,12 +76,11 @@ func (r *Room) Send(msg Message) {
 	}
 }
 
-// Receive processes an incoming NATS message, appending it to the buffer.
-// Returns the new message and a snapshot of all messages.
-func (r *Room) Receive(data []byte) (Message, []Message) {
+// receive processes an incoming NATS message, appending it to the buffer.
+func (r *Room) receive(data []byte) (Message, bool) {
 	var msg Message
 	if err := json.Unmarshal(data, &msg); err != nil {
-		return msg, nil
+		return msg, false
 	}
 
 	r.mu.Lock()
@@ -89,11 +88,9 @@ func (r *Room) Receive(data []byte) (Message, []Message) {
 	if len(r.messages) > maxMessages {
 		r.messages = r.messages[len(r.messages)-maxMessages:]
 	}
-	snapshot := make([]Message, len(r.messages))
-	copy(snapshot, r.messages)
 	r.mu.Unlock()
 
-	return msg, snapshot
+	return msg, true
 }
 
 // Messages returns a snapshot of the current message buffer.
@@ -105,15 +102,32 @@ func (r *Room) Messages() []Message {
 	return snapshot
 }
 
-// Subscribe creates a NATS channel subscription for the room's subject.
-// Caller is responsible for unsubscribing.
-func (r *Room) Subscribe() (chan *nats.Msg, *nats.Subscription, error) {
-	ch := make(chan *nats.Msg, 64)
-	sub, err := r.nc.ChanSubscribe(r.subject, ch)
+// Subscribe returns a channel of parsed messages and a cleanup function.
+// The room handles NATS subscription internally and buffers messages.
+func (r *Room) Subscribe() (<-chan Message, func()) {
+	natsCh := make(chan *nats.Msg, 64)
+	msgCh := make(chan Message, 64)
+
+	sub, err := r.nc.ChanSubscribe(r.subject, natsCh)
 	if err != nil {
-		return nil, nil, err
+		close(msgCh)
+		return msgCh, func() {}
 	}
-	return ch, sub, nil
+
+	go func() {
+		for natsMsg := range natsCh {
+			if msg, ok := r.receive(natsMsg.Data); ok {
+				msgCh <- msg
+			}
+		}
+		close(msgCh)
+	}()
+
+	cleanup := func() {
+		_ = sub.Unsubscribe()
+	}
+
+	return msgCh, cleanup
 }
 
 func (r *Room) saveMessage(msg Message) {

chat/components/chat.templ

@@ -23,16 +23,21 @@ type Config struct {
 	StopKeyPropagation bool
 }
 
-templ Chat(messages []chat.Message, cfg Config) {
-	<div id={ cfg.CSSPrefix + "-chat" } class={ cfg.CSSPrefix + "-chat" }>
-		<div class={ cfg.CSSPrefix + "-chat-history" }>
-			for _, m := range messages {
+// ChatMessage renders a single chat message. Used for appending new messages via SSE.
+templ ChatMessage(m chat.Message, cfg Config) {
 	<div class={ cfg.CSSPrefix + "-chat-msg" }>
 		<span style={ fmt.Sprintf("color:%s;font-weight:bold;", cfg.Color(m.Slot)) }>
 			{ m.Nickname + ": " }
 		</span>
 		<span>{ m.Message }</span>
 	</div>
+}
+
+templ Chat(messages []chat.Message, cfg Config) {
+	<div id={ cfg.CSSPrefix + "-chat" } class={ cfg.CSSPrefix + "-chat" }>
+		<div id={ cfg.CSSPrefix + "-chat-history" } class={ cfg.CSSPrefix + "-chat-history" }>
+			for _, m := range messages {
+				@ChatMessage(m, cfg)
 			}
 		</div>
 		<div class={ cfg.CSSPrefix + "-chat-input" } data-morph-ignore>

docker-compose.yml

@@ -1,6 +1,10 @@
 services:
   games:
-    build: .
+    build:
+      context: .
+      args:
+        VERSION: ${VERSION:-dev}
+        COMMIT: ${COMMIT:-unknown}
     container_name: games
     restart: unless-stopped
     ports:

features/c4game/handlers.go

@@ -16,6 +16,7 @@ import (
 	"github.com/ryanhamamura/games/connect4"
 	"github.com/ryanhamamura/games/db/repository"
 	"github.com/ryanhamamura/games/features/c4game/pages"
+	sharedcomponents "github.com/ryanhamamura/games/features/common/components"
 	"github.com/ryanhamamura/games/sessions"
 )
 
@@ -118,11 +119,21 @@ func HandleGameEvents(store *connect4.Store, nc *nats.Conn, sm *scs.SessionManag
 			return sse.PatchElementTempl(pages.GameContent(g, myColor, room.Messages(), chatCfg))
 		}
 
-		// Send initial render
+		sendPing := func() error {
+			return sse.PatchElementTempl(sharedcomponents.ConnectionIndicator(time.Now().UnixMilli()))
+		}
+
+		// Send initial render and ping
+		if err := sendPing(); err != nil {
+			return
+		}
 		if err := patchAll(); err != nil {
 			return
 		}
 
+		heartbeat := time.NewTicker(15 * time.Second)
+		defer heartbeat.Stop()
+
 		// Subscribe to game state updates
 		gameCh := make(chan *nats.Msg, 64)
 		gameSub, err := nc.ChanSubscribe(connect4.GameSubject(gameID), gameCh)
@@ -132,24 +143,29 @@ func HandleGameEvents(store *connect4.Store, nc *nats.Conn, sm *scs.SessionManag
 		defer gameSub.Unsubscribe() //nolint:errcheck
 
 		// Subscribe to chat messages
-		chatCh, chatSub, err := room.Subscribe()
-		if err != nil {
-			return
-		}
-		defer chatSub.Unsubscribe() //nolint:errcheck
+		chatCh, cleanupChat := room.Subscribe()
+		defer cleanupChat()
 
 		ctx := r.Context()
 		for {
 			select {
 			case <-ctx.Done():
 				return
+			case <-heartbeat.C:
+				if err := sendPing(); err != nil {
+					return
+				}
 			case <-gameCh:
 				if err := patchAll(); err != nil {
 					return
 				}
-			case msg := <-chatCh:
-				room.Receive(msg.Data)
-				if err := patchAll(); err != nil {
+			case chatMsg := <-chatCh:
+				err := sse.PatchElementTempl(
+					chatcomponents.ChatMessage(chatMsg, chatCfg),
+					datastar.WithSelectorID("c4-chat-history"),
+					datastar.WithModeAppend(),
+				)
+				if err != nil {
 					return
 				}
 			}

features/c4game/pages/game.templ

@@ -18,6 +18,7 @@ templ GamePage(g *connect4.Game, myColor int, messages []chat.Message, chatCfg c
 			data-signals="{chatMsg: ''}"
 			data-init={ fmt.Sprintf("@get('/games/%s/events',{requestCancellation:'disabled'})", g.ID) }
 		>
+			@sharedcomponents.ConnectionIndicator(0)
 			@GameContent(g, myColor, messages, chatCfg)
 		</main>
 	}

features/common/components/shared.templ

@@ -1,6 +1,10 @@
 package components
 
-import "github.com/starfederation/datastar-go/datastar"
+import (
+	"fmt"
+
+	"github.com/starfederation/datastar-go/datastar"
+)
 
 templ BackToLobby() {
 	<a class="link text-sm opacity-70" href="/">&larr; Back</a>
@@ -44,6 +48,62 @@ templ NicknamePrompt(returnPath string) {
 	</main>
 }
 
+func isStale(lastPing int64) bool {
+	return lastPing == 0
+}
+
+var connectionWatcherHandle = templ.NewOnceHandle()
+
+// ConnectionIndicator shows a small dot indicating SSE connection status.
+// Server patches this with a timestamp; client JS detects staleness.
+templ ConnectionIndicator(lastPing int64) {
+	<div
+		id="connection-indicator"
+		class="fixed top-2 right-2"
+		data-last-ping={ fmt.Sprintf("%d", lastPing) }
+	>
+		<div class="inline-grid *:[grid-area:1/1]">
+			<div
+				id="connection-ping"
+				class={
+					"status status-sm",
+					templ.KV("status-success animate-ping", !isStale(lastPing)),
+					templ.KV("status-error", isStale(lastPing)),
+				}
+			></div>
+			<div
+				id="connection-dot"
+				class={
+					"status status-sm",
+					templ.KV("status-success", !isStale(lastPing)),
+					templ.KV("status-error", isStale(lastPing)),
+				}
+			></div>
+		</div>
+	</div>
+	@connectionWatcherHandle.Once() {
+		@connectionWatcher()
+	}
+}
+
+script connectionWatcher() {
+	setInterval(function() {
+		var el = document.getElementById('connection-indicator');
+		var dot = document.getElementById('connection-dot');
+		var ping = document.getElementById('connection-ping');
+		if (!el || !dot || !ping) return;
+		
+		var lastPing = parseInt(el.dataset.lastPing, 10) || 0;
+		var stale = Date.now() - lastPing > 20000;
+		
+		dot.classList.toggle('status-success', !stale);
+		dot.classList.toggle('status-error', stale);
+		ping.classList.toggle('status-success', !stale);
+		ping.classList.toggle('status-error', stale);
+		ping.classList.toggle('animate-ping', !stale);
+	}, 1000);
+}
+
 templ GameJoinPrompt(loginURL string, registerURL string, gamePath string) {
 	<main class="max-w-sm mx-auto mt-8 text-center">
 		<h1 class="text-3xl font-bold">Join Game</h1>

features/snakegame/handlers.go

@@ -4,6 +4,7 @@ import (
 	"fmt"
 	"net/http"
 	"strconv"
+	"time"
 
 	"github.com/alexedwards/scs/v2"
 	"github.com/go-chi/chi/v5"
@@ -12,6 +13,7 @@ import (
 
 	"github.com/ryanhamamura/games/chat"
 	chatcomponents "github.com/ryanhamamura/games/chat/components"
+	sharedcomponents "github.com/ryanhamamura/games/features/common/components"
 	"github.com/ryanhamamura/games/features/snakegame/pages"
 	"github.com/ryanhamamura/games/sessions"
 	"github.com/ryanhamamura/games/snake"
@@ -123,11 +125,21 @@ func HandleSnakeEvents(snakeStore *snake.SnakeStore, nc *nats.Conn, sm *scs.Sess
 			return sse.PatchElementTempl(pages.GameContent(sg, mySlot, chatMessages(), chatCfg, gameID))
 		}
 
-		// Send initial render
+		sendPing := func() error {
+			return sse.PatchElementTempl(sharedcomponents.ConnectionIndicator(time.Now().UnixMilli()))
+		}
+
+		// Send initial render and ping
+		if err := sendPing(); err != nil {
+			return
+		}
 		if err := patchAll(); err != nil {
 			return
 		}
 
+		heartbeat := time.NewTicker(15 * time.Second)
+		defer heartbeat.Stop()
+
 		// Subscribe to game updates via NATS
 		gameCh := make(chan *nats.Msg, 64)
 		gameSub, err := nc.ChanSubscribe(snake.GameSubject(gameID), gameCh)
@@ -137,15 +149,12 @@ func HandleSnakeEvents(snakeStore *snake.SnakeStore, nc *nats.Conn, sm *scs.Sess
 		defer gameSub.Unsubscribe() //nolint:errcheck
 
 		// Chat subscription (multiplayer only)
-		var chatCh chan *nats.Msg
-		var chatSub *nats.Subscription
+		var chatCh <-chan chat.Message
+		var cleanupChat func()
 
 		if room != nil {
-			chatCh, chatSub, err = room.Subscribe()
-			if err != nil {
-				return
-			}
-			defer chatSub.Unsubscribe() //nolint:errcheck
+			chatCh, cleanupChat = room.Subscribe()
+			defer cleanupChat()
 		}
 
 		ctx := r.Context()
@@ -154,6 +163,11 @@ func HandleSnakeEvents(snakeStore *snake.SnakeStore, nc *nats.Conn, sm *scs.Sess
 			case <-ctx.Done():
 				return
 
+			case <-heartbeat.C:
+				if err := sendPing(); err != nil {
+					return
+				}
+
 			case <-gameCh:
 				// Drain backed-up game updates
 				for {
@@ -168,12 +182,16 @@ func HandleSnakeEvents(snakeStore *snake.SnakeStore, nc *nats.Conn, sm *scs.Sess
 					return
 				}
 
-			case msg := <-chatCh:
-				if msg == nil {
+			case chatMsg, ok := <-chatCh:
+				if !ok {
 					continue
 				}
-				room.Receive(msg.Data)
-				if err := patchAll(); err != nil {
+				err := sse.PatchElementTempl(
+					chatcomponents.ChatMessage(chatMsg, chatCfg),
+					datastar.WithSelectorID("snake-chat-history"),
+					datastar.WithModeAppend(),
+				)
+				if err != nil {
 					return
 				}
 			}

features/snakegame/pages/game.templ

@@ -37,6 +37,7 @@ templ GamePage(sg *snake.SnakeGame, mySlot int, messages []chat.Message, chatCfg
 			data-on:keydown__throttle.100ms={ keydownScript(gameID) }
 			tabindex="0"
 		>
+			@components.ConnectionIndicator(0)
 			@GameContent(sg, mySlot, messages, chatCfg, gameID)
 		</main>
 	}