🚀 Thecultofcult CLI - Multi-Instance File Download & Print System

A production-ready, cross-platform TypeScript CLI application that processes file downloads from a Supabase PGMQ queue and executes print commands using event-driven architecture. Supports multiple distributed instances across Windows, macOS, and Linux with comprehensive monitoring, health tracking, and real-time observability.

✅ 324+ Tests Passing | ⚡ Event-Driven | 🌐 Cross-Platform | 🔄 Multi-Instance | 🖨️ Print Integration | 🏗️ Clean Architecture | 🔒 Type-Safe | 📊 92.4% Coverage | 🤖 CI/CD Automated

🚀 Quick Navigation

| Task | Section | |------|---------| | Install the CLI | Installation & Setup | | Complete setup guide | ONBOARDING.md | | Run with PM2 | PM2_GUIDE.md | | Deploy to production | DEPLOYMENT.md | | View all features | Features | | Read documentation | Documentation | | Visual diagrams | DIAGRAMS.md |

📦 Installation & Setup

# Install globally via npm
npm install -g thecultofcult-cli

# Or use directly with npx
npx thecultofcult-cli start

📖 Complete Setup Guide: ONBOARDING.md

• Install from npm (for users)
• Local development setup (for developers)
• Configuration and environment setup
• Platform-specific instructions

🔄 Production Deployment: PM2_GUIDE.md

• PM2 process manager setup
• Auto-start on system boot
• Monitoring and log management

✨ Features

🌐 Cross-Platform Support

• Windows, macOS, Linux: Single codebase runs on all platforms
• Platform-Aware Paths: Automatic validation for drive letters (Windows) and Unix paths
• Path Resolution: Home directory expansion (~, %USERPROFILE%), environment variables
• Absolute Paths Only: Clear, unambiguous file locations
• Reserved Name Detection: Windows reserved names (CON, PRN, etc.) automatically blocked

🔄 Multi-Instance Architecture

• Distributed Processing: Run multiple CLI instances across different computers
• Instance Registration: Automatic registration with unique identity
• Health Monitoring: Heartbeat system tracks instance health (5-minute intervals)
• Workload Tracking: Per-instance statistics (jobs processed, failures, bytes downloaded)
• Configuration Hierarchy: Global config with instance-specific overrides
• Platform Distribution: Track workload across Windows, Mac, and Linux instances

Core Functionality

• 📥 File Download: Downloads files from any public URL to specified folders
• 🖨️ Print Integration: Executes print commands after successful downloads using lpr
• 📬 Queue-Based Processing: Uses Supabase PGMQ for reliable, scalable message handling
• ⚡ Event-Driven: Blocking reads eliminate polling - instant message processing
• 🚀 Fail-Fast Design: No retry mechanism - immediate, clear failure handling
• 📊 Complete Observability: All logs and metrics stored in Supabase
• 🎯 Single Processing: Each message processed exactly once with ACID guarantees
• 🔄 Graceful Degradation: Print failures don't fail the download job

Architecture & Quality

• 🏗️ Clean Architecture: SOLID principles with clear layer separation (Domain, Application, Infrastructure)
• 💉 Dependency Injection: TSyringe IoC container for testability
• 🧪 Test-Driven Development: 324+ tests with 92.4% coverage
• 🔒 Type-Safe: Full TypeScript with strict mode
• 🛡️ Security: Path traversal protection, input validation, RLS policies
• 📐 Interface-Driven Design: All adapters implement domain interfaces (IPrintAdapter, IPgmqAdapter, etc.)

Admin UI

• 🎨 Web Dashboard: Real-time monitoring and management interface
• 📈 Live Statistics: Track completed, processing, and failed jobs
• 📝 Detailed Logs: View execution logs with expandable data and stack traces
• 🔄 Auto-Refresh: Real-time updates every 3 seconds
• ✉️ Queue Management: Send test messages directly from the UI

📚 Documentation

Welcome to the CLI Base documentation! This streamlined index helps you find exactly what you need.

🚀 Getting Started

New to the project? Follow this path:

1. README - Project overview and quick start (you are here!)
2. ONBOARDING.md - Complete setup and first-time guide
3. ADMIN_UI_GUIDE.md - Using the web dashboard

📖 Core Documentation

For Developers

ONBOARDING.md - Your first stop

• Prerequisites and installation
• Local development setup
• Configuration guide
• Running the application
• Verification and testing

DEVELOPER_GUIDE.md - Deep dive into the codebase

• Clean Architecture principles
• Core components and services
• Design patterns
• Testing strategy (291 tests)
• Debugging techniques
• Contributing guidelines

For Operators

OPERATIONS.md - Running in production

• Multi-instance architecture
• Cross-platform support (Windows, Mac, Linux)
• Monitoring and health checks
• Troubleshooting guide
• Performance tuning

DEPLOYMENT.md - Production deployment

• Supabase deployment
• Worker deployment (PM2, Docker, Systemd)
• CI/CD setup (GitHub Actions, GitLab CI)
• Publishing to npm
• Migration guide

PM2_GUIDE.md - PM2 process manager

• Complete PM2 setup for Windows, macOS, and Linux
• Auto-start on system boot configuration
• Process management and monitoring
• Log management and rotation
• Troubleshooting guide

