claude-smart 0.2.42 → 0.2.44

package/plugin/vendor/reflexio/reflexio/cli/errors.py

@@ -0,0 +1,217 @@
+"""Structured error handling for Reflexio CLI."""
+
+from __future__ import annotations
+
+import contextlib
+import functools
+import json
+import sys
+from typing import Any
+
+import requests
+from pydantic import ValidationError
+
+# Semantic exit codes (modeled on Lark CLI)
+EXIT_SUCCESS = 0
+EXIT_GENERAL = 1
+EXIT_VALIDATION = 2
+EXIT_AUTH = 3
+EXIT_NETWORK = 4
+
+
+class CliError(Exception):
+    """Structured CLI error with type, message, hint, and exit code.
+
+    Args:
+        error_type: Category of error (general, validation, auth, network, rate_limit)
+        message: Human-readable error description
+        hint: Actionable suggestion for fixing the error
+        exit_code: Process exit code (0-4)
+    """
+
+    def __init__(
+        self,
+        error_type: str = "general",
+        message: str = "An error occurred",
+        hint: str | None = None,
+        exit_code: int = EXIT_GENERAL,
+    ) -> None:
+        super().__init__(message)
+        self.error_type = error_type
+        self.message = message
+        self.hint = hint
+        self.exit_code = exit_code
+
+
+def _classify_http_error(exc: requests.HTTPError) -> CliError:
+    """Map HTTP status codes to structured CliError instances.
+
+    Args:
+        exc: The HTTP error to classify
+
+    Returns:
+        CliError: Classified error with appropriate type, hint, and exit code
+    """
+    status = exc.response.status_code if exc.response is not None else 0
+
+    if status in (401, 403):
+        return CliError(
+            error_type="auth",
+            message=f"Authentication failed (HTTP {status})",
+            hint="Run: reflexio auth login --api-key <key> --server-url <url>",
+            exit_code=EXIT_AUTH,
+        )
+    if status == 422:
+        detail = ""
+        with contextlib.suppress(ValueError, AttributeError):
+            detail = exc.response.json().get("detail", "")
+        return CliError(
+            error_type="validation",
+            message=f"Invalid request: {detail or exc}",
+            exit_code=EXIT_VALIDATION,
+        )
+    if status == 429:
+        return CliError(
+            error_type="rate_limit",
+            message="Rate limit exceeded",
+            hint="Wait a moment and retry",
+            exit_code=EXIT_GENERAL,
+        )
+    return CliError(
+        error_type="general",
+        message=f"HTTP error: {exc}",
+        exit_code=EXIT_GENERAL,
+    )
+
+
+def raise_if_failed(resp: object, default: str = "operation failed") -> None:
+    """Raise a ``CliError`` if the API response envelope reports failure.
+
+    Intended for CLI mutation commands (``add`` / ``update`` /
+    ``update-status``) so that ``success=False`` envelopes do not get
+    reported as a success. The server's response schemas use either
+    ``message`` or ``msg`` for the human-readable error string; both
+    are checked. Call only in non-JSON mode — JSON-mode callers
+    introspect the response envelope themselves.
+
+    Args:
+        resp: Response object returned by the client.
+        default: Fallback message when neither ``message`` nor ``msg`` is set.
+
+    Raises:
+        CliError: If ``resp.success`` is falsy. The wrapped
+            ``handle_errors`` decorator will render the error and
+            exit with ``EXIT_GENERAL``.
+    """
+    if getattr(resp, "success", True):
+        return
+    message = getattr(resp, "message", None) or getattr(resp, "msg", None) or default
+    raise CliError(
+        error_type="api",
+        message=message,
+        exit_code=EXIT_GENERAL,
+    )
+
+
+def render_error(error: CliError, json_mode: bool = False) -> None:
+    """Render an error to stderr in structured or human-readable format.
+
+    Args:
+        error: The CLI error to render
+        json_mode: If True, output JSON envelope; otherwise plain text
+    """
+    if json_mode:
+        envelope: dict[str, Any] = {
+            "ok": False,
+            "error": {
+                "type": error.error_type,
+                "message": error.message,
+            },
+        }
+        if error.hint:
+            envelope["error"]["hint"] = error.hint
+        print(json.dumps(envelope, indent=2), file=sys.stderr)
+    else:
+        print(f"Error: {error.message}", file=sys.stderr)
+        if error.hint:
+            print(f"Hint: {error.hint}", file=sys.stderr)
+
+
+def handle_errors(fn):  # noqa: ANN001, ANN201
+    """Decorator that catches common exceptions and renders structured errors.
+
+    Catches ``CliError``, ``ConnectionError``, ``HTTPError``, and the
+    client's ``ReflexioAPIError`` (for "2xx with non-JSON body"
+    failures, typically a misconfigured ``REFLEXIO_URL`` pointing at a
+    marketing site or misrouting proxy), rendering them through the
+    structured error system before exiting with the appropriate code.
+    """
+    # Imported lazily to avoid a circular import: client.py → cli.output
+    # → cli.errors. The import only fires when the decorator is built.
+    from reflexio.client.client import ReflexioAPIError
+
+    @functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        # Determine json_mode from context if available
+        import typer
+
+        ctx = None
+        for arg in args:
+            if isinstance(arg, typer.Context):
+                ctx = arg
+                break
+
+        json_mode = False
+        if ctx and ctx.obj:
+            json_mode = getattr(ctx.obj, "json_mode", False)
+
+        try:
+            return fn(*args, **kwargs)
+        except CliError as exc:
+            # CliError must be caught first so its subclasses don't
+            # get swallowed by the generic ValueError branch below.
+            render_error(exc, json_mode=json_mode)
+            raise SystemExit(exc.exit_code) from None
+        except ValidationError as exc:
+            err = CliError(
+                error_type="validation",
+                message=str(exc),
+                exit_code=EXIT_VALIDATION,
+            )
+            render_error(err, json_mode=json_mode)
+            raise SystemExit(err.exit_code) from None
+        except ValueError as exc:
+            err = CliError(
+                error_type="validation",
+                message=str(exc),
+                exit_code=EXIT_VALIDATION,
+            )
+            render_error(err, json_mode=json_mode)
+            raise SystemExit(err.exit_code) from None
+        except requests.ConnectionError as exc:
+            err = CliError(
+                error_type="network",
+                message=f"Connection failed: {exc}",
+                hint="Is the Reflexio server running? Try: reflexio services start",
+                exit_code=EXIT_NETWORK,
+            )
+            render_error(err, json_mode=json_mode)
+            raise SystemExit(err.exit_code) from None
+        except requests.HTTPError as exc:
+            err = _classify_http_error(exc)
+            render_error(err, json_mode=json_mode)
+            raise SystemExit(err.exit_code) from None
+        except ReflexioAPIError as exc:
+            err = CliError(
+                error_type="api",
+                message=str(exc),
+                hint=(
+                    "Double-check REFLEXIO_URL — it should point at your "
+                    "Reflexio API host, not a marketing site or proxy."
+                ),
+                exit_code=EXIT_GENERAL,
+            )
+            render_error(err, json_mode=json_mode)
+            raise SystemExit(err.exit_code) from None
+
+    return wrapper

