publishport-opencli 1.0.0

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

@@ -0,0 +1 @@
+import*as X from"node:fs";import*as L from"node:path";import{getErrorMessage as D}from"../errors.js";import{httpDownload as F,ytdlpDownload as b,checkYtdlp as B,getTempDir as x,exportCookiesToNetscape as h,sanitizeFilename as g}from"./index.js";import{DownloadProgressTracker as f,formatBytes as j}from"./progress.js";export async function downloadMedia(H,J){const{output:R,subdir:U,cookies:A,browserCookies:O,timeout:Z,filenamePrefix:E="download",ytdlpExtraArgs:C=[],verbose:T=!0}=J;if(!H||H.length===0)return[{index:0,type:"-",status:"failed",size:"No media found"}];const M=U?L.join(R,U):R;X.mkdirSync(M,{recursive:!0});const v=B();let Q;if(H.some((q)=>q.type==="video-tweet"||q.type==="video-ytdlp")&&O&&O.length>0){const q=x();X.mkdirSync(q,{recursive:!0});Q=L.join(q,`media_cookies_${Date.now()}.txt`);h(O,Q)}const W=new f(H.length,T),_=[];try{for(let q=0;q<H.length;q++){const I=H[q],S=I.type!=="image",w=S?"mp4":"jpg",V=k(I.filename,E,q+1,w),Y=L.join(M,V),K=W.onFileStart(V,q);try{let G;if((I.type==="video-tweet"||I.type==="video-ytdlp")&&v)G=await b(I.url,Y,{cookiesFile:Q,extraArgs:C,onProgress:(N)=>{if(K)K.update(N,100)}});else{const N=Z||(S?60000:30000);G=await F(I.url,Y,{cookies:A,timeout:N,onProgress:(P,z)=>{if(K)K.update(P,z)}})}if(K)K.complete(G.success,G.success?j(G.size):void 0);W.onFileComplete(G.success);_.push({index:q+1,type:I.type==="video-tweet"||I.type==="video-ytdlp"?"video":I.type,status:G.success?"success":"failed",size:G.success?j(G.size):G.error||"unknown error"})}catch(G){const $=D(G);if(K)K.fail($);W.onFileComplete(!1);_.push({index:q+1,type:I.type,status:"failed",size:$})}}}finally{W.finish();if(Q&&X.existsSync(Q))X.unlinkSync(Q)}return _}function k(H,J,R,U){const O=`${y(L.basename(L.win32.basename(J)))||"download"}_${R}.${U}`;if(!H)return O;const Z=L.basename(L.win32.basename(H));return y(Z)||O}function y(H){const J=g(H);return J&&J!=="."&&J!==".."?J:""}

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

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

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

@@ -0,0 +1,36 @@
+/**
+ * Download progress display: terminal progress bars, status updates.
+ */
+export interface ProgressBar {
+    update(current: number, total: number, label?: string): void;
+    complete(success: boolean, message?: string): void;
+    fail(error: string): void;
+}
+/**
+ * Format bytes as human-readable string (KB, MB, GB).
+ */
+export declare function formatBytes(bytes: number): string;
+/**
+ * Format milliseconds as human-readable duration.
+ */
+export declare function formatDuration(ms: number): string;
+/**
+ * Create a simple progress bar for terminal display.
+ */
+export declare function createProgressBar(filename: string, index: number, total: number): ProgressBar;
+/**
+ * Multi-file download progress tracker.
+ */
+export declare class DownloadProgressTracker {
+    private completed;
+    private failed;
+    private skipped;
+    private total;
+    private startTime;
+    private verbose;
+    constructor(total: number, verbose?: boolean);
+    onFileStart(filename: string, index: number): ProgressBar | null;
+    onFileComplete(success: boolean, skipped?: boolean): void;
+    getSummary(): string;
+    finish(): void;
+}

package/dist/src/download/progress.js

@@ -0,0 +1,5 @@
+export function formatBytes(j){if(!Number.isFinite(j)||j<1)return"0 B";const q=1024,A=["B","KB","MB","GB","TB"],C=Math.min(A.length-1,Math.floor(Math.log(j)/Math.log(q)));return`${(j/Math.pow(q,C)).toFixed(1)} ${A[C]}`}export function formatDuration(j){if(j<1000)return`${j}ms`;const q=Math.floor(j/1000);if(q<60)return`${q}s`;const A=Math.floor(q/60);if(A<60){const E=q%60;return E>0?`${A}m ${E}s`:`${A}m`}const C=Math.floor(A/60),G=A%60;return G>0?`${C}h ${G}m`:`${C}h`}export function createProgressBar(j,q,A){const C=`[${q+1}/${A}]`,G=j.length>40?j.slice(0,37)+"...":j;return{update(E,F,H){const I=O(F>0?Math.round(E/F*100):0),J=Q(I),K=F>0?formatBytes(F):"",L=H?` ${H}`:"";process.stderr.write(`\r${C} ${G} ${J} ${I}% ${K}${L}`)},complete(E,F){const H=E?"✓":"✗",I=F?` ${F}`:"";process.stderr.write(`\r${C} ${H} ${G}${I}
+`)},fail(E){process.stderr.write(`\r${C} ✗ ${G} ${E}
+`)}}}function O(j){if(!Number.isFinite(j))return 0;return Math.max(0,Math.min(100,j))}function Q(j,q=20){const A=Math.round(j/100*q),C=q-A;return"█".repeat(A)+"░".repeat(C)}export class DownloadProgressTracker{completed=0;failed=0;skipped=0;total;startTime;verbose;constructor(j,q=!0){this.total=j;this.startTime=Date.now();this.verbose=q}onFileStart(j,q){if(!this.verbose)return null;return createProgressBar(j,q,this.total)}onFileComplete(j,q=!1){if(q)this.skipped++;else if(j)this.completed++;else this.failed++}getSummary(){const j=formatDuration(Date.now()-this.startTime),q=[];if(this.completed>0)q.push(`${this.completed} downloaded`);if(this.skipped>0)q.push(`${this.skipped} skipped`);if(this.failed>0)q.push(`${this.failed} failed`);return`${q.join(", ")} in ${j}`}finish(){if(this.verbose)process.stderr.write(`
+Download complete: ${this.getSummary()}
+`)}}

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

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

package/dist/src/electron-apps.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Electron app registry — maps site names to launch metadata.
+ *
+ * Builtin apps are defined here. User-defined apps are loaded
+ * from ~/.opencli/apps.yaml (additive only, does not override builtins).
+ */
+export interface ElectronAppEntry {
+    /** CDP debug port (unique per app) */
+    port: number;
+    /** macOS process name for detection via pgrep */
+    processName: string;
+    /** Candidate executable names inside Contents/MacOS/, tried in order */
+    executableNames?: string[];
+    /** macOS bundle ID for path discovery */
+    bundleId?: string;
+    /** Human-readable name for prompts */
+    displayName?: string;
+    /** Additional launch args beyond --remote-debugging-port */
+    extraArgs?: string[];
+}
+export declare const builtinApps: Record<string, ElectronAppEntry>;
+/** Merge builtin + user-defined apps. User entries are additive only. */
+export declare function loadApps(userApps?: Record<string, Omit<ElectronAppEntry, 'displayName'> & {
+    displayName?: string;
+}>): Record<string, ElectronAppEntry>;
+export declare function getElectronApp(site: string): ElectronAppEntry | undefined;
+export declare function isElectronApp(site: string): boolean;
+/** Get all registered apps (builtin + user-defined). */
+export declare function getAllElectronApps(): Record<string, ElectronAppEntry>;
+/** Reset loaded apps (for testing). */
+export declare function _resetRegistry(): void;

package/dist/src/electron-apps.js

