@kirrosh/apitool 0.4.3

package/docs/archive/BACKLOG-AI-NATIVE.md

@@ -0,0 +1,56 @@
+# BACKLOG — AI-Native API Testing Strategy (Archived)
+
+> Archived: all milestones M22-M27 completed. See BACKLOG.md for current backlog.
+
+---
+
+## M22: MCP-First Smart Test Generation ✅ DONE
+
+- `generate_tests_guide` tool — полная API-спека + алгоритм генерации + YAML format reference
+- `save_test_suite` tool — парсит YAML, валидирует через Zod, сохраняет
+- `explore_api` enhanced — `includeSchemas: true` → request/response schemas
+- `schema-utils.ts` — `compressSchema()`, `formatParam()`
+- Удалён `list_environments` (дубликат `manage_environment`)
+
+## M23: Runner Improvements + MCP Refinements ✅ DONE
+
+- Nested body assertions — `flattenBodyAssertions` preprocessor
+- Root body assertions (`_body`) — `_body: { type: "array" }`, `_body.length: { gt: 0 }`
+- `setup_api` MCP tool
+- `generate_missing_tests` MCP tool
+- Исправлен `z.record()` баг (MCP SDK 1.27.1)
+- int64 workaround документирован
+
+## M24: Tags + Description Support ✅ DONE
+
+- `tags: string[]` и `description: string` в TestSuite
+- `filterSuitesByTags()` — OR logic, case-insensitive
+- CLI `--tag` флаг (repeatable, comma-separated)
+- MCP `run_tests` — параметр `tag: string[]`
+- Console reporter — отображение тегов
+
+## M25: MCP + CLI Cleanup ✅ DONE
+
+- `query_db` — consolidated 4 tools into 1 (list_collections, list_runs, get_run_results, diagnose_failure)
+- Deleted dead code (`list-environments.ts`)
+- Removed `request` CLI command
+
+## M26: WebUI Simplification ✅ DONE
+
+- Single-page dashboard: collection selector → env → Run Tests → results + coverage + history
+- Removed 8 routes, extracted shared views
+- JUnit XML + JSON export buttons
+
+## M27: CI/CD Integration (partial) ✅ DONE
+
+- `apitool ci init` CLI command (GitHub Actions, GitLab CI)
+- `ci_init` MCP tool with `dir` param
+- Templates: permissions, continue-on-error, publish-unit-test-result-action, repository_dispatch
+- Agent hints: run_tests, save_test_suite, generate_tests_guide suggest CI after tests pass
+- `docs/ci.md` — guide with triggers, secrets, examples
+
+---
+
+## Стратегия и принципы
+
+Перенесены в APITOOL.md.

package/docs/archive/M1-M2-parser-runner.md

