npm - @jackwener/opencli - Versions diffs - 1.7.5 → 1.7.7 - Mend

@jackwener/opencli 1.7.5 → 1.7.7

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.

Files changed (121) hide show

package/README.md +22 -10
package/README.zh-CN.md +18 -9
package/cli-manifest.json +401 -11
package/clis/51job/company.js +125 -0
package/clis/51job/detail.js +108 -0
package/clis/51job/hot.js +55 -0
package/clis/51job/search.js +79 -0
package/clis/51job/utils.js +302 -0
package/clis/51job/utils.test.js +69 -0
package/clis/bilibili/video.js +68 -0
package/clis/bilibili/video.test.js +132 -0
package/clis/chatgpt/image.js +1 -1
package/clis/deepseek/ask.js +37 -11
package/clis/deepseek/ask.test.js +165 -0
package/clis/deepseek/utils.js +192 -24
package/clis/deepseek/utils.test.js +145 -0
package/clis/gemini/image.js +1 -1
package/clis/instagram/download.js +1 -1
package/clis/jianyu/search.js +139 -3
package/clis/jianyu/search.test.js +25 -0
package/clis/jianyu/shared/procurement-detail.js +15 -0
package/clis/jianyu/shared/procurement-detail.test.js +12 -0
package/clis/twitter/likes.js +3 -2
package/clis/twitter/search.js +4 -2
package/clis/twitter/search.test.js +4 -0
package/clis/twitter/shared.js +35 -2
package/clis/twitter/shared.test.js +96 -0
package/clis/twitter/thread.js +3 -1
package/clis/twitter/timeline.js +3 -2
package/clis/twitter/tweets.js +219 -0
package/clis/twitter/tweets.test.js +125 -0
package/clis/web/read.js +25 -5
package/clis/web/read.test.js +76 -0
package/clis/weread/ai-outline.js +170 -0
package/clis/weread/ai-outline.test.js +83 -0
package/clis/weread/book.js +57 -44
package/clis/weread/commands.test.js +24 -0
package/clis/xiaoyuzhou/podcast-episodes.js +2 -2
package/clis/xiaoyuzhou/podcast-episodes.test.js +78 -0
package/clis/youtube/channel.js +35 -0
package/dist/src/browser/analyze.d.ts +103 -0
package/dist/src/browser/analyze.js +230 -0
package/dist/src/browser/analyze.test.d.ts +1 -0
package/dist/src/browser/analyze.test.js +164 -0
package/dist/src/browser/article-extract.d.ts +57 -0
package/dist/src/browser/article-extract.e2e.test.d.ts +1 -0
package/dist/src/browser/article-extract.e2e.test.js +105 -0
package/dist/src/browser/article-extract.js +169 -0
package/dist/src/browser/article-extract.test.d.ts +1 -0
package/dist/src/browser/article-extract.test.js +94 -0
package/dist/src/browser/base-page.d.ts +13 -3
package/dist/src/browser/base-page.js +35 -25
package/dist/src/browser/cdp.d.ts +1 -0
package/dist/src/browser/cdp.js +23 -5
package/dist/src/browser/compound.d.ts +59 -0
package/dist/src/browser/compound.js +112 -0
package/dist/src/browser/compound.test.d.ts +1 -0
package/dist/src/browser/compound.test.js +175 -0
package/dist/src/browser/dom-snapshot.d.ts +7 -0
package/dist/src/browser/dom-snapshot.js +76 -3
package/dist/src/browser/dom-snapshot.test.js +65 -0
package/dist/src/browser/extract.d.ts +69 -0
package/dist/src/browser/extract.js +132 -0
package/dist/src/browser/extract.test.d.ts +1 -0
package/dist/src/browser/extract.test.js +129 -0
package/dist/src/browser/find.d.ts +76 -0
package/dist/src/browser/find.js +179 -0
package/dist/src/browser/find.test.d.ts +1 -0
package/dist/src/browser/find.test.js +120 -0
package/dist/src/browser/html-tree.d.ts +75 -0
package/dist/src/browser/html-tree.js +112 -0
package/dist/src/browser/html-tree.test.d.ts +1 -0
package/dist/src/browser/html-tree.test.js +181 -0
package/dist/src/browser/network-cache.d.ts +48 -0
package/dist/src/browser/network-cache.js +66 -0
package/dist/src/browser/network-cache.test.d.ts +1 -0
package/dist/src/browser/network-cache.test.js +58 -0
package/dist/src/browser/network-key.d.ts +22 -0
package/dist/src/browser/network-key.js +66 -0
package/dist/src/browser/network-key.test.d.ts +1 -0
package/dist/src/browser/network-key.test.js +49 -0
package/dist/src/browser/shape-filter.d.ts +52 -0
package/dist/src/browser/shape-filter.js +101 -0
package/dist/src/browser/shape-filter.test.d.ts +1 -0
package/dist/src/browser/shape-filter.test.js +101 -0
package/dist/src/browser/shape.d.ts +23 -0
package/dist/src/browser/shape.js +95 -0
package/dist/src/browser/shape.test.d.ts +1 -0
package/dist/src/browser/shape.test.js +82 -0
package/dist/src/browser/target-errors.d.ts +14 -1
package/dist/src/browser/target-errors.js +13 -0
package/dist/src/browser/target-errors.test.js +39 -6
package/dist/src/browser/target-resolver.d.ts +57 -10
package/dist/src/browser/target-resolver.js +195 -75
package/dist/src/browser/target-resolver.test.js +80 -5
package/dist/src/browser/verify-fixture.d.ts +59 -0
package/dist/src/browser/verify-fixture.js +213 -0
package/dist/src/browser/verify-fixture.test.d.ts +1 -0
package/dist/src/browser/verify-fixture.test.js +161 -0
package/dist/src/cli.d.ts +32 -0
package/dist/src/cli.js +936 -141
package/dist/src/cli.test.js +1051 -1
package/dist/src/daemon.d.ts +3 -2
package/dist/src/daemon.js +16 -4
package/dist/src/daemon.test.d.ts +1 -0
package/dist/src/daemon.test.js +19 -0
package/dist/src/download/article-download.d.ts +12 -0
package/dist/src/download/article-download.js +141 -17
package/dist/src/download/article-download.test.js +196 -0
package/dist/src/download/index.js +73 -86
package/dist/src/errors.js +4 -2
package/dist/src/errors.test.js +13 -0
package/dist/src/execution.js +7 -2
package/dist/src/execution.test.js +54 -0
package/dist/src/launcher.d.ts +1 -1
package/dist/src/launcher.js +3 -3
package/dist/src/main.js +16 -0
package/dist/src/output.js +1 -1
package/dist/src/output.test.js +6 -0
package/dist/src/types.d.ts +18 -3
package/package.json +5 -1

