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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: milo-cli
-Version: 0.2.0
+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/

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "milo-cli"
-version = "0.2.0"
+version = "0.2.1"
 description = "Template-driven CLI applications for free-threaded Python"
 readme = "README.md"
 requires-python = ">=3.14"
@@ -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 = ["", "", ""]
 

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

@@ -154,7 +154,7 @@ def _Py_mod_gil() -> int:  # noqa: N802
     return 0
 
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"
 __all__ = [
     "BUILTIN_ACTIONS",
     "CLI",

{milo_cli-0.2.0 → 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.2.0 → milo_cli-0.2.1}/src/milo/commands.py

@@ -9,6 +9,7 @@ import io
 import os
 import sys
 from collections.abc import Callable
+from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any, NoReturn
 
 from milo._command_defs import (
@@ -41,6 +42,39 @@ __all__ = [
 ]
 
 
+# ---------------------------------------------------------------------------
+# Resolve result types — discriminated union for command resolution
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedCommand:
+    """A command was found and should be dispatched."""
+
+    command: CommandDef | LazyCommandDef
+    fmt: str
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedGroup:
+    """A group was invoked without a subcommand — show its help."""
+
+    group: Group
+    fmt: str
+    prog: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedNothing:
+    """No command or group matched — may offer did-you-mean."""
+
+    attempted: str | None
+    fmt: str
+
+
+ResolveResult = ResolvedCommand | ResolvedGroup | ResolvedNothing
+
+
 class _MiloArgumentParser(argparse.ArgumentParser):
     """ArgumentParser subclass that provides did-you-mean suggestions."""
 
@@ -186,6 +220,7 @@ class CLI:
         examples: tuple[dict[str, Any], ...] | list[dict[str, Any]] = (),
         confirm: str = "",
         annotations: dict[str, Any] | None = None,
+        display_result: bool = True,
     ) -> Callable:
         """Register a function as a CLI command.
 
@@ -198,6 +233,8 @@ class CLI:
             confirm: If set, prompt user with this message before executing.
             annotations: MCP tool annotations (readOnlyHint, destructiveHint,
                 idempotentHint, openWorldHint).
+            display_result: If False, suppress plain-format output while still
+                returning data for ``--format json`` or ``--output-file``.
         """
 
         def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
@@ -211,6 +248,7 @@ class CLI:
                 examples=tuple(examples),
                 confirm=confirm,
                 annotations=annotations,
+                display_result=display_result,
             )
             self._commands[name] = cmd
             for alias in aliases:
@@ -233,11 +271,16 @@ class CLI:
         examples: tuple[dict[str, Any], ...] | list[dict[str, Any]] = (),
         confirm: str = "",
         annotations: dict[str, Any] | None = None,
+        display_result: bool = True,
     ) -> LazyCommandDef:
         """Register a lazy-loaded command.
 
         The handler module is not imported until the command is invoked.
         This keeps CLI startup fast for large command sets.
+
+        When providing a pre-computed *schema*, include ``"default"`` fields
+        in properties for optional parameters so argparse receives the correct
+        defaults without importing the handler module.
         """
         cmd = LazyCommandDef(
             name=name,
@@ -250,6 +293,7 @@ class CLI:
             examples=examples,
             confirm=confirm,
             annotations=annotations,
+            display_result=display_result,
         )
         self._commands[name] = cmd
         for alias in aliases:
@@ -620,7 +664,7 @@ class CLI:
                 "--format",
                 choices=["plain", "json", "table"],
                 default="plain",
