9cef9b8d57
Merge _configs/ into config/ for single configuration directory. Update all path references. Changes: - Move _configs/* to config/ - Update .gitignore for new patterns - No code references to _configs/ found Impact: -1 root directory (layout_conventions.md compliance)
265 lines
8.2 KiB
Markdown
265 lines
8.2 KiB
Markdown
# Lifecycle Manager - Terminal UI
|
||
|
||
A modern Terminal User Interface (TUI) for managing syntaxis, built with **ratatui** and **crossterm**.
|
||
|
||
## Features
|
||
|
||
### Project Management
|
||
- 📋 **Projects List**: Display all projects with their current phase and version
|
||
- 🔍 **Project Details**: View detailed information about any project
|
||
- 🔒 **Security Assessments**: Monitor security status of projects
|
||
- ⚙️ **Project Creation**: Create new projects directly from the terminal
|
||
- ⌨️ **Vim-style Navigation**: Use hjkl keys or arrow keys to navigate
|
||
|
||
### Task Management ✨
|
||
- ✅ **Task List & Checklist**: View all project tasks and checklists
|
||
- 🔍 **Live Search**: Real-time search by task description or ID
|
||
- 📊 **Statistics Dashboard**: View task completion metrics and progress bar with total, completed, pending counts
|
||
- 🎯 **Flexible Sorting**: 6 sort options (newest, oldest, highest priority, lowest priority, completed first, pending first)
|
||
- 🔴 **Priority Levels**: Critical, High, Medium, Low - with visual indicators
|
||
- 🏷️ **Task Types**: Feature, BugFix, Documentation, Testing, Deployment, Maintenance classifications
|
||
- 🏆 **Completion Tracking**: Toggle task completion with visual feedback
|
||
- 📝 **Task Creation**: Create new tasks with multi-line textarea editor
|
||
- 🎨 **Beautiful UI**: Responsive terminal interface with borders and colors
|
||
- 📈 **Progress Visualization**: Unicode progress bar showing completion percentage
|
||
|
||
## Architecture
|
||
|
||
The TUI is organized into several modules:
|
||
|
||
- **`api.rs`**: HTTP client for communicating with the REST API server
|
||
- **`app.rs`**: Application state management and logic
|
||
- **`events.rs`**: Event handling (keyboard input, ticks)
|
||
- **`terminal.rs`**: Terminal lifecycle management (initialization, cleanup)
|
||
- **`ui.rs`**: UI rendering functions for all screens
|
||
- **`types.rs`**: Data models (DTOs)
|
||
- **`main.rs`**: Application entry point and event loop
|
||
|
||
## Building
|
||
|
||
```bash
|
||
cargo build -p syntaxis-tui
|
||
```
|
||
|
||
## Running
|
||
|
||
First, ensure the REST API server is running:
|
||
|
||
```bash
|
||
cargo run -p syntaxis-api
|
||
```
|
||
|
||
Then, in another terminal, start the TUI:
|
||
|
||
```bash
|
||
cargo run -p syntaxis-tui
|
||
```
|
||
|
||
Or run the compiled binary:
|
||
|
||
```bash
|
||
./target/debug/syntaxis-dashboard
|
||
```
|
||
|
||
## Key Bindings
|
||
|
||
### General
|
||
- **q** or **Esc**: Quit the application
|
||
- **Tab**: Switch between tabs/screens
|
||
|
||
### Projects List Screen
|
||
- **↑ / k**: Navigate up
|
||
- **↓ / j**: Navigate down
|
||
- **Enter**: View project details
|
||
- **c**: Create new project
|
||
- **s**: View security assessments
|
||
|
||
### Project Detail Screen
|
||
- **b**: Go back to projects list
|
||
|
||
### Security Screen
|
||
- **b**: Go back to projects list
|
||
|
||
### Create Project Screen
|
||
- **b**: Cancel and go back
|
||
|
||
### Tasks Screen
|
||
- **↑ / k**: Navigate task list up
|
||
- **↓ / j**: Navigate task list down
|
||
- **Space**: Toggle task completion status
|
||
- **n**: Create new task
|
||
- **/**: Open filter/sort menu
|
||
- **f**: Toggle completion filter (show all / pending only / completed only)
|
||
- **c**: Clear all filters
|
||
- **←/→ or h/l**: Navigate sort options (when filter menu open)
|
||
- **Enter**: Apply selected sort option
|
||
- **b**: Go back to project details
|
||
|
||
## Screens
|
||
|
||
### Projects List
|
||
Displays all projects in a table format showing:
|
||
- Project name
|
||
- Current phase
|
||
- Version
|
||
|
||
### Project Detail
|
||
Shows detailed information about a selected project:
|
||
- ID
|
||
- Name
|
||
- Version
|
||
- Type
|
||
- Current phase
|
||
- Description
|
||
- Creation date
|
||
- Access to tasks, security assessments, and tools management
|
||
|
||
### Tasks Management
|
||
Enhanced task screen with:
|
||
- **Statistics Panel**: Real-time metrics showing total, completed, pending tasks and completion percentage with progress bar
|
||
- **Task List**: Sortable, filterable list of all project tasks
|
||
- **Task Details Panel**: Shows selected task information including:
|
||
- Task ID
|
||
- Description
|
||
- Priority level (Critical, High, Medium, Low)
|
||
- Task type (Feature, BugFix, Documentation, Testing, Deployment, Maintenance)
|
||
- Completion status
|
||
- Creation date
|
||
- **Sorting Options** (6 variants):
|
||
1. Newest First (by creation date, descending)
|
||
2. Oldest First (by creation date, ascending)
|
||
3. Highest Priority (Critical → High → Medium → Low)
|
||
4. Lowest Priority (Low → Medium → High → Critical)
|
||
5. Completed First (completed tasks first)
|
||
6. Pending First (pending tasks first)
|
||
- **Filtering**: Toggle between all tasks / pending only / completed only
|
||
- **Search**: Real-time search by task description or ID
|
||
|
||
### Security Assessments
|
||
Displays security status across projects:
|
||
- Security profile
|
||
- Risk level
|
||
- Passed/failed rules
|
||
- Critical issues
|
||
|
||
### Create Project
|
||
Form for creating a new project with:
|
||
- Project name
|
||
- Description
|
||
- Project type (optional)
|
||
|
||
## API Integration
|
||
|
||
The TUI communicates with the REST API server running on `http://localhost:3000/api`.
|
||
|
||
Available API endpoints:
|
||
- `GET /projects` - List all projects
|
||
- `GET /projects/:id` - Get project details
|
||
- `GET /projects/:id/status` - Get project status
|
||
- `GET /projects/:id/security` - Get security assessment
|
||
- `GET /projects/:id/checklists` - Get checklist items
|
||
- `GET /projects/:id/tools` - Get tools
|
||
- `POST /projects` - Create new project
|
||
|
||
## Data Model
|
||
|
||
### Task Priority
|
||
```
|
||
Critical (🔴) - Highest priority
|
||
High (🟠)
|
||
Medium (🟡) - Default
|
||
Low (🟢) - Lowest priority
|
||
```
|
||
|
||
### Task Type
|
||
```
|
||
Feature (⭐) - New feature implementation
|
||
BugFix (🐛) - Bug fixes and patches
|
||
Documentation (📚) - Documentation and guides
|
||
Testing (✔) - Testing and QA tasks
|
||
Deployment (🚀) - Deployment and release tasks
|
||
Maintenance (🔧) - Maintenance and updates
|
||
```
|
||
|
||
### Statistics Calculation
|
||
The TUI continuously calculates and displays:
|
||
- **Total Tasks**: Complete count of all tasks
|
||
- **Completed Tasks**: Count of tasks marked as completed
|
||
- **Pending Tasks**: Count of tasks still pending
|
||
- **Completion Percentage**: (Completed / Total) × 100
|
||
- **Progress Bar**: Visual representation with Unicode characters (█ filled, ░ empty)
|
||
|
||
## Guidelines
|
||
|
||
The TUI is implemented following these principles:
|
||
|
||
- **No unsafe code**: All code is safe Rust with `#![forbid(unsafe_code)]`
|
||
- **Error handling**: Proper error messages displayed in the UI
|
||
- **Async/await**: All API calls are non-blocking using tokio
|
||
- **Clean architecture**: Separation of concerns (API, UI, state, events)
|
||
- **User experience**: Responsive, intuitive navigation with vim-style keys
|
||
- **Backward compatibility**: Uses `#[serde(default)]` for new fields to work with older API versions
|
||
- **Type-safe filtering**: Enum-based sorting and filtering instead of string comparisons
|
||
|
||
## Feature Parity Status
|
||
|
||
### ✅ Completed (Phase 12)
|
||
- [x] Task priority levels (Critical, High, Medium, Low)
|
||
- [x] Task type classifications (Feature, BugFix, Documentation, Testing, Deployment, Maintenance)
|
||
- [x] 6 flexible sort options (Newest, Oldest, HighestPriority, LowestPriority, CompletedFirst, PendingFirst)
|
||
- [x] Task statistics display (Total, Completed, Pending, Completion %)
|
||
- [x] Progress bar visualization with Unicode characters
|
||
- [x] Feature parity with Dashboard
|
||
|
||
## Future Enhancements
|
||
|
||
- [ ] Display priority/type badges in task list with colors
|
||
- [ ] Filter by priority in TUI
|
||
- [ ] Edit project details
|
||
- [ ] Delete projects
|
||
- [ ] Add new checklist items
|
||
- [ ] Update checklist priority/type
|
||
- [ ] Run security assessments
|
||
- [ ] Enable/disable tools
|
||
- [ ] Phase transitions
|
||
- [ ] Search/filter projects by name
|
||
- [ ] Keyboard shortcuts help overlay (press ? for help)
|
||
- [ ] Color themes (dark/light mode)
|
||
- [ ] Statistics breakdown by priority/type
|
||
- [ ] Task deadlines/due dates with statistics
|
||
- [ ] Milestone tracking
|
||
|
||
## Dependencies
|
||
|
||
- **ratatui 0.25**: Terminal UI framework
|
||
- **crossterm 0.27**: Cross-platform terminal handling
|
||
- **tokio 1.x**: Async runtime
|
||
- **reqwest 0.11**: HTTP client
|
||
- **serde**: Serialization/deserialization
|
||
|
||
## Performance
|
||
|
||
The TUI is designed for performance:
|
||
- Non-blocking event handling
|
||
- Efficient rendering with only changed areas redrawn
|
||
- Connection pooling for API calls
|
||
- Responsive to user input with 250ms tick rate
|
||
|
||
## Testing
|
||
|
||
Run tests with:
|
||
|
||
```bash
|
||
cargo test -p syntaxis-tui
|
||
```
|
||
|
||
## Status
|
||
|
||
✅ **Phase 11 Complete**
|
||
|
||
The TUI application provides a fully functional terminal interface for managing projects with:
|
||
- Complete event handling system
|
||
- All screens implemented
|
||
- Full API integration
|
||
- Production-ready code quality
|