@jackwener/opencli 0.1.0 → 0.1.1

package/src/main.ts

@@ -52,12 +52,26 @@ program.command('verify').description('Validate + smoke test').argument('[target
 program.command('explore').description('Explore a website').argument('<url>').option('--site <name>').option('--goal <text>').option('--wait <s>', '', '3')
   .action(async (url, opts) => { const { exploreUrl, renderExploreSummary } = await import('./explore.js'); console.log(renderExploreSummary(await exploreUrl(url, { BrowserFactory: PlaywrightMCP, site: opts.site, goal: opts.goal, waitSeconds: parseFloat(opts.wait) }))); });
 
+program.command('probe').description('Probe a website: discover APIs, stores, and recommend strategies').argument('<url>').option('--site <name>').option('--goal <text>').option('--wait <s>', '', '3')
+  .action(async (url, opts) => { const { exploreUrl, renderExploreSummary } = await import('./explore.js'); console.log(renderExploreSummary(await exploreUrl(url, { BrowserFactory: PlaywrightMCP, site: opts.site, goal: opts.goal, waitSeconds: parseFloat(opts.wait) }))); });
+
 program.command('synthesize').description('Synthesize CLIs from explore').argument('<target>').option('--top <n>', '', '3')
   .action(async (target, opts) => { const { synthesizeFromExplore, renderSynthesizeSummary } = await import('./synthesize.js'); console.log(renderSynthesizeSummary(synthesizeFromExplore(target, { top: parseInt(opts.top) }))); });
 
 program.command('generate').description('One-shot: explore → synthesize → register').argument('<url>').option('--goal <text>').option('--site <name>')
   .action(async (url, opts) => { const { generateCliFromUrl, renderGenerateSummary } = await import('./generate.js'); const r = await generateCliFromUrl({ url, BrowserFactory: PlaywrightMCP, builtinClis: BUILTIN_CLIS, userClis: USER_CLIS, goal: opts.goal, site: opts.site }); console.log(renderGenerateSummary(r)); process.exitCode = r.ok ? 0 : 1; });
 
+program.command('cascade').description('Strategy cascade: find simplest working strategy').argument('<url>').option('--site <name>')
+  .action(async (url, opts) => {
+    const { cascadeProbe, renderCascadeResult } = await import('./cascade.js');
+    const result = await browserSession(PlaywrightMCP, async (page) => {
+      // Navigate to the site first for cookie context
+      try { const siteUrl = new URL(url); await page.goto(`${siteUrl.protocol}//${siteUrl.host}`); await page.wait(2); } catch {}
+      return cascadeProbe(page, url);
+    });
+    console.log(renderCascadeResult(result));
+  });
+
 // ── Dynamic site commands ──────────────────────────────────────────────────
 
 const registry = getRegistry();

package/src/pipeline.ts

@@ -26,6 +26,11 @@ export async function executePipeline(
     for (const [op, params] of Object.entries(step)) {
       if (debug) debugStepStart(i + 1, total, op, params);
       data = await executeStep(page, op, params, data, args);
+      // Detect error objects returned by steps (e.g. tap store not found)
+      if (data && typeof data === 'object' && !Array.isArray(data) && data.error) {
+        process.stderr.write(`  ${chalk.yellow('⚠')}  ${chalk.yellow(op)}: ${data.error}\n`);
+        if (data.hint) process.stderr.write(`  ${chalk.dim('💡')} ${chalk.dim(data.hint)}\n`);
+      }
       if (debug) debugStepResult(op, data);
     }
   }
@@ -143,7 +148,15 @@ async function executeStep(page: any, op: string, params: any, data: any, args:
     }
     case 'evaluate': {
       const js = String(render(params, { args, data }));
-      return page.evaluate(normalizeEvaluateSource(js));
+      let result = await page.evaluate(normalizeEvaluateSource(js));
+      // MCP may return JSON as a string — auto-parse it
+      if (typeof result === 'string') {
+        const trimmed = result.trim();
+        if ((trimmed.startsWith('[') && trimmed.endsWith(']')) || (trimmed.startsWith('{') && trimmed.endsWith('}'))) {
+          try { result = JSON.parse(trimmed); } catch {}
+        }
+      }
+      return result;
     }
     case 'snapshot': {
       const opts = (typeof params === 'object' && params) ? params : {};
@@ -208,7 +221,231 @@ async function executeStep(page: any, op: string, params: any, data: any, args:
       if (!Array.isArray(data)) return data;
       return data.slice(0, Number(render(params, { args, data })));
     }
-    case 'intercept': return data;
+    case 'intercept': {
+      // Declarative XHR interception step
+      // Usage:
+      //   intercept:
+      //     trigger: "navigate:https://..." | "evaluate:store.note.fetch()" | "click:ref"
+      //     capture: "api/pattern"     # URL substring to match
+      //     timeout: 5                 # seconds to wait for matching request
+      //     select: "data.items"       # optional: extract sub-path from response
+      const cfg = typeof params === 'object' ? params : {};
+      const trigger = cfg.trigger ?? '';
+      const capturePattern = cfg.capture ?? '';
+      const timeout = cfg.timeout ?? 8;
+      const selectPath = cfg.select ?? null;
+
+      if (!capturePattern) return data;
+
+      // Step 1: Execute the trigger action
+      if (trigger.startsWith('navigate:')) {
+        const url = render(trigger.slice('navigate:'.length), { args, data });
+        await page.goto(String(url));
+      } else if (trigger.startsWith('evaluate:')) {
+        const js = trigger.slice('evaluate:'.length);
+        await page.evaluate(normalizeEvaluateSource(render(js, { args, data }) as string));
+      } else if (trigger.startsWith('click:')) {
+        const ref = render(trigger.slice('click:'.length), { args, data });
+        await page.click(String(ref).replace(/^@/, ''));
+      } else if (trigger === 'scroll') {
+        await page.scroll('down');
+      }
+
+      // Step 2: Wait a bit for network requests to fire
+      await page.wait(Math.min(timeout, 3));
+
+      // Step 3: Get network requests and find matching ones
+      const rawNetwork = await page.networkRequests(false);
+      const matchingResponses: any[] = [];
+
+      if (typeof rawNetwork === 'string') {
+        // Parse the network output to find matching URLs
+        const lines = rawNetwork.split('\n');
+        for (const line of lines) {
+          const match = line.match(/\[?(GET|POST)\]?\s+(\S+)\s*(?:=>|→)\s*\[?(\d+)\]?/i);
+          if (match) {
+            const [, method, url, status] = match;
+            if (url.includes(capturePattern) && status === '200') {
+              // Re-fetch the matching URL to get the response body
+              try {
+                const body = await page.evaluate(`
+                  async () => {
+                    try {
+                      const resp = await fetch(${JSON.stringify(url)}, { credentials: 'include' });
+                      if (!resp.ok) return null;
+                      return await resp.json();
+                    } catch { return null; }
+                  }
+                `);
+                if (body) matchingResponses.push(body);
+              } catch {}
+            }
+          }
+        }
+      }
+
+      // Step 4: Select from response if specified
+      let result = matchingResponses.length === 1 ? matchingResponses[0] :
+                   matchingResponses.length > 1 ? matchingResponses : data;
+
+      if (selectPath && result) {
+        let current = result;
+        for (const part of String(selectPath).split('.')) {
+          if (current && typeof current === 'object' && !Array.isArray(current)) {
+            current = current[part];
+          } else break;
+        }
+        result = current ?? result;
+      }
+
+      return result;
+    }
+    case 'tap': {
+      // ── Declarative Store Action Bridge ──────────────────────────────────
+      // Usage:
+      //   tap:
+      //     store: feed                 # Pinia/Vuex store name
+      //     action: fetchFeeds          # Store action to call
+      //     args: []                    # Optional args to pass to action
+      //     capture: homefeed           # URL pattern to capture response
+      //     timeout: 5                  # Seconds to wait for network (default: 5)
+      //     select: data.items          # Optional: extract sub-path from response
+      //     framework: pinia            # Optional: pinia | vuex (auto-detected if omitted)
+      //
+      // Generates a self-contained IIFE that:
+      // 1. Injects fetch + XHR dual interception proxy
+      // 2. Finds the Pinia/Vuex store and calls the action
+      // 3. Captures the response matching the URL pattern
+      // 4. Auto-cleans up interception in finally block
+      // 5. Returns the captured data (optionally sub-selected)
+
+      const cfg = typeof params === 'object' ? params : {};
+      const storeName = String(render(cfg.store ?? '', { args, data }));
+      const actionName = String(render(cfg.action ?? '', { args, data }));
+      const capturePattern = String(render(cfg.capture ?? '', { args, data }));
+      const timeout = cfg.timeout ?? 5;
+      const selectPath = cfg.select ? String(render(cfg.select, { args, data })) : null;
+      const framework = cfg.framework ?? null; // auto-detect if null
+      const actionArgs = cfg.args ?? [];
+
+      if (!storeName || !actionName) throw new Error('tap: store and action are required');
+
+      // Build select chain for the captured response
+      const selectChain = selectPath
+        ? selectPath.split('.').map((p: string) => `?.[${JSON.stringify(p)}]`).join('')
+        : '';
+
+      // Serialize action arguments
+      const actionArgsRendered = actionArgs.map((a: any) => {
+        const rendered = render(a, { args, data });
+        return JSON.stringify(rendered);
+      });
+      const actionCall = actionArgsRendered.length
+        ? `store[${JSON.stringify(actionName)}](${actionArgsRendered.join(', ')})`
+        : `store[${JSON.stringify(actionName)}]()`;
+
+      const js = `
+        async () => {
+          // ── 1. Setup capture proxy (fetch + XHR dual interception) ──
+          let captured = null;
+          const capturePattern = ${JSON.stringify(capturePattern)};
+
+          // Intercept fetch API
+          const origFetch = window.fetch;
+          window.fetch = async function(...fetchArgs) {
+            const resp = await origFetch.apply(this, fetchArgs);
+            try {
+              const url = typeof fetchArgs[0] === 'string' ? fetchArgs[0]
+                : fetchArgs[0] instanceof Request ? fetchArgs[0].url : String(fetchArgs[0]);
+              if (capturePattern && url.includes(capturePattern) && !captured) {
+                try { captured = await resp.clone().json(); } catch {}
+              }
+            } catch {}
+            return resp;
+          };
+
+          // Intercept XMLHttpRequest
+          const origXhrOpen = XMLHttpRequest.prototype.open;
+          const origXhrSend = XMLHttpRequest.prototype.send;
+          XMLHttpRequest.prototype.open = function(method, url) {
+            this.__tapUrl = String(url);
+            return origXhrOpen.apply(this, arguments);
+          };
+          XMLHttpRequest.prototype.send = function(body) {
+            if (capturePattern && this.__tapUrl?.includes(capturePattern)) {
+              const xhr = this;
+              const origHandler = xhr.onreadystatechange;
+              xhr.onreadystatechange = function() {
+                if (xhr.readyState === 4 && !captured) {
+                  try { captured = JSON.parse(xhr.responseText); } catch {}
+                }
+                if (origHandler) origHandler.apply(this, arguments);
+              };
+              // Also handle onload
+              const origOnload = xhr.onload;
+              xhr.onload = function() {
+                if (!captured) { try { captured = JSON.parse(xhr.responseText); } catch {} }
+                if (origOnload) origOnload.apply(this, arguments);
+              };
+            }
+            return origXhrSend.apply(this, arguments);
+          };
+
+          try {
+            // ── 2. Find store ──
+            let store = null;
+            const storeName = ${JSON.stringify(storeName)};
+            const fw = ${JSON.stringify(framework)};
+
+            // Auto-detect framework if not specified
+            const app = document.querySelector('#app');
+            if (!fw || fw === 'pinia') {
+              // Try Pinia (Vue 3)
+              try {
+                const pinia = app?.__vue_app__?.config?.globalProperties?.$pinia;
+                if (pinia?._s) store = pinia._s.get(storeName);
+              } catch {}
+            }
+            if (!store && (!fw || fw === 'vuex')) {
+              // Try Vuex (Vue 2/3)
+              try {
+                const vuexStore = app?.__vue_app__?.config?.globalProperties?.$store
+                  ?? app?.__vue__?.$store;
+                if (vuexStore) {
+                  // Vuex doesn't have named stores like Pinia, dispatch action
+                  store = { [${JSON.stringify(actionName)}]: (...a) => vuexStore.dispatch(storeName + '/' + ${JSON.stringify(actionName)}, ...a) };
+                }
+              } catch {}
+            }
+
+            if (!store) return { error: 'Store not found: ' + storeName, hint: 'Page may not be fully loaded or store name may be incorrect' };
+            if (typeof store[${JSON.stringify(actionName)}] !== 'function') {
+              return { error: 'Action not found: ' + ${JSON.stringify(actionName)} + ' on store ' + storeName,
+                hint: 'Available: ' + Object.keys(store).filter(k => typeof store[k] === 'function' && !k.startsWith('$') && !k.startsWith('_')).join(', ') };
+            }
+
+            // ── 3. Call store action ──
+            await ${actionCall};
+
+            // ── 4. Wait for network response ──
+            const deadline = Date.now() + ${timeout} * 1000;
+            while (!captured && Date.now() < deadline) {
+              await new Promise(r => setTimeout(r, 200));
+            }
+          } finally {
+            // ── 5. Always restore originals ──
+            window.fetch = origFetch;
+            XMLHttpRequest.prototype.open = origXhrOpen;
+            XMLHttpRequest.prototype.send = origXhrSend;
+          }
+
+          if (!captured) return { error: 'No matching response captured for pattern: ' + capturePattern };
+          return captured${selectChain} ?? captured;
+        }
+      `;
+
+      return page.evaluate(js);
+    }
     default: return data;
   }
 }

