@codejoy/terminal-pet/README.md

A virtual pet that lives in your terminal and grows with your coding activity

# 🐾 Terminal Pet

A virtual pet that lives in your terminal and grows with your coding activity! Your pet gets stronger, happier, and more experienced with every git commit you make.

![Terminal Pet Demo](https://img.shields.io/badge/terminal-pet-brightgreen?style=for-the-badge&logo=terminal)
![Node.js](https://img.shields.io/badge/node.js-v14+-green?style=for-the-badge&logo=node.js)
![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)

## ✨ Features

- 🐱 **Multiple Pet Types**: Choose from cats, dogs, or dragons
- 📊 **Real-time Stats**: Health, happiness, hunger, and energy tracking
- 🎯 **Git Integration**: Your pet grows stronger with every commit
- 🏆 **Achievement System**: Unlock achievements for coding milestones
- 🎨 **Beautiful ASCII Art**: Colorful pet visualizations with mood indicators
- 💾 **Persistent State**: Your pet remembers everything between sessions
- 🔄 **Automatic Git Hooks**: Optional automatic feeding on commits
- 📈 **Coding Analytics**: Track your programming patterns and streaks

## 🚀 Installation

### Global Installation (Recommended)

```bash
npm install -g terminal-pet
```

### Local Installation

```bash
npm install terminal-pet
```

## 🎮 Quick Start

1. **Adopt your first pet:**
   ```bash
   pet adopt
   ```

2. **Check on your pet:**
   ```bash
   pet status
   ```

3. **Take care of your pet:**
   ```bash
   pet feed    # When hungry
   pet play    # When bored
   pet sleep   # When tired
   ```

4. **Start coding!** Your pet will automatically get stronger with every git commit! 🎉

## 📋 Commands

| Command | Description |
|---------|-------------|
| `pet` | Show your pet's current status |
| `pet adopt` | Adopt a new pet (replaces current pet) |
| `pet status` | View detailed pet status |
| `pet feed` | Feed your hungry pet |
| `pet play` | Play with your pet (requires energy) |
| `pet sleep` | Let your pet rest and recover |
| `pet stats` | View achievements and coding statistics |
| `pet help` | Show help information |
| `pet git-setup` | Set up automatic git hooks |
| `pet git-remove` | Remove git hooks |

## 🐾 Pet Types

### 🐱 Cat
- **Personality**: Independent but loving
- **Special**: Extra happiness from successful commits
- **ASCII Art**: Classic cat expressions

### 🐶 Dog  
- **Personality**: Loyal and energetic
- **Special**: Bonus energy recovery
- **ASCII Art**: Adorable dog animations

### 🐉 Dragon
- **Personality**: Powerful and mystical  
- **Special**: Higher experience gains
- **ASCII Art**: Majestic dragon poses

## 📊 Pet Stats Explained

### Core Stats
- **❤️ Health** (0-100): Overall wellbeing. Decreases if hungry or unhappy for too long
- **😊 Happiness** (0-100): Mood level. Increases with play and commits, decreases over time
- **🍖 Hunger** (0-100): How hungry your pet is. Increases over time, feed to decrease
- **⚡ Energy** (0-100): Activity level. Decreases with play, recovers with sleep

### Progression
- **Level**: Increases with experience points from commits
- **Experience**: Gained from git commits and good coding practices
- **Age**: How many days since adoption
- **Streak**: Consecutive days with commits

## 🏆 Achievement System

Unlock achievements by reaching coding milestones:

- 🎉 **First Commit**: Make your first commit with your pet
- 💯 **Century Club**: Reach 100 total commits
- 🔥 **Week Warrior**: Maintain a 7-day commit streak
- 🌟 **Month Master**: Maintain a 30-day commit streak
- 🔟 **Double Digits**: Reach level 10
- 🎖️ **Half Century**: Reach level 50
- 🍖 **Well Fed**: Keep hunger at 0
- 😍 **Pure Joy**: Achieve 100% happiness

## 🎯 Git Integration

Terminal Pet integrates with your git workflow to reward good coding practices:

### Commit Rewards
- **Base XP**: 10 points per commit
- **Streak Bonus**: Up to 20 extra points for consecutive days
- **Message Quality**: Bonus points for descriptive commit messages
- **Commit Type Bonuses**:
  - Bug fixes: +5 XP
  - New features: +8 XP  
  - Refactoring: +6 XP

### Automatic Git Hooks
Set up automatic feeding with git hooks:

```bash
pet git-setup
```

This creates a post-commit hook that automatically rewards your pet after each commit!

## 🎨 Pet Moods

Your pet's mood changes based on their stats:

- 😊 **Happy**: Good overall stats
- 🤩 **Ecstatic**: Excellent health and happiness
- 😢 **Sad**: Low happiness
- 🍽️ **Hungry**: High hunger level
- 😴 **Tired**: Low energy
- 🤒 **Sick**: Low health
- 💀 **Dead**: Health reached 0 (adopt a new pet!)

## 🔧 Advanced Usage

### Programmatic Usage

```javascript
const { Pet, PetDisplay, GitIntegration } = require('terminal-pet');

// Create a new pet
const pet = new Pet('MyPet', 'cat');

// Simulate a commit
pet.onCommit('feat: add awesome feature');

// Display the pet
console.log(PetDisplay.displayPet(pet));

// Save state
pet.save();
```

### Custom Git Integration

```javascript
const { GitIntegration } = require('terminal-pet');

const git = new GitIntegration();

// Get commit statistics
const stats = await git.analyzeCommitActivity();
console.log('Recent commits:', stats.totalCommits);

// Check if in git repository
const isRepo = await git.isGitRepository();
```

## 🛠️ Development

### Setup

```bash
git clone https://github.com/yourusername/terminal-pet.git
cd terminal-pet
npm install
```

### Testing

```bash
# Link for local testing
npm link

# Test commands
pet adopt
pet status
```

### Project Structure

```
terminal-pet/
├── bin/
│   └── cli.js          # CLI interface
├── lib/
│   ├── Pet.js          # Core pet logic
│   ├── PetDisplay.js   # ASCII art and display
│   └── GitIntegration.js # Git workflow integration
├── package.json
├── index.js           # Main module exports
└── README.md
```

## 🤝 Contributing

Contributions are welcome! Here are some ideas:

- 🎨 New pet types and ASCII art
- 🏆 Additional achievements
- 📊 More detailed analytics
- 🎮 Mini-games and interactions
- 🌍 Localization support

### Development Guidelines

1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Ensure all tests pass
5. Submit a pull request

## 📝 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Inspired by the classic Tamagotchi virtual pets
- Built with love for the developer community
- ASCII art inspired by various terminal art collections

## 🐛 Troubleshooting

### Common Issues

**Pet not responding to commits:**
- Ensure you're in a git repository
- Set up git hooks with `pet git-setup`
- Check that the pet is alive with `pet status`

**Pet died:**
- Adopt a new pet with `pet adopt`
- Remember to feed and play with your pet regularly!

**Commands not found:**
- Ensure global installation: `npm install -g terminal-pet`
- Check PATH includes npm global binaries

### Support

- 🐛 [Report bugs](https://github.com/yourusername/terminal-pet/issues)
- 💡 [Request features](https://github.com/yourusername/terminal-pet/issues)
- 💬 [Join discussions](https://github.com/yourusername/terminal-pet/discussions)

---

**Made with ❤️ for developers who love their code (and virtual pets)!**

*Remember: A well-fed pet is a happy pet! Keep coding and keep your terminal buddy healthy! 🐾*