publishport-opencli 1.0.0

package/dist/src/hooks.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Plugin lifecycle hooks: allows plugins to tap into opencli's execution lifecycle.
+ *
+ * Hooks use globalThis (like the command registry) to guarantee a single shared
+ * instance across all module copies — critical when TS plugins are loaded via
+ * npm link / peerDependency symlinks.
+ *
+ * Available hooks:
+ *   onStartup        — fired once after all commands & plugins are discovered
+ *   onBeforeExecute  — fired before every command execution
+ *   onAfterExecute   — fired after every command execution (receives result)
+ */
+export type HookName = 'onStartup' | 'onBeforeExecute' | 'onAfterExecute';
+export interface HookContext {
+    /** Command full name in "site/name" format, or "__startup__" for onStartup */
+    command: string;
+    /** Coerced and validated arguments */
+    args: Record<string, unknown>;
+    /** Epoch ms when execution started (set by executeCommand) */
+    startedAt?: number;
+    /** Epoch ms when execution finished (set by executeCommand) */
+    finishedAt?: number;
+    /** Error thrown by the command, if execution failed */
+    error?: unknown;
+    /** Plugins can attach arbitrary data here for cross-hook communication */
+    [key: string]: unknown;
+}
+export type HookFn = (ctx: HookContext, result?: unknown) => void | Promise<void>;
+declare global {
+    var __opencli_hooks__: Map<HookName, HookFn[]> | undefined;
+}
+/** Register a hook that fires once after all plugins are discovered. */
+export declare function onStartup(fn: HookFn): void;
+/** Register a hook that fires before every command execution. */
+export declare function onBeforeExecute(fn: HookFn): void;
+/** Register a hook that fires after every command execution with the result. */
+export declare function onAfterExecute(fn: HookFn): void;
+/**
+ * Trigger all registered handlers for a hook.
+ * Each handler is wrapped in try/catch — a failing hook never blocks command execution.
+ */
+export declare function emitHook(name: HookName, ctx: HookContext, result?: unknown): Promise<void>;
+/**
+ * Remove all registered hooks. Intended for testing only.
+ */
+export declare function clearAllHooks(): void;

package/dist/src/hooks.js

@@ -0,0 +1 @@
+import{log as D}from"./logger.js";const w=globalThis.__opencli_hooks__??=new Map;function B(b,q){const p=w.get(b)??[];if(p.includes(q))return;p.push(q);w.set(b,p)}export function onStartup(b){B("onStartup",b)}export function onBeforeExecute(b){B("onBeforeExecute",b)}export function onAfterExecute(b){B("onAfterExecute",b)}export async function emitHook(b,q,p){const z=w.get(b);if(!z||z.length===0)return;for(const C of z)try{await C(q,p)}catch(A){D.warn(`Hook ${b} handler failed: ${A instanceof Error?A.message:String(A)}`)}}export function clearAllHooks(){w.clear()}

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

@@ -0,0 +1,4 @@
+/**
+ * Tests for the plugin lifecycle hooks system.
+ */
+export {};

package/dist/src/interceptor.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Shared XHR/Fetch interceptor JavaScript generators.
+ *
+ * Provides a single source of truth for monkey-patching browser
+ * fetch() and XMLHttpRequest to capture API responses matching
+ * a URL pattern. Used by:
+ *   - Page.installInterceptor()  (browser.ts)
+ *   - stepIntercept              (pipeline/steps/intercept.ts)
+ *   - stepTap                    (pipeline/steps/tap.ts)
+ */
+/**
+ * Generate JavaScript source that installs a fetch/XHR interceptor.
+ * Captured responses are pushed to `window.__opencli_intercepted`.
+ *
+ * @param patternExpr - JS expression resolving to a URL substring to match (e.g. a JSON.stringify'd string)
+ * @param opts.arrayName - Global array name for captured data (default: '__opencli_intercepted')
+ * @param opts.patchGuard - Global boolean name to prevent double-patching (default: '__opencli_interceptor_patched')
+ */
+export declare function generateInterceptorJs(patternExpr: string, opts?: {
+    arrayName?: string;
+    patchGuard?: string;
+}): string;
+/**
+ * Generate JavaScript source to read and clear intercepted data.
+ */
+export declare function generateReadInterceptedJs(arrayName?: string): string;
+/**
+ * Generate a self-contained tap interceptor for store-action bridge.
+ * Unlike the global interceptor, this one:
+ * - Installs temporarily, restores originals in finally block
+ * - Resolves a promise on first capture (for immediate await)
+ * - Returns captured data directly
+ *
+ * Reuses the shared DISGUISE_FN for consistent toString() disguising.
+ */
+export declare function generateTapInterceptorJs(patternExpr: string): {
+    setupVar: string;
+    capturedVar: string;
+    promiseVar: string;
+    resolveVar: string;
+    fetchPatch: string;
+    xhrPatch: string;
+    restorePatch: string;
+};

package/dist/src/interceptor.js

