elizaos-plugin-cli 2.0.0a4__tar.gz

elizaos_plugin_cli-2.0.0a4/.gitignore

@@ -0,0 +1,12 @@
+dist
+node_modules
+.env
+.elizadb
+.turbo
+target/
+__pycache__
+*.pyc
+.venv
+*.egg-info
+.DS_Store
+package-lock.json

elizaos_plugin_cli-2.0.0a4/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: elizaos-plugin-cli
+Version: 2.0.0a4
+Summary: elizaOS CLI Plugin - CLI framework and command registration
+Project-URL: Homepage, https://github.com/elizaos/eliza
+Project-URL: Repository, https://github.com/elizaos/eliza
+Author: elizaOS Contributors
+License-Expression: MIT
+Keywords: agents,ai,cli,commands,elizaos,framework
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: mypy>=1.14.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'

elizaos_plugin_cli-2.0.0a4/elizaos_plugin_cli/__init__.py

@@ -0,0 +1,63 @@
+"""elizaOS CLI Plugin - CLI framework and command registration.
+
+Provides:
+- CLI command registration and management via :class:`CliRegistry`
+- Type definitions for commands, arguments, and contexts
+- Duration/timeout parsing and formatting utilities
+- Progress reporting
+"""
+
+from elizaos_plugin_cli.registry import CliRegistry
+from elizaos_plugin_cli.types import (
+    CliArg,
+    CliCommand,
+    CliContext,
+    CliLogger,
+    CliPluginConfig,
+    CommonCommandOptions,
+    DefaultCliLogger,
+    ParsedDuration,
+    ProgressReporter,
+)
+from elizaos_plugin_cli.utils import (
+    DEFAULT_CLI_NAME,
+    DEFAULT_CLI_VERSION,
+    format_bytes,
+    format_cli_command,
+    format_duration,
+    parse_duration,
+    parse_timeout_ms,
+    truncate_string,
+)
+
+__version__ = "2.0.0"
+
+PLUGIN_NAME = "cli"
+PLUGIN_DESCRIPTION = "CLI framework plugin for command registration and execution"
+
+__all__ = [
+    # Registry
+    "CliRegistry",
+    # Types
+    "CliArg",
+    "CliCommand",
+    "CliContext",
+    "CliLogger",
+    "CliPluginConfig",
+    "CommonCommandOptions",
+    "DefaultCliLogger",
+    "ParsedDuration",
+    "ProgressReporter",
+    # Utils
+    "DEFAULT_CLI_NAME",
+    "DEFAULT_CLI_VERSION",
+    "format_bytes",
+    "format_cli_command",
+    "format_duration",
+    "parse_duration",
+    "parse_timeout_ms",
+    "truncate_string",
+    # Constants
+    "PLUGIN_NAME",
+    "PLUGIN_DESCRIPTION",
+]

elizaos_plugin_cli-2.0.0a4/elizaos_plugin_cli/registry.py