@@ -0,0 +1,216 @@
+> **Исторический snapshot** на момент реализации M1+M2. Актуальная документация — [APITOOL.md](../../APITOOL.md)
+
+# M1: Parser + M2: Runner
+
+Модули парсинга YAML-тестов и их выполнения.
+
+## Быстрый старт
+
+```bash
+bun add zod
+bun test
+```
+
+Программный запуск:
+
+```typescript
+import { parseFile } from "./src/core/parser/index.ts";
+import { runSuite } from "./src/core/runner/index.ts";
+
+const suite = await parseFile("examples/jsonplaceholder.yaml");
+const result = await runSuite(suite);
+
+console.log(`${result.passed}/${result.total} passed`);
+```
+
+## YAML-формат тестов
+
+### Минимальный пример
+
+```yaml
+name: Health Check
+tests:
+  - name: "API is alive"
+    GET: /health
+    expect:
+      status: 200
+```
+
+### Полный пример (CRUD-цепочка с captures)
+
+```yaml
+name: Users CRUD
+base_url: "{{base}}"
+headers:
+  Authorization: "Bearer {{token}}"
+  Content-Type: application/json
+
+config:
+  timeout: 10000
+  retries: 1
+  retry_delay: 1000
+
+tests:
+  - name: "Create user"
+    POST: /users
+    json:
+      name: "{{$randomName}}"
+      email: "{{$randomEmail}}"
+    expect:
+      status: 201
+      body:
+        id: { capture: user_id, type: integer }
+        name: { type: string }
+      duration: 2000
+
+  - name: "Get created user"
+    GET: /users/{{user_id}}
+    expect:
+      status: 200
+      body:
+        id: { equals: "{{user_id}}" }
+
+  - name: "Delete user"
+    DELETE: /users/{{user_id}}
+    expect:
+      status: 204
+```
+
+### Формат шагов
+
+HTTP-метод указывается как ключ: `GET: /path`, `POST: /path`, `PUT:`, `PATCH:`, `DELETE:`.
+
+| Поле | Тип | Описание |
+|------|-----|----------|
+| `name` | string | Название шага (обязательное) |
+| `GET/POST/PUT/PATCH/DELETE` | string | HTTP-метод + путь (обязательное) |
+| `headers` | Record | Заголовки запроса |
+| `json` | any | JSON-тело (auto Content-Type: application/json) |
+| `form` | Record | Form-urlencoded тело |
+| `query` | Record | Query-параметры |
+| `expect` | object | Блок assertions |
+
+### Assertions (блок expect)
+
+| Поле | Описание |
+|------|----------|
+| `status` | Ожидаемый HTTP-код (exact match) |
+| `duration` | Максимальное время ответа в мс |
+| `headers` | Проверка заголовков ответа (exact match) |
+| `body` | Проверка полей JSON-ответа по dot-path |
+
+### Assertion rules (правила для body-полей)
+
+```yaml
+body:
+  id: { type: integer }              # проверка типа
+  name: { equals: "John" }           # точное совпадение
+  email: { matches: ".+@.+" }        # regex
+  bio: { contains: "developer" }     # подстрока
+  age: { gt: 18, lt: 100 }           # числовые сравнения
+  avatar: { exists: true }           # поле существует
+  id: { capture: user_id }           # сохранить в переменную
+```
+
+Поддерживаемые типы: `string`, `integer`, `number`, `boolean`, `array`, `object`.
+
+Вложенные поля через dot-path: `data.user.name`, `items.0.id`.
+
+### Переменные
+
+Синтаксис: `{{variable_name}}`
+
+Источники значений (приоритет):
+1. CLI-флаги (`--auth-token` → `auth_token`)
+2. Environment (из `.env.yaml` или программно)
+3. Captures из предыдущих шагов
+4. Встроенные генераторы (с префиксом `$`)
+
+### Встроенные генераторы
+
+| Генератор | Пример | Тип |
+|-----------|--------|-----|
+| `{{$uuid}}` | `550e8400-e29b-41d4-a716-446655440000` | string |
+| `{{$timestamp}}` | `1708876800` | number |
+| `{{$randomName}}` | `John Smith` | string |
+| `{{$randomEmail}}` | `xk92m@test.com` | string |
+| `{{$randomInt}}` | `4217` | number |
+| `{{$randomString}}` | `aBcDeFgH` | string |
+
+### Config
+
+```yaml
+config:
+  timeout: 30000        # мс, таймаут запроса (default: 30000)
+  retries: 0            # повторы при сетевой ошибке (default: 0)
+  retry_delay: 1000     # задержка между повторами (default: 1000)
+  follow_redirects: true
+  verify_ssl: true
+```
+
+Retry срабатывает только на сетевые ошибки (fetch throws). HTTP 4xx/5xx — валидные ответы для assertions.
+
+## Архитектура
+
+### Parser (src/core/parser/)
+
+```
+parseFile("test.yaml") → Bun.file() → Bun.YAML.parse() → Zod validate → TestSuite
+```
+
+- `types.ts` — интерфейсы TypeScript
+- `schema.ts` — Zod-схемы, method-as-key transform (`POST: /path` → `{method, path}`)
+- `variables.ts` — подстановка `{{var}}`, генераторы, загрузка `.env.yaml`
+- `yaml-parser.ts` — чтение файлов/директорий
+
+### Runner (src/core/runner/)
+
+```
+runSuite(suite, env) → для каждого step: substitute → fetch → captures → assertions → StepResult
+```
+
+- `http-client.ts` — fetch-обёртка с timeout (AbortController) и retry
+- `assertions.ts` — проверка всех assertion rules + извлечение captures
+- `executor.ts` — оркестратор: sequential steps, capture propagation, skip logic
+
+### Логика выполнения
+
+1. Для каждого шага проверяется, не зависит ли он от failed capture → skip
+2. Подстановка переменных (env + captures) в path, headers, body, query
+3. HTTP-запрос через fetch с timeout/retry
+4. Извлечение captures из ответа
+5. Проверка assertions
+6. Если step failed/error — его captures помечаются как failed
+
+Suites выполняются параллельно (`Promise.all`), steps внутри suite — последовательно (из-за captures).
+
+## Environment файлы
+
+```yaml
+# .env.yaml (по умолчанию)
+base: http://localhost:3000/api
+token: dev-token-123
+```
+
+Загрузка:
+
+```typescript
+import { loadEnvironment } from "./src/core/parser/index.ts";
+
+const env = await loadEnvironment();           // .env.yaml
+const env = await loadEnvironment("staging");  // .env.staging.yaml
+```
+
+## Зависимости
+
+- **zod** — валидация YAML-схемы
+- Всё остальное — Bun built-in: `Bun.YAML`, `Bun.Glob`, `Bun.file()`, `Bun.sleep()`, native `fetch`
+
+## Тесты
+
+```bash
+bun test                    # все тесты (100 tests)
+bun test tests/parser/      # только парсер (43 tests)
+bun test tests/runner/      # только раннер (55 tests)
+bun test tests/integration/ # интеграционные (2 tests, real HTTP)
+```

