dsh-desktop-kit 2.2.1 → 2.7.2

package/plugins/dsh-browser-qa/lib/ui-gate.js

@@ -0,0 +1,256 @@
+/**
+ * Hard UI gate for browser_qa.
+ *
+ * It observes UI file writes and browser_qa audit results. At
+ * `agent/turn-stopping` a dirty session gets a steer message instead of being
+ * allowed to close: the model must run audit until overflow, console errors
+ * and markup issues are zero. A bounded number of reminders prevents an
+ * accidental infinite turn.
+ */
+import crypto from "node:crypto";
+
+const UI_FILE = /\.(?:html?|xhtml|css|scss|sass|less|jsx|tsx|vue|svelte|astro|mdx)$/iu;
+const SKIP_PATH = /(?:^|[\\/])(?:node_modules|\.git|\.dsh|dist|build|coverage|qa)(?:[\\/]|$)/iu;
+const SHELL_WRITE = /(?:^|[\s"'=])(?:>|>>|Set-Content|Add-Content|Out-File|Copy-Item|Move-Item|cp|mv|sed\s+-i|perl\s+-pi|tee)\b/iu;
+const MAX_REMINDERS = 4;
+const MAX_PATHS = 12;
+
+function shellUiPath(command) {
+  const match = String(command).match(/(?:[A-Za-z]:[\\/]|\.{0,2}[\\/])?[^\s"'<>|;]+\.(?:html?|xhtml|css|scss|sass|less|jsx|tsx|vue|svelte|astro|mdx)/iu);
+  return match?.[0] ?? "";
+}
+
+function pathOf(target) {
+  const value = target?.displayPath ?? target?.path ?? target?.file ?? "";
+  return typeof value === "string" ? value : "";
+}
+
+function sessionIdOf(ctx, actor, agent) {
+  const direct = actor?.id ?? actor?.session?.id ?? agent?.id;
+  if (typeof direct === "string" && direct.length > 0) return direct;
+  try {
+    const current = ctx.get?.("agents")?.currentInitiator?.();
+    return typeof current?.id === "string" ? current.id : "";
+  } catch {
+    return "";
+  }
+}
+
+function findAudit(value, depth = 0) {
+  if (!value || typeof value !== "object" || depth > 4) return null;
+  if (value.summary && (Array.isArray(value.reports) || value.summary.widthsChecked !== undefined || value.summary.markupIssues !== undefined)) {
+    return value;
+  }
+  for (const key of ["value", "result", "data", "structuredContent", "output"]) {
+    const found = findAudit(value[key], depth + 1);
+    if (found) return found;
+  }
+  return null;
+}
+
+function resultText(result) {
+  if (typeof result?.text === "string") return result.text;
+  const content = result?.content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter((block) => block && block.type === "text" && typeof block.text === "string")
+    .map((block) => block.text)
+    .join("\n");
+}
+
+/** The normalized tool result is `{content:[{type:'text',text}]}`, so parse the audit summary. */
+function auditFromText(result) {
+  if (result?.isError === true) return null;
+  const text = resultText(result);
+  if (!text.includes("browser_qa audit:")) return null;
+  const summary = text.match(/Итог: overflow на (\d+) из (\d+)[^\n]*console errors: (\d+)[^\n]*markup: (\d+)/iu);
+  if (summary) {
+    return {
+      reports: [],
+      summary: {
+        widthsWithOverflow: Number(summary[1]),
+        widthsChecked: Number(summary[2]),
+        consoleErrors: Number(summary[3]),
+        markupIssues: Number(summary[4]),
+      },
+    };
+  }
+  const rows = [...text.matchAll(/- (\d+)px: overflow (?:нет|(\d+)px)[^\n]*console errors: (\d+)[^\n]*markup: (\d+)/giu)];
+  if (rows.length === 0) return null;
+  return {
+    reports: rows.map((row) => ({ width: Number(row[1]) })),
+    summary: {
+      widthsWithOverflow: rows.filter((row) => row[2] !== undefined).length,
+      widthsChecked: rows.length,
+      consoleErrors: rows.reduce((sum, row) => sum + Number(row[3]), 0),
+      markupIssues: rows.reduce((sum, row) => sum + Number(row[4]), 0),
+    },
+  };
+}
+
+function cleanAudit(summary) {
+  const checked = Number(summary?.widthsChecked ?? 1);
+  return (
+    checked > 0 &&
+    Number(summary?.widthsWithOverflow ?? 0) === 0 &&
+    Number(summary?.consoleErrors ?? 0) === 0 &&
+    Number(summary?.markupIssues ?? 0) === 0
+  );
+}
+
+function summaryText(summary) {
+  if (!summary) return "audit ещё не запускался";
+  return `audit: overflow ${summary.widthsWithOverflow ?? "?"} · console ${summary.consoleErrors ?? "?"} · markup ${summary.markupIssues ?? "?"}`;
+}
+
+export function createUiGate(ctx) {
+  const states = new Map();
+  const logger = ctx.logger;
+
+  function stateFor(sessionId) {
+    let state = states.get(sessionId);
+    if (!state) {
+      state = { dirty: false, lastEditAt: 0, auditAt: 0, clean: false, summary: null, paths: new Set(), reminders: 0 };
+      states.set(sessionId, state);
+      if (states.size > 200) states.delete(states.keys().next().value);
+    }
+    return state;
+  }
+
+  function markUi(target, actor) {
+    const file = pathOf(target);
+    if (!UI_FILE.test(file) || SKIP_PATH.test(file)) return;
+    const sessionId = sessionIdOf(ctx, actor);
+    if (!sessionId) return;
+    const state = stateFor(sessionId);
+    state.dirty = true;
+    state.lastEditAt = Date.now();
+    state.reminders = 0;
+    state.paths.add(file);
+    if (state.paths.size > MAX_PATHS) state.paths.delete(state.paths.values().next().value);
+  }
+
+  function onToolResult(exec, result) {
+    if (exec?.name !== "browser_qa") return;
+    const action = exec?.arguments?.action ?? exec?.args?.action ?? exec?.input?.action;
+    if (action !== "audit") return;
+    const payload = findAudit(result) ?? auditFromText(result);
+    if (!payload) return;
+    const sessionId = sessionIdOf(ctx, exec?.agent, exec?.agent);
+    if (!sessionId) return;
+    const state = stateFor(sessionId);
+    state.auditAt = Date.now();
+    state.clean = cleanAudit(payload.summary);
+    state.summary = payload.summary ?? null;
+    if (state.clean && state.lastEditAt <= state.auditAt) {
+      state.dirty = false;
+      state.reminders = 0;
+      state.paths.clear();
+    } else {
+      state.reminders = 0;
+    }
+    logger?.debug?.(`[ui-gate] ${sessionId}: ${summaryText(payload.summary)}`);
+  }
+
+  async function turnStopping(payload) {
+    const agent = payload?.agent;
+    const sessionId = sessionIdOf(ctx, agent, agent);
+    if (!sessionId) return;
+    const state = states.get(sessionId);
+    if (!state?.dirty) return;
+    if (state.reminders >= MAX_REMINDERS) {
+      logger?.warn?.(`[ui-gate] ${sessionId}: ${MAX_REMINDERS} reminders without a clean audit; allowing the turn to close`);
+      state.dirty = false;
+      return;
+    }
+    state.reminders += 1;
+    const files = [...state.paths].slice(0, 6).join(", ") || "UI-файлы";
+    const text = [
+      "<ui-gate>",
+      `Изменены UI-файлы: ${files}.`,
+      `Последний ${summaryText(state.summary)}.`,
+      "Ход не закрыт: запусти browser_qa action=audit для этой страницы/файла на 390/768/1440 (лучше с outDir), исправь overflow, console errors и markup (alt, label, duplicate id, heading order).",
+      "После исправлений снова запусти audit. Не заявляй «готово», пока audit не станет чистым.",
+      "</ui-gate>",
+    ].join("\n");
+    try {
+      agent.steer({
+        id: crypto.randomUUID(),
+        role: "user",
+        content: [{ type: "text", text }],
+        source: { kind: "user" },
+      });
+      logger?.info?.(`[ui-gate] ${sessionId}: steered for ${summaryText(state.summary)}`);
+    } catch (error) {
+      logger?.warn?.(`[ui-gate] ${sessionId}: steer failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  const disposers = [];
+  if (typeof ctx.on === "function") {
+    for (const event of ["fs/write-intent", "fs/edit-intent"]) {
+      try {
+        const dispose = ctx.on(event, async (target, actor, next) => {
+          const decision = typeof next === "function" ? await next() : undefined;
+          markUi(target, actor);
+          return decision;
+        });
+        if (typeof dispose === "function") disposers.push(dispose);
+      } catch (error) {
+        logger?.warn?.(`[ui-gate] ${event} hook skipped: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+    try {
+      const dispose = ctx.on("tools/result", (exec, result) => onToolResult(exec, result));
+      if (typeof dispose === "function") disposers.push(dispose);
+    } catch (error) {
+      logger?.warn?.(`[ui-gate] tools/result hook skipped: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    try {
+      const dispose = ctx.on("tools/pre-execute", async (exec, next) => {
+        const decision = typeof next === "function" ? await next() : { kind: "allow" };
+        const command = exec?.arguments?.command;
+        if (
+          decision?.kind === "allow" &&
+          (exec?.name === "pwsh" || exec?.name === "bash" || exec?.name === "shell") &&
+          typeof command === "string" &&
+          SHELL_WRITE.test(command)
+        ) {
+          const file = shellUiPath(command);
+          if (file) markUi({ displayPath: file }, exec.agent);
+        }
+        return decision;
+      });
+      if (typeof dispose === "function") disposers.push(dispose);
+    } catch (error) {
+      logger?.warn?.(`[ui-gate] tools/pre-execute hook skipped: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    try {
+      const dispose = ctx.on("agent/turn-stopping", (payload) => turnStopping(payload));
+      if (typeof dispose === "function") disposers.push(dispose);
+    } catch (error) {
+      logger?.warn?.(`[ui-gate] turn-stopping hook skipped: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    try {
+      const dispose = ctx.on("agent/disposed", (payload) => {
+        const id = sessionIdOf(ctx, payload?.agent, payload?.agent);
+        if (id) states.delete(id);
+      });
+      if (typeof dispose === "function") disposers.push(dispose);
+    } catch {
+      /* optional */
+    }
+  }
+
+  return {
+    markUi,
+    onToolResult,
+    turnStopping,
+    dispose() {
+      for (const dispose of disposers) {
+        try { dispose(); } catch { /* best effort */ }
+      }
+      states.clear();
+    },
+  };
+}

package/plugins/dsh-browser-qa/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "dsh-browser-qa",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Headless-Chrome visual QA for DSH agents: screenshots and responsive horizontal-overflow/console-error audits through the DevTools protocol, with no Playwright dependency.",
+  "license": "MIT",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./lib": "./lib/qa.js",
+    "./lib/chrome": "./lib/chrome.js",
+    "./lib/pages": "./lib/pages.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "lib/**",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dsh": {
+    "manifestVersion": 1,
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  }
+}

package/plugins/dsh-checkpoints/README.md

@@ -0,0 +1,22 @@
+# dsh-checkpoints
+
+Безопасные снимки workspace на git-объектах.
+
+## Инструмент `checkpoint`
+
+- `action: "create"` — снимок текущего дерева (включая untracked) в
+  `refs/dsh-checkpoints/<id>`; HEAD не двигается, индекс не меняется;
+- `action: "list"` — список снимков;
+- `action: "restore"` — вернуть файлы из снимка; перед откатом автоматически
+  создаётся страховочный снимок;
+- `action: "delete"` — удалить ref и метаданные.
+
+Метаданные — `~/.dsh/checkpoints/<repo-hash>/<id>.json`, права `0700/0600`.
+
+## Важно
+
+- Откат **не удаляет** файлы, появившиеся после снимка; он восстанавливает
+  файлы, которые были в снимке. Такой откат не стирает новую работу.
+- Снимок — полноценный git-tree: в него попадают все файлы, включая `.env`.
+  Это локальный приватный объект; не отправляйте его в публичный репозиторий.
+- Нужен git-репозиторий; при отсутствии HEAD снимок создаётся без родителя.

package/plugins/dsh-checkpoints/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: dsh-checkpoints
+      name: dsh-checkpoints

package/plugins/dsh-checkpoints/index.js

@@ -0,0 +1,80 @@
+/**
+ * dsh-checkpoints — safe workspace snapshots via git objects.
+ */
+import path from "node:path";
+
+import { createCheckpoint, deleteCheckpoint, listCheckpoints, restoreCheckpoint } from "./lib/checkpoints.js";
+
+export const inject = ["tools"];
+
+function rootOf(args, exec) {
+  const explicit = typeof args?.root === "string" ? args.root.trim() : "";
+  const cwd = exec?.agent?.session?.header?.cwd;
+  return path.resolve(explicit || cwd || process.cwd());
+}
+
+function home() {
+  return process.env.DSH_HOME || path.join(process.env.USERPROFILE || process.env.HOME || "", ".dsh");
+}
+
+function truncate(text, max = 20_000) {
+  return text.length <= max ? text : `${text.slice(0, max)}\n…`;
+}
+
+export function apply(ctx) {
+  ctx.tools.register({
+    name: "checkpoint",
+    description:
+      "Create, list, restore or delete a safe git-backed workspace checkpoint. Use create before risky edits and restore to roll back. Snapshots are local objects under refs/dsh-checkpoints; restore never deletes files created after the snapshot.",
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        action: { type: "string", enum: ["create", "list", "restore", "delete"], description: "create | list | restore | delete" },
+        label: { type: "string", description: "Human label for create." },
+        id: { type: "string", description: "Checkpoint id (or prefix) for restore/delete." },
+        root: { type: "string", description: "Project root; defaults to Session cwd." },
+      },
+      required: ["action"],
+    },
+    timeoutMs: 30_000,
+    output: {
+      schema: { type: "object", additionalProperties: true },
+      render(_args, value) {
+        const text = typeof value?.text === "string" ? value.text : JSON.stringify(value);
+        return [{ type: "text", text: truncate(text) }];
+      },
+    },
+    async execute(args, exec) {
+      const cwd = rootOf(args, exec);
+      const action = String(args?.action ?? "list");
+      if (action === "create") {
+        const meta = createCheckpoint({ cwd, label: args?.label, home: home() });
+        return { ok: true, checkpoint: meta, text: `Создан checkpoint ${meta.id} · файлов ${meta.files}${meta.label ? ` · ${meta.label}` : ""}` };
+      }
+      if (action === "restore") {
+        if (typeof args?.id !== "string" || args.id.trim().length === 0) return { ok: false, text: "checkpoint restore: нужен id" };
+        const result = restoreCheckpoint({ cwd, id: args.id.trim(), home: home() });
+        return {
+          ok: true,
+          ...result,
+          text: `Восстановлен ${result.restored.id} (${result.restored.label || "без метки"}). Перед откатом создан ${result.safety?.id ?? "—"}.`,
+        };
+      }
+      if (action === "delete") {
+        if (typeof args?.id !== "string" || args.id.trim().length === 0) return { ok: false, text: "checkpoint delete: нужен id" };
+        const meta = deleteCheckpoint({ cwd, id: args.id.trim(), home: home() });
+        return { ok: true, checkpoint: meta, text: `Удалён checkpoint ${meta.id}` };
+      }
+      const list = listCheckpoints({ cwd, home: home() });
+      return {
+        ok: true,
+        checkpoints: list,
+        text: list.length === 0
+          ? "Checkpoints нет. Создать: checkpoint action=create label=... "
+          : ["Checkpoints:", ...list.map((item) => `- ${item.id} · ${item.createdAt} · ${item.files} файлов${item.label ? ` · ${item.label}` : ""}`)].join("\n"),
+      };
+    },
+  });
+  ctx.logger?.info?.("[checkpoints] tool ready");
+}

package/plugins/dsh-checkpoints/lib/checkpoints.js

@@ -0,0 +1,111 @@
+/**
+ * Git-backed workspace checkpoints.
+ *
+ * A checkpoint is an unreachable commit stored under refs/dsh-checkpoints/<id>.
+ * It captures tracked + untracked files (a full tree) without moving HEAD.
+ * Restore checks out that tree into the worktree; it never deletes files that
+ * were created after the checkpoint, which keeps the action non-destructive.
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+function git(cwd, args, { allowFail = false } = {}) {
+  const result = spawnSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    timeout: 20_000,
+    windowsHide: true,
+  });
+  if (result.error) throw new Error(`git ${args[0]}: ${result.error.message}`);
+  if (result.status !== 0 && !allowFail) {
+    throw new Error(`git ${args.join(" ")}: ${(result.stderr || result.stdout || "").trim()}`);
+  }
+  return { ok: result.status === 0, status: result.status, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
+}
+
+export function repoRoot(cwd) {
+  const result = git(cwd, ["rev-parse", "--show-toplevel"]);
+  return result.stdout.trim();
+}
+
+function checkpointHome(home, root) {
+  const digest = crypto.createHash("sha256").update(root.toLowerCase()).digest("hex").slice(0, 16);
+  return path.join(home, "checkpoints", digest);
+}
+
+export function createCheckpoint({ cwd, label = "", home = path.join(os.homedir(), ".dsh") }) {
+  const root = repoRoot(cwd);
+  const id = `cp-${new Date().toISOString().replace(/[-:T.Z]/gu, "").slice(0, 14)}-${crypto.randomBytes(3).toString("hex")}`;
+  const hasHead = git(root, ["rev-parse", "--verify", "HEAD"], { allowFail: true }).ok;
+  git(root, ["add", "-A"]);
+  const tree = git(root, ["write-tree"]).stdout.trim();
+  const message = `dsh checkpoint ${id}${label ? `: ${label}` : ""}`;
+  const commitArgs = ["commit-tree", tree];
+  if (hasHead) commitArgs.push("-p", "HEAD");
+  commitArgs.push("-m", message);
+  const commit = git(root, commitArgs).stdout.trim();
+  git(root, ["update-ref", `refs/dsh-checkpoints/${id}`, commit]);
+  if (hasHead) {
+    git(root, ["reset"], { allowFail: true });
+  } else {
+    git(root, ["read-tree", "--empty"], { allowFail: true });
+  }
+  const meta = {
+    id,
+    label: String(label ?? ""),
+    createdAt: new Date().toISOString(),
+    repo: root,
+    ref: `refs/dsh-checkpoints/${id}`,
+    commit,
+    tree,
+    files: git(root, ["ls-tree", "-r", "--name-only", commit]).stdout.trim().split(/\r?\n/u).filter(Boolean).length,
+  };
+  const directory = checkpointHome(home, root);
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  fs.writeFileSync(path.join(directory, `${id}.json`), `${JSON.stringify(meta, null, 2)}\n`, { mode: 0o600 });
+  return meta;
+}
+
+export function listCheckpoints({ cwd, home = path.join(os.homedir(), ".dsh") }) {
+  const root = repoRoot(cwd);
+  const directory = checkpointHome(home, root);
+  if (!fs.existsSync(directory)) return [];
+  return fs
+    .readdirSync(directory)
+    .filter((name) => name.endsWith(".json"))
+    .map((name) => {
+      try {
+        return JSON.parse(fs.readFileSync(path.join(directory, name), "utf8"));
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean)
+    .sort((left, right) => right.createdAt.localeCompare(left.createdAt));
+}
+
+export function restoreCheckpoint({ cwd, id, home = path.join(os.homedir(), ".dsh"), safety = true }) {
+  const root = repoRoot(cwd);
+  const list = listCheckpoints({ cwd, home });
+  const meta = list.find((item) => item.id === id || item.id.startsWith(id));
+  if (!meta) throw new Error(`checkpoint не найден: ${id}`);
+  const exists = git(root, ["rev-parse", "--verify", `${meta.ref}^{commit}`], { allowFail: true });
+  if (!exists.ok) throw new Error(`git-ref ${meta.ref} потерян`);
+  const before = safety ? createCheckpoint({ cwd, home, label: `before restore ${meta.id}` }) : null;
+  git(root, ["checkout", meta.commit, "--", "."], { allowFail: false });
+  return { restored: meta, safety: before };
+}
+
+export function deleteCheckpoint({ cwd, id, home = path.join(os.homedir(), ".dsh") }) {
+  const root = repoRoot(cwd);
+  const list = listCheckpoints({ cwd, home });
+  const meta = list.find((item) => item.id === id || item.id.startsWith(id));
+  if (!meta) throw new Error(`checkpoint не найден: ${id}`);
+  git(root, ["update-ref", "-d", meta.ref], { allowFail: true });
+  const file = path.join(checkpointHome(home, root), `${meta.id}.json`);
+  fs.rmSync(file, { force: true });
+  return meta;
+}

package/plugins/dsh-checkpoints/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "dsh-checkpoints",
+  "version": "1.0.0",
+  "description": "Safe git-backed workspace checkpoints for DSH coding agents: create a snapshot before risky edits, list and restore it without losing unrelated work.",
+  "license": "MIT",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./lib": "./lib/checkpoints.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "lib/**",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "dsh": {
+    "manifestVersion": 1,
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  }
+}

package/plugins/dsh-github-review/README.md

@@ -0,0 +1,131 @@
+# dsh-github-review
+
+Ревью GitHub pull request'ов одним инструментом `github_review` поверх официального
+`gh` CLI — без копирования diff в чат руками и без read-only «угадывания» состояния PR.
+
+## Зачем
+
+Модель часто спрашивают «что в PR / почему CI красный / что просили в ревью».
+Инструмент отдаёт это компактно и с жёсткими лимитами:
+
+- `status` — установлен ли `gh`, авторизован ли он, какой репозиторий и ветка видны из cwd;
+- `pr` — заголовок, автор, base/head, body, файлы, additions/deletions, коммиты;
+- `checks` — CI-проверки и отдельный список проваленных;
+- `comments` — review-треды (inline) и обсуждение PR;
+- `diff` — diff PR с байтовым лимитом.
+
+По умолчанию инструмент **read-only**. Единственная мутация — `comment`, и она
+выполняется только при явном подтверждении. Merge, close, reopen, force-push **не
+реализованы** и отклоняются отдельным сообщением.
+
+## Требования
+
+- [GitHub CLI](https://cli.github.com) `gh` **2.x** в `PATH` (проверено на 2.96.0; если
+  `gh pr checks` в вашей версии не поддерживает `--json`, плагин сам переключается
+  на разбор текстовой таблицы);
+- авторизация:
+
+  ```bash
+  gh auth login
+  ```
+
+  достаточно scope `repo` (для чтения приватных репозиториев) и прав на чтение Actions;
+- git-репозиторий с remote `origin` на GitHub (или явный `repo=owner/name`);
+- сеть для всех действий, кроме `status` (там только локальные `gh --version`,
+  `gh auth status` и `git remote get-url`).
+
+## Инструмент `github_review`
+
+| action | что делает | параметры |
+| --- | --- | --- |
+| `status` | `gh --version`, `gh auth status`, определение репозитория/ветки из cwd | `cwd`, `repo` |
+| `pr` | текущий PR (или по номеру): title, author, base/head, body, files, +/−, commits | `pr`, `repo`, `cwd` |
+| `checks` | CI checks + сводка по fail/pending/skipping/cancel | `pr`, `repo`, `cwd` |
+| `comments` | review threads, conversation, состояния review (approved / changes requested) | `pr`, `repo`, `cwd` |
+| `diff` | `gh pr diff` с байтовым лимитом | `pr`, `repo`, `cwd`, `maxBytes` |
+| `comment` | отправить один комментарий в PR | `confirm: true`, `pr`, `body`, `repo`, `cwd` |
+
+`pr` по умолчанию — PR текущей ветки. Если PR не найден, инструмент вернёт
+подсказку «укажите номер», а не ошибку gh.
+
+### Примеры
+
+```
+github_review action=status
+github_review action=pr
+github_review action=pr pr=42
+github_review action=checks pr=42
+github_review action=comments pr=42
+github_review action=diff pr=42 maxBytes=65536
+github_review action=comment pr=42 confirm=true body="Проверил таймауты — ок, но нужен тест на обрыв."
+```
+
+Ответ `diff` содержит `patch` (не больше `maxBytes`, по умолчанию 200 КиБ) и
+заголовок с реальным размером; в чат рендерится не больше 48k символов.
+
+## Безопасность
+
+- **argv, не shell.** Все вызовы `gh`/`git` — массив аргументов через
+  `spawn`/`spawnSync` с `shell: false`. Номер PR, `repo`, `body` и cwd не могут
+  стать shell-синтаксисом.
+- **Строгая валидация.** `repo` принимается только как `owner/name` (или
+  `host/owner/name` для GHES) по регулярному выражению; `pr` — только целое
+  положительное число. Некорректные значения отклоняются до запуска процесса.
+- **Комментарий — только с подтверждением.** `comment` требует одновременно
+  `confirm: true` (строго boolean), явный номер PR и непустой `body`. Без этого —
+  отказ, никаких сетевых вызовов. `body` передаётся через stdin
+  (`gh pr comment --body-file -`), а не аргументом командной строки.
+- **Таймауты.** Каждый вызов ограничен по времени (10–45 с) и по буферу вывода;
+  diff читается потоком и останавливается по достижении лимита.
+- **Секреты.** Плагин не читает token-файлы и не печатает значения `GH_TOKEN`/
+  `GITHUB_TOKEN`; вывод gh и текст ошибок очищаются от токенов/ключей/JWT/
+  `Authorization`/cookie/учётных данных в URL. Diff и body — это содержимое PR:
+  если в PR есть секрет, он попадёт в diff как есть. Поэтому не публикуйте diff
+  PR с секретами в незащищённые каналы и не коммитьте `.env`.
+- **Никаких лишних мутаций.** Нет merge/close/reopen/force-push/approve — эти
+  действия возвращают `unsupported-action`.
+
+## Лимиты
+
+| Что | Лимит |
+| --- | --- |
+| body PR | 16 000 символов |
+| файлов в `pr` | 60 (остальные — счётчиком) |
+| коммитов в `pr` | 40 |
+| checks | 200 |
+| conversation | 40 |
+| inline-тредов | 40, комментариев в `comments` — 100 |
+| комментарий в PR | 60 000 символов |
+| diff | по умолчанию 200 КиБ, диапазон 4 КиБ … 2 МиБ (`maxBytes`) |
+| рендер в чат | 24k символов (48k для `diff`) |
+
+## Ограничения
+
+- Только GitHub (github.com и GHES через `gh`); GitLab/Bitbucket не поддерживаются.
+- Inline-комментарии берутся из REST API: состояние `resolved`/`outdated` и полная
+  пагинация тредов недоступны — плагин честно помечает это в ответе.
+- `checks` на старых `gh` разбирает текстовую таблицу; форматирование таблицы
+  может отличаться между версиями.
+- Текущая ветка без `pr=` должна иметь локальную git-ветку и remote; для PR из
+  форка надёжнее передать номер.
+- Нет создания PR, ревью-аппрувов, назначения ревьюеров, редактирования PR.
+- Сеть и права токена — ответственность пользователя: при отсутствии прав
+  инструмент вернёт сообщение об ошибке gh, а не попытается обойти её.
+
+## Тесты
+
+```bash
+node tools/github-review-tests.mjs
+```
+
+Тесты герметичны: разбор PR/checks/comments/auth на фикстурах, проверка
+редакции секретов, байтовых лимитов, безопасной передачи argv, регистрации
+инструмента и отказа мутациям. Live-блок только проверяет локальную установку
+`gh` (`--version`, `auth status`, git remote) и пропускается, если `gh` нет.
+
+## Интеграция в набор
+
+Плагин — стандартный host-плагин набора: `package.json` с `dsh.bundle.patch`,
+`cordis.patch.yml` с insert-строкой и `export const inject = ["tools"]` в
+`index.js`. Набор подключает его как дочерний плагин (`plugins/dsh-github-review/index.js`),
+инструмент становится доступен модели как `github_review`.

package/plugins/dsh-github-review/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: dsh-github-review
+      name: dsh-github-review