---
name: dev-cli-development
description: Guide for developing AIDB dev-cli commands and services. Covers Click
  framework patterns, service architecture, command development, decorators, error
  handling, CommandExecutor, CliOutput, BaseService, BaseManager patterns. Use when
  working with src/aidb_cli/, adding CLI commands, creating services, or integrating
  with Docker/test/adapter systems.
---

# Dev-CLI Development Guide

## Purpose

The AIDB dev-cli (`src/aidb_cli/`) is a Click-based command-line interface for AIDB development workflows. This skill guides developers in:

- Adding new CLI commands and command groups
- Creating reusable services following BaseService pattern
- Using custom decorators (@handle_exceptions, @require_repo_context)
- Integrating with Docker, test, and adapter systems
- Following Click framework best practices
- Proper error handling and output formatting

## When to Use This Skill

Auto-activates when:

- Editing files in `src/aidb_cli/`
- Mentioning "dev-cli", "CLI command", "Click", "CliOutput"
- Adding commands, services, or CLI utilities
- Working with test orchestration or Docker integration

## Related Skills

When developing CLI commands, you may also need:

- **testing-strategy** - CLI orchestrates test execution via test coordinator service
- **code-reuse-enforcement** - CLI must use existing constants and avoid magic strings

## Architecture Overview

**For comprehensive architecture details**, see `docs/developer-guide/cli-reference.md` and source code in `src/aidb_cli/`.

### Component Structure

```
src/aidb_cli/
├── commands/      # CLI command definitions (13 modules)
├── services/      # Business logic services (41+ files)
├── managers/      # High-level orchestration (singleton pattern)
├── core/          # Decorators, utilities, constants, param types
└── generators/    # Code generation for test scenarios
```

### Key Patterns

1. **Commands** - Thin wrappers that delegate to services
1. **Services** - Reusable business logic with CommandExecutor
1. **Managers** - Singleton orchestrators for complex workflows
1. **Context Injection** - Dependencies via Click's `ctx.obj`
1. **Unified Error Handling** - `@handle_exceptions` decorator
1. **Dynamic Parameter Types** - Custom types with shell completion

## Quick Start: Adding a Command

### Step 1: Create Command File

Create `src/aidb_cli/commands/mycommand.py`:

```python
"""My new command description."""

import click

from aidb_cli.core.decorators import handle_exceptions
from aidb_logging import get_cli_logger

logger = get_cli_logger(__name__)


@click.group(name="mycommand")
@click.pass_context
def group(ctx: click.Context) -> None:
    """Command group description."""
    pass


@group.command()
@click.option("--option", "-o", help="Option description")
@click.pass_context
@handle_exceptions
def subcommand(ctx: click.Context, option: str) -> None:
    """Subcommand description."""
    # Get dependencies from context
    output = ctx.obj.output
    repo_root = ctx.obj.repo_root
    executor = ctx.obj.command_executor

    # Delegate to service
    from aidb_cli.services.myservice import MyService
    service = MyService(repo_root, executor)
    result = service.do_something(option)

    # User-facing output (via OutputStrategy)
    output.success(f"Done: {result}")
```

### Step 2: Register Command

In `src/aidb_cli/cli.py`:

```python
from aidb_cli.commands import mycommand

# In main CLI setup
cli.add_command(mycommand.group)
```

### Step 3: Test

```bash
./dev-cli mycommand subcommand --option value
```

## Command Development Patterns

### Decorator Order (CRITICAL)

**Always stack decorators in this exact order**:

```python
@group.command()                    # 1. Click command
@click.option("--opt", "-o")        # 2. Options
@click.pass_context                 # 3. Context (BEFORE handle_exceptions)
@handle_exceptions                  # 4. Error handling (LAST)
def command(ctx: click.Context, opt: str) -> None:
    """Implementation."""
```

**Wrong order causes cryptic errors!**

### Custom Parameter Types

Use custom types for validation and autocompletion:

