fastbrowser_cli 1.0.35 → 1.0.39

package/examples/whatsapp/whatsapp.sh

@@ -0,0 +1,10 @@
+#!/bin/env bash
+
+# restart the server
+NODE_OPTIONS='' NPM_CONFIG_LOGLEVEL=silent npm run dev:cli -- server restart
+
+# navigate to whatsapp web
+NODE_OPTIONS='' NPM_CONFIG_LOGLEVEL=silent npm run dev:cli -- navigate_page --url https://web.whatsapp.com/
+
+# List all conversations in the chat list
+NODE_OPTIONS='' NPM_CONFIG_LOGLEVEL=silent npm run dev:cli -- query_selectors -s 'grid[name="Chat list"] > row' -a

package/listitem

@@ -0,0 +1,7 @@
+
+> fastbrowser_cli@1.0.37 dev:cli
+> npx tsx ./src/fastbrowser_cli/fastbrowser_cli.ts click -s list[name=Conversation List] heading[name^=Eric Defiez]
+
+Expected ] at column 22:
+  list[name=Conversation List]
+                        ^

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "fastbrowser_cli",
-  "version": "1.0.35",
+  "version": "1.0.39",
   "description": "A CLI tool for FastBrowser, providing commands to interact with the FastBrowser MCP (Model Context Protocol) server and perform various browser automation tasks.",
   "main": "dist/fastbrowser_cli/fastbrowser_cli.js",
   "bin": {
     "fastbrowser_cli": "./dist/fastbrowser_cli/fastbrowser_cli.js",
-    "fastbrowser_mcp": "./dist/fastbrowser_mcp/fastbrowser_mcp.js"
+    "fastbrowser_mcp": "./dist/fastbrowser_mcp/fastbrowser_mcp.js",
+    "linkedin_cli": "./dist/contribs/linkedin_cli/src/cli.js",
+    "twitter_cli": "./dist/contribs/twitter_cli/src/cli.js"
   },
   "keywords": [],
   "author": "",
@@ -30,7 +32,7 @@
     "typescript": "^6.0.3",
     "zod": "^4.3.6",
     "zod-from-json-schema": "^0.5.2",
