docs: přidat CLAUDE.md s přehledem architektury a příkazů

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

.gitignore

@@ -1,2 +1,5 @@
 __pycache__/
-*.pyc
+*.pyc
+dist/
+build/
+*.egg-info/

CLAUDE.md

@@ -0,0 +1,44 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project
+
+`kostky` is a Czech-language terminal CLI game — a Farkle/"tisícovky" dice game variant for multiple players. Single runtime dependency: `tabulate` (for the final results table).
+
+## Commands
+
+```bash
+pip install -e ".[dev]"   # editable install with mypy + ruff
+kostky                     # run the game (after install)
+python -m kostky           # run without installing (requires tabulate)
+mypy                        # type-check (strict mode, see pyproject.toml)
+ruff check .                 # lint
+```
+
+There are no tests in this repository.
+
+## Architecture
+
+The entire game lives in `kostky/kostky.py` as a single module with module-level mutable state (no classes):
+
+- `hodnoty: dict[str, int]` — scoring table, loaded at import time from `kostky/hodnoty.csv` via `importlib.resources`. Keys are sorted-digit strings representing dice combos (e.g. `"111"` = three ones), values are point totals.
+- `players: dict[str, list[int]]` — per-player history of per-turn scores (insertion order == turn order).
+- `aggr: dict[str, int]` — per-player running total, used for win checks and the results table.
+- `pointer` / `first` — current player's name / the player who started the round (used to detect when a full round has completed in `next_player`/`check_win`).
+- `score` — points accumulated *within the current turn*, reset on bust or on banking (`k`).
+- `h_bool` — guards re-rolling: you can't roll again until you've banked at least one scoring combination in the current roll sequence.
+
+Control flow is a manual state machine driven by tuples, not exceptions or return codes:
+
+- `evaluate(inp, count, throw)` parses a single line of user input against the current dice state and returns a `data` tuple whose first element is a tag: `"count"` (continue turn with N remaining dice and a throw string), `"msg"` (show an error/message, possibly re-prompting), `"win"`, or `"exit"`.
+- `game(data)` is the main loop: it pattern-matches on `data[0]`, prints state, prompts for input, and calls `evaluate` again to get the next `data` tuple. This loop is how every turn — and the whole game — progresses.
+- Dice picks are entered as letters (`a`-`f` mapped to position 1-6 via `ord(x)-96`), not digit values; `evaluate` converts letters to positions internally before checking the picked dice values against `hodnoty`.
+- Bust detection (`check_value`) checks whether *any* key in `hodnoty` is a substring of the sorted current throw — not a full combinatorial scoring check, so this is the single source of truth for "is this throw dead."
+- Win condition (`check_win`) only fires once `pointer` cycles back to `first`, i.e. checked once per full round rather than once per turn, and only declares a winner if exactly one player is alone at/above `final_score`.
+
+`kostky/__main__.py` and the `kostky` console-script entry point (in `pyproject.toml`) both call `kostky.kostky.main()`.
+
+## Scoring data
+
+`kostky/hodnoty.csv` (digit-string-of-dice-values → points) is the single source of truth for scoring and is also documented in tables in `README.md`. If you change one, update the other.

README.md

@@ -1,2 +1,100 @@
 # kostky
 
