publishport-opencli 1.0.0

package/clis/zsxq/utils.js

@@ -0,0 +1,72 @@
+import{ArgumentError as z,AuthRequiredError as Y,CliError as W}from"@jackwener/opencli/errors";const J="wx.zsxq.com",Z="https://wx.zsxq.com";function $(B){return B&&typeof B==="object"&&!Array.isArray(B)?B:null}function X(...B){for(const G of B)if(Array.isArray(G))return G;return[]}export async function ensureZsxqPage(B){await B.goto(Z)}export async function ensureZsxqAuth(B){try{if(!await B.evaluate(`
+      (async () => {
+        try {
+          const r = await new Promise((resolve, reject) => {
+            const xhr = new XMLHttpRequest();
+            xhr.open('GET', 'https://api.zsxq.com/v2/groups', true);
+            xhr.withCredentials = true;
+            xhr.setRequestHeader('accept', 'application/json');
+            xhr.onload = () => {
+              if (xhr.status >= 200 && xhr.status < 300) {
+                try { resolve(JSON.parse(xhr.responseText)); }
+                catch { resolve(null); }
+              } else { resolve(null); }
+            };
+            xhr.onerror = () => resolve(null);
+            xhr.send();
+          });
+          return r !== null;
+        } catch { return false; }
+      })()
+    `))throw new Y("zsxq.com")}catch(G){if(G instanceof Y)throw G;throw new Y("zsxq.com")}}export async function getCookieValue(B,G){return(await B.getCookies({domain:J})).find((K)=>K.name===G)?.value}export async function getActiveGroupId(B){const G=await B.evaluate(`
+    (() => {
+      const target = localStorage.getItem('target_group');
+      if (target) {
+        try {
+          const parsed = JSON.parse(target);
+          if (parsed.group_id) return String(parsed.group_id);
+        } catch {}
+      }
+      return null;
+    })()
+  `);if(G)return G;throw new z("Cannot determine active group_id","Pass --group_id <id> or open the target 知识星球 page in Chrome first")}export async function browserJsonRequest(B,G){return await B.evaluate(`
+    (async () => {
+      const path = ${JSON.stringify(G)};
+
+      try {
+        return await new Promise((resolve) => {
+          const xhr = new XMLHttpRequest();
+          xhr.open('GET', path, true);
+          xhr.withCredentials = true;
+          xhr.setRequestHeader('accept', 'application/json, text/plain, */*');
+          xhr.onload = () => {
+            let parsed = null;
+            if (xhr.responseText) {
+              try { parsed = JSON.parse(xhr.responseText); }
+              catch {}
+            }
+
+            resolve({
+              ok: xhr.status >= 200 && xhr.status < 300,
+              url: path,
+              status: xhr.status,
+              data: parsed,
+              error: xhr.status >= 200 && xhr.status < 300 ? undefined : 'HTTP ' + xhr.status,
+            });
+          };
+          xhr.onerror = () => resolve({
+            ok: false,
+            url: path,
+            error: 'Network error',
+          });
+          xhr.send();
+        });
+      } catch (error) {
+        return {
+          ok: false,
+          url: path,
+          error: error instanceof Error ? error.message : String(error),
+        };
+      }
+    })()
+  `)}export async function fetchFirstJson(B,G){let H=null;for(const K of G){const Q=await browserJsonRequest(B,K);if(Q.ok)return Q;H=Q}if(!H)throw new W("FETCH_ERROR","No candidate endpoint returned JSON",`Checked endpoints: ${G.join(", ")}`);throw new W("FETCH_ERROR",H.error||"Failed to fetch ZSXQ API",`Checked endpoints: ${G.join(", ")}`)}export function unwrapRespData(B){const G=$(B);if(!G)throw new W("PARSE_ERROR","Invalid ZSXQ API response");if(G.succeeded===!1){const H=typeof G.code==="number"?String(G.code):"API_ERROR",K=typeof G.info==="string"?G.info:typeof G.error==="string"?G.error:"ZSXQ API returned an error";throw new W(H,K)}return G.resp_data??G.data??B}export function getTopicsFromResponse(B){const G=unwrapRespData(B);if(Array.isArray(G))return G;return X(G.topics,G.list,G.records,G.items,G.search_result)}export function getCommentsFromResponse(B){const G=unwrapRespData(B);if(Array.isArray(G))return G;return X(G.comments,G.list,G.items)}export function getGroupsFromResponse(B){const G=unwrapRespData(B);if(Array.isArray(G))return G;return X(G.groups,G.list,G.items)}export function getTopicFromResponse(B){const G=unwrapRespData(B);if(Array.isArray(G))return G[0]??null;if(typeof G.topic_id==="number"||typeof G.topic_id==="string")return G;const H=$(G);if(!H)return null;const K=H.topic;return K&&typeof K==="object"?K:null}export function getTopicAuthor(B){return B.owner?.name||B.talk?.owner?.name||B.question?.owner?.name||B.answer?.owner?.name||B.task?.owner?.name||B.solution?.owner?.name||""}export function getTopicText(B){return(B.title||"").replace(/\s+/g," ").trim()||getTopicContent(B)}export function getTopicContent(B){return([B.talk?.text,B.question?.text,B.answer?.text,B.task?.text,B.solution?.text].find((H)=>typeof H==="string"&&H.trim())||"").replace(/\s+/g," ").trim()}export function getTopicUrl(B){return B?`${Z}/topic/${B}`:Z}export function summarizeComments(B,G=3){return B.slice(0,G).map((H)=>{const K=H.owner?.name||"匿名",Q=H.repliee?.name?` -> ${H.repliee.name}`:"",j=(H.text||"").replace(/\s+/g," ").trim();return`${K}${Q}: ${j}`}).join(" | ")}export function toTopicRow(B){const G=B.topic_id??"",H=X(B.show_comments,B.comments);return{topic_id:G,type:B.type||"",group:B.group?.name||"",author:getTopicAuthor(B),title:getTopicText(B),content:getTopicContent(B),comments:B.comments_count??H.length??0,likes:B.likes_count??0,readers:B.readers_count??B.reading_count??0,time:B.create_time||"",comment_preview:summarizeComments(H),url:getTopicUrl(G)}}

