ensue-cli 0.1.0__tar.gz

ensue_cli-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.eggs/
+.coverage

ensue_cli-0.1.0/Makefile

@@ -0,0 +1,39 @@
+.PHONY: format lint check test test-cov install clean build publish
+
+# Formatting
+format:
+	ruff format .
+
+# Linting
+lint:
+	ruff check --fix .
+
+# Check without modifying (for CI)
+check:
+	ruff format --check .
+	ruff check .
+
+# Run tests
+test:
+	pytest -v
+
+# Run tests with coverage
+test-cov:
+	pytest --cov=ensue_cli --cov-report=term-missing --cov-fail-under=100
+
+# Install in development mode
+install:
+	pip install -e ".[dev]"
+
+# Clean build artifacts
+clean:
+	rm -rf dist/ build/ *.egg-info src/*.egg-info .pytest_cache .ruff_cache
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+
+# Build package
+build: clean
+	python -m build
+
+# Publish to PyPI
+publish: build
+	twine upload dist/*

ensue_cli-0.1.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: ensue-cli
+Version: 0.1.0
+Summary: CLI for Ensue Memory - a distributed memory network for AI agents built on MCP, enabling persistent, shared context across conversations and applications
+Project-URL: Homepage, https://www.ensue-network.ai
+Project-URL: Repository, https://github.com/mutable-state-inc/ensue-cli
+Project-URL: Documentation, https://www.ensue-network.ai/docs
+Author: Mutable State Inc
+Keywords: agents,ai,cli,ensue,mcp,memory,model-context-protocol
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: click>=8.0
+Requires-Dist: mcp>=1.0
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Requires-Dist: twine>=4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ensue-cli
+
+CLI for Ensue Memory - a distributed memory network for AI agents built on MCP, enabling persistent, shared context across conversations and applications.
+
+## Installation
+
+```bash
+pip install ensue-cli
+```
+
+## Usage
+
+Set your authentication token:
+
+```bash
+export ENSUE_TOKEN=your-token
+```
+
+List available commands:
+
+```bash
+ensue --help
+```
+
+Commands are loaded dynamically from the MCP server.
+
+## Configuration
+
+- `ENSUE_TOKEN` (required): Your Ensue API token
+- `ENSUE_URL` (optional): API endpoint (defaults to https://www.ensue-network.ai/api/)

ensue_cli-0.1.0/README.md

@@ -0,0 +1,30 @@
+# ensue-cli
+
+CLI for Ensue Memory - a distributed memory network for AI agents built on MCP, enabling persistent, shared context across conversations and applications.
+
+## Installation
+
+```bash
+pip install ensue-cli
+```
+
+## Usage
+
+Set your authentication token:
+
+```bash
+export ENSUE_TOKEN=your-token
+```
+
+List available commands:
+
+```bash
+ensue --help
+```
+
+Commands are loaded dynamically from the MCP server.
+
+## Configuration
+
+- `ENSUE_TOKEN` (required): Your Ensue API token
+- `ENSUE_URL` (optional): API endpoint (defaults to https://www.ensue-network.ai/api/)

ensue_cli-0.1.0/pyproject.toml

@@ -0,0 +1,78 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ensue-cli"
+version = "0.1.0"
+description = "CLI for Ensue Memory - a distributed memory network for AI agents built on MCP, enabling persistent, shared context across conversations and applications"
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [
+    { name = "Mutable State Inc" }
+]
+keywords = ["mcp", "memory", "ai", "agents", "cli", "ensue", "model-context-protocol"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "click>=8.0",
+    "mcp>=1.0",
+    "rich>=13.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+    "pytest-cov>=4.0",
+    "build>=1.0",
+    "twine>=4.0",
+    "ruff>=0.8",
+]
+
+[project.scripts]
+ensue = "ensue_cli.cli:main"
+
+[project.urls]
+Homepage = "https://www.ensue-network.ai"
+Repository = "https://github.com/mutable-state-inc/ensue-cli"
+Documentation = "https://www.ensue-network.ai/docs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ensue_cli"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+ignore = ["SIM117"]  # nested with statements are clearer for async context managers
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.coverage.run]
+source = ["src/ensue_cli"]
+omit = ["*/__main__.py"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "if __name__ == .__main__.:",
+    "pragma: no cover",
+]

