@jackwener/opencli 1.5.5 → 1.5.7

package/src/clis/spotify/utils.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  assertSpotifyCredentialsConfigured,
+  getFirstSpotifyTrack,
+  hasConfiguredSpotifyCredentials,
+  mapSpotifyTrackResults,
+  parseDotEnv,
+  resolveSpotifyCredentials,
+} from './utils.js';
+
+describe('spotify utils', () => {
+  it('parses dotenv-style credential files', () => {
+    const env = parseDotEnv(`
+      # Spotify credentials
+      SPOTIFY_CLIENT_ID=abc123
+      SPOTIFY_CLIENT_SECRET=def456
+    `);
+
+    expect(env).toEqual({
+      SPOTIFY_CLIENT_ID: 'abc123',
+      SPOTIFY_CLIENT_SECRET: 'def456',
+    });
+  });
+
+  it('prefers explicit process env over file values', () => {
+    const credentials = resolveSpotifyCredentials(
+      {
+        SPOTIFY_CLIENT_ID: 'file-id',
+        SPOTIFY_CLIENT_SECRET: 'file-secret',
+      },
+      {
+        SPOTIFY_CLIENT_ID: 'env-id',
+        SPOTIFY_CLIENT_SECRET: 'env-secret',
+      },
+    );
+
+    expect(credentials).toEqual({
+      clientId: 'env-id',
+      clientSecret: 'env-secret',
+    });
+  });
+
+  it('treats placeholder values as unconfigured credentials', () => {
+    expect(hasConfiguredSpotifyCredentials({
+      clientId: 'your_spotify_client_id_here',
+      clientSecret: 'your_spotify_client_secret_here',
+    })).toBe(false);
+  });
+
+  it('throws a helpful CONFIG error for empty or placeholder credentials', () => {
+    expect(() => assertSpotifyCredentialsConfigured({
+      clientId: '',
+      clientSecret: '',
+    }, '/tmp/spotify.env')).toThrow(/Missing Spotify credentials/);
+
+    expect(() => assertSpotifyCredentialsConfigured({
+      clientId: 'your_spotify_client_id_here',
+      clientSecret: 'real-secret',
+    }, '/tmp/spotify.env')).toThrow(/Fill in SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET/);
+  });
+
+  it('maps search payloads into stable track summaries', () => {
+    const results = mapSpotifyTrackResults({
+      tracks: {
+        items: [
+          {
+            name: 'Numb',
+            artists: [{ name: 'Linkin Park' }, { name: 'Jay-Z' }],
+            album: { name: 'Encore' },
+            uri: 'spotify:track:123',
+          },
+        ],
+      },
+    });
+
+    expect(results).toEqual([
+      {
+        track: 'Numb',
+        artist: 'Linkin Park, Jay-Z',
+        album: 'Encore',
+        uri: 'spotify:track:123',
+      },
+    ]);
+    expect(getFirstSpotifyTrack({ tracks: { items: [] } })).toBeNull();
+  });
+});

package/src/clis/spotify/utils.ts

