@rezkam/browser-tools 0.2.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.
@@ -0,0 +1,143 @@
1
+ import { writeFileSync } from 'node:fs';
2
+ import { DEFAULT_PORT, connectBrowser } from './browser-control.mjs';
3
+ import { readCachedResponse, writeCachedResponse } from './browser-query-cache.mjs';
4
+
5
+ export function writeResourceOutput({ output, outFile = null, metadata = null }) {
6
+ if (outFile) {
7
+ writeFileSync(outFile, output, 'utf-8');
8
+ if (metadata) writeFileSync(`${outFile}.meta.json`, JSON.stringify(metadata, null, 2), 'utf-8');
9
+ console.log(`Saved to ${outFile}`);
10
+ return;
11
+ }
12
+
13
+ console.log(output);
14
+ }
15
+
16
+ export function readCachedResourceOutput({ tool, cacheInput, outFile = null, readCache = readCachedResponse } = {}) {
17
+ const cached = readCache(tool, cacheInput);
18
+ if (!cached) return null;
19
+
20
+ const metadata = {
21
+ ...(cached.entry?.metadata || {}),
22
+ cache_hit: true,
23
+ cache_key: cached.key,
24
+ };
25
+ writeResourceOutput({ output: cached.output, outFile, metadata });
26
+ return { status: 'cached', key: cached.key, output: cached.output, metadata };
27
+ }
28
+
29
+ export function writeResourceCache({
30
+ tool,
31
+ cacheInput,
32
+ output,
33
+ rawText = output,
34
+ pageUrl = null,
35
+ metadata = {},
36
+ extension = 'txt',
37
+ writeCache = writeCachedResponse,
38
+ } = {}) {
39
+ const cacheWrite = writeCache(tool, cacheInput, {
40
+ output,
41
+ rawText,
42
+ pageUrl,
43
+ metadata,
44
+ extension,
45
+ });
46
+ if (cacheWrite) metadata.cache_key = cacheWrite.key;
47
+ return cacheWrite;
48
+ }
49
+
50
+ export async function newBackgroundPage(browser) {
51
+ return browser.newPage({ background: true });
52
+ }
53
+
54
+ export async function closeResourcePage(page) {
55
+ if (!page) return;
56
+ const isClosed = typeof page.isClosed === 'function' ? page.isClosed() : false;
57
+ if (!isClosed && typeof page.close === 'function') await page.close().catch(() => {});
58
+ }
59
+
60
+ function connectOptionsForOwner(ownerToken) {
61
+ return ownerToken === undefined ? {} : { ownerToken };
62
+ }
63
+
64
+ function normalizePageResult(pageResult, closePage) {
65
+ if (pageResult && typeof pageResult === 'object' && Object.hasOwn(pageResult, 'page')) {
66
+ return {
67
+ page: pageResult.page,
68
+ closePage: Object.hasOwn(pageResult, 'closePage') ? Boolean(pageResult.closePage) : closePage,
69
+ };
70
+ }
71
+ return { page: pageResult, closePage };
72
+ }
73
+
74
+ export async function runBrowserResource({
75
+ port = DEFAULT_PORT,
76
+ ownerToken = undefined,
77
+ connect = connectBrowser,
78
+ getPage = null,
79
+ closePage = false,
80
+ run,
81
+ } = {}) {
82
+ if (typeof run !== 'function') throw new Error('Missing Resource Helper run function');
83
+
84
+ const browser = await connect(port, connectOptionsForOwner(ownerToken));
85
+ let page = null;
86
+ let shouldClosePage = closePage;
87
+
88
+ try {
89
+ const normalized = normalizePageResult(getPage ? await getPage(browser) : null, closePage);
90
+ page = normalized.page;
91
+ shouldClosePage = normalized.closePage;
92
+ return await run({ browser, page });
93
+ } finally {
94
+ if (shouldClosePage) await closeResourcePage(page);
95
+ if (browser && typeof browser.disconnect === 'function') browser.disconnect();
96
+ }
97
+ }
98
+
99
+ export async function runCachedBrowserResource({
100
+ tool,
101
+ cacheInput,
102
+ outFile = null,
103
+ port = DEFAULT_PORT,
104
+ ownerToken = undefined,
105
+ connect = connectBrowser,
106
+ getPage = newBackgroundPage,
107
+ closePage = true,
108
+ run,
109
+ readCache = readCachedResponse,
110
+ writeCache = writeCachedResponse,
111
+ } = {}) {
112
+ const cached = readCachedResourceOutput({ tool, cacheInput, outFile, readCache });
113
+ if (cached) return cached;
114
+ if (typeof run !== 'function') throw new Error('Missing Resource Helper run function');
115
+
116
+ return runBrowserResource({
117
+ port,
118
+ ownerToken,
119
+ connect,
120
+ getPage,
121
+ closePage,
122
+ run: async ({ browser, page }) => {
123
+ const result = await run({ browser, page });
124
+ if (!result || !Object.hasOwn(result, 'output')) throw new Error('Resource Helper run function must return output');
125
+ const output = result.output;
126
+ const metadata = result.metadata || {};
127
+ const extension = result.extension || 'txt';
128
+ const pageUrl = result.pageUrl ?? (page && typeof page.url === 'function' ? page.url() : null);
129
+ writeResourceCache({
130
+ tool,
131
+ cacheInput,
132
+ output,
133
+ rawText: result.rawText ?? output,
134
+ pageUrl,
135
+ metadata,
136
+ extension,
137
+ writeCache,
138
+ });
139
+ writeResourceOutput({ output, outFile, metadata });
140
+ return { status: 'fresh', output, metadata };
141
+ },
142
+ });
143
+ }
@@ -0,0 +1,127 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Scrape all article links + timestamps visible on the current tab.
4
+ * Usage: ./scrape-page.js [--port 9222] [--owner-token token]
5
+ * Outputs JSON: [{headline, href, time}]
6
+ */
7
+ import { realpathSync } from 'node:fs';
8
+ import { fileURLToPath } from 'node:url';
9
+ import { activePage, parseOwnerToken, parsePort } from './browser-control.mjs';
10
+ import { runBrowserResource } from './resource-helper.mjs';
11
+
12
+ const ARTICLE_LIKE_PATH_SEGMENT_PATTERN = /(?:^|\/)(?:articles?|news|stor(?:y|ies)|(?:19|20)\d{2})(?=\/|$)/i;
13
+
14
+ if (isDirectExecution()) await main();
15
+
16
+ async function main() {
17
+ const args = process.argv.slice(2);
18
+ const port = parsePort(args);
19
+ const ownerToken = parseOwnerToken(args);
20
+
21
+ await runBrowserResource({
22
+ port,
23
+ ownerToken,
24
+ getPage: activePage,
25
+ run: async ({ page }) => {
26
+ // Scroll to bottom to trigger lazy-loaded content
27
+ await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight));
28
+ await new Promise(r => setTimeout(r, 2000));
29
+ await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight));
30
+ await new Promise(r => setTimeout(r, 1500));
31
+
32
+ const articles = await page.evaluate((articleLikePathSegmentPatternSource, articleLikePathSegmentPatternFlags) => {
33
+ const articleLikePathSegmentPattern = new RegExp(
34
+ articleLikePathSegmentPatternSource,
35
+ articleLikePathSegmentPatternFlags,
36
+ );
37
+ const isGenericArticleLikeHref = (href) => {
38
+ let pathname = href;
39
+ try {
40
+ pathname = new URL(href, 'https://example.invalid').pathname;
41
+ } catch {
42
+ pathname = href;
43
+ }
44
+
45
+ return articleLikePathSegmentPattern.test(pathname);
46
+ };
47
+ const scrapeVisibleText = (element) => {
48
+ const raw = typeof element?.innerText === 'string'
49
+ ? element.innerText
50
+ : typeof element?.textContent === 'string'
51
+ ? element.textContent
52
+ : '';
53
+ return raw.trim().replace(/\s+/g, ' ');
54
+ };
55
+ const seen = new Set();
56
+ const results = [];
57
+
58
+ // Candidate link selectors (broad)
59
+ const links = Array.from(document.querySelectorAll("a[href]"));
60
+
61
+ for (const a of links) {
62
+ const href = a.href;
63
+ const headline = scrapeVisibleText(a);
64
+
65
+ // Filter: meaningful headlines, article-like URLs
66
+ if (
67
+ headline.length < 25 ||
68
+ headline.length > 250 ||
69
+ seen.has(headline) ||
70
+ !isGenericArticleLikeHref(href)
71
+ ) continue;
72
+
73
+ // Skip nav/footer/promo links
74
+ if (/subscribe|sign.?in|login|newsletter|podcast|video|watch|listen/i.test(headline)) continue;
75
+
76
+ seen.add(headline);
77
+
78
+ // Try to find a timestamp near this link
79
+ let time = "";
80
+ let el = a;
81
+ for (let i = 0; i < 7; i++) {
82
+ el = el.parentElement;
83
+ if (!el) break;
84
+ const ts = el.querySelector("time, [class*='time'], [class*='timestamp'], [class*='date'], [data-testid*='time']");
85
+ if (ts) { time = scrapeVisibleText(ts) || ts.getAttribute("datetime") || ""; break; }
86
+ }
87
+
88
+ results.push({ headline, href, time });
89
+ }
90
+
91
+ return results;
92
+ }, ARTICLE_LIKE_PATH_SEGMENT_PATTERN.source, ARTICLE_LIKE_PATH_SEGMENT_PATTERN.flags);
93
+
94
+ // Deduplicate by href
95
+ const unique = Object.values(
96
+ Object.fromEntries(articles.map(a => [a.href, a]))
97
+ );
98
+
99
+ console.log(JSON.stringify(unique, null, 2));
100
+ },
101
+ });
102
+ }
103
+
104
+ function isDirectExecution() {
105
+ if (!process.argv[1]) return false;
106
+ return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
107
+ }
108
+
109
+ export function scrapeVisibleText(element) {
110
+ const raw = typeof element?.innerText === 'string'
111
+ ? element.innerText
112
+ : typeof element?.textContent === 'string'
113
+ ? element.textContent
114
+ : '';
115
+ return raw.trim().replace(/\s+/g, ' ');
116
+ }
117
+
118
+ export function isGenericArticleLikeHref(href) {
119
+ let pathname = href;
120
+ try {
121
+ pathname = new URL(href, 'https://example.invalid').pathname;
122
+ } catch {
123
+ pathname = href;
124
+ }
125
+
126
+ return ARTICLE_LIKE_PATH_SEGMENT_PATTERN.test(pathname);
127
+ }
@@ -0,0 +1,25 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Take a screenshot of the active tab's viewport.
4
+ * Prints the file path so the agent can read it.
5
+ *
6
+ * Usage:
7
+ * scripts/screenshot.mjs
8
+ * scripts/screenshot.mjs --port 9223
9
+ * scripts/screenshot.mjs --full
10
+ * scripts/screenshot.mjs --owner-token "$BROWSER_TOOLS_OWNER_TOKEN"
11
+ */
12
+
13
+ import { activePage, hasFlag, parseOwnerToken, parsePort, timestampedTmpPath, withBrowser } from './browser-control.mjs';
14
+
15
+ const args = process.argv.slice(2);
16
+ const port = parsePort(args);
17
+ const ownerToken = parseOwnerToken(args);
18
+ const fullPage = hasFlag(args, '--full');
19
+
20
+ await withBrowser(port, async (browser) => {
21
+ const page = await activePage(browser);
22
+ const filepath = timestampedTmpPath('browser-screenshot', 'png');
23
+ await page.screenshot({ path: filepath, fullPage });
24
+ console.log(filepath);
25
+ }, { ownerToken });
@@ -0,0 +1,49 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Start a sandboxed Chrome instance with a synced copy of your profile.
4
+ * Never touches or kills your main Chrome because it uses a separate user-data-dir.
5
+ *
6
+ * Usage:
7
+ * scripts/start.mjs
8
+ * scripts/start.mjs --profile "<Chrome profile folder>"
9
+ * scripts/start.mjs --profile "<Chrome profile folder>" --sync
10
+ * scripts/start.mjs --profile "<Chrome profile folder>" --port 9223
11
+ * scripts/start.mjs --headless (run without opening a browser window)
12
+ * scripts/start.mjs --include-google (keep the Google session in the clone; needed for Google workflows)
13
+ * BROWSER_TOOLS_OWNER_TOKEN="<owner token>" scripts/start.mjs
14
+ */
15
+
16
+ import { hasFlag, requiredOptionValue, parseOwnerId, parseOwnerToken, parsePort, startChrome } from './browser-control.mjs';
17
+
18
+ const args = process.argv.slice(2);
19
+ const profileName = requiredOptionValue(args, '--profile', null);
20
+ const taskName = requiredOptionValue(args, '--task', null);
21
+ const forceProfileSync = hasFlag(args, '--sync');
22
+ const headless = hasFlag(args, '--headless');
23
+ const includeGoogle = hasFlag(args, '--include-google');
24
+ const explicitPort = args.includes('--port');
25
+ const port = parsePort(args);
26
+ const ownerToken = parseOwnerToken(args);
27
+ const ownerId = parseOwnerId(args);
28
+
29
+ try {
30
+ const result = await startChrome({ port, profileName, taskName, forceProfileSync, autoAllocatePort: !explicitPort, ownerToken, ownerId, headless, includeGoogle });
31
+ const mode = result.headless ? ' (headless)' : '';
32
+ if (result.status === 'reused') {
33
+ console.log(`✓ Chrome already running on :${result.port}${mode}; reusing owned instance`);
34
+ } else if (result.requestedProfileName) {
35
+ const resolved = result.profileName && result.profileName !== result.requestedProfileName ? ` resolved to "${result.profileName}"` : '';
36
+ const task = taskName ? ` for task "${taskName}"` : '';
37
+ console.log(`✓ Chrome ready on :${result.port}${mode} with profile "${result.requestedProfileName}"${resolved}${task}`);
38
+ } else {
39
+ console.log(`✓ Chrome ready on :${result.port}${mode} (fresh)`);
40
+ }
41
+ if (result.ownerTokenGenerated) {
42
+ console.log(`Owner token: ${result.ownerToken}`);
43
+ console.log(`Run: export BROWSER_TOOLS_OWNER_TOKEN="${result.ownerToken}"`);
44
+ console.log(`Use with follow-up commands: --port ${result.port}`);
45
+ }
46
+ } catch (e) {
47
+ console.error(`✗ ${e.message}`);
48
+ process.exit(1);
49
+ }
@@ -0,0 +1,51 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Report whether a managed Chrome instance is running for a port.
4
+ * Reads the same managed-state file start.mjs writes and stop.mjs verifies; never launches
5
+ * or connects to Chrome itself.
6
+ *
7
+ * Usage:
8
+ * scripts/status.mjs
9
+ * scripts/status.mjs --port 9223
10
+ * scripts/status.mjs --json
11
+ */
12
+
13
+ import { hasFlag, managedBrowserSafetyForPort, parsePort, readManagedStateForPort } from './browser-control.mjs';
14
+
15
+ const args = process.argv.slice(2);
16
+ const port = parsePort(args);
17
+ const json = hasFlag(args, '--json');
18
+
19
+ const state = readManagedStateForPort(port);
20
+
21
+ if (!state) {
22
+ if (json) console.log(JSON.stringify({ running: false, port }, null, 2));
23
+ else console.log(`No managed Chrome instance found for port ${port}`);
24
+ process.exit(0);
25
+ }
26
+
27
+ const safety = managedBrowserSafetyForPort(port);
28
+ const running = Boolean(safety.ok);
29
+
30
+ const report = {
31
+ running,
32
+ port,
33
+ pid: state.pid ?? null,
34
+ profileName: state.profileName ?? null,
35
+ headless: Boolean(state.headless),
36
+ includeGoogle: Boolean(state.includeGoogle),
37
+ ownerId: state.ownerId ?? null,
38
+ startedAt: state.startedAt ?? null,
39
+ reason: running ? null : safety.reason,
40
+ };
41
+
42
+ if (json) {
43
+ console.log(JSON.stringify(report, null, 2));
44
+ } else if (running) {
45
+ const mode = report.headless ? ' (headless)' : '';
46
+ const profile = report.profileName ? ` profile="${report.profileName}"` : '';
47
+ const owner = report.ownerId ? ` owner=${report.ownerId}` : '';
48
+ console.log(`✓ Managed Chrome running on :${port}${mode} (PID ${report.pid})${profile}${owner}`);
49
+ } else {
50
+ console.log(`✗ Managed state found for :${port}, but the browser is not verified running (${report.reason})`);
51
+ }
@@ -0,0 +1,71 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Stop the sandboxed Chrome instance started by start.mjs.
4
+ * Only kills the PID we spawned, never the main Chrome process.
5
+ *
6
+ * Usage:
7
+ * scripts/stop.mjs
8
+ * scripts/stop.mjs --port 9223
9
+ * scripts/stop.mjs --clean
10
+ * scripts/stop.mjs --dry-run
11
+ * scripts/stop.mjs --prune (remove all cached clones not in use)
12
+ * scripts/stop.mjs --owner-token "$BROWSER_TOOLS_OWNER_TOKEN"
13
+ */
14
+
15
+ import { hasFlag, parseOwnerToken, parsePort, pruneChromeClones, stopChrome } from './browser-control.mjs';
16
+
17
+ const args = process.argv.slice(2);
18
+ const port = parsePort(args);
19
+ const clean = hasFlag(args, '--clean');
20
+ const dryRun = hasFlag(args, '--dry-run');
21
+ const ownerToken = parseOwnerToken(args);
22
+
23
+ if (hasFlag(args, '--prune')) {
24
+ const prune = pruneChromeClones({ dryRun });
25
+ if (!prune.removed.length && !prune.kept.length) {
26
+ console.log('No cached Chrome clones found.');
27
+ }
28
+ for (const entry of prune.kept) {
29
+ console.log(`• Keeping :${entry.port} (in use by PID ${entry.pid})`);
30
+ }
31
+ for (const entry of prune.removed) {
32
+ const count = entry.paths.length;
33
+ console.log(`${dryRun ? '• Would remove' : '✓ Removed'} clone for :${entry.port} (${count} item${count === 1 ? '' : 's'})`);
34
+ }
35
+ process.exit(0);
36
+ }
37
+
38
+ const result = stopChrome({ port, clean, dryRun, ownerToken });
39
+
40
+ if (result.status === 'missing') {
41
+ console.log(`No managed debug Chrome instance found for port ${port}`);
42
+ process.exit(0);
43
+ }
44
+
45
+ if (result.status === 'would-stop') {
46
+ console.log(`✓ Dry run: would stop managed Chrome (PID ${result.pid}) on :${port}`);
47
+ } else if (result.status === 'stopped') {
48
+ console.log(`✓ Stopped managed Chrome (PID ${result.pid}) on :${port}`);
49
+ } else if (result.status === 'killed') {
50
+ console.log(`✓ Killed managed Chrome (PID ${result.pid}) on :${port} after SIGTERM did not exit`);
51
+ } else if (result.status === 'already-gone') {
52
+ console.log(`✓ Managed Chrome (PID ${result.pid}) was already gone`);
53
+ } else if (result.status === 'not-managed') {
54
+ const target = result.pid ? `PID ${result.pid}` : `port ${port}`;
55
+ console.error(`✗ Refusing to stop ${target}: ${result.reason}`);
56
+ console.error(' Safety rule: stop.mjs only kills Chrome processes launched by start.mjs.');
57
+ process.exit(1);
58
+ } else if (result.status === 'not-owned') {
59
+ const owner = result.ownerId ? ` owned by ${result.ownerId}` : '';
60
+ console.error(`✗ Refusing to stop managed Chrome on :${port}${owner}: ${result.reason}`);
61
+ console.error(' Safety rule: provide the same --owner-token that start.mjs printed for this browser.');
62
+ process.exit(1);
63
+ } else if (result.status === 'locked') {
64
+ console.error(`✗ Refusing to stop managed Chrome on :${port}: ${result.reason}`);
65
+ console.error(' A start operation is still claiming this port. Retry after it finishes.');
66
+ process.exit(1);
67
+ } else {
68
+ console.error(`✗ Failed to stop Chrome: ${result.error?.message || 'unknown error'}`);
69
+ }
70
+
71
+ if (result.cleaned) console.log('✓ Cleaned up cached profile copy');