@@ -0,0 +1,123 @@
+const J=`
+      function __defHidden(obj, key, val) {
+        try {
+          Object.defineProperty(obj, key, { value: val, writable: true, enumerable: false, configurable: true });
+        } catch { obj[key] = val; }
+      }`,C=`
+      function __disguise(fn, name) {
+        const nativeStr = 'function ' + name + '() { [native code] }';
+        // Override toString on the instance AND patch Function.prototype.toString
+        // to handle Function.prototype.toString.call(fn) bypasses.
+        const _origToString = Function.prototype.toString;
+        const _patchedFns = window.__dFns || (function() {
+          const m = new Map();
+          Object.defineProperty(window, '__dFns', { value: m, enumerable: false, configurable: true });
+          // Patch Function.prototype.toString once to consult the map
+          Object.defineProperty(Function.prototype, 'toString', {
+            value: function() {
+              const override = m.get(this);
+              return override !== undefined ? override : _origToString.call(this);
+            },
+            writable: true, configurable: true
+          });
+          return m;
+        })();
+        _patchedFns.set(fn, nativeStr);
+        try { Object.defineProperty(fn, 'name', { value: name, configurable: true }); } catch {}
+        return fn;
+      }`;export function generateInterceptorJs(q,B={}){const j=B.arrayName??"__opencli_intercepted",z=B.patchGuard??"__opencli_interceptor_patched",A=`${z}_pattern`;return`
+    () => {
+      ${J}
+      ${C}
+
+      if (!window.${j}) __defHidden(window, '${j}', []);
+      if (!window.${j}_errors) __defHidden(window, '${j}_errors', []);
+      __defHidden(window, '${A}', ${q});
+      const __checkMatch = (url) => window.${A} && url.includes(window.${A});
+
+      if (!window.${z}) {
+        // ── Patch fetch ──
+        const __origFetch = window.fetch;
+        window.fetch = __disguise(async function(...args) {
+          const reqUrl = typeof args[0] === 'string' ? args[0]
+            : (args[0] && args[0].url) || '';
+          const response = await __origFetch.apply(this, args);
+          if (__checkMatch(reqUrl)) {
+            try {
+              const clone = response.clone();
+              const json = await clone.json();
+              window.${j}.push(json);
+            } catch(e) { window.${j}_errors.push({ url: reqUrl, error: String(e) }); }
+          }
+          return response;
+        }, 'fetch');
+
+        // ── Patch XMLHttpRequest ──
+        const __XHR = XMLHttpRequest.prototype;
+        const __origOpen = __XHR.open;
+        const __origSend = __XHR.send;
+        __XHR.open = __disguise(function(method, url) {
+          Object.defineProperty(this, '__iurl', { value: String(url), writable: true, enumerable: false, configurable: true });
+          return __origOpen.apply(this, arguments);
+        }, 'open');
+        __XHR.send = __disguise(function() {
+          if (__checkMatch(this.__iurl)) {
+            this.addEventListener('load', function() {
+              try {
+                window.${j}.push(JSON.parse(this.responseText));
+              } catch(e) { window.${j}_errors.push({ url: this.__iurl, error: String(e) }); }
+            });
+          }
+          return __origSend.apply(this, arguments);
+        }, 'send');
+
+        __defHidden(window, '${z}', true);
+      }
+    }
+  `}export function generateReadInterceptedJs(q="__opencli_intercepted"){return`
+    () => {
+      const data = window.${q} || [];
+      window.${q} = [];
+      return data;
+    }
+  `}export function generateTapInterceptorJs(q){return{setupVar:`
+      let captured = null;
+      let captureResolve;
+      const capturePromise = new Promise(r => { captureResolve = r; });
+      const capturePattern = ${q};
+      ${C}
+    `,capturedVar:"captured",promiseVar:"capturePromise",resolveVar:"captureResolve",fetchPatch:`
+      const origFetch = window.fetch;
+      window.fetch = __disguise(async function(...fetchArgs) {
+        const resp = await origFetch.apply(this, fetchArgs);
+        try {
+          const url = typeof fetchArgs[0] === 'string' ? fetchArgs[0]
+            : fetchArgs[0] instanceof Request ? fetchArgs[0].url : String(fetchArgs[0]);
+          if (capturePattern && url.includes(capturePattern) && !captured) {
+            try { captured = await resp.clone().json(); captureResolve(); } catch {}
+          }
+        } catch {}
+        return resp;
+      }, 'fetch');
+    `,xhrPatch:`
+      const origXhrOpen = XMLHttpRequest.prototype.open;
+      const origXhrSend = XMLHttpRequest.prototype.send;
+      XMLHttpRequest.prototype.open = __disguise(function(method, url) {
+        Object.defineProperty(this, '__iurl', { value: String(url), writable: true, enumerable: false, configurable: true });
+        return origXhrOpen.apply(this, arguments);
+      }, 'open');
+      XMLHttpRequest.prototype.send = __disguise(function(body) {
+        if (capturePattern && this.__iurl?.includes(capturePattern)) {
+          this.addEventListener('load', function() {
+            if (!captured) {
+              try { captured = JSON.parse(this.responseText); captureResolve(); } catch {}
+            }
+          });
+        }
+        return origXhrSend.apply(this, arguments);
+      }, 'send');
+    `,restorePatch:`
+      window.fetch = origFetch;
+      XMLHttpRequest.prototype.open = origXhrOpen;
+      XMLHttpRequest.prototype.send = origXhrSend;
+    `}}

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

@@ -0,0 +1,4 @@
+/**
+ * Tests for interceptor.ts: JavaScript code generators for XHR/Fetch interception.
+ */
+export {};

package/dist/src/launcher.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Electron app launcher — auto-detect, confirm, launch, and connect.
+ *
+ * Flow:
+ * 1. Probe CDP port → already running with debug? connect directly
+ * 2. Detect process → running without CDP? prompt to restart
+ * 3. Discover app path → not installed? error
+ * 4. Launch with --remote-debugging-port
+ * 5. Poll /json until ready
+ */
+import type { ElectronAppEntry } from './electron-apps.js';
+/**
+ * Probe whether a CDP endpoint is listening on the given port.
+ * Returns true if http://127.0.0.1:{port}/json responds successfully.
+ */
+export declare function probeCDP(port: number, timeoutMs?: number): Promise<boolean>;
+/**
+ * Check if a process with the given name is running.
+ * Uses pgrep on macOS/Linux.
+ */
+export declare function detectProcess(processName: string): boolean;
+/**
+ * Kill a process by name. Sends SIGTERM first, then SIGKILL after grace period.
+ */
+export declare function killProcess(processName: string): Promise<void>;
+/**
+ * Discover the app installation path on macOS.
+ * Uses osascript to resolve the app name to a POSIX path.
+ * Returns null if the app is not installed.
+ */
+export declare function discoverAppPath(displayName: string): string | null;
+export declare function resolveExecutableCandidates(appPath: string, app: ElectronAppEntry): string[];
+export declare function launchDetachedApp(executable: string, args: string[], label: string, extraEnv?: NodeJS.ProcessEnv): Promise<void>;
+export declare function launchElectronApp(appPath: string, app: ElectronAppEntry, args: string[], label: string): Promise<void>;
+export declare function electronLaunchArgs(port: number, extraArgs?: string[]): string[];
+/**
+ * Main entry point: resolve an Electron app to a CDP endpoint URL.
+ *
+ * Returns the endpoint URL: http://127.0.0.1:{port}
+ */
+export declare function resolveElectronEndpoint(site: string): Promise<string>;

