aster-cli 0.1.2__py3-none-any.whl

aster_cli/shell/guide.py

@@ -0,0 +1,230 @@
+"""
+aster_cli.shell.guide -- First-time guided tour system.
+
+Provides step-by-step hints for new users, triggered by their actions.
+The tour state is persisted in ~/.aster/config.toml under [shell] so
+it only runs once.
+
+The guide is a sequence of steps, each triggered by a specific event
+(command executed, directory entered, etc.). When a step's trigger fires,
+we show the hint and advance to the next step.
+
+Custom tours can be registered for domain-specific workflows.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable
+
+
+@dataclass
+class TourStep:
+    """A single step in a guided tour."""
+
+    id: str
+    trigger: str  # event name that triggers this step
+    message: str  # rich-formatted hint to display
+    trigger_value: str | None = None  # optional: match on specific value
+
+
+@dataclass
+class Tour:
+    """A guided tour -- a sequence of steps shown to first-time users."""
+
+    name: str
+    steps: list[TourStep] = field(default_factory=list)
+    current_step: int = 0
+
+    @property
+    def is_complete(self) -> bool:
+        return self.current_step >= len(self.steps)
+
+    @property
+    def current(self) -> TourStep | None:
+        if self.is_complete:
+            return None
+        return self.steps[self.current_step]
+
+    def advance(self) -> None:
+        self.current_step += 1
+
+
+# ── Default tour ──────────────────────────────────────────────────────────────
+
+DEFAULT_TOUR = Tour(
+    name="welcome",
+    steps=[
+        TourStep(
+            id="welcome",
+            trigger="connected",
+            message=(
+                "[bold cyan]Welcome to the Aster shell![/bold cyan]\n"
+                "  Try [green]ls[/green] to see what's here."
+            ),
+        ),
+        TourStep(
+            id="after_ls_root",
+            trigger="command",
+            trigger_value="ls",
+            message=(
+                "  You can explore [cyan]services/[/cyan], [cyan]blobs/[/cyan], or [cyan]gossip/[/cyan].\n"
+                "  Try [green]cd services[/green] to browse available RPC services."
+            ),
+        ),
+        TourStep(
+            id="in_services",
+            trigger="cd",
+            trigger_value="/services",
+            message=(
+                "  These are the services on this peer.\n"
+                "  Try [green]ls[/green] to see them, then [green]cd <ServiceName>[/green] to explore one."
+            ),
+        ),
+        TourStep(
+            id="in_service",
+            trigger="cd",
+            trigger_value="/services/*",
+            message=(
+                "  You're inside a service. Try [green]ls[/green] to see its methods.\n"
+                "  You can invoke a method directly: [green]./methodName arg=value[/green]\n"
+                "  Or use [green]describe[/green] to see the full contract."
+            ),
+        ),
+        TourStep(
+            id="first_invoke",
+            trigger="invoke",
+            message=(
+                "  Nice! You just made your first RPC call.\n"
+                "  [dim]Tip: methods with no args will prompt you interactively.[/dim]\n"
+                "  [dim]Use Tab for autocomplete anywhere.[/dim]\n"
+                "\n"
+                "  [bold]You're all set![/bold] Type [green]help[/green] anytime to see available commands."
+            ),
+        ),
+    ],
+)
+
+
+# ── Guide manager ─────────────────────────────────────────────────────────────
+
+class GuideManager:
+    """Manages the guided tour state and event dispatch."""
+
+    def __init__(self, display: Any, tour: Tour | None = None) -> None:
+        self._display = display
+        self._tour = tour or Tour(name="empty")
+        self._enabled = True
+        self._listeners: list[Callable[[str, str | None], None]] = []
+
+    @property
+    def tour(self) -> Tour:
+        return self._tour
+
+    @property
+    def is_active(self) -> bool:
+        return self._enabled and not self._tour.is_complete
+
+    def disable(self) -> None:
+        """Disable the guide (e.g., for experienced users)."""
+        self._enabled = False
+
+    def add_listener(self, listener: Callable[[str, str | None], None]) -> None:
+        """Add a custom event listener for extensibility."""
+        self._listeners.append(listener)
+
+    def fire(self, event: str, value: str | None = None) -> None:
+        """Fire a guide event. Shows hint if it matches the current step.
+
+        Args:
+            event: Event name (e.g., "command", "cd", "invoke", "connected").
+            value: Optional value (e.g., command name, target path).
+        """
+        if not self._enabled:
+            return
+
+        # Notify custom listeners
+        for listener in self._listeners:
+            listener(event, value)
+
+        step = self._tour.current
+        if step is None:
+            return
+
+        # Check if this event matches the current step's trigger
+        if step.trigger != event:
+            return
+
+        # Check trigger_value if specified
+        if step.trigger_value is not None:
+            if step.trigger_value.endswith("/*"):
+                # Glob match: /services/* matches /services/anything
+                prefix = step.trigger_value[:-1]
+                if value is None or not value.startswith(prefix):
+                    return
+            elif step.trigger_value != value:
+                return
+
+        # Show the hint
+        self._display.print()
+        self._display.print(f"  [dim]{'─' * 50}[/dim]")
+        self._display.print(step.message)
+        self._display.print(f"  [dim]{'─' * 50}[/dim]")
+        self._display.print()
+
+        self._tour.advance()
+
+
+# ── Persistence ───────────────────────────────────────────────────────────────
+
+_CONFIG_PATH = Path(os.path.expanduser("~/.aster/config.toml"))
+
+
+def is_first_time() -> bool:
+    """Check if this is the user's first time using the shell."""
+    if not _CONFIG_PATH.exists():
+        return True
+
+    try:
+        if __import__("sys").version_info >= (3, 11):
+            import tomllib
+        else:
+            import tomli as tomllib  # type: ignore[no-redef]
+
+        with _CONFIG_PATH.open("rb") as f:
+            config = tomllib.load(f)
+        return config.get("shell", {}).get("first_time", True)
+    except Exception:
+        return True
+
+
+def mark_tour_complete() -> None:
+    """Mark the guided tour as complete in the config."""
+    _CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+
+    # Read existing config
+    existing_lines: list[str] = []
+    if _CONFIG_PATH.exists():
+        existing_lines = _CONFIG_PATH.read_text().splitlines()
+
+    # Check if [shell] section exists
+    shell_section_idx = None
+    first_time_idx = None
+    for i, line in enumerate(existing_lines):
+        if line.strip() == "[shell]":
+            shell_section_idx = i
+        if "first_time" in line and shell_section_idx is not None:
+            first_time_idx = i
+
+    if first_time_idx is not None:
+        existing_lines[first_time_idx] = "first_time = false"
+    elif shell_section_idx is not None:
+        existing_lines.insert(shell_section_idx + 1, "first_time = false")
+    else:
+        existing_lines.append("")
+        existing_lines.append("[shell]")
+        existing_lines.append("first_time = false")
+
+    _CONFIG_PATH.write_text("\n".join(existing_lines) + "\n")

