fchek 1.0.0

package/skills/agent.md

@@ -0,0 +1,444 @@
+# agent.md — Полная инструкция автономной работы
+
+Ты работаешь как опытный разработчик: взял задачу, сделал, проверил, сдал.
+Человек получает только готовый результат — не процесс.
+
+---
+
+## ЦИКЛ РАЗРАБОТКИ
+
+```
+ПОЛУЧИЛ
+  └─→ ПОНЯЛ ──────────────────────────────────────────────────┐
+        └─→ СПЛАНИРОВАЛ ──────────────────────────────────────┤
+              └─→ НАПИСАЛ ───────────────────────────────────┤
+                    └─→ ПРОВЕРИЛ ─── ✗ ──→ ИСПРАВИЛ ─────────┤
+                          └─── ✓ ──→ ЗАФИКСИРОВАЛ            ┤
+                                          └─→ ДОЛОЖИЛ ────────┘
+```
+
+Если ПРОВЕРИЛ вернул ошибку — возвращайся к ИСПРАВИЛ, потом снова ПРОВЕРИЛ.
+Не выходи из петли пока все проверки не зелёные.
+
+---
+
+## КОМАНДЫ ПО ФАЗАМ
+
+### ФАЗА: ПОНЯЛ
+
+Выполни все три команды перед тем как писать хоть одну строку кода.
+
+```bash
+fchek audit .
+```
+```json
+{
+  "status": "ok",
+  "data": {
+    "verdict": "healthy",
+    "critical_issues": [],
+    "next_actions": ["run fchek lint . to clean up 3 warnings"]
+  }
+}
+```
+Если `verdict: "needs_attention"` — исправь `critical_issues[]` немедленно.
+
+```bash
+fchek convention .
+```
+```json
+{
+  "status": "ok",
+  "data": {
+    "conventions": [{
+      "framework": "FastAPI",
+      "naming_style": "snake_case",
+      "error_handling": "HTTPException + custom handlers",
+      "async_patterns": "async/await throughout",
+      "logging_style": ["structlog", "stdlib logging"]
+    }]
+  }
+}
+```
+Читай `naming_style`, `error_handling`, `logging_style[0]`. Используй тот же стиль.
+
+```bash
+fchek context src/ --names-only
+```
+```json
+{
+  "status": "ok",
+  "data": {
+    "name_index": {
+      "UserService": [{"file": "src/services/user.py", "line": 12}],
+      "validate_email": [{"file": "src/utils.py", "line": 87}]
+    },
+    "duplicates": []
+  }
+}
+```
+Читай `name_index`. Если нужное имя уже занято — используй существующее или выбери другое.
+
+---
+
+### ФАЗА: СПЛАНИРОВАЛ
+
+Зафиксируй план до написания кода:
+```bash
+fchek state set task "реализовать JWT refresh token rotation"
+fchek state set files "src/auth.py src/middleware.py tests/test_auth.py"
+fchek state set next_step "начать с src/auth.py — функция rotate_refresh_token()"
+```
+
+Проверь зависимости которые собираешься использовать:
+```bash
+fchek deps-check <lib> --lang=<python|js|rust|go|csharp>
+```
+```json
+{
+  "status": "ok",
+  "data": {
+    "package": "python-jose",
+    "installed_version": "3.3.0",
+    "latest_version": "3.3.0",
+    "installed_deprecated": null,
+    "deprecation_notices": []
+  }
+}
+```
+Если `installed_deprecated` не null или `deprecation_notices` не пуст — сообщи пользователю.
+
+---
+
+### ФАЗА: НАПИСАЛ
+
+Пиши код в стиле который показала `fchek convention`.
+После каждого файла сохраняй прогресс:
+```bash
+fchek state set status "in_progress"
+fchek state set next_step "написать тесты для rotate_refresh_token()"
+```
+
+---
+
+### ФАЗА: ПРОВЕРИЛ
+
+Выполни все четыре проверки строго по порядку:
+
+**Проверка 1 — код запускается:**
+```bash
+fchek run src/main.py
+```
+```json
+{
+  "status": "ok",
+  "data": {
+    "exit_code": 0,
+    "success": true,
+    "stdout": "Server started on :8000\n",
+    "stderr": ""
+  }
+}
+```
+Ожидаемое: `exit_code: 0`, `success: true`, `stderr: ""`.
+
+**Проверка 2 — тесты проходят:**
+```bash
+fchek test .
+```
+```json
+{
+  "status": "ok",
+  "data": {
+    "verdict": "all_passed",
+    "passed": 24,
+    "failed": 0,
+    "skipped": 1
+  }
+}
+```
+Ожидаемое: `verdict: "all_passed"`, `failed: 0`.
+
+**Проверка 3 — нет секретов:**
+```bash
+fchek secrets .
+```
+```json
+{
+  "status": "ok",
+  "data": {
+    "verdict": "clean",
+    "total_findings": 0,
+    "summary": {"critical": 0, "high": 0, "other": 0}
+  }
+}
+```
+Ожидаемое: `verdict: "clean"`, `total_findings: 0`.
+
+**Проверка 4 — код чистый:**
+```bash
+fchek lint .
+```
+```json
+{
+  "status": "ok",
+  "data": {
+    "issues_count": 0,
+    "fixed": 3,
+    "remaining_issues": []
+  }
+}
+```
+Ожидаемое: `issues_count: 0` (или ≤ `config.lint_threshold`).
+
+---
+
+### ФАЗА: ИСПРАВИЛ (ПЕТЛЯ ИСПРАВЛЕНИЯ)
+
+Если любая проверка упала — входи в петлю:
+
+```
+ОШИБКА ПОЛУЧЕНА
+      ↓
+Читай error/reason/verdict — точно что упало?
+      ↓
+Исправь ОДНУ конкретную причину
+      ↓
+Запусти ТУ ЖЕ проверку снова
+      ↓
+Получи зелёный результат
+      ↓
+Переходи к следующей проверке
+```
+
+**Правила петли:**
+- Исправляй одну причину за раз — не переписывай всё сразу
+- После двух неудачных попыток одного подхода — смени подход
+- Не переходи к следующей проверке пока текущая не зелёная
+- Если застрял более трёх итераций — зафиксируй: `fchek state set blocker "<проблема>"`
+
+**Максимальное число итераций на одну ошибку: 5.**
+Если за 5 итераций не исправил — это блокер. Зафиксируй и доложи.
+
+---
+
+### ФАЗА: ЗАФИКСИРОВАЛ
+
+```bash
+# Убедись что всё в порядке
+fchek git status
+```
+```json
+{
+  "data": {
+    "branch": "feat/jwt-refresh",
+    "staged": [],
+    "unstaged": ["src/auth.py", "tests/test_auth.py"],
+    "is_clean": false
+  }
+}
+```
+
+```bash
+# Поставь в stage только изменённые файлы задачи
+fchek git stage src/auth.py tests/test_auth.py
+
+# Коммит с осмысленным сообщением
+fchek git commit "feat: implement JWT refresh token rotation"
+```
+```json
+{
+  "status": "ok",
+  "data": {
+    "committed": true,
+    "message": "feat: implement JWT refresh token rotation",
+    "files_committed": ["src/auth.py", "tests/test_auth.py"],
+    "hash": "a3f9c2d"
+  }
+}
+```
+
+```bash
+# Обнови state
+fchek state set status "done"
+```
+
+---
+
+### ФАЗА: ДОЛОЖИЛ
+
+Доклад состоит из четырёх частей — ни больше, ни меньше:
+
+1. **Что сделано** — одно-два предложения
+2. **Какие файлы изменены** — список
+3. **Вывод проверок** — `fchek run` + `fchek test` с реальными значениями
+4. **Что не сделано** (если есть) — блокеры или ограничения
+
+Шаблон доклада:
+```
+Реализовал JWT refresh token rotation.
+
+Изменённые файлы:
+  src/auth.py        — функция rotate_refresh_token()
+  tests/test_auth.py — 4 новых теста
+
+Проверки:
+  fchek run src/main.py  → exit_code: 0
+  fchek test .           → verdict: all_passed (24 passed, 0 failed)
+  fchek secrets .        → verdict: clean
+  fchek lint .           → issues_count: 0
+
+Коммит: feat: implement JWT refresh token rotation (a3f9c2d)
+```
+
+Не добавляй ничего лишнего. Не говори «я» и «постарался». Только факты.
+
+---
+
+## ПРИМЕРЫ РЕАЛЬНЫХ ДИАЛОГОВ
+
+### Пример 1: простая задача
+
+**Задача:** Добавь функцию `calculate_discount(price, percent)` в `src/pricing.py`
+
+**Что делает агент:**
+```bash
+fchek context src/ --names-only
+# → name_index не содержит "calculate_discount" ✓
+
+fchek convention .
+# → naming_style: snake_case, error_handling: raise ValueError
+
+# [пишет функцию]
+
+fchek run src/pricing.py
+# → exit_code: 0
+
+fchek test .
+# → verdict: all_passed, passed: 8
+
+fchek secrets .
+# → verdict: clean
+
+fchek lint .
+# → issues_count: 0
+
+fchek git stage src/pricing.py
+fchek git commit "feat: add calculate_discount function"
+```
+
+**Что говорит агент:**
+```
+Добавил функцию calculate_discount(price, percent) в src/pricing.py.
+
+Изменённые файлы:
+  src/pricing.py — calculate_discount() в строке 34
+
+Проверки:
+  fchek run src/pricing.py → exit_code: 0
+  fchek test .             → verdict: all_passed (8 passed)
+  fchek secrets .          → verdict: clean
+
+Коммит: feat: add calculate_discount function (b2e8a1f)
+```
+
+---
+
+### Пример 2: задача с существующим именем
+
+**Задача:** Создай класс `UserValidator` в проекте
+
+**Что делает агент:**
+```bash
+fchek context src/ --names-only
+# → name_index содержит "UserValidator": [{"file": "src/validators.py", "line": 45}]
+```
+
+**Что говорит агент:**
+```
+В проекте уже есть UserValidator в src/validators.py:45.
+Использую существующий. Уточни какую именно логику нужно добавить или изменить.
+```
+
+---
+
+### Пример 3: задача с секретами
+
+**Задача:** Добавь подключение к PostgreSQL
+
+**Что делает агент:**
+```bash
+# [пишет код с connection string]
+
+fchek secrets .
+# → verdict: "critical", findings[0].file: "src/db.py", findings[0].line: 8
+```
+
+**Что делает агент (исправляет):**
+```python
+# Было:
+DB_URL = "postgresql://admin:Secret123@prod.db:5432/app"
+
+# Стало:
+import os
+DB_URL = os.environ.get("DATABASE_URL")
+```
+
+```bash
+fchek secrets .
+# → verdict: clean ✓
+```
+
+**Что говорит агент:**
+```
+Добавил подключение к PostgreSQL через переменную окружения DATABASE_URL.
+
+Изменённые файлы:
+  src/db.py — connection через os.environ.get("DATABASE_URL")
+
+Проверки:
+  fchek secrets . → verdict: clean
+  fchek run src/main.py → exit_code: 0
+
+Установи переменную перед запуском:
+  export DATABASE_URL="postgresql://user:pass@host:5432/db"
+```
+
+---
+
+### Пример 4: задача с блокером
+
+**Задача:** Добавь кэширование через Redis
+
+**Что делает агент:**
+```bash
+fchek deps-check redis --lang=python
+# → installed_version: null (не установлен)
+
+# [пытается запустить после установки]
+fchek run main.py
+# → error: "Runtime not found: redis-server"
+
+fchek doctor
+# → redis-server: not found
+```
+
+```bash
+fchek state set blocker "redis-server не установлен на хосте"
+fchek state set next_step "установить Redis: brew install redis / apt install redis-server"
+```
+
+**Что говорит агент:**
+```
+Написал код кэширования через Redis (src/cache.py).
+
+Блокер: redis-server не установлен на этой машине.
+fchek doctor → redis-server: not found
+
+Что нужно:
+  brew install redis     # macOS
+  apt install redis-server  # Linux
+
+После установки запусти: fchek run src/main.py
+Код готов, ждёт только Redis.
+```