package/dist/src/launcher.js

@@ -0,0 +1,7 @@
+import{execFileSync as G,spawn as w}from"node:child_process";import{request as D}from"node:http";import*as K from"node:path";import{getElectronApp as U}from"./electron-apps.js";import{confirmPrompt as q}from"./tui.js";import{CommandExecutionError as $}from"./errors.js";import{log as H}from"./logger.js";const F=500,V=15000,I=2000,R=3000;export function probeCDP(z,Q=I){return new Promise((J)=>{const W=D({hostname:"127.0.0.1",port:z,path:"/json",method:"GET",timeout:Q},(Y)=>{Y.resume();J(Y.statusCode!==void 0&&Y.statusCode>=200&&Y.statusCode<300)});W.on("error",()=>J(!1));W.on("timeout",()=>{W.destroy();J(!1)});W.end()})}export function detectProcess(z){if(process.platform==="win32")return!1;try{G("pgrep",["-x",z],{encoding:"utf-8",stdio:"pipe"});return!0}catch{return!1}}export async function killProcess(z){if(process.platform==="win32")return;try{G("pkill",["-x",z],{stdio:"pipe"})}catch{}const Q=Date.now()+R;while(Date.now()<Q){if(!detectProcess(z))return;await new Promise((J)=>setTimeout(J,200))}try{G("pkill",["-9","-x",z],{stdio:"pipe"})}catch{}}export function discoverAppPath(z){if(process.platform!=="darwin")return null;try{return G("osascript",["-e",`POSIX path of (path to application "${z}")`],{encoding:"utf-8",stdio:"pipe",timeout:5000}).trim().replace(/\/$/,"")}catch{return null}}function O(z,Q){return`${z}/Contents/MacOS/${Q}`}function T(z,Q){return z instanceof $&&z.message.startsWith(`Could not launch ${Q}: executable not found at `)}export function resolveExecutableCandidates(z,Q){const J=Q.executableNames?.length?Q.executableNames:[Q.processName];return[...new Set(J)].map((W)=>O(z,W))}export async function launchDetachedApp(z,Q,J,W){await new Promise((Y,X)=>{const Z=w(z,Q,{detached:!0,stdio:"ignore",...W?{env:{...process.env,...W}}:{}}),k=(B)=>{if(B.code==="ENOENT"){X(new $(`Could not launch ${J}: executable not found at ${z}`,`Install ${J}, reinstall it, or register a custom app path in ~/.opencli/apps.yaml`));return}X(new $(`Failed to launch ${J}`,B.message))};Z.once("error",k);Z.once("spawn",()=>{Z.off("error",k);Z.unref();Y()})})}export async function launchElectronApp(z,Q,J,W){const Y=resolveExecutableCandidates(z,Q);let X;for(const Z of Y){H.debug(`[launcher] Launching: ${Z} ${J.join(" ")}`);try{await launchDetachedApp(Z,J,W);return}catch(k){if(T(k,W)){X=k;continue}throw k}}if(Y.length>1)throw new $(`Could not launch ${W}: no compatible executable found in ${K.join(z,"Contents","MacOS")}`,`Tried: ${Y.map((Z)=>K.basename(Z)).join(", ")}. Install ${W}, reinstall it, or register a custom app path in ~/.opencli/apps.yaml`);throw X??new $(`Could not launch ${W}`,`Install ${W}, reinstall it, or register a custom app path in ~/.opencli/apps.yaml`)}export function electronLaunchArgs(z,Q=[]){return[`--remote-debugging-port=${z}`,"--remote-allow-origins=*",...Q]}function j(z,Q){return`Start ${z} manually with --remote-debugging-port=${Q} --remote-allow-origins=*, then either:`}async function y(z){const Q=Date.now()+V;while(Date.now()<Q){if(await probeCDP(z,1000))return;await new Promise((J)=>setTimeout(J,F))}throw new $(`App launched but CDP not available on port ${z} after ${V/1000}s`,"The app may be slow to start. Try running the command again.")}export async function resolveElectronEndpoint(z){const Q=U(z);if(!Q)throw new $(`No Electron app registered for site "${z}"`,"Register the app in ~/.opencli/apps.yaml or check the site name.");const{port:J,processName:W,displayName:Y}=Q,X=Y??W,Z=`http://127.0.0.1:${J}`;H.debug(`[launcher] Probing CDP on port ${J}...`);if(await probeCDP(J)){H.debug(`[launcher] CDP already available on port ${J}`);return Z}if(process.platform!=="darwin")throw new $(`${X} is not reachable on CDP port ${J}.`,`Auto-launch is not yet supported on ${process.platform}.
+${j(X,J)}
+`+`  • Set OPENCLI_CDP_ENDPOINT=http://127.0.0.1:${J}
+`+`  • Or just re-run the command once ${X} is listening on port ${J}.`);if(detectProcess(W)){H.debug(`[launcher] ${X} is running but CDP not available`);if(!await q(`${X} is running but CDP is not enabled. Restart with debug port?`,!0))throw new $(`${X} needs to be restarted with CDP enabled.`,`Manually restart: kill the app and relaunch with --remote-debugging-port=${J} --remote-allow-origins=*`);process.stderr.write(`  Restarting ${X}...
+`);await killProcess(W)}const B=discoverAppPath(X);if(!B)throw new $(`Could not find ${X} on this machine.`,`Install ${X} or register a custom path in ~/.opencli/apps.yaml`);const f=electronLaunchArgs(J,Q.extraArgs??[]);await launchElectronApp(B,Q,f,X);process.stderr.write(`  Waiting for ${X} on port ${J}...
+`);await y(J);process.stderr.write(`  Connected to ${X} on port ${J}.
+`);return Z}

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

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

