@jackwener/opencli 0.6.1 → 0.6.2

package/src/pipeline/executor.test.ts

@@ -0,0 +1,161 @@
+/**
+ * Tests for pipeline/executor.ts: pipeline execution with mock page.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { executePipeline } from './index.js';
+import type { IPage } from '../types.js';
+
+/** Create a minimal mock page for testing */
+function createMockPage(overrides: Partial<IPage> = {}): IPage {
+  return {
+    goto: vi.fn(),
+    evaluate: vi.fn().mockResolvedValue(null),
+    snapshot: vi.fn().mockResolvedValue(''),
+    click: vi.fn(),
+    typeText: vi.fn(),
+    pressKey: vi.fn(),
+    wait: vi.fn(),
+    tabs: vi.fn().mockResolvedValue([]),
+    closeTab: vi.fn(),
+    newTab: vi.fn(),
+    selectTab: vi.fn(),
+    networkRequests: vi.fn().mockResolvedValue([]),
+    consoleMessages: vi.fn().mockResolvedValue(''),
+    scroll: vi.fn(),
+    autoScroll: vi.fn(),
+    installInterceptor: vi.fn(),
+    getInterceptedRequests: vi.fn().mockResolvedValue([]),
+    ...overrides,
+  };
+}
+
+describe('executePipeline', () => {
+  it('returns null for empty pipeline', async () => {
+    const result = await executePipeline(null, []);
+    expect(result).toBeNull();
+  });
+
+  it('skips null/invalid steps', async () => {
+    const result = await executePipeline(null, [null, undefined, 42] as any);
+    expect(result).toBeNull();
+  });
+
+  it('executes navigate step', async () => {
+    const page = createMockPage();
+    await executePipeline(page, [
+      { navigate: 'https://example.com' },
+    ]);
+    expect(page.goto).toHaveBeenCalledWith('https://example.com');
+  });
+
+  it('executes evaluate + select pipeline', async () => {
+    const page = createMockPage({
+      evaluate: vi.fn().mockResolvedValue({ data: { list: [{ name: 'a' }, { name: 'b' }] } }),
+    });
+    const result = await executePipeline(page, [
+      { evaluate: '() => ({ data: { list: [{name: "a"}, {name: "b"}] } })' },
+      { select: 'data.list' },
+    ]);
+    expect(result).toEqual([{ name: 'a' }, { name: 'b' }]);
+  });
+
+  it('executes map step to transform items', async () => {
+    const page = createMockPage({
+      evaluate: vi.fn().mockResolvedValue([
+        { title: 'Hello', count: 10 },
+        { title: 'World', count: 20 },
+      ]),
+    });
+    const result = await executePipeline(page, [
+      { evaluate: 'test' },
+      { map: { name: '${{ item.title }}', score: '${{ item.count }}' } },
+    ]);
+    expect(result).toEqual([
+      { name: 'Hello', score: 10 },
+      { name: 'World', score: 20 },
+    ]);
+  });
+
+  it('executes limit step', async () => {
+    const page = createMockPage({
+      evaluate: vi.fn().mockResolvedValue([1, 2, 3, 4, 5]),
+    });
+    const result = await executePipeline(page, [
+      { evaluate: 'test' },
+      { limit: '3' },
+    ]);
+    expect(result).toEqual([1, 2, 3]);
+  });
+
+  it('executes sort step', async () => {
+    const page = createMockPage({
+      evaluate: vi.fn().mockResolvedValue([{ n: 3 }, { n: 1 }, { n: 2 }]),
+    });
+    const result = await executePipeline(page, [
+      { evaluate: 'test' },
+      { sort: { by: 'n', order: 'asc' } },
+    ]);
+    expect(result).toEqual([{ n: 1 }, { n: 2 }, { n: 3 }]);
+  });
+
+  it('executes sort step with desc order', async () => {
+    const page = createMockPage({
+      evaluate: vi.fn().mockResolvedValue([{ n: 1 }, { n: 3 }, { n: 2 }]),
+    });
+    const result = await executePipeline(page, [
+      { evaluate: 'test' },
+      { sort: { by: 'n', order: 'desc' } },
+    ]);
+    expect(result).toEqual([{ n: 3 }, { n: 2 }, { n: 1 }]);
+  });
+
+  it('executes wait step with number', async () => {
+    const page = createMockPage();
+    await executePipeline(page, [
+      { wait: 2 },
+    ]);
+    expect(page.wait).toHaveBeenCalledWith(2);
+  });
+
+  it('handles unknown steps gracefully in debug mode', async () => {
+    const stderr = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    await executePipeline(null, [
+      { unknownStep: 'test' },
+    ], { debug: true });
+    expect(stderr).toHaveBeenCalledWith(expect.stringContaining('Unknown step'));
+    stderr.mockRestore();
+  });
+
+  it('passes args through template rendering', async () => {
+    const page = createMockPage({
+      evaluate: vi.fn().mockResolvedValue([1, 2, 3, 4, 5]),
+    });
+    const result = await executePipeline(page, [
+      { evaluate: 'test' },
+      { limit: '${{ args.count }}' },
+    ], { args: { count: 2 } });
+    expect(result).toEqual([1, 2]);
+  });
+
+  it('click step calls page.click', async () => {
+    const page = createMockPage();
+    await executePipeline(page, [
+      { click: '@5' },
+    ]);
+    expect(page.click).toHaveBeenCalledWith('5');
+  });
+
+  it('navigate preserves existing data through pipeline', async () => {
+    const page = createMockPage({
+      evaluate: vi.fn().mockResolvedValue([{ a: 1 }]),
+    });
+    const result = await executePipeline(page, [
+      { evaluate: 'test' },
+      { navigate: 'https://example.com' },
+    ]);
+    // navigate should preserve existing data
+    expect(result).toEqual([{ a: 1 }]);
+    expect(page.goto).toHaveBeenCalledWith('https://example.com');
+  });
+});

