fchek 1.0.0

package/skills/state.md

@@ -0,0 +1,261 @@
+# state.md — Память агента: диск vs RAM
+
+Агент имеет два инструмента памяти. Не путай их — у каждого своё назначение.
+
+---
+
+## Разграничение: state (диск) vs repl (RAM)
+
+| | `fchek state` | `fchek repl` |
+|---|---|---|
+| **Где хранит** | Диск (`.fcheck_state.json`) | Память процесса |
+| **Живёт после exit** | Да — навсегда | Нет — теряется при выходе |
+| **Назначение** | Долгосрочная память проекта | Итеративная работа в одной сессии |
+| **Что хранить** | Задача, решения, блокеры, прогресс | Черновики, промежуточные результаты |
+| **Размер** | До ~10KB на ключ | Не ограничен |
+| **Коммитится в git** | Нет (`.gitignore`) | Нет |
+
+**Правило:** если информация нужна в следующей сессии — используй `state`. Если только сейчас — используй `repl`.
+
+---
+
+## Что хранить в state
+
+Обязательные ключи для автономной работы:
+
+```bash
+# Текущая задача (обязательно в начале каждой задачи)
+fchek state set task "implement JWT refresh token rotation"
+fchek state set status "in_progress"   # todo | in_progress | done | blocked
+
+# Файлы относящиеся к задаче
+fchek state set files "src/auth.py src/middleware.py tests/test_auth.py"
+
+# Следующий шаг (обновляй после каждого законченного подшага)
+fchek state set next_step "написать тест для token expiry edge case"
+
+# Блокер (если задача заблокирована)
+fchek state set blocker "redis-server не установлен — нужен человек"
+
+# Архитектурные решения (сохраняй причину, не только выбор)
+fchek state set auth_lib "python-jose (выбрали вместо PyJWT — нужна поддержка JWE)"
+fchek state set db_pattern "repository pattern (файлы: src/repos/)"
+fchek state set error_style "Result[T, E] с custom exceptions (см. src/errors.py)"
+fchek state set cache_backend "Redis с TTL 3600s (bench показал 8ms vs 42ms для N>1000)"
+```
+
+### Что НЕ хранить в state:
+- Секреты, токены, пароли → только через env vars
+- Данные больше 10KB → используй `snapshot` для файлов
+- Временные результаты вычислений → используй `repl`
+
+---
+
+## Что хранить в repl
+
+`fchek repl` — это рабочий стол **одной сессии**. Используй для итеративной работы:
+
+```
+fchek> set hypothesis "LRU cache быстрее HashMap для N<100"
+fchek> profile src/cache.py
+fchek> set profile_result "HashMap: 42ms, Vec+linear: 8ms для N=50"
+fchek> bench . --before=cache_v1.py --after=cache_v2.py
+fchek> get hypothesis
+```
+
+Если результат важен для будущего — сохрани в state:
+```
+fchek> state set cache_decision "Vec+linear быстрее для N<100 (bench: 8ms vs 42ms)"
+```
+
+---
+
+## Команды state
+
+```bash
+fchek state set <key> <value>   # сохранить ключ
+fchek state get <key>           # прочитать один ключ
+fchek state list                # показать всё состояние
+fchek state delete <key>        # удалить ключ
+fchek state clear --yes         # сбросить всё состояние
+fchek state snapshot            # снапшот хешей файлов проекта
+```
+
+Вывод `fchek state list`:
+```json
+{
+  "status": "ok",
+  "data": {
+    "state": {
+      "task": "implement JWT refresh token rotation",
+      "status": "in_progress",
+      "files": "src/auth.py src/middleware.py tests/test_auth.py",
+      "next_step": "написать тест для token expiry edge case",
+      "blocker": null,
+      "auth_lib": "python-jose (выбрали вместо PyJWT — нужна поддержка JWE)"
+    }
+  }
+}
+```
+
+---
+
+## Полный сценарий автономной сессии
+
+**Задача:** Реализовать кэширование результатов SQL запросов через Redis
+
+---
+
+**Сессия 1 — начало работы**
+
+```bash
+# 1. Прочитать задачу, зафиксировать
+fchek state set task "кэширование SQL запросов через Redis"
+fchek state set status "in_progress"
+
+# 2. Войти в проект
+fchek audit .
+# → verdict: "healthy"
+
+fchek convention .
+# → framework: FastAPI, naming_style: snake_case, error_handling: raise HTTPException
+
+fchek context src/ --names-only
+# → name_index: {UserService, get_user, list_users}
+# → нет CacheService и нет cache_key — можно создавать
+
+# 3. Проверить зависимость
+fchek deps-check redis --lang=python
+# → installed_version: "5.0.1", latest_version: "5.0.1", deprecation_notices: []
+
+# 4. Зафиксировать архитектурное решение
+fchek state set cache_backend "redis 5.0.1 — актуальная версия"
+fchek state set files "src/cache.py src/services/user.py tests/test_cache.py"
+fchek state set next_step "создать CacheService в src/cache.py"
+
+# 5. Написать src/cache.py
+# [создаёт файл с CacheService]
+
+# 6. Проверить
+fchek run src/cache.py
+# → exit_code: 1, stderr: "redis.exceptions.ConnectionError: Error 111 connecting..."
+# → Redis не запущен локально
+
+# 7. Зафиксировать блокер
+fchek state set blocker "redis-server не запущен: ConnectionError 111"
+fchek state set next_step "запустить redis-server или использовать docker"
+fchek state set status "blocked"
+```
+
+Агент докладывает пользователю:
+```
+Реализовал CacheService (src/cache.py). Код написан и синтаксически корректен.
+
+Блокер: redis-server не запущен на хосте.
+fchek run → ConnectionError: Error 111 connecting to localhost:6379
+
+Запусти Redis:
+  redis-server          # если установлен
+  docker run -p 6379:6379 redis  # через Docker
+
+Затем продолжу: fchek run src/cache.py → интеграция с UserService.
+```
+
+---
+
+**Сессия 2 — пользователь запустил Redis, продолжаем**
+
+```bash
+# 1. Восстановить контекст
+fchek state list
+# → task: "кэширование SQL запросов через Redis"
+# → status: "blocked"
+# → blocker: "redis-server не запущен: ConnectionError 111"
+# → next_step: "запустить redis-server или использовать docker"
+# → files: "src/cache.py src/services/user.py tests/test_cache.py"
+
+# 2. Продолжить с next_step
+fchek run src/cache.py
+# → exit_code: 0, stdout: "CacheService initialized, connected to Redis"
+
+# 3. Снять блокер
+fchek state set blocker ""
+fchek state set status "in_progress"
+fchek state set next_step "интегрировать CacheService в UserService"
+
+# 4. Интегрировать в UserService
+# [изменяет src/services/user.py]
+
+# 5. Написать тесты
+# [создаёт tests/test_cache.py]
+
+# 6. Полный цикл проверок
+fchek run src/main.py
+# → exit_code: 0
+
+fchek test .
+# → verdict: all_passed, passed: 18, failed: 0
+
+fchek secrets .
+# → verdict: clean
+
+fchek lint .
+# → issues_count: 0
+
+# 7. Зафиксировать
+fchek git stage src/cache.py src/services/user.py tests/test_cache.py
+fchek git commit "feat: add Redis cache for SQL query results"
+
+fchek state set status "done"
+```
+
+Агент докладывает пользователю:
+```
+Реализовал кэширование SQL запросов через Redis.
+
+Изменённые файлы:
+  src/cache.py              — CacheService (TTL, invalidation)
+  src/services/user.py      — интеграция с кэшем в get_user(), list_users()
+  tests/test_cache.py       — 6 тестов (mock Redis)
+
+Проверки:
+  fchek run src/main.py → exit_code: 0
+  fchek test .          → verdict: all_passed (18 passed, 0 failed)
+  fchek secrets .       → verdict: clean
+  fchek lint .          → issues_count: 0
+
+Коммит: feat: add Redis cache for SQL query results (c7a4b2e)
+```
+
+---
+
+## Снапшот — сохранение состояния файлов
+
+```bash
+fchek state snapshot
+```
+```json
+{
+  "status": "ok",
+  "data": {
+    "file_count": 12,
+    "snapshot_time": "2026-07-08T11:06:51Z",
+    "__snapshot": {
+      "files": {
+        "src/cache.py":          {"hash": "a3f9c2d", "lines": 87},
+        "src/services/user.py":  {"hash": "b2e8a1f", "lines": 124}
+      }
+    }
+  }
+}
+```
+
+Используй перед большим рефакторингом — чтобы знать что именно изменилось.
+
+---
+
+## Безопасность
+
+- `.fcheck_state.json` автоматически добавляется в `.gitignore`
+- Файл не коммитится в git
+- Никогда не сохраняй в state: пароли, API ключи, токены, connection strings

