@jackwener/opencli 0.7.6 → 0.7.9

package/src/clis/twitter/timeline.ts

@@ -1,50 +1,218 @@
 import { cli, Strategy } from '../../registry.js';
 
+// ── Twitter GraphQL constants ──────────────────────────────────────────
+
+const BEARER_TOKEN = 'AAAAAAAAAAAAAAAAAAAAANRILgAAAAAAnNwIzUejRCOuH5E6I8xnZz4puTs%3D1Zv7ttfk8LF81IUq16cHjhLTvJu4FA33AGWWjCpTnA';
+const HOME_TIMELINE_QUERY_ID = 'c-CzHF1LboFilMpsx4ZCrQ';
+
+const FEATURES = {
+  rweb_video_screen_enabled: false,
+  profile_label_improvements_pcf_label_in_post_enabled: true,
+  rweb_tipjar_consumption_enabled: true,
+  verified_phone_label_enabled: false,
+  creator_subscriptions_tweet_preview_api_enabled: true,
+  responsive_web_graphql_timeline_navigation_enabled: true,
+  responsive_web_graphql_skip_user_profile_image_extensions_enabled: false,
+  premium_content_api_read_enabled: false,
+  communities_web_enable_tweet_community_results_fetch: true,
+  c9s_tweet_anatomy_moderator_badge_enabled: true,
+  responsive_web_grok_analyze_button_fetch_trends_enabled: false,
+  responsive_web_grok_analyze_post_followups_enabled: true,
+  responsive_web_jetfuel_frame: false,
+  responsive_web_grok_share_attachment_enabled: true,
+  articles_preview_enabled: true,
+  responsive_web_edit_tweet_api_enabled: true,
+  graphql_is_translatable_rweb_tweet_is_translatable_enabled: true,
+  view_counts_everywhere_api_enabled: true,
+  longform_notetweets_consumption_enabled: true,
+  responsive_web_twitter_article_tweet_consumption_enabled: true,
+  tweet_awards_web_tipping_enabled: false,
+  responsive_web_grok_show_grok_translated_post: false,
+  responsive_web_grok_analysis_button_from_backend: false,
+  creator_subscriptions_quote_tweet_preview_enabled: false,
+  freedom_of_speech_not_reach_fetch_enabled: true,
+  standardized_nudges_misinfo: true,
+  tweet_with_visibility_results_prefer_gql_limited_actions_policy_enabled: true,
+  longform_notetweets_rich_text_read_enabled: true,
+  longform_notetweets_inline_media_enabled: true,
+  responsive_web_grok_image_annotation_enabled: true,
+  responsive_web_enhance_cards_enabled: false,
+};
+
+// ── Pure functions (type-safe, testable) ───────────────────────────────
+
+interface TimelineTweet {
+  id: string;
+  author: string;
+  text: string;
+  likes: number;
+  retweets: number;
+  replies: number;
+  views: number;
+  created_at: string;
+  url: string;
+}
+
+function buildHomeTimelineUrl(count: number, cursor?: string | null): string {
+  const vars: Record<string, any> = {
+    count,
+    includePromotedContent: false,
+    latestControlAvailable: true,
+    requestContext: 'launch',
+    withCommunity: true,
+  };
+  if (cursor) vars.cursor = cursor;
+
+  return `/i/api/graphql/${HOME_TIMELINE_QUERY_ID}/HomeTimeline`
+    + `?variables=${encodeURIComponent(JSON.stringify(vars))}`
+    + `&features=${encodeURIComponent(JSON.stringify(FEATURES))}`;
+}
+
+function extractTweet(result: any, seen: Set<string>): TimelineTweet | null {
+  if (!result) return null;
+  const tw = result.tweet || result;
+  const l = tw.legacy || {};
+  if (!tw.rest_id || seen.has(tw.rest_id)) return null;
+  seen.add(tw.rest_id);
+
+  const u = tw.core?.user_results?.result;
+  const screenName = u?.legacy?.screen_name || u?.core?.screen_name || 'unknown';
+  const noteText = tw.note_tweet?.note_tweet_results?.result?.text;
+  const views = tw.views?.count ? parseInt(tw.views.count, 10) : 0;
+
+  return {
+    id: tw.rest_id,
+    author: screenName,
+    text: noteText || l.full_text || '',
+    likes: l.favorite_count || 0,
+    retweets: l.retweet_count || 0,
+    replies: l.reply_count || 0,
+    views,
+    created_at: l.created_at || '',
+    url: `https://x.com/${screenName}/status/${tw.rest_id}`,
+  };
+}
+
+function parseHomeTimeline(data: any, seen: Set<string>): { tweets: TimelineTweet[]; nextCursor: string | null } {
+  const tweets: TimelineTweet[] = [];
+  let nextCursor: string | null = null;
+
+  const instructions =
+    data?.data?.home?.home_timeline_urt?.instructions || [];
+
+  for (const inst of instructions) {
+    for (const entry of inst.entries || []) {
+      const c = entry.content;
+
+      // Cursor entries
+      if (c?.entryType === 'TimelineTimelineCursor' || c?.__typename === 'TimelineTimelineCursor') {
+        if (c.cursorType === 'Bottom') nextCursor = c.value;
+        continue;
+      }
+      if (entry.entryId?.startsWith('cursor-bottom-')) {
+        nextCursor = c?.value || nextCursor;
+        continue;
+      }
+
+      // Single tweet entry
+      const tweetResult = c?.itemContent?.tweet_results?.result;
+      if (tweetResult) {
+        // Skip promoted content
+        if (c?.itemContent?.promotedMetadata) continue;
+        const tw = extractTweet(tweetResult, seen);
+        if (tw) tweets.push(tw);
+        continue;
+      }
+
+      // Conversation module (grouped tweets)
+      for (const item of c?.items || []) {
+        const nested = item.item?.itemContent?.tweet_results?.result;
+        if (nested) {
+          if (item.item?.itemContent?.promotedMetadata) continue;
+          const tw = extractTweet(nested, seen);
+          if (tw) tweets.push(tw);
+        }
+      }
+    }
+  }
+
+  return { tweets, nextCursor };
+}
+
+// ── CLI definition ────────────────────────────────────────────────────
+
 cli({
   site: 'twitter',
   name: 'timeline',
-  description: 'Twitter Home Timeline',
+  description: 'Fetch Twitter Home Timeline',
   domain: 'x.com',
   strategy: Strategy.COOKIE,
+  browser: true,
   args: [
     { name: 'limit', type: 'int', default: 20 },
   ],
-  columns: ['responseType', 'first'],
+  columns: ['id', 'author', 'text', 'likes', 'retweets', 'replies', 'views', 'created_at', 'url'],
   func: async (page, kwargs) => {
-    await page.goto('https://x.com/home');
-    await page.wait(5);
-    // Inject the fetch interceptor manually to see exactly what happens
-    await page.evaluate(`
-      () => {
-        window.__intercept_data = [];
-        const origFetch = window.fetch;
-        window.fetch = async function(...args) {
-          let u = typeof args[0] === 'string' ? args[0] : (args[0] && args[0].url) || '';
-          const res = await origFetch.apply(this, args);
-          setTimeout(async () => {
-            try {
-              if (u.includes('HomeTimeline')) {
-                const clone = res.clone();
-                const j = await clone.json();
-                window.__intercept_data.push(j);
-              }
-            } catch(e) {}
-          }, 0);
-          return res;
-        };
+    const limit = kwargs.limit || 20;
+
+    // Navigate to x.com for cookie context
+    await page.goto('https://x.com');
+    await page.wait(3);
+
+    // Extract CSRF token
+    const ct0 = await page.evaluate(`() => {
+      return document.cookie.split(';').map(c=>c.trim()).find(c=>c.startsWith('ct0='))?.split('=')[1] || null;
+    }`);
+    if (!ct0) throw new Error('Not logged into x.com (no ct0 cookie)');
+
+    // Dynamically resolve queryId
+    const queryId = await page.evaluate(`async () => {
+      try {
+        const ghResp = await fetch('https://raw.githubusercontent.com/fa0311/twitter-openapi/refs/heads/main/src/config/placeholder.json');
+        if (ghResp.ok) {
+          const data = await ghResp.json();
+          const entry = data['HomeTimeline'];
+          if (entry && entry.queryId) return entry.queryId;
+        }
+      } catch {}
+      return null;
+    }`) || HOME_TIMELINE_QUERY_ID;
+
+    // Build auth headers
+    const headers = JSON.stringify({
+      'Authorization': `Bearer ${decodeURIComponent(BEARER_TOKEN)}`,
+      'X-Csrf-Token': ct0,
+      'X-Twitter-Auth-Type': 'OAuth2Session',
+      'X-Twitter-Active-User': 'yes',
+    });
+
+    // Paginate — fetch in browser, parse in TypeScript
+    const allTweets: TimelineTweet[] = [];
+    const seen = new Set<string>();
+    let cursor: string | null = null;
+
+    for (let i = 0; i < 5 && allTweets.length < limit; i++) {
+      const fetchCount = Math.min(40, limit - allTweets.length + 5); // over-fetch slightly for promoted filtering
+      const apiUrl = buildHomeTimelineUrl(fetchCount, cursor)
+        .replace(HOME_TIMELINE_QUERY_ID, queryId);
+
+      const data = await page.evaluate(`async () => {
+        const r = await fetch("${apiUrl}", { headers: ${headers}, credentials: 'include' });
+        return r.ok ? await r.json() : { error: r.status };
+      }`);
+
+      if (data?.error) {
+        if (allTweets.length === 0) throw new Error(`HTTP ${data.error}: Failed to fetch timeline. queryId may have expired.`);
+        break;
       }
-    `);
-    
-    // trigger scroll
-    for(let i=0; i<3; i++) {
-      await page.evaluate('() => window.scrollTo(0, document.body.scrollHeight)');
-      await page.wait(2);
+
+      const { tweets, nextCursor } = parseHomeTimeline(data, seen);
+      allTweets.push(...tweets);
+
+      if (!nextCursor || nextCursor === cursor) break;
+      cursor = nextCursor;
     }
-    
-    // extract
-    const data = await page.evaluate('() => window.__intercept_data');
-    if (!data || data.length === 0) return [{responseType: 'no data captured'}];
-    
-    return [{responseType: `captured ${data.length} responses`, first: JSON.stringify(data[0]).substring(0,300)}];
-  }
+
+    return allTweets.slice(0, limit);
+  },
 });

