@jackwener/opencli 1.5.5 → 1.5.7

package/dist/clis/spotify/spotify.js

@@ -0,0 +1,316 @@
+import { cli, Strategy } from '../../registry.js';
+import { CliError } from '../../errors.js';
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { createServer } from 'http';
+import { homedir } from 'os';
+import { join } from 'path';
+import { exec } from 'child_process';
+import { assertSpotifyCredentialsConfigured, getFirstSpotifyTrack, mapSpotifyTrackResults, parseDotEnv, resolveSpotifyCredentials, } from './utils.js';
+// ── Credentials ───────────────────────────────────────────────────────────────
+// Set SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET as environment variables,
+// or place them in ~/.opencli/spotify.env:
+//   SPOTIFY_CLIENT_ID=your_id
+//   SPOTIFY_CLIENT_SECRET=your_secret
+const ENV_FILE = join(homedir(), '.opencli', 'spotify.env');
+function loadEnv() {
+    if (!existsSync(ENV_FILE))
+        return {};
+    return parseDotEnv(readFileSync(ENV_FILE, 'utf-8'));
+}
+const env = loadEnv();
+const credentials = resolveSpotifyCredentials(env);
+const CLIENT_ID = credentials.clientId;
+const CLIENT_SECRET = credentials.clientSecret;
+const REDIRECT_URI = 'http://127.0.0.1:8888/callback';
+const SCOPES = [
+    'user-read-playback-state',
+    'user-modify-playback-state',
+    'user-read-currently-playing',
+    'playlist-read-private',
+].join(' ');
+// ── Token storage ─────────────────────────────────────────────────────────────
+const TOKEN_FILE = join(homedir(), '.opencli', 'spotify-tokens.json');
+function loadTokens() {
+    try {
+        return JSON.parse(readFileSync(TOKEN_FILE, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+function saveTokens(tokens) {
+    mkdirSync(join(homedir(), '.opencli'), { recursive: true });
+    writeFileSync(TOKEN_FILE, JSON.stringify(tokens, null, 2));
+}
+async function refreshAccessToken(refreshToken) {
+    const res = await fetch('https://accounts.spotify.com/api/token', {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/x-www-form-urlencoded',
+            Authorization: 'Basic ' + Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString('base64'),
+        },
+        body: new URLSearchParams({ grant_type: 'refresh_token', refresh_token: refreshToken }),
+    });
+    if (!res.ok) {
+        const err = await res.json().catch(() => ({}));
+        throw new CliError('REFRESH_FAILED', err?.error_description || `Token refresh failed (${res.status})`);
+    }
+    const data = await res.json();
+    const tokens = {
+        access_token: data.access_token,
+        refresh_token: data.refresh_token || refreshToken,
+        expires_at: Date.now() + data.expires_in * 1000,
+    };
+    saveTokens(tokens);
+    return tokens.access_token;
+}
+async function getToken() {
+    const tokens = loadTokens();
+    if (!tokens)
+        throw new CliError('AUTH_REQUIRED', 'Not authenticated. Run: opencli spotify auth');
+    if (!tokens.access_token || !tokens.refresh_token || !(tokens.expires_at > 0)) {
+        throw new CliError('AUTH_CORRUPTED', 'Token file is corrupted. Run: opencli spotify auth');
+    }
+    if (Date.now() > tokens.expires_at - 60_000)
+        return refreshAccessToken(tokens.refresh_token);
+    return tokens.access_token;
+}
+// ── Spotify API helper ────────────────────────────────────────────────────────
+async function api(method, path, body) {
+    const token = await getToken();
+    const res = await fetch(`https://api.spotify.com/v1${path}`, {
+        method,
+        headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    if (res.status === 204 || res.status === 202)
+        return null;
+    if (!res.ok) {
+        const err = await res.json().catch(() => ({}));
+        throw new CliError('API_ERROR', err?.error?.message || `Spotify API error ${res.status}`);
+    }
+    return res.json();
+}
+async function findTrackUri(query) {
+    const data = await api('GET', `/search?q=${encodeURIComponent(query)}&type=track&limit=1`);
+    const track = getFirstSpotifyTrack(data);
+    if (!track)
+        throw new CliError('EMPTY_RESULT', `No track found for: ${query}`);
+    return track;
+}
+function openBrowser(url) {
+    const cmd = process.platform === 'win32' ? `start "" "${url}"` : process.platform === 'darwin' ? `open "${url}"` : `xdg-open "${url}"`;
+    exec(cmd);
+}
+// ── Commands ──────────────────────────────────────────────────────────────────
+cli({
+    site: 'spotify',
+    name: 'auth',
+    description: 'Authenticate with Spotify (OAuth — run once)',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [],
+    columns: ['status'],
+    func: async () => {
+        assertSpotifyCredentialsConfigured(credentials, ENV_FILE);
+        return new Promise((resolve, reject) => {
+            const server = createServer(async (req, res) => {
+                try {
+                    const url = new URL(req.url, 'http://localhost:8888');
+                    if (url.pathname !== '/callback') {
+                        res.end();
+                        return;
+                    }
+                    const code = url.searchParams.get('code');
+                    if (!code) {
+                        res.end('Missing code');
+                        return;
+                    }
+                    const tokenRes = await fetch('https://accounts.spotify.com/api/token', {
+                        method: 'POST',
+                        headers: {
+                            'Content-Type': 'application/x-www-form-urlencoded',
+                            Authorization: 'Basic ' + Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString('base64'),
+                        },
+                        body: new URLSearchParams({ grant_type: 'authorization_code', code, redirect_uri: REDIRECT_URI }),
+                    });
+                    if (!tokenRes.ok) {
+                        const err = await tokenRes.json().catch(() => ({}));
+                        server.close();
+                        reject(new CliError('AUTH_FAILED', err?.error_description || `Token exchange failed (${tokenRes.status})`));
+                        return;
+                    }
+                    const data = await tokenRes.json();
+                    saveTokens({ access_token: data.access_token, refresh_token: data.refresh_token, expires_at: Date.now() + data.expires_in * 1000 });
+                    res.writeHead(200, { 'Content-Type': 'text/html' });
+                    res.end('<h2>Spotify authenticated! You can close this tab.</h2>');
+                    server.close();
+                    resolve([{ status: 'Authenticated successfully' }]);
+                }
+                catch (e) {
+                    server.close();
+                    reject(e);
+                }
+            });
+            server.on('error', (e) => {
+                if (e.code === 'EADDRINUSE')
+                    reject(new CliError('PORT_IN_USE', 'Port 8888 is already in use. Stop the other process and retry.'));
+                else
+                    reject(e);
+            });
+            const timeout = setTimeout(() => { server.close(); reject(new CliError('AUTH_TIMEOUT', 'Authentication timed out after 5 minutes')); }, 5 * 60 * 1000);
+            server.listen(8888, () => {
+                const authUrl = `https://accounts.spotify.com/authorize?${new URLSearchParams({ client_id: CLIENT_ID, response_type: 'code', redirect_uri: REDIRECT_URI, scope: SCOPES })}`;
+                console.log('Opening browser for Spotify login...');
+                console.log('If it does not open, visit:', authUrl);
+                openBrowser(authUrl);
+            });
+            server.on('close', () => clearTimeout(timeout));
+        });
+    },
+});
+cli({
+    site: 'spotify',
+    name: 'status',
+    description: 'Show current playback status',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [],
+    columns: ['track', 'artist', 'album', 'status', 'progress'],
+    func: async () => {
+        const data = await api('GET', '/me/player');
+        if (!data || !data.item)
+            return [{ track: 'Nothing playing', artist: '', album: '', status: '', progress: '' }];
+        const t = data.item;
+        if (t.type !== 'track')
+            return [{ track: t.name, artist: '', album: t.show?.name ?? '', status: data.is_playing ? 'playing' : 'paused', progress: '' }];
+        const prog = (data.progress_ms ?? 0) / 1000 | 0;
+        const dur = t.duration_ms / 1000 | 0;
+        const fmt = (s) => `${s / 60 | 0}:${String(s % 60).padStart(2, '0')}`;
+        return [{ track: t.name, artist: t.artists.map((a) => a.name).join(', '), album: t.album.name, status: data.is_playing ? 'playing' : 'paused', progress: `${fmt(prog)} / ${fmt(dur)}` }];
+    },
+});
+cli({
+    site: 'spotify',
+    name: 'play',
+    description: 'Resume playback or search and play a track/artist',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [{ name: 'query', type: 'str', default: '', positional: true, help: 'Track or artist to play (optional)' }],
+    columns: ['track', 'artist', 'status'],
+    func: async (_page, kwargs) => {
+        if (kwargs.query) {
+            const { uri, name, artist } = await findTrackUri(kwargs.query);
+            await api('PUT', '/me/player/play', { uris: [uri] });
+            return [{ track: name, artist, status: 'playing' }];
+        }
+        await api('PUT', '/me/player/play');
+        return [{ track: '', artist: '', status: 'resumed' }];
+    },
+});
+cli({
+    site: 'spotify',
+    name: 'pause',
+    description: 'Pause playback',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [],
+    columns: ['status'],
+    func: async () => { await api('PUT', '/me/player/pause'); return [{ status: 'paused' }]; },
+});
+cli({
+    site: 'spotify',
+    name: 'next',
+    description: 'Skip to next track',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [],
+    columns: ['status'],
+    func: async () => { await api('POST', '/me/player/next'); return [{ status: 'skipped to next' }]; },
+});
+cli({
+    site: 'spotify',
+    name: 'prev',
+    description: 'Skip to previous track',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [],
+    columns: ['status'],
+    func: async () => { await api('POST', '/me/player/previous'); return [{ status: 'skipped to previous' }]; },
+});
+cli({
+    site: 'spotify',
+    name: 'volume',
+    description: 'Set playback volume (0-100)',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [{ name: 'level', type: 'int', default: 50, positional: true, required: true, help: 'Volume 0–100' }],
+    columns: ['volume'],
+    func: async (_page, kwargs) => {
+        const level = Math.round(kwargs.level);
+        if (level < 0 || level > 100)
+            throw new CliError('INVALID_ARGS', 'Volume must be between 0 and 100');
+        await api('PUT', `/me/player/volume?volume_percent=${level}`);
+        return [{ volume: `${level}%` }];
+    },
+});
+cli({
+    site: 'spotify',
+    name: 'search',
+    description: 'Search for tracks',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'query', type: 'str', required: true, positional: true, help: 'Search query' },
+        { name: 'limit', type: 'int', default: 10, help: 'Number of results (default: 10)' },
+    ],
+    columns: ['track', 'artist', 'album', 'uri'],
+    func: async (_page, kwargs) => {
+        const limit = Math.min(50, Math.max(1, Math.round(kwargs.limit)));
+        const data = await api('GET', `/search?q=${encodeURIComponent(kwargs.query)}&type=track&limit=${limit}`);
+        const results = mapSpotifyTrackResults(data);
+        if (!results.length)
+            throw new CliError('EMPTY_RESULT', `No results found for: ${kwargs.query}`);
+        return results;
+    },
+});
+cli({
+    site: 'spotify',
+    name: 'queue',
+    description: 'Add a track to the playback queue',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [{ name: 'query', type: 'str', required: true, positional: true, help: 'Track to add to queue' }],
+    columns: ['track', 'artist', 'status'],
+    func: async (_page, kwargs) => {
+        const { uri, name, artist } = await findTrackUri(kwargs.query);
+        await api('POST', `/me/player/queue?uri=${encodeURIComponent(uri)}`);
+        return [{ track: name, artist, status: 'added to queue' }];
+    },
+});
+cli({
+    site: 'spotify',
+    name: 'shuffle',
+    description: 'Toggle shuffle on/off',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [{ name: 'state', type: 'str', default: 'on', positional: true, choices: ['on', 'off'], help: 'on or off' }],
+    columns: ['shuffle'],
+    func: async (_page, kwargs) => {
+        await api('PUT', `/me/player/shuffle?state=${kwargs.state === 'on'}`);
+        return [{ shuffle: kwargs.state }];
+    },
+});
+cli({
+    site: 'spotify',
+    name: 'repeat',
+    description: 'Set repeat mode (off / track / context)',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [{ name: 'mode', type: 'str', default: 'context', positional: true, choices: ['off', 'track', 'context'], help: 'off / track / context' }],
+    columns: ['repeat'],
+    func: async (_page, kwargs) => {
+        await api('PUT', `/me/player/repeat?state=${kwargs.mode}`);
+        return [{ repeat: kwargs.mode }];
+    },
+});

package/dist/clis/spotify/utils.d.ts

@@ -0,0 +1,21 @@
+export interface SpotifyCredentials {
+    clientId: string;
+    clientSecret: string;
+}
+export interface SpotifyTrackSummary {
+    track: string;
+    artist: string;
+    album: string;
+    uri: string;
+}
+export declare function parseDotEnv(content: string): Record<string, string>;
+export declare function resolveSpotifyCredentials(fileEnv: Record<string, string>, processEnv?: NodeJS.ProcessEnv): SpotifyCredentials;
+export declare function isPlaceholderCredential(value: string | null | undefined): boolean;
+export declare function hasConfiguredSpotifyCredentials(credentials: SpotifyCredentials): boolean;
+export declare function assertSpotifyCredentialsConfigured(credentials: SpotifyCredentials, envFile: string): void;
+export declare function mapSpotifyTrackResults(data: any): SpotifyTrackSummary[];
+export declare function getFirstSpotifyTrack(data: any): {
+    uri: string;
+    name: string;
+    artist: string;
+} | null;

package/dist/clis/spotify/utils.js

@@ -0,0 +1,66 @@
+import { CliError } from '../../errors.js';
+const SPOTIFY_PLACEHOLDER_PATTERNS = [
+    /^your_spotify_client_id_here$/i,
+    /^your_spotify_client_secret_here$/i,
+    /^your_.+_here$/i,
+];
+export function parseDotEnv(content) {
+    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()];
+    }));
+}
+export function resolveSpotifyCredentials(fileEnv, processEnv = process.env) {
+    return {
+        clientId: processEnv.SPOTIFY_CLIENT_ID || fileEnv.SPOTIFY_CLIENT_ID || '',
+        clientSecret: processEnv.SPOTIFY_CLIENT_SECRET || fileEnv.SPOTIFY_CLIENT_SECRET || '',
+    };
+}
+export function isPlaceholderCredential(value) {
+    const normalized = value?.trim() || '';
+    if (!normalized)
+        return false;
+    return SPOTIFY_PLACEHOLDER_PATTERNS.some(pattern => pattern.test(normalized));
+}
+export function hasConfiguredSpotifyCredentials(credentials) {
+    return Boolean(credentials.clientId.trim()) &&
+        Boolean(credentials.clientSecret.trim()) &&
+        !isPlaceholderCredential(credentials.clientId) &&
+        !isPlaceholderCredential(credentials.clientSecret);
+}
+export function assertSpotifyCredentialsConfigured(credentials, envFile) {
+    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) {
+    const items = data?.tracks?.items;
+    if (!Array.isArray(items))
+        return [];
+    return items.map((track) => ({
+        track: track?.name || '',
+        artist: Array.isArray(track?.artists) ? track.artists.map((artist) => artist.name).join(', ') : '',
+        album: track?.album?.name || '',
+        uri: track?.uri || '',
+    }));
+}
+export function getFirstSpotifyTrack(data) {
+    const track = mapSpotifyTrackResults(data)[0];
+    if (!track)
+        return null;
+    return {
+        uri: track.uri,
+        name: track.track,
+        artist: track.artist,
+    };
+}

