dsh-web-search-pro 0.2.0 → 0.2.3

package/lib/cli/chains-spec.js

@@ -0,0 +1,118 @@
+/**
+ * The static facts of the platform backend chains (dev-plan M12), free of Node imports so the settings card validates
+ * `platformBackends` with the same code the server resolves it with: the default chain of each platform, which backend
+ * ids exist and which platforms each can serve.
+ * @module web-search-pro/cli/chains-spec
+ */
+import { BUILTIN_CLI_SPECS } from "./builtin-specs.js";
+import { OPENCLI_SITE_OF } from "./opencli-sites.js";
+import { platformBackendProblems, resolveCliAdapters } from "./spec.js";
+/**
+ * The default chain of each platform: first usable backend answers, empty or failing ones fall through in order. The platforms
+ * that need a login (xiaohongshu, reddit, twitter, zhihu) try the standalone OpenCLI first: it reads the login of the user's
+ * own day-to-day Chrome through the OpenCLI Browser Bridge, so nothing is logged in by the plugin. The standalone CLIs
+ * (xhs, rdt, twitter, zhihu) stay as the optional fallback for users who logged them in themselves.
+ */
+export const DEFAULT_CHAINS = {
+    xiaohongshu: ['opencli', 'xhs', 'browser-opencli'],
+    reddit: ['opencli', 'rdt', 'browser-opencli'],
+    twitter: ['opencli', 'twitter', 'browser-opencli'],
+    zhihu: ['opencli', 'zhihu', 'browser-search'],
+    bilibili: ['bili'],
+    youtube: ['yt-dlp'],
+    github: ['rest', 'gh'],
+    'github-issues': ['rest', 'gh'],
+    'github-code': ['rest', 'gh'],
+    wechat: ['omnireach', 'wx-search-cli'],
+    omnireach: ['omnireach'],
+    tanso: ['tanso'],
+    instagram: ['browser-opencli'],
+    facebook: ['browser-opencli'],
+    weibo: ['browser-search'],
+    douban: ['browser-search'],
+    tieba: ['browser-search'],
+    douyin: ['browser-search'],
+    kuaishou: ['browser-search'],
+};
+/** Platforms whose provider is a chain (everything in the default table). */
+export const CHAIN_PLATFORMS = Object.keys(DEFAULT_CHAINS);
+export { OPENCLI_SITE_OF };
+/** Platforms the dsh-browser OpenCLI bridge has a site adapter for (pinned to engines.ts by a test). */
+export const BROWSER_OPENCLI_PLATFORMS = ['xiaohongshu', 'twitter', 'reddit', 'instagram', 'facebook'];
+/** Platforms with a built-in rendered-search-page spec in dsh-browser's searchResults (pinned to platform-search.ts by a test). */
+export const BROWSER_SEARCH_PLATFORMS = ['zhihu', 'weibo', 'douban', 'tieba', 'douyin', 'kuaishou'];
+/** Platforms the plugin's own REST client serves. */
+export const REST_PLATFORMS = ['github', 'github-issues', 'github-code'];
+/** Backend ids that are not CLI specs. */
+export const FIXED_BACKENDS = ['opencli', 'browser-opencli', 'browser-search', 'rest'];
+/** Whether `id` names a platform backend: a built-in CLI spec, a fixed backend, or a custom CLI (`custom-cli:<id>`). */
+export function isBackendId(id) {
+    return FIXED_BACKENDS.includes(id) || BUILTIN_CLI_SPECS.some(spec => spec.id === id) || id.startsWith('custom-cli:');
+}
+/**
+ * Whether backend `id` can serve `platform`. `specPlatforms` maps a CLI spec id (built-in, or `custom-cli:<id>` of the user)
+ * to the platforms it lists; a user spec serves any platform its chain names.
+ */
+export function backendServes(id, platform, specPlatforms) {
+    if (id === 'opencli')
+        return OPENCLI_SITE_OF[platform] ? { ok: true } : { ok: false, why: 'has no site for platform ' + platform };
+    if (id === 'browser-opencli')
+        return BROWSER_OPENCLI_PLATFORMS.includes(platform) ? { ok: true } : { ok: false, why: 'does not serve platform ' + platform };
+    if (id === 'browser-search')
+        return BROWSER_SEARCH_PLATFORMS.includes(platform) ? { ok: true } : { ok: false, why: 'does not serve platform ' + platform };
+    if (id === 'rest')
+        return REST_PLATFORMS.includes(platform) ? { ok: true } : { ok: false, why: 'does not serve platform ' + platform };
+    const platforms = specPlatforms.get(id);
+    if (!platforms)
+        return { ok: false, why: 'is not a known backend (built-in ids: ' + [...specPlatforms.keys()].filter(k => !k.startsWith('custom-cli:')).join(', ') + ', ' + FIXED_BACKENDS.join(', ') + ')' };
+    // A custom CLI is the platform `custom-cli:<id>` of its own and serves exactly the platforms its spec declares.
+    if (id === platform)
+        return { ok: true };
+    if (!platforms.includes(platform))
+        return { ok: false, why: 'does not serve platform ' + platform + (platforms.length ? ' (it serves ' + platforms.join(', ') + ')' : ' (it declares no platform' + (id.startsWith('custom-cli:') ? ': add ' + platform + ' to its "platforms"' : '') + ')') };
+    return { ok: true };
+}
+/** The CLI specs a chain may name: the built-ins by id and the user's valid `cliAdapters` as `custom-cli:<id>`. */
+export function specPlatformsOf(cliAdapters) {
+    const platforms = new Map(BUILTIN_CLI_SPECS.map(spec => [spec.id, spec.platforms]));
+    const user = resolveCliAdapters(cliAdapters);
+    for (const [id, spec] of user.specs)
+        platforms.set('custom-cli:' + id, spec.platforms);
+    return { platforms, diagnostics: user.diagnostics };
+}
+/** The declared platforms of the user's CLI adapters that no backend chain exists for (the spec would serve nothing there). */
+export function customCliPlatformIssues(cliAdapters) {
+    const { specs } = resolveCliAdapters(cliAdapters);
+    const out = [];
+    for (const [id, spec] of specs) {
+        const unknown = spec.platforms.filter(platform => !CHAIN_PLATFORMS.includes(platform));
+        if (unknown.length)
+            out.push('cliAdapters.' + id + '.platforms: no backend chain exists for ' + unknown.join(', ') + ' (platforms with a chain: ' + CHAIN_PLATFORMS.join(', ') + ')');
+    }
+    return out;
+}
+/**
+ * Every problem of the `platformBackends` setting (shape, unknown platform, unknown or foreign backend id) given the
+ * `cliAdapters` setting. The settings card and `sources.status` both call this.
+ */
+export function platformBackendIssues(platformBackends, cliAdapters) {
+    const shape = platformBackendProblems(platformBackends);
+    if (shape.length || !platformBackends || typeof platformBackends !== 'object')
+        return shape;
+    const { platforms } = specPlatformsOf(cliAdapters);
+    const known = new Set([...CHAIN_PLATFORMS, ...[...platforms.keys()].filter(id => id.startsWith('custom-cli:'))]);
+    const out = [];
+    for (const [platform, ids] of Object.entries(platformBackends)) {
+        if (!known.has(platform)) {
+            out.push('platformBackends.' + platform + ': no such platform with a backend chain (known: ' + [...known].join(', ') + ')');
+            continue;
+        }
+        for (const id of ids) {
+            const served = backendServes(id, platform, platforms);
+            if (!served.ok)
+                out.push('platformBackends.' + platform + ': "' + id + '" ' + served.why);
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=chains-spec.js.map

package/lib/cli/chains-spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chains-spec.js","sourceRoot":"","sources":["../../src/cli/chains-spec.ts"],"names":[],"mappings":"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"}

package/lib/cli/engine.js

@@ -0,0 +1,99 @@
+/**
+ * The Engine of a CLI adapter spec (dev-plan M12): one search leg that probes the command's contract (cached), then runs
+ * the spec through the shared runner. `available()` is synchronous and local (settings gates plus the probe cache);
+ * every failure reaches the caller as a structured error naming what to install or run.
+ * @module web-search-pro/cli/engine
+ */
+import { CliAdapterError, loginHint, missingEnv, runCliSearchDetailed, savedLoginPresent } from "./runner.js";
+import { cachedProbe, probeCli } from "./probe.js";
+import { USER_DEFINED_TAG } from "./spec.js";
+/** Settings that gate a spec on top of `enableCliBackends` (twitter-cli kept its own `agentReachEnabled` switch). */
+const SETTING_GATE = {
+    twitter: { key: 'agentReachEnabled', label: 'the twitter-cli backend is disabled in settings (agentReachEnabled)' },
+};
+/** Why a spec is switched off by settings, or undefined when it may run. */
+export function disabledBySettings(spec, deps) {
+    if (!deps.enableCli)
+        return 'CLI backends are disabled in settings (enableCliBackends)';
+    const gate = SETTING_GATE[spec.id];
+    return gate && !deps[gate.key] ? gate.label : undefined;
+}
+/**
+ * The environment a spec's credential variables are read from: the process environment overlaid with the values the router
+ * resolved (settings literal -> DSH credentials -> process environment). Undefined = the process environment as it is.
+ */
+export function specEnv(deps) {
+    return deps.cliEnv && Object.keys(deps.cliEnv).length ? { ...process.env, ...deps.cliEnv } : undefined;
+}
+/** The probe verdict as the structured error a search would raise, or undefined when the command is usable. */
+export function probeError(spec, probe) {
+    if (probe.state === 'detected')
+        return undefined;
+    if (probe.state === 'missing')
+        return new CliAdapterError('the ' + spec.bins[0] + ' command is not installed: install it (' + spec.packageNote + ')', 'CLI_NOT_FOUND', 'install: ' + spec.packageNote);
+    return new CliAdapterError(spec.bins[0] + ' is installed but does not match this adapter: ' + (probe.reason ?? 'contract mismatch'), 'CLI_CONTRACT_MISMATCH', 'a different program with the same name, or a version the adapter does not know: check `sources.deps`');
+}
+export function cliSpecEngine(spec, platform, deps, options = {}) {
+    return {
+        id: options.id ?? spec.id,
+        backend: options.id ?? spec.id,
+        label: options.label ?? spec.bins[0],
+        available: () => {
+            if (disabledBySettings(spec, deps))
+                return false;
+            // Before the first probe the command is assumed present; the search itself probes and reports.
+            return options.run ? true : (cachedProbe(spec)?.state ?? 'detected') === 'detected';
+        },
+        unavailableReason: () => {
+            const off = disabledBySettings(spec, deps);
+            if (off)
+                return off;
+            const probe = options.run ? undefined : cachedProbe(spec);
+            return probe && probe.state !== 'detected' ? probeError(spec, probe)?.message : undefined;
+        },
+        async search(query, count, signal) {
+            const why = disabledBySettings(spec, deps);
+            if (why)
+                throw new CliAdapterError(why, 'CLI_NOT_FOUND', undefined, false);
+            let bin = spec.bins[0];
+            if (!options.run) {
+                const probe = await probeCli(spec);
+                const failure = probeError(spec, probe);
+                if (failure)
+                    throw failure;
+                bin = probe.path ?? bin;
+            }
+            const runOptions = {
+                platform, bin,
+                ...options.run ? { run: options.run } : {},
+                ...(options.env ?? specEnv(deps)) ? { env: (options.env ?? specEnv(deps)) } : {},
+                ...options.home ? { home: options.home } : {},
+                ...options.skipCredentialGate ? { skipCredentialGate: true } : {},
+            };
+            const { sources, skipped } = await runCliSearchDetailed(spec, { query, count, signal }, runOptions);
+            const rows = options.userDefined ? sources.map(source => ({ ...source, via: options.id ?? spec.id, tag: USER_DEFINED_TAG })) : sources;
+            return { sources: rows, via: options.id ?? spec.id, backend: options.id ?? spec.id, ...skipped ? { notes: [skipped + ' result' + (skipped === 1 ? '' : 's') + ' without a link skipped'] } : {} };
+        },
+    };
+}
+/** Local readiness of one spec: settings, contract probe, then the credentials it needs. Never runs a search. */
+export async function specReadiness(spec, deps, options = {}) {
+    const off = disabledBySettings(spec, deps);
+    if (off)
+        return { ready: false, installation: 'missing', credential: 'not_required', reason: spec.id + ': ' + off, code: 'disabled' };
+    const probe = await probeCli(spec);
+    const base = { installation: probe.state, ...probe.version ? { version: probe.version } : {}, ...probe.path ? { path: probe.path } : {} };
+    if (probe.state === 'missing')
+        return { ...base, ready: false, installation: 'missing', credential: 'not_required', reason: spec.id + ': ' + (probe.reason ?? 'not installed'), code: 'cli_missing' };
+    if (probe.state === 'incompatible')
+        return { ...base, ready: false, installation: 'incompatible', credential: 'not_required', reason: spec.id + ': ' + (probe.reason ?? 'contract mismatch'), code: 'cli_incompatible' };
+    const missing = missingEnv(spec, options.env ?? specEnv(deps));
+    if (missing.length)
+        return { ...base, ready: false, installation: 'detected', credential: 'missing', reason: spec.id + ': ' + missing.join(' / ') + ' not set (' + loginHint(spec) + ')', code: 'not_logged_in' };
+    const saved = savedLoginPresent(spec, options);
+    if (saved === false)
+        return { ...base, ready: false, installation: 'detected', credential: 'missing', reason: spec.id + ': no saved login (' + loginHint(spec) + ')', code: 'not_logged_in' };
+    const credential = saved === true || (spec.env.required?.length ?? 0) > 0 ? 'configured' : spec.needsLogin ? undefined : 'not_required';
+    return { ...base, ready: true, installation: 'detected', ...credential ? { credential } : {}, code: 'ok' };
+}
+//# sourceMappingURL=engine.js.map

package/lib/cli/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../src/cli/engine.ts"],"names":[],"mappings":"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"}

package/lib/cli/opencli-sites.js

@@ -0,0 +1,83 @@
+/**
+ * The static facts of the standalone OpenCLI sites the plugin searches (free of Node imports, so the catalog and the chain
+ * specs can read them): which site serves which platform, how each site's `search` rows map to sources, and how far each
+ * mapping was verified. The spec generation itself (src/cli/opencli.ts) reads the live command table.
+ * @module web-search-pro/cli/opencli-sites
+ */
+/** Platform -> site of the standalone OpenCLI (`opencli <site> search`). */
+export const OPENCLI_SITE_OF = {
+    xiaohongshu: 'xiaohongshu', twitter: 'twitter', reddit: 'reddit', instagram: 'instagram', facebook: 'facebook',
+    zhihu: 'zhihu', weibo: 'weibo', douban: 'douban', tieba: 'tieba', douyin: 'douyin', bilibili: 'bilibili', youtube: 'youtube', wechat: 'weixin',
+};
+/** Generic field mapping over the columns OpenCLI commands emit (rank, title, url, summary, ...), for the sites without a measured or documented mapping below. */
+const FIELDS = {
+    url: ['url', 'link', 'href', 'projectUrl', 'item_url'],
+    title: ['title', 'name', 'text', 'desc', 'label'],
+    snippet: ['summary', 'snippet', 'description', 'desc', 'content', 'selftext', 'abstract', 'author', 'user'],
+    publishedAt: ['published_at', 'publish_time', 'created_at', 'date', 'time', 'published', 'postTime'],
+};
+export const GENERIC_OUTPUT = {
+    format: 'json', stripTags: true,
+    fields: { url: [...FIELDS.url], title: [...FIELDS.title], snippet: [...FIELDS.snippet], publishedAt: [...FIELDS.publishedAt] },
+};
+/**
+ * The output mapping of the sites the plugin knows by their real columns. All four print a JSON array of flat rows under `-f json`.
+ *  - twitter, zhihu: MEASURED (opencli 1.8.8, 2026-10-27, fixtures live-opencli-*). twitter rows are `id, author (handle), bio, text,
+ *    created_at (X API format), likes (number), views (string), url (https://x.com/i/status/<id>), has_media, media_urls, ...`; the
+ *    title and meta line follow the standalone twitter backend (text, then author · likes · views · time). zhihu rows are
+ *    `rank, title, type, author, votes, url` and carry no excerpt and no time.
+ *  - xiaohongshu, reddit: NOT MEASURED. The only runs failed (login wall; an HTML page instead of JSON), so the mapping is the
+ *    documented columns of clis/xiaohongshu/search.js (`rank, title, author, likes, published_at (date from the note id), url`,
+ *    the url is a signed search_result link) and clis/reddit/search.js (`id, title, subreddit (r/x), author, score, comments, url,
+ *    created_utc (epoch seconds), selftext, ...`), read from the source of 1.8.8.
+ */
+export const SITE_OUTPUT = {
+    twitter: {
+        format: 'json', titleMax: 200,
+        fields: {
+            url: [{ template: 'https://x.com/{author}/status/{id}' }, 'url'],
+            title: ['text', { template: '@{author}' }],
+            snippet: { join: [{ template: '@{author}' }, { path: 'likes', prefix: 'likes ' }, { path: 'views', prefix: 'views ' }, { time: 'created_at' }], sep: ' · ' },
+            publishedAt: { time: 'created_at' },
+        },
+    },
+    zhihu: {
+        format: 'json', stripTags: true,
+        fields: {
+            url: 'url',
+            title: 'title',
+            snippet: { join: ['type', 'author', { path: 'votes', prefix: '赞同 ' }], sep: ' · ' },
+        },
+    },
+    xiaohongshu: {
+        format: 'json',
+        fields: {
+            url: 'url',
+            title: 'title',
+            snippet: { join: [{ path: 'author', prefix: '作者: ' }, { path: 'likes', prefix: '赞: ' }] },
+            publishedAt: { time: 'published_at' },
+        },
+    },
+    reddit: {
+        format: 'json',
+        fields: {
+            url: 'url',
+            title: 'title',
+            snippet: { join: ['subreddit', { path: 'score', prefix: 'score ' }, { path: 'comments', suffix: ' comments' }, 'selftext'], sep: ' · ' },
+            publishedAt: { epoch: 'created_utc' },
+        },
+    },
+};
+const CHECKED = { version: '1.8.8', date: '2026-10-27' };
+const SITE_VERIFICATION = {
+    twitter: { status: 'live', ...CHECKED, note: '`opencli twitter search -f json` run on the user\'s own Chrome (OpenCLI Browser Bridge) and parsed: a JSON array of tweets (fixture live-opencli-twitter-search.json); created_at is in the X API format and is converted to ISO' },
+    zhihu: { status: 'live', ...CHECKED, note: '`opencli zhihu search -f json` run on the user\'s own Chrome and parsed: a JSON array of { rank, title, type, author, votes, url } without excerpt or time (fixture live-opencli-zhihu-search.json)' },
+    xiaohongshu: { status: 'contract-only', ...CHECKED, note: 'not measured: the only run answered AUTH_REQUIRED (exit 77, the Chrome had no xiaohongshu login); columns read from clis/xiaohongshu/search.js of 1.8.8. The AUTH_REQUIRED failure itself is mapped (fixture live-opencli-xiaohongshu-auth-required.yaml)' },
+    reddit: { status: 'contract-only', ...CHECKED, note: 'not measured: the only run got an HTML page where the command expects JSON (exit 1, code UNKNOWN; Reddit blocked the request on this proxied network); columns read from clis/reddit/search.js of 1.8.8. That failure is mapped (fixture live-opencli-reddit-html-error.yaml)' },
+};
+const GENERIC_VERIFICATION = { status: 'contract-only', ...CHECKED, note: 'command table from `opencli list -f json`; -f json is the documented output option; this site\'s search was not run (it uses your Chrome session)' };
+/** How far the search of one OpenCLI site was checked (`live`, `contract-only`). */
+export function opencliSiteVerification(site) {
+    return SITE_VERIFICATION[site] ?? GENERIC_VERIFICATION;
+}
+//# sourceMappingURL=opencli-sites.js.map

package/lib/cli/opencli-sites.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"opencli-sites.js","sourceRoot":"","sources":["../../src/cli/opencli-sites.ts"],"names":[],"mappings":"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"}

package/lib/cli/opencli.js

@@ -0,0 +1,153 @@
+/**
+ * Standalone OpenCLI (dev-plan M12): the `opencli` command the user installed themselves, which drives their own Chrome
+ * through its Browser Bridge, independent of the dsh-browser plugin. It has one command per site and the plugin only
+ * calls `<site> search`, and only for sites that `opencli list -f json` itself reports with a read-access `search`
+ * command taking a positional query (the catalog is the tool's own, so a site without search, such as douyin or v2ex,
+ * is never assumed to have one). The list is a local call: no browser, no login.
+ * @module web-search-pro/cli/opencli
+ */
+import { runCli } from "../util.js";
+import { buildCliEnv } from "./runner.js";
+import { findOnPath, probeCli } from "./probe.js";
+import { validateCliAdapterSpec } from "./spec.js";
+import { GENERIC_OUTPUT, opencliSiteVerification, SITE_OUTPUT } from "./opencli-sites.js";
+export { OPENCLI_SITE_OF } from "./chains-spec.js";
+export { opencliSiteVerification };
+/** The command that proves this is the OpenCLI whose `list` output the adapter understands. Verified on 1.8.8. */
+export const OPENCLI_PROBE = {
+    id: 'opencli',
+    bins: ['opencli'],
+    packageNote: 'OpenCLI (npm i -g @jackwener/opencli; needs its Browser Bridge extension in your own Chrome)',
+    probe: { versionArgs: ['--version'], minVersion: '1.8.0', helpArgs: ['list', '--help'], mustContain: ['--format', 'json'] },
+    env: {},
+};
+/**
+ * The browser options every browser-backed site command of OpenCLI accepts (read from `opencli <site> search --help` and
+ * dist/src/execution.js of 1.8.8): the command runs in a background window (no focus is taken from the user's Chrome), with an
+ * ephemeral site session whose tab is released when it finishes. These are also its defaults; the plugin passes them
+ * explicitly so a changed `OPENCLI_WINDOW` / `OPENCLI_SITE_SESSION` environment cannot bring a window to the front, and only
+ * when the command itself lists the three options (a command without a browser rejects unknown options).
+ */
+export const OPENCLI_SILENT_ARGS = ['--window', 'background', '--site-session', 'ephemeral', '--keep-tab', 'false'];
+const SILENT_OPTIONS = ['--window', '--site-session', '--keep-tab'];
+/** The probe of one site's search command: it must list the three silent browser options (`opencli <site> search --help`). Local, cached, no browser. */
+export function opencliSiteProbe(site) {
+    return {
+        id: 'opencli:' + site,
+        bins: ['opencli'],
+        packageNote: OPENCLI_PROBE.packageNote,
+        probe: { versionArgs: ['--version'], minVersion: '1.8.0', helpArgs: [site, 'search', '--help'], mustContain: [...SILENT_OPTIONS] },
+        env: {},
+    };
+}
+/** Sites with a read `search` command taking a positional query, from the JSON of `opencli list -f json`. Pure. */
+export function parseOpencliList(json) {
+    const rows = JSON.parse(json);
+    if (!Array.isArray(rows))
+        throw new Error('opencli list did not return an array');
+    const sites = new Map();
+    for (const row of rows) {
+        if (!row || typeof row.site !== 'string' || row.name !== 'search' || row.access !== 'read' || !Array.isArray(row.args))
+            continue;
+        const args = row.args;
+        if (!args.some(a => a.positional === true && a.name === 'query') && !args.some(a => a.positional === true))
+            continue;
+        sites.set(row.site, {
+            site: row.site,
+            strategy: typeof row.strategy === 'string' ? row.strategy : 'cookie',
+            browser: row.browser === true,
+            hasLimit: args.some(a => a.name === 'limit'),
+            ...typeof row.domain === 'string' && row.domain ? { domain: row.domain } : {},
+        });
+    }
+    return sites;
+}
+const cache = new Map();
+export function clearOpencliCache() { cache.clear(); }
+/** The searchable sites of the installed OpenCLI (cached 5 minutes); `undefined` when the command cannot be listed. */
+export async function listOpencliSites(options = {}) {
+    const found = findOnPath('opencli');
+    if (!found)
+        return { problem: 'opencli not found on PATH' };
+    const now = options.now ?? Date.now;
+    const key = found + '\u0000' + (process.env.PATH ?? '');
+    const hit = cache.get(key);
+    if (!options.force && hit && now() - hit.at <= (options.ttlMs ?? 300_000))
+        return { sites: hit.sites };
+    const run = options.run ?? runCli;
+    const res = await run(found, ['list', '-f', 'json'], { timeoutMs: 20_000, signal: undefined, env: buildCliEnv({ env: {} }), cleanEnv: true, maxOutput: 16 * 1024 * 1024, outputEncoding: 'utf-8' });
+    if (res.code !== 0 || res.truncated)
+        return { problem: res.truncated ? 'opencli list output exceeded the size cap' : 'opencli list failed with exit ' + res.code };
+    try {
+        const sites = parseOpencliList(res.stdout);
+        cache.set(key, { at: now(), sites });
+        return { sites };
+    }
+    catch (error) {
+        return { problem: 'opencli list returned an unexpected payload: ' + (error instanceof Error ? error.message : String(error)) };
+    }
+}
+/**
+ * The failure format of OpenCLI 1.8.8 (dist/src/errors.js `toEnvelope`, printed as YAML on stderr whatever `-f` says):
+ * `ok: false` / `error: { code, message, help?, exitCode }`. Codes, from that file and the site adapters:
+ *  - AUTH_REQUIRED (exit 77): the Chrome has no login for the site -> not logged in (measured on xiaohongshu);
+ *  - LOGIN_WALL (77), SECURITY_BLOCK, RATE_LIMITED, FORBIDDEN: an HTML page where JSON was expected, a risk-control block -> blocked;
+ *    UNKNOWN with a JSON parse error on an HTML body (`Unexpected token '<'`) is the same thing from an adapter that does not
+ *    check (measured on reddit through a proxy);
+ *  - EMPTY_RESULT (66), NO_DATA, EMPTY_RESPONSE: nothing found; BROWSER_CONNECT (69): no Chrome / bridge; TIMEOUT (75);
+ *  - ARGUMENT, INVALID_ARGUMENT, ...: the arguments of this adapter are not accepted by that version.
+ * Anything else (COMMAND_EXEC, FETCH_ERROR, HTTP_ERROR, ...) keeps OpenCLI's own message.
+ */
+export const OPENCLI_ERROR_CODES = {
+    codePath: 'error.code',
+    messagePath: 'error.message',
+    notLoggedIn: ['AUTH_REQUIRED'],
+    notLoggedInExit: [77],
+    blocked: ['LOGIN_WALL', 'SECURITY_BLOCK', 'RATE_LIMITED', 'FORBIDDEN'],
+    blockedPatterns: ["unexpected token '<'", 'is not valid json', '<!doctype', '<html', '<body'],
+    empty: ['EMPTY_RESULT', 'NO_DATA', 'EMPTY_RESPONSE'],
+    unavailable: ['BROWSER_CONNECT'],
+    timeout: ['TIMEOUT'],
+    usage: ['ARGUMENT', 'INVALID_ARGUMENT', 'INVALID_ARG', 'INVALID_ARGS', 'INVALID_INPUT'],
+};
+const NOT_LOGGED_IN = ['not logged in', 'login required', 'please log in', 'please login', 'sign in', 'auth_required', 'requires login', '未登录', '请先登录'];
+/** The spec that runs `opencli <site> search` for one platform, or undefined when the generated spec is invalid (a site named like a write command). */
+export function opencliSearchSpec(platform, entry, options = {}) {
+    const spec = {
+        id: 'opencli',
+        bins: ['opencli'],
+        packageNote: OPENCLI_PROBE.packageNote,
+        platforms: [platform],
+        probe: OPENCLI_PROBE.probe,
+        allowedSubcommands: ['list', entry.site, 'search'],
+        search: {
+            argv: [entry.site, 'search', '{query}', ...entry.hasLimit ? ['--limit', '{count}'] : [], '-f', 'json', ...entry.browser && options.silent ? OPENCLI_SILENT_ARGS : []],
+            maxCount: 20,
+            output: SITE_OUTPUT[entry.site] ?? GENERIC_OUTPUT,
+            notLoggedInPatterns: NOT_LOGGED_IN,
+            errorCodes: OPENCLI_ERROR_CODES,
+        },
+        env: {},
+        needsLogin: entry.strategy !== 'public',
+        // The login is the one of the user's own Chrome; the plugin never suggests a login command for it.
+        ...entry.strategy !== 'public' ? { login: { hint: '在你的 Chrome 里登录 ' + (entry.domain ?? entry.site) + ' 后重试（opencli 使用 Chrome 的登录态）' } } : {},
+        timeoutMs: 60_000,
+        maxOutputBytes: 8 * 1024 * 1024,
+        verification: opencliSiteVerification(entry.site),
+    };
+    return validateCliAdapterSpec(spec, 'builtin').ok ? spec : undefined;
+}
+/**
+ * Everything a search of one platform through the standalone OpenCLI needs, checked locally (the command table and the site's
+ * `--help`, never a search): the site's entry, whether its command takes the silent browser options, and the generated spec.
+ */
+export async function planOpencliSearch(platform, site) {
+    const listed = await listOpencliSites();
+    const entry = listed.sites?.get(site);
+    if (!entry)
+        return { silent: false, problem: listed.problem ?? 'opencli has no read `search` command for the site ' + site + ' (opencli list)', hint: 'run `opencli list` to see the sites your version supports' };
+    const silent = entry.browser && (await probeCli(opencliSiteProbe(site))).state === 'detected';
+    const spec = opencliSearchSpec(platform, entry, { silent });
+    return spec ? { spec, entry, silent } : { entry, silent, problem: 'opencli site ' + site + ' cannot be used by this adapter' };
+}
+//# sourceMappingURL=opencli.js.map

package/lib/cli/opencli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"opencli.js","sourceRoot":"","sources":["../../src/cli/opencli.ts"],"names":[],"mappings":"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"}

package/lib/cli/probe.js

@@ -0,0 +1,128 @@
+/**
+ * Contract probes of CLI adapter specs (dev-plan M12, design §4.3 / §4.4): local only, cached with a TTL. A probe finds
+ * the command on PATH and runs ONLY the spec's version and help commands, then checks the contract the spec needs: a
+ * minimum version and the subcommands / flags that must appear in the help text. A same-named program with another
+ * contract is `incompatible`, not `detected`. A probe never runs a search and never logs in.
+ * @module web-search-pro/cli/probe
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { runCli } from "../util.js";
+import { buildCliEnv } from "./runner.js";
+import { compareVersions, parseVersion } from "./spec.js";
+const DEFAULT_TTL_MS = 60_000;
+const PROBE_TIMEOUT_MS = 8_000;
+const cache = new Map();
+const flights = new Map();
+export function clearProbeCache() {
+    cache.clear();
+    flights.clear();
+}
+/** The executable `cmd` resolves to on PATH (no process is spawned; Windows tries PATHEXT). */
+export function findOnPath(cmd, env = process.env) {
+    const win = process.platform === 'win32';
+    const dirs = (env.PATH ?? env.Path ?? '').split(path.delimiter).filter(Boolean);
+    const exts = win ? ['', ...(env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean)] : [''];
+    for (const dir of dirs) {
+        for (const ext of exts) {
+            const file = path.join(dir, cmd + ext);
+            try {
+                const stat = fs.statSync(file);
+                if (stat.isFile() && (win || (stat.mode & 0o111) !== 0))
+                    return file;
+            }
+            catch { /* not here */ }
+        }
+    }
+    return undefined;
+}
+const keyOf = (spec) => [spec.id, spec.bins.join(','), JSON.stringify(spec.probe), process.env.PATH ?? ''].join('\u0000');
+/** The cached probe of a spec, when one is fresh (no spawn: `Engine.available()` is synchronous). */
+export function cachedProbe(spec, ttlMs = DEFAULT_TTL_MS, now = Date.now) {
+    const hit = cache.get(keyOf(spec));
+    return hit && now() - hit.at <= ttlMs ? hit.result : undefined;
+}
+/**
+ * Decide whether version and help output satisfy a spec's contract. Pure (the fixtures tests call it directly).
+ * The version command may fail or print nothing unless the spec asks for a minimum version.
+ */
+export function evaluateCliContract(spec, bin, version, help) {
+    const { probe } = spec;
+    const versionCmd = [bin, ...probe.versionArgs].join(' ');
+    const detected = version.code === 0 ? parseVersion(version.output) : undefined;
+    if (probe.minVersion !== undefined) {
+        if (version.code !== 0)
+            return { state: 'incompatible', reason: versionCmd + ' failed with exit ' + version.code };
+        if (!detected)
+            return { state: 'incompatible', reason: versionCmd + ' returned no semantic version' };
+        if (compareVersions(detected, probe.minVersion) < 0)
+            return { state: 'incompatible', version: detected, reason: bin + ' ' + detected + ' is older than required ' + probe.minVersion };
+    }
+    const withVersion = detected ? { version: detected } : {};
+    const helpCmd = [bin, ...probe.helpArgs].join(' ');
+    if (help.code !== 0)
+        return { state: 'incompatible', ...withVersion, reason: helpCmd + ' failed with exit ' + help.code };
+    const lower = help.output.toLowerCase();
+    const missing = probe.mustContain.filter(fragment => !lower.includes(fragment.toLowerCase()));
+    if (missing.length) {
+        const words = probe.helpArgs.filter(arg => !arg.startsWith('-')).join(' ') || 'help';
+        return { state: 'incompatible', ...withVersion, reason: bin + ' ' + words + ' contract missing ' + missing.join(', ') + ' (a different program with the same name' + (probe.contractHint ? ', or an older version: ' + probe.contractHint : '?') + ')' };
+    }
+    return { state: 'detected', ...withVersion };
+}
+async function probeUncached(spec, options) {
+    const run = options.run ?? runCli;
+    const now = options.now ?? Date.now;
+    const env = buildCliEnv(spec);
+    const call = async (bin, args) => {
+        const res = await run(bin, [...args], { timeoutMs: PROBE_TIMEOUT_MS, signal: undefined, env, cleanEnv: true, maxOutput: 128 * 1024, outputEncoding: 'utf-8' });
+        return { code: res.timedOut || res.spawnFailed ? -1 : res.code, output: res.stdout + '\n' + res.stderr };
+    };
+    let firstBad;
+    for (const bin of spec.bins) {
+        const found = findOnPath(bin);
+        if (!found)
+            continue;
+        const version = await call(found, spec.probe.versionArgs);
+        const help = await call(found, spec.probe.helpArgs);
+        const verdict = evaluateCliContract(spec, bin, version, help);
+        const result = { state: verdict.state, bin, path: found, ...verdict.version ? { version: verdict.version } : {}, ...verdict.reason ? { reason: verdict.reason } : {}, checkedAt: now() };
+        if (verdict.state === 'detected')
+            return result;
+        firstBad ??= result;
+    }
+    return firstBad ?? { state: 'missing', reason: spec.bins.join(' / ') + ' not found on PATH (' + spec.packageNote + ')', checkedAt: now() };
+}
+/** Probe one spec (cached; concurrent calls for the same spec share one run). */
+export async function probeCli(spec, options = {}) {
+    const key = keyOf(spec);
+    const now = options.now ?? Date.now;
+    if (!options.force) {
+        const hit = cache.get(key);
+        if (hit && now() - hit.at <= (options.ttlMs ?? DEFAULT_TTL_MS))
+            return hit.result;
+        const flight = flights.get(key);
+        if (flight)
+            return flight;
+    }
+    const flight = probeUncached(spec, options).then(result => { cache.set(key, { at: now(), result }); return result; }).finally(() => { if (flights.get(key) === flight)
+        flights.delete(key); });
+    flights.set(key, flight);
+    return flight;
+}
+/** Probe many specs with a small concurrency bound (a settings refresh must not spawn dozens of processes at once). */
+export async function probeAll(specs, options = {}, concurrency = 4) {
+    const out = new Map();
+    let next = 0;
+    const worker = async () => {
+        for (;;) {
+            const spec = specs[next++];
+            if (!spec)
+                return;
+            out.set(spec.id, await probeCli(spec, options));
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(concurrency, specs.length) }, worker));
+    return out;
+}
+//# sourceMappingURL=probe.js.map