```python
from aidb_cli.core.param_types import TestSuiteParamType

@click.option("--suite", type=TestSuiteParamType(), required=True)
def command(ctx: click.Context, suite: str) -> None:
    """Command with validated suite parameter."""
```

Available: `TestSuiteParamType`, `LanguageParamType`, `DockerProfileParamType`, `TestMarkerParamType`

**For comprehensive Click patterns**, see [click-framework-patterns.md](resources/click-framework-patterns.md):

- Decorator stacking rules explained
- All custom parameter types with examples
- Context management patterns
- Error handling with @handle_exceptions
- Command groups and subcommands
- Advanced Click patterns

## Service Development Patterns

### BaseService Pattern (Recommended)

Most services extend `BaseService` for consistent dependency injection and utilities:

```python
from aidb_cli.managers.base.service import BaseService

class MyService(BaseService):
    def __init__(self, repo_root: Path, command_executor=None, ctx=None):
        super().__init__(repo_root, command_executor, ctx)
        # Inherited: command_executor, resolved_env, logging methods, path utilities

    def do_something(self) -> str:
        self.log_info("Starting operation...")
        return self.command_executor.execute(["cmd"], cwd=self.repo_root).stdout
```

**See [service-patterns.md](resources/service-patterns.md)** for comprehensive BaseService details, advanced patterns, and testing examples.

### Standalone Service Pattern

For simple services without BaseService:

```python
class MyService:
    """Service for my operations."""

    def __init__(
        self,
        repo_root: Path,
        command_executor: CommandExecutor,
        logger: Logger | None = None
    ):
        self.repo_root = repo_root
        self.executor = command_executor
        self.logger = logger or get_cli_logger(__name__)

    def do_something(self, arg: str) -> str:
        """Do something useful."""
        from aidb.common.errors import AidbError

        result = self.executor.execute(["command", arg], cwd=self.repo_root)
        if result.returncode != 0:
            raise AidbError(f"Operation failed: {result.stderr}")
        return result.stdout.strip()
```

**Key principles**:

- Accept dependencies in `__init__` (testable)
- Use `CommandExecutor` for all subprocess calls
- Log with `get_cli_logger(__name__)`
- Raise exceptions for errors

**For comprehensive service patterns**, see [service-patterns.md](resources/service-patterns.md):

- BaseService detailed patterns
- CommandExecutor comprehensive guide
- Service composition and singletons
- Testing services
- Real examples from AIDB codebase

## Error Handling

### @handle_exceptions Decorator

This decorator provides unified error handling:

```python
@handle_exceptions
def command(ctx: click.Context) -> None:
    """Command with automatic error handling."""
    # Just raise errors naturally - decorator handles:
    # - KeyboardInterrupt (cleanup Docker resources)
    # - AidbError (formatted error output)
    # - FileNotFoundError (specific exit code)
    # - PermissionError (specific exit code)
    # - Generic exceptions (traceback in verbose mode)

    if not valid:
        from aidb.common.errors import AidbError
        raise AidbError("Validation failed")
```

### Exit Codes

Use standard exit codes:

```python
from aidb_cli.core.constants import ExitCode

if error:
    CliOutput.error("Operation failed")
    ctx.exit(ExitCode.GENERAL_ERROR)  # 1

if not found:
    ctx.exit(ExitCode.NOT_FOUND)  # 2

if config_error:
    ctx.exit(ExitCode.CONFIG_ERROR)  # 3
```

## Output and Logging

### OutputStrategy for Commands

Commands use `ctx.obj.output` (OutputStrategy) for verbosity-aware user-facing output:

```python
output = ctx.obj.output

output.success("Operation completed")  # Always visible (green)
output.error("Operation failed")       # Always visible (red, stderr)
output.warning("Potential issue")      # Always visible (yellow)
output.plain("Regular message")        # Always visible (no color)
output.section("Title", Icons.ROCKET)  # Always visible (with separator)
output.info("Verbose detail")          # Only with -v flag
output.debug("Debug trace")            # Only with -vvv flag
```

