publishport-opencli 1.0.0

package/dist/src/completion-shared.js

@@ -0,0 +1,30 @@
+export const BUILTIN_COMMANDS=["list","validate","verify","auth","browser","tab","doctor","plugin","external","completion"];export function bashCompletionScript(){return`# Bash completion for opencli
+# Add to ~/.bashrc:  eval "$(opencli completion bash)"
+_opencli_completions() {
+  local cur words cword
+  _get_comp_words_by_ref -n : cur words cword
+
+  local completions
+  completions=$(opencli --get-completions --cursor "$cword" "\${words[@]:1}" 2>/dev/null)
+
+  COMPREPLY=( $(compgen -W "$completions" -- "$cur") )
+  __ltrim_colon_completions "$cur"
+}
+complete -F _opencli_completions opencli
+`}export function zshCompletionScript(){return`# Zsh completion for opencli
+# Add to ~/.zshrc:  eval "$(opencli completion zsh)"
+_opencli() {
+  local -a completions
+  local cword=$((CURRENT - 1))
+  completions=(\${(f)"$(opencli --get-completions --cursor "$cword" "\${words[@]:1}" 2>/dev/null)"})
+  compadd -a completions
+}
+compdef _opencli opencli
+`}export function fishCompletionScript(){return`# Fish completion for opencli
+# Add to ~/.config/fish/config.fish:  opencli completion fish | source
+complete -c opencli -f -a '(
+  set -l tokens (commandline -cop)
+  set -l cursor (count (commandline -cop))
+  opencli --get-completions --cursor $cursor $tokens[2..] 2>/dev/null
+)'
+`}

package/dist/src/completion.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shell tab-completion support for opencli.
+ *
+ * Provides:
+ *  - Shell script generators for bash, zsh, and fish
+ *  - Dynamic completion logic that returns candidates for the current cursor position
+ */
+import { bashCompletionScript, zshCompletionScript, fishCompletionScript } from './completion-shared.js';
+export { bashCompletionScript, zshCompletionScript, fishCompletionScript };
+/**
+ * Return completion candidates given the current command-line words and cursor index.
+ * Requires full CLI discovery to have been run (uses getRegistry()).
+ *
+ * @param words  - The argv after 'opencli' (words[0] is the first arg, e.g. site name)
+ * @param cursor - 1-based position of the word being completed (1 = first arg)
+ */
+export declare function getCompletions(words: string[], cursor: number): string[];
+/**
+ * Print the completion script for the requested shell.
+ */
+export declare function printCompletionScript(shell: string): void;

package/dist/src/completion.js

@@ -0,0 +1 @@
+import{getRegistry as H}from"./registry.js";import{CliError as K}from"./errors.js";import{BUILTIN_COMMANDS as J,bashCompletionScript,zshCompletionScript,fishCompletionScript}from"./completion-shared.js";export{bashCompletionScript,zshCompletionScript,fishCompletionScript};export function getCompletions(x,F){if(F<=1){const k=new Set;for(const[,v]of H())k.add(v.site);return[...J,...k].sort()}const G=x[0];if(J.includes(G))return[];if(F===2){const k=[];for(const[,v]of H())if(v.site===G){k.push(v.name);if(v.aliases?.length)k.push(...v.aliases)}return[...new Set(k)].sort()}return[]}export function printCompletionScript(x){switch(x){case"bash":process.stdout.write(bashCompletionScript());break;case"zsh":process.stdout.write(zshCompletionScript());break;case"fish":process.stdout.write(fishCompletionScript());break;default:throw new K("UNSUPPORTED_SHELL",`Unsupported shell: ${x}. Supported: bash, zsh, fish`)}}

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

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

package/dist/src/constants.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Shared constants used across explore, synthesize, and pipeline modules.
+ */
+/** Default daemon port for HTTP/WebSocket communication with browser extension */
+export declare const DEFAULT_DAEMON_PORT = 19825;
+/**
+ * PublishPort 自有插件的专用端口。daemon 同时监听两个端口：19826 供 PublishPort 官方
+ * 插件优先连接，19825 作为回退端口（同一 /ext 升级）。daemon 只接受官方插件（hello 带
+ * brand:'publishport'），非官方 / 旧 opencli 插件即使连上任一端口也会在握手时被拒。
+ */
+export declare const PUBLISHPORT_DAEMON_PORT = 19826;
+export declare function unsupportedDaemonPortEnvMessage(value?: string): string;
+/** URL query params that are volatile/ephemeral and should be stripped from patterns */
+export declare const VOLATILE_PARAMS: Set<string>;
+/** Search-related query parameter names */
+export declare const SEARCH_PARAMS: Set<string>;
+/** Pagination-related query parameter names */
+export declare const PAGINATION_PARAMS: Set<string>;
+/** Limit/page-size query parameter names */
+export declare const LIMIT_PARAMS: Set<string>;
+/** Field role → common API field names mapping */
+export declare const FIELD_ROLES: Record<string, string[]>;

package/dist/src/constants.js

@@ -0,0 +1 @@
+export const DEFAULT_DAEMON_PORT=19825,PUBLISHPORT_DAEMON_PORT=19826;export function unsupportedDaemonPortEnvMessage(b){return`OPENCLI_DAEMON_PORT is no longer supported${b?` (received ${b})`:""}. The OpenCLI Chrome extension can only connect to localhost:${DEFAULT_DAEMON_PORT}. Unset OPENCLI_DAEMON_PORT and rerun opencli.`}export const VOLATILE_PARAMS=new Set(["w_rid","wts","_","callback","timestamp","t","nonce","sign"]),SEARCH_PARAMS=new Set(["q","query","keyword","search","wd","kw","search_query","w"]),PAGINATION_PARAMS=new Set(["page","pn","offset","cursor","next","page_num"]),LIMIT_PARAMS=new Set(["limit","count","size","per_page","page_size","ps","num"]),FIELD_ROLES={title:["title","name","text","content","desc","description","headline","subject"],url:["url","uri","link","href","permalink","jump_url","web_url","share_url"],author:["author","username","user_name","nickname","nick","owner","creator","up_name","uname"],score:["score","hot","heat","likes","like_count","view_count","views","play","favorite_count","reply_count"],time:["time","created_at","publish_time","pub_time","date","ctime","mtime","pubdate","created"],id:["id","aid","bvid","mid","uid","oid","note_id","item_id"],cover:["cover","pic","image","thumbnail","poster","avatar"],category:["category","tag","type","tname","channel","section"]};

package/dist/src/convention-audit.d.ts

@@ -0,0 +1,50 @@
+export type ConventionRuleId = 'silent-column-drop' | 'camelCase-in-columns' | 'missing-access-metadata' | 'silent-clamp' | 'silent-empty-fallback' | 'silent-sentinel' | 'write-without-delete-pair';
+type ManifestArg = {
+    name?: string;
+    positional?: boolean;
+    required?: boolean;
+    help?: string;
+};
+export type ManifestCommand = {
+    site?: string;
+    name?: string;
+    access?: string;
+    args?: ManifestArg[];
+    columns?: string[];
+    modulePath?: string;
+    sourceFile?: string;
+};
+export type ConventionViolation = {
+    rule: ConventionRuleId;
+    site: string;
+    name: string;
+    command: string;
+    message: string;
+    file?: string;
+    line?: number;
+    details?: Record<string, unknown>;
+};
+export type ConventionCategory = {
+    rule: ConventionRuleId;
+    count: number;
+    violations: ConventionViolation[];
+};
+export type ConventionAuditReport = {
+    ok: boolean;
+    summary: {
+        commands: number;
+        sites: number;
+        files_scanned: number;
+        violations: number;
+    };
+    categories: ConventionCategory[];
+};
+export type ConventionAuditOptions = {
+    projectRoot: string;
+    manifestPath?: string;
+    target?: string;
+    site?: string;
+};
+export declare function runConventionAudit(opts: ConventionAuditOptions): ConventionAuditReport;
+export declare function renderConventionAuditText(report: ConventionAuditReport): string;
+export {};

package/dist/src/convention-audit.js

