breakbuddy 0.1.1
A CLI tool that reminds developers to take breaks after a set time interval
License: MIT
Requires Python: >=3.10
Keywords: cli, break, reminder, productivity, developer-tools

# 🧘‍♂️ BreakBuddy

> A CLI tool that reminds developers to take breaks after a set time interval

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI version](https://badge.fury.io/py/breakbuddy.svg)](https://badge.fury.io/py/breakbuddy)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

BreakBuddy helps you maintain a healthy work-life balance by reminding you to take regular breaks. Perfect for developers who spend long hours coding and need gentle nudges to step away from the screen.

## ✨ Features

- **⏰ Smart Time Parsing**: Support for various time formats (`10s`, `45m`, `1h`, `1h30m`, or just `15` for minutes)
- **🔄 Flexible Reminders**: One-time reminders or recurring loops
- **💬 Motivational Quotes**: Built-in quotes in different categories (zen, humor, focus)
- **🎨 Beautiful Output**: Rich, styled output with emojis and panels
- **🛡️ Safe Exit**: Clean Ctrl+C handling with graceful shutdown
- **⚙️ Customizable**: Custom messages, quote categories, and formatting options

## 🚀 Quick Start

### Installation

```bash
pip install breakbuddy
```

### Basic Usage

```bash
# Show a reminder after 45 minutes
breakbuddy once 45m

# Show recurring reminders every 45 minutes
breakbuddy loop --every 45m

# Show a random zen quote immediately
breakbuddy quote --category zen

# See available quote categories
breakbuddy categories
```

## 📖 Usage Examples

### One-time Reminders

```bash
# Remind me in 30 seconds
breakbuddy once 30s

# Remind me in 1 hour and 30 minutes
breakbuddy once 1h30m

# Remind me in 15 minutes with a custom message
breakbuddy once 15 --message "Time to stretch those legs!"

# Remind me in 45 minutes with a zen quote
breakbuddy once 45m --category zen
```

### Recurring Reminders

```bash
# Remind me every 45 minutes (infinite loop)
breakbuddy loop --every 45m

# Remind me every 30 minutes, 5 times
breakbuddy loop --every 30m --count 5

# Remind me every hour for 4 hours total
breakbuddy loop --every 1h --for 4h

# Recurring reminders with custom message
breakbuddy loop --every 90m --message "Coffee break time!"
```

### Quote Management

```bash
# Show a random quote from default category
breakbuddy quote

# Show a random zen quote
breakbuddy quote --category zen

# Show a random humor quote
breakbuddy quote --category humor

# Show a random focus quote
breakbuddy quote --category focus

# List all available categories
breakbuddy categories
```

### Formatting Options

```bash
# Use plain text output (no fancy boxes)
breakbuddy once 30m --no-fancy

# Use fancy formatting (default)
breakbuddy once 30m --fancy
```

## 🎯 Time Format Support

BreakBuddy supports flexible time formats:

| Format | Example | Description |
|--------|---------|-------------|
| `N` | `15` | N minutes |
| `Ns` | `30s` | N seconds |
| `Nm` | `45m` | N minutes |
| `Nh` | `2h` | N hours |
| `NhNm` | `1h30m` | N hours and M minutes |
| `NhNmNs` | `1h30m15s` | N hours, M minutes, and S seconds |

## 🔒 Security Features

BreakBuddy includes several security measures to protect against common vulnerabilities:

### **Input Validation & Sanitization**
- **Duration Limits**: Maximum duration of 1 year (31,536,000 seconds) to prevent DoS attacks
- **String Length Limits**: 
  - Duration strings: max 50 characters
  - Messages: max 500 characters
  - Categories: max 50 characters
  - Quotes: max 500 characters
- **Reminder Count Limits**: Maximum 1,000 reminders to prevent resource exhaustion
- **Category Validation**: Only predefined categories (zen, humor, focus, default) are accepted
- **Path Traversal Protection**: Dangerous characters (/, \, :, *, ?, ", <, >, |, ..) are blocked

### **Resource Protection**
- **Integer Overflow Prevention**: All numeric inputs are validated and limited
- **Memory Protection**: Large input strings are rejected before processing
- **Signal Handler Security**: Proper error handling in signal handlers
- **Loop Safety**: Maximum 10,000 iterations to prevent infinite loops
- **Minimum Intervals**: Minimum 1-second intervals to prevent DoS attacks

### **Error Handling**
- **Graceful Degradation**: Invalid inputs are rejected with clear error messages
- **Exception Safety**: All commands handle unexpected errors gracefully
- **Input Sanitization**: All user inputs are stripped and validated
- **Safety Limits**: Hard limits prevent resource exhaustion and runaway processes

### **Security Best Practices**
- **Principle of Least Privilege**: Only necessary functionality is exposed
- **Input Validation**: All user inputs are validated before processing
- **Resource Limits**: Hard limits prevent resource exhaustion attacks
- **Error Messages**: Security-conscious error messages that don't leak information
- **Category Whitelisting**: Only predefined, safe categories are allowed

For security concerns, please report them privately to the maintainers.

## 🏗️ Development

### Prerequisites

- Python 3.10+
- pip

### Local Development Setup

1. **Clone the repository**
   ```bash
   git clone https://github.com/breakbuddy/breakbuddy.git
   cd breakbuddy
   ```

2. **Create a virtual environment**
   ```bash
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```

3. **Install development dependencies**
   ```bash
   pip install -e ".[dev]"
   ```

4. **Run tests**
   ```bash
   pytest
   ```

5. **Format code**
   ```bash
   black src/ tests/
   isort src/ tests/
   ```

6. **Type checking**
   ```bash
   mypy src/
   ```

### Project Structure

```
breakbuddy/
├── src/breakbuddy/
│   ├── __init__.py      # Package initialization
│   ├── cli.py          # CLI interface using Typer
│   ├── core.py         # Core BreakBuddy functionality
│   └── quotes.py       # Quote management
├── tests/
│   ├── __init__.py
│   └── test_core.py    # Test suite
├── pyproject.toml      # Project configuration
├── README.md           # This file
└── LICENSE             # MIT license
```

## 🧪 Testing

Run the test suite:

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=breakbuddy --cov-report=html

# Run specific test file
pytest tests/test_core.py

# Run with verbose output
pytest -v
```

## 📦 Building and Distribution

### Build the package

```bash
python -m build
```

### Install from source

```bash
pip install .
```

## 🤝 Contributing

We welcome contributions! Here's how you can help:

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** (`pytest`)
6. **Format your code** (`black src/ tests/`)
7. **Commit your changes** (`git commit -m 'Add amazing feature'`)
8. **Push to the branch** (`git push origin feature/amazing-feature`)
9. **Open a Pull Request**

### Development Guidelines

- Follow [PEP 8](https://www.python.org/dev/peps/pep-0008/) style guidelines
- Use type hints for all function parameters and return values
- Write docstrings for all public functions and classes
- Ensure 100% test coverage for new code
- Use meaningful commit messages

## 📝 License

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

## 🙏 Acknowledgments

- [Typer](https://typer.tiangolo.com/) for the excellent CLI framework
- [Rich](https://rich.readthedocs.io/) for beautiful terminal output
- [pytest](https://docs.pytest.org/) for testing framework
- All contributors who help make BreakBuddy better

## 📊 Changelog

### [0.1.0] - 2024-01-01

#### Added
- Initial release of BreakBuddy
- Core break reminder functionality
- CLI interface with Typer
- Rich terminal output with styled panels
- Quote management system with multiple categories
- Flexible time parsing (seconds, minutes, hours)
- One-time and recurring reminder modes
- Custom message support
- Quote category selection
- Fancy/plain output options
- Graceful signal handling (Ctrl+C)
- Comprehensive test suite
- Full type hints and documentation

#### Features
- `once` command for single reminders
- `loop` command for recurring reminders
- `quote` command for immediate quotes
- `categories` command to list available categories
- `demo` command to showcase capabilities
- Support for time formats: `10s`, `45m`, `1h`, `1h30m`, `15`
- Quote categories: zen, humor, focus, default
- Options: `--every`, `--count`, `--for`, `--message`, `--category`, `--fancy/--no-fancy`

## 🆘 Support

If you encounter any issues or have questions:

1. Check the [existing issues](https://github.com/breakbuddy/breakbuddy/issues)
2. Create a new issue with a detailed description
3. Include your operating system and Python version
4. Provide steps to reproduce the problem

## 🌟 Star History

[![Star History Chart](https://api.star-history.com/svg?repos=breakbuddy/breakbuddy&type=Date)](https://star-history.com/#breakbuddy/breakbuddy&Date)

---

**Made with ❤️ for developers who need gentle reminders to take care of themselves.**

*Remember: A well-rested developer is a productive developer!* 🧘‍♂️✨