# 🎮 Termdoku

**A beautiful, feature-rich terminal-based Sudoku game.**

![License](https://img.shields.io/badge/license-MIT-blue.svg)
![Go Version](https://img.shields.io/badge/go-%3E%3D1.21-00ADD8.svg)

## ✨ Features

### 🎯 Core Gameplay

- **Multiple Difficulty Levels**: Easy, Normal, Hard, Expert, and Lunatic
- **Daily Puzzles**: New puzzle every day with consistent seeds
- **Smart Hint System**: Intelligent hints using solving techniques (Naked Singles, Hidden Singles)
- **Auto-Check Mode**: Optional real-time validation of moves
- **Timer**: Track your solving time
- **Undo/Redo**: Full move history support

### 🧩 Advanced Puzzle Generation

- **Unique Solution Guarantee**: All puzzles have exactly one solution
- **Symmetry Patterns**: Support for rotational, vertical, and horizontal symmetry
- **Puzzle Analysis**: Comprehensive difficulty rating and analysis
- **Custom Generation**: Create puzzles with custom parameters
- **Pattern Detection**: Identifies required solving techniques
- **Optimized Solver**: Uses most-constrained-first heuristic for fast solving

### 📊 Statistics & Progress

- **Comprehensive Stats**: Track games played, win rate, streaks, and more
- **Best Times**: Personal records for each difficulty level
- **Leaderboard**: Top 5 fastest times per difficulty
- **Daily History**: Track your daily puzzle completions
- **Recent Games**: View your last 50 games

### 🏆 Achievement System

- **8 Unique Achievements**: Unlock achievements as you play
- **Progress Tracking**: See your progress toward each achievement
- **Visual Indicators**: Beautiful UI showing locked/unlocked status
- **Achievements Include**:
  - 🏆 First Victory - Complete your first puzzle
  - ⚡ Speed Demon - Complete an Easy puzzle in under 3 minutes
  - 💎 Perfectionist - Complete a puzzle without using hints
  - 🔥 Streak Master - Achieve a 5-day streak
  - 💯 Century Club - Complete 100 puzzles
  - 🌙 Lunatic Legend - Complete 10 Lunatic puzzles
  - 📅 Daily Devotee - Complete 30 daily puzzles
  - ✨ Flawless - Complete a Hard puzzle without auto-check

### 🎨 Customization

- **Theme Support**: Customizable color themes
- **Adaptive Colors**: Dynamic color schemes for different UI elements
- **Gradient Effects**: Beautiful gradient text and borders
- **Configurable Settings**: Auto-check, timer, and more

### 💾 Data Persistence

- **SQLite Database**: Robust data storage for games and achievements
- **JSON Stats**: Human-readable statistics files
- **Save Games**: Resume puzzles later
- **Cross-Session**: All data persists between sessions

## 📦 Installation

### Prerequisites

- Go 1.21 or higher

### Build from Source

```bash
# Clone the repository
git clone https://gitlab.com/bereckobrian/termdoku.git
cd termdoku

make build

# Run
./termdoku
```

### Using Go Install

```bash
go install github.com/bereckobrian/termdoku/cmd/termdoku@latest
```

## 🎮 How to Play

### Controls

#### Menu Navigation

- `↑/↓` or `k/j` - Navigate menu items
- `←/→` or `h/l` - Navigate menu items (horizontal)
- `Enter` - Select menu item
- `a` - Toggle auto-check mode
- `t` - Toggle timer
- `q` - Quit

#### In-Game

- `Arrow Keys` or `h/j/k/l` - Move cursor
- `1-9` - Enter number
- `0` or `Backspace` - Clear cell
- `n` - Toggle notes mode
- `u` - Undo move
- `r` - Redo move
- `?` or `h` - Get hint
- `c` - Check solution
- `s` - Solve puzzle
- `m` or `Esc` - Return to menu
- `q` - Quit game

### Game Modes

1. **Easy** - 38 empty cells, perfect for beginners
2. **Normal** - 46 empty cells, balanced difficulty
3. **Hard** - 52 empty cells, challenging puzzles
4. **Expert** - 56 empty cells, very difficult
5. **Lunatic** - 60 empty cells, extreme challenge
6. **Daily** - One puzzle per day, same for everyone

## 🏗️ Project Structure

```
termdoku/
├── cmd/
│   └── termdoku/          # Main application entry point
├── internal/
│   ├── achievements/      # Achievement system
│   ├── config/           # Configuration management
│   ├── database/         # SQLite database layer
│   ├── game/             # Game board logic
│   ├── generator/        # Puzzle generation engine
│   │   ├── api.go       # Grid analysis & validation
│   │   ├── core.go      # Generation algorithms
│   │   ├── generator.go # Main generation interface
│   │   ├── benchmark.go # Performance benchmarking
│   │   └── utils.go     # Utility functions
│   ├── savegame/         # Save/load game state
│   ├── solver/           # Sudoku solver
│   ├── stats/            # Statistics tracking
│   ├── theme/            # Theme system
│   └── ui/               # Terminal UI (Bubble Tea)
├── go.mod
├── go.sum
├── LICENSE
├── Makefile
└── README.md
```

## 🔧 Advanced Features

### Puzzle Generation API

The generator package provides advanced puzzle generation capabilities:

```go
import "termdoku/internal/generator"

// Generate a puzzle with specific difficulty
puzzle, err := generator.Generate(generator.Hard, "seed")

// Generate with symmetry
puzzle, err := generator.GenerateWithSymmetry(
    generator.Normal, 
    "seed", 
    generator.SymmetryRotational180,
)

// Generate with analysis
result, err := generator.GenerateWithAnalysis(generator.Expert, "seed")
fmt.Printf("Difficulty Rating: %d/100\n", generator.RatePuzzle(result.Puzzle))

// Analyze a puzzle
analysis := puzzle.Analyze()
fmt.Printf("Symmetry: %s\n", analysis.SymmetryType)
fmt.Printf("Techniques: %v\n", analysis.SolvingTechniques)
```

### Puzzle Analysis

Every puzzle can be analyzed for:

- **Filled/Empty cells count**
- **Candidate distribution** (min, max, average)
- **Solution uniqueness**
- **Estimated difficulty**
- **Required solving techniques**
- **Symmetry pattern**
- **Complexity score**

### Benchmarking

```go
import "termdoku/internal/generator"

// Benchmark generation performance
result := generator.BenchmarkGeneration(generator.Hard, 10)
fmt.Println(result.String())

// Compare generation methods
standard, symmetric := generator.CompareGenerationMethods(generator.Normal, 10)
```

## 📊 Data Storage

Termdoku stores data in `~/.termdoku/`:

- `termdoku.db` - SQLite database (games, achievements, stats)
- `stats.json` - Statistics backup (JSON format)
- `achievements.json` - Achievements backup (JSON format)
- `config.json` - User configuration
- `themes/` - Custom theme files

## 🎨 Themes

Create custom themes in `~/.termdoku/themes/`:

```json
{
  "name": "My Theme",
  "palette": {
    "background": "#1a1b26",
    "foreground": "#c0caf5",
    "accent": "#7aa2f7",
    "error": "#f7768e",
    "success": "#9ece6a",
    "warning": "#e0af68"
  }
}
```

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📝 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Built with [Bubble Tea](https://github.com/charmbracelet/bubbletea) - A powerful TUI framework
- [Lipgloss](https://github.com/charmbracelet/lipgloss) - Style definitions for nice terminal layouts