shotgun-sh 0.2.3.dev2__py3-none-any.whl → 0.2.11.dev1__py3-none-any.whl

shotgun/tui/state/processing_state.py

@@ -0,0 +1,185 @@
+"""Processing state management for TUI operations.
+
+This module provides centralized management of processing state including:
+- Tracking whether operations are in progress
+- Managing worker references for cancellation
+- Coordinating spinner widget updates
+- Providing clean cancellation API
+"""
+
+from typing import TYPE_CHECKING, Any
+
+from shotgun.logging_config import get_logger
+from shotgun.posthog_telemetry import track_event
+
+if TYPE_CHECKING:
+    from textual.screen import Screen
+    from textual.worker import Worker
+
+    from shotgun.tui.components.spinner import Spinner
+
+logger = get_logger(__name__)
+
+
+class ProcessingStateManager:
+    """Manages processing state and spinner coordination for async operations.
+
+    This class centralizes the logic for tracking whether the TUI is processing
+    an operation, managing the current worker for cancellation, and updating
+    spinner text.
+
+    Example:
+        ```python
+        # In ChatScreen
+        self.processing_state = ProcessingStateManager(self)
+
+        # Start processing
+        @work
+        async def some_operation(self) -> None:
+            self.processing_state.start_processing("Doing work...")
+            self.processing_state.bind_worker(get_current_worker())
+            try:
+                # ... do work ...
+            finally:
+                self.processing_state.stop_processing()
+        ```
+    """
+
+    def __init__(
+        self, screen: "Screen[Any]", telemetry_context: dict[str, Any] | None = None
+    ) -> None:
+        """Initialize the processing state manager.
+
+        Args:
+            screen: The Textual screen this manager is attached to
+            telemetry_context: Optional context to include in telemetry events
+                (e.g., {"agent_mode": "research"})
+        """
+        self.screen = screen
+        self._working = False
+        self._current_worker: Worker[Any] | None = None
+        self._spinner_widget: Spinner | None = None
+        self._default_spinner_text = "Processing..."
+        self._telemetry_context = telemetry_context or {}
+
+    @property
+    def is_working(self) -> bool:
+        """Check if an operation is currently in progress.
+
+        Returns:
+            True if processing, False if idle
+        """
+        return self._working
+
+    def bind_spinner(self, spinner: "Spinner") -> None:
+        """Bind a spinner widget for state coordination.
+
+        Should be called during screen mount after the spinner widget is available.
+
+        Args:
+            spinner: The Spinner widget to coordinate with
+        """
+        self._spinner_widget = spinner
+        logger.debug(f"Spinner widget bound: {spinner}")
+
+    def start_processing(self, spinner_text: str | None = None) -> None:
+        """Start processing state with optional custom spinner text.
+
+        Args:
+            spinner_text: Custom text to display in spinner. If None, uses default.
+        """
+        if self._working:
+            logger.warning("Attempted to start processing while already processing")
+            return
+
+        self._working = True
+        text = spinner_text or self._default_spinner_text
+
+        # Update screen's reactive working state
+        if hasattr(self.screen, "working"):
+            self.screen.working = True
+
+        if self._spinner_widget:
+            self._spinner_widget.text = text
+            logger.debug(f"Processing started with spinner text: {text}")
+        else:
+            logger.warning("Processing started but no spinner widget bound")
+
+    def stop_processing(self) -> None:
+        """Stop processing state and reset to default."""
+        if not self._working:
+            logger.debug("stop_processing called when not working (no-op)")
+            return
+
+        self._working = False
+        self._current_worker = None
+
+        # Update screen's reactive working state
+        if hasattr(self.screen, "working"):
+            self.screen.working = False
+
+        # Reset spinner to default text
+        if self._spinner_widget:
+            self._spinner_widget.text = self._default_spinner_text
+            logger.debug("Processing stopped, spinner reset to default")
+
+    def bind_worker(self, worker: "Worker[Any]") -> None:
+        """Bind a worker for cancellation tracking.
+
+        Should be called immediately after starting a @work decorated method
+        using get_current_worker().
+
+        Args:
+            worker: The Worker instance to track for cancellation
+        """
+        self._current_worker = worker
+        logger.debug(f"Worker bound: {worker}")
+
+    def cancel_current_operation(self, cancel_key: str | None = None) -> bool:
+        """Attempt to cancel the current operation if one is running.
+
+        Automatically tracks cancellation telemetry with context from initialization.
+
+        Args:
+            cancel_key: Optional key that triggered cancellation (e.g., "Escape")
+
+        Returns:
+            True if an operation was cancelled, False if no operation was running
+        """
+        if not self._working or not self._current_worker:
+            logger.debug("No operation to cancel")
+            return False
+
+        try:
+            self._current_worker.cancel()
+            logger.info("Operation cancelled successfully")
+
+            # Track cancellation event with context
+            event_data = {**self._telemetry_context}
+            if cancel_key:
+                event_data["cancel_key"] = cancel_key
+
+            track_event("agent_cancelled", event_data)
+
+            return True
+        except Exception as e:
+            logger.error(f"Failed to cancel operation: {e}", exc_info=True)
+            return False
+
+    def update_spinner_text(self, text: str) -> None:
+        """Update spinner text during processing.
+
+        Args:
+            text: New text to display in spinner
+        """
+        if not self._working:
+            logger.warning(
+                f"Attempted to update spinner text while not working: {text}"
+            )
+            return
+
+        if self._spinner_widget:
+            self._spinner_widget.text = text
+            logger.debug(f"Spinner text updated to: {text}")
+        else:
+            logger.warning(f"Cannot update spinner text, widget not bound: {text}")