ensue_cli-0.1.0/src/ensue_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Ensue CLI - Command line interface for the Ensue Memory Network."""
+
+__version__ = "0.1.0"

ensue_cli-0.1.0/src/ensue_cli/cli.py

@@ -0,0 +1,141 @@
+"""Dynamic CLI for Ensue Memory Network."""
+
+import asyncio
+import json
+import os
+import sys
+
+import click
+from rich.console import Console
+from rich.json import JSON
+
+from . import client
+
+console = Console()
+DEFAULT_URL = "https://www.ensue-network.ai/api/"
+
+
+def run_async(coro):
+    """Run async coroutine, handling nested event loops."""
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        return asyncio.run(coro)
+    # If there's already a running loop, create a new one in a thread
+    import concurrent.futures
+
+    with concurrent.futures.ThreadPoolExecutor() as pool:
+        return pool.submit(asyncio.run, coro).result()
+
+
+def get_config():
+    url = os.environ.get("ENSUE_URL", DEFAULT_URL)
+    token = os.environ.get("ENSUE_TOKEN")
+    if not token:
+        console.print("[red]Error:[/red] ENSUE_TOKEN environment variable required")
+        sys.exit(1)
+    return url, token
+
+
+def print_result(result):
+    if hasattr(result, "content"):
+        for item in result.content:
+            if hasattr(item, "text"):
+                try:
+                    console.print(JSON(item.text))
+                except Exception:
+                    console.print(item.text)
+    else:
+        console.print(JSON(json.dumps(result, indent=2)))
+
+
+TYPE_MAP = {
+    "integer": click.INT,
+    "number": click.FLOAT,
+    "boolean": click.BOOL,
+}
+
+
+def parse_arg(value, schema_type):
+    if schema_type in ("array", "object") and isinstance(value, str):
+        try:
+            return json.loads(value)
+        except json.JSONDecodeError:
+            pass
+    return value
+
+
+def build_command(tool):
+    """Build a Click command from an MCP tool definition."""
+    schema = tool.get("inputSchema", {})
+    props = schema.get("properties", {})
+    required = set(schema.get("required", []))
+
+    params = [
+        click.Option(
+            [f"--{name.replace('_', '-')}"],
+            type=TYPE_MAP.get(p.get("type"), click.STRING),
+            required=name in required,
+            help=p.get("description", ""),
+        )
+        for name, p in props.items()
+    ]
+
+    def callback(**kwargs):
+        url, token = get_config()
+        args = {
+            k.replace("-", "_"): parse_arg(v, props.get(k.replace("-", "_"), {}).get("type"))
+            for k, v in kwargs.items()
+            if v is not None
+        }
+        result = run_async(client.call_tool(url, token, tool["name"], args))
+        print_result(result)
+
+    return click.Command(
+        name=tool["name"],
+        callback=callback,
+        params=params,
+        help=tool.get("description", ""),
+    )
+
+
+class MCPToolsCLI(click.Group):
+    """CLI that loads commands dynamically from MCP server."""
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self._tools = None
+
+    @property
+    def tools(self):
+        if self._tools is None:
+            url, token = get_config()
+            self._tools = {t["name"]: t for t in run_async(client.list_tools(url, token))}
+        return self._tools
+
+    def list_commands(self, ctx):
+        try:
+            return sorted(self.tools.keys())
+        except Exception as e:
+            console.print("[red]Connection error:[/red] Could not connect to MCP server")
+            console.print(f"[dim]{e}[/dim]")
+            return []
+
+    def get_command(self, ctx, name):
+        if name not in self.tools:
+            return None
+        return build_command(self.tools[name])
+
+
+@click.group(cls=MCPToolsCLI)
+@click.version_option()
+def main():
+    """Ensue Memory CLI - A distributed memory network for AI agents.
+
+    Commands are loaded dynamically from the MCP server.
+    Set ENSUE_TOKEN to authenticate.
+    """
+
+
+if __name__ == "__main__":
+    main()

ensue_cli-0.1.0/src/ensue_cli/client.py

@@ -0,0 +1,38 @@
+"""MCP client for communicating with the Ensue Memory Network."""
+
+from contextlib import asynccontextmanager
+from typing import Any
+
+from mcp import ClientSession
+from mcp.client.streamable_http import streamablehttp_client
+
+
+@asynccontextmanager
+async def create_session(url: str, token: str):
+    """Create an MCP client session connected to the Ensue service."""
+    headers = {"Authorization": f"Bearer {token}"}
+    async with streamablehttp_client(url, headers=headers) as (read_stream, write_stream, _):
+        async with ClientSession(read_stream, write_stream) as session:
+            await session.initialize()
+            yield session
+
+
+async def list_tools(url: str, token: str) -> list[dict[str, Any]]:
+    """Fetch the list of available tools from the MCP server."""
+    async with create_session(url, token) as session:
+        result = await session.list_tools()
+        return [
+            {
+                "name": tool.name,
+                "description": tool.description,
+                "inputSchema": tool.inputSchema,
+            }
+            for tool in result.tools
+        ]
+
+
+async def call_tool(url: str, token: str, name: str, arguments: dict[str, Any]) -> Any:
+    """Call a tool on the MCP server."""
+    async with create_session(url, token) as session:
+        result = await session.call_tool(name, arguments)
+        return result

ensue_cli-0.1.0/tests/test_integration.py

@@ -0,0 +1,169 @@
+"""Integration tests for Ensue CLI dynamic functionality."""
+
+import base64
+import json
+import os
+import uuid
+
+import pytest
+from click.testing import CliRunner
+
+from ensue_cli import client
+from ensue_cli.cli import main
+
+ENSUE_URL = os.environ.get("ENSUE_URL", "https://www.ensue-network.ai/api/")
+ENSUE_TOKEN = os.environ.get("ENSUE_TOKEN")
+
+pytestmark = pytest.mark.skipif(not ENSUE_TOKEN, reason="ENSUE_TOKEN environment variable not set")
+
+
+@pytest.fixture
+def runner():
+    return CliRunner(env={"ENSUE_TOKEN": ENSUE_TOKEN, "ENSUE_URL": ENSUE_URL})
+
+
+@pytest.fixture
+def test_key():
+    return f"cli-test-{uuid.uuid4()}"
+
+
+@pytest.mark.asyncio
+async def test_cli_commands_match_server_tools(runner):
+    """CLI commands should match tools available from the MCP server."""
+    # Get tools directly from server
+    server_tools = await client.list_tools(ENSUE_URL, ENSUE_TOKEN)
+    server_tool_names = {t["name"] for t in server_tools}
+
+    # Get commands from CLI
+    result = runner.invoke(main, ["--help"])
+    assert result.exit_code == 0
+
+    # Each server tool should appear in CLI help
+    for tool_name in server_tool_names:
+        assert tool_name in result.output, f"Tool '{tool_name}' not found in CLI"
+
+
+def test_cli_shows_help_without_error(runner):
+    """CLI --help should work and show available commands."""
+    result = runner.invoke(main, ["--help"])
+
+    assert result.exit_code == 0
+    assert "Ensue Memory CLI" in result.output
+    assert "Commands are loaded dynamically" in result.output
+
+
+def test_cli_shows_version(runner):
+    """CLI --version should show version."""
+    result = runner.invoke(main, ["--version"])
+
+    assert result.exit_code == 0
+    assert "0.1.0" in result.output
+
+
+@pytest.mark.asyncio
+async def test_cli_command_has_correct_options(runner):
+    """CLI command options should match the tool's input schema."""
+    # Get a tool's schema from server
+    tools = await client.list_tools(ENSUE_URL, ENSUE_TOKEN)
+    tool = next((t for t in tools if t["name"] == "create_memory"), None)
+
+    if not tool:
+        pytest.skip("create_memory tool not available")
+
+    schema = tool.get("inputSchema", {})
+    properties = schema.get("properties", {})
+
+    # Get CLI command help
+    result = runner.invoke(main, ["create_memory", "--help"])
+    assert result.exit_code == 0
+
+    # Each schema property should be a CLI option
+    for prop_name in properties:
+        option_name = f"--{prop_name.replace('_', '-')}"
+        assert option_name in result.output, f"Option '{option_name}' not in CLI"
+
+
+def test_cli_create_and_delete_memory(runner, test_key):
+    """Test full CLI workflow: create and delete a memory."""
+    # Value must be base64 encoded
+    test_value = base64.b64encode(json.dumps({"test": True, "key": test_key}).encode()).decode()
+
+    # Create memory via CLI
+    create_result = runner.invoke(
+        main,
+        [
+            "create_memory",
+            "--key-name",
+            test_key,
+            "--value",
+            test_value,
+            "--description",
+            "Integration test memory",
+        ],
+    )
+    assert create_result.exit_code == 0, f"Create failed: {create_result.output}"
+
+    # Delete memory via CLI
+    delete_result = runner.invoke(
+        main,
+        [
+            "delete_memory",
+            "--key-name",
+            test_key,
+        ],
+    )
+    assert delete_result.exit_code == 0, f"Delete failed: {delete_result.output}"
+
+
+def test_cli_missing_required_option(runner):
+    """CLI should error when required options are missing."""
+    result = runner.invoke(main, ["create_memory"])
+
+    # Should fail due to missing required options
+    assert result.exit_code != 0
+    assert "Missing option" in result.output or "required" in result.output.lower()
+
+
+@pytest.mark.asyncio
+async def test_all_tools_translate_to_valid_cli_commands(runner):
+    """Every tool from the server should translate to a working CLI command with correct options."""
+    tools = await client.list_tools(ENSUE_URL, ENSUE_TOKEN)
+
+    for tool in tools:
+        tool_name = tool["name"]
+        schema = tool.get("inputSchema", {})
+        properties = schema.get("properties", {})
+
+        # Each tool's help should be accessible
+        result = runner.invoke(main, [tool_name, "--help"])
+        assert result.exit_code == 0, f"Tool '{tool_name}' --help failed: {result.output}"
+
+        # Verify each property is translated to a CLI option
+        for prop_name, prop_schema in properties.items():
+            option_name = f"--{prop_name.replace('_', '-')}"
+            assert option_name in result.output, (
+                f"Tool '{tool_name}' missing option '{option_name}'"
+            )
+
+            # Verify type hints appear for typed options
+            prop_type = prop_schema.get("type")
+            if prop_type == "integer":
+                assert "INTEGER" in result.output or option_name in result.output
+            elif prop_type == "number":
+                assert "FLOAT" in result.output or option_name in result.output
+            elif prop_type == "boolean":
+                assert "BOOLEAN" in result.output or option_name in result.output
+
+
+@pytest.mark.asyncio
+async def test_all_tools_callable_with_help(runner):
+    """Verify every tool can at least show its help without errors."""
+    tools = await client.list_tools(ENSUE_URL, ENSUE_TOKEN)
+
+    errors = []
+    for tool in tools:
+        result = runner.invoke(main, [tool["name"], "--help"])
+        if result.exit_code != 0:
+            errors.append(f"{tool['name']}: {result.output}")
+
+    assert not errors, "Tools failed to show help:\n" + "\n".join(errors)

