ccburn 0.1.0__py3-none-any.whl

ccburn/display/layout.py

@@ -0,0 +1,246 @@
+"""Layout manager for ccburn TUI."""
+
+import os
+from datetime import datetime, timezone
+
+from rich.console import Console
+from rich.layout import Layout
+from rich.text import Text
+
+try:
+    from ..data.models import BurnMetrics, LimitData, LimitType, UsageSnapshot
+    from ..utils.calculator import calculate_budget_pace, calculate_burn_metrics
+    from .chart import BurnupChart
+    from .gauges import create_gauge_section, create_header
+except ImportError:
+    from ccburn.data.models import BurnMetrics, LimitData, LimitType, UsageSnapshot
+    from ccburn.display.chart import BurnupChart
+    from ccburn.display.gauges import create_gauge_section, create_header
+    from ccburn.utils.calculator import calculate_budget_pace, calculate_burn_metrics
+
+
+class BurnupLayout:
+    """Layout manager for the ccburn TUI."""
+
+    MIN_WIDTH = 40
+    MIN_HEIGHT = 10
+    COMPACT_WIDTH = 60
+    COMPACT_HEIGHT = 15
+
+    def __init__(self, console: Console | None = None):
+        """Initialize the layout manager.
+
+        Args:
+            console: Rich Console instance (creates one if not provided)
+        """
+        self.console = console or Console()
+        self._last_limit_data: LimitData | None = None
+        self._last_snapshots: list[UsageSnapshot] = []
+        self._last_metrics: BurnMetrics | None = None
+        self._error_message: str | None = None
+        self._stale_data_time: datetime | None = None
+
+    def get_terminal_size(self) -> tuple[int, int]:
+        """Get current terminal size.
+
+        Returns:
+            (width, height) tuple
+        """
+        try:
+            size = os.get_terminal_size()
+            return size.columns, size.lines
+        except OSError:
+            return 80, 24  # Default fallback
+
+    def should_use_compact_mode(self) -> bool:
+        """Determine if compact mode should be used.
+
+        Returns:
+            True if terminal is too small for full layout
+        """
+        width, height = self.get_terminal_size()
+        return width < self.COMPACT_WIDTH or height < self.COMPACT_HEIGHT
+
+    def update(
+        self,
+        limit_type: LimitType,
+        limit_data: LimitData | None,
+        snapshots: list[UsageSnapshot],
+        error: str | None = None,
+        stale_since: datetime | None = None,
+        since: datetime | None = None,
+    ) -> Layout:
+        """Update the layout with new data.
+
+        Args:
+            limit_type: Which limit to display
+            limit_data: Current limit data
+            snapshots: Historical snapshots for chart
+            error: Error message to display (if any)
+            stale_since: When data became stale (if using cached data)
+            since: Zoom view start time
+
+        Returns:
+            Updated Rich Layout
+        """
+        self._last_limit_data = limit_data
+        self._last_snapshots = snapshots
+        self._error_message = error
+        self._stale_data_time = stale_since
+
+        # Calculate metrics
+        if limit_data:
+            self._last_metrics = calculate_burn_metrics(limit_data, snapshots)
+
+        width, height = self.get_terminal_size()
+
+        if self.should_use_compact_mode():
+            return self._create_compact_layout(limit_type, width, height)
+
+        return self._create_full_layout(limit_type, width, height, since)
+
+    def _create_full_layout(
+        self,
+        limit_type: LimitType,
+        width: int,
+        height: int,
+        since: datetime | None = None,
+    ) -> Layout:
+        """Create full TUI layout with header, gauges, and chart.
+
+        Args:
+            limit_type: Which limit to display
+            width: Terminal width
+            height: Terminal height
+            since: Zoom view start time
+
+        Returns:
+            Rich Layout
+        """
+        root = Layout()
+
+        # Calculate sizes - minimize header/gauges, maximize chart
+        header_height = 1
+        gauges_height = 2  # Two progress bars
+        error_height = 1 if self._error_message or self._stale_data_time else 0
+        # Use full remaining height for chart (no extra padding with screen=True)
+        chart_height = height - header_height - gauges_height - error_height
+
+        # Create sections
+        header_layout = Layout(size=header_height, name="header")
+        gauges_layout = Layout(size=gauges_height, name="gauges")
+        chart_layout = Layout(name="chart")
+
+        # Add error banner if needed
+        if self._error_message or self._stale_data_time:
+            error_layout = Layout(size=error_height, name="error")
+            root.split_column(header_layout, gauges_layout, error_layout, chart_layout)
+            error_layout.update(self._create_error_banner())
+        else:
+            root.split_column(header_layout, gauges_layout, chart_layout)
+
+        # Update header
+        header_layout.update(create_header(limit_type, self._last_limit_data))
+
+        # Update gauges
+        budget_pace = 0.0
+        if self._last_limit_data:
+            budget_pace = calculate_budget_pace(
+                self._last_limit_data.resets_at,
+                self._last_limit_data.window_hours,
+            )
+        gauges_layout.update(create_gauge_section(self._last_limit_data, budget_pace))
+
+        # Update chart
+        chart = BurnupChart(
+            self._last_limit_data,
+            self._last_snapshots,
+            since=since,
+            explicit_height=chart_height,
+        )
+        chart_layout.update(chart)
+
+        return root
+
+    def _create_compact_layout(
+        self,
+        limit_type: LimitType,
+        width: int,
+        height: int,
+    ) -> Layout:
+        """Create compact layout for small terminals.
+
+        Args:
+            limit_type: Which limit to display
+            width: Terminal width
+            height: Terminal height
+
+        Returns:
+            Rich Layout with minimal display
+        """
+        root = Layout()
+
+        # Just header and gauges in compact mode
+        header_layout = Layout(size=1, name="header")
+        gauges_layout = Layout(size=3, name="gauges")
+        info_layout = Layout(name="info")
+
+        root.split_column(header_layout, gauges_layout, info_layout)
+
+        # Update header
+        header_layout.update(create_header(limit_type, self._last_limit_data))
+
+        # Update gauges
+        budget_pace = 0.0
+        if self._last_limit_data:
+            budget_pace = calculate_budget_pace(
+                self._last_limit_data.resets_at,
+                self._last_limit_data.window_hours,
+            )
+        gauges_layout.update(create_gauge_section(self._last_limit_data, budget_pace))
+
+        # Show info text instead of chart
+        info_text = Text("Terminal too small for chart. Expand window or use --compact.", style="dim")
+        if self._error_message:
+            info_text = Text(self._error_message, style="yellow")
+        info_layout.update(info_text)
+
+        return root
+
+    def _create_error_banner(self) -> Text:
+        """Create error/warning banner.
+
+        Returns:
+            Rich Text with error/warning message
+        """
+        if self._error_message:
+            return Text(f"Warning: {self._error_message}", style="yellow")
+
+        if self._stale_data_time:
+            from ..utils.formatting import format_duration
+
+            now = datetime.now(timezone.utc)
+            minutes_stale = int((now - self._stale_data_time).total_seconds() / 60)
+            return Text(
+                f"Using cached data (last updated {format_duration(minutes_stale)} ago)",
+                style="yellow",
+            )
+
+        return Text("")
+
+    def render(self) -> Layout:
+        """Get the current layout without updating data.
+
+        Returns:
+            Current Rich Layout
+        """
+        limit_type = LimitType.SESSION
+        if self._last_limit_data:
+            limit_type = self._last_limit_data.limit_type
+
+        width, height = self.get_terminal_size()
+
+        if self.should_use_compact_mode():
+            return self._create_compact_layout(limit_type, width, height)
+
+        return self._create_full_layout(limit_type, width, height)

