korolevpavel/xbsl-ai-skills/xbsl-deploy

Во всех командах ниже {python} означает python в Windows и python3 в macOS/Linux/WSL. Выбирай команду сразу по текущей ОС, не запускай оба варианта.

Деплой на 1С:Предприятие.Элемент

Справочник по API: references/endpoints.md — читай его если нужны детали по полям запросов/ответов.

Шаг 0: Загрузи переменные окружения

Перед любым обращением к API загрузи env vars. Выполни команду:

set -a && source .env 2>/dev/null; set +a

Если .env не найден — продолжай: нужные переменные могут быть уже заданы в системе.

Обязательные переменные: ELEMENT_BASE_URL, ELEMENT_CLIENT_ID, ELEMENT_CLIENT_SECRET. Если хотя бы одна отсутствует — сообщи пользователю и остановись.

Два вида веток: внешний git vs внутренний git платформы

В 1С:Элемент существуют два независимых механизма веток — не путай их:

Если получаешь 503 на `list-branches` / `get-branch` — проект работает через внешний git. Используй Сценарий I (путь 2: --from-branch) вместо Сценария B.

Шаг 1: Определи намерение

Шаг 2: Получи токен

{python} skills/xbsl-deploy/scripts/api.py --action get-token

Если ошибка — сообщи пользователю что нужно задать env vars: ELEMENT_BASE_URL, ELEMENT_CLIENT_ID, ELEMENT_CLIENT_SECRET.

Сценарий A: Создать новое приложение и задеплоить

По умолчанию: новое приложение привязывается к существующему проекту. Загрузка файла сборки для создания нового проекта — только если пользователь явно попросил («создать проект из сборки», «загрузить сборку» и т.п.) — тогда используй Сценарий H.

A0. Проверь вид проекта (если известна папка проекта)

Если пользователь указал локальную папку проекта — прочитай Проект.yaml и проверь ВидПроекта:

grep "ВидПроекта" <путь>/Проект.yaml

Если найдено ВидПроекта: Библиотека — остановись и сообщи пользователю:

Платформа не может развернуть библиотеку как самостоятельное приложение. Библиотека предназначена для подключения через Импорт в другой проект, а не для деплоя.

Если найдено ВидПроекта: Расширение — перейди к сценарию L. Расширение подключается к существующему приложению и не создаёт отдельное приложение.

A1. Определи проект

Если ELEMENT_PROJECT_ID не задан — выведи список проектов и попроси пользователя выбрать:

{python} skills/xbsl-deploy/scripts/api.py --action list-projects

Показывай только не удалённые ("deleted": false) проекты типа Application.

Сохрани выбранный project-id для следующих шагов.

A2. Определи space-id

Если ELEMENT_SPACE_ID не задан:

{python} skills/xbsl-deploy/scripts/api.py --action list-spaces

• Если пространство одно — используй его id как space-id. Предложи пользователю сохранить в .env: ELEMENT_SPACE_ID=<id>.
• Если пространств несколько — покажи список и спроси пользователя выбрать.
• Если пространств нет — сообщи пользователю, создать пространство нужно через веб-консоль.

A3. Создай приложение

Спроси имя приложения если не указано.

Если проект создан загрузкой сборки в сценарии H, используй id сборки из ответа upload-build как assembly-id. У нового проекта может ещё не быть сборки по умолчанию, поэтому передавай точную версию:

{python} skills/xbsl-deploy/scripts/api.py --action create-app --name <name> --space-id <space-id> --version-id <assembly-id>

Для уже существующего проекта, когда конкретная сборка не выбрана, сохрани прежний вариант:

{python} skills/xbsl-deploy/scripts/api.py --action create-app --name <name> --space-id <space-id> --project-id <project-id>

Сохрани id из ответа как app-id.

A4. Запусти приложение

{python} skills/xbsl-deploy/scripts/api.py --action start-app --app-id <app-id>

A5. Жди Running

Опрашивай каждые 10 сек, до 5 мин:

{python} skills/xbsl-deploy/scripts/api.py --action get-app --app-id <app-id>

Жди пока status == Running. Если status == Error — сообщи error пользователю и остановись. Если 5 мин прошло, а статус не Running — сообщи пользователю текущий статус и предложи проверить логи в консоли Элемента. После создания из сборки дополнительно проверь, что source.project-version-id совпадает с assembly-id из H4. Старый Running для другой сборки не доказывает успех новой публикации.

A6. Верни ссылку

Из последнего ответа get-app возьми поле uri и отправь пользователю.

Сценарий B: Обновить приложение из ветки

B1. Найди приложение

Используй ELEMENT_APP_ID или спроси имя и найди:

{python} skills/xbsl-deploy/scripts/api.py --action list-apps --name <name>

Сохрани id как app-id.

B2. Определи project-id

Используй ELEMENT_PROJECT_ID. Если не задан — извлеки из ответа B1: поле project.id в объекте приложения. Если поле project отсутствует или пустое:

{python} skills/xbsl-deploy/scripts/api.py --action list-projects

Спроси пользователя выбрать проект. Сохрани как project-id.

B3. Создай дамп (страховка перед изменениями)

Дамп нужен как точка отката на случай проблем после деплоя.

{python} skills/xbsl-deploy/scripts/api.py --action create-dump --app-id <app-id>

Сохрани id из ответа как dump-id. Проверь статус сразу (без паузы), затем опрашивай каждые 3 сек (до 60 сек):

{python} skills/xbsl-deploy/scripts/api.py --action get-dump --app-id <app-id> --dump-id <dump-id>

Жди пока status станет Done или Completed. Если дамп завершился ошибкой или не готов за 60 сек — остановись и сообщи пользователю. Не продолжай.

B4. Найди ветку

{python} skills/xbsl-deploy/scripts/api.py --action list-branches --project-id <project-id> --branch-name <branch>

B5. Привяжи ветку к приложению (если нужно)

Если branch.application.id != app-id:

{python} skills/xbsl-deploy/scripts/api.py --action update-branch --branch-id <branch-id> --app-id <app-id>

B6. Перезапусти (подхвати изменения из репозитория)

Сначала останови (если приложение не Stopped):

{python} skills/xbsl-deploy/scripts/api.py --action stop-app --app-id <app-id>

Жди Stopped (опрос каждые 10 сек, до 3 мин). Затем запусти:

{python} skills/xbsl-deploy/scripts/api.py --action start-app --app-id <app-id>

B7. Жди Running → верни URL (как A5-A6)

Сценарий C: Статус приложения

{python} skills/xbsl-deploy/scripts/api.py --action get-app --app-id <app-id>

Выведи пользователю:

• status (Running / Stopped / Error / ...)
• uri — ссылка на приложение
• error — если есть
• current-task — текущая задача если есть
• technology-version

Сценарий D: Запустить приложение

{python} skills/xbsl-deploy/scripts/api.py --action start-app --app-id <app-id>

Жди Running (опрос каждые 10 сек, до 5 мин) → верни статус и ссылку. Если таймаут — сообщи текущий статус и предложи проверить логи в консоли Элемента.

Сценарий E: Остановить приложение

{python} skills/xbsl-deploy/scripts/api.py --action stop-app --app-id <app-id>

Жди Stopped (опрос каждые 10 сек, до 3 мин) → сообщи что остановлено. Если таймаут — сообщи текущий статус.

Сценарий F: Удалить приложение

Обязательно запроси подтверждение у пользователя перед любым удалением. Сообщи имя удаляемого объекта и что действие необратимо. Продолжай только после явного подтверждения («да», «удали», «confirm» и т.п.). Если пользователь не подтвердил — остановись.

Если приложение не Stopped:

{python} skills/xbsl-deploy/scripts/api.py --action stop-app --app-id <app-id>

Жди Stopped (опрос каждые 10 сек, до 3 мин). Затем:

{python} skills/xbsl-deploy/scripts/api.py --action delete-app --app-id <app-id>

Если ветка создавалась скиллом — предложи удалить и её. Удаляй ветку только после отдельного подтверждения:

{python} skills/xbsl-deploy/scripts/api.py --action delete-branch --branch-id <branch-id>

Сценарий G: Принять изменения (merge ветки)

Если branch-id не известен — найди ветку. Для этого нужен project-id (из ELEMENT_PROJECT_ID или спроси пользователя через list-projects):

{python} skills/xbsl-deploy/scripts/api.py --action list-branches --project-id <project-id> --branch-name <branch>

Затем выполни merge:

{python} skills/xbsl-deploy/scripts/api.py --action merge-branch --branch-id <branch-id>

Сообщи результат.

Сценарий H: Создать проект из файла сборки

Проект на Элементе создаётся загрузкой бинарного файла сборки (.zip или артефакт компилятора). Без файла создать проект через API нельзя.

H1. Уточни параметры

Спроси пользователя:

• путь к файлу сборки (--file)
• имя ветки (--branch-name), если нужно зафиксировать (иначе используется ELEMENT_BRANCH)
• хэш коммита и сообщение (--commit-id, --commit-message) — опционально

H2. Определи space-id

Если ELEMENT_SPACE_ID не задан:

{python} skills/xbsl-deploy/scripts/api.py --action list-spaces

Если пространство одно — используй его автоматически.

H3. Выполни fail-closed проверку идентичности

При создании без project-id команда upload-build до бинарной загрузки автоматически:

1. читает точную пару Vendor + Name из корневого Assembly.yaml;
2. получает список проектов через read-only GET /projects;
3. для каждого активного проекта целевого пространства читает его сборки и

сравнивает project-developer + project-name как единую пару;

1. использует строгое регистрозависимое сравнение без fuzzy-сопоставления,

нормализации или попытки вывести пару только из ProjectDto.name: в ProjectDto нет второй координаты identity — поставщика.