@qlover/scripts-context 1.3.0 → 2.1.0

package/dist/index.d.ts

@@ -1,10 +1,9 @@
-import * as _commitlint_types from '@commitlint/types';
-import { LoggerInterface, FormatterInterface, LogEvent } from '@qlover/logger';
+import { UserConfig } from '@commitlint/types';
 import { Env } from '@qlover/env-loader';
-import { ExecutorPlugin, ExecutorContext } from '@qlover/fe-corekit';
+import { ExecutorContextImpl, LifecyclePluginInterface, ExecutorContextInterface, ExecutorError } from '@qlover/fe-corekit';
 
 declare const defaultFeConfig: FeConfig;
-type FeConfig = {
+interface FeConfig {
     /**
      * Run `fe-clean-branch` to exclude branches
      *
@@ -40,7 +39,7 @@ type FeConfig = {
      *
      * @default { "extends": ["@commitlint/config-conventional"] }
      */
-    commitlint?: _commitlint_types.UserConfig;
+    commitlint?: UserConfig;
     /**
      * config of CI release
      *
@@ -51,7 +50,24 @@ type FeConfig = {
      * @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
  *
@@ -343,205 +359,1535 @@ interface FeReleaseConfig {
      * - `${changelog}`: Generated changelog content
      * - `${pkgName}`: Package name
      *
-     * @optional
-     * @default Comprehensive PR body template with changelog
-     * @example Simple PR body
+     * @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
-     * const config: FeReleaseConfig = {
-     *   PRBody: 'Release ${pkgName} v${tagName}\n\n${changelog}'
-     * };
+     * 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
      *
-     * @example Detailed PR body
+     * 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
-     * const config: FeReleaseConfig = {
-     *   PRBody: `
-     * ## Release ${pkgName} v${tagName}
+     * 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
      *
-     * **Environment:** ${env}
-     * **Branch:** ${branch}
+     * Use for situations that:
+     * - Are unusual but not errors
+     * - Might cause problems in the future
+     * - Indicate deprecated feature usage
      *
-     * ### Changes
-     * ${changelog}
+     * @param args - Message content followed by optional context
      *
-     * ### Checklist
-     * - [ ] Version number is correct
-     * - [ ] All tests pass
-     * - [ ] Documentation updated
-     * `
-     * };
+     * @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%'
+     * }));
      * ```
      */
-    PRBody?: string;
+    warn(...args: unknown[]): void;
     /**
-     * Configuration for release pull request labels
+     * Logs normal but significant events
      *
-     * Core concept:
-     * Defines the label configuration for release pull requests,
-     * enabling automated categorization and visual identification
-     * of release-related PRs.
+     * Use for events that:
+     * - Mark major application state changes
+     * - Track business process completion
+     * - Record user actions
      *
-     * Label features:
-     * - Automated label application
-     * - Customizable label appearance
-     * - Consistent release identification
-     * - Integration with GitHub labeling system
-     * - Support for custom label descriptions
+     * @param args - Message content followed by optional context
      *
-     * Label properties:
-     * - name: Label identifier and display name
-     * - color: Hexadecimal color code for visual distinction
-     * - description: Label description for documentation
+     * @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
      *
-     * @optional
-     * @example Basic label configuration
+     * 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
-     * const config: FeReleaseConfig = {
-     *   label: {
-     *     name: 'release',
-     *     color: '1A7F37',
-     *     description: 'Automated release PR'
-     *   }
-     * };
+     * 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
      *
-     * @example Custom label
+     * 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
-     * const config: FeReleaseConfig = {
-     *   label: {
-     *     name: 'CI-Release',
-     *     color: '0366D6',
-     *     description: 'Release created by CI/CD'
-     *   }
-     * };
+     * 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
+     * }));
      * ```
      */
-    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;
-    };
+    trace(...args: unknown[]): void;
     /**
-     * Template for package change labels in monorepos
+     * Adds a new handler (appender) to the logger
      *
-     * Core concept:
-     * Defines the naming pattern for labels that identify
-     * which packages have changed in monorepo releases,
-     * enabling targeted review and deployment.
+     * Handlers are responsible for processing and outputting log events.
+     * Multiple handlers can be added to send logs to different destinations
+     * or format them differently.
      *
-     * 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
+     * @param appender - The handler instance to add
      *
-     * Template variables:
-     * - `${name}`: Package name for label identification
+     * @example Basic console handler
+     * ```typescript
+     * const logger = new Logger();
+     * logger.addAppender(new ConsoleHandler());
+     * ```
      *
-     * @optional
-     * @default `'changes:${name}'`
-     * @example Basic change label
+     * @example Multiple handlers
      * ```typescript
-     * const config: FeReleaseConfig = {
-     *   changePackagesLabel: 'changes:${name}'
-     * };
+     * 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 Custom change label
+     * @example Conditional handlers
      * ```typescript
-     * const config: FeReleaseConfig = {
-     *   changePackagesLabel: 'package:${name}'
-     * };
+     * 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'
+     *   }));
+     * }
      * ```
      */
-    changePackagesLabel?: string;
+    addAppender(appender: HandlerInterface<Ctx>): void;
     /**
-     * Directories containing packages for monorepo releases
+     * Creates a new LogContext instance for structured logging
      *
-     * Core concept:
-     * Specifies the directories that contain packages for
-     * monorepo release management, enabling selective
-     * package discovery and release coordination.
+     * 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.
      *
-     * Directory patterns:
-     * - Supports glob patterns for flexible matching
-     * - Enables selective package inclusion
-     * - Supports nested directory structures
-     * - Facilitates monorepo organization
-     * - Enables workspace-specific configurations
+     * @since 0.1.0
+     * @param value - Optional value to be stored in the context
+     * @returns A new LogContext instance with the provided value
      *
-     * Use cases:
-     * - Monorepo package discovery
-     * - Selective package releases
-     * - Workspace-specific configurations
-     * - Multi-package coordination
-     * - Dependency-aware releases
+     * @example Basic context usage
+     * ```typescript
+     * logger.info('User logged in', logger.context({
+     *   userId: 123,
+     *   role: 'admin',
+     *   loginTime: new Date()
+     * }));
+     * ```
      *
-     * @optional
-     * @default `[]`
-     * @example Basic package directories
+     * @example Type-safe context
      * ```typescript
-     * const config: FeReleaseConfig = {
-     *   packagesDirectories: ['packages/*']
-     * };
+     * 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 Multiple package directories
+     * @example Error context
      * ```typescript
-     * const config: FeReleaseConfig = {
-     *   packagesDirectories: ['packages/*', 'apps/*', 'libs/*']
-     * };
+     * 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()
+     *   }));
+     * }
      * ```
      */
-    packagesDirectories?: string[];
+    context<Value>(value?: Value): LogContext<Value>;
 }
 
 /**
@@ -2938,7 +4284,7 @@ declare class ConfigSearch {
  * });
  * ```
  */