shotgun/tui/widgets/__init__.py

@@ -0,0 +1,5 @@
+"""Widget utilities and coordinators for TUI."""
+
+from shotgun.tui.widgets.widget_coordinator import WidgetCoordinator
+
+__all__ = ["WidgetCoordinator"]

shotgun/tui/widgets/widget_coordinator.py

@@ -0,0 +1,247 @@
+# mypy: disable-error-code="import-not-found"
+"""Widget coordinator to centralize widget queries and updates.
+
+This module eliminates scattered `query_one()` calls throughout ChatScreen
+by providing a single place for all widget updates. This improves:
+- Testability (can test update logic in isolation)
+- Maintainability (clear update contracts)
+- Performance (can batch updates if needed)
+"""
+
+import logging
+from typing import TYPE_CHECKING
+
+from pydantic_ai.messages import ModelMessage
+
+from shotgun.agents.config.models import ModelName
+from shotgun.agents.models import AgentType
+from shotgun.tui.components.context_indicator import ContextIndicator
+from shotgun.tui.components.mode_indicator import ModeIndicator
+from shotgun.tui.components.prompt_input import PromptInput
+from shotgun.tui.components.spinner import Spinner
+from shotgun.tui.components.status_bar import StatusBar
+from shotgun.tui.screens.chat_screen.history.chat_history import ChatHistory
+
+if TYPE_CHECKING:
+    from shotgun.agents.context_analyzer.models import ContextAnalysis
+    from shotgun.agents.conversation_history import HintMessage
+    from shotgun.tui.screens.chat import ChatScreen
+
+logger = logging.getLogger(__name__)
+
+
+class WidgetCoordinator:
+    """Coordinates updates to all widgets in ChatScreen.
+
+    This class centralizes all `query_one()` calls and widget manipulations,
+    providing clear update methods instead of scattered direct queries.
+
+    Benefits:
+    - Single place for all widget updates
+    - Testable without full TUI
+    - Clear update contracts
+    - Can add batching/debouncing easily
+    """
+
+    def __init__(self, screen: "ChatScreen"):
+        """Initialize the coordinator with a reference to the screen.
+
+        Args:
+            screen: The ChatScreen instance containing the widgets.
+        """
+        self.screen = screen
+
+    def update_for_mode_change(
+        self, new_mode: AgentType, placeholder: str | None = None
+    ) -> None:
+        """Update all widgets when agent mode changes.
+
+        Args:
+            new_mode: The new agent mode.
+            placeholder: Optional placeholder text for input. If not provided,
+                        will use the screen's _placeholder_for_mode method.
+        """
+        if not self.screen.is_mounted:
+            return
+
+        # Update mode indicator
+        try:
+            mode_indicator = self.screen.query_one(ModeIndicator)
+            mode_indicator.mode = new_mode
+            mode_indicator.refresh()
+        except Exception as e:
+            logger.exception(f"Failed to update mode indicator: {e}")
+
+        # Update prompt input placeholder
+        try:
+            prompt_input = self.screen.query_one(PromptInput)
+            if placeholder is None:
+                placeholder = self.screen._placeholder_for_mode(
+                    new_mode, force_new=True
+                )
+            prompt_input.placeholder = placeholder
+            prompt_input.refresh()
+        except Exception as e:
+            logger.exception(f"Failed to update prompt input: {e}")
+
+    def update_for_processing_state(
+        self, is_processing: bool, spinner_text: str | None = None
+    ) -> None:
+        """Update widgets when processing state changes.
+
+        Args:
+            is_processing: Whether processing is active.
+            spinner_text: Optional text to display in spinner.
+        """
+        if not self.screen.is_mounted:
+            return
+
+        # Update spinner visibility
+        try:
+            spinner = self.screen.query_one("#spinner", Spinner)
+            spinner.set_classes("" if is_processing else "hidden")
+            spinner.display = is_processing
+            if spinner_text and is_processing:
+                spinner.text = spinner_text
+        except Exception as e:
+            logger.exception(f"Failed to update spinner: {e}")
+
+        # Update status bar
+        try:
+            status_bar = self.screen.query_one(StatusBar)
+            status_bar.working = is_processing
+            status_bar.refresh()
+        except Exception as e:
+            logger.exception(f"Failed to update status bar: {e}")
+
+    def update_for_qa_mode(self, qa_mode_active: bool) -> None:
+        """Update widgets when Q&A mode changes.
+
+        Args:
+            qa_mode_active: Whether Q&A mode is active.
+        """
+        if not self.screen.is_mounted:
+            return
+
+        # Update status bar
+        try:
+            status_bar = self.screen.query_one(StatusBar)
+            status_bar.refresh()
+        except Exception as e:
+            logger.exception(f"Failed to update status bar for Q&A: {e}")
+
+        # Update mode indicator
+        try:
+            mode_indicator = self.screen.query_one(ModeIndicator)
+            mode_indicator.refresh()
+        except Exception as e:
+            logger.exception(f"Failed to update mode indicator for Q&A: {e}")
+
+    def update_messages(self, messages: list[ModelMessage | "HintMessage"]) -> None:
+        """Update chat history with new messages.
+
+        Args:
+            messages: The messages to display.
+        """
+        if not self.screen.is_mounted:
+            return
+
+        try:
+            chat_history = self.screen.query_one(ChatHistory)
+            chat_history.update_messages(messages)
+        except Exception as e:
+            logger.exception(f"Failed to update messages: {e}")
+
+    def set_partial_response(
+        self, message: ModelMessage | None, messages: list[ModelMessage | "HintMessage"]
+    ) -> None:
+        """Update chat history with partial streaming response.
+
+        Args:
+            message: The partial message being streamed.
+            messages: The full message history.
+        """
+        if not self.screen.is_mounted:
+            return
+
+        try:
+            chat_history = self.screen.query_one(ChatHistory)
+            if message:
+                chat_history.partial_response = message
+            chat_history.update_messages(messages)
+        except Exception as e:
+            logger.exception(f"Failed to set partial response: {e}")
+
+    def update_context_indicator(
+        self, analysis: "ContextAnalysis | None", model_name: str
+    ) -> None:
+        """Update context indicator with new analysis.
+
+        Args:
+            analysis: The context analysis results.
+            model_name: The current model name.
+        """
+        if not self.screen.is_mounted:
+            return
+
+        try:
+            context_indicator = self.screen.query_one(ContextIndicator)
+            # Cast the string model name to ModelName type
+            model = ModelName(model_name) if model_name else None
+            context_indicator.update_context(analysis, model)
+        except Exception as e:
+            logger.exception(f"Failed to update context indicator: {e}")
+
+    def update_prompt_input(
+        self,
+        placeholder: str | None = None,
+        clear: bool = False,
+        focus: bool = False,
+    ) -> None:
+        """Update prompt input widget.
+
+        Args:
+            placeholder: New placeholder text.
+            clear: Whether to clear the input.
+            focus: Whether to focus the input.
+        """
+        if not self.screen.is_mounted:
+            return
+
+        try:
+            prompt_input = self.screen.query_one(PromptInput)
+            if placeholder is not None:
+                prompt_input.placeholder = placeholder
+            if clear:
+                prompt_input.clear()
+            if focus:
+                prompt_input.focus()
+        except Exception as e:
+            logger.exception(f"Failed to update prompt input: {e}")
+
+    def refresh_mode_indicator(self) -> None:
+        """Refresh mode indicator without changing mode."""
+        if not self.screen.is_mounted:
+            return
+
+        try:
+            mode_indicator = self.screen.query_one(ModeIndicator)
+            mode_indicator.refresh()
+        except Exception as e:
+            logger.exception(f"Failed to refresh mode indicator: {e}")
+
+    def update_spinner_text(self, text: str) -> None:
+        """Update spinner text without changing visibility.
+
+        Args:
+            text: The new spinner text.
+        """
+        if not self.screen.is_mounted:
+            return
+
+        try:
+            spinner = self.screen.query_one("#spinner", Spinner)
+            if spinner.display:  # Only update if visible
+                spinner.text = text
+        except Exception as e:
+            logger.exception(f"Failed to update spinner text: {e}")

