fchek 1.0.0

package/skills/port.md

@@ -0,0 +1,57 @@
+# skill: fchek port — Сеть и порты
+
+## Что делает
+
+Проверяет сетевые порты и активные соединения. 
+- Позволяет узнать, запущен ли сервис на конкретном порту.
+- Выясняет, какой процесс занимает порт (PID и имя процесса).
+- Позволяет получить список всех активных прослушиваемых портов.
+
+## Синтаксис
+
+```bash
+# Проверить конкретный порт
+fchek port <port_number>
+
+# Показать все активные слушающие порты
+fchek port --all
+```
+
+## Вывод JSON
+
+```json
+{
+  "status": "ok",
+  "command": "port",
+  "data": {
+    "port": 8080,
+    "in_use": true,
+    "connections": [
+      {
+        "proto": "TCP",
+        "localAddress": "0.0.0.0:8080",
+        "state": "LISTENING",
+        "port": 8080,
+        "pid": 1234,
+        "processName": "node.exe"
+      }
+    ]
+  }
+}
+```
+
+## КАК AI ДОЛЖЕН ИСПОЛЬЗОВАТЬ ЭТО
+
+### Сценарии
+
+1. **Порт занят**: если запускаемый сервер выдает ошибку `EADDRINUSE`, запусти:
+   ```bash
+   fchek port 8080
+   ```
+   Найди PID процесса и убей его с помощью `fchek process kill <pid>`.
+
+2. **Проверить запуск сервера**: после запуска фонового процесса/сервера проверь, слушает ли он порт:
+   ```bash
+   fchek port 3000
+   ```
+   Убедись, что `"in_use": true`.

package/skills/profile.md

@@ -0,0 +1,91 @@
+# skill: fchek profile — профилировщик кода
+
+## Что делает
+
+Запускает код и показывает, какие функции занимают больше всего CPU времени.
+Помогает найти bottleneck без ручного добавления замеров в код.
+
+## Поддерживаемые языки
+
+| Язык | Инструмент | Требование |
+|---|---|---|
+| Python (.py) | py-spy | `pip install py-spy` |
+| Python (fallback) | cProfile | встроен в Python |
+| C/C++ (.c .cpp) | valgrind callgrind | `apt install valgrind` (Linux only) |
+
+## Синтаксис
+
+```bash
+fchek profile <file> [app|web] [--timeout=<ms>]
+```
+
+- `app` — запуск как standalone (по умолчанию)
+- `web` — Python web-режим
+- `--timeout=30000` — максимальное время ожидания (мс), по умолчанию 60000
+
+## Вывод JSON
+
+```json
+{
+  "status": "ok",
+  "command": "profile",
+  "data": {
+    "file": "/path/to/main.py",
+    "lang": "python",
+    "mode": "app",
+    "tool": "cProfile",
+    "timeout_ms": 60000,
+    "top_functions": [
+      { "ncalls": 1000, "tottime": 0.42, "cumtime": 1.3, "location": "utils.py:15(process)" }
+    ],
+    "raw_summary": "...",
+    "stderr": null
+  }
+}
+```
+
+## Как AI должен использовать это
+
+### Сценарий: "Код медленный, не знаю где"
+
+```bash
+# 1. Запусти профилировщик
+fchek profile slow_script.py
+
+# 2. Разбери JSON — найди top_functions с наибольшим cumtime
+# 3. Перейди к самой медленной функции через goto
+fchek goto slow_script.py:15
+```
+
+### Алгоритм принятия решений
+
+```
+ЕСЛИ lang=python:
+  ЕСЛИ py-spy доступен → используй его (данные точнее)
+  ИНАЧЕ → cProfile (fallback, всегда работает)
+
+ЕСЛИ lang=c/cpp:
+  ЕСЛИ Linux → valgrind callgrind
+  ИНАЧЕ → сообщи пользователю об ограничении платформы
+```
+
+### Как читать top_functions
+
+- `cumtime` — суммарное время включая вызовы дочерних функций → ищи здесь bottleneck
+- `tottime` — только время самой функции → ищи здесь горячий код
+- `ncalls` — число вызовов → если высокое + tottime большое → оптимизируй саму функцию
+
+## Частые ошибки и решения
+
+| Ошибка | Решение |
+|---|---|
+| `File not found` | Проверь путь к файлу |
+| `timed out` | Код зависает или слишком долго выполняется — проверь на бесконечный цикл |
+| `valgrind not found` | Linux: `apt install valgrind`; macOS/Windows: используй WSL |
+| `py-spy needs elevated permissions` | Запусти с sudo (Linux) или используй fallback cProfile |
+
+## Платформенные ограничения
+
+- `valgrind` — только Linux. На macOS не работает с 10.15+. На Windows — WSL.
+- `py-spy` — работает везде, но на Linux требует sudo или ptrace прав.
+- `cProfile` — встроен в Python, работает везде без sudo.

