browse-agent-cli 0.0.1

package/README.md

@@ -0,0 +1,125 @@
+# browse-agent-cli
+
+`browse-agent-cli` is an npm package that provides:
+
+- A CLI command: `browse-agent`
+- Script-style exports for Node.js: `browse-agent-cli/script`
+
+It is designed for browser automation workflows powered by `browse-agent-sdk`.
+
+## Installation
+
+### Global install (recommended for CLI)
+
+```bash
+npm install -g browse-agent-cli
+```
+
+After installation:
+
+```bash
+browse-agent --help
+```
+
+### Project install (for script imports)
+
+```bash
+npm install browse-agent-cli
+```
+
+## Quick Start (CLI)
+
+```bash
+# One-time setup
+browse-agent setup
+
+# Launch browser session
+browse-agent launch
+
+# Navigate and extract
+browse-agent navigate "https://example.com"
+browse-agent get-content --format text
+
+# Close session
+browse-agent close
+```
+
+## CLI Commands
+
+### Lifecycle
+
+- `browse-agent setup`
+- `browse-agent launch`
+- `browse-agent connect`
+- `browse-agent close`
+- `browse-agent clear`
+
+### Feature commands
+
+- `browse-agent navigate <url>`
+- `browse-agent get-content [--format text|html] [--tabId <id>]`
+- `browse-agent get-dom <selector> [--property outerHTML|innerHTML|innerText] [--all] [--tabId <id>]`
+- `browse-agent evaluate <expression> [--tabId <id>]`
+- `browse-agent inject-script <code> [--tabId <id>]`
+- `browse-agent inject-css <code> [--tabId <id>]`
+- `browse-agent screenshot [visible|fullPage|area] [--format png|jpeg] [--quality <1-100>] [--tabId <id>]`
+- `browse-agent tabs [list|close|activate] [tabId]`
+
+### Skill command
+
+- `browse-agent skill <directory>`
+
+This command copies the package `skill` folder into:
+
+- `<directory>/browse-agent`
+
+Conflict behavior when target exists and is not empty:
+
+- `overwrite`: remove and replace target folder
+- `rename`: enter a new directory name, then retry
+- `cancel`: abort operation
+
+## Script Import
+
+Import helper functions from `browse-agent-cli/script`:
+
+```ts
+import { browse } from 'browse-agent-cli/script';
+
+await browse(async (agent) => {
+  await agent.navigate('https://example.com');
+  const page = await agent.getContent({ format: 'text' });
+  return { title: page.title, content: page.content };
+});
+```
+
+You can also import modular helpers:
+
+```ts
+import {
+  launchBrowser,
+  navigate,
+  getContent,
+  screenshot,
+  closeBrowser,
+} from 'browse-agent-cli/script';
+```
+
+## Common Options
+
+- `--browser <name>`: `chrome | chromium | edge | brave`
+- `--headless`
+- `--port <number>`
+- `--servicePort <number>`
+- `--timeout <ms>`
+- `--tabId <id>`
+
+## Notes
+
+- Node.js 18+ is required.
+- One of Chrome/Chromium/Edge/Brave is required.
+- For logged-in pages, ensure your browser profile/session strategy matches your environment.
+
+## License
+
+MIT

package/dist/clear.js

@@ -0,0 +1,24 @@
+import { t as BASE_DIR, u as loadSession } from "./config.js";
+import { existsSync, rmSync } from "node:fs";
+//#region src/scripts/clear.ts
+async function clear() {
+	const baseDir = BASE_DIR;
+	console.log("Clearing browse-agent...");
+	const session = loadSession();
+	if (session?.pid) try {
+		process.kill(session.pid);
+		console.log(`  Killed browser (PID: ${session.pid})`);
+	} catch (err) {
+		const killErr = err;
+		if (killErr.code !== "ESRCH") console.error(`  Failed to kill browser (PID: ${session.pid}):`, killErr.message);
+	}
+	if (existsSync(baseDir)) {
+		rmSync(baseDir, { recursive: true });
+		console.log(`  Removed ${baseDir}`);
+	} else console.log(`  ${baseDir} does not exist, skipping.`);
+	console.log("Done.\n");
+}
+//#endregion
+export { clear as t };
+
+//# sourceMappingURL=clear.js.map

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli.js