package/dist/src/logger.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Unified logging for opencli.
+ *
+ * All framework output (warnings, debug info, errors) should go through
+ * this module so that verbosity levels are respected consistently.
+ */
+export declare const log: {
+    /** Informational message (always shown) */
+    info(msg: string): void;
+    /** Lightweight status line for adapter progress updates */
+    status(msg: string): void;
+    /** Positive completion/status line without the heavier info prefix */
+    success(msg: string): void;
+    /** Warning (always shown) */
+    warn(msg: string): void;
+    /** Error (always shown) */
+    error(msg: string): void;
+    /** Verbose output (shown when -v flag or OPENCLI_VERBOSE is set) */
+    verbose(msg: string): void;
+    /** Alias for verbose output. */
+    debug(msg: string): void;
+    /** Step-style debug (for pipeline steps, etc.) */
+    step(stepNum: number, total: number, op: string, preview?: string): void;
+    /** Step result summary */
+    stepResult(summary: string): void;
+};

package/dist/src/logger.js

@@ -0,0 +1,9 @@
+function x(){return!!process.env.OPENCLI_VERBOSE}export const log={info(h){process.stderr.write(`ℹ  ${h}
+`)},status(h){process.stderr.write(`${h}
+`)},success(h){process.stderr.write(`${h}
+`)},warn(h){process.stderr.write(`⚠  ${h}
+`)},error(h){process.stderr.write(`✖  ${h}
+`)},verbose(h){if(x())process.stderr.write(`[verbose] ${h}
+`)},debug(h){this.verbose(h)},step(h,j,k,q=""){process.stderr.write(`  [${h}/${j}] ${k}${q}
+`)},stepResult(h){process.stderr.write(`       → ${h}
+`)}};

package/dist/src/main.d.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+/**
+ * opencli — Make any website your CLI. AI-powered.
+ */
+export {};

package/dist/src/main.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+if(process.platform!=="win32"){const q=["/usr/local/bin","/usr/bin","/bin","/usr/sbin","/sbin"],Q=new Set((process.env.PATH??"").split(":").filter(Boolean));for(const z of q)Q.add(z);process.env.PATH=[...Q].join(":")}import*as J from"node:fs";import*as B from"node:os";import*as K from"node:path";import{fileURLToPath as X}from"node:url";import{getCompletionsFromManifest as k,hasAllManifests as R,printCompletionScriptFast as M}from"./completion-fast.js";import{findPackageRoot as N,getCliManifestPath as y}from"./package-paths.js";import{PKG_VERSION as O}from"./version.js";import{EXIT_CODES as Z}from"./errors.js";import{isSupportedNodeVersion as j,MIN_SUPPORTED_NODE_MAJOR as D}from"./runtime-detect.js";import{unsupportedDaemonPortEnvMessage as U}from"./constants.js";const x=X(import.meta.url),d=K.dirname(x),G=K.join(N(x),"clis"),F=K.join(B.homedir(),".opencli","clis"),b=process.argv.slice(2);if(typeof globalThis.Bun>"u"&&!j(process.version)){process.stderr.write([`OpenCLI requires Node.js >= ${D}.0.0.`,`Current runtime: ${process.version}`,"Upgrade Node.js, then retry the same command.",""].join(`
+`));process.exit(Z.CONFIG_ERROR)}if(process.env.OPENCLI_DAEMON_PORT){process.stderr.write(`error: ${U(process.env.OPENCLI_DAEMON_PORT)}
+`);process.exit(Z.CONFIG_ERROR)}if(b[0]==="--version"||b[0]==="-V"){process.stdout.write(O+`
+`);process.exit(Z.SUCCESS)}if(b[0]==="completion"&&b.length>=2){if(M(b[1]))process.exit(Z.SUCCESS)}const H=process.argv.indexOf("--get-completions");if(H!==-1){const q=[y(G)],Q=y(F);try{J.accessSync(Q);q.push(Q)}catch{}if(R(q)){const z=process.argv.slice(H+1);let $;const W=[];for(let Y=0;Y<z.length;Y++)if(z[Y]==="--cursor"&&Y+1<z.length){$=parseInt(z[Y+1],10);Y++}else W.push(z[Y]);if($===void 0)$=W.length;const A=k(W,$,q);process.stdout.write(A.join(`
+`)+`
+`);process.exit(Z.SUCCESS)}}const{discoverClis:V,discoverPlugins:w,ensureUserCliCompatShims:T,ensureUserAdapters:L}=await import("./discovery.js"),{getCompletions:P}=await import("./completion.js"),{runCli:v}=await import("./cli.js"),{emitHook:h}=await import("./hooks.js"),{installNodeNetwork:u}=await import("./node-network.js");u();const E=b[0]==="convention-audit";if(E)await V(G);else{const[,,]=await Promise.all([T(),L(),V(G)]);await V(F);await w()}if(H!==-1){const q=process.argv.slice(H+1);let Q;const z=[];for(let W=0;W<q.length;W++)if(q[W]==="--cursor"&&W+1<q.length){Q=parseInt(q[W+1],10);W++}else z.push(q[W]);if(Q===void 0)Q=z.length;const $=P(z,Q);process.stdout.write($.join(`
+`)+`
+`);process.exit(Z.SUCCESS)}const{rewriteBrowserArgv:g,BrowserSessionArgvError:_,escapeLeadingDashPositional:f}=await import("./cli-argv-preprocess.js");try{let q=g(process.argv.slice(2));try{const Q=y(G);if(J.existsSync(Q)){const z=JSON.parse(J.readFileSync(Q,"utf-8"));if(Array.isArray(z))q=f(q,z)}}catch{}process.argv.splice(2,process.argv.length-2,...q)}catch(q){if(q instanceof _){process.stderr.write(`error: ${q.message}
+`);process.exit(Z.GENERIC_ERROR)}throw q}await h("onStartup",{command:"__startup__",args:{}});v(G,F);

