# 🚀 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**

[![npm version](https://img.shields.io/npm/v/thecultofcult-cli.svg)](https://www.npmjs.com/package/thecultofcult-cli)
[![npm downloads](https://img.shields.io/npm/dm/thecultofcult-cli.svg)](https://www.npmjs.com/package/thecultofcult-cli)
[![CI](https://github.com/Shiphero-Yolo/thecultofcult-cli/workflows/CI/badge.svg)](https://github.com/Shiphero-Yolo/thecultofcult-cli/actions)
[![Tests](https://img.shields.io/badge/tests-324%20passing-brightgreen)]()
[![Coverage](https://img.shields.io/badge/coverage-92.4%25-brightgreen)]()
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue)]()
[![Platforms](https://img.shields.io/badge/platforms-Windows%20%7C%20macOS%20%7C%20Linux-blue)]()
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

---

## 🚀 Quick Navigation

| Task | Section |
|------|---------|
| **Install the CLI** | [Installation & Setup](#-installation--setup) |
| **Complete setup guide** | [ONBOARDING.md](docs/ONBOARDING.md) |
| **Run with PM2** | [PM2_GUIDE.md](docs/PM2_GUIDE.md) |
| **Deploy to production** | [DEPLOYMENT.md](docs/DEPLOYMENT.md) |
| **View all features** | [Features](#-features) |
| **Read documentation** | [Documentation](#-documentation) |
| **Visual diagrams** | [DIAGRAMS.md](docs/diagrams/DIAGRAMS.md) |

---

## 📦 Installation & Setup

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

# Or use directly with npx
npx thecultofcult-cli start
```

**📖 Complete Setup Guide**: [ONBOARDING.md](docs/ONBOARDING.md)
- Install from npm (for users)
- Local development setup (for developers)
- Configuration and environment setup
- Platform-specific instructions

**🔄 Production Deployment**: [PM2_GUIDE.md](docs/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](README.md)** - Project overview and quick start (you are here!)
2. **[ONBOARDING.md](docs/ONBOARDING.md)** - Complete setup and first-time guide
3. **[ADMIN_UI_GUIDE.md](docs/ADMIN_UI_GUIDE.md)** - Using the web dashboard

### 📖 Core Documentation

#### For Developers

**[ONBOARDING.md](docs/ONBOARDING.md)** - Your first stop
- Prerequisites and installation
- Local development setup
- Configuration guide
- Running the application
- Verification and testing

**[DEVELOPER_GUIDE.md](docs/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](docs/OPERATIONS.md)** - Running in production
- Multi-instance architecture
- Cross-platform support (Windows, Mac, Linux)
- Monitoring and health checks
- Troubleshooting guide
- Performance tuning

**[DEPLOYMENT.md](docs/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](docs/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](docs/ADMIN_UI_GUIDE.md)** - Web interface guide
- Sending messages to queue
- Viewing messages and logs
- Dashboard statistics
- API endpoints

**[PRD-CLI-BASE.md](docs/PRD-CLI-BASE.md)** - Product requirements
- Full feature specifications
- Technical requirements
- Use cases

**[DIAGRAMS.md](docs/diagrams/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](docs/ONBOARDING.md) |
| **Understand architecture** | [DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md) |
| **Run tests** | [DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md#testing) |
| **Deploy to production** | [DEPLOYMENT.md](docs/DEPLOYMENT.md) |
| **Troubleshoot issues** | [OPERATIONS.md](docs/OPERATIONS.md#troubleshooting) |
| **Multi-instance setup** | [OPERATIONS.md](docs/OPERATIONS.md#multi-instance-architecture) |
| **Use Admin UI** | [ADMIN_UI_GUIDE.md](docs/ADMIN_UI_GUIDE.md) |

#### Learning Path

**Week 1: Basics**
1. Read [ONBOARDING.md](docs/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](docs/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](docs/OPERATIONS.md)
2. Read [DEPLOYMENT.md](docs/DEPLOYMENT.md)
3. Set up multi-instance deployment
4. Configure monitoring

#### By Role

**New Developer:**
1. [ONBOARDING.md](docs/ONBOARDING.md) - Get started
2. [DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md) - Learn the codebase
3. [ADMIN_UI_GUIDE.md](docs/ADMIN_UI_GUIDE.md) - Test your changes

**DevOps Engineer:**
1. [DEPLOYMENT.md](docs/DEPLOYMENT.md) - Deploy to production
2. [OPERATIONS.md](docs/OPERATIONS.md) - Monitor and maintain
3. [ONBOARDING.md](docs/ONBOARDING.md#configuration) - Configuration reference

**Product Manager:**
1. [README](README.md) - Feature overview (you are here!)
2. [PRD-CLI-BASE.md](docs/PRD-CLI-BASE.md) - Full requirements
3. [ADMIN_UI_GUIDE.md](docs/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](docs/OPERATIONS.md#troubleshooting)
2. Review logs in Admin UI or Supabase Studio
3. Verify setup in [ONBOARDING.md](docs/ONBOARDING.md)

**Common Issues**:
- Worker not processing? → [OPERATIONS.md](docs/OPERATIONS.md#issue-worker-not-processing-messages)
- Database connection issues? → [OPERATIONS.md](docs/OPERATIONS.md#issue-database-connection-terminated)
- Path validation errors? → [OPERATIONS.md](docs/OPERATIONS.md#issue-path-validation-fails)
- Deployment problems? → [DEPLOYMENT.md](docs/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](docs/diagrams/DIAGRAMS.md)
- System architecture and component diagrams
- Sequence diagrams for key workflows
- Database schema (ERD)

**📖 Detailed Architecture**: [DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md)

## 🧪 Development & Testing

**Testing**: 324+ tests with 92.4% coverage
```bash
npm test              # Run all tests
npm run test:coverage # Coverage report
```

**Code Quality**:
```bash
npm run lint         # Lint code
npm run format       # Format code
npm run type-check   # TypeScript checks
```

**📖 Development Guide**: [DEVELOPER_GUIDE.md](docs/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](docs/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](docs/ONBOARDING.md#configuration)
- **Config Priority**: Instance > Global > ENV > Default

## 🔧 Troubleshooting

**Common Issues**:
- Worker not processing? → [OPERATIONS.md](docs/OPERATIONS.md#troubleshooting)
- Database connection issues? → [OPERATIONS.md](docs/OPERATIONS.md#issue-database-connection-terminated)
- Path validation errors? → [OPERATIONS.md](docs/OPERATIONS.md#issue-path-validation-fails)
- Windows command not recognized? → [ONBOARDING.md](docs/ONBOARDING.md)

**📖 Complete Guide**: [OPERATIONS.md](docs/OPERATIONS.md#troubleshooting)

## 📦 Deployment

**Production Deployment**: [DEPLOYMENT.md](docs/DEPLOYMENT.md)
- Supabase deployment
- Worker deployment (PM2, Docker, Systemd)
- CI/CD setup
- Publishing to npm

**Process Management**: [PM2_GUIDE.md](docs/PM2_GUIDE.md)
- PM2 setup and auto-start
- Monitoring and logs

## 🤝 Contributing

Contributions are welcome! Please see [DEVELOPER_GUIDE.md](docs/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](#-documentation) section above for complete guides

**Issues**: Check [OPERATIONS.md](docs/OPERATIONS.md#troubleshooting) for troubleshooting

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

---

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