@qlover/scripts-context 2.2.0 → 2.3.2

package/dist/index.d.ts

@@ -1,6 +1,5 @@
 import { UserConfig } from '@commitlint/types';
 import { Env } from '@qlover/env-loader';
-import { ExecutorContextImpl, LifecyclePluginInterface, ExecutorContextInterface, ExecutorError } from '@qlover/fe-corekit';
 
 declare const defaultFeConfig: FeConfig;
 interface FeConfig {
@@ -40,524 +39,10 @@ interface FeConfig {
      * @default { "extends": ["@commitlint/config-conventional"] }
      */
     commitlint?: UserConfig;
-    /**
-     * config of CI release
-     *
-     * scripts release
-     */
-    release?: FeReleaseConfig;
     /**
      * @default ['.env.local', '.env']
      */
     envOrder?: string[];
-    /**
-     * Allow additional custom properties for script-specific configurations
-     *
-     * This enables users to add custom configuration properties for their
-     * specific scripts without modifying the core FeConfig type definition.
-     *
-     * @example
-     * ```typescript
-     * const config: FeConfig = {
-     *   protectedBranches: ['main'],
-     *   'my-script': {
-     *     customOption: 'value'
-     *   }
-     * };
-     * ```
-     */
-    [key: string]: unknown;
-}
-/**
- * Configuration interface for automated release process management
- *
- * Core concept:
- * Defines comprehensive configuration options for automated release
- * processes, including PR management, package publishing, and
- * release workflow customization.
- *
- * Main features:
- * - PR management: Automated pull request creation and management
- *   - Dynamic branch naming with template variables
- *   - Customizable PR titles and descriptions
- *   - Automatic PR labeling and categorization
- *   - Configurable auto-merge behavior and strategies
- *
- * - Package publishing: Flexible package distribution configuration
- *   - Custom publish paths for different environments
- *   - Multi-package directory support for monorepos
- *   - Package-specific labeling and tracking
- *   - Environment-aware publishing strategies
- *
- * - Release workflow: Comprehensive release process control
- *   - Template-based content generation
- *   - Environment-specific configurations
- *   - Integration with CI/CD pipelines
- *   - Automated changelog and version management
- *
- * Design considerations:
- * - All properties are optional for maximum flexibility
- * - Template variables support dynamic content generation
- * - Environment-aware configuration for different deployment stages
- * - Integration with GitHub and other Git hosting platforms
- * - Support for both single-package and monorepo scenarios
- *
- * Template variables:
- * - `${pkgName}`: Package name from package.json
- * - `${tagName}`: Release version tag
- * - `${env}`: Release environment (development, staging, production)
- * - `${branch}`: Source branch name
- * - `${name}`: Package name for labeling
- * - `${changelog}`: Generated changelog content
- *
- * @example Basic release configuration
- * ```typescript
- * const releaseConfig: FeReleaseConfig = {
- *   autoMergeReleasePR: true,
- *   autoMergeType: 'squash',
- *   branchName: 'release-${pkgName}-${tagName}'
- * };
- * ```
- *
- * @example Advanced configuration with custom templates
- * ```typescript
- * const releaseConfig: FeReleaseConfig = {
- *   publishPath: './dist',
- *   autoMergeReleasePR: false,
- *   branchName: 'feat/release-${pkgName}-v${tagName}',
- *   PRTitle: '🚀 Release ${pkgName} v${tagName}',
- *   PRBody: '## Release ${pkgName} v${tagName}\n\n${changelog}',
- *   label: {
- *     name: 'release',
- *     color: '1A7F37',
- *     description: 'Automated release'
- *   }
- * };
- * ```
- *
- * @example Monorepo configuration
- * ```typescript
- * const releaseConfig: FeReleaseConfig = {
- *   packagesDirectories: ['packages/*', 'apps/*'],
- *   changePackagesLabel: 'changes:${name}',
- *   autoMergeReleasePR: true
- * };
- * ```
- */
-interface FeReleaseConfig {
-    /**
-     * The path to publish the package
-     *
-     * Core concept:
-     * Specifies the directory path where the package should be
-     * published, allowing for custom distribution locations
-     * and environment-specific publishing strategies.
-     *
-     * Publishing behavior:
-     * - Overrides default package.json publishConfig
-     * - Supports both relative and absolute paths
-     * - Used by npm publish and other distribution tools
-     * - Enables environment-specific publishing locations
-     * - Supports custom registry and distribution strategies
-     *
-     * Use cases:
-     * - Custom npm registry publishing
-     * - Environment-specific package distribution
-     * - Private package repository publishing
-     * - Alternative distribution platforms
-     * - Testing and staging package distribution
-     *
-     * @optional
-     * @default `''`
-     * @example Basic publish path
-     * ```typescript
-     * const config: FeReleaseConfig = {
-     *   publishPath: './dist'
-     * };
-     * ```
-     *
-     * @example Custom registry
-     * ```typescript
-     * const config: FeReleaseConfig = {
-     *   publishPath: '@myorg/registry'
-     * };
-     * ```
-     */
-    publishPath?: string;
-    /**
-     * Whether to automatically merge PR when creating and publishing
-     *
-     * Core concept:
-     * Controls whether release pull requests should be automatically
-     * merged after successful validation, enabling fully automated
-     * release workflows.
-     *
-     * Auto-merge behavior:
-     * - Merges PR after all checks pass
-     * - Uses specified auto-merge type (merge/squash/rebase)
-     * - Triggers post-merge release actions
-     * - Enables continuous deployment workflows
-     * - Reduces manual intervention in release process
-     *
-     * Workflow integration:
-     * - Integrates with GitHub auto-merge features
-     * - Supports CI/CD pipeline automation
-     * - Enables fully automated release processes
-     * - Reduces release cycle time
-     * - Maintains release quality through automated checks
-     *
-     * @optional
-     * @default `false`
-     * @example Enable auto-merge
-     * ```typescript
-     * const config: FeReleaseConfig = {
-     *   autoMergeReleasePR: true,
-     *   autoMergeType: 'squash'
-     * };
-     * ```
-     *
-     * @example Manual review required
-     * ```typescript
-     * const config: FeReleaseConfig = {
-     *   autoMergeReleasePR: false
-     * };
-     * ```
-     */
-    autoMergeReleasePR?: boolean;
-    /**
-     * PR auto-merge strategy for release pull requests
-     *
-     * Core concept:
-     * Defines the merge strategy used when automatically merging
-     * release pull requests, affecting commit history and
-     * repository structure.
-     *
-     * Merge strategies:
-     * - merge: Creates merge commit with branch history
-     * - squash: Combines all commits into single commit
-     * - rebase: Replays commits on target branch
-     *
-     * Strategy considerations:
-     * - merge: Preserves complete branch history
-     * - squash: Creates clean, linear history
-     * - rebase: Maintains chronological order
-     * - Affects commit message and history structure
-     * - Influences repository maintenance and debugging
-     *
-     * @optional
-     * @default `'squash'`
-     * @example Squash merge
-     * ```typescript
-     * const config: FeReleaseConfig = {
-     *   autoMergeType: 'squash'
-     * };
-     * ```
-     *
-     * @example Preserve history
-     * ```typescript
-     * const config: FeReleaseConfig = {
-     *   autoMergeType: 'merge'
-     * };
-     * ```
-     */
-    autoMergeType?: 'merge' | 'squash' | 'rebase';
-    /**
-     * Template for creating release branch names
-     *
-     * Core concept:
-     * Defines the naming pattern for release branches using
-     * template variables, enabling consistent and descriptive
-     * branch naming across different packages and environments.
-     *
-     * Template variables:
-     * - `${pkgName}`: Package name from package.json
-     * - `${tagName}`: Release version tag
-     * - `${env}`: Release environment
-     * - `${branch}`: Source branch name
-     *
-     * Branch naming patterns:
-     * - Descriptive names for easy identification
-     * - Consistent format across all releases
-     * - Environment and package-specific naming
-     * - Supports Git branch naming conventions
-     * - Enables automated branch management
-     *
-     * @optional
-     * @default `'release-${pkgName}-${tagName}'`
-     * @example Basic branch naming
-     * ```typescript
-     * const config: FeReleaseConfig = {
-     *   branchName: 'release-${pkgName}-${tagName}'
-     * };
-     * ```
-     *
-     * @example Environment-aware naming
-     * ```typescript
-     * const config: FeReleaseConfig = {
-     *   branchName: 'release/${env}/${pkgName}-${tagName}'
-     * };
-     * ```
-     */
-    branchName?: string;
-    /**
-     * Template for release pull request titles
-     *
-     * Core concept:
-     * Defines the title format for release pull requests using
-     * template variables, providing clear and informative
-     * PR titles for release management.
-     *
-     * Title components:
-     * - Package name for identification
-     * - Release version for version tracking
-     * - Environment for deployment context
-     * - Source branch for change tracking
-     * - Consistent formatting for automation
-     *
-     * Template variables:
-     * - `${pkgName}`: Package name from package.json
-     * - `${tagName}`: Release version tag
-     * - `${env}`: Release environment
-     * - `${branch}`: Source branch name
-     *
-     * @optional
-     * @default `'[${pkgName} Release] Branch:${branch}, Tag:${tagName}, Env:${env}'`
-     * @example Basic PR title
-     * ```typescript
-     * const config: FeReleaseConfig = {
-     *   PRTitle: '[${pkgName} Release] v${tagName}'
-     * };
-     * ```
-     *
-     * @example Detailed PR title
-     * ```typescript
-     * const config: FeReleaseConfig = {
-     *   PRTitle: '🚀 Release ${pkgName} v${tagName} (${env})'
-     * };
-     * ```
-     */
-    PRTitle?: string;
-    /**
-     * Template for release pull request body content
-     *
-     * Core concept:
-     * Defines the content template for release pull request
-     * descriptions, providing comprehensive release information
-     * and automated content generation.
-     *
-     * Content sections:
-     * - Release details and metadata
-     * - Generated changelog content
-     * - Review checklist and notes
-     * - Environment and version information
-     * - Automated process notifications
-     *
-     * Template variables:
-     * - `${tagName}`: Release version tag
-     * - `${branch}`: Source branch name
-     * - `${env}`: Release environment
-     * - `${changelog}`: Generated changelog content
-     * - `${pkgName}`: Package name
-     *
-     * @optional
-     * @default Comprehensive PR body template with changelog
-     * @example Simple PR body
-     * ```typescript
-     * const config: FeReleaseConfig = {
-     *   PRBody: 'Release ${pkgName} v${tagName}\n\n${changelog}'
-     * };
-     * ```
-     *
-     * @example Detailed PR body
-     * ```typescript
-     * const config: FeReleaseConfig = {
-     *   PRBody: `
-     * ## Release ${pkgName} v${tagName}
-     *
-     * **Environment:** ${env}
-     * **Branch:** ${branch}
-     *
-     * ### Changes
-     * ${changelog}
-     *
-     * ### Checklist
-     * - [ ] Version number is correct
-     * - [ ] All tests pass
-     * - [ ] Documentation updated
-     * `
-     * };
-     * ```
-     */
-    PRBody?: string;
-    /**
-     * Configuration for release pull request labels
-     *
-     * Core concept:
-     * Defines the label configuration for release pull requests,
-     * enabling automated categorization and visual identification
-     * of release-related PRs.
-     *
-     * Label features:
-     * - Automated label application
-     * - Customizable label appearance
-     * - Consistent release identification
-     * - Integration with GitHub labeling system
-     * - Support for custom label descriptions
-     *
-     * Label properties:
-     * - name: Label identifier and display name
-     * - color: Hexadecimal color code for visual distinction
-     * - description: Label description for documentation
-     *
-     * @optional
-     * @example Basic label configuration
-     * ```typescript
-     * const config: FeReleaseConfig = {
-     *   label: {
-     *     name: 'release',
-     *     color: '1A7F37',
-     *     description: 'Automated release PR'
-     *   }
-     * };
-     * ```
-     *
-     * @example Custom label
-     * ```typescript
-     * const config: FeReleaseConfig = {
-     *   label: {
-     *     name: 'CI-Release',
-     *     color: '0366D6',
-     *     description: 'Release created by CI/CD'
-     *   }
-     * };
-     * ```
-     */
-    label?: {
-        /**
-         * Hexadecimal color code for label appearance
-         *
-         * Color format: 6-character hex string without '#'
-         * Used for visual distinction in GitHub interface
-         * Supports standard web color codes
-         *
-         * @optional
-         * @default `'1A7F37'`
-         * @example Green color
-         * ```typescript
-         * color: '1A7F37'
-         * ```
-         *
-         * @example Blue color
-         * ```typescript
-         * color: '0366D6'
-         * ```
-         */
-        color?: string;
-        /**
-         * Descriptive text for label documentation
-         *
-         * Provides context about the label's purpose
-         * Used in GitHub label management interface
-         * Helps team members understand label usage
-         *
-         * @optional
-         * @default `'Release PR'`
-         * @example
-         * ```typescript
-         * description: 'Automated release pull request'
-         * ```
-         */
-        description?: string;
-        /**
-         * Label name for identification and display
-         *
-         * Used as the primary identifier for the label
-         * Displayed in GitHub PR interface
-         * Should be descriptive and consistent
-         *
-         * @optional
-         * @default `'CI-Release'`
-         * @example
-         * ```typescript
-         * name: 'release'
-         * ```
-         */
-        name?: string;
-    };
-    /**
-     * Template for package change labels in monorepos
-     *
-     * Core concept:
-     * Defines the naming pattern for labels that identify
-     * which packages have changed in monorepo releases,
-     * enabling targeted review and deployment.
-     *
-     * Label usage:
-     * - Applied to PRs when specific packages change
-     * - Enables package-specific review processes
-     * - Supports selective deployment strategies
-     * - Improves monorepo change tracking
-     * - Facilitates team collaboration and review
-     *
-     * Template variables:
-     * - `${name}`: Package name for label identification
-     *
-     * @optional
-     * @default `'changes:${name}'`
-     * @example Basic change label
-     * ```typescript
-     * const config: FeReleaseConfig = {
-     *   changePackagesLabel: 'changes:${name}'
-     * };
-     * ```
-     *
-     * @example Custom change label
-     * ```typescript
-     * const config: FeReleaseConfig = {
-     *   changePackagesLabel: 'package:${name}'
-     * };
-     * ```
-     */
-    changePackagesLabel?: string;
-    /**
-     * Directories containing packages for monorepo releases
-     *
-     * Core concept:
-     * Specifies the directories that contain packages for
-     * monorepo release management, enabling selective
-     * package discovery and release coordination.
-     *
-     * Directory patterns:
-     * - Supports glob patterns for flexible matching
-     * - Enables selective package inclusion
-     * - Supports nested directory structures
-     * - Facilitates monorepo organization
-     * - Enables workspace-specific configurations
-     *
-     * Use cases:
-     * - Monorepo package discovery
-     * - Selective package releases
-     * - Workspace-specific configurations
-     * - Multi-package coordination
-     * - Dependency-aware releases
-     *
-     * @optional
-     * @default `[]`
-     * @example Basic package directories
-     * ```typescript
-     * const config: FeReleaseConfig = {
-     *   packagesDirectories: ['packages/*']
-     * };
-     * ```
-     *
-     * @example Multiple package directories
-     * ```typescript
-     * const config: FeReleaseConfig = {
-     *   packagesDirectories: ['packages/*', 'apps/*', 'libs/*']
-     * };
-     * ```
-     */
-    packagesDirectories?: string[];
 }
 
 /**
@@ -2784,7 +2269,7 @@ interface ShellConfig extends ShellExecOptions {
  *
  * Main features:
  * - Template formatting: Dynamic command generation with context
- *   - Uses lodash template for string interpolation
+ *   - Uses TemplateEngine for string interpolation
  *   - Supports complex template expressions
  *   - Provides error handling for template failures
  *   - Enables dynamic command construction
@@ -2833,7 +2318,7 @@ interface ShellConfig extends ShellExecOptions {
  * @example With template formatting
  * ```typescript
  * const shell = new Shell({ logger: myLogger });
- * const output = await shell.exec('git clone <%= repo %>', {
+ * const output = await shell.exec('git clone ${repo}', {
  *   context: { repo: 'https://github.com/user/repo.git' }
  * });
  * ```
@@ -2859,6 +2344,7 @@ interface ShellConfig extends ShellExecOptions {
 declare class Shell implements ShellInterface {
     config: ShellConfig;
     private cache;
+    private static readonly templateEngine;
     /**
      * Creates a new Shell instance with the specified configuration
      *
@@ -2926,59 +2412,30 @@ declare class Shell implements ShellInterface {
      */
     get logger(): LoggerInterface;
     /**
-     * Formats a template string with context using lodash template
-     *
-     * Core concept:
-     * Provides static template formatting functionality using
-     * lodash template for string interpolation with context data.
-     *
-     * Template features:
-     * - Uses lodash template for powerful string interpolation
-     * - Supports complex template expressions and logic
-     * - Handles undefined and null context values gracefully
-     * - Returns formatted string with context values substituted
+     * Formats a template string with context using {@link TemplateEngine}.
      *
-     * Template syntax:
-     * - `<%= variable %>` for escaped output
-     * - `<%- variable %>` for unescaped output
-     * - `<% code %>` for JavaScript code execution
-     * - Supports nested object access and function calls
-     *
-     * Context handling:
-     * - Accepts any object with string/number/boolean values
-     * - Handles undefined and null values safely
-     * - Supports nested object property access
-     * - Provides fallback for missing context values
+     * Uses ES6-style `${ path }` placeholders via {@link TemplateEngine}.
      *
      * @param template - Template string with interpolation placeholders
      * @param context - Context object for template variable substitution
      * @returns Formatted string with context values substituted
      *
-     * @example Basic template formatting
+     * @example Basic formatting
      * ```typescript
-     * const result = Shell.format('Hello <%= name %>!', { name: 'World' });
+     * const result = Shell.format('Hello ${name}!', { name: 'World' });
      * // Returns: 'Hello World!'
      * ```
      *
      * @example Complex template with nested objects
      * ```typescript
      * const result = Shell.format(
-     *   'git clone <%= repo.url %> <%= repo.branch %>',
+     *   'git clone ${repo.url} ${repo.branch}',
      *   { repo: { url: 'https://github.com/user/repo.git', branch: 'main' } }
      * );
      * // Returns: 'git clone https://github.com/user/repo.git main'
      * ```
-     *
-     * @example Template with conditional logic
-     * ```typescript
-     * const result = Shell.format(
-     *   'npm install<% if (dev) { %> --save-dev<% } %>',
-     *   { dev: true }
-     * );
-     * // Returns: 'npm install --save-dev'
-     * ```
      */
-    static format(template?: string, context?: Record<string, unknown>): string;
+    static format(template?: string, context?: Record<string, any>): string;
     /**
      * Formats a template string with context and comprehensive error handling
      *
@@ -3012,14 +2469,14 @@ declare class Shell implements ShellInterface {
      *
      * @example Basic formatting
      * ```typescript
-     * const result = shell.format('Hello <%= name %>!', { name: 'World' });
+     * const result = shell.format('Hello ${name}!', { name: 'World' });
      * // Returns: 'Hello World!'
      * ```
      *
      * @example Error handling
      * ```typescript
      * try {
-     *   const result = shell.format('Hello <%= name %>!', {});
+     *   const result = shell.format('Hello ${name}!', {});
      * } catch (error) {
      *   // Error is logged with template and context information
      *   console.error('Template formatting failed:', error.message);
@@ -3061,7 +2518,7 @@ declare class Shell implements ShellInterface {
      *
      * @example String command with template
      * ```typescript
-     * const output = await shell.exec('git clone <%= repo %>', {
+     * const output = await shell.exec('git clone ${repo}', {
      *   context: { repo: 'https://github.com/user/repo.git' }
      * });
      * ```
@@ -4201,45 +3658,1783 @@ declare class ConfigSearch {
 }
 
 /**
- * Enhanced script context that provides environment management and configuration utilities
+ * Base error class for all executor-related errors in the system
  *
- * Core concept:
- * Provides a comprehensive script execution environment with integrated
- * configuration management, environment variable handling, logging,
- * and shell command execution capabilities.
+ * ExecutorError provides a standardized way to handle errors throughout the executor
+ * lifecycle. It wraps underlying errors while maintaining error context through an
+ * error ID system, enabling precise error categorization and handling.
  *
- * Main features:
- * - Environment management: Integrated environment variable handling
- *   - Automatic loading of .env files with configurable order
- *   - Type-safe environment variable access with defaults
- *   - Support for environment-specific configurations
- *   - Integration with fe-config environment settings
+ * Core features:
+ * - **Error identification**: Uses unique `id` to categorize different error types without relying on error messages
+ * - **Error wrapping**: Preserves original error information through `cause` property, supporting error chaining
+ * - **Stack trace independence**: Each error maintains its own stack trace, original error stack accessible via `cause.stack`
+ * - **Type safety**: Provides type-safe error handling with TypeScript, enabling compile-time error checking
+ * - **Subclass support**: Designed to be extended by specific error types (RequestError, AbortError, etc.)
  *
- * - Configuration management: Unified configuration access and merging
- *   - Script-specific configuration sections
- *   - Deep merging with default values
- *   - Type-safe option access with nested path support
- *   - Configuration validation and fallback handling
+ * Design considerations:
+ * - The `id` field enables error categorization without relying on error messages, which may be localized or changed
+ * - The `cause` field supports error chaining (similar to Java's exception chaining), preserving the original error context
+ * - When `cause` is an Error, its message is inherited but stack trace remains independent, and the Error object is stored in `cause`
+ * - When `cause` is a string, it's used directly as the error message, but not stored in `cause` property (to avoid duplication)
+ * - When `cause` is undefined or other types, the error message falls back to `id` value
+ * - Each ExecutorError has its own stack trace showing where it was created, not where the original error occurred
+ * - Original error's stack trace is preserved in `cause.stack` for complete error chain debugging
+ * - Stack trace is automatically captured in V8 environments (Node.js, Chrome) for better debugging
+ * - For subclasses, `name` is set to `constructor.name`, which may be affected by bundling/minification (see TODO comment in constructor)
+ *
+ * Error handling strategy:
+ * - Use specific error IDs for different failure scenarios to enable precise error handling
+ * - Always wrap lower-level errors with ExecutorError to maintain consistent error interface
+ * - Preserve original error information through the `cause` property for debugging
+ * - Use `instanceof` checks for error type detection, and `id` for specific error scenario handling
+ *
+ * @example Basic usage with error ID only
+ * ```typescript
+ * throw new ExecutorError('VALIDATION_ERROR');
+ * // Error message will be 'VALIDATION_ERROR' (falls back to id)
+ * ```
  *
- * - Logging system: Structured logging with timestamp formatting
- *   - Configurable verbosity levels
- *   - Timestamp formatting with timezone support
- *   - Logger name identification for multi-script environments
- *   - Console output with structured formatting
+ * @example Wrapping an existing error
+ * ```typescript
+ * try {
+ *   await riskyOperation();
+ * } catch (error) {
+ *   throw new ExecutorError('OPERATION_FAILED', error);
+ * }
+ * ```
  *
- * - Shell integration: Command execution with dry run support
- *   - Safe command execution with error handling
- *   - Dry run mode for testing and validation
- *   - Integrated logging for command output
- *   - Support for custom execution functions
+ * @example With custom string message
+ * ```typescript
+ * throw new ExecutorError(
+ *   'CUSTOM_ERROR',
+ *   'Invalid configuration: timeout must be positive'
+ * );
+ * ```
  *
- * Design considerations:
- * - Uses lodash merge for deep configuration merging
- * - Supports environment file loading with configurable order
- * - Provides type-safe option access with fallback values
- * - Implements proper error handling for missing configurations
- * - Maintains backward compatibility with existing interfaces
- * - Supports both development and production environments
+ * @example Error identification and handling
+ * ```typescript
+ * try {
+ *   await executor.exec(task);
+ * } catch (error) {
+ *   if (error instanceof ExecutorError) {
+ *     switch (error.id) {
+ *       case 'VALIDATION_ERROR':
+ *         // Handle validation errors
+ *         console.error('Validation failed:', error.message);
+ *         break;
+ *       case 'TIMEOUT_ERROR':
+ *         // Handle timeout errors
+ *         console.error('Operation timed out:', error.message);
+ *         break;
+ *       default:
+ *         // Handle other executor errors
+ *         console.error('Unknown executor error:', error.id);
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @see RequestError - Extends ExecutorError for request-specific errors
+ * @see AbortError - Extends ExecutorError for abort-specific errors
+ */
+declare class ExecutorError extends Error {
+    /**
+     * Unique identifier for categorizing the error type
+     *
+     * This ID enables programmatic error handling without relying on error messages,
+     * which may change or be localized. It serves as a stable contract for error types
+     * across the entire executor system.
+     *
+     * Best practices:
+     * - Use UPPER_SNAKE_CASE for consistency
+     * - Make IDs descriptive and specific to the error scenario
+     * - Document common error IDs in the class-level documentation
+     * - Avoid changing existing IDs to maintain backward compatibility
+     *
+     * @example `'VALIDATION_ERROR'`
+     * @example `'EXECUTOR_ASYNC_ERROR'`
+     * @example `'REQUEST_TIMEOUT'`
+     */
+    readonly id: string;
+    /**
+     * Creates a new ExecutorError instance
+     *
+     * The constructor intelligently handles different types of `cause` values:
+     * - If `cause` is an Error: Inherits its message but maintains independent stack trace
+     * - If `cause` is a string: Uses it as the error message directly
+     * - If `cause` is undefined or other types: Uses the `id` as the error message
+     *
+     * Implementation details:
+     * - Uses `super()` to initialize the parent Error class first
+     * - Sets the error name based on whether this is the base class or a subclass
+     * - For base ExecutorError, uses the constant `EXECUTOR_ERROR_NAME`
+     * - For subclasses, uses `this.constructor.name` (note: may be affected by bundling/minification)
+     * - Each ExecutorError gets its own stack trace (captured by V8 automatically)
+     * - Original error's stack trace is preserved in `cause.stack` for debugging the error chain
+     * - The `cause` property is only set when `this.message !== cause` to avoid redundancy
+     *
+     * Message resolution logic:
+     * 1. If `cause` is an Error: `message = cause.message`
+     * 2. Else if `cause` is a string: `message = cause`
+     * 3. Else: `message = id` (fallback to error ID)
+     *
+     * Cause property logic:
+     * - Set `this.cause = cause` only when `this.message !== cause`
+     * - This means: Error objects always set `cause`, strings don't (to avoid duplication), undefined sets `cause` to undefined
+     *
+     * @param id - Unique identifier for the error type
+     *
+     * Used to categorize and identify specific error scenarios. Common IDs include:
+     * - `'UNKNOWN_ASYNC_ERROR'` (EXECUTOR_ASYNC_ERROR) - Async execution failures in executor lifecycle
+     * - `'UNKNOWN_SYNC_ERROR'` (EXECUTOR_SYNC_ERROR) - Sync execution failures in executor lifecycle
+     * - `'VALIDATION_ERROR'` - Input validation failures
+     * - `'TIMEOUT_ERROR'` - Operation timeout
+     * - `'ABORT_ERROR'` - Operation aborted by user or system
+     * - `'PLUGIN_ERROR'` - Plugin execution failures
+     * - `'CONTEXT_ERROR'` - Context-related errors
+     *
+     * @param cause - Optional underlying cause of the error
+     *
+     * Can be:
+     * - An Error object: Original error to wrap, inheriting its message. The Error object will be stored in `cause` property (access original stack via `cause.stack`).
+     * - A string: Custom error message describing the failure. The string will be used as `message`, but won't be stored in `cause` (to avoid duplication).
+     * - Undefined: Error message will be set to `id`. The `cause` property will be set to `undefined`.
+     * - Any other value: Error message will be set to `id`. The value will be stored in `cause` property.
+     *
+     * @example Create error with ID only
+     * ```typescript
+     * const error = new ExecutorError('UNKNOWN_ERROR');
+     * console.log(error.id); // 'UNKNOWN_ERROR'
+     * console.log(error.message); // 'UNKNOWN_ERROR' (falls back to id)
+     * console.log(error.cause); // undefined
+     * console.log(error.name); // 'ExecutorError'
+     * ```
+     *
+     * @example Wrap an existing error
+     * ```typescript
+     * try {
+     *   JSON.parse(invalidJson);
+     * } catch (err) {
+     *   const error = new ExecutorError('PARSE_ERROR', err);
+     *   console.log(error.id); // 'PARSE_ERROR'
+     *   console.log(error.message); // 'Unexpected token...' (from err.message)
+     *   console.log(error.cause); // Original SyntaxError (stored in cause)
+     *   console.log(error.stack); // Stack trace showing where ExecutorError was created
+     *   console.log(error.cause.stack); // Original SyntaxError stack trace
+     * }
+     * ```
+     *
+     * @example Create error with custom message
+     * ```typescript
+     * const error = new ExecutorError(
+     *   'CONFIG_ERROR',
+     *   'Timeout must be a positive number'
+     * );
+     * console.log(error.id); // 'CONFIG_ERROR'
+     * console.log(error.message); // 'Timeout must be a positive number'
+     * console.log(error.cause); // undefined (not stored to avoid duplication)
+     * ```
+     *
+     * @example Subclass usage
+     * ```typescript
+     * class RequestError extends ExecutorError {
+     *   constructor(cause?: unknown) {
+     *     super('REQUEST_ERROR', cause);
+     *     // Note: constructor.name may be mangled during bundling
+     *     // Consider explicitly setting this.name if needed
+     *   }
+     * }
+     * const error = new RequestError('Network failure');
+     * console.log(error.name); // 'RequestError' (from constructor.name)
+     * console.log(error.id); // 'REQUEST_ERROR'
+     * console.log(error.message); // 'Network failure'
+     * ```
+     */
+    constructor(
+    /**
+     * Unique identifier for categorizing the error type
+     *
+     * This ID enables programmatic error handling without relying on error messages,
+     * which may change or be localized. It serves as a stable contract for error types
+     * across the entire executor system.
+     *
+     * Best practices:
+     * - Use UPPER_SNAKE_CASE for consistency
+     * - Make IDs descriptive and specific to the error scenario
+     * - Document common error IDs in the class-level documentation
+     * - Avoid changing existing IDs to maintain backward compatibility
+     *
+     * @example `'VALIDATION_ERROR'`
+     * @example `'EXECUTOR_ASYNC_ERROR'`
+     * @example `'REQUEST_TIMEOUT'`
+     */
+    id: string, 
+    /**
+     * Optional underlying cause of the error
+     *
+     * Supports error chaining by preserving the original error or message.
+     * The behavior differs based on the type:
+     *
+     * - **Error object**: Its message is inherited, and the Error object is stored in `cause` property (original stack accessible via `cause.stack`)
+     * - **String**: Used as the error message directly, but not stored in `cause` property (to avoid duplication)
+     * - **Undefined**: Error message falls back to `id`, and `cause` is set to `undefined`
+     * - **Other types**: Error message falls back to `id`, and the value is stored in `cause` property
+     *
+     * Use cases:
+     * - Wrapping lower-level errors (network errors, parse errors, etc.) - use Error object
+     * - Providing custom error messages for specific scenarios - use string
+     * - Storing additional error context (objects, metadata, etc.) - use any other type
+     *
+     * @optional
+     * @example Error object: `new Error('Connection failed')` - message and stack inherited, Error stored in cause
+     * @example String message: `'Invalid input format'` - used as message, not stored in cause
+     * @example Other values: `{ code: 500, details: '...' }` - message falls back to id, value stored in cause
+     */
+    cause?: unknown);
+}
+
+/**
+ * Asynchronous task function type
+ *
+ * Represents a task that returns a Promise. Used for async operations
+ * like API calls, file I/O, or any asynchronous work.
+ *
+ * @template R - Return type of the task
+ * @template P - Parameter type for the context
+ *
+ * @example
+ * ```typescript
+ * const asyncTask: ExecutorAsyncTask<User, UserId> = async (ctx) => {
+ *   const response = await fetch(`/api/users/${ctx.parameters.id}`);
+ *   return response.json();
+ * };
+ * ```
+ */
+type ExecutorAsyncTask<R, P> = (ctx: ExecutorContextInterface<P, R>) => Promise<R>;
+/**
+ * Synchronous task function type
+ *
+ * Represents a task that returns immediately. Used for synchronous
+ * operations like data transformation, validation, or computation.
+ *
+ * @template R - Return type of the task
+ * @template P - Parameter type for the context
+ *
+ * @example
+ * ```typescript
+ * const syncTask: ExecutorSyncTask<string, string> = (ctx) => {
+ *   return ctx.parameters.toUpperCase();
+ * };
+ * ```
+ */
+type ExecutorSyncTask<R, P> = (ctx: ExecutorContextInterface<P, R>) => R;
+/**
+ * Union type for both sync and async tasks
+ *
+ * Allows a single type to represent either synchronous or asynchronous tasks.
+ * The executor will automatically detect the return type and handle accordingly.
+ *
+ * @template R - Return type of the task
+ * @template P - Parameter type for the context
+ */
+type ExecutorTask<R, P> = ExecutorAsyncTask<R, P> | ExecutorSyncTask<R, P>;
+/**
+ * Plugin hook name type
+ *
+ * Currently supports string names. Symbol support is planned for future versions
+ * to allow for more advanced plugin identification and namespacing.
+ *
+ * @todo Add symbol support | symbol;
+ */
+type ExecutorPluginNameType = string;
+/**
+ * Base plugin interface for executor plugins
+ *
+ * ## Purpose
+ * Defines the minimum contract that all executor plugins must implement.
+ * Provides plugin identification, enablement checking, and basic metadata.
+ *
+ * Key Features:
+ *
+ * Plugin Identification:
+ * - pluginName: Optional name for plugin identification
+ * - onlyOne: Flag to ensure only one instance of this plugin type
+ *
+ * Enablement Checking:
+ * - enabled: Method to check if plugin should execute for a given hook
+ * - Context-Aware: Can check context state to determine enablement
+ * - Hook-Specific: Can enable/disable per hook name
+ *
+ * Usage:
+ * This is the base interface. Most plugins should extend `LifecyclePluginInterface`
+ * which adds lifecycle hooks (onBefore, onExec, onSuccess, onError).
+ *
+ * @template Ctx - Type of executor context interface
+ *
+ * @example Basic plugin
+ * ```typescript
+ * const plugin: ExecutorPluginInterface<ExecutorContextInterface<unknown, unknown>> = {
+ *   pluginName: 'myPlugin',
+ *   onlyOne: true,
+ *   enabled: (name, context) => {
+ *     return name === 'onBefore' && context.parameters.shouldRun;
+ *   }
+ * };
+ * ```
+ *
+ * @see LifecyclePluginInterface - Extended interface with lifecycle hooks
+ * @see LifecycleExecutor - Executor that uses plugins
+ */
+interface ExecutorPluginInterface<Ctx extends ExecutorContextInterface<unknown, unknown>> {
+    /** Optional plugin name for identification */
+    readonly pluginName: ExecutorPluginNameType;
+    /** If true, ensures only one instance of this plugin type */
+    readonly onlyOne?: boolean;
+    /**
+     * Check if plugin should be enabled for a given hook
+     * @param name - Hook name to check
+     * @param context - Optional execution context
+     * @returns true if plugin should execute, false otherwise
+     */
+    enabled?(name: ExecutorPluginNameType, context?: Ctx): boolean;
+}
+
+/**
+ * Runtime information interface for hook execution tracking
+ *
+ * Core concept:
+ * Provides detailed runtime metadata for individual hook execution,
+ * enabling performance monitoring, flow control, and execution state tracking
+ *
+ * Main features:
+ * - Execution tracking: Monitors hook execution state and performance
+ * - Flow control: Provides mechanisms to control execution pipeline flow
+ * - Performance metrics: Tracks execution times and performance data
+ * - State preservation: Maintains execution state throughout the pipeline
+ * - Extensibility: Supports additional custom properties for specific use cases
+ *
+ * Flow control mechanisms:
+ * - breakChain: Immediately stops execution pipeline
+ * - returnBreakChain: Stops pipeline when return value is present
+ * - times: Tracks execution frequency for optimization
+ *
+ * @since 3.0.0
+ * @example Basic runtime information
+ * ```typescript
+ * const runtime: HookRuntimes = {
+ *   hookName: 'onBefore',
+ *   returnValue: { validated: true },
+ *   times: 1,
+ *   breakChain: false,
+ *   returnBreakChain: false
+ * };
+ * ```
+ *
+ * @example Runtime with custom properties
+ * ```typescript
+ * const runtime: HookRuntimes = {
+ *   hookName: 'customHook',
+ *   returnValue: { processed: true },
+ *   times: 3,
+ *   breakChain: false,
+ *   returnBreakChain: true,
+ *   customMetric: 'performance_data',
+ *   executionTime: 150
+ * };
+ * ```
+ */
+interface HookRuntimes {
+    /**
+     * Name of the current plugin being executed
+     *
+     * Core concept:
+     * Identifies which plugin is currently executing, enabling plugin-specific
+     * debugging and tracking
+     *
+     * @optional
+     * @example `'ValidationPlugin'`
+     * @example `'CachePlugin'`
+     */
+    pluginName?: string;
+    /**
+     * Index of the current plugin in the plugins array
+     *
+     * Core concept:
+     * Tracks the position of the current plugin in the execution chain,
+     * useful for debugging execution order
+     *
+     * @optional
+     * @example `0` // First plugin
+     * @example `2` // Third plugin
+     */
+    pluginIndex?: number;
+    /**
+     * Name of the current hook being executed
+     *
+     * Core concept:
+     * Identifies the specific hook that is currently being executed,
+     * enabling targeted debugging and monitoring of hook performance
+     *
+     * Main features:
+     * - Hook identification: Clearly identifies which hook is executing
+     * - Debugging support: Enables targeted debugging of specific hooks
+     * - Performance monitoring: Allows tracking of individual hook performance
+     * - Pipeline visibility: Provides visibility into execution pipeline state
+     *
+     * @optional
+     * @example `'onBefore'`
+     * @example `'onExec'`
+     * @example `'onAfter'`
+     * @example `'customValidationHook'`
+     */
+    hookName?: string;
+    /**
+     * Return value from the current hook execution
+     *
+     * Core concept:
+     * Captures the return value from the current hook execution,
+     * enabling result tracking and flow control based on hook output
+     *
+     * Main features:
+     * - Result tracking: Monitors what each hook returns
+     * - Flow control: Enables conditional execution based on return values
+     * - Debugging support: Provides visibility into hook output
+     * - Pipeline integration: Results can influence downstream execution
+     *
+     * @readonly
+     * @optional
+     * @example `{ validated: true, data: 'processed' }`
+     * @example `'hook_result'`
+     * @example `{ error: 'validation_failed' }`
+     */
+    returnValue?: unknown;
+    /**
+     * Number of times the current hook has been executed
+     *
+     * Core concept:
+     * Tracks how many plugins have executed the current hook (e.g., onBefore).
+     * This counter increments for each plugin that successfully executes the hook.
+     *
+     * Important:
+     * - This is per-hook, not global
+     * - Reset when switching to a different hook
+     * - Represents "which plugin is executing this hook" (1st, 2nd, 3rd, etc.)
+     *
+     * Main features:
+     * - Execution counting: Monitors how many plugins executed this hook
+     * - Performance analysis: Identifies frequently executed hooks
+     * - Loop detection: Helps identify potential infinite loops
+     * - Optimization insights: Provides data for performance optimization
+     *
+     * Usage scenarios:
+     * - Know if any plugin executed the hook (times > 0)
+     * - Track which plugin number is executing (useful for debugging)
+     * - Detect if hook was skipped by all plugins (times === 0)
+     *
+     * @optional
+     * @example `0` // No plugin has executed this hook yet
+     * @example `1` // First plugin executed this hook
+     * @example `3` // Third plugin is executing this hook
+     */
+    times?: number;
+    /**
+     * Flag to immediately break the execution chain
+     *
+     * Core concept:
+     * Provides a mechanism to immediately stop the execution pipeline,
+     * enabling early termination when certain conditions are met
+     *
+     * Main features:
+     * - Immediate termination: Stops execution pipeline immediately
+     * - Conditional control: Enables conditional execution flow
+     * - Error handling: Allows early termination on critical errors
+     * - Performance optimization: Avoids unnecessary processing
+     *
+     * Use cases:
+     * - Error conditions: Stop execution when critical errors occur
+     * - Validation failures: Terminate when validation fails
+     * - Early success: Stop when desired result is achieved early
+     * - Resource constraints: Terminate when resources are exhausted
+     *
+     * @optional
+     * @example `true` // Break execution chain immediately
+     * @example `false` // Continue normal execution
+     */
+    breakChain?: boolean;
+    /**
+     * Flag to break chain when return value exists
+     *
+     * Core concept:
+     * Enables conditional chain breaking based on the presence of a return value,
+     * commonly used in error handling and early termination scenarios
+     *
+     * Main features:
+     * - Conditional termination: Breaks chain only when return value exists
+     * - Error handling: Commonly used in `onError` lifecycle hooks
+     * - Result-based control: Enables flow control based on hook results
+     * - Flexible termination: Provides more nuanced control than `breakChain`
+     *
+     * Common usage:
+     * - Error handlers: Break chain when error is handled and result is returned
+     * - Validation: Stop processing when validation result is returned
+     * - Caching: Terminate when cached result is found
+     * - Early success: Stop when desired result is achieved
+     *
+     * @optional
+     * @example `true` // Break chain if returnValue exists
+     * @example `false` // Continue regardless of returnValue
+     */
+    returnBreakChain?: boolean;
+    /**
+     * Flag to continue execution on error
+     *
+     * Core concept:
+     * Provides a mechanism to continue executing subsequent plugins even when
+     * a plugin hook throws an error, enabling resilient execution pipelines
+     *
+     * Main features:
+     * - Error resilience: Continues execution despite individual plugin failures
+     * - Fault tolerance: Enables graceful degradation in plugin chains
+     * - Cleanup guarantees: Ensures all cleanup hooks execute even if some fail
+     * - Flexible error handling: Allows selective error suppression
+     *
+     * Use cases:
+     * - Finally hooks: Ensure all cleanup operations execute even if one fails
+     * - Logging hooks: Continue logging even if one logger fails
+     * - Monitoring hooks: Collect metrics from all plugins despite failures
+     * - Non-critical operations: Continue execution for non-critical hooks
+     *
+     * @optional
+     * @example `true` // Continue to next plugin even if current plugin throws error
+     * @example `false` // Stop execution and throw error (default behavior)
+     */
+    continueOnError?: boolean;
+    /**
+     * Additional custom properties for extensibility
+     *
+     * Core concept:
+     * Provides a flexible mechanism to add custom properties to runtime
+     * information, enabling plugin-specific metadata and custom tracking
+     *
+     * Main features:
+     * - Extensibility: Allows plugins to add custom runtime data
+     * - Custom metrics: Enables plugin-specific performance tracking
+     * - Metadata storage: Provides space for custom execution metadata
+     * - Plugin integration: Enables rich plugin-to-plugin communication
+     *
+     * Common custom properties:
+     * - executionTime: Hook execution time in milliseconds
+     * - memoryUsage: Memory consumption during hook execution
+     * - customMetrics: Plugin-specific performance metrics
+     * - debugInfo: Additional debugging information
+     *
+     * @example
+     * ```typescript
+     * {
+     *   executionTime: 150,
+     *   memoryUsage: '2.5MB',
+     *   customMetric: 'validation_score',
+     *   debugInfo: { step: 'validation', level: 'info' }
+     * }
+     * ```
+     */
+    [key: string]: unknown;
+}
+/**
+ * Interface for runtime tracking of executor hooks
+ *
+ * Core concept:
+ * Generic interface that allows extending HookRuntimes with custom properties.
+ * This enables plugins to add their own runtime tracking data.
+ *
+ * @template RuntimesType - Type of hook runtimes (extends HookRuntimes)
+ *
+ * @example Basic usage (default HookRuntimes)
+ * ```typescript
+ * class MyContext implements ExecutorHookRuntimesInterface {
+ *   // Uses default HookRuntimes
+ * }
+ * ```
+ *
+ * @example Extended runtimes with custom properties
+ * ```typescript
+ * interface CustomRuntimes extends HookRuntimes {
+ *   executionTime?: number;
+ *   memoryUsage?: number;
+ *   customMetric?: string;
+ * }
+ *
+ * class MyContext implements ExecutorHookRuntimesInterface<CustomRuntimes> {
+ *   get hooksRuntimes(): Readonly<CustomRuntimes> {
+ *     // Return extended runtime data
+ *   }
+ * }
+ * ```
+ *
+ * @since 2.6.0
+ */
+interface ExecutorHookRuntimesInterface<RuntimesType extends HookRuntimes = HookRuntimes> {
+    /**
+     * Reset hooks runtime state to initial values
+     *
+     * If hookName is provided, only reset the runtime state for that hook.
+     *
+     * Core concept:
+     * Clears all runtime tracking information for fresh execution
+     */
+    resetHooksRuntimes(hookName?: string): void;
+    /**
+     * Reset entire context to initial state
+     */
+    reset(): void;
+    /**
+     * Check if a plugin hook should be skipped
+     * @param plugin - The plugin to check
+     * @param hookName - The name of the hook to validate
+     * @returns True if the hook should be skipped, false otherwise
+     */
+    shouldSkipPluginHook<Ctx extends ExecutorContextInterface<unknown, unknown>>(plugin: ExecutorPluginInterface<Ctx>, hookName: string): boolean;
+    /**
+     * Get read-only snapshot of hooks runtime information
+     *
+     * Core concept:
+     * Provides safe read-only access to runtime tracking information.
+     * Returns a frozen copy to prevent accidental modifications.
+     *
+     * Generic support:
+     * - Can return extended HookRuntimes with custom properties
+     * - Type-safe access to custom runtime data
+     * - Maintains immutability through Readonly
+     *
+     * @returns Frozen snapshot of hook runtime state (can include custom properties)
+     *
+     * @example Access standard properties
+     * ```typescript
+     * const runtimes = context.hooksRuntimes;
+     * console.log(runtimes.hookName, runtimes.times);
+     * ```
+     *
+     * @example Access custom properties (with extended type)
+     * ```typescript
+     * interface CustomRuntimes extends HookRuntimes {
+     *   executionTime: number;
+     * }
+     * const context: ExecutorHookRuntimesInterface<CustomRuntimes>;
+     * const runtimes = context.hooksRuntimes;
+     * console.log(runtimes.executionTime); // Type-safe!
+     * ```
+     */
+    get hooksRuntimes(): Readonly<RuntimesType>;
+    /**
+     * Update runtime tracking information for plugin execution
+     *
+     * Core concept:
+     * Controlled way to update runtime state through partial updates.
+     * This is the only safe way to modify runtime state.
+     *
+     * Generic support:
+     * - Can update custom properties in extended HookRuntimes
+     * - Type-safe updates with partial type checking
+     * - Maintains immutability through object replacement
+     *
+     * @param runtimes - Partial runtime updates to apply (can include custom properties)
+     *
+     * @example Update standard properties
+     * ```typescript
+     * context.runtimes({
+     *   pluginName: 'ValidationPlugin',
+     *   hookName: 'onBefore',
+     *   pluginIndex: 0,
+     *   times: 1
+     * });
+     * ```
+     *
+     * @example Update custom properties (with extended type)
+     * ```typescript
+     * interface CustomRuntimes extends HookRuntimes {
+     *   executionTime: number;
+     * }
+     * const context: ExecutorHookRuntimesInterface<CustomRuntimes>;
+     * context.runtimes({
+     *   executionTime: 150,
+     *   customMetric: 'performance'
+     * });
+     * ```
+     */
+    runtimes(runtimes: Partial<RuntimesType>): void;
+    /**
+     * Set return value in context runtime tracking
+     * @param returnValue - The value to set as return value
+     */
+    runtimeReturnValue(returnValue: unknown): void;
+    /**
+     * Check if the execution chain should be broken
+     * @returns True if the chain should be broken, false otherwise
+     */
+    shouldBreakChain(): boolean;
+    /**
+     * Check if the execution chain should be broken due to return value
+     * @returns True if the chain should be broken due to return value, false otherwise
+     */
+    shouldBreakChainOnReturn(): boolean;
+    /**
+     * Check if execution should continue on error
+     *
+     * Core concept:
+     * Determines whether to continue executing subsequent plugins when a plugin hook
+     * throws an error, enabling resilient execution pipelines
+     *
+     * Main features:
+     * - Error resilience: Allows execution to continue despite individual failures
+     * - Fault tolerance: Enables graceful degradation in plugin chains
+     * - Cleanup guarantees: Ensures all cleanup hooks execute even if some fail
+     *
+     * Use cases:
+     * - Finally hooks: Ensure all cleanup operations execute even if one fails
+     * - Logging hooks: Continue logging even if one logger fails
+     * - Monitoring hooks: Collect metrics from all plugins despite failures
+     *
+     * @returns True if execution should continue on error, false otherwise
+     *
+     * @example
+     * ```typescript
+     * // Enable continue on error for finally hooks
+     * context.runtimes({ continueOnError: true });
+     * await runPluginsHookAsync(plugins, 'onFinally', context);
+     * ```
+     */
+    shouldContinueOnError(): boolean;
+}
+
+/**
+ * Executor context interface with generic runtime support
+ *
+ * Core concept:
+ * Provides a shared context for task execution, allowing plugins to access
+ * and modify parameters, track execution state, and share data across the
+ * execution lifecycle. The context acts as a communication bridge between
+ * the executor, plugins, and the task being executed.
+ *
+ * Main features:
+ * - Parameter management: Read and update execution parameters
+ *   - Type-safe parameter access through generic type `T`
+ *   - Immutable read access via `parameters` property
+ *   - Safe updates via `setParameters()` with internal cloning
+ *   - Prevents accidental parameter mutation
+ *
+ * - Error tracking: Store and retrieve error state
+ *   - Captures errors from task execution
+ *   - Accessible to error handling plugins
+ *   - Supports any error type (Error, string, object, etc.)
+ *   - Automatically converts to ExecutorError
+ *
+ * - Return value handling: Access task return values
+ *   - Type-safe return value through generic type `R`
+ *   - Available to afterHooks for result transformation
+ *   - Undefined until task completes successfully
+ *
+ * - Runtime metadata: Track execution timing and state
+ *   - Extensible runtime information via `RuntimesType`
+ *   - Hook execution tracking
+ *   - Performance monitoring support
+ *   - Custom metadata storage
+ *
+ * Design considerations:
+ * - Immutable core properties: `parameters`, `error`, `returnValue` are read-only
+ * - Safe mutation methods: `setParameters()`, `setError()`, `setReturnValue()`
+ * - Generic type safety: Full type inference for parameters and return values
+ * - Extensible runtimes: Custom runtime metadata via `RuntimesType` generic
+ *
+ * @since `3.0.0`
+ * @template T - Type of execution parameters
+ * @template R - Type of return value (required for type safety)
+ * @template RuntimesType - Type of hook runtimes (extends `HookRuntimes`, defaults to `HookRuntimes`)
+ *
+ * @example Basic usage
+ * ```typescript
+ * interface UserParams {
+ *   userId: number;
+ *   action: string;
+ * }
+ *
+ * interface UserResult {
+ *   success: boolean;
+ *   data: User;
+ * }
+ *
+ * const context: ExecutorContextInterface<UserParams, UserResult> =
+ *   new ExecutorContextImpl({ userId: 123, action: 'fetch' });
+ *
+ * console.log(context.parameters.userId); // 123
+ * ```
+ *
+ * @example In plugin hooks
+ * ```typescript
+ * const plugin: LifecyclePluginInterface<ExecutorContextInterface<UserParams, UserResult>> = {
+ *   pluginName: 'logger',
+ *
+ *   onBefore: async (ctx) => {
+ *     console.log('Starting with:', ctx.parameters);
+ *     // Add timestamp to parameters
+ *     ctx.setParameters({
+ *       ...ctx.parameters,
+ *       timestamp: Date.now()
+ *     });
+ *   },
+ *
+ *   onAfter: async (ctx, result) => {
+ *     console.log('Completed with:', ctx.returnValue);
+ *     return result;
+ *   },
+ *
+ *   onError: async (ctx, error) => {
+ *     console.error('Failed with:', ctx.error);
+ *     throw error;
+ *   }
+ * };
+ * ```
+ *
+ * @example Parameter transformation
+ * ```typescript
+ * const executor = new LifecycleExecutor();
+ *
+ * executor.use({
+ *   pluginName: 'validator',
+ *   onBefore: async (ctx) => {
+ *     // Validate and transform parameters
+ *     const validated = validateParams(ctx.parameters);
+ *     ctx.setParameters(validated);
+ *   }
+ * });
+ *
+ * const result = await executor.exec(
+ *   { userId: '123' }, // String input
+ *   async (ctx) => {
+ *     // ctx.parameters.userId is now validated and transformed
+ *     return await fetchUser(ctx.parameters.userId);
+ *   }
+ * );
+ * ```
+ *
+ * @example Error handling
+ * ```typescript
+ * executor.use({
+ *   pluginName: 'errorHandler',
+ *   onError: async (ctx, error) => {
+ *     // Access error from context
+ *     console.error('Task failed:', ctx.error);
+ *
+ *     // Transform error
+ *     if (ctx.error instanceof NetworkError) {
+ *       throw new UserFriendlyError('Network connection failed');
+ *     }
+ *     throw error;
+ *   }
+ * });
+ * ```
+ *
+ * @example With unknown return type
+ * ```typescript
+ * // When return type is not known in advance
+ * const context: ExecutorContextInterface<UserParams, unknown> =
+ *   new ExecutorContextImpl(params);
+ * ```
+ *
+ * @example Extended runtimes
+ * ```typescript
+ * interface CustomRuntimes extends HookRuntimes {
+ *   executionTime: number;
+ *   memoryUsage: number;
+ *   cacheHits: number;
+ * }
+ *
+ * const context: ExecutorContextInterface<UserParams, UserResult, CustomRuntimes> =
+ *   new ExecutorContextImpl(params);
+ *
+ * // Access custom runtime metadata
+ * console.log(context.runtimes.executionTime);
+ * ```
+ *
+ * @see {@link ExecutorHookRuntimesInterface} for runtime metadata interface
+ * @see {@link ExecutorContextImpl} for default implementation
+ */
+interface ExecutorContextInterface<T, R = unknown, RuntimesType extends HookRuntimes = HookRuntimes> extends ExecutorHookRuntimesInterface<RuntimesType> {
+    /**
+     * Read-only access to execution parameters
+     *
+     * Provides immutable access to the current parameters. To modify parameters,
+     * use `setParameters()` method which ensures safe cloning.
+     *
+     * @example
+     * ```typescript
+     * console.log(ctx.parameters.userId);
+     * console.log(ctx.parameters.action);
+     * ```
+     */
+    readonly parameters: T;
+    /**
+     * Current error state, if any
+     *
+     * Contains the error that occurred during task execution. Only populated
+     * when an error is thrown. Accessible in error handling hooks.
+     *
+     * @example
+     * ```typescript
+     * onError: (ctx, error) => {
+     *   if (ctx.error instanceof NetworkError) {
+     *     console.log('Network error occurred');
+     *   }
+     * }
+     * ```
+     */
+    readonly error: unknown;
+    /**
+     * Task return value
+     *
+     * Contains the value returned by the task after successful execution.
+     * Undefined until the task completes. Accessible in afterHooks for
+     * result transformation.
+     *
+     * @example
+     * ```typescript
+     * onAfter: (ctx, result) => {
+     *   console.log('Task returned:', ctx.returnValue);
+     *   // Transform result
+     *   return { ...result, timestamp: Date.now() };
+     * }
+     * ```
+     */
+    readonly returnValue: R | undefined;
+    /**
+     * Set the error state
+     *
+     * Stores an error in the context for access by error handling plugins.
+     * Accepts any type of error value and converts it to `ExecutorError`.
+     * This matches the behavior of JavaScript's catch clause which can catch any type.
+     *
+     * @param error - Error to set (can be any type: Error, string, object, etc.)
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await riskyOperation();
+     * } catch (error) {
+     *   ctx.setError(error);
+     * }
+     * ```
+     */
+    setError(error: unknown): void;
+    /**
+     * Set the return value
+     *
+     * Stores the task's return value in the context. Typically called by
+     * the executor after task completion, but can be used by plugins to
+     * override the return value.
+     *
+     * @param value - Return value to set
+     *
+     * @example
+     * ```typescript
+     * onAfter: (ctx, result) => {
+     *   // Override return value
+     *   ctx.setReturnValue({ ...result, enhanced: true });
+     *   return ctx.returnValue;
+     * }
+     * ```
+     */
+    setReturnValue(value: unknown): void;
+    /**
+     * Update parameters (clones internally for safety)
+     *
+     * Updates the execution parameters with a new value. The parameters are
+     * cloned internally to prevent accidental mutation. This ensures that
+     * plugins cannot inadvertently affect each other's parameter views.
+     *
+     * @param params - New parameters to set
+     *
+     * @example
+     * ```typescript
+     * onBefore: (ctx) => {
+     *   // Add authentication token
+     *   ctx.setParameters({
+     *     ...ctx.parameters,
+     *     authToken: getAuthToken()
+     *   });
+     * }
+     * ```
+     *
+     * @example Parameter validation
+     * ```typescript
+     * onBefore: (ctx) => {
+     *   const validated = validateAndTransform(ctx.parameters);
+     *   ctx.setParameters(validated);
+     * }
+     * ```
+     */
+    setParameters(params: T): void;
+}
+
+type LifecycleErrorResult = ExecutorError | Error | void;
+type LifecycleExecResult<R, Param> = R | ExecutorTask<R, Param> | void;
+/**
+ * Lifecycle plugin interface for executor plugins
+ *
+ * Purpose:
+ * This interface extends ExecutorPluginInterface and adds standardized lifecycle hook methods
+ * that plugins can implement to participate in the executor's execution pipeline.
+ * It serves as the default plugin type for LifecycleExecutor.
+ *
+ * Key Lifecycle Hooks:
+ *
+ * - onBefore: Pre-execution hook that can modify parameters
+ *   - Can return new parameters to update context
+ *   - Supports both sync and async return values
+ *   - More flexible than direct parameter modification
+ *
+ * - onSuccess: Post-execution hook for result processing
+ *   - Executed after successful task completion
+ *   - Can transform or log results
+ *   - Supports both sync and async execution
+ *
+ * - onError: Error handling hook
+ *   - Executed when errors occur
+ *   - Can handle, transform, or log errors
+ *   - Supports both sync and async execution
+ *
+ * - onExec: Task modification hook
+ *   - Can modify or wrap the task
+ *   - Supports both sync and async task modifications
+ *
+ * - onFinally: Cleanup hook
+ *   - Always executed after task completion
+ *   - Guaranteed to run regardless of success or failure
+ *   - Supports both sync and async execution
+ *
+ * Enhanced onBefore Hook:
+ * - Return Value Support: Can return new parameters to update context
+ *   ```typescript
+ *   onBefore: (ctx) => {
+ *     // Return new parameters - automatically updates context
+ *     return { ...ctx.parameters, newField: 'value' };
+ *   }
+ *   ```
+ *
+ * - Type Safety: Return type inferred from context parameter type
+ *   - TypeScript automatically infers correct return type
+ *   - Compile-time type checking
+ *   - Better IDE support
+ *
+ * Default Plugin Type for LifecycleExecutor:
+ * - Type Constraint: LifecycleExecutor defaults to this interface
+ *   - Ensures plugins implement lifecycle hooks
+ *   - Better type safety
+ *   - Clearer plugin contract
+ *
+ * - Backward Compatibility: Extends ExecutorPluginInterface
+ *   - Compatible with existing plugin implementations
+ *   - Can be used with other executor types
+ *   - Gradual migration path
+ *
+ * Usage with LifecycleExecutor:
+ *
+ * Default Usage (Recommended):
+ * ```typescript
+ * const executor = new LifecycleExecutor();
+ * // Plugin type defaults to LifecyclePluginInterface
+ * executor.use({
+ *   pluginName: 'myPlugin',
+ *   enabled: () => true,
+ *   onBefore: (ctx) => {
+ *     return { ...ctx.parameters, timestamp: Date.now() };
+ *   }
+ * });
+ * ```
+ *
+ * Explicit Type Usage:
+ * ```typescript
+ * interface MyPlugin extends LifecyclePluginInterface<ExecutorContextInterface<MyParams, MyResult>> {
+ *   customMethod(): void;
+ * }
+ *
+ * const executor = new LifecycleExecutor<
+ *   ExecutorContextInterface<MyParams, MyResult>,
+ *   MyPlugin
+ * >();
+ * ```
+ *
+ * Benefits:
+ * - Type Safety: Stronger type constraints than generic ExecutorPluginInterface
+ * - Clear Contract: Explicit lifecycle hook definitions
+ * - Better IDE Support: Improved autocomplete and type checking
+ * - Parameter Safety: Supports safe parameter updates via return values
+ * - Unified API: Consistent interface across all lifecycle hooks
+ *
+ * @since 3.0.0
+ * @template Ctx - Type of executor context interface
+ *
+ * @example Basic lifecycle plugin
+ * ```typescript
+ * const plugin: LifecyclePluginInterface<ExecutorContextInterface<UserParams, UserResult>> = {
+ *   pluginName: 'userPlugin',
+ *   enabled: () => true,
+ *   onBefore: (ctx) => {
+ *     // Modify parameters via return value
+ *     return { ...ctx.parameters, timestamp: Date.now() };
+ *   },
+ *   onSuccess: (ctx) => {
+ *     console.log('Task completed:', ctx.returnValue);
+ *   },
+ *   onError: (ctx) => {
+ *     console.error('Error occurred:', ctx.error);
+ *   }
+ * };
+ * ```
+ *
+ * @example onBefore returning new parameters (async)
+ * ```typescript
+ * const plugin: LifecyclePluginInterface<ExecutorContextInterface<ApiParams, ApiResult>> = {
+ *   onBefore: async (ctx) => {
+ *     const apiKey = await fetchApiKey();
+ *     // Return new parameters - automatically updates context
+ *     return { ...ctx.parameters, apiKey };
+ *   }
+ * };
+ * ```
+ *
+ * @see LifecycleExecutor - Executor that uses this as default plugin type
+ * @see ExecutorPluginInterface - Base plugin interface
+ * @see ExecutorContextInterface - Context interface used by plugins
+ *
+ * @category Plugin
+ */
+interface LifecyclePluginInterface<Ctx extends ExecutorContextInterface<unknown, unknown>, Result = Ctx['returnValue'], Param = Ctx['parameters']> extends ExecutorPluginInterface<Ctx> {
+    /**
+     * Hook executed before the main task
+     * Can modify the input data before it reaches the task
+     *
+     * Return value behavior:
+     * - If returns a value (non-void), it will be used to update context parameters
+     * - If returns void or undefined, parameters remain unchanged
+     * - Supports both sync and async return values
+     *
+     * @param ctx - Execution context
+     * @returns Modified parameters (will update context parameters), void, or Promise of either
+     */
+    onBefore?(ctx: Ctx): Param | Promise<Param> | void | Promise<void>;
+    /**
+     * Hook executed after successful task completion
+     * Can transform the task result
+     *
+     * @param ctx - Execution context
+     * @returns void or Promise<void>
+     */
+    onSuccess?(ctx: Ctx): void | Promise<void>;
+    /**
+     * Error handling hook
+     * - For `exec`: returning a value or throwing will break the chain
+     * - For `execNoError`: returning a value or throwing will return the error
+     *
+     * Because `onError` can break the chain, best practice is each plugin only handle plugin related error
+     *
+     * @param ctx - Execution context containing error information
+     * @returns ExecutorError, Error, void, or Promise of either
+     */
+    onError?(ctx: Ctx): LifecycleErrorResult | Promise<LifecycleErrorResult>;
+    /**
+     * Custom execution logic hook
+     *
+     * Purpose:
+     * Allows plugins to intercept, wrap, or replace the task execution.
+     * Plugins can return a value directly, return a new task function, or execute
+     * the task within the hook.
+     *
+     * Return value behavior:
+     * - If returns a function (ExecutorTask): The function will be executed as the new task
+     * - If returns any other value: The value will be used as the task result (skips task execution)
+     * - Supports both sync and async return values
+     *
+     * Type inference:
+     * - The return type `R` is automatically inferred from the task parameter
+     * - Return values are type-safe and match the task's return type
+     * - TypeScript can infer types from return statements without explicit annotations
+     *
+     * Use cases:
+     * - Return a wrapped task function to add middleware behavior
+     * - Return a direct value to bypass task execution
+     * - Execute the task with custom logic and return the result
+     *
+     * @template R - Return type of the task (automatically inferred from task parameter)
+     * @param ctx - Execution context
+     * @param task - Original task to be executed
+     * @returns Task result (type R), modified task function, or Promise of either
+     *
+     * @example Return a direct value (bypass task) - type automatically inferred
+     * ```typescript
+     * onExec: async () => {
+     *   return 'intercepted-result'; // Type inferred as Promise<string>
+     * }
+     * ```
+     *
+     * @example Return a wrapped task function
+     * ```typescript
+     * onExec: (ctx, task) => {
+     *   // Return a new task function that wraps the original
+     *   return async (wrappedCtx) => {
+     *     console.log('Before task execution');
+     *     const result = await task(wrappedCtx);
+     *     console.log('After task execution');
+     *     return result;
+     *   };
+     * }
+     * ```
+     *
+     * @example Return a direct value (bypass task)
+     * ```typescript
+     * onExec: (ctx, task) => {
+     *   // Return cached result, skip task execution
+     *   if (cache.has(ctx.parameters.id)) {
+     *     return cache.get(ctx.parameters.id);
+     *   }
+     *   // Or execute task and return result
+     *   return task(ctx);
+     * }
+     * ```
+     *
+     * 如果需要手动覆盖返回类型，可以使用提供的 R 泛型手动推断类型，但是这样不够安全，
+     * 未来可能会加入接口类型的泛型
+     *
+     * @example 使用手动推断类型
+     * ```typescript
+     * interface TestResult {
+     *   data: string;
+     *   processed?: boolean;
+     * }
+     *
+     * type TestContext = ExecutorContextInterface<TestParams>;
+     *
+     * const plugin: LifecyclePluginInterface<TestContext> = {
+     *   pluginName: 'plugin',
+     *   onExec: async <R>(ctx, task) => {
+     *     const result = await task(ctx);
+     *     return `wrapped: ${result}` as R;
+     *   }
+     * };
+     * ```
+     */
+    onExec?: (ctx: Ctx, task: ExecutorTask<Result, Param>) => LifecycleExecResult<Result, Param> | Promise<LifecycleExecResult<Result, Param>>;
+    /**
+     * Hook executed in finally block after task execution
+     *
+     * Purpose:
+     * Allows plugins to perform cleanup operations that must run regardless
+     * of whether the task succeeded or failed. Supports both sync and async execution.
+     *
+     * Execution Guarantees:
+     * - Always executed after task completion (success or error)
+     * - Executed in finally block, ensuring cleanup even if errors occur
+     * - Runs after onSuccess or onError hooks
+     * - Cannot prevent error propagation
+     *
+     * Use Cases:
+     * - Resource cleanup
+     * - Logging completion status
+     * - Resetting state
+     * - Closing connections
+     * - Finalizing transactions
+     *
+     * @param ctx - Execution context (may contain error if task failed)
+     * @returns void or Promise<void>
+     *
+     * @example Resource cleanup
+     * ```typescript
+     * onFinally: async (ctx) => {
+     *   if (ctx.parameters.connection) {
+     *     await ctx.parameters.connection.close();
+     *   }
+     * }
+     * ```
+     *
+     * @example Logging completion
+     * ```typescript
+     * onFinally: (ctx) => {
+     *   const status = ctx.error ? 'failed' : 'succeeded';
+     *   console.log(`Task ${status}`);
+     * }
+     * ```
+     */
+    onFinally?(ctx: Ctx): void | Promise<void>;
+}
+
+/**
+ * Base implementation of ExecutorContextInterface that integrates ContextHandler functionality
+ *
+ * ## Core Concept
+ * Provides a complete implementation of the executor context interface, integrating
+ * all context management functionality that was previously handled by ContextHandler.
+ * This eliminates the need for a separate ContextHandler class and centralizes
+ * all context-related operations in a single class.
+ *
+ * Key Differences from Original Implementation:
+ *
+ * No Separate ContextHandler:
+ * - Integrated Functionality: All ContextHandler methods integrated into context
+ *   - Original: Separate ContextHandler class managed context state
+ *   - New: All functionality in ExecutorContextImpl
+ *   - Benefits: Simpler API, fewer dependencies, clearer ownership
+ *
+ * - Direct Method Access: All methods available directly on context
+ *   - No need to pass context to handler methods
+ *   - More intuitive API
+ *   - Better encapsulation
+ *
+ * Parameter Handling (Reference-Based):
+ * - **No Cloning**: Parameters are stored by reference, not cloned
+ *   - Original: Parameters were cloned automatically
+ *   - New: Parameters are used directly (zero overhead)
+ *   - Benefits: Better performance, user control, predictable behavior
+ *
+ * - **User Responsibility**: Users must clone parameters if isolation is needed
+ *   - If you need isolation: `new ExecutorContextImpl({ ...params })`
+ *   - If you don't need isolation: `new ExecutorContextImpl(params)`
+ *   - Trade-off: More control vs. more responsibility
+ *
+ * - **Performance**: Zero cloning overhead
+ *   - No Object.assign or spread operations
+ *   - No memory allocation for parameter copies
+ *   - Ideal for high-performance scenarios
+ *
+ * Enhanced Runtime Tracking:
+ * - Integrated Tracking: All runtime tracking in context
+ *   - Plugin execution metadata
+ *   - Hook execution tracking
+ *   - Chain breaking state
+ *   - Return value tracking
+ *
+ * - Better Debugging: Comprehensive runtime information
+ *   - Track which plugins executed
+ *   - Track execution order
+ *   - Track return values
+ *   - Track chain breaking conditions
+ *
+ * Improved API Design:
+ * - Consistent Naming: All methods follow consistent naming conventions
+ * - Type Safety: Strong typing throughout
+ * - Clear Responsibilities: Each method has a single, clear purpose
+ * - Better Documentation: Comprehensive JSDoc comments
+ *
+ * Main Features:
+ * - Context state management: Manages parameters, error, and return value
+ * - Plugin runtime tracking: Tracks plugin execution metadata
+ * - Chain control: Manages execution chain breaking conditions
+ * - Error handling: Context error state management
+ * - Hook validation: Checks plugin hook availability and enablement
+ * - Reference-based parameters: No automatic cloning (user control)
+ * - High performance: Zero overhead parameter handling
+ *
+ * Parameter Handling (Important):
+ *
+ * **No Automatic Cloning**:
+ * - Parameters are stored by reference
+ * - Modifications affect the original object
+ * - Users must clone parameters themselves if isolation is needed
+ *
+ * **Usage Examples**:
+ * ```typescript
+ * // Without isolation (parameters will be modified)
+ * const params = { userId: 123, data: 'test' };
+ * const context = new ExecutorContextImpl(params);
+ * context.setParameters({ userId: 456 });
+ * console.log(params.userId); // 456 - original modified
+ *
+ * // With isolation (clone parameters first)
+ * const params = { userId: 123, data: 'test' };
+ * const context = new ExecutorContextImpl({ ...params }); // shallow clone
+ * context.setParameters({ userId: 456 });
+ * console.log(params.userId); // 123 - original unchanged
+ * ```
+ *
+ * **Performance**:
+ * - Constructor: Zero overhead (no cloning)
+ * - Getter: Direct return (zero overhead)
+ * - setParameters: Zero overhead (no cloning)
+ *
+ * Design Considerations:
+ * - Integrates ContextHandler functionality directly into the context
+ * - Provides all methods needed for executor plugin lifecycle management
+ * - Maintains backward compatibility with existing ExecutorContext interface
+ * - Eliminates the need for separate ContextHandler instance
+ * - Delegates parameter isolation responsibility to users
+ * - Optimized for maximum performance with zero-overhead parameter handling
+ *
+ * @since 3.0.0
+ * @template T - Type of context parameters
+ *
+ * @example Basic usage
+ * ```typescript
+ * const context = new ExecutorContextImpl({ userId: 123, data: 'test' });
+ *
+ * // Use context methods directly
+ * context.setReturnValue('result');
+ * context.runtimes(plugin, 'onBefore', 0);
+ * if (context.shouldBreakChain()) {
+ *   // Handle chain breaking
+ * }
+ * ```
+ *
+ * @example Parameter isolation
+ * ```typescript
+ * const originalParams = { value: 'original' };
+ * const context = new ExecutorContextImpl(originalParams);
+ *
+ * // Parameters are cloned - modifications don't affect original
+ * const params = context.parameters;
+ * params.value = 'modified';
+ * expect(originalParams.value).toBe('original'); // Original unchanged
+ * ```
+ *
+ * @example With error handling
+ * ```typescript
+ * const context = new ExecutorContextImpl(data);
+ *
+ * try {
+ *   // Execute some operation
+ * } catch (error) {
+ *   context.setError(new ExecutorError('ERROR_CODE', error));
+ * }
+ *
+ * if (context.error) {
+ *   // Handle error
+ * }
+ * ```
+ *
+ * @see ExecutorContextInterface - Interface that this class implements
+ * @see LifecycleExecutor - Executor that uses this context implementation
+ *
+ * @category ExecutorContextImpl
+ */
+declare class ExecutorContextImpl<T, R = unknown, RuntimesType extends HookRuntimes = HookRuntimes> implements ExecutorContextInterface<T, R, RuntimesType> {
+    private _parameters;
+    private _error;
+    private _returnValue?;
+    /**
+     * Creates a new ExecutorContextImpl instance
+     *
+     * **Important**: Parameters are stored by reference, not cloned.
+     * If you need parameter isolation, clone them before passing to the constructor.
+     *
+     * @param parameters - The initial parameters for the context
+     *
+     * @example Without isolation (parameters will be modified)
+     * ```typescript
+     * const params = { value: 1 };
+     * const context = new ExecutorContextImpl(params);
+     * context.setParameters({ value: 2 });
+     * console.log(params.value); // 2 - original object is modified
+     * ```
+     *
+     * @example With isolation (clone parameters first)
+     * ```typescript
+     * const params = { value: 1 };
+     * const context = new ExecutorContextImpl({ ...params }); // shallow clone
+     * context.setParameters({ value: 2 });
+     * console.log(params.value); // 1 - original object is unchanged
+     * ```
+     */
+    constructor(parameters: T);
+    /**
+     * Get the context parameters
+     *
+     * **Important**: Returns the parameters by reference.
+     * Modifications to the returned object will affect the context's internal state.
+     *
+     * @override
+     * @returns The parameters object (by reference)
+     */
+    get parameters(): T;
+    /**
+     * Get the error, if any
+     *
+     * @override
+     * @returns The error, if any
+     */
+    get error(): unknown;
+    /**
+     * Get the return value, if any
+     *
+     * @override
+     * @returns The return value, if any
+     */
+    get returnValue(): R | undefined;
+    /**
+     * Get read-only snapshot of hooks runtime information
+     *
+     * Core concept:
+     * Provides safe read-only access to runtime tracking information.
+     * Returns a frozen shallow copy to prevent accidental modifications.
+     *
+     * Security features:
+     * - Stored in WeakMap, truly private (cannot access via ._hooksRuntimes)
+     * - Returns a new frozen object (not the internal reference)
+     * - Object is frozen to prevent modifications
+     * - Setter throws error to prevent assignment
+     *
+     * Why WeakMap?
+     * - TypeScript's `private` is only compile-time protection
+     * - JavaScript runtime can still access `._hooksRuntimes`
+     * - WeakMap provides true runtime privacy
+     * - No way to access the internal state from outside
+     *
+     * @override
+     * @returns Frozen shallow copy of hook runtime state
+     *
+     * @example Safe read access
+     * ```typescript
+     * const runtimes = context.hooksRuntimes;
+     * console.log(`Hook ${runtimes.hookName} executed ${runtimes.times} times`);
+     * ```
+     *
+     * @example Modification attempts fail
+     * ```typescript
+     * const runtimes = context.hooksRuntimes;
+     * runtimes.times = 10; // Error: Cannot assign to read only property
+     * context.hooksRuntimes = {}; // Error: hooksRuntimes is read-only
+     * context._hooksRuntimes; // undefined - truly private!
+     * ```
+     */
+    get hooksRuntimes(): Readonly<RuntimesType>;
+    /**
+     * Set error in context
+     *
+     * Automatically converts standard Error objects to ExecutorError for consistency.
+     * If the error is already an ExecutorError, it is stored as-is.
+     * If the error is a standard Error, it is wrapped in an ExecutorError with id 'EXECUTOR_ERROR'.
+     *
+     * @override
+     * @param error - The error to set in context (ExecutorError or standard Error)
+     *
+     * @example With ExecutorError
+     * ```typescript
+     * context.setError(new ExecutorError('VALIDATION_ERROR', 'Invalid input'));
+     * console.log(context.error.id); // 'VALIDATION_ERROR'
+     * ```
+     *
+     * @example With standard Error (auto-converted)
+     * ```typescript
+     * try {
+     *   JSON.parse('invalid');
+     * } catch (error) {
+     *   context.setError(error); // Auto-converted to ExecutorError
+     *   console.log(context.error.id); // 'EXECUTOR_ERROR'
+     *   console.log(context.error.cause); // Original SyntaxError
+     * }
+     * ```
+     */
+    setError(error: unknown): void;
+    /**
+     * Set return value in context
+     *
+     * @override
+     * @param value - The value to set as return value
+     */
+    setReturnValue(value: R): void;
+    /**
+     * Set parameters in context
+     *
+     * **Important**: Parameters are stored by reference, not cloned.
+     * The provided parameters object will be used directly.
+     *
+     * @override
+     * @param params - The parameters to set (stored by reference)
+     *
+     * @example
+     * ```typescript
+     * const newParams = { value: 2 };
+     * context.setParameters(newParams);
+     * // context.parameters === newParams (same reference)
+     * ```
+     */
+    setParameters(params: T): void;
+    /**
+     * Reset hooks runtime state to initial values
+     *
+     * Core concept:
+     * Clears all runtime tracking information for fresh execution
+     *
+     * Reset operations:
+     * - Clears plugin name and hook name
+     * - Resets return value and chain breaking flags
+     * - Resets execution counter and index
+     *
+     * @override
+     */
+    resetHooksRuntimes(hookName?: string): void;
+    /**
+     * Reset entire context to initial state
+     *
+     * Core concept:
+     * Complete context cleanup for new execution cycle
+     *
+     * Reset operations:
+     * - Resets hooks runtime state
+     * - Clears return value
+     * - Clears error state
+     *
+     * @override
+     */
+    reset(): void;
+    /**
+     * Check if a plugin hook should be skipped
+     * Returns true if the hook should be skipped (invalid or disabled)
+     *
+     * Core concept:
+     * Plugin hook validation and enablement checking
+     *
+     * Validation criteria:
+     * - Hook method exists and is callable
+     * - Plugin is enabled for the specific hook
+     * - Plugin enablement function returns true
+     *
+     * @override
+     * @template Ctx - Type of task context
+     * @param plugin - The plugin to check
+     * @param hookName - The name of the hook to validate
+     * @returns True if the hook should be skipped, false otherwise
+     */
+    shouldSkipPluginHook<Ctx extends ExecutorContextInterface<unknown, unknown>>(plugin: ExecutorPluginInterface<Ctx>, hookName: string): boolean;
+    /**
+     * Update runtime tracking information for plugin execution
+     *
+     * Core concept:
+     * Track plugin execution metadata for debugging and flow control.
+     * Creates a new runtime object with merged updates to ensure immutability.
+     *
+     * Security:
+     * - Always creates a new object (immutable updates)
+     * - Stored in WeakMap (truly private)
+     * - Cannot be accessed or modified from outside
+     *
+     * Tracking information:
+     * - Current plugin name
+     * - Current hook name
+     * - Execution counter (times)
+     * - Plugin index in execution chain
+     *
+     * @override
+     * @param updates - Partial runtime updates to merge
+     * @example
+     * ```typescript
+     * context.runtimes({
+     *   pluginName: 'testPlugin',
+     *   hookName: 'onBefore',
+     *   times: 1,
+     *   pluginIndex: 0
+     * });
+     * ```
+     */
+    runtimes(updates: Partial<HookRuntimes>): void;
+    /**
+     * Set return value in context runtime tracking
+     *
+     * Core concept:
+     * Store plugin hook return value for chain control and debugging.
+     * Creates a new runtime object with updated return value.
+     *
+     * Security:
+     * - Creates new object (immutable update)
+     * - Stored in WeakMap (truly private)
+     *
+     * Usage scenarios:
+     * - Track plugin hook return values
+     * - Enable chain breaking based on return values
+     * - Debug plugin execution flow
+     *
+     * @override
+     * @param returnValue - The value to set as return value
+     */
+    runtimeReturnValue(returnValue: unknown): void;
+    /**
+     * Check if the execution chain should be broken
+     *
+     * Core concept:
+     * Chain breaking control for plugin execution flow
+     *
+     * Chain breaking scenarios:
+     * - Plugin explicitly sets breakChain flag
+     * - Error conditions requiring immediate termination
+     * - Business logic requiring early exit
+     *
+     * @override
+     * @returns True if the chain should be broken, false otherwise
+     */
+    shouldBreakChain(): boolean;
+    /**
+     * Check if the execution chain should be broken due to return value
+     *
+     * Core concept:
+     * Return value-based chain breaking control
+     *
+     * Usage scenarios:
+     * - Plugin returns a value that should terminate execution
+     * - Error handling hooks return error objects
+     * - Business logic requires return value-based flow control
+     *
+     * @override
+     * @returns True if the chain should be broken due to return value, false otherwise
+     */
+    shouldBreakChainOnReturn(): boolean;
+    /**
+     * Check if execution should continue on error
+     *
+     * Core concept:
+     * Determines whether to continue executing subsequent plugins when a plugin hook
+     * throws an error, enabling resilient execution pipelines
+     *
+     * @override
+     * @returns True if execution should continue on error, false otherwise
+     */
+    shouldContinueOnError(): boolean;
+}
+
+/**
+ * Enhanced script context that provides environment management and configuration utilities
+ *
+ * Core concept:
+ * Provides a comprehensive script execution environment with integrated
+ * configuration management, environment variable handling, logging,
+ * and shell command execution capabilities.
+ *
+ * Main features:
+ * - Environment management: Integrated environment variable handling
+ *   - Automatic loading of .env files with configurable order
+ *   - Type-safe environment variable access with defaults
+ *   - Support for environment-specific configurations
+ *   - Integration with fe-config environment settings
+ *
+ * - Configuration management: Unified configuration access and merging
+ *   - Script-specific configuration sections
+ *   - Deep merging with default values
+ *   - Type-safe option access with nested path support
+ *   - Configuration validation and fallback handling
+ *
+ * - Logging system: Structured logging with timestamp formatting
+ *   - Configurable verbosity levels
+ *   - Timestamp formatting with timezone support
+ *   - Logger name identification for multi-script environments
+ *   - Console output with structured formatting
+ *
+ * - Shell integration: Command execution with dry run support
+ *   - Safe command execution with error handling
+ *   - Dry run mode for testing and validation
+ *   - Integrated logging for command output
+ *   - Support for custom execution functions
+ *
+ * Design considerations:
+ * - Uses lodash merge for deep configuration merging
+ * - Supports environment file loading with configurable order
+ * - Provides type-safe option access with fallback values
+ * - Implements proper error handling for missing configurations
+ * - Maintains backward compatibility with existing interfaces
+ * - Supports both development and production environments
  *
  * Performance optimizations:
  * - Lazy environment initialization
@@ -4321,6 +5516,25 @@ declare class ScriptContext<Opt extends ScriptSharedInterface> extends ExecutorC
      * detailed information display.
      */
     readonly verbose: boolean;
+    /**
+     * 该属性只是一个 parameters 的别名
+     *
+     * 当你需要设置最新的参数时可以直接使用 setParameters 方法
+     *
+     * @override
+     * @example
+     * ```ts
+     * context.setParameters({
+     *   target: 'production'
+     * });
+     *
+     * console.log(context.options);
+     * // { target: 'production' }
+     * console.log(context.parameters);
+     * // { target: 'production' }
+     * ```
+     */
+    get options(): Opt;
     /**
      * Creates a new ScriptContext instance with the specified configuration
      *
@@ -4368,10 +5582,6 @@ declare class ScriptContext<Opt extends ScriptSharedInterface> extends ExecutorC
      * ```
      */
     constructor(name: string, opts?: Partial<ScriptContextInterface<Opt>>);
-    /**
-     * @override
-     */
-    get options(): Opt;
     /**
      * Environment instance for variable access and management
      *
@@ -4457,8 +5667,9 @@ declare class ScriptContext<Opt extends ScriptSharedInterface> extends ExecutorC
      * });
      * // Merges nested build configuration
      * ```
+     *
      */
-    setOptions(options: Partial<Opt>): void;
+    setParameters(params: Partial<Opt>): void;
     /**
      * Retrieves environment variable with optional default value
      *
@@ -4558,7 +5769,7 @@ declare class ScriptContext<Opt extends ScriptSharedInterface> extends ExecutorC
      * // Returns the complete options object
      * ```
      */
-    getOptions<T = unknown>(key?: string | string[], defaultValue?: T): T;
+    getParameters<T = unknown>(key?: string | string[], defaultValue?: T): T;
 }
 
 /**
@@ -4796,7 +6007,7 @@ declare abstract class ScriptPlugin<Context extends ScriptContext<any>, Props ex
      * }
      * ```
      */
