publishport-opencli 1.0.0

package/dist/src/serialization.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Serialization and formatting helpers for CLI commands and args.
+ *
+ * Used by the `list` command, Commander --help, and build-manifest.
+ * Separated from registry.ts to keep the registry focused on types + registration.
+ */
+import type { Arg, CliCommand } from './registry.js';
+export type SerializedArg = {
+    name: string;
+    type: string;
+    required: boolean;
+    valueRequired: boolean;
+    positional: boolean;
+    choices: string[];
+    default: unknown;
+    help: string;
+};
+/** Stable arg schema — every field is always present (no sparse objects). */
+export declare function serializeArg(a: Arg): SerializedArg;
+/** Full command metadata for structured output (json/yaml). */
+export declare function serializeCommand(cmd: CliCommand): {
+    command: string;
+    site: string;
+    name: string;
+    aliases: string[];
+    description: string;
+    access: import("./registry.js").CommandAccess;
+    strategy: string;
+    browser: boolean;
+    args: SerializedArg[];
+    columns: string[];
+    domain: string | null;
+    example: string;
+    defaultFormat: "table" | "plain" | "json" | "yaml" | "yml" | "md" | "markdown" | "csv" | null;
+    siteSession: import("./registry.js").SiteSessionMode | null;
+};
+/** Human-readable arg summary: `<required> [optional]` style. */
+export declare function formatArgSummary(args: Arg[]): string;
+/** Agent-facing canonical invocation. Adapter authors may override with `example`. */
+export declare function formatCommandExample(cmd: CliCommand): string;
+/** Generate the --help appendix showing registry metadata not exposed by Commander. */
+export declare function formatRegistryHelpText(cmd: CliCommand): string;

package/dist/src/serialization.js

@@ -0,0 +1,4 @@
+import{fullName as J,strategyLabel as K}from"./registry.js";export function serializeArg(k){return{name:k.name,type:k.type??"string",required:!!k.required,valueRequired:!!k.valueRequired,positional:!!k.positional,choices:k.choices??[],default:k.default??null,help:k.help??""}}export function serializeCommand(k){return{command:J(k),site:k.site,name:k.name,aliases:k.aliases??[],description:k.description,access:k.access,strategy:K(k),browser:!!k.browser,args:k.args.map(serializeArg),columns:k.columns??[],domain:k.domain??null,example:formatCommandExample(k),defaultFormat:k.defaultFormat??null,siteSession:k.siteSession??null}}export function formatArgSummary(k){return k.map((q)=>{if(q.positional)return q.required?`<${q.name}>`:`[${q.name}]`;return q.required?`--${q.name}`:`[--${q.name}]`}).join(" ")}function M(k){if(k.length<=4)return k.join(", ");return`${k.slice(0,4).join(", ")}, ... (+${k.length-4} more)`}function F(k){return`<${k}>`}export function formatCommandExample(k){if(k.example?.trim())return k.example.trim();const q=["opencli",k.site,k.name];for(const v of k.args)if(v.positional&&v.required)q.push(F(v.name));for(const v of k.args){if(v.positional||!v.required)continue;q.push(`--${v.name}`);if(v.type!=="bool"&&v.type!=="boolean")q.push(F(v.name))}q.push("-f","yaml");return q.join(" ")}export function formatRegistryHelpText(k){const q=[],v=k.args.filter((B)=>B.choices?.length);for(const B of v){const H=B.positional?`<${B.name}>`:`--${B.name}`,I=B.default!=null?`  (default: ${B.default})`:"";q.push(`  ${H}: ${M(B.choices)}${I}`)}const D=[];D.push(`Access: ${k.access}`);D.push(`Browser: ${k.browser?"yes":"no"}`);if(k.domain)D.push(`Domain: ${k.domain}`);if(k.defaultFormat)D.push(`Default format: ${k.defaultFormat}`);if(k.aliases?.length)D.push(`Aliases: ${k.aliases.join(", ")}`);q.push(D.join(" | "));q.push(`Example: ${formatCommandExample(k)}`);if(k.columns?.length)q.push(`Output columns: ${k.columns.join(", ")}`);return`
+`+q.join(`
+`)+`
+`}

package/dist/src/serialization.test.d.ts

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

package/dist/src/skills.d.ts

@@ -0,0 +1,14 @@
+export interface OpenCliSkillInfo {
+    name: string;
+    description: string;
+    version: string;
+    path: string;
+}
+export interface OpenCliSkillReadResult {
+    skill: string;
+    path: string;
+    content: string;
+}
+export declare function getSkillsRoot(packageRoot?: string): string;
+export declare function listOpenCliSkills(packageRoot?: string): OpenCliSkillInfo[];
+export declare function readOpenCliSkill(target: string, relpath?: string, packageRoot?: string): OpenCliSkillReadResult;

package/dist/src/skills.js

