shellmate-cli 3.0.0__py3-none-any.whl

shellmate/ui/annotations.py

@@ -0,0 +1,232 @@
+"""Inline annotation formatting for autocomplete mode."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+# Emoji mappings for risk levels (short inline / Unix terminals)
+RISK_ICONS = {
+    "SAFE": "✅",
+    "LOW": "ℹ️",
+    "MEDIUM": "⚠️",
+    "HIGH": "🔥",
+    "CRITICAL": "⛔",
+}
+
+# ASCII-safe risk icons (Windows PS 5.1 / constrained consoles)
+RISK_ICONS_ASCII = {
+    "SAFE": "[OK]",
+    "LOW": "[i]",
+    "MEDIUM": "[!]",
+    "HIGH": "[!!]",
+    "CRITICAL": "[X]",
+}
+
+SEVERITY_ICONS = {
+    "blocking": "🔥",
+    "warning": "⚠️",
+    "info": "ℹ️",
+}
+
+SEVERITY_ICONS_ASCII = {
+    "blocking": "[X]",
+    "warning": "[!]",
+    "info": "[i]",
+}
+
+# Environment badges (emoji form for short annotations)
+ENV_BADGES = {
+    "production": "🏭",
+    "staging": "🧪",
+    "ci": "🤖",
+    "development": "💻",
+}
+
+# Text badges used in consequence / pipeline annotations (cross-platform)
+ENV_TEXT_BADGES = {
+    "production": "[PROD]",
+    "staging": "[STAGE]",
+    "development": "[DEV]",
+    "ci": "[CI]",
+}
+
+# Time context badges
+TIME_BADGES = {
+    "business_hours": "⏰",
+    "after_hours": "🌙",
+}
+
+
+def format_annotation(
+    risk_analysis: Dict[str, Any],
+    environment_context: Optional[Dict[str, Any]] = None,
+    max_chars: int = 30,
+    *,
+    ascii_safe: bool = False,
+) -> str:
+    """
+    Format risk analysis into a short inline annotation.
+
+    Returns e.g. "🔥 rewrites history 🏭⏰" (truncated to max_chars).
+    """
+    severity = risk_analysis.get("severity") or risk_analysis.get("risk", "MEDIUM")
+    reason = risk_analysis.get("reason", "")
+
+    icons = RISK_ICONS_ASCII if ascii_safe else RISK_ICONS
+    parts = [icons.get(severity, "[!]" if ascii_safe else "⚠️")]
+
+    if reason:
+        short_reason = reason[:20] if len(reason) > 20 else reason
+        parts.append(short_reason)
+
+    if environment_context:
+        env_type = environment_context.get("type")
+        if ascii_safe:
+            if env_type in ENV_TEXT_BADGES:
+                parts.append(ENV_TEXT_BADGES[env_type])
+        elif env_type in ENV_BADGES:
+            parts.append(ENV_BADGES[env_type])
+
+        time_ctx = environment_context.get("time", {}) or {}
+        if time_ctx:
+            if time_ctx.get("is_business_hours"):
+                parts.append("BH" if ascii_safe else TIME_BADGES["business_hours"])
+            elif time_ctx.get("after_hours") or time_ctx.get("is_business_hours") is False:
+                parts.append("AH" if ascii_safe else TIME_BADGES["after_hours"])
+
+    annotation = " ".join(parts)
+    return annotation[:max_chars]
+
+
+def format_consequence_annotation(
+    consequence: Dict[str, Any],
+    env_context: Optional[Dict[str, Any]] = None,
+    chain_patterns: Optional[Dict[str, Any]] = None,
+    risk: str = "MEDIUM",
+    *,
+    ascii_safe: bool = False,
+) -> str:
+    """Format annotation using structured consequence preview + badges."""
+    env_context = env_context or {}
+    chain_patterns = chain_patterns or {}
+
+    severity = consequence.get("severity", "warning")
+    icons = SEVERITY_ICONS_ASCII if ascii_safe else SEVERITY_ICONS
+    icon = icons.get(severity)
+    if not icon:
+        risk_icons = RISK_ICONS_ASCII if ascii_safe else RISK_ICONS
+        icon = risk_icons.get(risk, "[!]" if ascii_safe else "ℹ️")
+
+    parts = [icon]
+
+    env_type = env_context.get("type", "")
+    if env_type in ENV_TEXT_BADGES:
+        parts.append(ENV_TEXT_BADGES[env_type])
+
+    if chain_patterns.get("broken", []):
+        parts.append("[BROKEN]")
+    elif chain_patterns.get("dangerous_escalations", []):
+        parts.append("[ESCALATION]")
+
+    what = consequence.get("what_happens", "") or ""
+    if what:
+        if len(what) > 50:
+            what = what[:47] + "..."
+        parts.append(what)
+
+    if not consequence.get("reversible", True):
+        parts.append("[IRREVERSIBLE]")
+
+    return " ".join(parts) if len(parts) > 1 else ""
+
+
+def format_legacy_pipeline_annotation(
+    risk_result: Dict[str, Any],
+    env_context: Optional[Dict[str, Any]] = None,
+    chain_patterns: Optional[Dict[str, Any]] = None,
+    *,
+    ascii_safe: bool = False,
+) -> str:
+    """Format annotation from pipeline result without consequence_preview."""
+    env_context = env_context or {}
+    chain_patterns = chain_patterns or {}
+
+    risk_analysis = risk_result.get("risk_analysis", {}) or {}
+    msg = risk_analysis.get("reason", risk_result.get("message", "")) or ""
+    risk = risk_result.get("risk", "MEDIUM")
+
+    icons = RISK_ICONS_ASCII if ascii_safe else RISK_ICONS
+    # Map HIGH->🔥 style: prefer risk-level icons; CRITICAL uses ⛔ in short form
+    # Pipeline historically used 🔥 for CRITICAL — keep that for non-ascii.
+    if not ascii_safe:
+        pipeline_icons = {
+            "CRITICAL": "🔥",
+            "HIGH": "⚠️",
+            "MEDIUM": "ℹ️",
+            "LOW": "✓",
+            "SAFE": "✓",
+        }
+        icon = pipeline_icons.get(risk, "ℹ️")
+    else:
+        icon = icons.get(risk, "[i]")
+
+    parts = [icon]
+
+    env_type = env_context.get("type", "")
+    if env_type in ENV_TEXT_BADGES:
+        parts.append(ENV_TEXT_BADGES[env_type])
+
+    if chain_patterns.get("broken", []):
+        parts.append("[BROKEN-WORKFLOW]")
+    elif chain_patterns.get("dangerous_escalations", []):
+        parts.append("[ESCALATION]")
+
+    if msg:
+        if len(msg) > 40:
+            msg = msg[:37] + "..."
+        parts.append(msg)
+
+    return " ".join(parts) if len(parts) > 1 else ""
+
+
+def format_pipeline_annotation(
+    risk_result: Dict[str, Any],
+    env_context: Optional[Dict[str, Any]] = None,
+    chain_patterns: Optional[Dict[str, Any]] = None,
+    *,
+    ascii_safe: bool = False,
+) -> str:
+    """Prefer consequence_preview; fall back to legacy pipeline formatting."""
+    consequence = risk_result.get("consequence_preview") or {}
+    if consequence.get("what_happens"):
+        return format_consequence_annotation(
+            consequence,
+            env_context,
+            chain_patterns,
+            risk_result.get("risk", "MEDIUM"),
+            ascii_safe=ascii_safe,
+        )
+    return format_legacy_pipeline_annotation(
+        risk_result, env_context, chain_patterns, ascii_safe=ascii_safe
+    )
+
+
+def format_cached_annotation(cached_result: Dict[str, Any], *, ascii_safe: bool = False) -> str:
+    """Format a simple annotation from a cache hit payload."""
+    msg = cached_result.get("explanation", "") or ""
+    risk = cached_result.get("risk", "MEDIUM")
+    if ascii_safe:
+        icon = RISK_ICONS_ASCII.get(risk, "[i]")
+    else:
+        icons = {
+            "CRITICAL": "🔥",
+            "HIGH": "⚠️",
+            "MEDIUM": "ℹ️",
+            "LOW": "✓",
+            "SAFE": "✓",
+        }
+        icon = icons.get(risk, "ℹ️")
+
+    if len(msg) > 50:
+        msg = msg[:47] + "..."
+    return f"{icon} {msg}" if msg else ""

shellmate/ui/banner.py

@@ -0,0 +1,49 @@
+from rich.console import Console
+from rich.text import Text
+from rich.panel import Panel
+
+from shellmate.cli.version import VERSION
+from shellmate.ui.runtime import tokens
+from shellmate.ui.runtime.console_factory import ConsoleFactory
+from shellmate.ui.scenes.help import print_help, render_help
+
+console = ConsoleFactory().create()
+
+# Kept for any external imports; enable scene uses its own compact logo.
+BANNER_ART = "[bold cyan]ShellMate[/]"
+
+
+def print_banner():
+    """Minimal wordmark banner (no giant ASCII). Bold logo lives on sm enable only."""
+    width = tokens.content_width(console.width)
+    body = Text.assemble(
+        Text("ShellMate", style=f"bold {tokens.ACCENT}"),
+        Text(f"  v{VERSION}", style=tokens.MUTED),
+        Text("\n"),
+        Text("Intelligent command safety layer", style=tokens.MUTED),
+    )
+    console.print(
+        Panel(body, border_style=tokens.ACCENT, padding=(1, 2), width=width, expand=False)
+    )
+
+
+def render_enable_panel(stages: list[tuple[str, bool]]) -> Panel:
+    """Deprecated compatibility wrapper — prefer ui.scenes.enable.render_enable_frame."""
+    from shellmate.ui.scenes.stages import StageStatus, StageView, EnableViewState
+    from shellmate.ui.scenes.enable import render_enable_frame
+
+    views = [
+        StageView(
+            key=label,
+            label=label,
+            status=StageStatus.DONE if done else StageStatus.INCOMPLETE,
+        )
+        for label, done in stages
+    ]
+    state = EnableViewState(stages=views, ready=all(d for _, d in stages), timed_out=not all(d for _, d in stages))
+    frame = render_enable_frame(state, console_width=console.width, settled=True)
+    return frame  # type: ignore[return-value]
+
+
+def print_usage():
+    print_help(console)

shellmate/ui/progress.py

@@ -0,0 +1,126 @@
+import time
+import threading
+from contextlib import contextmanager
+from rich.console import Console
+from rich.status import Status
+from rich.live import Live
+from rich.table import Table
+from rich.panel import Panel
+from rich import box
+
+from shellmate.ui.runtime import tokens
+
+STAGES = [
+    (">  Routing command...", "dots12"),
+    ("*  Gathering context...", "dots12"),
+    ("*  Analyzing risk...", "dots12"),
+    (">  Building usage guide...", "dots12"),
+    ("*  Formatting result...", "dots12"),
+]
+
+STAGE_TIMINGS = {
+    "sanitizer": 2,
+    "parser": 5,
+    "rules": 10,
+    "cache": 1,
+    "command_chain": 10,
+    "supervisor": 50,
+    "watcher": 200,
+    "environment": 30,
+    "librarian": 300,
+    "risk_analyzer": 200,
+    "remediation": 150,
+    "command_guide": 100,
+    "formatter": 5,
+    "query_agent": 100,
+}
+
+
+@contextmanager
+def analysis_progress(console: Console, interval: float = 0.4, verbose: bool = False):
+    """Progress indicator with optional live agent view."""
+    # Plain / non-TTY: no animation
+    if not console.is_terminal or console.no_color:
+        yield
+        return
+
+    if verbose:
+        with _live_progress_table(console):
+            yield
+    else:
+        stop = threading.Event()
+        idx = [0]
+
+        def cycle(status: Status):
+            while not stop.is_set():
+                text, spinner = STAGES[idx[0] % len(STAGES)]
+                status.update(text, spinner=spinner)
+                idx[0] += 1
+                stop.wait(interval)
+
+        with console.status(STAGES[0][0], spinner=STAGES[0][1]) as status:
+            t = threading.Thread(target=cycle, args=(status,), daemon=True)
+            t.start()
+            try:
+                yield
+            finally:
+                stop.set()
+                t.join(timeout=1.0)
+
+
+@contextmanager
+def _live_progress_table(console: Console):
+    icon_map = tokens.icons(ascii_safe=console.no_color)
+    status_icons = {
+        "pending": icon_map["pending"],
+        "running": icon_map["running"],
+        "done": icon_map["done"],
+        "cached": icon_map["done"],
+        "skipped": icon_map["skip"],
+        "error": icon_map["error"],
+    }
+
+    agent_state = {
+        stage: {"status": "pending", "elapsed_ms": 0}
+        for stage in STAGE_TIMINGS.keys()
+    }
+
+    def build_table() -> Panel:
+        table = Table(show_header=True, box=box.SIMPLE, expand=False)
+        table.add_column("Stage", style=tokens.ACCENT, no_wrap=True)
+        table.add_column("Status", style="white", justify="center", width=8)
+        table.add_column("Time", justify="right", style=tokens.WARNING, width=10)
+
+        for stage, data in agent_state.items():
+            status = data["status"]
+            icon = status_icons.get(status, "·")
+            elapsed = f"{data['elapsed_ms']}ms" if data["elapsed_ms"] > 0 else "—"
+            stage_name = stage.replace("_", " ").title()
+            table.add_row(stage_name, icon, elapsed)
+
+        width = tokens.content_width(console.width)
+        return Panel(
+            table,
+            title="[bold]Analysis[/]",
+            border_style=tokens.ACCENT,
+            width=width,
+            expand=False,
+        )
+
+    with Live(build_table(), console=console, refresh_per_second=8, transient=True) as live:
+        try:
+            for stage, duration_ms in STAGE_TIMINGS.items():
+                agent_state[stage]["status"] = "running"
+                live.update(build_table())
+                # Cap simulated waits so verbose mode cannot dominate wall clock
+                time.sleep(min(duration_ms, 40) / 1000.0)
+                agent_state[stage]["status"] = "done"
+                agent_state[stage]["elapsed_ms"] = duration_ms
+                live.update(build_table())
+            yield
+        except KeyboardInterrupt:
+            for stage in agent_state:
+                if agent_state[stage]["status"] == "running":
+                    agent_state[stage]["status"] = "error"
+            live.update(build_table())
+            raise

shellmate/ui/runtime/__init__.py

@@ -0,0 +1,15 @@
+"""Shared Rich presentation runtime for ShellMate CLI scenes."""
+
+from shellmate.ui.runtime.console_factory import ConsoleFactory, is_plain_mode
+from shellmate.ui.runtime.live_scene import LiveScene
+from shellmate.ui.runtime.motion_policy import MotionPolicy, motion_from_env
+from shellmate.ui.runtime import tokens
+
+__all__ = [
+    "ConsoleFactory",
+    "is_plain_mode",
+    "LiveScene",
+    "MotionPolicy",
+    "motion_from_env",
+    "tokens",
+]

shellmate/ui/runtime/console_factory.py

@@ -0,0 +1,65 @@
+"""Console construction with plain-mode detection and real terminal width."""
+
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass
+
+from rich.console import Console
+
+
+def is_plain_mode(
+    *,
+    no_color: bool = False,
+    force_terminal: bool | None = None,
+    environ: dict | None = None,
+    stdout=None,
+) -> bool:
+    """True when animation/color should be disabled.
+
+    Triggers: --no-color, NO_COLOR, CI, or non-TTY stdout.
+    """
+    env = environ if environ is not None else os.environ
+    if no_color:
+        return True
+    if env.get("NO_COLOR", ""):
+        return True
+    if env.get("CI", ""):
+        return True
+    stream = stdout if stdout is not None else sys.stdout
+    if force_terminal is False:
+        return True
+    if force_terminal is True:
+        return False
+    try:
+        return not stream.isatty()
+    except Exception:
+        return True
+
+
+@dataclass
+class ConsoleFactory:
+    no_color: bool = False
+    force_terminal: bool | None = None
+    width: int | None = None
+
+    def is_plain(self) -> bool:
+        return is_plain_mode(no_color=self.no_color, force_terminal=self.force_terminal)
+
+    def create(self) -> Console:
+        plain = self.is_plain()
+        kwargs: dict = {
+            "no_color": plain or self.no_color,
+            "highlight": False,
+        }
+        if self.force_terminal is not None:
+            kwargs["force_terminal"] = self.force_terminal
+        console = Console(**kwargs)
+        # Soft-wrap; never pin 110/120. Optional override via size when provided.
+        if self.width is not None:
+            try:
+                console.width = self.width
+            except Exception:
+                pass
+        return console

shellmate/ui/runtime/live_scene.py

@@ -0,0 +1,116 @@
+"""One Live region per command: morph updates, then settle to a static frame."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from rich.console import Console, RenderableType
+from rich.live import Live
+
+
+class LiveScene:
+    """Owns a single Rich Live (or static printer in plain mode).
+
+    Guarantees: settle shows the final frame once; render failures fall back
+    to static print and never raise to the caller by default.
+    """
+
+    def __init__(self, console: Console, *, plain: bool = False, refresh_per_second: int = 12):
+        self.console = console
+        self.plain = plain
+        self.refresh_per_second = refresh_per_second
+        self._live: Optional[Live] = None
+        self._started = False
+        self._settled = False
+        self._fallback = False
+        self._transient = False
+
+    def start(self, initial: RenderableType) -> None:
+        if self._started:
+            return
+        self._started = True
+        if self.plain:
+            return
+        try:
+            # transient=False so Windows/Cursor terminals keep painting mid-frames.
+            # settle() updates in-place then stops without reprinting a duplicate.
+            self._transient = False
+            self._live = Live(
+                initial,
+                console=self.console,
+                refresh_per_second=self.refresh_per_second,
+                transient=self._transient,
+                auto_refresh=True,
+            )
+            self._live.start()
+            try:
+                self._live.refresh()
+            except Exception:
+                pass
+        except Exception:
+            self._fallback = True
+            self._live = None
+
+    def update(self, renderable: RenderableType) -> None:
+        if self.plain or self._fallback or self._settled:
+            return
+        if self._live is None:
+            return
+        try:
+            self._live.update(renderable, refresh=True)
+        except TypeError:
+            try:
+                self._live.update(renderable)
+                self._live.refresh()
+            except Exception:
+                self._fallback = True
+                self._stop_live_quiet()
+        except Exception:
+            self._fallback = True
+            self._stop_live_quiet()
+
+    def settle(self, final: RenderableType) -> None:
+        """Show the final frame once (in-place if Live is active)."""
+        if self._settled:
+            return
+        self._settled = True
+
+        if self._live is not None and not self._fallback:
+            try:
+                try:
+                    self._live.update(final, refresh=True)
+                except TypeError:
+                    self._live.update(final)
+                    self._live.refresh()
+                # Leave non-transient final frame on screen; do not reprint.
+                self._stop_live_quiet()
+                if self._transient:
+                    self.console.print(final)
+                return
+            except Exception:
+                self._stop_live_quiet()
+
+        try:
+            self.console.print(final)
+        except Exception:
+            try:
+                with self.console.capture() as cap:
+                    self.console.print(final)
+                self.console.print(cap.get())
+            except Exception:
+                pass
+
+    def _stop_live_quiet(self) -> None:
+        if self._live is None:
+            return
+        try:
+            self._live.stop()
+        except Exception:
+            pass
+        self._live = None
+
+    def __enter__(self) -> "LiveScene":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self._stop_live_quiet()

