Skip to content

Phase 4: Agent context, doctor, CLAUDE.md, README #4

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
padak wants to merge 1 commit into from
Closed

Phase 4: Agent context, doctor, CLAUDE.md, README #4

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
136 changes: 136 additions & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,136 @@
# CLAUDE.md - Project Development Context

This file provides context for AI coding assistants (Claude Code, etc.) working
on the `kbagent` (Keboola Agent CLI) project.

## Quick Start

### Build and install (editable mode)

```bash
uv pip install -e ".[dev]"
```

### Run the CLI

```bash
kbagent --help
kbagent project list
kbagent --json project list
```

### Run tests

```bash
pytest tests/ -v
```

Or with uv:

```bash
uv run pytest tests/ -v
```

## Project Structure

```
src/keboola_agent_cli/
__init__.py # Package init, exports __version__
__main__.py # python -m support
cli.py # Typer root app, global options, subcommand registration
client.py # HTTP client for Keboola Storage API (retry, timeouts)
config_store.py # JSON config persistence (~/.config/keboola-agent-cli/config.json)
errors.py # KeboolaApiError, ConfigError, mask_token()
models.py # Pydantic models: AppConfig, ProjectConfig, TokenVerifyResponse, etc.
output.py # OutputFormatter - dual mode (JSON for agents, Rich for humans)
commands/
__init__.py
project.py # project add/list/remove/edit/status commands
config.py # config list/detail commands
context.py # Agent usage instructions
doctor.py # Health check command
services/
__init__.py
project_service.py # Business logic for project management
config_service.py # Business logic for config listing (Phase 3)
tests/
conftest.py # Shared fixtures (tmp dirs, formatters)
test_cli.py # End-to-end CLI tests via CliRunner
test_client.py # API client tests (mocked HTTP)
test_config_store.py # Config persistence tests
test_errors.py # Error handling and token masking tests
test_models.py # Pydantic model serialization tests
test_output.py # Output formatter tests
test_services.py # Service layer business logic tests
```

## Architecture (3-Layer)

```
CLI commands --> Services (business logic) --> API Client (HTTP)
(Typer, output) (aggregation, resolving) (endpoints, requests)
```

- **API changes** --> only modify `client.py`
- **Business logic changes** --> only modify `services/`
- **UI/output changes** --> only modify `commands/`

## Coding Conventions

### Commands (`commands/`)

- Thin layer: parse arguments with Typer, call service, format output.
- No business logic in commands.
- Use `_get_formatter(ctx)` and `_get_service(ctx)` helpers to pull from Typer context.
- All commands handle `KeboolaApiError` and `ConfigError` with proper exit codes.

### Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | General error |
| 2 | Usage error (bad arguments) |
| 3 | Authentication error (invalid token) |
| 4 | Network error (timeout, unreachable) |
| 5 | Configuration error (bad config file, missing alias) |

### Services (`services/`)

- Accept `ConfigStore` and `client_factory` via dependency injection.
- `client_factory` is `Callable[[str, str], KeboolaClient]` for easy mocking.
- Return plain dicts (not Pydantic models) so the CLI layer can format freely.

### Models (`models.py`)

- All data contracts are Pydantic v2 models.
- `AppConfig` is the top-level config file schema (versioned).
- `ProjectConfig` stores per-project connection details.
- `SuccessResponse` and `ErrorResponse` define the JSON output envelope.

### Output (`output.py`)

- `OutputFormatter` supports dual mode: `--json` for agents, Rich for humans.
- JSON mode writes to stdout via `SuccessResponse` / `ErrorResponse`.
- Human mode uses `rich.console.Console` with optional color disable.

### Error Handling (`errors.py`)

- `KeboolaApiError`: HTTP/API failures with `error_code`, `status_code`, `retryable`.
- `ConfigError`: Configuration file issues.
- `mask_token()`: Always mask tokens in output (`901-...pt0k`).

### Testing

- Use `pytest` with `typer.testing.CliRunner` for CLI tests.
- Mock `ConfigStore` and `ProjectService` via `unittest.mock.patch`.
- Use `tmp_path` fixture for isolated config directories.
- All API calls in tests must be mocked (no real HTTP).

