mepcli 1.3.1 → 1.4.0

package/README.md

@@ -226,7 +226,7 @@ const result = await MepCLI.pipeline()
 
 ## Keyboard & Mouse Support
 
-For a detailed list of shortcuts and mouse interactions, please refer to the **[Shortcuts Documentation](./docs/shortcuts.md)**.
+For a detailed list of shortcuts and mouse interactions, please refer to the **[Shortcuts Documentation](./docs/features/shortcuts.md)**.
 
 ## License
 

package/dist/pipeline.d.ts

@@ -1,11 +1,58 @@
 import { TaskRunner } from './tasks';
-export type PipelineAction<Ctx, T> = (context: Ctx, tasks?: TaskRunner) => Promise<T>;
-export type PipelineCondition<Ctx> = (context: Ctx) => boolean;
-export interface PipelineStep<Ctx> {
-    name: keyof Ctx;
+export declare const PipelineExit: unique symbol;
+export type PipelineAction<Ctx, T> = (context: Ctx, tasks?: TaskRunner) => Promise<T | typeof PipelineExit> | T | typeof PipelineExit;
+export type PipelineCondition<Ctx> = (context: Readonly<Ctx>) => boolean;
+export interface ValidationSchema {
+    parse?: (data: any) => any;
+    safeParse?: (data: any) => {
+        success: boolean;
+        error?: any;
+        issues?: any;
+        data?: any;
+    };
+}
+export type Validator = ((value: any) => boolean | string | Promise<boolean | string>) | ValidationSchema;
+export type Transformer<Ctx> = (value: any, context: Readonly<Ctx>) => any | Promise<any>;
+export interface PipelineStep<Ctx> extends StepConfig<Ctx> {
+    name?: keyof Ctx;
     action: PipelineAction<Ctx, any>;
     condition?: PipelineCondition<Ctx>;
 }
+export interface StepConfig<Ctx> {
+    validate?: Validator;
+    transform?: Transformer<Ctx>;
+    onError?: (error: unknown, context: Readonly<Ctx>) => void | Promise<void>;
+    fallback?: any | ((error: unknown, context: Readonly<Ctx>) => any | Promise<any>);
+    optional?: boolean;
+    timeout?: number;
+}
+export interface StepMetadata {
+    index: number;
+    name?: string;
+    type: 'named' | 'anonymous';
+}
+export interface PipelineOptions<Ctx> {
+    onStepStart?: (meta: StepMetadata, context: Readonly<Ctx>) => void | Promise<void>;
+    onStepComplete?: (meta: StepMetadata, context: Readonly<Ctx>) => void | Promise<void>;
+    onError?: (error: unknown, meta: StepMetadata, context: Readonly<Ctx>) => void | Promise<void>;
+    validate?: Validator;
+    onPipelineStart?: (context: Readonly<Ctx>) => void | Promise<void>;
+    onPipelineComplete?: (context: Readonly<Ctx>) => void | Promise<void>;
+    signal?: AbortSignal;
+}
+export declare class PipelineValidationError<Ctx = any> extends Error {
+    step?: StepMetadata;
+    context?: Ctx;
+    constructor(message: string, step?: StepMetadata, context?: Ctx);
+}
+export declare class PipelineTimeoutError<Ctx = any> extends Error {
+    step?: StepMetadata;
+    context?: Ctx;
+    constructor(message: string, step?: StepMetadata, context?: Ctx);
+}
+export declare class PipelineAbortError extends Error {
+    constructor(message?: string);
+}
 /**
  * Pipeline (Workflow Engine)
  *
@@ -16,20 +63,24 @@ export interface PipelineStep<Ctx> {
  */
 export declare class Pipeline<Ctx extends Record<string, any> = Record<string, any>> {
     private steps;
-    constructor();
+    private options;
+    constructor(options?: PipelineOptions<Ctx>);
+    /**
+     * Adds a named step to the pipeline. The result of the action is stored in the context under the given name.
+     */
+    step<K extends keyof Ctx>(name: K, action: PipelineAction<Ctx, Ctx[K]> | Pipeline<any>, config?: StepConfig<Ctx>): this;
+    /**
+     * Adds an anonymous step to the pipeline. The action can mutate the context directly or return a partial context to merge in.
+     */
+    step(action: PipelineAction<Ctx, void | Partial<Ctx>> | Pipeline<any>, config?: StepConfig<Ctx>): this;
     /**
-     * Adds a step to the pipeline.
-     * @param name The key in the context to store the result.
-     * @param action The function to execute, returning a Promise (usually a Prompt).
+     * Adds a conditional named step to the pipeline.
      */
-    step<K extends keyof Ctx>(name: K, action: PipelineAction<Ctx, Ctx[K]>): this;
+    stepIf<K extends keyof Ctx>(condition: PipelineCondition<Ctx>, name: K, action: PipelineAction<Ctx, Ctx[K]> | Pipeline<any>, config?: StepConfig<Ctx>): this;
     /**
-     * Adds a conditional step to the pipeline.
-     * @param condition A function that returns true if the step should run.
-     * @param name The key in the context to store the result.
-     * @param action The function to execute.
+     * Adds a conditional anonymous step to the pipeline.
      */
-    stepIf<K extends keyof Ctx>(condition: PipelineCondition<Ctx>, name: K, action: PipelineAction<Ctx, Ctx[K]>): this;
+    stepIf(condition: PipelineCondition<Ctx>, action: PipelineAction<Ctx, void | Partial<Ctx>> | Pipeline<any>, config?: StepConfig<Ctx>): this;
     /**
      * Executes the pipeline steps sequentially.
      * @param initialContext Optional initial context.

package/dist/pipeline.js

@@ -1,6 +1,32 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Pipeline = void 0;
+exports.Pipeline = exports.PipelineAbortError = exports.PipelineTimeoutError = exports.PipelineValidationError = exports.PipelineExit = void 0;
+exports.PipelineExit = Symbol.for('PipelineExit');
+class PipelineValidationError extends Error {
+    constructor(message, step, context) {
+        super(message);
+        this.name = 'PipelineValidationError';
+        this.step = step;
+        this.context = context;
+    }
+}
+exports.PipelineValidationError = PipelineValidationError;
+class PipelineTimeoutError extends Error {
+    constructor(message, step, context) {
+        super(message);
+        this.name = 'PipelineTimeoutError';
+        this.step = step;
+        this.context = context;
+    }
+}
+exports.PipelineTimeoutError = PipelineTimeoutError;
+class PipelineAbortError extends Error {
+    constructor(message = 'Pipeline aborted') {
+        super(message);
+        this.name = 'PipelineAbortError';
+    }
+}
+exports.PipelineAbortError = PipelineAbortError;
 /**
  * Pipeline (Workflow Engine)
  *
@@ -10,26 +36,54 @@ exports.Pipeline = void 0;
  * Philosophy: Enter-and-Forget (EAF), Zero-Dependency, Method Chaining.
  */
 class Pipeline {
-    constructor() {
+    constructor(options) {
         this.steps = [];
+        this.options = options || {};
     }
-    /**
-     * Adds a step to the pipeline.
-     * @param name The key in the context to store the result.
-     * @param action The function to execute, returning a Promise (usually a Prompt).
-     */
-    step(name, action) {
-        this.steps.push({ name, action });
+    step(nameOrAction, actionOrConfig, config) {
+        if (typeof nameOrAction === 'function' || nameOrAction instanceof Pipeline) {
+            const action = nameOrAction instanceof Pipeline
+                ? ((ctx, tasks) => nameOrAction.run(ctx, tasks))
+                : nameOrAction;
+            this.steps.push({
+                action: action,
+                ...(actionOrConfig || {})
+            });
+        }
+        else {
+            const action = actionOrConfig instanceof Pipeline
+                ? ((ctx, tasks) => actionOrConfig.run(ctx, tasks))
+                : actionOrConfig;
+            this.steps.push({
+                name: nameOrAction,
+                action: action,
+                ...(config || {})
+            });
+        }
         return this;
     }
-    /**
-     * Adds a conditional step to the pipeline.
-     * @param condition A function that returns true if the step should run.
-     * @param name The key in the context to store the result.
-     * @param action The function to execute.
-     */
-    stepIf(condition, name, action) {
-        this.steps.push({ name, action, condition });
+    stepIf(condition, nameOrAction, actionOrConfig, config) {
+        if (typeof nameOrAction === 'function' || nameOrAction instanceof Pipeline) {
+            const action = nameOrAction instanceof Pipeline
+                ? ((ctx, tasks) => nameOrAction.run(ctx, tasks))
+                : nameOrAction;
+            this.steps.push({
+                condition,
+                action: action,
+                ...(actionOrConfig || {})
+            });
+        }
+        else {
+            const action = actionOrConfig instanceof Pipeline
+                ? ((ctx, tasks) => actionOrConfig.run(ctx, tasks))
+                : actionOrConfig;
+            this.steps.push({
+                condition,
+                name: nameOrAction,
+                action: action,
+                ...(config || {})
+            });
+        }
         return this;
     }
     /**
@@ -39,14 +93,152 @@ class Pipeline {
      */
     async run(initialContext = {}, tasks) {
         const context = { ...initialContext };
-        for (const step of this.steps) {
-            if (step.condition && !step.condition(context)) {
-                continue;
+        if (this.options.onPipelineStart) {
+            await this.options.onPipelineStart({ ...context });
+        }
+        try {
+            for (let i = 0; i < this.steps.length; i++) {
+                if (this.options.signal?.aborted) {
+                    throw new PipelineAbortError();
+                }
+                const step = this.steps[i];
+                const meta = {
+                    index: i,
+                    name: step.name,
+                    type: step.name ? 'named' : 'anonymous'
+                };
+                if (step.condition && !step.condition(context)) {
+                    continue;
+                }
+                if (this.options.onStepStart) {
+                    await this.options.onStepStart(meta, { ...context });
+                }
+                try {
+                    let result;
+                    if (step.timeout && step.timeout > 0) {
+                        const timeoutPromise = new Promise((_, reject) => {
+                            setTimeout(() => {
+                                reject(new PipelineTimeoutError(`Step timed out after ${step.timeout}ms`, meta, context));
+                            }, step.timeout);
+                        });
+                        result = await Promise.race([step.action(context, tasks), timeoutPromise]);
+                    }
+                    else {
+                        result = await step.action(context, tasks);
+                    }
+                    if (result === exports.PipelineExit) {
+                        break;
+                    }
+                    if (!step.name) {
+                        // Anonymous action
+                        if (result && typeof result === 'object' && !Array.isArray(result)) {
+                            Object.assign(context, result);
+                        }
+                    }
+                    else {
+                        // Named action
+                        if (step.transform) {
+                            result = await step.transform(result, { ...context });
+                        }
+                        if (step.validate) {
+                            const validator = step.validate;
+                            if (typeof validator === 'function') {
+                                const valid = await validator(result);
+                                if (valid === false) {
+                                    throw new PipelineValidationError(`Validation failed for step at index ${i} (${String(step.name)})`, meta, context);
+                                }
+                                if (typeof valid === 'string') {
+                                    throw new PipelineValidationError(valid, meta, context);
+                                }
+                            }
+                            else if (typeof validator === 'object') {
+                                if (typeof validator.safeParse === 'function') {
+                                    const res = validator.safeParse(result);
+                                    if (!res.success) {
+                                        const errorMsg = res.error?.message || res.issues?.[0]?.message || 'Schema validation failed';
+                                        throw new PipelineValidationError(`Validation failed: ${errorMsg}`, meta, context);
+                                    }
+                                    result = res.data !== undefined ? res.data : result;
+                                }
+                                else if (typeof validator.parse === 'function') {
+                                    try {
+                                        const parsed = validator.parse(result);
+                                        result = parsed !== undefined ? parsed : result;
+                                    }
+                                    catch (err) {
+                                        throw new PipelineValidationError(`Validation failed: ${err.message || 'Schema parsing error'}`, meta, context);
+                                    }
+                                }
+                            }
+                        }
+                        context[step.name] = result;
+                    }
+                    if (this.options.onStepComplete) {
+                        await this.options.onStepComplete(meta, { ...context });
+                    }
+                }
+                catch (err) {
+                    let handled = false;
+                    if (step.onError) {
+                        await step.onError(err, { ...context });
+                    }
+                    if ('fallback' in step) {
+                        const fallbackValue = typeof step.fallback === 'function' ? await step.fallback(err, { ...context }) : step.fallback;
+                        if (step.name) {
+                            context[step.name] = fallbackValue;
+                        }
+                        handled = true;
+                    }
+                    else if (step.optional) {
+                        if (step.name) {
+                            context[step.name] = undefined;
+                        }
+                        handled = true;
+                    }
+                    if (!handled) {
+                        if (this.options.onError) {
+                            await this.options.onError(err, meta, { ...context });
+                        }
+                        throw err;
+                    }
+                }
+            }
+            if (this.options.validate) {
+                const validator = this.options.validate;
+                if (typeof validator === 'function') {
+                    const valid = await validator(context);
+                    if (valid === false) {
+                        throw new PipelineValidationError(`Final validation failed`);
+                    }
+                    if (typeof valid === 'string') {
+                        throw new PipelineValidationError(valid);
+                    }
+                }
+                else if (typeof validator === 'object') {
+                    if (typeof validator.safeParse === 'function') {
+                        const res = validator.safeParse(context);
+                        if (!res.success) {
+                            const errorMsg = res.error?.message || res.issues?.[0]?.message || 'Schema validation failed';
+                            throw new PipelineValidationError(`Final validation failed: ${errorMsg}`);
+                        }
+                        Object.assign(context, res.data !== undefined ? res.data : context);
+                    }
+                    else if (typeof validator.parse === 'function') {
+                        try {
+                            const parsed = validator.parse(context);
+                            Object.assign(context, parsed !== undefined ? parsed : context);
+                        }
+                        catch (err) {
+                            throw new PipelineValidationError(`Final validation failed: ${err.message || 'Schema parsing error'}`);
+                        }
+                    }
+                }
+            }
+        }
+        finally {
+            if (this.options.onPipelineComplete) {
+                await this.options.onPipelineComplete({ ...context });
             }
-            // In EAF (Enter-And-Forget) philosophy, if a prompt fails or is cancelled,
-            // the exception will propagate up and stop the pipeline.
-            const result = await step.action(context, tasks);
-            context[step.name] = result;
         }
         return context;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mepcli",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Zero-dependency, interactive CLI prompt",
   "repository": {
     "type": "git",
@@ -55,4 +55,4 @@
     "typescript": "^5",
     "typescript-eslint": "^8"
   }
-}
+}