dsh-desktop-kit 2.2.1 → 2.7.2

package/plugins/dsh-agent-extensions/lib/project.js

@@ -0,0 +1,144 @@
+/**
+ * Project discovery for agent extensions.
+ *
+ * Everything is optional and project-local: `.dsh/hooks.json`,
+ * `.dsh/agents/*.md`, `.dsh/commands/*.md`, `.dsh/verify.json`. A project
+ * without `.dsh` simply gets no extra hooks/commands/agents.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+export const BUILTIN_COMMANDS = new Set(["init", "doctor", "verify", "hooks", "checkpoint", "rewind", "project"]);
+
+export function findDshDir(start) {
+  let current = path.resolve(start || process.cwd());
+  for (let depth = 0; depth < 8; depth += 1) {
+    const candidate = path.join(current, ".dsh");
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) return { root: current, dsh: candidate };
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return { root: path.resolve(start || process.cwd()), dsh: null };
+}
+
+export function projectFor(cwd) {
+  if (typeof cwd !== "string" || cwd.trim().length === 0) return { root: process.cwd(), dsh: null };
+  return findDshDir(cwd);
+}
+
+export function parseFrontmatter(text) {
+  const source = String(text ?? "").replace(/^\uFEFF/u, "");
+  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/u.exec(source);
+  if (!match) return { meta: {}, body: source.trim() };
+  const meta = {};
+  for (const line of match[1].split(/\r?\n/u)) {
+    const pair = /^([A-Za-z0-9_-]+)\s*:\s*(.*)$/u.exec(line.trim());
+    if (!pair) continue;
+    let value = pair[2].trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    if (value === "true") value = true;
+    else if (value === "false") value = false;
+    meta[pair[1]] = value;
+  }
+  return { meta, body: source.slice(match[0].length).trim() };
+}
+
+function listMarkdown(directory) {
+  try {
+    return fs
+      .readdirSync(directory, { withFileTypes: true })
+      .filter((entry) => entry.isFile() && /\.md$/iu.test(entry.name))
+      .map((entry) => entry.name)
+      .sort((left, right) => left.localeCompare(right));
+  } catch {
+    return [];
+  }
+}
+
+export function loadAgents(projectDir, dshDir) {
+  const directory = dshDir ? path.join(dshDir, "agents") : null;
+  if (!directory || !fs.existsSync(directory)) return [];
+  const agents = [];
+  for (const name of listMarkdown(directory)) {
+    try {
+      const parsed = parseFrontmatter(fs.readFileSync(path.join(directory, name), "utf8"));
+      const id = String(parsed.meta.name || name.replace(/\.md$/iu, "")).trim();
+      if (!/^[a-z0-9][a-z0-9_-]{0,48}$/iu.test(id)) continue;
+      if (!parsed.body) continue;
+      agents.push({
+        name: id,
+        description: typeof parsed.meta.description === "string" ? parsed.meta.description : "",
+        model: typeof parsed.meta.model === "string" ? parsed.meta.model : "",
+        tools: typeof parsed.meta.tools === "string" ? parsed.meta.tools : "",
+        permission: typeof parsed.meta.permission === "string" ? parsed.meta.permission : "full",
+        body: parsed.body,
+        file: path.join(directory, name),
+      });
+    } catch {
+      /* unreadable agent */
+    }
+  }
+  return agents;
+}
+
+export function loadCommands(projectDir, dshDir) {
+  const directory = dshDir ? path.join(dshDir, "commands") : null;
+  if (!directory || !fs.existsSync(directory)) return [];
+  const commands = [];
+  for (const name of listMarkdown(directory)) {
+    const id = name.replace(/\.md$/iu, "").trim().toLowerCase();
+    if (!/^[a-z0-9][a-z0-9_-]{0,40}$/u.test(id) || BUILTIN_COMMANDS.has(id)) continue;
+    try {
+      const parsed = parseFrontmatter(fs.readFileSync(path.join(directory, name), "utf8"));
+      if (!parsed.body) continue;
+      commands.push({
+        name: id,
+        description: typeof parsed.meta.description === "string" ? parsed.meta.description : `Проектная команда /${id}`,
+        body: parsed.body,
+        file: path.join(directory, name),
+      });
+    } catch {
+      /* unreadable command */
+    }
+  }
+  return commands;
+}
+
+export function loadHooks(projectDir, dshDir) {
+  const file = dshDir ? path.join(dshDir, "hooks.json") : null;
+  if (!file || !fs.existsSync(file)) return { hooks: {}, trusted: false, file };
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return { hooks: {}, trusted: false, file, error: "hooks.json: invalid JSON" };
+  }
+  const hooks = parsed && typeof parsed.hooks === "object" && parsed.hooks !== null ? parsed.hooks : {};
+  const trusted = Boolean(dshDir && fs.existsSync(path.join(dshDir, "hooks.trusted")));
+  return { hooks, trusted, file };
+}
+
+export function loadVerify(projectDir, dshDir) {
+  const file = dshDir ? path.join(dshDir, "verify.json") : null;
+  if (file && fs.existsSync(file)) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+      if (Array.isArray(parsed?.commands)) {
+        return { commands: parsed.commands.filter((item) => typeof item === "string" && item.trim()).slice(0, 10), source: file };
+      }
+    } catch {
+      /* fall through */
+    }
+  }
+  return { commands: [], source: null };
+}
+
+export function projectSummary(projectDir) {
+  const agents = loadAgents(projectDir, path.join(projectDir, ".dsh"));
+  const commands = loadCommands(projectDir, path.join(projectDir, ".dsh"));
+  const hooks = loadHooks(projectDir, path.join(projectDir, ".dsh"));
+  return { agents, commands, hooks };
+}

