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

package/dist/cli/commands/rabbitmq.js

@@ -0,0 +1,124 @@
+// Команда verdeect-kit rabbitmq definitions (prd.md §3.4 M3, UC-12, AC-5.10): definitions.json для брокера — vhost,
+// пользователи сервисов с хешами паролей из RABBITMQ_PASSWORD_HASH_<SVC> (П3), права, exchange verdeect.events. Образец —
+// commands/db.ts. Без amqplib, pg и messaging: только internal/rabbitmq-definitions динамическим import().
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { pino } from 'pino';
+import { z } from 'zod';
+const defaultContext = {
+    cwd: process.cwd(),
+    write: (text) => void process.stdout.write(text),
+    env: process.env,
+};
+/** base64 соли (4 байта) и sha256 (32 байта) — не короче 44 знаков. */
+const HASH_FORMAT = /^[A-Za-z0-9+/]+={0,2}$/;
+const MIN_HASH_LENGTH = 44;
+/** Ошибка команды: 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);
+}
+function parseOptions(args) {
+    try {
+        return parseArgs({
+            args: [...args],
+            strict: true,
+            options: { services: { type: 'string' }, out: { type: 'string' } },
+        }).values;
+    }
+    catch (error) {
+        throw new CommandError('USAGE', error instanceof Error ? error.message : String(error));
+    }
+}
+async function servicesOf(raw) {
+    const services = (raw ?? '')
+        .split(',')
+        .map((name) => name.trim())
+        .filter((name) => name !== '');
+    if (services.length === 0) {
+        throw new CommandError('USAGE', 'нужна опция --services <svc,…>');
+    }
+    const { SERVICE_NAME_PATTERN } = await import('../../internal/service-name.js');
+    const bad = services.find((name) => !SERVICE_NAME_PATTERN.test(name));
+    if (bad !== undefined) {
+        throw new CommandError('USAGE', `--services: имя «${bad}» вне формата ^[a-z][a-z0-9-]{1,31}$`);
+    }
+    if (new Set(services).size !== services.length) {
+        throw new CommandError('USAGE', '--services: имя указано дважды');
+    }
+    return services;
+}
+async function definitions(args, context, logger) {
+    const values = parseOptions(args);
+    const services = await servicesOf(values.services);
+    const { buildDefinitions, passwordHashKey } = await import('../../internal/rabbitmq-definitions.js');
+    // Только имена ключей в ошибке: значения хешей не выводятся.
+    const keys = [];
+    const users = services.map((service) => {
+        const key = passwordHashKey(service);
+        const hash = context.env[key] ?? '';
+        if (hash.length < MIN_HASH_LENGTH || !HASH_FORMAT.test(hash)) {
+            keys.push(key);
+        }
+        return { service, passwordHash: hash };
+    });
+    if (keys.length > 0) {
+        throw new CommandError('INVALID_ENVIRONMENT', 'Неверное окружение', { keys });
+    }
+    const json = `${JSON.stringify(buildDefinitions({ users }), null, 2)}\n`;
+    if (values.out === undefined) {
+        context.write(json);
+        logger.info({ services }, 'rabbitmq definitions: собрано');
+        return;
+    }
+    const out = resolve(context.cwd, values.out);
+    await mkdir(dirname(out), { recursive: true });
+    await writeFile(out, json);
+    context.write(`${JSON.stringify({ out, services })}\n`);
+    logger.info({ services, out }, 'rabbitmq definitions: собрано');
+}
+function failureOf(error) {
+    if (error instanceof CommandError) {
+        return { code: error.code, message: error.message, ...error.extra };
+    }
+    return { code: 'RABBITMQ_COMMAND_FAILED', message: 'команда rabbitmq завершилась ошибкой' };
+}
+/** Обработчик команды `rabbitmq`: 0 — definitions собраны, 1 — ошибка (JSON `{error}` в stdout). */
+export async function rabbitmqCommand(args, context = defaultContext) {
+    try {
+        if (args[0] !== 'definitions') {
+            throw new CommandError('USAGE', 'подкоманда rabbitmq: definitions');
+        }
+        const logger = await createLogger(context.env);
+        logger.debug({ command: 'rabbitmq', sub: 'definitions' }, 'cli: команда');
+        await definitions(args.slice(1), context, logger);
+        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/redis.d.ts

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

package/dist/cli/commands/redis.js

@@ -0,0 +1,119 @@
+// Команда verdeect-kit redis acl (prd.md §3.7, UC-12; D3 плана E8): aclfile Redis — `user default off`, пользователи
+// сервисов с sha256 паролей из REDIS_PASSWORD_HASH_<SVC>, ключи и каналы <svc>:*. Образец — commands/rabbitmq.ts. Без
+// ioredis: только internal/redis-acl динамическим import(). aclfile — не JSON, поэтому --out обязателен.
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { pino } from 'pino';
+import { z } from 'zod';
+const defaultContext = {
+    cwd: process.cwd(),
+    write: (text) => void process.stdout.write(text),
+    env: process.env,
+};
+/** Ошибка команды: 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);
+}
+function parseOptions(args) {
+    try {
+        return parseArgs({
+            args: [...args],
+            strict: true,
+            options: { services: { type: 'string' }, out: { type: 'string' } },
+        }).values;
+    }
+    catch (error) {
+        throw new CommandError('USAGE', error instanceof Error ? error.message : String(error));
+    }
+}
+/** Копия servicesOf из rabbitmq.ts: та бросает свой CommandError, и failureOf здесь его не узнал бы. */
+async function servicesOf(raw) {
+    const services = (raw ?? '')
+        .split(',')
+        .map((name) => name.trim())
+        .filter((name) => name !== '');
+    if (services.length === 0) {
+        throw new CommandError('USAGE', 'нужна опция --services <svc,…>');
+    }
+    const { SERVICE_NAME_PATTERN } = await import('../../internal/service-name.js');
+    const bad = services.find((name) => !SERVICE_NAME_PATTERN.test(name));
+    if (bad !== undefined) {
+        throw new CommandError('USAGE', `--services: имя «${bad}» вне формата ^[a-z][a-z0-9-]{1,31}$`);
+    }
+    if (new Set(services).size !== services.length) {
+        throw new CommandError('USAGE', '--services: имя указано дважды');
+    }
+    return services;
+}
+async function acl(args, context, logger) {
+    const values = parseOptions(args);
+    const services = await servicesOf(values.services);
+    if (values.out === undefined) {
+        throw new CommandError('USAGE', 'нужна опция --out <файл>: aclfile — не JSON');
+    }
+    const { buildRedisAclFile, redisPasswordHashKey, REDIS_PASSWORD_HASH } = await import('../../internal/redis-acl.js');
+    // Только имена ключей в ошибке: значения хешей не выводятся.
+    const keys = [];
+    const users = services.map((service) => {
+        const key = redisPasswordHashKey(service);
+        const hash = context.env[key] ?? '';
+        if (!REDIS_PASSWORD_HASH.test(hash)) {
+            keys.push(key);
+        }
+        return { service, passwordHash: hash };
+    });
+    if (keys.length > 0) {
+        throw new CommandError('INVALID_ENVIRONMENT', 'Неверное окружение', { keys });
+    }
+    const out = resolve(context.cwd, values.out);
+    await mkdir(dirname(out), { recursive: true });
+    await writeFile(out, buildRedisAclFile({ users }));
+    context.write(`${JSON.stringify({ out, services })}\n`);
+    logger.info({ services, out }, 'redis acl: собрано');
+}
+function failureOf(error) {
+    if (error instanceof CommandError) {
+        return { code: error.code, message: error.message, ...error.extra };
+    }
+    return { code: 'REDIS_COMMAND_FAILED', message: 'команда redis завершилась ошибкой' };
+}
+/** Обработчик команды `redis`: 0 — aclfile записан, 1 — ошибка (JSON `{error}` в stdout). */
+export async function redisCommand(args, context = defaultContext) {
+    try {
+        if (args[0] !== 'acl') {
+            throw new CommandError('USAGE', 'подкоманда redis: acl');
+        }
+        const logger = await createLogger(context.env);
+        logger.debug({ command: 'redis', sub: 'acl' }, 'cli: команда');
+        await acl(args.slice(1), context, logger);
+        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/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import 'reflect-metadata';

package/dist/cli/main.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+// CLI verdeect-kit (prd.md §3.5, AC-3.7; ARCHITECTURE.md «CLI»): разбор команды и динамическая загрузка только её
+// обработчика (openapi, db, rabbitmq, crypto, redis). Результат — JSON в stdout, ошибка — JSON и код выхода 1. process.exit не вызывается: его вызывают только
+// failStartup и сторож KitLifecycle; код выхода — process.exitCode.
+import 'reflect-metadata';
+import { parseArgs } from 'node:util';
+const COMMANDS = {
+    openapi: async () => (await import('./commands/openapi.js')).openapiCommand,
+    db: async () => (await import('./commands/db.js')).dbCommand,
+    rabbitmq: async () => (await import('./commands/rabbitmq.js')).rabbitmqCommand,
+    crypto: async () => (await import('./commands/crypto.js')).cryptoCommand,
+    redis: async () => (await import('./commands/redis.js')).redisCommand,
+};
+/** Точка входа: `verdeect-kit <команда> [опции]`. */
+async function main(argv) {
+    const { positionals } = parseArgs({ args: [...argv], strict: false, allowPositionals: true });
+    const command = positionals[0] ?? '';
+    const load = Object.hasOwn(COMMANDS, command) ? COMMANDS[command] : undefined;
+    if (load === undefined) {
+        process.stdout.write(`${JSON.stringify({
+            error: {
+                code: 'UNKNOWN_COMMAND',
+                message: `неизвестная команда «${command}»; доступны: ${Object.keys(COMMANDS).join(', ')}`,
+            },
+        })}\n`);
+        return 1;
+    }
+    const handler = await load();
+    return handler(argv.slice(argv.indexOf(command) + 1));
+}
+process.exitCode = await main(process.argv.slice(2));

package/dist/config/cli-schemas.d.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+/** Окружение CLI `db migrate`: адрес БД роли-владельца схемы (§3.1). */
+export declare const migrateEnvSchema: z.ZodObject<{
+    DATABASE_MIGRATOR_URL: z.ZodString;
+    LOG_LEVEL: z.ZodDefault<z.ZodEnum<{
+        error: "error";
+        fatal: "fatal";
+        warn: "warn";
+        info: "info";
+        debug: "debug";
+        trace: "trace";
+        silent: "silent";
+    }>>;
+}, z.core.$strip>;
+/** Окружение CLI `db prepare`: суперпользователь и пароли ролей (§3.1). */
+export declare const prepareEnvSchema: z.ZodObject<{
+    DATABASE_ADMIN_URL: z.ZodString;
+    DB_OWNER_PASSWORD: z.ZodString;
+    DB_APP_PASSWORD: z.ZodString;
+    LOG_LEVEL: z.ZodDefault<z.ZodEnum<{
+        error: "error";
+        fatal: "fatal";
+        warn: "warn";
+        info: "info";
+        debug: "debug";
+        trace: "trace";
+        silent: "silent";
+    }>>;
+}, z.core.$strip>;

package/dist/config/cli-schemas.js

@@ -0,0 +1,15 @@
+// Схемы окружения CLI (prd.md §3.1); эталон — O env.schema.ts MigrateEnvSchema/PrepareEnvSchema, имена паролей — §3.1.
+import { z } from 'zod';
+import { logLevel } from './fragments.js';
+/** Окружение CLI `db migrate`: адрес БД роли-владельца схемы (§3.1). */
+export const migrateEnvSchema = z.object({
+    DATABASE_MIGRATOR_URL: z.string().min(1),
+    LOG_LEVEL: logLevel,
+});
+/** Окружение CLI `db prepare`: суперпользователь и пароли ролей (§3.1). */
+export const prepareEnvSchema = z.object({
+    DATABASE_ADMIN_URL: z.string().min(1),
+    DB_OWNER_PASSWORD: z.string().min(16),
+    DB_APP_PASSWORD: z.string().min(16),
+    LOG_LEVEL: logLevel,
+});

package/dist/config/define-env.d.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+import type { envBase, envCrypto, envDatabase, envMessaging, envRedis, envSentry, envServiceUrls } from './fragments.js';
+type KitShape = typeof envBase & typeof envDatabase & typeof envMessaging & typeof envRedis & typeof envSentry & typeof envCrypto & ReturnType<typeof envServiceUrls>;
+type KitKeyOutput = {
+    [K in keyof KitShape]: z.output<KitShape[K]>;
+};
+/** Ключ пакета в shape сервиса обязан давать тот же выходной тип (AC-1.6). */
+export type CompatibleShape<S extends z.ZodRawShape> = {
+    [K in keyof S]: K extends keyof KitKeyOutput ? z.ZodType<KitKeyOutput[K]> : S[K];
+};
+/**
+ * Проверки между ключами пакета (§3.1, AC-1.4): PORT ≠ METRICS_PORT (кроме 0 — порт выбирает ОС),
+ * SHUTDOWN_DRAIN_MS < SHUTDOWN_TIMEOUT_MS. Ключей нет в схеме — проверки нет. Форма схемы сохраняется.
+ */
+export declare function withBaseChecks<T extends z.ZodObject>(schema: T): T;
+/**
+ * Схема окружения сервиса (§3.1): распаковка фрагментов пакета + свои ключи, проверки withBaseChecks
+ * и необязательная своя проверка `refine`. Лишние переменные процесса отбрасываются.
+ */
+export declare function defineEnv<S extends z.ZodRawShape>(shape: S & CompatibleShape<S>, refine?: (env: z.output<z.ZodObject<S>>, ctx: z.RefinementCtx) => void): z.ZodObject<S>;
+export {};

package/dist/config/define-env.js

@@ -0,0 +1,43 @@
+// defineEnv и withBaseChecks (prd.md §3.1, AC-1.4, AC-1.6). Проверки между ключами пакета — эталон O superRefine.
+import { z } from 'zod';
+/** Число из разобранного окружения или undefined: проверки идут, только если ключи есть в схеме. */
+function numberAt(env, key) {
+    const value = env[key];
+    return typeof value === 'number' ? value : undefined;
+}
+/**
+ * Проверки между ключами пакета (§3.1, AC-1.4): PORT ≠ METRICS_PORT (кроме 0 — порт выбирает ОС),
+ * SHUTDOWN_DRAIN_MS < SHUTDOWN_TIMEOUT_MS. Ключей нет в схеме — проверки нет. Форма схемы сохраняется.
+ */
+export function withBaseChecks(schema) {
+    return schema.superRefine((env, ctx) => {
+        const appPort = numberAt(env, 'PORT');
+        const metricsPort = numberAt(env, 'METRICS_PORT');
+        if (appPort !== undefined && appPort === metricsPort && appPort !== 0) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['METRICS_PORT'],
+                message: 'PORT и METRICS_PORT совпадают',
+                input: '',
+            });
+        }
+        const drain = numberAt(env, 'SHUTDOWN_DRAIN_MS');
+        const timeout = numberAt(env, 'SHUTDOWN_TIMEOUT_MS');
+        if (drain !== undefined && timeout !== undefined && drain >= timeout) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['SHUTDOWN_DRAIN_MS'],
+                message: 'пауза не меньше общего срока остановки',
+                input: '',
+            });
+        }
+    });
+}
+/**
+ * Схема окружения сервиса (§3.1): распаковка фрагментов пакета + свои ключи, проверки withBaseChecks
+ * и необязательная своя проверка `refine`. Лишние переменные процесса отбрасываются.
+ */
+export function defineEnv(shape, refine) {
+    const schema = withBaseChecks(z.object(shape));
+    return refine === undefined ? schema : schema.superRefine(refine);
+}