package/dist/src/browser/article-extract.e2e.test.js ADDED Viewed

@@ -0,0 +1,105 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { JSDOM } from 'jsdom';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { buildExtractArticleJs } from './article-extract.js';
+import { downloadArticle } from '../download/article-download.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const fixturesDir = path.join(__dirname, '__fixtures__', 'article-extract');
+const tempDirs = [];
+afterEach(() => {
+    for (const dir of tempDirs)
+        fs.rmSync(dir, { recursive: true, force: true });
+    tempDirs.length = 0;
+});
+function loadFixture(name) {
+    return fs.readFileSync(path.join(fixturesDir, name), 'utf8');
+}
+function escapeHtml(text) {
+    return text.replace(/[&<>]/g, ch => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;' }[ch]));
+}
+function runExtract(html, url, options = {}, contentType) {
+    const dom = new JSDOM(html, {
+        url,
+        contentType: 'text/html',
+        pretendToBeVisual: true,
+        runScripts: 'outside-only',
+    });
+    if (contentType) {
+        Object.defineProperty(dom.window.document, 'contentType', {
+            value: contentType,
+            configurable: true,
+        });
+    }
+    return dom.window.eval(buildExtractArticleJs(options));
+}
+async function renderMarkdown(article, url, options = {}) {
+    const tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'opencli-article-e2e-'));
+    tempDirs.push(tempDir);
+    const result = await downloadArticle({
+        title: article.title || 'untitled',
+        contentHtml: article.html,
+        sourceUrl: url,
+    }, {
+        output: tempDir,
+        downloadImages: false,
+        cleanSelectors: options.cleanSelectors,
+    });
+    expect(result[0].status).toBe('success');
+    return fs.readFileSync(result[0].saved, 'utf8');
+}
+describe('article extract → markdown e2e fixtures', () => {
+    it('extracts a Wikipedia article fixture and keeps infobox/reference noise out of markdown', async () => {
+        const url = 'https://en.wikipedia.org/wiki/Markdown';
+        const cleanSelectors = ['.infobox', '.navbox', '.reference', '.mw-editsection', '.metadata'];
+        const article = runExtract(loadFixture('wikipedia-markdown.html'), url, { cleanSelectors });
+        expect(article?.source).toBe('readability');
+        expect(article?.title).toBe('Markdown');
+        if (!article)
+            throw new Error('expected extracted article');
+        const md = await renderMarkdown(article, url, { cleanSelectors });
+        expect(md).toContain('lightweight markup language');
+        expect(md).toContain('John Gruber');
+        expect(md).not.toContain('Syntax description');
+        expect(md).not.toContain('Standard file extension');
+    });
+    it('extracts a Deno blog fixture, preserves embedded iframes as markdown links, and drops page chrome', async () => {
+        const url = 'https://deno.com/blog/v2.0';
+        const article = runExtract(loadFixture('deno-v2.html'), url);
+        expect(article?.source).toBe('readability');
+        expect(article?.title).toBe('Announcing Deno 2 | Deno');
+        if (!article)
+            throw new Error('expected extracted article');
+        const md = await renderMarkdown(article, url);
+        expect(md).toContain('## Announcing Deno 2');
+        expect(md).toContain('The web is humanity’s largest software platform');
+        expect(md).toMatch(/\]\(https:\/\/www\.youtube(?:-nocookie)?\.com\/embed\/[^)]+\)/);
+        expect(md).not.toContain('Skip to main content');
+    });
+    it('short-circuits non-HTML raw text pages end-to-end', async () => {
+        const url = 'https://raw.githubusercontent.com/openai/openai-cookbook/main/README.md';
+        const text = loadFixture('openai-cookbook-readme.txt');
+        const html = `<html><head><title>OpenAI Cookbook README</title></head><body><pre>${escapeHtml(text)}</pre></body></html>`;
+        const article = runExtract(html, url, {}, 'text/plain');
+        expect(article?.source).toBe('raw-text');
+        if (!article)
+            throw new Error('expected extracted article');
+        const md = await renderMarkdown(article, url);
+        expect(md).toContain('OPENAI\\_API\\_KEY');
+        expect(md).toContain('Example code and guides for accomplishing common tasks');
+    });
+    it('short-circuits a single-pre document end-to-end', async () => {
+        const url = 'https://raw.githubusercontent.com/openai/openai-cookbook/main/README.md';
+        const text = loadFixture('openai-cookbook-readme.txt');
+        const html = `<html><head><title>OpenAI Cookbook README</title></head><body><pre>${escapeHtml(text)}</pre></body></html>`;
+        const article = runExtract(html, url);
+        expect(article?.source).toBe('pre');
+        if (!article)
+            throw new Error('expected extracted article');
+        const md = await renderMarkdown(article, url);
+        expect(md).toContain('OPENAI\\_API\\_KEY');
+        expect(md).toContain('Most code examples are written in Python');
+    });
+});

