fastbrowser_cli 1.0.30 → 1.0.33

package/examples/wttj_cli/wttj_search.ts

@@ -0,0 +1,162 @@
+#!/usr/bin/env npx tsx
+
+// npm imports
+import * as Commander from 'commander';
+import { FastBrowserHelper } from './fastbrowser_helper.js';
+import { A11yTree } from 'a11y_parse';
+
+type JobSearchResult = {
+	title: string;
+	url: string;
+};
+
+///////////////////////////////////////////////////////////////////////////////
+///////////////////////////////////////////////////////////////////////////////
+//	
+///////////////////////////////////////////////////////////////////////////////
+///////////////////////////////////////////////////////////////////////////////
+
+class WttjSearch {
+
+	static async outputJson(jobs: Array<JobSearchResult>): Promise<void> {
+		console.log(JSON.stringify(jobs, null, 2));
+	}
+
+	static async outputMarkdown(jobs: Array<JobSearchResult>): Promise<void> {
+		console.log('| # | Title | URL |');
+		console.log('|---|-------|-----|');
+		for (const [i, job] of jobs.entries()) {
+			const url = job.url !== '' ? `[link](${job.url})` : '';
+			console.log(`| ${i + 1} | ${job.title} | ${url} |`);
+		}
+	}
+
+	///////////////////////////////////////////////////////////////////////////////
+	///////////////////////////////////////////////////////////////////////////////
+	//	
+	///////////////////////////////////////////////////////////////////////////////
+	///////////////////////////////////////////////////////////////////////////////
+
+	private static parseJobTitles(output: string): Array<JobSearchResult> {
+		const results: Array<JobSearchResult> = [];
+		const headingRe = /heading "(.+?)" level/g;
+		const urlRe = /url="([^"]+)"/;
+		for (const line of output.split('\n')) {
+			const headingMatch = headingRe.exec(line);
+			if (headingMatch === null) continue;
+			const urlMatch = urlRe.exec(line);
+			results.push({
+				title: headingMatch[1],
+				url: urlMatch !== null ? urlMatch[1] : '',
+			});
+			headingRe.lastIndex = 0;
+		}
+		return results;
+	}
+
+	static async collectOnePageResults(): Promise<Array<JobSearchResult>> {
+		const searchResults: Array<JobSearchResult> = [];
+		const a11ySelector = 'link[url^="/fr/companies/"]';
+		let outputStr: string = await FastBrowserHelper.querySelectorsAll(a11ySelector, 0);
+		// trim output to avoid issues with trailing newlines
+		outputStr = outputStr.trim();
+		// split output into lines and remove the first line which is a header
+		const outputLines = outputStr.split('\n');
+		// remove the first line which is a header
+		outputLines.shift();
+
+		// parse each line as an axNode and extract the job title and url
+		for (const outputLine of outputLines) {
+			const axNode = A11yTree.parse(outputLine);
+			// sanity check - the axNode should have a 'name' and a 'url' attribute
+			if (axNode.name === undefined) {
+				throw new Error(`Expected axNode.name to be defined for selector: ${a11ySelector} line: ${outputLine}`);
+			}
+			if (axNode.attributes['url'] === undefined) {
+				throw new Error(`Expected axNode.url to be defined for selector: ${a11ySelector} line: ${outputLine}`);
+			}
+			// Build the search result object and add it to the results array
+			const searchResult: JobSearchResult = {
+				title: axNode.name!,
+				url: `https://www.welcometothejungle.com${axNode.attributes['url']!}`,
+			};
+			searchResults.push(searchResult);
+		}
+
+		// return the search results
+		return searchResults
+	}
+
+	static async runSearch(query: string, pageIndexLimit: number = 1, pageIndexOffset: number = 0): Promise<Array<JobSearchResult>> {
+		const searchResults: Array<JobSearchResult> = [];
+		for (let pageIndex = pageIndexOffset; pageIndex < pageIndexOffset + pageIndexLimit; pageIndex++) {
+			// load the page
+			const pageUrl = `https://www.welcometothejungle.com/fr/jobs-matches?page=${pageIndex + 1}`;
+			FastBrowserHelper.navigatePage(pageUrl);
+
+			// collect results for the current page
+			const newSearchResults = await this.collectOnePageResults();
+			searchResults.push(...newSearchResults);
+		}
+		return searchResults;
+	}
+}
+
+///////////////////////////////////////////////////////////////////////////////
+///////////////////////////////////////////////////////////////////////////////
+//	
+///////////////////////////////////////////////////////////////////////////////
+///////////////////////////////////////////////////////////////////////////////
+
+
+async function main() {
+	///////////////////////////////////////////////////////////////////////////////
+	///////////////////////////////////////////////////////////////////////////////
+	//	
+	///////////////////////////////////////////////////////////////////////////////
+	///////////////////////////////////////////////////////////////////////////////
+
+	const program = new Commander.Command();
+	program
+		.argument('[query]', 'job search query', 'machine learning')
+		.option('-l, --page-limit <number>', 'number of pages to fetch', '1')
+		.option('-o, --page-offset <number>', 'first page to scrape', '0')
+		.addOption(new Commander.Option('-f, --format <format>', 'output format: json or markdown').choices(['json', 'markdown']).default('markdown'))
+		.parse();
+
+	type CliOptions = {
+		pageLimit: string;
+		pageOffset: string;
+		format: 'json' | 'markdown';
+	};
+	const options: CliOptions = program.opts<CliOptions>();
+
+	///////////////////////////////////////////////////////////////////////////////
+	///////////////////////////////////////////////////////////////////////////////
+	//	
+	///////////////////////////////////////////////////////////////////////////////
+	///////////////////////////////////////////////////////////////////////////////
+
+	// run the search and get results
+	const query = program.args[0]
+	const limit = Number(options.pageLimit);
+	const offset = Number(options.pageOffset);
+	const searchResults: Array<JobSearchResult> = await WttjSearch.runSearch(query, limit, offset);
+
+	// Output results in the specified format
+	if (options.format === 'json') {
+		await WttjSearch.outputJson(searchResults);
+	} else if (options.format === 'markdown') {
+		await WttjSearch.outputMarkdown(searchResults);
+	} else {
+		throw new Error(`Unsupported output format: ${options.format}`);
+	}
+}
+
+///////////////////////////////////////////////////////////////////////////////
+///////////////////////////////////////////////////////////////////////////////
+//	Entry point
+///////////////////////////////////////////////////////////////////////////////
+///////////////////////////////////////////////////////////////////////////////
+
+void main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fastbrowser_cli",
-  "version": "1.0.30",
+  "version": "1.0.33",
   "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": {
@@ -12,14 +12,20 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/jeromeetienne/skillmd_collecetion.git"
+    "url": "git+https://github.com/jeromeetienne/skillmd_collection.git",
+    "directory": "packages/fastbrowser_cli"
+  },
+  "homepage": "https://github.com/jeromeetienne/skillmd_collection/tree/main/packages/fastbrowser_cli#readme",
+  "bugs": {
+    "url": "https://github.com/jeromeetienne/skillmd_collection/issues"
   },
