@qlover/scripts-context 2.2.0 → 2.3.3

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { UserConfig } from '@commitlint/types';
+import { LoggerInterface, FormatterInterface, LogEvent } from '@qlover/logger';
 import { Env } from '@qlover/env-loader';
 import { ExecutorContextImpl, LifecyclePluginInterface, ExecutorContextInterface, ExecutorError } from '@qlover/fe-corekit';
 
@@ -41,1853 +42,9 @@ interface FeConfig {
      */
     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[];
-}
-
-/**
- * Represents a log event in the logging system
- *
- * This class encapsulates all information about a single log event,
- * including the log level, message arguments, timestamp, logger name,
- * and optional typed context data.
- *
- * Core features:
- * - Automatic timestamp generation
- * - Type-safe context support
- * - Flexible argument handling
- * - Logger identification
- *
- * @typeParam Ctx - Type of the context value, defaults to unknown
- *
- * @example Basic usage
- * ```typescript
- * const event = new LogEvent(
- *   'info',
- *   ['Application started'],
- *   'app'
- * );
- * // event.timestamp is automatically set
- * console.log(event);
- * ```
- *
- * @example With context
- * ```typescript
- * interface RequestContext {
- *   requestId: string;
- *   userId: string;
- *   path: string;
- * }
- *
- * const event = new LogEvent<RequestContext>(
- *   'info',
- *   ['Request processed', { duration: 150 }],
- *   'http',
- *   new LogContext({
- *     requestId: 'req-123',
- *     userId: 'user-456',
- *     path: '/api/users'
- *   })
- * );
- * ```
- *
- * @example Error event
- * ```typescript
- * const error = new Error('Database connection failed');
- * const event = new LogEvent(
- *   'error',
- *   [
- *     'Failed to connect to database',
- *     {
- *       error: error.message,
- *       stack: error.stack,
- *       code: 'DB_CONN_ERROR'
- *     }
- *   ],
- *   'database'
- * );
- * ```
- *
- * @example Performance monitoring
- * ```typescript
- * interface PerformanceContext {
- *   operation: string;
- *   startTime: number;
- *   endTime: number;
- *   metadata: Record<string, unknown>;
- * }
- *
- * const event = new LogEvent<PerformanceContext>(
- *   'debug',
- *   ['Operation completed'],
- *   'performance',
- *   new LogContext({
- *     operation: 'data-processing',
- *     startTime: 1679395845000,
- *     endTime: 1679395846000,
- *     metadata: {
- *       itemsProcessed: 1000,
- *       batchSize: 100,
- *       cacheHits: 850
- *     }
- *   })
- * );
- * ```
- */
-declare class LogEvent<Ctx = unknown> {
-    /**
-     * Log level indicating the severity or importance
-     *
-     * Common values:
-     * - 'fatal': System is unusable
-     * - 'error': Error conditions
-     * - 'warn': Warning conditions
-     * - 'info': Informational messages
-     * - 'debug': Debug-level messages
-     * - 'trace': Trace-level messages
-     *
-     * @example
-     * ```typescript
-     * new LogEvent('error', ['Database connection failed'], 'db');
-     * ```
-     */
-    level: string;
-    /**
-     * Array of log message arguments
-     *
-     * The first argument is typically the main message string,
-     * followed by optional data objects, error instances, or
-     * other relevant information.
-     *
-     * @example
-     * ```typescript
-     * // Simple message
-     * new LogEvent('info', ['User logged in'], 'auth');
-     *
-     * // Message with data
-     * new LogEvent('info', [
-     *   'User logged in',
-     *   { userId: 123, role: 'admin' }
-     * ], 'auth');
-     *
-     * // Error with details
-     * new LogEvent('error', [
-     *   'Operation failed',
-     *   new Error('Invalid input'),
-     *   { operation: 'validate', input: data }
-     * ], 'validator');
-     * ```
-     */
-    args: unknown[];
-    /**
-     * Name of the logger that created this event
-     *
-     * Used to identify the source or category of the log event.
-     * This can be a module name, service name, or any other
-     * identifier that helps categorize log events.
-     *
-     * @example
-     * ```typescript
-     * // Module-based names
-     * new LogEvent('info', ['Starting'], 'auth.service');
-     * new LogEvent('debug', ['Cache miss'], 'data.cache');
-     *
-     * // Component-based names
-     * new LogEvent('info', ['Render complete'], 'ui.dashboard');
-     * new LogEvent('error', ['API error'], 'api.users');
-     * ```
-     */
-    loggerName: string;
-    /**
-     * Optional typed context data for the log event
-     *
-     * Provides additional structured data that can be used by
-     * formatters and handlers. The context type is controlled
-     * by the Ctx type parameter.
-     *
-     * @example
-     * ```typescript
-     * // Request context
-     * interface RequestContext {
-     *   requestId: string;
-     *   path: string;
-     *   method: string;
-     * }
-     *
-     * new LogEvent<RequestContext>(
-     *   'info',
-     *   ['Request received'],
-     *   'http',
-     *   new LogContext({
-     *     requestId: 'req-123',
-     *     path: '/api/users',
-     *     method: 'GET'
-     *   })
-     * );
-     *
-     * // Performance context
-     * interface PerfContext {
-     *   duration: number;
-     *   memoryUsage: number;
-     * }
-     *
-     * new LogEvent<PerfContext>(
-     *   'debug',
-     *   ['Operation completed'],
-     *   'perf',
-     *   new LogContext({
-     *     duration: 150,
-     *     memoryUsage: process.memoryUsage().heapUsed
-     *   })
-     * );
-     * ```
-     */
-    context?: Ctx | undefined;
-    /**
-     * Timestamp when the log event was created
-     *
-     * Automatically set to the current time in milliseconds since the Unix epoch
-     * when the event is constructed. This ensures accurate timing information
-     * for each log entry.
-     *
-     * @example
-     * ```typescript
-     * const event = new LogEvent('info', ['message'], 'app');
-     * console.log(new Date(event.timestamp).toISOString());
-     * // Output: "2024-03-21T14:30:45.123Z"
-     * ```
-     */
-    timestamp: number;
-    constructor(
-    /**
-     * Log level indicating the severity or importance
-     *
-     * Common values:
-     * - 'fatal': System is unusable
-     * - 'error': Error conditions
-     * - 'warn': Warning conditions
-     * - 'info': Informational messages
-     * - 'debug': Debug-level messages
-     * - 'trace': Trace-level messages
-     *
-     * @example
-     * ```typescript
-     * new LogEvent('error', ['Database connection failed'], 'db');
-     * ```
-     */
-    level: string, 
-    /**
-     * Array of log message arguments
-     *
-     * The first argument is typically the main message string,
-     * followed by optional data objects, error instances, or
-     * other relevant information.
-     *
-     * @example
-     * ```typescript
-     * // Simple message
-     * new LogEvent('info', ['User logged in'], 'auth');
-     *
-     * // Message with data
-     * new LogEvent('info', [
-     *   'User logged in',
-     *   { userId: 123, role: 'admin' }
-     * ], 'auth');
-     *
-     * // Error with details
-     * new LogEvent('error', [
-     *   'Operation failed',
-     *   new Error('Invalid input'),
-     *   { operation: 'validate', input: data }
-     * ], 'validator');
-     * ```
-     */
-    args: unknown[], 
-    /**
-     * Name of the logger that created this event
-     *
-     * Used to identify the source or category of the log event.
-     * This can be a module name, service name, or any other
-     * identifier that helps categorize log events.
-     *
-     * @example
-     * ```typescript
-     * // Module-based names
-     * new LogEvent('info', ['Starting'], 'auth.service');
-     * new LogEvent('debug', ['Cache miss'], 'data.cache');
-     *
-     * // Component-based names
-     * new LogEvent('info', ['Render complete'], 'ui.dashboard');
-     * new LogEvent('error', ['API error'], 'api.users');
-     * ```
-     */
-    loggerName: string, 
-    /**
-     * Optional typed context data for the log event
-     *
-     * Provides additional structured data that can be used by
-     * formatters and handlers. The context type is controlled
-     * by the Ctx type parameter.
-     *
-     * @example
-     * ```typescript
-     * // Request context
-     * interface RequestContext {
-     *   requestId: string;
-     *   path: string;
-     *   method: string;
-     * }
-     *
-     * new LogEvent<RequestContext>(
-     *   'info',
-     *   ['Request received'],
-     *   'http',
-     *   new LogContext({
-     *     requestId: 'req-123',
-     *     path: '/api/users',
-     *     method: 'GET'
-     *   })
-     * );
-     *
-     * // Performance context
-     * interface PerfContext {
-     *   duration: number;
-     *   memoryUsage: number;
-     * }
-     *
-     * new LogEvent<PerfContext>(
-     *   'debug',
-     *   ['Operation completed'],
-     *   'perf',
-     *   new LogContext({
-     *     duration: 150,
-     *     memoryUsage: process.memoryUsage().heapUsed
-     *   })
-     * );
-     * ```
-     */
-    context?: Ctx | undefined);
-}
-
-/**
- * Interface for log event formatters
- *
- * Formatters are responsible for converting log events into specific output
- * formats. They can transform the event data into strings, objects, or arrays
- * suitable for the target output medium.
- *
- * Core responsibilities:
- * - Format log events into desired output format
- * - Support type-safe context handling
- * - Maintain consistent formatting across log entries
- * - Handle different log levels appropriately
- *
- * @typeParam Ctx - Type of the context value, defaults to unknown
- *
- * @example Basic string formatter
- * ```typescript
- * class SimpleFormatter implements FormatterInterface {
- *   format(event: LogEvent): string[] {
- *     const timestamp = new Date(event.timestamp).toISOString();
- *     const level = event.level.toUpperCase();
- *     const message = event.args.join(' ');
- *
- *     return [`[${timestamp}] ${level}: ${message}`];
- *   }
- * }
- * ```
- *
- * @example JSON formatter
- * ```typescript
- * class JSONFormatter implements FormatterInterface {
- *   format(event: LogEvent): string {
- *     return JSON.stringify({
- *       timestamp: event.timestamp,
- *       level: event.level,
- *       message: event.args[0],
- *       data: event.args.slice(1),
- *       context: event.context?.value
- *     });
- *   }
- * }
- * ```
- *
- * @example Type-safe context formatter
- * ```typescript
- * interface RequestContext {
- *   requestId: string;
- *   userId?: string;
- *   path: string;
- *   method: string;
- * }
- *
- * class RequestFormatter implements FormatterInterface<RequestContext> {
- *   format(event: LogEvent<RequestContext>): string[] {
- *     const ctx = event.context?.value;
- *     const prefix = ctx
- *       ? `[${ctx.method} ${ctx.path}] [${ctx.requestId}]`
- *       : '';
- *
- *     return [
- *       prefix,
- *       event.level.toUpperCase(),
- *       ...event.args
- *     ];
- *   }
- * }
- * ```
- *
- * @example Colored console formatter
- * ```typescript
- * class ColoredFormatter implements FormatterInterface {
- *   private colors = {
- *     error: '\x1b[31m',  // Red
- *     warn: '\x1b[33m',   // Yellow
- *     info: '\x1b[36m',   // Cyan
- *     debug: '\x1b[90m',  // Gray
- *     reset: '\x1b[0m'    // Reset
- *   };
- *
- *   format(event: LogEvent): unknown[] {
- *     const color = this.colors[event.level] || this.colors.reset;
- *     const timestamp = new Date(event.timestamp).toISOString();
- *
- *     return [
- *       `${color}[${timestamp}] ${event.level.toUpperCase()}:${this.colors.reset}`,
- *       ...event.args
- *     ];
- *   }
- * }
- * ```
- */
-interface FormatterInterface<Ctx = unknown> {
-    /**
-     * Formats a log event into the desired output format
-     *
-     * This method transforms a log event into a format suitable for output.
-     * The return value can be:
-     * - A single value (string, object, etc.)
-     * - An array of values (for handlers that support multiple arguments)
-     *
-     * Implementation considerations:
-     * - Handle all log levels consistently
-     * - Process context data appropriately
-     * - Maintain type safety with generic context
-     * - Consider performance for high-volume logging
-     *
-     * @param event - The log event to format
-     * @returns Formatted output as a single value or array of values
-     *
-     * @example String output
-     * ```typescript
-     * format(event: LogEvent): string {
-     *   const { timestamp, level, args } = event;
-     *   return `[${new Date(timestamp).toISOString()}] ${
-     *     level.toUpperCase()
-     *   }: ${args.join(' ')}`;
-     * }
-     * ```
-     *
-     * @example Array output for console
-     * ```typescript
-     * format(event: LogEvent): unknown[] {
-     *   const prefix = `[${event.level.toUpperCase()}]`;
-     *   return [prefix, ...event.args];
-     * }
-     * ```
-     *
-     * @example Structured output
-     * ```typescript
-     * format(event: LogEvent): object {
-     *   return {
-     *     '@timestamp': event.timestamp,
-     *     level: event.level,
-     *     message: event.args[0],
-     *     metadata: {
-     *       args: event.args.slice(1),
-     *       context: event.context?.value
-     *     }
-     *   };
-     * }
-     * ```
-     *
-     * @example Type-safe context handling
-     * ```typescript
-     * interface UserContext {
-     *   userId: string;
-     *   sessionId: string;
-     * }
-     *
-     * format(event: LogEvent<UserContext>): object {
-     *   const ctx = event.context?.value;
-     *   return {
-     *     timestamp: event.timestamp,
-     *     level: event.level,
-     *     message: event.args[0],
-     *     user: ctx ? {
-     *       id: ctx.userId,
-     *       session: ctx.sessionId
-     *     } : undefined
-     *   };
-     * }
-     * ```
-     */
-    format(event: LogEvent<Ctx>): unknown | unknown[];
-}
-
-/**
- * Interface for log event handlers (appenders)
- *
- * Handlers are responsible for processing and outputting log events to
- * various destinations (console, file, network, etc.). They can optionally
- * use formatters to customize the output format.
- *
- * Core responsibilities:
- * - Process log events
- * - Output logs to specific destinations
- * - Support optional formatting
- * - Handle different log levels
- *
- * @example Basic console handler
- * ```typescript
- * class ConsoleHandler implements HandlerInterface {
- *   private formatter: FormatterInterface | null = null;
- *
- *   append(event: LogEvent): void {
- *     const args = this.formatter
- *       ? this.formatter.format(event)
- *       : event.args;
- *
- *     console.log(...args);
- *   }
- *
- *   setFormatter(formatter: FormatterInterface): void {
- *     this.formatter = formatter;
- *   }
- * }
- * ```
- *
- * @example File handler with rotation
- * ```typescript
- * class RotatingFileHandler implements HandlerInterface {
- *   constructor(
- *     private filename: string,
- *     private maxSize: number = 10 * 1024 * 1024
- *   ) {}
- *
- *   append(event: LogEvent): void {
- *     const message = this.formatter
- *       ? this.formatter.format(event)
- *       : event.args.join(' ');
- *
- *     if (this.shouldRotate()) {
- *       this.rotate();
- *     }
- *     fs.appendFileSync(this.filename, message + '\n');
- *   }
- *
- *   setFormatter(formatter: FormatterInterface): void {
- *     this.formatter = formatter;
- *   }
- *
- *   private shouldRotate(): boolean {
- *     return fs.statSync(this.filename).size > this.maxSize;
- *   }
- *
- *   private rotate(): void {
- *     const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
- *     fs.renameSync(
- *       this.filename,
- *       `${this.filename}.${timestamp}.backup`
- *     );
- *   }
- * }
- * ```
- *
- * @example Network handler with buffering
- * ```typescript
- * class NetworkHandler implements HandlerInterface {
- *   private buffer: LogEvent[] = [];
- *   private timer: NodeJS.Timer | null = null;
- *
- *   constructor(
- *     private endpoint: string,
- *     private batchSize: number = 100,
- *     private flushInterval: number = 5000
- *   ) {
- *     this.startTimer();
- *   }
- *
- *   append(event: LogEvent): void {
- *     this.buffer.push(event);
- *     if (this.buffer.length >= this.batchSize) {
- *       this.flush();
- *     }
- *   }
- *
- *   setFormatter(formatter: FormatterInterface): void {
- *     this.formatter = formatter;
- *   }
- *
- *   private async flush(): Promise<void> {
- *     if (this.buffer.length === 0) return;
- *
- *     const events = this.buffer.map(event => ({
- *       level: event.level,
- *       message: this.formatter
- *         ? this.formatter.format(event)
- *         : event.args.join(' '),
- *       timestamp: event.timestamp
- *     }));
- *
- *     try {
- *       await fetch(this.endpoint, {
- *         method: 'POST',
- *         body: JSON.stringify(events)
- *       });
- *       this.buffer = [];
- *     } catch (error) {
- *       console.error('Failed to send logs:', error);
- *     }
- *   }
- *
- *   private startTimer(): void {
- *     this.timer = setInterval(() => this.flush(), this.flushInterval);
- *   }
- * }
- * ```
- */
-interface HandlerInterface<Ctx = unknown> {
-    /**
-     * Processes and outputs a log event
-     *
-     * This method is called by the logger for each log event that needs
-     * to be processed. The handler can format the event using its formatter
-     * (if set) and output it to its destination.
-     *
-     * Implementation considerations:
-     * - Handle all log levels appropriately
-     * - Apply formatting if a formatter is set
-     * - Handle errors gracefully
-     * - Consider performance implications
-     *
-     * @param event - The log event to process and output
-     *
-     * @example Basic implementation
-     * ```typescript
-     * append(event: LogEvent): void {
-     *   const output = this.formatter
-     *     ? this.formatter.format(event)
-     *     : event.args;
-     *
-     *   console.log(...output);
-     * }
-     * ```
-     *
-     * @example Advanced implementation with error handling
-     * ```typescript
-     * append(event: LogEvent): void {
-     *   try {
-     *     // Format the event
-     *     const formatted = this.formatter
-     *       ? this.formatter.format(event)
-     *       : event.args;
-     *
-     *     // Add timestamp and level
-     *     const output = [
-     *       new Date(event.timestamp).toISOString(),
-     *       event.level.toUpperCase(),
-     *       ...formatted
-     *     ];
-     *
-     *     // Write to file
-     *     fs.appendFileSync(this.filename, output.join(' ') + '\n');
-     *   } catch (error) {
-     *     console.error('Failed to append log:', error);
-     *     // Optionally write to fallback location
-     *     fs.appendFileSync(
-     *       'error.log',
-     *       `Failed to write log: ${error.message}\n`
-     *     );
-     *   }
-     * }
-     * ```
-     *
-     * @example Asynchronous implementation
-     * ```typescript
-     * async append(event: LogEvent): Promise<void> {
-     *   // Format the event
-     *   const message = this.formatter
-     *     ? this.formatter.format(event)
-     *     : event.args.join(' ');
-     *
-     *   // Prepare log entry
-     *   const entry = {
-     *     timestamp: event.timestamp,
-     *     level: event.level,
-     *     message,
-     *     metadata: event.context?.value
-     *   };
-     *
-     *   try {
-     *     // Send to logging service
-     *     await fetch('https://logging.example.com/ingest', {
-     *       method: 'POST',
-     *       headers: { 'Content-Type': 'application/json' },
-     *       body: JSON.stringify(entry)
-     *     });
-     *   } catch (error) {
-     *     // Handle failure
-     *     console.error('Failed to send log:', error);
-     *     // Add to retry queue
-     *     this.retryQueue.push(entry);
-     *   }
-     * }
-     * ```
-     */
-    append(event: LogEvent<Ctx>): void;
-    /**
-     * Sets or updates the formatter for this handler
-     *
-     * The formatter is responsible for converting log events into
-     * the desired output format. This method allows changing the
-     * formatter at runtime.
-     *
-     * Implementation considerations:
-     * - Handle null formatters gracefully
-     * - Consider thread safety in async environments
-     * - Clean up old formatter resources if necessary
-     *
-     * @param formatter - The formatter instance to use
-     *
-     * @example Basic implementation
-     * ```typescript
-     * setFormatter(formatter: FormatterInterface): void {
-     *   this.formatter = formatter;
-     * }
-     * ```
-     *
-     * @example Implementation with cleanup
-     * ```typescript
-     * setFormatter(formatter: FormatterInterface): void {
-     *   if (this.formatter && 'dispose' in this.formatter) {
-     *     // Clean up old formatter resources
-     *     this.formatter.dispose();
-     *   }
-     *   this.formatter = formatter;
-     * }
-     * ```
-     *
-     * @example Thread-safe implementation
-     * ```typescript
-     * setFormatter(formatter: FormatterInterface): void {
-     *   // Ensure atomic formatter update
-     *   this.lock.acquire();
-     *   try {
-     *     const oldFormatter = this.formatter;
-     *     this.formatter = formatter;
-     *
-     *     // Flush any pending logs with old formatter
-     *     if (oldFormatter) {
-     *       this.flushBuffer(oldFormatter);
-     *     }
-     *   } finally {
-     *     this.lock.release();
-     *   }
-     * }
-     * ```
-     */
-    setFormatter(formatter: FormatterInterface): void;
-}
-
-/**
- * Type-safe container for log event context data
- *
- * This class provides a generic wrapper for additional context data
- * that can be attached to log events. It ensures type safety through
- * its generic type parameter and provides a consistent structure for
- * context handling.
- *
- * Core features:
- * - Generic type support
- * - Optional value handling
- * - Immutable context data
- * - Type-safe access
- *
- * @typeParam Value - Type of the context value
- *
- * @example Basic usage
- * ```typescript
- * // Simple context
- * const context = new LogContext({ userId: 123 });
- * logger.info('User action', context);
- * ```
- *
- * @example Type-safe context
- * ```typescript
- * interface RequestContext {
- *   requestId: string;
- *   path: string;
- *   method: string;
- *   userId?: string;
- * }
- *
- * const context = new LogContext<RequestContext>({
- *   requestId: 'req-123',
- *   path: '/api/users',
- *   method: 'GET'
- * });
- *
- * logger.info('Request received', context);
- * ```
- *
- * @example Optional context
- * ```typescript
- * // Empty context
- * const emptyContext = new LogContext();
- *
- * // Context with undefined value
- * const context = new LogContext<string | undefined>(undefined);
- *
- * // Context with null value
- * const nullContext = new LogContext<string | null>(null);
- * ```
- *
- * @example Complex context
- * ```typescript
- * interface PerformanceContext {
- *   operation: string;
- *   metrics: {
- *     duration: number;
- *     memory: {
- *       before: number;
- *       after: number;
- *     };
- *     cpu: {
- *       user: number;
- *       system: number;
- *     };
- *   };
- *   metadata: Record<string, unknown>;
- * }
- *
- * const context = new LogContext<PerformanceContext>({
- *   operation: 'data-processing',
- *   metrics: {
- *     duration: 1500,
- *     memory: {
- *       before: 100000,
- *       after: 150000
- *     },
- *     cpu: {
- *       user: 80,
- *       system: 20
- *     }
- *   },
- *   metadata: {
- *     batchSize: 1000,
- *     compression: true,
- *     priority: 'high'
- *   }
- * });
- *
- * logger.debug('Operation metrics', context);
- * ```
- *
- * @example Context in formatters
- * ```typescript
- * class DetailedFormatter implements FormatterInterface<RequestContext> {
- *   format(event: LogEvent<RequestContext>): string[] {
- *     const ctx = event.context?.value;
- *     if (ctx) {
- *       return [
- *         `[${ctx.method} ${ctx.path}]`,
- *         `[${ctx.requestId}]`,
- *         ...event.args
- *       ];
- *     }
- *     return event.args;
- *   }
- * }
- * ```
- */
-declare class LogContext<Value> {
-    /**
-     * The context value that will be attached to log events
-     *
-     * This value is typed according to the Value type parameter
-     * and can be accessed safely through optional chaining.
-     */
-    value?: Value | undefined;
-    /**
-     * Creates a new LogContext instance
-     *
-     * @param value - Optional context value of type Value
-     *
-     * The value parameter is marked as optional to support:
-     * - Empty contexts (no value provided)
-     * - Explicitly undefined values
-     * - Nullable types (Value | null)
-     *
-     * The value is stored as a public property to allow:
-     * - Direct access in formatters and handlers
-     * - Type-safe value extraction
-     * - Optional chaining support
-     *
-     * @example Basic construction
-     * ```typescript
-     * // With value
-     * const context = new LogContext({ userId: 123 });
-     * console.log(context.value?.userId); // 123
-     *
-     * // Empty context
-     * const empty = new LogContext();
-     * console.log(empty.value); // undefined
-     * ```
-     *
-     * @example Type-safe construction
-     * ```typescript
-     * interface UserContext {
-     *   id: number;
-     *   name: string;
-     *   role?: string;
-     * }
-     *
-     * const context = new LogContext<UserContext>({
-     *   id: 123,
-     *   name: 'John',
-     *   role: 'admin'  // Optional property
-     * });
-     *
-     * // Type-safe access
-     * const userId = context.value?.id;  // number | undefined
-     * const role = context.value?.role;  // string | undefined
-     * ```
-     *
-     * @example Nullable context
-     * ```typescript
-     * type NullableContext = {
-     *   sessionId: string;
-     * } | null;
-     *
-     * // With value
-     * const active = new LogContext<NullableContext>({
-     *   sessionId: 'sess-123'
-     * });
-     *
-     * // With null
-     * const inactive = new LogContext<NullableContext>(null);
-     *
-     * // Type-safe null handling
-     * console.log(active.value?.sessionId);    // 'sess-123'
-     * console.log(inactive.value?.sessionId);  // undefined
-     * ```
-     *
-     * @example Context in logging
-     * ```typescript
-     * interface RequestContext {
-     *   path: string;
-     *   method: string;
-     *   duration: number;
-     * }
-     *
-     * const context = new LogContext<RequestContext>({
-     *   path: '/api/users',
-     *   method: 'GET',
-     *   duration: 150
-     * });
-     *
-     * // Using context in log messages
-     * logger.info('Request completed', context);
-     *
-     * // Accessing context in formatters
-     * class RequestFormatter implements FormatterInterface<RequestContext> {
-     *   format(event: LogEvent<RequestContext>): string[] {
-     *     const ctx = event.context?.value;
-     *     return [
-     *       ctx ? `${ctx.method} ${ctx.path} (${ctx.duration}ms)` : 'Unknown',
-     *       ...event.args
-     *     ];
-     *   }
-     * }
-     * ```
-     */
-    constructor(
-    /**
-     * The context value that will be attached to log events
-     *
-     * This value is typed according to the Value type parameter
-     * and can be accessed safely through optional chaining.
-     */
-    value?: Value | undefined);
-}
-
-/**
- * Core interface for logger implementations
- *
- * This interface defines the standard contract for logger implementations,
- * providing methods for different log levels, handler management, and
- * context creation.
- *
- * Core functionality:
- * - Standard log level methods (fatal, error, warn, info, debug, trace)
- * - Handler (appender) management
- * - Context creation for structured logging
- * - Type-safe logging with generic context support
- *
- * @example Basic usage
- * ```typescript
- * class MyLogger implements LoggerInterface {
- *   info(...args: unknown[]): void {
- *     console.log('[INFO]', ...args);
- *   }
- *   // ... implement other methods
- * }
- *
- * const logger = new MyLogger();
- * logger.info('Application started');
- * ```
- *
- * @example With handlers and context
- * ```typescript
- * class AdvancedLogger implements LoggerInterface {
- *   private handlers: HandlerInterface[] = [];
- *
- *   addAppender(handler: HandlerInterface): void {
- *     this.handlers.push(handler);
- *   }
- *
- *   info(...args: unknown[]): void {
- *     const event = {
- *       level: 'info',
- *       args,
- *       timestamp: Date.now()
- *     };
- *
- *     this.handlers.forEach(handler => handler.append(event));
- *   }
- *
- *   context<T>(value?: T): LogContext<T> {
- *     return new LogContext(value);
- *   }
- *   // ... implement other methods
- * }
- *
- * const logger = new AdvancedLogger();
- * logger.addAppender(new ConsoleHandler());
- * logger.info('User logged in', logger.context({ userId: 123 }));
- * ```
- *
- * @example Type-safe context usage
- * ```typescript
- * interface UserContext {
- *   userId: number;
- *   username: string;
- *   role: string;
- * }
- *
- * const logger: LoggerInterface = new Logger();
- *
- * // Type-safe context
- * logger.info('User action', logger.context<UserContext>({
- *   userId: 123,
- *   username: 'john_doe',
- *   role: 'admin'
- * }));
- * ```
- */
-interface LoggerInterface<Ctx = unknown> {
-    /**
-     * General purpose logging method (alias for info)
-     *
-     * @param args - Message content followed by optional context
-     *
-     * @example
-     * ```typescript
-     * logger.log('Application started');
-     * logger.log('User action', { userId: 123 });
-     * logger.log('Process completed', logger.context({ duration: 1500 }));
-     * ```
-     */
-    log(...args: unknown[]): void;
-    /**
-     * Logs a critical error that causes application termination
-     *
-     * Use for severe errors that:
-     * - Cause immediate application shutdown
-     * - Require immediate administrator attention
-     * - Indicate system is unusable
-     *
-     * @param args - Message content followed by optional context
-     *
-     * @example
-     * ```typescript
-     * logger.fatal('Database connection permanently lost');
-     * logger.fatal('Out of memory', { memoryUsage: process.memoryUsage() });
-     * logger.fatal('System crash', logger.context({
-     *   error: new Error('Unrecoverable error'),
-     *   state: 'corrupted'
-     * }));
-     * ```
-     */
-    fatal(...args: unknown[]): void;
-    /**
-     * Logs an error condition that doesn't cause termination
-     *
-     * Use for errors that:
-     * - Prevent normal operation but allow recovery
-     * - Require administrator attention
-     * - Need to be tracked for troubleshooting
-     *
-     * @param args - Message content followed by optional context
-     *
-     * @example
-     * ```typescript
-     * logger.error('Failed to process payment');
-     * logger.error('API request failed', { status: 500, path: '/api/users' });
-     * logger.error('Database query error', logger.context({
-     *   query: 'SELECT * FROM users',
-     *   error: new Error('Connection timeout')
-     * }));
-     * ```
-     */
-    error(...args: unknown[]): void;
-    /**
-     * Logs a warning condition that might cause issues
-     *
-     * Use for situations that:
-     * - Are unusual but not errors
-     * - Might cause problems in the future
-     * - Indicate deprecated feature usage
-     *
-     * @param args - Message content followed by optional context
-     *
-     * @example
-     * ```typescript
-     * logger.warn('High memory usage detected');
-     * logger.warn('Deprecated API used', { api: 'oldMethod', alternative: 'newMethod' });
-     * logger.warn('Cache miss rate high', logger.context({
-     *   rate: '85%',
-     *   threshold: '75%'
-     * }));
-     * ```
-     */
-    warn(...args: unknown[]): void;
-    /**
-     * Logs normal but significant events
-     *
-     * Use for events that:
-     * - Mark major application state changes
-     * - Track business process completion
-     * - Record user actions
-     *
-     * @param args - Message content followed by optional context
-     *
-     * @example
-     * ```typescript
-     * logger.info('Application started on port 3000');
-     * logger.info('User logged in', { userId: 123, role: 'admin' });
-     * logger.info('Order processed', logger.context({
-     *   orderId: 'ORD-123',
-     *   amount: 99.99,
-     *   currency: 'USD'
-     * }));
-     * ```
-     */
-    info(...args: unknown[]): void;
-    /**
-     * Logs detailed information for debugging
-     *
-     * Use for information that:
-     * - Helps diagnose problems
-     * - Shows detailed flow of execution
-     * - Exposes internal state
-     *
-     * @param args - Message content followed by optional context
-     *
-     * @example
-     * ```typescript
-     * logger.debug('Processing request payload');
-     * logger.debug('Cache state', { size: 1024, entries: 50 });
-     * logger.debug('Query execution plan', logger.context({
-     *   sql: 'SELECT * FROM users WHERE role = ?',
-     *   params: ['admin'],
-     *   executionTime: 150
-     * }));
-     * ```
-     */
-    debug(...args: unknown[]): void;
-    /**
-     * Logs the most detailed level of information
-     *
-     * Use for information that:
-     * - Shows step-by-step execution flow
-     * - Includes method entry/exit points
-     * - Contains variable state changes
-     *
-     * @param args - Message content followed by optional context
-     *
-     * @example
-     * ```typescript
-     * logger.trace('Entering method processUser');
-     * logger.trace('Variable state', { counter: 5, buffer: [1,2,3] });
-     * logger.trace('Method execution', logger.context({
-     *   method: 'processUser',
-     *   args: { id: 123 },
-     *   stack: new Error().stack
-     * }));
-     * ```
-     */
-    trace(...args: unknown[]): void;
-    /**
-     * Adds a new handler (appender) to the logger
-     *
-     * Handlers are responsible for processing and outputting log events.
-     * Multiple handlers can be added to send logs to different destinations
-     * or format them differently.
-     *
-     * @param appender - The handler instance to add
-     *
-     * @example Basic console handler
-     * ```typescript
-     * const logger = new Logger();
-     * logger.addAppender(new ConsoleHandler());
-     * ```
-     *
-     * @example Multiple handlers
-     * ```typescript
-     * const logger = new Logger();
-     *
-     * // Console output for development
-     * logger.addAppender(new ConsoleHandler(
-     *   new TimestampFormatter({ locale: 'en-US' })
-     * ));
-     *
-     * // File output for errors
-     * logger.addAppender(new FileHandler('./logs/errors.log', {
-     *   level: 'error',
-     *   formatter: new JSONFormatter()
-     * }));
-     *
-     * // Metrics collection
-     * logger.addAppender(new MetricsHandler({
-     *   service: 'user-api',
-     *   endpoint: 'https://metrics.example.com'
-     * }));
-     * ```
-     *
-     * @example Conditional handlers
-     * ```typescript
-     * const logger = new Logger();
-     *
-     * // Development handlers
-     * if (process.env.NODE_ENV === 'development') {
-     *   logger.addAppender(new ConsoleHandler(
-     *     new PrettyFormatter({ colors: true })
-     *   ));
-     *   logger.addAppender(new FileHandler('./logs/dev.log'));
-     * }
-     *
-     * // Production handlers
-     * if (process.env.NODE_ENV === 'production') {
-     *   logger.addAppender(new CloudWatchHandler({
-     *     region: 'us-east-1',
-     *     logGroupName: '/aws/api'
-     *   }));
-     *   logger.addAppender(new AlertHandler({
-     *     level: 'error',
-     *     webhook: 'https://alerts.example.com'
-     *   }));
-     * }
-     * ```
-     */
-    addAppender(appender: HandlerInterface<Ctx>): void;
-    /**
-     * Creates a new LogContext instance for structured logging
-     *
-     * Context objects allow adding structured data to log messages
-     * in a type-safe way. They can be used to add metadata,
-     * performance metrics, error details, or any other relevant
-     * information to log entries.
-     *
-     * @since 0.1.0
-     * @param value - Optional value to be stored in the context
-     * @returns A new LogContext instance with the provided value
-     *
-     * @example Basic context usage
-     * ```typescript
-     * logger.info('User logged in', logger.context({
-     *   userId: 123,
-     *   role: 'admin',
-     *   loginTime: new Date()
-     * }));
-     * ```
-     *
-     * @example Type-safe context
-     * ```typescript
-     * interface RequestContext {
-     *   method: string;
-     *   path: string;
-     *   duration: number;
-     *   statusCode: number;
-     * }
-     *
-     * logger.info('Request completed', logger.context<RequestContext>({
-     *   method: 'GET',
-     *   path: '/api/users',
-     *   duration: 150,
-     *   statusCode: 200
-     * }));
-     * ```
-     *
-     * @example Error context
-     * ```typescript
-     * try {
-     *   await processOrder(orderId);
-     * } catch (error) {
-     *   logger.error('Order processing failed', logger.context({
-     *     orderId,
-     *     error: error instanceof Error ? error.message : String(error),
-     *     stack: error instanceof Error ? error.stack : undefined
-     *   }));
-     * }
-     * ```
-     *
-     * @example Performance monitoring
-     * ```typescript
-     * const startTime = Date.now();
-     * try {
-     *   const result = await heavyOperation();
-     *   logger.info('Operation completed', logger.context({
-     *     duration: Date.now() - startTime,
-     *     resultSize: result.length,
-     *     memoryUsage: process.memoryUsage()
-     *   }));
-     * } catch (error) {
-     *   logger.error('Operation failed', logger.context({
-     *     duration: Date.now() - startTime,
-     *     error,
-     *     memoryUsage: process.memoryUsage()
-     *   }));
-     * }
-     * ```
+     * @default ['.env.local', '.env']
      */
-    context<Value>(value?: Value): LogContext<Value>;
+    envOrder?: string[];
 }
 
 /**
@@ -2784,7 +941,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 +990,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 +1016,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 +1084,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
-     *
-     * Template syntax:
-     * - `<%= variable %>` for escaped output
-     * - `<%- variable %>` for unescaped output
-     * - `<% code %>` for JavaScript code execution
-     * - Supports nested object access and function calls
+     * Formats a template string with context using {@link TemplateEngine}.
      *
-     * 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 +1141,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 +1190,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' }
      * });
      * ```
@@ -4321,6 +2450,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 +2516,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 +2601,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 +2703,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 +2941,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 +2967,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 +2999,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 | string | Array<keyof Props | string>, defaultValue?: T): T;
     /**
      * Updates plugin configuration with deep merging
      *
@@ -4950,7 +3095,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 +3126,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 +3159,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 +3241,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 };