From 14c0e3630ff7ea514370d957790221fa92421fe4 Mon Sep 17 00:00:00 2001 From: 7000pctAUTO Date: Thu, 29 Jan 2026 11:10:22 +0000 Subject: [PATCH] Add project metadata, README, and LICENSE --- README.md | 200 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 198 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index cf74f79..ed82a40 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,199 @@ -# devterm +# Devterm -A CLI tool that spawns a local web server providing browser-based developer utilities with TUI menu and hot-reload support \ No newline at end of file +![Python Version](https://img.shields.io/badge/python-3.8%2B-blue) +![License](https://img.shields.io/badge/License-MIT-green) +![Version](https://img.shields.io/badge/Version-0.1.0-orange) + +A CLI tool that spawns a local web server providing browser-based developer utilities. Features a TUI menu for tool selection, hot-reload support, and a modern web interface built with HTMX. + +## Features + +- **TUI Menu**: Interactive terminal menu using Rich for beautiful CLI interactions +- **Browser Interface**: Clean, modern UI with HTMX for dynamic content +- **Hot Reload**: Uvicorn reload for development - changes reflect instantly +- **Local Processing**: All data processed locally, no external API calls +- **Multiple Tools**: Essential developer utilities in one place + +### Available Tools + +- **JSON Formatter** - Format, validate, and prettify JSON data +- **JWT Decoder** - Decode and inspect JWT tokens header and payload +- **Cron Validator** - Validate cron expressions and calculate next run times +- **Base64 Tool** - Encode and decode Base64 strings +- **URL Encoder** - Encode and decode URL components + +## Installation + +### From PyPI + +```bash +pip install devterm +``` + +### From Source + +```bash +git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/devterm.git +cd devterm +pip install -e . +``` + +### Using pipx (Recommended for CLI Tools) + +```bash +pipx install devterm +``` + +## Usage + +### Basic Usage + +Start the Devterm server with default settings: + +```bash +devterm +``` + +This will: +1. Display a TUI menu with available tools +2. Automatically open your browser to `http://127.0.0.1:8000` +3. Start the server with hot-reload enabled + +### Custom Configuration + +Set custom host and port using environment variables: + +```bash +DEVTERM_HOST=0.0.0.0 DEVTERM_PORT=8080 devterm +``` + +Or via command-line arguments (if supported): + +```bash +devterm --host 0.0.0.0 --port 8080 +``` + +## Configuration + +### Environment Variables + +| Variable | Default | Description | +|----------|---------|-------------| +| `DEVTERM_HOST` | `127.0.0.1` | Server host address | +| `DEVTERM_PORT` | `8000` | Server port | +| `DEVTERM_DEBUG` | `false` | Enable debug mode | + +### Programmatic Usage + +```python +from devterm.main import main + +# Start the server programmatically +main(host="127.0.0.1", port=8000) +``` + +## Architecture + +``` +devterm/ +├── __init__.py # Package initialization +├── main.py # Entry point +├── config.py # Configuration management +├── server/ +│ ├── app.py # FastAPI application +│ └── routes.py # API routes +├── tools/ +│ ├── json_tool.py # JSON formatting tool +│ ├── jwt_tool.py # JWT decoder tool +│ ├── cron_tool.py # Cron validator tool +│ ├── base64_tool.py # Base64 encoder/decoder +│ └── url_tool.py # URL encoder/decoder +├── templates/ # HTML templates +├── tui/ +│ └── menu.py # TUI menu implementation +└── tests/ # Test suite +``` + +## Development + +### Setup + +```bash +git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/devterm.git +cd devterm +pip install -e ".[dev]" +``` + +### Running Tests + +```bash +# Run all tests +pytest + +# Run with coverage +pytest --cov=devterm --cov-report=html + +# Run specific test categories +pytest tests/unit/ # Unit tests +pytest tests/integration/ # Integration tests +``` + +### Linting + +```bash +# Check code style +ruff check . + +# Auto-fix issues +ruff check --fix . +``` + +### Type Checking + +```bash +mypy devterm/ +``` + +### Running Locally + +```bash +# Start development server with hot reload +devterm + +# Or run directly with uvicorn +uvicorn devterm.server.app:app --reload --host 127.0.0.1 --port 8000 +``` + +## Tech Stack + +- **FastAPI** - Modern Python web framework +- **Uvicorn** - ASGI server implementation +- **Rich** - Rich text and beautiful formatting in terminal +- **Jinja2** - Template engine +- **HTMX** - Dynamic HTML content +- **PyJWT** - JWT handling +- **Pycron** - Cron expression parsing + +## Contributing + +1. Fork the repository +2. Create a feature branch (`git checkout -b feature/amazing-feature`) +3. Make your changes +4. Run tests and linting +5. Commit your changes (`git commit -m 'Add amazing feature'`) +6. Push to the branch (`git push origin feature/amazing-feature`) +7. Open a Pull Request + +## Changelog + +See [CHANGELOG.md](CHANGELOG.md) for a list of changes. + +## License + +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. + +## Support + +- 📧 Email: support@devterm.dev +- 🐛 Issues: [Gitea Issues](https://7000pct.gitea.bloupla.net/7000pctAUTO/devterm/issues) +- 💬 Discussions: [Gitea Discussions](https://7000pct.gitea.bloupla.net/7000pctAUTO/devterm/discussions) \ No newline at end of file