code-ai-installer 3.0.0 → 4.0.1-a

package/domains/development/.agents/skills/node-express-beast-practices/agents/kimi.yaml

@@ -1,16 +1,16 @@
-name: "node-express-beast-practices"
-display_name: "Практики Node и Express"
-description: "Node.js + Express — REST API, middleware pipeline, сервисный слой, репозитории, централизованная обработка ошибок, валидация (Zod), graceful shutdown, health checks, security headers. Активируй при написании API, рефакторинге Express-приложений, или при вопросах «как правильно организовать backend на Express»."
-default_prompt: "Используй $node-express-beast-practices, когда задача относится к навыку \"Практики Node и Express\"."
-triggers:
-  - "node-express-beast-practices"
-  - "node express beast practices"
-  - "Практики Node и Express"
-  - "Node"
-capabilities:
-  - "node"
-  - "express"
-  - "beast"
-  - "practices"
-tools: []
-implicit_invocation: true
+name: "node-express-beast-practices"
+display_name: "Практики Node и Express"
+description: "Node.js + Express — REST API, middleware pipeline, сервисный слой, репозитории, централизованная обработка ошибок, валидация (Zod), graceful shutdown, health checks, security headers. Активируй при написании API, рефакторинге Express-приложений, или при вопросах «как правильно организовать backend на Express»."
+default_prompt: "Используй $node-express-beast-practices, когда задача относится к навыку \"Практики Node и Express\"."
+triggers:
+  - "node-express-beast-practices"
+  - "node express beast practices"
+  - "Практики Node и Express"
+  - "Node"
+capabilities:
+  - "node"
+  - "express"
+  - "beast"
+  - "practices"
+tools: []
+implicit_invocation: true

package/domains/development/.agents/skills/node-express-beast-practices-reference/SKILL.md

