@mmmbuto/nexuscli 0.8.9 → 0.9.1

package/lib/server/docs/README.md

@@ -1,272 +0,0 @@
-# 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)_