fastbrowser_cli 1.0.22 → 1.0.25

package/src/fastbrowser_cli/fastbrowser_cli.ts

@@ -1,20 +1,22 @@
 #!/usr/bin/env node
 
-import fs from 'node:fs';
-import path from 'node:path';
+import Fs from 'node:fs';
+import Path from 'node:path';
 
-import { Command, CommanderError } from 'commander';
+import { Command, CommanderError, Option } from 'commander';
 import stringArgv from 'string-argv';
 
 import { HttpClient } from './libs/http-client.js';
 import { ServerManager } from './libs/server-manager.js';
-import type { QuerySelectorInput, QuerySelectorFirstInput, QuerySelectorsAllRequest, QuerySelectorRequest } from '../fastbrowser_httpd/libs/tool-schemas.js';
+import { QueryBuilder } from './libs/query-builder.js';
+import type { FastBrowserMcpTarget } from '../fastbrowser_mcp/fastbrowser_types.js';
 
 ///////////////////////////////////////////////////////////////////////////////
 
 type GlobalOpts = {
 	server?: string;
 	autostart?: boolean;
+	mcpTarget?: FastBrowserMcpTarget;
 };
 
 class SilentExitError extends Error {
@@ -38,113 +40,59 @@ class MainHelper {
 
 	/**
 	 * Determine whether to auto-start the server based on command options (default: true)
-	 * @param cmd 
-	 * @returns 
+	 * @param cmd
+	 * @returns
 	 */
 	static getAutostartFromCmd(cmd: Command): boolean {
 		const globalOpts = cmd.optsWithGlobals<GlobalOpts>();
 		return globalOpts.autostart !== false;
 	}
 
+	static getMcpTargetFromCmd(cmd: Command): FastBrowserMcpTarget {
+		const globalOpts = cmd.optsWithGlobals<GlobalOpts>();
+		return globalOpts.mcpTarget ?? 'playwright';
+	}
+
 	/**
 	 * Run a tool by making an HTTP request to the server, with optional auto-start
-	 * @param cmd 
-	 * @param routeName 
-	 * @param body 
+	 * @param cmd
+	 * @param routeName
+	 * @param body
 	 */
 	static async runTool(cmd: Command, routeName: string, body: unknown): Promise<void> {
 		const server = MainHelper.getServerUrlFromCmd(cmd);
+		const mcpTarget = MainHelper.getMcpTargetFromCmd(cmd);
 		if (MainHelper.getAutostartFromCmd(cmd) === true) {
-			await ServerManager.ensureRunning(server);
+			await ServerManager.ensureRunning(server, mcpTarget);
 		}
 		const response = await HttpClient.postTool(server, routeName, body);
 		HttpClient.printResponse(response);
 	}
 
-	static 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 };
-	}
-
-	static 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');
+	static readPackageVersion(): string {
+		const packageJsonPath = Path.resolve(import.meta.dirname, '../../package.json');
+		const raw = Fs.readFileSync(packageJsonPath, 'utf-8');
+		const parsed = JSON.parse(raw) as { version?: string };
+		if (typeof parsed.version !== 'string') {
+			throw new Error(`fastbrowser-cli: missing "version" in ${packageJsonPath}`);
 		}
-
-		const withAncestors = opts.withAncestors !== false;
-
-		const selectors: QuerySelectorFirstInput[] = selectorList.map((selector) => ({
-			selector,
-			withAncestors,
-		}));
-		return { selectors };
+		return parsed.version;
 	}
 
 	static async runInstall(skillFolder: string): Promise<void> {
-		const sourceSkillsDir = path.resolve(import.meta.dirname, '../../skills');
-		const targetSkillsDir = path.resolve(skillFolder, 'skills');
+		const sourceSkillsDir = Path.resolve(import.meta.dirname, '../../skills');
+		const targetSkillsDir = Path.resolve(skillFolder, 'skills');
 		try {
-			const entries = await fs.promises.readdir(sourceSkillsDir, { withFileTypes: true });
+			const entries = await Fs.promises.readdir(sourceSkillsDir, { withFileTypes: true });
 			const skillDirs = entries.filter((entry) => entry.isDirectory() === true);
 			if (skillDirs.length === 0) {
 				console.error(`fastbrowser-cli error: no skills found in ${sourceSkillsDir}`);
 				process.exit(1);
 			}
 			for (const skillDir of skillDirs) {
-				const sourceDir = path.join(sourceSkillsDir, skillDir.name);
-				const targetDir = path.join(targetSkillsDir, skillDir.name);
-				await fs.promises.cp(sourceDir, targetDir, { recursive: true });
+				const sourceDir = Path.join(sourceSkillsDir, skillDir.name);
+				const targetDir = Path.join(targetSkillsDir, skillDir.name);
+				await Fs.promises.cp(sourceDir, targetDir, { recursive: true });
 				console.log(`Installed ${skillDir.name} skill at ${targetDir}`);
 			}
 		} catch (err) {
@@ -159,7 +107,7 @@ class MainHelper {
 			return inlineScript;
 		}
 		if (file !== undefined && file !== '') {
-			return await fs.promises.readFile(file, 'utf-8');
+			return await Fs.promises.readFile(file, 'utf-8');
 		}
 		if (process.stdin.isTTY === true) {
 			throw new Error('batch: no input. Provide a file path, --script, or pipe commands on stdin.');
@@ -185,6 +133,9 @@ class MainHelper {
 		if (globalOpts.autostart === false) {
 			globalFlags.push('--no-autostart');
 		}
+		if (globalOpts.mcpTarget !== undefined) {
+			globalFlags.push('--mcp-target', globalOpts.mcpTarget);
+		}
 
 		const lines = source.split('\n');
 		let ok = 0;
@@ -232,9 +183,15 @@ async function main(): Promise<void> {
 	program
 		.name('fastbrowser-cli')
 		.description('CLI client for fastbrowser')
+		.version(MainHelper.readPackageVersion(), '-V, --version', 'Print the fastbrowser-cli version')
 		.option('--server <url>', 'fastbrowser-httpd URL (default: env FASTBROWSER_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');
+		.option('--no-autostart', 'Do not auto-start the server before a command')
+		.addOption(
+			new Option('--mcp-target <target>', 'browser backend (default: $FASTBROWSER_MCP_TARGET or playwright)')
+				.choices(['chrome_devtools', 'playwright'])
+				.default(process.env.FASTBROWSER_MCP_TARGET ?? 'playwright'),
+		);
 
 	///////////////////////////////////////////////////////////////////////////////
 	///////////////////////////////////////////////////////////////////////////////
@@ -251,7 +208,8 @@ async function main(): Promise<void> {
 		.description('Start the fastbrowser HTTP server as a detached daemon')
 		.action(async (_opts, cmd: Command) => {
 			const serverUrl = MainHelper.getServerUrlFromCmd(cmd);
-			await ServerManager.start(serverUrl);
+			const mcpTarget = MainHelper.getMcpTargetFromCmd(cmd);
+			await ServerManager.start(serverUrl, mcpTarget);
 		});
 
 	serverCmd
@@ -268,7 +226,8 @@ async function main(): Promise<void> {
 		.action(async (_opts, cmd: Command) => {
 			const serverUrl = MainHelper.getServerUrlFromCmd(cmd);
 			const serverStatus = await ServerManager.status(serverUrl);
-			console.log(`fastbrowser server at ${serverUrl}: ${serverStatus}`);
+			const targetSuffix = serverStatus.mcpTarget !== undefined ? ` (mcpTarget=${serverStatus.mcpTarget})` : '';
+			console.log(`fastbrowser server at ${serverUrl}: ${serverStatus.state}${targetSuffix}`);
 		});
 
 	serverCmd
@@ -276,8 +235,9 @@ async function main(): Promise<void> {
 		.description('Restart the fastbrowser HTTP server')
 		.action(async (_opts, cmd: Command) => {
 			const serverUrl = MainHelper.getServerUrlFromCmd(cmd);
+			const mcpTarget = MainHelper.getMcpTargetFromCmd(cmd);
 			await ServerManager.stop(serverUrl);
-			await ServerManager.start(serverUrl);
+			await ServerManager.start(serverUrl, mcpTarget);
 		});
 	///////////////////////////////////////////////////////////////////////////////
 	///////////////////////////////////////////////////////////////////////////////
@@ -356,7 +316,7 @@ async function main(): Promise<void> {
 			withAncestors?: boolean;
 			selectorsJson?: string;
 		}, cmd: Command) => {
-			const body = MainHelper.buildQuerySelectorsBody(opts);
+			const body = QueryBuilder.buildQuerySelectorsBody(opts);
 			await MainHelper.runTool(cmd, 'query_selectors_all', body);
 		});
 
@@ -375,7 +335,7 @@ async function main(): Promise<void> {
 			withAncestors?: boolean;
 			selectorsJson?: string;
 		}, cmd: Command) => {
-			const body = MainHelper.buildQuerySelectorFirstBody(opts);
+			const body = QueryBuilder.buildQuerySelectorFirstBody(opts);
 			await MainHelper.runTool(cmd, 'query_selectors', body);
 		});
 

package/src/fastbrowser_cli/libs/query-builder.ts

@@ -0,0 +1,89 @@
+// local imports
+import type {
+	QuerySelectorInput,
+	QuerySelectorFirstInput,
+	QuerySelectorsAllRequest,
+	QuerySelectorRequest,
+} from '../../fastbrowser_httpd/libs/tool-schemas.js';
+
+///////////////////////////////////////////////////////////////////////////////
+///////////////////////////////////////////////////////////////////////////////
+//
+///////////////////////////////////////////////////////////////////////////////
+///////////////////////////////////////////////////////////////////////////////
+
+export type BuildQuerySelectorsAllOpts = {
+	selector?: string[];
+	limit?: string;
+	withAncestors?: boolean;
+	selectorsJson?: string;
+};
+
+export type BuildQuerySelectorFirstOpts = {
+	selector?: string[];
+	withAncestors?: boolean;
+	selectorsJson?: string;
+};
+
+export class QueryBuilder {
+	static buildQuerySelectorsBody(opts: BuildQuerySelectorsAllOpts): 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 };
+	}
+
+	static buildQuerySelectorFirstBody(opts: BuildQuerySelectorFirstOpts): 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 };
+	}
+}

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

