@jackwener/opencli 1.6.1 → 1.6.3

package/dist/src/execution.js

@@ -0,0 +1,209 @@
+/**
+ * Command execution: validates args, manages browser sessions, runs commands.
+ *
+ * This is the single entry point for executing any CLI command. It handles:
+ * 1. Argument validation and coercion
+ * 2. Browser session lifecycle (if needed)
+ * 3. Domain pre-navigation for cookie/header strategies
+ * 4. Timeout enforcement
+ * 5. Lazy-loading of TS modules from manifest
+ * 6. Lifecycle hooks (onBeforeExecute / onAfterExecute)
+ */
+import { Strategy, getRegistry, fullName } from './registry.js';
+import { pathToFileURL } from 'node:url';
+import { executePipeline } from './pipeline/index.js';
+import { AdapterLoadError, ArgumentError, BrowserConnectError, CommandExecutionError, getErrorMessage } from './errors.js';
+import { shouldUseBrowserSession } from './capabilityRouting.js';
+import { getBrowserFactory, browserSession, runWithTimeout, DEFAULT_BROWSER_COMMAND_TIMEOUT } from './runtime.js';
+import { emitHook } from './hooks.js';
+import { checkDaemonStatus } from './browser/discover.js';
+import { log } from './logger.js';
+import { isElectronApp } from './electron-apps.js';
+import { probeCDP, resolveElectronEndpoint } from './launcher.js';
+const _loadedModules = new Set();
+export function coerceAndValidateArgs(cmdArgs, kwargs) {
+    const result = { ...kwargs };
+    for (const argDef of cmdArgs) {
+        const val = result[argDef.name];
+        if (argDef.required && (val === undefined || val === null || val === '')) {
+            throw new ArgumentError(`Argument "${argDef.name}" is required.`, argDef.help ?? `Provide a value for --${argDef.name}`);
+        }
+        if (val !== undefined && val !== null) {
+            if (argDef.type === 'int' || argDef.type === 'number') {
+                const num = Number(val);
+                if (Number.isNaN(num)) {
+                    throw new ArgumentError(`Argument "${argDef.name}" must be a valid number. Received: "${val}"`);
+                }
+                result[argDef.name] = num;
+            }
+            else if (argDef.type === 'boolean' || argDef.type === 'bool') {
+                if (typeof val === 'string') {
+                    const lower = val.toLowerCase();
+                    if (lower === 'true' || lower === '1')
+                        result[argDef.name] = true;
+                    else if (lower === 'false' || lower === '0')
+                        result[argDef.name] = false;
+                    else
+                        throw new ArgumentError(`Argument "${argDef.name}" must be a boolean (true/false). Received: "${val}"`);
+                }
+                else {
+                    result[argDef.name] = Boolean(val);
+                }
+            }
+            const coercedVal = result[argDef.name];
+            if (argDef.choices && argDef.choices.length > 0) {
+                if (!argDef.choices.map(String).includes(String(coercedVal))) {
+                    throw new ArgumentError(`Argument "${argDef.name}" must be one of: ${argDef.choices.join(', ')}. Received: "${coercedVal}"`);
+                }
+            }
+        }
+        else if (argDef.default !== undefined) {
+            result[argDef.name] = argDef.default;
+        }
+    }
+    return result;
+}
+async function runCommand(cmd, page, kwargs, debug) {
+    const internal = cmd;
+    if (internal._lazy && internal._modulePath) {
+        const modulePath = internal._modulePath;
+        if (!_loadedModules.has(modulePath)) {
+            try {
+                await import(pathToFileURL(modulePath).href);
+                _loadedModules.add(modulePath);
+            }
+            catch (err) {
+                throw new AdapterLoadError(`Failed to load adapter module ${modulePath}: ${getErrorMessage(err)}`, 'Check that the adapter file exists and has no syntax errors.');
+            }
+        }
+        const updated = getRegistry().get(fullName(cmd));
+        if (updated?.func) {
+            if (!page && updated.browser !== false) {
+                throw new CommandExecutionError(`Command ${fullName(cmd)} requires a browser session but none was provided`);
+            }
+            return updated.func(page, kwargs, debug);
+        }
+        if (updated?.pipeline)
+            return executePipeline(page, updated.pipeline, { args: kwargs, debug });
+    }
+    if (cmd.func)
+        return cmd.func(page, kwargs, debug);
+    if (cmd.pipeline)
+        return executePipeline(page, cmd.pipeline, { args: kwargs, debug });
+    throw new CommandExecutionError(`Command ${fullName(cmd)} has no func or pipeline`, 'This is likely a bug in the adapter definition. Please report this issue.');
+}
+function resolvePreNav(cmd) {
+    if (cmd.navigateBefore === false)
+        return null;
+    if (typeof cmd.navigateBefore === 'string')
+        return cmd.navigateBefore;
+    if ((cmd.strategy === Strategy.COOKIE || cmd.strategy === Strategy.HEADER) && cmd.domain) {
+        return `https://${cmd.domain}`;
+    }
+    return null;
+}
+function ensureRequiredEnv(cmd) {
+    const missing = (cmd.requiredEnv ?? []).find(({ name }) => {
+        const value = process.env[name];
+        return value === undefined || value === null || value === '';
+    });
+    if (!missing)
+        return;
+    throw new CommandExecutionError(`Command ${fullName(cmd)} requires environment variable ${missing.name}.`, missing.help ?? `Set ${missing.name} before running ${fullName(cmd)}.`);
+}
+export async function executeCommand(cmd, rawKwargs, debug = false) {
+    let kwargs;
+    try {
+        kwargs = coerceAndValidateArgs(cmd.args, rawKwargs);
+        cmd.validateArgs?.(kwargs);
+    }
+    catch (err) {
+        if (err instanceof ArgumentError)
+            throw err;
+        throw new ArgumentError(getErrorMessage(err));
+    }
+    const hookCtx = {
+        command: fullName(cmd),
+        args: kwargs,
+        startedAt: Date.now(),
+    };
+    await emitHook('onBeforeExecute', hookCtx);
+    let result;
+    try {
+        if (shouldUseBrowserSession(cmd)) {
+            const electron = isElectronApp(cmd.site);
+            let cdpEndpoint;
+            if (electron) {
+                // Electron apps: respect manual endpoint override, then try auto-detect
+                const manualEndpoint = process.env.OPENCLI_CDP_ENDPOINT;
+                if (manualEndpoint) {
+                    const port = Number(new URL(manualEndpoint).port);
+                    if (!await probeCDP(port)) {
+                        throw new CommandExecutionError(`CDP not reachable at ${manualEndpoint}`, 'Check that the app is running with --remote-debugging-port and the endpoint is correct.');
+                    }
+                    cdpEndpoint = manualEndpoint;
+                }
+                else {
+                    cdpEndpoint = await resolveElectronEndpoint(cmd.site);
+                }
+            }
+            else {
+                // Browser Bridge: fail-fast when daemon is up but extension is missing.
+                // 300ms timeout avoids a full 2s wait on cold-start.
+                const status = await checkDaemonStatus({ timeout: 300 });
+                if (status.running && !status.extensionConnected) {
+                    throw new BrowserConnectError('Browser Bridge extension not connected', 'Install the Browser Bridge:\n' +
+                        '  1. Download: https://github.com/jackwener/opencli/releases\n' +
+                        '  2. In Chrome or Chromium, open chrome://extensions → Developer Mode → Load unpacked\n' +
+                        '  Then run: opencli doctor');
+                }
+            }
+            ensureRequiredEnv(cmd);
+            const BrowserFactory = getBrowserFactory(cmd.site);
+            result = await browserSession(BrowserFactory, async (page) => {
+                const preNavUrl = resolvePreNav(cmd);
+                if (preNavUrl) {
+                    // Navigate directly — the extension's handleNavigate already has a fast-path
+                    // that skips navigation if the tab is already at the target URL.
+                    // This avoids an extra exec round-trip (getCurrentUrl) on first command and
+                    // lets the extension create the automation window with the target URL directly
+                    // instead of about:blank.
+                    try {
+                        await page.goto(preNavUrl);
+                    }
+                    catch (err) {
+                        if (debug)
+                            log.debug(`[pre-nav] Failed to navigate to ${preNavUrl}: ${err instanceof Error ? err.message : err}`);
+                    }
+                }
+                return runWithTimeout(runCommand(cmd, page, kwargs, debug), {
+                    timeout: cmd.timeoutSeconds ?? DEFAULT_BROWSER_COMMAND_TIMEOUT,
+                    label: fullName(cmd),
+                });
+            }, { workspace: `site:${cmd.site}`, cdpEndpoint });
+        }
+        else {
+            // Non-browser commands: apply timeout only when explicitly configured.
+            const timeout = cmd.timeoutSeconds;
+            if (timeout !== undefined && timeout > 0) {
+                result = await runWithTimeout(runCommand(cmd, null, kwargs, debug), {
+                    timeout,
+                    label: fullName(cmd),
+                    hint: `Increase the adapter's timeoutSeconds setting (currently ${timeout}s)`,
+                });
+            }
+            else {
+                result = await runCommand(cmd, null, kwargs, debug);
+            }
+        }
+    }
+    catch (err) {
+        hookCtx.error = err;
+        hookCtx.finishedAt = Date.now();
+        await emitHook('onAfterExecute', hookCtx);
+        throw err;
+    }
+    hookCtx.finishedAt = Date.now();
+    await emitHook('onAfterExecute', hookCtx, result);
+    return result;
+}

