milo-cli 0.1.0__py3-none-any.whl

milo/input/_platform.py

@@ -0,0 +1,81 @@
+"""Platform abstraction for terminal raw mode and character reading."""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Generator
+from contextlib import contextmanager
+
+
+@contextmanager
+def raw_mode(fd: int | None = None) -> Generator[None]:
+    """Context manager that puts the terminal into raw mode.
+
+    Restores original settings on exit.
+    """
+    if fd is None:
+        fd = sys.stdin.fileno()
+
+    if sys.platform == "win32":
+        yield
+        return
+
+    import termios
+    import tty
+
+    old_settings = termios.tcgetattr(fd)
+    try:
+        tty.setraw(fd)
+        yield
+    finally:
+        termios.tcsetattr(fd, termios.TCSADRAIN, old_settings)
+
+
+def read_char(fd: int | None = None) -> str:
+    """Read a single character from the terminal.
+
+    Must be called within a raw_mode() context.
+    """
+    if fd is None:
+        fd = sys.stdin.fileno()
+
+    if sys.platform == "win32":
+        import msvcrt
+
+        return msvcrt.getwch()
+
+    import os
+
+    return os.read(fd, 1).decode("utf-8", errors="replace")
+
+
+def read_available(fd: int | None = None, max_bytes: int = 16) -> str:
+    """Read all immediately available bytes (non-blocking).
+
+    Used to consume multi-byte escape sequences after the initial escape.
+    """
+    if fd is None:
+        fd = sys.stdin.fileno()
+
+    import os
+    import select
+
+    result = ""
+    for _ in range(max_bytes):
+        ready, _, _ = select.select([fd], [], [], 0)
+        if not ready:
+            break
+        result += os.read(fd, 1).decode("utf-8", errors="replace")
+    return result
+
+
+def is_tty(fd: int | None = None) -> bool:
+    """Check if fd is connected to a terminal."""
+    if fd is None:
+        try:
+            fd = sys.stdin.fileno()
+        except AttributeError, ValueError, OSError:
+            return False
+    import os
+
+    return os.isatty(fd)

milo/input/_reader.py

@@ -0,0 +1,93 @@
+"""KeyReader — iterator that yields Key objects from terminal input."""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Iterator
+from types import TracebackType
+
+from milo._errors import ErrorCode, InputError
+from milo._types import Key, SpecialKey
+from milo.input._platform import is_tty, raw_mode, read_available, read_char
+from milo.input._sequences import CTRL_CHARS, ESCAPE_SEQUENCES
+
+
+class KeyReader:
+    """Iterator that yields Key objects from terminal input.
+
+    Usage::
+
+        with KeyReader() as keys:
+            for key in keys:
+                if key.name == SpecialKey.ESCAPE:
+                    break
+                print(key)
+    """
+
+    def __init__(self, fd: int | None = None) -> None:
+        self._fd = fd if fd is not None else sys.stdin.fileno()
+        self._raw_ctx = None
+        self._closed = False
+
+    def __enter__(self) -> KeyReader:
+        if not is_tty(self._fd):
+            raise InputError(
+                ErrorCode.INP_RAW_MODE,
+                "Cannot read keys: stdin is not a TTY",
+            )
+        self._raw_ctx = raw_mode(self._fd)
+        self._raw_ctx.__enter__()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        self._closed = True
+        if self._raw_ctx is not None:
+            self._raw_ctx.__exit__(exc_type, exc_val, exc_tb)
+
+    def __iter__(self) -> Iterator[Key]:
+        return self
+
+    def __next__(self) -> Key:
+        if self._closed:
+            raise StopIteration
+        return self.read_key()
+
+    def read_key(self) -> Key:
+        """Read and return the next keypress."""
+        try:
+            ch = read_char(self._fd)
+        except (OSError, ValueError) as e:
+            raise InputError(ErrorCode.INP_READ, str(e)) from e
+
+        # Escape sequence
+        if ch == "\x1b":
+            rest = read_available(self._fd)
+            seq = "\x1b" + rest
+            if seq in ESCAPE_SEQUENCES:
+                return ESCAPE_SEQUENCES[seq]
+            if not rest:
+                return Key(name=SpecialKey.ESCAPE)
+            # Alt+char
+            if len(rest) == 1 and rest.isprintable():
+                return Key(char=rest, alt=True)
+            return Key(name=SpecialKey.ESCAPE)
+
+        # Known single-char sequences (tab, enter, backspace)
+        if ch in ESCAPE_SEQUENCES:
+            return ESCAPE_SEQUENCES[ch]
+
+        # Ctrl+letter
+        code = ord(ch)
+        if code in CTRL_CHARS:
+            return Key(char=CTRL_CHARS[code], ctrl=True)
+
+        # Regular printable character
+        if ch.isprintable():
+            return Key(char=ch)
+
+        return Key(char=ch)