ccburn/main.py

@@ -0,0 +1,98 @@
+"""ccburn - Terminal-based Claude Code usage limit visualizer."""
+
+
+import typer
+
+try:
+    from .cli import (
+        CompactOption,
+        DebugOption,
+        JsonOption,
+        OnceOption,
+        SessionIntervalOption,
+        SinceOption,
+        register_commands,
+        run_app,
+    )
+    from .data.models import LimitType
+except ImportError:
+    from ccburn.cli import (
+        CompactOption,
+        DebugOption,
+        JsonOption,
+        OnceOption,
+        SessionIntervalOption,
+        SinceOption,
+        register_commands,
+        run_app,
+    )
+    from ccburn.data.models import LimitType
+
+
+app = typer.Typer(
+    name="ccburn",
+    help="Visualize Claude Code usage limits with real-time burn-up charts.",
+    rich_markup_mode="rich",
+    add_completion=True,
+    no_args_is_help=False,
+)
+
+# Register subcommands
+register_commands(app)
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-v",
+        help="Show version and exit.",
+    ),
+    json_output: bool = JsonOption,
+    once: bool = OnceOption,
+    compact: bool = CompactOption,
+    since: str | None = SinceOption,
+    interval: int = SessionIntervalOption,
+    debug: bool = DebugOption,
+) -> None:
+    """ccburn - Claude Code usage limit visualizer.
+
+    Visualize your Claude Code usage limits with real-time burn-up charts.
+    Shows 5-hour rolling session limit by default.
+
+    \b
+    Examples:
+        ccburn              # Live TUI showing session limit
+        ccburn session      # Same as above (explicit)
+        ccburn weekly       # Show 7-day weekly limit
+        ccburn weekly-sonnet # Show 7-day Sonnet limit
+        ccburn --json       # JSON output
+        ccburn --compact    # Single-line for status bars
+        ccburn --once       # Print once and exit
+    """
+    if version:
+        try:
+            from importlib.metadata import version as get_version
+
+            typer.echo(f"ccburn {get_version('ccburn')}")
+        except Exception:
+            typer.echo("ccburn 1.0.0")
+        raise typer.Exit()
+
+    # If no subcommand, default to session
+    if ctx.invoked_subcommand is None:
+        run_app(
+            LimitType.SESSION,
+            json_output=json_output,
+            once=once,
+            compact=compact,
+            since=since,
+            interval=interval,
+            debug=debug,
+        )
+
+
+if __name__ == "__main__":
+    app()