-  "homepage": "https://github.com/jeromeetienne/skillmd_collection/packages/fastbrowser_cli#readme",
   "type": "module",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "chalk": "^5.6.2",
     "commander": "^12.1.0",
     "express": "^4.21.2",
+    "minimatch": "^10.2.5",
     "string-argv": "^0.3.2",
     "typescript": "^6.0.3",
     "zod": "^4.3.6",
@@ -43,7 +49,7 @@
     "inspect:playwright:extension": "npx @modelcontextprotocol/inspector npx @playwright/mcp@latest --extension",
     "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 to $(node -p 'require(\\\"./package.json\\\").version') in fastbrowser_cli package.json\"",
+    "version:bump": "npm version patch --no-git-tag-version && git add package.json && git commit -m \"feat: bump version in fastbrowser_cli package.json\"",
     "publish:all": "pnpm run prepublish:check && pnpm run build && pnpm run version:bump && pnpm publish --access public",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "npx tsx --test 'tests/**/*.test.ts'"

package/skills/fastbrowser/SKILL.md

@@ -20,7 +20,7 @@ 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).
+1. **Query** the accessibility tree for specific nodes with `query_selectors` (first match per selector by default; pass `-a, --all` for every match).
 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:
@@ -145,8 +145,8 @@ Example queries on it:
 
 ## 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`.
+- `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.
 
 ```bash
 # Query the accessibility tree returning the FIRST match per selector (--selector is repeatable)
@@ -159,14 +159,14 @@ npx fastbrowser_cli query_selectors --selector 'heading[level="1"]' --no-with-an
 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
+# 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
 
 # Exclude ancestor nodes from the result
-npx fastbrowser_cli query_selectors_all --selector 'heading[level="1"]' --no-with-ancestors
+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 \
+# 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}]'
 
 # Take an accessibility-tree full page snapshot of the current page - very expensive, prefer targeted queries when possible
@@ -233,9 +233,8 @@ press_keys --keys "Tab, Enter"
 | `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` |
+| `take_snapshot` | Dump the accessibility tree of the whole page - very expensive, prefer targeted queries (`query_selectors`) when possible | — |
+| `query_selectors` | Query a11y tree by CSS-like selector (first match per selector by default; pass `-a, --all` for every match, with optional `--limit`) | `--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` |

package/skills/fastbrowser-script/SKILL.md

