fastbrowser_cli 1.0.2 → 1.0.4

package/src/{fastweb_cli → fastbrowser_cli}/libs/http-client.ts

@@ -1,5 +1,5 @@
 // local imports
-import { ToolResponseSchema, type ToolResponse } from '../../fastweb_http_server/libs/tool-schemas.js';
+import { ToolResponseSchema, type ToolResponse } from '../../fastbrowser_httpd/libs/tool-schemas.js';
 
 ///////////////////////////////////////////////////////////////////////////////
 ///////////////////////////////////////////////////////////////////////////////
@@ -10,7 +10,7 @@ import { ToolResponseSchema, type ToolResponse } from '../../fastweb_http_server
 export class HttpClient {
 	static getServerUrl(overrideUrl: string | undefined): string {
 		if (overrideUrl !== undefined && overrideUrl !== '') return overrideUrl;
-		const envUrl = process.env.FASTWEB_SERVER;
+		const envUrl = process.env.FASTBROWSER_SERVER;
 		if (envUrl !== undefined && envUrl !== '') return envUrl;
 		return 'http://localhost:8787';
 	}

package/src/{fastweb_cli → fastbrowser_cli}/libs/server-manager.ts

@@ -16,7 +16,7 @@ type PidFile = {
 	startedAt: string;
 };
 
-const STATE_DIR = Path.join(Os.homedir(), '.fastweb_cli');
+const STATE_DIR = Path.join(Os.homedir(), '.fastbrowser_cli');
 const PID_FILE = Path.join(STATE_DIR, 'server.json');
 const LOG_FILE = Path.join(STATE_DIR, 'server.log');
 
@@ -47,7 +47,7 @@ export class ServerManager {
 		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)`);
+			throw new Error(`fastbrowser server at ${serverUrl} is not reachable and cannot be auto-started (non-local URL)`);
 		}
 		await ServerManager.start(serverUrl);
 	}
@@ -55,7 +55,7 @@ export class ServerManager {
 	static async start(serverUrl: string): Promise<void> {
 		const existing = await ServerManager.status(serverUrl);
 		if (existing === 'running') {
-			console.error(`fastweb server already running at ${serverUrl}`);
+			console.error(`fastbrowser server already running at ${serverUrl}`);
 			return;
 		}
 
@@ -64,7 +64,7 @@ export class ServerManager {
 		}
 
 		const port = ServerManager.parsePort(serverUrl);
-		const entryPath = Path.resolve(__dirname, '..', '..', 'fastweb_http_server', 'fastweb_http_server.ts');
+		const entryPath = Path.resolve(__dirname, '..', '..', 'fastbrowser_httpd', 'fastbrowser_httpd.ts');
 		const packageRoot = Path.resolve(__dirname, '..', '..', '..');
 
 		Fs.mkdirSync(STATE_DIR, { recursive: true });
@@ -81,7 +81,7 @@ export class ServerManager {
 		const pid = child.pid;
 		if (pid === undefined) {
 			Fs.closeSync(logFd);
-			throw new Error('Failed to spawn fastweb-http-server (no pid)');
+			throw new Error('Failed to spawn fastbrowser-httpd (no pid)');
 		}
 
 		const pidFile: PidFile = {
@@ -96,7 +96,7 @@ export class ServerManager {
 			const state = await ServerManager.status(serverUrl);
 			if (state === 'running') {
 				Fs.closeSync(logFd);
-				console.error(`fastweb server started (pid=${pid}, port=${port})`);
+				console.error(`fastbrowser server started (pid=${pid}, port=${port})`);
 				return;
 			}
 			await ServerManager.sleep(500);
@@ -104,7 +104,7 @@ export class ServerManager {
 
 		Fs.closeSync(logFd);
 		const tail = ServerManager.readLogTail(50);
-		throw new Error(`fastweb server did not become healthy within 10s. Log tail:\n${tail}`);
+		throw new Error(`fastbrowser server did not become healthy within 10s. Log tail:\n${tail}`);
 	}
 
 	static async stop(serverUrl: string): Promise<void> {
@@ -157,7 +157,7 @@ export class ServerManager {
 			console.error(`warning: process ${pid} killed but ${serverUrl} still responds to /health`);
 			return;
 		}
-		console.error('fastweb server stopped');
+		console.error('fastbrowser server stopped');
 	}
 
 	private static isLocalUrl(serverUrl: string): boolean {

package/src/{fastweb_http_server/fastweb_http_server.ts → fastbrowser_httpd/fastbrowser_httpd.ts}

@@ -8,7 +8,7 @@ import { Command } from 'commander';
 import express from 'express';
 
 // local imports
-import { McpClient } from '../fastweb_mcp/libs/mcp_client.js';
+import { McpClient } from '../fastbrowser_mcp/libs/mcp_client.js';
 import { Routes } from './libs/routes.js';
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -25,25 +25,25 @@ class MainHelper {
 		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');
+		// Spawn fastbrowser-mcp as a subprocess and hold a persistent MCP client to it.
+		const fastbrowserMcpEntry = Path.resolve(__dirname, '..', 'fastbrowser_mcp', 'fastbrowser_mcp.ts');
 		const mcpClient = new McpClient({
-			name: 'fastweb-http-server',
+			name: 'fastbrowser-httpd',
 			version: '1.0.0',
 			transport: {
 				type: 'stdio',
 				command: 'npx',
-				args: ['tsx', fastwebMcpEntry, 'mcp_server'],
+				args: ['tsx', fastbrowserMcpEntry, 'mcp_server'],
 			},
 		});
 
-		console.error('Connecting to fastweb-mcp ...');
+		console.error('Connecting to fastbrowser-mcp ...');
 		await mcpClient.connect();
 		console.error('MCP client connected');
 
 		if (verbose) {
 			const tools = await mcpClient.listTools();
-			console.error('Tools available in fastweb-mcp:');
+			console.error('Tools available in fastbrowser-mcp:');
 			for (const tool of tools) {
 				console.error(`- ${tool.name}`);
 			}
@@ -54,7 +54,7 @@ class MainHelper {
 		Routes.register(app, mcpClient);
 
 		const server = app.listen(port, () => {
-			console.error(`fastweb-http-server listening on http://localhost:${port}`);
+			console.error(`fastbrowser-httpd listening on http://localhost:${port}`);
 		});
 
 		const shutdown = async (signal: string): Promise<void> => {
@@ -78,8 +78,8 @@ async function main(): Promise<void> {
 	const program = new Command();
 
 	program
-		.name('fastweb-http-server')
-		.description('Persistent HTTP server fronting fastweb-mcp')
+		.name('fastbrowser-httpd')
+		.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 }) => {

package/src/{fastweb_http_server → fastbrowser_httpd}/libs/routes.ts

@@ -2,7 +2,7 @@
 import type { Express, Request, Response } from 'express';
 
 // local imports
-import { McpClient } from '../../fastweb_mcp/libs/mcp_client.js';
+import { McpClient } from '../../fastbrowser_mcp/libs/mcp_client.js';
 import { TOOL_SCHEMAS, ToolResponseSchema } from './tool-schemas.js';
 
 ///////////////////////////////////////////////////////////////////////////////

package/src/{fastweb_http_server → fastbrowser_httpd}/libs/tool-schemas.ts

@@ -2,13 +2,13 @@
 import { z } from 'zod';
 
 // local imports - reuse the authoritative query selector schemas
-import { QuerySelectorsInputSchema, QuerySelectorsFirstInputSchema } from '../../fastweb_mcp/libs/schemas.js';
-export type { QuerySelectorInput, QuerySelectorsInput, QuerySelectorFirstInput, QuerySelectorsFirstInput } from '../../fastweb_mcp/libs/schemas.js';
+import { QuerySelectorsInputSchema, QuerySelectorsFirstInputSchema } from '../../fastbrowser_mcp/libs/schemas.js';
+export type { QuerySelectorInput, QuerySelectorsInput, QuerySelectorFirstInput, QuerySelectorsFirstInput } from '../../fastbrowser_mcp/libs/schemas.js';
 
 ///////////////////////////////////////////////////////////////////////////////
 ///////////////////////////////////////////////////////////////////////////////
 //	Request schemas — one per tool. Shapes mirror what the underlying
-//	fastweb-mcp tools accept. For the proxied chrome-devtools-mcp tools,
+//	fastbrowser-mcp tools accept. For the proxied chrome-devtools-mcp tools,
 //	the shapes come from chrome-devtools-mcp's tool reference.
 ///////////////////////////////////////////////////////////////////////////////
 ///////////////////////////////////////////////////////////////////////////////
@@ -85,7 +85,7 @@ export type ToolResponse = z.infer<typeof ToolResponseSchema>;
 ///////////////////////////////////////////////////////////////////////////////
 
 // The REST route name (snake_case, matches the CLI command) is distinct from
-// the underlying MCP tool name (which may be camelCase for fastweb-mcp's own
+// the underlying MCP tool name (which may be camelCase for fastbrowser-mcp's own
 // tools). `mcpToolName` is what we send over MCP; `routeName` is the URL path.
 export type ToolSchemaEntry = {
 	routeName: string;

package/src/{fastweb_mcp → fastbrowser_mcp}/libs/mcp_proxy.ts

@@ -14,7 +14,7 @@ export class McpProxy {
 
 	constructor() {
 		this._mcpServer = new McpServer({
-			name: "fastweb_mcp",
+			name: "fastbrowser_mcp",
 			version: "1.0.0",
 		});
 	}

package/src/{fastweb_mcp → fastbrowser_mcp}/libs/schemas.ts

@@ -4,7 +4,7 @@ import { z } from 'zod';
 ///////////////////////////////////////////////////////////////////////////////
 ///////////////////////////////////////////////////////////////////////////////
 //	Authoritative query selector schemas — shared between the MCP server
-//	and the HTTP/CLI layer. Kept out of the fastweb_mcp.ts entrypoint so
+//	and the HTTP/CLI layer. Kept out of the fastbrowser_mcp.ts entrypoint so
 //	importing the schemas does not execute the CLI's top-level `main()`.
 ///////////////////////////////////////////////////////////////////////////////
 ///////////////////////////////////////////////////////////////////////////////

package/tmp/.claude/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npx fastbrowser_cli *)"
+    ]
+  }
+}