+Textová (CLI) hra v kostky pro více hráčů – varianta klasického *Farkle*
+(„tisícovky“). Běží celá v terminálu, v Pythonu, s jedinou závislostí
+(`tabulate` pro závěrečnou výsledkovou tabulku).
+
+## Požadavky
+
+- Python 3.9+
+- Závislost `tabulate` (doinstaluje se automaticky při instalaci)
+
+## Instalace a spuštění
+
+```bash
+git clone https://gitea.spacilovi.eu/david/kostky.git
+cd kostky
+pip install .
+kostky
+```
+
+Případně bez instalace (s nainstalovaným `tabulate`) přes `python -m kostky`,
+nebo izolovaně jako CLI nástroj přes `pipx install .`.
+
+> Pro vývoj: `pip install -e ".[dev]"` – editovatelná instalace včetně `mypy`
+> a `ruff`.
+
+## Jak se hraje
+
+### Začátek hry
+
+1. Zadej jméno prvního hráče (povinné, nesmí být prázdné).
+2. Přidávej další hráče; zadáním `x` zadávání ukončíš. Jména musí být unikátní.
+3. Zadej cílové skóre, nebo nech pole prázdné pro výchozích **10 000**.
+
+### Průběh tahu
+
+Na začátku tahu uvidíš, kdo je na tahu (s jeho skóre a cílem), a hod šesti
+kostkami s písmennými pozicemi:
+
+```
+Na tahu je Anna (0/10000).
+1, 5, 3, 2, 6, 4
+^  ^  ^  ^  ^  ^
+a  b  c  d  e  f
+```
+
+Pak zvolíš jednu z akcí:
+
+| Vstup | Akce |
+| --- | --- |
+| `pozice kostek` | Odložíš vybrané kostky k vyhodnocení – písmeny (např. `a`, `cd`, `abcdef`). Hodnoty na zvolených pozicích musí dohromady tvořit některou kombinaci z bodovací tabulky. |
+| `h` | Hodíš znovu zbývajícími kostkami. Povoleno až poté, co v tomto tahu odložíš aspoň jednu bodující kombinaci. |
+| `k` | Ukončíš tah, připíšeš si nasbírané skóre a předáš tah dalšímu hráči. |
+| `exit` | Předčasně ukončíš celou hru. |
+
+Odkládat můžeš i víc kombinací po sobě – po každém vyhodnocení pokračuješ se
+zbývajícími kostkami a body se v rámci tahu sčítají.
+
+### Smůla, hot dice, vynulování a výhra
+
+- **Smůla (bust):** když čerstvý hod neobsahuje žádnou bodující kombinaci,
+  o body z tohoto tahu přijdeš a tah přechází na dalšího hráče.
+- **Hot dice:** když se ti podaří odložit všech šest kostek, dostaneš čerstvý
+  hod šesti kostkami a pokračuješ ve stejném tahu.
+- **Vynulování:** tři po sobě jdoucí nulové tahy vynulují tvé celkové skóre.
+  Počet aktuálních nul se vedle skóre ukazuje jako `x` / `xx`.
+- **Výhra:** po dokončení každého kola vyhrává osamocený lídr nad cílovým
+  skóre; při shodě na první příčce se hraje dál. Na konci se vypíše výsledková
+  tabulka s pořadím všech hráčů.
+
+## Bodování
+
+Kompletní tabulka je v souboru [`kostky/hodnoty.csv`](kostky/hodnoty.csv).
+Kombinace se vyhodnocuje podle hodnot odložených kostek – na jejich pořadí
+nezáleží.
+
+### Stejné kostky
+
+| Kostka | ×1 | ×2 | ×3 | ×4 | ×5 | ×6 |
+| --- | --- | --- | --- | --- | --- | --- |
+| **1** | 100 | 200 | 1000 | 2000 | 4000 | 8000 |
+| **2** | – | – | 200 | 400 | 800 | 1600 |
+| **3** | – | – | 300 | 600 | 1200 | 2400 |
+| **4** | – | – | 400 | 800 | 1600 | 3200 |
+| **5** | 50 | 100 | 500 | 1000 | 2000 | 4000 |
+| **6** | – | – | 600 | 1200 | 2400 | 4800 |
+
+(„–“ = daná kombinace samostatně neboduje.)
+
+### Postupky
+
+| Kombinace | Body |
+| --- | --- |
+| 1-2-3-4-5 | 750 |
+| 2-3-4-5-6 | 1000 |
+| 1-2-3-4-5-6 | 1500 |
+
+## Licence
+
+Projekt je licencovaný pod [GPL-3.0](LICENSE).

kostky/__main__.py

@@ -0,0 +1,4 @@
+from kostky.kostky import main
+
+if __name__ == "__main__":
+    main()

kostky/hodnoty.csv

