@mmmbuto/nexuscli 0.7.6 → 0.7.7

package/lib/server/docs/README.md

@@ -0,0 +1,272 @@
+# NexusCLI Backend Documentation
+
+**Version**: 0.1.0
+**Created**: 2025-11-17
+**Status**: Design Phase
+
+---
+
+## 📚 Documentation Index
+
+This directory contains the **official design documentation** for NexusCLI backend, based on analysis of the NexusChat wrapper architecture.
+
+### Core Documents
+
+| Document | Purpose | Audience |
+|----------|---------|----------|
+| **⭐ [Design Principles](./DESIGN_PRINCIPLES.md)** | **Three Pillars**: Lightweight, Portable, ChatGPT UI | **Everyone - Start here!** |
+| **[Database Schema](./DATABASE_SCHEMA.md)** | SQLite schema for chat/sessions (Linux + Termux friendly) | Backend developers, DB admins |
+| **[API & Wrapper Contract](./API_WRAPPER_CONTRACT.md)** | Complete API specification for Control Plane and node wrappers | Backend developers, API consumers |
+| **[Architecture Overview](./ARCHITECTURE.md)** | High-level system architecture and component design | System architects, DevOps |
+| **[Pipeline Integration](./PIPELINE_INTEGRATION.md)** | How the 5-phase pipeline works (Analysis → Deploy) | Product managers, full-stack developers |
+| **[NexusChat Analysis](./NEXUSCHAT_ANALYSIS.md)** | Detailed analysis of reference implementation | Backend developers, researchers |
+
+---
+
+## 🎯 Quick Start
+
+### For Everyone
+
+**Start with**: [Design Principles](./DESIGN_PRINCIPLES.md) - Understand the three pillars (Lightweight, Portable, ChatGPT UI)
+
+### For Backend Developers
+
+1. Read [Architecture Overview](./ARCHITECTURE.md) to understand the system design
+2. Review [API Contract](./API_WRAPPER_CONTRACT.md) for endpoint specifications
+3. Study [Pipeline Integration](./PIPELINE_INTEGRATION.md) for workflow logic
+4. Check [NexusChat Analysis](./NEXUSCHAT_ANALYSIS.md) for reference implementation details
+
+### For Frontend Developers
+
+1. Focus on **API Contract** sections:
+   - Control Plane API endpoints
+   - SSE event streaming format
+   - Data structures (Node, Job, Event)
+
+### For DevOps Engineers
+
+1. Read **Architecture** for deployment strategy
+2. Check **Pipeline Integration** for monitoring metrics
+3. See **API Contract** for health check endpoints
+
+---
+
+## 🏗️ Architecture Summary
+
+**NexusCLI** = Distributed control plane for CLI orchestration
+
+```
+┌───────────────┐
+│   Frontend    │  ← React dashboard
+└───────┬───────┘
+        │ REST API + SSE
+        ↓
+┌───────────────┐
+│ Control Plane │  ← Express.js (this codebase)
+└───────┬───────┘
+        │ HTTP
+        ↓
+┌───────────────┐
+│ nexus-wrapper │  ← Node agent (separate repo)
+└───────┬───────┘
+        │ PTY
+        ↓
+┌───────────────┐
+│   CLI Tools   │  ← bash, git, docker, etc.
+└───────────────┘
+```
+
+**Inspired by**: NexusChat's claude-code-server wrapper architecture
+
+---
+
+## 🔄 5-Phase Pipeline
+
+```
+Analysis → Coordination → Execution → Test → Deploy
+```
+
+Each job follows this pipeline:
+
+1. **Analysis**: Validate command, check feasibility
+2. **Coordination**: Select node, queue job
+3. **Execution**: Run command, stream output
+4. **Test**: Verify results, assert expectations
+5. **Deploy**: Apply changes, trigger follow-ups
+
+See [Pipeline Integration](./PIPELINE_INTEGRATION.md) for details.
+
+---
+
+## 📊 Data Structures
+
+### Node
+```json
+{
+  "nodeId": "node-001",
+  "hostname": "server-prod-1",
+  "status": "online",
+  "capabilities": {
+    "tools": ["bash", "git", "docker"]
+  }
+}
+```
+
+### Job
+```json
+{
+  "jobId": "job-123",
+  "nodeId": "node-001",
+  "status": "completed",
+  "tool": "bash",
+  "command": "ls -la",
+  "result": {
+    "exitCode": 0,
+    "stdout": "...",
+    "duration": 123
+  }
+}
+```
+
+### Event (SSE)
+```json
+{
+  "type": "status",
+  "category": "tool",
+  "message": "Bash: ls -la",
+  "icon": "🔧"
+}
+```
+
+---
+
+## 🔗 Key APIs
+
+### Control Plane
+
+```
+POST   /api/v1/nodes/register      # Register node
+GET    /api/v1/nodes               # List nodes
+POST   /api/v1/jobs                # Create job
+GET    /api/v1/jobs/:id/stream     # SSE stream
+GET    /api/v1/jobs/:id            # Get result
+DELETE /api/v1/jobs/:id            # Cancel job
+```
+
+### Node Wrapper
+
+```
+GET    /api/v1/health              # Health check
+GET    /api/v1/capabilities        # List tools
+POST   /api/v1/jobs                # Execute job
+GET    /api/v1/jobs/:id/stream     # SSE stream
+```
+
+---
+
+## 🧪 Implementation Status
+
+| Component | Status | Priority |
+|-----------|--------|----------|
+| Control Plane API | 📝 Designed | High |
+| Node Registry | 📝 Designed | High |
+| Job Manager | 📝 Designed | High |
+| SSE Streaming | 📝 Designed | High |
+| nexus-wrapper | 📝 Designed | Medium |
+| Output Parser | 📝 Designed | Medium |
+| Frontend Dashboard | ✅ Bootstrap | Medium |
+| Pipeline Templates | 📝 Designed | Low |
+| WellaNet Integration | 🔮 Future | Low |
+
+**Legend**: ✅ Done | 🔄 In Progress | 📝 Designed | 🔮 Future
+
+---
+
+## 📖 Design Philosophy
+
+### Learned from NexusChat
+
+1. **PTY over Subprocess**: Use `node-pty` for real TTY simulation
+2. **2-Layer Persistence**: RAM cache + disk storage for crash recovery
+3. **SSE for Streaming**: Server-Sent Events for real-time updates
+4. **Output Parser State Machine**: Regex-based parsing with state tracking
+5. **Graceful Shutdown**: Handle SIGTERM, save in-flight jobs
+
+### Generalized for NexusCLI
+
+- **Wrapper abstraction**: Generic interface for any CLI tool
+- **Multi-node orchestration**: Control plane coordinates multiple wrappers
+- **Pipeline thinking**: Every job follows Analysis → Deploy workflow
+- **Event-driven**: All updates flow through SSE event streams
+
+---
+
+## 🔐 Security Considerations
+
+### Authentication
+- JWT tokens for API clients
+- Bearer tokens for node wrappers
+- Rate limiting per user/node
+
+### Authorization
+- RBAC for job execution
+- Tool restrictions per node
+- Command whitelisting/blacklisting
+
+### Isolation
+- Isolated working directories
+- Resource limits (CPU, memory, timeout)
+- No access to wrapper process environment
+
+---
+
+## 📈 Performance Targets
+
+| Metric | Target |
+|--------|--------|
+| Job submission latency | < 100ms |
+| SSE event latency | < 50ms |
+| Concurrent jobs (per node) | 5-10 |
+| Control plane throughput | 100 jobs/sec |
+| Node wrapper memory | < 100MB |
+
+---
+
+## 🚀 Next Steps
+
+### Immediate (Phase 1)
+
+1. Implement Control Plane API endpoints
+2. Create nexus-wrapper reference implementation
+3. Adapt OutputParser for generic CLI tools
+4. Set up systemd services
+
+### Short-term (Phase 2)
+
+1. Add WebSocket support (alternative to SSE)
+2. Implement job scheduling (cron-like)
+3. Create pipeline templates
+4. Add approval workflows
+
+### Long-term (Phase 3)
+
+1. WellaNet integration (compute marketplace)
+2. AI-assisted command validation
+3. Blockchain-based node registry
+4. Multi-cloud orchestration
+
+---
+
+## 📞 Contact & Contribution
+
+**Project Lead**: Davide A. Guglielmi
+**Email**: dev@mmmbuto.com
+**Repository**: `/var/www/cli.wellanet.dev/`
+
+**Based on**:
+- NexusChat wrapper architecture (`/var/www/chat.mmmbuto.com/servers/claude-code-server/`)
+- Production experience with 100+ daily requests
+
+---
+
+_All documentation generated with [Claude Code](https://claude.com/claude-code) (Sonnet 4.5)_