# 🔮 Tarot Card Reader

A beautiful command-line tarot card reading application written in Rust. Draw random tarot cards and receive mystical insights with colorful, formatted output.

## ✨ Features

- 🃏 **Multi-Card Draws**: Draw multiple unique cards for a more detailed reading.
- 🎴 **Complete Tarot Deck**: Full 78-card tarot deck (22 Major Arcana + 56 Minor Arcana)
- 🎲 **Random Card Drawing**: Statistically accurate card distribution
- 🔄 **Card Positions**: Support for upright and reversed card positions
- 🎨 **Beautiful Output**: Colorful, well-formatted terminal display
- 📊 **JSON Export**: Machine-readable output for integrations
- 🧪 **Comprehensive Testing**: Full test suite with 12 test cases
- 📖 **Rich Meanings**: Detailed interpretations for all Major Arcana cards

## 🚀 Installation

### Prerequisites
- [Rust](https://rustup.rs/) (2021 edition or later)
- Cargo (comes with Rust)

### Build from Source
```bash
git clone https://gitlab.com/dump-stuff/tarot.git 
cd tarot
cargo build --release
```

### Run Directly
```bash
cargo run
```

## 🎯 Usage

### Basic Usage
```bash
# Draw a random tarot card with beautiful formatting
tarot

# Example output:
# ════════════════════════════════════════════════════════════
#            ♦ TAROT CARD READING ♦            
# ════════════════════════════════════════════════════════════
# Card: The Fool
# Type: Major Arcana
# Position: Upright
# Meaning: Folly, mania, extravagance, intoxication, delirium, frenzy, bewrayment
# ════════════════════════════════════════════════════════════
```

### Command Line Options

| Flag | Short | Description |
|------|-------|-------------|
| `--help` | `-h` | Show help message and usage information |
| `--version` | `-v` | Display version information |
| `--json` | `-j` | Output reading in JSON format |
| `--number` | `-n` | Set the number of cards to draw (default: 1) |

### Examples

```bash
# Show help
tarot --help

# Show version
tarot --version

# Get JSON output for programmatic use
tarot --json

# Draw 3 cards
tarot --number 3

# Short flags work too
tarot -h
tarot -v
tarot -j
tarot -n 5
```

## 🎴 Card Types

### Major Arcana (22 cards)
Complete set of Major Arcana cards with detailed meanings:
- The Fool, The Magician, The High Priestess, The Empress
- The Emperor, The Hierophant, The Lovers, The Chariot
- Strength, The Hermit, Wheel of Fortune, Justice
- The Hanged Man, Death, Temperance, The Devil
- The Tower, The Star, The Moon, The Sun
- Judgement, The World

### Minor Arcana (56 cards)
Four suits with 14 cards each:
- **Wands** (Fire): Creativity, passion, energy
- **Cups** (Water): Emotions, relationships, spirituality  
- **Swords** (Air): Thoughts, communication, conflict
- **Pentacles** (Earth): Material, career, resources

Each suit contains: Ace, 2-10, Page, Knight, Queen, King

## 🎨 Visual Features

- **Color-coded output**: Different colors for card types and positions
- **Styled text**: Bold headers, italic meanings, bright highlights
- **Centered layout**: Professional-looking card reading display
- **Unicode symbols**: Decorative elements (♦, ═) for visual appeal

## 🔧 Development

### Running Tests
```bash
# Run all tests
cargo test

# Run tests with output
cargo test -- --nocapture

# Run specific test
cargo test test_get_tarot_meaning_valid_card
```

### CI/CD Pipeline
This project includes a comprehensive GitLab CI/CD pipeline (`.gitlab-ci.yml`) that:

- ✅ **Automated Testing**: Runs tests, clippy, and formatting checks on all MRs
- 🏗️ **Release Builds**: Creates optimized binaries on main branch merges
- 📦 **Automatic Releases**: Generates GitLab releases with artifacts

### Project Structure
```
tarot/
├── src/
│   └── main.rs          # Main application code
├── cards.json           # Tarot card meanings data
├── .gitlab-ci.yml       # GitLab CI/CD pipeline configuration
├── Cargo.toml           # Dependencies and metadata
├── Cargo.lock           # Dependency lock file
├── README.md            # This file
└── target/              # Build artifacts
```

### Dependencies
- `rand = "0.8"` - Random number generation for card drawing
- `colored = "2.0"` - Terminal color and styling
- `serde = "1.0"` - Serialization framework
- `serde_json = "1.0"` - JSON serialization support
- `once_cell = "1.19.0"` - Lazy initialization of static data

## 🧪 Testing

The project includes comprehensive tests covering:

- ✅ Card meaning retrieval and validation
- ✅ Random card drawing functionality  
- ✅ Case-insensitive card lookup
- ✅ Error handling for invalid cards
- ✅ JSON serialization
- ✅ Text formatting and centering
- ✅ All Major Arcana cards validation

Run `cargo test` to execute the full test suite.

## 📊 API Reference

### Core Functions

#### `get_tarot_meaning(card_name: &str) -> Result<CardMeaning, String>`
Retrieves the meaning for a specific tarot card.

#### `draw_random_tarot_cards(count: usize) -> Vec<(String, &'static str)>`
Draws a specified number of unique random cards from the full 78-card deck.

### Data Structures

#### `CardMeaning`
```rust
pub struct CardMeaning {
    pub upright: String,
    pub reversed: String,
}
```

#### `TarotReading` (JSON output)
```rust
struct TarotReading {
    card: String,
    arcana_type: String,
    position: String,
    meaning: String,
}
```

## 🎪 Examples in Practice

### Integration with Scripts
```bash
# Get a daily reading in JSON format
READING=$(tarot --json)
echo "Today's card: $(echo $READING | jq -r '.card')"
```

### Sample JSON Output (for `tarot -n 2 --json`)
```json
[
  {
    "card": "The Fool",
    "arcana_type": "Major Arcana",
    "position": "Upright",
    "meaning": "Folly, mania, extravagance, intoxication, delirium, frenzy, bewrayment"
  },
  {
    "card": "Three of Cups",
    "arcana_type": "Minor Arcana",
    "position": "Reversed",
    "meaning": "Independence, alone time, hardcore partying"
  }
]
```

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass (`cargo test`)
6. Commit your changes (`git commit -m 'Add amazing feature'`)
7. Push to the branch (`git push origin feature/amazing-feature`)
8. Open a Pull Request

## 📝 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) - see the [LICENSE](LICENSE) file for details.

**What this means:**
- ✅ You can freely use, modify, and distribute this software
- ✅ You must share any modifications under the same license
- ✅ If you use this in a network service, you must provide the source code to users
- 🚫 Commercial entities typically avoid AGPL due to its copyleft requirements

This license ensures the software remains free and open source while preventing proprietary commercialization.

## 🔮 Future Enhancements

- [ ] Custom card spreads (Celtic Cross, Three Card, etc.)
- [ ] Historical reading log
- [ ] Card image display in terminal
- [ ] Interactive card selection mode
- [ ] Configuration file for custom meanings
- [ ] Web API server mode
- [ ] Multiple language support

## 🙏 Acknowledgments

- Tarot card meanings compiled from traditional interpretations
- Built with the amazing Rust ecosystem
- Colored terminal output powered by the `colored` crate

---

*"The cards don't lie, but they do speak in riddles."* 🔮
