feat(): adjust utils documentation

Author: Karnaukhov-kh

packages/shared/utils/ai/API.md

@@ -9,6 +9,7 @@ import {
   executeProcess,
   findFilesWithPattern,
   resolveFileCached,
+  loadDefaultExport,
   objectToCliArgs,
 } from '@push-based/utils';
 
@@ -29,6 +30,9 @@ const files = await findFilesWithPattern('./src', 'Component');
 // Resolve file with caching
 const content = await resolveFileCached('./config.json');
 
+// Load ES module default export
+const config = await loadDefaultExport('./config.mjs');
+
 // String utilities
 const slug = slugify('Hello World!'); // → 'hello-world'
 const args = objectToCliArgs({ name: 'test', verbose: true }); // → ['--name="test"', '--verbose']
@@ -38,6 +42,7 @@ const args = objectToCliArgs({ name: 'test', verbose: true }); // → ['--name="
 
 - **Process Execution**: Robust child process management with observers and error handling
 - **File Operations**: Cached file resolution and pattern-based file searching
+- **ES Module Loading**: Dynamic import of ES modules with default export extraction
 - **String Utilities**: Text transformation, slugification, and pluralization
 - **CLI Utilities**: Object-to-arguments conversion and command formatting
 - **Logging**: Environment-based verbose logging control
@@ -47,6 +52,7 @@ const args = objectToCliArgs({ name: 'test', verbose: true }); // → ['--name="
 
 - **Build Tools**: Execute CLI commands with real-time output monitoring
 - **File Processing**: Search and resolve files efficiently with caching
+- **Module Loading**: Dynamic import of configuration files and plugins
 - **Code Generation**: Transform data into CLI arguments and formatted strings
 - **Development Tools**: Create development utilities with proper logging
 - **Static Analysis**: Find and process files based on content patterns

packages/shared/utils/ai/EXAMPLES.md

@@ -433,6 +433,48 @@ if (largeFiles.length > 0) {
 
 ---
 
+## 7 — ES Module loading and dynamic imports
+
+> Load ES modules dynamically and extract default exports safely.
+
+```ts
+import { loadDefaultExport } from '@push-based/utils';
+
+// Load configuration from ES module
+const config = await loadDefaultExport('./config/app.config.mjs');
+console.log(`API Port: ${config.port}`);
+
+// Load with type safety
+interface AppData {
+  version: string;
+  features: string[];
+}
+
+const appData = await loadDefaultExport<AppData>('./data/app.mjs');
+console.log(`App version: ${appData.version}`);
+console.log(`Features: ${appData.features.join(', ')}`);
+
+// Handle loading errors gracefully
+try {
+  const plugin = await loadDefaultExport('./plugins/optional.mjs');
+  console.log('✅ Plugin loaded');
+} catch (error) {
+  if (error.message.includes('No default export found')) {
+    console.warn('⚠️  Module missing default export');
+  } else {
+    console.warn('⚠️  Plugin not found, continuing without it');
+  }
+}
+
+// Output:
+// → API Port: 3000
+// → App version: 1.2.0  
+// → Features: auth, logging, metrics
+// → ⚠️  Plugin not found, continuing without it
+```
+
+---
+
 
 
 These examples demonstrate the comprehensive capabilities of the `@push-based/utils` library for process execution, file operations, string manipulation, and development tooling in Node.js applications.

packages/shared/utils/ai/FUNCTIONS.md

@@ -20,6 +20,7 @@
 | `getLineHits`          | function | Get all pattern matches within a text line                     |
 | `isExcludedDirectory`  | function | Check if a directory should be excluded from searches          |
 | `isVerbose`            | function | Check if verbose logging is enabled via environment variable   |
+| `loadDefaultExport`    | function | Dynamically import ES modules and extract default export       |
 | `objectToCliArgs`      | function | Convert object properties to command-line arguments            |
 | `resolveFile`          | function | Read file content directly without caching                     |
 | `resolveFileCached`    | function | Read file content with caching for performance                 |
@@ -251,6 +252,25 @@ Checks if verbose logging is enabled via the `NG_MCP_VERBOSE` environment variab
 
 **Returns:** `true` if verbose logging is enabled
 
+### `loadDefaultExport<T = unknown>(filePath: string): Promise<T>`
+
+Dynamically imports an ES Module and extracts the default export. Uses proper file URL conversion for cross-platform compatibility.
+
+**Parameters:**
+
+- `filePath` - Absolute path to the ES module file to import
+
+**Returns:** Promise resolving to the default export from the module
+
+**Throws:** Error if the module cannot be loaded or has no default export
+
+**Example:**
+
+```typescript
+const config = await loadDefaultExport('/path/to/config.js');
+const data = await loadDefaultExport<MyDataType>('/path/to/data.mjs');
+```
+
 ## Constants
 
 ### `fileResolverCache: Map<string, Promise<string>>`