code-ai-installer 2.5.0 → 4.0.0

package/domains/development/.agents/skills/observability-logging/agents/kimi.yaml

@@ -1,14 +1,14 @@
-name: "observability-logging"
-display_name: "Логирование и наблюдаемость"
-description: "Реализация наблюдаемости на уровне кода — структурированные логи (pino), request_id/trace_id корреляция, уровни логов, запрет утечки PII/секретов, базовые метрики, health checks. DO/DON'T примеры. Активируй при настройке логирования, добавлении метрик, или при вопросах «как правильно логировать»."
-default_prompt: "Используй $observability-logging, когда задача относится к навыку \"Логирование и наблюдаемость\"."
-triggers:
-  - "observability-logging"
-  - "observability logging"
-  - "Логирование и наблюдаемость"
-  - "Реализация наблюдаемости на уровне кода — структурированные логи (pino), request_id/trace_id корреляция, уровни логов, запрет утечки PII/секретов, базовые метрики, health checks"
-capabilities:
-  - "observability"
-  - "logging"
-tools: []
-implicit_invocation: true
+name: "observability-logging"
+display_name: "Логирование и наблюдаемость"
+description: "Реализация наблюдаемости на уровне кода — decision rules для логов (pino), request_id/trace_id correlation, уровни логов, запрет PII/секретов, метрики, health checks. Активируй при настройке логирования, добавлении метрик, или при вопросах «как правильно логировать». Полные code templates — в `$observability-logging-reference`."
+default_prompt: "Используй $observability-logging, когда задача относится к навыку \"Логирование и наблюдаемость\"."
+triggers:
+  - "observability-logging"
+  - "observability logging"
+  - "Логирование и наблюдаемость"
+  - "Реализация наблюдаемости на уровне кода — структурированные логи (pino), request_id/trace_id корреляция, уровни логов, запрет утечки PII/секретов, базовые метрики, health checks"
+capabilities:
+  - "observability"
+  - "logging"
+tools: []
+implicit_invocation: true

package/domains/development/.agents/skills/observability-logging/agents/qwen.json

