fastbrowser_cli 1.0.2

package/src/fastweb_cli/fastweb_cli.ts

@@ -0,0 +1,306 @@
+#!/usr/bin/env node
+
+// npm imports
+import { Command } from 'commander';
+
+// local imports
+import { HttpClient } from './libs/http-client.js';
+import { ServerManager } from './libs/server-manager.js';
+import type { QuerySelectorInput, QuerySelectorFirstInput, QuerySelectorsAllRequest, QuerySelectorRequest } from '../fastweb_http_server/libs/tool-schemas.js';
+
+
+///////////////////////////////////////////////////////////////////////////////
+///////////////////////////////////////////////////////////////////////////////
+//
+///////////////////////////////////////////////////////////////////////////////
+///////////////////////////////////////////////////////////////////////////////
+
+type GlobalOpts = {
+	server?: string;
+	autostart?: boolean;
+};
+
+function getServerFromCmd(cmd: Command): string {
+	const globalOpts = cmd.optsWithGlobals<GlobalOpts>();
+	return HttpClient.getServerUrl(globalOpts.server);
+}
+
+function getAutostartFromCmd(cmd: Command): boolean {
+	const globalOpts = cmd.optsWithGlobals<GlobalOpts>();
+	return globalOpts.autostart !== false;
+}
+
+async function runTool(cmd: Command, routeName: string, body: unknown): Promise<void> {
+	const server = getServerFromCmd(cmd);
+	try {
+		if (getAutostartFromCmd(cmd) === true) {
+			await ServerManager.ensureRunning(server);
+		}
+		const response = await HttpClient.postTool(server, routeName, body);
+		HttpClient.printResponse(response);
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		console.error(`fastweb-cli error: ${message}`);
+		process.exit(1);
+	}
+}
+
+///////////////////////////////////////////////////////////////////////////////
+///////////////////////////////////////////////////////////////////////////////
+//
+///////////////////////////////////////////////////////////////////////////////
+///////////////////////////////////////////////////////////////////////////////
+
+function buildQuerySelectorsBody(opts: {
+	selector?: string[];
+	limit?: string;
+	withAncestors?: boolean;
+	selectorsJson?: string;
+}): QuerySelectorsAllRequest {
+	if (opts.selectorsJson !== undefined && opts.selectorsJson !== '') {
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(opts.selectorsJson);
+		} catch (err) {
+			throw new Error(`--selectors-json is not valid JSON: ${(err as Error).message}`);
+		}
+		if (Array.isArray(parsed) === false) {
+			throw new Error('--selectors-json must be a JSON array');
+		}
+		return { selectors: parsed as QuerySelectorInput[] };
+	}
+
+	const selectorList = opts.selector ?? [];
+	if (selectorList.length === 0) {
+		throw new Error('At least one --selector or --selectors-json is required');
+	}
+
+	const limit = opts.limit === undefined ? 0 : Number.parseInt(opts.limit, 10);
+	if (Number.isNaN(limit) === true) {
+		throw new Error(`Invalid --limit: ${opts.limit}`);
+	}
+	const withAncestors = opts.withAncestors !== false;
+
+	const selectors: QuerySelectorInput[] = selectorList.map((selector) => ({
+		selector,
+		limit,
+		withAncestors,
+	}));
+	return { selectors };
+}
+
+function buildQuerySelectorFirstBody(opts: {
+	selector?: string[];
+	withAncestors?: boolean;
+	selectorsJson?: string;
+}): QuerySelectorRequest {
+	if (opts.selectorsJson !== undefined && opts.selectorsJson !== '') {
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(opts.selectorsJson);
+		} catch (err) {
+			throw new Error(`--selectors-json is not valid JSON: ${(err as Error).message}`);
+		}
+		if (Array.isArray(parsed) === false) {
+			throw new Error('--selectors-json must be a JSON array');
+		}
+		return { selectors: parsed as QuerySelectorFirstInput[] };
+	}
+
+	const selectorList = opts.selector ?? [];
+	if (selectorList.length === 0) {
+		throw new Error('At least one --selector or --selectors-json is required');
+	}
+
+	const withAncestors = opts.withAncestors !== false;
+
+	const selectors: QuerySelectorFirstInput[] = selectorList.map((selector) => ({
+		selector,
+		withAncestors,
+	}));
+	return { selectors };
+}
+
+///////////////////////////////////////////////////////////////////////////////
+///////////////////////////////////////////////////////////////////////////////
+//
+///////////////////////////////////////////////////////////////////////////////
+///////////////////////////////////////////////////////////////////////////////
+
+async function main(): Promise<void> {
+	const program = new Command();
+	program
+		.name('fastweb-cli')
+		.description('CLI client for fastweb-http-server2')
+		.option('--server <url>', 'fastweb-http-server URL (default: env FASTWEB_SERVER or http://localhost:8787)')
+		.option('--autostart', 'Auto-start the server before a command if it is not running', true)
+		.option('--no-autostart', 'Do not auto-start the server before a command');
+
+	const serverCmd = program
+		.command('server')
+		.description('Manage the fastweb HTTP server');
+
+	serverCmd
+		.command('start')
+		.description('Start the fastweb HTTP server as a detached daemon')
+		.action(async (_opts, cmd: Command) => {
+			const server = getServerFromCmd(cmd);
+			try {
+				await ServerManager.start(server);
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				console.error(`fastweb-cli error: ${message}`);
+				process.exit(1);
+			}
+		});
+
+	serverCmd
+		.command('stop')
+		.description('Stop the fastweb HTTP server')
+		.action(async (_opts, cmd: Command) => {
+			const server = getServerFromCmd(cmd);
+			try {
+				await ServerManager.stop(server);
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				console.error(`fastweb-cli error: ${message}`);
+				process.exit(1);
+			}
+		});
+
+	serverCmd
+		.command('status')
+		.description('Report whether the fastweb HTTP server is running')
+		.action(async (_opts, cmd: Command) => {
+			const server = getServerFromCmd(cmd);
+			const state = await ServerManager.status(server);
+			console.log(`fastweb server at ${server}: ${state}`);
+			if (state === 'stopped') process.exit(1);
+		});
+
+	program
+		.command('list_pages')
+		.description('List all open browser pages')
+		.action(async (_opts, cmd: Command) => {
+			await runTool(cmd, 'list_pages', {});
+		});
+
+	program
+		.command('new_page')
+		.description('Open a new browser page')
+		.requiredOption('--url <url>', 'URL to open')
+		.action(async (opts: { url: string }, cmd: Command) => {
+			await runTool(cmd, 'new_page', { url: opts.url });
+		});
+
+	program
+		.command('close_page')
+		.description('Close a page by its id')
+		.requiredOption('--page-id <number>', 'The page id to close')
+		.action(async (opts: { pageId: string }, cmd: Command) => {
+			const pageId = Number.parseInt(opts.pageId, 10);
+			if (Number.isNaN(pageId) === true) {
+				console.error(`Invalid --page-id: ${opts.pageId}`);
+				process.exit(1);
+			}
+			await runTool(cmd, 'close_page', { pageId });
+		});
+
+	program
+		.command('navigate_page')
+		.description('Navigate the current page to a URL')
+		.requiredOption('--url <url>', 'URL to navigate to')
+		.action(async (opts: { url: string }, cmd: Command) => {
+			await runTool(cmd, 'navigate_page', { url: opts.url });
+		});
+
+	program
+		.command('click')
+		.description('Click an element by its accessibility selector')
+		.requiredOption('-s, --selector <selector>', 'Accessibility selector (e.g. "#1_3" or \'button[name="Submit"]\')')
+		.action(async (opts: { selector: string }, cmd: Command) => {
+			await runTool(cmd, 'click', { selector: opts.selector });
+		});
+
+	program
+		.command('fill_form')
+		.description('Fill a form field by its accessibility selector')
+		.requiredOption('-s, --selector <selector>', 'Accessibility selector (e.g. "#1_3" or \'textbox[name="Email"]\')')
+		.requiredOption('--value <value>', 'Value to fill')
+		.action(async (opts: { selector: string; value: string }, cmd: Command) => {
+			await runTool(cmd, 'fill_form', {
+				elements: [{ selector: opts.selector, value: opts.value }],
+			});
+		});
+
+	program
+		.command('query_selectors_all')
+		.description('Query the accessibility tree with CSS-like selectors')
+		.option('-s, --selector <selector>', 'CSS-like selector (repeatable)', (value: string, prev: string[] = []) => {
+			prev.push(value);
+			return prev;
+		})
+		.option('--limit <number>', 'Max nodes per selector (0 = unlimited)', '0')
+		.option('--with-ancestors', 'Include ancestor nodes', true)
+		.option('--no-with-ancestors', 'Exclude ancestor nodes')
+		.option('--selectors-json <json>', 'JSON array of {selector,limit,withAncestors} for per-selector control')
+		.action(async (opts: {
+			selector?: string[];
+			limit?: string;
+			withAncestors?: boolean;
+			selectorsJson?: string;
+		}, cmd: Command) => {
+			let body: QuerySelectorsAllRequest;
+			try {
+				body = buildQuerySelectorsBody(opts);
+			} catch (err) {
+				console.error(`fastweb-cli error: ${(err as Error).message}`);
+				process.exit(1);
+			}
+			await runTool(cmd, 'query_selectors_all', body);
+		});
+
+	program
+		.command('query_selectors')
+		.description('Query the accessibility tree with CSS-like selectors and, for each, return the first matching node')
+		.option('-s, --selector <selector>', 'CSS-like selector (repeatable)', (value: string, prev: string[] = []) => {
+			prev.push(value);
+			return prev;
+		})
+		.option('--with-ancestors', 'Include ancestor nodes', true)
+		.option('--no-with-ancestors', 'Exclude ancestor nodes')
+		.option('--selectors-json <json>', 'JSON array of {selector,withAncestors} for per-selector control')
+		.action(async (opts: {
+			selector?: string[];
+			withAncestors?: boolean;
+			selectorsJson?: string;
+		}, cmd: Command) => {
+			let body: QuerySelectorRequest;
+			try {
+				body = buildQuerySelectorFirstBody(opts);
+			} catch (err) {
+				console.error(`fastweb-cli error: ${(err as Error).message}`);
+				process.exit(1);
+			}
+			await runTool(cmd, 'query_selectors', body);
+		});
+
+	program
+		.command('take_snapshot')
+		.description('Take an accessibility-tree snapshot of the current page')
+		.action(async (_opts, cmd: Command) => {
+			await runTool(cmd, 'take_snapshot', {});
+		});
+
+	program
+		.command('press_keys')
+		.description('Press a sequence of keys')
+		.requiredOption('--keys <keys>', "Comma-separated keys. E.g. 'Hello, Tab, Enter'")
+		.action(async (opts: { keys: string }, cmd: Command) => {
+			await runTool(cmd, 'press_keys', { keys: opts.keys });
+		});
+
+	await program.parseAsync(process.argv);
+}
+
+void main();