@@ -0,0 +1,99 @@
+"""CLI command registry.
+
+Provides command registration and management for the CLI plugin.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Iterator
+
+from elizaos_plugin_cli.types import CliCommand
+
+logger = logging.getLogger(__name__)
+
+
+class CliRegistry:
+    """Central registry for CLI commands.
+
+    Commands are stored by their primary name and can be looked up by name
+    or alias.
+
+    Example::
+
+        registry = CliRegistry()
+        cmd = CliCommand(name="run", description="Run the agent", handler_name="handle_run")
+        registry.register_command(cmd)
+        assert registry.has_command("run")
+    """
+
+    def __init__(self) -> None:
+        self._commands: dict[str, CliCommand] = {}
+
+    def register_command(self, cmd: CliCommand) -> CliCommand | None:
+        """Register a command.
+
+        If a command with the same name already exists, it is replaced and
+        the old command is returned.
+        """
+        logger.debug("Registering CLI command: %s", cmd.name)
+        old = self._commands.get(cmd.name)
+        self._commands[cmd.name] = cmd
+        return old
+
+    def unregister_command(self, name: str) -> CliCommand | None:
+        """Unregister a command by its primary name.
+
+        Returns the removed command if found, otherwise ``None``.
+        """
+        return self._commands.pop(name, None)
+
+    def get_command(self, name: str) -> CliCommand | None:
+        """Get a command by its primary name."""
+        return self._commands.get(name)
+
+    def find_command(self, name: str) -> CliCommand | None:
+        """Find a command by name or any of its aliases."""
+        # Direct lookup (fast path).
+        if name in self._commands:
+            return self._commands[name]
+        # Fall back to alias scan.
+        for cmd in self._commands.values():
+            if cmd.matches(name):
+                return cmd
+        return None
+
+    def list_commands(self) -> list[CliCommand]:
+        """List all registered commands, sorted by priority then name."""
+        return sorted(
+            self._commands.values(),
+            key=lambda c: (c.priority, c.name),
+        )
+
+    def has_command(self, name: str) -> bool:
+        """Check if a command with the given primary name is registered."""
+        return name in self._commands
+
+    def __len__(self) -> int:
+        """Return the number of registered commands."""
+        return len(self._commands)
+
+    def __bool__(self) -> bool:
+        """Return True if the registry has any commands."""
+        return bool(self._commands)
+
+    def __iter__(self) -> Iterator[CliCommand]:
+        """Iterate over all commands (unsorted)."""
+        return iter(self._commands.values())
+
+    def __contains__(self, name: str) -> bool:
+        """Support ``'name' in registry`` syntax."""
+        return self.has_command(name)
+
+    def clear(self) -> None:
+        """Remove all commands."""
+        self._commands.clear()
+
+    def command_names(self) -> list[str]:
+        """Get all primary command names, sorted alphabetically."""
+        return sorted(self._commands.keys())

elizaos_plugin_cli-2.0.0a4/elizaos_plugin_cli/types.py

@@ -0,0 +1,224 @@
+"""CLI plugin types.
+
+Core type definitions for CLI command registration and execution.
+All types are immutable dataclasses following the frozen pattern.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class CliArg:
+    """A single argument definition for a CLI command."""
+
+    name: str
+    """Argument name (e.g. 'output', 'verbose')."""
+    description: str
+    """Human-readable description."""
+    required: bool = False
+    """Whether this argument is required."""
+    default_value: str | None = None
+    """Optional default value when not supplied."""
+
+    @classmethod
+    def required_arg(cls, name: str, description: str) -> CliArg:
+        """Create a required argument."""
+        return cls(name=name, description=description, required=True)
+
+    @classmethod
+    def optional_arg(cls, name: str, description: str, default: str) -> CliArg:
+        """Create an optional argument with a default value."""
+        return cls(name=name, description=description, required=False, default_value=default)
+
+
+@dataclass(frozen=True)
+class CliCommand:
+    """Definition of a CLI command that can be registered in the registry."""
+
+    name: str
+    """Primary command name (e.g. 'run', 'config')."""
+    description: str
+    """Human-readable description."""
+    handler_name: str
+    """Name of the handler function to invoke."""
+    aliases: tuple[str, ...] = ()
+    """Alternate names for this command."""
+    args: tuple[CliArg, ...] = ()
+    """Arguments accepted by this command."""
+    priority: int = 100
+    """Priority for registration order (lower = earlier)."""
+
+    def matches(self, name: str) -> bool:
+        """Check if this command matches a name or any of its aliases."""
+        return self.name == name or name in self.aliases
+
+    def with_alias(self, alias: str) -> CliCommand:
+        """Return a new command with an additional alias."""
+        return CliCommand(
+            name=self.name,
+            description=self.description,
+            handler_name=self.handler_name,
+            aliases=(*self.aliases, alias),
+            args=self.args,
+            priority=self.priority,
+        )
+
+    def with_arg(self, arg: CliArg) -> CliCommand:
+        """Return a new command with an additional argument."""
+        return CliCommand(
+            name=self.name,
+            description=self.description,
+            handler_name=self.handler_name,
+            aliases=self.aliases,
+            args=(*self.args, arg),
+            priority=self.priority,
+        )
+
+    def with_priority(self, priority: int) -> CliCommand:
+        """Return a new command with a different priority."""
+        return CliCommand(
+            name=self.name,
+            description=self.description,
+            handler_name=self.handler_name,
+            aliases=self.aliases,
+            args=self.args,
+            priority=priority,
+        )
+
+
+@dataclass(frozen=True)
+class CliContext:
+    """Context provided to CLI command handlers."""
+
+    program_name: str
+    """Program name (e.g. 'elizaos', 'otto')."""
+    version: str
+    """CLI version string."""
+    description: str
+    """Human-readable description of the CLI."""
+    workspace_dir: str | None = None
+    """Optional workspace directory for file operations."""
+    config: dict[str, Any] | None = None
+    """Optional configuration key-value pairs."""
+
+
+class CliLogger(ABC):
+    """Abstract logger interface for CLI output, allowing pluggable backends."""
+
+    @abstractmethod
+    def info(self, msg: str) -> None:
+        """Log an informational message."""
+
+    @abstractmethod
+    def warn(self, msg: str) -> None:
+        """Log a warning message."""
+
+    @abstractmethod
+    def error(self, msg: str) -> None:
+        """Log an error message."""
+
+    def debug(self, msg: str) -> None:
+        """Log a debug message (optional, defaults to no-op)."""
+
+
+class DefaultCliLogger(CliLogger):
+    """Default logger that writes to stdout/stderr."""
+
+    def info(self, msg: str) -> None:
+        print(f"[INFO] {msg}")
+
+    def warn(self, msg: str) -> None:
+        print(f"[WARN] {msg}")
+
+    def error(self, msg: str) -> None:
+        import sys
+
+        print(f"[ERROR] {msg}", file=sys.stderr)
+
+    def debug(self, msg: str) -> None:
+        print(f"[DEBUG] {msg}")
+
+
+@dataclass
+class ProgressReporter:
+    """Tracks progress of a long-running operation."""
+
+    current: int = 0
+    """Current step number."""
+    total: int = 0
+    """Total number of steps (0 if unknown)."""
+    message: str = ""
+    """Current status message."""
+
+    def __init__(self, total: int = 0, message: str = "") -> None:
+        self.current = 0
+        self.total = total
+        self.message = message
+
+    def advance(self, message: str) -> None:
+        """Advance by one step with a new message."""
+        self.current += 1
+        self.message = message
+
+    def set(self, current: int, message: str) -> None:
+        """Set absolute progress."""
+        self.current = current
+        self.message = message
+
+    def fraction(self) -> float | None:
+        """Return progress as a fraction in [0.0, 1.0], or None if total is 0."""
+        if self.total == 0:
+            return None
+        return self.current / self.total
+
+    def is_complete(self) -> bool:
+        """Whether the operation is complete."""
+        return self.total > 0 and self.current >= self.total
+
+    def display(self) -> str:
+        """Format as a human-readable string like '[3/10] Building...'."""
+        if self.total > 0:
+            return f"[{self.current}/{self.total}] {self.message}"
+        return f"[{self.current}] {self.message}"
+
+
+@dataclass(frozen=True)
+class CommonCommandOptions:
+    """Common options that many CLI commands accept."""
+
+    json: bool = False
+    """Output as JSON."""
+    verbose: bool = False
+    """Verbose output."""
+    quiet: bool = False
+    """Quiet mode (minimal output)."""
+    force: bool = False
+    """Force action without confirmation."""
+    dry_run: bool = False
+    """Dry run (show what would happen)."""
+
+
+@dataclass(frozen=True)
+class ParsedDuration:
+    """Result of parsing a duration string."""
+
+    ms: int
+    """Duration in milliseconds."""
+    original: str
+    """The original input string."""
+    valid: bool
+    """Whether parsing succeeded."""
+
+
+@dataclass(frozen=True)
+class CliPluginConfig:
+    """CLI plugin configuration."""
+
+    name: str = "elizaos"
+    """CLI name."""
+    version: str = "1.0.0"
+    """CLI version."""