@@ -0,0 +1,92 @@
+import { CliError } from '../../errors.js';
+
+export interface SpotifyCredentials {
+  clientId: string;
+  clientSecret: string;
+}
+
+export interface SpotifyTrackSummary {
+  track: string;
+  artist: string;
+  album: string;
+  uri: string;
+}
+
+const SPOTIFY_PLACEHOLDER_PATTERNS = [
+  /^your_spotify_client_id_here$/i,
+  /^your_spotify_client_secret_here$/i,
+  /^your_.+_here$/i,
+];
+
+export function parseDotEnv(content: string): Record<string, string> {
+  return Object.fromEntries(
+    content
+      .split(/\r?\n/)
+      .map(line => line.trim())
+      .filter(line => line && !line.startsWith('#') && line.includes('='))
+      .map(line => {
+        const index = line.indexOf('=');
+        return [line.slice(0, index).trim(), line.slice(index + 1).trim()] as [string, string];
+      }),
+  );
+}
+
+export function resolveSpotifyCredentials(
+  fileEnv: Record<string, string>,
+  processEnv: NodeJS.ProcessEnv = process.env,
+): SpotifyCredentials {
+  return {
+    clientId: processEnv.SPOTIFY_CLIENT_ID || fileEnv.SPOTIFY_CLIENT_ID || '',
+    clientSecret: processEnv.SPOTIFY_CLIENT_SECRET || fileEnv.SPOTIFY_CLIENT_SECRET || '',
+  };
+}
+
+export function isPlaceholderCredential(value: string | null | undefined): boolean {
+  const normalized = value?.trim() || '';
+  if (!normalized) return false;
+  return SPOTIFY_PLACEHOLDER_PATTERNS.some(pattern => pattern.test(normalized));
+}
+
+export function hasConfiguredSpotifyCredentials(credentials: SpotifyCredentials): boolean {
+  return Boolean(credentials.clientId.trim()) &&
+    Boolean(credentials.clientSecret.trim()) &&
+    !isPlaceholderCredential(credentials.clientId) &&
+    !isPlaceholderCredential(credentials.clientSecret);
+}
+
+export function assertSpotifyCredentialsConfigured(credentials: SpotifyCredentials, envFile: string): void {
+  if (hasConfiguredSpotifyCredentials(credentials)) return;
+
+  throw new CliError(
+    'CONFIG',
+    `Missing Spotify credentials.\n\n` +
+    `1. Go to https://developer.spotify.com/dashboard and create an app\n` +
+    `2. Add ${'http://127.0.0.1:8888/callback'} as a Redirect URI\n` +
+    `3. Copy your Client ID and Client Secret\n` +
+    `4. Open the file: ${envFile}\n` +
+    `5. Fill in SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET, then save\n` +
+    `6. Run: opencli spotify auth`,
+  );
+}
+
+export function mapSpotifyTrackResults(data: any): SpotifyTrackSummary[] {
+  const items = data?.tracks?.items;
+  if (!Array.isArray(items)) return [];
+
+  return items.map((track: any) => ({
+    track: track?.name || '',
+    artist: Array.isArray(track?.artists) ? track.artists.map((artist: any) => artist.name).join(', ') : '',
+    album: track?.album?.name || '',
+    uri: track?.uri || '',
+  }));
+}
+
+export function getFirstSpotifyTrack(data: any): { uri: string; name: string; artist: string } | null {
+  const track = mapSpotifyTrackResults(data)[0];
+  if (!track) return null;
+  return {
+    uri: track.uri,
+    name: track.track,
+    artist: track.artist,
+  };
+}

package/src/clis/substack/utils.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { IPage } from '../../types.js';
+import { __test__, loadSubstackArchive, loadSubstackFeed } from './utils.js';
+
+function createPageMock(evaluateResult: unknown): IPage {
+  return {
+    goto: vi.fn().mockResolvedValue(undefined),
+    evaluate: vi.fn().mockResolvedValue(evaluateResult),
+    snapshot: vi.fn().mockResolvedValue(undefined),
+    click: vi.fn().mockResolvedValue(undefined),
+    typeText: vi.fn().mockResolvedValue(undefined),
+    pressKey: vi.fn().mockResolvedValue(undefined),
+    scrollTo: vi.fn().mockResolvedValue(undefined),
+    getFormState: vi.fn().mockResolvedValue({}),
+    wait: vi.fn().mockResolvedValue(undefined),
+    tabs: vi.fn().mockResolvedValue([]),
+    closeTab: vi.fn().mockResolvedValue(undefined),
+    newTab: vi.fn().mockResolvedValue(undefined),
+    selectTab: vi.fn().mockResolvedValue(undefined),
+    networkRequests: vi.fn().mockResolvedValue([]),
+    consoleMessages: vi.fn().mockResolvedValue([]),
+    scroll: vi.fn().mockResolvedValue(undefined),
+    autoScroll: vi.fn().mockResolvedValue(undefined),
+    installInterceptor: vi.fn().mockResolvedValue(undefined),
+    getInterceptedRequests: vi.fn().mockResolvedValue([]),
+    getCookies: vi.fn().mockResolvedValue([]),
+    screenshot: vi.fn().mockResolvedValue(''),
+    waitForCapture: vi.fn().mockResolvedValue(undefined),
+  };
+}
+
+describe('substack utils wait selectors', () => {
+  it('waits for both feed link shapes before scraping the feed', async () => {
+    const page = createPageMock([]);
+
+    await loadSubstackFeed(page, 'https://substack.com/', 5);
+
+    expect(page.wait).toHaveBeenCalledWith({
+      selector: __test__.FEED_POST_LINK_SELECTOR,
+      timeout: 5,
+    });
+  });
+
+  it('waits for archive post links before scraping archive pages', async () => {
+    const page = createPageMock([]);
+
+    await loadSubstackArchive(page, 'https://example.substack.com', 5);
+
+    expect(page.wait).toHaveBeenCalledWith({
+      selector: __test__.ARCHIVE_POST_LINK_SELECTOR,
+      timeout: 5,
+    });
+  });
+});