@@ -0,0 +1 @@
+import*as B from"node:fs";import*as C from"node:path";import*as D from"node:os";import E from"js-yaml";export const builtinApps={cursor:{port:9226,processName:"Cursor",bundleId:"com.todesktop.runtime.Cursor",displayName:"Cursor"},codex:{port:9238,processName:"Codex",bundleId:"com.openai.codex",displayName:"Codex"},chatwise:{port:9228,processName:"ChatWise",bundleId:"com.chatwise.app",displayName:"ChatWise"},"discord-app":{port:9232,processName:"Discord",bundleId:"com.discord.app",displayName:"Discord"},"doubao-app":{port:9225,processName:"Doubao",bundleId:"com.volcengine.doubao",displayName:"Doubao"},antigravity:{port:9234,processName:"Antigravity",executableNames:["Electron","Antigravity"],bundleId:"dev.antigravity.app",displayName:"Antigravity"},"chatgpt-app":{port:9236,processName:"ChatGPT",bundleId:"com.openai.chat",displayName:"ChatGPT"},qoder:{port:9237,processName:"Qoder",executableNames:["Electron"],bundleId:"com.qoder.ide",displayName:"Qoder"},"trae-solo":{port:9235,processName:"TRAE SOLO",executableNames:["Electron","TRAE SOLO"],bundleId:"com.trae.solo.app",displayName:"Trae SOLO"},"trae-cn":{port:39240,processName:"Trae CN",executableNames:["Electron"],bundleId:"cn.trae.app",displayName:"Trae CN"}};export function loadApps(k){const q={...builtinApps};if(k){for(const[w,z]of Object.entries(k))if(!(w in q))q[w]=z}return q}let v=null;function x(){if(v)return v;let k;try{const q=C.join(D.homedir(),".opencli","apps.yaml");if(B.existsSync(q)){const w=B.readFileSync(q,"utf-8");k=E.load(w)?.apps}}catch{}v=loadApps(k);return v}export function getElectronApp(k){return x()[k]}export function isElectronApp(k){return k in x()}export function getAllElectronApps(){return x()}export function _resetRegistry(){v=null}

package/dist/src/electron-apps.test.d.ts

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

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

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

package/dist/src/errors.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Unified error types for opencli.
+ *
+ * All errors thrown by the framework should extend CliError so that
+ * the top-level handler in commanderAdapter.ts can render consistent,
+ * helpful output with emoji-coded severity and actionable hints.
+ *
+ * ## Exit codes
+ *
+ * opencli follows Unix conventions (sysexits.h) for process exit codes:
+ *
+ *   0   Success
+ *   1   Generic / unexpected error
+ *   2   Argument / usage error          (ArgumentError)
+ *  66   No input / empty result         (EmptyResultError)
+ *  69   Service unavailable             (BrowserConnectError, adapter load failures)
+ *  75   Temporary failure, retry later  (TimeoutError)   EX_TEMPFAIL
+ *  77   Permission denied / auth needed (AuthRequiredError)
+ *  78   Configuration error             (ConfigError)
+ * 130   Interrupted by Ctrl-C           (set by tui.ts SIGINT handler)
+ */
+import type { ObservationTraceReceipt } from './observation/events.js';
+export declare const EXIT_CODES: {
+    readonly SUCCESS: 0;
+    readonly GENERIC_ERROR: 1;
+    readonly USAGE_ERROR: 2;
+    readonly EMPTY_RESULT: 66;
+    readonly SERVICE_UNAVAIL: 69;
+    readonly TEMPFAIL: 75;
+    readonly NOPERM: 77;
+    readonly CONFIG_ERROR: 78;
+    readonly INTERRUPTED: 130;
+};
+export type ExitCode = typeof EXIT_CODES[keyof typeof EXIT_CODES];
+export declare class CliError extends Error {
+    /** Machine-readable error code (e.g. 'BROWSER_CONNECT', 'AUTH_REQUIRED') */
+    readonly code: string;
+    /** Human-readable hint on how to fix the problem */
+    readonly hint?: string;
+    /** Unix process exit code — defaults to 1 (generic error) */
+    readonly exitCode: ExitCode;
+    constructor(code: string, message: string, hint?: string, exitCode?: ExitCode);
+}
+export declare function attachTraceReceipt(err: unknown, receipt: ObservationTraceReceipt): void;
+export declare function getTraceReceipt(err: unknown): ObservationTraceReceipt | undefined;
+export type BrowserConnectKind = 'daemon-not-running' | 'extension-not-connected' | 'profile-required' | 'profile-disconnected' | 'command-failed' | 'unknown';
+export declare class BrowserConnectError extends CliError {
+    readonly kind: BrowserConnectKind;
+    constructor(message: string, hint?: string, kind?: BrowserConnectKind);
+}
+export declare class CommandExecutionError extends CliError {
+    constructor(message: string, hint?: string);
+}
+export declare class ConfigError extends CliError {
+    constructor(message: string, hint?: string);
+}
+export declare class AuthRequiredError extends CliError {
+    readonly domain: string;
+    constructor(domain: string, message?: string);
+}
+export declare class TimeoutError extends CliError {
+    constructor(label: string, seconds: number, hint?: string);
+}
+export declare class RateLimitError extends CliError {
+    constructor(command: string, retryAfterMs: number, configPath: string);
+}
+export declare class ArgumentError extends CliError {
+    constructor(message: string, hint?: string);
+}
+export declare class EmptyResultError extends CliError {
+    constructor(command: string, hint?: string);
+}
+export declare function adapterLoadError(message: string, hint?: string): CliError;
+export declare function selectorError(selector: string, hint?: string): CliError;
+export declare class PluginError extends CliError {
+    constructor(message: string, hint?: string);
+}
+/**
+ * Thrown when a JSON endpoint returns HTML instead of JSON — typically a login
+ * wall, rate-limit page, or WAF challenge. Surfaced as a structured error so
+ * callers can show "re-login or wait out the rate limit" guidance instead of
+ * the cryptic `SyntaxError: Unexpected token '<', "<!DOCTYPE "...` that a naive
+ * JSON.parse on an HTML body produces.
+ *
+ * `bodyPreview` is the first 100 chars of the response body (after trimming
+ * leading whitespace) — useful for logs / debugging without dumping the full
+ * page.
+ */
+export declare class LoginWallError extends CliError {
+    readonly status: number;
+    readonly url: string;
+    readonly bodyPreview: string;
+    constructor(message: string, status: number, url: string, bodyPreview: string, hint?: string);
+}
+/** Structured error output — unified contract for all consumers (AI agents, scripts, humans). */
+export interface ErrorEnvelope {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+        help?: string;
+        exitCode: number;
+        stack?: string;
+        cause?: string;
+    };
+    trace?: {
+        traceId: string;
+        dir: string;
+        summaryPath: string;
+        receiptPath: string;
+        status: ObservationTraceReceipt['status'];
+    };
+}
+/** Extract a human-readable message from an unknown caught value. */
+export declare function getErrorMessage(error: unknown): string;
+/** Build an ErrorEnvelope from any caught value. */
+export declare function toEnvelope(err: unknown): ErrorEnvelope;

package/dist/src/errors.js