elizaos_plugin_cli-2.0.0a4/elizaos_plugin_cli/utils.py

@@ -0,0 +1,187 @@
+"""CLI utilities.
+
+Common utilities for CLI operations including duration parsing,
+byte formatting, and string helpers.
+"""
+
+from __future__ import annotations
+
+import re
+
+DEFAULT_CLI_NAME: str = "elizaos"
+"""Default CLI name."""
+
+DEFAULT_CLI_VERSION: str = "1.0.0"
+"""Default CLI version."""
+
+# Regex for matching duration components like "1h", "30m", "500ms".
+_DURATION_PART_RE = re.compile(
+    r"(\d+(?:\.\d+)?)\s*"
+    r"(milliseconds?|ms|seconds?|sec|s|minutes?|min|m|hours?|hr|h|days?|d)?",
+    re.IGNORECASE,
+)
+
+_UNIT_TO_MS: dict[str, float] = {
+    "ms": 1,
+    "millisecond": 1,
+    "milliseconds": 1,
+    "s": 1_000,
+    "sec": 1_000,
+    "second": 1_000,
+    "seconds": 1_000,
+    "m": 60_000,
+    "min": 60_000,
+    "minute": 60_000,
+    "minutes": 60_000,
+    "h": 3_600_000,
+    "hr": 3_600_000,
+    "hour": 3_600_000,
+    "hours": 3_600_000,
+    "d": 86_400_000,
+    "day": 86_400_000,
+    "days": 86_400_000,
+}
+
+
+def parse_duration(s: str) -> int | None:
+    """Parse a duration string to milliseconds.
+
+    Supports compound formats and multiple unit suffixes::
+
+        "1h"      -> 3600000
+        "30m"     -> 1800000
+        "1h30m"   -> 5400000
+        "2d"      -> 172800000
+        "500ms"   -> 500
+        "1000"    -> 1000 (plain number = milliseconds)
+
+    Returns ``None`` for invalid input.
+    """
+    s = s.strip().lower()
+    if not s:
+        return None
+
+    # Plain numeric value -> milliseconds.
+    try:
+        return int(s)
+    except ValueError:
+        pass
+
+    # Try float as bare number.
+    try:
+        return round(float(s))
+    except ValueError:
+        pass
+
+    total_ms = 0
+    found_any = False
+    pos = 0
+
+    while pos < len(s):
+        # Skip whitespace.
+        while pos < len(s) and s[pos].isspace():
+            pos += 1
+        if pos >= len(s):
+            break
+
+        match = _DURATION_PART_RE.match(s, pos)
+        if not match:
+            return None
+
+        value = float(match.group(1))
+        unit = (match.group(2) or "").lower()
+
+        if not unit:
+            if found_any:
+                return None  # Bare number in middle of compound.
+            # Bare number = ms.
+            multiplier = 1.0
+        else:
+            multiplier = _UNIT_TO_MS.get(unit)
+            if multiplier is None:
+                return None
+
+        total_ms += round(value * multiplier)
+        found_any = True
+        pos = match.end()
+
+    return total_ms if found_any else None
+
+
+def format_duration(ms: int) -> str:
+    """Format milliseconds as a human-readable string.
+
+    Uses the largest appropriate unit:
+
+    - ``< 1s``  -> ``"450ms"``
+    - ``< 1m``  -> ``"12.3s"``
+    - ``< 1h``  -> ``"5.2m"``
+    - ``< 1d``  -> ``"3.5h"``
+    - ``>= 1d`` -> ``"2.0d"``
+    """
+    if ms < 1_000:
+        return f"{ms}ms"
+    if ms < 60_000:
+        return f"{ms / 1_000:.1f}s"
+    if ms < 3_600_000:
+        return f"{ms / 60_000:.1f}m"
+    if ms < 86_400_000:
+        return f"{ms / 3_600_000:.1f}h"
+    return f"{ms / 86_400_000:.1f}d"
+
+
+def format_bytes(bytes_count: int) -> str:
+    """Format a byte count as a human-readable string (e.g. ``"1.5 MB"``).
+
+    Uses binary prefixes (1 KB = 1024 bytes).
+    """
+    units = ("B", "KB", "MB", "GB", "TB")
+    value = float(bytes_count)
+    unit_idx = 0
+
+    while value >= 1024.0 and unit_idx < len(units) - 1:
+        value /= 1024.0
+        unit_idx += 1
+
+    if unit_idx == 0:
+        return f"{bytes_count} B"
+    return f"{value:.1f} {units[unit_idx]}"
+
+
+def truncate_string(s: str, max_len: int) -> str:
+    """Truncate a string to at most ``max_len`` characters.
+
+    Appends ``"..."`` if truncated. If the string fits, returns it unchanged.
+    """
+    if len(s) <= max_len:
+        return s
+    if max_len <= 3:
+        return "." * max_len
+    return s[: max_len - 3] + "..."
+
+
+def parse_timeout_ms(input_str: str | None, default_ms: int) -> int:
+    """Parse a timeout string with a fallback default.
+
+    If ``input_str`` is ``None`` or parsing fails, returns ``default_ms``.
+    """
+    if input_str is None:
+        return default_ms
+    result = parse_duration(input_str)
+    return result if result is not None else default_ms
+
+
+def format_cli_command(
+    command: str,
+    cli_name: str | None = None,
+    profile: str | None = None,
+    env: str | None = None,
+) -> str:
+    """Format a CLI command string with optional profile and env context."""
+    parts = [cli_name or DEFAULT_CLI_NAME]
+    if profile is not None:
+        parts.append(f"--profile {profile}")
+    if env is not None:
+        parts.append(f"--env {env}")
+    parts.append(command)
+    return " ".join(parts)

