docker-orb 1.0.0__py3-none-any.whl

docker_orb/__main__.py

@@ -0,0 +1,5 @@
+"""Allows `python -m docker_orb` to work alongside the `docker-orb` script."""
+from .cli import main
+
+if __name__ == "__main__":
+    main()

docker_orb/_scrollbar.py

@@ -0,0 +1,136 @@
+"""
+Enforces a minimum scrollbar thumb size, app-wide.
+
+Textual's default ScrollBarRender lets the thumb shrink to a single cell for
+very long content (e.g. the main log stream, which buffers up to 20,000
+lines — see ViewerApp._buffer_cap). A 1-cell thumb is nearly impossible to
+grab with a real mouse in a terminal: clicks land on the track instead,
+which pages the view rather than dragging it, making click-drag scrolling
+feel broken. Clamping the *visual* thumb size doesn't affect drag math
+(ScrollBar._on_mouse_move scales purely from window_size/virtual_size, not
+from how big the thumb is drawn), so this is purely a grabbability fix.
+
+render_bar() below is a fork of textual.scrollbar.ScrollBarRender.render_bar
+(textual==8.2.7) with a single change: the thumb-size floor is MIN_THUMB_SIZE
+instead of 1. It can't be done by pre-inflating the `window_size` argument
+and delegating to super().render_bar() — window_size also drives the thumb's
+*position* ratio there, so inflating it shifts the thumb as well as
+resizing it. The size floor has to be applied after position is derived from
+the real window_size, which means owning the whole method body.
+
+Call install() once, early, before any scrollable widgets are composed.
+"""
+from __future__ import annotations
+
+from math import ceil
+
+from rich.color import Color
+from rich.segment import Segment
+from rich.segment import Segments
+from rich.style import Style
+
+from textual.scrollbar import ScrollBar, ScrollBarRender
+
+MIN_THUMB_SIZE = 3
+
+
+class _MinThumbScrollBarRender(ScrollBarRender):
+    @classmethod
+    def render_bar(
+        cls,
+        size: int = 25,
+        virtual_size: float = 50,
+        window_size: float = 20,
+        position: float = 0,
+        thickness: int = 1,
+        vertical: bool = True,
+        back_color: Color = Color.parse("#555555"),
+        bar_color: Color = Color.parse("bright_magenta"),
+    ) -> Segments:
+        if vertical:
+            bars = cls.VERTICAL_BARS
+        else:
+            bars = cls.HORIZONTAL_BARS
+
+        back = back_color
+        bar = bar_color
+
+        len_bars = len(bars)
+
+        width_thickness = thickness if vertical else 1
+
+        _Segment = Segment
+        _Style = Style
+        blank = cls.BLANK_GLYPH * width_thickness
+
+        foreground_meta = {"@mouse.down": "grab"}
+        if window_size and size and virtual_size and size != virtual_size:
+            bar_ratio = virtual_size / size
+            thumb_size = max(MIN_THUMB_SIZE, window_size / bar_ratio)
+
+            position_ratio = position / (virtual_size - window_size)
+            position = (size - thumb_size) * position_ratio
+
+            start = int(position * len_bars)
+            end = start + ceil(thumb_size * len_bars)
+
+            start_index, start_bar = divmod(max(0, start), len_bars)
+            end_index, end_bar = divmod(max(0, end), len_bars)
+
+            upper = {"@mouse.down": "scroll_up"}
+            lower = {"@mouse.down": "scroll_down"}
+
+            upper_back_segment = Segment(blank, _Style(bgcolor=back, meta=upper))
+            lower_back_segment = Segment(blank, _Style(bgcolor=back, meta=lower))
+
+            segments = [upper_back_segment] * int(size)
+            segments[end_index:] = [lower_back_segment] * (size - end_index)
+
+            segments[start_index:end_index] = [
+                _Segment(blank, _Style(color=bar, reverse=True, meta=foreground_meta))
+            ] * (end_index - start_index)
+
+            # Apply the smaller bar characters to head and tail of scrollbar for more "granularity"
+            if start_index < len(segments):
+                bar_character = bars[len_bars - 1 - start_bar]
+                if bar_character != " ":
+                    segments[start_index] = _Segment(
+                        bar_character * width_thickness,
+                        (
+                            _Style(bgcolor=back, color=bar, meta=foreground_meta)
+                            if vertical
+                            else _Style(
+                                bgcolor=back,
+                                color=bar,
+                                meta=foreground_meta,
+                                reverse=True,
+                            )
+                        ),
+                    )
+            if end_index < len(segments):
+                bar_character = bars[len_bars - 1 - end_bar]
+                if bar_character != " ":
+                    segments[end_index] = _Segment(
+                        bar_character * width_thickness,
+                        (
+                            _Style(
+                                bgcolor=back,
+                                color=bar,
+                                meta=foreground_meta,
+                                reverse=True,
+                            )
+                            if vertical
+                            else _Style(bgcolor=back, color=bar, meta=foreground_meta)
+                        ),
+                    )
+        else:
+            style = _Style(bgcolor=back)
+            segments = [_Segment(blank, style=style)] * int(size)
+        if vertical:
+            return Segments(segments, new_lines=True)
+        else:
+            return Segments((segments + [_Segment.line()]) * thickness, new_lines=False)
+
+
+def install() -> None:
+    ScrollBar.renderer = _MinThumbScrollBarRender

