nexus-tui 0.1.4__py3-none-any.whl → 0.1.5__py3-none-any.whl

nexus/__init__.py

@@ -0,0 +1 @@
+"""Nexus TUI Application package."""

nexus/app.py

@@ -0,0 +1,106 @@
+"""Main application entry point for Nexus.
+
+Configures the Textual application class, global bindings, and initial screen loading.
+"""
+
+from typing import Any
+from textual.app import App
+from textual.notifications import SeverityLevel
+from nexus.container import get_container
+from nexus.screens.tool_selector import ToolSelector
+
+
+class NexusApp(App[None]):
+    """The main Nexus application class.
+
+    Manages the application lifecycle, global bindings, and screen navigation.
+    """
+
+    CSS_PATH = "style.tcss"
+    BINDINGS = [
+        ("ctrl+q", "quit", "Quit"),
+        ("ctrl+c", "quit", "Quit"),
+        ("ctrl+b", "back", "Back"),
+    ]
+
+    def on_mount(self) -> None:
+        """Called when the application is mounted.
+
+        Push the ToolSelector screen to the stack on startup.
+        """
+        # Initialize services
+        self.container = get_container()
+        
+        # Apply keybindings from config
+        self._apply_bindings()
+        
+        self.push_screen(ToolSelector())
+
+    def _apply_bindings(self) -> None:
+        """Applies configurable keybindings."""
+        from nexus.config import get_keybindings
+        bindings = get_keybindings()
+        
+        if "quit" in bindings:
+            self.bind(keys=bindings["quit"], action="quit", description="Quit")
+        if "force_quit" in bindings:
+            self.bind(keys=bindings["force_quit"], action="quit", description="Quit")
+        if "back" in bindings:
+            self.bind(keys=bindings["back"], action="back", description="Back")
+
+    async def action_back(self) -> None:
+        """Navigates back to the previous screen.
+
+        Removes the current screen from the stack if there is more than one
+        screen present.
+        """
+        if len(self.screen_stack) > 1:
+            self.pop_screen()
+
+    def notify(
+        self,
+        message: str,
+        *,
+        title: str = "",
+        severity: SeverityLevel = "information",
+        timeout: float | None = 1.0,
+        **kwargs: Any,
+    ) -> None:
+        """Override notify to use a shorter default timeout.
+
+        Args:
+            message: The message to display.
+            title: The title of the notification.
+            severity: The severity of the notification (e.g., 'information', 'error').
+            timeout: Duration in seconds to show the notification.
+            **kwargs: Additional keyword arguments passed to the parent notify method.
+        """
+        super().notify(
+            message, title=title, severity=severity, timeout=timeout, **kwargs
+        )
+
+    def show_error(self, title: str, message: str, details: str = "") -> None:
+        """Displays a modal error screen.
+
+        Args:
+            title: The title of the error.
+            message: The user-friendly error message.
+            details: Optional technical details.
+        """
+        from nexus.screens.error import ErrorScreen
+
+        self.push_screen(ErrorScreen(title, message, details))
+
+
+def main() -> None:
+    """Entry point for the application."""
+    from nexus.logger import configure_logging
+
+    configure_logging()
+    app = NexusApp()
+    app.run()
+
+
+if __name__ == "__main__":
+    main()
+

nexus/config.py

