Макросы: проверенные команды проекта

Макрос — команда терминала с параметрами. Она лежит в репозитории, в файле .koder/macros/<имя>.yaml, и проходит ревью как код. У каждого макроса есть уровень опасности: чтение, изменение или разрушительное действие. Вы запускаете макросы из окна «Макросы», где перед глазами форма параметров и итоговая команда. Агент с модулем «Macros» берёт только макросы, прошедшие ревью. Всё, что опаснее чтения, он выполняет после вашего ответа: запрос приходит во «Входящие» — вкладку того же окна «Макросы».

#Как открыть

Кнопка «Макросы» — в шапке панели терминала, справа от вкладок и «+»; пока проект не открыт, она неактивна. Если агенты ждут вашего ответа, на кнопке появляется счётчик, а окно откроется сразу на вкладке «Входящие».

В окне три раздела: «Макросы», «Входящие» и «История». Строка состояния внизу показывает, какая ветка считается проверенной и задана ли учётная запись агента. Проверенная ветка — основная ветка удалённого репозитория: агенты запускают макросы только в том виде, в каком они лежат в ней (подробнее — ниже, в разделе «Что может агент»). Закрыть окно можно крестиком или клавишей Esc.

Своей клавиши у команды «Макросы» по умолчанию нет, зато её можно найти по имени в окне поиска. Ещё к макросу ведут кнопки на алертах и объектах в Kubernetes.

#Как запустить макрос

1. Откройте «Макросы» и найдите нужный макрос. Искать можно по имени, описанию, тегу, сервису и окружению.
2. Заполните «Параметры». Для полей context, namespace, pod, deployment, service приложение подсказывает имена из кластера. Рядом с полем написано, откуда взялось значение: «по умолчанию», «из алерта», «из Pod».
3. Проверьте блок «Команда»: в нём итоговая команда, и она обновляется при каждой правке. Пока каких-то значений не хватает, «Выполнить» неактивна, а ниже перечислено, каких именно.
4. Нажмите «Выполнить». Что произойдёт дальше, зависит от уровня опасности (таблица ниже).
5. Макрос откроется в новой вкладке терминала с его именем. Там сначала идёт план (уровень, команда, параметры), потом вывод, а в конце — «[макрос завершён]» или код ошибки.

Выполняется ровно та команда, которую вы видели в предпросмотре. Запускает её /bin/sh -c в корне репозитория. Интерактивные программы вроде kubectl exec -it и пейджеров в макросе не работают. Когда истекает timeout (по умолчанию 120 секунд), команда останавливается вместе со всем, что успела запустить.

#Уровни опасности

Модуль сверяет уровень, который указал автор, с текстом команды. Например, kubectl delete, helm uninstall, DROP TABLE, terraform destroy, rm -r — разрушительное действие; kubectl apply, scale, rollout restart, HTTP POST — изменение. Если команда опаснее объявленного уровня, макрос не запустится.

Уровень отдельного запуска может поднять и значение параметра: макрос с --replicas={{n}} относится к изменениям, но при n=0 становится разрушительным. Форма это показывает.

Запуски опаснее чтения требуют подтверждения всегда, даже в режиме «Полный».

#Формат файла

Макросы лежат в папке .koder/macros/ в корне репозитория, в файлах .yaml или .yml. Имя файла и есть имя макроса: строчные латинские буквы, цифры и дефис, не длиннее 63 знаков. Файлы, имя которых начинается с _ или ., макросами не считаются. Файл с ошибкой виден в списке, но не запускается. Что с файлом не так, показывает панель выбранного макроса: пока в ней есть блок «Ошибки в файле», макрос не запустится; блок «Замечания» запуску не мешает.

Типы параметров: string, number (с min и max), choice (с options), duration (30s, 15m, 2h, 1d), time, context, namespace, pod, deployment, service и secret. Каждый параметр обязателен, если не указано required: false; default задаёт значение по умолчанию. Значения подставляются безопасно: параметр не закроет кавычку, не начнёт вторую команду и не раскроет переменную.

