Transform CLI into interactive TUI application

[Isqanderm]

🎯 Overview

Transform @nexus-ioc/cli from a traditional command-line interface into a modern Terminal User Interface (TUI) application with interactive wizards, code previews, and enhanced user experience.

🎨 Goals

1. Convert the CLI to an interactive TUI with a menu-driven interface
2. Improve user experience with visual feedback, progress indicators, and better navigation
3. Add new features that leverage the interactive nature of TUI
4. Maintain backward compatibility with existing CLI commands for CI/CD usage

📋 Core Features

Interactive Main Menu

• Generate Service
• Generate Module
• Bootstrap Project
• Visualize Dependency Graph
• Install Package
• Exit

Multi-step Wizards

• Service Generation: Name, path, scope, dependencies, module registration, test generation
• Module Generation: Name, path, provider imports
• Bootstrap: Dependency installation, React integration, project structure

Enhanced Capabilities

• Real-time code preview with syntax highlighting
• Input validation at each step
• Confirmation prompts with undo/cancel options
• Dependency discovery and selection
• Dry-run mode to preview changes
• Progress indicators for long-running operations

Dependency Graph Visualization

• Interactive graph viewer in terminal
• Filtering options (by module, by depth)
• Export options (JSON, Mermaid, DOT format)

🏗️ Implementation Plan

Phase 1: Foundation (2-3 days, ~16 hours)

Priority: Critical

• Install dependencies (@clack/prompts, picocolors, cli-highlight)
• Create TUI directory structure (src/tui/)
• Implement main interactive menu
• Add --interactive flag support
• Ensure backward compatibility
• Write basic tests

Deliverables:

• Working main menu
• Backward compatible CLI
• Basic test coverage

Phase 2: Interactive Generate Command (3-4 days, ~30 hours)

Priority: High

• Create service generation wizard
• Create module generation wizard
• Implement input validation utilities
• Add code preview with syntax highlighting
• Add confirmation steps
• Update GenerateAction for TUI inputs
• Comprehensive tests

Deliverables:

• Interactive service wizard
• Interactive module wizard
• Code preview functionality
• Full test coverage

Phase 3: Enhanced Features (3-4 days, ~26 hours)

Priority: Medium

• Create dependency scanner (find existing services)
• Implement scope selection (Singleton/Transient)
• Create module selector/creator
• Build bootstrap wizard
• Add dry-run mode
• Tests for all features

Deliverables:

• Dependency discovery system
• Enhanced wizards with all options
• Bootstrap wizard
• Dry-run mode

Phase 4: Dependency Graph Visualization (2-3 days, ~20 hours)

Priority: Low

• Research terminal graph visualization options
• Implement graph generation
• Add filtering options
• Add export formats (Mermaid, DOT, JSON, HTML)
• Create interactive viewer or export wizard
• Tests

Deliverables:

• Graph visualization
• Multiple export formats
• Interactive filtering

Phase 5: Polish & Testing (2-3 days, ~24 hours)

Priority: High

• Error handling and graceful degradation
• Loading spinners and progress indicators
• Success/error messages with colors
• Undo/cancel functionality
• Comprehensive test suite (unit, integration, E2E)
• Update README with TUI usage examples
• Create screenshots/GIFs
• Create demo video
• Migration guide

Deliverables:

• Polished UX
• Full test coverage
• Updated documentation
• Demo materials

🛠️ Technical Details

Framework Selection

Primary: @clack/prompts

• Modern, beautiful UI
• TypeScript-first
• Lightweight (~50KB)
• Perfect for wizard-style interactions
• Active maintenance

Directory Structure

packages/cli/src/
├── actions/              # Existing action handlers
├── commands/             # Existing command definitions
├── templates/            # Code generation templates
├── tui/                  # NEW: TUI-specific code
│   ├── wizards/         # Multi-step wizards
│   ├── prompts/         # Reusable prompt definitions
│   ├── components/      # Reusable TUI components
│   ├── utils/           # TUI utilities
│   └── main-menu.ts     # Main interactive menu
├── index.ts             # Entry point (updated)
└── commands.helper.ts   # Command registry

Backward Compatibility

# CLI mode (existing) - continues to work
nexus-cli generate service auth ./src

# TUI mode (new)
nexus-cli --interactive
nexus-cli -i
nexus-cli generate --interactive
nexus-cli  # No args = interactive mode

⏱️ Effort Estimation

Phase	Duration	Hours	Priority
Phase 1: Foundation	2-3 days	16h	Critical
Phase 2: Generate Wizards	3-4 days	30h	High
Phase 3: Enhanced Features	3-4 days	26h	Medium
Phase 4: Visualization	2-3 days	20h	Low
Phase 5: Polish & Testing	2-3 days	24h	High
Total	12-17 days	116h

🎬 Implementation Approach

1. Start with MVP (Phases 1-2)
2. Get user feedback
3. Iterate based on feedback
4. Expand with Phases 3-5
5. Polish and document

📚 References

• @clack/prompts Documentation
• cli-highlight
• Current CLI README: packages/cli/README.md

✅ Success Criteria

• All existing CLI commands work without changes
• Interactive mode provides better UX than CLI mode
• Code generation includes preview and confirmation
• Comprehensive test coverage (>80%)
• Documentation updated with examples and screenshots
• No breaking changes to existing API