@verdeect/kit 0.0.0-stage → 1.0.0-rc.2

package/alerts/verdeect-kit.rules.yml

@@ -0,0 +1,133 @@
+# Шаблон правил vmalert для метрик @verdeect/kit — prd.md §3.2 (alertRulesTemplate), AC-2.11, UC-13.
+# Формат правил Prometheus (совместим с vmalert). Путь к файлу в установленном пакете — экспорт alertRulesTemplate
+# из @verdeect/kit/observability.
+#
+# Порог: у каждого правила есть порог по умолчанию и переопределение по метке service. Чтобы задать свой порог,
+# добавьте в файл правил сервиса recording-правило verdeect_kit_threshold:<метрика> с меткой service, например:
+#
+#   - record: verdeect_kit_threshold:outbox_lag_seconds
+#     expr: vector(30)
+#     labels:
+#       service: platform
+#
+# Имена порогов: verdeect_kit_threshold:outbox_pending, :outbox_lag_seconds, :events_consumed (result="dlq"),
+# :db_pool_wait_timeouts, :rate_limit_unavailable, :cleanup_runs. Правая часть каждого правила агрегирована max by (service),
+# чтобы сравнение on (service) group_left () не давало many-to-many.
+groups:
+  - name: verdeect-kit
+    rules:
+      - alert: VerdeectOutboxLag
+        # Порог по умолчанию — 5 с за 1 минуту.
+        expr: |
+          max by (service) (verdeect_outbox_lag_seconds)
+            > on (service) group_left ()
+          (
+            max by (service) (verdeect_kit_threshold:outbox_lag_seconds)
+              or on (service) (max by (service) (verdeect_outbox_lag_seconds) * 0 + 5)
+          )
+        for: 1m
+        labels:
+          severity: warning
+        annotations:
+          summary: 'Задержка outbox {{ $labels.service }} выше порога'
+          description: >-
+            Самая старая неотправленная строка outbox сервиса {{ $labels.service }} ждёт дольше порога
+            (verdeect_outbox_lag_seconds, по умолчанию 5 с) в течение минуты. Проверьте relay в журнале
+            сервиса и доступность брокера.
+
+      - alert: VerdeectOutboxPending
+        # Порог по умолчанию — 1000 строк за 5 минут.
+        expr: |
+          max by (service) (verdeect_outbox_pending)
+            > on (service) group_left ()
+          (
+            max by (service) (verdeect_kit_threshold:outbox_pending)
+              or on (service) (max by (service) (verdeect_outbox_pending) * 0 + 1000)
+          )
+        for: 5m
+        labels:
+          severity: warning
+        annotations:
+          summary: 'Очередь outbox {{ $labels.service }} выше порога'
+          description: >-
+            Неотправленных строк outbox сервиса {{ $labels.service }} больше порога (verdeect_outbox_pending,
+            по умолчанию 1000) в течение 5 минут. Проверьте relay и брокер.
+
+      - alert: VerdeectEventsDlq
+        # Порог по умолчанию — 0: любое событие в DLQ за 15 минут.
+        expr: |
+          sum by (service, type) (increase(verdeect_events_consumed_total{result="dlq"}[15m]))
+            > on (service) group_left ()
+          (
+            max by (service) (verdeect_kit_threshold:events_consumed)
+              or on (service)
+            (
+              max by (service) (
+                sum by (service, type) (increase(verdeect_events_consumed_total{result="dlq"}[15m]))
+              ) * 0
+            )
+          )
+        labels:
+          severity: warning
+        annotations:
+          summary: 'События {{ $labels.type }} сервиса {{ $labels.service }} уходят в DLQ'
+          description: >-
+            За 15 минут события {{ $labels.type }} сервиса {{ $labels.service }} попали в DLQ
+            (verdeect_events_consumed_total, result="dlq"). Разберите сообщения очереди <svc>.dlq по
+            заголовку x-dlq-reason и журналу подписчика; у очередей реплики (<svc>.replica.*) сообщение не
+            сохраняется — смотрите лог и GlitchTip.
+
+      - alert: VerdeectDbPoolWaitTimeouts
+        # Порог по умолчанию — 0: любой срок ожидания пула за 5 минут.
+        expr: |
+          sum by (service) (increase(verdeect_db_pool_wait_timeouts_total[5m]))
+            > on (service) group_left ()
+          (
+            max by (service) (verdeect_kit_threshold:db_pool_wait_timeouts)
+              or on (service)
+            (max by (service) (sum by (service) (increase(verdeect_db_pool_wait_timeouts_total[5m]))) * 0)
+          )
+        labels:
+          severity: warning
+        annotations:
+          summary: 'Пул БД {{ $labels.service }} исчерпан'
+          description: >-
+            За 5 минут запросы сервиса {{ $labels.service }} не дождались клиента пула БД
+            (verdeect_db_pool_wait_timeouts_total). Проверьте DB_POOL_MAX, долгие запросы и нагрузку.
+
+      - alert: VerdeectRateLimitUnavailable
+        # Порог по умолчанию — 0: любая проверка лимита без Redis за 5 минут.
+        expr: |
+          sum by (service) (increase(verdeect_rate_limit_unavailable_total[5m]))
+            > on (service) group_left ()
+          (
+            max by (service) (verdeect_kit_threshold:rate_limit_unavailable)
+              or on (service)
+            (max by (service) (sum by (service) (increase(verdeect_rate_limit_unavailable_total[5m]))) * 0)
+          )
+        labels:
+          severity: warning
+        annotations:
+          summary: 'Лимитер {{ $labels.service }} работает без Redis'
+          description: >-
+            За 5 минут сервис {{ $labels.service }} пропускал запросы без проверки лимита: Redis недоступен
+            (verdeect_rate_limit_unavailable_total). Проверьте доступность Redis.
+
+      - alert: VerdeectCleanupFailing
+        # Порог по умолчанию — 0: любой неудачный или неполный проход очистки за 2 часа.
+        expr: |
+          sum by (service, table, result) (increase(verdeect_cleanup_runs_total{result=~"error|partial"}[2h]))
+            > on (service) group_left ()
+          (
+            max by (service) (verdeect_kit_threshold:cleanup_runs)
+              or on (service) (max by (service) (verdeect_cleanup_runs_total) * 0)
+          )
+        labels:
+          severity: warning
+        annotations:
+          summary: 'Очистка {{ $labels.table }} сервиса {{ $labels.service }}: {{ $labels.result }}'
+          description: >-
+            За 2 часа проход очистки таблицы {{ $labels.table }} сервиса {{ $labels.service }} завершился с итогом
+            {{ $labels.result }} (verdeect_cleanup_runs_total). error — проход упал: ошибка в журнале сервиса
+            («очистка … : ошибка»). partial — проход упёрся в предел пачек, записи старше срока остались: очистка
+            не успевает за потоком записей.