-    "a11y_parse": "^1.0.5"
+    "a11y_parse": "^1.0.8"
   },
   "devDependencies": {
     "@types/express": "^4.17.21",
@@ -47,6 +49,8 @@
     "inspect:playwright:chrome": "npx @modelcontextprotocol/inspector npx @playwright/mcp@latest --cdp-endpoint=chrome",
     "inspect:playwright:cdp_endpoint": "npx @modelcontextprotocol/inspector npx @playwright/mcp@latest --cdp-endpoint=http://localhost:9222",
     "inspect:playwright:extension": "npx @modelcontextprotocol/inspector npx @playwright/mcp@latest --extension",
+    "contribs:linkedin:profile": "npx tsx ./src/contribs/linkedin_cli/src/cli.ts profile jeromeetienne",
+    "contribs:twitter:profile": "npx tsx ./src/contribs/twitter_cli/src/cli.ts profile jerome_etienne",
     "build": "tsc -p tsconfig.build.json",
     "prepublish:check": "test -z \"$(git status --porcelain)\" || (echo 'Working tree dirty — commit or stash first' && exit 1)",
     "version:bump": "npm version patch --no-git-tag-version && git add package.json && git commit -m \"feat: bump version in fastbrowser_cli package.json\"",

package/skills/fastbrowser/SKILL.md

@@ -15,7 +15,7 @@ maps 1-to-1 to a FastBrowser tool and returns the tool's response on stdout.
 Run the CLI directly via `tsx`:
 
 ```bash
-npx fastbrowser_cli <command> [flags]
+npx fastbrowser_cli@latest <command> [flags]
 ```
 
 ## Typical Workflow
@@ -35,16 +35,41 @@ uid=1_0 RootWebArea "Example Domain" url="https://example.com/"
 
 ```bash
 # List all open browser pages
-npx fastbrowser_cli list_pages
+npx fastbrowser_cli@latest list_pages
 
 # Open a new page at a URL
-npx fastbrowser_cli new_page --url https://example.com
+npx fastbrowser_cli@latest new_page --url https://example.com
 
 # Close a page by its numeric id
-npx fastbrowser_cli close_page --page-id 1
+npx fastbrowser_cli@latest close_page --page-id 1
 
 # Navigate the current page to a URL
-npx fastbrowser_cli navigate_page --url https://example.com
+npx fastbrowser_cli@latest navigate_page --url https://example.com
+
+# Restart the daemon - run this if pages opened by the bridge were closed manually
+# and the MCP connection has broken
+npx fastbrowser_cli@latest server restart
+```
+
+
+## Configuration
+
+Global flags accepted by every command:
+
+| Flag / env | Purpose | Default |
+|---|---|---|
+| `--server <url>` / `FASTBROWSER_SERVER` | URL of the `fastbrowser_httpd` daemon | `http://localhost:8787` |
+| `--autostart` / `--no-autostart` | Auto-start the daemon if it is not already running | `--autostart` |
+| `--mcp-target <target>` / `FASTBROWSER_MCP_TARGET` | Browser backend: `playwright` or `chrome_devtools` | `playwright` |
+
+The daemon binds to one backend at startup. If it is already running with a different backend, the CLI refuses the request and prints the exact restart command to switch.
+
+```bash
+# Use chrome-devtools-mcp for one command
+npx fastbrowser_cli@latest --mcp-target chrome_devtools list_pages
+
+# Switch the running daemon to a different backend
+npx fastbrowser_cli@latest --mcp-target chrome_devtools server restart
 ```
 
 
@@ -59,7 +84,7 @@ Matches nodes by their accessibility role.
 ```
 button
 link
-comboxbox
+combobox
 searchbox
 heading
 WebArea
@@ -93,6 +118,7 @@ Attribute selectors match values inside `node.attributes`. The special virtual a
 | `[attr^="prefix"]` | starts with |
 | `[attr$="suffix"]` | ends with |
 | `[attr*="sub"]` | contains substring |
+| `[attr~="word"]` | contains `word` as a whole space-separated word |
 
 ```
 link[href]
@@ -100,6 +126,7 @@ button[disabled="true"]
 link[href^="https"]
 link[href$=".com"]
 link[href*="example"]
+button[name~="Submit"]
 heading[name="Welcome"]
 link[name="Click \"here\""]
 ```
@@ -110,15 +137,56 @@ link[name="Click \"here\""]
 |--------|-----------|
 | `A B` | B is a descendant of A (any depth) |
 | `A > B` | B is a direct child of A |
+| `A + B` | B is the immediately following sibling of A |
+| `A ~ B` | B is any following sibling of A |
 | `A, B` | union — matches A or B |
 
 ```
 WebArea link
 main > button
+label + textbox
+link ~ link
 heading, button
 RootWebArea > link[href^="https"]
 ```
 
+### Positional pseudo-classes
+
+Narrow a match by position within the parent's children array. Indexing is 1-based; the root node never matches a positional pseudo-class.
+
+| Syntax | Semantics |
+|--------|-----------|
+| `:first-child` | node is the first child of its parent |
+| `:last-child` | node is the last child of its parent |
+| `:nth-child(n)` | node is the nth child (1-based) |
+
+```
+link:first-child
+button:last-child
+menuitem:nth-child(2)
+```
+
+### Functional pseudo-classes
+
+Take a comma-separated selector list inside parentheses. The argument list itself supports the full selector language and may be nested.
+
+| Syntax | Semantics |
+|--------|-----------|
+| `:is(s1, s2, …)` | node matches any selector in the list |
+| `:where(s1, s2, …)` | alias of `:is()` (no specificity in this engine) |
+| `:not(s1, s2, …)` | node matches none of the selectors |
+| `:has(s1, s2, …)` | node has a descendant matching any selector |
+
+`:has()` walks descendants of the candidate node (excluding the node itself). Relative leading combinators (e.g. `:has(> link)`) are not supported.
+
+```
+:is(heading, button)
+link:not(:first-child)
+*:has(button)
+*:not(:has(link))
+main > *:not(button)
+```
+
 ### Examples
 
 Sample accessibility tree:
@@ -136,58 +204,74 @@ uid=1 WebArea "Main Page"
 
 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)
+- `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)
+- `link:first-child` matches uid=4 and uid=7 (first child of `main` and `navigation`)
+- `link + button` matches uid=5 (button immediately after a link)
+- `:is(heading, button)` is equivalent to `heading, button` (uid=3, uid=5)
+- `link:not([href^="https"])` matches the relative-href links (uid=7, uid=8)
+- `*:has(button)` matches ancestors of a button (uid=1, uid=2)
 
 ## Inspection
 
 - `query_selectors` is the most efficient way to get specific elements or data from the page. Use it instead of `take_snapshot` whenever possible.
 - By default, `query_selectors` returns the first match per selector (cheaper, less output). Pass `-a, --all` when you need every match — pair it with `--limit` to cap results per selector.
