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,111 @@
+---
+title: "Действия и оверлей"
+description: "Контракт действия и как узло-локальные проприетарии затеняют действия commons."
+weight: 13
+---
+
+Каждая единица автоматизации в apex — это [действие](/apex/glossary#action): один Python-модуль, который [движок](/apex/glossary#engine) диспетчеризует по имени. [Оверлей](/apex/glossary#overlay) позволяет [проприетариям](/apex/glossary#proprietaries) узла добавлять, переопределять или отключать действия [«commons»](/apex/glossary#commons), не форкая их. Эта страница определяет контракт действия, декларативные дескрипторы аргументов и правила разрешения.
+
+## Контракт действия {#contract}
+
+Действие — это один файл `.py` в дереве `actions/`. Путь к файлу **является** именем действия: `actions/<group>/<action>.py` вызывается как `apex <group>/<action> [args...]`. Нет реестра, который нужно обновлять — размещение файла в дереве публикует действие.
+
+Модуль должен предоставлять две вещи:
+
+- **`METADATA = Meta(...)`** &rarr; краткое описание и дескрипторы аргументов, которые управляют как текстом справки, так и парсингом. Система дескрипторов пришла на смену heredoc-у `action_metadata()` bash-фреймворка «root» commons, предшественника apex.
+- **`run(ctx, args)`** &rarr; точка входа. `ctx` — это построенный движком контекст выполнения; `args` — распарсенное пространство имён `argparse`.
+
+```python {filename="actions/<group>/<action>.py"}
+from engine.descriptor import Meta, Arg, Flag
+
+METADATA = Meta(
+    summary="Однострочное описание, показываемое в перечислении действий",
+    args=[
+        Arg("target", help="Обязательный позиционный аргумент"),
+        Flag("--dry-run", help="Булев флаг"),
+    ],
+)
+
+def run(ctx, args):
+    ...
+    return 0
+```
+
+Возвращаемое значение `run` становится кодом завершения процесса. Нецелочисленный возврат (включая `None`) трактуется как успех (`0`). Необработанное исключение логируется с префиксом контекста и завершается с кодом `1`.
+
+> [!NOTE]
+> `METADATA` технически необязательна — модуль без неё диспетчеризуется с пустым `Meta` и не принимает аргументов — но каждое настоящее действие должно её объявлять, поскольку вывод в перечислении и `--help` генерируется из неё.
+
+## Декларативные аргументы {#arguments}
+
+`Meta.args` — это список дескрипторов. Каждый отображается ровно на одну конструкцию `argparse`:
+
+| Дескриптор | Отображается на | Поведение |
+| --- | --- | --- |
+| `Arg("name")` | позиционный аргумент | Обязателен по умолчанию; `required=False` делает его опциональным позиционным (`nargs="?"`, по умолчанию `None`). |
+| `Opt("--name", default=...)` | опция со значением | Опциональный флаг, принимающий значение, с объявленным значением по умолчанию. |
+| `Flag("--name")` | булев флаг | `store_true`; наличие означает `True`. |
+| `Rest("name")` | остаток | Жадная сквозная передача всех оставшихся argv (`argparse.REMAINDER`). |
+
+Движок строит парсер как `apex <group>/<action>` и парсит оставшиеся argv перед вызовом `run`. `--help` обрабатывается на этапе парсинга. Ошибка использования — неизвестный флаг, отсутствующий позиционный аргумент — печатает usage и завершается с кодом `64` (`EX_USAGE`) вместо стандартного для argparse `2`.
+
+## Перечисление без импорта {#listing}
+
+`apex` без аргументов (или `--help`) перечисляет каждое доступное действие. Перечисление никогда не импортирует модули действий: движок статически сканирует каждый файл модулем `ast` и извлекает только краткое описание `METADATA` и любую константу `DISABLED`. Поэтому код действия не может выполниться — или упасть — во время перечисления; файл, который не удаётся распарсить, перечисляется как `(unparseable)`, а не ломает перечисление.
+
+Каждая запись помечается своим источником оверлея:
+
+- нет метки &rarr; действие commons,
+- `(local)` &rarr; существует только в проприетариях,
+- `(local override)` &rarr; действие проприетариев, затеняющее действие commons,
+- `[DISABLED: reason]` &rarr; действие объявляет `DISABLED`.
+
+## Оверлей {#overlay}
+
+Имена действий разрешаются по двум деревьям, сначала проприетарии:
+
+{{< filetree/container >}}
+{{< filetree/folder name="node repository" state="open" >}}
+  {{< filetree/file name="node.env" >}}
+  {{< filetree/folder name="commons" state="open" >}}
+    {{< filetree/folder name="engine" state="closed" >}}{{< /filetree/folder >}}
+    {{< filetree/folder name="actions" state="open" >}}
+      {{< filetree/file name="<group>/<action>.py" >}}
+    {{< /filetree/folder >}}
+  {{< /filetree/folder >}}
+  {{< filetree/folder name="proprietaries" state="open" >}}
+    {{< filetree/folder name="actions" state="open" >}}
+      {{< filetree/file name="<group>/<action>.py" >}}
+    {{< /filetree/folder >}}
+  {{< /filetree/folder >}}
+{{< /filetree/folder >}}
+{{< /filetree/container >}}
+
+Движок определяет эту схему по своему собственному расположению: когда он запускается из каталога `commons/`, родитель которого содержит `node.env`, родитель является корнем репозитория [узла](/apex/glossary#node), а `proprietaries/actions/` — деревом оверлея. Автономный checkout commons является собственным корнем и не имеет слоя оверлея. Внутри репозитория узла [идентичность узла](/apex/glossary#node-identity) разрешается из FQDN хоста перед диспетчеризацией.
+
+Разрешение для заданного имени проверяет `proprietaries/actions/<name>.py` первым и `commons/actions/<name>.py` вторым; ровно один модуль загружается по пути. Неизвестное имя — это ошибка (код завершения `1`). Оверлей поддерживает четыре приёма:
+
+- **Добавление (Add)** &rarr; файл, существующий только в проприетариях, становится узло-локальным действием, перечисляется как `(local)`.
+- **Переопределение (Override)** &rarr; файл проприетариев по тому же относительному пути полностью затеняет реализацию commons; путь commons записывается в разрешении как `shadowed`.
+- **Обёртывание (Wrap)** &rarr; переопределяющий модуль может делегировать реализации, которую он затеняет, через `ctx.commons.run(args)`, добавляя узло-локальное поведение до или после логики commons вместо её замены.
+- **Отключение (Disable)** &rarr; модуль, присваивающий `DISABLED = "reason"`, отклоняется при диспетчеризации: движок логирует причину и завершается с кодом `1`. Перечисление показывает `[DISABLED: reason]`. Голый `DISABLED = True` также отключает, с обобщённой причиной `disabled`; пустая строка не отключает.
+
+## Коды завершения {#exit-codes}
+
+Действия и движок следуют фиксированному соглашению о кодах завершения:
+
+| Код | Значение | Типичная причина |
+| --- | --- | --- |
+| `0` | успех | `run` вернул `0` или нецелочисленное значение. |
+| `1` | общая ошибка | Неизвестное действие, отключённое действие, необработанное исключение, нецелочисленный `SystemExit`. |
+| `64` | ошибка использования | Аргументы отклонены парсером (`EX_USAGE`). |
+| `65` | ошибка данных | Некорректные входные данные (`EX_DATAERR`), поднимается библиотеками движка. |
+| `66` | отсутствующий ввод | Требуемый ввод отсутствует (`EX_NOINPUT`), поднимается библиотеками движка. |
+
+---
+
+**См. также:**
+
+- [Концепция: Архитектура фреймворка](/apex/concepts/architecture)
+- [Концепция: Контекст выполнения](/apex/concepts/execution-context)
+- [GitHub: apex.ermnvldmr.com](https://github.com/deytenit/apex.ermnvldmr.com)