aster_cli/shell/hooks.py

@@ -0,0 +1,255 @@
+"""
+aster_cli.shell.hooks -- Extension hooks for the shell.
+
+Provides the hook protocol and registry for plugging in:
+  - Input builders (construct RPC payloads from user intent)
+  - Output renderers (format RPC responses for display)
+  - Session lifecycle events
+
+The LLM plugin will implement InputBuilder and OutputRenderer to handle
+complex types conversationally rather than field-by-field.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+
+# ── Hook protocols ────────────────────────────────────────────────────────────
+
+
+@runtime_checkable
+class InputBuilder(Protocol):
+    """Builds an RPC request payload from user input and method schema.
+
+    The default implementation prompts field-by-field. An LLM plugin
+    replaces this with conversational input construction:
+
+    1. Receives the method schema (fields, types, nested types, constraints)
+    2. Receives any raw user input (partial key=value pairs, natural language)
+    3. Constructs the complete JSON payload, asking follow-up questions if needed
+
+    For complex nested types, the LLM can:
+    - Explain what each field means in context
+    - Suggest reasonable defaults
+    - Validate constraints before sending
+    - Build nested objects conversationally ("What file do you want to get?")
+    """
+
+    async def build_payload(
+        self,
+        method_schema: MethodSchema,
+        user_input: dict[str, Any],
+        ask: AskFn,
+    ) -> dict[str, Any] | None:
+        """Build a complete RPC payload.
+
+        Args:
+            method_schema: Full type information for the method.
+            user_input: Any args the user already provided (may be partial/empty).
+            ask: Callable to prompt the user for more information.
+                 Signature: ask(prompt: str) -> str | None (None = cancelled)
+
+        Returns:
+            Complete payload dict, or None if cancelled.
+        """
+        ...
+
+
+@runtime_checkable
+class OutputRenderer(Protocol):
+    """Renders an RPC response for display.
+
+    The default implementation dumps JSON. An LLM plugin replaces this
+    with intelligent rendering:
+
+    1. Receives the response data and its type schema
+    2. Decides the best presentation:
+       - Simple scalar → inline display
+       - List of records → table
+       - Nested object → tree or summarized view
+       - Large payload → paginated or summarized
+       - Error/status → highlighted with explanation
+    3. Can explain what the response means in context
+
+    The renderer also receives the display object so it can use
+    rich tables, trees, panels, etc.
+    """
+
+    async def render_response(
+        self,
+        method_schema: MethodSchema,
+        result: Any,
+        display: Any,
+    ) -> bool:
+        """Render an RPC response.
+
+        Args:
+            method_schema: Full type information for the method.
+            result: The response data (already deserialized).
+            display: The Display instance for output.
+
+        Returns:
+            True if the response was rendered (suppresses default JSON dump).
+            False to fall through to default rendering.
+        """
+        ...
+
+
+@runtime_checkable
+class SessionHook(Protocol):
+    """Lifecycle hook for session-scoped services.
+
+    Called when entering/exiting a session subshell.
+    """
+
+    async def on_session_start(self, service_name: str, ctx: Any) -> None: ...
+    async def on_session_end(self, service_name: str, ctx: Any) -> None: ...
+
+
+# ── Data types ────────────────────────────────────────────────────────────────
+
+
+@dataclass
+class FieldSchema:
+    """Schema for a single field in a request/response type."""
+
+    name: str
+    type_name: str  # "str", "int", "list[str]", "MyNestedType", etc.
+    required: bool = True
+    default: Any = None
+    description: str = ""
+    nested_fields: list[FieldSchema] | None = None  # for complex types
+
+
+@dataclass
+class MethodSchema:
+    """Full schema for a method -- everything a hook needs to build input or render output."""
+
+    service_name: str
+    method_name: str
+    pattern: str  # "unary", "server_stream", "client_stream", "bidi_stream"
+    request_type: str = ""
+    response_type: str = ""
+    request_fields: list[FieldSchema] | None = None
+    response_fields: list[FieldSchema] | None = None
+    timeout: float | None = None
+    description: str = ""
+
+
+# Type alias for the ask function
+AskFn = Any  # Callable[[str], Awaitable[str | None]] -- avoid complex type for 3.9
+
+
+# ── Hook registry ─────────────────────────────────────────────────────────────
+
+
+class HookRegistry:
+    """Central registry for shell extension hooks."""
+
+    def __init__(self) -> None:
+        self._input_builders: list[InputBuilder] = []
+        self._output_renderers: list[OutputRenderer] = []
+        self._session_hooks: list[SessionHook] = []
+
+    def register_input_builder(self, builder: InputBuilder) -> None:
+        """Register an input builder (e.g., LLM-powered)."""
+        self._input_builders.append(builder)
+
+    def register_output_renderer(self, renderer: OutputRenderer) -> None:
+        """Register an output renderer (e.g., LLM-powered)."""
+        self._output_renderers.append(renderer)
+
+    def register_session_hook(self, hook: SessionHook) -> None:
+        """Register a session lifecycle hook."""
+        self._session_hooks.append(hook)
+
+    @property
+    def input_builder(self) -> InputBuilder | None:
+        """The active input builder (last registered wins)."""
+        return self._input_builders[-1] if self._input_builders else None
+
+    @property
+    def output_renderer(self) -> OutputRenderer | None:
+        """The active output renderer (last registered wins)."""
+        return self._output_renderers[-1] if self._output_renderers else None
+
+    @property
+    def session_hooks(self) -> list[SessionHook]:
+        """All registered session hooks."""
+        return list(self._session_hooks)
+
+
+# ── Default implementations ──────────────────────────────────────��────────────
+
+
+class DefaultInputBuilder:
+    """Field-by-field interactive prompting (the built-in fallback)."""
+
+    async def build_payload(
+        self,
+        method_schema: MethodSchema,
+        user_input: dict[str, Any],
+        ask: AskFn,
+    ) -> dict[str, Any] | None:
+        if not method_schema.request_fields:
+            return user_input or {}
+
+        result = dict(user_input)  # start with what user already provided
+
+        for f in method_schema.request_fields:
+            if f.name in result:
+                continue  # already provided
+
+            prompt = f"  ▸ {f.name}"
+            if f.type_name:
+                prompt += f" ({f.type_name})"
+            if f.default is not None:
+                prompt += f" [{f.default}]"
+            prompt += ": "
+
+            value = await ask(prompt)
+            if value is None:
+                return None  # cancelled
+
+            value = value.strip()
+            if not value and f.default is not None:
+                result[f.name] = f.default
+            elif not value and not f.required:
+                continue
+            elif not value:
+                return None  # required field missing
+            else:
+                # Try JSON parse
+                import json
+                try:
+                    result[f.name] = json.loads(value)
+                except (json.JSONDecodeError, ValueError):
+                    result[f.name] = value
+
+        return result
+
+
+class DefaultOutputRenderer:
+    """JSON dump with timing (the built-in fallback)."""
+
+    async def render_response(
+        self,
+        method_schema: MethodSchema,
+        result: Any,
+        display: Any,
+    ) -> bool:
+        # Return False to use default rendering in invoker
+        return False
+
+
+# ── Singleton ─────────────────────────────────────────────────────────────────
+
+_registry = HookRegistry()
+
+
+def get_hook_registry() -> HookRegistry:
+    """Get the global hook registry."""
+    return _registry