package/skills/api.md

@@ -0,0 +1,47 @@
+# skill: fchek api — Тестирование HTTP/API
+
+## Что делает
+
+Выполняет HTTP-запросы к веб-сервисам и эндпоинтам для проверки работоспособности API. Возвращает статус-код, заголовки, размер тела ответа и latency.
+
+## Синтаксис
+
+```bash
+fchek api <url> [--method=<method>] [--headers=<key:val,key2:val2>] [--body=<body>]
+```
+
+## Вывод JSON
+
+```json
+{
+  "status": "ok",
+  "command": "api",
+  "data": {
+    "status_code": 200,
+    "status_text": "OK",
+    "time_ms": 42,
+    "headers": {
+      "content-type": "application/json; charset=utf-8",
+      "connection": "close"
+    },
+    "body_size_bytes": 17,
+    "body": "{\"hello\":\"world\"}",
+    "body_truncated": false
+  }
+}
+```
+
+## КАК AI ДОЛЖЕН ИСПОЛЬЗОВАТЬ ЭТО
+
+### Сценарии
+
+1. **Проверка работоспособности**: после развертывания веб-сервера выполни запрос:
+   ```bash
+   fchek api http://localhost:3000/health
+   ```
+   Убедись, что `"status_code": 200`.
+
+2. **Проверка интеграции**: проверь ответ внешнего API:
+   ```bash
+   fchek api https://httpbin.org/post --method=POST --headers="Content-Type:application/json" --body="{\"test\":true}"
+   ```

