milo-cli 0.2.0__tar.gz → 0.2.2__tar.gz

{milo_cli-0.2.0 → milo_cli-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: milo-cli
-Version: 0.2.0
+Version: 0.2.2
 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.4.0
+Requires-Dist: kida-templates>=0.6.0
 Provides-Extra: docs
 Requires-Dist: bengal>=0.2.6; extra == "docs"
 Provides-Extra: yaml
@@ -150,7 +150,7 @@ Requires Python 3.14+
 | **Observability** | Built-in request logging with latency stats (`milo://stats` resource) | [MCP →](https://lbliii.github.io/milo-cli/docs/usage/mcp/) |
 | **State Management** | Redux-style `Store` with dispatch, listeners, middleware, and saga scheduling | [State →](https://lbliii.github.io/milo-cli/docs/usage/state/) |
 | **Commands** | Lightweight `Cmd` thunks, `Batch`, `Sequence`, `TickCmd` for one-shot effects | [Commands →](https://lbliii.github.io/milo-cli/docs/usage/commands-effects/) |
-| **Sagas** | Generator-based side effects: `Call`, `Put`, `Select`, `Fork`, `Delay`, `Retry` | [Sagas →](https://lbliii.github.io/milo-cli/docs/usage/sagas/) |
+| **Sagas** | Generator-based side effects: `Call`, `Put`, `Select`, `Fork`, `Delay`, `Retry`, `Race`, `All`, `Take`, and more | [Sagas →](https://lbliii.github.io/milo-cli/docs/usage/sagas/) |
 | **ViewState** | Declarative terminal state (`cursor_visible`, `alt_screen`, `window_title`, `mouse_mode`) | [Commands →](https://lbliii.github.io/milo-cli/docs/usage/commands-effects/) |
 | **Flows** | Multi-screen state machines with `>>` operator and custom transitions | [Flows →](https://lbliii.github.io/milo-cli/docs/usage/flows/) |
 | **Forms** | Text, select, confirm, password fields with validation and TTY fallback | [Forms →](https://lbliii.github.io/milo-cli/docs/usage/forms/) |
@@ -159,6 +159,7 @@ Requires Python 3.14+
 | **Dev Server** | `milo dev` with filesystem polling and `@@HOT_RELOAD` dispatch | [Dev →](https://lbliii.github.io/milo-cli/docs/usage/dev/) |
 | **Session Recording** | JSONL action log with state hashes for debugging and regression testing | [Testing →](https://lbliii.github.io/milo-cli/docs/usage/testing/) |
 | **Snapshot Testing** | `assert_renders`, `assert_state`, `assert_saga` for deterministic test coverage | [Testing →](https://lbliii.github.io/milo-cli/docs/usage/testing/) |
+| **Pipeline** | Declarative multi-phase workflows with dependency graphs, retry policies, and output capture | [Pipeline →](https://lbliii.github.io/milo-cli/docs/usage/pipeline/) |
 | **Help Rendering** | `HelpRenderer` — drop-in `argparse.HelpFormatter` using Kida templates | [Help →](https://lbliii.github.io/milo-cli/docs/usage/help/) |
 | **Context** | Execution context with verbosity, output format, global options, and `run_app()` bridge | [Context →](https://lbliii.github.io/milo-cli/docs/usage/context/) |
 | **Configuration** | `Config` with validation, init scaffolding, and profile support | [Config →](https://lbliii.github.io/milo-cli/docs/usage/config/) |
@@ -343,7 +344,7 @@ def reducer(state, action):
     return state
 ```
 
-Saga effects: `Call(fn, args)`, `Put(action)`, `Select(selector)`, `Fork(saga)`, `Delay(seconds)`, `Retry(fn, ...)`.
+Saga effects: `Call`, `Put`, `Select`, `Fork`, `Delay`, `Retry`, `Timeout`, `TryCall`, `Race`, `All`, `Take`, `Debounce`, `TakeEvery`, `TakeLatest`.
 
 For one-shot effects, use `Cmd` instead — no generator needed:
 

{milo_cli-0.2.0 → milo_cli-0.2.2}/README.md

@@ -122,7 +122,7 @@ Requires Python 3.14+
 | **Observability** | Built-in request logging with latency stats (`milo://stats` resource) | [MCP →](https://lbliii.github.io/milo-cli/docs/usage/mcp/) |
 | **State Management** | Redux-style `Store` with dispatch, listeners, middleware, and saga scheduling | [State →](https://lbliii.github.io/milo-cli/docs/usage/state/) |
 | **Commands** | Lightweight `Cmd` thunks, `Batch`, `Sequence`, `TickCmd` for one-shot effects | [Commands →](https://lbliii.github.io/milo-cli/docs/usage/commands-effects/) |
-| **Sagas** | Generator-based side effects: `Call`, `Put`, `Select`, `Fork`, `Delay`, `Retry` | [Sagas →](https://lbliii.github.io/milo-cli/docs/usage/sagas/) |
+| **Sagas** | Generator-based side effects: `Call`, `Put`, `Select`, `Fork`, `Delay`, `Retry`, `Race`, `All`, `Take`, and more | [Sagas →](https://lbliii.github.io/milo-cli/docs/usage/sagas/) |
 | **ViewState** | Declarative terminal state (`cursor_visible`, `alt_screen`, `window_title`, `mouse_mode`) | [Commands →](https://lbliii.github.io/milo-cli/docs/usage/commands-effects/) |
 | **Flows** | Multi-screen state machines with `>>` operator and custom transitions | [Flows →](https://lbliii.github.io/milo-cli/docs/usage/flows/) |
 | **Forms** | Text, select, confirm, password fields with validation and TTY fallback | [Forms →](https://lbliii.github.io/milo-cli/docs/usage/forms/) |
@@ -131,6 +131,7 @@ Requires Python 3.14+
 | **Dev Server** | `milo dev` with filesystem polling and `@@HOT_RELOAD` dispatch | [Dev →](https://lbliii.github.io/milo-cli/docs/usage/dev/) |
 | **Session Recording** | JSONL action log with state hashes for debugging and regression testing | [Testing →](https://lbliii.github.io/milo-cli/docs/usage/testing/) |
 | **Snapshot Testing** | `assert_renders`, `assert_state`, `assert_saga` for deterministic test coverage | [Testing →](https://lbliii.github.io/milo-cli/docs/usage/testing/) |
+| **Pipeline** | Declarative multi-phase workflows with dependency graphs, retry policies, and output capture | [Pipeline →](https://lbliii.github.io/milo-cli/docs/usage/pipeline/) |
 | **Help Rendering** | `HelpRenderer` — drop-in `argparse.HelpFormatter` using Kida templates | [Help →](https://lbliii.github.io/milo-cli/docs/usage/help/) |
 | **Context** | Execution context with verbosity, output format, global options, and `run_app()` bridge | [Context →](https://lbliii.github.io/milo-cli/docs/usage/context/) |
 | **Configuration** | `Config` with validation, init scaffolding, and profile support | [Config →](https://lbliii.github.io/milo-cli/docs/usage/config/) |
@@ -315,7 +316,7 @@ def reducer(state, action):
     return state
 ```
 
-Saga effects: `Call(fn, args)`, `Put(action)`, `Select(selector)`, `Fork(saga)`, `Delay(seconds)`, `Retry(fn, ...)`.
+Saga effects: `Call`, `Put`, `Select`, `Fork`, `Delay`, `Retry`, `Timeout`, `TryCall`, `Race`, `All`, `Take`, `Debounce`, `TakeEvery`, `TakeLatest`.
 
 For one-shot effects, use `Cmd` instead — no generator needed:
 

{milo_cli-0.2.0 → milo_cli-0.2.2}/pyproject.toml

@@ -4,12 +4,12 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "milo-cli"
-version = "0.2.0"
+version = "0.2.2"
 description = "Template-driven CLI applications for free-threaded Python"
 readme = "README.md"
 requires-python = ">=3.14"
 license = "MIT"
-dependencies = ["kida-templates>=0.4.0"]
+dependencies = ["kida-templates>=0.6.0"]
 keywords = ["cli", "terminal", "forms", "free-threading", "template", "elm"]
 classifiers = [
     "Development Status :: 3 - Alpha",
@@ -123,7 +123,7 @@ ignore = [
 
 [tool.ruff.lint.per-file-ignores]
 "__init__.py" = ["F401"]
-"tests/**/*.py" = ["S101", "S108", "S110", "S604", "SIM117", "N806", "ARG"]
+"tests/**/*.py" = ["S101", "S108", "S110", "S604", "SIM117", "N806", "ARG", "T201"]
 "src/milo/_child.py" = ["S101"]          # asserts for type narrowing on subprocess pipes
 "src/milo/testing/*.py" = ["S101", "ARG"] # test helpers use assert and may have unused args
 "src/milo/version_check.py" = ["S110", "S310"] # best-effort cache reads + known PyPI URL
@@ -136,7 +136,7 @@ directory = "changelog.d"
 filename = "CHANGELOG.md"
 package = "milo"
 package_dir = "src"
-title_format = "## [{version}] - {project_date}"
+title_format = "## {version} — {project_date}"
 issue_format = "[#{issue}](https://github.com/lbliii/milo-cli/issues/{issue})"
 underlines = ["", "", ""]
 
@@ -187,3 +187,6 @@ dev = [
     # Changelog
     "towncrier>=24.0",
 ]
+docs = [
+    "bengal>=0.2.6",
+]

{milo_cli-0.2.0 → milo_cli-0.2.2}/src/milo/__init__.py

@@ -93,8 +93,14 @@ def __getattr__(name: str):
         "Pipeline": "pipeline",
         "Phase": "pipeline",
         "PhasePolicy": "pipeline",
+        "PhaseLog": "pipeline",
         "PipelineState": "pipeline",
         "PhaseStatus": "pipeline",
+        "PipelineViewState": "pipeline",
+        "make_detail_reducer": "pipeline",
+        "pipeline_to_timeline": "pipeline",
+        "set_active_pipeline": "pipeline",
+        "get_active_pipeline": "pipeline",
         "CycleError": "pipeline",
         # Plugins
         "HookRegistry": "plugins",
@@ -154,7 +160,7 @@ def _Py_mod_gil() -> int:  # noqa: N802
     return 0
 
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"
 __all__ = [
     "BUILTIN_ACTIONS",
     "CLI",
@@ -211,11 +217,13 @@ __all__ = [
     "MinLen",
     "Pattern",
     "Phase",
+    "PhaseLog",
     "PhasePolicy",
     "PhaseStatus",
     "Pipeline",
     "PipelineError",
     "PipelineState",
+    "PipelineViewState",
     "PluginError",
     "Progress",
     "PromptDef",
@@ -254,14 +262,18 @@ __all__ = [
     "format_render_error",
     "function_to_schema",
     "generate_llms_txt",
+    "get_active_pipeline",
     "get_context",
     "install_completions",
+    "make_detail_reducer",
     "make_form_reducer",
     "make_style_filter",
+    "pipeline_to_timeline",
     "quit_on",
     "render_html",
     "run",
     "run_doctor",
+    "set_active_pipeline",
     "with_confirm",
     "with_cursor",
     "write_output",

{milo_cli-0.2.0 → milo_cli-0.2.2}/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()
@@ -127,7 +132,11 @@ class LazyCommandDef:
         return self.resolve().handler
 
     def resolve(self) -> CommandDef:
-        """Import the handler and cache as a full CommandDef. Thread-safe."""
+        """Import the handler and cache as a full CommandDef. Thread-safe.
+
+        Raises :class:`LazyImportError` if the module or attribute cannot
+        be imported, wrapping the original exception with a clear message.
+        """
         if self._resolved is not None:
             return self._resolved
 
@@ -139,10 +148,13 @@ class LazyCommandDef:
             module_path, _, attr_name = self.import_path.rpartition(":")
             if not module_path or not attr_name:
                 msg = f"Invalid import_path {self.import_path!r}: expected 'module.path:attribute'"
-                raise ValueError(msg)
+                raise LazyImportError(self.name, self.import_path, ValueError(msg))
 
-            module = importlib.import_module(module_path)
-            handler = getattr(module, attr_name)
+            try:
+                module = importlib.import_module(module_path)
+                handler = getattr(module, attr_name)
+            except Exception as exc:
+                raise LazyImportError(self.name, self.import_path, exc) from exc
 
             from milo.schema import function_to_schema
 
@@ -159,6 +171,7 @@ class LazyCommandDef:
                 examples=self.examples,
                 confirm=self.confirm,
                 annotations=self.annotations,
+                display_result=self.display_result,
             )
             return self._resolved
 
@@ -174,6 +187,20 @@ class InvokeResult:
     stderr: str = ""
 
 
+class LazyImportError(Exception):
+    """Raised when a lazy command's import fails.
+
+    Wraps the original exception with the command name and import path
+    so callers can provide actionable error messages.
+    """
+
+    def __init__(self, command_name: str, import_path: str, cause: Exception) -> None:
+        self.command_name = command_name
+        self.import_path = import_path
+        self.cause = cause
+        super().__init__(f"Command {command_name!r} failed to import from {import_path!r}: {cause}")
+
+
 def _make_command_def(
     name: str,
     func: Callable,
@@ -185,6 +212,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,17 +232,20 @@ def _make_command_def(
         examples=examples,
         confirm=confirm,
         annotations=annotations or {},
+        display_result=display_result,
     )
 
 
 def _is_context_param(param: inspect.Parameter) -> bool:
     """Check if a parameter is a Context injection point."""
+    from milo.context import Context as _MiloContext
+
     annotation = param.annotation
     if annotation is inspect.Parameter.empty:
         return False
-    # Check for Context type or string annotation
+    # Check for exact type identity or subclass of milo.context.Context
     if isinstance(annotation, type):
-        return annotation.__name__ == "Context"
+        return issubclass(annotation, _MiloContext)
     if isinstance(annotation, str):
         return annotation in ("Context", "milo.context.Context")
     return False

{milo_cli-0.2.0 → milo_cli-0.2.2}/src/milo/_jsonrpc.py

@@ -15,11 +15,16 @@ def _write_result(req_id: Any, result: dict[str, Any]) -> None:
     sys.stdout.flush()
 
 
-def _write_error(req_id: Any, code: int, message: str) -> None:
+def _write_error(
+    req_id: Any, code: int, message: str, *, data: dict[str, Any] | None = None
+) -> None:
+    error_obj: dict[str, Any] = {"code": code, "message": message}
+    if data is not None:
+        error_obj["data"] = data
     response = {
         "jsonrpc": "2.0",
         "id": req_id,
-        "error": {"code": code, "message": message},
+        "error": error_obj,
     }
     sys.stdout.write(json.dumps(response) + "\n")
     sys.stdout.flush()

{milo_cli-0.2.0 → milo_cli-0.2.2}/src/milo/_types.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import warnings
 from collections.abc import Callable, Generator
 from dataclasses import dataclass, field
 from enum import Enum, auto
@@ -82,6 +83,7 @@ BUILTIN_ACTIONS: frozenset[str] = frozenset(
         "@@PHASE_FAILED",
         "@@PHASE_SKIPPED",
         "@@PHASE_RETRY",
+        "@@PHASE_LOG",
         "@@SAGA_ERROR",
         "@@SAGA_CANCELLED",
         "@@CMD_ERROR",
@@ -326,6 +328,14 @@ class Take:
     action_type: str
     timeout: float | None = None
 
+    def __post_init__(self) -> None:
+        if self.timeout is None:
+            warnings.warn(
+                f"Take({self.action_type!r}) has no timeout and may block forever. "
+                f"Consider setting timeout= to prevent silent hangs.",
+                stacklevel=2,
+            )
+
 
 @dataclass(frozen=True, slots=True)
 class Debounce:

{milo_cli-0.2.0 → milo_cli-0.2.2}/src/milo/app.py

@@ -241,7 +241,14 @@ class App:
             from milo.templates import get_env
 
             env = get_env()
-        tmpl = env.get_template(template)
+        try:
+            tmpl = env.get_template(template)
+        except Exception as e:
+            raise AppError(
+                ErrorCode.APP_RENDER,
+                f"Template not found: {template!r}",
+                suggestion="Ensure the template file exists and the kida environment is configured correctly.",
+            ) from e
         return tmpl.render(state=state)
 
     def run(self) -> Any:
@@ -405,7 +412,14 @@ class App:
 
     def _render_exit(self, state: Any, env: Any) -> None:
         """Render the exit template once to stdout."""
-        template = env.get_template(self._exit_template)
+        try:
+            template = env.get_template(self._exit_template)
+        except Exception as e:
+            raise AppError(
+                ErrorCode.APP_RENDER,
+                f"Exit template not found: {self._exit_template!r}",
+                suggestion="Ensure the exit template file exists and the kida environment is configured correctly.",
+            ) from e
         render_state = state
         if isinstance(state, FlowState):
             # For flows, pass all screen states so exit template can reference any data