@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,309 @@
1
+ import {
2
+ chmodSync,
3
+ closeSync,
4
+ existsSync,
5
+ mkdirSync,
6
+ openSync,
7
+ renameSync,
8
+ writeFileSync,
9
+ } from 'node:fs';
10
+ import { basename, dirname, extname, parse, resolve } from 'node:path';
11
+ import { activePage, connectBrowser } from './browser-control.mjs';
12
+
13
+ export const HAR_RESOURCE_TYPES = [
14
+ 'Document',
15
+ 'Stylesheet',
16
+ 'Image',
17
+ 'Media',
18
+ 'Font',
19
+ 'Script',
20
+ 'TextTrack',
21
+ 'XHR',
22
+ 'Fetch',
23
+ 'Prefetch',
24
+ 'EventSource',
25
+ 'Manifest',
26
+ 'SignedExchange',
27
+ 'Ping',
28
+ 'CSPViolationReport',
29
+ 'Preflight',
30
+ 'FedCM',
31
+ 'Other',
32
+ ];
33
+
34
+ export const HAR_RESOURCE_PRESETS = {
35
+ api: ['XHR', 'Fetch', 'Preflight', 'EventSource'],
36
+ page: ['Document', 'Script', 'Stylesheet', 'XHR', 'Fetch'],
37
+ all: [...HAR_RESOURCE_TYPES],
38
+ };
39
+
40
+ export const BLOCKED_CDP_METHODS = new Set([
41
+ 'Browser.close',
42
+ 'Browser.crash',
43
+ 'Page.close',
44
+ 'Page.crash',
45
+ 'Target.attachToBrowserTarget',
46
+ 'Target.closeTarget',
47
+ 'Target.detachFromTarget',
48
+ 'Target.disposeBrowserContext',
49
+ 'Target.sendMessageToTarget',
50
+ ]);
51
+
52
+ const SENSITIVE_NAME = /(?:^|[-_])(?:authorization|proxy[-_]?authorization|cookie|set[-_]?cookie|api[-_]?key|access[-_]?token|refresh[-_]?token|id[-_]?token|token|secret|password|passwd|session|csrf|xsrf)(?:$|[-_])/i;
53
+ const URL_HEADER_NAME = /^(?:content-location|location|origin|referer|referrer)$/i;
54
+ const GENERIC_CAPTURE_STEMS = new Set(['capture', 'network', 'output', 'recording', 'trace', 'untitled', 'test']);
55
+
56
+ export function validateCdpMethod(value, { allowBlocked = false } = {}) {
57
+ if (!value || !/^[A-Z][A-Za-z0-9]*\.[a-zA-Z][A-Za-z0-9]*$/.test(value)) {
58
+ throw new Error(`Invalid CDP method: ${value || '<missing>'}. Expected Domain.method`);
59
+ }
60
+ if (!allowBlocked && BLOCKED_CDP_METHODS.has(value)) {
61
+ throw new Error(`CDP method ${value} is blocked because it bypasses managed-browser lifecycle safety`);
62
+ }
63
+ return value;
64
+ }
65
+
66
+ export function rawOptionValues(args, name) {
67
+ const values = [];
68
+ for (let index = 0; index < args.length; index += 1) {
69
+ if (args[index] !== name) continue;
70
+ const value = args[index + 1];
71
+ if (value === undefined || value.startsWith('--')) throw new Error(`Missing value after ${name}`);
72
+ values.push(String(value));
73
+ index += 1;
74
+ }
75
+ return values;
76
+ }
77
+
78
+ export function optionValues(args, name) {
79
+ return rawOptionValues(args, name)
80
+ .flatMap((value) => value.split(',').map((part) => part.trim()).filter(Boolean));
81
+ }
82
+
83
+ export function patternOptionValues(args, name) {
84
+ return rawOptionValues(args, name).map((value) => value.trim()).filter(Boolean);
85
+ }
86
+
87
+ export function normalizeResourceTypes(values, { allowEmpty = true } = {}) {
88
+ if (!values.length && allowEmpty) return [];
89
+ const canonical = new Map(HAR_RESOURCE_TYPES.map((type) => [type.toLowerCase(), type]));
90
+ return [...new Set(values.map((value) => {
91
+ const type = canonical.get(String(value).toLowerCase());
92
+ if (!type) throw new Error(`Unsupported HAR resource type: ${value}. Expected one of: ${HAR_RESOURCE_TYPES.join(', ')}`);
93
+ return type;
94
+ }))];
95
+ }
96
+
97
+ export function resourceTypesForPreset(preset = 'all') {
98
+ const types = HAR_RESOURCE_PRESETS[String(preset).toLowerCase()];
99
+ if (!types) throw new Error(`Unknown capture preset: ${preset}. Expected api, page, or all`);
100
+ return [...types];
101
+ }
102
+
103
+ export function globToRegExp(pattern) {
104
+ let source = '';
105
+ for (const character of String(pattern)) {
106
+ if (character === '*') source += '.*';
107
+ else if (character === '?') source += '.';
108
+ else source += character.replace(/[|\\{}()[\]^$+?.]/g, '\\$&');
109
+ }
110
+ return new RegExp(`^${source}$`, 'i');
111
+ }
112
+
113
+ export function matchesPatterns(value, includes = [], excludes = []) {
114
+ const text = String(value ?? '');
115
+ if (excludes.some((pattern) => globToRegExp(pattern).test(text))) return false;
116
+ return !includes.length || includes.some((pattern) => globToRegExp(pattern).test(text));
117
+ }
118
+
119
+ export function parseStatusSelectors(values) {
120
+ return values.map((value) => {
121
+ const match = String(value).match(/^(\d{3})(?:-(\d{3}))?$/);
122
+ if (!match) throw new Error(`Invalid status selector: ${value}. Use a code or range such as 200-299`);
123
+ const start = Number(match[1]);
124
+ const end = Number(match[2] || match[1]);
125
+ if (end < start) throw new Error(`Invalid status selector range: ${value}`);
126
+ return { start, end };
127
+ });
128
+ }
129
+
130
+ export function matchesStatus(status, includes = [], excludes = []) {
131
+ const number = Number(status);
132
+ const matches = (selector) => number >= selector.start && number <= selector.end;
133
+ if (excludes.some(matches)) return false;
134
+ return !includes.length || includes.some(matches);
135
+ }
136
+
137
+ export function redactUrl(value, { includeSensitive = false } = {}) {
138
+ if (includeSensitive) return value;
139
+ const text = String(value);
140
+ try {
141
+ const url = new URL(text);
142
+ for (const key of [...url.searchParams.keys()]) {
143
+ if (isSensitiveName(key)) url.searchParams.set(key, '<redacted>');
144
+ }
145
+ return url.toString();
146
+ } catch {
147
+ const hashIndex = text.indexOf('#');
148
+ const beforeHash = hashIndex >= 0 ? text.slice(0, hashIndex) : text;
149
+ const hash = hashIndex >= 0 ? text.slice(hashIndex) : '';
150
+ const queryIndex = beforeHash.indexOf('?');
151
+ if (queryIndex < 0) return value;
152
+ const params = new URLSearchParams(beforeHash.slice(queryIndex + 1));
153
+ let changed = false;
154
+ for (const key of [...params.keys()]) {
155
+ if (isSensitiveName(key)) {
156
+ params.set(key, '<redacted>');
157
+ changed = true;
158
+ }
159
+ }
160
+ return changed ? `${beforeHash.slice(0, queryIndex)}?${params}${hash}` : value;
161
+ }
162
+ }
163
+
164
+ export function isSensitiveName(name) {
165
+ const normalized = String(name).replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
166
+ return SENSITIVE_NAME.test(normalized);
167
+ }
168
+
169
+ export function redactSensitive(value, { includeSensitive = false, parentKey = '' } = {}) {
170
+ if (includeSensitive || value === null || value === undefined) return value;
171
+ if (Array.isArray(value)) {
172
+ return value.map((item) => redactSensitive(item, { includeSensitive, parentKey }));
173
+ }
174
+ if (typeof value !== 'object') return value;
175
+
176
+ const result = {};
177
+ for (const [key, child] of Object.entries(value)) {
178
+ if (/headersText$/i.test(key) && typeof child === 'string') {
179
+ result[key] = '<redacted>';
180
+ continue;
181
+ }
182
+ if (/(?:^|_)(?:url|documenturl|redirecturl)$/i.test(key) && typeof child === 'string') {
183
+ result[key] = redactUrl(child, { includeSensitive });
184
+ continue;
185
+ }
186
+ if (/cookies?/i.test(key) && child && typeof child === 'object') {
187
+ result[key] = redactSensitive(child, { includeSensitive, parentKey: 'cookies' });
188
+ continue;
189
+ }
190
+ if (isSensitiveName(key)) {
191
+ result[key] = '<redacted>';
192
+ continue;
193
+ }
194
+ if (URL_HEADER_NAME.test(key) && typeof child === 'string') {
195
+ result[key] = redactUrl(child, { includeSensitive });
196
+ continue;
197
+ }
198
+ if (key === 'value' && isSensitiveName(value.name)) {
199
+ result[key] = '<redacted>';
200
+ continue;
201
+ }
202
+ if (key === 'value' && URL_HEADER_NAME.test(value.name) && typeof child === 'string') {
203
+ result[key] = redactUrl(child, { includeSensitive });
204
+ continue;
205
+ }
206
+ if (key === 'value' && /cookies?|associatedcookies/i.test(parentKey)) {
207
+ result[key] = '<redacted>';
208
+ continue;
209
+ }
210
+ if (key === 'payloadData' && /websocket/i.test(parentKey)) {
211
+ result[key] = '<redacted>';
212
+ continue;
213
+ }
214
+ result[key] = redactSensitive(child, { includeSensitive, parentKey: key });
215
+ }
216
+ return result;
217
+ }
218
+
219
+ export function redactHeaders(headers = {}, { includeSensitive = false } = {}) {
220
+ return Object.entries(headers).map(([name, value]) => ({
221
+ name,
222
+ value: includeSensitive
223
+ ? String(value)
224
+ : (isSensitiveName(name)
225
+ ? '<redacted>'
226
+ : (URL_HEADER_NAME.test(name) ? redactUrl(value) : String(value))),
227
+ }));
228
+ }
229
+
230
+ export function redactBodyText(text, mimeType = '', { includeSensitive = false } = {}) {
231
+ if (includeSensitive || text === undefined || text === null) return text;
232
+ const value = String(text);
233
+ const normalizedMime = String(mimeType).toLowerCase();
234
+ if (normalizedMime.includes('json') || /^[\s]*[\[{]/.test(value)) {
235
+ try {
236
+ return JSON.stringify(redactSensitive(JSON.parse(value)));
237
+ } catch {
238
+ return '<redacted: malformed JSON>';
239
+ }
240
+ }
241
+ const looksFormEncoded = normalizedMime.includes('application/x-www-form-urlencoded')
242
+ || value.split('&').every((part) => /^[^=&\s]+=[^&]*$/.test(part));
243
+ if (looksFormEncoded) {
244
+ const params = new URLSearchParams(value);
245
+ let changed = false;
246
+ for (const key of [...params.keys()]) {
247
+ if (isSensitiveName(key)) {
248
+ params.set(key, '<redacted>');
249
+ changed = true;
250
+ }
251
+ }
252
+ return changed ? params.toString() : value;
253
+ }
254
+ return value;
255
+ }
256
+
257
+ export function openPrivateFile(file, flags) {
258
+ const fd = openSync(file, flags, 0o600);
259
+ try {
260
+ chmodSync(file, 0o600);
261
+ return fd;
262
+ } catch (error) {
263
+ closeSync(fd);
264
+ throw new Error(`Could not make capture output private: ${file}: ${error.message}`);
265
+ }
266
+ }
267
+
268
+ export function privateOutputPath(value, extension, { overwrite = false, cwd = process.cwd() } = {}) {
269
+ if (!value || value === true || !String(value).trim()) {
270
+ throw new Error(`Missing --output. Use a meaningful interaction-specific .${extension} filename`);
271
+ }
272
+ const path = resolve(cwd, String(value));
273
+ if (extname(path).toLowerCase() !== `.${extension.toLowerCase()}`) {
274
+ throw new Error(`Capture output must end in .${extension}: ${value}`);
275
+ }
276
+ const stem = parse(basename(path)).name.toLowerCase().replace(/[^a-z0-9]/g, '');
277
+ if (GENERIC_CAPTURE_STEMS.has(stem)) {
278
+ throw new Error(`Capture output name is too generic: ${basename(path)}. Describe the interaction, for example checkout_api_network.${extension}`);
279
+ }
280
+ mkdirSync(dirname(path), { recursive: true });
281
+ if (existsSync(path) && !overwrite) {
282
+ throw new Error(`Capture output already exists: ${path}. Choose another meaningful name or pass --overwrite`);
283
+ }
284
+ return path;
285
+ }
286
+
287
+ export function writePrivateJson(file, value) {
288
+ const temporary = `${file}.${process.pid}.tmp`;
289
+ writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
290
+ renameSync(temporary, file);
291
+ try {
292
+ chmodSync(file, 0o600);
293
+ } catch {
294
+ // Best effort. Capture output may contain private request data.
295
+ }
296
+ }
297
+
298
+ export async function withPageCdpSession(port, ownerToken, callback) {
299
+ const browser = await connectBrowser(port, { ownerToken });
300
+ let session;
301
+ try {
302
+ const page = await activePage(browser);
303
+ session = await page.createCDPSession();
304
+ return await callback({ browser, page, session });
305
+ } finally {
306
+ if (session && !session.detached) await session.detach().catch(() => {});
307
+ browser.disconnect();
308
+ }
309
+ }
@@ -0,0 +1,139 @@
1
+ import { hasFlag, parsePositiveIntegerOption, sleep } from './browser-control.mjs';
2
+ import {
3
+ matchesPatterns,
4
+ optionValues,
5
+ rawOptionValues,
6
+ redactBodyText,
7
+ redactSensitive,
8
+ validateCdpMethod,
9
+ } from './cdp-common.mjs';
10
+
11
+ export const DEFAULT_CDP_POST_WAIT_MS = 500;
12
+ export const DEFAULT_CDP_MAX_DURATION_SECONDS = 300;
13
+ export const DEFAULT_CDP_MAX_EVENTS = 100000;
14
+
15
+ function validateDomain(domain) {
16
+ if (!/^[A-Z][A-Za-z0-9]*$/.test(domain)) throw new Error(`Invalid CDP domain: ${domain}`);
17
+ return domain;
18
+ }
19
+
20
+ function validateEventPattern(pattern) {
21
+ if (!/^[A-Z*][A-Za-z0-9*?]*\.[A-Za-z0-9*?]+$/.test(pattern)) {
22
+ throw new Error(`Invalid CDP event pattern: ${pattern}. Use Domain.event or Domain.*`);
23
+ }
24
+ return pattern;
25
+ }
26
+
27
+ function parseSetupCommand(value) {
28
+ let command;
29
+ if (String(value).trim().startsWith('{')) {
30
+ try {
31
+ command = JSON.parse(value);
32
+ } catch (error) {
33
+ throw new Error(`Invalid --setup JSON: ${error.message}`);
34
+ }
35
+ } else {
36
+ command = { method: value, params: {} };
37
+ }
38
+ const method = validateCdpMethod(command.method);
39
+ const params = command.params ?? {};
40
+ if (!params || typeof params !== 'object' || Array.isArray(params)) {
41
+ throw new Error(`CDP setup params for ${method} must be a JSON object`);
42
+ }
43
+ return { method, params };
44
+ }
45
+
46
+ export function parseCdpEventCaptureOptions(args) {
47
+ const eventPatterns = optionValues(args, '--event').map(validateEventPattern);
48
+ const excludedEventPatterns = optionValues(args, '--exclude-event').map(validateEventPattern);
49
+ const explicitDomains = optionValues(args, '--domain').map(validateDomain);
50
+ const inferredDomains = eventPatterns
51
+ .map((pattern) => pattern.split('.')[0])
52
+ .filter((domain) => !domain.includes('*') && !domain.includes('?'))
53
+ .map(validateDomain);
54
+ const domains = [...new Set([...explicitDomains, ...inferredDomains])];
55
+ if (!domains.length) domains.push('Network');
56
+ const skippedDomainEnables = optionValues(args, '--skip-enable').map(validateDomain);
57
+ const setupCommands = rawOptionValues(args, '--setup').map(parseSetupCommand);
58
+
59
+ return {
60
+ domains,
61
+ skippedDomainEnables,
62
+ setupCommands,
63
+ eventPatterns: eventPatterns.length ? eventPatterns : domains.map((domain) => `${domain}.*`),
64
+ excludedEventPatterns,
65
+ postWaitMs: parsePositiveIntegerOption(args, '--post-wait-ms', DEFAULT_CDP_POST_WAIT_MS),
66
+ maxDurationSeconds: parsePositiveIntegerOption(args, '--max-duration', DEFAULT_CDP_MAX_DURATION_SECONDS),
67
+ maxEvents: parsePositiveIntegerOption(args, '--max-events', DEFAULT_CDP_MAX_EVENTS),
68
+ redact: hasFlag(args, '--redact'),
69
+ };
70
+ }
71
+
72
+ function headerValue(headers, wanted) {
73
+ const match = Object.entries(headers || {}).find(([name]) => name.toLowerCase() === wanted.toLowerCase());
74
+ return match ? String(match[1]) : '';
75
+ }
76
+
77
+ export function sanitizeCdpEvent(method, params, { redact = false } = {}) {
78
+ if (!redact) return params;
79
+ const sanitized = redactSensitive(params);
80
+ if (method === 'Network.requestWillBeSent') {
81
+ if (sanitized.request?.postData !== undefined) {
82
+ const mimeType = headerValue(sanitized.request.headers, 'content-type');
83
+ sanitized.request.postData = redactBodyText(sanitized.request.postData, mimeType);
84
+ }
85
+ if (sanitized.request?.postDataEntries !== undefined) sanitized.request.postDataEntries = '<redacted>';
86
+ }
87
+ if (method === 'Network.webSocketFrameSent' || method === 'Network.webSocketFrameReceived') {
88
+ if (sanitized.response?.payloadData !== undefined) sanitized.response.payloadData = '<redacted>';
89
+ }
90
+ if (method === 'Network.eventSourceMessageReceived' && sanitized.data !== undefined) {
91
+ sanitized.data = '<redacted>';
92
+ }
93
+ return sanitized;
94
+ }
95
+
96
+ export async function runCdpEventCapture({
97
+ session,
98
+ options,
99
+ shouldStop,
100
+ writeEvent,
101
+ onPhase = () => {},
102
+ }) {
103
+ let eventCount = 0;
104
+ const startedMonotonic = performance.now();
105
+ const onAnyEvent = (method, params) => {
106
+ if (eventCount >= options.maxEvents) return;
107
+ if (typeof method !== 'string') return;
108
+ if (!matchesPatterns(method, options.eventPatterns, options.excludedEventPatterns)) return;
109
+ writeEvent({
110
+ timestamp: new Date().toISOString(),
111
+ elapsed_ms: Number((performance.now() - startedMonotonic).toFixed(3)),
112
+ method,
113
+ params: sanitizeCdpEvent(method, params, options),
114
+ });
115
+ eventCount += 1;
116
+ };
117
+ session.on('*', onAnyEvent);
118
+
119
+ for (const domain of options.domains) {
120
+ if (options.skippedDomainEnables.includes(domain)) continue;
121
+ try {
122
+ await session.send(`${domain}.enable`);
123
+ } catch (error) {
124
+ throw new Error(`Could not enable CDP domain ${domain}: ${error.message}. Use --skip-enable ${domain} and --setup when the domain needs a different activation method.`);
125
+ }
126
+ }
127
+ for (const command of options.setupCommands) {
128
+ await session.send(command.method, command.params);
129
+ }
130
+ await onPhase('recording');
131
+
132
+ const deadline = Date.now() + options.maxDurationSeconds * 1000;
133
+ while (!shouldStop() && Date.now() < deadline && eventCount < options.maxEvents) await sleep(100);
134
+ const reason = shouldStop() ? 'requested' : (eventCount >= options.maxEvents ? 'max-events' : 'max-duration');
135
+ await onPhase('post-wait', reason);
136
+ await sleep(options.postWaitMs);
137
+ session.off('*', onAnyEvent);
138
+ return { reason, eventCount };
139
+ }
@@ -0,0 +1,160 @@
1
+ import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
2
+ import { join } from 'node:path';
3
+ import {
4
+ OWNER_TOKEN_ENV,
5
+ browserToolsCacheDir,
6
+ ensureCacheDir,
7
+ normalizePort,
8
+ ownerTokenHash,
9
+ sleep,
10
+ } from './browser-control.mjs';
11
+
12
+ export const CDP_CAPTURE_START_TIMEOUT_MS = 30000;
13
+ export const CDP_CAPTURE_STOP_TIMEOUT_MS = 30000;
14
+
15
+ function safeKind(kind) {
16
+ if (!/^[a-z][a-z0-9-]*$/.test(kind)) throw new Error(`Invalid capture kind: ${kind}`);
17
+ return kind;
18
+ }
19
+
20
+ function writePrivateJson(file, value) {
21
+ const temporary = `${file}.${process.pid}.tmp`;
22
+ writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
23
+ renameSync(temporary, file);
24
+ try {
25
+ chmodSync(file, 0o600);
26
+ } catch {
27
+ // Best effort. State contains output paths but never the owner token itself.
28
+ }
29
+ }
30
+
31
+ function readJson(file) {
32
+ try {
33
+ return JSON.parse(readFileSync(file, 'utf-8'));
34
+ } catch (error) {
35
+ if (error?.code === 'ENOENT') return null;
36
+ throw error;
37
+ }
38
+ }
39
+
40
+ function processExists(pid) {
41
+ if (!Number.isInteger(Number(pid)) || Number(pid) < 1) return false;
42
+ try {
43
+ process.kill(Number(pid), 0);
44
+ return true;
45
+ } catch (error) {
46
+ return error?.code === 'EPERM';
47
+ }
48
+ }
49
+
50
+ export function cdpRecordingDir(kind, port) {
51
+ return join(browserToolsCacheDir(), `${safeKind(kind)}-recording-${normalizePort(port)}`);
52
+ }
53
+
54
+ export function cdpRecordingStateFile(kind, port) {
55
+ return join(cdpRecordingDir(kind, port), 'state.json');
56
+ }
57
+
58
+ export function cdpRecordingStopFile(kind, port) {
59
+ return join(cdpRecordingDir(kind, port), 'stop-request.json');
60
+ }
61
+
62
+ export function cdpRecordingLogFile(kind, port) {
63
+ return join(cdpRecordingDir(kind, port), 'recorder.log');
64
+ }
65
+
66
+ export function readCdpRecordingState(kind, port) {
67
+ return readJson(cdpRecordingStateFile(kind, port));
68
+ }
69
+
70
+ export function updateCdpRecordingState(kind, port, state) {
71
+ writePrivateJson(cdpRecordingStateFile(kind, port), state);
72
+ return state;
73
+ }
74
+
75
+ export function cdpRecordingReport(kind, port) {
76
+ const normalizedPort = normalizePort(port);
77
+ const state = readCdpRecordingState(kind, normalizedPort);
78
+ if (!state) return { recording: false, kind, port: normalizedPort };
79
+ const processRunning = processExists(state.pid);
80
+ const terminal = ['completed', 'failed'].includes(state.status);
81
+ return {
82
+ recording: processRunning && !terminal,
83
+ processRunning,
84
+ kind,
85
+ port: normalizedPort,
86
+ pid: state.pid ?? null,
87
+ status: state.status ?? 'unknown',
88
+ phase: state.phase ?? null,
89
+ output: state.output ?? null,
90
+ eventCount: state.eventCount ?? null,
91
+ startedAt: state.startedAt ?? null,
92
+ completedAt: state.completedAt ?? null,
93
+ reason: state.reason ?? null,
94
+ error: state.error ?? null,
95
+ };
96
+ }
97
+
98
+ export function claimCdpRecording(kind, port) {
99
+ const normalizedPort = normalizePort(port);
100
+ ensureCacheDir();
101
+ const directory = cdpRecordingDir(kind, normalizedPort);
102
+
103
+ for (let attempt = 0; attempt < 2; attempt += 1) {
104
+ try {
105
+ mkdirSync(directory, { mode: 0o700 });
106
+ return directory;
107
+ } catch (error) {
108
+ if (error?.code !== 'EEXIST') throw error;
109
+ const state = readCdpRecordingState(kind, normalizedPort);
110
+ if (state && processExists(state.pid) && !['completed', 'failed'].includes(state.status)) {
111
+ throw new Error(`A ${kind} capture is already active on port ${normalizedPort}: ${state.output}`);
112
+ }
113
+ let stale = Boolean(state);
114
+ try {
115
+ stale ||= Date.now() - statSync(directory).mtimeMs > CDP_CAPTURE_START_TIMEOUT_MS;
116
+ } catch {
117
+ stale = true;
118
+ }
119
+ if (!stale) throw new Error(`A ${kind} capture is already starting on port ${normalizedPort}`);
120
+ rmSync(directory, { recursive: true, force: true });
121
+ }
122
+ }
123
+ throw new Error(`Could not claim ${kind} capture state for port ${normalizedPort}`);
124
+ }
125
+
126
+ export function assertCdpRecordingOwner(state, ownerToken) {
127
+ if (!state?.ownerTokenHash) throw new Error('Capture has no owner information');
128
+ if (!ownerToken) {
129
+ throw new Error(`Missing browser owner token. Export ${OWNER_TOKEN_ENV} with the token printed by browser-tools start`);
130
+ }
131
+ if (ownerTokenHash(ownerToken) !== state.ownerTokenHash) {
132
+ throw new Error('Capture is owned by another Browser Tools agent');
133
+ }
134
+ }
135
+
136
+ export function requestCdpRecordingStop(kind, port, ownerToken) {
137
+ const state = readCdpRecordingState(kind, port);
138
+ if (!state) throw new Error(`No ${kind} capture found on port ${normalizePort(port)}`);
139
+ assertCdpRecordingOwner(state, ownerToken);
140
+ writePrivateJson(cdpRecordingStopFile(kind, port), { requestedAt: new Date().toISOString() });
141
+ return state;
142
+ }
143
+
144
+ export async function waitForCdpRecordingState(kind, port, predicate, {
145
+ timeoutMs = CDP_CAPTURE_START_TIMEOUT_MS,
146
+ intervalMs = 100,
147
+ } = {}) {
148
+ const deadline = Date.now() + timeoutMs;
149
+ let state = null;
150
+ while (Date.now() < deadline) {
151
+ state = readCdpRecordingState(kind, port);
152
+ if (state && predicate(state)) return state;
153
+ await sleep(intervalMs);
154
+ }
155
+ return state;
156
+ }
157
+
158
+ export function removeCdpRecordingState(kind, port) {
159
+ rmSync(cdpRecordingDir(kind, port), { recursive: true, force: true });
160
+ }