s-skillkit 0.3.3__tar.gz → 0.3.4__tar.gz

{s_skillkit-0.3.3 → s_skillkit-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: s-skillkit
-Version: 0.3.3
+Version: 0.3.4
 Summary: Локальное ядро управления навыками: install из git/локальной папки, junction/symlink-линковка в scope агента, .skillignore-фильтр, build manifest, project-манифест. 0 завязок на сеть/auth — stdlib + tomli-w + pathspec + platformdirs.
 Author: Dmitry
 License: MIT
@@ -9,6 +9,7 @@ Requires-Python: >=3.11
 Requires-Dist: pathspec>=0.12.0
 Requires-Dist: platformdirs>=4.0
 Requires-Dist: s-librarykit>=0.7.1
+Requires-Dist: s-telemetrykit>=0.2.0
 Requires-Dist: tomli-w>=1.0
 Provides-Extra: dev
 Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'

{s_skillkit-0.3.3 → s_skillkit-0.3.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "s-skillkit"
-version = "0.3.3"
+version = "0.3.4"
 description = "Локальное ядро управления навыками: install из git/локальной папки, junction/symlink-линковка в scope агента, .skillignore-фильтр, build manifest, project-манифест. 0 завязок на сеть/auth — stdlib + tomli-w + pathspec + platformdirs."
 readme = "README.md"
 license = { text = "MIT" }
@@ -18,11 +18,18 @@ authors = [{ name = "Dmitry" }]
 #   ВИДИМОЕ окно поверх браузера; ``capture_output`` его не подавляет. Своей
 #   второй реализации «как правильно на Windows» в ките быть не должно —
 #   поэтому прежний статус «sibling, ни от чего не зависим» осознанно снят.
+# s-telemetrykit — продуктово-нейтральный SDK учёта запусков. Кит нейтрален
+#   намеренно (он переиспользуем в любом продукте), поэтому skillery-специфику
+#   телеметрии — каталог ~/.skillery, префикс SKILLERY_*, канон _skill_meta.* и
+#   kind="skill_run" — держит адаптер `skillkit.telemetry`: канон меты навыка это
+#   ответственность ИМЕННО этого кита. Зависимость лёгкая: telemetrykit
+#   stdlib-only и своих зависимостей не имеет.
 dependencies = [
     "tomli-w>=1.0",
     "pathspec>=0.12.0",
     "platformdirs>=4.0",
     "s-librarykit>=0.7.1",
+    "s-telemetrykit>=0.2.0",
 ]
 
 [project.optional-dependencies]

{s_skillkit-0.3.3 → s_skillkit-0.3.4}/skillkit/__init__.py

@@ -27,6 +27,12 @@ platformdirs. Отвечает за ФС-механику навыка:
   бинари с GitHub Releases), ``bootstrap.bootstrap_skill`` (ensure_uv → deps →
   бинари → gate → self_check) + ``bootstrap.run_self_check``.
 
+- ``telemetry`` — skillery-адаптер продуктово-нейтрального ``telemetrykit``:
+  ``~/.skillery`` + префикс ``SKILLERY_*`` + канон ``_skill_meta.*``/``SKILL.md``
+  + ``kind="skill_run"``. Импортируется ОТДЕЛЬНО (``from skillkit.telemetry
+  import track_skill``) и НЕ входит в eager-импорты пакета: применение
+  конфигурации — побочный эффект, он не должен случаться от ``import skillkit``.
+
 Хаб-специфика (track_skill_event, install-by-slug bundle, /me/installs) живёт в
 CLI, НЕ здесь.
 """

s_skillkit-0.3.4/skillkit/telemetry.py

@@ -0,0 +1,118 @@
+"""Skillery-адаптер нейтрального ``telemetrykit`` — вся skillery-специфика здесь.
+
+Зачем отдельный модуль. ``s-telemetrykit`` — кит ОБЩЕГО назначения: он должен
+одинаково годиться любому продукту и поэтому не вправе знать ни про
+``~/.skillery``, ни про ``SKILLERY_*``, ни про ``_skill_meta.json``, ни про слово
+«навык». А ``skillkit`` — кит ИМЕННО ЭТОГО продукта: канон стора навыков и его
+меты — его прямая ответственность. Значит и место склейки — здесь.
+
+Подключение в навыке — одна строка, skillery-имя сохранено::
+
+    from skillkit.telemetry import track_skill
+
+    @track_skill()
+    def main() -> int:
+        ...
+
+Импорт модуля САМ применяет конфигурацию (``apply()`` внизу файла): навыку не
+нужно помнить о втором вызове, а забытый вызов означал бы события в чужом
+каталоге. Идемпотентно — повторный импорт ничего не ломает.
+
+**Кто читает outbox — обязан импортировать этот же модуль.** Писатели (навыки)
+и читатель (воркер доставки) должны сойтись в одном каталоге; без общей
+конфигурации воркер будет смотреть в нейтральный ``~/.telemetrykit``, а события
+лежать в ``~/.skillery``.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from telemetrykit import TelemetryConfig, configure, outbox, paths, track_run
+
+#: Каталог-дом семейства инструментов Skillery. Кит НЕ заводит своего: outbox
+#: лежит рядом с конфигом CLI, потому что читать его будет именно CLI-воркер, а
+#: писатели и читатель обязаны сходиться в одной точке без договорённости в
+#: рантайме.
+HOME_DIR_NAME = ".skillery"
+
+#: Префикс env-переменных продукта: ``SKILLERY_HOME``, ``SKILLERY_DISABLED``, …
+ENV_PREFIX = "SKILLERY"
+
+#: Канон меты навыка. ``_skill_meta.json`` пишет установщик (см.
+#: ``skillkit.installer.meta.write_meta``), ``_skill_meta.toml`` — манифест в
+#: исходниках, ``SKILL.md`` — frontmatter, источник правды формы навыка у агентов.
+META_FILES = ("_skill_meta.json", "_skill_meta.toml", "SKILL.md")
+
+#: Ключи идентичности внутри меты. ``skill_id`` — числовой id slug-less навыка
+#: (PK-миграция): если slug не задан, идентичностью каталога становится он.
+META_ID_KEYS = ("slug", "skill_id", "name")
+META_VERSION_KEYS = ("version",)
+
+#: Тип конверта в outbox'е для запусков навыков.
+KIND_SKILL_RUN = "skill_run"
+
+#: Исторические имена env-переменных Skillery. Проверяются ПОСЛЕ префиксных
+#: (``SKILLERY_DISABLED`` сильнее ``SKILLERY_TELEMETRY_DISABLED``), но ломать их
+#: нельзя: они уже разошлись по машинам пользователей и по документации.
+#: ``SKILLERY_CONFIG_DIR`` в списке домов намеренно — если пользователь увёл
+#: конфиг CLI, туда же должен уехать outbox, иначе воркер не найдёт файл.
+LEGACY_ENV_NAMES = {
+    paths.ENV_HOME: ("SKILLERY_CONFIG_DIR",),
+    paths.ENV_DISABLED: ("SKILLERY_TELEMETRY_DISABLED",),
+    paths.ENV_COMPONENT_ID: ("SKILLERY_SKILL_ID",),
+    paths.ENV_COMPONENT_VERSION: ("SKILLERY_SKILL_VERSION",),
+    paths.ENV_OUTBOX_DIR: ("SKILLERY_TELEMETRY_DIR",),
+}
+
+
+def telemetry_config() -> TelemetryConfig:
+    """Конфигурация ``telemetrykit`` под канон Skillery.
+
+    ``home`` задан ЛЕНИВЫМ провайдером, а не готовым путём: ``Path.home()`` на
+    момент импорта модуля и на момент записи события — не обязательно одно и то
+    же (тесты, sandbox, смена профиля), и вычислять его заранее значит зашить
+    первое попавшееся значение.
+    """
+    return TelemetryConfig(
+        home_provider=lambda: Path.home() / HOME_DIR_NAME,
+        env_prefix=ENV_PREFIX,
+        extra_env_names=LEGACY_ENV_NAMES,
+        meta_files=META_FILES,
+        meta_id_keys=META_ID_KEYS,
+        meta_version_keys=META_VERSION_KEYS,
+        default_kind=KIND_SKILL_RUN,
+    )
+
+
+def apply() -> None:
+    """Применить skillery-конфигурацию к ``telemetrykit`` (идемпотентно)."""
+    configure(telemetry_config())
+
+
+#: Skillery-имя канонического ``telemetrykit.track_run``.
+#:
+#: ПРИСВОЕНИЕ, а не функция-обёртка: каскад определения навыка идёт вверх по
+#: кадрам стека и пропускает только кадры самого кита (``telemetrykit.*``).
+#: Обёртка в ``skillkit`` добавила бы кадр, который каскад не пропускает, и
+#: вызывающим оказался бы ЭТОТ файл — идентичность резолвилась бы в мету
+#: skillkit вместо меты навыка.
+track_skill = track_run
+
+__all__ = [
+    "ENV_PREFIX",
+    "HOME_DIR_NAME",
+    "KIND_SKILL_RUN",
+    "LEGACY_ENV_NAMES",
+    "META_FILES",
+    "META_ID_KEYS",
+    "META_VERSION_KEYS",
+    "apply",
+    "outbox",
+    "telemetry_config",
+    "track_run",
+    "track_skill",
+]
+
+# Конфигурация применяется на ИМПОРТЕ: навыку достаточно
+# ``from skillkit.telemetry import track_skill``.
+apply()

s_skillkit-0.3.4/tests/test_telemetry_adapter.py

@@ -0,0 +1,211 @@
+"""Адаптер ``skillkit.telemetry``: skillery-специфика поверх нейтрального кита.
+
+``s-telemetrykit`` продуктово-нейтрален и сам по себе пишет в ``~/.telemetrykit``
+с префиксом ``TELEMETRYKIT_`` и ``kind="run"``. Skillery-канон (``~/.skillery``,
+``SKILLERY_*``, ``_skill_meta.*``, ``kind="skill_run"``) задаётся ИМЕННО здесь —
+и проверяется здесь же, иначе «настроили» и «работает как настроили» разъедутся.
+"""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from collections.abc import Iterator
+from pathlib import Path
+
+import pytest
+import telemetrykit
+from telemetrykit import outbox, paths
+
+from skillkit import telemetry
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+
+
+@pytest.fixture(autouse=True)
+def _skillery_config(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> Iterator[Path]:
+    """Skillery-конфигурация + изолированный дом; после теста — нейтральный сброс."""
+    for name in (
+        "SKILLERY_HOME",
+        "SKILLERY_CONFIG_DIR",
+        "SKILLERY_DISABLED",
+        "SKILLERY_TELEMETRY_DISABLED",
+        "SKILLERY_OUTBOX_PATH",
+        "SKILLERY_OUTBOX_DIR",
+        "SKILLERY_TELEMETRY_DIR",
+        "SKILLERY_OUTBOX_DISABLED",
+        "SKILLERY_SKILL_ID",
+        "SKILLERY_SKILL_VERSION",
+        "SKILLERY_COMPONENT_ID",
+        "SKILLERY_COMPONENT_VERSION",
+    ):
+        monkeypatch.delenv(name, raising=False)
+    telemetry.apply()
+    home = tmp_path / "skillery-home"
+    monkeypatch.setenv("SKILLERY_HOME", str(home))
+    telemetrykit.identity.reset_cache()
+    telemetrykit.detect.reset_cache()
+    yield home
+    telemetrykit.reset_to_defaults()
+
+
+# --- адаптер реально переключает кит -----------------------------------------
+
+
+def test_home_is_skillery_dir(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    """Дом — ``~/.skillery``, а не нейтральный ``~/.telemetrykit``."""
+    monkeypatch.delenv("SKILLERY_HOME", raising=False)
+    monkeypatch.setattr(Path, "home", classmethod(lambda cls: tmp_path))
+    assert paths.home_base() == tmp_path / ".skillery"
+    assert outbox.path() == tmp_path / ".skillery" / "outbox.jsonl"
+
+
+def test_home_is_lazy_not_frozen_at_import(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    """``Path.home()`` берётся в момент записи, а не в момент импорта модуля."""
+    monkeypatch.delenv("SKILLERY_HOME", raising=False)
+    monkeypatch.setattr(Path, "home", classmethod(lambda cls: tmp_path / "later"))
+    assert paths.home_base() == tmp_path / "later" / ".skillery"
+
+
+def test_env_prefix_is_skillery(monkeypatch: pytest.MonkeyPatch) -> None:
+    assert paths.env_names(paths.ENV_DISABLED)[0] == "SKILLERY_DISABLED"
+    monkeypatch.setenv("SKILLERY_OUTBOX_DISABLED", "1")
+    assert outbox.is_disabled() is True
+
+
+def test_legacy_env_names_still_work(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    """Исторические имена переменных ломать нельзя — они уже у пользователей."""
+    assert paths.env_names(paths.ENV_DISABLED) == (
+        "SKILLERY_DISABLED",
+        "SKILLERY_TELEMETRY_DISABLED",
+    )
+    monkeypatch.setenv("SKILLERY_TELEMETRY_DISABLED", "1")
+    assert telemetrykit.telemetry_disabled() is True
+
+    monkeypatch.delenv("SKILLERY_HOME", raising=False)
+    monkeypatch.setenv("SKILLERY_CONFIG_DIR", str(tmp_path / "cfg"))
+    assert paths.home_base() == tmp_path / "cfg"
+
+
+def test_legacy_skill_id_env_override(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("SKILLERY_SKILL_ID", "vk")
+    monkeypatch.setenv("SKILLERY_SKILL_VERSION", "1.2.3")
+    telemetrykit.detect.reset_cache()
+    found = telemetrykit.detect.resolve(caller_file=tmp_path / "x.py", module_name="x")
+    assert (found.component_id, found.component_version) == ("vk", "1.2.3")
+
+
+def test_skill_meta_json_is_read(tmp_path: Path) -> None:
+    """Канон стора: ``_skill_meta.json`` со slug и version."""
+    (tmp_path / "_skill_meta.json").write_text(
+        json.dumps({"slug": "vk", "version": "3.1.4"}), encoding="utf-8"
+    )
+    found = telemetrykit.detect.resolve(caller_file=tmp_path / "cli.py", module_name="absent_pkg")
+    assert (found.component_id, found.component_version, found.source) == (
+        "vk",
+        "3.1.4",
+        "meta_file",
+    )
+
+
+def test_slugless_skill_identified_by_numeric_skill_id(tmp_path: Path) -> None:
+    """PK-миграция: без slug идентичностью становится числовой ``skill_id``."""
+    (tmp_path / "_skill_meta.json").write_text(
+        json.dumps({"slug": None, "skill_id": 42, "version": "0.1.0"}), encoding="utf-8"
+    )
+    found = telemetrykit.detect.resolve(caller_file=tmp_path / "cli.py", module_name="absent_pkg")
+    assert found.component_id == "42"
+
+
+def test_skill_md_frontmatter_is_read(tmp_path: Path) -> None:
+    (tmp_path / "SKILL.md").write_text(
+        "---\nname: max-cli\nversion: 0.4.2\n---\n\n# Навык\n", encoding="utf-8"
+    )
+    found = telemetrykit.detect.resolve(caller_file=tmp_path / "cli.py", module_name="absent_pkg")
+    assert (found.component_id, found.component_version) == ("max-cli", "0.4.2")
+
+
+def test_default_kind_is_skill_run(_skillery_config: Path) -> None:
+    with telemetry.track_skill("vk", "1.0.0"):
+        pass
+    assert [e["kind"] for e in outbox.read_batch(10)] == ["skill_run"]
+
+
+def test_track_skill_is_the_neutral_canon(_skillery_config: Path) -> None:
+    """Алиас — ПРИСВОЕНИЕ: лишний кадр обёртки сбил бы определение навыка."""
+    assert telemetry.track_skill is telemetrykit.track_run
+
+
+# --- навык, использующий адаптер (сквозной прогон в отдельном процессе) ------
+
+
+_SKILL_MODULE = """
+from skillkit.telemetry import track_skill
+
+
+@track_skill()
+def main() -> int:
+    return 0
+
+
+main()
+"""
+
+
+def test_skill_using_adapter_writes_skillery_outbox(tmp_path: Path) -> None:
+    """Сквозь: навык с адаптером пишет в ~/.skillery/outbox.jsonl, kind=skill_run.
+
+    Отдельный процесс, а не in-process вызов: только так проверяется, что
+    конфигурация применяется САМИМ импортом адаптера, без чужой подготовки.
+    """
+    skill_dir = tmp_path / "skills" / "vk"
+    (skill_dir / "vk_skill").mkdir(parents=True)
+    (skill_dir / "_skill_meta.json").write_text(
+        json.dumps({"slug": "vk", "version": "3.1.4"}), encoding="utf-8"
+    )
+    (skill_dir / "vk_skill" / "__init__.py").write_text("", encoding="utf-8")
+    (skill_dir / "vk_skill" / "cli.py").write_text(_SKILL_MODULE, encoding="utf-8")
+    fake_home = tmp_path / "fake-home"
+    fake_home.mkdir()
+
+    env = dict(os.environ)
+    env["PYTHONPATH"] = str(REPO_ROOT) + os.pathsep + str(skill_dir)
+    # Дом НЕ задаём переменной: проверяем именно дефолт адаптера (~/.skillery).
+    for junk in (
+        "SKILLERY_HOME",
+        "SKILLERY_CONFIG_DIR",
+        "SKILLERY_OUTBOX_PATH",
+        "SKILLERY_OUTBOX_DIR",
+        "SKILLERY_TELEMETRY_DIR",
+        "SKILLERY_TELEMETRY_DISABLED",
+        "SKILLERY_DISABLED",
+        "SKILLERY_SKILL_ID",
+        "SKILLERY_SKILL_VERSION",
+    ):
+        env.pop(junk, None)
+    env["USERPROFILE"] = str(fake_home)  # Windows
+    env["HOME"] = str(fake_home)  # POSIX
+
+    res = subprocess.run(
+        [sys.executable, "-c", "import vk_skill.cli"],
+        cwd=str(tmp_path),
+        env=env,
+        capture_output=True,
+        text=True,
+        timeout=180,
+    )
+    assert res.returncode == 0, res.stderr
+    assert res.stdout == "" and res.stderr == "", "кит обязан молчать в консоль"
+
+    outbox_file = fake_home / ".skillery" / "outbox.jsonl"
+    assert outbox_file.is_file(), "события должны лечь в ~/.skillery, а не ~/.telemetrykit"
+    assert not (fake_home / ".telemetrykit").exists()
+
+    envelopes = [json.loads(line) for line in outbox_file.read_text(encoding="utf-8").splitlines()]
+    assert [e["kind"] for e in envelopes] == ["skill_run"]
+    payload = envelopes[0]["payload"]
+    assert (payload["component_id"], payload["component_version"]) == ("vk", "3.1.4")
+    assert payload["status"] == "OK"

{s_skillkit-0.3.3 → s_skillkit-0.3.4}/uv.lock

@@ -481,12 +481,13 @@ wheels = [
 
 [[package]]
 name = "s-skillkit"
-version = "0.3.3"
+version = "0.3.4"
 source = { editable = "." }
 dependencies = [
     { name = "pathspec" },
     { name = "platformdirs" },
     { name = "s-librarykit" },
+    { name = "s-telemetrykit" },
     { name = "tomli-w" },
 ]
 
@@ -503,10 +504,20 @@ requires-dist = [
     { name = "pytest", marker = "extra == 'dev'", specifier = ">=8" },
     { name = "pytest-asyncio", marker = "extra == 'dev'", specifier = ">=0.24" },
     { name = "s-librarykit", specifier = ">=0.7.1" },
+    { name = "s-telemetrykit", specifier = ">=0.2.0" },
     { name = "tomli-w", specifier = ">=1.0" },
 ]
 provides-extras = ["dev"]
 
+[[package]]
+name = "s-telemetrykit"
+version = "0.2.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/ef/bb/b94167ec1bb53ecddf06638085d29504b0894d7c493c793d5d1cd3676484/s_telemetrykit-0.2.0.tar.gz", hash = "sha256:1eecc0cca068d1e07b38fe0f265bb29f09c0887cb2991a88bbb06ec215092062", size = 55381, upload-time = "2026-07-28T13:24:03.369Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/28/86/7d3bb8f0ca17d9470d6ba8c0aa814478b32ea43bc2ea50dee04f8fb72259/s_telemetrykit-0.2.0-py3-none-any.whl", hash = "sha256:447a8446837d4454d7ee253e32a43638b9d64a078405cab3cab30fbe40575f53", size = 45525, upload-time = "2026-07-28T13:24:02.405Z" },
+]
+
 [[package]]
 name = "secretstorage"
 version = "3.5.0"