package/dist/src/manifest-types.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Shared manifest types — kept in their own module so both runtime code
+ * (discovery.ts) and the build-time compiler (build-manifest.ts) can
+ * import them without pulling each other in. This is what lets us
+ * exclude `src/build-manifest.ts` from `tsc`'s emit set: the only thing
+ * runtime code needs from build-manifest is the `ManifestEntry` type,
+ * and that lives here.
+ */
+export interface ManifestEntry {
+    site: string;
+    name: string;
+    aliases?: string[];
+    description: string;
+    access: 'read' | 'write';
+    example?: string;
+    domain?: string;
+    strategy: string;
+    browser: boolean;
+    args: Array<{
+        name: string;
+        type?: string;
+        default?: unknown;
+        required?: boolean;
+        valueRequired?: boolean;
+        positional?: boolean;
+        help?: string;
+        choices?: string[];
+    }>;
+    columns?: string[];
+    pipeline?: Record<string, unknown>[];
+    defaultFormat?: 'table' | 'plain' | 'json' | 'yaml' | 'yml' | 'md' | 'markdown' | 'csv';
+    type: 'js';
+    /** Relative path from clis/ dir, e.g. 'bilibili/search.js' */
+    modulePath?: string;
+    /** Relative path to the source file from clis/ dir (e.g. 'site/cmd.js') */
+    sourceFile?: string;
+    /** Pre-navigation control — see CliCommand.navigateBefore */
+    navigateBefore?: boolean | string;
+    /** Site session lifecycle defaults — see CliCommand.siteSession */
+    siteSession?: 'ephemeral' | 'persistent';
+    /** Default browser window visibility — see CliCommand.defaultWindowMode */
+    defaultWindowMode?: 'foreground' | 'background';
+}

package/dist/src/manifest-types.js

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

package/dist/src/node-network.d.ts