package/dist/config/fragments.d.ts

@@ -0,0 +1,105 @@
+import { z } from 'zod';
+/** Уровень pino (§3.1); внутренний экспорт для схем CLI, из /config не реэкспортируется. */
+export declare const logLevel: z.ZodDefault<z.ZodEnum<{
+    error: "error";
+    fatal: "fatal";
+    warn: "warn";
+    info: "info";
+    debug: "debug";
+    trace: "trace";
+    silent: "silent";
+}>>;
+/**
+ * Базовые ключи каждого сервиса (§3.1): NODE_ENV (production), LOG_LEVEL (info), PORT (3000),
+ * METRICS_PORT (9100), REPLICA_ID (hostname()), SHUTDOWN_TIMEOUT_MS (10000), SHUTDOWN_DRAIN_MS (0).
+ */
+export declare const envBase: {
+    NODE_ENV: z.ZodDefault<z.ZodEnum<{
+        development: "development";
+        test: "test";
+        production: "production";
+    }>>;
+    LOG_LEVEL: z.ZodDefault<z.ZodEnum<{
+        error: "error";
+        fatal: "fatal";
+        warn: "warn";
+        info: "info";
+        debug: "debug";
+        trace: "trace";
+        silent: "silent";
+    }>>;
+    PORT: z.ZodCoercedNumber<unknown> | z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    METRICS_PORT: z.ZodCoercedNumber<unknown> | z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    REPLICA_ID: z.ZodPipe<z.ZodPipe<z.ZodPipe<z.ZodDefault<z.ZodString>, z.ZodTransform<string | null, string>>, z.ZodTransform<string, string | null>>, z.ZodString>;
+    SHUTDOWN_TIMEOUT_MS: z.ZodCoercedNumber<unknown> | z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    SHUTDOWN_DRAIN_MS: z.ZodCoercedNumber<unknown> | z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+};
+/** БД (§3.1): DATABASE_URL (обязателен), DB_POOL_MAX (10), DB_POOL_ACQUIRE_TIMEOUT_MS (5000, мин. 1). */
+export declare const envDatabase: {
+    DATABASE_URL: z.ZodString;
+    DB_POOL_MAX: z.ZodCoercedNumber<unknown> | z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    DB_POOL_ACQUIRE_TIMEOUT_MS: z.ZodCoercedNumber<unknown> | z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+};
+/** RabbitMQ (§3.1): RABBITMQ_URL (обязателен), RABBITMQ_RETRY_SECONDS (30, целое ≥ 1). */
+export declare const envMessaging: {
+    RABBITMQ_URL: z.ZodURL;
+    RABBITMQ_RETRY_SECONDS: z.ZodCoercedNumber<unknown> | z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+};
+/** Redis (§3.1): REDIS_URL (обязателен). */
+export declare const envRedis: {
+    REDIS_URL: z.ZodURL;
+};
+/** GlitchTip (§3.1): SENTRY_DSN, SENTRY_ENVIRONMENT, SENTRY_RELEASE — пусто → null; NODE_ENV. */
+export declare const envSentry: {
+    SENTRY_DSN: z.ZodPipe<z.ZodDefault<z.ZodString>, z.ZodTransform<string | null, string>>;
+    SENTRY_ENVIRONMENT: z.ZodPipe<z.ZodDefault<z.ZodString>, z.ZodTransform<string | null, string>>;
+    SENTRY_RELEASE: z.ZodPipe<z.ZodDefault<z.ZodString>, z.ZodTransform<string | null, string>>;
+    NODE_ENV: z.ZodDefault<z.ZodEnum<{
+        development: "development";
+        test: "test";
+        production: "production";
+    }>>;
+};
+/**
+ * @internal Массив ключей шифра `[{version, secret}]`: одна проверка для envCrypto и createCipher (§3.6);
+ * из /config не реэкспортируется.
+ */
+export declare const encryptionKeysSchema: z.ZodArray<z.ZodObject<{
+    version: z.ZodNumber;
+    secret: z.ZodString;
+}, z.core.$strip>>;
+/** Ключи шифра (§3.1, §3.6): ENCRYPTION_KEYS — JSON `[{version, secret}]`, версии без повторов. */
+export declare const envCrypto: {
+    ENCRYPTION_KEYS: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<unknown, string>>, z.ZodArray<z.ZodObject<{
+        version: z.ZodNumber;
+        secret: z.ZodString;
+    }, z.core.$strip>>> | z.ZodPipe<z.ZodPipe<z.ZodDefault<z.ZodString>, z.ZodTransform<unknown, string>>, z.ZodArray<z.ZodObject<{
+        version: z.ZodNumber;
+        secret: z.ZodString;
+    }, z.core.$strip>>>;
+};
+/**
+ * Адреса других сервисов (§3.1, AC-1.11): SERVICE_URLS — JSON `{имя: http(s)-URL}`; имена `required`
+ * обязательны, лишние имена допустимы, но тоже должны быть URL.
+ */
+export declare function envServiceUrls(required: readonly string[]): {
+    SERVICE_URLS: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<unknown, string>>, z.ZodPipe<z.ZodObject<{
+        [x: string]: z.ZodURL;
+    }, z.core.$catchall<z.ZodURL>>, z.ZodTransform<Readonly<Record<string, string>>, {
+        [x: string]: string;
+    }>>> | z.ZodPipe<z.ZodPipe<z.ZodDefault<z.ZodString>, z.ZodTransform<unknown, string>>, z.ZodPipe<z.ZodObject<{
+        [x: string]: z.ZodURL;
+    }, z.core.$catchall<z.ZodURL>>, z.ZodTransform<Readonly<Record<string, string>>, {
+        [x: string]: string;
+    }>>>;
+};
+/** Разобранные базовые ключи (§3.1). */
+export type KitBaseEnv = z.output<z.ZodObject<typeof envBase>>;
+/** Разобранные ключи БД (§3.1). */
+export type KitDatabaseEnv = z.output<z.ZodObject<typeof envDatabase>>;
+/** Разобранные ключи RabbitMQ (§3.1). */
+export type KitMessagingEnv = z.output<z.ZodObject<typeof envMessaging>>;
+/** Разобранные ключи Redis (§3.1). */
+export type KitRedisEnv = z.output<z.ZodObject<typeof envRedis>>;
+/** Разобранные ключи шифра (§3.1). */
+export type KitCryptoEnv = z.output<z.ZodObject<typeof envCrypto>>;

