@xelth/eck-snapshot 1.5.1 → 2.2.0

package/README.md

@@ -1,15 +1,80 @@
+# eck-snapshot
 
-# eckSnapshot
+[![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 a single-file text snapshot 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) like GPT or Claude.
+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).
 
-## Features
+## Why eck-snapshot?
 
--   **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.
--   **Directory Tree**: Generates a clean, readable tree of the repository structure at the top of the snapshot.
--   **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.
+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.
+  * **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
+
+Here's an example of `eck-snapshot` in action:
+
+```
+🚀 Starting snapshot for repository: /path/to/your/project
+✅ .gitignore patterns loaded
+📊 Found 152 total files in the repository
+🌳 Generating directory tree...
+📝 Processing files...
+Progress |██████████████████████████████| 100% | 152/152 files
+
+📊 Snapshot Summary
+==================================================
+🎉 Snapshot created successfully!
+📄 File saved to: /path/to/your/project/snapshots/project_snapshot_...txt
+📈 Included text files: 130 of 152
+⏭️  Skipped files: 22
+...
+==================================================
+```
+
+The beginning of the generated file will look like this:
+
+```text
+Directory Structure:
+
+├── .github/
+│   └── workflows/
+│       └── publish.yml
+├── src/
+│   ├── utils/
+│   │   └── formatters.js
+│   └── index.js
+├── .gitignore
+├── package.json
+└── README.md
+
+
+--- File: /src/index.js ---
+
+#!/usr/bin/env node
+import { Command } from 'commander';
+// ... rest of the file content
+
+--- File: /package.json ---
+
+{
+  "name": "eck-snapshot",
+  "version": "2.1.0",
+  // ... rest of the file content
+```
 
 ## Installation
 
@@ -17,31 +82,55 @@ To install the tool globally, run the following command:
 
 ```bash
 npm install -g @xelth/eck-snapshot
-````
-
+```
 
 ## Usage
 
-Once installed, you can run the tool from any directory in your terminal. While the project is named `eckSnapshot`, the command-line tool is invoked as **`eck-snapshot`** to follow standard CLI conventions.
+Once installed, you can run the tool from any directory in your terminal.
 
-**Generate a snapshot of the current directory:**
+### Creating a Snapshot
 
 ```bash
+# Create a snapshot of the current directory
 eck-snapshot
+
+# Specify a path to another repository
+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
 ```
 
-**Specify a path to another repository:**
+### Restoring from a Snapshot
 
 ```bash
-eck-snapshot /path/to/your/other/project
-```
+# Basic restore to current directory
+eck-snapshot restore ./snapshots/project_snapshot_...txt
+
+# 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/*"
 
-**Common Options:**
+# Restore with custom concurrency and verbose output
+eck-snapshot restore snapshot.txt --concurrency 20 --verbose
 