@@ -0,0 +1,2 @@
+export const EXIT_CODES={SUCCESS:0,GENERIC_ERROR:1,USAGE_ERROR:2,EMPTY_RESULT:66,SERVICE_UNAVAIL:69,TEMPFAIL:75,NOPERM:77,CONFIG_ERROR:78,INTERRUPTED:130};export class CliError extends Error{code;hint;exitCode;constructor(j,q,F,G=EXIT_CODES.GENERIC_ERROR){super(q);this.name=new.target.name;this.code=j;this.hint=F;this.exitCode=G}}const J=Symbol.for("opencli.traceReceipt");export function attachTraceReceipt(j,q){if(!j||typeof j!=="object"&&typeof j!=="function")return;try{Object.defineProperty(j,J,{value:q,enumerable:!1,configurable:!0})}catch{}}export function getTraceReceipt(j){if(!j||typeof j!=="object"&&typeof j!=="function")return;return j[J]}export class BrowserConnectError extends CliError{kind;constructor(j,q,F="unknown"){super("BROWSER_CONNECT",j,q,EXIT_CODES.SERVICE_UNAVAIL);this.kind=F}}export class CommandExecutionError extends CliError{constructor(j,q){super("COMMAND_EXEC",j,q,EXIT_CODES.GENERIC_ERROR)}}export class ConfigError extends CliError{constructor(j,q){super("CONFIG",j,q,EXIT_CODES.CONFIG_ERROR)}}export class AuthRequiredError extends CliError{domain;constructor(j,q){super("AUTH_REQUIRED",q??`Not logged in to ${j}`,`Please open Chrome or Chromium and log in to https://${j}`,EXIT_CODES.NOPERM);this.domain=j}}export class TimeoutError extends CliError{constructor(j,q,F){super("TIMEOUT",`${j} timed out after ${q}s`,F??"Try again, or increase timeout with --timeout <seconds> (or OPENCLI_BROWSER_COMMAND_TIMEOUT for the global default)",EXIT_CODES.TEMPFAIL)}}export class RateLimitError extends CliError{constructor(j,q,F){const G=N(q);super("RATE_LIMITED",`Rate limit exceeded for ${j}`,`Retry after ${G}. To change this limit, edit ${F}.`,EXIT_CODES.TEMPFAIL)}}export class ArgumentError extends CliError{constructor(j,q){super("ARGUMENT",j,q,EXIT_CODES.USAGE_ERROR)}}export class EmptyResultError extends CliError{constructor(j,q){super("EMPTY_RESULT",`${j} returned no data`,q??"The page structure may have changed, or you may need to log in",EXIT_CODES.EMPTY_RESULT)}}export function adapterLoadError(j,q){return new CliError("ADAPTER_LOAD",j,q,EXIT_CODES.SERVICE_UNAVAIL)}export function selectorError(j,q){return new CliError("SELECTOR",`Could not find element: ${j}`,q??"The page UI may have changed. Please report this issue.",EXIT_CODES.GENERIC_ERROR)}export class PluginError extends CliError{constructor(j,q){super("PLUGIN",j,q,EXIT_CODES.GENERIC_ERROR)}}function N(j){const q=Math.max(0,Math.ceil(j));if(q<1000)return`${q}ms`;const F=Math.ceil(q/1000);if(F<60)return`${F}s`;const G=Math.ceil(F/60);if(G<60)return`${G}m`;return`${Math.ceil(G/60)}h`}export class LoginWallError extends CliError{status;url;bodyPreview;constructor(j,q,F,G,H){super("LOGIN_WALL",j,H??"The server returned an HTML page instead of JSON — likely a login wall, rate limit, or WAF challenge. Try re-logging in via your browser, or wait a few minutes before retrying.",EXIT_CODES.NOPERM);this.status=q;this.url=F;this.bodyPreview=G}}export function getErrorMessage(j){return j instanceof Error?j.message:String(j)}function K(j,q=0){if(q>10)return"(cause chain truncated)";if(j instanceof Error){const F=[j.message];if(j.cause)F.push(`  caused by: ${K(j.cause,q+1)}`);return F.join(`
+`)}return String(j)}export function toEnvelope(j){const q=j instanceof Error&&j.cause?K(j.cause):void 0,F=getTraceReceipt(j),G=F?{traceId:F.traceId,dir:F.traceDir,summaryPath:F.summaryPath,receiptPath:F.receiptPath,status:F.status}:void 0;if(j instanceof CliError)return{ok:!1,error:{code:j.code,message:j.message,...j.hint?{help:j.hint}:{},exitCode:j.exitCode,...q?{cause:q}:{}},...G?{trace:G}:{}};return{ok:!1,error:{code:"UNKNOWN",message:getErrorMessage(j),exitCode:EXIT_CODES.GENERIC_ERROR,...q?{cause:q}:{}},...G?{trace:G}:{}}}

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

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

package/dist/src/execution.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Command execution: validates args, manages browser sessions, runs commands.
+ *
+ * This is the single entry point for executing any CLI command. It handles:
+ * 1. Argument validation and coercion
+ * 2. Browser session lifecycle (if needed)
+ * 3. Domain pre-navigation for cookie strategies
+ * 4. Timeout enforcement
+ * 5. Lazy-loading of TS modules from manifest
+ * 6. Lifecycle hooks (onBeforeExecute / onAfterExecute)
+ */
+import { type CliCommand, type Arg, type CommandArgs } from './registry.js';
+import { type ObservationExportResult } from './observation/index.js';
+export declare function coerceAndValidateArgs(cmdArgs: Arg[], kwargs: CommandArgs): CommandArgs;
+export declare function executeCommand(cmd: CliCommand, rawKwargs: CommandArgs, debug?: boolean, opts?: {
+    prepared?: boolean;
+    profile?: string;
+    trace?: string;
+    keepTab?: string;
+    windowMode?: string;
+    siteSession?: string;
+    onTraceExport?: (trace: ObservationExportResult) => void;
+}): Promise<unknown>;
+export declare function prepareCommandArgs(cmd: CliCommand, rawKwargs: CommandArgs): CommandArgs;

package/dist/src/execution.js

