ralph-code 0.5.0__py3-none-any.whl

ralph/spinner.py

@@ -0,0 +1,287 @@
+"""Rich-based spinner utility module for ralph-coding.
+
+This module provides spinner functionality using Rich's rendering system,
+allowing spinners to be embedded in Live displays and panels.
+
+The module provides:
+- Multiple braille spinner styles including 6-dot rotating pattern
+- Integration with Rich's Live display system
+- Nord theme color support
+- Thread-safe operation for background spinning
+
+Usage Example:
+    from ralph.spinner import RichSpinner, SpinnerStyle
+    from rich.live import Live
+    from rich.panel import Panel
+
+    # Create spinner for use in Live display
+    spinner = RichSpinner("Processing...", style=SpinnerStyle.DOTS_6)
+
+    with Live(Panel(spinner), refresh_per_second=10) as live:
+        while working:
+            live.update(Panel(spinner))  # Spinner auto-advances
+
+    # Or use standalone with context manager
+    with RichSpinner("Loading...") as spinner:
+        do_work()
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Iterator
+
+from rich.console import Console, ConsoleOptions, RenderResult
+from rich.live import Live
+from rich.style import Style
+from rich.text import Text
+
+from ralph.colors import FROST_CYAN, FG_PRIMARY
+
+
+class SpinnerStyle(Enum):
+    """Available spinner animation styles using braille patterns.
+
+    DOTS_6: Six dots rotating around the braille cell (2x3 pattern)
+    DOTS_8: Eight dots rotating around the full braille cell (2x4 pattern)
+    DOTS_BOUNCE: Dots bouncing left-right pattern
+    DOTS_GROW: Dots growing/shrinking pattern
+    CLASSIC: Traditional |/-\\ spinner
+    """
+
+    # Six dots rotating around the 2x3 braille cell
+    # Pattern: top-left -> mid-left -> bot-left -> top-right -> mid-right -> bot-right
+    DOTS_6 = ("⠁", "⠂", "⠄", "⠈", "⠐", "⠠")
+
+    # Eight dots rotating around full 2x4 braille cell
+    DOTS_8 = ("⣾", "⣽", "⣻", "⢿", "⡿", "⣟", "⣯", "⣷")
+
+    # Classic braille dots pattern (10 frames)
+    DOTS = ("⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏")
+
+    # Dots bouncing
+    DOTS_BOUNCE = ("⠁", "⠂", "⠄", "⠂")
+
+    # Growing dots
+    DOTS_GROW = ("⠀", "⠁", "⠃", "⠇", "⠏", "⠟", "⠿", "⠟", "⠏", "⠇", "⠃", "⠁")
+
+    # Classic ASCII spinner
+    CLASSIC = ("|", "/", "-", "\\")
+
+    # Circle quadrants
+    CIRCLE = ("◴", "◷", "◶", "◵")
+
+    # Half circles
+    HALF_CIRCLE = ("◐", "◓", "◑", "◒")
+
+
+@dataclass
+class RichSpinner:
+    """A Rich-compatible spinner that can be rendered in Live displays.
+
+    This spinner implements Rich's console protocol, allowing it to be
+    used directly in Rich's rendering system including Live, Panel, etc.
+
+    The spinner automatically advances frames on each render, or can be
+    manually advanced with next_frame().
+
+    Attributes:
+        message: Text displayed next to the spinner.
+        style: The spinner animation style.
+        spinner_color: Color for the spinner character.
+        message_color: Color for the message text.
+        interval: Time between frames in seconds (for threaded mode).
+
+    Example:
+        # In a Live display (auto-advances on render)
+        spinner = RichSpinner("Loading...")
+        with Live(spinner, refresh_per_second=10):
+            time.sleep(2)
+
+        # Standalone with threading
+        with RichSpinner("Working...") as spinner:
+            time.sleep(2)
+    """
+
+    message: str = ""
+    style: SpinnerStyle = SpinnerStyle.DOTS_6
+    spinner_color: str = FROST_CYAN
+    message_color: str = FG_PRIMARY
+    interval: float = 0.1
+
+    _frame_index: int = field(default=0, init=False, repr=False)
+    _running: bool = field(default=False, init=False, repr=False)
+    _thread: threading.Thread | None = field(default=None, init=False, repr=False)
+    _lock: threading.Lock = field(default_factory=threading.Lock, init=False, repr=False)
+    _console: Console | None = field(default=None, init=False, repr=False)
+    _live: Live | None = field(default=None, init=False, repr=False)
+
+    @property
+    def frames(self) -> tuple[str, ...]:
+        """Get the frame sequence for the current style."""
+        value: tuple[str, ...] = self.style.value
+        return value
+
+    @property
+    def current_frame(self) -> str:
+        """Get the current spinner frame character."""
+        return self.frames[self._frame_index % len(self.frames)]
+
+    def next_frame(self) -> str:
+        """Advance to the next frame and return it."""
+        with self._lock:
+            self._frame_index = (self._frame_index + 1) % len(self.frames)
+            return self.current_frame
+
+    def reset(self) -> None:
+        """Reset the spinner to the first frame."""
+        with self._lock:
+            self._frame_index = 0
+
+    def update_message(self, message: str) -> None:
+        """Update the spinner message."""
+        self.message = message
+
+    def __rich_console__(
+        self, console: Console, options: ConsoleOptions
+    ) -> RenderResult:
+        """Render the spinner for Rich console output.
+
+        This method is called by Rich when rendering the spinner.
+        It advances the frame on each render for automatic animation
+        when used with Live displays.
+        """
+        # Build the text with styled spinner and message
+        text = Text()
+        text.append(self.current_frame, style=Style(color=self.spinner_color))
+        if self.message:
+            text.append(" ")
+            text.append(self.message, style=Style(color=self.message_color))
+
+        # Advance frame for next render (makes Live auto-animate)
+        self.next_frame()
+
+        yield text
+
+    def _spin_loop(self) -> None:
+        """Internal loop for threaded spinning."""
+        while self._running:
+            if self._live:
+                self._live.update(self)
+            time.sleep(self.interval)
+
+    def start(self, console: Console | None = None) -> None:
+        """Start the spinner with its own Live display.
+
+        Args:
+            console: Optional Rich console to use. Creates one if not provided.
+        """
+        if self._running:
+            return
+
+        self._console = console or Console()
+        self._running = True
+        self.reset()
+
+        # Create Live display for standalone usage
+        self._live = Live(
+            self,
+            console=self._console,
+            refresh_per_second=int(1 / self.interval),
+            transient=True,
+        )
+        self._live.start()
+
+        # Start background thread to keep updating
+        self._thread = threading.Thread(target=self._spin_loop, daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        """Stop the spinner and clean up."""
+        self._running = False
+
+        if self._thread:
+            self._thread.join(timeout=1.0)
+            self._thread = None
+
+        if self._live:
+            self._live.stop()
+            self._live = None
+
+    def __enter__(self) -> RichSpinner:
+        """Context manager entry - start the spinner."""
+        self.start()
+        return self
+
+    def __exit__(self, exc_type: type | None, exc_val: BaseException | None, exc_tb: object | None) -> None:
+        """Context manager exit - stop the spinner."""
+        self.stop()
+
+
+def create_spinner_text(
+    message: str = "",
+    style: SpinnerStyle = SpinnerStyle.DOTS_6,
+    spinner_color: str = FROST_CYAN,
+    message_color: str = FG_PRIMARY,
+    frame_index: int = 0,
+) -> Text:
+    """Create a Rich Text object with spinner and message.
+
+    This is a utility function for creating spinner text without
+    the full RichSpinner class. Useful for manual frame control.
+
+    Args:
+        message: Text to display after the spinner.
+        style: Spinner animation style.
+        spinner_color: Color for the spinner character.
+        message_color: Color for the message text.
+        frame_index: Which frame to display (0-indexed).
+
+    Returns:
+        Rich Text object with styled spinner and message.
+
+    Example:
+        for i in range(20):
+            text = create_spinner_text("Loading...", frame_index=i)
+            console.print(text, end="\\r")
+            time.sleep(0.1)
+    """
+    frames = style.value
+    frame = frames[frame_index % len(frames)]
+
+    text = Text()
+    text.append(frame, style=Style(color=spinner_color))
+    if message:
+        text.append(" ")
+        text.append(message, style=Style(color=message_color))
+
+    return text
+
+
+# Convenience aliases for backwards compatibility
+SpinnerManager = RichSpinner
+
+
+def spinner_frames(style: SpinnerStyle = SpinnerStyle.DOTS_6) -> Iterator[str]:
+    """Generate infinite spinner frames.
+
+    Args:
+        style: Spinner animation style.
+
+    Yields:
+        Spinner frame characters in sequence, repeating indefinitely.
+
+    Example:
+        frames = spinner_frames(SpinnerStyle.DOTS_6)
+        for _ in range(30):
+            print(next(frames), end="\\r", flush=True)
+            time.sleep(0.1)
+    """
+    frames_tuple = style.value
+    index = 0
+    while True:
+        yield frames_tuple[index % len(frames_tuple)]
+        index += 1

ralph/storage.py

@@ -0,0 +1,77 @@
+"""Platform-specific storage paths for ralph-coding application."""
+
+from pathlib import Path
+from platformdirs import user_data_dir
+
+
+APP_NAME = "ralph-coding"
+
+
+def get_app_data_dir() -> Path:
+    """
+    Get the platform-specific application data directory.
+
+    Returns:
+        - Windows: %APPDATA%/ralph-coding/
+        - macOS: ~/Library/Application Support/ralph-coding/
+        - Linux: ~/.local/share/ralph-coding/
+    """
+    data_dir = Path(user_data_dir(APP_NAME))
+    data_dir.mkdir(parents=True, exist_ok=True)
+    return data_dir
+
+
+def get_config_path() -> Path:
+    """Get the path to the global config file."""
+    return get_app_data_dir() / "config.json"
+
+
+def get_project_ralph_dir(project_dir: Path) -> Path:
+    """
+    Get the .ralph directory for a specific project.
+
+    Args:
+        project_dir: The root directory of the project
+
+    Returns:
+        Path to the .ralph directory within the project
+    """
+    ralph_dir = project_dir / ".ralph"
+    ralph_dir.mkdir(parents=True, exist_ok=True)
+    return ralph_dir
+
+
+def get_project_tasks_path(project_dir: Path) -> Path:
+    """Get the path to the project's tasks.json file."""
+    return get_project_ralph_dir(project_dir) / "tasks.json"
+
+
+def get_project_state_path(project_dir: Path) -> Path:
+    """Get the path to the project's state.json file."""
+    return get_project_ralph_dir(project_dir) / "state.json"
+
+
+def get_project_logs_dir(project_dir: Path) -> Path:
+    """Get the path to the project's logs directory (for debug mode)."""
+    logs_dir = get_project_ralph_dir(project_dir) / "logs"
+    logs_dir.mkdir(parents=True, exist_ok=True)
+    return logs_dir
+
+
+def get_progress_md_path(project_dir: Path) -> Path:
+    """Get the path to progress.md in the project root."""
+    return project_dir / "progress.md"
+
+
+def get_learnings_md_path(project_dir: Path) -> Path:
+    """Get the path to learnings.md in the project root."""
+    return project_dir / "learnings.md"
+
+
+def get_summarised_notes_path(project_dir: Path) -> Path:
+    """Get the path to summarised_notes.txt in the .ralph directory.
+
+    This file archives full story notes along with their summaries
+    when stories hit max attempts (debug mode only).
+    """
+    return get_project_ralph_dir(project_dir) / "summarised_notes.txt"