-                help="Output format (default: plain)",
+                help="Output format",
             )
 
     def _add_groups_to_subparsers(
@@ -670,13 +714,21 @@ class CLI:
             # Determine type
             json_type = param_schema.get("type", "string")
             if json_type == "boolean":
-                default = (
-                    param.default
-                    if param and param.default is not inspect.Parameter.empty
-                    else False
-                )
-                kwargs["action"] = "store_true"
+                if param and param.default is not inspect.Parameter.empty:
+                    default = param.default
+                elif "default" in param_schema:
+                    default = param_schema["default"]
+                else:
+                    default = False
                 kwargs["default"] = default
+                if default is True:
+                    # default=True → --no-xxx flag to disable
+                    flag = f"--no-{param_name.replace('_', '-')}"
+                    kwargs["action"] = "store_false"
+                    parser.add_argument(flag, dest=param_name, **kwargs)
+                    continue
+                else:
+                    kwargs["action"] = "store_true"
             elif json_type == "integer":
                 kwargs["type"] = int
             elif json_type == "number":
@@ -691,9 +743,15 @@ class CLI:
             else:
                 kwargs["type"] = str
 
-            # Set default from signature if available
+            # Enum choices from schema
+            if "enum" in param_schema:
+                kwargs["choices"] = param_schema["enum"]
+
+            # Set default from signature or schema
             if param and param.default is not inspect.Parameter.empty and json_type != "boolean":
                 kwargs["default"] = param.default
+            elif "default" not in kwargs and "default" in param_schema:
+                kwargs["default"] = param_schema["default"]
 
             # Required vs optional
             if param_name in required_set and json_type != "boolean":
@@ -710,6 +768,7 @@ class CLI:
     def run(self, argv: list[str] | None = None) -> Any:
         """Parse args and dispatch to the appropriate command."""
         parser = self.build_parser()
+        self._parser = parser
         args = parser.parse_args(argv)
 
         # --completions mode
@@ -747,20 +806,26 @@ class CLI:
         ctx = self._build_context(args)
 
         # Resolve command from args (may be nested in groups)
-        found, fmt = self._resolve_command_from_args(args)
-        if not found:
-            # Did-you-mean suggestion for typos
-            cmd_name = getattr(args, "_command", None)
-            if cmd_name:
-                suggestion = self.suggest_command(cmd_name)
+        result = self._resolve_command_from_args(args)
+
+        if isinstance(result, ResolvedGroup):
+            result.group.format_help(result.prog)
+            return None
+
+        if isinstance(result, ResolvedNothing):
+            if result.attempted:
+                suggestion = self.suggest_command(result.attempted)
                 if suggestion:
                     sys.stderr.write(
-                        f"Unknown command: {cmd_name!r}. Did you mean {suggestion!r}?\n"
+                        f"Unknown command: {result.attempted!r}. Did you mean {suggestion!r}?\n"
                     )
                     return None
-            parser.print_help()
+            self._format_root_help()
             return None
 
+        found = result.command
+        fmt = result.fmt
+
         # Resolve lazy commands
         cmd = found.resolve() if isinstance(found, LazyCommandDef) else found
 
@@ -838,13 +903,17 @@ class CLI:
                 ctx.error(f"after_command hook failed: {type(exc).__name__}: {exc}")
 
         # Format and output (to file or stdout)
-        output_file = ctx.output_file
-        if output_file:
-            formatted = format_output(result, fmt=fmt)
-            with open(output_file, "w") as f:
-                f.write(formatted + "\n")
-        else:
-            write_output(result, fmt=fmt)
+        # When display_result=False, suppress plain-format stdout output but
+        # still honor explicit --format or --output-file requests.
+        suppress = not cmd.display_result and fmt == "plain" and not ctx.output_file
+        if not suppress:
+            output_file = ctx.output_file
+            if output_file:
+                formatted = format_output(result, fmt=fmt)
+                with open(output_file, "w") as f:
+                    f.write(formatted + "\n")
+            else:
+                write_output(result, fmt=fmt)
 
         return result
 
@@ -914,55 +983,94 @@ class CLI:
             globals=user_globals,
         )
 
