@jackwener/opencli 0.5.1 → 0.5.2

package/dist/interceptor.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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
+ */
+export declare function generateTapInterceptorJs(patternExpr: string): {
+    setupVar: string;
+    capturedVar: string;
+    promiseVar: string;
+    resolveVar: string;
+    fetchPatch: string;
+    xhrPatch: string;
+    restorePatch: string;
+};

package/dist/interceptor.js

@@ -0,0 +1,138 @@
+/**
+ * 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 function generateInterceptorJs(patternExpr, opts = {}) {
+    const arr = opts.arrayName ?? '__opencli_intercepted';
+    const guard = opts.patchGuard ?? '__opencli_interceptor_patched';
+    return `
+    () => {
+      window.${arr} = window.${arr} || [];
+      const __pattern = ${patternExpr};
+
+      if (!window.${guard}) {
+        const __checkMatch = (url) => __pattern && url.includes(__pattern);
+
+        // ── Patch fetch ──
+        const __origFetch = window.fetch;
+        window.fetch = 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.${arr}.push(json);
+            } catch(e) {}
+          }
+          return response;
+        };
+
+        // ── Patch XMLHttpRequest ──
+        const __XHR = XMLHttpRequest.prototype;
+        const __origOpen = __XHR.open;
+        const __origSend = __XHR.send;
+        __XHR.open = function(method, url) {
+          this.__opencli_url = String(url);
+          return __origOpen.apply(this, arguments);
+        };
+        __XHR.send = function() {
+          if (__checkMatch(this.__opencli_url)) {
+            this.addEventListener('load', function() {
+              try {
+                window.${arr}.push(JSON.parse(this.responseText));
+              } catch(e) {}
+            });
+          }
+          return __origSend.apply(this, arguments);
+        };
+
+        window.${guard} = true;
+      }
+    }
+  `;
+}
+/**
+ * Generate JavaScript source to read and clear intercepted data.
+ */
+export function generateReadInterceptedJs(arrayName = '__opencli_intercepted') {
+    return `
+    () => {
+      const data = window.${arrayName} || [];
+      window.${arrayName} = [];
+      return data;
+    }
+  `;
+}
+/**
+ * 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
+ */
+export function generateTapInterceptorJs(patternExpr) {
+    return {
+        setupVar: `
+      let captured = null;
+      let captureResolve;
+      const capturePromise = new Promise(r => { captureResolve = r; });
+      const capturePattern = ${patternExpr};
+    `,
+        capturedVar: 'captured',
+        promiseVar: 'capturePromise',
+        resolveVar: 'captureResolve',
+        fetchPatch: `
+      const origFetch = window.fetch;
+      window.fetch = 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;
+      };
+    `,
+        xhrPatch: `
+      const origXhrOpen = XMLHttpRequest.prototype.open;
+      const origXhrSend = XMLHttpRequest.prototype.send;
+      XMLHttpRequest.prototype.open = function(method, url) {
+        this.__tapUrl = String(url);
+        return origXhrOpen.apply(this, arguments);
+      };
+      XMLHttpRequest.prototype.send = function(body) {
+        if (capturePattern && this.__tapUrl?.includes(capturePattern)) {
+          this.addEventListener('load', function() {
+            if (!captured) {
+              try { captured = JSON.parse(this.responseText); captureResolve(); } catch {}
+            }
+          });
+        }
+        return origXhrSend.apply(this, arguments);
+      };
+    `,
+        restorePatch: `
+      window.fetch = origFetch;
+      XMLHttpRequest.prototype.open = origXhrOpen;
+      XMLHttpRequest.prototype.send = origXhrSend;
+    `,
+    };
+}

package/dist/main.js

@@ -2,7 +2,6 @@
 /**
  * opencli — Make any website your CLI. AI-powered.
  */