Самый короткий макрос:

name: uptime
description: Сколько работает узел
danger: read
command: echo up 3 days

Макрос чтения с параметрами и кнопками на алертах и подах:

name: pod-logs
description: Логи пода за окно времени
danger: read
command: kubectl -n {{namespace}} logs {{pod}} --since={{window}}
params:
  namespace: { type: namespace }
  pod: { type: pod }
  window: { type: duration, default: 15m }
bindings: { alerts: ["KubePod*"], kinds: [pod] }

Открытый с алерта KubePodCrashLooping, этот макрос сам получит namespace и под из меток алерта, а окно — от начала алерта до сейчас с запасом в 5 минут.

Разрушительный макрос с пробным запуском:

name: delete-pod
description: Удалить под
danger: destructive
command: kubectl -n {{namespace}} delete pod {{pod}}
dry_run: kubectl -n {{namespace}} delete pod {{pod}} --dry-run=server
params:
  namespace: { type: namespace }
  pod: { type: pod }
bindings: { kinds: [pod] }

Чтобы его запустить, нужно ввести имя пода. Если в том же файле указать danger: read или change, он не сохранится и не запустится.

В bindings можно указать alerts — имена алертов (* заменяет любые символы), services — сервисы и kinds — pod, deployment, service.

#Агент и макросы

#Как включить

1. Включите модуль «Macros» в «Настройки → Модули». Настраивать его не нужно. Модуль заработает в новых чатах.
2. Если макросы обращаются к кластеру, задайте агенту отдельную учётную запись: в строке внизу окна «Макросы» нажмите «Задать…» и выберите kubeconfig сервисной учётной записи. Под вашими учётными данными агент в кластер не ходит, поэтому без своей записи не запустит ни одного макроса, который туда обращается. Даже запуск, который вы подтвердили, агент выполняет под своей записью.

#Что может агент

• Видеть список макросов и запускать их. Агент видит только макросы проверенной ветки — основной ветки удалённого репозитория (origin/HEAD, а если её нет — origin/main или origin/master). Ваши черновики и файлы, которые ещё не попали в эту ветку, ему недоступны.
• Макрос чтения агент выполняет сам, если проверенная ветка совпадает с удалённой. Если удалённый репозиторий недоступен, даже чтение идёт через «Входящие».
• Изменение и разрушительное действие — только через запрос во «Входящие». Сессия агента ждёт ответа, по умолчанию 30 минут. Отказ окончательный: агенту сказано не пытаться сделать то же самое другим путём.
• Предложить новый макрос. Агент записывает файл в рабочую копию. Агентам макрос станет доступен, когда вы закоммитите его и вольёте в проверенную ветку, а коммит со слиянием попадёт и на ваш компьютер — например, после «Fetch» (см. страницу Git). Проверить это можно в окне «Макросы»: пока файл отличается от проверенной ветки, в панели макроса стоит пометка «Этот файл отличается от проверенной ветки: вы можете его запустить, агенты получат его после слияния.»

Вывод запуска приходит агенту с вырезанными секретами. На его запуски действуют те же ограничения, что и на его команды в терминале.

#Запретить агенту программы в терминале

В файле .koder/macros/_policy.yaml можно перечислить программы, которые агент в этом проекте не будет запускать из своего терминала. Тогда работать с ними он сможет только через макросы:

agent:
  shell_deny: [kubectl, helm, psql, redis-cli]
  approval_timeout_min: 30

approval_timeout_min — сколько минут запрос агента ждёт вашего ответа: от 1 до 1440. Действует версия файла из проверенной ветки. Без этого файла агента в терминале ограничивают только общие правила, и макросы остаются для него удобным, но необязательным путём.

#Входящие

Вкладка «Входящие» делится на «Ждут вашего ответа» и «Недавние». В карточке запроса видно имя макроса, уровень, до какого времени запрос ждёт, кто просит (агент и название чата), итоговую команду, параметры, названия секретов без значений, а у разрушительного макроса — ещё и вывод пробного запуска.

