milo-cli 0.1.0__py3-none-any.whl

milo/gateway.py

@@ -0,0 +1,393 @@
+"""Milo MCP gateway — one MCP server that proxies to all registered CLIs.
+
+Register this once with your AI host:
+
+    claude mcp add milo -- uv run python -m milo.gateway --mcp
+
+Then every CLI registered via ``--mcp-install`` is discoverable.
+Tools are namespaced: ``taskman.add``, ``ghub.repo.list``, etc.
+
+Can also be run directly for debugging:
+
+    uv run python -m milo.gateway --mcp
+    uv run python -m milo.gateway --list
+    uv run python -m milo.gateway --doctor
+    uv run python -m milo.gateway --status
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import threading
+import time
+from typing import Any
+
+from milo._child import ChildProcess
+from milo.registry import list_clis
+
+_MCP_VERSION = "2025-11-25"
+
+
+def main() -> None:
+    """Entry point for ``python -m milo.gateway``."""
+    if "--list" in sys.argv:
+        _print_registry()
+        return
+    if "--doctor" in sys.argv:
+        from milo.registry import doctor
+
+        sys.stdout.write(doctor())
+        return
+    if "--status" in sys.argv:
+        _print_status()
+        return
+    if "--mcp" in sys.argv:
+        _run_gateway()
+        return
+    # Default: show help
+    sys.stderr.write("milo gateway — one MCP server for all your CLIs\n\n")
+    sys.stderr.write("Usage:\n")
+    sys.stderr.write("  python -m milo.gateway --mcp      Run as MCP server\n")
+    sys.stderr.write("  python -m milo.gateway --list      List registered CLIs\n")
+    sys.stderr.write("  python -m milo.gateway --doctor    Health check all CLIs\n")
+    sys.stderr.write("  python -m milo.gateway --status    Show stats and children\n")
+    sys.stderr.write("\nRegister CLIs with: myapp --mcp-install\n")
+
+
+def _print_registry() -> None:
+    """Print all registered CLIs."""
+    clis = list_clis()
+    if not clis:
+        sys.stderr.write("No CLIs registered. Use --mcp-install on a milo CLI.\n")
+        return
+    for name, info in clis.items():
+        desc = info.get("description", "")
+        ver = info.get("version", "")
+        cmd = " ".join(info.get("command", []))
+        label = f"{name} {ver}".strip()
+        sys.stdout.write(f"{label}\n")
+        if desc:
+            sys.stdout.write(f"  {desc}\n")
+        sys.stdout.write(f"  {cmd}\n\n")
+
+
+def _print_status() -> None:
+    """Print gateway status (placeholder for F7 observability)."""
+    clis = list_clis()
+    sys.stdout.write(f"Registered CLIs: {len(clis)}\n")
+    for name in clis:
+        sys.stdout.write(f"  {name}\n")
+
+
+def _run_gateway() -> None:
+    """Run the MCP gateway server with persistent child processes."""
+    clis = list_clis()
+
+    # Create persistent children for each CLI
+    children: dict[str, ChildProcess] = {}
+    for cli_name, info in clis.items():
+        command = info.get("command", [])
+        if command:
+            children[cli_name] = ChildProcess(cli_name, command)
+
+    # Discover tools from all registered CLIs
+    all_tools, tool_routing = _discover_tools(clis, children)
+    tool_names = [t["name"] for t in all_tools]
+
+    # Discover resources and prompts
+    all_resources, resource_routing = _discover_resources(clis, children)
+    all_prompts, prompt_routing = _discover_prompts(clis, children)
+
+    _stderr("milo gateway ready")
+    _stderr(f"  Protocol:  {_MCP_VERSION}")
+    _stderr(f"  CLIs:      {len(clis)} ({', '.join(clis.keys()) if clis else 'none'})")
+    _stderr(f"  Tools:     {len(all_tools)}")
+    _stderr(f"  Resources: {len(all_resources)}")
+    _stderr(f"  Prompts:   {len(all_prompts)}")
+    if tool_names:
+        _stderr(f"  Available: {', '.join(tool_names)}")
+    _stderr("")
+    _stderr("Press Ctrl+C to stop.")
+    _stderr("")
+
+    # Start idle reaper thread
+    reaper = threading.Thread(target=_idle_reaper, args=(children,), daemon=True)
+    reaper.start()
+
+    try:
+        for line in sys.stdin:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                request = json.loads(line)
+            except json.JSONDecodeError:
+                _write_error(None, -32700, "Parse error")
+                continue
+
+            req_id = request.get("id")
+            method = request.get("method", "")
+
+            try:
+                result = _handle_method(
+                    clis,
+                    all_tools,
+                    tool_routing,
+                    all_resources,
+                    resource_routing,
+                    all_prompts,
+                    prompt_routing,
+                    children,
+                    method,
+                    request.get("params", {}),
+                )
+                if result is not None:
+                    _write_result(req_id, result)
+            except Exception as e:
+                _write_error(req_id, -32603, str(e))
+    finally:
+        # Clean up children on exit
+        for child in children.values():
+            child.kill()
+
+
+def _idle_reaper(children: dict[str, ChildProcess]) -> None:
+    """Periodically check and kill idle children."""
+    while True:
+        time.sleep(60)
+        for child in list(children.values()):
+            if child.is_idle():
+                _stderr(f"  Reaping idle child: {child.name}")
+                child.kill()
+
+
+def _discover_tools(
+    clis: dict[str, dict[str, Any]],
+    children: dict[str, ChildProcess],
+) -> tuple[list[dict[str, Any]], dict[str, tuple[str, str]]]:
+    """Discover tools from all registered CLIs via persistent children."""
+    all_tools: list[dict[str, Any]] = []
+    routing: dict[str, tuple[str, str]] = {}
+
+    for cli_name in clis:
+        child = children.get(cli_name)
+        if not child:
+            continue
+
+        try:
+            tools = child.fetch_tools()
+        except Exception as e:
+            _stderr(f"  Warning: failed to discover {cli_name}: {e}")
+            continue
+
+        for tool in tools:
+            original_name = tool["name"]
+            namespaced = f"{cli_name}.{original_name}"
+            tool["name"] = namespaced
+            if "title" not in tool:
+                tool["title"] = f"{cli_name}: {tool.get('description', original_name)}"
+            all_tools.append(tool)
+            routing[namespaced] = (cli_name, original_name)
+
+    return all_tools, routing
+
+
+def _discover_resources(
+    clis: dict[str, dict[str, Any]],
+    children: dict[str, ChildProcess],
+) -> tuple[list[dict[str, Any]], dict[str, tuple[str, str]]]:
+    """Discover resources from all registered CLIs."""
+    all_resources: list[dict[str, Any]] = []
+    routing: dict[str, tuple[str, str]] = {}
+
+    for cli_name in clis:
+        child = children.get(cli_name)
+        if not child:
+            continue
+
+        try:
+            result = child.send_call("resources/list", {})
+            resources = result.get("resources", [])
+        except Exception:
+            continue
+
+        for resource in resources:
+            original_uri = resource["uri"]
+            namespaced_uri = f"{cli_name}/{original_uri}"
+            resource["uri"] = namespaced_uri
+            all_resources.append(resource)
+            routing[namespaced_uri] = (cli_name, original_uri)
+
+    return all_resources, routing
+
+
+def _discover_prompts(
+    clis: dict[str, dict[str, Any]],
+    children: dict[str, ChildProcess],
+) -> tuple[list[dict[str, Any]], dict[str, tuple[str, str]]]:
+    """Discover prompts from all registered CLIs."""
+    all_prompts: list[dict[str, Any]] = []
+    routing: dict[str, tuple[str, str]] = {}
+
+    for cli_name in clis:
+        child = children.get(cli_name)
+        if not child:
+            continue
+
+        try:
+            result = child.send_call("prompts/list", {})
+            prompts = result.get("prompts", [])
+        except Exception:
+            continue
+
+        for prompt in prompts:
+            original_name = prompt["name"]
+            namespaced = f"{cli_name}.{original_name}"
+            prompt["name"] = namespaced
+            all_prompts.append(prompt)
+            routing[namespaced] = (cli_name, original_name)
+
+    return all_prompts, routing
+
+
+def _handle_method(
+    clis: dict[str, dict[str, Any]],
+    all_tools: list[dict[str, Any]],
+    tool_routing: dict[str, tuple[str, str]],
+    all_resources: list[dict[str, Any]],
+    resource_routing: dict[str, tuple[str, str]],
+    all_prompts: list[dict[str, Any]],
+    prompt_routing: dict[str, tuple[str, str]],
+    children: dict[str, ChildProcess],
+    method: str,
+    params: dict[str, Any],
+) -> dict[str, Any] | None:
+    """Dispatch an MCP method."""
+    match method:
+        case "initialize":
+            cli_names = list(clis.keys())
+            return {
+                "protocolVersion": _MCP_VERSION,
+                "capabilities": {"tools": {}, "resources": {}, "prompts": {}},
+                "serverInfo": {
+                    "name": "milo-gateway",
+                    "version": "0.1.0",
+                    "title": "Milo Gateway",
+                },
+                "instructions": (
+                    f"Gateway to {len(clis)} milo CLIs: {', '.join(cli_names)}. "
+                    "Tools are namespaced as cli_name.command_name."
+                ),
+            }
+        case "notifications/initialized":
+            return None
+        case "tools/list":
+            return {"tools": all_tools}
+        case "tools/call":
+            return _proxy_call(children, tool_routing, params)
+        case "resources/list":
+            return {"resources": all_resources}
+        case "resources/read":
+            return _proxy_resource(children, resource_routing, params)
+        case "prompts/list":
+            return {"prompts": all_prompts}
+        case "prompts/get":
+            return _proxy_prompt(children, prompt_routing, params)
+        case _:
+            raise ValueError(f"Unknown method: {method!r}")
+
+
+def _proxy_call(
+    children: dict[str, ChildProcess],
+    tool_routing: dict[str, tuple[str, str]],
+    params: dict[str, Any],
+) -> dict[str, Any]:
+    """Proxy a tools/call to the appropriate child process."""
+    tool_name = params.get("name", "")
+    arguments = params.get("arguments", {})
+
+    if tool_name not in tool_routing:
+        return {
+            "content": [{"type": "text", "text": f"Unknown tool: {tool_name!r}"}],
+            "isError": True,
+        }
+
+    cli_name, original_name = tool_routing[tool_name]
+    child = children.get(cli_name)
+    if not child:
+        return {
+            "content": [{"type": "text", "text": f"CLI {cli_name!r} not available"}],
+            "isError": True,
+        }
+
+    result = child.send_call("tools/call", {"name": original_name, "arguments": arguments})
+    if "error" in result:
+        return {
+            "content": [{"type": "text", "text": result["error"].get("message", "Unknown error")}],
+            "isError": True,
+        }
+    return result
+
+
+def _proxy_resource(
+    children: dict[str, ChildProcess],
+    resource_routing: dict[str, tuple[str, str]],
+    params: dict[str, Any],
+) -> dict[str, Any]:
+    """Proxy a resources/read to the appropriate child process."""
+    uri = params.get("uri", "")
+    if uri not in resource_routing:
+        return {"contents": []}
+
+    cli_name, original_uri = resource_routing[uri]
+    child = children.get(cli_name)
+    if not child:
+        return {"contents": []}
+
+    return child.send_call("resources/read", {"uri": original_uri})
+
+
+def _proxy_prompt(
+    children: dict[str, ChildProcess],
+    prompt_routing: dict[str, tuple[str, str]],
+    params: dict[str, Any],
+) -> dict[str, Any]:
+    """Proxy a prompts/get to the appropriate child process."""
+    name = params.get("name", "")
+    if name not in prompt_routing:
+        return {"messages": []}
+
+    cli_name, original_name = prompt_routing[name]
+    child = children.get(cli_name)
+    if not child:
+        return {"messages": []}
+
+    return child.send_call(
+        "prompts/get", {"name": original_name, "arguments": params.get("arguments", {})}
+    )
+
+
+def _write_result(req_id: Any, result: dict[str, Any]) -> None:
+    response = {"jsonrpc": "2.0", "id": req_id, "result": result}
+    sys.stdout.write(json.dumps(response) + "\n")
+    sys.stdout.flush()
+
+
+def _write_error(req_id: Any, code: int, message: str) -> None:
+    response = {
+        "jsonrpc": "2.0",
+        "id": req_id,
+        "error": {"code": code, "message": message},
+    }
+    sys.stdout.write(json.dumps(response) + "\n")
+    sys.stdout.flush()
+
+
+def _stderr(message: str) -> None:
+    sys.stderr.write(message + "\n")
+    sys.stderr.flush()
+
+
+if __name__ == "__main__":
+    main()

milo/groups.py

@@ -0,0 +1,194 @@
+"""Nestable command groups for hierarchical CLI structures."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+from milo.schema import function_to_schema
+
+
+@dataclass(frozen=True, slots=True)
+class GroupDef:
+    """Frozen snapshot of a command group."""
+
+    name: str
+    description: str
+    commands: dict[str, Any] = field(default_factory=dict)  # str -> CommandDef
+    groups: dict[str, GroupDef] = field(default_factory=dict)
+    aliases: tuple[str, ...] = ()
+    hidden: bool = False
+
+
+class Group:
+    """A nestable command namespace.
+
+    Usage::
+
+        site = cli.group("site", description="Site operations")
+
+        @site.command("build", description="Build the site")
+        def build(output: str = "_site") -> str: ...
+
+        config = site.group("config", description="Config management")
+
+        @config.command("show", description="Show merged config")
+        def show() -> dict: ...
+
+    CLI::
+
+        myapp site build --output _site
+        myapp site config show
+    """
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        description: str = "",
+        aliases: tuple[str, ...] | list[str] = (),
+        hidden: bool = False,
+    ) -> None:
+        self.name = name
+        self.description = description
+        self.aliases = tuple(aliases)
+        self.hidden = hidden
+        self._commands: dict[str, Any] = {}  # str -> CommandDef
+        self._alias_map: dict[str, str] = {}
+        self._groups: dict[str, Group] = {}
+        self._group_alias_map: dict[str, str] = {}
+
+    def command(
+        self,
+        name: str,
+        *,
+        description: str = "",
+        aliases: tuple[str, ...] | list[str] = (),
+        tags: tuple[str, ...] | list[str] = (),
+        hidden: bool = False,
+    ) -> Callable:
+        """Register a function as a command within this group."""
+        from milo.commands import CommandDef
+
+        def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+            schema = function_to_schema(func)
+            desc = description or func.__doc__ or ""
+            if "\n" in desc:
+                desc = desc.strip().split("\n")[0].strip()
+
+            cmd = CommandDef(
+                name=name,
+                description=desc,
+                handler=func,
+                schema=schema,
+                aliases=tuple(aliases),
+                tags=tuple(tags),
+                hidden=hidden,
+            )
+            self._commands[name] = cmd
+            for alias in aliases:
+                self._alias_map[alias] = name
+
+            return func
+
+        return decorator
+
+    def lazy_command(
+        self,
+        name: str,
+        import_path: str,
+        *,
+        description: str = "",
+        schema: dict[str, Any] | None = None,
+        aliases: tuple[str, ...] | list[str] = (),
+        tags: tuple[str, ...] | list[str] = (),
+        hidden: bool = False,
+    ) -> Any:
+        """Register a lazy-loaded command within this group.
+
+        The handler module is not imported until the command is invoked.
+        """
+        from milo.commands import LazyCommandDef
+
+        cmd = LazyCommandDef(
+            name=name,
+            import_path=import_path,
+            description=description,
+            schema=schema,
+            aliases=aliases,
+            tags=tags,
+            hidden=hidden,
+        )
+        self._commands[name] = cmd
+        for alias in aliases:
+            self._alias_map[alias] = name
+        return cmd
+
+    def group(
+        self,
+        name: str,
+        *,
+        description: str = "",
+        aliases: tuple[str, ...] | list[str] = (),
+        hidden: bool = False,
+    ) -> Group:
+        """Create and register a sub-group. Returns it for chaining."""
+        sub = Group(name, description=description, aliases=aliases, hidden=hidden)
+        self._groups[name] = sub
+        for alias in aliases:
+            self._group_alias_map[alias] = name
+        return sub
+
+    def add_group(self, group: Group) -> None:
+        """Add an existing Group as a sub-group."""
+        self._groups[group.name] = group
+        for alias in group.aliases:
+            self._group_alias_map[alias] = group.name
+
+    @property
+    def commands(self) -> dict[str, Any]:
+        """All registered commands in this group."""
+        return dict(self._commands)
+
+    @property
+    def groups(self) -> dict[str, Group]:
+        """All registered sub-groups."""
+        return dict(self._groups)
+
+    def get_command(self, name: str) -> Any | None:
+        """Look up a command by name or alias within this group."""
+        if name in self._commands:
+            return self._commands[name]
+        resolved = self._alias_map.get(name)
+        if resolved:
+            return self._commands.get(resolved)
+        return None
+
+    def get_group(self, name: str) -> Group | None:
+        """Look up a sub-group by name or alias."""
+        if name in self._groups:
+            return self._groups[name]
+        resolved = self._group_alias_map.get(name)
+        if resolved:
+            return self._groups.get(resolved)
+        return None
+
+    def to_def(self) -> GroupDef:
+        """Freeze into immutable GroupDef tree."""
+        return GroupDef(
+            name=self.name,
+            description=self.description,
+            commands=dict(self._commands),
+            groups={n: g.to_def() for n, g in self._groups.items()},
+            aliases=self.aliases,
+            hidden=self.hidden,
+        )
+
+    def walk_commands(self, prefix: str = "") -> list[tuple[str, Any]]:
+        """Yield (dotted_path, CommandDef) for all commands in this tree."""
+        path_prefix = f"{prefix}{self.name}." if prefix else f"{self.name}."
+        result = [(f"{path_prefix}{cmd.name}", cmd) for cmd in self._commands.values()]
+        for group in self._groups.values():
+            result.extend(group.walk_commands(path_prefix))
+        return result