package/plugins/dsh-agent-extensions/lib/scaffold.js

@@ -0,0 +1,151 @@
+/**
+ * Zero-config scaffolding for dsh-desktop-kit.
+ *
+ * Global: `~/.dsh/mcp.json` (empty, valid).
+ * Project: `<project>/.dsh/` with agents/, commands/, hooks.json, verify.json,
+ * mcp.json, PROJECT.md and rules/project.md.
+ *
+ * Trust markers are deliberately NOT created: hooks and project MCP servers
+ * must remain an explicit user decision.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const SCAFFOLD_VERSION = 1;
+
+function writeIfMissing(file, content) {
+  if (fs.existsSync(file)) return false;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, content, "utf8");
+  return true;
+}
+
+export function ensureGlobalScaffold(home = process.env.DSH_HOME || path.join(os.homedir(), ".dsh")) {
+  const created = [];
+  const mcpFile = path.join(home, "mcp.json");
+  if (writeIfMissing(mcpFile, `${JSON.stringify({ mcpServers: {} }, null, 2)}\n`)) created.push(mcpFile);
+  const readme = path.join(home, "mcp.README.md");
+  if (
+    writeIfMissing(
+      readme,
+      [
+        "# MCP servers",
+        "",
+        "Add trusted servers to `mcp.json`:",
+        "",
+        "```json",
+        '{ "mcpServers": { "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }, "trusted": true } } }',
+        "```",
+        "",
+        "A server is started only with `trusted: true`. Project-level servers additionally require `.dsh/mcp.trusted` (`/mcp trust`).",
+        "",
+      ].join("\n"),
+    )
+  ) {
+    created.push(readme);
+  }
+  return { home, created };
+}
+
+function isKitRepo(cwd) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf8"));
+    return pkg?.name === "dsh-desktop-kit";
+  } catch {
+    return false;
+  }
+}
+
+export function shouldScaffold(cwd) {
+  if (typeof cwd !== "string" || cwd.length === 0) return false;
+  let resolved;
+  try { resolved = fs.realpathSync(cwd); } catch { return false; }
+  if (!fs.statSync(resolved).isDirectory()) return false;
+  const home = path.resolve(os.homedir());
+  const root = path.parse(resolved).root;
+  if (resolved === home || resolved === root) return false;
+  if (resolved.startsWith(path.join(home, ".dsh"))) return false;
+  if (isKitRepo(resolved)) return false;
+  return true;
+}
+
+export function ensureProjectScaffold(cwd) {
+  if (!shouldScaffold(cwd)) return { skipped: true, created: [] };
+  const dsh = path.join(cwd, ".dsh");
+  const created = [];
+  fs.mkdirSync(dsh, { recursive: true });
+  for (const directory of ["agents", "commands", "rules"]) {
+    const target = path.join(dsh, directory);
+    if (!fs.existsSync(target)) {
+      fs.mkdirSync(target, { recursive: true });
+      created.push(target);
+    }
+  }
+  if (writeIfMissing(path.join(dsh, "agents", ".gitkeep"), "")) created.push(path.join(dsh, "agents", ".gitkeep"));
+  if (writeIfMissing(path.join(dsh, "commands", ".gitkeep"), "")) created.push(path.join(dsh, "commands", ".gitkeep"));
+  if (writeIfMissing(path.join(dsh, "hooks.json"), `${JSON.stringify({ hooks: {} }, null, 2)}\n`)) created.push(path.join(dsh, "hooks.json"));
+  if (writeIfMissing(path.join(dsh, "verify.json"), `${JSON.stringify({ commands: [] }, null, 2)}\n`)) created.push(path.join(dsh, "verify.json"));
+  if (writeIfMissing(path.join(dsh, "mcp.json"), `${JSON.stringify({ mcpServers: {} }, null, 2)}\n`)) created.push(path.join(dsh, "mcp.json"));
+  if (
+    writeIfMissing(
+      path.join(dsh, ".gitignore"),
+      ["hooks.trusted", "mcp.trusted", "checkpoints/", ".kit-scaffold.json", ""].join("\n"),
+    )
+  ) {
+    created.push(path.join(dsh, ".gitignore"));
+  }
+  if (
+    writeIfMissing(
+      path.join(dsh, "README.md"),
+      [
+        "# .dsh",
+        "",
+        "Project-local DSH extensions, created automatically by dsh-desktop-kit.",
+        "",
+        "- `agents/*.md` — custom subagents (`project_agent`).",
+        "- `commands/*.md` — project commands (`/project <name>`).",
+        "- `hooks.json` — lifecycle hooks; run `/hooks trust` after review.",
+        "- `verify.json` — commands for `/verify`.",
+        "- `mcp.json` — project MCP servers; run `/mcp trust` after review.",
+        "- `PROJECT.md` — project context; `/init --force` regenerates it.",
+        "",
+      ].join("\n"),
+    )
+  ) {
+    created.push(path.join(dsh, "README.md"));
+  }
+  const projectFile = path.join(dsh, "PROJECT.md");
+  if (!fs.existsSync(projectFile)) {
+    let pkg = {};
+    try { pkg = JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf8")); } catch { /* optional */ }
+    fs.writeFileSync(
+      projectFile,
+      [
+        "# Project",
+        "",
+        `Root: ${cwd}`,
+        pkg.name ? `Package: ${pkg.name}${pkg.version ? ` ${pkg.version}` : ""}` : "",
+        pkg.scripts?.test ? `Tests: ${pkg.scripts.test}` : "",
+        "",
+        "Created automatically by dsh-desktop-kit. Edit freely; `/init --force` regenerates.",
+        "",
+      ]
+        .filter(Boolean)
+        .join("\n"),
+      "utf8",
+    );
+    created.push(projectFile);
+  }
+  const ruleFile = path.join(dsh, "rules", "project.md");
+  if (!fs.existsSync(ruleFile)) {
+    fs.writeFileSync(ruleFile, "---\nalways: true\n---\n# Правила проекта\n\n- Источник истины: `.dsh/PROJECT.md`.\n- Перед сдачей — тесты и проверка UI.\n", "utf8");
+    created.push(ruleFile);
+  }
+  const marker = path.join(dsh, ".kit-scaffold.json");
+  if (!fs.existsSync(marker)) {
+    fs.writeFileSync(marker, `${JSON.stringify({ version: SCAFFOLD_VERSION, createdAt: new Date().toISOString() }, null, 2)}\n`, "utf8");
+    created.push(marker);
+  }
+  return { skipped: false, created, dsh };
+}