package/src/fastweb_cli/libs/http-client.ts

@@ -0,0 +1,50 @@
+// local imports
+import { ToolResponseSchema, type ToolResponse } from '../../fastweb_http_server/libs/tool-schemas.js';
+
+///////////////////////////////////////////////////////////////////////////////
+///////////////////////////////////////////////////////////////////////////////
+//
+///////////////////////////////////////////////////////////////////////////////
+///////////////////////////////////////////////////////////////////////////////
+
+export class HttpClient {
+	static getServerUrl(overrideUrl: string | undefined): string {
+		if (overrideUrl !== undefined && overrideUrl !== '') return overrideUrl;
+		const envUrl = process.env.FASTWEB_SERVER;
+		if (envUrl !== undefined && envUrl !== '') return envUrl;
+		return 'http://localhost:8787';
+	}
+
+	static async postTool(serverUrl: string, routeName: string, body: unknown): Promise<ToolResponse> {
+		const url = `${serverUrl.replace(/\/+$/, '')}/tools/${routeName}`;
+		const response = await fetch(url, {
+			method: 'POST',
+			headers: { 'content-type': 'application/json' },
+			body: JSON.stringify(body ?? {}),
+		});
+
+		const responseText = await response.text();
+		if (response.ok === false) {
+			throw new Error(`HTTP ${response.status} ${response.statusText}: ${responseText}`);
+		}
+
+		let parsedJson: unknown;
+		try {
+			parsedJson = JSON.parse(responseText);
+		} catch (err) {
+			throw new Error(`Invalid JSON from server: ${responseText}`);
+		}
+
+		const parsed = ToolResponseSchema.safeParse(parsedJson);
+		if (parsed.success === false) {
+			throw new Error(`Unexpected response shape: ${JSON.stringify(parsed.error.flatten())}`);
+		}
+		return parsed.data;
+	}
+
+	static printResponse(response: ToolResponse): void {
+		for (const part of response.content) {
+			console.log(part.text);
+		}
+	}
+}

