indusagi-coding-agent 0.1.28 → 0.1.30

package/docs/UTILS-MODULE-OVERVIEW.md

@@ -1,1480 +0,0 @@
-# Utils Module Overview
-
-**Version**: 1.0.0  
-**Last Updated**: February 2024  
-**Status**: Production Ready
-
----
-
-## Table of Contents
-
-1. [Introduction](#introduction)
-2. [Module Architecture](#module-architecture)
-3. [Complete Utilities Reference](#complete-utilities-reference)
-4. [Utility Categories](#utility-categories)
-5. [Quick Reference Table](#quick-reference-table)
-6. [Common Patterns](#common-patterns)
-7. [Error Handling Best Practices](#error-handling-best-practices)
-8. [Performance Guidelines](#performance-guidelines)
-9. [Security Considerations](#security-considerations)
-10. [Quick Start Examples](#quick-start-examples)
-11. [Troubleshooting Guide](#troubleshooting-guide)
-
----
-
-## Introduction
-
-The **Utils Module** (`src/utils/`) provides a comprehensive collection of 24 specialized utilities designed to handle common operations in the indusagi coding agent. These utilities are organized into logical categories and follow consistent patterns for error handling, type safety, and performance optimization.
-
-### Key Features
-
-- **Modular Design**: Each utility is self-contained and independently importable
-- **Type Safety**: Full TypeScript support with proper type definitions
-- **Error Handling**: Comprehensive error handling with recovery suggestions
-- **Performance**: Optimized algorithms with documented complexity
-- **Security**: Built-in protection against common vulnerabilities
-- **Testing**: Extensive test coverage with edge cases
-
-### Module Statistics
-
-```
-Total Utilities: 24
-Categories: 6
-Lines of Code: ~15,000+
-Test Cases: 200+
-Test Coverage: 85%+
-```
-
----
-
-## Module Architecture
-
-### File Structure
-
-```
-src/utils/
-├── __tests__/                    # Comprehensive test suite
-│   ├── array.test.ts
-│   ├── changelog.test.ts
-│   ├── clipboard.test.ts
-│   ├── error-handler.test.ts
-│   └── ... (more test files)
-│
-├── array.ts                      # Array manipulation (25+ functions)
-├── changelog.ts                  # Changelog generation & parsing
-├── clipboard.ts                  # Clipboard operations
-├── clipboard-image.ts            # Image clipboard handling
-├── color-formatter.ts            # Color utilities
-├── data-transformer.ts           # Data transformation pipeline
-├── date-formatter.ts             # Date/time formatting
-├── error-handler.ts              # Error handling & recovery
-├── file-operations.ts            # File I/O with safety
-├── frontmatter.ts                # YAML frontmatter parsing
-├── git.ts                        # Git operations wrapper
-├── image-convert.ts              # Image format conversion
-├── image-resize.ts               # Image resizing & optimization
-├── json-formatter.ts             # JSON processing utilities
-├── logger.ts                     # Structured logging
-├── markdown-formatter.ts         # Markdown processing
-├── mime.ts                       # MIME type detection
-├── path-validator.ts             # Path validation & resolution
-├── photon.ts                     # Image processing via Photon
-├── shell.ts                      # Safe shell command execution
-├── sleep.ts                      # Async delays & timing
-├── string-formatter.ts           # String manipulation
-├── tools-manager.ts              # Tool registry management
-└── type-guards.ts                # Runtime type checking
-```
-
----
-
-## Complete Utilities Reference
-
-### 1. Array Utilities (`array.ts`)
-
-**Purpose**: Advanced array manipulation with functional programming patterns
-
-**Key Functions** (25+):
-- `groupBy()` - Group items by key function
-- `unique()` - Remove duplicates while preserving order
-- `flatten()` - Flatten nested arrays to depth
-- `chunk()` - Split array into chunks
-- `sortBy()` - Custom sorting
-- `partition()` - Split into two arrays by predicate
-- `zip()` / `unzip()` - Array zipping operations
-- `take()` / `takeLast()` - Get first/last n items
-- `drop()` / `dropLast()` - Remove first/last n items
-- `union()` / `intersection()` / `difference()` - Set operations
-- `minBy()` / `maxBy()` - Find extremes
-- `sum()` / `average()` - Numeric aggregations
-- `shuffle()` / `sample()` / `sampleSize()` - Randomization
-
-**Performance**: O(n) to O(n log n) depending on operation
-
-**Example Usage**:
-```typescript
-const users = [{ role: 'admin' }, { role: 'user' }, { role: 'admin' }];
-const grouped = groupBy(users, u => u.role);
-const unique = unique([1, 2, 2, 3, 3, 3]);
-const chunked = chunk([1,2,3,4,5], 2); // [[1,2], [3,4], [5]]
-```
-
----
-
-### 2. Error Handler (`error-handler.ts`)
-
-**Purpose**: Robust error handling with user-friendly messages and recovery suggestions
-
-**Key Functions** (8):
-- `categorizeError()` - Classify error by type
-- `extractStackTrace()` - Get formatted stack trace
-- `sanitizeErrorMessage()` - Remove sensitive information
-- `extractErrorMessage()` - Unified message extraction
-- `getRecoverySuggestions()` - Get user-facing recovery steps
-- `formatErrorForUser()` - Main error formatting function
-- `handlePromise()` - Promise error wrapping (Go-style)
-- `retryWithBackoff()` - Exponential backoff retry logic
-
-**Error Codes**:
-```
-E001 - Unknown error
-E002 - Validation error
-E003 - Configuration error
-E004 - Permission denied
-E005 - Resource not found
-E006 - Timeout error
-E007 - Network error
-E008 - Parse error
-EACCES - Permission denied (POSIX)
-ENOENT - File not found (POSIX)
-ETIMEDOUT - Connection timeout (POSIX)
-ECONNREFUSED - Connection refused (POSIX)
-```
-
-**Example Usage**:
-```typescript
-try {
-  await riskyOperation();
-} catch (error) {
-  const formatted = formatErrorForUser(error, { code: 'ENOENT' });
-  console.log(formatted.message);
-  console.log(formatted.suggestions);
-}
-```
-
----
-
-### 3. Logger (`logger.ts`)
-
-**Purpose**: Structured logging with levels, context, and performance tracking
-
-**Key Functions** (8):
-- `createLogger()` - Create named logger instance
-- `setLogLevel()` / `getLogLevel()` - Control logging verbosity
-- `createScopedLogger()` - Logger with automatic context
-- `logGroup()` - Grouped log output
-- `logBatch()` - Batch log entries
-- `createPerformanceMonitor()` - Track function performance
-- `clearLoggers()` - Reset all loggers
-- `getActiveLoggers()` - List active loggers
-
-**Log Levels** (in order):
-- DEBUG (0) - Detailed diagnostic info
-- INFO (1) - General information
-- WARN (2) - Warning messages
-- ERROR (3) - Error messages
-- FATAL (4) - Critical errors
-
-**Example Usage**:
-```typescript
-const log = createLogger('Database');
-setLogLevel('debug');
-log.info('Connected', { connection: 'postgres' });
-
-const timer = log.time('query');
-await db.query('SELECT *');
-timer(); // Logs duration
-
-const scoped = createScopedLogger(log, 'request-123', { userId: 42 });
-scoped.info('Processing'); // Includes userId
-```
-
----
-
-### 4. File Operations (`file-operations.ts`)
-
-**Purpose**: Safe file and directory operations with error recovery
-
-**Key Functions** (15+):
-- `readFile()` / `readFileBuffer()` - Safe file reading
-- `writeFile()` / `appendFile()` - Safe file writing
-- `exists()` - Check existence
-- `deleteFile()` - Delete with optional backup
-- `getSize()` / `getModTime()` - File metadata
-- `isDirectory()` / `isFile()` - Type checking
-- `listFiles()` - Directory listing with filtering
-- `getMetadata()` - Comprehensive metadata
-- `readLinesSync()` - Line-by-line reading
-- `copyFile()` - Copy with verification
-- `batchProcessFiles()` - Process multiple files
-- `ensureDir()` - Ensure directory exists
-- `glob()` - Pattern matching
-
-**Example Usage**:
-```typescript
-const content = await readFile('./data.json');
-await writeFile('./backup.json', content, { createDirs: true });
-const files = await listFiles('./src', { extension: '.ts', recursive: true });
-const meta = await getMetadata('./config.json', true); // Include hash
-```
-
----
-
-### 5. String Formatter (`string-formatter.ts`)
-
-**Purpose**: String manipulation and formatting utilities
-
-**Key Functions**:
-- `capitalize()` - Capitalize first letter
-- `toCamelCase()` / `toSnakeCase()` / `toKebabCase()` - Case conversion
-- `truncate()` - Truncate with ellipsis
-- `padStart()` / `padEnd()` - Padding utilities
-- `repeat()` - Repeat string
-- `reverse()` - Reverse string
-- `escape()` / `unescape()` - HTML/special char handling
-- `slugify()` - URL-safe slug generation
-
-**Example Usage**:
-```typescript
-capitalize('hello'); // 'Hello'
-toCamelCase('hello-world'); // 'helloWorld'
-truncate('Long text here', 10); // 'Long te...'
-```
-
----
-
-### 6. Date Formatter (`date-formatter.ts`)
-
-**Purpose**: Date and time formatting utilities
-
-**Key Functions**:
-- `formatDate()` - Format date with patterns
-- `formatTime()` - Format time strings
-- `parseDate()` - Parse date strings
-- `addDays()` / `addHours()` / `addMinutes()` - Date arithmetic
-- `getDayOfWeek()` - Get day name
-- `isWeekend()` / `isWorkday()` - Day classification
-- `getWeekNumber()` - ISO week number
-- `getDuration()` - Time duration calculation
-
-**Example Usage**:
-```typescript
-formatDate(new Date(), 'yyyy-MM-dd HH:mm:ss');
-addDays(new Date(), 7);
-const duration = getDuration(start, end); // { days: 1, hours: 2, minutes: 30 }
-```
-
----
-
-### 7. JSON Formatter (`json-formatter.ts`)
-
-**Purpose**: JSON processing, validation, and formatting
-
-**Key Functions**:
-- `parseJSON()` - Safe JSON parsing
-- `stringifyJSON()` - Safe JSON stringification
-- `formatJSON()` - Pretty print with indentation
-- `minifyJSON()` - Remove whitespace
-- `validateJSON()` - Validate JSON structure
-- `mergeJSON()` - Deep merge JSON objects
-- `flattenJSON()` - Flatten nested structures
-- `unflattenJSON()` - Restore nested structure
-
-**Example Usage**:
-```typescript
-const [data, error] = parseJSON('{"name":"John"}');
-const pretty = formatJSON(obj, 2);
-const merged = mergeJSON(obj1, obj2);
-const flat = flattenJSON({ a: { b: { c: 1 } } }); // { 'a.b.c': 1 }
-```
-
----
-
-### 8. Color Formatter (`color-formatter.ts`)
-
-**Purpose**: Color processing and format conversion
-
-**Key Functions**:
-- `hexToRgb()` / `rgbToHex()` - Color conversion
-- `rgbToHsl()` / `hslToRgb()` - HSL conversion
-- `lighten()` / `darken()` - Color brightness
-- `saturate()` / `desaturate()` - Color saturation
-- `invertColor()` - Color inversion
-- `getContrast()` - WCAG contrast ratio
-- `isValidColor()` - Color validation
-- `toHex()` / `toRgb()` / `toHsl()` - Unified conversion
-
-**Example Usage**:
-```typescript
-hexToRgb('#FF0000'); // { r: 255, g: 0, b: 0 }
-lighten('#FF0000', 0.2); // Lighter red
-getContrast('#FFFFFF', '#000000'); // 21 (WCAG AAA)
-```
-
----
-
-### 9. Markdown Formatter (`markdown-formatter.ts`)
-
-**Purpose**: Markdown parsing, generation, and processing
-
-**Key Functions**:
-- `parseMarkdown()` - Parse markdown to AST
-- `generateMarkdown()` - Generate markdown from AST
-- `extractHeadings()` - Extract heading hierarchy
-- `tableOfContents()` - Generate TOC
-- `linkValidator()` - Validate markdown links
-- `sanitizeMarkdown()` - Remove dangerous content
-- `markdownToHtml()` - Convert to HTML
-- `htmlToMarkdown()` - Convert from HTML
-
-**Example Usage**:
-```typescript
-const toc = tableOfContents(markdown);
-const headings = extractHeadings(markdown);
-const html = markdownToHtml(markdown);
-```
-
----
-
-### 10. Image Operations
-
-#### Image Convert (`image-convert.ts`)
-- `convertFormat()` - Convert image formats (PNG, JPG, WEBP)
-- `detectFormat()` - Detect image format
-- `optimizeImage()` - Reduce file size
-- `getImageDimensions()` - Get width/height
-
-#### Image Resize (`image-resize.ts`)
-- `resizeImage()` - Resize with options
-- `fitImage()` - Fit to bounds
-- `cropImage()` - Crop region
-- `rotateImage()` - Rotate degrees
-- `thumbnailImage()` - Generate thumbnail
-
-#### Clipboard Image (`clipboard-image.ts`)
-- `copyImageToClipboard()` - Copy image from path
-- `pasteImageFromClipboard()` - Get image from clipboard
-- `captureScreenshot()` - Capture screen region
-- `saveClipboardImage()` - Save clipboard image to file
-
-#### Photon (`photon.ts`)
-- `applyFilter()` - Apply image filters
-- `adjustBrightness()` - Brightness control
-- `adjustContrast()` - Contrast control
-- `applyBlur()` - Gaussian blur
-- `sharpenImage()` - Sharpening effect
-
-**Example Usage**:
-```typescript
-const resized = await resizeImage('./image.jpg', { width: 800, height: 600 });
-const thumbnail = await thumbnailImage('./large.jpg', 200);
-const converted = await convertFormat('./image.png', 'webp', { quality: 0.8 });
-```
-
----
-
-### 11. Git Operations (`git.ts`)
-
-**Purpose**: Git command wrapper and repository operations
-
-**Key Functions**:
-- `getGitStatus()` - Get repository status
-- `getCommitHistory()` - Retrieve commit log
-- `getCurrentBranch()` - Get active branch
-- `getRemotes()` - List remotes
-- `getGitRoot()` - Find repository root
-- `getAuthorInfo()` - Get author configuration
-- `checkIsRepository()` - Verify git repo
-- `getGitVersion()` - Get git version
-
-**Example Usage**:
-```typescript
-const status = await getGitStatus();
-const history = await getCommitHistory(10); // Last 10 commits
-const branch = await getCurrentBranch();
-```
-
----
-
-### 12. Clipboard Operations (`clipboard.ts`)
-
-**Purpose**: Read/write to system clipboard
-
-**Key Functions**:
-- `readClipboard()` - Read clipboard text
-- `writeClipboard()` - Write clipboard text
-- `clearClipboard()` - Clear clipboard
-- `getClipboardHistory()` - Clipboard history
-- `isClipboardAvailable()` - Check availability
-
-**Example Usage**:
-```typescript
-const text = await readClipboard();
-await writeClipboard('Copied text');
-```
-
----
-
-### 13. Changelog (`changelog.ts`)
-
-**Purpose**: Changelog parsing and generation
-
-**Key Functions**:
-- `parseChangelog()` - Parse CHANGELOG.md
-- `generateChangelog()` - Create from commits
-- `formatVersion()` - Format version entries
-- `addEntry()` - Add changelog entry
-- `getLatestVersion()` - Get latest version
-- `getVersionHistory()` - All versions
-
-**Example Usage**:
-```typescript
-const changelog = await parseChangelog();
-const latest = getLatestVersion(changelog);
-const entry = addEntry(changelog, '1.2.0', { features: ['New feature'] });
-```
-
----
-
-### 14. Data Transformer (`data-transformer.ts`)
-
-**Purpose**: Data transformation and pipeline utilities
-
-**Key Functions**:
-- `transform()` - Transform data through pipeline
-- `map()` - Transform each item
-- `filter()` - Filter items
-- `reduce()` - Reduce to single value
-- `batch()` - Process in batches
-- `parallel()` - Parallel processing
-- `chain()` - Chain transformations
-
-**Example Usage**:
-```typescript
-const result = await transform(data)
-  .pipe(filter(x => x.active))
-  .pipe(map(x => x.value))
-  .pipe(reduce((a, b) => a + b, 0))
-  .execute();
-```
-
----
-
-### 15. YAML Frontmatter (`frontmatter.ts`)
-
-**Purpose**: Parse and manipulate YAML frontmatter in files
-
-**Key Functions**:
-- `parseFrontmatter()` - Extract frontmatter and content
-- `stringifyFrontmatter()` - Create file with frontmatter
-- `updateFrontmatter()` - Update frontmatter properties
-- `getFrontmatterValue()` - Get specific value
-- `validateFrontmatter()` - Validate structure
-
-**Example Usage**:
-```typescript
-const { frontmatter, content } = parseFrontmatter(fileContent);
-const updated = updateFrontmatter(fileContent, { title: 'New Title' });
-```
-
----
-
-### 16. MIME Type Detection (`mime.ts`)
-
-**Purpose**: MIME type detection and mapping
-
-**Key Functions**:
-- `getMimeType()` - Get MIME type from extension
-- `getExtension()` - Get extension from MIME type
-- `isMimeType()` - Check MIME type
-- `getCategory()` - Categorize MIME type
-- `isText()` / `isImage()` / `isVideo()` - Type checking
-
-**Example Usage**:
-```typescript
-getMimeType('.jpg'); // 'image/jpeg'
-getExtension('text/plain'); // '.txt'
-isImage('image/png'); // true
-```
-
----
-
-### 17. Path Validator (`path-validator.ts`)
-
-**Purpose**: Path validation and resolution utilities
-
-**Key Functions**:
-- `validatePath()` - Validate path format
-- `resolvePath()` - Resolve relative/absolute paths
-- `normalizePath()` - Normalize path separators
-- `isAbsolute()` / `isRelative()` - Path type checking
-- `joinPaths()` - Join path segments
-- `getPathParts()` - Extract path components
-- `isSafePath()` - Check security
-
-**Example Usage**:
-```typescript
-const safe = validatePath('./src/utils');
-const absolute = resolvePath('../config.json');
-const joined = joinPaths('src', 'utils', 'array.ts');
-```
-
----
-
-### 18. Shell Operations (`shell.ts`)
-
-**Purpose**: Safe shell command execution
-
-**Key Functions**:
-- `executeCommand()` - Run shell commands
-- `executeCommandAsync()` - Async command execution
-- `executeWithPipe()` - Pipe commands
-- `checkCommand()` - Check command availability
-- `shellEscape()` - Escape shell arguments
-
-**Example Usage**:
-```typescript
-const result = await executeCommand('npm --version');
-const output = result.stdout;
-
-const piped = await executeWithPipe('cat file.txt | grep pattern');
-```
-
----
-
-### 19. Sleep Utilities (`sleep.ts`)
-
-**Purpose**: Timing and delay utilities
-
-**Key Functions**:
-- `sleep()` - Simple delay
-- `delay()` - Delay with callback
-- `timeout()` - Timeout wrapper
-- `debounce()` - Debounce function calls
-- `throttle()` - Throttle function calls
-
-**Example Usage**:
-```typescript
-await sleep(1000); // Wait 1 second
-const debounced = debounce(handleChange, 300);
-const throttled = throttle(handleScroll, 100);
-```
-
----
-
-### 20. Type Guards (`type-guards.ts`)
-
-**Purpose**: Runtime type checking utilities
-
-**Key Functions**:
-- `isString()` / `isNumber()` / `isBoolean()` - Primitive checks
-- `isArray()` / `isObject()` / `isFunction()` - Type checks
-- `isNull()` / `isUndefined()` / `isDefined()` - Null checks
-- `isDate()` / `isRegExp()` / `isPromise()` - Special types
-- `isPlainObject()` - Check plain object
-- `hasProperty()` / `hasMethod()` - Property checks
-- `assertType()` - Throw if type mismatch
-
-**Example Usage**:
-```typescript
-if (isArray(value)) { /* ... */ }
-if (isDefined(value) && isString(value)) { /* ... */ }
-assertType(value, 'string');
-```
-
----
-
-### 21. Tools Manager (`tools-manager.ts`)
-
-**Purpose**: Tool registry and lifecycle management
-
-**Key Functions**:
-- `registerTool()` - Register tool
-- `getTool()` - Retrieve tool
-- `listTools()` - List all tools
-- `enableTool()` / `disableTool()` - Control tools
-- `executeTool()` - Run tool
-- `validateTool()` - Validate tool
-
-**Example Usage**:
-```typescript
-registerTool('logger', loggerTool);
-const tool = getTool('logger');
-const result = await executeTool('logger', { level: 'info' });
-```
-
----
-
-## Utility Categories
-
-### Data Processing (9)
-1. Array - Array manipulation
-2. String Formatter - String operations
-3. Color Formatter - Color processing
-4. JSON Formatter - JSON processing
-5. Data Transformer - Transformation pipeline
-6. Frontmatter - YAML handling
-7. Markdown Formatter - Markdown processing
-8. Date Formatter - Date/time operations
-9. MIME - MIME type detection
-
-### File & System (7)
-1. File Operations - File I/O
-2. Path Validator - Path handling
-3. Shell - Command execution
-4. Git - Git operations
-5. Clipboard - Clipboard access
-6. Changelog - Changelog management
-7. Sleep - Timing utilities
-
-### Image Processing (5)
-1. Image Convert - Format conversion
-2. Image Resize - Resizing operations
-3. Image Photon - Filters & effects
-4. Clipboard Image - Image clipboard
-5. Color Formatter - Color utilities
-
-### Infrastructure (3)
-1. Logger - Structured logging
-2. Error Handler - Error handling
-3. Type Guards - Type checking
-
-### Tools & Registry (1)
-1. Tools Manager - Tool management
-
----
-
-## Quick Reference Table
-
-| Utility | Purpose | Key Functions | Files | Lines |
-|---------|---------|---------------|-------|-------|
-| array.ts | Array manipulation | groupBy, unique, flatten, chunk, sort | 25+ | 600+ |
-| error-handler.ts | Error handling | formatError, sanitize, retry | 8 | 500+ |
-| logger.ts | Structured logging | createLogger, setLevel, time | 8 | 450+ |
-| file-operations.ts | File I/O | read, write, list, delete | 15+ | 550+ |
-| string-formatter.ts | String utils | capitalize, case, truncate | 12+ | 400+ |
-| date-formatter.ts | Date utils | format, parse, add, duration | 10+ | 350+ |
-| json-formatter.ts | JSON utils | parse, stringify, merge, flatten | 8 | 400+ |
-| color-formatter.ts | Color utils | convert, lighten, contrast | 12+ | 400+ |
-| markdown-formatter.ts | Markdown | parse, generate, TOC, sanitize | 10+ | 450+ |
-| image-convert.ts | Image convert | convert, detect, optimize | 6 | 300+ |
-| image-resize.ts | Image resize | resize, crop, rotate | 8 | 350+ |
-| clipboard-image.ts | Image clipboard | copy, paste, capture | 6 | 300+ |
-| photon.ts | Image filters | filters, brightness, contrast, blur | 12+ | 400+ |
-| git.ts | Git operations | status, history, branch, author | 10+ | 400+ |
-| clipboard.ts | Clipboard | read, write, clear, history | 5 | 250+ |
-| changelog.ts | Changelog | parse, generate, version | 8 | 350+ |
-| data-transformer.ts | Transform pipeline | transform, map, filter, reduce | 8 | 350+ |
-| frontmatter.ts | YAML frontmatter | parse, stringify, update | 6 | 300+ |
-| mime.ts | MIME detection | getMimeType, getExtension | 6 | 250+ |
-| path-validator.ts | Path utils | validate, resolve, normalize | 10+ | 350+ |
-| shell.ts | Shell execution | execute, async, pipe, escape | 6 | 300+ |
-| sleep.ts | Timing | sleep, delay, debounce, throttle | 6 | 250+ |
-| type-guards.ts | Type checking | isString, isArray, assertType | 20+ | 350+ |
-| tools-manager.ts | Tool registry | register, get, execute, validate | 8 | 300+ |
-
----
-
-## Common Patterns
-
-### Error Handling Pattern
-
-```typescript
-// Pattern 1: Try-Catch with Formatting
-try {
-  const result = await operation();
-  return result;
-} catch (error) {
-  const formatted = formatErrorForUser(error);
-  console.error(formatted.message);
-  console.error('Suggestions:', formatted.suggestions);
-  throw error;
-}
-
-// Pattern 2: Promise Wrapper (Go-style)
-const [data, error] = await handlePromise(fetch('/api/data'));
-if (error) {
-  const formatted = formatErrorForUser(error);
-  return { success: false, error: formatted };
-}
-return { success: true, data };
-
-// Pattern 3: Retry with Backoff
-const data = await retryWithBackoff(
-  () => fetch('/api/data').then(r => r.json()),
-  3,
-  1000
-);
-```
-
-### Logging Pattern
-
-```typescript
-// Pattern 1: Module Logger
-const log = createLogger('ModuleName');
-log.info('Operation started', { userId: 42 });
-log.error('Failed', { error: error.message });
-
-// Pattern 2: Performance Monitoring
-const timer = log.time('database-query');
-const result = await db.query('SELECT *');
-timer(); // Logs: "database-query: 25ms"
-
-// Pattern 3: Scoped Context
-const requestLog = createScopedLogger(log, 'req-123', { userId: 42 });
-requestLog.info('Processing'); // Includes userId automatically
-```
-
-### Transformation Pipeline
-
-```typescript
-const result = await transform(users)
-  .pipe(filter(u => u.active))
-  .pipe(map(u => ({ ...u, name: u.name.toUpperCase() })))
-  .pipe(sortBy(u => u.name))
-  .pipe(chunk(10))
-  .execute();
-```
-
-### File Operations Pattern
-
-```typescript
-// Pattern 1: Safe Read-Process-Write
-const content = await readFile('./input.json');
-const data = JSON.parse(content);
-const processed = processData(data);
-await writeFile('./output.json', JSON.stringify(processed, null, 2), {
-  createDirs: true
-});
-
-// Pattern 2: Batch Processing
-const count = await batchProcessFiles(
-  './src',
-  async (filePath) => {
-    const content = await readFile(filePath);
-    await processFile(content);
-  },
-  { extension: '.ts', recursive: true }
-);
-```
-
----
-
-## Error Handling Best Practices
-
-### 1. Always Format Errors for Users
-
-```typescript
-// BAD: Shows technical details
-catch (error) {
-  console.error(error.message);
-}
-
-// GOOD: User-friendly with suggestions
-catch (error) {
-  const formatted = formatErrorForUser(error);
-  showNotification({
-    title: 'Operation Failed',
-    message: formatted.message,
-    suggestions: formatted.suggestions
-  });
-}
-```
-
-### 2. Sanitize Messages Before Display
-
-```typescript
-// BAD: May leak sensitive info
-const message = error.message; // Could contain paths, tokens
-
-// GOOD: Sanitized safe message
-const message = sanitizeErrorMessage(error.message);
-// Removes: paths, URLs, credentials, env vars
-```
-
-### 3. Use Proper Error Codes
-
-```typescript
-// BAD: Generic error handling
-if (error) console.error('Error');
-
-// GOOD: Categorized error handling
-try {
-  await fileOp();
-} catch (error) {
-  let code = 'UNKNOWN';
-  if (error.message.includes('ENOENT')) code = 'ENOENT';
-  else if (error.message.includes('EACCES')) code = 'EACCES';
-  
-  const formatted = formatErrorForUser(error, { code });
-  // Show appropriate UI based on code
-}
-```
-
-### 4. Log Technical Details Separately
-
-```typescript
-try {
-  await operation();
-} catch (error) {
-  const formatted = formatErrorForUser(error);
-  
-  // Log full technical details (never shown to user)
-  internalLogger.error(formatted.technicalDetails);
-  
-  // Show safe user message
-  userNotification.error(formatted.message);
-}
-```
-
-### 5. Implement Retry Logic
-
-```typescript
-// Pattern: Retry for transient failures
-try {
-  return await retryWithBackoff(
-    () => fetch('/api/data').then(r => r.json()),
-    3,    // max attempts
-    1000  // base delay ms
-  );
-} catch (error) {
-  // Final error after all retries failed
-  const formatted = formatErrorForUser(error);
-  showFatalError(formatted);
-}
-```
-
----
-
-## Performance Guidelines
-
-### Array Operations
-
-| Operation | Complexity | Notes | When to Use |
-|-----------|-----------|-------|-----------|
-| groupBy | O(n) | Single pass | Categorizing data |
-| unique | O(n) | Uses Set | Remove duplicates |
-| flatten | O(n) | Recursive | Normalize structure |
-| chunk | O(n) | Memory efficient | Batch processing |
-| sortBy | O(n log n) | Array copy | Ordered results |
-| partition | O(n) | Single pass | Split by criteria |
-| zip/unzip | O(n) | Single pass | Pair arrays |
-
-### File Operations
-
-| Operation | Performance | Best For |
-|-----------|-----------|----------|
-| readFile | I/O bound | < 100 MB files |
-| listFiles recursive | I/O bound | Use with caution on large trees |
-| batch processing | I/O bound | Process multiple files sequentially |
-| copyFile verify | I/O bound + Hash | Critical files |
-
-### Optimization Tips
-
-1. **Array Operations**: Reuse results, avoid multiple passes
-```typescript
-// BAD: Multiple passes
-const filtered = data.filter(x => x.active);
-const grouped = groupBy(filtered, x => x.role);
-const mapped = grouped.map(x => x.value);
-
-// GOOD: Pipeline or single operation
-const result = await transform(data)
-  .pipe(filter(x => x.active))
-  .pipe(map(x => ({ ...x, role: x.role.toUpperCase() })))
-  .execute();
-```
-
-2. **File I/O**: Batch operations when possible
-```typescript
-// BAD: Multiple operations
-for (const file of files) {
-  const meta = await getMetadata(file);
-}
-
-// GOOD: Batch with iterator
-const count = await batchProcessFiles(dir, async (file) => {
-  const meta = await getMetadata(file);
-}, { recursive: true });
-```
-
-3. **Logging**: Use appropriate levels
-```typescript
-// BAD: Expensive operation always runs
-log.debug('User data: ' + JSON.stringify(hugeObject));
-
-// GOOD: Only runs if debug is enabled
-if (getLogLevel() <= LogLevel.DEBUG) {
-  log.debug('User data', hugeObject);
-}
-```
-
-4. **String Operations**: Use efficient methods
-```typescript
-// BAD: Multiple operations
-const result = str.toLowerCase().trim().split(' ').join('-');
-
-// GOOD: Direct formatting
-const result = stringFormatter.toKebabCase(str.trim());
-```
-
----
-
-## Security Considerations
-
-### 1. Path Traversal Prevention
-
-```typescript
-// BAD: Unsafe path handling
-const userPath = req.query.file;
-const content = await readFile(`./uploads/${userPath}`);
-// User could request: "../../../etc/passwd"
-
-// GOOD: Validate path safety
-const userPath = validatePath(req.query.file);
-if (!isSafePath(userPath)) {
-  throw new Error('Invalid path');
-}
-const content = await readFile(`./uploads/${userPath}`);
-```
-
-### 2. Command Injection Prevention
-
-```typescript
-// BAD: Shell injection vulnerability
-const result = await executeCommand(`rm -rf ${userDir}`);
-// User provides: ".; cat /etc/passwd"
-
-// GOOD: Proper escaping
-const result = await executeCommand('rm', ['-rf', userDir]);
-// Or use shell escape
-const command = `rm -rf ${shellEscape(userDir)}`;
-```
-
-### 3. Error Information Leakage
-
-```typescript
-// BAD: Exposes internal paths
-catch (error) {
-  res.json({ error: error.message });
-}
-// Client sees: "/home/user/app/src/db/connection.ts:42"
-
-// GOOD: Sanitize before sending
-catch (error) {
-  const formatted = formatErrorForUser(error);
-  res.json({ error: formatted.message });
-  // Client sees: "Database connection failed"
-  // Internal log: "TypeError: Cannot read property..."
-}
-```
-
-### 4. Clipboard Security
-
-```typescript
-// Only request clipboard when necessary
-const permission = await navigator.permissions.query({ name: 'clipboard-read' });
-if (permission.state === 'granted') {
-  const data = await readClipboard();
-}
-
-// Clear sensitive clipboard data
-await copyImageToClipboard(sensitiveImage);
-// Later...
-await clearClipboard();
-```
-
-### 5. Frontmatter Validation
-
-```typescript
-// Bad: Accept any YAML
-const { frontmatter } = parseFrontmatter(userFile);
-const title = frontmatter.title; // Could contain malicious code
-
-// Good: Validate structure
-const { frontmatter } = parseFrontmatter(userFile);
-validateFrontmatter(frontmatter, {
-  title: { type: 'string', maxLength: 200 },
-  author: { type: 'string', maxLength: 100 },
-  tags: { type: 'array', maxItems: 10 }
-});
-```
-
-### 6. File Size Limits
-
-```typescript
-// Prevent resource exhaustion
-const content = await readFile(filePath, {
-  maxSize: 10 * 1024 * 1024 // 10 MB limit
-});
-
-// Check before processing
-const meta = await getMetadata(filePath);
-if (meta.size > MAX_SAFE_SIZE) {
-  throw new Error('File too large');
-}
-```
-
----
-
-## Quick Start Examples
-
-### Example 1: Complete Error Handling
-
-```typescript
-import {
-  formatErrorForUser,
-  sanitizeErrorMessage,
-  retryWithBackoff,
-  ErrorCode
-} from './utils';
-
-async function fetchWithErrorHandling() {
-  try {
-    const data = await retryWithBackoff(
-      () => fetch('/api/data').then(r => r.json()),
-      3,
-      1000
-    );
-    return { success: true, data };
-  } catch (error) {
-    const formatted = formatErrorForUser(error, {
-      code: ErrorCode.NETWORK
-    });
-    return {
-      success: false,
-      error: formatted.message,
-      suggestions: formatted.suggestions
-    };
-  }
-}
-```
-
-### Example 2: File Processing with Logging
-
-```typescript
-import {
-  createLogger,
-  readFile,
-  writeFile,
-  batchProcessFiles,
-  formatErrorForUser
-} from './utils';
-
-const log = createLogger('FileProcessor');
-
-async function processMarkdownFiles() {
-  try {
-    const timer = log.time('processing');
-    
-    let processed = 0;
-    const count = await batchProcessFiles(
-      './docs',
-      async (filePath) => {
-        try {
-          const content = await readFile(filePath);
-          const processed = processMarkdown(content);
-          await writeFile(filePath, processed, { createDirs: true });
-          log.debug('Processed file', { file: filePath });
-          processed++;
-        } catch (error) {
-          log.error('Failed processing file', { file: filePath, error: String(error) });
-        }
-      },
-      { extension: '.md', recursive: true }
-    );
-    
-    timer(); // Logs duration
-    log.info('Processing complete', { filesProcessed: processed, total: count });
-  } catch (error) {
-    const formatted = formatErrorForUser(error);
-    log.fatal('Batch processing failed', { error: formatted.message });
-    throw error;
-  }
-}
-```
-
-### Example 3: Data Transformation Pipeline
-
-```typescript
-import {
-  transform,
-  createLogger,
-  groupBy,
-  formatDate
-} from './utils';
-
-const log = createLogger('Analytics');
-
-async function analyzeUserActivity() {
-  const result = await transform(userEvents)
-    .pipe(filter(e => e.timestamp > oneWeekAgo))
-    .pipe(map(e => ({
-      userId: e.userId,
-      action: e.action.toUpperCase(),
-      date: formatDate(new Date(e.timestamp), 'yyyy-MM-dd')
-    })))
-    .pipe(groupBy(e => e.userId))
-    .execute();
-  
-  log.info('Analysis complete', { uniqueUsers: Object.keys(result).length });
-  return result;
-}
-```
-
-### Example 4: Git Repository Analysis
-
-```typescript
-import {
-  createLogger,
-  getCommitHistory,
-  getCurrentBranch,
-  getGitStatus
-} from './utils';
-
-const log = createLogger('GitAnalysis');
-
-async function analyzeRepository() {
-  try {
-    const branch = await getCurrentBranch();
-    const status = await getGitStatus();
-    const history = await getCommitHistory(50);
-    
-    log.info('Repository analysis', {
-      branch,
-      uncommittedChanges: status.unstaged.length,
-      recentCommits: history.length
-    });
-    
-    return { branch, status, history };
-  } catch (error) {
-    log.error('Git operation failed', { error: String(error) });
-    throw error;
-  }
-}
-```
-
-### Example 5: Image Processing Pipeline
-
-```typescript
-import {
-  resizeImage,
-  convertFormat,
-  createLogger,
-  formatErrorForUser
-} from './utils';
-
-const log = createLogger('ImageProcessor');
-
-async function optimizeImage(inputPath, outputPath) {
-  try {
-    const timer = log.time('optimization');
-    
-    // Resize to max 2048 width
-    const resized = await resizeImage(inputPath, {
-      width: 2048,
-      height: 2048,
-      fit: 'inside'
-    });
-    
-    // Convert to WebP for better compression
-    const optimized = await convertFormat(resized, 'webp', {
-      quality: 0.8
-    });
-    
-    // Save result
-    await writeFile(outputPath, optimized);
-    
-    timer(); // Logs duration
-    log.info('Image optimized', { 
-      from: inputPath,
-      to: outputPath 
-    });
-  } catch (error) {
-    const formatted = formatErrorForUser(error);
-    log.error('Optimization failed', { error: formatted.message });
-    throw error;
-  }
-}
-```
-
----
-
-## Troubleshooting Guide
-
-### Common Issues
-
-#### 1. File Not Found Errors
-
-**Problem**: FileOperationError with ENOENT code
-
-**Root Causes**:
-- File path is incorrect
-- File deleted before operation
-- Relative path resolving differently
-- Permission issues
-
-**Solutions**:
-```typescript
-// Solution 1: Validate path
-const safePath = validatePath(filePath);
-
-// Solution 2: Resolve to absolute
-const absolute = resolvePath(filePath);
-const exists = await fileExists(absolute);
-
-// Solution 3: Create dirs before write
-await writeFile(filePath, content, { createDirs: true });
-
-// Solution 4: Better error handling
-try {
-  const content = await readFile(filePath);
-} catch (error) {
-  if (error.code === ErrorCode.ENOENT) {
-    console.log('File not found. Creating template...');
-    await writeFile(filePath, defaultContent, { createDirs: true });
-  }
-}
-```
-
-#### 2. Permission Denied Errors
-
-**Problem**: FileOperationError with EACCES code
-
-**Root Causes**:
-- Insufficient file permissions
-- Operating system restrictions
-- Running as wrong user
-
-**Solutions**:
-```typescript
-// Solution 1: Check permissions
-const meta = await getMetadata(filePath);
-const isReadable = (meta.mode & 0o400) !== 0;
-const isWritable = (meta.mode & 0o200) !== 0;
-
-// Solution 2: Use elevated privileges
-// Note: Requires system configuration
-const result = await executeCommand(`sudo ${command}`);
-
-// Solution 3: Create with proper mode
-await writeFile(filePath, content, { mode: 0o644 });
-```
-
-#### 3. Logging Not Showing
-
-**Problem**: Log messages don't appear
-
-**Root Causes**:
-- Log level set too high
-- Logger not configured
-- Wrong logger instance
-
-**Solutions**:
-```typescript
-// Solution 1: Check log level
-const currentLevel = getLogLevel();
-if (currentLevel > LogLevel.DEBUG) {
-  setLogLevel('debug'); // Lower the threshold
-}
-
-// Solution 2: Create logger properly
-const log = createLogger('MyModule');
-log.info('This should show');
-
-// Solution 3: Use createLogger consistently
-// Always use named loggers, not console.log
-const log = createLogger('FeatureName');
-```
-
-#### 4. JSON Parsing Errors
-
-**Problem**: JSON.parse fails or produces invalid data
-
-**Root Causes**:
-- Malformed JSON syntax
-- Encoding issues
-- Data contamination
-
-**Solutions**:
-```typescript
-// Solution 1: Use safe parsing
-const [data, error] = parseJSON(jsonString);
-if (error) {
-  console.error('Invalid JSON:', error.message);
-  return null;
-}
-
-// Solution 2: Validate before parsing
-const valid = validateJSON(jsonString);
-if (!valid) {
-  console.error('JSON validation failed');
-  return null;
-}
-
-// Solution 3: Format and clean
-const cleaned = formatJSON(dirtyJSON);
-const parsed = JSON.parse(cleaned);
-```
-
-#### 5. Image Processing Failures
-
-**Problem**: Image conversion or resizing fails
-
-**Root Causes**:
-- Unsupported format
-- Corrupted image data
-- Missing dependencies
-
-**Solutions**:
-```typescript
-// Solution 1: Validate format
-const format = detectFormat(imagePath);
-const supported = ['png', 'jpg', 'webp', 'gif'];
-if (!supported.includes(format)) {
-  throw new Error(`Unsupported format: ${format}`);
-}
-
-// Solution 2: Check dimensions
-const dimensions = await getImageDimensions(imagePath);
-if (dimensions.width > 10000 || dimensions.height > 10000) {
-  throw new Error('Image too large');
-}
-
-// Solution 3: Try incremental resizing
-const step1 = await resizeImage(input, { width: 4000 });
-const step2 = await resizeImage(step1, { width: 2000 });
-```
-
-#### 6. Shell Command Execution Failures
-
-**Problem**: executeCommand throws or produces wrong output
-
-**Root Causes**:
-- Command not in PATH
-- Wrong argument format
-- Permission issues
-- Shell not available
-
-**Solutions**:
-```typescript
-// Solution 1: Check command availability
-const available = await checkCommand('npm');
-if (!available) {
-  console.error('npm not found in PATH');
-  return;
-}
-
-// Solution 2: Use proper escaping
-const result = await executeCommand('ls', ['-la', safePath]);
-// Instead of: await executeCommand(`ls -la ${userInput}`);
-
-// Solution 3: Check output carefully
-const result = await executeCommand('npm', ['--version']);
-if (result.code !== 0) {
-  console.error('Command failed:', result.stderr);
-}
-```
-
-#### 7. Type Guard Failures
-
-**Problem**: Type guards not catching errors
-
-**Root Causes**:
-- Using JavaScript typeof incorrectly
-- Complex type structures
-- Runtime type differences
-
-**Solutions**:
-```typescript
-// Solution 1: Use provided type guards
-if (isArray(value) && value.length > 0) {
-  // Safe to access value[0]
-}
-
-// Solution 2: Chain type checks
-if (isDefined(value) && isObject(value) && hasProperty(value, 'name')) {
-  console.log(value.name); // Safe
-}
-
-// Solution 3: Use assertion
-try {
-  assertType(value, 'string');
-  console.log(value.toUpperCase()); // Now safe
-} catch (error) {
-  console.error('Type mismatch:', error.message);
-}
-```
-
-### Performance Issues
-
-#### Problem: Slow Array Operations
-
-```typescript
-// Bad: Multiple iterations
-const filtered = data.filter(x => x.active);
-const mapped = filtered.map(x => transform(x));
-const sorted = mapped.sort((a, b) => a.id - b.id);
-
-// Good: Single pipeline
-const result = await transform(data)
-  .pipe(filter(x => x.active))
-  .pipe(map(x => transform(x)))
-  .pipe(sortBy((a, b) => a.id - b.id))
-  .execute();
-```
-
-#### Problem: Slow File Operations
-
-```typescript
-// Bad: Individual operations
-for (const file of files) {
-  const content = await readFile(file);
-  await processFile(content);
-  await writeFile(file, processed);
-}
-
-// Good: Batch processing
-await batchProcessFiles(dir, async (file) => {
-  const content = await readFile(file);
-  const processed = await processFile(content);
-  await writeFile(file, processed);
-});
-```
-
----
-
-## Resources
-
-### External References
-- [Node.js fs module](https://nodejs.org/api/fs.html)
-- [POSIX error codes](https://nodejs.org/api/errors.html#errors_posix_error_codes)
-- [TypeScript Handbook](https://www.typescriptlang.org/docs/)
-- [WCAG Color Contrast](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum)
-
-### Related Documentation
-- [UTILS-USAGE-GUIDE.md](./UTILS-USAGE-GUIDE.md) - Detailed usage examples
-- [UTILS-QA-CHECKLIST.md](./UTILS-QA-CHECKLIST.md) - Testing and QA
-- [UTILS-IMPLEMENTATION-SUMMARY.md](./UTILS-IMPLEMENTATION-SUMMARY.md) - Implementation details
-
-### Source Code
-- Main utilities: `src/utils/*.ts`
-- Tests: `src/utils/__tests__/*.test.ts`
-- Type definitions: `src/utils/*.ts` (inline)
-
----
-
-**Last Updated**: February 2024  
-**Maintained By**: Indusagi Core Team  
-**License**: MIT
-