milo-cli 0.1.0__py3-none-any.whl

milo/schema.py

@@ -0,0 +1,214 @@
+"""Function signature → JSON Schema for MCP tool compatibility."""
+
+from __future__ import annotations
+
+import dataclasses
+import enum
+import inspect
+import types
+import typing
+from collections.abc import Callable
+from typing import Any, Literal, Union, get_args, get_origin
+
+_TYPE_MAP: dict[type, str] = {
+    str: "string",
+    int: "integer",
+    float: "number",
+    bool: "boolean",
+}
+
+
+def function_to_schema(func: Callable[..., Any]) -> dict[str, Any]:
+    """Generate MCP-compatible JSON Schema from function type annotations.
+
+    Parameters with defaults are optional (not in required).
+    X | None unions unwrapped to base type.
+    Supports: str, int, float, bool, list[X], dict[str, X], X | None,
+    Enum, Literal, dataclass, TypedDict, Union.
+    """
+    sig = inspect.signature(func)
+    # Resolve string annotations (from __future__ import annotations)
+    try:
+        hints = typing.get_type_hints(func)
+    except Exception:
+        hints = {}
+
+    properties: dict[str, Any] = {}
+    required: list[str] = []
+
+    for name, param in sig.parameters.items():
+        annotation = hints.get(name, param.annotation)
+        if annotation is inspect.Parameter.empty:
+            annotation = str
+
+        # Strip return type
+        if name == "return":
+            continue
+
+        # Skip Context parameters (injected by CLI dispatcher)
+        if _is_context_type(annotation, name):
+            continue
+
+        is_optional = _is_optional(annotation)
+        if is_optional:
+            annotation = _unwrap_optional(annotation)
+
+        properties[name] = _type_to_schema(annotation)
+
+        has_default = param.default is not inspect.Parameter.empty
+        if not has_default and not is_optional:
+            required.append(name)
+
+    result: dict[str, Any] = {"type": "object", "properties": properties}
+    if required:
+        result["required"] = required
+    return result
+
+
+def _type_to_schema(annotation: Any, _seen: set[int] | None = None) -> dict[str, Any]:
+    """Convert Python type annotation to JSON Schema fragment."""
+    # Primitive types
+    if annotation in _TYPE_MAP:
+        return {"type": _TYPE_MAP[annotation]}
+
+    # Handle bare dict/list (unparameterized)
+    if annotation is dict:
+        return {"type": "object"}
+    if annotation is list:
+        return {"type": "array"}
+
+    # Enum subclass
+    if isinstance(annotation, type) and issubclass(annotation, enum.Enum):
+        values = [m.value for m in annotation]
+        if all(isinstance(v, int) for v in values):
+            return {"type": "integer", "enum": values}
+        return {"type": "string", "enum": values}
+
+    # Literal
+    origin = get_origin(annotation)
+    if origin is Literal:
+        return {"enum": list(get_args(annotation))}
+
+    # dataclass
+    if dataclasses.is_dataclass(annotation) and isinstance(annotation, type):
+        if _seen is None:
+            _seen = set()
+        type_id = id(annotation)
+        if type_id in _seen:
+            return {"type": "object"}  # cycle detected
+        _seen = _seen | {type_id}
+        props = {}
+        req = []
+        hints = typing.get_type_hints(annotation)
+        for f in dataclasses.fields(annotation):
+            field_type = hints.get(f.name, str)
+            props[f.name] = _type_to_schema(field_type, _seen)
+            if f.default is dataclasses.MISSING and f.default_factory is dataclasses.MISSING:
+                req.append(f.name)
+        result: dict[str, Any] = {"type": "object", "properties": props}
+        if req:
+            result["required"] = req
+        return result
+
+    # TypedDict
+    if _is_typed_dict(annotation):
+        if _seen is None:
+            _seen = set()
+        type_id = id(annotation)
+        if type_id in _seen:
+            return {"type": "object"}
+        _seen = _seen | {type_id}
+        hints = typing.get_type_hints(annotation)
+        props = {}
+        for fname, ftype in hints.items():
+            props[fname] = _type_to_schema(ftype, _seen)
+        result = {"type": "object", "properties": props}
+        # TypedDict required keys
+        req_keys = getattr(annotation, "__required_keys__", set())
+        if req_keys:
+            result["required"] = sorted(req_keys)
+        return result
+
+    # Union (non-Optional, non-None)
+    if origin is Union or origin is types.UnionType:
+        args = get_args(annotation)
+        non_none = [a for a in args if a is not type(None)]
+        if len(non_none) > 1:
+            if _seen is None:
+                _seen = set()
+            return {"anyOf": [_type_to_schema(a, _seen) for a in non_none]}
+        if len(non_none) == 1:
+            return _type_to_schema(non_none[0], _seen)
+
+    # list[T] with recursive item schema
+    if origin is list:
+        args = get_args(annotation)
+        if args:
+            return {"type": "array", "items": _type_to_schema(args[0], _seen)}
+        return {"type": "array"}
+
+    # dict[str, V] with additionalProperties
+    if origin is dict:
+        args = get_args(annotation)
+        if args and len(args) == 2:
+            return {"type": "object", "additionalProperties": _type_to_schema(args[1], _seen)}
+        return {"type": "object"}
+
+    return {"type": "string"}
+
+
+def _is_typed_dict(annotation: Any) -> bool:
+    """Check if annotation is a TypedDict subclass."""
+    return (
+        isinstance(annotation, type)
+        and issubclass(annotation, dict)
+        and hasattr(annotation, "__annotations__")
+        and hasattr(annotation, "__required_keys__")
+    )
+
+
+def _is_optional(annotation: Any) -> bool:
+    """Check if annotation is X | None."""
+    origin = get_origin(annotation)
+    if origin is Union or origin is types.UnionType:
+        return type(None) in get_args(annotation)
+    return False
+
+
+def _unwrap_optional(annotation: Any) -> Any:
+    """Extract non-None type from X | None."""
+    args = get_args(annotation)
+    non_none = [a for a in args if a is not type(None)]
+    return non_none[0] if len(non_none) == 1 else str
+
+
+def return_to_schema(func: Callable[..., Any]) -> dict[str, Any] | None:
+    """Generate JSON Schema from function return type annotation.
+
+    Returns None if the function has no return annotation or returns None.
+    """
+    try:
+        hints = typing.get_type_hints(func)
+    except Exception:
+        hints = {}
+
+    ret = hints.get("return", inspect.Parameter.empty)
+    if ret is inspect.Parameter.empty or ret is type(None):
+        return None
+
+    # Unwrap Optional return types
+    if _is_optional(ret):
+        ret = _unwrap_optional(ret)
+        if ret is type(None):
+            return None
+
+    return _type_to_schema(ret)
+
+
+def _is_context_type(annotation: Any, name: str) -> bool:
+    """Check if an annotation refers to milo's Context type."""
+    if name == "ctx":
+        return True
+    if isinstance(annotation, type) and annotation.__name__ == "Context":
+        return True
+    return isinstance(annotation, str) and annotation in ("Context", "milo.context.Context")

