# progetto2

`progetto2` ospita un **client MUD CLI** pensato per collegarsi a un MUD
LP‑MUD basato sul driver **FluffOS** (per esempio **Dead Souls**, libreria
3.8.6). Il client parla telnet con estensioni standard: `ECHO`, `NAWS`,
`TTYPE`, e rifiuta (`WONT`) tutte le altre (`GMCP`, `MSDP`, `MCCP`, `MXP`
per ora). Tiene traccia delle stanze visitate e le renderizza come **mappa
ASCII** on-demand.

## Requisiti

- Python ≥ 3.10
- Una libreria Python: [`prompt_toolkit`](https://pypi.org/project/prompt-toolkit/) ≥ 3.0

## Setup

```bash
cd progetto2
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

Verrà installato il comando `mudclient`.

## Uso

```bash
# Default: si collega a localhost:6666 con un finestra iniziale 120×40
mudclient

# Espliciti
mudclient --host localhost --port 6666 --cols 120 --rows 40

# Auto-login: passa il nome; il client lo invia quando il server chiede
# "What name do you wish?". Se serve la password, il client chiede
# /password PWD oppure la puoi passare con --password (o env MUDCLIENT_PASSWORD).
mudclient --user zork --password hunter2

# Log di sessione: ogni evento (testo, GMCP, stanze, comandi locali, linee inviate)
# viene serializzato in append‑only, flushed dopo ogni write — adatto a `tail -f`.
mudclient --log-json ~/mud-session.jsonl --log-md ~/mud-session.md
```

> I file `--log-json` / `--log-md` vengono **truncati** all'apertura:
> ogni nuova sessione ricomincia da zero. Per ruotare manualmente
> prima della sessione:
> ```bash
> mv ~/mud-session.jsonl{,.prev} && mudclient --log-json ~/mud-session.jsonl
> ```

Schema eventi (un oggetto JSON per riga):

| `kind` | Scopo | Note |
| --- | --- | --- |
| `session_start` | apertura sessione | `host`, `port`, `user` |
| `session_end` | chiusura normale | `reason` |
| `disconnect` | chiusura socket | `reason` |
| `text` | chunk ANSI ricevuto dal server | `raw` preservato |
| `room_enter` | mapper ha registrato una stanza | `id`, `name`, `exits` |
| `gmcp` | frame GMCP accettato | `module`, `payload` |
| `vitals` | snapshot hp/sp/mv | solo i campi presenti |
| `line_sent` | riga inoltrata al MUD | password redatte (`***`) |
| `local_cmd` | comando `/...` intercettato | password/segreti redatti |
| `login` | prompt/risposta auto-login | `value` redatto di default; passare `redact=False` per i nomi account |

Una volta connesso:

| Tasto | Effetto |
| --- | --- |
| Testo qualsiasi | inviato al MUD terminato da `\r\n` |
| `/map` | disegna la mappa ASCII delle stanze visitate (multi-source BFS) |
| `/where` | mostra la stanza corrente e le uscite |
| `/look` | invia `look` al MUD |
| `/vitals` | mostra hp/sp/mv (via GMCP `Char.Vitals`) |
| `/stats` | locali scoperti, GMCP stato, vitali |
| `/password PWD` | invia una password al MUD |
| `/clear` | pulisce lo schermo |
| `/help` (`/?`) | mostra l'aiuto |
| `/quit` (`/q`, `Ctrl‑D`) | esce |

Il prompt è sempre del tipo:

```
[NomeStanza]> _
```

con il nome della stanza corrente in cyan brillante. In basso c'è una **status bar** che mostra:

```
[stanza: Outer Courtyard]   [GMCP: on]   HP 100/100  SP 50/50  MV 80/80
```

Quando il server invia `Char.Vitals` via GMCP, hp/sp/mv compaiono automaticamente.

## Layout dei sorgenti

```
progetto2/
├── pyproject.toml         # metadata + dipendenze + entry point `mudclient`
├── README.md              # questo file
├── .gitignore
├── docs/                  # documentazione completa (vedi sotto)
│   ├── README.md          # indice della cartella docs
│   ├── architecture.md    # analisi architetturale (data flow + boundary)
│   ├── modules.md         # descrizione modulo‑per‑modulo
│   ├── protocol.md        # telnet, GMCP, ANSI, euristiche Dead Souls
│   ├── usage.md           # flag CLI, esempi, auto‑login, comandi slash
│   ├── events.md          # schema eventi del logger
│   ├── development.md     # setup dev, pytest, ruff, come estendere
│   └── gitea.md           # flusso di pubblicazione sul Gitea + sicurezza token
├── src/progetto2/         # package
│   ├── __init__.py
│   ├── __main__.py        # supporta `python -m progetto2`
│   ├── cli.py             # entry point + UI a riga di comando
│   ├── telnet.py          # state machine IAC + asyncio
│   ├── deadsouls.py       # parser di stanze Dead Souls / LP‑MUD
│   ├── gmcp.py            # parser GMCP (Char.Vitals / Room.Info)
│   ├── mapper.py          # grafo delle stanze + render ASCII
│   ├── logger.py          # EventLogger (JSONL + Markdown sinks)
│   └── ansi.py            # stripper ANSI per il parser
└── tests/                 # unit test (pytest)
    ├── test_telnet.py
    ├── test_ansi.py
    ├── test_deadsouls.py
    ├── test_mapper.py
    └── test_logger.py
```

## 📚 Documentazione completa

La documentazione vive nella cartella [`docs/`](./docs/README.md) e
copre:

- **[`docs/architecture.md`](./docs/architecture.md)** — analisi
  architetturale completa: dipendenze tra moduli, data flow di un
  frame dal server, boundary concerns, refactor raccomandati.
- **[`docs/modules.md`](./docs/modules.md)** — cosa fa ogni modulo,
  API pubblica, responsabilità, tolleranze.
- **[`docs/protocol.md`](./docs/protocol.md)** — IAC state machine,
  GMCP wire format, euristiche Dead Souls, ANSI handling.
- **[`docs/usage.md`](./docs/usage.md)** — riferimento flag CLI, esempi
  pratici, flusso auto‑login, comandi slash, rotazione log.
- **[`docs/events.md`](./docs/events.md)** — schema completo degli
  eventi del logger (JSONL + Markdown), regole di redazione, esempi
  `jq`.
- **[`docs/development.md`](./docs/development.md)** — workflow
  sviluppatore: setup, test, lint, come aggiungere moduli, debugging.
- **[`docs/gitea.md`](./docs/gitea.md)** — flusso di pubblicazione sul
  server Gitea `192.168.0.183:8085` (utente `truetype`) **+ regole di
  sicurezza del token**.

## Note sul protocollo

Il client negozia:

- `ECHO`: invia `WILL ECHO` in risposta a `DO ECHO`. Il server non eseguirà
  più echo remoto, mentre l'eco locale è gestita da `prompt_toolkit`.
- `NAWS`: se attivo, invia la dimensione della finestra iniziale.
- `TTYPE`: risponde con `XTERM-256COLOR` quando il server lo richiede.
- `GMCP`: viene **offerto proattivamente** (`WILL` al connect). Dead Souls
  lo accetta e invia pacchetti `Char.Vitals`, `Room.Info`, `Char.Login`,
  ecc. Quando una stanza arriva via `Room.Info`, si usa il `num`
  (vnum) del server come id stabile della stanza.

Le righe di stato del parser considerano `IAC GA` (`249`) e `IAC EOR`
(`239`) come delimitatori di "record/prompt", così da poter chiudere un
blocco di stanza anche quando il prompt testuale non è immediatamente
riconoscibile.

La rilevazione automatica della geometria del mondo si basa sul **movimento
inviato dall'utente** + **descrizione della stanza** osservata subito
dopo: quando digiti `n`, il client informa il mapper; quando la risposta
del MUD arriva, `Mapper.visit()` collega automaticamente
`corrente → nuova` lungo la direzione digitata.

Il render della mappa è un **multi-source BFS** dal current room, con
fallback di **posizionamento orfano** per le stanze visitate in sequenza
indietro (es. `n→s`) e stack nell'angolo in basso a destra per stanze
completamente isolate.

## Limitazioni note (v0.2)

- **MSDP / MCCP / MCP / MXP** non sono ancora abilitati: una sessione che
  li richiede ottiene `WONT` dal nostro lato. Dead Souls usa GMCP, che è
  ben coperto; altri MUD basati su MSDP possono essere aggiunti seguendo
  lo schema di `gmcp.py`.
- La detection delle stanze **senza GMCP** resta **euristica** sul testo.
- **Login automatico**: il client riconosce il prompt `What name do you
  wish?` / `Password:` e invia automaticamente solo la prima volta.
  Per la password senza `--password` viene mostrato un suggerimento
  `usa /password <pwd>` (niente prompt annidato, troppo fragile).
- Gli `u`/`d` (verticali) sono rappresentati nella mappa ma non
  influenzano le coordinate 2D (offset `(0,0)`).
- La status bar si aggiorna ad ogni rilettura della riga del prompt;
  per refresh continui in idle si può aggiungere `refresh_interval`
  al `PromptSession` come estensione futura.

## Sviluppo

```bash
pip install -e ".[dev]"
pytest          # gira tutta la suite
ruff check src tests   # lint
```

## Licenza

MIT per il codice del client. Il server **Dead Souls** non è GPL — assicurati
di rispettarne la licenza prima di redistribuirlo.