oh-my-node-modules 1.0.0

package/dist/index.js

@@ -0,0 +1,882 @@
+import { promises } from 'fs';
+import { join, basename, dirname } from 'path';
+
+/** Default color configuration using standard terminal colors */ const DEFAULT_COLORS = {
+    huge: 'red',
+    large: 'yellow',
+    small: 'green',
+    stale: 'gray',
+    fresh: 'white',
+    selected: 'cyan',
+    error: 'red',
+    success: 'green',
+    warning: 'yellow',
+    info: 'blue'
+};
+/**
+ * Thresholds for size categorization in bytes.
+ * Used to determine visual styling and smart selection rules.
+ */ const SIZE_THRESHOLDS = {
+    /** 100 MB - upper bound for "small" category */ SMALL: 100 * 1024 * 1024,
+    /** 500 MB - upper bound for "medium" category */ MEDIUM: 500 * 1024 * 1024,
+    /** 1 GB - upper bound for "large" category */ LARGE: 1024 * 1024 * 1024
+};
+/**
+ * Thresholds for age categorization in days.
+ * Used to identify stale node_modules that might be safe to delete.
+ */ const AGE_THRESHOLDS = {
+    /** 7 days - still considered fresh */ FRESH: 7,
+    /** 30 days - warning threshold */ RECENT: 30,
+    /** 90 days - stale threshold */ OLD: 90
+};
+
+/**
+ * Format bytes into human-readable string.
+ * Uses binary units (MiB, GiB) for accuracy.
+ * 
+ * @param bytes - Number of bytes to format
+ * @returns Formatted string like "1.2 GB" or "456 MB"
+ */ function formatBytes(bytes) {
+    if (bytes === 0) return '0 B';
+    const units = [
+        'B',
+        'KB',
+        'MB',
+        'GB',
+        'TB'
+    ];
+    const base = 1024;
+    const exponent = Math.floor(Math.log(bytes) / Math.log(base));
+    const unit = units[Math.min(exponent, units.length - 1)];
+    const value = bytes / Math.pow(base, exponent);
+    // Show 1 decimal place for MB and above, 0 for smaller
+    const decimals = exponent >= 2 ? 1 : 0;
+    return `${value.toFixed(decimals)} ${unit}`;
+}
+/**
+ * Parse human-readable size string into bytes.
+ * Supports formats like "1gb", "500MB", "10mb"
+ * 
+ * @param sizeStr - Size string to parse
+ * @returns Size in bytes, or undefined if invalid
+ */ function parseSize(sizeStr) {
+    const match = sizeStr.trim().toLowerCase().match(/^(\d+(?:\.\d+)?)\s*(b|kb|mb|gb|tb)?$/);
+    if (!match) return undefined;
+    const value = parseFloat(match[1]);
+    const unit = match[2] || 'b';
+    const multipliers = {
+        b: 1,
+        kb: 1024,
+        mb: 1024 * 1024,
+        gb: 1024 * 1024 * 1024,
+        tb: 1024 * 1024 * 1024 * 1024
+    };
+    return Math.floor(value * (multipliers[unit] || 1));
+}
+/**
+ * Format a date into "X days ago" string.
+ * Provides more readable relative time than raw dates.
+ * 
+ * @param date - Date to format
+ * @returns Formatted string like "30d ago" or "2d ago"
+ */ function formatRelativeTime(date) {
+    const now = new Date();
+    const diffMs = now.getTime() - date.getTime();
+    const diffDays = Math.floor(diffMs / (1000 * 60 * 60 * 24));
+    if (diffDays === 0) {
+        const diffHours = Math.floor(diffMs / (1000 * 60 * 60));
+        if (diffHours === 0) {
+            const diffMinutes = Math.floor(diffMs / (1000 * 60));
+            return diffMinutes <= 1 ? 'just now' : `${diffMinutes}m ago`;
+        }
+        return `${diffHours}h ago`;
+    }
+    if (diffDays < 30) return `${diffDays}d ago`;
+    if (diffDays < 365) return `${Math.floor(diffDays / 30)}mo ago`;
+    return `${Math.floor(diffDays / 365)}y ago`;
+}
+/**
+ * Determine size category based on bytes.
+ * Used for color coding and smart selection.
+ * 
+ * @param bytes - Size in bytes
+ * @returns Size category
+ */ function getSizeCategory(bytes) {
+    if (bytes > SIZE_THRESHOLDS.LARGE) return 'huge';
+    if (bytes > SIZE_THRESHOLDS.MEDIUM) return 'large';
+    if (bytes > SIZE_THRESHOLDS.SMALL) return 'medium';
+    return 'small';
+}
+/**
+ * Determine age category based on days since modification.
+ * Used to identify potentially stale node_modules.
+ * 
+ * @param lastModified - Last modification date
+ * @returns Age category
+ */ function getAgeCategory(lastModified) {
+    const now = new Date();
+    const diffDays = Math.floor((now.getTime() - lastModified.getTime()) / (1000 * 60 * 60 * 24));
+    if (diffDays > AGE_THRESHOLDS.OLD) return 'stale';
+    if (diffDays > AGE_THRESHOLDS.RECENT) return 'old';
+    if (diffDays > AGE_THRESHOLDS.FRESH) return 'recent';
+    return 'fresh';
+}
+/**
+ * Calculate age in days from a date.
+ * 
+ * @param date - Date to calculate age from
+ * @returns Number of days
+ */ function getAgeInDays$1(date) {
+    const now = new Date();
+    return Math.floor((now.getTime() - date.getTime()) / (1000 * 60 * 60 * 24));
+}
+/**
+ * Sort node_modules by the specified option.
+ * Pure function that returns a new sorted array.
+ * 
+ * @param items - Array to sort
+ * @param sortBy - Sort option
+ * @returns New sorted array
+ */ function sortNodeModules(items, sortBy) {
+    const sorted = [
+        ...items
+    ]; // Create copy to avoid mutation
+    switch(sortBy){
+        case 'size-desc':
+            return sorted.sort((a, b)=>b.sizeBytes - a.sizeBytes);
+        case 'size-asc':
+            return sorted.sort((a, b)=>a.sizeBytes - b.sizeBytes);
+        case 'date-desc':
+            return sorted.sort((a, b)=>b.lastModified.getTime() - a.lastModified.getTime());
+        case 'date-asc':
+            return sorted.sort((a, b)=>a.lastModified.getTime() - b.lastModified.getTime());
+        case 'name-asc':
+            return sorted.sort((a, b)=>a.projectName.localeCompare(b.projectName));
+        case 'name-desc':
+            return sorted.sort((a, b)=>b.projectName.localeCompare(a.projectName));
+        case 'packages-desc':
+            return sorted.sort((a, b)=>b.totalPackageCount - a.totalPackageCount);
+        case 'packages-asc':
+            return sorted.sort((a, b)=>a.totalPackageCount - b.totalPackageCount);
+        default:
+            return sorted;
+    }
+}
+/**
+ * Filter node_modules by search query.
+ * Matches against project name and path.
+ * 
+ * @param items - Array to filter
+ * @param query - Search query (case-insensitive)
+ * @returns Filtered array
+ */ function filterNodeModules(items, query) {
+    if (!query.trim()) return items;
+    const lowerQuery = query.toLowerCase();
+    return items.filter((item)=>item.projectName.toLowerCase().includes(lowerQuery) || item.path.toLowerCase().includes(lowerQuery));
+}
+/**
+ * Calculate statistics from node_modules list.
+ * Used for overview displays and summaries.
+ * 
+ * @param items - Node modules to analyze
+ * @returns Calculated statistics
+ */ function calculateStatistics(items) {
+    const selectedItems = items.filter((item)=>item.selected);
+    const totalSize = items.reduce((sum, item)=>sum + item.sizeBytes, 0);
+    const selectedSize = selectedItems.reduce((sum, item)=>sum + item.sizeBytes, 0);
+    const totalAge = items.reduce((sum, item)=>{
+        return sum + getAgeInDays$1(item.lastModified);
+    }, 0);
+    const staleCount = items.filter((item)=>item.ageCategory === 'stale').length;
+    return {
+        totalProjects: new Set(items.map((item)=>item.projectPath)).size,
+        totalNodeModules: items.length,
+        totalSizeBytes: totalSize,
+        totalSizeFormatted: formatBytes(totalSize),
+        selectedCount: selectedItems.length,
+        selectedSizeBytes: selectedSize,
+        selectedSizeFormatted: formatBytes(selectedSize),
+        averageAgeDays: items.length > 0 ? Math.round(totalAge / items.length) : 0,
+        staleCount
+    };
+}
+/**
+ * Check if a path should be excluded based on patterns.
+ * Supports glob-like patterns with * and ? wildcards.
+ * 
+ * @param path - Path to check
+ * @param patterns - Exclusion patterns
+ * @returns True if path should be excluded
+ */ function shouldExcludePath(path, patterns) {
+    return patterns.some((pattern)=>{
+        // Convert glob pattern to regex
+        const regexPattern = pattern.replace(/\*\*/g, '{{GLOBSTAR}}').replace(/\*/g, '[^/]*').replace(/\?/g, '.').replace(/\{\{GLOBSTAR\}\}/g, '.*');
+        const regex = new RegExp(regexPattern, 'i');
+        return regex.test(path);
+    });
+}
+/**
+ * Toggle selection state for a node_modules item.
+ * Returns new array with toggled item (immutable update).
+ * 
+ * @param items - Current items array
+ * @param index - Index of item to toggle
+ * @returns New array with toggled selection
+ */ function toggleSelection(items, index) {
+    if (index < 0 || index >= items.length) return items;
+    return items.map((item, i)=>i === index ? {
+            ...item,
+            selected: !item.selected
+        } : item);
+}
+/**
+ * Select or deselect all items matching a predicate.
+ * Useful for "select all >500MB" or "select all stale" operations.
+ * 
+ * @param items - Current items array
+ * @param predicate - Function to determine which items to select
+ * @param selected - Whether to select (true) or deselect (false)
+ * @returns New array with updated selections
+ */ function selectByPredicate(items, predicate, selected) {
+    return items.map((item)=>predicate(item) ? {
+            ...item,
+            selected
+        } : item);
+}
+/**
+ * Safe file existence check that doesn't throw.
+ * Useful for checking if package.json exists before parsing.
+ * 
+ * @param path - Path to check
+ * @returns True if file exists
+ */ async function fileExists(path) {
+    try {
+        await promises.access(path);
+        return true;
+    } catch  {
+        return false;
+    }
+}
+/**
+ * Read and parse package.json safely.
+ * Returns undefined if file doesn't exist or is invalid.
+ * 
+ * @param projectPath - Path to project directory
+ * @returns Parsed package.json or undefined
+ */ async function readPackageJson(projectPath) {
+    const packagePath = join(projectPath, 'package.json');
+    try {
+        const content = await promises.readFile(packagePath, 'utf-8');
+        const parsed = JSON.parse(content);
+        return parsed;
+    } catch  {
+        return undefined;
+    }
+}
+
+/**
+ * Recursively scan for node_modules directories starting from root path.
+ * 
+ * This is the main entry point for discovery. It walks the directory tree,
+ * identifies node_modules folders, and collects metadata about each one.
+ * 
+ * @param options - Scan configuration options
+ * @param onProgress - Optional callback for progress updates (0-100)
+ * @returns Scan results with all discovered node_modules
+ */ async function scanForNodeModules(options, onProgress) {
+    const result = {
+        nodeModules: [],
+        directoriesScanned: 0,
+        errors: []
+    };
+    const visitedPaths = new Set();
+    const pathsToScan = [
+        {
+            path: options.rootPath,
+            depth: 0
+        }
+    ];
+    let processedCount = 0;
+    let totalEstimate = 1; // Start with 1, will adjust as we discover
+    while(pathsToScan.length > 0){
+        const { path: currentPath, depth } = pathsToScan.shift();
+        // Skip if already visited or exceeds max depth
+        if (visitedPaths.has(currentPath)) continue;
+        if (options.maxDepth !== undefined && depth > options.maxDepth) continue;
+        if (shouldExcludePath(currentPath, options.excludePatterns)) continue;
+        visitedPaths.add(currentPath);
+        result.directoriesScanned++;
+        try {
+            const entries = await promises.readdir(currentPath, {
+                withFileTypes: true
+            });
+            // Check if current directory has node_modules
+            const hasNodeModules = entries.some((entry)=>entry.isDirectory() && entry.name === 'node_modules');
+            if (hasNodeModules) {
+                const nodeModulesPath = join(currentPath, 'node_modules');
+                const info = await analyzeNodeModules(nodeModulesPath, currentPath);
+                // Apply filters
+                if (options.minSizeBytes && info.sizeBytes < options.minSizeBytes) {
+                // Skip - too small
+                } else if (options.olderThanDays && getAgeInDays(info.lastModified) < options.olderThanDays) {
+                // Skip - too recent
+                } else {
+                    result.nodeModules.push(info);
+                }
+            }
+            // Add subdirectories to scan queue (excluding node_modules itself)
+            for (const entry of entries){
+                if (entry.isDirectory() && entry.name !== 'node_modules' && !entry.name.startsWith('.')) {
+                    const subPath = join(currentPath, entry.name);
+                    if (!shouldExcludePath(subPath, options.excludePatterns)) {
+                        pathsToScan.push({
+                            path: subPath,
+                            depth: depth + 1
+                        });
+                        totalEstimate++;
+                    }
+                }
+            }
+        } catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            result.errors.push(`Error scanning ${currentPath}: ${errorMessage}`);
+        }
+        // Report progress
+        processedCount++;
+        if (onProgress) {
+            const progress = Math.min(100, Math.round(processedCount / totalEstimate * 100));
+            onProgress(progress);
+        }
+    }
+    // Ensure we report 100% at the end
+    if (onProgress) {
+        onProgress(100);
+    }
+    return result;
+}
+/**
+ * Analyze a specific node_modules directory and extract all metadata.
+ * 
+ * This function performs the heavy lifting of:
+ * - Calculating total size (recursive)
+ * - Counting packages
+ * - Reading parent project info
+ * - Determining age and size categories
+ * 
+ * @param nodeModulesPath - Path to node_modules directory
+ * @param projectPath - Path to parent project (containing package.json)
+ * @returns Complete metadata for the node_modules
+ */ async function analyzeNodeModules(nodeModulesPath, projectPath) {
+    // Get basic stats
+    const stats = await promises.stat(nodeModulesPath);
+    // Calculate size and count packages
+    const { totalSize, packageCount, totalPackageCount } = await calculateDirectorySize(nodeModulesPath);
+    // Read project info from package.json
+    const packageJson = await readPackageJson(projectPath);
+    const projectName = packageJson?.name || basename(projectPath);
+    const projectVersion = packageJson?.version;
+    // Determine categories
+    const sizeCategory = getSizeCategory(totalSize);
+    const ageCategory = getAgeCategory(stats.mtime);
+    return {
+        path: nodeModulesPath,
+        projectPath,
+        projectName,
+        projectVersion,
+        sizeBytes: totalSize,
+        sizeFormatted: formatBytes(totalSize),
+        packageCount,
+        totalPackageCount,
+        lastModified: stats.mtime,
+        lastModifiedFormatted: formatRelativeTime(stats.mtime),
+        selected: false,
+        isFavorite: false,
+        ageCategory,
+        sizeCategory
+    };
+}
+/**
+ * Recursively calculate directory size and package counts.
+ * 
+ * This is an expensive operation for large node_modules directories.
+ * We optimize by:
+ * - Using iterative approach (avoid stack overflow)
+ * - Counting only top-level packages for packageCount
+ * - Counting all packages for totalPackageCount
+ * 
+ * @param dirPath - Directory to analyze
+ * @returns Size in bytes and package counts
+ */ async function calculateDirectorySize(dirPath) {
+    let totalSize = 0;
+    let packageCount = 0;
+    let totalPackageCount = 0;
+    let isTopLevel = true;
+    const pathsToProcess = [
+        dirPath
+    ];
+    const processedPaths = new Set();
+    while(pathsToProcess.length > 0){
+        const currentPath = pathsToProcess.pop();
+        if (processedPaths.has(currentPath)) continue;
+        processedPaths.add(currentPath);
+        try {
+            const stats = await promises.stat(currentPath);
+            if (stats.isFile()) {
+                totalSize += stats.size;
+            } else if (stats.isDirectory()) {
+                // Add directory entry size (approximate)
+                totalSize += 4096; // Typical directory entry size
+                // Count packages at top level only
+                if (isTopLevel && currentPath !== dirPath) {
+                    const entryName = basename(currentPath);
+                    // Skip hidden directories and special directories
+                    if (!entryName.startsWith('.') && entryName !== '.bin') {
+                        packageCount++;
+                    }
+                }
+                // Count all packages for total
+                if (currentPath !== dirPath) {
+                    const entryName = basename(currentPath);
+                    if (!entryName.startsWith('.') && entryName !== '.bin') {
+                        totalPackageCount++;
+                    }
+                }
+                // Read directory contents
+                try {
+                    const entries = await promises.readdir(currentPath, {
+                        withFileTypes: true
+                    });
+                    for (const entry of entries){
+                        const entryPath = join(currentPath, entry.name);
+                        pathsToProcess.push(entryPath);
+                    }
+                } catch  {
+                // Permission denied or other error - skip this directory
+                }
+            } else if (stats.isSymbolicLink()) {
+            // Skip symbolic links to avoid cycles
+            }
+        } catch  {
+        // File not accessible - skip
+        }
+        if (currentPath === dirPath) {
+            isTopLevel = false;
+        }
+    }
+    return {
+        totalSize,
+        packageCount,
+        totalPackageCount
+    };
+}
+/**
+ * Helper to get age in days from a date.
+ */ function getAgeInDays(date) {
+    const now = new Date();
+    return Math.floor((now.getTime() - date.getTime()) / (1000 * 60 * 60 * 24));
+}
+/**
+ * Load ignore patterns from .onmignore file.
+ * 
+ * Looks for .onmignore in:
+ * 1. Current working directory
+ * 2. Home directory
+ * 
+ * @returns Array of ignore patterns
+ */ async function loadIgnorePatterns() {
+    const patterns = [
+        '**/node_modules/**',
+        '**/.git/**',
+        '**/.*'
+    ];
+    const ignoreFiles = [
+        join(process.cwd(), '.onmignore'),
+        join(process.env.HOME || process.cwd(), '.onmignore')
+    ];
+    for (const ignoreFile of ignoreFiles){
+        try {
+            if (await fileExists(ignoreFile)) {
+                const content = await promises.readFile(ignoreFile, 'utf-8');
+                const lines = content.split('\n').map((line)=>line.trim()).filter((line)=>line && !line.startsWith('#'));
+                patterns.push(...lines);
+            }
+        } catch  {
+        // Ignore errors reading ignore files
+        }
+    }
+    return patterns;
+}
+/**
+ * Load favorites list from .onmfavorites file.
+ * 
+ * Favorites are projects that should never be suggested for deletion.
+ * 
+ * @returns Set of favorite project paths
+ */ async function loadFavorites() {
+    const favorites = new Set();
+    const favoritesFile = join(process.env.HOME || process.cwd(), '.onmfavorites');
+    try {
+        if (await fileExists(favoritesFile)) {
+            const content = await promises.readFile(favoritesFile, 'utf-8');
+            const lines = content.split('\n').map((line)=>line.trim()).filter((line)=>line && !line.startsWith('#'));
+            for (const line of lines){
+                favorites.add(line);
+            }
+        }
+    } catch  {
+    // Ignore errors reading favorites
+    }
+    return favorites;
+}
+/**
+ * Check if a node_modules directory is currently in use.
+ * 
+ * This is a safety check to prevent deleting node_modules that
+ * might be actively being used by a running process.
+ * 
+ * Note: This is a best-effort check and may not catch all cases.
+ * 
+ * @param path - Path to node_modules
+ * @returns True if potentially in use
+ */ async function isNodeModulesInUse(path) {
+    // This is a simplified check - in production, you might want to:
+    // 1. Check for lock files
+    // 2. Check for running node processes using this path
+    // 3. Check for open file handles
+    try {
+        const lockFiles = [
+            '.package-lock.json',
+            'yarn.lock',
+            'pnpm-lock.yaml'
+        ];
+        const projectPath = dirname(path);
+        for (const lockFile of lockFiles){
+            const lockPath = join(projectPath, lockFile);
+            try {
+                const stats = await promises.stat(lockPath);
+                // If lock file was modified in the last minute, might be in use
+                const oneMinuteAgo = Date.now() - 60 * 1000;
+                if (stats.mtime.getTime() > oneMinuteAgo) {
+                    return true;
+                }
+            } catch  {
+            // Lock file doesn't exist - that's fine
+            }
+        }
+    } catch  {
+    // Error checking - assume not in use
+    }
+    return false;
+}
+/**
+ * Quick scan mode - just report without full metadata.
+ * 
+ * Faster than full scan when you just need a quick overview.
+ * 
+ * @param rootPath - Root directory to scan
+ * @returns Basic info about found node_modules
+ */ async function quickScan(rootPath) {
+    const results = [];
+    const visitedPaths = new Set();
+    const pathsToScan = [
+        rootPath
+    ];
+    while(pathsToScan.length > 0){
+        const currentPath = pathsToScan.pop();
+        if (visitedPaths.has(currentPath)) continue;
+        visitedPaths.add(currentPath);
+        try {
+            const entries = await promises.readdir(currentPath, {
+                withFileTypes: true
+            });
+            const hasNodeModules = entries.some((entry)=>entry.isDirectory() && entry.name === 'node_modules');
+            if (hasNodeModules) {
+                const projectPath = currentPath;
+                const nodeModulesPath = join(currentPath, 'node_modules');
+                const packageJson = await readPackageJson(projectPath);
+                results.push({
+                    path: nodeModulesPath,
+                    projectPath,
+                    projectName: packageJson?.name || basename(projectPath)
+                });
+            }
+            // Add subdirectories
+            for (const entry of entries){
+                if (entry.isDirectory() && entry.name !== 'node_modules' && !entry.name.startsWith('.')) {
+                    pathsToScan.push(join(currentPath, entry.name));
+                }
+            }
+        } catch  {
+        // Skip directories we can't read
+        }
+    }
+    return results;
+}
+
+/**
+ * Delete selected node_modules directories.
+ * 
+ * This is the main entry point for deletion operations. It:
+ * 1. Filters to only selected items
+ * 2. Performs safety checks
+ * 3. Deletes each node_modules (or simulates in dry run)
+ * 4. Collects results and statistics
+ * 
+ * @param nodeModules - List of all node_modules (selected ones will be deleted)
+ * @param options - Deletion options
+ * @param onProgress - Optional callback for progress updates
+ * @returns Deletion results with statistics
+ */ async function deleteSelectedNodeModules(nodeModules, options, onProgress) {
+    const selected = nodeModules.filter((nm)=>nm.selected);
+    const result = {
+        totalAttempted: selected.length,
+        successful: 0,
+        failed: 0,
+        bytesFreed: 0,
+        formattedBytesFreed: '0 B',
+        details: []
+    };
+    for(let i = 0; i < selected.length; i++){
+        const item = selected[i];
+        if (onProgress) {
+            onProgress(i + 1, selected.length, item.projectName);
+        }
+        const detail = await deleteNodeModules(item, options);
+        result.details.push(detail);
+        if (detail.success) {
+            result.successful++;
+            result.bytesFreed += item.sizeBytes;
+        } else {
+            result.failed++;
+        }
+    }
+    result.formattedBytesFreed = formatBytes(result.bytesFreed);
+    return result;
+}
+/**
+ * Delete a single node_modules directory.
+ * 
+ * Performs safety checks before deletion:
+ * - Verifies it's actually a node_modules directory
+ * - Checks if it's in use (if enabled)
+ * - Verifies the path is valid
+ * 
+ * @param nodeModules - NodeModulesInfo to delete
+ * @param options - Deletion options
+ * @returns Detailed result of the deletion
+ */ async function deleteNodeModules(nodeModules, options) {
+    const startTime = Date.now();
+    const detail = {
+        nodeModules,
+        success: false,
+        durationMs: 0
+    };
+    try {
+        // Safety check 1: Verify path ends with node_modules
+        if (!nodeModules.path.endsWith('node_modules')) {
+            detail.error = 'Path does not appear to be a node_modules directory';
+            detail.durationMs = Date.now() - startTime;
+            return detail;
+        }
+        // Safety check 2: Verify directory exists
+        if (!await fileExists(nodeModules.path)) {
+            detail.error = 'Directory does not exist';
+            detail.durationMs = Date.now() - startTime;
+            return detail;
+        }
+        // Safety check 3: Check if in use
+        if (options.checkRunningProcesses) {
+            const inUse = await isNodeModulesInUse(nodeModules.path);
+            if (inUse) {
+                detail.error = 'Directory appears to be in use by a running process';
+                detail.durationMs = Date.now() - startTime;
+                return detail;
+            }
+        }
+        // Safety check 4: Verify it looks like a real node_modules
+        const isValidNodeModules = await verifyNodeModules(nodeModules.path);
+        if (!isValidNodeModules) {
+            detail.error = 'Directory does not appear to be a valid node_modules';
+            detail.durationMs = Date.now() - startTime;
+            return detail;
+        }
+        // Perform deletion (or simulate)
+        if (options.dryRun) {
+            // In dry run, just simulate success
+            detail.success = true;
+        } else {
+            // Actually delete the directory
+            await promises.rm(nodeModules.path, {
+                recursive: true,
+                force: true
+            });
+            detail.success = true;
+        }
+        detail.durationMs = Date.now() - startTime;
+    } catch (error) {
+        detail.error = error instanceof Error ? error.message : String(error);
+        detail.durationMs = Date.now() - startTime;
+    }
+    return detail;
+}
+/**
+ * Verify that a directory looks like a real node_modules.
+ * 
+ * We check for:
+ * - Directory name is exactly "node_modules"
+ * - Contains at least one subdirectory (package)
+ * - Parent directory contains package.json
+ * 
+ * These checks prevent accidental deletion of similarly named directories.
+ * 
+ * @param path - Path to verify
+ * @returns True if it looks like a valid node_modules
+ */ async function verifyNodeModules(path) {
+    try {
+        // Check name
+        const parts = path.split('/');
+        if (parts[parts.length - 1] !== 'node_modules') {
+            return false;
+        }
+        // Check it has contents (not empty)
+        const entries = await promises.readdir(path);
+        const hasSubdirs = entries.some(async (entry)=>{
+            const entryPath = join(path, entry);
+            const stats = await promises.stat(entryPath);
+            return stats.isDirectory();
+        });
+        // Parent should have package.json
+        const parentPath = path.replace(/\/node_modules$/, '').replace(/\\node_modules$/, '');
+        const hasPackageJson = await fileExists(join(parentPath, 'package.json'));
+        return hasSubdirs || hasPackageJson;
+    } catch  {
+        return false;
+    }
+}
+/**
+ * Generate a preview report of what would be deleted.
+ * 
+ * Used for dry run mode and confirmation prompts.
+ * 
+ * @param nodeModules - All node_modules items
+ * @returns Formatted report string
+ */ function generateDeletionPreview(nodeModules) {
+    const selected = nodeModules.filter((nm)=>nm.selected);
+    if (selected.length === 0) {
+        return 'No node_modules selected for deletion.';
+    }
+    const totalBytes = selected.reduce((sum, nm)=>sum + nm.sizeBytes, 0);
+    let report = `\n⚠️  You are about to delete ${selected.length} node_modules director${selected.length === 1 ? 'y' : 'ies'}:\n\n`;
+    for (const nm of selected){
+        const shortPath = nm.path.replace(process.cwd(), '.');
+        report += `   • ${shortPath} (${nm.sizeFormatted})\n`;
+    }
+    report += `\n   Total space to reclaim: ${formatBytes(totalBytes)}\n`;
+    return report;
+}
+/**
+ * Generate a JSON report of deletion results.
+ * 
+ * @param result - Deletion result
+ * @returns JSON string
+ */ function generateJSONReport(result) {
+    return JSON.stringify({
+        summary: {
+            totalAttempted: result.totalAttempted,
+            successful: result.successful,
+            failed: result.failed,
+            bytesFreed: result.bytesFreed,
+            formattedBytesFreed: result.formattedBytesFreed
+        },
+        details: result.details.map((d)=>({
+                path: d.nodeModules.path,
+                projectName: d.nodeModules.projectName,
+                sizeBytes: d.nodeModules.sizeBytes,
+                sizeFormatted: d.nodeModules.sizeFormatted,
+                success: d.success,
+                error: d.error,
+                durationMs: d.durationMs
+            }))
+    }, null, 2);
+}
+/**
+ * Select node_modules by size criteria.
+ * 
+ * Helper for "select all >500MB" functionality.
+ * 
+ * @param nodeModules - All node_modules
+ * @param minSizeBytes - Minimum size in bytes
+ * @returns Updated array with selections
+ */ function selectBySize(nodeModules, minSizeBytes) {
+    return nodeModules.map((nm)=>nm.sizeBytes >= minSizeBytes ? {
+            ...nm,
+            selected: true
+        } : nm);
+}
+/**
+ * Select node_modules by age criteria.
+ * 
+ * Helper for "select all older than X days" functionality.
+ * 
+ * @param nodeModules - All node_modules
+ * @param minAgeDays - Minimum age in days
+ * @returns Updated array with selections
+ */ function selectByAge(nodeModules, minAgeDays) {
+    const now = new Date();
+    return nodeModules.map((nm)=>{
+        const ageDays = Math.floor((now.getTime() - nm.lastModified.getTime()) / (1000 * 60 * 60 * 24));
+        return ageDays >= minAgeDays ? {
+            ...nm,
+            selected: true
+        } : nm;
+    });
+}
+/**
+ * Select all node_modules.
+ * 
+ * @param nodeModules - All node_modules
+ * @param selected - Whether to select (true) or deselect (false)
+ * @returns Updated array
+ */ function selectAll(nodeModules, selected) {
+    return nodeModules.map((nm)=>({
+            ...nm,
+            selected
+        }));
+}
+/**
+ * Invert selection.
+ * 
+ * @param nodeModules - All node_modules
+ * @returns Updated array with inverted selections
+ */ function invertSelection(nodeModules) {
+    return nodeModules.map((nm)=>({
+            ...nm,
+            selected: !nm.selected
+        }));
+}
+
+/**
+ * oh-my-node-modules - Public API
+ * 
+ * This module exports the public API for programmatic use.
+ * Most users will use the CLI, but the API is available for
+ * integration with other tools.
+ * 
+ * @example
+ * ```typescript
+ * import { scanForNodeModules, deleteSelectedNodeModules } from 'oh-my-node-modules';
+ * 
+ * const result = await scanForNodeModules({
+ *   rootPath: '/path/to/projects',
+ *   excludePatterns: [],
+ *   followSymlinks: false,
+ * });
+ * 
+ * // ... process results ...
+ * ```
+ */ // Core types
+// Core functions
+// Version
+const VERSION = '1.0.0';
+
+export { AGE_THRESHOLDS, DEFAULT_COLORS, SIZE_THRESHOLDS, VERSION, analyzeNodeModules, calculateStatistics, deleteSelectedNodeModules, filterNodeModules, formatBytes, formatRelativeTime, generateDeletionPreview, generateJSONReport, getAgeCategory, getSizeCategory, invertSelection, isNodeModulesInUse, loadFavorites, loadIgnorePatterns, parseSize, quickScan, scanForNodeModules, selectAll, selectByAge, selectByPredicate, selectBySize, sortNodeModules, toggleSelection };