milo-cli 0.1.0__py3-none-any.whl

milo/pipeline.py

@@ -0,0 +1,276 @@
+"""Pipeline orchestration with observable state through the Store/saga system."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from dataclasses import dataclass, replace
+from typing import Any
+
+from milo._types import Action, Call, Fork, Put
+
+# ---------------------------------------------------------------------------
+# Data types
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class Phase:
+    """A named pipeline phase."""
+
+    name: str
+    handler: Callable[..., Any]
+    description: str = ""
+    depends_on: tuple[str, ...] = ()
+    parallel: bool = False
+    weight: int = 1
+
+
+@dataclass(frozen=True, slots=True)
+class PhaseStatus:
+    """Runtime status of a single phase."""
+
+    name: str
+    status: str = "pending"  # pending, running, completed, failed, skipped
+    started_at: float = 0.0
+    elapsed: float = 0.0
+    error: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class PipelineState:
+    """Observable state for a running pipeline."""
+
+    name: str = ""
+    phases: tuple[PhaseStatus, ...] = ()
+    current_phase: str = ""
+    started_at: float = 0.0
+    elapsed: float = 0.0
+    progress: float = 0.0
+    status: str = "pending"  # pending, running, completed, failed
+
+
+# ---------------------------------------------------------------------------
+# Pipeline action types
+# ---------------------------------------------------------------------------
+
+
+PIPELINE_START = "@@PIPELINE_START"
+PIPELINE_COMPLETE = "@@PIPELINE_COMPLETE"
+PHASE_START = "@@PHASE_START"
+PHASE_COMPLETE = "@@PHASE_COMPLETE"
+PHASE_FAILED = "@@PHASE_FAILED"
+
+
+# ---------------------------------------------------------------------------
+# Pipeline class
+# ---------------------------------------------------------------------------
+
+
+class Pipeline:
+    """Declarative build pipeline that executes through the Store.
+
+    Usage::
+
+        pipeline = Pipeline(
+            "build",
+            Phase("discover", handler=discover),
+            Phase("parse", handler=parse, depends_on=("discover",)),
+            Phase("render", handler=render, depends_on=("parse",), parallel=True),
+            Phase("assets", handler=assets, depends_on=("parse",), parallel=True),
+            Phase("write", handler=write, depends_on=("render", "assets")),
+        )
+
+        # Extend with >>
+        pipeline = pipeline >> Phase("health", handler=check)
+
+    The pipeline generates a saga and reducer that work with the Store
+    for observable, testable execution.
+    """
+
+    def __init__(self, name: str, *phases: Phase) -> None:
+        self.name = name
+        self.phases = list(phases)
+
+    def __rshift__(self, phase: Phase) -> Pipeline:
+        """Extend the pipeline: ``pipeline >> Phase(...)``."""
+        new = Pipeline(self.name, *self.phases, phase)
+        return new
+
+    def build_reducer(self) -> Callable:
+        """Generate a reducer that handles pipeline state transitions."""
+        name = self.name
+        phase_names = tuple(p.name for p in self.phases)
+        total_weight = sum(p.weight for p in self.phases)
+        weight_map = {p.name: p.weight for p in self.phases}
+
+        def reducer(state: PipelineState | None, action: Action) -> PipelineState:
+            if action.type == "@@INIT":
+                return PipelineState(
+                    name=name,
+                    phases=tuple(PhaseStatus(name=n) for n in phase_names),
+                    status="pending",
+                )
+
+            if state is None:
+                return PipelineState(name=name)
+
+            if action.type == PIPELINE_START:
+                return replace(
+                    state,
+                    status="running",
+                    started_at=action.payload or time.monotonic(),
+                )
+
+            if action.type == PHASE_START:
+                phase_name = action.payload
+                now = time.monotonic()
+                new_phases = tuple(
+                    replace(p, status="running", started_at=now) if p.name == phase_name else p
+                    for p in state.phases
+                )
+                return replace(state, phases=new_phases, current_phase=phase_name)
+
+            if action.type == PHASE_COMPLETE:
+                phase_name = (
+                    action.payload.get("name", "")
+                    if isinstance(action.payload, dict)
+                    else action.payload
+                )
+                now = time.monotonic()
+                new_phases = []
+                completed_weight = 0
+                for p in state.phases:
+                    if p.name == phase_name:
+                        new_phases.append(
+                            replace(p, status="completed", elapsed=now - p.started_at)
+                        )
+                    else:
+                        new_phases.append(p)
+                    if new_phases[-1].status == "completed":
+                        completed_weight += weight_map.get(p.name, 1)
+
+                progress = completed_weight / total_weight if total_weight > 0 else 1.0
+                return replace(
+                    state,
+                    phases=tuple(new_phases),
+                    progress=progress,
+                )
+
+            if action.type == PHASE_FAILED:
+                payload = (
+                    action.payload if isinstance(action.payload, dict) else {"name": action.payload}
+                )
+                phase_name = payload.get("name", "")
+                error = payload.get("error", "")
+                now = time.monotonic()
+                new_phases = tuple(
+                    replace(p, status="failed", error=error, elapsed=now - p.started_at)
+                    if p.name == phase_name
+                    else p
+                    for p in state.phases
+                )
+                return replace(
+                    state,
+                    phases=new_phases,
+                    status="failed",
+                    current_phase=phase_name,
+                )
+
+            if action.type == PIPELINE_COMPLETE:
+                now = time.monotonic()
+                return replace(
+                    state,
+                    status="completed",
+                    progress=1.0,
+                    elapsed=now - state.started_at if state.started_at else 0.0,
+                    current_phase="",
+                )
+
+            return state
+
+        return reducer
+
+    def build_saga(self) -> Callable:
+        """Generate a saga that executes all phases in dependency order."""
+        phases = list(self.phases)
+        dep_graph = {p.name: set(p.depends_on) for p in phases}
+        phase_map = {p.name: p for p in phases}
+
+        def saga():
+            yield Put(Action(PIPELINE_START, time.monotonic()))
+
+            executed: set[str] = set()
+            remaining = set(dep_graph.keys())
+
+            while remaining:
+                # Find phases whose dependencies are all satisfied
+                ready = [name for name in remaining if dep_graph[name].issubset(executed)]
+
+                if not ready:
+                    # Circular dependency or impossible state
+                    yield Put(
+                        Action(
+                            PHASE_FAILED,
+                            {"name": next(iter(remaining)), "error": "Unresolvable dependencies"},
+                        )
+                    )
+                    return
+
+                # Separate parallel and sequential phases
+                parallel_ready = [n for n in ready if phase_map[n].parallel]
+                sequential_ready = [n for n in ready if not phase_map[n].parallel]
+
+                # Run parallel phases concurrently via Fork
+                if parallel_ready:
+                    for name in parallel_ready:
+                        yield Fork(_make_phase_saga(name, phase_map[name].handler))
+                    # Mark them as executed (Fork runs concurrently)
+                    for name in parallel_ready:
+                        remaining.discard(name)
+                        executed.add(name)
+
+                # Run sequential phases one at a time
+                for name in sequential_ready:
+                    yield Put(Action(PHASE_START, name))
+                    try:
+                        result = yield Call(phase_map[name].handler)
+                        yield Put(Action(PHASE_COMPLETE, {"name": name, "result": result}))
+                    except Exception as e:
+                        yield Put(Action(PHASE_FAILED, {"name": name, "error": str(e)}))
+                        return
+                    remaining.discard(name)
+                    executed.add(name)
+
+            yield Put(Action(PIPELINE_COMPLETE))
+
+        return saga
+
+    def execution_order(self) -> list[str]:
+        """Return the topological execution order of phases."""
+        dep_graph = {p.name: set(p.depends_on) for p in self.phases}
+        order: list[str] = []
+        remaining = set(dep_graph.keys())
+
+        while remaining:
+            ready = [n for n in remaining if dep_graph[n].issubset(set(order))]
+            if not ready:
+                break
+            order.extend(sorted(ready))
+            remaining -= set(ready)
+
+        return order
+
+
+def _make_phase_saga(name: str, handler: Callable) -> Callable:
+    """Create a saga for a single phase (used by Fork for parallel phases)."""
+
+    def phase_saga():
+        yield Put(Action(PHASE_START, name))
+        try:
+            result = yield Call(handler)
+            yield Put(Action(PHASE_COMPLETE, {"name": name, "result": result}))
+        except Exception as e:
+            yield Put(Action(PHASE_FAILED, {"name": name, "error": str(e)}))
+
+    return phase_saga

milo/plugins.py

@@ -0,0 +1,168 @@
+"""Plugin system with hook registry and Store middleware integration."""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Callable
+from typing import Any
+
+from milo._errors import ErrorCode, PluginError
+from milo._types import Action
+
+
+class HookRegistry:
+    """Registry of named hooks that plugins can subscribe to.
+
+    Usage::
+
+        hooks = HookRegistry()
+        hooks.define("before_build")
+        hooks.define("after_phase", required_args=("phase_name",))
+
+        @hooks.on("before_build")
+        def my_plugin(config):
+            print("Building with", config)
+
+        # Invoke all listeners
+        hooks.invoke("before_build", config=my_config)
+
+        # Freeze after setup (optional but recommended)
+        hooks.freeze()
+
+        # Use as Store middleware
+        store = Store(reducer, state, middleware=(hooks.as_middleware(),))
+    """
+
+    def __init__(self) -> None:
+        self._hooks: dict[str, list[Callable]] = {}
+        self._action_map: dict[str, str] = {}  # action_type -> hook_name
+        self._frozen = False
+        self._lock = threading.Lock()
+
+    def define(
+        self,
+        name: str,
+        *,
+        action_type: str = "",
+        description: str = "",
+    ) -> None:
+        """Define a named hook point.
+
+        Args:
+            name: Hook name (e.g., "before_build", "after_phase").
+            action_type: If set, this hook fires automatically when
+                the Store dispatches an action of this type.
+            description: Human-readable description for docs/introspection.
+        """
+        if self._frozen:
+            raise PluginError(
+                ErrorCode.PLG_HOOK,
+                f"Cannot define hook '{name}' — registry is frozen",
+            )
+        with self._lock:
+            if name not in self._hooks:
+                self._hooks[name] = []
+            if action_type:
+                self._action_map[action_type] = name
+
+    def on(self, hook_name: str) -> Callable:
+        """Decorator to register a listener on a hook.
+
+        Usage::
+
+            @hooks.on("before_build")
+            def my_listener(config): ...
+        """
+
+        def decorator(fn: Callable) -> Callable:
+            self.register(hook_name, fn)
+            return fn
+
+        return decorator
+
+    def register(self, hook_name: str, fn: Callable) -> None:
+        """Register a listener function on a hook."""
+        if self._frozen:
+            raise PluginError(
+                ErrorCode.PLG_HOOK,
+                f"Cannot register on hook '{hook_name}' — registry is frozen",
+            )
+        with self._lock:
+            if hook_name not in self._hooks:
+                raise PluginError(
+                    ErrorCode.PLG_HOOK,
+                    f"Unknown hook '{hook_name}'",
+                    suggestion=f"Define it first with hooks.define('{hook_name}')",
+                )
+            self._hooks[hook_name].append(fn)
+
+    def invoke(self, hook_name: str, **kwargs: Any) -> list[Any]:
+        """Invoke all listeners registered on a hook.
+
+        Returns a list of return values from each listener.
+        Listeners are called in registration order.
+        """
+        with self._lock:
+            listeners = list(self._hooks.get(hook_name, []))
+
+        results = []
+        for fn in listeners:
+            try:
+                results.append(fn(**kwargs))
+            except Exception as e:
+                raise PluginError(
+                    ErrorCode.PLG_HOOK,
+                    f"Hook '{hook_name}' listener {getattr(fn, '__name__', repr(fn))!r} raised: {e}",
+                ) from e
+        return results
+
+    def freeze(self) -> None:
+        """Freeze the registry — no more defines or registrations."""
+        self._frozen = True
+
+    @property
+    def frozen(self) -> bool:
+        return self._frozen
+
+    def hook_names(self) -> tuple[str, ...]:
+        """Return all defined hook names."""
+        return tuple(self._hooks.keys())
+
+    def listeners(self, hook_name: str) -> tuple[Callable, ...]:
+        """Return all listeners for a hook."""
+        return tuple(self._hooks.get(hook_name, []))
+
+    def as_middleware(self) -> Callable:
+        """Return a Store middleware that fires hooks on matching actions.
+
+        The middleware intercepts actions whose type matches an
+        ``action_type`` registered via ``define()``, invokes the
+        corresponding hook, and then passes the action through.
+
+        Usage::
+
+            store = Store(reducer, state, middleware=(hooks.as_middleware(),))
+        """
+        action_map = self._action_map
+        registry = self
+
+        def middleware(store_api: Any) -> Callable:
+            def wrapper(next_dispatch: Callable) -> Callable:
+                def dispatch(action: Action) -> Any:
+                    # Fire hook before reducer processes the action
+                    hook_name = action_map.get(action.type)
+                    if hook_name:
+                        registry.invoke(
+                            hook_name,
+                            action=action,
+                            get_state=store_api.get_state
+                            if hasattr(store_api, "get_state")
+                            else lambda: None,
+                        )
+                    return next_dispatch(action)
+
+                return dispatch
+
+            return wrapper
+
+        return middleware

milo/registry.py

@@ -0,0 +1,213 @@
+"""Milo CLI registry — tracks installed CLIs for gateway discovery."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import subprocess
+import sys
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+_REGISTRY_DIR = Path.home() / ".milo"
+_REGISTRY_FILE = _REGISTRY_DIR / "registry.json"
+
+
+@dataclass(frozen=True, slots=True)
+class HealthResult:
+    """Result of a CLI health check."""
+
+    name: str
+    reachable: bool
+    latency_ms: float
+    error: str = ""
+    stale: bool = False
+
+
+def _load() -> dict[str, Any]:
+    """Load the registry file."""
+    if not _REGISTRY_FILE.exists():
+        return {"version": 1, "clis": {}}
+    try:
+        return json.loads(_REGISTRY_FILE.read_text())
+    except json.JSONDecodeError:
+        return {"version": 1, "clis": {}}
+    except OSError:
+        return {"version": 1, "clis": {}}
+
+
+def _save(data: dict[str, Any]) -> None:
+    """Save the registry file."""
+    _REGISTRY_DIR.mkdir(parents=True, exist_ok=True)
+    _REGISTRY_FILE.write_text(json.dumps(data, indent=2) + "\n")
+
+
+def install(
+    name: str,
+    command: list[str],
+    *,
+    description: str = "",
+    version: str = "",
+    project_root: str = "",
+) -> None:
+    """Register a CLI in the milo registry.
+
+    Args:
+        name: CLI name (used as namespace prefix in the gateway).
+        command: Shell command to start the CLI with --mcp.
+        description: Human-readable description.
+        version: CLI version string.
+        project_root: Absolute path to the project root.
+    """
+    data = _load()
+    entry: dict[str, Any] = {
+        "command": command,
+        "description": description,
+        "version": version,
+    }
+    if project_root:
+        entry["project_root"] = project_root
+        entry["fingerprint"] = fingerprint(command, project_root)
+    entry["installed_at"] = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+    data["clis"][name] = entry
+    _save(data)
+    sys.stderr.write(f"Registered {name!r} in {_REGISTRY_FILE}\n")
+    sys.stderr.write(f"  Command: {' '.join(command)}\n")
+    if description:
+        sys.stderr.write(f"  Description: {description}\n")
+    sys.stderr.write("\n")
+    sys.stderr.write("Tools are available via the milo gateway:\n")
+    sys.stderr.write("  uv run python -m milo.gateway --mcp\n")
+    sys.stderr.flush()
+
+
+def uninstall(name: str) -> bool:
+    """Remove a CLI from the milo registry. Returns True if it was found."""
+    data = _load()
+    if name not in data.get("clis", {}):
+        sys.stderr.write(f"{name!r} not found in registry\n")
+        return False
+    del data["clis"][name]
+    _save(data)
+    sys.stderr.write(f"Removed {name!r} from {_REGISTRY_FILE}\n")
+    return True
+
+
+def list_clis() -> dict[str, dict[str, Any]]:
+    """Return all registered CLIs."""
+    data = _load()
+    return data.get("clis", {})
+
+
+def registry_path() -> Path:
+    """Return the registry file path."""
+    return _REGISTRY_FILE
+
+
+def fingerprint(command: list[str], project_root: str) -> str:
+    """Compute a SHA-256 fingerprint for a CLI entry."""
+    content = json.dumps({"command": command, "project_root": project_root}, sort_keys=True)
+    return hashlib.sha256(content.encode()).hexdigest()
+
+
+def health_check(name: str) -> HealthResult:
+    """Ping a registered CLI with initialize and measure latency."""
+    data = _load()
+    clis = data.get("clis", {})
+    if name not in clis:
+        return HealthResult(name=name, reachable=False, latency_ms=0.0, error="Not registered")
+
+    info = clis[name]
+    command = info.get("command", [])
+    if not command:
+        return HealthResult(name=name, reachable=False, latency_ms=0.0, error="No command")
+
+    start = time.monotonic()
+    try:
+        input_data = '{"jsonrpc":"2.0","id":1,"method":"initialize"}\n'
+        result = subprocess.run(
+            command,
+            input=input_data,
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        elapsed = (time.monotonic() - start) * 1000
+
+        # Check for valid response
+        for line in result.stdout.strip().split("\n"):
+            if not line:
+                continue
+            try:
+                response = json.loads(line)
+                if response.get("id") == 1 and "result" in response:
+                    # Check staleness
+                    stored_fp = info.get("fingerprint", "")
+                    project_root = info.get("project_root", "")
+                    stale = False
+                    if stored_fp and project_root:
+                        current_fp = fingerprint(command, project_root)
+                        stale = current_fp != stored_fp
+                    return HealthResult(
+                        name=name,
+                        reachable=True,
+                        latency_ms=round(elapsed, 2),
+                        stale=stale,
+                    )
+            except json.JSONDecodeError:
+                continue
+
+        return HealthResult(
+            name=name,
+            reachable=False,
+            latency_ms=round(elapsed, 2),
+            error="No valid response",
+        )
+    except subprocess.TimeoutExpired:
+        elapsed = (time.monotonic() - start) * 1000
+        return HealthResult(
+            name=name, reachable=False, latency_ms=round(elapsed, 2), error="Timeout"
+        )
+    except Exception as e:
+        elapsed = (time.monotonic() - start) * 1000
+        return HealthResult(name=name, reachable=False, latency_ms=round(elapsed, 2), error=str(e))
+
+
+def check_all() -> list[HealthResult]:
+    """Run health checks on all registered CLIs."""
+    clis = list_clis()
+    return [health_check(name) for name in clis]
+
+
+def doctor() -> str:
+    """Generate a diagnostic report for all registered CLIs."""
+    clis = list_clis()
+    if not clis:
+        return "No CLIs registered. Use --mcp-install on a milo CLI.\n"
+
+    lines: list[str] = []
+    lines.append("milo gateway — diagnostic report")
+    lines.append(f"Registry: {_REGISTRY_FILE}")
+    lines.append(f"CLIs: {len(clis)}")
+    lines.append("")
+
+    results = check_all()
+    for r in results:
+        status = "OK" if r.reachable else "FAIL"
+        stale_marker = " [STALE]" if r.stale else ""
+        lines.append(f"  {r.name}: {status} ({r.latency_ms:.0f}ms){stale_marker}")
+        if r.error:
+            lines.append(f"    Error: {r.error}")
+
+    lines.append("")
+
+    healthy = sum(1 for r in results if r.reachable)
+    lines.append(f"Summary: {healthy}/{len(results)} reachable")
+    stale = sum(1 for r in results if r.stale)
+    if stale:
+        lines.append(f"  {stale} stale (fingerprint mismatch)")
+    lines.append("")
+    return "\n".join(lines)