code-ai-installer 1.3.1 → 1.4.0

package/.agents/skills/data_model/SKILL.md

@@ -0,0 +1,284 @@
+---
+name: data_model
+description: Модель данных и стратегия хранения — нормализация/денормализация, индексы, транзакции, кэш, (опц.) event sourcing/eventual consistency — с trade-offs и привязкой к UX flows.
+---
+
+# Skill: Data Model
+
+Модель данных: от entity definitions до query optimization.
+
+**Разделы:**
+1. [Входы](#1-входы)
+2. [Entity Definition Template](#2-entity-template)
+3. [ER Diagram](#3-er-diagram)
+4. [Data Patterns](#4-data-patterns)
+5. [Index Strategy](#5-indexes)
+6. [Query Pattern Mapping](#6-query-mapping)
+7. [Transactions](#7-transactions)
+8. [Migrations](#8-migrations)
+9. [Пример: полная модель](#9-пример)
+10. [Output Template](#10-output)
+
+---
+
+## 1. Входы
+
+| Вход | Откуда | Зачем |
+|------|--------|-------|
+| PRD | PM gate | Acceptance criteria → entities, constraints |
+| UX Spec | UX gate | Screens/flows → query patterns |
+| API Contracts | Architect | Request/Response → fields, types |
+| NFR | System Design | Volume, latency, retention |
+
+---
+
+## 2. Entity Definition Template
+
+Для каждой сущности:
+
+```markdown
+### Entity: Product
+
+**Collection:** `products`
+**Lifecycle:** Created by admin, read by public endpoint, deleted manually
+
+| Field | Type | Required | Default | Constraints | Description |
+|-------|------|----------|---------|-------------|-------------|
+| _id | ObjectId | auto | auto | unique | Primary key |
+| ownerId | string | ✅ | — | indexed | Owner/tenant reference |
+| name | string | ✅ | — | 3-100 chars | Product name |
+| price | number | ✅ | — | min: 0 | Product price |
+| category | string | ✅ | "general" | enum: general, premium, sale | Product category |
+| active | boolean | ⬜ | true | — | Is product visible |
+| viewCount | number | ⬜ | 0 | min: 0 | Times viewed |
+| createdAt | Date | auto | now | — | Timestamp |
+| updatedAt | Date | auto | now | — | Timestamp |
+
+**Unique constraints:** (ownerId, name)
+**Indexes:** See Index Strategy
+**Relationships:** belongs to Owner (via ownerId)
+**Storage pattern:** Reference (separate collection)
+**Rationale:** Products have independent lifecycle, unbounded per owner
+```
+
+---
+
+## 3. ER Diagram
+
+```mermaid
+erDiagram
+    OWNER ||--|| SETTINGS : "has one"
+    OWNER ||--o{ PRODUCT : "has many"
+
+    OWNER {
+        ObjectId _id PK
+        string ownerId UK
+        string email
+        string name
+        string status
+        Date createdAt
+    }
+
+    SETTINGS {
+        ObjectId _id PK
+        string ownerId UK "FK → Owner"
+        object general
+        object appearance
+        object notifications
+        string theme
+        string templateId
+        object templateSettings
+    }
+
+    PRODUCT {
+        ObjectId _id PK
+        string ownerId "FK → Owner"
+        string name
+        number price
+        string category
+        boolean active
+        number viewCount
+        Date createdAt
+    }
+```
+
+---
+
+## 4. Data Patterns
+
+### Embed vs Reference Decision
+
+| Критерий | Embed ✅ | Reference ✅ |
+|---------|---------|-------------|
+| Читаются вместе | Да | Нет |
+| Independent lifecycle | Нет | Да |
+| Bounded size | Да (< 50 items) | Unbounded |
+| Atomic updates child | Нужны | Не критично |
+
+### Decision table (для проекта)
+
+| Parent | Child | Pattern | Rationale |
+|--------|-------|---------|-----------|
+| Owner | Settings | **Embed** (или 1:1 ref) | Всегда читаются вместе, 1 settings per owner |
+| Owner | Products | **Reference** | Independent CRUD, unbounded, own pagination |
+| Settings | general/appearance/notifications | **Embed** | Bounded subdocuments, always read together |
+
+> Каждый выбор embed/reference = потенциальный ADR. Если неочевидно — создай `$adr_log`.
+
+### Caching (если применимо)
+
+| Data | Cache? | Strategy | TTL | Invalidation |
+|------|--------|----------|-----|--------------|
+| Public content | ✅ | HTTP Cache-Control | 60s | PUT settings → purge |
+| Product list | ⬜ | No cache (small, dashboard only) | — | — |
+| Settings (dashboard) | ⬜ | No cache (always fresh) | — | — |
+
+---
+
+## 5. Index Strategy
+
+### Index → Query Pattern Mapping
+
+| Index | Fields | Type | Serves Query |
+|-------|--------|------|-------------|
+| `owners_ownerId` | `{ ownerId: 1 }` | unique | Lookup by ownerId |
+| `settings_ownerId` | `{ ownerId: 1 }` | unique | Lookup settings by owner |
+| `products_owner_name` | `{ ownerId: 1, name: 1 }` | unique | Duplicate check on create |
+| `products_owner_active_date` | `{ ownerId: 1, active: 1, createdAt: -1 }` | compound | List active products sorted by date |
+| `products_owner_date` | `{ ownerId: 1, createdAt: -1 }` | compound | List all products sorted |
+
+### Index rules
+
+| Правило | Описание |
+|---------|---------|
+| **ESR** | Equality → Sort → Range (порядок полей в compound) |
+| **Max 5-7** | Каждый index = write overhead |
+| **Verify** | `explain('executionStats')` → IXSCAN, не COLLSCAN |
+| **Partial** | Если index нужен не для всех docs: `partialFilterExpression` |
+
+---
+
+## 6. Query Pattern Mapping
+
+Маппинг UX screen → query:
+
+| UX Screen | Action | Query | Index Used |
+|-----------|--------|-------|------------|
+| Dashboard: Products list | Load page | `find({ ownerId }).sort({ createdAt: -1 }).limit(20)` | `products_owner_date` |
+| Dashboard: Products list | Filter active | `find({ ownerId, active: true }).sort({ createdAt: -1 })` | `products_owner_active_date` |
+| Dashboard: Products list | Search by name | `find({ ownerId, name: { $regex } })` | `products_owner_name` (prefix) |
+| Dashboard: Settings | Load | `findOne({ ownerId })` | `settings_ownerId` |
+| Dashboard: Settings | Save | `updateOne({ ownerId }, { $set: ... })` | `settings_ownerId` |
+| Public Content | Load config | `findOne({ ownerId })` + `findOne({ ownerId, active: true }).sort({ createdAt: -1 })` | `settings_ownerId` + `products_owner_active_date` |
+| Webhook: register | Create | `updateOne({ ownerId }, { ... }, { upsert: true })` | `owners_ownerId` |
+
+### Performance notes
+
+| Query | Expected latency | Volume | Notes |
+|-------|-----------------|--------|-------|
+| Public content | < 10ms | Every page view | Add cache header |
+| Products list | < 20ms | Dashboard only | Paginated |
+| Settings load | < 5ms | Dashboard only | Single doc |
+
+---
+
+## 7. Transactions
+
+### Когда нужны
+
+| Scenario | Transaction? | Rationale |
+|----------|:---:|-----------|
+| Create product | ⬜ No | Single collection write |
+| Update settings | ⬜ No | Single document update |
+| Process order (if order system) | ✅ Yes | Multi-doc: update order + decrement stock |
+| Register webhook (upsert owner + settings) | ⬜ No | Idempotent upserts, eventual consistency OK |
+
+### Правило
+
+> MongoDB любит моделирование, где транзакции нужны **редко**. Если транзакция нужна часто — пересмотри schema (может стоит embed).
+
+---
+
+## 8. Migrations
+
+### Strategy
+
+| Когда | Как |
+|-------|-----|
+| Новое поле (optional) | Добавить в schema + `$setOnInsert` default |
+| Новое поле (required) | Migration script: `updateMany` + backfill |
+| Rename field | Migration script + update code + period with both fields |
+| Remove field | Migration script: `$unset` + remove from schema |
+| Change type | Два шага: add new field → migrate data → remove old |
+
+### Tool
+
+```bash
+npx migrate-mongo create add-templateId-to-settings
+npx migrate-mongo up
+npx migrate-mongo down   # rollback
+npx migrate-mongo status
+```
+
+---
+
+## 9. Пример: полная модель
+
+```markdown
+# Data Model: SaaS Admin Panel
+
+## Entities
+1. Owner — registered account/tenant record
+2. Settings — Application configuration (1:1 with Owner)
+3. Product — Content items (1:N with Owner)
+
+## Storage
+- MongoDB 7 (single instance, Docker)
+- Mongoose ODM (strict: 'throw')
+- Timestamps on all collections
+
+## Key decisions
+- Settings embedded approach considered, but separate collection for independent API
+- Products always referenced (unbounded, independent CRUD)
+- See ADR-001 (MongoDB), ADR-003 (embed vs reference)
+```
+
+---
+
+## 10. Output Template
+
+```markdown
+# Data Model: <project-name>
+
+**Date:** YYYY-MM-DD
+**Database:** MongoDB 7 + Mongoose
+
+## ER Diagram
+<mermaid diagram>
+
+## Entities
+<for each entity: section 2 template>
+
+## Data Patterns
+<embed vs ref decisions with rationale>
+
+## Indexes
+<section 5 table>
+
+## Query Mapping
+<section 6 table>
+
+## Transactions
+<section 7 table>
+
+## Migration Strategy
+<section 8>
+```
+
+---
+
+## См. также
+- `$api_contracts` — API endpoints (schemas match entity fields)
+- `$mongodb_mongoose_best_practices` — implementation patterns
+- `$architecture_doc` — Architecture Document (data model section)
+- `$adr_log` — ADR for embed/reference/DB decisions

package/.agents/skills/deployment_ci_plan/SKILL.md

@@ -0,0 +1,409 @@
+---
+name: deployment_ci_plan
+description: План деплоя и CI — окружения, конфиги, секреты, миграции, проверки в CI (tests/lint/security), стратегия релизов и откатов.
+---
+
+# Skill: Deployment & CI Plan
+
+Воспроизводимый build → test → deploy процесс.
+
+**Разделы:**
+1. [Environments](#1-environments)
+2. [Config & Secrets](#2-config--secrets)
+3. [Docker Setup](#3-docker)
+4. [CI Pipeline](#4-ci-pipeline)
+5. [DB Migrations](#5-migrations)
+6. [Release Strategy](#6-release)
+7. [Rollback Plan](#7-rollback)
+8. [Smoke Tests](#8-smoke)
+9. [Пример](#9-пример)
+10. [Output Template](#10-output)
+
+---
+
+## 1. Environments
+
+| Env | Purpose | URL | Deploy trigger | Infra |
+|-----|---------|-----|---------------|-------|
+| **local** | Development | `https://localhost:5173` | Manual (`docker compose up`) | Docker Compose |
+| **staging** | Pre-release testing | `https://staging.example.com` | Push to `staging` branch | Docker Compose / K8s |
+| **production** | Live users | `https://app.example.com` | Tag `v*` or manual approval | Docker Compose / K8s |
+
+### Environment parity rule
+
+> Dev, staging, and production use **the same Docker images**. Only env vars differ.
+
+---
+
+## 2. Config & Secrets
+
+### Env vars registry
+
+| Variable | Required | Default | Env | Description |
+|----------|:--------:|---------|-----|-------------|
+| `NODE_ENV` | ✅ | — | all | `development` / `production` |
+| `PORT` | ⬜ | 3000 | all | API server port |
+| `MONGODB_URI` | ✅ | — | all | MongoDB connection string |
+| `VITE_API_URL` | ✅ | — | FE | API base URL for frontend |
+| `EXTERNAL_API_KEY` | ⬜ | — | BE | External service API key (if applicable) |
+| `EXTERNAL_API_SECRET` | ⬜ | — | BE | External service secret (sensitive!) |
+| `LOG_LEVEL` | ⬜ | info | BE | pino log level |
+
+### Secrets policy
+
+| Rule | How |
+|------|-----|
+| **Storage** | `.env` local, Docker secrets / K8s secrets / Vault for prod |
+| **Never in code** | grep check in CI |
+| **Never in logs** | pino redact config |
+| **Never in Docker image** | ARG for build, ENV for runtime only |
+| **Rotation** | Document rotation procedure per secret |
+| **.env.example** | Committed, no real values, all vars listed |
+
+---
+
+## 3. Docker Setup
+
+### Dockerfile (multi-stage, Node.js)
+
+```dockerfile
+# ── Build stage ──
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci --ignore-scripts
+COPY . .
+RUN npm run build
+
+# ── Runtime stage ──
+FROM node:20-alpine AS runtime
+WORKDIR /app
+ENV NODE_ENV=production
+RUN addgroup -g 1001 appgroup && \
+    adduser -u 1001 -G appgroup -s /bin/sh -D appuser
+COPY --from=builder --chown=appuser:appgroup /app/dist ./dist
+COPY --from=builder --chown=appuser:appgroup /app/node_modules ./node_modules
+COPY --from=builder --chown=appuser:appgroup /app/package.json ./
+USER appuser
+EXPOSE 3000
+HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://localhost:3000/health/live || exit 1
+CMD ["node", "dist/server.js"]
+```
+
+### Docker Compose (development)
+
+```yaml
+version: "3.9"
+services:
+  api:
+    build:
+      context: ./api
+      dockerfile: Dockerfile
+    ports:
+      - "3000:3000"
+    env_file: ./api/.env
+    depends_on:
+      mongo:
+        condition: service_healthy
+    restart: unless-stopped
+
+  dashboard:
+    build:
+      context: ./dashboard
+      dockerfile: Dockerfile
+    ports:
+      - "3001:3001"
+    env_file: ./dashboard/.env
+    restart: unless-stopped
+
+  mongo:
+    image: mongo:7
+    ports:
+      - "27017:27017"
+    volumes:
+      - mongo_data:/data/db
+    healthcheck:
+      test: mongosh --eval "db.adminCommand('ping')"
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  gateway:
+    image: caddy:2-alpine
+    ports:
+      - "5173:5173"
+    volumes:
+      - ./Caddyfile:/etc/caddy/Caddyfile:ro
+    depends_on:
+      - api
+      - dashboard
+
+volumes:
+  mongo_data:
+```
+
+### Docker rules
+
+| Rule | Description |
+|------|-------------|
+| **Multi-stage** | Builder → Runtime (smaller image, no dev deps) |
+| **Non-root** | `USER appuser` (never root in runtime) |
+| **Lockfile** | `npm ci` (deterministic installs) |
+| **HEALTHCHECK** | Built into Dockerfile or docker-compose |
+| **Cache-friendly** | Copy `package*.json` before source code |
+| **No secrets** | Never `COPY .env`, use `env_file` in compose |
+| **.dockerignore** | `node_modules`, `.env`, `.git`, `*.log` |
+
+---
+
+## 4. CI Pipeline
+
+### GitHub Actions example
+
+```yaml
+name: CI
+on:
+  push:
+    branches: [main, staging]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 20 }
+      - run: npm ci
+      - run: npx biome check .
+
+  test:
+    runs-on: ubuntu-latest
+    needs: lint
+    services:
+      mongo:
+        image: mongo:7
+        ports: ["27017:27017"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 20 }
+      - run: npm ci
+      - run: npm test
+        env:
+          MONGODB_URI: mongodb://localhost:27017/test
+
+  security:
+    runs-on: ubuntu-latest
+    needs: lint
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 20 }
+      - run: npm ci
+      - run: npm audit --audit-level=high
+      - run: npx secretlint "**/*"
+
+  build:
+    runs-on: ubuntu-latest
+    needs: [test, security]
+    steps:
+      - uses: actions/checkout@v4
+      - run: docker build -t app-api ./api
+      - run: docker build -t app-dashboard ./dashboard
+```
+
+### Pipeline stages
+
+```
+┌────────┐    ┌──────┐    ┌──────────┐    ┌───────┐    ┌────────┐
+│  Lint  │───▸│ Test │───▸│ Security │───▸│ Build │───▸│ Deploy │
+└────────┘    └──────┘    └──────────┘    └───────┘    └────────┘
+ biome check   vitest      npm audit        docker      compose
+                           secretlint       build       up -d
+```
+
+### CI rules
+
+| Rule | Description |
+|------|-------------|
+| **Block merge** | Failed CI = no merge |
+| **Parallelism** | lint ∥ security, then test, then build |
+| **Secrets** | GitHub Secrets / CI vars (never hardcoded) |
+| **Deps cache** | `actions/cache` for node_modules |
+| **Coverage** | Fail if < threshold (e.g. 70%) |
+
+---
+
+## 5. Migrations
+
+### Strategy (MongoDB + migrate-mongo)
+
+```bash
+# Create migration
+npx migrate-mongo create add-templateId-to-settings
+
+# Apply pending migrations
+npx migrate-mongo up
+
+# Rollback last migration
+npx migrate-mongo down
+
+# Check status
+npx migrate-mongo status
+```
+
+### Rules
+
+| Rule | Description |
+|------|-------------|
+| **Run before deploy** | Migrations applied before new code starts |
+| **Forward-compatible** | New code must work with old schema during rolling update |
+| **Reversible** | Every `up()` has matching `down()` |
+| **Tested** | Run against test DB in CI |
+| **Idempotent** | Safe to run multiple times |
+
+---
+
+## 6. Release Strategy
+
+### Versioning
+
+```
+SemVer: MAJOR.MINOR.PATCH
+- MAJOR: breaking API changes
+- MINOR: new features (backward compatible)
+- PATCH: bug fixes
+
+Git tags: v1.0.0, v1.1.0, v1.1.1
+Docker tags: app-api:v1.0.0, app-api:latest
+```
+
+### Release flow
+
+```
+feature branch → PR → main (CI green) → tag vX.Y.Z → deploy
+```
+
+### Feature flags (if needed)
+
+| Flag | Purpose | Default | How to toggle |
+|------|---------|---------|---------------|
+| `ENABLE_NEW_TEMPLATE` | Show new popup template | false | Env var |
+| `ENABLE_ANALYTICS` | Send analytics events | false | Env var |
+
+---
+
+## 7. Rollback Plan
+
+### Procedure
+
+```markdown
+## Rollback Checklist
+
+1. ☐ **Identify issue** — what broke? Check logs, alerts, user reports
+2. ☐ **Communicate** — inform team that rollback is starting
+3. ☐ **Rollback code:**
+   - Docker: `docker compose up -d --build` with previous image tag
+   - K8s: `kubectl rollout undo deployment/<name>`
+4. ☐ **Rollback DB (if migration applied):**
+   - `npx migrate-mongo down`
+   - Verify data integrity
+5. ☐ **Verify** — run smoke tests, check health endpoints
+6. ☐ **Post-mortem** — document what went wrong
+```
+
+### Time targets
+
+| Action | Target |
+|--------|--------|
+| Detection | < 5 min (alerts) |
+| Decision to rollback | < 10 min |
+| Rollback execution | < 5 min |
+| Verification | < 5 min |
+| **Total MTTR** | **< 25 min** |
+
+---
+
+## 8. Smoke Tests
+
+### Post-deploy smoke test checklist
+
+| # | Test | How | Expected |
+|---|------|-----|----------|
+| 1 | Health check | `GET /health/live` | 200 OK |
+| 2 | Ready check | `GET /health/ready` | 200 OK (DB connected) |
+| 3 | Content endpoint | `GET /api/v1/content/<testId>` | 200 + valid payload |
+| 4 | Dashboard loads | Open dashboard URL | Page renders |
+| 5 | Settings CRUD | PUT, then GET settings | Values persisted |
+| 6 | Public content | Check public content endpoint | Content served |
+
+---
+
+## 9. Пример
+
+```markdown
+# Deployment & CI Plan: SaaS Admin Panel
+
+## Environments
+- local: Docker Compose + Caddy (https://localhost:5173)
+- production: Docker Compose + Cloudflare Tunnel
+
+## CI: GitHub Actions (lint → test → security → build)
+## Migrations: migrate-mongo (run before deploy)
+## Release: SemVer tags, manual production deploy
+## Rollback: Previous Docker image + migrate-mongo down
+```
+
+---
+
+## 10. Output Template
+
+```markdown
+# Deployment & CI Plan: <project-name>
+
+**Date:** YYYY-MM-DD
+
+## Environments
+<section 1 table>
+
+## Config & Secrets
+<section 2 registry + policy>
+
+## Docker Setup
+<Dockerfile + docker-compose.yml>
+
+## CI Pipeline
+<pipeline stages + YAML config>
+
+## Migrations
+<strategy + commands>
+
+## Release Strategy
+<versioning + flow>
+
+## Rollback Plan
+<procedure + time targets>
+
+## Smoke Tests
+<post-deploy checklist>
+```
+
+---
+
+## DoD (Definition of Done)
+
+- ☐ CI is green (all stages pass)
+- ☐ Migrations applied and tested
+- ☐ Smoke tests passed after deploy
+- ☐ Rollback procedure documented and executable
+- ☐ No secrets in code/images/logs
+
+---
+
+## См. также
+- `$docker_kubernetes_architecture` — detailed Docker/K8s architecture
+- `$k8s_manifests_conventions` — K8s manifest standards
+- `$observability_plan` — logging/metrics/alerts
+- `$security_baseline_dev` — secrets management