@qlover/scripts-context 0.2.0 → 1.0.0

package/dist/index.d.ts

@@ -1,161 +1,7 @@
 import * as _commitlint_types from '@commitlint/types';
 import { LoggerInterface, FormatterInterface, LogEvent } from '@qlover/logger';
-
-/**
- * Configuration search options interface
- * @interface
- * @description
- * Significance: Defines the configuration structure for ConfigSearch initialization
- * Core idea: Centralize configuration search parameters
- * Main function: Type-safe configuration options
- * Main purpose: Standardize configuration initialization
- * Example:
- * ```typescript
- * const options: ConfigSearchOptions = {
- *   name: 'myapp',
- *   searchPlaces: ['myapp.config.js'],
- *   defaultConfig: { port: 3000 }
- * };
- * ```
- */
-interface ConfigSearchOptions {
-    /** Base name for configuration files */
-    name: string;
-    /** Custom search locations for config files */
-    searchPlaces?: string[];
-    /** Default configuration object */
-    defaultConfig?: Record<string, unknown>;
-    /** Custom loaders for different file types */
-    loaders?: Record<string, (filepath: string) => unknown>;
-}
-/**
- * Search options interface for configuration retrieval
- * @interface
- * @description
- * Significance: Defines options for configuration search operation
- * Core idea: Control configuration file search behavior
- * Main function: Customize search parameters
- * Main purpose: Flexible configuration loading
- * Example:
- * ```typescript
- * const searchOptions: SearchOptions = {
- *   file: 'custom.config.js',
- *   dir: '/path/to/project'
- * };
- * ```
- */
-interface SearchOptions {
-    /** Specific configuration file to load */
-    file?: string | false;
-    /** Directory to search in */
-    dir?: string;
-}
-/**
- * Configuration search utility class
- * @class
- * @description
- * Significance: Manages configuration file discovery and loading
- * Core idea: Unified configuration management
- * Main function: Search and load configuration from various sources
- * Main purpose: Provide consistent configuration access
- * Example:
- * ```typescript
- * const configSearch = new ConfigSearch({
- *   name: 'myapp',
- *   defaultConfig: { port: 3000 }
- * });
- * const config = configSearch.config;
- * ```
- */
-declare class ConfigSearch {
-    private name;
-    private searchPlaces;
-    private _config;
-    private loaders?;
-    private searchCache?;
-    /**
-     * Creates a ConfigSearch instance
-     * @param options - Configuration search options
-     * @throws Error if neither name nor searchPlaces is provided
-     * @description
-     * Significance: Initializes configuration search environment
-     * Core idea: Setup configuration search parameters
-     * Main function: Create search instance with options
-     * Main purpose: Prepare for configuration discovery
-     * Example:
-     * ```typescript
-     * const search = new ConfigSearch({
-     *   name: 'myapp',
-     *   defaultConfig: { debug: true }
-     * });
-     * ```
-     */
-    constructor(options: ConfigSearchOptions);
-    /**
-     * Get effective configuration
-     * @returns Merged configuration object
-     * @description
-     * Significance: Provides access to final configuration
-     * Core idea: Merge default and discovered configurations
-     * Main function: Retrieve effective configuration
-     * Main purpose: Access complete configuration
-     * Example:
-     * ```typescript
-     * const config = configSearch.config;
-     * console.log(config.debug); // true
-     * ```
-     */
-    get config(): Record<string, unknown>;
-    /**
-     * Get search locations
-     * @returns Array of search locations
-     * @description
-     * Significance: Exposes configuration search paths
-     * Core idea: Provide transparency in search process
-     * Main function: Return search locations
-     * Main purpose: Debug and verify search paths
-     * Example:
-     * ```typescript
-     * const places = configSearch.getSearchPlaces();
-     * // ['package.json', 'myapp.config.js', ...]
-     * ```
-     */
-    getSearchPlaces(): string[];
-    /**
-     * Get configuration from specific location
-     * @param options - Search options
-     * @returns Configuration object
-     * @throws Error if configuration file is invalid
-     * @description
-     * Significance: Load configuration from specific location
-     * Core idea: Flexible configuration loading
-     * Main function: Load and validate configuration
-     * Main purpose: Custom configuration loading
-     * Example:
-     * ```typescript
-     * const config = configSearch.get({
-     *   file: 'custom.config.js',
-     *   dir: process.cwd()
-     * });
-     * ```
-     */
-    get(options?: SearchOptions): Record<string, unknown>;
-    /**
-     * Search for configuration with caching
-     * @returns Cached configuration object
-     * @description
-     * Significance: Provides cached configuration access
-     * Core idea: Cache configuration for performance
-     * Main function: Search and cache configuration
-     * Main purpose: Optimize repeated access
-     * Example:
-     * ```typescript
-     * const config = configSearch.search();
-     * // Subsequent calls use cached result
-     * ```
-     */
-    search(): Record<string, unknown>;
-}
+import { Env } from '@qlover/env-loader';
+import { ExecutorPlugin, ExecutorContext } from '@qlover/fe-corekit';
 
 declare const defaultFeConfig: FeConfig;
 type FeConfig = {
@@ -206,336 +52,3774 @@ type FeConfig = {
      */
     envOrder?: string[];
 };
-type FeReleaseConfig = {
+/**
+ * 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
      *
-     * @default ''
+     * 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
      *
-     * @default true
+     * 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 merged type
+     * 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
      *
-     * @default squash
+     * @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';
     /**
-     * Create the branch name of PR when publishing
+     * 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
      *
-     * support vars: pkgName, tagName, env, branch
+     * @optional
+     * @default `'release-${pkgName}-${tagName}'`
+     * @example Basic branch naming
+     * ```typescript
+     * const config: FeReleaseConfig = {
+     *   branchName: 'release-${pkgName}-${tagName}'
+     * };
+     * ```
      *
-     * @default 'release-${pkgName}-${tagName}'
+     * @example Environment-aware naming
+     * ```typescript
+     * const config: FeReleaseConfig = {
+     *   branchName: 'release/${env}/${pkgName}-${tagName}'
+     * };
+     * ```
      */
     branchName?: string;
     /**
-     * Create a title for publishing PR
+     * 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}'
+     * };
+     * ```
      *
-     * @default [${pkgName} Release] Branch:${branch}, Tag:${tagName}, Env:${env}
+     * @example Detailed PR title
+     * ```typescript
+     * const config: FeReleaseConfig = {
+     *   PRTitle: '🚀 Release ${pkgName} v${tagName} (${env})'
+     * };
+     * ```
      */
     PRTitle?: string;
     /**
-     * Create a body for publishing PR
+     * 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}
      *
-     * @default This PR includes version bump to ${tagName}
+     * **Environment:** ${env}
+     * **Branch:** ${branch}
+     *
+     * ### Changes
+     * ${changelog}
+     *
+     * ### Checklist
+     * - [ ] Version number is correct
+     * - [ ] All tests pass
+     * - [ ] Documentation updated
+     * `
+     * };
+     * ```
      */
     PRBody?: string;
     /**
-     * Create a label for publishing PR
+     * 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?: {
         /**
-         * hex color string
+         * Hexadecimal color code for label appearance
          *
-         * @default `1A7F37`
+         * 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;
         /**
-         * @default `Label for version update PRs`
+         * 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;
         /**
-         * @default `CI-Release`
+         * 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;
     };
     /**
-     * @default `changes:${name}`
+     * 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[];
-};
+}
 
 /**
- * Options for shell execution
+ * Common/shared configuration options for script execution context
  *
- * This interface defines the options available for executing shell commands.
- * It provides flexibility in controlling the behavior of shell command execution.
+ * Core concept:
+ * Defines the fundamental properties that are shared across different
+ * script contexts and plugins, providing consistent environment access,
+ * project path management, and source branch information for unified
+ * configuration management.
  *
- * @interface
- * @example
- * const options: ShellExecOptions = {
- *   silent: true,
- *   env: { PATH: '/usr/bin' },
- *   dryRun: false
+ * Main features:
+ * - Environment access: Integrated environment variable management
+ *   - Provides access to loaded environment variables
+ *   - Supports configuration, secrets, and runtime flags
+ *   - Integrates with fe-config environment settings
+ *   - Handles environment file loading and validation
+ *
+ * - Path management: Project root path for file operations
+ *   - Used as base directory for all relative file operations
+ *   - Supports both absolute and relative path resolution
+ *   - Maintains path consistency across environments
+ *   - Defaults to current working directory
+ *
+ * - Branch information: Source branch for build and deployment
+ *   - Determines source branch for build or deployment processes
+ *   - Supports environment variable resolution
+ *   - Provides fallback to default branch
+ *   - Used in CI/CD and build automation
+ *
+ * Design considerations:
+ * - All properties are optional to allow flexible extension in derived interfaces
+ * - Environment and branch information are used for build, deploy, and CI/CD scripts
+ * - Path management supports cross-platform compatibility
+ * - Provides sensible defaults for all optional properties
+ * - Maintains backward compatibility with existing implementations
+ *
+ * Usage patterns:
+ * - Base interface for script-specific option extensions
+ * - Common functionality across different script types
+ * - Environment-aware configuration management
+ * - Path-relative file and directory operations
+ *
+ * @example Basic usage
+ * ```typescript
+ * const shared: ScriptSharedInterface = {
+ *   env: Env.searchEnv(),
+ *   sourceBranch: 'develop',
+ *   rootPath: '/project/root'
+ * };
+ * ```
+ *
+ * @example With environment variables
+ * ```typescript
+ * const shared: ScriptSharedInterface = {
+ *   env: Env.searchEnv(),
+ *   sourceBranch: process.env.FE_RELEASE_BRANCH || 'master',
+ *   rootPath: process.cwd()
  * };
+ * ```
+ *
+ * @example Extended interface
+ * ```typescript
+ * interface BuildOptions extends ScriptSharedInterface {
+ *   target: 'development' | 'production';
+ *   outputDir: string;
+ * }
+ * ```
  */
-interface ShellExecOptions {
+interface ScriptSharedInterface {
     /**
-     * Whether to suppress output to the console.
+     * Environment variable accessor instance
      *
-     * @type {boolean}
-     */
-    silent?: boolean;
-    /**
-     * Environment variables to be passed to the command.
+     * Core concept:
+     * Provides access to loaded environment variables for the script
+     * context, enabling configuration management, secret access,
+     * and runtime flag control.
      *
-     * @type {Record<string, string>}
-     */
-    env?: Record<string, string>;
-    /**
-     * Result to return when in dry-run mode.
+     * Environment capabilities:
+     * - Automatic loading of .env files with configurable order
+     * - Type-safe environment variable access with defaults
+     * - Support for environment-specific configurations
+     * - Integration with fe-config environment settings
+     * - Lazy initialization for performance optimization
      *
-     * @type {unknown}
-     */
-    dryRunResult?: unknown;
-    /**
-     * Whether to perform a dry run.
-     * Overrides shell config.isDryRun if set.
+     * Common use cases:
+     * - API keys and authentication tokens
+     * - Database connection strings
+     * - Feature flags and configuration switches
+     * - Build and deployment settings
+     * - Runtime environment identification
      *
-     * @type {boolean}
-     */
-    dryRun?: boolean;
-    /**
-     * Template context for command string interpolation.
+     * Loading behavior:
+     * - Files loaded in priority order (highest first)
+     * - Missing files are silently ignored
+     * - Variables cached after first load
+     * - Environment shared across script instances
+     * - Supports both development and production environments
+     *
+     * @optional
+     * @example Basic environment access
+     * ```typescript
+     * const apiKey = shared.env?.get('API_KEY');
+     * const port = shared.env?.get('PORT', '3000');
+     * ```
+     *
+     * @example With defaults
+     * ```typescript
+     * const databaseUrl = shared.env?.get('DATABASE_URL', 'localhost:5432');
+     * const debug = shared.env?.get('DEBUG', 'false');
+     * const isDebug = debug === 'true';
+     * ```
      *
-     * @type {Record<string, unknown>}
+     * @example Environment validation
+     * ```typescript
+     * if (!shared.env?.get('REQUIRED_VAR')) {
+     *   throw new Error('REQUIRED_VAR environment variable is missing');
+     * }
+     * ```
      */
-    context?: Record<string, unknown>;
+    env?: Env;
     /**
-     * Encoding for command output.
+     * The source branch of the project for build and deployment
+     *
+     * Core concept:
+     * Determines which branch is considered the source for build
+     * or deployment processes, supporting environment variable
+     * resolution and providing fallback values.
+     *
+     * Resolution priority:
+     * 1. `FE_RELEASE_SOURCE_BRANCH` environment variable (primary)
+     * 2. `FE_RELEASE_BRANCH` environment variable (fallback)
+     * 3. 'master' (default fallback)
+     * 4. Explicitly set value (highest priority)
+     *
+     * Use cases:
+     * - Build automation and CI/CD pipelines
+     * - Deployment targeting and branch selection
+     * - Release management and versioning
+     * - Environment-specific configuration
+     * - Git workflow integration
+     *
+     * Branch handling:
+     * - Supports all Git branch naming conventions
+     * - Handles special characters and spaces
+     * - Validates branch existence when possible
+     * - Provides consistent branch reference
+     * - Supports both local and remote branches
+     *
+     * @optional
+     * @example Basic branch usage
+     * ```typescript
+     * const branch = shared.sourceBranch || 'master';
+     * console.log('Building from branch:', branch);
+     * ```
+     *
+     * @example With environment resolution
+     * ```typescript
+     * const branch = shared.sourceBranch ||
+     *   process.env.FE_RELEASE_SOURCE_BRANCH ||
+     *   process.env.FE_RELEASE_BRANCH ||
+     *   'master';
+     * ```
      *
-     * @type {string}
+     * @example Branch validation
+     * ```typescript
+     * if (shared.sourceBranch === 'main' || shared.sourceBranch === 'master') {
+     *   console.log('Building from main branch');
+     * } else {
+     *   console.log('Building from feature branch:', shared.sourceBranch);
+     * }
+     * ```
      */
-    encoding?: BufferEncoding;
+    sourceBranch?: string;
     /**
-     * Whether to cache the command
+     * The root path of the project for file operations
      *
-     * @type {boolean}
-     * @default `false`
+     * Core concept:
+     * Specifies the base directory for all relative file operations,
+     * providing consistent path resolution across different
+     * environments and execution contexts.
+     *
+     * Path behavior:
+     * - Used as base directory for all relative file operations
+     * - Supports both absolute and relative path resolution
+     * - Maintains path consistency across environments
+     * - Defaults to current working directory if not specified
+     * - Handles cross-platform path separators
+     *
+     * File operations:
+     * - Configuration file loading and searching
+     * - Build output directory resolution
+     * - Asset and resource file access
+     * - Temporary file and cache management
+     * - Log file and output directory creation
+     *
+     * Path resolution:
+     * - Absolute paths are used as-is
+     * - Relative paths are resolved from root path
+     * - Supports nested directory structures
+     * - Handles path normalization and validation
+     * - Provides consistent path representation
+     *
+     * @optional
+     * @default `process.cwd()`
+     * @example Basic path usage
+     * ```typescript
+     * const root = shared.rootPath || process.cwd();
+     * const configPath = path.join(root, 'fe-config.json');
+     * ```
+     *
+     * @example Relative path resolution
+     * ```typescript
+     * const root = shared.rootPath || process.cwd();
+     * const buildDir = path.join(root, 'dist');
+     * const srcDir = path.join(root, 'src');
+     * ```
+     *
+     * @example Path validation
+     * ```typescript
+     * const root = shared.rootPath || process.cwd();
+     * if (!fs.existsSync(root)) {
+     *   throw new Error(`Root path does not exist: ${root}`);
+     * }
+     * ```
      */
-    isCache?: boolean;
-    [key: string]: unknown;
+    rootPath?: string;
 }
+
 /**
- * Interface for shell execution
+ * Options for shell command execution with comprehensive customization
  *
- * This interface defines a method for executing shell commands.
- * It abstracts the details of shell command execution and provides a consistent interface.
+ * Core concept:
+ * Defines the configuration options available for executing shell
+ * commands, providing flexibility in controlling execution behavior,
+ * output handling, and environment configuration.
  *
- * @interface
- * @example
- * const shell: ShellInterface = {
- *   exec: async (command, options) => {
- *     // Logic to execute the command
- *     return 'Command output';
- *   }
- * };
- */
-interface ShellInterface {
+ * Main features:
+ * - Execution control: Fine-grained control over command execution
+ *   - Silent mode for quiet execution
+ *   - Dry run mode for safe testing
+ *   - Custom environment variable injection
+ *   - Working directory specification
+ *
+ * - Output handling: Flexible output and result management
+ *   - Encoding specification for output processing
+ *   - Dry run result customization
+ *   - Template context for dynamic command generation
+ *   - Caching support for performance optimization
+ *
+ * - Environment integration: Comprehensive environment management
+ *   - Environment variable injection
+ *   - Template context for variable substitution
+ *   - Cross-platform compatibility
+ *   - Security considerations for sensitive data
+ *
+ * Design considerations:
+ * - All options are optional for maximum flexibility
+ * - Supports both string and array command formats
+ * - Maintains backward compatibility with existing implementations
+ * - Provides sensible defaults for all optional properties
+ * - Supports extensibility through index signature
+ *
+ * Usage patterns:
+ * - Basic command execution with minimal options
+ * - Advanced execution with custom environment and encoding
+ * - Template-based command generation with context
+ * - Dry run testing and validation
+ * - Performance optimization through caching
+ *
+ * @example Basic usage
+ * ```typescript
+ * const options: ShellExecOptions = {
+ *   silent: true,
+ *   env: { PATH: '/usr/bin' },
+ *   dryRun: false
+ * };
+ * ```
+ *
+ * @example With template context
+ * ```typescript
+ * const options: ShellExecOptions = {
+ *   context: { repo: 'https://github.com/user/repo.git' },
+ *   cwd: '/project/root'
+ * };
+ * ```
+ *
+ * @example Dry run mode
+ * ```typescript
+ * const options: ShellExecOptions = {
+ *   dryRun: true,
+ *   dryRunResult: 'Would execute: npm install'
+ * };
+ * ```
+ */
+interface ShellExecOptions {
     /**
-     * Execute a command.
+     * Whether to suppress output to the console
+     *
+     * Core concept:
+     * Controls whether command execution details are logged
+     * to the console, useful for quiet execution in automated
+     * scripts or when detailed logging is not needed.
+     *
+     * Silent mode behavior:
+     * - Suppresses command execution logging
+     * - Maintains error logging for debugging
+     * - Reduces log noise in automated environments
+     * - Useful for background or batch operations
+     * - Preserves error handling and reporting
+     *
+     * Use cases:
+     * - Automated script execution
+     * - Background command processing
+     * - Batch operations with minimal output
+     * - Integration with external logging systems
+     * - Performance-critical operations
+     *
+     * @optional
+     * @example Basic silent execution
+     * ```typescript
+     * const options: ShellExecOptions = { silent: true };
+     * // Command executes without console output
+     * ```
      *
-     * @param {string | string[]} command - The command to execute.
-     * @param {ShellExecOptions} [options] - Options for the command execution.
-     * @returns {Promise<string>} The output of the command.
+     * @example Conditional silent mode
+     * ```typescript
+     * const options: ShellExecOptions = {
+     *   silent: process.env.NODE_ENV === 'production'
+     * };
+     * ```
      */
-    exec(command: string | string[], options?: ShellExecOptions): Promise<string>;
-}
-
-type ExecPromiseFunction = (command: string | string[], options: ShellExecOptions) => Promise<string>;
-/**
- * Configuration interface for Shell class
- * @interface
- */
-interface ShellConfig extends ShellExecOptions {
-    /** Logger instance */
-    logger: LoggerInterface;
+    silent?: boolean;
     /**
-     * Promise for the execer
+     * Environment variables to be passed to the command
+     *
+     * Core concept:
+     * Specifies custom environment variables that will be
+     * available to the executed command, allowing for
+     * environment-specific configuration and behavior.
+     *
+     * Environment injection:
+     * - Variables are merged with existing environment
+     * - Overrides existing variables with same names
+     * - Supports both string and object value types
+     * - Maintains security for sensitive data
+     * - Provides cross-platform compatibility
+     *
+     * Common use cases:
+     * - PATH modifications for command resolution
+     * - API keys and authentication tokens
+     * - Configuration overrides for specific commands
+     * - Development vs production environment switching
+     * - Custom script environment setup
+     *
+     * Security considerations:
+     * - Sensitive data should be handled carefully
+     * - Avoid logging environment variables with secrets
+     * - Use appropriate file permissions for environment files
+     * - Consider using secure environment variable management
+     *
+     * @optional
+     * @example Basic environment injection
+     * ```typescript
+     * const options: ShellExecOptions = {
+     *   env: { PATH: '/usr/bin:/usr/local/bin' }
+     * };
+     * ```
+     *
+     * @example With API keys
+     * ```typescript
+     * const options: ShellExecOptions = {
+     *   env: {
+     *     API_KEY: process.env.API_KEY,
+     *     NODE_ENV: 'production'
+     *   }
+     * };
+     * ```
      */
-    execPromise?: ExecPromiseFunction;
-}
-/**
- * Shell class for command execution
- * @class
- * @description Provides methods for executing shell commands with caching and templating support
- */
-declare class Shell implements ShellInterface {
-    config: ShellConfig;
-    private cache;
+    env?: Record<string, string>;
     /**
-     * Creates a new Shell instance
-     * @param config - Shell configuration
-     * @param cache - Command cache map
+     * Result to return when in dry-run mode
+     *
+     * Core concept:
+     * Specifies the value to return when dry-run mode is
+     * enabled, allowing for predictable testing and
+     * validation without actual command execution.
+     *
+     * Dry run behavior:
+     * - Command is not actually executed
+     * - Returns the specified result value
+     * - Maintains logging for debugging
+     * - Useful for command validation and testing
+     * - Supports both string and object result types
+     *
+     * Testing scenarios:
+     * - Command generation validation
+     * - Template formatting verification
+     * - Configuration testing without side effects
+     * - Script logic debugging
+     * - Safe exploration of command behavior
+     *
+     * Result types:
+     * - String: Simple text output simulation
+     * - Object: Complex result structure simulation
+     * - Array: Multiple output line simulation
+     * - Function: Dynamic result generation
+     *
+     * @optional
+     * @example Basic dry run result
+     * ```typescript
+     * const options: ShellExecOptions = {
+     *   dryRun: true,
+     *   dryRunResult: 'Command would execute successfully'
+     * };
+     * ```
+     *
+     * @example Complex dry run result
+     * ```typescript
+     * const options: ShellExecOptions = {
+     *   dryRun: true,
+     *   dryRunResult: {
+     *     status: 'success',
+     *     output: 'Files would be copied',
+     *     files: ['file1.txt', 'file2.txt']
+     *   }
+     * };
+     * ```
      */
-    constructor(config: ShellConfig, cache?: Map<string, Promise<string>>);
+    dryRunResult?: unknown;
     /**
-     * Gets the logger instance
+     * Whether to perform a dry run without actual execution
+     *
+     * Core concept:
+     * Controls whether the command should be executed or
+     * simulated, providing a safe way to test command
+     * generation and validation without side effects.
+     *
+     * Dry run mode:
+     * - Commands are logged but not executed
+     * - Returns predefined result for testing
+     * - Useful for command validation and debugging
+     * - Maintains logging for debugging purposes
+     * - Supports both global and per-command dry run
+     *
+     * Override behavior:
+     * - Overrides shell config.isDryRun if set
+     * - Per-command setting takes precedence
+     * - Global setting provides default behavior
+     * - Allows fine-grained control over execution
+     * - Maintains consistency across command types
+     *
+     * Use cases:
+     * - Testing command generation and formatting
+     * - Validating configuration and options
+     * - Debugging script logic without side effects
+     * - Safe exploration of script behavior
+     * - CI/CD pipeline validation
+     *
+     * @optional
+     * @example Basic dry run
+     * ```typescript
+     * const options: ShellExecOptions = { dryRun: true };
+     * // Command is logged but not executed
+     * ```
+     *
+     * @example Conditional dry run
+     * ```typescript
+     * const options: ShellExecOptions = {
+     *   dryRun: process.env.DRY_RUN === 'true'
+     * };
+     * ```
      */
-    get logger(): LoggerInterface;
+    dryRun?: boolean;
     /**
-     * Formats a template string with context
-     * @param template - Template string
-     * @param context - Context object for template interpolation
-     * @returns Formatted string
+     * Template context for command string interpolation
+     *
+     * Core concept:
+     * Provides variables and data for template string
+     * interpolation, enabling dynamic command generation
+     * based on runtime context and configuration.
+     *
+     * Template features:
+     * - Uses lodash template for powerful interpolation
+     * - Supports complex template expressions and logic
+     * - Handles undefined and null context values gracefully
+     * - Enables dynamic command construction
+     * - Supports nested object access and function calls
+     *
+     * Context usage:
+     * - Variable substitution in command strings
+     * - Conditional command generation
+     * - Dynamic path and parameter construction
+     * - Environment-specific command customization
+     * - Runtime configuration injection
+     *
+     * Template syntax:
+     * - `<%= variable %>` for escaped output
+     * - `<%- variable %>` for unescaped output
+     * - `<% code %>` for JavaScript code execution
+     * - Supports nested object access and function calls
+     *
+     * @optional
+     * @example Basic template context
+     * ```typescript
+     * const options: ShellExecOptions = {
+     *   context: { repo: 'https://github.com/user/repo.git' }
+     * };
+     * // Used with: 'git clone <%= repo %>'
+     * ```
+     *
+     * @example Complex template context
+     * ```typescript
+     * const options: ShellExecOptions = {
+     *   context: {
+     *     branch: 'main',
+     *     repo: { url: 'https://github.com/user/repo.git' },
+     *     flags: ['--depth=1', '--single-branch']
+     *   }
+     * };
+     * ```
      */
-    static format(template?: string, context?: Record<string, unknown>): string;
+    context?: Record<string, unknown>;
     /**
-     * Formats a template string with context and error handling
-     * @param template - Template string
-     * @param context - Context object for template interpolation
-     * @returns Formatted string
-     * @throws Error if template formatting fails
+     * Encoding for command output processing
+     *
+     * Core concept:
+     * Specifies the character encoding used for command
+     * output processing, ensuring proper handling of
+     * international characters and special symbols.
+     *
+     * Encoding behavior:
+     * - Affects how command output is interpreted
+     * - Ensures proper character encoding for output
+     * - Supports various encoding formats
+     * - Handles international character sets
+     * - Maintains consistency across platforms
+     *
+     * Common encodings:
+     * - 'utf8': Unicode UTF-8 encoding (default)
+     * - 'ascii': ASCII encoding for basic text
+     * - 'base64': Base64 encoding for binary data
+     * - 'hex': Hexadecimal encoding for binary data
+     * - 'latin1': Latin-1 encoding for legacy systems
+     *
+     * Use cases:
+     * - International character handling
+     * - Binary data processing
+     * - Legacy system integration
+     * - Cross-platform compatibility
+     * - Special character processing
+     *
+     * @optional
+     * @example UTF-8 encoding
+     * ```typescript
+     * const options: ShellExecOptions = { encoding: 'utf8' };
+     * ```
+     *
+     * @example Base64 encoding
+     * ```typescript
+     * const options: ShellExecOptions = { encoding: 'base64' };
+     * ```
      */
-    format(template?: string, context?: Record<string, unknown>): string;
+    encoding?: BufferEncoding;
     /**
-     * Executes a command with options
-     * @param command - Command string or array
-     * @param options - Execution options
-     * @returns Promise resolving to command output
+     * Whether to cache the command result for performance optimization
+     *
+     * Core concept:
+     * Controls whether the command result should be cached
+     * to avoid repeated execution of identical commands,
+     * providing performance optimization for repeated operations.
+     *
+     * Caching behavior:
+     * - Caches command results for repeated access
+     * - Uses command string as cache key
+     * - Respects per-command and global cache settings
+     * - Provides performance optimization for repeated commands
+     * - Handles cache misses gracefully
+     *
+     * Performance benefits:
+     * - Reduces file system I/O operations
+     * - Avoids repeated command execution
+     * - Particularly beneficial in build tools and CLI applications
+     * - Improves script execution performance
+     * - Reduces resource consumption
+     *
+     * Cache management:
+     * - Cache is shared across command executions
+     * - Supports concurrent command execution
+     * - Automatic memory management
+     * - Cache invalidation through command options
+     * - Simple cache implementation for reliability
+     *
+     * @optional
+     * @default `false`
+     * @example Basic caching
+     * ```typescript
+     * const options: ShellExecOptions = { isCache: true };
+     * // Command result will be cached for future use
+     * ```
+     *
+     * @example Conditional caching
+     * ```typescript
+     * const options: ShellExecOptions = {
+     *   isCache: command.includes('npm install')
+     * };
+     * // Only cache npm install commands
+     * ```
      */
-    exec(command: string | string[], options?: ShellExecOptions): Promise<string>;
+    isCache?: boolean;
     /**
-     * Executes a command silently
-     * @param command - Command string or array
-     * @param options - Execution options
-     * @returns Promise resolving to command output
-     * @deprecated Use `exec` instead
+     * Additional custom options for extensibility
+     *
+     * Core concept:
+     * Provides extensibility for custom options and
+     * implementation-specific configurations that
+     * may not be covered by the standard interface.
+     *
+     * Extensibility features:
+     * - Supports any additional string-keyed properties
+     * - Maintains type safety for known properties
+     * - Allows implementation-specific customization
+     * - Provides backward compatibility for future extensions
+     * - Supports custom execution strategies
+     *
+     * Use cases:
+     * - Custom execution function parameters
+     * - Implementation-specific configurations
+     * - Third-party integration options
+     * - Future interface extensions
+     * - Custom validation and processing
+     *
+     * @optional
+     * @example Custom options
+     * ```typescript
+     * const options: ShellExecOptions = {
+     *   customOption: 'value',
+     *   timeout: 5000,
+     *   retries: 3
+     * };
+     * ```
      */
-    run(command: string | string[], options?: ShellExecOptions): Promise<string>;
+    [key: string]: unknown;
+}
+/**
+ * Interface for shell command execution with comprehensive capabilities
+ *
+ * Core concept:
+ * Defines a standardized interface for executing shell commands
+ * with support for various command formats, execution options,
+ * and result handling across different execution environments.
+ *
+ * Main features:
+ * - Command execution: Flexible command execution with options
+ *   - Supports both string and array command formats
+ *   - Comprehensive execution options for customization
+ *   - Promise-based asynchronous execution
+ *   - Consistent error handling and reporting
+ *
+ * - Execution abstraction: Platform-independent command execution
+ *   - Abstracts shell execution details
+ *   - Provides consistent interface across platforms
+ *   - Supports custom execution strategies
+ *   - Maintains backward compatibility
+ *
+ * - Result handling: Standardized result processing
+ *   - Returns command output as string
+ *   - Handles both success and error conditions
+ *   - Provides consistent error reporting
+ *   - Supports output encoding and processing
+ *
+ * Design considerations:
+ * - Simple interface for maximum compatibility
+ * - Promise-based for modern async/await usage
+ * - Extensible through execution options
+ * - Platform-independent implementation
+ * - Consistent error handling across implementations
+ *
+ * Implementation requirements:
+ * - Must handle both string and array command formats
+ * - Should support all ShellExecOptions properties
+ * - Must return Promise<string> for command output
+ * - Should provide meaningful error messages
+ * - Must handle command execution failures gracefully
+ *
+ * @example Basic implementation
+ * ```typescript
+ * const shell: ShellInterface = {
+ *   exec: async (command, options) => {
+ *     // Logic to execute the command
+ *     return 'Command output';
+ *   }
+ * };
+ * ```
+ *
+ * @example With error handling
+ * ```typescript
+ * const shell: ShellInterface = {
+ *   exec: async (command, options) => {
+ *     try {
+ *       // Command execution logic
+ *       return await executeCommand(command, options);
+ *     } catch (error) {
+ *       throw new Error(`Command execution failed: ${error.message}`);
+ *     }
+ *   }
+ * };
+ * ```
+ *
+ * @example Usage with options
+ * ```typescript
+ * const output = await shell.exec('npm install', {
+ *   cwd: '/project/root',
+ *   silent: true,
+ *   env: { NODE_ENV: 'production' }
+ * });
+ * ```
+ */
+interface ShellInterface {
     /**
-     * Executes a formatted command with caching
-     * @param command - Formatted command string or array
-     * @param options - Execution options
-     * @returns Promise resolving to command output
+     * Execute a shell command with optional configuration
+     *
+     * Core concept:
+     * Provides the main method for executing shell commands
+     * with comprehensive options for customization, error
+     * handling, and result processing.
+     *
+     * Command execution:
+     * - Supports both string and array command formats
+     * - Handles command parsing and validation
+     * - Provides comprehensive execution options
+     * - Returns Promise for asynchronous execution
+     * - Maintains consistent error handling
+     *
+     * Execution options:
+     * - Environment variable injection
+     * - Working directory specification
+     * - Output encoding configuration
+     * - Silent mode for quiet execution
+     * - Dry run mode for safe testing
+     * - Template context for dynamic commands
+     * - Caching for performance optimization
+     *
+     * Result handling:
+     * - Returns command output as string
+     * - Handles both success and error conditions
+     * - Provides consistent error reporting
+     * - Supports output encoding and processing
+     * - Maintains command execution context
+     *
+     * Error handling:
+     * - Throws errors for command execution failures
+     * - Provides meaningful error messages
+     * - Maintains error context and stack traces
+     * - Handles various failure scenarios
+     * - Supports error recovery and retry logic
+     *
+     * @param command - Command to execute (string or array of command parts)
+     * @param options - Optional execution options for customization
+     * @returns Promise resolving to command output string
+     * @throws Error when command execution fails
+     *
+     * @example Basic command execution
+     * ```typescript
+     * const output = await shell.exec('npm install');
+     * console.log('Installation output:', output);
+     * ```
+     *
+     * @example Array command format
+     * ```typescript
+     * const output = await shell.exec(['git', 'commit', '-m', 'Update docs']);
+     * ```
+     *
+     * @example With execution options
+     * ```typescript
+     * const output = await shell.exec('npm run build', {
+     *   cwd: '/project/root',
+     *   silent: true,
+     *   env: { NODE_ENV: 'production' }
+     * });
+     * ```
+     *
+     * @example Template-based command
+     * ```typescript
+     * const output = await shell.exec('git clone <%= repo %>', {
+     *   context: { repo: 'https://github.com/user/repo.git' }
+     * });
+     * ```
      */
-    execFormattedCommand(command: string | string[], options?: ShellExecOptions): Promise<string>;
+    exec(command: string | string[], options?: ShellExecOptions): Promise<string>;
 }
 
 /**
- * Create a new ConfigSearch instance with fe configuration
- * @param feConfig - Custom fe configuration
- * @returns ConfigSearch instance
- * @description
- * Significance: Creates configuration search utility
- * Core idea: Merge default and custom configurations
- * Main function: Initialize configuration search
- * Main purpose: Provide configuration discovery
+ * Function type for executing shell commands
  *
- * @example
+ * Core concept:
+ * Defines the signature for command execution functions that
+ * can be injected into the Shell class for flexible command
+ * execution strategies.
+ *
+ * Function signature:
+ * - Accepts command as string or array of strings
+ * - Accepts execution options for customization
+ * - Returns Promise resolving to command output
+ * - Handles command execution and error conditions
+ *
+ * @param command - Command string or array of command parts
+ * @param options - Shell execution options for customization
+ * @returns Promise resolving to command output (trimmed)
+ *
+ * @example Basic usage
  * ```typescript
- * const configSearch = getFeConfigSearch({ debug: true });
+ * const execFn: ExecPromiseFunction = async (command, options) => {
+ *   // Custom command execution logic
+ *   return 'command output';
+ * };
  * ```
  */
-declare function getFeConfigSearch(feConfig?: Record<string, unknown>): ConfigSearch;
-type ScriptContextOptions<T> = T & {
-    execPromise?: ExecPromiseFunction;
-};
+type ExecPromiseFunction = (command: string | string[], options: ShellExecOptions) => Promise<string>;
 /**
- * Options interface for FeScriptContext
- * @interface
- * @description
- * Significance: Defines script execution context options
- * Core idea: Centralize script execution configuration
- * Main function: Type-safe context options
- * Main purpose: Configure script execution environment
+ * Configuration interface for Shell class initialization
  *
- * @example
+ * Core concept:
+ * Defines the configuration parameters required to initialize
+ * a Shell instance with logging, execution, and caching capabilities.
+ *
+ * Configuration components:
+ * - Logger: Required for command logging and error reporting
+ * - Execution function: Optional custom command execution strategy
+ * - Execution options: Inherited from ShellExecOptions for command customization
+ *
+ * @example Basic configuration
+ * ```typescript
+ * const config: ShellConfig = {
+ *   logger: myLogger,
+ *   dryRun: false,
+ *   isCache: true
+ * };
+ * ```
+ *
+ * @example With custom execution function
  * ```typescript
- * const options: FeScriptContextOptions<T> = {
- *   logger: new ScriptsLogger(),
+ * const config: ShellConfig = {
+ *   logger: myLogger,
+ *   execPromise: customExecFunction,
  *   dryRun: true
  * };
  * ```
  */
-interface FeScriptContextOptions<T> {
-    /** Custom logger instance */
-    logger?: LoggerInterface;
-    /** Shell instance for command execution */
-    shell?: Shell;
-    /** Custom fe configuration */
-    feConfig?: Record<string, unknown>;
-    /** Whether to perform dry run */
-    dryRun?: boolean;
-    /** Enable verbose logging */
-    verbose?: boolean;
-    /** Additional script-specific options */
-    options?: ScriptContextOptions<T>;
+interface ShellConfig extends ShellExecOptions {
+    /**
+     * Logger instance for command logging and error reporting
+     *
+     * Used for:
+     * - Logging command execution details
+     * - Reporting template formatting errors
+     * - Debug information for command execution
+     * - Error messages and stack traces
+     *
+     * @example `new Logger({ level: 'info', handlers: new ConsoleHandler() })`
+     */
+    logger: LoggerInterface;
+    /**
+     * Custom command execution function
+     *
+     * Optional function to override the default command execution
+     * strategy. When not provided, the Shell class will throw an
+     * error if no execution function is available.
+     *
+     * Use cases:
+     * - Custom command execution logic
+     * - Integration with specific shell environments
+     * - Mock functions for testing
+     * - Enhanced error handling and reporting
+     *
+     * @optional
+     * @example
+     * ```typescript
+     * const customExec: ExecPromiseFunction = async (command, options) => {
+     *   // Custom execution logic
+     *   return await executeCommand(command, options);
+     * };
+     * ```
+     */
+    execPromise?: ExecPromiseFunction;
 }
 /**
- * Script execution context class
- * @class
- * @description
- * Significance: Manages script execution environment
- * Core idea: Provide unified context for script execution
- * Main function: Initialize and maintain script context
- * Main purpose: Standardize script execution environment
+ * Shell class for command execution with templating and caching support
  *
- * @example
+ * Core concept:
+ * Provides a comprehensive command execution interface with
+ * template string formatting, command caching, dry run support,
+ * and integrated logging capabilities.
+ *
+ * Main features:
+ * - Template formatting: Dynamic command generation with context
+ *   - Uses lodash template for string interpolation
+ *   - Supports complex template expressions
+ *   - Provides error handling for template failures
+ *   - Enables dynamic command construction
+ *
+ * - Command caching: Performance optimization for repeated commands
+ *   - Caches command results to avoid repeated execution
+ *   - Configurable caching per command
+ *   - Memory-efficient cache management
+ *   - Cache invalidation through command options
+ *
+ * - Dry run support: Safe command testing and validation
+ *   - Executes commands without actual system impact
+ *   - Returns predefined results for testing
+ *   - Useful for command validation and debugging
+ *   - Supports both global and per-command dry run
+ *
+ * - Integrated logging: Comprehensive command execution tracking
+ *   - Logs command execution details
+ *   - Reports template formatting errors
+ *   - Provides debug information for troubleshooting
+ *   - Supports silent mode for quiet execution
+ *
+ * Design considerations:
+ * - Uses dependency injection for execution functions
+ * - Provides flexible configuration options
+ * - Maintains backward compatibility with existing interfaces
+ * - Supports both string and array command formats
+ * - Implements proper error handling and reporting
+ *
+ * Performance optimizations:
+ * - Command result caching for repeated executions
+ * - Efficient template compilation and caching
+ * - Minimal memory footprint for cache storage
+ * - Lazy initialization of execution functions
+ *
+ * @example Basic usage
  * ```typescript
- * const context = new FeScriptContext<MyOptions>({
- *   dryRun: true,
- *   verbose: true
+ * const shell = new Shell({
+ *   logger: myLogger,
+ *   dryRun: false
+ * });
+ *
+ * const output = await shell.exec('npm install');
+ * ```
+ *
+ * @example With template formatting
+ * ```typescript
+ * const shell = new Shell({ logger: myLogger });
+ * const output = await shell.exec('git clone <%= repo %>', {
+ *   context: { repo: 'https://github.com/user/repo.git' }
+ * });
+ * ```
+ *
+ * @example With caching
+ * ```typescript
+ * const shell = new Shell({ logger: myLogger, isCache: true });
+ * // First execution
+ * await shell.exec('npm install');
+ * // Second execution uses cached result
+ * await shell.exec('npm install');
+ * ```
+ *
+ * @example Dry run mode
+ * ```typescript
+ * const shell = new Shell({ logger: myLogger, dryRun: true });
+ * const output = await shell.exec('rm -rf /', {
+ *   dryRunResult: 'Would delete all files'
  * });
+ * // Returns 'Would delete all files' without executing command
  * ```
  */
-declare class FeScriptContext<T = unknown> {
-    /** Logger instance */
-    readonly logger: LoggerInterface;
-    /** Shell instance */
-    readonly shell: Shell;
-    /** Fe configuration */
-    readonly feConfig: FeConfig;
-    /** Dry run flag */
-    readonly dryRun: boolean;
-    /** Verbose logging flag */
-    readonly verbose: boolean;
-    /** Script-specific options */
-    options: ScriptContextOptions<T>;
+declare class Shell implements ShellInterface {
+    config: ShellConfig;
+    private cache;
     /**
-     * Creates a FeScriptContext instance
+     * Creates a new Shell instance with the specified configuration
      *
-     * @description
-     * Significance: Initializes script execution context
-     * Core idea: Setup execution environment
-     * Main function: Create context with options
-     * Main purpose: Prepare script execution environment
+     * Core concept:
+     * Initializes a Shell instance with logging, execution, and
+     * caching capabilities based on the provided configuration.
      *
-     * @example
+     * Initialization process:
+     * 1. Validates and stores configuration parameters
+     * 2. Initializes command cache for performance optimization
+     * 3. Sets up logging integration for command tracking
+     * 4. Prepares template formatting capabilities
+     *
+     * Configuration validation:
+     * - Logger is required for command logging and error reporting
+     * - Execution function is optional but required for actual command execution
+     * - Cache is initialized as an empty Map for command result storage
+     * - All ShellExecOptions are inherited and validated
+     *
+     * Cache initialization:
+     * - Uses Map for efficient key-value storage
+     * - Stores Promise<string> for command results
+     * - Supports concurrent command execution
+     * - Provides automatic memory management
+     *
+     * @param config - Shell configuration with logger and execution options
+     * @param cache - Optional command cache map for result storage
+     *
+     * @example Basic initialization
      * ```typescript
-     * const context = new FeScriptContext({
+     * const shell = new Shell({
+     *   logger: myLogger,
+     *   dryRun: false,
+     *   isCache: true
+     * });
+     * ```
+     *
+     * @example With custom cache
+     * ```typescript
+     * const customCache = new Map<string, Promise<string>>();
+     * const shell = new Shell({ logger: myLogger }, customCache);
+     * ```
+     */
+    constructor(config: ShellConfig, cache?: Map<string, Promise<string>>);
+    /**
+     * Gets the logger instance for command logging and error reporting
+     *
+     * Core concept:
+     * Provides access to the configured logger instance for
+     * command execution tracking and error reporting.
+     *
+     * Logger usage:
+     * - Command execution logging (debug level)
+     * - Template formatting error reporting
+     * - Command execution error logging
+     * - Debug information for troubleshooting
+     *
+     * @returns Logger instance for command logging and error reporting
+     *
+     * @example Basic usage
+     * ```typescript
+     * const logger = shell.logger;
+     * logger.info('Shell instance created');
+     * ```
+     */
+    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
+     *
+     * 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
+     *
+     * @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
+     * ```typescript
+     * 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 %>',
+     *   { 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;
+    /**
+     * Formats a template string with context and comprehensive error handling
+     *
+     * Core concept:
+     * Provides instance-based template formatting with detailed
+     * error logging and exception handling for debugging and
+     * troubleshooting template issues.
+     *
+     * Error handling:
+     * - Catches template compilation errors
+     * - Logs detailed error information including template and context
+     * - Provides stack trace information for debugging
+     * - Re-throws errors for proper error propagation
+     *
+     * Logging features:
+     * - Logs template content for debugging
+     * - Logs context object for variable inspection
+     * - Logs error details and stack traces
+     * - Uses error level for template failures
+     *
+     * Debugging support:
+     * - Provides template content in error messages
+     * - Includes context object for variable inspection
+     * - Logs complete error information for troubleshooting
+     * - Maintains error stack traces for debugging
+     *
+     * @param template - Template string with interpolation placeholders
+     * @param context - Context object for template variable substitution
+     * @returns Formatted string with context values substituted
+     * @throws Error if template formatting fails with detailed logging
+     *
+     * @example Basic formatting
+     * ```typescript
+     * const result = shell.format('Hello <%= name %>!', { name: 'World' });
+     * // Returns: 'Hello World!'
+     * ```
+     *
+     * @example Error handling
+     * ```typescript
+     * try {
+     *   const result = shell.format('Hello <%= name %>!', {});
+     * } catch (error) {
+     *   // Error is logged with template and context information
+     *   console.error('Template formatting failed:', error.message);
+     * }
+     * ```
+     */
+    format(template?: string, context?: Record<string, unknown>): string;
+    /**
+     * Executes a command with template formatting and execution options
+     *
+     * Core concept:
+     * Provides the main command execution interface with template
+     * formatting support, allowing dynamic command generation
+     * based on context variables.
+     *
+     * Execution process:
+     * 1. Extracts context from options for template formatting
+     * 2. Formats command string with context if command is a string
+     * 3. Passes formatted command to execution engine
+     * 4. Handles both string and array command formats
+     * 5. Applies execution options for customization
+     *
+     * Template formatting:
+     * - Only applies to string commands (not arrays)
+     * - Uses context object for variable substitution
+     * - Handles template formatting errors gracefully
+     * - Supports complex template expressions
+     *
+     * Command handling:
+     * - String commands: Formatted with context before execution
+     * - Array commands: Passed directly to execution engine
+     * - Mixed formats: Handled appropriately based on type
+     * - Options: Applied consistently across all command types
+     *
+     * @param command - Command string (with template) or array of command parts
+     * @param options - Execution options including context for template formatting
+     * @returns Promise resolving to command output
+     *
+     * @example String command with template
+     * ```typescript
+     * const output = await shell.exec('git clone <%= repo %>', {
+     *   context: { repo: 'https://github.com/user/repo.git' }
+     * });
+     * ```
+     *
+     * @example Array command
+     * ```typescript
+     * const output = await shell.exec(['git', 'clone', 'https://github.com/user/repo.git']);
+     * ```
+     *
+     * @example With execution options
+     * ```typescript
+     * const output = await shell.exec('npm install', {
+     *   cwd: '/path/to/project',
+     *   silent: true,
+     *   dryRun: false
+     * });
+     * ```
+     */
+    exec(command: string | string[], options?: ShellExecOptions): Promise<string>;
+    /**
+     * Executes a command silently (deprecated)
+     *
+     * Core concept:
+     * Legacy method for silent command execution, now deprecated
+     * in favor of the more flexible `exec` method with silent option.
+     *
+     * Deprecation notice:
+     * - This method is deprecated and will be removed in future versions
+     * - Use `exec` method with `silent: true` option instead
+     * - Provides backward compatibility for existing code
+     * - Maintains same functionality through `exec` method
+     *
+     * Silent execution:
+     * - Suppresses command logging output
+     * - Maintains error logging for debugging
+     * - Useful for quiet command execution
+     * - Reduces log noise in automated scripts
+     *
+     * @param command - Command string or array
+     * @param options - Execution options (silent mode is automatically enabled)
+     * @returns Promise resolving to command output
+     * @deprecated Use `exec` method with `silent: true` option instead
+     *
+     * @example Deprecated usage
+     * ```typescript
+     * const output = await shell.run('npm install');
+     * ```
+     *
+     * @example Recommended replacement
+     * ```typescript
+     * const output = await shell.exec('npm install', { silent: true });
+     * ```
+     */
+    run(command: string | string[], options?: ShellExecOptions): Promise<string>;
+    /**
+     * Executes a formatted command with caching and dry run support
+     *
+     * Core concept:
+     * Core execution engine that handles command execution with
+     * caching, dry run support, and comprehensive logging.
+     *
+     * Execution flow:
+     * 1. Validates execution function availability
+     * 2. Determines dry run and caching settings
+     * 3. Logs command for debugging (unless silent)
+     * 4. Returns dry run result or cached result if available
+     * 5. Executes command and caches result if caching enabled
+     * 6. Returns command execution result
+     *
+     * Caching behavior:
+     * - Uses command string as cache key
+     * - Caches Promise<string> for concurrent access
+     * - Respects per-command and global cache settings
+     * - Provides performance optimization for repeated commands
+     * - Handles cache misses gracefully
+     *
+     * Dry run support:
+     * - Returns predefined result without execution
+     * - Supports both global and per-command dry run
+     * - Useful for command validation and testing
+     * - Maintains logging for debugging
+     *
+     * Error handling:
+     * - Validates execution function availability
+     * - Handles cache access errors gracefully
+     * - Propagates execution errors to caller
+     * - Provides detailed logging for debugging
+     *
+     * @param command - Formatted command string or array
+     * @param options - Execution options for customization
+     * @returns Promise resolving to command output
+     * @throws Error if execution function is not available
+     *
+     * @example Basic execution
+     * ```typescript
+     * const output = await shell.execFormattedCommand('npm install');
+     * ```
+     *
+     * @example With caching
+     * ```typescript
+     * const output1 = await shell.execFormattedCommand('npm install', { isCache: true });
+     * const output2 = await shell.execFormattedCommand('npm install', { isCache: true });
+     * // Second call uses cached result
+     * ```
+     *
+     * @example Dry run mode
+     * ```typescript
+     * const output = await shell.execFormattedCommand('rm -rf /', {
      *   dryRun: true,
-     *   options: { branch: 'main' }
+     *   dryRunResult: 'Would delete all files'
+     * });
+     * // Returns 'Would delete all files' without execution
+     * ```
+     */
+    execFormattedCommand(command: string | string[], options?: ShellExecOptions): Promise<string>;
+}
+
+/**
+ * Core interface for script execution context with integrated capabilities
+ *
+ * Core concept:
+ * Defines the complete interface for script execution contexts that
+ * provide integrated logging, shell execution, configuration management,
+ * and script-specific options in a unified environment.
+ *
+ * Main components:
+ * - Logger: Structured logging with timestamp formatting and verbosity control
+ * - Shell: Command execution with templating, caching, and dry run support
+ * - Configuration: Merged fe-config with script-specific overrides
+ * - Execution control: Dry run and verbose mode flags
+ * - Script options: Type-safe script-specific configuration with execution function
+ *
+ * Design considerations:
+ * - Uses generic type constraints for type-safe script options
+ * - Provides readonly properties for immutable context components
+ * - Integrates execution function into script options for flexibility
+ * - Maintains backward compatibility with existing implementations
+ * - Supports both development and production environments
+ *
+ * Type safety:
+ * - Generic type parameter ensures script-specific option types
+ * - Readonly properties prevent accidental modification
+ * - Optional execution function for custom command execution
+ * - Extends ScriptSharedInterface for common functionality
+ *
+ * @example Basic usage
+ * ```typescript
+ * interface BuildOptions extends ScriptSharedInterface {
+ *   target: 'development' | 'production';
+ *   outputDir: string;
+ * }
+ *
+ * const context: ScriptContextInterface<BuildOptions> = {
+ *   logger: myLogger,
+ *   shell: myShell,
+ *   feConfig: mergedConfig,
+ *   dryRun: false,
+ *   verbose: true,
+ *   options: {
+ *     target: 'production',
+ *     outputDir: './dist',
+ *     env: environment
+ *   }
+ * };
+ * ```
+ *
+ * @example With custom execution function
+ * ```typescript
+ * const context: ScriptContextInterface<DeployOptions> = {
+ *   // ... other properties
+ *   options: {
+ *     region: 'us-east-1',
+ *     execPromise: customExecFunction
+ *   }
+ * };
+ * ```
+ */
+interface ScriptContextInterface<Opt extends ScriptSharedInterface> {
+    /**
+     * Logger instance for structured logging and error reporting
+     *
+     * Core concept:
+     * Provides access to the configured logger instance for
+     * command execution tracking, error reporting, and debug
+     * information throughout the script execution lifecycle.
+     *
+     * Logger capabilities:
+     * - Timestamp-formatted logging with timezone support
+     * - Configurable verbosity levels (debug/info/warn/error)
+     * - Script name identification for multi-script environments
+     * - Console output with structured formatting
+     * - Error logging with stack traces
+     *
+     * Usage patterns:
+     * - Command execution logging (debug level)
+     * - Configuration loading and validation
+     * - Error reporting and debugging
+     * - Progress tracking and status updates
+     *
+     * @readonly
+     * @example
+     * ```typescript
+     * context.logger.info('Starting build process');
+     * context.logger.debug('Configuration loaded:', context.feConfig);
+     * context.logger.error('Build failed:', error);
+     * ```
+     */
+    readonly logger: LoggerInterface;
+    /**
+     * Shell interface for command execution and management
+     *
+     * Core concept:
+     * Provides command execution capabilities with template
+     * formatting, caching, dry run support, and integrated
+     * logging for comprehensive command management.
+     *
+     * Shell features:
+     * - Template string formatting with context variables
+     * - Command result caching for performance optimization
+     * - Dry run mode for safe command testing
+     * - Silent mode for quiet execution
+     * - Integrated logging for command tracking
+     *
+     * Execution capabilities:
+     * - String and array command formats
+     * - Environment variable injection
+     * - Working directory control
+     * - Custom execution function support
+     * - Error handling and reporting
+     *
+     * @readonly
+     * @example
+     * ```typescript
+     * await context.shell.exec('npm install', { cwd: context.options.rootPath });
+     * await context.shell.exec('git clone <%= repo %>', {
+     *   context: { repo: 'https://github.com/user/repo.git' }
      * });
      * ```
      */
-    constructor(scriptsOptions?: FeScriptContextOptions<T>);
+    readonly shell: ShellInterface;
+    /**
+     * Merged fe-configuration object with script-specific overrides
+     *
+     * Core concept:
+     * Contains the complete configuration after merging default
+     * fe-config with script-specific overrides, providing a
+     * unified configuration interface.
+     *
+     * Configuration structure:
+     * - Default fe-config provides base values
+     * - Script-specific sections override defaults
+     * - Environment-specific configurations
+     * - Nested object merging with lodash defaultsDeep
+     * - Type-safe configuration access
+     *
+     * Configuration sources:
+     * - Default fe-config files (fe-config.json, etc.)
+     * - Script-specific configuration sections
+     * - Environment variable overrides
+     * - Runtime configuration updates
+     *
+     * @readonly
+     * @example
+     * ```typescript
+     * const buildConfig = context.feConfig.build;
+     * const deployConfig = context.feConfig.deploy;
+     * const envOrder = context.feConfig.envOrder;
+     * ```
+     */
+    readonly feConfig: FeConfig;
+    /**
+     * Whether to run in dry run mode for safe testing
+     *
+     * Core concept:
+     * Controls whether commands are actually executed or
+     * simulated for safe testing and validation purposes.
+     *
+     * Dry run behavior:
+     * - Commands are logged but not executed
+     * - Returns predefined results for testing
+     * - Useful for command validation and debugging
+     * - Maintains logging for debugging purposes
+     * - Supports both global and per-command dry run
+     *
+     * Use cases:
+     * - Testing command generation and formatting
+     * - Validating configuration and options
+     * - Debugging script logic without side effects
+     * - Safe exploration of script behavior
+     *
+     * @readonly
+     * @example
+     * ```typescript
+     * if (context.dryRun) {
+     *   context.logger.info('DRY RUN: Would execute command');
+     * } else {
+     *   await context.shell.exec(command);
+     * }
+     * ```
+     */
+    readonly dryRun: boolean;
+    /**
+     * Whether to enable verbose logging for detailed output
+     *
+     * Core concept:
+     * Controls the level of detail in logging output,
+     * enabling debug-level information for troubleshooting
+     * and detailed execution tracking.
+     *
+     * Verbose mode effects:
+     * - Enables debug-level logging output
+     * - Provides detailed execution information
+     * - Shows configuration loading details
+     * - Displays command execution steps
+     * - Includes performance and timing information
+     *
+     * Logging levels:
+     * - true: Debug level (detailed information)
+     * - false: Info level (essential information only)
+     * - Affects both console output and log filtering
+     * - Maintains error logging regardless of setting
+     *
+     * @readonly
+     * @example
+     * ```typescript
+     * if (context.verbose) {
+     *   context.logger.debug('Loading configuration from:', configPath);
+     *   context.logger.debug('Environment variables:', envVars);
+     * }
+     * ```
+     */
+    readonly verbose: boolean;
+    /**
+     * Script-specific options with execution function integration
+     *
+     * Core concept:
+     * Contains all script configuration options with defaults
+     * applied, environment integration, and optional custom
+     * execution function for command handling.
+     *
+     * Option structure:
+     * - Extends ScriptSharedInterface for common functionality
+     * - Includes script-specific configuration properties
+     * - Provides optional custom execution function
+     * - Supports deep merging with default values
+     * - Maintains type safety through generic constraints
+     *
+     * Execution function:
+     * - Optional custom command execution strategy
+     * - Overrides default shell execution behavior
+     * - Useful for testing, mocking, and custom logic
+     * - Maintains compatibility with ShellInterface
+     *
+     * @example Basic options
+     * ```typescript
+     * context.options = {
+     *   env: environment,
+     *   sourceBranch: 'develop',
+     *   rootPath: '/project/root',
+     *   target: 'production',
+     *   outputDir: './dist'
+     * };
+     * ```
+     *
+     * @example With custom execution function
+     * ```typescript
+     * context.options = {
+     *   // ... other options
+     *   execPromise: async (command, options) => {
+     *     // Custom execution logic
+     *     return await customExec(command, options);
+     *   }
+     * };
+     * ```
+     */
+    options: Opt & {
+        /**
+         * Optional custom command execution function
+         *
+         * Overrides the default command execution strategy
+         * for specialized command handling, testing, or
+         * integration with specific execution environments.
+         *
+         * Use cases:
+         * - Mock functions for testing
+         * - Custom execution logic
+         * - Integration with specific shell environments
+         * - Enhanced error handling and reporting
+         *
+         * @optional
+         * @example
+         * ```typescript
+         * execPromise: async (command, options) => {
+         *   console.log('Executing:', command);
+         *   return await executeWithCustomLogic(command, options);
+         * }
+         * ```
+         */
+        execPromise?: ExecPromiseFunction;
+    };
 }
 
+/**
+ * Color formatter for log output with customizable level-based coloring
+ *
+ * Core concept:
+ * Provides visual distinction between different log levels by applying
+ * chalk color functions to log level text, making log output more readable
+ * and easier to scan for different types of messages.
+ *
+ * Main features:
+ * - Level-based coloring: Each log level (fatal, error, warn, info, debug, trace, log)
+ *   has a distinct color scheme for quick visual identification
+ *   - Fatal: Red background with white bold text (highest visibility)
+ *   - Error: Red bold text (critical issues)
+ *   - Warn: Yellow bold text (warnings and potential issues)
+ *   - Info: Blue text (general information)
+ *   - Debug: Green text (debugging information)
+ *   - Trace: Gray text (detailed tracing)
+ *   - Log: White text (default logging)
+ *
+ * - Customizable colors: Supports custom color mapping through constructor
+ *   - Override default colors for specific levels
+ *   - Support both string colors and chalk function references
+ *   - Fallback to white color for unknown levels
+ *
+ * - Chalk integration: Leverages chalk library for cross-platform color support
+ *   - Consistent colors across different terminals and operating systems
+ *   - Support for various color formats and styles
+ *   - Automatic color detection and fallback for non-color terminals
+ *
+ * @example Basic usage
+ * ```typescript
+ * const formatter = new ColorFormatter();
+ * const formatted = formatter.format({
+ *   level: 'error',
+ *   args: ['Database connection failed']
+ * });
+ * // Returns: [chalk.red.bold('ERROR'), 'Database connection failed']
+ * ```
+ *
+ * @example Custom colors
+ * ```typescript
+ * const customFormatter = new ColorFormatter({
+ *   error: chalk.magenta.bold,
+ *   info: chalk.cyan,
+ *   custom: chalk.rainbow
+ * });
+ * ```
+ */
 declare class ColorFormatter implements FormatterInterface {
+    /**
+     * Custom color mapping for different log levels
+     *
+     * Overrides default color scheme for specific log levels.
+     * Each level can be mapped to a chalk color function or string.
+     * Unknown levels will use white color as fallback.
+     *
+     * @default `{
+     *   fatal: chalk.bgRed.white.bold,
+     *   error: chalk.red.bold,
+     *   warn: chalk.yellow.bold,
+     *   info: chalk.blue,
+     *   debug: chalk.green,
+     *   trace: chalk.gray,
+     *   log: chalk.white
+     * }`
+     */
     protected levelColors: Record<string, string | ((...args: unknown[]) => string)>;
-    constructor(levelColors?: Record<string, string | ((...args: unknown[]) => string)>);
+    /**
+     * Create a new color formatter with optional custom level colors
+     *
+     * @param levelColors - Custom color mapping for log levels
+     *   - Keys: Log level names (fatal, error, warn, info, debug, trace, log)
+     *   - Values: Chalk color functions or string color names
+     *   - Unknown levels fallback to white color
+     *   - Supports both function references and string values
+     *
+     * @example Default colors
+     * ```typescript
+     * const formatter = new ColorFormatter();
+     * ```
+     *
+     * @example Custom colors
+     * ```typescript
+     * const formatter = new ColorFormatter({
+     *   error: chalk.red.underline,
+     *   warn: chalk.orange.bold,
+     *   info: chalk.blue.italic
+     * });
+     * ```
+     */
+    constructor(
+    /**
+     * Custom color mapping for different log levels
+     *
+     * Overrides default color scheme for specific log levels.
+     * Each level can be mapped to a chalk color function or string.
+     * Unknown levels will use white color as fallback.
+     *
+     * @default `{
+     *   fatal: chalk.bgRed.white.bold,
+     *   error: chalk.red.bold,
+     *   warn: chalk.yellow.bold,
+     *   info: chalk.blue,
+     *   debug: chalk.green,
+     *   trace: chalk.gray,
+     *   log: chalk.white
+     * }`
+     */
+    levelColors?: Record<string, string | ((...args: unknown[]) => string)>);
+    /**
+     * Format log event by applying color to the level and preserving original arguments
+     *
+     * Processing steps:
+     * 1. Extract level and arguments from the log event
+     * 2. Look up the appropriate color function for the log level
+     * 3. Apply color function to uppercase level text
+     * 4. Return colored level followed by original arguments
+     *
+     * Color application:
+     * - Uses chalk color functions for consistent cross-platform support
+     * - Converts level to uppercase for better visibility
+     * - Preserves all original log arguments unchanged
+     * - Handles both function and string color values
+     *
+     * @param event - Log event containing level and arguments
+     * @returns Array with colored level text followed by original arguments
+     *
+     * @example Error level formatting
+     * ```typescript
+     * const result = formatter.format({
+     *   level: 'error',
+     *   args: ['Connection failed', { retryCount: 3 }]
+     * });
+     * // Returns: [chalk.red.bold('ERROR'), 'Connection failed', { retryCount: 3 }]
+     * ```
+     *
+     * @example Unknown level fallback
+     * ```typescript
+     * const result = formatter.format({
+     *   level: 'unknown',
+     *   args: ['Custom message']
+     * });
+     * // Returns: [chalk.white('UNKNOWN'), 'Custom message']
+     * ```
+     */
     format(event: LogEvent): unknown[];
 }
 
-export { ColorFormatter, ConfigSearch, FeScriptContext, Shell, defaultFeConfig, getFeConfigSearch };
-export type { ConfigSearchOptions, ExecPromiseFunction, FeConfig, FeReleaseConfig, FeScriptContextOptions, ScriptContextOptions, ShellConfig, ShellExecOptions, ShellInterface };
+/**
+ * Configuration search options for initializing ConfigSearch instances
+ *
+ * Core concept:
+ * Defines the configuration parameters for setting up a configuration search
+ * utility that can discover and load configuration files from various locations
+ * in a project directory structure.
+ *
+ * Design considerations:
+ * - Supports both name-based and custom search place configurations
+ * - Provides default configuration fallback for graceful degradation
+ * - Allows custom loaders for specialized file formats
+ * - Maintains backward compatibility with cosmiconfig options
+ * - Enables flexible configuration discovery strategies
+ *
+ * @example Basic usage
+ * ```typescript
+ * const options: ConfigSearchOptions = {
+ *   name: 'myapp',
+ *   defaultConfig: { port: 3000, debug: false }
+ * };
+ * ```
+ *
+ * @example Advanced usage with custom loaders
+ * ```typescript
+ * const options: ConfigSearchOptions = {
+ *   name: 'myapp',
+ *   searchPlaces: ['myapp.config.js', 'myapp.config.ts'],
+ *   loaders: {
+ *     '.toml': (filepath) => parseTOML(readFileSync(filepath, 'utf8'))
+ *   }
+ * };
+ * ```
+ */
+interface ConfigSearchOptions {
+    /**
+     * Base name for configuration files (used to generate default search patterns)
+     *
+     * This name is used to generate default search patterns for configuration files.
+     * For example, if name is 'myapp', it will search for files like:
+     * - myapp.json
+     * - myapp.js
+     * - myapp.ts
+     * - .myapp.json
+     * - etc.
+     *
+     * The name is also used as the cosmiconfig module name for package.json
+     * configuration discovery.
+     *
+     * @example `'myapp'` // Searches for myapp.* files
+     * @example `'fe-config'` // Searches for fe-config.* files
+     */
+    name: string;
+    /**
+     * Custom search locations for config files (overrides default patterns)
+     *
+     * When provided, this completely overrides the default search patterns
+     * generated from the name. Useful for projects with specific configuration
+     * file naming conventions or directory structures.
+     *
+     * Search order:
+     * - Files are searched in the order they appear in the array
+     * - First found file is used (cosmiconfig behavior)
+     * - Relative paths are resolved from the search directory
+     *
+     * @optional
+     * @example `['config/app.js', 'app.config.ts']`
+     * @example `['package.json', 'custom.config.js']`
+     */
+    searchPlaces?: string[];
+    /**
+     * Default configuration object (merged with discovered config)
+     *
+     * Provides fallback values that are merged with discovered configuration.
+     * Uses lodash defaultsDeep for deep merging, so nested objects are
+     * properly merged rather than replaced.
+     *
+     * Merging behavior:
+     * - Default values are used when not found in discovered config
+     * - Discovered config values override defaults
+     * - Nested objects are merged recursively
+     * - Arrays are replaced (not merged)
+     *
+     * @optional
+     * @default `{}`
+     * @example `{ port: 3000, debug: false, database: { host: 'localhost' } }`
+     */
+    defaultConfig?: Record<string, unknown>;
+    /**
+     * Custom loaders for different file types (extends cosmiconfig loaders)
+     *
+     * Allows loading of custom file formats beyond the built-in support
+     * for JSON, JavaScript, TypeScript, YAML, etc. Each loader function
+     * receives the filepath and should return the parsed configuration object.
+     *
+     * Loader requirements:
+     * - Must be synchronous (cosmiconfigSync requirement)
+     * - Should throw errors for invalid files
+     * - Should return plain objects or throw for invalid configs
+     * - File extension should include the dot (e.g., '.toml')
+     *
+     * @optional
+     * @default `{}`
+     * @example
+     * ```typescript
+     * {
+     *   '.toml': (filepath) => parseTOML(readFileSync(filepath, 'utf8')),
+     *   '.ini': (filepath) => parseINI(readFileSync(filepath, 'utf8'))
+     * }
+     * ```
+     */
+    loaders?: Record<string, (filepath: string) => unknown>;
+}
+/**
+ * Search options for configuration retrieval operations
+ *
+ * Core concept:
+ * Controls how configuration files are discovered and loaded during
+ * configuration retrieval operations, allowing fine-grained control
+ * over the search behavior.
+ *
+ * Use cases:
+ * - Load configuration from specific files
+ * - Search in specific directories
+ * - Skip file loading for testing or debugging
+ * - Control search scope for performance optimization
+ *
+ * @example Load from specific file
+ * ```typescript
+ * const config = configSearch.get({ file: 'custom.config.js' });
+ * ```
+ *
+ * @example Search in specific directory
+ * ```typescript
+ * const config = configSearch.get({ dir: '/path/to/project' });
+ * ```
+ *
+ * @example Skip file loading (return empty config)
+ * ```typescript
+ * const config = configSearch.get({ file: false });
+ * ```
+ */
+interface SearchOptions {
+    /**
+     * Specific configuration file to load (false to skip file loading)
+     *
+     * When provided as a string, loads configuration from the specified file.
+     * When set to false, skips file loading entirely and returns an empty object.
+     * When undefined, performs automatic search in the specified directory.
+     *
+     * File loading behavior:
+     * - Absolute paths are used as-is
+     * - Relative paths are resolved from the search directory
+     * - File must exist and be readable
+     * - File must contain valid configuration data
+     *
+     * @optional
+     * @example `'config/production.js'` // Load specific file
+     * @example `false` // Skip file loading
+     */
+    file?: string | false;
+    /**
+     * Directory to search in (defaults to process.cwd())
+     *
+     * Specifies the root directory for configuration file search.
+     * The search will look for configuration files in this directory
+     * and its parent directories (cosmiconfig behavior).
+     *
+     * Search behavior:
+     * - Starts from the specified directory
+     * - Searches upward through parent directories
+     * - Stops at the first found configuration file
+     * - Respects .gitignore and other ignore patterns
+     *
+     * @optional
+     * @default `process.cwd()`
+     * @example `'/path/to/project'` // Search in specific directory
+     * @example `process.cwd()` // Search from current working directory
+     */
+    dir?: string;
+}
+/**
+ * Configuration search and loading utility with caching support
+ *
+ * Core concept:
+ * Provides a robust, performant way to discover and load configuration
+ * files from various locations in a project directory structure, with
+ * intelligent caching and merging capabilities.
+ *
+ * Main features:
+ * - File discovery: Automatically finds configuration files in project directories
+ *   - Searches multiple file formats (JSON, JS, TS, YAML, etc.)
+ *   - Supports both prefixed and non-prefixed file names
+ *   - Follows cosmiconfig search patterns and conventions
+ *   - Respects .gitignore and other ignore patterns
+ *
+ * - Configuration merging: Intelligently combines default and discovered configs
+ *   - Uses lodash defaultsDeep for deep object merging
+ *   - Preserves nested object structures
+ *   - Provides fallback values for missing configurations
+ *   - Handles complex configuration hierarchies
+ *
+ * - Performance optimization: Implements caching to avoid repeated file system operations
+ *   - Caches search results for repeated access
+ *   - Reduces file system I/O in build tools and CLI applications
+ *   - Improves performance for configuration-heavy applications
+ *   - Supports cache invalidation when needed
+ *
+ * - Custom loaders: Extends cosmiconfig with custom file format support
+ *   - Add support for TOML, INI, or other custom formats
+ *   - Maintains compatibility with existing cosmiconfig loaders
+ *   - Allows project-specific configuration file formats
+ *   - Supports both synchronous and asynchronous loading patterns
+ *
+ * Design considerations:
+ * - Uses cosmiconfig for robust file discovery and loading
+ * - Implements caching to avoid repeated file system operations
+ * - Supports deep merging with lodash defaultsDeep
+ * - Maintains backward compatibility with existing config patterns
+ * - Provides flexible configuration override mechanisms
+ *
+ * Performance optimizations:
+ * - Caches search results to avoid repeated file system access
+ * - Uses synchronous operations for better performance in build tools
+ * - Implements lazy loading of configuration data
+ * - Minimizes memory usage through efficient caching strategies
+ *
+ * @example Basic usage
+ * ```typescript
+ * const configSearch = new ConfigSearch({
+ *   name: 'myapp',
+ *   defaultConfig: { port: 3000, debug: false }
+ * });
+ *
+ * // Get merged configuration
+ * const config = configSearch.config;
+ * console.log(config.port); // 3000 (from default)
+ * ```
+ *
+ * @example Advanced usage with custom search
+ * ```typescript
+ * const configSearch = new ConfigSearch({
+ *   name: 'myapp',
+ *   searchPlaces: ['myapp.config.js', 'config/myapp.js'],
+ *   defaultConfig: { environment: 'development' }
+ * });
+ *
+ * // Search in specific directory
+ * const config = configSearch.get({ dir: '/path/to/project' });
+ *
+ * // Get search locations for debugging
+ * console.log(configSearch.getSearchPlaces());
+ * ```
+ *
+ * @example Custom file format support
+ * ```typescript
+ * const configSearch = new ConfigSearch({
+ *   name: 'myapp',
+ *   loaders: {
+ *     '.toml': (filepath) => parseTOML(readFileSync(filepath, 'utf8'))
+ *   }
+ * });
+ * ```
+ */
+declare class ConfigSearch {
+    /**
+     * Base name for configuration files
+     *
+     * Used to generate default search patterns and as the cosmiconfig
+     * module name for package.json configuration discovery.
+     */
+    private name;
+    /**
+     * Search locations for configuration files
+     *
+     * Array of file patterns to search for, in priority order.
+     * Can be either default patterns generated from name or
+     * custom patterns provided in constructor options.
+     */
+    private searchPlaces;
+    /**
+     * Default configuration object
+     *
+     * Provides fallback values that are merged with discovered
+     * configuration using lodash defaultsDeep.
+     */
+    private _config;
+    /**
+     * Custom file loaders for extended format support
+     *
+     * Extends cosmiconfig's built-in loaders with custom file
+     * format support (e.g., TOML, INI, etc.).
+     */
+    private loaders?;
+    /**
+     * Cache for search results
+     *
+     * Stores the result of the last search operation to avoid
+     * repeated file system access. Simple implementation that
+     * caches the entire search result.
+     */
+    private searchCache?;
+    /**
+     * Creates a ConfigSearch instance with specified options
+     *
+     * Core concept:
+     * Initializes a configuration search utility with the specified
+     * options, setting up file discovery patterns and default values.
+     *
+     * Validation rules:
+     * - Either name or searchPlaces must be provided
+     * - Name is used to generate default search patterns if searchPlaces not provided
+     * - Default configuration provides fallback values
+     * - Custom loaders extend cosmiconfig's built-in support
+     *
+     * Initialization process:
+     * 1. Validates that either name or searchPlaces is provided
+     * 2. Sets up search patterns (custom or generated from name)
+     * 3. Initializes default configuration object
+     * 4. Stores custom loaders for extended format support
+     *
+     * @param options - Configuration search options
+     * @throws {Error} When neither name nor searchPlaces is provided
+     *
+     * @example Using name (generates default search patterns)
+     * ```typescript
+     * const search = new ConfigSearch({
+     *   name: 'myapp',
+     *   defaultConfig: { debug: true }
+     * });
+     * ```
+     *
+     * @example Using custom search places
+     * ```typescript
+     * const search = new ConfigSearch({
+     *   searchPlaces: ['custom.config.js'],
+     *   defaultConfig: { port: 8080 }
+     * });
+     * ```
+     *
+     * @example With custom loaders
+     * ```typescript
+     * const search = new ConfigSearch({
+     *   name: 'myapp',
+     *   loaders: {
+     *     '.toml': (filepath) => parseTOML(readFileSync(filepath, 'utf8'))
+     *   }
+     * });
+     * ```
+     */
+    constructor(options: ConfigSearchOptions);
+    /**
+     * Gets the effective configuration with deep merging
+     *
+     * Core concept:
+     * Retrieves the complete configuration by merging default values
+     * with discovered configuration files, providing a unified
+     * configuration object for the application.
+     *
+     * Merging strategy:
+     * - Default configuration provides base values
+     * - Discovered configuration overrides defaults
+     * - Uses lodash defaultsDeep for nested object merging
+     * - Returns a new object to prevent mutation
+     * - Handles complex nested structures properly
+     *
+     * Merging behavior:
+     * - Primitive values: Discovered values override defaults
+     * - Objects: Deep merge, preserving both default and discovered properties
+     * - Arrays: Discovered arrays replace default arrays (not merged)
+     * - Undefined values: Default values are preserved
+     * - Null values: Treated as explicit values (override defaults)
+     *
+     * Performance considerations:
+     * - Uses cached search results when available
+     * - Performs deep merge only when necessary
+     * - Returns new object to prevent external mutation
+     *
+     * @returns Merged configuration object
+     *
+     * @example Basic merging
+     * ```typescript
+     * const configSearch = new ConfigSearch({
+     *   name: 'myapp',
+     *   defaultConfig: {
+     *     server: { port: 3000, host: 'localhost' },
+     *     debug: false
+     *   }
+     * });
+     *
+     * // If myapp.config.js contains: { server: { port: 8080 }, log: true }
+     * const config = configSearch.config;
+     * // Result: { server: { port: 8080, host: 'localhost' }, debug: false, log: true }
+     * ```
+     *
+     * @example Complex nested merging
+     * ```typescript
+     * const configSearch = new ConfigSearch({
+     *   name: 'myapp',
+     *   defaultConfig: {
+     *     database: {
+     *       host: 'localhost',
+     *       options: { timeout: 5000, retries: 3 }
+     *     }
+     *   }
+     * });
+     *
+     * // If config file contains: { database: { port: 5432, options: { timeout: 10000 } } }
+     * const config = configSearch.config;
+     * // Result: {
+     * //   database: {
+     * //     host: 'localhost',
+     * //     port: 5432,
+     * //     options: { timeout: 10000, retries: 3 }
+     * //   }
+     * // }
+     * ```
+     */
+    get config(): Record<string, unknown>;
+    /**
+     * Gets the configured search locations for debugging and verification
+     *
+     * Core concept:
+     * Provides access to the search patterns used by this ConfigSearch
+     * instance, useful for debugging configuration discovery issues
+     * and understanding the search behavior.
+     *
+     * Use cases:
+     * - Debug configuration discovery issues
+     * - Verify search patterns are correct
+     * - Document expected configuration file locations
+     * - Understand search priority order
+     * - Validate custom search place configurations
+     *
+     * Search pattern information:
+     * - Returns the exact patterns used for file discovery
+     * - Patterns are in priority order (first match wins)
+     * - Includes both custom and generated patterns
+     * - Useful for troubleshooting missing configuration files
+     *
+     * @returns Array of search locations in priority order
+     *
+     * @example Basic usage
+     * ```typescript
+     * const configSearch = new ConfigSearch({ name: 'myapp' });
+     * const places = configSearch.getSearchPlaces();
+     * console.log('Searching for config in:', places);
+     * // ['package.json', 'myapp.json', 'myapp.js', 'myapp.ts', ...]
+     * ```
+     *
+     * @example Debugging missing configuration
+     * ```typescript
+     * const configSearch = new ConfigSearch({
+     *   searchPlaces: ['custom.config.js', 'config/app.js']
+     * });
+     *
+     * const places = configSearch.getSearchPlaces();
+     * console.log('Expected config files:', places);
+     * // ['custom.config.js', 'config/app.js']
+     * ```
+     */
+    getSearchPlaces(): string[];
+    /**
+     * Loads configuration from a specific location with validation
+     *
+     * Core concept:
+     * Performs targeted configuration loading from specific files or
+     * directories, with comprehensive validation and error handling.
+     *
+     * Loading process:
+     * 1. Creates cosmiconfig instance with configured options
+     * 2. Loads from specific file or searches in directory
+     * 3. Validates configuration is a plain object
+     * 4. Returns empty object for invalid configurations
+     * 5. Handles various error conditions gracefully
+     *
+     * File loading behavior:
+     * - Specific file: Loads configuration from the exact file path
+     * - Directory search: Searches for configuration files in the directory
+     * - Skip loading: Returns empty object when file is false
+     * - Validation: Ensures configuration is a valid plain object
+     *
+     * Error handling:
+     * - Throws error for invalid configuration files (string configs)
+     * - Returns empty object for missing or invalid configurations
+     * - Logs warnings for non-object configurations
+     * - Handles file system errors gracefully
+     * - Validates configuration structure and format
+     *
+     * Validation rules:
+     * - Configuration must be a plain object (not string, array, etc.)
+     * - File must exist and be readable
+     * - File must contain valid configuration data
+     * - Custom loaders must return valid objects
+     *
+     * @param options - Search options for configuration loading
+     * @returns Configuration object from specified location
+     * @throws {Error} When configuration file contains invalid data
+     *
+     * @example Load from specific file
+     * ```typescript
+     * const configSearch = new ConfigSearch({ name: 'myapp' });
+     * const config = configSearch.get({ file: 'custom.config.js' });
+     * ```
+     *
+     * @example Search in current directory
+     * ```typescript
+     * const configSearch = new ConfigSearch({ name: 'myapp' });
+     * const config = configSearch.get({ dir: process.cwd() });
+     * ```
+     *
+     * @example Skip file loading
+     * ```typescript
+     * const configSearch = new ConfigSearch({ name: 'myapp' });
+     * const config = configSearch.get({ file: false }); // Returns {}
+     * ```
+     *
+     * @example Search in specific directory
+     * ```typescript
+     * const configSearch = new ConfigSearch({ name: 'myapp' });
+     * const config = configSearch.get({ dir: '/path/to/project' });
+     * ```
+     */
+    get(options?: SearchOptions): Record<string, unknown>;
+    /**
+     * Searches for configuration with caching for performance optimization
+     *
+     * Core concept:
+     * Performs configuration file discovery with intelligent caching
+     * to optimize performance for repeated configuration access.
+     *
+     * Caching strategy:
+     * - Caches search results to avoid repeated file system operations
+     * - Cache is invalidated on each search call (simple implementation)
+     * - Improves performance for repeated configuration access
+     * - Reduces file system I/O in build tools and CLI applications
+     *
+     * Performance benefits:
+     * - Reduces file system I/O operations
+     * - Avoids repeated cosmiconfig initialization
+     * - Particularly beneficial in build tools and CLI applications
+     * - Minimizes configuration loading overhead
+     * - Improves application startup time
+     *
+     * Cache behavior:
+     * - First call: Performs full file system search
+     * - Subsequent calls: Returns cached result
+     * - Cache is shared across all method calls
+     * - Simple cache invalidation strategy
+     *
+     * Search process:
+     * 1. Check if cached result exists
+     * 2. If cached, return cached result
+     * 3. If not cached, perform file system search
+     * 4. Cache the search result
+     * 5. Return the discovered configuration
+     *
+     * @returns Cached configuration object from search
+     *
+     * @example Basic usage
+     * ```typescript
+     * const configSearch = new ConfigSearch({ name: 'myapp' });
+     *
+     * // First call performs file system search
+     * const config1 = configSearch.search();
+     *
+     * // Subsequent calls use cached result
+     * const config2 = configSearch.search(); // No file system access
+     *
+     * // Both return the same configuration object
+     * console.log(config1 === config2); // true
+     * ```
+     *
+     * @example Performance optimization
+     * ```typescript
+     * const configSearch = new ConfigSearch({ name: 'myapp' });
+     *
+     * // In a build tool or CLI application
+     * for (let i = 0; i < 100; i++) {
+     *   const config = configSearch.search(); // Only first call hits file system
+     *   // Use configuration...
+     * }
+     * ```
+     */
+    search(): Record<string, unknown>;
+}
+
+/**
+ * Enhanced script context that provides environment management and configuration utilities
+ *
+ * Core concept:
+ * Provides a comprehensive script execution environment with integrated
+ * configuration management, environment variable handling, logging,
+ * and shell command execution capabilities.
+ *
+ * Main features:
+ * - Environment management: Integrated environment variable handling
+ *   - Automatic loading of .env files with configurable order
+ *   - Type-safe environment variable access with defaults
+ *   - Support for environment-specific configurations
+ *   - Integration with fe-config environment settings
+ *
+ * - Configuration management: Unified configuration access and merging
+ *   - Script-specific configuration sections
+ *   - Deep merging with default values
+ *   - Type-safe option access with nested path support
+ *   - Configuration validation and fallback handling
+ *
+ * - Logging system: Structured logging with timestamp formatting
+ *   - Configurable verbosity levels
+ *   - Timestamp formatting with timezone support
+ *   - Logger name identification for multi-script environments
+ *   - Console output with structured formatting
+ *
+ * - Shell integration: Command execution with dry run support
+ *   - Safe command execution with error handling
+ *   - Dry run mode for testing and validation
+ *   - Integrated logging for command output
+ *   - Support for custom execution functions
+ *
+ * Design considerations:
+ * - Uses lodash merge for deep configuration merging
+ * - Supports environment file loading with configurable order
+ * - Provides type-safe option access with fallback values
+ * - Implements proper error handling for missing configurations
+ * - Maintains backward compatibility with existing interfaces
+ * - Supports both development and production environments
+ *
+ * Performance optimizations:
+ * - Lazy environment initialization
+ * - Cached configuration access
+ * - Efficient option merging
+ * - Minimal memory footprint
+ *
+ * @example Basic usage
+ * ```typescript
+ * const context = new ScriptContext('build-script', {
+ *   verbose: true,
+ *   options: { outputDir: './dist' }
+ * });
+ *
+ * // Access environment variables
+ * const apiKey = context.getEnv('API_KEY', 'default-key');
+ *
+ * // Access configuration options
+ * const outputDir = context.getOptions('outputDir', './build');
+ * ```
+ *
+ * @example Advanced configuration
+ * ```typescript
+ * const context = new ScriptContext('deploy-script', {
+ *   feConfig: {
+ *     envOrder: ['.env.prod', '.env.local', '.env'],
+ *     'deploy-script': {
+ *       target: 'production',
+ *       region: 'us-east-1'
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @example With custom components
+ * ```typescript
+ * const context = new ScriptContext('test-script', {
+ *   logger: customLogger,
+ *   shell: customShell,
+ *   dryRun: true,
+ *   options: { testMode: true }
+ * });
+ * ```
+ */
+declare class ScriptContext<Opt extends ScriptSharedInterface> implements ScriptContextInterface<Opt> {
+    readonly name: string;
+    /**
+     * Logger instance for structured logging
+     *
+     * Provides timestamp-formatted logging with configurable
+     * verbosity levels and script name identification.
+     */
+    readonly logger: LoggerInterface;
+    /**
+     * Shell interface for command execution
+     *
+     * Handles command execution with dry run support,
+     * error handling, and integrated logging.
+     */
+    readonly shell: ShellInterface;
+    /**
+     * Merged fe-configuration object
+     *
+     * Contains the complete configuration after merging
+     * default fe-config with script-specific overrides.
+     */
+    readonly feConfig: FeConfig;
+    /**
+     * Whether to run in dry run mode
+     *
+     * When true, commands are logged but not executed,
+     * useful for testing and validation.
+     */
+    readonly dryRun: boolean;
+    /**
+     * Whether to enable verbose logging
+     *
+     * Controls debug level logging output and
+     * 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
+     *
+     * Core concept:
+     * Initializes a complete script execution environment with
+     * integrated configuration, logging, and shell capabilities.
+     *
+     * Initialization process:
+     * 1. Validates script name requirement
+     * 2. Sets up logger, shell, and configuration components
+     * 3. Loads environment variables with configurable order
+     * 4. Applies default options and environment integration
+     * 5. Merges script-specific configuration with defaults
+     *
+     * Validation rules:
+     * - Script name must be provided and be a non-empty string
+     * - Options are optional and have sensible defaults
+     * - Environment loading follows configurable priority order
+     * - Configuration merging preserves type safety
+     *
+     * Component initialization:
+     * - Logger: Created with timestamp formatting and verbosity control
+     * - Shell: Set up with dry run support and integrated logging
+     * - Configuration: Merged from fe-config with script-specific overrides
+     * - Environment: Loaded from files with fallback to defaults
+     *
+     * @param name - Script identifier for logging and configuration
+     * @param opts - Optional initialization options
+     * @throws {Error} When script name is not provided or invalid
+     *
+     * @example Basic initialization
+     * ```typescript
+     * const context = new ScriptContext('build-script', {
+     *   verbose: true,
+     *   dryRun: false
+     * });
+     * ```
+     *
+     * @example With custom options
+     * ```typescript
+     * const context = new ScriptContext('deploy-script', {
+     *   feConfig: { target: 'production' },
+     *   options: { region: 'us-east-1' }
+     * });
+     * ```
+     */
+    constructor(name: string, opts?: Partial<ScriptContextInterface<Opt>>);
+    /**
+     * Environment instance for variable access and management
+     *
+     * Core concept:
+     * Provides access to environment variables loaded from
+     * configuration files with type-safe getter methods
+     * and default value support.
+     *
+     * Environment features:
+     * - Automatic file loading (.env.local, .env)
+     * - Type-safe getter methods with defaults
+     * - Configurable file loading order
+     * - Integration with fe-config environment settings
+     * - Lazy initialization for performance
+     *
+     * Loading behavior:
+     * - Files are loaded in priority order (highest first)
+     * - Missing files are silently ignored
+     * - Variables are cached after first load
+     * - Environment is shared across script instances
+     *
+     * Error handling:
+     * - Throws error if environment is not initialized
+     * - Provides clear error messages for debugging
+     * - Graceful handling of missing environment files
+     *
+     * @returns Env instance for environment variable operations
+     * @throws {Error} When environment is not properly initialized
+     *
+     * @example Basic usage
+     * ```typescript
+     * const apiKey = this.env.get('API_KEY');
+     * const port = this.env.get('PORT', '3000');
+     * ```
+     *
+     * @example With defaults
+     * ```typescript
+     * const databaseUrl = this.env.get('DATABASE_URL', 'localhost:5432');
+     * const debug = this.env.get('DEBUG', 'false');
+     * ```
+     */
+    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
+     *
+     * Core concept:
+     * Merges new options with existing configuration using
+     * lodash merge for deep object merging, preserving
+     * existing options not specified in the update.
+     *
+     * Merging strategy:
+     * - Uses lodash merge for deep object merging
+     * - Preserves existing options not specified in update
+     * - Supports nested object updates
+     * - Maintains type safety through generic constraints
+     * - Handles arrays and primitives appropriately
+     *
+     * Update behavior:
+     * - New options override existing ones
+     * - Nested objects are merged recursively
+     * - Arrays are replaced (not merged)
+     * - Primitives are replaced directly
+     * - Undefined values are ignored
+     *
+     * Type safety:
+     * - Maintains generic type constraints
+     * - Preserves option structure
+     * - Validates option types at runtime
+     * - Supports partial option updates
+     *
+     * @param options - Partial options to merge with current configuration
+     *
+     * @example Basic update
+     * ```typescript
+     * this.setOptions({ debug: true });
+     * // Merges debug: true with existing options
+     * ```
+     *
+     * @example Nested update
+     * ```typescript
+     * this.setOptions({
+     *   build: { target: 'production', minify: true }
+     * });
+     * // Merges nested build configuration
+     * ```
+     */
+    setOptions(options: Partial<Opt>): void;
+    /**
+     * Retrieves environment variable with optional default value
+     *
+     * Core concept:
+     * Provides safe access to environment variables with
+     * default value fallback, delegating to the underlying
+     * Env.get method for consistent behavior.
+     *
+     * Access features:
+     * - Safe access to environment variables
+     * - Default value fallback when variable not found
+     * - Delegates to Env.get method for consistency
+     * - Handles undefined and null values gracefully
+     * - Maintains environment variable type safety
+     *
+     * Default behavior:
+     * - Returns undefined if variable not found and no default provided
+     * - Returns default value if variable not found and default provided
+     * - Returns actual value if variable exists
+     * - Handles empty string values appropriately
+     *
+     * @param key - Environment variable name to retrieve
+     * @param defaultValue - Optional default value if variable not found
+     * @returns Environment variable value or default, undefined if not found
+     *
+     * @example Basic access
+     * ```typescript
+     * const apiKey = this.getEnv('API_KEY');
+     * // Returns API_KEY value or undefined
+     * ```
+     *
+     * @example With default
+     * ```typescript
+     * const port = this.getEnv('PORT', '3000');
+     * // Returns PORT value or '3000' if not found
+     * ```
+     *
+     * @example Boolean handling
+     * ```typescript
+     * const debug = this.getEnv('DEBUG', 'false');
+     * const isDebug = debug === 'true';
+     * ```
+     */
+    getEnv(key: string, defaultValue?: string): string | undefined;
+    /**
+     * Retrieves configuration options with nested path support
+     *
+     * Core concept:
+     * Provides safe access to configuration options using
+     * lodash get for nested path support, with type-safe
+     * return values and default value fallback.
+     *
+     * Access features:
+     * - Safe nested object access using lodash get
+     * - Type-safe return values with generic constraints
+     * - Default value support for missing keys
+     * - Full options object access when no key provided
+     * - Support for both string and array path formats
+     *
+     * Path formats:
+     * - String: 'build.target' for nested access
+     * - Array: ['build', 'target'] for explicit path
+     * - Empty: Returns full options object
+     * - Invalid: Returns default value or undefined
+     *
+     * Type safety:
+     * - Generic type parameter for return type
+     * - Type inference from default values
+     * - Runtime type validation
+     * - Consistent return type handling
+     *
+     * @param key - Optional path to specific option (string or array)
+     * @param defaultValue - Default value if option not found
+     * @returns Option value or default, full options if no key provided
+     *
+     * @example Basic access
+     * ```typescript
+     * const debug = this.getOptions('debug', false);
+     * // Returns debug option or false if not found
+     * ```
+     *
+     * @example Nested access
+     * ```typescript
+     * const target = this.getOptions('build.target', 'development');
+     * // Returns build.target or 'development' if not found
+     * ```
+     *
+     * @example Array path
+     * ```typescript
+     * const region = this.getOptions(['deploy', 'region'], 'us-east-1');
+     * // Returns deploy.region or 'us-east-1' if not found
+     * ```
+     *
+     * @example Full options
+     * ```typescript
+     * const allOptions = this.getOptions();
+     * // Returns the complete options object
+     * ```
+     */
+    getOptions<T = unknown>(key?: string | string[], defaultValue?: T): T;
+}
+
+/**
+ * Configuration for a single execution step
+ *
+ * Represents a discrete task within a script plugin with:
+ * - Human-readable label for logging
+ * - Optional enable/disable control
+ * - Async task function to execute
+ *
+ * @example
+ * ```typescript
+ * const step: StepOption<string> = {
+ *   label: 'Building project',
+ *   enabled: true,
+ *   task: async () => {
+ *     // Build logic here
+ *     return 'build completed';
+ *   }
+ * };
+ * ```
+ */
+type StepOption<T> = {
+    /** Human-readable label for the step, used in logging */
+    label: string;
+    /** Whether the step should be executed (default: true) */
+    enabled?: boolean;
+    /** Async function that performs the actual work */
+    task: () => Promise<T>;
+};
+/**
+ * Base properties for script plugin configuration
+ *
+ * Provides common configuration options that all script plugins can use:
+ * - Lifecycle execution control
+ * - Step skipping capabilities
+ * - Plugin-specific overrides
+ *
+ * @example
+ * ```typescript
+ * const props: ScriptPluginProps = {
+ *   skip: false // Enable all lifecycle methods
+ * };
+ *
+ * const props: ScriptPluginProps = {
+ *   skip: 'onBefore' // Skip only the onBefore lifecycle
+ * };
+ * ```
+ */
+interface ScriptPluginProps {
+    /**
+     * Controls whether to skip lifecycle execution
+     *
+     * Skip Options:
+     * - `true` - Skip all lifecycle methods (onBefore, onExec, onSuccess, onError)
+     * - `string` - Skip specific lifecycle method ('onBefore', 'onExec', 'onSuccess', 'onError')
+     * - `false` or `undefined` - Execute all lifecycle methods (default)
+     *
+     * @example
+     * ```typescript
+     * // Skip all lifecycle methods
+     * { skip: true }
+     *
+     * // Skip only onBefore
+     * { skip: 'onBefore' }
+     *
+     * // Skip only onError
+     * { skip: 'onError' }
+     * ```
+     */
+    skip?: boolean | string;
+}
+/**
+ * Abstract base class for script plugins that provides common functionality
+ *
+ * Core Features:
+ * - Lifecycle management (onBefore, onExec, onSuccess, onError)
+ * - Configuration management with priority merging
+ * - Step execution with logging
+ * - Plugin enable/disable control
+ * - Shell and logger access
+ *
+ * Design Considerations:
+ * - Uses generic types for type-safe context and properties
+ * - Implements ExecutorPlugin interface for integration
+ * - Supports configuration from multiple sources with priority
+ * - Provides consistent logging and error handling
+ *
+ * Configuration Priority (highest to lowest):
+ * 1. Constructor props (runtime)
+ * 2. Command line config (context.options[pluginName])
+ * 3. File config (context.getOptions(pluginName))
+ * 4. Default values
+ *
+ * @example Basic Plugin Implementation
+ * ```typescript
+ * class MyPlugin extends ScriptPlugin<MyContext, MyProps> {
+ *   async onExec(context: ExecutorContext<MyContext>): Promise<void> {
+ *     await this.step({
+ *       label: 'Processing files',
+ *       task: async () => {
+ *         // Process files logic
+ *         return 'processed';
+ *       }
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example Plugin with Custom Configuration
+ * ```typescript
+ * interface MyPluginProps extends ScriptPluginProps {
+ *   outputDir: string;
+ *   verbose: boolean;
+ * }
+ *
+ * class BuildPlugin extends ScriptPlugin<BuildContext, MyPluginProps> {
+ *   async onExec(context: ExecutorContext<BuildContext>): Promise<void> {
+ *     const outputDir = this.getConfig('outputDir', './dist');
+ *     const verbose = this.getConfig('verbose', false);
+ *
+ *     if (verbose) {
+ *       this.logger.info(`Building to ${outputDir}`);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare abstract class ScriptPlugin<Context extends ScriptContext<any>, Props extends ScriptPluginProps = ScriptPluginProps> implements ExecutorPlugin<Context> {
+    protected context: Context;
+    readonly pluginName: string;
+    protected props: Props;
+    /** Ensures only one instance of this plugin can be registered */
+    readonly onlyOne = true;
+    /**
+     * Creates a new script plugin instance
+     *
+     * Initialization Process:
+     * 1. Stores context and plugin name references
+     * 2. Merges configuration from multiple sources
+     * 3. Sets up initial configuration state
+     *
+     * @param context - Script context providing environment and configuration
+     * @param pluginName - Unique identifier for this plugin (used for config namespace)
+     * @param props - Optional runtime configuration overrides
+     *
+     * @example
+     * ```typescript
+     * // Basic initialization
+     * const plugin = new MyPlugin(context, 'my-plugin');
+     *
+     * // With runtime configuration
+     * const plugin = new MyPlugin(context, 'build-plugin', {
+     *   outputDir: './custom-dist',
+     *   skip: false
+     * });
+     * ```
+     */
+    constructor(context: Context, pluginName: string, props?: Props);
+    /**
+     * Merges configuration from multiple sources with proper priority
+     *
+     * Configuration Sources (priority order):
+     * 1. Constructor props (highest priority)
+     * 2. Command line config (context.options[pluginName])
+     * 3. File config (context.getOptions(pluginName))
+     * 4. Empty object (fallback)
+     *
+     * @param props - Runtime configuration overrides
+     * @returns Merged configuration object
+     *
+     * @example
+     * ```typescript
+     * // Get merged config from all sources
+     * const config = this.getInitialProps({
+     *   outputDir: './runtime-dist' // This will override file config
+     * });
+     * ```
+     */
+    getInitialProps(props?: Props): Props;
+    /**
+     * Logger instance for structured logging
+     *
+     * Provides access to the context logger with proper type casting
+     * for integration with the logging system.
+     *
+     * @returns LoggerInterface instance for logging operations
+     *
+     * @example
+     * ```typescript
+     * this.logger.info('Starting build process');
+     * this.logger.error('Build failed', error);
+     * this.logger.debug('Debug information', { config: this.options });
+     * ```
+     */
+    get logger(): LoggerInterface;
+    /**
+     * Shell interface for command execution
+     *
+     * Provides access to shell operations for executing commands,
+     * managing processes, and file system operations.
+     *
+     * @returns ShellInterface instance for shell operations
+     *
+     * @example
+     * ```typescript
+     * // Execute a command
+     * await this.shell.exec('npm run build');
+     *
+     * // Check if file exists
+     * const exists = await this.shell.exists('./package.json');
+     *
+     * // Read file content
+     * const content = await this.shell.readFile('./config.json');
+     * ```
+     */
+    get shell(): ShellInterface;
+    /**
+     * Current plugin configuration options
+     *
+     * Retrieves the merged configuration for this plugin from the context.
+     * This includes all configuration sources merged with proper priority.
+     *
+     * @returns Current plugin configuration object
+     *
+     * @example
+     * ```typescript
+     * // Access configuration
+     * const { outputDir, verbose } = this.options;
+     *
+     * // Use in conditional logic
+     * if (this.options.skip) {
+     *   this.logger.info('Plugin execution skipped');
+     *   return;
+     * }
+     * ```
+     */
+    get options(): Props;
+    /**
+     * Determines whether a lifecycle method should be executed
+     *
+     * Skip Logic:
+     * - Returns `false` if skip is `true` (skip all)
+     * - Returns `false` if skip matches the lifecycle name (skip specific)
+     * - Returns `true` otherwise (execute normally)
+     *
+     * @param _name - Name of the lifecycle method being checked
+     * @param _context - Executor context (unused in base implementation)
+     * @returns Whether the lifecycle method should be executed
+     *
+     * @example
+     * ```typescript
+     * // Skip all lifecycle methods
+     * const plugin = new MyPlugin(context, 'my-plugin', { skip: true });
+     * plugin.enabled('onBefore', context); // Returns false
+     *
+     * // Skip specific lifecycle method
+     * const plugin = new MyPlugin(context, 'my-plugin', { skip: 'onBefore' });
+     * plugin.enabled('onBefore', context); // Returns false
+     * plugin.enabled('onExec', context);   // Returns true
+     * ```
+     */
+    enabled(_name: string, _context: ExecutorContext<Context>): boolean;
+    /**
+     * Retrieves configuration values with nested path support
+     *
+     * Features:
+     * - Safe nested object access using lodash get
+     * - Automatic plugin namespace prefixing
+     * - Default value support for missing keys
+     * - Type-safe return values
+     *
+     * @param keys - Optional path to specific configuration (string or array)
+     * @param defaultValue - Default value if configuration not found
+     * @returns Configuration value or default, full config if no keys provided
+     *
+     * @example
+     * ```typescript
+     * // Get full plugin configuration
+     * const config = this.getConfig();
+     *
+     * // Get specific configuration value
+     * const outputDir = this.getConfig('outputDir', './dist');
+     *
+     * // Get nested configuration
+     * const buildMode = this.getConfig(['build', 'mode'], 'development');
+     *
+     * // Get with type safety
+     * const port = this.getConfig<number>('port', 3000);
+     *
+     * // Get array configuration
+     * const plugins = this.getConfig<string[]>('plugins', []);
+     * ```
+     */
+    getConfig<T>(keys?: string | string[], defaultValue?: T): T;
+    /**
+     * Updates plugin configuration with deep merging
+     *
+     * Merging Strategy:
+     * - Uses lodash merge for deep object merging
+     * - Preserves existing configuration not specified in update
+     * - Updates configuration in the plugin's namespace
+     * - Maintains type safety through generic constraints
+     *
+     * @param config - Partial configuration to merge with current settings
+     *
+     * @example
+     * ```typescript
+     * // Update single configuration
+     * this.setConfig({ outputDir: '/new/path' });
+     *
+     * // Update multiple configurations
+     * this.setConfig({
+     *   verbose: true,
+     *   buildMode: 'production'
+     * });
+     *
+     * // Update nested configuration
+     * this.setConfig({
+     *   build: {
+     *     minify: true,
+     *     sourcemap: false
+     *   }
+     * });
+     * ```
+     */
+    setConfig(config: Partial<Props>): void;
+    /**
+     * Lifecycle method called before script execution
+     *
+     * Override this method to perform setup tasks such as:
+     * - Environment validation
+     * - Configuration verification
+     * - Resource preparation
+     * - Pre-execution checks
+     *
+     * @param _context - Executor context containing execution state
+     *
+     * @example
+     * ```typescript
+     * async onBefore(context: ExecutorContext<MyContext>): Promise<void> {
+     *   // Validate required environment variables
+     *   const apiKey = this.context.getEnv('API_KEY');
+     *   if (!apiKey) {
+     *     throw new Error('API_KEY environment variable is required');
+     *   }
+     *
+     *   // Check if output directory exists
+     *   const outputDir = this.getConfig('outputDir', './dist');
+     *   if (!(await this.shell.exists(outputDir))) {
+     *     await this.shell.mkdir(outputDir);
+     *   }
+     * }
+     * ```
+     */
+    onBefore?(_context: ExecutorContext<Context>): void | Promise<void>;
+    /**
+     * Lifecycle method called during script execution
+     *
+     * Override this method to implement the main plugin logic:
+     * - Core functionality execution
+     * - Business logic implementation
+     * - Task orchestration
+     * - Process management
+     *
+     * @param _context - Executor context containing execution state
+     *
+     * @example
+     * ```typescript
+     * async onExec(context: ExecutorContext<MyContext>): Promise<void> {
+     *   await this.step({
+     *     label: 'Building project',
+     *     task: async () => {
+     *       await this.shell.exec('npm run build');
+     *       return 'build completed';
+     *     }
+     *   });
+     *
+     *   await this.step({
+     *     label: 'Running tests',
+     *     task: async () => {
+     *       await this.shell.exec('npm test');
+     *       return 'tests passed';
+     *     }
+     *   });
+     * }
+     * ```
+     */
+    onExec?(_context: ExecutorContext<Context>): void | Promise<void>;
+    /**
+     * Lifecycle method called after successful script execution
+     *
+     * Override this method to perform cleanup tasks such as:
+     * - Resource cleanup
+     * - Success notifications
+     * - Result processing
+     * - Post-execution reporting
+     *
+     * @param _context - Executor context containing execution state
+     *
+     * @example
+     * ```typescript
+     * async onSuccess(context: ExecutorContext<MyContext>): Promise<void> {
+     *   // Send success notification
+     *   await this.sendNotification('Build completed successfully');
+     *
+     *   // Generate success report
+     *   await this.generateReport({
+     *     status: 'success',
+     *     timestamp: new Date(),
+     *     duration: context.duration
+     *   });
+     *
+     *   // Clean up temporary files
+     *   await this.shell.rmdir('./temp');
+     * }
+     * ```
+     */
+    onSuccess?(_context: ExecutorContext<Context>): void | Promise<void>;
+    /**
+     * Lifecycle method called when script execution fails
+     *
+     * Override this method to handle errors such as:
+     * - Error logging and reporting
+     * - Resource cleanup on failure
+     * - Error notifications
+     * - Failure recovery attempts
+     *
+     * @param _context - Executor context containing execution state
+     *
+     * @example
+     * ```typescript
+     * async onError(context: ExecutorContext<MyContext>): Promise<void> {
+     *   // Log detailed error information
+     *   this.logger.error('Script execution failed', {
+     *     error: context.error,
+     *     duration: context.duration,
+     *     config: this.options
+     *   });
+     *
+     *   // Send error notification
+     *   await this.sendNotification('Build failed', {
+     *     error: context.error.message
+     *   });
+     *
+     *   // Clean up partial results
+     *   await this.shell.rmdir('./partial-build');
+     * }
+     * ```
+     */
+    onError?(_context: ExecutorContext<Context>): void | Promise<void>;
+    /**
+     * Executes a step with structured logging and error handling
+     *
+     * Features:
+     * - Automatic step labeling in logs
+     * - Structured success/failure logging
+     * - Error propagation with context
+     * - Visual separation in log output
+     *
+     * Step Execution Flow:
+     * 1. Log step start with label
+     * 2. Execute task function
+     * 3. Log success or error
+     * 4. Return task result or throw error
+     *
+     * @param options - Step configuration object
+     * @param {string} options.label - Human-readable label for the step
+     * @param {() => Promise<T>} options.task - Async function that performs the step work
+     * @param {boolean} [options.enabled] - Whether the step should be executed (default: true)
+     * @returns The result of the task execution
+     *
+     * @throws {Error} When the task function throws an error
+     *
+     * @example
+     * ```typescript
+     * // Basic step execution
+     * const result = await this.step({
+     *   label: 'Installing dependencies',
+     *   task: async () => {
+     *     await this.shell.exec('npm install');
+     *     return 'dependencies installed';
+     *   }
+     * });
+     *
+     * // Step with conditional logic
+     * await this.step({
+     *   label: 'Running tests',
+     *   enabled: this.getConfig('runTests', true),
+     *   task: async () => {
+     *     await this.shell.exec('npm test');
+     *     return 'tests passed';
+     *   }
+     * });
+     *
+     * // Step with complex logic
+     * await this.step({
+     *   label: 'Building project',
+     *   task: async () => {
+     *     const buildMode = this.getConfig('buildMode', 'development');
+     *     const command = `npm run build:${buildMode}`;
+     *     await this.shell.exec(command);
+     *     return {
+     *       mode: buildMode,
+     *       outputDir: this.getConfig('outputDir', './dist')
+     *     };
+     *   }
+     * });
+     * ```
+     */
+    step<T>(options: StepOption<T>): Promise<T>;
+}
+
+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 };