Справочник Render

dwe render производит файлы, выведенные из объединённой конфигурации DWE. Это единая точка входа для сгенерированных артефактов — ни один из этих файлов не должен править вручную; вместо этого перезапустите соответствующую подкоманду.

Содержание

• Подкоманды
• Общий конвейер
• Вход и выход одним взглядом
• Общая схема manifest
• Локальные оверрайды
• Страницы
• Связанные справочники

Подкоманды

Команда	Вывод	Источник
dwe render env	содержимое .env (stdout или --out <path>)	правила exports.env в workspace/defaults.yml + системные переменные
dwe render ide	IDE-файлы по каждому сервису внутри hub-каталога сервиса	пакеты шаблонов в workspace/templates/ide/<pack>/, управляемые manifest.yml
dwe render ai	agent-доки на уровне hub (AGENTS.md, …)	пакеты шаблонов в workspace/templates/ai/<pack>/, управляемые manifest.yml
dwe render git	shell git-хуки на каждый сервис, в <svc.Dir>/src/.git/hooks/<basename> (режим 0755)	пакеты шаблонов в workspace/templates/git/<pack>/, управляемые manifest.yml
dwe render config	config-файлы по каждому сервису (.env, env.php, …) внутри hub-каталога сервиса, с воспроизведением собранных секретов	пакеты шаблонов в workspace/templates/config/<pack>/, управляемые manifest.yml
dwe render workspace	файлы в корне проекта (.ralphex/, AGENTS.md, .mcp.json, …)	пакеты в workspace/templates/workspace/<pack>/, выбранные через render.workspace или аргументы CLI

Все шесть подкоманд читают одну и ту же объединённую конфигурацию (workspace.yml → workspace/defaults.yml → workspace/local.yml, с объявлениями сервисов из workspace/services/<name>/service.yml). Различаются они тем, что итерируют и куда пишут.

Общий конвейер

flowchart LR
  L1[workspace.yml] --> M
  L2[workspace/defaults.yml] --> M
  L3[workspace/local.yml] --> M
  S["workspace/services/*/service.yml"] --> M
  M[("Объединённая конфигурация")]

  M --> E[render env]
  M --> I[render ide]
  M --> A[render ai]
  M --> G[render git]
  M --> C[render config]
  M --> W[render workspace]

  E --> EOUT[".env / stdout"]
  I --> IOUT["services/{name}/..."]
  A --> AOUT["services/{name}/AGENTS.md<br/>..."]
  G --> GOUT["services/{name}/src/.git/hooks/...<br/>(режим 0755)"]
  C --> COUT["services/{name}/.env<br/>services/{name}/env.php<br/>..."]
  W --> WOUT[".ralphex/...<br/>AGENTS.md<br/>.mcp.json<br/>..."]

Каждая подкоманда:

1. Загружает объединённую конфигурацию. Отсутствующая или невалидная проектная конфигурация — жёсткая ошибка.
2. Выбирает цели:
   • env — один артефакт, без выборки.
   • ide / ai / git — итерируют сервисы, применяют политику выборки, опционально сужают до одного сервиса через аргумент [service]. Без аргумента каждая из них обходит все сервисы и учитывает поле opt-in каждого сервиса (render.<pack>.enabled), поэтому в конвейере должен быть один шаг без аргумента (например, cmd: "render ai"), а не по шагу на сервис; аргумент [service] — для разовых запусков по одному hub’у.
   • config — тоже итерирует сервисы и принимает [service], но выборка у неё другая: только app-сервисы, и разрешается она через config-пак, а не через поле opt-in у сервиса.
   • workspace — использует верхнеуровневый список render.workspace или явные аргументы [pack…]; сервисы не выбирает. Пустой список выводит info-строку и завершает команду успешно.
3. Пишет выходные файлы. Куда они идут — зависит от подкоманды:
   • render ide и render ai пишут внутрь hub-каталога каждого сервиса, привязанного к корню проекта (каталог, содержащий workspace.yml), и применяют границы безопасности путей.
   • render git пишет в <svc.Dir>/src/.git/hooks/ для каждого сервиса, у которого src/.git — реальный каталог; назначение никогда не отслеживается git.
   • render config пишет runtime config-файлы по каждому сервису (.env, env.php, …) внутрь hub-каталога каждого сервиса из workspace/templates/config/<pack>/, воспроизводя собранные секреты; app-сервисы итерируются в порядке DeployOrder.
   • render workspace проверяет все выбранные паки и рендерит их в памяти перед записью в корень проекта; ошибка планирования не меняет файлы. Источники .tmpl — строгие Go-шаблоны, остальные копируются побайтно.
   • render env пишет в stdout по умолчанию или в аргумент --out <path> как задано. Путь --out трактуется относительно текущего рабочего каталога, не корня проекта — указывайте абсолютный путь, если нужно детерминированное расположение независимо от того, откуда запущена команда.