-    get options(): Props;
+    get config(): Props;
     /**
      * Determines whether a lifecycle method should be executed
      *
@@ -4822,7 +6033,7 @@ declare abstract class ScriptPlugin<Context extends ScriptContext<any>, Props ex
      * plugin.enabled('onExec', context);   // Returns true
      * ```
      */
-    enabled(_name: string, _context: Context): boolean;
+    enabled(name: string, _context: Context): boolean;
     /**
      * Retrieves configuration values with nested path support
      *
@@ -4854,7 +6065,7 @@ declare abstract class ScriptPlugin<Context extends ScriptContext<any>, Props ex
      * const plugins = this.getConfig<string[]>('plugins', []);
      * ```
      */
-    getConfig<T>(keys?: string | string[], defaultValue?: T): T;
+    getConfig<T>(keys?: keyof Props | (keyof Props)[], defaultValue?: T): T;
     /**
      * Updates plugin configuration with deep merging
      *
@@ -4950,7 +6161,7 @@ declare abstract class ScriptPlugin<Context extends ScriptContext<any>, Props ex
      * }
      * ```
      */
-    onExec?(_context: Context): void | Promise<void>;
+    onExec?(context: Context): void | Promise<void>;
     /**
      * Lifecycle method called after successful script execution
      *
@@ -4981,7 +6192,7 @@ declare abstract class ScriptPlugin<Context extends ScriptContext<any>, Props ex
      * }
      * ```
      */
