@jackwener/opencli 0.5.1 → 0.5.2

package/src/interceptor.ts

@@ -0,0 +1,153 @@
+/**
+ * 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: string,
+  opts: { arrayName?: string; patchGuard?: string } = {},
+): string {
+  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: string = '__opencli_intercepted'): string {
+  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: string): {
+  setupVar: string;
+  capturedVar: string;
+  promiseVar: string;
+  resolveVar: string;
+  fetchPatch: string;
+  xhrPatch: string;
+  restorePatch: string;
+} {
+  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/src/main.ts

@@ -3,7 +3,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';
@@ -14,16 +13,13 @@ import { type CliCommand, fullName, getRegistry, strategyLabel } from './registr
 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();

package/src/output.ts

@@ -40,10 +40,6 @@ function renderTable(data: any, opts: RenderOptions): void {
     style: { head: [], border: [] },
     wordWrap: true,
     wrapOnWordBoundary: true,
-    colWidths: columns.map((_c, i) => {
-      if (i === 0) return 6;
-      return null as any;
-    }).filter(() => true),
   });
 
   for (const row of rows) {

package/src/pipeline/executor.ts

@@ -15,26 +15,26 @@ export interface PipelineContext {
   debug?: boolean;
 }
 
-/** Step handler signature */
+/** Step handler: all steps conform to (page, params, data, args) => Promise<any> */
 type StepHandler = (page: IPage | null, params: any, data: any, args: Record<string, any>) => Promise<any>;
 
 /** Registry of all available step handlers */
 const STEP_HANDLERS: Record<string, StepHandler> = {
-  navigate: stepNavigate as StepHandler,
+  navigate: stepNavigate,
   fetch: stepFetch,
-  select: stepSelect as StepHandler,
-  evaluate: stepEvaluate as StepHandler,
-  snapshot: stepSnapshot as StepHandler,
-  click: stepClick as StepHandler,
-  type: stepType as StepHandler,
-  wait: stepWait as StepHandler,
-  press: stepPress as StepHandler,
-  map: stepMap as StepHandler,
-  filter: stepFilter as StepHandler,
-  sort: stepSort as StepHandler,
-  limit: stepLimit as StepHandler,
-  intercept: stepIntercept as StepHandler,
-  tap: stepTap as StepHandler,
+  select: stepSelect,
+  evaluate: stepEvaluate,
+  snapshot: stepSnapshot,
+  click: stepClick,
+  type: stepType,
+  wait: stepWait,
+  press: stepPress,
+  map: stepMap,
+  filter: stepFilter,
+  sort: stepSort,
+  limit: stepLimit,
+  intercept: stepIntercept,
+  tap: stepTap,
 };
 
 export async function executePipeline(

package/src/pipeline/steps/intercept.ts

@@ -4,6 +4,7 @@
 
 import type { IPage } from '../../types.js';
 import { render } from '../template.js';
+import { generateInterceptorJs, generateReadInterceptedJs } from '../../interceptor.js';
 
 export async function stepIntercept(page: IPage, params: any, data: any, args: Record<string, any>): Promise<any> {
   const cfg = typeof params === 'object' ? params : {};
@@ -15,52 +16,7 @@ export async function stepIntercept(page: IPage, params: any, data: any, args: R
   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:')) {
@@ -81,16 +37,9 @@ export async function stepIntercept(page: IPage, params: any, data: any, args: R
   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;
-    }
-  `);
-
+  const matchingResponses = await page.evaluate(generateReadInterceptedJs());
 
-  // Step 4: Select from response if specified
+  // Step 5: Select from response if specified
   let result = matchingResponses.length === 1 ? matchingResponses[0] :
                matchingResponses.length > 1 ? matchingResponses : data;
 

package/src/pipeline/steps/tap.ts

@@ -11,6 +11,7 @@
 
 import type { IPage } from '../../types.js';
 import { render } from '../template.js';
+import { generateTapInterceptorJs } from '../../interceptor.js';
 
 export async function stepTap(page: IPage, params: any, data: any, args: Record<string, any>): Promise<any> {
   const cfg = typeof params === 'object' ? params : {};
@@ -38,53 +39,15 @@ export async function stepTap(page: IPage, params: any, data: any, args: Record<
     ? `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 ──
@@ -119,19 +82,17 @@ export async function stepTap(page: IPage, params: any, data: any, args: Record<
         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};
     }
   `;
 

package/src/registry.test.ts

@@ -0,0 +1,106 @@
+/**
+ * Tests for registry.ts: Strategy enum, cli() registration, helpers.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { cli, getRegistry, fullName, strategyLabel, registerCommand, Strategy, type CliCommand } 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: CliCommand = {
+      site: 'bilibili', name: 'hot', description: '', args: [],
+    };
+    expect(fullName(cmd)).toBe('bilibili/hot');
+  });
+});
+
+describe('strategyLabel', () => {
+  it('returns strategy string', () => {
+    const cmd: CliCommand = {
+      site: 'test', name: 'test', description: '', args: [],
+      strategy: Strategy.INTERCEPT,
+    };
+    expect(strategyLabel(cmd)).toBe('intercept');
+  });
+
+  it('returns public when no strategy set', () => {
+    const cmd: CliCommand = {
+      site: 'test', name: 'test', description: '', args: [],
+    };
+    expect(strategyLabel(cmd)).toBe('public');
+  });
+});
+
+describe('registerCommand', () => {
+  it('registers a pre-built command', () => {
+    const cmd: CliCommand = {
+      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/src/registry.ts

@@ -34,7 +34,10 @@ 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/src/runtime.ts

@@ -9,23 +9,37 @@ export const DEFAULT_BROWSER_COMMAND_TIMEOUT = parseInt(process.env.OPENCLI_BROW
 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<T>(
   promise: Promise<T>,
   opts: { timeout: number; label?: string },
 ): Promise<T> {
-  return new Promise<T>((resolve, reject) => {
-    const timer = setTimeout(() => {
-      reject(new Error(`${opts.label ?? 'Operation'} timed out after ${opts.timeout}s`));
-    }, opts.timeout * 1000);
+  return withTimeoutMs(promise, opts.timeout * 1000, `${opts.label ?? 'Operation'} timed out after ${opts.timeout}s`);
+}
 
-    promise
-      .then((result) => { clearTimeout(timer); resolve(result); })
-      .catch((err) => { clearTimeout(timer); reject(err); });
+/**
+ * Timeout with milliseconds unit. Used for low-level internal timeouts.
+ */
+export function withTimeoutMs<T>(promise: Promise<T>, timeoutMs: number, message: string): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(message)), timeoutMs);
+    promise.then(
+      (value) => { clearTimeout(timer); resolve(value); },
+      (error) => { clearTimeout(timer); reject(error); },
+    );
   });
 }
 
+/** Interface for browser factory (PlaywrightMCP or test mocks) */
+export interface IBrowserFactory {
+  connect(opts?: { timeout?: number }): Promise<IPage>;
+  close(): Promise<void>;
+}
+
 export async function browserSession<T>(
-  BrowserFactory: new () => any,
+  BrowserFactory: new () => IBrowserFactory,
   fn: (page: IPage) => Promise<T>,
 ): Promise<T> {
   const mcp = new BrowserFactory();

package/src/synthesize.ts

@@ -6,12 +6,12 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import yaml from 'js-yaml';
+import { VOLATILE_PARAMS, SEARCH_PARAMS, LIMIT_PARAMS, PAGINATION_PARAMS } from './constants.js';
 
-/** 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']);
+/** 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: string,

package/src/validate.ts

@@ -3,6 +3,14 @@ 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: string[], target?: string): any {
   const results: any[] = [];
   let errors = 0; let warnings = 0; let files = 0;
@@ -38,6 +46,20 @@ function validateYamlFile(filePath: string): any {
     if (def.pipeline && !Array.isArray(def.pipeline)) errors.push('"pipeline" must be an array');
     if (def.columns && !Array.isArray(def.columns)) 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: any) { errors.push(`YAML parse error: ${e.message}`); }
   return { path: filePath, errors, warnings };
 }

package/src/verify.ts

@@ -1,9 +1,18 @@
-/** 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: any): Promise<any> {
   const report = validateClisWithTarget([opts.builtinClis, opts.userClis], opts.target);
   return { ok: report.ok, validation: report, smoke: null };
 }
+
 export function renderVerifyReport(report: any): string {
   return renderValidationReport(report.validation);
 }

package/src/version.ts

@@ -0,0 +1,18 @@
+/**
+ * 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: string = (() => {
+  try {
+    return JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8')).version;
+  } catch {
+    return '0.0.0';
+  }
+})();