fix, feat, doc: massive build system refactorion, bug fixes and apex documentation (#19)

2026-07-12 01:57:40 +03:00
1 parent e8b42c60c2
commit 91f5245823
@@ -0,0 +1,56 @@
+---
+title: Справочник CLI
+description: "Лаунчер apex: перечисление, диспетчеризация, справка и коды возврата."
+weight: 31
+---
+
+Лаунчер — это единый скрипт на Python из стандартной библиотеки, `commons/apex` (в `PATH` после `init.sh`). Всё, что он делает, нацелено на локальный checkout — аргумента узла не существует.
+
+## Формы вызова {#invocation}
+
+| Команда | Поведение |
+|---|---|
+| `apex` или `apex --help` | Перечислить каждое доступное [действие](/apex/glossary#action) с его кратким описанием; выход `0`. |
+| `apex <group>/<action> [args...]` | Выполнить одно действие. |
+| `apex <group>/<action> --help` | Вывести справку argparse для действия, сгенерированную из его `METADATA`; выход `0`. |
+
+Перечисление помечает каждую запись источником [оверлея](/apex/glossary#overlay) — без метки (commons), `(local)`, `(local override)` — и добавляет `[DISABLED: reason]`, когда модуль объявляет `DISABLED`. Перечисление использует статическое сканирование `ast`, поэтому код действий не выполняется.
+
+## Раскладка и разрешение путей {#layout}
+
+При запуске лаунчер определяет, в какой из двух раскладок он находится:
+
+- **Checkout узла** — лаунчер находится в каталоге с именем `commons/`, родитель которого содержит `node.env`. Родитель является корнем репозитория; `proprietaries/actions/` — это дерево оверлея; [идентичность узла](/apex/glossary#node-identity) разрешается перед диспетчеризацией, и любые предупреждения об идентичности логируются первыми.
+- **Автономный commons** — любое другое расположение. Каталог commons является собственным корнем, оверлея нет, а `ctx.node` равен `None` (строки лога несут префикс `global`).
+
+`sys.path` собирается так: каталог commons (делает `engine` импортируемым), затем `commons/vendor/` при наличии, затем `../proprietaries/` в checkout узла (делает проприетарный код `lib/` импортируемым).
+
+## Коды возврата {#exit-codes}
+
+| Код | Источник |
+|---|---|
+| `0` | Действие вернуло `0` или нецелое значение; пути `--help`. |
+| `1` | Неизвестное действие; отключённое действие; необработанное исключение (логируется как `Type: message` с префиксом контекста); нецелый `SystemExit`. |
+| `64` | Ошибка использования при разборе аргументов (`EX_USAGE`). |
+| `65` | Ошибка данных, вызванная библиотеками движка (`EX_DATAERR`) — например, пустой отрендеренный crontab. |
+| `66` | Отсутствующий ввод (`EX_NOINPUT`) — например, отсутствующие поля идентичности или отсутствующий каталог конфигурации ufw. |
+
+Любой другой код — это то, что вернуло или вызвало само действие.
+
+## Формат лога {#log-format}
+
+Весь вывод движка и действий следует одной форме строки:
+
+```text
+[<node>] [<group>/<action>] [LEVEL] message
+```
+
+`LEVEL` — это `INFO`, `WARN`, `ERROR` или `SUCCESS`; строки `ERROR` идут в stderr, всё остальное — в stdout — удобно для cron как для захвата, так и для оповещения.
+
+---
+
+**См. также:**
+
+- [Концепция: Действия и оверлей](/apex/concepts/actions-and-overlay)
+- [Справочник: Действия](/apex/reference/actions)
+- [Справочник: API движка](/apex/reference/engine-api)