@anastops/cli 1.1.0 → 1.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anastops/cli",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "Infrastructure CLI for Anastops MCP Server setup and diagnostics",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -15,6 +15,7 @@
     }
   },
   "scripts": {
+    "prebuild": "node scripts/copy-ranger.js",
     "build": "tsc",
     "dev": "tsc --watch",
     "start": "node dist/index.js",
@@ -44,7 +45,8 @@
     "typescript": ">=5.0.0"
   },
   "files": [
-    "dist"
+    "dist",
+    "ranger-tui"
   ],
   "keywords": [
     "cli",

package/ranger-tui/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "ranger-tui"
+version = "0.1.0"
+description = "Beautiful terminal UI dashboard for Anastops orchestration"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+    { name = "Anastops Team" }
+]
+keywords = ["tui", "terminal", "dashboard", "orchestration", "textual"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: User Interfaces",
+]
+
+dependencies = [
+    "textual>=0.89.0",
+    "textual-image>=0.6.0",
+    "motor>=3.6.0",
+    "redis>=5.2.0",
+    "pydantic>=2.10.0",
+    "rich>=13.9.0",
+    "nanoid>=2.0.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.24.0",
+    "textual-dev>=1.7.0",
+]
+
+[project.scripts]
+ranger-tui = "ranger_tui.__main__:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ranger_tui"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

package/ranger-tui/ranger_tui/__init__.py

@@ -0,0 +1,5 @@
+"""
+Ranger TUI - Beautiful terminal UI dashboard for Anastops orchestration.
+"""
+
+__version__ = "0.1.0"

package/ranger-tui/ranger_tui/__main__.py

@@ -0,0 +1,16 @@
+"""
+Entry point for ranger-tui.
+"""
+
+import asyncio
+from ranger_tui.app import RangerApp
+
+
+def main() -> None:
+    """Run the Ranger TUI application."""
+    app = RangerApp()
+    app.run()
+
+
+if __name__ == "__main__":
+    main()

package/ranger-tui/ranger_tui/accessibility.py

