(Feat): Initial Commit, Termdoku

2025-11-25 21:09:27 +00:00
commit f6933958e2
40 changed files with 5755 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,254 @@
+# 🎮 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