@@ -0,0 +1,197 @@
+"""Configuration management for the Nexus application.
+
+Handles loading tool definitions from TOML, determining terminal preferences,
+and defining visual assets like colors and icons.
+"""
+
+import os
+import shutil
+import tomllib
+from pathlib import Path
+from typing import Any
+
+import platformdirs
+from nexus.models import Tool
+
+# Configuration Paths in priority order (lowest to highest)
+CWD_NEXUS_CONFIG = Path.cwd() / "nexus" / "tools.local.toml"
+CWD_CONFIG = Path.cwd() / "tools.local.toml"
+USER_CONFIG_PATH = Path(platformdirs.user_config_dir("nexus", roaming=True)) / "tools.toml"
+LOCAL_CONFIG_PATH = Path(__file__).parent / "tools.local.toml"
+DEFAULT_CONFIG_PATH = Path(__file__).parent / "tools.toml"
+
+CONFIG_PATHS = [
+    DEFAULT_CONFIG_PATH,
+    LOCAL_CONFIG_PATH,
+    USER_CONFIG_PATH,
+    CWD_NEXUS_CONFIG,
+    CWD_CONFIG,
+]
+
+
+# Global error tracking for configuration loading
+CONFIG_ERRORS: list[str] = []
+_CONFIG_CACHE: dict[str, Any] | None = None
+
+
+def _load_config_data() -> dict[str, Any]:
+    """Loads and merges configuration data from all sources (Lazy).
+
+    Iterates through configuration paths in priority order and merges meaningful
+    data (tools, project root) into a single dictionary.
+
+    Returns:
+        A dictionary containing the merged configuration data.
+    """
+    global _CONFIG_CACHE
+    if _CONFIG_CACHE is not None:
+        return _CONFIG_CACHE
+
+    merged_data: dict[str, Any] = {"tool": [], "project_root": None}
+
+    def merge_from_file(path: Path) -> None:
+        if path.exists():
+            try:
+                with open(path, "rb") as f:
+                    data = tomllib.load(f)
+
+                    # Replacement strategy: If a config file defines tools,
+                    # it replaces the set of tools from lower-priority configs.
+                    if "tool" in data and data["tool"]:
+                        merged_data["tool"] = data["tool"]
+
+                    if "project_root" in data:
+                        merged_data["project_root"] = data["project_root"]
+
+            except Exception as e:
+                CONFIG_ERRORS.append(f"Error in {path.name}: {e}")
+
+    for path in CONFIG_PATHS:
+        merge_from_file(path)
+
+    _CONFIG_CACHE = merged_data
+    return merged_data
+
+
+def get_project_root() -> Path:
+    """Returns the project root directory.
+
+    Priority:
+    1. NEXUS_PROJECT_ROOT environment variable
+    2. 'project_root' in configuration files
+    3. Default: ~/Projects
+
+    Returns:
+        The defined project root path.
+    """
+    # 1. Environment Variable
+    env_root = os.environ.get("NEXUS_PROJECT_ROOT")
+    if env_root:
+        return Path(env_root).expanduser()
+
+    # 2. Configuration File
+    config = _load_config_data()
+    if config_root := config.get("project_root"):
+        path_str = str(config_root)
+        if path_str.startswith("~"):
+            return Path(path_str).expanduser()
+        return Path(path_str)
+
+    # 3. Default
+    return Path.home() / "Projects"
+
+
+def get_tools() -> list[Tool]:
+    """Returns the list of configured tools.
+
+    Parses the configuration data into Tool models, skipping any invalid entries.
+
+    Returns:
+        A list of Tool objects.
+    """
+    tools = []
+    config = _load_config_data()
+    for t in config.get("tool", []):
+        try:
+            tools.append(Tool(**t))
+        except Exception as e:
+            CONFIG_ERRORS.append(f"Invalid tool definition: {e}")
+            continue
+    return tools
+
+
+def get_keybindings() -> dict[str, str]:
+    """Returns the keybinding configuration.
+
+    Merges default bindings with user overrides from configuration files.
+
+    Returns:
+        A dictionary mapping action names to key sequences.
+    """
+    defaults = {
+        "quit": "q",
+        "force_quit": "ctrl+c",
+        "back": "escape",
+        "theme": "ctrl+t",
+        "help": "?",
+        "fuzzy_search": "ctrl+f",
+        "toggle_favorite": "f",
+    }
+
+    config = _load_config_data()
+    user_bindings = config.get("keybindings", {})
+    
+    # Merge defaults with user bindings
+    return {**defaults, **user_bindings}
+
+
+CATEGORY_COLORS = {
+    "DEV": "blue",
+    "AI": "purple",
+    "MEDIA": "green",
+    "UTIL": "orange",
+}
+
+USE_NERD_FONTS = True
+
+CATEGORY_ICONS = {
+    "DEV": "",  # fh-fa-code_fork
+    "AI": "",  # fh-fa-microchip
+    "MEDIA": "",  # fh-fa-video_camera
+    "UTIL": "",  # fh-fa-wrench
+    "ALL": "",  # fh-fa-list
+}
+
+
+def get_preferred_terminal() -> str | None:
+    """Determines the available terminal emulator based on a priority list.
+
+    Checks `pyproject.toml` for [tool.nexus.priority_terminals] and falls back
+    to a default list if configuration is missing.
+
+    Returns:
+        The command string for the first found terminal, or None if no supported
+        terminal is found.
+    """
+    pyproject_path = Path(__file__).parent.parent / "pyproject.toml"
+
+    terminals = ["kitty", "ghostty", "gnome-terminal", "xterm"]
+
+    if pyproject_path.exists():
+        try:
+            with open(pyproject_path, "rb") as f:
+                data = tomllib.load(f)
+                config_terminals = (
+                    data.get("tool", {}).get("nexus", {}).get("priority_terminals")
+                )
+                if config_terminals:
+                    terminals = config_terminals
+        except Exception:
+            pass
+
+    for term in terminals:
+        path = shutil.which(term)
+        if path:
+            return path
+
+    return None