+- Use `--wa, --with-ancestors` to include each match's ancestor chain in the result, and `--wc, --with-children` to include the descendant subtree of each match.
 
 ```bash
 # Query the accessibility tree returning the FIRST match per selector (--selector is repeatable)
-npx fastbrowser_cli query_selectors --selector "button" --selector "link"
+npx fastbrowser_cli@latest query_selectors --selector "button" --selector "link"
 
-# Exclude ancestor nodes from the result
-npx fastbrowser_cli query_selectors --selector 'heading[level="1"]' --no-with-ancestors
+# Include ancestor nodes in the result
+npx fastbrowser_cli@latest query_selectors --selector 'heading[level="1"]' --with-ancestors
 
-# Per-selector control over withAncestors via JSON
-npx fastbrowser_cli query_selectors \
-  --selectors-json '[{"selector":"button","withAncestors":true},{"selector":"link","withAncestors":false}]'
+# Include the descendant subtree of each match
+npx fastbrowser_cli@latest query_selectors --selector 'main' --with-children
+
+# Per-selector control over withAncestors / withChildren via JSON
+npx fastbrowser_cli@latest query_selectors \
+  --selectors-json '[{"selector":"button","withAncestors":true},{"selector":"link","withChildren":true}]'
 
 # Pass --all to return every match per selector; --limit caps results per selector (0 = unlimited)
-npx fastbrowser_cli query_selectors --all --selector "button" --selector "link" --limit 5
+npx fastbrowser_cli@latest 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
+# Include ancestor nodes in the result
+npx fastbrowser_cli@latest query_selectors --all --selector 'heading[level="1"]' --with-ancestors
 
-# Per-selector control over limit / withAncestors via JSON (with --all)
-npx fastbrowser_cli query_selectors --all \
-  --selectors-json '[{"selector":"button","limit":3,"withAncestors":true},{"selector":"link","limit":0,"withAncestors":false}]'
+# Per-selector control over limit / withAncestors / withChildren via JSON (with --all)
+npx fastbrowser_cli@latest query_selectors --all \
+  --selectors-json '[{"selector":"button","limit":3,"withAncestors":true},{"selector":"link","limit":0,"withChildren":true}]'
 
 # Take an accessibility-tree full page snapshot of the current page - very expensive, prefer targeted queries when possible
-npx fastbrowser_cli take_snapshot
+npx fastbrowser_cli@latest take_snapshot
 ```
 
 ## Interaction
 
 ```bash
 # Click by a direct uid reference (fast path - no accessibility-tree lookup)
-npx fastbrowser_cli click --selector "#1_42"
+npx fastbrowser_cli@latest click --selector "#1_42"
 
 # Click by any CSS-like selector - resolved to a uid internally
-npx fastbrowser_cli click -s 'button[name="Submit"]'
+npx fastbrowser_cli@latest 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"]' -v "hello@example.com"
+npx fastbrowser_cli@latest fill_form -s 'textbox[name="Email"]' -v "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"
+npx fastbrowser_cli@latest press_keys --keys "Tab, Tab, Enter"
+npx fastbrowser_cli@latest press_keys --keys "Hello, Tab, Enter"
+
+# Evaluate a JS function in the page context and get its JSON-able return value
+npx fastbrowser_cli@latest evaluate_script --script 'function() { return { title: document.title, url: location.href }; }'
+
+# Same, reading the function from a file or piped stdin
+npx fastbrowser_cli@latest evaluate_script ./my_script.js
+echo 'function() { return document.querySelectorAll("a").length; }' | npx fastbrowser_cli@latest evaluate_script
 ```
 
 ## Batch Execution