package/dist/cli/commands/crypto.d.ts

@@ -0,0 +1,9 @@
+/** Окружение команды. */
+export interface CryptoCommandContext {
+    /** Запись результата в stdout. */
+    readonly write: (text: string) => void;
+    /** Переменные окружения (по умолчанию `process.env`). */
+    readonly env: Readonly<Record<string, string | undefined>>;
+}
+/** Обработчик команды `crypto`: 0 — секрет в stdout `{"secret":"…"}`, 1 — ошибка (JSON `{error}` в stdout). */
+export declare function cryptoCommand(args: readonly string[], context?: CryptoCommandContext): Promise<number>;

package/dist/cli/commands/crypto.js

@@ -0,0 +1,87 @@
+// Команда verdeect-kit crypto generate-secret [--bytes N] (prd.md §3.6, UC-10, AC-7.5): секрет base64url для
+// ENCRYPTION_KEYS. Образец — commands/rabbitmq.ts. Без pg, ioredis, amqplib: только crypto динамическим import().
+import { parseArgs } from 'node:util';
+import { pino } from 'pino';
+import { z } from 'zod';
+const defaultContext = {
+    write: (text) => void process.stdout.write(text),
+    env: process.env,
+};
+const DEFAULT_BYTES = 32;
+const BYTES_USAGE = '--bytes — целое не меньше 32';
+/** Ошибка команды: JSON в stdout и код 1. */
+class CommandError extends Error {
+    code;
+    extra;
+    constructor(code, message, extra = {}) {
+        super(message);
+        this.code = code;
+        this.extra = extra;
+    }
+}
+async function createLogger(env) {
+    const [{ envBase }, { createLoggerOptions }] = await Promise.all([
+        import('../../config/fragments.js'),
+        import('../../observability/logger-options.js'),
+    ]);
+    const parsed = z
+        .object({ LOG_LEVEL: envBase.LOG_LEVEL, REPLICA_ID: envBase.REPLICA_ID })
+        .safeParse(env);
+    if (!parsed.success) {
+        const keys = [...new Set(parsed.error.issues.map((issue) => issue.path.join('.')))];
+        throw new CommandError('INVALID_ENVIRONMENT', 'Неверное окружение', { keys });
+    }
+    return pino(...createLoggerOptions({ service: 'verdeect-kit', entry: 'cli', env: parsed.data })
+        .pinoHttp);
+}
+/** Разбор `generate-secret [--bytes N]` → число байт. */
+function bytesOf(args) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: [...args],
+            strict: true,
+            allowPositionals: true,
+            options: { bytes: { type: 'string' } },
+        });
+    }
+    catch (error) {
+        throw new CommandError('USAGE', error instanceof Error ? error.message : String(error));
+    }
+    const [sub, ...rest] = parsed.positionals;
+    if (sub !== 'generate-secret' || rest.length > 0) {
+        throw new CommandError('USAGE', 'подкоманда crypto: generate-secret [--bytes N]');
+    }
+    const raw = parsed.values.bytes;
+    if (raw === undefined) {
+        return DEFAULT_BYTES;
+    }
+    if (!/^\d+$/.test(raw) || Number(raw) < DEFAULT_BYTES) {
+        throw new CommandError('USAGE', BYTES_USAGE);
+    }
+    return Number(raw);
+}
+function failureOf(error) {
+    if (error instanceof CommandError) {
+        return { code: error.code, message: error.message, ...error.extra };
+    }
+    return { code: 'CRYPTO_COMMAND_FAILED', message: 'команда crypto завершилась ошибкой' };
+}
+/** Обработчик команды `crypto`: 0 — секрет в stdout `{"secret":"…"}`, 1 — ошибка (JSON `{error}` в stdout). */
+export async function cryptoCommand(args, context = defaultContext) {
+    try {
+        const bytes = bytesOf(args);
+        const logger = await createLogger(context.env);
+        // Только число байт: секрет в лог не попадает.
+        logger.debug({ command: 'crypto', sub: 'generate-secret', bytes }, `crypto generate-secret: ${bytes} байт`);
+        const { generateSecret } = await import('../../crypto/index.js');
+        context.write(`${JSON.stringify({ secret: generateSecret(bytes) })}\n`);
+        return 0;
+    }
+    catch (error) {
+        const failure = failureOf(error);
+        process.stderr.write(`${JSON.stringify({ level: 'error', ...failure })}\n`);
+        context.write(`${JSON.stringify({ error: failure })}\n`);
+        return 1;
+    }
+}

