spych.cli_tools

  1import sys, time, threading, re, random
  2
  3from spych.spinners import Spinner
  4
  5# Helper to strip ANSI escape codes before measuring string length,
  6# so box-drawing alignment is based on visible characters only.
  7_ANSI_ESCAPE_RE = re.compile(r"\033\[[0-9;]*m")
  8
  9
 10def _visible_len(text: str) -> int:
 11    return len(_ANSI_ESCAPE_RE.sub("", text))
 12
 13
 14# ---------------------------------------------------------------------------
 15# Theme system
 16# ---------------------------------------------------------------------------
 17
 18# Escape-code constants used only inside this module to build the palettes.
 19_RESET = "\033[0m"
 20_BOLD = "\033[1m"
 21_DIM = "\033[2m"
 22_ITALIC = "\033[3m"
 23
 24
 25class Theme:
 26    """
 27    Holds the active color palette.  Four built-in themes are provided:
 28
 29    - ``"dark"``      (default) — bright colors on dark backgrounds.
 30    - ``"light"``     — deep, high-contrast colors on light/white backgrounds.
 31    - ``"solarized"`` — Solarized-Dark accent palette; comfortable for long sessions.
 32    - ``"mono"``      — greyscale only; no color, just bold/dim contrast.
 33
 34    Every role needed by ``CliSpinner`` and ``CliPrinter`` lives here,
 35    including the formatting escapes (``reset``, ``bold``, ``italic``) so
 36    nothing outside this class references raw ANSI strings.
 37    """
 38
 39    THEMES: dict[str, dict] = {
 40        # ------------------------------------------------------------------
 41        # dark — original palette, bright on dark
 42        # ------------------------------------------------------------------
 43        "dark": {
 44            # formatting
 45            "reset": _RESET,
 46            "bold": _BOLD,
 47            "italic": _ITALIC,
 48            # structural
 49            "chrome": "\033[90m",  # dark-gray  — borders, dividers
 50            "body": "\033[97m",  # bright white — primary text
 51            "dim": _DIM,  # secondary / de-emphasised
 52            # semantic
 53            "accent": "\033[96m",  # bright cyan  — brand accent
 54            "highlight": "\033[95m",  # bright magenta — speaker label
 55            "running": "\033[93m",  # bright yellow — in-progress
 56            "success": "\033[92m",  # bright green  — completed
 57            "error": "\033[91m",  # bright red    — failures
 58            # spinner
 59            "spinner_colors": [
 60                "\033[96m",  # bright cyan
 61                "\033[94m",  # bright blue
 62                "\033[95m",  # bright magenta
 63                "\033[96m",
 64            ],
 65        },
 66        # ------------------------------------------------------------------
 67        # light — readable on white/light backgrounds
 68        # ------------------------------------------------------------------
 69        "light": {
 70            "reset": _RESET,
 71            "bold": _BOLD,
 72            "italic": _ITALIC,
 73            "chrome": "\033[90m",  # dark-gray borders
 74            "body": "\033[30m",  # black text
 75            "dim": _DIM,
 76            "accent": "\033[36m",  # teal
 77            "highlight": "\033[35m",  # magenta/purple
 78            "running": "\033[33m",  # amber
 79            "success": "\033[32m",  # dark green
 80            "error": "\033[31m",  # dark red
 81            "spinner_colors": [
 82                "\033[36m",  # teal
 83                "\033[34m",  # blue
 84                "\033[35m",  # magenta
 85                "\033[36m",
 86            ],
 87        },
 88        # ------------------------------------------------------------------
 89        # solarized — Solarized-Dark accent colors, muted base
 90        # ------------------------------------------------------------------
 91        "solarized": {
 92            "reset": _RESET,
 93            "bold": _BOLD,
 94            "italic": _ITALIC,
 95            "chrome": "\033[38;5;240m",  # base01  — subtle borders
 96            "body": "\033[38;5;252m",  # base2   — primary text
 97            "dim": _DIM,
 98            "accent": "\033[38;5;37m",  # cyan    (#2aa198)
 99            "highlight": "\033[38;5;125m",  # magenta (#d33682)
100            "running": "\033[38;5;136m",  # yellow  (#b58900)
101            "success": "\033[38;5;64m",  # green   (#859900)
102            "error": "\033[38;5;160m",  # red     (#dc322f)
103            "spinner_colors": [
104                "\033[38;5;37m",  # cyan
105                "\033[38;5;33m",  # blue   (#268bd2)
106                "\033[38;5;61m",  # violet (#6c71c4)
107                "\033[38;5;37m",
108            ],
109        },
110        # ------------------------------------------------------------------
111        # mono — greyscale; bold/dim contrast only, no hue
112        # ------------------------------------------------------------------
113        "mono": {
114            "reset": _RESET,
115            "bold": _BOLD,
116            "italic": _ITALIC,
117            "chrome": "\033[90m",  # dark gray
118            "body": "\033[97m",  # bright white
119            "dim": _DIM,
120            "accent": _BOLD,  # bold, no hue
121            "highlight": _BOLD,
122            "running": "\033[97m",
123            "success": "\033[97m",
124            "error": _BOLD,
125            "spinner_colors": [
126                "\033[97m",  # bright white
127                "\033[37m",  # light gray
128                "\033[90m",  # dark gray
129                "\033[97m",
130            ],
131        },
132    }
133
134    VALID: tuple[str, ...] = tuple(THEMES.keys())
135
136    def __init__(self) -> None:
137        self._palette: dict = self.THEMES["dark"]
138
139    # Convenience accessors -------------------------------------------------
140
141    @property
142    def reset(self) -> str:
143        return self._palette["reset"]
144
145    @property
146    def bold(self) -> str:
147        return self._palette["bold"]
148
149    @property
150    def italic(self) -> str:
151        return self._palette["italic"]
152
153    @property
154    def chrome(self) -> str:
155        return self._palette["chrome"]
156
157    @property
158    def body(self) -> str:
159        return self._palette["body"]
160
161    @property
162    def dim(self) -> str:
163        return self._palette["dim"]
164
165    @property
166    def accent(self) -> str:
167        return self._palette["accent"]
168
169    @property
170    def highlight(self) -> str:
171        return self._palette["highlight"]
172
173    @property
174    def running(self) -> str:
175        return self._palette["running"]
176
177    @property
178    def success(self) -> str:
179        return self._palette["success"]
180
181    @property
182    def error(self) -> str:
183        return self._palette["error"]
184
185    @property
186    def spinner_colors(self) -> list[str]:
187        return self._palette["spinner_colors"]
188
189    # Mutation --------------------------------------------------------------
190
191    def apply(self, name: str) -> None:
192        """Switch the active theme by name."""
193        if name not in self.THEMES:
194            raise ValueError(
195                f"Unknown theme {name!r}. Choose one of: {', '.join(self.VALID)}"
196            )
197        self._palette = self.THEMES[name]
198
199
200# Module-level singleton consumed by CliSpinner and CliPrinter.
201theme = Theme()
202
203
204def set_theme(name: str) -> None:
205    """
206    Switch the global CLI color theme.
207
208    Call this **once**, before any output is produced — typically right after
209    argument parsing in ``cli.py``.
210
211    Requires:
212
213    - ``name``:
214        - Type: ``str``
215        - What: One of ``"dark"`` (default), ``"light"``, ``"solarized"``,
216          or ``"mono"``
217    """
218    theme.apply(name)
219
220
221# ---------------------------------------------------------------------------
222
223
224class CliSpinner:
225    """
226    Animated terminal spinner that runs on a background thread.
227    Call .start(message) and .stop() around blocking work.
228    """
229
230    DEFAULT_VERBS = [
231        "thinking",
232        "vibing",
233        "pontificating",
234        "contemplating",
235        "deliberating",
236        "cogitating",
237        "ruminating",
238        "musing",
239        "ideating",
240        "postulating",
241        "hypothesizing",
242        "extrapolating",
243        "philosophizing",
244        "noodling",
245        "percolating",
246        "marinating",
247        "stewing",
248        "scheming",
249        "conniving",
250        "divining",
251        "spelunking",
252        "ratiocinating",
253        "cerebrating",
254        "woolgathering",
255        "daydreaming",
256        "lucubrating",
257        "excogitating",
258        "thinkulating",
259        "brainwaving",
260        "cogitronning",
261        "synapsing",
262        "thoughtcrafting",
263        "mindweaving",
264        "intellectualizing",
265        "computating",
266        "ponderizing",
267        "mentalating",
268        "brainbrewing",
269    ]
270
271    def __init__(self) -> None:
272        self._thread: threading.Thread | None = None
273        self._stop_event = threading.Event()
274        self._message = ""
275        self._verb_thread: threading.Thread | None = None
276        self._running = False
277        self._frames = Spinner.BRAILLE
278
279    # ------------------------------------------------------------------
280    # Public API
281    # ------------------------------------------------------------------
282
283    def start(
284        self,
285        message: str | None = None,
286        spinner: list[str] | None = None,
287    ) -> None:
288        """
289        Start the spinner.
290
291        Optional:
292
293        - ``message``:
294            - Type: str | None
295            - What: Text displayed beside the spinner frame.
296            - Default: None (keeps previous message)
297
298        - ``spinner``:
299            - Type: list[str] | None
300            - What: Spinner Frames to use
301            - Default: None (Braille)
302        """
303        if self._thread and self._thread.is_alive():
304            self.stop()
305        self._running = True
306        self._stop_event.clear()
307        if spinner is not None:
308            self._frames = spinner
309        if message:
310            self._message = message
311        self._thread = threading.Thread(target=self._spin, daemon=True)
312        self._thread.start()
313
314    def start_with_verbs(
315        self,
316        name: str,
317        verbs: list[str] | None = None,
318        interval: float = 10.0,
319        spinner: list[str] | None = None,
320    ) -> None:
321        """
322        Start the spinner with a cycling verb message: "<name> is <verb>".
323        The verb rotates through `verbs` every `interval` seconds.
324
325        Requires:
326
327        - `name`:
328            - Type: str
329            - What: The subject displayed before the verb (e.g. "Claude")
330
331        Optional:
332
333        - `verbs`:
334            - Type: list[str] | None
335            - What: Verbs to cycle through. Defaults to CliSpinner.DEFAULT_VERBS
336            - Default: None
337
338        - `interval`:
339            - Type: float
340            - What: Seconds between each verb swap
341            - Default: 10.0
342
343        - `spinner`:
344            - Type: list[str] | None
345            - What: Frame list or None to not change.
346            - Default: None
347        """
348        verbs = verbs if verbs is not None else self.DEFAULT_VERBS
349
350        def _get_random_message():
351            idx = random.randrange(len(verbs))
352            return f"{name} is {verbs[idx]}"
353
354        def _get_random_spinner():
355            options = [
356                Spinner.ARC,
357                Spinner.CIRCLE_ARCS,
358                Spinner.CIRCLE_FILL,
359                Spinner.LINE,
360                Spinner.DOT_PULSE,
361                Spinner.BOUNCE,
362                Spinner.BLOCK,
363            ]
364            idx = random.randrange(len(options))
365            return options[idx]
366
367        self.start(_get_random_message(), spinner=_get_random_spinner())
368
369        def _verb_cycle() -> None:
370            while not self._stop_event.wait(timeout=interval):
371                # Update message and spinner frames directly instead of
372                # calling start(), which would call stop() and try to
373                # join this thread — causing "cannot join current thread".
374                self._message = _get_random_message()
375                self._frames = _get_random_spinner()
376
377        self._verb_thread = threading.Thread(target=_verb_cycle, daemon=True)
378        self._verb_thread.start()
379
380    def stop(self, final_message: str | None = None) -> None:
381        was_running = self._running
382        self._running = False
383        self._stop_event.set()
384        if self._thread and self._thread.is_alive():
385            self._thread.join()
386        self._thread = None
387        # Don't join verb_thread if we're being called from within it —
388        # that would raise "cannot join current thread".
389        if (
390            self._verb_thread
391            and self._verb_thread.is_alive()
392            and self._verb_thread is not threading.current_thread()
393        ):
394            self._verb_thread.join()
395        self._verb_thread = None
396        sys.stdout.write("\r\033[2K")
397        sys.stdout.flush()
398        if final_message:
399            print(final_message)
400        return was_running
401
402    def _spin(self) -> None:
403        frame_idx = 0
404        color_idx = 0
405        dot_count = 0
406        frames = self._frames  # snapshot so swaps don't mid-spin
407        while not self._stop_event.is_set():
408            frame = frames[frame_idx % len(frames)]
409            colors = theme.spinner_colors
410            color = colors[color_idx % len(colors)]
411            dots = "." * (dot_count % 4)
412
413            visible_content = f"  {frame}  {self._message}{dots:<3}"
414            padding = max(0, 60 - _visible_len(visible_content)) * " "
415            line = (
416                f"\r  {color}{theme.bold}{frame}{theme.reset}  "
417                f"{theme.body}{self._message}{theme.chrome}{dots:<3}{theme.reset}"
418                f"{padding}"
419            )
420            sys.stdout.write(line)
421            sys.stdout.flush()
422
423            time.sleep(0.12)
424            frame_idx += 1
425            if frame_idx % 5 == 0:
426                dot_count += 1
427            if frame_idx % 20 == 0:
428                color_idx += 1
429
430            # Re-read frames each tick so verb-cycle updates take effect
431            frames = self._frames
432
433
434class CliPrinter:
435    @staticmethod
436    def divider(
437        char: str = "─", width: int = 60, color: str | None = None
438    ) -> None:
439        color = color if color is not None else theme.accent
440        print(f"{color}{char * width}{theme.reset}")
441
442    @staticmethod
443    def empty_line() -> None:
444        """Create an empty line for spacing."""
445        print()
446
447    @staticmethod
448    def header(label: str) -> None:
449        inner = (
450            f"  {theme.accent}{theme.bold}Spych{theme.reset}"
451            f": {theme.body}{label}{theme.reset}"
452        )
453        pad = max(0, 58 - _visible_len(inner))
454        print(
455            f"\n{theme.chrome}┌{'─' * 58}┐{theme.reset}\n"
456            f"{theme.chrome}│{theme.reset}{inner}{theme.reset}"
457            f"{' ' * pad}{theme.chrome}│{theme.reset}\n"
458            f"{theme.chrome}└{'─' * 58}┘{theme.reset}"
459        )
460
461    @staticmethod
462    def kwarg_inputs(**kwargs) -> None:
463        for key, value in kwargs.items():
464            print(
465                f"  {theme.accent}{key}{theme.reset}: {theme.body}{value}{theme.reset}"
466            )
467
468    @staticmethod
469    def label(tag: str, text: str, color: str | None = None) -> None:
470        color = color if color is not None else theme.accent
471        print(
472            f"  {color}{theme.bold}{tag}{theme.reset} {theme.body}{text}{theme.reset}"
473        )
474
475    @staticmethod
476    def tool_event(
477        tool_name: str,
478        status: str,
479        is_running: bool = False,
480        elapsed: float | None = None,
481    ) -> None:
482        icon = "⚙" if is_running else "✓"
483        color = theme.running if is_running else theme.success
484        elapsed_str = (
485            f" {theme.chrome}({elapsed:.2f}s){theme.reset}" if elapsed else ""
486        )
487        print(
488            f"  {color}{icon}{theme.reset}  {theme.dim}tool:{theme.reset} "
489            f"{theme.italic}{tool_name}{theme.reset} -> {theme.chrome}{status}{elapsed_str}"
490        )
491
492    @staticmethod
493    def info(message: str, color: str | None = None) -> None:
494        """
495        Usage:
496
497        - Print a single informational line. Useful from inside respond() to
498          surface status updates without touching the spinner directly.
499
500        Requires:
501
502        - `message`:
503            - Type: str
504            - What: The message to print
505
506        Optional:
507
508        - `color`:
509            - Type: str (ANSI escape code)
510            - What: ANSI color code for the message. Defaults to theme accent.
511            - Default: None
512        """
513        color = color if color is not None else theme.accent
514        print(
515            f"  {color}{theme.bold}i{theme.reset}  {theme.body}{message}{theme.reset}"
516        )
517
518    @staticmethod
519    def typewrite(text: str, delay: float = 0.008) -> None:
520        """Print text with a subtle typewriter effect."""
521        for ch in text:
522            sys.stdout.write(ch)
523            sys.stdout.flush()
524            time.sleep(delay)
525        print()
526
527    @staticmethod
528    def print_response(name: str, text: str) -> None:
529        """Render the final response with light formatting."""
530        print(f"  {theme.highlight}{theme.bold}{name}:{theme.reset}")
531        print()
532        print(text)
533
534    @staticmethod
535    def print_status(name: str, success: bool, elapsed: float) -> None:
536        icon = "✓" if success else "✗"
537        color = theme.success if success else theme.error
538        print(
539            f"\n  {color}{icon}{theme.reset} {theme.dim}{name} {elapsed:.2f}s{theme.reset}"
540        )