ensue_cli-0.1.0/tests/test_unit.py

@@ -0,0 +1,112 @@
+"""Unit tests for CLI internals (no network required)."""
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+from click.testing import CliRunner
+
+from ensue_cli.cli import get_config, main, parse_arg, print_result
+
+
+class TestGetConfig:
+    def test_missing_token_exits(self):
+        """get_config should exit when ENSUE_TOKEN is not set."""
+        runner = CliRunner(env={"ENSUE_TOKEN": ""})
+        with runner.isolated_filesystem():
+            with patch.dict("os.environ", {"ENSUE_TOKEN": ""}, clear=False):
+                with pytest.raises(SystemExit):
+                    get_config()
+
+    def test_returns_url_and_token(self):
+        """get_config should return URL and token from env."""
+        with patch.dict(
+            "os.environ",
+            {"ENSUE_TOKEN": "test-token", "ENSUE_URL": "http://test.com"},
+            clear=False,
+        ):
+            url, token = get_config()
+            assert url == "http://test.com"
+            assert token == "test-token"
+
+    def test_default_url(self):
+        """get_config should use default URL when not set."""
+        with patch.dict("os.environ", {"ENSUE_TOKEN": "test-token"}, clear=False):
+            # Remove ENSUE_URL if present
+            import os
+
+            os.environ.pop("ENSUE_URL", None)
+            url, token = get_config()
+            assert "ensue-network.ai" in url
+
+
+class TestParseArg:
+    def test_parses_json_array(self):
+        """parse_arg should parse JSON arrays."""
+        result = parse_arg('["a", "b"]', "array")
+        assert result == ["a", "b"]
+
+    def test_parses_json_object(self):
+        """parse_arg should parse JSON objects."""
+        result = parse_arg('{"key": "value"}', "object")
+        assert result == {"key": "value"}
+
+    def test_returns_original_on_invalid_json(self):
+        """parse_arg should return original value on JSON parse failure."""
+        result = parse_arg("not-json", "array")
+        assert result == "not-json"
+
+    def test_returns_value_for_other_types(self):
+        """parse_arg should return value unchanged for non-array/object types."""
+        assert parse_arg("hello", "string") == "hello"
+        assert parse_arg(42, "integer") == 42
+
+
+class TestPrintResult:
+    def test_prints_mcp_content(self, capsys):
+        """print_result should handle MCP CallToolResult with content."""
+        mock_result = MagicMock()
+        mock_item = MagicMock()
+        mock_item.text = '{"success": true}'
+        mock_result.content = [mock_item]
+
+        print_result(mock_result)
+        # Should not raise
+
+    def test_prints_mcp_content_invalid_json(self, capsys):
+        """print_result should handle non-JSON text content."""
+        mock_result = MagicMock()
+        mock_item = MagicMock()
+        mock_item.text = "plain text response"
+        mock_result.content = [mock_item]
+
+        print_result(mock_result)
+        captured = capsys.readouterr()
+        assert "plain text response" in captured.out
+
+    def test_prints_dict_result(self, capsys):
+        """print_result should handle dict results."""
+        print_result({"key": "value"})
+        # Should not raise
+
+
+class TestCLIErrorHandling:
+    def setup_method(self):
+        """Reset the CLI tools cache before each test."""
+        main._tools = None
+
+    def test_unknown_command(self):
+        """CLI should handle unknown commands gracefully."""
+        runner = CliRunner(env={"ENSUE_TOKEN": "test"})
+        # Mock client.list_tools to return known tools
+        with patch("ensue_cli.cli.client.list_tools") as mock_list:
+            mock_list.return_value = [{"name": "known_cmd", "inputSchema": {}}]
+            result = runner.invoke(main, ["unknown_command"])
+            assert result.exit_code != 0
+
+    def test_connection_error_on_list(self):
+        """CLI should handle connection errors when listing tools."""
+        runner = CliRunner(env={"ENSUE_TOKEN": "invalid"})
+
+        with patch("ensue_cli.cli.client.list_tools", side_effect=Exception("Connection failed")):
+            result = runner.invoke(main, ["--help"])
+            assert "Connection error" in result.output