# Chess CLI Client Documentation

The chess client is an interactive command-line debugging tool for the chess server API. It provides a rich terminal interface with colored output, command completion, and session management.

## Features

- Interactive shell with readline support and command history
- Comprehensive command set for game operations and debugging
- User authentication with JWT token management
- Colored board visualization and game state display
- Session persistence across commands
- Verbose mode for detailed API request/response inspection
- Long-polling support for real-time game updates

## Replay Foundation

The Go API client exposes `GetGameHistory(gameID)`, `GetGamePGN(gameID, ply)`,
and `GetMyGames(limit, cursor)`, including durable result, timestamps, player
claims, move count, ordered UCI and SAN moves, and FEN after every move. The
`games` and `pgn` commands use them; step-by-step `replay` controls are still
planned, see [Replay Implementation Tasks](./todo.md).

## Building
```bash
go build ./cmd/chess-client-cli
# or with make: make build client
```

## Running
```bash
# Connect to default server (localhost:8080)
./chess-client-cli
# if built with make: bin/chess-client-cli

# The client starts with an interactive prompt
chess > 
```

### Prompt States

The prompt dynamically updates to show context:
- `chess` - Base prompt
- `chess [username]` - Authenticated user
- `chess [username - gameId]` - User in active game
- `chess [username - gameId] White` - Shows player color
- Turn indicator with player type (h=human, c=computer)

## Command Reference

### Authentication Commands

#### `register` / `r`
Register new user account.
```
chess > register
Username: alice
Password: ********
Email (optional): alice@example.com
```

#### `login` / `l`
Authenticate with existing account.
```
chess > login
Username or Email: alice
Password: ********
```

#### `logout` / `o`
Clear authentication token.
```
chess > logout
```

#### `whoami` / `i`
Display current authenticated user.
```
chess > whoami
```