-    def _resolve_command_from_args(
-        self, args: argparse.Namespace
-    ) -> tuple[CommandDef | LazyCommandDef | None, str]:
-        """Walk the parsed args to find the leaf command."""
+    def _format_root_help(self) -> None:
+        """Render root help from command/group registries and the actual parser."""
+        from milo.help import HelpState
+        from milo.templates import get_env
+
+        commands = tuple(
+            [
+                {"name": cmd.name, "help": getattr(cmd, "description", "")}
+                for cmd in self._commands.values()
+                if not getattr(cmd, "hidden", False)
+            ]
+            + [
+                {"name": g.name, "help": g.description}
+                for g in self._groups.values()
+                if not g.hidden
+            ]
+        )
+
+        # Derive options from the actual parser so new flags are never missed
+        options: list[dict[str, Any]] = []
+        for action in self._parser._actions:
+            if isinstance(action, argparse._SubParsersAction):
+                continue
+            flags = ", ".join(action.option_strings) if action.option_strings else ""
+            if not flags:
+                continue
+            entry: dict[str, Any] = {"flags": flags, "help": action.help or ""}
+            if action.metavar:
+                entry["metavar"] = action.metavar
+            options.append(entry)
+
+        state = HelpState(
+            prog=self.name,
+            description=self.description,
+            commands=commands,
+            options=tuple(options),
+        )
+        env = get_env()
+        template = env.get_template("help.kida")
+        sys.stdout.write(template.render(state=state) + "\n")
+        sys.stdout.flush()
+
+    def _resolve_command_from_args(self, args: argparse.Namespace) -> ResolveResult:
+        """Walk the parsed args to find the leaf command, group, or nothing."""
         fmt = getattr(args, "format", "plain")
 
-        # Check top-level command
         cmd_name = getattr(args, "_command", None)
         if not cmd_name:
-            return None, fmt
+            return ResolvedNothing(attempted=None, fmt=fmt)
 
-        # Is it a direct command?
+        # Direct command?
         cmd = self.get_command(cmd_name)
         if cmd:
-            return cmd, fmt
+            return ResolvedCommand(command=cmd, fmt=fmt)
 
-        # Is it a group? Walk into it.
+        # Group? Walk into it.
         group = self._groups.get(cmd_name)
         if group is None:
             resolved = self._group_alias_map.get(cmd_name)
             if resolved:
                 group = self._groups.get(resolved)
         if group is None:
-            return None, fmt
+            return ResolvedNothing(attempted=cmd_name, fmt=fmt)
 
-        return self._resolve_group_command(group, args, fmt)
+        return self._resolve_group_command(group, args, fmt, prog=self.name)
 
     def _resolve_group_command(
         self,
         group: Group,
         args: argparse.Namespace,
         fmt: str,
-    ) -> tuple[CommandDef | None, str]:
+        prog: str = "",
+    ) -> ResolveResult:
         """Recursively resolve a command within a group from parsed args."""
+        group_prog = f"{prog} {group.name}".strip()
         sub_name = getattr(args, f"_command_{group.name}", None)
         if not sub_name:
-            return None, fmt
+            return ResolvedGroup(group=group, fmt=fmt, prog=group_prog)
 
-        # Check if it's a command in this group
         cmd = group.get_command(sub_name)
         if cmd:
-            return cmd, fmt
+            return ResolvedCommand(command=cmd, fmt=fmt)
 
-        # Check if it's a nested sub-group
         sub_group = group.get_group(sub_name)
         if sub_group:
-            return self._resolve_group_command(sub_group, args, fmt)
+            return self._resolve_group_command(sub_group, args, fmt, prog=group_prog)
 
