@jackwener/opencli 1.7.6 → 1.7.7

package/clis/weread/ai-outline.test.js

@@ -0,0 +1,83 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import './ai-outline.js';
+
+describe('weread ai-outline', () => {
+    const command = getRegistry().get('weread/ai-outline');
+
+    beforeEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    it('registers ai-outline with plain default output', () => {
+        expect(command?.defaultFormat).toBe('plain');
+    });
+
+    it('maps chapterInfos auth-expired responses to AUTH_REQUIRED', async () => {
+        expect(command?.func).toBeTypeOf('function');
+        const page = {
+            getCookies: vi.fn()
+                .mockResolvedValueOnce([{ name: 'wr_vid', value: 'vid123', domain: '.weread.qq.com' }])
+                .mockResolvedValueOnce([{ name: 'wr_name', value: 'alice', domain: '.weread.qq.com' }]),
+        };
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
+            ok: true,
+            status: 200,
+            json: () => Promise.resolve({ errcode: -2012, errmsg: '登录超时' }),
+        }));
+        await expect(command.func(page, { 'book-id': 'book-1' })).rejects.toMatchObject({
+            code: 'AUTH_REQUIRED',
+            message: 'Not logged in to WeRead',
+        });
+    });
+
+    it('returns structured rows for --raw and respects depth filtering', async () => {
+        expect(command?.func).toBeTypeOf('function');
+        const page = {
+            getCookies: vi.fn()
+                .mockResolvedValueOnce([{ name: 'wr_vid', value: 'vid123', domain: '.weread.qq.com' }])
+                .mockResolvedValueOnce([{ name: 'wr_name', value: 'alice', domain: '.weread.qq.com' }]),
+        };
+        const fetchMock = vi.fn()
+            .mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            json: () => Promise.resolve({
+                data: [{
+                        updated: [
+                            { chapterUid: 'c1', title: '第一章' },
+                        ],
+                    }],
+            }),
+        })
+            .mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            json: () => Promise.resolve({
+                itemsArray: [{
+                        chapterUid: 'c1',
+                        items: [
+                            { level: 2, uiIdx: '1', text: '主题一' },
+                            { level: 3, uiIdx: '1.1', text: '要点一' },
+                            { level: 4, text: '细节一' },
+                        ],
+                    }],
+            }),
+        });
+        vi.stubGlobal('fetch', fetchMock);
+        const rows = await command.func(page, { 'book-id': 'book-1', raw: true, depth: 3, limit: 10 });
+        expect(rows).toEqual([
+            { chapter: '第一章', idx: '1', level: 2, text: '主题一' },
+            { chapter: '第一章', idx: '1.1', level: 3, text: '要点一' },
+        ]);
+        expect(fetchMock).toHaveBeenNthCalledWith(1, 'https://weread.qq.com/web/book/chapterInfos', expect.objectContaining({
+            method: 'POST',
+            headers: expect.objectContaining({
+                Cookie: 'wr_name=alice; wr_vid=vid123',
+            }),
+        }));
+        expect(fetchMock).toHaveBeenNthCalledWith(2, 'https://weread.qq.com/web/book/outline', expect.objectContaining({
+            method: 'POST',
+        }));
+    });
+});

package/clis/weread/book.js

@@ -37,6 +37,61 @@ function countSearchIdentities(entries) {
     }
     return counts;
 }