package/plugins/dsh-agent-extensions/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "dsh-agent-extensions",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "main": "index.js",
+  "description": "Project-local hooks, custom agents, commands and safe checkpoints for DeepSeek Harness — Claude Code-like extensibility.",
+  "license": "MIT"
+}

package/plugins/dsh-browser-qa/README.md

@@ -0,0 +1,221 @@
+# dsh-browser-qa
+
+Headless-проверка вёрстки для DSH-агента: скриншоты и адаптивный аудит
+горизонтального переполнения и ошибок консоли через протокол Chrome DevTools.
+Без Playwright и без внешних зависимостей — только встроенные модули Node.js.
+
+## Зачем
+
+Агент может сам проверить страницу перед сдачей: «нет ли горизонтального
+скролла на 390/768/1440», «какие элементы вылезают», «что пишет консоль»,
+«как это выглядит». Работает и с локальными HTML-файлами, и с http(s)-страницами.
+
+## Требования
+
+- **Chrome или Chromium-браузер**. На Windows плагин ищет:
+  `CHROME_PATH` → `%ProgramFiles%\Google\Chrome\Application\chrome.exe` →
+  `%ProgramFiles(x86)%\...` → `%LOCALAPPDATA%\Google\Chrome\Application\chrome.exe` →
+  Chrome Canary → Edge (`msedge.exe`) как Chromium-запасной вариант.
+  Путь можно задать явно: `CHROME_PATH=C:\путь\chrome.exe` (переменная окружения
+  процесса DSH).
+- **Node 22+** — нужен встроенный `WebSocket` (в Node 24 он стабилен). DSH
+  Desktop на Electron 44 запускает Node 24, отдельная установка Node не нужна.
+  Если WebSocket недоступен, `browser_qa action=status` честно сообщит об этом.
+- Работает и на macOS/Linux (стандартные пути Chrome/Chromium), но основные
+  пути и проверки — под Windows.
+
+## Инструмент `browser_qa`
+
+Регистрируется один инструмент с тремя действиями. Параметры:
+
+| Параметр | Тип | По умолчанию | Назначение |
+|---|---|---|---|
+| `action` | `"shot"` \| `"audit"` \| `"status"` | — (обязателен) | Что сделать |
+| `url` | string | — | `http(s)`-адрес, `file://` или путь к локальному HTML (относительный — от cwd сессии) |
+| `width` | integer | `1440` | Ширина viewport для `shot`, CSS px (200..3840) |
+| `height` | integer | `900` | Высота viewport, CSS px (200..2160) |
+| `widths` | integer[] | `[390, 768, 1440]` | Ширины для `audit`, CSS px (до 6 значений) |
+| `outDir` | string | `<cwd>/.dsh/browser-qa` | Куда писать PNG; для `audit` — включает скриншоты |
+| `fullPage` | boolean | `false` | Снимать всю страницу, а не viewport (высота обрезается на 16384 px) |
+| `timeoutMs` | integer | `30000` | Таймаут загрузки страницы на одну ширину (3000..120000) |
+
+### `status`
+
+Находит браузер и возвращает путь, тип (Chrome/Edge), версию (через
+`/json/version`), версию Node и наличие WebSocket. Ничего не сохраняет.
+Пробный запуск Chrome занимает ~1–2 с и кэшируется на 5 минут.
+
+### `shot`
+
+Открывает страницу, выставляет viewport, сохраняет PNG и возвращает
+`output.path`, `output.width`, `output.height`, `output.bytes`, а также
+краткую сводку overflow и ошибок консоли. По умолчанию PNG кладётся в
+`<cwd>/.dsh/browser-qa/`.
+
+### `audit`
+
+Для каждой ширины из `widths` заново открывает страницу (так корректно
+срабатывают media queries и JS-перестройка), затем измеряет:
+
+- `document.documentElement.scrollWidth` против `clientWidth` (допуск 1 px) —
+  `horizontalOverflow.hasOverflow`, `overflowPx`;
+- элементы, чей `getBoundingClientRect().right` выходит за viewport
+  (`overflowingElements`: селектор, тег, id, классы, rect, насколько вылез,
+  текст); максимум 25 в отчёте, всего просмотрено до 5000 элементов;
+- ошибки консоли: `Runtime.consoleAPICalled` с `type=error/assert`,
+  `Runtime.exceptionThrown` и `Log.entryAdded` уровня `error` (включая
+  CSP-нарушения и сетевые ошибки); дедупликация, максимум 30;
+- **разметка и доступность** (`markup`): дубли `id`, `<img>` без `alt`,
+  поля без `label`/`aria-*`, ссылки и кнопки без доступного имени,
+  пропуски уровней заголовков, несколько `h1`, отсутствие `lang`/`title`/
+  `meta viewport`, положительный `tabindex`; до 60 issues на ширину;
+- дополнительно: viewport, title, финальный URL, `loadTimedOut`, время загрузки.
+
+Сводка: `summary.widthsChecked`, `widthsWithOverflow`, `overflowingElements`,
+`consoleErrors`, `markupIssues`, `widthsWithMarkupIssues`, `failedWidths`,
+`screenshots`.
+
+**Скриншоты в audit — опционально:** они сохраняются по одной штуке на ширину
+только если передан `outDir`. Без `outDir` audit работает быстрее и не пишет
+файлов. `fullPage` действует и на audit, и на shot.
+
+## UI gate
+
+Плагин также ставит жёсткий gate на хуках:
+
+- `fs/write-intent` / `fs/edit-intent` запоминают правки `.html`, `.css`,
+  `.scss`, `.jsx`, `.tsx`, `.vue`, `.svelte`, `.astro`, `.mdx`;
+- `tools/result` читает итог `browser_qa audit` (`overflow`, console, markup);
+- на `agent/turn-stopping` грязная сессия получает `agent.steer(...)`:
+  «запусти `browser_qa audit` на 390/768/1440, исправь overflow/console/markup
+  и проверь снова»;
+- ход закрывается только после **чистого** audit (0 overflow, 0 console,
+  0 markup) или после 4 напоминаний — предохранитель от бесконечного цикла.
+
+Это не запрет записи: агент может править, но не может молча завершить ход
+после UI-правки без проверки.
+
+## Примеры вызовов
+
+```json
+{ "action": "status" }
+```
+
+```json
+{ "action": "shot", "url": "C:\\project\\dist\\index.html", "width": 390, "height": 844 }
+```
+
+```json
+{
+  "action": "audit",
+  "url": "https://example.com/pricing",
+  "widths": [390, 768, 1440],
+  "outDir": "qa/browser",
+  "timeoutMs": 45000
+}
+```
+
+```json
+{ "action": "audit", "url": "C:\\project\\index.html", "widths": [390, 1440], "fullPage": true, "outDir": "qa/browser" }
+```
+
+## Куда сохраняются PNG
+
+- `shot` без `outDir`: `<cwd-сессии>/.dsh/browser-qa/`.
+- `audit` без `outDir`: ничего не сохраняется (только отчёт).
+- `audit` с `outDir` (или `shot` с `outDir`): указанный каталог, абсолютный или
+  относительно cwd сессии; создаётся при необходимости.
+- Имя файла: `<slug>-<ширина>x<высота>[-full]-<YYYYMMDD-HHmmss>-<hex>.png`,
+  например `localhost-390x844-20261109-205501-a1b2c3.png`. `slug` берётся из
+  хоста и пути URL или из имени локального файла.
+- Размеры PNG — ровно CSS-пиксели viewport (`deviceScaleFactor=1`), поэтому
+  390-px скриншот получается 390 px шириной (а не 500, как при
+  `chrome --screenshot` на Windows).
+
+## Ограничения
+
+- **CSP.** Плагин не обходит Content-Security-Policy страницы: если CSP
+  запрещает собственные inline-скрипты/шрифты/картинки сайта, в отчёте будут
+  соответствующие console errors. Сам замер выполняется через
+  `Runtime.evaluate` DevTools и CSP страницы не блокируется.
+- **Авторизация.** Профиль браузера временный, cookies нет. Приватные
+  страницы, за логином или с SSO, вернут редирект на страницу входа — это
+  ожидаемо. Для проверки таких страниц нужен публичный staging/preview URL.
+- **`file://`.** Локальные HTML открываются (флаг
+  `--allow-file-access-from-files` включён), но Chrome ограничивает часть
+  возможностей file-страниц: ES-модули и `fetch` к локальным файлам могут
+  блокироваться CORS, часть API недоступна. Относительные `src`/`href`
+  обычно работают — `file://`, `../../`, внешние CDN подключаются.
+- **SPA и асинхронность.** Плагин ждёт `load`, `document.readyState=complete`
+  и шрифты (`document.fonts.ready`, не дольше ~1.75 с), затем снимает замер.
+  Бесконечные таймеры, ленивые секции и контент, появляющийся через 5+ секунд
+  после load, могут не попасть в кадр — это не полноценный E2E-раннер.
+- **Интерактивность.** Нет кликов, скроллинга, ввода и навигации по шагам.
+  Только загрузка страницы и измерение.
+- **Псевдоэлементы, `transform`, `position: fixed`.** Overflow считается по
+  реальным DOM-элементам; `::before/::after` не перечисляются, а элементы
+  внутри контейнеров с `overflow-x != visible` (карусели, таблицы со скроллом)
+  считаются «содержимыми» и в список вылезающих не попадают.
+- **`fullPage`.** Ограничен 16384 px по высоте и ширине (лимит поверхности
+  Chrome); при превышении `output.clipped=true`. Full-page снимок включает и
+  горизонтально переполненную область, поэтому может быть шире viewport.
+- **Антибот/headless-детект.** Некоторые сайты (Cloudflare и т.п.) отдают
+  headless-браузеру заглушку или блокируют его — аудит покажет то, что увидел.
+- **Windows.** Определение путей и очистка процессов рассчитаны в первую
+  очередь на Windows; на Linux/macOS поддерживаются базовые пути, но тесты
+  прогонялись на Windows.
+
+## Безопасность и уборка
+
+- Каждый вызов запускает отдельный Chrome с временным `--user-data-dir` и
+  случайным `--remote-debugging-port=0`; порт слушает только `127.0.0.1` и
+  живёт внутри одного вызова.
+- Профиль пользователя не затрагивается; cookies, история и расширения из
+  обычного Chrome не используются.
+- После каждого вызова (включая ошибку и отмену) браузер убивается
+  (`taskkill /T /F` при необходимости), временный профиль удаляется с
+  ретраями; на случай аварийного завершения DSH есть `exit`-guard.
+- Внешних сетевых запросов, кроме самой проверяемой страницы, нет; телеметрии
+  нет.
+
+## Тесты
+
+```bash
+node tools/browser-qa-tests.mjs
+```
+
+- Чистые хелперы (всегда): параметры инструмента, viewport/widths/timeouts,
+  нормализация URL и путей, имена файлов, PNG-заголовок, shaping overflow- и
+  console-отчётов, summary и текст.
+- Реальный Chrome smoke (если Chrome/Edge найден; иначе SKIP):
+  временный HTML с намеренным overflow 1200 px и `console.error`; проверяются
+  overflow на 390/768, отсутствие overflow на 1440, найденный элемент
+  `#wide`, пойманная ошибка консоли, PNG на каждую ширину, точные размеры
+  `shot`, fullPage выше viewport, `status` с путём/версией, вызов через
+  зарегистрированный инструмент и отсутствие оставшихся временных профилей.
+
+## Устройство
+
+```
+plugins/dsh-browser-qa/
+  index.js          — регистрация инструмента browser_qa (inject: ["tools"])
+  lib/qa.js         — чистые хелперы: URL/viewport/widths, overflow-probe,
+                      console-события, отчёты, текст
+  lib/cdp.js        — минимальный CDP-клиент на встроенном WebSocket
+  lib/chrome.js     — поиск Chrome, запуск headless с temp-профилем,
+                      /json/version|list, очистка процессов и профиля
+  lib/pages.js      — shot/audit/status: навигация, viewport, скриншоты, сборка отчёта
+  cordis.patch.yml  — host-патч для standalone-установки bundle
+```
+
+## Диагностика
+
+- `Chrome/Edge not found` — установите Chrome или задайте `CHROME_PATH`
+  (полный путь к `chrome.exe`); `status` покажет список проверенных путей.
+- `has no built-in WebSocket` — Node в рантайме DSH старше 22; нужен Node 22+
+  (в актуальном DSH Desktop уже Node 24).
+- Таймауты на медленных страницах — увеличьте `timeoutMs` (до 120000).
+- `loadTimedOut: true` в отчёте означает, что `load` не успел за таймаут, но
+  замер всё равно сделан по текущему DOM.
+- Если временный профиль не удалился (`warnings` в ответе), повторите позже:
+  обычно антивирус/индексатор Windows держит файл не больше секунды.

package/plugins/dsh-browser-qa/cordis.patch.yml

@@ -0,0 +1,4 @@
+# Host half of the browser-QA plugin.
+- insert:
+    - id: dsh-browser-qa
+      name: dsh-browser-qa