-        return None, fmt
+        return ResolvedNothing(attempted=sub_name, fmt=fmt)
 
     def call(self, command_name: str, **kwargs: Any) -> Any:
         """Programmatically call a command by name or dotted path.

{milo_cli-0.2.0 → milo_cli-0.2.1}/src/milo/groups.py

@@ -67,6 +67,7 @@ class Group:
         hidden: bool = False,
         examples: tuple[dict[str, Any], ...] | list[dict[str, Any]] = (),
         confirm: str = "",
+        display_result: bool = True,
     ) -> Callable:
         """Register a function as a command within this group."""
         from milo.commands import _make_command_def
@@ -81,6 +82,7 @@ class Group:
                 hidden=hidden,
                 examples=tuple(examples),
                 confirm=confirm,
+                display_result=display_result,
             )
             self._commands[name] = cmd
             for alias in aliases:
@@ -100,6 +102,10 @@ class Group:
         aliases: tuple[str, ...] | list[str] = (),
         tags: tuple[str, ...] | list[str] = (),
         hidden: bool = False,
+        examples: tuple[dict[str, Any], ...] | list[dict[str, Any]] = (),
+        confirm: str = "",
+        annotations: dict[str, Any] | None = None,
+        display_result: bool = True,
     ) -> Any:
         """Register a lazy-loaded command within this group.
 
@@ -115,6 +121,10 @@ class Group:
             aliases=aliases,
             tags=tags,
             hidden=hidden,
+            examples=examples,
+            confirm=confirm,
+            annotations=annotations,
+            display_result=display_result,
         )
         self._commands[name] = cmd
         for alias in aliases:
@@ -181,6 +191,38 @@ class Group:
             hidden=self.hidden,
         )
 
+    def format_help(self, prog_prefix: str = "") -> str:
+        """Render help from this group's command/group registries.
+
+        Writes rendered help to stdout and returns the output string.
+        """
+        import sys
+
+        from milo.help import HelpState
+        from milo.templates import get_env
+
+        prog = f"{prog_prefix} {self.name}".strip() if prog_prefix else self.name
+        commands = tuple(
+            [
+                {"name": cmd.name, "help": getattr(cmd, "description", "")}
+                for cmd in self._commands.values()
+                if not getattr(cmd, "hidden", False)
+            ]
+            + [
+                {"name": g.name, "help": g.description}
+                for g in self._groups.values()
+                if not g.hidden
+            ]
+        )
+
+        state = HelpState(prog=prog, description=self.description, commands=commands)
+        env = get_env()
+        template = env.get_template("help.kida")
+        output = template.render(state=state)
+        sys.stdout.write(output + "\n")
+        sys.stdout.flush()
+        return output
+
     def walk_commands(self, prefix: str = ""):
         """Yield (dotted_path, CommandDef) for all commands in this tree."""
         path_prefix = f"{prefix}{self.name}." if prefix else f"{self.name}."

{milo_cli-0.2.0 → milo_cli-0.2.1}/src/milo/help.py

@@ -17,6 +17,8 @@ class HelpState:
     usage: str = ""
     groups: tuple[dict[str, Any], ...] = ()
     examples: tuple[dict[str, Any], ...] = ()
+    commands: tuple[dict[str, Any], ...] = ()
+    options: tuple[dict[str, Any], ...] = ()
 
 
 class HelpRenderer(argparse.HelpFormatter):

{milo_cli-0.2.0 → milo_cli-0.2.1}/src/milo/schema.py

@@ -6,6 +6,7 @@ import dataclasses
 import enum
 import functools
 import inspect
+import json
 import re as _re
 import types
 import typing
@@ -161,6 +162,15 @@ def function_to_schema(func: Callable[..., Any]) -> dict[str, Any]:
         properties[name] = prop
 
         has_default = param.default is not inspect.Parameter.empty
+        if has_default and isinstance(
+            param.default, (str, int, float, bool, type(None), list, dict)
+        ):
+            try:
+                json.dumps(param.default)
+            except TypeError, ValueError:
+                pass  # non-serializable nested value — omit default
+            else:
+                prop["default"] = param.default
         if not has_default and not is_optional:
             required.append(name)
 

milo_cli-0.2.1/src/milo/templates/help.kida

