elemctl 0.1.0__py3-none-any.whl

elemctl/deploy.py

@@ -0,0 +1,236 @@
+"""Деплой: сборка -> загрузка -> применение -> перезапуск -> проверка.
+
+Главная особенность платформы: при ошибке применения она молча откатывает
+приложение на предыдущую сборку и запускает его – статус Running ничего не
+говорит об успехе. Поэтому отчёт деплоя строится по трём проверкам:
+задачи приложения с ошибками после начала деплоя, сверка фактически
+применённой версии и информационный HTTP-запрос по uri приложения.
+"""
+
+from __future__ import annotations
+
+import tempfile
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+
+from .build import build_assembly
+from .client import extract_assembly_id
+
+# Статусы задач приложения, означающие ошибку (сравнение без учёта регистра).
+FAILED_TASK_STATUSES = {"error", "failed"}
+
+
+@dataclass
+class DeployReport:
+    """Отчёт деплоя.
+
+    applied: True – версия совпала, False – не совпала (похоже на откат),
+    None – фактическую версию определить не удалось. ok – итоговый вердикт:
+    нет проблем и нет доказанного отката.
+    """
+
+    app_id: str = ""
+    uri: str = ""
+    status: str = ""
+    version: str = ""
+    assembly_id: str = ""
+    applied_version: str = ""
+    applied: bool | None = None
+    uri_status: int | None = None
+    problems: list = field(default_factory=list)
+    ok: bool = False
+
+    def to_dict(self):
+        """Представить отчёт словарём с ключами в kebab-case (для JSON-вывода)."""
+        return {
+            "app-id": self.app_id,
+            "uri": self.uri,
+            "status": self.status,
+            "version": self.version,
+            "assembly-id": self.assembly_id,
+            "applied-version": self.applied_version,
+            "applied": self.applied,
+            "uri-status": self.uri_status,
+            "problems": list(self.problems),
+            "ok": self.ok,
+        }
+
+
+def deploy_from_sources(
+    client,
+    app_id,
+    project_id,
+    *,
+    project_dir=None,
+    output_dir=None,
+    version="",
+    branch=None,
+    commit=None,
+    commit_message="",
+    log=None,
+):
+    """Полный цикл деплоя из исходников с проверкой фактического применения.
+
+    log – callback для строк прогресса (например print); библиотека сама
+    ничего не печатает.
+    """
+    log = log or (lambda message: None)
+    started_at = datetime.now(timezone.utc)
+
+    # Версия сборки: явная либо автоинкремент от последней сборки проекта.
+    last_version = ""
+    if not version:
+        latest = client.latest_assembly(project_id)
+        if latest:
+            last_version = str(latest.get("assembly-version") or "")
+
+    result = build_assembly(
+        project_dir,
+        output_dir=output_dir or tempfile.mkdtemp(prefix="elemctl-build-"),
+        version=version,
+        last_build_version=last_version,
+        branch=branch,
+        commit=commit,
+    )
+    log(f"собран архив {result.file} (версия {result.version})")
+
+    response = client.upload_assembly(
+        result.file.read_bytes(),
+        project_id=project_id,
+        branch_name=result.branch or None,
+        commit_id=result.commit or None,
+        commit_message=commit_message or None,
+    )
+    assembly_id = extract_assembly_id(response) or ""
+    log(f"сборка загружена (id: {assembly_id or 'не определён'})")
+
+    if assembly_id:
+        client.apply_build(app_id, image_id=assembly_id)
+    else:
+        # Ответ без id сборки: применяем по проекту и версии.
+        client.apply_build(app_id, project_id=project_id, assembly_version=result.version)
+    log("применение запущено, ждём стабилизации приложения...")
+
+    card = client.ensure_running(app_id, log=log)
+    log("приложение в статусе Running, проверяем фактическое применение...")
+
+    report = _verify(
+        client,
+        app_id,
+        card=card,
+        expected_version=result.version,
+        since=started_at,
+    )
+    report.assembly_id = assembly_id
+    _log_outcome(report, log)
+    return report
+
+
+def deploy_from_platform_branch(client, app_id, branch_id, *, log=None):
+    """Деплой загрузкой изменений из git-ветки платформы (внутренний UI API).
+
+    Проверка применения та же, но без сверки версии (её у загрузки из
+    ветки нет), поэтому applied остаётся None.
+    """
+    log = log or (lambda message: None)
+    started_at = datetime.now(timezone.utc)
+
+    log(f"загружаем изменения из ветки {branch_id} в приложение {app_id}...")
+    client.sync_branch(app_id, branch_id)
+    log("загрузка запущена, ждём стабилизации приложения...")
+
+    card = client.ensure_running(app_id, log=log)
+    log("приложение в статусе Running, проверяем задачи приложения...")
+
+    report = _verify(client, app_id, card=card, expected_version="", since=started_at)
+    _log_outcome(report, log)
+    return report
+
+
+def verify_deploy(client, app_id, *, expected_version="", since=None, log=None):
+    """Самостоятельная проверка применения (без деплоя).
+
+    since – момент, раньше которого ошибки задач не учитываются (старые
+    ошибки из истории не должны портить вердикт).
+    """
+    log = log or (lambda message: None)
+    report = _verify(client, app_id, card=None, expected_version=expected_version, since=since)
+    _log_outcome(report, log)
+    return report
+
+
+# -- внутреннее ---------------------------------------------------------------
+
+
+def _verify(client, app_id, *, card, expected_version, since):
+    problems = []
+
+    # 1. Задачи приложения со статусами Error/Failed после начала деплоя.
+    for task in client.list_app_tasks(app_id):
+        if not isinstance(task, dict):
+            continue
+        status = str(task.get("status") or "")
+        if status.lower() not in FAILED_TASK_STATUSES:
+            continue
+        task_started = _parse_datetime(task.get("start-date"))
+        if since is not None and task_started is not None and task_started < since:
+            continue
+        label = task.get("operation-type") or task.get("id") or "задача"
+        message = task.get("error-message") or "без текста ошибки"
+        problems.append(f"задача {label} завершилась со статусом {status}: {message}")
+
+    # 2. Сверка фактически применённой версии с загруженной.
+    if card is None:
+        card = client.get_app(app_id) or {}
+    source = card.get("source") or {}
+    applied_version = str(source.get("project-version") or "")
+    applied = None
+    if expected_version and applied_version:
+        applied = applied_version == expected_version
+        if not applied:
+            problems.append(
+                f"применённая версия {applied_version} не совпадает с загруженной "
+                f"{expected_version} – похоже, платформа откатила применение"
+            )
+
+    # 3. Информационный GET по uri приложения (401/403 нормальны).
+    uri = str(card.get("uri") or "")
+    uri_status = client.check_uri(uri) if uri else None
+
+    report = DeployReport(
+        app_id=str(app_id),
+        uri=uri,
+        status=str(card.get("status") or ""),
+        version=expected_version or "",
+        applied_version=applied_version,
+        applied=applied,
+        uri_status=uri_status,
+        problems=problems,
+    )
+    report.ok = not problems and applied is not False
+    return report
+
+
+def _log_outcome(report, log):
+    if report.ok:
+        log("проверка пройдена: сборка применена")
+    else:
+        for problem in report.problems:
+            log(f"проблема: {problem}")
+        log("проверка НЕ пройдена")
+
+
+def _parse_datetime(value):
+    """Разобрать дату ISO 8601 (допускается суффикс Z); наивную считать UTC."""
+    if not value or not isinstance(value, str):
+        return None
+    text = value.strip()
+    if text.endswith("Z"):
+        text = text[:-1] + "+00:00"
+    try:
+        parsed = datetime.fromisoformat(text)
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed

