syntaxis/core/crates/tui/README.md

# 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