chess/doc/client.md

# 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

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`, `pgn` and `replay` commands use them. A replay renders the stored
FEN of each ply; the client never computes a move.

## 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)
- `chess [...] replay 12/40` - Replaying a stored game at ply 12 of 40

## 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), numbered
for `replay <#>` and `games delete <#>`. The result column is the PGN token
(`1-0`, `0-1`, `1/2-1/2`, `*`). Deleting a game you alone hold removes it
with its moves; a game another player also claims is only released from
your list.
```
chess > games              # Newest games
chess > games more         # Next page
chess > games delete 3     # Remove the third game of the last listing (or an ID)
```

#### `import`
Store a PGN file (one game) under your account, for replay with `replay`.
The server checks every move; tags such as `White`, `Black`, `Event` and
`Date` are kept. Not available in the browser build, which has no files;
the web board imports a pasted PGN instead.
```
chess > import games/fischer-spassky-1972-1.pgn
```

#### `pgn`
Print a stored game as PGN (SAN movetext, standard tags), or save it with
`save <path>`. During a replay the default is the replayed game up to the
current ply.
```
chess > pgn                        # Current game, every ply
chess > pgn 10                     # Current game, first 10 plies
chess > pgn <gameId> [ply]         # Another game
chess > pgn save game.pgn          # Write instead of print
```
In the browser build there is no file system: `save` prints the PGN to copy.

### Replay Commands

A replay steps through a stored game's history: any game by ID (histories
are public to holders of the ID), or one of your own by its number in the
last `games` listing. The replay is separate from the live session: the
current game, login and poll position are kept, and `new`, `join`, `move`,
`computer`, `undo`, `delete`, `poll`, `resign` and `draw` are refused until
`live` ends the replay.

#### `replay`
Load a stored game and show its initial position, the players, the result,
and the whole move list.
```
chess > replay 2                                      # From the last 'games' page
chess > replay a1b2c3d4-e5f6-7890-1234-567890abcdef   # Any stored game
```

#### `next` / `>`, `prev` / `<`, `first`, `last`, `goto`
Move through the line; each prints the board, the ply, and the move that
led to it (`2... Nf6`). `next` and `prev` take a count.
```
chess > next
chess > next 4
chess > prev
chess > goto 12
chess > last
chess > first
```

#### `auto`
Play forward from the current ply to the end of the line, one board per ply,
with a delay in milliseconds (default 1000).
```
chess > auto        # one ply a second
chess > auto 250
```

#### `fen`
Print the FEN of the current position.
```
chess > fen
```

#### `show` / `h` while replaying
Shows the replayed position instead of the live game.

#### `live`
Leave the replay and return to the live session.
```
chess > live
```

### 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
```

### Long output

`help`, `games`, `pgn`, `state`, `show` and `replay` print one screen at a
time when their output is taller than the terminal: `-- More (N lines left;
Enter continues, q quits) --`. The terminal's size comes from the TTY, or in
the browser from xterm.js; output piped to another program is never paged.

### 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
The live game's history is displayed in UCI notation with move numbers:
```
History: 1.e2e4 e7e5 2.g1f3 b8c6 3.f1b5
```
A replay lists the stored game in SAN, with the current ply in brackets:
```
1. e4 c5 2. [Nf3] Nf6 3. Nc3 e6
```

## 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 (plus one replay)
- No persistent authentication across restarts
- `auto` runs to the end of the line; it cannot be interrupted

## 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).