@@ -4,6 +4,9 @@ import Os from 'node:os';
 import Path from 'node:path';
 import { spawn } from 'node:child_process';
 
+// local imports
+import type { FastBrowserMcpTarget } from '../../fastbrowser_mcp/fastbrowser_types.js';
+
 ///////////////////////////////////////////////////////////////////////////////
 ///////////////////////////////////////////////////////////////////////////////
 //
@@ -13,9 +16,15 @@ import { spawn } from 'node:child_process';
 type PidFile = {
 	pid: number;
 	port: number;
+	mcpTarget?: FastBrowserMcpTarget;
 	startedAt: string;
 };
 
+export type ServerStatus = {
+	state: 'running' | 'stopped';
+	mcpTarget?: FastBrowserMcpTarget;
+};
+
 const STATE_DIRNAME = Path.join(Os.homedir(), '.fastbrowser_cli');
 const PID_FILENAME = Path.join(STATE_DIRNAME, 'server.json');
 const LOG_FILENAME = Path.join(STATE_DIRNAME, 'server.log');
@@ -27,34 +36,52 @@ const LOG_FILENAME = Path.join(STATE_DIRNAME, 'server.log');
 ///////////////////////////////////////////////////////////////////////////////
 
 export class ServerManager {
-	static async status(serverUrl: string): Promise<'running' | 'stopped'> {
+	static async status(serverUrl: string): Promise<ServerStatus> {
 		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';
+			if (response.ok === false) return { state: 'stopped' };
+			const payload = await response.json() as { ok?: unknown; mcpTarget?: unknown };
+			if (payload.ok !== true) return { state: 'stopped' };
+			const mcpTarget = payload.mcpTarget === 'chrome_devtools' || payload.mcpTarget === 'playwright'
+				? payload.mcpTarget
+				: undefined;
+			return { state: 'running', mcpTarget };
 		} catch {
-			return 'stopped';
+			return { state: 'stopped' };
 		}
 	}
 
-	static async ensureRunning(serverUrl: string): Promise<void> {
-		const state = await ServerManager.status(serverUrl);
-		if (state === 'running') return;
+	static async ensureRunning(serverUrl: string, mcpTarget: FastBrowserMcpTarget): Promise<void> {
+		const info = await ServerManager.status(serverUrl);
+		if (info.state === 'running') {
+			if (info.mcpTarget !== undefined && info.mcpTarget !== mcpTarget) {
+				throw new Error(
+					`fastbrowser server already running with mcpTarget=${info.mcpTarget}. ` +
+					`To switch to ${mcpTarget}, run: fastbrowser-cli --mcp-target ${mcpTarget} server restart`,
+				);
+			}
+			return;
+		}
 
 		if (ServerManager.isLocalUrl(serverUrl) === false) {
 			throw new Error(`fastbrowser server at ${serverUrl} is not reachable and cannot be auto-started (non-local URL)`);
 		}
-		await ServerManager.start(serverUrl);
+		await ServerManager.start(serverUrl, mcpTarget);
 	}
 
-	static async start(serverUrl: string): Promise<void> {
+	static async start(serverUrl: string, mcpTarget: FastBrowserMcpTarget): Promise<void> {
 		const existing = await ServerManager.status(serverUrl);
-		if (existing === 'running') {
+		if (existing.state === 'running') {
+			if (existing.mcpTarget !== undefined && existing.mcpTarget !== mcpTarget) {
+				throw new Error(
+					`fastbrowser server already running with mcpTarget=${existing.mcpTarget}. ` +
+					`Stop it first: fastbrowser-cli server stop`,
+				);
+			}
 			console.error(`fastbrowser server already running at ${serverUrl}`);
 			return;
 		}
@@ -67,7 +94,7 @@ export class ServerManager {
 		let entryPath = Path.resolve(import.meta.dirname, '..', '..', 'fastbrowser_httpd', 'fastbrowser_httpd.js');
 		const port = ServerManager.parsePort(serverUrl);
 		let spawnCommand = process.execPath;
-		let spawnArgs = [entryPath, '--port', String(port)]
+		let spawnArgs = [entryPath, '--port', String(port), '--mcp-target', mcpTarget]
 		// trick to work without being in `./dist'
 		if (entryPath.includes('/dist/') === false) {
 			spawnCommand = '/usr/local/bin/npx';
@@ -96,16 +123,17 @@ export class ServerManager {
 		const pidFile: PidFile = {
 			pid,
 			port,
+			mcpTarget,
 			startedAt: new Date().toISOString(),
 		};
 		Fs.writeFileSync(PID_FILENAME, JSON.stringify(pidFile, null, 2));
 
 		const deadline = Date.now() + 10_000;
 		while (Date.now() < deadline) {
-			const state = await ServerManager.status(serverUrl);
-			if (state === 'running') {
+			const info = await ServerManager.status(serverUrl);
+			if (info.state === 'running') {
 				Fs.closeSync(logFd);
-				console.error(`fastbrowser server started (pid=${pid}, port=${port})`);
+				console.error(`fastbrowser server started (pid=${pid}, port=${port}, mcpTarget=${mcpTarget})`);
 				return;
 			}
 			await ServerManager.sleep(500);
@@ -161,8 +189,8 @@ export class ServerManager {
 		}
 
 		// Best-effort: ensure the HTTP server is actually down from the caller's perspective.
-		const state = await ServerManager.status(serverUrl);
-		if (state === 'running') {
+		const info = await ServerManager.status(serverUrl);
+		if (info.state === 'running') {
 			console.error(`warning: process ${pid} killed but ${serverUrl} still responds to /health`);
 			return;
 		}

package/src/fastbrowser_httpd/fastbrowser_httpd.ts

@@ -4,11 +4,12 @@
 import Path from 'node:path';
 
 // npm imports
-import { Command } from 'commander';
+import { Command, Option } from 'commander';
 import express from 'express';
 
 // local imports
 import { McpMyClient } from '../fastbrowser_mcp/libs/mcp_my_client.js';
+import type { FastBrowserMcpTarget } from '../fastbrowser_mcp/fastbrowser_types.js';
 import { Routes } from './libs/routes.js';
 
 
@@ -21,15 +22,17 @@ import { Routes } from './libs/routes.js';
 class MainHelper {
 	static async commandStart({
 		port,
+		mcpTarget,
 		verbose = false,
 	}: {
 		port: number;
+		mcpTarget: FastBrowserMcpTarget;
 		verbose?: boolean;
 	}): Promise<void> {
 		// Spawn fastbrowser-mcp as a subprocess and hold a persistent MCP client to it.
 		const fastbrowserMcpEntry = Path.resolve(import.meta.dirname, '..', 'fastbrowser_mcp', 'fastbrowser_mcp.js');
 		let mcpServerCommand = process.execPath;
-		let mcpServerArgs = [fastbrowserMcpEntry, 'mcp_server'];
+		let mcpServerArgs = [fastbrowserMcpEntry, 'mcp_server', '--mcp_target', mcpTarget];
 		// trick to work without being in `./dist'
 		if (fastbrowserMcpEntry.includes('/dist/') === false) {
 			mcpServerCommand = '/usr/local/bin/npx';
@@ -40,7 +43,7 @@ class MainHelper {
 		const mcpClient = new McpMyClient({
 			name: 'fastbrowser-httpd',
 			version: '1.0.0',
-			mcpTarget: 'chrome_devtools',
+			mcpTarget,
 			transport: {
 				type: 'stdio',
 				command: mcpServerCommand,
@@ -62,7 +65,7 @@ class MainHelper {
 
 		const app = express();
 		app.use(express.json({ limit: '2mb' }));
-		Routes.register(app, mcpClient);
+		Routes.register(app, mcpClient, mcpTarget);
 
 		const server = app.listen(port, () => {
 			console.error(`fastbrowser-httpd listening on http://localhost:${port}`);
@@ -93,13 +96,18 @@ async function main(): Promise<void> {
 		.description('Persistent HTTP server fronting fastbrowser-mcp')
 		.option('-p, --port <number>', 'Port to listen on', '8787')
 		.option('-v, --verbose', 'Enable verbose logging')
-		.action(async (opts: { port: string; verbose?: boolean }) => {
+		.addOption(
+			new Option('--mcp-target <target>', 'browser backend (default: $FASTBROWSER_MCP_TARGET or playwright)')
+				.choices(['chrome_devtools', 'playwright'])
+				.default(process.env.FASTBROWSER_MCP_TARGET ?? 'playwright'),
+		)
+		.action(async (opts: { port: string; verbose?: boolean; mcpTarget: FastBrowserMcpTarget }) => {
 			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 MainHelper.commandStart({ port, mcpTarget: opts.mcpTarget, verbose: opts.verbose });
 		});
 
 	await program.parseAsync(process.argv);

package/src/fastbrowser_httpd/libs/routes.ts

@@ -3,6 +3,7 @@ import type { Express, Request, Response } from 'express';
 
 // local imports
 import { McpMyClient } from '../../fastbrowser_mcp/libs/mcp_my_client.js';
+import type { FastBrowserMcpTarget } from '../../fastbrowser_mcp/fastbrowser_types.js';
 import { TOOL_SCHEMAS, ToolResponseSchema } from './tool-schemas.js';
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -12,9 +13,9 @@ import { TOOL_SCHEMAS, ToolResponseSchema } from './tool-schemas.js';
 ///////////////////////////////////////////////////////////////////////////////
 
 export class Routes {
-	static register(app: Express, mcpClient: McpMyClient): void {
+	static register(app: Express, mcpClient: McpMyClient, mcpTarget: FastBrowserMcpTarget): void {
 		app.get('/health', (_req: Request, res: Response) => {
-			res.json({ ok: true });
+			res.json({ ok: true, mcpTarget });
 		});
 
 		for (const entry of TOOL_SCHEMAS) {

package/tests/http-client.test.ts

@@ -0,0 +1,63 @@
+// node imports
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+
+// local imports
+import { HttpClient } from '../src/fastbrowser_cli/libs/http-client.js';
+
+///////////////////////////////////////////////////////////////////////////////
+///////////////////////////////////////////////////////////////////////////////
+//
+///////////////////////////////////////////////////////////////////////////////
+///////////////////////////////////////////////////////////////////////////////
+
+describe('HttpClient.getServerUrl', () => {
+	let originalEnv: string | undefined;
+
+	beforeEach(() => {
+		originalEnv = process.env['FASTBROWSER_SERVER'];
+		delete process.env['FASTBROWSER_SERVER'];
+	});
+
+	afterEach(() => {
+		if (originalEnv !== undefined) {
+			process.env['FASTBROWSER_SERVER'] = originalEnv;
+		} else {
+			delete process.env['FASTBROWSER_SERVER'];
+		}
+	});
+
+	it('returns the override URL when one is provided', () => {
+		const url = HttpClient.getServerUrl('http://example.com:1234');
+		assert.equal(url, 'http://example.com:1234');
+	});
+
+	it('prefers the override URL over the env var', () => {
+		process.env['FASTBROWSER_SERVER'] = 'http://from-env:9999';
+		const url = HttpClient.getServerUrl('http://override:1111');
+		assert.equal(url, 'http://override:1111');
+	});
+
+	it('falls back to FASTBROWSER_SERVER env var when override is undefined', () => {
+		process.env['FASTBROWSER_SERVER'] = 'http://from-env:9999';
+		const url = HttpClient.getServerUrl(undefined);
+		assert.equal(url, 'http://from-env:9999');
+	});
+
+	it('falls back to FASTBROWSER_SERVER env var when override is empty string', () => {
+		process.env['FASTBROWSER_SERVER'] = 'http://from-env:9999';
+		const url = HttpClient.getServerUrl('');
+		assert.equal(url, 'http://from-env:9999');
+	});
+
+	it('ignores empty FASTBROWSER_SERVER env var', () => {
+		process.env['FASTBROWSER_SERVER'] = '';
+		const url = HttpClient.getServerUrl(undefined);
+		assert.equal(url, 'http://localhost:8787');
+	});
+
+	it('returns the default URL when nothing is set', () => {
+		const url = HttpClient.getServerUrl(undefined);
+		assert.equal(url, 'http://localhost:8787');
+	});
+});