Reference

ADMIN_UI_GUIDE.md - Web interface guide

• Sending messages to queue
• Viewing messages and logs
• Dashboard statistics
• API endpoints

PRD-CLI-BASE.md - Product requirements

• Full feature specifications
• Technical requirements
• Use cases

DIAGRAMS.md - Visual diagrams

• Architecture diagrams (Clean Architecture, System Context, Multi-Instance)
• Component diagrams (Services, Repositories, Adapters)
• Sequence diagrams (Message processing, Configuration, Path resolution)
• E2E flow diagrams (Complete workflows, Admin UI, Monitoring)
• Database schema (ERD, PGMQ structure)

📋 Quick Reference

Common Tasks

| Task | Documentation | |------|---------------| | First-time setup | ONBOARDING.md | | Understand architecture | DEVELOPER_GUIDE.md | | Run tests | DEVELOPER_GUIDE.md | | Deploy to production | DEPLOYMENT.md | | Troubleshoot issues | OPERATIONS.md | | Multi-instance setup | OPERATIONS.md | | Use Admin UI | ADMIN_UI_GUIDE.md |

Learning Path

Week 1: Basics

1. Read ONBOARDING.md
2. Complete local setup
3. Run the application
4. Send test messages via Admin UI

Week 2: Development

1. Read DEVELOPER_GUIDE.md
2. Explore the codebase
3. Run tests: npm test
4. Make a small code change

Week 3: Production

1. Read OPERATIONS.md
2. Read DEPLOYMENT.md
3. Set up multi-instance deployment
4. Configure monitoring

By Role

New Developer:

1. ONBOARDING.md - Get started
2. DEVELOPER_GUIDE.md - Learn the codebase
3. ADMIN_UI_GUIDE.md - Test your changes

DevOps Engineer:

1. DEPLOYMENT.md - Deploy to production
2. OPERATIONS.md - Monitor and maintain
3. ONBOARDING.md - Configuration reference

Product Manager:

1. README - Feature overview (you are here!)
2. PRD-CLI-BASE.md - Full requirements
3. ADMIN_UI_GUIDE.md - User interface

🔍 What's New

Version 2.0.0 Documentation Consolidation:

• ✅ Streamlined from 23 files to 6 core documents
• ✅ Removed redundancy and overlap
• ✅ Clear learning path for new developers
• ✅ Comprehensive coverage of all features
• ✅ Better organization by role and task

🆘 Need Help?

Quick Troubleshooting:

1. Check OPERATIONS.md - Troubleshooting
2. Review logs in Admin UI or Supabase Studio
3. Verify setup in ONBOARDING.md

Common Issues:

• Worker not processing? → OPERATIONS.md
• Database connection issues? → OPERATIONS.md
• Path validation errors? → OPERATIONS.md
• Deployment problems? → DEPLOYMENT.md

🏗️ Architecture

Built with Clean Architecture principles:

• Domain Layer: Business entities and rules
• Application Layer: Use cases and services
• Infrastructure Layer: External integrations (Supabase, PGMQ, File System)
• CLI Layer: Command-line interface

📊 Visual Diagrams: DIAGRAMS.md

• System architecture and component diagrams
• Sequence diagrams for key workflows
• Database schema (ERD)

📖 Detailed Architecture: DEVELOPER_GUIDE.md

🧪 Development & Testing

Testing: 324+ tests with 92.4% coverage

npm test              # Run all tests
npm run test:coverage # Coverage report

Code Quality:

npm run lint         # Lint code
npm run format       # Format code
npm run type-check   # TypeScript checks

📖 Development Guide: DEVELOPER_GUIDE.md

• Testing strategy and best practices
• Debugging techniques
• Contributing guidelines

📝 Usage

Sending Messages: Use the Admin UI or API

• Admin UI: http://127.0.0.1:54321/functions/v1/admin-ui
• API Examples: See ADMIN_UI_GUIDE.md

Monitoring: View logs in Supabase Studio or Admin UI

• Studio: http://127.0.0.1:54323
• Tables: messages, job_logs, cli_instances

Configuration: Environment variables and database config

• Setup Guide: ONBOARDING.md
• Config Priority: Instance > Global > ENV > Default

🔧 Troubleshooting

Common Issues:

• Worker not processing? → OPERATIONS.md
• Database connection issues? → OPERATIONS.md
• Path validation errors? → OPERATIONS.md
• Windows command not recognized? → ONBOARDING.md

📖 Complete Guide: OPERATIONS.md

📦 Deployment

Production Deployment: DEPLOYMENT.md

• Supabase deployment
• Worker deployment (PM2, Docker, Systemd)
• CI/CD setup
• Publishing to npm

Process Management: PM2_GUIDE.md

• PM2 setup and auto-start
• Monitoring and logs

🤝 Contributing

Contributions are welcome! Please see DEVELOPER_GUIDE.md for:

• Development setup
• Testing requirements
• Code quality standards
• Contributing guidelines

📄 License

MIT License - see LICENSE file for details

🆘 Support

Documentation: See Documentation section above for complete guides

Issues: Check OPERATIONS.md for troubleshooting

npm Package: https://www.npmjs.com/package/thecultofcult-cli

Built with ❤️ using TypeScript, Supabase, and Clean Architecture principles