ralph/tasks.py

@@ -0,0 +1,298 @@
+"""Task management and JSON schema validation for ralph-coding."""
+
+import json
+import uuid
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Literal
+
+import jsonschema
+
+from .storage import get_project_tasks_path
+
+
+TaskStatus = Literal["pending", "in_progress", "completed", "errored"]
+
+
+def _get_schema() -> dict[str, Any]:
+    """Load the task schema from the schemas directory."""
+    schema_path = Path(__file__).parent / "schemas" / "task_schema.json"
+    with open(schema_path, "r", encoding="utf-8") as f:
+        result: dict[str, Any] = json.load(f)
+        return result
+
+
+def _validate_tasks_data(data: dict[str, Any]) -> None:
+    """Validate tasks data against the JSON schema."""
+    schema = _get_schema()
+    jsonschema.validate(instance=data, schema=schema)
+
+
+class Task:
+    """Represents a single task (either thin or full spec)."""
+
+    def __init__(
+        self,
+        name: str,
+        id: str | None = None,
+        description: str = "",
+        status: TaskStatus = "pending",
+        prerequisites: list[str] | None = None,
+        acceptance_criteria: list[str] | None = None,
+        files_to_modify: list[str] | None = None,
+        notes: str = "",
+        created_at: str | None = None,
+        started_at: str | None = None,
+        completed_at: str | None = None,
+        is_thin: bool = False,
+    ):
+        self.id = id or str(uuid.uuid4())
+        self.name = name
+        self.description = description
+        self.status = status
+        self.prerequisites = prerequisites or []
+        self.acceptance_criteria = acceptance_criteria or []
+        self.files_to_modify = files_to_modify or []
+        self.notes = notes
+        self.created_at = created_at or datetime.utcnow().isoformat()
+        self.started_at = started_at
+        self.completed_at = completed_at
+        self._is_thin = is_thin
+
+    @classmethod
+    def from_thin(cls, description: str) -> "Task":
+        """Create a task from a thin task string."""
+        return cls(name=description, is_thin=True)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | str) -> "Task":
+        """Create a task from a dictionary or thin task string."""
+        if isinstance(data, str):
+            return cls.from_thin(data)
+
+        return cls(
+            id=data.get("id"),
+            name=data["name"],
+            description=data.get("description", ""),
+            status=data.get("status", "pending"),
+            prerequisites=data.get("prerequisites"),
+            acceptance_criteria=data.get("acceptance_criteria"),
+            files_to_modify=data.get("files_to_modify"),
+            notes=data.get("notes", ""),
+            created_at=data.get("created_at"),
+            started_at=data.get("started_at"),
+            completed_at=data.get("completed_at"),
+            is_thin=False,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert task to a dictionary for serialization."""
+        return {
+            "id": self.id,
+            "name": self.name,
+            "description": self.description,
+            "status": self.status,
+            "prerequisites": self.prerequisites,
+            "acceptance_criteria": self.acceptance_criteria,
+            "files_to_modify": self.files_to_modify,
+            "notes": self.notes,
+            "created_at": self.created_at,
+            "started_at": self.started_at,
+            "completed_at": self.completed_at,
+        }
+
+    def to_serializable(self) -> str | dict[str, Any]:
+        """Convert task to serializable format (thin string or full dict)."""
+        if self._is_thin and self.status == "pending":
+            return self.name
+        return self.to_dict()
+
+    @property
+    def is_thin(self) -> bool:
+        """Check if this is a thin (unspecced) task."""
+        return self._is_thin
+
+    @property
+    def is_specced(self) -> bool:
+        """Check if this task has been fully specified."""
+        return not self._is_thin
+
+    def spec(
+        self,
+        description: str,
+        acceptance_criteria: list[str] | None = None,
+        files_to_modify: list[str] | None = None,
+        prerequisites: list[str] | None = None,
+        notes: str = "",
+    ) -> None:
+        """Convert a thin task to a full spec."""
+        self.description = description
+        self.acceptance_criteria = acceptance_criteria or []
+        self.files_to_modify = files_to_modify or []
+        self.prerequisites = prerequisites or []
+        self.notes = notes
+        self._is_thin = False
+
+    def start(self) -> None:
+        """Mark the task as in progress."""
+        self.status = "in_progress"
+        self.started_at = datetime.utcnow().isoformat()
+
+    def complete(self) -> None:
+        """Mark the task as completed."""
+        self.status = "completed"
+        self.completed_at = datetime.utcnow().isoformat()
+
+    def error(self, reason: str = "") -> None:
+        """Mark the task as errored."""
+        self.status = "errored"
+        if reason:
+            self.notes = f"{self.notes}\n\nError: {reason}".strip()
+
+
+class TaskManager:
+    """Manages the collection of tasks for a project."""
+
+    def __init__(self, project_dir: Path):
+        self.project_dir = project_dir
+        self._tasks: list[Task] = []
+        self._load()
+
+    def _load(self) -> None:
+        """Load tasks from the project's tasks.json file."""
+        tasks_path = get_project_tasks_path(self.project_dir)
+
+        if tasks_path.exists():
+            try:
+                with open(tasks_path, "r", encoding="utf-8") as f:
+                    data = json.load(f)
+                _validate_tasks_data(data)
+                self._tasks = [Task.from_dict(t) for t in data.get("tasks", [])]
+            except (json.JSONDecodeError, jsonschema.ValidationError, IOError) as e:
+                # Start fresh if file is corrupted
+                self._tasks = []
+        else:
+            self._tasks = []
+
+    def _save(self) -> None:
+        """Save tasks to the project's tasks.json file."""
+        tasks_path = get_project_tasks_path(self.project_dir)
+        tasks_path.parent.mkdir(parents=True, exist_ok=True)
+
+        data = {"tasks": [t.to_serializable() for t in self._tasks]}
+        _validate_tasks_data(data)
+
+        with open(tasks_path, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2, ensure_ascii=False)
+
+    @property
+    def tasks(self) -> list[Task]:
+        """Get all tasks."""
+        return self._tasks.copy()
+
+    def add_thin_task(self, description: str) -> Task:
+        """Add a thin (unspecced) task."""
+        task = Task.from_thin(description)
+        self._tasks.append(task)
+        self._save()
+        return task
+
+    def add_full_task(
+        self,
+        name: str,
+        description: str,
+        acceptance_criteria: list[str] | None = None,
+        files_to_modify: list[str] | None = None,
+        prerequisites: list[str] | None = None,
+        notes: str = "",
+    ) -> Task:
+        """Add a fully specified task."""
+        task = Task(
+            name=name,
+            description=description,
+            acceptance_criteria=acceptance_criteria,
+            files_to_modify=files_to_modify,
+            prerequisites=prerequisites,
+            notes=notes,
+        )
+        self._tasks.append(task)
+        self._save()
+        return task
+
+    def get_task_by_id(self, task_id: str) -> Task | None:
+        """Get a task by its ID."""
+        for task in self._tasks:
+            if task.id == task_id:
+                return task
+        return None
+
+    def get_unspecced_tasks(self) -> list[Task]:
+        """Get all thin (unspecced) tasks."""
+        return [t for t in self._tasks if t.is_thin]
+
+    def get_specced_tasks(self) -> list[Task]:
+        """Get all fully specified tasks."""
+        return [t for t in self._tasks if t.is_specced]
+
+    def get_pending_tasks(self) -> list[Task]:
+        """Get all pending tasks that are ready to work on."""
+        return [
+            t for t in self._tasks
+            if t.status == "pending" and t.is_specced and self._prerequisites_met(t)
+        ]
+
+    def get_in_progress_task(self) -> Task | None:
+        """Get the currently in-progress task, if any."""
+        for task in self._tasks:
+            if task.status == "in_progress":
+                return task
+        return None
+
+    def get_completed_tasks(self) -> list[Task]:
+        """Get all completed tasks."""
+        return [t for t in self._tasks if t.status == "completed"]
+
+    def get_errored_tasks(self) -> list[Task]:
+        """Get all errored tasks."""
+        return [t for t in self._tasks if t.status == "errored"]
+
+    def _prerequisites_met(self, task: Task) -> bool:
+        """Check if all prerequisites for a task are completed.
+
+        Only considers prerequisites that match existing task IDs.
+        Descriptive prerequisites (non-UUID strings) are ignored.
+        """
+        for prereq_id in task.prerequisites:
+            prereq = self.get_task_by_id(prereq_id)
+            # Only block on prerequisites that actually exist
+            if prereq is not None and prereq.status != "completed":
+                return False
+        return True
+
+    def update_task(self, task: Task) -> None:
+        """Update a task and save changes."""
+        for i, t in enumerate(self._tasks):
+            if t.id == task.id:
+                self._tasks[i] = task
+                self._save()
+                return
+        raise ValueError(f"Task not found: {task.id}")
+
+    def remove_task(self, task_id: str) -> bool:
+        """Remove a task by ID."""
+        for i, task in enumerate(self._tasks):
+            if task.id == task_id:
+                del self._tasks[i]
+                self._save()
+                return True
+        return False
+
+    def get_stats(self) -> dict[str, int]:
+        """Get task statistics."""
+        return {
+            "unspecced": len(self.get_unspecced_tasks()),
+            "pending": sum(1 for t in self._tasks if t.status == "pending" and t.is_specced),
+            "in_progress": sum(1 for t in self._tasks if t.status == "in_progress"),
+            "completed": sum(1 for t in self._tasks if t.status == "completed"),
+            "errored": sum(1 for t in self._tasks if t.status == "errored"),
+        }