package/dist/src/browser/article-extract.js ADDED Viewed

@@ -0,0 +1,169 @@
+/**
+ * Article extraction via Readability — generic `page → article HTML` pipeline.
+ *
+ * Complements `src/browser/extract.ts`: that one takes a caller-supplied
+ * selector. This one works with zero configuration on arbitrary article pages
+ * (blogs, news, docs) by running `@mozilla/readability` inside the page
+ * context via CDP evaluate.
+ *
+ * Pipeline:
+ *   1. Short-circuit non-HTML documents (`text/plain`, JSON, XML) — a page
+ *      renderer wrapping a plain-text file would pollute the DOM pipeline.
+ *   2. Short-circuit the "body is a single <pre>" case, which browsers use
+ *      when loading *.txt / *.md over file:// or raw.githubusercontent.com.
+ *   3. Deep-clone the document, apply caller-supplied `cleanSelectors` to the
+ *      clone (preserves live page state for subsequent snapshot/click).
+ *   4. Inject Readability + isProbablyReaderable sources into the page,
+ *      parse on the clone. `isProbablyReaderable` gates the parse unless
+ *      `force: true`.
+ *   5. On Readability miss, walk a fallback selector chain
+ *      (main → [role="main"] → #main-content → … → body) and return the
+ *      first root with >80 characters of text.
+ *
+ * Readability runs in the page's own window because it needs real DOM APIs
+ * (getComputedStyle, treeWalker). Running it Node-side would require jsdom —
+ * a heavy dep the rest of OpenCLI doesn't need.
+ */
+import * as fs from 'node:fs';
+import { createRequire } from 'node:module';
+const requireFromHere = createRequire(import.meta.url);
+let cachedSources = null;
+function readabilitySources() {
+    if (cachedSources)
+        return cachedSources;
+    const readabilityPath = requireFromHere.resolve('@mozilla/readability/Readability.js');
+    const readerablePath = requireFromHere.resolve('@mozilla/readability/Readability-readerable.js');
+    cachedSources = {
+        readability: fs.readFileSync(readabilityPath, 'utf8'),
+        readerable: fs.readFileSync(readerablePath, 'utf8'),
+    };
+    return cachedSources;
+}
+export const DEFAULT_FALLBACK_SELECTORS = [
+    'main',
+    '[role="main"]',
+    '#main-content',
+    '#main',
+    '#content',
+    '.content',
+    'article',
+    'body',
+];
+const MIN_FALLBACK_TEXT_LENGTH = 80;
+/**
+ * Build the JS expression evaluated in-page to extract the article. Exported
+ * for testability — callers on the host side should use `extractArticle`.
+ */
+export function buildExtractArticleJs(options = {}) {
+    const { readability, readerable } = readabilitySources();
+    const cleanSelectors = options.cleanSelectors ?? [];
+    const fallbackSelectors = options.fallbackSelectors ?? DEFAULT_FALLBACK_SELECTORS;
+    const force = !!options.force;
+    // Library sources contain backticks and ${...} fragments, so we embed them
+    // as JSON-encoded string literals and eval them inside a Function() scope.
+    // This isolates their var declarations from the outer IIFE without polluting
+    // window globals.
+    const readabilityLit = JSON.stringify(readability);
+    const readerableLit = JSON.stringify(readerable);
+    const cleanLit = JSON.stringify(cleanSelectors);
+    const fallbackLit = JSON.stringify(fallbackSelectors);
+    const forceLit = JSON.stringify(force);
+    return [
+        '(() => {',
+        '  const cleanSelectors = ' + cleanLit + ';',
+        '  const fallbackSelectors = ' + fallbackLit + ';',
+        '  const force = ' + forceLit + ';',
+        '  const minFallbackText = ' + MIN_FALLBACK_TEXT_LENGTH + ';',
+        '  const readabilitySrc = ' + readabilityLit + ';',
+        '  const readerableSrc = ' + readerableLit + ';',
+        '',
+        '  function escapeHtml(s) {',
+        '    return String(s).replace(/[&<>]/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;" }[c]));',
+        '  }',
+        '',
+        '  // Short-circuit 1: non-HTML document',
+        '  const ct = document.contentType || "";',
+        '  if (ct && ct !== "text/html" && ct !== "application/xhtml+xml") {',
+        '    const body = document.body ? (document.body.textContent || "") : "";',
+        '    return { source: "raw-text", html: "<pre>" + escapeHtml(body) + "</pre>", title: document.title || "" };',
+        '  }',
+        '',
+        '  // Short-circuit 2: body is a single <pre>',
+        '  if (document.body) {',
+        '    const kids = document.body.children;',
+        '    if (kids.length === 1 && kids[0] && kids[0].tagName === "PRE") {',
+        '      return { source: "pre", html: document.body.outerHTML, title: document.title || "" };',
+        '    }',
+        '  }',
+        '',
+        '  // Deep-clone + adapter-supplied dirty-node removal',
+        '  const cloneDoc = document.cloneNode(true);',
+        '  for (const sel of cleanSelectors) {',
+        '    try { for (const n of cloneDoc.querySelectorAll(sel)) n.remove(); }',
+        '    catch (e) { /* ignore invalid selector */ }',
+        '  }',
+        '',
+        '  // Inject Readability into an isolated Function scope and extract the',
+        '  // constructors we need. Library sources use their own module.exports',
+        '  // guard (if typeof module === "object"), which is falsy here.',
+        '  const libs = (new Function(',
+        '    readabilitySrc + "\\n" + readerableSrc + "\\nreturn {" +',
+        '    " Readability: typeof Readability !== \\"undefined\\" ? Readability : null," +',
+        '    " isProbablyReaderable: typeof isProbablyReaderable !== \\"undefined\\" ? isProbablyReaderable : null" +',
+        '    " };"',
+        '  ))();',
+        '  const Readability = libs.Readability;',
+        '  const isProbablyReaderable = libs.isProbablyReaderable;',
+        '',
+        '  const readerableOk = force || (typeof isProbablyReaderable === "function" ? isProbablyReaderable(cloneDoc) : true);',
+        '  let article = null;',
+        '  if (readerableOk && typeof Readability === "function") {',
+        '    try { article = new Readability(cloneDoc).parse(); } catch (e) { article = null; }',
+        '  }',
+        '  if (article && article.content) {',
+        '    return {',
+        '      source: "readability",',
+        '      html: article.content,',
+        '      title: article.title || document.title || "",',
+        '      byline: article.byline || undefined,',
+        '      publishedTime: article.publishedTime || undefined,',
+        '      siteName: article.siteName || undefined,',
+        '    };',
+        '  }',
+        '',
+        '  // Fallback chain',
+        '  for (const sel of fallbackSelectors) {',
+        '    let el = null;',
+        '    try { el = cloneDoc.querySelector(sel); } catch (e) { continue; }',
+        '    if (!el) continue;',
+        '    const text = (el.textContent || "").trim();',
+        '    if (text.length < minFallbackText) continue;',
+        '    return { source: "fallback", html: el.outerHTML, title: document.title || "" };',
+        '  }',
+        '',
+        '  return null;',
+        '})()',
+    ].join('\n');
+}
+/**
+ * Run the extract pipeline on the given page. Returns `null` when no usable
+ * content is found (Readability miss + empty fallback chain).
+ */
+export async function extractArticle(page, options = {}) {
+    const js = buildExtractArticleJs(options);
+    const raw = await page.evaluate(js);
+    if (raw == null || typeof raw !== 'object')
+        return null;
+    const r = raw;
+    if (typeof r.html !== 'string' || typeof r.source !== 'string')
+        return null;
+    const source = r.source;
+    return {
+        html: r.html,
+        title: typeof r.title === 'string' ? r.title : '',
+        ...(r.byline && { byline: r.byline }),
+        ...(r.publishedTime && { publishedTime: r.publishedTime }),
+        ...(r.siteName && { siteName: r.siteName }),
+        source,
+    };
+}