package/skills/bench.md

@@ -0,0 +1,117 @@
+# skill: fchek bench — бенчмарк до/после рефакторинга
+
+## Что делает
+
+Запускает два варианта кода (до и после изменений) N раз каждый
+и показывает точный diff по времени и памяти.
+Убирает "я думаю стало быстрее" — заменяет догадки числами.
+
+## Синтаксис
+
+```bash
+fchek bench <file> --before=<ver_a> --after=<ver_b> [--runs=5] [--timeout=30000]
+```
+
+- `--before=<path>` — "до" версия (файл или shell-команда)
+- `--after=<path>`  — "после" версия
+- `--runs=N` — количество запусков для стабильного среднего (default: 5)
+- `--timeout=ms` — таймаут на один запуск (default: 30000)
+
+## Вывод JSON
+
+```json
+{
+  "status": "ok",
+  "command": "bench",
+  "data": {
+    "before": {
+      "spec": "main_old.py",
+      "runs": 5,
+      "avg_ms": 842,
+      "min_ms": 831,
+      "max_ms": 860,
+      "stdout_sample": "result: 42\n"
+    },
+    "after": {
+      "spec": "main.py",
+      "avg_ms": 201,
+      "min_ms": 195,
+      "max_ms": 210
+    },
+    "comparison": {
+      "time_delta_ms": -641,
+      "speedup_ratio": 4.189,
+      "verdict": "faster",
+      "pct_change": 318.9
+    },
+    "stdout_diff": [
+      { "line": 3, "before": "old output", "after": "new output" }
+    ]
+  }
+}
+```
+
+`verdict`: `"faster"` | `"slower"` | `"no_significant_change"` (порог ±5%)
+
+## Как AI должен использовать это
+
+### Сценарий: "Провёл рефакторинг — проверить что стало быстрее"
+
+```bash
+# Сохрани старую версию перед изменениями
+cp main.py main_old.py
+# ... внеси изменения в main.py ...
+
+# Бенчмарк
+fchek bench main.py --before=main_old.py --after=main.py --runs=10
+```
+
+### Сценарий: "Сравнить два алгоритма"
+
+```bash
+fchek bench . \
+  --before="python algo_v1.py --input=data.json" \
+  --after="python algo_v2.py --input=data.json" \
+  --runs=5
+```
+
+### Сценарий: "Сравнить Rust релиз vs дебаг"
+
+```bash
+fchek bench . \
+  --before="cargo run -- data.txt" \
+  --after="cargo run --release -- data.txt" \
+  --runs=3
+```
+
+### Алгоритм интерпретации результатов
+
+```
+speedup_ratio > 1.0 → after быстрее
+speedup_ratio < 1.0 → after медленнее
+speedup_ratio = 4.2 → после в 4.2× быстрее = +320% производительности
+
+verdict = "no_significant_change" → разница < 5%, шум измерений
+  → увеличь --runs=20 для стабильности
+  → проверь что входные данные одинаковые
+
+stdout_diff не пустой → результаты различаются!
+  → рефакторинг изменил поведение — баг?
+```
+
+### Ключевые поля для AI
+
+| Поле | Что означает |
+|---|---|
+| `comparison.speedup_ratio` | во сколько раз after быстрее before |
+| `comparison.verdict` | `faster` / `slower` / `no_significant_change` |
+| `comparison.pct_change` | % изменения производительности |
+| `stdout_diff` | различия в выводе — если не пустой, поведение изменилось |
+| `before.min_ms` / `after.min_ms` | минимальное время (наиболее стабильная метрика) |
+
+## Важные замечания
+
+- Используй `min_ms` как основную метрику — она менее подвержена шуму OS
+- `--runs=5` достаточно для первой оценки, `--runs=20` для точных данных
+- Если `stdout_diff` не пустой — сначала проверь правильность, потом скорость
+- Для C/C++ файлы компилируются с `-O2` — убедись что тестируешь то что хочешь