@xelth/eck-snapshot 2.1.0 → 2.2.0

package/README.md

@@ -1,23 +1,27 @@
 # eck-snapshot
 
-[](https://www.google.com/search?q=https://www.npmjs.com/package/%40xelth/eck-snapshot)
-[](https://www.google.com/search?q=https://github.com/xelth-com/eckSnapshot/blob/main/LICENSE)
+[![npm version](https://badge.fury.io/js/%40xelth%2Feck-snapshot.svg)](https://www.npmjs.com/package/@xelth/eck-snapshot)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/xelth-com/eckSnapshot/blob/main/LICENSE)
 
 A CLI tool to create and restore single-file text snapshots of a Git repository. It generates a single `.txt` file containing the directory structure and the content of all text-based files, which is ideal for providing context to Large Language Models (LLMs).
 
 ## Why eck-snapshot?
 
-When working with LLMs like Claude or GPT-4, you often need to provide the full context of your project. Manually copying and pasting dozens of files is tedious and inefficient. This tool automates the process by creating a single, comprehensive file that you can easily feed into an LLM. And with the new `restore` feature, you can instantly recreate a project structure from a snapshot.
+When working with Large Language Models (LLMs), providing the full context of your project is crucial for getting accurate results. Manually copying and pasting dozens of files is tedious and inefficient.
+
+eck-snapshot automates this by generating a single, comprehensive text file of your entire repository. This is particularly effective with models that support large context windows (like Google's Gemini), as it often allows the entire project snapshot to be analyzed at once—a task that can be challenging with smaller context windows.
 
 ## Key Features
 
   * **Git Integration**: Automatically includes all files tracked by Git.
   * **Intelligent Ignoring**: Respects `.gitignore` rules and has its own configurable ignore lists for files, extensions, and directories.
-  * **Restore from Snapshot**: The new `restore` command allows you to recreate files and folders from a snapshot file.
+  * **Advanced Restore**: Powerful `restore` command with filtering, dry-run mode, and parallel processing.
   * **Directory Tree**: Generates a clean, readable tree of the repository structure at the top of the snapshot.
+  * **Multiple Formats**: Supports both plain text and JSON output formats.
   * **Configurable**: Customize behavior using an `.ecksnapshot.config.js` file.
   * **Progress and Stats**: Provides a progress bar and a detailed summary of what was included and skipped.
   * **Compression**: Supports gzipped (`.gz`) snapshots for smaller file sizes.
+  * **Security**: Built-in path validation to prevent directory traversal attacks during restore.
 
 ## Demo
 
@@ -95,16 +99,37 @@ eck-snapshot /path/to/your/other/project
 
 # Save the snapshot to a different directory and exclude the tree view
 eck-snapshot --output ./backups --no-tree
+
+# Create a compressed JSON snapshot
+eck-snapshot --format json --compress
+
+# Include hidden files and set custom size limits
+eck-snapshot --include-hidden --max-file-size 5MB --max-total-size 50MB
 ```
 
 ### Restoring from a Snapshot
 
 ```bash
-# Restore files from a snapshot into the current directory
+# Basic restore to current directory
 eck-snapshot restore ./snapshots/project_snapshot_...txt
 
-# Restore into a new directory without a confirmation prompt
+# Restore to a specific directory without confirmation
 eck-snapshot restore snapshot.txt ./restored-project --force
+
+# Preview what would be restored (dry run)
+eck-snapshot restore snapshot.txt --dry-run
+
+# Restore only specific files using patterns
+eck-snapshot restore snapshot.txt --include "*.js" "*.json"
+
+# Restore everything except certain files
+eck-snapshot restore snapshot.txt --exclude "*.log" "node_modules/*"
+
+# Restore with custom concurrency and verbose output
+eck-snapshot restore snapshot.txt --concurrency 20 --verbose
+
+# Restore compressed snapshots
+eck-snapshot restore project_snapshot.txt.gz ./restored
 ```
 
 ## Configuration
@@ -131,11 +156,71 @@ export default {
     '.git/',
     'dist/',
   ],
-  // Maximum size for individual files
+  // Size and performance settings
   maxFileSize: '10MB',
+  maxTotalSize: '100MB',
+  maxDepth: 10,
+  concurrency: 10
 };
 ```
 
+## Advanced Features
+
+### Restore Command Options
+
+The restore command offers powerful filtering and control options:
+
+- **`--dry-run`**: Preview what files would be restored without actually writing them
+- **`--include <patterns>`**: Only restore files matching the specified patterns (supports wildcards)
+- **`--exclude <patterns>`**: Skip files matching the specified patterns (supports wildcards)
+- **`--concurrency <number>`**: Control how many files are processed simultaneously (default: 10)
+- **`--force`**: Skip confirmation prompts and overwrite existing files
+- **`--verbose`**: Show detailed information about each file being processed
+
+### Supported Formats
+
+- **Plain Text** (`.txt`): Human-readable format, ideal for LLM context
+- **JSON** (`.json`): Structured format with metadata and statistics
+- **Compressed** (`.gz`): Any format can be gzipped for smaller file sizes
+
+### Security Features
+
+- **Path Validation**: Prevents directory traversal attacks during restore operations
+- **File Sanitization**: Validates file paths and names for security
+- **Confirmation Prompts**: Requires user confirmation before overwriting files (unless `--force` is used)
+
+## Command Reference
+
+### Snapshot Command
+```bash
+eck-snapshot [options] [repoPath]
+```
+
+**Options:**
+- `-o, --output <dir>`: Output directory for snapshots
+- `--no-tree`: Exclude directory tree from output
+- `-v, --verbose`: Show detailed processing information
+- `--max-file-size <size>`: Maximum individual file size (e.g., 10MB)
+- `--max-total-size <size>`: Maximum total snapshot size (e.g., 100MB)
+- `--max-depth <number>`: Maximum directory depth for tree generation
+- `--config <path>`: Path to custom configuration file
+- `--compress`: Create gzipped output
+- `--include-hidden`: Include hidden files (starting with .)
+- `--format <type>`: Output format: txt or json
+
+### Restore Command
+```bash
+eck-snapshot restore [options] <snapshot_file> [target_directory]
+```
+
+**Options:**
+- `-f, --force`: Force overwrite without confirmation
+- `-v, --verbose`: Show detailed processing information
+- `--dry-run`: Preview without actually writing files
+- `--include <patterns>`: Include only matching files
+- `--exclude <patterns>`: Exclude matching files
+- `--concurrency <number>`: Number of concurrent operations
+
 ## License
 
 This project is licensed under the MIT License.

package/index.js

@@ -509,115 +509,175 @@ async function createRepoSnapshot(repoPath, options) {
   }
 }
 
-// NEW: Restore Snapshot Function
 async function restoreSnapshot(snapshotFile, targetDir, options) {
   const absoluteSnapshotPath = path.resolve(snapshotFile);
   const absoluteTargetDir = path.resolve(targetDir);
 
-  console.log(`⚙️  Starting restore from snapshot: ${absoluteSnapshotPath}`);
-  console.log(`🗂️  Target directory: ${absoluteTargetDir}`);
+  console.log(`🔄 Starting restore from snapshot: ${absoluteSnapshotPath}`);
+  console.log(`📁 Target directory: ${absoluteTargetDir}`);
 
   try {
     let rawContent;
-    // Check if the file is compressed
     if (snapshotFile.endsWith('.gz')) {
-        const compressedBuffer = await fs.readFile(absoluteSnapshotPath);
-        rawContent = (await gunzip(compressedBuffer)).toString('utf-8');
-        console.log('✅ Decompressed gzipped snapshot.');
+      const compressedBuffer = await fs.readFile(absoluteSnapshotPath);
+      rawContent = (await gunzip(compressedBuffer)).toString('utf-8');
+      console.log('✅ Decompressed gzipped snapshot');
     } else {
-        rawContent = await fs.readFile(absoluteSnapshotPath, 'utf-8');
+      rawContent = await fs.readFile(absoluteSnapshotPath, 'utf-8');
     }
 
-    // Check if the content is JSON
     let filesToRestore;
     try {
-        const jsonData = JSON.parse(rawContent);
-        if (jsonData.content) {
-            console.log('📄 Detected JSON format, extracting content.');
-            filesToRestore = parseSnapshotContent(jsonData.content);
-        } else {
-            throw new Error('JSON format detected, but no "content" key found.');
-        }
+      const jsonData = JSON.parse(rawContent);
+      if (jsonData.content) {
+        console.log('📄 Detected JSON format, extracting content');
+        filesToRestore = parseSnapshotContent(jsonData.content);
+      } else {
+        throw new Error('JSON format detected, but no "content" key found');
+      }
     } catch (e) {
-        // Not a JSON file, or not the format we expect. Treat as plain text.
-        console.log('📄 Treating snapshot as plain text format.');
-        filesToRestore = parseSnapshotContent(rawContent);
+      console.log('📄 Treating snapshot as plain text format');
+      filesToRestore = parseSnapshotContent(rawContent);
     }
     
     if (filesToRestore.length === 0) {
-      console.warn('⚠️  No files found to restore in the snapshot.');
+      console.warn('⚠️  No files found to restore in the snapshot');
       return;
     }
 
-    console.log(`📊 Found ${filesToRestore.length} files in the snapshot.`);
+    // Apply filters if specified
+    if (options.include || options.exclude) {
+      filesToRestore = filterFilesToRestore(filesToRestore, options);
+      if (filesToRestore.length === 0) {
+        console.warn('⚠️  No files remaining after applying filters');
+        return;
+      }
+    }
+
+    // Validate file paths for security
+    const invalidFiles = validateFilePaths(filesToRestore, absoluteTargetDir);
+    if (invalidFiles.length > 0) {
+      console.error('❌ Invalid file paths detected (potential directory traversal):');
+      invalidFiles.forEach(file => console.error(`  ${file}`));
+      process.exit(1);
+    }
+
+    console.log(`📊 Found ${filesToRestore.length} files to restore`);
+
+    if (options.dryRun) {
+      console.log('\n🔍 Dry run mode - files that would be restored:');
+      filesToRestore.forEach(file => {
+        const fullPath = path.join(absoluteTargetDir, file.path);
+        console.log(`  ${fullPath}`);
+      });
+      return;
+    }
 
-    // Confirmation prompt
     if (!options.force) {
-      const { confirm } = await inquirer.prompt([
-        {
-          type: 'confirm',
-          name: 'confirm',
-          message: `You are about to write ${filesToRestore.length} files to ${absoluteTargetDir}. Existing files will be overwritten. Are you sure you want to continue?`,
-          default: false,
-        },
-      ]);
+      const { confirm } = await inquirer.prompt([{
+        type: 'confirm',
+        name: 'confirm',
+        message: `You are about to write ${filesToRestore.length} files to ${absoluteTargetDir}. Existing files will be overwritten. Continue?`,
+        default: false
+      }]);
 
       if (!confirm) {
-        console.log('🚫 Restore operation cancelled by user.');
+        console.log('🚫 Restore operation cancelled by user');
         return;
       }
     }
 
-    // Create target directory if it doesn't exist
     await fs.mkdir(absoluteTargetDir, { recursive: true });
 
-    // Restore files
-    const progressBar = new SingleBar({
-        format: 'Restoring |{bar}| {percentage}% | {value}/{total} files',
-        barCompleteChar: '\u2588',
-        barIncompleteChar: '\u2591',
-        hideCursor: true
+    const stats = {
+      totalFiles: filesToRestore.length,
+      restoredFiles: 0,
+      failedFiles: 0,
+      errors: []
+    };
+
+    const progressBar = options.verbose ? null : new SingleBar({
+      format: 'Restoring |{bar}| {percentage}% | {value}/{total} files',
+      barCompleteChar: '\u2588',
+      barIncompleteChar: '\u2591',
+      hideCursor: true
     }, Presets.shades_classic);
 
-    progressBar.start(filesToRestore.length, 0);
+    if (progressBar) progressBar.start(filesToRestore.length, 0);
 
-    for (const file of filesToRestore) {
-      const fullPath = path.join(absoluteTargetDir, file.path);
-      const dir = path.dirname(fullPath);
+    const limit = pLimit(options.concurrency || 10);
+    const filePromises = filesToRestore.map((file, index) => 
+      limit(async () => {
+        try {
+          const fullPath = path.join(absoluteTargetDir, file.path);
+          const dir = path.dirname(fullPath);
 
-      // Create directory for the file
-      await fs.mkdir(dir, { recursive: true });
-      // Write the file content
-      await fs.writeFile(fullPath, file.content);
-      progressBar.increment();
-    }
+          await fs.mkdir(dir, { recursive: true });
+          await fs.writeFile(fullPath, file.content, 'utf-8');
+          
+          stats.restoredFiles++;
+          
+          if (progressBar) {
+            progressBar.update(index + 1);
+          } else if (options.verbose) {
+            console.log(`✅ Restored: ${file.path}`);
+          }
+          
+          return { success: true, file: file.path };
+        } catch (error) {
+          stats.failedFiles++;
+          stats.errors.push({ file: file.path, error: error.message });
+          
+          if (options.verbose) {
+            console.log(`❌ Failed to restore: ${file.path} - ${error.message}`);
+          }
+          
+          return { success: false, file: file.path, error: error.message };
+        }
+      })
+    );
 
-    progressBar.stop();
-    console.log(`\n🎉 Restore complete! ${filesToRestore.length} files have been written to ${absoluteTargetDir}.`);
+    await Promise.allSettled(filePromises);
+    if (progressBar) progressBar.stop();
+
+    console.log('\n📊 Restore Summary');
+    console.log('='.repeat(50));
+    console.log(`🎉 Restore completed!`);
+    console.log(`✅ Successfully restored: ${stats.restoredFiles} files`);
+    if (stats.failedFiles > 0) {
+      console.log(`❌ Failed to restore: ${stats.failedFiles} files`);
+      if (stats.errors.length > 0) {
+        console.log('\n⚠️  Errors encountered:');
+        stats.errors.slice(0, 5).forEach(({ file, error }) => {
+          console.log(`  ${file}: ${error}`);
+        });
+        if (stats.errors.length > 5) {
+          console.log(`  ... and ${stats.errors.length - 5} more errors`);
+        }
+      }
+    }
+    console.log(`📁 Target directory: ${absoluteTargetDir}`);
+    console.log('='.repeat(50));
 
   } catch (error) {
     console.error('\n❌ An error occurred during restore:');
     console.error(error.message);
     if (options.verbose) {
-        console.error(error.stack);
+      console.error(error.stack);
     }
     process.exit(1);
   }
 }
 
-// NEW: Snapshot Parser Function
 function parseSnapshotContent(content) {
   const files = [];
   const fileRegex = /--- File: \/(.+) ---/g;
   const sections = content.split(fileRegex);
   
-  // sections will be [ '...everything before first match...', 'path1', 'content1', 'path2', 'content2', ...]
-  // We start at index 1 because index 0 is anything before the first delimiter (like the directory tree)
   for (let i = 1; i < sections.length; i += 2) {
     const filePath = sections[i].trim();
     let fileContent = sections[i + 1] || '';
 
-    // Remove the trailing newline that the split might leave
     if (fileContent.startsWith('\n\n')) {
       fileContent = fileContent.substring(2);
     }
@@ -631,6 +691,49 @@ function parseSnapshotContent(content) {
   return files;
 }
 
+function filterFilesToRestore(files, options) {
+  let filtered = files;
+  
+  if (options.include) {
+    const includePatterns = Array.isArray(options.include) ? options.include : [options.include];
+    filtered = filtered.filter(file => 
+      includePatterns.some(pattern => {
+        const regex = new RegExp(pattern.replace(/\*/g, '.*'));
+        return regex.test(file.path);
+      })
+    );
+  }
+  
+  if (options.exclude) {
+    const excludePatterns = Array.isArray(options.exclude) ? options.exclude : [options.exclude];
+    filtered = filtered.filter(file => 
+      !excludePatterns.some(pattern => {
+        const regex = new RegExp(pattern.replace(/\*/g, '.*'));
+        return regex.test(file.path);
+      })
+    );
+  }
+  
+  return filtered;
+}
+
+function validateFilePaths(files, targetDir) {
+  const invalidFiles = [];
+  
+  for (const file of files) {
+    const normalizedPath = path.normalize(file.path);
+    
+    if (normalizedPath.includes('..') || 
+        normalizedPath.startsWith('/') || 
+        normalizedPath.includes('\0') ||
+        /[<>:"|?*]/.test(normalizedPath)) {
+      invalidFiles.push(file.path);
+    }
+  }
+  
+  return invalidFiles;
+}
+
 
 // --- CLI SETUP ---
 const program = new Command();
@@ -657,14 +760,17 @@ program
   .option('--format <type>', 'Output format: txt, json', 'txt')
   .action((repoPath, options) => createRepoSnapshot(repoPath, options));
 
-// NEW: Restore command (Corrected)
 program
-  .command('restore') // Убираем аргументы отсюда
-  .description('Restore files and directories from a snapshot file.')
-  .argument('<snapshot_file>', 'Path to the snapshot file (.txt, .json, or .gz).') // Аргументы определяем здесь
-  .argument('[target_directory]', 'Directory to restore the files into.', process.cwd())
-  .option('-f, --force', 'Force overwrite of existing files without confirmation.')
-  .option('-v, --verbose', 'Show detailed processing information.')
+  .command('restore')
+  .description('Restore files and directories from a snapshot file')
+  .argument('<snapshot_file>', 'Path to the snapshot file (.txt, .json, or .gz)')
+  .argument('[target_directory]', 'Directory to restore the files into', process.cwd())
+  .option('-f, --force', 'Force overwrite of existing files without confirmation')
+  .option('-v, --verbose', 'Show detailed processing information')
+  .option('--dry-run', 'Show what would be restored without actually writing files')
+  .option('--include <patterns...>', 'Include only files matching these patterns (supports wildcards)')
+  .option('--exclude <patterns...>', 'Exclude files matching these patterns (supports wildcards)')
+  .option('--concurrency <number>', 'Number of concurrent file operations', (val) => parseInt(val), 10)
   .action((snapshotFile, targetDir, options) => restoreSnapshot(snapshotFile, targetDir, options));
 
 program.parse(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xelth/eck-snapshot",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "A CLI tool to create and restore single-file text snapshots of a Git repository.",
   "main": "index.js",
   "type": "module",
@@ -31,4 +31,4 @@
     "p-limit": "^5.0.0",
     "inquirer": "^9.2.20"
   }
-}
+}