package/skills/race.md

@@ -0,0 +1,117 @@
+# skill: fchek race — sanitizers и гонки данных
+
+## Что делает
+
+Компилирует C/C++ код с активированными sanitizers и запускает его.
+Sanitizers встроены в компилятор (gcc/clang) — они инструментируют код во время компиляции
+и сообщают о проблемах в рантайме.
+
+## Поддерживаемые sanitizers
+
+| Флаг | Название | Что ловит |
+|---|---|---|
+| `--tsan` | ThreadSanitizer | Гонки данных (data races) между потоками |
+| `--asan` | AddressSanitizer | Buffer overflow, use-after-free, утечки памяти |
+| `--ubsan` | UndefinedBehaviorSanitizer | Integer overflow, null deref, misalignment |
+| `--all` | Все три | Запускает все последовательно |
+
+## Синтаксис
+
+```bash
+fchek race <file.cpp> [--tsan | --asan | --ubsan | --all]
+```
+
+По умолчанию (без флага): `--tsan`
+
+## Вывод JSON
+
+```json
+{
+  "status": "ok",
+  "command": "race",
+  "data": {
+    "file": "/path/to/threaded.cpp",
+    "build_system": "single",
+    "compiler": "g++",
+    "timeout_ms": 30000,
+    "sanitizers": [
+      {
+        "sanitizer": "ThreadSanitizer",
+        "compiled": true,
+        "timed_out": false,
+        "issues": [
+          {
+            "sanitizer": "ThreadSanitizer",
+            "headline": "ERROR: ThreadSanitizer: data race at 0x...",
+            "stack": ["#0 worker() threaded.cpp:42", "#1 ..."]
+          }
+        ],
+        "raw_output": "..."
+      }
+    ],
+    "summary": {
+      "total_issues": 1,
+      "verdict": "issues_found"
+    }
+  }
+}
+```
+
+`verdict`: `"clean"` или `"issues_found"`
+
+## Как AI должен использовать это
+
+### Сценарий: "Многопоточный код, подозрение на race condition"
+
+```bash
+# 1. Проверь на гонки данных
+fchek race threaded.cpp --tsan
+
+# 2. Разбери JSON — смотри summary.verdict
+# 3. Если verdict = "issues_found" → читай issues[].headline и issues[].stack
+# 4. Найди файл:строку в stack trace → перейди через goto
+fchek goto threaded.cpp:42
+```
+
+### Сценарий: "Подозрение на утечку памяти"
+
+```bash
+fchek race memory.cpp --asan
+# Смотри issues с "heap-use-after-free" или "LeakSanitizer"
+```
+
+### Алгоритм принятия решений
+
+```
+ЕСЛИ подозреваешь гонку данных (два потока пишут одну переменную):
+  → fchek race file.cpp --tsan
+
+ЕСЛИ подозреваешь утечку / выход за границы массива:
+  → fchek race file.cpp --asan
+
+ЕСЛИ не уверен что именно:
+  → fchek race file.cpp --all
+```
+
+## Платформенные ограничения
+
+- **Linux** — полная поддержка (gcc + clang)
+- **macOS** — только clang (Apple clang поддерживает -fsanitize). Valgrind не работает.
+- **Windows** — sanitizers **не работают** с MinGW/MSVC. Используй WSL.
+
+Если `fchek doctor` показывает `"win32"` → предупреди пользователя что нужен WSL.
+
+## Многофайловые проекты
+
+Текущая версия компилирует один файл. Если проект использует CMake или Makefile,
+компилируй весь проект вручную с флагами sanitizer и передай итоговый бинарь.
+`build_system` в выводе показывает что было найдено в родительских директориях.
+
+## Частые ошибки и решения
+
+| Ошибка | Решение |
+|---|---|
+| `compiled: false` | Ошибка компиляции — смотри поле `error` |
+| `timed_out: true` | Код завис — проверь на бесконечный цикл |
+| Нет вывода sanitizer | Проблем не обнаружено или код не выполняет нужный путь |
+| ThreadSanitizer + AddressSanitizer вместе | Нельзя комбинировать, запускай раздельно |