+export function strictTitleFromWereadDocumentTitle(rawTitle) {
+    const suffix = ' - 微信读书';
+    const normalized = String(rawTitle || '').trim();
+    if (!normalized.endsWith(suffix))
+        return '';
+    const base = normalized.slice(0, -suffix.length).trim();
+    // Only accept the title when WeRead exposes the strict "<title> - 微信读书"
+    // shape. If extra separators remain, the page title is ambiguous.
+    return base.includes(' - ') ? '' : base;
+}
+export function extractReaderFallbackMetadata(doc) {
+    const text = (node) => node?.textContent?.trim() || '';
+    const firstText = (...sels) => { for (const s of sels) {
+        const v = text(doc.querySelector(s));
+        if (v)
+            return v;
+    } return ''; };
+    const bodyText = doc.body?.innerText?.replace(/\s+/g, ' ').trim() || '';
+    const extractRating = () => {
+        const match = bodyText.match(/微信读书推荐值\s*([0-9.]+%)/);
+        return match ? match[1] : '';
+    };
+    const extractPublisher = () => {
+        const direct = text(doc.querySelector('.introDialog_content_pub_line'));
+        return direct.startsWith('出版社') ? direct.replace(/^出版社\s*/, '').trim() : '';
+    };
+    const extractIntro = () => {
+        const selectors = [
+            '.horizontalReaderCoverPage_content_bookInfo_intro',
+            '.wr_flyleaf_page_bookIntro_content',
+            '.introDialog_content_intro_para',
+        ];
+        for (const selector of selectors) {
+            const value = text(doc.querySelector(selector));
+            if (value)
+                return value;
+        }
+        return '';
+    };
+    const categorySource = Array.from(doc.scripts || [])
+        .map((script) => script.textContent || '')
+        .find((scriptText) => scriptText.includes('"category"')) || '';
+    const categoryMatch = categorySource.match(/"category"\s*:\s*"([^"]+)"/);
+    const title = firstText('.horizontalReaderCoverPage_content_bookTitle', '.wr_flyleaf_page_bookInfo_bookTitle', '.outline_book_detail_header_title', '.readerTopBar_title_link') || strictTitleFromWereadDocumentTitle(doc.title || '');
+    const author = firstText('.horizontalReaderCoverPage_content_author', '.wr_flyleaf_page_bookInfo_author', '.outline_book_detail_header_author');
+    return {
+        title,
+        author,
+        publisher: extractPublisher(),
+        intro: extractIntro(),
+        category: categoryMatch ? categoryMatch[1].trim() : '',
+        rating: extractRating(),
+        metadataReady: Boolean(title || author),
+    };
+}
 /**
  * Reuse the public search page as a last-resort reader URL source when the
  * cached shelf page cannot provide a trustworthy bookId-to-reader mapping.
@@ -108,51 +163,9 @@ async function resolveSearchReaderUrl(title, author) {
  */
 async function loadReaderFallbackResult(page, readerUrl) {
     await page.goto(readerUrl);
-    await page.wait({ selector: '.horizontalReaderCoverPage_content_bookTitle, .wr_flyleaf_page_bookInfo_bookTitle', timeout: 10 });
+    await page.wait({ selector: '.horizontalReaderCoverPage_content_bookTitle, .wr_flyleaf_page_bookInfo_bookTitle, .readerTopBar_title_link', timeout: 10 });
     const result = await page.evaluate(`
-    (() => {
-      const text = (node) => node?.textContent?.trim() || '';
-      const bodyText = document.body?.innerText?.replace(/\\s+/g, ' ').trim() || '';
-      const titleSelector = '.horizontalReaderCoverPage_content_bookTitle, .wr_flyleaf_page_bookInfo_bookTitle';
-      const authorSelector = '.horizontalReaderCoverPage_content_author, .wr_flyleaf_page_bookInfo_author';
-      const extractRating = () => {
-        const match = bodyText.match(/微信读书推荐值\\s*([0-9.]+%)/);
-        return match ? match[1] : '';
-      };
-      const extractPublisher = () => {
-        const direct = text(document.querySelector('.introDialog_content_pub_line'));
-        return direct.startsWith('出版社') ? direct.replace(/^出版社\\s*/, '').trim() : '';
-      };
-      const extractIntro = () => {
-        const selectors = [
-          '.horizontalReaderCoverPage_content_bookInfo_intro',
-          '.wr_flyleaf_page_bookIntro_content',
-          '.introDialog_content_intro_para',
-        ];
-        for (const selector of selectors) {
-          const value = text(document.querySelector(selector));
-          if (value) return value;
-        }
-        return '';
-      };
-
-      const categorySource = Array.from(document.scripts)
-        .map((script) => script.textContent || '')
-        .find((scriptText) => scriptText.includes('"category"')) || '';
-      const categoryMatch = categorySource.match(/"category"\\s*:\\s*"([^"]+)"/);
-      const title = text(document.querySelector(titleSelector));
-      const author = text(document.querySelector(authorSelector));
-
-      return {
-        title,
-        author,
-        publisher: extractPublisher(),
-        intro: extractIntro(),
-        category: categoryMatch ? categoryMatch[1].trim() : '',
-        rating: extractRating(),
-        metadataReady: Boolean(title || author),
-      };
-    })()
+    (${extractReaderFallbackMetadata.toString()})(document)
   `);
     return {
         title: String(result?.title || '').trim(),

package/clis/weread/commands.test.js

@@ -14,6 +14,7 @@ import { getRegistry } from '@jackwener/opencli/registry';
 import './book.js';
 import './highlights.js';
 import './notes.js';
+import { extractReaderFallbackMetadata, strictTitleFromWereadDocumentTitle } from './book.js';
 describe('weread book-id positional args', () => {
     const book = getRegistry().get('weread/book');
     const highlights = getRegistry().get('weread/highlights');
@@ -356,6 +357,29 @@ describe('weread book-id positional args', () => {
             message: 'Not logged in to WeRead',
         });
     });
+    it('does not guess author from document.title when the reader page skips cover metadata', async () => {
+        const nodes = new Map([
+            ['.readerTopBar_title_link', { textContent: 'Part 1 - Part 2' }],
+            ['.introDialog_content_pub_line', { textContent: '出版社 测试出版社' }],
+            ['.introDialog_content_intro_para', { textContent: '测试简介。' }],
+        ]);
+        const mockDocument = {
+            title: 'Part 1 - Part 2 - 作者甲 - 微信读书',
+            body: { innerText: '微信读书推荐值 88.8%' },
+            scripts: [],
+            querySelector: (selector) => nodes.get(selector) || null,
+        };
+        expect(strictTitleFromWereadDocumentTitle(mockDocument.title)).toBe('');
+        expect(extractReaderFallbackMetadata(mockDocument)).toEqual({
+            title: 'Part 1 - Part 2',
+            author: '',
+            publisher: '测试出版社',
+            intro: '测试简介。',
+            category: '',
+            rating: '88.8%',
+            metadataReady: true,
+        });
+    });
     it('passes the positional book-id to highlights', async () => {
         mockFetchPrivateApi.mockResolvedValue({ updated: [] });
         await highlights.func({}, { 'book-id': 'abc', limit: 5 });

package/clis/xiaoyuzhou/podcast-episodes.js

@@ -20,9 +20,9 @@ cli({
             throw new CliError('INVALID_ARGUMENT', 'limit must be a positive integer', 'Example: --limit 5');
         }
         const credentials = loadXiaoyuzhouCredentials();
-        const response = await requestXiaoyuzhouJson('/v1/podcast/listEpisode', {
+        const response = await requestXiaoyuzhouJson('/v1/episode/list', {
             method: 'POST',
-            body: { pid: args.id, limit: requestedLimit },
+            body: { pid: args.id, order: 'desc', limit: requestedLimit },
             credentials,
         });
         const episodes = response.data ?? [];

package/clis/xiaoyuzhou/podcast-episodes.test.js

@@ -0,0 +1,78 @@
+import { beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+
+const { mockRequestJson, mockLoadCredentials } = vi.hoisted(() => ({
+    mockRequestJson: vi.fn(),
+    mockLoadCredentials: vi.fn(),
+}));
+
+vi.mock('./auth.js', async () => {
+    const actual = await vi.importActual('./auth.js');
+    return {
+        ...actual,
+        requestXiaoyuzhouJson: mockRequestJson,
+        loadXiaoyuzhouCredentials: mockLoadCredentials,
+    };
+});
+
+await import('./podcast-episodes.js');
+
+let cmd;
+
+beforeAll(() => {
+    cmd = getRegistry().get('xiaoyuzhou/podcast-episodes');
+    expect(cmd?.func).toBeTypeOf('function');
+});
+
+describe('xiaoyuzhou podcast-episodes', () => {
+    beforeEach(() => {
+        mockRequestJson.mockReset();
+        mockLoadCredentials.mockReset();
+        mockLoadCredentials.mockReturnValue({ access_token: 'access', refresh_token: 'refresh' });
+    });
+
+    it('calls the fixed episode list endpoint with desc ordering', async () => {
+        mockRequestJson.mockResolvedValue({
+            data: [
+                {
+                    eid: 'ep-1',
+                    title: 'Episode 1',
+                    duration: 3661,
+                    playCount: 42,
+                    pubDate: '2026-04-20T10:00:00.000Z',
+                },
+            ],
+        });
+
+        const result = await cmd.func(null, {
+            id: 'podcast-1',
+            limit: 3,
+        });
+
+        expect(mockRequestJson).toHaveBeenCalledWith('/v1/episode/list', {
+            method: 'POST',
+            body: { pid: 'podcast-1', order: 'desc', limit: 3 },
+            credentials: { access_token: 'access', refresh_token: 'refresh' },
+        });
+        expect(result).toEqual([
+            {
+                eid: 'ep-1',
+                title: 'Episode 1',
+                duration: '61:01',
+                plays: 42,
+                date: '2026-04-20',
+            },
+        ]);
+    });
+
+    it('rejects non-positive limits before hitting the API', async () => {
+        await expect(cmd.func(null, {
+            id: 'podcast-1',
+            limit: 0,
+        })).rejects.toMatchObject({
+            code: 'INVALID_ARGUMENT',
+            message: 'limit must be a positive integer',
+        });
+        expect(mockRequestJson).not.toHaveBeenCalled();
+    });
+});

package/dist/src/browser/analyze.d.ts

@@ -0,0 +1,103 @@
+/**
+ * `browser analyze <url>` — turn site-recon guesswork into deterministic CLI output.
+ *
+ * When an agent starts a new adapter, the first question is "which pattern am
+ * I looking at?" (A/B/C/D/E from site-recon docs) and "will Node-side fetch
+ * work, or will anti-bot middleware block me?". Today the agent has to open
+ * the page, poke `network`, try cURL, fail, guess again. This module condenses
+ * that into one call that returns a classification + evidence.
+ *
+ * Kept pure (no page imports) so the bulk is unit-testable; the CLI wrapper
+ * drives a real page, feeds the resulting signals here, and prints the verdict.
+ */
+import type { CliCommand } from '../registry.js';
+export interface PageSignals {
+    /** URL we navigated to (may redirect; both fields help agents notice that). */
+    requestedUrl: string;
+    finalUrl: string;
+    /** document.cookie split into names; value not needed for detection. */
+    cookieNames: string[];
+    /**
+     * Response bodies captured during the navigation + first few seconds.
+     * We only need enough body text to spot WAF markers; the CLI truncates
+     * per-entry before feeding us.
+     */
+    networkEntries: Array<{
+        url: string;
+        status: number;
+        contentType: string;
+        /** First N chars of body; null when not available. */
+        bodyPreview: string | null;
+    }>;
+    /**
+     * Which globals the page exposes on `window`. We don't care about the values,
+     * just presence — distinguishes Pattern B (SSR state) from Pattern A.
+     */
+    initialState: {
+        __INITIAL_STATE__: boolean;
+        __NUXT__: boolean;
+        __NEXT_DATA__: boolean;
+        __APOLLO_STATE__: boolean;
+    };
+    /** Document title — only for the human-debug `summary` field. */
+    title: string;
+}
+export type AntiBotVendor = 'aliyun_waf' | 'cloudflare' | 'akamai' | 'geetest' | 'unknown';
+export interface AntiBotVerdict {
+    detected: boolean;
+    vendor: AntiBotVendor | null;
+    evidence: string[];
+    /** One-line imperative instruction for the agent. */
+    implication: string;
+}
+export declare function detectAntiBot(signals: PageSignals): AntiBotVerdict;
+export type Pattern = 'A' | 'B' | 'C' | 'D' | 'E' | 'unknown';
+export interface PatternVerdict {
+    pattern: Pattern;
+    reason: string;
+    /** How many JSON XHR/fetch responses we saw during navigation. */
+    json_responses: number;
+    /** Count of non-2xx API responses — hint for token-gated (Pattern D). */
+    auth_failures: number;
+}
+/**
+ * Apply the decision tree from `site-recon.md` mechanically.
+ *
+ * B beats A when initial-state globals are present: even if the page fetches
+ * more data via XHR afterwards, the SSR payload is the highest-leverage source.
+ * D (token-gated) dominates when we see 401/403 on what looks like API
+ * endpoints — without that, an authenticated route looks identical to A.
+ */
+export declare function classifyPattern(signals: PageSignals): PatternVerdict;
+export interface NearestAdapter {
+    site: string;
+    example_commands: string[];
+    reason: string;
+}
+/**
+ * Find existing adapters that target the same site.
+ *
+ * Keep the hostname match simple — agents extend naming conventions
+ * differently per site, so we match on the registered `domain` field and fall
+ * back to site-name containment. Returning `null` is fine; agents can always
+ * read site-memory docs.
+ */
+export declare function findNearestAdapter(finalUrl: string, registry: Map<string, CliCommand>): NearestAdapter | null;
+export interface AnalyzeReport {
+    requested_url: string;
+    final_url: string;
+    title: string;
+    pattern: PatternVerdict;
+    anti_bot: AntiBotVerdict;
+    initial_state: PageSignals['initialState'];
+    nearest_adapter: NearestAdapter | null;
+    recommended_next_step: string;
+}
+/**
+ * Synthesize the verdict from collected signals + registry.
+ *
+ * The `recommended_next_step` is deliberately a single imperative
+ * sentence — agents act on it directly instead of re-deriving advice from
+ * the structured fields.
+ */
+export declare function analyzeSite(signals: PageSignals, registry: Map<string, CliCommand>): AnalyzeReport;

package/dist/src/browser/analyze.js

@@ -0,0 +1,230 @@
+/**
+ * `browser analyze <url>` — turn site-recon guesswork into deterministic CLI output.
+ *
+ * When an agent starts a new adapter, the first question is "which pattern am
+ * I looking at?" (A/B/C/D/E from site-recon docs) and "will Node-side fetch
+ * work, or will anti-bot middleware block me?". Today the agent has to open
+ * the page, poke `network`, try cURL, fail, guess again. This module condenses
+ * that into one call that returns a classification + evidence.
+ *
+ * Kept pure (no page imports) so the bulk is unit-testable; the CLI wrapper
+ * drives a real page, feeds the resulting signals here, and prints the verdict.
+ */
+/**
+ * WAF vendors we can reliably detect from cookies + response body markers
+ * alone. Signals are orthogonal per vendor — so when two vendors match
+ * simultaneously (rare), we keep all evidence and report the higher-signal
+ * vendor first.
+ */
+const WAF_SIGNATURES = [
+    {
+        vendor: 'aliyun_waf',
+        cookiePatterns: [/^acw_sc__v2$/, /^acw_tc$/, /^ssxmod_itna/],
+        bodyPatterns: [/arg1\s*=\s*['"][0-9A-F]{30,}/, /\/ntc_captcha\//i],
+        implication: 'Direct Node-side fetch/curl will return the slider HTML. Validate the endpoint in browser context first; HTML COOKIE adapters still finish with Node-side fetch + page.getCookies.',
+    },
+    {
+        vendor: 'cloudflare',
+        cookiePatterns: [/^__cf_bm$/, /^cf_clearance$/, /^__cfduid$/],
+        bodyPatterns: [/Cloudflare Ray ID/i, /Checking your browser before accessing/i, /cf-chl-/i],
+        implication: 'Cloudflare bot check. Start from a real browser session; probe in browser context first. HTML COOKIE adapters still finish with Node-side fetch + page.getCookies.',
+    },
+    {
+        vendor: 'akamai',
+        cookiePatterns: [/^_abck$/, /^bm_sz$/, /^bm_sv$/],
+        bodyPatterns: [/akamai/i],
+        implication: 'Akamai Bot Manager. Probe in browser context first; keep final HTML COOKIE adapters on Node-side fetch + page.getCookies.',
+    },
+    {
+        vendor: 'geetest',
+        cookiePatterns: [],
+        bodyPatterns: [/geetest/i, /gt_captcha/i],
+        implication: 'Geetest slider/puzzle captcha. Agent cannot bypass programmatically — requires UI strategy or human-in-loop.',
+    },
+];
+export function detectAntiBot(signals) {
+    const evidence = [];
+    let match = null;
+    for (const sig of WAF_SIGNATURES) {
+        const hits = [];
+        for (const pat of sig.cookiePatterns) {
+            const hit = signals.cookieNames.find((c) => pat.test(c));
+            if (hit)
+                hits.push(`cookie:${hit}`);
+        }
+        for (const pat of sig.bodyPatterns) {
+            for (const entry of signals.networkEntries) {
+                if (entry.bodyPreview && pat.test(entry.bodyPreview)) {
+                    hits.push(`body:${entry.url}`);
+                    break;
+                }
+            }
+        }
+        if (hits.length > 0 && !match) {
+            match = sig;
+            evidence.push(...hits);
+        }
+    }
+    if (!match) {
+        return {
+            detected: false,
+            vendor: null,
+            evidence: [],
+            implication: 'No known anti-bot signatures. Try Node-side COOKIE fetch first; if endpoint validation is blocked, retry from browser context.',
+        };
+    }
+    return {
+        detected: true,
+        vendor: match.vendor,
+        evidence,
+        implication: match.implication,
+    };
+}
+/**
+ * Apply the decision tree from `site-recon.md` mechanically.
+ *
+ * B beats A when initial-state globals are present: even if the page fetches
+ * more data via XHR afterwards, the SSR payload is the highest-leverage source.
+ * D (token-gated) dominates when we see 401/403 on what looks like API
+ * endpoints — without that, an authenticated route looks identical to A.
+ */
+export function classifyPattern(signals) {
+    const jsonEntries = signals.networkEntries.filter((e) => /json/i.test(e.contentType));
+    const authFailures = signals.networkEntries.filter((e) => e.status === 401 || e.status === 403).length;
+    const hasInitialState = signals.initialState.__INITIAL_STATE__ ||
+        signals.initialState.__NUXT__ ||
+        signals.initialState.__NEXT_DATA__ ||
+        signals.initialState.__APOLLO_STATE__;
+    if (authFailures >= 2 && jsonEntries.length >= 1) {
+        return {
+            pattern: 'D',
+            reason: `${authFailures} auth-failing API responses seen — endpoint is token-gated`,
+            json_responses: jsonEntries.length,
+            auth_failures: authFailures,
+        };
+    }
+    if (hasInitialState) {
+        const which = Object.entries(signals.initialState)
+            .filter(([, v]) => v)
+            .map(([k]) => k);
+        return {
+            pattern: 'B',
+            reason: `SSR state global present: ${which.join(', ')}`,
+            json_responses: jsonEntries.length,
+            auth_failures: authFailures,
+        };
+    }
+    if (jsonEntries.length >= 1) {
+        return {
+            pattern: 'A',
+            reason: `${jsonEntries.length} JSON XHR/fetch responses observed — classic API pattern`,
+            json_responses: jsonEntries.length,
+            auth_failures: authFailures,
+        };
+    }
+    // No API, no SSR state — probably static HTML or a bundled SPA that lazy-loads.
+    // Pattern C (HTML scrape) is the default fallback; E (streaming) we can't
+    // reliably detect without watching WebSocket frames, so we label 'C' and
+    // leave the agent to upgrade to E manually if they see WS traffic.
+    return {
+        pattern: 'C',
+        reason: 'No JSON XHR and no SSR state — HTML scrape (Pattern C); escalate to E manually if WebSocket traffic appears',
+        json_responses: jsonEntries.length,
+        auth_failures: authFailures,
+    };
+}
+/**
+ * Find existing adapters that target the same site.
+ *
+ * Keep the hostname match simple — agents extend naming conventions
+ * differently per site, so we match on the registered `domain` field and fall
+ * back to site-name containment. Returning `null` is fine; agents can always
+ * read site-memory docs.
+ */
+export function findNearestAdapter(finalUrl, registry) {
+    let host;
+    try {
+        host = new URL(finalUrl).hostname;
+    }
+    catch {
+        return null;
+    }
+    // Strip leading www.; 'www' as a site identifier is never what an adapter uses.
+    const cleanedHost = host.replace(/^www\./, '');
+    // Extract apex (xx.com) and registrable parts for fuzzy match.
+    const parts = cleanedHost.split('.');
+    const apex = parts.slice(-2).join('.');
+    const siteKey = parts.length > 1 ? parts[parts.length - 2] : cleanedHost;
+    const hits = new Map();
+    for (const cmd of registry.values()) {
+        const domain = cmd.domain?.toLowerCase();
+        const siteMatches = (domain && (cleanedHost.endsWith(domain) || domain.endsWith(apex))) ||
+            cmd.site.toLowerCase() === siteKey?.toLowerCase() ||
+            cleanedHost.includes(cmd.site.toLowerCase());
+        if (siteMatches) {
+            const list = hits.get(cmd.site) ?? [];
+            list.push(cmd);
+            hits.set(cmd.site, list);
+        }
+    }
+    if (hits.size === 0)
+        return null;
+    // Pick the site with the most commands — likely the most-developed adapter,
+    // and the best reference for a new command on the same host.
+    let best = null;
+    for (const entry of hits) {
+        if (!best || entry[1].length > best[1].length)
+            best = entry;
+    }
+    if (!best)
+        return null;
+    return {
+        site: best[0],
+        example_commands: best[1].slice(0, 5).map((c) => `${c.site} ${c.name}`),
+        reason: `${best[1].length} existing adapter${best[1].length === 1 ? '' : 's'} target this site — reuse strategy/cookie config`,
+    };
+}
+/**
+ * Synthesize the verdict from collected signals + registry.
+ *
+ * The `recommended_next_step` is deliberately a single imperative
+ * sentence — agents act on it directly instead of re-deriving advice from
+ * the structured fields.
+ */
+export function analyzeSite(signals, registry) {
+    const pattern = classifyPattern(signals);
+    const antiBot = detectAntiBot(signals);
+    const nearest = findNearestAdapter(signals.finalUrl, registry);
+    let next;
+    if (antiBot.detected) {
+        next = antiBot.implication;
+    }
+    else if (pattern.pattern === 'A') {
+        next = 'Pick the most specific JSON endpoint from `opencli browser network` and try a bare Node fetch with cookies; escalate to browser-context fetch only if blocked.';
+    }
+    else if (pattern.pattern === 'B') {
+        next = 'Read the SSR global via `opencli browser eval "JSON.stringify(window.__INITIAL_STATE__ ?? window.__NUXT__ ?? window.__NEXT_DATA__ ?? window.__APOLLO_STATE__)"` — no API needed.';
+    }
+    else if (pattern.pattern === 'C') {
+        next = 'No API visible — use SSR HTML scrape (e.g. `opencli browser extract`) against the rendered page.';
+    }
+    else if (pattern.pattern === 'D') {
+        next = 'Endpoints need auth. Re-open the page from a signed-in session, then retry analyze; see `field-decode-playbook` §4 for token tracing.';
+    }
+    else if (pattern.pattern === 'E') {
+        next = 'WebSocket stream detected — find the underlying HTTP poll/long-poll endpoint; raw WS is not supported.';
+    }
+    else {
+        next = 'No strong signal. Manually inspect `opencli browser network --all` and pick a pattern.';
+    }
+    return {
+        requested_url: signals.requestedUrl,
+        final_url: signals.finalUrl,
+        title: signals.title,
+        pattern,
+        anti_bot: antiBot,
+        initial_state: signals.initialState,
+        nearest_adapter: nearest,
+        recommended_next_step: next,
+    };
+}

package/dist/src/browser/analyze.test.d.ts

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