### CliOutput for Services/Managers

Services and managers (without Click context) use the static `CliOutput` utility:

```python
from aidb_cli.core.utils import CliOutput

CliOutput.success("Operation completed successfully")
CliOutput.error("Operation failed")
```

### Logger for Debugging

Use logger for debugging/trace information:

```python
from aidb_logging import get_cli_logger

logger = get_cli_logger(__name__)

logger.debug("Detailed debugging info")
logger.info("General info")
```

**Rule**: Commands → `ctx.obj.output`, Services → `CliOutput`, Debugging → `logger`

## Verbosity Levels

CLI supports three verbosity levels via global flags:

| Flag   | Log Level | Enabled Features                                |
| ------ | --------- | ----------------------------------------------- |
| (none) | INFO      | Standard output only                            |
| `-v`   | DEBUG     | + AIDB_ADAPTER_TRACE=1                          |
| `-vvv` | TRACE     | + AIDB_ADAPTER_TRACE=1 + AIDB_CONSOLE_LOGGING=1 |

**What each level includes:**

- **INFO**: User-facing milestones (session started, breakpoint hit, etc.)
- **DEBUG**: Operation summaries, state transitions, adapter lifecycle
- **TRACE**: Full DAP/LSP JSON payloads, receiver timing, protocol details

**Examples:**

```bash
./dev-cli test run -s unit          # INFO level
./dev-cli -v test run -s unit       # DEBUG + adapter traces
./dev-cli -vvv test run -s unit     # TRACE + protocol payloads
```

Use `-vvv` for maximum observability when debugging DAP/LSP protocol issues.

## Common Patterns

### Import Organization

Follow project standard: stdlib → third-party → AIDB core → CLI → logging. All imports at top unless avoiding circular dependency.

**Avoiding circular imports**: Use `TYPE_CHECKING` for type-only imports:

```python
from typing import TYPE_CHECKING

import click

if TYPE_CHECKING:
    from aidb_cli.cli import Context  # Only imported for type checking
```

See `CLAUDE.md` for full style details.

### Service Instantiation in Commands

```python
@group.command()
@click.pass_context
@handle_exceptions
def command(ctx: click.Context) -> None:
    """Command that uses a service."""
    # Instantiate service with dependencies from context
    from aidb_cli.services.adapter.adapter_build_service import AdapterBuildService

    service = AdapterBuildService(
        repo_root=ctx.obj.repo_root,
        command_executor=ctx.obj.command_executor
    )

    # Call service method
    result = service.build_locally(["python"], verbose=False)

    # Output result
    CliOutput.success(f"Built adapter: {result}")
```

## Common Pitfalls

### 1. Decorator Order

**Wrong**: `@handle_exceptions` before `@click.pass_context`
**Right**: `@click.pass_context` then `@handle_exceptions`

### 2. Using subprocess Directly

**Wrong**: `subprocess.run(["cmd"])`
**Right**: `ctx.obj.command_executor.execute(["cmd"])`

### 3. Mixing Output Types

**Wrong**: `print("Success")` or `logger.info("User message")`
**Right**: `CliOutput.success("Message")` for users, `logger.debug()` for debugging

### 4. Hardcoded Paths

**Wrong**: `Path("/path/to/repo")`
**Right**: `ctx.obj.repo_root / "relative/path"`

## Real Code Examples

### Example 1: Simple Command

From `src/aidb_cli/commands/docker.py`:

```python
@group.command()
@click.option("--profile", "-p", type=DockerProfileParamType(), default=None)
@click.option("--no-cache", is_flag=True, help="Build without cache")
@click.pass_context
@handle_exceptions
def build(ctx: click.Context, profile: str | None, no_cache: bool) -> None:
    """Build Docker images."""
    from aidb_cli.services.docker.docker_build_service import DockerBuildService

    service = DockerBuildService(
        repo_root=ctx.obj.repo_root,
        command_executor=ctx.obj.command_executor
    )

    result = service.build_images(profile=profile, no_cache=no_cache)
    CliOutput.success(f"Build complete: {result}")
```

