elemctl 0.1.0__tar.gz

elemctl-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KeyFire
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

elemctl-0.1.0/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: elemctl
+Version: 0.1.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,
+  загрузка изменений из git-ветки.
+- **Дампы**: создание и контроль готовности.
+- **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` | пространство по умолчанию (необязательно) |
+| `ELEMENT_BRANCH_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
+  может меняться без предупреждения.
+- Операция `branches sync` (загрузка изменений из git-ветки в приложение)
+  использует внутренний UI API платформы, а не Console API v2 - контракт
+  наименее стабильный.
+- Создание приложения только по `--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 нет, она выполняется в
+  консоли управления.
+
+## Лицензия
+
+[MIT](LICENSE)

elemctl-0.1.0/README.md

@@ -0,0 +1,173 @@
+# 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,
+  загрузка изменений из git-ветки.
+- **Дампы**: создание и контроль готовности.
+- **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` | пространство по умолчанию (необязательно) |
+| `ELEMENT_BRANCH_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
+  может меняться без предупреждения.
+- Операция `branches sync` (загрузка изменений из git-ветки в приложение)
+  использует внутренний UI API платформы, а не Console API v2 - контракт
+  наименее стабильный.
+- Создание приложения только по `--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 нет, она выполняется в
+  консоли управления.
+
+## Лицензия
+
+[MIT](LICENSE)

elemctl-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+# Метаданные пакета elemctl (раздел 1 спецификации).
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "elemctl"
+version = "0.1.0"
+description = "CLI, MCP-сервер и библиотека для Console API v2 платформы 1С:Предприятие.Элемент (1cmycloud)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "KeyFire" }]
+keywords = ["1c", "element", "1cmycloud", "console-api", "deploy", "mcp", "xbsl"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Natural Language :: Russian",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Build Tools",
+]
+dependencies = []
+
+[project.optional-dependencies]
+mcp = ["mcp>=1.2"]
+dev = ["pytest>=7"]
+
+[project.scripts]
+elemctl = "elemctl.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

elemctl-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

elemctl-0.1.0/src/elemctl/__init__.py

@@ -0,0 +1,25 @@
+"""elemctl – CLI, MCP-сервер и библиотека для Console API v2 платформы
+1С:Предприятие.Элемент (1cmycloud).
+
+Публичный API библиотеки:
+
+    from elemctl import Config, ElementClient
+    from elemctl.deploy import deploy_from_sources
+"""
+
+from .client import ElementClient
+from .config import Config
+from .errors import ApiError, BuildError, ConfigError, ElemctlError, TransportError
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ApiError",
+    "BuildError",
+    "Config",
+    "ConfigError",
+    "ElemctlError",
+    "ElementClient",
+    "TransportError",
+    "__version__",
+]

elemctl-0.1.0/src/elemctl/auth.py

@@ -0,0 +1,142 @@
+"""Получение и кеширование токена Console API.
+
+Токен живёт около часа, поэтому кешируется в файле в системном каталоге
+временных файлов с TTL один час; ключ кеша различает пары base_url +
+client_id. При 401 клиент запрашивает токен принудительно (force=True).
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import tempfile
+import time
+from pathlib import Path
+
+from .errors import ApiError
+
+TOKEN_TTL = 3600.0
+# Запас до истечения: кеш считается годным, если жить осталось больше запаса.
+EXPIRY_MARGIN = 30.0
+
+
+def extract_token(payload):
+    """Достать токен из ответа сервера.
+
+    Токен лежит в первом непустом из полей id_token, token, value,
+    access_token. Особый случай: значение "Not implemented" токеном
+    не является и пропускается.
+    """
+    if not isinstance(payload, dict):
+        return None
+    for key in ("id_token", "token", "value", "access_token"):
+        value = payload.get(key)
+        if not isinstance(value, str):
+            continue
+        value = value.strip()
+        if not value or value == "Not implemented":
+            continue
+        return value
+    return None
+
+
+class TokenManager:
+    """Выдаёт действующий Bearer-токен, пряча кеширование и обновление."""
+
+    def __init__(self, config, transport, cache_dir=None):
+        self._config = config
+        self._transport = transport
+        self._cache_dir = Path(cache_dir) if cache_dir else Path(tempfile.gettempdir())
+        self._token = None
+        self._expires_at = 0.0
+
+    def get_token(self, force=False):
+        """Вернуть токен: из памяти, из файлового кеша или запросив новый."""
+        now = time.time()
+        if not force:
+            if self._token and now + EXPIRY_MARGIN < self._expires_at:
+                return self._token
+            cached = self._read_cache()
+            if cached and now + EXPIRY_MARGIN < cached.get("expires", 0):
+                self._token = cached["token"]
+                self._expires_at = cached["expires"]
+                return self._token
+        token = self._request_token()
+        self._token = token
+        self._expires_at = now + TOKEN_TTL
+        self._write_cache()
+        return token
+
+    # -- внутреннее -----------------------------------------------------
+
+    def _cache_path(self):
+        key = f"{self._config.base_url}|{self._config.client_id}"
+        digest = hashlib.sha256(key.encode("utf-8")).hexdigest()[:16]
+        return self._cache_dir / f"elemctl-token-{digest}.json"
+
+    def _read_cache(self):
+        try:
+            data = json.loads(self._cache_path().read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            return None
+        if isinstance(data, dict) and isinstance(data.get("token"), str):
+            return data
+        return None
+
+    def _write_cache(self):
+        try:
+            self._cache_dir.mkdir(parents=True, exist_ok=True)
+            payload = {"token": self._token, "expires": self._expires_at}
+            self._cache_path().write_text(
+                json.dumps(payload), encoding="utf-8"
+            )
+        except OSError:
+            # Кеш – только ускорение; его недоступность не должна ломать работу.
+            pass
+
+    def _request_token(self):
+        config = self._config.require()
+        credentials = f"{config.client_id}:{config.client_secret}".encode("utf-8")
+        basic = base64.b64encode(credentials).decode("ascii")
+        url = f"{config.base_url}/console/sys/token"
+        response = self._transport.request(
+            "POST",
+            url,
+            headers={
+                "Authorization": f"Basic {basic}",
+                "Content-Type": "application/x-www-form-urlencoded",
+            },
+            data=b"grant_type=client_credentials",
+            timeout=config.timeout,
+        )
+        if not 200 <= response.status < 300:
+            raise ApiError(
+                f"не удалось получить токен: HTTP {response.status}",
+                status=response.status,
+                method="POST",
+                url=url,
+                body=_safe_body(response),
+            )
+        try:
+            payload = response.json()
+        except ValueError:
+            payload = None
+        token = extract_token(payload)
+        if not token:
+            raise ApiError(
+                "токен не найден в ответе сервера (ожидались поля id_token, token, value или access_token)",
+                status=response.status,
+                method="POST",
+                url=url,
+                body=payload if payload is not None else response.text(),
+            )
+        return token
+
+
+def _safe_body(response):
+    """Тело ответа для деталей ошибки: JSON, а если не разбирается – текст."""
+    try:
+        return response.json()
+    except ValueError:
+        return response.text()