dsh-desktop-kit 2.2.1 → 2.7.2

package/plugins/dsh-browser-qa/index.js

@@ -0,0 +1,165 @@
+/**
+ * dsh-browser-qa — headless-Chrome quality checks for DSH agents.
+ *
+ * One tool, three actions:
+ *   status — detect Chrome/Edge and report its path/version;
+ *   shot   — open a URL or local HTML file, set a viewport, save a PNG;
+ *   audit  — at responsive widths measure horizontal overflow, list the
+ *            overflowing elements and console errors, optionally save PNGs.
+ *
+ * Everything is Node-built-ins only: the DevTools protocol is spoken over the
+ * WebSocket client built into Node 22+/24, so there is no Playwright dependency.
+ */
+import { auditPages, captureShot, statusReport } from "./lib/pages.js";
+import { createUiGate } from "./lib/ui-gate.js";
+import { errorMessage, normalizeViewport, parseTimeout, parseWidths } from "./lib/qa.js";
+
+export const inject = ["tools"];
+
+const TOOL_NAME = "browser_qa";
+const TOOL_TIMEOUT_MS = 240_000;
+const MAX_RENDER_CHARS = 24_000;
+
+function sessionCwd(exec) {
+  const cwd = exec?.agent?.session?.header?.cwd;
+  return typeof cwd === "string" && cwd.length > 0 ? cwd : process.cwd();
+}
+
+function sessionSignal(exec) {
+  const signal = exec?.signal ?? exec?.abortSignal;
+  return signal && typeof signal.addEventListener === "function" ? signal : undefined;
+}
+
+function failure(prefix, error) {
+  const message = errorMessage(error);
+  const result = { ok: false, error: message, text: message.startsWith(prefix) ? message : `${prefix}: ${message}` };
+  if (error && typeof error.code === "string") result.code = error.code;
+  if (error && Array.isArray(error.candidates)) result.candidates = error.candidates;
+  return result;
+}
+
+function missingUrl(action) {
+  return {
+    ok: false,
+    error: "url is required",
+    text: `browser_qa ${action}: нужен параметр url — http(s)-адрес, file:// или путь к локальному HTML-файлу`,
+  };
+}
+
+function makeToolDefinition() {
+  return {
+    name: TOOL_NAME,
+    description:
+      "Headless-Chrome quality checks without Playwright. status: detect Chrome and its version. shot: open an http(s) URL or local HTML file, set the viewport, save a PNG and return its path/size. audit: load the page at responsive widths (default 390/768/1440) and report horizontal overflow (documentElement.scrollWidth vs clientWidth), the overflowing elements, console errors, markup/accessibility issues (missing alt, unlabeled fields, nameless links/buttons, duplicate ids, heading order, lang/title/viewport, positive tabindex), and optionally one PNG per width (pass outDir). Uses the Chrome DevTools protocol over a temporary profile; no external network calls beyond the page itself.",
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        action: {
+          type: "string",
+          enum: ["shot", "audit", "status"],
+          description: "shot: one viewport PNG | audit: overflow/console report at responsive widths | status: Chrome path/version",
+        },
+        url: {
+          type: "string",
+          description: "http(s) URL, file:// URL or local HTML file path (relative paths resolve from the Session cwd).",
+        },
+        width: { type: "integer", description: "Viewport width for shot, in CSS px (default 1440, range 200..3840)." },
+        height: { type: "integer", description: "Viewport height, in CSS px (default 900, range 200..2160)." },
+        widths: {
+          type: "array",
+          items: { type: "integer" },
+          description: "Audit widths in CSS px (default [390, 768, 1440], at most 6 values).",
+        },
+        outDir: {
+          type: "string",
+          description:
+            "Directory for PNGs. shot default: <cwd>/.dsh/browser-qa. audit saves one PNG per width only when outDir is given.",
+        },
+        fullPage: { type: "boolean", description: "Capture the full page instead of the viewport (height capped at 16384 px)." },
+        timeoutMs: { type: "integer", description: "Page load timeout per width in ms (default 30000, range 3000..120000)." },
+      },
+      required: ["action"],
+    },
+    timeoutMs: TOOL_TIMEOUT_MS,
+    output: {
+      schema: { type: "object", additionalProperties: true },
+      render(_args, value) {
+        const text =
+          value !== null && typeof value === "object" && typeof value.text === "string"
+            ? value.text
+            : JSON.stringify(value);
+        return [{ type: "text", text: text.length <= MAX_RENDER_CHARS ? text : `${text.slice(0, MAX_RENDER_CHARS)}\n…` }];
+      },
+    },
+    async execute(args, exec) {
+      const action = String(args?.action ?? "").trim().toLowerCase();
+      const cwd = sessionCwd(exec);
+      const signal = sessionSignal(exec);
+      try {
+        if (action === "status") {
+          const status = await statusReport({ cwd });
+          if (status.ok !== true) {
+            status.error = status.chrome?.probeError ?? "Chrome is not available";
+          }
+          return status;
+        }
+        if (action === "shot") {
+          if (typeof args?.url !== "string" || args.url.trim().length === 0) return missingUrl("shot");
+          const viewport = normalizeViewport(args);
+          return await captureShot({
+            target: args.url,
+            width: viewport.width,
+            height: viewport.height,
+            fullPage: args?.fullPage === true,
+            outDir: args?.outDir,
+            timeoutMs: parseTimeout(args?.timeoutMs),
+            cwd,
+            signal,
+          });
+        }
+        if (action === "audit") {
+          if (typeof args?.url !== "string" || args.url.trim().length === 0) return missingUrl("audit");
+          const widths = parseWidths(args?.widths);
+          const viewport = normalizeViewport(args);
+          const hasOutDir = typeof args?.outDir === "string" && args.outDir.trim().length > 0;
+          return await auditPages({
+            target: args.url,
+            widths,
+            height: viewport.height,
+            fullPage: args?.fullPage === true,
+            outDir: hasOutDir ? args.outDir : null,
+            screenshots: hasOutDir,
+            timeoutMs: parseTimeout(args?.timeoutMs),
+            cwd,
+            signal,
+          });
+        }
+        return {
+          ok: false,
+          error: `unknown action: ${action || "(empty)"}`,
+          text: `browser_qa: неизвестное действие «${action || "(пусто)"}». Доступно: shot, audit, status.`,
+        };
+      } catch (error) {
+        return failure("browser_qa", error);
+      }
+    },
+  };
+}
+
+export function apply(ctx) {
+  const tool = makeToolDefinition();
+  const register = () => ctx.tools.register(tool);
+  if (typeof ctx.effect === "function") {
+    ctx.effect(register, "dsh-browser-qa: tool");
+  } else {
+    register();
+  }
+  try {
+    const gate = createUiGate(ctx);
+    if (typeof ctx.effect === "function") ctx.effect(() => () => gate.dispose(), "dsh-browser-qa: ui gate");
+  } catch (error) {
+    ctx.logger?.warn?.(`[browser-qa] ui gate skipped: ${errorMessage(error)}`);
+  }
+  ctx.logger?.info?.("[browser-qa] tool ready");
+}