@@ -204,16 +288,16 @@ By default, the batch stops at the first failing line (shell `set -e` semantics)
 
 ```bash
 # From a file
-npx fastbrowser_cli batch ./demo.fbs
+npx fastbrowser_cli@latest batch ./demo.fbs
 
 # Piped on stdin
-cat demo.fbs | npx fastbrowser_cli batch
+cat demo.fbs | npx fastbrowser_cli@latest batch
 
 # Inline script
-npx fastbrowser_cli batch --script $'press_keys --keys "Enter"\nclick -s \'button[name^="Tout effacer"]\''
+npx fastbrowser_cli@latest batch --script $'press_keys --keys "Enter"\nclick -s \'button[name^="Tout effacer"]\''
 
 # Continue through failures
-npx fastbrowser_cli batch --no-stop-on-error ./demo.fbs
+npx fastbrowser_cli@latest batch --no-stop-on-error ./demo.fbs
 ```
 
 Example `demo.fbs`:
@@ -238,10 +322,13 @@ press_keys --keys "Tab, Enter"
 | `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` |
+| `evaluate_script` | Run a JS function in the page context and return its JSON-able result | one of: `<file>`, `--script`, or piped stdin |
 | `batch` | Run multiple commands from a file, piped stdin, or `--script` inline | one of: `<file>`, `--script`, or piped stdin |
+| `install [skill-folder]` | Install bundled skills into `<skill-folder>/skills/` (default: `.`) | — |
 | `server start` | Start the HTTP server daemon | — |
 | `server status` | Report server running/stopped | — |
 | `server stop` | Stop the HTTP server | — |
+| `server restart` | Restart the HTTP server (re-establishes the MCP connection) | — |
 
 ## Output & Errors
 

package/src/contribs/_shared/fastbrowser_helper.ts

@@ -0,0 +1,49 @@
+import { execSync } from 'node:child_process';
+
+const __dirname = new URL('.', import.meta.url).pathname;
+
+export class FastBrowserHelper {
+	static async run(command: string): Promise<string> {
+		// const fullCommand = `npx fastbrowser_cli ${command}`;
+		const fullCommand = `npx tsx ${__dirname}../../fastbrowser_cli/fastbrowser_cli.ts  ${command}`;
+		console.error(`Running command: ${fullCommand}`);
+		return execSync(fullCommand, { encoding: 'utf8' });
+	}
+
+	static async navigatePage(url: string): Promise<void> {
+		await FastBrowserHelper.run(`navigate_page --url '${url}'`);
+	}
+
+	static async fillForm(selector: string, value: string): Promise<void> {
+		await FastBrowserHelper.run(`fill_form --selector '${selector}' --value '${value}'`);
+	}
+
+	static async pressKeys(keys: string): Promise<void> {
+		await FastBrowserHelper.run(`press_keys --keys '${keys}'`);
+	}
+
+	static async click(selector: string): Promise<void> {
+		await FastBrowserHelper.run(`click -s '${selector}'`);
+	}
+
+	static async querySelectorsAll(selector: string, limit: number): Promise<string> {
+		return await FastBrowserHelper.run(`query_selectors --all --selector '${selector}' --limit ${limit}`);
+	}
+
+	static async querySelectorsAllWithChildren(selector: string, limit: number): Promise<string> {
+		return await FastBrowserHelper.run(`query_selectors --all --selector '${selector}' --limit ${limit} --with-ancestors --with-children`);
+	}
+
+	static async takeSnapshot(): Promise<string> {
+		return await FastBrowserHelper.run('take_snapshot');
+	}
+
+	static async querySelectors(selector: string, withAncestors = true): Promise<string> {
+		const flag = withAncestors === false ? ' --no-with-ancestors' : '';
+		return await FastBrowserHelper.run(`query_selectors --selector '${selector}'${flag}`);
+	}
+
+	static async evaluateScript(functionText: string): Promise<string> {
+		return await FastBrowserHelper.run(`evaluate_script --script "${functionText}"`);
+	}
+}