nexus/container.py

@@ -0,0 +1,45 @@
+"""Dependency Injection Container for Nexus.
+
+Manages the lifecycle and resolution of application services.
+"""
+
+from typing import Any
+from nexus.state import get_state_manager, StateManager
+
+from nexus.services import executor, scanner
+
+
+class Container:
+    """Simple service container."""
+
+    def __init__(self) -> None:
+        """Initialize the container."""
+        # In a more complex app, we might use a proper DI library.
+        # For now, simplistic service location is sufficient.
+        pass
+
+    @property
+    def executor(self) -> Any:
+        """Returns the executor service module."""
+        # Currently the executor is a module with functions.
+        # Future refactor could make it a class.
+        return executor
+
+    @property
+    def scanner(self) -> Any:
+        """Returns the scanner service module."""
+        return scanner
+
+    @property
+    def state_manager(self) -> StateManager:
+        """Returns the state manager service."""
+        return get_state_manager()
+
+
+# Global instance
+_container = Container()
+
+
+def get_container() -> Container:
+    """Returns the global service container."""
+    return _container

nexus/logger.py

@@ -0,0 +1,48 @@
+"""Logging configuration for Nexus.
+
+Configures structlog to write asynchronous logs to a rotating file in the user's
+cache directory, ensuring it does not interfere with the TUI.
+"""
+
+import logging
+
+from pathlib import Path
+from typing import Any
+
+import structlog
+
+# Define log path
+LOG_DIR = Path.home() / ".cache" / "nexus"
+LOG_FILE = LOG_DIR / "nexus.log"
+
+
+def configure_logging() -> None:
+    """Configures structural logging."""
+    if not LOG_DIR.exists():
+        LOG_DIR.mkdir(parents=True, exist_ok=True)
+
+    # Configure standard logging to file
+    logging.basicConfig(
+        filename=str(LOG_FILE),
+        level=logging.INFO,
+        format="%(message)s",
+    )
+
+    structlog.configure(
+        processors=[
+            structlog.contextvars.merge_contextvars,
+            structlog.processors.add_log_level,
+            structlog.processors.StackInfoRenderer(),
+            structlog.processors.format_exc_info,
+            structlog.processors.TimeStamper(fmt="iso"),
+            structlog.processors.JSONRenderer(),
+        ],
+        logger_factory=structlog.stdlib.LoggerFactory(),
+        wrapper_class=structlog.stdlib.BoundLogger,
+        cache_logger_on_first_use=True,
+    )
+
+
+def get_logger(name: str = "nexus") -> Any:
+    """Returns a structured logger instance."""
+    return structlog.get_logger(name)

