@anweat/dsh-browser 0.1.13-alpha.1 → 0.1.14-alpha.1

package/lib/browser-service.js

@@ -30,66 +30,66 @@ import { configuredBrowserTools } from "./freedom.js";
 import { filterOpencliCatalog, parseOpencliCatalog } from "./opencli-catalog.js";
 import { UsageGovernor } from "./usage-policy.js";
 /** Rules-aware content extractor (runs in the page). */
-const EXTRACTOR_FN = `(ruleList) => {
-  const doc = document
-  const title = doc.title ? doc.title.trim() : ''
-  let host = ''
-  try { host = location.hostname } catch (e) {}
-  const norm = (h) => { const x = h.toLowerCase(); return x.startsWith('www.') ? x.slice(4) : x }
-  let rule = null
-  for (const r of ruleList) {
-    const rh = norm(r.hostname)
-    if (host === rh || host.endsWith('.' + rh)) rule = r
-  }
-  const pick = (selectors) => {
-    for (const sel of selectors) {
-      try {
-        const el = doc.querySelector(sel)
-        if (el && (el.textContent || '').trim().length > 40) return el
-      } catch (e) {}
-    }
-    return null
-  }
-  const content = rule ? pick(rule.contentSelectors) : (pick(['article', 'main', '[role="main"]']) || doc.body)
-  if (content && rule && rule.removeSelectors) {
-    for (const sel of rule.removeSelectors) {
-      try { content.querySelectorAll(sel).forEach((el) => el.remove()) } catch (e) {}
-    }
-  }
-  const text = content ? (content.innerText || content.textContent || '') : ''
-  return { title, text, html: doc.documentElement.outerHTML.slice(0, 2000000), usedRule: rule ? rule.hostname : null }
+const EXTRACTOR_FN = `(ruleList) => {
+  const doc = document
+  const title = doc.title ? doc.title.trim() : ''
+  let host = ''
+  try { host = location.hostname } catch (e) {}
+  const norm = (h) => { const x = h.toLowerCase(); return x.startsWith('www.') ? x.slice(4) : x }
+  let rule = null
+  for (const r of ruleList) {
+    const rh = norm(r.hostname)
+    if (host === rh || host.endsWith('.' + rh)) rule = r
+  }
+  const pick = (selectors) => {
+    for (const sel of selectors) {
+      try {
+        const el = doc.querySelector(sel)
+        if (el && (el.textContent || '').trim().length > 40) return el
+      } catch (e) {}
+    }
+    return null
+  }
+  const content = rule ? pick(rule.contentSelectors) : (pick(['article', 'main', '[role="main"]']) || doc.body)
+  if (content && rule && rule.removeSelectors) {
+    for (const sel of rule.removeSelectors) {
+      try { content.querySelectorAll(sel).forEach((el) => el.remove()) } catch (e) {}
+    }
+  }
+  const text = content ? (content.innerText || content.textContent || '') : ''
+  return { title, text, html: doc.documentElement.outerHTML.slice(0, 2000000), usedRule: rule ? rule.hostname : null }
 }`;
 /** Platform search-page list extractor (runs in the page). */
-const LIST_EXTRACTOR = `(spec) => {
-  const items = []
-  const nodes = document.querySelectorAll(spec.item)
-  for (let i = 0; i < nodes.length && items.length < 20; i++) {
-    const el = nodes[i]
-    const titleEl = spec.title ? el.querySelector(spec.title) : null
-    const linkEl = spec.link ? el.querySelector(spec.link) : null
-    const textEl = spec.text ? el.querySelector(spec.text) : null
-    const title = (titleEl ? titleEl.textContent : el.textContent || '').trim().replace(/\\s+/g, ' ')
-    let url = linkEl ? (linkEl.href || linkEl.getAttribute('href') || '') : ''
-    if (url && url.startsWith('/')) url = location.origin + url
-    if (!url && linkEl === null && titleEl) { const a = titleEl.closest ? titleEl.closest('a') : null; if (a) url = a.href }
-    const snippet = textEl ? (textEl.textContent || '').trim().replace(/\\s+/g, ' ').slice(0, 300) : ''
-    if (!url || !title || title.length < 2) continue
-    items.push({ url, title, snippet })
-  }
-  return items
+const LIST_EXTRACTOR = `(spec) => {
+  const items = []
+  const nodes = document.querySelectorAll(spec.item)
+  for (let i = 0; i < nodes.length && items.length < 20; i++) {
+    const el = nodes[i]
+    const titleEl = spec.title ? el.querySelector(spec.title) : null
+    const linkEl = spec.link ? el.querySelector(spec.link) : null
+    const textEl = spec.text ? el.querySelector(spec.text) : null
+    const title = (titleEl ? titleEl.textContent : el.textContent || '').trim().replace(/\\s+/g, ' ')
+    let url = linkEl ? (linkEl.href || linkEl.getAttribute('href') || '') : ''
+    if (url && url.startsWith('/')) url = location.origin + url
+    if (!url && linkEl === null && titleEl) { const a = titleEl.closest ? titleEl.closest('a') : null; if (a) url = a.href }
+    const snippet = textEl ? (textEl.textContent || '').trim().replace(/\\s+/g, ' ').slice(0, 300) : ''
+    if (!url || !title || title.length < 2) continue
+    items.push({ url, title, snippet })
+  }
+  return items
 }`;
-const CRAWL_EXTRACTOR = `(maxChars) => {
-  const root = document.querySelector('article, main, [role="main"]') || document.body
-  const text = ((root && (root.innerText || root.textContent)) || '').replace(/\\n{3,}/g, '\\n\\n').trim().slice(0, maxChars)
-  const links = []
-  for (const anchor of document.querySelectorAll('a[href]')) {
-    try {
-      const url = new URL(anchor.href, location.href)
-      if ((url.protocol === 'http:' || url.protocol === 'https:') && !links.includes(url.href)) links.push(url.href)
-      if (links.length >= 500) break
-    } catch (e) {}
-  }
-  return { title: document.title || '', text, links }
+const CRAWL_EXTRACTOR = `(maxChars) => {
+  const root = document.querySelector('article, main, [role="main"]') || document.body
+  const text = ((root && (root.innerText || root.textContent)) || '').replace(/\\n{3,}/g, '\\n\\n').trim().slice(0, maxChars)
+  const links = []
+  for (const anchor of document.querySelectorAll('a[href]')) {
+    try {
+      const url = new URL(anchor.href, location.href)
+      if ((url.protocol === 'http:' || url.protocol === 'https:') && !links.includes(url.href)) links.push(url.href)
+      if (links.length >= 500) break
+    } catch (e) {}
+  }
+  return { title: document.title || '', text, links }
 }`;
 function uid() {
     return crypto.randomUUID();
@@ -117,6 +117,35 @@ function storageStateOptions(statePath, label, allowMissing = false) {
         throw new Error(`dsh-browser: ${label} storageState path is not a file: ${statePath}`);
     return { storageState: statePath };
 }
+function boundedString(value, label, max) {
+    if (!value || value.length > max)
+        throw new Error(`${label} must contain 1 to ${max} characters`);
+    return value;
+}
+function boundedTimeout(value, label) {
+    const resolved = value ?? 15_000;
+    if (!Number.isFinite(resolved) || resolved < 1 || resolved > 30_000)
+        throw new Error(`${label} must be between 1 and 30,000 ms`);
+    return resolved;
+}
+function redactCaptureText(value, max = 2_000) {
+    return value
+        .replace(/\b(authorization|cookie|set-cookie|password|passwd|secret|token|api[-_]?key|session[-_]?id)\b\s*[:=]\s*([^\s,;]+)/gi, '$1=[redacted]')
+        .slice(0, max);
+}
+function redactCaptureUrl(value) {
+    try {
+        const parsed = new URL(value);
+        for (const key of [...parsed.searchParams.keys()]) {
+            if (/token|key|auth|session|cookie|password|secret/i.test(key))
+                parsed.searchParams.set(key, '[redacted]');
+        }
+        return parsed.toString().slice(0, 2_000);
+    }
+    catch {
+        return redactCaptureText(value);
+    }
+}
 export class BrowserService {
     config;
     browser;
@@ -128,6 +157,10 @@ export class BrowserService {
     authProfiles;
     usageGovernor;
     opencliCatalogCache;
+    captureConsoleEnabled = false;
+    captureNetworkEnabled = false;
+    capturedConsole = [];
+    capturedRequests = [];
     constructor(config) {
         this.config = config;
         this.authProfiles = new AuthProfileStore(config.authProfiles);
@@ -566,12 +599,139 @@ export class BrowserService {
             this.activeContext = await browser.newContext(storageStateOptions(this.config.storageStatePath, 'global'));
         }
         this.activePage = await this.activeContext.newPage();
+        this.attachCapture(this.activePage);
         return this.activePage;
     }
-    async captureScreenshot(page) {
+    attachCapture(page) {
+        page.on('console', (message) => {
+            if (!this.captureConsoleEnabled)
+                return;
+            const location = message.location?.();
+            this.capturedConsole.push({
+                type: String(message.type?.() ?? 'log').slice(0, 40),
+                text: redactCaptureText(String(message.text?.() ?? '')),
+                ...location?.url ? { url: redactCaptureUrl(location.url) } : {},
+                timestamp: new Date().toISOString(),
+            });
+            if (this.capturedConsole.length > 200)
+                this.capturedConsole.splice(0, this.capturedConsole.length - 200);
+        });
+        page.on('response', (response) => {
+            if (!this.captureNetworkEnabled)
+                return;
+            const status = Number(response.status?.() ?? 0);
+            if (status < 400)
+                return;
+            const request = response.request?.();
+            this.capturedRequests.push({
+                method: String(request?.method?.() ?? 'GET').slice(0, 20),
+                url: redactCaptureUrl(String(response.url?.() ?? '')),
+                status,
+                timestamp: new Date().toISOString(),
+            });
+            if (this.capturedRequests.length > 200)
+                this.capturedRequests.splice(0, this.capturedRequests.length - 200);
+        });
+        page.on('requestfailed', (request) => {
+            if (!this.captureNetworkEnabled)
+                return;
+            this.capturedRequests.push({
+                method: String(request.method?.() ?? 'GET').slice(0, 20),
+                url: redactCaptureUrl(String(request.url?.() ?? '')),
+                failure: redactCaptureText(String(request.failure?.()?.errorText ?? 'request failed'), 500),
+                timestamp: new Date().toISOString(),
+            });
+            if (this.capturedRequests.length > 200)
+                this.capturedRequests.splice(0, this.capturedRequests.length - 200);
+        });
+    }
+    resetCapture(capture = []) {
+        this.captureConsoleEnabled = capture.includes('console');
+        this.captureNetworkEnabled = capture.includes('network');
+        this.capturedConsole = [];
+        this.capturedRequests = [];
+    }
+    resolveTarget(page, target) {
+        if (!target || (typeof target !== 'string' && typeof target !== 'object'))
+            throw new Error('browser target must be a selector string or locator object');
+        const spec = typeof target === 'string' ? { selector: target } : target;
+        const modes = [spec.selector, spec.role, spec.text, spec.label].filter(value => value !== undefined);
+        if (modes.length !== 1)
+            throw new Error('browser target requires exactly one of selector, role, text, or label');
+        if (spec.name !== undefined && spec.role === undefined)
+            throw new Error('browser target name is only valid with role');
+        let root = page;
+        if (spec.frame) {
+            const frameModes = [spec.frame.selector, spec.frame.name, spec.frame.url].filter(value => value !== undefined);
+            if (frameModes.length !== 1)
+                throw new Error('browser frame requires exactly one of selector, name, or url');
+            if (spec.frame.selector)
+                root = page.frameLocator(boundedString(spec.frame.selector, 'frame selector', 500));
+            else {
+                const frame = page.frame(spec.frame.name
+                    ? { name: boundedString(spec.frame.name, 'frame name', 500) }
+                    : { url: boundedString(spec.frame.url, 'frame url', 2_000) });
+                if (!frame)
+                    throw new Error('browser target frame was not found');
+                root = frame;
+            }
+        }
+        if (spec.selector)
+            return root.locator(boundedString(spec.selector, 'selector', 500));
+        if (spec.role)
+            return root.getByRole(boundedString(spec.role, 'role', 100), {
+                ...spec.name !== undefined ? { name: boundedString(spec.name, 'role name', 2_000) } : {},
+                exact: spec.exact ?? false,
+            });
+        if (spec.text)
+            return root.getByText(boundedString(spec.text, 'text locator', 2_000), { exact: spec.exact ?? false });
+        return root.getByLabel(boundedString(spec.label, 'label locator', 2_000), { exact: spec.exact ?? false });
+    }
+    screenshotFile(options) {
+        const filename = options.filename ?? `shot-${Date.now()}-${uid().slice(0, 8)}.${options.format === 'jpeg' ? 'jpg' : 'png'}`;
+        if (filename !== path.basename(filename) || !/^[\w.() -]{1,160}$/.test(filename)) {
+            throw new Error('browser_screenshot filename must be a plain file name inside snapshotDir');
+        }
+        const extension = path.extname(filename).toLowerCase();
+        const inferred = extension === '.jpg' || extension === '.jpeg' ? 'jpeg' : extension === '.png' ? 'png' : undefined;
+        const format = options.format ?? inferred ?? 'png';
+        if (inferred && inferred !== format)
+            throw new Error('browser_screenshot filename extension does not match format');
+        if (!inferred)
+            throw new Error('browser_screenshot filename must end in .png, .jpg, or .jpeg');
+        return { file: path.join(this.config.snapshotDir, filename), format };
+    }
+    async captureScreenshot(page, options = {}) {
         fs.mkdirSync(this.config.snapshotDir, { recursive: true });
-        const file = path.join(this.config.snapshotDir, 'shot-' + Date.now() + '-' + uid().slice(0, 8) + '.png');
-        await page.screenshot({ path: file, fullPage: true });
+        if (options.target && options.clip)
+            throw new Error('browser_screenshot cannot combine target and clip');
+        if (options.target && options.fullPage)
+            throw new Error('browser_screenshot cannot combine target and fullPage');
+        if (options.quality !== undefined && (!Number.isInteger(options.quality) || options.quality < 0 || options.quality > 100)) {
+            throw new Error('browser_screenshot quality must be an integer from 0 to 100');
+        }
+        const { file, format } = this.screenshotFile(options);
+        if (format === 'png' && options.quality !== undefined)
+            throw new Error('browser_screenshot quality is only supported for jpeg');
+        const screenshotOptions = {
+            path: file,
+            type: format,
+            ...options.quality !== undefined ? { quality: options.quality } : {},
+        };
+        if (options.clip) {
+            const { x, y, width, height } = options.clip;
+            if (![x, y, width, height].every(Number.isFinite) || x < 0 || y < 0 || width <= 0 || height <= 0 || width > 20_000 || height > 20_000) {
+                throw new Error('browser_screenshot clip must use finite non-negative coordinates and dimensions from 1 to 20,000');
+            }
+            screenshotOptions.clip = options.clip;
+        }
+        else if (!options.target) {
+            screenshotOptions.fullPage = options.fullPage ?? true;
+        }
+        if (options.target)
+            await this.resolveTarget(page, options.target).screenshot(screenshotOptions);
+        else
+            await page.screenshot(screenshotOptions);
         return file;
     }
     async readState(page, includeScreenshot) {
@@ -587,6 +747,7 @@ export class BrowserService {
     }
     async open(url, opts = {}) {
         const page = await this.ensureActivePage(url, opts);
+        this.resetCapture(opts.capture);
         page.setDefaultTimeout(30_000);
         await this.navigate(page, url, { waitUntil: 'domcontentloaded', timeout: 30_000 });
         await page.waitForLoadState('networkidle', { timeout: 8_000 }).catch(() => { });
@@ -595,32 +756,75 @@ export class BrowserService {
             await page.waitForTimeout(opts.waitMs);
         return this.readState(page, true);
     }
-    async click(selector, opts = {}) {
+    async click(target, opts = {}) {
         const page = await this.ensureActivePage();
-        await page.waitForSelector(selector, { timeout: opts.timeoutMs ?? 15_000 });
-        await page.click(selector);
+        await this.resolveTarget(page, target).click({ timeout: boundedTimeout(opts.timeoutMs, 'browser_click timeoutMs') });
         if (opts.waitMs !== undefined)
             await page.waitForTimeout(opts.waitMs);
         else
             await page.waitForTimeout(500);
         return this.readState(page, true);
     }
-    async type(selector, text, opts = {}) {
+    async type(target, text, opts = {}) {
+        const page = await this.ensureActivePage();
+        await this.resolveTarget(page, target).fill(text, { timeout: boundedTimeout(opts.timeoutMs, 'browser_type timeoutMs') });
+        return this.readState(page, false);
+    }
+    async wait(target, opts = {}) {
+        const page = await this.ensureActivePage();
+        const modes = [target !== undefined, opts.urlPattern !== undefined, opts.networkIdle === true, opts.timeMs !== undefined].filter(Boolean);
+        if (modes.length !== 1)
+            throw new Error('browser_wait requires exactly one target, urlPattern, networkIdle=true, or timeMs');
+        const timeout = boundedTimeout(opts.timeoutMs, 'browser_wait timeoutMs');
+        if (target !== undefined)
+            await this.resolveTarget(page, target).waitFor({ state: opts.state ?? 'visible', timeout });
+        else if (opts.urlPattern !== undefined)
+            await page.waitForURL(boundedString(opts.urlPattern, 'urlPattern', 2_000), { timeout });
+        else if (opts.networkIdle)
+            await page.waitForLoadState('networkidle', { timeout });
+        else {
+            const timeMs = opts.timeMs;
+            if (!Number.isFinite(timeMs) || timeMs < 0 || timeMs > 10_000)
+                throw new Error('browser_wait timeMs must be between 0 and 10,000');
+            await page.waitForTimeout(timeMs);
+        }
+        return this.readState(page, false);
+    }
+    async press(target, key, opts = {}) {
+        const page = await this.ensureActivePage();
+        const value = boundedString(key, 'browser_press key', 100);
+        if (target !== undefined)
+            await this.resolveTarget(page, target).press(value, { timeout: boundedTimeout(opts.timeoutMs, 'browser_press timeoutMs') });
+        else
+            await page.keyboard.press(value);
+        return this.readState(page, false);
+    }
+    async select(target, values, opts = {}) {
+        if (values.length < 1 || values.length > 20)
+            throw new Error('browser_select requires 1 to 20 values');
+        values.forEach(value => boundedString(value, 'browser_select value', 2_000));
+        const page = await this.ensureActivePage();
+        await this.resolveTarget(page, target).selectOption([...values], { timeout: boundedTimeout(opts.timeoutMs, 'browser_select timeoutMs') });
+        return this.readState(page, false);
+    }
+    async check(target, checked = true, opts = {}) {
         const page = await this.ensureActivePage();
-        await page.waitForSelector(selector, { timeout: opts.timeoutMs ?? 15_000 });
-        await page.fill(selector, text);
+        const locator = this.resolveTarget(page, target);
+        if (checked)
+            await locator.check({ timeout: boundedTimeout(opts.timeoutMs, 'browser_check timeoutMs') });
+        else
+            await locator.uncheck({ timeout: boundedTimeout(opts.timeoutMs, 'browser_check timeoutMs') });
         return this.readState(page, false);
     }
-    async hover(selector, opts = {}) {
+    async hover(target, opts = {}) {
         const page = await this.ensureActivePage();
-        const timeoutMs = opts.timeoutMs ?? 15_000;
+        const timeoutMs = boundedTimeout(opts.timeoutMs, 'browser_hover timeoutMs');
         const waitMs = Math.min(Math.max(opts.waitMs ?? 300, 0), timeoutMs);
-        await page.waitForSelector(selector, { timeout: timeoutMs });
-        await page.hover(selector);
+        await this.resolveTarget(page, target).hover({ timeout: timeoutMs });
         await page.waitForTimeout(waitMs);
         return this.readState(page, true);
     }
-    async setFiles(selector, files, opts = {}) {
+    async setFiles(target, files, opts = {}) {
         if (files.length === 0 || files.length > 20)
             throw new Error('browser_set_files requires 1 to 20 files');
         const resolved = files.map(file => {
@@ -635,8 +839,7 @@ export class BrowserService {
         if (totalBytes > 512 * 1024 * 1024)
             throw new Error('browser_set_files total upload size exceeds 512 MiB');
         const page = await this.ensureActivePage();
-        await page.waitForSelector(selector, { timeout: opts.timeoutMs ?? 15_000 });
-        await page.setInputFiles(selector, resolved);
+        await this.resolveTarget(page, target).setInputFiles(resolved, { timeout: boundedTimeout(opts.timeoutMs, 'browser_set_files timeoutMs') });
         return { ...await this.readState(page, true), files: resolved.map(file => path.basename(file)) };
     }
     async evaluate(expression, opts = {}) {
@@ -648,15 +851,38 @@ export class BrowserService {
         const page = await this.ensureActivePage();
         const timeoutMs = Math.min(Math.max(opts.timeoutMs ?? 15_000, 1_000), 30_000);
         let timer;
+        let timedOut = false;
         const timeout = new Promise((_resolve, reject) => {
             timer = setTimeout(() => {
-                void this.closePage();
-                reject(new Error('browser_evaluate timed out after ' + timeoutMs + 'ms; the active page was closed'));
+                timedOut = true;
+                void (async () => {
+                    try {
+                        const session = await page.context().newCDPSession(page);
+                        try {
+                            await session.send('Runtime.terminateExecution');
+                        }
+                        finally {
+                            await session.detach().catch(() => { });
+                        }
+                        reject(new Error('browser_evaluate timed out after ' + timeoutMs + 'ms; page JavaScript was terminated and the active page remains open'));
+                    }
+                    catch (error) {
+                        reject(new Error('browser_evaluate timed out after ' + timeoutMs + 'ms; unable to terminate page JavaScript without closing the active page: ' + String(error).slice(0, 200)));
+                    }
+                })();
             }, timeoutMs);
         });
         try {
             const script = `(async () => {\nconst value = await (${source}\n);\nconst json = JSON.stringify(value);\nif (json === undefined) throw new Error('expression result is not JSON-serializable');\nreturn { resultJson: json.slice(0, 100000), truncated: json.length > 100000 };\n})()`;
-            const result = await Promise.race([page.evaluate(script), timeout]);
+            let result;
+            try {
+                result = await Promise.race([page.evaluate(script), timeout]);
+            }
+            catch (error) {
+                if (timedOut)
+                    throw new Error('browser_evaluate timed out after ' + timeoutMs + 'ms; page JavaScript was terminated and the active page remains open');
+                throw error;
+            }
             return {
                 url: page.url(),
                 resultJson: result.resultJson,
@@ -684,9 +910,30 @@ export class BrowserService {
         const page = await this.ensureActivePage();
         return this.readState(page, false);
     }
-    async screenshot() {
+    consoleMessages(opts = {}) {
+        const severities = ['debug', 'log', 'info', 'warning', 'error'];
+        const threshold = opts.level ? severities.indexOf(opts.level) : 0;
+        if (opts.level && threshold < 0)
+            throw new Error('browser_console level must be debug, log, info, warning, or error');
+        const limit = Math.min(Math.max(Math.trunc(opts.limit ?? 100), 1), 200);
+        const records = this.capturedConsole.filter(record => {
+            const index = severities.indexOf(record.type === 'warn' ? 'warning' : record.type);
+            return index < 0 || index >= threshold;
+        }).slice(-limit);
+        if (opts.clear)
+            this.capturedConsole = [];
+        return { enabled: this.captureConsoleEnabled, records };
+    }
+    networkRequests(opts = {}) {
+        const limit = Math.min(Math.max(Math.trunc(opts.limit ?? 100), 1), 200);
+        const records = this.capturedRequests.slice(-limit);
+        if (opts.clear)
+            this.capturedRequests = [];
+        return { enabled: this.captureNetworkEnabled, records };
+    }
+    async screenshot(options = {}) {
         const page = await this.ensureActivePage();
-        return { path: await this.captureScreenshot(page) };
+        return { path: await this.captureScreenshot(page, options) };
     }
     async recipe(steps, opts = {}) {
         if (!opts.url && (!this.activePage || this.activePage.isClosed()))
@@ -723,6 +970,7 @@ export class BrowserService {
         this.activeContext = undefined;
         this.activeProfile = undefined;
         this.activeRulePack = undefined;
+        this.resetCapture();
     }
     async status() {
         let chromiumInstalled = false;