package/dist/src/execution.test.d.ts

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

package/dist/src/explore.js

@@ -0,0 +1,379 @@
+/**
+ * Deep Explore: intelligent API discovery with response analysis.
+ *
+ * Navigates to the target URL, auto-scrolls to trigger lazy loading,
+ * captures network traffic, analyzes JSON responses, and automatically
+ * infers CLI capabilities from discovered API endpoints.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { DEFAULT_BROWSER_EXPLORE_TIMEOUT, browserSession, runWithTimeout } from './runtime.js';
+import { LIMIT_PARAMS } from './constants.js';
+import { detectFramework } from './scripts/framework.js';
+import { discoverStores } from './scripts/store.js';
+import { interactFuzz } from './scripts/interact.js';
+import { log } from './logger.js';
+import { urlToPattern, findArrayPath, flattenFields, detectFieldRoles, inferCapabilityName, inferStrategy, detectAuthFromHeaders, classifyQueryParams, } from './analysis.js';
+// ── Site name detection ────────────────────────────────────────────────────
+const KNOWN_SITE_ALIASES = {
+    'x.com': 'twitter', 'twitter.com': 'twitter',
+    'news.ycombinator.com': 'hackernews',
+    'www.zhihu.com': 'zhihu', 'www.bilibili.com': 'bilibili',
+    'search.bilibili.com': 'bilibili',
+    'www.v2ex.com': 'v2ex', 'www.reddit.com': 'reddit',
+    'www.xiaohongshu.com': 'xiaohongshu', 'www.douban.com': 'douban',
+    'www.weibo.com': 'weibo', 'www.bbc.com': 'bbc',
+};
+export function detectSiteName(url) {
+    try {
+        const host = new URL(url).hostname.toLowerCase();
+        if (host in KNOWN_SITE_ALIASES)
+            return KNOWN_SITE_ALIASES[host];
+        const parts = host.split('.').filter(p => p && p !== 'www');
+        if (parts.length >= 2) {
+            if (['uk', 'jp', 'cn', 'com'].includes(parts[parts.length - 1]) && parts.length >= 3) {
+                return slugify(parts[parts.length - 3]);
+            }
+            return slugify(parts[parts.length - 2]);
+        }
+        return parts[0] ? slugify(parts[0]) : 'site';
+    }
+    catch {
+        return 'site';
+    }
+}
+export function slugify(value) {
+    return value.trim().toLowerCase().replace(/[^a-zA-Z0-9]+/g, '-').replace(/^-|-$/g, '') || 'site';
+}
+/**
+ * Parse raw network output from browser page.
+ * Handles text format: [GET] url => [200]
+ */
+function parseNetworkRequests(raw) {
+    if (typeof raw === 'string') {
+        const entries = [];
+        for (const line of raw.split('\n')) {
+            // Format: [GET] URL => [200]
+            const m = line.match(/\[?(GET|POST|PUT|DELETE|PATCH|OPTIONS)\]?\s+(\S+)\s*(?:=>|→)\s*\[?(\d+)\]?/i);
+            if (m) {
+                const [, method, url, status] = m;
+                entries.push({
+                    method: method.toUpperCase(), url, status: status ? parseInt(status) : null,
+                    contentType: (url.includes('/api/') || url.includes('/x/') || url.endsWith('.json')) ? 'application/json' : '',
+                });
+            }
+        }
+        return entries;
+    }
+    if (Array.isArray(raw)) {
+        return raw.filter(e => e && typeof e === 'object').map(e => ({
+            method: (e.method ?? 'GET').toUpperCase(),
+            url: String(e.url ?? e.request?.url ?? e.requestUrl ?? ''),
+            status: e.status ?? e.statusCode ?? null,
+            contentType: e.contentType ?? e.response?.contentType ?? '',
+            responseBody: e.responseBody, requestHeaders: e.requestHeaders,
+        }));
+    }
+    return [];
+}
+function analyzeResponseBody(body) {
+    if (!body || typeof body !== 'object')
+        return null;
+    const result = findArrayPath(body);
+    if (!result)
+        return null;
+    const sample = result.items[0];
+    const sampleFields = sample && typeof sample === 'object' ? flattenFields(sample, '', 2) : [];
+    const detectedFields = detectFieldRoles(sampleFields);
+    return { itemPath: result.path || null, itemCount: result.items.length, detectedFields, sampleFields };
+}
+function isBooleanRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        && Object.values(value).every(v => typeof v === 'boolean');
+}
+function scoreEndpoint(ep) {
+    let s = 0;
+    if (ep.contentType.includes('json'))
+        s += 10;
+    if (ep.responseAnalysis) {
+        s += 5;
+        s += Math.min(ep.responseAnalysis.itemCount, 10);
+        s += Object.keys(ep.responseAnalysis.detectedFields).length * 2;
+    }
+    if (ep.pattern.includes('/api/') || ep.pattern.includes('/x/'))
+        s += 3;
+    if (ep.hasSearchParam)
+        s += 3;
+    if (ep.hasPaginationParam)
+        s += 2;
+    if (ep.hasLimitParam)
+        s += 2;
+    if (ep.status === 200)
+        s += 2;
+    // Anti-Bot Empty Value Detection: penalize JSON endpoints returning empty data
+    if (ep.responseAnalysis && ep.responseAnalysis.itemCount === 0 && ep.contentType.includes('json'))
+        s -= 3;
+    return s;
+}
+// ── Framework detection ────────────────────────────────────────────────────
+const FRAMEWORK_DETECT_JS = detectFramework.toString();
+// ── Store discovery ────────────────────────────────────────────────────────
+const STORE_DISCOVER_JS = discoverStores.toString();
+// ── Auto-Interaction (Fuzzing) ─────────────────────────────────────────────
+const INTERACT_FUZZ_JS = interactFuzz.toString();
+// ── Analysis helpers (extracted from exploreUrl) ───────────────────────────
+/** Filter, deduplicate, and score network endpoints. */
+function analyzeEndpoints(networkEntries) {
+    const seen = new Map();
+    for (const entry of networkEntries) {
+        if (!entry.url)
+            continue;
+        const ct = entry.contentType.toLowerCase();
+        if (ct.includes('image/') || ct.includes('font/') || ct.includes('css') || ct.includes('javascript') || ct.includes('wasm'))
+            continue;
+        if (entry.status && entry.status >= 400)
+            continue;
+        const pattern = urlToPattern(entry.url);
+        const key = `${entry.method}:${pattern}`;
+        if (seen.has(key))
+            continue;
+        const { params: qp, hasSearch, hasPagination, hasLimit } = classifyQueryParams(entry.url);
+        const ep = {
+            pattern, method: entry.method, url: entry.url, status: entry.status, contentType: ct,
+            queryParams: qp, hasSearchParam: hasSearch,
+            hasPaginationParam: hasPagination,
+            hasLimitParam: hasLimit || qp.some(p => LIMIT_PARAMS.has(p)),
+            authIndicators: detectAuthFromHeaders(entry.requestHeaders),
+            responseAnalysis: entry.responseBody ? analyzeResponseBody(entry.responseBody) : null,
+            score: 0,
+        };
+        ep.score = scoreEndpoint(ep);
+        seen.set(key, ep);
+    }
+    const analyzed = [...seen.values()].filter(ep => ep.score >= 5).sort((a, b) => b.score - a.score);
+    return { analyzed, totalCount: seen.size };
+}
+/** Infer CLI capabilities from analyzed endpoints. */
+function inferCapabilitiesFromEndpoints(endpoints, stores, opts) {
+    const capabilities = [];
+    const usedNames = new Set();
+    for (const ep of endpoints.slice(0, 8)) {
+        let capName = inferCapabilityName(ep.url, opts.goal);
+        if (usedNames.has(capName)) {
+            const suffix = ep.pattern.split('/').filter(s => s && !s.startsWith('{') && !s.includes('.')).pop();
+            capName = suffix ? `${capName}_${suffix}` : `${capName}_${usedNames.size}`;
+        }
+        usedNames.add(capName);
+        const cols = [];
+        if (ep.responseAnalysis) {
+            for (const role of ['title', 'url', 'author', 'score', 'time']) {
+                if (ep.responseAnalysis.detectedFields[role])
+                    cols.push(role);
+            }
+        }
+        const args = [];
+        if (ep.hasSearchParam)
+            args.push({ name: 'keyword', type: 'str', required: true });
+        args.push({ name: 'limit', type: 'int', required: false, default: 20 });
+        if (ep.hasPaginationParam)
+            args.push({ name: 'page', type: 'int', required: false, default: 1 });
+        const epStrategy = inferStrategy(ep.authIndicators);
+        let storeHint;
+        if ((epStrategy === 'intercept' || ep.authIndicators.includes('signature')) && stores.length > 0) {
+            for (const s of stores) {
+                const matchingAction = s.actions.find(a => capName.split('_').some(part => a.toLowerCase().includes(part)) ||
+                    a.toLowerCase().includes('fetch') || a.toLowerCase().includes('get'));
+                if (matchingAction) {
+                    storeHint = { store: s.id, action: matchingAction };
+                    break;
+                }
+            }
+        }
+        capabilities.push({
+            name: capName, description: `${opts.site ?? detectSiteName(opts.url)} ${capName}`,
+            strategy: storeHint ? 'store-action' : epStrategy,
+            confidence: Math.min(ep.score / 20, 1.0), endpoint: ep.pattern,
+            itemPath: ep.responseAnalysis?.itemPath ?? null,
+            recommendedColumns: cols.length ? cols : ['title', 'url'],
+            recommendedArgs: args,
+            ...(storeHint ? { storeHint } : {}),
+        });
+    }
+    const allAuth = new Set(endpoints.flatMap(ep => ep.authIndicators));
+    const topStrategy = allAuth.has('signature') ? 'intercept'
+        : allAuth.has('bearer') || allAuth.has('csrf') ? 'header'
+            : allAuth.size === 0 ? 'public' : 'cookie';
+    return { capabilities, topStrategy, authIndicators: [...allAuth] };
+}
+/** Write explore artifacts (manifest, endpoints, capabilities, auth, stores) to disk. */
+async function writeExploreArtifacts(targetDir, result, analyzedEndpoints, stores) {
+    await fs.promises.mkdir(targetDir, { recursive: true });
+    const tasks = [
+        fs.promises.writeFile(path.join(targetDir, 'manifest.json'), JSON.stringify({
+            site: result.site, target_url: result.target_url, final_url: result.final_url, title: result.title,
+            framework: result.framework, stores: stores.map(s => ({ type: s.type, id: s.id, actions: s.actions })),
+            top_strategy: result.top_strategy, explored_at: new Date().toISOString(),
+        }, null, 2)),
+        fs.promises.writeFile(path.join(targetDir, 'endpoints.json'), JSON.stringify(analyzedEndpoints.map(ep => ({
+            pattern: ep.pattern, method: ep.method, url: ep.url, status: ep.status,
+            contentType: ep.contentType, score: ep.score, queryParams: ep.queryParams,
+            itemPath: ep.responseAnalysis?.itemPath ?? null, itemCount: ep.responseAnalysis?.itemCount ?? 0,
+            detectedFields: ep.responseAnalysis?.detectedFields ?? {}, authIndicators: ep.authIndicators,
+        })), null, 2)),
+        fs.promises.writeFile(path.join(targetDir, 'capabilities.json'), JSON.stringify(result.capabilities, null, 2)),
+        fs.promises.writeFile(path.join(targetDir, 'auth.json'), JSON.stringify({
+            top_strategy: result.top_strategy, indicators: result.auth_indicators, framework: result.framework,
+        }, null, 2)),
+    ];
+    if (stores.length > 0) {
+        tasks.push(fs.promises.writeFile(path.join(targetDir, 'stores.json'), JSON.stringify(stores, null, 2)));
+    }
+    await Promise.all(tasks);
+}
+// ── Main explore function ──────────────────────────────────────────────────
+export async function exploreUrl(url, opts) {
+    const waitSeconds = opts.waitSeconds ?? 3.0;
+    const exploreTimeout = Math.max(DEFAULT_BROWSER_EXPLORE_TIMEOUT, 45.0 + waitSeconds * 8.0);
+    return browserSession(opts.BrowserFactory, async (page) => {
+        return runWithTimeout((async () => {
+            // Step 1: Navigate
+            await page.goto(url);
+            await page.wait(waitSeconds);
+            // Step 2: Auto-scroll to trigger lazy loading intelligently
+            await page.autoScroll({ times: 3, delayMs: 1500 }).catch(() => { });
+            // Step 2.5: Interactive Fuzzing (if requested)
+            if (opts.auto) {
+                try {
+                    // First: targeted clicks by label (e.g. "字幕", "CC", "评论")
+                    if (opts.clickLabels?.length) {
+                        for (const label of opts.clickLabels) {
+                            const safeLabel = JSON.stringify(label);
+                            await page.evaluate(`
+                 (() => {
+                   const el = [...document.querySelectorAll('button, [role="button"], [role="tab"], a, span')]
+                     .find(e => e.textContent && e.textContent.trim().includes(${safeLabel}));
+                   if (el) el.click();
+                 })()
+               `);
+                            await page.wait(1);
+                        }
+                    }
+                    // Then: blind fuzzing on generic interactive elements
+                    const clicks = await page.evaluate(INTERACT_FUZZ_JS);
+                    await page.wait(2); // wait for XHRs to settle
+                }
+                catch (e) {
+                    log.verbose(`Interactive fuzzing skipped: ${e instanceof Error ? e.message : String(e)}`);
+                }
+            }
+            // Step 3: Read page metadata
+            const metadata = await readPageMetadata(page);
+            // Step 4: Capture network traffic
+            const rawNetwork = await page.networkRequests(false);
+            const networkEntries = parseNetworkRequests(rawNetwork);
+            // Step 5: For JSON endpoints missing a body, carefully re-fetch in-browser via a pristine iframe
+            const jsonEndpoints = networkEntries.filter(e => e.contentType.includes('json') && e.method === 'GET' && e.status === 200 && !e.responseBody);
+            await Promise.allSettled(jsonEndpoints.slice(0, 5).map(async (ep) => {
+                try {
+                    const body = await page.evaluate(`async () => {
+            let iframe = null;
+            try {
+              iframe = document.createElement('iframe');
+              iframe.style.display = 'none';
+              document.body.appendChild(iframe);
+              const cleanFetch = iframe.contentWindow.fetch || window.fetch;
+              const r = await cleanFetch(${JSON.stringify(ep.url)}, { credentials: 'include' });
+              if (!r.ok) return null;
+              const d = await r.json();
+              return JSON.stringify(d).slice(0, 10000);
+            } catch {
+              return null;
+            } finally {
+              if (iframe && iframe.parentNode) iframe.parentNode.removeChild(iframe);
+            }
+          }`);
+                    if (body && typeof body === 'string') {
+                        try {
+                            ep.responseBody = JSON.parse(body);
+                        }
+                        catch { }
+                    }
+                    else if (body && typeof body === 'object')
+                        ep.responseBody = body;
+                }
+                catch { }
+            }));
+            // Step 6: Detect framework
+            let framework = {};
+            try {
+                const fw = await page.evaluate(FRAMEWORK_DETECT_JS);
+                if (isBooleanRecord(fw))
+                    framework = fw;
+            }
+            catch { }
+            // Step 6.5: Discover stores (Pinia / Vuex)
+            let stores = [];
+            if (framework.pinia || framework.vuex) {
+                try {
+                    const raw = await page.evaluate(STORE_DISCOVER_JS);
+                    if (Array.isArray(raw))
+                        stores = raw;
+                }
+                catch { }
+            }
+            // Step 7+8: Analyze endpoints and infer capabilities
+            const { analyzed: analyzedEndpoints, totalCount } = analyzeEndpoints(networkEntries);
+            const { capabilities, topStrategy, authIndicators } = inferCapabilitiesFromEndpoints(analyzedEndpoints, stores, { site: opts.site, goal: opts.goal, url });
+            // Step 9: Assemble result and write artifacts
+            const siteName = opts.site ?? detectSiteName(metadata.url || url);
+            const targetDir = opts.outDir ?? path.join('.opencli', 'explore', siteName);
+            const result = {
+                site: siteName, target_url: url, final_url: metadata.url, title: metadata.title,
+                framework, stores, top_strategy: topStrategy,
+                endpoint_count: totalCount,
+                api_endpoint_count: analyzedEndpoints.length,
+                capabilities, auth_indicators: authIndicators,
+            };
+            await writeExploreArtifacts(targetDir, result, analyzedEndpoints, stores);
+            return { ...result, out_dir: targetDir };
+        })(), { timeout: exploreTimeout, label: `Explore ${url}` });
+    }, { workspace: opts.workspace });
+}
+export function renderExploreSummary(result) {
+    const lines = [
+        'opencli probe: OK', `Site: ${result.site}`, `URL: ${result.target_url}`,
+        `Title: ${result.title || '(none)'}`, `Strategy: ${result.top_strategy}`,
+        `Endpoints: ${result.endpoint_count} total, ${result.api_endpoint_count} API`,
+        `Capabilities: ${result.capabilities?.length ?? 0}`,
+    ];
+    for (const cap of (result.capabilities ?? []).slice(0, 5)) {
+        const storeInfo = cap.storeHint ? ` → ${cap.storeHint.store}.${cap.storeHint.action}()` : '';
+        lines.push(`  • ${cap.name} (${cap.strategy}, ${(cap.confidence * 100).toFixed(0)}%)${storeInfo}`);
+    }
+    const fw = result.framework ?? {};
+    const fwNames = Object.entries(fw).filter(([, v]) => v).map(([k]) => k);
+    if (fwNames.length)
+        lines.push(`Framework: ${fwNames.join(', ')}`);
+    const stores = result.stores ?? [];
+    if (stores.length) {
+        lines.push(`Stores: ${stores.length}`);
+        for (const s of stores.slice(0, 5)) {
+            lines.push(`  • ${s.type}/${s.id}: ${s.actions.slice(0, 5).join(', ')}${s.actions.length > 5 ? '...' : ''}`);
+        }
+    }
+    lines.push(`Output: ${result.out_dir}`);
+    return lines.join('\n');
+}
+async function readPageMetadata(page) {
+    try {
+        const result = await page.evaluate(`() => ({ url: window.location.href, title: document.title || '' })`);
+        if (result && typeof result === 'object' && !Array.isArray(result)) {
+            return {
+                url: String(result.url ?? ''),
+                title: String(result.title ?? ''),
+            };
+        }
+    }
+    catch { }
+    return { url: '', title: '' };
+}

