# Error Handling

## Категории ошибок

### 1. Configuration Errors

Ошибки связанные с отсутствием или невалидностью конфигурации.

| Код | Сообщение | Когда возникает | Решение |
|-----|-----------|-----------------|---------|
| `ERR_NO_GLOBAL_CONFIG` | `No storage configured. Run 'aevs config' first.` | Любая команда кроме `config` без глобального конфига | `aevs config` |
| `ERR_NO_PROJECT_CONFIG` | `No aevs.yaml found. Run 'aevs init' first.` | `push`, `status` без локального конфига | `aevs init` |
| `ERR_CONFIG_EXISTS` | `aevs.yaml already exists. Use --force to overwrite.` | `init` когда конфиг существует | `aevs init --force` |
| `ERR_INVALID_CONFIG` | `Invalid config: {details}` | Конфиг существует, но невалидный | Проверить синтаксис YAML |

### 2. Validation Errors

Ошибки валидации входных данных.

| Код | Сообщение | Когда возникает |
|-----|-----------|-----------------|
| `ERR_INVALID_PROJECT_NAME` | `Invalid project name "{name}". Use only a-z, 0-9, -, _` | Невалидное имя проекта |
| `ERR_EMPTY_FILES` | `No files specified in aevs.yaml` | Пустой список files |
| `ERR_INVALID_PATH` | `Invalid file path: {path}` | Путь содержит `..` или абсолютный |

### 3. File System Errors

Ошибки работы с локальной файловой системой.

| Код | Сообщение | Когда возникает |
|-----|-----------|-----------------|
| `ERR_FILE_NOT_FOUND` | `File not found: {path}` | Файл из config не существует при push |
| `ERR_PERMISSION_DENIED` | `Permission denied: {path}` | Нет прав на чтение/запись |
| `ERR_DIR_CREATE_FAILED` | `Failed to create directory: {path}` | Не удалось создать директорию при pull |

### 4. Storage Errors

Ошибки работы с S3 storage.

| Код | Сообщение | Когда возникает |
|-----|-----------|-----------------|
| `ERR_ACCESS_DENIED` | `Access denied. Check your credentials.` | Невалидные credentials |
| `ERR_BUCKET_NOT_FOUND` | `Bucket "{name}" not found.` | Bucket не существует |
| `ERR_PROJECT_NOT_FOUND` | `Project "{name}" not found in storage.` | Проект не найден при pull |
| `ERR_UPLOAD_FAILED` | `Failed to upload: {details}` | Ошибка при загрузке |
| `ERR_DOWNLOAD_FAILED` | `Failed to download: {details}` | Ошибка при скачивании |
| `ERR_CONNECTION_FAILED` | `Could not connect to storage: {details}` | Сетевая ошибка |

### 5. Archive Errors

Ошибки работы с архивами.

| Код | Сообщение | Когда возникает |
|-----|-----------|-----------------|
| `ERR_ARCHIVE_CREATE` | `Failed to create archive: {details}` | Ошибка создания tar.gz |
| `ERR_ARCHIVE_EXTRACT` | `Failed to extract archive: {details}` | Ошибка распаковки |
| `ERR_ARCHIVE_CORRUPT` | `Archive is corrupted` | Повреждённый архив |

---

## Формат вывода ошибок

### Стандартный формат

```
Error: {сообщение}

{подсказка как исправить, если есть}
```

### Примеры

```
$ aevs push

Error: No aevs.yaml found. Run 'aevs init' first.
```

```
$ aevs pull my-project

Error: Project "my-project" not found in storage.

Available projects:
  - my-app
  - another-project
```

```
$ aevs push

Error: File not found: .env.production

The file is listed in aevs.yaml but doesn't exist.
Remove it from the config or create the file.
```

---

## Exit Codes

| Code | Meaning |
|------|---------|
| `0` | Success |
| `1` | General error |
| `2` | Configuration error |
| `3` | File system error |
| `4` | Storage error |
| `5` | Network error |
| `130` | Interrupted (Ctrl+C) |

### Использование в скриптах

```bash
#!/bin/bash

aevs push
exit_code=$?

case $exit_code in
    0)
        echo "Success"
        ;;
    2)
        echo "Config error - run 'aevs config' or 'aevs init'"
        ;;
    4)
        echo "Storage error - check credentials"
        ;;
    5)
        echo "Network error - check connection"
        ;;
    *)
        echo "Unknown error: $exit_code"
        ;;
esac
```

---

## Логирование

### Уровни логирования

По умолчанию выводятся только ошибки. Для подробного вывода:

```bash
# Verbose mode
$ aevs push -v
$ aevs push --verbose

# Debug mode (максимум деталей)
$ aevs push --debug
```

### Формат verbose вывода

```
$ aevs push -v

[INFO] Reading config from ./aevs.yaml
[INFO] Project: my-app
[INFO] Files to upload: 3
[INFO] Creating archive...
[INFO] Archive size: 479 bytes
[INFO] Uploading to s3://my-bucket/my-app/envs.tar.gz
[INFO] Uploading metadata...
[INFO] Done

Pushed 3 files to "my-app"
```

### Формат debug вывода

```
$ aevs push --debug

[DEBUG] Config path: /Users/me/project/aevs.yaml
[DEBUG] Global config: /Users/me/.config/aevs/config.yaml
[DEBUG] Storage endpoint: https://s3.amazonaws.com
[DEBUG] Bucket: my-bucket
[DEBUG] Reading file: .env.development (156 bytes)
[DEBUG] Reading file: .env.production (234 bytes)
[DEBUG] Reading file: docker/.env (89 bytes)
[DEBUG] Creating tar.gz archive
[DEBUG] S3 PutObject: my-app/envs.tar.gz
[DEBUG] S3 Response: 200 OK, ETag: "abc123"
[DEBUG] S3 PutObject: my-app/metadata.json
[DEBUG] S3 Response: 200 OK
...
```

---

## Graceful Degradation

### При сетевых ошибках

```
$ aevs push

Error: Could not connect to storage.

Retrying in 2 seconds... (1/3)
Retrying in 4 seconds... (2/3)
Retrying in 8 seconds... (3/3)

Error: Connection failed after 3 attempts.
Check your internet connection and try again.
```

### При прерывании (Ctrl+C)

```
$ aevs push
Pushing "my-app"...
  ✓ .env.development
^C
Interrupted. No changes were made to storage.
```

```
$ aevs pull
Pulling "my-app"...
  ✓ .env.development (created)
^C
Interrupted. Partially pulled files:
  - .env.development

Run 'aevs pull' again to complete.
```

---

## Recovery Scenarios

### Corrupted local config

```
$ aevs push

Error: Invalid config: yaml: line 3: did not find expected key

Fix the syntax error in aevs.yaml or run 'aevs init --force' to recreate.
```

### Missing credentials

```
$ aevs push

Error: Access denied. Check your credentials.

Your credentials may have expired or been revoked.
Run 'aevs config' to update them.
```

### Partial push failure

```
$ aevs push

Pushing "my-app"...
  ✓ .env.development
  ✓ .env.production
  ✗ docker/.env (failed)

Error: Upload interrupted.

Some files may have been uploaded. Run 'aevs push' again to retry.
```

При повторном push всё будет загружено заново (идемпотентность).