@@ -1,7 +1,7 @@
 {
   "name": "observability-logging",
   "display_name": "Логирование и наблюдаемость",
-  "description": "Реализация наблюдаемости на уровне кода — структурированные логи (pino), request_id/trace_id корреляция, уровни логов, запрет утечки PII/секретов, базовые метрики, health checks. DO/DON'T примеры. Активируй при настройке логирования, добавлении метрик, или при вопросах «как правильно логировать».",
+  "description": "Реализация наблюдаемости на уровне кода — decision rules для логов (pino), request_id/trace_id correlation, уровни логов, запрет PII/секретов, метрики, health checks. Активируй при настройке логирования, добавлении метрик, или при вопросах «как правильно логировать». Полные code templates — в `$observability-logging-reference`.",
   "default_prompt": "Используй $observability-logging, когда задача относится к навыку \"Логирование и наблюдаемость\".",
   "triggers": [
     "observability-logging",

package/domains/development/.agents/skills/observability-logging/agents/skill.yaml

@@ -1,7 +1,7 @@
 version: 1
 name: "observability-logging"
 display_name: "Логирование и наблюдаемость"
-description: "Реализация наблюдаемости на уровне кода — структурированные логи (pino), request_id/trace_id корреляция, уровни логов, запрет утечки PII/секретов, базовые метрики, health checks. DO/DON'T примеры. Активируй при настройке логирования, добавлении метрик, или при вопросах «как правильно логировать»."
+description: "Реализация наблюдаемости на уровне кода — decision rules для логов (pino), request_id/trace_id correlation, уровни логов, запрет PII/секретов, метрики, health checks. Активируй при настройке логирования, добавлении метрик, или при вопросах «как правильно логировать». Полные code templates — в `$observability-logging-reference`."
 default_prompt: "Используй $observability-logging, когда задача относится к навыку \"Логирование и наблюдаемость\"."
 triggers:
   - "observability-logging"

package/domains/development/.agents/skills/observability-logging-reference/SKILL.md

@@ -0,0 +1,409 @@
+---
+name: observability-logging-reference
+description: Канонический справочник шаблонов observability — pino config с redact paths, standard log fields object, requestId middleware, distributed tracing, маскеры PII (maskEmail/maskCard), metricsMiddleware, prom-client setup, liveness/readiness endpoints. Активируй при поиске конкретного шаблона logger / metrics / health.
+type: reference
+domain: development
+owners:
+  - devops
+  - senior_full_stack
+gates:
+  - OPS
+  - DEV
+tech: []
+topic:
+  - general
+  - ops
+  - observability
+triggers:
+  - pino config пример
+  - structured log fields template
+  - requestId middleware code
+  - distributed tracing headers
+  - PII masking helper
+  - metricsMiddleware template
+  - prom-client setup
+  - liveness readiness endpoint
+related:
+  - observability-logging
+  - security-baseline-dev
+  - security-baseline-dev-reference
+  - node-express-beast-practices-reference
+  - observability-plan
+  - observability-review
+budget_lines: 450
+schema_version: 1
+---
+
+
+# Skill: Observability Reference
+
+Канонические code templates для реализации observability — копируй и адаптируй. Decision rules "когда / какой уровень / правила" — в `$observability-logging`.
+
+**Разделы:**
+1. [Logger Setup (pino)](#1-logger-setup)
+2. [Standard Log Fields](#2-standard-log-fields)
+3. [Request Correlation Middleware](#3-request-correlation-middleware)
+4. [Redaction Templates](#4-redaction-templates)
+5. [Metrics](#5-metrics)
+6. [Health Checks](#6-health-checks)
+
+---
+
+## 1. Logger Setup
+
+```js
+// utils/logger.js
+import pino from 'pino';
+import { config } from '../config/env.js';
+
+/**
+ * Создаёт структурированный JSON logger.
+ * Production: JSON output (для LogDNA/Datadog/ELK).
+ * Development: pretty-print для консоли.
+ */
+export const logger = pino({
+  level: config.LOG_LEVEL || 'info',
+
+  // ✅ Автоматическая фильтрация чувствительных данных
+  redact: {
+    paths: [
+      'req.headers.authorization',
+      'req.headers.cookie',
+      '*.password',
+      '*.token',
+      '*.secret',
+      '*.apiKey',
+      '*.creditCard',
+    ],
+    censor: '[REDACTED]',
+  },
+
+  // ✅ Стандартные поля
+  base: {
+    service: config.SERVICE_NAME || 'smart-cart-rescue',
+    env: config.NODE_ENV,
+  },
+
+  // ✅ ISO timestamp вместо epoch
+  timestamp: pino.stdTimeFunctions.isoTime,
+
+  // Pretty print в dev (через transport, не в production)
+  ...(config.NODE_ENV === 'development' && {
+    transport: {
+      target: 'pino-pretty',
+      options: {
+        colorize: true,
+        translateTime: 'HH:MM:ss.l',
+        ignore: 'pid,hostname',
+      },
+    },
+  }),
+});
+```
+
+### Зачем pino, а не winston/console.log?
+
+| Критерий | pino | winston | console.log |
+|---------|------|---------|------------|
+| **Скорость** | ~5x faster | Стандарт | N/A |
+| **JSON output** | Нативный | Через transport | Нет |
+| **Redaction** | Встроенный | Плагин | Нет |
+| **Child loggers** | ✅ | ✅ | Нет |
+| **Async** | ✅ (не блокирует event loop) | ⚠️ | Блокирует |
+| **Production** | ✅ | ✅ | ❌ |
+
+---
+
+## 2. Standard Log Fields
+
+```js
+// Рекомендуемые поля для единообразия (полный набор):
+{
+  // Автоматические (pino)
+  "level": "info",
+  "time": "...",
+  "service": "smart-cart-rescue",
+  "env": "production",
+
+  // Request context
+  "requestId": "abc-123",
+  "method": "POST",
+  "url": "/api/coupons",
+  "status": 201,
+  "durationMs": 45,
+
+  // Business context
+  "event": "coupon_created",     // machine-readable event name
+  "userId": "u-789",
+  "couponId": "c-123",
+
+  // Error context (only for errors)
+  "err": {
+    "message": "...",
+    "stack": "...",
+    "type": "ValidationError"
+  },
+
+  // Message (human-readable)
+  "msg": "Coupon created successfully"
+}
+```
+
+### Structured log пример
+
+```js
+logger.info({
+  event: 'coupon_applied',
+  couponId: 'c-123',
+  orderId: 'o-456',
+  discount: 20,
+  type: 'percent',
+  durationMs: 45,
+}, 'Coupon applied to order');
+
+// Output (JSON):
+// {
+//   "level": "info",
+//   "time": "2026-03-13T03:00:00.000Z",
+//   "service": "smart-cart-rescue",
+//   "event": "coupon_applied",
+//   "couponId": "c-123",
+//   "msg": "Coupon applied to order"
+// }
+```
+
+---
+
+## 3. Request Correlation Middleware
+
+```js
+// middleware/requestId.js
+import { randomUUID } from 'node:crypto';
+
+/**
+ * Добавляет request ID и child logger к каждому запросу.
+ * @param {pino.Logger} logger - root logger.
+ */
+export function requestIdMiddleware(logger) {
+  return (req, _res, next) => {
+    req.id = req.headers['x-request-id'] || randomUUID();
+
+    // ✅ Child logger с request context — все логи автоматически включают requestId
+    req.log = logger.child({ requestId: req.id });
+
+    next();
+  };
+}
+
+// Использование в controller:
+async function createCoupon(req, res) {
+  req.log.info({ code: req.body.code }, 'Creating coupon');
+
+  const coupon = await couponService.create(req.body);
+
+  req.log.info({ couponId: coupon.id }, 'Coupon created');
+  res.status(201).json(coupon);
+}
+```
+
+### Correlation across services (distributed tracing)
+
+```js
+// ✅ Пробрасывать trace_id при вызове внешних сервисов
+async function callPaymentService(orderId, requestId) {
+  return fetch('https://payments.example.com/charge', {
+    headers: {
+      'X-Request-ID': requestId,          // ✅ тот же ID
+      'X-Trace-ID': requestId,            // ✅ для distributed tracing
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ orderId }),
+  });
+}
+```
+
+---
+
+## 4. Redaction Templates
+
+### Полный список redact.paths
+
+```js
+const logger = pino({
+  redact: {
+    paths: [
+      'req.headers.authorization',
+      'req.headers.cookie',
+      '*.password',
+      '*.token',
+      '*.secret',
+      '*.apiKey',
+      '*.ssn',
+      '*.creditCard',
+      '*.cardNumber',
+      '*.cvv',
+    ],
+    censor: '[REDACTED]',
+  },
+});
+
+logger.info({ user: { email: 'a@b.com', password: '123' } });
+// Output: { user: { email: 'a@b.com', password: '[REDACTED]' } }
+```
+
+### Ручные sanitizer helpers
+
+```js
+/**
+ * Маскирует email для логов: a****@example.com
+ * @param {string} email
+ * @returns {string}
+ */
+function maskEmail(email) {
+  const [local, domain] = email.split('@');
+  return `${local[0]}${'*'.repeat(Math.min(local.length - 1, 4))}@${domain}`;
+}
+
+/**
+ * Маскирует номер карты: **** **** **** 1234
+ * @param {string} cardNumber
+ * @returns {string}
+ */
+function maskCard(cardNumber) {
+  return `**** **** **** ${cardNumber.slice(-4)}`;
+}
+
+// Использование:
+logger.info({ email: maskEmail(user.email) }, 'User logged in');
+```
+
+---
+
+## 5. Metrics
+
+### metricsMiddleware (structured logs)
+
+```js
+// middleware/metrics.js
+
+/**
+ * Middleware для измерения latency и error rate.
+ * @param {pino.Logger} logger
+ */
+export function metricsMiddleware(logger) {
+  return (req, res, next) => {
+    const start = performance.now();
+
+    res.on('finish', () => {
+      const durationMs = Math.round(performance.now() - start);
+
+      // ✅ Structured log с метриками — можно строить дашборды
+      logger.info({
+        event: 'http_request',
+        method: req.method,
+        url: req.route?.path ?? req.originalUrl,
+        status: res.statusCode,
+        durationMs,
+        requestId: req.id,
+      });
+
+      // ✅ Warn для медленных запросов
+      if (durationMs > 2000) {
+        logger.warn({
+          event: 'slow_request',
+          method: req.method,
+          url: req.originalUrl,
+          durationMs,
+        }, 'Slow request detected');
+      }
+    });
+
+    next();
+  };
+}
+```
+
+### prom-client setup (Prometheus)
+
+```js
+import { Registry, Counter, Histogram, collectDefaultMetrics } from 'prom-client';
+
+const register = new Registry();
+collectDefaultMetrics({ register });
+
+// HTTP request counter
+const httpRequestsTotal = new Counter({
+  name: 'http_requests_total',
+  help: 'Total HTTP requests',
+  labelNames: ['method', 'route', 'status'],
+  registers: [register],
+});
+
+// HTTP request duration
+const httpRequestDuration = new Histogram({
+  name: 'http_request_duration_seconds',
+  help: 'HTTP request duration in seconds',
+  labelNames: ['method', 'route', 'status'],
+  buckets: [0.01, 0.05, 0.1, 0.5, 1, 2, 5],
+  registers: [register],
+});
+
+// Metrics endpoint
+app.get('/metrics', async (_req, res) => {
+  res.set('Content-Type', register.contentType);
+  res.end(await register.metrics());
+});
+```
+
+### Ключевые метрики
+
+| Метрика | Тип | Зачем |
+|---------|-----|-------|
+| **Request rate** | Counter | Нагрузка |
+| **Error rate** | Counter (status >= 400) | Здоровье |
+| **Latency (p50, p95, p99)** | Histogram | Производительность |
+| **Active connections** | Gauge | Капасити |
+| **DB query duration** | Histogram | Bottlenecks |
+| **Cache hit ratio** | Counter (hit/miss) | Эффективность кэша |
+
+---
+
+## 6. Health Checks
+
+```js
+// ✅ Liveness — приложение живо?
+app.get('/health/live', (_req, res) => {
+  res.json({ status: 'ok' });
+});
+
+// ✅ Readiness — готово обрабатывать запросы? (DB connected, cache warm)
+app.get('/health/ready', async (_req, res) => {
+  try {
+    // Проверяем все зависимости
+    await db.command({ ping: 1 });
+
+    res.json({
+      status: 'ok',
+      checks: {
+        database: 'connected',
+        uptime: process.uptime(),
+      },
+    });
+  } catch (err) {
+    logger.error({ err }, 'Readiness check failed');
+    res.status(503).json({
+      status: 'unhealthy',
+      checks: { database: 'disconnected' },
+    });
+  }
+});
+```
+
+---
+
+## См. также
+- `$observability-logging` — decision rules, anti-patterns, cheat sheet
+- `$security-baseline-dev` — PII/secrets baseline
+- `$node-express-beast-practices-reference` — Express middleware pipeline
+- `$observability-plan` — архитектурный план наблюдаемости
+- `$observability-review` — ревью observability реализации

package/domains/development/.agents/skills/observability-logging-reference/agents/claude.json

@@ -0,0 +1,19 @@
+{
+  "name": "observability-logging-reference",
+  "display_name": "Справочник шаблонов Observability",
+  "description": "Канонический справочник шаблонов observability — pino config с redact paths, standard log fields object, requestId middleware, distributed tracing, маскеры PII (maskEmail/maskCard), metricsMiddleware, prom-client setup, liveness/readiness endpoints. Активируй при поиске конкретного шаблона logger / metrics / health.",
+  "default_prompt": "Используй $observability-logging-reference, когда задача относится к навыку \"Справочник шаблонов Observability\".",
+  "triggers": [
+    "observability-logging-reference",
+    "observability logging reference",
+    "Справочник шаблонов Observability",
+    "Канонический справочник шаблонов observability — pino, redact, structured fields, requestId, metricsMiddleware, prom-client, health"
+  ],
+  "capabilities": [
+    "observability",
+    "logging",
+    "reference"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/domains/development/.agents/skills/observability-logging-reference/agents/copilot.json

@@ -0,0 +1,19 @@
+{
+  "name": "observability-logging-reference",
+  "display_name": "Справочник шаблонов Observability",
+  "description": "Канонический справочник шаблонов observability — pino config с redact paths, standard log fields object, requestId middleware, distributed tracing, маскеры PII (maskEmail/maskCard), metricsMiddleware, prom-client setup, liveness/readiness endpoints. Активируй при поиске конкретного шаблона logger / metrics / health.",
+  "default_prompt": "Используй $observability-logging-reference, когда задача относится к навыку \"Справочник шаблонов Observability\".",
+  "triggers": [
+    "observability-logging-reference",
+    "observability logging reference",
+    "Справочник шаблонов Observability",
+    "Канонический справочник шаблонов observability — pino, redact, structured fields, requestId, metricsMiddleware, prom-client, health"
+  ],
+  "capabilities": [
+    "observability",
+    "logging",
+    "reference"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/domains/development/.agents/skills/observability-logging-reference/agents/gemini.json

@@ -0,0 +1,19 @@
+{
+  "name": "observability-logging-reference",
+  "display_name": "Справочник шаблонов Observability",
+  "description": "Канонический справочник шаблонов observability — pino config с redact paths, standard log fields object, requestId middleware, distributed tracing, маскеры PII (maskEmail/maskCard), metricsMiddleware, prom-client setup, liveness/readiness endpoints. Активируй при поиске конкретного шаблона logger / metrics / health.",
+  "default_prompt": "Используй $observability-logging-reference, когда задача относится к навыку \"Справочник шаблонов Observability\".",
+  "triggers": [
+    "observability-logging-reference",
+    "observability logging reference",
+    "Справочник шаблонов Observability",
+    "Канонический справочник шаблонов observability — pino, redact, structured fields, requestId, metricsMiddleware, prom-client, health"
+  ],
+  "capabilities": [
+    "observability",
+    "logging",
+    "reference"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/domains/development/.agents/skills/observability-logging-reference/agents/kimi.yaml

@@ -0,0 +1,15 @@
+name: "observability-logging-reference"
+display_name: "Справочник шаблонов Observability"
+description: "Канонический справочник шаблонов observability — pino config с redact paths, standard log fields object, requestId middleware, distributed tracing, маскеры PII (maskEmail/maskCard), metricsMiddleware, prom-client setup, liveness/readiness endpoints. Активируй при поиске конкретного шаблона logger / metrics / health."
+default_prompt: "Используй $observability-logging-reference, когда задача относится к навыку \"Справочник шаблонов Observability\"."
+triggers:
+  - "observability-logging-reference"
+  - "observability logging reference"
+  - "Справочник шаблонов Observability"
+  - "Канонический справочник шаблонов observability — pino, redact, structured fields, requestId, metricsMiddleware, prom-client, health"
+capabilities:
+  - "observability"
+  - "logging"
+  - "reference"
+tools: []
+implicit_invocation: true

package/domains/development/.agents/skills/observability-logging-reference/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "Справочник шаблонов Observability"
+  short_description: "Реализация наблюдаемости на уровне кода — структурированные логи (pino), request_id/trace_id ко…"
+  default_prompt: "Используй $observability-logging-reference, когда задача относится к навыку \"Справочник шаблонов Observability\"."
+dependencies:
+  tools: []
+policy:
+  allow_implicit_invocation: true

package/domains/development/.agents/skills/observability-logging-reference/agents/qwen.json

@@ -0,0 +1,19 @@
+{
+  "name": "observability-logging-reference",
+  "display_name": "Справочник шаблонов Observability",
+  "description": "Канонический справочник шаблонов observability — pino config с redact paths, standard log fields object, requestId middleware, distributed tracing, маскеры PII (maskEmail/maskCard), metricsMiddleware, prom-client setup, liveness/readiness endpoints. Активируй при поиске конкретного шаблона logger / metrics / health.",
+  "default_prompt": "Используй $observability-logging-reference, когда задача относится к навыку \"Справочник шаблонов Observability\".",
+  "triggers": [
+    "observability-logging-reference",
+    "observability logging reference",
+    "Справочник шаблонов Observability",
+    "Канонический справочник шаблонов observability — pino, redact, structured fields, requestId, metricsMiddleware, prom-client, health"
+  ],
+  "capabilities": [
+    "observability",
+    "logging",
+    "reference"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/domains/development/.agents/skills/observability-logging-reference/agents/skill.yaml

@@ -0,0 +1,23 @@
+version: 1
+name: "observability-logging-reference"
+display_name: "Справочник шаблонов Observability"
+description: "Канонический справочник шаблонов observability — pino config с redact paths, standard log fields object, requestId middleware, distributed tracing, маскеры PII (maskEmail/maskCard), metricsMiddleware, prom-client setup, liveness/readiness endpoints. Активируй при поиске конкретного шаблона logger / metrics / health."
+default_prompt: "Используй $observability-logging-reference, когда задача относится к навыку \"Справочник шаблонов Observability\"."
+triggers:
+  - "observability-logging-reference"
+  - "observability logging reference"
+  - "Справочник шаблонов Observability"
+  - "Канонический справочник шаблонов observability — pino, redact, structured fields, requestId, metricsMiddleware, prom-client, health"
+capabilities:
+  - "observability"
+  - "logging"
+  - "reference"
+tools: []
+invocation:
+  explicit: true
+  implicit: true
+localization:
+  default_locale: "ru"
+  available_locales:
+    - "ru"
+    - "en"