package/src/fastweb_cli/libs/server-manager.ts

@@ -0,0 +1,210 @@
+// node imports
+import Fs from 'node:fs';
+import Os from 'node:os';
+import Path from 'node:path';
+import { spawn } from 'node:child_process';
+
+///////////////////////////////////////////////////////////////////////////////
+///////////////////////////////////////////////////////////////////////////////
+//
+///////////////////////////////////////////////////////////////////////////////
+///////////////////////////////////////////////////////////////////////////////
+
+type PidFile = {
+	pid: number;
+	port: number;
+	startedAt: string;
+};
+
+const STATE_DIR = Path.join(Os.homedir(), '.fastweb_cli');
+const PID_FILE = Path.join(STATE_DIR, 'server.json');
+const LOG_FILE = Path.join(STATE_DIR, 'server.log');
+
+///////////////////////////////////////////////////////////////////////////////
+///////////////////////////////////////////////////////////////////////////////
+//
+///////////////////////////////////////////////////////////////////////////////
+///////////////////////////////////////////////////////////////////////////////
+
+export class ServerManager {
+	static async status(serverUrl: string): Promise<'running' | 'stopped'> {
+		const base = serverUrl.replace(/\/+$/, '');
+		try {
+			const response = await fetch(`${base}/health`, {
+				method: 'GET',
+				signal: AbortSignal.timeout(500),
+			});
+			if (response.ok === false) return 'stopped';
+			const payload = await response.json() as { ok?: unknown };
+			return payload.ok === true ? 'running' : 'stopped';
+		} catch {
+			return 'stopped';
+		}
+	}
+
+	static async ensureRunning(serverUrl: string): Promise<void> {
+		const state = await ServerManager.status(serverUrl);
+		if (state === 'running') return;
+
+		if (ServerManager.isLocalUrl(serverUrl) === false) {
+			throw new Error(`fastweb server at ${serverUrl} is not reachable and cannot be auto-started (non-local URL)`);
+		}
+		await ServerManager.start(serverUrl);
+	}
+
+	static async start(serverUrl: string): Promise<void> {
+		const existing = await ServerManager.status(serverUrl);
+		if (existing === 'running') {
+			console.error(`fastweb server already running at ${serverUrl}`);
+			return;
+		}
+
+		if (ServerManager.isLocalUrl(serverUrl) === false) {
+			throw new Error(`Refusing to start: ${serverUrl} is not a local URL`);
+		}
+
+		const port = ServerManager.parsePort(serverUrl);
+		const entryPath = Path.resolve(__dirname, '..', '..', 'fastweb_http_server', 'fastweb_http_server.ts');
+		const packageRoot = Path.resolve(__dirname, '..', '..', '..');
+
+		Fs.mkdirSync(STATE_DIR, { recursive: true });
+		const logFd = Fs.openSync(LOG_FILE, 'a');
+
+		const child = spawn('npx', ['tsx', entryPath, '--port', String(port)], {
+			detached: true,
+			stdio: ['ignore', logFd, logFd],
+			cwd: packageRoot,
+			env: process.env,
+		});
+		child.unref();
+
+		const pid = child.pid;
+		if (pid === undefined) {
+			Fs.closeSync(logFd);
+			throw new Error('Failed to spawn fastweb-http-server (no pid)');
+		}
+
+		const pidFile: PidFile = {
+			pid,
+			port,
+			startedAt: new Date().toISOString(),
+		};
+		Fs.writeFileSync(PID_FILE, JSON.stringify(pidFile, null, 2));
+
+		const deadline = Date.now() + 10_000;
+		while (Date.now() < deadline) {
+			const state = await ServerManager.status(serverUrl);
+			if (state === 'running') {
+				Fs.closeSync(logFd);
+				console.error(`fastweb server started (pid=${pid}, port=${port})`);
+				return;
+			}
+			await ServerManager.sleep(500);
+		}
+
+		Fs.closeSync(logFd);
+		const tail = ServerManager.readLogTail(50);
+		throw new Error(`fastweb server did not become healthy within 10s. Log tail:\n${tail}`);
+	}
+
+	static async stop(serverUrl: string): Promise<void> {
+		if (Fs.existsSync(PID_FILE) === false) {
+			console.error('no server pid file; nothing to stop');
+			return;
+		}
+
+		let pidFile: PidFile;
+		try {
+			const raw = Fs.readFileSync(PID_FILE, 'utf8');
+			pidFile = JSON.parse(raw) as PidFile;
+		} catch (err) {
+			throw new Error(`Failed to read pid file ${PID_FILE}: ${(err as Error).message}`);
+		}
+
+		const pid = pidFile.pid;
+		try {
+			process.kill(pid, 'SIGTERM');
+		} catch (err) {
+			const code = (err as NodeJS.ErrnoException).code;
+			if (code !== 'ESRCH') {
+				throw err;
+			}
+		}
+
+		const deadline = Date.now() + 5_000;
+		while (Date.now() < deadline) {
+			if (ServerManager.isAlive(pid) === false) break;
+			await ServerManager.sleep(200);
+		}
+
+		if (ServerManager.isAlive(pid) === true) {
+			try {
+				process.kill(pid, 'SIGKILL');
+			} catch {
+				// best effort
+			}
+		}
+
+		try {
+			Fs.unlinkSync(PID_FILE);
+		} catch {
+			// best effort
+		}
+
+		// Best-effort: ensure the HTTP server is actually down from the caller's perspective.
+		const state = await ServerManager.status(serverUrl);
+		if (state === 'running') {
+			console.error(`warning: process ${pid} killed but ${serverUrl} still responds to /health`);
+			return;
+		}
+		console.error('fastweb server stopped');
+	}
+
+	private static isLocalUrl(serverUrl: string): boolean {
+		try {
+			const parsed = new URL(serverUrl);
+			const host = parsed.hostname;
+			return host === 'localhost' || host === '127.0.0.1' || host === '::1' || host === '0.0.0.0';
+		} catch {
+			return false;
+		}
+	}
+
+	private static parsePort(serverUrl: string): number {
+		try {
+			const parsed = new URL(serverUrl);
+			if (parsed.port !== '') {
+				const port = Number.parseInt(parsed.port, 10);
+				if (Number.isNaN(port) === false) return port;
+			}
+		} catch {
+			// fall through
+		}
+		return 8787;
+	}
+
+	private static isAlive(pid: number): boolean {
+		try {
+			process.kill(pid, 0);
+			return true;
+		} catch (err) {
+			const code = (err as NodeJS.ErrnoException).code;
+			if (code === 'EPERM') return true;
+			return false;
+		}
+	}
+
+	private static readLogTail(maxLines: number): string {
+		try {
+			const content = Fs.readFileSync(LOG_FILE, 'utf8');
+			const lines = content.split('\n');
+			return lines.slice(Math.max(0, lines.length - maxLines)).join('\n');
+		} catch {
+			return '(log unavailable)';
+		}
+	}
+
+	private static sleep(ms: number): Promise<void> {
+		return new Promise((resolve) => setTimeout(resolve, ms));
+	}
+}