@@ -0,0 +1,29 @@
+111111,8000
+666666,4800
+11111,4000
+555555,4000
+444444,3200
+66666,2400
+333333,2400
+1111,2000
+55555,2000
+44444,1600
+222222,1600
+123456,1500
+6666,1200
+33333,1200
+111,1000
+5555,1000
+23456,1000
+4444,800
+22222,800
+12345,750
+666,600
+3333,600
+555,500
+444,400
+2222,400
+333,300
+222,200
+1,100
+5,50

kostky/kostky.py

@@ -0,0 +1,336 @@
+import csv
+import re
+from collections import Counter
+from importlib.resources import files
+from os import name, system
+from random import randint
+from typing import Any
+
+from tabulate import tabulate
+
+score: int = 0
+hodnoty: dict[str, int] = {}
+players: dict[str, list[int]] = {}
+pointer: str = ""
+first: str = ""
+h_bool: bool = True
+aggr: dict[str, int] = {}
+final_score: int = 10000
+
+csv_text = files(__package__).joinpath("hodnoty.csv").read_text(encoding="utf-8")
+csv_reader = csv.reader(csv_text.splitlines())
+
+for row in csv_reader:
+    key = str(row[0])
+    value = int(row[1])
+
+    hodnoty[key] = value
+
+def throw(count: int) -> str:
+    count = int(count)
+    new_throw: list[str] = []
+    for _dice in range(count):
+        new_throw.append(str(randint(1, 6)))
+    new_throw_str: str = "".join(new_throw)
+    return new_throw_str
+
+def show_throw(throw: str) -> str:
+    throw_temp: list[str] = []
+    for x in throw:
+        throw_temp.append(x)
+
+    pretty_list: str = ", ".join(throw_temp)
+    pretty_list += "\n"
+    for _i in range(1, len(throw_temp) + 1):
+        pretty_list += "^  "
+    pretty_list += "\n"
+    for i in range(len(throw_temp)):
+        pretty_list += f"{chr(97+i)}  "
+    return pretty_list
+
+def clear() -> None:
+    _ = system('cls') if name == 'nt' else system('clear') 
+
+def evaluate(inp: Any, count: int, throw: str) -> tuple[Any, ...]:
+
+    global h_bool
+
+    def eval_score(pick: str) -> bool:
+        if(pick in hodnoty):
+            global score
+            score += hodnoty[pick]
+            return True
+        else:
+            return False
+
+    def next_player() -> None:
+        global pointer
+
+        keys_iter = iter(players)
+        for key in keys_iter:
+            if key == pointer: 
+                nxt_key = next(keys_iter, first) 
+                break
+        
+        pointer = nxt_key
+
+    inp = str(inp)
+    inp_temp: str = ""
+
+    if re.search(r"^[a-f]+$", inp):
+        if len(inp) > count:
+            data: tuple[Any, ...] = (
+                "msg",
+                "ER01",
+                "Tolika kostkami nemůžete hodit. Zkuste to znovu: ",
+                count,
+                throw
+            )
+        else:
+            for x in inp:
+                x = ord(x)-96
+                if x > count:
+                    ran = "1" if count == 1 else f"1–{count}"
+                    data = (
+                        "msg",
+                        "ER02",
+                        f"Zvolte prosím kostky v platném rozsahu ({ran}): ",
+                        count,
+                        throw
+                    )
+                    return data
+                else:
+                    inp_temp += str(x)
+            inp = inp_temp
+            
+            old_throw: list[str] = []
+            pick: list[str] = []
+            for y in range(count):
+                if str(y+1) not in inp:
+                    old_throw.append(throw[y])
+                if str(y+1) in inp:
+                    pick.append(throw[y])
+
+            old_throw_str: str = "".join(old_throw)
+            pick.sort()
+            pick_str: str = "".join(pick)
+            
+            new_count: int = len(old_throw_str)
+
+            if not eval_score(pick_str):
+                new_count = count
+                old_throw_str = throw
+            else:
+                h_bool = False
+
+            data = ("count", new_count, old_throw_str)
+
+    elif inp == "h":
+        if h_bool:
+            clear()
+            input("Nemůžete házet znovu, dokud nevyhodnotíte některé kostky.")
+            data = ("count", count, throw)
+        else:
+            h_bool = True
+            data = ("count", count, "")
+
+    elif inp == "k":
+        global score
+
+        if score == 0:
+            last_two = players[pointer][-2:]
+            if len(last_two) > 1:
+                last_two_sum = sum(last_two)
+                if last_two_sum == 0:
+                    score = -sum(players[pointer])
+                    clear()
+                    input("Po třech nulových hodech bylo vaše skóre vynulováno.")
+
+        players[pointer].append(score)
+        aggr[pointer] = sum(players[pointer])
+        score = 0
+        h_bool = True
+        next_player()
+        data = ("count", 6, "")
+        if pointer == first:
+            winner: str = check_win()
+            if winner:
+                data = ("win", winner, aggr[winner])
+
+    elif inp == "exit":
+        data = ("exit",)
+
+    else:
+        data = ("msg", "ER03", "Zadejte prosím platnou hodnotu:", count, throw)
+
+    return data
+
+def check_value(throw: str) -> bool:
+    throw_s: list[str] = sorted(throw)
+    throw_str: str = "".join(throw_s)
+    hodnota: bool = False
+    for h in hodnoty:
+        if h in throw_str:
+            hodnota = True
+            break
+
+    return hodnota
+
+def add_players() -> None:    
+    global pointer, first, final_score
+
+    while True:
+        inp: str = input("Zadejte jméno prvního hráče: ")
+        if inp == "":
+            print("Jméno nemůže být prázdné.")
+        else:
+            players[inp] = []
+            aggr[inp] = 0
+            pointer = inp
+            first = inp
+            print(f"Do seznamu přidáno jméno {inp}.")
+            break
+
+    while True:
+        inp = input("Zadejte jméno dalšího hráče nebo [x] pro ukončení zadávání hráčů: ")
+        if inp == "":
+            print("Jméno nemůže být prázdné.")
+        elif inp == "x":
+            break
+        elif inp in players:
+            print("Zadávejte, prosím, unikátní jména.")
+        else:
+            players[inp] = []
+            aggr[inp] = 0
+            print(f"Do seznamu přidáno jméno {inp}.")
+
+    while True:
+        inp = input("Zadejte finální skóre (nechte prázdné pro výchozích 10 000): ")
+        if inp != "":
+            try:
+                inp_int: int = int(inp)
+                final_score = inp_int
+            except ValueError:
+                print("Zadejte prosím platnou číselnou hodnotu.")
+            else:
+                break
+        else:
+            break
+
+def to_sorted_tuple(d: dict[str, int], s: bool = True) -> tuple[list[tuple[int, str, int]],
+                                                                dict[str, int]]:
+    L: list[tuple[int, str, int]] = []
+
+    if s:
+        d = dict(sorted(d.items(), key=lambda x: x[1], reverse=True)) 
+    
+    for i, (k, v) in enumerate(d.items()):
+        L.append((i+1, k, v))
+
+    return L, d
+
+def check_win() -> str:
+    over_limit: dict[str, int] = {}
+    for p in aggr:
+        if aggr[p] >= final_score:
+            over_limit[p] = aggr[p]
+
+    winner: str = ""
+
+    if over_limit:
+        L, d = to_sorted_tuple(over_limit)
+
+        count: Counter = Counter(list(d.values()))
+
+        for c in count:
+            if count[c] == 1:
+                winner = L[0][1]
+            break
+
+    return winner
+
+def win(winner: str, score: int) -> None:
+    results, d = to_sorted_tuple(aggr)
+
+    headers = ["Pořadí", "Hráč", "Skóre"]
+    table = tabulate(results, headers=headers, tablefmt="fancy_grid")
+
+    print(f"Vítězem se stává {winner} s {score} body!")
+    print("Díky za hru a zase příště.\n")
+
+    print(table)
+
+def game(data: tuple) -> None:
+    while True:
+        if data[0] == "count":
+            count: int = data[1]
+            th: str = data[2]
+            if(th == ""):
+                th = throw(count)
+            clear()
+            # print(f"Vítězné skóre: {final_score}.")
+
+            strikes: str = ""
+
+            if len(players[pointer]) > 0: 
+                if players[pointer][-1:][0] == 0:
+                    strikes = "x"
+                    if players[pointer][-2:][0] == 0:
+                        strikes += "x"
+            else:
+                strikes = ""
+
+            print(f"Na tahu je {pointer} ({aggr[pointer]}{strikes}/{final_score}).")
+            print(show_throw(th))
+            if not check_value(th) and data[2] == "" and count != 0:
+                global score
+                score = 0
+                input("Oh no... anyway.")
+                data = evaluate("k", count, th)
+            else:
+                if count == 0:
+                    count = 6
+                msg: str = ("Jakou akci chcete provést?\n"
+                    " - Zadejte kombinaci kostek k ponechání (dojde k jejich vyhodnocení): "
+                    "[pozice kostek] (např. a nebo cd nebo abcdef).\n"
+                    " - Hodit znovu: [h].\n"
+                    f" - Ukončit hod a ponechat si skóre z tohoto hodu ({score}): [k].\n"
+                    " - Ukončit hru: [exit].\n"
+                )
+                inp: str = input(msg)
+                data = evaluate(inp, count, th)
+
+        elif data[0] == "msg":
+            if data[1] == "ER01" or data[1] == "ER02" or data[1] == "ER03":
+                msg = data[2]
+                count = data[3]
+                th = data[4]
+                inp = input(msg)
+                data = evaluate(inp, count, th)
+            else:
+                msg = data[1]
+                print(msg)
+                break
+        
+        elif data[0] == "win":
+            winner: str = data[1]
+            score = data[2]
+
+            clear()
+            win(winner, score)
+            break
+
+        elif data[0] == "exit":
+            clear()
+            print("Hra byla předčasně ukončena. Snad se zase brzy uvidíme.")
+            break
+
+def main() -> None:
+    clear()
+    print("Vítejte ve hře v kostky!")
+    add_players()
+    data = ("count", 6, "")
+    game(data)
+
+if __name__ == "__main__":
+    main()