nexus/models.py

@@ -0,0 +1,43 @@
+"""Data models for the Nexus application.
+
+Defines the Pydantic models used for validation and typehinting of
+tools and projects within the application.
+"""
+
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel
+
+
+class Tool(BaseModel):
+    """Represents a command-line tool available in Nexus.
+
+    Attributes:
+        label: The display name of the tool.
+        category: The category the tool belongs to (DEV, AI, MEDIA, UTIL).
+        description: A brief description of the tool's purpose.
+        command: The shell command to execute.
+        requires_project: True if the tool needs a project directory to run.
+    """
+
+    label: str
+    category: Literal["DEV", "AI", "MEDIA", "UTIL"]
+    description: str
+    command: str
+    requires_project: bool
+
+
+class Project(BaseModel):
+    """Represents a local project directory.
+
+    Attributes:
+        name: The name of the project folder.
+        path: The absolute path to the project directory.
+        is_git: True if the directory is a git repository.
+    """
+
+    name: str
+    path: Path
+    is_git: bool
+

nexus/screens/create_project.py

@@ -0,0 +1,115 @@
+"""Screen for creating a new project.
+
+Collects user input for a new project directory name and creates the directory.
+"""
+
+import os
+from typing import Any, Callable
+
+from nexus.config import get_project_root
+from textual.app import ComposeResult
+from textual.binding import Binding
+from textual.containers import Container, Horizontal
+from textual.screen import ModalScreen
+from textual.widgets import Button, Input, Label
+
+
+class CreateProject(ModalScreen[None]):
+    """A modal screen for creating a new project.
+
+    Attributes:
+        on_created_callback: Callback function called with the new project name upon success.
+    """
+
+    CSS_PATH = "../style.tcss"
+
+    def __init__(self, on_created: Callable[[str], None], **kwargs: Any):
+        """Initializes the CreateProject screen.
+
+        Args:
+            on_created: Callback function (str) -> None.
+            **kwargs: Additional arguments passed to ModalScreen.
+        """
+        super().__init__(**kwargs)
+        self.on_created_callback = on_created
+
+    BINDINGS = [
+        Binding("escape", "cancel", "Cancel"),
+    ]
+
+    def compose(self) -> ComposeResult:
+        """Composes the screen layout.
+
+        Returns:
+            A ComposeResult containing the widget tree.
+        """
+        with Container(id="create-project-dialog"):
+            yield Label("Create New Project", id="create-project-title")
+            yield Input(placeholder="Project Name", id="project-name-input")
+            yield Label("", id="create-error", classes="error-label hidden")
+
+            with Horizontal(id="create-project-buttons"):
+                yield Button("Cancel", variant="default", id="btn-cancel")
+                yield Button("Create", variant="primary", id="btn-create")
+
+    def on_mount(self) -> None:
+        """Called when the screen is mounted."""
+        self.query_one("#project-name-input").focus()
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        """Handles button press events.
+
+        Args:
+            event: The button pressed event.
+        """
+        if event.button.id == "btn-cancel":
+            self.action_cancel()
+        elif event.button.id == "btn-create":
+            self.create_project()
+
+    def on_input_submitted(self, event: Input.Submitted) -> None:
+        """Handles enter key in input field.
+
+        Args:
+            event: The input submitted event.
+        """
+        self.create_project()
+
+    def create_project(self) -> None:
+        """Validates input and attempts to create the project directory."""
+        name_input = self.query_one("#project-name-input", Input)
+        name = name_input.value.strip()
+        if not name:
+            self.show_error("Project name cannot be empty.")
+            return
+
+        project_path = get_project_root() / name
+
+        if project_path.exists():
+            self.show_error("Project already exists.")
+            return
+
+        try:
+            os.makedirs(project_path)
+            self.dismiss()
+            self.on_created_callback(name)
+        except Exception as e:
+            self.show_error(f"Error: {e}")
+
+    def show_error(self, message: str) -> None:
+        """Displays an error message to the user.
+
+        Args:
+            message: The error description.
+        """
+        lbl = self.query_one("#create-error", Label)
+        lbl.update(message)
+        lbl.remove_class("hidden")
+
+    def action_cancel(self) -> None:
+        """Cancels the action and closes the modal."""
+        self.dismiss()
+
+# Summary:
+# Formatted docstrings to strict Google Style.
+# Added module docstring.