package/tmp/.claude/skills/fastbrowser/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: fastbrowser
+description: >
+  Control a live browser from the command line: navigate, click, fill forms, and query the accessibility tree with CSS-like selectors. Lighter alternative to Chrome DevTools MCP or Puppeteer. Triggers on: navigate/click/fill actions, page snapshots, or mentions of fastbrowser.
+---
+
+# fastbrowser Skill
+
+`fastbrowser-cli` is a command-line client for the FastWeb HTTP server, which keeps a persistent
+MCP connection to a Chrome browser alive so commands incur minimal latency. Each command
+maps 1-to-1 to a FastWeb tool and returns the tool's response on stdout.
+
+## Invocation
+
+Run the CLI directly via `tsx`:
+
+```bash
+npx fastbrowser_cli <command> [flags]
+```
+
+## Typical Workflow
+
+1. **Query** the accessibility tree for specific nodes: `query_selectors` (first match per selector) or `query_selectors_all` (every match per selector).
+2. **Act** on an element by its accessibility selector: `click`, `fill_form`, `press_keys`. The selector can be a direct uid reference (e.g. `#1_42`, fastest path) or any CSS-like selector (e.g. `button[name="Submit"]`), which is resolved to a uid internally.
+
+Snapshot output looks like:
+
+```
+uid=1_0 RootWebArea "Example Domain" url="https://example.com/"
+  uid=1_1 heading "Example Domain" level="1"
+  uid=1_2 link "More information..." url="https://www.iana.org/..."
+```
+
+## Page Management
+
+```bash
+# List all open browser pages
+npx fastbrowser_cli list_pages
+
+# Open a new page at a URL
+npx fastbrowser_cli new_page --url https://example.com
+
+# Close a page by its numeric id
+npx fastbrowser_cli close_page --page-id 1
+
+# Navigate the current page to a URL
+npx fastbrowser_cli navigate_page --url https://example.com
+```
+
+
+## Selector Language
+
+The selector syntax is modelled on CSS selectors, adapted for accessibility tree structures.
+
+### Role selector
+
+Matches nodes by their accessibility role.
+
+```
+button
+link
+comboxbox
+searchbox
+heading
+WebArea
+```
+
+### Universal selector
+
+Matches any node.
+
+```
+*
+```
+
+### UID selector
+
+Matches a node by its exact unique identifier.
+
+```
+#4
+#1_3
+```
+
+### Attribute selectors
+
+Attribute selectors match values inside `node.attributes`. The special virtual attribute `name` maps to `node.name`.
+
+| Syntax | Semantics |
+|--------|-----------|
+| `[attr]` | attribute is present |
+| `[attr="value"]` | exact match |
+| `[attr^="prefix"]` | starts with |
+| `[attr$="suffix"]` | ends with |
+| `[attr*="sub"]` | contains substring |
+
+```
+link[href]
+button[disabled="true"]
+link[href^="https"]
+link[href$=".com"]
+link[href*="example"]
+heading[name="Welcome"]
+link[name="Click \"here\""]
+```
+
+### Combinators
+
+| Syntax | Semantics |
+|--------|-----------|
+| `A B` | B is a descendant of A (any depth) |
+| `A > B` | B is a direct child of A |
+| `A, B` | union — matches A or B |
+
+```
+WebArea link
+main > button
+heading, button
+RootWebArea > link[href^="https"]
+```
+
+### Examples
+
+Sample accessibility tree:
+
+```
+uid=1 WebArea "Main Page"
+  uid=2 main
+    uid=3 heading "Welcome"
+    uid=4 link "Click here" href="https://example.com"
+    uid=5 button "Submit" disabled="true"
+  uid=6 navigation
+    uid=7 link "Home" href="/"
+    uid=8 link "About" href="/about"
+```
+
+Example queries on it:
+- `link` matches all the links (uid=4, uid=7, uid=8)
+- 'navigation > link' matches only the links that are direct children of navigation (uid=7, uid=8)
+- `link[href^="https"]` matches links with an external href (uid=4)
+- `button[name="Submit"]` matches the submit button by name (uid=5)
+- `*[disabled="true"]` matches any disabled element (uid=5)
+- `heading, button` matches both headings and buttons in one query (uid=3, uid=5)
+- `#7` matches a node by its UID (uid=7)
+
+## Inspection
+
+- `query_selectors` and `query_selectors_all` are the most efficient way to get specific elements or data from the page. Use them instead of `take_snapshot` whenever possible.
+- Prefer `query_selectors` when you only need the first match per selector (cheaper, less output); use `query_selectors_all` when you need every match or want to cap with `--limit`.
+
+```bash
+# Query the accessibility tree returning the FIRST match per selector (--selector is repeatable)
+npx fastbrowser_cli query_selectors --selector "button" --selector "link"
+
+# Exclude ancestor nodes from the result
+npx fastbrowser_cli query_selectors --selector 'heading[level="1"]' --no-with-ancestors
+
+# Per-selector control over withAncestors via JSON
+npx fastbrowser_cli query_selectors \
+  --selectors-json '[{"selector":"button","withAncestors":true},{"selector":"link","withAncestors":false}]'
+
+# Query the accessibility tree returning ALL matches per selector (--selector is repeatable)
+npx fastbrowser_cli query_selectors_all --selector "button" --selector "link" --limit 5
+
+# Exclude ancestor nodes from the result
+npx fastbrowser_cli query_selectors_all --selector 'heading[level="1"]' --no-with-ancestors
+
+# Per-selector control over limit / withAncestors via JSON
+npx fastbrowser_cli query_selectors_all \
+  --selectors-json '[{"selector":"button","limit":3,"withAncestors":true},{"selector":"link","limit":0,"withAncestors":false}]'
+
+# Take an accessibility-tree full page snapshot of the current page - very expensive, prefer targeted queries when possible
+npx fastbrowser_cli take_snapshot
+```
+
+## Interaction
+
+```bash
+# Click by a direct uid reference (fast path - no accessibility-tree lookup)
+npx fastbrowser_cli click --selector "#1_42"
+
+# Click by any CSS-like selector - resolved to a uid internally
+npx fastbrowser_cli click -s 'button[name="Submit"]'
+
+# Fill a single form field - selector can be a uid (#1_7) or any CSS-like selector
+npx fastbrowser_cli fill_form -s 'textbox[name="Email"]' --value "hello@example.com"
+
+# Press a comma-separated sequence of keys (literals and named keys both work)
+npx fastbrowser_cli press_keys --keys "Tab, Tab, Enter"
+npx fastbrowser_cli press_keys --keys "Hello, Tab, Enter"
+```
+
+## Command Reference
+
+| Command | Purpose | Required flags |
+|---------|---------|----------------|
+| `list_pages` | List open browser pages | — |
+| `new_page` | Open a new page at a URL | `--url` |
+| `close_page` | Close a page by id | `--page-id` |
+| `navigate_page` | Navigate current page to a URL | `--url` |
+| `take_snapshot` | Dump the accessibility tree of the whole page - very expensive, prefer targeted queries (`query_selectors` / `query_selectors_all`) when possible | — |
+| `query_selectors` | Query a11y tree by CSS-like selector, returning the first match per selector | `--selector` or `--selectors-json` |
+| `query_selectors_all` | Query a11y tree by CSS-like selector, returning every match per selector | `--selector` or `--selectors-json` |
+| `click` | Click an element by accessibility selector | `--selector` / `-s` |
+| `fill_form` | Fill a form field by accessibility selector | `--selector` / `-s`, `--value` |
+| `press_keys` | Press a comma-separated key sequence | `--keys` |
+| `server start` | Start the HTTP server daemon | — |
+| `server status` | Report server running/stopped | — |
+| `server stop` | Stop the HTTP server | — |
+
+## Output & Errors
+
+Tool output is written to **stdout** — one line per response content part. On failure the
+CLI writes `fastbrowser-cli error: <message>` to **stderr** and exits with code 1.