Вход и выход одним взглядом

Аспект	render env	render ide	render ai	render git	render config	render workspace
Итерирует сервисы	нет	да	да	да	да (app-сервисы, DeployOrder)	нет
Читает шаблоны с диска	нет	да (через manifest)	да (через manifest)	да (через manifest)	да (через manifest)	да (через manifest)
Пер-сервисное поле opt-in	—	services.<name>.render.ide.enabled	services.<name>.render.ai.enabled	services.<name>.render.git.enabled	разрешимый config-пакет (только app)	—; верхнеуровневый render.workspace
Политика opt-in по умолчанию	—	true для type: app; false иначе	true для type: app; false иначе	true для type: app; false иначе	только app-сервисы; нет пакета → молча no-op	пустой список → info и exit 0
Политика коллизий при общем dir	—	выигрывает самый глубокий extends (per-variant override)	выигрывает самый поверхностный extends (каноническая идентичность hub)	выигрывает самый глубокий extends (per-variant хуки)	hub родителя extends рендерится один раз (alias пропускается)	одинаковые пути и конфликты файл/каталог между паками отвергаются
Файл manifest	—	manifest.yml объявляет render (+ symlinks)	manifest.yml объявляет render + symlinks	manifest.yml объявляет только render	manifest.yml объявляет только render	manifest.yml объявляет render (+ symlinks)
Поддерживаются симлинки	нет	да (относительные, внутри hub)	да (относительные, внутри hub)	нет — to должен быть basename	нет — отвергаются	да (относительные, внутри корня проекта)
Режим вывода	n/a	как написано	как написано	явный chmod 0755 на каждый прогон	replace (перезапись)	0755 при любом exec-бите источника, иначе 0644; chmod при каждом рендере
Защита путей	n/a	отказ от симлинков в пакете и назначении	отказ от симлинков в пакете и назначении	preflight hub-а + отказ от симлинков в .git/hooks/	отказ от симлинков в пакете и назначении	защищённые пути, отказ от симлинков и каталогов назначения

Общая схема manifest

render ide, render ai, render git, render config и render workspace читают manifest.yml в корне выбранного пакета шаблонов по единой общей схеме:

render:
  - from: <путь внутри пакета>
    to:   <путь назначения относительно dest-root конкретного типа>

symlinks:
  - link: <путь симлинка>
    to:   <существующий путь рендера>

Поверх — ограничения по типу:

Тип	Dest root	Форма to	symlinks
ide	hub-каталог сервиса	любой содержащийся относительный путь	разрешены
ai	hub-каталог сервиса	любой содержащийся относительный путь	разрешены, должны ссылаться на to из render
git	<svc.Dir>/src/.git/hooks/	только basename (без слешей, без ..)	отвергаются — должны быть пусты
config	hub-каталог сервиса	любой содержащийся относительный путь	отвергаются — должны быть пусты
workspace	корень проекта	содержащийся относительный путь вне защищённых путей	разрешены, должны ссылаться на to из render

Для workspace только from, оканчивающиеся на .tmpl, вычисляются как шаблоны; остальные файлы копируются побайтно. render.to и symlinks.link не могут указывать на workspace.yml, workspace/, services/, .dwe/, .git/, .env или их потомков; регистр не учитывается.

Manifest загружается со строгим YAML-декодом (yaml.Decoder.KnownFields(true)); неизвестные поля — жёсткая ошибка. Пустой manifest (без render и symlinks) отвергается. Валидация разделена на shape (чистая, без файловой системы) и sources (resolver-aware проверка существования), чтобы shadow-pack override участвовал в валидации существования источников ровно так же, как их читает рендерер.

Локальные оверрайды