@@ -0,0 +1,6 @@
+import*as s from"node:fs";import*as o from"node:path";import{fileURLToPath as d}from"node:url";import h from"js-yaml";import{ArgumentError as l}from"./errors.js";import{findPackageRoot as k}from"./package-paths.js";const y=d(import.meta.url);export function getSkillsRoot(e=k(y)){return o.join(e,"skills")}export function listOpenCliSkills(e){const n=getSkillsRoot(e);if(!s.existsSync(n))return[];return s.readdirSync(n,{withFileTypes:!0}).filter((t)=>t.isDirectory()&&t.name.startsWith("opencli-")).map((t)=>S(n,t.name)).filter((t)=>t!==null).sort((t,i)=>t.name.localeCompare(i.name))}export function readOpenCliSkill(e,n="",t){const{name:i,pathInSkill:r}=L(e,n);if(!i.startsWith("opencli-"))throw new l(`Unknown OpenCLI skill: ${i}`,'Run "opencli skills list" to see available OpenCLI skills.');const f=getSkillsRoot(t),a=o.join(f,i);if(!w(a)||!s.existsSync(o.join(a,"SKILL.md")))throw new l(`Unknown OpenCLI skill: ${i}`,'Run "opencli skills list" to see available OpenCLI skills.');const c=u(r||"SKILL.md"),p=o.resolve(a,c),m=o.relative(a,p);if(m.startsWith("..")||o.isAbsolute(m))throw new l(`Invalid skill path: ${c}`,"Skill paths must stay inside the selected OpenCLI skill.");if(!s.existsSync(p)||!s.statSync(p).isFile())throw new l(`Skill file not found: ${i}/${c}`,'Run "opencli skills list <skill>" is not supported yet; read SKILL.md or a known references/... file.');return{skill:i,path:c,content:s.readFileSync(p,"utf8")}}function S(e,n){const t=o.join(e,n,"SKILL.md");if(!s.existsSync(t))return null;const i=s.readFileSync(t,"utf8"),r=I(i);return{name:typeof r.name==="string"&&r.name?r.name:n,description:typeof r.description==="string"?r.description:v(i),version:typeof r.version==="string"||typeof r.version==="number"?String(r.version):"",path:`${n}/SKILL.md`}}function L(e,n){const t=u(e);if(n)return{name:t,pathInSkill:n};const i=t.indexOf("/");if(i===-1)return{name:t,pathInSkill:""};return{name:t.slice(0,i),pathInSkill:t.slice(i+1)}}function u(e){const n=e.trim().replace(/\\/g,"/");if(!n||n.includes("\x00"))throw new l("Skill path must be non-empty.");if(n.startsWith("/")||n.split("/").some((t)=>t===".."))throw new l(`Invalid skill path: ${e}`,"Use a path relative to an OpenCLI skill directory.");return o.posix.normalize(n)}function I(e){if(!e.startsWith(`---
+`))return{};const n=e.indexOf(`
+---`,4);if(n<0)return{};try{const t=h.load(e.slice(4,n));return t&&typeof t==="object"?t:{}}catch{return g(e.slice(4,n))}}function g(e){const n={};for(const t of e.split(`
+`)){const i=/^([A-Za-z][A-Za-z0-9_-]*)\s*:\s*(.*)$/.exec(t);if(!i)continue;const[,r,f]=i;if(!["name","description","version"].includes(r))continue;n[r]=f.trim().replace(/^['"]|['"]$/g,"")}return n}function v(e){return(e.startsWith(`---
+`)?e.slice(Math.max(e.indexOf(`
+---`,4)+4,0)):e).split(/\n\s*\n/).map((i)=>i.replace(/^#+\s*/gm,"").trim()).find(Boolean)??""}function w(e){try{return s.statSync(e).isDirectory()}catch{return!1}}

package/dist/src/skills.test.d.ts

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

package/dist/src/snapshotFormatter.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Aria snapshot formatter: parses snapshot text into clean format.
+ *
+ * 4-pass pipeline:
+ * 1. Parse & filter: strip annotations, metadata, noise, ads, boilerplate subtrees
+ * 2. Deduplicate: generic/text parent match, heading+link, nested identical links
+ * 3. Prune: empty containers (iterative bottom-up)
+ * 4. Collapse: single-child containers
+ */
+import type { SnapshotOptions } from './types.js';
+export declare function formatSnapshot(raw: string, opts?: SnapshotOptions): string;

package/dist/src/snapshotFormatter.js

@@ -0,0 +1,3 @@
+const D=200,S=new Set(["none","presentation","separator","paragraph","tooltip","status"]),m=new Set(["contentinfo"]),O=new Set(["button","link","textbox","checkbox","radio","combobox","tab","menuitem","option","switch","slider","spinbutton","searchbox"]),A=new Set(["main","navigation","banner","heading","search","region","list","listitem","article","complementary","group","toolbar","tablist"]),U=new Set(["list","listitem","group","toolbar","tablist","navigation","region","complementary","search","article","paragraph","figure"]),C=new Set(["•","·","|","—","-","/","\\"]),N=["googleadservices.com/pagead/","alb.reddit.com/cr?","doubleclick.net/","cm.bilibili.com/cm/api/fees/"],_=["回到顶部","back to top","scroll to top","go to top"];function R(W){let q=W;if(q.startsWith("'")&&q.endsWith("':"))q=q.slice(1,-2)+":";else if(q.startsWith("'")&&q.endsWith("'"))q=q.slice(1,-1);const $=q.match(/^([a-zA-Z]+)\b/),V=$?$[1].toLowerCase():"",H=q.match(/"([^"]*)"/),P=H?H[1]:"";let K=q;K=K.replace(/"[^"]*"/g,'""');K=K.replace(/\[[^\]]*\]/g,"");const b=K.lastIndexOf(":");let F="";if(b!==-1){if(K.slice(b+1).trim().length>0){const G=q.lastIndexOf(":");if(G!==-1)F=q.slice(G+1).trim()}}return{role:V,text:P,hasText:P.length>0||F.length>0,trailingText:F}}function g(W){let q=W;if(q.startsWith("'")&&(q.endsWith("':")||q.endsWith("'")))if(q.endsWith("':"))q=q.slice(1,-2)+":";else q=q.slice(1,-1);const $=q.split('"');for(let H=0;H<$.length;H+=2)$[H]=$[H].replace(/\s*\[[^\]]*\]/g,"");return $.join('"').replace(/\s{2,}/g," ").trim()}function j(W){return/^\/[a-zA-Z]+:/.test(W)}function I(W){return C.has(W.trim())}function L(W,q){const $=(W+" "+q).toLowerCase();if($.includes("sponsored")||$.includes("advertisement"))return!0;if($.includes("广告"))return!0;for(const V of N)if(W.includes(V)||q.includes(V))return!0;return!1}function E(W){const q=W.toLowerCase();return _.some(($)=>q.includes($))}function u(W,q,$,V){if(S.has(W))return!0;if(W==="generic"&&!q)return!0;if(W==="img"&&!q)return!0;if((W==="generic"||W==="text")&&q){if(I(V||$))return!0}return!1}export function formatSnapshot(W,q={}){if(!W||typeof W!=="string")return"";const $=q.maxTextLength??D,V=W.split(`
+`),H=[];let P=0,K=-1;for(let Y=0;Y<V.length;Y++){const z=V[Y];if(!z.trim())continue;const Q=z.length-z.trimStart().length,Z=Math.floor(Q/2);if(K>=0){if(Z>K)continue;K=-1}let J=z.trimStart();if(J.startsWith("- "))J=J.slice(2);if(j(J))continue;if(q.maxDepth!==void 0&&Z>q.maxDepth)continue;const{role:v,text:f,hasText:k,trailingText:B}=R(J);if(u(v,k,f,B))continue;if(m.has(v)){K=Z;continue}if(L(f,B)||E(f)){K=Z;continue}J=g(J);const w=O.has(v),M=A.has(v);if(q.interactive&&!w&&!M&&!k)continue;if(q.compact)J=J.replace(/\s*\[.*?\]\s*/g," ").replace(/\s+/g," ").trim();if($>0&&J.length>$)J=J.slice(0,$)+"…";if(w){P++;J=`[@${P}] ${J}`}H.push({depth:Z,content:J,role:v,text:f,trailingText:B,isInteractive:w,isLandmark:M})}const b=[];for(let Y=0;Y<H.length;Y++){const z=H[Y];if(z.role==="generic"||z.role==="text"){let Q;for(let Z=b.length-1;Z>=0;Z--){if(b[Z].depth<z.depth){Q=b[Z];break}if(b[Z].depth===z.depth)break}if(Q){const Z=z.trailingText||z.text;if(Z&&Q.text&&Z===Q.text)continue}}if(z.role==="heading"&&z.text){const Q=H[Y+1];if(Q&&Q.role==="link"&&Q.text===z.text&&Q.depth===z.depth+1){b.push(z);Y++;continue}}if(z.role==="link"&&z.text){const Q=H[Y+1];if(Q&&Q.role==="link"&&Q.text===z.text&&Q.depth===z.depth+1)continue}b.push(z)}let F=b,X=!0;while(X){X=!1;const Y=[];for(let z=0;z<F.length;z++){const Q=F[z];if(U.has(Q.role)&&!Q.text&&!Q.trailingText){let Z=!1;for(let J=z+1;J<F.length;J++){if(F[J].depth<=Q.depth)break;if(F[J].depth>Q.depth){Z=!0;break}}if(!Z){X=!0;continue}}Y.push(Q)}F=Y}const G=[];for(let Y=0;Y<F.length;Y++){const z=F[Y];if(U.has(z.role)&&!z.text&&!z.trailingText){let Q=0,Z=-1;for(let J=Y+1;J<F.length;J++){if(F[J].depth<=z.depth)break;if(F[J].depth===z.depth+1){Q++;if(Q===1)Z=J}}if(Q===1&&Z!==-1){const J=F[Z];let v=!1;for(let f=Z+1;f<F.length;f++){if(F[f].depth<=J.depth)break;if(F[f].depth>J.depth){v=!0;break}}if(!v){G.push({...z,content:z.content.replace(/:$/,"")+" > "+J.content,role:J.role,text:J.text,trailingText:J.trailingText,isInteractive:J.isInteractive});Y++;continue}}}G.push(z)}return G.map((Y)=>"  ".repeat(Y.depth)+Y.content).join(`
+`)}

package/dist/src/snapshotFormatter.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Tests for snapshotFormatter.ts: snapshot tree filtering.
+ *
+ * Uses sanitized excerpts from real websites (GitHub, Bilibili, Twitter)
+ * to validate noise filtering, annotation stripping, and output quality.
+ */
+export {};

package/dist/src/tui.d.ts

@@ -0,0 +1,28 @@
+export interface CheckboxItem {
+    label: string;
+    value: string;
+    checked: boolean;
+    /** Optional status to display after the label */
+    status?: string;
+}
+/**
+ * Interactive multi-select checkbox prompt.
+ *
+ * Controls:
+ *   ↑/↓ or j/k  — navigate
+ *   Space        — toggle selection
+ *   a            — toggle all
+ *   Enter        — confirm
+ *   q/Esc        — cancel (returns empty)
+ */
+export declare function checkboxPrompt(items: CheckboxItem[], opts?: {
+    title?: string;
+    hint?: string;
+}): Promise<string[]>;
+/**
+ * Simple yes/no confirmation prompt.
+ *
+ * In non-TTY environments, returns `defaultYes` (defaults to true) without blocking.
+ * In TTY, waits for a single keypress: y/Enter → true, n/Esc/q → false.
+ */
+export declare function confirmPrompt(message: string, defaultYes?: boolean): Promise<boolean>;

package/dist/src/tui.js

@@ -0,0 +1,16 @@
+import{EXIT_CODES as j}from"./errors.js";export async function checkboxPrompt(Q,P={}){if(Q.length===0)return[];const{stdin:B,stdout:J}=process;if(!B.isTTY)return Q.filter((z)=>z.checked).map((z)=>z.value);let G=0;const F=Q.map((z)=>({...z}));function U(){let z="";if(P.title)z+=`
+${P.title}
+
+`;for(let K=0;K<F.length;K++){const L=F[K],A=K===G?"❯":" ",V=L.checked?"◉":"○",W=L.status??"";z+=`  ${A} ${V} ${L.label}${W?`  ${W}`:""}
+`}z+=`
+  ↑↓ navigate  ·  Space toggle  ·  a all  ·  Enter confirm  ·  q cancel
+`;return z}return new Promise((z)=>{const K=B.isRaw;B.setRawMode(!0);B.resume();J.write("\x1B[?25l");let L=!0;function A(){if(!L){const Z=U().split(`
+`).length;J.write(`\x1B[${Z}A\x1B[J`)}L=!1;J.write(U())}function V(){B.setRawMode(K??!1);B.pause();B.removeListener("data",W);const Z=U().split(`
+`).length;J.write(`\x1B[${Z}A\x1B[J`);J.write("\x1B[?25h")}function W(Z){const H=Z.toString();if(H==="\x1B[A"||H==="k"){G=(G-1+F.length)%F.length;A();return}if(H==="\x1B[B"||H==="j"){G=(G+1)%F.length;A();return}if(H===" "){F[G].checked=!F[G].checked;A();return}if(H==="\t"){F[G].checked=!F[G].checked;G=(G+1)%F.length;A();return}if(H==="a"){const $=F.every((M)=>M.checked);for(const M of F)M.checked=!$;A();return}if(H==="\r"||H===`
+`){V();const $=F.filter((M)=>M.checked).map((M)=>M.value);J.write(`  ✓ ${$.length} file(s) selected
+
+`);z($);return}if(H==="q"||H==="\x1B"){V();J.write(`  ✗ Cancelled
+
+`);z([]);return}if(H==="\x03"){V();process.exit(j.INTERRUPTED)}}B.on("data",W);A()})}export async function confirmPrompt(Q,P=!0){const{stdin:B,stdout:J}=process;if(!B.isTTY)return P;const G=P?"[Y/n]":"[y/N]";J.write(`  ${Q} ${G} `);return new Promise((F)=>{const U=B.isRaw;B.setRawMode(!0);B.resume();function z(){B.setRawMode(U??!1);B.pause();B.removeListener("data",K);J.write(`
+`)}function K(L){const A=L.toString();if(A==="\x03"){z();process.exit(j.INTERRUPTED)}if(A==="\r"||A===`
+`){z();F(P);return}if(A==="y"||A==="Y"){z();F(!0);return}if(A==="n"||A==="N"||A==="q"||A==="\x1B"){z();F(!1);return}}B.on("data",K)})}

package/dist/src/tui.test.d.ts

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

package/dist/src/types.d.ts

@@ -0,0 +1,236 @@
+/**
+ * Page interface: type-safe abstraction over browser page.
+ *
+ * All pipeline steps and CLI adapters should use this interface
+ * instead of `any` for browser interactions.
+ */
+export interface BrowserCookie {
+    name: string;
+    value: string;
+    domain: string;
+    path?: string;
+    secure?: boolean;
+    httpOnly?: boolean;
+    expirationDate?: number;
+}
+export interface SnapshotOptions {
+    interactive?: boolean;
+    compact?: boolean;
+    maxDepth?: number;
+    raw?: boolean;
+    viewportExpand?: number;
+    maxTextLength?: number;
+    /** Observation backend. `dom` is the stable default; `ax` is an opt-in prototype. */
+    source?: 'dom' | 'ax';
+}
+export interface WaitOptions {
+    text?: string;
+    selector?: string;
+    time?: number;
+    timeout?: number;
+}
+export interface BrowserDownloadWaitResult {
+    downloaded: boolean;
+    id?: number;
+    filename?: string;
+    url?: string;
+    finalUrl?: string;
+    mime?: string;
+    totalBytes?: number;
+    state?: string;
+    danger?: string;
+    error?: string;
+    elapsedMs: number;
+}
+export interface ScreenshotOptions {
+    format?: 'png' | 'jpeg';
+    quality?: number;
+    fullPage?: boolean;
+    /** Overlay current browser-state refs on visible interactive elements. */
+    annotate?: boolean;
+    /** Override viewport width in CSS pixels for the screenshot only (cleared after). */
+    width?: number;
+    /** Override viewport height in CSS pixels for the screenshot only (ignored when fullPage). */
+    height?: number;
+    path?: string;
+}
+export interface FetchJsonOptions {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+    timeoutMs?: number;
+}
+export type BrowserEvaluateFunction<Args extends unknown[] = unknown[], Result = unknown> = (...args: Args) => Result | Promise<Result>;
+export interface IPage {
+    goto(url: string, options?: {
+        waitUntil?: 'load' | 'none';
+        settleMs?: number;
+    }): Promise<void>;
+    evaluate<T = any>(js: string): Promise<T>;
+    evaluate<Args extends unknown[], T>(fn: BrowserEvaluateFunction<Args, T>, ...args: Args): Promise<Awaited<T>>;
+    /** Safely evaluate JS with pre-serialized arguments — prevents injection. */
+    evaluateWithArgs?(js: string, args: Record<string, unknown>): Promise<any>;
+    /**
+     * Fetch JSON from inside the browser context, carrying the page's cookies.
+     * This is intentionally narrow: browser-context JSON fetch, not a generic
+     * HTTP client.
+     */
+    fetchJson(url: string, opts?: FetchJsonOptions): Promise<unknown>;
+    getCookies(opts?: {
+        domain?: string;
+        url?: string;
+    }): Promise<BrowserCookie[]>;
+    snapshot(opts?: SnapshotOptions): Promise<any>;
+    click(ref: string, opts?: {
+        nth?: number;
+        firstOnMulti?: boolean;
+    }): Promise<{
+        matches_n: number;
+        match_level: 'exact' | 'stable' | 'reidentified';
+    }>;
+    dblClick?(ref: string, opts?: {
+        nth?: number;
+        firstOnMulti?: boolean;
+    }): Promise<{
+        matches_n: number;
+        match_level: 'exact' | 'stable' | 'reidentified';
+    }>;
+    hover?(ref: string, opts?: {
+        nth?: number;
+        firstOnMulti?: boolean;
+    }): Promise<{
+        matches_n: number;
+        match_level: 'exact' | 'stable' | 'reidentified';
+    }>;
+    focus?(ref: string, opts?: {
+        nth?: number;
+        firstOnMulti?: boolean;
+    }): Promise<{
+        focused: boolean;
+        matches_n: number;
+        match_level: 'exact' | 'stable' | 'reidentified';
+    }>;
+    setChecked?(ref: string, checked: boolean, opts?: {
+        nth?: number;
+        firstOnMulti?: boolean;
+    }): Promise<{
+        checked: boolean;
+        changed: boolean;
+        matches_n: number;
+        match_level: 'exact' | 'stable' | 'reidentified';
+        kind?: string;
+    }>;
+    uploadFiles?(ref: string, files: string[], opts?: {
+        nth?: number;
+        firstOnMulti?: boolean;
+    }): Promise<{
+        uploaded: boolean;
+        files: number;
+        file_names: string[];
+        target: string;
+        matches_n: number;
+        match_level: 'exact' | 'stable' | 'reidentified';
+        multiple?: boolean;
+        accept?: string;
+    }>;
+    drag?(source: string, target: string, opts?: {
+        from?: {
+            nth?: number;
+            firstOnMulti?: boolean;
+        };
+        to?: {
+            nth?: number;
+            firstOnMulti?: boolean;
+        };
+    }): Promise<{
+        dragged: boolean;
+        source: string;
+        target: string;
+        source_matches_n: number;
+        target_matches_n: number;
+        source_match_level: 'exact' | 'stable' | 'reidentified';
+        target_match_level: 'exact' | 'stable' | 'reidentified';
+    }>;
+    typeText(ref: string, text: string, opts?: {
+        nth?: number;
+        firstOnMulti?: boolean;
+    }): Promise<{
+        matches_n: number;
+        match_level: 'exact' | 'stable' | 'reidentified';
+    }>;
+    fillText(ref: string, text: string, opts?: {
+        nth?: number;
+        firstOnMulti?: boolean;
+    }): Promise<{
+        filled: boolean;
+        verified: boolean;
+        expected: string;
+        actual: string;
+        length: number;
+        matches_n: number;
+        match_level: 'exact' | 'stable' | 'reidentified';
+        mode?: 'input' | 'textarea' | 'contenteditable';
+    }>;
+    pressKey(key: string): Promise<void>;
+    scrollTo(ref: string, opts?: {
+        nth?: number;
+        firstOnMulti?: boolean;
+    }): Promise<any>;
+    getFormState(): Promise<any>;
+    wait(options: number | WaitOptions): Promise<void>;
+    waitForDownload?(pattern?: string, timeoutMs?: number): Promise<BrowserDownloadWaitResult>;
+    tabs(): Promise<any>;
+    closeTab?(target?: number | string): Promise<void>;
+    newTab?(url?: string): Promise<string | undefined>;
+    selectTab(target: number | string): Promise<void>;
+    networkRequests(includeStatic?: boolean): Promise<any>;
+    consoleMessages(level?: string): Promise<any>;
+    scroll(direction?: string, amount?: number): Promise<void>;
+    autoScroll(options?: {
+        times?: number;
+        delayMs?: number;
+    }): Promise<void>;
+    installInterceptor(pattern: string): Promise<void>;
+    getInterceptedRequests(): Promise<any[]>;
+    waitForCapture(timeout?: number): Promise<void>;
+    screenshot(options?: ScreenshotOptions): Promise<string>;
+    annotatedScreenshot?(options?: ScreenshotOptions): Promise<string>;
+    startNetworkCapture?(pattern?: string): Promise<boolean>;
+    readNetworkCapture?(): Promise<unknown[]>;
+    /**
+     * Set local file paths on a file input element via CDP DOM.setFileInputFiles.
+     * Chrome reads the files directly — no base64 encoding or payload size limits.
+     */
+    setFileInput?(files: string[], selector?: string): Promise<void>;
+    /**
+     * Insert text via native CDP Input.insertText into the currently focused element.
+     * Useful for rich editors that ignore synthetic DOM value/text mutations.
+     */
+    insertText?(text: string): Promise<void>;
+    closeWindow?(): Promise<void>;
+    /** Returns the current page URL, or null if unavailable. */
+    getCurrentUrl?(): Promise<string | null>;
+    /** Returns the active page identity (targetId), or undefined if not yet resolved. */
+    getActivePage?(): string | undefined;
+    /** Bind the page object to a specific page identity (targetId). */
+    setActivePage?(page?: string): void;
+    /** Send a raw CDP command via chrome.debugger passthrough. */
+    cdp?(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    /** Accept or dismiss the currently open JavaScript alert/confirm/prompt dialog. */
+    handleJavaScriptDialog?(accept: boolean, promptText?: string): Promise<void>;
+    /** List cross-origin iframe targets in snapshot order. */
+    frames?(): Promise<Array<{
+        index: number;
+        frameId: string;
+        url: string;
+        name: string;
+    }>>;
+    /** Evaluate JavaScript inside a cross-origin iframe identified by its frame index. */
+    evaluateInFrame?(js: string, frameIndex: number): Promise<unknown>;
+    /** Click at native coordinates via CDP Input.dispatchMouseEvent. */
+    nativeClick?(x: number, y: number): Promise<void>;
+    /** Type text via CDP Input.insertText. */
+    nativeType?(text: string): Promise<void>;
+    /** Press a key via CDP Input.dispatchKeyEvent. */
+    nativeKeyPress?(key: string, modifiers?: string[]): Promise<void>;
+}

package/dist/src/types.js

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

package/dist/src/utils.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Shared utility functions used across the codebase.
+ */
+import TurndownService from 'turndown';
+/** Type guard: checks if a value is a non-null, non-array object. */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** Simple async concurrency limiter. */
+export declare function mapConcurrent<T, R>(items: T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
+/** Pause for the given number of milliseconds. */
+export declare function sleep(ms: number): Promise<void>;
+/** Save a base64-encoded string to a file, creating parent directories as needed. */
+export declare function saveBase64ToFile(base64: string, filePath: string): Promise<void>;
+export declare function createMarkdownConverter(configure?: (td: TurndownService) => void): TurndownService;
+export declare function htmlToMarkdown(value: string, configure?: (td: TurndownService) => void): string;
+/** Sentinel shape that browser-side `fetch` wrappers return when they detect an
+ * HTML response in place of JSON. Kept as a plain object so it survives the
+ * `page.evaluate` JSON round-trip. */
+export interface LoginWallSignal {
+    __loginWall: true;
+    status: number;
+    url: string;
+    contentType: string;
+    bodyPreview: string;
+}
+/** Throw a `LoginWallError` if `value` is the sentinel returned by the
+ * browser-side sniffer; otherwise return `value` unchanged. Adapters that
+ * fetch from inside `page.evaluate` call this on the result before consuming
+ * it, so the Node-side gets a typed error instead of a JSON-parse stack
+ * trace. */
+export declare function throwIfLoginWall<T>(value: T, opts?: {
+    url?: string;
+}): T;
+/** Parse a `Response` body as JSON, throwing `LoginWallError` if the server
+ * returned an HTML page (login wall / rate limit / WAF interception) instead
+ * of the expected JSON. Catches the common case of `<!DOCTYPE` or `<html`
+ * leading the body \u2014 naive `JSON.parse` on these gives a cryptic
+ * `SyntaxError` that callers can't distinguish from "real" malformed JSON.
+ *
+ * On real (non-HTML) JSON-parse failures, throws a regular `Error` with a
+ * body preview attached so debugging doesn't require a packet capture. */
+export declare function parseJsonOrThrowLoginWall(response: Response, opts?: {
+    url?: string;
+}): Promise<unknown>;
+/** Browser-side JS source fragment (as a string) that performs a `fetch` and
+ * either returns the parsed JSON body or a `LoginWallSignal` sentinel when
+ * the response is HTML. Intended to be embedded inside an adapter's
+ * `page.evaluate` block.
+ *
+ * Usage from inside a `page.evaluate` IIFE:
+ *
+ *     ${BROWSER_JSON_SNIFF_FN}
+ *     const res = await fetchJsonOrLoginWall('/some/path.json', { credentials: 'include' });
+ *     // res is the parsed JSON object, OR { __loginWall: true, status, url, contentType, bodyPreview }
+ *     return res;
+ *
+ * The Node side then calls `throwIfLoginWall(res, { url })` on the result. */
+export declare const BROWSER_JSON_SNIFF_FN = "\nasync function fetchJsonOrLoginWall(input, init) {\n  const r = await fetch(input, init);\n  const contentType = r.headers.get('content-type') || '';\n  const text = await r.text();\n  const trimmed = text.replace(/^\\s+/, '');\n  const looksLikeHtml =\n    contentType.toLowerCase().includes('text/html')\n    || trimmed.startsWith('<!DOCTYPE')\n    || trimmed.startsWith('<!doctype')\n    || trimmed.startsWith('<html')\n    || trimmed.startsWith('<HTML');\n  if (looksLikeHtml) {\n    return {\n      __loginWall: true,\n      status: r.status,\n      url: r.url || (typeof input === 'string' ? input : ''),\n      contentType,\n      bodyPreview: trimmed.slice(0, 100),\n    };\n  }\n  if (!r.ok) {\n    return { error: r.status };\n  }\n  try {\n    return JSON.parse(text);\n  } catch (err) {\n    throw new Error(\n      'JSON parse failed (status=' + r.status + ', body[0..50]=' + JSON.stringify(trimmed.slice(0, 50)) + '): '\n      + (err && err.message ? err.message : String(err))\n    );\n  }\n}\n";

package/dist/src/utils.js

@@ -0,0 +1,38 @@
+import*as X from"node:fs";import*as Z from"node:path";import C from"turndown";import{LoginWallError as Y}from"./errors.js";export function isRecord(q){return typeof q==="object"&&q!==null&&!Array.isArray(q)}export async function mapConcurrent(q,z,D){const G=Array(q.length);let A=0;async function V(){while(A<q.length){const Q=A++;G[Q]=await D(q[Q],Q)}}const K=Array.from({length:Math.min(z,q.length)},()=>V());await Promise.all(K);return G}export function sleep(q){return new Promise((z)=>setTimeout(z,q))}export async function saveBase64ToFile(q,z){const D=Z.dirname(z);await X.promises.mkdir(D,{recursive:!0});await X.promises.writeFile(z,Buffer.from(q,"base64"))}export function createMarkdownConverter(q){const z=new C({headingStyle:"atx",codeBlockStyle:"fenced",bulletListMarker:"-"});z.addRule("linebreak",{filter:"br",replacement:()=>`
+`});if(q)q(z);return z}export function htmlToMarkdown(q,z){return createMarkdownConverter(z).turndown(q||"").replace(/\u00a0/g," ").replace(/\n{4,}/g,`
+
+
+`).replace(/[ \t]+$/gm,"").trim()}function H(q){return typeof q==="object"&&q!==null&&q.__loginWall===!0&&typeof q.status==="number"}export function throwIfLoginWall(q,z={}){if(H(q))throw new Y(`Server returned HTML instead of JSON (status=${q.status}). Likely a login wall, rate limit, or WAF challenge.`,q.status,z.url||q.url||"",q.bodyPreview);return q}export async function parseJsonOrThrowLoginWall(q,z={}){const D=q.headers.get("content-type")||"",G=await q.text(),A=G.trimStart();if(D.toLowerCase().includes("text/html")||A.startsWith("<!DOCTYPE")||A.startsWith("<!doctype")||A.startsWith("<html")||A.startsWith("<HTML"))throw new Y(`Server returned HTML instead of JSON (status=${q.status}). Likely a login wall, rate limit, or WAF challenge.`,q.status,z.url||q.url||"",A.slice(0,100));try{return JSON.parse(G)}catch(K){throw Error(`JSON parse failed (status=${q.status}, body[0..50]=${JSON.stringify(A.slice(0,50))}): `+(K instanceof Error?K.message:String(K)))}}export const BROWSER_JSON_SNIFF_FN=`
+async function fetchJsonOrLoginWall(input, init) {
+  const r = await fetch(input, init);
+  const contentType = r.headers.get('content-type') || '';
+  const text = await r.text();
+  const trimmed = text.replace(/^\\s+/, '');
+  const looksLikeHtml =
+    contentType.toLowerCase().includes('text/html')
+    || trimmed.startsWith('<!DOCTYPE')
+    || trimmed.startsWith('<!doctype')
+    || trimmed.startsWith('<html')
+    || trimmed.startsWith('<HTML');
+  if (looksLikeHtml) {
+    return {
+      __loginWall: true,
+      status: r.status,
+      url: r.url || (typeof input === 'string' ? input : ''),
+      contentType,
+      bodyPreview: trimmed.slice(0, 100),
+    };
+  }
+  if (!r.ok) {
+    return { error: r.status };
+  }
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    throw new Error(
+      'JSON parse failed (status=' + r.status + ', body[0..50]=' + JSON.stringify(trimmed.slice(0, 50)) + '): '
+      + (err && err.message ? err.message : String(err))
+    );
+  }
+}
+`;

package/dist/src/utils.test.d.ts

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

package/dist/src/validate.d.ts

@@ -0,0 +1,21 @@
+export interface CommandValidationResult {
+    /** Display label: "site/name" or source path if available */
+    label: string;
+    errors: string[];
+    warnings: string[];
+}
+export interface ValidationReport {
+    ok: boolean;
+    results: CommandValidationResult[];
+    errors: number;
+    warnings: number;
+    commands: number;
+}
+/**
+ * Validate registered CLI commands from the in-memory registry.
+ *
+ * The `_dirs` parameter is kept for call-site compatibility but is no longer
+ * used — validation now operates on the registry populated by `discoverClis()`.
+ */
+export declare function validateClisWithTarget(_dirs: string[], target?: string): ValidationReport;
+export declare function renderValidationReport(report: ValidationReport): string;

package/dist/src/validate.js

@@ -0,0 +1,3 @@
+import{getRegistry as O,fullName as M}from"./registry.js";import{getRegisteredStepNames as Q}from"./pipeline/registry.js";function U(){return new Set(Q())}export function validateClisWithTarget(q,F){const x=O(),B=[];let I=0,H=0;if(x.size===0)return{ok:!0,results:[{label:"(registry)",errors:[],warnings:["Registry is empty — no commands discovered. Did discoverClis() run?"]}],errors:0,warnings:1,commands:0};let D=F;if(F?.includes("/")){const G=x.get(F);if(G)D=M(G)}const E=new Set;for(const[G,J]of x){if(E.has(J))continue;if(G!==M(J))continue;E.add(J);if(D){if(D.includes("/")){if(G!==D)continue}else if(J.site!==D)continue}const L=V(J);B.push(L);I+=L.errors.length;H+=L.warnings.length}return{ok:I===0,results:B,errors:I,warnings:H,commands:B.length}}function V(q){const F=M(q),x=[],B=[];if(!q.description)B.push("Missing description");if(q.browser&&!q.domain)B.push('Browser command without "domain" — authenticated browser context may not work');if(Array.isArray(q.pipeline)){const H=U();for(let D=0;D<q.pipeline.length;D++){const E=q.pipeline[D];if(E&&typeof E==="object"){for(const G of Object.keys(E))if(!H.has(G))B.push(`Pipeline step ${D}: unknown step name "${G}" (did you mean one of: ${[...H].join(", ")}?)`)}}}const I=q;if(!q.func&&!q.pipeline&&!I._lazy)x.push('Command has neither "func" nor "pipeline" — it cannot execute');if(q.args&&q.args.length>0){const H=new Set;let D=!1;for(const E of q.args){if(H.has(E.name))x.push(`Duplicate arg name "${E.name}"`);H.add(E.name);if(E.positional&&D)B.push(`Positional arg "${E.name}" appears after named args`);if(!E.positional)D=!0}}return{label:F,errors:x,warnings:B}}export function renderValidationReport(q){const F=[`opencli validate: ${q.ok?"PASS":"FAIL"}`,`Checked ${q.commands} command(s)`,`Errors: ${q.errors}  Warnings: ${q.warnings}`];for(const x of q.results)if(x.errors.length>0||x.warnings.length>0){F.push(`
+${x.label}:`);for(const B of x.errors)F.push(`  ❌ ${B}`);for(const B of x.warnings)F.push(`  ⚠️  ${B}`)}return F.join(`
+`)}

package/dist/src/validate.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Tests for src/validate.ts.
+ *
+ * Focus: regression guards for the "single source of truth" link between
+ * pipeline step registry (src/pipeline/registry.ts) and validate.ts step
+ * allowlist. A new step registered via `registerStep()` must automatically
+ * be allowlisted by `opencli validate` — no parallel hand-maintained list.
+ */
+export {};

package/dist/src/verify.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Verification: runs validation and an optional smoke test.
+ *
+ * The smoke test runs `vitest run tests/smoke/` from the package root when that
+ * directory is present (repo/dev/CI checkouts). It reports "unavailable" when the
+ * directory is absent — notably in published npm installs, since `tests/` is not
+ * listed in package.json "files".
+ */
+import { type ValidationReport } from './validate.js';
+export interface VerifyOptions {
+    builtinClis: string;
+    userClis: string;
+    target?: string;
+    smoke?: boolean;
+}
+export interface VerifyReport {
+    ok: boolean;
+    validation: ValidationReport;
+    smoke: null | {
+        requested: boolean;
+        executed: boolean;
+        ok: boolean;
+        summary: string;
+    };
+}
+export declare function verifyClis(opts: VerifyOptions): Promise<VerifyReport>;
+export declare function renderVerifyReport(report: VerifyReport): string;

package/dist/src/verify.js

@@ -0,0 +1,2 @@
+import{validateClisWithTarget as I,renderValidationReport as J}from"./validate.js";import{spawn as K}from"node:child_process";import*as L from"node:fs";import*as H from"node:path";export async function verifyClis(q){const y=I([q.builtinClis,q.userClis],q.target);let z=null;if(q.smoke)z=await M(q.builtinClis);return{ok:y.ok&&(z?.ok??!0),validation:y,smoke:z}}export function renderVerifyReport(q){const y=J(q.validation);if(!q.smoke)return y;const z=q.smoke.ok?"PASS":"FAIL",B=q.smoke.executed?"executed":"skipped";return`${y}
+Smoke: ${z} (${B}) — ${q.smoke.summary}`}async function M(q){const y=H.resolve(q,".."),z=H.join(y,"tests","smoke");if(!L.existsSync(z))return{requested:!0,executed:!1,ok:!1,summary:"Smoke tests are unavailable in this package/environment."};const B=process.platform==="win32"?"npx.cmd":"npx";return new Promise((F)=>{const E=K(B,["vitest","run","tests/smoke/","--reporter=dot"],{cwd:y,env:{...process.env},stdio:["ignore","pipe","pipe"]});let G="";E.stderr.on("data",(A)=>{G+=A.toString()});E.on("error",(A)=>{F({requested:!0,executed:!1,ok:!1,summary:`Failed to start smoke tests: ${A.message}`})});E.on("close",(A)=>{F({requested:!0,executed:!0,ok:A===0,summary:A===0?"tests/smoke passed":G.trim()||`vitest exited with code ${A}`})})})}

package/dist/src/verify.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Tests for src/verify.ts.
+ *
+ * Focus: smoke-test directory resolution. `builtinClis` is `<packageRoot>/clis`
+ * (see src/main.ts), so the package root — and thus `<packageRoot>/tests/smoke` —
+ * must be reached by going a SINGLE level up from `builtinClis`, not two.
+ */
+export {};

package/dist/src/version.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Single source of truth for package version.
+ */
+export declare const PKG_VERSION: string;

package/dist/src/version.js

@@ -0,0 +1 @@
+import*as q from"node:fs";import*as b from"node:path";import{fileURLToPath as x}from"node:url";const y=b.dirname(x(import.meta.url));let j=b.resolve(y,"..");if(!q.existsSync(b.join(j,"package.json")))j=b.resolve(j,"..");const z=b.join(j,"package.json");export const PKG_VERSION=(()=>{try{return JSON.parse(q.readFileSync(z,"utf-8")).version}catch{return"0.0.0"}})();

package/dist/src/weixin-download.test.d.ts

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