@@ -0,0 +1,618 @@
+---
+name: node-express-beast-practices-reference
+description: "Канонический справочник кода Node.js + Express — детальные DO/DON'T примеры по 7 темам — App Factory, Router+Controller, Middleware Pipeline, обработка ошибок, валидация (Zod), Service+Repository, Graceful Shutdown. Активируй при поиске конкретного кодового паттерна."
+type: reference
+domain: development
+owners:
+  - senior_full_stack
+gates:
+  - DEV
+tech:
+  - node
+  - express
+topic:
+  - general
+triggers:
+  - Express код пример
+  - createApp factory код
+  - asyncHandler wrapper
+  - AppError классы Express
+  - Zod validate middleware
+  - service repository Express
+  - graceful shutdown Express код
+related:
+  - node-express-beast-practices
+  - security-baseline-dev
+  - security-baseline-dev-reference
+  - observability-logging
+  - es2025-beast-practices
+  - testing-strategy-js
+  - mongodb-mongoose-best-practices
+  - mongodb-mongoose-best-practices-reference
+  - tdd-workflow
+  - dev-reference-snippets
+budget_lines: 750
+schema_version: 1
+---
+
+
+# Skill: Node/Express Code Reference (DO/DON'T)
+
+Канонический справочник кодовых паттернов Node.js + Express. Decision rules + canonical tables — в `$node-express-beast-practices`.
+
+**Разделы:**
+2. [App Factory](#2-app-factory)
+3. [Router + Controller](#3-router--controller)
+4. [Middleware Pipeline](#4-middleware-pipeline)
+5. [Обработка ошибок](#5-обработка-ошибок)
+6. [Валидация (Zod)](#6-валидация)
+7. [Service + Repository](#7-service--repository)
+8. [Graceful Shutdown](#8-graceful-shutdown)
+
+> §1 Layers table, §4 Middleware order list, §5 HTTP Status Codes table, §9 Anti-patterns table — живут в workflow `$node-express-beast-practices`.
+
+---
+
+## 2. App Factory
+
+### ✅ DO: app отдельно от server (тестируемость)
+
+```js
+// app.js — чистый Express app, без listen()
+import express from 'express';
+import helmet from 'helmet';
+import cors from 'cors';
+import compression from 'compression';
+import { requestIdMiddleware } from './middleware/requestId.js';
+import { errorHandler } from './middleware/errorHandler.js';
+import { routes } from './routes/index.js';
+
+/**
+ * Создаёт и конфигурирует Express приложение.
+ * @param {{ db: object, logger: object }} deps - зависимости.
+ * @returns {express.Express} сконфигурированное приложение.
+ */
+export function createApp(deps) {
+  const app = express();
+
+  // ── Security ──
+  app.use(helmet());
+  app.use(cors({ origin: deps.config?.corsOrigin ?? '*' }));
+
+  // ── Parsing ──
+  app.use(express.json({ limit: '1mb' }));
+  app.use(express.urlencoded({ extended: false }));
+
+  // ── Compression ──
+  app.use(compression());
+
+  // ── Request ID ──
+  app.use(requestIdMiddleware);
+
+  // ── Routes ──
+  app.use('/api', routes(deps));
+
+  // ── Health ──
+  app.get('/health', (_req, res) => res.json({ status: 'ok' }));
+
+  // ── 404 ──
+  app.use((_req, _res, next) => {
+    next(new AppError('Route not found', 404));
+  });
+
+  // ── Error Handler (MUST be last) ──
+  app.use(errorHandler(deps.logger));
+
+  return app;
+}
+```
+
+```js
+// server.js — HTTP сервер + graceful shutdown
+import { createApp } from './app.js';
+import { config } from './config/env.js';
+import { logger } from './utils/logger.js';
+import { connectDb } from './db/connection.js';
+
+async function main() {
+  const db = await connectDb(config.databaseUrl);
+  const app = createApp({ db, logger, config });
+
+  const server = app.listen(config.port, () => {
+    logger.info({ port: config.port }, 'Server started');
+  });
+
+  // Graceful shutdown (см. §8)
+  setupGracefulShutdown(server, db);
+}
+
+main().catch((err) => {
+  console.error('Fatal startup error:', err);
+  process.exit(1);
+});
+```
+
+---
+
+## 3. Router + Controller
+
+### ✅ DO: тонкие контроллеры, бизнес-логика в service
+
+```js
+// routes/coupons.router.js
+import { Router } from 'express';
+import { CouponController } from '../controllers/coupons.controller.js';
+import { validate } from '../middleware/validate.js';
+import { createCouponSchema, updateCouponSchema } from '../schemas/coupon.schema.js';
+
+export function couponRouter(deps) {
+  const router = Router();
+  const ctrl = new CouponController(deps);
+
+  router.get('/',        ctrl.list);
+  router.get('/:id',     ctrl.getById);
+  router.post('/',       validate(createCouponSchema), ctrl.create);
+  router.patch('/:id',   validate(updateCouponSchema), ctrl.update);
+  router.delete('/:id',  ctrl.remove);
+
+  return router;
+}
+```
+
+```js
+// controllers/coupons.controller.js
+import { asyncHandler } from '../utils/asyncHandler.js';
+import { CouponService } from '../services/coupon.service.js';
+
+export class CouponController {
+  #service;
+
+  constructor(deps) {
+    this.#service = new CouponService(deps);
+  }
+
+  list = asyncHandler(async (req, res) => {
+    const { page = 1, limit = 20 } = req.query;
+    const result = await this.#service.list({ page: +page, limit: +limit });
+    res.json(result);
+  });
+
+  getById = asyncHandler(async (req, res) => {
+    const coupon = await this.#service.getById(req.params.id);
+    res.json(coupon);
+  });
+
+  create = asyncHandler(async (req, res) => {
+    const coupon = await this.#service.create(req.body);
+    res.status(201).json(coupon);
+  });
+
+  update = asyncHandler(async (req, res) => {
+    const coupon = await this.#service.update(req.params.id, req.body);
+    res.json(coupon);
+  });
+
+  remove = asyncHandler(async (req, res) => {
+    await this.#service.remove(req.params.id);
+    res.status(204).end();
+  });
+}
+```
+
+### ✅ DO: asyncHandler для автоматического перехвата ошибок
+
+```js
+// utils/asyncHandler.js
+
+/**
+ * Оборачивает async controller в try/catch, передавая ошибку в next().
+ */
+export function asyncHandler(fn) {
+  return (req, res, next) => {
+    Promise.resolve(fn(req, res, next)).catch(next);
+  };
+}
+```
+
+---
+
+## 4. Middleware Pipeline
+
+### ✅ DO: request ID middleware
+
+```js
+// middleware/requestId.js
+import { randomUUID } from 'node:crypto';
+
+/**
+ * Добавляет request ID к каждому запросу для корреляции логов.
+ */
+export function requestIdMiddleware(req, _res, next) {
+  req.id = req.headers['x-request-id'] || randomUUID();
+  next();
+}
+```
+
+### ✅ DO: request logging middleware
+
+```js
+// middleware/requestLog.js
+
+/**
+ * Логирует HTTP запросы с длительностью.
+ */
+export function requestLogMiddleware(logger) {
+  return (req, res, next) => {
+    const start = performance.now();
+
+    res.on('finish', () => {
+      const duration = Math.round(performance.now() - start);
+      logger.info({
+        method: req.method,
+        url: req.originalUrl,
+        status: res.statusCode,
+        durationMs: duration,
+        requestId: req.id,
+      });
+    });
+
+    next();
+  };
+}
+```
+
+---
+
+## 5. Обработка ошибок
+
+### ✅ DO: кастомный AppError
+
+```js
+// errors/AppError.js
+
+/**
+ * Базовый класс ошибки приложения с HTTP-кодом.
+ */
+export class AppError extends Error {
+  constructor(message, statusCode = 500, details = undefined) {
+    super(message);
+    this.name = 'AppError';
+    this.statusCode = statusCode;
+    this.details = details;
+    this.isOperational = true; // отличает от programmer errors
+  }
+}
+
+export class NotFoundError extends AppError {
+  constructor(resource = 'Resource') {
+    super(`${resource} not found`, 404);
+  }
+}
+
+export class ValidationError extends AppError {
+  constructor(details) {
+    super('Validation failed', 400, details);
+  }
+}
+
+export class ConflictError extends AppError {
+  constructor(message = 'Resource already exists') {
+    super(message, 409);
+  }
+}
+
+export class UnauthorizedError extends AppError {
+  constructor(message = 'Authentication required') {
+    super(message, 401);
+  }
+}
+
+export class ForbiddenError extends AppError {
+  constructor(message = 'Access denied') {
+    super(message, 403);
+  }
+}
+```
+
+### ✅ DO: централизованный error handler
+
+```js
+// middleware/errorHandler.js
+
+/**
+ * Централизованный обработчик ошибок Express.
+ * MUST be the last middleware in the pipeline.
+ */
+export function errorHandler(logger) {
+  // eslint-disable-next-line no-unused-vars -- Express requires 4 params for error middleware
+  return (err, req, res, _next) => {
+    // Operational errors (expected)
+    if (err.isOperational) {
+      logger.warn({
+        err: { message: err.message, statusCode: err.statusCode },
+        requestId: req.id,
+      });
+
+      return res.status(err.statusCode).json({
+        error: err.message,
+        ...(err.details && { details: err.details }),
+      });
+    }
+
+    // Programmer errors (unexpected) — log full stack, return generic message
+    logger.error({
+      err,
+      requestId: req.id,
+      method: req.method,
+      url: req.originalUrl,
+    });
+
+    res.status(500).json({
+      error: 'Internal server error',
+      // ❌ NEVER expose stack trace or internal details
+    });
+  };
+}
+```
+
+> Полная HTTP Status Codes table (200/201/204/400/401/403/404/409/422/429/500) → workflow `$node-express-beast-practices` §5.
+
+---
+
+## 6. Валидация
+
+### ✅ DO: Zod schema + validation middleware
+
+```js
+// schemas/coupon.schema.js
+import { z } from 'zod';
+
+export const createCouponSchema = z.object({
+  body: z.object({
+    code: z.string().min(3).max(20).toUpperCase(),
+    discount: z.number().min(1).max(100),
+    type: z.enum(['percent', 'fixed']),
+    expiresAt: z.string().datetime().optional(),
+  }),
+});
+
+export const updateCouponSchema = z.object({
+  params: z.object({
+    id: z.string().uuid(),
+  }),
+  body: z.object({
+    code: z.string().min(3).max(20).toUpperCase().optional(),
+    discount: z.number().min(1).max(100).optional(),
+    active: z.boolean().optional(),
+  }),
+});
+```
+
+```js
+// middleware/validate.js
+import { AppError } from '../errors/AppError.js';
+
+/**
+ * Middleware для валидации req через Zod schema.
+ */
+export function validate(schema) {
+  return (req, _res, next) => {
+    const result = schema.safeParse({
+      body: req.body,
+      query: req.query,
+      params: req.params,
+    });
+
+    if (!result.success) {
+      const errors = result.error.issues.map((issue) => ({
+        path: issue.path.join('.'),
+        message: issue.message,
+      }));
+      return next(new AppError('Validation failed', 400, errors));
+    }
+
+    // ✅ Заменяем req данные на parsed (coerced, defaults applied)
+    req.body = result.data.body ?? req.body;
+    req.query = result.data.query ?? req.query;
+    req.params = result.data.params ?? req.params;
+
+    next();
+  };
+}
+```
+
+---
+
+## 7. Service + Repository
+
+### ✅ DO: service layer для бизнес-логики
+
+```js
+// services/coupon.service.js
+import { CouponRepo } from '../repositories/coupon.repo.js';
+import { NotFoundError, ConflictError } from '../errors/AppError.js';
+
+export class CouponService {
+  #repo;
+
+  constructor({ db }) {
+    this.#repo = new CouponRepo(db);
+  }
+
+  async list({ page, limit }) {
+    const offset = (page - 1) * limit;
+    const [data, total] = await Promise.all([
+      this.#repo.findAll({ offset, limit }),
+      this.#repo.count(),
+    ]);
+    return { data, total, page, limit };
+  }
+
+  async getById(id) {
+    const coupon = await this.#repo.findById(id);
+    if (!coupon) throw new NotFoundError('Coupon');
+    return coupon;
+  }
+
+  async create(data) {
+    const existing = await this.#repo.findByCode(data.code);
+    if (existing) throw new ConflictError(`Coupon code "${data.code}" already exists`);
+    return this.#repo.create(data);
+  }
+
+  async update(id, data) {
+    await this.getById(id); // throws NotFoundError
+    return this.#repo.update(id, data);
+  }
+
+  async remove(id) {
+    await this.getById(id);
+    return this.#repo.remove(id);
+  }
+}
+```
+
+### ✅ DO: repository для доступа к данным
+
+```js
+// repositories/coupon.repo.js
+
+export class CouponRepo {
+  #db;
+
+  constructor(db) {
+    this.#db = db;
+  }
+
+  async findAll({ offset, limit }) {
+    return this.#db.collection('coupons')
+      .find({})
+      .skip(offset)
+      .limit(limit)
+      .toArray();
+  }
+
+  async findById(id) {
+    return this.#db.collection('coupons').findOne({ _id: id });
+  }
+
+  async findByCode(code) {
+    return this.#db.collection('coupons').findOne({ code });
+  }
+
+  async count() {
+    return this.#db.collection('coupons').countDocuments();
+  }
+
+  async create(data) {
+    const result = await this.#db.collection('coupons').insertOne({
+      ...data,
+      active: true,
+      createdAt: new Date(),
+    });
+    return { _id: result.insertedId, ...data };
+  }
+
+  async update(id, data) {
+    const result = await this.#db.collection('coupons').findOneAndUpdate(
+      { _id: id },
+      { $set: { ...data, updatedAt: new Date() } },
+      { returnDocument: 'after' }
+    );
+    return result;
+  }
+
+  async remove(id) {
+    await this.#db.collection('coupons').deleteOne({ _id: id });
+  }
+}
+```
+
+---
+
+## 8. Graceful Shutdown
+
+### ✅ DO: graceful shutdown + health check
+
+```js
+// server.js (фрагмент)
+
+/**
+ * Настраивает graceful shutdown.
+ */
+function setupGracefulShutdown(server, db) {
+  let isShuttingDown = false;
+
+  async function shutdown(signal) {
+    if (isShuttingDown) return;
+    isShuttingDown = true;
+
+    logger.info({ signal }, 'Graceful shutdown started');
+
+    // 1. Stop accepting new connections
+    server.close(async () => {
+      try {
+        // 2. Close DB connections
+        await db.close();
+        logger.info('Graceful shutdown complete');
+        process.exit(0);
+      } catch (err) {
+        logger.error({ err }, 'Error during shutdown');
+        process.exit(1);
+      }
+    });
+
+    // 3. Force kill after timeout
+    setTimeout(() => {
+      logger.error('Forced shutdown after timeout');
+      process.exit(1);
+    }, 10_000);
+  }
+
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+  process.on('SIGINT', () => shutdown('SIGINT'));
+
+  // Unhandled errors — log and exit
+  process.on('unhandledRejection', (reason) => {
+    logger.fatal({ reason }, 'Unhandled rejection');
+    process.exit(1);
+  });
+}
+```
+
+### ✅ DO: env validation
+
+```js
+// config/env.js
+import { z } from 'zod';
+
+const envSchema = z.object({
+  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+  PORT: z.coerce.number().default(3000),
+  DATABASE_URL: z.string().url(),
+  CORS_ORIGIN: z.string().default('*'),
+  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
+});
+
+const parsed = envSchema.safeParse(process.env);
+
+if (!parsed.success) {
+  console.error('Invalid environment variables:', parsed.error.flatten().fieldErrors);
+  process.exit(1);
+}
+
+export const config = parsed.data;
+```
+
+---
+
+## См. также
+- `$node-express-beast-practices` — decision rules + Layers/Middleware-order/HTTP-status/Anti-pattern tables
+- `$security-baseline-dev` — безопасность в реализации
+- `$observability-logging` — структурированные логи и метрики
+- `$es2025-beast-practices` — современный JavaScript
+- `$testing-strategy-js` — тестирование API (integration tests)
+- `$tdd-workflow` — RED→GREEN→REFACTOR
+- `$mongodb-mongoose-best-practices` — MongoDB/Mongoose (repository layer)
+- `$mongodb-mongoose-best-practices-reference` — Mongo code reference
+- `$dev-reference-snippets` — общие dev примеры

package/domains/development/.agents/skills/node-express-beast-practices-reference/agents/claude.json

@@ -0,0 +1,19 @@
+{
+  "name": "node-express-beast-practices-reference",
+  "display_name": "Справочник кода Node и Express (DO/DON'T)",
+  "description": "Канонический справочник кода Node.js + Express — детальные DO/DON'T примеры по 7 темам — App Factory, Router+Controller, Middleware Pipeline, обработка ошибок, валидация (Zod), Service+Repository, Graceful Shutdown. Активируй при поиске конкретного кодового паттерна.",
+  "default_prompt": "Используй $node-express-beast-practices-reference, когда задача относится к навыку \"Справочник кода Node и Express (DO/DON'T)\".",
+  "triggers": [
+    "node-express-beast-practices-reference",
+    "node express beast practices reference",
+    "Справочник кода Node и Express (DO/DON'T)",
+    "Node"
+  ],
+  "capabilities": [
+    "node",
+    "express",
+    "reference"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/domains/development/.agents/skills/node-express-beast-practices-reference/agents/copilot.json

@@ -0,0 +1,19 @@
+{
+  "name": "node-express-beast-practices-reference",
+  "display_name": "Справочник кода Node и Express (DO/DON'T)",
+  "description": "Канонический справочник кода Node.js + Express — детальные DO/DON'T примеры по 7 темам — App Factory, Router+Controller, Middleware Pipeline, обработка ошибок, валидация (Zod), Service+Repository, Graceful Shutdown. Активируй при поиске конкретного кодового паттерна.",
+  "default_prompt": "Используй $node-express-beast-practices-reference, когда задача относится к навыку \"Справочник кода Node и Express (DO/DON'T)\".",
+  "triggers": [
+    "node-express-beast-practices-reference",
+    "node express beast practices reference",
+    "Справочник кода Node и Express (DO/DON'T)",
+    "Node"
+  ],
+  "capabilities": [
+    "node",
+    "express",
+    "reference"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/domains/development/.agents/skills/node-express-beast-practices-reference/agents/gemini.json

@@ -0,0 +1,19 @@
+{
+  "name": "node-express-beast-practices-reference",
+  "display_name": "Справочник кода Node и Express (DO/DON'T)",
+  "description": "Канонический справочник кода Node.js + Express — детальные DO/DON'T примеры по 7 темам — App Factory, Router+Controller, Middleware Pipeline, обработка ошибок, валидация (Zod), Service+Repository, Graceful Shutdown. Активируй при поиске конкретного кодового паттерна.",
+  "default_prompt": "Используй $node-express-beast-practices-reference, когда задача относится к навыку \"Справочник кода Node и Express (DO/DON'T)\".",
+  "triggers": [
+    "node-express-beast-practices-reference",
+    "node express beast practices reference",
+    "Справочник кода Node и Express (DO/DON'T)",
+    "Node"
+  ],
+  "capabilities": [
+    "node",
+    "express",
+    "reference"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}