code-ai-installer 1.3.1 → 1.5.0

package/.agents/api_contracts/SKILL.md

@@ -1,329 +0,0 @@
----
-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/coupons` |
-| **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/coupons
-
-**Summary:** Create a new coupon for the installation.
-
-**Auth:** Required (appInstanceId in path or JWT)
-
-**Request:**
-| Field | Type | Required | Constraints | Example |
-|-------|------|----------|------------|---------|
-| code | string | ✅ | 3-20 chars, alphanumeric | "SAVE20" |
-| discount | number | ✅ | 1-100 | 20 |
-| type | string | ✅ | enum: percent, fixed | "percent" |
-| active | boolean | ⬜ | default: true | true |
-
-**Request example:**
-\`\`\`json
-{
-  "code": "SAVE20",
-  "discount": 20,
-  "type": "percent"
-}
-\`\`\`
-
-**Response (201):**
-\`\`\`json
-{
-  "data": {
-    "id": "c-abc123",
-    "code": "SAVE20",
-    "discount": 20,
-    "type": "percent",
-    "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 | Coupon code already exists for this app |
-| 401 | UNAUTHORIZED | Missing or invalid auth |
-
-**Perf notes:**
-- Unique index on (appInstanceId, code) — O(log n) lookup
-- No pagination needed (single resource create)
-```
-
-### Zod Schema (для валидации)
-
-```js
-import { z } from 'zod';
-
-/**
- * Schema для создания купона.
- */
-export const createCouponSchema = z.object({
-  code: z.string()
-    .min(3, 'Code must be at least 3 characters')
-    .max(20, 'Code must be at most 20 characters')
-    .regex(/^[A-Za-z0-9]+$/, 'Code must be alphanumeric')
-    .transform((v) => v.toUpperCase()),
-  discount: z.number()
-    .min(1, 'Discount must be at least 1')
-    .max(100, 'Discount cannot exceed 100'),
-  type: z.enum(['percent', 'fixed']),
-  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 | Coupon 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/coupons
-
-**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 code (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 | Coupons list, activity log |
-| **Offset** | Маленькие коллекции, admin UI | Settings list (< 100 items) |
-| **No pagination** | Single resource, bounded data | Widget 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/appInstanceId 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/widget/:id` | ⬜ Public | — | Embedded script reads this |
-| `GET /api/v1/settings/:id` | ✅ Required | owner | Dashboard only |
-| `PUT /api/v1/settings/:id` | ✅ Required | owner | Dashboard only |
-| `POST /api/v1/coupons` | ✅ Required | owner | Dashboard only |
-| `POST /api/webhooks/install` | 🔑 Webhook sig | — | Wix signs with JWT |
-
----
-
-## 6. Integration Contracts
-
-### Webhook contract
-
-```markdown
-### POST /api/webhooks/v1/install
-
-**Source:** Wix Platform
-**Auth:** JWT signature verification (not Bearer token)
-**Content-Type:** text/plain (JWT string)
-
-**Processing:**
-1. Decode JWT (no verify — Wix dev environment)
-2. Extract appInstanceId from payload
-3. Upsert installation + default settings
-4. Call Embed Script API
-5. Return 200 { success: true }
-
-**Idempotent:** Yes (upsert)
-**Retry:** Wix retries on timeout/5xx
-**Timeout:** Must respond within 10s
-```
-
-### External API call contract
-
-```markdown
-### Wix Embed Script API
-
-**Endpoint:** POST https://www.wixapis.com/apps/v1/scripts
-**Auth:** OAuth access token
-**Timeout:** 5s
-**Retry:** 2x with exponential backoff (1s, 3s)
-**Idempotent:** Yes (same script URL = no-op)
-**Failure handling:** Log error, don't fail webhook (re-embed manually)
-```
-
----
-
-## 7. Пример: полный контракт (Smart Cart Rescue)
-
-```markdown
-# API Contracts: Smart Cart Rescue
-
-## Endpoints
-
-| Method | Path | Auth | Summary |
-|--------|------|------|---------|
-| GET | /api/v1/widget/:appInstanceId | Public | Widget payload for embedded script |
-| GET | /api/v1/widget/resolve-instance | Public | Resolve appInstanceId from site origin |
-| GET | /api/v1/settings/:appInstanceId | Owner | Get settings |
-| PUT | /api/v1/settings/:appInstanceId | Owner | Update settings |
-| GET | /api/v1/coupons | Owner | List coupons (paginated) |
-| POST | /api/v1/coupons | Owner | Create coupon |
-| PUT | /api/v1/coupons/:id | Owner | Update coupon |
-| DELETE | /api/v1/coupons/:id | Owner | Delete coupon |
-| POST | /api/webhooks/v1/install | Webhook | Wix install webhook |
-| POST | /api/webhooks/v1/uninstall | Webhook | Wix 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

package/.agents/architecture_compliance_review/SKILL.md

@@ -1,213 +0,0 @@
----
-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/coupons.js:25` | `Coupon.find()` called directly in route | Move to `couponService.list()` |
-| 2 | 🟠 P1 | ARCH-10 | `services/settings.js` | 620 lines — God Object risk | Split into `settingsService` + `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