package/dist/src/adapter-shadow.d.ts

@@ -0,0 +1,11 @@
+export type AdapterShadow = {
+    name: string;
+    userPath: string;
+    builtinPath: string;
+};
+export type AdapterShadowOptions = {
+    userClisDir?: string;
+    builtinClisDir?: string;
+};
+export declare function findShadowedUserAdapters(opts?: AdapterShadowOptions): AdapterShadow[];
+export declare function formatAdapterShadowIssue(shadows: AdapterShadow[]): string;

package/dist/src/adapter-shadow.js

@@ -0,0 +1,2 @@
+import*as d from"node:fs";import*as y from"node:os";import*as o from"node:path";import{fileURLToPath as j}from"node:url";import{findPackageRoot as w,getCliManifestPath as S}from"./package-paths.js";function g(){return o.join(w(j(import.meta.url)),"clis")}function f(e){try{return d.readdirSync(e,{withFileTypes:!0})}catch{return[]}}function C(e){try{const n=d.readFileSync(S(e),"utf-8"),t=JSON.parse(n),i=new Set;for(const s of t){const r=s.sourceFile??s.modulePath;if(r)i.add(o.resolve(e,r))}return i}catch{return new Set}}export function findShadowedUserAdapters(e={}){const n=e.userClisDir??o.join(y.homedir(),".opencli","clis"),t=e.builtinClisDir??g(),i=C(t),s=[];for(const r of f(n)){if(!r.isDirectory())continue;const a=r.name,l=o.join(n,a),m=o.join(t,a);for(const c of f(l)){if(!c.isFile()||!c.name.endsWith(".js"))continue;const p=o.join(l,c.name),u=o.join(m,c.name),h=o.resolve(u);if(!i.has(h))continue;s.push({name:`${a}/${c.name.replace(/\.js$/,"")}`,userPath:p,builtinPath:u})}}return s.sort((r,a)=>r.name.localeCompare(a.name))}export function formatAdapterShadowIssue(e){const n=e.slice(0,10),t=["Local adapter overrides shadow packaged adapters:"];for(const i of n)t.push(`  ${i.name}: ${i.userPath} overrides ${i.builtinPath}`);if(e.length>n.length)t.push(`  ... and ${e.length-n.length} more`);t.push("Remove the local ~/.opencli/clis copy, or run opencli adapter reset <site>, when you want packaged updates.");return t.join(`
+`)}

package/dist/src/adapter-shadow.test.d.ts

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

package/dist/src/adapter-source.d.ts

@@ -0,0 +1,11 @@
+import type { InternalCliCommand } from './registry.js';
+/**
+ * Resolve the editable source file path for an adapter.
+ *
+ * Priority:
+ * 1. cmd.source (set for FS-scanned JS and manifest lazy-loaded JS)
+ * 2. cmd._modulePath (set for manifest lazy-loaded JS)
+ *
+ * Skip manifest: prefixed pseudo-paths (YAML commands inlined in manifest).
+ */
+export declare function resolveAdapterSourcePath(cmd: InternalCliCommand): string | undefined;

package/dist/src/adapter-source.js

@@ -0,0 +1 @@
+import*as w from"node:fs";export function resolveAdapterSourcePath(g){const j=[];if(g.source&&!g.source.startsWith("manifest:"))j.push(g.source);if(g._modulePath)j.push(g._modulePath);for(const q of j)if(w.existsSync(q))return q;return j[0]}

package/dist/src/adapter-source.test.d.ts

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

package/dist/src/browser/analyze.d.ts

