@jackwener/opencli 0.1.1 → 0.2.0

package/src/main.ts

@@ -3,6 +3,7 @@
  * opencli — Make any website your CLI. AI-powered.
  */
 
+import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -20,10 +21,14 @@ const __dirname = path.dirname(__filename);
 const BUILTIN_CLIS = path.resolve(__dirname, 'clis');
 const USER_CLIS = path.join(os.homedir(), '.opencli', 'clis');
 
+// Read version from package.json (single source of truth)
+const pkgJsonPath = path.resolve(__dirname, '..', 'package.json');
+const PKG_VERSION = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8')).version ?? '0.0.0';
+
 discoverClis(BUILTIN_CLIS, USER_CLIS);
 
 const program = new Command();
-program.name('opencli').description('Make any website your CLI. Zero setup. AI-powered.').version('0.1.0');
+program.name('opencli').description('Make any website your CLI. Zero setup. AI-powered.').version(PKG_VERSION);
 
 // ── Built-in commands ──────────────────────────────────────────────────────
 
@@ -49,10 +54,7 @@ program.command('validate').description('Validate CLI definitions').argument('[t
 program.command('verify').description('Validate + smoke test').argument('[target]').option('--smoke', 'Run smoke tests', false)
   .action(async (target, opts) => { const { verifyClis, renderVerifyReport } = await import('./verify.js'); const r = await verifyClis({ builtinClis: BUILTIN_CLIS, userClis: USER_CLIS, target, smoke: opts.smoke }); console.log(renderVerifyReport(r)); process.exitCode = r.ok ? 0 : 1; });
 
-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')
+program.command('explore').alias('probe').description('Explore 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')

package/src/output.ts

@@ -1,9 +1,10 @@
 /**
- * Output formatting: table, JSON, Markdown, CSV.
+ * Output formatting: table, JSON, Markdown, CSV, YAML.
  */
 
 import chalk from 'chalk';
 import Table from 'cli-table3';
+import yaml from 'js-yaml';
 
 export interface RenderOptions {
   fmt?: string;
@@ -23,6 +24,7 @@ export function render(data: any, opts: RenderOptions = {}): void {
     case 'json': renderJson(data); break;
     case 'md': case 'markdown': renderMarkdown(data, opts); break;
     case 'csv': renderCsv(data, opts); break;
+    case 'yaml': case 'yml': renderYaml(data); break;
     default: renderTable(data, opts); break;
   }
 }
@@ -32,16 +34,14 @@ function renderTable(data: any, opts: RenderOptions): void {
   if (!rows.length) { console.log(chalk.dim('(no data)')); return; }
   const columns = opts.columns ?? Object.keys(rows[0]);
 
-  const header = columns.map((c, i) => i === 0 ? '#' : capitalize(c));
+  const header = columns.map(c => capitalize(c));
   const table = new Table({
     head: header.map(h => chalk.bold(h)),
     style: { head: [], border: [] },
     wordWrap: true,
     wrapOnWordBoundary: true,
-    colWidths: columns.map((c, i) => {
-      if (i === 0) return 4;
-      if (c === 'url' || c === 'description') return null as any;
-      if (c === 'title' || c === 'name' || c === 'repo') return null as any;
+    colWidths: columns.map((_c, i) => {
+      if (i === 0) return 6;
       return null as any;
     }).filter(() => true),
   });
@@ -91,6 +91,10 @@ function renderCsv(data: any, opts: RenderOptions): void {
   }
 }
 
+function renderYaml(data: any): void {
+  console.log(yaml.dump(data, { sortKeys: false, lineWidth: 120, noRefs: true }));
+}
+
 function capitalize(s: string): string {
   return s.charAt(0).toUpperCase() + s.slice(1);
 }

package/src/pipeline/executor.ts

@@ -0,0 +1,98 @@
+/**
+ * Pipeline executor: runs YAML pipeline steps sequentially.
+ */
+
+import chalk from 'chalk';
+import type { IPage } from '../types.js';
+import { stepNavigate, stepClick, stepType, stepWait, stepPress, stepSnapshot, stepEvaluate } from './steps/browser.js';
+import { stepFetch } from './steps/fetch.js';
+import { stepSelect, stepMap, stepFilter, stepSort, stepLimit } from './steps/transform.js';
+import { stepIntercept } from './steps/intercept.js';
+import { stepTap } from './steps/tap.js';
+
+export interface PipelineContext {
+  args?: Record<string, any>;
+  debug?: boolean;
+}
+
+/** Step handler signature */
+type StepHandler = (page: IPage | null, params: any, data: any, args: Record<string, any>) => Promise<any>;
+
+/** Registry of all available step handlers */
+const STEP_HANDLERS: Record<string, StepHandler> = {
+  navigate: stepNavigate as StepHandler,
+  fetch: stepFetch,
+  select: stepSelect as StepHandler,
+  evaluate: stepEvaluate as StepHandler,
+  snapshot: stepSnapshot as StepHandler,
+  click: stepClick as StepHandler,
+  type: stepType as StepHandler,
+  wait: stepWait as StepHandler,
+  press: stepPress as StepHandler,
+  map: stepMap as StepHandler,
+  filter: stepFilter as StepHandler,
+  sort: stepSort as StepHandler,
+  limit: stepLimit as StepHandler,
+  intercept: stepIntercept as StepHandler,
+  tap: stepTap as StepHandler,
+};
+
+export async function executePipeline(
+  page: IPage | null,
+  pipeline: any[],
+  ctx: PipelineContext = {},
+): Promise<any> {
+  const args = ctx.args ?? {};
+  const debug = ctx.debug ?? false;
+  let data: any = null;
+  const total = pipeline.length;
+
+  for (let i = 0; i < pipeline.length; i++) {
+    const step = pipeline[i];
+    if (!step || typeof step !== 'object') continue;
+    for (const [op, params] of Object.entries(step)) {
+      if (debug) debugStepStart(i + 1, total, op, params);
+
+      const handler = STEP_HANDLERS[op];
+      if (handler) {
+        data = await handler(page, params, data, args);
+      } else {
+        if (debug) process.stderr.write(`  ${chalk.yellow('⚠')}  Unknown step: ${op}\n`);
+      }
+
+      // 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);
+    }
+  }
+  return data;
+}
+
+function debugStepStart(stepNum: number, total: number, op: string, params: any): void {
+  let preview = '';
+  if (typeof params === 'string') {
+    preview = params.length <= 80 ? ` → ${params}` : ` → ${params.slice(0, 77)}...`;
+  } else if (params && typeof params === 'object' && !Array.isArray(params)) {
+    preview = ` (${Object.keys(params).join(', ')})`;
+  }
+  process.stderr.write(`  ${chalk.dim(`[${stepNum}/${total}]`)} ${chalk.bold.cyan(op)}${preview}\n`);
+}
+
+function debugStepResult(op: string, data: any): void {
+  if (data === null || data === undefined) {
+    process.stderr.write(`       ${chalk.dim('→ (no data)')}\n`);
+  } else if (Array.isArray(data)) {
+    process.stderr.write(`       ${chalk.dim(`→ ${data.length} items`)}\n`);
+  } else if (typeof data === 'object') {
+    const keys = Object.keys(data).slice(0, 5);
+    process.stderr.write(`       ${chalk.dim(`→ dict (${keys.join(', ')}${Object.keys(data).length > 5 ? '...' : ''})`)}\n`);
+  } else if (typeof data === 'string') {
+    const p = data.slice(0, 60).replace(/\n/g, '\\n');
+    process.stderr.write(`       ${chalk.dim(`→ "${p}${data.length > 60 ? '...' : ''}"`)}\n`);
+  } else {
+    process.stderr.write(`       ${chalk.dim(`→ ${typeof data}`)}\n`);
+  }
+}

package/src/pipeline/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Pipeline module: re-exports for backward compatibility.
+ */
+
+export { executePipeline, type PipelineContext } from './executor.js';
+export { render, evalExpr, resolvePath, normalizeEvaluateSource, type RenderContext } from './template.js';

package/src/pipeline/steps/browser.ts

@@ -0,0 +1,67 @@
+/**
+ * Pipeline step: navigate, click, type, wait, press, snapshot.
+ * Browser interaction primitives.
+ */
+
+import type { IPage } from '../../types.js';
+import { render, normalizeEvaluateSource } from '../template.js';
+
+export async function stepNavigate(page: IPage, params: any, data: any, args: Record<string, any>): Promise<any> {
+  const url = render(params, { args, data });
+  await page.goto(String(url));
+  return data;
+}
+
+export async function stepClick(page: IPage, params: any, data: any, args: Record<string, any>): Promise<any> {
+  await page.click(String(render(params, { args, data })).replace(/^@/, ''));
+  return data;
+}
+
+export async function stepType(page: IPage, params: any, data: any, args: Record<string, any>): Promise<any> {
+  if (typeof params === 'object' && params) {
+    const ref = String(render(params.ref ?? '', { args, data })).replace(/^@/, '');
+    const text = String(render(params.text ?? '', { args, data }));
+    await page.typeText(ref, text);
+    if (params.submit) await page.pressKey('Enter');
+  }
+  return data;
+}
+
+export async function stepWait(page: IPage, params: any, data: any, args: Record<string, any>): Promise<any> {
+  if (typeof params === 'number') await page.wait(params);
+  else if (typeof params === 'object' && params) {
+    if ('text' in params) {
+      const timeout = params.timeout ?? 10;
+      const start = Date.now();
+      while ((Date.now() - start) / 1000 < timeout) {
+        const snap = await page.snapshot({ raw: true });
+        if (typeof snap === 'string' && snap.includes(params.text)) break;
+        await page.wait(0.5);
+      }
+    } else if ('time' in params) await page.wait(Number(params.time));
+  } else if (typeof params === 'string') await page.wait(Number(render(params, { args, data })));
+  return data;
+}
+
+export async function stepPress(page: IPage, params: any, data: any, args: Record<string, any>): Promise<any> {
+  await page.pressKey(String(render(params, { args, data })));
+  return data;
+}
+
+export async function stepSnapshot(page: IPage, params: any, _data: any, _args: Record<string, any>): Promise<any> {
+  const opts = (typeof params === 'object' && params) ? params : {};
+  return page.snapshot({ interactive: opts.interactive ?? false, compact: opts.compact ?? false, maxDepth: opts.max_depth, raw: opts.raw ?? false });
+}
+
+export async function stepEvaluate(page: IPage, params: any, data: any, args: Record<string, any>): Promise<any> {
+  const js = String(render(params, { args, data }));
+  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;
+}

package/src/pipeline/steps/fetch.ts

@@ -0,0 +1,60 @@
+/**
+ * Pipeline step: fetch — HTTP API requests.
+ */
+
+import type { IPage } from '../../types.js';
+import { render } from '../template.js';
+
+/** Single URL fetch helper */
+async function fetchSingle(
+  page: IPage | null, url: string, method: string,
+  queryParams: Record<string, any>, headers: Record<string, any>,
+  args: Record<string, any>, data: any,
+): Promise<any> {
+  const renderedParams: Record<string, string> = {};
+  for (const [k, v] of Object.entries(queryParams)) renderedParams[k] = String(render(v, { args, data }));
+  const renderedHeaders: Record<string, string> = {};
+  for (const [k, v] of Object.entries(headers)) renderedHeaders[k] = String(render(v, { args, data }));
+
+  let finalUrl = url;
+  if (Object.keys(renderedParams).length > 0) {
+    const qs = new URLSearchParams(renderedParams).toString();
+    finalUrl = `${finalUrl}${finalUrl.includes('?') ? '&' : '?'}${qs}`;
+  }
+
+  if (page === null) {
+    const resp = await fetch(finalUrl, { method: method.toUpperCase(), headers: renderedHeaders });
+    return resp.json();
+  }
+
+  const headersJs = JSON.stringify(renderedHeaders);
+  const escapedUrl = finalUrl.replace(/"/g, '\\"');
+  return page.evaluate(`
+    async () => {
+      const resp = await fetch("${escapedUrl}", {
+        method: "${method}", headers: ${headersJs}, credentials: "include"
+      });
+      return await resp.json();
+    }
+  `);
+}
+
+export async function stepFetch(page: IPage | null, params: any, data: any, args: Record<string, any>): Promise<any> {
+  const urlOrObj = typeof params === 'string' ? params : (params?.url ?? '');
+  const method = params?.method ?? 'GET';
+  const queryParams: Record<string, any> = params?.params ?? {};
+  const headers: Record<string, any> = params?.headers ?? {};
+  const urlTemplate = String(urlOrObj);
+
+  // Per-item fetch when data is array and URL references item
+  if (Array.isArray(data) && urlTemplate.includes('item')) {
+    const results: any[] = [];
+    for (let i = 0; i < data.length; i++) {
+      const itemUrl = String(render(urlTemplate, { args, data, item: data[i], index: i }));
+      results.push(await fetchSingle(page, itemUrl, method, queryParams, headers, args, data));
+    }
+    return results;
+  }
+  const url = render(urlOrObj, { args, data });
+  return fetchSingle(page, String(url), method, queryParams, headers, args, data);
+}

package/src/pipeline/steps/intercept.ts

@@ -0,0 +1,78 @@
+/**
+ * Pipeline step: intercept — declarative XHR interception.
+ */
+
+import type { IPage } from '../../types.js';
+import { render } from '../template.js';
+
+export async function stepIntercept(page: IPage, params: any, data: any, args: Record<string, any>): Promise<any> {
+  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);
+    const { normalizeEvaluateSource } = await import('../template.js');
+    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') {
+    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 [, , url, status] = match;
+        if (url.includes(capturePattern) && status === '200') {
+          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;
+}

package/src/pipeline/steps/tap.ts

@@ -0,0 +1,137 @@
+/**
+ * Pipeline step: tap — declarative Store Action Bridge.
+ *
+ * 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)
+ */
+
+import type { IPage } from '../../types.js';
+import { render } from '../template.js';
+
+export async function stepTap(page: IPage, params: any, data: any, args: Record<string, any>): Promise<any> {
+  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;
+  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);
+          };
+          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)};
+
+        const app = document.querySelector('#app');
+        if (!fw || fw === 'pinia') {
+          try {
+            const pinia = app?.__vue_app__?.config?.globalProperties?.$pinia;
+            if (pinia?._s) store = pinia._s.get(storeName);
+          } catch {}
+        }
+        if (!store && (!fw || fw === 'vuex')) {
+          try {
+            const vuexStore = app?.__vue_app__?.config?.globalProperties?.$store
+              ?? app?.__vue__?.$store;
+            if (vuexStore) {
+              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);
+}

package/src/pipeline/steps/transform.ts

@@ -0,0 +1,50 @@
+/**
+ * Pipeline steps: data transforms — select, map, filter, sort, limit.
+ */
+
+import { render, evalExpr } from '../template.js';
+
+export async function stepSelect(_page: any, params: any, data: any, args: Record<string, any>): Promise<any> {
+  const pathStr = String(render(params, { args, data }));
+  if (data && typeof data === 'object') {
+    let current = data;
+    for (const part of pathStr.split('.')) {
+      if (current && typeof current === 'object' && !Array.isArray(current)) current = (current as any)[part];
+      else if (Array.isArray(current) && /^\d+$/.test(part)) current = current[parseInt(part, 10)];
+      else return null;
+    }
+    return current;
+  }
+  return data;
+}
+
+export async function stepMap(_page: any, params: any, data: any, args: Record<string, any>): Promise<any> {
+  if (!data || typeof data !== 'object') return data;
+  let items: any[] = Array.isArray(data) ? data : [data];
+  if (!Array.isArray(data) && typeof data === 'object' && 'data' in data) items = data.data;
+  const result: any[] = [];
+  for (let i = 0; i < items.length; i++) {
+    const item = items[i];
+    const row: Record<string, any> = {};
+    for (const [key, template] of Object.entries(params)) row[key] = render(template, { args, data, item, index: i });
+    result.push(row);
+  }
+  return result;
+}
+
+export async function stepFilter(_page: any, params: any, data: any, args: Record<string, any>): Promise<any> {
+  if (!Array.isArray(data)) return data;
+  return data.filter((item, i) => evalExpr(String(params), { args, item, index: i }));
+}
+
+export async function stepSort(_page: any, params: any, data: any, _args: Record<string, any>): Promise<any> {
+  if (!Array.isArray(data)) return data;
+  const key = typeof params === 'object' ? (params.by ?? '') : String(params);
+  const reverse = typeof params === 'object' ? params.order === 'desc' : false;
+  return [...data].sort((a, b) => { const va = a[key] ?? ''; const vb = b[key] ?? ''; const cmp = va < vb ? -1 : va > vb ? 1 : 0; return reverse ? -cmp : cmp; });
+}
+
+export async function stepLimit(_page: any, params: any, data: any, args: Record<string, any>): Promise<any> {
+  if (!Array.isArray(data)) return data;
+  return data.slice(0, Number(render(params, { args, data })));
+}