@@ -0,0 +1,501 @@
+#!/usr/bin/env node
+import { l as loadServiceSession, n as DEFAULT_SERVICE_PORT, t as BASE_DIR } from "./config.js";
+import { t as clear } from "./clear.js";
+import { execSync, spawn } from "node:child_process";
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync, statSync, unlinkSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+//#region src/scripts/setup.ts
+async function setup() {
+	const baseDir = BASE_DIR;
+	const extensionDir = join(baseDir, "extension");
+	const zipPath = join(baseDir, "extension.zip");
+	const extensionInstalled = existsSync(join(extensionDir, "manifest.json"));
+	if (extensionInstalled) {
+		console.log("browse-agent is already set up.");
+		console.log(`  Extension path: ${extensionDir}`);
+		console.log("  Extension: installed\n");
+		return;
+	}
+	console.log("Setting up browse-agent...\n");
+	mkdirSync(baseDir, { recursive: true });
+	if (extensionInstalled) {
+		console.log("\n[1/2] Downloading Chrome extension from latest release...");
+		console.log("  Skipped: extension is already installed.");
+		console.log("\n[2/2] Extracting extension...");
+		console.log("  Skipped: extension is already installed.");
+	} else {
+		console.log("\n[1/2] Downloading Chrome extension from latest release...");
+		const releaseJson = execSync(`curl -s "https://api.github.com/repos/imlinhanchao/browse-agent/releases/latest"`).toString();
+		const asset = JSON.parse(releaseJson).assets?.find((item) => item.name.endsWith(".zip"));
+		if (!asset) {
+			console.error("Error: No extension zip found in latest release.");
+			console.error("Visit https://github.com/imlinhanchao/browse-agent/releases to check.");
+			process.exit(1);
+		}
+		console.log(`  Downloading ${asset.name} (${(asset.size / 1024).toFixed(1)} KB)...`);
+		execSync(`curl -sL -o "${zipPath}" "${asset.browser_download_url}"`);
+		console.log("\n[2/2] Extracting extension...");
+		if (existsSync(extensionDir)) execSync(`rm -rf "${extensionDir}"`);
+		mkdirSync(extensionDir, { recursive: true });
+		execSync(`unzip -o "${zipPath}" -d "${extensionDir}"`, { stdio: "pipe" });
+		unlinkSync(zipPath);
+		const files = readdirSync(extensionDir);
+		if (!files.includes("manifest.json")) {
+			const subdirs = files.filter((file) => {
+				try {
+					return readdirSync(join(extensionDir, file)).includes("manifest.json");
+				} catch {
+					return false;
+				}
+			});
+			if (subdirs.length > 0) {
+				const subdir = join(extensionDir, subdirs[0]);
+				execSync(`mv "${subdir}"/* "${extensionDir}"/`);
+				execSync(`rmdir "${subdir}"`);
+			} else {
+				console.error("Error: Extension extraction failed - manifest.json not found.");
+				process.exit(1);
+			}
+		}
+	}
+	console.log("\nSetup complete!");
+	console.log(`  Extension path: ${extensionDir}`);
+	console.log("  Extension: installed\n");
+}
+//#endregion
+//#region src/cli.ts
+function parseArgs(argv) {
+	const args = argv.slice(2);
+	const command = args.find((a) => !a.startsWith("-"));
+	const positional = args.filter((a) => !a.startsWith("-"));
+	const flags = {};
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === "--headless") {
+			flags.headless = true;
+			continue;
+		}
+		if (arg === "--all") {
+			flags.all = true;
+			continue;
+		}
+		if (arg.startsWith("--") && i + 1 < args.length && !args[i + 1].startsWith("-")) {
+			flags[arg.slice(2)] = args[++i];
+			continue;
+		}
+	}
+	return {
+		command,
+		positional: positional.slice(1),
+		flags
+	};
+}
+function getStringFlag(flags, key) {
+	const value = flags[key];
+	return typeof value === "string" ? value : void 0;
+}
+function getNumberFlag(flags, key) {
+	const value = getStringFlag(flags, key);
+	if (!value) return void 0;
+	const parsed = Number(value);
+	return Number.isNaN(parsed) ? void 0 : parsed;
+}
+function showHelp() {
+	console.log(`
+browse-agent - Browser automation skill CLI
+
+Usage: browse-agent <command> [options]
+
+Lifecycle commands:
+  setup                Install Chrome extension
+  launch               Start background service and launch browser
+  connect              Verify connection to running service/browser
+  close                Stop browser and background service
+  clear                Remove local installation data
+  skill <dir>          Copy skill bundle into <dir>/browse-agent
+
+Feature commands (require launch first):
+  navigate <url>       Navigate to URL
+  get-content          Get page content (HTML or text)
+  get-dom <selector>   Query DOM elements
+  evaluate <expr>      Evaluate JavaScript expression
+  inject-script <code> Inject and execute JavaScript
+  inject-css <code>    Inject CSS stylesheet
+  screenshot [mode]    Capture screenshot (visible|fullPage|area)
+  tabs [action] [id]   Manage tabs (list|close|activate)
+
+Options:
+  --browser <name>       Browser: chrome | chromium | edge | brave (default: chrome)
+  --headless             Run in headless mode
+  --port <number>        WebSocket port for browser-agent (default: 9315)
+  --servicePort <number> Local service port (default: 9316)
+  --tabId <id>           Target tab ID (from navigate or tabs list output)
+  --format <type>        Content/screenshot format (text|html / png|jpeg)
+  --property <prop>      DOM property: outerHTML | innerHTML | innerText
+  --all                  Return all DOM matches instead of first only
+  --quality <num>        Screenshot quality (1-100, jpeg only)
+  --timeout <ms>         Connection timeout in ms
+  --help, -h             Show this help
+
+Examples:
+  browse-agent setup
+  browse-agent launch --browser edge --headless
+  browse-agent navigate https://example.com
+  browse-agent get-content --format text
+  browse-agent get-dom "h1" --property innerText
+  browse-agent evaluate "document.title"
+  browse-agent screenshot fullPage --format png
+  browse-agent tabs list
+  browse-agent close
+  browse-agent clear
+  browse-agent skill ~/my-skills
+`.trim());
+}
+function resolveSkillSourceDir() {
+	return join(dirname(fileURLToPath(import.meta.url)), "..", "skill");
+}
+function isNonEmptyDirectory(path) {
+	if (!existsSync(path)) return false;
+	if (!statSync(path).isDirectory()) return true;
+	return readdirSync(path).length > 0;
+}
+async function chooseSkillDestination(baseDir) {
+	let targetName = "browse-agent";
+	while (true) {
+		const targetDir = join(baseDir, targetName);
+		if (!isNonEmptyDirectory(targetDir)) return targetDir;
+		const rl = createInterface({
+			input: process.stdin,
+			output: process.stdout
+		});
+		const action = (await rl.question(`Target directory "${targetDir}" already exists and is not empty. Choose [o]verwrite, [r]ename, or [c]ancel: `)).trim().toLowerCase();
+		if (action === "o" || action === "overwrite") {
+			rmSync(targetDir, {
+				recursive: true,
+				force: true
+			});
+			rl.close();
+			return targetDir;
+		}
+		if (action === "r" || action === "rename") {
+			const nextName = (await rl.question("Enter a new directory name: ")).trim();
+			rl.close();
+			if (!nextName) {
+				console.error("Directory name cannot be empty.");
+				continue;
+			}
+			targetName = nextName;
+			continue;
+		}
+		rl.close();
+		return null;
+	}
+}
+async function installSkill(targetBaseDir) {
+	const sourceDir = resolveSkillSourceDir();
+	if (!existsSync(sourceDir) || !statSync(sourceDir).isDirectory()) throw new Error(`Skill source directory not found: ${sourceDir}`);
+	const targetDir = await chooseSkillDestination(targetBaseDir);
+	if (!targetDir) {
+		console.log("Skill installation canceled.");
+		return;
+	}
+	mkdirSync(targetDir, { recursive: true });
+	cpSync(sourceDir, targetDir, { recursive: true });
+	console.log(JSON.stringify({
+		success: true,
+		source: sourceDir,
+		target: targetDir
+	}, null, 2));
+}
+function sleep(ms) {
+	return new Promise((resolve) => {
+		setTimeout(resolve, ms);
+	});
+}
+async function requestService(servicePort, path, method = "GET", body) {
+	const response = await fetch(`http://127.0.0.1:${servicePort}${path}`, {
+		method,
+		headers: { "Content-Type": "application/json" },
+		body: body === void 0 ? void 0 : JSON.stringify(body)
+	});
+	const payload = await response.json();
+	if (!response.ok) throw new Error(payload.error || `Service request failed: ${method} ${path}`);
+	return payload;
+}
+async function isServiceHealthy(servicePort) {
+	try {
+		await requestService(servicePort, "/health", "GET");
+		return true;
+	} catch {
+		return false;
+	}
+}
+function getRequestedServicePort(flags) {
+	return getNumberFlag(flags, "servicePort") ?? DEFAULT_SERVICE_PORT;
+}
+async function ensureServiceRunning(flags) {
+	const requestedPort = getRequestedServicePort(flags);
+	if (await isServiceHealthy(requestedPort)) return {
+		servicePort: requestedPort,
+		newlyStarted: false
+	};
+	const existing = loadServiceSession();
+	if (existing && await isServiceHealthy(existing.servicePort)) return {
+		servicePort: existing.servicePort,
+		newlyStarted: false
+	};
+	const serviceScript = join(dirname(fileURLToPath(import.meta.url)), "service.js");
+	spawn(process.execPath, [
+		serviceScript,
+		"--service-port",
+		String(requestedPort)
+	], {
+		stdio: "ignore",
+		detached: true
+	}).unref();
+	const deadline = Date.now() + 8e3;
+	while (Date.now() < deadline) {
+		if (await isServiceHealthy(requestedPort)) return {
+			servicePort: requestedPort,
+			newlyStarted: true
+		};
+		await sleep(200);
+	}
+	throw new Error("Failed to start background service.");
+}
+async function getRunningServicePort(flags) {
+	const requestedPort = getRequestedServicePort(flags);
+	if (await isServiceHealthy(requestedPort)) return requestedPort;
+	const existing = loadServiceSession();
+	if (existing && await isServiceHealthy(existing.servicePort)) return existing.servicePort;
+	throw new Error("Service is not running. Run \"browse-agent launch\" first.");
+}
+async function runServiceCommand(flags, name, payload = {}) {
+	const result = await requestService(await getRunningServicePort(flags), "/command", "POST", {
+		name,
+		payload
+	});
+	if (result !== void 0) console.log(JSON.stringify(result, null, 2));
+}
+const { command, positional, flags } = parseArgs(process.argv);
+if (!command || flags.help || flags.h || command === "help") {
+	showHelp();
+	process.exit(0);
+}
+const browser = getStringFlag(flags, "browser");
+const port = getStringFlag(flags, "port");
+const timeout = getStringFlag(flags, "timeout");
+if (browser) process.env.BROWSER = browser;
+if (flags.headless) process.env.HEADLESS = "true";
+if (port) process.env.BROWSE_AGENT_PORT = port;
+if (timeout) process.env.CONNECTION_TIMEOUT = timeout;
+try {
+	switch (command) {
+		case "setup":
+			await setup();
+			break;
+		case "launch": {
+			const service = await ensureServiceRunning(flags);
+			const servicePort = service.servicePort;
+			if (!service.newlyStarted) {
+				const status = await requestService(servicePort, "/status", "GET");
+				if (status.running === true) {
+					console.log(JSON.stringify({
+						servicePort,
+						skipped: "service-and-browser-already-running",
+						...status
+					}, null, 2));
+					break;
+				}
+			}
+			const opts = {};
+			const launchBrowserFlag = getStringFlag(flags, "browser") || "chrome";
+			const launchPort = getNumberFlag(flags, "port");
+			const launchTimeout = getNumberFlag(flags, "timeout");
+			if (launchBrowserFlag) opts.browser = launchBrowserFlag;
+			if (flags.headless) opts.headless = true;
+			if (launchPort !== void 0) opts.port = launchPort;
+			if (launchTimeout !== void 0) opts.timeout = launchTimeout;
+			const result = await requestService(servicePort, "/launch", "POST", opts);
+			console.log(JSON.stringify({
+				servicePort,
+				...result
+			}, null, 2));
+			break;
+		}
+		case "connect": {
+			const servicePort = await getRunningServicePort(flags);
+			const status = await requestService(servicePort, "/status", "GET");
+			console.log(JSON.stringify({
+				servicePort,
+				...status
+			}, null, 2));
+			break;
+		}
+		case "close": {
+			const servicePort = await getRunningServicePort(flags);
+			const closeResult = await requestService(servicePort, "/close", "POST");
+			const shutdownResult = await requestService(servicePort, "/shutdown", "POST");
+			console.log(JSON.stringify({
+				servicePort,
+				...closeResult,
+				...shutdownResult
+			}, null, 2));
+			break;
+		}
+		case "clear":
+			try {
+				await requestService(await getRunningServicePort(flags), "/shutdown", "POST");
+			} catch {}
+			await clear();
+			break;
+		case "skill": {
+			const directory = positional[0];
+			if (!directory) {
+				console.error("Usage: browse-agent skill <directory>");
+				process.exit(1);
+			}
+			const targetBaseDir = directory.startsWith("~") ? join(process.env.HOME || "", directory.replace(/^~[\\/]?/, "")) : resolve(directory);
+			mkdirSync(targetBaseDir, { recursive: true });
+			if (!statSync(targetBaseDir).isDirectory()) throw new Error(`Target path is not a directory: ${targetBaseDir}`);
+			await installSkill(targetBaseDir);
+			break;
+		}
+		case "navigate": {
+			const url = positional[0];
+			if (!url) {
+				console.error("Usage: browse-agent navigate <url>");
+				process.exit(1);
+			}
+			await runServiceCommand(flags, "navigate", { url });
+			break;
+		}
+		case "get-content": {
+			const opts = {};
+			const format = getStringFlag(flags, "format");
+			const tabId = getNumberFlag(flags, "tabId");
+			if (format) opts.format = format;
+			if (tabId !== void 0) opts.tabId = tabId;
+			await runServiceCommand(flags, "get-content", { options: opts });
+			break;
+		}
+		case "get-dom": {
+			const selector = positional[0];
+			if (!selector) {
+				console.error("Usage: browse-agent get-dom <selector>");
+				process.exit(1);
+			}
+			const opts = {};
+			const property = getStringFlag(flags, "property");
+			const tabId = getNumberFlag(flags, "tabId");
+			if (property) opts.property = property;
+			if (flags.all) opts.all = true;
+			if (tabId !== void 0) opts.tabId = tabId;
+			await runServiceCommand(flags, "get-dom", {
+				selector,
+				options: opts
+			});
+			break;
+		}
+		case "evaluate": {
+			const expression = positional[0];
+			if (!expression) {
+				console.error("Usage: browse-agent evaluate <expression>");
+				process.exit(1);
+			}
+			const opts = {};
+			const tabId = getNumberFlag(flags, "tabId");
+			if (tabId !== void 0) opts.tabId = tabId;
+			await runServiceCommand(flags, "evaluate", {
+				expression,
+				options: opts
+			});
+			break;
+		}
+		case "inject-script": {
+			const code = positional[0];
+			if (!code) {
+				console.error("Usage: browse-agent inject-script <code>");
+				process.exit(1);
+			}
+			const opts = {};
+			const tabId = getNumberFlag(flags, "tabId");
+			if (tabId !== void 0) opts.tabId = tabId;
+			await runServiceCommand(flags, "inject-script", {
+				code,
+				options: opts
+			});
+			break;
+		}
+		case "inject-css": {
+			const code = positional[0];
+			if (!code) {
+				console.error("Usage: browse-agent inject-css <code>");
+				process.exit(1);
+			}
+			const opts = {};
+			const tabId = getNumberFlag(flags, "tabId");
+			if (tabId !== void 0) opts.tabId = tabId;
+			await runServiceCommand(flags, "inject-css", {
+				code,
+				options: opts
+			});
+			break;
+		}
+		case "screenshot": {
+			const mode = positional[0] || "visible";
+			const opts = {};
+			const format = getStringFlag(flags, "format");
+			const quality = getNumberFlag(flags, "quality");
+			const tabId = getNumberFlag(flags, "tabId");
+			if (format) opts.format = format;
+			if (quality !== void 0) opts.quality = quality;
+			if (tabId !== void 0) opts.tabId = tabId;
+			await runServiceCommand(flags, "screenshot", {
+				mode,
+				options: opts
+			});
+			break;
+		}
+		case "tabs": {
+			const action = positional[0] || "list";
+			const tabId = positional[1] ? Number(positional[1]) : void 0;
+			switch (action) {
+				case "list":
+					await runServiceCommand(flags, "tabs-list");
+					break;
+				case "close":
+					if (tabId === void 0) {
+						console.error("Usage: browse-agent tabs close <tabId>");
+						process.exit(1);
+					}
+					await runServiceCommand(flags, "tabs-close", { tabId });
+					break;
+				case "activate":
+					if (tabId === void 0) {
+						console.error("Usage: browse-agent tabs activate <tabId>");
+						process.exit(1);
+					}
+					await runServiceCommand(flags, "tabs-activate", { tabId });
+					break;
+				default:
+					console.error(`Unknown tabs action: ${action}. Use: list, close, activate`);
+					process.exit(1);
+			}
+			break;
+		}
+		default:
+			console.error(`Unknown command: ${command}\\nRun "browse-agent --help" for usage.`);
+			process.exit(1);
+	}
+} catch (err) {
+	const message = err instanceof Error ? err.message : String(err);
+	console.error(`[browse-agent] Error: ${message}`);
+	process.exit(1);
+}
+//#endregion
+export {};
+
+//# sourceMappingURL=cli.js.map