milo-cli 0.1.0__py3-none-any.whl

milo/__init__.py

@@ -0,0 +1,183 @@
+"""Milo — Template-driven CLI applications for free-threaded Python."""
+
+from __future__ import annotations
+
+
+def __getattr__(name: str):
+    """Lazy imports for public API."""
+    _imports = {
+        # Types
+        "Action": "_types",
+        "Key": "_types",
+        "SpecialKey": "_types",
+        "AppStatus": "_types",
+        "RenderTarget": "_types",
+        "FieldType": "_types",
+        "FieldSpec": "_types",
+        "FieldState": "_types",
+        "FormState": "_types",
+        "Screen": "_types",
+        "Transition": "_types",
+        "ReducerResult": "_types",
+        "Quit": "_types",
+        "Call": "_types",
+        "Put": "_types",
+        "Select": "_types",
+        "Fork": "_types",
+        "Delay": "_types",
+        "BUILTIN_ACTIONS": "_types",
+        # Errors
+        "MiloError": "_errors",
+        "InputError": "_errors",
+        "StateError": "_errors",
+        "FormError": "_errors",
+        "AppError": "_errors",
+        "FlowError": "_errors",
+        "ConfigError": "_errors",
+        "PipelineError": "_errors",
+        "PluginError": "_errors",
+        "ErrorCode": "_errors",
+        "format_error": "_errors",
+        "format_render_error": "_errors",
+        # State
+        "Store": "state",
+        "combine_reducers": "state",
+        # App
+        "App": "app",
+        "run": "app",
+        "render_html": "app",
+        # Flow
+        "FlowScreen": "flow",
+        "Flow": "flow",
+        "FlowState": "flow",
+        # Form
+        "form": "form",
+        "form_reducer": "form",
+        "make_form_reducer": "form",
+        # Help
+        "HelpRenderer": "help",
+        # Dev
+        "DevServer": "dev",
+        # Commands (AI-native)
+        "CLI": "commands",
+        "CommandDef": "commands",
+        "LazyCommandDef": "commands",
+        # Groups
+        "Group": "groups",
+        "GroupDef": "groups",
+        "GlobalOption": "commands",
+        # Context
+        "Context": "context",
+        "get_context": "context",
+        # Config
+        "Config": "config",
+        "ConfigSpec": "config",
+        # Pipeline
+        "Pipeline": "pipeline",
+        "Phase": "pipeline",
+        "PipelineState": "pipeline",
+        "PhaseStatus": "pipeline",
+        # Plugins
+        "HookRegistry": "plugins",
+        "function_to_schema": "schema",
+        "format_output": "output",
+        "write_output": "output",
+        "generate_llms_txt": "llms",
+        # Commands v2 (resources, prompts)
+        "ResourceDef": "commands",
+        "PromptDef": "commands",
+        # Middleware
+        "MCPCall": "middleware",
+        "MiddlewareStack": "middleware",
+        # Streaming
+        "Progress": "streaming",
+        # Observability
+        "RequestLog": "observability",
+        "RequestLogger": "observability",
+    }
+    if name in _imports:
+        import importlib
+
+        module = importlib.import_module(f"milo.{_imports[name]}")
+        return getattr(module, name)
+    raise AttributeError(f"module 'milo' has no attribute {name!r}")
+
+
+# Free-threaded Python marker (PEP 703)
+def _Py_mod_gil() -> int:  # noqa: N802
+    return 0
+
+
+__version__ = "0.1.0"
+__all__ = [
+    "BUILTIN_ACTIONS",
+    "CLI",
+    "Action",
+    "App",
+    "AppError",
+    "AppStatus",
+    "Call",
+    "CommandDef",
+    "Config",
+    "ConfigError",
+    "ConfigSpec",
+    "Context",
+    "Delay",
+    "DevServer",
+    "ErrorCode",
+    "FieldSpec",
+    "FieldState",
+    "FieldType",
+    "Flow",
+    "FlowError",
+    "FlowScreen",
+    "FlowState",
+    "Fork",
+    "FormError",
+    "FormState",
+    "GlobalOption",
+    "Group",
+    "GroupDef",
+    "HelpRenderer",
+    "HookRegistry",
+    "InputError",
+    "Key",
+    "LazyCommandDef",
+    "MCPCall",
+    "MiddlewareStack",
+    "MiloError",
+    "Phase",
+    "PhaseStatus",
+    "Pipeline",
+    "PipelineError",
+    "PipelineState",
+    "PluginError",
+    "Progress",
+    "PromptDef",
+    "Put",
+    "Quit",
+    "ReducerResult",
+    "RenderTarget",
+    "RequestLog",
+    "RequestLogger",
+    "ResourceDef",
+    "Screen",
+    "Select",
+    "SpecialKey",
+    "StateError",
+    "Store",
+    "Transition",
+    "combine_reducers",
+    "form",
+    "form_reducer",
+    "format_error",
+    "format_output",
+    "format_render_error",
+    "function_to_schema",
+    "generate_llms_txt",
+    "get_context",
+    "make_form_reducer",
+    "render_html",
+    "run",
+    "write_output",
+]