-import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -13,13 +12,11 @@ import { fullName, getRegistry, strategyLabel } from './registry.js';
 import { render as renderOutput } from './output.js';
 import { PlaywrightMCP } from './browser.js';
 import { browserSession, DEFAULT_BROWSER_COMMAND_TIMEOUT, runWithTimeout } from './runtime.js';
+import { PKG_VERSION } from './version.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const BUILTIN_CLIS = path.resolve(__dirname, 'clis');
 const USER_CLIS = path.join(os.homedir(), '.opencli', 'clis');
-// Read version from package.json (single source of truth)
-const pkgJsonPath = path.resolve(__dirname, '..', 'package.json');
-const PKG_VERSION = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8')).version ?? '0.0.0';
 await discoverClis(BUILTIN_CLIS, USER_CLIS);
 const program = new Command();
 program.name('opencli').description('Make any website your CLI. Zero setup. AI-powered.').version(PKG_VERSION);

package/dist/output.js

@@ -43,11 +43,6 @@ function renderTable(data, opts) {
         style: { head: [], border: [] },
         wordWrap: true,
         wrapOnWordBoundary: true,
-        colWidths: columns.map((_c, i) => {
-            if (i === 0)
-                return 6;
-            return null;
-        }).filter(() => true),
     });
     for (const row of rows) {
         table.push(columns.map(c => {

package/dist/pipeline/steps/intercept.js

@@ -2,6 +2,7 @@
  * Pipeline step: intercept — declarative XHR interception.
  */
 import { render } from '../template.js';
+import { generateInterceptorJs, generateReadInterceptedJs } from '../../interceptor.js';
 export async function stepIntercept(page, params, data, args) {
     const cfg = typeof params === 'object' ? params : {};
     const trigger = cfg.trigger ?? '';
@@ -11,52 +12,7 @@ export async function stepIntercept(page, params, data, args) {
     if (!capturePattern)
         return data;
     // Step 1: Inject fetch/XHR interceptor BEFORE trigger
-    await page.evaluate(`
-    () => {
-      window.__opencli_intercepted = window.__opencli_intercepted || [];
-      const pattern = ${JSON.stringify(capturePattern)};
-      
-      if (!window.__opencli_fetch_patched) {
-        const origFetch = window.fetch;
-        window.fetch = async function(...args) {
-          const reqUrl = typeof args[0] === 'string' ? args[0] : (args[0] && args[0].url) || '';
-          const response = await origFetch.apply(this, args);
-          setTimeout(async () => {
-            try {
-              if (reqUrl.includes(pattern)) {
-                const clone = response.clone();
-                const json = await clone.json();
-                window.__opencli_intercepted.push(json);
-              }
-            } catch(e) {}
-          }, 0);
-          return response;
-        };
-        window.__opencli_fetch_patched = true;
-      }
-
-      if (!window.__opencli_xhr_patched) {
-        const XHR = XMLHttpRequest.prototype;
-        const open = XHR.open;
-        const send = XHR.send;
-        XHR.open = function(method, url, ...args) {
-          this._reqUrl = url;
-          return open.call(this, method, url, ...args);
-        };
-        XHR.send = function(...args) {
-          this.addEventListener('load', function() {
-            try {
-              if (this._reqUrl && this._reqUrl.includes(pattern)) {
-                window.__opencli_intercepted.push(JSON.parse(this.responseText));
-              }
-            } catch(e) {}
-          });
-          return send.apply(this, args);
-        };
-        window.__opencli_xhr_patched = true;
-      }
-    }
-  `);
+    await page.evaluate(generateInterceptorJs(JSON.stringify(capturePattern)));
     // Step 2: Execute the trigger action
     if (trigger.startsWith('navigate:')) {
         const url = render(trigger.slice('navigate:'.length), { args, data });
@@ -77,14 +33,8 @@ export async function stepIntercept(page, params, data, args) {
     // Step 3: Wait a bit for network requests to fire
     await page.wait(Math.min(timeout, 3));
     // Step 4: Retrieve captured data
-    const matchingResponses = await page.evaluate(`
-    () => {
-      const data = window.__opencli_intercepted || [];
-      window.__opencli_intercepted = []; // clear after reading
-      return data;
-    }
-  `);
-    // Step 4: Select from response if specified
+    const matchingResponses = await page.evaluate(generateReadInterceptedJs());
+    // Step 5: Select from response if specified
     let result = matchingResponses.length === 1 ? matchingResponses[0] :
         matchingResponses.length > 1 ? matchingResponses : data;
     if (selectPath && result) {

package/dist/pipeline/steps/tap.js

@@ -9,6 +9,7 @@
  * 5. Returns the captured data (optionally sub-selected)
  */
 import { render } from '../template.js';
+import { generateTapInterceptorJs } from '../../interceptor.js';
 export async function stepTap(page, params, data, args) {
     const cfg = typeof params === 'object' ? params : {};
     const storeName = String(render(cfg.store ?? '', { args, data }));
@@ -32,53 +33,14 @@ export async function stepTap(page, params, data, args) {
     const actionCall = actionArgsRendered.length
         ? `store[${JSON.stringify(actionName)}](${actionArgsRendered.join(', ')})`
         : `store[${JSON.stringify(actionName)}]()`;
+    // Use shared interceptor generator for fetch/XHR patching
+    const tap = generateTapInterceptorJs(JSON.stringify(capturePattern));
     const js = `
     async () => {
       // ── 1. Setup capture proxy (fetch + XHR dual interception) ──
-      let captured = null;
-      let captureResolve;
-      const capturePromise = new Promise(r => { captureResolve = r; });
-      const capturePattern = ${JSON.stringify(capturePattern)};
-
-      // Intercept fetch API
-      const origFetch = window.fetch;
-      window.fetch = 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;
-      };
-
-      // Intercept XMLHttpRequest
-      const origXhrOpen = XMLHttpRequest.prototype.open;
-      const origXhrSend = XMLHttpRequest.prototype.send;
-      XMLHttpRequest.prototype.open = function(method, url) {
-        this.__tapUrl = String(url);
-        return origXhrOpen.apply(this, arguments);
-      };
-      XMLHttpRequest.prototype.send = function(body) {
-        if (capturePattern && this.__tapUrl?.includes(capturePattern)) {
-          const xhr = this;
-          const origHandler = xhr.onreadystatechange;
-          xhr.onreadystatechange = function() {
-            if (xhr.readyState === 4 && !captured) {
-              try { captured = JSON.parse(xhr.responseText); captureResolve(); } catch {}
-            }
-            if (origHandler) origHandler.apply(this, arguments);
-          };
-          const origOnload = xhr.onload;
-          xhr.onload = function() {
-            if (!captured) { try { captured = JSON.parse(xhr.responseText); captureResolve(); } catch {} }
-            if (origOnload) origOnload.apply(this, arguments);
-          };
-        }
-        return origXhrSend.apply(this, arguments);
-      };
+      ${tap.setupVar}
+      ${tap.fetchPatch}
+      ${tap.xhrPatch}
 
       try {
         // ── 2. Find store ──
@@ -113,19 +75,17 @@ export async function stepTap(page, params, data, args) {
         await ${actionCall};
 
         // ── 4. Wait for network response ──
-        if (!captured) {
+        if (!${tap.capturedVar}) {
           const timeoutPromise = new Promise(r => setTimeout(r, ${timeout} * 1000));
-          await Promise.race([capturePromise, timeoutPromise]);
+          await Promise.race([${tap.promiseVar}, timeoutPromise]);
         }
       } finally {
         // ── 5. Always restore originals ──
-        window.fetch = origFetch;
-        XMLHttpRequest.prototype.open = origXhrOpen;
-        XMLHttpRequest.prototype.send = origXhrSend;
+        ${tap.restorePatch}
       }
 
-      if (!captured) return { error: 'No matching response captured for pattern: ' + capturePattern };
-      return captured${selectChain} ?? captured;
+      if (!${tap.capturedVar}) return { error: 'No matching response captured for pattern: ' + capturePattern };
+      return ${tap.capturedVar}${selectChain} ?? ${tap.capturedVar};
     }
   `;
     return page.evaluate(js);

package/dist/registry.d.ts

@@ -30,7 +30,9 @@ export interface CliCommand {
     pipeline?: any[];
     timeoutSeconds?: number;
     source?: string;
-    /** Internal: lazy-loaded TS module support */
+}
+/** Internal extension for lazy-loaded TS modules (not exposed in public API) */
+export interface InternalCliCommand extends CliCommand {
     _lazy?: boolean;
     _modulePath?: string;
 }

package/dist/registry.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Tests for registry.ts: Strategy enum, cli() registration, helpers.
+ */
+export {};

package/dist/registry.test.js

@@ -0,0 +1,90 @@
+/**
+ * Tests for registry.ts: Strategy enum, cli() registration, helpers.
+ */
+import { describe, it, expect } from 'vitest';
+import { cli, getRegistry, fullName, strategyLabel, registerCommand, Strategy } from './registry.js';
+describe('cli() registration', () => {
+    it('registers a command and returns it', () => {
+        const cmd = cli({
+            site: 'test-registry',
+            name: 'hello',
+            description: 'A test command',
+            strategy: Strategy.PUBLIC,
+            browser: false,
+        });
+        expect(cmd.site).toBe('test-registry');
+        expect(cmd.name).toBe('hello');
+        expect(cmd.strategy).toBe(Strategy.PUBLIC);
+        expect(cmd.browser).toBe(false);
+        expect(cmd.args).toEqual([]);
+    });
+    it('puts registered command in the registry', () => {
+        cli({
+            site: 'test-registry',
+            name: 'registered',
+            description: 'test',
+        });
+        const registry = getRegistry();
+        expect(registry.has('test-registry/registered')).toBe(true);
+    });
+    it('defaults strategy to COOKIE when browser is true', () => {
+        const cmd = cli({
+            site: 'test-registry',
+            name: 'default-strategy',
+        });
+        expect(cmd.strategy).toBe(Strategy.COOKIE);
+        expect(cmd.browser).toBe(true);
+    });
+    it('defaults strategy to PUBLIC when browser is false', () => {
+        const cmd = cli({
+            site: 'test-registry',
+            name: 'no-browser',
+            browser: false,
+        });
+        expect(cmd.strategy).toBe(Strategy.PUBLIC);
+    });
+    it('overwrites existing command on re-registration', () => {
+        cli({ site: 'test-registry', name: 'overwrite', description: 'v1' });
+        cli({ site: 'test-registry', name: 'overwrite', description: 'v2' });
+        const reg = getRegistry();
+        expect(reg.get('test-registry/overwrite')?.description).toBe('v2');
+    });
+});
+describe('fullName', () => {
+    it('returns site/name', () => {
+        const cmd = {
+            site: 'bilibili', name: 'hot', description: '', args: [],
+        };
+        expect(fullName(cmd)).toBe('bilibili/hot');
+    });
+});
+describe('strategyLabel', () => {
+    it('returns strategy string', () => {
+        const cmd = {
+            site: 'test', name: 'test', description: '', args: [],
+            strategy: Strategy.INTERCEPT,
+        };
+        expect(strategyLabel(cmd)).toBe('intercept');
+    });
+    it('returns public when no strategy set', () => {
+        const cmd = {
+            site: 'test', name: 'test', description: '', args: [],
+        };
+        expect(strategyLabel(cmd)).toBe('public');
+    });
+});
+describe('registerCommand', () => {
+    it('registers a pre-built command', () => {
+        const cmd = {
+            site: 'test-registry',
+            name: 'direct-reg',
+            description: 'directly registered',
+            args: [],
+            strategy: Strategy.HEADER,
+            browser: true,
+        };
+        registerCommand(cmd);
+        const reg = getRegistry();
+        expect(reg.get('test-registry/direct-reg')?.strategy).toBe(Strategy.HEADER);
+    });
+});

package/dist/runtime.d.ts

@@ -6,8 +6,22 @@ export declare const DEFAULT_BROWSER_CONNECT_TIMEOUT: number;
 export declare const DEFAULT_BROWSER_COMMAND_TIMEOUT: number;
 export declare const DEFAULT_BROWSER_EXPLORE_TIMEOUT: number;
 export declare const DEFAULT_BROWSER_SMOKE_TIMEOUT: number;
+/**
+ * Timeout with seconds unit. Used for high-level command timeouts.
+ */
 export declare function runWithTimeout<T>(promise: Promise<T>, opts: {
     timeout: number;
     label?: string;
 }): Promise<T>;
-export declare function browserSession<T>(BrowserFactory: new () => any, fn: (page: IPage) => Promise<T>): Promise<T>;
+/**
+ * Timeout with milliseconds unit. Used for low-level internal timeouts.
+ */
+export declare function withTimeoutMs<T>(promise: Promise<T>, timeoutMs: number, message: string): Promise<T>;
+/** Interface for browser factory (PlaywrightMCP or test mocks) */
+export interface IBrowserFactory {
+    connect(opts?: {
+        timeout?: number;
+    }): Promise<IPage>;
+    close(): Promise<void>;
+}
+export declare function browserSession<T>(BrowserFactory: new () => IBrowserFactory, fn: (page: IPage) => Promise<T>): Promise<T>;

package/dist/runtime.js

@@ -5,14 +5,19 @@ export const DEFAULT_BROWSER_CONNECT_TIMEOUT = parseInt(process.env.OPENCLI_BROW
 export const DEFAULT_BROWSER_COMMAND_TIMEOUT = parseInt(process.env.OPENCLI_BROWSER_COMMAND_TIMEOUT ?? '45', 10);
 export const DEFAULT_BROWSER_EXPLORE_TIMEOUT = parseInt(process.env.OPENCLI_BROWSER_EXPLORE_TIMEOUT ?? '120', 10);
 export const DEFAULT_BROWSER_SMOKE_TIMEOUT = parseInt(process.env.OPENCLI_BROWSER_SMOKE_TIMEOUT ?? '60', 10);
+/**
+ * Timeout with seconds unit. Used for high-level command timeouts.
+ */
 export async function runWithTimeout(promise, opts) {
+    return withTimeoutMs(promise, opts.timeout * 1000, `${opts.label ?? 'Operation'} timed out after ${opts.timeout}s`);
+}
+/**
+ * Timeout with milliseconds unit. Used for low-level internal timeouts.
+ */
+export function withTimeoutMs(promise, timeoutMs, message) {
     return new Promise((resolve, reject) => {
-        const timer = setTimeout(() => {
-            reject(new Error(`${opts.label ?? 'Operation'} timed out after ${opts.timeout}s`));
-        }, opts.timeout * 1000);
-        promise
-            .then((result) => { clearTimeout(timer); resolve(result); })
-            .catch((err) => { clearTimeout(timer); reject(err); });
+        const timer = setTimeout(() => reject(new Error(message)), timeoutMs);
+        promise.then((value) => { clearTimeout(timer); resolve(value); }, (error) => { clearTimeout(timer); reject(error); });
     });
 }
 export async function browserSession(BrowserFactory, fn) {

package/dist/synthesize.js

@@ -5,11 +5,11 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import yaml from 'js-yaml';
-/** Volatile params to strip from generated URLs */
-const VOLATILE_PARAMS = new Set(['w_rid', 'wts', 'callback', '_', 'timestamp', 't', 'nonce', 'sign']);
-const SEARCH_PARAM_NAMES = new Set(['q', 'query', 'keyword', 'search', 'wd', 'kw', 'w', 'search_query']);
-const LIMIT_PARAM_NAMES = new Set(['ps', 'page_size', 'limit', 'count', 'per_page', 'size', 'num']);
-const PAGE_PARAM_NAMES = new Set(['pn', 'page', 'page_num', 'offset', 'cursor']);
+import { VOLATILE_PARAMS, SEARCH_PARAMS, LIMIT_PARAMS, PAGINATION_PARAMS } from './constants.js';
+/** Renamed aliases for backward compatibility with local references */
+const SEARCH_PARAM_NAMES = SEARCH_PARAMS;
+const LIMIT_PARAM_NAMES = LIMIT_PARAMS;
+const PAGE_PARAM_NAMES = PAGINATION_PARAMS;
 export function synthesizeFromExplore(target, opts = {}) {
     const exploreDir = resolveExploreDir(target);
     const bundle = loadExploreBundle(exploreDir);

package/dist/validate.js

@@ -2,6 +2,13 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import yaml from 'js-yaml';
+/** All recognized pipeline step names */
+const KNOWN_STEP_NAMES = new Set([
+    'navigate', 'click', 'type', 'wait', 'press', 'snapshot', 'scroll',
+    'fetch', 'evaluate',
+    'select', 'map', 'filter', 'sort', 'limit',
+    'intercept', 'tap',
+]);
 export function validateClisWithTarget(dirs, target) {
     const results = [];
     let errors = 0;
@@ -52,6 +59,20 @@ function validateYamlFile(filePath) {
             errors.push('"columns" must be an array');
         if (def.args && typeof def.args !== 'object')
             errors.push('"args" must be an object');
+        // Validate pipeline step names (catch typos like 'navaigate')
+        if (Array.isArray(def.pipeline)) {
+            for (let i = 0; i < def.pipeline.length; i++) {
+                const step = def.pipeline[i];
+                if (step && typeof step === 'object') {
+                    const stepKeys = Object.keys(step);
+                    for (const key of stepKeys) {
+                        if (!KNOWN_STEP_NAMES.has(key)) {
+                            warnings.push(`Pipeline step ${i}: unknown step name "${key}" (did you mean one of: ${[...KNOWN_STEP_NAMES].join(', ')}?)`);
+                        }
+                    }
+                }
+            }
+        }
     }
     catch (e) {
         errors.push(`YAML parse error: ${e.message}`);

package/dist/verify.d.ts

@@ -1,2 +1,9 @@
+/**
+ * Verification: runs validation and optional smoke test.
+ *
+ * The smoke test is intentionally kept as a stub — full browser-based
+ * smoke testing requires a running browser session and is better suited
+ * to the `opencli test` command or CI pipelines.
+ */
 export declare function verifyClis(opts: any): Promise<any>;
 export declare function renderVerifyReport(report: any): string;

package/dist/verify.js

@@ -1,4 +1,10 @@
-/** Verification: validate + smoke. */
+/**
+ * Verification: runs validation and optional smoke test.
+ *
+ * The smoke test is intentionally kept as a stub — full browser-based
+ * smoke testing requires a running browser session and is better suited
+ * to the `opencli test` command or CI pipelines.
+ */
 import { validateClisWithTarget, renderValidationReport } from './validate.js';
 export async function verifyClis(opts) {
     const report = validateClisWithTarget([opts.builtinClis, opts.userClis], opts.target);

package/dist/version.d.ts

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

package/dist/version.js

@@ -0,0 +1,16 @@
+/**
+ * Single source of truth for package version.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkgJsonPath = path.resolve(__dirname, '..', 'package.json');
+export const PKG_VERSION = (() => {
+    try {
+        return JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8')).version;
+    }
+    catch {
+        return '0.0.0';
+    }
+})();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jackwener/opencli",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "publishConfig": {
     "access": "public"
   },