@mirta/cli 0.3.5 → 0.4.0

package/dist/deploy.mjs

@@ -0,0 +1,902 @@
+import chalk from 'chalk';
+import { isString, isNumber } from '@mirta/basics';
+import { D as DEFAULT_SSH_USERNAME, K as KNOWN_SSH_PORT, e as expandHomeDir, a as resolveSubpath, i as isExistsAsync, r as resolveConfigAsync } from './resolve.mjs';
+import { loadEnv as loadEnv$1 } from '@mirta/env-loader';
+import { l as logger, t, r as runCommandAsync, S as STDIO_INTERACTIVE, a as assertNoParseErrors, e as STDIO_CAPTURE_ERRORS } from './index.mjs';
+import { resolveWorkspaceContextAsync } from '@mirta/workspace';
+import 'node:fs/promises';
+import 'node:os';
+import './constants.mjs';
+import '@mirta/package';
+import 'node:path';
+import 'node:path/posix';
+import 'jsonc-parser';
+import '@mirta/basics/object';
+import 'prompts';
+import '@mirta/staged-args';
+import 'node:child_process';
+import '@mirta/i18n';
+import '../package.json' with { type: 'json' };
+import '@mirta/basics/fuzzy';
+
+let isLoaded = false;
+/**
+ * Загружает переменные окружения из .env-файлов в проекте.
+ *
+ * Выполняется только один раз за сессию (ленивая инициализация).
+ * Загружает файлы из `rootDir` и `cwd`, применяет префиксы `WB_` и `MIRTA_`.
+ * Результат объединяется с `process.env`.
+ *
+ * @param rootDir - Корневая директория проекта.
+ * @param cwd - Текущая рабочая директория (опционально).
+ *
+ * @since 0.4.0
+ *
+ **/
+function loadEnv(rootDir, cwd) {
+    if (isLoaded)
+        return;
+    const env = loadEnv$1({
+        cwd,
+        rootDir,
+        prefix: ['WB_', 'MIRTA_'],
+    });
+    // Объединяем с текущим process.env
+    Object.assign(process.env, env);
+    isLoaded = true;
+}
+/**
+ * Заменяет в строке все вхождения `${VAR_NAME}` на значения из `process.env`.
+ *
+ * Используется для подстановки переменных в строках подключения, путях и т.д.
+ *
+ * @param input - Входная строка с переменными, например: `${WB_HOST}`
+ * @returns Строка с подставленными значениями.
+ * @throws Ошибка, если переменная не определена.
+ *
+ * @since 0.4.0
+ *
+ **/
+function replaceEnvVars(input) {
+    return input.replace(/\$\{([^}]+)\}/g, (_, key) => {
+        const value = process.env[key];
+        if (value === undefined)
+            throw new Error(`Environment variable not set: ${key}`);
+        return value;
+    });
+}
+
+/**
+ * Регулярное выражение для проверки формата времени в стиле OpenSSH.
+ *
+ * Разрешает:
+ * - Чистые числа: `600` (секунды)
+ * - С последовательностями: `10m`, `1h30m`, `2d`
+ *
+ * Запрещает: `1h30`, `30x`, `m`, `abc`.
+ *
+ * Используется для валидации параметра `ttl`.
+ *
+ * @since 0.4.0
+ *
+ **/
+const SSH_TIME_PATTERN = /^(?:\d+[smhdw])+$|^\d+$/i;
+/**
+ * Утверждает, что переданный объект является валидным `MirtaConnection`.
+ *
+ * Проверяет все поля на корректность типов и допустимые значения.
+ * При неудаче выбрасывает `Error` с описанием проблемы.
+ *
+ * Используется для runtime-валидации конфигурации.
+ *
+ * @param value - Частичный объект подключения.
+ * @throws Ошибка, если объект не проходит валидацию.
+ *
+ * @since 0.4.0
+ *
+ **/
+function assertConnectionIsValid(value) {
+    if (value.type !== 'ssh')
+        throw new Error(`Only SSH connection type supported`);
+    if (value.username !== undefined && (!isString(value.username) || value.username.trim() === ''))
+        throw new Error(`username must be a non-empty string`);
+    if (value.hostname === undefined || !isString(value.hostname))
+        throw new Error(`hostname is required and must be a string`);
+    if (value.port !== undefined) {
+        const port = isString(value.port)
+            ? parseInt(value.port, 10)
+            : value.port;
+        if (!isNumber(port) || !Number.isInteger(port) || port < 1 || port > 65535)
+            throw new Error(`port must be integer between 1 and 65535, got ${JSON.stringify(value.port)}`);
+    }
+    if (value.pkcs11 !== undefined && !isString(value.pkcs11))
+        throw new Error(`pkcs11: path to identity must be a string`);
+    if (value.key !== undefined && !isString(value.key))
+        throw new Error(`key: path to identity must be a string`);
+    if (value.ttl !== undefined) {
+        if (!isString(value.ttl))
+            throw new Error(`ttl must be a string`);
+        if (!SSH_TIME_PATTERN.test(value.ttl.trim()))
+            throw new Error(`ttl must be in format <number>[smhd]`);
+    }
+    if (value.wsl !== undefined && !isString(value.wsl))
+        throw new Error(`wsl: distro name must be a string`);
+}
+
+/**
+ * Разделяет строку по первому вхождению указанного разделителя.
+ *
+ * @param input - Входная строка.
+ * @param separator - Разделитель.
+ * @returns Массив из двух элементов: до и после разделителя. Если разделитель не найден — возвращает `[input]`.
+ *
+ * @since 0.4.0
+ *
+ **/
+function splitByFirstOccurrence(input, separator) {
+    const index = input.indexOf(separator);
+    if (index === -1)
+        return [input];
+    return [input.slice(0, index), input.slice(index + separator.length)];
+}
+/**
+ * Парсит строку подключения в структурированный объект.
+ *
+ * Формат строки:
+ * ```txt
+ * protocol://user@host:port;param1=value1;param2=value2
+ * ```
+ * Извлекает:
+ * - Протокол, имя пользователя, хост, порт из URL-части
+ * - Дополнительные параметры из пар ключ=значение после точки с запятой:
+ *   `pkcs11`, `key`, `ttl`, `wsl`
+ *
+ * Выполняет подстановку переменных окружения в формате ${VAR_NAME}.
+ *
+ * @param input - Строка подключения
+ * @returns Объект с распарсенными полями (требует последующей валидации)
+ * @throws Ошибка при невалидном URL или пустой строке
+ *
+ * @since 0.4.0
+ *
+ **/
+function parseConnectionString(input) {
+    const source = replaceEnvVars(input).trim();
+    if (source === '')
+        throw new Error('Empty connection string');
+    const parts = source.split(';');
+    // === 1. Основные параметры ===
+    let url;
+    try {
+        url = new URL(parts[0]);
+    }
+    catch {
+        throw new Error(`Invalid connection URL: "${parts[0]}"`);
+    }
+    const protocol = url.protocol.replace(':', '');
+    const result = {
+        type: protocol,
+        username: decodeURIComponent(url.username),
+        hostname: url.hostname,
+    };
+    if (url.port !== '')
+        result.port = url.port;
+    // === 2. Вспомогательные опции ===
+    const params = parts.slice(1).reduce((items, nextItem) => {
+        const [key, value] = splitByFirstOccurrence(nextItem, '=');
+        if (key) {
+            if (value !== undefined) {
+                items[key] = value;
+            }
+            else {
+                logger.warn(t('connection.emptyParameterSkipped', { key }));
+            }
+        }
+        return items;
+    }, {});
+    result.pkcs11 = params.pkcs11;
+    result.key = params.key;
+    result.ttl = params.ttl;
+    if (result.ttl && !result.pkcs11 && !result.key)
+        logger.warn(t('connection.ttlSkipped'));
+    result.wsl = params.wsl;
+    return result;
+}
+
+/**
+ * Разрешает имя подключения в полный объект `MirtaConnection`.
+ *
+ * Поддерживает:
+ * - Прямые строки с URL (например, `ssh://...`)
+ * - Ссылки на имена из `config.connections`
+ * - Подстановку переменных окружения
+ *
+ * Если соединение найдено, применяет значение по умолчанию для `username` и проверяет валидность.
+ *
+ * @param config - Конфигурация проекта.
+ * @param input - Имя подключения или строка с URL (по умолчанию `'default'`).
+ * @returns Полный объект подключения.
+ * @throws Ошибка, если подключение не найдено или невалидно.
+ *
+ * @since 0.4.0
+ *
+ **/
+function resolveConnection(config, input = 'default') {
+    const inputNorm = replaceEnvVars(input);
+    let connection;
+    // Явная строка с протоколом
+    if (/^(?:[\w]+\+)?[\w]+:\/\//.test(inputNorm)) {
+        connection = inputNorm;
+    }
+    // Имя подключения из набора config.connections
+    else if (config.connections && inputNorm in config.connections) {
+        connection = config.connections[inputNorm];
+    }
+    if (!connection)
+        throw new Error(`Connection "${input}" not found`);
+    // Если строка — парсим в объект
+    if (isString(connection))
+        connection = parseConnectionString(connection);
+    if (connection.username === '' || connection.username === undefined)
+        connection.username = DEFAULT_SSH_USERNAME;
+    if (connection.ttl && isNumber(connection.ttl))
+        connection.ttl = connection.ttl.toString();
+    if (connection.port === '')
+        connection.port = undefined;
+    assertConnectionIsValid(connection);
+    return connection;
+}
+
+/**
+ * Формирует строку назначения подключения в формате `user@host[:port]`.
+ *
+ * Порт включается только если отличается от стандартного (22).
+ *
+ * @param connection - Объект подключения.
+ * @returns Строка вида `user@host` или `user@host:port`.
+ *
+ **/
+function getConnectionTarget(connection) {
+    let target = `${connection.username}@${connection.hostname}`;
+    if (connection.port && connection.port !== KNOWN_SSH_PORT)
+        target += `:${connection.port}`;
+    return target;
+}
+
+/**
+ * Базовая директория для SSH-файлов в зависимости от платформы.
+ *
+ * На Unix-системах — домашняя директория пользователя.
+ * На Windows — используется символ `~`, который раскрывается в оболочке.
+ *
+ * Используется для формирования пути к сокету SSH-агента.
+ *
+ * @since 0.4.0
+ *
+ **/
+const SSH_DIR = expandHomeDir('~/.ssh');
+/**
+ * Путь к сокету изолированного ssh-agent.
+ *
+ * @since 0.4.0
+ *
+ **/
+const SSH_AUTH_SOCK = SSH_DIR + '/mirta-agent.sock';
+/**
+ * Время жизни ключа, используемое в ssh-agent по умолчанию.
+ *
+ * @since 0.4.0
+ *
+ **/
+const DEFAULT_SSH_KEY_TTL = '15m';
+
+/**
+ * Асинхронно выполняет синхронизацию файлов с контроллером через `rsync` по SSH.
+ *
+ * Если исходный путь не существует — операция пропускается без ошибки.
+ * Поддерживает фильтрацию, очистку, защиту файлов и изменение группы.
+ * На Windows команда выполняется внутри WSL2.
+ *
+ * @param options - Параметры синхронизации.
+ *
+ * @since 0.4.0
+ *
+ **/
+async function runRsyncAsync(options) {
+    const { connection, mapping, toGroup, cwd, isDryRun, } = options;
+    const from = resolveSubpath(cwd, mapping.from);
+    if (!await isExistsAsync(from)) {
+        logger.step(t('deploy.sourceNotExists', {
+            source: from,
+        }));
+        // Файлы могут отсутствовать, это допустимо.
+        return;
+    }
+    const to = `${connection.username}@${connection.hostname}:${mapping.to}/`;
+    const args = [];
+    const sshParts = [];
+    if (connection.port && connection.port !== KNOWN_SSH_PORT)
+        sshParts.push(`-p ${connection.port}`);
+    if (sshParts.length > 0)
+        args.push('-e', `'ssh ${sshParts.join(' ')}'`);
+    // Флаги rsync:
+    // -r: рекурсивно
+    // -t: сохранять время файлов
+    // -z: сжатие
+    // -g: сохранять группу
+    // -O: не обновлять время на директориях
+    args.push('-rtzgO');
+    if (isDryRun)
+        args.unshift('--dry-run', '--itemize-changes');
+    if (mapping.cleanup)
+        args.push('--delete');
+    mapping.exclude?.forEach((pattern) => {
+        args.push('--exclude', pattern);
+    });
+    mapping.protect?.forEach((pattern) => {
+        args.push('--filter', `P ${pattern}`);
+    });
+    if (toGroup)
+        args.push('--groupmap', `*:${toGroup}`);
+    args.push(from, to);
+    logger.step(t('deploy.transmitting', {
+        from: mapping.from,
+        to: mapping.to,
+    }));
+    await runCommandAsync.inUnixShell(connection.wsl)('rsync', [...args], {
+        env: {
+            SSH_AUTH_SOCK,
+        },
+        cwd,
+        stdio: STDIO_INTERACTIVE,
+        shell: false,
+    });
+}
+
+/**
+ * Схема доступных опций команды `deploy`.
+ *
+ * Определяет типы и сокращённые формы флагов.
+ *
+ * @since 0.4.0
+ *
+ **/
+const options = ({
+    'config': {
+        type: 'string',
+        short: 'c',
+    },
+    'dry-run': {
+        type: 'boolean',
+    },
+    'profile': {
+        type: 'string',
+        short: 'p',
+    },
+    'to': {
+        type: 'string',
+    },
+    // Deprecated. Use 'dry-run' instead
+    'dry': {
+        type: 'boolean',
+    },
+});
+/**
+ * Парсит аргументы командной строки для команды `deploy`.
+ *
+ * - Обрабатывает опции в соответствии с объявленной схемой.
+ * - Если используется устаревший флаг `--dry`, выводит предупреждение и преобразует его в `--dry-run`.
+ *
+ * @param args - Объект с аргументами, управляемый `StagedArgs`.
+ * @returns Объект с распарсенными значениями и позиционными аргументами.
+ *
+ * @since 0.4.0
+ *
+ **/
+function parseArgs(args) {
+    const parseResult = args.parseFinal(options);
+    assertNoParseErrors(parseResult);
+    const { values, positionals } = parseResult.data;
+    if (values.dry) {
+        logger.warn('Deprecated flag "--dry" used. Please use "--dry-run" instead');
+        values['dry-run'] = values['dry-run'] !== false;
+    }
+    return {
+        values,
+        positionals,
+    };
+}
+
+/**
+ * Обеспечивает запуск изолированного SSH-агента для текущей сессии CLI.
+ *
+ * Проверяет, запущен ли агент. Если нет — удаляет старый сокет (если есть), создаёт директорию `~/.ssh`,
+ * и запускает новый экземпляр `ssh-agent` с ограниченным временем жизни ключей.
+ *
+ * Используется для безопасного управления ключами и токенами (PKCS#11) без влияния на основной агент системы.
+ *
+ * @param context - Контекст выполнения (включая поддержку WSL2).
+ * @throws Ошибка, если не удалось запустить `ssh-agent`.
+ *
+ * @since 0.4.0
+ *
+ **/
+async function ensureAgentIsRunningAsync(context) {
+    try {
+        // Проверяем, отвечает ли агент
+        const result = await context.runAsync('ssh-add', ['-l'], {
+            env: {
+                SSH_AUTH_SOCK,
+            },
+            stdio: STDIO_CAPTURE_ERRORS,
+            doneCodes: [0, 1],
+        });
+        if (result.code === 0 || result.code === 1) {
+            logger.debug('SSH agent is running');
+            return;
+        }
+    }
+    catch {
+        // Агент не отвечает — продолжаем инициализацию
+    }
+    try {
+        // Удаляем старый сокет, если существует
+        await context.runAsync('rm', ['-f', SSH_AUTH_SOCK], { stdio: STDIO_CAPTURE_ERRORS });
+    }
+    catch (e) {
+        logger.warn(`Could not remove stale socket: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    try {
+        // Создаём директорию ~/.ssh, если не существует
+        await context.runAsync('mkdir', ['-p', SSH_DIR], { stdio: STDIO_CAPTURE_ERRORS });
+    }
+    catch (e) {
+        logger.warn(`Could not create SSH directory: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    // Аргументы для запуска ssh-agent
+    const args = ['-a', SSH_AUTH_SOCK, '-t', DEFAULT_SSH_KEY_TTL];
+    // Если используется PKCS#11, указываем путь к модулю
+    if (context.pkcs11)
+        args.push('-P', context.pkcs11);
+    try {
+        await context.runAsync('ssh-agent', args, {
+            stdio: STDIO_CAPTURE_ERRORS,
+        });
+        logger.debug('SSH agent started');
+    }
+    catch (e) {
+        throw new Error(`Failed to start ssh-agent: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+
+/**
+ * Проверяет, содержится ли указанный отпечаток (или путь к токену) в списке добавленных сущностей в SSH-агенте.
+ *
+ * Использует команду `ssh-add -l`, которая выводит список всех добавленных ключей и токенов.
+ * Подходит как для проверки SSH-ключей (по отпечатку), так и для PKCS#11-токенов (по пути к библиотеке).
+ *
+ * @param fingerprint - Отпечаток ключа или путь к PKCS#11 модулю, который нужно проверить.
+ * @param context - Контекст выполнения команды (включая настройки окружения и WSL2).
+ * @returns `true`, если запись найдена в агенте, иначе `false`.
+ *
+ * @since 0.4.0
+ *
+ **/
+async function hasEntryAsync(fingerprint, context) {
+    const response = await context.runAsync('ssh-add', ['-l'], {
+        env: {
+            SSH_AUTH_SOCK,
+        },
+        stdio: STDIO_CAPTURE_ERRORS,
+        doneCodes: [0, 1], // 0 = есть ключи, 1 = нет ключей
+    });
+    if (response.code === 1)
+        return false;
+    return response.stdout.includes(fingerprint);
+}
+
+/**
+ * Удаляет PKCS#11 токен из SSH-агента.
+ *
+ * Использует команду `ssh-add -qe <path>` для выгрузки модуля.
+ *
+ * @param path - Путь к библиотеке PKCS#11 (например, `/usr/lib/libykcs11.so`).
+ * @param context - Контекст выполнения, включая среду (WSL2) и переменные окружения.
+ * @returns `true`, если токен успешно удалён, иначе `false`.
+ *
+ * @since 0.4.0
+ *
+ **/
+async function removeTokenAsync(path, context) {
+    try {
+        await context.runAsync('ssh-add', ['-qe', path], {
+            env: {
+                SSH_AUTH_SOCK,
+            },
+            stdio: 'ignore',
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Проверяет, добавлен ли PKCS#11 токен в SSH-агент.
+ *
+ * Анализирует вывод `ssh-add -l` на наличие пути к токену.
+ *
+ * @param path - Путь к библиотеке PKCS#11.
+ * @param context - Контекст выполнения.
+ * @returns `true`, если токен найден в агенте, иначе `false`.
+ *
+ * @since 0.4.0
+ *
+ **/
+async function hasTokenAsync(path, context) {
+    // Для PKCS#11 токенов ssh-add -l выводит путь к библиотеке,
+    // поэтому можем проверить наличие через простой поиск строки
+    return await hasEntryAsync(path, context);
+}
+/**
+ * Добавляет PKCS#11 токен в SSH-агент.
+ *
+ * Использует `ssh-add -s <path>`, с опциональным указанием времени жизни (`-t`).
+ * Вывод команды передаётся в терминал для отображения подсказок (например, ввод PIN-кода).
+ *
+ * @param path - Путь к библиотеке PKCS#11.
+ * @param context - Контекст выполнения.
+ * @throws Ошибка, если команда завершилась с кодом, отличным от 0.
+ *
+ * @since 0.4.0
+ *
+ **/
+async function addTokenAsync(path, context) {
+    const args = ['-q'];
+    if (context.ttl)
+        args.push('-t', context.ttl.toString());
+    args.push('-s', path);
+    await context.runAsync('ssh-add', args, {
+        env: {
+            SSH_AUTH_SOCK,
+        },
+        stdio: STDIO_INTERACTIVE,
+        cancelCodes: [2, 130],
+    });
+    logger.debug('PKCS#11 token added to ssh-agent');
+}
+
+/**
+ * Получает отпечаток (fingerprint) приватного SSH-ключа с помощью `ssh-keygen -lf`.
+ *
+ * Используется для идентификации ключа перед проверкой его наличия в агенте.
+ *
+ * @param key - Путь к приватному SSH-ключу.
+ * @param context - Контекст выполнения (включая поддержку WSL2).
+ * @returns Отпечаток ключа в формате, выводимом `ssh-keygen`.
+ * @throws Ошибка, если не удалось получить или распарсить вывод.
+ *
+ * @since 0.4.0
+ *
+ **/
+async function getFingerprintAsync(key, context) {
+    const response = await context.runAsync('ssh-keygen', ['-lf', key]);
+    const output = response.stdout.trim();
+    if (!output)
+        throw new Error('No data from ssh-keygen');
+    const fingerprint = output.split(' ')[1];
+    if (!fingerprint)
+        throw new Error('No fingerprint in ssh-keygen output');
+    return fingerprint;
+}
+/**
+ * Проверяет, добавлен ли SSH-ключ в агент.
+ *
+ * Сравнивает отпечаток ключа с отпечатками, возвращёнными `ssh-add -l`.
+ *
+ * @param path - Путь к приватному SSH-ключу.
+ * @param context - Контекст выполнения.
+ * @returns `true`, если ключ найден в агенте, иначе `false`.
+ *
+ * @since 0.4.0
+ *
+ **/
+async function hasKeyAsync(path, context) {
+    const fingerprint = await getFingerprintAsync(path, context);
+    return await hasEntryAsync(fingerprint, context);
+}
+/**
+ * Добавляет приватный SSH-ключ в SSH-агент.
+ *
+ * Использует `ssh-add` с опциональным временем жизни (`-t`) из контекста.
+ * Вывод команды передаётся в терминал для отображения подсказок (например, ввод пароля).
+ *
+ * @param path - Путь к приватному ключу.
+ * @param context - Контекст выполнения.
+ * @throws Ошибка, если команда завершилась с кодом, отличным от 0.
+ *
+ * @since 0.4.0
+ *
+ **/
+async function addKeyAsync(path, context) {
+    const args = ['-q'];
+    if (context.ttl)
+        args.push('-t', context.ttl);
+    args.push(expandHomeDir(path));
+    await context.runAsync('ssh-add', args, {
+        env: {
+            SSH_AUTH_SOCK,
+        },
+        stdio: STDIO_INTERACTIVE,
+        cancelCodes: [2, 130],
+    });
+    logger.debug('SSH key added to ssh-agent');
+}
+
+/**
+ * Выполняет аутентификацию подключения к контроллеру через SSH-агент.
+ *
+ * Добавляет в ssh-agent либо:
+ * - PKCS#11 токен (например, Rutoken), если указан `connection.pkcs11`
+ * - Приватный ключ, если указан `connection.key`
+ *
+ * Приоритет — у PKCS#11. Агент запускается автоматически при необходимости.
+ * Поддерживает выполнение в WSL2 на Windows.
+ *
+ * @param connection - Конфигурация подключения, содержащая параметры аутентификации.
+ *
+ * @since 0.4.0
+ *
+ **/
+async function authenticateAsync(connection) {
+    if (connection.type !== 'ssh')
+        return;
+    const context = {
+        pkcs11: connection.pkcs11,
+        key: connection.key,
+        ttl: connection.ttl,
+        runAsync: runCommandAsync.inUnixShell(connection.wsl),
+    };
+    // Ленивая инициализация агента SSH - только если это имеет смысл.
+    if (context.pkcs11 || context.key) {
+        await ensureAgentIsRunningAsync(context);
+        // Приоритет pkcs11 над key для кросс-машинной совместимости.
+        // TODO: добавить fallback на key, если токен pkcs11 не обнаружен.
+        //
+        if (context.pkcs11) {
+            const hasToken = await hasTokenAsync(context.pkcs11, context);
+            if (!hasToken) {
+                // Если срок действия токена истёк —
+                // выгружаем модуль, иначе повторно не добавить.
+                //
+                const isRemoved = await removeTokenAsync(context.pkcs11, context);
+                if (isRemoved)
+                    logger.debug('Stale PKCS#11 module unloaded');
+                await addTokenAsync(context.pkcs11, context);
+            }
+        }
+        else if (context.key) {
+            const hasKey = await hasKeyAsync(context.key, context);
+            if (!hasKey)
+                await addKeyAsync(context.key, context);
+        }
+    }
+}
+
+/**
+ * Проверяет, существует ли указанная группа на удалённом контроллере Wiren Board.
+ *
+ * Использует команду `getent group <group>` через SSH для проверки наличия группы.
+ * Поддерживает выполнение через WSL2 на Windows.
+ *
+ * @param group - Имя группы (например, 'wb-users').
+ * @param connection - Конфигурация подключения к контроллеру.
+ * @returns `true`, если группа найдена, иначе `false`.
+ *
+ * @since 0.4.0
+ *
+ **/
+async function hasRemoteGroupAsync(group, connection) {
+    const { hostname, username, port } = connection;
+    const args = [];
+    if (port)
+        args.push('-p', String(port));
+    args.push(`${username}@${hostname}`, `getent group ${group} > /dev/null 2>&1`);
+    try {
+        const result = await runCommandAsync.inUnixShell(connection.wsl)('ssh', args, {
+            env: {
+                SSH_AUTH_SOCK,
+            },
+            stdio: STDIO_CAPTURE_ERRORS,
+            doneCodes: [0, 2],
+            cancelCodes: [130],
+        });
+        return result.code === 0;
+    }
+    catch (e) {
+        logger.warn(e instanceof Error ? e.message : String(e));
+        return false;
+    }
+}
+
+/**
+ * Рекомендуемая группа для безопасного развертывания.
+ *
+ * Отдельная группа изолирует разработчиков,
+ * предотвращая случайное изменение или удаление важных системных файлов.
+ *
+ * @example
+ * ```bash
+ * sudo groupadd -f developers
+ * sudo usermod -aG developers deploy-user
+ * ```
+ *
+ * @since 0.4.0
+ *
+ **/
+const RECOMMENDED_GROUP = 'developers';
+
+/**
+ * Асинхронно проверяет, что WSL2 корректно настроен для выполнения команд.
+ *
+ * - Выполняет `wsl --list --verbose` через PowerShell
+ * - Анализирует список дистрибутивов
+ * - Проверяет версию WSL для указанного или дистрибутива по умолчанию
+ *
+ * Выбрасывает локализованные ошибки при проблемах.
+ *
+ * @param connection - Подключение, которое может указывать на конкретный дистрибутив WSL.
+ * @throws Ошибка с текстом на русском языке, если:
+ * - WSL не установлен
+ * - Нет дистрибутивов
+ * - Указанный дистрибутив не найден
+ * - Дистрибутив не WSL2
+ * - Дистрибутив по умолчанию не WSL2
+ *
+ * @since 0.4.0
+ *
+ **/
+async function assertWsl2ConfiguredAsync(connection) {
+    try {
+        // Запускаем wsl --list --verbose через PowerShell
+        const { stdout } = await runCommandAsync('powershell', ['$env:WSL_UTF8=1;', 'wsl', '--list', '--verbose']);
+        const lines = stdout.split('\n').slice(1); // Пропускаем заголовок
+        const distros = new Map();
+        let defaultDistro;
+        // Парсим каждую строку вывода.
+        for (const line of lines) {
+            const match = /^(\*)?\s+(\S+)\s+(?:\S+)\s+(\d+)$/
+                .exec(line.trim());
+            if (!match)
+                continue;
+            const distro = {
+                name: match[2],
+                version: parseInt(match[3], 10),
+                isDefault: match[1] === '*',
+            };
+            if (distro.isDefault)
+                defaultDistro = distro;
+            distros.set(distro.name.toLowerCase(), distro);
+        }
+        if (distros.size === 0)
+            throw new Error(t('wsl.noDistros'));
+        if (connection.wsl) {
+            const targetDistro = distros.get(connection.wsl.toLowerCase());
+            if (!targetDistro)
+                throw new Error(t('wsl.distroNotFound', { name: connection.wsl }));
+            if (targetDistro.version < 2)
+                throw new Error(t('wsl.distroNotWsl2', { name: connection.wsl }));
+            return;
+        }
+        if (!defaultDistro)
+            throw new Error(t('wsl.noDefault'));
+        if (defaultDistro.version >= 2)
+            return;
+        throw new Error(t('wsl.distroNotWsl2', { name: defaultDistro.name }));
+    }
+    catch (e) {
+        // Пробрасываем внутренние ошибки валидации как есть.
+        if (e instanceof Error && !('code' in e))
+            throw e;
+        if (e instanceof Error && 'code' in e && e.code === 'ENOENT')
+            throw new Error(t('wsl.notInstalled'));
+        throw new Error(t('wsl.error', {
+            error: e instanceof Error ? e.message : String(e),
+        }));
+    }
+}
+
+const { yellow } = chalk;
+/**
+ * Асинхронно выполняет команду `deploy`.
+ *
+ * - Парсит аргументы
+ * - Загружает конфигурацию
+ * - Настраивает подключение и аутентификацию
+ * - Проверяет окружение (WSL2)
+ * - Выполняет синхронизацию файлов по заданным маппингам
+ *
+ * @param args - Аргументы командной строки, управляемые `StagedArgs`.
+ *
+ * @since 0.4.0
+ *
+ **/
+async function runAsync(args) {
+    const { values: argv } = parseArgs(args);
+    const isDryRun = argv['dry-run'];
+    // Определение профиля деплоя.
+    const profileName = argv.profile && isString(argv.profile)
+        ? argv.profile
+        : 'default';
+    const cwd = process.cwd();
+    // Определение корневой директории проекта.
+    const context = await resolveWorkspaceContextAsync(cwd);
+    const rootDir = context.rootDir;
+    // Загрузка и объединение конфигурации.
+    const { config, userConfig } = await resolveConfigAsync(rootDir, argv.config);
+    // Полный набор маппингов из конфигурации.
+    const mappingPresets = config.deploy?.mappings ?? {};
+    // Используемый профиль.
+    const profile = config.deploy?.profiles?.[profileName];
+    const isImplicitProfile = !userConfig?.deploy?.profiles?.[profileName];
+    if (!profile)
+        throw new Error(t('deploy.profileNotFound', { name: profileName }));
+    // Загрузка переменных окружения ДО разрешения подключения.
+    loadEnv(rootDir, cwd);
+    // Определение подключения: из CLI-аргумента или профиля.
+    const connection = resolveConnection(config, argv.to ?? profile.connection);
+    // Проверка WSL2 на Windows.
+    if (process.platform === 'win32')
+        await assertWsl2ConfiguredAsync(connection);
+    // Логирование начала операции.
+    logger.log(t('deploy.deploying', {
+        target: yellow(getConnectionTarget(connection)),
+        mode: yellow(isDryRun ? 'dry-run' : 'live'),
+        profile: isImplicitProfile
+            ? t('deploy.profileImplicit', { name: yellow(profileName) })
+            : yellow(profileName),
+    }));
+    // Аутентификация через ssh-agent (PKCS#11 или ключ).
+    await authenticateAsync(connection);
+    if (!profile.toGroup) {
+        // Если группа не указана явно,
+        // то проверяем наличие рекомендуемой группы.
+        const isGroupExists = await hasRemoteGroupAsync(RECOMMENDED_GROUP, connection);
+        if (isGroupExists) {
+            profile.toGroup = RECOMMENDED_GROUP;
+        }
+        else {
+            // Если группы на контроллере нет,
+            // то выводим рекомендацию использовать отдельную группу.
+            logger.warn(t('deploy.useDedicatedGroup', { group: RECOMMENDED_GROUP }));
+        }
+    }
+    // Выполнение синхронизации по маппингам.
+    for (const key of profile.mappings ?? []) {
+        if (!(key in mappingPresets))
+            throw new Error(t('deploy.mappingsNotFound', { key }));
+        const mappings = mappingPresets[key];
+        for (const mapping of mappings) {
+            if (mapping.enabled === false) {
+                logger.log(t('deploy.mappingDisabled', {
+                    from: mapping.from,
+                    to: mapping.to,
+                }));
+                continue;
+            }
+            await runRsyncAsync({
+                mapping,
+                toGroup: mapping.toGroup ?? profile.toGroup,
+                connection,
+                cwd,
+                isDryRun,
+            });
+        }
+    }
+    // Финальное сообщение.
+    logger.success(isDryRun
+        ? t('deploy.simulationComplete')
+        : t('deploy.successful'));
+}
+
+export { runAsync };