package/docs/archive/M4-M7-reporter-cli.md

@@ -0,0 +1,179 @@
+> **Исторический snapshot** на момент реализации M4+M7. Актуальная документация — [APITOOL.md](../../APITOOL.md)
+
+# M4: Reporter + M7: CLI (базовый)
+
+Модули вывода результатов и командной строки.
+
+## Быстрый старт
+
+```bash
+# Запуск тестов
+bun src/cli/index.ts run examples/jsonplaceholder.yaml
+
+# Валидация YAML без запуска
+bun src/cli/index.ts validate examples/jsonplaceholder.yaml
+
+# JSON-вывод
+bun src/cli/index.ts run tests/ --report json
+
+# Помощь
+bun src/cli/index.ts --help
+```
+
+## CLI-команды
+
+### `run <path>`
+
+Запуск API-тестов. Принимает файл `.yaml` или директорию.
+
+```bash
+bun src/cli/index.ts run tests/api.yaml
+bun src/cli/index.ts run tests/              # все YAML в директории
+bun src/cli/index.ts run tests/ --env staging --report json --timeout 5000 --bail
+
+# Auth-токен из внешнего источника (Keycloak, CI/CD)
+TOKEN=$(curl -s -X POST https://keycloak/token -d 'grant_type=...' | jq -r .access_token)
+bun src/cli/index.ts run tests/ --auth-token "$TOKEN"
+```
+
+| Флаг | Описание | По умолчанию |
+|------|----------|-------------|
+| `--env <name>` | Файл окружения `.env.<name>.yaml` | `.env.yaml` |
+| `--report <format>` | Формат вывода: `console`, `json`, `junit` | `console` |
+| `--timeout <ms>` | Таймаут запроса (мс) | `30000` |
+| `--bail` | Остановиться после первого упавшего suite | `false` |
+| `--auth-token <token>` | Auth-токен, доступен как `{{auth_token}}` | — |
+
+Exit codes:
+- `0` — все тесты прошли
+- `1` — есть упавшие тесты
+- `2` — ошибка конфигурации (невалидный YAML, неверные аргументы)
+
+### `validate <path>`
+
+Проверка YAML-тестов без HTTP-запросов.
+
+```bash
+bun src/cli/index.ts validate tests/api.yaml
+# OK: 1 suite(s), 4 test(s) validated successfully
+
+bun src/cli/index.ts validate tests/broken.yaml
+# Error: Validation error in tests/broken.yaml: ...
+```
+
+Exit codes: `0` — валидно, `2` — ошибка.
+
+## Reporter
+
+### Console Reporter
+
+Цветной вывод в терминал (ANSI). Цвета отключаются автоматически при перенаправлении в файл.
+
+```
+ Users CRUD
+  ✓ Create user (450ms)
+  ✓ Get user (120ms)
+  ✗ Update user (310ms)
+    status: expected equals 200 but got 500
+  ○ Verify deleted (skipped)
+
+Results: 2 passed, 1 failed, 1 skipped (1.2s)
+```
+
+Для нескольких suites выводится итого:
+
+```
+Total: 5 passed, 1 failed (2.3s)
+```
+
+### JSON Reporter
+
+Сериализация `TestRunResult[]` в stdout. Для записи в файл:
+
+```bash
+bun src/cli/index.ts run tests/ --report json > results.json
+```
+
+## Программное использование
+
+```typescript
+import { getReporter } from "./src/core/reporter/index.ts";
+import { parseFile } from "./src/core/parser/index.ts";
+import { runSuite } from "./src/core/runner/index.ts";
+
+const suite = await parseFile("tests/api.yaml");
+const result = await runSuite(suite);
+
+// Console-вывод
+const reporter = getReporter("console");
+reporter.report([result]);
+
+// JSON-вывод
+const jsonReporter = getReporter("json");
+jsonReporter.report([result]);
+```
+
+### Форматирующие функции (экспортируются для кастомизации)
+
+```typescript
+import {
+  formatDuration,     // (ms: number) => "450ms" | "1.2s" | "2m 5s"
+  formatStep,         // (step: StepResult, color: boolean) => string
+  formatFailures,     // (step: StepResult, color: boolean) => string
+  formatSuiteResult,  // (result: TestRunResult, color: boolean) => string
+  formatGrandTotal,   // (results: TestRunResult[], color: boolean) => string
+} from "./src/core/reporter/index.ts";
+```
+
+## Архитектура
+
+### Reporter (src/core/reporter/)
+
+```
+TestRunResult[] → getReporter("console" | "json") → report(results) → stdout
+```
+
+- `types.ts` — интерфейсы Reporter, ReporterOptions, ReporterName
+- `console.ts` — ANSI-форматирование, `✓`/`✗`/`○`, duration, assertion details
+- `json.ts` — `JSON.stringify(results, null, 2)`
+- `index.ts` — barrel export + `getReporter()` factory
+
+### CLI (src/cli/)
+
+```
+process.argv → parseArgs() → command routing → run/validate → process.exitCode
+```
+
+- `index.ts` — entry point, парсинг argv, роутинг команд
+- `output.ts` — ANSI-утилиты: `printError`, `printSuccess`, `printWarning`
+- `commands/run.ts` — pipeline: `parse() → loadEnvironment() → runSuites() → report()`
+- `commands/validate.ts` — `parse()` → OK / error
+
+### Pipeline команды `run`
+
+1. `parse(path)` — файл или директория → `TestSuite[]`
+2. `loadEnvironment(env, dir)` — загрузка `.env.yaml`
+3. `--auth-token` → инъекция `auth_token` в env (перезаписывает значение из файла)
+4. `--timeout` override → мутация `suite.config.timeout`
+5. `runSuites()` или sequential с `--bail`
+6. `reporter.report(results)`
+7. Exit code по результатам
+
+### Bail mode
+
+При `--bail` suites запускаются последовательно. Если suite содержит `failed > 0` или `error`, последующие suites пропускаются.
+
+## Зависимости
+
+Новых зависимостей нет. Используются:
+- Bun built-in: `process.argv`, `process.exitCode`, `console.log`
+- Node compat: `path.dirname`
+- Существующие модули: Parser, Runner
+
+## Тесты
+
+```bash
+bun test tests/reporter/    # reporter (25 tests)
+bun test tests/cli/         # CLI (18 tests)
+bun test                    # все unit-тесты
+```