@yibie/pi-jev-browser 0.1.0

package/src/actions.ts

@@ -0,0 +1,205 @@
+import { setTimeout as sleep } from "node:timers/promises";
+import type { Page } from "playwright";
+import type { BrowserAction } from "./types.ts";
+
+export async function executeActions(
+	page: Page,
+	actions: BrowserAction[],
+	options: { assertUrlAllowed: (url: string) => void; signal?: AbortSignal },
+): Promise<void> {
+	if (!Array.isArray(actions) || actions.length === 0) {
+		throw new Error("actions must contain at least one Jev Browser action.");
+	}
+	if (actions.length > 50) {
+		throw new Error("A single jev_actions call is limited to 50 actions.");
+	}
+	// Validate the whole batch before touching the page, so a malformed action
+	// cannot leave earlier actions half-applied.
+	for (const action of actions) assertActionShape(action);
+
+	for (const action of actions) {
+		assertActive(options.signal);
+		switch (action.type) {
+			case "click":
+			case "double_click": {
+				const modifiers = (action.keys ?? []).map(normalizeKey);
+				const options = {
+					button: normalizeButton(action.button),
+					clickCount: action.type === "double_click" ? 2 : 1,
+					modifiers,
+				};
+				await page.mouse.click(action.x, action.y, options);
+				break;
+			}
+			case "scroll":
+				if (typeof action.x === "number" && typeof action.y === "number") {
+					await page.mouse.move(action.x, action.y);
+				}
+				await page.mouse.wheel(action.deltaX, action.deltaY);
+				break;
+			case "type":
+				await page.keyboard.type(action.text);
+				break;
+			case "wait":
+				await delay(
+					Math.min(30_000, Math.max(0, action.ms ?? 1000)),
+					options.signal,
+				);
+				break;
+			case "keypress":
+				await page.keyboard.press(action.keys.map(normalizeKey).join("+"));
+				break;
+			case "drag":
+				await executeDrag(page, action.path, normalizeButton(action.button));
+				break;
+			case "move":
+				await page.mouse.move(action.x, action.y);
+				break;
+			case "screenshot":
+				break;
+			case "navigate":
+				options.assertUrlAllowed(action.url);
+				await page.goto(action.url, {
+					waitUntil: "domcontentloaded",
+					timeout: 30_000,
+				});
+				break;
+			case "back":
+				await page.goBack({ waitUntil: "domcontentloaded", timeout: 30_000 });
+				break;
+			case "forward":
+				await page.goForward({
+					waitUntil: "domcontentloaded",
+					timeout: 30_000,
+				});
+				break;
+			case "reload":
+				await page.reload({ waitUntil: "domcontentloaded", timeout: 30_000 });
+				break;
+			default:
+				throw new Error(
+					`Unsupported Jev Browser action: ${String((action as { type?: unknown }).type)}`,
+				);
+		}
+	}
+}
+
+export function normalizeKey(value: string): string {
+	const key = value.trim();
+	const lookup = key.toUpperCase();
+	const aliases: Record<string, string> = {
+		CTRL: "Control",
+		CONTROL: "Control",
+		CMD: "Meta",
+		COMMAND: "Meta",
+		META: "Meta",
+		ALT: "Alt",
+		OPTION: "Alt",
+		SHIFT: "Shift",
+		ENTER: "Enter",
+		RETURN: "Enter",
+		ESC: "Escape",
+		ESCAPE: "Escape",
+		SPACE: "Space",
+		TAB: "Tab",
+		BACKSPACE: "Backspace",
+		DELETE: "Delete",
+		DEL: "Delete",
+		HOME: "Home",
+		END: "End",
+		PGUP: "PageUp",
+		PAGEUP: "PageUp",
+		PGDN: "PageDown",
+		PAGEDOWN: "PageDown",
+		UP: "ArrowUp",
+		ARROWUP: "ArrowUp",
+		DOWN: "ArrowDown",
+		ARROWDOWN: "ArrowDown",
+		LEFT: "ArrowLeft",
+		ARROWLEFT: "ArrowLeft",
+		RIGHT: "ArrowRight",
+		ARROWRIGHT: "ArrowRight",
+	};
+	return aliases[lookup] ?? (key.length === 1 ? key : key);
+}
+
+function normalizeButton(value?: "left" | "right" | "wheel") {
+	if (!value || value === "left") return "left" as const;
+	if (value === "right") return "right" as const;
+	if (value === "wheel") return "middle" as const;
+	throw new Error(`Unsupported mouse button: ${String(value)}`);
+}
+
+async function executeDrag(
+	page: Page,
+	path: Array<{ x: number; y: number } | [number, number]>,
+	button: "left" | "right" | "middle",
+) {
+	if (!Array.isArray(path) || path.length < 2) {
+		throw new Error("drag requires a path with at least two points.");
+	}
+	const points = path.map((point) =>
+		Array.isArray(point) ? { x: point[0], y: point[1] } : point,
+	);
+	await page.mouse.move(points[0].x, points[0].y);
+	await page.mouse.down({ button });
+	try {
+		for (const point of points.slice(1)) {
+			await page.mouse.move(point.x, point.y, { steps: 5 });
+		}
+	} finally {
+		await page.mouse.up({ button });
+	}
+}
+
+function assertActionShape(action: BrowserAction) {
+	const numeric = (value: unknown) =>
+		typeof value === "number" && Number.isFinite(value);
+	const require = (condition: boolean, message: string) => {
+		if (!condition) throw new Error(message);
+	};
+	switch (action.type) {
+		case "click":
+		case "double_click":
+		case "move":
+			return require(
+				numeric(action.x) && numeric(action.y),
+				`${action.type} requires numeric x and y.`,
+			);
+		case "scroll":
+			return require(
+				numeric(action.deltaX) && numeric(action.deltaY),
+				"scroll requires numeric deltaX and deltaY.",
+			);
+		case "type":
+			return require(
+				typeof action.text === "string",
+				"type requires text.",
+			);
+		case "keypress":
+			return require(
+				Array.isArray(action.keys) && action.keys.length > 0,
+				"keypress requires at least one key.",
+			);
+		case "drag":
+			return require(
+				Array.isArray(action.path) && action.path.length >= 2,
+				"drag requires a path with at least two points.",
+			);
+		case "navigate":
+			return require(
+				typeof action.url === "string" && action.url.trim().length > 0,
+				"navigate requires a url.",
+			);
+		default:
+			return;
+	}
+}
+
+function assertActive(signal?: AbortSignal) {
+	if (signal?.aborted) throw new Error("Browser action was aborted.");
+}
+
+async function delay(ms: number, signal?: AbortSignal) {
+	await sleep(ms, undefined, { signal });
+}