-    onSuccess?(_context: Context): void | Promise<void>;
+    onSuccess?(context: Context): void | Promise<void>;
     /**
      * Lifecycle method called when script execution fails
      *
@@ -5014,7 +6225,7 @@ declare abstract class ScriptPlugin<Context extends ScriptContext<any>, Props ex
      * }
      * ```
      */
-    onError?(_context: Context): Promise<ExecutorError | void> | ExecutorError | Error | void;
+    onError?(context: Context): Promise<ExecutorError | void> | ExecutorError | Error | void;
     /**
      * Lifecycle method called after script execution
      *
@@ -5096,6 +6307,159 @@ declare abstract class ScriptPlugin<Context extends ScriptContext<any>, Props ex
      * ```
      */
     step<T>(options: StepOption<T>): Promise<T>;
+    /**
+     * Builds the shared step log prefix (plugin context + dry-run)
+     */
+    protected createStepLabel(label: string): string;
+}
+
+/**
+ * @module TemplateEngine
+ * @description Lightweight, safe template engine for variable interpolation.
+ *
+ * Supports path-based value lookup (e.g. `user.name`, `items[0].id`) without
+ * executing arbitrary JavaScript. Designed as a drop-in replacement for
+ * simple `lodash.template` use cases in scripts and configuration formatting.
+ *
+ * Default syntax: ES6 template-literal `${ path }`.
+ *
+ * @example Basic usage
+ * ```typescript
+ * const engine = new TemplateEngine();
+ * engine.render('Hello ${user.name}!', { user: { name: 'Alice' } });
+ * // => 'Hello Alice!'
+ * ```
+ *
+ * @example Reusable compiled renderer
+ * ```typescript
+ * const render = engine.compile('git clone ${repo.url}');
+ * render({ repo: { url: 'https://github.com/user/repo.git' } });
+ * ```
+ */
+/**
+ * Template engine configuration options.
+ */
+interface TemplateOptions {
+    /**
+     * Interpolation regex with exactly one capture group for the variable path.
+     * Defaults to {@link interpolatePreset.ES6}.
+     */
+    interpolate?: RegExp;
+    /**
+     * Required path prefix in templates (lodash `variable` option semantics).
+     * e.g. `variable: 'data'` → use `${data.user.name}` with `{ user: { name } }`.
+     */
+    variable?: string;
+    /** Default when value is missing (undefined/null) or path is invalid. */
+    defaultValue?: unknown | ((path: string, data: Record<string, unknown>) => unknown);
+    /** Escape HTML entities in output. Default false. */
+    escapeHtml?: boolean;
+    /** Serialize objects via JSON.stringify. Default true. */
+    stringifyObject?: boolean;
+    /** Keep original placeholder when value is missing. Default false. */
+    keepUnmatched?: boolean;
+    /** Block prototype keys and only read own properties. Default true. */
+    safePrototype?: boolean;
+}
+/** Compiled render function returned by {@link TemplateEngine.compile}. */
+type RenderFn = (data: Record<string, unknown>) => string;
+/**
+ * Built-in interpolation regex presets.
+ *
+ * Pass one of these to `new TemplateEngine({ interpolate })` when you need
+ * a syntax other than the default ES6-style delimiters.
+ *
+ * @example ES6 (default — no extra config needed)
+ * ```typescript
+ * new TemplateEngine().render('Hello ${name}!', { name: 'World' });
+ * ```
+ *
+ * @example Lodash / EJS style
+ * ```typescript
+ * new TemplateEngine({ interpolate: interpolatePreset.LODASH })
+ *   .render('Hello <%= name %>!', { name: 'World' });
+ * ```
+ *
+ * @example Mustache style
+ * ```typescript
+ * new TemplateEngine({ interpolate: interpolatePreset.MUSTACHE })
+ *   .render('Hello {{ name }}!', { name: 'World' });
+ * ```
+ */
+declare const interpolatePreset: {
+    /**
+     * ES6 template-literal style: `${ variable }`
+     *
+     * This is the default for {@link TemplateEngine}.
+     *
+     * @example
+     * ```typescript
+     * engine.render('${user.name}', { user: { name: 'Bob' } });
+     * ```
+     */
+    readonly ES6: RegExp;
+    /**
+     * Lodash / EJS style: `<%= variable %>`
+     *
+     * Useful when migrating existing lodash templates.
+     *
+     * @example
+     * ```typescript
+     * new TemplateEngine({ interpolate: interpolatePreset.LODASH })
+     *   .render('<%= repo.url %>', { repo: { url: 'https://example.com' } });
+     * ```
+     */
+    readonly LODASH: RegExp;
+    /**
+     * Mustache / Handlebars style: `{{ variable }}`
+     *
+     * @example
+     * ```typescript
+     * new TemplateEngine({ interpolate: interpolatePreset.MUSTACHE })
+     *   .render('{{ user.name }}', { user: { name: 'Alice' } });
+     * ```
+     */
+    readonly MUSTACHE: RegExp;
+};
+/**
+ * Lightweight template engine for safe variable interpolation.
+ *
+ * Features:
+ * - ES6 `${ path }` syntax by default
+ * - Nested path access and numeric array indices
+ * - Prototype pollution protection (`safePrototype`, enabled by default)
+ * - Compile-once, render-many for performance
+ *
+ * Does NOT execute `<% code %>` logic blocks or arbitrary JavaScript.
+ */
+declare class TemplateEngine {
+    private readonly options;
+    /**
+     * @param options - Engine configuration. All fields are optional;
+     *   defaults to ES6 `${}` interpolation with safe prototype access.
+     */
+    constructor(options?: TemplateOptions);
+    /**
+     * Compile a template into a reusable render function.
+     *
+     * Path parsing and validation happen once at compile time; subsequent
+     * renders only perform value lookup and string assembly.
+     *
+     * @param template - Template string containing placeholders
+     * @returns Render function bound to the compiled template
+     * @throws {TypeError} When template is not a string
+     */
+    compile(template: string): RenderFn;
+    /**
+     * Render a template in one shot.
+     *
+     * Convenience wrapper around `compile(template)(data)`.
+     * Prefer {@link compile} when the same template is rendered multiple times.
+     *
+     * @param template - Template string containing placeholders
+     * @param data - Context object for variable substitution
+     */
+    render(template: string, data: Record<string, any>): string;
 }
 
-export { ColorFormatter, ConfigSearch, type ConfigSearchOptions, type ExecPromiseFunction, type FeConfig, type FeReleaseConfig, ScriptContext, type ScriptContextInterface, ScriptPlugin, type ScriptPluginProps, type ScriptSharedInterface, Shell, type ShellConfig, type ShellExecOptions, type ShellInterface, type StepOption, defaultFeConfig };
+export { ColorFormatter, ConfigSearch, type ConfigSearchOptions, type ExecPromiseFunction, type FeConfig, type RenderFn, ScriptContext, type ScriptContextInterface, ScriptPlugin, type ScriptPluginProps, type ScriptSharedInterface, Shell, type ShellConfig, type ShellExecOptions, type ShellInterface, type StepOption, TemplateEngine, type TemplateOptions, defaultFeConfig, interpolatePreset };