package/src/fastweb_http_server/fastweb_http_server.ts

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+
+// node imports
+import Path from 'node:path';
+
+// npm imports
+import { Command } from 'commander';
+import express from 'express';
+
+// local imports
+import { McpClient } from '../fastweb_mcp/libs/mcp_client.js';
+import { Routes } from './libs/routes.js';
+
+///////////////////////////////////////////////////////////////////////////////
+///////////////////////////////////////////////////////////////////////////////
+//
+///////////////////////////////////////////////////////////////////////////////
+///////////////////////////////////////////////////////////////////////////////
+
+class MainHelper {
+	static async commandStart({
+		port,
+		verbose = false,
+	}: {
+		port: number;
+		verbose?: boolean;
+	}): Promise<void> {
+		// Spawn fastweb-mcp as a subprocess and hold a persistent MCP client to it.
+		const fastwebMcpEntry = Path.resolve(__dirname, '..', 'fastweb_mcp', 'fastweb_mcp.ts');
+		const mcpClient = new McpClient({
+			name: 'fastweb-http-server',
+			version: '1.0.0',
+			transport: {
+				type: 'stdio',
+				command: 'npx',
+				args: ['tsx', fastwebMcpEntry, 'mcp_server'],
+			},
+		});
+
+		console.error('Connecting to fastweb-mcp ...');
+		await mcpClient.connect();
+		console.error('MCP client connected');
+
+		if (verbose) {
+			const tools = await mcpClient.listTools();
+			console.error('Tools available in fastweb-mcp:');
+			for (const tool of tools) {
+				console.error(`- ${tool.name}`);
+			}
+		}
+
+		const app = express();
+		app.use(express.json({ limit: '2mb' }));
+		Routes.register(app, mcpClient);
+
+		const server = app.listen(port, () => {
+			console.error(`fastweb-http-server listening on http://localhost:${port}`);
+		});
+
+		const shutdown = async (signal: string): Promise<void> => {
+			console.error(`Received ${signal}, shutting down ...`);
+			server.close();
+			await mcpClient.close();
+			process.exit(0);
+		};
+		process.on('SIGINT', () => { void shutdown('SIGINT'); });
+		process.on('SIGTERM', () => { void shutdown('SIGTERM'); });
+	}
+}
+
+///////////////////////////////////////////////////////////////////////////////
+///////////////////////////////////////////////////////////////////////////////
+//
+///////////////////////////////////////////////////////////////////////////////
+///////////////////////////////////////////////////////////////////////////////
+
+async function main(): Promise<void> {
+	const program = new Command();
+
+	program
+		.name('fastweb-http-server')
+		.description('Persistent HTTP server fronting fastweb-mcp')
+		.option('-p, --port <number>', 'Port to listen on', '8787')
+		.option('-v, --verbose', 'Enable verbose logging')
+		.action(async (opts: { port: string; verbose?: boolean }) => {
+			const port = Number.parseInt(opts.port, 10);
+			if (Number.isNaN(port) === true) {
+				console.error(`Invalid --port: ${opts.port}`);
+				process.exit(1);
+			}
+			await MainHelper.commandStart({ port, verbose: opts.verbose });
+		});
+
+	await program.parseAsync(process.argv);
+}
+
+void main();