@jackwener/opencli 0.7.6 → 0.7.8

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();

package/src/pipeline/steps/intercept.ts

@@ -6,7 +6,7 @@ import type { IPage } from '../../types.js';
 import { render } from '../template.js';
 import { generateInterceptorJs, generateReadInterceptedJs } from '../../interceptor.js';
 
-export async function stepIntercept(page: IPage, params: any, data: any, args: Record<string, any>): Promise<any> {
+export async function stepIntercept(page: IPage | null, params: any, data: any, args: Record<string, any>): Promise<any> {
   const cfg = typeof params === 'object' ? params : {};
   const trigger = cfg.trigger ?? '';
   const capturePattern = cfg.capture ?? '';
@@ -16,28 +16,28 @@ export async function stepIntercept(page: IPage, params: any, data: any, args: R
   if (!capturePattern) return data;
 
   // Step 1: Inject fetch/XHR interceptor BEFORE trigger
-  await page.evaluate(generateInterceptorJs(JSON.stringify(capturePattern)));
+  await page!.evaluate(generateInterceptorJs(JSON.stringify(capturePattern)));
 
   // Step 2: Execute the trigger action
   if (trigger.startsWith('navigate:')) {
     const url = render(trigger.slice('navigate:'.length), { args, data });
-    await page.goto(String(url));
+    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));
+    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(/^@/, ''));
+    await page!.click(String(ref).replace(/^@/, ''));
   } else if (trigger === 'scroll') {
-    await page.scroll('down');
+    await page!.scroll('down');
   }
 
   // Step 3: Wait a bit for network requests to fire
-  await page.wait(Math.min(timeout, 3));
+  await page!.wait(Math.min(timeout, 3));
 
   // Step 4: Retrieve captured data
-  const matchingResponses = await page.evaluate(generateReadInterceptedJs());
+  const matchingResponses = await page!.evaluate(generateReadInterceptedJs());
 
   // Step 5: Select from response if specified
   let result = matchingResponses.length === 1 ? matchingResponses[0] :

package/src/pipeline/steps/tap.ts

@@ -13,7 +13,7 @@ import type { IPage } from '../../types.js';
 import { render } from '../template.js';
 import { generateTapInterceptorJs } from '../../interceptor.js';
 
-export async function stepTap(page: IPage, params: any, data: any, args: Record<string, any>): Promise<any> {
+export async function stepTap(page: IPage | null, 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 }));
@@ -96,5 +96,5 @@ export async function stepTap(page: IPage, params: any, data: any, args: Record<
     }
   `;
 
-  return page.evaluate(js);
+  return page!.evaluate(js);
 }

package/src/setup.ts

@@ -24,7 +24,7 @@ import {
   upsertTomlConfigToken,
   writeFileWithMkdir,
 } from './doctor.js';
-import { getTokenFingerprint } from './browser.js';
+import { getTokenFingerprint } from './browser/index.js';
 import { type CheckboxItem, checkboxPrompt } from './tui.js';
 
 export async function runSetup(opts: { cliVersion?: string; token?: string } = {}) {

package/tsconfig.json

@@ -5,8 +5,7 @@
     "moduleResolution": "Node16",
     "outDir": "dist",
     "rootDir": "src",
-    "strict": false,
-    "strictNullChecks": true,
+    "strict": true,
     "esModuleInterop": true,
     "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true,

package/dist/browser.d.ts

@@ -1,105 +0,0 @@
-/**
- * Browser interaction via Playwright MCP Bridge extension.
- * Connects to an existing Chrome browser through the extension.
- */
-import { withTimeoutMs } from './runtime.js';
-type ConnectFailureKind = 'missing-token' | 'extension-timeout' | 'extension-not-installed' | 'mcp-init' | 'process-exit' | 'unknown';
-type PlaywrightMCPState = 'idle' | 'connecting' | 'connected' | 'closing' | 'closed';
-type ConnectFailureInput = {
-    kind: ConnectFailureKind;
-    timeout: number;
-    hasExtensionToken: boolean;
-    tokenFingerprint?: string | null;
-    stderr?: string;
-    exitCode?: number | null;
-    rawMessage?: string;
-};
-export declare function getTokenFingerprint(token: string | undefined): string | null;
-export declare function formatBrowserConnectError(input: ConnectFailureInput): Error;
-declare function createJsonRpcRequest(method: string, params?: Record<string, any>): {
-    id: number;
-    message: string;
-};
-import type { IPage } from './types.js';
-/**
- * Page abstraction wrapping JSON-RPC calls to Playwright MCP.
- */
-export declare class Page implements IPage {
-    private _request;
-    constructor(_request: (method: string, params?: Record<string, any>) => Promise<any>);
-    call(method: string, params?: Record<string, any>): Promise<any>;
-    goto(url: string): Promise<void>;
-    evaluate(js: string): Promise<any>;
-    snapshot(opts?: {
-        interactive?: boolean;
-        compact?: boolean;
-        maxDepth?: number;
-        raw?: boolean;
-    }): Promise<any>;
-    click(ref: string): Promise<void>;
-    typeText(ref: string, text: string): Promise<void>;
-    pressKey(key: string): Promise<void>;
-    wait(options: number | {
-        text?: string;
-        time?: number;
-        timeout?: number;
-    }): Promise<void>;
-    tabs(): Promise<any>;
-    closeTab(index?: number): Promise<void>;
-    newTab(): Promise<void>;
-    selectTab(index: number): Promise<void>;
-    networkRequests(includeStatic?: boolean): Promise<any>;
-    consoleMessages(level?: string): Promise<any>;
-    scroll(direction?: string, _amount?: number): Promise<void>;
-    autoScroll(options?: {
-        times?: number;
-        delayMs?: number;
-    }): Promise<void>;
-    installInterceptor(pattern: string): Promise<void>;
-    getInterceptedRequests(): Promise<any[]>;
-}
-/**
- * Playwright MCP process manager.
- */
-export declare class PlaywrightMCP {
-    private static _activeInsts;
-    private static _cleanupRegistered;
-    private static _registerGlobalCleanup;
-    private _proc;
-    private _buffer;
-    private _pending;
-    private _initialTabIdentities;
-    private _closingPromise;
-    private _state;
-    private _page;
-    get state(): PlaywrightMCPState;
-    private _sendRequest;
-    private _rejectPendingRequests;
-    private _resetAfterFailedConnect;
-    connect(opts?: {
-        timeout?: number;
-    }): Promise<Page>;
-    close(): Promise<void>;
-}
-declare function extractTabEntries(raw: any): Array<{
-    index: number;
-    identity: string;
-}>;
-declare function diffTabIndexes(initialIdentities: string[], currentTabs: Array<{
-    index: number;
-    identity: string;
-}>): number[];
-declare function appendLimited(current: string, chunk: string, limit: number): string;
-declare function buildMcpArgs(input: {
-    mcpPath: string;
-    executablePath?: string | null;
-}): string[];
-export declare const __test__: {
-    createJsonRpcRequest: typeof createJsonRpcRequest;
-    extractTabEntries: typeof extractTabEntries;
-    diffTabIndexes: typeof diffTabIndexes;
-    appendLimited: typeof appendLimited;
-    buildMcpArgs: typeof buildMcpArgs;
-    withTimeoutMs: typeof withTimeoutMs;
-};
-export {};