package/plugin/vendor/reflexio/reflexio/cli/log_format.py

@@ -0,0 +1,247 @@
+"""Log formatting utilities for the dev server.
+
+Provides colored service prefixes for subprocess output, a duplicate log filter,
+and a startup banner for the multi-service dev server.
+"""
+
+from __future__ import annotations
+
+import itertools
+import logging
+import re
+import sys
+import threading
+import time
+from pathlib import Path
+
+# ANSI color codes for service prefixes
+SERVICE_COLORS: dict[str, str] = {
+    "backend": "34",  # blue
+    "frontend": "32",  # green
+    "docs": "35",  # magenta
+    "supabase": "36",  # cyan
+}
+
+# ANSI codes for log-level severity highlighting in service output.
+# Keys are matched against the level token captured by `_LEVEL_RE`.
+_LEVEL_COLORS: dict[str, str] = {
+    "ERROR": "31",  # red
+    "CRITICAL": "1;31",  # bold red
+    "WARNING": "33",  # yellow
+    "WARN": "33",  # yellow (Next.js / some loggers)
+}
+
+# Match a log-level token at the start of a line, optionally bracketed,
+# followed by a typical separator (":", whitespace, or " - "). Covers
+# uvicorn ("ERROR:    msg"), stdlib logging ("[ERROR] msg"), and the
+# "ERROR - msg" style used by Next.js / some custom loggers.
+_LEVEL_RE = re.compile(r"^(?:\[)?(ERROR|CRITICAL|WARNING|WARN)(?:\])?(?::|\s+-\s+|\s+)")
+
+
+# Canonical log file paths.
+# Default: ~/.reflexio/logs/. The REFLEXIO_LOG_DIR env var overrides only the
+# base directory (the ~ part) — the .reflexio/logs suffix is preserved so the
+# on-disk layout stays consistent regardless of where the base points. Base
+# resolution is delegated to ``reflexio_home`` so every ``~/.reflexio/*`` path
+# honors the env var identically.
+def _resolve_log_dir() -> Path:
+    """Return the directory log files are written to.
+
+    Resolved at module import time so the public ``DEV_LOG_FILE`` /
+    ``LLM_IO_LOG_FILE`` constants are stable across a server's lifetime —
+    change requires a restart.
+
+    Returns:
+        Path: Resolved log directory. Not created here — callers must
+            ``mkdir(parents=True, exist_ok=True)`` before opening any
+            file handler against ``DEV_LOG_FILE`` / ``LLM_IO_LOG_FILE``.
+    """
+    from .paths import reflexio_home
+
+    return reflexio_home() / "logs"
+
+
+LOG_DIR: Path = _resolve_log_dir()
+DEV_LOG_FILE: str = str(LOG_DIR / "dev_server.log")
+LLM_IO_LOG_FILE: str = str(LOG_DIR / "llm_io.log")
+
+# Thread-safe sequential entry counter for LLM prompt/response entries
+_llm_entry_counter = itertools.count(1)
+_llm_entry_lock = threading.Lock()
+
+
+def next_llm_entry_id() -> int:
+    """Get the next sequential LLM log entry ID (thread-safe)."""
+    with _llm_entry_lock:
+        return next(_llm_entry_counter)
+
+
+# Fixed-width for service prefix alignment
+_PREFIX_WIDTH = 10
+
+
+def colorize(text: str, ansi_code: str, *, bold: bool = False) -> str:
+    """Wrap text in ANSI escape sequences for terminal color.
+
+    Returns raw text when stdout is not a TTY (piped output, log files),
+    keeping output clean for AI agents and file parsing.
+
+    Args:
+        text: The text to colorize.
+        ansi_code: ANSI color code (e.g., "34" for blue).
+        bold: If True, also apply bold formatting.
+
+    Returns:
+        str: Colorized text if TTY, raw text otherwise.
+    """
+    if not sys.stdout.isatty():
+        return text
+    prefix = f"\033[1;{ansi_code}m" if bold else f"\033[{ansi_code}m"
+    return f"{prefix}{text}\033[0m"
+
+
+def highlight_log_level(line: str) -> str:
+    """Wrap a line in a severity color if it starts with a log-level token.
+
+    Supports common formats: ``ERROR: msg``, ``[ERROR] msg``, ``ERROR - msg``.
+    Returns the line unchanged when stdout is not a TTY or no level matches,
+    keeping output clean for pipes, log files, and AI agents.
+
+    Args:
+        line: The log line content (without the service prefix).
+
+    Returns:
+        str: Color-wrapped line for ERROR/CRITICAL/WARNING; otherwise unchanged.
+    """
+    if not sys.stdout.isatty():
+        return line
+    match = _LEVEL_RE.match(line)
+    if not match:
+        return line
+    code = _LEVEL_COLORS[match.group(1)]
+    return f"\033[{code}m{line}\033[0m"
+
+
+def format_service_line(service_name: str, line: str) -> str:
+    """Format a log line with a colored, fixed-width service prefix.
+
+    The line body is additionally wrapped in a severity color when it
+    starts with a recognised log-level token (ERROR/CRITICAL/WARNING),
+    so failures stand out against the scrolling dev-server output.
+
+    Args:
+        service_name: Name of the service (e.g., "backend", "frontend").
+        line: The log line content.
+
+    Returns:
+        str: Formatted line like "[backend ] message".
+    """
+    color = SERVICE_COLORS.get(service_name, "37")  # default white
+    padded = service_name.ljust(_PREFIX_WIDTH - 2)  # -2 for brackets
+    prefix = colorize(f"[{padded}]", color)
+    return f"{prefix} {highlight_log_level(line)}"
+
+
+class DuplicateFilter(logging.Filter):
+    """Suppress duplicate log messages within a time window.
+
+    Keys on (logger_name, msg_template) — the message template string,
+    not the formatted output. This is stable across different args since
+    the template (e.g., "Supabase Storage for org %s uses URL %s") doesn't
+    change between calls.
+
+    Args:
+        window_seconds: Time window in seconds to suppress duplicates.
+    """
+
+    def __init__(self, window_seconds: int = 5) -> None:
+        super().__init__()
+        self._recent: dict[tuple[str, str], float] = {}
+        self._window = window_seconds
+        self._lock = threading.Lock()
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        """Return False to suppress duplicate messages within the time window."""
+        # record.msg can be any object (callers sometimes pass a list/dict
+        # directly to logger.warning). Stringify so the key is always
+        # hashable — otherwise this filter raises TypeError and crashes
+        # whatever was being logged. Surfaced via the Nomic embedder
+        # pre-warm path that calls logger.warning(load_return_list).
+        key = (record.name, str(record.msg))
+        now = time.monotonic()
+
+        with self._lock:
+            # Evict stale entries periodically (every 100 checks)
+            if len(self._recent) > 200:
+                cutoff = now - self._window
+                self._recent = {k: v for k, v in self._recent.items() if v >= cutoff}
+
+            last_seen = self._recent.get(key)
+            if last_seen is not None and now - last_seen < self._window:
+                return False
+            self._recent[key] = now
+            return True
+
+
+def print_startup_banner(
+    ports: dict[str, int],
+    *,
+    supabase_port: int | None = 54321,
+    log_file: str = DEV_LOG_FILE,
+    config_paths: dict[str, str] | None = None,
+) -> None:
+    """Print a consolidated startup summary banner with service URLs.
+
+    Args:
+        ports: Mapping of service name to port number.
+        supabase_port: Supabase port, or None if not running.
+        log_file: Path to the log file.
+        config_paths: Optional mapping of config-label → path string (e.g.
+            ``{"env": "~/.reflexio/.env", "config": "~/.reflexio/configs/config_default.json"}``).
+            Renders as a "Config" section above the "Logs" line so operators
+            can see at a glance which files the server actually loaded.
+    """
+    lines = []
+    width = 44
+
+    lines.append(f"\n{'=' * width}")
+    lines.append(colorize("  Reflexio Dev Server", "1", bold=True))
+    lines.append(f"{'-' * width}")
+
+    for name in ("backend", "frontend", "docs"):
+        if name in ports:
+            url = f"http://localhost:{ports[name]}"
+            color = SERVICE_COLORS.get(name, "37")
+            label = colorize(f"  {name.capitalize():<11}", color)
+            status = colorize("ready", "32")
+            lines.append(f"{label}{url:<26}{status}")
+
+    if supabase_port is not None:
+        url = f"http://localhost:{supabase_port}"
+        label = colorize("  Supabase   ", "36")
+        status = colorize("ready", "32")
+        lines.append(f"{label}{url:<26}{status}")
+
+    home = str(Path.home())
+
+    def _collapse_home(path: str) -> str:
+        # Collapse HOME to ~ for readability; absolute paths stay absolute
+        # so log scrapers and copy-paste still work when outside HOME.
+        return "~" + path[len(home) :] if path.startswith(home) else path
+
+    if config_paths:
+        lines.append(f"{'-' * width}")
+        for label, path in config_paths.items():
+            lines.append(f"  {label:<11}{_collapse_home(str(path))}")
+
+    lines.append(f"{'-' * width}")
+    # Logs section — surface both the general dev log and the LLM I/O log.
+    # LLM_IO_LOG_FILE is the one operators hit first when debugging prompt /
+    # tool-call issues; it's opaque without this pointer.
+    lines.append(f"  Dev log    {_collapse_home(log_file)}")
+    lines.append(f"  LLM I/O    {_collapse_home(LLM_IO_LOG_FILE)}")
+    lines.append(f"{'=' * width}\n")
+
+    # Print all at once to avoid interleaving
+    sys.stdout.write("\n".join(lines) + "\n")
+    sys.stdout.flush()