package/src/completion.ts

@@ -7,6 +7,7 @@
  */
 
 import { getRegistry } from './registry.js';
+import { CliError } from './errors.js';
 
 // ── Dynamic completion logic ───────────────────────────────────────────────
 
@@ -123,7 +124,6 @@ export function printCompletionScript(shell: string): void {
       process.stdout.write(fishCompletionScript());
       break;
     default:
-      console.error(`Unsupported shell: ${shell}. Supported: bash, zsh, fish`);
-      process.exitCode = 1;
+      throw new CliError('UNSUPPORTED_SHELL', `Unsupported shell: ${shell}. Supported: bash, zsh, fish`);
   }
 }

package/src/doctor.ts

@@ -6,7 +6,7 @@ import { createInterface } from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
 import chalk from 'chalk';
 import type { IPage } from './types.js';
-import { PlaywrightMCP, getTokenFingerprint } from './browser.js';
+import { PlaywrightMCP, getTokenFingerprint } from './browser/index.js';
 import { browserSession } from './runtime.js';
 
 const PLAYWRIGHT_SERVER_NAME = 'playwright';
@@ -325,6 +325,8 @@ export function discoverExtensionToken(): string | null {
   if (platform === 'darwin') {
     bases.push(
       path.join(home, 'Library', 'Application Support', 'Google', 'Chrome'),
+      path.join(home, 'Library', 'Application Support', 'Google', 'Chrome Dev'),
+      path.join(home, 'Library', 'Application Support', 'Google', 'Chrome Beta'),
       path.join(home, 'Library', 'Application Support', 'Google', 'Chrome Canary'),
       path.join(home, 'Library', 'Application Support', 'Chromium'),
       path.join(home, 'Library', 'Application Support', 'Microsoft Edge'),
@@ -332,6 +334,8 @@ export function discoverExtensionToken(): string | null {
   } else if (platform === 'linux') {
     bases.push(
       path.join(home, '.config', 'google-chrome'),
+      path.join(home, '.config', 'google-chrome-unstable'),
+      path.join(home, '.config', 'google-chrome-beta'),
       path.join(home, '.config', 'chromium'),
       path.join(home, '.config', 'microsoft-edge'),
     );
@@ -339,6 +343,8 @@ export function discoverExtensionToken(): string | null {
     const appData = process.env.LOCALAPPDATA || path.join(home, 'AppData', 'Local');
     bases.push(
       path.join(appData, 'Google', 'Chrome', 'User Data'),
+      path.join(appData, 'Google', 'Chrome Dev', 'User Data'),
+      path.join(appData, 'Google', 'Chrome Beta', 'User Data'),
       path.join(appData, 'Microsoft', 'Edge', 'User Data'),
     );
   }
@@ -451,6 +457,8 @@ export function checkExtensionInstalled(): { installed: boolean; browsers: strin
   if (platform === 'darwin') {
     browserDirs.push(
       { name: 'Chrome', base: path.join(home, 'Library', 'Application Support', 'Google', 'Chrome') },
+      { name: 'Chrome Dev', base: path.join(home, 'Library', 'Application Support', 'Google', 'Chrome Dev') },
+      { name: 'Chrome Beta', base: path.join(home, 'Library', 'Application Support', 'Google', 'Chrome Beta') },
       { name: 'Chrome Canary', base: path.join(home, 'Library', 'Application Support', 'Google', 'Chrome Canary') },
       { name: 'Chromium', base: path.join(home, 'Library', 'Application Support', 'Chromium') },
       { name: 'Edge', base: path.join(home, 'Library', 'Application Support', 'Microsoft Edge') },
@@ -458,6 +466,8 @@ export function checkExtensionInstalled(): { installed: boolean; browsers: strin
   } else if (platform === 'linux') {
     browserDirs.push(
       { name: 'Chrome', base: path.join(home, '.config', 'google-chrome') },
+      { name: 'Chrome Dev', base: path.join(home, '.config', 'google-chrome-unstable') },
+      { name: 'Chrome Beta', base: path.join(home, '.config', 'google-chrome-beta') },
       { name: 'Chromium', base: path.join(home, '.config', 'chromium') },
       { name: 'Edge', base: path.join(home, '.config', 'microsoft-edge') },
     );
@@ -465,6 +475,8 @@ export function checkExtensionInstalled(): { installed: boolean; browsers: strin
     const appData = process.env.LOCALAPPDATA || path.join(home, 'AppData', 'Local');
     browserDirs.push(
       { name: 'Chrome', base: path.join(appData, 'Google', 'Chrome', 'User Data') },
+      { name: 'Chrome Dev', base: path.join(appData, 'Google', 'Chrome Dev', 'User Data') },
+      { name: 'Chrome Beta', base: path.join(appData, 'Google', 'Chrome Beta', 'User Data') },
       { name: 'Edge', base: path.join(appData, 'Microsoft', 'Edge', 'User Data') },
     );
   }

package/src/engine.ts

@@ -14,6 +14,8 @@ import yaml from 'js-yaml';
 import { type CliCommand, type InternalCliCommand, type Arg, Strategy, registerCommand } from './registry.js';
 import type { IPage } from './types.js';
 import { executePipeline } from './pipeline.js';
+import { log } from './logger.js';
+import { AdapterLoadError } from './errors.js';
 
 /** Set of TS module paths that have been loaded */
 const _loadedModules = new Set<string>();
@@ -84,7 +86,7 @@ function loadFromManifest(manifestPath: string, clisDir: string): void {
       }
     }
   } catch (err: any) {
-    process.stderr.write(`Warning: failed to load manifest ${manifestPath}: ${err.message}\n`);
+    log.warn(`Failed to load manifest ${manifestPath}: ${err.message}`);
   }
 }
 
@@ -107,7 +109,7 @@ async function discoverClisFromFs(dir: string): Promise<void> {
       ) {
         promises.push(
           import(`file://${filePath}`).catch((err: any) => {
-            process.stderr.write(`Warning: failed to load module ${filePath}: ${err.message}\n`);
+            log.warn(`Failed to load module ${filePath}: ${err.message}`);
           })
         );
       }
@@ -158,7 +160,7 @@ function registerYamlCli(filePath: string, defaultSite: string): void {
 
     registerCommand(cmd);
   } catch (err: any) {
-    process.stderr.write(`Warning: failed to load ${filePath}: ${err.message}\n`);
+    log.warn(`Failed to load ${filePath}: ${err.message}`);
   }
 }
 
@@ -180,7 +182,10 @@ export async function executeCommand(
         await import(`file://${modulePath}`);
         _loadedModules.add(modulePath);
       } catch (err: any) {
-        throw new Error(`Failed to load adapter module ${modulePath}: ${err.message}`);
+        throw new AdapterLoadError(
+          `Failed to load adapter module ${modulePath}: ${err.message}`,
+          'Check that the adapter file exists and has no syntax errors.',
+        );
       }
     }
     // After loading, the module's cli() call will have updated the registry

package/src/errors.ts

@@ -0,0 +1,48 @@
+/**
+ * Unified error types for opencli.
+ *
+ * All errors thrown by the framework should extend CliError so that
+ * the top-level handler in main.ts can render consistent, helpful output.
+ */
+
+export class CliError extends Error {
+  /** Machine-readable error code (e.g. 'BROWSER_CONNECT', 'ADAPTER_LOAD') */
+  readonly code: string;
+  /** Human-readable hint on how to fix the problem */
+  readonly hint?: string;
+
+  constructor(code: string, message: string, hint?: string) {
+    super(message);
+    this.name = 'CliError';
+    this.code = code;
+    this.hint = hint;
+  }
+}
+
+export class BrowserConnectError extends CliError {
+  constructor(message: string, hint?: string) {
+    super('BROWSER_CONNECT', message, hint);
+    this.name = 'BrowserConnectError';
+  }
+}
+
+export class AdapterLoadError extends CliError {
+  constructor(message: string, hint?: string) {
+    super('ADAPTER_LOAD', message, hint);
+    this.name = 'AdapterLoadError';
+  }
+}
+
+export class CommandExecutionError extends CliError {
+  constructor(message: string, hint?: string) {
+    super('COMMAND_EXEC', message, hint);
+    this.name = 'CommandExecutionError';
+  }
+}
+
+export class ConfigError extends CliError {
+  constructor(message: string, hint?: string) {
+    super('CONFIG', message, hint);
+    this.name = 'ConfigError';
+  }
+}

package/src/logger.ts

@@ -0,0 +1,57 @@
+/**
+ * Unified logging for opencli.
+ *
+ * All framework output (warnings, debug info, errors) should go through
+ * this module so that verbosity levels are respected consistently.
+ */
+
+import chalk from 'chalk';
+
+function isVerbose(): boolean {
+  return !!process.env.OPENCLI_VERBOSE;
+}
+
+function isDebug(): boolean {
+  return !!process.env.DEBUG?.includes('opencli');
+}
+
+export const log = {
+  /** Informational message (always shown) */
+  info(msg: string): void {
+    process.stderr.write(`${chalk.blue('ℹ')}  ${msg}\n`);
+  },
+
+  /** Warning (always shown) */
+  warn(msg: string): void {
+    process.stderr.write(`${chalk.yellow('⚠')}  ${msg}\n`);
+  },
+
+  /** Error (always shown) */
+  error(msg: string): void {
+    process.stderr.write(`${chalk.red('✖')}  ${msg}\n`);
+  },
+
+  /** Verbose output (only when OPENCLI_VERBOSE is set or -v flag) */
+  verbose(msg: string): void {
+    if (isVerbose()) {
+      process.stderr.write(`${chalk.dim('[verbose]')} ${msg}\n`);
+    }
+  },
+
+  /** Debug output (only when DEBUG includes 'opencli') */
+  debug(msg: string): void {
+    if (isDebug()) {
+      process.stderr.write(`${chalk.dim('[debug]')} ${msg}\n`);
+    }
+  },
+
+  /** Step-style debug (for pipeline steps, etc.) */
+  step(stepNum: number, total: number, op: string, preview: string = ''): void {
+    process.stderr.write(`  ${chalk.dim(`[${stepNum}/${total}]`)} ${chalk.bold.cyan(op)}${preview}\n`);
+  },
+
+  /** Step result summary */
+  stepResult(summary: string): void {
+    process.stderr.write(`       ${chalk.dim(`→ ${summary}`)}\n`);
+  },
+};

package/src/main.ts

@@ -11,10 +11,11 @@ import chalk from 'chalk';
 import { discoverClis, executeCommand } from './engine.js';
 import { type CliCommand, fullName, getRegistry, strategyLabel } from './registry.js';
 import { render as renderOutput } from './output.js';
-import { PlaywrightMCP } from './browser.js';
+import { PlaywrightMCP } from './browser/index.js';
 import { browserSession, DEFAULT_BROWSER_COMMAND_TIMEOUT, runWithTimeout } from './runtime.js';
 import { PKG_VERSION } from './version.js';
 import { getCompletions, printCompletionScript } from './completion.js';
+import { CliError } from './errors.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -212,8 +213,14 @@ for (const [, cmd] of registry) {
       }
       renderOutput(result, { fmt: actionOpts.format, columns: cmd.columns, title: `${cmd.site}/${cmd.name}`, elapsed: (Date.now() - startTime) / 1000, source: fullName(cmd) });
     } catch (err: any) { 
-      if (actionOpts.verbose && err.stack) { console.error(chalk.red(err.stack)); }
-      else { console.error(chalk.red(`Error: ${err.message ?? err}`)); }
+      if (err instanceof CliError) {
+        console.error(chalk.red(`Error [${err.code}]: ${err.message}`));
+        if (err.hint) console.error(chalk.yellow(`Hint: ${err.hint}`));
+      } else if (actionOpts.verbose && err.stack) {
+        console.error(chalk.red(err.stack));
+      } else {
+        console.error(chalk.red(`Error: ${err.message ?? err}`));
+      }
       process.exitCode = 1; 
     }
   });

