Metadata-Version: 2.4
Name: elemctl
Version: 0.2.0
Summary: CLI, MCP-сервер и библиотека для Console API v2 платформы 1С:Предприятие.Элемент (1cmycloud)
Author: KeyFire
License-Expression: MIT
Keywords: 1c,element,1cmycloud,console-api,deploy,mcp,xbsl
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: Russian
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: mcp
Requires-Dist: mcp>=1.2; extra == "mcp"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Dynamic: license-file

# elemctl

Утилита командной строки, MCP-сервер и Python-библиотека для управления
приложениями облачной платформы **1С:Предприятие.Элемент** (1cmycloud.com)
через Console API v2.

elemctl закрывает жизненный цикл приложения на платформе без веб-консоли:
создать приложение, собрать архив сборки `.xasm`/`.xlib` из исходников
проекта, загрузить сборку, применить её к приложению и убедиться, что
применение действительно произошло (платформа умеет молча откатывать),
управлять ветками среды разработки, дампами и версией технологии. Один и
тот же движок доступен тремя способами: команда `elemctl` для терминала и
CI, MCP-сервер для AI-агентов (Claude Code и другие MCP-клиенты) и
python-модуль `elemctl` для собственных скриптов.

*elemctl is a CLI tool, MCP server and Python library for the
1C:Enterprise.Element (1cmycloud) Console API: manage applications, upload
builds and deploy with honest apply verification. Docs are in Russian - the
platform's audience - but the CLI output is plain JSON.*

## Возможности

- **Приложения**: список, карточка, создание, запуск, остановка, удаление,
  версия технологии.
- **Проекты и сборки**: загрузка `.xasm`/`.xlib`, список сборок, удаление.
- **Сборка из исходников**: упаковка каталога проекта (`Проект.yaml` + модули)
  в архив сборки с манифестом и git-метаданными, автоинкремент версии.
- **Деплой одной командой**: сборка -> загрузка -> применение -> перезапуск ->
  **проверка фактического применения**.
- **Ветки среды разработки**: список, создание, привязка к приложению, merge.
- **Дампы**: создание и контроль готовности.
- **MCP-сервер**: те же операции как инструменты для AI-агентов
  (Claude Code и другие MCP-клиенты).

### Честная проверка применения

Особенность платформы: если применение проекта падает, платформа **молча
откатывает** приложение на предыдущую сборку - статус `Running` ничего не
говорит об успехе деплоя. `elemctl deploy` поэтому не верит статусу, а
проверяет после деплоя:

1. задачи приложения со статусом `Error`/`Failed`, начатые после старта
   деплоя (старые ошибки из истории не учитываются);
2. фактическую версию проекта приложения (`source.project-version`) - она
   должна совпасть с только что загруженной сборкой;
3. доступность uri приложения контрольным HTTP-запросом (информационно,
   поле `uri-status` в отчёте: 401/403 нормальны для закрытых приложений).

Код возврата `deploy` равен нулю только если сборка действительно применилась.

## Установка

```bash
pipx install elemctl            # или: pip install elemctl
pip install "elemctl[mcp]"      # с MCP-сервером
```

Требуется Python 3.10+. Ядро и CLI не имеют внешних зависимостей
(только стандартная библиотека).

## Настройка

Реквизиты подключения берутся из переменных окружения либо из `.env`
в текущем каталоге (переменные окружения имеют приоритет):

| Переменная | Назначение |
|---|---|
| `ELEMENT_BASE_URL` | базовый URL платформы, например `https://1cmycloud.com` |
| `ELEMENT_CLIENT_ID` | Client-Id для получения токена |
| `ELEMENT_CLIENT_SECRET` | Client-Secret |
| `ELEMENT_APP_ID` | приложение по умолчанию (необязательно) |
| `ELEMENT_PROJECT_ID` | проект по умолчанию (необязательно) |
| `ELEMENT_SPACE_ID` | пространство по умолчанию (необязательно) |

Client-Id/Client-Secret выпускаются в панели управления 1cmycloud
(раздел интеграций Console API). Шаблон файла - [.env.example](.env.example).

## Быстрый старт

```bash
# список приложений
elemctl apps list

# карточка приложения (статус, uri, фактическая версия проекта)
elemctl apps get <app-id>

# полный цикл деплоя из исходников с проверкой применения
elemctl deploy --app-id <app-id> --project-id <project-id> --project-dir acme/crm

# только собрать архив .xasm, никуда не загружая
elemctl build --project-dir acme/crm --output ./dist

# принять изменения ветки среды разработки
elemctl branches merge <branch-id>
```

Вывод всех команд - JSON в stdout; прогресс длительных операций - в stderr.
Ошибки возвращаются JSON-объектом с полем `error` и кодом возврата 1.

Полный список команд: `elemctl --help`, по группам - `elemctl apps --help`,
`elemctl deploy --help` и т.д.

## MCP-сервер

Сервер отдаёт операции платформы как MCP-инструменты (транспорт stdio):

```bash
pip install "elemctl[mcp]"
claude mcp add elemctl -- elemctl mcp
```

Реквизиты подключения сервер берёт из тех же переменных `ELEMENT_*` /
`.env`. Среди инструментов: `list_apps`, `get_app`, `deploy` (с полем `ok`
в ответе), `verify_deploy`, `list_builds`, `merge_branch` и другие.

## Использование как библиотеки

```python
from elemctl import Config, ElementClient
from elemctl.deploy import deploy_from_sources

client = ElementClient(Config.from_env())
apps = client.list_apps()

report = deploy_from_sources(
    client,
    app_id="...",
    project_id="...",
    project_dir="acme/crm",
    log=print,
)
assert report.ok, report.problems
```

## Формат сборки

`.xasm` (приложение) и `.xlib` (библиотека) - это ZIP-архив:

```
Assembly.yaml            # манифест: ProjectKind, Vendor, Name, Version, ...
{vendor}/{name}/...      # файлы проекта: .yaml, .xbsl, ресурсы
```

Каталог проекта должен лежать по схеме `{repo}/{vendor}/{name}/Проект.yaml` -
пути в архиве строятся относительно корня репозитория. Вид проекта
(приложение/библиотека) определяется по полю `ВидПроекта` в `Проект.yaml`.

## Ограничения и статус

- Инструмент **неофициальный** и не аффилирован с фирмой "1С"; Console API
  может меняться без предупреждения.
- Используется только документированный Console API v2 - внутренние API
  консоли платформы инструмент не вызывает и не описывает.
- Создание приложения только по `--project-id` на части конфигураций платформы
  даёт пустой каркас без данных проекта. Надёжный путь - источник-сборка:
  `elemctl apps create <имя> --project-id <id> --latest-build` (MCP-инструмент
  `create_app` подставляет последнюю сборку автоматически), а после создания -
  `elemctl deploy`.
- Приложение с неопубликованными правками в среде разработки платформа
  удалить не даёт (HTTP 400 `FAILED_PRECONDITION`), принудительного удаления
  в Console API нет - только через панель управления; elemctl подскажет это
  в тексте ошибки.
- Пересоздание приложения (delete + create) меняет его URL - внешние
  настройки, завязанные на адрес (OIDC redirect и т.п.), придётся обновлять.
  "Мягкой" очистки данных приложения в Console API нет, она выполняется в
  консоли управления.

## Происхождение и правовые заметки

Код написан с нуля по спецификации внешнего интерфейса платформы - процесс и
гарантии описаны в [ORIGIN.md](ORIGIN.md). Товарные знаки и отсутствие
аффилиации с фирмой "1С" - в файле [NOTICE](NOTICE).

## Лицензия

[MIT](LICENSE)