@@ -0,0 +1,499 @@
+"""
+Accessibility module for ranger-tui - ARIA-like labels and metadata.
+
+This module provides accessibility metadata for terminal UI components,
+enabling screen reader support and semantic structure similar to web ARIA.
+
+The accessibility system includes:
+1. Widget labeling and descriptions
+2. Screen reader announcements
+3. Semantic roles and landmarks
+4. Keyboard shortcut documentation
+5. Form validation feedback
+"""
+
+from dataclasses import dataclass
+from typing import Optional, Dict, List, Any
+from enum import Enum, StrEnum
+
+
+class WidgetRole(StrEnum):
+    """Semantic roles for widgets (ARIA role equivalents)."""
+
+    # Structural roles
+    APPLICATION = "application"
+    DOCUMENT = "document"
+    REGION = "region"
+    NAVIGATION = "navigation"
+    BANNER = "banner"
+    CONTENTINFO = "contentinfo"
+    MAIN = "main"
+    COMPLEMENTARY = "complementary"
+
+    # Table roles
+    TABLE = "table"
+    ROWGROUP = "rowgroup"
+    ROW = "row"
+    COLUMNHEADER = "columnheader"
+    ROWHEADER = "rowheader"
+    CELL = "cell"
+
+    # Form roles
+    FORM = "form"
+    GROUP = "group"
+    TEXTBOX = "textbox"
+    BUTTON = "button"
+    DIALOG = "dialog"
+    COMBOBOX = "combobox"
+
+    # List roles
+    LIST = "list"
+    LISTITEM = "listitem"
+    MENUITEM = "menuitem"
+    TAB = "tab"
+    TABLIST = "tablist"
+    TABPANEL = "tabpanel"
+
+    # Other roles
+    HEADING = "heading"
+    LINK = "link"
+    SEPARATOR = "separator"
+    STATUS = "status"
+    ALERT = "alert"
+    PROGRESSBAR = "progressbar"
+    TREE = "tree"
+    TREEITEM = "treeitem"
+
+
+class StatusIndicator(Enum):
+    """Status indicator meanings with screen reader text."""
+
+    ACTIVE = ("●", "Active")
+    COMPLETED = ("✓", "Completed")
+    ARCHIVED = ("◌", "Archived")
+    PENDING = ("○", "Pending")
+    QUEUED = ("◐", "Queued")
+    RUNNING = ("●", "Running")
+    FAILED = ("✗", "Failed")
+    CANCELLED = ("⊘", "Cancelled")
+    IDLE = ("○", "Idle")
+    WORKING = ("●", "Working")
+    DISCONNECTED = ("○", "Disconnected")
+
+    def get_symbol(self) -> str:
+        """Get the Unicode symbol."""
+        return self.value[0]
+
+    def get_text(self) -> str:
+        """Get the screen reader text."""
+        return self.value[1]
+
+
+@dataclass
+class AccessibilityMetadata:
+    """Accessibility metadata for a widget."""
+
+    role: WidgetRole
+    """The semantic role of the widget (ARIA role equivalent)."""
+
+    label: str
+    """Short label for the widget (e.g., "Sessions Table")."""
+
+    description: Optional[str] = None
+    """Longer description of the widget's purpose."""
+
+    help_text: Optional[str] = None
+    """Additional help or instructions for the widget."""
+
+    keyboard_shortcuts: Optional[Dict[str, str]] = None
+    """Mapping of keyboard shortcuts to their actions (e.g., {"enter": "Open session"})."""
+
+    landmark: Optional[str] = None
+    """Landmark name if this is a significant region (e.g., "main", "navigation")."""
+
+    aria_live: Optional[str] = None
+    """ARIA live region politeness level: "off", "polite", "assertive"."""
+
+    aria_atomic: bool = False
+    """Whether the entire widget should be announced on updates."""
+
+    aria_busy: bool = False
+    """Whether the widget is currently loading or processing."""
+
+    aria_disabled: bool = False
+    """Whether the widget is disabled."""
+
+    aria_hidden: bool = False
+    """Whether the widget should be hidden from screen readers."""
+
+    def to_announcement(self) -> str:
+        """Convert metadata to a screen reader announcement."""
+        parts = [self.label]
+        if self.description:
+            parts.append(self.description)
+        return ". ".join(parts)
+
+
+# Widget-specific accessibility metadata
+
+# Dashboard screen widgets
+DASHBOARD_METADATA: Dict[str, AccessibilityMetadata] = {
+    "sessions-table": AccessibilityMetadata(
+        role=WidgetRole.TABLE,
+        label="Sessions Table",
+        description="List of orchestration sessions with status, objective, task count, token usage, cost, and age",
+        help_text="Navigate with arrow keys or j/k. Press Enter to open a session.",
+        keyboard_shortcuts={
+            "enter": "Open selected session",
+            "n": "Create new session",
+            "a": "Archive selected session",
+            "p": "Purge selected session",
+            "f": "Fork selected session",
+            "↓/j": "Move down",
+            "↑/k": "Move up",
+        },
+        landmark="main",
+        aria_live="polite",
+    ),
+    "topbar": AccessibilityMetadata(
+        role=WidgetRole.BANNER,
+        label="Application Header",
+        description="Displays application logo, environment status, and database connections",
+        landmark="banner",
+    ),
+    "sidebar": AccessibilityMetadata(
+        role=WidgetRole.COMPLEMENTARY,
+        label="Summary Panel",
+        description="Displays statistics and metadata for the selected item",
+        landmark="complementary",
+        aria_live="polite",
+    ),
+}
+
+# Session screen widgets
+SESSION_METADATA: Dict[str, AccessibilityMetadata] = {
+    "session-detail-tabs": AccessibilityMetadata(
+        role=WidgetRole.TABLIST,
+        label="Session Details Tabs",
+        description="View different aspects of the session: Tasks, Agents, and Logs",
+        keyboard_shortcuts={
+            "Tab": "Switch to next tab",
+            "Shift+Tab": "Switch to previous tab",
+            "Enter": "Open selected task",
+        },
+    ),
+    "session-tasks-tab": AccessibilityMetadata(
+        role=WidgetRole.TABPANEL,
+        label="Session Tasks",
+        description="Table of tasks in this session with status, type, description, provider, tokens, and age",
+        help_text="View all tasks associated with this session.",
+    ),
+    "session-agents-tab": AccessibilityMetadata(
+        role=WidgetRole.TABPANEL,
+        label="Session Agents",
+        description="Table of agents working on this session with status, name, role, provider, and performance metrics",
+        help_text="View all agents assigned to this session.",
+    ),
+    "session-logs-tab": AccessibilityMetadata(
+        role=WidgetRole.TABPANEL,
+        label="Session Logs",
+        description="Activity log showing all events and state transitions for this session",
+        help_text="View the complete history of this session.",
+        aria_live="polite",
+    ),
+    "tasks-table": AccessibilityMetadata(
+        role=WidgetRole.TABLE,
+        label="Tasks Table",
+        description="List of tasks with status, ID, type, description, provider, token usage, and creation age",
+        help_text="Navigate with arrow keys or j/k. Press Enter to open a task.",
+        keyboard_shortcuts={
+            "enter": "Open selected task",
+            "t": "Create new task",
+            "e": "Execute or queue task",
+            "c": "Cancel task",
+            "y": "Retry failed task",
+        },
+        aria_live="polite",
+    ),
+    "agents-table": AccessibilityMetadata(
+        role=WidgetRole.TABLE,
+        label="Agents Table",
+        description="List of agents with status, ID, name, role, provider, task counts, and token usage",
+        help_text="Navigate with arrow keys or j/k to view agent details.",
+        aria_live="polite",
+    ),
+}
+
+# Task screen widgets
+TASK_METADATA: Dict[str, AccessibilityMetadata] = {
+    "task-detail-tabs": AccessibilityMetadata(
+        role=WidgetRole.TABLIST,
+        label="Task Details Tabs",
+        description="View different aspects of the task: Output, Input, and Error logs",
+        keyboard_shortcuts={
+            "Tab": "Switch to next tab",
+            "Shift+Tab": "Switch to previous tab",
+        },
+    ),
+    "task-output-tab": AccessibilityMetadata(
+        role=WidgetRole.TABPANEL,
+        label="Task Output",
+        description="Execution output and results from the task",
+        help_text="Read-only output produced by task execution.",
+        aria_live="polite",
+    ),
+    "task-input-tab": AccessibilityMetadata(
+        role=WidgetRole.TABPANEL,
+        label="Task Input",
+        description="Input parameters and context used for task execution",
+        help_text="View the prompt, context files, and other input provided to this task.",
+    ),
+    "task-error-tab": AccessibilityMetadata(
+        role=WidgetRole.TABPANEL,
+        label="Task Error Log",
+        description="Error messages and diagnostic information from task execution",
+        help_text="View any errors or warnings that occurred during task execution.",
+        aria_live="assertive",
+    ),
+}
+
+# Modal widgets
+MODAL_METADATA: Dict[str, AccessibilityMetadata] = {
+    "new-session-modal": AccessibilityMetadata(
+        role=WidgetRole.DIALOG,
+        label="New Session Dialog",
+        description="Create a new orchestration session by specifying its objective",
+        help_text="Enter the objective for your session and click Create or press Escape to cancel.",
+        keyboard_shortcuts={
+            "Enter": "Create session",
+            "Escape": "Cancel and close dialog",
+        },
+    ),
+    "objective-input": AccessibilityMetadata(
+        role=WidgetRole.TEXTBOX,
+        label="Session Objective Input",
+        description="Text field for entering the session objective",
+        help_text="Describe what you want to accomplish with this session",
+    ),
+    "new-task-modal": AccessibilityMetadata(
+        role=WidgetRole.DIALOG,
+        label="New Task Dialog",
+        description="Create a new task within the current session",
+        help_text="Provide task description, detailed prompt, select type, and click Create.",
+        keyboard_shortcuts={
+            "Tab": "Move to next field",
+            "Shift+Tab": "Move to previous field",
+            "Enter": "Create task",
+            "Escape": "Cancel and close dialog",
+        },
+    ),
+    "description-input": AccessibilityMetadata(
+        role=WidgetRole.TEXTBOX,
+        label="Task Description Input",
+        description="Brief description of the task",
+        help_text="Enter a short summary of what this task will do",
+    ),
+    "prompt-input": AccessibilityMetadata(
+        role=WidgetRole.TEXTBOX,
+        label="Task Prompt Input",
+        description="Detailed instructions for the task",
+        help_text="Enter the complete prompt with all details the task needs",
+    ),
+    "type-select": AccessibilityMetadata(
+        role=WidgetRole.COMBOBOX,
+        label="Task Type Selector",
+        description="Choose the type of task: Code, Test, Docs, Analysis, or Other",
+        help_text="Use arrow keys or j/k to select, Enter to confirm",
+        keyboard_shortcuts={
+            "↓/j": "Move to next option",
+            "↑/k": "Move to previous option",
+            "Enter": "Select highlighted option",
+        },
+    ),
+    "help-modal": AccessibilityMetadata(
+        role=WidgetRole.DIALOG,
+        label="Help Dialog",
+        description="Keyboard shortcuts and usage reference for the application",
+        help_text="Navigate with arrow keys or scroll. Press Escape or Enter to close.",
+        keyboard_shortcuts={
+            "Escape": "Close help",
+            "Enter": "Close help",
+            "↓": "Scroll down",
+            "↑": "Scroll up",
+        },
+    ),
+    "command-palette": AccessibilityMetadata(
+        role=WidgetRole.DIALOG,
+        label="Command Palette",
+        description="Quick access to all application commands with search filtering",
+        help_text="Type to filter commands. Use arrow keys to navigate. Press Enter to execute or Escape to close.",
+        keyboard_shortcuts={
+            "Escape": "Close command palette",
+            "Enter": "Execute selected command",
+            "↓": "Select next command",
+            "↑": "Select previous command",
+        },
+    ),
+}
+
+# Global keyboard shortcuts
+GLOBAL_SHORTCUTS: Dict[str, str] = {
+    "q": "Quit application",
+    "?": "Show help and keyboard shortcuts",
+    "r": "Refresh data from database",
+    "d": "Toggle dark/light theme",
+    "Ctrl+P": "Open command palette",
+    "Escape": "Go back or close current modal",
+}
+
+# Table column descriptions (for screen readers)
+TABLE_COLUMNS: Dict[str, Dict[str, str]] = {
+    "sessions-table": {
+        "status": "Session status (Active, Completed, or Archived)",
+        "id": "Unique session identifier",
+        "objective": "What the session is meant to accomplish",
+        "tasks": "Number of completed and total tasks",
+        "tokens": "Total tokens consumed by this session",
+        "cost": "Estimated cost in USD for this session",
+        "age": "How long ago this session was created",
+    },
+    "tasks-table": {
+        "status": "Task status (Pending, Queued, Running, Completed, Failed, or Cancelled)",
+        "id": "Unique task identifier",
+        "type": "Type of task (Code, Test, Docs, Analysis, or Other)",
+        "description": "Brief description of what the task does",
+        "provider": "AI provider executing this task (Claude, Cursor, Gemini, etc.)",
+        "tokens": "Total tokens used by this task",
+        "age": "How long ago this task was created",
+    },
+    "agents-table": {
+        "status": "Agent status (Idle, Working, Completed, or Failed)",
+        "id": "Unique agent identifier",
+        "name": "Name of the agent",
+        "role": "Role of the agent (e.g., orchestrator, planner, implementer)",
+        "provider": "AI provider powering this agent",
+        "tasks": "Number of completed and total tasks assigned to this agent",
+        "tokens": "Total tokens used by this agent",
+    },
+}
+
+# Form validation messages (for accessibility)
+VALIDATION_MESSAGES: Dict[str, str] = {
+    "objective_required": "Session objective is required. Please enter what you want to accomplish.",
+    "objective_empty": "Session objective cannot be empty or only whitespace.",
+    "description_required": "Task description is required. Please provide a brief summary.",
+    "description_empty": "Task description cannot be empty or only whitespace.",
+    "prompt_required": "Task prompt is required. Please provide detailed instructions.",
+    "prompt_empty": "Task prompt cannot be empty or only whitespace.",
+    "both_required": "Both description and prompt are required to create a task.",
+}
+
+
+def get_widget_metadata(widget_id: str) -> Optional[AccessibilityMetadata]:
+    """Get accessibility metadata for a widget."""
+    # Search in all metadata dictionaries
+    for metadata_dict in [
+        DASHBOARD_METADATA,
+        SESSION_METADATA,
+        TASK_METADATA,
+        MODAL_METADATA,
+    ]:
+        if widget_id in metadata_dict:
+            return metadata_dict[widget_id]
+    return None
+
+
+def get_status_text(symbol: str) -> str:
+    """Get screen reader text for a status symbol."""
+    for indicator in StatusIndicator:
+        if indicator.get_symbol() == symbol:
+            return indicator.get_text()
+    return symbol
+
+
+def get_column_description(table_id: str, column_key: str) -> str:
+    """Get description for a table column."""
+    if table_id in TABLE_COLUMNS:
+        return TABLE_COLUMNS[table_id].get(column_key, column_key)
+    return column_key
+
+
+def format_accessibility_announcement(
+    action: str,
+    details: Optional[Dict[str, Any]] = None,
+) -> str:
+    """Format an accessibility announcement for status changes."""
+    announcement = action
+    if details:
+        detail_parts = [f"{k}: {v}" for k, v in details.items()]
+        announcement += ". " + ". ".join(detail_parts)
+    return announcement
+
+
+class AccessibilityHelper:
+    """Helper class for accessibility operations."""
+
+    @staticmethod
+    def announce_table_row(table_id: str, row_data: Dict[str, Any]) -> str:
+        """Generate an announcement for a table row."""
+        if table_id not in TABLE_COLUMNS:
+            return str(row_data)
+
+        columns = TABLE_COLUMNS[table_id]
+        parts = []
+
+        for key, value in row_data.items():
+            description = columns.get(key, key)
+            # Get screen reader text for status indicators
+            if key == "status" and isinstance(value, str):
+                # Extract symbol if present
+                if any(symbol in value for symbol in [s.get_symbol() for s in StatusIndicator]):
+                    parts.append(get_status_text(value.split()[0]))
+                    continue
+            parts.append(f"{description}: {value}")
+
+        return ". ".join(parts)
+
+    @staticmethod
+    def announce_keyboard_help(widget_id: str) -> str:
+        """Generate keyboard help announcement for a widget."""
+        metadata = get_widget_metadata(widget_id)
+        if not metadata or not metadata.keyboard_shortcuts:
+            return ""
+
+        parts = ["Keyboard shortcuts for this widget:"]
+        for key, action in metadata.keyboard_shortcuts.items():
+            parts.append(f"{key}: {action}")
+
+        return ". ".join(parts)
+
+    @staticmethod
+    def validate_form_input(
+        field: str,
+        value: str,
+        required: bool = True,
+    ) -> Optional[str]:
+        """Validate form input and return error message if invalid."""
+        if required and not value.strip():
+            key = f"{field}_empty"
+            return VALIDATION_MESSAGES.get(key, f"{field} is required")
+        return None
+
+
+__all__ = [
+    "AccessibilityMetadata",
+    "WidgetRole",
+    "StatusIndicator",
+    "DASHBOARD_METADATA",
+    "SESSION_METADATA",
+    "TASK_METADATA",
+    "MODAL_METADATA",
+    "GLOBAL_SHORTCUTS",
+    "TABLE_COLUMNS",
+    "VALIDATION_MESSAGES",
+    "get_widget_metadata",
+    "get_status_text",
+    "get_column_description",
+    "format_accessibility_announcement",
+    "AccessibilityHelper",
+]

package/ranger-tui/ranger_tui/actions/__init__.py

@@ -0,0 +1,13 @@
+"""
+Action handlers for Ranger TUI.
+"""
+
+from .session_actions import SessionActions
+from .task_actions import TaskActions
+from .agent_actions import AgentActions
+
+__all__ = [
+    "SessionActions",
+    "TaskActions",
+    "AgentActions",
+]