package/src/browser-setup.ts

@@ -0,0 +1,45 @@
+import { execFile } from "node:child_process";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const require = createRequire(import.meta.url);
+
+async function installChromium(): Promise<void> {
+	// Resolve the installed plugin's CLI so browser revisions match its dependency.
+	const cli = join(
+		dirname(require.resolve("playwright/package.json")),
+		"cli.js",
+	);
+	try {
+		await execFileAsync(process.execPath, [cli, "install", "chromium"], {
+			timeout: 120_000,
+			maxBuffer: 2 * 1024 * 1024,
+			windowsHide: true,
+		});
+	} catch {
+		// Installer output can contain proxy credentials; do not expose it to tools.
+		throw new Error(
+			"Automatic Chromium setup failed or timed out. Check network/proxy access and browser-cache permissions, then retry jev_run. On Linux, required system libraries must also be installed by the system administrator.",
+		);
+	}
+}
+
+export function createBrowserSetup(install: () => Promise<void>) {
+	let pending: Promise<void> | undefined;
+	return () => {
+		if (!pending) {
+			pending = Promise.resolve()
+				.then(install)
+				.catch((error) => {
+					pending = undefined;
+					throw error;
+				});
+		}
+		return pending;
+	};
+}
+
+// The CLI checks its cache and downloads only missing browser artifacts.
+export const ensureChromium = createBrowserSetup(installChromium);

package/src/config.ts

