@sovovs/bycli 1.8.0

package/clis/goproxy/utils.js

@@ -0,0 +1,165 @@
+// Shared helpers for the Go module proxy adapters.
+//
+// proxy.golang.org is the canonical Go module proxy. It is unauthenticated
+// and serves the GOPROXY protocol (`@latest`, `@v/list`, `@v/<ver>.info|mod|zip`).
+// Spec: https://go.dev/ref/mod#goproxy-protocol
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@sovovs/bycli/errors';
+
+export const GOPROXY_BASE = 'https://proxy.golang.org';
+const UA = 'bycli-goproxy-adapter (+https://github.com/sovovs/byCLI)';
+
+// Module paths look like host/path/...; conservative shape: at least one slash,
+// host segment is alnum + dots, path segments are alnum + dashes/dots/underscores/slashes.
+// We enforce at most 200 chars and reject characters that would need URL-escaping.
+const MODULE_PATH = /^[A-Za-z0-9][A-Za-z0-9._\/-]{0,199}$/;
+
+// Go semver tags include "v" prefix; we accept the GOPROXY canonical form.
+const VERSION_TAG = /^v[0-9]+(\.[0-9]+)*([-+][A-Za-z0-9._-]+)?$/;
+
+export function requireModulePath(value) {
+    const s = String(value ?? '').trim();
+    if (!s) {
+        throw new ArgumentError(
+            'goproxy module path is required (e.g. "github.com/gin-gonic/gin", "golang.org/x/net")',
+            'Use the canonical module path that appears in `go.mod`.',
+        );
+    }
+    if (!MODULE_PATH.test(s) || !s.includes('/')) {
+        throw new ArgumentError(
+            `goproxy module path "${value}" is not a recognised Go module path`,
+            'Module paths look like "github.com/<org>/<repo>" or "golang.org/x/<name>".',
+        );
+    }
+    return s;
+}
+
+export function requireVersionTag(value) {
+    const s = String(value ?? '').trim();
+    if (!s) throw new ArgumentError('goproxy --version cannot be empty');
+    if (!VERSION_TAG.test(s)) {
+        throw new ArgumentError(
+            `goproxy --version "${value}" is not a valid Go semver tag`,
+            'Use the GOPROXY canonical form like "v1.2.3" or "v0.0.0-20240101010101-abcdef012345".',
+        );
+    }
+    return s;
+}
+
+export function requireBoundedInt(value, defaultValue, maxValue, label = 'limit') {
+    const raw = value ?? defaultValue;
+    const n = typeof raw === 'number' ? raw : Number(raw);
+    if (!Number.isInteger(n) || n <= 0) {
+        throw new ArgumentError(`goproxy ${label} must be a positive integer`);
+    }
+    if (n > maxValue) {
+        throw new ArgumentError(`goproxy ${label} must be <= ${maxValue}`);
+    }
+    return n;
+}
+
+async function rawFetch(url, label) {
+    let resp;
+    try {
+        resp = await fetch(url, { headers: { 'user-agent': UA } });
+    }
+    catch (err) {
+        throw new CommandExecutionError(
+            `${label} request failed: ${err?.message ?? err}`,
+            'Check that proxy.golang.org is reachable from this network.',
+        );
+    }
+    if (resp.status === 404 || resp.status === 410) {
+        throw new EmptyResultError(label, `proxy.golang.org returned ${resp.status} for ${url}.`);
+    }
+    if (resp.status === 429) {
+        throw new CommandExecutionError(`${label} returned HTTP 429 (rate limited)`);
+    }
+    if (!resp.ok) {
+        throw new CommandExecutionError(`${label} returned HTTP ${resp.status}`);
+    }
+    return resp;
+}
+
+export async function goproxyJson(url, label) {
+    const resp = await rawFetch(url, label);
+    let body;
+    try {
+        body = await resp.json();
+    }
+    catch (err) {
+        throw new CommandExecutionError(`${label} returned malformed JSON: ${err?.message ?? err}`);
+    }
+    return body;
+}
+
+export async function goproxyText(url, label) {
+    const resp = await rawFetch(url, label);
+    return resp.text();
+}
+
+// Sort version tags by their numeric components, newest first. Pre-release tags
+// (anything after "-" that isn't a pure number) sort lower than the matching
+// release. Returns a new sorted array; non-tag inputs are dropped.
+export function sortVersionsDescending(versions) {
+    return versions
+        .filter((v) => typeof v === 'string' && VERSION_TAG.test(v))
+        .map((v) => ({ v, parts: parseSemver(v) }))
+        .sort((a, b) => compareParts(b.parts, a.parts))
+        .map((entry) => entry.v);
+}
+
+function parseSemver(tag) {
+    // Strip leading "v"; split into <numbers>(-<pre>)?(+<build>)?
+    const stripped = tag.replace(/^v/, '');
+    const plusIdx = stripped.indexOf('+');
+    const noBuild = plusIdx >= 0 ? stripped.slice(0, plusIdx) : stripped;
+    const dashIdx = noBuild.indexOf('-');
+    const head = dashIdx >= 0 ? noBuild.slice(0, dashIdx) : noBuild;
+    const pre = dashIdx >= 0 ? noBuild.slice(dashIdx + 1) : '';
+    const numbers = head.split('.').map((s) => Number.parseInt(s, 10)).map((n) => Number.isFinite(n) ? n : 0);
+    return { numbers, pre };
+}
+
+function compareParts(a, b) {
+    const len = Math.max(a.numbers.length, b.numbers.length);
+    for (let i = 0; i < len; i += 1) {
+        const ai = a.numbers[i] ?? 0;
+        const bi = b.numbers[i] ?? 0;
+        if (ai !== bi) return ai - bi;
+    }
+    // No pre-release sorts higher than has pre-release.
+    if (a.pre === '' && b.pre !== '') return 1;
+    if (a.pre !== '' && b.pre === '') return -1;
+    if (a.pre === b.pre) return 0;
+    return comparePrerelease(a.pre, b.pre);
+}
+
+function comparePrerelease(a, b) {
+    const aParts = a.split('.');
+    const bParts = b.split('.');
+    const len = Math.max(aParts.length, bParts.length);
+    for (let i = 0; i < len; i += 1) {
+        const ai = aParts[i];
+        const bi = bParts[i];
+        if (ai == null) return -1;
+        if (bi == null) return 1;
+        const aNum = /^\d+$/.test(ai);
+        const bNum = /^\d+$/.test(bi);
+        if (aNum && bNum) {
+            const diff = Number(ai) - Number(bi);
+            if (diff !== 0) return diff;
+            continue;
+        }
+        if (aNum !== bNum) return aNum ? -1 : 1;
+        if (ai !== bi) return ai < bi ? -1 : 1;
+    }
+    return 0;
+}
+
+// Normalise GOPROXY ISO-Z timestamps to second precision (no fractional ms).
+export function trimDate(value) {
+    const s = String(value ?? '').trim();
+    if (!s) return null;
+    const noFrac = s.replace(/\.\d+/, '');
+    return noFrac.endsWith('Z') ? noFrac : (s.length >= 10 ? s.slice(0, 10) : null);
+}