shellmate/ui/runtime/motion_policy.py

@@ -0,0 +1,69 @@
+"""Timing rules for sequential stage reveals (hybrid dwell + artificial cap)."""
+
+from __future__ import annotations
+
+import os
+import time
+from dataclasses import dataclass
+
+
+def motion_from_env(*, plain: bool = False) -> "MotionPolicy":
+    """Build policy; SM_UI_SLOW=1 roughly doubles dwell for demo visibility."""
+    slow = os.environ.get("SM_UI_SLOW", "").strip().lower() in ("1", "true", "yes")
+    if slow:
+        return MotionPolicy(
+            min_dwell_ms=350,
+            stagger_ms=120,
+            max_artificial_ms_after_ready=2800,
+            plain=plain,
+        )
+    return MotionPolicy(
+        min_dwell_ms=180,
+        stagger_ms=70,
+        max_artificial_ms_after_ready=1600,
+        plain=plain,
+    )
+
+
+@dataclass
+class MotionPolicy:
+    """Hybrid timing: short min dwell/stagger, hard cap on artificial wait after ready."""
+
+    min_dwell_ms: int = 180
+    stagger_ms: int = 70
+    max_artificial_ms_after_ready: int = 1600
+    plain: bool = False
+
+    def dwell_seconds(self) -> float:
+        if self.plain:
+            return 0.0
+        return max(0, self.min_dwell_ms) / 1000.0
+
+    def stagger_seconds(self) -> float:
+        if self.plain:
+            return 0.0
+        return max(0, self.stagger_ms) / 1000.0
+
+    def sleep(self, seconds: float) -> None:
+        if self.plain or seconds <= 0:
+            return
+        time.sleep(seconds)
+
+    def clamp_artificial_budget(self, already_spent_ms: float) -> float:
+        """Seconds still allowed for artificial waits after ready was observed."""
+        if self.plain:
+            return 0.0
+        remaining = self.max_artificial_ms_after_ready - already_spent_ms
+        return max(0.0, remaining) / 1000.0
+
+    def play_reveal_delays(self, n_stages: int) -> list[float]:
+        """Per-stage delays for ordered reveal when jumping ahead (e.g. already ready)."""
+        if self.plain or n_stages <= 0:
+            return [0.0] * max(0, n_stages)
+        per = self.dwell_seconds() + self.stagger_seconds()
+        raw_total = per * n_stages
+        budget = self.max_artificial_ms_after_ready / 1000.0
+        if raw_total <= budget or raw_total <= 0:
+            return [per] * n_stages
+        scaled = budget / n_stages
+        return [scaled] * n_stages