shotgun/utils/datetime_utils.py

@@ -0,0 +1,77 @@
+"""Datetime utilities for consistent datetime formatting across the application."""
+
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+
+class DateTimeContext(BaseModel):
+    """Structured datetime context with timezone information.
+
+    This model provides consistently formatted datetime information
+    for use in prompts, templates, and UI display.
+
+    Attributes:
+        datetime_formatted: Human-readable datetime string
+        timezone_name: Short timezone name (e.g., "PST", "UTC")
+        utc_offset: UTC offset formatted with colon (e.g., "UTC-08:00")
+
+    Example:
+        >>> dt_context = get_datetime_context()
+        >>> print(dt_context.datetime_formatted)
+        'Monday, January 13, 2025 at 3:45:30 PM'
+        >>> print(dt_context.timezone_name)
+        'PST'
+        >>> print(dt_context.utc_offset)
+        'UTC-08:00'
+    """
+
+    datetime_formatted: str = Field(
+        description="Human-readable datetime string in format: 'Day, Month DD, YYYY at HH:MM:SS AM/PM'"
+    )
+    timezone_name: str = Field(description="Short timezone name (e.g., PST, EST, UTC)")
+    utc_offset: str = Field(
+        description="UTC offset formatted with colon (e.g., UTC-08:00, UTC+05:30)"
+    )
+
+
+def get_datetime_context() -> DateTimeContext:
+    """Get formatted datetime context with timezone information.
+
+    Returns a Pydantic model containing consistently formatted datetime
+    information suitable for use in prompts and templates.
+
+    Returns:
+        DateTimeContext: Structured datetime context with formatted strings
+
+    Example:
+        >>> dt_context = get_datetime_context()
+        >>> dt_context.datetime_formatted
+        'Monday, January 13, 2025 at 3:45:30 PM'
+        >>> dt_context.timezone_name
+        'PST'
+        >>> dt_context.utc_offset
+        'UTC-08:00'
+    """
+    # Get current datetime with timezone information
+    now = datetime.now().astimezone()
+
+    # Format datetime in plain English
+    # Example: "Monday, January 13, 2025 at 3:45:30 PM"
+    datetime_formatted = now.strftime("%A, %B %d, %Y at %I:%M:%S %p")
+
+    # Get timezone name and UTC offset
+    # Example: "PST" and "UTC-08:00"
+    timezone_name = now.strftime("%Z")
+    utc_offset = now.strftime("%z")  # Format: +0800 or -0500
+
+    # Reformat UTC offset to include colon: +08:00 or -05:00
+    utc_offset_formatted = (
+        f"UTC{utc_offset[:3]}:{utc_offset[3:]}" if utc_offset else "UTC"
+    )
+
+    return DateTimeContext(
+        datetime_formatted=datetime_formatted,
+        timezone_name=timezone_name,
+        utc_offset=utc_offset_formatted,
+    )

