🔮 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 (2021 edition or later)
• Cargo (comes with Rust)

Build from Source

git clone https://gitlab.com/dump-stuff/tarot.git 
cd tarot
cargo build --release

Run Directly

cargo run

🎯 Usage

Basic Usage

# 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

Examples

# 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

# 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

pub struct CardMeaning {
    pub upright: String,
    pub reversed: String,
}

TarotReading (JSON output)

struct TarotReading {
    card: String,
    arcana_type: String,
    position: String,
    meaning: String,
}

🎪 Examples in Practice

Integration with Scripts

# 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)

[
  {
    "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 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." 🔮