@jackwener/opencli 1.7.17 → 1.7.18

package/clis/xiaohongshu/notifications.js

@@ -1,23 +1,11 @@
 import { cli, Strategy } from '@jackwener/opencli/registry';
-cli({
-    site: 'xiaohongshu',
-    name: 'notifications',
-    access: 'read',
-    description: '小红书通知 (mentions/likes/connections)',
-    domain: 'www.xiaohongshu.com',
-    strategy: Strategy.INTERCEPT,
-    browser: true,
-    args: [
-        {
-            name: 'type',
-            default: 'mentions',
-            help: 'Notification type: mentions, likes, or connections',
-        },
-        { name: 'limit', type: 'int', default: 20, help: 'Number of notifications to return' },
-    ],
-    columns: ['rank', 'user', 'action', 'content', 'note', 'time'],
-    pipeline: [
-        { navigate: 'https://www.xiaohongshu.com/notification' },
+/**
+ * Build the notifications pipeline for the given web host. Exported so the
+ * rednote adapter can register the same pipeline against www.rednote.com.
+ */
+export function buildNotificationsPipeline(webHost) {
+    return [
+        { navigate: `https://${webHost}/notification` },
         { tap: {
                 store: 'notification',
                 action: 'getNotification',
@@ -35,5 +23,24 @@ cli({
                 time: '${{ item.time }}',
             } },
         { limit: '${{ args.limit | default(20) }}' },
+    ];
+}
+export const command = cli({
+    site: 'xiaohongshu',
+    name: 'notifications',
+    access: 'read',
+    description: '小红书通知 (mentions/likes/connections)',
+    domain: 'www.xiaohongshu.com',
+    strategy: Strategy.INTERCEPT,
+    browser: true,
+    args: [
+        {
+            name: 'type',
+            default: 'mentions',
+            help: 'Notification type: mentions, likes, or connections',
+        },
+        { name: 'limit', type: 'int', default: 20, help: 'Number of notifications to return' },
     ],
+    columns: ['rank', 'user', 'action', 'content', 'note', 'time'],
+    pipeline: buildNotificationsPipeline('www.xiaohongshu.com'),
 });

package/clis/xiaohongshu/search.js

@@ -52,37 +52,19 @@ export function stripXhsAuthorDateSuffix(value) {
     const stripped = text.replace(/\s*(?:\d{1,2}天前|\d+小时前|\d+分钟前|\d+秒前|刚刚|昨天|前天|\d+周前|\d+个月前|\d{1,2}-\d{1,2}|\d{4}-\d{1,2}-\d{1,2})$/u, '').trim();
     return stripped || text;
 }
-cli({
-    site: 'xiaohongshu',
-    name: 'search',
-    access: 'read',
-    description: '搜索小红书笔记',
-    domain: 'www.xiaohongshu.com',
-    strategy: Strategy.COOKIE,
-    navigateBefore: false,
-    args: [
-        { name: 'query', required: true, positional: true, help: 'Search keyword' },
-        { name: 'limit', type: 'int', default: 20, help: 'Number of results' },
-    ],
-    columns: ['rank', 'title', 'author', 'likes', 'published_at', 'url'],
-    func: async (page, kwargs) => {
-        const keyword = encodeURIComponent(kwargs.query);
-        await page.goto(`https://www.xiaohongshu.com/search_result?keyword=${keyword}&source=web_search_result_notes`);
-        // Wait for search results to render (or login wall to appear).
-        // Uses MutationObserver to resolve as soon as content appears,
-        // instead of a fixed delay + blind retry.
-        const waitResult = await page.evaluate(WAIT_FOR_CONTENT_JS);
-        if (waitResult === 'login_wall') {
-            throw new AuthRequiredError('www.xiaohongshu.com', 'Xiaohongshu search results are blocked behind a login wall');
-        }
-        // Scroll a couple of times to load more results
-        await page.autoScroll({ times: 2 });
-        const payload = await page.evaluate(`
+/**
+ * Build the search-result extraction IIFE. The web host is baked into the
+ * `normalizeUrl` fallback so relative `/explore/...` hrefs resolve to a full
+ * URL on the calling site. Exported so the rednote adapter can call it with
+ * `www.rednote.com` without duplicating the selector logic.
+ */
+export function buildSearchExtractJs(webHost) {
+    return `
       (() => {
         const normalizeUrl = (href) => {
           if (!href) return '';
           if (href.startsWith('http://') || href.startsWith('https://')) return href;
-          if (href.startsWith('/')) return 'https://www.xiaohongshu.com' + href;
+          if (href.startsWith('/')) return 'https://${webHost}' + href;
           return '';
         };
 
@@ -131,7 +113,34 @@ cli({
 
         return results;
       })()
-    `);
+    `;
+}
+export const command = cli({
+    site: 'xiaohongshu',
+    name: 'search',
+    access: 'read',
+    description: '搜索小红书笔记',
+    domain: 'www.xiaohongshu.com',
+    strategy: Strategy.COOKIE,
+    navigateBefore: false,
+    args: [
+        { name: 'query', required: true, positional: true, help: 'Search keyword' },
+        { name: 'limit', type: 'int', default: 20, help: 'Number of results' },
+    ],
+    columns: ['rank', 'title', 'author', 'likes', 'published_at', 'url'],
+    func: async (page, kwargs) => {
+        const keyword = encodeURIComponent(kwargs.query);
+        await page.goto(`https://www.xiaohongshu.com/search_result?keyword=${keyword}&source=web_search_result_notes`);
+        // Wait for search results to render (or login wall to appear).
+        // Uses MutationObserver to resolve as soon as content appears,
+        // instead of a fixed delay + blind retry.
+        const waitResult = await page.evaluate(WAIT_FOR_CONTENT_JS);
+        if (waitResult === 'login_wall') {
+            throw new AuthRequiredError('www.xiaohongshu.com', 'Xiaohongshu search results are blocked behind a login wall');
+        }
+        // Scroll a couple of times to load more results
+        await page.autoScroll({ times: 2 });
+        const payload = await page.evaluate(buildSearchExtractJs('www.xiaohongshu.com'));
         const data = Array.isArray(payload) ? payload : [];
         return data
             .filter((item) => item.title)

package/clis/xiaohongshu/user-helpers.js

@@ -27,12 +27,17 @@ export function flattenXhsNoteGroups(noteGroups) {
     }
     return notes;
 }
-export function buildXhsNoteUrl(userId, noteId, xsecToken) {
+/**
+ * Build a signed user-profile note URL on the given web host (defaults to
+ * `www.xiaohongshu.com`). The rednote adapter passes `'www.rednote.com'` so
+ * the same builder works for both sites.
+ */
+export function buildXhsNoteUrl(userId, noteId, xsecToken, webHost = 'www.xiaohongshu.com') {
     const cleanUserId = toCleanString(userId);
     const cleanNoteId = toCleanString(noteId);
     if (!cleanUserId || !cleanNoteId)
         return '';
-    const url = new URL(`https://www.xiaohongshu.com/user/profile/${cleanUserId}/${cleanNoteId}`);
+    const url = new URL(`https://${webHost}/user/profile/${cleanUserId}/${cleanNoteId}`);
     const cleanToken = toCleanString(xsecToken);
     if (cleanToken) {
         url.searchParams.set('xsec_token', cleanToken);
@@ -40,7 +45,11 @@ export function buildXhsNoteUrl(userId, noteId, xsecToken) {
     }
     return url.toString();
 }
-export function extractXhsUserNotes(snapshot, fallbackUserId) {
+/**
+ * Normalise a Pinia user-store snapshot into CLI rows. `webHost` is forwarded
+ * to `buildXhsNoteUrl` so the resulting URLs point at the calling site.
+ */
+export function extractXhsUserNotes(snapshot, fallbackUserId, webHost = 'www.xiaohongshu.com') {
     const notes = flattenXhsNoteGroups(snapshot.noteGroups);
     const rows = [];
     const seen = new Set();
@@ -62,7 +71,7 @@ export function extractXhsUserNotes(snapshot, fallbackUserId) {
             type: toCleanString(noteCard.type),
             likes,
             cover,
-            url: buildXhsNoteUrl(userId || fallbackUserId, noteId, xsecToken),
+            url: buildXhsNoteUrl(userId || fallbackUserId, noteId, xsecToken, webHost),
         });
     }
     return rows;

package/clis/xiaohongshu/user-helpers.test.js

@@ -20,6 +20,9 @@ describe('buildXhsNoteUrl', () => {
     it('includes xsec token when available', () => {
         expect(buildXhsNoteUrl('user123', 'note456', 'token789')).toBe('https://www.xiaohongshu.com/user/profile/user123/note456?xsec_token=token789&xsec_source=pc_user');
     });
+    it('emits a rednote URL when webHost is overridden', () => {
+        expect(buildXhsNoteUrl('user123', 'note456', 'token789', 'www.rednote.com')).toBe('https://www.rednote.com/user/profile/user123/note456?xsec_token=token789&xsec_source=pc_user');
+    });
 });
 describe('extractXhsUserNotes', () => {
     it('normalizes grouped note cards into CLI rows', () => {
@@ -96,4 +99,21 @@ describe('extractXhsUserNotes', () => {
         expect(rows).toHaveLength(1);
         expect(rows[0]?.title).toBe('keep me');
     });
+    it('emits rednote-hosted URLs when webHost is overridden', () => {
+        const rows = extractXhsUserNotes({
+            noteGroups: [
+                [
+                    {
+                        xsecToken: 'tok',
+                        noteCard: {
+                            noteId: 'note-red',
+                            displayTitle: 'rednote note',
+                            user: { userId: 'user-red' },
+                        },
+                    },
+                ],
+            ],
+        }, 'fallback-user', 'www.rednote.com');
+        expect(rows[0]?.url).toBe('https://www.rednote.com/user/profile/user-red/note-red?xsec_token=tok&xsec_source=pc_user');
+    });
 });

package/clis/xiaohongshu/user.js

@@ -1,7 +1,10 @@
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { extractXhsUserNotes, normalizeXhsUserId } from './user-helpers.js';
-async function readUserSnapshot(page) {
-    return await page.evaluate(`
+/**
+ * Host-agnostic IIFE that snapshots the user profile's Pinia store. Exported
+ * so the rednote adapter can reuse it without copying the safeClone block.
+ */
+export const USER_SNAPSHOT_JS = `
     (() => {
       const safeClone = (value) => {
         try {
@@ -17,9 +20,11 @@ async function readUserSnapshot(page) {
         pageData: safeClone(userStore.userPageData?._value || userStore.userPageData || {}),
       };
     })()
-  `);
+  `;
+async function readUserSnapshot(page) {
+    return await page.evaluate(USER_SNAPSHOT_JS);
 }
-cli({
+export const command = cli({
     site: 'xiaohongshu',
     name: 'user',
     access: 'read',

package/clis/youtube/transcript.js

@@ -86,12 +86,37 @@ cli({
             console.error(`Warning: --lang "${captionData.requestedLang}" not found. Using "${captionData.language}" instead. Available: ${captionData.available.join(', ')}`);
         }
         // Step 2: Fetch caption XML and parse segments
+        // Ensure caption URL requests srv3 XML format — YouTube may return empty
+        // responses when no explicit format is specified.
+        const originalCaptionUrl = captionData.captionUrl;
+        let captionUrl = originalCaptionUrl;
+        if (!/[&?]fmt=/.test(originalCaptionUrl)) {
+            captionUrl = originalCaptionUrl + (originalCaptionUrl.includes('?') ? '&' : '?') + 'fmt=srv3';
+        }
         const segments = await page.evaluate(`
       (async () => {
-        const resp = await fetch(${JSON.stringify(captionData.captionUrl)});
-        const xml = await resp.text();
+        async function fetchCaptionXml(url) {
+          const resp = await fetch(url);
+          if (!resp.ok) return { error: 'Caption URL returned HTTP ' + resp.status };
+          return { xml: await resp.text() || '' };
+        }
+
+        const primaryUrl = ${JSON.stringify(captionUrl)};
+        const originalUrl = ${JSON.stringify(originalCaptionUrl)};
+        let result = await fetchCaptionXml(primaryUrl);
+        if (result.error) return result;
+
+        // If srv3 format returned an empty successful body, retry with the
+        // original URL. Do not hide HTTP/non-OK failures behind fallback.
+        if (!result.xml.length && originalUrl !== primaryUrl) {
+          result = await fetchCaptionXml(originalUrl);
+          if (result.error) {
+            return result;
+          }
+        }
+        const xml = result.xml;
 
-        if (!xml?.length) {
+        if (!xml.length) {
           return { error: 'Caption URL returned empty response' };
         }
 

package/clis/youtube/transcript.test.js

@@ -1,11 +1,37 @@
-import { describe, expect, it } from 'vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 import { readFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { getRegistry } from '@jackwener/opencli/registry';
+import './transcript.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const transcriptSource = readFileSync(resolve(__dirname, 'transcript.js'), 'utf8');
 
+function createPageMock(captionUrl) {
+    const page = {
+        goto: vi.fn().mockResolvedValue(undefined),
+        wait: vi.fn().mockResolvedValue(undefined),
+        evaluate: vi.fn(),
+    };
+    page.evaluate
+        .mockResolvedValueOnce({
+        captionUrl,
+        language: 'en',
+        kind: 'manual',
+        available: ['en'],
+        requestedLang: null,
+        langMatched: false,
+        langPrefixMatched: false,
+    })
+        .mockResolvedValue([{ start: 1, end: 3, text: 'hello & world' }]);
+    return page;
+}
+
+afterEach(() => {
+    vi.unstubAllGlobals();
+});
+
 describe('youtube transcript source contract', () => {
     it('gets caption tracks from watch page bootstrap data, not Android InnerTube', () => {
         expect(transcriptSource).toContain("fetch('/watch?v='");
@@ -14,4 +40,67 @@ describe('youtube transcript source contract', () => {
         expect(transcriptSource).not.toContain('/youtubei/v1/player');
         expect(transcriptSource).not.toContain("clientName: 'ANDROID'");
     });
+
+    it('normalizes caption URL to request srv3 XML format', () => {
+        expect(transcriptSource).toContain('fmt=srv3');
+    });
+
+    it('checks HTTP status before reading caption response body', () => {
+        expect(transcriptSource).toContain('resp.ok');
+    });
+});
+
+describe('youtube transcript caption fetch', () => {
+    const command = getRegistry().get('youtube/transcript');
+
+    it('requests srv3 when the caption track URL has no explicit format', async () => {
+        const page = createPageMock('https://www.youtube.com/api/timedtext?v=abc&lang=en');
+
+        const rows = await command.func(page, { url: 'abc', mode: 'raw' });
+
+        expect(page.evaluate.mock.calls[1][0]).toContain('const primaryUrl = "https://www.youtube.com/api/timedtext?v=abc&lang=en&fmt=srv3"');
+        expect(page.evaluate.mock.calls[1][0]).toContain('const originalUrl = "https://www.youtube.com/api/timedtext?v=abc&lang=en"');
+        expect(rows).toEqual([{ index: 1, start: '1.00s', end: '3.00s', text: 'hello & world' }]);
+    });
+
+    it('does not override an existing caption format', async () => {
+        const page = createPageMock('https://www.youtube.com/api/timedtext?v=abc&lang=en&fmt=vtt');
+
+        await command.func(page, { url: 'abc', mode: 'raw' });
+
+        expect(page.evaluate.mock.calls[1][0]).toContain('const primaryUrl = "https://www.youtube.com/api/timedtext?v=abc&lang=en&fmt=vtt"');
+        expect(page.evaluate.mock.calls[1][0]).toContain('const originalUrl = "https://www.youtube.com/api/timedtext?v=abc&lang=en&fmt=vtt"');
+    });
+
+    it('falls back to the original URL only after an empty successful srv3 response', async () => {
+        const page = createPageMock('https://www.youtube.com/api/timedtext?v=abc&lang=en');
+
+        await command.func(page, { url: 'abc', mode: 'raw' });
+
+        const script = page.evaluate.mock.calls[1][0];
+        expect(script).toContain('if (!result.xml.length && originalUrl !== primaryUrl)');
+        expect(script).toContain('result = await fetchCaptionXml(originalUrl)');
+        expect(script).toContain('if (result.error) {');
+    });
+
+    it('fails typed on caption HTTP errors instead of falling back silently', async () => {
+        const page = createPageMock('https://www.youtube.com/api/timedtext?v=abc&lang=en');
+        page.evaluate.mockReset();
+        page.evaluate
+            .mockResolvedValueOnce({
+            captionUrl: 'https://www.youtube.com/api/timedtext?v=abc&lang=en',
+            language: 'en',
+            kind: 'manual',
+            available: ['en'],
+            requestedLang: null,
+            langMatched: false,
+            langPrefixMatched: false,
+        })
+            .mockResolvedValueOnce({ error: 'Caption URL returned HTTP 503' });
+
+        await expect(command.func(page, { url: 'abc', mode: 'raw' })).rejects.toMatchObject({
+            code: 'COMMAND_EXEC',
+            message: expect.stringContaining('HTTP 503'),
+        });
+    });
 });

package/dist/src/cli.js

@@ -600,7 +600,7 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
     // All commands wrapped in browserAction() for consistent error handling.
     const browser = program
         .command('browser')
-        .option('--session <name>', 'Browser session to use')
+        .requiredOption('--session <name>', 'Browser session to use (required)')
         .option('--window <mode>', 'Browser window mode: foreground or background')
         .description('Browser control — navigate, click, type, extract, wait (no LLM needed)');
     const originalBrowserDescription = browser.description();
@@ -723,7 +723,7 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
         };
     }
     browser.command('bind')
-        .option('--session <name>', 'Browser session name to bind')
+        .option('--session <name>', 'Browser session name to bind (required)')
         .description('Bind the current Chrome tab/window to a browser session')
         .action(async (optsOrCommand, maybeCommand) => {
         const command = optsOrCommand instanceof Command ? optsOrCommand : maybeCommand;
@@ -754,7 +754,7 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
         }
     });
     browser.command('unbind')
-        .option('--session <name>', 'Browser session name to detach')
+        .option('--session <name>', 'Browser session name to detach (required)')
         .description('Detach a bound browser session without closing the user tab/window')
         .action(async (optsOrCommand, maybeCommand) => {
         const command = optsOrCommand instanceof Command ? optsOrCommand : maybeCommand;

package/dist/src/cli.test.js

@@ -354,6 +354,8 @@ describe('createProgram root help descriptions', () => {
                     name: 'session',
                     flags: '--session <name>',
                     takes_value: 'required',
+                    required: true,
+                    help: expect.stringContaining('required'),
                 }),
                 expect.objectContaining({
                     name: 'window',
@@ -896,10 +898,13 @@ describe('browser tab targeting commands', () => {
     });
     it('requires an explicit session for browser commands', async () => {
         const program = createProgram('', '');
-        await program.parseAsync(['node', 'opencli', 'browser', 'state']);
+        program.exitOverride((err) => { throw err; });
+        program.commands.find(cmd => cmd.name() === 'browser')?.exitOverride((err) => { throw err; });
+        await expect(program.parseAsync(['node', 'opencli', 'browser', 'state'])).rejects.toMatchObject({
+            code: 'commander.missingMandatoryOptionValue',
+        });
         expect(mockBrowserConnect).not.toHaveBeenCalled();
-        expect(stderrSpy.mock.calls.flat().join('')).toContain('--session <name> is required');
-        expect(process.exitCode).toBeDefined();
+        expect(stderrSpy.mock.calls.flat().join('')).toContain("required option '--session <name>' not specified");
     });
     it('runs browser commands against an explicit session', async () => {
         const program = createProgram('', '');

package/dist/src/doctor.js

@@ -14,6 +14,7 @@ import { aliasForContextId, loadProfileConfig } from './browser/profile.js';
 import { formatDaemonVersion, isDaemonStale, staleDaemonIssue } from './browser/daemon-version.js';
 import { findShadowedUserAdapters, formatAdapterShadowIssue } from './adapter-shadow.js';
 const DOCTOR_LIVE_TIMEOUT_SECONDS = 8;
+const DOCTOR_SESSION = '__doctor__';
 /** Parse a semver string into [major, minor, patch]. Returns null on invalid input. */
 function parseSemver(v) {
     const parts = v.replace(/^v/, '').split('-')[0].split('.').map(Number);
@@ -50,7 +51,11 @@ export async function checkConnectivity(opts) {
     const start = Date.now();
     try {
         const bridge = new BrowserBridge();
-        const page = await bridge.connect({ timeout: opts?.timeout ?? DOCTOR_LIVE_TIMEOUT_SECONDS });
+        const page = await bridge.connect({
+            timeout: opts?.timeout ?? DOCTOR_LIVE_TIMEOUT_SECONDS,
+            session: DOCTOR_SESSION,
+            surface: 'browser',
+        });
         try {
             // Try a simple eval to verify end-to-end connectivity.
             await page.evaluate('1 + 1');

package/dist/src/doctor.test.js

@@ -173,6 +173,8 @@ describe('doctor report rendering', () => {
         const closeWindow = vi.fn().mockResolvedValue(undefined);
         mockConnect.mockImplementationOnce(async (opts) => {
             timeoutSeen = opts?.timeout;
+            expect(opts?.session).toBe('__doctor__');
+            expect(opts?.surface).toBe('browser');
             return {
                 evaluate: vi.fn().mockResolvedValue(2),
                 closeWindow,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jackwener/opencli",
-  "version": "1.7.17",
+  "version": "1.7.18",
   "publishConfig": {
     "access": "public"
   },