refactor: type pipeline core (#217)

Author: jackwener

src/pipeline/executor.ts

@@ -8,18 +8,18 @@ import { getStep, type StepHandler } from './registry.js';
 import { log } from '../logger.js';
 
 export interface PipelineContext {
-  args?: Record<string, any>;
+  args?: Record<string, unknown>;
   debug?: boolean;
 }
 
 export async function executePipeline(
   page: IPage | null,
-  pipeline: any[],
+  pipeline: unknown[],
   ctx: PipelineContext = {},
-): Promise<any> {
+): Promise<unknown> {
   const args = ctx.args ?? {};
   const debug = ctx.debug ?? false;
-  let data: any = null;
+  let data: unknown = null;
   const total = pipeline.length;
 
   for (let i = 0; i < pipeline.length; i++) {
@@ -41,7 +41,7 @@ export async function executePipeline(
   return data;
 }
 
-function debugStepStart(stepNum: number, total: number, op: string, params: any): void {
+function debugStepStart(stepNum: number, total: number, op: string, params: unknown): void {
   let preview = '';
   if (typeof params === 'string') {
     preview = params.length <= 80 ? ` → ${params}` : ` → ${params.slice(0, 77)}...`;
@@ -51,7 +51,7 @@ function debugStepStart(stepNum: number, total: number, op: string, params: any)
   log.step(stepNum, total, op, preview);
 }
 
-function debugStepResult(op: string, data: any): void {
+function debugStepResult(op: string, data: unknown): void {
   if (data === null || data === undefined) {
     log.stepResult('(no data)');
   } else if (Array.isArray(data)) {

src/pipeline/registry.ts

@@ -18,11 +18,11 @@ import { stepDownload } from './steps/download.js';
  * TData is the type of the `data` state flowing into the step.
  * TResult is the expected return type.
  */
-export type StepHandler<TData = any, TResult = any> = (
+export type StepHandler<TData = unknown, TResult = unknown, TParams = unknown> = (
   page: IPage | null,
-  params: any,
+  params: TParams,
   data: TData,
-  args: Record<string, any>
+  args: Record<string, unknown>
 ) => Promise<TResult>;
 
 const _stepRegistry = new Map<string, StepHandler>();

src/pipeline/steps/browser.ts

@@ -6,24 +6,28 @@
 import type { IPage } from '../../types.js';
 import { render } from '../template.js';
 
-export async function stepNavigate(page: IPage | null, params: any, data: any, args: Record<string, any>): Promise<any> {
-  if (typeof params === 'object' && params && 'url' in params) {
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+export async function stepNavigate(page: IPage | null, params: unknown, data: unknown, args: Record<string, unknown>): Promise<unknown> {
+  if (isRecord(params) && 'url' in params) {
     const url = String(render(params.url, { args, data }));
-    await page!.goto(url, { waitUntil: params.waitUntil, settleMs: params.settleMs });
+    await page!.goto(url, { waitUntil: params.waitUntil as 'load' | 'none' | undefined, settleMs: typeof params.settleMs === 'number' ? params.settleMs : undefined });
   } else {
     const url = render(params, { args, data });
     await page!.goto(String(url));
   }
   return data;
 }
 
-export async function stepClick(page: IPage | null, params: any, data: any, args: Record<string, any>): Promise<any> {
+export async function stepClick(page: IPage | null, params: unknown, data: unknown, args: Record<string, unknown>): Promise<unknown> {
   await page!.click(String(render(params, { args, data })).replace(/^@/, ''));
   return data;
 }
 
-export async function stepType(page: IPage | null, params: any, data: any, args: Record<string, any>): Promise<any> {
-  if (typeof params === 'object' && params) {
+export async function stepType(page: IPage | null, params: unknown, data: unknown, args: Record<string, unknown>): Promise<unknown> {
+  if (isRecord(params)) {
     const ref = String(render(params.ref ?? '', { args, data })).replace(/^@/, '');
     const text = String(render(params.text ?? '', { args, data }));
     await page!.typeText(ref, text);
@@ -32,32 +36,37 @@ export async function stepType(page: IPage | null, params: any, data: any, args:
   return data;
 }
 
-export async function stepWait(page: IPage | null, params: any, data: any, args: Record<string, any>): Promise<any> {
+export async function stepWait(page: IPage | null, params: unknown, data: unknown, args: Record<string, unknown>): Promise<unknown> {
   if (typeof params === 'number') await page!.wait(params);
-  else if (typeof params === 'object' && params) {
+  else if (isRecord(params)) {
     if ('text' in params) {
       await page!.wait({
         text: String(render(params.text, { args, data })),
-        timeout: params.timeout
+        timeout: typeof params.timeout === 'number' ? params.timeout : undefined,
       });
     } 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 | null, params: any, data: any, args: Record<string, any>): Promise<any> {
+export async function stepPress(page: IPage | null, params: unknown, data: unknown, args: Record<string, unknown>): Promise<unknown> {
   await page!.pressKey(String(render(params, { args, data })));
   return data;
 }
 
-export async function stepSnapshot(page: IPage | null, 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 stepSnapshot(page: IPage | null, params: unknown, _data: unknown, _args: Record<string, unknown>): Promise<unknown> {
+  const opts = isRecord(params) ? params : {};
+  return page!.snapshot({
+    interactive: typeof opts.interactive === 'boolean' ? opts.interactive : false,
+    compact: typeof opts.compact === 'boolean' ? opts.compact : false,
+    maxDepth: typeof opts.max_depth === 'number' ? opts.max_depth : undefined,
+    raw: typeof opts.raw === 'boolean' ? opts.raw : false,
+  });
 }
 
-export async function stepEvaluate(page: IPage | null, params: any, data: any, args: Record<string, any>): Promise<any> {
+export async function stepEvaluate(page: IPage | null, params: unknown, data: unknown, args: Record<string, unknown>): Promise<unknown> {
   const js = String(render(params, { args, data }));
-  let result = await page!.evaluate(js);
+  let result: unknown = await page!.evaluate(js);
   // MCP may return JSON as a string — auto-parse it
   if (typeof result === 'string') {
     const trimmed = result.trim();

src/pipeline/steps/fetch.ts

@@ -5,6 +5,10 @@
 import type { IPage } from '../../types.js';
 import { render } from '../template.js';
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
 /** Simple async concurrency limiter */
 async function mapConcurrent<T, R>(items: T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]> {
   const results: R[] = new Array(items.length);
@@ -25,9 +29,9 @@ async function mapConcurrent<T, R>(items: T[], limit: number, fn: (item: T, inde
 /** 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> {
+  queryParams: Record<string, unknown>, headers: Record<string, unknown>,
+  args: Record<string, unknown>, data: unknown,
+): Promise<unknown> {
   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> = {};
@@ -65,7 +69,7 @@ async function fetchSingle(
 async function fetchBatchInBrowser(
   page: IPage, urls: string[], method: string,
   headers: Record<string, string>, concurrency: number,
-): Promise<any[]> {
+): Promise<unknown[]> {
   const headersJs = JSON.stringify(headers);
   const urlsJs = JSON.stringify(urls);
   return page.evaluate(`
@@ -97,24 +101,25 @@ async function fetchBatchInBrowser(
   `);
 }
 
-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 ?? {};
+export async function stepFetch(page: IPage | null, params: unknown, data: unknown, args: Record<string, unknown>): Promise<unknown> {
+  const paramObject = isRecord(params) ? params : {};
+  const urlOrObj = typeof params === 'string' ? params : (paramObject.url ?? '');
+  const method = typeof paramObject.method === 'string' ? paramObject.method : 'GET';
+  const queryParams = isRecord(paramObject.params) ? paramObject.params : {};
+  const headers = isRecord(paramObject.headers) ? paramObject.headers : {};
   const urlTemplate = String(urlOrObj);
 
   // Per-item fetch when data is array and URL references item
   if (Array.isArray(data) && urlTemplate.includes('item')) {
-    const concurrency = typeof params?.concurrency === 'number' ? params.concurrency : 5;
+    const concurrency = typeof paramObject.concurrency === 'number' ? paramObject.concurrency : 5;
 
     // Render all URLs upfront
     const renderedHeaders: Record<string, string> = {};
     for (const [k, v] of Object.entries(headers)) renderedHeaders[k] = String(render(v, { args, data }));
     const renderedParams: Record<string, string> = {};
     for (const [k, v] of Object.entries(queryParams)) renderedParams[k] = String(render(v, { args, data }));
 
-    const urls = data.map((item: any, index: number) => {
+    const urls = data.map((item, index) => {
       let url = String(render(urlTemplate, { args, data, item, index }));
       if (Object.keys(renderedParams).length > 0) {
         const qs = new URLSearchParams(renderedParams).toString();

src/pipeline/steps/transform.ts

@@ -2,14 +2,19 @@
  * Pipeline steps: data transforms — select, map, filter, sort, limit.
  */
 
+import type { IPage } from '../../types.js';
 import { render, evalExpr } from '../template.js';
 
-export async function stepSelect(_page: any, params: any, data: any, args: Record<string, any>): Promise<any> {
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+export async function stepSelect(_page: IPage | null, params: unknown, data: unknown, args: Record<string, unknown>): Promise<unknown> {
   const pathStr = String(render(params, { args, data }));
   if (data && typeof data === 'object') {
-    let current = data;
+    let current: unknown = data;
     for (const part of pathStr.split('.')) {
-      if (current && typeof current === 'object' && !Array.isArray(current)) current = (current as any)[part];
+      if (isRecord(current)) current = current[part];
       else if (Array.isArray(current) && /^\d+$/.test(part)) current = current[parseInt(part, 10)];
       else return null;
     }
@@ -18,24 +23,25 @@ export async function stepSelect(_page: any, params: any, data: any, args: Recor
   return data;
 }
 
-export async function stepMap(_page: any, params: any, data: any, args: Record<string, any>): Promise<any> {
+export async function stepMap(_page: IPage | null, params: unknown, data: unknown, args: Record<string, unknown>): Promise<unknown> {
   if (!data || typeof data !== 'object') return data;
-  let source = data;
+  let source: unknown = data;
 
   // Support inline select: { map: { select: 'path', key: '${{ item.x }}' } }
-  if (params && typeof params === 'object' && 'select' in params) {
-    source = await stepSelect(null, (params as any).select, data, args);
+  if (isRecord(params) && 'select' in params) {
+    source = await stepSelect(null, params.select, data, args);
   }
 
   if (!source || typeof source !== 'object') return source;
 
-  let items: any[] = Array.isArray(source) ? source : [source];
-  if (!Array.isArray(source) && typeof source === 'object' && 'data' in source) items = source.data;
-  const result: any[] = [];
+  let items: unknown[] = Array.isArray(source) ? source : [source];
+  if (isRecord(source) && Array.isArray(source.data)) items = source.data;
+  const result: Array<Record<string, unknown>> = [];
+  const templateParams = isRecord(params) ? params : {};
   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)) {
+    const row: Record<string, unknown> = {};
+    for (const [key, template] of Object.entries(templateParams)) {
       if (key === 'select') continue;
       row[key] = render(template, { args, data: source, item, index: i });
     }
@@ -44,19 +50,26 @@ export async function stepMap(_page: any, params: any, data: any, args: Record<s
   return result;
 }
 
-export async function stepFilter(_page: any, params: any, data: any, args: Record<string, any>): Promise<any> {
+export async function stepFilter(_page: IPage | null, params: unknown, data: unknown, args: Record<string, unknown>): Promise<unknown> {
   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> {
+export async function stepSort(_page: IPage | null, params: unknown, data: unknown, _args: Record<string, unknown>): Promise<unknown> {
   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; });
+  const key = isRecord(params) ? String(params.by ?? '') : String(params);
+  const reverse = isRecord(params) ? params.order === 'desc' : false;
+  return [...data].sort((a, b) => {
+    const left = isRecord(a) ? a[key] : undefined;
+    const right = isRecord(b) ? b[key] : undefined;
+    const va = left ?? '';
+    const vb = right ?? '';
+    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> {
+export async function stepLimit(_page: IPage | null, params: unknown, data: unknown, args: Record<string, unknown>): Promise<unknown> {
   if (!Array.isArray(data)) return data;
   return data.slice(0, Number(render(params, { args, data })));
 }

src/pipeline/template.ts

@@ -3,13 +3,17 @@
  */
 
 export interface RenderContext {
-  args?: Record<string, any>;
-  data?: any;
-  item?: any;
+  args?: Record<string, unknown>;
+  data?: unknown;
+  item?: unknown;
   index?: number;
 }
 
-export function render(template: any, ctx: RenderContext): any {
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+export function render(template: unknown, ctx: RenderContext): unknown {
   if (typeof template !== 'string') return template;
   const trimmed = template.trim();
   // Full expression: entire string is a single ${{ ... }}
@@ -26,7 +30,7 @@ export function render(template: any, ctx: RenderContext): any {
   return template.replace(/\$\{\{\s*(.*?)\s*\}\}/g, (_m, expr) => String(evalExpr(expr.trim(), ctx)));
 }
 
-export function evalExpr(expr: string, ctx: RenderContext): any {
+export function evalExpr(expr: string, ctx: RenderContext): unknown {
   const args = ctx.args ?? {};
   const item = ctx.item ?? {};
   const data = ctx.data;
@@ -81,7 +85,7 @@ export function evalExpr(expr: string, ctx: RenderContext): any {
  *   default(val), join(sep), upper, lower, truncate(n), trim,
  *   replace(old,new), keys, length, first, last, json
  */
-function applyFilter(filterExpr: string, value: any): any {
+function applyFilter(filterExpr: string, value: unknown): unknown {
   const match = filterExpr.match(/^(\w+)(?:\((.+)\))?$/);
   if (!match) return value;
   const [, name, rawArgs] = match;
@@ -158,21 +162,22 @@ function applyFilter(filterExpr: string, value: any): any {
   }
 }
 
-export function resolvePath(pathStr: string, ctx: RenderContext): any {
+export function resolvePath(pathStr: string, ctx: RenderContext): unknown {
   const args = ctx.args ?? {};
   const item = ctx.item ?? {};
   const data = ctx.data;
   const index = ctx.index ?? 0;
   const parts = pathStr.split('.');
   const rootName = parts[0];
-  let obj: any; let rest: string[];
+  let obj: unknown;
+  let rest: string[];
   if (rootName === 'args') { obj = args; rest = parts.slice(1); }
   else if (rootName === 'item') { obj = item; rest = parts.slice(1); }
   else if (rootName === 'data') { obj = data; rest = parts.slice(1); }
   else if (rootName === 'index') return index;
   else { obj = item; rest = parts; }
   for (const part of rest) {
-    if (obj && typeof obj === 'object' && !Array.isArray(obj)) obj = obj[part];
+    if (isRecord(obj)) obj = obj[part];
     else if (Array.isArray(obj) && /^\d+$/.test(part)) obj = obj[parseInt(part, 10)];
     else return null;
   }
@@ -190,7 +195,7 @@ export function resolvePath(pathStr: string, ctx: RenderContext): any {
  * If opencli ever loads untrusted third-party adapters, this MUST be replaced
  * with a proper sandboxed evaluator.
  */
-function evalJsExpr(expr: string, ctx: RenderContext): any {
+function evalJsExpr(expr: string, ctx: RenderContext): unknown {
   // Guard against absurdly long expressions that could indicate injection.
   if (expr.length > 2000) return undefined;
 

src/pipeline/transform.test.ts

@@ -88,12 +88,12 @@ describe('stepFilter', () => {
 describe('stepSort', () => {
   it('sorts ascending by key', async () => {
     const result = await stepSort(null, 'score', SAMPLE_DATA, {});
-    expect(result.map((r: any) => r.title)).toEqual(['Alpha', 'Gamma', 'Beta']);
+    expect((result as typeof SAMPLE_DATA).map((r) => r.title)).toEqual(['Alpha', 'Gamma', 'Beta']);
   });
 
   it('sorts descending', async () => {
     const result = await stepSort(null, { by: 'score', order: 'desc' }, SAMPLE_DATA, {});
-    expect(result.map((r: any) => r.title)).toEqual(['Beta', 'Gamma', 'Alpha']);
+    expect((result as typeof SAMPLE_DATA).map((r) => r.title)).toEqual(['Beta', 'Gamma', 'Alpha']);
   });
 
   it('does not mutate original', async () => {