elemctl/errors.py

@@ -0,0 +1,54 @@
+"""Исключения elemctl.
+
+Иерархия простая: всё наследуется от ElemctlError, чтобы вызывающая сторона
+могла перехватить любую ошибку инструмента одним except.
+"""
+
+from __future__ import annotations
+
+
+class ElemctlError(Exception):
+    """Базовое исключение elemctl."""
+
+
+class ConfigError(ElemctlError):
+    """Ошибка конфигурации подключения: не хватает параметров или файла."""
+
+
+class BuildError(ElemctlError):
+    """Ошибка локальной сборки архива .xasm/.xlib."""
+
+
+class TransportError(ElemctlError):
+    """Сетевая ошибка: до сервера не удалось достучаться."""
+
+
+class ApiError(ElemctlError):
+    """Ошибка Console API: HTTP-статус и тело ответа сервера.
+
+    Детали сериализуемы в JSON (метод to_dict) – так CLI выводит их
+    в stderr без потери информации.
+    """
+
+    def __init__(self, message, *, status=None, method=None, url=None, body=None, hint=None):
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.method = method
+        self.url = url
+        self.body = body
+        self.hint = hint
+
+    def to_dict(self):
+        """Представить ошибку JSON-сериализуемым словарём."""
+        payload = {"error": self.message}
+        for key, value in (
+            ("status", self.status),
+            ("method", self.method),
+            ("url", self.url),
+            ("body", self.body),
+            ("hint", self.hint),
+        ):
+            if value not in (None, ""):
+                payload[key] = value
+        return payload

