# catalib doctor

Префлайт-проверка окружения: одна команда отвечает на вопрос «почему не собирается / не деплоится». Запускайте перед первым деплоем и когда что-то идёт не так.

```bash
catalib doctor [--project DIR] [--serial SERIAL] [--port PORT]
```

## Опции

| Опция             | По умолчанию | Назначение                                    |
| ----------------- | ------------ | --------------------------------------------- |
| `--project`, `-p` | `.`          | каталог проекта плагина                       |
| `--serial`        | —            | серийный номер устройства (если их несколько) |
| `--port`          | `42690`      | локальный порт для временного `adb forward`   |

## Что проверяется

| Проверка       | Когда `ok`                                            | Иначе                               |
| -------------- | ----------------------------------------------------- | ----------------------------------- |
| **Python**     | интерпретатор разработчика ≥ 3.11                     | `fail`                              |
| **catalib**    | всегда (печатает версию)                              | —                                   |
| **Среда**      | всегда (печатает ПК или Android: Termux/Pydroid)      | —                                   |
| **adb**        | `adb` найден в `PATH` *(только на ПК)*                | `warn`                              |
| **Устройство** | есть устройство в состоянии `device` *(только на ПК)* | `warn`                              |
| **Dev server** | отвечает на `ping`                                    | `warn`                              |
| **Проект**     | `catalib.toml` найден и валиден                       | `warn` (нет файла) / `fail` (битый) |

На самом устройстве (Termux/Pydroid) `adb` не нужен: проверки `adb` и «Устройство» не выполняются, а dev server проверяется **напрямую** (`127.0.0.1:<port>`, без `adb forward`). Подробнее — [Разработка на устройстве](/catalib/rukovodstvo/android.md).

`doctor` не имеет побочных эффектов: проброс порта снимается сразу после проверки.

## Статусы и код возврата

* `ok` — всё хорошо.
* `warn` — не критично: нужно только для деплоя (нет `adb`, устройства или dev server) либо каталог не является проектом catalib. Сборке это не мешает.
* `fail` — сборка точно не получится: старый Python или битый `catalib.toml`.

Код возврата `1` — **только** при наличии `fail`; иначе `0`. Поэтому `doctor` можно ставить в CI как мягкий гейт:

```bash
catalib doctor --project . || exit 1
```

## Пример

```bash
$ catalib doctor
[OK  ] Python: 3.11.9 (>= 3.11)
[OK  ] catalib: версия 0.3.3
[OK  ] Среда: ПК (linux)
[OK  ] adb: найден в PATH
[OK  ] Устройство: подключено: emulator-5554
[OK  ] Dev server: доступен на порту 42690
[OK  ] Проект: hello 1.0 — манифест валиден
Окружение готово.
```

На самом устройстве в Termux (без `adb`, dev server напрямую):

```bash
$ catalib doctor
[OK  ] Python: 3.11.9 (>= 3.11)
[OK  ] catalib: версия 0.3.3
[OK  ] Среда: Termux (Android)
[OK  ] Dev server: доступен напрямую на 127.0.0.1:42690
[OK  ] Проект: hello 1.0 — манифест валиден
Окружение готово.
```

Без устройства (разработка без деплоя — это нормально):

```bash
$ catalib doctor
[OK  ] Python: 3.11.9 (>= 3.11)
[OK  ] catalib: версия 0.3.3
[WARN] adb: не найден в PATH
        -> установите Android platform-tools (нужно только для деплоя)
[WARN] Устройство: пропущено — нет adb
[WARN] Dev server: пропущено — нет устройства
[OK  ] Проект: hello 1.0 — манифест валиден
Окружение готово.
```

Битый манифест — единственный «проектный» случай с кодом `1`:

```bash
$ catalib doctor
...
[FAIL] Проект: catalib.toml невалиден: в [plugin] нет обязательных ключей: version
        -> исправьте манифест (формат — в документации)
Есть критические проблемы — устраните их перед сборкой.
```

Подробнее про устройство и dev server — [Подготовка устройства](/catalib/deploi/device-setup.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://raito-kyokai.gitbook.io/catalib/cli/doctor.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.