@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.
- package/README.md +33 -1
- package/bin/browser-tools.mjs +12 -0
- package/package.json +4 -3
- package/scripts/browser-control.mjs +774 -74
- package/scripts/cdp-common.mjs +309 -0
- package/scripts/cdp-event-capture.mjs +139 -0
- package/scripts/cdp-recording-state.mjs +160 -0
- package/scripts/cdp.mjs +111 -0
- package/scripts/extract-har.mjs +227 -0
- package/scripts/gif-recorder.mjs +451 -0
- package/scripts/har-capture.mjs +485 -0
- package/scripts/record-cdp.mjs +261 -0
- package/scripts/record-gif.mjs +234 -0
- package/scripts/record-har.mjs +270 -0
- package/scripts/review-gif.mjs +203 -0
- package/scripts/start.mjs +2 -2
- package/scripts/stop.mjs +60 -5
package/scripts/cdp.mjs
ADDED
|
@@ -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
|
+
}
|