dsh-browser-verify 0.1.0

package/lib/driver-DxMldTYf.js

@@ -0,0 +1,424 @@
+import { exec } from "node:child_process";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { existsSync, readdirSync, rmSync } from "node:fs";
+import { chromium } from "playwright-core";
+import { createHash } from "node:crypto";
+//#region src/browser/discover.ts
+/**
+* Locate a Browser-for-Testing binary in the machine playwright cache. Pure:
+* filesystem probing is injected so every branch is unit-testable.
+* @module dsh-browser-verify/browser/discover
+*/
+/** Revision numbers verified against the matching playwright-core browsers.json. */
+const KNOWN_REVISIONS = { 1234: "1.62.x" };
+const SUBDIRS = {
+	"headless-shell": "chrome-headless-shell-mac-arm64/chrome-headless-shell",
+	chromium: "chrome-mac-arm64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing"
+};
+const LIST_PREFIXES = [{
+	kind: "headless-shell",
+	prefix: "chromium_headless_shell-"
+}, {
+	kind: "chromium",
+	prefix: "chromium-"
+}];
+/** Default cache location on macOS. */
+function defaultCacheDir() {
+	return join(homedir(), "Library", "Caches", "ms-playwright");
+}
+function maxRevision(list, prefix) {
+	let max = null;
+	for (const entry of list) {
+		if (!entry.startsWith(prefix)) continue;
+		const suffix = entry.slice(prefix.length);
+		if (!/^\d+$/.test(suffix)) continue;
+		const value = Number(suffix);
+		if (max === null || value > max) max = value;
+	}
+	return max;
+}
+/**
+* Find the browser binary: env override wins, then headless shell (highest
+* revision), then full chromium. Throws with an install hint when absent.
+*/
+function discoverBrowser(opts = {}) {
+	const exists = opts.exists ?? existsSync;
+	if (opts.overridePath !== void 0) {
+		if (!exists(opts.overridePath)) throw new Error(`browser-verify: DSH_BROWSER_VERIFY_CHROMIUM 指向的二进制不存在: ${opts.overridePath}。请检查路径或取消该环境变量。`);
+		return {
+			executablePath: opts.overridePath,
+			kind: "custom",
+			revision: 0,
+			known: true,
+			versionHint: null
+		};
+	}
+	const cacheDir = opts.cacheDir ?? defaultCacheDir();
+	let list = null;
+	if (opts.entries !== void 0) list = opts.entries;
+	else try {
+		list = readdirSync(cacheDir);
+	} catch {
+		list = null;
+	}
+	if (list === null) throw new Error(`browser-verify: 未找到浏览器缓存目录 ${cacheDir}。请先安装：npx playwright install chromium（需 playwright-core@1.62.0），或设置 DSH_BROWSER_VERIFY_CHROMIUM=<完整路径>。`);
+	for (const { kind, prefix } of LIST_PREFIXES) {
+		const revision = maxRevision(list, prefix);
+		if (revision === null) continue;
+		const executablePath = join(cacheDir, `${kind === "headless-shell" ? `chromium_headless_shell-${revision}` : `chromium-${revision}`}`, SUBDIRS[kind]);
+		if (!exists(executablePath)) throw new Error(`browser-verify: 缓存目录存在 ${prefix}${revision} 但可执行文件缺失（${cacheDir}）。请删除该目录后重新执行 npx playwright install chromium。`);
+		const known = KNOWN_REVISIONS[revision] !== void 0;
+		return {
+			executablePath,
+			kind,
+			revision,
+			known,
+			versionHint: known ? null : `浏览器 revision ${revision} 不在已认证表（playwright-core 1.62.0 认证 ${Object.keys(KNOWN_REVISIONS).join("/")}）；若协议异常，请安装匹配版本`
+		};
+	}
+	throw new Error(`browser-verify: 未找到浏览器二进制。请先安装：npx playwright install chromium（需 playwright-core@1.62.0），或设置 DSH_BROWSER_VERIFY_CHROMIUM=<完整路径>。`);
+}
+//#endregion
+//#region src/browser/scenario.ts
+/**
+* One verification scenario = one page + its request mocks + assertion/shot
+* state. Pure helpers are exported for unit tests; the IO methods use
+* playwright-core. Polluting nothing outside the page's own requests.
+* @module dsh-browser-verify/browser/scenario
+*/
+const MAX_VISIBLE = 8;
+const MAX_VISIBLE_LEN = 40;
+const MAX_ERRORS = 5;
+const MAX_ERROR_LEN = 120;
+function assertNoMockConflict(patterns, next) {
+	if (patterns.includes(next)) throw new Error(`browser-verify: 拦截 pattern 已存在: ${next}（已有: ${patterns.join(", ")}）。请先 browser_open 重开场景或用不同的 urlPattern。`);
+}
+function normalizeCountSpec(count) {
+	if (typeof count === "number") return {
+		min: count,
+		max: count
+	};
+	if (count !== void 0 && typeof count.min === "number" && typeof count.max === "number") return {
+		min: count.min,
+		max: count.max
+	};
+	return null;
+}
+function summarizeVisibleText(texts) {
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	for (const raw of texts) {
+		const trimmed = raw.trim();
+		if (trimmed === "") continue;
+		const reduced = trimmed.length > MAX_VISIBLE_LEN ? trimmed.slice(0, MAX_VISIBLE_LEN) : trimmed;
+		if (seen.has(reduced)) continue;
+		seen.add(reduced);
+		out.push(reduced);
+		if (out.length >= MAX_VISIBLE) break;
+	}
+	return out;
+}
+function capConsoleErrors(errors) {
+	return errors.slice(0, MAX_ERRORS).map((e) => e.length > MAX_ERROR_LEN ? `${e.slice(0, MAX_ERROR_LEN - 1)}…` : e);
+}
+function sha256Hex(data) {
+	return createHash("sha256").update(data).digest("hex");
+}
+/** Visible-text extraction, evaluated in the page: text of visible elements. */
+const VISIBLE_TEXT_SCRIPT = `
+Array.from(document.querySelectorAll('body *')).map(el => {
+  const rect = el.getBoundingClientRect()
+  if (rect.width === 0 || rect.height === 0) return ''
+  const text = (el.childElementCount === 0 ? el.textContent ?? '' : '').trim()
+  return text.length > 0 ? text : ''
+})
+`;
+var Scenario = class {
+	page;
+	context;
+	mocks = /* @__PURE__ */ new Map();
+	lastScreenshotHash = null;
+	constructor(page, context) {
+		this.page = page;
+		this.context = context;
+	}
+	async navigate(opts) {
+		const started = Date.now();
+		const timeout = opts.timeoutMs ?? 1e4;
+		const errors = [];
+		const onError = (message) => {
+			errors.push(message);
+		};
+		this.page.on("console", (msg) => {
+			if (msg.type() === "error") onError(msg.text());
+		});
+		this.page.on("pageerror", (err) => onError(String(err)));
+		const response = await this.page.goto(opts.url, {
+			waitUntil: "domcontentloaded",
+			timeout
+		});
+		if (opts.waitSelector !== void 0) await this.page.waitForSelector(opts.waitSelector, { timeout });
+		const texts = await this.page.evaluate(VISIBLE_TEXT_SCRIPT);
+		return {
+			title: await this.page.title(),
+			url: this.page.url(),
+			status: response?.status() ?? null,
+			visible: summarizeVisibleText(texts),
+			consoleErrors: capConsoleErrors(errors),
+			elapsedMs: Date.now() - started
+		};
+	}
+	async addMock(rule) {
+		assertNoMockConflict([...this.mocks.keys()], rule.urlPattern);
+		const status = rule.status ?? 200;
+		this.mocks.set(rule.urlPattern, {
+			json: rule.json,
+			status
+		});
+		await this.context.route(rule.urlPattern, async (route) => {
+			const body = Buffer.from(JSON.stringify(this.mocks.get(rule.urlPattern)?.json ?? rule.json));
+			await route.fulfill({
+				status,
+				body,
+				contentType: "application/json; charset=utf-8"
+			});
+		});
+		if (rule.reload !== false) await this.page.reload({
+			waitUntil: "domcontentloaded",
+			timeout: rule.timeoutMs ?? 1e4
+		});
+		return [...this.mocks.keys()];
+	}
+	async assert(opts) {
+		const started = Date.now();
+		const expected = normalizeCountSpec(opts.count);
+		try {
+			await this.page.waitForSelector(opts.selector, {
+				state: "attached",
+				timeout: opts.timeoutMs
+			});
+		} catch (error) {
+			if (error instanceof Error && /timeout/i.test(error.message)) return {
+				pass: expected !== null && expected.min === 0 && expected.max === 0 && opts.text === void 0,
+				count: 0,
+				actualText: null,
+				elapsedMs: Date.now() - started
+			};
+			throw error;
+		}
+		const count = await this.page.locator(opts.selector).count();
+		const actualText = await this.page.locator(opts.selector).first().textContent();
+		return {
+			pass: (expected === null || count >= expected.min && count <= expected.max) && (opts.text === void 0 || actualText !== null && actualText.includes(opts.text)),
+			count,
+			actualText,
+			elapsedMs: Date.now() - started
+		};
+	}
+	async screenshot(opts) {
+		const data = await this.page.screenshot({
+			fullPage: opts.fullPage ?? false,
+			type: "png"
+		});
+		const sha256 = sha256Hex(data);
+		const identicalToPrevious = sha256 === this.lastScreenshotHash;
+		this.lastScreenshotHash = sha256;
+		return {
+			data,
+			sha256,
+			identicalToPrevious
+		};
+	}
+	async close() {
+		try {
+			await this.context.close();
+		} catch {}
+	}
+};
+//#endregion
+//#region src/browser/driver.ts
+/**
+* Browser driving: one lazy launch per process, one active verification
+* scenario, FIFO-serialized tool access, idle reclamation, graceful close +
+* temp dir removal on dispose. launch args are pure for unit tests.
+* @module dsh-browser-verify/browser/driver
+*/
+/**
+* Headless launch args. Deviation D8-3: playwright-core >= 1.41 rejects
+* `--user-data-dir` inside `args` (misuse error, both launch and
+* launchPersistentContext); the user data dir must be passed as the
+* launchPersistentContext first parameter. Only the headless-mode flag remains.
+*/
+function buildLaunchArgs(headlessShell) {
+	return [headlessShell ? "--headless" : "--headless=new"];
+}
+var BrowserDriver = class {
+	opts;
+	browser = null;
+	discovered = null;
+	scenario = null;
+	userDataDir = join(tmpdir(), `dsh-browser-verify-${process.pid}`, "profile");
+	idleTimer = null;
+	lockChain = Promise.resolve();
+	disposed = false;
+	constructor(opts = {}) {
+		this.opts = opts;
+	}
+	/** FIFO serialization: every tool op runs alone. */
+	chain(fn) {
+		const run = this.lockChain.then(fn);
+		this.lockChain = run.catch(() => void 0);
+		return run;
+	}
+	/** Reject new op entries once disposed; the engine cannot come back. */
+	ensureNotDisposed() {
+		if (this.disposed) throw new Error("browser-verify: 验证引擎已停止。请重新调用 browser_open 开始新的验证。");
+	}
+	/** Normalize errors at the driver boundary: prefix + context + advice. */
+	wrapError(error, context, advice) {
+		if (error instanceof Error && error.message.startsWith("browser-verify: ")) return error;
+		const message = error instanceof Error ? error.message : String(error);
+		return /* @__PURE__ */ new Error(`browser-verify: ${context}: ${message}。${advice}`);
+	}
+	withScenario(fn) {
+		this.ensureNotDisposed();
+		return this.chain(async () => {
+			this.ensureNotDisposed();
+			this.resetIdleTimer();
+			try {
+				return await fn(this.requireScenario());
+			} catch (error) {
+				throw this.wrapError(error, "场景操作失败", "请 browser_open 重开场景后重试。");
+			}
+		});
+	}
+	/** Open a fresh verification scenario; per design, each open = new context+page. */
+	async startScenario(reset) {
+		this.ensureNotDisposed();
+		return this.chain(async () => {
+			this.ensureNotDisposed();
+			this.resetIdleTimer();
+			return this.openScenario(reset);
+		});
+	}
+	async openScenario(reset) {
+		const browser = await this.ensureBrowser();
+		await this.scenario?.close();
+		const context = await browser.newContext({
+			viewport: reset.viewport ?? this.opts.viewport ?? {
+				width: 390,
+				height: 844
+			},
+			deviceScaleFactor: reset.deviceScaleFactor ?? this.opts.deviceScaleFactor ?? 2
+		});
+		const page = await context.newPage();
+		this.scenario = new Scenario(page, context);
+		this.resetIdleTimer();
+		try {
+			for (const rule of reset.mocks ?? []) await this.scenario.addMock({
+				...rule,
+				reload: false
+			});
+			return {
+				...await this.scenario.navigate({
+					url: reset.url,
+					waitSelector: reset.waitSelector,
+					timeoutMs: reset.timeoutMs ?? this.opts.timeoutMs
+				}),
+				browserKnown: this.discovered?.known ?? true,
+				versionHint: this.discovered?.versionHint ?? null
+			};
+		} catch (error) {
+			await this.scenario.close();
+			this.scenario = null;
+			throw this.wrapError(error, "打开页面失败", "请检查 URL 是否可访问、页面是否可在超时内加载，必要时调大 DSH_BROWSER_VERIFY_TIMEOUT。");
+		}
+	}
+	resetIdleTimer() {
+		if (this.idleTimer !== null) clearTimeout(this.idleTimer);
+		this.idleTimer = setTimeout(() => {
+			this.dispose();
+		}, this.opts.idleMs ?? 6e5);
+	}
+	async ensureBrowser() {
+		this.ensureNotDisposed();
+		if (this.browser !== null) return this.browser;
+		try {
+			const found = (this.opts.discover ?? discoverBrowser)({ overridePath: process.env.DSH_BROWSER_VERIFY_CHROMIUM ?? void 0 });
+			this.discovered = found;
+			const browser = (await chromium.launchPersistentContext(this.userDataDir, {
+				executablePath: found.executablePath,
+				args: buildLaunchArgs(found.kind === "headless-shell"),
+				headless: true
+			})).browser();
+			if (browser === null) throw new Error("browser-verify: 持久化上下文未返回浏览器实例。请检查 DSH_BROWSER_VERIFY_CHROMIUM 指向的浏览器，或重新执行 npx playwright install chromium。");
+			this.browser = browser;
+		} catch (error) {
+			throw this.wrapError(error, "浏览器启动失败", "请检查 DSH_BROWSER_VERIFY_CHROMIUM 指向的浏览器路径，或重新执行 npx playwright install chromium。");
+		}
+		this.resetIdleTimer();
+		return this.browser;
+	}
+	requireScenario() {
+		if (this.scenario === null) throw new Error("browser-verify: 尚未打开验证会话。请先调用 browser_open 打开页面。");
+		return this.scenario;
+	}
+	/**
+	* Reset on dispose: mark disposed first (idempotent, blocks new ops), then
+	* run the teardown serialized on the FIFO chain so it waits out any
+	* in-flight op and cannot interleave with a launch or scenario op.
+	*/
+	async dispose() {
+		if (this.disposed) return;
+		this.disposed = true;
+		await this.chain(() => this.teardown());
+	}
+	/** Best-effort teardown: close scenario + browser, delete the profile dir. */
+	async teardown() {
+		if (this.idleTimer !== null) {
+			clearTimeout(this.idleTimer);
+			this.idleTimer = null;
+		}
+		const scenario = this.scenario;
+		this.scenario = null;
+		if (scenario !== null) try {
+			await scenario.close();
+		} catch {}
+		const browser = this.browser;
+		this.browser = null;
+		if (browser !== null) try {
+			await browser.close();
+		} catch {
+			try {
+				await this.hardKillChromium();
+			} catch {}
+		}
+		try {
+			rmSync(join(tmpdir(), `dsh-browser-verify-${process.pid}`), {
+				recursive: true,
+				force: true
+			});
+		} catch {}
+	}
+	/**
+	* Hard-kill fallback: SIGKILL every process whose command line still
+	* carries our user-data-dir (playwright appends `--user-data-dir` itself;
+	* our predictable temp dir is the reverse-lookup key, per design §6).
+	*/
+	async hardKillChromium() {
+		const out = await new Promise((resolve) => {
+			exec("ps -Ao pid=,ppid=,command=", { maxBuffer: 10 * 1024 * 1024 }, (error, stdout) => resolve(error ? "" : stdout));
+		});
+		const marker = `--user-data-dir=${this.userDataDir}`;
+		for (const line of out.split("\n")) {
+			const m = /^\s*(\d+)\s+\d+\s+(.+)$/.exec(line);
+			if (m === null) continue;
+			if (m[2].includes(marker)) try {
+				process.kill(Number(m[1]), "SIGKILL");
+			} catch {}
+		}
+	}
+};
+//#endregion
+export { BrowserDriver as t };