package/skills/vuln.md

@@ -0,0 +1,57 @@
+# skill: fchek vuln — Безопасность и зависимости (Тайпосквоттинг)
+
+## Что делает
+
+Сканирует файлы зависимостей (`package.json`, `requirements.txt`, `Cargo.toml`) на:
+- **Уязвимости**: запускает `npm audit`, `pip-audit` или `cargo audit`.
+- **Тайпосквоттинг**: сравнивает установленные пакеты с базой популярных библиотек с помощью расстояния Левенштейна. Обнаруживает опечатки, подменяющие легитимные пакеты вредоносными (например, `react-doom` вместо `react-dom`).
+
+## Синтаксис
+
+```bash
+# Проверить текущую директорию
+fchek vuln
+
+# Проверить конкретную папку проекта
+fchek vuln /path/to/project
+```
+
+## Вывод JSON
+
+```json
+{
+  "status": "ok",
+  "command": "vuln",
+  "data": {
+    "packages_checked": 12,
+    "vulnerabilities": [
+      {
+        "package": "lodash",
+        "severity": "high",
+        "via": "CVE-2021-23337",
+        "effects": []
+      }
+    ],
+    "typosquatting_warnings": [
+      {
+        "package": "react-doom",
+        "type": "npm",
+        "suspectedTyposquatOf": "react-dom",
+        "distance": 1
+      }
+    ],
+    "audit_ran": ["npm"]
+  }
+}
+```
+
+## КАК AI ДОЛЖЕН ИСПОЛЬЗОВАТЬ ЭТО
+
+### Сценарии
+
+1. **Добавление новой библиотеки**: всегда проверяй зависимости после их установки или перед фиксацией изменений:
+   ```bash
+   fchek vuln .
+   ```
+2. **Проверка уязвимостей**: используй результаты `vulnerabilities` для обновления пакетов на исправленные версии.
+3. **Обнаружение вредоносных опечаток**: при наличии предупреждений в `typosquatting_warnings` немедленно удали подозрительный пакет и установи правильный.

