standkit 0.3.7__py3-none-any.whl

standkit/models.py

@@ -0,0 +1,211 @@
+"""
+Модели данных ядра standkit: описание стенда (Stand) и его состояния (StandStatus).
+
+Поля Stand буквально повторяют схему записи в реестре projects.json (см.
+projects.sample.json в корне репозитория) плюс универсальное поле транспорта
+``transport``, которое определяет, как ядро должно управлять стендом:
+
+- "local" — стенд поднимается локально текущим процессом standkit (subprocess,
+  см. standkit.platform / standkit.lifecycle);
+- "agent" — стенд управляется через удалённый standkit_agent по HTTP
+  (используются agent_url / agent_secret_ref);
+- "ssh" / "winrm" — зарезервировано под будущие транспорты, СХЕМОЙ допускается,
+  логика НЕ реализована (см. TODO в lifecycle.py).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, fields
+from enum import Enum
+from typing import Any, Optional
+
+
+class Transport(str, Enum):
+    """Способ, которым ядро/GUI дотягивается до стенда."""
+
+    LOCAL = "local"
+    AGENT = "agent"
+    # Задел на будущее — схема допускает значения, реализации пока нет.
+    SSH = "ssh"
+    WINRM = "winrm"
+
+
+class ProbeState(str, Enum):
+    """Единое множество состояний для любой health-пробы."""
+
+    OK = "ok"
+    DOWN = "down"
+    UNKNOWN = "unknown"
+    # Проба сознательно не выполнялась (например, глубокая БД-проба выключена флагом).
+    SKIPPED = "skipped"
+
+
+# Поля, обязательные для валидной записи Stand (без них смысла в объекте нет).
+_REQUIRED_FIELDS = ("name", "stand_dir")
+
+
+@dataclass
+class Stand:
+    """
+    Описание одного стенда BPMSoft — один к одному со схемой записи в projects.json.
+
+    ``name`` — ключ записи в реестре (не хранится внутри самой записи в JSON,
+    проставляется registry.py при чтении).
+    """
+
+    name: str
+
+    # --- Транспорт управления стендом ---
+    transport: Transport = Transport.LOCAL
+    agent_url: Optional[str] = None
+    agent_secret_ref: Optional[str] = None
+
+    # --- Процесс стенда ---
+    stand_dir: str = ""
+    stand_dll: str = "BPMSoft.WebHost.dll"
+    dotnet: str = "dotnet"
+    stand_host: str = "127.0.0.1"
+    stand_port: int = 5000
+
+    # --- База данных ---
+    db_type: str = "postgres"
+    db_host: str = ""
+    db_port: int = 0
+    db_name: str = ""
+    db_user: str = ""
+    db_password: str = ""
+    secret_ref_db: Optional[str] = None
+
+    # --- Администратор стенда ---
+    admin_user: str = "Supervisor"
+    secret_ref_admin: Optional[str] = None
+
+    # --- Прочее ---
+    distrib_dir: str = ""
+    description: str = ""
+    customer: str = ""
+
+    # Произвольные дополнительные поля из реестра, которые ядро не знает явно,
+    # но не хочет терять при повторной записи (forward-compatibility).
+    extra: dict = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, name: str, data: dict) -> "Stand":
+        """
+        Строит Stand из словаря записи реестра (как он приходит из JSON).
+
+        Неизвестные поля не теряются — уходят в ``extra``, чтобы round-trip
+        чтение→запись не терял данные, добавленные другими инструментами
+        экосистемы (например, provision_stand из BPMkit).
+        """
+        known = {f.name for f in fields(cls)} - {"name", "extra"}
+        kwargs: dict[str, Any] = {}
+        extra: dict[str, Any] = {}
+        for key, value in data.items():
+            if key == "transport":
+                kwargs["transport"] = _coerce_transport(value)
+            elif key in known:
+                kwargs[key] = value
+            elif key == "name":
+                continue
+            else:
+                extra[key] = value
+        return cls(name=name, extra=extra, **kwargs)
+
+    def to_dict(self) -> dict:
+        """Сериализует запись обратно в словарь для записи в projects.json (без ``name``)."""
+        result: dict[str, Any] = {}
+        for f in fields(self):
+            if f.name in ("name", "extra"):
+                continue
+            value = getattr(self, f.name)
+            if f.name == "transport":
+                value = value.value if isinstance(value, Transport) else value
+            result[f.name] = value
+        result.update(self.extra)
+        return result
+
+    def validate(self) -> list[str]:
+        """
+        Минимальная валидация записи. Возвращает список текстов ошибок
+        (пустой список — запись валидна). Не бросает исключений намеренно —
+        вызывающий код сам решает, насколько строго реагировать.
+        """
+        errors: list[str] = []
+        if not self.name:
+            errors.append("name не может быть пустым")
+        if not self.stand_dir:
+            errors.append("stand_dir не может быть пустым")
+        if self.transport == Transport.AGENT:
+            if not self.agent_url:
+                errors.append("transport=agent требует agent_url")
+        return errors
+
+
+def _coerce_transport(value: Any) -> Transport:
+    if isinstance(value, Transport):
+        return value
+    try:
+        return Transport(str(value))
+    except ValueError:
+        # Неизвестное будущее значение транспорта — не роняем чтение реестра,
+        # оставляем как UNKNOWN-эквивалент через LOCAL с пометкой в extra.
+        return Transport.LOCAL
+
+
+@dataclass
+class StandStatus:
+    """
+    Снимок состояния стенда по всем доступным пробам разом.
+
+    Каждое поле — состояние независимой пробы (см. standkit.health):
+    - process: жив ли процесс стенда (по pid-файлу);
+    - http: отвечает ли web-хост стенда по HTTP;
+    - db: открыт ли TCP-порт БД (не полноценный запрос — TODO);
+    - redis: открыт ли TCP-порт Redis (если используется);
+    - last_deploy: состояние последнего деплоя — вне ядра здоровья, задел на
+      будущее для витрины GUI (TODO: источник данных).
+    """
+
+    name: str
+    process: ProbeState = ProbeState.UNKNOWN
+    http: ProbeState = ProbeState.UNKNOWN
+    db: ProbeState = ProbeState.UNKNOWN
+    redis: ProbeState = ProbeState.UNKNOWN
+    last_deploy: ProbeState = ProbeState.UNKNOWN
+    details: dict = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "StandStatus":
+        """Строит StandStatus из словаря (например, ответа агента по HTTP)."""
+        kwargs: dict[str, Any] = {"name": data.get("name", "")}
+        for key in ("process", "http", "db", "redis", "last_deploy"):
+            if key in data:
+                kwargs[key] = _coerce_probe_state(data[key])
+        kwargs["details"] = dict(data.get("details", {}))
+        return cls(**kwargs)
+
+    def to_dict(self) -> dict:
+        return {
+            "name": self.name,
+            "process": self.process.value,
+            "http": self.http.value,
+            "db": self.db.value,
+            "redis": self.redis.value,
+            "last_deploy": self.last_deploy.value,
+            "details": self.details,
+        }
+
+    @property
+    def is_healthy(self) -> bool:
+        """Грубая сводная оценка: процесс и HTTP в порядке (БД/Redis — опциональны)."""
+        return self.process == ProbeState.OK and self.http in (ProbeState.OK, ProbeState.SKIPPED)
+
+
+def _coerce_probe_state(value: Any) -> ProbeState:
+    if isinstance(value, ProbeState):
+        return value
+    try:
+        return ProbeState(str(value))
+    except ValueError:
+        return ProbeState.UNKNOWN

standkit/platform.py

@@ -0,0 +1,174 @@
+"""
+OS-абстракция запуска процессов: скрытый (headless, без консольного окна)
+процесс на Windows, отсоединённый (setsid) процесс на Linux.
+
+Никакого хардкода путей вида ``C:\\...`` — все пути принимаются и возвращаются
+как ``pathlib.Path``. Модуль не знает ничего про BPMSoft — только про то, как
+корректно поднять/остановить/проверить произвольный процесс кроссплатформенно.
+
+TODO(следующая итерация):
+  - Windows: сейчас используется CREATE_NO_WINDOW через subprocess без
+    полноценной службы (Job Object) — процесс-потомок может пережить
+    неожиданное падение родителя без присмотра. Рассмотреть Job Object API
+    (через ctypes) для гарантированной остановки дерева процессов.
+  - Linux: полноценная демонизация (двойной fork, отвязка от сессии) —
+    сейчас используется упрощённый setsid через start_new_session=True,
+    этого достаточно для большинства случаев, но не эквивалентно классическому
+    double-fork демону.
+  - graceful stop (SIGTERM/таймаут/SIGKILL на Linux; CTRL_BREAK_EVENT на
+    Windows) — сейчас stop() сразу и безусловно завершает процесс.
+"""
+
+from __future__ import annotations
+
+import os
+import signal
+import subprocess
+import sys
+from pathlib import Path
+from typing import Optional, Sequence
+
+
+class ProcessError(Exception):
+    """Ошибки запуска/остановки/проверки процесса."""
+
+
+def spawn_hidden(cmd: Sequence[str], cwd: Path, log_path: Path) -> int:
+    """
+    Запускает процесс в фоне, без видимого консольного окна (Windows) /
+    в новой сессии (Linux), с перенаправлением stdout+stderr в log_path.
+
+    Возвращает pid запущенного процесса. Не блокирует вызывающий поток.
+    """
+    cwd = Path(cwd)
+    log_path = Path(log_path)
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Открываем лог в режиме дозаписи — предыдущие запуски не теряются молча.
+    log_file = open(log_path, "ab", buffering=0)
+
+    popen_kwargs: dict = {
+        "cwd": str(cwd),
+        "stdout": log_file,
+        "stderr": subprocess.STDOUT,
+        "stdin": subprocess.DEVNULL,
+    }
+
+    if sys.platform == "win32":
+        # Скрытое окно + отдельная группа процессов, чтобы CTRL-C консоли
+        # родителя (если он в консоли) не убивал дочерний процесс стенда.
+        creationflags = 0
+        creationflags |= getattr(subprocess, "CREATE_NO_WINDOW", 0x08000000)
+        creationflags |= getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0x00000200)
+        popen_kwargs["creationflags"] = creationflags
+    else:
+        # Новая сессия — процесс переживает завершение управляющего терминала
+        # и получает свою группу для последующего управляемого stop().
+        popen_kwargs["start_new_session"] = True
+
+    try:
+        proc = subprocess.Popen(list(cmd), **popen_kwargs)
+    except OSError as exc:
+        raise ProcessError(f"Не удалось запустить процесс {cmd!r}: {exc}") from exc
+    finally:
+        log_file.close()
+
+    return proc.pid
+
+
+def is_alive(pid: int) -> bool:
+    """Проверяет, жив ли процесс с данным pid (кроссплатформенно)."""
+    if pid <= 0:
+        return False
+    if sys.platform == "win32":
+        return _is_alive_windows(pid)
+    return _is_alive_posix(pid)
+
+
+def stop(pid: int, *, timeout: float = 10.0) -> bool:
+    """
+    Останавливает процесс по pid.
+
+    TODO: сейчас — безусловное завершение (SIGTERM/taskkill), без ожидания
+    graceful shutdown и без эскалации до SIGKILL по таймауту. Для веб-хоста
+    BPMSoft это может быть недостаточно аккуратно (незавершённые транзакции) —
+    в следующей итерации добавить: сигнал → ожидание ``timeout`` секунд с
+    опросом is_alive() → принудительное убийство, если процесс не завершился.
+
+    Возвращает True, если процесс на момент вызова считался остановленным
+    (уже не был жив, либо остановлен успешно).
+    """
+    if not is_alive(pid):
+        return True
+
+    if sys.platform == "win32":
+        return _stop_windows(pid)
+    return _stop_posix(pid)
+
+
+# --- Windows-специфика ---
+
+def _is_alive_windows(pid: int) -> bool:
+    try:
+        import ctypes
+
+        PROCESS_QUERY_LIMITED_INFORMATION = 0x1000
+        handle = ctypes.windll.kernel32.OpenProcess(  # type: ignore[attr-defined]
+            PROCESS_QUERY_LIMITED_INFORMATION, False, pid
+        )
+        if not handle:
+            return False
+        try:
+            exit_code = ctypes.c_ulong()
+            STILL_ACTIVE = 259
+            ok = ctypes.windll.kernel32.GetExitCodeProcess(  # type: ignore[attr-defined]
+                handle, ctypes.byref(exit_code)
+            )
+            return bool(ok) and exit_code.value == STILL_ACTIVE
+        finally:
+            ctypes.windll.kernel32.CloseHandle(handle)  # type: ignore[attr-defined]
+    except Exception:
+        # Фолбэк на tasklist, если ctypes-путь недоступен по какой-то причине.
+        try:
+            out = subprocess.check_output(
+                ["tasklist", "/FI", f"PID eq {pid}"], text=True, stderr=subprocess.DEVNULL
+            )
+            return str(pid) in out
+        except Exception:
+            return False
+
+
+def _stop_windows(pid: int) -> bool:
+    try:
+        subprocess.run(
+            ["taskkill", "/PID", str(pid), "/T", "/F"],
+            check=False,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+    except OSError as exc:
+        raise ProcessError(f"Не удалось остановить процесс {pid}: {exc}") from exc
+    return not is_alive(pid)
+
+
+# --- Linux/POSIX-специфика ---
+
+def _is_alive_posix(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+        return True
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        # Процесс существует, но принадлежит другому пользователю — жив.
+        return True
+
+
+def _stop_posix(pid: int) -> bool:
+    try:
+        os.kill(pid, signal.SIGTERM)
+    except ProcessLookupError:
+        return True
+    except OSError as exc:
+        raise ProcessError(f"Не удалось остановить процесс {pid}: {exc}") from exc
+    return not is_alive(pid)

standkit/registry.py

@@ -0,0 +1,223 @@
+"""
+Реестр стендов — чтение/запись projects.json.
+
+Формат совпадает со схемой BPMkit (см. projects.sample.json в корне репозитория):
+верхний уровень ``{"default": <имя>, "stands": {<имя>: {...}}}``. Файл читается как
+``utf-8-sig`` (терпим к BOM, который оставляют некоторые редакторы на Windows) и
+пишется БЕЗ BOM, чтобы не плодить дифф на ровном месте между инструментами.
+
+Важно: этот модуль НЕ занимается провижинингом стендов (созданием каталогов,
+БД, установкой дистрибутива) — только чтением/записью записей реестра для уже
+существующих стендов. Провижининг — зона ответственности платного продукта
+(BPMkit: provision_stand и т.п.).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Iterable, Optional
+
+from standkit.models import Stand
+
+_DEFAULT_SCHEMA_VERSION = 1
+
+# Имя папки с общими файлами экосистемы BPMkit (реестр стендов, конфиг GUI и
+# т.п.) — единая точка правды между standkit и BPMkit MCP.
+_BPMKIT_DIR_NAME = "BPMkit"
+_REGISTRY_FILE_NAME = "projects.json"
+_ENV_REGISTRY_VAR = "BPMSOFT_PROJECTS_FILE"
+
+
+class RegistryError(Exception):
+    """Ошибки чтения/записи/валидации реестра стендов."""
+
+
+def bpmkit_config_dir() -> Path:
+    """
+    Каталог общих файлов экосистемы BPMkit (реестр стендов, конфиг GUI и т.п.)
+    — та же папка, которую резолвит клиентский MCP BPMkit:
+
+    - Windows: ``%APPDATA%\\BPMkit``;
+    - POSIX: ``$XDG_CONFIG_HOME/BPMkit`` либо, если переменная не задана,
+      ``~/.config/BPMkit``.
+
+    Функция ничего не создаёт на диске — только считает путь.
+    """
+    if sys.platform == "win32":
+        appdata = os.environ.get("APPDATA")
+        base = Path(appdata) if appdata else Path.home() / "AppData" / "Roaming"
+        return base / _BPMKIT_DIR_NAME
+
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    base = Path(xdg) if xdg else Path.home() / ".config"
+    return base / _BPMKIT_DIR_NAME
+
+
+def default_registry_path() -> Path:
+    """
+    Резолвит путь к реестру стендов ТОЙ ЖЕ цепочкой, что использует BPMkit MCP,
+    чтобы standkit и кит смотрели в один и тот же ``projects.json`` без
+    дополнительной настройки:
+
+    1. env ``BPMSOFT_PROJECTS_FILE`` — если задана и путь существует, он в
+       приоритете;
+    2. канонический путь кита: ``%APPDATA%\\BPMkit\\projects.json`` (Windows)
+       или ``$XDG_CONFIG_HOME/BPMkit/projects.json`` / ``~/.config/BPMkit/
+       projects.json`` (POSIX);
+    3. фолбэк ``./projects.json`` в текущей рабочей директории — для
+       standalone-запуска standkit без установленного кита.
+
+    Возвращает первый СУЩЕСТВУЮЩИЙ файл из цепочки; если ни один не
+    существует — возвращает канонический путь п.2 (куда реестр следовало бы
+    положить), чтобы вызывающий код мог использовать его как путь для
+    первого создания реестра.
+    """
+    env_value = os.environ.get(_ENV_REGISTRY_VAR)
+    if env_value:
+        env_path = Path(env_value)
+        if env_path.exists():
+            return env_path
+
+    canonical = bpmkit_config_dir() / _REGISTRY_FILE_NAME
+    if canonical.exists():
+        return canonical
+
+    fallback = Path.cwd() / _REGISTRY_FILE_NAME
+    if fallback.exists():
+        return fallback
+
+    return canonical
+
+
+class Registry:
+    """
+    Реестр стендов поверх JSON-файла.
+
+    Пример:
+        reg = Registry.load("projects.json")
+        stand = reg.get("my-stand")
+        reg.add_existing(Stand(name="another", stand_dir="/opt/bpmsoft/another"))
+        reg.save()
+    """
+
+    def __init__(self, path: Path, default: str = "", stands: Optional[dict[str, Stand]] = None,
+                 extra_top: Optional[dict] = None):
+        self.path = Path(path)
+        self.default = default
+        self._stands: dict[str, Stand] = stands or {}
+        # Прочие top-level ключи исходного файла (у реестра BPMkit: _comment,
+        # scaffold_root, shared_docs_root, default_locked и т.п.) — сохраняются,
+        # чтобы save() не затирал их и не портил общий с китом projects.json.
+        self._extra_top: dict = extra_top or {}
+
+    # --- чтение/запись ---
+
+    @classmethod
+    def load(cls, path: str | Path) -> "Registry":
+        """
+        Читает реестр из файла. Если файла нет — возвращает ПУСТОЙ реестр
+        (это нормальная ситуация при первом запуске; см. projects.sample.json
+        как образец для ручного заполнения).
+        """
+        p = Path(path)
+        if not p.exists():
+            return cls(path=p, default="", stands={})
+
+        raw = p.read_text(encoding="utf-8-sig")
+        try:
+            data = json.loads(raw) if raw.strip() else {}
+        except json.JSONDecodeError as exc:
+            raise RegistryError(f"Некорректный JSON реестра {p}: {exc}") from exc
+
+        default = data.get("default", "")
+        # Реестр BPMkit (и кита) хранит стенды под ключом "projects"; поддерживаем
+        # и "stands" для обратной совместимости со старым форматом standkit.
+        stands_raw = data.get("projects")
+        if stands_raw is None:
+            stands_raw = data.get("stands", {})
+        extra_top = {k: v for k, v in data.items() if k not in ("projects", "stands", "default")}
+        stands = {name: Stand.from_dict(name, rec) for name, rec in stands_raw.items()}
+        return cls(path=p, default=default, stands=stands, extra_top=extra_top)
+
+    def save(self) -> None:
+        """Пишет реестр обратно в файл БЕЗ BOM, с отступом для читаемости диффов."""
+        # Сохраняем В ФОРМАТЕ BPMkit (ключ "projects") и переносим прочие top-level
+        # ключи исходного файла — чтобы не разрушить общий с китом реестр.
+        payload: dict = dict(self._extra_top)
+        payload["default"] = self.default
+        payload["projects"] = {name: stand.to_dict() for name, stand in self._stands.items()}
+        text = json.dumps(payload, ensure_ascii=False, indent=2)
+        self.path.write_text(text, encoding="utf-8")
+
+    # --- доступ к записям ---
+
+    def list(self) -> list[Stand]:
+        """Список всех стендов реестра (без гарантии порядка вставки не даётся, но сохраняется)."""
+        return list(self._stands.values())
+
+    def names(self) -> list[str]:
+        return list(self._stands.keys())
+
+    def get(self, name: str) -> Stand:
+        """Возвращает Stand по имени. Бросает RegistryError, если такого нет."""
+        try:
+            return self._stands[name]
+        except KeyError as exc:
+            raise RegistryError(f"Стенд '{name}' не найден в реестре {self.path}") from exc
+
+    def get_default(self) -> Stand:
+        """Возвращает стенд по умолчанию (поле ``default`` реестра)."""
+        if not self.default:
+            raise RegistryError("В реестре не задан стенд по умолчанию (default)")
+        return self.get(self.default)
+
+    def __contains__(self, name: str) -> bool:
+        return name in self._stands
+
+    def __len__(self) -> int:
+        return len(self._stands)
+
+    # --- изменение реестра ---
+
+    def add_existing(self, stand: Stand, *, make_default: bool = False) -> None:
+        """
+        Привязывает УЖЕ СУЩЕСТВУЮЩИЙ стенд к реестру (не провижининг!).
+
+        Ожидается, что каталог стенда/БД/дистрибутив уже существуют — этот
+        метод только регистрирует их в реестре standkit, чтобы ядро могло
+        ими управлять (start/stop/health). Валидирует запись перед добавлением.
+        """
+        errors = stand.validate()
+        if errors:
+            raise RegistryError(
+                f"Невозможно добавить стенд '{stand.name}': {'; '.join(errors)}"
+            )
+        if stand.name in self._stands:
+            raise RegistryError(f"Стенд '{stand.name}' уже есть в реестре")
+        self._stands[stand.name] = stand
+        if make_default or not self.default:
+            self.default = stand.name
+
+    def remove(self, name: str) -> None:
+        """Удаляет запись стенда из реестра (сам стенд физически не трогает)."""
+        if name not in self._stands:
+            raise RegistryError(f"Стенд '{name}' не найден в реестре")
+        del self._stands[name]
+        if self.default == name:
+            self.default = next(iter(self._stands), "")
+
+    def update(self, stand: Stand) -> None:
+        """Обновляет существующую запись стенда (по имени)."""
+        if stand.name not in self._stands:
+            raise RegistryError(f"Стенд '{stand.name}' не найден в реестре, обновлять нечего")
+        errors = stand.validate()
+        if errors:
+            raise RegistryError(f"Невозможно обновить стенд '{stand.name}': {'; '.join(errors)}")
+        self._stands[stand.name] = stand
+
+    def filter_by_transport(self, transport: str) -> Iterable[Stand]:
+        """Вспомогательный фильтр — например, для GUI, чтобы отдельно собрать agent-стенды."""
+        return (s for s in self._stands.values() if s.transport.value == transport)