package/src/pipeline/executor.ts

@@ -9,6 +9,7 @@ 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';
+import { log } from '../logger.js';
 
 export interface PipelineContext {
   args?: Record<string, any>;
@@ -57,7 +58,7 @@ export async function executePipeline(
       if (handler) {
         data = await handler(page, params, data, args);
       } else {
-        if (debug) process.stderr.write(`  ${chalk.yellow('⚠')}  Unknown step: ${op}\n`);
+        if (debug) log.warn(`Unknown step: ${op}`);
       }
 
       if (debug) debugStepResult(op, data);
@@ -73,21 +74,21 @@ function debugStepStart(stepNum: number, total: number, op: string, params: any)
   } 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`);
+  log.step(stepNum, total, op, preview);
 }
 
 function debugStepResult(op: string, data: any): void {
   if (data === null || data === undefined) {
-    process.stderr.write(`       ${chalk.dim('→ (no data)')}\n`);
+    log.stepResult('(no data)');
   } else if (Array.isArray(data)) {
-    process.stderr.write(`       ${chalk.dim(`→ ${data.length} items`)}\n`);
+    log.stepResult(`${data.length} items`);
   } 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`);
+    log.stepResult(`dict (${keys.join(', ')}${Object.keys(data).length > 5 ? '...' : ''})`);
   } 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`);
+    log.stepResult(`"${p}${data.length > 60 ? '...' : ''}"`);
   } else {
-    process.stderr.write(`       ${chalk.dim(`→ ${typeof data}`)}\n`);
+    log.stepResult(`${typeof data}`);
   }
 }

package/src/pipeline/steps/browser.ts

@@ -6,53 +6,53 @@
 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> {
+export async function stepNavigate(page: IPage | null, params: any, data: any, args: Record<string, any>): Promise<any> {
   const url = render(params, { args, data });
-  await page.goto(String(url));
+  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(/^@/, ''));
+export async function stepClick(page: IPage | null, 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> {
+export async function stepType(page: IPage | null, 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');
+    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);
+export async function stepWait(page: IPage | null, 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) {
-      await page.wait({
+      await page!.wait({
         text: String(render(params.text, { args, data })),
         timeout: params.timeout
       });
-    } else if ('time' in params) await page.wait(Number(params.time));
-  } else if (typeof params === 'string') await page.wait(Number(render(params, { args, data })));
+    } 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 })));
+export async function stepPress(page: IPage | null, 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> {
+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 });
+  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> {
+export async function stepEvaluate(page: IPage | null, params: any, data: any, args: Record<string, any>): Promise<any> {
   const js = String(render(params, { args, data }));
-  let result = await 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();