-  - `-o, --output <dir>`: Specify a different output directory for the snapshot file.
-  - `-v, --verbose`: Show detailed processing information, including skipped files.
-  - `--no-tree`: Exclude the directory tree from the snapshot.
-  - `--config <path>`: Use a configuration file from a specific path.
+# Restore compressed snapshots
+eck-snapshot restore project_snapshot.txt.gz ./restored
+```
 
 ## Configuration
 
@@ -67,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.
+This project is licensed under the MIT License.

package/index.js

@@ -11,9 +11,12 @@ import { SingleBar, Presets } from 'cli-progress';
 import pLimit from 'p-limit';
 import zlib from 'zlib';
 import { promisify } from 'util';
+// NEW: Import inquirer for user prompts
+import inquirer from 'inquirer';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const gzip = promisify(zlib.gzip);
+const gunzip = promisify(zlib.gunzip);
 
 const DEFAULT_CONFIG = {
   filesToIgnore: ['package-lock.json', '*.log', 'yarn.lock'],
@@ -25,6 +28,9 @@ const DEFAULT_CONFIG = {
   concurrency: 10
 };
 
+// ... (остальные существующие функции: parseSize, formatSize, matchesPattern, loadConfig, и т.д. остаются без изменений)
+// --- НАЧАЛО СУЩЕСТВУЮЩИХ ФУНКЦИЙ ---
+
 function parseSize(sizeStr) {
   const units = { B: 1, KB: 1024, MB: 1024 ** 2, GB: 1024 ** 3 };
   const match = sizeStr.match(/^(\d+(?:\.\d+)?)\s*(B|KB|MB|GB)?$/i);
@@ -44,19 +50,9 @@ function formatSize(bytes) {
   return `${size.toFixed(1)} ${units[unitIndex]}`;
 }
 
-/**
- * Correctly matches a file path against glob-like patterns.
- * @param {string} filePath - The path of the file to check.
- * @param {string[]} patterns - An array of patterns to match against.
- * @returns {boolean} - True if the file path matches any of the patterns.
- */
 function matchesPattern(filePath, patterns) {
     const fileName = path.basename(filePath);
     return patterns.some(pattern => {
-        // This is a robust way to convert simple globs to regex
-        // 1. Escape all special regex characters.
-        // 2. Convert the glob star '*' into the regex '.*'.
-        // 3. Anchor the pattern to match the whole string.
         const regexPattern = '^' + pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*') + '$';
         try {
             const regex = new RegExp(regexPattern);
@@ -253,8 +249,13 @@ async function processFile(filePath, config, gitignore, stats) {
     return { skipped: true, reason: error.message };
   }
 }
+// --- КОНЕЦ СУЩЕСТВУЮЩИХ ФУНКЦИЙ ---
+
+
+// --- ОСНОВНЫЕ ФУНКЦИИ ДЛЯ КОМАНД ---
 
 async function createRepoSnapshot(repoPath, options) {
+  // ... (эта функция остается без изменений)
   const absoluteRepoPath = path.resolve(repoPath);
   const absoluteOutputPath = path.resolve(options.output);
   const originalCwd = process.cwd();
@@ -508,24 +509,268 @@ async function createRepoSnapshot(repoPath, options) {
   }
 }
 
-// CLI setup
+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}`);
+
+  try {
+    let rawContent;
+    if (snapshotFile.endsWith('.gz')) {
+      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');
+    }
+
+    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');
+      }
+    } catch (e) {
+      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');
+      return;
+    }
+
+    // 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;
+    }
+
+    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. Continue?`,
+        default: false
+      }]);
+
+      if (!confirm) {
+        console.log('🚫 Restore operation cancelled by user');
+        return;
+      }
+    }
+
+    await fs.mkdir(absoluteTargetDir, { recursive: 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);
+
+    if (progressBar) progressBar.start(filesToRestore.length, 0);
+
+    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);
+
+          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 };
+        }
+      })
+    );
+
+    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);
+    }
+    process.exit(1);
+  }
+}
+
+function parseSnapshotContent(content) {
+  const files = [];
+  const fileRegex = /--- File: \/(.+) ---/g;
+  const sections = content.split(fileRegex);
+  
+  for (let i = 1; i < sections.length; i += 2) {
+    const filePath = sections[i].trim();
+    let fileContent = sections[i + 1] || '';
+
+    if (fileContent.startsWith('\n\n')) {
+      fileContent = fileContent.substring(2);
+    }
+    if (fileContent.endsWith('\n\n')) {
+      fileContent = fileContent.substring(0, fileContent.length - 2);
+    }
+    
+    files.push({ path: filePath, content: fileContent });
+  }
+
+  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();
 
 program
   .name('eck-snapshot')
-  .description('A CLI tool to create a single text snapshot of a local Git repository.')
-  .version('2.0.0')
+  .description('A CLI tool to create and restore single-file text snapshots of a Git repository.')
+  .version('2.1.0');
+
+// Snapshot command (existing)
+program
+  .command('snapshot', { isDefault: true })
+  .description('Create a snapshot of a Git repository (default command).')
   .argument('[repoPath]', 'Path to the git repository to snapshot.', process.cwd())
-  .option('-o, --output <dir>', 'Output directory for the snapshot file.', path.join(__dirname, 'snapshots'))
+  .option('-o, --output <dir>', 'Output directory for the snapshot file.', path.join(process.cwd(), 'snapshots'))
   .option('--no-tree', 'Do not include the directory tree in the snapshot.')
   .option('-v, --verbose', 'Show detailed processing information, including skipped files.')
   .option('--max-file-size <size>', 'Maximum file size to include (e.g., 10MB)', '10MB')
   .option('--max-total-size <size>', 'Maximum total snapshot size (e.g., 100MB)', '100MB')
-  .option('--max-depth <number>', 'Maximum directory depth for tree generation', parseInt, 10)
+  .option('--max-depth <number>', 'Maximum directory depth for tree generation', (val) => parseInt(val), 10)
   .option('--config <path>', 'Path to configuration file')
   .option('--compress', 'Compress output file with gzip')
   .option('--include-hidden', 'Include hidden files (starting with .)')
   .option('--format <type>', 'Output format: txt, json', 'txt')
-  .action(createRepoSnapshot);
+  .action((repoPath, options) => createRepoSnapshot(repoPath, options));
+
+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')
+  .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,7 +1,7 @@
 {
   "name": "@xelth/eck-snapshot",
-  "version": "1.5.1",
-  "description": "A CLI tool to create a single-file text snapshot of a Git repository, ideal for providing context to LLMs.",
+  "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",
   "bin": {
@@ -16,14 +16,6 @@
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },
-  "keywords": [
-    "snapshot",
-    "repository",
-    "cli",
-    "git",
-    "llm",
-    "context"
-  ],
   "author": "xelth-com",
   "license": "MIT",
   "repository": {
@@ -36,6 +28,7 @@
     "is-binary-path": "^2.1.0",
     "ignore": "^5.3.1",
     "cli-progress": "^3.12.0",
-    "p-limit": "^5.0.0"
+    "p-limit": "^5.0.0",
+    "inquirer": "^9.2.20"
   }
-}
+}