code-ai-installer 1.3.1 → 1.4.0

package/.agents/skills/adr_log/SKILL.md

@@ -0,0 +1,369 @@
+---
+name: adr_log
+description: Зафиксировать ключевые архитектурные решения (ADR) с trade-offs — Pros/Cons/Alternatives/Decision, статусом и датой.
+---
+
+# Skill: ADR Log
+
+Формат и примеры для Architectural Decision Records.
+
+**Разделы:**
+1. [Когда создавать ADR](#1-когда)
+2. [Формат (обязательный)](#2-формат)
+3. [Naming Convention](#3-naming)
+4. [Примеры ADR](#4-примеры)
+5. [Decision Matrix](#5-decision-matrix)
+6. [Lifecycle](#6-lifecycle)
+7. [Anti-patterns](#7-anti-patterns)
+
+---
+
+## 1. Когда создавать ADR
+
+Создавай ADR для **каждого нетривиального выбора** — если через 6 месяцев кто-то спросит "почему так?":
+
+| Категория | Примеры |
+|-----------|---------|
+| **Database** | Выбор СУБД, embed vs reference, sharding strategy |
+| **Auth** | JWT vs sessions, cookie vs header, OAuth flow |
+| **API Design** | REST vs GraphQL, versioning, error format |
+| **Architecture** | Monolith vs microservices, layering, module boundaries |
+| **Infrastructure** | Docker vs K8s, CDN, reverse proxy, HTTPS strategy |
+| **Integration** | Wix SDK choice, payment provider, email service |
+| **State** | Zustand vs Redux vs Context, server state (React Query) |
+| **Styling** | CSS Modules vs Tailwind vs styled-components |
+| **Testing** | Test runner, coverage thresholds, mock strategy |
+| **Error handling** | Error format, retry policy, circuit breaker |
+
+---
+
+## 2. Формат (обязательный)
+
+```markdown
+# ADR-XXX: <Краткое название решения>
+
+## Status
+Proposed | Accepted | Deprecated | Superseded by ADR-YYY
+
+## Date
+YYYY-MM-DD
+
+## Context
+<Почему это нужно? Какие ограничения? Что болит?>
+- Текущая ситуация
+- Требования / constraints
+- Что произойдёт если не решить
+
+## Decision
+<Что выбрали и как именно будем делать>
+
+## Consequences
+
+### Positive
+- ...
+- ...
+
+### Negative
+- ...
+- ...
+
+### Risks
+- ... (и как митигируем)
+
+## Alternatives Considered
+
+### Option A: <название>
+- ✅ Pros: ...
+- ❌ Cons: ...
+- 💡 Why rejected: ...
+
+### Option B: <название>
+- ✅ Pros: ...
+- ❌ Cons: ...
+- 💡 Why rejected: ...
+
+## References
+- PRD section / UX Spec / ticket
+- External docs / articles
+- Related ADRs: ADR-XXX
+```
+
+---
+
+## 3. Naming Convention
+
+| Правило | Пример |
+|---------|--------|
+| Номер: 3-значный, с ведущими нулями | ADR-001, ADR-042 |
+| Название: action + object | "Use MongoDB as primary database" |
+| Файл: `ADR-XXX-kebab-case.md` | `ADR-001-use-mongodb.md` |
+| Директория: `docs/architecture/adr/` | — |
+| Хронологический порядок | Новые ADR = следующий номер |
+
+---
+
+## 4. Примеры ADR
+
+### ADR-001: Use MongoDB as primary database
+
+```markdown
+# ADR-001: Use MongoDB as primary database
+
+## Status
+Accepted
+
+## Date
+2025-06-15
+
+## Context
+The application needs persistent storage for tenants, settings,
+and products. Requirements:
+- Flexible schema (settings structure varies per configuration)
+- Low operational overhead (small team)
+- Good Node.js ecosystem support
+- No complex joins needed (data is per-tenant)
+
+## Decision
+Use MongoDB 7 with Mongoose ODM.
+- Single database, collections: tenants, settings, products
+- Hosted via Docker (dev) / MongoDB Atlas (production)
+
+## Consequences
+
+### Positive
+- Flexible schema fits varying template settings
+- Excellent Mongoose ecosystem (validators, middleware, lean queries)
+- Easy Docker setup for local development
+- Native JSON — minimal serialization overhead
+
+### Negative
+- No ACID transactions across collections (need replica set)
+- No joins — must denormalize or do application-level joins
+- Schema discipline required (strict mode + Zod validation)
+
+### Risks
+- Schema drift without validation → mitigated by strict: 'throw'
+- 16MB document limit → mitigated by reference strategy for unbounded arrays
+
+## Alternatives Considered
+
+### Option A: PostgreSQL
+- ✅ ACID, complex queries, strong typing
+- ❌ Schema migrations more complex for flexible settings
+- ❌ JSON column less ergonomic than native MongoDB documents
+- 💡 Overkill for current use case (no joins, no complex queries)
+
+### Option B: SQLite
+- ✅ Zero infrastructure, file-based
+- ❌ No concurrent writes in Docker
+- ❌ No production scaling path
+- 💡 Too limiting for multi-service architecture
+
+## References
+- PRD: Data requirements section
+- Related: ADR-002 (Mongoose strict mode)
+```
+
+---
+
+### ADR-018: Use Wix ImageViewer for dashboard images
+
+```markdown
+# ADR-018: Use Wix ImageViewer for dashboard images
+
+## Status
+Accepted
+
+## Date
+2025-12-20
+
+## Context
+Dashboard needs to display template preview images.
+The app runs inside Wix iframe where standard <img> tags may have
+CORS issues with Wix media URLs (wixstatic.com).
+
+## Decision
+Use WDS (Wix Design System) ImageViewer component for all
+dashboard images instead of native <img> tags.
+
+## Consequences
+
+### Positive
+- Handles Wix media URLs natively (no CORS issues)
+- Consistent with Wix design system (visual parity)
+- Built-in loading states and error handling
+
+### Negative
+- Dependency on WDS component library
+- Different API than standard <img> (onLoad, src format)
+
+## Alternatives Considered
+
+### Option A: Native <img> with proxy
+- ✅ Simple, no dependency
+- ❌ CORS errors with wixstatic.com
+- ❌ Need custom proxy endpoint
+- 💡 Unnecessary complexity
+
+## References
+- Bug: Dashboard images not loading (blank src)
+- Wix Design System docs: ImageViewer component
+```
+
+---
+
+### ADR-019: CSS overflow containment for popup templates
+
+```markdown
+# ADR-019: CSS overflow containment for popup
+
+## Status
+Accepted
+
+## Date
+2025-12-20
+
+## Context
+Popup templates render inside Wix embedded script.
+CSS overflow from popup elements leaks outside the container,
+causing scrollbars on the Wix page.
+
+## Decision
+Apply containment strategy:
+1. `overflow: hidden` on popup container
+2. `contain: layout style` on root widget element
+3. `box-sizing: border-box` on all popup children
+
+## Consequences
+
+### Positive
+- No visual leaking outside container
+- No unexpected scrollbars on host page
+- Each template isolated
+
+### Negative
+- Must test each template for clipping issues
+- Shadow effects near edges may be cut off
+
+## Alternatives Considered
+
+### Option A: Shadow DOM
+- ✅ Complete style isolation
+- ❌ Complex to implement for dynamic templates
+- ❌ Limited shadow DOM support for legacy browsers
+- 💡 Overkill for current 3-template scope
+
+## References
+- Bug: Scrollbar appearing on Wix site when popup opens
+- Related: ADR-018 (ImageViewer)
+```
+
+---
+
+## 5. Decision Matrix
+
+Для сложных решений с 3+ альтернативами используй weighted matrix:
+
+```markdown
+## Decision Matrix: State Management
+
+### Criteria (weighted)
+| Criteria | Weight | Description |
+|----------|--------|-------------|
+| Simplicity | 3 | Learning curve, boilerplate |
+| Performance | 2 | Re-render efficiency |
+| DevTools | 1 | Debugging experience |
+| Ecosystem | 1 | Community, plugins |
+| Bundle size | 2 | KB added |
+
+### Scoring (1-5, higher = better)
+
+| Option | Simplicity (×3) | Performance (×2) | DevTools (×1) | Ecosystem (×1) | Bundle (×2) | **Total** |
+|--------|:---:|:---:|:---:|:---:|:---:|:---:|
+| **Zustand** | 5 (15) | 4 (8) | 4 (4) | 3 (3) | 5 (10) | **40** |
+| Redux Toolkit | 3 (9) | 4 (8) | 5 (5) | 5 (5) | 3 (6) | **33** |
+| Context + useReducer | 4 (12) | 2 (4) | 3 (3) | 5 (5) | 5 (10) | **34** |
+| Jotai | 4 (12) | 5 (10) | 3 (3) | 2 (2) | 5 (10) | **37** |
+
+### Decision
+Zustand wins (40 points). Best simplicity + performance + bundle size.
+```
+
+---
+
+## 6. Lifecycle
+
+```
+Proposed → Accepted → [Active use]
+                         ↓
+                    Deprecated (if better solution found)
+                         ↓
+                    Superseded by ADR-YYY
+```
+
+| Status | Значение |
+|--------|---------|
+| **Proposed** | Решение предложено, ждёт review |
+| **Accepted** | Решение утверждено, применяется |
+| **Deprecated** | Решение устарело, но код ещё использует |
+| **Superseded** | Заменено другим ADR (указать ссылку) |
+
+### Supersedes/Superseded-by
+
+```markdown
+# ADR-025: Migrate from CSS Modules to Tailwind
+
+## Status
+Accepted (Supersedes ADR-008)
+
+---
+
+# ADR-008: Use CSS Modules for component styling
+
+## Status
+Superseded by ADR-025
+```
+
+---
+
+## 7. Anti-patterns
+
+| ❌ Anti-pattern | ✅ Решение |
+|----------------|-----------|
+| ADR без Alternatives | Всегда минимум 2 альтернативы |
+| "We chose X because it's popular" | Конкретные Pros/Cons по критериям проекта |
+| 500-строчный ADR | Короткий и конкретный: max 50-80 строк |
+| ADR задним числом (через месяц) | Создавать ADR в момент принятия решения |
+| Нет cross-references | Ссылки на PRD, related ADRs, tickets |
+| Нет Negative consequences | Каждое решение имеет trade-offs |
+| "Alternatives: none" | Если альтернатив нет — пересмотри скоуп вопроса |
+
+---
+
+## Deliverables
+
+| Артефакт | Формат | Где |
+|---------|--------|-----|
+| ADR record | Markdown (format above) | `docs/architecture/adr/ADR-XXX-name.md` |
+| ADR index | Table of contents | `docs/architecture/adr/README.md` |
+
+### ADR Index format
+
+```markdown
+# Architecture Decision Records
+
+| # | Title | Status | Date |
+|---|-------|--------|------|
+| ADR-001 | Use MongoDB as primary database | Accepted | 2025-06-15 |
+| ADR-008 | Use CSS Modules for styling | Superseded by ADR-025 | 2025-07-01 |
+| ADR-018 | Use WDS ImageViewer | Accepted | 2025-12-20 |
+| ADR-019 | CSS overflow containment | Accepted | 2025-12-20 |
+| ADR-025 | Migrate to Tailwind | Accepted | 2026-01-15 |
+```
+
+---
+
+## См. также
+- `$architecture_doc` — Architecture Document (ADR decisions referenced inline)
+- `$current_state_analysis` — аудит перед новыми ADR
+- `$system_design_checklist` — checklist полноты дизайна

package/.agents/skills/api_contracts/SKILL.md

@@ -0,0 +1,328 @@
+---
+name: api_contracts
+description: API контракты по UX flows — эндпоинты, схемы, ошибки, валидация, авторизация, perf/scalability соображения, идемпотентность и интеграционные паттерны.
+---
+
+# Skill: API Contracts
+
+Полное описание API: от endpoint definition до error format.
+
+**Разделы:**
+1. [Общие правила](#1-общие-правила)
+2. [Endpoint Definition Template](#2-endpoint-template)
+3. [Error Format](#3-error-format)
+4. [Pagination & Filtering](#4-pagination)
+5. [Auth Convention](#5-auth)
+6. [Integration Contracts](#6-integrations)
+7. [Пример: полный контракт](#7-пример)
+8. [Output Template](#8-output)
+
+---
+
+## 1. Общие правила
+
+| Правило | Convention |
+|---------|-----------|
+| **Base path** | `/api/v1/<resource>` |
+| **Naming** | kebab-case, plural nouns: `/api/v1/products` |
+| **Methods** | GET (read), POST (create), PUT (full update), PATCH (partial), DELETE |
+| **Status codes** | 200 (OK), 201 (Created), 204 (No Content), 400, 401, 403, 404, 409, 422, 500 |
+| **Content-Type** | `application/json` (request & response) |
+| **Error format** | Единый (см. section 3) |
+| **Validation** | Zod schemas на каждый endpoint, на границе (middleware) |
+| **Auth** | Token в header или httpOnly cookie. Проверка на каждом protected endpoint |
+| **Idempotency** | PUT = idempotent. POST create = idempotent key (если нужно) |
+| **Versioning** | URL prefix: `/api/v1/`, `/api/v2/` (при breaking changes) |
+
+---
+
+## 2. Endpoint Definition Template
+
+Для каждого endpoint заполни:
+
+```markdown
+### POST /api/v1/products
+
+**Summary:** Create a new product for the tenant.
+
+**Auth:** Required (tenantId in path or JWT)
+
+**Request:**
+| Field | Type | Required | Constraints | Example |
+|-------|------|----------|------------|---------|
+| name | string | ✅ | 3-100 chars | "Premium Widget" |
+| price | number | ✅ | 0.01-99999 | 29.99 |
+| category | string | ✅ | enum: digital, physical, subscription | "digital" |
+| active | boolean | ⬜ | default: true | true |
+
+**Request example:**
+\`\`\`json
+{
+  "name": "Premium Widget",
+  "price": 29.99,
+  "category": "digital"
+}
+\`\`\`
+
+**Response (201):**
+\`\`\`json
+{
+  "data": {
+    "id": "p-abc123",
+    "name": "Premium Widget",
+    "price": 29.99,
+    "category": "digital",
+    "active": true,
+    "createdAt": "2026-03-13T03:00:00Z",
+    "updatedAt": "2026-03-13T03:00:00Z"
+  }
+}
+\`\`\`
+
+**Errors:**
+| Status | Code | When |
+|--------|------|------|
+| 400 | VALIDATION_ERROR | Invalid input (see details) |
+| 409 | DUPLICATE | Product name already exists for this tenant |
+| 401 | UNAUTHORIZED | Missing or invalid auth |
+
+**Perf notes:**
+- Unique index on (tenantId, name) — O(log n) lookup
+- No pagination needed (single resource create)
+```
+
+### Zod Schema (для валидации)
+
+```js
+import { z } from 'zod';
+
+/**
+ * Schema для создания продукта.
+ */
+export const createProductSchema = z.object({
+  name: z.string()
+    .min(3, 'Name must be at least 3 characters')
+    .max(100, 'Name must be at most 100 characters')
+    .trim(),
+  price: z.number()
+    .min(0.01, 'Price must be at least 0.01')
+    .max(99999, 'Price cannot exceed 99999'),
+  category: z.enum(['digital', 'physical', 'subscription']),
+  active: z.boolean().optional().default(true),
+});
+```
+
+---
+
+## 3. Error Format
+
+### Единый формат (все endpoints)
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Invalid input",
+    "details": [
+      { "field": "code", "message": "Must be at least 3 characters" },
+      { "field": "discount", "message": "Must be at least 1" }
+    ]
+  }
+}
+```
+
+### Error codes (registry)
+
+| HTTP | Code | Description | When |
+|------|------|-------------|------|
+| 400 | `VALIDATION_ERROR` | Input validation failed | Zod parse error |
+| 400 | `BAD_REQUEST` | Malformed request | Missing body, bad JSON |
+| 401 | `UNAUTHORIZED` | No auth or expired token | Missing/invalid JWT |
+| 403 | `FORBIDDEN` | Authenticated but not allowed | Wrong role/scope |
+| 404 | `NOT_FOUND` | Resource doesn't exist | ID not in DB |
+| 409 | `DUPLICATE` | Unique constraint violation | Duplicate key |
+| 409 | `CONFLICT` | Optimistic concurrency | Version mismatch |
+| 422 | `UNPROCESSABLE` | Business rule violation | Item expired, limit reached |
+| 429 | `RATE_LIMITED` | Too many requests | Rate limit exceeded |
+| 500 | `INTERNAL_ERROR` | Unexpected server error | Bug, DB down |
+
+### Правила
+
+- **Никогда** не возвращать stack trace, DB error, internal path
+- `code` = machine-readable (для клиента)
+- `message` = human-readable (для toast/UI)
+- `details` = field-level errors (для form validation)
+
+---
+
+## 4. Pagination & Filtering
+
+### Cursor pagination (default для списков)
+
+```markdown
+### GET /api/v1/products
+
+**Query params:**
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| limit | number | 20 | Max items per page (1-100) |
+| cursor | string | — | Cursor from previous response |
+| status | string | — | Filter: "active" or "inactive" |
+| q | string | — | Search by name (case-insensitive) |
+| sort | string | -createdAt | Sort field with direction prefix |
+
+**Response (200):**
+\`\`\`json
+{
+  "data": [...],
+  "pagination": {
+    "nextCursor": "eyJpZCI6ImMtYWJjMTIzIn0=",
+    "hasMore": true,
+    "total": 42
+  }
+}
+\`\`\`
+```
+
+### Convention
+
+| Pattern | Когда | Пример |
+|---------|-------|--------|
+| **Cursor** | Большие коллекции (> 1K), real-time data | Products list, activity log |
+| **Offset** | Маленькие коллекции, admin UI | Settings list (< 100 items) |
+| **No pagination** | Single resource, bounded data | Config, user profile |
+
+---
+
+## 5. Auth
+
+### Convention
+
+```markdown
+**Auth header:**
+Authorization: Bearer <jwt_token>
+
+**Or httpOnly cookie:**
+Cookie: token=<jwt_token>
+
+**Auth check middleware:**
+1. Extract token (header → cookie fallback)
+2. Verify JWT signature + expiration
+3. Attach user/tenantId to req
+4. Check required role/scope (if endpoint needs it)
+
+**Protected endpoints:** All /api/v1/* except:
+- GET /health/live
+- GET /health/ready
+- POST /api/webhooks/* (verified by webhook signature)
+```
+
+### Auth table (per endpoint)
+
+| Endpoint | Auth | Role | Notes |
+|----------|------|------|-------|
+| `GET /api/v1/content/:id` | ⬜ Public | — | Public content endpoint |
+| `GET /api/v1/settings/:id` | ✅ Required | owner | Dashboard only |
+| `PUT /api/v1/settings/:id` | ✅ Required | owner | Dashboard only |
+| `POST /api/v1/products` | ✅ Required | owner | Dashboard only |
+| `POST /api/webhooks/install` | 🔑 Webhook sig | — | Platform signs with JWT |
+
+---
+
+## 6. Integration Contracts
+
+### Webhook contract
+
+```markdown
+### POST /api/webhooks/v1/install
+
+**Source:** External Platform
+**Auth:** JWT signature verification (not Bearer token)
+**Content-Type:** text/plain (JWT string)
+
+**Processing:**
+1. Decode JWT (verify signature in production)
+2. Extract tenantId from payload
+3. Upsert tenant + default settings
+4. Call Platform registration API
+5. Return 200 { success: true }
+
+**Idempotent:** Yes (upsert)
+**Retry:** Platform retries on timeout/5xx
+**Timeout:** Must respond within 10s
+```
+
+### External API call contract
+
+```markdown
+### External Platform API
+
+**Endpoint:** POST https://api.example.com/v1/register
+**Auth:** OAuth access token
+**Timeout:** 5s
+**Retry:** 2x with exponential backoff (1s, 3s)
+**Idempotent:** Yes (same registration = no-op)
+**Failure handling:** Log error, don't fail webhook (retry manually)
+```
+
+---
+
+## 7. Пример: полный контракт
+
+```markdown
+# API Contracts: SaaS Admin Panel
+
+## Endpoints
+
+| Method | Path | Auth | Summary |
+|--------|------|------|---------|
+| GET | /api/v1/content/:tenantId | Public | Public content payload |
+| GET | /api/v1/content/resolve-tenant | Public | Resolve tenantId from origin |
+| GET | /api/v1/settings/:tenantId | Owner | Get settings |
+| PUT | /api/v1/settings/:tenantId | Owner | Update settings |
+| GET | /api/v1/products | Owner | List products (paginated) |
+| POST | /api/v1/products | Owner | Create product |
+| PUT | /api/v1/products/:id | Owner | Update product |
+| DELETE | /api/v1/products/:id | Owner | Delete product |
+| POST | /api/webhooks/v1/install | Webhook | Platform install webhook |
+| POST | /api/webhooks/v1/uninstall | Webhook | Platform uninstall webhook |
+| GET | /health/live | Public | Liveness probe |
+| GET | /health/ready | Public | Readiness probe |
+```
+
+---
+
+## 8. Output Template
+
+```markdown
+# API Contracts: <project-name>
+
+**Date:** YYYY-MM-DD
+**Version:** v1
+**Base URL:** https://<host>/api/v1
+
+## General Rules
+- Error format: { error: { code, message, details } }
+- Auth: Bearer JWT or httpOnly cookie
+- Pagination: cursor-based (limit, cursor, hasMore)
+
+## Endpoints
+<for each endpoint: section 2 template>
+
+## Error Codes
+<section 3 registry table>
+
+## Auth Table
+<section 5 per-endpoint table>
+
+## Integration Contracts
+<section 6 for each external integration>
+```
+
+---
+
+## См. также
+- `$architecture_doc` — Architecture Document (references API contracts)
+- `$data_model` — Data model (entities match request/response schemas)
+- `$security_baseline_dev` — Zod validation, auth patterns
+- `$node_express_beast_practices` — Express implementation patterns