Любой пакет шаблонов workspace/templates/<kind>/<pack>/<rel> может быть пофайлово переопределён соседним shadow-пакетом workspace/templates/<kind>/<pack>.local/<rel>. Resolver, применяемый всеми подкомандами рендера паков, включая workspace:

1. Проверить workspace/templates/<kind>/<pack>.local/<rel>:
   • обычный файл → использовать; рендерер выводит одну info-строку using local override: workspace/templates/<kind>/<pack>.local/<rel>.
   • существует, но это каталог или симлинк → жёсткая ошибка; override не падает молча на канонический пакет (так плохой override обозначит себя сам).
   • отсутствует → провалиться дальше.
2. Проверить workspace/templates/<kind>/<pack>/<rel>:
   • обычный файл → использовать.
   • существует, но это каталог или симлинк → жёсткая ошибка с именем нарушающего пути.
   • отсутствует → обёрнутый os.ErrNotExist.

Каталог <pack>.local/ — это сосед канонического пакета, не его потомок. Он лежит в отслеживаемом workspace/templates/<kind>/ и игнорируется git по паттерну (workspace/templates/*/*.local/ или более широкое правило *.local/ — рекомендуется добавить в проектный .gitignore).

В override-пакете должны быть только переопределяемые файлы — это не полный пакет. manifest.yml читается только из канонического пакета; override не может переписать manifest, а только подменить отдельные from:-источники.

Это зеркалит существующее в проекте соглашение про user-local override:

Каноническое (отслеживаемое)	Локальный сосед (gitignored)
workspace/workspace.yml	workspace/local.yml (описан в справочнике services)
workspace/docker.yml	workspace/docker.local.yml
workspace/templates/<kind>/<pack>/	workspace/templates/<kind>/<pack>.local/

.dwe/ (runtime-каталог) никогда не используется для пользовательских оверрайдов — он зарезервирован под управляемое DWE состояние (deploy/state.yml, deploy/deploy.lock, logs/).

Вход vs выход

Override — это подмена входа, а не перенаправление выхода:

• Файл-override workspace/templates/<kind>/<pack>.local/<rel> игнорируется git по паттерну .local/ и никогда не коммитится.
• Отрендеренный выход всё равно падает на to, объявленный в manifest.

Что это означает на практике:

Тип	Путь вывода	Отслеживается?	Эффект локального override
git	<svc.Dir>/src/.git/hooks/<basename>	никогда (внутри .git/)	override полностью приватен для разработчика
ide / ai	<svc.Dir>/<rel> (обычно отслеживается)	как правило да	перерендер меняет отслеживаемый артефакт; разработчик сам отвечает за то, чтобы не закоммитить эти изменения (git stash, git checkout -- <path> или личный pre-commit guard)
workspace	<project-root>/<rel>	зависит от проектного .gitignore	override может менять отслеживаемые файлы в корне; не коммитьте локальные различия

Для IDE/AI/workspace локальный override, дающий другой выход, — это поток, в который вы намеренно входите; держите его вне коммитов так же, как и любую несвязанную WIP-правку.

Страницы

• render env — генерация .env: системные переменные, правила экспорта, фильтрация через when, форматирование значений
• render ide — IDE-пакеты шаблонов: разрешение пакета, схема manifest, политика «глубочайший выигрывает», пер-сервисный рендер
• render ai — пакеты agent-доков: схема manifest, политика «поверхностнейший выигрывает», записи render + symlinks
• render git — shell git-хуки: manifest-driven рендер в <svc.Dir>/src/.git/hooks/, «глубочайший выигрывает», режим 0755
• render config — config-файлы сервисов: подложка ${...}, воспроизведение ${generated.<name>}, секреты по принципу «собрать, а не выпустить», opt-in разрешение пакетов
• render workspace — паки в корне проекта: явная активация, .tmpl и побайтное копирование, права файлов, защищённые пути, планирование перед записью

Связанные справочники

• workspace.yml / defaults.yml / local.yml — слои объединённой конфигурации и разрешение dot-path (используется render env)
• определения сервисов (workspace/services/*/service.yml) — определения сервисов, блоки ide / ai / git, цепочки extends
• Шаблоны — синтаксис Go-шаблонов и render-контекст; различия встроенных функций паков и Sprout-хелперов info / commands / pipelines
• Запустите dwe render --help (или dwe render <подкоманда> --help), чтобы увидеть актуальный CLI-интерфейс