elemctl/mcp_server.py

@@ -0,0 +1,210 @@
+"""MCP-сервер elemctl: операции платформы как инструменты для AI-агентов.
+
+Транспорт – stdio; реквизиты подключения – из переменных окружения
+ELEMENT_* или .env-файла в текущем каталоге. Требует optional extra
+"elemctl[mcp]" (пакет mcp>=1.2, используется FastMCP).
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+
+try:
+    from mcp.server.fastmcp import FastMCP
+except ImportError as error:  # pragma: no cover - ветка без extra
+    raise ImportError(
+        'для MCP-сервера нужен extra: pip install "elemctl[mcp]"'
+    ) from error
+
+from .build import build_assembly
+from .client import ElementClient, extract_assembly_id
+from .config import Config
+from .deploy import (
+    deploy_from_platform_branch,
+    deploy_from_sources,
+    verify_deploy as _verify_deploy,
+)
+from .errors import ElemctlError
+
+INSTRUCTIONS = (
+    "Инструменты управления платформой 1С:Предприятие.Элемент (Console API v2). "
+    "Важно: при ошибке применения сборки платформа МОЛЧА откатывает приложение "
+    "на предыдущую сборку и запускает его – статус Running не означает успех "
+    "деплоя. Доверяйте только отчёту инструментов deploy/verify_deploy: поле ok, "
+    "список problems и сверка applied-version с загруженной версией."
+)
+
+
+def create_server(config=None):
+    """Создать MCP-сервер elemctl со всеми инструментами.
+
+    config – готовая конфигурация; без неё она собирается из переменных
+    окружения и .env при первом обращении к платформе.
+    """
+    server = FastMCP("elemctl", instructions=INSTRUCTIONS)
+    state = {"client": None, "config": config}
+
+    def client():
+        if state["client"] is None:
+            cfg = state["config"] or Config.from_env()
+            state["client"] = ElementClient(cfg)
+        return state["client"]
+
+    @server.tool()
+    def list_apps(name: str = "") -> list:
+        """Список приложений платформы; name – необязательный фильтр по имени."""
+        return client().list_apps(name=name)
+
+    @server.tool()
+    def get_app(app_id: str) -> dict:
+        """Карточка приложения: статус, uri, фактическая версия проекта (source.project-version)."""
+        return client().get_app(app_id)
+
+    @server.tool()
+    def find_app(name: str) -> dict:
+        """Найти приложение по точному имени без учёта регистра; вернуть id и признак found."""
+        app = client().find_app(name)
+        if app is None:
+            return {"id": None, "found": False}
+        return {"id": app.get("id"), "found": True, "application": app}
+
+    @server.tool()
+    def create_app(
+        name: str,
+        project_id: str = "",
+        version_id: str = "",
+        space_id: str = "",
+        development_mode: bool = True,
+    ) -> dict:
+        """Создать приложение. При задании только project_id источником берётся последняя сборка проекта (создание из проекта целиком может дать пустой каркас)."""
+        source_version_id = version_id
+        if not source_version_id:
+            if not project_id:
+                raise ElemctlError("нужен project_id или version_id")
+            latest = client().latest_assembly(project_id)
+            if latest is None:
+                raise ElemctlError(
+                    f"у проекта {project_id} нет сборок – загрузите сборку или укажите version_id"
+                )
+            source_version_id = extract_assembly_id(latest)
+        return client().create_app(
+            name,
+            project_version_id=source_version_id,
+            development_mode=development_mode,
+            space_id=space_id or None,
+        )
+
+    @server.tool()
+    def start_app(app_id: str) -> dict:
+        """Запустить приложение."""
+        return client().start_app(app_id) or {"ok": True, "app-id": app_id}
+
+    @server.tool()
+    def stop_app(app_id: str) -> dict:
+        """Остановить приложение."""
+        return client().stop_app(app_id) or {"ok": True, "app-id": app_id}
+
+    @server.tool()
+    def delete_app(app_id: str) -> dict:
+        """Удалить приложение. НЕОБРАТИМО: данные теряются, а пересозданное приложение получит другой URL – внешние настройки (OIDC redirect и т.п.) придётся обновлять."""
+        return client().delete_app(app_id) or {"deleted": True, "app-id": app_id}
+
+    @server.tool()
+    def list_spaces() -> list:
+        """Список пространств."""
+        return client().list_spaces()
+
+    @server.tool()
+    def list_projects() -> list:
+        """Список проектов."""
+        return client().list_projects()
+
+    @server.tool()
+    def list_builds(project_id: str) -> list:
+        """Список сборок проекта."""
+        return client().list_assemblies(project_id)
+
+    # Имя функции отличается от имени инструмента, чтобы не затенять
+    # импортированный build_assembly из модуля build.
+    @server.tool(name="build_assembly")
+    def build_assembly_tool(project_dir: str = "", output_dir: str = "", version: str = "") -> dict:
+        """Локально собрать архив .xasm/.xlib из исходников проекта."""
+        result = build_assembly(
+            project_dir or None, output_dir=output_dir or None, version=version
+        )
+        return {"file": str(result.file), "version": result.version, "kind": result.kind}
+
+    @server.tool()
+    def deploy(
+        app_id: str,
+        project_id: str,
+        project_dir: str = "",
+        version: str = "",
+        branch: str = "",
+        commit_message: str = "",
+    ) -> dict:
+        """Полный цикл деплоя из исходников с честной проверкой применения; итог – поле ok, детали – problems и log."""
+        lines: list[str] = []
+        report = deploy_from_sources(
+            client(),
+            app_id,
+            project_id,
+            project_dir=project_dir or None,
+            version=version,
+            branch=branch or None,
+            commit_message=commit_message,
+            log=lines.append,
+        )
+        payload = report.to_dict()
+        payload["log"] = lines
+        return payload
+
+    @server.tool(name="deploy_from_platform_branch")
+    def deploy_from_platform_branch_tool(app_id: str, branch_id: str) -> dict:
+        """Загрузить изменения из git-ветки платформы в приложение и проверить итог (без сверки версии)."""
+        lines: list[str] = []
+        report = deploy_from_platform_branch(client(), app_id, branch_id, log=lines.append)
+        payload = report.to_dict()
+        payload["log"] = lines
+        return payload
+
+    @server.tool()
+    def apply_build(app_id: str, version_id: str) -> dict:
+        """Применить загруженную сборку (по id) к приложению; после применения проверьте итог инструментом verify_deploy."""
+        response = client().apply_build(app_id, image_id=version_id)
+        return response or {"ok": True, "app-id": app_id, "version-id": version_id}
+
+    @server.tool()
+    def verify_deploy(app_id: str, expected_version: str = "", since_minutes: int = 30) -> dict:
+        """Проверить фактическое применение сборки: задачи с ошибками за последние since_minutes минут, сверка версии, доступность uri."""
+        since = datetime.now(timezone.utc) - timedelta(minutes=since_minutes)
+        report = _verify_deploy(
+            client(), app_id, expected_version=expected_version, since=since
+        )
+        return report.to_dict()
+
+    @server.tool()
+    def list_app_tasks(app_id: str = "") -> list:
+        """Задачи приложений; app_id – необязательный фильтр (выполняется на клиенте)."""
+        return client().list_app_tasks(app_id)
+
+    @server.tool()
+    def list_branches(project_id: str = "", name: str = "") -> list:
+        """Список веток среды разработки; фильтры project_id и name необязательны."""
+        return client().list_branches(project_id=project_id, name=name)
+
+    @server.tool()
+    def merge_branch(branch_id: str) -> dict:
+        """Принять изменения ветки среды разработки (merge)."""
+        return client().merge_branch(branch_id) or {"merged": True, "branch-id": branch_id}
+
+    return server
+
+
+def main():
+    """Запустить MCP-сервер на stdio."""
+    create_server().run()
+
+
+if __name__ == "__main__":
+    main()

elemctl/transport.py

@@ -0,0 +1,53 @@
+"""HTTP-транспорт поверх urllib – единственная точка сетевых вызовов.
+
+Транспорт выделен в отдельный объект, чтобы тесты могли подменить его
+заглушкой и работать без сети.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+
+from .errors import TransportError
+
+
+class HttpResponse:
+    """Ответ HTTP-запроса: статус, заголовки и тело в байтах."""
+
+    def __init__(self, status, headers, body):
+        self.status = int(status)
+        self.headers = dict(headers or {})
+        self.body = body or b""
+
+    def text(self):
+        """Тело ответа строкой (UTF-8, нечитаемые байты заменяются)."""
+        return self.body.decode("utf-8", errors="replace")
+
+    def json(self):
+        """Тело ответа как JSON; для пустого тела – None."""
+        if not self.body:
+            return None
+        return json.loads(self.text())
+
+
+class UrllibTransport:
+    """Транспорт на urllib.request.
+
+    Ответы с кодами не-2xx возвращаются как обычные ответы (решение об
+    ошибке принимает клиент); сетевые сбои превращаются в TransportError.
+    """
+
+    def request(self, method, url, *, headers=None, data=None, timeout=60.0):
+        request = urllib.request.Request(url, data=data, method=method)
+        for name, value in (headers or {}).items():
+            request.add_header(name, value)
+        try:
+            with urllib.request.urlopen(request, timeout=timeout) as response:
+                return HttpResponse(response.status, response.headers, response.read())
+        except urllib.error.HTTPError as error:
+            # HTTPError сам является ответом – возвращаем его тело и код.
+            return HttpResponse(error.code, error.headers, error.read())
+        except OSError as error:
+            raise TransportError(f"сетевая ошибка {method} {url}: {error}") from error

