@jackwener/opencli 1.7.17 → 1.7.19

package/clis/reddit/subreddit-info.js

@@ -0,0 +1,117 @@
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import { cli, Strategy } from '@jackwener/opencli/registry';
+
+// Reddit subreddit names: 3–21 chars, letters/digits/underscore, must start
+// with a letter. Accept an optional `r/` prefix and normalise it off.
+const SUBREDDIT_NAME_RE = /^[A-Za-z][A-Za-z0-9_]{2,20}$/;
+
+export function parseSubredditName(raw) {
+    let name = String(raw || '').trim();
+    if (!name) {
+        throw new ArgumentError(
+            'Subreddit name is required.',
+            'Pass a subreddit name like `python` (or `r/python`).',
+        );
+    }
+    if (name.startsWith('/r/')) name = name.slice(3);
+    else if (name.startsWith('r/')) name = name.slice(2);
+    if (!SUBREDDIT_NAME_RE.test(name)) {
+        throw new ArgumentError(
+            'Invalid subreddit name.',
+            'Subreddit names are 3–21 characters, start with a letter, and contain only letters, digits, and underscores.',
+        );
+    }
+    return name;
+}
+
+cli({
+    site: 'reddit',
+    name: 'subreddit-info',
+    access: 'read',
+    description: 'Show metadata for a Reddit subreddit (subscribers, description, created date, NSFW)',
+    domain: 'reddit.com',
+    strategy: Strategy.COOKIE,
+    browser: true,
+    siteSession: 'persistent',
+    args: [
+        { name: 'name', type: 'string', required: true, positional: true, help: 'Subreddit name (no `r/` prefix needed)' },
+    ],
+    columns: ['field', 'value'],
+    func: async (page, kwargs) => {
+        const sub = parseSubredditName(kwargs.name);
+        await page.goto('https://www.reddit.com');
+        // Banned / private / non-existent subreddits return a 404 envelope
+        // ({"error":404,"reason":"banned"|"private"|null,"message":"Not Found"}).
+        // We surface those as EmptyResultError so the table never contains a
+        // silent sentinel row. Intermediate keys avoid `field`/`value`.
+        const result = await page.evaluate(`(async () => {
+      try {
+        const sub = ${JSON.stringify(sub)};
+        const res = await fetch('/r/' + encodeURIComponent(sub) + '/about.json?raw_json=1', { credentials: 'include' });
+        if (res.status === 401 || res.status === 403 || res.status === 404) {
+          return { kind: 'missing', detail: 'Subreddit r/' + sub + ' was not found or is not accessible (HTTP ' + res.status + ').' };
+        }
+        if (!res.ok) {
+          return { kind: 'http', httpStatus: res.status, where: '/r/' + sub + '/about.json' };
+        }
+        const j = await res.json();
+        // Reddit may return an envelope-style 200 with {"kind":"Listing"} or
+        // an error body for quarantined / private subs. Identify "subreddit
+        // not found / not accessible" by the absence of data.display_name.
+        if (j?.error) {
+          if (j.error === 404 || j.reason === 'banned' || j.reason === 'private' || j.reason === 'quarantined') {
+            return { kind: 'missing', detail: 'Subreddit r/' + sub + ' is ' + (j.reason || 'unavailable') + '.' };
+          }
+          return { kind: 'http', httpStatus: j.error, where: '/r/' + sub + '/about.json (' + (j.reason || 'error') + ')' };
+        }
+        const info = j?.data;
+        if (!info || !info.display_name) {
+          return { kind: 'malformed', detail: 'Reddit returned malformed subreddit info for r/' + sub + ' (missing data.display_name).' };
+        }
+        return { kind: 'ok', info };
+      } catch (e) {
+        return { kind: 'exception', detail: String(e && e.message || e) };
+      }
+    })()`);
+
+        if (result?.kind === 'missing') {
+            throw new EmptyResultError(result.detail);
+        }
+        if (result?.kind === 'http') {
+            throw new CommandExecutionError(`HTTP ${result.httpStatus} from ${result.where}`);
+        }
+        if (result?.kind === 'malformed') {
+            throw new CommandExecutionError(result.detail);
+        }
+        if (result?.kind === 'exception') {
+            throw new CommandExecutionError(`subreddit-info failed: ${result.detail}`);
+        }
+        if (result?.kind !== 'ok') {
+            throw new CommandExecutionError(`Unexpected result from reddit subreddit-info: ${JSON.stringify(result)}`);
+        }
+
+        const s = result.info;
+        const created = s.created_utc
+            ? new Date(s.created_utc * 1000).toISOString().split('T')[0]
+            : null;
+        const subscribers = typeof s.subscribers === 'number' ? s.subscribers : null;
+        const activeNow = typeof s.active_user_count === 'number'
+            ? s.active_user_count
+            : (typeof s.accounts_active === 'number' ? s.accounts_active : null);
+        const description = typeof s.public_description === 'string'
+            ? s.public_description.trim()
+            : '';
+
+        return [
+            { field: 'Name', value: s.display_name_prefixed || ('r/' + s.display_name) },
+            { field: 'Title', value: typeof s.title === 'string' ? s.title : null },
+            { field: 'Subscribers', value: subscribers != null ? String(subscribers) : null },
+            { field: 'Active Now', value: activeNow != null ? String(activeNow) : null },
+            { field: 'NSFW', value: s.over18 ? 'Yes' : 'No' },
+            { field: 'Type', value: typeof s.subreddit_type === 'string' ? s.subreddit_type : null },
+            { field: 'Description', value: description || null },
+            { field: 'Created', value: created },
+            { field: 'URL', value: s.url ? 'https://www.reddit.com' + s.url : null },
+        ];
+    },
+});