package/dist/config/fragments.js

@@ -0,0 +1,86 @@
+// Фрагменты схемы окружения пакета (prd.md §3.1, C0–C6); эталон — O env.schema.ts, SERVICE_URLS — B.
+// Решения PRD поверх эталонов: PORT вместо BFF_PORT/IDENTITY_PORT, RABBITMQ_RETRY_SECONDS = 30, ENCRYPTION_KEYS —
+// JSON [{version, secret}] (§3.6, CE-2). Псевдонимов старых ключей нет (P0, N9).
+// Фрагмент — объект zod-схем (raw shape), а не z.object: он распаковывается в defineEnv.
+import { hostname } from 'node:os';
+import { z } from 'zod';
+import { httpUrl, jsonValue, nonNegativeInt, optionalText, port, positiveInt, uniqueBy, } from './helpers.js';
+/** Режим процесса; одна схема для envBase и envSentry, чтобы распаковка обоих не конфликтовала. */
+const nodeEnv = z.enum(['development', 'test', 'production']).default('production');
+/** Уровень pino (§3.1); внутренний экспорт для схем CLI, из /config не реэкспортируется. */
+export const logLevel = z
+    .enum(['fatal', 'error', 'warn', 'info', 'debug', 'trace', 'silent'])
+    .default('info');
+/** Имя реплики: пусто → hostname() (§3.1). */
+const replicaId = optionalText()
+    .transform((value) => value ?? hostname())
+    .pipe(z.string().regex(/^[A-Za-z0-9._-]{1,128}$/));
+/**
+ * Базовые ключи каждого сервиса (§3.1): NODE_ENV (production), LOG_LEVEL (info), PORT (3000),
+ * METRICS_PORT (9100), REPLICA_ID (hostname()), SHUTDOWN_TIMEOUT_MS (10000), SHUTDOWN_DRAIN_MS (0).
+ */
+export const envBase = {
+    NODE_ENV: nodeEnv,
+    LOG_LEVEL: logLevel,
+    PORT: port(3000),
+    METRICS_PORT: port(9100),
+    REPLICA_ID: replicaId,
+    SHUTDOWN_TIMEOUT_MS: positiveInt(10_000),
+    SHUTDOWN_DRAIN_MS: nonNegativeInt(0),
+};
+/** БД (§3.1): DATABASE_URL (обязателен), DB_POOL_MAX (10), DB_POOL_ACQUIRE_TIMEOUT_MS (5000, мин. 1). */
+export const envDatabase = {
+    DATABASE_URL: z.string().min(1),
+    DB_POOL_MAX: positiveInt(10),
+    DB_POOL_ACQUIRE_TIMEOUT_MS: positiveInt(5000),
+};
+/** RabbitMQ (§3.1): RABBITMQ_URL (обязателен), RABBITMQ_RETRY_SECONDS (30, целое ≥ 1). */
+export const envMessaging = {
+    RABBITMQ_URL: z.url(),
+    RABBITMQ_RETRY_SECONDS: positiveInt(30),
+};
+/** Redis (§3.1): REDIS_URL (обязателен). */
+export const envRedis = {
+    REDIS_URL: z.url(),
+};
+/** GlitchTip (§3.1): SENTRY_DSN, SENTRY_ENVIRONMENT, SENTRY_RELEASE — пусто → null; NODE_ENV. */
+export const envSentry = {
+    SENTRY_DSN: optionalText(),
+    SENTRY_ENVIRONMENT: optionalText(),
+    SENTRY_RELEASE: optionalText(),
+    NODE_ENV: nodeEnv,
+};
+/** Секрет ключа шифра: base64url без `=`, не короче 32 байт (§3.6). Issue — без значения. */
+const encryptionSecret = z
+    .string()
+    .regex(/^[A-Za-z0-9_-]+$/)
+    .superRefine((value, ctx) => {
+    if (Buffer.from(value, 'base64url').length < 32) {
+        ctx.addIssue({ code: 'custom', message: 'секрет короче 32 байт', input: '' });
+    }
+});
+/**
+ * @internal Массив ключей шифра `[{version, secret}]`: одна проверка для envCrypto и createCipher (§3.6);
+ * из /config не реэкспортируется.
+ */
+export const encryptionKeysSchema = z
+    .array(z.object({ version: z.number().int().positive(), secret: encryptionSecret }))
+    .min(1)
+    .superRefine(uniqueBy('version'));
+/** Ключи шифра (§3.1, §3.6): ENCRYPTION_KEYS — JSON `[{version, secret}]`, версии без повторов. */
+export const envCrypto = {
+    ENCRYPTION_KEYS: jsonValue(encryptionKeysSchema),
+};
+/**
+ * Адреса других сервисов (§3.1, AC-1.11): SERVICE_URLS — JSON `{имя: http(s)-URL}`; имена `required`
+ * обязательны, лишние имена допустимы, но тоже должны быть URL.
+ */
+export function envServiceUrls(required) {
+    const known = Object.fromEntries(required.map((name) => [name, httpUrl()]));
+    return {
+        SERVICE_URLS: jsonValue(z
+            .object(known)
+            .catchall(httpUrl())
+            .transform((map) => map)),
+    };
+}