@@ -0,0 +1,10 @@
+import { type Dispatcher } from 'undici';
+export interface ProxyDecision {
+    mode: 'direct' | 'proxy';
+    proxyUrl?: string;
+}
+export declare function hasProxyEnv(env?: NodeJS.ProcessEnv): boolean;
+export declare function decideProxy(url: URL, env?: NodeJS.ProcessEnv): ProxyDecision;
+export declare function getDispatcherForUrl(url: URL, env?: NodeJS.ProcessEnv): Dispatcher;
+export declare function fetchWithNodeNetwork(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+export declare function installNodeNetwork(): void;

package/dist/src/node-network.js

@@ -0,0 +1 @@
+import{Agent as P,EnvHttpProxyAgent as x,fetch as d}from"undici";const m=["127.0.0.1","localhost","::1"],_={"http:":["http_proxy","HTTP_PROXY","all_proxy","ALL_PROXY"],"https:":["https_proxy","HTTPS_PROXY","all_proxy","ALL_PROXY"]},O={"http:":"80","https:":"443"};let h=!1;const f=new P,u=new Map,R=globalThis.fetch.bind(globalThis);function E(t,o,r){const e=t[o];if(typeof e==="string"&&e.trim()!=="")return e;const n=t[r];if(typeof n==="string"&&n.trim()!=="")return n;return}function a(t,o){for(const r of o){const e=t[r];if(typeof e==="string"&&e.trim()!=="")return e}return}function c(t){return t.replace(/^\[(.*)\]$/,"$1").toLowerCase()}function T(t){return(t??"").split(/[,\s]+/).map((o)=>o.trim()).filter(Boolean)}function l(t){if(t==="*")return{host:"*"};const o=t.trim().replace(/^\*?\./,"");if(o.startsWith("[")){const e=o.indexOf("]");if(e!==-1){const n=o.slice(1,e),s=o.slice(e+1);if(s.startsWith(":"))return{host:c(n),port:s.slice(1)};return{host:c(n)}}}if((o.match(/:/g)??[]).length===1){const[e,n]=o.split(":");return{host:c(e),port:n}}return{host:c(o)}}function N(t){const o=E(t,"no_proxy","NO_PROXY"),r=T(o).map(l),e=new Set(r.map((n)=>`${n.host}:${n.port??""}`));for(const n of m){const s=l(n),p=`${s.host}:${s.port??""}`;if(e.has(p))continue;r.push(s);e.add(p)}return r}function g(t){if(t.host==="*")return"*";const o=t.host.includes(":")?`[${t.host}]`:t.host;return t.port?`${o}:${t.port}`:o}function L(t){if(t.length===0)return;return t.map(g).join(",")}function y(t,o){const{host:r,port:e}=o;if(r==="*")return!0;const n=c(t.hostname),s=t.port||O[t.protocol]||void 0;if(e&&e!==s)return!1;return n===r||n.endsWith(`.${r}`)}function i(t=process.env){const o=N(t);return{httpProxy:a(t,_["http:"]),httpsProxy:a(t,["https_proxy","HTTPS_PROXY","http_proxy","HTTP_PROXY","all_proxy","ALL_PROXY"]),noProxy:L(o),noProxyEntries:o}}function w(t){const o=JSON.stringify([t.httpProxy??"",t.httpsProxy??"",t.noProxy??""]),r=u.get(o);if(r)return r;const e=new x({httpProxy:t.httpProxy,httpsProxy:t.httpsProxy,noProxy:t.noProxy});u.set(o,e);return e}function Y(t){if(typeof t==="string")return new URL(t);if(t instanceof URL)return t;if(typeof Request<"u"&&t instanceof Request)return new URL(t.url);return null}export function hasProxyEnv(t=process.env){const o=i(t);return Boolean(o.httpProxy||o.httpsProxy)}export function decideProxy(t,o=process.env){const r=i(o);if(r.noProxyEntries.some((n)=>y(t,n)))return{mode:"direct"};const e=t.protocol==="https:"?r.httpsProxy:r.httpProxy;if(!e)return{mode:"direct"};return{mode:"proxy",proxyUrl:e}}export function getDispatcherForUrl(t,o=process.env){const r=i(o);if(r.noProxyEntries.some((e)=>y(t,e)))return f;if(!r.httpProxy&&!r.httpsProxy)return f;return w(r)}export async function fetchWithNodeNetwork(t,o={}){const r=Y(t);if(!r||!hasProxyEnv()||decideProxy(r).mode==="direct")return R(t,o);return await d(t,{...o,dispatcher:getDispatcherForUrl(r)})}export function installNodeNetwork(){if(h)return;globalThis.fetch=(t,o)=>fetchWithNodeNetwork(t,o);h=!0}

package/dist/src/node-network.test.d.ts

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

package/dist/src/observation/artifact.d.ts

@@ -0,0 +1,16 @@
+import type { ObservationExportResult, ObservationExportStatus, ObservationTraceReceipt } from './events.js';
+import { ObservationSession } from './session.js';
+import { type TraceRetentionPolicyInput } from './retention.js';
+export interface ExportObservationOptions {
+    baseDir?: string;
+    error?: unknown;
+    status?: ObservationExportStatus;
+    retentionPolicy?: TraceRetentionPolicyInput;
+}
+export declare function getTraceDirectory(contextId: string | undefined, traceId: string, baseDir?: string): string;
+export declare function exportObservationSession(session: ObservationSession, opts?: ExportObservationOptions): ObservationExportResult;
+export declare function buildTraceReceipt(result: Pick<ObservationExportResult, 'traceId' | 'dir' | 'summaryPath' | 'receiptPath'>, status: ObservationExportStatus, error?: unknown, opts?: {
+    createdAt?: string;
+    scope?: ObservationSession['scope'];
+    retentionPolicy?: TraceRetentionPolicyInput;
+}): ObservationTraceReceipt;

package/dist/src/observation/artifact.js

@@ -0,0 +1,8 @@
+import*as c from"node:fs";import*as L from"node:os";import*as s from"node:path";import{redactValue as p}from"./redaction.js";import{pruneTraceArtifacts as R,traceExpiresAt as N}from"./retention.js";import{CliError as b,getErrorMessage as k}from"../errors.js";import{log as C}from"../logger.js";import{PKG_VERSION as T}from"../version.js";function V(){return process.env.OPENCLI_CONFIG_DIR||s.join(L.homedir(),".opencli")}function F(e){return(e||"default").replace(/[^a-zA-Z0-9_-]+/g,"_")||"default"}export function getTraceDirectory(e,n,t=V()){return s.join(t,"profiles",F(e),"traces",F(n))}export function exportObservationSession(e,n={}){const t=getTraceDirectory(e.scope.contextId,e.id,n.baseDir),r=n.status??(n.error===void 0?"success":"failure"),o=new Date().toISOString();c.mkdirSync(t,{recursive:!0});c.mkdirSync(s.join(t,"screenshots"),{recursive:!0});c.mkdirSync(s.join(t,"state"),{recursive:!0});const l=e.events(),h=l.map((f)=>J(f)),S=[],g=[],$=[];let i=0,d=0;for(let f=0;f<h.length;f++){const j=l[f],m=h[f],u={...m};if(m.stream==="screenshot"&&j.stream==="screenshot"&&typeof j.data==="string"){const y=m.format==="jpeg"?"jpg":"png",A=`screenshots/${String(++i).padStart(4,"0")}.${y}`;c.writeFileSync(s.join(t,A),j.data,"base64");u.path=A;delete u.data}if(m.stream==="state"&&u.snapshot!==void 0){const y=`state/${String(++d).padStart(4,"0")}.json`;c.writeFileSync(s.join(t,y),JSON.stringify(u.snapshot,null,2),"utf-8");u.snapshotPath=y;delete u.snapshot}const P=JSON.stringify(u);S.push(P);if(m.stream==="network")g.push(P);if(m.stream==="console")$.push(P)}c.writeFileSync(s.join(t,"trace.jsonl"),S.join(`
+`)+(S.length?`
+`:""),"utf-8");c.writeFileSync(s.join(t,"network.jsonl"),g.join(`
+`)+(g.length?`
+`:""),"utf-8");c.writeFileSync(s.join(t,"console.jsonl"),$.join(`
+`)+($.length?`
+`:""),"utf-8");const E=s.join(t,"summary.md");c.writeFileSync(E,z(e,h,{error:n.error,status:r,dir:t,createdAt:o,retentionPolicy:n.retentionPolicy}),"utf-8");const O=s.join(t,"receipt.json"),x={traceId:e.id,dir:t,summaryPath:E,receiptPath:O},I=buildTraceReceipt(x,r,n.error,{createdAt:o,scope:e.scope,retentionPolicy:n.retentionPolicy});c.writeFileSync(O,JSON.stringify(I,null,2),"utf-8");_(s.dirname(t),t,n.retentionPolicy);return{...x,receipt:I}}function J(e){return p(e)}export function buildTraceReceipt(e,n,t,r={}){const o=t instanceof b?t:void 0,l=r.createdAt??new Date().toISOString();return{schemaVersion:1,opencliVersion:T,traceId:e.traceId,traceDir:e.dir,summaryPath:e.summaryPath,receiptPath:e.receiptPath,status:n,createdAt:l,expiresAt:N(l,r.retentionPolicy),...r.scope?{scope:r.scope}:{},...t===void 0?{}:{error:{...t instanceof Error?{name:t.name}:{},...o?{code:o.code,hint:o.hint,exitCode:o.exitCode}:{},message:String(p(k(t)))}}}}function _(e,n,t){try{R(e,{policy:t,protectedTraceDirs:[n],warn:(r)=>C.warn(`[trace] ${r}`)})}catch(r){C.warn(`[trace] Failed to prune trace artifacts: ${r instanceof Error?r.message:String(r)}`)}}function z(e,n,t){const r=n.reduce((i,d)=>{i[d.stream]=(i[d.stream]??0)+1;return i},{}),o=v(t.error),l=n.filter((i)=>i.stream==="error").slice(-20).reverse(),h=n.filter((i)=>i.stream==="network").filter((i)=>i.status===void 0||i.status===0||i.status>=400).slice(-20).reverse(),S=n.filter((i)=>i.stream==="console").filter((i)=>/^(error|warning|warn|assert)$/i.test(i.level)).slice(-20).reverse(),g=n.filter((i)=>i.stream==="action").slice(-30);return["---","schemaVersion: 1",`opencliVersion: ${a(T)}`,`traceId: ${a(e.id)}`,`status: ${t.status}`,`contextId: ${a(e.scope.contextId??"default")}`,`session: ${a(e.scope.session)}`,...e.scope.target?[`target: ${a(e.scope.target)}`]:[],...e.scope.site?[`site: ${a(e.scope.site)}`]:[],...e.scope.command?[`command: ${a(e.scope.command)}`]:[],...e.scope.adapterSourcePath?[`adapterSourcePath: ${a(e.scope.adapterSourcePath)}`]:[],...e.scope.adapterSourcePath?[`adapterSourcePathExists: ${c.existsSync(e.scope.adapterSourcePath)}`]:[],`traceDir: ${a(t.dir)}`,`startedAt: ${a(new Date(e.startedAt).toISOString())}`,`exportedAt: ${a(t.createdAt)}`,`expiresAt: ${a(N(t.createdAt,t.retentionPolicy))}`,...o?[`errorCode: ${a(o.code??"UNKNOWN")}`,`errorMessage: ${a(o.message)}`]:[],"---","","# OpenCLI Trace Summary","","## How To Use","","- Start with this summary, then inspect `trace.jsonl` only when the evidence below is insufficient.","- For adapter repair policy and retry limits, use the `opencli-autofix` skill.","- `adapterSourcePathExists: false` means the path is a best-effort hint, not a confirmed editable file.","","## Error","",...G(o,l),"","## Failed Network","",...K(h),"","## Suspicious Console","",...U(S),"","## Action Timeline","",...B(g),"","## Event Counts","",...Object.entries(r).map(([i,d])=>`- ${i}: ${d}`),"","## Artifact Files","","- `trace.jsonl`: full redacted event timeline","- `network.jsonl`: redacted network events","- `console.jsonl`: redacted console events","- `state/`: final state snapshots when available","- `screenshots/`: final screenshots when available",""].join(`
+`)}function v(e){if(e===void 0)return;if(e instanceof b)return{code:e.code,message:String(p(e.message)),...e.hint?{hint:String(p(e.hint))}:{}};return{message:String(p(k(e)))}}function a(e){return JSON.stringify(e)}function G(e,n){const t=[];if(e){t.push(`- ${e.code??"UNKNOWN"}: ${e.message}`);if(e.hint)t.push(`- hint: ${e.hint}`)}for(const r of n){if(r.stream!=="error")continue;t.push(`- ${w(r.ts)} ${r.code??"ERROR"}: ${r.message}`)}return t.length?t:["- none"]}function K(e){if(!e.length)return["- none"];return e.map((n)=>{const t=n.status??"unknown",r=n.method??"GET",o=n.contentType?` ${n.contentType}`:"";return`- ${w(n.ts)} ${t} ${r} ${n.url}${o}`})}function U(e){if(!e.length)return["- none"];return e.map((n)=>`- ${w(n.ts)} ${n.level}: ${D(n.text,240)}`)}function B(e){if(!e.length)return["- none"];return e.map((n)=>{const t=n.phase?` ${n.phase}`:"",r=n.data&&Object.keys(n.data).length?` ${D(JSON.stringify(p(n.data)),240)}`:"";return`- ${w(n.ts)} ${n.name}${t}${r}`})}function w(e){return new Date(e).toISOString()}function D(e,n){const t=e.replace(/\s+/g," ").trim();return t.length>n?`${t.slice(0,n)}...`:t}

package/dist/src/observation/artifact.test.d.ts

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

package/dist/src/observation/events.d.ts

@@ -0,0 +1,89 @@
+export type ObservationStream = 'action' | 'network' | 'console' | 'screenshot' | 'state' | 'error';
+export interface ObservationScope {
+    contextId?: string;
+    session: string;
+    target?: string;
+    site?: string;
+    command?: string;
+    adapterSourcePath?: string;
+}
+interface BaseObservationEvent {
+    id: string;
+    ts: number;
+    stream: ObservationStream;
+}
+export interface ActionObservationEvent extends BaseObservationEvent {
+    stream: 'action';
+    name: string;
+    phase?: 'start' | 'end' | 'error';
+    data?: Record<string, unknown>;
+}
+export interface NetworkObservationEvent extends BaseObservationEvent {
+    stream: 'network';
+    url: string;
+    method?: string;
+    status?: number;
+    contentType?: string;
+    size?: number;
+    requestHeaders?: Record<string, unknown>;
+    responseHeaders?: Record<string, unknown>;
+    requestBody?: unknown;
+    responseBody?: unknown;
+}
+export interface ConsoleObservationEvent extends BaseObservationEvent {
+    stream: 'console';
+    level: string;
+    text: string;
+    source?: string;
+}
+export interface ScreenshotObservationEvent extends BaseObservationEvent {
+    stream: 'screenshot';
+    format: 'png' | 'jpeg';
+    data: string;
+    label?: string;
+}
+export interface StateObservationEvent extends BaseObservationEvent {
+    stream: 'state';
+    url?: string | null;
+    target?: string;
+    snapshot?: unknown;
+    label?: string;
+}
+export interface ErrorObservationEvent extends BaseObservationEvent {
+    stream: 'error';
+    code?: string;
+    message: string;
+    stack?: string;
+    hint?: string;
+}
+export type ObservationEvent = ActionObservationEvent | NetworkObservationEvent | ConsoleObservationEvent | ScreenshotObservationEvent | StateObservationEvent | ErrorObservationEvent;
+export type ObservationEventInput = ObservationEvent extends infer T ? T extends ObservationEvent ? Omit<T, 'id' | 'ts'> & Partial<Pick<T, 'id' | 'ts'>> : never : never;
+export interface ObservationExportResult {
+    traceId: string;
+    dir: string;
+    summaryPath: string;
+    receiptPath: string;
+    receipt: ObservationTraceReceipt;
+}
+export type ObservationExportStatus = 'success' | 'failure';
+export interface ObservationTraceReceipt {
+    schemaVersion: 1;
+    opencliVersion: string;
+    traceId: string;
+    traceDir: string;
+    summaryPath: string;
+    receiptPath: string;
+    status: ObservationExportStatus;
+    createdAt: string;
+    /** Advisory only; actual deletion is governed by current trace retention budgets. */
+    expiresAt?: string;
+    scope?: ObservationScope;
+    error?: {
+        name?: string;
+        code?: string;
+        message: string;
+        hint?: string;
+        exitCode?: number;
+    };
+}
+export {};

package/dist/src/observation/events.js

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

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

@@ -0,0 +1,7 @@
+export * from './events.js';
+export * from './ring-buffer.js';
+export * from './redaction.js';
+export * from './session.js';
+export * from './manager.js';
+export * from './artifact.js';
+export * from './retention.js';

package/dist/src/observation/index.js

@@ -0,0 +1 @@
+export*from"./events.js";export*from"./ring-buffer.js";export*from"./redaction.js";export*from"./session.js";export*from"./manager.js";export*from"./artifact.js";export*from"./retention.js";

package/dist/src/observation/manager.d.ts

@@ -0,0 +1,9 @@
+import { ObservationSession, type ObservationSessionOptions } from './session.js';
+import type { ObservationScope } from './events.js';
+export declare class ObservationManager {
+    private readonly sessions;
+    start(opts: ObservationSessionOptions): ObservationSession;
+    get(id: string): ObservationSession | undefined;
+    stop(id: string): ObservationSession | undefined;
+    findByScope(scope: ObservationScope): ObservationSession[];
+}

package/dist/src/observation/manager.js

@@ -0,0 +1 @@
+import{ObservationSession as t}from"./session.js";export class ObservationManager{sessions=new Map;start(n){const s=new t(n);this.sessions.set(s.id,s);return s}get(n){return this.sessions.get(n)}stop(n){const s=this.sessions.get(n);this.sessions.delete(n);return s}findByScope(n){return[...this.sessions.values()].filter((s)=>i(s.scope,n))}}function i(n,s){return n.session===s.session&&(s.contextId===void 0||n.contextId===s.contextId)&&(s.target===void 0||n.target===s.target)&&(s.site===void 0||n.site===s.site)&&(s.command===void 0||n.command===s.command)}

package/dist/src/observation/manager.test.d.ts

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

package/dist/src/observation/redaction.d.ts

@@ -0,0 +1,11 @@
+export interface RedactionOptions {
+    allowlist?: string[];
+    maxStringLength?: number;
+    maxDepth?: number;
+    maxArrayItems?: number;
+    maxObjectFields?: number;
+}
+export declare function redactUrl(url: string): string;
+export declare function redactHeaders(headers: Record<string, unknown> | undefined, opts?: RedactionOptions): Record<string, unknown> | undefined;
+export declare function redactText(text: string, opts?: RedactionOptions): string;
+export declare function redactValue(value: unknown, opts?: RedactionOptions, keyHint?: string, depth?: number): unknown;

package/dist/src/observation/redaction.js

@@ -0,0 +1,2 @@
+const d="[REDACTED]",p=new Set(["authorization","cookie","set-cookie","proxy-authorization","x-api-key","x-auth-token","x-csrf-token","x-xsrf-token"]),l=/(password|passwd|pwd|token|secret|authorization|cookie|set-cookie|api[_-]?key|access[_-]?token|refresh[_-]?token|session[_-]?id|csrf|xsrf)/i,E=/([?&])(token|key|secret|password|auth|access_token|api_key|session_id|csrf|xsrf)=[^&]*/gi;export function redactUrl(e){return e.replace(E,"$1$2=[REDACTED]")}export function redactHeaders(e,t={}){if(!e)return e;const o=new Set((t.allowlist??[]).map((n)=>n.toLowerCase())),r={};for(const[n,_]of Object.entries(e)){const s=n.toLowerCase();r[n]=p.has(s)&&!o.has(s)?d:redactValue(_,t,n)}return r}export function redactText(e,t={}){const o=t.maxStringLength??50000;let r=e.replace(/Bearer\s+[A-Za-z0-9\-._~+/]+=*/gi,"Bearer [REDACTED]").replace(/(["'])(password|passwd|pwd|token|secret|api_key|apikey|access_token|session_id)\1\s*:\s*(["'])(.*?)\3/gi,"$1$2$1:$3[REDACTED]$3").replace(/(token|secret|password|api_key|apikey|access_token|session_id)[=:]\s*['"]?[^'"\s,;}&]+['"]?/gi,"$1=[REDACTED]").replace(/(cookie[=:]\s*)[^\n;]{3,}/gi,"$1[REDACTED]").replace(/eyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g,"[REDACTED_JWT]");if(r.length>o)r=r.slice(0,o)+`
+...[truncated, ${r.length-o} chars omitted]`;return r}export function redactValue(e,t={},o,r=0){const n=new Set((t.allowlist??[]).map((s)=>s.toLowerCase()));if(o&&l.test(o)&&!n.has(o.toLowerCase()))return d;if(typeof e==="string")return o==="url"?redactUrl(e):redactText(e,t);if(e===null||typeof e==="number"||typeof e==="boolean")return e;const _=t.maxDepth??5;if(r>=_)return"[truncated: max depth reached]";if(Array.isArray(e)){const s=t.maxArrayItems??100,c=e.slice(0,s).map((i)=>redactValue(i,t,void 0,r+1));if(e.length>s)c.push(`[truncated, ${e.length-s} items omitted]`);return c}if(typeof e==="object"){const s=Object.entries(e),c=t.maxObjectFields??100,i={};for(const[f,a]of s.slice(0,c))if(f.toLowerCase()==="url"&&typeof a==="string")i[f]=redactUrl(a);else if(f.toLowerCase().includes("headers")&&a&&typeof a==="object"&&!Array.isArray(a))i[f]=redactHeaders(a,t);else i[f]=redactValue(a,t,f,r+1);if(s.length>c)i.__truncated__=`[${s.length-c} fields omitted]`;return i}return e}

package/dist/src/observation/redaction.test.d.ts

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