package/clis/reddit/subreddit-info.test.js

@@ -0,0 +1,163 @@
+import { describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import { parseSubredditName } from './subreddit-info.js';
+import './subreddit-info.js';
+
+function makePage(result) {
+    return {
+        goto: vi.fn().mockResolvedValue(undefined),
+        evaluate: vi.fn().mockResolvedValue(result),
+    };
+}
+
+describe('reddit subreddit-info command', () => {
+    const command = getRegistry().get('reddit/subreddit-info');
+
+    it('registers with the expected shape', () => {
+        expect(command).toBeDefined();
+        expect(command.access).toBe('read');
+        expect(command.browser).toBe(true);
+        expect(command.columns).toEqual(['field', 'value']);
+    });
+
+    it('parseSubredditName strips prefixes and validates the name shape', () => {
+        expect(parseSubredditName('python')).toBe('python');
+        expect(parseSubredditName('r/python')).toBe('python');
+        expect(parseSubredditName('/r/python')).toBe('python');
+        expect(parseSubredditName('  AskReddit  ')).toBe('AskReddit');
+        expect(parseSubredditName('aw3some_sub')).toBe('aw3some_sub');
+    });
+
+    it('parseSubredditName rejects invalid names without silent fallback', () => {
+        for (const bad of [
+            '',
+            '  ',
+            'py',                   // too short
+            '1abc',                 // must start with letter
+            '_sub',                 // must start with letter
+            'has space',            // no spaces
+            'has-dash',             // no dashes
+            'way_too_long_subreddit_name_here', // too long (>21)
+        ]) {
+            expect(() => parseSubredditName(bad)).toThrow(ArgumentError);
+        }
+    });
+
+    it('rejects bad subreddit names BEFORE navigating', async () => {
+        const page = makePage({ kind: 'ok', info: {} });
+        await expect(command.func(page, { name: 'has space' })).rejects.toBeInstanceOf(ArgumentError);
+        expect(page.goto).not.toHaveBeenCalled();
+        expect(page.evaluate).not.toHaveBeenCalled();
+    });
+
+    it('throws EmptyResultError for missing / banned / private / quarantined subreddits', async () => {
+        for (const detail of ['not found', 'banned', 'private', 'quarantined']) {
+            await expect(command.func(makePage({ kind: 'missing', detail }), { name: 'python' }))
+                .rejects.toBeInstanceOf(EmptyResultError);
+        }
+    });
+
+    it('treats HTTP 401/403/404 about.json responses as inaccessible subreddit, not auth-required', async () => {
+        for (const status of [401, 403, 404]) {
+            const scriptResults = [];
+            const page = {
+                goto: vi.fn().mockResolvedValue(undefined),
+                evaluate: vi.fn(async (script) => {
+                    const result = await (new Function('fetch', `return (${script})`))(vi.fn(async () => ({
+                        status,
+                        ok: false,
+                    })));
+                    scriptResults.push(result);
+                    return result;
+                }),
+            };
+            await expect(command.func(page, { name: 'python' })).rejects.toBeInstanceOf(EmptyResultError);
+            expect(scriptResults[0]).toMatchObject({ kind: 'missing' });
+        }
+    });
+
+    it('throws CommandExecutionError on HTTP and exception failure modes', async () => {
+        await expect(command.func(makePage({ kind: 'http', httpStatus: 500, where: 'about.json' }), { name: 'python' }))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+        await expect(command.func(makePage({ kind: 'exception', detail: 'bad' }), { name: 'python' }))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('throws CommandExecutionError for malformed 200 subreddit payloads', async () => {
+        await expect(command.func(makePage({
+            kind: 'malformed',
+            detail: 'Reddit returned malformed subreddit info for r/python (missing data.display_name).',
+        }), { name: 'python' }))
+            .rejects.toMatchObject({
+                code: 'COMMAND_EXEC',
+                message: expect.stringContaining('malformed subreddit info'),
+            });
+    });
+
+    it('maps a normal subreddit payload into typed field/value rows', async () => {
+        const info = {
+            display_name: 'python',
+            display_name_prefixed: 'r/python',
+            title: 'Python',
+            public_description: '  News about the programming language Python.  ',
+            subscribers: 1234567,
+            active_user_count: 4321,
+            over18: false,
+            subreddit_type: 'public',
+            created_utc: 1201881600, // 2008-02-01
+            url: '/r/python/',
+        };
+        const rows = await command.func(makePage({ kind: 'ok', info }), { name: 'python' });
+        const byField = Object.fromEntries(rows.map((r) => [r.field, r.value]));
+
+        expect(byField.Name).toBe('r/python');
+        expect(byField.Title).toBe('Python');
+        expect(byField.Subscribers).toBe('1234567');
+        expect(byField['Active Now']).toBe('4321');
+        expect(byField.NSFW).toBe('No');
+        expect(byField.Type).toBe('public');
+        expect(byField.Description).toBe('News about the programming language Python.');
+        expect(byField.Created).toBe('2008-02-01');
+        expect(byField.URL).toBe('https://www.reddit.com/r/python/');
+
+        for (const row of rows) {
+            expect(Object.keys(row).sort()).toEqual(['field', 'value']);
+        }
+    });
+
+    it('falls back to accounts_active when active_user_count is missing', async () => {
+        const info = {
+            display_name: 'sub',
+            display_name_prefixed: 'r/sub',
+            accounts_active: 99,
+            url: '/r/sub/',
+        };
+        const rows = await command.func(makePage({ kind: 'ok', info }), { name: 'sub' });
+        const byField = Object.fromEntries(rows.map((r) => [r.field, r.value]));
+        expect(byField['Active Now']).toBe('99');
+    });
+
+    it('emits typed null (not "-" sentinel) when subscribers / activity / created are missing', async () => {
+        const info = {
+            display_name: 'sparse',
+            display_name_prefixed: 'r/sparse',
+            url: '/r/sparse/',
+        };
+        const rows = await command.func(makePage({ kind: 'ok', info }), { name: 'sparse' });
+        const byField = Object.fromEntries(rows.map((r) => [r.field, r.value]));
+        expect(byField.Subscribers).toBeNull();
+        expect(byField['Active Now']).toBeNull();
+        expect(byField.Created).toBeNull();
+        expect(byField.Description).toBeNull();
+        expect(byField.Title).toBeNull();
+        expect(byField.Type).toBeNull();
+    });
+
+    it('encodes the subreddit name into the fetch URL embedded in evaluate', async () => {
+        const page = makePage({ kind: 'ok', info: { display_name: 'python', display_name_prefixed: 'r/python', url: '/r/python/' } });
+        await command.func(page, { name: 'r/python' });
+        const script = page.evaluate.mock.calls[0][0];
+        expect(script).toContain('const sub = "python"');
+    });
+});

package/clis/reddit/whoami.js

@@ -0,0 +1,84 @@
+import { AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
+import { cli, Strategy } from '@jackwener/opencli/registry';
+
+cli({
+    site: 'reddit',
+    name: 'whoami',
+    access: 'read',
+    description: 'Show the currently logged-in Reddit user',
+    domain: 'reddit.com',
+    strategy: Strategy.COOKIE,
+    browser: true,
+    siteSession: 'persistent',
+    args: [],
+    columns: ['field', 'value'],
+    func: async (page) => {
+        await page.goto('https://www.reddit.com');
+        // Probe identity via /api/me.json. Reddit returns 200 with an empty
+        // body for stale anonymous sessions, so 401/403 alone is not a
+        // sufficient logged-out signal — we also verify `data.name` exists
+        // (two-pronged auth detection from PR #1428).
+        //
+        // Intermediate object keys deliberately avoid `field` / `value` to
+        // sidestep the silent-column-drop audit (columns are ['field',
+        // 'value']) — see PR #1329 sediment "中间解析对象 key 不能跟 columns
+        // 任一项重叠".
+        const result = await page.evaluate(`(async () => {
+      try {
+        const res = await fetch('/api/me.json?raw_json=1', { credentials: 'include' });
+        if (res.status === 401 || res.status === 403) {
+          return { kind: 'auth', detail: 'Reddit /api/me.json returned HTTP ' + res.status };
+        }
+        if (!res.ok) {
+          return { kind: 'http', httpStatus: res.status, where: '/api/me.json' };
+        }
+        const d = await res.json();
+        const me = d?.data;
+        if (!me?.name) {
+          return { kind: 'auth', detail: 'Not logged in to reddit.com (no identity in /api/me.json)' };
+        }
+        return { kind: 'ok', identity: me };
+      } catch (e) {
+        return { kind: 'exception', detail: String(e && e.message || e) };
+      }
+    })()`);
+
+        if (result?.kind === 'auth') {
+            throw new AuthRequiredError('reddit.com', result.detail);
+        }
+        if (result?.kind === 'http') {
+            throw new CommandExecutionError(`HTTP ${result.httpStatus} from ${result.where}`);
+        }
+        if (result?.kind === 'exception') {
+            throw new CommandExecutionError(`whoami failed: ${result.detail}`);
+        }
+        if (result?.kind !== 'ok') {
+            throw new CommandExecutionError(`Unexpected result from reddit whoami: ${JSON.stringify(result)}`);
+        }
+
+        const u = result.identity;
+        const created = u.created_utc
+            ? new Date(u.created_utc * 1000).toISOString().split('T')[0]
+            : null;
+        const linkKarma = typeof u.link_karma === 'number' ? u.link_karma : null;
+        const commentKarma = typeof u.comment_karma === 'number' ? u.comment_karma : null;
+        const totalKarma = typeof u.total_karma === 'number'
+            ? u.total_karma
+            : (linkKarma != null && commentKarma != null ? linkKarma + commentKarma : null);
+        const inboxCount = typeof u.inbox_count === 'number' ? u.inbox_count : null;
+
+        return [
+            { field: 'Username', value: 'u/' + u.name },
+            { field: 'ID', value: u.id ? 't2_' + u.id : null },
+            { field: 'Post Karma', value: linkKarma != null ? String(linkKarma) : null },
+            { field: 'Comment Karma', value: commentKarma != null ? String(commentKarma) : null },
+            { field: 'Total Karma', value: totalKarma != null ? String(totalKarma) : null },
+            { field: 'Account Created', value: created },
+            { field: 'Gold', value: u.is_gold ? 'Yes' : 'No' },
+            { field: 'Mod', value: u.is_mod ? 'Yes' : 'No' },
+            { field: 'Verified Email', value: u.has_verified_email ? 'Yes' : 'No' },
+            { field: 'Has Mail', value: u.has_mail ? 'Yes' : 'No' },
+            { field: 'Inbox Count', value: inboxCount != null ? String(inboxCount) : null },
+        ];
+    },
+});

package/clis/reddit/whoami.test.js

@@ -0,0 +1,105 @@
+import { describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
+import './whoami.js';
+
+function makePage(result) {
+    return {
+        goto: vi.fn().mockResolvedValue(undefined),
+        evaluate: vi.fn().mockResolvedValue(result),
+    };
+}
+
+describe('reddit whoami command', () => {
+    const command = getRegistry().get('reddit/whoami');
+
+    it('registers with the expected shape', () => {
+        expect(command).toBeDefined();
+        expect(command.access).toBe('read');
+        expect(command.browser).toBe(true);
+        expect(command.columns).toEqual(['field', 'value']);
+        expect(command.args).toEqual([]);
+    });
+
+    it('throws AuthRequiredError on 401/403 from /api/me.json', async () => {
+        const page = makePage({ kind: 'auth', detail: 'Reddit /api/me.json returned HTTP 401' });
+        await expect(command.func(page, {})).rejects.toBeInstanceOf(AuthRequiredError);
+        expect(page.goto).toHaveBeenCalledWith('https://www.reddit.com');
+    });
+
+    it('throws AuthRequiredError on 200 with missing data.name (stale anon session)', async () => {
+        const page = makePage({ kind: 'auth', detail: 'Not logged in to reddit.com (no identity in /api/me.json)' });
+        await expect(command.func(page, {})).rejects.toBeInstanceOf(AuthRequiredError);
+    });
+
+    it('throws CommandExecutionError on HTTP / exception failure modes', async () => {
+        await expect(command.func(makePage({ kind: 'http', httpStatus: 500, where: '/api/me.json' }), {}))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+        await expect(command.func(makePage({ kind: 'exception', detail: 'bad json' }), {}))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('maps a full identity payload into the field/value rows', async () => {
+        const identity = {
+            name: 'alice',
+            id: 'abcdef',
+            link_karma: 1234,
+            comment_karma: 5678,
+            total_karma: 6912,
+            created_utc: 1577836800, // 2020-01-01
+            is_gold: true,
+            is_mod: false,
+            has_verified_email: true,
+            has_mail: false,
+            inbox_count: 0,
+        };
+        const page = makePage({ kind: 'ok', identity });
+        const rows = await command.func(page, {});
+
+        const byField = Object.fromEntries(rows.map((r) => [r.field, r.value]));
+        expect(byField.Username).toBe('u/alice');
+        expect(byField.ID).toBe('t2_abcdef');
+        expect(byField['Post Karma']).toBe('1234');
+        expect(byField['Comment Karma']).toBe('5678');
+        expect(byField['Total Karma']).toBe('6912');
+        expect(byField['Account Created']).toBe('2020-01-01');
+        expect(byField.Gold).toBe('Yes');
+        expect(byField.Mod).toBe('No');
+        expect(byField['Verified Email']).toBe('Yes');
+        expect(byField['Has Mail']).toBe('No');
+        expect(byField['Inbox Count']).toBe('0');
+
+        // Row shape must match the declared columns exactly so the
+        // silent-column-drop audit can't be triggered.
+        for (const row of rows) {
+            expect(Object.keys(row).sort()).toEqual(['field', 'value']);
+        }
+    });
+
+    it('falls back to null for missing numeric karma fields rather than 0 sentinels', async () => {
+        const identity = {
+            name: 'bob',
+            id: 'xyz',
+            created_utc: null,
+            is_gold: false,
+            is_mod: false,
+            has_verified_email: false,
+            has_mail: false,
+        };
+        const page = makePage({ kind: 'ok', identity });
+        const rows = await command.func(page, {});
+        const byField = Object.fromEntries(rows.map((r) => [r.field, r.value]));
+        expect(byField['Post Karma']).toBeNull();
+        expect(byField['Comment Karma']).toBeNull();
+        expect(byField['Total Karma']).toBeNull();
+        expect(byField['Account Created']).toBeNull();
+        expect(byField['Inbox Count']).toBeNull();
+    });
+
+    it('does not throw on `data.name` present even if optional booleans are missing', async () => {
+        const identity = { name: 'carol', id: 'i1' };
+        const page = makePage({ kind: 'ok', identity });
+        const rows = await command.func(page, {});
+        expect(rows[0]).toEqual({ field: 'Username', value: 'u/carol' });
+    });
+});

package/clis/rednote/comments.js

@@ -0,0 +1,76 @@
+/**
+ * Rednote comments — international mirror of xiaohongshu/comments.
+ * Reuses the DOM-extraction IIFE from `../xiaohongshu/comments.js`.
+ */
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, AuthRequiredError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import { buildCommentsExtractJs } from '../xiaohongshu/comments.js';
+import { buildNoteUrl, parseNoteId } from '../xiaohongshu/note-helpers.js';
+
+const REDNOTE_SIGNED_URL_HINT = 'Pass a full rednote.com note URL with xsec_token from search results or user/profile context.';
+
+function parseCommentLimit(raw) {
+    const parsed = Number(raw ?? 20);
+    if (!Number.isFinite(parsed) || !Number.isInteger(parsed)) {
+        throw new ArgumentError(`--limit must be an integer between 1 and 50, got ${JSON.stringify(raw)}`);
+    }
+    if (parsed < 1 || parsed > 50) {
+        throw new ArgumentError(`--limit must be between 1 and 50, got ${parsed}`);
+    }
+    return parsed;
+}
+
+cli({
+    site: 'rednote',
+    name: 'comments',
+    access: 'read',
+    description: 'Read comments from a rednote note (supports nested replies)',
+    domain: 'www.rednote.com',
+    strategy: Strategy.COOKIE,
+    navigateBefore: false,
+    args: [
+        { name: 'note-id', required: true, positional: true, help: 'Full rednote note URL with xsec_token' },
+        { name: 'limit', type: 'int', default: 20, help: 'Number of top-level comments (max 50)' },
+        { name: 'with-replies', type: 'boolean', default: false, help: 'Include nested replies (楼中楼)' },
+    ],
+    columns: ['rank', 'author', 'text', 'likes', 'time', 'is_reply', 'reply_to'],
+    func: async (page, kwargs) => {
+        const limit = parseCommentLimit(kwargs.limit);
+        const withReplies = Boolean(kwargs['with-replies']);
+        const raw = String(kwargs['note-id']);
+        const noteId = parseNoteId(raw);
+        await page.goto(buildNoteUrl(raw, {
+            commandName: 'rednote comments',
+            cookieRoot: 'rednote.com',
+            signedUrlHint: REDNOTE_SIGNED_URL_HINT,
+        }));
+        await page.wait({ time: 2 + Math.random() * 3 });
+        const data = await page.evaluate(buildCommentsExtractJs(withReplies));
+        if (!data || typeof data !== 'object') {
+            throw new EmptyResultError('rednote/comments', 'Unexpected evaluate response');
+        }
+        if (data.securityBlock) {
+            throw new CommandExecutionError('Rednote security block: the note detail page was blocked by risk control.', /^https?:\/\//.test(raw)
+                ? 'The page may be temporarily restricted. Try again later or from a different session.'
+                : 'Try using a full URL from search results (with xsec_token) instead of a bare note ID.');
+        }
+        if (data.loginWall) {
+            throw new AuthRequiredError('www.rednote.com', 'Note comments require login');
+        }
+        void noteId;
+        const all = data.results ?? [];
+        if (withReplies) {
+            const limited = [];
+            let topCount = 0;
+            for (const c of all) {
+                if (!c.is_reply)
+                    topCount++;
+                if (topCount > limit)
+                    break;
+                limited.push(c);
+            }
+            return limited.map((c, i) => ({ rank: i + 1, ...c }));
+        }
+        return all.slice(0, limit).map((c, i) => ({ rank: i + 1, ...c }));
+    },
+});

package/clis/rednote/download.js

@@ -0,0 +1,59 @@
+/**
+ * Rednote download — international mirror of xiaohongshu/download.
+ * Reuses the DOM-extraction IIFE from `../xiaohongshu/download.js`; that
+ * IIFE's CDN allowlist already accepts rednote-hosted media URLs.
+ */
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { formatCookieHeader } from '@jackwener/opencli/download';
+import { downloadMedia } from '@jackwener/opencli/download/media-download';
+import { CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import { buildDownloadExtractJs } from '../xiaohongshu/download.js';
+import { buildNoteUrl, parseNoteId } from '../xiaohongshu/note-helpers.js';
+
+const REDNOTE_SIGNED_URL_HINT = 'Pass a full rednote.com note URL with xsec_token from search results or user/profile context.';
+
+cli({
+    site: 'rednote',
+    name: 'download',
+    access: 'read',
+    description: 'Download images and videos from a rednote note',
+    domain: 'www.rednote.com',
+    strategy: Strategy.COOKIE,
+    navigateBefore: false,
+    args: [
+        { name: 'note-id', positional: true, required: true, help: 'Full rednote note URL with xsec_token' },
+        { name: 'output', default: './rednote-downloads', help: 'Output directory' },
+    ],
+    columns: ['index', 'type', 'status', 'size'],
+    func: async (page, kwargs) => {
+        const rawInput = String(kwargs['note-id']);
+        const output = kwargs.output;
+        const noteId = parseNoteId(rawInput);
+        await page.goto(buildNoteUrl(rawInput, {
+            commandName: 'rednote download',
+            cookieRoot: 'rednote.com',
+            signedUrlHint: REDNOTE_SIGNED_URL_HINT,
+        }));
+        await page.wait({ time: 1 + Math.random() * 2 });
+        const data = await page.evaluate(buildDownloadExtractJs(noteId));
+        if (data?.securityBlock) {
+            throw new CommandExecutionError('Rednote security block: the note detail page was blocked by risk control.', /^https?:\/\//.test(rawInput)
+                ? 'The page may be temporarily restricted. Try again later or from a different session.'
+                : 'Try using a full URL from search results (with xsec_token) instead of a bare note ID.');
+        }
+        if (!data || !data.media || data.media.length === 0) {
+            throw new EmptyResultError('rednote/download', 'No downloadable media found on this rednote note.');
+        }
+        const cookies = formatCookieHeader(await page.getCookies({ url: 'https://www.rednote.com' }));
+        const resolvedNoteId = typeof data.noteId === 'string' && data.noteId.trim()
+            ? data.noteId.trim()
+            : noteId;
+        return downloadMedia(data.media, {
+            output,
+            subdir: resolvedNoteId,
+            cookies,
+            filenamePrefix: resolvedNoteId,
+            timeout: 60000,
+        });
+    },
+});