ccburn/utils/__init__.py

@@ -0,0 +1,45 @@
+"""Utilities for ccburn - calculators and formatters."""
+
+try:
+    from .calculator import (
+        calculate_budget_pace,
+        calculate_burn_metrics,
+        calculate_burn_rate,
+        classify_burn_trend,
+        estimate_time_to_empty,
+        get_recommendation,
+    )
+    from .formatting import (
+        format_duration,
+        format_percentage,
+        format_reset_time,
+        get_utilization_color,
+    )
+except ImportError:
+    from ccburn.utils.calculator import (
+        calculate_budget_pace,
+        calculate_burn_metrics,
+        calculate_burn_rate,
+        classify_burn_trend,
+        estimate_time_to_empty,
+        get_recommendation,
+    )
+    from ccburn.utils.formatting import (
+        format_duration,
+        format_percentage,
+        format_reset_time,
+        get_utilization_color,
+    )
+
+__all__ = [
+    "format_duration",
+    "format_percentage",
+    "format_reset_time",
+    "get_utilization_color",
+    "calculate_budget_pace",
+    "calculate_burn_rate",
+    "estimate_time_to_empty",
+    "classify_burn_trend",
+    "get_recommendation",
+    "calculate_burn_metrics",
+]

ccburn/utils/calculator.py