milo/_child.py

@@ -0,0 +1,141 @@
+"""Persistent child process for MCP gateway communication."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import threading
+import time
+from typing import Any
+
+
+class ChildProcess:
+    """A persistent child process that speaks JSON-RPC on stdin/stdout.
+
+    Thread-safe: a lock serializes all calls to the same child.
+    Auto-reconnects if the child process dies.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        command: list[str],
+        *,
+        idle_timeout: float = 300.0,
+    ) -> None:
+        self.name = name
+        self.command = command
+        self.idle_timeout = idle_timeout
+        self._proc: subprocess.Popen[str] | None = None
+        self._lock = threading.Lock()
+        self._last_use = time.monotonic()
+        self._request_id = 0
+        self._initialized = False
+
+    def _spawn(self) -> None:
+        """Start the child process with persistent pipes."""
+        self._proc = subprocess.Popen(
+            self.command,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            bufsize=1,  # line-buffered
+        )
+        self._initialized = False
+        self._request_id = 0
+
+    def _ensure_initialized(self) -> None:
+        """Send initialize if not already done."""
+        if self._initialized:
+            return
+        self._request_id += 1
+        req = {
+            "jsonrpc": "2.0",
+            "id": self._request_id,
+            "method": "initialize",
+        }
+        self._write_line(json.dumps(req))
+        self._read_line()  # consume initialize response
+        # Send notifications/initialized
+        notif = {"jsonrpc": "2.0", "method": "notifications/initialized"}
+        self._write_line(json.dumps(notif))
+        self._initialized = True
+
+    def ensure_alive(self) -> None:
+        """Spawn or reconnect if the child process is dead."""
+        with self._lock:
+            if self._proc is None or self._proc.poll() is not None:
+                self._spawn()
+                self._ensure_initialized()
+
+    def send_call(self, method: str, params: dict[str, Any]) -> dict[str, Any]:
+        """Send a JSON-RPC request and return the result. Thread-safe."""
+        with self._lock:
+            if self._proc is None or self._proc.poll() is not None:
+                self._spawn()
+                self._ensure_initialized()
+
+            self._request_id += 1
+            req_id = self._request_id
+            request = {
+                "jsonrpc": "2.0",
+                "id": req_id,
+                "method": method,
+                "params": params,
+            }
+            self._write_line(json.dumps(request))
+            response_line = self._read_line()
+            self._last_use = time.monotonic()
+
+            if not response_line:
+                return {"error": {"code": -32603, "message": f"No response from {self.name}"}}
+
+            try:
+                response = json.loads(response_line)
+            except json.JSONDecodeError:
+                return {"error": {"code": -32700, "message": "Parse error from child"}}
+
+            if "error" in response:
+                return response
+            return response.get("result", {})
+
+    def fetch_tools(self) -> list[dict[str, Any]]:
+        """Fetch tools/list from the child process."""
+        result = self.send_call("tools/list", {})
+        return result.get("tools", [])
+
+    def is_idle(self) -> bool:
+        """Check if the child has been idle longer than idle_timeout."""
+        return (time.monotonic() - self._last_use) > self.idle_timeout
+
+    def kill(self) -> None:
+        """Kill the child process."""
+        with self._lock:
+            if self._proc is not None:
+                try:
+                    self._proc.terminate()
+                    self._proc.wait(timeout=5)
+                except ProcessLookupError:
+                    pass
+                except subprocess.TimeoutExpired:
+                    import contextlib
+
+                    with contextlib.suppress(ProcessLookupError):
+                        self._proc.kill()
+                self._proc = None
+                self._initialized = False
+
+    def _write_line(self, line: str) -> None:
+        """Write a line to the child's stdin."""
+        assert self._proc is not None
+        assert self._proc.stdin is not None
+        self._proc.stdin.write(line + "\n")
+        self._proc.stdin.flush()
+
+    def _read_line(self) -> str:
+        """Read a line from the child's stdout."""
+        assert self._proc is not None
+        assert self._proc.stdout is not None
+        line = self._proc.stdout.readline()
+        return line.strip()

