@jackwener/opencli 1.5.4 → 1.5.6

package/src/external.ts

@@ -6,7 +6,7 @@ import { spawnSync, execFileSync } from 'node:child_process';
 import yaml from 'js-yaml';
 import chalk from 'chalk';
 import { log } from './logger.js';
-import { getErrorMessage } from './errors.js';
+import { EXIT_CODES, getErrorMessage } from './errors.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -180,7 +180,7 @@ export function executeExternalCli(name: string, args: string[], preloaded?: Ext
     // 2. Try to auto install
     const success = installExternalCli(cli);
     if (!success) {
-      process.exitCode = 1;
+      process.exitCode = EXIT_CODES.SERVICE_UNAVAIL;
       return;
     }
   }
@@ -189,7 +189,7 @@ export function executeExternalCli(name: string, args: string[], preloaded?: Ext
   const result = spawnSync(cli.binary, args, { stdio: 'inherit' });
   if (result.error) {
     console.error(chalk.red(`Failed to execute '${cli.binary}': ${result.error.message}`));
-    process.exitCode = 1;
+    process.exitCode = EXIT_CODES.GENERIC_ERROR;
     return;
   }
   

package/src/main.ts

@@ -22,6 +22,7 @@ import { runCli } from './cli.js';
 import { emitHook } from './hooks.js';
 import { installNodeNetwork } from './node-network.js';
 import { registerUpdateNoticeOnExit, checkForUpdateBackground } from './update-check.js';
+import { EXIT_CODES } from './errors.js';
 
 installNodeNetwork();
 
@@ -57,7 +58,7 @@ if (getCompIdx !== -1) {
   if (cursor === undefined) cursor = words.length;
   const candidates = getCompletions(words, cursor);
   process.stdout.write(candidates.join('\n') + '\n');
-  process.exit(0);
+  process.exit(EXIT_CODES.SUCCESS);
 }
 
 await emitHook('onStartup', { command: '__startup__', args: {} });

package/src/tui.ts

@@ -4,6 +4,7 @@
  * Uses raw stdin mode + ANSI escape codes for interactive prompts.
  */
 import chalk from 'chalk';
+import { EXIT_CODES } from './errors.js';
 
 export interface CheckboxItem {
   label: string;
@@ -161,7 +162,7 @@ export async function checkboxPrompt(
       // Ctrl+C — exit process
       if (key === '\x03') {
         cleanup();
-        process.exit(130);
+        process.exit(EXIT_CODES.INTERRUPTED);
       }
     }
 

package/src/types.ts

@@ -67,6 +67,11 @@ export interface IPage {
   getInterceptedRequests(): Promise<any[]>;
   waitForCapture(timeout?: number): Promise<void>;
   screenshot(options?: ScreenshotOptions): Promise<string>;
+  /**
+   * Set local file paths on a file input element via CDP DOM.setFileInputFiles.
+   * Chrome reads the files directly — no base64 encoding or payload size limits.
+   */
+  setFileInput?(files: string[], selector?: string): Promise<void>;
   closeWindow?(): Promise<void>;
   /** Returns the current page URL, or null if unavailable. */
   getCurrentUrl?(): Promise<string | null>;

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

@@ -0,0 +1,20 @@
+import { describe, it } from 'vitest';
+import { expectGracefulAuthFailure } from './browser-auth-helpers.js';
+
+describe('band auth-required commands — graceful failure', () => {
+  it('band bands fails gracefully without login', async () => {
+    await expectGracefulAuthFailure(['band', 'bands', '-f', 'json']);
+  }, 60_000);
+
+  it('band mentions fails gracefully without login', async () => {
+    await expectGracefulAuthFailure(['band', 'mentions', '--limit', '3', '-f', 'json']);
+  }, 60_000);
+
+  it('band posts fails gracefully without login', async () => {
+    await expectGracefulAuthFailure(['band', 'posts', '58400480', '--limit', '3', '-f', 'json']);
+  }, 60_000);
+
+  it('band post fails gracefully without login', async () => {
+    await expectGracefulAuthFailure(['band', 'post', '58400480', '1', '-f', 'json']);
+  }, 60_000);
+});

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

@@ -0,0 +1,18 @@
+import { 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.
+ */
+export async function expectGracefulAuthFailure(args: 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.
+}

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

@@ -6,148 +6,136 @@
  * 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
-}
+import { describe, it } from 'vitest';
+import { expectGracefulAuthFailure } from './browser-auth-helpers.js';
 
 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');
+    await expectGracefulAuthFailure(['bilibili', 'me', '-f', 'json']);
   }, 60_000);
 
   it('bilibili dynamic fails gracefully without login', async () => {
-    await expectGracefulAuthFailure(['bilibili', 'dynamic', '--limit', '3', '-f', 'json'], 'bilibili dynamic');
+    await expectGracefulAuthFailure(['bilibili', 'dynamic', '--limit', '3', '-f', 'json']);
   }, 60_000);
 
   it('bilibili favorite fails gracefully without login', async () => {
-    await expectGracefulAuthFailure(['bilibili', 'favorite', '--limit', '3', '-f', 'json'], 'bilibili favorite');
+    await expectGracefulAuthFailure(['bilibili', 'favorite', '--limit', '3', '-f', 'json']);
   }, 60_000);
 
   it('bilibili history fails gracefully without login', async () => {
-    await expectGracefulAuthFailure(['bilibili', 'history', '--limit', '3', '-f', 'json'], 'bilibili history');
+    await expectGracefulAuthFailure(['bilibili', 'history', '--limit', '3', '-f', 'json']);
   }, 60_000);
 
   it('bilibili following fails gracefully without login', async () => {
-    await expectGracefulAuthFailure(['bilibili', 'following', '--limit', '3', '-f', 'json'], 'bilibili following');
+    await expectGracefulAuthFailure(['bilibili', 'following', '--limit', '3', '-f', 'json']);
   }, 60_000);
 
   // ── twitter (requires login) ──
   it('twitter bookmarks fails gracefully without login', async () => {
-    await expectGracefulAuthFailure(['twitter', 'bookmarks', '--limit', '3', '-f', 'json'], 'twitter bookmarks');
+    await expectGracefulAuthFailure(['twitter', 'bookmarks', '--limit', '3', '-f', 'json']);
   }, 60_000);
 
   it('twitter timeline fails gracefully without login', async () => {
-    await expectGracefulAuthFailure(['twitter', 'timeline', '--limit', '3', '-f', 'json'], 'twitter timeline');
+    await expectGracefulAuthFailure(['twitter', 'timeline', '--limit', '3', '-f', 'json']);
   }, 60_000);
 
   it('twitter notifications fails gracefully without login', async () => {
-    await expectGracefulAuthFailure(['twitter', 'notifications', '--limit', '3', '-f', 'json'], 'twitter notifications');
+    await expectGracefulAuthFailure(['twitter', 'notifications', '--limit', '3', '-f', 'json']);
   }, 60_000);
 
   // ── v2ex (requires login) ──
   it('v2ex me fails gracefully without login', async () => {
-    await expectGracefulAuthFailure(['v2ex', 'me', '-f', 'json'], 'v2ex me');
+    await expectGracefulAuthFailure(['v2ex', 'me', '-f', 'json']);
   }, 60_000);
 
   it('v2ex notifications fails gracefully without login', async () => {
-    await expectGracefulAuthFailure(['v2ex', 'notifications', '--limit', '3', '-f', 'json'], 'v2ex notifications');
+    await expectGracefulAuthFailure(['v2ex', 'notifications', '--limit', '3', '-f', 'json']);
   }, 60_000);
 
   // ── xueqiu (requires login) ──
   it('xueqiu feed fails gracefully without login', async () => {
-    await expectGracefulAuthFailure(['xueqiu', 'feed', '--limit', '3', '-f', 'json'], 'xueqiu feed');
+    await expectGracefulAuthFailure(['xueqiu', 'feed', '--limit', '3', '-f', 'json']);
   }, 60_000);
 
   it('xueqiu watchlist fails gracefully without login', async () => {
-    await expectGracefulAuthFailure(['xueqiu', 'watchlist', '-f', 'json'], 'xueqiu watchlist');
+    await expectGracefulAuthFailure(['xueqiu', 'watchlist', '-f', 'json']);
+  }, 60_000);
+
+  it('xueqiu comments fails gracefully without login', async () => {
+    await expectGracefulAuthFailure(['xueqiu', 'comments', 'SH600519', '--limit', '3', '-f', 'json'], 'xueqiu comments');
   }, 60_000);
 
   // ── linux-do (requires login — all endpoints need authentication) ──
   it('linux-do feed fails gracefully without login', async () => {
-    await expectGracefulAuthFailure(['linux-do', 'feed', '--limit', '3', '-f', 'json'], 'linux-do feed');
+    await expectGracefulAuthFailure(['linux-do', 'feed', '--limit', '3', '-f', 'json']);
   }, 60_000);
 
   it('linux-do categories fails gracefully without login', async () => {
-    await expectGracefulAuthFailure(['linux-do', 'categories', '--limit', '3', '-f', 'json'], 'linux-do categories');
+    await expectGracefulAuthFailure(['linux-do', 'categories', '--limit', '3', '-f', 'json']);
   }, 60_000);
 
   it('linux-do tags fails gracefully without login', async () => {
-    await expectGracefulAuthFailure(['linux-do', 'tags', '--limit', '3', '-f', 'json'], 'linux-do tags');
+    await expectGracefulAuthFailure(['linux-do', 'tags', '--limit', '3', '-f', 'json']);
   }, 60_000);
 
   it('linux-do topic fails gracefully without login', async () => {
-    await expectGracefulAuthFailure(['linux-do', 'topic', '1', '-f', 'json'], 'linux-do topic');
+    await expectGracefulAuthFailure(['linux-do', 'topic', '1', '-f', 'json']);
   }, 60_000);
 
   it('linux-do search fails gracefully without login', async () => {
-    await expectGracefulAuthFailure(['linux-do', 'search', 'test', '--limit', '3', '-f', 'json'], 'linux-do search');
+    await expectGracefulAuthFailure(['linux-do', 'search', 'test', '--limit', '3', '-f', 'json']);
   }, 60_000);
 
   it('linux-do user-topics fails gracefully without login', async () => {
-    await expectGracefulAuthFailure(['linux-do', 'user-topics', 'test', '--limit', '3', '-f', 'json'], 'linux-do user-topics');
+    await expectGracefulAuthFailure(['linux-do', 'user-topics', 'test', '--limit', '3', '-f', 'json']);
   }, 60_000);
 
   it('linux-do user-posts fails gracefully without login', async () => {
-    await expectGracefulAuthFailure(['linux-do', 'user-posts', 'test', '--limit', '3', '-f', 'json'], 'linux-do user-posts');
+    await expectGracefulAuthFailure(['linux-do', 'user-posts', 'test', '--limit', '3', '-f', 'json']);
   }, 60_000);
 
   // ── xiaohongshu (requires login) ──
   it('xiaohongshu feed fails gracefully without login', async () => {
-    await expectGracefulAuthFailure(['xiaohongshu', 'feed', '--limit', '3', '-f', 'json'], 'xiaohongshu feed');
+    await expectGracefulAuthFailure(['xiaohongshu', 'feed', '--limit', '3', '-f', 'json']);
   }, 60_000);
 
   it('xiaohongshu notifications fails gracefully without login', async () => {
-    await expectGracefulAuthFailure(['xiaohongshu', 'notifications', '--limit', '3', '-f', 'json'], 'xiaohongshu notifications');
+    await expectGracefulAuthFailure(['xiaohongshu', 'notifications', '--limit', '3', '-f', 'json']);
   }, 60_000);
 
   // ── pixiv (requires login) ──
   it('pixiv ranking fails gracefully without login', async () => {
-    await expectGracefulAuthFailure(['pixiv', 'ranking', '--limit', '3', '-f', 'json'], 'pixiv ranking');
+    await expectGracefulAuthFailure(['pixiv', 'ranking', '--limit', '3', '-f', 'json']);
   }, 60_000);
 
   it('pixiv search fails gracefully without login', async () => {
-    await expectGracefulAuthFailure(['pixiv', 'search', '初音ミク', '--limit', '3', '-f', 'json'], 'pixiv search');
+    await expectGracefulAuthFailure(['pixiv', 'search', '初音ミク', '--limit', '3', '-f', 'json']);
   }, 60_000);
 
   it('pixiv user fails gracefully without login', async () => {
-    await expectGracefulAuthFailure(['pixiv', 'user', '11', '-f', 'json'], 'pixiv user');
+    await expectGracefulAuthFailure(['pixiv', 'user', '11', '-f', 'json']);
   }, 60_000);
 
   it('pixiv illusts fails gracefully without login', async () => {
-    await expectGracefulAuthFailure(['pixiv', 'illusts', '11', '--limit', '3', '-f', 'json'], 'pixiv illusts');
+    await expectGracefulAuthFailure(['pixiv', 'illusts', '11', '--limit', '3', '-f', 'json']);
   }, 60_000);
 
   it('pixiv detail fails gracefully without login', async () => {
-    await expectGracefulAuthFailure(['pixiv', 'detail', '123456', '-f', 'json'], 'pixiv detail');
+    await expectGracefulAuthFailure(['pixiv', 'detail', '123456', '-f', 'json']);
   }, 60_000);
 
   it('pixiv download fails gracefully without login', async () => {
-    await expectGracefulAuthFailure(['pixiv', 'download', '123456', '--output', '/tmp/pixiv-e2e-test', '-f', 'json'], 'pixiv download');
+    await expectGracefulAuthFailure(['pixiv', 'download', '123456', '--output', '/tmp/pixiv-e2e-test', '-f', 'json']);
   }, 60_000);
 
   // ── yollomi (requires login session) ──
   it('yollomi generate fails gracefully without login', async () => {
-    await expectGracefulAuthFailure(['yollomi', 'generate', 'a cute cat', '--no-download', '-f', 'json'], 'yollomi generate');
+    await expectGracefulAuthFailure(['yollomi', 'generate', 'a cute cat', '--no-download', '-f', 'json']);
   }, 60_000);
 
   it('yollomi video fails gracefully without login', async () => {
-    await expectGracefulAuthFailure(['yollomi', 'video', 'a sunset over the ocean', '--no-download', '-f', 'json'], 'yollomi video');
+    await expectGracefulAuthFailure(['yollomi', 'video', 'a sunset over the ocean', '--no-download', '-f', 'json']);
   }, 60_000);
 });

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