milo/input/_sequences.py

@@ -0,0 +1,63 @@
+"""Frozen escape sequence lookup table."""
+
+from __future__ import annotations
+
+from milo._types import Key, SpecialKey
+
+# Map escape sequences to Key objects
+ESCAPE_SEQUENCES: dict[str, Key] = {
+    # Arrow keys
+    "\x1b[A": Key(name=SpecialKey.UP),
+    "\x1b[B": Key(name=SpecialKey.DOWN),
+    "\x1b[C": Key(name=SpecialKey.RIGHT),
+    "\x1b[D": Key(name=SpecialKey.LEFT),
+    # Home / End
+    "\x1b[H": Key(name=SpecialKey.HOME),
+    "\x1b[F": Key(name=SpecialKey.END),
+    "\x1b[1~": Key(name=SpecialKey.HOME),
+    "\x1b[4~": Key(name=SpecialKey.END),
+    # Page Up / Down
+    "\x1b[5~": Key(name=SpecialKey.PAGE_UP),
+    "\x1b[6~": Key(name=SpecialKey.PAGE_DOWN),
+    # Insert / Delete
+    "\x1b[2~": Key(name=SpecialKey.INSERT),
+    "\x1b[3~": Key(name=SpecialKey.DELETE),
+    # Function keys
+    "\x1bOP": Key(name=SpecialKey.F1),
+    "\x1bOQ": Key(name=SpecialKey.F2),
+    "\x1bOR": Key(name=SpecialKey.F3),
+    "\x1bOS": Key(name=SpecialKey.F4),
+    "\x1b[15~": Key(name=SpecialKey.F5),
+    "\x1b[17~": Key(name=SpecialKey.F6),
+    "\x1b[18~": Key(name=SpecialKey.F7),
+    "\x1b[19~": Key(name=SpecialKey.F8),
+    "\x1b[20~": Key(name=SpecialKey.F9),
+    "\x1b[21~": Key(name=SpecialKey.F10),
+    "\x1b[23~": Key(name=SpecialKey.F11),
+    "\x1b[24~": Key(name=SpecialKey.F12),
+    # Shift+arrow
+    "\x1b[1;2A": Key(name=SpecialKey.UP, shift=True),
+    "\x1b[1;2B": Key(name=SpecialKey.DOWN, shift=True),
+    "\x1b[1;2C": Key(name=SpecialKey.RIGHT, shift=True),
+    "\x1b[1;2D": Key(name=SpecialKey.LEFT, shift=True),
+    # Alt+arrow
+    "\x1b[1;3A": Key(name=SpecialKey.UP, alt=True),
+    "\x1b[1;3B": Key(name=SpecialKey.DOWN, alt=True),
+    "\x1b[1;3C": Key(name=SpecialKey.RIGHT, alt=True),
+    "\x1b[1;3D": Key(name=SpecialKey.LEFT, alt=True),
+    # Ctrl+arrow
+    "\x1b[1;5A": Key(name=SpecialKey.UP, ctrl=True),
+    "\x1b[1;5B": Key(name=SpecialKey.DOWN, ctrl=True),
+    "\x1b[1;5C": Key(name=SpecialKey.RIGHT, ctrl=True),
+    "\x1b[1;5D": Key(name=SpecialKey.LEFT, ctrl=True),
+    # Tab and Enter
+    "\t": Key(name=SpecialKey.TAB),
+    "\r": Key(name=SpecialKey.ENTER),
+    "\n": Key(name=SpecialKey.ENTER),
+    # Backspace variants
+    "\x7f": Key(name=SpecialKey.BACKSPACE),
+    "\x08": Key(name=SpecialKey.BACKSPACE),
+}
+
+# Control character to ctrl+letter mapping (ctrl+a = 0x01, ctrl+z = 0x1a)
+CTRL_CHARS: dict[int, str] = {i: chr(i + 96) for i in range(1, 27)}

milo/llms.py