### Example 2: Service with CommandExecutor

**See real implementation**: `src/aidb_cli/services/docker/docker_build_service.py`

Key pattern - services delegate to CommandExecutor and raise exceptions on failure:

```python
class DockerBuildService:
    def __init__(self, repo_root: Path, command_executor: CommandExecutor):
        self.repo_root = repo_root
        self.executor = command_executor

    def build_images(self, profile: str | None = None) -> int:
        """Build Docker images."""
        from aidb.common.errors import AidbError

        cmd = ["docker-compose", "build"]
        if profile:
            cmd.extend(["--profile", profile])

        result = self.executor.execute(cmd, cwd=self.repo_root)
        if result.returncode != 0:
            raise AidbError(f"Build failed: {result.stderr}")
        return 0
```

## Testing Your Changes

### Run CLI Locally

```bash
./dev-cli mycommand subcommand --option value    # Run command
./dev-cli -v mycommand subcommand                # Verbose mode
./dev-cli --dry-run mycommand subcommand         # Dry run (no execution)
```

### Unit Testing Services

Test services by mocking CommandExecutor:

```python
from unittest.mock import Mock
from pathlib import Path

def test_my_service():
    """Test service logic without executing commands."""
    executor = Mock()
    executor.execute.return_value = Mock(returncode=0, stdout="success")

    service = MyService(Path("/tmp"), executor)
    result = service.do_something("arg")

    assert result == "success"
    executor.execute.assert_called_once_with(["command", "arg"], cwd=Path("/tmp"))
```

**See actual test examples**: `src/tests/aidb_cli/commands/integration/` for command integration tests and `src/tests/aidb_cli/services/` for service unit tests

## Service Discovery Guide

Common tasks and which services to use:

| Task                           | Service                        | Location                                             |
| ------------------------------ | ------------------------------ | ---------------------------------------------------- |
| Build Docker images            | `DockerBuildService`           | `services/docker/docker_build_service.py`            |
| Generate docker-compose.yaml   | `ComposeGeneratorService`      | `services/docker/compose_generator_service.py`       |
| Track Docker image checksums   | `DockerImageChecksumService`   | `services/docker/docker_image_checksum_service.py`   |
| Track framework deps checksums | `FrameworkDepsChecksumService` | `services/docker/framework_deps_checksum_service.py` |
| Check Docker health            | `DockerHealthService`          | `services/docker/docker_health_service.py`           |
| Run tests                      | `TestCoordinatorService`       | `services/test/test_coordinator_service.py`          |
| Build adapters                 | `AdapterBuildService`          | `services/adapter/adapter_build_service.py`          |
| Execute commands               | `CommandExecutor`              | `services/command_executor/__init__.py`              |
| Generate test programs         | `Generator`                    | `generators/core/generator.py`                       |

**Full service list**: See `src/aidb_cli/services/` subdirectories - `docker/` (Docker operations), `test/` (test execution), `adapter/` (adapter building), `docs/` (documentation), `command_executor/` (subprocess execution)

## Resource Files

For deeper dives into specific topics, see:

- **[service-patterns.md](resources/service-patterns.md)** - Comprehensive service architecture patterns, CommandExecutor guide, testing, real examples
- **[click-framework-patterns.md](resources/click-framework-patterns.md)** - Click decorator stacking, custom parameter types, context management, error handling
- **[docker-compose-generation.md](resources/docker-compose-generation.md)** - Template-based docker-compose.yaml generation, Jinja2 templates, languages.yaml configuration, hash-based cache invalidation
- **[checksum-services.md](resources/checksum-services.md)** - ChecksumServiceBase pattern, DockerImageChecksumService, FrameworkDepsChecksumService, container lifecycle tracking, creating custom checksum services

______________________________________________________________________