PMDaemon v0.1.4 - Documentation Accuracy & Stability

Released on May 29, 2025

PMDaemon v0.1.4 represents a critical documentation accuracy release that fixes major discrepancies between documentation and actual implementation. This release ensures users can rely on the documentation to accurately reflect PMDaemon's capabilities.

🎯 Key Highlights

• 📚 Documentation Accuracy - Fixed major discrepancies between docs and implementation
• 🔒 Security Hardening - Removed dangerous API endpoints and improved security model
• 🐛 Critical Bug Fix - Fixed uptime monitoring showing 0s for all processes
• ✅ Production Ready - Documentation now accurately reflects actual capabilities

📚 Documentation Overhaul

Fixed Major Inaccuracies

Load Balancing Documentation

• Before: Claimed enterprise-grade load balancing with round-robin algorithms, SSL termination
• After: Accurately describes clustering capabilities with external load balancer integration
• Impact: Users now understand PMDaemon focuses on process management, not traffic routing

API Error Format

• Before: Complex nested error structure with codes, details, timestamps
• After: Simple {"success": false, "error": "message"} format matching implementation
• Impact: API integration code will work correctly

CLI Parameters

• Before: Extensive --health-check-* parameters that don't exist
• After: Removed all non-existent health check CLI parameters
• Impact: Users won't try to use parameters that cause errors

Library API Methods

• Before: Incorrect method names like start_process(), wait_for_ready()
• After: Correct method names like start(), removed non-existent methods
• Impact: Rust library integration will compile and work

Environment Variables

• Before: 10+ fictional environment variables like PMDAEMON_LOG_LEVEL
• After: Only PMDAEMON_HOME (the one that actually works)
• Impact: Environment configuration will work as documented

WebSocket API

• Before: Claimed bidirectional communication with command sending
• After: Clearly marked as read-only for security
• Impact: Prevents security vulnerabilities from attempted command injection

Watch Mode

• Before: Working file watching examples throughout documentation
• After: Marked as "not yet implemented" with current status
• Impact: Users won't expect functionality that doesn't exist

Installation Methods

• Before: Claimed availability through package managers (Homebrew, apt, etc.)
• After: Accurately reflects pre-1.0 status with manual installation only
• Impact: Users know the actual installation methods

Exit Codes

• Before: Complex exit code system (0, 1, 2, 126, 127, etc.)
• After: Simple Unix standard (0=success, 1=error)
• Impact: Shell scripts will handle errors correctly

🔒 Security Improvements

Removed Dangerous API Endpoint

# This dangerous endpoint has been removed for security
# POST /api/processes - Could execute arbitrary commands

Enhanced Authentication & API Key Management

• Auto-generated API keys - Secure keys created and saved automatically on first web server start
• Persistent storage - Keys saved to ~/.pmdaemon/api-key and reused automatically
• Simple management - show-api-key and regenerate-api-key commands
• Environment variable support - PMDAEMON_API_KEY still works if needed
• Cross-platform compatible - Works reliably on Windows, Linux, and macOS

# Auto-generates secure API key on first run
pmdaemon web

# Key management commands
pmdaemon show-api-key        # Display current key
pmdaemon regenerate-api-key  # Generate new key

🐛 Critical Bug Fixes

Fixed Uptime Monitoring

Issue: All processes showed 0s for uptime values Root Cause: Monitoring data collected but never applied to processes
Fix: Added proper monitoring data application in update_monitoring_data()

// Fixed in src/manager.rs
for (id, metrics) in monitoring_data {
    if let Some(process) = processes.get_mut(&id) {
        process.update_monitoring(metrics.cpu_usage, metrics.memory_usage);
    }
}

📊 Documentation Statistics

Files Reviewed: 35+ documentation files
Major Issues Fixed: 15+ critical discrepancies
Lines Updated: 500+ lines of corrections
Accuracy Improvement: 🚫 Fictional → ✅ Accurate

🔄 Breaking Changes

Removed Features (That Never Existed)

• Health check CLI parameters (--health-check-url, etc.)
• Complex API error format
• Bidirectional WebSocket commands
• Most environment variables (only PMDAEMON_HOME works)
• Package manager installations

API Changes

• Simplified error response format
• Removed dangerous process creation endpoint
• Enhanced authentication requirements

🏗️ Before vs After

Feature	v0.1.3 Docs	v0.1.4 Reality
Load Balancing	❌ Enterprise features	✅ Process clustering
Health Check CLI	❌ Extensive parameters	✅ Config file only
API Errors	❌ Complex nested format	✅ Simple format
Library Methods	❌ Wrong method names	✅ Correct methods
Environment Vars	❌ 10+ fictional vars	✅ Only PMDAEMON_HOME
WebSocket API	❌ Bidirectional claims	✅ Read-only security
Watch Mode	❌ Working examples	✅ Not implemented
Installation	❌ Package managers	✅ Manual/source only
Exit Codes	❌ Complex system	✅ Unix standard

📋 Migration Guide

For CLI Users

# Remove health check parameters (they never worked)
# Before (would error):
pmdaemon start app.js --health-check-url http://localhost:3000/health

# After (works):
pmdaemon start app.js --name app

For API Users

// Update error handling for correct format
// Before:
if (response.error.code === 'PROCESS_NOT_FOUND') 

// After:
if (!response.success && response.error === 'Process not found')

For Library Users

// Update method names
// Before:
let id = manager.start_process(config).await?;

// After:  
let id = manager.start(config).await?;

🔮 Looking Forward

Looking Forward to v0.1.5

• Watch Mode Implementation: Add file watching capabilities
• Enhanced Health Checks: CLI parameter support
• Package Manager Support: Prepare for crates.io and GitHub releases

📖 Updated Documentation

All documentation has been thoroughly reviewed and updated:

• 35+ files reviewed for accuracy
• 15+ major discrepancies fixed
• Complete alignment between docs and implementation
• Production-ready documentation standards

⚡ Performance & Reliability

• Uptime Monitoring: Now shows accurate process uptime values
• Memory Efficiency: Proper monitoring data management
• Security: Removed dangerous endpoints and improved authentication

🎯 Upgrade Instructions

From v0.1.3

# 1. Download new binary or rebuild from source
cargo build --release

# 2. Update any scripts using removed CLI parameters
# 3. Update API integration to use correct error format
# 4. Update library code to use correct method names

Verification

# Test uptime monitoring fix
pmdaemon start "sleep 60" --name test-uptime
pmdaemon list  # Should show actual uptime, not 0s

# Test API authentication
pmdaemon web --api-key "test-key"
curl -H "Authorization: Bearer test-key" http://localhost:9615/api/processes

🤝 Community Impact

This release represents a commitment to documentation accuracy and production reliability. Users can now trust that:

• ✅ Documentation matches implementation
• ✅ Examples actually work
• ✅ Security is properly implemented
• ✅ APIs behave as documented

📝 Notes

• No new features - Focus on accuracy and stability
• Breaking changes only affect features that never worked
• Security improvements through dangerous endpoint removal
• Foundation for reliable future development

---

Full Changelog: v0.1.3...v0.1.4
Download: GitHub Releases

PMDaemon v0.1.4 ensures you can rely on the documentation to accurately reflect what PMDaemon actually does, making it truly production-ready.