package/dist/src/extension-manifest-regression.test.d.ts

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

package/dist/src/external.test.d.ts

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

package/dist/src/interceptor.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Shared XHR/Fetch interceptor JavaScript generators.
+ *
+ * Provides a single source of truth for monkey-patching browser
+ * fetch() and XMLHttpRequest to capture API responses matching
+ * a URL pattern. Used by:
+ *   - Page.installInterceptor()  (browser.ts)
+ *   - stepIntercept              (pipeline/steps/intercept.ts)
+ *   - stepTap                    (pipeline/steps/tap.ts)
+ */
+/**
+ * Generate JavaScript source that installs a fetch/XHR interceptor.
+ * Captured responses are pushed to `window.__opencli_intercepted`.
+ *
+ * @param patternExpr - JS expression resolving to a URL substring to match (e.g. a JSON.stringify'd string)
+ * @param opts.arrayName - Global array name for captured data (default: '__opencli_intercepted')
+ * @param opts.patchGuard - Global boolean name to prevent double-patching (default: '__opencli_interceptor_patched')
+ */
+export declare function generateInterceptorJs(patternExpr: string, opts?: {
+    arrayName?: string;
+    patchGuard?: string;
+}): string;
+/**
+ * Generate JavaScript source to read and clear intercepted data.
+ */
+export declare function generateReadInterceptedJs(arrayName?: string): string;
+/**
+ * Generate a self-contained tap interceptor for store-action bridge.
+ * Unlike the global interceptor, this one:
+ * - Installs temporarily, restores originals in finally block
+ * - Resolves a promise on first capture (for immediate await)
+ * - Returns captured data directly
+ *
+ * Reuses the shared DISGUISE_FN for consistent toString() disguising.
+ */
+export declare function generateTapInterceptorJs(patternExpr: string): {
+    setupVar: string;
+    capturedVar: string;
+    promiseVar: string;
+    resolveVar: string;
+    fetchPatch: string;
+    xhrPatch: string;
+    restorePatch: string;
+};