@jackwener/opencli 1.1.1 → 1.2.1

package/src/plugin.ts

@@ -0,0 +1,254 @@
+/**
+ * Plugin management: install, uninstall, and list plugins.
+ *
+ * Plugins live in ~/.opencli/plugins/<name>/.
+ * Install source format: "github:user/repo"
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { execSync, execFileSync } from 'node:child_process';
+import { PLUGINS_DIR } from './discovery.js';
+import { log } from './logger.js';
+
+export interface PluginInfo {
+  name: string;
+  path: string;
+  commands: string[];
+  source?: string;
+}
+
+/**
+ * Install a plugin from a source.
+ * Currently supports "github:user/repo" format (git clone wrapper).
+ */
+export function installPlugin(source: string): string {
+  const parsed = parseSource(source);
+  if (!parsed) {
+    throw new Error(
+      `Invalid plugin source: "${source}"\n` +
+      `Supported formats:\n` +
+      `  github:user/repo\n` +
+      `  https://github.com/user/repo`
+    );
+  }
+
+  const { cloneUrl, name } = parsed;
+  const targetDir = path.join(PLUGINS_DIR, name);
+
+  if (fs.existsSync(targetDir)) {
+    throw new Error(`Plugin "${name}" is already installed at ${targetDir}`);
+  }
+
+  // Ensure plugins directory exists
+  fs.mkdirSync(PLUGINS_DIR, { recursive: true });
+
+  try {
+    execFileSync('git', ['clone', '--depth', '1', cloneUrl, targetDir], {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+  } catch (err: any) {
+    throw new Error(`Failed to clone plugin: ${err.message}`);
+  }
+
+  // If the plugin has a package.json, run npm install for regular deps,
+  // then symlink the host opencli into node_modules for peerDep resolution.
+  const pkgJsonPath = path.join(targetDir, 'package.json');
+  if (fs.existsSync(pkgJsonPath)) {
+    try {
+      execFileSync('npm', ['install', '--omit=dev'], {
+        cwd: targetDir,
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+    } catch {
+      // Non-fatal: npm install may fail if no real deps
+    }
+
+    // Symlink host opencli into plugin's node_modules so TS plugins
+    // can resolve '@jackwener/opencli/registry' against the running host.
+    // This is more reliable than depending on the npm-published version
+    // which may lag behind the local installation.
+    linkHostOpencli(targetDir);
+
+    // Transpile TS plugin files to JS so they work in production mode
+    // (node cannot load .ts files directly without tsx).
+    transpilePluginTs(targetDir);
+  }
+
+  return name;
+}
+
+/**
+ * Uninstall a plugin by name.
+ */
+export function uninstallPlugin(name: string): void {
+  const targetDir = path.join(PLUGINS_DIR, name);
+  if (!fs.existsSync(targetDir)) {
+    throw new Error(`Plugin "${name}" is not installed.`);
+  }
+  fs.rmSync(targetDir, { recursive: true, force: true });
+}
+
+/**
+ * List all installed plugins.
+ */
+export function listPlugins(): PluginInfo[] {
+  if (!fs.existsSync(PLUGINS_DIR)) return [];
+
+  const entries = fs.readdirSync(PLUGINS_DIR, { withFileTypes: true });
+  const plugins: PluginInfo[] = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const pluginDir = path.join(PLUGINS_DIR, entry.name);
+    const commands = scanPluginCommands(pluginDir);
+    const source = getPluginSource(pluginDir);
+
+    plugins.push({
+      name: entry.name,
+      path: pluginDir,
+      commands,
+      source,
+    });
+  }
+
+  return plugins;
+}
+
+/** Scan a plugin directory for command files */
+function scanPluginCommands(dir: string): string[] {
+  try {
+    const files = fs.readdirSync(dir);
+    const names = new Set(
+      files
+        .filter(f =>
+          f.endsWith('.yaml') || f.endsWith('.yml') ||
+          (f.endsWith('.ts') && !f.endsWith('.d.ts') && !f.endsWith('.test.ts')) ||
+          (f.endsWith('.js') && !f.endsWith('.d.js'))
+        )
+        .map(f => path.basename(f, path.extname(f)))
+    );
+    return [...names];
+  } catch {
+    return [];
+  }
+}
+
+/** Get git remote origin URL */
+function getPluginSource(dir: string): string | undefined {
+  try {
+    return execSync('git config --get remote.origin.url', {
+      cwd: dir,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+  } catch {
+    return undefined;
+  }
+}
+
+/** Parse a plugin source string into clone URL and name */
+function parseSource(source: string): { cloneUrl: string; name: string } | null {
+  // github:user/repo
+  const githubMatch = source.match(/^github:([\w.-]+)\/([\w.-]+)$/);
+  if (githubMatch) {
+    const [, user, repo] = githubMatch;
+    const name = repo.replace(/^opencli-plugin-/, '');
+    return {
+      cloneUrl: `https://github.com/${user}/${repo}.git`,
+      name,
+    };
+  }
+
+  // https://github.com/user/repo (or .git)
+  const urlMatch = source.match(/^https?:\/\/github\.com\/([\w.-]+)\/([\w.-]+?)(?:\.git)?$/);
+  if (urlMatch) {
+    const [, user, repo] = urlMatch;
+    const name = repo.replace(/^opencli-plugin-/, '');
+    return {
+      cloneUrl: `https://github.com/${user}/${repo}.git`,
+      name,
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Symlink the host opencli package into a plugin's node_modules.
+ * This ensures TS plugins resolve '@jackwener/opencli/registry' against
+ * the running host installation rather than a stale npm-published version.
+ */
+function linkHostOpencli(pluginDir: string): void {
+  try {
+    // 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 hostRoot = path.resolve(path.dirname(thisFile), '..');
+
+    const targetLink = path.join(pluginDir, 'node_modules', '@jackwener', 'opencli');
+
+    // Remove existing (npm-installed copy or stale symlink)
+    if (fs.existsSync(targetLink)) {
+      fs.rmSync(targetLink, { recursive: true, force: true });
+    }
+
+    // Ensure parent directory exists
+    fs.mkdirSync(path.dirname(targetLink), { recursive: true });
+
+    // Create symlink
+    fs.symlinkSync(hostRoot, targetLink, 'dir');
+    log.debug(`Linked host opencli into plugin: ${targetLink} → ${hostRoot}`);
+  } catch (err: any) {
+    log.warn(`Failed to link host opencli into plugin: ${err.message}`);
+  }
+}
+
+/**
+ * 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');
+
+    if (!fs.existsSync(esbuildBin)) {
+      log.debug('esbuild not found in host node_modules, skipping TS transpilation');
+      return;
+    }
+
+    const files = fs.readdirSync(pluginDir);
+    const tsFiles = files.filter(f =>
+      f.endsWith('.ts') && !f.endsWith('.d.ts') && !f.endsWith('.test.ts')
+    );
+
+    for (const tsFile of tsFiles) {
+      const jsFile = tsFile.replace(/\.ts$/, '.js');
+      const jsPath = path.join(pluginDir, jsFile);
+
+      // Skip if .js already exists (plugin may ship pre-compiled)
+      if (fs.existsSync(jsPath)) continue;
+
+      try {
+        execFileSync(esbuildBin, [tsFile, `--outfile=${jsFile}`, '--format=esm', '--platform=node'], {
+          cwd: pluginDir,
+          encoding: 'utf-8',
+          stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        log.debug(`Transpiled plugin file: ${tsFile} → ${jsFile}`);
+      } catch (err: any) {
+        log.warn(`Failed to transpile ${tsFile}: ${err.message}`);
+      }
+    }
+  } catch {
+    // Non-fatal: skip transpilation if anything goes wrong
+  }
+}
+
+export { parseSource as _parseSource };

package/src/registry-api.ts

@@ -0,0 +1,12 @@
+/**
+ * Public API for opencli plugins.
+ *
+ * TS plugins should import from '@jackwener/opencli/registry' which resolves to
+ * this file. It re-exports ONLY the core registration API — no serialization,
+ * no transitive side-effects — to avoid circular dependency deadlocks when
+ * plugins are dynamically imported during discoverPlugins().
+ */
+
+export { cli, Strategy, getRegistry, fullName, registerCommand } from './registry.js';
+export type { CliCommand, Arg, CliOptions } from './registry.js';
+export type { IPage } from './types.js';

package/src/registry.ts

@@ -36,6 +36,17 @@ export interface CliCommand {
   timeoutSeconds?: number;
   source?: string;
   footerExtra?: (kwargs: Record<string, any>) => string | undefined;
+  /**
+   * Control pre-navigation for cookie/header context before command execution.
+   *
+   * Browser adapters using COOKIE/HEADER strategy need the page to be on the
+   * target domain so that `fetch(url, { credentials: 'include' })` carries cookies.
+   *
+   * - `undefined` / `true`: navigate to `https://${domain}` (default)
+   * - `false`: skip — adapter handles its own navigation (e.g. boss common.ts)
+   * - `string`: navigate to this specific URL instead of the domain root
+   */
+  navigateBefore?: boolean | string;
 }
 
 /** Internal extension for lazy-loaded TS modules (not exposed in public API) */
@@ -49,7 +60,13 @@ export interface CliOptions extends Partial<Omit<CliCommand, 'args' | 'descripti
   description?: string;
   args?: Arg[];
 }
-const _registry = new Map<string, CliCommand>();
+
+// Use globalThis to ensure a single shared registry across all module instances.
+// This is critical for TS plugins loaded via npm link / peerDependency — without
+// this, the plugin's import creates a separate module instance with its own Map.
+const REGISTRY_KEY = '__opencli_registry__';
+const _registry: Map<string, CliCommand> =
+  (globalThis as any)[REGISTRY_KEY] ??= new Map<string, CliCommand>();
 
 export function cli(opts: CliOptions): CliCommand {
   const strategy = opts.strategy ?? (opts.browser === false ? Strategy.PUBLIC : Strategy.COOKIE);
@@ -67,6 +84,7 @@ export function cli(opts: CliOptions): CliCommand {
     pipeline: opts.pipeline,
     timeoutSeconds: opts.timeoutSeconds,
     footerExtra: opts.footerExtra,
+    navigateBefore: opts.navigateBefore,
   };
 
   const key = fullName(cmd);

package/src/synthesize.ts

@@ -7,16 +7,96 @@ 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';
+import type { ExploreAuthSummary, ExploreEndpointArtifact, ExploreManifest } from './explore.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;
 
+interface RecommendedArg {
+  name: string;
+  type?: string;
+  required?: boolean;
+  default?: unknown;
+}
+
+interface StoreHint {
+  store: string;
+  action: string;
+}
+
+export interface SynthesizeCapability {
+  name: string;
+  description: string;
+  strategy: string;
+  confidence?: number;
+  endpoint?: string;
+  itemPath?: string | null;
+  recommendedColumns?: string[];
+  recommendedArgs?: RecommendedArg[];
+  recommended_args?: RecommendedArg[];
+  recommendedColumnsLegacy?: string[];
+  recommended_columns?: string[];
+  storeHint?: StoreHint;
+}
+
+export interface GeneratedArgDefinition {
+  type: string;
+  required?: boolean;
+  default?: unknown;
+  description?: string;
+}
+
+type CandidatePipelineStep =
+  | { navigate: string }
+  | { wait: number }
+  | { evaluate: string }
+  | { select: string }
+  | { map: Record<string, string> }
+  | { limit: string }
+  | { fetch: { url: string } }
+  | { tap: { store: string; action: string; timeout: number; capture?: string; select?: string | null } };
+
+export interface CandidateYaml {
+  site: string;
+  name: string;
+  description: string;
+  domain: string;
+  strategy: string;
+  browser: boolean;
+  args: Record<string, GeneratedArgDefinition>;
+  pipeline: CandidatePipelineStep[];
+  columns: string[];
+}
+
+export interface SynthesizeCandidateSummary {
+  name: string;
+  path: string;
+  strategy: string;
+  confidence?: number;
+}
+
+export interface SynthesizeResult {
+  site: string;
+  explore_dir: string;
+  out_dir: string;
+  candidate_count: number;
+  candidates: SynthesizeCandidateSummary[];
+}
+
+type ExploreManifestLike = Pick<ExploreManifest, 'target_url' | 'final_url'> & Partial<ExploreManifest>;
+interface LoadedExploreBundle {
+  manifest: ExploreManifest;
+  endpoints: ExploreEndpointArtifact[];
+  capabilities: SynthesizeCapability[];
+  auth: ExploreAuthSummary;
+}
+
 export function synthesizeFromExplore(
   target: string,
   opts: { outDir?: string; top?: number } = {},
-): Record<string, any> {
+): SynthesizeResult {
   const exploreDir = resolveExploreDir(target);
   const bundle = loadExploreBundle(exploreDir);
 
@@ -25,9 +105,9 @@ export function synthesizeFromExplore(
 
   const site = bundle.manifest.site;
   const capabilities = (bundle.capabilities ?? [])
-    .sort((a: any, b: any) => (b.confidence ?? 0) - (a.confidence ?? 0))
+    .sort((a, b) => (b.confidence ?? 0) - (a.confidence ?? 0))
     .slice(0, opts.top ?? 3);
-  const candidates: any[] = [];
+  const candidates: SynthesizeCandidateSummary[] = [];
 
   for (const cap of capabilities) {
     const endpoint = chooseEndpoint(cap, bundle.endpoints);
@@ -44,7 +124,7 @@ export function synthesizeFromExplore(
   return { site, explore_dir: exploreDir, out_dir: targetDir, candidate_count: candidates.length, candidates };
 }
 
-export function renderSynthesizeSummary(result: Record<string, any>): string {
+export function renderSynthesizeSummary(result: SynthesizeResult): string {
   const lines = ['opencli synthesize: OK', `Site: ${result.site}`, `Source: ${result.explore_dir}`, `Candidates: ${result.candidate_count}`];
   for (const c of result.candidates ?? []) lines.push(`  • ${c.name} (${c.strategy}, ${((c.confidence ?? 0) * 100).toFixed(0)}% confidence) → ${c.path}`);
   return lines.join('\n');
@@ -57,33 +137,34 @@ export function resolveExploreDir(target: string): string {
   throw new Error(`Explore directory not found: ${target}`);
 }
 
-export function loadExploreBundle(exploreDir: string): Record<string, any> {
+export function loadExploreBundle(exploreDir: string): LoadedExploreBundle {
   return {
-    manifest: JSON.parse(fs.readFileSync(path.join(exploreDir, 'manifest.json'), 'utf-8')),
-    endpoints: JSON.parse(fs.readFileSync(path.join(exploreDir, 'endpoints.json'), 'utf-8')),
-    capabilities: JSON.parse(fs.readFileSync(path.join(exploreDir, 'capabilities.json'), 'utf-8')),
+    manifest: JSON.parse(fs.readFileSync(path.join(exploreDir, 'manifest.json'), 'utf-8')) as ExploreManifest,
+    endpoints: JSON.parse(fs.readFileSync(path.join(exploreDir, 'endpoints.json'), 'utf-8')) as ExploreEndpointArtifact[],
+    capabilities: JSON.parse(fs.readFileSync(path.join(exploreDir, 'capabilities.json'), 'utf-8')) as SynthesizeCapability[],
     auth: JSON.parse(fs.readFileSync(path.join(exploreDir, 'auth.json'), 'utf-8')),
   };
 }
 
-function chooseEndpoint(cap: any, endpoints: any[]): any | null {
+function chooseEndpoint(cap: SynthesizeCapability, endpoints: ExploreEndpointArtifact[]): ExploreEndpointArtifact | null {
   if (!endpoints.length) return null;
   // Match by endpoint pattern from capability
   if (cap.endpoint) {
-    const match = endpoints.find((e: any) => e.pattern === cap.endpoint || e.url?.includes(cap.endpoint));
+    const endpointPattern = cap.endpoint;
+    const match = endpoints.find((endpoint) => endpoint.pattern === endpointPattern || endpoint.url?.includes(endpointPattern));
     if (match) return match;
   }
-  return endpoints.sort((a: any, b: any) => (b.score ?? 0) - (a.score ?? 0))[0];
+  return [...endpoints].sort((a, b) => (b.score ?? 0) - (a.score ?? 0))[0];
 }
 
 // ── URL templating ─────────────────────────────────────────────────────────
 
-function buildTemplatedUrl(rawUrl: string, cap: any, _endpoint: any): string {
+function buildTemplatedUrl(rawUrl: string, cap: SynthesizeCapability, _endpoint: ExploreEndpointArtifact): string {
   try {
     const u = new URL(rawUrl);
     const base = `${u.protocol}//${u.host}${u.pathname}`;
     const params: Array<[string, string]> = [];
-    const hasKeyword = cap.recommendedArgs?.some((a: any) => a.name === 'keyword');
+    const hasKeyword = cap.recommendedArgs?.some((arg) => arg.name === 'keyword');
 
     u.searchParams.forEach((v, k) => {
       if (VOLATILE_PARAMS.has(k)) return;
@@ -101,7 +182,7 @@ function buildTemplatedUrl(rawUrl: string, cap: any, _endpoint: any): string {
  * Build inline evaluate script for browser-based fetch+parse.
  * Follows patterns from bilibili/hot.yaml and twitter/trending.yaml.
  */
-function buildEvaluateScript(url: string, itemPath: string, endpoint: any): string {
+function buildEvaluateScript(url: string, itemPath: string, endpoint: ExploreEndpointArtifact): string {
   const pathChain = itemPath.split('.').map((p: string) => `?.${p}`).join('');
   const detectedFields = endpoint?.detectedFields ?? {};
   const hasFields = Object.keys(detectedFields).length > 0;
@@ -127,9 +208,9 @@ function buildEvaluateScript(url: string, itemPath: string, endpoint: any): stri
 
 // ── YAML pipeline generation ───────────────────────────────────────────────
 
-function buildCandidateYaml(site: string, manifest: any, cap: any, endpoint: any): { name: string; yaml: any } {
+function buildCandidateYaml(site: string, manifest: ExploreManifestLike, cap: SynthesizeCapability, endpoint: ExploreEndpointArtifact): { name: string; yaml: CandidateYaml } {
   const needsBrowser = cap.strategy !== 'public';
-  const pipeline: any[] = [];
+  const pipeline: CandidatePipelineStep[] = [];
   const templatedUrl = buildTemplatedUrl(endpoint?.url ?? manifest.target_url, cap, endpoint);
 
   let domain = '';
@@ -139,7 +220,7 @@ function buildCandidateYaml(site: string, manifest: any, cap: any, endpoint: any
     // Store Action: navigate + wait + tap (declarative, clean)
     pipeline.push({ navigate: manifest.target_url });
     pipeline.push({ wait: 3 });
-    const tapStep: Record<string, any> = {
+    const tapStep: { store: string; action: string; timeout: number; capture?: string; select?: string | null } = {
       store: cap.storeHint.store,
       action: cap.storeHint.action,
       timeout: 8,
@@ -170,7 +251,7 @@ function buildCandidateYaml(site: string, manifest: any, cap: any, endpoint: any
   // Map fields
   const mapStep: Record<string, string> = {};
   const columns = cap.recommendedColumns ?? ['title', 'url'];
-  if (!cap.recommendedArgs?.some((a: any) => a.name === 'keyword')) mapStep['rank'] = '${{ index + 1 }}';
+  if (!cap.recommendedArgs?.some((arg) => arg.name === 'keyword')) mapStep['rank'] = '${{ index + 1 }}';
   const detectedFields = endpoint?.detectedFields ?? {};
   for (const col of columns) {
     const fieldPath = detectedFields[col];
@@ -180,9 +261,9 @@ function buildCandidateYaml(site: string, manifest: any, cap: any, endpoint: any
   pipeline.push({ limit: '${{ args.limit | default(20) }}' });
 
   // Args
-  const argsDef: Record<string, any> = {};
+  const argsDef: Record<string, GeneratedArgDefinition> = {};
   for (const arg of cap.recommendedArgs ?? []) {
-    const def: any = { type: arg.type ?? 'str' };
+    const def: GeneratedArgDefinition = { type: arg.type ?? 'str' };
     if (arg.required) def.required = true;
     if (arg.default != null) def.default = arg.default;
     if (arg.name === 'keyword') def.description = 'Search keyword';
@@ -203,7 +284,7 @@ function buildCandidateYaml(site: string, manifest: any, cap: any, endpoint: any
 }
 
 /** Backward-compatible export for scaffold.ts */
-export function buildCandidate(site: string, targetUrl: string, cap: any, endpoint: any): any {
+export function buildCandidate(site: string, targetUrl: string, cap: SynthesizeCapability, endpoint: ExploreEndpointArtifact): { name: string; yaml: CandidateYaml } {
   // Map old-style field names to new ones
   const normalizedCap = {
     ...cap,

package/src/types.ts

@@ -5,23 +5,55 @@
  * instead of `any` for browser interactions.
  */
 
+export interface BrowserCookie {
+  name: string;
+  value: string;
+  domain: string;
+  path?: string;
+  secure?: boolean;
+  httpOnly?: boolean;
+  expirationDate?: number;
+}
+
+export interface SnapshotOptions {
+  interactive?: boolean;
+  compact?: boolean;
+  maxDepth?: number;
+  raw?: boolean;
+  viewportExpand?: number;
+  maxTextLength?: number;
+}
+
+export interface WaitOptions {
+  text?: string;
+  time?: number;
+  timeout?: number;
+}
+
+export interface ScreenshotOptions {
+  format?: 'png' | 'jpeg';
+  quality?: number;
+  fullPage?: boolean;
+  path?: string;
+}
+
+export interface BrowserSessionInfo {
+  workspace?: string;
+  connected?: boolean;
+  [key: string]: unknown;
+}
+
 export interface IPage {
   goto(url: string, options?: { waitUntil?: 'load' | 'none'; settleMs?: number }): Promise<void>;
   evaluate(js: string): Promise<any>;
-  getCookies(opts?: { domain?: string; url?: string }): Promise<Array<{
-    name: string;
-    value: string;
-    domain: string;
-    path?: string;
-    secure?: boolean;
-    httpOnly?: boolean;
-    expirationDate?: number;
-  }>>;
-  snapshot(opts?: { interactive?: boolean; compact?: boolean; maxDepth?: number; raw?: boolean }): Promise<any>;
+  getCookies(opts?: { domain?: string; url?: string }): Promise<BrowserCookie[]>;
+  snapshot(opts?: SnapshotOptions): Promise<any>;
   click(ref: string): Promise<void>;
   typeText(ref: string, text: string): Promise<void>;
   pressKey(key: string): Promise<void>;
-  wait(options: number | { text?: string; time?: number; timeout?: number }): Promise<void>;
+  scrollTo(ref: string): Promise<any>;
+  getFormState(): Promise<any>;
+  wait(options: number | WaitOptions): Promise<void>;
   tabs(): Promise<any>;
   closeTab(index?: number): Promise<void>;
   newTab(): Promise<void>;
@@ -32,5 +64,5 @@ export interface IPage {
   autoScroll(options?: { times?: number; delayMs?: number }): Promise<void>;
   installInterceptor(pattern: string): Promise<void>;
   getInterceptedRequests(): Promise<any[]>;
-  screenshot(options?: { format?: 'png' | 'jpeg'; quality?: number; fullPage?: boolean; path?: string }): Promise<string>;
+  screenshot(options?: ScreenshotOptions): Promise<string>;
 }

package/src/validate.ts

@@ -25,6 +25,22 @@ export interface ValidationReport {
   files: number;
 }
 
+interface ValidatedYamlCliDefinition {
+  site?: string;
+  name?: string;
+  pipeline?: unknown[];
+  columns?: unknown[];
+  args?: Record<string, unknown>;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function getErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
 export function validateClisWithTarget(dirs: string[], target?: string): ValidationReport {
   const results: FileValidationResult[] = [];
   let errors = 0; let warnings = 0; let files = 0;
@@ -53,8 +69,8 @@ function validateYamlFile(filePath: string): FileValidationResult {
   const errors: string[] = []; const warnings: string[] = [];
   try {
     const raw = fs.readFileSync(filePath, 'utf-8');
-    const def = yaml.load(raw) as any;
-    if (!def || typeof def !== 'object') { errors.push('Not a valid YAML object'); return { path: filePath, errors, warnings }; }
+    const def = yaml.load(raw) as ValidatedYamlCliDefinition | null;
+    if (!isRecord(def)) { errors.push('Not a valid YAML object'); return { path: filePath, errors, warnings }; }
     if (!def.site) errors.push('Missing "site"');
     if (!def.name) errors.push('Missing "name"');
     if (def.pipeline && !Array.isArray(def.pipeline)) errors.push('"pipeline" must be an array');
@@ -74,7 +90,7 @@ function validateYamlFile(filePath: string): FileValidationResult {
         }
       }
     }
-  } catch (e: any) { errors.push(`YAML parse error: ${e.message}`); }
+  } catch (e) { errors.push(`YAML parse error: ${getErrorMessage(e)}`); }
   return { path: filePath, errors, warnings };
 }
 
@@ -89,4 +105,3 @@ export function renderValidationReport(report: ValidationReport): string {
   }
   return lines.join('\n');
 }
-

package/tests/e2e/browser-public.test.ts

@@ -186,6 +186,17 @@ describe('browser public-data commands E2E', () => {
     expectDataOrSkip(data, 'xiaohongshu search');
   }, 60_000);
 
+  // ── google search (browser: true, public strategy) ──
+  it('google search returns results', async () => {
+    const data = await tryBrowserCommand(['google', 'search', 'typescript', '--limit', '5', '-f', 'json']);
+    expectDataOrSkip(data, 'google search');
+    if (data) {
+      expect(data[0]).toHaveProperty('type');
+      expect(data[0]).toHaveProperty('title');
+      expect(data[0]).toHaveProperty('url');
+    }
+  }, 60_000);
+
   // ── yahoo-finance (browser: true) ──
   it('yahoo-finance quote returns stock data', async () => {
     const data = await tryBrowserCommand(['yahoo-finance', 'quote', '--symbol', 'AAPL', '-f', 'json']);