milo/_errors.py

@@ -0,0 +1,189 @@
+"""Structured error hierarchy with format_compact() for terminal display."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+
+class ErrorCode(Enum):
+    # Input errors
+    INP_RAW_MODE = "M-INP-001"
+    INP_ESCAPE_PARSE = "M-INP-002"
+    INP_READ = "M-INP-003"
+
+    # State errors
+    STA_REDUCER = "M-STA-001"
+    STA_DISPATCH = "M-STA-002"
+    STA_SAGA = "M-STA-003"
+    STA_COMBINE = "M-STA-004"
+
+    # App errors
+    APP_LIFECYCLE = "M-APP-001"
+    APP_RENDER = "M-APP-002"
+    APP_TEMPLATE = "M-APP-003"
+
+    # Form errors
+    FRM_VALIDATION = "M-FRM-001"
+    FRM_FIELD = "M-FRM-002"
+    FRM_SUBMIT = "M-FRM-003"
+
+    # Flow errors
+    FLW_TRANSITION = "M-FLW-001"
+    FLW_SCREEN = "M-FLW-002"
+    FLW_DUPLICATE = "M-FLW-003"
+
+    # Dev errors
+    DEV_WATCH = "M-DEV-001"
+    DEV_RELOAD = "M-DEV-002"
+
+    # Config errors
+    CFG_PARSE = "M-CFG-001"
+    CFG_MERGE = "M-CFG-002"
+    CFG_VALIDATE = "M-CFG-003"
+    CFG_MISSING = "M-CFG-004"
+
+    # Pipeline errors
+    PIP_PHASE = "M-PIP-001"
+    PIP_TIMEOUT = "M-PIP-002"
+    PIP_DEPENDENCY = "M-PIP-003"
+
+    # Plugin errors
+    PLG_LOAD = "M-PLG-001"
+    PLG_HOOK = "M-PLG-002"
+
+    # Command errors
+    CMD_NOT_FOUND = "M-CMD-001"
+    CMD_AMBIGUOUS = "M-CMD-002"
+
+
+class MiloError(Exception):
+    """Base error for all milo errors."""
+
+    def __init__(
+        self,
+        code: ErrorCode,
+        message: str,
+        *,
+        suggestion: str = "",
+        context: dict[str, Any] | None = None,
+        docs_url: str = "",
+    ) -> None:
+        self.code = code
+        self.message = message
+        self.suggestion = suggestion
+        self.context = context or {}
+        self.docs_url = docs_url
+        super().__init__(f"[{code.value}] {message}")
+
+    def format_compact(self) -> str:
+        """Format error for terminal display, consistent with kida's format_compact()."""
+        parts = [f"{self.code.value}: {self.message}"]
+        if self.suggestion:
+            parts.append(f"  hint: {self.suggestion}")
+        if self.docs_url:
+            parts.append(f"  docs: {self.docs_url}")
+        return "\n".join(parts)
+
+
+class InputError(MiloError):
+    """Input-related errors (raw mode, escape parsing)."""
+
+
+class StateError(MiloError):
+    """State-related errors (reducer, dispatch, saga)."""
+
+
+class FormError(MiloError):
+    """Form-related errors (validation, field)."""
+
+
+class AppError(MiloError):
+    """App lifecycle errors."""
+
+
+class FlowError(MiloError):
+    """Flow errors (transitions, screens)."""
+
+
+class DevError(MiloError):
+    """Dev server errors (watch, reload)."""
+
+
+class ConfigError(MiloError):
+    """Configuration errors (parse, merge, validate)."""
+
+
+class PipelineError(MiloError):
+    """Pipeline orchestration errors (phase, timeout, dependency)."""
+
+
+class PluginError(MiloError):
+    """Plugin system errors (load, hook)."""
+
+
+def format_error(error: Exception) -> str:
+    """Format any error for terminal display.
+
+    Uses format_compact() for kida TemplateErrors and MiloErrors.
+    Falls back to str() for other exceptions.
+    """
+    if hasattr(error, "format_compact"):
+        return error.format_compact()
+    return f"{type(error).__name__}: {error}"
+
+
+def format_render_error(
+    error: Exception,
+    *,
+    template_name: str = "",
+    env: Any = None,
+) -> str:
+    """Format a render error with optional error template rendering.
+
+    Tries to render through the built-in error.txt template.
+    Falls back to format_error() if template rendering fails.
+    """
+    compact = format_error(error)
+
+    # Try to render through error template
+    if env is not None:
+        try:
+            tmpl = env.get_template("error.kida")
+            return tmpl.render(
+                error=compact,
+                code=_get_error_code(error),
+                template_name=template_name,
+                message=str(error),
+                hint=_get_hint(error),
+                docs_url=_get_docs_url(error),
+            )
+        except Exception:
+            pass
+
+    return compact
+
+
+def _get_error_code(error: Exception) -> str:
+    """Extract error code string from any error."""
+    if isinstance(error, MiloError):
+        return error.code.value
+    if hasattr(error, "code") and error.code is not None:
+        return str(error.code.value) if hasattr(error.code, "value") else str(error.code)
+    return ""
+
+
+def _get_hint(error: Exception) -> str:
+    """Extract hint/suggestion from an error."""
+    if hasattr(error, "suggestion") and error.suggestion:
+        return str(error.suggestion)
+    return ""
+
+
+def _get_docs_url(error: Exception) -> str:
+    """Extract docs URL from an error."""
+    if hasattr(error, "docs_url") and error.docs_url:
+        return str(error.docs_url)
+    if hasattr(error, "code") and hasattr(error.code, "docs_url"):
+        return str(error.code.docs_url)
+    return ""

milo/_protocols.py

@@ -0,0 +1,37 @@
+"""Protocols — stdlib/typing only, no internal imports."""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+from milo._types import Action, ReducerResult
+
+
+@runtime_checkable
+class Reducer(Protocol):
+    def __call__(self, state: Any, action: Action) -> Any | ReducerResult: ...
+
+
+@runtime_checkable
+class Saga(Protocol):
+    def __call__(self, *args: Any, **kwargs: Any) -> Any: ...
+
+
+@runtime_checkable
+class DispatchFn(Protocol):
+    def __call__(self, action: Action) -> None: ...
+
+
+@runtime_checkable
+class Middleware(Protocol):
+    def __call__(self, dispatch: DispatchFn, get_state: GetStateFn) -> DispatchFn: ...
+
+
+@runtime_checkable
+class GetStateFn(Protocol):
+    def __call__(self) -> Any: ...
+
+
+@runtime_checkable
+class FieldValidator(Protocol):
+    def __call__(self, value: Any) -> tuple[bool, str]: ...