@@ -0,0 +1,2 @@
+import{getRegistry as i,fullName as R}from"./registry.js";import{pathToFileURL as m}from"node:url";import*as n from"node:crypto";import*as h from"node:fs";import*as t from"node:os";import{executePipeline as b}from"./pipeline/index.js";import{adapterLoadError as d,ArgumentError as F,CommandExecutionError as U,attachTraceReceipt as s,getErrorMessage as f}from"./errors.js";import{shouldUseBrowserSession as o}from"./capabilityRouting.js";import{getBrowserFactory as a,browserSession as r,runWithTimeout as v,DEFAULT_BROWSER_COMMAND_TIMEOUT as e}from"./runtime.js";import{withBrowserSessionLockIf as qq}from"./browser-session-lock.js";import{resolveProfile as Qq}from"./browser/profile.js";import{ensureManagedChrome as Xq}from"./browser/managed-chrome.js";import{generateFingerprintJs as Yq}from"./browser/fingerprint.js";import{CDPBridge as Zq}from"./browser/index.js";import{emitHook as C}from"./hooks.js";import{log as w}from"./logger.js";import{isElectronApp as $q}from"./electron-apps.js";import{probeCDP as Jq,resolveElectronEndpoint as Gq}from"./launcher.js";import{ObservationSession as Hq,exportObservationSession as Vq}from"./observation/index.js";import{resolveAdapterSourcePath as Lq}from"./adapter-source.js";const j=new Map,N=new Map,zq=`${t.homedir()}/.opencli/clis/`;function Wq(q){if(q===void 0||q===null||q===""||q==="off")return"off";if(q==="on"||q==="retain-on-failure")return q;throw new F(`--trace must be one of: off, on, retain-on-failure. Received: "${String(q)}"`)}export function coerceAndValidateArgs(q,Q){const Y={...Q};for(const X of q){const Z=Y[X.name];if(X.required&&(Z===void 0||Z===null||Z===""))throw new F(`Argument "${X.name}" is required.`,X.help??`Provide a value for --${X.name}`);if(Z!==void 0&&Z!==null){if(X.type==="int"||X.type==="number"){const V=Number(Z);if(Number.isNaN(V))throw new F(`Argument "${X.name}" must be a valid number. Received: "${Z}"`);Y[X.name]=V}else if(X.type==="boolean"||X.type==="bool")if(typeof Z==="string"){const V=Z.toLowerCase();if(V==="true"||V==="1")Y[X.name]=!0;else if(V==="false"||V==="0")Y[X.name]=!1;else throw new F(`Argument "${X.name}" must be a boolean (true/false). Received: "${Z}"`)}else Y[X.name]=Boolean(Z);const J=Y[X.name];if(X.choices&&X.choices.length>0){if(!X.choices.map(String).includes(String(J)))throw new F(`Argument "${X.name}" must be one of: ${X.choices.join(", ")}. Received: "${J}"`)}}else if(X.default!==void 0)Y[X.name]=X.default}return Y}async function x(q,Q,Y,X){const Z=q;if(Z._lazy&&Z._modulePath){const J=Z._modulePath;if(J.startsWith(zq)&&j.has(J))try{const z=h.statSync(J),$=N.get(J);if($!==void 0&&z.mtimeMs!==$)j.delete(J)}catch{}if(!j.has(J)){const z=m(J).href,y=import(N.has(J)?`${z}?t=${Date.now()}`:z).then(()=>{try{N.set(J,h.statSync(J).mtimeMs)}catch{}},(K)=>{j.delete(J);throw d(`Failed to load adapter module ${J}: ${f(K)}`,"Check that the adapter file exists and has no syntax errors.")});j.set(J,y)}await j.get(J);const W=i().get(R(q));if(W?.func)return u(W,Q,Y,X);if(W?.pipeline)return b(Q,W.pipeline,{args:Y,debug:X})}if(q.func)return u(q,Q,Y,X);if(q.pipeline)return b(Q,q.pipeline,{args:Y,debug:X});throw new U(`Command ${R(q)} has no func or pipeline`,"This is likely a bug in the adapter definition. Please report this issue.")}function u(q,Q,Y,X){if(q.browser===!1)return q.func(Y,X);if(!Q)throw new U(`Command ${R(q)} requires a browser session but none was provided`);return q.func(Q,Y,X)}function Fq(q){if(q.navigateBefore===!1)return null;if(typeof q.navigateBefore==="string")return q.navigateBefore;return null}function Kq(q,Q){if(!q||!Q)return!1;try{const Y=new URL(q).hostname;return Y===Q||Y.endsWith(`.${Q}`)}catch{return!1}}function Bq(q,Q){if(!Q)return!1;try{const Y=new URL(q),X=Y.hostname===Q||Y.hostname.endsWith(`.${Q}`),Z=Y.pathname===""||Y.pathname==="/";return X&&Z&&Y.search===""&&Y.hash===""}catch{return!1}}async function Iq(q,Q,Y,X){if(Y!=="persistent"||!q.domain)return!0;if(!Bq(X,q.domain))return!0;const Z=await Q.getCurrentUrl?.().catch(()=>null);return!Kq(Z,q.domain)}export async function executeCommand(q,Q,Y=!1,X={}){let Z;try{Z=X.prepared?Q:prepareCommandArgs(q,Q)}catch($){if($ instanceof F)throw $;throw new F(f($))}const J=Nq(q,Z),V=Wq(X.trace),W={command:R(q),args:Z,startedAt:Date.now()};await C("onBeforeExecute",W);let z;try{if(o(q)){const $=$q(q.site),y=Qq(X.profile),K=!$&&y.kind==="managed"?y:null;let O,S,D;if(K){O=await Xq(K.name,K.entry);const L=K.entry.fingerprint;if(L?.enabled)S=Yq(L);const G=K.entry.proxy;if(G?.username)D={username:G.username,password:G.password??""}}else if($){const L=process.env.OPENCLI_CDP_ENDPOINT;if(L){const G=Number(new URL(L).port);if(!await Jq(G))throw new U(`CDP not reachable at ${L}`,"Check that the app is running with --remote-debugging-port and the endpoint is correct.");O=L}else O=await Gq(q.site)}const l=K?Zq:a(q.site),M=!K&&y.kind==="extension"?y.contextId:void 0,c=q,_=jq(q,X.siteSession),k=Oq(q,_),P=Uq(_,X.keepTab),E=Cq(q.defaultWindowMode??"background",X.windowMode);z=await qq(E!=="foreground",()=>r(l,async(L)=>{const G=V==="off"?null:new Hq({scope:{contextId:M??K?.name,session:k,target:L.getActivePage?.(),site:q.site,command:R(q),adapterSourcePath:Lq(c)}});if(G){G.record({stream:"action",name:"command",phase:"start",data:{args:Z}});await L.startNetworkCapture?.().catch(()=>!1)}const I=Fq(q);if(I&&await Iq(q,L,_,I)){G?.record({stream:"action",name:"pre_navigate",phase:"start",data:{url:I}});try{await L.goto(I);G?.record({stream:"action",name:"pre_navigate",phase:"end",data:{url:I}})}catch(H){G?.record({stream:"action",name:"pre_navigate",phase:"error",data:{url:I,error:H instanceof Error?H.message:String(H)}});const B=new U(`Pre-navigation to ${I} failed: ${H instanceof Error?H.message:H}`,"Check that the site is reachable and the browser extension is running.");if(G&&(V==="on"||V==="retain-on-failure")){G.record({stream:"error",message:B.message,stack:B.stack,code:B.code,hint:B.hint});await A(G,L).catch(()=>{});T(G,"failure",B,X.onTraceExport)}throw B}}try{const H=J!==null?J+p:e,B=await v(x(q,L,Z,Y),{timeout:H,label:R(q)});G?.record({stream:"action",name:"command",phase:"end"});if(G&&V==="on"){await A(G,L).catch(()=>{});T(G,"success",void 0,X.onTraceExport)}if(!P)await L.closeWindow?.().catch(()=>{});return B}catch(H){if(G){G.record({stream:"action",name:"command",phase:"error",data:{error:H instanceof Error?H.message:String(H)}});G.record({stream:"error",message:H instanceof Error?H.message:String(H),stack:H instanceof Error?H.stack:void 0});if(V==="on"||V==="retain-on-failure"){await A(G,L).catch(()=>{});T(G,"failure",H,X.onTraceExport)}}if(!P)await L.closeWindow?.().catch(()=>{});throw H}},{session:k,cdpEndpoint:O,contextId:M,windowMode:E,surface:"adapter",siteSession:_,initScript:S,proxyAuth:D}),K?.name)}else if(J!==null){const $=J+p;z=await v(x(q,null,Z,Y),{timeout:$,label:R(q),hint:`Pass a higher --timeout value (currently ${J}s)`})}else z=await x(q,null,Z,Y)}catch($){W.error=$;W.finishedAt=Date.now();await C("onAfterExecute",W);throw $}W.finishedAt=Date.now();await C("onAfterExecute",W,z);return z}async function A(q,Q){const Y=Q.getActivePage?.()??q.scope.target,[X,Z,J,V,W]=await Promise.all([Q.getCurrentUrl?.().catch(()=>null)??Promise.resolve(null),Q.snapshot().catch(()=>{return}),Q.readNetworkCapture?.().catch(()=>[])??Promise.resolve([]),Q.consoleMessages("all").catch(()=>[]),Q.screenshot({format:"png"}).catch(()=>{return})]);if(Z!==void 0||X!==void 0)q.record({stream:"state",url:X,target:Y,snapshot:Z,label:"final"});for(const z of Array.isArray(J)?J:[]){const $=z;q.record({stream:"network",url:String($.url??""),method:typeof $.method==="string"?$.method:void 0,status:typeof $.responseStatus==="number"?$.responseStatus:void 0,contentType:typeof $.responseContentType==="string"?$.responseContentType:void 0,size:typeof $.responseBodyFullSize==="number"?$.responseBodyFullSize:void 0,requestHeaders:$.requestHeaders,responseHeaders:$.responseHeaders,requestBody:$.requestBodyPreview,responseBody:$.responsePreview,ts:typeof $.timestamp==="number"?$.timestamp:void 0})}for(const z of Array.isArray(V)?V:[])if(z&&typeof z==="object"){const $=z;q.record({stream:"console",level:String($.type??$.level??"log"),text:String($.text??$.message??""),ts:typeof $.timestamp==="number"?$.timestamp:void 0})}else q.record({stream:"console",level:"log",text:String(z)});if(typeof W==="string"&&W)q.record({stream:"screenshot",format:"png",data:W,label:"final"})}function T(q,Q,Y,X){try{const Z=Vq(q,{error:Y,status:Q});if(Q==="failure"&&Y!==void 0)s(Y,Z.receipt);else process.stderr.write(`OpenCLI trace artifact: ${Z.dir}
+`);try{X?.(Z)}catch(J){w.warn(`[trace] Trace export callback failed: ${J instanceof Error?J.message:String(J)}`)}return Z}catch(Z){w.warn(`[trace] Failed to export trace artifact: ${Z instanceof Error?Z.message:String(Z)}`);return}}export function prepareCommandArgs(q,Q){const Y=coerceAndValidateArgs(q.args,Q);q.validateArgs?.(Y);return Y}const p=30;function Rq(q){if(q===void 0||q===null||q==="")return null;if(q==="ephemeral"||q==="persistent")return q;throw new F(`--site-session must be one of: ephemeral, persistent. Received: "${String(q)}"`)}function yq(){const q=process.env.PUBLISHPORT_SITE_SESSION;if(q==="persistent"||q==="ephemeral")return q;return null}function jq(q,Q){return Rq(Q)??yq()??q.siteSession??"persistent"}function Oq(q,Q){if(Q==="persistent")return`site:${q.site}`;return`site:${q.site}:${n.randomUUID()}`}function _q(q,Q){if(Q===void 0||Q==="")return null;if(Q==="true")return!0;if(Q==="false")return!1;throw new F(`${q} must be one of: true, false. Received: "${String(Q)}"`)}function Uq(q,Q){if(q==="persistent")return!0;return _q("--keep-tab",Q)??!1}function g(q,Q){if(Q===void 0||Q==="")return null;if(Q==="foreground"||Q==="background")return Q;throw new F(`${q} must be one of: foreground, background. Received: "${String(Q)}"`)}function Cq(q="background",Q){return g("--window",Q)??g("OPENCLI_WINDOW",process.env.OPENCLI_WINDOW)??q}function Nq(q,Q){if(!q.args.some((Z)=>Z.name==="timeout"))return null;const Y=Q.timeout;if(Y===void 0||Y===null||Y==="")throw new F(`Argument "timeout" must be a positive integer. Received: "${String(Y)}"`);const X=Number(Y);if(!Number.isInteger(X)||X<=0)throw new F(`Argument "timeout" must be a positive integer. Received: "${String(Y)}"`);return X}

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

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