package/dist/cli/commands/db.d.ts

@@ -0,0 +1,11 @@
+/** Окружение команды. */
+export interface DbCommandContext {
+    /** Рабочий каталог (от него — путь `--folder`). */
+    readonly cwd: string;
+    /** Запись строки результата в stdout. */
+    readonly write: (line: string) => void;
+    /** Переменные окружения (по умолчанию `process.env`). */
+    readonly env: Readonly<Record<string, string | undefined>>;
+}
+/** Обработчик команды `db`: 0 — подкоманда выполнена, 1 — ошибка (JSON `{error}` в stdout). */
+export declare function dbCommand(args: readonly string[], context?: DbCommandContext): Promise<number>;

package/dist/cli/commands/db.js

@@ -0,0 +1,151 @@
+// Команда verdeect-kit db prepare|migrate|move-journal (prd.md §3.3 v1.14, AC-4.17, UC-12). Эталон — O run-cli.ts
+// (db:prepare, migrate). Подпути пакета — динамическим import() (ARCHITECTURE «CLI»); окружение — только prepareEnvSchema /
+// migrateEnvSchema и LOG_LEVEL, REPLICA_ID логгера. Текст ошибок pg (имя роли, хост) не выводится.
+import { resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { pino } from 'pino';
+import { z } from 'zod';
+const defaultContext = {
+    cwd: process.cwd(),
+    write: (line) => void process.stdout.write(line),
+    env: process.env,
+};
+const SUBCOMMANDS_MESSAGE = 'подкоманда db: prepare, migrate, move-journal';
+/** Ошибка команды: JSON в stdout и код 1. */
+class CommandError extends Error {
+    code;
+    extra;
+    constructor(code, message, extra = {}) {
+        super(message);
+        this.code = code;
+        this.extra = extra;
+    }
+}
+/** Только имена ключей: значения окружения не выводятся. */
+function invalidEnvironment(error) {
+    const keys = [...new Set(error.issues.map((issue) => issue.path.map(String).join('.')))];
+    return new CommandError('INVALID_ENVIRONMENT', 'Неверное окружение', { keys });
+}
+function parseEnv(schema, env) {
+    const parsed = schema.safeParse(env);
+    if (!parsed.success) {
+        throw invalidEnvironment(parsed.error);
+    }
+    return parsed.data;
+}
+async function createLogger(env) {
+    const [{ envBase }, { createLoggerOptions }] = await Promise.all([
+        import('../../config/fragments.js'),
+        import('../../observability/logger-options.js'),
+    ]);
+    const parsed = parseEnv(z.object({ LOG_LEVEL: envBase.LOG_LEVEL, REPLICA_ID: envBase.REPLICA_ID }), env);
+    return pino(...createLoggerOptions({ service: 'verdeect-kit', entry: 'cli', env: parsed }).pinoHttp);
+}
+/** Опции подкоманды; неизвестная опция или опция без значения — `USAGE`. */
+function parseOptions(args, names) {
+    const options = Object.fromEntries(names.map((name) => [name, { type: 'string' }]));
+    try {
+        return parseArgs({ args: [...args], options, strict: true }).values;
+    }
+    catch (error) {
+        throw new CommandError('USAGE', error instanceof Error ? error.message : String(error));
+    }
+}
+function required(values, names) {
+    for (const name of names) {
+        if (values[name] === undefined) {
+            throw new CommandError('USAGE', `нужна опция --${name}`);
+        }
+    }
+}
+async function prepare(args, context, logger) {
+    const values = parseOptions(args, ['service']);
+    if (values.service === undefined) {
+        throw new CommandError('USAGE', 'нужна опция --service <svc>');
+    }
+    const { SERVICE_NAME_PATTERN } = await import('../../internal/service-name.js');
+    if (!SERVICE_NAME_PATTERN.test(values.service)) {
+        throw new CommandError('USAGE', '--service: имя сервиса вне формата ^[a-z][a-z0-9-]{1,31}$');
+    }
+    const { prepareEnvSchema } = await import('../../config/cli-schemas.js');
+    const env = parseEnv(prepareEnvSchema, context.env);
+    const { prepareDatabase } = await import('../../database/prepare-database.js');
+    const result = await prepareDatabase({
+        service: values.service,
+        adminUrl: env.DATABASE_ADMIN_URL,
+        ownerPassword: env.DB_OWNER_PASSWORD,
+        appPassword: env.DB_APP_PASSWORD,
+    }, logger);
+    return { database: result.database, roles: result.roles, created: result.created };
+}
+async function migrate(args, context, logger) {
+    const values = parseOptions(args, ['folder', 'schema']);
+    required(values, ['folder', 'schema']);
+    const { migrateEnvSchema } = await import('../../config/cli-schemas.js');
+    const env = parseEnv(migrateEnvSchema, context.env);
+    const { runMigrations } = await import('../../database/migrations.js');
+    const schema = values.schema ?? '';
+    const { applied } = await runMigrations({
+        url: env.DATABASE_MIGRATOR_URL,
+        folder: resolve(context.cwd, values.folder ?? ''),
+        schema,
+    }, logger);
+    return { schema, applied };
+}
+async function moveJournal(args, context, logger) {
+    const values = parseOptions(args, ['from', 'to']);
+    required(values, ['from', 'to']);
+    const { migrateEnvSchema } = await import('../../config/cli-schemas.js');
+    const env = parseEnv(migrateEnvSchema, context.env);
+    const migrations = await import('../../database/migrations.js');
+    const from = values.from ?? '';
+    const to = values.to ?? '';
+    const { moved } = await migrations.moveJournal({ url: env.DATABASE_MIGRATOR_URL, from, to }, logger);
+    return { from, to, moved };
+}
+const SUBCOMMANDS = {
+    prepare,
+    migrate,
+    'move-journal': moveJournal,
+};
+/** Перевод ошибки в JSON без адресов, паролей и текста pg; порядок проверок важен — ошибки pg тоже `Error`. */
+async function failureOf(error) {
+    if (error instanceof CommandError) {
+        return { code: error.code, message: error.message, ...error.extra };
+    }
+    const { isConnectionError, sqlStateOf } = await import('../../internal/pg-errors.js');
+    if (isConnectionError(error)) {
+        return { code: 'DATABASE_UNAVAILABLE', message: 'БД недоступна' };
+    }
+    if (error instanceof TypeError || (error instanceof Error && error.name === 'KitUsageError')) {
+        return { code: 'USAGE', message: error.message };
+    }
+    // SQLSTATE — по цепочке cause: у DrizzleQueryError код pg во вложенной ошибке (KT-22 п. 6).
+    const code = sqlStateOf(error);
+    const sqlState = code === null ? {} : { sqlState: code };
+    return { code: 'DB_COMMAND_FAILED', message: 'команда db завершилась ошибкой', ...sqlState };
+}
+async function run(args, context) {
+    const sub = args[0] ?? '';
+    const handler = Object.hasOwn(SUBCOMMANDS, sub) ? SUBCOMMANDS[sub] : undefined;
+    if (handler === undefined) {
+        throw new CommandError('USAGE', SUBCOMMANDS_MESSAGE);
+    }
+    const logger = await createLogger(context.env);
+    logger.debug({ command: 'db', sub }, 'cli: команда');
+    const result = await handler(args.slice(1), context, logger);
+    context.write(`${JSON.stringify(result)}\n`);
+}
+/** Обработчик команды `db`: 0 — подкоманда выполнена, 1 — ошибка (JSON `{error}` в stdout). */
+export async function dbCommand(args, context = defaultContext) {
+    try {
+        await run(args, context);
+        return 0;
+    }
+    catch (error) {
+        const failure = await failureOf(error);
+        process.stderr.write(`${JSON.stringify({ level: 'error', ...failure })}\n`);
+        context.write(`${JSON.stringify({ error: failure })}\n`);
+        return 1;
+    }
+}

package/dist/cli/commands/openapi.d.ts

@@ -0,0 +1,9 @@
+/** Окружение команды. */
+export interface OpenApiCommandContext {
+    /** Рабочий каталог (корень проекта сервиса). */
+    readonly cwd: string;
+    /** Запись строки результата в stdout. */
+    readonly write: (line: string) => void;
+}
+/** Обработчик команды `openapi`: 0 — документ записан, 1 — ошибка (JSON `{error}` в stdout). */
+export declare function openapiCommand(args: readonly string[], context?: OpenApiCommandContext): Promise<number>;

package/dist/cli/commands/openapi.js

@@ -0,0 +1,144 @@
+// Команда `verdeect-kit openapi --out <файл> [--module <файл>#<экспорт>]` (prd.md §3.5, AC-3.7, AC-3.8). Документ —
+// buildOpenApiDocument по метаданным модуля сервиса без создания приложения; окружение сервиса не нужно. title и version
+// — из package.json в cwd; рядом с --out — contracts/openapi.extra.json (глубокое слияние). Подпути пакета загружаются
+// динамическим import() (ARCHITECTURE.md «CLI»). CLI разбирает только свои ключи окружения (LOG_LEVEL, REPLICA_ID).
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { parseArgs } from 'node:util';
+import { pino } from 'pino';
+import { z } from 'zod';
+/** Модуль сервиса по умолчанию (§3.5), относительно cwd. */
+const DEFAULT_MODULE = 'dist/app.module.js#AppModule';
+const defaultContext = {
+    cwd: process.cwd(),
+    write: (line) => void process.stdout.write(line),
+};
+/** Ошибка команды: JSON в stdout и код 1. */
+class CommandError extends Error {
+    code;
+    extra;
+    constructor(code, message, extra = {}) {
+        super(message);
+        this.code = code;
+        this.extra = extra;
+    }
+}
+async function createLogger() {
+    const [{ envBase }, { createLoggerOptions }] = await Promise.all([
+        import('../../config/fragments.js'),
+        import('../../observability/logger-options.js'),
+    ]);
+    const parsed = z
+        .object({ LOG_LEVEL: envBase.LOG_LEVEL, REPLICA_ID: envBase.REPLICA_ID })
+        .safeParse(process.env);
+    if (!parsed.success) {
+        // Только имена ключей: значения окружения не выводятся.
+        const keys = [
+            ...new Set(parsed.error.issues.map((issue) => issue.path.map(String).join('.'))),
+        ];
+        throw new CommandError('INVALID_ENVIRONMENT', 'Неверное окружение', { keys });
+    }
+    return pino(...createLoggerOptions({ service: 'verdeect-kit', entry: 'cli', env: parsed.data })
+        .pinoHttp);
+}
+async function packageInfo(cwd) {
+    const path = join(cwd, 'package.json');
+    let manifest;
+    try {
+        manifest = JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch {
+        throw new CommandError('INVALID_PACKAGE_JSON', `нет или не разобран ${path}`);
+    }
+    const parsed = z
+        .object({ name: z.string().min(1), version: z.string().min(1) })
+        .safeParse(manifest);
+    if (!parsed.success) {
+        throw new CommandError('INVALID_PACKAGE_JSON', `в ${path} нужны поля name и version (info.version обязателен в OpenAPI 3.1)`);
+    }
+    return { title: parsed.data.name, version: parsed.data.version };
+}
+async function loadModule(cwd, spec) {
+    const hash = spec.lastIndexOf('#');
+    const file = hash === -1 ? spec : spec.slice(0, hash);
+    const name = hash === -1 ? 'AppModule' : spec.slice(hash + 1);
+    const path = resolve(cwd, file);
+    if (!existsSync(path)) {
+        throw new CommandError('MODULE_NOT_FOUND', `файл модуля не найден: ${file}`);
+    }
+    const loaded = (await import(pathToFileURL(path).href));
+    const module = loaded[name];
+    if (module === undefined) {
+        throw new CommandError('MODULE_NOT_FOUND', `в ${file} нет экспорта ${name}`);
+    }
+    return module;
+}
+async function readExtra(path) {
+    if (!existsSync(path)) {
+        return null;
+    }
+    let value;
+    try {
+        value = JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch {
+        throw new CommandError('INVALID_EXTRA', `${path}: не разобран как JSON`);
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new CommandError('INVALID_EXTRA', `${path}: ожидается объект JSON`);
+    }
+    return value;
+}
+/** Опции команды; неизвестная опция или опция без значения — `USAGE`. */
+function parseOptions(args) {
+    try {
+        return parseArgs({
+            args: [...args],
+            options: { out: { type: 'string' }, module: { type: 'string' } },
+            strict: true,
+        }).values;
+    }
+    catch (error) {
+        throw new CommandError('USAGE', error instanceof Error ? error.message : String(error));
+    }
+}
+async function run(args, context) {
+    const values = parseOptions(args);
+    if (values.out === undefined) {
+        throw new CommandError('USAGE', 'нужна опция --out <файл>');
+    }
+    const logger = await createLogger();
+    logger.debug({ command: 'openapi' }, 'cli: команда');
+    const info = await packageInfo(context.cwd);
+    const module = await loadModule(context.cwd, values.module ?? DEFAULT_MODULE);
+    const { buildOpenApiDocument, deepMerge } = await import('../../http/api/openapi-document.js');
+    const out = resolve(context.cwd, values.out);
+    const built = await buildOpenApiDocument(module, info, logger);
+    const extra = await readExtra(join(dirname(out), 'openapi.extra.json'));
+    const document = extra === null ? { ...built } : deepMerge({ ...built }, extra);
+    await mkdir(dirname(out), { recursive: true });
+    await writeFile(out, `${JSON.stringify(document, null, 2)}\n`, 'utf8');
+    const operations = Object.values(built.paths).reduce((count, item) => count + Object.keys(item).length, 0);
+    logger.info({ out: values.out, operations }, 'openapi: записан');
+    context.write(`${JSON.stringify({ written: values.out, operations })}\n`);
+}
+/** Обработчик команды `openapi`: 0 — документ записан, 1 — ошибка (JSON `{error}` в stdout). */
+export async function openapiCommand(args, context = defaultContext) {
+    try {
+        await run(args, context);
+        return 0;
+    }
+    catch (error) {
+        const failure = error instanceof CommandError
+            ? { code: error.code, message: error.message, ...error.extra }
+            : {
+                code: 'OPENAPI_FAILED',
+                message: error instanceof Error ? error.message : String(error),
+            };
+        process.stderr.write(`${JSON.stringify({ level: 'error', ...failure })}\n`);
+        context.write(`${JSON.stringify({ error: failure })}\n`);
+        return 1;
+    }
+}

package/dist/cli/commands/rabbitmq.d.ts

@@ -0,0 +1,11 @@
+/** Окружение команды. */
+export interface RabbitmqCommandContext {
+    /** Рабочий каталог (от него — путь `--out`). */
+    readonly cwd: string;
+    /** Запись результата в stdout. */
+    readonly write: (text: string) => void;
+    /** Переменные окружения (по умолчанию `process.env`). */
+    readonly env: Readonly<Record<string, string | undefined>>;
+}
+/** Обработчик команды `rabbitmq`: 0 — definitions собраны, 1 — ошибка (JSON `{error}` в stdout). */
+export declare function rabbitmqCommand(args: readonly string[], context?: RabbitmqCommandContext): Promise<number>;