package/dist/config/helpers.d.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+/** TCP-порт 0–65535; 0 — порт выбирает ОС (тесты). Пустая строка даёт 0, как в эталоне (§3.1). */
+export declare function port(fallback?: number): z.ZodCoercedNumber<unknown> | z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+/** Целое > 0 (§3.1). */
+export declare function positiveInt(fallback?: number): z.ZodCoercedNumber<unknown> | z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+/** Целое ≥ 0; внутренний помощник фрагментов, из /config не реэкспортируется. */
+export declare function nonNegativeInt(fallback?: number): z.ZodCoercedNumber<unknown> | z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+/** Необязательный текст: пусто или пробелы → null, иначе значение без крайних пробелов (§3.1). */
+export declare function optionalText(): z.ZodPipe<z.ZodDefault<z.ZodString>, z.ZodTransform<string | null, string>>;
+/** Только строки `true`/`false`: приведение zod к boolean сделало бы строку `false` истиной (§3.1). */
+export declare function booleanFlag(fallback?: boolean): z.ZodPipe<z.ZodDefault<z.ZodEnum<{
+    true: "true";
+    false: "false";
+}>>, z.ZodTransform<boolean, "true" | "false">> | z.ZodPipe<z.ZodEnum<{
+    true: "true";
+    false: "false";
+}>, z.ZodTransform<boolean, "true" | "false">>;
+/**
+ * Ключ с JSON-значением (§3.1). Умолчание — строка до разбора: в zod 4 умолчание после
+ * преобразования ожидает уже разобранный тип. Ошибка разбора — без входного значения.
+ */
+export declare function jsonValue<T extends z.ZodType>(schema: T, fallback?: string): z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<unknown, string>>, T> | z.ZodPipe<z.ZodPipe<z.ZodDefault<z.ZodString>, z.ZodTransform<unknown, string>>, T>;
+/** Адрес HTTP-ресурса: только http и https (§3.1). */
+export declare function httpUrl(): z.ZodURL;
+/** Значения поля `key` элементов массива не повторяются; для `superRefine`, issue — без значений (§3.1). */
+export declare function uniqueBy<T>(key: keyof T): (items: readonly T[], ctx: z.RefinementCtx) => void;