elemctl/versions.py

@@ -0,0 +1,45 @@
+"""Версии сборок: числовое сравнение и автоинкремент.
+
+Версия сборки имеет вид "{база}-{счётчик}", например "1.0-42". Сравнивать
+версии нужно по числовому счётчику после последнего дефиса: "1.0-10" новее
+"1.0-9", хотя лексикографически порядок обратный.
+"""
+
+from __future__ import annotations
+
+
+def version_counter(version):
+    """Числовой счётчик версии – суффикс после последнего дефиса.
+
+    Для версии без дефиса или с нечисловым суффиксом возвращается 0.
+    """
+    text = str(version or "")
+    head, sep, tail = text.rpartition("-")
+    if not sep:
+        return 0
+    try:
+        return int(tail)
+    except ValueError:
+        return 0
+
+
+def next_version(base_version, last_version=None):
+    """Следующая версия сборки: "{база}-{N+1}" от последней, иначе "{база}-1"."""
+    base = (base_version or "1.0").strip()
+    if not last_version:
+        return f"{base}-1"
+    return f"{base}-{version_counter(last_version) + 1}"
+
+
+def pick_latest(assemblies, version_key="assembly-version"):
+    """Выбрать из списка сборок последнюю по числовому счётчику версии."""
+    best = None
+    best_counter = -1
+    for item in assemblies or []:
+        if not isinstance(item, dict):
+            continue
+        counter = version_counter(item.get(version_key))
+        if counter > best_counter:
+            best = item
+            best_counter = counter
+    return best