• «Подтвердить» запускает макрос. Для разрушительного сначала введите имя ресурса.
• «Отклонить» — в поле «Причина — необязательно» можно объяснить отказ, затем нажмите «Отклонить запрос».

О новом запросе приложение присылает уведомление с кнопкой «Открыть входящие». В ленте чата карточки нет, ответить с телефона нельзя.

#История

Раздел «История» показывает последние 100 запусков, ваших и агентов. Для каждого видно время, макрос, уровень, итог, длительность, кто запустил и кто подтвердил, откуда запустили (с алерта, с пода) и параметры. Если раскрыть строку, появятся команда и конец вывода. Секреты история хранит только ссылками.

#Черновики и предложения

• «Новый черновик» открывает редактор «Черновик макроса» с заготовкой YAML, ошибки в нём видны сразу. Черновики личные и лежат вне репозитория: запускать их можете вы, агент их не видит. «Предложить в общий набор» записывает файл в .koder/macros/, дальше закоммитьте его и откройте запрос на слияние.
• «Предложения» — команды эксплуатации, которые вы или агенты выполняли три раза и больше с разными значениями; параметры в них уже выделены. Приложение берёт их из истории вашей оболочки и журнала команд агента. Команды со значениями, похожими на пароль или токен, не предлагаются. Кнопки здесь — «Оформить черновиком» и «Не предлагать».
• «Обернуть существующее» — цели Makefile, рецепты just, скрипты из scripts/, bin/, tools/ и package.json, которые пока не вызывает ни один макрос.

#Секреты

В макросе секрет указывают ссылкой: k8s://<namespace>/<secret>/<ключ>, vault://<путь>#<ключ> или env://<ИМЯ>. Само значение читается в момент запуска, учётными данными того, кто запускает, и попадает в команду через переменную окружения. В команде обращайтесь к ней как к $ИМЯ: подставлять секрет через {{…}} нельзя.

command: psql "$DB_URL" -c "select count(*) from orders"
params:
  namespace: { type: namespace, default: production }
  url: { type: secret, ref: "k8s://{{namespace}}/db-credentials/url", env: DB_URL }

В выводе значение секрета и его варианты (base64, URL, hex) заменяются на ***. Секрет короче 4 символов так не скрыть, поэтому такой запуск отменяется. Ссылки env:// агенту недоступны никогда. Настроить агенту секреты из Vault через приложение пока нельзя.

#Кнопки в Kubernetes

В виде Kubernetes кнопки привязанных макросов появляются под каждым алертом в списке и в панели открытого Pod, Deployment или Service. Сама кнопка ничего не запускает: она открывает окно «Макросы» с уже заполненными параметрами.

#Ограничения

• Макросы работают на macOS и Linux. На Windows нужен sh в PATH (например, из Git for Windows); cmd и PowerShell не поддерживаются.
• Если проект открыт на сервере по SSH, макросы читаются, выполняются и хранятся на сервере. Кнопка «Задать…» для учётной записи агента в таком проекте не работает.
• Модуль распознаёт опасность команды по образцам. Собственную утилиту проекта он оценит так, как объявил автор, а вызванный скрипт проверит только на один уровень вглубь. Поэтому ревью макросов обязательно.

#Какие данные куда уходят

Модуль ничего не отправляет на серверы DevMachine. Он обращается только к вашей инфраструктуре: кластерам, Vault, удалённому репозиторию и туда, куда ходит сама команда. История оболочки читается на вашем компьютере и только для предложений. Агент получает список проверенных макросов, итоговые команды и вывод без значений секретов. Всё это входит в запрос к модели и идёт к ней через сервер DevMachine; подробнее — на странице «Данные и приватность».

#Что дальше

• Kubernetes
• Терминал
• Доступ агента к базам, кластерам и очередям
• Модули