package/dist/src/extension-manifest-regression.test.d.ts

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

package/dist/src/external-clis.yaml

@@ -0,0 +1,109 @@
+- name: gh
+  binary: gh
+  description: "GitHub CLI — repos, PRs, issues, releases, gists"
+  homepage: "https://cli.github.com"
+  tags: [github, git, dev]
+  install:
+    mac: "brew install gh"
+
+- name: obsidian
+  binary: obsidian
+  description: "Obsidian vault management — notes, search, tags, tasks, sync"
+  homepage: "https://obsidian.md/help/cli"
+  tags: [notes, knowledge, markdown]
+  install:
+    mac: "brew install --cask obsidian"
+
+- name: ntn
+  binary: ntn
+  package: notion
+  description: "Notion CLI — official Notion API CLI for pages, databases, blocks, search, comments"
+  homepage: "https://ntn.dev"
+  tags: [notion, notes, knowledge, productivity]
+
+- name: docker
+  binary: docker
+  description: "Docker command-line interface"
+  homepage: "https://docs.docker.com/engine/reference/commandline/cli/"
+  tags: [docker, containers, devops]
+  install:
+    mac: "brew install --cask docker"
+
+- name: lark-cli
+  binary: lark-cli
+  description: "Lark/Feishu CLI — messages, documents, spreadsheets, calendar, tasks and 200+ commands for AI agents"
+  homepage: "https://github.com/larksuite/cli"
+  tags: [lark, feishu, collaboration, productivity, ai-agent]
+  install:
+    default: "npm install -g @larksuite/cli"
+
+- name: longbridge
+  binary: longbridge
+  description: "Longbridge CLI — AI-native market data, account management and trading commands for Longbridge OpenAPI"
+  homepage: "https://open.longbridge.com/zh-CN/docs/cli/"
+  tags: [longbridge, finance, trading, market-data, openapi, ai-agent]
+  install:
+    mac: "brew install --cask longbridge/tap/longbridge-terminal"
+    windows: "scoop install https://open.longbridge.com/longbridge/longbridge-terminal/longbridge.json"
+
+- name: dws
+  binary: dws
+  package: DingTalk Workspace
+  description: "DingTalk Workspace CLI — messages, docs, calendar, contacts and more for humans and AI agents"
+  homepage: "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli"
+  tags: [dingtalk, collaboration, productivity, ai-agent]
+  install:
+    mac: "npm install -g dingtalk-workspace-cli"
+    linux: "npm install -g dingtalk-workspace-cli"
+
+- name: wecom-cli
+  binary: wecom-cli
+  package: 企业微信
+  description: "WeCom/企业微信 CLI — contacts, todos, meetings, messages, calendar, docs and smart sheets for AI agents"
+  homepage: "https://github.com/WecomTeam/wecom-cli"
+  tags: [wecom, wechat-work, collaboration, productivity, ai-agent]
+  install:
+    default: "npm install -g @wecom/cli"
+
+- name: vercel
+  binary: vercel
+  description: "Vercel CLI — deploy projects, manage domains, env vars, logs and serverless functions"
+  homepage: "https://vercel.com/docs/cli"
+  tags: [vercel, deployment, serverless, frontend, devops]
+  install:
+    default: "npm install -g vercel"
+
+- name: tg
+  binary: tg
+  package: tg-cli
+  description: "Telegram CLI — local-first sync, search, export via MTProto for AI agents"
+  homepage: "https://github.com/jackwener/tg-cli"
+  tags: [telegram, messaging, search, export, ai-agent]
+  install:
+    default: "uv tool install kabi-tg-cli"
+
+- name: discord
+  binary: discord
+  package: discord-cli
+  description: "Discord CLI — local-first sync, search, export via SQLite for AI agents"
+  homepage: "https://github.com/jackwener/discord-cli"
+  tags: [discord, messaging, search, export, ai-agent]
+  install:
+    default: "uv tool install kabi-discord-cli"
+
+- name: wx
+  binary: wx
+  package: wx-cli
+  description: "WeChat local data CLI — sessions, messages, search, contacts, export for AI agents"
+  homepage: "https://github.com/jackwener/wx-cli"
+  tags: [wechat, messaging, search, export, ai-agent]
+  install:
+    default: "npm install -g @jackwener/wx-cli"
+
+- name: wrangler
+  binary: wrangler
+  description: "Cloudflare Wrangler — deploy Workers, manage R2/D1/KV, publish Pages"
+  homepage: "https://developers.cloudflare.com/workers/wrangler/"
+  tags: [cloudflare, workers, serverless, edge, deployment]
+  install:
+    default: "npm install -g wrangler"

package/dist/src/external.d.ts

@@ -0,0 +1,49 @@
+export interface ExternalCliInstall {
+    mac?: string;
+    linux?: string;
+    windows?: string;
+    default?: string;
+}
+export interface ExternalCliConfig {
+    /** User-facing OpenCLI subcommand and, by default, the executable name. */
+    name: string;
+    binary: string;
+    /**
+     * Display alias rendered alongside `name` in help/listing as `name(package)`.
+     * Use either the upstream distribution/project name (e.g. `tg-cli`, `discord-cli`)
+     * or a human-readable brand label (e.g. `notion`, `企业微信`) when the bare
+     * executable name is ambiguous.
+     */
+    package?: string;
+    description?: string;
+    homepage?: string;
+    tags?: string[];
+    install?: ExternalCliInstall;
+}
+export declare function loadExternalClis(): ExternalCliConfig[];
+export declare function isBinaryInstalled(binary: string): boolean;
+export declare function getInstallCmd(installConfig?: ExternalCliInstall): string | null;
+export declare function formatExternalCliLabel(cli: ExternalCliConfig): string;
+/**
+ * Safely parses a command string into a binary and argument list.
+ * Rejects commands containing shell operators (&&, ||, |, ;, >, <, `) that
+ * cannot be safely expressed as execFileSync arguments.
+ *
+ * Args:
+ *   cmd: Raw command string from YAML config (e.g. "brew install gh")
+ *
+ * Returns:
+ *   Object with `binary` and `args` fields, or throws on unsafe input.
+ */
+export declare function parseCommand(cmd: string): {
+    binary: string;
+    args: string[];
+};
+export declare function installExternalCli(cli: ExternalCliConfig): boolean;
+export declare function executeExternalCli(name: string, args: string[], preloaded?: ExternalCliConfig[]): void;
+export interface RegisterOptions {
+    binary?: string;
+    install?: string;
+    description?: string;
+}
+export declare function registerExternalCli(name: string, opts?: RegisterOptions): void;

