dsh-edt-projects 0.0.0-stage → 0.9.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Iosif Pravets
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,29 @@
-# Temporary Holding Version
+# dsh-edt-projects
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Плагин [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) для
+разработки на 1С: держит **1C:EDT** подключённым через
+[EDT-MCP](https://github.com/DitriXNew/EDT-MCP), поднимает **BSL Language Server**
+по требованию, добавляет настройки на проект, правила для модели и навыки
+SonarQube/GitLab.
+
+## Установка
+
+```text
+plugin_manager { action: "install_bundle", target: "dsh-edt-projects" }
+```
+
+Нужны EDT 2026.1/2026.2 с установленным EDT-MCP и запущенным MCP-сервером
+(по умолчанию `127.0.0.1:8765`) — подробности и настройка в
+[README репозитория](https://github.com/pravets/dsh-edt-projects#readme).
+
+## Что внутри
+
+- `lib/` — хаб MCP-серверов: монтаж по требованию (`mcp_pin`), настройки на
+  проект, правила для системного промпта, провайдер навыков.
+- `skills/` — навыки `edt-mcp-project-sonar` и `edt-mcp-project-gitlab`,
+  включаются флагами `sonar.enabled` и `gitlab.enabled`.
+- `cordis.patch.yml` — состав серверов, который применяет менеджер плагинов.
+
+## Лицензия
+
+MIT, см. [LICENSE](LICENSE).

package/cordis.patch.yml

@@ -0,0 +1,83 @@
+# Хаб MCP-серверов для разработки на 1С.
+#
+# Серверы описываются здесь и подключаются плагином mcp-hub (lib/index.js):
+#   - `lazy: true`      — не занимать контекст: сервер монтируется по вызову mcp_pin
+#   - `provision: true` — параметры запуска добираются на mcp_pin (BSL LS скачивается)
+#   - `shared: true`    — одна копия на процесс; остальные серверы монтируются
+#                         в скоуп агента (параллельные worktree не мешают друг другу)
+#   - `unavailable`     — сервер описан, но настроить его нечем (mcp_pin объяснит, чем)
+#
+# Настройки можно переопределить без перезапуска DSH — файлами
+# $DSH_HOME/dsh-1c.json (пользователь) и <cwd>/.dsh-1c.json (проект):
+#   { "wiki": { "paths": ["C:\\git\\dev-llm-wiki"], "entry": "wiki/index.md" },
+#     "servers": { "edt": { "url": "http://127.0.0.1:8765/mcp" },
+#                  "bsl": { "root": "C:\\git\\trade\\src\\cf" } },
+#     "tests": { "yaxunit": { "enabled": true, "path": "tests/yaxunit", "project": "cfe_yaxunit" },
+#                "vanessa": { "enabled": true, "path": "features" } } }
+# После правки файла: mcp_reload (или mcp_pin заново).
+# Флаги tests включают правила тестируемости: YAxUnit — закладывать тестируемость
+# и писать тесты в указанный проект, Vanessa — предлагать сценарные тесты.
+#
+# Переменные окружения (префикс DSH_1C_ — чтобы ни с чем не пересекаться):
+#   EDT_MCP_URL               адрес MCP-сервера EDT (по умолчанию 127.0.0.1:8765)
+#   EDT_MCP_TOKEN             токен, если он включён в EDT
+#   DSH_1C_WIKI               пути к вики через «;»
+#   DSH_1C_WIKI_ENTRY         входная точка вики, например wiki/index.md
+#   DSH_1C_BSL_LS_JAR         готовый bsl-language-server jar (главнее всего)
+#   DSH_1C_BSL_LS_URL         прямой URL на jar вместо GitHub
+#   DSH_1C_BSL_LS_VERSION     тег релиза, например v1.0.7 (по умолчанию последний)
+#   DSH_1C_BSL_LS_GITHUB_TOKEN токен GitHub для API (иначе GITHUB_TOKEN, GH_TOKEN):
+#                             без него загрузка идёт со страниц релизов и не упирается
+#                             в лимит API 60/ч на IP
+#   DSH_1C_BSL_LS_CACHE       каталог кэша ($DSH_HOME/cache/bsl-language-server)
+#   DSH_1C_BSL_LS_DOWNLOAD    «0» — не скачивать, использовать только готовый jar
+#   DSH_1C_BSL_LS_JAVA        java-команда (по умолчанию java)
+#   DSH_1C_BSL_LS_ROOT        корень исходников для BSL LS
+#   DSH_1C_BSL_MCP_URL        адрес уже запущенного BSL LS по Streamable HTTP
+#   TASKS_MCP_URL             адрес MCP-сервера системы задач
+#   TASKS_MCP_TOKEN           токен системы задач
+- insert:
+    - id: mcp-hub
+      name: 'dsh-edt-projects'
+      config:
+        wiki:
+          paths: !!js 'process.env.DSH_1C_WIKI ? process.env.DSH_1C_WIKI.split(";").filter(Boolean) : []'
+          entry: !!js 'process.env.DSH_1C_WIKI_ENTRY ?? ""'
+        servers:
+          # EDT один на процесс: одна копия, чтобы агенты не поднимали лишние сессии.
+          edt:
+            shared: true
+            lazy: false
+            transport: streamable-http
+            url: !!js 'process.env.EDT_MCP_URL ?? "http://127.0.0.1:8765/mcp"'
+            headers: !!js 'process.env.EDT_MCP_TOKEN ? { Authorization: `Bearer ${process.env.EDT_MCP_TOKEN}` } : {}'
+            # Операции EDT (update_database, run_yaxunit_tests, валидация) идут дольше 60 с.
+            toolCallTimeoutMs: 900000
+            # EDT часто закрыт: не валить активацию, ждать сервер.
+            failOnStartupError: false
+            reconnect:
+              enabled: true
+              initialDelayMs: 1000
+              maxDelayMs: 30000
+              maxAttempts: 1000
+
+          # BSL Language Server: 10 инструментов, нужны эпизодически.
+          # provision: на mcp_pin берётся готовый jar из DSH_1C_BSL_LS_JAR, иначе из
+          # кэша, иначе скачивается последний релиз с GitHub (sha256 сверяется).
+          # Корень по умолчанию — servers.bsl.root из файла настроек проекта.
+          bsl:
+            lazy: true
+            provision: true
+            toolCallTimeoutMs: 120000
+            failOnStartupError: false
+
+          # Система задач: место зарезервировано под любой MCP-сервер.
+          # Конкретный продукт (YouTrack, Jira, GitLab, GitHub) — это его адрес и токен.
+          tasks:
+            lazy: true
+            unavailable: !!js '!process.env.TASKS_MCP_URL'
+            transport: streamable-http
+            url: !!js 'process.env.TASKS_MCP_URL ?? "http://127.0.0.1:8090/mcp"'
+            headers: !!js 'process.env.TASKS_MCP_TOKEN ? { Authorization: `Bearer ${process.env.TASKS_MCP_TOKEN}` } : {}'
+            toolCallTimeoutMs: 120000
+            failOnStartupError: false

package/icon.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="1C:EDT MCP">
+  <rect x="3" y="3" width="58" height="58" rx="14" fill="#132a4a"/>
+  <path d="M18 23h20M18 32h28M18 41h14" fill="none" stroke="#6fb3ff" stroke-width="4" stroke-linecap="round"/>
+  <circle cx="47" cy="42" r="7" fill="#38d17a"/>
+  <path d="M43.5 42.2l2.6 2.6 4.6-5" fill="none" stroke="#132a4a" stroke-width="2.6" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/lib/bsl.mjs

@@ -0,0 +1,455 @@
+// Загрузка BSL Language Server по требованию: явный путь, прямой URL, страницы
+// релизов GitHub или API (с проверкой sha256).
+//
+// GitHub API без токена даёт 60 запросов в час на IP, поэтому источник выбирается
+// по наличию токена: с токеном — API первым, без токена — сначала обычные
+// страницы релизов (они не в лимите API), а API лишь как резерв.
+//
+// Все переменные окружения — с префиксом DSH_1C_, чтобы не пересекаться ни с
+// чем на машине. Старые имена (BSL_LS_JAR, BSL_MCP_URL…) принимаются как fallback.
+//
+//   DSH_1C_BSL_LS_JAR        готовый jar (главнее всего остального)
+//   DSH_1C_BSL_LS_URL        прямой URL на jar (зеркало, офлайн-раздача)
+//   DSH_1C_BSL_LS_VERSION    тег релиза, например v1.0.7 (по умолчанию последний)
+//   DSH_1C_BSL_LS_GITHUB_TOKEN  токен GitHub для API (иначе GITHUB_TOKEN, GH_TOKEN)
+//   DSH_1C_BSL_LS_CACHE      каталог кэша (по умолчанию $DSH_HOME/cache/bsl-language-server)
+//   DSH_1C_BSL_LS_DOWNLOAD   «0» — запретить скачивание
+//   DSH_1C_BSL_LS_JAVA       java-команда (по умолчанию java)
+//   DSH_1C_BSL_LS_CWD        рабочий каталог сервера (корень исходников)
+//   DSH_1C_BSL_LS_ROOT       корень рабочего пространства (главнее CWD)
+//   DSH_1C_BSL_LS_PORT       порт встроенного веб-сервера (по умолчанию свободный)
+//   DSH_1C_BSL_LS_MODE       hybrid (по умолчанию) или stdio
+//   DSH_1C_BSL_MCP_URL       адрес уже запущенного BSL LS по Streamable HTTP
+import { createHash } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { createWriteStream, existsSync, mkdirSync, readdirSync, rmSync, renameSync, statSync } from 'node:fs';
+import { connect, createServer } from 'node:net';
+import { homedir } from 'node:os';
+import { basename, join } from 'node:path';
+import { Readable } from 'node:stream';
+import { pathToFileURL } from 'node:url';
+
+export const REPO = '1c-syntax/bsl-language-server';
+/** 130 МБ по медленному каналу — запас большой. */
+export const DOWNLOAD_TIMEOUT_MS = 30 * 60 * 1000;
+const ASSET_PATTERN = /-exec\.jar$/;
+const RELEASES_URL = `https://github.com/${REPO}/releases`;
+const API_REPO_URL = `https://api.github.com/repos/${REPO}`;
+const REQUEST_TIMEOUT_MS = 30_000;
+
+/** GitHub API ответил лимитом запросов: сообщение должно подсказывать выход. */
+export class RateLimitError extends Error {
+  constructor(message, { resetAt, status } = {}) {
+    super(message);
+    this.name = 'RateLimitError';
+    this.resetAt = resetAt;
+    this.status = status;
+  }
+}
+
+/** Скачанный файл не совпал по sha256: повтор без сверки недопустим. */
+export class IntegrityError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'IntegrityError';
+  }
+}
+
+const first = (env, ...names) => names.map((name) => env[name]).find((value) => value !== undefined && value !== '');
+const isOff = (value) => ['0', 'false', 'no', 'off'].includes(String(value).toLowerCase());
+
+/** Разбирает окружение в настройки загрузчика. */
+export function bslSettings(env = process.env) {
+  const download = first(env, 'DSH_1C_BSL_LS_DOWNLOAD');
+  return {
+    jar: first(env, 'DSH_1C_BSL_LS_JAR', 'BSL_LS_JAR'),
+    url: first(env, 'DSH_1C_BSL_LS_URL'),
+    version: first(env, 'DSH_1C_BSL_LS_VERSION'),
+    githubToken: first(env, 'DSH_1C_BSL_LS_GITHUB_TOKEN', 'GITHUB_TOKEN', 'GH_TOKEN'),
+    mcpUrl: first(env, 'DSH_1C_BSL_MCP_URL', 'BSL_MCP_URL'),
+    cacheDir: first(env, 'DSH_1C_BSL_LS_CACHE') ?? join(env.DSH_HOME ?? join(homedir(), '.dsh'), 'cache', 'bsl-language-server'),
+    java: first(env, 'DSH_1C_BSL_LS_JAVA', 'BSL_LS_JAVA') ?? 'java',
+    cwd: first(env, 'DSH_1C_BSL_LS_CWD', 'BSL_LS_CWD') ?? '',
+    root: first(env, 'DSH_1C_BSL_LS_ROOT', 'DSH_1C_BSL_LS_CWD', 'BSL_LS_CWD') ?? process.cwd(),
+    port: first(env, 'DSH_1C_BSL_LS_PORT'),
+    mode: (first(env, 'DSH_1C_BSL_LS_MODE') ?? 'hybrid').toLowerCase(),
+    downloadAllowed: download === undefined ? true : !isOff(download),
+  };
+}
+
+/** Выбирает из релиза исполняемый jar и его sha256. */
+export function selectExecAsset(release) {
+  const assets = Array.isArray(release?.assets) ? release.assets : [];
+  const asset = assets.find((item) => ASSET_PATTERN.test(String(item.name)));
+  if (!asset) throw new Error(`в релизе ${release?.tag_name ?? '?'} нет ассета *-exec.jar`);
+  const digest = typeof asset.digest === 'string' && asset.digest.startsWith('sha256:') ? asset.digest.slice('sha256:'.length) : undefined;
+  return {
+    tag: release.tag_name,
+    name: asset.name,
+    url: asset.browser_download_url,
+    size: asset.size,
+    sha256: digest,
+  };
+}
+
+function cachedJars(cacheDir) {
+  if (!existsSync(cacheDir)) return [];
+  return readdirSync(cacheDir)
+    .filter((name) => name.endsWith('-exec.jar'))
+    .map((name) => join(cacheDir, name))
+    .sort((left, right) => statSync(right).mtimeMs - statSync(left).mtimeMs);
+}
+
+async function downloadToFile(url, target, { fetchImpl, log, timeoutMs = DOWNLOAD_TIMEOUT_MS, expectSha256 }) {
+  mkdirSync(join(target, '..'), { recursive: true });
+  const partial = `${target}.part`;
+  log(`скачиваю ${url}`);
+
+  const response = await fetchImpl(url, { redirect: 'follow', signal: AbortSignal.timeout(timeoutMs) });
+  if (!response.ok || response.body === null) throw new Error(`загрузка ${url} не удалась: HTTP ${response.status}`);
+
+  const hash = createHash('sha256');
+  const stream = createWriteStream(partial);
+  let received = 0;
+  let lastReport = 0;
+  try {
+    for await (const chunk of Readable.fromWeb(response.body)) {
+      hash.update(chunk);
+      received += chunk.length;
+      if (!stream.write(chunk)) await new Promise((done) => stream.once('drain', done));
+      if (received - lastReport >= 10 * 1024 * 1024) {
+        lastReport = received;
+        log(`получено ${(received / 1024 / 1024).toFixed(1)} МБ`);
+      }
+    }
+  } finally {
+    await new Promise((done, fail) => stream.end((error) => (error ? fail(error) : done())));
+  }
+
+  const actual = hash.digest('hex');
+  if (expectSha256 !== undefined && actual !== expectSha256) {
+    rmSync(partial, { force: true });
+    throw new IntegrityError(`sha256 не совпал: ожидался ${expectSha256}, получен ${actual}`);
+  }
+
+  renameSync(partial, target);
+  log(`сохранено ${target} (${(received / 1024 / 1024).toFixed(1)} МБ)`);
+  return target;
+}
+
+/** Предсказуемый адрес ассета: имя файла детерминировано тегом релиза. */
+export function predictAsset(tag) {
+  const version = String(tag).replace(/^v/, '');
+  const name = `bsl-language-server-${version}-exec.jar`;
+  return { tag, name, url: `${RELEASES_URL}/download/${tag}/${name}`, sha256: undefined, unverified: true };
+}
+
+/** Тег последнего релиза из обычной страницы: она редиректит на releases/tag/<тег>. */
+async function latestTag(fetchImpl, log) {
+  const url = `${RELEASES_URL}/latest`;
+  log(`запрашиваю ${url}`);
+  const response = await fetchImpl(url, { redirect: 'follow', signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+  if (!response.ok) throw new Error(`страница последнего релиза ${url}: HTTP ${response.status}`);
+  const location = String(response.url ?? response.headers?.get?.('location') ?? '');
+  const tag = location.split('/').filter(Boolean).pop();
+  if (tag === undefined || !/^v?\d/.test(tag)) throw new Error(`не удалось определить тег последнего релиза (${location || url})`);
+  return tag;
+}
+
+/**
+ * Разбирает релиз со страниц github.com — они не расходуют лимит API.
+ * На странице ассетов рядом с ссылкой лежит и sha256.
+ * @returns {{tag: string, name: string, url: string, sha256: string|undefined}}
+ */
+export async function resolveReleaseViaHtml(fetchImpl, { tag, log = () => {} } = {}) {
+  const resolvedTag = tag ?? (await latestTag(fetchImpl, log));
+  const url = `${RELEASES_URL}/expanded_assets/${encodeURIComponent(resolvedTag)}`;
+  log(`запрашиваю ${url}`);
+  const response = await fetchImpl(url, { signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+  if (!response.ok) throw new Error(`страница ассетов ${url}: HTTP ${response.status}`);
+
+  const html = await response.text();
+  const name = /href="[^"]*\/([^"/]+-exec\.jar)"/.exec(html)?.[1];
+  if (name === undefined) throw new Error(`на ${url} нет ассета *-exec.jar`);
+  const start = html.indexOf(name);
+  const sha256 = /sha256:([0-9a-f]{64})/i.exec(html.slice(start, start + 2000))?.[1];
+  return { tag: resolvedTag, name, url: `${RELEASES_URL}/download/${resolvedTag}/${name}`, sha256 };
+}
+
+/** Ассет из GitHub API: JSON содержит и тег, и digest. */
+async function apiAsset(tag, { fetchImpl, log, token }) {
+  const url = tag === undefined ? `${API_REPO_URL}/releases/latest` : `${API_REPO_URL}/releases/tags/${tag}`;
+  return selectExecAsset(await fetchJson(fetchImpl, url, { log, token }));
+}
+
+/**
+ * Источники релиза по порядку. С токеном API первым, без токена — страницы
+ * релизов: лимит 60/ч на IP перестаёт быть условием инициализации.
+ * Функции не вызываются здесь: каждый следующий источник пробуется только
+ * после отказа предыдущего, поэтому успешная страница не тянет за собой API.
+ */
+function assetSources(settings, deps) {
+  const { fetchImpl, log, token } = deps;
+  const tag = settings.version;
+  const viaHtml = () => resolveReleaseViaHtml(fetchImpl, { tag, log });
+  const viaApi = () => apiAsset(tag, deps);
+  const sources = token === undefined ? [viaHtml, viaApi] : [viaApi, viaHtml];
+  // Предсказуемый адрес — последний сетевой резерв, только если тег известен.
+  if (tag !== undefined) sources.push(async () => predictAsset(tag));
+  return sources;
+}
+
+/**
+ * Возвращает путь к jar: явный, из кэша или скачанный с GitHub.
+ * @param settings настройки из bslSettings().
+ * @param deps { fetchImpl, log, warn } — подменяются в тестах.
+ */
+export async function ensureJar(settings, deps = {}) {
+  const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
+  const log = deps.log ?? (() => {});
+  const warn = deps.warn ?? log;
+
+  if (settings.jar !== undefined) {
+    if (!existsSync(settings.jar)) throw new Error(`DSH_1C_BSL_LS_JAR указывает на ${settings.jar}, файла нет`);
+    return settings.jar;
+  }
+
+  if (settings.url !== undefined) {
+    const target = join(settings.cacheDir, basename(new URL(settings.url).pathname) || 'bsl-language-server-exec.jar');
+    if (existsSync(target)) return target;
+    return downloadToFile(settings.url, target, { fetchImpl, log });
+  }
+
+  if (!settings.downloadAllowed) {
+    throw new Error('BSL LS не настроен: задайте DSH_1C_BSL_LS_JAR (или URL) либо разрешите скачивание (DSH_1C_BSL_LS_DOWNLOAD не 0)');
+  }
+
+  const cached = cachedJars(settings.cacheDir);
+  // Зафиксированная версия: сначала кэш именно этой версии.
+  if (settings.version !== undefined) {
+    const target = join(settings.cacheDir, `bsl-language-server-${settings.version.replace(/^v/, '')}-exec.jar`);
+    if (existsSync(target)) return target;
+  } else if (cached.length > 0) {
+    // Версия не задана: годится любой уже скачанный jar.
+    log(`использую кэш ${cached[0]}`);
+    return cached[0];
+  }
+
+  const failures = [];
+  let rateLimited;
+  const text = (error) => (error instanceof Error ? error.message : String(error));
+
+  for (const source of assetSources(settings, { fetchImpl, log, token: settings.githubToken })) {
+    let asset;
+    try {
+      asset = await source();
+    } catch (error) {
+      if (error instanceof RateLimitError) rateLimited = error;
+      failures.push(error);
+      warn(`источник релиза не сработал: ${text(error)}`);
+      continue;
+    }
+
+    const target = join(settings.cacheDir, asset.name);
+    if (existsSync(target)) return target;
+    if (asset.unverified === true) {
+      warn(`sha256 для ${asset.name} не сверен: страницы релиза недоступны, скачиваю по предсказуемому адресу`);
+    }
+    try {
+      return await downloadToFile(asset.url, target, { fetchImpl, log, expectSha256: asset.sha256 });
+    } catch (error) {
+      // Подмена файла не лечится повтором без сверки — сразу наверх.
+      if (error instanceof IntegrityError) throw error;
+      failures.push(error);
+      warn(`не удалось скачать ${asset.name}: ${text(error)}`);
+    }
+  }
+
+  // Любая версия из кэша лучше, чем немигающая инициализация BSL LS.
+  if (cached.length > 0) {
+    const reason = rateLimited ?? failures[failures.length - 1];
+    warn(`релиз недоступен (${reason === undefined ? 'нет источников' : text(reason)}); использую кэш ${basename(cached[0])}`);
+    return cached[0];
+  }
+
+  if (rateLimited !== undefined) throw rateLimited;
+  throw new Error(`не удалось получить релиз BSL LS: ${failures.map(text).join('; ')}`);
+}
+
+/** Тело ответа API в виде текста ошибки, если оно есть. */
+async function responseMessage(response) {
+  try {
+    const body = await response.json();
+    return typeof body?.message === 'string' ? body.message : '';
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Запрос к GitHub API. Токен уходит только на api.github.com — ни на страницы,
+ * ни на скачивание ассета. Лимит распознаётся и превращается в понятную ошибку.
+ */
+export async function fetchJson(fetchImpl, url, { log = () => {}, token } = {}) {
+  log(`запрашиваю ${url}`);
+  const headers = { accept: 'application/vnd.github+json', 'user-agent': 'dsh-edt-projects' };
+  if (token !== undefined && new URL(url).host === 'api.github.com') headers.authorization = `Bearer ${token}`;
+
+  const response = await fetchImpl(url, { headers, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+  if (response.ok) return response.json();
+
+  const message = await responseMessage(response);
+  const header = (name) => response.headers?.get?.(name);
+  const resetSeconds = Number(header('x-ratelimit-reset'));
+  const resetAt = Number.isFinite(resetSeconds) && resetSeconds > 0 ? resetSeconds : undefined;
+  const limited = response.status === 429 || (response.status === 403 && (header('x-ratelimit-remaining') === '0' || /rate limit/i.test(message) || resetAt !== undefined));
+  if (limited) {
+    const until = resetAt === undefined ? '' : ` Сброс лимита не раньше ${new Date(resetAt * 1000).toISOString()}.`;
+    throw new RateLimitError(
+      `GitHub API исчерпал лимит запросов (без токена — 60/ч на IP).${until}` +
+        ' Варианты: задать DSH_1C_BSL_LS_GITHUB_TOKEN, DSH_1C_BSL_LS_VERSION (скачивание без API), DSH_1C_BSL_LS_URL или DSH_1C_BSL_LS_JAR.',
+      { resetAt, status: response.status },
+    );
+  }
+  throw new Error(`GitHub API ${url}: HTTP ${response.status}${message === '' ? '' : ` — ${message}`}`);
+}
+
+/**
+ * Собирает параметры монтирования BSL LS.
+ * @returns {{transport: 'stdio', command: string, args: string[], cwd: string} |
+ *           {transport: 'streamable-http', url: string}}
+ */
+export async function resolveBsl(settings, deps = {}) {
+  if (settings.mcpUrl !== undefined) return { transport: 'streamable-http', url: settings.mcpUrl };
+  const jar = await ensureJar(settings, deps);
+  return { transport: 'stdio', command: settings.java, args: ['-jar', jar, 'mcp'], cwd: settings.cwd };
+}
+
+/** Можно ли вообще поднять сервер: без скачивания, пути и кэша он «не настроен». */
+export function bslAvailable(settings) {
+  if (settings.mcpUrl !== undefined) return true;
+  if (settings.jar !== undefined || settings.url !== undefined) return true;
+  if (settings.downloadAllowed) return true;
+  // Кэш остаётся рабочим источником и при DSH_1C_BSL_LS_DOWNLOAD=0.
+  return settings.cacheDir !== undefined && cachedJars(settings.cacheDir).length > 0;
+}
+
+/** Свободный порт на loopback. */
+export function freePort() {
+  return new Promise((resolvePort, reject) => {
+    const probe = createServer();
+    probe.once('error', reject);
+    probe.listen(0, '127.0.0.1', () => {
+      const { port: found } = probe.address();
+      probe.close(() => resolvePort(found));
+    });
+  });
+}
+
+/** LSP-сообщение с заголовком Content-Length. */
+export function lspFrame(message) {
+  const body = JSON.stringify(message);
+  return `Content-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`;
+}
+
+/** Ждёт, пока на порту начнёт приниматься TCP. */
+export async function waitForPort(port, { timeoutMs = 180_000, intervalMs = 500 } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const connected = await new Promise((resolveConnect) => {
+      const socket = connect({ host: '127.0.0.1', port });
+      const settle = (ok) => {
+        socket.destroy();
+        resolveConnect(ok);
+      };
+      socket.setTimeout(1000);
+      socket.once('connect', () => settle(true));
+      socket.once('timeout', () => settle(false));
+      socket.once('error', () => settle(false));
+    });
+    if (connected) return;
+    if (Date.now() > deadline) throw new Error(`BSL LS не открыл порт ${port} за ${Math.round(timeoutMs / 1000)} с`);
+    await new Promise((done) => setTimeout(done, intervalMs));
+  }
+}
+
+/**
+ * Поднимает BSL LS в гибридном режиме: LSP по stdio объявляет рабочие
+ * пространства (workspace folders), MCP открывается по Streamable HTTP на том
+ * же процессе. Так BSL LS получает корни, которых не умеет передавать
+ * dsh-mcp-client (он не объявляет capability roots).
+ *
+ * @param options.jar путь к jar, options.java команда java, options.root корень
+ * @returns {{url: string, root: string, stop: () => Promise<void>}}
+ */
+export async function startBslSupervisor({ jar, java = 'java', root, port, log = () => {}, timeoutMs = 180_000 }) {
+  // Каталог корня должен существовать: иначе spawn падает с ENOENT, и вместо
+  // понятной ошибки получается долгое ожидание порта.
+  if (!existsSync(root)) throw new Error(`каталог рабочего пространства не найден: ${root}`);
+
+  const actualPort = port === undefined ? await freePort() : Number(port);
+  log(`запускаю BSL LS: ${java} -jar ${basename(jar)} lsp --mcp --server.port=${actualPort} (root ${root})`);
+
+  const child = (() => {
+    try {
+      return spawn(java, ['-jar', jar, 'lsp', '--mcp', `--server.port=${actualPort}`], {
+        cwd: root,
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+    } catch (error) {
+      // Windows может бросить синхронно (нет прав на создание процесса).
+      throw new Error(`BSL LS не удалось запустить (${java}): ${error.message}`);
+    }
+  })();
+
+  // Ошибка запуска и ранний выход должны прерывать ожидание, а не висеть в нём.
+  let startupFailure = null;
+  const failed = new Promise((_, reject) => {
+    child.once('error', (error) => {
+      startupFailure = error.code === 'ENOENT' ? `команда ${java} не найдена` : error.message;
+      reject(new Error(`BSL LS не запустился: ${startupFailure}`));
+    });
+    child.once('exit', (code, signal) => {
+      startupFailure = `процесс завершился (${signal ?? code})`;
+      reject(new Error(`BSL LS завершился при запуске: ${signal ?? code}`));
+    });
+  });
+  failed.catch(() => {});
+
+  child.stderr.on('data', (chunk) => {
+    const text = String(chunk);
+    if (/ERROR|Exception|WARN.*roots/i.test(text)) log(text.trim().slice(0, 400));
+  });
+
+  const rootUri = pathToFileURL(root).href;
+  child.stdin.write(
+    lspFrame({
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'initialize',
+      params: {
+        processId: process.pid,
+        rootUri,
+        workspaceFolders: [{ uri: rootUri, name: basename(root) || 'workspace' }],
+        capabilities: {},
+      },
+    }),
+  );
+  child.stdin.write(lspFrame({ jsonrpc: '2.0', method: 'initialized', params: {} }));
+
+  try {
+    await Promise.race([waitForPort(actualPort, { timeoutMs }), failed]);
+  } catch (error) {
+    child.kill();
+    throw error;
+  }
+
+  return {
+    url: `http://127.0.0.1:${actualPort}/mcp`,
+    root,
+    stop: async () => {
+      child.kill();
+    },
+  };
+}
+

package/lib/config-file.mjs

@@ -0,0 +1,67 @@
+// Создание и обновление файла настроек dsh-1c.json.
+//
+// Существующие значения не перезаписываются: init отказывается работать при
+// наличии файла, upgrade только дописывает недостающие ключи. Запись атомарная.
+import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+
+import { DEFAULTS, planUpgrade, stringifyConfig, validateConfig } from './schema.mjs';
+
+/** Читает файл настроек; отсутствие — не ошибка. */
+export function readExisting(path) {
+  if (!existsSync(path)) return { exists: false };
+  try {
+    const config = JSON.parse(readFileSync(path, 'utf8'));
+    if (config === null || typeof config !== 'object' || Array.isArray(config)) {
+      return { exists: true, error: `${path}: ожидался JSON-объект` };
+    }
+    return { exists: true, config };
+  } catch (error) {
+    return { exists: true, error: `${path}: ${error.message}` };
+  }
+}
+
+/** Атомарная запись: временный файл рядом, затем rename. */
+export function writeAtomic(path, text) {
+  const tmp = `${path}.tmp`;
+  try {
+    writeFileSync(tmp, text, 'utf8');
+    renameSync(tmp, path);
+  } catch (error) {
+    rmSync(tmp, { force: true });
+    throw error;
+  }
+}
+
+/**
+ * Создаёт файл со значениями по умолчанию.
+ * @returns {{ status: 'created'|'exists'|'error', path: string, keys?: string[], error?: string }}
+ */
+export function initFile(path) {
+  const existing = readExisting(path);
+  if (existing.error !== undefined) return { status: 'error', path, error: existing.error };
+  if (existing.exists) return { status: 'exists', path };
+
+  writeAtomic(path, stringifyConfig(DEFAULTS));
+  return { status: 'created', path, keys: Object.keys(DEFAULTS) };
+}
+
+/**
+ * Дописывает недостающие ключи. При `dryRun` файл не трогается.
+ * @returns {{ status: 'updated'|'noop'|'error'|'dry-run', path: string,
+ *             added: string[], warnings: string[], errors: string[], config?: object, error?: string }}
+ */
+export function upgradeFile(path, { dryRun = false } = {}) {
+  const existing = readExisting(path);
+  if (existing.error !== undefined) return { status: 'error', path, error: existing.error, added: [], warnings: [], errors: [] };
+
+  const base = existing.exists ? existing.config : {};
+  const plan = planUpgrade(base);
+  const { errors, warnings } = validateConfig(plan.config);
+
+  const result = { path, added: plan.added, warnings, errors, config: plan.config, version: plan.version };
+  if (plan.added.length === 0) return { status: 'noop', ...result };
+  if (dryRun) return { status: 'dry-run', ...result };
+
+  writeAtomic(path, stringifyConfig(plan.config));
+  return { status: 'updated', ...result };
+}