milo/state.py

@@ -0,0 +1,229 @@
+"""Store, dispatch, saga runner, combine_reducers."""
+
+from __future__ import annotations
+
+import hashlib
+import threading
+import time
+from collections.abc import Callable
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+from typing import Any
+
+from milo._errors import ErrorCode, StateError
+from milo._types import (
+    Action,
+    Call,
+    Delay,
+    Fork,
+    Put,
+    Quit,
+    ReducerResult,
+    Select,
+)
+
+
+class Store:
+    """Centralized state container with saga support.
+
+    Thread-safety: reads are lock-free (frozen state).
+    Dispatch serializes through a lock.
+    Sagas run on a ThreadPoolExecutor.
+    """
+
+    def __init__(
+        self,
+        reducer: Callable,
+        initial_state: Any,
+        middleware: tuple[Callable, ...] = (),
+        *,
+        record: bool | str | Path = False,
+    ) -> None:
+        self._reducer = reducer
+        self._state = initial_state
+        self._lock = threading.Lock()
+        self._listeners: list[Callable] = []
+        self._executor = ThreadPoolExecutor(max_workers=4)
+        self._recording: list[dict] | None = [] if record else None
+        self._record_path = record if isinstance(record, (str, Path)) else None
+        self._quit = threading.Event()
+        self._exit_code = 0
+
+        # Build middleware chain
+        self._dispatch_fn = self._base_dispatch
+        for mw in reversed(middleware):
+            self._dispatch_fn = mw(self._dispatch_fn, self._get_state)
+
+        # Initialize
+        self.dispatch(Action("@@INIT"))
+
+    def _get_state(self) -> Any:
+        return self._state
+
+    @property
+    def state(self) -> Any:
+        return self._state
+
+    def dispatch(self, action: Action) -> None:
+        """Dispatch action through middleware -> reducer."""
+        self._dispatch_fn(action)
+
+    def _base_dispatch(self, action: Action) -> None:
+        """Core dispatch: reducer + saga scheduling + recording."""
+        quit_signal = False
+
+        with self._lock:
+            try:
+                result = self._reducer(self._state, action)
+            except Exception as e:
+                raise StateError(ErrorCode.STA_REDUCER, f"Reducer error: {e}") from e
+
+            sagas = ()
+
+            # Unwrap Quit — may wrap a ReducerResult or plain state
+            if isinstance(result, Quit):
+                quit_signal = True
+                self._exit_code = result.code
+                sagas = result.sagas
+                result = result.state
+
+            # Unwrap ReducerResult
+            if isinstance(result, ReducerResult):
+                self._state = result.state
+                sagas = sagas + result.sagas
+            else:
+                self._state = result
+
+            # Record
+            if self._recording is not None:
+                state_hash = hashlib.sha256(repr(self._state).encode()).hexdigest()[:16]
+                self._recording.append(
+                    {
+                        "timestamp": time.time(),
+                        "action_type": action.type,
+                        "action_payload": action.payload,
+                        "state_hash": state_hash,
+                    }
+                )
+
+        # Notify listeners
+        for listener in self._listeners:
+            listener()
+
+        # Schedule sagas outside the lock
+        for saga_fn in sagas:
+            self.run_saga(saga_fn())
+
+        # Set quit after sagas are scheduled and listeners notified
+        if quit_signal:
+            self._quit.set()
+
+    def run_saga(self, saga: Any) -> None:
+        """Schedule a saga on the thread pool."""
+        self._executor.submit(self._run_saga, saga)
+
+    def _run_saga(self, saga: Any) -> None:
+        """Step through a generator saga, executing effects."""
+        try:
+            effect = next(saga)
+            while True:
+                match effect:
+                    case Call(fn, args, kwargs):
+                        result = fn(*args, **kwargs)
+                        effect = saga.send(result)
+                    case Put(action):
+                        self.dispatch(action)
+                        effect = next(saga)
+                    case Select(selector):
+                        state = self._state
+                        if selector:
+                            state = selector(state)
+                        effect = saga.send(state)
+                    case Fork(child_saga):
+                        self._executor.submit(self._run_saga, child_saga)
+                        effect = next(saga)
+                    case Delay(seconds):
+                        time.sleep(seconds)
+                        effect = next(saga)
+                    case _:
+                        raise StateError(
+                            ErrorCode.STA_SAGA,
+                            f"Unknown effect type: {type(effect).__name__}",
+                        )
+        except StopIteration:
+            pass
+        except StateError:
+            raise
+        except Exception as e:
+            raise StateError(ErrorCode.STA_SAGA, f"Saga error: {e}") from e
+
+    def subscribe(self, listener: Callable) -> Callable[[], None]:
+        """Register state-change listener. Returns unsubscribe callable."""
+        self._listeners.append(listener)
+
+        def unsubscribe() -> None:
+            self._listeners.remove(listener)
+
+        return unsubscribe
+
+    @property
+    def quit_requested(self) -> bool:
+        """True if a reducer returned Quit."""
+        return self._quit.is_set()
+
+    @property
+    def exit_code(self) -> int:
+        """Exit code from the Quit signal (default 0)."""
+        return self._exit_code
+
+    @property
+    def recording(self) -> list[dict] | None:
+        """Get session recording if enabled."""
+        return self._recording
+
+    def shutdown(self) -> None:
+        """Shut down the thread pool."""
+        self._executor.shutdown(wait=False)
+
+
+def combine_reducers(**reducers: Callable) -> Callable:
+    """Combine multiple reducers into one that manages a dict state.
+
+    Each reducer manages a slice of state under its keyword name.
+    Sagas from ReducerResult and Quit are collected and propagated.
+    """
+
+    def combined(state: dict | None, action: Action) -> dict | ReducerResult | Quit:
+        if state is None:
+            state = {}
+        next_state = {}
+        changed = False
+        all_sagas: list[Callable] = []
+        quit_signal: Quit | None = None
+
+        for key, reducer in reducers.items():
+            prev = state.get(key)
+            next_val = reducer(prev, action)
+            if isinstance(next_val, Quit):
+                quit_signal = next_val
+                next_state[key] = next_val.state
+                all_sagas.extend(next_val.sagas)
+                changed = True
+            elif isinstance(next_val, ReducerResult):
+                next_state[key] = next_val.state
+                all_sagas.extend(next_val.sagas)
+                changed = True
+            else:
+                next_state[key] = next_val
+            if next_state[key] is not prev:
+                changed = True
+
+        result = next_state if changed else state
+
+        if quit_signal is not None:
+            return Quit(state=result, code=quit_signal.code, sagas=tuple(all_sagas))
+        if all_sagas:
+            return ReducerResult(state=result, sagas=tuple(all_sagas))
+        return result
+
+    return combined