package/clis/goproxy/versions.js

@@ -0,0 +1,59 @@
+// goproxy versions — published version tags for one Go module, newest first.
+//
+// Hits `https://proxy.golang.org/<module>/@v/list` (plain text, one tag per line).
+// Sort by semver (descending) and return up to `--limit` rows; per-tag publish
+// time comes from `@v/<ver>.info` and is fetched only when `--with-time` is set,
+// since it costs one HTTP request per row.
+import { cli, Strategy } from '@sovovs/bycli/registry';
+import { EmptyResultError } from '@sovovs/bycli/errors';
+import {
+    GOPROXY_BASE, goproxyJson, goproxyText, requireBoundedInt, requireModulePath, sortVersionsDescending, trimDate,
+} from './utils.js';
+
+cli({
+    site: 'goproxy',
+    name: 'versions',
+    access: 'read',
+    description: 'Published version tags for a Go module (newest first), optionally with publish times',
+    domain: 'proxy.golang.org',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'module', positional: true, type: 'string', required: true, help: 'Go module path (e.g. "github.com/gin-gonic/gin")' },
+        { name: 'limit', type: 'int', default: 30, help: 'Max rows to return (1-200)' },
+        { name: 'with-time', type: 'boolean', default: false, help: 'Fetch each version\'s publish time (one extra request per row)' },
+    ],
+    columns: [
+        'rank', 'module', 'version', 'publishedAt', 'url',
+    ],
+    func: async (args) => {
+        const modulePath = requireModulePath(args.module);
+        const limit = requireBoundedInt(args.limit, 30, 200, 'limit');
+        const withTime = args['with-time'] === true;
+        const encoded = modulePath.split('/').map(encodeURIComponent).join('/');
+        const text = await goproxyText(`${GOPROXY_BASE}/${encoded}/@v/list`, `goproxy versions ${modulePath}`);
+        const raw = text.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+        if (raw.length === 0) {
+            throw new EmptyResultError('goproxy versions', `proxy.golang.org returned no published versions for "${modulePath}".`);
+        }
+        const sorted = sortVersionsDescending(raw).slice(0, limit);
+        if (sorted.length === 0) {
+            throw new EmptyResultError('goproxy versions', `"${modulePath}" has no semver-shaped tags on proxy.golang.org.`);
+        }
+        const rows = sorted.map((v, i) => ({
+            rank: i + 1,
+            module: modulePath,
+            version: v,
+            publishedAt: null,
+            url: `${GOPROXY_BASE}/${encoded}/@v/${encodeURIComponent(v)}.info`,
+        }));
+        if (withTime) {
+            // Sequential to keep the proxy happy; cap at limit which is already <=200.
+            for (const row of rows) {
+                const info = await goproxyJson(`${GOPROXY_BASE}/${encoded}/@v/${encodeURIComponent(row.version)}.info`, `goproxy versions ${modulePath} ${row.version}`);
+                row.publishedAt = trimDate(info?.Time);
+            }
+        }
+        return rows;
+    },
+});

