syntaxis/core/crates/tui

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

cargo build -p syntaxis-tui

Running

First, ensure the REST API server is running:

cargo run -p syntaxis-api

Then, in another terminal, start the TUI:

cargo run -p syntaxis-tui

Or run the compiled binary:

./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)

• Task priority levels (Critical, High, Medium, Low)
• Task type classifications (Feature, BugFix, Documentation, Testing, Deployment, Maintenance)
• 6 flexible sort options (Newest, Oldest, HighestPriority, LowestPriority, CompletedFirst, PendingFirst)
• Task statistics display (Total, Completed, Pending, Completion %)
• Progress bar visualization with Unicode characters
• 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:

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