Add project configuration files

README.md

@@ -1,3 +1,216 @@
-# cron-parser-cli
+# Cron Parser CLI
 
-A CLI tool that parses, validates, generates, and explains cron expressions in human-readable language
+A powerful and user-friendly CLI tool that parses, validates, generates, and explains cron expressions in human-readable language. Perfect for developers, DevOps engineers, and system administrators who work with scheduled tasks.
+
+![CI Status](https://7000pct.gitea.bloupla.net/api/status/7000pctAUTO/cron-parser-cli/pipeline)
+![Python Version](https://img.shields.io/badge/python-3.9+-blue.svg)
+![License](https://img.shields.io/badge/License-MIT-yellow.svg)
+
+## Features
+
+- **Parse & Validate**: Validate cron expressions and get detailed field breakdowns
+- **Natural Language**: Convert phrases like "every Monday at 9am" to cron syntax
+- **Next Execution**: See upcoming run times with visual timeline
+- **Interactive Generator**: Wizard-style cron expression builder
+- **Human-Readable**: Explain any cron expression in plain English
+- **Cross-Platform**: Works on Linux, macOS, and Windows
+
+## Installation
+
+### From PyPI (Recommended)
+
+```bash
+pip install cron-parser-cli
+```
+
+### From Source
+
+```bash
+git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/cron-parser-cli.git
+cd cron-parser-cli
+pip install -e ".[dev]"
+```
+
+### Using pipx
+
+```bash
+pipx install cron-parser-cli
+```
+
+## Quick Start
+
+```bash
+# Show help
+cronparse --help
+
+# Parse a cron expression
+cronparse parse "0 9 * * *"
+
+# Convert natural language to cron
+cronparse from-text "every Monday at 9am"
+
+# See next execution times
+cronparse next "0 9 * * *"
+
+# Generate cron interactively
+cronparse generate
+
+# Explain cron in plain English
+cronparse explain "0 9 * * *"
+```
+
+## Commands
+
+### parse
+
+Validate and parse a cron expression, showing field breakdown.
+
+```bash
+cronparse parse "0 9 * * *"
+```
+
+Output:
+
+```
+Valid cron expression: 0 9 * * *
+  minute        : 0
+  hour          : 9
+  day           : *
+  month         : *
+  day_of_week   : *
+```
+
+### from-text
+
+Convert natural language phrases to cron expressions.
+
+```bash
+# Various examples
+cronparse from-text "every 5 minutes"
+cronparse from-text "daily at 9am"
+cronparse from-text "every Monday at 2:30pm"
+cronparse from-text "on the 1st of every month at midnight"
+```
+
+### next
+
+Show next execution times for a cron expression.
+
+```bash
+# Show next 5 executions with timeline
+cronparse next "0 9 * * *"
+
+# Show 10 executions without timeline
+cronparse next "0 9 * * *" --count 10 --no-timeline
+```
+
+### generate
+
+Interactive wizard to build cron expressions step by step.
+
+```bash
+cronparse generate
+```
+
+### explain
+
+Get human-readable description of a cron expression.
+
+```bash
+cronparse explain "0 9 * * *"
+# Output: At 09:00 AM, every day
+
+# Use 24-hour format
+cronparse explain "0 14 * * *" --24h
+# Output: At 14:00, every day
+```
+
+## Natural Language Patterns
+
+The tool supports various natural language patterns:
+
+| Pattern | Cron |
+|---------|------|
+| every 5 minutes | */5 * * * * |
+| every hour | 0 * * * * |
+| daily at 9am | 0 9 * * * |
+| daily at 2:30pm | 30 14 * * * |
+| every Monday at 9am | 0 9 * * 1 |
+| on the 1st of every month at midnight | 0 0 1 * * |
+| every 30 seconds (via cron workaround) | * * * * * |
+
+## Output Formats
+
+All commands support JSON output for scripting:
+
+```bash
+cronparse parse "0 9 * * *" --json
+cronparse next "0 9 * * *" --json
+cronparse explain "0 9 * * *" --json
+```
+
+## Cron Expression Format
+
+Standard cron format with 5 fields:
+
+```
+┌───────────── minute (0 - 59)
+│ ┌───────────── hour (0 - 23)
+│ │ ┌───────────── day of month (1 - 31)
+│ │ │ ┌───────────── month (1 - 12)
+│ │ │ │ ┌───────────── day of week (0 - 6) (Sunday = 0)
+│ │ │ │ │
+* * * * *
+```
+
+## Development
+
+### Setup
+
+```bash
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # Linux/macOS
+# or
+.\venv\Scripts\activate  # Windows
+
+# Install dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/ -v
+
+# Run linter
+ruff check .
+```
+
+### Project Structure
+
+```
+cron-parser-cli/
+├── src/cronparse/
+│   ├── __init__.py      # Package init
+│   ├── cli.py           # Main CLI entry point
+│   ├── parser.py        # Cron parsing & validation
+│   ├── nlp.py           # Natural language conversion
+│   ├── scheduler.py     # Next execution calculations
+│   ├── generator.py     # Interactive wizard
+│   └── describer.py     # Human-readable descriptions
+├── tests/
+│   ├── test_parser.py
+│   ├── test_nlp.py
+│   ├── test_scheduler.py
+│   ├── test_generator.py
+│   ├── test_cli.py
+│   └── test_describer.py
+├── pyproject.toml
+└── README.md
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.