#### `user` / `e`
Set user ID manually (for display only, doesn't authenticate).
```
chess > user 550e8400-e29b-41d4-a716-446655440000
```

### Game Commands

#### `new` / `n`
Create new game interactively.
```
chess > new
White player type (h/c) [h]: h
Black player type (h/c) [h]: c
Computer level (0-20) [10]: 15
Search time (100-10000ms) [1000]: 2000
Starting position (FEN) [default]: 
```

#### `join` / `j`
Set current game context.
```
chess > join a1b2c3d4-e5f6-7890-1234-567890abcdef
```

#### `move` / `m`
Make chess move in UCI notation. Castling is the king's move (`e1g1`); a
promotion appends the piece letter (`q`, `r`, `b`, or `n`).
```
chess > move e2e4
chess > move e7e5
chess > move g7g8q
```

#### `computer` / `c`
Trigger computer move calculation.
```
chess > computer
```

#### `undo` / `u`
Undo one or more moves. Refused when another user claimed a side (players
cannot take back each other's moves) and after a resignation or agreed draw
between two humans. Against the computer a resignation can be undone; the
client notes that it stays on record.
```
chess > undo       # Undo last move
chess > undo 3     # Undo last 3 moves
```

#### `show` / `h`
Display board and game state with colored pieces, the result, and any
pending draw offer.
```
chess > show
```

#### `state` / `s`
Show raw game JSON response.
```
chess > state
```

#### `delete` / `d`
Unload a live game from server memory. Durable history remains available.
```
chess > delete              # Unload current live game
chess > delete <gameId>      # Unload specific live game
```

#### `poll` / `p`
Long-poll for game updates (waits up to 30 seconds). Returns on a move, an
undo, a result (a resignation or an accepted draw), or a draw offer, and
prints the outcome or offer. In a two-player game, `poll` is how you learn
that the opponent moved, offered a draw, or resigned.
```
chess > poll
```

#### `resign`
Resign the current game. The side may be omitted when you play one human side
(or claimed one); name it in a hot-seat game.
```
chess > resign
chess > resign b
```

#### `draw`
Offer (the default), accept, or decline a draw. A computer answers an offer
at once; a human opponent sees the offer in their next response, and it
lapses if they move instead of answering.
```
chess > draw              # offer
chess > draw accept b
chess > draw decline w
```

Game outcomes print with how they were reached, e.g. `DRAW by threefold
repetition.` or `Black wins by resignation.`; a pending offer is shown as
`White offers a draw`.

#### `games` / `g`
List your stored games, newest first, 20 per page (requires login). The
result column is the PGN token (`1-0`, `0-1`, `1/2-1/2`, `*`).
```
chess > games        # Newest games
chess > games more   # Next page
```

#### `pgn`
Print a stored game as PGN (SAN movetext, standard tags).
```
chess > pgn                  # Current game, every ply
chess > pgn 10               # Current game, first 10 plies
chess > pgn <gameId> [ply]   # Another game
```

### Debug Commands

#### `health` / `.`
Check server health status.
```
chess > health
```

#### `url` / `/`
Get or set API base URL.
```
chess > url                           # Show current URL
chess > url http://localhost:9090     # Change server URL
```

#### `raw` / `:`
Send raw API request.
```
chess > raw GET /api/games/<id>
chess > raw POST /api/games '{"white":{"type":1},"black":{"type":2}}'
```

#### `clear` / `-`
Clear terminal screen.
```
chess > clear
```

#### `help` / `?`
Display available commands or specific command usage.
```
chess > help          # Show all commands
chess > help move     # Show move command details
```

#### `exit` / `x`
Exit the client.
```
chess > exit
```

### Verbose Mode

Append `-v` flag to any command for detailed output:
```
chess > move e2e4 -v
```

Shows full HTTP request/response with formatted JSON bodies.

## Session Management

The client maintains session state including:
- API base URL
- Current game ID
- Authentication token
- Username and user ID
- Last move count (for polling)
- Current game state
- Player color assignment

Session state persists across commands within the same client instance.

## Display Features

### Colored Output
- **Blue**: White pieces, API requests, prompts
- **Red**: Black pieces, errors
- **Green**: Success messages
- **Yellow**: Warnings, input prompts
- **Magenta**: Computer moves, usernames
- **Cyan**: Information, file coordinates
- **White**: Game IDs

### Board Visualization
ASCII board with colored pieces:
```
  a b c d e f g h
8 r n b q k b n r 8
7 p p p p p p p p 7
6 . . . . . . . . 6
5 . . . . . . . . 5
4 . . . . P . . . 4
3 . . . . . . . . 3
2 P P P P . P P P 2
1 R N B Q K B N R 1
  a b c d e f g h
```

### Move History
Displayed in UCI notation with move numbers:
```
History: 1.e2e4 e7e5 2.g1f3 b8c6 3.f1b5
```

## Workflows

### Authenticated Game Creation
1. Register or login to obtain token
2. Create game (human players automatically associated with user)
3. Make moves with authentication context
4. Games persist with user association

### Computer vs Computer Observation
1. Create game with both players as computer
2. Use polling to watch moves in real-time
3. Board updates automatically as engines calculate

### Debug Server Testing
1. Set verbose mode for request inspection
2. Use raw command for custom API calls
3. Health endpoint for connectivity verification
4. URL switching for multi-server testing

## Configuration

### Environment
- History file: `.chess_history` in working directory
- Default API URL: `http://localhost:8080`
- Timeout: 30 seconds for HTTP requests

### Limitations
- No move validation in client (server validates)
- No algebraic notation input (UCI format only)
- Single game context at a time
- No persistent authentication across restarts

## Error Handling

The client displays server errors with color coding:
- Red text for error messages
- Error codes for specific failures
- Details when available

Common error codes:
- `GAME_NOT_FOUND` - Invalid game ID
- `INVALID_MOVE` - Illegal chess move
- `NOT_HUMAN_TURN` - Wrong player type
- `GAME_OVER` - Game already ended
- `RATE_LIMIT_EXCEEDED` - Too many requests

## Development

The client architecture follows a command pattern with:
- **Registry**: Central command dispatcher
- **Session**: State management interface
- **API Client**: HTTP communication layer
- **Display**: Terminal formatting utilities
- **Commands**: Modular command handlers

Extensions can add new commands by registering handlers in the appropriate command group (game, auth, debug).