@@ -0,0 +1,207 @@
+"""Calculator utilities for burn rate, budget pace, and predictions."""
+
+from datetime import datetime, timedelta, timezone
+
+try:
+    from ..data.models import BurnMetrics, LimitData, LimitType, UsageSnapshot
+except ImportError:
+    from ccburn.data.models import BurnMetrics, LimitData, LimitType, UsageSnapshot
+
+
+def calculate_budget_pace(resets_at: datetime, window_hours: float) -> float:
+    """Calculate what percentage of the window has elapsed.
+
+    Formula: (now - window_start) / window_duration
+    Where: window_start = resets_at - window_hours
+
+    Args:
+        resets_at: When the limit resets
+        window_hours: Duration of the window in hours
+
+    Returns:
+        Float between 0.0 and 1.0 representing elapsed fraction
+    """
+    now = datetime.now(timezone.utc)
+
+    # Ensure resets_at is timezone-aware
+    if resets_at.tzinfo is None:
+        resets_at = resets_at.replace(tzinfo=timezone.utc)
+
+    window_start = resets_at - timedelta(hours=window_hours)
+    elapsed = (now - window_start).total_seconds()
+    window_seconds = window_hours * 3600
+
+    if window_seconds <= 0:
+        return 0.0
+
+    pace = elapsed / window_seconds
+    return max(0.0, min(1.0, pace))  # Clamp 0-1
+
+
+def calculate_burn_rate(
+    snapshots: list[UsageSnapshot],
+    limit_type: LimitType,
+    window_minutes: int = 5,
+) -> float:
+    """Calculate burn rate as percentage points per hour.
+
+    Uses simple linear calculation over recent snapshots.
+
+    Args:
+        snapshots: List of usage snapshots (should be sorted by timestamp)
+        limit_type: Which limit to calculate burn rate for
+        window_minutes: How far back to look for calculation
+
+    Returns:
+        Burn rate in percentage points per hour (e.g., 12.5 means 12.5%/hour)
+    """
+    if len(snapshots) < 2:
+        return 0.0
+
+    now = datetime.now(timezone.utc)
+    cutoff = now - timedelta(minutes=window_minutes)
+
+    # Filter to recent snapshots
+    recent = [s for s in snapshots if s.timestamp >= cutoff]
+
+    if len(recent) < 2:
+        # Fall back to any 2 snapshots if not enough recent ones
+        recent = snapshots[-2:] if len(snapshots) >= 2 else []
+
+    if len(recent) < 2:
+        return 0.0
+
+    # Get utilization for the specified limit type
+    first = recent[0]
+    last = recent[-1]
+
+    first_limit = first.get_limit(limit_type)
+    last_limit = last.get_limit(limit_type)
+
+    if first_limit is None or last_limit is None:
+        return 0.0
+
+    delta_util = (last_limit.utilization - first_limit.utilization) * 100  # Convert to %
+    delta_hours = (last.timestamp - first.timestamp).total_seconds() / 3600
+
+    if delta_hours <= 0:
+        return 0.0
+
+    return delta_util / delta_hours  # %/hour
+
+
+def estimate_time_to_empty(current_utilization: float, burn_rate_per_hour: float) -> int | None:
+    """Estimate minutes until 100% utilization at current burn rate.
+
+    Args:
+        current_utilization: Current utilization (0-1)
+        burn_rate_per_hour: Burn rate in percentage points per hour
+
+    Returns:
+        Minutes until 100%, or None if burn rate is zero or negative
+    """
+    if burn_rate_per_hour <= 0:
+        return None
+
+    remaining = 100.0 - (current_utilization * 100)
+    if remaining <= 0:
+        return 0
+
+    hours_to_empty = remaining / burn_rate_per_hour
+    return int(hours_to_empty * 60)
+
+
+def classify_burn_trend(burn_rate_per_hour: float) -> str:
+    """Classify burn rate into human-readable trend.
+
+    Args:
+        burn_rate_per_hour: Burn rate in percentage points per hour
+
+    Returns:
+        One of: "low", "moderate", "high", "critical"
+    """
+    if burn_rate_per_hour < 5:
+        return "low"
+    elif burn_rate_per_hour < 15:
+        return "moderate"
+    elif burn_rate_per_hour < 30:
+        return "high"
+    else:
+        return "critical"
+
+
+def get_recommendation(utilization: float, budget_pace: float) -> str:
+    """Get recommendation based on utilization and budget pace.
+
+    Args:
+        utilization: Current utilization (0-1)
+        budget_pace: How much of window has elapsed (0-1)
+
+    Returns:
+        One of: "plenty_available", "on_track", "moderate_pace", "conserve", "critical"
+    """
+    if utilization > 0.9:
+        return "critical"
+    elif utilization > 0.75:
+        return "conserve"
+    elif utilization > 0.5:
+        if utilization <= budget_pace:
+            return "on_track"
+        return "moderate_pace"
+    else:
+        return "plenty_available"
+
+
+def get_status(utilization: float, budget_pace: float) -> str:
+    """Get pace status.
+
+    Args:
+        utilization: Current utilization (0-1)
+        budget_pace: How much of window has elapsed (0-1)
+
+    Returns:
+        One of: "ahead_of_pace", "on_pace", "behind_pace"
+    """
+    # "ahead" means using more than expected (bad)
+    # "behind" means using less than expected (good)
+    diff = utilization - budget_pace
+
+    if abs(diff) < 0.05:  # Within 5% tolerance
+        return "on_pace"
+    elif diff > 0:
+        return "ahead_of_pace"
+    else:
+        return "behind_pace"
+
+
+def calculate_burn_metrics(
+    limit_data: LimitData,
+    snapshots: list[UsageSnapshot],
+    window_minutes: int = 5,
+) -> BurnMetrics:
+    """Calculate all burn metrics for a limit.
+
+    Args:
+        limit_data: Current limit data
+        snapshots: Historical snapshots for burn rate calculation
+        window_minutes: How far back to look for burn rate
+
+    Returns:
+        BurnMetrics with all calculated values
+    """
+    budget_pace = calculate_budget_pace(limit_data.resets_at, limit_data.window_hours)
+    burn_rate = calculate_burn_rate(snapshots, limit_data.limit_type, window_minutes)
+    time_to_empty = estimate_time_to_empty(limit_data.utilization, burn_rate)
+    trend = classify_burn_trend(burn_rate)
+    status = get_status(limit_data.utilization, budget_pace)
+    recommendation = get_recommendation(limit_data.utilization, budget_pace)
+
+    return BurnMetrics(
+        limit_type=limit_data.limit_type,
+        percent_per_hour=burn_rate,
+        trend=trend,
+        estimated_minutes_to_100=time_to_empty,
+        budget_pace=budget_pace,
+        status=status,
+        recommendation=recommendation,
+    )