@rezkam/browser-tools 0.2.1 → 1.0.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,111 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Send owner-protected CDP calls to the active managed-browser tab.
4
+ *
5
+ * Usage:
6
+ * scripts/cdp.mjs call Runtime.evaluate --params '{"expression":"document.title"}'
7
+ * scripts/cdp.mjs call Network.getCookies --params-file ./params.json --redact
8
+ */
9
+
10
+ import { readFileSync, realpathSync } from 'node:fs';
11
+ import { fileURLToPath } from 'node:url';
12
+ import {
13
+ OWNER_TOKEN_ENV,
14
+ hasFlag,
15
+ parseOwnerToken,
16
+ parsePort,
17
+ requiredOptionValue,
18
+ } from './browser-control.mjs';
19
+ import {
20
+ redactBodyText,
21
+ redactSensitive,
22
+ validateCdpMethod,
23
+ withPageCdpSession,
24
+ } from './cdp-common.mjs';
25
+
26
+ const SCRIPT_FILE = fileURLToPath(import.meta.url);
27
+
28
+ function usage() {
29
+ console.error(`Usage: browser-tools cdp call <Domain.method> [options]
30
+
31
+ Options:
32
+ --params <json> CDP parameters as a JSON object
33
+ --params-file <path> Read parameters from a file instead of process arguments
34
+ --redact Redact sensitive-looking values from the result
35
+ --port <n> Managed browser port (default: 9222)
36
+ --owner-token <token> Prefer ${OWNER_TOKEN_ENV} instead
37
+
38
+ Direct calls target the active tab and require its owner token. Methods that bypass
39
+ managed-browser lifecycle safety are blocked. Prefer --params-file for sensitive input.`);
40
+ }
41
+
42
+ function parseParams(args) {
43
+ const inline = requiredOptionValue(args, '--params', null);
44
+ const file = requiredOptionValue(args, '--params-file', null);
45
+ if (inline && file) throw new Error('Use only one of --params or --params-file');
46
+ const source = file ? readFileSync(file, 'utf-8') : (inline || '{}');
47
+ let params;
48
+ try {
49
+ params = JSON.parse(source);
50
+ } catch (error) {
51
+ throw new Error(`Invalid CDP params JSON: ${error.message}`);
52
+ }
53
+ if (!params || typeof params !== 'object' || Array.isArray(params)) {
54
+ throw new Error('CDP params must be a JSON object');
55
+ }
56
+ return params;
57
+ }
58
+
59
+ export function sanitizeCdpCallResult(method, result, { redact = false } = {}) {
60
+ if (!redact) return result;
61
+ const output = redactSensitive(result);
62
+ if ((method === 'Network.getResponseBody' || method === 'Fetch.getResponseBody') && output.body && !output.base64Encoded) {
63
+ output.body = redactBodyText(output.body, '');
64
+ }
65
+ if (method === 'Network.getRequestPostData' && output.postData) {
66
+ output.postData = redactBodyText(output.postData, '');
67
+ }
68
+ return output;
69
+ }
70
+
71
+ async function callMethod(args) {
72
+ const method = validateCdpMethod(args[0]);
73
+ const rest = args.slice(1);
74
+ const port = parsePort(rest);
75
+ const ownerToken = parseOwnerToken(rest);
76
+ if (!ownerToken) {
77
+ throw new Error(`Missing browser owner token. Export ${OWNER_TOKEN_ENV} with the token printed by browser-tools start`);
78
+ }
79
+ const params = parseParams(rest);
80
+ const result = await withPageCdpSession(port, ownerToken, ({ session }) => session.send(method, params));
81
+ const output = sanitizeCdpCallResult(method, result, { redact: hasFlag(rest, '--redact') });
82
+ console.log(JSON.stringify(output, null, 2));
83
+ }
84
+
85
+ export async function main(args = process.argv.slice(2)) {
86
+ const [command] = args;
87
+ if (!command || command === '--help' || command === '-h') {
88
+ usage();
89
+ return command ? 0 : 1;
90
+ }
91
+ if (command === 'call') await callMethod(args.slice(1));
92
+ else {
93
+ usage();
94
+ throw new Error(`Unknown cdp command: ${command}`);
95
+ }
96
+ return 0;
97
+ }
98
+
99
+ function isDirectExecution() {
100
+ if (!process.argv[1]) return false;
101
+ return realpathSync(process.argv[1]) === realpathSync(SCRIPT_FILE);
102
+ }
103
+
104
+ if (isDirectExecution()) {
105
+ try {
106
+ process.exitCode = await main();
107
+ } catch (error) {
108
+ console.error(`✗ ${error.message}`);
109
+ process.exitCode = 1;
110
+ }
111
+ }
@@ -0,0 +1,227 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Extract a compact chronological network recipe from a HAR file for agent analysis.
4
+ * This command never replays requests.
5
+ *
6
+ * Usage:
7
+ * scripts/extract-har.mjs ./checkout_api_network.har
8
+ * scripts/extract-har.mjs ./checkout_api_network.har --output ./checkout_api_recipe.json
9
+ */
10
+
11
+ import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
12
+ import { basename, dirname, extname, join, parse, resolve } from 'node:path';
13
+ import { fileURLToPath } from 'node:url';
14
+ import { hasFlag, optionValue, requiredOptionValue } from './browser-control.mjs';
15
+ import {
16
+ isSensitiveName,
17
+ matchesPatterns,
18
+ matchesStatus,
19
+ normalizeResourceTypes,
20
+ optionValues,
21
+ patternOptionValues,
22
+ parseStatusSelectors,
23
+ privateOutputPath,
24
+ redactBodyText,
25
+ redactSensitive,
26
+ resourceTypesForPreset,
27
+ writePrivateJson,
28
+ } from './cdp-common.mjs';
29
+
30
+ const SCRIPT_FILE = fileURLToPath(import.meta.url);
31
+
32
+ function usage() {
33
+ console.error(`Usage: browser-tools extract-har <capture.har> [options]
34
+
35
+ Options:
36
+ --output <meaningful.json> Recipe output path
37
+ --preset <api|page|all> Resource preset (default: api)
38
+ --resource-type <types> Include CDP resource types
39
+ --exclude-resource-type <types>
40
+ --url-pattern <glob> Include URL glob, repeatable
41
+ --exclude-url-pattern <glob>
42
+ --method <methods>
43
+ --exclude-method <methods>
44
+ --status <code|range>
45
+ --exclude-status <code|range>
46
+ --mime-type <glob>
47
+ --exclude-mime-type <glob>
48
+ --redact Redact sensitive-looking values from the recipe
49
+ --overwrite Replace an existing recipe
50
+ --json Print extraction metadata as JSON
51
+
52
+ The recipe preserves chronological request structure for an agent to inspect and use
53
+ when writing a separate fetch, curl, or browser-backed replay script. It never executes requests.`);
54
+ }
55
+
56
+ function harInputPath(value) {
57
+ if (!value || value.startsWith('--')) throw new Error('Missing HAR path');
58
+ const path = resolve(value);
59
+ if (extname(path).toLowerCase() !== '.har') throw new Error(`HAR input must end in .har: ${value}`);
60
+ if (!existsSync(path) || !statSync(path).isFile()) throw new Error(`HAR input not found: ${path}`);
61
+ return path;
62
+ }
63
+
64
+ function defaultOutputPath(input) {
65
+ const stem = parse(basename(input)).name.replace(/[^a-zA-Z0-9._-]/g, '-');
66
+ return join(dirname(input), `${stem}-recipe.json`);
67
+ }
68
+
69
+ export function parseHarRecipeOptions(args) {
70
+ const preset = String(optionValue(args, '--preset', 'api')).toLowerCase();
71
+ const explicitTypes = normalizeResourceTypes(optionValues(args, '--resource-type'));
72
+ const presetTypes = explicitTypes.length && !args.includes('--preset') ? [] : resourceTypesForPreset(preset);
73
+ return {
74
+ preset,
75
+ resourceTypes: [...new Set([...presetTypes, ...explicitTypes])],
76
+ excludedResourceTypes: normalizeResourceTypes(optionValues(args, '--exclude-resource-type')),
77
+ urlPatterns: patternOptionValues(args, '--url-pattern'),
78
+ excludedUrlPatterns: patternOptionValues(args, '--exclude-url-pattern'),
79
+ methods: optionValues(args, '--method').map((method) => method.toUpperCase()),
80
+ excludedMethods: optionValues(args, '--exclude-method').map((method) => method.toUpperCase()),
81
+ statuses: parseStatusSelectors(optionValues(args, '--status')),
82
+ excludedStatuses: parseStatusSelectors(optionValues(args, '--exclude-status')),
83
+ mimeTypes: optionValues(args, '--mime-type'),
84
+ excludedMimeTypes: optionValues(args, '--exclude-mime-type'),
85
+ redact: hasFlag(args, '--redact'),
86
+ };
87
+ }
88
+
89
+ function entryMatches(entry, options) {
90
+ const type = entry._resourceType || 'Other';
91
+ const method = String(entry.request?.method || '').toUpperCase();
92
+ const status = Number(entry.response?.status || 0);
93
+ const mimeType = entry.response?.content?.mimeType || '';
94
+ if (!options.resourceTypes.includes(type) || options.excludedResourceTypes.includes(type)) return false;
95
+ if (options.methods.length && !options.methods.includes(method)) return false;
96
+ if (options.excludedMethods.includes(method)) return false;
97
+ if (!matchesPatterns(entry.request?.url, options.urlPatterns, options.excludedUrlPatterns)) return false;
98
+ if (!matchesStatus(status, options.statuses, options.excludedStatuses)) return false;
99
+ return matchesPatterns(mimeType, options.mimeTypes, options.excludedMimeTypes);
100
+ }
101
+
102
+ function headerObject(headers = []) {
103
+ return Object.fromEntries(headers.map((header) => [String(header.name).toLowerCase(), String(header.value)]));
104
+ }
105
+
106
+ function bodyRecipe(value, mimeType = '', encoding = null, { redact = false } = {}) {
107
+ if (value === undefined) return null;
108
+ const text = redact && !encoding ? redactBodyText(value, mimeType) : value;
109
+ const result = { mime_type: mimeType || 'application/octet-stream', text };
110
+ if (encoding) result.encoding = encoding;
111
+ if (!encoding && (String(mimeType).toLowerCase().includes('json') || /^[\s]*[\[{]/.test(String(value)))) {
112
+ try {
113
+ result.json = JSON.parse(text);
114
+ } catch {
115
+ // Keep malformed or truncated JSON as text only.
116
+ }
117
+ }
118
+ return result;
119
+ }
120
+
121
+ export function extractHarRecipe(har, sourceHar, options) {
122
+ const entries = Array.isArray(har?.log?.entries) ? har.log.entries : null;
123
+ if (!entries) throw new Error(`Invalid HAR 1.2 log: ${sourceHar}`);
124
+ const requests = entries
125
+ .filter((entry) => entryMatches(entry, options))
126
+ .map((entry, index) => ({
127
+ sequence: index + 1,
128
+ started_at: entry.startedDateTime || null,
129
+ resource_type: entry._resourceType || 'Other',
130
+ method: entry.request.method,
131
+ url: entry.request.url,
132
+ headers: headerObject(entry.request.headers),
133
+ query: (entry.request.queryString || []).map((parameter) => ({
134
+ ...parameter,
135
+ value: options.redact && isSensitiveName(parameter.name) ? '<redacted>' : parameter.value,
136
+ })),
137
+ body: bodyRecipe(
138
+ entry.request.postData?.text,
139
+ entry.request.postData?.mimeType,
140
+ null,
141
+ { redact: options.redact },
142
+ ),
143
+ response: {
144
+ status: entry.response.status,
145
+ status_text: entry.response.statusText,
146
+ headers: headerObject(entry.response.headers),
147
+ mime_type: entry.response.content?.mimeType || '',
148
+ body: bodyRecipe(
149
+ entry.response.content?.text,
150
+ entry.response.content?.mimeType,
151
+ entry.response.content?.encoding || null,
152
+ { redact: options.redact },
153
+ ),
154
+ },
155
+ timing: {
156
+ total_ms: entry.time,
157
+ ...entry.timings,
158
+ },
159
+ failure: entry._failure || null,
160
+ }));
161
+
162
+ const recipe = {
163
+ version: 1,
164
+ kind: 'browser-tools-network-recipe',
165
+ source_har: sourceHar,
166
+ generated_at: new Date().toISOString(),
167
+ filters: {
168
+ preset: options.preset,
169
+ resource_types: options.resourceTypes,
170
+ excluded_resource_types: options.excludedResourceTypes,
171
+ url_patterns: options.urlPatterns,
172
+ excluded_url_patterns: options.excludedUrlPatterns,
173
+ methods: options.methods,
174
+ excluded_methods: options.excludedMethods,
175
+ statuses: options.statuses,
176
+ excluded_statuses: options.excludedStatuses,
177
+ mime_types: options.mimeTypes,
178
+ excluded_mime_types: options.excludedMimeTypes,
179
+ },
180
+ request_count: requests.length,
181
+ requests,
182
+ notes: [
183
+ 'This file describes captured requests but does not execute them.',
184
+ 'Validate dynamic tokens, cookies, ordering dependencies, and side effects before writing or running a replay script.',
185
+ ],
186
+ };
187
+ return options.redact ? redactSensitive(recipe) : recipe;
188
+ }
189
+
190
+ export async function main(args = process.argv.slice(2)) {
191
+ if (!args.length || args[0] === '--help' || args[0] === '-h') {
192
+ usage();
193
+ return args.length ? 0 : 1;
194
+ }
195
+ const input = harInputPath(args[0]);
196
+ const rest = args.slice(1);
197
+ const overwrite = hasFlag(rest, '--overwrite');
198
+ const requestedOutput = requiredOptionValue(rest, '--output', null) || defaultOutputPath(input);
199
+ const output = privateOutputPath(requestedOutput, 'json', { overwrite });
200
+ const options = parseHarRecipeOptions(rest);
201
+ const har = JSON.parse(readFileSync(input, 'utf-8'));
202
+ const recipe = extractHarRecipe(har, input, options);
203
+ writePrivateJson(output, recipe);
204
+
205
+ const report = { input, output, request_count: recipe.request_count };
206
+ if (hasFlag(rest, '--json')) console.log(JSON.stringify(report, null, 2));
207
+ else {
208
+ console.log(`HAR: ${input}`);
209
+ console.log(`Recipe: ${output}`);
210
+ console.log(`Requests: ${recipe.request_count}`);
211
+ }
212
+ return 0;
213
+ }
214
+
215
+ function isDirectExecution() {
216
+ if (!process.argv[1]) return false;
217
+ return realpathSync(process.argv[1]) === realpathSync(SCRIPT_FILE);
218
+ }
219
+
220
+ if (isDirectExecution()) {
221
+ try {
222
+ process.exitCode = await main();
223
+ } catch (error) {
224
+ console.error(`✗ ${error.message}`);
225
+ process.exitCode = 1;
226
+ }
227
+ }