shotgun/utils/file_system_utils.py

@@ -1,8 +1,9 @@
 """File system utility functions."""
 
-import os
 from pathlib import Path
 
+from shotgun.settings import settings
+
 
 def get_shotgun_base_path() -> Path:
     """Get the absolute path to the .shotgun directory."""
@@ -18,7 +19,7 @@ def get_shotgun_home() -> Path:
         Path to shotgun home directory (default: ~/.shotgun-sh/)
     """
     # Allow override via environment variable (useful for testing)
-    if custom_home := os.environ.get("SHOTGUN_HOME"):
+    if custom_home := settings.dev.home:
         return Path(custom_home)
 
     return Path.home() / ".shotgun-sh"

shotgun/utils/update_checker.py

@@ -10,6 +10,7 @@ from packaging import version
 
 from shotgun import __version__
 from shotgun.logging_config import get_logger
+from shotgun.settings import settings
 
 logger = get_logger(__name__)
 
@@ -18,8 +19,34 @@ def detect_installation_method() -> str:
     """Detect how shotgun-sh was installed.
 
     Returns:
-        Installation method: 'pipx', 'pip', 'venv', or 'unknown'.
+        Installation method: 'uvx', 'uv-tool', 'pipx', 'pip', 'venv', or 'unknown'.
     """
+    # Check for simulation environment variable (for testing)
+    if settings.dev.pipx_simulate:
+        logger.debug("SHOTGUN_PIPX_SIMULATE enabled, simulating pipx installation")
+        return "pipx"
+
+    # Check for uvx (ephemeral execution) by looking at executable path
+    # uvx runs from a temporary cache directory
+    executable = Path(sys.executable)
+    if ".cache/uv" in str(executable) or "uv/cache" in str(executable):
+        logger.debug("Detected uvx (ephemeral) execution")
+        return "uvx"
+
+    # Check for uv tool installation
+    try:
+        result = subprocess.run(
+            ["uv", "tool", "list"],  # noqa: S607, S603
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode == 0 and "shotgun-sh" in result.stdout:
+            logger.debug("Detected uv tool installation")
+            return "uv-tool"
+    except (subprocess.SubprocessError, FileNotFoundError):
+        pass
+
     # Check for pipx installation
     try:
         result = subprocess.run(
@@ -59,7 +86,7 @@ def detect_installation_method() -> str:
 
 
 def perform_auto_update(no_update_check: bool = False) -> None:
-    """Perform automatic update if installed via pipx.
+    """Perform automatic update if installed via pipx or uv tool.
 
     Args:
         no_update_check: If True, skip the update.
@@ -68,23 +95,40 @@ def perform_auto_update(no_update_check: bool = False) -> None:
         return
 
     try:
-        # Only auto-update for pipx installations
-        if detect_installation_method() != "pipx":
-            logger.debug("Not a pipx installation, skipping auto-update")
+        method = detect_installation_method()
+
+        # Skip auto-update for ephemeral uvx executions
+        if method == "uvx":
+            logger.debug("uvx (ephemeral) execution, skipping auto-update")
             return
 
-        # Run pipx upgrade quietly
-        logger.debug("Running pipx upgrade shotgun-sh --quiet")
-        result = subprocess.run(
-            ["pipx", "upgrade", "shotgun-sh", "--quiet"],  # noqa: S607, S603
+        # Only auto-update for pipx and uv-tool installations
+        if method not in ["pipx", "uv-tool"]:
+            logger.debug(f"Installation method '{method}', skipping auto-update")
+            return
+
+        # Determine the appropriate upgrade command
+        if method == "pipx":
+            command = ["pipx", "upgrade", "shotgun-sh", "--quiet"]
+            logger.debug("Running pipx upgrade shotgun-sh --quiet")
+        elif method == "uv-tool":
+            command = ["uv", "tool", "upgrade", "shotgun-sh"]
+            logger.debug("Running uv tool upgrade shotgun-sh")
+        else:
+            return
+
+        # Run upgrade command
+        result = subprocess.run(  # noqa: S603, S607
+            command,
             capture_output=True,
             text=True,
             timeout=30,
         )
 
         if result.returncode == 0:
-            # Check if there was an actual update (pipx shows output even with --quiet for actual updates)
-            if result.stdout and "upgraded" in result.stdout.lower():
+            # Check if there was an actual update
+            output = result.stdout.lower()
+            if "upgraded" in output or "updated" in output:
                 logger.info("Shotgun-sh has been updated to the latest version")
         else:
             # Only log errors at debug level to not annoy users
@@ -166,16 +210,18 @@ def compare_versions(current: str, latest: str) -> bool:
         return False
 
 
-def get_update_command(method: str) -> list[str]:
+def get_update_command(method: str) -> list[str] | None:
     """Get the appropriate update command based on installation method.
 
     Args:
-        method: Installation method ('pipx', 'pip', 'venv', or 'unknown').
+        method: Installation method ('uvx', 'uv-tool', 'pipx', 'pip', 'venv', or 'unknown').
 
     Returns:
-        Command list to execute for updating.
+        Command list to execute for updating, or None for uvx (ephemeral).
     """
     commands = {
+        "uvx": None,  # uvx is ephemeral, no update command
+        "uv-tool": ["uv", "tool", "upgrade", "shotgun-sh"],
         "pipx": ["pipx", "upgrade", "shotgun-sh"],
         "pip": [sys.executable, "-m", "pip", "install", "--upgrade", "shotgun-sh"],
         "venv": [sys.executable, "-m", "pip", "install", "--upgrade", "shotgun-sh"],
@@ -210,6 +256,15 @@ def perform_update(force: bool = False) -> tuple[bool, str]:
     method = detect_installation_method()
     command = get_update_command(method)
 
+    # Handle uvx (ephemeral) installations
+    if method == "uvx" or command is None:
+        return (
+            False,
+            "You're running shotgun-sh via uvx (ephemeral mode). "
+            "To get the latest version, simply run 'uvx shotgun-sh' again, "
+            "or install permanently with 'uv tool install shotgun-sh'.",
+        )
+
     # Perform update
     try:
         logger.info(f"Updating shotgun-sh using {method}...")