package/dist/clis/spotify/utils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/clis/spotify/utils.test.js

@@ -0,0 +1,67 @@
+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/dist/clis/substack/utils.d.ts

@@ -2,3 +2,7 @@ import type { IPage } from '../../types.js';
 export declare function buildSubstackBrowseUrl(category?: string): string;
 export declare function loadSubstackFeed(page: IPage, url: string, limit: number): Promise<any[]>;
 export declare function loadSubstackArchive(page: IPage, baseUrl: string, limit: number): Promise<any[]>;
+export declare const __test__: {
+    FEED_POST_LINK_SELECTOR: string;
+    ARCHIVE_POST_LINK_SELECTOR: string;
+};

package/dist/clis/substack/utils.js

@@ -1,4 +1,6 @@
 import { CommandExecutionError } from '../../errors.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) {
     if (!category || category === 'all')
         return 'https://substack.com/';
@@ -9,7 +11,7 @@ export async function loadSubstackFeed(page, url, limit) {
     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));
@@ -77,7 +79,7 @@ export async function loadSubstackArchive(page, baseUrl, limit) {
     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));
@@ -128,3 +130,7 @@ export async function loadSubstackArchive(page, baseUrl, limit) {
   `);
     return Array.isArray(data) ? data : [];
 }
+export const __test__ = {
+    FEED_POST_LINK_SELECTOR,
+    ARCHIVE_POST_LINK_SELECTOR,
+};

package/dist/clis/substack/utils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/clis/substack/utils.test.js

@@ -0,0 +1,46 @@
+import { describe, expect, it, vi } from 'vitest';
+import { __test__, loadSubstackArchive, loadSubstackFeed } from './utils.js';
+function createPageMock(evaluateResult) {
+    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/dist/clis/tieba/commands.test.d.ts

@@ -0,0 +1,4 @@
+import './hot.js';
+import './posts.js';
+import './read.js';
+import './search.js';

package/dist/clis/tieba/commands.test.js

@@ -0,0 +1,79 @@
+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, {
+            id: '10163164720',
+            page: 2,
+            limit: 5,
+        })).rejects.toMatchObject({
+            code: 'EMPTY_RESULT',
+            hint: expect.stringMatching(/requested page/i),
+        });
+    });
+});

package/dist/clis/tieba/hot.d.ts

@@ -0,0 +1 @@
+export {};