package/dist/src/browser/article-extract.test.d.ts ADDED Viewed

	@@ -0,0 +1 @@
1	+ export {};

package/dist/src/browser/article-extract.test.js ADDED Viewed

@@ -0,0 +1,94 @@
+import { describe, expect, it } from 'vitest';
+import { buildExtractArticleJs, extractArticle, DEFAULT_FALLBACK_SELECTORS, } from './article-extract.js';
+function fakePage(response) {
+    const state = { lastJs: null };
+    return {
+        lastJs: null,
+        async evaluate(js) {
+            state.lastJs = js;
+            Object.assign(this, state);
+            return response;
+        },
+    };
+}
+describe('buildExtractArticleJs', () => {
+    it('embeds Readability + Readerable sources once per evaluation', () => {
+        const js = buildExtractArticleJs();
+        // Both libs should be inlined (matched by identifying strings from the
+        // upstream @mozilla/readability sources).
+        expect(js).toContain('function Readability(doc, options)');
+        expect(js).toContain('function isProbablyReaderable');
+    });
+    it('serializes caller-supplied options into the evaluated JS', () => {
+        const js = buildExtractArticleJs({
+            cleanSelectors: ['.ads', '#banner'],
+            fallbackSelectors: ['article', 'body'],
+            force: true,
+        });
+        expect(js).toContain('[".ads","#banner"]');
+        expect(js).toContain('["article","body"]');
+        expect(js).toContain('const force = true;');
+    });
+    it('uses the default fallback chain when none is supplied', () => {
+        const js = buildExtractArticleJs();
+        for (const sel of DEFAULT_FALLBACK_SELECTORS) {
+            expect(js).toContain(JSON.stringify(sel));
+        }
+    });
+    it('runs fallback selection against the cleaned clone', () => {
+        const js = buildExtractArticleJs({ cleanSelectors: ['.noise'] });
+        expect(js).toContain('el = cloneDoc.querySelector(sel);');
+        expect(js).not.toContain('el = document.querySelector(sel);');
+    });
+    it('produces syntactically valid JavaScript', () => {
+        // Parsing via the Function constructor rejects any syntax error in the
+        // generated code — including accidental template-literal break-outs from
+        // the embedded Readability sources.
+        expect(() => new Function(buildExtractArticleJs())).not.toThrow();
+        expect(() => new Function(buildExtractArticleJs({ force: true }))).not.toThrow();
+        expect(() => new Function(buildExtractArticleJs({
+            cleanSelectors: ['.a', '.b'],
+            fallbackSelectors: ['main', 'body'],
+        }))).not.toThrow();
+    });
+});
+describe('extractArticle (host-side)', () => {
+    it('returns a normalized ExtractedArticle when the page responds with one', async () => {
+        const page = fakePage({
+            source: 'readability',
+            html: '<p>hello</p>',
+            title: 'Hello',
+            byline: 'Alice',
+            publishedTime: '2026-04-22',
+            siteName: 'Example',
+        });
+        const res = await extractArticle(page);
+        expect(res).toEqual({
+            source: 'readability',
+            html: '<p>hello</p>',
+            title: 'Hello',
+            byline: 'Alice',
+            publishedTime: '2026-04-22',
+            siteName: 'Example',
+        });
+    });
+    it('drops undefined optional fields cleanly', async () => {
+        const page = fakePage({ source: 'fallback', html: '<main>x</main>', title: 't' });
+        const res = await extractArticle(page);
+        expect(res).toEqual({ source: 'fallback', html: '<main>x</main>', title: 't' });
+        expect(res).not.toHaveProperty('byline');
+        expect(res).not.toHaveProperty('publishedTime');
+    });
+    it('returns null on a missing body or malformed payload', async () => {
+        expect(await extractArticle(fakePage(null))).toBeNull();
+        expect(await extractArticle(fakePage('oops'))).toBeNull();
+        expect(await extractArticle(fakePage({ source: 'readability' }))).toBeNull();
+        expect(await extractArticle(fakePage({ html: '<p>x</p>' }))).toBeNull();
+    });
+    it('defaults title to empty string when the page omits it', async () => {
+        const page = fakePage({ source: 'pre', html: '<body><pre>x</pre></body>' });
+        const res = await extractArticle(page);
+        expect(res?.title).toBe('');
+        expect(res?.source).toBe('pre');
+    });
+});

