s-skillkit 0.1.9__tar.gz → 0.2.2__tar.gz

s_skillkit-0.2.2/AGENTS.md

@@ -0,0 +1,45 @@
+# AGENTS.md — skillkit
+
+> Контекст для AI-ассистентов (Claude Code, ChatGPT, Cursor и т.п.), работающих
+> над этим проектом.
+
+## Что это
+
+(заполнить one-line)
+
+## Atlas
+
+Проект зарегистрирован в Atlas-БД (Atlas). Карточка:
+
+```sh
+atlas projects get skillkit
+```
+
+Любые изменения метаданных (приоритет, статус, теги) — через atlas CLI:
+
+- `atlas projects update skillkit --priority P0` — поменять приоритет
+- `atlas add-tags skillkit -t domain:<slug>` — добавить тег
+- `atlas projects move skillkit --to-type <type>` — конвертировать тип
+
+## Тип / Статус (на момент создания)
+
+- type=`kit`, status=`experiment`, priority=`P1`
+
+## Правила работы
+
+- Все исходные тексты, документы, код проекта — в этом репо.
+- Чувствительные данные (`.env`, токены, ключи) — игнорируются `.gitignore`.
+- AI-ассистенту разрешено: читать, генерировать, редактировать в этом репо.
+
+## Канонические команды
+
+- `atlas projects get skillkit` — карточка проекта
+- `atlas task list --project skillkit` — задачи проекта (когда W7
+  волна будет реализована)
+
+<!-- atlas:usage:start -->
+## Управление проектом — через Atlas
+
+Этот проект ведётся в Atlas (личная PM-система портфеля). Для задач/проектов/эпиков/бэкапов
+используй CLI `atlas` и вызывай навык `atlas` — вся логика и роутинг внутри навыка.
+<!-- atlas:usage:end -->

