@fractalizer/mcp-cli 0.3.18 → 1.0.0

package/dist/types/{base.types.d.ts → client.types.d.ts}

@@ -1,19 +1,7 @@
 /**
- * Base types for MCP CLI Framework (no external dependencies)
+ * Client-related types for MCP CLI Framework (framework-agnostic)
  * @packageDocumentation
  */
-/**
- * Базовая конфигурация для любого MCP сервера
- * Все MCP серверы должны расширять этот интерфейс
- */
-export interface BaseMCPServerConfig {
-    /** Абсолютный путь к директории проекта */
-    projectPath: string;
-    /** Уровень логирования */
-    logLevel?: 'debug' | 'info' | 'warn' | 'error';
-    /** Дополнительные переменные окружения для MCP сервера */
-    env?: Record<string, string>;
-}
 /**
  * Информация о MCP клиенте (Claude Desktop, Claude Code и т.д.)
  */
@@ -51,6 +39,9 @@ export interface ConnectionStatus {
 }
 /**
  * Конфигурация MCP сервера для записи в файл клиента (JSON/TOML)
+ *
+ * @internal Используется только реализациями коннекторов. Публичный API
+ * принимает {@link ServerLaunchSpec}.
  */
 export interface MCPClientServerConfig {
     command: string;
@@ -60,6 +51,8 @@ export interface MCPClientServerConfig {
 /**
  * Базовая структура конфигурационного файла MCP клиента
  * Generic тип для разных форматов (mcpServers, mcp_servers и т.д.)
+ *
+ * @internal Используется только реализациями коннекторов.
  */
 export type MCPClientConfig<TKey extends string = 'mcpServers'> = {
     [K in TKey]?: Record<string, MCPClientServerConfig>;
@@ -70,9 +63,11 @@ export type MCPClientConfig<TKey extends string = 'mcpServers'> = {
 export type PromptType = 'input' | 'password' | 'select' | 'confirm' | 'number';
 /**
  * Определение промпта для сбора конфигурации
- * Generic по типу конфигурации и ключу поля
+ *
+ * @template TDomainConfig - Тип доменной конфигурации MCP сервера (произвольный объект)
+ * @template K - Ключ поля в конфигурации
  */
-export interface ConfigPromptDefinition<TConfig extends BaseMCPServerConfig, K extends keyof TConfig = keyof TConfig> {
+export interface ConfigPromptDefinition<TDomainConfig extends object, K extends keyof TDomainConfig = keyof TDomainConfig> {
     /** Имя поля в конфигурации */
     name: K;
     /** Тип промпта */
@@ -80,37 +75,42 @@ export interface ConfigPromptDefinition<TConfig extends BaseMCPServerConfig, K e
     /** Сообщение для пользователя */
     message: string;
     /** Значение по умолчанию (может быть функцией от сохраненной конфигурации) */
-    default?: TConfig[K] | ((savedConfig?: Partial<TConfig>) => TConfig[K] | undefined);
+    default?: TDomainConfig[K] | ((savedConfig?: Partial<TDomainConfig>) => TDomainConfig[K] | undefined);
     /** Функция валидации */
-    validate?: (value: TConfig[K]) => string | true;
+    validate?: (value: TDomainConfig[K]) => string | true;
     /** Варианты выбора (для type: 'select') */
     choices?: Array<{
         name: string;
-        value: TConfig[K];
+        value: TDomainConfig[K];
     }>;
     /** Условное отображение промпта */
-    when?: (answers: Partial<TConfig>) => boolean;
+    when?: (answers: Partial<TDomainConfig>) => boolean;
     /** Маска для ввода (для type: 'password') */
     mask?: string;
 }
 /**
  * Опции для ConfigManager
+ *
+ * @template TDomainConfig - Тип доменной конфигурации MCP сервера (произвольный объект)
  */
-export interface ConfigManagerOptions<TConfig extends BaseMCPServerConfig> {
+export interface ConfigManagerOptions<TDomainConfig extends object> {
     /** Название проекта (для ~/.{projectName}/config.json) */
     projectName: string;
     /**
-     * Поля конфигурации, которые можно сохранять (без секретов!)
-     * Например: ['orgId', 'logLevel', 'apiBase']
-     */
-    safeFields: Array<keyof TConfig>;
-    /**
-     * Опционально: кастомная сериализация перед записью в файл
+     * Кастомная сериализация перед записью в файл.
+     *
+     * Обязательное поле — гарантия защиты от случайного сохранения секретов:
+     * адаптер сервера обязан явно решить, какие поля попадают в config.json
+     * (например, исключить token и сохранить только orgId/apiBase).
+     *
+     * Если в твоём адаптере хочется писать «весь объект как есть» — передай
+     * `serialize: (cfg) => ({ ...cfg })`. Это явное согласие на сохранение
+     * всех полей.
      */
-    serialize?: (config: TConfig) => Record<string, unknown>;
+    serialize: (config: TDomainConfig) => Record<string, unknown>;
     /**
-     * Опционально: кастомная десериализация после чтения из файла
+     * Опционально: кастомная десериализация после чтения из файла.
      */
-    deserialize?: (data: Record<string, unknown>) => Partial<TConfig>;
+    deserialize?: (data: Record<string, unknown>) => Partial<TDomainConfig>;
 }
-//# sourceMappingURL=base.types.d.ts.map
+//# sourceMappingURL=client.types.d.ts.map

package/dist/types/client.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.types.d.ts","sourceRoot":"","sources":["../../src/types/client.types.ts"],"names":[],"mappings":"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"}

package/dist/types/client.types.js

@@ -0,0 +1,6 @@
+/**
+ * Client-related types for MCP CLI Framework (framework-agnostic)
+ * @packageDocumentation
+ */
+export {};
+//# sourceMappingURL=client.types.js.map

package/dist/types/client.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.types.js","sourceRoot":"","sources":["../../src/types/client.types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/types/doctor.types.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Типы для команды самодиагностики `doctor`.
+ *
+ * Команда `doctor` запускает набор проверок (client-level + доменные) и
+ * возвращает агрегированный {@link DoctorReport}. Доменные проверки
+ * передаются вызывающим кодом через `extraChecks` — framework к доменной
+ * модели агностичен.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Статус результата одной проверки.
+ *
+ * - `ok`   — проверка пройдена.
+ * - `warn` — есть подозрение/неполные данные, но не блокер
+ *            (например, путь выглядит относительным, файл конфига отсутствует).
+ * - `fail` — проблема, из-за которой сервер точно не заработает.
+ * - `skip` — проверка пропущена по объективным причинам (например, сервер не
+ *            подключен к этому клиенту, нет данных для проверки).
+ *            `skip` не учитывается в `summary.fail/warn/ok`.
+ */
+export type DoctorCheckStatus = 'ok' | 'warn' | 'fail' | 'skip';
+/**
+ * Результат выполнения одной проверки.
+ */
+export interface DoctorCheckResult {
+    /** Итоговый статус. */
+    status: DoctorCheckStatus;
+    /** Человекочитаемое сообщение о результате. */
+    message: string;
+    /** Многострочные детали (например, путь к файлу, версия). Опционально. */
+    details?: string[];
+    /** Рекомендация по исправлению. Для `warn`/`fail`. Опционально. */
+    hint?: string;
+}
+/**
+ * Описание одной проверки.
+ *
+ * `run` — асинхронная функция, выполняющая проверку. Не должна выбрасывать
+ * исключений (любое исключение перехватывается `doctorCommand` и трактуется
+ * как `fail`).
+ */
+export interface DoctorCheck {
+    /** Короткое имя проверки для вывода (например, `bundle-accessible`). */
+    name: string;
+    /** Развёрнутое описание того, что проверяется. */
+    description: string;
+    /**
+     * Опциональная группа для визуальной группировки в выводе
+     * (например, имя клиента `Claude Code` или домен `Yandex Tracker`).
+     */
+    group?: string;
+    /** Функция выполнения проверки. */
+    run: () => Promise<DoctorCheckResult>;
+}
+/**
+ * Агрегированный отчёт о всех проверках.
+ */
+export interface DoctorReport {
+    /**
+     * Результаты проверок в детерминированном порядке (соответствует порядку,
+     * в котором проверки были собраны: client-level → extraChecks).
+     */
+    checks: Array<{
+        check: DoctorCheck;
+        result: DoctorCheckResult;
+    }>;
+    /**
+     * Сводка по статусам (без учёта `skip`).
+     */
+    summary: {
+        ok: number;
+        warn: number;
+        fail: number;
+        skip: number;
+    };
+}
+import type { IConnectorRegistry } from '../types.js';
+/**
+ * Опции для команды `doctor`.
+ */
+export interface DoctorCommandOptions {
+    /** Реестр коннекторов MCP клиентов. */
+    registry: IConnectorRegistry;
+    /**
+     * Дополнительные доменные проверки (например, валидация бандла сервера,
+     * проверка локальной конфигурации). Выполняются параллельно с client-level.
+     */
+    extraChecks?: DoctorCheck[];
+}
+//# sourceMappingURL=doctor.types.d.ts.map

package/dist/types/doctor.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.types.d.ts","sourceRoot":"","sources":["../../src/types/doctor.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,iBAAiB,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAEhE;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,uBAAuB;IACvB,MAAM,EAAE,iBAAiB,CAAC;IAE1B,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAEhB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAEnB,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IAEb,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,mCAAmC;IACnC,GAAG,EAAE,MAAM,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACvC;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,MAAM,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,WAAW,CAAC;QAAC,MAAM,EAAE,iBAAiB,CAAA;KAAE,CAAC,CAAC;IAEjE;;OAEG;IACH,OAAO,EAAE;QACP,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;CACH;AAID,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,uCAAuC;IACvC,QAAQ,EAAE,kBAAkB,CAAC;IAE7B;;;OAGG;IACH,WAAW,CAAC,EAAE,WAAW,EAAE,CAAC;CAC7B"}

package/dist/types/doctor.types.js

@@ -0,0 +1,12 @@
+/**
+ * Типы для команды самодиагностики `doctor`.
+ *
+ * Команда `doctor` запускает набор проверок (client-level + доменные) и
+ * возвращает агрегированный {@link DoctorReport}. Доменные проверки
+ * передаются вызывающим кодом через `extraChecks` — framework к доменной
+ * модели агностичен.
+ *
+ * @packageDocumentation
+ */
+export {};
+//# sourceMappingURL=doctor.types.js.map

package/dist/types/doctor.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.types.js","sourceRoot":"","sources":["../../src/types/doctor.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/types/launch.types.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Launch specification types for MCP servers (framework-agnostic)
+ * @packageDocumentation
+ */
+/**
+ * Спецификация запуска MCP сервера
+ *
+ * Готовая «команда + аргументы + переменные окружения» для записи в конфиг клиента.
+ * Публичный контракт между вызывающим кодом (адаптером домена) и framework: framework
+ * ничего не знает о доменных полях, оперируя только `ServerLaunchSpec`.
+ *
+ * Структурно совпадает с `MCPClientServerConfig` (internal), но логически выполняет
+ * другую роль: spec — это вход в `connector.connect()`, а `MCPClientServerConfig` — формат
+ * записи в JSON/TOML файлах клиентов.
+ *
+ * @example
+ * ```typescript
+ * const spec: ServerLaunchSpec = {
+ *   command: 'node',
+ *   args: ['/abs/path/dist/server.bundle.cjs'],
+ *   env: { API_TOKEN: 'xxx', ORG_ID: 'my-org' },
+ * };
+ *
+ * await connector.connect(spec);
+ * ```
+ */
+export interface ServerLaunchSpec {
+    /** Команда для запуска (обычно `node` или абсолютный путь к исполняемому файлу) */
+    command: string;
+    /**
+     * Аргументы команды (включая путь к скрипту и Node-флаги при необходимости).
+     *
+     * `readonly` — гарантия неизменяемости. Если коннектору нужно изменить
+     * массив, он должен сделать локальную копию.
+     */
+    args: readonly string[];
+    /** Переменные окружения, передаваемые серверу */
+    env: Record<string, string>;
+    /**
+     * Рабочая директория для процесса сервера (опционально).
+     *
+     * Если задано — должно быть абсолютным путём. Поддержка зависит от конкретного
+     * клиента: для file-based клиентов (Claude Desktop, Gemini, Qwen, Codex)
+     * сохраняется в конфиге и читается обратно; для Claude Code не поддерживается
+     * (выводится warning).
+     *
+     * Если `undefined` — поле не пишется в конфиг, наследуется текущий cwd процесса.
+     */
+    cwd?: string;
+    /**
+     * Метка «сервер выключен» (опционально). Если `true`, клиент НЕ должен
+     * запускать процесс сервера. Поддержка зависит от клиента: file-based клиенты
+     * пишут поле в JSON/TOML; Claude Code эту опцию не поддерживает (warning).
+     *
+     * Если `undefined` — поле не пишется в конфиг (по умолчанию активный).
+     */
+    disabled?: boolean;
+}
+//# sourceMappingURL=launch.types.d.ts.map

package/dist/types/launch.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"launch.types.d.ts","sourceRoot":"","sources":["../../src/types/launch.types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,gBAAgB;IAC/B,mFAAmF;IACnF,OAAO,EAAE,MAAM,CAAC;IAEhB;;;;;OAKG;IACH,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IAExB,iDAAiD;IACjD,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE5B;;;;;;;;;OASG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB"}

package/dist/types/launch.types.js

@@ -0,0 +1,6 @@
+/**
+ * Launch specification types for MCP servers (framework-agnostic)
+ * @packageDocumentation
+ */
+export {};
+//# sourceMappingURL=launch.types.js.map

package/dist/types/launch.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"launch.types.js","sourceRoot":"","sources":["../../src/types/launch.types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/types.d.ts

@@ -2,36 +2,45 @@
  * Core types for MCP CLI Framework
  * @packageDocumentation
  */
-export { type BaseMCPServerConfig, type MCPClientInfo, type ConnectionStatus, type MCPClientServerConfig, type MCPClientConfig, type PromptType, type ConfigPromptDefinition, type ConfigManagerOptions, } from './types/base.types.js';
-import type { BaseMCPServerConfig, ConnectionStatus, ConfigPromptDefinition } from './types/base.types.js';
+export { type MCPClientInfo, type ConnectionStatus, type PromptType, type ConfigPromptDefinition, type ConfigManagerOptions, } from './types/client.types.js';
+export { type ServerLaunchSpec } from './types/launch.types.js';
+export { type DoctorCheck, type DoctorCheckResult, type DoctorCheckStatus, type DoctorReport, type DoctorCommandOptions, } from './types/doctor.types.js';
+import type { ConnectionStatus, ConfigPromptDefinition } from './types/client.types.js';
+import type { ServerLaunchSpec } from './types/launch.types.js';
 import type { MCPConnector } from './connectors/base/connector.interface.js';
 import type { ConfigManager } from './utils/config-manager.js';
 /**
  * Опции для команды connect
+ *
+ * @template TDomainConfig - Тип доменной конфигурации MCP сервера (произвольный объект)
  */
-export interface ConnectCommandOptions<TConfig extends BaseMCPServerConfig> {
+export interface ConnectCommandOptions<TDomainConfig extends object> {
     /** Реестр коннекторов */
-    registry: IConnectorRegistry<TConfig>;
+    registry: IConnectorRegistry;
     /** Менеджер конфигурации */
-    configManager: ConfigManager<TConfig>;
-    /** Промпты для сбора конфигурации */
-    configPrompts: ConfigPromptDefinition<TConfig>[];
+    configManager: ConfigManager<TDomainConfig>;
+    /** Промпты для сбора доменной конфигурации */
+    configPrompts: ConfigPromptDefinition<TDomainConfig>[];
+    /**
+     * Адаптер: доменная конфигурация → спецификация запуска MCP сервера.
+     * Framework не знает структуру `TDomainConfig`, эта функция превращает её в
+     * `{ command, args, env }` для записи в конфиг клиента.
+     */
+    buildServerLaunch: (config: TDomainConfig) => ServerLaunchSpec;
     /** CLI опции (из commander) */
     cliOptions?: {
         client?: string;
     };
-    /** Опционально: функция для добавления projectPath к конфигу */
-    buildConfig?: (serverConfig: Omit<TConfig, 'projectPath'>) => TConfig;
 }
 /**
  * Интерфейс для реестра MCP коннекторов
  * @internal - используется только для типизации command options
  */
-export interface IConnectorRegistry<TConfig extends BaseMCPServerConfig = BaseMCPServerConfig> {
-    register(connector: MCPConnector<TConfig>): void;
-    get(name: string): MCPConnector<TConfig> | undefined;
-    getAll(): MCPConnector<TConfig>[];
-    findInstalled(): Promise<MCPConnector<TConfig>[]>;
+export interface IConnectorRegistry {
+    register(connector: MCPConnector): void;
+    get(name: string): MCPConnector | undefined;
+    getAll(): MCPConnector[];
+    findInstalled(): Promise<MCPConnector[]>;
     checkAllStatuses(): Promise<Map<string, ConnectionStatus>>;
 }
 export type { MCPConnector };

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,GAC1B,MAAM,uBAAuB,CAAC;AAG/B,OAAO,KAAK,EACV,mBAAmB,EACnB,gBAAgB,EAChB,sBAAsB,EACvB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAC7E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE/D;;GAEG;AACH,MAAM,WAAW,qBAAqB,CAAC,OAAO,SAAS,mBAAmB;IACxE,yBAAyB;IACzB,QAAQ,EAAE,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAEtC,4BAA4B;IAC5B,aAAa,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IAEtC,qCAAqC;IACrC,aAAa,EAAE,sBAAsB,CAAC,OAAO,CAAC,EAAE,CAAC;IAEjD,+BAA+B;IAC/B,UAAU,CAAC,EAAE;QACX,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;IAEF,gEAAgE;IAChE,WAAW,CAAC,EAAE,CAAC,YAAY,EAAE,IAAI,CAAC,OAAO,EAAE,aAAa,CAAC,KAAK,OAAO,CAAC;CACvE;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB,CAAC,OAAO,SAAS,mBAAmB,GAAG,mBAAmB;IAC3F,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;IACjD,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,GAAG,SAAS,CAAC;IACrD,MAAM,IAAI,YAAY,CAAC,OAAO,CAAC,EAAE,CAAC;IAClC,aAAa,IAAI,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAClD,gBAAgB,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC;CAC5D;AAGD,YAAY,EAAE,YAAY,EAAE,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,UAAU,EACf,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,GAC1B,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAGhE,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,oBAAoB,GAC1B,MAAM,yBAAyB,CAAC;AAGjC,OAAO,KAAK,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACxF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAC7E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE/D;;;;GAIG;AACH,MAAM,WAAW,qBAAqB,CAAC,aAAa,SAAS,MAAM;IACjE,yBAAyB;IACzB,QAAQ,EAAE,kBAAkB,CAAC;IAE7B,4BAA4B;IAC5B,aAAa,EAAE,aAAa,CAAC,aAAa,CAAC,CAAC;IAE5C,8CAA8C;IAC9C,aAAa,EAAE,sBAAsB,CAAC,aAAa,CAAC,EAAE,CAAC;IAEvD;;;;OAIG;IACH,iBAAiB,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,gBAAgB,CAAC;IAE/D,+BAA+B;IAC/B,UAAU,CAAC,EAAE;QACX,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,SAAS,EAAE,YAAY,GAAG,IAAI,CAAC;IACxC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAAC;IAC5C,MAAM,IAAI,YAAY,EAAE,CAAC;IACzB,aAAa,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IACzC,gBAAgB,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC;CAC5D;AAGD,YAAY,EAAE,YAAY,EAAE,CAAC"}

package/dist/types.js

@@ -2,6 +2,13 @@
  * Core types for MCP CLI Framework
  * @packageDocumentation
  */
-// Re-export all base types
-export {} from './types/base.types.js';
+// Re-export client-related types.
+// Note: MCPClientServerConfig / MCPClientConfig — internal-only (используются
+// внутри ConfigurableConnector для типизации raw-JSON/TOML структур). НЕ
+// re-export.
+export {} from './types/client.types.js';
+// Re-export launch spec
+export {} from './types/launch.types.js';
+// Re-export doctor types (Stage 1.3)
+export {} from './types/doctor.types.js';
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,2BAA2B;AAC3B,OAAO,EASN,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,kCAAkC;AAClC,8EAA8E;AAC9E,yEAAyE;AACzE,aAAa;AACb,OAAO,EAMN,MAAM,yBAAyB,CAAC;AAEjC,wBAAwB;AACxB,OAAO,EAAyB,MAAM,yBAAyB,CAAC;AAEhE,qCAAqC;AACrC,OAAO,EAMN,MAAM,yBAAyB,CAAC"}

package/dist/utils/command-executor.d.ts

@@ -4,6 +4,16 @@
  * @module CommandExecutor
  * @description Утилита для выполнения shell команд с различными режимами вывода
  */
+/**
+ * Опции для {@link CommandExecutor.exec}.
+ */
+export interface ExecOptions {
+    /**
+     * Таймаут выполнения в миллисекундах. При превышении — процесс убивается
+     * `SIGKILL`, выбрасывается `Error('Timeout: <command> exceeded <ms>ms')`.
+     */
+    timeout?: number;
+}
 /**
  * Класс для выполнения shell команд
  *
@@ -12,6 +22,12 @@
  * // Выполнить команду и получить вывод
  * const output = CommandExecutor.exec('echo "test"');
  *
+ * // С таймаутом
+ * const output = CommandExecutor.exec('claude mcp list', { timeout: 5000 });
+ *
+ * // Безопасное выполнение без shell-интерпретации
+ * const out = CommandExecutor.execFile('claude', ['mcp', 'list'], { timeout: 5000 });
+ *
  * // Проверить наличие команды
  * if (CommandExecutor.isCommandAvailable('node')) {
  *   console.log('Node.js установлен');
@@ -20,11 +36,12 @@
  */
 export declare class CommandExecutor {
     /**
-     * Выполнить команду и вернуть stdout
+     * Выполнить команду и вернуть stdout.
      *
      * @param command - Команда для выполнения
+     * @param options - Опции выполнения (включая `timeout`)
      * @returns Вывод команды
-     * @throws {Error} Если команда завершилась с ошибкой
+     * @throws {Error} Если команда завершилась с ошибкой или превысила таймаут
      *
      * @example
      * ```typescript
@@ -32,7 +49,26 @@ export declare class CommandExecutor {
      * console.log(nodeVersion); // v22.21.1
      * ```
      */
-    static exec(command: string): string;
+    static exec(command: string, options?: ExecOptions): string;
+    /**
+     * Выполнить команду через `execFileSync` без shell-интерпретации.
+     *
+     * Этот метод предпочтительнее {@link exec} в случаях, когда команда и её
+     * аргументы фиксированы и НЕ должны интерпретироваться шеллом
+     * (избегаем риска инъекции, кросс-платформенных проблем с кавычками и т.п.).
+     *
+     * @param command - Имя исполняемого файла (резолвится через PATH) или абсолютный путь
+     * @param args - Аргументы команды (каждый — отдельный элемент массива)
+     * @param options - Опции (включая `timeout` в мс)
+     * @returns stdout команды
+     * @throws {Error} Если команда завершилась с ненулевым кодом или превысила таймаут
+     *
+     * @example
+     * ```typescript
+     * const out = CommandExecutor.execFile('claude', ['mcp', 'list'], { timeout: 5000 });
+     * ```
+     */
+    static execFile(command: string, args: string[], options?: ExecOptions): string;
     /**
      * Выполнить команду тихо (подавить вывод)
      *

package/dist/utils/command-executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-executor.d.ts","sourceRoot":"","sources":["../../src/utils/command-executor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;;;;;;;;;;GAaG;AACH,qBAAa,eAAe;IAC1B;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAQpC;;;;;;;;;;OAUG;IACH,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAQxC;;;;;;;;;;;;;OAaG;WACU,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB5E;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;CAQpD"}
+{"version":3,"file":"command-executor.d.ts","sourceRoot":"","sources":["../../src/utils/command-executor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAyBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,eAAe;IAC1B;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,MAAM;IA4B/D;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,WAAgB,GAAG,MAAM;IA6BnF;;;;;;;;;;OAUG;IACH,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAQxC;;;;;;;;;;;;;OAaG;WACU,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB5E;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;CAQpD"}

package/dist/utils/command-executor.js

@@ -4,7 +4,31 @@
  * @module CommandExecutor
  * @description Утилита для выполнения shell команд с различными режимами вывода
  */
-import { execSync, spawn } from 'node:child_process';
+import { execFileSync, execSync, spawn } from 'node:child_process';
+/**
+ * Максимальная длина stderr в сообщении об ошибке.
+ *
+ * Цель — не раздувать message длинными выводами CLI (некоторые программы
+ * пишут многостраничный traceback). 200 символов достаточно для диагностики.
+ */
+const STDERR_PREVIEW_LIMIT = 200;
+/**
+ * Извлечь и обрезать stderr из объекта ошибки `execSync`/`execFileSync`.
+ */
+function extractStderr(err) {
+    if (typeof err !== 'object' || err === null)
+        return undefined;
+    const stderr = err.stderr;
+    if (stderr === undefined || stderr === null)
+        return undefined;
+    const text = typeof stderr === 'string' ? stderr : String(stderr);
+    const trimmed = text.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    return trimmed.length > STDERR_PREVIEW_LIMIT
+        ? `${trimmed.slice(0, STDERR_PREVIEW_LIMIT)}…`
+        : trimmed;
+}
 /**
  * Класс для выполнения shell команд
  *
@@ -13,6 +37,12 @@ import { execSync, spawn } from 'node:child_process';
  * // Выполнить команду и получить вывод
  * const output = CommandExecutor.exec('echo "test"');
  *
+ * // С таймаутом
+ * const output = CommandExecutor.exec('claude mcp list', { timeout: 5000 });
+ *
+ * // Безопасное выполнение без shell-интерпретации
+ * const out = CommandExecutor.execFile('claude', ['mcp', 'list'], { timeout: 5000 });
+ *
  * // Проверить наличие команды
  * if (CommandExecutor.isCommandAvailable('node')) {
  *   console.log('Node.js установлен');
@@ -21,11 +51,12 @@ import { execSync, spawn } from 'node:child_process';
  */
 export class CommandExecutor {
     /**
-     * Выполнить команду и вернуть stdout
+     * Выполнить команду и вернуть stdout.
      *
      * @param command - Команда для выполнения
+     * @param options - Опции выполнения (включая `timeout`)
      * @returns Вывод команды
-     * @throws {Error} Если команда завершилась с ошибкой
+     * @throws {Error} Если команда завершилась с ошибкой или превысила таймаут
      *
      * @example
      * ```typescript
@@ -33,12 +64,68 @@ export class CommandExecutor {
      * console.log(nodeVersion); // v22.21.1
      * ```
      */
-    static exec(command) {
+    static exec(command, options = {}) {
+        const execOptions = {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        };
+        if (options.timeout !== undefined) {
+            execOptions.timeout = options.timeout;
+            execOptions.killSignal = 'SIGKILL';
+        }
         try {
-            return execSync(command, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'ignore'] });
+            return execSync(command, execOptions);
         }
-        catch {
-            throw new Error(`Command failed: ${command}`);
+        catch (err) {
+            // `execSync` бросает ошибку с `signal === 'SIGKILL'` при таймауте.
+            const errorObj = err;
+            if (options.timeout !== undefined &&
+                (errorObj?.signal === 'SIGKILL' || errorObj?.code === 'ETIMEDOUT')) {
+                throw new Error(`Timeout: ${command} exceeded ${String(options.timeout)}ms`);
+            }
+            const stderr = extractStderr(err);
+            throw new Error(stderr ? `Command failed: ${command} (${stderr})` : `Command failed: ${command}`);
+        }
+    }
+    /**
+     * Выполнить команду через `execFileSync` без shell-интерпретации.
+     *
+     * Этот метод предпочтительнее {@link exec} в случаях, когда команда и её
+     * аргументы фиксированы и НЕ должны интерпретироваться шеллом
+     * (избегаем риска инъекции, кросс-платформенных проблем с кавычками и т.п.).
+     *
+     * @param command - Имя исполняемого файла (резолвится через PATH) или абсолютный путь
+     * @param args - Аргументы команды (каждый — отдельный элемент массива)
+     * @param options - Опции (включая `timeout` в мс)
+     * @returns stdout команды
+     * @throws {Error} Если команда завершилась с ненулевым кодом или превысила таймаут
+     *
+     * @example
+     * ```typescript
+     * const out = CommandExecutor.execFile('claude', ['mcp', 'list'], { timeout: 5000 });
+     * ```
+     */
+    static execFile(command, args, options = {}) {
+        const execOptions = {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        };
+        if (options.timeout !== undefined) {
+            execOptions.timeout = options.timeout;
+            execOptions.killSignal = 'SIGKILL';
+        }
+        const displayCmd = `${command} ${args.join(' ')}`.trim();
+        try {
+            return execFileSync(command, args, execOptions);
+        }
+        catch (err) {
+            const errorObj = err;
+            if (options.timeout !== undefined &&
+                (errorObj?.signal === 'SIGKILL' || errorObj?.code === 'ETIMEDOUT')) {
+                throw new Error(`Timeout: ${displayCmd} exceeded ${String(options.timeout)}ms`);
+            }
+            const stderr = extractStderr(err);
+            throw new Error(stderr ? `Command failed: ${displayCmd} (${stderr})` : `Command failed: ${displayCmd}`);
         }
     }
     /**
@@ -82,7 +169,7 @@ export class CommandExecutor {
                     resolve();
                 }
                 else {
-                    reject(new Error(`Command exited with code ${code}`));
+                    reject(new Error(`Command exited with code ${String(code)}`));
                 }
             });
             child.on('error', reject);