@@ -30,7 +30,7 @@ Always follow this order — guessing selectors without checking the page wastes
    the user wants to parameterize (query, message, page count), and output format (stdout text,
    JSON, Markdown, file).
 2. **Probe the live page.** Open it and find selectors that actually match. Prefer
-   `query_selectors` / `query_selectors_all` over `take_snapshot` (cheaper, less noise).
+   `query_selectors` (use `-a, --all` to get every match) over `take_snapshot` (cheaper, less noise).
    ```bash
    npx fastbrowser_cli new_page --url https://example.com
    npx fastbrowser_cli query_selectors -s 'searchbox' -s 'button[name*="Search"]'
@@ -72,12 +72,12 @@ Hard-coded selectors are the fragile part of any scraper — choose stable ones.
 - Use **scoping** when a role is ambiguous: `dialog textbox`, `navigation > link`.
 - **Never** use uid selectors (`#1_42`, `#4`) in a script. They are session-local and change on
   every page rebuild. See the hard rule at the top.
-- If you need every match (e.g. a list of results), use `query_selectors_all --limit N` with a
-  reasonable cap; the default returns everything and is expensive.
+- If you need every match (e.g. a list of results), use `query_selectors --all --limit N` with a
+  reasonable cap; without `--limit` it returns everything and is expensive.
 
 ## Output parsing
 
-`query_selectors` / `query_selectors_all` print one indented line per node:
+`query_selectors` prints one indented line per node:
 
 ```
 uid=1_12 heading "Welcome" level="1"

package/src/fastbrowser_cli/fastbrowser_cli.ts

@@ -299,42 +299,31 @@ async function main(): Promise<void> {
 			});
 		});
 
-	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', false)
-		.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) => {
-			const body = QueryBuilder.buildQuerySelectorsBody(opts);
-			await MainHelper.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')
+		.description('Query the accessibility tree with CSS-like selectors. By default returns the first match per selector; use --all to return every match.')
 		.option('-s, --selector <selector>', 'CSS-like selector (repeatable)', (value: string, prev: string[] = []) => {
 			prev.push(value);
 			return prev;
 		})
-		.option('--with-ancestors', 'Include ancestor nodes', false)
-		.option('--no-with-ancestors', 'Exclude ancestor nodes')
-		.option('--selectors-json <json>', 'JSON array of {selector,withAncestors} for per-selector control')
+		.option('-a, --all', 'Return all matches per selector (default: first match only)', false)
+		.option('--limit <number>', 'Max nodes per selector when --all is set (0 = unlimited)', '0')
+		.option('--wa, --with-ancestors', 'Include ancestor nodes', false)
+		.option('--wc, --with-children', 'Include descendant nodes (subtree) of each matched node', false)
+		.option('--selectors-json <json>', 'JSON array of {selector,limit?,withAncestors,withChildren} for per-selector control')
 		.action(async (opts: {
 			selector?: string[];
+			all?: boolean;
+			limit?: string;
 			withAncestors?: boolean;
+			withChildren?: boolean;
 			selectorsJson?: string;
 		}, cmd: Command) => {
+			if (opts.all === true) {
+				const body = QueryBuilder.buildQuerySelectorsBody(opts);
+				await MainHelper.runTool(cmd, 'query_selectors_all', body);
+				return;
+			}
 			const body = QueryBuilder.buildQuerySelectorFirstBody(opts);
 			await MainHelper.runTool(cmd, 'query_selectors', body);
 		});

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

@@ -16,12 +16,14 @@ export type BuildQuerySelectorsAllOpts = {
 	selector?: string[];
 	limit?: string;
 	withAncestors?: boolean;
+	withChildren?: boolean;
 	selectorsJson?: string;
 };
 
 export type BuildQuerySelectorFirstOpts = {
 	selector?: string[];
 	withAncestors?: boolean;
+	withChildren?: boolean;
 	selectorsJson?: string;
 };
 
@@ -50,11 +52,13 @@ export class QueryBuilder {
 			throw new Error(`Invalid --limit: ${opts.limit}`);
 		}
 		const withAncestors = opts.withAncestors !== false;
+		const withChildren = opts.withChildren === true;
 
 		const selectors: QuerySelectorInput[] = selectorList.map((selector) => ({
 			selector,
 			limit,
 			withAncestors,
+			withChildren,
 		}));
 		return { selectors };
 	}
@@ -79,10 +83,12 @@ export class QueryBuilder {
 		}
 
 		const withAncestors = opts.withAncestors !== false;
+		const withChildren = opts.withChildren === true;
 
 		const selectors: QuerySelectorFirstInput[] = selectorList.map((selector) => ({
 			selector,
 			withAncestors,
+			withChildren,
 		}));
 		return { selectors };
 	}