docker_orb/cli.py

@@ -0,0 +1,167 @@
+"""
+CLI entry point for docker-orb.
+
+If enough arguments are provided to fully specify a session, the viewer
+launches directly. Otherwise (or with --wizard), the interactive wizard runs.
+"""
+from __future__ import annotations
+
+import sys
+
+import click
+
+from .models import HealthConfig, LogMode, SessionConfig
+
+
+@click.command(context_settings={"help_option_names": ["-h", "--help"]})
+@click.option("-n", "--project", default=None,
+              help="Docker Compose project name (default: current directory's compose project).")
+@click.option("-p", "--container", "containers", multiple=True, metavar="NAME",
+              help="Service name to watch. Repeatable. Use multiple times for multiple services.")
+@click.option("--all-containers", "all_containers", is_flag=True,
+              help="Watch all services in the project.")
+@click.option("--stream", "mode", flag_value="stream", default=True,
+              help="Live tail mode (default).")
+@click.option("--dump", "mode", flag_value="dump",
+              help="Fetch existing logs and exit. No live stream.")
+@click.option("--tail", type=int, default=None, metavar="N",
+              help="(Dump mode) Last N lines to fetch.")
+@click.option("--since", default=None, metavar="DURATION",
+              help="(Dump mode) Fetch logs from this far back, e.g. 1h, 30m.")
+@click.option("-c", "--config", "config_name", default=None, metavar="NAME",
+              help="Load a saved config by name (scoped to project).")
+@click.option("--save-config", default=None, metavar="NAME",
+              help="Save this session's config under NAME before launching.")
+@click.option("-f", "--filter", "filters", multiple=True, metavar="PATTERN",
+              help="Hide lines matching PATTERN. Repeatable. Use /regex/ for regex.")
+@click.option("-H", "--highlight", "highlights", multiple=True, metavar="PATTERN",
+              help="Highlight lines matching PATTERN. Repeatable.")
+@click.option("-m", "--monitor", "monitors", multiple=True, metavar="PATTERN",
+              help="(Stream mode) Collect matching lines in monitor panel. Repeatable.")
+@click.option("--health", is_flag=True,
+              help="(Stream mode) Enable container health monitoring panel.")
+@click.option("--health-interval", type=int, default=5, show_default=True, metavar="MINUTES",
+              help="Container health check interval in minutes (min 1).")
+@click.option("--health-restart-threshold", type=int, default=1, show_default=True,
+              metavar="N", hidden=True,
+              help="Show containers in health panel when restart delta >= N (default 1).")
+@click.option("--wizard", is_flag=True,
+              help="Force the interactive setup wizard even if all args are provided.")
+def main(
+    project: str | None,
+    containers: tuple[str, ...],
+    all_containers: bool,
+    mode: str,
+    tail: int | None,
+    since: str | None,
+    config_name: str | None,
+    save_config: str | None,
+    filters: tuple[str, ...],
+    highlights: tuple[str, ...],
+    monitors: tuple[str, ...],
+    health: bool,
+    health_interval: int,
+    health_restart_threshold: int,
+    wizard: bool,
+) -> None:
+    """
+    docker-orb — Interactive Docker Compose log viewer.
+
+    Run with no arguments to launch the setup wizard.
+    Provide --project and --container flags to skip the wizard.
+
+    \b
+    Examples:
+      docker-orb                                    # wizard
+      docker-orb -n myapp -p api -p worker --stream
+      docker-orb -n myapp --all-containers --dump --tail 500
+      docker-orb -n myapp -p worker -f DEBUG -H ERROR --health
+    """
+    from . import compose as k
+    from .config import (
+        add_to_saved_strings,
+        load_session_config,
+        parse_string_input,
+        save_session_config,
+    )
+
+    # ── Resolve project ────────────────────────────────────────────────────
+    if project is None:
+        project = k.get_current_project()
+
+    # ── Decide: wizard or direct launch ─────────────────────────────────────
+    needs_wizard = wizard or (not containers and not all_containers and not config_name)
+    if needs_wizard:
+        _run_wizard(project)
+        return
+
+    # ── Load saved config (pre-fill) ─────────────────────────────────────────
+    session: SessionConfig | None = None
+    if config_name:
+        session = load_session_config(project, config_name)
+        if session is None:
+            click.echo(f"No saved config '{config_name}' found for project '{project}'.",
+                       err=True)
+            sys.exit(1)
+
+    # ── Build / override SessionConfig ───────────────────────────────────────
+    # CLI flags override anything from the loaded config
+    if session is None:
+        session = SessionConfig(project=project, services=[])
+
+    if containers:
+        session.services = list(containers)
+    elif all_containers:
+        session.services = [svc.name for svc in k.get_services(project)]
+
+    session.mode = LogMode(mode)
+    if tail is not None:
+        session.tail = tail
+    if since is not None:
+        session.since = since
+
+    # Merge CLI strings with any loaded-config strings
+    def _merge(existing: list[str], incoming: tuple[str, ...]) -> list[str]:
+        extra: list[str] = []
+        for raw in incoming:
+            extra.extend(parse_string_input(raw))
+        return existing + [s for s in extra if s not in existing]
+
+    session.filters    = _merge(session.filters,    filters)
+    session.highlights = _merge(session.highlights, highlights)
+    session.monitors   = _merge(session.monitors,   monitors)
+
+    if health:
+        session.health.enabled = True
+    session.health.interval_minutes = max(1, health_interval)
+    session.health.restart_threshold = health_restart_threshold
+
+    # ── Validate ─────────────────────────────────────────────────────────────
+    if not session.services:
+        click.echo("No services specified. Use --container NAME or --all-containers.", err=True)
+        sys.exit(1)
+
+    # ── Optionally save config ────────────────────────────────────────────────
+    if save_config:
+        session.name = save_config
+        save_session_config(session)
+        click.echo(f"Config saved as '{save_config}' for project '{project}'.")
+
+    # ── Launch viewer ─────────────────────────────────────────────────────────
+    _run_viewer(session)
+
+
+def _run_wizard(project: str) -> None:
+    from .wizard.app import WizardApp
+    app = WizardApp(initial_project=project)
+    result = app.run()
+    if result is None:
+        # User cancelled
+        sys.exit(0)
+    _run_viewer(result)
+
+
+def _run_viewer(config: SessionConfig) -> None:
+    from .viewer.app import ViewerApp
+    app = ViewerApp(config=config)
+    app.run()