package/src/synthesize.ts

@@ -1,167 +1,185 @@
 /**
- * Synthesize: turn explore capabilities into ready-to-use CLI definitions.
- *
- * Takes the structured capabilities from Deep Explore and generates
- * YAML pipeline files that can be directly registered as CLI commands.
- *
- * This is the bridge between discovery (explore) and usability (CLI).
+ * Synthesize candidate CLIs from explore artifacts.
+ * Generates evaluate-based YAML pipelines (matching hand-written adapter patterns).
  */
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import yaml from 'js-yaml';
 
-export function synthesizeFromExplore(target: string, opts: any = {}): any {
-  const exploreDir = fs.existsSync(target) ? target : path.join('.opencli', 'explore', target);
-  if (!fs.existsSync(exploreDir)) throw new Error(`Explore dir not found: ${target}`);
+/** Volatile params to strip from generated URLs */
+const VOLATILE_PARAMS = new Set(['w_rid', 'wts', 'callback', '_', 'timestamp', 't', 'nonce', 'sign']);
+const SEARCH_PARAM_NAMES = new Set(['q', 'query', 'keyword', 'search', 'wd', 'kw', 'w', 'search_query']);
+const LIMIT_PARAM_NAMES = new Set(['ps', 'page_size', 'limit', 'count', 'per_page', 'size', 'num']);
+const PAGE_PARAM_NAMES = new Set(['pn', 'page', 'page_num', 'offset', 'cursor']);
 
-  const manifest = JSON.parse(fs.readFileSync(path.join(exploreDir, 'manifest.json'), 'utf-8'));
-  const capabilities = JSON.parse(fs.readFileSync(path.join(exploreDir, 'capabilities.json'), 'utf-8'));
-  const endpoints = JSON.parse(fs.readFileSync(path.join(exploreDir, 'endpoints.json'), 'utf-8'));
-  const auth = JSON.parse(fs.readFileSync(path.join(exploreDir, 'auth.json'), 'utf-8'));
+export function synthesizeFromExplore(
+  target: string,
+  opts: { outDir?: string; top?: number } = {},
+): Record<string, any> {
+  const exploreDir = resolveExploreDir(target);
+  const bundle = loadExploreBundle(exploreDir);
 
   const targetDir = opts.outDir ?? path.join(exploreDir, 'candidates');
   fs.mkdirSync(targetDir, { recursive: true });
 
-  const site = manifest.site;
-  const topN = opts.top ?? 5;
-  const candidates: any[] = [];
-
-  // Sort capabilities by confidence
-  const sortedCaps = [...capabilities]
+  const site = bundle.manifest.site;
+  const capabilities = (bundle.capabilities ?? [])
     .sort((a: any, b: any) => (b.confidence ?? 0) - (a.confidence ?? 0))
-    .slice(0, topN);
-
-  for (const cap of sortedCaps) {
-    // Find the matching endpoint for more detail
-    const endpoint = endpoints.find((ep: any) => ep.pattern === cap.endpoint) ??
-                     endpoints[0];
+    .slice(0, opts.top ?? 3);
+  const candidates: any[] = [];
 
-    const candidate = buildCandidateYaml(site, manifest, cap, endpoint);
-    const fileName = `${cap.name}.yaml`;
-    const filePath = path.join(targetDir, fileName);
+  for (const cap of capabilities) {
+    const endpoint = chooseEndpoint(cap, bundle.endpoints);
+    if (!endpoint) continue;
+    const candidate = buildCandidateYaml(site, bundle.manifest, cap, endpoint);
+    const filePath = path.join(targetDir, `${candidate.name}.yaml`);
     fs.writeFileSync(filePath, yaml.dump(candidate.yaml, { sortKeys: false, lineWidth: 120 }));
-
-    candidates.push({
-      name: cap.name,
-      path: filePath,
-      strategy: cap.strategy,
-      endpoint: cap.endpoint,
-      confidence: cap.confidence,
-      columns: candidate.yaml.columns,
-    });
+    candidates.push({ name: candidate.name, path: filePath, strategy: cap.strategy, confidence: cap.confidence });
   }
 
-  const index = {
-    site,
-    target_url: manifest.target_url,
-    generated_from: exploreDir,
-    candidate_count: candidates.length,
-    candidates,
-  };
+  const index = { site, target_url: bundle.manifest.target_url, generated_from: exploreDir, candidate_count: candidates.length, candidates };
   fs.writeFileSync(path.join(targetDir, 'candidates.json'), JSON.stringify(index, null, 2));
 
+  return { site, explore_dir: exploreDir, out_dir: targetDir, candidate_count: candidates.length, candidates };
+}
+
+export function renderSynthesizeSummary(result: Record<string, any>): string {
+  const lines = ['opencli synthesize: OK', `Site: ${result.site}`, `Source: ${result.explore_dir}`, `Candidates: ${result.candidate_count}`];
+  for (const c of result.candidates ?? []) lines.push(`  • ${c.name} (${c.strategy}, ${((c.confidence ?? 0) * 100).toFixed(0)}% confidence) → ${c.path}`);
+  return lines.join('\n');
+}
+
+export function resolveExploreDir(target: string): string {
+  if (fs.existsSync(target)) return target;
+  const candidate = path.join('.opencli', 'explore', target);
+  if (fs.existsSync(candidate)) return candidate;
+  throw new Error(`Explore directory not found: ${target}`);
+}
+
+export function loadExploreBundle(exploreDir: string): Record<string, any> {
   return {
-    site,
-    explore_dir: exploreDir,
-    out_dir: targetDir,
-    candidate_count: candidates.length,
-    candidates,
+    manifest: JSON.parse(fs.readFileSync(path.join(exploreDir, 'manifest.json'), 'utf-8')),
+    endpoints: JSON.parse(fs.readFileSync(path.join(exploreDir, 'endpoints.json'), 'utf-8')),
+    capabilities: JSON.parse(fs.readFileSync(path.join(exploreDir, 'capabilities.json'), 'utf-8')),
+    auth: JSON.parse(fs.readFileSync(path.join(exploreDir, 'auth.json'), 'utf-8')),
   };
 }
 
-/** Volatile params to strip from generated URLs */
-const VOLATILE_PARAMS = new Set(['w_rid', 'wts', 'callback', '_', 'timestamp', 't', 'nonce', 'sign']);
-const SEARCH_PARAM_NAMES = new Set(['q', 'query', 'keyword', 'search', 'wd', 'kw', 'w', 'search_query']);
-const LIMIT_PARAM_NAMES = new Set(['ps', 'page_size', 'limit', 'count', 'per_page', 'size', 'num']);
-const PAGE_PARAM_NAMES = new Set(['pn', 'page', 'page_num', 'offset', 'cursor']);
+function chooseEndpoint(cap: any, endpoints: any[]): any | null {
+  if (!endpoints.length) return null;
+  // Match by endpoint pattern from capability
+  if (cap.endpoint) {
+    const match = endpoints.find((e: any) => e.pattern === cap.endpoint || e.url?.includes(cap.endpoint));
+    if (match) return match;
+  }
+  return endpoints.sort((a: any, b: any) => (b.score ?? 0) - (a.score ?? 0))[0];
+}
 
-/**
- * Build a clean templated URL from a raw API URL.
- * - Strips volatile params (w_rid, wts, etc.)
- * - Templates search, limit, and pagination params
- * - Builds URL string manually to avoid URL encoding of ${{ }} expressions
- */
-function buildTemplatedUrl(rawUrl: string, cap: any, endpoint: any): string {
+// ── URL templating ─────────────────────────────────────────────────────────
+
+function buildTemplatedUrl(rawUrl: string, cap: any, _endpoint: any): string {
   try {
     const u = new URL(rawUrl);
     const base = `${u.protocol}//${u.host}${u.pathname}`;
     const params: Array<[string, string]> = [];
-
     const hasKeyword = cap.recommendedArgs?.some((a: any) => a.name === 'keyword');
 
     u.searchParams.forEach((v, k) => {
-      // Skip volatile params
       if (VOLATILE_PARAMS.has(k)) return;
-
-      // Template known param types
-      if (hasKeyword && SEARCH_PARAM_NAMES.has(k)) {
-        params.push([k, '${{ args.keyword }}']);
-      } else if (LIMIT_PARAM_NAMES.has(k)) {
-        params.push([k, '${{ args.limit | default(20) }}']);
-      } else if (PAGE_PARAM_NAMES.has(k)) {
-        params.push([k, '${{ args.page | default(1) }}']);
-      } else {
-        params.push([k, v]);
-      }
+      if (hasKeyword && SEARCH_PARAM_NAMES.has(k)) params.push([k, '${{ args.keyword }}']);
+      else if (LIMIT_PARAM_NAMES.has(k)) params.push([k, '${{ args.limit | default(20) }}']);
+      else if (PAGE_PARAM_NAMES.has(k)) params.push([k, '${{ args.page | default(1) }}']);
+      else params.push([k, v]);
     });
 
-    if (params.length === 0) return base;
-    return base + '?' + params.map(([k, v]) => `${k}=${v}`).join('&');
-  } catch {
-    return rawUrl;
-  }
+    return params.length ? base + '?' + params.map(([k, v]) => `${k}=${v}`).join('&') : base;
+  } catch { return rawUrl; }
 }
 
 /**
- * Build a YAML pipeline definition from a capability + endpoint.
+ * Build inline evaluate script for browser-based fetch+parse.
+ * Follows patterns from bilibili/hot.yaml and twitter/trending.yaml.
  */
+function buildEvaluateScript(url: string, itemPath: string, endpoint: any): string {
+  const pathChain = itemPath.split('.').map((p: string) => `?.${p}`).join('');
+  const detectedFields = endpoint?.detectedFields ?? {};
+  const hasFields = Object.keys(detectedFields).length > 0;
+
+  let mapCode = '';
+  if (hasFields) {
+    const mappings = Object.entries(detectedFields)
+      .map(([role, field]) => `      ${role}: item${String(field).split('.').map(p => `?.${p}`).join('')}`)
+      .join(',\n');
+    mapCode = `.map((item) => ({\n${mappings}\n    }))`;
+  }
+
+  return [
+    '(async () => {',
+    `  const res = await fetch('${url}', {`,
+    `    credentials: 'include'`,
+    '  });',
+    '  const data = await res.json();',
+    `  return (data${pathChain} || [])${mapCode};`,
+    '})()\n',
+  ].join('\n');
+}
+
+// ── YAML pipeline generation ───────────────────────────────────────────────
+
 function buildCandidateYaml(site: string, manifest: any, cap: any, endpoint: any): { name: string; yaml: any } {
   const needsBrowser = cap.strategy !== 'public';
   const pipeline: any[] = [];
+  const templatedUrl = buildTemplatedUrl(endpoint?.url ?? manifest.target_url, cap, endpoint);
 
-  // Step 1: Navigate (if browser-based)
-  if (needsBrowser) {
-    pipeline.push({ navigate: manifest.target_url });
-  }
+  let domain = '';
+  try { domain = new URL(manifest.target_url).hostname; } catch {}
 
-  // Step 2: Fetch the API — build a clean URL with templates
-  const rawUrl = endpoint?.url ?? manifest.target_url;
-  const fetchStep: any = { url: buildTemplatedUrl(rawUrl, cap, endpoint) };
-
-  pipeline.push({ fetch: fetchStep });
-
-  // Step 3: Select the item path
-  if (cap.itemPath) {
-    pipeline.push({ select: cap.itemPath });
+  if (cap.strategy === 'store-action' && cap.storeHint) {
+    // Store Action: navigate + wait + tap (declarative, clean)
+    pipeline.push({ navigate: manifest.target_url });
+    pipeline.push({ wait: 3 });
+    const tapStep: Record<string, any> = {
+      store: cap.storeHint.store,
+      action: cap.storeHint.action,
+      timeout: 8,
+    };
+    // Infer capture pattern from endpoint URL
+    if (endpoint?.url) {
+      try {
+        const epUrl = new URL(endpoint.url);
+        const pathParts = epUrl.pathname.split('/').filter((p: string) => p);
+        // Use last meaningful path segment as capture pattern
+        const capturePart = pathParts.filter((p: string) => !p.match(/^v\d+$/)).pop();
+        if (capturePart) tapStep.capture = capturePart;
+      } catch {}
+    }
+    if (cap.itemPath) tapStep.select = cap.itemPath;
+    pipeline.push({ tap: tapStep });
+  } else if (needsBrowser) {
+    // Browser-based: navigate + evaluate (like bilibili/hot.yaml, twitter/trending.yaml)
+    pipeline.push({ navigate: manifest.target_url });
+    const itemPath = cap.itemPath ?? 'data.data.list';
+    pipeline.push({ evaluate: buildEvaluateScript(templatedUrl, itemPath, endpoint) });
+  } else {
+    // Public API: direct fetch (like hackernews/top.yaml)
+    pipeline.push({ fetch: { url: templatedUrl } });
+    if (cap.itemPath) pipeline.push({ select: cap.itemPath });
   }
 
-  // Step 4: Map fields to columns
+  // Map fields
   const mapStep: Record<string, string> = {};
   const columns = cap.recommendedColumns ?? ['title', 'url'];
-
-  // Add a rank column if not doing search
-  if (!cap.recommendedArgs?.some((a: any) => a.name === 'keyword')) {
-    mapStep['rank'] = '${{ index + 1 }}';
-  }
-
-  // Build field mappings from the endpoint's detected fields
+  if (!cap.recommendedArgs?.some((a: any) => a.name === 'keyword')) mapStep['rank'] = '${{ index + 1 }}';
   const detectedFields = endpoint?.detectedFields ?? {};
   for (const col of columns) {
     const fieldPath = detectedFields[col];
-    if (fieldPath) {
-      mapStep[col] = `\${{ item.${fieldPath} }}`;
-    } else {
-      mapStep[col] = `\${{ item.${col} }}`;
-    }
+    mapStep[col] = fieldPath ? `\${{ item.${fieldPath} }}` : `\${{ item.${col} }}`;
   }
-
   pipeline.push({ map: mapStep });
-
-  // Step 5: Limit
   pipeline.push({ limit: '${{ args.limit | default(20) }}' });
 
-  // Build args definition
+  // Args
   const argsDef: Record<string, any> = {};
   for (const arg of cap.recommendedArgs ?? []) {
     const def: any = { type: arg.type ?? 'str' };
@@ -172,39 +190,26 @@ function buildCandidateYaml(site: string, manifest: any, cap: any, endpoint: any
     else if (arg.name === 'page') def.description = 'Page number';
     argsDef[arg.name] = def;
   }
-
-  // Ensure limit arg always exists
-  if (!argsDef['limit']) {
-    argsDef['limit'] = { type: 'int', default: 20, description: 'Number of items to return' };
-  }
-
-  const allColumns = Object.keys(mapStep);
+  if (!argsDef['limit']) argsDef['limit'] = { type: 'int', default: 20, description: 'Number of items to return' };
 
   return {
     name: cap.name,
     yaml: {
-      site,
-      name: cap.name,
-      description: `${site} ${cap.name} (auto-generated)`,
-      domain: manifest.final_url ? new URL(manifest.final_url).hostname : undefined,
-      strategy: cap.strategy,
-      browser: needsBrowser,
-      args: argsDef,
-      pipeline,
-      columns: allColumns,
+      site, name: cap.name, description: `${cap.description || site + ' ' + cap.name} (auto-generated)`,
+      domain, strategy: cap.strategy, browser: needsBrowser,
+      args: argsDef, pipeline, columns: Object.keys(mapStep),
     },
   };
 }
 
-export function renderSynthesizeSummary(r: any): string {
-  const lines = [
-    'opencli synthesize: OK',
-    `Site: ${r.site}`,
-    `Source: ${r.explore_dir}`,
-    `Candidates: ${r.candidate_count}`,
-  ];
-  for (const c of r.candidates ?? []) {
-    lines.push(`  • ${c.name} (${c.strategy}, ${(c.confidence * 100).toFixed(0)}% confidence) → ${c.path}`);
-  }
-  return lines.join('\n');
+/** Backward-compatible export for scaffold.ts */
+export function buildCandidate(site: string, targetUrl: string, cap: any, endpoint: any): any {
+  // Map old-style field names to new ones
+  const normalizedCap = {
+    ...cap,
+    recommendedArgs: cap.recommendedArgs ?? cap.recommended_args,
+    recommendedColumns: cap.recommendedColumns ?? cap.recommended_columns,
+  };
+  const manifest = { target_url: targetUrl, final_url: targetUrl };
+  return buildCandidateYaml(site, manifest, normalizedCap, endpoint);
 }