package/src/contribs/linkedin_cli/README.md

@@ -0,0 +1,80 @@
+# linkedin_cli
+
+Command-line tool to interact with LinkedIn through a real browser session, driven by `fastbrowser_cli`.
+
+It lets you create posts on the feed and manage direct-message conversations (list, read, send) from the terminal.
+
+## Requirements
+
+- A running `fastbrowser_cli` session already authenticated on `linkedin.com`.
+- The `_shared/fastbrowser_helper.ts` wrapper located in the sibling `contribs/_shared/` folder.
+
+## Usage
+
+```bash
+npx tsx ./src/cli.ts <command> [args]
+```
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `post <content>` | Create a post on the LinkedIn feed. |
+| `dm_page` | Navigate to the LinkedIn messaging page. Run this first before any `dm_*` command. |
+| `dm_list` | List the names of people you have conversations with. |
+| `dm_send <target_user> <message>` | Send a message in an existing conversation with `target_user`. |
+| `dm_thread <target_user>` | Print the message thread of a conversation with `target_user`. |
+| `profile <slug>` | Export a LinkedIn profile by slug (the path component of `/in/<slug>/`). Use `-f json` for JSON output. |
+
+`target_user` is matched against the conversation heading via a prefix match (e.g. `"Jerome"` matches `"Jerome Etienne"`).
+
+### Examples
+
+Create a post:
+
+```bash
+npx tsx ./src/cli.ts post "Hello LinkedIn from the CLI"
+```
+
+List your conversations:
+
+```bash
+npx tsx ./src/cli.ts dm_page
+npx tsx ./src/cli.ts dm_list
+```
+
+Read a thread:
+
+```bash
+npx tsx ./src/cli.ts dm_thread "Jerome Etienne"
+```
+
+Output is one message per line in the form:
+
+```
+2026-05-03T14:32:00:Jerome Etienne: hey, are you free this week?
+```
+
+Send a reply:
+
+```bash
+npx tsx ./src/cli.ts dm_send "Jerome Etienne" "Sure, Thursday afternoon works."
+```
+
+Export a profile as markdown (default):
+
+```bash
+npx tsx ./src/cli.ts profile jeromeetienne
+```
+
+Export the same profile as JSON:
+
+```bash
+npx tsx ./src/cli.ts profile jeromeetienne -f json
+```
+
+## Layout
+
+- [src/cli.ts](src/cli.ts) — Commander entry point, defines the commands and orchestrates browser actions through `FastBrowserHelper`.
+- [src/libs/linkedin_thread_helper.ts](src/libs/linkedin_thread_helper.ts) — Parses the LinkedIn message thread from an accessibility tree snapshot into timestamped lines.
+- [src/libs/linkedin_profile_helper.ts](src/libs/linkedin_profile_helper.ts) — Parses a LinkedIn profile snapshot into a typed `LinkedinProfile` (header, About, Experience, Education) with markdown rendering.