@jackwener/opencli 1.3.3 → 1.4.1

package/src/plugin.ts

@@ -6,16 +6,120 @@
  */
 
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 import { execSync, execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 import { PLUGINS_DIR } from './discovery.js';
+import { getErrorMessage } from './errors.js';
 import { log } from './logger.js';
 
+const isWindows = process.platform === 'win32';
+
+/** Get home directory, respecting HOME environment variable for test isolation. */
+function getHomeDir(): string {
+  return process.env.HOME || process.env.USERPROFILE || os.homedir();
+}
+
+/** Path to the lock file that tracks installed plugin versions. */
+export function getLockFilePath(): string {
+  return path.join(getHomeDir(), '.opencli', 'plugins.lock.json');
+}
+
+// Legacy const for backward compatibility (computed at load time)
+export const LOCK_FILE = path.join(os.homedir(), '.opencli', 'plugins.lock.json');
+
+export interface LockEntry {
+  source: string;
+  commitHash: string;
+  installedAt: string;
+  updatedAt?: string;
+}
+
 export interface PluginInfo {
   name: string;
   path: string;
   commands: string[];
   source?: string;
+  version?: string;
+  installedAt?: string;
+}
+
+// ── Validation helpers ──────────────────────────────────────────────────────
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+}
+
+// ── Lock file helpers ───────────────────────────────────────────────────────
+
+export function readLockFile(): Record<string, LockEntry> {
+  try {
+    const raw = fs.readFileSync(getLockFilePath(), 'utf-8');
+    return JSON.parse(raw) as Record<string, LockEntry>;
+  } catch {
+    return {};
+  }
+}
+
+export function writeLockFile(lock: Record<string, LockEntry>): void {
+  const lockPath = getLockFilePath();
+  fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+  fs.writeFileSync(lockPath, JSON.stringify(lock, null, 2) + '\n');
+}
+
+/** Get the HEAD commit hash of a git repo directory. */
+export function getCommitHash(dir: string): string | undefined {
+  try {
+    return execFileSync('git', ['rev-parse', 'HEAD'], {
+      cwd: dir,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Validate that a downloaded plugin directory is a structurally valid plugin.
+ * Checks for at least one command file (.yaml, .yml, .ts, .js) and a valid
+ * package.json if it contains .ts files.
+ */
+export function validatePluginStructure(pluginDir: string): ValidationResult {
+  const errors: string[] = [];
+  
+  if (!fs.existsSync(pluginDir)) {
+    return { valid: false, errors: ['Plugin directory does not exist'] };
+  }
+
+  const files = fs.readdirSync(pluginDir);
+  const hasYaml = files.some(f => f.endsWith('.yaml') || f.endsWith('.yml'));
+  const hasTs = files.some(f => f.endsWith('.ts') && !f.endsWith('.d.ts') && !f.endsWith('.test.ts'));
+  const hasJs = files.some(f => f.endsWith('.js') && !f.endsWith('.d.js'));
+
+  if (!hasYaml && !hasTs && !hasJs) {
+    errors.push(`No command files found in plugin directory. A plugin must contain at least one .yaml, .ts, or .js command file.`);
+  }
+
+  if (hasTs) {
+    const pkgJsonPath = path.join(pluginDir, 'package.json');
+    if (!fs.existsSync(pkgJsonPath)) {
+      errors.push(`Plugin contains .ts files but no package.json. A package.json with "type": "module" and "@jackwener/opencli" peer dependency is required for TS plugins.`);
+    } else {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
+        if (pkg.type !== 'module') {
+          errors.push(`Plugin package.json must have "type": "module" for TypeScript plugins.`);
+        }
+      } catch {
+        errors.push(`Plugin package.json is malformed or invalid JSON.`);
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
 }
 
 /**
@@ -31,9 +135,10 @@ function postInstallLifecycle(pluginDir: string): void {
       cwd: pluginDir,
       encoding: 'utf-8',
       stdio: ['pipe', 'pipe', 'pipe'],
+      ...(isWindows && { shell: true }),
     });
-  } catch {
-    // Non-fatal: npm install may fail if no real deps
+  } catch (err) {
+    console.error(`[plugin] npm install failed in ${pluginDir}: ${err instanceof Error ? err.message : err}`);
   }
 
   // Symlink host opencli so TS plugins resolve '@jackwener/opencli/registry'
@@ -74,11 +179,30 @@ export function installPlugin(source: string): string {
       encoding: 'utf-8',
       stdio: ['pipe', 'pipe', 'pipe'],
     });
-  } catch (err: any) {
-    throw new Error(`Failed to clone plugin: ${err.message}`);
+  } catch (err) {
+    throw new Error(`Failed to clone plugin: ${getErrorMessage(err)}`);
+  }
+
+  const validation = validatePluginStructure(targetDir);
+  if (!validation.valid) {
+    // If validation fails, clean up the cloned directory and abort
+    fs.rmSync(targetDir, { recursive: true, force: true });
+    throw new Error(`Invalid plugin structure:\n- ${validation.errors.join('\n- ')}`);
   }
 
   postInstallLifecycle(targetDir);
+
+  const commitHash = getCommitHash(targetDir);
+  if (commitHash) {
+    const lock = readLockFile();
+    lock[name] = {
+      source: cloneUrl,
+      commitHash,
+      installedAt: new Date().toISOString(),
+    };
+    writeLockFile(lock);
+  }
+
   return name;
 }
 
@@ -91,6 +215,12 @@ export function uninstallPlugin(name: string): void {
     throw new Error(`Plugin "${name}" is not installed.`);
   }
   fs.rmSync(targetDir, { recursive: true, force: true });
+
+  const lock = readLockFile();
+  if (lock[name]) {
+    delete lock[name];
+    writeLockFile(lock);
+  }
 }
 
 /**
@@ -108,11 +238,54 @@ export function updatePlugin(name: string): void {
       encoding: 'utf-8',
       stdio: ['pipe', 'pipe', 'pipe'],
     });
-  } catch (err: any) {
-    throw new Error(`Failed to update plugin: ${err.message}`);
+  } catch (err) {
+    throw new Error(`Failed to update plugin: ${getErrorMessage(err)}`);
+  }
+
+  const validation = validatePluginStructure(targetDir);
+  if (!validation.valid) {
+    log.warn(`Plugin "${name}" updated, but structure is now invalid:\n- ${validation.errors.join('\n- ')}`);
   }
 
   postInstallLifecycle(targetDir);
+
+  const commitHash = getCommitHash(targetDir);
+  if (commitHash) {
+    const lock = readLockFile();
+    const existing = lock[name];
+    lock[name] = {
+      source: existing?.source ?? getPluginSource(targetDir) ?? '',
+      commitHash,
+      installedAt: existing?.installedAt ?? new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    };
+    writeLockFile(lock);
+  }
+}
+
+export interface UpdateResult {
+  name: string;
+  success: boolean;
+  error?: string;
+}
+
+/**
+ * Update all installed plugins.
+ * Continues even if individual plugin updates fail.
+ */
+export function updateAllPlugins(): UpdateResult[] {
+  return listPlugins().map((plugin): UpdateResult => {
+    try {
+      updatePlugin(plugin.name);
+      return { name: plugin.name, success: true };
+    } catch (err) {
+      return {
+        name: plugin.name,
+        success: false,
+        error: getErrorMessage(err),
+      };
+    }
+  });
 }
 
 /**
@@ -122,6 +295,7 @@ export function listPlugins(): PluginInfo[] {
   if (!fs.existsSync(PLUGINS_DIR)) return [];
 
   const entries = fs.readdirSync(PLUGINS_DIR, { withFileTypes: true });
+  const lock = readLockFile();
   const plugins: PluginInfo[] = [];
 
   for (const entry of entries) {
@@ -129,12 +303,15 @@ export function listPlugins(): PluginInfo[] {
     const pluginDir = path.join(PLUGINS_DIR, entry.name);
     const commands = scanPluginCommands(pluginDir);
     const source = getPluginSource(pluginDir);
+    const lockEntry = lock[entry.name];
 
     plugins.push({
       name: entry.name,
       path: pluginDir,
       commands,
       source,
+      version: lockEntry?.commitHash?.slice(0, 7),
+      installedAt: lockEntry?.installedAt,
     });
   }
 
@@ -163,7 +340,7 @@ function scanPluginCommands(dir: string): string[] {
 /** Get git remote origin URL */
 function getPluginSource(dir: string): string | undefined {
   try {
-    return execSync('git config --get remote.origin.url', {
+    return execFileSync('git', ['config', '--get', 'remote.origin.url'], {
       cwd: dir,
       encoding: 'utf-8',
       stdio: ['pipe', 'pipe', 'pipe'],
@@ -210,7 +387,7 @@ function linkHostOpencli(pluginDir: string): void {
     // Determine the host opencli package root from this module's location.
     // Both dev (tsx src/plugin.ts) and prod (node dist/plugin.js) are one level
     // deep, so path.dirname + '..' always gives us the package root.
-    const thisFile = new URL(import.meta.url).pathname;
+    const thisFile = fileURLToPath(import.meta.url);
     const hostRoot = path.resolve(path.dirname(thisFile), '..');
 
     const targetLink = path.join(pluginDir, 'node_modules', '@jackwener', 'opencli');
@@ -223,27 +400,85 @@ function linkHostOpencli(pluginDir: string): void {
     // Ensure parent directory exists
     fs.mkdirSync(path.dirname(targetLink), { recursive: true });
 
-    // Create symlink
-    fs.symlinkSync(hostRoot, targetLink, 'dir');
+    // Use 'junction' on Windows (doesn't require admin privileges),
+    // 'dir' symlink on other platforms.
+    const linkType = isWindows ? 'junction' : 'dir';
+    fs.symlinkSync(hostRoot, targetLink, linkType);
     log.debug(`Linked host opencli into plugin: ${targetLink} → ${hostRoot}`);
-  } catch (err: any) {
-    log.warn(`Failed to link host opencli into plugin: ${err.message}`);
+  } catch (err) {
+    log.warn(`Failed to link host opencli into plugin: ${getErrorMessage(err)}`);
   }
 }
 
+/**
+ * Resolve the path to the esbuild CLI executable with fallback strategies.
+ */
+export function resolveEsbuildBin(): string | null {
+  const thisFile = fileURLToPath(import.meta.url);
+  const hostRoot = path.resolve(path.dirname(thisFile), '..');
+
+  // Strategy 1 (Windows): prefer the .cmd wrapper which is executable via shell
+  if (isWindows) {
+    const cmdPath = path.join(hostRoot, 'node_modules', '.bin', 'esbuild.cmd');
+    if (fs.existsSync(cmdPath)) {
+      return cmdPath;
+    }
+  }
+
+  // Strategy 2: resolve esbuild binary via import.meta.resolve
+  // (On Unix, shebang scripts are directly executable; on Windows they are not,
+  //  so this strategy is skipped on Windows in favour of the .cmd wrapper above.)
+  if (!isWindows) {
+    try {
+      const pkgUrl = import.meta.resolve('esbuild/package.json');
+      if (pkgUrl.startsWith('file://')) {
+        const pkgPath = fileURLToPath(pkgUrl);
+        const pkgRaw = fs.readFileSync(pkgPath, 'utf8');
+        const pkg = JSON.parse(pkgRaw);
+        if (pkg.bin && typeof pkg.bin === 'object' && pkg.bin.esbuild) {
+          const binPath = path.resolve(path.dirname(pkgPath), pkg.bin.esbuild);
+          if (fs.existsSync(binPath)) return binPath;
+        } else if (typeof pkg.bin === 'string') {
+          const binPath = path.resolve(path.dirname(pkgPath), pkg.bin);
+          if (fs.existsSync(binPath)) return binPath;
+        }
+      }
+    } catch {
+      // ignore package resolution failures
+    }
+  }
+
+  // Strategy 3: fallback to node_modules/.bin/esbuild (Unix)
+  const binFallback = path.join(hostRoot, 'node_modules', '.bin', 'esbuild');
+  if (fs.existsSync(binFallback)) {
+    return binFallback;
+  }
+
+  // Strategy 4: global esbuild in PATH
+  try {
+    const lookupCmd = isWindows ? 'where esbuild' : 'which esbuild';
+    // `where` on Windows may return multiple lines; take only the first match.
+    const globalBin = execSync(lookupCmd, { encoding: 'utf-8', stdio: 'pipe' }).trim().split('\n')[0].trim();
+    if (globalBin && fs.existsSync(globalBin)) {
+      return globalBin;
+    }
+  } catch {
+    // ignore PATH lookup failures
+  }
+
+  return null;
+}
+
 /**
  * Transpile TS plugin files to JS so they work in production mode.
  * Uses esbuild from the host opencli's node_modules for fast single-file transpilation.
  */
 function transpilePluginTs(pluginDir: string): void {
   try {
-    // Resolve esbuild binary from the host opencli's node_modules
-    const thisFile = new URL(import.meta.url).pathname;
-    const hostRoot = path.resolve(path.dirname(thisFile), '..');
-    const esbuildBin = path.join(hostRoot, 'node_modules', '.bin', 'esbuild');
+    const esbuildBin = resolveEsbuildBin();
 
-    if (!fs.existsSync(esbuildBin)) {
-      log.debug('esbuild not found in host node_modules, skipping TS transpilation');
+    if (!esbuildBin) {
+      log.debug('esbuild not found in host node_modules, via resolve, or in PATH, skipping TS transpilation');
       return;
     }
 
@@ -264,10 +499,11 @@ function transpilePluginTs(pluginDir: string): void {
           cwd: pluginDir,
           encoding: 'utf-8',
           stdio: ['pipe', 'pipe', 'pipe'],
+          ...(isWindows && { shell: true }),
         });
         log.debug(`Transpiled plugin file: ${tsFile} → ${jsFile}`);
-      } catch (err: any) {
-        log.warn(`Failed to transpile ${tsFile}: ${err.message}`);
+      } catch (err) {
+        log.warn(`Failed to transpile ${tsFile}: ${getErrorMessage(err)}`);
       }
     }
   } catch {
@@ -275,4 +511,12 @@ function transpilePluginTs(pluginDir: string): void {
   }
 }
 
-export { parseSource as _parseSource };
+export {
+  resolveEsbuildBin as _resolveEsbuildBin,
+  getCommitHash as _getCommitHash,
+  parseSource as _parseSource,
+  readLockFile as _readLockFile,
+  updateAllPlugins as _updateAllPlugins,
+  validatePluginStructure as _validatePluginStructure,
+  writeLockFile as _writeLockFile,
+};

package/src/record.ts

@@ -19,12 +19,15 @@ import chalk from 'chalk';
 import yaml from 'js-yaml';
 import { sendCommand } from './browser/daemon-client.js';
 import type { IPage } from './types.js';
+import { SEARCH_PARAMS, PAGINATION_PARAMS, FIELD_ROLES } from './constants.js';
 import {
-  VOLATILE_PARAMS,
-  SEARCH_PARAMS,
-  PAGINATION_PARAMS,
-  FIELD_ROLES,
-} from './constants.js';
+  urlToPattern,
+  findArrayPath,
+  inferCapabilityName,
+  inferStrategy,
+  detectAuthFromContent,
+  classifyQueryParams,
+} from './analysis.js';
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
@@ -142,78 +145,6 @@ function generateReadRecordedJs(): string {
 
 // ── Analysis helpers ───────────────────────────────────────────────────────
 
-function urlToPattern(url: string): string {
-  try {
-    const p = new URL(url);
-    const pathNorm = p.pathname
-      .replace(/\/\d+/g, '/{id}')
-      .replace(/\/[0-9a-fA-F]{8,}/g, '/{hex}')
-      .replace(/\/BV[a-zA-Z0-9]{10}/g, '/{bvid}');
-    const params: string[] = [];
-    p.searchParams.forEach((_v, k) => { if (!VOLATILE_PARAMS.has(k)) params.push(k); });
-    return `${p.host}${pathNorm}${params.length ? '?' + params.sort().map(k => `${k}={}`).join('&') : ''}`;
-  } catch { return url; }
-}
-
-function detectAuthIndicators(url: string, body: unknown): string[] {
-  const indicators: string[] = [];
-  // Heuristic: if body contains sign/w_rid fields, it's likely signed
-  if (body && typeof body === 'object') {
-    const keys = Object.keys(body as object).map(k => k.toLowerCase());
-    if (keys.some(k => k.includes('sign') || k === 'w_rid' || k.includes('token'))) {
-      indicators.push('signature');
-    }
-  }
-  // Check URL for common auth patterns
-  if (url.includes('/wbi/') || url.includes('w_rid=')) indicators.push('signature');
-  if (url.includes('bearer') || url.includes('access_token')) indicators.push('bearer');
-  return indicators;
-}
-
-function findArrayPath(obj: unknown, depth = 0): { path: string; items: unknown[] } | null {
-  if (depth > 5 || !obj || typeof obj !== 'object') return null;
-  if (Array.isArray(obj)) {
-    if (obj.length >= 2 && obj.some(i => i && typeof i === 'object' && !Array.isArray(i))) {
-      return { path: '', items: obj };
-    }
-    return null;
-  }
-  let best: { path: string; items: unknown[] } | null = null;
-  for (const [key, val] of Object.entries(obj as Record<string, unknown>)) {
-    const found = findArrayPath(val, depth + 1);
-    if (found) {
-      const fullPath = found.path ? `${key}.${found.path}` : key;
-      const candidate = { path: fullPath, items: found.items };
-      if (!best || candidate.items.length > best.items.length) best = candidate;
-    }
-  }
-  return best;
-}
-
-function inferCapabilityName(url: string): string {
-  const u = url.toLowerCase();
-  if (u.includes('hot') || u.includes('popular') || u.includes('ranking') || u.includes('trending')) return 'hot';
-  if (u.includes('search')) return 'search';
-  if (u.includes('feed') || u.includes('timeline') || u.includes('dynamic')) return 'feed';
-  if (u.includes('comment') || u.includes('reply')) return 'comments';
-  if (u.includes('history')) return 'history';
-  if (u.includes('profile') || u.includes('me')) return 'me';
-  if (u.includes('favorite') || u.includes('collect') || u.includes('bookmark')) return 'favorite';
-  try {
-    const segs = new URL(url).pathname
-      .split('/')
-      .filter(s => s && !s.match(/^\d+$/) && !s.match(/^[0-9a-f]{8,}$/i) && !s.match(/^v\d+$/));
-    if (segs.length) return segs[segs.length - 1].replace(/[^a-z0-9]/gi, '_').toLowerCase();
-  } catch {}
-  return 'data';
-}
-
-function inferStrategy(authIndicators: string[]): string {
-  if (authIndicators.includes('signature')) return 'intercept';
-  if (authIndicators.includes('bearer') || authIndicators.includes('csrf')) return 'header';
-  return 'cookie';
-}
-
 function scoreRequest(req: RecordedRequest, arrayResult: ReturnType<typeof findArrayPath> | null): number {
   let s = 0;
   if (arrayResult) {
@@ -267,10 +198,7 @@ function buildRecordedYaml(
       : itemPath.split('.').map(p => `?.${p}`).join('');
 
   // Detect search/limit/page params (must be before fetch URL building to use hasSearch/hasPage)
-  const qp: string[] = [];
-  try { new URL(req.url).searchParams.forEach((_v, k) => { if (!VOLATILE_PARAMS.has(k)) qp.push(k); }); } catch {}
-  const hasSearch = qp.some(p => SEARCH_PARAMS.has(p));
-  const hasPage = qp.some(p => PAGINATION_PARAMS.has(p));
+  const { hasSearch, hasPagination: hasPage } = classifyQueryParams(req.url);
 
   // Build evaluate script
   const mapLines = Object.entries(detectedFields)
@@ -397,10 +325,9 @@ export async function recordSession(opts: RecordOptions): Promise<RecordResult>
     const stop = () => { stopped = true; };
 
     const { promise: enterPromise, cleanup: cleanupEnter } = waitForEnter();
-    const enterRace = enterPromise.then(stop);
+    enterPromise.then(stop);
     const timeoutPromise = new Promise<void>(r => setTimeout(() => {
       stop();
-      cleanupEnter(); // close readline to prevent process from hanging
       r();
     }, timeoutMs));
 
@@ -428,6 +355,7 @@ export async function recordSession(opts: RecordOptions): Promise<RecordResult>
     }, pollMs);
 
     await Promise.race([enterPromise, timeoutPromise]);
+    cleanupEnter(); // Always clean up readline to prevent process from hanging
     clearInterval(pollInterval);
 
     // Final drain from all known tabs
@@ -532,7 +460,7 @@ function analyzeAndWrite(
   const scored: ScoredEntry[] = [];
   for (const [pattern, req] of seen) {
     const arrayResult = findArrayPath(req.body);
-    const authIndicators = detectAuthIndicators(req.url, req.body);
+    const authIndicators = detectAuthFromContent(req.url, req.body);
     const score = scoreRequest(req, arrayResult);
     if (score > 0) {
       scored.push({ req, pattern, arrayResult, authIndicators, score });

package/src/registry-api.ts

@@ -10,3 +10,5 @@
 export { cli, Strategy, getRegistry, fullName, registerCommand } from './registry.js';
 export type { CliCommand, Arg, CliOptions } from './registry.js';
 export type { IPage } from './types.js';
+export { onStartup, onBeforeExecute, onAfterExecute } from './hooks.js';
+export type { HookFn, HookContext, HookName } from './hooks.js';

package/src/registry.ts

@@ -22,6 +22,11 @@ export interface Arg {
   choices?: string[];
 }
 
+export interface RequiredEnv {
+  name: string;
+  help?: string;
+}
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- kwargs from CLI parsing are inherently untyped
 export type CommandArgs = Record<string, any>;
 
@@ -40,6 +45,7 @@ export interface CliCommand {
   /** Origin of this command: 'yaml', 'ts', or plugin name. */
   source?: string;
   footerExtra?: (kwargs: CommandArgs) => string | undefined;
+  requiredEnv?: RequiredEnv[];
   /**
    * Control pre-navigation for cookie/header context before command execution.
    *
@@ -88,6 +94,7 @@ export function cli(opts: CliOptions): CliCommand {
     pipeline: opts.pipeline,
     timeoutSeconds: opts.timeoutSeconds,
     footerExtra: opts.footerExtra,
+    requiredEnv: opts.requiredEnv,
     navigateBefore: opts.navigateBefore,
   };
 
@@ -112,7 +119,3 @@ export function registerCommand(cmd: CliCommand): void {
   _registry.set(fullName(cmd), cmd);
 }
 
-// Re-export serialization helpers from their dedicated module
-export { serializeArg, serializeCommand, formatArgSummary, formatRegistryHelpText } from './serialization.js';
-export type { SerializedArg } from './serialization.js';
-

package/src/runtime.ts

@@ -10,10 +10,20 @@ export function getBrowserFactory(): new () => IBrowserFactory {
   return (process.env.OPENCLI_CDP_ENDPOINT ? CDPBridge : BrowserBridge) as unknown as new () => IBrowserFactory;
 }
 
-export const DEFAULT_BROWSER_CONNECT_TIMEOUT = parseInt(process.env.OPENCLI_BROWSER_CONNECT_TIMEOUT ?? '30', 10);
-export const DEFAULT_BROWSER_COMMAND_TIMEOUT = parseInt(process.env.OPENCLI_BROWSER_COMMAND_TIMEOUT ?? '60', 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);
+function parseEnvTimeout(envVar: string, fallback: number): number {
+  const raw = process.env[envVar];
+  if (raw === undefined) return fallback;
+  const parsed = parseInt(raw, 10);
+  if (Number.isNaN(parsed) || parsed <= 0) {
+    console.error(`[runtime] Invalid ${envVar}="${raw}", using default ${fallback}s`);
+    return fallback;
+  }
+  return parsed;
+}
+
+export const DEFAULT_BROWSER_CONNECT_TIMEOUT = parseEnvTimeout('OPENCLI_BROWSER_CONNECT_TIMEOUT', 30);
+export const DEFAULT_BROWSER_COMMAND_TIMEOUT = parseEnvTimeout('OPENCLI_BROWSER_COMMAND_TIMEOUT', 60);
+export const DEFAULT_BROWSER_EXPLORE_TIMEOUT = parseEnvTimeout('OPENCLI_BROWSER_EXPLORE_TIMEOUT', 120);
 
 /**
  * Timeout with seconds unit. Used for high-level command timeouts.