milo-cli 0.1.1__tar.gz → 0.2.1__tar.gz

{milo_cli-0.1.1 → milo_cli-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: milo-cli
-Version: 0.1.1
+Version: 0.2.1
 Summary: Template-driven CLI applications for free-threaded Python
 License-Expression: MIT
 Project-URL: Homepage, https://lbliii.github.io/milo-cli/
@@ -18,7 +18,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.14
 Description-Content-Type: text/markdown
-Requires-Dist: kida-templates>=0.3.0
+Requires-Dist: kida-templates>=0.4.0
 Provides-Extra: docs
 Requires-Dist: bengal>=0.2.6; extra == "docs"
 Provides-Extra: yaml

{milo_cli-0.1.1 → milo_cli-0.2.1}/pyproject.toml

@@ -4,12 +4,12 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "milo-cli"
-version = "0.1.1"
+version = "0.2.1"
 description = "Template-driven CLI applications for free-threaded Python"
 readme = "README.md"
 requires-python = ">=3.14"
 license = "MIT"
-dependencies = ["kida-templates>=0.3.0"]
+dependencies = ["kida-templates>=0.4.0"]
 keywords = ["cli", "terminal", "forms", "free-threading", "template", "elm"]
 classifiers = [
     "Development Status :: 3 - Alpha",
@@ -129,7 +129,46 @@ ignore = [
 "src/milo/version_check.py" = ["S110", "S310"] # best-effort cache reads + known PyPI URL
 "src/milo/mcp.py" = ["ARG002"]            # MCP protocol methods require params signature
 "src/milo/gateway.py" = ["ARG002", "S110"] # MCP protocol methods + best-effort discovery
-"benchmarks/**/*.py" = ["T201"] # benchmarks may use print for diagnostics
+"benchmarks/**/*.py" = ["T201", "ARG", "S101"] # benchmarks: print, unused args, assert
+
+[tool.towncrier]
+directory = "changelog.d"
+filename = "CHANGELOG.md"
+package = "milo"
+package_dir = "src"
+title_format = "## {version} — {project_date}"
+issue_format = "[#{issue}](https://github.com/lbliii/milo-cli/issues/{issue})"
+underlines = ["", "", ""]
+
+[[tool.towncrier.type]]
+directory = "added"
+name = "Added"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "changed"
+name = "Changed"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "deprecated"
+name = "Deprecated"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "removed"
+name = "Removed"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "fixed"
+name = "Fixed"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "security"
+name = "Security"
+showcontent = true
 
 [dependency-groups]
 dev = [
@@ -145,4 +184,6 @@ dev = [
     "ruff>=0.15.1",
     # Pre-commit
     "pre-commit>=4.0.0",
+    # Changelog
+    "towncrier>=24.0",
 ]

{milo_cli-0.1.1 → milo_cli-0.2.1}/src/milo/__init__.py

@@ -26,6 +26,12 @@ def __getattr__(name: str):
         "Fork": "_types",
         "Delay": "_types",
         "Retry": "_types",
+        "Timeout": "_types",
+        "TryCall": "_types",
+        "Race": "_types",
+        "All": "_types",
+        "Take": "_types",
+        "Debounce": "_types",
         "Cmd": "_types",
         "Batch": "_types",
         "Sequence": "_types",
@@ -48,6 +54,8 @@ def __getattr__(name: str):
         "format_render_error": "_errors",
         # State
         "Store": "state",
+        "SagaContext": "state",
+        "EffectResult": "state",
         "combine_reducers": "state",
         # App
         "App": "app",
@@ -84,8 +92,10 @@ def __getattr__(name: str):
         # Pipeline
         "Pipeline": "pipeline",
         "Phase": "pipeline",
+        "PhasePolicy": "pipeline",
         "PipelineState": "pipeline",
         "PhaseStatus": "pipeline",
+        "CycleError": "pipeline",
         # Plugins
         "HookRegistry": "plugins",
         "function_to_schema": "schema",
@@ -97,6 +107,11 @@ def __getattr__(name: str):
         "Le": "schema",
         "Pattern": "schema",
         "Description": "schema",
+        # Theme
+        "ThemeStyle": "theme",
+        "ThemeProxy": "theme",
+        "DEFAULT_THEME": "theme",
+        "make_style_filter": "theme",
         "format_output": "output",
         "write_output": "output",
         "generate_llms_txt": "llms",
@@ -139,11 +154,13 @@ def _Py_mod_gil() -> int:  # noqa: N802
     return 0
 
 
-__version__ = "0.1.1"
+__version__ = "0.2.1"
 __all__ = [
     "BUILTIN_ACTIONS",
     "CLI",
+    "DEFAULT_THEME",
     "Action",
+    "All",
     "App",
     "AppError",
     "AppStatus",
@@ -157,6 +174,8 @@ __all__ = [
     "ConfigError",
     "ConfigSpec",
     "Context",
+    "CycleError",
+    "Debounce",
     "Delay",
     "Description",
     "DevServer",
@@ -192,6 +211,7 @@ __all__ = [
     "MinLen",
     "Pattern",
     "Phase",
+    "PhasePolicy",
     "PhaseStatus",
     "Pipeline",
     "PipelineError",
@@ -201,6 +221,7 @@ __all__ = [
     "PromptDef",
     "Put",
     "Quit",
+    "Race",
     "ReducerResult",
     "RenderTarget",
     "RequestLog",
@@ -213,8 +234,13 @@ __all__ = [
     "SpecialKey",
     "StateError",
     "Store",
+    "Take",
+    "ThemeProxy",
+    "ThemeStyle",
     "TickCmd",
+    "Timeout",
     "Transition",
+    "TryCall",
     "VersionInfo",
     "ViewState",
     "check_version",
@@ -231,6 +257,7 @@ __all__ = [
     "get_context",
     "install_completions",
     "make_form_reducer",
+    "make_style_filter",
     "quit_on",
     "render_html",
     "run",

{milo_cli-0.1.1 → milo_cli-0.2.1}/src/milo/_child.py

@@ -9,8 +9,6 @@ import threading
 import time
 from typing import Any
 
-_READ_TIMEOUT = 30.0  # seconds
-
 
 class ChildProcess:
     """A persistent child process that speaks JSON-RPC on stdin/stdout.
@@ -25,10 +23,12 @@ class ChildProcess:
         command: list[str],
         *,
         idle_timeout: float = 300.0,
+        request_timeout: float = 30.0,
     ) -> None:
         self.name = name
         self.command = command
         self.idle_timeout = idle_timeout
+        self.request_timeout = request_timeout
         self._proc: subprocess.Popen[str] | None = None
         self._lock = threading.Lock()
         self._last_use = time.monotonic()
@@ -72,8 +72,13 @@ class ChildProcess:
                 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."""
+    def send_call(
+        self, method: str, params: dict[str, Any], *, timeout: float | None = None
+    ) -> dict[str, Any]:
+        """Send a JSON-RPC request and return the result. Thread-safe.
+
+        *timeout* overrides the instance ``request_timeout`` for this call.
+        """
         with self._lock:
             if self._proc is None or self._proc.poll() is not None:
                 self._spawn()
@@ -88,7 +93,8 @@ class ChildProcess:
                 "params": params,
             }
             self._write_line(json.dumps(request))
-            response_line = self._read_line()
+            effective_timeout = timeout if timeout is not None else self.request_timeout
+            response_line = self._read_line(timeout=effective_timeout)
             self._last_use = time.monotonic()
 
             if not response_line:
@@ -115,19 +121,25 @@ class ChildProcess:
     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
+            self._graceful_kill()
+
+    def _graceful_kill(self) -> None:
+        """SIGTERM with grace period, then SIGKILL if needed.
+
+        Must be called while holding ``self._lock``.
+        """
+        if self._proc is None:
+            return
+        try:
+            self._proc.terminate()  # SIGTERM
+            self._proc.wait(timeout=5)  # Grace period
+        except ProcessLookupError:
+            pass  # Already dead
+        except subprocess.TimeoutExpired:
+            with contextlib.suppress(ProcessLookupError):
+                self._proc.kill()  # SIGKILL
+        self._proc = None
+        self._initialized = False
 
     def _write_line(self, line: str) -> None:
         """Write a line to the child's stdin."""
@@ -136,12 +148,13 @@ class ChildProcess:
         self._proc.stdin.write(line + "\n")
         self._proc.stdin.flush()
 
-    def _read_line(self) -> str:
+    def _read_line(self, *, timeout: float | None = None) -> str:
         """Read a line from the child's stdout with timeout.
 
         Uses a background thread so we can enforce a deadline even
         when the child blocks without writing a newline.
         """
+        effective_timeout = timeout if timeout is not None else self.request_timeout
         assert self._proc is not None
         assert self._proc.stdout is not None
         result: list[str] = []
@@ -150,12 +163,9 @@ class ChildProcess:
             daemon=True,
         )
         reader.start()
-        reader.join(timeout=_READ_TIMEOUT)
+        reader.join(timeout=effective_timeout)
         if reader.is_alive():
-            # Timed out — kill the child to unblock the reader thread
-            with contextlib.suppress(OSError):
-                self._proc.kill()
-            self._proc = None
-            self._initialized = False
+            # Timed out — graceful shutdown: SIGTERM → grace → SIGKILL
+            self._graceful_kill()
             return ""
         return result[0].strip() if result else ""

{milo_cli-0.1.1 → milo_cli-0.2.1}/src/milo/_command_defs.py

@@ -59,6 +59,8 @@ class CommandDef:
     """If non-empty, prompt for confirmation before running."""
     annotations: dict[str, Any] = field(default_factory=dict)
     """MCP tool annotations (readOnlyHint, destructiveHint, etc.)."""
+    display_result: bool = True
+    """If False, suppress plain-format output (return value still available for --format json)."""
 
 
 class LazyCommandDef:
@@ -80,6 +82,7 @@ class LazyCommandDef:
         "annotations",
         "confirm",
         "description",
+        "display_result",
         "examples",
         "hidden",
         "import_path",
@@ -100,6 +103,7 @@ class LazyCommandDef:
         examples: tuple[dict[str, Any], ...] | list[dict[str, Any]] = (),
         confirm: str = "",
         annotations: dict[str, Any] | None = None,
+        display_result: bool = True,
     ) -> None:
         self.name = name
         self.description = description
@@ -110,6 +114,7 @@ class LazyCommandDef:
         self.examples = tuple(examples)
         self.confirm = confirm
         self.annotations = annotations or {}
+        self.display_result = display_result
         self._schema = schema
         self._resolved: CommandDef | None = None
         self._lock = threading.Lock()
@@ -159,6 +164,7 @@ class LazyCommandDef:
                 examples=self.examples,
                 confirm=self.confirm,
                 annotations=self.annotations,
+                display_result=self.display_result,
             )
             return self._resolved
 
@@ -185,6 +191,7 @@ def _make_command_def(
     examples: tuple[dict[str, Any], ...] = (),
     confirm: str = "",
     annotations: dict[str, Any] | None = None,
+    display_result: bool = True,
 ) -> CommandDef:
     """Build a CommandDef from a function and decorator kwargs."""
     from milo.schema import function_to_schema
@@ -204,6 +211,7 @@ def _make_command_def(
         examples=examples,
         confirm=confirm,
         annotations=annotations or {},
+        display_result=display_result,
     )
 
 

{milo_cli-0.1.1 → milo_cli-0.2.1}/src/milo/_types.py

@@ -80,7 +80,10 @@ BUILTIN_ACTIONS: frozenset[str] = frozenset(
         "@@PHASE_START",
         "@@PHASE_COMPLETE",
         "@@PHASE_FAILED",
+        "@@PHASE_SKIPPED",
+        "@@PHASE_RETRY",
         "@@SAGA_ERROR",
+        "@@SAGA_CANCELLED",
         "@@CMD_ERROR",
     }
 )
@@ -202,9 +205,16 @@ class Select:
 
 @dataclass(frozen=True, slots=True)
 class Fork:
-    """Run another saga concurrently."""
+    """Run another saga concurrently.
+
+    By default forks are *detached*: the child gets its own cancellation
+    scope and is not cancelled when the parent is.  Set ``attached=True``
+    to inherit the parent's cancellation scope — cancelling the parent
+    will transitively cancel the child.
+    """
 
     saga: Callable | Generator
+    attached: bool = False
 
 
 @dataclass(frozen=True, slots=True)
@@ -232,6 +242,154 @@ class Retry:
     max_delay: float = 30.0
 
 
+@dataclass(frozen=True, slots=True)
+class Timeout:
+    """Wrap a blocking effect with a deadline.
+
+    Usage in a saga::
+
+        result = yield Timeout(Call(fetch_data, args=(url,)), seconds=5)
+
+    Raises ``TimeoutError`` if the effect doesn't complete in time.
+    Only wraps blocking effects (``Call`` and ``Retry``).
+    """
+
+    effect: Call | Retry
+    seconds: float
+
+
+@dataclass(frozen=True, slots=True)
+class TryCall:
+    """Call a function, returning (result, None) on success or (None, error) on failure.
+
+    Unlike ``Call``, exceptions do not crash the saga::
+
+        result, error = yield TryCall(fn=might_fail)
+        if error:
+            yield Put(Action("FETCH_FAILED", payload=str(error)))
+        else:
+            yield Put(Action("FETCH_OK", payload=result))
+    """
+
+    fn: Callable
+    args: tuple = ()
+    kwargs: dict = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class Race:
+    """Run multiple sagas concurrently, return the first result.
+
+    Losers are cancelled via their cancel events as soon as a winner
+    completes.  If all racers fail, the first error is thrown into
+    the parent saga::
+
+        winner = yield Race(sagas=(fetch_primary(), fetch_fallback()))
+
+    Raises ``StateError`` if *sagas* is empty.
+    """
+
+    sagas: tuple
+
+
+@dataclass(frozen=True, slots=True)
+class All:
+    """Run multiple sagas concurrently, wait for all to complete.
+
+    Returns a tuple of results in the same order as the input sagas.
+    Fail-fast: if any saga raises, remaining sagas are cancelled and
+    the error is thrown into the parent::
+
+        a, b = yield All(sagas=(fetch_users(), fetch_roles()))
+
+    An empty tuple returns ``()`` immediately.
+    """
+
+    sagas: tuple
+
+
+@dataclass(frozen=True, slots=True)
+class Take:
+    """Pause the saga until a matching action is dispatched.
+
+    Waits for *future* actions only — actions dispatched before the
+    Take is yielded are not matched.  Returns the full ``Action``
+    object so the saga can inspect both type and payload::
+
+        action = yield Take("USER_CONFIRMED")
+        name = action.payload["name"]
+
+    An optional *timeout* (in seconds) raises ``TimeoutError`` if the
+    action is not dispatched in time.
+    """
+
+    action_type: str
+    timeout: float | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class Debounce:
+    """Delay-then-fork: start a timer, fork *saga* when it expires.
+
+    If the parent saga yields another ``Debounce`` before the timer
+    fires, the previous timer is cancelled and restarted.  The parent
+    continues immediately (non-blocking)::
+
+        # In a keystroke handler saga:
+        while True:
+            key = yield Take("@@KEY")
+            yield Debounce(seconds=0.3, saga=search_saga)
+
+    The debounced saga runs independently; use ``Take`` if the parent
+    needs the result.
+    """
+
+    seconds: float
+    saga: Callable
+
+
+@dataclass(frozen=True, slots=True)
+class TakeEvery:
+    """Fork a new saga for every matching action (auto-restart pattern).
+
+    Blocks the parent saga until cancelled.  For each dispatched action
+    whose type matches *action_type*, a new saga is forked with the
+    action as argument::
+
+        # Fork a handler for every CLICK action:
+        yield TakeEvery("CLICK", handle_click)
+
+        def handle_click(action):
+            url = action.payload["url"]
+            result = yield Call(fetch, args=(url,))
+            yield Put(Action("FETCHED", payload=result))
+
+    The watcher loop runs until the parent saga is cancelled.
+    """
+
+    action_type: str
+    saga: Callable  # (action: Action) -> Generator
+
+
+@dataclass(frozen=True, slots=True)
+class TakeLatest:
+    """Fork a saga for the latest matching action, cancelling the previous.
+
+    Like :class:`TakeEvery` but only the most recent saga runs — when a
+    new matching action arrives, the previous fork is cancelled before
+    the new one starts::
+
+        # Only the latest search runs:
+        yield TakeLatest("SEARCH", run_search)
+
+    Useful for typeahead/autocomplete patterns where earlier results
+    are obsolete.
+    """
+
+    action_type: str
+    saga: Callable  # (action: Action) -> Generator
+
+
 # ---------------------------------------------------------------------------
 # Commands (lightweight alternative to sagas)
 # ---------------------------------------------------------------------------