barebrowse 0.25.0 → 0.26.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +38 -0
- package/README.md +21 -0
- package/barebrowse.context.md +7 -3
- package/cli.js +6 -6
- package/commands/barebrowse/SKILL.md +141 -0
- package/commands/barebrowse.md +140 -0
- package/mcp-server.js +8 -5
- package/package.json +2 -1
- package/src/aria.js +5 -0
- package/src/ax-snapshot.js +1 -0
- package/src/bareagent.js +5 -3
- package/src/daemon.js +5 -4
- package/src/data.js +24 -9
- package/src/firefox-page.js +63 -12
- package/src/index.js +88 -21
- package/src/links.js +46 -0
- package/src/navigation.js +42 -0
- package/src/prune.js +11 -3
- package/types/aria.d.ts +0 -6
- package/types/data.d.ts +6 -1
- package/types/firefox-page.d.ts +5 -1
- package/types/index.d.ts +18 -3
- package/types/links.d.ts +28 -0
- package/types/navigation.d.ts +44 -0
- package/types/prune.d.ts +2 -0
package/src/prune.js
CHANGED
|
@@ -62,6 +62,7 @@ const SKIP_ROLES = new Set([
|
|
|
62
62
|
* @param {object} [options]
|
|
63
63
|
* @param {'act'|'browse'|'navigate'|'full'|'read'} [options.mode='act'] - Pruning mode ('read' is an alias for 'browse')
|
|
64
64
|
* @param {string} [options.context=''] - Search context for relevance filtering
|
|
65
|
+
* @param {boolean} [options.links=false] - Links carry `urls` (see links.js): nodes that drop their children keep the URLs of links beneath them
|
|
65
66
|
* @returns {object|null} Pruned tree
|
|
66
67
|
*/
|
|
67
68
|
export function prune(tree, options = {}) {
|
|
@@ -80,7 +81,7 @@ export function prune(tree, options = {}) {
|
|
|
80
81
|
nodes = extractRegions(nodes, allowedRegions);
|
|
81
82
|
|
|
82
83
|
// Step 2: Prune nodes
|
|
83
|
-
const ctx = { mode, parentRole: null, keywords };
|
|
84
|
+
const ctx = { mode, parentRole: null, keywords, links: !!options.links };
|
|
84
85
|
nodes = nodes.map((n) => pruneNode(n, ctx)).filter(Boolean);
|
|
85
86
|
|
|
86
87
|
// Step 3: Collapse structural wrappers
|
|
@@ -204,7 +205,7 @@ function pruneNode(node, ctx) {
|
|
|
204
205
|
return { ...node, children: pruneChildren(node.children, ctx) };
|
|
205
206
|
}
|
|
206
207
|
if (node.role === 'group' && node.name) {
|
|
207
|
-
if (!isBrowse && /kleuren|colors?|couleurs?|farben/i.test(node.name)) {
|
|
208
|
+
if (!isBrowse && !ctx.links && /kleuren|colors?|couleurs?|farben/i.test(node.name)) {
|
|
208
209
|
return collapseColors(node);
|
|
209
210
|
}
|
|
210
211
|
return { ...node, children: pruneChildren(node.children, ctx) };
|
|
@@ -217,7 +218,7 @@ function pruneNode(node, ctx) {
|
|
|
217
218
|
return null;
|
|
218
219
|
}
|
|
219
220
|
}
|
|
220
|
-
return { ...node, children: [] };
|
|
221
|
+
return { ...node, children: [], ...carryUrls(node, ctx) };
|
|
221
222
|
}
|
|
222
223
|
|
|
223
224
|
// StaticText — CDP equivalent of mcprune's "text" nodes
|
|
@@ -448,6 +449,13 @@ function flatten(nodes) {
|
|
|
448
449
|
return result;
|
|
449
450
|
}
|
|
450
451
|
|
|
452
|
+
// Links on: a node that drops its children keeps the URLs of the links beneath it.
|
|
453
|
+
function carryUrls(node, ctx) {
|
|
454
|
+
if (!ctx.links) return {};
|
|
455
|
+
const urls = [...new Set(flatten([node]).flatMap((n) => n.urls || []))];
|
|
456
|
+
return urls.length ? { urls } : {};
|
|
457
|
+
}
|
|
458
|
+
|
|
451
459
|
function condenseCard(node) {
|
|
452
460
|
const all = flatten([node]);
|
|
453
461
|
const link = all.find((n) => n.role === 'link' && n.name);
|
package/types/aria.d.ts
CHANGED
|
@@ -1,9 +1,3 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* aria.js — Format ARIA accessibility tree nodes for agent consumption.
|
|
3
|
-
*
|
|
4
|
-
* Takes a nested tree (built from CDP's Accessibility.getFullAXTree)
|
|
5
|
-
* and formats it as readable YAML-like text, similar to Playwright's ariaSnapshot.
|
|
6
|
-
*/
|
|
7
1
|
/**
|
|
8
2
|
* Format a nested ARIA tree as readable text output.
|
|
9
3
|
*
|
package/types/data.d.ts
CHANGED
|
@@ -2,9 +2,14 @@
|
|
|
2
2
|
* Render a raw ARIA tree in data mode.
|
|
3
3
|
*
|
|
4
4
|
* @param {object} root - Root node from buildTree() (CDP vocabulary)
|
|
5
|
+
* @param {{ links?: boolean }} [opts] - links: the tree's link nodes carry `urls` (annotateLinks); adds the legend note
|
|
5
6
|
* @returns {string} LEGEND line, then one line per record, YAML-ish like formatTree(); '' when there are no records
|
|
6
7
|
*/
|
|
7
|
-
export function dataSnapshot(root: object
|
|
8
|
+
export function dataSnapshot(root: object, opts?: {
|
|
9
|
+
links?: boolean;
|
|
10
|
+
}): string;
|
|
8
11
|
/** First line of every data-mode snapshot: tells an agent with no docs how to read it. */
|
|
9
12
|
export const LEGEND: "# data mode: one line per record. Tables: row \"<label>\": <column>: <value> \u00B7 \u2026 Groups: <label>: a, b, c. A title line followed by detail lines is one block, up to the next title line. Main content only; use mode \"act\" for menus and page controls.";
|
|
13
|
+
/** Appended to the legend only when links are on. */
|
|
14
|
+
export const LINKS_NOTE: " Links: \"name\" <url>.";
|
|
10
15
|
export function stripLegend(s: any): any;
|
package/types/firefox-page.d.ts
CHANGED
|
@@ -3,6 +3,7 @@
|
|
|
3
3
|
* @param {object} bidi - BiDi client from createBiDi()
|
|
4
4
|
* @param {object} [opts]
|
|
5
5
|
* @param {'act'|'browse'|'navigate'|'full'|'read'|'data'} [opts.pruneMode='act'] - Default prune mode.
|
|
6
|
+
* @param {boolean} [opts.links=false] - Default for snapshot({ links }): show link URLs.
|
|
6
7
|
* @param {{allowLocalUrls?: boolean, blockPrivateNetwork?: boolean}} [opts.urlGuard] - Navigation safety policy, applied on every goto().
|
|
7
8
|
* @param {string} [opts.uploadDir] - When set, upload() rejects files outside this dir.
|
|
8
9
|
* @param {boolean} [opts.incognito=false] - Clean session: injectCookies() is a no-op.
|
|
@@ -13,6 +14,7 @@
|
|
|
13
14
|
*/
|
|
14
15
|
export function createFirefoxPage(bidi: object, opts?: {
|
|
15
16
|
pruneMode?: "data" | "act" | "browse" | "navigate" | "full" | "read" | undefined;
|
|
17
|
+
links?: boolean | undefined;
|
|
16
18
|
urlGuard?: {
|
|
17
19
|
allowLocalUrls?: boolean;
|
|
18
20
|
blockPrivateNetwork?: boolean;
|
|
@@ -33,6 +35,8 @@ export function createFirefoxPage(bidi: object, opts?: {
|
|
|
33
35
|
readonly context: any;
|
|
34
36
|
/** Whether the last goto() landed on a bot-challenge page (parity w/ CDP). */
|
|
35
37
|
readonly botBlocked: boolean;
|
|
38
|
+
/** Outcome of the latest goto(): `{url, status}`, or null before any goto. */
|
|
39
|
+
readonly lastNavigation: import("./navigation.js").NavigationOutcome | null;
|
|
36
40
|
/** @type {'firefox'} Engine driving this session (see also `capabilities`). */
|
|
37
41
|
engine: "firefox";
|
|
38
42
|
/**
|
|
@@ -44,7 +48,7 @@ export function createFirefoxPage(bidi: object, opts?: {
|
|
|
44
48
|
* @type {import('./index.js').Capabilities}
|
|
45
49
|
*/
|
|
46
50
|
capabilities: import("./index.js").Capabilities;
|
|
47
|
-
goto(url: any, timeout?: number): Promise<
|
|
51
|
+
goto(url: any, timeout?: number): Promise<import("./navigation.js").NavigationOutcome>;
|
|
48
52
|
/** @param {import('./index.js').SnapshotOptions|false} [pruneOpts] */
|
|
49
53
|
snapshot(pruneOpts?: import("./index.js").SnapshotOptions | false): Promise<string>;
|
|
50
54
|
readable(): Promise<any>;
|
package/types/index.d.ts
CHANGED
|
@@ -26,6 +26,7 @@
|
|
|
26
26
|
* @param {string} [opts.browser] - Source browser for cookie extraction.
|
|
27
27
|
* @param {boolean} [opts.consent=true] - Auto-dismiss cookie consent dialogs.
|
|
28
28
|
* @param {'act'|'browse'|'navigate'|'full'|'read'|'data'} [opts.pruneMode='act'] - Pruning mode.
|
|
29
|
+
* @param {boolean} [opts.links=false] - Show link URLs: `link "name" <url> [ref=N]`.
|
|
29
30
|
* @returns {Promise<string>} ARIA snapshot text
|
|
30
31
|
*/
|
|
31
32
|
export function browse(url: string, opts?: {
|
|
@@ -48,6 +49,7 @@ export function browse(url: string, opts?: {
|
|
|
48
49
|
browser?: string | undefined;
|
|
49
50
|
consent?: boolean | undefined;
|
|
50
51
|
pruneMode?: "data" | "act" | "browse" | "navigate" | "full" | "read" | undefined;
|
|
52
|
+
links?: boolean | undefined;
|
|
51
53
|
}): Promise<string>;
|
|
52
54
|
/**
|
|
53
55
|
* Decide which engine connect() should use. Pure — the caller passes lazy
|
|
@@ -74,9 +76,10 @@ export function connect(opts?: {}): Promise<{
|
|
|
74
76
|
readonly bidi: any;
|
|
75
77
|
readonly context: any;
|
|
76
78
|
readonly botBlocked: boolean;
|
|
79
|
+
readonly lastNavigation: import("./navigation.js").NavigationOutcome | null;
|
|
77
80
|
engine: "firefox";
|
|
78
81
|
capabilities: import("./index.js").Capabilities;
|
|
79
|
-
goto(url: any, timeout?: number): Promise<
|
|
82
|
+
goto(url: any, timeout?: number): Promise<import("./navigation.js").NavigationOutcome>;
|
|
80
83
|
snapshot(pruneOpts?: import("./index.js").SnapshotOptions | false): Promise<string>;
|
|
81
84
|
readable(): Promise<any>;
|
|
82
85
|
click(ref: any): Promise<void>;
|
|
@@ -109,7 +112,7 @@ export function connect(opts?: {}): Promise<{
|
|
|
109
112
|
waitForNavigation(timeout?: number): Promise<void>;
|
|
110
113
|
close(): Promise<void>;
|
|
111
114
|
} | {
|
|
112
|
-
goto(url: any, timeout?: number): Promise<
|
|
115
|
+
goto(url: any, timeout?: number): Promise<import("./navigation.js").NavigationOutcome>;
|
|
113
116
|
goBack(): Promise<void>;
|
|
114
117
|
goForward(): Promise<void>;
|
|
115
118
|
reload(reloadOpts?: {}): Promise<void>;
|
|
@@ -133,6 +136,8 @@ export function connect(opts?: {}): Promise<{
|
|
|
133
136
|
waitFor(waitOpts?: {}): Promise<void>;
|
|
134
137
|
saveState(filePath: any): Promise<void>;
|
|
135
138
|
readonly botBlocked: boolean;
|
|
139
|
+
/** Outcome of the latest goto(): `{url, status}`, or null before any goto. */
|
|
140
|
+
readonly lastNavigation: import("./navigation.js").NavigationOutcome | null;
|
|
136
141
|
/** @type {'chromium'} Engine driving this session (see also `capabilities`) */
|
|
137
142
|
engine: "chromium";
|
|
138
143
|
/**
|
|
@@ -159,7 +164,7 @@ export function connect(opts?: {}): Promise<{
|
|
|
159
164
|
/** Raw CDP session for escape hatch — getter so it survives hybrid fallback / tab swaps */
|
|
160
165
|
readonly cdp: any;
|
|
161
166
|
createTab(): Promise<{
|
|
162
|
-
goto(url: any, timeout?: number): Promise<
|
|
167
|
+
goto(url: any, timeout?: number): Promise<import("./navigation.js").NavigationOutcome>;
|
|
163
168
|
readonly botBlocked: boolean;
|
|
164
169
|
/** @param {string} url @param {CookieOptions} [cookieOpts] */
|
|
165
170
|
injectCookies(url: string, cookieOpts?: CookieOptions): Promise<number>;
|
|
@@ -243,12 +248,22 @@ export type Capabilities = {
|
|
|
243
248
|
*/
|
|
244
249
|
cookieInjection: boolean;
|
|
245
250
|
};
|
|
251
|
+
/**
|
|
252
|
+
* What `goto()` resolves to: the final URL (after redirects) and the main
|
|
253
|
+
* document's HTTP status (0 when no HTTP response was observed, e.g. an aborted navigation).
|
|
254
|
+
* Network failures reject with an Error whose `code` is 'NAV_FAILED' and
|
|
255
|
+
* `reason` the browser's raw error string.
|
|
256
|
+
*/
|
|
257
|
+
export type NavigationOutcome = import("./navigation.js").NavigationOutcome;
|
|
246
258
|
/**
|
|
247
259
|
* Options for `page.snapshot()`. Pass `false` instead of an object to skip
|
|
248
260
|
* pruning and return the raw ARIA tree.
|
|
261
|
+
* `links: true` adds each link's absolute URL after its name (default off,
|
|
262
|
+
* or the `connect({ links })` default).
|
|
249
263
|
*/
|
|
250
264
|
export type SnapshotOptions = {
|
|
251
265
|
mode?: "act" | "browse" | "navigate" | "full" | "read" | "data";
|
|
266
|
+
links?: boolean;
|
|
252
267
|
};
|
|
253
268
|
/**
|
|
254
269
|
* Options for `page.type()`.
|
package/types/links.d.ts
ADDED
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* links.js — opt-in link URLs for snapshots (`links: true`).
|
|
3
|
+
*
|
|
4
|
+
* `annotateLinks()` stamps `urls: [url]` on every link node that has a usable
|
|
5
|
+
* browser-serialized absolute URL. aria.js, prune.js and data.js print/carry
|
|
6
|
+
* `urls` — they never see the option, so with links off nothing changes.
|
|
7
|
+
*/
|
|
8
|
+
/**
|
|
9
|
+
* Normalise a link's URL for a snapshot line. Returns '' when it should not be
|
|
10
|
+
* shown: no URL, `javascript:`, or a same-document link (the page URL, only
|
|
11
|
+
* the #fragment differs). A raw space, `<` or `>` (browsers encode them, but
|
|
12
|
+
* not always in the fragment) is percent-encoded so a line splits cleanly on
|
|
13
|
+
* ` <` and `> `.
|
|
14
|
+
*
|
|
15
|
+
* @param {string|undefined} url - Absolute URL as serialized by the browser
|
|
16
|
+
* @param {string} [pageUrl] - URL of the page the link is on
|
|
17
|
+
* @returns {string}
|
|
18
|
+
*/
|
|
19
|
+
export function linkUrl(url: string | undefined, pageUrl?: string): string;
|
|
20
|
+
/**
|
|
21
|
+
* Copy a tree with `urls` set on its link nodes (input is not mutated).
|
|
22
|
+
*
|
|
23
|
+
* @param {object|null} node - Root from buildTree()
|
|
24
|
+
* @param {string} pageUrl
|
|
25
|
+
* @returns {object|null}
|
|
26
|
+
*/
|
|
27
|
+
export function annotateLinks(node: object | null, pageUrl: string): object | null;
|
|
28
|
+
export function urlsText(urls: any): any;
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* navigation.js — Shared pieces of the goto() outcome contract, so both
|
|
3
|
+
* engines (CDP in index.js, BiDi in firefox-page.js) report it identically.
|
|
4
|
+
*/
|
|
5
|
+
/**
|
|
6
|
+
* What goto() resolves to: where the page ended up and how the server answered.
|
|
7
|
+
* `status` is 0 when no HTTP response was observed for the navigation (e.g. an
|
|
8
|
+
* aborted navigation that never got one).
|
|
9
|
+
* @typedef {{ url: string, status: number }} NavigationOutcome
|
|
10
|
+
*/
|
|
11
|
+
/**
|
|
12
|
+
* Typed error for a navigation that never reached a document (DNS failure,
|
|
13
|
+
* connection refused, TLS error, ...). `code` is 'NAV_FAILED'; `reason` is the
|
|
14
|
+
* browser's raw error string (`net::ERR_NAME_NOT_RESOLVED`,
|
|
15
|
+
* `NS_ERROR_UNKNOWN_HOST`, ...).
|
|
16
|
+
* @param {string} url
|
|
17
|
+
* @param {string} reason
|
|
18
|
+
* @returns {Error & {code: 'NAV_FAILED', reason: string}}
|
|
19
|
+
*/
|
|
20
|
+
export function navFailed(url: string, reason: string): Error & {
|
|
21
|
+
code: "NAV_FAILED";
|
|
22
|
+
reason: string;
|
|
23
|
+
};
|
|
24
|
+
/**
|
|
25
|
+
* True for a final HTTP status that is not 2xx (0 = unknown is not an error).
|
|
26
|
+
* @param {number|undefined} status
|
|
27
|
+
*/
|
|
28
|
+
export function isHttpError(status: number | undefined): boolean;
|
|
29
|
+
/**
|
|
30
|
+
* Warning line for a non-2xx final status ('' for 2xx and for unknown 0), in
|
|
31
|
+
* the style of the bot-challenge line, newline-terminated for prepending.
|
|
32
|
+
* @param {number|undefined} status
|
|
33
|
+
* @returns {string}
|
|
34
|
+
*/
|
|
35
|
+
export function httpWarning(status: number | undefined): string;
|
|
36
|
+
/**
|
|
37
|
+
* What goto() resolves to: where the page ended up and how the server answered.
|
|
38
|
+
* `status` is 0 when no HTTP response was observed for the navigation (e.g. an
|
|
39
|
+
* aborted navigation that never got one).
|
|
40
|
+
*/
|
|
41
|
+
export type NavigationOutcome = {
|
|
42
|
+
url: string;
|
|
43
|
+
status: number;
|
|
44
|
+
};
|
package/types/prune.d.ts
CHANGED
|
@@ -5,9 +5,11 @@
|
|
|
5
5
|
* @param {object} [options]
|
|
6
6
|
* @param {'act'|'browse'|'navigate'|'full'|'read'} [options.mode='act'] - Pruning mode ('read' is an alias for 'browse')
|
|
7
7
|
* @param {string} [options.context=''] - Search context for relevance filtering
|
|
8
|
+
* @param {boolean} [options.links=false] - Links carry `urls` (see links.js): nodes that drop their children keep the URLs of links beneath them
|
|
8
9
|
* @returns {object|null} Pruned tree
|
|
9
10
|
*/
|
|
10
11
|
export function prune(tree: object, options?: {
|
|
11
12
|
mode?: "act" | "browse" | "navigate" | "full" | "read" | undefined;
|
|
12
13
|
context?: string | undefined;
|
|
14
|
+
links?: boolean | undefined;
|
|
13
15
|
}): object | null;
|