docker_orb/colors.py

@@ -0,0 +1,60 @@
+"""
+Color assignment for containers using the golden angle method.
+
+Distributes hues at 137.508° (the golden angle) intervals in HSL space,
+which mathematically maximises perceptual distance between consecutive colors
+regardless of how many containers are selected.
+
+With 2 containers  → hues ~180° apart (near-complementary)
+With 5 containers  → hues evenly spread ~137° apart
+With 10 containers → still well-separated, no two adjacent colors look alike
+
+Saturation and lightness are fixed for good readability on dark terminals.
+"""
+from __future__ import annotations
+
+import colorsys
+
+# Golden angle in degrees
+GOLDEN_ANGLE = 137.508
+
+# HSL fixed axes — tuned for dark terminal backgrounds
+SATURATION = 0.75   # vivid but not neon
+LIGHTNESS   = 0.65  # bright enough to read, not washed out
+
+# Starting hue offset — avoids starting at pure red (0°) which can look like error color
+_START_HUE = 30.0  # degrees
+
+
+def _hsl_to_rgb(h_deg: float, s: float, l: float) -> tuple[int, int, int]:
+    """Convert HSL (h in degrees, s and l in [0,1]) to RGB tuple (0–255)."""
+    h = h_deg / 360.0
+    r, g, b = colorsys.hls_to_rgb(h, l, s)
+    return int(r * 255), int(g * 255), int(b * 255)
+
+
+def _rgb_to_hex(r: int, g: int, b: int) -> str:
+    return f"#{r:02x}{g:02x}{b:02x}"
+
+
+def assign_colors(container_names: list[str]) -> dict[str, str]:
+    """
+    Return a mapping of container_name → hex color string.
+
+    Colors are assigned in the order containers appear in the list.
+    The same container list always produces the same colors (deterministic).
+    """
+    result: dict[str, str] = {}
+    for i, name in enumerate(container_names):
+        hue = (_START_HUE + i * GOLDEN_ANGLE) % 360.0
+        rgb = _hsl_to_rgb(hue, SATURATION, LIGHTNESS)
+        result[name] = _rgb_to_hex(*rgb)
+    return result
+
+
+def get_color(container_name: str, color_map: dict[str, str]) -> str:
+    """
+    Look up a container's color, returning a safe fallback if not found.
+    The fallback is white, which is always readable on dark backgrounds.
+    """
+    return color_map.get(container_name, "#ffffff")