@@ -0,0 +1,30 @@
+{{ state.prog | bold }}{% if state.description %} {{ "-" | dim }} {{ state.description }}{% endif %}
+{%- if state.commands %}
+
+{{ "commands" | yellow | bold }}:
+{%- for cmd in state.commands %}
+  {{ cmd.name | cyan }}    {{ cmd.help }}
+{%- endfor %}
+{%- endif %}
+{%- for group in state.groups %}
+
+{{ group.title | yellow | bold }}:
+{%- for action in group.actions %}
+  {% if action.option_strings %}{{ action.option_strings | join(", ") | green }}{% if action.metavar %} {{ action.metavar | dim }}{% endif %}    {{ action.help }}{% if action.default is not none and action.default != "==SUPPRESS==" and action.default is not false and action.default != 0 and action.default != "" %} {{ ("(default: " ~ action.default ~ ")") | dim }}{% endif %}{% else %}{{ action.dest | cyan }}{% if action.metavar %} {{ action.metavar | dim }}{% endif %}    {{ action.help }}{% if action.default is not none and action.default != "==SUPPRESS==" and action.default is not false and action.default != 0 and action.default != "" %} {{ ("(default: " ~ action.default ~ ")") | dim }}{% endif %}{% endif %}
+{%- endfor %}
+{%- endfor %}
+{%- if state.options %}
+
+{{ "options" | yellow | bold }}:
+{%- for opt in state.options %}
+  {{ opt.flags | green }}{% if opt.metavar %} {{ opt.metavar | dim }}{% endif %}    {{ opt.help }}{% if opt.default %} {{ ("(default: " ~ opt.default ~ ")") | dim }}{% endif %}
+{%- endfor %}
+{%- endif %}
+{%- if state.examples %}
+
+{{ "examples" | yellow | bold }}:
+{%- for ex in state.examples %}
+  {{ ("$ " ~ ex.command) | green }}{% if ex.description %}
+    {{ ex.description | dim }}{% endif %}
+{%- endfor %}
+{%- endif %}

{milo_cli-0.2.0 → milo_cli-0.2.1}/src/milo_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: milo-cli
-Version: 0.2.0
+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/

{milo_cli-0.2.0 → milo_cli-0.2.1}/tests/test_effects.py

@@ -992,14 +992,14 @@ class TestDebounceEffect:
             yield Put(Action("DEBOUNCED_FIRE"))
 
         def parent():
-            # First debounce — 0.15s
-            yield Debounce(seconds=0.15, saga=inner_saga)
+            # First debounce — 0.2s
+            yield Debounce(seconds=0.2, saga=inner_saga)
             # Wait a bit, then retrigger before first fires
             yield Delay(seconds=0.05)
             # Second debounce — resets the timer
-            yield Debounce(seconds=0.15, saga=inner_saga)
+            yield Debounce(seconds=0.2, saga=inner_saga)
             # Wait long enough for second to fire
-            yield Delay(seconds=0.3)
+            yield Delay(seconds=0.5)
 
         def reducer(state, action):
             actions.append(action.type)
@@ -1007,7 +1007,7 @@ class TestDebounceEffect:
 
         store = Store(reducer, None)
         store.run_saga(parent())
-        time.sleep(0.6)
+        time.sleep(1.0)
         store._executor.shutdown(wait=True)
 
         # Should fire exactly once (first timer cancelled, second fires)
@@ -1460,10 +1460,10 @@ class TestEffectComposition:
         def parent():
             # Simulate: receive 3 rapid keys, debounce should fire once
             for _ in range(3):
-                yield Take("@@KEY", timeout=1.0)
-                yield Debounce(seconds=0.15, saga=search_saga)
+                yield Take("@@KEY", timeout=2.0)
+                yield Debounce(seconds=0.5, saga=search_saga)
             # Wait for debounce to fire
-            yield Delay(seconds=0.3)
+            yield Delay(seconds=1.0)
 
         def reducer(state, action):
             actions.append(action.type)
@@ -1478,7 +1478,7 @@ class TestEffectComposition:
         store.dispatch(Action("@@KEY", payload="b"))
         time.sleep(0.02)
         store.dispatch(Action("@@KEY", payload="c"))
-        time.sleep(0.6)
+        time.sleep(1.5)
         store._executor.shutdown(wait=True)
 
         # Debounce should have fired exactly once (last one)