From f464b78ac2f8fac6a267271486705e17a6233695 Mon Sep 17 00:00:00 2001 From: diogo464 Date: Thu, 19 Jun 2025 09:48:21 +0100 Subject: Add comprehensive README.md with complete documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add detailed overview highlighting key features and benefits - Include installation instructions for multiple methods - Provide comprehensive command reference with examples - Document use cases for development, LLM integration, DevOps - Add practical examples for each major workflow - Include machine-readable output documentation for automation - Document file management, security, and system requirements - Add contributing guidelines and development setup - Position as LLM-friendly tool for background process management - Focus on developer experience and automation integration - Highlight key differentiators vs similar tools README emphasizes: - Simplicity and zero-configuration approach - LLM agent integration capabilities - Development workflow optimization - Practical examples for common scenarios - Clear documentation for automation use cases 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- README.md | 350 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ src/main.rs | 21 ++-- 2 files changed, 362 insertions(+), 9 deletions(-) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..cbc8fe5 --- /dev/null +++ b/README.md @@ -0,0 +1,350 @@ +# Demon - Background Process Manager + +A lightweight, intuitive CLI tool for spawning, managing, and monitoring background processes on Linux systems. Perfect for development servers, long-running tasks, and automation workflows. + +## ✨ Features + +- **Simple Process Management**: Start, stop, and monitor background processes with ease +- **Persistent Logging**: Automatic stdout/stderr capture to files +- **Real-time Monitoring**: Tail logs in real-time with file watching +- **Process Lifecycle**: Graceful termination with SIGTERM/SIGKILL fallback +- **Machine-readable Output**: Perfect for scripting and LLM agent integration +- **Zero Configuration**: Works out of the box, no setup required + +## 🚀 Installation + +### From Source +```bash +git clone https://github.com/yourusername/demon +cd demon +cargo install --path . +``` + +### From Crates.io (Coming Soon) +```bash +cargo install demon +``` + +## 🎯 Quick Start + +```bash +# Start a development server +demon run web-server python -m http.server 8080 + +# Monitor the logs in real-time +demon tail web-server + +# Check what's running +demon list + +# Stop the server +demon stop web-server + +# Clean up finished processes +demon clean +``` + +## 📋 Command Reference + +### `demon run [command...]` +Spawn a background process with the given identifier. + +```bash +# Basic usage +demon run my-app ./my-application + +# Development server +demon run dev-server npm run dev + +# Complex commands (use -- to separate) +demon run backup-job -- rsync -av /data/ /backup/ + +# Long-running computation +demon run ml-training python train_model.py --epochs 100 +``` + +### `demon list [--quiet]` +List all managed processes and their status. + +```bash +# Human-readable format +demon list + +# Machine-readable format (for scripts/agents) +demon list --quiet +``` + +### `demon status ` +Show detailed status information for a specific process. + +```bash +demon status web-server +``` + +### `demon stop [--timeout ]` +Stop a running process gracefully (SIGTERM, then SIGKILL if needed). + +```bash +# Default 10-second timeout +demon stop web-server + +# Custom timeout +demon stop slow-service --timeout 30 +``` + +### `demon tail [--stdout] [--stderr]` +Follow log files in real-time (like `tail -f`). + +```bash +# Follow both stdout and stderr +demon tail web-server + +# Follow only stdout +demon tail web-server --stdout + +# Follow only stderr +demon tail web-server --stderr +``` + +### `demon cat [--stdout] [--stderr]` +Display the complete contents of log files. + +```bash +# Show both logs +demon cat web-server + +# Show only stdout +demon cat web-server --stdout +``` + +### `demon clean` +Remove orphaned files from processes that are no longer running. + +```bash +demon clean +``` + +### `demon llm` +Output comprehensive usage guide optimized for LLM consumption. + +```bash +demon llm +``` + +## 🎮 Use Cases + +### Development Workflows +Perfect for managing development servers and build processes: + +```bash +# Start multiple development services +demon run api-server npm run dev +demon run frontend yarn start +demon run db-server docker run -p 5432:5432 postgres + +# Monitor everything +demon list +demon tail api-server --stderr # Watch for errors +``` + +### LLM Agent Integration +Designed for seamless automation and LLM agent workflows: + +```bash +# Agents can start long-running processes +demon run data-processor python process_large_dataset.py + +# Check status programmatically +if demon status data-processor | grep -q "RUNNING"; then + echo "Processing is still running" +fi + +# Get machine-readable process list +demon list --quiet | while IFS=: read id pid status; do + echo "Process $id ($pid) is $status" +done +``` + +### Background Tasks & Scripts +Ideal for CI/CD, backups, and system maintenance: + +```bash +# Database backup +demon run nightly-backup -- pg_dump mydb > backup.sql + +# Log file processing +demon run log-analyzer tail -f /var/log/app.log | grep ERROR + +# System monitoring +demon run monitor -- iostat -x 1 +``` + +### DevOps & System Administration +Manage services without complex init systems: + +```bash +# Application deployment +demon run app-server ./deploy.sh production + +# Health monitoring +demon run health-check -- while true; do curl -f http://localhost:8080/health || exit 1; sleep 30; done + +# Resource monitoring +demon run resource-monitor -- top -b -n1 | head -20 +``` + +## 🏗️ How It Works + +When you run `demon run web-server python -m http.server 8080`: + +1. **Process Creation**: Spawns the process detached from your terminal +2. **File Management**: Creates three files: + - `web-server.pid` - Contains the process ID and command + - `web-server.stdout` - Captures standard output + - `web-server.stderr` - Captures error output +3. **Process Monitoring**: Tracks process lifecycle independently +4. **Log Management**: Files persist after process termination for inspection + +## 🤖 LLM Agent Integration + +Demon is specifically designed to work seamlessly with LLM agents and automation tools: + +### Machine-Readable Output +```bash +# Get process status in parseable format +demon list --quiet +# Output: web-server:12345:RUNNING +# backup-job:12346:DEAD +``` + +### Scripting Examples +```bash +# Start service if not running +demon list --quiet | grep -q "web-server:" || demon run web-server python -m http.server + +# Wait for process to finish +while demon list --quiet | grep -q "backup-job:.*:RUNNING"; do + sleep 5 +done + +# Get all running processes +demon list --quiet | grep ":RUNNING" | cut -d: -f1 +``` + +### Error Handling +```bash +# Check if process started successfully +if demon run api-server ./start-api.sh; then + echo "API server started successfully" + demon tail api-server & # Monitor in background +else + echo "Failed to start API server" + exit 1 +fi +``` + +## 📁 File Management + +### File Locations +All files are created in the current working directory: +- `.pid` - Process ID and command information +- `.stdout` - Standard output log +- `.stderr` - Standard error log + +### Cleanup +- Files persist after process termination for inspection +- Use `demon clean` to remove files from dead processes +- Consider adding `*.pid`, `*.stdout`, `*.stderr` to `.gitignore` + +### Log Rotation +- Demon doesn't handle log rotation internally +- For long-running processes, implement rotation in your application +- Or use external tools like `logrotate` + +## 🔧 Advanced Usage + +### Process Management +```bash +# Graceful shutdown with custom timeout +demon stop long-running-task --timeout 60 + +# Force kill if process is stuck +demon stop stuck-process --timeout 1 +``` + +### Monitoring & Debugging +```bash +# Monitor multiple processes +for id in web-server api-server worker; do + demon tail $id --stderr & +done + +# Check resource usage +demon run monitor -- ps aux | grep my-app +demon cat monitor +``` + +### Integration with System Tools +```bash +# Use with systemd +demon run my-service systemctl --user start my-app + +# Use with Docker +demon run container -- docker run -d --name myapp nginx + +# Use with tmux/screen for complex setups +demon run dev-env -- tmux new-session -d 'npm run dev' +``` + +## ⚠️ System Requirements + +- **Operating System**: Linux (uses `kill` command for process management) +- **Rust**: 1.70+ (for building from source) +- **Permissions**: Standard user permissions (no root required) + +## 🔒 Security Considerations + +- Demon runs processes with the same permissions as the calling user +- PID files contain process information - protect accordingly +- Log files may contain sensitive information from your applications +- No network access or elevated privileges required + +## 🤝 Contributing + +We welcome contributions! Here's how to get started: + +1. **Fork the repository** +2. **Create a feature branch**: `git checkout -b feature/amazing-feature` +3. **Make your changes** +4. **Run tests**: `cargo test` +5. **Format code**: `cargo fmt` +6. **Submit a pull request** + +### Development Setup +```bash +git clone https://github.com/yourusername/demon +cd demon +cargo build +cargo test +``` + +## 📝 License + +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. + +## 🐛 Bug Reports & Feature Requests + +Found a bug or have a feature idea? Please open an issue on [GitHub Issues](https://github.com/yourusername/demon/issues). + +## 📚 Similar Tools + +- **pm2** - Process manager for Node.js applications +- **supervisor** - Process control system for Unix +- **systemd** - System and service manager for Linux +- **screen/tmux** - Terminal multiplexers + +Demon focuses on simplicity, LLM integration, and developer experience over complex process management features. + +--- + +**Built with ❤️ in Rust** \ No newline at end of file diff --git a/src/main.rs b/src/main.rs index bedcb74..e90bfed 100644 --- a/src/main.rs +++ b/src/main.rs @@ -80,12 +80,15 @@ impl PidFile { let lines: Vec<&str> = contents.lines().collect(); if lines.is_empty() { - return Err(PidFileReadError::FileInvalid("PID file is empty".to_string())); + return Err(PidFileReadError::FileInvalid( + "PID file is empty".to_string(), + )); } - let pid = lines[0].trim().parse::().map_err(|_| { - PidFileReadError::FileInvalid("Invalid PID on first line".to_string()) - })?; + let pid = lines[0] + .trim() + .parse::() + .map_err(|_| PidFileReadError::FileInvalid("Invalid PID on first line".to_string()))?; let command: Vec = lines[1..].iter().map(|line| line.to_string()).collect(); @@ -647,7 +650,10 @@ fn list_daemons(quiet: bool) -> Result<()> { println!("{}:{}:{}", id, pid_file_data.pid, status); } else { let command = pid_file_data.command_string(); - println!("{:<20} {:<8} {:<10} {}", id, pid_file_data.pid, status, command); + println!( + "{:<20} {:<8} {:<10} {}", + id, pid_file_data.pid, status, command + ); } } Err(PidFileReadError::FileNotFound) => { @@ -665,10 +671,7 @@ fn list_daemons(quiet: bool) -> Result<()> { if quiet { println!("{}:INVALID:ERROR", id); } else { - println!( - "{:<20} {:<8} {:<10} {}", - id, "INVALID", "ERROR", reason - ); + println!("{:<20} {:<8} {:<10} {}", id, "INVALID", "ERROR", reason); } } Err(PidFileReadError::IoError(_)) => { -- cgit