@@ -0,0 +1,172 @@
+"""llms.txt generation from CLI command definitions."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from milo.commands import CLI, CommandDef, LazyCommandDef
+    from milo.groups import Group
+
+
+def generate_llms_txt(cli: CLI) -> str:
+    """Generate llms.txt content from a CLI's registered commands.
+
+    Follows the llms.txt specification (https://llmstxt.org/).
+    Output is a curated Markdown document that helps AI agents
+    discover what the CLI can do. Groups produce nested headings.
+    """
+    lines: list[str] = []
+
+    # Title
+    lines.append(f"# {cli.name}")
+    lines.append("")
+
+    # Description
+    if cli.description:
+        lines.append(f"> {cli.description}")
+        lines.append("")
+
+    # Version
+    if cli.version:
+        lines.append(f"Version: {cli.version}")
+        lines.append("")
+
+    # Group commands by tag
+    tagged: dict[str, list[CommandDef | LazyCommandDef]] = {}
+    untagged: list[CommandDef | LazyCommandDef] = []
+
+    for cmd in cli.commands.values():
+        if cmd.hidden:
+            continue
+        if cmd.tags:
+            for tag in cmd.tags:
+                tagged.setdefault(tag, []).append(cmd)
+        else:
+            untagged.append(cmd)
+
+    # Untagged commands
+    if untagged:
+        lines.append("## Commands")
+        lines.append("")
+        lines.extend(_format_command(cmd) for cmd in untagged)
+        lines.append("")
+
+    # Tagged groups
+    for tag, cmds in sorted(tagged.items()):
+        title = tag.replace("-", " ").replace("_", " ").title()
+        lines.append(f"## {title}")
+        lines.append("")
+        lines.extend(_format_command(cmd) for cmd in cmds)
+        lines.append("")
+
+    # Command groups
+    for group in cli.groups.values():
+        if group.hidden:
+            continue
+        _format_group(group, lines, depth=2)
+
+    # Resources section
+    resources = cli.walk_resources()
+    if resources:
+        lines.append("## Resources")
+        lines.append("")
+        for _uri, res in resources:
+            lines.append(f"- **{res.uri}** ({res.mime_type}): {res.description}")
+        lines.append("")
+
+    # Prompts section
+    prompts = cli.walk_prompts()
+    if prompts:
+        lines.append("## Prompts")
+        lines.append("")
+        for _name, p in prompts:
+            args_str = ""
+            if p.arguments:
+                arg_names = [a.get("name", "?") for a in p.arguments]
+                args_str = f" ({', '.join(arg_names)})"
+            lines.append(f"- **{p.name}**{args_str}: {p.description}")
+        lines.append("")
+
+    # Workflows section (heuristic relationship detection)
+    workflows = _detect_workflows(cli)
+    if workflows:
+        lines.append("## Workflows")
+        lines.append("")
+        lines.extend(f"- {desc}" for desc in workflows)
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def _format_group(group: Group, lines: list[str], depth: int) -> None:
+    """Format a command group as a section with nested headings."""
+    heading = "#" * depth
+    title = group.description or group.name.replace("-", " ").replace("_", " ").title()
+    lines.append(f"{heading} {title}")
+    lines.append("")
+
+    for cmd in group.commands.values():
+        if cmd.hidden:
+            continue
+        lines.append(_format_command(cmd))
+    if group.commands:
+        lines.append("")
+
+    for sub_group in group.groups.values():
+        if sub_group.hidden:
+            continue
+        _format_group(sub_group, lines, depth=depth + 1)
+
+
+def _format_command(cmd: CommandDef) -> str:
+    """Format a single command as an llms.txt entry."""
+    parts = [f"- **{cmd.name}**"]
+
+    if cmd.aliases:
+        parts.append(f" ({', '.join(cmd.aliases)})")
+
+    parts.append(f": {cmd.description}" if cmd.description else "")
+
+    # Parameter summary
+    props = cmd.schema.get("properties", {})
+    required = set(cmd.schema.get("required", []))
+    if props:
+        params = []
+        for name, schema in props.items():
+            param_type = schema.get("type", "string")
+            if name in required:
+                params.append(f"`--{name}` ({param_type}, required)")
+            else:
+                params.append(f"`--{name}` ({param_type})")
+        parts.append("\n  Parameters: " + ", ".join(params))
+
+    # Examples
+    examples = getattr(cmd, "examples", ())
+    if examples:
+        parts.append("\n  Examples:")
+        for ex in examples:
+            args_str = " ".join(f"--{k} {v}" for k, v in ex.items())
+            parts.append(f"\n    `{cmd.name} {args_str}`")
+
+    return "".join(parts)
+
+
+def _detect_workflows(cli: CLI) -> list[str]:
+    """Heuristically detect command workflows via output→input parameter overlap."""
+    commands = list(cli.walk_commands())
+    workflows: list[str] = []
+
+    for i, (name_a, cmd_a) in enumerate(commands):
+        if cmd_a.hidden:
+            continue
+        props_a = set(cmd_a.schema.get("properties", {}).keys())
+        for name_b, cmd_b in commands[i + 1 :]:
+            if cmd_b.hidden:
+                continue
+            props_b = set(cmd_b.schema.get("properties", {}).keys())
+            overlap = props_a & props_b
+            if overlap:
+                workflows.append(f"`{name_a}` → `{name_b}` (shared: {', '.join(sorted(overlap))})")
+
+    return workflows