package/src/pipeline/executor.ts

@@ -60,11 +60,6 @@ export async function executePipeline(
         if (debug) process.stderr.write(`  ${chalk.yellow('⚠')}  Unknown step: ${op}\n`);
       }
 
-      // Detect error objects returned by steps (e.g. tap store not found)
-      if (data && typeof data === 'object' && !Array.isArray(data) && data.error) {
-        process.stderr.write(`  ${chalk.yellow('⚠')}  ${chalk.yellow(op)}: ${data.error}\n`);
-        if (data.hint) process.stderr.write(`  ${chalk.dim('💡')} ${chalk.dim(data.hint)}\n`);
-      }
       if (debug) debugStepResult(op, data);
     }
   }

package/src/pipeline/steps/fetch.ts

@@ -45,11 +45,12 @@ async function fetchSingle(
   }
 
   const headersJs = JSON.stringify(renderedHeaders);
-  const escapedUrl = finalUrl.replace(/"/g, '\\"');
+  const urlJs = JSON.stringify(finalUrl);
+  const methodJs = JSON.stringify(method.toUpperCase());
   return page.evaluate(`
     async () => {
-      const resp = await fetch("${escapedUrl}", {
-        method: "${method}", headers: ${headersJs}, credentials: "include"
+      const resp = await fetch(${urlJs}, {
+        method: ${methodJs}, headers: ${headersJs}, credentials: "include"
       });
       return await resp.json();
     }

package/src/registry.ts

@@ -30,7 +30,7 @@ export interface CliCommand {
   browser?: boolean;
   args: Arg[];
   columns?: string[];
-  func?: (page: IPage | null, kwargs: Record<string, any>, debug?: boolean) => Promise<any>;
+  func?: (page: IPage, kwargs: Record<string, any>, debug?: boolean) => Promise<any>;
   pipeline?: any[];
   timeoutSeconds?: number;
   source?: string;
@@ -50,7 +50,7 @@ export interface CliOptions {
   browser?: boolean;
   args?: Arg[];
   columns?: string[];
-  func?: (page: IPage | null, kwargs: Record<string, any>, debug?: boolean) => Promise<any>;
+  func?: (page: IPage, kwargs: Record<string, any>, debug?: boolean) => Promise<any>;
   pipeline?: any[];
   timeoutSeconds?: number;
 }

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

@@ -0,0 +1,90 @@
+/**
+ * E2E tests for login-required browser commands.
+ * These commands REQUIRE authentication (cookie/session).
+ * In CI (headless, no login), they should fail gracefully — NOT crash.
+ *
+ * These tests verify the error handling path, not the data extraction.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { runCli } from './helpers.js';
+
+/**
+ * Verify a login-required command fails gracefully (no crash, no hang).
+ * Acceptable outcomes: exit code 1 with error message, OR timeout handled.
+ */
+async function expectGracefulAuthFailure(args: string[], label: string) {
+  const { stdout, stderr, code } = await runCli(args, { timeout: 60_000 });
+  // Should either fail with exit code 1 (error message) or succeed with empty data
+  // The key assertion: it should NOT hang forever or crash with unhandled exception
+  if (code !== 0) {
+    // Verify stderr has a meaningful error, not an unhandled crash
+    const output = stderr + stdout;
+    expect(output.length).toBeGreaterThan(0);
+  }
+  // If it somehow succeeds (e.g., partial public data), that's fine too
+}
+
+describe('login-required commands — graceful failure', () => {
+
+  // ── bilibili (requires cookie session) ──
+  it('bilibili me fails gracefully without login', async () => {
+    await expectGracefulAuthFailure(['bilibili', 'me', '-f', 'json'], 'bilibili me');
+  }, 60_000);
+
+  it('bilibili dynamic fails gracefully without login', async () => {
+    await expectGracefulAuthFailure(['bilibili', 'dynamic', '--limit', '3', '-f', 'json'], 'bilibili dynamic');
+  }, 60_000);
+
+  it('bilibili favorite fails gracefully without login', async () => {
+    await expectGracefulAuthFailure(['bilibili', 'favorite', '--limit', '3', '-f', 'json'], 'bilibili favorite');
+  }, 60_000);
+
+  it('bilibili history fails gracefully without login', async () => {
+    await expectGracefulAuthFailure(['bilibili', 'history', '--limit', '3', '-f', 'json'], 'bilibili history');
+  }, 60_000);
+
+  it('bilibili following fails gracefully without login', async () => {
+    await expectGracefulAuthFailure(['bilibili', 'following', '--limit', '3', '-f', 'json'], 'bilibili following');
+  }, 60_000);
+
+  // ── twitter (requires login) ──
+  it('twitter bookmarks fails gracefully without login', async () => {
+    await expectGracefulAuthFailure(['twitter', 'bookmarks', '--limit', '3', '-f', 'json'], 'twitter bookmarks');
+  }, 60_000);
+
+  it('twitter timeline fails gracefully without login', async () => {
+    await expectGracefulAuthFailure(['twitter', 'timeline', '--limit', '3', '-f', 'json'], 'twitter timeline');
+  }, 60_000);
+
+  it('twitter notifications fails gracefully without login', async () => {
+    await expectGracefulAuthFailure(['twitter', 'notifications', '--limit', '3', '-f', 'json'], 'twitter notifications');
+  }, 60_000);
+
+  // ── v2ex (requires login) ──
+  it('v2ex me fails gracefully without login', async () => {
+    await expectGracefulAuthFailure(['v2ex', 'me', '-f', 'json'], 'v2ex me');
+  }, 60_000);
+
+  it('v2ex notifications fails gracefully without login', async () => {
+    await expectGracefulAuthFailure(['v2ex', 'notifications', '--limit', '3', '-f', 'json'], 'v2ex notifications');
+  }, 60_000);
+
+  // ── xueqiu (requires login) ──
+  it('xueqiu feed fails gracefully without login', async () => {
+    await expectGracefulAuthFailure(['xueqiu', 'feed', '--limit', '3', '-f', 'json'], 'xueqiu feed');
+  }, 60_000);
+
+  it('xueqiu watchlist fails gracefully without login', async () => {
+    await expectGracefulAuthFailure(['xueqiu', 'watchlist', '-f', 'json'], 'xueqiu watchlist');
+  }, 60_000);
+
+  // ── xiaohongshu (requires login) ──
+  it('xiaohongshu feed fails gracefully without login', async () => {
+    await expectGracefulAuthFailure(['xiaohongshu', 'feed', '--limit', '3', '-f', 'json'], 'xiaohongshu feed');
+  }, 60_000);
+
+  it('xiaohongshu notifications fails gracefully without login', async () => {
+    await expectGracefulAuthFailure(['xiaohongshu', 'notifications', '--limit', '3', '-f', 'json'], 'xiaohongshu notifications');
+  }, 60_000);
+});

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

@@ -0,0 +1,169 @@
+/**
+ * E2E tests for browser commands that access PUBLIC data (no login required).
+ * These use OPENCLI_HEADLESS=1 to launch a headless Chromium.
+ *
+ * NOTE: Some sites may block headless browsers with bot detection.
+ * Tests are wrapped with tryBrowserCommand() which allows graceful failure.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { runCli, parseJsonOutput } from './helpers.js';
+
+/**
+ * Run a browser command — returns parsed data or null on failure.
+ */
+async function tryBrowserCommand(args: string[]): Promise<any[] | null> {
+  const { stdout, code } = await runCli(args, { timeout: 60_000 });
+  if (code !== 0) return null;
+  try {
+    const data = parseJsonOutput(stdout);
+    return Array.isArray(data) ? data : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Assert browser command returns data OR log a warning if blocked.
+ * Empty results (bot detection, geo-blocking) are treated as a warning, not a failure.
+ */
+function expectDataOrSkip(data: any[] | null, label: string) {
+  if (data === null || data.length === 0) {
+    console.warn(`${label}: skipped — no data returned (likely bot detection or geo-blocking)`);
+    return;
+  }
+  expect(data.length).toBeGreaterThanOrEqual(1);
+}
+
+describe('browser public-data commands E2E', () => {
+
+  // ── bbc (browser: true, strategy: public) ──
+  it('bbc news returns headlines', async () => {
+    const data = await tryBrowserCommand(['bbc', 'news', '--limit', '3', '-f', 'json']);
+    expectDataOrSkip(data, 'bbc news');
+    if (data) {
+      expect(data[0]).toHaveProperty('title');
+    }
+  }, 60_000);
+
+  // ── v2ex daily (browser: true) ──
+  it('v2ex daily returns topics', async () => {
+    const data = await tryBrowserCommand(['v2ex', 'daily', '--limit', '3', '-f', 'json']);
+    expectDataOrSkip(data, 'v2ex daily');
+  }, 60_000);
+
+  // ── bilibili (browser: true, cookie strategy) ──
+  it('bilibili hot returns trending videos', async () => {
+    const data = await tryBrowserCommand(['bilibili', 'hot', '--limit', '5', '-f', 'json']);
+    expectDataOrSkip(data, 'bilibili hot');
+    if (data) {
+      expect(data[0]).toHaveProperty('title');
+    }
+  }, 60_000);
+
+  it('bilibili ranking returns ranked videos', async () => {
+    const data = await tryBrowserCommand(['bilibili', 'ranking', '--limit', '5', '-f', 'json']);
+    expectDataOrSkip(data, 'bilibili ranking');
+  }, 60_000);
+
+  it('bilibili search returns results', async () => {
+    const data = await tryBrowserCommand(['bilibili', 'search', '--keyword', 'typescript', '--limit', '3', '-f', 'json']);
+    expectDataOrSkip(data, 'bilibili search');
+  }, 60_000);
+
+  // ── weibo (browser: true, cookie strategy) ──
+  it('weibo hot returns trending topics', async () => {
+    const data = await tryBrowserCommand(['weibo', 'hot', '--limit', '5', '-f', 'json']);
+    expectDataOrSkip(data, 'weibo hot');
+  }, 60_000);
+
+  // ── zhihu (browser: true, cookie strategy) ──
+  it('zhihu hot returns trending questions', async () => {
+    const data = await tryBrowserCommand(['zhihu', 'hot', '--limit', '5', '-f', 'json']);
+    expectDataOrSkip(data, 'zhihu hot');
+    if (data) {
+      expect(data[0]).toHaveProperty('title');
+    }
+  }, 60_000);
+
+  it('zhihu search returns results', async () => {
+    const data = await tryBrowserCommand(['zhihu', 'search', '--keyword', 'playwright', '--limit', '3', '-f', 'json']);
+    expectDataOrSkip(data, 'zhihu search');
+  }, 60_000);
+
+  // ── reddit (browser: true, cookie strategy) ──
+  it('reddit hot returns posts', async () => {
+    const data = await tryBrowserCommand(['reddit', 'hot', '--limit', '5', '-f', 'json']);
+    expectDataOrSkip(data, 'reddit hot');
+  }, 60_000);
+
+  it('reddit frontpage returns posts', async () => {
+    const data = await tryBrowserCommand(['reddit', 'frontpage', '--limit', '5', '-f', 'json']);
+    expectDataOrSkip(data, 'reddit frontpage');
+  }, 60_000);
+
+  // ── twitter (browser: true) ──
+  it('twitter trending returns trends', async () => {
+    const data = await tryBrowserCommand(['twitter', 'trending', '--limit', '5', '-f', 'json']);
+    expectDataOrSkip(data, 'twitter trending');
+  }, 60_000);
+
+  // ── xueqiu (browser: true, cookie strategy) ──
+  it('xueqiu hot returns hot posts', async () => {
+    const data = await tryBrowserCommand(['xueqiu', 'hot', '--limit', '5', '-f', 'json']);
+    expectDataOrSkip(data, 'xueqiu hot');
+  }, 60_000);
+
+  it('xueqiu hot-stock returns stocks', async () => {
+    const data = await tryBrowserCommand(['xueqiu', 'hot-stock', '--limit', '5', '-f', 'json']);
+    expectDataOrSkip(data, 'xueqiu hot-stock');
+  }, 60_000);
+
+  // ── reuters (browser: true) ──
+  it('reuters search returns articles', async () => {
+    const data = await tryBrowserCommand(['reuters', 'search', '--keyword', 'technology', '--limit', '3', '-f', 'json']);
+    expectDataOrSkip(data, 'reuters search');
+  }, 60_000);
+
+  // ── youtube (browser: true) ──
+  it('youtube search returns videos', async () => {
+    const data = await tryBrowserCommand(['youtube', 'search', '--keyword', 'typescript tutorial', '--limit', '3', '-f', 'json']);
+    expectDataOrSkip(data, 'youtube search');
+  }, 60_000);
+
+  // ── smzdm (browser: true) ──
+  it('smzdm search returns deals', async () => {
+    const data = await tryBrowserCommand(['smzdm', 'search', '--keyword', '键盘', '--limit', '3', '-f', 'json']);
+    expectDataOrSkip(data, 'smzdm search');
+  }, 60_000);
+
+  // ── boss (browser: true) ──
+  it('boss search returns jobs', async () => {
+    const data = await tryBrowserCommand(['boss', 'search', '--keyword', 'golang', '--limit', '3', '-f', 'json']);
+    expectDataOrSkip(data, 'boss search');
+  }, 60_000);
+
+  // ── ctrip (browser: true) ──
+  it('ctrip search returns flights', async () => {
+    const data = await tryBrowserCommand(['ctrip', 'search', '-f', 'json']);
+    expectDataOrSkip(data, 'ctrip search');
+  }, 60_000);
+
+  // ── coupang (browser: true) ──
+  it('coupang search returns products', async () => {
+    const data = await tryBrowserCommand(['coupang', 'search', '--keyword', 'laptop', '--limit', '3', '-f', 'json']);
+    expectDataOrSkip(data, 'coupang search');
+  }, 60_000);
+
+  // ── xiaohongshu (browser: true) ──
+  it('xiaohongshu search returns notes', async () => {
+    const data = await tryBrowserCommand(['xiaohongshu', 'search', '--keyword', '美食', '--limit', '3', '-f', 'json']);
+    expectDataOrSkip(data, 'xiaohongshu search');
+  }, 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']);
+    expectDataOrSkip(data, 'yahoo-finance quote');
+  }, 60_000);
+});

package/tests/e2e/helpers.ts

@@ -0,0 +1,63 @@
+/**
+ * Shared helpers for E2E tests.
+ * Runs the built opencli binary as a subprocess.
+ */
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const exec = promisify(execFile);
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '../..');
+const MAIN = path.join(ROOT, 'dist', 'main.js');
+
+export interface CliResult {
+  stdout: string;
+  stderr: string;
+  code: number;
+}
+
+/**
+ * Run `opencli` as a child process with the given arguments.
+ * Without PLAYWRIGHT_MCP_EXTENSION_TOKEN, opencli auto-launches its own browser.
+ */
+export async function runCli(
+  args: string[],
+  opts: { timeout?: number; env?: Record<string, string> } = {},
+): Promise<CliResult> {
+  const timeout = opts.timeout ?? 30_000;
+  try {
+    const { stdout, stderr } = await exec('node', [MAIN, ...args], {
+      cwd: ROOT,
+      timeout,
+      env: {
+        ...process.env,
+        // Prevent chalk colors from polluting test assertions
+        FORCE_COLOR: '0',
+        NO_COLOR: '1',
+        ...opts.env,
+      },
+    });
+    return { stdout, stderr, code: 0 };
+  } catch (err: any) {
+    return {
+      stdout: err.stdout ?? '',
+      stderr: err.stderr ?? '',
+      code: err.code ?? 1,
+    };
+  }
+}
+
+/**
+ * Parse JSON output from a CLI command.
+ * Throws a descriptive error if parsing fails.
+ */
+export function parseJsonOutput(stdout: string): any {
+  try {
+    return JSON.parse(stdout.trim());
+  } catch {
+    throw new Error(`Failed to parse CLI JSON output:\n${stdout.slice(0, 500)}`);
+  }
+}

package/tests/e2e/management.test.ts

@@ -0,0 +1,106 @@
+/**
+ * E2E tests for management/built-in commands.
+ * These commands require no external network access (except verify --smoke).
+ */
+
+import { describe, it, expect } from 'vitest';
+import { runCli, parseJsonOutput } from './helpers.js';
+
+describe('management commands E2E', () => {
+
+  // ── list ──
+  it('list shows all registered commands', async () => {
+    const { stdout, code } = await runCli(['list', '-f', 'json']);
+    expect(code).toBe(0);
+    const data = parseJsonOutput(stdout);
+    expect(Array.isArray(data)).toBe(true);
+    // Should have 50+ commands across 18 sites
+    expect(data.length).toBeGreaterThan(50);
+    // Each entry should have the standard fields
+    expect(data[0]).toHaveProperty('command');
+    expect(data[0]).toHaveProperty('site');
+    expect(data[0]).toHaveProperty('name');
+    expect(data[0]).toHaveProperty('strategy');
+    expect(data[0]).toHaveProperty('browser');
+  });
+
+  it('list default table format renders sites', async () => {
+    const { stdout, code } = await runCli(['list']);
+    expect(code).toBe(0);
+    // Should contain site names
+    expect(stdout).toContain('hackernews');
+    expect(stdout).toContain('bilibili');
+    expect(stdout).toContain('twitter');
+    expect(stdout).toContain('commands across');
+  });
+
+  it('list -f yaml produces valid yaml', async () => {
+    const { stdout, code } = await runCli(['list', '-f', 'yaml']);
+    expect(code).toBe(0);
+    expect(stdout).toContain('command:');
+    expect(stdout).toContain('site:');
+  });
+
+  it('list -f csv produces valid csv', async () => {
+    const { stdout, code } = await runCli(['list', '-f', 'csv']);
+    expect(code).toBe(0);
+    const lines = stdout.trim().split('\n');
+    expect(lines.length).toBeGreaterThan(50);
+  });
+
+  it('list -f md produces markdown table', async () => {
+    const { stdout, code } = await runCli(['list', '-f', 'md']);
+    expect(code).toBe(0);
+    expect(stdout).toContain('|');
+    expect(stdout).toContain('command');
+  });
+
+  // ── validate ──
+  it('validate passes for all built-in adapters', async () => {
+    const { stdout, code } = await runCli(['validate']);
+    expect(code).toBe(0);
+    expect(stdout).toContain('PASS');
+    expect(stdout).not.toContain('❌');
+  });
+
+  it('validate works for specific site', async () => {
+    const { stdout, code } = await runCli(['validate', 'hackernews']);
+    expect(code).toBe(0);
+    expect(stdout).toContain('PASS');
+  });
+
+  it('validate works for specific command', async () => {
+    const { stdout, code } = await runCli(['validate', 'hackernews/top']);
+    expect(code).toBe(0);
+    expect(stdout).toContain('PASS');
+  });
+
+  // ── verify ──
+  it('verify runs validation without smoke tests', async () => {
+    const { stdout, code } = await runCli(['verify']);
+    expect(code).toBe(0);
+    expect(stdout).toContain('PASS');
+  });
+
+  // ── version ──
+  it('--version shows version number', async () => {
+    const { stdout, code } = await runCli(['--version']);
+    expect(code).toBe(0);
+    expect(stdout.trim()).toMatch(/^\d+\.\d+\.\d+$/);
+  });
+
+  // ── help ──
+  it('--help shows usage', async () => {
+    const { stdout, code } = await runCli(['--help']);
+    expect(code).toBe(0);
+    expect(stdout).toContain('opencli');
+    expect(stdout).toContain('list');
+    expect(stdout).toContain('validate');
+  });
+
+  // ── unknown command ──
+  it('unknown command shows error', async () => {
+    const { stderr, code } = await runCli(['nonexistent-command-xyz']);
+    expect(code).toBe(1);
+  });
+});