code-ai-installer 1.3.1 → 1.4.0

package/.agents/skills/architecture_compliance_review/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: architecture_compliance_review
+description: Проверка соответствия кода архитектуре/ADR — границы модулей, слои, зависимости, конвенции, red flags.
+---
+
+# Skill: Architecture Compliance Review
+
+Ревью на соответствие архитектурному документу и ADR.
+
+**Разделы:**
+1. [Expected Architecture](#1-expected)
+2. [Checklist](#2-checklist)
+3. [Automated Detection](#3-detection)
+4. [Red Flags](#4-red-flags)
+5. [Output Template](#5-output)
+
+---
+
+## 1. Expected Architecture
+
+### Layer Architecture (Node.js / Express)
+
+```
+┌──────────────────────────┐
+│        Routes            │  ← HTTP routing only, no logic
+├──────────────────────────┤
+│      Middleware           │  ← Auth, validation (Zod), logging
+├──────────────────────────┤
+│      Controllers          │  ← Request/response handling, HTTP concerns
+├──────────────────────────┤
+│       Services            │  ← Business logic, orchestration
+├──────────────────────────┤
+│     Repositories          │  ← Data access (Mongoose), queries
+├──────────────────────────┤
+│        Models             │  ← Schema definitions
+└──────────────────────────┘
+```
+
+### Dependency rules
+
+| Layer | Can depend on | MUST NOT depend on |
+|-------|--------------|-------------------|
+| Routes | Controllers, Middleware | Services, Repos, Models |
+| Middleware | (standalone) | Services, Repos |
+| Controllers | Services | Repos, Models directly |
+| Services | Repos, other Services | `req`, `res`, HTTP concerns |
+| Repos | Models | `req`, `res`, `next`, Services |
+| Models | (standalone) | Anything above |
+
+### Frontend Architecture (React)
+
+```
+┌──────────────────────────┐
+│        Pages              │  ← Route-level components
+├──────────────────────────┤
+│      Components           │  ← UI building blocks (presentational)
+├──────────────────────────┤
+│        Hooks              │  ← State/logic encapsulation
+├──────────────────────────┤
+│       Services/API        │  ← HTTP calls to backend
+├──────────────────────────┤
+│        Store              │  ← Global state (Zustand/RTK)
+└──────────────────────────┘
+```
+
+---
+
+## 2. Checklist
+
+### 2.1 Layer Boundaries
+
+| # | Check | Severity | Status |
+|---|-------|----------|--------|
+| ARCH-01 | No DB calls (Mongoose) in routes or controllers | 🔴 P0 | ☐ |
+| ARCH-02 | No `req`/`res` objects in services | 🔴 P0 | ☐ |
+| ARCH-03 | No business logic in routes (only routing) | 🟠 P1 | ☐ |
+| ARCH-04 | Controllers delegate to services (no direct repo calls) | 🟠 P1 | ☐ |
+| ARCH-05 | Models are standalone (no imports from layers above) | 🟠 P1 | ☐ |
+
+### 2.2 Module Boundaries
+
+| # | Check | Severity | Status |
+|---|-------|----------|--------|
+| ARCH-06 | Service A doesn't import internals of Service B | 🟠 P1 | ☐ |
+| ARCH-07 | No circular dependencies between modules | 🔴 P0 | ☐ |
+| ARCH-08 | Shared code is in `utils/` or `common/`, not copy-pasted | 🟠 P1 | ☐ |
+| ARCH-09 | Feature modules have clear public API (index exports) | 🟡 P2 | ☐ |
+
+### 2.3 Code Size & Complexity
+
+| # | Check | Severity | Status |
+|---|-------|----------|--------|
+| ARCH-10 | File < 500 lines (God Object indicator) | 🟠 P1 | ☐ |
+| ARCH-11 | Function < 40 lines (complexity indicator) | 🟠 P1 | ☐ |
+| ARCH-12 | Class/module < 10 public methods | 🟡 P2 | ☐ |
+| ARCH-13 | Cyclomatic complexity reasonable (no deeply nested if/else) | 🟠 P1 | ☐ |
+
+### 2.4 ADR Compliance
+
+| # | Check | Severity | Status |
+|---|-------|----------|--------|
+| ARCH-14 | Code follows existing ADR decisions | 🔴 P0 | ☐ |
+| ARCH-15 | New patterns/libraries → ADR created | 🟠 P1 | ☐ |
+| ARCH-16 | DB schema changes → ADR if significant | 🟠 P1 | ☐ |
+| ARCH-17 | Integration changes → ADR created | 🟠 P1 | ☐ |
+
+### 2.5 Naming Conventions
+
+| # | Check | Severity | Status |
+|---|-------|----------|--------|
+| ARCH-18 | Files follow naming convention (`camelCase.js` or `kebab-case.js`) | 🟡 P2 | ☐ |
+| ARCH-19 | Exports match file purpose (not mixed responsibilities) | 🟠 P1 | ☐ |
+| ARCH-20 | Test files co-located or in `__tests__/` consistently | 🟡 P2 | ☐ |
+
+---
+
+## 3. Automated Detection
+
+### Grep patterns for boundary violations
+
+```bash
+# 🔴 P0: DB in routes/controllers
+grep_search: Query="mongoose"    Includes=["*/routes/*"]       → DB access in routes!
+grep_search: Query="Model.find"  Includes=["*/controllers/*"]  → DB in controller!
+grep_search: Query=".save()"     Includes=["*/routes/*"]       → DB mutation in route!
+
+# 🔴 P0: HTTP in services
+grep_search: Query="req\."  Includes=["*/services/*"]  → HTTP object in service!
+grep_search: Query="res\."  Includes=["*/services/*"]  → HTTP object in service!
+grep_search: Query="next("  Includes=["*/services/*"]  → Express middleware in service!
+
+# 🟠 P1: Cross-module internals
+grep_search: Query="from '\.\./" Includes=["*/services/*"]  → Check: crossing module boundary?
+
+# 🟠 P1: God Object detection
+find_by_name: Pattern="*.js" Extensions=["js","ts"]
+→ Check: file size > 500 lines?
+
+# 🟡 P2: Copy-paste detection
+grep_search: Query="<duplicated code block>"  → Extract to shared util
+```
+
+### File size audit
+
+```bash
+# Find files > 500 lines
+find_by_name: Pattern="*.js" → for each: check line count
+# If file > 500 lines → P1: God Object risk
+# If function > 40 lines → P1: complexity risk
+```
+
+---
+
+## 4. Red Flags
+
+| Red Flag | Pattern | Severity | Indicator |
+|----------|---------|----------|-----------|
+| **Big Ball of Mud** | Everything in one file/folder | 🔴 P0 | File > 1000 lines, no folder structure |
+| **God Object** | One module does everything | 🔴 P0 | Class > 20 methods, file > 500 lines |
+| **Tight Coupling** | Service A depends on internals of B | 🟠 P1 | Deep import paths, circular deps |
+| **Magic** | Implicit side effects, hidden globals | 🟠 P1 | Global state mutation, hidden event listeners |
+| **Layering violation** | DB in routes, HTTP in services | 🔴 P0 | Mongoose in wrong folder |
+| **Missing abstraction** | Same code in 3+ places | 🟠 P1 | Duplicated validation, repeated queries |
+| **Wrong granularity** | Too many tiny files or too few large files | 🟡 P2 | 1-liner utils as separate files |
+
+---
+
+## 5. Output Template
+
+```markdown
+# Architecture Compliance Review
+
+**Scope:** <PR/module>
+**Reviewer:** Reviewer Agent
+**Date:** YYYY-MM-DD
+**Reference:** Architecture Doc, ADR-xxx
+
+## Findings
+
+| # | Severity | Check | File:Line | Finding | Fix |
+|---|----------|-------|-----------|---------|-----|
+| 1 | 🔴 P0 | ARCH-01 | `routes/products.js:25` | `Product.find()` called directly in route | Move to `productService.list()` |
+| 2 | 🟠 P1 | ARCH-10 | `services/config.js` | 620 lines — God Object risk | Split into `configService` + `templateService` |
+| 3 | 🟠 P1 | ARCH-15 | `services/analytics.js` | New analytics module, no ADR | Create ADR for analytics approach |
+
+## Layer Compliance
+| Layer | Files | Violations | Status |
+|-------|:-----:|:----------:|:------:|
+| Routes | 5 | 0 | ✅ |
+| Controllers | 4 | 1 | ⚠️ |
+| Services | 6 | 0 | ✅ |
+| Repos | 3 | 0 | ✅ |
+
+## ADR Compliance
+| ADR | Description | Compliant? |
+|-----|-------------|:----------:|
+| ADR-018 | ImageViewer component | ✅ |
+| ADR-019 | CSS overflow strategy | ✅ |
+| — | New analytics pattern | ❌ ADR needed |
+
+## Verdict
+- ✅ COMPLIANT — architecture fully followed
+- ⚠️ VIOLATIONS — fix P0/P1 before merge
+- ❌ REDESIGN — fundamental architecture mismatch
+```
+
+---
+
+## См. также
+- `$architecture_doc` — Architecture Document (reference)
+- `$adr_log` — ADR Log (reference)
+- `$code_review_checklist` — general review (architecture section)
+- `$current_state_analysis` — initial repo audit

package/.agents/skills/architecture_doc/SKILL.md

@@ -0,0 +1,380 @@
+---
+name: architecture_doc
+description: Архитектурный документ по PRD+UX — модули, потоки, данные, интеграции, ошибки, тестируемость, узкие места, план роста и план реализации.
+---
+
+# Skill: Architecture Document
+
+Полная архитектура системы — от overview до implementation plan.
+
+**Разделы:**
+1. [Входы](#входы)
+2. [Структура документа](#структура) (11 секций)
+3. [Примеры для каждой секции](#примеры)
+4. [Quality Checklist](#quality-checklist)
+5. [Red Flags](#red-flags)
+
+---
+
+## Входы
+
+| Вход | Обязательный | Откуда |
+|------|:---:|--------|
+| PRD | ✅ | Product Manager gate |
+| UX Spec | ✅ | UX/UI Designer gate |
+| Current State Analysis | ⬜ опц. | `$current_state_analysis` |
+| System Design Checklist | ⬜ опц. | `$system_design_checklist` |
+| Ограничения стека/деплоя | ✅ | DevOps / team constraints |
+
+---
+
+## Структура документа
+
+### 1) Overview
+
+```markdown
+## 1. Overview
+
+### What we're building
+<1 абзац: что строим, какую проблему решаем>
+
+### Constraints
+- Stack: React 18 + Vite (FE), Express 4 (BE), MongoDB 7 (DB)
+- Deployment: Docker Compose + Nginx/Caddy
+- Integration: <External platform if any>
+- Timeline: 2 sprints (4 weeks)
+
+### Assumptions
+- Authentication handled via JWT / external provider
+- Single MongoDB instance sufficient for MVP (< 10K users)
+- Admin panel used by team members only (low concurrency)
+```
+
+---
+
+### 2) System Context
+
+```markdown
+## 2. System Context
+
+### Actors
+| Actor | Type | Interaction |
+|-------|------|-------------|
+| Admin | Human | Dashboard: manages settings, content |
+| End User | Human | Public UI: views content, interacts |
+| External Platform | System | Webhooks, OAuth |
+
+### External Integrations
+| System | Protocol | Purpose |
+|--------|----------|---------|
+| External API | HTTPS | Data sync, webhooks |
+| Auth Provider | OAuth 2.0 / JWT | User authentication |
+
+### System Boundary
+Dashboard + API + Public UI = our system.
+External Platform + End User's Browser = external.
+```
+
+---
+
+### 3) High-level Architecture Diagram
+
+```mermaid
+graph TB
+    subgraph "Public (External)"
+        U[End User]
+        PUI[Public UI]
+    end
+
+    subgraph "Our System"
+        subgraph "Gateway (Nginx/Caddy :443)"
+            GW[HTTPS Termination + Routing]
+        end
+        subgraph "Frontend (:3001)"
+            DASH[Admin Dashboard SPA]
+        end
+        subgraph "Backend (:3000)"
+            API[Express API]
+            WH[Webhook Handler]
+        end
+        DB[(MongoDB :27017)]
+    end
+
+    EXT[External Platform]
+
+    U --> PUI
+    PUI -->|GET /api/v1/content/:id| GW
+    DASH -->|REST| GW
+    GW --> API
+    GW --> DASH
+    API --> DB
+    EXT -->|Webhooks| WH
+```
+
+---
+
+### 4) Modules / Components
+
+Для каждого модуля заполни:
+
+```markdown
+## 4. Modules
+
+### 4.1 API Server (Express)
+
+| Аспект | Описание |
+|--------|---------|
+| **Responsibility** | REST API, webhook handling, auth |
+| **NOT responsible for** | UI rendering, static files serving (reverse proxy does this) |
+| **Public API** | See API Contracts doc |
+| **Dependencies** | MongoDB (via Mongoose), External APIs |
+| **Layers** | Router → Controller → Service → Repository |
+| **Test boundary** | Unit: services (mock repos). Integration: repos + DB |
+
+### 4.2 Admin Dashboard (React SPA)
+
+| Аспект | Описание |
+|--------|---------|
+| **Responsibility** | Settings management, content CRUD, preview |
+| **NOT responsible for** | Direct DB access, external API calls |
+| **Public API** | N/A (user-facing UI) |
+| **Dependencies** | API Server (REST) |
+| **State** | Zustand (settings store, content store) |
+| **Test boundary** | Unit: stores, utils. Integration: component render tests |
+
+### 4.3 Public UI (optional)
+
+| Аспект | Описание |
+|--------|---------|
+| **Responsibility** | Fetch config from API, render public-facing content |
+| **NOT responsible for** | Settings management, data persistence |
+| **Dependencies** | API Server (GET /content/:id) |
+| **Test boundary** | Unit: render logic. E2E: browser test |
+```
+
+---
+
+### 5) Flow Mapping
+
+Маппинг UX flow → technical path:
+
+```markdown
+## 5. Flow Mapping
+
+### Flow: Admin saves settings
+
+| Step | UX | Frontend | API | Service | Repository | DB |
+|------|-----|---------|-----|---------|------------|-----|
+| 1 | Click "Save" | `PUT /api/v1/settings/:id` | `settingsRouter` | `configService.update()` | `configRepo.upsert()` | `settings.updateOne()` |
+| 2 | See "Saved!" toast | Response 200 → toast | — | — | — | — |
+| 3 | Preview updates | Re-fetch config | — | — | — | — |
+
+**States:**
+- Loading: spinner on Save button
+- Error: toast "Failed to save" + retry
+- Success: toast "Settings saved" + preview refresh
+
+### Flow: End user views content
+
+| Step | UX | Public UI | API | DB |
+|------|-----|----------------|-----|-----|
+| 1 | Page loads | Public UI bootstrap | — | — |
+| 2 | — | `GET /api/v1/content/:id` | `contentController` | `settings.findOne()` + `items.findOne()` |
+| 3 | Content appears | `renderContent(config)` | — | — |
+| 4 | Click CTA | Execute action | — | — |
+```
+
+---
+
+### 6) Integration Patterns
+
+```markdown
+## 6. Integration Patterns
+
+| Integration | Pattern | Timeout | Retry | Idempotent |
+|------------|---------|---------|-------|------------|
+| Install Webhook | Async POST → process | 10s | No (platform retries) | Yes (upsert) |
+| External API | Sync POST | 5s | 2x with backoff | Yes |
+| Public Content Fetch | Sync GET | 3s | No (fail gracefully) | N/A (read) |
+| Admin REST | Sync CRUD | 5s | No (user retries) | PUT = idempotent |
+```
+
+---
+
+### 7) Error Handling Strategy
+
+```markdown
+## 7. Error Handling
+
+### Error format (API response)
+\`\`\`json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Invalid product name",
+    "details": [{ "field": "name", "message": "Must be 3-100 chars" }]
+  }
+}
+\`\`\`
+
+### Mapping
+| Domain Error | HTTP | Code | UI Message | Log |
+|-------------|------|------|-----------|-----|
+| Validation | 400 | VALIDATION_ERROR | Field-level errors | warn |
+| Not Found | 404 | NOT_FOUND | "Not found" | info |
+| Duplicate | 409 | DUPLICATE | "Already exists" | warn |
+| Auth | 401 | UNAUTHORIZED | "Please log in" | warn |
+| Forbidden | 403 | FORBIDDEN | "Access denied" | warn |
+| Internal | 500 | INTERNAL_ERROR | "Something went wrong" | error |
+
+### Rule: never expose
+- Stack traces
+- DB error messages
+- Internal paths
+- Secret values
+```
+
+---
+
+### 8) Testing Strategy
+
+```markdown
+## 8. Testing Strategy
+
+| Layer | What | Tool | Mock |
+|-------|------|------|------|
+| Unit | Services, utils, validators | Vitest | Repos, external APIs |
+| Integration | API endpoints, DB queries | Vitest + MongoMemoryServer | External APIs |
+| Component | React components | Vitest + RTL | API calls (msw) |
+| E2E | Critical flows | Browser agent / Playwright | Nothing |
+
+### Must-have scenarios
+- [ ] CRUD settings (happy path + validation errors)
+- [ ] CRUD items (happy path + duplicate)
+- [ ] Public content endpoint returns correct payload
+- [ ] Install webhook creates installation + settings
+- [ ] Public UI renders from API payload
+```
+
+---
+
+### 9) Scalability Bottlenecks
+
+```markdown
+## 9. Scalability Bottlenecks
+
+| Bottleneck | Current | When it hurts | Mitigation |
+|-----------|---------|---------------|------------|
+| No DB indexes | Collection scan | > 1K docs | Add compound indexes |
+| Content fetch on every pageview | API load | > 100 rps | Cache-Control + CDN |
+| Single MongoDB | Write throughput | > 10K writes/s | Replica set |
+| Sync processing in webhook | Webhook timeout | Many installs | Background job |
+| No connection pooling | Connection storms | > 50 concurrent | maxPoolSize config |
+```
+
+---
+
+### 10) Growth Plan
+
+```markdown
+## 10. Growth Plan
+
+| Scale | Architecture | Changes needed |
+|-------|-------------|----------------|
+| **< 1K users** | Current: monolith + single Mongo | None |
+| **1K – 10K** | Add indexes, connection pooling, cache | ARCH-xx |
+| **10K – 100K** | Replica set, CDN for public content, Redis cache | ARCH-xx |
+| **100K – 1M** | Separate API from webhook processing, queue | ARCH-xx |
+| **> 1M** | Microservices, sharding, multi-region | Full redesign |
+```
+
+---
+
+### 11) Implementation Plan
+
+```markdown
+## 11. Implementation Plan
+
+### Phase 1: Foundation (Sprint 1)
+| # | Task | Dependencies | Estimate |
+|---|------|-------------|----------|
+| 1 | DB schemas + migrations | None | 2h |
+| 2 | API: CRUD settings | #1 | 4h |
+| 3 | API: CRUD items | #1 | 4h |
+| 4 | API: Widget endpoint | #1 | 2h |
+| 5 | Webhook handler | #1 | 3h |
+
+### Phase 2: Frontend (Sprint 1-2)
+| # | Task | Dependencies | Estimate |
+|---|------|-------------|----------|
+| 6 | Dashboard: Settings page | #2 | 6h |
+| 7 | Dashboard: Item management | #3 | 4h |
+| 8 | Dashboard: Live Preview | #4, #6 | 4h |
+
+### Phase 3: Integration (Sprint 2)
+| # | Task | Dependencies | Estimate |
+|---|------|-------------|----------|
+| 9 | Public UI | #4 | 6h |
+| 10 | External platform integration | #5, #9 | 3h |
+| 11 | E2E testing | All | 4h |
+
+### Dependency graph
+\`\`\`
+#1 → #2 → #6
+#1 → #3 → #7
+#1 → #4 → #8, #9
+#1 → #5 → #10
+#6 + #4 → #8
+#9 + #5 → #10
+All → #11
+\`\`\`
+```
+
+---
+
+## Quality Checklist
+
+| # | Check | Status |
+|---|-------|--------|
+| 1 | Любой UX flow трассируется через modules → API → DB | ☐ |
+| 2 | Границы модулей снижают связность (no circular deps) | ☐ |
+| 3 | Тестируемость заложена (mock boundaries defined) | ☐ |
+| 4 | Error handling единообразен (format + mapping) | ☐ |
+| 5 | Наблюдаемость запланирована (logs, health checks) | ☐ |
+| 6 | Deployment strategy определена | ☐ |
+| 7 | Growth plan есть (хотя бы 3 порога) | ☐ |
+| 8 | Implementation plan с зависимостями | ☐ |
+
+---
+
+## Red Flags
+
+| Flag | Описание | Обнаружение |
+|------|---------|-------------|
+| Big Ball of Mud | Нет чёткой архитектуры | Нет разделения слоёв |
+| Golden Hammer | Одно решение для всех задач | "MongoDB for everything" |
+| Premature Optimization | Оптимизация без данных | Cache/sharding до первого пользователя |
+| Not Invented Here | Отказ от готовых решений | Custom auth, custom ORM |
+| Analysis Paralysis | Бесконечное планирование | 3+ альтернативы без решения |
+| Magic | Неочевидное поведение | Hooks с бизнес-логикой |
+| Tight Coupling | Высокая связность | Изменение модуля ломает другие |
+| God Object | Один компонент делает всё | Файл > 500 строк |
+
+---
+
+## Deliverables
+
+| Артефакт | Формат | Где сохранять |
+|---------|--------|---------------|
+| Architecture Document | Markdown (11 sections above) | `docs/architecture/architecture.md` |
+| Architecture Diagram | Mermaid в документе | inline |
+| ADR records | `$adr_log` формат | `docs/architecture/adr/` |
+
+---
+
+## См. также
+- `$current_state_analysis` — аудит перед новой архитектурой
+- `$system_design_checklist` — quick check полноты
+- `$adr_log` — фиксация решений
+- `$api_contracts` — детальные API контракты
+- `$data_model` — детальная data model