package/src/clis/substack/utils.ts

@@ -1,6 +1,9 @@
 import { CommandExecutionError } from '../../errors.js';
 import type { IPage } from '../../types.js';
 
+const FEED_POST_LINK_SELECTOR = 'a[href*="/home/post/"], a[href*="/p/"]';
+const ARCHIVE_POST_LINK_SELECTOR = 'a[href*="/p/"]';
+
 export function buildSubstackBrowseUrl(category?: string): string {
   if (!category || category === 'all') return 'https://substack.com/';
   const slug = category === 'tech' ? 'technology' : category;
@@ -10,7 +13,7 @@ export function buildSubstackBrowseUrl(category?: string): string {
 export async function loadSubstackFeed(page: IPage, url: string, limit: number): Promise<any[]> {
   if (!page) throw new CommandExecutionError('Browser session required for substack feed');
   await page.goto(url);
-  await page.wait({ selector: 'article', timeout: 5 });
+  await page.wait({ selector: FEED_POST_LINK_SELECTOR, timeout: 5 });
   const data = await page.evaluate(`
     (async () => {
       await new Promise((resolve) => setTimeout(resolve, 3000));
@@ -79,7 +82,7 @@ export async function loadSubstackFeed(page: IPage, url: string, limit: number):
 export async function loadSubstackArchive(page: IPage, baseUrl: string, limit: number): Promise<any[]> {
   if (!page) throw new CommandExecutionError('Browser session required for substack archive');
   await page.goto(`${baseUrl}/archive`);
-  await page.wait({ selector: 'article', timeout: 5 });
+  await page.wait({ selector: ARCHIVE_POST_LINK_SELECTOR, timeout: 5 });
   const data = await page.evaluate(`
     (async () => {
       await new Promise((resolve) => setTimeout(resolve, 3000));
@@ -131,3 +134,8 @@ export async function loadSubstackArchive(page: IPage, baseUrl: string, limit: n
 
   return Array.isArray(data) ? data : [];
 }
+
+export const __test__ = {
+  FEED_POST_LINK_SELECTOR,
+  ARCHIVE_POST_LINK_SELECTOR,
+};

package/src/clis/tieba/commands.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from 'vitest';
+import { Strategy, getRegistry } from '../../registry.js';
+import './hot.js';
+import './posts.js';
+import './read.js';
+import './search.js';
+
+describe('tieba commands', () => {
+  it('registers all tieba commands as TypeScript adapters', () => {
+    const hot = getRegistry().get('tieba/hot');
+    const posts = getRegistry().get('tieba/posts');
+    const search = getRegistry().get('tieba/search');
+    const read = getRegistry().get('tieba/read');
+
+    expect(hot).toBeDefined();
+    expect(posts).toBeDefined();
+    expect(search).toBeDefined();
+    expect(read).toBeDefined();
+    expect(typeof hot?.func).toBe('function');
+    expect(typeof posts?.func).toBe('function');
+    expect(typeof search?.func).toBe('function');
+    expect(typeof read?.func).toBe('function');
+  });
+
+  it('keeps the intended browser strategies', () => {
+    const hot = getRegistry().get('tieba/hot');
+    const posts = getRegistry().get('tieba/posts');
+    const search = getRegistry().get('tieba/search');
+    const read = getRegistry().get('tieba/read');
+
+    expect(hot?.strategy).toBe(Strategy.PUBLIC);
+    expect(posts?.strategy).toBe(Strategy.COOKIE);
+    expect(search?.strategy).toBe(Strategy.COOKIE);
+    expect(read?.strategy).toBe(Strategy.COOKIE);
+    expect(hot?.browser).toBe(true);
+    expect(posts?.browser).toBe(true);
+    expect(search?.browser).toBe(true);
+    expect(read?.browser).toBe(true);
+  });
+
+  it('keeps the public limit contract at 20 items for list commands', () => {
+    const hot = getRegistry().get('tieba/hot');
+    const posts = getRegistry().get('tieba/posts');
+    const search = getRegistry().get('tieba/search');
+
+    expect(hot?.args.find((arg) => arg.name === 'limit')?.default).toBe(20);
+    expect(posts?.args.find((arg) => arg.name === 'limit')?.default).toBe(20);
+    expect(search?.args.find((arg) => arg.name === 'limit')?.default).toBe(20);
+  });
+
+  it('rejects tieba read results when navigation lands on the wrong page number', async () => {
+    const read = getRegistry().get('tieba/read');
+    expect(read).toBeDefined();
+    expect(typeof read?.func).toBe('function');
+    const run = read?.func;
+    if (!run) throw new Error('tieba/read did not register a handler');
+    const page = {
+      goto: async () => undefined,
+      evaluate: async () => ({
+        pageMeta: {
+          pathname: '/p/10163164720',
+          pn: '1',
+        },
+        mainPost: {
+          title: '测试帖子',
+          author: '作者',
+          contentText: '正文',
+          structuredText: '',
+          visibleTime: '2026-03-29 12:00',
+          structuredTime: 0,
+          hasMedia: false,
+        },
+        replies: [],
+      }),
+    };
+
+    await expect(run(page as never, {
+      id: '10163164720',
+      page: 2,
+      limit: 5,
+    })).rejects.toMatchObject({
+      code: 'EMPTY_RESULT',
+      hint: expect.stringMatching(/requested page/i),
+    });
+  });
+});

package/src/clis/tieba/hot.ts

@@ -0,0 +1,52 @@
+import { EmptyResultError } from '../../errors.js';
+import { cli, Strategy } from '../../registry.js';
+import { normalizeTiebaLimit } from './utils.js';
+
+cli({
+  site: 'tieba',
+  name: 'hot',
+  description: 'Tieba hot topics',
+  domain: 'tieba.baidu.com',
+  strategy: Strategy.PUBLIC,
+  browser: true,
+  navigateBefore: false,
+  args: [
+    { name: 'limit', type: 'int', default: 20, help: 'Number of items to return' },
+  ],
+  columns: ['rank', 'title', 'discussions', 'description'],
+  func: async (page, kwargs) => {
+    const limit = normalizeTiebaLimit(kwargs.limit);
+    // Use the default browser settle path so we do not scrape the previous page.
+    await page.goto('https://tieba.baidu.com/hottopic/browse/topicList?res_type=1');
+
+    const raw = await page.evaluate(`(() => {
+      const items = document.querySelectorAll('li.topic-top-item');
+      return Array.from(items).map((item) => {
+        const titleEl = item.querySelector('a.topic-text');
+        const numEl = item.querySelector('span.topic-num');
+        const descEl = item.querySelector('p.topic-top-item-desc');
+        const href = titleEl?.getAttribute('href') || '';
+
+        return {
+          title: titleEl?.textContent?.trim() || '',
+          discussions: numEl?.textContent?.trim() || '',
+          description: descEl?.textContent?.trim() || '',
+          url: href.startsWith('http') ? href : 'https://tieba.baidu.com' + href,
+        };
+      }).filter((item) => item.title).slice(0, ${limit});
+    })()`);
+
+    const items = Array.isArray(raw) ? raw as Array<Record<string, string>> : [];
+    if (!items.length) {
+      throw new EmptyResultError('tieba hot', 'Tieba may have blocked the hot page, or the DOM structure may have changed');
+    }
+
+    return items.map((item, index) => ({
+      rank: index + 1,
+      title: item.title || '',
+      discussions: item.discussions || '',
+      description: item.description || '',
+      url: item.url || '',
+    }));
+  },
+});

package/src/clis/tieba/posts.ts

@@ -0,0 +1,108 @@
+import { EmptyResultError } from '../../errors.js';
+import { cli, Strategy, type CommandArgs } from '../../registry.js';
+import type { IPage } from '../../types.js';
+import {
+  buildTiebaPostCardsFromPagePc,
+  buildTiebaPostItems,
+  normalizeTiebaLimit,
+  signTiebaPcParams,
+  type RawTiebaPagePcFeedEntry,
+} from './utils.js';
+
+interface TiebaPagePcResponse {
+  error_code?: number;
+  page_data?: {
+    feed_list?: RawTiebaPagePcFeedEntry[];
+  };
+}
+
+function getForumPageNumber(kwargs: CommandArgs): number {
+  return Math.max(1, Number(kwargs.page || 1));
+}
+
+function getForumUrl(kwargs: CommandArgs): string {
+  const forum = String(kwargs.forum || '');
+  return `https://tieba.baidu.com/f?kw=${encodeURIComponent(forum)}&ie=utf-8&pn=${(getForumPageNumber(kwargs) - 1) * 50}`;
+}
+
+/**
+ * Rebuild the signed page_pc request instead of scraping only the visible thread cards.
+ */
+function buildTiebaPagePcParams(kwargs: CommandArgs, limit: number): Record<string, string> {
+  return {
+    kw: encodeURIComponent(String(kwargs.forum || '')),
+    pn: String(getForumPageNumber(kwargs)),
+    sort_type: '-1',
+    is_newfrs: '1',
+    is_newfeed: '1',
+    rn: '30',
+    rn_need: String(Math.min(Math.max(limit + 10, 10), 30)),
+    tbs: '',
+    subapp_type: 'pc',
+    _client_type: '20',
+  };
+}
+
+/**
+ * Tieba expects the signed forum-list request to be replayed with the browser's cookies.
+ */
+async function fetchTiebaPagePc(page: IPage, kwargs: CommandArgs, limit: number): Promise<TiebaPagePcResponse> {
+  await page.goto(getForumUrl(kwargs), { waitUntil: 'none' });
+  await page.wait(2);
+
+  const params = buildTiebaPagePcParams(kwargs, limit);
+  const cookies = await page.getCookies({ domain: 'tieba.baidu.com' });
+  const cookieHeader = cookies.map((item) => `${item.name}=${item.value}`).join('; ');
+  const body = new URLSearchParams({
+    ...params,
+    sign: signTiebaPcParams(params),
+  }).toString();
+
+  const response = await fetch('https://tieba.baidu.com/c/f/frs/page_pc', {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/x-www-form-urlencoded;charset=UTF-8',
+      cookie: cookieHeader,
+      'x-requested-with': 'XMLHttpRequest',
+      referer: getForumUrl(kwargs),
+      'user-agent': 'Mozilla/5.0',
+    },
+    body,
+  });
+
+  const text = await response.text();
+  try {
+    return JSON.parse(text) as TiebaPagePcResponse;
+  } catch {
+    return {};
+  }
+}
+
+cli({
+  site: 'tieba',
+  name: 'posts',
+  description: 'Browse posts in a tieba forum',
+  domain: 'tieba.baidu.com',
+  strategy: Strategy.COOKIE,
+  browser: true,
+  navigateBefore: false,
+  args: [
+    { name: 'forum', positional: true, required: true, type: 'string', help: 'Forum name in Chinese' },
+    { name: 'page', type: 'int', default: 1, help: 'Page number' },
+    { name: 'limit', type: 'int', default: 20, help: 'Number of items to return' },
+  ],
+  columns: ['rank', 'title', 'author', 'replies'],
+  func: async (page, kwargs) => {
+    const limit = normalizeTiebaLimit(kwargs.limit);
+    const payload = await fetchTiebaPagePc(page, kwargs, limit);
+    const rawFeeds = Array.isArray(payload.page_data?.feed_list) ? payload.page_data.feed_list : [];
+    const rawCards = buildTiebaPostCardsFromPagePc(rawFeeds);
+    const items = buildTiebaPostItems(rawCards, limit);
+
+    if (!items.length || payload.error_code) {
+      throw new EmptyResultError('tieba posts', 'Tieba may have blocked the forum page, or the DOM structure may have changed');
+    }
+
+    return items;
+  },
+});

package/src/clis/tieba/read.ts

@@ -0,0 +1,158 @@
+import { EmptyResultError } from '../../errors.js';
+import { cli, Strategy, type CommandArgs } from '../../registry.js';
+import { buildTiebaReadItems, type RawTiebaReadPayload } from './utils.js';
+
+type TiebaReadPageMeta = {
+  pathname?: string;
+  pn?: string;
+};
+
+type RawTiebaReadPagePayload = RawTiebaReadPayload & {
+  pageMeta?: TiebaReadPageMeta;
+};
+
+function getThreadUrl(kwargs: CommandArgs): string {
+  const threadId = String(kwargs.id || '');
+  const pageNumber = Math.max(1, Number(kwargs.page || 1));
+  return `https://tieba.baidu.com/p/${encodeURIComponent(threadId)}?pn=${pageNumber}`;
+}
+
+/**
+ * Ensure the browser actually landed on the requested thread page before we trust the DOM.
+ */
+function assertTiebaReadTargetPage(raw: RawTiebaReadPagePayload, kwargs: CommandArgs): void {
+  const expectedThreadId = String(kwargs.id || '').trim();
+  const expectedPageNumber = Math.max(1, Number(kwargs.page || 1));
+  const pathname = String(raw.pageMeta?.pathname || '').trim();
+  const actualThreadId = pathname.match(/^\/p\/(\d+)/)?.[1] || '';
+  const actualPn = String(raw.pageMeta?.pn || '').trim();
+
+  if (!actualThreadId || actualThreadId !== expectedThreadId) {
+    throw new EmptyResultError('tieba read', 'Tieba did not land on the requested thread page');
+  }
+
+  if (expectedPageNumber > 1 && actualPn !== String(expectedPageNumber)) {
+    throw new EmptyResultError('tieba read', 'Tieba did not land on the requested page');
+  }
+}
+
+function buildExtractReadEvaluate(): string {
+  return `
+    (async () => {
+      const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+      const waitFor = async (predicate, timeoutMs = 4000) => {
+        const start = Date.now();
+        while (Date.now() - start < timeoutMs) {
+          if (predicate()) return true;
+          await wait(100);
+        }
+        return false;
+      };
+      const normalizeText = (value) => (value || '').replace(/\\s+/g, ' ').trim();
+      const getVueProps = (element) => {
+        const vue = element && element.__vue__ ? element.__vue__ : null;
+        return vue ? (vue._props || vue.$props || {}) : {};
+      };
+      const extractStructuredText = (content) => {
+        if (!Array.isArray(content)) return '';
+        return content
+          .map((part) => (part && typeof part === 'object' && typeof part.text === 'string') ? part.text : '')
+          .join('')
+          .replace(/\\s+/g, ' ')
+          .trim();
+      };
+      const parseFloor = (text) => {
+        const match = (text || '').match(/第(\\d+)楼/);
+        return match ? parseInt(match[1], 10) : 0;
+      };
+
+      await waitFor(() => {
+        const hasMainTree = document.querySelector('.pb-title-wrap.pc-pb-title') || document.querySelector('.pb-content-wrap');
+        return Boolean(hasMainTree || document.querySelector('.pb-comment-item'));
+      });
+
+      const titleNode = document.querySelector('.pb-title-wrap.pc-pb-title');
+      const titleProps = getVueProps(titleNode);
+      const mainUser = document.querySelector('.head-line.user-info:not(.no-extra-margin)');
+      const mainUserProps = getVueProps(mainUser);
+      const contentWrap = document.querySelector('.pb-content-wrap');
+      const contentProps = getVueProps(contentWrap);
+      const structuredContent = Array.isArray(contentProps.content) ? contentProps.content : [];
+      const visibleContent = normalizeText(
+        contentWrap?.querySelector('.pb-content-item .text')?.textContent
+        || contentWrap?.querySelector('.text')?.textContent
+        || contentWrap?.textContent
+      );
+
+      return {
+        pageMeta: {
+          pathname: window.location.pathname || '',
+          pn: new URLSearchParams(window.location.search).get('pn') || '',
+        },
+        mainPost: {
+          title: typeof titleProps.title === 'string' && titleProps.title.trim()
+            ? titleProps.title.trim()
+            : normalizeText(titleNode?.textContent).replace(/-百度贴吧$/, '').trim(),
+          author: normalizeText(
+            mainUser?.querySelector('.head-name')?.textContent
+            || mainUser?.querySelector('.name-info .head-name')?.textContent
+            || ''
+          ),
+          fallbackAuthor: mainUserProps?.userShowInfo?.[0]?.text?.text || '',
+          contentText: visibleContent,
+          structuredText: extractStructuredText(structuredContent),
+          visibleTime: (() => {
+            const userText = normalizeText(mainUser?.textContent);
+            const match = userText.match(/(刚刚|昨天|前天|\\d+\\s*(?:分钟|小时|天)前|\\d{2}-\\d{2}(?:\\s+\\d{2}:\\d{2})?|\\d{4}-\\d{2}-\\d{2}(?:\\s+\\d{2}:\\d{2})?)/);
+            return match ? match[1].trim() : '';
+          })(),
+          structuredTime: mainUserProps?.descInfo?.time || 0,
+          hasMedia: structuredContent.length > 0 && !extractStructuredText(structuredContent),
+        },
+        replies: Array.from(document.querySelectorAll('.pb-comment-item')).map((item) => {
+          const meta = item.querySelector('.comment-desc-left')?.textContent?.replace(/\\s+/g, ' ').trim() || '';
+          return {
+            floor: parseFloor(meta),
+            author: item.querySelector('.head-name')?.textContent?.trim() || '',
+            content: item.querySelector('.comment-content .pb-content-item .text')?.textContent?.replace(/\\s+/g, ' ').trim() || '',
+            time: meta,
+          };
+        }),
+      };
+    })()
+  `;
+}
+
+cli({
+  site: 'tieba',
+  name: 'read',
+  description: 'Read a tieba thread',
+  domain: 'tieba.baidu.com',
+  strategy: Strategy.COOKIE,
+  browser: true,
+  navigateBefore: false,
+  args: [
+    { name: 'id', positional: true, required: true, type: 'string', help: 'Thread ID' },
+    { name: 'page', type: 'int', default: 1, help: 'Page number' },
+    { name: 'limit', type: 'int', default: 30, help: 'Number of replies to return' },
+  ],
+  columns: ['floor', 'author', 'content', 'time'],
+  func: async (page, kwargs) => {
+    const pageNumber = Math.max(1, Number(kwargs.page || 1));
+    // Use the browser's normal settle path so we do not scrape stale DOM from the previous tab state.
+    await page.goto(getThreadUrl(kwargs));
+
+    const raw = (await page.evaluate(buildExtractReadEvaluate()) || {}) as RawTiebaReadPagePayload;
+    assertTiebaReadTargetPage(raw, kwargs);
+
+    const items = buildTiebaReadItems(raw, {
+      limit: kwargs.limit,
+      includeMainPost: pageNumber === 1,
+    });
+    if (!items.length) {
+      throw new EmptyResultError('tieba read', 'Tieba may have blocked the thread page, or the DOM structure may have changed');
+    }
+
+    return items;
+  },
+});