package/clis/gov-law/commands.test.js

@@ -0,0 +1,39 @@
+import { describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@sovovs/bycli/registry';
+import './search.js';
+import './recent.js';
+
+describe('gov-law commands', () => {
+    const search = getRegistry().get('gov-law/search');
+    const recent = getRegistry().get('gov-law/recent');
+
+    it('registers both commands as public browser commands', () => {
+        expect(search).toBeDefined();
+        expect(recent).toBeDefined();
+        expect(search.strategy).toBe('public');
+        expect(recent.strategy).toBe('public');
+        expect(search.browser).toBe(true);
+        expect(recent.browser).toBe(true);
+    });
+
+    it('rejects empty search queries before browser navigation', async () => {
+        const page = { goto: vi.fn() };
+        await expect(search.func(page, { query: '   ' })).rejects.toMatchObject({
+            name: 'ArgumentError',
+            code: 'ARGUMENT',
+        });
+        expect(page.goto).not.toHaveBeenCalled();
+    });
+
+    it('throws a descriptive error when Vue Router is unavailable', async () => {
+        const page = {
+            goto: vi.fn(),
+            wait: vi.fn(),
+            evaluate: vi.fn().mockResolvedValue(false),
+        };
+        await expect(recent.func(page, { limit: 3 })).rejects.toMatchObject({
+            name: 'CliError',
+            code: 'FRAMEWORK_CHANGED',
+        });
+    });
+});

package/clis/gov-law/recent.js

@@ -0,0 +1,22 @@
+import { cli, Strategy } from '@sovovs/bycli/registry';
+import { clampInt } from '../_shared/common.js';
+import { extractLawResults, navigateViaVueRouter } from './shared.js';
+
+cli({
+    site: 'gov-law',
+    name: 'recent',
+    access: 'read',
+    description: '最新法律法规',
+    domain: 'flk.npc.gov.cn',
+    strategy: Strategy.PUBLIC,
+    browser: true,
+    args: [
+        { name: 'limit', type: 'int', default: 10, help: '返回结果数量 (max 20)' },
+    ],
+    columns: ['rank', 'title', 'status', 'publish_date', 'type', 'department'],
+    func: async (page, kwargs) => {
+        const limit = clampInt(kwargs.limit, 10, 1, 20);
+        await navigateViaVueRouter(page, {});
+        return extractLawResults(page, limit);
+    },
+});

package/clis/gov-law/search.js

@@ -0,0 +1,41 @@
+import { cli, Strategy } from '@sovovs/bycli/registry';
+import { clampInt, requireNonEmptyQuery } from '../_shared/common.js';
+import { extractLawResults, navigateViaVueRouter } from './shared.js';
+
+cli({
+    site: 'gov-law',
+    name: 'search',
+    access: 'read',
+    description: '国家法律法规数据库搜索',
+    domain: 'flk.npc.gov.cn',
+    strategy: Strategy.PUBLIC,
+    browser: true,
+    args: [
+        { name: 'query', positional: true, required: true, help: '搜索关键词' },
+        { name: 'limit', type: 'int', default: 10, help: '返回结果数量 (max 20)' },
+    ],
+    columns: ['rank', 'title', 'status', 'publish_date', 'type', 'department'],
+    func: async (page, kwargs) => {
+        const limit = clampInt(kwargs.limit, 10, 1, 20);
+        const query = requireNonEmptyQuery(kwargs.query);
+        await navigateViaVueRouter(page, { searchWord: query });
+
+        const encodedQuery = JSON.stringify(query);
+        await page.evaluate(`
+      (async () => {
+        const input = document.querySelector('.el-input__inner');
+        if (input && !input.value) {
+          const setter = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, 'value').set;
+          setter.call(input, ${encodedQuery});
+          input.dispatchEvent(new Event('input', { bubbles: true }));
+          input.dispatchEvent(new Event('change', { bubbles: true }));
+          await new Promise(r => setTimeout(r, 300));
+          input.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', keyCode: 13, bubbles: true }));
+          input.dispatchEvent(new KeyboardEvent('keyup', { key: 'Enter', keyCode: 13, bubbles: true }));
+        }
+      })()
+    `);
+        await page.wait(3);
+        return extractLawResults(page, limit);
+    },
+});

package/clis/gov-law/shared.js

@@ -0,0 +1,51 @@
+import { CliError } from '@sovovs/bycli/errors';
+
+export async function navigateViaVueRouter(page, query) {
+    await page.goto('https://flk.npc.gov.cn/index.html');
+    await page.wait(4);
+
+    const routerAvailable = await page.evaluate(`
+      (async () => {
+        const app = document.querySelector('#app');
+        const router = app?.__vue_app__?.config?.globalProperties?.$router;
+        if (!router) return false;
+        await router.push({ path: '/search', query: ${JSON.stringify(query)} });
+        return true;
+      })()
+    `);
+
+    if (!routerAvailable) {
+        throw new CliError(
+            'FRAMEWORK_CHANGED',
+            'Could not access Vue Router on flk.npc.gov.cn — the site may have been restructured.',
+            'Please report this issue so the adapter can be updated.',
+        );
+    }
+
+    await page.wait(5);
+}
+
+export async function extractLawResults(page, limit) {
+    const data = await page.evaluate(`
+      (async () => {
+        const normalize = v => (v || '').replace(/\\s+/g, ' ').trim();
+        for (let i = 0; i < 40; i++) {
+          if (document.querySelectorAll('.result-item').length > 0) break;
+          await new Promise(r => setTimeout(r, 500));
+        }
+        const results = [];
+        for (const el of document.querySelectorAll('.result-item')) {
+          const title = normalize(el.querySelector('.title-content')?.textContent);
+          if (!title) continue;
+          const status = normalize(el.querySelector('[class*="status"]')?.textContent);
+          const publish_date = normalize(el.querySelector('.publish-time')?.textContent).replace(/^公布日期[：:]\\s*/, '');
+          const type = normalize(el.querySelector('.type')?.textContent);
+          const department = normalize(el.querySelector('.department')?.textContent);
+          results.push({ rank: results.length + 1, title, status, publish_date, type, department });
+          if (results.length >= ${limit}) break;
+        }
+        return results;
+      })()
+    `);
+    return Array.isArray(data) ? data : [];
+}

package/clis/gov-policy/__fixtures__/recent.html

@@ -0,0 +1,16 @@
+<!DOCTYPE html>
+<html lang="zh">
+<head>
+<meta charset="UTF-8">
+<title>国务院最新政策文件</title>
+</head>
+<body>
+<div class="news_box">
+<div class="list list_1 list_2">
+<ul id="list-1-ajax-id">
+<li><h4><a href="https://www.gov.cn/zhengce/202604/content_7066998.htm" target="_blank">中共中央办公厅 国务院办公厅关于加强新就业群体服务管理的意见</a><span class="date">2026-04-26</span></h4></li><li><h4><a href="https://www.gov.cn/zhengce/202604/content_7066695.htm" target="_blank">中共中央办公厅 国务院办公厅印发《碳达峰碳中和综合评价考核办法》</a><span class="date">2026-04-23</span></h4></li><li><h4><a href="https://www.gov.cn/zhengce/202604/content_7066623.htm" target="_blank">中办国办关于更高水平更高质量做好节能降碳工作的意见</a><span class="date">2026-04-22</span></h4></li><li><h4><a href="https://www.gov.cn/zhengce/content/202604/content_7066483.htm" target="_blank">国务院关于推进服务业扩能提质的意见</a><span class="date">2026-04-21</span></h4></li><li><h4 class="line"><a href="https://www.gov.cn/zhengce/content/202604/content_7066113.htm" target="_blank">国务院办公厅转发海关总署《关于促进综合保税区扩能提质的若干措施》的通知</a><span class="date">2026-04-17</span></h4></li>
+</ul>
+</div>
+</div>
+</body>
+</html>

package/clis/gov-policy/__fixtures__/search.html

@@ -0,0 +1,41 @@
+<!DOCTYPE html>
+<html lang="zh">
+<head>
+<meta charset="UTF-8">
+<title>中国政府网站内搜索 - 数字经济</title>
+</head>
+<body>
+<div class="basic_result_content js_basic_result_content clearfix">
+<div class="item hasImg is-news" data-documentid="thirdparty_code_107_t_17e00f1efbb_25992758">
+            <div class="partitions"></div>
+            <a class="title log-anchor" title="经济数据速览：10组数字看一季度中国经济" href="https://www.gov.cn/zhengce/jiedu/tujie/202604/content_7065945.htm" target="_blank">
+                <span class="type_title">要闻</span><em>经济</em>数据速览：10组<em>数字</em>看一季度中国<em>经济</em>
+            </a>
+            <div class="description">
+                <img src="placeholder.png" aria-label="经济数据速览：10组数字看一季度中国经济">
+                <span class="sourceTime">发布时间：2026-4-16</span>
+            </div>
+        </div><div class="item hasImg is-news" data-documentid="thirdparty_code_107_t_17e00f1efbb_25839485">
+            <div class="partitions"></div>
+            <a class="title log-anchor" title="何立峰会见法国经济、财政和工业、能源与数字主权部部长莱斯屈尔" href="https://www.gov.cn/yaowen/liebiao/202603/content_7062985.htm" target="_blank">
+                <span class="type_title">要闻</span>何立峰会见法国<em>经济</em>、财政和工业、能源与<em>数字</em>主权部部长莱斯屈尔
+            </a>
+            <div class="description">
+                <div class="detail js_limit_text">
+                    <p class="js_text line_clamp_two">新华社巴黎3月16日电 当地时间3月16日，中法高级别经济财金对话中方牵头人、国务院副总理何立峰在中美经贸巴黎磋商之后应约会见对话法方牵头人，法国经济、财政和工业、能源与数字主权部部长莱斯屈尔，就近期中法经济财金合作和双方共同关心的问题深入交换意见。 何立峰表示，中方愿与法方一道，落实好习近平主席与马克龙总统重要共识，进一步深化中法经济财金各领域交流与合作，推动中法经济关系行稳致远。何立峰还应询介</p>
+                </div>
+                <span class="sourceTime">发布时间：2026-3-17</span>
+            </div>
+        </div><div class="item hasImg is-news" data-documentid="thirdparty_code_107_t_17e00f1efbb_25836739">
+            <div class="partitions"></div>
+            <a class="title log-anchor" title="经济数据速览：7组数字看1—2月份中国经济" href="https://www.gov.cn/zhengce/jiedu/tujie/202603/content_7062831.htm" target="_blank">
+                <span class="type_title">要闻</span><em>经济</em>数据速览：7组<em>数字</em>看1—2月份中国<em>经济</em>
+            </a>
+            <div class="description">
+                <img src="placeholder.png" aria-label="经济数据速览：7组数字看1—2月份中国经济">
+                <span class="sourceTime">发布时间：2026-3-16</span>
+            </div>
+        </div>
+</div>
+</body>
+</html>

package/clis/gov-policy/gov-policy.test.js

@@ -0,0 +1,224 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { JSDOM } from 'jsdom';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+    ArgumentError,
+    CommandExecutionError,
+    EmptyResultError,
+} from '@sovovs/bycli/errors';
+import { getRegistry } from '@sovovs/bycli/registry';
+import { extractSearchRows } from './search.js';
+import { extractRecentRows } from './recent.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SEARCH_FIXTURE = readFileSync(join(__dirname, '__fixtures__/search.html'), 'utf8');
+const RECENT_FIXTURE = readFileSync(join(__dirname, '__fixtures__/recent.html'), 'utf8');
+
+function createPageMock(evaluateResult, overrides = {}) {
+    const evaluate = typeof evaluateResult === 'function'
+        ? vi.fn(evaluateResult)
+        : vi.fn().mockResolvedValue(evaluateResult);
+    return {
+        goto: vi.fn().mockResolvedValue(undefined),
+        wait: vi.fn().mockResolvedValue(undefined),
+        evaluate,
+        ...overrides,
+    };
+}
+
+describe('gov-policy commands — registration', () => {
+    it('registers search and recent as public browser commands', () => {
+        const search = getRegistry().get('gov-policy/search');
+        const recent = getRegistry().get('gov-policy/recent');
+
+        expect(search).toBeDefined();
+        expect(recent).toBeDefined();
+        expect(search.browser).toBe(true);
+        expect(recent.browser).toBe(true);
+        expect(search.strategy).toBe('public');
+        expect(recent.strategy).toBe('public');
+        expect(search.columns).toEqual(['rank', 'title', 'description', 'date', 'url']);
+        expect(recent.columns).toEqual(['rank', 'title', 'date', 'source', 'url']);
+    });
+
+    it('rejects empty search queries before browser navigation', async () => {
+        const search = getRegistry().get('gov-policy/search');
+        const page = { goto: vi.fn() };
+        await expect(search.func(page, { query: '   ' })).rejects.toThrow(ArgumentError);
+        expect(page.goto).not.toHaveBeenCalled();
+    });
+
+    it('rejects invalid limits before browser navigation', async () => {
+        const search = getRegistry().get('gov-policy/search');
+        const recent = getRegistry().get('gov-policy/recent');
+        const page = createPageMock({ ok: true, rows: [] });
+
+        await expect(search.func(page, { query: '数字经济', limit: '0' })).rejects.toThrow(ArgumentError);
+        await expect(search.func(page, { query: '数字经济', limit: '1.5' })).rejects.toThrow(ArgumentError);
+        await expect(search.func(page, { query: '数字经济', limit: '21' })).rejects.toThrow(ArgumentError);
+        await expect(recent.func(page, { limit: 'abc' })).rejects.toThrow(ArgumentError);
+        expect(page.goto).not.toHaveBeenCalled();
+        expect(page.evaluate).not.toHaveBeenCalled();
+    });
+
+    it('maps empty search pages, selector drift, and browser failures to typed errors', async () => {
+        const search = getRegistry().get('gov-policy/search');
+        const recent = getRegistry().get('gov-policy/recent');
+
+        await expect(search.func(createPageMock({
+            ok: false,
+            sample: '很抱歉，没有找到与 数字经济 相关的结果',
+            url: 'https://sousuo.www.gov.cn/sousuo/search.shtml?searchWord=x',
+        }), { query: '数字经济' })).rejects.toThrow(EmptyResultError);
+
+        await expect(recent.func(createPageMock({
+            ok: false,
+            sample: '<main>unexpected government page shell</main>',
+            url: 'https://www.gov.cn/zhengce/zuixin/index.htm',
+        }), {})).rejects.toThrow(CommandExecutionError);
+
+        await expect(search.func(createPageMock(
+            { ok: true, rows: [] },
+            { goto: vi.fn().mockRejectedValue(new Error('browser disconnected')) },
+        ), { query: '数字经济' })).rejects.toThrow(CommandExecutionError);
+    });
+});
+
+/**
+ * In-browser DOM extractors against frozen sanitized HTML fixtures.
+ *
+ * Mocked-page.evaluate tests can't catch silent bugs that live inside the
+ * extractor, since they feed pre-baked results to the func and the real
+ * DOM walk never runs.
+ *
+ * These tests replay the real (sanitized) HTML through JSDOM so changes
+ * to the extractor logic that re-introduce a silent regression fail in CI.
+ */
+describe('gov-policy adapter — extractors against frozen HTML fixtures', () => {
+    let originalDocument;
+    let originalLocation;
+
+    beforeEach(() => {
+        originalDocument = globalThis.document;
+        originalLocation = globalThis.location;
+    });
+
+    afterEach(() => {
+        globalThis.document = originalDocument;
+        globalThis.location = originalLocation;
+    });
+
+    function loadFixture(html, url) {
+        const dom = new JSDOM(html, { url });
+        globalThis.document = dom.window.document;
+        globalThis.location = dom.window.location;
+        return dom;
+    }
+
+    it('extractSearchRows returns three result-shaped rows with title, description, date, url', () => {
+        loadFixture(SEARCH_FIXTURE, 'https://sousuo.www.gov.cn/sousuo/search.shtml?searchWord=%E6%95%B0%E5%AD%97%E7%BB%8F%E6%B5%8E');
+
+        const result = extractSearchRows();
+
+        expect(result.ok).toBe(true);
+        expect(result.rows).toHaveLength(3);
+
+        // Rank 1 + 3 are the homogeneous "type tag + emphasized title" cards
+        // whose .description div carries only the date span (no real snippet).
+        expect(result.rows[0]).toMatchObject({
+            rank: 1,
+            title: '要闻经济数据速览：10组数字看一季度中国经济',
+            date: '2026-4-16',
+            url: 'https://www.gov.cn/zhengce/jiedu/tujie/202604/content_7065945.htm',
+        });
+        // Description for these rows is just the publish-time line.
+        expect(result.rows[0].description).toContain('发布时间');
+        expect(result.rows[0].description).toContain('2026-4-16');
+
+        // Rank 2 has a real article snippet inside .description > .detail > p,
+        // and the extractor must capture it (sliced to 120 chars).
+        expect(result.rows[1]).toMatchObject({
+            rank: 2,
+            title: '要闻何立峰会见法国经济、财政和工业、能源与数字主权部部长莱斯屈尔',
+            date: '2026-3-17',
+            url: 'https://www.gov.cn/yaowen/liebiao/202603/content_7062985.htm',
+        });
+        expect(result.rows[1].description.length).toBeLessThanOrEqual(120);
+        expect(result.rows[1].description).toContain('新华社巴黎');
+
+        expect(result.rows[2]).toMatchObject({
+            rank: 3,
+            title: '要闻经济数据速览：7组数字看1—2月份中国经济',
+            date: '2026-3-16',
+            url: 'https://www.gov.cn/zhengce/jiedu/tujie/202603/content_7062831.htm',
+        });
+
+        // Lock the no-collapse contract on the title: the type_title prefix
+        // ('要闻') is fused into the textContent because we read the whole <a>.
+        // If a future refactor strips the prefix, this assertion catches it
+        // before any field-level downstream surprises.
+        for (const row of result.rows) {
+            expect(row.title.startsWith('要闻')).toBe(true);
+        }
+    });
+
+    it('extractRecentRows returns five rows with title, date, url and empty source', () => {
+        loadFixture(RECENT_FIXTURE, 'https://www.gov.cn/zhengce/zuixin/index.htm');
+
+        const result = extractRecentRows();
+
+        expect(result.ok).toBe(true);
+        expect(result.rows).toHaveLength(5);
+
+        expect(result.rows[0]).toMatchObject({
+            rank: 1,
+            title: '中共中央办公厅 国务院办公厅关于加强新就业群体服务管理的意见',
+            date: '2026-04-26',
+            url: 'https://www.gov.cn/zhengce/202604/content_7066998.htm',
+        });
+        expect(result.rows[1]).toMatchObject({
+            rank: 2,
+            date: '2026-04-23',
+        });
+        expect(result.rows[4]).toMatchObject({
+            rank: 5,
+            date: '2026-04-17',
+        });
+
+        // gov.cn/zhengce/zuixin layout has no .source / .from elements, so
+        // the source field is always an empty string. Lock that contract:
+        // a future selector change that picks up unrelated text would break
+        // it and fail this assertion.
+        for (const row of result.rows) {
+            expect(row.source).toBe('');
+        }
+    });
+
+    it('extractSearchRows signals ok:false with a sample when result list is empty', () => {
+        loadFixture(
+            '<html><head><title>blocked</title></head><body><main>访问受限，请稍后再试</main></body></html>',
+            'https://sousuo.www.gov.cn/sousuo/search.shtml?searchWord=zzz',
+        );
+
+        const result = extractSearchRows();
+
+        expect(result.ok).toBe(false);
+        expect(result.url).toBe('https://sousuo.www.gov.cn/sousuo/search.shtml?searchWord=zzz');
+        expect(result.sample).toContain('访问受限');
+    });
+
+    it('extractRecentRows signals ok:false with a sample when listing is empty', () => {
+        loadFixture(
+            '<html><head><title>not found</title></head><body><main>页面正在加载</main></body></html>',
+            'https://www.gov.cn/zhengce/zuixin/index.htm',
+        );
+
+        const result = extractRecentRows();
+
+        expect(result.ok).toBe(false);
+        expect(result.url).toBe('https://www.gov.cn/zhengce/zuixin/index.htm');
+        expect(result.sample).toContain('页面正在加载');
+    });
+});