s_skillkit-0.2.2/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+Все заметные изменения кита `s-skillkit` фиксируются здесь. Формат близок к
+[Keep a Changelog](https://keepachangelog.com/ru/1.1.0/); версионирование —
+[SemVer](https://semver.org/lang/ru/).
+
+## [0.2.2] — 2026-07-21
+
+### Fixed — монорепо-навык (навык в подпапке репозитория)
+
+- **`skill_path` переживает установку**: `_skill_meta.json` теперь хранит
+  подпапку навыка, а `SkillStore.update()` берёт её оттуда, если не передали
+  явно. Раньше в `update` стоял жёсткий `skill_path=None` — обновление
+  материализовало КОРЕНЬ монорепо, и в папку навыка налипали `src/`,
+  `pyproject.toml` и копия самого навыка, а `SKILL.md` оказывался этажом ниже
+  (в таком виде Claude Code навык не видит).
+- **`preserved_paths` читаются из `_skill_meta.toml`** навыка, а не только из
+  захардкоженного списка. Навык может защитить свои данные (папку с БД,
+  кэш) — они переживут обновление; общие дефолты (`_local/`,
+  `browser_profiles/`) при этом сохраняются.
+
+### Added — детект пакетного менеджера (`pkg_manager`)
+
+- `detect_project()` определяет экосистему по маркерам: python (`uv.lock`,
+  `pyproject.toml`, `requirements.txt`), node с КОНКРЕТНЫМ менеджером по
+  lock-файлу (`bun`/`pnpm`/`yarn`/`npm`, при нескольких — по времени
+  изменения), rust, go, ruby, php.
+- `missing_manager_report()` вместо голого «не найдены ни uv, ни pip» отдаёт
+  машиночитаемые факты: тип проекта и маркер, чего не хватает, команда
+  установки под ТЕКУЩУЮ ОС и список реально доступных альтернатив. ИИ-агент
+  может довести установку сам.
+
+## [0.2.0] — 2026-07-15
+
+### Added — install-kit (установка навыка «под ключ» со ВСЕМИ зависимостями)
+
+- **`uv_bootstrap.ensure_uv()`** — гарантирует наличие `uv`: `which` →
+  официальный Astral-инсталлер (Windows PowerShell `install.ps1` / POSIX
+  `curl … install.sh | sh`) → фолбэк `python -m pip install uv`; PATH-плюмбинг
+  через `path_store`. Идемпотентно, graceful (не смогли поставить → `None`),
+  мокабельно (сеть не дёргается в тестах).
+- **`binary_installer`** — обобщение bespoke-`install_xray` в переиспользуемый
+  примитив внешних бинарей с GitHub Releases:
+  - `ensure_binary(name, *, github_repo, asset_match, dest_dir, version=None,
+    bin_subpath=None, force=False) -> Path` — latest/тег → выбор ассета
+    (callable/паттерн) → скачивание → распаковка zip/tar → `chmod 0o755` (POSIX)
+    → удаление архива; идемпотентно; на сбое — `BinaryInstallError`;
+  - `platform_asset_name(templates, *, system=None, arch=None)` — резолв имени
+    ассета по текущей ОС×архитектуре (ключи `(os, arch)` или строки `"os-arch"`);
+  - `is_binary_installed(name, dest_dir, *, bin_subpath=None)`.
+- **`deps_installer`** — новые kind `binary` / `github-release` в
+  `runtime_dependencies`: несут spec-словарь `{name, github_repo,
+  asset_match|asset_templates, dest, version?, bin_subpath?}` и делегируют
+  `ensure_binary`. Ветки `pip`/`npm`/`system` не изменены.
+- **`manifest.build_manifest`** — сохраняет полный spec-словарь бинарей (не
+  только `kind`/`spec`), чтобы install мог поставить внешний бинарь.
+- **`bootstrap.bootstrap_skill(skill_dir, *, manifest=None, gate_check=None,
+  run_self_check=True) -> dict`** — оркестрация: `ensure_uv` → python-deps
+  (`uv sync` при наличии `pyproject.toml`, иначе per-spec) → внешние бинари →
+  опциональный `gate_check`-хук (graceful, без жёсткой завязки на s-xray-gate) →
+  `run_self_check`. Отчёт `{uv, deps, binaries, gate, self_check}`; ни один шаг
+  не роняет установку.
+- **`bootstrap.run_self_check(skill_dir) -> (bool, str)`** — находит и запускает
+  `scripts/self_check.py` (venv-python навыка → `uv run` → текущий интерпретатор),
+  возвращает `(ok, output)`.
+- Экспорт в `skillkit.__all__`: `ensure_uv`, `ensure_binary`,
+  `is_binary_installed`, `platform_asset_name`, `bootstrap_skill`,
+  `run_self_check` (+ `BinaryInstallError`, подмодули `uv_bootstrap` /
+  `binary_installer` / `bootstrap`).
+
+### Changed
+
+- `version` 0.1.9 → 0.2.0.

s_skillkit-0.2.2/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: s-skillkit
+Version: 0.2.2
+Summary: Локальное ядро управления навыками: install из git/локальной папки, junction/symlink-линковка в scope агента, .skillignore-фильтр, build manifest, project-манифест. 0 завязок на сеть/auth — stdlib + tomli-w + pathspec + platformdirs.
+Author: Dmitry
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: pathspec>=0.12.0
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: tomli-w>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# s-skillkit
+
+Локальное ядро управления навыками (skills) — **SIBLING** `librarykit`
+(не зависит от него, от httpx, auth или сети). Только локальная ФС-механика.
+
+## Что внутри
+
+- **`SkillStore`** (`skillkit.installer`) — материализация навыка в центральный
+  стор и линковка (junction на Windows / symlink на POSIX) в scope агента:
+  - `install_from_git` / `install_from_path` / `install` / `materialize`
+  - `update` (инкрементальный sha-diff), `link_existing`, `migrate_scope`
+  - `remove` (keep-local / purge)
+  - P0 **stub-would-clobber guard** (stub не затирает живой контент).
+- **`targets`** — `IAgentTarget` + `detect_agent` / `get_target` (Claude Code,
+  Codex, Antigravity).
+- **`manifest`** — `build_manifest` для publish + ридеры frontmatter /
+  `_skill_meta.toml`.
+- **`filter`** — `.skillignore` / `files`-allowlist фильтр (pathspec).
+- **`project`** — проектный манифест `.skills-hub/skills.toml`.
+- **`Paths`** — инъекция каталогов (`store_dir` / `config_dir` / `bin_dir`).
+  `Paths.default()` — нативная раскладка через platformdirs.
+
+## Инъекция вместо завязки на конфиг
+
+Кит НЕ читает env/config. Каталоги передаются явным `Paths`; git-учётка —
+инъектируемым `credential_resolver` (callable `url -> url`). Потребитель (CLI)
+читает env-токен и собирает резолвер:
+
+```python
+from skillkit import SkillStore, Paths, get_target
+
+paths = Paths.default()  # или из ClientConfig
+
+def resolver(url: str) -> str:
+    token = os.environ.get("SKILLS_HUB_GIT_TOKEN")
+    if token and url.startswith("https://") and "@" not in url:
+        return url.replace("https://", f"https://oauth2:{token}@", 1)
+    return url
+
+store = SkillStore(get_target(None), paths.store_dir, credential_resolver=resolver)
+```
+
+## Канон «супер-навыка» (навык + CLI + онбординг)
+
+**Супер-навык** — навык, который несёт собственный CLI-инструмент. Канон нужен,
+чтобы ОДИН и тот же навык одинаково ставился тремя путями: локальным
+install-скриптом, `skillery install` из хаба и `skillery install --path/--from-git`.
+
+### Структура репозитория
+
+```
+<repo>/
+  pyproject.toml            # пакет CLI-инструмента (публикуется на PyPI)
+  src/<tool>/               # исходники CLI
+  install/install.sh|.ps1   # локальный установщик (см. ниже)
+  skills/<name>/            # САМ НАВЫК — только это материализуется агенту
+    SKILL.md                # инструкция для ИИ-агента
+    _skill_meta.toml        # ДЕКЛАРАЦИЯ навыка (источник истины)
+    references/  agents/
+```
+
+Навык может лежать и в корне репо (`SKILL.md` рядом с `_skill_meta.toml`) — тогда
+подпапка не нужна. Если навык в подпапке, хаб хранит её в `Skill.skill_path`, и
+манифест версии читается ИМЕННО оттуда (иначе tooling-поля теряются).
+
+### `_skill_meta.toml` — полная декларация
+
+```toml
+description = "Atlas - local-first PM портфеля проектов и задач."
+version = "0.3.0"
+kind = "tooling"                 # prompt | comprehensive | tooling
+tags = ["pm", "cli"]
+
+# ВАЖНО (TOML): top-level массивы объявляются ДО заголовков [[...]] —
+# иначе tomllib отнесёт ключ ВНУТРЬ таблицы, а не на верхний уровень.
+runtime_dependencies = [
+    { kind = "pip", spec = "atlas-pm==0.3.0" },   # чем ставится CLI
+]
+
+[[cli]]                          # какие команды навык приносит
+command_name = "atlas"
+entrypoint = "atlas.cli:app"
+
+[onboarding]                     # что делать ПОСЛЕ установки
+summary = "Локальный PM портфеля: проекты, задачи, эпики."
+next_steps = [
+  "atlas setup          # правила в CLAUDE.md/AGENTS.md + SessionStart-хук",
+  "atlas task triage    # что в работе / застряло / забыто",
+]
+docs = "https://github.com/<owner>/<repo>#readme"
+```
+
+### Как ставится: две дороги, один источник истины
+
+**Локальный install-скрипт** (`install/install.sh|.ps1`) — для человека «с нуля»:
+ставит `uv` (если нет) → `uv tool install <пакет>` → запускает post-setup
+инструмента (напр. `atlas setup`). Скрипты держим **ASCII-only**: их тянут через
+`irm | iex` / `curl | sh`, и не-ASCII может побиться.
+
+**`skillery install <skill>`** — та же логика, но декларативно:
+1. материализует папку навыка агенту (global или project scope);
+2. читает `_skill_meta.toml` **из установленного навыка** и ставит
+   `runtime_dependencies` + регистрирует `cli[]` (`apply_tooling_artifacts`);
+3. печатает `[onboarding]` — «что делать дальше».
+
+Источник истины для tooling — **декларация в самом навыке**, а не то, что доехало
+в манифесте бандла хаба: у навыка в подпапке бандл может прийти без `cli`/
+`runtime_dependencies`, поэтому инсталлятор до-читывает `_skill_meta.toml`.
+
+### Детект: не навреди стороннему навыку
+
+Установка CLI запускается **только по явной декларации** (`runtime_dependencies` /
+`cli` в `_skill_meta.toml`). Эвристики вида «рядом лежит `pyproject.toml` — значит
+надо поставить пакет» ЗАПРЕЩЕНЫ: сторонний навык часто живёт в чужом репо, и такая
+догадка поставила бы левый пакет. Навык без `_skill_meta.toml` (просто `SKILL.md`)
+материализуется как есть — ничего не выполняется и не ставится.
+
+### Онбординг обязателен для супер-навыка
+
+Навык, приносящий CLI, ОБЯЗАН объявить `[onboarding].next_steps`. Инсталлятор
+печатает их сразу после установки, чтобы **ИИ-агент довёл настройку сам**, а не
+оставлял пользователя с установленным, но ненастроенным инструментом. Контракт
+вывода: в text-режиме — человекочитаемый список, в `--json` — структурные поля
+(`next_steps`) в stderr, чтобы не засорять stdout с основным payload'ом.
+
+## Зависимости
+
+`tomli-w`, `pathspec`, `platformdirs`. requires-python `>=3.11`. MIT.

s_skillkit-0.2.2/README.md

@@ -0,0 +1,128 @@
+# s-skillkit
+
+Локальное ядро управления навыками (skills) — **SIBLING** `librarykit`
+(не зависит от него, от httpx, auth или сети). Только локальная ФС-механика.
+
+## Что внутри
+
+- **`SkillStore`** (`skillkit.installer`) — материализация навыка в центральный
+  стор и линковка (junction на Windows / symlink на POSIX) в scope агента:
+  - `install_from_git` / `install_from_path` / `install` / `materialize`
+  - `update` (инкрементальный sha-diff), `link_existing`, `migrate_scope`
+  - `remove` (keep-local / purge)
+  - P0 **stub-would-clobber guard** (stub не затирает живой контент).
+- **`targets`** — `IAgentTarget` + `detect_agent` / `get_target` (Claude Code,
+  Codex, Antigravity).
+- **`manifest`** — `build_manifest` для publish + ридеры frontmatter /
+  `_skill_meta.toml`.
+- **`filter`** — `.skillignore` / `files`-allowlist фильтр (pathspec).
+- **`project`** — проектный манифест `.skills-hub/skills.toml`.
+- **`Paths`** — инъекция каталогов (`store_dir` / `config_dir` / `bin_dir`).
+  `Paths.default()` — нативная раскладка через platformdirs.
+
+## Инъекция вместо завязки на конфиг
+
+Кит НЕ читает env/config. Каталоги передаются явным `Paths`; git-учётка —
+инъектируемым `credential_resolver` (callable `url -> url`). Потребитель (CLI)
+читает env-токен и собирает резолвер:
+
+```python
+from skillkit import SkillStore, Paths, get_target
+
+paths = Paths.default()  # или из ClientConfig
+
+def resolver(url: str) -> str:
+    token = os.environ.get("SKILLS_HUB_GIT_TOKEN")
+    if token and url.startswith("https://") and "@" not in url:
+        return url.replace("https://", f"https://oauth2:{token}@", 1)
+    return url
+
+store = SkillStore(get_target(None), paths.store_dir, credential_resolver=resolver)
+```
+
+## Канон «супер-навыка» (навык + CLI + онбординг)
+
+**Супер-навык** — навык, который несёт собственный CLI-инструмент. Канон нужен,
+чтобы ОДИН и тот же навык одинаково ставился тремя путями: локальным
+install-скриптом, `skillery install` из хаба и `skillery install --path/--from-git`.
+
+### Структура репозитория
+
+```
+<repo>/
+  pyproject.toml            # пакет CLI-инструмента (публикуется на PyPI)
+  src/<tool>/               # исходники CLI
+  install/install.sh|.ps1   # локальный установщик (см. ниже)
+  skills/<name>/            # САМ НАВЫК — только это материализуется агенту
+    SKILL.md                # инструкция для ИИ-агента
+    _skill_meta.toml        # ДЕКЛАРАЦИЯ навыка (источник истины)
+    references/  agents/
+```
+
+Навык может лежать и в корне репо (`SKILL.md` рядом с `_skill_meta.toml`) — тогда
+подпапка не нужна. Если навык в подпапке, хаб хранит её в `Skill.skill_path`, и
+манифест версии читается ИМЕННО оттуда (иначе tooling-поля теряются).
+
+### `_skill_meta.toml` — полная декларация
+
+```toml
+description = "Atlas - local-first PM портфеля проектов и задач."
+version = "0.3.0"
+kind = "tooling"                 # prompt | comprehensive | tooling
+tags = ["pm", "cli"]
+
+# ВАЖНО (TOML): top-level массивы объявляются ДО заголовков [[...]] —
+# иначе tomllib отнесёт ключ ВНУТРЬ таблицы, а не на верхний уровень.
+runtime_dependencies = [
+    { kind = "pip", spec = "atlas-pm==0.3.0" },   # чем ставится CLI
+]
+
+[[cli]]                          # какие команды навык приносит
+command_name = "atlas"
+entrypoint = "atlas.cli:app"
+
+[onboarding]                     # что делать ПОСЛЕ установки
+summary = "Локальный PM портфеля: проекты, задачи, эпики."
+next_steps = [
+  "atlas setup          # правила в CLAUDE.md/AGENTS.md + SessionStart-хук",
+  "atlas task triage    # что в работе / застряло / забыто",
+]
+docs = "https://github.com/<owner>/<repo>#readme"
+```
+
+### Как ставится: две дороги, один источник истины
+
+**Локальный install-скрипт** (`install/install.sh|.ps1`) — для человека «с нуля»:
+ставит `uv` (если нет) → `uv tool install <пакет>` → запускает post-setup
+инструмента (напр. `atlas setup`). Скрипты держим **ASCII-only**: их тянут через
+`irm | iex` / `curl | sh`, и не-ASCII может побиться.
+
+**`skillery install <skill>`** — та же логика, но декларативно:
+1. материализует папку навыка агенту (global или project scope);
+2. читает `_skill_meta.toml` **из установленного навыка** и ставит
+   `runtime_dependencies` + регистрирует `cli[]` (`apply_tooling_artifacts`);
+3. печатает `[onboarding]` — «что делать дальше».
+
+Источник истины для tooling — **декларация в самом навыке**, а не то, что доехало
+в манифесте бандла хаба: у навыка в подпапке бандл может прийти без `cli`/
+`runtime_dependencies`, поэтому инсталлятор до-читывает `_skill_meta.toml`.
+
+### Детект: не навреди стороннему навыку
+
+Установка CLI запускается **только по явной декларации** (`runtime_dependencies` /
+`cli` в `_skill_meta.toml`). Эвристики вида «рядом лежит `pyproject.toml` — значит
+надо поставить пакет» ЗАПРЕЩЕНЫ: сторонний навык часто живёт в чужом репо, и такая
+догадка поставила бы левый пакет. Навык без `_skill_meta.toml` (просто `SKILL.md`)
+материализуется как есть — ничего не выполняется и не ставится.
+
+### Онбординг обязателен для супер-навыка
+
+Навык, приносящий CLI, ОБЯЗАН объявить `[onboarding].next_steps`. Инсталлятор
+печатает их сразу после установки, чтобы **ИИ-агент довёл настройку сам**, а не
+оставлял пользователя с установленным, но ненастроенным инструментом. Контракт
+вывода: в text-режиме — человекочитаемый список, в `--json` — структурные поля
+(`next_steps`) в stderr, чтобы не засорять stdout с основным payload'ом.
+
+## Зависимости
+
+`tomli-w`, `pathspec`, `platformdirs`. requires-python `>=3.11`. MIT.

{s_skillkit-0.1.9 → s_skillkit-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "s-skillkit"
-version = "0.1.9"
+version = "0.2.2"
 description = "Локальное ядро управления навыками: install из git/локальной папки, junction/symlink-линковка в scope агента, .skillignore-фильтр, build manifest, project-манифест. 0 завязок на сеть/auth — stdlib + tomli-w + pathspec + platformdirs."
 readme = "README.md"
 license = { text = "MIT" }