@@ -38,6 +38,201 @@ function isBrowserBridgeUnavailable(result: CliResult): boolean {
   return /Browser Bridge.*not connected|Extension.*not connected/i.test(text);
 }
 
+function isBaiduChallengeText(text: string): boolean {
+  return /百度安全验证|安全验证|请完成验证|captcha/i.test(text);
+}
+
+function isBaiduChallenge(result: CliResult): boolean {
+  const text = `${result.stderr}\n${result.stdout}`;
+  return isBaiduChallengeText(text);
+}
+
+function isTransientBrowserDetach(result: CliResult): boolean {
+  const text = `${result.stderr}\n${result.stdout}`;
+  return /Detached while handling command|No tab with id|Debugger is not attached to the tab/i.test(text);
+}
+
+async function runCliWithTransientRetry(args: string[], timeout: number): Promise<CliResult> {
+  let result = await runCli(args, { timeout });
+  if (result.code !== 0 && isTransientBrowserDetach(result)) {
+    result = await runCli(args, { timeout });
+  }
+  return result;
+}
+
+async function runJsonCliOrThrow(args: string[], label: string, timeout: number, opts: { retryTransient?: boolean } = {}): Promise<any[] | null> {
+  const result = opts.retryTransient
+    ? await runCliWithTransientRetry(args, timeout)
+    : await runCli(args, { timeout });
+  if (result.code !== 0) {
+    if (isBrowserBridgeUnavailable(result)) {
+      console.warn(`${label}: skipped — Browser Bridge extension is unavailable in this environment`);
+      return null;
+    }
+    if (isBaiduChallenge(result)) {
+      console.warn(`${label}: skipped — Baidu challenge page detected`);
+      return null;
+    }
+    throw new Error(`${label} failed:\n${result.stderr || result.stdout}`);
+  }
+
+  const data = parseJsonOutput(result.stdout);
+  if (!Array.isArray(data)) {
+    throw new Error(`${label} returned non-array JSON:\n${result.stdout.slice(0, 500)}`);
+  }
+  return data;
+}
+
+function normalizeTiebaTitle(value: string): string {
+  return value.replace(/\s+/g, ' ').trim();
+}
+
+function hasTiebaMainPost(data: any[] | null): boolean {
+  return Array.isArray(data) && data.some((item: any) => Number(item.floor) === 1);
+}
+
+function expectNonEmptyDataOrSkipEnv(data: any[] | null, label: string): data is any[] {
+  if (data === null) {
+    console.warn(`${label}: skipped — environment is unavailable for browser assertions`);
+    return false;
+  }
+  expect(data.length).toBeGreaterThanOrEqual(1);
+  return true;
+}
+
+function countTiebaReplies(data: any[] | null): number {
+  if (!Array.isArray(data)) return 0;
+  return data.filter((item: any) => Number(item.floor) > 1).length;
+}
+
+function maxTiebaFloor(data: any[] | null): number {
+  if (!Array.isArray(data) || !data.length) return 0;
+  return Math.max(...data.map((item: any) => Number(item.floor) || 0));
+}
+
+function getTiebaReplyFloors(data: any[] | null): number[] {
+  if (!Array.isArray(data)) return [];
+  return data
+    .map((item: any) => Number(item.floor) || 0)
+    .filter((floor) => floor > 1);
+}
+
+function countTiebaReplyFloorOverlap(left: any[] | null, right: any[] | null): number {
+  const rightFloors = new Set(getTiebaReplyFloors(right));
+  return getTiebaReplyFloors(left).filter((floor) => rightFloors.has(floor)).length;
+}
+
+function pickTiebaReadCandidates(
+  posts: any[] | null,
+  minReplies: number,
+): Array<{ threadId: string; title: string; replies: number }> {
+  if (!Array.isArray(posts) || !posts.length) return [];
+
+  return [...posts]
+    .filter((item: any) => item?.id)
+    .map((item: any) => ({
+      threadId: String(item.id || '').trim(),
+      title: normalizeTiebaTitle(String(item.title || '')),
+      replies: Number(item.replies) || 0,
+    }))
+    .filter((item) => item.threadId && item.title && item.replies >= minReplies)
+    .sort((left, right) => right.replies - left.replies);
+}
+
+/**
+ * Pick a live thread that actually exposes enough visible replies for the read assertions.
+ */
+async function getTiebaReadCandidateOrSkip(
+  label: string,
+  options: { minRepliesOnPage1?: number; requirePage2?: boolean } = {},
+): Promise<{ threadId: string; title: string; replies: number } | null> {
+  const minRepliesOnPage1 = Math.max(1, Number(options.minRepliesOnPage1 || 1));
+  const requirePage2 = options.requirePage2 === true;
+  const posts = await runJsonCliOrThrow(['tieba', 'posts', '李毅', '--limit', '10', '-f', 'json'], `${label} setup`, 90_000, {
+    retryTransient: true,
+  });
+  if (posts === null) {
+    return null;
+  }
+  if (!Array.isArray(posts) || !posts.length) {
+    console.warn(`${label}: skipped — could not resolve Tieba posts for setup`);
+    return null;
+  }
+
+  const minReplies = requirePage2 ? Math.max(minRepliesOnPage1, 50) : minRepliesOnPage1;
+  const candidates = pickTiebaReadCandidates(posts, minReplies).slice(0, 5);
+  if (!candidates.length) {
+    console.warn(`${label}: skipped — could not find a Tieba thread with enough replies from posts metadata`);
+    return null;
+  }
+
+  for (const candidate of candidates) {
+    const page1Preview = await runJsonCliOrThrow(
+      ['tieba', 'read', candidate.threadId, '--page', '1', '--limit', String(Math.max(minRepliesOnPage1, 2)), '-f', 'json'],
+      `${label} preview page 1`,
+      90_000,
+      { retryTransient: true },
+    );
+    if (page1Preview === null) {
+      return null;
+    }
+    if (!hasTiebaMainPost(page1Preview) || countTiebaReplies(page1Preview) < minRepliesOnPage1) {
+      continue;
+    }
+
+    if (requirePage2) {
+      const page2Preview = await runJsonCliOrThrow(
+        ['tieba', 'read', candidate.threadId, '--page', '2', '--limit', '1', '-f', 'json'],
+        `${label} preview page 2`,
+        90_000,
+        { retryTransient: true },
+      );
+      if (page2Preview === null) {
+        return null;
+      }
+      if (hasTiebaMainPost(page2Preview) || countTiebaReplies(page2Preview) < 1) {
+        continue;
+      }
+    }
+
+    return candidate;
+  }
+
+  console.warn(`${label}: skipped — could not find a Tieba thread with enough visible replies`);
+  return null;
+}
+
+describe('tieba e2e helper guards', () => {
+  it('does not treat generic empty-result errors as a Baidu challenge', () => {
+    expect(isBaiduChallengeText('tieba posts returned no data\n→ The page structure may have changed — this adapter may be outdated.')).toBe(false);
+  });
+
+  it('still recognizes actual Baidu challenge text', () => {
+    expect(isBaiduChallengeText('百度安全验证，请完成验证后继续')).toBe(true);
+  });
+
+  it('counts partial overlap between read pages', () => {
+    expect(countTiebaReplyFloorOverlap(
+      [{ floor: 1 }, { floor: 23 }, { floor: 27 }, { floor: 28 }, { floor: 29 }, { floor: 30 }],
+      [{ floor: 27 }, { floor: 28 }, { floor: 31 }],
+    )).toBe(2);
+  });
+
+  it('picks read fixtures from posts metadata in descending reply order', () => {
+    expect(pickTiebaReadCandidates([
+      { id: '1', title: '普通帖', replies: 2 },
+      { id: '2', title: '大帖', replies: 120 },
+      { id: '', title: '无效帖', replies: 999 },
+    ], 50)).toEqual([{
+      threadId: '2',
+      title: '大帖',
+      replies: 120,
+    }]);
+
+    expect(pickTiebaReadCandidates([{ id: '1', title: '普通帖', replies: 2 }], 50)).toEqual([]);
+  });
+});
+
 async function expectImdbDataOrChallengeSkip(args: string[], label: string): Promise<any[] | null> {
   const result = await runCli(args, { timeout: 60_000 });
   if (result.code !== 0) {
@@ -103,6 +298,99 @@ describe('browser public-data commands E2E', () => {
     expectDataOrSkip(data, 'v2ex daily');
   }, 60_000);
 
+  // ── tieba ──
+  it('tieba hot returns trending topics', async () => {
+    const data = await runJsonCliOrThrow(['tieba', 'hot', '--limit', '5', '-f', 'json'], 'tieba hot', 60_000, { retryTransient: true });
+    if (expectNonEmptyDataOrSkipEnv(data, 'tieba hot')) {
+      expect(data[0]).toHaveProperty('title');
+      expect(data[0]).toHaveProperty('discussions');
+    }
+  }, 60_000);
+
+  it('tieba posts returns forum threads', async () => {
+    const data = await runJsonCliOrThrow(['tieba', 'posts', '李毅', '--limit', '20', '-f', 'json'], 'tieba posts', 90_000, { retryTransient: true });
+    if (expectNonEmptyDataOrSkipEnv(data, 'tieba posts')) {
+      expect(data[0]).toHaveProperty('title');
+      expect(String(data[0].id || '')).toMatch(/^\d+$/);
+      expect(String(data[0].url || '')).toContain('/p/');
+      expect(Number.isFinite(Number(data[0].replies))).toBe(true);
+      expect(data.length).toBeLessThanOrEqual(20);
+    }
+  }, 90_000);
+
+  it('tieba posts page 2 returns a different forum slice', async () => {
+    const data1 = await runJsonCliOrThrow(['tieba', 'posts', '李毅', '--page', '1', '--limit', '5', '-f', 'json'], 'tieba posts page 1', 60_000, { retryTransient: true });
+    const data2 = await runJsonCliOrThrow(['tieba', 'posts', '李毅', '--page', '2', '--limit', '5', '-f', 'json'], 'tieba posts page 2', 60_000, { retryTransient: true });
+    if (expectNonEmptyDataOrSkipEnv(data1, 'tieba posts page 1') && expectNonEmptyDataOrSkipEnv(data2, 'tieba posts page 2')) {
+      const ids1 = data1.map((item: any) => String(item.id || '')).filter(Boolean);
+      const ids2 = data2.map((item: any) => String(item.id || '')).filter(Boolean);
+      const newIds = ids2.filter((id) => !ids1.includes(id));
+      expect(newIds.length).toBeGreaterThan(0);
+    }
+  }, 90_000);
+
+  it('tieba search returns results', async () => {
+    const data = await runJsonCliOrThrow(['tieba', 'search', '编程', '--limit', '20', '-f', 'json'], 'tieba search', 90_000, { retryTransient: true });
+    if (expectNonEmptyDataOrSkipEnv(data, 'tieba search')) {
+      expect(data[0]).toHaveProperty('title');
+      expect(String(data[0].id || '')).toMatch(/^\d+$/);
+      expect(String(data[0].url || '')).toContain('/p/');
+      expect(data.length).toBeLessThanOrEqual(20);
+    }
+  }, 90_000);
+
+  it('tieba search rejects unsupported pages above 1', async () => {
+    const result = await runCli(['tieba', 'search', '编程', '--page', '2', '--limit', '3', '-f', 'json'], {
+      timeout: 60_000,
+    });
+    expect(result.code).toBe(2);
+    expect(`${result.stderr}\n${result.stdout}`).toContain('Argument "page" must be one of: 1');
+  }, 60_000);
+
+  it('tieba read returns thread content', async () => {
+    const fixture = await getTiebaReadCandidateOrSkip('tieba read');
+    if (!fixture) {
+      return;
+    }
+    const data = await runJsonCliOrThrow(['tieba', 'read', fixture.threadId, '--limit', '5', '-f', 'json'], 'tieba read', 90_000, { retryTransient: true });
+    if (expectNonEmptyDataOrSkipEnv(data, 'tieba read')) {
+      expect(data[0]).toHaveProperty('floor');
+      expect(data[0]).toHaveProperty('content');
+      expect(data.some((item: any) => Number(item.floor) === 1)).toBe(true);
+      expect(normalizeTiebaTitle(String(data[0].content || ''))).toContain(fixture.title);
+    }
+  }, 90_000);
+
+  it('tieba read page 2 omits the main post', async () => {
+    const fixture = await getTiebaReadCandidateOrSkip('tieba read page', { requirePage2: true });
+    if (!fixture) {
+      return;
+    }
+    const data1 = await runJsonCliOrThrow(['tieba', 'read', fixture.threadId, '--page', '1', '--limit', '5', '-f', 'json'], 'tieba read page 1', 90_000, { retryTransient: true });
+    const data2 = await runJsonCliOrThrow(['tieba', 'read', fixture.threadId, '--page', '2', '--limit', '5', '-f', 'json'], 'tieba read page 2', 90_000, { retryTransient: true });
+    if (expectNonEmptyDataOrSkipEnv(data1, 'tieba read page 1') && expectNonEmptyDataOrSkipEnv(data2, 'tieba read page 2')) {
+      const overlap = countTiebaReplyFloorOverlap(data1, data2);
+      expect(normalizeTiebaTitle(String(data1[0].content || ''))).toContain(fixture.title);
+      expect(hasTiebaMainPost(data1)).toBe(true);
+      expect(hasTiebaMainPost(data2)).toBe(false);
+      expect(overlap).toBe(0);
+      expect(maxTiebaFloor(data2)).toBeGreaterThan(maxTiebaFloor(data1));
+    }
+  }, 90_000);
+
+  it('tieba read limit counts replies instead of consuming the main post slot', async () => {
+    const fixture = await getTiebaReadCandidateOrSkip('tieba read limit semantics', { minRepliesOnPage1: 2 });
+    if (!fixture) {
+      return;
+    }
+    const data = await runJsonCliOrThrow(['tieba', 'read', fixture.threadId, '--page', '1', '--limit', '2', '-f', 'json'], 'tieba read limit semantics', 90_000, { retryTransient: true });
+    if (expectNonEmptyDataOrSkipEnv(data, 'tieba read limit semantics')) {
+      expect(normalizeTiebaTitle(String(data[0].content || ''))).toContain(fixture.title);
+      expect(hasTiebaMainPost(data)).toBe(true);
+      expect(countTiebaReplies(data)).toBe(2);
+    }
+  }, 90_000);
+
   // ── imdb ──
   it('imdb top returns chart data', async () => {
     const data = await expectImdbDataOrChallengeSkip(['imdb', 'top', '--limit', '3', '-f', 'json'], 'imdb top');

package/tests/e2e/management.test.ts

@@ -101,6 +101,6 @@ describe('management commands E2E', () => {
   // ── unknown command ──
   it('unknown command shows error', async () => {
     const { stderr, code } = await runCli(['nonexistent-command-xyz']);
-    expect(code).toBe(1);
+    expect(code).toBe(2);
   });
 });

package/tests/e2e/plugin-management.test.ts

@@ -134,7 +134,7 @@ describe('plugin management E2E', () => {
 
   it('plugin update without name or --all shows error', async () => {
     const { stderr, code } = await runPluginCli(['plugin', 'update']);
-    expect(code).toBe(1);
+    expect(code).toBe(2);
     expect(stderr).toContain('specify a plugin name');
   });
 });

package/vitest.config.ts

@@ -25,6 +25,7 @@ export default defineConfig({
           name: 'e2e',
           include: [
             'tests/e2e/browser-public.test.ts',
+            'tests/e2e/band-auth.test.ts',
             'tests/e2e/public-commands.test.ts',
             'tests/e2e/management.test.ts',
             'tests/e2e/output-formats.test.ts',