@hera-al/browser-server 1.0.0

package/dist/server/routes/snapshot.js

@@ -0,0 +1,143 @@
+import { Hono } from "hono";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+import { snapshotRoleViaPlaywright, snapshotAiViaPlaywright, pdfViaPlaywright, } from "../../playwright/pw-tools-core.snapshot.js";
+import { takeScreenshotViaPlaywright } from "../../playwright/pw-tools-core.interactions.js";
+import { snapshotAria as snapshotAriaCdp, snapshotDom as snapshotDomCdp, getDomText, querySelector, } from "../../core/cdp.js";
+import { getChromeWebSocketUrl } from "../../core/chrome.js";
+import { normalizeCdpWsUrl } from "../../core/cdp.js";
+import { fetchJson, appendCdpPath } from "../../core/cdp.helpers.js";
+export function snapshotRoutes(ctx) {
+    const app = new Hono();
+    // Role-based snapshot (Playwright)
+    app.get("/snapshot", async (c) => {
+        const profileName = c.req.query("profile");
+        const mode = c.req.query("mode") || "role";
+        const selector = c.req.query("selector");
+        const frameSelector = c.req.query("frameSelector");
+        const interactive = c.req.query("interactive") === "true";
+        const compact = c.req.query("compact") === "true";
+        const targetId = c.req.query("targetId");
+        try {
+            const profile = ctx.getProfile(profileName);
+            const cdpUrl = profile.cdpUrl;
+            const tid = targetId || ctx.getLastTargetId(profile.name);
+            if (mode === "aria") {
+                // CDP-based aria snapshot
+                const wsUrl = await resolveWsUrl(cdpUrl, tid);
+                const result = await snapshotAriaCdp({ wsUrl });
+                return c.json({ ok: true, result });
+            }
+            if (mode === "dom") {
+                const wsUrl = await resolveWsUrl(cdpUrl, tid);
+                const result = await snapshotDomCdp({ wsUrl });
+                return c.json({ ok: true, result });
+            }
+            if (mode === "text" || mode === "html") {
+                const wsUrl = await resolveWsUrl(cdpUrl, tid);
+                const result = await getDomText({
+                    wsUrl,
+                    format: mode,
+                    selector: selector || undefined,
+                });
+                return c.json({ ok: true, result });
+            }
+            if (mode === "query") {
+                const sel = selector || c.req.query("q") || "";
+                if (!sel) {
+                    return c.json({ ok: false, error: "selector (q) is required for query mode" }, 400);
+                }
+                const wsUrl = await resolveWsUrl(cdpUrl, tid);
+                const result = await querySelector({ wsUrl, selector: sel });
+                return c.json({ ok: true, result });
+            }
+            if (mode === "ai") {
+                const result = await snapshotAiViaPlaywright({
+                    cdpUrl,
+                    targetId: tid,
+                });
+                return c.json({ ok: true, result });
+            }
+            // Default: role snapshot via Playwright
+            const result = await snapshotRoleViaPlaywright({
+                cdpUrl,
+                targetId: tid,
+                selector: selector || undefined,
+                frameSelector: frameSelector || undefined,
+                options: {
+                    interactive: interactive || undefined,
+                    compact: compact || undefined,
+                },
+            });
+            return c.json({ ok: true, result });
+        }
+        catch (err) {
+            return c.json({ ok: false, error: err instanceof Error ? err.message : String(err) }, 500);
+        }
+    });
+    app.post("/screenshot", async (c) => {
+        const body = await c.req.json().catch(() => ({}));
+        try {
+            const profile = ctx.getProfile(body.profile);
+            const cdpUrl = profile.cdpUrl;
+            const tid = body.targetId || ctx.getLastTargetId(profile.name);
+            const shot = await takeScreenshotViaPlaywright({
+                cdpUrl,
+                targetId: tid,
+                ref: body.ref,
+                element: body.element,
+                fullPage: body.fullPage,
+                type: body.type,
+            });
+            const ext = body.type === "jpeg" ? "jpg" : "png";
+            const fileName = `screenshot-${crypto.randomUUID().slice(0, 8)}.${ext}`;
+            const dir = path.join(os.tmpdir(), "grabmeabeer", "screenshots");
+            await fs.mkdir(dir, { recursive: true });
+            const filePath = path.join(dir, fileName);
+            await fs.writeFile(filePath, shot.buffer);
+            return c.json({ ok: true, path: filePath, size: shot.buffer.length });
+        }
+        catch (err) {
+            return c.json({ ok: false, error: err instanceof Error ? err.message : String(err) }, 500);
+        }
+    });
+    app.post("/pdf", async (c) => {
+        const body = await c.req.json().catch(() => ({}));
+        try {
+            const profile = ctx.getProfile(body.profile);
+            const cdpUrl = profile.cdpUrl;
+            const tid = body.targetId || ctx.getLastTargetId(profile.name);
+            const pdf = await pdfViaPlaywright({ cdpUrl, targetId: tid });
+            const fileName = `page-${crypto.randomUUID().slice(0, 8)}.pdf`;
+            const dir = path.join(os.tmpdir(), "grabmeabeer", "pdfs");
+            await fs.mkdir(dir, { recursive: true });
+            const filePath = path.join(dir, fileName);
+            await fs.writeFile(filePath, pdf.buffer);
+            return c.json({ ok: true, path: filePath, size: pdf.buffer.length });
+        }
+        catch (err) {
+            return c.json({ ok: false, error: err instanceof Error ? err.message : String(err) }, 500);
+        }
+    });
+    return app;
+}
+async function resolveWsUrl(cdpUrl, targetId) {
+    if (targetId) {
+        const listUrl = appendCdpPath(cdpUrl, "/json/list");
+        const targets = await fetchJson(listUrl, 2000).catch(() => []);
+        const target = targets.find(t => t.id === targetId);
+        const wsRaw = target?.webSocketDebuggerUrl;
+        if (wsRaw) {
+            return normalizeCdpWsUrl(wsRaw, cdpUrl);
+        }
+    }
+    // Fall back to browser debugger URL
+    const wsUrl = await getChromeWebSocketUrl(cdpUrl, 2000);
+    if (!wsUrl) {
+        throw new Error(`Cannot resolve WebSocket URL for ${cdpUrl}`);
+    }
+    return wsUrl;
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/server/routes/storage.d.ts

@@ -0,0 +1,4 @@
+import { Hono } from "hono";
+import type { BrowserContext } from "../browser-context.js";
+export declare function storageRoutes(ctx: BrowserContext): Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
+//# sourceMappingURL=storage.d.ts.map

package/dist/server/routes/storage.js

@@ -0,0 +1,117 @@
+import { Hono } from "hono";
+import { cookiesGetViaPlaywright, cookiesSetViaPlaywright, cookiesClearViaPlaywright, storageGetViaPlaywright, storageSetViaPlaywright, storageClearViaPlaywright, } from "../../playwright/pw-tools-core.storage.js";
+export function storageRoutes(ctx) {
+    const app = new Hono();
+    // Cookies
+    app.get("/cookies", async (c) => {
+        const profileName = c.req.query("profile");
+        const targetId = c.req.query("targetId");
+        try {
+            const profile = ctx.getProfile(profileName);
+            const result = await cookiesGetViaPlaywright({
+                cdpUrl: profile.cdpUrl,
+                targetId: targetId || ctx.getLastTargetId(profile.name),
+            });
+            return c.json({ ok: true, ...result });
+        }
+        catch (err) {
+            return c.json({ ok: false, error: err instanceof Error ? err.message : String(err) }, 500);
+        }
+    });
+    app.post("/cookies", async (c) => {
+        const body = await c.req.json();
+        try {
+            const profile = ctx.getProfile(body.profile);
+            await cookiesSetViaPlaywright({
+                cdpUrl: profile.cdpUrl,
+                targetId: body.targetId || ctx.getLastTargetId(profile.name),
+                cookie: body.cookie,
+            });
+            return c.json({ ok: true });
+        }
+        catch (err) {
+            return c.json({ ok: false, error: err instanceof Error ? err.message : String(err) }, 500);
+        }
+    });
+    app.delete("/cookies", async (c) => {
+        const profileName = c.req.query("profile");
+        const targetId = c.req.query("targetId");
+        try {
+            const profile = ctx.getProfile(profileName);
+            await cookiesClearViaPlaywright({
+                cdpUrl: profile.cdpUrl,
+                targetId: targetId || ctx.getLastTargetId(profile.name),
+            });
+            return c.json({ ok: true });
+        }
+        catch (err) {
+            return c.json({ ok: false, error: err instanceof Error ? err.message : String(err) }, 500);
+        }
+    });
+    // localStorage / sessionStorage
+    app.get("/storage/:kind", async (c) => {
+        const kind = c.req.param("kind");
+        if (kind !== "local" && kind !== "session") {
+            return c.json({ ok: false, error: "kind must be 'local' or 'session'" }, 400);
+        }
+        const profileName = c.req.query("profile");
+        const targetId = c.req.query("targetId");
+        const key = c.req.query("key");
+        try {
+            const profile = ctx.getProfile(profileName);
+            const result = await storageGetViaPlaywright({
+                cdpUrl: profile.cdpUrl,
+                targetId: targetId || ctx.getLastTargetId(profile.name),
+                kind,
+                key: key || undefined,
+            });
+            return c.json({ ok: true, ...result });
+        }
+        catch (err) {
+            return c.json({ ok: false, error: err instanceof Error ? err.message : String(err) }, 500);
+        }
+    });
+    app.post("/storage/:kind", async (c) => {
+        const kind = c.req.param("kind");
+        if (kind !== "local" && kind !== "session") {
+            return c.json({ ok: false, error: "kind must be 'local' or 'session'" }, 400);
+        }
+        const body = await c.req.json();
+        try {
+            const profile = ctx.getProfile(body.profile);
+            await storageSetViaPlaywright({
+                cdpUrl: profile.cdpUrl,
+                targetId: body.targetId || ctx.getLastTargetId(profile.name),
+                kind,
+                key: body.key,
+                value: body.value,
+            });
+            return c.json({ ok: true });
+        }
+        catch (err) {
+            return c.json({ ok: false, error: err instanceof Error ? err.message : String(err) }, 500);
+        }
+    });
+    app.delete("/storage/:kind", async (c) => {
+        const kind = c.req.param("kind");
+        if (kind !== "local" && kind !== "session") {
+            return c.json({ ok: false, error: "kind must be 'local' or 'session'" }, 400);
+        }
+        const profileName = c.req.query("profile");
+        const targetId = c.req.query("targetId");
+        try {
+            const profile = ctx.getProfile(profileName);
+            await storageClearViaPlaywright({
+                cdpUrl: profile.cdpUrl,
+                targetId: targetId || ctx.getLastTargetId(profile.name),
+                kind,
+            });
+            return c.json({ ok: true });
+        }
+        catch (err) {
+            return c.json({ ok: false, error: err instanceof Error ? err.message : String(err) }, 500);
+        }
+    });
+    return app;
+}
+//# sourceMappingURL=storage.js.map

package/dist/server/routes/tabs.d.ts

@@ -0,0 +1,4 @@
+import { Hono } from "hono";
+import type { BrowserContext } from "../browser-context.js";
+export declare function tabsRoutes(ctx: BrowserContext): Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
+//# sourceMappingURL=tabs.d.ts.map

package/dist/server/routes/tabs.js

@@ -0,0 +1,51 @@
+import { Hono } from "hono";
+export function tabsRoutes(ctx) {
+    const app = new Hono();
+    app.get("/tabs", async (c) => {
+        const profile = c.req.query("profile");
+        try {
+            const tabs = await ctx.listTabs(profile);
+            return c.json({ ok: true, tabs });
+        }
+        catch (err) {
+            return c.json({ ok: false, error: err instanceof Error ? err.message : String(err) }, 500);
+        }
+    });
+    app.post("/tabs/open", async (c) => {
+        const body = await c.req.json();
+        const url = body.url || "about:blank";
+        try {
+            const tab = await ctx.openTab(url, body.profile);
+            return c.json({ ok: true, tab });
+        }
+        catch (err) {
+            return c.json({ ok: false, error: err instanceof Error ? err.message : String(err) }, 500);
+        }
+    });
+    app.post("/tabs/focus", async (c) => {
+        const body = await c.req.json();
+        if (!body.id) {
+            return c.json({ ok: false, error: "id is required" }, 400);
+        }
+        try {
+            await ctx.focusTab(body.id, body.profile);
+            return c.json({ ok: true });
+        }
+        catch (err) {
+            return c.json({ ok: false, error: err instanceof Error ? err.message : String(err) }, 500);
+        }
+    });
+    app.delete("/tabs/:id", async (c) => {
+        const id = c.req.param("id");
+        const profile = c.req.query("profile");
+        try {
+            await ctx.closeTab(id, profile);
+            return c.json({ ok: true });
+        }
+        catch (err) {
+            return c.json({ ok: false, error: err instanceof Error ? err.message : String(err) }, 500);
+        }
+    });
+    return app;
+}
+//# sourceMappingURL=tabs.js.map

package/dist/server/standalone.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * Standalone entry point for the browser HTTP server.
+ * Can be spawned as a subprocess by standardnode or run directly.
+ *
+ * Usage: tsx src/browser/server/standalone.ts [--port 3002] [--headless true] [--noSandbox true]
+ */
+export {};
+//# sourceMappingURL=standalone.d.ts.map

package/dist/server/standalone.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+/**
+ * Standalone entry point for the browser HTTP server.
+ * Can be spawned as a subprocess by standardnode or run directly.
+ *
+ * Usage: tsx src/browser/server/standalone.ts [--port 3002] [--headless true] [--noSandbox true]
+ */
+import { startBrowserServer, stopBrowserServer } from "./browser-server.js";
+import { BrowserConfigSchema, resolveBrowserConfig } from "../config.js";
+function parseArgs() {
+    const args = process.argv.slice(2);
+    const result = {};
+    for (let i = 0; i < args.length; i++) {
+        if (args[i].startsWith("--") && args[i + 1] && !args[i + 1].startsWith("--")) {
+            result[args[i].slice(2)] = args[++i];
+        }
+    }
+    return result;
+}
+const args = parseArgs();
+const port = parseInt(args.port ?? "3002", 10);
+const parsed = BrowserConfigSchema.parse({
+    enabled: true,
+    controlPort: port,
+    headless: args.headless === "true",
+    noSandbox: args.noSandbox === "true",
+    attachOnly: args.attachOnly === "true",
+    executablePath: args.executablePath || undefined,
+});
+const config = resolveBrowserConfig(parsed);
+await startBrowserServer(config);
+// Signal parent process (if spawned via fork / IPC)
+if (process.send) {
+    process.send({ type: "ready", port });
+}
+const shutdown = async () => {
+    await stopBrowserServer();
+    process.exit(0);
+};
+process.on("SIGTERM", shutdown);
+process.on("SIGINT", shutdown);
+//# sourceMappingURL=standalone.js.map

package/dist/utils.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Check if a port is available (not in use).
+ * Throws if the port is already taken.
+ */
+export declare function ensurePortAvailable(port: number): Promise<void>;
+/**
+ * Format an error into a human-readable message.
+ */
+export declare function formatErrorMessage(err: unknown): string;
+/**
+ * Check if a hostname is a loopback address.
+ */
+export declare function isLoopbackHost(host: string): boolean;
+/**
+ * Convert raw WebSocket data to string.
+ */
+export declare function rawDataToString(data: unknown): string;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.js

@@ -0,0 +1,58 @@
+import net from "node:net";
+/**
+ * Check if a port is available (not in use).
+ * Throws if the port is already taken.
+ */
+export async function ensurePortAvailable(port) {
+    return new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.once("error", (err) => {
+            if (err.code === "EADDRINUSE") {
+                reject(new Error(`Port ${port} is already in use`));
+            }
+            else {
+                reject(err);
+            }
+        });
+        server.once("listening", () => {
+            server.close(() => resolve());
+        });
+        server.listen(port, "127.0.0.1");
+    });
+}
+/**
+ * Format an error into a human-readable message.
+ */
+export function formatErrorMessage(err) {
+    if (err instanceof Error)
+        return err.message;
+    if (typeof err === "string")
+        return err;
+    return String(err);
+}
+/**
+ * Check if a hostname is a loopback address.
+ */
+export function isLoopbackHost(host) {
+    const lower = host.toLowerCase();
+    return (lower === "localhost" ||
+        lower === "127.0.0.1" ||
+        lower === "::1" ||
+        lower === "[::1]" ||
+        lower === "0.0.0.0");
+}
+/**
+ * Convert raw WebSocket data to string.
+ */
+export function rawDataToString(data) {
+    if (typeof data === "string")
+        return data;
+    if (Buffer.isBuffer(data))
+        return data.toString("utf-8");
+    if (data instanceof ArrayBuffer)
+        return Buffer.from(data).toString("utf-8");
+    if (Array.isArray(data))
+        return Buffer.concat(data).toString("utf-8");
+    return String(data);
+}
+//# sourceMappingURL=utils.js.map

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@hera-al/browser-server",
+  "version": "1.0.0",
+  "description": "Hera Browser Server — local browser automation via Playwright and CDP",
+  "license": "MIT",
+  "author": "TGP <ltoscano@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ltoscano/hera_al.git",
+    "directory": "packages/browser-server"
+  },
+  "homepage": "https://github.com/ltoscano/hera_al",
+  "keywords": [
+    "browser-automation",
+    "playwright",
+    "cdp",
+    "chrome-devtools-protocol",
+    "ai-agent",
+    "hera"
+  ],
+  "type": "module",
+  "main": "./dist/server/browser-server.js",
+  "types": "./dist/server/browser-server.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/server/browser-server.js",
+      "types": "./dist/server/browser-server.d.ts"
+    },
+    "./config": {
+      "import": "./dist/config.js",
+      "types": "./dist/config.d.ts"
+    },
+    "./utils": {
+      "import": "./dist/utils.js",
+      "types": "./dist/utils.d.ts"
+    },
+    "./standalone": {
+      "import": "./dist/server/standalone.js",
+      "types": "./dist/server/standalone.d.ts"
+    }
+  },
+  "bin": {
+    "hera-browser": "./dist/server/standalone.js"
+  },
+  "files": ["dist", "!dist/**/*.map", "!src", "!tsconfig.json"],
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "start": "node dist/server/standalone.js",
+    "dev": "tsx watch src/server/standalone.ts",
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@hono/node-server": "^1.14.0",
+    "hono": "^4.7.0",
+    "playwright-core": "^1.50.0",
+    "ws": "^8.18.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.4",
+    "@types/ws": "^8.5.13",
+    "tsx": "^4.19.3",
+    "typescript": "^5.7.3"
+  }
+}