-declare class ScriptContext<Opt extends ScriptSharedInterface> implements ScriptContextInterface<Opt> {
+declare class ScriptContext<Opt extends ScriptSharedInterface> extends ExecutorContextImpl<Opt> implements ScriptContextInterface<Opt> {
     readonly name: string;
     /**
      * Logger instance for structured logging
@@ -2975,13 +4321,6 @@ declare class ScriptContext<Opt extends ScriptSharedInterface> implements Script
      * detailed information display.
      */
     readonly verbose: boolean;
-    /**
-     * Script-specific options
-     *
-     * Contains all script configuration options
-     * with defaults applied and environment integration.
-     */
-    options: Opt;
     /**
      * Creates a new ScriptContext instance with the specified configuration
      *
@@ -3029,6 +4368,10 @@ declare class ScriptContext<Opt extends ScriptSharedInterface> implements Script
      * ```
      */
     constructor(name: string, opts?: Partial<ScriptContextInterface<Opt>>);
+    /**
+     * @override
+     */
+    get options(): Opt;
     /**
      * Environment instance for variable access and management
      *
@@ -3071,101 +4414,6 @@ declare class ScriptContext<Opt extends ScriptSharedInterface> implements Script
      * ```
      */
     get env(): Env;
-    /**
-     * Extracts configuration store from feConfig based on script name
-     *
-     * Core concept:
-     * Safely extracts script-specific configuration from the
-     * merged fe-config object, handling various data types
-     * and providing fallback values.
-     *
-     * Extraction process:
-     * 1. Uses lodash get to safely access nested configuration
-     * 2. Validates that the extracted value is an object
-     * 3. Converts primitive values to empty objects
-     * 4. Logs warnings for non-object configurations
-     * 5. Returns type-safe configuration object
-     *
-     * Safety features:
-     * - Safe nested property access with lodash get
-     * - Null and undefined handling
-     * - Type validation for configuration objects
-     * - Warning logging for invalid configurations
-     * - Fallback to empty object for primitives
-     *
-     * Configuration validation:
-     * - Checks if extracted value is an object
-     * - Warns when configuration is not an object
-     * - Converts primitives to empty objects
-     * - Maintains type safety through generic constraints
-     *
-     * @param scriptName - Script name or array of names for nested access
-     * @param sources - Configuration source object (feConfig)
-     * @returns Extracted configuration object with type safety
-     *
-     * @example Basic extraction
-     * ```typescript
-     * const config = this.getDefaultStore('build-script', feConfig);
-     * // Returns configuration from feConfig['build-script']
-     * ```
-     *
-     * @example Nested access
-     * ```typescript
-     * const config = this.getDefaultStore(['scripts', 'build'], feConfig);
-     * // Returns configuration from feConfig.scripts.build
-     * ```
-     */
-    protected getDefaultStore(scriptName: string | string[], sources: Record<string, unknown>): Opt;
-    /**
-     * Applies default values to script options with environment integration
-     *
-     * Core concept:
-     * Enhances provided options with sensible defaults and
-     * environment variable integration, ensuring all required
-     * configuration is available.
-     *
-     * Default logic:
-     * 1. Uses existing environment or loads from files
-     * 2. Sets rootPath to current working directory if not specified
-     * 3. Determines sourceBranch from environment or defaults to 'master'
-     * 4. Merges all options with proper precedence
-     * 5. Ensures environment is properly initialized
-     *
-     * Environment variable priority:
-     * 1. FE_RELEASE_BRANCH (primary environment variable)
-     * 2. FE_RELEASE_SOURCE_BRANCH (fallback environment variable)
-     * 3. 'master' (default value)
-     * 4. Options.sourceBranch (if provided)
-     *
-     * Path handling:
-     * - rootPath defaults to process.cwd() if not specified
-     * - Supports both absolute and relative paths
-     * - Maintains path consistency across environments
-     * - Used for file operations and configuration loading
-     *
-     * Environment integration:
-     * - Loads environment from files if not provided
-     * - Uses configurable file loading order
-     * - Integrates with fe-config environment settings
-     * - Provides fallback to default environment
-     *
-     * @param options - Current options to enhance with defaults
-     * @returns Options with default values and environment integration
-     *
-     * @example Basic defaults
-     * ```typescript
-     * const options = this.getDefaultOptions({});
-     * // Returns: { rootPath: process.cwd(), sourceBranch: 'master', env: Env instance }
-     * ```
-     *
-     * @example With environment variables
-     * ```typescript
-     * // If FE_RELEASE_BRANCH=develop
-     * const options = this.getDefaultOptions({});
-     * // Returns: { rootPath: process.cwd(), sourceBranch: 'develop', env: Env instance }
-     * ```
-     */
-    protected getDefaultOptions(options: Opt): Opt;
     /**
      * Updates script options with deep merging support
      *
@@ -3439,7 +4687,7 @@ interface ScriptPluginProps {
  * }
  * ```
  */
-declare abstract class ScriptPlugin<Context extends ScriptContext<any>, Props extends ScriptPluginProps = ScriptPluginProps> implements ExecutorPlugin<Context> {
+declare abstract class ScriptPlugin<Context extends ScriptContext<any>, Props extends ScriptPluginProps = ScriptPluginProps> implements LifecyclePluginInterface<Context> {
     protected context: Context;
     readonly pluginName: string;
     protected props: Props;
@@ -3574,7 +4822,7 @@ declare abstract class ScriptPlugin<Context extends ScriptContext<any>, Props ex
      * plugin.enabled('onExec', context);   // Returns true
      * ```
      */
-    enabled(_name: string, _context: ExecutorContext<Context>): boolean;
+    enabled(_name: string, _context: Context): boolean;
     /**
      * Retrieves configuration values with nested path support
      *
@@ -3668,7 +4916,7 @@ declare abstract class ScriptPlugin<Context extends ScriptContext<any>, Props ex
      * }
      * ```
      */
-    onBefore?(_context: ExecutorContext<Context>): void | Promise<void>;
+    onBefore?(_context: Context): Context extends ExecutorContextInterface<infer P> ? P | Promise<P> | void | Promise<void> : unknown | Promise<unknown> | void | Promise<void>;
     /**
      * Lifecycle method called during script execution
      *
@@ -3683,7 +4931,7 @@ declare abstract class ScriptPlugin<Context extends ScriptContext<any>, Props ex
      *
      * @example
      * ```typescript
-     * async onExec(context: ExecutorContext<MyContext>): Promise<void> {
+     * async onExec(context: Context): Promise<void> {
      *   await this.step({
      *     label: 'Building project',
      *     task: async () => {
@@ -3702,7 +4950,7 @@ declare abstract class ScriptPlugin<Context extends ScriptContext<any>, Props ex
      * }
      * ```
      */
-    onExec?(_context: ExecutorContext<Context>): void | Promise<void>;
+    onExec?(_context: Context): void | Promise<void>;
     /**
      * Lifecycle method called after successful script execution
      *
@@ -3717,7 +4965,7 @@ declare abstract class ScriptPlugin<Context extends ScriptContext<any>, Props ex
      *
      * @example
      * ```typescript
-     * async onSuccess(context: ExecutorContext<MyContext>): Promise<void> {
+     * async onSuccess(context: Context): Promise<void> {
      *   // Send success notification
      *   await this.sendNotification('Build completed successfully');
      *
@@ -3733,7 +4981,7 @@ declare abstract class ScriptPlugin<Context extends ScriptContext<any>, Props ex
      * }
      * ```
      */
-    onSuccess?(_context: ExecutorContext<Context>): void | Promise<void>;
+    onSuccess?(_context: Context): void | Promise<void>;
     /**
      * Lifecycle method called when script execution fails
      *
@@ -3748,7 +4996,7 @@ declare abstract class ScriptPlugin<Context extends ScriptContext<any>, Props ex
      *
      * @example
      * ```typescript
-     * async onError(context: ExecutorContext<MyContext>): Promise<void> {
+     * async onError(context: Context): Promise<void> {
      *   // Log detailed error information
      *   this.logger.error('Script execution failed', {
      *     error: context.error,
@@ -3766,7 +5014,28 @@ declare abstract class ScriptPlugin<Context extends ScriptContext<any>, Props ex
      * }
      * ```
      */
-    onError?(_context: ExecutorContext<Context>): void | Promise<void>;
+    onError?(_context: Context): Promise<ExecutorError | void> | ExecutorError | Error | void;
+    /**
+     * Lifecycle method called after script execution
+     *
+     * Override this method to perform cleanup tasks such as:
+     * - Resource cleanup
+     * - Success notifications
+     * - Result processing
+     * - Post-execution reporting
+     *
+     * @override
+     * @param _context - Executor context containing execution state
+     *
+     * @example
+     * ```typescript
+     * async onFinally(context: Context): Promise<void> {
+     *   // Clean up temporary files
+     *   await this.shell.rmdir('./temp');
+     * }
+     * ```
+     */
+    onFinally?(_context: Context): void | Promise<void>;
     /**
      * Executes a step with structured logging and error handling
      *