milo/help.py

@@ -0,0 +1,84 @@
+"""HelpRenderer — argparse formatter_class for styled help output."""
+
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class HelpState:
+    """State for help rendering."""
+
+    prog: str = ""
+    description: str = ""
+    epilog: str = ""
+    usage: str = ""
+    groups: tuple[dict[str, Any], ...] = ()
+
+
+class HelpRenderer(argparse.HelpFormatter):
+    """Argparse formatter that renders through kida templates.
+
+    Usage::
+
+        parser = argparse.ArgumentParser(
+            formatter_class=HelpRenderer,
+        )
+    """
+
+    def __init__(
+        self,
+        prog: str,
+        indent_increment: int = 2,
+        max_help_position: int = 24,
+        width: int | None = None,
+    ) -> None:
+        super().__init__(prog, indent_increment, max_help_position, width)
+        self._prog = prog
+
+    def format_help(self) -> str:
+        """Format help using kida template if available, else fall back to default."""
+        try:
+            return self._render_with_template()
+        except Exception:
+            return super().format_help()
+
+    def _render_with_template(self) -> str:
+        """Render help through the kida help template."""
+        from milo.templates import get_env
+
+        env = get_env()
+        template = env.get_template("help.kida")
+
+        groups = []
+        for action_group in self._action_groups:  # type: ignore[attr-defined]
+            actions = [
+                {
+                    "option_strings": action.option_strings,
+                    "dest": action.dest,
+                    "help": action.help or "",
+                    "default": action.default,
+                    "required": getattr(action, "required", False),
+                    "choices": action.choices,
+                    "nargs": action.nargs,
+                    "metavar": action.metavar,
+                }
+                for action in action_group._group_actions
+            ]
+            if actions:
+                groups.append(
+                    {
+                        "title": action_group.title or "",
+                        "actions": actions,
+                    }
+                )
+
+        state = HelpState(
+            prog=self._prog,
+            description=self._root_section.heading or "",
+            groups=tuple(groups),
+        )
+
+        return template.render(state=state)

milo/input/__init__.py

@@ -0,0 +1,6 @@
+"""Input handling — key reading and escape sequence parsing."""
+
+from milo._types import Key, SpecialKey
+from milo.input._reader import KeyReader
+
+__all__ = ["Key", "KeyReader", "SpecialKey"]