@@ -0,0 +1,118 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import type { JevBrowserConfig } from "./types.ts";
+
+export const CONFIG_PATH =
+	process.env.PI_JEV_BROWSER_CONFIG?.trim() ||
+	join(homedir(), ".pi", "agent", "pi-jev-browser.config.json");
+
+const DEFAULT_CONFIG: JevBrowserConfig = {
+	// pi's own configured model by default: it needs no second credential and no
+	// extra API quota, so the loop works out of the box.
+	policy: "pi",
+	allowedOrigins: ["http://*", "https://*"],
+	headless: true,
+	recordVideo: true,
+	showCursor: true,
+	showClickIndicators: true,
+	outputDir: join(homedir(), ".pi", "agent", "data", "jev-browser"),
+	viewport: { width: 1280, height: 720 },
+	stream: { enabled: false, intervalMs: 1000 },
+};
+
+export function readConfigFile(path = CONFIG_PATH): Record<string, unknown> {
+	try {
+		const raw: unknown = JSON.parse(readFileSync(path, "utf8"));
+		if (!raw || typeof raw !== "object" || Array.isArray(raw))
+			throw new Error("Invalid configuration");
+		return raw as Record<string, unknown>;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return {};
+		throw new Error(
+			"Cannot read pi-jev-browser.config.json. Check permissions and JSON syntax.",
+		);
+	}
+}
+
+export function readConfig(path = CONFIG_PATH): JevBrowserConfig {
+	// Only browser settings leave this reader; credentials stay out of browser state.
+	const raw = readConfigFile(path) as Partial<JevBrowserConfig>;
+
+	const viewport = {
+		width: boundedInteger(
+			raw.viewport?.width,
+			640,
+			2560,
+			DEFAULT_CONFIG.viewport.width,
+		),
+		height: boundedInteger(
+			raw.viewport?.height,
+			480,
+			1600,
+			DEFAULT_CONFIG.viewport.height,
+		),
+	};
+	const allowedOrigins = Array.isArray(raw.allowedOrigins)
+		? raw.allowedOrigins.filter(
+				(value): value is string =>
+					typeof value === "string" && value.trim().length > 0,
+			)
+		: DEFAULT_CONFIG.allowedOrigins;
+
+	return {
+		policy: raw.policy === "typesafe" ? "typesafe" : DEFAULT_CONFIG.policy,
+		allowedOrigins,
+		headless: raw.headless !== false,
+		recordVideo: raw.recordVideo !== false,
+		showCursor: raw.showCursor !== false,
+		showClickIndicators: raw.showClickIndicators !== false,
+		outputDir:
+			typeof raw.outputDir === "string" && raw.outputDir.trim()
+				? resolve(raw.outputDir.replace(/^~/, homedir()))
+				: DEFAULT_CONFIG.outputDir,
+		viewport,
+		stream: {
+			enabled: raw.stream?.enabled === true,
+			intervalMs: boundedInteger(
+				raw.stream?.intervalMs,
+				250,
+				10_000,
+				DEFAULT_CONFIG.stream.intervalMs,
+			),
+		},
+	};
+}
+
+export function isUrlAllowed(value: string, patterns: string[]): boolean {
+	if (value === "about:blank") return true;
+	let url: URL;
+	try {
+		url = new URL(value);
+	} catch {
+		return false;
+	}
+	if (url.protocol !== "http:" && url.protocol !== "https:") return false;
+
+	return patterns.some((pattern) => {
+		const normalized = pattern.trim();
+		if (!normalized) return false;
+		const expression = `^${escapeRegExp(normalized).replaceAll("\\*", ".*")}$`;
+		return new RegExp(expression, "i").test(url.origin);
+	});
+}
+
+function boundedInteger(
+	value: unknown,
+	min: number,
+	max: number,
+	fallback: number,
+) {
+	return typeof value === "number" && Number.isInteger(value)
+		? Math.min(max, Math.max(min, value))
+		: fallback;
+}
+
+function escapeRegExp(value: string) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/src/credentials.ts

@@ -0,0 +1,26 @@
+import { CONFIG_PATH, readConfigFile } from "./config.ts";
+
+/**
+ * Credentials for the direct TypeSafe API. Read per run without mutating
+ * process.env or exposing them to the browser process, which gets `env: {}`.
+ */
+export function readTypesafeCredentials(
+	options: { path?: string; env?: NodeJS.ProcessEnv } = {},
+) {
+	const path = options.path ?? CONFIG_PATH;
+	const env = options.env ?? process.env;
+	const raw = readConfigFile(path);
+	const typesafe = raw.typesafe as
+		| { apiKey?: unknown; model?: unknown }
+		| undefined;
+	const value = (input: unknown) =>
+		typeof input === "string" ? input.trim() : "";
+	const apiKey = value(env.TYPESAFE_API_KEY) || value(typesafe?.apiKey);
+	if (!apiKey)
+		throw new Error(
+			`policy "typesafe" requires TYPESAFE_API_KEY in the pi process environment or typesafe.apiKey in ${path}. Get a key at https://console.typesafe.ai/keys`,
+		);
+	const model =
+		value(env.TYPESAFE_MODEL) || value(typesafe?.model) || "jev-latest";
+	return { apiKey, model };
+}