package/plugins/dsh-browser-qa/lib/cdp.js

@@ -0,0 +1,224 @@
+/**
+ * Minimal Chrome DevTools Protocol client.
+ *
+ * Uses the WebSocket client built into Node.js (22+/24) so the plugin has no
+ * npm dependencies. Only request/response plus named events are implemented —
+ * enough for Page, Runtime, Log and Emulation domains used by browser_qa.
+ */
+export class Cdp {
+  constructor(webSocketUrl, options = {}) {
+    if (typeof webSocketUrl !== "string" || webSocketUrl.length === 0) {
+      throw new Error("CDP websocket URL is empty");
+    }
+    if (typeof WebSocket !== "function") {
+      throw new Error("This Node.js runtime has no built-in WebSocket (Node 22+ is required)");
+    }
+    this.webSocketUrl = webSocketUrl;
+    this.ws = null;
+    this.nextId = 0;
+    this.pending = new Map();
+    this.listeners = new Map();
+    this.closeWaiters = new Set();
+    this.closed = false;
+    this.sendTimeoutMs = options.sendTimeoutMs ?? 15_000;
+  }
+
+  async connect(timeoutMs = 10_000) {
+    const ws = new WebSocket(this.webSocketUrl);
+    this.ws = ws;
+    try {
+      await new Promise((resolve, reject) => {
+        let settled = false;
+        const timer = setTimeout(() => {
+          if (settled) return;
+          settled = true;
+          cleanup();
+          reject(new Error("CDP websocket connect timeout"));
+        }, timeoutMs);
+        if (typeof timer.unref === "function") timer.unref();
+        const cleanup = () => {
+          clearTimeout(timer);
+          ws.removeEventListener("open", onOpen);
+          ws.removeEventListener("error", onError);
+          ws.removeEventListener("close", onClose);
+        };
+        const onOpen = () => {
+          if (settled) return;
+          settled = true;
+          cleanup();
+          resolve();
+        };
+        const onError = () => {
+          if (settled) return;
+          settled = true;
+          cleanup();
+          reject(new Error("CDP websocket connection error"));
+        };
+        const onClose = () => {
+          if (settled) return;
+          settled = true;
+          cleanup();
+          reject(new Error("CDP websocket closed before it opened"));
+        };
+        ws.addEventListener("open", onOpen);
+        ws.addEventListener("error", onError);
+        ws.addEventListener("close", onClose);
+      });
+    } catch (error) {
+      try {
+        ws.close();
+      } catch {
+        /* already closed */
+      }
+      this.ws = null;
+      this.closed = true;
+      throw error;
+    }
+    this.closed = false;
+    ws.addEventListener("message", (event) => this.handleMessage(event.data));
+    ws.addEventListener("close", () => this.handleClose());
+    ws.addEventListener("error", () => {
+      /* a close event follows; pending calls will be rejected there */
+    });
+    return this;
+  }
+
+  isClosed() {
+    return this.closed || this.ws === null;
+  }
+
+  handleMessage(raw) {
+    let text;
+    if (typeof raw === "string") text = raw;
+    else if (raw instanceof ArrayBuffer) text = Buffer.from(raw).toString("utf8");
+    else if (ArrayBuffer.isView(raw)) text = Buffer.from(raw.buffer, raw.byteOffset, raw.byteLength).toString("utf8");
+    else text = String(raw ?? "");
+    let message;
+    try {
+      message = JSON.parse(text);
+    } catch {
+      return;
+    }
+    if (message === null || typeof message !== "object") return;
+    if (message.id !== undefined) {
+      const pending = this.pending.get(message.id);
+      if (pending === undefined) return;
+      this.pending.delete(message.id);
+      clearTimeout(pending.timer);
+      if (message.error) pending.reject(new Error(message.error.message || "CDP request failed"));
+      else pending.resolve(message.result);
+      return;
+    }
+    if (typeof message.method !== "string") return;
+    const listeners = this.listeners.get(message.method);
+    if (!listeners || listeners.size === 0) return;
+    for (const listener of [...listeners]) {
+      try {
+        listener(message.params ?? {});
+      } catch {
+        /* a listener must never break the protocol loop */
+      }
+    }
+  }
+
+  handleClose() {
+    if (this.closed) return;
+    this.closed = true;
+    this.ws = null;
+    const error = new Error("CDP connection closed");
+    for (const pending of this.pending.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(error);
+    }
+    this.pending.clear();
+    for (const fail of [...this.closeWaiters]) {
+      try {
+        fail(error);
+      } catch {
+        /* ignore */
+      }
+    }
+    this.closeWaiters.clear();
+  }
+
+  send(method, params = {}, timeoutMs = this.sendTimeoutMs) {
+    if (this.isClosed()) return Promise.reject(new Error(`CDP connection is closed (${method})`));
+    const id = (this.nextId += 1);
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`CDP timeout: ${method} (${timeoutMs} ms)`));
+      }, timeoutMs);
+      if (typeof timer.unref === "function") timer.unref();
+      this.pending.set(id, { resolve, reject, timer, method });
+      try {
+        this.ws.send(JSON.stringify({ id, method, params }));
+      } catch (error) {
+        clearTimeout(timer);
+        this.pending.delete(id);
+        reject(error instanceof Error ? error : new Error(String(error)));
+      }
+    });
+  }
+
+  /** Subscribe to a CDP event; returns an unsubscribe function. */
+  on(method, listener) {
+    if (typeof listener !== "function") throw new Error("CDP listener must be a function");
+    if (!this.listeners.has(method)) this.listeners.set(method, new Set());
+    this.listeners.get(method).add(listener);
+    return () => {
+      const listeners = this.listeners.get(method);
+      if (!listeners) return;
+      listeners.delete(listener);
+      if (listeners.size === 0) this.listeners.delete(method);
+    };
+  }
+
+  /** Resolve on the next event, reject on timeout or connection close. */
+  once(method, timeoutMs = 15_000) {
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      let off = null;
+      const finish = (callback, value) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        if (off) off();
+        this.closeWaiters.delete(fail);
+        callback(value);
+      };
+      const fail = (error) => finish(reject, error);
+      const timer = setTimeout(() => finish(reject, new Error(`CDP event timeout: ${method} (${timeoutMs} ms)`)), timeoutMs);
+      if (typeof timer.unref === "function") timer.unref();
+      this.closeWaiters.add(fail);
+      off = this.on(method, (params) => finish(resolve, params));
+    });
+  }
+
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    const error = new Error("CDP client closed");
+    for (const pending of this.pending.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(error);
+    }
+    this.pending.clear();
+    for (const fail of [...this.closeWaiters]) {
+      try {
+        fail(error);
+      } catch {
+        /* ignore */
+      }
+    }
+    this.closeWaiters.clear();
+    this.listeners.clear();
+    const ws = this.ws;
+    this.ws = null;
+    try {
+      ws?.close();
+    } catch {
+      /* already closed */
+    }
+  }
+}