nexus/screens/error.py

@@ -0,0 +1,57 @@
+"""Generic Error Screen for Nexus.
+
+Displays an error message and functionality to dismiss or copy details.
+"""
+
+from typing import Any
+
+from textual.app import ComposeResult
+from textual.containers import Container, Horizontal, Vertical
+from textual.screen import ModalScreen
+from textual.widgets import Button, Label, Static
+
+
+class ErrorScreen(ModalScreen[None]):
+    """A modal screen that displays an error message."""
+
+    CSS_PATH = "../style.tcss"
+
+    def __init__(
+        self,
+        title: str,
+        message: str,
+        details: str = "",
+        **kwargs: Any,
+    ):
+        """Initializes the ErrorScreen.
+
+        Args:
+            title: The title of the error.
+            message: The main error message.
+            details: Optional technical details.
+            **kwargs: Additional arguments.
+        """
+        super().__init__(**kwargs)
+        self.error_title = title
+        self.error_message = message
+        self.error_details = details
+
+    def compose(self) -> ComposeResult:
+        """Composes the screen layout."""
+        with Container(id="error-dialog"):
+            with Horizontal(id="error-header"):
+                yield Label("Error", classes="error-icon")
+                yield Label(self.error_title, id="error-title")
+            
+            with Vertical(id="error-body"):
+                yield Label(self.error_message, id="error-message")
+                if self.error_details:
+                    yield Static(self.error_details, id="error-details")
+
+            with Horizontal(id="error-footer"):
+                yield Button("Close", variant="error", id="btn-error-close")
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        """Handles button presses."""
+        if event.button.id == "btn-error-close":
+            self.dismiss()

nexus/screens/help.py

@@ -0,0 +1,62 @@
+"""Help screen for the Nexus application.
+
+Displays information about key bindings and usage.
+"""
+
+from textual.app import ComposeResult
+from textual.containers import Horizontal, Vertical
+from textual.screen import ModalScreen
+from textual.widgets import Button, Label, Markdown
+
+
+class HelpScreen(ModalScreen[None]):
+    """A modal screen that displays help and key bindings."""
+
+    CSS_PATH = "../style.tcss"
+
+    BINDINGS = [
+        ("escape", "dismiss", "Close"),
+        ("q", "dismiss", "Close"),
+    ]
+
+    def compose(self) -> ComposeResult:
+        """Composes the screen layout.
+
+        Returns:
+            A ComposeResult containing the widget tree.
+        """
+        with Vertical(id="help-dialog"):
+            with Horizontal(id="help-title-container"):
+                yield Label("Nexus Help", id="help-title")
+
+            with Vertical(id="help-content"):
+                yield Markdown(
+                    """
+**Navigation**
+- `↑ / ↓` : Navigate lists
+- `← / →` : Switch between Categories and Tool List
+- `Enter` : Select Category or Launch Tool
+
+**Search**
+- Type any character to start searching tools.
+- `Esc` : Clear search or Go Back.
+
+**System**
+- `Ctrl+t` : Open Theme Picker
+- `Ctrl+c` : Quit Application
+- `?` or `F1`: Show this Help Screen
+                    """
+                )
+
+            with Horizontal(id="help-footer"):
+                yield Button("Close", variant="primary", id="btn-close")
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        """Handles button press events.
+
+        Args:
+            event: The button pressed event.
+        """
+        if event.button.id == "btn-close":
+            self.dismiss()
+