package/skills/repl.md

@@ -0,0 +1,81 @@
+# skill: fchek repl — интерактивный REPL
+
+## Что делает
+
+Запускает интерактивный режим где процесс остаётся живым между командами.
+Все команды fchek доступны внутри REPL без перезапуска.
+
+**Отличие от state:**
+- `repl`  = in-memory → переменные живут только пока REPL запущен
+- `state` = disk → данные живут между запусками процесса
+
+Используй REPL для быстрой итерации в одной сессии.
+Используй state для сохранения контекста между сессиями.
+
+## Запуск
+
+```bash
+fchek repl
+```
+
+## Команды внутри REPL
+
+```
+fchek> profile <file> [app|web]       # профилировать
+fchek> race <file.cpp> [--asan]       # sanitizers
+fchek> goto <file:line>               # LSP навигация
+fchek> state <action> [key] [val]     # дисковое состояние
+fchek> set <key> <value>              # session-переменная (только память)
+fchek> get <key>                      # читать session-переменную
+fchek> vars                           # список всех session-переменных
+fchek> clear                          # очистить экран
+fchek> help                           # справка
+fchek> exit                           # выйти
+```
+
+## Вывод
+
+Каждая команда выводит JSON — тот же формат что и CLI.
+
+```
+fchek> set task "profile the auth module"
+{"status":"ok","command":"repl","data":{"set":"task","value":"profile the auth module"}}
+
+fchek> profile src/auth.py
+{"status":"ok","command":"profile","data":{"file":"/project/src/auth.py",...}}
+```
+
+## Как AI должен использовать это
+
+### Сценарий: "Хочу быстро проверить несколько файлов"
+
+```
+fchek> profile src/auth.py
+# → смотрю top_functions
+fchek> goto src/auth.py:42
+# → нахожу определение медленной функции
+fchek> set bottleneck "auth.py:42 process_token()"
+fchek> race src/auth.cpp --asan
+# → проверяю на утечки
+```
+
+### Session-переменные vs State
+
+```
+# Временно в сессии (исчезнет при exit):
+fchek> set draft "trying approach X"
+
+# Надолго (переживёт перезапуск):
+fchek> state set approach "trying approach X"
+```
+
+### Автодополнение
+
+REPL поддерживает Tab для автодополнения команд.
+История команд — стрелки вверх/вниз (последние 100 команд).
+
+## Ограничения
+
+- Session-переменные (`set`/`get`) живут только в рамках одного запуска REPL
+- Параллельный запуск нескольких REPL-сессий не синхронизирован — каждая независима
+- Для долгосрочной памяти всегда используй `state`, не `set`

package/skills/rules.md