package/dist/src/browser/base-page.d.ts CHANGED Viewed

@@ -9,6 +9,16 @@
  * getCookies, screenshot, tabs, etc.
  */
 import type { BrowserCookie, IPage, ScreenshotOptions, SnapshotOptions, WaitOptions } from '../types.js';
+import { type ResolveOptions, type TargetMatchLevel } from './target-resolver.js';
+export interface ResolveSuccess {
+    matches_n: number;
+    /**
+     * Cascading stale-ref tier the resolver traversed. Callers surface this to
+     * agents so `stable` / `reidentified` hits are visibly distinct from a
+     * clean `exact` match — the page changed, the action still succeeded.
+     */
+    match_level: TargetMatchLevel;
+}
 export declare abstract class BasePage implements IPage {
     protected _lastUrl: string | null;
     /** Cached previous snapshot hashes for incremental diff marking */
@@ -34,12 +44,12 @@ export declare abstract class BasePage implements IPage {
     abstract screenshot(options?: ScreenshotOptions): Promise<string>;
     abstract tabs(): Promise<unknown[]>;
     abstract selectTab(target: number | string): Promise<void>;
-    click(ref: string): Promise<void>;
+    click(ref: string, opts?: ResolveOptions): Promise<ResolveSuccess>;
     /** Override in subclasses with CDP native click support */
     protected tryNativeClick(_x: number, _y: number): Promise<boolean>;
-    typeText(ref: string, text: string): Promise<void>;
+    typeText(ref: string, text: string, opts?: ResolveOptions): Promise<ResolveSuccess>;
     pressKey(key: string): Promise<void>;
-    scrollTo(ref: string): Promise<unknown>;
+    scrollTo(ref: string, opts?: ResolveOptions): Promise<unknown>;
     getFormState(): Promise<Record<string, unknown>>;
     scroll(direction?: string, amount?: number): Promise<void>;
     autoScroll(options?: {

package/dist/src/browser/base-page.js CHANGED Viewed

@@ -10,8 +10,26 @@
  */
 import { generateSnapshotJs, getFormStateJs } from './dom-snapshot.js';
 import { pressKeyJs, waitForTextJs, waitForCaptureJs, waitForSelectorJs, scrollJs, autoScrollJs, networkRequestsJs, waitForDomStableJs, } from './dom-helpers.js';
-import { resolveTargetJs, clickResolvedJs, typeResolvedJs, scrollResolvedJs } from './target-resolver.js';
+import { resolveTargetJs, clickResolvedJs, typeResolvedJs, scrollResolvedJs, } from './target-resolver.js';
 import { TargetError } from './target-errors.js';
+/**
+ * Execute `resolveTargetJs` once, throw structured `TargetError` on failure.
+ * Single helper so click/typeText/scrollTo share one resolution pathway,
+ * which is what the selector-first contract promises agents.
+ */
+async function runResolve(page, ref, opts = {}) {
+    const resolution = (await page.evaluate(resolveTargetJs(ref, opts)));
+    if (!resolution.ok) {
+        throw new TargetError({
+            code: resolution.code,
+            message: resolution.message,
+            hint: resolution.hint,
+            candidates: resolution.candidates,
+            matches_n: resolution.matches_n,
+        });
+    }
+    return { matches_n: resolution.matches_n, match_level: resolution.match_level };
+}
 import { formatSnapshot } from '../snapshotFormatter.js';
 export class BasePage {
     _lastUrl = null;
@@ -37,25 +55,20 @@ export class BasePage {
         return this.evaluate(`${declarations}\n${js}`);
     }
     // ── Shared DOM helper implementations ──
-    async click(ref) {
+    async click(ref, opts = {}) {
         // Phase 1: Resolve target with fingerprint verification
-        const resolution = await this.evaluate(resolveTargetJs(ref));
-        if (!resolution.ok) {
-            throw new TargetError(resolution);
-        }
+        const resolved = await runResolve(this, ref, opts);
         // Phase 2: Execute click on resolved element
         const result = await this.evaluate(clickResolvedJs());
-        // Backwards compat: old format returned 'clicked' string
         if (typeof result === 'string' || result == null)
-            return;
-        // JS click succeeded
+            return resolved;
         if (result.status === 'clicked')
-            return;
+            return resolved;
         // JS click failed — try CDP native click if coordinates available
         if (result.x != null && result.y != null) {
             const success = await this.tryNativeClick(result.x, result.y);
             if (success)
-                return;
+                return resolved;
         }
         throw new Error(`Click failed: ${result.error ?? 'JS click and CDP fallback both failed'}`);
     }
@@ -63,26 +76,23 @@ export class BasePage {
     async tryNativeClick(_x, _y) {
         return false;
     }
-    async typeText(ref, text) {
-        // Phase 1: Resolve target with fingerprint verification
-        const resolution = await this.evaluate(resolveTargetJs(ref));
-        if (!resolution.ok) {
-            throw new TargetError(resolution);
-        }
-        // Phase 2: Execute type on resolved element
+    async typeText(ref, text, opts = {}) {
+        const resolved = await runResolve(this, ref, opts);
         await this.evaluate(typeResolvedJs(text));
+        return resolved;
     }
     async pressKey(key) {
         await this.evaluate(pressKeyJs(key));
     }
-    async scrollTo(ref) {
-        // Phase 1: Resolve target with fingerprint verification
-        const resolution = await this.evaluate(resolveTargetJs(ref));
-        if (!resolution.ok) {
-            throw new TargetError(resolution);
+    async scrollTo(ref, opts = {}) {
+        const resolved = await runResolve(this, ref, opts);
+        const result = (await this.evaluate(scrollResolvedJs()));
+        // Fold match_level into the scroll payload so the user-facing envelope
+        // carries it the same way click / type do.
+        if (result && typeof result === 'object') {
+            return { ...result, matches_n: resolved.matches_n, match_level: resolved.match_level };
         }
-        // Phase 2: Scroll to resolved element
-        return this.evaluate(scrollResolvedJs());
+        return { matches_n: resolved.matches_n, match_level: resolved.match_level };
     }
     async getFormState() {
         return (await this.evaluate(getFormStateJs()));

package/dist/src/browser/cdp.d.ts CHANGED Viewed

@@ -15,6 +15,7 @@ export interface CDPTarget {
     title?: string;
     webSocketDebuggerUrl?: string;
 }
+export declare const CDP_RESPONSE_BODY_CAPTURE_LIMIT: number;
 export declare class CDPBridge implements IBrowserFactory {
     private _ws;
     private _idCounter;

package/dist/src/browser/cdp.js CHANGED Viewed

@@ -17,6 +17,12 @@ import { isRecord, saveBase64ToFile } from '../utils.js';
 import { getAllElectronApps } from '../electron-apps.js';
 import { BasePage } from './base-page.js';
 const CDP_SEND_TIMEOUT = 30_000;
+// Memory guard for in-process capture. The 4k cap we used to apply everywhere
+// silently truncated JSON so `JSON.parse` failed or gave partial objects — the
+// primary agent-facing bug. Now we keep the full body up to a large cap and
+// surface `responseBodyFullSize` + `responseBodyTruncated` so downstream layers
+// can tell the agent what happened instead of lying about the payload.
+export const CDP_RESPONSE_BODY_CAPTURE_LIMIT = 8 * 1024 * 1024;
 export class CDPBridge {
     _ws = null;
     _idCounter = 0;
@@ -85,7 +91,12 @@ export class CDPBridge {
                         }
                     }
                 }
-                catch { }
+                catch (err) {
+                    if (process.env.OPENCLI_VERBOSE) {
+                        // eslint-disable-next-line no-console
+                        console.error('[cdp] Failed to parse WebSocket message:', err instanceof Error ? err.message : err);
+                    }
+                }
             });
         });
     }
@@ -240,12 +251,19 @@ class CDPPage extends BasePage {
                     const bodyFetch = this.bridge.send('Network.getResponseBody', { requestId: p.requestId }).then((result) => {
                         const r = result;
                         if (typeof r?.body === 'string') {
-                            this._networkEntries[idx].responsePreview = r.base64Encoded
-                                ? `base64:${r.body.slice(0, 4000)}`
-                                : r.body.slice(0, 4000);
+                            const fullSize = r.body.length;
+                            const truncated = fullSize > CDP_RESPONSE_BODY_CAPTURE_LIMIT;
+                            const body = truncated ? r.body.slice(0, CDP_RESPONSE_BODY_CAPTURE_LIMIT) : r.body;
+                            this._networkEntries[idx].responsePreview = r.base64Encoded ? `base64:${body}` : body;
+                            this._networkEntries[idx].responseBodyFullSize = fullSize;
+                            this._networkEntries[idx].responseBodyTruncated = truncated;
                         }
-                    }).catch(() => {
+                    }).catch((err) => {
                         // Body unavailable for some requests (e.g. uploads) — non-fatal
+                        if (process.env.OPENCLI_VERBOSE) {
+                            // eslint-disable-next-line no-console
+                            console.error(`[cdp] getResponseBody failed for ${p.requestId}:`, err instanceof Error ? err.message : err);
+                        }
                     }).finally(() => {
                         this._pendingBodyFetches.delete(bodyFetch);
                     });

package/dist/src/browser/compound.d.ts ADDED Viewed

@@ -0,0 +1,59 @@
+/**
+ * Compound-component expansion for high-agent-failure form controls.
+ *
+ * Agents burn turns on three recurring input categories because the raw
+ * attribute dump from `browser state` under-specifies them:
+ *
+ *   - date / time / datetime-local / month / week — agents type
+ *     free-form strings and the browser silently ignores mismatched formats.
+ *   - select — the snapshot caps visible options at ~6; agents don't know
+ *     the full option set, can't match by label, and waste turns clicking
+ *     to open the dropdown just to read options.
+ *   - file — the snapshot shows current filenames but not `accept` or
+ *     `multiple`; agents re-upload or pick unsupported MIME types.
+ *
+ * `compoundInfoOf(el)` returns a structured JSON summary agents can rely
+ * on. Included in `browser find --css` envelope so the agent gets the
+ * rich view without extra round-trips.
+ *
+ * Emitted as a JS source string (`COMPOUND_INFO_JS`) so it can be inlined
+ * into the generated evaluate scripts under find / snapshot / eval.
+ */
+export type DateLikeControl = 'date' | 'time' | 'datetime-local' | 'month' | 'week';
+export interface DateCompound {
+    control: DateLikeControl;
+    format: string;
+    current: string;
+    min?: string;
+    max?: string;
+}
+export interface SelectOption {
+    label: string;
+    value: string;
+    selected: boolean;
+    disabled?: boolean;
+}
+export interface SelectCompound {
+    control: 'select';
+    multiple: boolean;
+    current: string | string[];
+    options: SelectOption[];
+    options_total: number;
+}
+export interface FileCompound {
+    control: 'file';
+    multiple: boolean;
+    current: string[];
+    accept?: string;
+}
+export type CompoundInfo = DateCompound | SelectCompound | FileCompound;
+/** Max options included in a SelectCompound.options[]. Above this, `options_total` still reflects the true count. */
+export declare const COMPOUND_SELECT_OPTIONS_CAP = 50;
+/** Max characters per option label / file name. */
+export declare const COMPOUND_LABEL_CAP = 80;
+/**
+ * JavaScript source declaring `compoundInfoOf(el)`. Inlined into the JS
+ * emitted by `buildFindJs` (and any other evaluate script that needs the
+ * rich compound view). Returns a `CompoundInfo` object or `null`.
+ */
+export declare const COMPOUND_INFO_JS = "\nfunction compoundInfoOf(el) {\n  if (!el || !el.tagName) return null;\n  const tag = el.tagName;\n  const LABEL_CAP = 80;\n  const OPTS_CAP = 50;\n  if (tag === 'INPUT') {\n    const type = (el.getAttribute('type') || 'text').toLowerCase();\n    const FORMATS = {\n      'date': 'YYYY-MM-DD',\n      'time': 'HH:MM',\n      'datetime-local': 'YYYY-MM-DDTHH:MM',\n      'month': 'YYYY-MM',\n      'week': 'YYYY-W##',\n    };\n    if (FORMATS[type]) {\n      const info = {\n        control: type,\n        format: FORMATS[type],\n        current: (el.value == null ? '' : String(el.value)),\n      };\n      const min = el.getAttribute('min');\n      if (min) info.min = min;\n      const max = el.getAttribute('max');\n      if (max) info.max = max;\n      return info;\n    }\n    if (type === 'file') {\n      const info = {\n        control: 'file',\n        multiple: !!el.multiple,\n        current: [],\n      };\n      const accept = el.getAttribute('accept');\n      if (accept) info.accept = accept;\n      try {\n        if (el.files && el.files.length) {\n          for (let i = 0; i < el.files.length; i++) {\n            const name = (el.files[i].name || '').slice(0, LABEL_CAP);\n            info.current.push(name);\n          }\n        }\n      } catch (_) {}\n      return info;\n    }\n    return null;\n  }\n  if (tag === 'SELECT') {\n    const multiple = !!el.multiple;\n    const options = [];\n    const selectedLabels = [];\n    let total = 0;\n    try {\n      const opts = el.options || [];\n      total = opts.length;\n      // Walk ALL options so `current` reflects selections that sit beyond the\n      // serialization cap. Only the first OPTS_CAP entries get pushed into\n      // options[]; anything past the cap still contributes to selectedLabels\n      // so agents see the true current state of big dropdowns.\n      for (let i = 0; i < opts.length; i++) {\n        const o = opts[i];\n        const labelRaw = (o.label != null && o.label !== '') ? o.label : (o.text || '');\n        const label = String(labelRaw).trim().slice(0, LABEL_CAP);\n        if (i < OPTS_CAP) {\n          const entry = { label: label, value: o.value, selected: !!o.selected };\n          if (o.disabled) entry.disabled = true;\n          options.push(entry);\n        }\n        if (o.selected) selectedLabels.push(label);\n      }\n    } catch (_) {}\n    return {\n      control: 'select',\n      multiple: multiple,\n      current: multiple ? selectedLabels : (selectedLabels[0] || ''),\n      options: options,\n      options_total: total,\n    };\n  }\n  return null;\n}\n";