package/skills/windows.md

@@ -0,0 +1,320 @@
+# skill: fchek — Windows & WPF автономная работа
+
+## Что доступно на Windows
+
+| Команда | Что делает | Когда использовать |
+|---|---|---|
+| `fchek screenshot` | Скриншот окна или экрана → PNG | Проверить что UI открылся и выглядит правильно |
+| `fchek launch` | Запустить .exe и ждать окна | Запустить WPF/WinForms и убедиться что открылось |
+| `fchek winlog` | Читать Event Viewer | Найти crash/error после запуска |
+| `fchek registry` | Читать/писать реестр | Проверить что установщик/скрипт записал ключи |
+| `fchek process` | Список/kill/info процессов | Убить старый экземпляр, проверить память |
+| `fchek watch` | Авто-rebuild при изменении файлов | WPF: изменил XAML → автоматически пересобирается |
+
+---
+
+## WORKFLOW: WPF / Windows приложение
+
+### Полный цикл от кода до проверки UI
+
+```bash
+# 1. Понять проект
+fchek convention .
+fchek context src/ --names-only
+
+# 2. Проверить что нет старых экземпляров
+fchek process exists Vertex
+# → если exists: true → убить
+fchek process kill Vertex
+
+# 3. Написать код, затем собрать
+fchek run src/MainWindow.cs      # dotnet build через fchek run
+# или
+fchek watch . --cmd="dotnet build" --launch=bin/Debug/net8.0-windows/Vertex.exe
+
+# 4. Запустить и дождаться окна
+fchek launch bin/Debug/net8.0-windows/Vertex.exe --title=Vertex --wait=8000
+# → window_appeared: true? Да → дальше
+# → window_appeared: false? → смотри winlog
+
+# 5. Сделать скриншот и проверить UI
+fchek screenshot --window=Vertex
+# → { "file": "C:/tmp/fchek_screenshot_123.png", "width": 1200, "height": 800 }
+# Прочитай изображение — правильно ли выглядит UI?
+
+# 6. Если что-то не так — смотри логи
+fchek winlog --source=Application --filter=Vertex --level=Error --since=5
+# → события за последние 5 минут
+
+# 7. Проверить реестр если нужно
+fchek registry get HKCU\Software\Vertex
+```
+
+---
+
+## Команды подробно
+
+### fchek screenshot
+
+```bash
+fchek screenshot --screen                    # весь экран
+fchek screenshot --window=Vertex             # конкретное окно по заголовку
+fchek screenshot --window=SpotlightWindow    # partial match
+fchek screenshot --region=0,0,800,600        # координаты x,y,ширина,высота
+fchek screenshot --out=C:\tmp\ui_check.png   # сохранить в конкретный файл
+```
+
+Вывод:
+```json
+{
+  "file": "C:\\Users\\...\\fchek_screenshot_1234.png",
+  "width": 1200,
+  "height": 800,
+  "window": "Vertex — Settings",
+  "pid": 12345,
+  "type": "window"
+}
+```
+
+**Как AI использует скриншот:**
+1. `fchek screenshot --window=Vertex` → получаю путь к PNG
+2. Читаю изображение — вижу реальный UI
+3. Проверяю: правильно ли расположены элементы, закруглены ли углы, появился ли popup
+
+---
+
+### fchek launch
+
+```bash
+fchek launch bin/Vertex.exe
+fchek launch bin/Vertex.exe --title=SpotlightWindow --wait=8000
+fchek launch "C:\App\App.exe" --kill-existing --args="--debug"
+```
+
+Вывод:
+```json
+{
+  "launched": true,
+  "pid": 12345,
+  "window_appeared": true,
+  "window_title": "Vertex — Main",
+  "position": { "x": 100, "y": 100, "width": 1200, "height": 800 },
+  "elapsed_ms": 1240,
+  "next_step": "Window is visible. Run: fchek screenshot --window=\"Vertex — Main\""
+}
+```
+
+**Алгоритм:**
+```
+window_appeared: true  → делай screenshot → проверяй UI
+window_appeared: false → смотри winlog --since=1 → ищи ошибку запуска
+error: "Process exited with code 1" → fchek winlog → читай stderr
+```
+
+---
+
+### fchek winlog
+
+```bash
+fchek winlog                                          # последние 50 из Application
+fchek winlog --source=Application --filter=Vertex    # только твоё приложение
+fchek winlog --level=Error --since=10                 # ошибки за последние 10 минут
+fchek winlog --source=System --level=Critical        # системные критические
+```
+
+Вывод:
+```json
+{
+  "verdict": "errors_found",
+  "errors": 2,
+  "events": [
+    {
+      "time": "2026-07-09 19:00:00",
+      "level": "Error",
+      "provider": "Vertex",
+      "id": 1000,
+      "message": "NullReferenceException in MainWindow.cs:42"
+    }
+  ]
+}
+```
+
+**Алгоритм:**
+```
+verdict: "clean"        → нет ошибок в логах
+verdict: "errors_found" → читай events[].message → найди строку с ошибкой
+verdict: "warnings_found" → предупреждения, не критично
+
+Типичные провайдеры:
+  ".NET Runtime"         → NullReferenceException, StackOverflow
+  "Application Error"    → необработанное исключение
+  "Windows Error Reporting" → crash dump
+```
+
+---
+
+### fchek registry
+
+```bash
+fchek registry get HKCU\Software\Vertex
+fchek registry get HKCU\Software\Vertex\Theme
+fchek registry set HKCU\Software\Vertex Theme dark
+fchek registry set HKCU\Software\Vertex AutoStart 1 --type=REG_DWORD
+fchek registry exists HKCU\Software\Vertex
+fchek registry delete HKCU\Software\Vertex\OldKey
+```
+
+Проверяй что bat/инсталлятор реально записал нужные ключи:
+```bash
+# После запуска bat-скрипта:
+fchek registry exists HKCU\Software\MyApp
+# → exists: true → скрипт отработал
+# → exists: false → скрипт не выполнил запись
+```
+
+---
+
+### fchek process
+
+```bash
+fchek process list                      # все процессы
+fchek process list --filter=Vertex      # фильтр по имени
+fchek process info Vertex               # детальная инфо: память, CPU, потоки
+fchek process info 12345                # по PID
+fchek process kill Vertex               # убить процесс
+fchek process exists Vertex             # проверить запущен ли
+fchek process wait-exit Vertex --timeout=10000  # ждать пока закроется
+```
+
+Вывод info:
+```json
+{
+  "found": true,
+  "pid": 12345,
+  "name": "Vertex",
+  "mem_mb": 145.3,
+  "peak_mem_mb": 198.7,
+  "cpu_s": 2.34,
+  "threads": 24,
+  "handles": 456,
+  "started": "2026-07-09 18:55:00"
+}
+```
+
+---
+
+### fchek watch
+
+```bash
+# WPF проект — авто-rebuild при изменении .cs или .xaml
+fchek watch . --ext=cs,xaml --cmd="dotnet build" --launch=bin/Debug/net8.0-windows/Vertex.exe
+
+# Python — авто-запуск тестов при изменении .py
+fchek watch src/ --ext=py --cmd="python -m pytest" --debounce=500
+
+# Только один раз (CI-режим)
+fchek watch . --once
+```
+
+При каждом успешном rebuild:
+```json
+{
+  "build": 3,
+  "success": true,
+  "cmd": "dotnet build",
+  "built_at": "2026-07-09T19:00:00.000Z",
+  "launched": true
+}
+```
+
+---
+
+## Типичные проблемы и решения
+
+### Приложение не запускается
+
+```bash
+fchek launch bin/Vertex.exe --wait=10000
+# → window_appeared: false
+
+# Смотри логи
+fchek winlog --source=Application --level=Error --since=2
+# → читай message → находи строку с ошибкой
+
+# Проверь что .NET установлен
+fchek doctor
+# → dotnet: ok / missing
+```
+
+### Окно открылось но UI неправильный
+
+```bash
+fchek screenshot --window=Vertex
+# → читаю PNG → вижу что popup открылся не там
+
+# Смотрю позицию окна
+fchek process info Vertex
+# → координаты через fchek launch тоже возвращают x,y,width,height
+```
+
+### Реестр не записался
+
+```bash
+fchek registry exists HKCU\Software\MyApp
+# → exists: false → bat не отработал
+
+# Проверяем права
+fchek winlog --source=System --level=Error --since=5
+# → ищем "Access Denied" или "Insufficient privileges"
+```
+
+### Завис старый экземпляр
+
+```bash
+fchek process exists Vertex
+# → exists: true, pid: 12345
+
+fchek process kill Vertex
+# → killed: true
+
+# Ждём пока точно закроется
+fchek process wait-exit Vertex --timeout=5000
+
+# Теперь запускаем новый
+fchek launch bin/Vertex.exe
+```
+
+---
+
+## Полный WPF цикл для AI-агента
+
+```bash
+# Вход в проект
+fchek audit .
+fchek config show
+
+# Понять структуру
+fchek context src/ --names-only
+fchek convention .
+
+# Убить старый экземпляр
+fchek process kill Vertex 2>/dev/null || true
+
+# Написать код...
+
+# Собрать
+fchek run src/App.cs       # dotnet build
+
+# Запустить
+fchek launch bin/Debug/net8.0-windows/Vertex.exe --title=Vertex --wait=8000
+
+# Проверить UI визуально
+fchek screenshot --window=Vertex
+
+# Проверить логи на ошибки
+fchek winlog --filter=Vertex --level=Error --since=2
+
+# Зафиксировать
+fchek git stage src/MainWindow.cs src/MainWindow.xaml
+fchek git commit "fix: correct popup positioning in SpotlightWindow"
+```