@@ -0,0 +1,318 @@
+# rules.md — Жёсткие правила для агента
+
+Каждое правило здесь — это ЗАПРЕТ или ТРЕБОВАНИЕ.
+Нарушение = ошибка агента, даже если код "выглядит правильно".
+
+---
+
+## ПРАВИЛО 1 — Нельзя говорить «готово» без fchek run exit_code=0
+
+### ЗАПРЕЩЕНО:
+```
+User: Исправь функцию parse_data()
+AI:   Я переписал функцию. Теперь она корректно обрабатывает edge cases. Готово.
+```
+
+### ОБЯЗАТЕЛЬНО:
+```bash
+fchek run src/parser.py
+```
+```json
+{
+  "status": "ok",
+  "data": {
+    "exit_code": 0,
+    "success": true,
+    "stdout": "parsed 42 items\n",
+    "stderr": ""
+  }
+}
+```
+Только если `exit_code: 0` И `success: true` — разрешено говорить «работает» / «готово».
+
+**Единственное исключение:** код это черновик, явно помечен как «набросок» или «псевдокод».
+
+---
+
+## ПРАВИЛО 2 — Нельзя говорить «тесты проходят» без fchek test verdict=all_passed
+
+### ЗАПРЕЩЕНО:
+```
+AI: Я обновил код. Все тесты проходят.
+```
+
+### ОБЯЗАТЕЛЬНО:
+```bash
+fchek test .
+```
+```json
+{
+  "status": "ok",
+  "data": {
+    "verdict": "all_passed",
+    "passed": 14,
+    "failed": 0,
+    "skipped": 0
+  }
+}
+```
+Только `verdict: "all_passed"` И `failed: 0` → разрешено говорить «тесты проходят».
+
+Если `verdict: "failures_found"` — читай `failures[].test` и `failures[].reason`, исправь, запусти снова.
+
+---
+
+## ПРАВИЛО 3 — Нельзя создавать символ без проверки fchek context
+
+### ЗАПРЕЩЕНО:
+```python
+# Сразу писать код
+class UserRepository:
+    def save(self, user): ...
+```
+
+### ОБЯЗАТЕЛЬНО:
+```bash
+fchek context src/ --names-only
+```
+```json
+{
+  "status": "ok",
+  "data": {
+    "name_index": {
+      "UserRepository": [{"file": "src/repos/user.py", "line": 12}],
+      "save": [{"file": "src/repos/base.py", "line": 45}]
+    },
+    "duplicates": []
+  }
+}
+```
+Читай `name_index`. Если нужное имя там есть:
+- Используй существующее
+- Или выбери другое имя
+- Или уточни у пользователя
+
+Нельзя создавать дубликат класса/функции не спросив.
+
+---
+
+## ПРАВИЛО 4 — Нельзя использовать библиотеку без fchek deps-check
+
+### ЗАПРЕЩЕНО:
+```javascript
+// Писать на основе памяти о библиотеке
+const result = await axios.get(url, { validateStatus: false });
+```
+
+### ОБЯЗАТЕЛЬНО:
+```bash
+fchek deps-check axios --lang=js
+```
+```json
+{
+  "status": "ok",
+  "data": {
+    "package": "axios",
+    "installed_version": "0.27.2",
+    "latest_version": "1.6.0",
+    "installed_deprecated": null,
+    "deprecation_notices": ["validateStatus option deprecated in 1.x — use axios.isAxiosError()"]
+  }
+}
+```
+Читай:
+- `installed_version` vs `latest_version` — несоответствие? Уведомь пользователя
+- `installed_deprecated` — если не null, библиотека устарела, предложи альтернативу
+- `deprecation_notices[]` — используй актуальный API
+
+---
+
+## ПРАВИЛО 5 — Нельзя коммитить с секретами (fchek secrets verdict=clean)
+
+### ЗАПРЕЩЕНО:
+```bash
+# Коммитить файл с захардкоженными секретами
+fchek git commit "feat: add database connection"
+# (файл содержит: DB_URL = "postgresql://admin:Secret123@...")
+```
+
+### ОБЯЗАТЕЛЬНО:
+```bash
+fchek secrets .
+```
+```json
+{
+  "status": "ok",
+  "data": {
+    "verdict": "clean",
+    "total_findings": 0,
+    "summary": {"critical": 0, "high": 0, "other": 0}
+  }
+}
+```
+
+Если `verdict ≠ "clean"`:
+1. Читай `findings[].file` и `findings[].line`
+2. Замени на переменные окружения
+3. Запусти снова → получи `verdict: "clean"`
+4. Только после этого коммить
+
+Ни при каких условиях не коммитить код с `verdict: "critical"`.
+
+---
+
+## ПРАВИЛО 6 — Нельзя коммитить с failing tests
+
+### ЗАПРЕЩЕНО:
+```bash
+fchek test .
+# → verdict: "failures_found", failed: 2
+
+fchek git commit "feat: add feature X"
+# ❌ Два теста падают, коммитить нельзя
+```
+
+### ОБЯЗАТЕЛЬНО:
+```bash
+fchek test .
+# → verdict: "all_passed", failed: 0
+
+fchek git commit "feat: add feature X"
+# ✓ Все тесты зелёные — коммитить можно
+```
+
+---
+
+## ПРАВИЛО 7 — Нельзя пушить — это решение человека
+
+### ЗАПРЕЩЕНО:
+```bash
+fchek git push origin main
+```
+
+### ОБЯЗАТЕЛЬНО:
+Никогда не выполняй `git push`. Остановись на коммите.
+
+Доклад должен заканчиваться на:
+```
+Коммит: feat: implement feature X (a3f9c2d)
+
+Для отправки в remote выполни:
+  git push origin feat/feature-x
+```
+
+Решение пушить принимает только человек.
+
+---
+
+## ПРАВИЛО 8 — Нельзя удалять файлы без явного указания
+
+### ЗАПРЕЩЕНО:
+```
+User: Рефактор проекта — убери дублирование
+AI:   [удаляет src/old_api.py потому что выглядит как legacy]
+```
+
+### ОБЯЗАТЕЛЬНО:
+Удаление файла требует явного указания в задаче:
+- «удали файл X»
+- «почисти старые модули: X, Y, Z»
+- «убери всё что связано с feature_flag_X»
+
+Если задача неявная — спроси:
+```
+Нашёл old_api.py который выглядит как legacy код.
+Удалить его? (14 ссылок в других файлах)
+```
+
+---
+
+## Примеры правильных диалогов
+
+### ✅ Правило 1 + 2: перед «готово» показывай вывод
+
+```
+User: Исправь баг в calculate_tax()
+AI:   [исправляет код]
+      
+      fchek run src/pricing.py
+      → exit_code: 0
+      
+      fchek test .
+      → verdict: all_passed (12 passed)
+      
+      Исправил баг. Тесты проходят.
+```
+
+---
+
+### ✅ Правило 3: проверь name_index перед созданием
+
+```
+User: Добавь класс EmailValidator
+AI:   fchek context src/ --names-only
+      → name_index содержит EmailValidator в src/validators.py:34
+      
+      Класс EmailValidator уже существует.
+      Использовать существующий или нужен новый с другой логикой?
+```
+
+---
+
+### ✅ Правило 4: проверь библиотеку перед использованием
+
+```
+User: Добавь отправку email через sendgrid
+AI:   fchek deps-check sendgrid --lang=python
+      → installed_version: 6.9.0, latest_version: 6.11.0
+      → deprecation_notices: ["send() метод deprecated — используй send_mail()"]
+      
+      Установленная версия sendgrid (6.9.0) устарела.
+      Обновить до 6.11.0? API send() заменён на send_mail().
+```
+
+---
+
+### ✅ Правило 5: проверь секреты перед коммитом
+
+```
+User: Добавь подключение к Stripe API
+AI:   [пишет код с переменной окружения]
+      
+      fchek secrets .
+      → verdict: clean
+      
+      Добавил подключение к Stripe через STRIPE_SECRET_KEY env var.
+      
+      fchek git commit "feat: integrate Stripe payment"
+```
+
+---
+
+### ✅ Правило 7: не пушить без разрешения
+
+```
+AI:   Коммит: feat: add user authentication (a3f9c2d)
+      
+      Для отправки в remote выполни:
+        git push origin feat/auth
+      
+      [НЕ выполняется git push автоматически]
+```
+
+---
+
+## Матрица строгости правил
+
+| Правило | Нарушение = блокер | Можно отложить? | Исключения |
+|---|---|---|---|
+| 1. fchek run | Да | Нет | Черновики |
+| 2. fchek test | Да | Нет | Нет |
+| 3. fchek context | Да | Нет | Новый проект без файлов |
+| 4. fchek deps-check | Нет (warning) | Да | Stdlib |
+| 5. fchek secrets | Да | Нет | Нет |
+| 6. no failing tests | Да | Нет | Нет |
+| 7. no git push | Да | Нет | Нет |
+| 8. no file delete | Да | Нет | Явно указано в задаче |
+
+Правила 1, 2, 5, 6, 7, 8 — абсолютные. Нарушение блокирует завершение задачи.