milo/streaming.py

@@ -0,0 +1,41 @@
+"""Streaming support for long-running CLI commands."""
+
+from __future__ import annotations
+
+import inspect
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class Progress:
+    """Progress notification from a streaming command."""
+
+    status: str
+    step: int = 0
+    total: int = 0
+
+
+def consume_generator(gen: Any) -> tuple[list[Progress], Any]:
+    """Consume a generator, collecting Progress yields and capturing the final value.
+
+    Returns ``(progress_list, final_value)``.
+    If the generator has no ``StopIteration.value``, final_value is ``None``.
+    """
+    progress: list[Progress] = []
+    final_value = None
+
+    try:
+        while True:
+            value = next(gen)
+            if isinstance(value, Progress):
+                progress.append(value)
+    except StopIteration as e:
+        final_value = e.value
+
+    return progress, final_value
+
+
+def is_generator_result(result: Any) -> bool:
+    """Check if a call result is a generator that should be consumed for streaming."""
+    return inspect.isgenerator(result)

milo/templates/__init__.py

@@ -0,0 +1,38 @@
+"""Built-in templates and template environment factory."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+_TEMPLATE_DIR = Path(__file__).parent
+
+
+def get_env(**kwargs: Any) -> Any:
+    """Create a kida Environment with the built-in template loader.
+
+    Returns a kida Environment with a chained loader:
+    user templates -> milo built-in templates -> kida components.
+    """
+    from kida import Environment, FileSystemLoader
+
+    loaders = []
+
+    # User-provided loader
+    if "loader" in kwargs:
+        user_loader = kwargs.pop("loader")
+        if user_loader is not None:
+            loaders.append(user_loader)
+
+    # Built-in milo templates
+    loaders.append(FileSystemLoader(str(_TEMPLATE_DIR)))
+
+    if len(loaders) == 1:
+        loader = loaders[0]
+    else:
+        from kida import ChoiceLoader
+
+        loader = ChoiceLoader(loaders)
+
+    kwargs.setdefault("autoescape", "terminal")
+    return Environment(loader=loader, **kwargs)

milo/templates/error.kida

@@ -0,0 +1,5 @@
+{{ "error" | red | bold }}{% if code %} {{ code | yellow }}{% endif %}
+{{ error | dim }}
+{% if template_name %}  {{ "template:" | dim }} {{ template_name }}{% endif %}
+{% if hint %}  {{ "hint:" | cyan }} {{ hint }}{% endif %}
+{% if docs_url %}  {{ "docs:" | dim }} {{ docs_url }}{% endif %}

milo/templates/field_confirm.kida

@@ -0,0 +1 @@
+{% if field.focused %}{{ ">" | green | bold }} {{ spec.label | bold }}: {% if field.value %}{{ "Yes" | green | bold }}{% else %}{{ "No" | dim }}{% endif %}{% else %}  {{ spec.label | dim }}: {% if field.value %}{{ "Yes" | dim }}{% else %}{{ "No" | dim }}{% endif %}{% endif %}

milo/templates/field_select.kida

@@ -0,0 +1,3 @@
+{% if field.focused %}{{ ">" | green | bold }} {{ spec.label | bold }}:{% else %}  {{ spec.label | dim }}:{% endif %}
+{% for choice in spec.choices %}  {% if loop.index0 == field.selected_index %}{{ icons.check | green }} {{ choice | bold }}{% else %}  {{ choice | dim }}{% endif %}
+{% endfor %}

milo/templates/field_text.kida

@@ -0,0 +1 @@
+{% if field.focused %}{{ ">" | green | bold }} {{ spec.label | bold }}: {{ field.value }}{% else %}  {{ spec.label | dim }}: {{ field.value | dim }}{% endif %}{% if field.error %} {{ field.error | red }}{% endif %}

milo/templates/form.kida

@@ -0,0 +1,8 @@
+{% for spec, field in zip(state.specs, state.fields) %}
+{% if field.focused %}{{ ">" | green | bold }} {{ spec.label | bold }}{% else %}  {{ spec.label | dim }}{% endif %}{% if field.error %} {{ field.error | red }}{% endif %}
+{% if spec.field_type.name == "TEXT" or spec.field_type.name == "PASSWORD" %}  {% if spec.field_type.name == "PASSWORD" %}{{ "*" * (field.value | length) | dim }}{% else %}{{ field.value }}{% endif %}
+{% elif spec.field_type.name == "SELECT" %}{% for choice in spec.choices %}
+  {% if loop.index0 == field.selected_index %}{{ icons.check | green }} {{ choice | bold }}{% else %}  {{ choice | dim }}{% endif %}{% endfor %}
+{% elif spec.field_type.name == "CONFIRM" %}  {% if field.value %}{{ "Yes" | green | bold }}{% else %}{{ "No" | dim }}{% endif %}
+{% endif %}
+{% endfor %}

milo/templates/help.kida

@@ -0,0 +1,7 @@
+{{ state.prog | bold }}{% if state.description %} {{ "-" | dim }} {{ state.description }}{% endif %}
+
+{% for group in state.groups %}
+{{ group.title | yellow | bold }}:
+{% for action in group.actions %}  {% if action.option_strings %}{{ action.option_strings | join(", ") | green }}{% else %}{{ action.dest | cyan }}{% endif %}{% if action.metavar %} {{ action.metavar | dim }}{% endif %}    {{ action.help }}{% if action.default is not none and action.default != "==SUPPRESS==" %} {{ ("(default: " ~ action.default ~ ")") | dim }}{% endif %}
+{% endfor %}
+{% endfor %}

milo/templates/progress.kida

@@ -0,0 +1 @@
+{{ state.label | default("Progress") | bold }}: {{ bar(state.progress, width=20) | green }} {{ (state.progress * 100) | int }}%

milo/testing/__init__.py

@@ -0,0 +1,27 @@
+"""Public test API: assert_renders, replay, record, MCP client."""
+
+from milo.testing._mcp import CallResult, MCPClient, ToolInfo
+from milo.testing._record import (
+    ActionRecord,
+    SessionRecording,
+    load_recording,
+    recording_middleware,
+    save_recording,
+)
+from milo.testing._replay import replay
+from milo.testing._snapshot import assert_renders, assert_saga, assert_state
+
+__all__ = [
+    "ActionRecord",
+    "CallResult",
+    "MCPClient",
+    "SessionRecording",
+    "ToolInfo",
+    "assert_renders",
+    "assert_saga",
+    "assert_state",
+    "load_recording",
+    "recording_middleware",
+    "replay",
+    "save_recording",
+]

milo/testing/_mcp.py

@@ -0,0 +1,87 @@
+"""MCP test client — synchronous wrapper around milo.mcp internals."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from milo.commands import CLI
+from milo.mcp import _call_tool, _handle_method, _list_tools
+
+
+@dataclass(frozen=True, slots=True)
+class ToolInfo:
+    """Frozen snapshot of an MCP tool descriptor."""
+
+    name: str
+    description: str
+    input_schema: dict[str, Any]
+    output_schema: dict[str, Any] | None
+
+
+@dataclass(frozen=True, slots=True)
+class CallResult:
+    """Frozen snapshot of an MCP tools/call response."""
+
+    text: str
+    is_error: bool
+    structured: Any
+
+
+class MCPClient:
+    """Synchronous test client for exercising a CLI's MCP surface."""
+
+    def __init__(self, cli: CLI) -> None:
+        self._cli = cli
+
+    def initialize(self) -> dict[str, Any]:
+        """Send ``initialize`` and return the server info dict."""
+        result = _handle_method(self._cli, "initialize", {})
+        assert result is not None, "initialize must return a result"
+        return result
+
+    def list_tools(self) -> list[ToolInfo]:
+        """Return all visible tools as ToolInfo objects."""
+        raw = _list_tools(self._cli)
+        return [
+            ToolInfo(
+                name=t["name"],
+                description=t.get("description", ""),
+                input_schema=t.get("inputSchema", {}),
+                output_schema=t.get("outputSchema"),
+            )
+            for t in raw
+        ]
+
+    def call(self, tool_name: str, **arguments: Any) -> CallResult:
+        """Invoke a tool by name and return a CallResult."""
+        raw = _call_tool(self._cli, {"name": tool_name, "arguments": arguments})
+        content = raw.get("content", [])
+        text = content[0]["text"] if content else ""
+        return CallResult(
+            text=text,
+            is_error=raw.get("isError", False),
+            structured=raw.get("structuredContent"),
+        )
+
+    def list_resources(self) -> list[dict[str, Any]]:
+        """Return all resources (requires F3 resources support)."""
+        result = _handle_method(self._cli, "resources/list", {})
+        return result.get("resources", []) if result else []
+
+    def read_resource(self, uri: str) -> dict[str, Any]:
+        """Read a resource by URI (requires F3 resources support)."""
+        result = _handle_method(self._cli, "resources/read", {"uri": uri})
+        return result or {}
+
+    def list_prompts(self) -> list[dict[str, Any]]:
+        """Return all prompts (requires F3 prompts support)."""
+        result = _handle_method(self._cli, "prompts/list", {})
+        return result.get("prompts", []) if result else []
+
+    def get_prompt(self, prompt_name: str, **arguments: Any) -> dict[str, Any]:
+        """Get a prompt by name (requires F3 prompts support)."""
+        result = _handle_method(
+            self._cli, "prompts/get", {"name": prompt_name, "arguments": arguments}
+        )
+        return result or {}