@@ -0,0 +1,2 @@
+import*as D from"node:fs";import*as _ from"node:path";const S=["silent-column-drop","camelCase-in-columns","missing-access-metadata","silent-clamp","silent-empty-fallback","silent-sentinel","write-without-delete-pair"],C=new Set(["ok","error"]),E=[{match:/(^|[-_])like($|[-_])/,describe:"like",expected:(H)=>[H.replace(/like/g,"unlike"),"unlike"]},{match:/(^|[-_])follow($|[-_])/,describe:"follow",expected:(H)=>[H.replace(/follow/g,"unfollow"),"unfollow"]},{match:/(^|[-_])subscribe($|[-_])/,describe:"subscribe",expected:(H)=>[H.replace(/subscribe/g,"unsubscribe"),"unsubscribe"]},{match:/(^|[-_])bookmark($|[-_])/,describe:"bookmark",expected:(H)=>[H.replace(/bookmark/g,"unbookmark"),"unbookmark"]},{match:/(^|[-_])save($|[-_])/,describe:"save",expected:(H)=>[H.replace(/save/g,"unsave"),"unsave","delete","remove","rm"]},{match:/(^|[-_])create($|[-_])/,describe:"create",expected:(H)=>[H.replace(/create/g,"delete"),H.replace(/create/g,"remove"),"delete","remove","rm"]},{match:/(^|[-_])post($|[-_])/,describe:"post",expected:(H)=>[H.replace(/post/g,"delete"),"delete","remove","rm"]}];export function runConventionAudit(H){const J=H.manifestPath??_.join(H.projectRoot,"cli-manifest.json"),$=JSON.parse(D.readFileSync(J,"utf-8")).filter((Y)=>w(Y,H)),Z=[],G=new Map,X=new Set;for(const Y of $){const A=K(Y);if(!A)continue;if(Y.access!=="read"&&Y.access!=="write")Z.push({rule:"missing-access-metadata",...A,message:`${A.command} must declare access: 'read' | 'write'`});for(const M of Y.columns??[])if(/[a-z][A-Z]/.test(M))Z.push({rule:"camelCase-in-columns",...A,message:`${A.command} column "${M}" should use snake_case for agent-stable keys`,details:{column:M}});const W=T(H.projectRoot,Y);if(!W)continue;const U=O(W,G);if(U==null)continue;X.add(W);Z.push(...q(A,Y,U,W,H.projectRoot));Z.push(...I(A,U,W,H.projectRoot))}Z.push(...b($));const N=S.map((Y)=>{const A=Z.filter((W)=>W.rule===Y);return{rule:Y,count:A.length,violations:A}}),V=$.filter((Y)=>K(Y)!=null).length,z=new Set($.map((Y)=>Y.site).filter((Y)=>typeof Y==="string"));return{ok:Z.length===0,summary:{commands:V,sites:z.size,files_scanned:X.size,violations:Z.length},categories:N}}export function renderConventionAuditText(H){const J=[];J.push("Convention Audit Report");J.push(`Scanned ${H.summary.commands} command(s) across ${H.summary.sites} site(s), ${H.summary.files_scanned} source file(s).`);J.push(`Violations: ${H.summary.violations}`);J.push("");for(const Q of H.categories){const $=Q.count===0?"OK":String(Q.count);J.push(`${Q.rule}: ${$}`);for(const Z of Q.violations){const G=Z.file?` (${Z.file}${Z.line?`:${Z.line}`:""})`:"";J.push(`  - ${Z.command}${G}`);J.push(`    ${Z.message}`);const X=l(Z.details);if(X)J.push(`    ${X}`)}J.push("")}if(H.ok)J.push("OK - no convention violations found.");else J.push("Run with -f yaml or -f json for machine-readable output.");return J.join(`
+`)}function K(H){if(typeof H.site!=="string"||typeof H.name!=="string")return null;return{site:H.site,name:H.name,command:`${H.site}/${H.name}`}}function w(H,J){const Q=J.target?.trim(),$=J.site?.trim();if($&&H.site!==$)return!1;if(!Q)return!0;if(Q.includes("/"))return`${H.site}/${H.name}`===Q;return H.site===Q}function T(H,J){const Q=J.sourceFile??J.modulePath;if(!Q)return null;const $=_.join(H,"clis",Q);return D.existsSync($)?$:null}function O(H,J){if(J.has(H))return J.get(H)??null;try{const Q=D.readFileSync(H,"utf-8");J.set(H,Q);return Q}catch{J.set(H,null);return null}}function q(H,J,Q,$,Z){const G=new Set(J.columns??[]);if(G.size===0)return[];const X=y(Q,G),N=new Set,V=[];for(const z of j(Q)){if(v(z.text))continue;const Y=g(z.text).filter((M)=>!C.has(M));if(Y.length<2)continue;if(u(Y))continue;if(Y.filter((M)=>G.has(M)).length===0)continue;const W=Y.filter((M)=>!G.has(M)&&!X.has(M));if(W.length===0)continue;const U=W.sort().join(",");if(N.has(U))continue;N.add(U);V.push({rule:"silent-column-drop",...H,file:L(Z,$),line:p(Q,z.index),message:`${H.command} row emits key(s) not present in columns: ${W.join(", ")}`,details:{emitted_keys:Y,columns:[...G],missing:W}})}return V}function I(H,J,Q,$){const Z=[],G=L($,Q),X=J.split(/\r?\n/),N=k(J);let V=0;X.forEach((z,Y)=>{if(/Math\.min\s*\([^)]*limit[^)]*\)/i.test(z))Z.push({rule:"silent-clamp",...H,file:G,line:Y+1,message:"limit is clamped with Math.min; prefer validating and throwing ArgumentError on invalid input",details:{text:z.trim()}});const A=z.search(/\breturn\s+\[\s*\]\s*;?/);if(A>=0&&P(V+A,N))Z.push({rule:"silent-empty-fallback",...H,file:G,line:Y+1,message:"empty array fallback hides fetch/parse failures from agents; prefer a typed error when data is expected",details:{text:z.trim()}});const W=/(?:\?\?|\|\|)\s*(['"])(unknown|Unknown|UNKNOWN|N\/A|n\/a|NA|未知|-)\1/.exec(z);if(W){if(!R(z))Z.push({rule:"silent-sentinel",...H,file:G,line:Y+1,message:`sentinel fallback ${W[0].trim()} can turn missing data into fake data; prefer dropping the field or throwing a typed error`,details:{text:z.trim()}})}V+=z.length+1});return c(Z)}function R(H){return/\bthrow\s+new\b/.test(H)}function b(H){const J=new Map;for(const $ of H){if(!$.site||!$.name)continue;const Z=J.get($.site)??[];Z.push($);J.set($.site,Z)}const Q=[];for(const[$,Z]of J){const G=new Set(Z.map((X)=>X.name).filter((X)=>typeof X==="string"));for(const X of Z){if(X.access!=="write"||!X.name)continue;const N=E.find((z)=>z.match.test(X.name));if(!N)continue;const V=[...new Set(N.expected(X.name).filter((z)=>z!==X.name))];if(V.some((z)=>G.has(z)))continue;Q.push({rule:"write-without-delete-pair",site:$,name:X.name,command:`${$}/${X.name}`,message:`write command "${X.name}" looks like ${N.describe} but no matching undo/delete command exists on this site`,details:{expected_any_of:V}})}}return Q}function j(H){const J=[],Q=[/\.push\s*\(\s*{/g,/\breturn\s+(?:\(\s*)?{/g,/=>\s*\(\s*{/g,/\bmap\s*:\s*{/g];for(const $ of Q)for(const Z of H.matchAll($)){const X=Z[0].lastIndexOf("{");if(Z.index===void 0||X<0)continue;const N=Z.index+X,V=B(H,N);if(V)J.push({text:V,index:N})}return J}function k(H){const J=[];for(const Q of H.matchAll(/\bcatch\s*(?:\([^)]*\))?\s*{/g)){if(Q.index===void 0)continue;const $=Q.index+Q[0].lastIndexOf("{"),Z=f(H,$);if(Z>=0)J.push({start:$,end:Z})}return J}function f(H,J){let Q=0,$=null,Z=!1;for(let G=J;G<H.length;G++){const X=H[G];if($){if(Z)Z=!1;else if(X==="\\")Z=!0;else if(X===$)$=null;continue}if(X==='"'||X==="'"||X==="`"){$=X;continue}if(X==="{")Q++;if(X==="}"){Q--;if(Q===0)return G}}return-1}function P(H,J){return J.some((Q)=>H>=Q.start&&H<=Q.end)}function B(H,J){let Q=0,$=null,Z=!1;for(let G=J;G<H.length;G++){const X=H[G];if($){if(Z)Z=!1;else if(X==="\\")Z=!0;else if(X===$)$=null;continue}if(X==='"'||X==="'"||X==="`"){$=X;continue}if(X==="{")Q++;if(X==="}"){Q--;if(Q===0)return H.slice(J,G+1)}}return null}function g(H){return[...new Set(F(H).map((J)=>J.key))]}function F(H){const J=H.trim().replace(/^\{/,"").replace(/\}$/,""),Q=m(J,","),$=[];for(const Z of Q){const G=x(Z);if(G)$.push(G)}return $}function x(H){const J=H.trim();if(!J||J.startsWith("...")||J.startsWith("["))return null;const Q=d(J,":");if(Q>=0){const Z=J.slice(0,Q).trim(),G=J.slice(Q+1).trim();if(/^['"][^'"]+['"]$/.test(Z))return{key:Z.slice(1,-1),value:G};const X=/^([A-Za-z_$][\w$]*)$/.exec(Z);return X?{key:X[1],value:G}:null}const $=/^([A-Za-z_$][\w$]*)\b/.exec(J);return $?{key:$[1],value:$[1]}:null}function v(H){const J=F(H).find((Q)=>Q.key==="ok");return J!=null&&/^false\b/.test(J.value)}function y(H,J){const Q=new Set;for(const $ of h(H))for(const Z of F($.text)){if(!J.has(Z.key))continue;for(const G of Z.value.matchAll(/\b([A-Za-z_$][\w$]*(?:Raw|Class))\b/g)){const X=G[1];if(X!==Z.key)Q.add(X)}}return Q}function h(H){const J=[];for(const Q of H.matchAll(/=>\s*\(\s*{/g)){const Z=Q[0].lastIndexOf("{");if(Q.index===void 0||Z<0)continue;const G=Q.index+Z,X=B(H,G);if(X)J.push({text:X,index:G})}return J}function m(H,J){const Q=[];let $=0,Z=0,G=null,X=!1;for(let N=0;N<H.length;N++){const V=H[N];if(G){if(X)X=!1;else if(V==="\\")X=!0;else if(V===G)G=null;continue}if(V==='"'||V==="'"||V==="`"){G=V;continue}if(V==="{"||V==="["||V==="(")Z++;if(V==="}"||V==="]"||V===")")Z--;if(Z===0&&V===J){Q.push(H.slice($,N));$=N+1}}Q.push(H.slice($));return Q}function d(H,J){let Q=0,$=null,Z=!1;for(let G=0;G<H.length;G++){const X=H[G];if($){if(Z)Z=!1;else if(X==="\\")Z=!0;else if(X===$)$=null;continue}if(X==='"'||X==="'"||X==="`"){$=X;continue}if(X==="{"||X==="["||X==="(")Q++;if(X==="}"||X==="]"||X===")")Q--;if(Q===0&&X===J)return G}return-1}function u(H){const J=new Set(H);return J.has("site")&&(J.has("description")||J.has("access")||J.has("strategy"))}function p(H,J){return H.slice(0,J).split(/\r?\n/).length}function L(H,J){return _.relative(H,J).replaceAll(_.sep,"/")}function l(H){if(!H)return"";return Object.entries(H).map(([J,Q])=>`${J}: ${Array.isArray(Q)?Q.join(", "):String(Q)}`).join(" | ")}function c(H){const J=new Set;return H.filter((Q)=>{const $=`${Q.rule}:${Q.command}:${Q.file}:${Q.line}:${Q.message}`;if(J.has($))return!1;J.add($);return!0})}

package/dist/src/convention-audit.test.d.ts

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

package/dist/src/daemon-utils.d.ts

@@ -0,0 +1,18 @@
+export declare const COMMAND_RESULT_UNKNOWN_CODE = "command_result_unknown";
+export declare const COMMAND_RESULT_UNKNOWN_HINT = "Inspect the browser/session state before retrying. Do not blindly retry write commands such as navigate, click, type, or eval.";
+export declare const PROFILE_DISCONNECTED_HINT = "Open that Chrome profile and make sure the OpenCLI extension is enabled, or choose another profile with opencli profile use <name>.";
+export type DaemonFailureContract = {
+    message: string;
+    errorCode: string;
+    errorHint: string;
+    status: number;
+    countAsCommandResultUnknown: boolean;
+};
+export declare function commandResultUnknownMessage(action: string): string;
+export declare function buildExtensionDisconnectFailure(input: {
+    contextId: string;
+    action: string;
+    dispatched: boolean;
+}): DaemonFailureContract;
+export declare function buildCommandDispatchFailure(contextId: string): DaemonFailureContract;
+export declare function getResponseCorsHeaders(pathname: string, origin?: string): Record<string, string> | undefined;

package/dist/src/daemon-utils.js

@@ -0,0 +1 @@
+export const COMMAND_RESULT_UNKNOWN_CODE="command_result_unknown",COMMAND_RESULT_UNKNOWN_HINT="Inspect the browser/session state before retrying. Do not blindly retry write commands such as navigate, click, type, or eval.",PROFILE_DISCONNECTED_HINT="Open that Chrome profile and make sure the OpenCLI extension is enabled, or choose another profile with opencli profile use <name>.";export function commandResultUnknownMessage(e){return`Browser connection dropped after the ${e} command was dispatched; it may have completed.`}export function buildExtensionDisconnectFailure(e){if(e.dispatched)return{message:commandResultUnknownMessage(e.action),errorCode:COMMAND_RESULT_UNKNOWN_CODE,errorHint:COMMAND_RESULT_UNKNOWN_HINT,status:503,countAsCommandResultUnknown:!0};return buildCommandDispatchFailure(e.contextId)}export function buildCommandDispatchFailure(e){return{message:`Browser profile "${e}" disconnected before command dispatch`,errorCode:"profile_disconnected",errorHint:PROFILE_DISCONNECTED_HINT,status:503,countAsCommandResultUnknown:!1}}export function getResponseCorsHeaders(e,n){if(e!=="/ping")return;if(!n||!n.startsWith("chrome-extension://"))return;return{"Access-Control-Allow-Origin":n,Vary:"Origin"}}

package/dist/src/daemon.d.ts

@@ -0,0 +1,22 @@
+/**
+ * opencli micro-daemon — HTTP + WebSocket bridge between CLI and Chrome Extension.
+ *
+ * Architecture:
+ *   CLI → HTTP POST /command → daemon → WebSocket → Extension
+ *   Extension → WebSocket result → daemon → HTTP response → CLI
+ *
+ * Security (defense-in-depth against browser-based CSRF):
+ *   1. Origin check — reject HTTP/WS from non chrome-extension:// origins
+ *   2. Custom header — require X-OpenCLI header (browsers can't send it
+ *      without CORS preflight, which we deny)
+ *   3. No CORS headers on command endpoints — only /ping is readable from the
+ *      Browser Bridge extension origin so the extension can probe daemon reachability
+ *   4. Body size limit — 1 MB max to prevent OOM
+ *   5. WebSocket verifyClient — reject upgrade before connection is established
+ *
+ * Lifecycle:
+ *   - Auto-spawned by opencli on first browser command
+ *   - Persistent — stays alive until explicit shutdown, SIGTERM, or uninstall
+ *   - Listens on localhost:19825
+ */
+export {};

package/dist/src/daemon.js

@@ -0,0 +1 @@
+import{createServer as b}from"node:http";import{WebSocketServer as u,WebSocket as v}from"ws";import{DEFAULT_DAEMON_PORT as p,PUBLISHPORT_DAEMON_PORT as g,unsupportedDaemonPortEnvMessage as c}from"./constants.js";import{EXIT_CODES as S}from"./errors.js";import{log as G}from"./logger.js";import{PKG_VERSION as l}from"./version.js";import{DEFAULT_CONTEXT_ID as d}from"./browser/profile.js";import{buildCommandDispatchFailure as a,buildExtensionDisconnectFailure as i,getResponseCorsHeaders as t}from"./daemon-utils.js";import*as L from"./browser/trace.js";const B=p,h=g;if(process.env.OPENCLI_DAEMON_PORT){G.error(c(process.env.OPENCLI_DAEMON_PORT));process.exit(S.USAGE_ERROR)}const W=new Map,N=new Map;let I=0;const n=200,k=[];class E extends Error{errorCode;errorHint;status;constructor(J,K,Z,z=400){super(J);this.errorCode=K;this.errorHint=Z;this.status=z;this.name="DaemonCommandFailure"}}function s(J){k.push(J);if(k.length>n)k.shift()}function j(){return[...W.values()].filter((J)=>J.ws.readyState===v.OPEN)}function q(J){const K=typeof J==="string"&&J.trim()?J.trim():void 0;if(K){const z=W.get(K);if(z?.ws.readyState===v.OPEN)return{connection:z};const Q=j();if(Q.length===1){G.warn(`[daemon] Requested profile "${K}" not connected; falling back to the only connected profile "${Q[0].contextId}"`);return{connection:Q[0]}}return{errorCode:"profile_disconnected",error:`Browser profile "${K}" is not connected.`,errorHint:"Open that Chrome profile and make sure the OpenCLI extension is enabled, or choose another profile with opencli profile use <name>."}}const Z=j();if(Z.length===1)return{connection:Z[0]};if(Z.length>1)return{errorCode:"profile_required",error:"Multiple Browser Bridge profiles are connected; choose one with --profile.",errorHint:"Run opencli profile list, then use opencli --profile <name> ... or opencli profile use <name>."};return{errorCode:"extension_not_connected",error:"Extension not connected. Please install the opencli Browser Bridge extension."}}function o(J,K){const Z=typeof K==="string"&&K.trim()?K.trim():d,z=W.get(Z);if(z&&z.ws!==J)z.ws.close();const Q=[...W.entries()].find(([,A])=>A.ws===J);if(Q&&Q[0]!==Z)W.delete(Q[0]);const $=W.get(Z),V={contextId:Z,ws:J,extensionVersion:$?.ws===J?$.extensionVersion:null,extensionCompatRange:$?.ws===J?$.extensionCompatRange:null,lastSeenAt:Date.now()};W.set(Z,V);return V}function x(J){for(const[K,Z]of W.entries()){if(Z.ws!==J)continue;W.delete(K);L.traceExtDisconnect(K);for(const[z,Q]of N){if(Q.contextId!==K)continue;clearTimeout(Q.timer);const $=i({contextId:K,action:Q.action,dispatched:Q.dispatched});if($.countAsCommandResultUnknown){I++;G.warn(`[daemon] Command result unknown after extension disconnect (id=${z}, action=${Q.action}, context=${K})`)}L.traceResult(z,!1,Date.now()-Q.dispatchTs,$.errorCode);Q.reject(new E($.message,$.errorCode,$.errorHint,$.status));N.delete(z)}}}const w=33554432;class P extends Error{status=413;constructor(){super(`请求体超过 ${w/1024/1024} MB 上限（正文内联图片过多/过大？可减少单次发布的图片体积）`);this.name="BodyTooLargeError"}}function r(J){return new Promise((K,Z)=>{const z=[];let Q=0,$=!1;J.on("data",(V)=>{if($)return;Q+=V.length;if(Q>w){$=!0;z.length=0;Z(new P);return}z.push(V)});J.on("end",()=>{if(!$)K(Buffer.concat(z).toString("utf-8"))});J.on("error",(V)=>{if(!$)Z(V)})})}function Y(J,K,Z,z){J.writeHead(K,{"Content-Type":"application/json",...z});J.end(JSON.stringify(Z))}async function f(J,K){const Z=J.headers.origin;if(Z&&!Z.startsWith("chrome-extension://")){Y(K,403,{ok:!1,error:"Forbidden: cross-origin request blocked"});return}if(J.method==="OPTIONS"){K.writeHead(204);K.end();return}const z=J.url??"/",Q=z.split("?")[0];if(J.method==="GET"&&Q==="/ping"){Y(K,200,{ok:!0},t(Q,Z));return}if(!J.headers["x-opencli"]){Y(K,403,{ok:!1,error:"Forbidden: missing X-OpenCLI header"});return}if(J.method==="GET"&&Q==="/status"){const $=process.uptime(),V=process.memoryUsage(),F=new URL(z,`http://localhost:${B}`).searchParams.get("contextId")?.trim()||void 0,X=q(F),_=j().map((M)=>({contextId:M.contextId,extensionConnected:!0,extensionVersion:M.extensionVersion??void 0,extensionCompatRange:M.extensionCompatRange??void 0,pending:[...N.values()].filter((H)=>H.contextId===M.contextId).length,lastSeenAt:M.lastSeenAt}));Y(K,200,{ok:!0,pid:process.pid,uptime:$,daemonVersion:l,extensionConnected:!!X.connection,extensionVersion:X.connection?.extensionVersion??void 0,extensionCompatRange:X.connection?.extensionCompatRange??void 0,contextId:X.connection?.contextId??F,profileRequired:X.errorCode==="profile_required",profileDisconnected:X.errorCode==="profile_disconnected",profiles:_,pending:N.size,commandResultUnknown:I,memoryMB:Math.round(V.rss/1024/1024*10)/10,port:B});return}if(J.method==="GET"&&Q==="/logs"){const V=new URL(z,`http://localhost:${B}`).searchParams.get("level"),A=V?k.filter((F)=>F.level===V):k;Y(K,200,{ok:!0,logs:A});return}if(J.method==="DELETE"&&Q==="/logs"){k.length=0;Y(K,200,{ok:!0});return}if(J.method==="POST"&&Q==="/shutdown"){Y(K,200,{ok:!0,message:"Shutting down"});setTimeout(()=>R(),100);return}if(J.method==="POST"&&z==="/command"){try{const $=JSON.parse(await r(J));if(!$.id){Y(K,400,{ok:!1,error:"Missing command id"});return}const V=q(typeof $.contextId==="string"?$.contextId:void 0);if(!V.connection){Y(K,V.errorCode==="profile_required"?409:503,{id:$.id,ok:!1,errorCode:V.errorCode,error:V.error,...V.errorHint?{errorHint:V.errorHint}:{}});return}const A=typeof $.timeout==="number"&&$.timeout>0?$.timeout*1000:120000;if(N.has($.id)){Y(K,409,{id:$.id,ok:!1,error:"Duplicate command id already pending; retry"});return}const F=await new Promise((X,_)=>{const M=setTimeout(()=>{N.delete($.id);L.traceTimeout($.id,A,typeof $.action==="string"?$.action:void 0);_(Error(`Command timeout (${A/1000}s)`))},A),H={contextId:V.connection.contextId,action:typeof $.action==="string"?$.action:"unknown",dispatched:!1,dispatchTs:Date.now(),resolve:X,reject:_,timer:M};N.set($.id,H);const y=(U)=>{if(N.get($.id)!==H)return;const D=a(H.contextId);clearTimeout(M);N.delete($.id);_(new E(D.message,D.errorCode,D.errorHint,D.status));G.warn(`[daemon] Failed to dispatch command ${$.id}: ${U instanceof Error?U.message:String(U)}`)};try{V.connection.ws.send(JSON.stringify($),(U)=>{if(U&&!H.dispatched)y(U)});H.dispatched=!0;L.traceDispatch($)}catch(U){y(U)}});Y(K,200,F)}catch($){const V=$ instanceof E?$:null;if($ instanceof P){Y(K,413,{ok:!1,error:$.message,errorCode:"body_too_large"});return}Y(K,V?.status??($ instanceof Error&&$.message.includes("timeout")?408:400),{ok:!1,error:$ instanceof Error?$.message:"Invalid request",...V?.errorCode?{errorCode:V.errorCode}:{},...V?.errorHint?{errorHint:V.errorHint}:{}})}return}Y(K,404,{error:"Not found"})}const O=b((J,K)=>{f(J,K).catch(()=>{K.writeHead(500);K.end()})}),T=b((J,K)=>{f(J,K).catch(()=>{K.writeHead(500);K.end()})}),C=new u({noServer:!0});function m(J,K,Z){if((J.url??"/").split("?")[0]!=="/ext"){K.destroy();return}const Q=J.headers.origin;if(Q&&!Q.startsWith("chrome-extension://")){K.destroy();return}C.handleUpgrade(J,K,Z,($)=>{C.emit("connection",$,J)})}O.on("upgrade",m);T.on("upgrade",m);C.on("connection",(J)=>{G.info("[daemon] Extension connected");let K=0;const Z=setInterval(()=>{if(J.readyState!==v.OPEN){clearInterval(Z);return}if(K>=2){G.warn("[daemon] Extension heartbeat lost, closing connection");clearInterval(Z);J.terminate();return}K++;J.ping()},15000);J.on("pong",()=>{K=0});J.on("message",(z)=>{try{const Q=JSON.parse(z.toString());if(Q.type==="hello"){if(Q.brand!=="publishport"){G.warn(`[daemon] 拒绝非 PublishPort 官方扩展连接（brand=${JSON.stringify(Q.brand)}）`);J.close(4003,"Only the official PublishPort extension is supported");return}const V=o(J,Q.contextId);V.extensionVersion=typeof Q.version==="string"?Q.version:null;V.extensionCompatRange=typeof Q.compatRange==="string"?Q.compatRange:null;V.lastSeenAt=Date.now();G.info(`[daemon] Extension profile connected: ${V.contextId}`);L.traceExtConnect(V.contextId,V.extensionVersion);return}if(Q.type==="log"){if(Q.level==="error")G.error(`[ext] ${Q.msg}`);else if(Q.level==="warn")G.warn(`[ext] ${Q.msg}`);else G.info(`[ext] ${Q.msg}`);s({level:Q.level,msg:Q.msg,ts:Q.ts??Date.now()});L.traceExtLog(Q.level,Q.msg);return}const $=N.get(Q.id);if($){clearTimeout($.timer);N.delete(Q.id);L.traceResult(Q.id,!!Q.ok,Date.now()-$.dispatchTs,typeof Q.errorCode==="string"?Q.errorCode:void 0,typeof Q.page==="string"?Q.page:void 0);$.resolve(Q)}}catch(Q){const $=z.toString().slice(0,200);G.warn(`[daemon] Ignoring malformed WS message from extension: ${Q instanceof Error?Q.message:String(Q)} (first 200 chars: ${JSON.stringify($)})`)}});J.on("close",()=>{G.info("[daemon] Extension disconnected");clearInterval(Z);x(J)});J.on("error",()=>{clearInterval(Z);x(J)})});O.listen(B,"127.0.0.1",()=>{G.info(`[daemon] Listening on http://127.0.0.1:${B}`)});O.on("error",(J)=>{if(J.code==="EADDRINUSE"){G.error(`[daemon] Port ${B} already in use — another daemon is likely running. Exiting.`);process.exit(S.SERVICE_UNAVAIL)}G.error(`[daemon] Server error: ${J.message}`);process.exit(S.GENERIC_ERROR)});T.listen(h,"127.0.0.1",()=>{G.info(`[daemon] Listening on http://127.0.0.1:${h} (PublishPort extension)`)});T.on("error",(J)=>{G.warn(`[daemon] PublishPort port ${h} unavailable (${J.message}) — extension will fall back to ${B}`)});function R(){for(const[,J]of N){clearTimeout(J.timer);J.reject(Error("Daemon shutting down"))}N.clear();for(const J of W.values())J.ws.close();O.close();T.close();process.exit(S.SUCCESS)}process.on("SIGTERM",R);process.on("SIGINT",R);

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

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

package/dist/src/discovery.d.ts

@@ -0,0 +1,43 @@
+/**
+ * CLI discovery: finds JS CLI definitions and registers them.
+ *
+ * Supports two modes:
+ * 1. FAST PATH (manifest): If a pre-compiled cli-manifest.json exists,
+ *    registers commands instantly. JS modules are loaded lazily only
+ *    when their command is executed.
+ * 2. FALLBACK (filesystem scan): Traditional runtime discovery for development.
+ */
+/** User runtime directory: ~/.opencli */
+export declare const USER_OPENCLI_DIR: string;
+/** User CLIs directory: ~/.opencli/clis */
+export declare const USER_CLIS_DIR: string;
+/** Plugins directory: ~/.opencli/plugins/ */
+export declare const PLUGINS_DIR: string;
+/**
+ * Ensure ~/.opencli/node_modules/@jackwener/opencli symlink exists so that
+ * user CLIs in ~/.opencli/clis/ can `import { cli } from '@jackwener/opencli/registry'`.
+ *
+ * This is the sole resolution mechanism — adapters use package exports
+ * (e.g. `@jackwener/opencli/registry`, `@jackwener/opencli/errors`) and
+ * Node.js resolves them through this symlink.
+ */
+export declare function ensureUserCliCompatShims(baseDir?: string): Promise<void>;
+/**
+ * Ensure the user adapters directory exists.
+ *
+ * With smart sync, ~/.opencli/clis/ only holds files that differ from the
+ * package baseline (upstream-synced cache + autofix output + user overrides).
+ * Built-in adapters are loaded directly from the installed package.
+ */
+export declare function ensureUserAdapters(): Promise<void>;
+/**
+ * Discover and register CLI commands.
+ * Uses pre-compiled manifest when available for instant startup.
+ */
+export declare function discoverClis(...dirs: string[]): Promise<void>;
+/**
+ * Discover and register plugins from ~/.opencli/plugins/.
+ * Each subdirectory is treated as a plugin (site = directory name).
+ * Files inside are scanned flat (no nested site subdirs).
+ */
+export declare function discoverPlugins(): Promise<void>;

package/dist/src/discovery.js

@@ -0,0 +1,2 @@
+import*as H from"node:fs";import*as G from"node:os";import*as Y from"node:path";import{fileURLToPath as F,pathToFileURL as v}from"node:url";import{Strategy as A,registerCommand as J}from"./registry.js";import{getErrorMessage as $}from"./errors.js";import{log as Z}from"./logger.js";import{findPackageRoot as O,getCliManifestPath as N}from"./package-paths.js";export const USER_OPENCLI_DIR=Y.join(G.homedir(),".opencli"),USER_CLIS_DIR=Y.join(USER_OPENCLI_DIR,"clis"),PLUGINS_DIR=Y.join(USER_OPENCLI_DIR,"plugins");const T=/\b(?:cli|registerSiteAuthCommands|onStartup|onBeforeExecute|onAfterExecute)\s*\(/;function b(z,x=A.COOKIE){if(!z)return x;const B=z.toUpperCase();return A[B]??x}const L=O(F(import.meta.url));export async function ensureUserCliCompatShims(z=USER_OPENCLI_DIR){await H.promises.mkdir(z,{recursive:!0});const x=Y.join(z,"package.json"),B=`${JSON.stringify({name:"opencli-user-runtime",private:!0,type:"module"},null,2)}
+`;try{if(await H.promises.readFile(x,"utf-8")!==B)await H.promises.writeFile(x,B,"utf-8")}catch{await H.promises.writeFile(x,B,"utf-8")}const V=L,q=Y.join(z,"node_modules","@jackwener"),Q=Y.join(q,"opencli");try{let W=!0;try{if(await H.promises.readlink(Q)===V)W=!1}catch{}if(W){await H.promises.mkdir(q,{recursive:!0});try{await H.promises.rm(Q,{recursive:!0,force:!0})}catch{}const X=process.platform==="win32"?"junction":"dir";await H.promises.symlink(V,Q,X)}}catch(W){Z.warn(`Could not create symlink at ${Q}: ${$(W)}`)}}export async function ensureUserAdapters(){await H.promises.mkdir(USER_CLIS_DIR,{recursive:!0})}export async function discoverClis(...z){for(const x of z){const B=N(x);try{await H.promises.access(B);if(await M(B,x))continue}catch{}await C(x)}}async function M(z,x){try{const B=await H.promises.readFile(z,"utf-8"),V=JSON.parse(B);for(const q of V){if(!q.modulePath)continue;const Q=Y.resolve(x,q.modulePath),W={site:q.site,name:q.name,aliases:q.aliases,description:q.description??"",access:q.access,example:q.example,domain:q.domain,strategy:b(q.strategy),browser:q.browser,args:q.args??[],columns:q.columns,defaultFormat:q.defaultFormat,pipeline:q.pipeline,source:q.sourceFile?Y.resolve(x,q.sourceFile):Q,navigateBefore:q.navigateBefore,siteSession:q.siteSession,defaultWindowMode:q.defaultWindowMode,_lazy:!0,_modulePath:Q};J(W)}return!0}catch(B){Z.warn(`Failed to load manifest ${z}: ${$(B)}`);return!1}}async function C(z){try{await H.promises.access(z)}catch{return}const B=(await H.promises.readdir(z,{withFileTypes:!0})).filter((V)=>V.isDirectory()).map(async(V)=>{const q=V.name,Q=Y.join(z,q),W=await H.promises.readdir(Q);await Promise.all(W.map(async(X)=>{const K=Y.join(Q,X);if(X.endsWith(".yaml")||X.endsWith(".yml"))return;if(X.endsWith(".ts")&&!X.endsWith(".d.ts")&&!X.endsWith(".test.ts")){Z.warn(`Ignoring TypeScript adapter ${K} — .ts adapters are no longer loaded. Rename to .js or convert to JavaScript.`);return}if(X.endsWith(".js")&&!X.endsWith(".d.js")&&!X.endsWith(".test.js")){if(!await j(K))return;await import(v(K).href).catch((w)=>{Z.warn(`Failed to load module ${K}: ${$(w)}`)})}}))});await Promise.all(B)}export async function discoverPlugins(){try{await H.promises.access(PLUGINS_DIR)}catch{return}const z=await H.promises.readdir(PLUGINS_DIR,{withFileTypes:!0});await Promise.all(z.map(async(x)=>{const B=Y.join(PLUGINS_DIR,x.name);if(!await _(x,B))return;await U(B,x.name)}))}async function U(z,x){let B;try{B=await H.promises.readdir(z)}catch(q){const Q=q.code;if(Q!=="ENOENT"&&Q!=="ENOTDIR")Z.warn(`Failed to scan plugin directory ${z}: ${$(q)}`);return}const V=new Set(B);await Promise.all(B.map(async(q)=>{const Q=Y.join(z,q);if(q.endsWith(".yaml")||q.endsWith(".yml"))return;if(q.endsWith(".js")&&!q.endsWith(".d.js")){if(!await j(Q))return;await import(v(Q).href).catch((W)=>{Z.warn(`Plugin ${x}/${q}: ${$(W)}`)})}else if(q.endsWith(".ts")&&!q.endsWith(".d.ts")&&!q.endsWith(".test.ts")){const W=q.replace(/\.ts$/,".js");if(V.has(W))return;Z.warn(`Plugin ${x}/${q}: no compiled .js found. Run "opencli plugin update ${x}" to re-transpile, or install esbuild.`)}}))}async function j(z){try{const x=await H.promises.readFile(z,"utf-8");return T.test(x)}catch(x){Z.warn(`Failed to inspect module ${z}: ${$(x)}`);return!1}}async function _(z,x){if(z.isDirectory())return!0;if(!z.isSymbolicLink())return!1;try{return(await H.promises.stat(x)).isDirectory()}catch(B){const V=B.code;if(V!=="ENOENT"&&V!=="ENOTDIR")Z.warn(`Failed to inspect plugin link ${x}: ${$(B)}`);return!1}}

package/dist/src/doctor.d.ts

@@ -0,0 +1,38 @@
+/**
+ * opencli doctor — diagnose browser connectivity.
+ *
+ * Simplified for the daemon-based architecture.
+ */
+import type { BrowserProfileStatus } from './browser/daemon-client.js';
+import { type AdapterShadow } from './adapter-shadow.js';
+export type DoctorOptions = {
+    yes?: boolean;
+    cliVersion?: string;
+};
+export type ConnectivityResult = {
+    ok: boolean;
+    error?: string;
+    durationMs: number;
+};
+export type DoctorReport = {
+    cliVersion?: string;
+    daemonRunning: boolean;
+    daemonFlaky?: boolean;
+    daemonStale?: boolean;
+    daemonVersion?: string;
+    extensionConnected: boolean;
+    extensionFlaky?: boolean;
+    extensionVersion?: string;
+    connectivity?: ConnectivityResult;
+    profiles?: BrowserProfileStatus[];
+    adapterShadows?: AdapterShadow[];
+    issues: string[];
+};
+/**
+ * Test connectivity by attempting a real browser command.
+ */
+export declare function checkConnectivity(opts?: {
+    timeout?: number;
+}): Promise<ConnectivityResult>;
+export declare function runBrowserDoctor(opts?: DoctorOptions): Promise<DoctorReport>;
+export declare function renderBrowserDoctorReport(report: DoctorReport): string;

package/dist/src/doctor.js

@@ -0,0 +1,13 @@
+import{DEFAULT_DAEMON_PORT as L}from"./constants.js";import{BrowserBridge as M}from"./browser/index.js";import{getDaemonHealth as k}from"./browser/daemon-client.js";import{getErrorMessage as _}from"./errors.js";import{getRuntimeLabel as F}from"./runtime-detect.js";import{aliasForContextId as E,loadProfileConfig as T}from"./browser/profile.js";import{formatDaemonVersion as P,isDaemonStale as I,staleDaemonIssue as O}from"./browser/daemon-version.js";import{findShadowedUserAdapters as b,formatAdapterShadowIssue as j}from"./adapter-shadow.js";const w=8,y="__doctor__";function N(q){const z=q.replace(/^v/,"").split("-")[0].split(".").map(Number);if(z.length<3||z.some(isNaN))return null;return[z[0],z[1],z[2]]}function D(q,z){const G=z.match(/^(>=?)\s*(\S+)$/);if(!G)return!0;const[,K,$]=G,X=N(q),Y=N($);if(!X||!Y)return!0;const Q=X[0]-Y[0]||X[1]-Y[1]||X[2]-Y[2];return K===">="?Q>=0:Q>0}export async function checkConnectivity(q){const z=Date.now();try{const G=new M,K=await G.connect({timeout:q?.timeout??w,session:y,surface:"browser"});try{await K.evaluate("1 + 1");await K.closeWindow?.()}finally{await G.close()}return{ok:!0,durationMs:Date.now()-z}}catch(G){return{ok:!1,error:_(G),durationMs:Date.now()-z}}}export async function runBrowserDoctor(q={}){const z=await checkConnectivity(),G=await k(),K=G.state!=="stopped",$=G.state==="ready",X=z.ok&&!K,Y=z.ok&&K&&!$,Q=I(G.status,q.cliVersion),Z=G.status?.profiles,W=G.status?.extensionVersion,H=b(),J=[];if(X)J.push(`Daemon connectivity is unstable. The live browser test succeeded, but the daemon was no longer running immediately afterward.
+This usually means the daemon crashed or exited right after serving the live probe.`);else if(!K)J.push("Daemon is not running. It should start automatically when you run an opencli browser command.");if(Q&&q.cliVersion)J.push(O(G.status,q.cliVersion));if(Y)J.push(`Extension connection is unstable. The live browser test succeeded, but the daemon reported the extension disconnected immediately afterward.
+This usually means the Browser Bridge service worker is reconnecting slowly or Chrome suspended it.`);else if(K&&!$)if(G.state==="profile-required")J.push(`Multiple Chrome profiles are connected to the daemon, but no default profile was selected.
+  Run opencli profile list, then opencli profile use <name>, or pass --profile <name>.`);else if(G.state==="profile-disconnected")J.push(`Selected browser profile is not connected: ${G.status?.contextId??"unknown"}.
+  Open that Chrome profile and make sure the OpenCLI extension is enabled.`);else J.push(`Daemon is running but the Chrome/Chromium extension is not connected.
+If the extension is already installed, try: opencli daemon restart
+If the extension is not installed, install the PublishPort browser extension
+from the PublishPort desktop app.`);if($&&!W)J.push(`Extension is connected but did not report a version.
+  This usually means an outdated Browser Bridge extension.
+  Reload or reinstall the PublishPort browser extension via the PublishPort desktop app.`);if(!z.ok)J.push(`Browser connectivity test failed: ${z.error??"unknown"}`);const B=G.status?.extensionCompatRange;if(W&&q.cliVersion&&B){if(!D(q.cliVersion,B))J.push(`CLI version incompatible with extension: extension v${W} requires CLI ${B}, but CLI is v${q.cliVersion}
+  Update via the PublishPort desktop app (or: npm install -g publishport-opencli).`)}else if(W&&q.cliVersion){const U=W.split(".")[0],A=q.cliVersion.split(".")[0];if(U!==A)J.push(`Extension major version mismatch: extension v${W} ≠ CLI v${q.cliVersion}
+  Update the PublishPort browser extension via the PublishPort desktop app.`)}if(H.length>0)J.push(j(H));return{cliVersion:q.cliVersion,daemonRunning:K,daemonFlaky:X,daemonStale:Q,daemonVersion:G.status?.daemonVersion,extensionConnected:$,extensionFlaky:Y,extensionVersion:W,connectivity:z,profiles:Z,adapterShadows:H,issues:J}}export function renderBrowserDoctorReport(q){const z=[`opencli v${q.cliVersion??"unknown"} doctor (${F()})`,""],G=q.daemonFlaky?"[WARN]":q.daemonStale?"[WARN]":q.daemonRunning?"[OK]":"[MISSING]",K=q.daemonFlaky?"unstable (running during live check, then stopped)":q.daemonRunning?`running on port ${L} (${q.daemonStale?`${P(q)}, stale; CLI v${q.cliVersion??"unknown"}`:P(q)})`:"not running";z.push(`${G} Daemon: ${K}`);const $=q.extensionFlaky||q.extensionConnected&&!q.extensionVersion?"[WARN]":q.extensionConnected?"[OK]":"[MISSING]",X=!q.extensionConnected?"":q.extensionVersion?` (v${q.extensionVersion})`:" (version unknown)",Y=q.extensionFlaky?"unstable (connected during live check, then disconnected)":q.extensionConnected?"connected":"not connected";z.push(`${$} Extension: ${Y}${X}`);if(q.profiles&&q.profiles.length>0){const Q=T();z.push("","Profiles:");for(const Z of q.profiles){const W=E(Q,Z.contextId),H=W?` (${W})`:"",J=Q.defaultContextId===Z.contextId?", default":"",B=Z.extensionVersion?`v${Z.extensionVersion}`:"version unknown";z.push(`  • ${Z.contextId}${H}: connected ${B}${J}`)}}if(q.connectivity){const Q=q.connectivity.ok?"[OK]":"[FAIL]",Z=q.connectivity.ok?`connected in ${(q.connectivity.durationMs/1000).toFixed(1)}s`:`failed (${q.connectivity.error??"unknown"})`;z.push(`${Q} Connectivity: ${Z}`)}if(q.issues.length){z.push("","Issues:");for(const Q of q.issues)z.push(`  • ${Q}`)}else if(q.daemonRunning&&q.extensionConnected)z.push("","Everything looks good!");return z.join(`
+`)}

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

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

package/dist/src/download/article-download.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Article download helper — shared logic for downloading articles as Markdown.
+ *
+ * Used by: zhihu/download, weixin/download, and future article adapters.
+ *
+ * Flow: ArticleData → TurndownService → image download → frontmatter → .md file
+ */
+import TurndownService from 'turndown';
+export interface ArticleData {
+    title: string;
+    author?: string;
+    publishTime?: string;
+    sourceUrl?: string;
+    contentHtml: string;
+    /** Pre-extracted code blocks to restore after Markdown conversion */
+    codeBlocks?: Array<{
+        lang: string;
+        code: string;
+    }>;
+    /** Image URLs found in the article (pre-collected from DOM) */
+    imageUrls?: string[];
+}
+export interface FrontmatterLabels {
+    author?: string;
+    publishTime?: string;
+    sourceUrl?: string;
+}
+export interface ArticleDownloadOptions {
+    output: string;
+    downloadImages?: boolean;
+    /** Extra headers for image downloads (e.g. { Referer: '...' }) */
+    imageHeaders?: Record<string, string>;
+    maxTitleLength?: number;
+    /** Custom TurndownService configuration callback */
+    configureTurndown?: (td: TurndownService) => void;
+    /** Custom image extension detector (default: infer from URL extension) */
+    detectImageExt?: (url: string) => string;
+    /** Custom frontmatter labels (default: Chinese labels) */
+    frontmatterLabels?: FrontmatterLabels;
+    /**
+     * Extra CSS selectors removed from the article before Turndown conversion.
+     * Use this to drop site-specific noise the adapter can't always trim upstream
+     * (e.g. zhihu 折叠卡, weixin 赞赏栏, wiki infobox).
+     */
+    cleanSelectors?: string[];
+    /**
+     * Write the markdown to `process.stdout` instead of a file on disk. Image
+     * download and directory creation are skipped — remote image URLs are kept
+     * as-is so the output is self-contained when piped.
+     */
+    stdout?: boolean;
+}
+export interface ArticleDownloadResult {
+    title: string;
+    author: string;
+    publish_time: string;
+    status: string;
+    size: string;
+    saved: string;
+}
+/**
+ * Download an article to Markdown with optional image localization.
+ *
+ * Handles the full pipeline:
+ * 1. HTML → Markdown (via TurndownService)
+ * 2. Code block placeholder restoration
+ * 3. Batch image downloading with concurrency + deduplication
+ * 4. Image URL replacement in Markdown
+ * 5. Frontmatter generation (customizable labels)
+ * 6. File write
+ */
+export declare function downloadArticle(data: ArticleData, options: ArticleDownloadOptions): Promise<ArticleDownloadResult[]>;

package/dist/src/download/article-download.js

@@ -0,0 +1,21 @@
+import*as P from"node:fs";import*as H from"node:path";import k from"turndown";import{gfm as x}from"turndown-plugin-gfm";import{httpDownload as C,sanitizeFilename as E}from"./index.js";import{formatBytes as I}from"./progress.js";const b=5,M={author:"作者",publishTime:"发布时间",sourceUrl:"原文链接"},T=["script","style","noscript","canvas","form","button","dialog","header","footer","nav","aside"];function D(J,$){const V=new k({headingStyle:"atx",codeBlockStyle:"fenced",bulletListMarker:"-"});V.use(x);V.remove(T);V.addRule("canonicalStrikethrough",{filter:(K)=>["DEL","S","STRIKE"].includes(K.nodeName),replacement:(K)=>`~~${K}~~`});V.addRule("stripSvg",{filter:(K)=>K.nodeName==="svg"||K.nodeName==="SVG",replacement:()=>""});V.addRule("linebreak",{filter:"br",replacement:()=>`
+`});V.addRule("ignoreBase64Images",{filter:(K)=>{if(K.nodeName!=="IMG")return!1;return(K.getAttribute?.("src")??"").startsWith("data:")},replacement:()=>""});V.addRule("videoElement",{filter:(K)=>K.nodeName==="VIDEO",replacement:(K,Q)=>{const W=Q,Z=W.getAttribute("src")||W.querySelector("source")?.getAttribute("src")||"";if(!Z)return"";const X=W.getAttribute("poster")||"";return`
+<video src="${Z}" controls${X?` poster="${X}"`:""}></video>
+`}});V.addRule("audioElement",{filter:(K)=>K.nodeName==="AUDIO",replacement:(K,Q)=>{const W=Q,Z=W.getAttribute("src")||W.querySelector("source")?.getAttribute("src")||"";return Z?`
+<audio src="${Z}" controls></audio>
+`:""}});V.addRule("iframeToLink",{filter:(K)=>K.nodeName==="IFRAME",replacement:(K,Q)=>{const W=Q,Z=W.getAttribute("src")||"";if(!Z)return"";return`
+[${W.getAttribute("title")||"Embedded content"}](${Z})
+`}});const q=($??[]).map((K)=>K.trim()).filter(Boolean);if(q.length>0)V.addRule("cleanSelectors",{filter:(K)=>{const Q=K.matches;if(typeof Q!=="function")return!1;return q.some((W)=>{try{return Q.call(K,W)}catch{return!1}})},replacement:()=>""});if(J)J(V);return V}function w(J,$,V,q){let Q=D(V,q).turndown(J);$.forEach((W,Z)=>{const X=`CODEBLOCK-PLACEHOLDER-${Z}`,y=`
+\`\`\`${W.lang}
+${W.code}
+\`\`\`
+`;Q=Q.replace(X,y)});Q=Q.replace(/\u00a0/g," ");Q=Q.replace(/^[ \t]*[-·][ \t]*$/gm,"");Q=Q.replace(/^[ \t]+$/gm,"");Q=Q.replace(/[ \t]+$/gm,"");Q=Q.replace(/\n{3,}/g,`
+
+`);return Q}function U(J,$){return J.replace(/!\[([^\]]*)\]\(([^)]+)\)/g,(V,q,K)=>{const Q=$[K];return Q?`![${q}](${Q})`:V})}function h(J){const $=J.match(/\.(\w{3,4})(?:\?|$)/);return $?$[1]:"jpg"}async function p(J,$,V,q){const K={};if(J.length===0)return K;const Q=q||h,W=new Set,Z=J.filter((X)=>{if(W.has(X))return!1;W.add(X);return!0});for(let X=0;X<Z.length;X+=b){const y=Z.slice(X,X+b),j=await Promise.all(y.map(async(F,z)=>{const G=X+z+1;let O=F;if(O.startsWith("//"))O=`https:${O}`;const v=Q(O),Y=`img_${String(G).padStart(3,"0")}.${v}`,N=H.join($,Y);try{if((await C(O,N,{headers:V,timeout:15000})).success)return{remoteUrl:F,localPath:`images/${Y}`}}catch{}return null}));for(const F of j)if(F)K[F.remoteUrl]=F.localPath}return K}export async function downloadArticle(J,$){const{output:V,downloadImages:q=!0,imageHeaders:K,maxTitleLength:Q=80,configureTurndown:W,detectImageExt:Z,frontmatterLabels:X,cleanSelectors:y,stdout:j=!1}=$,F={...M,...X};if(!J.title)return[{title:"Error",author:"-",publish_time:"-",status:"failed — no title",size:"-",saved:"-"}];if(!J.contentHtml)return[{title:J.title,author:J.author||"-",publish_time:J.publishTime||"-",status:"failed — no content",size:"-",saved:"-"}];let z=w(J.contentHtml,J.codeBlocks||[],W,y);const G=E(J.title,Q);if(!j&&q&&J.imageUrls&&J.imageUrls.length>0){const B=H.join(V,G);P.mkdirSync(B,{recursive:!0});const R=H.join(B,"images");P.mkdirSync(R,{recursive:!0});const S=await p(J.imageUrls,R,K,Z);z=U(z,S)}const O=[`# ${J.title}`];if(J.author)O.push(`> ${F.author}: ${J.author}`);if(J.publishTime)O.push(`> ${F.publishTime}: ${J.publishTime}`);if(J.sourceUrl)O.push(`> ${F.sourceUrl}: ${J.sourceUrl}`);const Y=O.join(`
+`)+`
+
+---
+
+`+z,N=Buffer.byteLength(Y,"utf-8");if(j){process.stdout.write(Y.endsWith(`
+`)?Y:Y+`
+`);return[{title:J.title,author:J.author||"-",publish_time:J.publishTime||"-",status:"success",size:I(N),saved:"-"}]}const _=H.join(V,G);P.mkdirSync(_,{recursive:!0});const L=`${G}.md`,A=H.join(_,L);P.writeFileSync(A,Y,"utf-8");return[{title:J.title,author:J.author||"-",publish_time:J.publishTime||"-",status:"success",size:I(N),saved:A}]}

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

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

package/dist/src/download/index.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Download utilities: HTTP downloads, yt-dlp wrapper, format conversion.
+ */
+import type { BrowserCookie } from '../types.js';
+export type { BrowserCookie } from '../types.js';
+export interface DownloadOptions {
+    cookies?: string;
+    headers?: Record<string, string>;
+    timeout?: number;
+    onProgress?: (received: number, total: number) => void;
+    maxRedirects?: number;
+}
+export interface YtdlpOptions {
+    cookies?: string;
+    cookiesFile?: string;
+    format?: string;
+    extraArgs?: string[];
+    onProgress?: (percent: number) => void;
+}
+/** Check if yt-dlp is available in PATH. */
+export declare function checkYtdlp(): boolean;
+/**
+ * Detect content type from URL and optional headers.
+ */
+export declare function detectContentType(url: string, contentType?: string): 'image' | 'video' | 'document' | 'binary';
+/**
+ * Check if URL requires yt-dlp for download.
+ */
+export declare function requiresYtdlp(url: string): boolean;
+/**
+ * HTTP download with progress callback.
+ */
+export declare function httpDownload(url: string, destPath: string, options?: DownloadOptions, redirectCount?: number): Promise<{
+    success: boolean;
+    size: number;
+    error?: string;
+}>;
+export declare function resolveRedirectUrl(currentUrl: string, location: string): string;
+/**
+ * Export cookies to Netscape format for yt-dlp.
+ */
+export declare function exportCookiesToNetscape(cookies: BrowserCookie[], filePath: string): void;
+export declare function formatCookieHeader(cookies: BrowserCookie[]): string;
+/**
+ * Download video using yt-dlp.
+ */
+export declare function ytdlpDownload(url: string, destPath: string, options?: YtdlpOptions): Promise<{
+    success: boolean;
+    size: number;
+    error?: string;
+}>;
+/**
+ * Save document content to file.
+ */
+export declare function saveDocument(content: string, destPath: string, format?: 'json' | 'markdown' | 'html' | 'text', metadata?: Record<string, unknown>): Promise<{
+    success: boolean;
+    size: number;
+    error?: string;
+}>;
+/**
+ * Sanitize filename by removing invalid characters.
+ */
+export declare function sanitizeFilename(name: string, maxLength?: number): string;
+/**
+ * Generate filename from URL if not provided.
+ */
+export declare function generateFilename(url: string, index: number, extension?: string): string;
+/**
+ * Get temp directory for cookie files.
+ */
+export declare function getTempDir(): string;

package/dist/src/download/index.js

@@ -0,0 +1,7 @@
+import{spawn as R}from"node:child_process";import*as W from"node:fs";import*as H from"node:path";import*as E from"node:os";import{Readable as v,Transform as U}from"node:stream";import{pipeline as y}from"node:stream/promises";import{URL as _}from"node:url";import{isBinaryInstalled as T}from"../external.js";import{getErrorMessage as L}from"../errors.js";import{fetchWithNodeNetwork as x}from"../node-network.js";import{log as g}from"../logger.js";export function checkYtdlp(){return T("yt-dlp")}const k=["youtube.com","youtu.be","bilibili.com","twitter.com","x.com","tiktok.com","vimeo.com","twitch.tv"];function F(K){let J;try{J=new _(K).hostname.toLowerCase()}catch{return!1}return k.some((Q)=>J===Q||J.endsWith(`.${Q}`))}const f=new Set([".jpg",".jpeg",".png",".gif",".webp",".svg",".ico",".bmp",".avif"]),P=new Set([".mp4",".webm",".avi",".mov",".mkv",".flv",".m3u8",".ts"]),m=new Set([".html",".htm",".json",".xml",".txt",".md",".markdown"]);export function detectContentType(K,J){if(J){if(J.startsWith("image/"))return"image";if(J.startsWith("video/"))return"video";if(J.startsWith("text/")||J.includes("json")||J.includes("xml"))return"document"}let Q="";try{Q=H.extname(new _(K).pathname).toLowerCase()}catch{return"binary"}if(f.has(Q))return"image";if(P.has(Q))return"video";if(F(K))return"video";if(m.has(Q))return"document";return"binary"}export function requiresYtdlp(K){return F(K)}export async function httpDownload(K,J,Q={},Z=0){const{cookies:$,headers:Y={},timeout:z=30000,onProgress:q,maxRedirects:w=10}=Q,A={"User-Agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/134.0.0.0 Safari/537.36",...Y};if($)A.Cookie=$;const D=`${J}.tmp`,M=async()=>{try{await W.promises.rm(D,{force:!0})}catch{}},C=new AbortController,X=setTimeout(()=>C.abort(),z);try{const B=await x(K,{headers:A,signal:C.signal,redirect:"manual"});clearTimeout(X);if(B.status>=300&&B.status<400){const V=B.headers.get("location");if(V){if(Z>=w)return{success:!1,size:0,error:`Too many redirects (> ${w})`};const b=resolveRedirectUrl(K,V),I=new _(K).hostname,S=new _(b).hostname,O=I===S?Q:{...Q,cookies:void 0,headers:u(Q.headers)};return httpDownload(b,J,O,Z+1)}}if(B.status!==200)return{success:!1,size:0,error:`HTTP ${B.status}`};if(!B.body)return{success:!1,size:0,error:"Empty response body"};const j=parseInt(B.headers.get("content-length")||"0",10);let G=0;const N=new U({transform(V,b,I){G+=V.length;if(q)q(G,j);I(null,V)}});try{await W.promises.mkdir(H.dirname(J),{recursive:!0});await y(v.fromWeb(B.body),N,W.createWriteStream(D));await W.promises.rename(D,J);return{success:!0,size:G}}catch(V){await M();return{success:!1,size:0,error:L(V)}}}catch(B){clearTimeout(X);await M();return{success:!1,size:0,error:B instanceof Error?B.message:String(B)}}}export function resolveRedirectUrl(K,J){return new _(J,K).toString()}function u(K){if(!K)return K;return Object.fromEntries(Object.entries(K).filter(([J])=>J.toLowerCase()!=="cookie"))}export function exportCookiesToNetscape(K,J){const Q=["# Netscape HTTP Cookie File","# https://curl.se/docs/http-cookies.html","# This is a generated file!  Do not edit.",""];for(const $ of K){const Y=$.domain.startsWith(".")?$.domain:`.${$.domain}`,z="TRUE",q=$.path||"/",w=$.secure?"TRUE":"FALSE",A=typeof $.expirationDate==="number"&&$.expirationDate>0?Math.floor($.expirationDate):Math.floor(Date.now()/1000)+31536000,D=$.name.replace(/[\t\n\r]/g,""),M=$.value.replace(/[\t\n\r]/g,"");Q.push(`${Y}	${z}	${q}	${w}	${A}	${D}	${M}`)}W.mkdirSync(H.dirname(J),{recursive:!0});let Z;try{Z=W.openSync(J,W.constants.O_WRONLY|W.constants.O_CREAT|W.constants.O_TRUNC,384);W.fchmodSync(Z,384);W.writeFileSync(Z,Q.join(`
+`),"utf8")}finally{if(Z!==void 0)W.closeSync(Z)}}export function formatCookieHeader(K){return K.map((J)=>`${J.name}=${J.value}`).join("; ")}export async function ytdlpDownload(K,J,Q={}){const{cookiesFile:Z,format:$="best",extraArgs:Y=[],onProgress:z}=Q;if(!checkYtdlp())return{success:!1,size:0,error:"yt-dlp not installed. Install with: pip install yt-dlp"};return new Promise((q)=>{const w=H.dirname(J);W.mkdirSync(w,{recursive:!0});const A=[K,"-o",J,"-f",$,"--no-playlist","--progress"];if(Z)if(W.existsSync(Z))A.push("--cookies",Z);else{g.warn(`[download] Cookies file not found: ${Z}, falling back to browser cookies`);A.push("--cookies-from-browser","chrome")}else A.push("--cookies-from-browser","chrome");A.push(...Y);const D=R("yt-dlp",A,{stdio:["ignore","pipe","pipe"]});let M=0,C="";D.stderr.on("data",(X)=>{const B=X.toString();C+=B;const j=B.match(/(\d+\.?\d*)%/);if(j&&z){const G=parseFloat(j[1]);if(G>M){M=G;z(G)}}});D.stdout.on("data",(X)=>{const j=X.toString().match(/(\d+\.?\d*)%/);if(j&&z){const G=parseFloat(j[1]);if(G>M){M=G;z(G)}}});D.on("close",(X)=>{if(X===0&&W.existsSync(J)){const B=W.statSync(J);q({success:!0,size:B.size})}else{const B=W.readdirSync(w).filter((j)=>j.startsWith(H.basename(J,H.extname(J))));if(B.length>0){const j=H.join(w,B[0]),G=W.statSync(j);q({success:!0,size:G.size})}else q({success:!1,size:0,error:C.slice(0,200)||`Exit code ${X}`})}});D.on("error",(X)=>{q({success:!1,size:0,error:X.message})})})}export async function saveDocument(K,J,Q="markdown",Z){try{const $=H.dirname(J);W.mkdirSync($,{recursive:!0});let Y;if(Q==="json")Y=JSON.stringify({...Z,content:K},null,2);else if(Q==="markdown")Y=(Z?`---
+${Object.entries(Z).map(([q,w])=>`${q}: ${JSON.stringify(w)}`).join(`
+`)}
+---
+
+`:"")+K;else Y=K;W.writeFileSync(J,Y,"utf-8");return{success:!0,size:Buffer.byteLength(Y,"utf-8")}}catch($){return{success:!1,size:0,error:L($)}}}export function sanitizeFilename(K,J=200){return K.replace(/[<>:"/\\|?*\x00-\x1f]/g,"_").replace(/\s+/g,"_").replace(/_+/g,"_").replace(/^_|_$/g,"").slice(0,J)}export function generateFilename(K,J,Q){try{const Z=new _(K),$=Z.pathname,Y=H.basename($);if(Y&&Y!=="/"&&Y.includes("."))return sanitizeFilename(Y);const z=Q||h(K),q=Z.hostname.replace(/^www\./,"");return sanitizeFilename(`${q}_${J+1}${z}`)}catch{const Z=Q||".bin";return`download_${J+1}${Z}`}}function h(K){switch(detectContentType(K)){case"image":return".jpg";case"video":return".mp4";case"document":return".md";default:return".bin"}}export function getTempDir(){return H.join(E.tmpdir(),"opencli-download")}

package/dist/src/download/index.test.d.ts

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

package/dist/src/download/media-download.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Media download helper — shared logic for batch downloading images/videos.
+ *
+ * Used by: xiaohongshu/download, twitter/download, bilibili/download,
+ * and future media adapters.
+ *
+ * Flow: MediaItem[] → DownloadProgressTracker → httpDownload/ytdlpDownload → results
+ */
+import type { BrowserCookie } from '../types.js';
+export interface MediaItem {
+    type: 'image' | 'video' | 'video-tweet' | 'video-ytdlp';
+    url: string;
+    /** Optional custom filename (without directory) */
+    filename?: string;
+}
+export interface MediaDownloadOptions {
+    output: string;
+    /** Subdirectory inside output */
+    subdir?: string;
+    /** Cookie string for HTTP downloads */
+    cookies?: string;
+    /** Raw browser cookies — auto-exported to Netscape for yt-dlp, auto-cleaned up */
+    browserCookies?: BrowserCookie[];
+    /** Timeout in ms (default: 30000 for images, 60000 for videos) */
+    timeout?: number;
+    /** File name prefix (default: 'download') */
+    filenamePrefix?: string;
+    /** Extra yt-dlp args */
+    ytdlpExtraArgs?: string[];
+    /** Whether to show progress (default: true) */
+    verbose?: boolean;
+}
+export interface MediaDownloadResult {
+    index: number;
+    type: string;
+    status: string;
+    size: string;
+}
+/**
+ * Batch download media files with progress tracking.
+ *
+ * Handles:
+ * - DownloadProgressTracker for terminal UX
+ * - Automatic httpDownload vs ytdlpDownload routing via MediaItem.type
+ * - Cookie export to Netscape format for yt-dlp (auto-cleanup)
+ * - Directory creation
+ * - Error handling with per-file results
+ */
+export declare function downloadMedia(items: MediaItem[], options: MediaDownloadOptions): Promise<MediaDownloadResult[]>;