main.py

@@ -1,40 +0,0 @@
-from random import randint
-from os import system, name
-
-def throw(count):
-    count = int(count)
-    new_throw = []
-    for dice in range(count):
-        new_throw.append(str(randint(1, 6)))
-    return new_throw
-
-def show_throw(throw):
-    pretty_list = ", ".join(throw)
-    pretty_list += "\n"
-    for i in range(1, len(throw) + 1):
-        pretty_list += "^  "
-    pretty_list += "\n"
-    for i in range(1, len(throw) + 1):
-        pretty_list += f"{i}  "
-    return pretty_list
-
-def clear():
-    if name == 'nt':
-        _ = system('cls')
-    else:
-        _ = system('clear')
-
-def game():
-    new_throw = throw(6)
-    clear()
-    print(show_throw(new_throw))
-    input("Prosím, stiskněte enter pro další hod:")
-    game()
-
-def main():
-    print("Vítejte ve hře v kostky!")
-    input("Prosím, stiskněte enter pro první hod:")
-    game()
-
-if __name__ == "__main__":
-    main()

pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kostky"
+dynamic = ["version"]
+description = "Textová hra v kostky."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "GPL-3.0-or-later"
+license-files = ["LICENSE"]
+authors = [{ name = "David Spáčil" }]
+keywords = ["hra", "kostky", "cli"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Environment :: Console",
+    "Operating System :: OS Independent",
+    "Topic :: Games/Entertainment",
+]
+dependencies = [
+    "tabulate",
+]
+
+[project.optional-dependencies]
+dev = ["mypy", "ruff", "types-tabulate"]
+
+[project.urls]
+Repository = "https://gitea.spacilovi.eu/david/kostky"
+
+[project.scripts]
+kostky = "kostky.kostky:main"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["kostky"]
+
+[tool.mypy]
+python_version = "3.9"
+strict = true
+files = ["kostky"]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]