### Dependencies

- **Typer** (with `rich` extra) for CLI framework
- **Rich** for formatted terminal output
- **httpx** for HTTP client
- **Pydantic v2** for data validation and serialization
- **platformdirs** for cross-platform config paths
182 changes: 180 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,181 @@
# Keboola Agent CLI
# kbagent - Keboola Agent CLI

AI-friendly CLI for managing Keboola projects.
AI-friendly command-line interface for managing Keboola projects. Designed for
use by AI coding agents (Claude, Codex, Gemini) and human operators alike.

## Features

- **Multi-project management** -- connect to multiple Keboola stacks and projects
- **AI-optimized output** -- structured JSON output with `--json` flag for easy parsing
- **Configuration browsing** -- list and inspect configurations across projects
- **Health diagnostics** -- built-in `doctor` command to verify setup
- **Self-documenting** -- `context` command provides comprehensive usage instructions for AI agents

## Installation

### With uv (recommended)

```bash
uv tool install .
```

### With pip

```bash
pip install .
```

### Development install

```bash
uv pip install -e ".[dev]"
```

After installation, the `kbagent` command is available globally.

## Quick Start

### 1. Add a project

```bash
kbagent project add \
--alias prod \
--url https://connection.keboola.com \
--token YOUR_STORAGE_API_TOKEN
```

### 2. List connected projects

```bash
kbagent project list
```

### 3. Check connectivity

```bash
kbagent project status
```

### 4. Browse configurations

```bash
kbagent config list --project prod
```

### 5. Run health check

```bash
kbagent doctor
```

## Commands

### Project Management

| Command | Description |
|---------|-------------|
| `kbagent project add --alias NAME --url URL --token TOKEN` | Add a new project connection |
| `kbagent project list` | List all connected projects |
| `kbagent project remove --alias NAME` | Remove a project connection |
| `kbagent project edit --alias NAME [--url URL] [--token TOKEN]` | Edit a project |
| `kbagent project status [--project NAME]` | Test connectivity |

### Configuration Browsing

| Command | Description |
|---------|-------------|
| `kbagent config list [--project NAME] [--component-type TYPE] [--component-id ID]` | List configurations |
| `kbagent config detail --project NAME --component-id ID --config-id ID` | Show configuration details |

### Diagnostics

| Command | Description |
|---------|-------------|
| `kbagent context` | Show AI agent usage instructions |
| `kbagent doctor` | Run health checks |

### Global Flags

| Flag | Short | Description |
|------|-------|-------------|
| `--json` | `-j` | Output structured JSON |
| `--verbose` | `-v` | Enable verbose output |
| `--no-color` | | Disable colored output |

## JSON Output

All commands support `--json` for structured output.

**Success:**

```json
{
"status": "ok",
"data": [ ... ]
}
```

**Error:**

```json
{
"status": "error",
"error": {
"code": "INVALID_TOKEN",
"message": "Token is invalid or expired",
"project": "prod",
"retryable": false
}
}
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | General error |
| 2 | Usage error (bad arguments) |
| 3 | Authentication error (invalid/expired token) |
| 4 | Network error (timeout, unreachable server) |
| 5 | Configuration error (corrupt config, missing alias) |

## Environment Variables

| Variable | Description |
|----------|-------------|
| `KBC_TOKEN` | Default Storage API token (fallback for `--token`) |
| `KBC_STORAGE_API_URL` | Default Keboola stack URL (fallback for `--url`) |

## Architecture

The project follows a 3-layer architecture:

```
CLI commands --> Services --> API Client
(commands/) (services/) (client.py)
```

- **Commands** -- thin Typer layer, parses arguments, formats output
- **Services** -- business logic, aggregation, validation
- **Client** -- HTTP communication with Keboola Storage API (retry, timeouts)

Configuration is stored at `~/.config/keboola-agent-cli/config.json` with
`0600` permissions. Tokens are always masked in output.

## Development

```bash
# Install in development mode
uv pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run a specific test file
pytest tests/test_cli.py -v
```

## License

MIT
Loading