chore: add tests

Author: damassi

Makefile

@@ -1,4 +1,4 @@
-.PHONY: dev console lint install start type-check
+.PHONY: dev console lint install start test type-check
 
 install:
 	uv sync && uv run pre-commit install && cp .env.example .env && echo "Please edit the .env file with your API keys."
@@ -15,5 +15,8 @@ lint:
 start:
 	uv run chat
 
+test:
+	uv run pytest
+
 type-check:
 	uv run mypy src

README.md

@@ -42,6 +42,12 @@ Additional MCP servers are configured in `agent-chat-cli.config.yaml` and prompt
   - `make type-check`
 - Linting and formatting is via [Ruff](https://docs.astral.sh/ruff/)
   - `make lint`
+- Testing is via [pytest](https://docs.pytest.org/):
+  - `make test`
+
+See [docs/architecture.md](docs/architecture.md) for an overview of the codebase structure.
+
+### Textual Dev Console
 
 Textual has an integrated logging console that one can boot separately from the app to receive logs.
 

docs/architecture.md

@@ -0,0 +1,163 @@
+# Architecture
+
+Agent Chat CLI is a terminal-based chat interface for interacting with Claude agents, built with [Textual](https://textual.textualize.io/) and the [Claude Agent SDK](https://github.com/anthropics/claude-agent-sdk).
+
+### Directory Structure
+
+```
+src/agent_chat_cli/
+├── app.py                     # Main Textual application entry point
+├── core/
+│   ├── actions.py             # User action handlers
+│   ├── agent_loop.py          # Claude Agent SDK client wrapper
+│   ├── message_bus.py         # Message routing from agent to UI
+│   ├── ui_state.py            # Centralized UI state management
+│   └── styles.tcss            # Textual CSS styles
+├── components/
+│   ├── balloon_spinner.py     # Animated spinner widget
+│   ├── caret.py               # Input caret indicator
+│   ├── chat_history.py        # Chat message container
+│   ├── flex.py                # Horizontal flex container
+│   ├── header.py              # App header with MCP server status
+│   ├── messages.py            # Message data models and widgets
+│   ├── spacer.py              # Empty spacer widget
+│   ├── thinking_indicator.py  # "Agent is thinking" indicator
+│   ├── tool_permission_prompt.py  # Tool permission request UI
+│   └── user_input.py          # User text input widget
+└── utils/
+    ├── config.py              # YAML config loading
+    ├── enums.py               # Shared enumerations
+    ├── format_tool_input.py   # Tool input formatting
+    ├── logger.py              # Logging setup
+    ├── mcp_server_status.py   # MCP server connection state
+    ├── system_prompt.py       # System prompt builder
+    └── tool_info.py           # Tool name parsing
+```
+
+### Core Architecture
+
+The application follows a loosely coupled architecture with four main orchestration objects:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     AgentChatCLIApp                         │
+│  ┌───────────┐  ┌───────────┐  ┌─────────┐  ┌───────────┐  │
+│  │  UIState  │  │MessageBus │  │ Actions │  │ AgentLoop │  │
+│  └─────┬─────┘  └─────┬─────┘  └────┬────┘  └─────┬─────┘  │
+│        │              │             │              │        │
+│        └──────────────┴─────────────┴──────────────┘        │
+│                            │                                 │
+│  ┌─────────────────────────┴─────────────────────────────┐  │
+│  │                    Components                          │  │
+│  │  Header │ ChatHistory │ ThinkingIndicator │ UserInput │  │
+│  └────────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Core Modules
+
+**UIState** (`core/ui_state.py`)
+Centralized management of UI state behaviors. Handles:
+- Thinking indicator visibility and cursor blink state
+- Tool permission prompt display/hide
+- Interrupt state tracking
+
+This class was introduced in PR #9 to consolidate scattered UI state logic from Actions and MessageBus into a single cohesive module.
+
+**MessageBus** (`core/message_bus.py`)
+Routes messages from the AgentLoop to appropriate UI components:
+- `STREAM_EVENT`: Streaming text chunks to AgentMessage widgets
+- `ASSISTANT`: Complete assistant responses with tool use blocks
+- `SYSTEM` / `USER`: System and user messages
+- `TOOL_PERMISSION_REQUEST`: Triggers permission prompt UI
+- `RESULT`: Signals completion, resets state
+
+**Actions** (`core/actions.py`)
+User-initiated action handlers:
+- `submit_user_message()`: Posts user message and queries agent
+- `interrupt()`: Cancels current agent operation
+- `new()`: Starts new conversation, clears history
+- `respond_to_tool_permission()`: Handles permission prompt responses
+
+**AgentLoop** (`core/agent_loop.py`)
+Manages the Claude Agent SDK client lifecycle:
+- Initializes `ClaudeSDKClient` with config and MCP servers
+- Processes incoming messages via async generator
+- Handles tool permission flow via `_can_use_tool()` callback
+- Manages `query_queue` and `permission_response_queue` for async communication
+
+### Message Flow
+
+1. User types in `UserInput` and presses Enter
+2. `Actions.submit_user_message()` posts to UI and enqueues to `AgentLoop.query_queue`
+3. `AgentLoop` sends query to Claude Agent SDK and streams responses
+4. Responses flow through `MessageBus.handle_agent_message()` to update UI
+5. Tool use triggers permission prompt via `UIState.show_permission_prompt()`
+6. User response flows back through `Actions.respond_to_tool_permission()`
+
+### Components
+
+**UserInput** (`components/user_input.py`)
+Text input with:
+- Enter to submit
+- Ctrl+J for newlines (PR #10)
+- Control commands: `exit`, `clear`
+
+**ToolPermissionPrompt** (`components/tool_permission_prompt.py`)
+Modal prompt for tool permission requests:
+- Shows tool name and MCP server
+- Enter to allow, ESC to deny, or type custom response
+- Manages focus to prevent input elsewhere while visible
+
+**ChatHistory** (`components/chat_history.py`)
+Container for message widgets, handles `MessagePosted` events.
+
+**ThinkingIndicator** (`components/thinking_indicator.py`)
+Animated indicator shown during agent processing.
+
+**Header** (`components/header.py`)
+Displays available MCP servers with connection status via `MCPServerStatus` subscription.
+
+### Configuration
+
+Configuration is loaded from `agent-chat-cli.config.yaml`:
+
+```yaml
+system_prompt: "prompt.md"  # File path or literal string
+model: "claude-sonnet-4-20250514"
+permission_mode: "bypass_permissions"
+
+mcp_servers:
+  server_name:
+    description: "Server description"
+    command: "npx"
+    args: ["-y", "@some/mcp-server"]
+    env:
+      API_KEY: "$API_KEY"
+    enabled: true
+    prompt: "server_prompt.md"
+
+agents:
+  agent_name:
+    description: "Agent description"
+    prompt: "agent_prompt.md"
+    tools: ["tool1", "tool2"]
+```
+
+### Key Patterns
+
+**Reactive Properties**: Textual's `reactive` and `var` are used for automatic UI updates when state changes (e.g., `ThinkingIndicator.is_thinking`, `ToolPermissionPrompt.is_visible`).
+
+**Async Queues**: Communication between UI and AgentLoop uses `asyncio.Queue` for decoupled async message passing.
+
+**Observer Pattern**: `MCPServerStatus` uses callback subscriptions to notify components of connection state changes.
+
+**TYPE_CHECKING Guards**: Circular import prevention via `if TYPE_CHECKING:` blocks for type hints.
+
+### Testing
+
+Tests use pytest with pytest-asyncio for async support and Textual's pilot testing framework for UI interactions.
+
+```bash
+make test
+```

pyproject.toml

@@ -19,6 +19,9 @@ dependencies = [
 dev = [
     "mypy>=1.19.0",
     "pre-commit>=4.3.0",
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.24.0",
+    "pytest-textual-snapshot>=1.0.0",
     "ruff>=0.14.7",
     "textual-dev>=1.8.0",
     "types-pyyaml>=6.0.12.20250915",
@@ -30,3 +33,9 @@ dev = "textual_dev.cli:run"
 
 [tool.uv]
 package = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+pythonpath = ["src"]

tests/__init__.py

@@ -0,0 +1,39 @@
+from agent_chat_cli.components.messages import Message, MessageType
+
+
+class TestMessage:
+    def test_system_creates_system_message(self):
+        msg = Message.system("System alert")
+
+        assert msg.type == MessageType.SYSTEM
+        assert msg.content == "System alert"
+        assert msg.metadata is None
+
+    def test_user_creates_user_message(self):
+        msg = Message.user("Hello there")
+
+        assert msg.type == MessageType.USER
+        assert msg.content == "Hello there"
+        assert msg.metadata is None
+
+    def test_agent_creates_agent_message(self):
+        msg = Message.agent("I can help with that.")
+
+        assert msg.type == MessageType.AGENT
+        assert msg.content == "I can help with that."
+        assert msg.metadata is None
+
+    def test_tool_creates_tool_message_with_metadata(self):
+        msg = Message.tool("read_file", '{"path": "/tmp/test.txt"}')
+
+        assert msg.type == MessageType.TOOL
+        assert msg.content == '{"path": "/tmp/test.txt"}'
+        assert msg.metadata == {"tool_name": "read_file"}
+
+
+class TestMessageType:
+    def test_all_types_have_values(self):
+        assert MessageType.SYSTEM.value == "system"
+        assert MessageType.USER.value == "user"
+        assert MessageType.AGENT.value == "agent"
+        assert MessageType.TOOL.value == "tool"

tests/components/__init__.py

@@ -0,0 +1,41 @@
+import os
+import pytest
+from pathlib import Path
+from unittest.mock import AsyncMock, MagicMock, patch
+
+
+os.environ["ANTHROPIC_API_KEY"] = "test-key"
+
+
+FIXTURES_DIR = Path(__file__).parent / "fixtures"
+
+
+@pytest.fixture
+def test_config_path():
+    return FIXTURES_DIR / "test_config.yaml"
+
+
+@pytest.fixture
+def mock_claude_sdk():
+    with patch("agent_chat_cli.core.agent_loop.ClaudeSDKClient") as mock_client:
+        instance = MagicMock()
+        instance.connect = AsyncMock()
+        instance.disconnect = AsyncMock()
+        instance.query = AsyncMock()
+        instance.interrupt = AsyncMock()
+        instance.receive_response = AsyncMock(return_value=AsyncIteratorMock([]))
+        mock_client.return_value = instance
+        yield mock_client
+
+
+class AsyncIteratorMock:
+    def __init__(self, items):
+        self.items = items
+
+    def __aiter__(self):
+        return self
+
+    async def __anext__(self):
+        if not self.items:
+            raise StopAsyncIteration
+        return self.items.pop(0)