nexus-tui 0.1.14__tar.gz → 0.1.16__tar.gz

nexus_tui-0.1.16/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: nexus-tui
+Version: 0.1.16
+Summary: A TUI orchestrator to manage your installed terminal tools—access everything through a single command
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: platformdirs>=4.0.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: structlog>=24.1.0
+Requires-Dist: textual>=0.86.0
+Requires-Dist: thefuzz>=0.20.0
+Description-Content-Type: text/markdown
+
+# Nexus
+
+Nexus is a terminal dashboard that lets you launch your favorite CLI and TUI tools (like Neovim, Git UIs, or custom scripts) from a single interactive menu. No memorizing commands or directories required.
+
+Think of Nexus as a launcher for terminal tools, similar to how Raycast or Alfred launch GUI apps.
+
+**Source Code**: https://github.com/jdluu/Nexus
+
+![Nexus Logic Demo](https://raw.githubusercontent.com/jdluu/Nexus/main/docs/nexus_demo.png)
+*Caption: Main dashboard showing projects and tools.*
+
+## Prerequisites
+
+*   Python 3.12 or newer.
+*   The [`uv`](https://docs.astral.sh/uv/) package manager.
+*   **Recommended**: A modern terminal emulator with TrueColor support (e.g., [Windows Terminal](https://aka.ms/terminal), [ghostty](https://ghostty.org/), [Kitty](https://sw.kovidgoyal.net/kitty/), or [WezTerm](https://wezfurlong.org/wezterm/)).
+*   **Recommended**: A [Nerd Font](https://www.nerdfonts.com/) for optimal icon rendering.
+
+## Installation
+
+It is recommended to use `uv`, a fast Python package and tool manager (similar to pipx), for a clean, isolated global installation.
+
+```bash
+# Install globally so you can run 'nexus' from anywhere
+uv tool install nexus-tui
+```
+
+**Alternative (Standard pip)**:
+You can also install via pip, though it is recommended `uv` or `pipx` to keep dependencies isolated.
+```bash
+pip install nexus-tui
+```
+
+### Upgrade
+
+To update to the latest version:
+```bash
+uv tool upgrade nexus-tui
+```
+
+### Local Development
+
+For contributors who want to modify the source code:
+
+```bash
+git clone https://github.com/jdluu/Nexus
+cd Nexus
+uv tool install --editable .
+```
+
+## Cross Platform Support
+
+Nexus supports Linux, MacOS, and Windows.
+
+*   **Linux**: Fully supported on standard terminals.
+*   **MacOS**: Fully supported.
+*   **Windows**: Recommended to use PowerShell 7 or Git Bash within Windows Terminal.
+
+*Note: Some tools you launch may behave differently depending on your shell and operating system.*
+
+## Configuration
+
+Nexus utilizes standard configuration paths. You can find your config file at the location listed in the **First Run** section above.
+
+### Minimal Starter Config
+
+Copy this into your `tools.toml` to get started immediately:
+
+```toml
+# Define where your code projects live
+project_root = "~/Projects"
+
+# Add a simple tool to open a shell in the selected project
+[[tool]]
+label = "Shell"
+category = "UTIL"
+description = "Open a shell in the project"
+command = "$SHELL"
+requires_project = true
+```
+
+### Understanding "Projects"
+
+A **Project** is any directory found inside your `project_root`. Nexus scans this folder and lets you select a specific project before launching a tool.
+
+For example, if you select the "Shell" tool above, Nexus will ask you to pick a project (e.g., `~/Projects/MyApp`). It then launches `$SHELL` inside that directory.
+
+### Tool Definitions
+
+Tools are defined using the `[[tool]]` table.
+
+```toml
+[[tool]]
+label = "Neovim"
+category = "DEV"
+description = "Text editor"
+command = "nvim"
+requires_project = true
+```
+
+*   **label**: The display name.
+*   **category**: The grouping identifier (e.g., DEV, UTIL).
+*   **description**: A short explanation of the function.
+*   **command**: The executable command line instruction.
+*   **requires_project**: If `true`, Nexus prompts for a project before running. If `false`, it runs immediately in the current directory.
+
+### Keybindings
+
+Nexus comes with default keybindings (see **Controls** below). You can override them in the `[keybindings]` section of your config.
+
+```toml
+[keybindings]
+# Override default quit to Alt+Q
+quit = "alt+q"
+# Override favorite toggle
+toggle_favorite = "ctrl+f"
+```
+
+## First Run Experience
+
+1.  Run `nexus` from your terminal.
+2.  Nexus creates a default configuration file at:
+    *   **Linux**: `~/.config/nexus/tools.toml`
+    *   **MacOS**: `~/Library/Application Support/Nexus/tools.toml`
+    *   **Windows**: `%LOCALAPPDATA%\Nexus\tools.toml`
+3.  On first launch, you will see an empty dashboard.
+4.  Edit the configuration file (see below) to add your tools and project roots.
+5.  Restart Nexus to see your changes.
+
+### Features
+
+*   **Smart Search**: Instantly find what you need with fuzzy matching, so you don't have to remember exact names.
+*   **Persistence**: Nexus remembers your recent projects and favorite tools, so common workflows are always one keystroke away.
+*   **Favorites**: Pin your most-used tools to the top of the list for quick access.
+
+### Controls
+
+*   **Arrow Keys**: Navigate through lists.
+*   **Enter**: Confirm selection or launch tool.
+*   **Ctrl+F**: Toggle the favorite status of a tool.
+*   **TypeAnywhere**: Instantly filter lists by typing in the search bar.
+*   **Esc**: Reset the search filter.
+*   **Ctrl+B**: Go back (on picker screens).
+*   **Ctrl+C**: Exit the application.
+*   **Ctrl+H**: Show Help / Controls.
+
+## FAQ & Troubleshooting
+
+### Does Nexus discover tools automatically?
+No. You must define your tools in `tools.toml` so you have full control over what appears in your dashboard.
+
+### Is this a replacement for my shell?
+No. Nexus is a dashboard. When you launch a tool, it temporarily suspends itself to let the tool take over your terminal found. When the tool exits, Nexus returns.
+
+### My icons look broken (rectangles or question marks).
+This usually means you aren't using a **Nerd Font**.
+1.  Download a font from [Nerd Fonts](https://www.nerdfonts.com/).
+2.  Install it on your system.
+3.  Configure your terminal emulator to use that font.
+
+### I see a blank screen on launch.
+Check that your `tools.toml` file exists and has at least one valid `[[tool]]` entry. See the **Configuration** section for a minimal example.
+
+## Development (For Contributors)
+
+To configure the development environment:
+
+1.  Synchronize dependencies:
+    ```bash
+    uv sync
+    ```
+
+2.  Run the application locally:
+    ```bash
+    uv run nexus
+    ```
+
+3.  Execute the comprehensive test suite:
+    ```bash
+    uv run pytest --cov=nexus
+    ```
+
+4.  Perform static analysis and type checking:
+    ```bash
+    uv run ruff check .
+    uv run mypy .
+    ```

nexus_tui-0.1.16/README.md

@@ -0,0 +1,187 @@
+# Nexus
+
+Nexus is a terminal dashboard that lets you launch your favorite CLI and TUI tools (like Neovim, Git UIs, or custom scripts) from a single interactive menu. No memorizing commands or directories required.
+
+Think of Nexus as a launcher for terminal tools, similar to how Raycast or Alfred launch GUI apps.
+
+**Source Code**: https://github.com/jdluu/Nexus
+
+![Nexus Logic Demo](https://raw.githubusercontent.com/jdluu/Nexus/main/docs/nexus_demo.png)
+*Caption: Main dashboard showing projects and tools.*
+
+## Prerequisites
+
+*   Python 3.12 or newer.
+*   The [`uv`](https://docs.astral.sh/uv/) package manager.
+*   **Recommended**: A modern terminal emulator with TrueColor support (e.g., [Windows Terminal](https://aka.ms/terminal), [ghostty](https://ghostty.org/), [Kitty](https://sw.kovidgoyal.net/kitty/), or [WezTerm](https://wezfurlong.org/wezterm/)).
+*   **Recommended**: A [Nerd Font](https://www.nerdfonts.com/) for optimal icon rendering.
+
+## Installation
+
+It is recommended to use `uv`, a fast Python package and tool manager (similar to pipx), for a clean, isolated global installation.
+
+```bash
+# Install globally so you can run 'nexus' from anywhere
+uv tool install nexus-tui
+```
+
+**Alternative (Standard pip)**:
+You can also install via pip, though it is recommended `uv` or `pipx` to keep dependencies isolated.
+```bash
+pip install nexus-tui
+```
+
+### Upgrade
+
+To update to the latest version:
+```bash
+uv tool upgrade nexus-tui
+```
+
+### Local Development
+
+For contributors who want to modify the source code:
+
+```bash
+git clone https://github.com/jdluu/Nexus
+cd Nexus
+uv tool install --editable .
+```
+
+## Cross Platform Support
+
+Nexus supports Linux, MacOS, and Windows.
+
+*   **Linux**: Fully supported on standard terminals.
+*   **MacOS**: Fully supported.
+*   **Windows**: Recommended to use PowerShell 7 or Git Bash within Windows Terminal.
+
+*Note: Some tools you launch may behave differently depending on your shell and operating system.*
+
+## Configuration
+
+Nexus utilizes standard configuration paths. You can find your config file at the location listed in the **First Run** section above.
+
+### Minimal Starter Config
+
+Copy this into your `tools.toml` to get started immediately:
+
+```toml
+# Define where your code projects live
+project_root = "~/Projects"
+
+# Add a simple tool to open a shell in the selected project
+[[tool]]
+label = "Shell"
+category = "UTIL"
+description = "Open a shell in the project"
+command = "$SHELL"
+requires_project = true
+```
+
+### Understanding "Projects"
+
+A **Project** is any directory found inside your `project_root`. Nexus scans this folder and lets you select a specific project before launching a tool.
+
+For example, if you select the "Shell" tool above, Nexus will ask you to pick a project (e.g., `~/Projects/MyApp`). It then launches `$SHELL` inside that directory.
+
+### Tool Definitions
+
+Tools are defined using the `[[tool]]` table.
+
+```toml
+[[tool]]
+label = "Neovim"
+category = "DEV"
+description = "Text editor"
+command = "nvim"
+requires_project = true
+```
+
+*   **label**: The display name.
+*   **category**: The grouping identifier (e.g., DEV, UTIL).
+*   **description**: A short explanation of the function.
+*   **command**: The executable command line instruction.
+*   **requires_project**: If `true`, Nexus prompts for a project before running. If `false`, it runs immediately in the current directory.
+
+### Keybindings
+
+Nexus comes with default keybindings (see **Controls** below). You can override them in the `[keybindings]` section of your config.
+
+```toml
+[keybindings]
+# Override default quit to Alt+Q
+quit = "alt+q"
+# Override favorite toggle
+toggle_favorite = "ctrl+f"
+```
+
+## First Run Experience
+
+1.  Run `nexus` from your terminal.
+2.  Nexus creates a default configuration file at:
+    *   **Linux**: `~/.config/nexus/tools.toml`
+    *   **MacOS**: `~/Library/Application Support/Nexus/tools.toml`
+    *   **Windows**: `%LOCALAPPDATA%\Nexus\tools.toml`
+3.  On first launch, you will see an empty dashboard.
+4.  Edit the configuration file (see below) to add your tools and project roots.
+5.  Restart Nexus to see your changes.
+
+### Features
+
+*   **Smart Search**: Instantly find what you need with fuzzy matching, so you don't have to remember exact names.
+*   **Persistence**: Nexus remembers your recent projects and favorite tools, so common workflows are always one keystroke away.
+*   **Favorites**: Pin your most-used tools to the top of the list for quick access.
+
+### Controls
+
+*   **Arrow Keys**: Navigate through lists.
+*   **Enter**: Confirm selection or launch tool.
+*   **Ctrl+F**: Toggle the favorite status of a tool.
+*   **TypeAnywhere**: Instantly filter lists by typing in the search bar.
+*   **Esc**: Reset the search filter.
+*   **Ctrl+B**: Go back (on picker screens).
+*   **Ctrl+C**: Exit the application.
+*   **Ctrl+H**: Show Help / Controls.
+
+## FAQ & Troubleshooting
+
+### Does Nexus discover tools automatically?
+No. You must define your tools in `tools.toml` so you have full control over what appears in your dashboard.
+
+### Is this a replacement for my shell?
+No. Nexus is a dashboard. When you launch a tool, it temporarily suspends itself to let the tool take over your terminal found. When the tool exits, Nexus returns.
+
+### My icons look broken (rectangles or question marks).
+This usually means you aren't using a **Nerd Font**.
+1.  Download a font from [Nerd Fonts](https://www.nerdfonts.com/).
+2.  Install it on your system.
+3.  Configure your terminal emulator to use that font.
+
+### I see a blank screen on launch.
+Check that your `tools.toml` file exists and has at least one valid `[[tool]]` entry. See the **Configuration** section for a minimal example.
+
+## Development (For Contributors)
+
+To configure the development environment:
+
+1.  Synchronize dependencies:
+    ```bash
+    uv sync
+    ```
+
+2.  Run the application locally:
+    ```bash
+    uv run nexus
+    ```
+
+3.  Execute the comprehensive test suite:
+    ```bash
+    uv run pytest --cov=nexus
+    ```
+
+4.  Perform static analysis and type checking:
+    ```bash
+    uv run ruff check .
+    uv run mypy .
+    ```

{nexus_tui-0.1.14 → nexus_tui-0.1.16}/nexus/config.py

@@ -63,8 +63,11 @@ def _load_config_data() -> dict[str, Any]:
                     if "project_root" in data:
                         merged_data["project_root"] = data["project_root"]
 
-            except Exception as e:
+            except (tomllib.TOMLDecodeError, PermissionError) as e:
                 CONFIG_ERRORS.append(f"Error in {path.name}: {e}")
+            except Exception as e:
+                # Catch-all for other unexpected IO errors
+                CONFIG_ERRORS.append(f"Unexpected error reading {path.name}: {e}")
 
     for path in CONFIG_PATHS:
         merge_from_file(path)
@@ -109,11 +112,16 @@ def get_tools() -> list[Tool]:
     Returns:
         A list of Tool objects.
     """
+    from pydantic import ValidationError
+
     tools = []
     config = _load_config_data()
     for t in config.get("tool", []):
         try:
             tools.append(Tool(**t))
+        except ValidationError as e:
+            # Pydantic validation error
+            CONFIG_ERRORS.append(f"Invalid tool definition (Validation): {e}")
         except Exception as e:
             CONFIG_ERRORS.append(f"Invalid tool definition: {e}")
             continue

{nexus_tui-0.1.14 → nexus_tui-0.1.16}/nexus/screens/create_project.py

@@ -109,7 +109,3 @@ class CreateProject(ModalScreen[None]):
     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_tui-0.1.14 → nexus_tui-0.1.16}/nexus/screens/help.py

@@ -41,10 +41,11 @@ class HelpScreen(ModalScreen[None]):
 - 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
+**Actions**
+- `Ctrl+F` : Toggle Favorite
+- `Ctrl+T` : Open Theme Picker
+- `Ctrl+C` : Quit Application
+- `Ctrl+H` or `?` : Show this Help Screen
                     """
                 )
 

{nexus_tui-0.1.14 → nexus_tui-0.1.16}/nexus/screens/project_picker.py

@@ -10,10 +10,11 @@ from nexus.config import get_project_root
 from nexus.models import Project, Tool
 from typing import Any
 from nexus.widgets.tool_list_item import ProjectListItem
+from nexus.widgets.footer import NexusFooter, KeyBadge
 from textual.app import ComposeResult
 from textual.containers import Container
 from textual.screen import Screen
-from textual.widgets import Footer, Header, Input, Label, ListItem, ListView, LoadingIndicator
+from textual.widgets import Header, Input, Label, ListItem, ListView, LoadingIndicator
 from thefuzz import process
 
 
@@ -43,6 +44,8 @@ class ProjectPicker(Screen[None]):
         ("down", "cursor_down", "Next Item"),
         ("up", "cursor_up", "Previous Item"),
         ("enter", "select_current", "Select"),
+        ("ctrl+b", "back", "Back"),
+        ("ctrl+c", "quit", "Quit"),
     ]
 
     def compose(self) -> ComposeResult:
@@ -63,7 +66,11 @@ class ProjectPicker(Screen[None]):
             yield Label(
                 "No projects found", id="projects-empty", classes="empty-state hidden"
             )
-        yield Footer()
+        yield NexusFooter(key_defs=[
+            ("Enter", "Select", "select_current"),
+            ("Ctrl+B", "Back", "back"),
+            ("Ctrl+C", "Quit", "quit"),
+        ])
 
     async def on_mount(self) -> None:
         """Called when the screen is mounted.
@@ -247,4 +254,18 @@ class ProjectPicker(Screen[None]):
         """Selects the currently highlighted item."""
         project_list = self.query_one("#project-list", ListView)
         if project_list.index is not None:
-            self._select_item(project_list.children[project_list.index])
+            self._select_item(project_list.children[project_list.index])
+            
+    def action_back(self) -> None:
+        """Go back to the previous screen."""
+        self.app.pop_screen()
+            
+    def on_key_badge_pressed(self, message: KeyBadge.Pressed) -> None:
+        """Handle footer clicks."""
+        action = message.action
+        if action == "select_current":
+            self.action_select_current()
+        elif action == "back":
+            self.action_back()
+        elif action == "quit":
+            self.app.exit()