@@ -0,0 +1,118 @@
+/**
+ * `browser analyze <url>` — turn site-recon guesswork into deterministic CLI output.
+ *
+ * When an agent starts a new adapter, the first question is "which pattern am
+ * I looking at?" (A/B/C/D/E from site-recon docs) and "will Node-side fetch
+ * work, or will anti-bot middleware block me?". Today the agent has to open
+ * the page, poke `network`, try cURL, fail, guess again. This module condenses
+ * that into one call that returns a classification + evidence.
+ *
+ * Kept pure (no page imports) so the bulk is unit-testable; the CLI wrapper
+ * drives a real page, feeds the resulting signals here, and prints the verdict.
+ */
+import type { CliCommand } from '../registry.js';
+export interface PageSignals {
+    /** URL we navigated to (may redirect; both fields help agents notice that). */
+    requestedUrl: string;
+    finalUrl: string;
+    /** document.cookie split into names; value not needed for detection. */
+    cookieNames: string[];
+    /**
+     * Response bodies captured during the navigation + first few seconds.
+     * We only need enough body text to spot WAF markers; the CLI truncates
+     * per-entry before feeding us.
+     */
+    networkEntries: Array<{
+        url: string;
+        status: number;
+        contentType: string;
+        /** First N chars of body; null when not available. */
+        bodyPreview: string | null;
+    }>;
+    /**
+     * Which globals the page exposes on `window`. We don't care about the values,
+     * just presence — distinguishes Pattern B (SSR state) from Pattern A.
+     */
+    initialState: {
+        __INITIAL_STATE__: boolean;
+        __NUXT__: boolean;
+        __NEXT_DATA__: boolean;
+        __APOLLO_STATE__: boolean;
+    };
+    /** Document title — only for the human-debug `summary` field. */
+    title: string;
+}
+export type EndpointEvidenceVerdict = 'likely_data' | 'maybe_data' | 'noise' | 'blocked';
+export interface EndpointEvidence {
+    url: string;
+    status: number;
+    contentType: string;
+    real_data_score: number;
+    verdict: EndpointEvidenceVerdict;
+    reasons: string[];
+    sample_paths: string[];
+}
+export type AntiBotVendor = 'aliyun_waf' | 'cloudflare' | 'akamai' | 'geetest' | 'unknown';
+export interface AntiBotVerdict {
+    detected: boolean;
+    vendor: AntiBotVendor | null;
+    evidence: string[];
+    /** One-line imperative instruction for the agent. */
+    implication: string;
+}
+export declare function detectAntiBot(signals: PageSignals): AntiBotVerdict;
+export type Pattern = 'A' | 'B' | 'C' | 'D' | 'E' | 'unknown';
+export interface PatternVerdict {
+    pattern: Pattern;
+    reason: string;
+    /** How many JSON XHR/fetch responses we saw during navigation. */
+    json_responses: number;
+    /** How many observed responses look like real business data, not telemetry. */
+    real_data_candidates: number;
+    /** Count of non-2xx API responses — hint for token-gated (Pattern D). */
+    auth_failures: number;
+}
+export declare function scoreEndpointEvidence(entry: PageSignals['networkEntries'][number]): EndpointEvidence;
+export declare function scoreNetworkEvidence(signals: PageSignals): EndpointEvidence[];
+/**
+ * Apply the decision tree from `site-recon.md` mechanically.
+ *
+ * B beats A when initial-state globals are present: even if the page fetches
+ * more data via XHR afterwards, the SSR payload is the highest-leverage source.
+ * D (token-gated) dominates when we see 401/403 on what looks like API
+ * endpoints — without that, an authenticated route looks identical to A.
+ */
+export declare function classifyPattern(signals: PageSignals): PatternVerdict;
+export interface NearestAdapter {
+    site: string;
+    example_commands: string[];
+    reason: string;
+}
+/**
+ * Find existing adapters that target the same site.
+ *
+ * Keep the hostname match simple — agents extend naming conventions
+ * differently per site, so we match on the registered `domain` field and fall
+ * back to site-name containment. Returning `null` is fine; agents can always
+ * read site-memory docs.
+ */
+export declare function findNearestAdapter(finalUrl: string, registry: Map<string, CliCommand>): NearestAdapter | null;
+export interface AnalyzeReport {
+    requested_url: string;
+    final_url: string;
+    title: string;
+    pattern: PatternVerdict;
+    anti_bot: AntiBotVerdict;
+    initial_state: PageSignals['initialState'];
+    api_candidates: EndpointEvidence[];
+    nearest_adapter: NearestAdapter | null;
+    recommended_next_step: string;
+}
+/**
+ * Synthesize the verdict from collected signals + registry.
+ *
+ * The `recommended_next_step` is deliberately a single imperative
+ * sentence — agents act on it directly instead of re-deriving advice from
+ * the structured fields.
+ */
+export declare function analyzeSite(signals: PageSignals, registry: Map<string, CliCommand>): AnalyzeReport;

package/dist/src/browser/analyze.js