package/dist/src/external.js

@@ -0,0 +1 @@
+import*as Q from"node:fs";import*as Y from"node:path";import*as V from"node:os";import{fileURLToPath as M}from"node:url";import{spawnSync as U,execFileSync as L}from"node:child_process";import $ from"js-yaml";import{log as K}from"./logger.js";import{EXIT_CODES as v,getErrorMessage as W}from"./errors.js";import{enforceRateLimit as j}from"./rate-limit.js";const O=Y.dirname(M(import.meta.url));function k(){const q=V.homedir();return Y.join(q,".opencli","external-clis.yaml")}let Z=null;export function loadExternalClis(){if(Z)return Z;const q=new Map,z=Y.resolve(O,"external-clis.yaml");try{if(Q.existsSync(z)){const H=Q.readFileSync(z,"utf8"),A=$.load(H)||[];for(const J of A)q.set(J.name,J)}}catch(H){K.warn(`Failed to parse built-in external-clis.yaml: ${W(H)}`)}const G=k();try{if(Q.existsSync(G)){const H=Q.readFileSync(G,"utf8"),A=$.load(H)||[];for(const J of A)q.set(J.name,J)}}catch(H){K.warn(`Failed to parse user external-clis.yaml: ${W(H)}`)}Z=Array.from(q.values()).sort((H,A)=>H.name.localeCompare(A.name));return Z}export function isBinaryInstalled(q){try{const z=V.platform()==="win32";L(z?"where":"which",[q],{stdio:"ignore"});return!0}catch{return!1}}export function getInstallCmd(q){if(!q)return null;const z=V.platform();if(z==="darwin"&&q.mac)return q.mac;if(z==="linux"&&q.linux)return q.linux;if(z==="win32"&&q.windows)return q.windows;if(q.default)return q.default;return null}export function formatExternalCliLabel(q){return q.package&&q.package!==q.name?`${q.name}(${q.package})`:q.name}export function parseCommand(q){if(/&&|\|\|?|;|[><`$#\n\r]|\$\(/.test(q))throw Error(`Install command contains unsafe shell operators and cannot be executed securely: "${q}". Please install the tool manually.`);const G=[],H=/(?:"([^"]*)")|(?:'([^']*)')|(\S+)/g;let A;while((A=H.exec(q))!==null)G.push(A[1]??A[2]??A[3]);if(G.length===0)throw Error("Install command is empty.");const[J,...N]=G;return{binary:J,args:N}}function X(q,z){const G=z instanceof Error?z.code:void 0;return V.platform()==="win32"&&!Y.extname(q)&&G==="ENOENT"}function R(q){const{binary:z,args:G}=parseCommand(q);try{L(z,G,{stdio:"inherit"})}catch(H){if(X(z,H)){L(`${z}.cmd`,G,{stdio:"inherit"});return}throw H}}export function installExternalCli(q){if(!q.install){K.error(`No auto-install command configured for '${q.name}'.`);K.info(`Please install '${q.binary}' manually.`);return!1}const z=getInstallCmd(q.install);if(!z){K.error(`No install command for your platform (${V.platform()}) for '${q.name}'.`);if(q.homepage)K.info(`See: ${q.homepage}`);return!1}K.info(`'${q.name}' is not installed. Auto-installing...`);K.verbose(`$ ${z}`);try{R(z);K.success(`Installed '${q.name}' successfully.`);return!0}catch(G){K.error(`Failed to install '${q.name}': ${W(G)}`);return!1}}export function executeExternalCli(q,z,G){const A=(G??loadExternalClis()).find((N)=>N.name===q);if(!A)throw Error(`External CLI '${q}' not found in registry.`);j(q);if(!isBinaryInstalled(A.binary)){if(!installExternalCli(A)){process.exitCode=v.SERVICE_UNAVAIL;return}}const J=U(A.binary,z,{stdio:"inherit"});if(J.error){K.error(`Failed to execute '${A.binary}': ${J.error.message}`);process.exitCode=v.GENERIC_ERROR;return}if(J.status!==null)process.exitCode=J.status;else if(J.signal){const N=J.signal;process.exitCode=N==="SIGINT"?v.INTERRUPTED:V.constants.signals[N]?128+V.constants.signals[N]:v.GENERIC_ERROR}}export function registerExternalCli(q,z){const G=k(),H=Y.dirname(G);if(!Q.existsSync(H))Q.mkdirSync(H,{recursive:!0});let A=[];if(Q.existsSync(G))try{const B=Q.readFileSync(G,"utf8");A=$.load(B)||[]}catch{}const J=A.findIndex((B)=>B.name===q),N={name:q,binary:z?.binary||q};if(z?.description)N.description=z.description;if(z?.install)N.install={default:z.install};if(J>=0){A[J]={...A[J],...N};K.success(`Updated '${q}' in user registry.`)}else{A.push(N);K.success(`Registered '${q}' in user registry.`)}const F=$.dump(A,{indent:2,sortKeys:!0});Q.writeFileSync(G,F,"utf8");Z=null;K.verbose(G)}

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

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

package/dist/src/help.d.ts

@@ -0,0 +1,88 @@
+import { Command } from 'commander';
+import type { CliCommand } from './registry.js';
+export type StructuredHelpFormat = 'yaml' | 'json';
+export interface ArgSpec {
+    name: string;
+    required?: true;
+    variadic?: true;
+    help?: string;
+    default?: unknown;
+    choices?: string[];
+}
+export interface OptionSpec {
+    name: string;
+    flags: string;
+    help?: string;
+    takes_value?: 'required' | 'optional';
+    required?: true;
+    default?: unknown;
+    choices?: string[];
+    negate?: true;
+}
+export declare function getRequestedHelpFormat(argv?: readonly string[]): StructuredHelpFormat | undefined;
+export declare function renderStructuredHelp(data: unknown, format: StructuredHelpFormat): string;
+export declare function wrapCommaList(items: readonly string[], opts?: {
+    width?: number;
+    indent?: string;
+}): string;
+/**
+ * Adapter category for help-text grouping.
+ *
+ * - `site`: web site adapter (real DNS-style domain, e.g. `www.bilibili.com`)
+ * - `app`: desktop app adapter (Electron/osascript, signaled by `domain: 'localhost'`
+ *   or other non-DNS/local endpoint string like `'127.0.0.1'` / `'doubao-app'`)
+ *
+ * Classification is derived from the adapter's `domain` field — no new schema
+ * required. Adapters without a `domain` field default to `site` (most are
+ * public web scrapers).
+ */
+export type AdapterKind = 'site' | 'app';
+export declare function classifyAdapter(domain: string | undefined): AdapterKind;
+export interface RootAdapterGroups {
+    /** Externally-registered CLIs (docker, gh, vercel, ...) — passthrough binaries */
+    external: readonly RootExternalCli[];
+    /** Desktop-app adapters (chatgpt-app, chatwise, codex, ...) */
+    apps: readonly string[];
+    /** Web-site adapters (bilibili, dianping, ...) */
+    sites: readonly string[];
+}
+export interface RootExternalCli {
+    name: string;
+    label: string;
+}
+export declare function formatRootAdapterHelpText(groups: RootAdapterGroups): string;
+/**
+ * Extracts a positional placeholder that should appear immediately after this
+ * command's name in user-facing path strings. Reads the leading positional
+ * (e.g. `<session>`) from a `.usage()` override; commands without a positional
+ * override return `null` so the path stays as-is.
+ *
+ * Example: `browser` declares `.usage('<session> <command> [options]')`,
+ * so `commanderPath(browserClickCmd)` becomes
+ * `['opencli', 'browser', '<session>', 'click']`.
+ */
+export declare function leadingPositionalFromUsage(command: Command): string | null;
+export declare function commanderNamespaceHelpData(namespaceRoot: Command, opts?: {
+    globalCommand?: Command;
+    description?: string;
+}): Record<string, unknown>;
+export declare function commanderCommandHelpData(namespaceRoot: Command, command: Command, opts?: {
+    globalCommand?: Command;
+}): Record<string, unknown>;
+export declare function commanderGroupHelpData(namespaceRoot: Command, groupCommand: Command, opts?: {
+    globalCommand?: Command;
+}): Record<string, unknown>;
+export declare function installCommanderNamespaceStructuredHelp(namespaceRoot: Command, opts?: {
+    globalCommand?: Command;
+    description?: string;
+}): void;
+export declare function formatCommandListTerm(cmd: CliCommand): string;
+export declare function rootHelpData(program: Command, groups: RootAdapterGroups): Record<string, unknown>;
+export declare function siteHelpData(site: string, commands: readonly CliCommand[]): Record<string, unknown>;
+export declare function commandHelpData(cmd: CliCommand): Record<string, unknown>;
+export declare function formatCommonOptionsHelpText(): string;
+export declare function formatBrowserCommonOptionsHelpText(): string;
+export declare function formatSiteHelpText(site: string, commands: readonly CliCommand[]): string;
+export declare function formatCommandHelpText(cmd: CliCommand): string;
+export declare function installStructuredHelp(command: Command, data: () => unknown, textSuffix?: string | (() => string)): void;
+export declare function formatSiteCommandDescription(cmd: CliCommand): string;

package/dist/src/help.js

@@ -0,0 +1,8 @@
+import w from"js-yaml";import{fullName as N}from"./registry.js";import{formatCommandExample as k}from"./serialization.js";const I=[{flags:"-f, --format <fmt>",name:"format",help:"Output format: table, plain, json, yaml, md, csv",default:"table",choices:["table","plain","json","yaml","md","csv"]},{flags:"--trace <mode>",name:"trace",help:"Trace capture: off, on, retain-on-failure",default:"off",choices:["off","on","retain-on-failure"]},{flags:"-v, --verbose",name:"verbose",help:"Debug output",default:!1},{flags:"-h, --help",name:"help",help:"display help for command"}],E=[{flags:"--window <mode>",name:"window",help:"Browser window mode: foreground or background",choices:["foreground","background"]},{flags:"--site-session <mode>",name:"site-session",help:"Adapter site session lifecycle: ephemeral or persistent",choices:["ephemeral","persistent"]},{flags:"--keep-tab <bool>",name:"keep-tab",help:"Keep the browser tab lease after the command finishes",choices:["true","false"]}];function _(j){const y=j?.toLowerCase();if(y==="yaml"||y==="yml")return"yaml";if(y==="json")return"json";return}export function getRequestedHelpFormat(j=process.argv){for(let y=0;y<j.length;y++){const G=j[y];if(G==="-f"||G==="--format")return _(j[y+1]);if(G.startsWith("--format="))return _(G.slice(9));if(G.startsWith("-f")&&G.length>2)return _(G.slice(2))}return}export function renderStructuredHelp(j,y){if(y==="json")return`${JSON.stringify(j,null,2)}
+`;return w.dump(j,{sortKeys:!1,lineWidth:120,noRefs:!0})}export function wrapCommaList(j,y={}){const G=Math.max(y.width??process.stdout.columns??100,40),K=y.indent??"  ",J=[...j].sort((Z,A)=>Z.localeCompare(A)),Q=[];let V=K;J.forEach((Z,A)=>{const D=`${Z}${A<J.length-1?",":""}`,q=V===K?"":" ";if(V.length+q.length+D.length>G&&V.trim()){Q.push(V);V=`${K}${D}`}else V+=`${q}${D}`});if(V.trim())Q.push(V);return Q.join(`
+`)}function h(j){if(j==="::1"||j==="[::1]")return!0;const y=j.split(".");if(y.length!==4)return!1;return y.every((G)=>/^\d+$/.test(G)&&Number(G)>=0&&Number(G)<=255)&&Number(y[0])===127}export function classifyAdapter(j){if(!j)return"site";if(h(j))return"app";return j.includes(".")?"site":"app"}function F(j,y){if(y.length===0)return[];return[`${j} (${y.length}):`,wrapCommaList(y),""]}export function formatRootAdapterHelpText(j){if(j.external.length+j.apps.length+j.sites.length===0)return"";const G=[""];G.push(...F("External CLIs",j.external.map((K)=>K.label)));G.push(...F("App adapters",j.apps));G.push(...F("Site adapters",j.sites));G.push("Run 'opencli list' for full command details, or 'opencli <site> --help' to inspect one site.");G.push("Agent tip: use 'opencli <site> --help -f yaml' for all command args/options in one structured response.");G.push("");return G.join(`
+`)}function H(j){return{name:j.name,...j.type&&j.type!=="string"?{type:j.type}:{},...j.positional?{positional:!0}:{},...j.required?{required:!0}:{},...j.valueRequired?{valueRequired:!0}:{},...j.default!==void 0?{default:j.default}:{},...j.choices?.length?{choices:j.choices}:{},...j.help?{help:j.help}:{}}}function $(j){return{name:j.name,flags:j.flags,help:j.help,..."default"in j?{default:j.default}:{},..."choices"in j?{choices:j.choices}:{}}}function x(j){return{name:j.name(),...j.required?{required:!0}:{},...j.variadic?{variadic:!0}:{},...j.description?{help:j.description}:{},...j.defaultValue!==void 0?{default:j.defaultValue}:{},...j.argChoices?.length?{choices:[...j.argChoices]}:{}}}function f(j){if(j.hidden)return null;return{name:j.attributeName(),flags:j.flags,...j.description?{help:j.description}:{},...j.required?{takes_value:"required"}:{},...j.optional?{takes_value:"optional"}:{},...j.mandatory?{required:!0}:{},...j.defaultValue!==void 0?{default:j.defaultValue}:{},...j.argChoices?.length?{choices:[...j.argChoices]}:{},...j.negate?{negate:!0}:{}}}function W(j){return j.map(f).filter((y)=>y!==null)}export function leadingPositionalFromUsage(j){const y=j._usage;if(!y)return null;const G=y.match(/^\s*(<[^>]+>)/);return G?G[1]:null}function X(j){const y=[];let G=j;while(G){const K=G.name();if(K){y.push(K);const J=leadingPositionalFromUsage(G);if(J&&y.length>1)y.splice(y.length-1,0,J)}G=G.parent}return y.reverse()}function Y(j,y){const G=X(j);return X(y).slice(G.length).filter((J)=>!/^<.+>$/.test(J))}function z(j){if(j.commands.length===0)return[j];return j.commands.flatMap((y)=>z(y))}function b(j){return j.commands.flatMap((y)=>[y,...b(y)])}function O(j){return j.map((y)=>{const G=`${y.name()}${y.variadic?"...":""}`;return y.required?`<${G}>`:`[${G}]`}).join(" ")}function C(j,y={}){const G=X(j).join(" "),K=O(j.registeredArguments),Q=W(j.options).length>0||(y.namespaceRoot?W(y.namespaceRoot.options).length>0:!1)||(y.globalCommand?W(y.globalCommand.options).length>0:!1)?" [options]":"";return`${G}${K?` ${K}`:""}${Q}`}function L(j,y,G={}){return{name:Y(j,y).join(" "),command:X(y).join(" "),usage:C(y,{namespaceRoot:j,globalCommand:G.globalCommand}),description:y.description(),...y.aliases().length?{aliases:y.aliases()}:{},positionals:y.registeredArguments.map(x),command_options:W(y.options)}}export function commanderNamespaceHelpData(j,y={}){const G=z(j).filter((V)=>V!==j).sort((V,Z)=>Y(j,V).join(" ").localeCompare(Y(j,Z).join(" "))),K=X(j).join(" "),J=j._usage,Q=J?`${K} ${J}`:`${K} <command> [args] [options]`;return{namespace:j.name(),command:K,usage:Q,description:y.description??j.description(),command_count:G.length,commands:G.map((V)=>L(j,V,y)),namespace_options:W(j.options),...y.globalCommand?{global_options:W(y.globalCommand.options)}:{},structured_help:{formats:["yaml","json"],usage:`${K} --help -f yaml`}}}export function commanderCommandHelpData(j,y,G={}){return{namespace:j.name(),...L(j,y,G),namespace_options:W(j.options),...G.globalCommand?{global_options:W(G.globalCommand.options)}:{},structured_help:{formats:["yaml","json"],usage:`${X(y).join(" ")} --help -f yaml`}}}export function commanderGroupHelpData(j,y,G={}){const K=z(y).filter((J)=>J!==y).sort((J,Q)=>Y(j,J).join(" ").localeCompare(Y(j,Q).join(" ")));return{namespace:j.name(),group:Y(j,y).join(" "),command:X(y).join(" "),usage:`${X(y).join(" ")} <command> [args] [options]`,description:y.description(),command_count:K.length,commands:K.map((J)=>L(j,J,G)),namespace_options:W(j.options),...G.globalCommand?{global_options:W(G.globalCommand.options)}:{},structured_help:{formats:["yaml","json"],usage:`${X(y).join(" ")} --help -f yaml`}}}export function installCommanderNamespaceStructuredHelp(j,y={}){installStructuredHelp(j,()=>commanderNamespaceHelpData(j,y));for(const G of b(j))if(G.commands.length>0)installStructuredHelp(G,()=>commanderGroupHelpData(j,G,y));else installStructuredHelp(G,()=>commanderCommandHelpData(j,G,y))}function U(j){return j.args.filter((y)=>y.positional)}function M(j){return j.args.filter((y)=>!y.positional)}function v(j){return j.map((y)=>y.required?`<${y.name}>`:`[${y.name}]`).join(" ")}function R(j){if(j.required||j.valueRequired)return`--${j.name} <value>`;return`--${j.name} [value]`}export function formatCommandListTerm(j){const y=v(U(j)),G=M(j).length>0?" [options]":"";return`${j.name}${y?` ${y}`:""}${G}`}function T(j){const y=v(U(j));return`opencli ${j.site} ${j.name}${y?` ${y}`:""} [options]`}function S(j){return{name:j.name,command:`opencli ${j.site} ${j.name}`,usage:T(j),access:j.access,description:j.description,browser:!!j.browser,...j.domain?{domain:j.domain}:{},...j.aliases?.length?{aliases:j.aliases}:{},positionals:U(j).map(H),command_options:M(j).map(H),...j.browser?{browser_common_options:E.map($)}:{},example:k(j),...j.siteSession?{siteSession:j.siteSession}:{},...j.defaultFormat?{defaultFormat:j.defaultFormat}:{},...j.columns?.length?{columns:j.columns}:{}}}export function rootHelpData(j,y){const G=new Set([...y.external.map((Q)=>Q.name),...y.apps,...y.sites]),K=j.commands.filter((Q)=>!G.has(Q.name())).map((Q)=>({name:Q.name(),description:Q.description()})),J=(Q,V)=>Q.localeCompare(V);return{name:j.name(),description:j.description(),commands:K,external_clis:{count:y.external.length,clis:y.external.map((Q)=>Q.name).sort(J),display:y.external.map((Q)=>Q.label).sort(J)},app_adapters:{count:y.apps.length,apps:[...y.apps].sort(J)},site_adapters:{count:y.sites.length,sites:[...y.sites].sort(J)},next:["opencli <site> --help -f yaml","opencli list -f yaml","opencli <site> <command> -f yaml"]}}export function siteHelpData(j,y){const G=[...new Map(y.map((K)=>[N(K),K])).values()].sort((K,J)=>K.name.localeCompare(J.name));return{site:j,command_count:G.length,commands:G.map((K)=>S(K)),common_options:I.map($),...G.some((K)=>K.browser)?{browser_common_options:E.map($)}:{},next:[`opencli ${j} <command> --help -f yaml`,`opencli ${j} <command> -f yaml`]}}export function commandHelpData(j){return{site:j.site,...S(j),common_options:I.map($),...j.browser?{browser_common_options:E.map($)}:{},output_formats:["table","plain","yaml","json","md","csv"]}}function B(j){if(j.length===0)return[];const y=Math.min(Math.max(...j.map(([G])=>G.length)),34);return j.map(([G,K])=>`  ${G.padEnd(y+2)}${K}`)}function P(j){const y=[];if(j.help)y.push(j.help);if(j.default!==void 0)y.push(`default: ${j.default}`);if(j.choices?.length)y.push(`choices: ${j.choices.join(", ")}`);return y.join("  ")}export function formatCommonOptionsHelpText(){const j=I.map((y)=>{const G=[y.help];if("default"in y)G.push(`default: ${y.default}`);if("choices"in y)G.push(`choices: ${y.choices.join(", ")}`);return[y.flags,G.join("  ")]});return["Common options:",...B(j)].join(`
+`)}export function formatBrowserCommonOptionsHelpText(){const j=E.map((y)=>{const G=[y.help];if("choices"in y)G.push(`choices: ${y.choices.join(", ")}`);return[y.flags,G.join("  ")]});return["Browser common options:",...B(j)].join(`
+`)}export function formatSiteHelpText(j,y){const G=[...new Map(y.map((J)=>[N(J),J])).values()].sort((J,Q)=>J.name.localeCompare(Q.name));return[`Usage: opencli ${j} <command> [args] [options]`,"",wrapCommaList(G.map((J)=>J.name),{indent:""}),"","Commands:",...B(G.map((J)=>[formatCommandListTerm(J),formatSiteCommandDescription(J)])),"",formatCommonOptionsHelpText(),...G.some((J)=>J.browser)?["",formatBrowserCommonOptionsHelpText()]:[],"",`Agent tip: use 'opencli ${j} --help -f yaml' to get all command args/options in one structured response.`,""].join(`
+`)}export function formatCommandHelpText(j){const y=[`Usage: ${T(j)}`,"",j.description,""],G=U(j).map((Q)=>[Q.name,P(Q)]);if(G.length)y.push("Arguments:",...B(G),"");const K=M(j).map((Q)=>[R(Q),P(Q)]);if(K.length)y.push("Command options:",...B(K),"");y.push(formatCommonOptionsHelpText(),"");if(j.browser)y.push(formatBrowserCommonOptionsHelpText(),"");const J=[];J.push(`Access: ${j.access}`);J.push(`Browser: ${j.browser?"yes":"no"}`);if(j.domain)J.push(`Domain: ${j.domain}`);if(j.defaultFormat)J.push(`Default format: ${j.defaultFormat}`);if(j.aliases?.length)J.push(`Aliases: ${j.aliases.join(", ")}`);y.push(J.join(" | "));y.push(`Example: ${k(j)}`);if(j.columns?.length)y.push(`Output columns: ${j.columns.join(", ")}`);y.push("Agent tip: use '--help -f yaml' for structured args/options.");y.push("");return y.join(`
+`)}export function installStructuredHelp(j,y,G){const K=j.helpInformation.bind(j);j.helpInformation=(J)=>{const Q=getRequestedHelpFormat();if(Q)return renderStructuredHelp(y(),Q);const V=typeof G==="function"?G():G??"";return K(J)+V}}export function formatSiteCommandDescription(j){return`${j.access==="write"?"[write]":"[read]"} ${j.description}`}

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

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