elizaos_plugin_cli-2.0.0a4/pyproject.toml

@@ -0,0 +1,76 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "elizaos-plugin-cli"
+version = "2.0.0a4"
+description = "elizaOS CLI Plugin - CLI framework and command registration"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "elizaOS Contributors" }]
+keywords = ["ai", "agents", "cli", "commands", "framework", "elizaos"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0.0",
+  "pytest-asyncio>=0.24.0",
+  "pytest-cov>=6.0.0",
+  "mypy>=1.14.0",
+  "ruff>=0.9.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/elizaos/eliza"
+Repository = "https://github.com/elizaos/eliza"
+
+[tool.hatch.build.targets.wheel]
+packages = ["elizaos_plugin_cli"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/elizaos_plugin_cli", "/tests"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = "test_*.py"
+python_functions = "test_*"
+addopts = "-v"
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_return_any = true
+warn_unused_ignores = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+no_implicit_optional = true
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "B", "C4", "UP", "ANN", "S"]
+ignore = [
+  "E501",
+  "ANN101",
+  "ANN102",
+  "S101",
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["elizaos_plugin_cli"]

elizaos_plugin_cli-2.0.0a4/tests/__init__.py

@@ -0,0 +1 @@
+

elizaos_plugin_cli-2.0.0a4/tests/conftest.py

@@ -0,0 +1,30 @@
+"""Shared test fixtures for plugin-cli tests."""
+
+from __future__ import annotations
+
+import pytest
+
+from elizaos_plugin_cli.registry import CliRegistry
+from elizaos_plugin_cli.types import CliArg, CliCommand
+
+
+@pytest.fixture
+def registry() -> CliRegistry:
+    """Create a fresh, empty CliRegistry for each test."""
+    return CliRegistry()
+
+
+@pytest.fixture
+def sample_command() -> CliCommand:
+    """A sample command for testing."""
+    return CliCommand(
+        name="run",
+        description="Run the agent",
+        handler_name="handle_run",
+        aliases=("start", "go"),
+        args=(
+            CliArg.required_arg("target", "Deployment target"),
+            CliArg.optional_arg("port", "Listen port", "3000"),
+        ),
+        priority=10,
+    )

elizaos_plugin_cli-2.0.0a4/tests/test_registry.py

@@ -0,0 +1,141 @@
+"""Tests for CLI registry."""
+
+from __future__ import annotations
+
+from elizaos_plugin_cli.registry import CliRegistry
+from elizaos_plugin_cli.types import CliArg, CliCommand
+
+
+def test_register_and_lookup(registry: CliRegistry) -> None:
+    cmd = CliCommand(name="run", description="Run the agent", handler_name="handle_run")
+    registry.register_command(cmd)
+
+    found = registry.get_command("run")
+    assert found is not None
+    assert found.name == "run"
+    assert found.description == "Run the agent"
+
+
+def test_has_command(registry: CliRegistry) -> None:
+    assert not registry.has_command("run")
+    registry.register_command(
+        CliCommand(name="run", description="Run", handler_name="handle_run")
+    )
+    assert registry.has_command("run")
+    assert not registry.has_command("build")
+
+
+def test_list_sorted_by_priority(registry: CliRegistry) -> None:
+    registry.register_command(
+        CliCommand(name="config", description="Config", handler_name="h1", priority=50)
+    )
+    registry.register_command(
+        CliCommand(name="run", description="Run", handler_name="h2", priority=10)
+    )
+    registry.register_command(
+        CliCommand(name="build", description="Build", handler_name="h3", priority=30)
+    )
+
+    cmds = registry.list_commands()
+    assert len(cmds) == 3
+    assert cmds[0].name == "run"     # priority 10
+    assert cmds[1].name == "build"   # priority 30
+    assert cmds[2].name == "config"  # priority 50
+
+
+def test_unregister(registry: CliRegistry) -> None:
+    registry.register_command(
+        CliCommand(name="run", description="Run", handler_name="h")
+    )
+    assert registry.has_command("run")
+
+    removed = registry.unregister_command("run")
+    assert removed is not None
+    assert not registry.has_command("run")
+    assert len(registry) == 0
+
+
+def test_replace_existing(registry: CliRegistry) -> None:
+    registry.register_command(
+        CliCommand(name="run", description="Old", handler_name="h_v1")
+    )
+    old = registry.register_command(
+        CliCommand(name="run", description="New", handler_name="h_v2")
+    )
+
+    assert old is not None
+    assert old.description == "Old"
+    assert registry.get_command("run") is not None
+    assert registry.get_command("run").description == "New"
+
+
+def test_find_by_alias(registry: CliRegistry, sample_command: CliCommand) -> None:
+    registry.register_command(sample_command)
+
+    assert registry.find_command("start") is not None
+    assert registry.find_command("go") is not None
+    assert registry.find_command("run") is not None
+    assert registry.find_command("stop") is None
+
+
+def test_command_names(registry: CliRegistry) -> None:
+    registry.register_command(CliCommand(name="build", description="B", handler_name="h1"))
+    registry.register_command(CliCommand(name="run", description="R", handler_name="h2"))
+    registry.register_command(CliCommand(name="config", description="C", handler_name="h3"))
+
+    names = registry.command_names()
+    assert names == ["build", "config", "run"]
+
+
+def test_clear(registry: CliRegistry) -> None:
+    registry.register_command(CliCommand(name="a", description="A", handler_name="h1"))
+    registry.register_command(CliCommand(name="b", description="B", handler_name="h2"))
+    assert len(registry) == 2
+
+    registry.clear()
+    assert len(registry) == 0
+    assert not registry
+
+
+def test_contains_protocol(registry: CliRegistry) -> None:
+    registry.register_command(CliCommand(name="run", description="R", handler_name="h"))
+    assert "run" in registry
+    assert "build" not in registry
+
+
+def test_iter_protocol(registry: CliRegistry) -> None:
+    registry.register_command(CliCommand(name="a", description="A", handler_name="h1"))
+    registry.register_command(CliCommand(name="b", description="B", handler_name="h2"))
+    names = {cmd.name for cmd in registry}
+    assert names == {"a", "b"}
+
+
+def test_command_with_args() -> None:
+    cmd = (
+        CliCommand(name="deploy", description="Deploy", handler_name="handle_deploy")
+        .with_arg(CliArg.required_arg("target", "Deployment target"))
+        .with_arg(CliArg.optional_arg("port", "Listen port", "3000"))
+    )
+    assert len(cmd.args) == 2
+    assert cmd.args[0].required is True
+    assert cmd.args[0].name == "target"
+    assert cmd.args[1].required is False
+    assert cmd.args[1].default_value == "3000"
+
+
+def test_command_matches() -> None:
+    cmd = CliCommand(
+        name="run",
+        description="Run",
+        handler_name="h",
+        aliases=("start", "go"),
+    )
+    assert cmd.matches("run")
+    assert cmd.matches("start")
+    assert cmd.matches("go")
+    assert not cmd.matches("stop")
+
+
+def test_unregister_nonexistent(registry: CliRegistry) -> None:
+    result = registry.unregister_command("nonexistent")
+    assert result is None

elizaos_plugin_cli-2.0.0a4/tests/test_utils.py

@@ -0,0 +1,170 @@
+"""Tests for CLI utilities."""
+
+from __future__ import annotations
+
+from elizaos_plugin_cli.types import (
+    CliContext,
+    CommonCommandOptions,
+    ProgressReporter,
+)
+from elizaos_plugin_cli.utils import (
+    DEFAULT_CLI_NAME,
+    DEFAULT_CLI_VERSION,
+    format_bytes,
+    format_cli_command,
+    format_duration,
+    parse_duration,
+    parse_timeout_ms,
+    truncate_string,
+)
+from elizaos_plugin_cli import PLUGIN_NAME
+
+
+# ---------------------------------------------------------------------------
+# Duration parsing
+# ---------------------------------------------------------------------------
+
+
+def test_parse_duration_seconds() -> None:
+    assert parse_duration("1s") == 1_000
+    assert parse_duration("90s") == 90_000
+    assert parse_duration("0s") == 0
+
+
+def test_parse_duration_minutes() -> None:
+    assert parse_duration("30m") == 30 * 60_000
+    assert parse_duration("1min") == 60_000
+
+
+def test_parse_duration_hours() -> None:
+    assert parse_duration("1h") == 3_600_000
+    assert parse_duration("2hr") == 7_200_000
+
+
+def test_parse_duration_days() -> None:
+    assert parse_duration("2d") == 2 * 86_400_000
+    assert parse_duration("1day") == 86_400_000
+
+
+def test_parse_duration_compound() -> None:
+    assert parse_duration("1h30m") == 5_400_000   # 90 minutes
+    assert parse_duration("2d12h") == 216_000_000  # 60 hours
+
+
+def test_parse_duration_milliseconds() -> None:
+    assert parse_duration("500ms") == 500
+    assert parse_duration("1000") == 1000
+
+
+def test_parse_duration_invalid() -> None:
+    assert parse_duration("") is None
+    assert parse_duration("abc") is None
+    assert parse_duration("1x") is None
+    assert parse_duration("h1") is None
+
+
+def test_parse_duration_whitespace() -> None:
+    assert parse_duration("  1h  ") == 3_600_000
+    assert parse_duration(" 30m ") == 1_800_000
+
+
+# ---------------------------------------------------------------------------
+# Format utilities
+# ---------------------------------------------------------------------------
+
+
+def test_format_duration_ranges() -> None:
+    assert format_duration(450) == "450ms"
+    assert format_duration(1500) == "1.5s"
+    assert format_duration(90_000) == "1.5m"
+    assert format_duration(5_400_000) == "1.5h"
+    assert format_duration(172_800_000) == "2.0d"
+
+
+def test_format_bytes_various() -> None:
+    assert format_bytes(0) == "0 B"
+    assert format_bytes(512) == "512 B"
+    assert format_bytes(1024) == "1.0 KB"
+    assert format_bytes(1536) == "1.5 KB"
+    assert format_bytes(1048576) == "1.0 MB"
+    assert format_bytes(1073741824) == "1.0 GB"
+    assert format_bytes(1099511627776) == "1.0 TB"
+
+
+def test_truncate_string() -> None:
+    assert truncate_string("hello", 10) == "hello"
+    assert truncate_string("hello world!", 8) == "hello..."
+    assert truncate_string("ab", 2) == "ab"
+    assert truncate_string("abcdef", 3) == "..."
+
+
+def test_parse_timeout_ms() -> None:
+    assert parse_timeout_ms("30s", 5000) == 30_000
+    assert parse_timeout_ms(None, 5000) == 5000
+    assert parse_timeout_ms("invalid!!", 5000) == 5000
+
+
+def test_format_cli_command_basic() -> None:
+    assert format_cli_command("run") == "elizaos run"
+
+
+def test_format_cli_command_full() -> None:
+    result = format_cli_command("run", cli_name="otto", profile="dev", env="staging")
+    assert result == "otto --profile dev --env staging run"
+
+
+# ---------------------------------------------------------------------------
+# Type tests
+# ---------------------------------------------------------------------------
+
+
+def test_cli_context_creation() -> None:
+    ctx = CliContext(
+        program_name="otto",
+        version="2.0.0",
+        description="Otto CLI",
+        workspace_dir="/home/user/project",
+    )
+    assert ctx.program_name == "otto"
+    assert ctx.version == "2.0.0"
+    assert ctx.workspace_dir == "/home/user/project"
+
+
+def test_progress_reporter() -> None:
+    progress = ProgressReporter(total=10, message="Starting...")
+    assert progress.fraction() == 0.0
+    assert not progress.is_complete()
+    assert progress.display() == "[0/10] Starting..."
+
+    progress.advance("Step 1 done")
+    assert progress.current == 1
+    assert progress.display() == "[1/10] Step 1 done"
+
+    progress.set(10, "Done!")
+    assert progress.is_complete()
+    assert progress.fraction() == 1.0
+
+
+def test_progress_reporter_unknown_total() -> None:
+    progress = ProgressReporter(total=0, message="Processing...")
+    assert progress.fraction() is None
+    assert not progress.is_complete()
+    assert progress.display() == "[0] Processing..."
+
+    progress.advance("Item processed")
+    assert progress.display() == "[1] Item processed"
+
+
+def test_common_command_options_default() -> None:
+    opts = CommonCommandOptions()
+    assert opts.json is False
+    assert opts.verbose is False
+    assert opts.quiet is False
+    assert opts.force is False
+    assert opts.dry_run is False
+
+
+def test_plugin_constants() -> None:
+    assert PLUGIN_NAME == "cli"
+    assert DEFAULT_CLI_NAME == "elizaos"
+    assert DEFAULT_CLI_VERSION == "1.0.0"