@@ -0,0 +1 @@
+const H=[{vendor:"aliyun_waf",cookiePatterns:[/^acw_sc__v2$/,/^acw_tc$/,/^ssxmod_itna/],bodyPatterns:[/arg1\s*=\s*['"][0-9A-F]{30,}/,/\/ntc_captcha\//i],implication:"Direct Node-side fetch/curl will return the slider HTML. Validate the endpoint in browser context first; HTML COOKIE adapters still finish with Node-side fetch + page.getCookies."},{vendor:"cloudflare",cookiePatterns:[/^__cf_bm$/,/^cf_clearance$/,/^__cfduid$/],bodyPatterns:[/Cloudflare Ray ID/i,/Checking your browser before accessing/i,/cf-chl-/i],implication:"Cloudflare bot check. Start from a real browser session; probe in browser context first. HTML COOKIE adapters still finish with Node-side fetch + page.getCookies."},{vendor:"akamai",cookiePatterns:[/^_abck$/,/^bm_sz$/,/^bm_sv$/],bodyPatterns:[/akamai/i],implication:"Akamai Bot Manager. Probe in browser context first; keep final HTML COOKIE adapters on Node-side fetch + page.getCookies."},{vendor:"geetest",cookiePatterns:[],bodyPatterns:[/geetest/i,/gt_captcha/i],implication:"Geetest slider/puzzle captcha. Agent cannot bypass programmatically — requires UI strategy or human-in-loop."}];export function detectAntiBot(q){const M=[];let Q=null;for(const V of H){const Z=[];for(const $ of V.cookiePatterns){const X=q.cookieNames.find((O)=>$.test(O));if(X)Z.push(`cookie:${X}`)}for(const $ of V.bodyPatterns)for(const X of q.networkEntries)if(X.bodyPreview&&$.test(X.bodyPreview)){Z.push(`body:${X.url}`);break}if(Z.length>0&&!Q){Q=V;M.push(...Z)}}if(!Q)return{detected:!1,vendor:null,evidence:[],implication:"No known anti-bot signatures. Try Node-side COOKIE fetch first; if endpoint validation is blocked, retry from browser context."};return{detected:!0,vendor:Q.vendor,evidence:M,implication:Q.implication}}const I=/(?:analytics|beacon|collect|telemetry|tracking|sentry|doubleclick|google-analytics|googletagmanager|adservice|\/ads?(?:[/?#]|$)|metrics?|pixel|personalization|experiment|\/events?(?:[/?#]|$))/i,U=/^(?:data|items?|results?|records?|list|rows?|edges?|nodes?|timeline|users?|title|name|text|content|body|price|amount|id|url|avatar|nickname|desc|comments?|likes?|shares?|total|page|cursor|next|rank|score|date|time|author)$/i,B=/^(?:event|events|trace|traceid|sessionid|clientid|visitorid|experiment|abtest|beacon|analytics|metrics?|pixel|log|logs)$/i;function P(q){return Math.max(0,Math.min(1,Math.round(q*100)/100))}function R(q){if(!q)return null;const M=q.trim();if(!M)return null;try{return JSON.parse(M)}catch{return M}}function Y(q,M="$",Q=[],V=0){if(V>4||Q.length>=24)return Q;if(Array.isArray(q)){Q.push(`${M}:array(${q.length})`);if(q.length>0)Y(q[0],`${M}[0]`,Q,V+1);return Q}if(!q||typeof q!=="object"){Q.push(`${M}:${typeof q}`);return Q}const Z=Object.entries(q).slice(0,12);for(const[$,X]of Z){Q.push(`${M}.${$}`);if(Array.isArray(X))Q.push(`${M}.${$}:array(${X.length})`);else if(X&&typeof X==="object")Y(X,`${M}.${$}`,Q,V+1);else Q.push(`${M}.${$}:${typeof X}`)}return Q}function G(q,M,Q=0){if(Q>4||!q||typeof q!=="object")return 0;if(Array.isArray(q))return q.slice(0,3).reduce((V,Z)=>V+G(Z,M,Q+1),0);return Object.entries(q).reduce((V,[Z,$])=>V+(M(Z)?1:0)+G($,M,Q+1),0)}function T(q,M=0){if(M>4||!q||typeof q!=="object")return!1;if(Array.isArray(q))return q.length>0;return Object.values(q).some((Q)=>T(Q,M+1))}export function scoreEndpointEvidence(q){const M=[],Q=R(q.bodyPreview);let V=0;if(q.status>=200&&q.status<300){V+=0.15;M.push("2xx status")}else if(q.status===401||q.status===403)return{url:q.url,status:q.status,contentType:q.contentType,real_data_score:0.05,verdict:"blocked",reasons:["auth-blocked status"],sample_paths:[]};else M.push(`non-2xx status ${q.status}`);if(/json/i.test(q.contentType)){V+=0.2;M.push("json content-type")}else if(/html/i.test(q.contentType)){V-=0.25;M.push("html content-type")}else if(/javascript|text/i.test(q.contentType)){V+=0.05;M.push("text/script content-type")}if(I.test(q.url)){V-=0.3;M.push("telemetry-like url")}const Z=Y(Q).slice(0,8);if(typeof Q==="string"){if(/^\s*</.test(Q)||/<!doctype html|<html/i.test(Q)){V-=0.25;M.push("html body")}else if(Q.trim().length>20){V+=0.05;M.push("non-empty text body")}}else if(Array.isArray(Q))if(Q.length>0){V+=0.3;M.push("non-empty top-level array")}else{V-=0.15;M.push("empty array")}else if(Q&&typeof Q==="object"){if(Object.keys(Q).length===0){V-=0.15;M.push("empty object")}else{V+=0.12;M.push("json object body")}const L=G(Q,(W)=>U.test(W));if(L>0){V+=Math.min(0.3,L*0.05);M.push(`${L} business-like key${L===1?"":"s"}`)}if(T(Q)){V+=0.2;M.push("nested non-empty array")}const z=G(Q,(W)=>B.test(W));if(z>0&&L===0){V-=Math.min(0.25,z*0.08);M.push(`${z} tracking-like key${z===1?"":"s"} without business keys`)}}const $=P(V),X=$>=0.65?"likely_data":$>=0.35?"maybe_data":"noise";return{url:q.url,status:q.status,contentType:q.contentType,real_data_score:$,verdict:X,reasons:M,sample_paths:Z}}export function scoreNetworkEvidence(q){return q.networkEntries.map(scoreEndpointEvidence).filter((M)=>M.verdict!=="noise"||M.real_data_score>0).sort((M,Q)=>Q.real_data_score-M.real_data_score).slice(0,8)}export function classifyPattern(q){const M=q.networkEntries.filter((X)=>/json/i.test(X.contentType)),V=scoreNetworkEvidence(q).filter((X)=>X.verdict==="likely_data"||X.verdict==="maybe_data").length,Z=q.networkEntries.filter((X)=>X.status===401||X.status===403).length,$=q.initialState.__INITIAL_STATE__||q.initialState.__NUXT__||q.initialState.__NEXT_DATA__||q.initialState.__APOLLO_STATE__;if(Z>=2&&M.length>=1)return{pattern:"D",reason:`${Z} auth-failing API responses seen — endpoint is token-gated`,json_responses:M.length,real_data_candidates:V,auth_failures:Z};if($)return{pattern:"B",reason:`SSR state global present: ${Object.entries(q.initialState).filter(([,O])=>O).map(([O])=>O).join(", ")}`,json_responses:M.length,real_data_candidates:V,auth_failures:Z};if(V>=1)return{pattern:"A",reason:`${V} captured response${V===1?"":"s"} look like real data — inspect api_candidates before choosing a strategy`,json_responses:M.length,real_data_candidates:V,auth_failures:Z};return{pattern:"C",reason:M.length>0?`${M.length} JSON response${M.length===1?"":"s"} observed, but none look like target data — likely telemetry/side-channel; treat as HTML/DOM until an endpoint validates`:"No JSON XHR and no SSR state — HTML scrape (Pattern C); escalate to E manually if WebSocket traffic appears",json_responses:M.length,real_data_candidates:V,auth_failures:Z}}export function findNearestAdapter(q,M){let Q;try{Q=new URL(q).hostname}catch{return null}const V=Q.replace(/^www\./,""),Z=V.split("."),$=Z.slice(-2).join("."),X=Z.length>1?Z[Z.length-2]:V,O=new Map;for(const z of M.values()){const W=z.domain?.toLowerCase();if(W&&(V.endsWith(W)||W.endsWith($))||z.site.toLowerCase()===X?.toLowerCase()||V.includes(z.site.toLowerCase())){const J=O.get(z.site)??[];J.push(z);O.set(z.site,J)}}if(O.size===0)return null;let L=null;for(const z of O)if(!L||z[1].length>L[1].length)L=z;if(!L)return null;return{site:L[0],example_commands:L[1].slice(0,5).map((z)=>`${z.site} ${z.name}`),reason:`${L[1].length} existing adapter${L[1].length===1?"":"s"} target this site — reuse strategy/cookie config`}}export function analyzeSite(q,M){const Q=classifyPattern(q),V=detectAntiBot(q),Z=scoreNetworkEvidence(q),$=findNearestAdapter(q.finalUrl,M);let X;if(V.detected)X=V.implication;else if(Q.pattern==="A")X="Inspect `api_candidates`, then replay the best endpoint and record the status/content-type/sample shape in your strategy note; do not choose API strategy from XHR count alone.";else if(Q.pattern==="B")X='Read the SSR global via `opencli browser eval "JSON.stringify(window.__INITIAL_STATE__ ?? window.__NUXT__ ?? window.__NEXT_DATA__ ?? window.__APOLLO_STATE__)"` — no API needed.';else if(Q.pattern==="C")X="No API visible — use SSR HTML scrape (e.g. `opencli browser extract`) against the rendered page.";else if(Q.pattern==="D")X="Endpoints need auth. Re-open the page from a signed-in session, then retry analyze; see `field-decode-playbook` §4 for token tracing.";else if(Q.pattern==="E")X="WebSocket stream detected — find the underlying HTTP poll/long-poll endpoint; raw WS is not supported.";else X="No strong signal. Manually inspect `opencli browser network --all` and pick a pattern.";return{requested_url:q.requestedUrl,final_url:q.finalUrl,title:q.title,pattern:Q,anti_bot:V,initial_state:q.initialState,api_candidates:Z,nearest_adapter:$,recommended_next_step:X}}

package/dist/src/browser/analyze.test.d.ts

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

package/dist/src/browser/article-extract.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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.
+ */
+export interface ExtractArticleOptions {
+    /** CSS selectors removed from the cloned document before Readability runs. */
+    cleanSelectors?: string[];
+    /** Fallback chain when Readability fails. Defaults to the common structural ids. */
+    fallbackSelectors?: string[];
+    /** Bypass `isProbablyReaderable` and always attempt a parse. */
+    force?: boolean;
+}
+export type ExtractSource = 'readability' | 'fallback' | 'raw-text' | 'pre';
+export interface ExtractedArticle {
+    html: string;
+    title: string;
+    byline?: string;
+    publishedTime?: string;
+    siteName?: string;
+    source: ExtractSource;
+}
+export declare const DEFAULT_FALLBACK_SELECTORS: string[];
+/**
+ * Build the JS expression evaluated in-page to extract the article. Exported
+ * for testability — callers on the host side should use `extractArticle`.
+ */
+export declare function buildExtractArticleJs(options?: ExtractArticleOptions): string;
+export interface PageLike {
+    evaluate(js: string): Promise<unknown>;
+}
+/**
+ * Run the extract pipeline on the given page. Returns `null` when no usable
+ * content is found (Readability miss + empty fallback chain).
+ */
+export declare function extractArticle(page: PageLike, options?: ExtractArticleOptions): Promise<ExtractedArticle | null>;

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

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

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

@@ -0,0 +1,2 @@
+import*as j from"node:fs";import{createRequire as O}from"node:module";const v=O(import.meta.url);let Y=null;function U(){if(Y)return Y;const Q=v.resolve("@mozilla/readability/Readability.js"),V=v.resolve("@mozilla/readability/Readability-readerable.js");Y={readability:j.readFileSync(Q,"utf8"),readerable:j.readFileSync(V,"utf8")};return Y}export const DEFAULT_FALLBACK_SELECTORS=["main",'[role="main"]',"#main-content","#main","#content",".content","article","body"];const X=80;export function buildExtractArticleJs(Q={}){const{readability:V,readerable:Z}=U(),W=Q.cleanSelectors??[],z=Q.fallbackSelectors??DEFAULT_FALLBACK_SELECTORS,$=!!Q.force,D=JSON.stringify(V),G=JSON.stringify(Z),I=JSON.stringify(W),J=JSON.stringify(z),M=JSON.stringify($);return["(() => {","  const cleanSelectors = "+I+";","  const fallbackSelectors = "+J+";","  const force = "+M+";","  const minFallbackText = "+X+";","  const readabilitySrc = "+D+";","  const readerableSrc = "+G+";","","  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(`
+`)}export async function extractArticle(Q,V={}){const Z=buildExtractArticleJs(V),W=await Q.evaluate(Z);if(W==null||typeof W!=="object")return null;const z=W;if(typeof z.html!=="string"||typeof z.source!=="string")return null;const $=z.source;return{html:z.html,title:typeof z.title==="string"?z.title:"",...z.byline&&{byline:z.byline},...z.publishedTime&&{publishedTime:z.publishedTime},...z.siteName&&{siteName:z.siteName},source:$}}

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

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

package/dist/src/browser/ax-snapshot.d.ts

@@ -0,0 +1,37 @@
+/**
+ * AX-backed browser snapshot prototype.
+ *
+ * This is intentionally additive to the current DOM snapshot. It learns from
+ * agent-browser's accessibility-tree refs without changing default `state`
+ * output until the AX path proves itself on fixtures and real SaaS workflows.
+ */
+export interface BrowserRef {
+    ref: string;
+    backendNodeId?: number;
+    role: string;
+    name: string;
+    nth?: number;
+    frame?: {
+        frameId?: string;
+        sessionId?: string;
+        url?: string;
+        targetUrl?: string;
+    };
+}
+export interface AxSnapshotTree {
+    tree: unknown;
+    frame?: BrowserRef['frame'];
+}
+export interface AxSnapshotBuildResult {
+    text: string;
+    refs: Map<string, BrowserRef>;
+}
+export declare function buildAxSnapshot(axTree: unknown, opts?: {
+    maxDepth?: number;
+    interactiveOnly?: boolean;
+}): AxSnapshotBuildResult;
+export declare function buildAxSnapshotFromTrees(trees: AxSnapshotTree[], opts?: {
+    maxDepth?: number;
+    interactiveOnly?: boolean;
+}): AxSnapshotBuildResult;
+export declare function findAxRefReplacement(axTree: unknown, ref: BrowserRef): BrowserRef | null;

package/dist/src/browser/ax-snapshot.js

@@ -0,0 +1,2 @@
+const _=new Set(["button","link","textbox","searchbox","checkbox","radio","combobox","listbox","menuitem","menuitemcheckbox","menuitemradio","option","slider","spinbutton","switch","tab","treeitem"]),T=new Set(["article","cell","columnheader","gridcell","heading","listitem","main","navigation","region","rowheader"]),j=new Set(["generic","group","list","none","presentation","RootWebArea","WebArea"]);export function buildAxSnapshot(n,e={}){return buildAxSnapshotFromTrees([{tree:n}],e)}export function buildAxSnapshotFromTrees(n,e={}){const r=["source: ax","---"],i=new Map;let o=1;for(const[s,a]of n.entries()){if(s>0){const d=a.frame?.url?JSON.stringify(a.frame.url):JSON.stringify(a.frame?.frameId??`frame:${s}`);r.push(`frame ${d}:`)}o=U(a.tree,r,i,o,{...e,frame:a.frame,baseDepth:s>0?1:0})}r.push("---");r.push(`interactive: ${i.size}`);return{text:r.join(`
+`),refs:i}}function U(n,e,r,i,o){const a=(Array.isArray(n?.nodes)?n.nodes:[]).filter((t)=>t&&!t.ignored),d=new Map,S=new Set;for(const t of a){if(typeof t.nodeId==="string")d.set(t.nodeId,t);for(const f of t.childIds??[])S.add(f)}const J=a.filter((t)=>{if(!t.nodeId)return!1;const f=c(t.role);return!S.has(t.nodeId)||f==="RootWebArea"||f==="WebArea"})[0]??a[0],L=Math.max(1,Math.min(Number(o.maxDepth)||50,200)),W=X(a),N=new Map;function I(t,f){if(!t||f>L)return!1;const h=c(t.role)||"generic",u=b(c(t.name)),m=b(c(t.value)||p(t,"value")),V=p(t,"disabled"),w=p(t,"checked"),k=p(t,"expanded"),A=p(t,"selected"),O=E(h,u,t.backendDOMNodeId),$=O||!!u||!!m||T.has(h)||!o.interactiveOnly&&!j.has(h),M=e.length;let R=!1;for(const g of t.childIds??[])if(I(d.get(g),f+1))R=!0;if(!$&&!R){e.length=M;return!1}if($){const g="  ".repeat(f),l=[];let v="";if(O){const x=String(i++);v=`[${x}]`;const y=C(h,u),D=N.get(y)??0;N.set(y,D+1);r.set(x,{ref:x,backendNodeId:t.backendDOMNodeId,role:h,name:u,...W.get(y)>1?{nth:D}:{},...o.frame?{frame:o.frame}:{}})}if(u)l.push(JSON.stringify(u));if(m&&m!==u)l.push(`value=${JSON.stringify(m)}`);if(w)l.push(`checked=${w}`);if(k)l.push(`expanded=${k}`);if(A)l.push(`selected=${A}`);if(V==="true")l.push("disabled");e.splice(M,0,`${g}${v}${h}${l.length?` ${l.join(" ")}`:""}`)}return!0}I(J,o.baseDepth);return i}export function findAxRefReplacement(n,e){const r=Array.isArray(n?.nodes)?n.nodes:[],i=e.nth??0;let o=0;for(const s of r){if(!s||s.ignored)continue;const a=c(s.role),d=b(c(s.name));if(a!==e.role||d!==e.name)continue;if(o===i){if(typeof s.backendDOMNodeId!=="number")return null;return{...e,backendNodeId:s.backendDOMNodeId}}o++}return null}function E(n,e,r){if(typeof r!=="number")return!1;if(_.has(n))return!0;return T.has(n)&&!!e}function X(n){const e=new Map;for(const r of n){if(!r||r.ignored)continue;const i=c(r.role),o=b(c(r.name));if(!E(i,o,r.backendDOMNodeId))continue;const s=C(i,o);e.set(s,(e.get(s)??0)+1)}return e}function C(n,e){return`${n}\x00${e}`}function c(n){const e=n?.value;if(typeof e==="string")return e;if(typeof e==="number"||typeof e==="boolean")return String(e);return""}function p(n,e){const r=n.properties?.find((i)=>i.name===e);return c(r?.value)}function b(n){return n.replace(/\s+/g," ").trim().slice(0,160)}

package/dist/src/browser/ax-snapshot.test.d.ts

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

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

@@ -0,0 +1,151 @@
+/**
+ * BasePage — shared IPage method implementations for DOM helpers.
+ *
+ * Both Page (daemon-backed) and CDPPage (direct CDP) execute JS the same way
+ * for DOM operations. This base class deduplicates ~200 lines of identical
+ * click/type/scroll/wait/snapshot/interceptor methods.
+ *
+ * Subclasses implement the transport-specific methods: goto, evaluate,
+ * getCookies, screenshot, tabs, etc.
+ */
+import type { BrowserCookie, BrowserEvaluateFunction, FetchJsonOptions, 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 interface FillTextResult extends ResolveSuccess {
+    filled: boolean;
+    verified: boolean;
+    expected: string;
+    actual: string;
+    length: number;
+    mode?: 'input' | 'textarea' | 'contenteditable';
+}
+export interface SetCheckedResult extends ResolveSuccess {
+    checked: boolean;
+    changed: boolean;
+    kind?: string;
+}
+export interface UploadFilesResult extends ResolveSuccess {
+    uploaded: boolean;
+    files: number;
+    file_names: string[];
+    target: string;
+    multiple?: boolean;
+    accept?: string;
+}
+export interface DragResult {
+    dragged: boolean;
+    source: string;
+    target: string;
+    source_matches_n: number;
+    target_matches_n: number;
+    source_match_level: TargetMatchLevel;
+    target_match_level: TargetMatchLevel;
+}
+export declare abstract class BasePage implements IPage {
+    protected _lastUrl: string | null;
+    /** Cached previous snapshot hashes for incremental diff marking */
+    private _prevSnapshotHashes;
+    private _cdpTargetMarkerSeq;
+    private _axRefs;
+    abstract goto(url: string, options?: {
+        waitUntil?: 'load' | 'none';
+        settleMs?: number;
+        allowBoundNavigation?: boolean;
+    }): Promise<void>;
+    abstract evaluate<T = unknown>(js: string): Promise<T>;
+    abstract evaluate<Args extends unknown[], T>(fn: BrowserEvaluateFunction<Args, T>, ...args: Args): Promise<Awaited<T>>;
+    /**
+     * Safely evaluate JS with pre-serialized arguments.
+     * Each key in `args` becomes a `const` declaration with JSON-serialized value,
+     * wrapped in a lexical block to avoid polluting the global execution context.
+     *
+     * Why a block: Chrome's Runtime.evaluate shares a single global context per page.
+     * Top-level `const` declarations persist across calls, so re-declaring the same
+     * variable name (e.g. `markerAttr` in both click resolution and file upload)
+     * throws "SyntaxError: Identifier has already been declared". A block keeps
+     * the args scoped without forcing callers to pass expression-only code.
+     *
+     * Usage:
+     *   page.evaluateWithArgs(`(async () => { return sym; })()`, { sym: userInput })
+     */
+    evaluateWithArgs(js: string, args: Record<string, unknown>): Promise<unknown>;
+    fetchJson(url: string, opts?: FetchJsonOptions): Promise<unknown>;
+    abstract getCookies(opts?: {
+        domain?: string;
+        url?: string;
+    }): Promise<BrowserCookie[]>;
+    abstract screenshot(options?: ScreenshotOptions): Promise<string>;
+    annotatedScreenshot(options?: ScreenshotOptions): Promise<string>;
+    abstract tabs(): Promise<unknown[]>;
+    abstract selectTab(target: number | string): Promise<void>;
+    click(ref: string, opts?: ResolveOptions): Promise<ResolveSuccess>;
+    /** Uses native CDP click support when the concrete page exposes it. */
+    protected tryNativeClick(x: number, y: number): Promise<boolean>;
+    protected tryNativeMouseMove(x: number, y: number): Promise<boolean>;
+    protected tryNativeDoubleClick(x: number, y: number): Promise<boolean>;
+    protected tryNativeDrag(from: {
+        x: number;
+        y: number;
+    }, to: {
+        x: number;
+        y: number;
+    }): Promise<boolean>;
+    protected tryClickAxRef(ref: string): Promise<ResolveSuccess | null>;
+    private resolveAxRefPoint;
+    private axBoxCenter;
+    /** Uses native CDP text insertion when the concrete page exposes it. */
+    protected tryNativeType(text: string): Promise<boolean>;
+    /** Uses native CDP key events when the concrete page exposes them. */
+    protected tryNativeKeyPress(key: string, modifiers: string[]): Promise<boolean>;
+    protected isResolvedFocused(): Promise<boolean>;
+    /**
+     * Run a DOM-domain CDP command against `window.__resolved`.
+     *
+     * CDP DOM.focus / DOM.scrollIntoViewIfNeeded need a nodeId, while our
+     * resolver stores the live Element in page JS. Bridge the two worlds with a
+     * short-lived marker attribute, then query it through CDP.
+     */
+    protected tryCdpOnResolvedElement(method: 'DOM.focus' | 'DOM.scrollIntoViewIfNeeded'): Promise<boolean>;
+    typeText(ref: string, text: string, opts?: ResolveOptions): Promise<ResolveSuccess>;
+    hover(ref: string, opts?: ResolveOptions): Promise<ResolveSuccess>;
+    focus(ref: string, opts?: ResolveOptions): Promise<ResolveSuccess & {
+        focused: boolean;
+    }>;
+    dblClick(ref: string, opts?: ResolveOptions): Promise<ResolveSuccess>;
+    private readCheckableState;
+    setChecked(ref: string, checked: boolean, opts?: ResolveOptions): Promise<SetCheckedResult>;
+    private setFileInputBySelector;
+    uploadFiles(ref: string, files: string[], opts?: ResolveOptions): Promise<UploadFilesResult>;
+    drag(source: string, target: string, opts?: {
+        from?: ResolveOptions;
+        to?: ResolveOptions;
+    }): Promise<DragResult>;
+    fillText(ref: string, text: string, opts?: ResolveOptions): Promise<FillTextResult>;
+    pressKey(key: string): Promise<void>;
+    scrollTo(ref: string, opts?: ResolveOptions): Promise<unknown>;
+    getFormState(): Promise<Record<string, unknown>>;
+    scroll(direction?: string, amount?: number): Promise<void>;
+    autoScroll(options?: {
+        times?: number;
+        delayMs?: number;
+    }): Promise<void>;
+    networkRequests(includeStatic?: boolean): Promise<unknown[]>;
+    consoleMessages(_level?: string): Promise<unknown[]>;
+    wait(options: number | WaitOptions): Promise<void>;
+    snapshot(opts?: SnapshotOptions): Promise<unknown>;
+    private collectAxSnapshotTrees;
+    getCurrentUrl(): Promise<string | null>;
+    installInterceptor(pattern: string): Promise<void>;
+    getInterceptedRequests(): Promise<unknown[]>;
+    waitForCapture(timeout?: number): Promise<void>;
+    /** Fallback basic snapshot */
+    protected _basicSnapshot(opts?: Pick<SnapshotOptions, 'interactive' | 'compact' | 'maxDepth' | 'raw'>): Promise<unknown>;
+}