@jackwener/opencli 0.7.11 → 0.8.0

package/src/engine.ts

@@ -164,15 +164,72 @@ function registerYamlCli(filePath: string, defaultSite: string): void {
   }
 }
 
+/**
+ * Validates and coerces arguments based on the command's Arg definitions.
+ */
+function coerceAndValidateArgs(cmdArgs: Arg[], kwargs: Record<string, any>): Record<string, any> {
+  const result: Record<string, any> = { ...kwargs };
+
+  for (const argDef of cmdArgs) {
+    const val = result[argDef.name];
+    
+    // 1. Check required
+    if (argDef.required && (val === undefined || val === null || val === '')) {
+      throw new Error(`Argument "${argDef.name}" is required.\n${argDef.help ? `Hint: ${argDef.help}` : ''}`);
+    }
+
+    if (val !== undefined && val !== null) {
+      // 2. Type coercion
+      if (argDef.type === 'int' || argDef.type === 'number') {
+        const num = Number(val);
+        if (Number.isNaN(num)) {
+          throw new Error(`Argument "${argDef.name}" must be a valid number. Received: "${val}"`);
+        }
+        result[argDef.name] = num;
+      } else if (argDef.type === 'boolean' || argDef.type === 'bool') {
+        if (typeof val === 'string') {
+          const lower = val.toLowerCase();
+          if (lower === 'true' || lower === '1') result[argDef.name] = true;
+          else if (lower === 'false' || lower === '0') result[argDef.name] = false;
+          else throw new Error(`Argument "${argDef.name}" must be a boolean (true/false). Received: "${val}"`);
+        } else {
+          result[argDef.name] = Boolean(val);
+        }
+      }
+
+      // 3. Choices validation
+      const coercedVal = result[argDef.name];
+      if (argDef.choices && argDef.choices.length > 0) {
+        // Only stringent check for string/number types against choices array
+        if (!argDef.choices.map(String).includes(String(coercedVal))) {
+          throw new Error(`Argument "${argDef.name}" must be one of: ${argDef.choices.join(', ')}. Received: "${coercedVal}"`);
+        }
+      }
+    } else if (argDef.default !== undefined) {
+      // Set default if value is missing
+      result[argDef.name] = argDef.default;
+    }
+  }
+  return result;
+}
+
 /**
  * Execute a CLI command. Handles lazy-loading of TS modules.
  */
 export async function executeCommand(
   cmd: CliCommand,
   page: IPage | null,
-  kwargs: Record<string, any>,
+  rawKwargs: Record<string, any>,
   debug: boolean = false,
 ): Promise<any> {
+  let kwargs: Record<string, any>;
+  try {
+    kwargs = coerceAndValidateArgs(cmd.args, rawKwargs);
+  } catch (err: any) {
+    // Re-throw validation errors clearly
+    throw new Error(`[Argument Validation Error]\n${err.message}`);
+  }
+
   // Lazy-load TS module on first execution
   const internal = cmd as InternalCliCommand;
   if (internal._lazy && internal._modulePath) {

package/src/main.ts

@@ -189,19 +189,21 @@ for (const [, cmd] of registry) {
     const actionOpts = actionArgs[positionalArgs.length] ?? {};
     const startTime = Date.now();
     const kwargs: Record<string, any> = {};
+    
     // Collect positional args
     for (let i = 0; i < positionalArgs.length; i++) {
       const arg = positionalArgs[i];
       const v = actionArgs[i];
-      if (v !== undefined) kwargs[arg.name] = coerce(v, arg.type ?? 'str');
-      else if (arg.default != null) kwargs[arg.name] = arg.default;
+      if (v !== undefined) kwargs[arg.name] = v;
     }
+    
     // Collect named options
     for (const arg of cmd.args) {
       if (arg.positional) continue;
-      const v = actionOpts[arg.name]; if (v !== undefined) kwargs[arg.name] = coerce(v, arg.type ?? 'str');
-      else if (arg.default != null) kwargs[arg.name] = arg.default;
+      const v = actionOpts[arg.name]; 
+      if (v !== undefined) kwargs[arg.name] = v;
     }
+
     try {
       if (actionOpts.verbose) process.env.OPENCLI_VERBOSE = '1';
       let result: any;
@@ -226,11 +228,4 @@ for (const [, cmd] of registry) {
   });
 }
 
-function coerce(v: any, t: string): any {
-  if (t === 'bool') return ['1', 'true', 'yes', 'on'].includes(String(v).toLowerCase());
-  if (t === 'int') return parseInt(String(v), 10);
-  if (t === 'float') return parseFloat(String(v));
-  return String(v);
-}
-
 program.parse();

package/src/pipeline/executor.ts

@@ -4,11 +4,7 @@
 
 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';
+import { getStep, type StepHandler } from './registry.js';
 import { log } from '../logger.js';
 
 export interface PipelineContext {
@@ -16,28 +12,6 @@ export interface PipelineContext {
   debug?: boolean;
 }
 
-/** Step handler: all steps conform to (page, params, data, args) => Promise<any> */
-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,
-  fetch: stepFetch,
-  select: stepSelect,
-  evaluate: stepEvaluate,
-  snapshot: stepSnapshot,
-  click: stepClick,
-  type: stepType,
-  wait: stepWait,
-  press: stepPress,
-  map: stepMap,
-  filter: stepFilter,
-  sort: stepSort,
-  limit: stepLimit,
-  intercept: stepIntercept,
-  tap: stepTap,
-};
-
 export async function executePipeline(
   page: IPage | null,
   pipeline: any[],
@@ -54,7 +28,7 @@ export async function executePipeline(
     for (const [op, params] of Object.entries(step)) {
       if (debug) debugStepStart(i + 1, total, op, params);
 
-      const handler = STEP_HANDLERS[op];
+      const handler = getStep(op);
       if (handler) {
         data = await handler(page, params, data, args);
       } else {

package/src/pipeline/registry.ts

@@ -0,0 +1,60 @@
+/**
+ * Dynamic registry for pipeline steps.
+ * Allows core and third-party plugins to register custom YAML operations.
+ */
+
+import type { IPage } from '../types.js';
+
+// Import core steps
+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';
+
+/** 
+ * Step handler: all pipeline steps conform to this generic interface.
+ * 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> = (
+  page: IPage | null,
+  params: any,
+  data: TData,
+  args: Record<string, any>
+) => Promise<TResult>;
+
+const _stepRegistry = new Map<string, StepHandler>();
+
+/**
+ * Get a registered step handler by name.
+ */
+export function getStep(name: string): StepHandler | undefined {
+  return _stepRegistry.get(name);
+}
+
+/**
+ * Register a new custom step handler for the YAML pipeline.
+ */
+export function registerStep(name: string, handler: StepHandler): void {
+  _stepRegistry.set(name, handler);
+}
+
+// -------------------------------------------------------------
+// Auto-Register Core Steps
+// -------------------------------------------------------------
+registerStep('navigate', stepNavigate);
+registerStep('fetch', stepFetch);
+registerStep('select', stepSelect);
+registerStep('evaluate', stepEvaluate);
+registerStep('snapshot', stepSnapshot);
+registerStep('click', stepClick);
+registerStep('type', stepType);
+registerStep('wait', stepWait);
+registerStep('press', stepPress);
+registerStep('map', stepMap);
+registerStep('filter', stepFilter);
+registerStep('sort', stepSort);
+registerStep('limit', stepLimit);
+registerStep('intercept', stepIntercept);
+registerStep('tap', stepTap);